Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
5 changes: 5 additions & 0 deletions .changeset/clear-authoring-handoff.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@fluentui-react-native/skills": patch
---

Follow the owning component contract's token companion and carry requirement-level source and native qualification evidence through the authoring workflow.
6 changes: 6 additions & 0 deletions .changeset/host-platform-component-tokens.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@fluentui-react-native/design': minor
'@fluentui-react-native/components': patch
---

Support host-specific component token bindings and theme overrides with the reserved final `when.platform.<host>` selector. MenuButton now declares its macOS label alignment in its token companion.
5 changes: 5 additions & 0 deletions .changeset/quiet-popup-alignment.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@fluentui-react-native/components": patch
---

Add native Storybook coverage for MenuButton and Dropdown popup alignment on Windows Fabric and Win32.
8 changes: 8 additions & 0 deletions .changeset/strong-toggles-align.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
'@fluentui-react-native/components': minor
'@fluentui-react-native/design': patch
---

Align the agentic component contracts and token bindings with Flex 1.7. Button is action-only: migrate selection to the new Subtle ToggleButton, and use independent leading and trailing icon slots instead of `icon` and `iconPosition`. Use `circular` explicitly in place of `circle`; the square shape was removed.

MenuButton uses `leadingIcon`. Dropdown uses `selectionMode` instead of `multiselect`; MenuItem and ListboxItem use a single selection mode instead of independent indicator flags. Badge defaults to Informative, removes Brand, and adds Filled Counter and Dot layouts. Avatar content modes are mutually exclusive. Tag supports an explicit caller-owned dismiss request, and busy status belongs to the host of a decorative Spinner. Visual defaults and component token overrides now follow the v2 JSON bindings.
5 changes: 5 additions & 0 deletions .changeset/tidy-control-alignment.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@fluentui-react-native/components': patch
---

Balance icon-side padding in Button and MenuButton, align MenuButton and Dropdown labels with their chevrons, and restore rounded Input outlines and the Input Icons story's width constraint.
5 changes: 5 additions & 0 deletions .changeset/toggle-button-contract-scaffold.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@fluentui-react-native/components': patch
---

Add the pre-implementation ToggleButton contract, selected-state tokens, and typed scaffold. ToggleButton is not yet exported; Button's API is unchanged.
5 changes: 5 additions & 0 deletions .changeset/tooltip-native-contract.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@fluentui-react-native/components': minor
---

Expose a native `tooltip?: string` prop on supported view-backed components. The compatibility wrapper is implemented for desktop qualification but is not yet exported.
6 changes: 3 additions & 3 deletions agency.toml
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
[profiles.flex-authoring]

[[profiles.flex-authoring.plugins.default]]
plugin = "market:flex-components@curated#206c4996205b027f4d806ac4ac7366f1f0ab0d5a"
plugin = "market:flex-components@curated#9f1df394126dd9ad2339b786ab7dcc090131533c"
cache_policy = "no-refresh"

[[profiles.flex-authoring.plugins.default]]
plugin = "market:flex-system@curated#206c4996205b027f4d806ac4ac7366f1f0ab0d5a"
plugin = "market:flex-system@curated#9f1df394126dd9ad2339b786ab7dcc090131533c"
cache_policy = "no-refresh"

[[profiles.flex-authoring.plugins.default]]
plugin = "market:flex-tokens@curated#206c4996205b027f4d806ac4ac7366f1f0ab0d5a"
plugin = "market:flex-tokens@curated#9f1df394126dd9ad2339b786ab7dcc090131533c"
cache_policy = "no-refresh"
8 changes: 6 additions & 2 deletions packages/agentic/components/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ and accessibility behavior, and colocated tests and stories.
| `@fluentui-react-native/components/primitives` | Unstyled building blocks: `CheckboxIndicator`, `CompoundItemLayout`, `FocusVisual`, `Icon`, `LayoutStableText` |

Higher-order components: Accordion, Avatar, Badge, Button, Card, Checkbox, Divider, Dropdown, Input, ListItem,
ListboxItem, Menu, MenuButton, MenuItem, Popover, ProgressBar, Radio, Skeleton, Spinner, Switch, Tab, TabList, Tag, and
Text.
ListboxItem, Menu, MenuButton, MenuItem, Popover, ProgressBar, Radio, Skeleton, Spinner, Switch, Tab, TabList, Tag,
Text, and ToggleButton.

## Quick start

Expand All @@ -31,6 +31,10 @@ export const App = () => (

Each component's `src/components/<name>/SPEC.md` describes its supported props, behavior, and platform differences.

For native desktop tooltip text, pass `tooltip` directly to a supported view-backed component, for example
`<Button content="Save" tooltip="Save a local copy" />`. This forwards text to the host, not an accessible name or
description. The [Tooltip contract](src/components/tooltip/SPEC.md) distinguishes the direct prop from the compatibility wrapper.

## Documentation

| Topic | Covers |
Expand Down
5 changes: 3 additions & 2 deletions packages/agentic/components/references/contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -260,8 +260,9 @@ It validates schema version 2, local references and artifact digests,
requirement evidence, lifecycle, and review state. It does not claim that a
remote source is current.

With `GH_TOKEN` or `GITHUB_TOKEN` authorized for the curated Marketplace and X3
source, generate the Flex-only digest report:
Use `GH_TOKEN` or `GITHUB_TOKEN` authorized for the curated Marketplace and
`GH_ENTERPRISE_TOKEN` or `GITHUB_ENTERPRISE_TOKEN` authorized for the X3
organization on `msft.ghe.com` to generate the Flex-only digest report:

```sh
yarn workspace @fluentui-react-native/components report:spec-source-drift --write
Expand Down
24 changes: 23 additions & 1 deletion packages/agentic/components/references/remaining-work.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,22 @@ Open work for the agentic component catalog. Completed work is removed rather th
is documented in the owning reference, component contract, or the repository focus references (`focus.common`,
`focus.windows-win32`, and `focus.macos`).

## ToggleButton and the Button migration

The [ToggleButton contract](../src/components/toggle-button/SPEC.md) implements a separate Subtle control. Check
native Toggle delivery, checked state and high-contrast selection on each desktop endpoint before claiming parity.
The [consumer migration](../src/components/toggle-button/spec/usage.md) requires an explicit decision for
non-Subtle and square callers.

## Flex 1.7 endpoint gates

- Require a verifiable native popup relationship for Menu, MenuButton and Dropdown, not only an expanded property
or a hint. Qualify Dropdown's invalid-state projection and associated error text separately.
- Qualify Popover's natural boundary exit before changing its current Tab cycle. Qualify Dropdown and MenuButton
continuation per renderer; Office Win32 does not yet support forward continuation from these popups.
- Author and review PresenceBadge before enabling visible presence in Avatar. The identity marker and its activity ring
do not stand in for presence.

## Desktop focus qualification

- **Issues:** [#4274](https://github.com/microsoft/fluentui-react-native/issues/4274); popup-family restoration in
Expand Down Expand Up @@ -45,6 +61,13 @@ is documented in the owning reference, component contract, or the repository foc
disabled and removed targets neither activate nor keep phantom focus, collection focus matches committed selection,
popups restore focus by dismissal reason, and theme or high-contrast changes keep stable identities.

## Tooltip native routing

Before exporting the [Tooltip wrapper](../src/components/tooltip/SPEC.md) for
[#4249](https://github.com/microsoft/fluentui-react-native/issues/4249), qualify trigger help, keyboard dismissal
and persistence on macOS Paper/Fabric and Windows Fabric. Compare Office Win32's view prop with `RCTTooltip`
before deciding whether to extract its legacy binding. The wrapper is not yet exported.

## Components without a local contract

These components had staged specs that were removed under
Expand All @@ -67,7 +90,6 @@ row against the current package before drafting its contract.
| Scrollbar | [#4238](https://github.com/microsoft/fluentui-react-native/issues/4238) | Blocked | Scroll metrics, tokenized thumb control, and drag interaction need a native host | Define a scroll-source API and platform scrollbar bridge |
| Textarea | [#4245](https://github.com/microsoft/fluentui-react-native/issues/4245) | Blocked as authored | HTML textarea semantics and CSS resize behavior | Make the product/API choice described below |
| Toolbar | [#4248](https://github.com/microsoft/fluentui-react-native/issues/4248) | Partial; blocked | Roving focus needs focusable Button refs; Divider was absent | Reuse implemented Divider and define imperative focus for toolbar children |
| Tooltip | [#4249](https://github.com/microsoft/fluentui-react-native/issues/4249) | Blocked as authored | Anchor/overlay host and trigger-coupled accessibility | Establish overlay infrastructure or retarget the contract |

**Done when:** each component has a reviewed local contract and implementation, or its issue records a decision not to
provide it.
Expand Down
7 changes: 3 additions & 4 deletions packages/agentic/components/references/rendering.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,16 +33,15 @@ Capitalize local optional slot variables when that improves readability. Render
return <state.root>{content}</state.root>;
```

Keep slot order visible in JSX. Button renders its active icon before or after content according to `iconPosition`.
Keep slot order visible in JSX. Button renders the leading icon, content, and trailing icon in that order.
Avoid array construction or opaque helper loops when direct JSX makes the public ordering contract clearer.

## Resolve conditional structure from state

The render function may select among already-resolved slots and compose conditional layout:

- Button chooses `selectedIcon` when selected and falls back to `icon`.
- Toggle content uses the private container, hidden ghost, and visible label.
- Ordinary content renders without that wrapper.
- ToggleButton resolves each selected icon and falls back to that side's regular icon before rendering.
- ToggleButton uses a private width reservation and visible label; action-only Button renders the content directly.

Do not create missing slots in the render stage. If a structural element can exist, represent it in the state type and
construct it in the state hook.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,9 @@ Do not resolve token styles or render elements in this hook.

## Preserve raw presence before applying defaults

Derive presence-sensitive behavior from raw props. Button computes `hasContent`, `hasIcon`, and `hasSelectedIcon` before
constructing slots. It uses those values to derive `iconOnly`, while `selected !== undefined` determines whether toggle
semantics are enabled even when `selected` is false.

Apply context-sensitive defaults only after those facts are known. Button defaults shape to `circle` for icon-only use
and `rounded` otherwise.
Derive presence-sensitive behavior from raw props. Button derives `iconOnly` from the absence of content and presence
of a leading icon. Its default shape is `rounded` regardless of layout. ToggleButton treats `selected={false}` as
controlled and always exposes its checked state.

## Decide who owns a stateful axis

Expand Down Expand Up @@ -87,8 +84,8 @@ it could never deselect and nothing would clear its siblings.
### Watch axes that change component identity

When `selected !== undefined` switches a component between two shapes, that is an identity change rather than a value
change. Button uses it to become a toggle button, which adds the Semibold ghost label that reserves layout width, and
Card uses it to become selectable, which adds the interactive overlay.
change. Card uses it to become selectable, which adds the interactive overlay. ToggleButton always reserves the
semibold label width regardless of which state owner is in use.

Keep those axes stable for a given instance and do not expose them as a Storybook control, because flipping the control
between `undefined` and `false` visibly resizes or re-roles the component. Demonstrate the axis with focused stories
Expand Down
6 changes: 5 additions & 1 deletion packages/agentic/components/references/styles-and-tokens.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ value.

## Component token companions (v2)

Button and MenuButton import `spec/tokens.json` in their module-scoped `defineComponentTokens` calls. JSON is the only
Higher-order components import `spec/tokens.json` in their module-scoped `defineComponentTokens` calls. JSON is the only
runtime source of ordered axes. Use the component's state type for typed resolution and theme patches; don't redeclare
the axes in TypeScript. Reuse the named field validators from `@fluentui-react-native/design/styling`. Each slot contains
flat React Native style keys and reviewed prop settings:
Expand Down Expand Up @@ -67,6 +67,10 @@ property; the higher differing axis wins within the same layer. Provide a compon
exclusive presentation; Button's order is disabled, pressed, hovered, then rest. Independent booleans such as `selected`
remain separate. Do not mutate raw interaction state.

For a measured platform-specific visual adjustment, use a final `when.platform.<host>` selector; `platform` is
reserved and is not listed in `axes` or passed as component state. MenuButton uses this to adjust only its macOS
label. Keep cross-platform typography in ordinary bindings and renderer-specific behavior out of token selectors.

Retrieve the cached definition with `getComponentTokens` using the original `ThemeState`, then pass the component state
directly to `resolveTokenStates`. A slot's domain splits the resolved `style` from `props`. Non-style icon color and
dimensions are presentation settings, not a basis for replacing caller sources or introducing a default icon.
Expand Down
9 changes: 5 additions & 4 deletions packages/agentic/components/references/tests-and-stories.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,13 +113,14 @@ For a self-driving control such as Checkbox, Switch, or Accordion, do not put th
nothing and the story looks broken. Expose `default<State>` as the on-device control and use it in `args`, including for
variant-scan stories, so each instance starts in the demonstrated state and still responds to presses.

For externally driven selection such as Button, Tab, Radio, Card, or the item components, a fixed `selected` arg is
For externally driven selection such as Tab, Radio, Card, or the item components, a fixed `selected` arg is
correct: the component never changes it. Give the interactive demonstration in one story that owns the value with
`React.useState` and updates it from `onPress`.

Do not expose an axis that changes component identity as a control. Button's `selected` decides whether it is a toggle
button at all, and Card's decides whether it is selectable, so a control that flips between `undefined` and `false`
resizes or re-roles the component instead of demonstrating a value.
Do not expose an axis that changes component identity as a control. Card's `selected` determines whether it is
selectable, so a control that flips between `undefined` and `false` changes the component instead of demonstrating
a value. ToggleButton is self-driving; use `defaultSelected` for a variant scan or bind a controlled story to
`onSelectedChange`.

Each story module should provide:

Expand Down
14 changes: 9 additions & 5 deletions packages/agentic/components/references/types-and-slots.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,8 @@ Define public slots in `<component>.types.ts`:
- Document what causes an optional slot to render and whether shorthand children are accepted.
- Keep the slot surface small. A slot is public customization API, not merely an element in the render tree.

Button exposes `root`, `content`, `icon`, and `selectedIcon`. Its `contentContainer` and `contentHidden` slots support the
selected-label layout but remain in the private `ButtonStateSlots` type. Follow that split whenever measuring, overlay,
ghost, or structural slots are implementation details.
Button exposes `root`, `content`, `leadingIcon`, and `trailingIcon`. ToggleButton’s width reservation remains private.
Follow that split whenever measuring, overlay, or structural slots are implementation details.

## Model variants explicitly

Expand All @@ -35,7 +34,7 @@ export type ComponentSize = 'small' | 'medium' | 'large';

Collect state-bearing public props in `<Component>StateProps`. Optional public values become required in resolved state
after the state hook applies defaults. Preserve a meaningful distinction between omitted and false values when omission
enables behavior; Button uses `selected !== undefined` to distinguish an ordinary button from a toggle button.
enables behavior; ToggleButton uses the presence of `selected` to distinguish controlled from uncontrolled state.

## Expose native props deliberately

Expand All @@ -48,6 +47,11 @@ Do not blindly inherit every root prop when the component owns part of the nativ
Button uses `OwnedRootProps<PropsWithRefOf<typeof Pressable>>`. This prevents native children from bypassing slot order,
preserves the native style type, and retains `ref`.

For a `View` or `Pressable` root that supports desktop tooltips, include the package-local `DesktopTooltipProps`
in its public root props and forward `tooltip?: string` unchanged to that view, once. Do not augment stock RN
types, create a second view, or add focus/hit testing just to show a tip. A polymorphic Icon and the pointer-transparent
FocusVisual are not tooltip targets. See the [Tooltip contract](../src/components/tooltip/SPEC.md#public-contract).

Compose the final public props with:

```ts
Expand Down Expand Up @@ -78,7 +82,7 @@ Build state from:
- derived booleans or values needed by styles and rendering
- preserved user values that must be applied at a later stage

Button state includes `ThemeState`, `PressableState`, `iconOnly`, `isToggleButton`, and `userStyle`. Avoid carrying raw
Button state includes `ThemeState`, `PressableState`, `iconOnly`, and `userStyle`. Avoid carrying raw
props that no later stage uses.

## Primitive contracts
Expand Down
Loading
Loading