@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Resizable/useResizable.ts

@@ -25,6 +25,22 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {devWarn} from '../utils/devWarning';
 import type {SizeValue} from '../utils/types';
 import type {ResizableSize} from './utils';
+import {
+  DEFAULT_COLLAPSED_SIZE,
+  DEFAULT_MIN,
+  DEFAULT_SIZE_FALLBACK,
+  RESIZABLE_SIZE_GUIDANCE,
+  SERVER_BASIS,
+  clampSize,
+  dependsOnBasis,
+  loadPersistedState,
+  measureContentBox,
+  parseSize,
+  persistState,
+  resolveBound,
+  type PersistedResizableState,
+  type ResizableDirection,
+} from './resizableModel';
 
 // =============================================================================
 // Types
@@ -36,7 +52,7 @@ export type ResizableMinConfig = {minSize?: ResizableSize};
 /** Maximum size configuration. */
 export type ResizableMaxConfig = {maxSize?: ResizableSize};
 
-export type ResizableDirection = 'horizontal' | 'vertical';
+export type {ResizableDirection} from './resizableModel';
 
 export interface ResizableRegionSizing {
   /**
@@ -195,115 +211,6 @@ export interface ResizableProps {
   _isResizableProps: true;
 }
 
-// =============================================================================
-// Constants
-// =============================================================================
-
-const DEFAULT_MIN = 50;
-const DEFAULT_COLLAPSED_SIZE = 40;
-const STORAGE_PREFIX = 'astryx-resizable:';
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-function clampSize(
-  size: number,
-  min: number,
-  max: number,
-  snaps: number[],
-): number {
-  const clamped = Math.min(max, Math.max(min, size));
-
-  // When snap points are defined, always snap to the nearest one.
-  // No intermediate positions — the panel can only rest at snap values.
-  if (snaps.length > 0) {
-    let nearest = snaps[0];
-    let nearestDist = Math.abs(clamped - nearest);
-    for (let i = 1; i < snaps.length; i++) {
-      const dist = Math.abs(clamped - snaps[i]);
-      if (dist < nearestDist) {
-        nearest = snaps[i];
-        nearestDist = dist;
-      }
-    }
-    return Math.min(max, Math.max(min, nearest));
-  }
-
-  return clamped;
-}
-
-interface PersistedResizableState {
-  /** Expanded size in px, or null when the entry carries no usable size. */
-  size: number | null;
-  /**
-   * Collapse state when the entry was written, or null when the entry
-   * predates collapse persistence and says nothing about it.
-   */
-  isCollapsed: boolean | null;
-}
-
-/**
- * Reads a persisted entry. Three formats exist in storage:
- * - `{size, isCollapsed}` — the current format; `size` is the expanded size,
- *   so the pre-collapse width survives a collapsed session
- * - a plain non-zero number — a legacy width-only entry that never recorded
- *   collapse, so `isCollapsed` is null (unknown)
- * - a plain `0` — written by legacy collapse, which restored the region as a
- *   zero-width expanded panel (#4790); read as "collapsed, no saved size"
- */
-function loadPersistedState(key: string): PersistedResizableState | null {
-  if (typeof window === 'undefined') {
-    return null;
-  }
-  try {
-    const raw = localStorage.getItem(STORAGE_PREFIX + key);
-    if (raw == null) {
-      return null;
-    }
-    const parsed: unknown = JSON.parse(raw);
-    if (typeof parsed === 'number') {
-      if (!Number.isFinite(parsed)) {
-        return null;
-      }
-      return parsed === 0
-        ? {size: null, isCollapsed: true}
-        : {size: parsed, isCollapsed: null};
-    }
-    if (typeof parsed === 'object' && parsed != null) {
-      const {size, isCollapsed} = parsed as {
-        size?: unknown;
-        isCollapsed?: unknown;
-      };
-      const hasSize =
-        typeof size === 'number' && Number.isFinite(size) && size > 0;
-      if (hasSize || isCollapsed === true) {
-        return {
-          size: hasSize ? size : null,
-          isCollapsed: isCollapsed === true,
-        };
-      }
-    }
-  } catch {
-    /* ignore */
-  }
-  return null;
-}
-
-function persistState(key: string, state: PersistedResizableState): void {
-  if (typeof window === 'undefined') {
-    return;
-  }
-  try {
-    localStorage.setItem(STORAGE_PREFIX + key, JSON.stringify(state));
-  } catch {
-    /* ignore */
-  }
-}
-
-/** The released compatibility basis when there is no window to measure. */
-const SERVER_BASIS = 1200;
-
 /** A store that never changes on its own; the snapshot is re-read on render. */
 const noopSubscribe = () => () => {};
 
@@ -334,244 +241,6 @@ function readWindowHeight(): number | null {
 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 ' +
-  '"N%" string from 0% to 100%, pixel(value), or ' +
-  'percent(value, {min: pixel(value)}) / percent(value, {max: pixel(value)}).';
-
-/** Parsed, validated input. */
-type ParsedSize =
-  | {kind: 'px'; value: number}
-  | {kind: 'percent'; value: number; min?: number; max?: number};
-
-const PX_PATTERN = /^(\d+(?:\.\d+)?)px$/;
-const PERCENT_PATTERN = /^(\d+(?:\.\d+)?)%$/;
-
-function parseSizeString(value: string): ParsedSize | null {
-  // Preserve the released atomic fast path exactly.
-  const px = PX_PATTERN.exec(value);
-  if (px) {
-    const parsed = Number(px[1]);
-    return Number.isFinite(parsed) ? {kind: 'px', value: parsed} : null;
-  }
-  const percentValue = PERCENT_PATTERN.exec(value);
-  if (percentValue) {
-    const parsed = Number(percentValue[1]);
-    return Number.isFinite(parsed) && parsed <= 100
-      ? {kind: 'percent', value: parsed}
-      : null;
-  }
-  return null;
-}
-
-function parsePixelSize(value: unknown): number | null {
-  if (typeof value !== 'object' || value == null || Array.isArray(value)) {
-    return null;
-  }
-  const candidate = value as {type?: unknown; value?: unknown};
-  return candidate.type === 'pixel' &&
-    typeof candidate.value === 'number' &&
-    Number.isFinite(candidate.value) &&
-    candidate.value >= 0
-    ? candidate.value
-    : null;
-}
-
-function parsePercentSize(value: object): ParsedSize | null {
-  if (Array.isArray(value)) {
-    return null;
-  }
-  const candidate = value as {
-    type?: unknown;
-    value?: unknown;
-    min?: unknown;
-    max?: unknown;
-  };
-  if (
-    candidate.type !== 'percent' ||
-    typeof candidate.value !== 'number' ||
-    !Number.isFinite(candidate.value) ||
-    candidate.value < 0 ||
-    candidate.value > 100
-  ) {
-    return null;
-  }
-
-  const hasMin = candidate.min !== undefined;
-  const hasMax = candidate.max !== undefined;
-  // Exactly one bound is required. The helper's public type enforces this for
-  // typed callers; this branch preserves it for JavaScript and `any`.
-  if (hasMin === hasMax) {
-    return null;
-  }
-  if (hasMin) {
-    const min = parsePixelSize(candidate.min);
-    return min == null ? null : {kind: 'percent', value: candidate.value, min};
-  }
-  const max = parsePixelSize(candidate.max);
-  return max == null ? null : {kind: 'percent', value: candidate.value, max};
-}
-
-function parseSize(value: unknown): ParsedSize | null {
-  if (typeof value === 'number') {
-    return Number.isFinite(value) && value >= 0 ? {kind: 'px', value} : null;
-  }
-  if (typeof value === 'string') {
-    return parseSizeString(value);
-  }
-  if (typeof value === 'object' && value != null) {
-    const pixelValue = parsePixelSize(value);
-    return pixelValue == null
-      ? parsePercentSize(value)
-      : {kind: 'px', value: pixelValue};
-  }
-  return null;
-}
-
-/** Whether this parsed value must be recomputed when its basis changes. */
-function dependsOnBasis(parsed: ParsedSize | null): boolean {
-  return parsed?.kind === 'percent';
-}
-
-/** Resolve a parsed size against its basis, then apply its one pixel bound. */
-function toPixels(parsed: ParsedSize, basis: number | null): number | null {
-  if (parsed.kind === 'px') {
-    return parsed.value;
-  }
-  if (basis == null) {
-    return null;
-  }
-  const percentagePx = Math.round((parsed.value / 100) * basis);
-  if (parsed.min !== undefined) {
-    return Math.max(percentagePx, parsed.min);
-  }
-  if (parsed.max !== undefined) {
-    return Math.min(percentagePx, parsed.max);
-  }
-  return percentagePx;
-}
-
-function describeUnknown(value: unknown): string {
-  if (typeof value === 'number' && !Number.isFinite(value)) {
-    return String(value);
-  }
-  try {
-    return JSON.stringify(value) ?? String(value);
-  } catch {
-    return String(value);
-  }
-}
-
-function describePixelCandidate(value: unknown): string {
-  if (typeof value !== 'object' || value == null || Array.isArray(value)) {
-    return describeUnknown(value);
-  }
-  const candidate = value as {type?: unknown; value?: unknown};
-  return candidate.type === 'pixel'
-    ? `{"type":"pixel","value":${describeUnknown(candidate.value)}}`
-    : describeUnknown(value);
-}
-
-function describeSize(value: unknown): string {
-  if (typeof value === 'object' && value != null && !Array.isArray(value)) {
-    const candidate = value as {
-      type?: unknown;
-      value?: unknown;
-      min?: unknown;
-      max?: unknown;
-    };
-    if (candidate.type === 'pixel') {
-      return describePixelCandidate(value);
-    }
-    if (candidate.type === 'percent') {
-      const fields = [
-        '"type":"percent"',
-        `"value":${describeUnknown(candidate.value)}`,
-      ];
-      if (candidate.min !== undefined) {
-        fields.push(`"min":${describePixelCandidate(candidate.min)}`);
-      }
-      if (candidate.max !== undefined) {
-        fields.push(`"max":${describePixelCandidate(candidate.max)}`);
-      }
-      return `{${fields.join(',')}}`;
-    }
-  }
-  return describeUnknown(value);
-}
-
-/**
- * Resolves one configured value, applying its role's fallback when the input is
- * not accepted. The warning remains development-only through `devWarn`; every
- * build takes the same deterministic fallback.
- */
-function resolveBound(
-  raw: unknown,
-  parsed: ParsedSize | null,
-  basis: number | null,
-  fallback: number,
-  label: string,
-  accepted: string,
-  didWarnRef: {current: boolean},
-): number {
-  if (raw === undefined) {
-    return fallback;
-  }
-  // Preserve the released explicit unbounded maximum. Other roles still
-  // reject non-finite numbers.
-  if (raw === Infinity && fallback === Infinity) {
-    return Infinity;
-  }
-  if (parsed == null) {
-    if (!didWarnRef.current) {
-      didWarnRef.current = true;
-      devWarn(
-        'useResizable',
-        `${label}: ${describeSize(raw)} is not a size. ${accepted} ` +
-          `Falling back to ${fallback}.`,
-      );
-    }
-    return fallback;
-  }
-  return toPixels(parsed, basis) ?? fallback;
-}
-
-/**
- * The container's content-box size on the active axis.
- *
- * Content box, not border box: a bordered or padded container would otherwise
- * report a basis a few pixels larger than the space a percentage is actually a
- * share of, and that error lands in `aria-valuemax`. The observer entry
- * carries `contentBoxSize` natively, which is already writing-mode aware;
- * measuring the element is the fallback for the synthetic entry
- * `observeResize` fires on registration.
- */
-function measureContentBox(
-  element: HTMLElement,
-  direction: ResizableDirection,
-  entry?: ResizeObserverEntry,
-): number | null {
-  const box = entry?.contentBoxSize?.[0];
-  if (box) {
-    return direction === 'vertical' ? box.blockSize : box.inlineSize;
-  }
-  const style =
-    typeof window === 'undefined' ? null : window.getComputedStyle(element);
-  if (style == null) {
-    return null;
-  }
-  const size =
-    direction === 'vertical'
-      ? element.clientHeight -
-        parseFloat(style.paddingTop) -
-        parseFloat(style.paddingBottom)
-      : element.clientWidth -
-        parseFloat(style.paddingLeft) -
-        parseFloat(style.paddingRight);
-  return Number.isFinite(size) ? size : null;
-}
-
 // =============================================================================
 // Single-region hook
 // =============================================================================

package/src/SegmentedControl/SegmentedControl.doc.mjs

@@ -132,14 +132,14 @@ function WorkspaceCard() {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Whether the entire control is disabled.',
+      description: 'Whether the entire control is disabled. The selected segment keeps the Tab stop, announced as disabled (aria-disabled), and nothing can be selected.',
       default: 'false',
     },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the control is disabled. Applies to the whole-group disabled state (isDisabled), not per segment. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the control focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled SegmentedControl in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the control is disabled. Applies to the whole-group disabled state (isDisabled), not per segment. With isDisabled, shows a tooltip on hover/keyboard focus, and the reason describes each segment (selection stays blocked). Use this instead of wrapping a disabled SegmentedControl in Tooltip, so the reason is attached to the control itself.',
     },
     {
       name: 'children',
@@ -230,7 +230,7 @@ function WorkspaceCard() {
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
       {guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
       {guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
-      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
+      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; the reason is then not attached to the control or its segments. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -246,7 +246,7 @@ export const docsZh = {
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
       {guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
       {guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
-      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
+      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; the reason is then not attached to the control or its segments. Use the disabledMessage prop instead.'},
     ],
   },
 };
@@ -262,7 +262,7 @@ export const docsDense = {
       {guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
       {guidance: false, description: 'Use for page-level navigation; use TabList instead. TabList is a navigation component, while SegmentedControl is an input that always has exactly one selected option.'},
       {guidance: false, description: 'Use for simple on/off states; use ToggleButton instead. ToggleButton can be toggled on or off independently, while SegmentedControl enforces a single selection from a group.'},
-      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
+      {guidance: false, description: 'Wrap a disabled SegmentedControl in Tooltip to explain why it is disabled; the reason is then not attached to the control or its segments. Use the disabledMessage prop instead.'},
     ],
   },
   propDescriptions: {

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 {
@@ -64,7 +65,9 @@ export interface SegmentedControlProps extends Omit<
    */
   layout?: SegmentedControlLayout;
   /**
-   * Whether the entire control is disabled.
+   * Whether the entire control is disabled. The selected segment keeps the
+   * control's Tab stop, announced as disabled (`aria-disabled`), and nothing
+   * can be selected.
    * @default false
    */
   isDisabled?: boolean;
@@ -72,11 +75,11 @@ export interface SegmentedControlProps extends Omit<
    * Explains why the control is disabled. Applies to the whole-group disabled
    * state (`isDisabled`), not individual segments. When set together with
    * `isDisabled`, the control shows a tooltip with this text on hover and
-   * keyboard focus, and stays focusable (via `aria-disabled`) so the reason is
-   * discoverable by keyboard and assistive technology. Selection stays blocked.
+   * keyboard focus, and the reason describes each segment for assistive
+   * technology. Selection stays blocked.
    *
-   * Use this instead of wrapping a disabled control in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled control in `Tooltip`, so the
+   * reason is attached to the control itself.
    */
   disabledMessage?: string;
   /**
@@ -118,15 +121,11 @@ const styles = stylex.create({
     display: 'flex',
     width: '100%',
   },
+  // Disabled: dimmed, with pointer events left on so a press can focus the
+  // segment that holds the Tab stop and a reason tooltip can open on hover.
+  // Selection is blocked by the isDisabled guards (spec:AST-085 FR1, FR2).
   disabled: {
     opacity: 0.5,
-    pointerEvents: 'none',
-  },
-  // Disabled *with* a disabledMessage: keep the dimmed look but leave pointer
-  // events on so the group can receive hover and surface the reason tooltip.
-  // Selection is still blocked by the isDisabled guards.
-  disabledWithMessage: {
-    opacity: 0.5,
   },
 });
 
@@ -179,11 +178,10 @@ export function SegmentedControl({
 }: SegmentedControlProps) {
   const size = useSize(sizeProp, 'md');
 
-  // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
-  // controls swallow pointer events, so the tooltip listeners attach to the
-  // radiogroup container (and the container keeps pointer events on in this
-  // mode) while the radios stay perceivable via aria-disabled. Selection is
-  // blocked by the isDisabled guards in the click/focus handlers.
+  // Disabled-reason tooltip. Applies to the whole-group disabled state. The
+  // tooltip listeners attach to the radiogroup container, which keeps pointer
+  // events while disabled; the radios stay perceivable via aria-disabled.
+  // Selection is blocked by the isDisabled guards in the click/focus handlers.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -198,12 +196,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,
+      // One Tab stop, placed by the control (FR2, FR7): the selected segment,
+      // enabled or not and in a disabled control too, else the first segment
+      // not disabled by its own isDisabled, else the first.
+      tabStopOrder: orderTabStop,
+      wrap: true,
+      orientation: 'horizontal',
+    });
 
   const hint = useKeyboardHint({
     orientation: 'horizontal',
@@ -270,9 +273,19 @@ export function SegmentedControl({
       size,
       layout,
       isDisabled,
-      hasDisabledMessage: showsDisabledMessage,
+      disabledReasonID: showsDisabledMessage
+        ? disabledMessageTooltip.describedBy
+        : undefined,
     }),
-    [value, onChange, size, layout, isDisabled, showsDisabledMessage],
+    [
+      value,
+      onChange,
+      size,
+      layout,
+      isDisabled,
+      showsDisabledMessage,
+      disabledMessageTooltip.describedBy,
+    ],
   );
 
   return (
@@ -297,10 +310,7 @@ export function SegmentedControl({
             styles.container,
             sizeStyles[size],
             layout === 'fill' && styles.fill,
-            isDisabled &&
-              (showsDisabledMessage
-                ? styles.disabledWithMessage
-                : styles.disabled),
+            isDisabled && styles.disabled,
             xstyle,
           ),
           className,
@@ -316,3 +326,21 @@ export function SegmentedControl({
 }
 
 SegmentedControl.displayName = 'SegmentedControl';
+
+/**
+ * The control's segments, its Tab stop first: the selected segment, enabled
+ * or not, else the first segment not disabled by its own isDisabled, else the
+ * first (FR2, FR7).
+ */
+function orderTabStop(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

@@ -24,12 +24,11 @@ export interface SegmentedControlContextValue {
   layout: SegmentedControlLayout;
   isDisabled: boolean;
   /**
-   * True when the whole control is disabled *and* a `disabledMessage` is set.
-   * In that mode the selected segment stays focusable (via `aria-disabled`
-   * rather than being dropped from the tab order) so the group's disabled-reason
-   * tooltip is keyboard-discoverable; selection is still blocked.
+   * The id of the group's disabled-reason tooltip while the group is disabled
+   * with a `disabledMessage`. It also describes each segment, so the segment that has focus is
+   * described by the reason (spec:AST-085 FR5).
    */
-  hasDisabledMessage?: boolean;
+  disabledReasonID?: string;
 }
 
 export const SegmentedControlContext =

package/src/SegmentedControl/SegmentedControlItem.doc.mjs

@@ -52,7 +52,7 @@ export const docs = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Whether this individual item is disabled.',
+      description: "Whether this individual item is disabled. A disabled selected item keeps the control's Tab stop.",
       default: 'false',
     },
   ],

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();
@@ -199,12 +202,6 @@ export function SegmentedControlItem({
 
   const isSelected = ctx.value === value;
   const isItemDisabled = isDisabled || ctx.isDisabled;
-  // When the whole group is disabled with a disabledMessage, keep the selected
-  // 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;
   const size: SegmentedControlSize = ctx.size;
   const isFill = ctx.layout === 'fill';
 
@@ -235,16 +232,17 @@ 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
-      // silently dead (arrows and activation are no-ops) (navigation-13). The
-      // exception is a whole-group disabledMessage, where the selected segment
-      // stays focusable so the reason tooltip is keyboard-discoverable.
-      tabIndex={
-        (isSelected && !isItemDisabled) || keepsSelectedFocusable ? 0 : -1
-      }
+      // The selected segment holds the Tab stop, disabled or not (spec:AST-085
+      // FR1); activation stays blocked by the isItemDisabled guard. With no
+      // selected segment, the group places the stop (SegmentedControl FR2).
+      tabIndex={isSelected ? 0 : -1}
       onClick={handleClick}
       {...mergeProps(
         themeProps('segmented-control-item', {