diff --git a/.changeset/build-info-node-modules.md b/.changeset/build-info-node-modules.md new file mode 100644 index 00000000000..9a29c2b0249 --- /dev/null +++ b/.changeset/build-info-node-modules.md @@ -0,0 +1,84 @@ +--- +"@fluentui-react-native/adapters": patch +"@fluentui-react-native/android-theme": patch +"@fluentui-react-native/apple-theme": patch +"@fluentui-react-native/avatar": patch +"@fluentui-react-native/badge": patch +"@fluentui-react-native/button": patch +"@fluentui-react-native/callout": patch +"@fluentui-react-native/checkbox": patch +"@fluentui-react-native/chip": patch +"@fluentui-react-native/codemods": patch +"@fluentui-react-native/components": patch +"@fluentui-react-native/composition": patch +"@fluentui-react-native/contextual-menu": patch +"@fluentui-react-native/default-theme": patch +"@fluentui-react-native/design": patch +"@fluentui-react-native/desktop-driver": patch +"@fluentui-react-native/desktop-test": patch +"@fluentui-react-native/divider": patch +"@fluentui-react-native/drawer": patch +"@fluentui-react-native/dropdown": patch +"@fluentui-react-native/experimental-activity-indicator": patch +"@fluentui-react-native/experimental-appearance-additions": patch +"@fluentui-react-native/experimental-avatar": patch +"@fluentui-react-native/experimental-checkbox": patch +"@fluentui-react-native/experimental-expander": patch +"@fluentui-react-native/experimental-menu-button": patch +"@fluentui-react-native/experimental-native-date-picker": patch +"@fluentui-react-native/experimental-native-font-metrics": patch +"@fluentui-react-native/experimental-shadow": patch +"@fluentui-react-native/experimental-shimmer": patch +"@fluentui-react-native/focus-trap-zone": patch +"@fluentui-react-native/focus-zone": patch +"@fluentui-react-native/framework": patch +"@fluentui-react-native/framework-base": patch +"@fluentui-react-native/icon": patch +"@fluentui-react-native/input": patch +"@fluentui-react-native/interactive-hooks": patch +"@fluentui-react-native/link": patch +"@fluentui-react-native/menu": patch +"@fluentui-react-native/menu-button": patch +"@fluentui-react-native/native-core": patch +"@fluentui-react-native/notification": patch +"@fluentui-react-native/overflow": patch +"@fluentui-react-native/persona": patch +"@fluentui-react-native/persona-coin": patch +"@fluentui-react-native/popover": patch +"@fluentui-react-native/pressable": patch +"@fluentui-react-native/radio-group": patch +"@fluentui-react-native/separator": patch +"@fluentui-react-native/spinner": patch +"@fluentui-react-native/stack": patch +"@fluentui-react-native/storybook-desktop": patch +"@fluentui-react-native/storybook-desktop-runtime": patch +"@fluentui-react-native/styling-utils": patch +"@fluentui-react-native/switch": patch +"@fluentui-react-native/tablist": patch +"@fluentui-react-native/tester": patch +"@fluentui-react-native/text": patch +"@fluentui-react-native/theme": patch +"@fluentui-react-native/theme-tokens": patch +"@fluentui-react-native/theme-types": patch +"@fluentui-react-native/themed-stylesheet": patch +"@fluentui-react-native/theming-utils": patch +"@fluentui-react-native/tokens": patch +"@fluentui-react-native/tooltip": patch +"@fluentui-react-native/use-slots": patch +"@fluentui-react-native/use-styling": patch +"@fluentui-react-native/use-tokens": patch +"@fluentui-react-native/vibrancy-view": patch +"@fluentui-react-native/win32-theme": patch +"@fluentui/react-native": patch +"@uifabricshared/foundation-composable": patch +"@uifabricshared/foundation-compose": patch +"@uifabricshared/foundation-settings": patch +"@uifabricshared/foundation-tokens": patch +"@uifabricshared/theme-registry": patch +"@uifabricshared/themed-settings": patch +"@uifabricshared/theming-ramp": patch +"@uifabricshared/theming-react-native": patch +--- + +Write TypeScript build information to `node_modules/.cache` instead of `.cache`, so +incremental build state is no longer included in published packages. diff --git a/.changeset/components-native-core-guidance.md b/.changeset/components-native-core-guidance.md new file mode 100644 index 00000000000..84b183117b8 --- /dev/null +++ b/.changeset/components-native-core-guidance.md @@ -0,0 +1,13 @@ +--- +"@fluentui-react-native/callout": patch +"@fluentui-react-native/components": patch +"@fluentui-react-native/focus-zone": patch +"@fluentui-react-native/native-core": patch +--- + +Add package-owned agent guidance, user entry points, and indexed references to +components and native-core. The agentic component recipes and contract source +adapters move into the components package, the desktop focus plan is replaced +by `references/remaining-work.md`, and both packages publish their guidance. +Components now restricts published contents with a `files` allowlist, and the +callout and focus-zone shims link to native-core's architecture reference. diff --git a/.changeset/design-framework-base-guidance.md b/.changeset/design-framework-base-guidance.md new file mode 100644 index 00000000000..c655f581230 --- /dev/null +++ b/.changeset/design-framework-base-guidance.md @@ -0,0 +1,11 @@ +--- +"@fluentui-react-native/design": patch +"@fluentui-react-native/desktop-driver": patch +"@fluentui-react-native/framework-base": patch +--- + +Add package-owned agent guidance, user entry points, and indexed references to +design and framework-base. Design's completed plan is removed and its open +theming work moves to `references/remaining-work.md`. Both packages now restrict +published contents with a `files` allowlist. Desktop Driver guidance now tracks +unfinished work in a remaining-work reference. diff --git a/.github/skills/agentic-component-authoring/SKILL.md b/.github/skills/agentic-component-authoring/SKILL.md index 523995961a1..28151f6bfca 100644 --- a/.github/skills/agentic-component-authoring/SKILL.md +++ b/.github/skills/agentic-component-authoring/SKILL.md @@ -14,10 +14,10 @@ references the current change needs. - **Higher-order components** live in `src/components`. Read the [package instructions](../../../packages/agentic/components/AGENTS.md) and the - [higher-order component instructions](../../../packages/agentic/components/src/components/AGENTS.md). The + [higher-order component reference](../../../packages/agentic/components/references/higher-order-components.md). The component's `SPEC.md` and `spec/` companions are its contract. - **Primitives** live in `src/primitives`. Read the package instructions and the - [primitive instructions](../../../packages/agentic/components/src/primitives/AGENTS.md). A primitive's colocated + [primitive reference](../../../packages/agentic/components/references/primitives.md). A primitive's colocated `CONTRACT.md` is its contract; primitives have no upstream-backed `SPEC.md`. - Changes spanning components, repeated helpers, or dependency boundaries also use the [optimization skill](../agentic-component-optimization/SKILL.md). Do not audit the whole package for a small edit. @@ -28,16 +28,16 @@ references the current change needs. ## Load focused references -| Work | Reference | -| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Source interpretation, provenance, contract drafting, or divergences | [Contract authoring](../agentic-component-contract-authoring/SKILL.md) | -| Public props, slots, state types, native prop exposure, or exports | [Types and slots](../../../references/agents/components/agentic/types-and-slots.md) | -| Defaults, derived state, interaction hooks, accessibility, or slots | [State and accessibility](../../../references/agents/components/agentic/state-and-accessibility.md) | -| Focus, focus visuals, keyboard activation, or native focus refs | [Common focus authoring](../../../references/agents/focus/common.md), then [Windows/Win32](../../../references/agents/focus/windows-win32.md) or [macOS](../../../references/agents/focus/macos.md) | -| Tokens, theme caching, state precedence, or slot style application | [Styles and tokens](../../../references/agents/components/agentic/styles-and-tokens.md) and [tokens and theming](../../../references/agents/design/tokens-and-theming.md) | -| Pure slot rendering, component assembly, or display names | [Rendering and assembly](../../../references/agents/components/agentic/rendering.md) | -| Runtime tests, type tests, snapshots, Storybook stories, or validation | [Tests and stories](../../../references/agents/components/agentic/tests-and-stories.md) | -| Native React Native Windows Fabric components, codegen, registration, or UIA | [Windows Fabric native components](../../../references/agents/native/windows-fabric.md) | +| Work | Reference | +| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Source interpretation, provenance, contract drafting, or divergences | [Contract authoring](../agentic-component-contract-authoring/SKILL.md) | +| Public props, slots, state types, native prop exposure, or exports | [Types and slots](../../../packages/agentic/components/references/types-and-slots.md) | +| Defaults, derived state, interaction hooks, accessibility, or slots | [State and accessibility](../../../packages/agentic/components/references/state-and-accessibility.md) | +| Focus, focus visuals, keyboard activation, or native focus refs | [Common focus authoring](../../../references/agents/focus/common.md), then [Windows/Win32](../../../references/agents/focus/windows-win32.md) or [macOS](../../../references/agents/focus/macos.md) | +| Tokens, theme caching, state precedence, or slot style application | [Styles and tokens](../../../packages/agentic/components/references/styles-and-tokens.md) and design [tokens](../../../packages/agentic/design/references/tokens.md) and [styling](../../../packages/agentic/design/references/styling.md) | +| Pure slot rendering, component assembly, or display names | [Rendering and assembly](../../../packages/agentic/components/references/rendering.md) | +| Runtime tests, type tests, snapshots, Storybook stories, or validation | [Tests and stories](../../../packages/agentic/components/references/tests-and-stories.md) | +| Native React Native Windows Fabric components, codegen, registration, or UIA | [Windows Fabric native components](../../../references/agents/native/windows-fabric.md) | A new higher-order component normally needs the types, state, styles, rendering, and tests references, plus focus guidance when it is focusable. Load the Windows Fabric reference only for native Windows views. A focused fix loads only @@ -55,8 +55,8 @@ references used, the implementation order, and the validation plan. [contract authoring workflow](../agentic-component-contract-authoring/SKILL.md) and complete its pre-code review gate first (R-AGENTIC-001 in the [package instructions](../../../packages/agentic/components/AGENTS.md)). 3. Inspect the closest canonical implementation: - [`components/button`](../../../packages/agentic/components/src/components/button) for a styled higher-order - component, or [`primitives/icon`](../../../packages/agentic/components/src/primitives/icon) for a direct primitive. + `packages/agentic/components/src/components/button` for a styled higher-order component, or + `packages/agentic/components/src/primitives/icon` for a direct primitive. 4. Establish the public contract before implementation: variants, slots, native props, accessibility, interaction states, and platform behavior. 5. Implement in dependency order: types and slots, state and accessibility, styles and slot props, pure rendering, diff --git a/.github/skills/agentic-component-contract-authoring/SKILL.md b/.github/skills/agentic-component-contract-authoring/SKILL.md index eb9c0a22b74..91e4b7006dc 100644 --- a/.github/skills/agentic-component-contract-authoring/SKILL.md +++ b/.github/skills/agentic-component-contract-authoring/SKILL.md @@ -32,20 +32,20 @@ draft, or accompanied by new source evidence. Load every adapter represented by the supplied evidence, but no others. -| Evidence | Adapter | -| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| Pinned Flex component skill and X3 lineage | [Flex and X3](../../../references/agents/components/agentic/contract-sources/flex-x3.md) | -| Fluent UI v9 source or specification | [Fluent v9](../../../references/agents/components/agentic/contract-sources/fluent-v9.md) | -| HTML, CSS, computed styles, or browser output | [HTML and CSS](../../../references/agents/components/agentic/contract-sources/html-css.md) | -| Images, screenshots, or design renders | [Visual reference](../../../references/agents/components/agentic/contract-sources/visual-reference.md) | -| Public native API plus repository precedent | [Local foundation](../../../references/agents/components/agentic/contract-sources/local-foundation.md) | -| More than one of the preceding source sets | [Composite evidence](../../../references/agents/components/agentic/contract-sources/composite-evidence.md) | +| Evidence | Adapter | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| Pinned Flex component skill and X3 lineage | [Flex and X3](../../../packages/agentic/components/references/contract-sources/flex-x3.md) | +| Fluent UI v9 source or specification | [Fluent v9](../../../packages/agentic/components/references/contract-sources/fluent-v9.md) | +| HTML, CSS, computed styles, or browser output | [HTML and CSS](../../../packages/agentic/components/references/contract-sources/html-css.md) | +| Images, screenshots, or design renders | [Visual reference](../../../packages/agentic/components/references/contract-sources/visual-reference.md) | +| Public native API plus repository precedent | [Local foundation](../../../packages/agentic/components/references/contract-sources/local-foundation.md) | +| More than one of the preceding source sets | [Composite evidence](../../../packages/agentic/components/references/contract-sources/composite-evidence.md) | ## Workflow -1. Read the package instructions, the existing `SPEC.md`, all companions under - `spec/`, and `SPEC-SOURCE.md`. Preserve a reviewed contract unless new - evidence or an explicit requested behavior change requires re-review. +1. Read the [package instructions](../../../packages/agentic/components/AGENTS.md), the existing `SPEC.md`, all + companions under `spec/`, and the [contracts reference](../../../packages/agentic/components/references/contracts.md). + Preserve a reviewed contract unless new evidence or an explicit requested behavior change requires re-review. 2. Inventory the source sets. Give each source a stable kebab-case ID, classify its authority, pin immutable identities where possible, and record only public or redistributable evidence. @@ -60,7 +60,7 @@ Load every adapter represented by the supplied evidence, but no others. - public API, slots, defaults, state ownership, and requirement IDs in `SPEC.md`; - FURN token bindings and gaps in `spec/tokens.yaml`, mapped through the - [Flex token map](../../../packages/agentic/design/src/tokens/mappings/flex-token-map.yaml). + canonical Flex token map described in the [design tokens reference](../../../packages/agentic/design/references/tokens.md). Name each proposed binding or list it as unresolved; - native accessibility in `spec/accessibility.md`; - keyboard, pointer, focus, and motion behavior in @@ -75,27 +75,18 @@ Load every adapter represented by the supplied evidence, but no others. `review-required`, and a null review date until the source interpretation, native adaptation, authority decisions, and planned evidence are coherent. Move to `contract-reviewed` only after that explicit review. -8. Run the package contract checker. Source refresh tools may update provenance - but never approve a contract or populate reviewed surfaces automatically. +8. Run the package contract checker described in + [validation and drift](../../../packages/agentic/components/references/contracts.md#validation-and-drift). Source + refresh tools may update provenance but never approve a contract or populate reviewed surfaces automatically. ## Contract rules -- `spec/source.json` uses schema version 2 and a sorted, non-empty `sources[]`. - Source IDs are unique. Keep this generated, digest-heavy metadata in JSON; - `spec/tokens.yaml` remains YAML because token mappings are human-authored. -- Supported source kinds are `flex-skill`, `git-files`, `html-css`, - `visual-reference`, and `local-foundation`. -- A source's `authority` describes how it may govern requirements. Requirement - `sources` identify the actual source set used for that decision. -- `git-files` records a repository, full commit SHA, and sorted file paths with - SHA-256 digests. `html-css` and `visual-reference` record immutable artifact - digests; repository-relative artifacts are verified locally. -- A `local-foundation` source is valid only when no Flex catalog component - exists and must be the contract's sole source. -- Only `flex-skill` has automated release and candidate drift reporting. - Other immutable sources report Flex drift as `not-applicable`; refresh their - identities through an explicit source review. -- A reviewed local contract is normative for FURN. New upstream evidence is a - change proposal, not an automatic rewrite. -- Do not copy or lightly transform private source bodies into this public - repository. Record identities and write original React Native documentation. +The [contracts reference](../../../packages/agentic/components/references/contracts.md) owns the `spec/source.json` +schema, source kinds and authorities, lifecycle and review state, the public content boundary, and the validation and +drift commands. Apply it rather than restating it here. In particular: + +- A reviewed local contract is normative for FURN. New upstream evidence is a change proposal, not an automatic + rewrite. +- A `local-foundation` source is valid only when no Flex catalog component exists, and it must be the sole source. +- Record identities and write original React Native documentation; never copy or lightly transform private source + bodies into this public repository (R-REPO-004). diff --git a/.github/skills/agentic-component-optimization/SKILL.md b/.github/skills/agentic-component-optimization/SKILL.md index 54a1a13240f..a545d073f0e 100644 --- a/.github/skills/agentic-component-optimization/SKILL.md +++ b/.github/skills/agentic-component-optimization/SKILL.md @@ -13,18 +13,18 @@ primitive or helper should exist at all. ## Read first 1. Read the [package instructions](../../../packages/agentic/components/AGENTS.md) and the - [source instructions](../../../packages/agentic/components/src/AGENTS.md). -2. Read the relevant component or primitive `AGENTS.md` file and the colocated `SPEC.md` or `CONTRACT.md` files for the - affected area. + [source boundaries reference](../../../packages/agentic/components/references/source-boundaries.md). +2. Read the [higher-order component](../../../packages/agentic/components/references/higher-order-components.md) or + [primitive](../../../packages/agentic/components/references/primitives.md) reference and the colocated `SPEC.md` or + `CONTRACT.md` files for the affected area. 3. Inspect the canonical implementations: - [`components/button`](../../../packages/agentic/components/src/components/button) and - [`primitives/icon`](../../../packages/agentic/components/src/primitives/icon). + `packages/agentic/components/src/components/button` and `packages/agentic/components/src/primitives/icon`. ## Audit checklist ### 1. Dependency direction -Apply the [source boundaries](../../../packages/agentic/components/src/AGENTS.md#source-boundaries): production +Apply the [source boundaries](../../../packages/agentic/components/references/source-boundaries.md#source-boundaries): production dependencies, where generalizable hooks and styling helpers belong, and what stays in `src/common`. ### 2. Repetition and ownership diff --git a/.github/skills/implement-native-component/SKILL.md b/.github/skills/implement-native-component/SKILL.md index 0fe06089204..0fa13aa0c0a 100644 --- a/.github/skills/implement-native-component/SKILL.md +++ b/.github/skills/implement-native-component/SKILL.md @@ -20,26 +20,30 @@ ownership and qualification rules (R-NATIVE-001 through R-NATIVE-003). [classification guide](../../../references/agents/components/classification.md); - native registration names and entrypoints that must not change. 2. Choose ownership. New modern native code belongs in native-core (R-NATIVE-001); maintain existing native wrappers, - such as experimental packages, where they live. For native-core work, read the relevant sections of the - [native-core README](../../../packages/agentic/native-core/README.md); for a wrapper in another package, read that - package's sources and documentation instead. + such as experimental packages, where they live. For native-core work, start from its + [package instructions](../../../packages/agentic/native-core/AGENTS.md) and read the relevant + [native-core references](../../../packages/agentic/native-core/references/README.md); for a wrapper in another + package, read that package's sources and documentation instead. 3. Load only the platform references the work needs: - React Native Windows Fabric views: [Windows Fabric](../../../references/agents/native/windows-fabric.md); - any iOS or macOS Swift, Objective-C, header, podspec, or bridge-manager change: [Apple native authoring and Office integration](../../../references/agents/native/apple-office.md) - (R-APPLE-001 through R-APPLE-007), plus native-core's macOS layout notes for native-core work; + (R-APPLE-001 through R-APPLE-007), plus native-core's + [native layout](../../../packages/agentic/native-core/references/architecture.md#native-layout-and-host-policy) and + [Swift interoperability](../../../packages/agentic/native-core/references/architecture.md#macos-swift-interoperability) + notes for native-core work; - focus targets or native focus visuals: [common focus authoring](../../../references/agents/focus/common.md) and its platform file; - accessibility actions: - [framework-base accessibility instructions](../../../packages/framework-base/src/accessibility/AGENTS.md); + [framework-base accessibility reference](../../../packages/framework-base/references/accessibility.md); - the JavaScript wrapper: the [agentic skill](../agentic-component-authoring/SKILL.md), [v0 recipe](../../../references/agents/components/v0.md), or [v1 recipe](../../../references/agents/components/v1.md). 4. Implement with the TypeScript specification, codegen configuration, native props, events, commands, and registration kept consistent. Preserve public APIs and registration names (R-NATIVE-002) and keep fork imports in platform files (R-REPO-002). 5. Validate the affected boundary with declared scripts (R-VALID-001), running focused package tests while iterating - (R-VALID-004): package build, test, and lint; native-core - `codegen:windows` when Windows specs change; native builds through the owning app, such as + (R-VALID-004): package build, test, and lint; native-core `yarn codegen:windows --check` when Windows specs change + and `yarn test:apple-integration` when its macOS native code changes; native builds through the owning app, such as `yarn storybook build --macos` or `--windows` from `apps/storybook`; and runtime evidence through Storybook smoke or `wdio` story tests. macOS Storybook commands default to Fabric: add `--paper` to `prep`, `build`, `run`, or `smoke` for Paper, and rerun `prep` when switching renderers. Desktop Storybook does not build iOS: validate iOS-only changes diff --git a/.github/skills/maintain-desktop-testing/SKILL.md b/.github/skills/maintain-desktop-testing/SKILL.md index 5c16d62d393..debc8e300c4 100644 --- a/.github/skills/maintain-desktop-testing/SKILL.md +++ b/.github/skills/maintain-desktop-testing/SKILL.md @@ -13,7 +13,8 @@ license: MIT | Storybook integration, CLI, extraction, tests | [`storybook-desktop`](../../../packages/agentic/storybook-desktop/AGENTS.md) | | On-device bridge, Metro, theme, chrome | [`runtime`](../../../packages/agentic/storybook-desktop-runtime/AGENTS.md) | -Read the matching contributing reference from the package index. +Read the owning package's `AGENTS.md`, then its contributing reference from the package index. The runtime has no +contributing reference; use its `AGENTS.md` validation section and its runtime contract reference instead. ## Mode first diff --git a/.github/skills/maintain-v0-v1-component/SKILL.md b/.github/skills/maintain-v0-v1-component/SKILL.md index 67127a3f609..a1e2042beaf 100644 --- a/.github/skills/maintain-v0-v1-component/SKILL.md +++ b/.github/skills/maintain-v0-v1-component/SKILL.md @@ -24,7 +24,8 @@ v0 and v1 are maintenance-only (R-V0-001 and R-V1-001). A request for a new comp [native component skill](../implement-native-component/SKILL.md) checklist; - focus, keyboard activation, or focus visuals: [common focus authoring](../../../references/agents/focus/common.md) and its platform file; - - token values or theme behavior: [tokens and theming](../../../references/agents/design/tokens-and-theming.md); + - token values or theme behavior: design [tokens](../../../packages/agentic/design/references/tokens.md) and + [theming](../../../packages/agentic/design/references/theming.md); - FluentTester pages or E2E specs: [legacy test apps](../../../references/agents/components/legacy-test-apps.md). 4. Read the component's existing tests, snapshots, platform variants, and any `SPEC.md` or `MIGRATION.md` before editing. diff --git a/.github/skills/review-component/SKILL.md b/.github/skills/review-component/SKILL.md index 8c13d635970..0903fdc52aa 100644 --- a/.github/skills/review-component/SKILL.md +++ b/.github/skills/review-component/SKILL.md @@ -19,17 +19,17 @@ license: MIT public compatibility, and native obligations (R-CLASSIFY-001, R-CLASSIFY-002). 3. Load only the checklists for the surfaces present: - | Surface | Checklist | - | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | v0 | [v0 review checklist](../../../references/agents/components/v0.md#review-checklist) | - | v1 | [v1 review checklist](../../../references/agents/components/v1.md#review-checklist) | - | Agentic higher-order | [Package](../../../packages/agentic/components/AGENTS.md) and [higher-order](../../../packages/agentic/components/src/components/AGENTS.md) invariants; the component's `SPEC.md` and `spec/`; and the review checklists in [types and slots](../../../references/agents/components/agentic/types-and-slots.md#review-checklist), [state and accessibility](../../../references/agents/components/agentic/state-and-accessibility.md#review-checklist), [styles and tokens](../../../references/agents/components/agentic/styles-and-tokens.md#review-checklist), and [rendering](../../../references/agents/components/agentic/rendering.md#review-checklist) for the areas changed | - | Agentic primitive | [Primitive invariants](../../../packages/agentic/components/src/primitives/AGENTS.md), the primitive's `CONTRACT.md`, and [primitive contracts](../../../references/agents/components/agentic/types-and-slots.md#primitive-contracts) | - | Tests and stories | [Tests and stories](../../../references/agents/components/agentic/tests-and-stories.md) for agentic code; [legacy test apps](../../../references/agents/components/legacy-test-apps.md) for v0 and v1 | - | Contract or provenance | [Contract authoring](../agentic-component-contract-authoring/SKILL.md) rules and only the [source adapters](../../../references/agents/README.md#document-index) matching the changed evidence | - | Focus or keyboard | [Required focus evidence](../../../references/agents/focus/common.md#required-evidence-before-shipping) and the affected platform file | - | Native code or roots | [Native overlay checklist](../implement-native-component/SKILL.md#native-overlay-checklist); for iOS or macOS, also [Apple and Office rules](../../../references/agents/native/apple-office.md) | - | Framework-base pattern | [Framework-base instructions](../../../packages/framework-base/AGENTS.md) | + | Surface | Checklist | + | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | v0 | [v0 review checklist](../../../references/agents/components/v0.md#review-checklist) | + | v1 | [v1 review checklist](../../../references/agents/components/v1.md#review-checklist) | + | Agentic higher-order | [Package](../../../packages/agentic/components/AGENTS.md) and [higher-order component](../../../packages/agentic/components/references/higher-order-components.md) invariants; the component's `SPEC.md` and `spec/`; and the review checklists in [types and slots](../../../packages/agentic/components/references/types-and-slots.md#review-checklist), [state and accessibility](../../../packages/agentic/components/references/state-and-accessibility.md#review-checklist), [styles and tokens](../../../packages/agentic/components/references/styles-and-tokens.md#review-checklist), and [rendering](../../../packages/agentic/components/references/rendering.md#review-checklist) for the areas changed | + | Agentic primitive | [Primitive invariants](../../../packages/agentic/components/references/primitives.md), the primitive's `CONTRACT.md`, and [primitive contracts](../../../packages/agentic/components/references/types-and-slots.md#primitive-contracts) | + | Tests and stories | [Tests and stories](../../../packages/agentic/components/references/tests-and-stories.md) for agentic code; [legacy test apps](../../../references/agents/components/legacy-test-apps.md) for v0 and v1 | + | Contract or provenance | [Contract authoring](../agentic-component-contract-authoring/SKILL.md) workflow, the [contracts reference](../../../packages/agentic/components/references/contracts.md), and only the [source adapters](../../../packages/agentic/components/references/README.md) matching the changed evidence | + | Focus or keyboard | [Required focus evidence](../../../references/agents/focus/common.md#required-evidence-before-shipping) and the affected platform file | + | Native code or roots | [Native overlay checklist](../implement-native-component/SKILL.md#native-overlay-checklist); for iOS or macOS, also [Apple and Office rules](../../../references/agents/native/apple-office.md) | + | Framework-base pattern | [Framework-base instructions](../../../packages/framework-base/AGENTS.md) | 4. Check repository-wide rules: explicit exports (R-REPO-001), platform fork imports (R-REPO-002), changesets (R-REPO-003), no copied private source (R-REPO-004), and the code-scanning patterns: linear-time regular expressions diff --git a/AGENTS.md b/AGENTS.md index 2b2aaa202c1..4dd9fb00f8b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,27 +60,26 @@ Classify the change with the [classification guide](references/agents/components | Dependency vulnerability remediation | [fix-security-issues](.github/skills/fix-security-issues/SKILL.md) | Other repository work starts from the [reference index](references/agents/README.md): architecture, commands and -validation, TypeScript, release, design tokens, focus, and native guidance. +validation, TypeScript, release, focus, and native guidance. Design tokens and theming start from the +[design package](packages/agentic/design/AGENTS.md). For package-owned knowledge, follow the [package guidance standard](references/agents/repository/package-guidance.md). ## Scoped instructions -| Path | Scope | -| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -| [packages/agentic/components](packages/agentic/components/AGENTS.md) | Agentic package invariants, contracts, and story tests | -| [packages/agentic/components/src](packages/agentic/components/src/AGENTS.md) | Source boundaries and extraction | -| [.../src/components](packages/agentic/components/src/components/AGENTS.md) | Higher-order components and the focus visual policy | -| [.../src/primitives](packages/agentic/components/src/primitives/AGENTS.md) | Public primitives | -| [packages/agentic/desktop-driver](packages/agentic/desktop-driver/AGENTS.md) | Desktop WebDriver driver | -| [packages/agentic/desktop-test](packages/agentic/desktop-test/AGENTS.md) | Application-neutral desktop test harness | -| [packages/agentic/storybook-desktop](packages/agentic/storybook-desktop/AGENTS.md) | Storybook desktop integration | -| [packages/agentic/storybook-desktop-runtime](packages/agentic/storybook-desktop-runtime/AGENTS.md) | On-device Storybook runtime | -| [packages/framework-base](packages/framework-base/AGENTS.md) | Shared component patterns | -| [packages/framework-base/src/accessibility](packages/framework-base/src/accessibility/AGENTS.md) | Accessibility helpers and native action qualification | -| [packages/framework/framework](packages/framework/framework/AGENTS.md) | v1 framework package | -| [packages/deprecated/foundation-compose](packages/deprecated/foundation-compose/AGENTS.md) | v0 framework package | -| [apps/storybook](apps/storybook/AGENTS.md) | Storybook app, native workflows, and diagnostics | +| Path | Scope | +| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [packages/agentic/components](packages/agentic/components/AGENTS.md) | Agentic components, primitives, and contracts | +| [packages/agentic/design](packages/agentic/design/AGENTS.md) | Tokens, theming, styling, and color utilities | +| [packages/agentic/desktop-driver](packages/agentic/desktop-driver/AGENTS.md) | Desktop WebDriver driver | +| [packages/agentic/desktop-test](packages/agentic/desktop-test/AGENTS.md) | Application-neutral desktop test harness | +| [packages/agentic/native-core](packages/agentic/native-core/AGENTS.md) | Native components and modules | +| [packages/agentic/storybook-desktop](packages/agentic/storybook-desktop/AGENTS.md) | Storybook desktop integration | +| [packages/agentic/storybook-desktop-runtime](packages/agentic/storybook-desktop-runtime/AGENTS.md) | On-device Storybook runtime | +| [packages/framework-base](packages/framework-base/AGENTS.md) | Component patterns, hooks, and accessibility helpers | +| [packages/framework/framework](packages/framework/framework/AGENTS.md) | v1 framework package | +| [packages/deprecated/foundation-compose](packages/deprecated/foundation-compose/AGENTS.md) | v0 framework package | +| [apps/storybook](apps/storybook/AGENTS.md) | Storybook app, native workflows, and diagnostics | ## Quick facts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8112f311799..471df8e079b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,7 +65,7 @@ package's [contributor instructions](./packages/agentic/components/AGENTS.md) an 1. A higher-order component starts with a reviewed contract: `SPEC.md` plus `spec/source.json`, `spec/tokens.yaml`, `spec/accessibility.md`, `spec/interaction.md`, and `spec/usage.md`. Follow - [SPEC-SOURCE.md](./packages/agentic/components/SPEC-SOURCE.md) for provenance, review state, and source adapters. + [the contracts reference](packages/agentic/components/references/contracts.md) for provenance, review state, and source adapters. 1. A primitive instead keeps a colocated `CONTRACT.md` that describes its public API and renderer branches. 1. Run `yarn workspace @fluentui-react-native/components check:spec-contracts` to validate the contract. @@ -77,7 +77,7 @@ A higher-order component uses these files, in dependency order: 1. `use.ts`: defaults, derived state, interaction, accessibility, and slot construction. 1. `.styles.ts` and `useStyles.ts`: token-based styles and slot style application. 1. `render.tsx`: pure slot rendering. Put `/** @jsxImportSource @fluentui-react-native/framework-base */` on - the first line of files that render slots; see `packages/framework-base/src/component-patterns/README.md`. + the first line of files that render slots; see `packages/framework-base/references/component-patterns.md`. 1. `.ts`: assembly and `displayName`. Expose the native root ref through the React 19 `ref` prop rather than `forwardRef`. Export the component and its public diff --git a/apps/E2E/README.md b/apps/E2E/README.md index 1703182121c..7d0a746363f 100644 --- a/apps/E2E/README.md +++ b/apps/E2E/README.md @@ -48,7 +48,7 @@ yarn workspace @fluentui-react-native/e2e-testing desktop-test --target macos te On October 22, 2026 (UTC), the macOS pilot and all 62 `legacy` tests pass on both Fabric and Paper, with no skips or retries. Fabric depends on the repository's RNmacOS Text accessibility patch, described in the -[native-core README](../../packages/agentic/native-core/README.md#repository-local-rnmacos-prerequisite-patch). +[native-core RNmacOS patch reference](../../packages/agentic/native-core/references/rnmacos-patch.md). Selected tester buttons are scrolled until their center is inside the list before clicking, because the native click targets that point. diff --git a/apps/E2E/tsconfig.json b/apps/E2E/tsconfig.json index 7bd00ba3fb7..ad3a600d662 100644 --- a/apps/E2E/tsconfig.json +++ b/apps/E2E/tsconfig.json @@ -5,7 +5,7 @@ "types": ["@types/jasmine", "@wdio/globals/types", "@wdio/jasmine-framework", "node"], "rootDir": "src", "composite": true, - "tsBuildInfoFile": ".cache/tsconfig.tsbuildinfo" + "tsBuildInfoFile": "node_modules/.cache/tsconfig.tsbuildinfo" }, "include": ["src"], "references": [ diff --git a/apps/bundle-size/targets/tsconfig.check.json b/apps/bundle-size/targets/tsconfig.check.json index 01ff1d1e878..69810f55237 100644 --- a/apps/bundle-size/targets/tsconfig.check.json +++ b/apps/bundle-size/targets/tsconfig.check.json @@ -8,7 +8,7 @@ "allowSyntheticDefaultImports": true, "target": "es2022", "composite": true, - "tsBuildInfoFile": "../.cache/tsconfig.tsbuildinfo" + "tsBuildInfoFile": "../node_modules/.cache/tsconfig.check.tsbuildinfo" }, "include": ["../scripts/**/*.mts"], "exclude": ["../node_modules", "../lib", "../dist"] diff --git a/apps/fluent-tester/tsconfig.json b/apps/fluent-tester/tsconfig.json index a66e1911e52..a8ff6d68f34 100644 --- a/apps/fluent-tester/tsconfig.json +++ b/apps/fluent-tester/tsconfig.json @@ -6,7 +6,7 @@ "types": ["@types/jasmine", "@wdio/globals/types", "@wdio/jasmine-framework", "node"], "rootDir": "src", "composite": true, - "tsBuildInfoFile": ".cache/tsconfig.tsbuildinfo" + "tsBuildInfoFile": "node_modules/.cache/tsconfig.tsbuildinfo" }, "include": ["src"], "references": [ diff --git a/apps/storybook/tsconfig.json b/apps/storybook/tsconfig.json index 7898b14c32e..71e3c3d41be 100644 --- a/apps/storybook/tsconfig.json +++ b/apps/storybook/tsconfig.json @@ -10,7 +10,7 @@ "esModuleInterop": true, "resolveJsonModule": true, "composite": true, - "tsBuildInfoFile": ".cache/tsconfig.tsbuildinfo" + "tsBuildInfoFile": "node_modules/.cache/tsconfig.tsbuildinfo" }, "include": ["index.js", "src", "app.json", "desktop.config.mts"], "exclude": ["node_modules", "dist", ".cache"], diff --git a/apps/tester-core/tsconfig.json b/apps/tester-core/tsconfig.json index ee6c375fcf5..0887c98a96e 100644 --- a/apps/tester-core/tsconfig.json +++ b/apps/tester-core/tsconfig.json @@ -6,7 +6,7 @@ "types": ["@types/jasmine", "@wdio/globals/types", "@wdio/jasmine-framework", "node"], "rootDir": "src", "composite": true, - "tsBuildInfoFile": ".cache/tsconfig.tsbuildinfo" + "tsBuildInfoFile": "node_modules/.cache/tsconfig.tsbuildinfo" }, "include": ["src"], "references": [ diff --git a/apps/win32-81/targets/tsconfig.check.json b/apps/win32-81/targets/tsconfig.check.json index 824fb07903d..d6368181f62 100644 --- a/apps/win32-81/targets/tsconfig.check.json +++ b/apps/win32-81/targets/tsconfig.check.json @@ -4,7 +4,7 @@ "rootDir": "..", "noEmit": true, "composite": true, - "tsBuildInfoFile": "../.cache/tsconfig.tsbuildinfo" + "tsBuildInfoFile": "../node_modules/.cache/tsconfig.check.tsbuildinfo" }, "include": ["../index.js", "../src"] } diff --git a/apps/win32/targets/tsconfig.check.json b/apps/win32/targets/tsconfig.check.json index 824fb07903d..d6368181f62 100644 --- a/apps/win32/targets/tsconfig.check.json +++ b/apps/win32/targets/tsconfig.check.json @@ -4,7 +4,7 @@ "rootDir": "..", "noEmit": true, "composite": true, - "tsBuildInfoFile": "../.cache/tsconfig.tsbuildinfo" + "tsBuildInfoFile": "../node_modules/.cache/tsconfig.check.tsbuildinfo" }, "include": ["../index.js", "../src"] } diff --git a/packages/agentic/components/AGENTS.md b/packages/agentic/components/AGENTS.md index da3456b3ac5..82b133f2ff8 100644 --- a/packages/agentic/components/AGENTS.md +++ b/packages/agentic/components/AGENTS.md @@ -1,66 +1,55 @@ -# Agentic Components authoring +# Agentic Components agent instructions -These instructions apply to `packages/agentic/components` and its descendants. Keep this file limited to durable package -invariants; detailed recipes live in the shared [agentic references](../../../references/agents/README.md), routed by -the [agentic component authoring skill](../../../.github/skills/agentic-component-authoring/SKILL.md). +This is the instruction root for `@fluentui-react-native/components` and every descendant. The package owns the agentic +Fluent higher-order components, the public unstyled primitives, their React Native contracts, and the contract tooling. -## Routing +## Start here -- Implementation and new components use the - [agentic component authoring skill](../../../.github/skills/agentic-component-authoring/SKILL.md); reviews use - [review-component](../../../.github/skills/review-component/SKILL.md). -- Higher-order components live in `src/components`; read [its instructions](src/components/AGENTS.md). -- Primitive components live in `src/primitives`; read [its instructions](src/primitives/AGENTS.md). -- Story files are library source and follow [tests and stories](../../../references/agents/components/agentic/tests-and-stories.md). - Executable tests are top-level `wdio` callbacks or maps of named callbacks typed with `import type` of `WdioStory` - from `storybook-desktop/testing`. Keep callbacks self-contained and dynamically import Node helpers inside them. - Each named case gets a fresh story, session, and worker. Use stable `testID` selectors and the injected `platform` - for real platform differences, with explicit skips for unsupported capabilities. Shared focus tests run on macOS, - Windows, and Win32; gate only genuinely platform-specific assertions. Legacy `parameters.desktopDriver` plans remain - only in runner compatibility fixtures. -- Focus work starts with the [common focus instructions](../../../references/agents/focus/common.md), - then the [Windows/Win32](../../../references/agents/focus/windows-win32.md) or - [macOS](../../../references/agents/focus/macos.md) detail. V1 Win32 is the - behavioral baseline for both Windows endpoints; renderer-specific plumbing remains separate. -- Storybook application, native project, Metro, bundle, or CocoaPods work follows the - [Storybook instructions](../../../apps/storybook/AGENTS.md) and the `agentic-storybook-development` skill. -- Native views, codegen, or registration follow the - [native component skill](../../../.github/skills/implement-native-component/SKILL.md); React Native Windows Fabric - views also follow the [Windows Fabric reference](../../../references/agents/native/windows-fabric.md). +Read the [user guide](README.md), then select the narrowest topic in the [reference index](references/README.md): -## Package invariants +| Task | Read | +| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| Add or change a higher-order component | [Higher-order components](references/higher-order-components.md), then the topic references | +| Add or change a public primitive | [Primitives](references/primitives.md) | +| Create or revise a component contract, its sources, or its review state | [Contracts](references/contracts.md) and the matching `references/contract-sources/` file | +| Public props, slots, refs, or exports | [Types and slots](references/types-and-slots.md) | +| State, interaction, or accessibility | [State and accessibility](references/state-and-accessibility.md) | +| Styles, tokens, theme caching, or state precedence | [Styles and tokens](references/styles-and-tokens.md) | +| Render functions and assembly | [Rendering and assembly](references/rendering.md) | +| Tests, stories, or native `wdio` story tests | [Tests and stories](references/tests-and-stories.md) | +| Shared helpers, dependencies, or cross-component extraction | [Source boundaries](references/source-boundaries.md) | +| Commands, source ownership, or open work | [Contributing](references/contributing.md) or [remaining work](references/remaining-work.md) | + +Implementation and planning use the `agentic-component-authoring` skill, contracts use the +`agentic-component-contract-authoring` skill, cross-component extraction uses the `agentic-component-optimization` +skill, and reviews use the `review-component` skill. Focus work starts with the repository's common focus reference +(`focus.common`), then `focus.windows-win32` or `focus.macos`; V1 Win32 is the behavioral baseline for both Windows +endpoints. Native views, codegen, or registration use the `implement-native-component` skill. Storybook application, +Metro, bundle, or CocoaPods work follows `apps/storybook/AGENTS.md`. + +## Invariants - **R-AGENTIC-001:** Before implementing a higher-order component whose contract is absent, stale, still a draft, or accompanied by new source evidence, create or revise its source-backed contract through the - [agentic component contract authoring skill](../../../.github/skills/agentic-component-contract-authoring/SKILL.md) - and complete its review gate. Never mechanically promote a web-authored specification. The skill routes Flex/X3, - Fluent v9, HTML/CSS, visual, local-foundation, and composite evidence. -- Use the repository's `flex-authoring` profile and `flex-components:` - only for a pinned Flex/X3 source. It is not a prerequisite for other source - adapters. -- A theme-aware foundational component that has no Flex catalog entry must use - a sole validator-backed `local-foundation` entry in `sources[]`. Cite its - public platform contract and repository evidence; never invent a - `flex-components:` skill or bypass the component contract gate. -- Follow [SPEC-SOURCE.md](./SPEC-SOURCE.md) for provenance fields, contract - lifecycle, review state, and drift commands. -- Read the component `SPEC.md`, `spec/source.json`, and all referenced React - Native companions before changing its contract. -- Use `src/components/button` as the canonical higher-order implementation and `src/primitives/icon` as the canonical - primitive. -- Keep public props and slots small, typed, and spec-driven. + `agentic-component-contract-authoring` skill and complete its review gate. Never mechanically promote a web-authored + specification. - **R-AGENTIC-002:** This package targets React 19.1.4 or newer. Expose a stable native root ref through the `ref` prop, receive it as part of the component props, and forward it to the declared root slot. Do not use `forwardRef`. -- Export higher-order components and public types explicitly from `src/index.ts`; export primitives and their public types - explicitly from `src/primitives/index.ts`. Never use wildcard exports (R-REPO-001). -- Colocate runtime tests, type tests, and Storybook stories with the implementation. -- Include every test-bearing story in `tsconfig.stories.json`. The representative - runner contract rejects legacy catalog plans and missing story type coverage. -- Node-only shared test helpers use `*.wdio.ts`, are excluded from production - emit, and are imported dynamically inside the stripped callbacks. -- Use package scripts for format, lint, build, tests, and snapshots. While iterating, run only the component's tests with - `yarn test `, and run the whole suite and `yarn lage buildci` once at the end (R-VALID-004). -- Do not copy web-only APIs, CSS behavior, or DOM assumptions into React Native. -- Do not copy or mechanically transform private source bodies into this public - package (R-REPO-004). Record source identifiers and digests, then author the local React - Native contract. +- Use the `flex-authoring` profile and `flex-components:` only for a pinned Flex/X3 source. A theme-aware + foundational component without a Flex catalog entry uses a sole validator-backed `local-foundation` source. +- Read the component `SPEC.md`, `spec/source.json`, and all referenced companions before changing its contract. +- Use `src/components/button` and `src/primitives/icon` as the canonical implementations, and keep public props and + slots small, typed, and contract-driven. +- Export higher-order components explicitly from `src/index.ts` and primitives from `src/primitives/index.ts`; never use + wildcard exports (R-REPO-001). +- Colocate runtime tests, type tests, and stories, include every test-bearing story in `tsconfig.stories.json`, and keep + Node-only story helpers in `*.wdio.ts` files imported dynamically inside callbacks. +- Do not copy web-only APIs, CSS behavior, or DOM assumptions into React Native, and do not copy or mechanically + transform private source bodies into this public package (R-REPO-004). +- Track open work only in [remaining work](references/remaining-work.md) (R-PKGDOC-009). + +## Validation + +Run `yarn format`, `yarn lint`, `yarn build`, and `yarn test` in this package, iterating with `yarn test `, +add a changeset, and finish with `yarn clean-lage-cache` followed by `yarn lage buildci`. See +[contributing](references/contributing.md#validation). diff --git a/packages/agentic/components/README.md b/packages/agentic/components/README.md new file mode 100644 index 00000000000..a727661c046 --- /dev/null +++ b/packages/agentic/components/README.md @@ -0,0 +1,46 @@ +# `@fluentui-react-native/components` + +Agentic Fluent UI React Native components for macOS, React Native Windows, and Office Win32. Each higher-order component +has an original React Native contract (`SPEC.md`), Flex token styling from `@fluentui-react-native/design`, native focus +and accessibility behavior, and colocated tests and stories. + +| Entry point | Contents | +| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| `@fluentui-react-native/components` | Higher-order components, public types, and component-qualified `_unstable` state, style, and render stages | +| `@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. + +## Quick start + +The package requires React 19.1.4. Render components inside a `ThemedRoot` from `@fluentui-react-native/design`, which +provides the theme and the scene's input modality: + +```tsx +import { ThemedRoot } from '@fluentui-react-native/design'; +import { Button } from '@fluentui-react-native/components'; + +export const App = () => ( + +