Skip to content
Merged
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
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/quiet-chevrons-pilot.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
'@fluentui-react-native/components': minor
'@fluentui-react-native/design': minor
'@fluentui-react-native/extract-icons': minor
---

Add typed asset references to component tokens and use size-specific Fluent SVG chevrons in MenuButton on macOS, Windows, and Win32. The extractor can emit a provenance manifest for generated icons.

Render the MenuButton chevron adapters directly without an extra React component layer.
9 changes: 9 additions & 0 deletions .changeset/round-buttons-layer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
'@fluentui-react-native/components': minor
'@fluentui-react-native/design': minor
'@fluentui-react-native/framework-base': minor
---

Add JSON component tokens and theme override layers for Button and MenuButton. Caller visual styles and slot props take precedence over component and theme defaults.

Export reusable token validators and React Native style enum value lists from `@fluentui-react-native/design/styling` for custom components.
2 changes: 2 additions & 0 deletions apps/storybook/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ configuration, driver, and runtime behavior belongs to package-owned guidance:
`prep` when switching renderer. Bundle before prep if Pods must embed the
JavaScript bundle. Only `macos/Podfile` is hand-authored; Pods, lockfiles,
workspaces, build products, and DerivedData are generated.
- macOS native smoke uses the instance-specific bundle embedded in the app.
The interactive development commands still use Metro.
- Windows project files and registrations are generated. Preserve the app's
declared helper and identity setup.
- Win32 uses the prebuilt REX Paper host. Bundle before run; native build is
Expand Down
23 changes: 22 additions & 1 deletion apps/storybook/desktop.config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,17 @@ import { defineDesktopConfig } from '@fluentui-react-native/desktop-test/config'

import appManifest from './app.json' with { type: 'json' };

// RNSVG's WinMD must not target a newer SDK than the app. CI supplies the installed SDK.
const windowsSdkVersion = process.env.WindowsTargetPlatformVersion || '10.0.22621.0';
const windowsArgs = [
'run-windows',
'--sln',
'windows/AgenticStorybook.sln',
'--no-packager',
'--msbuildprops',
`WindowsTargetPlatformVersion=${windowsSdkVersion}`,
];

const win32Host = {
component: 'AgenticStorybook',
windowTitle: 'Agentic Components Storybook (Win32)',
Expand All @@ -18,7 +29,13 @@ export default defineDesktopConfig({
projectRoot: new URL('.', import.meta.url),
targets: {
macos: { host: { kind: 'react-native-test-app', renderer: 'fabric' } },
windows: { host: { kind: 'react-native-test-app', renderer: 'fabric' } },
windows: {
host: { kind: 'react-native-test-app', renderer: 'fabric' },
commands: {
build: { command: 'rnc-cli', args: [...windowsArgs, '--no-deploy', '--no-launch'] },
run: { command: 'rnc-cli', args: windowsArgs },
},
},
win32: { host: { kind: 'rex', renderer: 'paper', ...win32Host }, commands: { run: createWin32RunCommand(win32Host) } },
},
reporting: { artifactsRoot: './artifacts/desktop' },
Expand Down Expand Up @@ -50,6 +67,10 @@ export default defineDesktopConfig({
],
],
platformOptions: {
macos: {
// Native smoke builds an instance-specific bundle. Test that bundle rather than starting a second, cold Metro build at launch.
smoke: { native: { kind: 'macos' }, metro: false },
},
windows: {
smoke: createWindowsSmokeOptions({
windowTitle: 'Agentic Components Storybook',
Expand Down
7 changes: 0 additions & 7 deletions apps/storybook/react-native.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,5 @@ const project = (() => {
})();

module.exports = {
dependencies: {
'react-native-svg': {
platforms: {
windows: null,
},
},
},
...(project ? { project } : undefined),
};
28 changes: 28 additions & 0 deletions packages/agentic/components/THIRD_PARTY_NOTICES.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
Fluent System Icons
https://github.com/microsoft/fluentui-system-icons

The generated Fluent icon modules use artwork from @fluentui/svg-icons and
code generated by @fluentui/react-native-icons. The adjacent generated
manifest records the package versions and hashes. The upstream MIT license:

MIT License

Copyright (c) 2020 Microsoft Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
15 changes: 13 additions & 2 deletions packages/agentic/components/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
"AGENTS.md",
"CHANGELOG.md",
"README.md",
"THIRD_PARTY_NOTICES.txt",
"jest.config.cjs",
"lib/",
"package.json",
Expand Down Expand Up @@ -49,6 +50,9 @@
"clean": "fluentui-scripts clean",
"format": "fluentui-scripts format",
"lint": "fluentui-scripts lint",
"prebuild": "node ./scripts/generate-token-icons.cjs",
"prepack": "node ./scripts/generate-token-icons.cjs --check",
"check:token-icons": "node ./scripts/generate-token-icons.cjs --check",
"report:spec-source-drift": "node ./scripts/spec-contracts/report-spec-source-drift.cjs",
"test": "node ./scripts/spec-contracts/check-spec-contracts.cjs && yarn test:stories && fluentui-scripts jest",
"test:stories": "tsc -p tsconfig.stories.json",
Expand All @@ -57,11 +61,13 @@
"dependencies": {
"@fluentui-react-native/design": "workspace:*",
"@fluentui-react-native/framework-base": "workspace:*",
"@fluentui-react-native/native-core": "workspace:*"
"@fluentui-react-native/native-core": "workspace:*",
"@fluentui/react-native-icons": "2.0.347"
},
"devDependencies": {
"@babel/core": "catalog:",
"@fluentui-react-native/desktop-driver": "workspace:*",
"@fluentui-react-native/extract-icons": "workspace:*",
"@fluentui-react-native/scripts": "workspace:*",
"@fluentui-react-native/storybook-desktop": "workspace:*",
"@office-iss/react-native-win32": "^0.81.0",
Expand Down Expand Up @@ -105,7 +111,12 @@
}
},
"furn": {
"jestPlatform": "macos"
"jestPlatform": "macos",
"tokenAssets": {
"fluent-icon": {
"output": "src/common/generated/fluent-icons"
}
}
},
"rnx-kit": {
"kitType": "library",
Expand Down
8 changes: 6 additions & 2 deletions packages/agentic/components/references/contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,12 @@ JSON provides unambiguous scalars, built-in Node parsing, deterministic atomic
rewrites, and no additional parser dependency. Generator rewrites would also
discard the main benefit of YAML comments. Keep this provenance in JSON.

`spec/tokens.yaml` remains YAML because it is concise, human-authored token
mapping data rather than a generated identity record.
Existing `spec/tokens.yaml` companions document version 1 bindings. Components
using the runtime token layer instead own a single `spec/tokens.json` companion
with `schemaVersion: 2`, `component`, `implementation`, an ordered `axes` list,
slot `bindings`, and `tokenGaps`. `SPEC.md` links the authoritative companion.
The component imports JSON directly; the checker must not regenerate its values.
See [Styles and tokens](styles-and-tokens.md) for selectors and resolution.

## Schema version 2

Expand Down
2 changes: 2 additions & 0 deletions packages/agentic/components/references/source-boundaries.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ or [primitive](primitives.md) reference when a change crosses component boundari

- Production source may depend only on React / React Native native components, `@fluentui-react-native/design`,
`@fluentui-react-native/framework-base`, and native-core's public modern platform entrypoints.
- Generated Fluent icon leaves may import `react-native-svg` and `@fluentui/react-native-icons/utils`. Do not import
the Fluent icons catalog from component code. The extractor and SVG catalog are build-time dependencies only.
- Import native-core values only from platform-resolved files (for example `common/popupHost.macos.ts` importing
`@fluentui-react-native/native-core/macos`). Shared files may use `import type` from `/macos`, whose types the
`/windows` entrypoint exports identically. Never import its root, `/legacy`, or internals, and give hosts without a
Expand Down
83 changes: 50 additions & 33 deletions packages/agentic/components/references/styles-and-tokens.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,24 +27,59 @@ value.
array of layers; the design token reference (`@fluentui-react-native/design/references/tokens.md`) describes shadow
and motion values.
- Prefer Flex tokens for every mapped semantic value.
- Import named global tokens only when Flex has no equivalent, such as current Button icon dimensions or a true zero.
- Record a genuine token gap in the component spec. Do not replace it with a nearby token or numeric literal.
- Use typed JSON literals for fixed defaults such as Button's icon dimensions. In older TypeScript factories, use named
globals where appropriate. Record genuine semantic gaps; do not substitute unrelated tokens that currently match by value.
- For compatibility with an existing V1 component, derive cross-platform mappings from its Win32, macOS, or Windows
implementation. Do not use iOS as the canonical value unless the change explicitly targets iOS.
- Consumers of the same theme source, revision, and resolved appearance share one `ThemeState`, and therefore token
and style-cache identity. The design theming reference (`@fluentui-react-native/design/references/theming.md`)
defines the cache keys and when a new state is created.

## Build styles in layers
## Component token companions (v2)

Button and MenuButton 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:

```json
{
"borderWidth": "tokens:strokeWidth.thin",
"when.size.medium": {
"paddingHorizontal": "tokens:spacing.componentBase250",
"when.iconOnly.true": { "paddingHorizontal": "tokens:spacing.componentBase150" }
}
}
```

For private icon slots, `fluent-icon: ChevronDown16Regular` references a sized Fluent export. Component `prebuild`
scans every binding branch and extracts one private TSX leaf per referenced asset into the directory configured
under `furn.tokenAssets` in the package manifest. Commit generated modules and their provenance manifest; run
`yarn check:token-icons` to detect stale output without writing it. Group all SVG adapters and asset registries for a
component in its private `<component>.assets.tsx`, even when they serve unrelated slots. Import only the generated
leaves the component needs, never a catalog barrel or a path read from JSON. Define hook-free SVG adapters with
`directComponent` from framework-base and use its JSX runtime so the `Icon` primitive can inline the adapter without an
extra React component layer. MenuButton uses the size-specific Fluent SVG chevron on all supported renderers; its
Variants story exercises the production trigger.

`when.<field>.<value>` is a literal selector key. Nest only later axes inside a branch. Matching rules combine by
property; the higher differing axis wins within the same layer. Provide a component-owned combined `visualState` for
exclusive presentation; Button's order is disabled, pressed, hovered, then rest. Independent booleans such as `selected`
remain separate. Do not mutate raw interaction state.

Use four layers:
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.

1. A module-scoped `StyleSheet` for structural values that do not depend on theme, props, or state.
2. Module-scoped state factories for theme-independent state selectors.
3. Module-scoped themed factories for token-derived styles.
4. Per-instance style arrays that select cached objects and place user styles last.
Visual precedence is **component defaults, then theme layers, then caller visuals**. Even a base theme field overrides
a state-specific default. A caller's slot visual props and styles win through `attachSlotDefaults`; component-owned
handlers, refs, slot presence, and accessibility are not token overrides. Keep shared focus behavior and Menu popup
styling outside MenuButton's chevron tokens.

Never create a style factory inside a hook or render function.
## Legacy state-style factories

For components without a v2 companion, use module-scoped structural styles, state factories, and themed factories,
then select cached styles and apply per-instance values. Never create a style factory inside a hook or render function.

Reuse the design package's `@fluentui-react-native/design/styling` submodule. The design
styling reference (`@fluentui-react-native/design/references/styling.md`) owns the factory and hierarchy semantics:
Expand All @@ -56,8 +91,7 @@ styling reference (`@fluentui-react-native/design/references/styling.md`) owns t
- `getThemedColorStyleFactory` converts semantic
color keys and delegates its hierarchy and caching to `getThemedStateStyleFactory`.

These are the canonical Button mechanisms and cache plain resolved style objects in `state.themeStyles`. Do not wrap them
in another `StyleSheet.create` cache. Use
These factories cache plain resolved style objects in `state.themeStyles`. Do not wrap them in another `StyleSheet.create` cache. Use
`themedStyleSheetFactory` only when a component genuinely
needs a complete theme-only `StyleSheet.create` result that is not represented by a branched state definition.

Expand All @@ -66,15 +100,8 @@ and user styles must remain outside the cache so one component instance cannot l

## Declare state hierarchy and precedence

Represent related axes as ordered hierarchy levels. Each level contains mutually exclusive states in priority order.
Button colors use:

```ts
[['primary', 'secondary', 'outline', 'subtle'], ['selected'], ['disabled', 'pressed', 'hovered']];
```

This means appearance is the base branch, selected refines it, and interaction is the final refinement. Put interaction
states in `disabled`, `pressed`, `hovered` order so the first active state has the required priority.
In legacy factories, represent related axes as ordered hierarchy levels. Each level contains mutually exclusive states
in priority order. Put exclusive interaction states in `disabled`, `pressed`, `hovered` order.

Use `getThemedStateStyleFactory` for token-derived hierarchy definitions and `getStateStyleFactory` for
theme-independent definitions. Use `getThemedColorStyleFactory` for semantic background, border, and foreground colors;
Expand All @@ -85,21 +112,11 @@ An interaction may intentionally switch semantic keys. Button Subtle is transpar
pressed token values provide visible stroke feedback. Do not assume a token named `Transparent` will produce visible
interaction states; verify the resolved colors' `hover` and `pressed` values.

Build the state source from resolved state without hiding precedence in conditionals. Button pushes appearance, selected,
disabled, pressed, and hovered values, then lets the declared hierarchy select the winner.
Build the legacy factory's state source from resolved state; the declared hierarchy selects the winner.

## Group related layout axes

Combine axes that produce one coherent style object. Button selects size, shape, and content layout from one root style
hierarchy:

```ts
[
['small', 'medium', 'large'],
['rounded', 'square', 'circle'],
['withContent', 'iconOnly'],
];
```
Group axes that produce one coherent style object; size, shape, and content layout can refine the same slot.

Use separate factories for independent concerns such as typography, focus, and content visibility. This keeps unrelated
state branches from multiplying into one large definition.
Expand All @@ -115,7 +132,7 @@ token before assigning it to `ViewStyle['gap']`.

## Apply slot props in one stage

`use<Component>Styles.ts` should export `use<Component>Styles_unstable`, select styles, and call `attachSlotProps`; it
`use<Component>Styles.ts` should export `use<Component>Styles_unstable`, select styles, and apply slot props; it
should not create factories. Export that hook directly from the package root under the same name.

Compose root styles in this order:
Expand Down
67 changes: 67 additions & 0 deletions packages/agentic/components/scripts/generate-token-icons.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
const { spawnSync } = require('node:child_process');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { validateTokenCompanion } = require('./spec-contracts/token-companion.cjs');

const root = path.resolve(__dirname, '..');
const { output } = require('../package.json').furn.tokenAssets['fluent-icon'];
const destination = path.resolve(root, output);
const check = process.argv[2] === '--check';
const manifestName = 'manifest.generated.json';

if (!/^src\/common\/generated\/[a-z][a-z0-9-]*$/.test(output)) {
throw new Error('The Fluent icon output must be a dedicated directory under src/common/generated.');
}

const required = new Set();
for (const file of fs.globSync('src/components/*/spec/tokens.json', { cwd: root }).sort()) {
const component = path.basename(path.dirname(path.dirname(file)));
const icons = validateTokenCompanion(fs.readFileSync(path.join(root, file), 'utf8'), component, file);
for (const icon of icons) required.add(icon);
}

const staging = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'furn-token-icons-'));
try {
const jobs = [...required].sort().map((icon) => ({ output: `${icon}.generated.tsx`, icons: [icon] }));
const manifest = path.join(staging, manifestName);
if (jobs.length > 0) {
const config = path.join(staging, 'extraction.json');
fs.writeFileSync(config, JSON.stringify({ extractIcons: jobs }));
// Repository prebuild runs before tsc has created the extractor's bin.
const cli = path.join(path.dirname(require.resolve('@fluentui-react-native/extract-icons/package.json')), 'src', 'cli.ts');
const result = spawnSync(process.execPath, [cli, '--config', config, '--manifest', manifest], { stdio: 'inherit' });
if (result.error) throw result.error;
if (result.status !== 0) throw new Error(`Token icon extraction failed (${result.signal ?? result.status}).`);
} else {
fs.writeFileSync(manifest, '{\n "schemaVersion": 1,\n "artifacts": []\n}\n');
}

const names = new Set([manifestName, ...jobs.map((job) => job.output)]);
const stale = fs.existsSync(destination)
? fs.readdirSync(destination).filter((file) => /^[A-Z][A-Za-z0-9]*\.generated\.tsx$/.test(file) && !names.has(file))
: [];
const changed = [...names].filter((file) => {
const target = path.join(destination, file);
return !fs.existsSync(target) || !fs.readFileSync(target).equals(fs.readFileSync(path.join(staging, file)));
});
if (check && (changed.length || stale.length)) {
throw new Error(`Generated Fluent icons are out of date: ${[...changed, ...stale].join(', ')}. Run yarn prebuild.`);
}
if (!check) {
fs.mkdirSync(destination, { recursive: true });
for (const file of changed) {
const target = path.join(destination, file);
const pending = `${target}.${process.pid}.tmp`;
try {
fs.copyFileSync(path.join(staging, file), pending);
fs.renameSync(pending, target);
} finally {
fs.rmSync(pending, { force: true });
}
}
for (const file of stale) fs.unlinkSync(path.join(destination, file));
}
} finally {
fs.rmSync(staging, { recursive: true, force: true });
}
Loading