Components: Generate Toggle Button #4247

Summary

Deliver ToggleButton as an original reviewed React Native component contract, implementation, public export, and evidence-backed desktop behavior. Parent: #4273.

Current state - 2026-10-02 (UTC)

Observed: Audited against main at 75c55923873124201d2ffbf3b3e67960047bd481. There is no implemented/exported toggle-button component or colocated contract on main. This generation issue remains open.

Assessment: State-ownership decision confirmed; contract review can start.

Dependencies and next action

Button and useToggleState are implemented. The ownership gate in #4215 is resolved; remaining source/spec alignment is follow-through, not an undecided behavior prerequisite.

Start with the component's source-backed native contract review. A missing local contract is work to author, not a reason to wait for the completed #4252. Only the named unresolved component/host/product decisions above remain prerequisites; do not carry forward blanket overlay-wave or missing-Fabric blockers.

Component scope

• Confirmed (owner, 2026-10-01 PDT / 2026-10-02 UTC): Button may display selected or not-selected, but actual toggle behavior belongs to a distinct ToggleButton.
• Button keeps externally driven selected presentation and onPress; it must not gain defaultSelected/onSelectedChange or mutate selected during activation.
• ToggleButton owns selected/defaultSelected/onSelectedChange through useToggleState: omitted selected is uncontrolled, explicit false is controlled, and controlled activation requests a change without mutating the supplied value.
• Compose activation exactly once for pointer, keyboard, and native toggle accessibility actions; disabled activation changes nothing. Reuse shared focus/activation and resolveAccessibilityAction transport helpers.
• Preserve selected icon/weight treatment and stable label width. Do not silently remove existing Button selected/accessibility presentation compatibility.
• Shape and independent leading/trailing-icon alignment are separate review choices. Preserve existing Button APIs; do not make unrelated breaking changes or claim the owner approved them.

Ownership-specific acceptance

• Owner decision recorded: selected presentation may remain on Button; ToggleButton owns real controlled/uncontrolled toggle behavior.
• Button without selected, selected=false, and selected=true each retain their supplied presentation after press and invoke onPress only as documented.
• ToggleButton flips internal selection when uncontrolled, reports the requested next value when controlled, preserves explicit false, and invokes toggle/change/press handlers exactly once.
• Pointer, Enter/Space, and native toggle accessibility actions follow the same state owner; disabled activation is inert.
• Review both components' local contracts and source divergence dispositions, with migration guidance from V1 checked/defaultChecked where needed. Do not imply that posting this decision changed repository source.

Non-goals

Do not migrate legacy consumers, add mobile support, copy private/web source prose into the public package, or rewrite unrelated component APIs. Desktop V1 Win32/Windows/macOS behavior is compatibility evidence, not an iOS canonical baseline. Keep shared hosting, icons, and focus ownership in their named tasks.

Delivery and acceptance

• Author an original colocated SPEC.md and spec/ companions with schema-version-2 sources[], requirement IDs, source authority, and explicit native divergences; pass pre-code contract review before implementation.
• Implement the typed state/style/render/assembly stages, finite variant axes, optional slots, native root refs, user-prop/style forwarding, and explicit package exports covered by src/index.test.ts. Preserve React 19 ref props, shared focus policy, theme-only style caching, disabled-over-pressed-over-hovered precedence, and repository source boundaries.
• Add runtime and compile-time coverage for public API, every finite axis, optional content, accessibility, disabled state, constrained layout, and each controlled/uncontrolled or externally selected state path.
• Add representative and stress stories with top-level executable wdio cases. Use the delivered Storybook/native assertion infrastructure (Infrastructure: Add native accessibility assertions and Storybook test support #4255, Infrastructure: Add Storybook end-to-end test pipelines #4256); record actual Windows/macOS results and Win32 compatibility evidence, with capability skips stated rather than counted as passes.
• Run owning-workspace format, lint, build, and tests, plus Windows/macOS Storybook bundles; run the root build for changed public types/exports/manifests and add a changeset for package changes. Record a readiness level with its evidence under Components: Component tests for the agentic component library #4216 and Components: Component readiness model and initial assessment #4251.
• Merge the reviewed implementation before closing this generation issue. Source contracts, branch code, successful bundling, or a closed unmerged PR alone do not establish delivered readiness.

Contract review is normal phase-one work, not a missing-ingestion blocker. #4252 is complete; the old specs/<name>/blockers.md records are historical evidence, not live authoring inputs.

Current native qualification limits: #4342 tracks all-skipped WDIO selections being reported as passed; inspect executed cases rather than aggregate success. #4343, #4346, and #4347 retain full accessibility, native state projection, and focus-regression qualification. #4344 tracks native catalog crash exclusions, and #4349 tracks qualifying/promoting required CI. These are evidence/readiness gates, not a claim that delivered test infrastructure or every component behavior is missing.

Evidence

• packages/agentic/components/spec-source-lock.json and packages/agentic/components/SPEC-SOURCE.md.
• packages/agentic/components/src/components/AGENTS.md and packages/agentic/components/src/index.ts.
• Shared focus/activation work Fix desktop focus management and accessibility action handling #4314; native Fabric FocusZone focus-zone: start of fabric implementations for both macos and windows #4199 / Components: Complete the Fabric FocusZone for macOS and Windows #4217 and traversal repair Fix FocusZone Shift+Tab traversal from first-child containers #4320 / Possible FocusZone logic error #4317.

Evidence reflects this repository snapshot; the checked-in candidate drift report is dated 2026-08-31 and is not a fresh upstream audit.