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

package/dist/Resizable/useResizable.js

@@ -126,6 +126,32 @@ 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() {
+  return typeof window === 'undefined' ? SERVER_BASIS : window.innerWidth;
+}
+function readServerBasis() {
+  return SERVER_BASIS;
+}
+
+/** The window's extent along a horizontal hook's axis. */
+function readWindowWidth() {
+  return typeof window === 'undefined' ? null : window.innerWidth;
+}
+
+/** The window's extent along a vertical hook's axis. */
+function readWindowHeight() {
+  return typeof window === 'undefined' ? null : window.innerHeight;
+}
+function readNoWindowExtent() {
+  return null;
+}
 const DEFAULT_SIZE_FALLBACK = 250;
 const RESIZABLE_SIZE_GUIDANCE = 'Use a non-negative number of pixels, an exact "Npx" string, an exact ' + '"N%" string from 0% to 100%, pixel(value), or ' + 'percent(value, {min: pixel(value)}) / percent(value, {max: pixel(value)}).';
 
@@ -432,7 +458,7 @@ function useSingleResizable(config) {
     window.addEventListener('resize', onStoreChange);
     return () => window.removeEventListener('resize', onStoreChange);
   }, [hasContainer, observeViewportBasis]);
-  const viewportBasis = useSyncExternalStore(subscribeToViewport, () => typeof window === 'undefined' ? SERVER_BASIS : window.innerWidth, () => SERVER_BASIS);
+  const viewportBasis = useSyncExternalStore(subscribeToViewport, readViewportBasis, readServerBasis);
 
   // The window's extent along the hook's axis, for the REPORTED maximum of an
   // unbounded region (never for clamping). Read through the same store shape
@@ -440,7 +466,7 @@ function useSingleResizable(config) {
   // one on the first client render, instead of a hydration mismatch. It takes
   // no resize subscription: an unbounded pixel region observes nothing
   // (component:Resizable Performance and resources).
-  const windowExtent = useSyncExternalStore(noopSubscribe, () => typeof window === 'undefined' ? null : direction === 'vertical' ? window.innerHeight : window.innerWidth, () => null);
+  const windowExtent = useSyncExternalStore(noopSubscribe, direction === 'vertical' ? readWindowHeight : readWindowWidth, readNoWindowExtent);
 
   // With a container, its content box is the basis; without one, the released
   // viewport basis. Before a supplied container has been measured — the first
@@ -461,10 +487,14 @@ function useSingleResizable(config) {
   // otherwise move the bound under the pointer; the new basis applies once the
   // gesture ends.
   const gestureBasisRef = useRef(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);
   const didWarnDefaultRef = useRef(false);
@@ -582,18 +612,55 @@ function useSingleResizable(config) {
       devWarn('useResizable', `the resolved minimum (${resolvedMin}px) is above the resolved ` + `maximum (${resolvedMax}px). The maximum wins, as it always has.`);
     }
   }, [resolvedMin, resolvedMax]);
+
+  // The size a gesture in flight has reached, for a region that unmounts
+  // before the gesture ends.
+  const pendingWriteRef = useRef(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;
+    }
+    // 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;
     }
-  }, [size, isCollapsed, autoSaveId, isBasisMeasured]);
+    // 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
     // transition that already happened.
@@ -657,7 +724,7 @@ function useSingleResizable(config) {
   }, [collapsible, collapsedSize, setCollapsed, resolvedMin, resolvedMax, snaps, onSizeChange, onCollapseChange]);
 
   // 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;
@@ -665,7 +732,8 @@ function useSingleResizable(config) {
     }
   }, []);
   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]);
 
@@ -673,7 +741,8 @@ function useSingleResizable(config) {
   // 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/dist/SegmentedControl/SegmentedControl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SegmentedControl.d.ts","sourceRoot":"","sources":["../../src/SegmentedControl/SegmentedControl.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAAuB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAOlE,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,2BAA2B,CAAC;AAInC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CACjD,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,CACX;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AA8DD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,GAAG,EACH,KAAK,EACL,QAAQ,EACR,KAAK,EACL,IAAI,EAAE,QAAQ,EACd,MAAc,EACd,UAAkB,EAClB,eAAe,EACf,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,UAAU,EAClB,kBAAkB,EAAE,mBAAmB,EACvC,GAAG,IAAI,EACR,EAAE,qBAAqB,qBAyIvB;yBA3Je,gBAAgB"}
+{"version":3,"file":"SegmentedControl.d.ts","sourceRoot":"","sources":["../../src/SegmentedControl/SegmentedControl.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAAuB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAQlE,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,2BAA2B,CAAC;AAInC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CACjD,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,CACX;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AA8DD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,GAAG,EACH,KAAK,EACL,QAAQ,EACR,KAAK,EACL,IAAI,EAAE,QAAQ,EACd,MAAc,EACd,UAAkB,EAClB,eAAe,EACf,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,UAAU,EAClB,kBAAkB,EAAE,mBAAmB,EACvC,GAAG,IAAI,EACR,EAAE,qBAAqB,qBAyJvB;yBA3Ke,gBAAgB"}

package/dist/SegmentedControl/SegmentedControl.js

@@ -19,7 +19,8 @@ import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, radiusVars } from "../theme/tokens.stylex.js";
 import { SegmentedControlContext } from "./SegmentedControlContext.js";
-import { useListFocus } from "../hooks/useListFocus.js";
+import { useInternalListFocus } from "../hooks/useListFocus.js";
+import { isSegmentDisabledOnItsOwn } from "../privateAttributes/segmentDisabled.stylex.js";
 import { useKeyboardHint } from "../hooks/useKeyboardHint.js";
 import { useTooltip } from "../Tooltip/index.js";
 import { mergeProps, composeEventHandlers } from "../utils/index.js";
@@ -135,9 +136,13 @@ export function SegmentedControl({
     listRef,
     handleKeyDown,
     handleFocus
-  } = useListFocus({
+  } = useInternalListFocus({
     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'
   });
@@ -195,8 +200,9 @@ export function SegmentedControl({
     size,
     layout,
     isDisabled,
-    hasDisabledMessage: showsDisabledMessage
-  }), [value, onChange, size, layout, isDisabled, showsDisabledMessage]);
+    hasDisabledMessage: showsDisabledMessage,
+    disabledReasonID: showsDisabledMessage ? disabledMessageTooltip.describedBy : undefined
+  }), [value, onChange, size, layout, isDisabled, showsDisabledMessage, disabledMessageTooltip.describedBy]);
   return /*#__PURE__*/_jsxs(SegmentedControlContext, {
     value: contextValue,
     children: [/*#__PURE__*/_jsxs("div", {
@@ -218,4 +224,15 @@ export function SegmentedControl({
     }), showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)]
   });
 }
-SegmentedControl.displayName = '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) {
+  const segments = Array.from(list.querySelectorAll('[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/dist/SegmentedControl/SegmentedControlContext.d.ts

@@ -13,6 +13,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 declare const SegmentedControlContext: import("react").Context<SegmentedControlContextValue | null>;
 export declare function useSegmentedControlContext(): SegmentedControlContextValue;

package/dist/SegmentedControl/SegmentedControlContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SegmentedControlContext.d.ts","sourceRoot":"","sources":["../../src/SegmentedControl/SegmentedControlContext.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AACtD,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,eAAO,MAAM,uBAAuB,8DACsB,CAAC;AAG3D,wBAAgB,0BAA0B,IAAI,4BAA4B,CASzE"}
+{"version":3,"file":"SegmentedControlContext.d.ts","sourceRoot":"","sources":["../../src/SegmentedControl/SegmentedControlContext.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AACtD,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,uBAAuB,8DACsB,CAAC;AAG3D,wBAAgB,0BAA0B,IAAI,4BAA4B,CASzE"}

package/dist/SegmentedControl/SegmentedControlItem.d.ts

@@ -48,7 +48,7 @@ export interface SegmentedControlItemProps extends BaseProps<HTMLButtonElement>
  * <SegmentedControlItem value="grid" label="Grid" icon={<GridIcon />} />
  * ```
  */
-export declare function SegmentedControlItem({ ref, value, label, isLabelHidden, icon, isDisabled, onClick: onClickProp, xstyle, ...rest }: SegmentedControlItemProps): React.JSX.Element;
+export declare function SegmentedControlItem({ ref, value, label, isLabelHidden, icon, isDisabled, onClick: onClickProp, xstyle, 'aria-describedby': ariaDescribedByProp, ...rest }: SegmentedControlItemProps): React.JSX.Element;
 export declare namespace SegmentedControlItem {
     var displayName: string;
 }

package/dist/SegmentedControl/SegmentedControlItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SegmentedControlItem.d.ts","sourceRoot":"","sources":["../../src/SegmentedControl/SegmentedControlItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAe5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,yBAA0B,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC7E,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAgHD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,GAAG,EACH,KAAK,EACL,KAAK,EACL,aAAqB,EACrB,IAAI,EACJ,UAAkB,EAClB,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,GAAG,IAAI,EACR,EAAE,yBAAyB,qBA0E3B;yBApFe,oBAAoB"}
+{"version":3,"file":"SegmentedControlItem.d.ts","sourceRoot":"","sources":["../../src/SegmentedControl/SegmentedControlItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAiB5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,yBAA0B,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC7E,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAgHD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,GAAG,EACH,KAAK,EACL,KAAK,EACL,aAAqB,EACrB,IAAI,EACJ,UAAkB,EAClB,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,kBAAkB,EAAE,mBAAmB,EACvC,GAAG,IAAI,EACR,EAAE,yBAAyB,qBAwF3B;yBAnGe,oBAAoB"}

package/dist/SegmentedControl/SegmentedControlItem.js

@@ -15,6 +15,8 @@
  * - /packages/cli/assets/templates/blocks/components/SegmentedControl/ (showcase blocks)
  */
 import React from 'react';
+import { joinAriaIDs } from "../utils/inputAria.js";
+import { segmentDisabledProps } from "../privateAttributes/segmentDisabled.stylex.js";
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, sizeVars, durationVars, easeVars, fontWeightVars, shadowVars, typeScaleVars } from "../theme/tokens.stylex.js";
@@ -142,6 +144,7 @@ export function SegmentedControlItem({
   isDisabled = false,
   onClick: onClickProp,
   xstyle,
+  'aria-describedby': ariaDescribedByProp,
   ...rest
 }) {
   const pressable = usePressFeedback();
@@ -152,13 +155,19 @@ 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.
-  const keepsSelectedFocusable = isSelected && (ctx.hasDisabledMessage ?? false) && !isDisabled;
+  // 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);
   const size = 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, () => {
+  // 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);
     }
@@ -174,8 +183,15 @@ export function SegmentedControlItem({
     role: "radio",
     "aria-checked": isSelected,
     "aria-disabled": isItemDisabled || undefined,
-    "aria-label": isLabelHidden ? label : undefined,
-    "data-value": value,
+    "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/dist/Selector/Selector.d.ts

@@ -17,12 +17,12 @@
 import React, { type ReactNode } from 'react';
 import { type IconType } from '../Icon/index.js';
 import type { IndicatorPosition } from '../Indicator/index.js';
-import { type FieldStatusVariant } from '../Field/index.js';
 import { type LayerPlacement } from '../Layer/useLayer.js';
 import type { SelectorOptionType, SelectorOptionData } from './types.js';
 import { type FieldInputBaseProps } from '../Field/fieldParts.js';
 import type { SizeValue } from '../utils/types.js';
 import type { AdaptivePresentation } from '../hooks/useAdaptivePresentation.js';
+import type { FieldStatusPlacement } from '../Field/fieldStatusPlacement.js';
 export type SelectorSize = 'sm' | 'md' | 'lg';
 export type SelectorVariant = 'input' | 'secondary' | 'ghost';
 export type SelectorPresentation = AdaptivePresentation;
@@ -163,7 +163,7 @@ interface SelectorPropsBase<T extends SelectorOptionType = SelectorOptionType> e
      * - '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
      * (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they

package/dist/Selector/Selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Selector.d.ts","sourceRoot":"","sources":["../../src/Selector/Selector.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"Selector.d.ts","sourceRoot":"","sources":["../../src/Selector/Selector.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,EAUZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAE5D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,cAAc,CAAC;AAUpD,OAAO,EAAwB,KAAK,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAkB7E,OAAO,KAAK,EAAC,kBAAkB,EAAE,kBAAkB,EAAC,MAAM,SAAS,CAAC;AAmBpE,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAK7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAU9C,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,kCAAkC,CAAC;AAI3E,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,+BAA+B,CAAC;AAycxE,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC;AAE9D,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,CAAC;AAExD,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,IAAI,EAAE,kBAAkB,CAAC;IACzB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,iBAAiB,CACzB,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,CACjD,SAAQ,IAAI,CAAC,mBAAmB,EAAE,UAAU,GAAG,cAAc,CAAC;IAC9D;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAEnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAE/C;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAE/C;;;OAGG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAEpD;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,OAAO,EAAE,CAAC,EAAE,CAAC;IAIb;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IAEpB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAErC;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAEjC;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,SAAS,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,SAAS,CAAC;IAExD;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAEtC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAE5B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAEpC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,KAAK,yBAAyB,CAC5B,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IAC/C,iBAAiB,CAAC,CAAC,CAAC,GAAG;IACzB,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD,CAAC;AAEF,KAAK,sBAAsB,CAAC,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IAC3E,iBAAiB,CAAC,CAAC,CAAC,GAAG;IACrB;;;;;OAKG;IACH,QAAQ,EAAE,IAAI,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC1C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D,CAAC;AAEJ,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IACzE,yBAAyB,CAAC,CAAC,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC;AA4C3D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,kBAAkB,EACnD,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,qBAytCxB;yBA1tCe,QAAQ"}

package/dist/Selector/Selector.js

@@ -49,6 +49,7 @@ import { useSize } from "../SizeContext/SizeContext.js";
 import { useFieldInputStyling } from "../Field/fieldParts.js";
 import { composeEventHandlers } from "../utils/composeEventHandlers.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
+import { useInteractionModalityTracking } from "../utils/interactionModality.js";
 import { useBusyAnnouncement } from "../hooks/useBusyAnnouncement.js";
 import { themeProps } from "../utils/themeProps.js";
 import { focusOutlineStyles } from "../utils/focusOutline.stylex.js";
@@ -431,7 +432,8 @@ export function Selector(props) {
   // shorter inner button makes every size's selected row land too low.
   const anchorRef = useRef(null);
   const triggerRef = useRef(null);
-  const triggerButtonRef = useMergedRefs(triggerRef, ref);
+  const triggerModality = useInteractionModalityTracking();
+  const triggerButtonRef = useMergedRefs(triggerRef, triggerModality.ref, ref);
   const searchRef = useRef(null);
   const [searchQuery, setSearchQuery] = useState('');
   // Mirrors searchQuery for the seed path, which runs before focus reaches the
@@ -448,11 +450,9 @@ export function Selector(props) {
   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',
@@ -540,6 +540,7 @@ export function Selector(props) {
     onHide: handleLayerHide,
     onShow: handleLayerShow,
     triggerRef,
+    triggerModality,
     popoverOptions: {
       hasLightDismiss: true,
       hasCloseButton: false,
@@ -675,6 +676,11 @@ export function Selector(props) {
     announceSearchResults(nextQuery);
   }, [announceSearchResults]);
   const commitValue = useCallback(newValue => {
+    // 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 () => {
@@ -682,7 +688,7 @@ export function Selector(props) {
         await changeAction(newValue);
       });
     }
-  }, [onChange, changeAction, startTransition, setOptimisticValue]);
+  }, [isDisabled, isEffectivelyReadOnly, onChange, changeAction, startTransition, setOptimisticValue]);
 
   // Selector behavior (keyboard nav, selection)
   const {

package/dist/Selector/hooks.js

@@ -183,12 +183,12 @@ export function useCombobox({
     onClose();
   }, [onClose]);
   const selectItem = useCallback(item => {
-    if (item.disabled) {
+    if (isDisabled || item.disabled) {
       return;
     }
     onSelect?.(item.value);
     closeAndReset();
-  }, [onSelect, closeAndReset]);
+  }, [isDisabled, onSelect, closeAndReset]);
   const onTriggerClick = useCallback(() => {
     if (isDisabled) {
       return;

package/dist/Selector/useSelectorPresentation.d.ts

@@ -7,12 +7,25 @@
 import { type FocusEvent, type RefObject } from 'react';
 import { type UsePopoverOptions, type UsePopoverReturn } from '../Popover/usePopover.js';
 import { type AdaptivePresentation, type ResolvedAdaptivePresentation } from '../hooks/useAdaptivePresentation.js';
+import type { InteractionModalityTracking } from '../utils/interactionModality.js';
 interface UseSelectorPresentationOptions {
     presentation: AdaptivePresentation;
     onHide: () => void;
     onShow: () => void;
     popoverOptions: Omit<UsePopoverOptions, 'onHide' | 'onShow'>;
     triggerRef: RefObject<HTMLElement | null>;
+    /**
+     * The component's one modality tracking, its `ref` attached to the trigger,
+     * so the returned trigger's ring follows the trigger's own document.
+     */
+    triggerModality: Pick<InteractionModalityTracking, 'readModality'>;
+    /**
+     * Return focus to the trigger on every close, even when a press already
+     * moved focus to another element. A caller-rendered trigger needs this
+     * (spec:AST-055 AR3); the built-in trigger leaves focus where the press put
+     * it (spec:Popover AR4).
+     */
+    isFocusReturnAlways?: boolean;
 }
 interface SelectorPresentationController {
     activePresentation: ResolvedAdaptivePresentation;
@@ -26,6 +39,6 @@ interface SelectorPresentationController {
     popover: UsePopoverReturn;
     show: () => boolean;
 }
-export declare function useSelectorPresentation({ presentation, onHide, onShow, popoverOptions, triggerRef, }: UseSelectorPresentationOptions): SelectorPresentationController;
+export declare function useSelectorPresentation({ presentation, onHide, onShow, popoverOptions, triggerRef, triggerModality, isFocusReturnAlways, }: UseSelectorPresentationOptions): SelectorPresentationController;
 export {};
 //# sourceMappingURL=useSelectorPresentation.d.ts.map

package/dist/Selector/useSelectorPresentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSelectorPresentation.d.ts","sourceRoot":"","sources":["../../src/Selector/useSelectorPresentation.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EAClC,MAAM,kCAAkC,CAAC;AAG1C,UAAU,8BAA8B;IACtC,YAAY,EAAE,oBAAoB,CAAC;IACnC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,cAAc,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAC7D,UAAU,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,UAAU,8BAA8B;IACtC,kBAAkB,EAAE,4BAA4B,CAAC;IACjD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,4BAA4B,EAAE,OAAO,CAAC;IACtC,iBAAiB,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,cAAc,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACzD,OAAO,EAAE,gBAAgB,CAAC;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC;CACrB;AAED,wBAAgB,uBAAuB,CAAC,EACtC,YAAY,EACZ,MAAM,EACN,MAAM,EACN,cAAc,EACd,UAAU,GACX,EAAE,8BAA8B,GAAG,8BAA8B,CA+GjE"}
+{"version":3,"file":"useSelectorPresentation.d.ts","sourceRoot":"","sources":["../../src/Selector/useSelectorPresentation.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AAEH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EAClC,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAC,2BAA2B,EAAC,MAAM,8BAA8B,CAAC;AAG9E,UAAU,8BAA8B;IACtC,YAAY,EAAE,oBAAoB,CAAC;IACnC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,cAAc,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAC7D,UAAU,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC1C;;;OAGG;IACH,eAAe,EAAE,IAAI,CAAC,2BAA2B,EAAE,cAAc,CAAC,CAAC;IACnE;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,UAAU,8BAA8B;IACtC,kBAAkB,EAAE,4BAA4B,CAAC;IACjD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,4BAA4B,EAAE,OAAO,CAAC;IACtC,iBAAiB,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,cAAc,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACzD,OAAO,EAAE,gBAAgB,CAAC;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC;CACrB;AAED,wBAAgB,uBAAuB,CAAC,EACtC,YAAY,EACZ,MAAM,EACN,MAAM,EACN,cAAc,EACd,UAAU,EACV,eAAe,EACf,mBAA2B,GAC5B,EAAE,8BAA8B,GAAG,8BAA8B,CAmIjE"}

package/dist/Selector/useSelectorPresentation.js

@@ -17,7 +17,9 @@ export function useSelectorPresentation({
   onHide,
   onShow,
   popoverOptions,
-  triggerRef
+  triggerRef,
+  triggerModality,
+  isFocusReturnAlways = false
 }) {
   const resolvedPresentation = useAdaptivePresentation(presentation);
   const activePresentationRef = useRef(resolvedPresentation);
@@ -30,19 +32,33 @@ export function useSelectorPresentation({
   const onHideRef = useRef(onHide);
   const onShowRef = useRef(onShow);
   const didShowPopoverRef = useRef(false);
+  // The open list's container, read when the popover hides to tell focus that
+  // is still inside the list from focus that moved to another element.
+  const popoverContentRef = useRef(null);
   const {
     isFocusRingSuppressed,
     onFocusReturnTargetFocus,
     prepareFocusReturn,
     resetFocusReturn
-  } = useFocusReturnVisibility();
+  } = useFocusReturnVisibility(triggerModality);
   onHideRef.current = onHide;
   onShowRef.current = onShow;
   const handlePopoverHide = useCallback(() => {
-    prepareFocusReturn();
     onHideRef.current();
-    triggerRef.current?.focus();
-  }, [prepareFocusReturn, triggerRef]);
+    const trigger = triggerRef.current;
+    // A light dismiss caused by pressing another focusable element has already
+    // moved focus there; taking it back would leave the next key on this
+    // closed Selector (spec:Popover AR4 returns focus only when it would
+    // otherwise be lost). Escape, a choice in the list, or a press on nothing
+    // focusable still returns focus to the trigger.
+    const active = document.activeElement;
+    const focusLandedElsewhere = !isFocusReturnAlways && active instanceof HTMLElement && active !== document.body && active !== trigger && !popoverContentRef.current?.contains(active);
+    if (focusLandedElsewhere) {
+      return;
+    }
+    prepareFocusReturn();
+    trigger?.focus();
+  }, [isFocusReturnAlways, prepareFocusReturn, triggerRef]);
   const handlePopoverShow = useCallback(() => {
     didShowPopoverRef.current = true;
     resetFocusReturn();
@@ -53,6 +69,7 @@ export function useSelectorPresentation({
     onHide: handlePopoverHide,
     onShow: handlePopoverShow
   });
+  popoverContentRef.current = popover.contentRef.current;
   const {
     hide: hidePopover,
     show: showPopover

package/dist/SideNav/SideNavItem.d.ts

@@ -9,8 +9,8 @@
  * provided and fall back to `label` when it is missing or blank. Their label
  * tooltip binds to the interactive control through a callback ref, so hover,
  * keyboard focus, and `aria-describedby` follow the control from the first
- * collapsed render. A disabled control takes neither pointer nor focus, so its
- * row is the tooltip's trigger instead.
+ * collapsed render. A disabled control takes no pointer, so its row listens
+ * for the tooltip instead, while the control keeps focus and the description.
  *
  * Collapsed items with children open their submenu flyout through
  * `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and

package/dist/SideNav/SideNavItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SideNavItem.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNavItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAYf,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAE5D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAIrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAgB,KAAK,WAAW,EAAC,MAAM,iCAAiC,CAAC;AAkThF,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EACR,OAAO,GACP;QACE,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;KACpD,CAAC;IACN;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,EAAE,EACF,KAAK,EACL,IAAI,EACJ,YAAY,EACZ,UAAkB,EAClB,UAAkB,EAClB,IAAI,EACJ,OAAO,EACP,UAAU,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EAAE,eAAe,EAC5B,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,MAAM,EACN,GAAG,IAAI,EACR,EAAE,gBAAgB,sCA2blB;yBA7ce,WAAW"}
+{"version":3,"file":"SideNavItem.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNavItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAYf,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAE5D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAIrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAgB,KAAK,WAAW,EAAC,MAAM,iCAAiC,CAAC;AA6ThF,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EACR,OAAO,GACP;QACE,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;KACpD,CAAC;IACN;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,EAAE,EACF,KAAK,EACL,IAAI,EACJ,YAAY,EACZ,UAAkB,EAClB,UAAkB,EAClB,IAAI,EACJ,OAAO,EACP,UAAU,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EAAE,eAAe,EAC5B,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,MAAM,EACN,GAAG,IAAI,EACR,EAAE,gBAAgB,sCAiclB;yBAnde,WAAW"}

package/dist/SideNav/SideNavItem.js

@@ -13,8 +13,8 @@
  * provided and fall back to `label` when it is missing or blank. Their label
  * tooltip binds to the interactive control through a callback ref, so hover,
  * keyboard focus, and `aria-describedby` follow the control from the first
- * collapsed render. A disabled control takes neither pointer nor focus, so its
- * row is the tooltip's trigger instead.
+ * collapsed render. A disabled control takes no pointer, so its row listens
+ * for the tooltip instead, while the control keeps focus and the description.
  *
  * Collapsed items with children open their submenu flyout through
  * `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and
@@ -52,6 +52,7 @@ import { useSideNavCollapse, SideNavCollapseContext } from "./SideNavCollapseCon
 import { useSideNavRenderMode } from "./SideNavRenderContext.js";
 import { useAppShellMobile } from "../AppShell/AppShellMobileContext.js";
 import { themeProps } from "../utils/themeProps.js";
+import { disabledInteractionProps } from "../utils/disabledInteraction.js";
 import { useTranslator } from "../i18n/index.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 // =============================================================================
@@ -207,6 +208,8 @@ const EXPANDED_COLLAPSE_STATE = {
 /**
  * Renders `<a>` (via LinkComponent) when `href` is set, otherwise `<button>`.
  * Centralizes the link-vs-button decision used across all SideNavItem paths.
+ * A disabled item is a `<button>` that keeps its tab stop and exposes
+ * `aria-disabled`, but is inert (spec:AST-085 FR1, FR2).
  */
 function NavItemElement({
   href,
@@ -231,8 +234,11 @@ function NavItemElement({
     ref: ref,
     type: "button",
     onClick: onClick,
-    disabled: isDisabled,
     ...rest,
+    ...(isDisabled ? {
+      'aria-disabled': true,
+      ...disabledInteractionProps(rest.onKeyDown)
+    } : null),
     children: children
   });
 }
@@ -335,6 +341,10 @@ export function SideNavItem({
   const isRailLeaf = isCollapsed && !hasChildren;
   const railTooltip = useTooltip({
     placement: 'end',
+    // A disabled leaf's row is the trigger (see the collapsed path). It is not
+    // focusable itself, so `auto` would never hear the focus that bubbles up
+    // from its control.
+    focusTrigger: 'always',
     isEnabled: isRailLeaf,
     isOpen: isRailLeaf ? undefined : false
   });
@@ -477,12 +487,14 @@ export function SideNavItem({
 
     // Items without children: icon-only link or button, its label in a
     // tooltip. The control is the trigger, so the element that takes focus is
-    // the one described. A disabled control takes neither pointer
-    // (`navItemStyles.disabled`) nor focus, so its row is the trigger instead.
+    // the one described. A disabled control takes no pointer
+    // (`navItemStyles.disabled`), so its row listens for the tooltip instead;
+    // the control still takes focus (focusin reaches the row) and stays the
+    // element described (spec:AST-085 FR5).
     const isRowTrigger = isDisabled;
     const collapsedAriaProps = {
       'aria-current': isSelected ? 'page' : undefined,
-      'aria-describedby': isRowTrigger ? rest['aria-describedby'] : joinIds(rest['aria-describedby'], railTooltip.describedBy),
+      'aria-describedby': joinIds(rest['aria-describedby'], railTooltip.describedBy),
       'aria-disabled': isDisabled || undefined,
       'aria-label': collapsedAccessibleLabel,
       'data-testid': testId
@@ -500,7 +512,6 @@ export function SideNavItem({
     });
     return /*#__PURE__*/_jsxs("div", {
       ref: isRowTrigger ? railTooltip.ref : undefined,
-      "aria-describedby": isRowTrigger ? railTooltip.describedBy : undefined,
       ...stylex.props(styles.root, xstyle),
       children: [collapsedElement, railTooltip.renderTooltip(label)]
     });