@astryxdesign/core 0.7.7-canary.f9ac85f → 0.7.7

package/src/Layer/layerAnimations.stylex.ts

@@ -2,7 +2,8 @@
 
 /**
  * @file layerAnimations.stylex.ts
- * @input Uses StyleX, theme duration/easing tokens
+ * @input Uses StyleX, theme duration/easing tokens, the Reduce Motion fade
+ *   constants
  * @output Exports shared entry animation styles for layer-based components
  * @position Shared animation primitives; consumed by DropdownMenu, Popover,
  *   HoverCard, Tooltip, Selector, and any component using useLayer
@@ -27,6 +28,7 @@
  */
 
 import * as stylex from '@stylexjs/stylex';
+import {reducedMotionFadeConsts} from '../motion/reducedMotion.stylex';
 import {durationVars, easeVars, spacingVars} from '../theme/tokens.stylex';
 
 const enterBelow = stylex.keyframes({
@@ -84,17 +86,21 @@ const enterStartRtl = stylex.keyframes({
 
 // Reduce Motion under a finger: the same entrance without its travel. A touch
 // presentation substitutes a cross-fade for motion, never a jump.
+// The fade's curve rides in its first keyframe, so the published class type
+// of `animationTimingFunction` stays the theme ease's.
 const fadeIn = stylex.keyframes({
-  from: {opacity: 0},
+  from: {opacity: 0, animationTimingFunction: reducedMotionFadeConsts.easing},
   to: {opacity: 1},
 });
 
+// No theme value lengthens the Reduce Motion fade, so its values are constants.
+// The media keys stay literal: StyleX gives an imported at-rule key a later
+// priority layer (see reducedMotionKeys).
 const animationBase = {
   animationDuration: {
     default: durationVars['--duration-fast-max'],
-    // The cross-fade is 200 ms or less, whatever the theme's duration
-    // (design:reduced-motion DR2).
-    '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': `min(${durationVars['--duration-fast-max']}, 200ms)`,
+    '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+      reducedMotionFadeConsts.duration,
   },
   animationTimingFunction: easeVars['--ease-standard'],
   animationFillMode: 'backwards' as const,
@@ -106,19 +112,18 @@ const animationBase = {
  * Keyed by LayerPlacement ('above' | 'below' | 'start' | 'end')
  * for easy lookup: `layerAnimations[placement]`.
  *
- * Each entry disables its keyframe animation under
- * `prefers-reduced-motion: reduce` so the layer appears instantly instead of
- * translating/scaling in (infra-6). Under a finger (the primary pointer is
- * coarse) it fades in instead, opacity only and in 200 ms or less: on a touch
- * screen Reduce Motion replaces motion with a cross-fade rather than a jump
- * (design:reduced-motion DR2, DR3), as iOS does for its menus, popovers and
- * tips.
+ * Under `prefers-reduced-motion: reduce` each entry drops its travel and
+ * scale. Under a finger (the primary pointer is coarse) the layer fades in,
+ * opacity only, in 200 ms on easeInOut: on a touch screen Reduce Motion
+ * replaces motion with a cross-fade rather than a jump; under any other
+ * pointer it appears at once.
  */
 export const layerAnimations = stylex.create({
   below: {
     animationName: {
       default: enterBelow,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
@@ -126,7 +131,8 @@ export const layerAnimations = stylex.create({
   above: {
     animationName: {
       default: enterAbove,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
@@ -135,7 +141,8 @@ export const layerAnimations = stylex.create({
     animationName: {
       default: enterEnd,
       ':is([dir="rtl"] *)': enterEndRtl,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
@@ -144,7 +151,8 @@ export const layerAnimations = stylex.create({
     animationName: {
       default: enterStart,
       ':is([dir="rtl"] *)': enterStartRtl,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,

package/src/Layer/usePressPin.ts

@@ -35,12 +35,10 @@ import {
 
 /**
  * How the trigger opens the layer. `adaptive`, the default, previews it on
- * hover and focus, and a tap opens it unless the trigger acts. While
- * `touchTrigger` remains, it decides those taps. `hover` previews it on hover
- * and focus, and no touch or pen tap opens it. `toggle` pins it on every
- * press of a button trigger.
+ * hover and focus, and `touchTrigger` decides taps. `toggle` pins it on every
+ * press of a button trigger. Internal: InfoTip's press-to-pin uses `toggle`.
  */
-export type LayerTriggerBehavior = 'adaptive' | 'hover' | 'toggle';
+export type LayerTriggerBehavior = 'adaptive' | 'toggle';
 
 /** The clicks a press pin answered, so the wrapper can stop them (`stopPressPinClick`). */
 const pressPinClicks = new WeakSet<Event>();
@@ -214,11 +212,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     clearTapOpen,
     armOutsideDismiss,
   } = useTouchTriggerInternal({
-    touchTrigger: isToggleMode
-      ? 'tap'
-      : triggerBehavior === 'hover'
-        ? 'none'
-        : options.touchTrigger,
+    touchTrigger: isToggleMode ? 'tap' : options.touchTrigger,
     isEnabled: options.isEnabled,
     isControlled: isOpen !== undefined,
     isOpen: isLayerOpen,
@@ -466,7 +460,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   const isWired = isToggleMode && offeredKind === 'button';
   useDevWarning(
     options.component,
-    '`triggerBehavior="toggle"` pins only a button trigger (a <button> or role="button"); this trigger keeps tap-only opening.',
+    'A press-to-pin tooltip pins only a button trigger (a <button> or role="button"); this trigger keeps tap-only opening.',
     isToggleMode && offeredKind === 'other',
   );
 

package/src/MobileNav/MobileNav.tsx

@@ -143,8 +143,8 @@ const styles = stylex.create({
   // ::backdrop is provided by the browser's top layer
   backdrop: {
     '::backdrop': {
+      // No backdrop-filter: a full-viewport blur is costly to repaint.
       backgroundColor: colorVars['--color-overlay'],
-      backdropFilter: 'blur(2px)',
       opacity: 0,
       transitionProperty: 'opacity',
       transitionDuration: durationVars['--duration-medium'],

package/src/MultiSelector/hooks.ts

@@ -174,13 +174,11 @@ export function useMultiCombobox({
       // The action cell is the caller's control, usable whether or not the
       // option itself is disabled (spec:AST-058 FR4).
       if (cell === 'action') {
-        highlightOnHover(index);
-        setHighlightedCell('action');
+        highlightOnHover(index, () => setHighlightedCell('action'));
         return;
       }
       if (!item.disabled) {
-        highlightOnHover(index);
-        setHighlightedCell('option');
+        highlightOnHover(index, () => setHighlightedCell('option'));
       }
     },
     [highlightOnHover],

package/src/Outline/Outline.doc.mjs

@@ -63,7 +63,11 @@ export const docs = {
     targets: [
       {className: 'astryx-outline', visualProps: ['density']},
       {className: 'astryx-outline-indicator'},
-      {className: 'astryx-outline-item', visualProps: ['level'], states: ['active']},
+      {
+        className: 'astryx-outline-item',
+        visualProps: ['level'],
+        states: ['active'],
+      },
     ],
   },
   components: [
@@ -101,7 +105,8 @@ export const docs = {
         {
           name: 'density',
           type: "'default' | 'compact'",
-          description: "Density variant controlling item padding. 'compact' for dense UIs, 'default' for standard spacing.",
+          description:
+            "Density variant controlling item padding. 'compact' for dense UIs, 'default' for standard spacing.",
           default: "'default'",
         },
         {
@@ -271,17 +276,53 @@ function FlashOnArrival() {
   usage: {
     anatomy,
     description:
-      'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes. Features a sliding indicator track that animates to the active heading. The list is a single tab stop: arrow keys move between headings, Home/End jump to the ends, and Enter/Space activate.',
+      'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes. Features a sliding indicator track that animates to the active heading. Each link is in the normal Tab order, and Enter/Space activate.',
     bestPractices: [
-      {guidance: true, description: 'Pass a flat ordered list of headings and let level control indentation.'},
-      {guidance: true, description: 'Use activeId when custom scroll logic owns the active section.'},
-      {guidance: true, description: 'Use density="compact" in dense sidebars where vertical space is tight.'},
-      {guidance: true, description: 'Use useOutlineFromMarkdown or useOutlineFromDOM when headings are generated from content. For linkable Markdown headings, pass the same createMarkdownHeadingLinks() entry to Markdown and Outline; configure headingIdPrefix on that plugin for multiple roots.'},
-      {guidance: true, description: 'Pass scrollContainerRef when the content scrolls in a split pane, modal, or panel instead of the viewport.'},
-      {guidance: true, description: 'Set offset to the height of a fixed header that overlays the content, so headings land below it instead of underneath it.'},
-      {guidance: false, description: 'Use Outline for application navigation - use SideNav or TopNav for routes.'},
-      {guidance: false, description: 'Use Outline for expandable hierarchy - use TreeList when nodes need expand and collapse.'},
-      {guidance: false, description: 'Rely on onNavigateEnd to mean "arrived" - it also fires when the user interrupts the scroll.'},
+      {
+        guidance: true,
+        description:
+          'Pass a flat ordered list of headings and let level control indentation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use activeId when custom scroll logic owns the active section.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use density="compact" in dense sidebars where vertical space is tight.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use useOutlineFromMarkdown or useOutlineFromDOM when headings are generated from content. For linkable Markdown headings, pass the same createMarkdownHeadingLinks() entry to Markdown and Outline; configure headingIdPrefix on that plugin for multiple roots.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass scrollContainerRef when the content scrolls in a split pane, modal, or panel instead of the viewport.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set offset to the height of a fixed header that overlays the content, so headings land below it instead of underneath it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Outline for application navigation - use SideNav or TopNav for routes.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Outline for expandable hierarchy - use TreeList when nodes need expand and collapse.',
+      },
+      {
+        guidance: false,
+        description:
+          'Rely on onNavigateEnd to mean "arrived" - it also fires when the user interrupts the scroll.',
+      },
     ],
   },
 };
@@ -295,7 +336,11 @@ export const docsZh = {
     targets: [
       {className: 'astryx-outline', visualProps: ['density']},
       {className: 'astryx-outline-indicator'},
-      {className: 'astryx-outline-item', visualProps: ['level'], states: ['active']},
+      {
+        className: 'astryx-outline-item',
+        visualProps: ['level'],
+        states: ['active'],
+      },
     ],
   },
   components: [
@@ -332,40 +377,47 @@ export const docsZh = {
         {
           name: 'density',
           type: "'default' | 'compact'",
-          description: "控制项目内边距的密度变体。'compact' 用于紧凑界面，'default' 为标准间距。",
+          description:
+            "控制项目内边距的密度变体。'compact' 用于紧凑界面，'default' 为标准间距。",
           default: "'default'",
         },
         {
           name: 'onNavigateStart',
           type: '(id: string) => void',
-          description: '导航开始时（滚动前）调用，传入项目 id。与 onNavigateEnd 搭配可在目标标题上实现到达效果（闪烁、描边、脉冲）。',
+          description:
+            '导航开始时（滚动前）调用，传入项目 id。与 onNavigateEnd 搭配可在目标标题上实现到达效果（闪烁、描边、脉冲）。',
         },
         {
           name: 'onNavigateEnd',
           type: '(id: string) => void',
-          description: '导航结束时调用（平滑滚动停止，或减弱动效将其变为瞬时跳转）。每次 onNavigateStart 必定对应一次调用，包括用户中途手动滚动打断的情况，因此“导航中”状态不会泄漏。',
+          description:
+            '导航结束时调用（平滑滚动停止，或减弱动效将其变为瞬时跳转）。每次 onNavigateStart 必定对应一次调用，包括用户中途手动滚动打断的情况，因此“导航中”状态不会泄漏。',
         },
         {
           name: 'offset',
           type: 'number',
-          description: '覆盖滚动根顶部的固定顶栏高度（px）。同时位移激活线与滚动落点，因此标题被激活的位置正是点击后停留的位置——落在顶栏下方，而非被顶栏遮住。它与每个标题自身的 scroll-margin-top 叠加（先顶栏，再留白），而非取代它。若没有元素覆盖内容，保持 0，交给 scroll-margin-top 处理。',
+          description:
+            '覆盖滚动根顶部的固定顶栏高度（px）。同时位移激活线与滚动落点，因此标题被激活的位置正是点击后停留的位置——落在顶栏下方，而非被顶栏遮住。它与每个标题自身的 scroll-margin-top 叠加（先顶栏，再留白），而非取代它。若没有元素覆盖内容，保持 0，交给 scroll-margin-top 处理。',
           default: '0',
         },
         {
           name: 'scrollContainerRef',
           type: 'React.RefObject<HTMLElement | null>',
-          description: '要跟踪的滚动容器，替代自动探测最近的可滚动祖先。当内容在分栏、弹窗或面板中滚动而非视口时使用。',
+          description:
+            '要跟踪的滚动容器，替代自动探测最近的可滚动祖先。当内容在分栏、弹窗或面板中滚动而非视口时使用。',
         },
         {
           name: 'hasScrollOnClick',
           type: 'boolean',
-          description: '激活项目时是否平滑滚动。设为 false 可自行接管滚动（虚拟列表、路由）：Outline 仍会更新激活项、hash 和导航回调，但不执行滚动。',
+          description:
+            '激活项目时是否平滑滚动。设为 false 可自行接管滚动（虚拟列表、路由）：Outline 仍会更新激活项、hash 和导航回调，但不执行滚动。',
           default: 'true',
         },
         {
           name: 'xstyle',
           type: 'StyleXStyles',
-          description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。',
+          description:
+            '用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。',
         },
       ],
     },
@@ -375,12 +427,36 @@ export const docsZh = {
     description:
       'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes.',
     bestPractices: [
-      {guidance: true, description: 'Pass a flat ordered list of headings and let level control indentation.'},
-      {guidance: true, description: 'Use activeId when custom scroll logic owns the active section.'},
-      {guidance: true, description: 'Use density="compact" in dense sidebars where vertical space is tight.'},
-      {guidance: true, description: 'Use useOutlineFromMarkdown or useOutlineFromDOM when headings are generated from content. For linkable Markdown headings, pass the same createMarkdownHeadingLinks() entry to Markdown and Outline; configure headingIdPrefix on that plugin for multiple roots.'},
-      {guidance: false, description: 'Use Outline for application navigation - use SideNav or TopNav for routes.'},
-      {guidance: false, description: 'Use Outline for expandable hierarchy - use TreeList when nodes need expand and collapse.'},
+      {
+        guidance: true,
+        description:
+          'Pass a flat ordered list of headings and let level control indentation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use activeId when custom scroll logic owns the active section.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use density="compact" in dense sidebars where vertical space is tight.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use useOutlineFromMarkdown or useOutlineFromDOM when headings are generated from content. For linkable Markdown headings, pass the same createMarkdownHeadingLinks() entry to Markdown and Outline; configure headingIdPrefix on that plugin for multiple roots.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Outline for application navigation - use SideNav or TopNav for routes.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Outline for expandable hierarchy - use TreeList when nodes need expand and collapse.',
+      },
     ],
   },
 };
@@ -388,34 +464,77 @@ export const docsZh = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
-    'Document outline/table-of-contents nav with sliding indicator track. Flat items array {id,label,level}; anchor links; density variant (default/compact); uncontrolled scroll-spy by scroll position (last heading past its resting line = offset + its own scroll-margin-top; first item at top, last at bottom); controlled with activeId; smooth-scroll on click that pins the active item until the next manual scroll. Single tab stop (roving tabindex): Arrow keys move, Home/End jump, Enter/Space activate. onNavigateStart/onNavigateEnd fire around the scroll. Scroll scoping via offset / scrollContainerRef / hasScrollOnClick.',
+    'Document outline/table-of-contents nav with sliding indicator track. Flat items array {id,label,level}; anchor links; density variant (default/compact); uncontrolled scroll-spy by scroll position (last heading past its resting line = offset + its own scroll-margin-top; first item at top, last at bottom); controlled with activeId; smooth-scroll on click that pins the active item until the next manual scroll. Each link is a Tab stop; Enter/Space activate; no arrow/Home/End movement. onNavigateStart/onNavigateEnd fire around the scroll. Scroll scoping via offset / scrollContainerRef / hasScrollOnClick.',
   usage: {
     anatomy,
     description:
       'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes.',
     bestPractices: [
-      {guidance: true, description: 'Pass a flat ordered list of headings and let level control indentation.'},
-      {guidance: true, description: 'Use activeId when custom scroll logic owns the active section.'},
-      {guidance: true, description: 'Use density="compact" in dense sidebars where vertical space is tight.'},
-      {guidance: true, description: 'Use useOutlineFromMarkdown or useOutlineFromDOM when headings are generated from content. For linkable Markdown headings, pass the same createMarkdownHeadingLinks() entry to Markdown and Outline; configure headingIdPrefix on that plugin for multiple roots.'},
-      {guidance: true, description: 'Pass scrollContainerRef when the content scrolls in a split pane, modal, or panel instead of the viewport.'},
-      {guidance: true, description: 'Set offset to the height of a fixed header that overlays the content, so headings land below it instead of underneath it.'},
-      {guidance: false, description: 'Use Outline for application navigation - use SideNav or TopNav for routes.'},
-      {guidance: false, description: 'Use Outline for expandable hierarchy - use TreeList when nodes need expand and collapse.'},
-      {guidance: false, description: 'Rely on onNavigateEnd to mean "arrived" - it also fires when the user interrupts the scroll.'},
+      {
+        guidance: true,
+        description:
+          'Pass a flat ordered list of headings and let level control indentation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use activeId when custom scroll logic owns the active section.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use density="compact" in dense sidebars where vertical space is tight.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use useOutlineFromMarkdown or useOutlineFromDOM when headings are generated from content. For linkable Markdown headings, pass the same createMarkdownHeadingLinks() entry to Markdown and Outline; configure headingIdPrefix on that plugin for multiple roots.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass scrollContainerRef when the content scrolls in a split pane, modal, or panel instead of the viewport.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set offset to the height of a fixed header that overlays the content, so headings land below it instead of underneath it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Outline for application navigation - use SideNav or TopNav for routes.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Outline for expandable hierarchy - use TreeList when nodes need expand and collapse.',
+      },
+      {
+        guidance: false,
+        description:
+          'Rely on onNavigateEnd to mean "arrived" - it also fires when the user interrupts the scroll.',
+      },
     ],
   },
   propDescriptions: {
-    items: 'Ordered OutlineItem[]: {id,label,level}. id should match target heading DOM id.',
+    items:
+      'Ordered OutlineItem[]: {id,label,level}. id should match target heading DOM id.',
     activeId: 'Controlled active heading id. Disables built-in scroll-spy.',
     onActiveIdChange: 'Called when active id changes from scroll-spy or click.',
     label: "Accessible nav label. Default: 'Table of contents'.",
-    density: "Density variant: 'default' (standard) or 'compact'. Default: 'default'.",
-    onNavigateStart: 'Called with the id when navigation begins, before the scroll.',
-    onNavigateEnd: 'Called with the id once the scroll settles. Fires exactly once per onNavigateStart, including on user interruption.',
-    offset: 'Height in px of a fixed header overlaying the scroll root. Shifts BOTH the activation line and the scroll landing, so a heading activates where navigating to it lands it. Composes with (does not replace) each heading scroll-margin-top. Default: 0.',
-    scrollContainerRef: 'RefObject of the scroll container to track, instead of the nearest scrollable ancestor. For split panes, modals, panels.',
-    hasScrollOnClick: 'Whether activating an item smooth-scrolls to it. false = you own scrolling; active id, hash and callbacks still update. Default: true.',
+    density:
+      "Density variant: 'default' (standard) or 'compact'. Default: 'default'.",
+    onNavigateStart:
+      'Called with the id when navigation begins, before the scroll.',
+    onNavigateEnd:
+      'Called with the id once the scroll settles. Fires exactly once per onNavigateStart, including on user interruption.',
+    offset:
+      'Height in px of a fixed header overlaying the scroll root. Shifts BOTH the activation line and the scroll landing, so a heading activates where navigating to it lands it. Composes with (does not replace) each heading scroll-margin-top. Default: 0.',
+    scrollContainerRef:
+      'RefObject of the scroll container to track, instead of the nearest scrollable ancestor. For split panes, modals, panels.',
+    hasScrollOnClick:
+      'Whether activating an item smooth-scrolls to it. false = you own scrolling; active id, hash and callbacks still update. Default: true.',
     xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
   },
   components: [
@@ -423,18 +542,25 @@ export const docsDense = {
       name: 'Outline',
       displayName: 'Outline',
       description:
-        'Document outline nav with sliding indicator. Renders heading anchors with a density variant, roving-tabindex keyboard nav, navigate callbacks, and scroll-spy active state when uncontrolled.',
+        'Document outline nav with sliding indicator. Renders heading anchors with a density variant, links in the normal Tab order, navigate callbacks, and scroll-spy active state when uncontrolled.',
       propDescriptions: {
-        items: 'Ordered OutlineItem[]: {id,label,level}. id should match target heading DOM id.',
+        items:
+          'Ordered OutlineItem[]: {id,label,level}. id should match target heading DOM id.',
         activeId: 'Controlled active heading id. Disables built-in scroll-spy.',
-        onActiveIdChange: 'Called when active id changes from scroll-spy or click.',
+        onActiveIdChange:
+          'Called when active id changes from scroll-spy or click.',
         label: "Accessible nav label. Default: 'Table of contents'.",
         density: "Density variant: 'default' | 'compact'. Default: 'default'.",
-        onNavigateStart: 'Called with the id when navigation begins, before the scroll.',
-        onNavigateEnd: 'Called with the id once the scroll settles. Fires exactly once per onNavigateStart, including on user interruption.',
-        offset: 'Height in px of a fixed header overlaying the scroll root. Shifts both the activation line and the scroll landing. Composes with scroll-margin-top. Default: 0.',
-        scrollContainerRef: 'RefObject of the scroll container to track, instead of the nearest scrollable ancestor.',
-        hasScrollOnClick: 'Whether activating an item smooth-scrolls to it. Default: true.',
+        onNavigateStart:
+          'Called with the id when navigation begins, before the scroll.',
+        onNavigateEnd:
+          'Called with the id once the scroll settles. Fires exactly once per onNavigateStart, including on user interruption.',
+        offset:
+          'Height in px of a fixed header overlaying the scroll root. Shifts both the activation line and the scroll landing. Composes with scroll-margin-top. Default: 0.',
+        scrollContainerRef:
+          'RefObject of the scroll container to track, instead of the nearest scrollable ancestor.',
+        hasScrollOnClick:
+          'Whether activating an item smooth-scrolls to it. Default: true.',
         xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
       },
     },

package/src/Outline/Outline.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Outline.tsx
- * @input Uses React, StyleX, Astryx link provider integration, Outline hooks/types, useListFocus
+ * @input Uses React, StyleX, Astryx link provider integration, Outline hooks/types
  * @output Exports Outline component and OutlineProps type
  * @position Core implementation; consumed by index.ts
  *
@@ -12,7 +12,7 @@
  * - Sliding indicator track (vertical divider + animated active bar)
  * - Density variant (default/compact)
  * - Scroll-spy active state when uncontrolled
- * - Roving-tabindex keyboard navigation (Arrow/Home/End, Enter/Space activate)
+ * - Each link in the normal Tab order (Enter/Space activate)
  * - onNavigateStart / onNavigateEnd callbacks around the smooth scroll
  * - Scroll scoping (offset, scrollContainerRef, hasScrollOnClick)
  *
@@ -35,8 +35,6 @@ import {
   fontWeightVars,
 } from '../theme/tokens.stylex';
 import {useLinkComponent} from '../Link/useLinkComponent';
-import {useListFocus} from '../hooks/useListFocus';
-import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useScrollSpy} from './useScrollSpy';
@@ -304,10 +302,8 @@ function moveFocusTo(id: string) {
  * scroll root) plus the heading's own `scroll-margin-top`. It defaults to the
  * first item at the top and the last at the bottom.
  *
- * Keyboard: the list is a single tab stop (roving tabindex), seated on the
- * active heading. Arrow keys move between headings, Home/End jump to the ends,
- * and Enter/Space activate — so a long table of contents costs one Tab press,
- * not one per heading.
+ * Keyboard: each link is in the normal Tab order, and Enter/Space activate.
+ * There is no arrow, Home, or End movement between links.
  *
  * @example
  * ```
@@ -369,49 +365,6 @@ export function Outline({
     onNavigateEnd,
   });
 
-  // Roving tabindex over the links: the whole outline is one tab stop, and
-  // arrows move between headings. The hook owns `tabindex` on the items.
-  const {
-    listRef,
-    handleKeyDown: handleListKeyDown,
-    handleFocus,
-  } = useListFocus<HTMLUListElement>({
-    itemSelector: 'a[href]',
-    orientation: 'vertical',
-    hasRovingTabIndex: true,
-  });
-
-  // Seat the tab stop on the *active* heading. WAI-ARIA puts the single tab
-  // stop on the current item, so tabbing into a table of contents while
-  // reading section 7 lands on section 7 — not back at section 1, which is
-  // where useListFocus would otherwise leave it (it promotes the first item on
-  // mount and then keeps whichever item already holds the stop).
-  //
-  // Only while focus is outside the list: once the reader has arrowed to an
-  // item, the stop is theirs and scroll-spy must not yank it away. Sets
-  // `tabindex` only — it never steals focus. Registered after useListFocus so
-  // it runs after the hook's own layout effect and wins; on later commits the
-  // hook then finds this item already holding the stop and keeps it.
-  useIsomorphicLayoutEffect(() => {
-    const list = listRef.current;
-    if (list == null || list.contains(document.activeElement)) {
-      return;
-    }
-    const links = Array.from(list.querySelectorAll<HTMLElement>('a[href]'));
-    const active = links.find(
-      link => link.getAttribute('aria-current') === 'location',
-    );
-    if (active == null) {
-      return;
-    }
-    for (const link of links) {
-      const tabIndex = link === active ? '0' : '-1';
-      if (link.getAttribute('tabindex') !== tabIndex) {
-        link.setAttribute('tabindex', tabIndex);
-      }
-    }
-  });
-
   /**
    * The single navigation path, shared by click and keyboard activation:
    * push the hash, then hand off to the scroll-spy's `scrollTo`, which fires
@@ -480,12 +433,7 @@ export function Outline({
         className,
         style,
       )}>
-      <ul
-        {...stylex.props(styles.list)}
-        ref={listRef}
-        role="list"
-        onKeyDown={handleListKeyDown}
-        onFocus={handleFocus}>
+      <ul {...stylex.props(styles.list)} role="list">
         {items.map(item => {
           const isActive = item.id === resolvedActiveId;