@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/src/Resizable/useResizable.ts

@@ -306,6 +306,34 @@ const SERVER_BASIS = 1200;
 
 /** A store that never changes on its own; the snapshot is re-read on render. */
 const noopSubscribe = () => () => {};
+
+// The window snapshots are module functions, so their identity is stable:
+// React re-reads a snapshot after the commit whenever getSnapshot is a new
+// function, and a window size read after the DOM changed forces a layout of
+// the whole page. With these, the window is read during render only.
+
+/** The viewport width, the basis without a container. */
+function readViewportBasis(): number {
+  return typeof window === 'undefined' ? SERVER_BASIS : window.innerWidth;
+}
+
+function readServerBasis(): number {
+  return SERVER_BASIS;
+}
+
+/** The window's extent along a horizontal hook's axis. */
+function readWindowWidth(): number | null {
+  return typeof window === 'undefined' ? null : window.innerWidth;
+}
+
+/** The window's extent along a vertical hook's axis. */
+function readWindowHeight(): number | null {
+  return typeof window === 'undefined' ? null : window.innerHeight;
+}
+
+function readNoWindowExtent(): null {
+  return null;
+}
 const DEFAULT_SIZE_FALLBACK = 250;
 const RESIZABLE_SIZE_GUIDANCE =
   'Use a non-negative number of pixels, an exact "Npx" string, an exact ' +
@@ -698,8 +726,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   );
   const viewportBasis = useSyncExternalStore(
     subscribeToViewport,
-    () => (typeof window === 'undefined' ? SERVER_BASIS : window.innerWidth),
-    () => SERVER_BASIS,
+    readViewportBasis,
+    readServerBasis,
   );
 
   // The window's extent along the hook's axis, for the REPORTED maximum of an
@@ -710,13 +738,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   // (component:Resizable Performance and resources).
   const windowExtent = useSyncExternalStore(
     noopSubscribe,
-    () =>
-      typeof window === 'undefined'
-        ? null
-        : direction === 'vertical'
-          ? window.innerHeight
-          : window.innerWidth,
-    () => null,
+    direction === 'vertical' ? readWindowHeight : readWindowWidth,
+    readNoWindowExtent,
   );
 
   // With a container, its content box is the basis; without one, the released
@@ -742,10 +765,14 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   // otherwise move the bound under the pointer; the new basis applies once the
   // gesture ends.
   const gestureBasisRef = useRef<number | null>(null);
-  // Only forces the render that releases the frozen basis when a gesture ends.
+  // Only forces the render that ends a gesture: it releases the frozen basis,
+  // and its commit writes the size the gesture settled on.
   const [gestureTick, setGestureTick] = useState(0);
   void gestureTick;
   const basis = gestureBasisRef.current ?? liveBasis;
+  // The frozen basis also marks a gesture in flight, from `_onResizeStart`
+  // until `_onResizeEnd` or `_onResizeCancel`.
+  const isGestureActive = gestureBasisRef.current != null;
 
   const didWarnMinRef = useRef(false);
   const didWarnMaxRef = useRef(false);
@@ -922,15 +949,52 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
     }
   }, [resolvedMin, resolvedMax]);
 
+  // The size a gesture in flight has reached, for a region that unmounts
+  // before the gesture ends.
+  const pendingWriteRef = useRef<{
+    key: string;
+    state: PersistedResizableState;
+  } | null>(null);
+
   useEffect(() => {
+    // Synchronizes the `autoSaveId` entry in localStorage with the size.
     // Nothing is written while the basis is still the temporary stand-in. The
     // size on such a render is a placeholder, and persisting it overwrites the
     // real saved size with a value derived from a basis that was never real
     // (AST-010 Platform support, FR9).
-    if (autoSaveId && isBasisMeasured) {
-      persistState(autoSaveId, {size, isCollapsed});
+    if (!autoSaveId || !isBasisMeasured) {
+      pendingWriteRef.current = null;
+      return;
     }
-  }, [size, isCollapsed, autoSaveId, isBasisMeasured]);
+    // Nor while a gesture is in flight. A drag commits a new size on every
+    // pointer move, and each write reaches every other open document of the
+    // origin as a `storage` event.
+    if (isGestureActive) {
+      pendingWriteRef.current = {key: autoSaveId, state: {size, isCollapsed}};
+      return;
+    }
+    // A gesture's one write happens here, in the commit that applies its
+    // release, not in the handler that ended it: this render is the first to
+    // know the final size. A basis that changed mid-gesture applies only at
+    // the release and can re-clamp the size (AST-010 FR7), and a move the
+    // release arrived before renders together with it. The handler sees
+    // neither.
+    pendingWriteRef.current = null;
+    persistState(autoSaveId, {size, isCollapsed});
+  }, [size, isCollapsed, autoSaveId, isBasisMeasured, isGestureActive]);
+
+  // A region that unmounts mid-gesture never commits a release, so the size
+  // the gesture reached is written on the way out.
+  useEffect(
+    () => () => {
+      const pending = pendingWriteRef.current;
+      pendingWriteRef.current = null;
+      if (pending != null) {
+        persistState(pending.key, pending.state);
+      }
+    },
+    [],
+  );
 
   const collapse = useCallback(() => {
     // The already-collapsed guard keeps a repeated call from re-notifying a
@@ -1026,7 +1090,7 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   );
 
   // Releasing the frozen basis needs a render to apply whatever the basis
-  // became during the gesture.
+  // became during the gesture; that render's commit writes the final size.
   const releaseGestureBasis = useCallback(() => {
     if (gestureBasisRef.current != null) {
       gestureBasisRef.current = null;
@@ -1035,7 +1099,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   }, []);
 
   const onResizeEnd = useCallback(() => {
-    // Sizes are already committed during move; only the basis is held.
+    // Sizes are already committed during move; the basis is held, and the
+    // commit that releases it writes the final size to storage.
     releaseGestureBasis();
   }, [releaseGestureBasis]);
 
@@ -1043,7 +1108,8 @@ function useSingleResizable(config: UseResizableSingleConfig): ResizableRegion {
   // capture, a handle unmounted mid-drag — is still over. It does not signal a
   // resize end (that is #5297's contract, and the sizes were committed during
   // move anyway), but the basis it froze has to come back, or every later
-  // percentage bound stays pinned to the container size at grab time.
+  // percentage bound stays pinned to the container size at grab time, and the
+  // size it reached has to reach storage.
   const onResizeCancel = releaseGestureBasis;
 
   // The maximum a handle REPORTS (End uses only a configured maximum). A

package/src/SegmentedControl/SegmentedControl.spec.md

@@ -49,15 +49,15 @@ system_specs: [spec:AST-020, spec:AST-085]
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | None changes. SegmentedControl takes `label`, `value`, `onChange`, `size`, `layout`, `isDisabled`, `disabledMessage`, base props, and SegmentedControlItem children.                                                                                                                                                                                                                                                                           |
-| Behavior                | A `role="radiogroup"` named by `label` with one Tab stop; arrow keys, Home, and End move focus between enabled segments, wrap, and select the segment they land on. Tabbing in never changes the value.                                                                                                                                                                                                                                        |
-| End-user impact         | People switch between a few modes with one click or arrow press, and the control shrinks with its row by truncating labels. A disabled control without a reason drops out of the tab order.                                                                                                                                                                                                                                                    |
-| Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A disabled selected segment loses the Tab stop, a disabled control can have no Tab stop, a press while focused selects before any click, a caller `onFocus` or `onBlur` can cancel built-in focus behavior, a group reason describes only the radiogroup, caller handlers run while disabled, and a caller `aria-describedby` is dropped; all are listed under Current-state impact. |
-| Review checks           | Reject more than one Tab stop, a value change on Tab entry, arrows that land on a disabled segment, a control that overflows its container when segments have labels, or a selection while disabled.                                                                                                                                                                                                                                           |
-| Governing rules         | WAI-ARIA radio group pattern; `spec:AST-020` FR9, FR15, DEC-5; `spec:AST-085` FR1, FR2, FR5, FR7; `design:user-states` DR1–DR3 (through SegmentedControlItem); `design:bidirectionality` DR6; `architecture:component-size-cascade` INV3–INV5; `architecture:interaction-modality` INV1; `architecture:public-component-api` INV5, INV7.                                                                                                       |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | None changes. SegmentedControl takes `label`, `value`, `onChange`, `size`, `layout`, `isDisabled`, `disabledMessage`, base props, and SegmentedControlItem children.                                                                                                                                                                                                                             |
+| Behavior                | A `role="radiogroup"` named by `label` with one Tab stop; arrow keys, Home, and End move focus between enabled segments, wrap, and select the segment they land on. Tabbing in never changes the value.                                                                                                                                                                                          |
+| End-user impact         | People switch between a few modes with one click or arrow press, and the control shrinks with its row by truncating labels. A disabled control without a reason drops out of the tab order.                                                                                                                                                                                                      |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                                                            |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A disabled selected segment loses the Tab stop, a disabled control can have no Tab stop, a press while focused selects before any click, a caller `onFocus` or `onBlur` can cancel built-in focus behavior, caller handlers run while disabled, and a caller `aria-describedby` is dropped; all are listed under Current-state impact. |
+| Review checks           | Reject more than one Tab stop, a value change on Tab entry, arrows that land on a disabled segment, a control that overflows its container when segments have labels, or a selection while disabled.                                                                                                                                                                                             |
+| Governing rules         | WAI-ARIA radio group pattern; `spec:AST-020` FR9, FR15, DEC-5; `spec:AST-085` FR1, FR2, FR5, FR7; `design:user-states` DR1–DR3 (through SegmentedControlItem); `design:bidirectionality` DR6; `architecture:component-size-cascade` INV3–INV5; `architecture:interaction-modality` INV1; `architecture:public-component-api` INV5, INV7.                                                         |
 
 This table is a review projection; the body below is authoritative.
 
@@ -112,16 +112,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                                                      |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| FR1 | The radiogroup container carries the current `segmented-control` target with `data-size`, sets `aria-label` to `label`, and renders its supplied children.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source, docs, and tests                                            |
-| FR2 | The group is one Tab stop: the selected segment, or, when the value matches no segment, the first segment not disabled by its own `isDisabled` (in a disabled group that segment keeps the stop, FR7); a disabled selected segment MUST keep the Tab stop (`spec:AST-085` FR1). Implementation gap: when the selected segment is disabled, the first enabled segment takes the Tab stop; and once the stop has fallen back to the first enabled segment, selecting another segment by click or by `value` leaves the stop there, so Tab re-enters on an unchecked segment. ArrowLeft and ArrowRight move focus between enabled segments in the visual direction, flipping in right-to-left layouts (`design:bidirectionality` DR6), and wrap; Home and End jump to the ends; ArrowUp and ArrowDown do nothing. Disabled segments are skipped.                                                      | WAI-ARIA radio group pattern; current tests; `design:bidirectionality` DR6 |
-| FR3 | When arrow, Home, or End navigation moves focus to an enabled segment, that segment's value is passed to `onChange` if it differs. A pointer press MUST select only on a click whose lift lands inside the segment (`spec:AST-020` FR9, DEC-5). Implementation gap: while focus is already in the group, a pointer press on another segment moves focus there and selects before any click, so a press that slides off still selects. Focus entering the group from outside never changes the value.                                                                                                                                                                                                                                                                                                                                                                                               | WAI-ARIA radio group pattern; current tests; `spec:AST-020` FR9, DEC-5     |
-| FR4 | A caller `onKeyDown` runs before built-in navigation and can cancel it with `preventDefault()`; a caller `onFocus` runs before selection-follows-focus. On first keyboard focus an ephemeral hint naming the arrow keys appears at the focused segment and dismisses on the first arrow press, a timeout, or blur. Built-in focus behavior MUST NOT be cancellable except where the public API promises it (`architecture:public-component-api` INV7). Implementation gap: a caller `onFocus` that calls `preventDefault()` also cancels the hint, the Tab-stop sync, and selection-follows-focus, and a caller `onBlur` that does so cancels the hint's blur dismissal.                                                                                                                                                                                                                           | Current source and tests; `architecture:public-component-api` INV7         |
-| FR5 | `hug` sizes the control to its segments; when any segment shows a visible label, the control never exceeds its container and labelled segments shrink and truncate. A control of only icon-only segments keeps its size. `fill` stretches the control to its container and gives segments equal shares that can shrink and truncate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current tests                                                              |
-| FR6 | Size resolves from an explicit `size`, then the nearest size provider, then `md`, and reaches every segment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `architecture:component-size-cascade` INV3–INV5; current source            |
-| FR7 | `isDisabled` sets `aria-disabled` on the radiogroup, disables every segment, dims the control to half opacity, and blocks selection. The group MUST keep a Tab stop while disabled (`spec:AST-085` FR1, FR7). With `disabledMessage`, the selected segment stays the Tab stop, pointer events stay on, and a reason tooltip opens on hover and keyboard focus; the reason MUST describe the focusable segment (`spec:AST-085` FR5, FR7). Implementation gap: the reason describes only the radiogroup; caller handlers on the radiogroup, such as `onKeyDown`, still run while disabled (`spec:AST-085` FR2); without a `disabledMessage` the group ignores pointer input and every segment leaves the tab order, so the control has no Tab stop; and with a `disabledMessage`, the control also has no Tab stop when the value matches no segment or the selected segment is itself `isDisabled`. | `spec:AST-085`; current tests                                              |
-| FR8 | The radiogroup owns `role`, `aria-label` (from `label`), `aria-disabled`, and `data-size`; a caller value for any of them is replaced. Other base props reach the radiogroup, and `ref` reaches it. Implementation gap: a caller `aria-describedby` is replaced, by the disabled-reason id or by nothing, against `architecture:public-component-api` INV5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `architecture:public-component-api` INV5; current source and tests         |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                                                                      |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| FR1 | The radiogroup container carries the current `segmented-control` target with `data-size`, sets `aria-label` to `label`, and renders its supplied children.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source, docs, and tests                                            |
+| FR2 | The group is one Tab stop: the selected segment, or, when the value matches no segment, the first segment not disabled by its own `isDisabled` (in a disabled group that segment keeps the stop, FR7); a disabled selected segment MUST keep the Tab stop (`spec:AST-085` FR1). Implementation gap: when the selected segment is disabled, the first enabled segment takes the Tab stop; and once the stop has fallen back to the first enabled segment, selecting another segment by click or by `value` leaves the stop there, so Tab re-enters on an unchecked segment. ArrowLeft and ArrowRight move focus between enabled segments in the visual direction, flipping in right-to-left layouts (`design:bidirectionality` DR6), and wrap; Home and End jump to the ends; ArrowUp and ArrowDown do nothing. Disabled segments are skipped. | WAI-ARIA radio group pattern; current tests; `design:bidirectionality` DR6 |
+| FR3 | When arrow, Home, or End navigation moves focus to an enabled segment, that segment's value is passed to `onChange` if it differs. A pointer press MUST select only on a click whose lift lands inside the segment (`spec:AST-020` FR9, DEC-5). Implementation gap: while focus is already in the group, a pointer press on another segment moves focus there and selects before any click, so a press that slides off still selects. Focus entering the group from outside never changes the value.                                                                                                                                                                                                                                                                                                                                          | WAI-ARIA radio group pattern; current tests; `spec:AST-020` FR9, DEC-5     |
+| FR4 | A caller `onKeyDown` runs before built-in navigation and can cancel it with `preventDefault()`; a caller `onFocus` runs before selection-follows-focus. On first keyboard focus an ephemeral hint naming the arrow keys appears at the focused segment and dismisses on the first arrow press, a timeout, or blur. Built-in focus behavior MUST NOT be cancellable except where the public API promises it (`architecture:public-component-api` INV7). Implementation gap: a caller `onFocus` that calls `preventDefault()` also cancels the hint, the Tab-stop sync, and selection-follows-focus, and a caller `onBlur` that does so cancels the hint's blur dismissal.                                                                                                                                                                      | Current source and tests; `architecture:public-component-api` INV7         |
+| FR5 | `hug` sizes the control to its segments; when any segment shows a visible label, the control never exceeds its container and labelled segments shrink and truncate. A control of only icon-only segments keeps its size. `fill` stretches the control to its container and gives segments equal shares that can shrink and truncate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current tests                                                              |
+| FR6 | Size resolves from an explicit `size`, then the nearest size provider, then `md`, and reaches every segment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `architecture:component-size-cascade` INV3–INV5; current source            |
+| FR7 | `isDisabled` sets `aria-disabled` on the radiogroup, disables every segment, dims the control to half opacity, and blocks selection. The group MUST keep a Tab stop while disabled (`spec:AST-085` FR1, FR7). With `disabledMessage`, the selected segment stays the Tab stop, pointer events stay on, and a reason tooltip opens on hover and keyboard focus; the reason MUST describe the focusable segment (`spec:AST-085` FR5, FR7). Implementation gap: caller handlers on the radiogroup, such as `onKeyDown`, still run while disabled (`spec:AST-085` FR2); and without a `disabledMessage` the group ignores pointer input and every segment leaves the tab order, so the control has no Tab stop.                                                                                                                                   | `spec:AST-085`; current tests                                              |
+| FR8 | The radiogroup owns `role`, `aria-label` (from `label`), `aria-disabled`, and `data-size`; a caller value for any of them is replaced. Other base props reach the radiogroup, and `ref` reaches it. Implementation gap: a caller `aria-describedby` is replaced, by the disabled-reason id or by nothing, against `architecture:public-component-api` INV5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `architecture:public-component-api` INV5; current source and tests         |
 
 ### Allowed variation
 
@@ -149,8 +149,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 - **ORD2 — Tab stop.** The selected segment; for a value that matches no
   segment, the first segment not disabled by its own `isDisabled`. Today a
   disabled selected segment keeps the stop only in a group disabled with a
-  reason when it is not itself `isDisabled`, and a fallen-back stop stays on
-  the first enabled segment after another segment is selected (FR2, FR7 gaps).
+  reason, and a fallen-back stop stays on the first enabled segment after
+  another segment is selected (FR2, FR7 gaps).
 
 ### Performance and resources
 
@@ -206,27 +206,26 @@ segment parts as well.
 
 ## Verification map
 
-| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                      | Representative states                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                            | Audit section                          |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
-| FR1, AR1            | `SegmentedControl.test.tsx` rendering, size, and data-testid cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-*` states                                                                                                                                                                       | Control with several segments; sizes                                    | Lost group semantics or name fails. Evidence gap: no test asserts the `segmented-control` target or `data-size`.                                                                                                                                                                                                                                                                                                                           | `audit:SegmentedControl/anatomy`       |
-| FR2, FR3, ORD2, AR2 | `SegmentedControl.test.tsx` keyboard-navigation and unmatched-value cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-*` states; the radio-group pattern's aborted-press check on `segmented-option-unselected`; the `segmented-group-selected-rtl` state's arrow round trip under `dir="rtl"` | Arrows, wrap, Home, End; Tab-in with an unmatched or disabled selection | A value change on Tab entry, no wrap, or landing on a disabled segment fails. A press that slides off with focus outside the group and still selects fails. Evidence gap: no test covers a slide-off press while focus is already in the group. No test selects another segment after the stop has fallen back.                                                                                                                            | `audit:SegmentedControl/accessibility` |
-| FR4, ORD1           | `SegmentedControl.test.tsx` container handler forwarding cases                                                                                                                                                                                                                                                                                                    | Caller `onKeyDown`, with and without `preventDefault`                   | A caller key handler that cannot cancel navigation fails. Evidence gap: no test asserts the caller `onFocus` order or the keyboard hint.                                                                                                                                                                                                                                                                                                   | `audit:SegmentedControl/behavior`      |
-| FR5                 | `SegmentedControl.test.tsx` layout cases                                                                                                                                                                                                                                                                                                                          | Hug, fill, narrow row, icon-only                                        | A control that overflows, or squeezes icon-only segments, fails.                                                                                                                                                                                                                                                                                                                                                                           | `audit:SegmentedControl/layout`        |
-| FR6                 | Evidence gap: no test asserts size precedence or its propagation                                                                                                                                                                                                                                                                                                  | —                                                                       | —                                                                                                                                                                                                                                                                                                                                                                                                                                          | `audit:SegmentedControl/layout`        |
-| FR7, AR3            | `SegmentedControl.test.tsx` disabled and disabledMessage cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-disabled` and `segmented-group-disabled-with-message` states                                                                                                                        | Group and item disabled; with reason                                    | A selection while disabled, or a missing reason tooltip, fails. Evidence gap: no test asserts the half opacity, or caller handlers while disabled. The `segmented-group-disabled` state declares `tabReachable: false`, asserting the current FR7 gap pending conformance. The `segmented-option-group-disabled-with-message` state declares no description on the focusable segment, asserting the reason-target gap pending conformance. | `audit:SegmentedControl/accessibility` |
-| FR8                 | `SegmentedControl.test.tsx` role-override and data-testid cases                                                                                                                                                                                                                                                                                                   | Forwarded role                                                          | A forwarded prop that overrides the role fails. Evidence gap: no test asserts `ref` or a caller `aria-describedby`.                                                                                                                                                                                                                                                                                                                        | `audit:SegmentedControl/api`           |
-| PR1                 | Evidence gap: no test asserts the absence of global listeners                                                                                                                                                                                                                                                                                                     | —                                                                       | —                                                                                                                                                                                                                                                                                                                                                                                                                                          | `audit:SegmentedControl/behavior`      |
-| Target inventory    | `packages/core/src/theme/themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                  | Control and item targets                                                | A rendered class absent from the documented targets fails.                                                                                                                                                                                                                                                                                                                                                                                 | `audit:SegmentedControl/theming`       |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                     | Canonical anatomy and both current targets                              | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                                    | `audit:SegmentedControl/theming`       |
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                      | Representative states                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                 | Audit section                          |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| FR1, AR1            | `SegmentedControl.test.tsx` rendering, size, and data-testid cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-*` states                                                                                                                                                                       | Control with several segments; sizes                                    | Lost group semantics or name fails. Evidence gap: no test asserts the `segmented-control` target or `data-size`.                                                                                                                                                                                                | `audit:SegmentedControl/anatomy`       |
+| FR2, FR3, ORD2, AR2 | `SegmentedControl.test.tsx` keyboard-navigation and unmatched-value cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-*` states; the radio-group pattern's aborted-press check on `segmented-option-unselected`; the `segmented-group-selected-rtl` state's arrow round trip under `dir="rtl"` | Arrows, wrap, Home, End; Tab-in with an unmatched or disabled selection | A value change on Tab entry, no wrap, or landing on a disabled segment fails. A press that slides off with focus outside the group and still selects fails. Evidence gap: no test covers a slide-off press while focus is already in the group. No test selects another segment after the stop has fallen back. | `audit:SegmentedControl/accessibility` |
+| FR4, ORD1           | `SegmentedControl.test.tsx` container handler forwarding cases                                                                                                                                                                                                                                                                                                    | Caller `onKeyDown`, with and without `preventDefault`                   | A caller key handler that cannot cancel navigation fails. Evidence gap: no test asserts the caller `onFocus` order or the keyboard hint.                                                                                                                                                                        | `audit:SegmentedControl/behavior`      |
+| FR5                 | `SegmentedControl.test.tsx` layout cases                                                                                                                                                                                                                                                                                                                          | Hug, fill, narrow row, icon-only                                        | A control that overflows, or squeezes icon-only segments, fails.                                                                                                                                                                                                                                                | `audit:SegmentedControl/layout`        |
+| FR6                 | Evidence gap: no test asserts size precedence or its propagation                                                                                                                                                                                                                                                                                                  | —                                                                       | —                                                                                                                                                                                                                                                                                                               | `audit:SegmentedControl/layout`        |
+| FR7, AR3            | `SegmentedControl.test.tsx` disabled and disabledMessage cases; `RadioGroup.a11y.test.tsx` and `RadioGroup.a11y.chromium.spec.ts` (in `RadioList/__tests__`) `segmented-group-disabled` and `segmented-group-disabled-with-message` states                                                                                                                        | Group and item disabled; with reason                                    | A selection while disabled, or a missing reason tooltip, fails. Evidence gap: no test asserts the half opacity, or caller handlers while disabled. The `segmented-group-disabled` state declares `tabReachable: false`, asserting the current FR7 gap pending conformance.                                      | `audit:SegmentedControl/accessibility` |
+| FR8                 | `SegmentedControl.test.tsx` role-override and data-testid cases                                                                                                                                                                                                                                                                                                   | Forwarded role                                                          | A forwarded prop that overrides the role fails. Evidence gap: no test asserts `ref` or a caller `aria-describedby`.                                                                                                                                                                                             | `audit:SegmentedControl/api`           |
+| PR1                 | Evidence gap: no test asserts the absence of global listeners                                                                                                                                                                                                                                                                                                     | —                                                                       | —                                                                                                                                                                                                                                                                                                               | `audit:SegmentedControl/behavior`      |
+| Target inventory    | `packages/core/src/theme/themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                  | Control and item targets                                                | A rendered class absent from the documented targets fails.                                                                                                                                                                                                                                                      | `audit:SegmentedControl/theming`       |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                     | Canonical anatomy and both current targets                              | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                                                                                                                                                                         | `audit:SegmentedControl/theming`       |
 
 ## Current-state impact
 
 - **Disabled Tab stop (FR7).** A control disabled without a reason has no Tab
   stop, against `spec:AST-085` FR1 and FR7.
-- **Disabled selected Tab stop (FR2, FR7).** A disabled selected segment
-  loses the Tab stop to the first enabled segment, and a control disabled with
-  a reason has no Tab stop when its value matches no segment or its selected
-  segment is itself disabled, against `spec:AST-085` FR1.
+- **Disabled selected Tab stop (FR2).** Outside a group disabled with a
+  reason, a disabled selected segment loses the Tab stop to the first enabled
+  segment, against `spec:AST-085` FR1.
 - **Stale fallback Tab stop (FR2).** After the Tab stop falls back to the
   first enabled segment, selecting another segment by click or by `value`
   leaves the stop there, so Tab re-enters on an unchecked segment.
@@ -236,8 +235,6 @@ segment parts as well.
 - **Focus handler cancellation (FR4).** A caller `onFocus` or `onBlur` that
   calls `preventDefault()` cancels built-in focus behavior the public API does
   not promise to expose, against `architecture:public-component-api` INV7.
-- **Group reason (FR7).** A group `disabledMessage` describes only the
-  radiogroup, not the focusable segment, against `spec:AST-085` FR5 and FR7.
 - **Caller handlers while disabled (FR7).** Caller handlers on the radiogroup,
   such as `onKeyDown`, still run while disabled, against `spec:AST-085` FR2.
 - **Caller description (FR8).** A caller `aria-describedby` on the control is

package/src/SegmentedControl/SegmentedControl.tsx

@@ -19,7 +19,8 @@ import React, {useMemo, useCallback, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars, radiusVars} from '../theme/tokens.stylex';
 import {SegmentedControlContext} from './SegmentedControlContext';
-import {useListFocus} from '../hooks/useListFocus';
+import {useInternalListFocus} from '../hooks/useListFocus';
+import {isSegmentDisabledOnItsOwn} from '../privateAttributes/segmentDisabled.stylex';
 import {useKeyboardHint} from '../hooks/useKeyboardHint';
 import {useTooltip} from '../Tooltip';
 import type {
@@ -198,12 +199,17 @@ export function SegmentedControl({
   // the radios, skips disabled ones, wraps at the ends, handles Home/End, and
   // repairs the tab stop on mount and whenever items mount/disable — replacing
   // the component's former inline keyboard handler and tab-stop repair effect.
-  const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
-    itemSelector: '[role="radio"]:not([aria-disabled="true"])',
-    hasRovingTabIndex: true,
-    wrap: true,
-    orientation: 'horizontal',
-  });
+  const {listRef, handleKeyDown, handleFocus} =
+    useInternalListFocus<HTMLDivElement>({
+      itemSelector: '[role="radio"]:not([aria-disabled="true"])',
+      hasRovingTabIndex: true,
+      // Disabled with a reason, the control keeps one Tab stop so the reason is
+      // reachable (FR2, FR7): the selected segment, else the first segment not
+      // disabled by its own isDisabled, else the first.
+      disabledTabStop: showsDisabledMessage ? orderDisabledTabStop : undefined,
+      wrap: true,
+      orientation: 'horizontal',
+    });
 
   const hint = useKeyboardHint({
     orientation: 'horizontal',
@@ -271,8 +277,19 @@ export function SegmentedControl({
       layout,
       isDisabled,
       hasDisabledMessage: showsDisabledMessage,
+      disabledReasonID: showsDisabledMessage
+        ? disabledMessageTooltip.describedBy
+        : undefined,
     }),
-    [value, onChange, size, layout, isDisabled, showsDisabledMessage],
+    [
+      value,
+      onChange,
+      size,
+      layout,
+      isDisabled,
+      showsDisabledMessage,
+      disabledMessageTooltip.describedBy,
+    ],
   );
 
   return (
@@ -316,3 +333,21 @@ export function SegmentedControl({
 }
 
 SegmentedControl.displayName = 'SegmentedControl';
+
+/**
+ * The segments of a control disabled with a reason, its Tab stop first: the
+ * selected segment, else the first segment not disabled by its own
+ * isDisabled, else the first (FR2, FR7).
+ */
+function orderDisabledTabStop(list: HTMLElement): ReadonlyArray<HTMLElement> {
+  const segments = Array.from(
+    list.querySelectorAll<HTMLElement>('[role="radio"]'),
+  );
+  const stop =
+    segments.find(segment => segment.getAttribute('aria-checked') === 'true') ??
+    segments.find(segment => !isSegmentDisabledOnItsOwn(segment)) ??
+    segments[0];
+  return stop == null
+    ? []
+    : [stop, ...segments.filter(segment => segment !== stop)];
+}

package/src/SegmentedControl/SegmentedControlContext.ts

@@ -30,6 +30,12 @@ export interface SegmentedControlContextValue {
    * tooltip is keyboard-discoverable; selection is still blocked.
    */
   hasDisabledMessage?: boolean;
+  /**
+   * The id of the group's disabled-reason tooltip while `hasDisabledMessage`
+   * is true. It also describes each segment, so the segment that has focus is
+   * described by the reason (spec:AST-085 FR5).
+   */
+  disabledReasonID?: string;
 }
 
 export const SegmentedControlContext =

package/src/SegmentedControl/SegmentedControlItem.spec.md

@@ -108,7 +108,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | FR1 | Each segment renders one `<button type="button" role="radio">` with `aria-checked` true when its `value` equals the group value, `data-value`, and the `segmented-control-item` target reflecting `data-size`, `data-selected`, and `data-disabled`. A forwarded prop cannot override the role.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | WAI-ARIA radio pattern; current source and tests                             |
 | FR2 | A click, including one from Space or Enter on the focused segment (native button activation; `spec:AST-020` FR15), runs the caller `onClick` first; unless it prevents default, an enabled, unselected segment passes its value to the group's `onChange`. Clicking the selected segment does nothing. The caller's `preventDefault()` MUST veto every press. Implementation gap: a press while focus is already in the group selects through `component:SegmentedControl` FR3 before the click, so the veto does not apply to it.                                                                                                                                                                                                                                                            | `spec:AST-020` FR15; current tests                                           |
 | FR3 | The segment renders its icon (sized to the segment size) followed by its label. With `isLabelHidden`, the label is not rendered and becomes `aria-label`, and the segment does not shrink. A visible label truncates with an ellipsis when the segment is narrower than it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current tests                                                                |
-| FR4 | A segment disabled by its own `isDisabled` or by the group sets `aria-disabled`, refuses selection, shows disabled text color, and shows no hover or press paint. A disabled selected segment MUST keep the Tab stop (`spec:AST-085` FR1); for a value that matches no segment, `component:SegmentedControl` FR2 places the stop. Implementation gap: a disabled selected segment leaves the tab order, except in a group disabled with a reason when it is not itself `isDisabled`, and a caller `onClick` still runs on a disabled segment (`spec:AST-085` FR2).                                                                                                                                                                                                                            | `spec:AST-085` FR1, FR2; current tests                                       |
+| FR4 | A segment disabled by its own `isDisabled` or by the group sets `aria-disabled`, refuses selection, shows disabled text color, and shows no hover or press paint. A disabled selected segment MUST keep the Tab stop (`spec:AST-085` FR1); for a value that matches no segment, `component:SegmentedControl` FR2 places the stop. Implementation gap: a disabled selected segment leaves the tab order, except in a group disabled with a reason, and a caller `onClick` still runs on a disabled segment (`spec:AST-085` FR2).                                                                                                                                                                                                                                                               | `spec:AST-085` FR1, FR2; current tests                                       |
 | FR5 | The selected segment paints a raised surface with a low shadow and semibold primary text; under forced colors it paints `Highlight` with `HighlightText`. Unselected enabled segments paint the shared hover tint and, under `design:user-states` DR1 and DR2, the pressed overlay; the selected segment keeps its raised surface during a press (DR3).                                                                                                                                                                                                                                                                                                                                                                                                                                       | WCAG 1.4.11; `design:user-states` DR1–DR3; current tests                     |
 | FR6 | Segment height is the element height for the size minus 4 CSS px (24, 28, or 32) as a minimum that grows with a set text size under `spec:AST-102` FR4 (implementation gap: the height is fixed), with corners concentric with the control; `sm` uses supporting text and tighter padding. Keyboard focus paints the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `architecture:interaction-modality` INV1; current source; `spec:AST-102` FR4 |
 | FR7 | The segment owns `role`, `aria-checked`, `aria-disabled`, `aria-label` (set from the label when hidden), `tabIndex`, `type`, `data-value`, and `data-size`, and writes `data-selected`, `data-disabled`, and the press marker `data-astryx-pressable` in their own states; a caller value for an owned attribute is replaced, while a caller `data-selected`, `data-disabled`, or `data-astryx-pressable` passes through on segments outside that state. `ref`, other `data-*`, `style`, other ARIA such as `aria-describedby`, and other base props reach the button; `xstyle` composes last. Caller `className` MUST compose with the component's classes (`architecture:public-component-api` INV5, INV6). Implementation gap: the component's merged class replaces a caller `className`. | `architecture:public-component-api` INV5, INV6; current tests                |

package/src/SegmentedControl/SegmentedControlItem.tsx

@@ -16,6 +16,8 @@
  */
 
 import React, {type ReactNode} from 'react';
+import {joinAriaIDs} from '../utils/inputAria';
+import {segmentDisabledProps} from '../privateAttributes/segmentDisabled.stylex';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -192,6 +194,7 @@ export function SegmentedControlItem({
   isDisabled = false,
   onClick: onClickProp,
   xstyle,
+  'aria-describedby': ariaDescribedByProp,
   ...rest
 }: SegmentedControlItemProps) {
   const pressable = usePressFeedback();
@@ -203,18 +206,27 @@ export function SegmentedControlItem({
   // segment focusable so the group's reason tooltip is keyboard-discoverable.
   // Per-item disabling (`isDisabled` on the item) always drops out of the tab
   // order. Activation stays blocked by the isItemDisabled guard in handleClick.
+  // Disabled with a reason, the selected segment keeps the Tab stop even when
+  // it is itself disabled (FR4); with no selected segment, the group places
+  // the stop (SegmentedControl FR2).
   const keepsSelectedFocusable =
-    isSelected && (ctx.hasDisabledMessage ?? false) && !isDisabled;
+    isSelected && (ctx.hasDisabledMessage ?? false);
   const size: SegmentedControlSize = ctx.size;
   const isFill = ctx.layout === 'fill';
 
   // Consumer-first: a consumer onClick can call preventDefault() to opt out of
   // selection; otherwise selection proceeds when enabled and not selected.
-  const handleClick = composeEventHandlers(onClickProp, () => {
-    if (!isItemDisabled && !isSelected) {
-      ctx.onChange(value);
-    }
-  });
+  // A disabled segment invokes no caller callback (spec:AST-085 FR2), so the
+  // consumer onClick is left out while it is disabled, including the selected
+  // segment of a group disabled with a reason, which stays focusable.
+  const handleClick = composeEventHandlers(
+    isItemDisabled ? undefined : onClickProp,
+    () => {
+      if (!isItemDisabled && !isSelected) {
+        ctx.onChange(value);
+      }
+    },
+  );
 
   const iconElement = icon ? (
     <span {...stylex.props(styles.icon, iconSizeStyles[size])}>{icon}</span>
@@ -229,7 +241,12 @@ export function SegmentedControlItem({
       aria-checked={isSelected}
       aria-disabled={isItemDisabled || undefined}
       aria-label={isLabelHidden ? label : undefined}
+      // A caller description, then the group's disabled reason, which
+      // describes each segment (FR7).
+      aria-describedby={joinAriaIDs(ariaDescribedByProp, ctx.disabledReasonID)}
       data-value={value}
+      // The group's fallback Tab stop skips segments disabled on their own.
+      {...segmentDisabledProps(isDisabled)}
       {...(!isSelected && !isItemDisabled ? pressable : undefined)}
       // Disabled items (including when the whole group is disabled) are not tab
       // stops — otherwise the selected segment stays keyboard-focusable but is

package/src/Selector/Selector.tsx

@@ -42,7 +42,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {Divider} from '../Divider';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
@@ -89,6 +88,7 @@ import {
 } from '../Field/fieldParts';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
@@ -104,6 +104,7 @@ import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
 import {SelectorBottomSheet} from './SelectorBottomSheet';
 import {useSelectorPresentation} from './useSelectorPresentation';
 import {selectorPresentationStyles} from './selectorPresentation.stylex';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 
 const styles = stylex.create({
   // Trigger container — the enhanced click target wrapping the combobox button and clear button as siblings
@@ -726,7 +727,7 @@ interface SelectorPropsBase<
    * - 'tooltip': message is exposed from the on-field status icon
    * @default 'attached' for input selectors; 'detached' for secondary/ghost selectors
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -1038,8 +1039,10 @@ export function Selector<T extends SelectorOptionType>(
   // shorter inner button makes every size's selected row land too low.
   const anchorRef = useRef<HTMLDivElement>(null);
   const triggerRef = useRef<HTMLElement>(null);
+  const triggerModality = useInteractionModalityTracking();
   const triggerButtonRef = useMergedRefs<HTMLButtonElement>(
     triggerRef as React.Ref<HTMLButtonElement>,
+    triggerModality.ref,
     ref,
   );
   const searchRef = useRef<HTMLInputElement>(null);
@@ -1060,11 +1063,9 @@ export function Selector<T extends SelectorOptionType>(
   useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);
   const announce = useAnnounce();
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the trigger container (which already exists)
-  // and the trigger button stays perceivable via aria-disabled instead of the
-  // disabled attribute. Activation is blocked by the isDisabled guards in
-  // useCombobox (onTriggerClick / onKeyDown).
+  // Disabled-reason tooltip. The container receives hover and bubbled focus
+  // while the trigger stays focusable via aria-disabled. Opening and selection
+  // are guarded independently, including options in an already-open surface.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -1183,6 +1184,7 @@ export function Selector<T extends SelectorOptionType>(
     onHide: handleLayerHide,
     onShow: handleLayerShow,
     triggerRef,
+    triggerModality,
     popoverOptions: {
       hasLightDismiss: true,
       hasCloseButton: false,
@@ -1327,6 +1329,11 @@ export function Selector<T extends SelectorOptionType>(
 
   const commitValue = useCallback(
     (newValue: string) => {
+      // A surface or pointer gesture can outlive the enabled state that opened
+      // it. Enforce current availability before callbacks or optimistic state.
+      if (isDisabled || isEffectivelyReadOnly) {
+        return;
+      }
       onChange?.(newValue);
       if (changeAction) {
         startTransition(async () => {
@@ -1335,7 +1342,14 @@ export function Selector<T extends SelectorOptionType>(
         });
       }
     },
-    [onChange, changeAction, startTransition, setOptimisticValue],
+    [
+      isDisabled,
+      isEffectivelyReadOnly,
+      onChange,
+      changeAction,
+      startTransition,
+      setOptimisticValue,
+    ],
   );
 
   // Selector behavior (keyboard nav, selection)