@astryxdesign/core 0.7.7-canary.c0929c8 → 0.7.7-canary.c19ca12

package/src/Layer/usePressPin.ts

@@ -6,8 +6,9 @@
  * @file usePressPin.ts
  * @input A hover layer's trigger, open state, show and hide, and its
  *   `triggerBehavior` and `touchTrigger` options
- * @output usePressPin, the press toggle that pins a hover layer open;
- *   isPressPinTrigger; stopPressPinClick; the LayerTriggerBehavior type
+ * @output usePressPin, the press toggle that pins a hover layer open, and
+ *   the app hold behind useTooltip's show() and hide(); isPressPinTrigger;
+ *   stopPressPinClick; the LayerTriggerBehavior type
  * @position Core-internal: one call per hover layer, useTooltip's. It owns
  *   the layer's touch trigger, so the host makes no second touch-trigger call.
  *
@@ -35,12 +36,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>();
@@ -105,8 +104,18 @@ export interface UsePressPinReturn {
   isHeldOpen: () => boolean;
   /** Wires the trigger element, or unwires it with `null`. */
   attach: (element: HTMLElement | null) => void;
-  /** Drops the pin: Escape, or a hide that came from elsewhere. */
+  /** Drops the pin and the app hold: Escape, or a hide from elsewhere. */
   unpin: () => void;
+  /**
+   * The app's `show()`: shows the layer and holds it open, as a pin does,
+   * until `release`, Escape, a press outside, or focus leaving the trigger
+   * and the layer. A controlled layer reports the request instead.
+   */
+  hold: () => void;
+  /** The app's `hide()`: drops the hold and hides the layer. */
+  release: () => void;
+  /** Whether the app's `show()` holds the layer open now. */
+  isAppHeld: () => boolean;
   /**
    * While pinned, focus moving onto an element outside the trigger and the
    * layer closes it. Returns whether the pin decided. The pin calls it for its
@@ -114,8 +123,9 @@ export interface UsePressPinReturn {
    */
   handleFocusLeave: (event: FocusEvent) => boolean;
   /**
-   * Whether the layer shows pinned on a wired trigger. The host then announces
-   * its rendered text, unless the layer has a `label`.
+   * Whether the layer shows pinned on a wired trigger, or held by the app's
+   * `show()`. The host then announces its rendered text, unless the layer has
+   * a `label`.
    */
   isPinShown: boolean;
   /** The layer's touch trigger (useTouchTriggerInternal), wired to the pin. */
@@ -177,8 +187,19 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     setIsPinnedState(next);
   }, []);
 
+  // The app's show() holds the layer on any trigger, in any mode.
+  const isAppHeldRef = useRef(false);
+  const [isAppHeldState, setIsAppHeldState] = useState(false);
+  const setAppHeld = useCallback((next: boolean) => {
+    isAppHeldRef.current = next;
+    setIsAppHeldState(next);
+  }, []);
+
   // The last offered element lets a `triggerBehavior` change rewire it.
   const triggerRef = useRef<HTMLElement | null>(null);
+  // Every offered trigger, in any mode, so focus leaving ends a pin or an
+  // app hold.
+  const focusTargetRef = useRef<HTMLElement | null>(null);
   const offeredRef = useRef<HTMLElement | null>(null);
   // A primitive: re-attaching the same trigger renders nothing.
   const [offeredKind, setOfferedKind] = useState<'none' | 'other' | 'button'>(
@@ -194,6 +215,13 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   // a pinned layer through the pin, so the pin drops with it.
   const hideFromTouch = useCallback(() => {
     const current = optionsRef.current;
+    if (isAppHeldRef.current) {
+      setAppHeld(false);
+      if (current.isOpen !== undefined) {
+        current.report(false);
+        return;
+      }
+    }
     if (current.triggerBehavior === 'toggle' && triggerRef.current != null) {
       if (current.isOpen !== undefined) {
         current.report(false);
@@ -204,7 +232,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
       }
     }
     current.hide();
-  }, [setPinned]);
+  }, [setPinned, setAppHeld]);
 
   const {
     isTouchPointerRef,
@@ -214,11 +242,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,
@@ -239,13 +263,14 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   const close = useCallback(() => {
     const current = optionsRef.current;
     clearTapOpen();
+    setAppHeld(false);
     if (current.isOpen !== undefined) {
       current.report(false);
       return;
     }
     setPinned(false);
     current.hide();
-  }, [setPinned, clearTapOpen]);
+  }, [setPinned, setAppHeld, clearTapOpen]);
 
   const announceName = useCallback(() => {
     const current = optionsRef.current;
@@ -354,6 +379,9 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
 
   const isHeldOpen = useCallback(() => {
     const current = optionsRef.current;
+    if (isAppHeldRef.current && current.isLayerOpen) {
+      return current.isOpen !== false;
+    }
     if (current.triggerBehavior !== 'toggle' || triggerRef.current == null) {
       return false;
     }
@@ -370,7 +398,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
         return false;
       }
       const next = event.relatedTarget;
-      const trigger = triggerRef.current;
+      const trigger = focusTargetRef.current;
       // Focus that leaves for no element is a press's to decide. The trigger
       // can sit in another document, so the check uses its own window.
       const view = trigger?.ownerDocument.defaultView;
@@ -393,6 +421,8 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   );
 
   const unwire = useCallback(() => {
+    focusTargetRef.current?.removeEventListener('focusout', handleFocusLeave);
+    focusTargetRef.current = null;
     const previous = triggerRef.current;
     if (previous == null) {
       return;
@@ -400,7 +430,6 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     previous.removeEventListener('click', handlePress);
     previous.removeEventListener('keydown', handleKeyDown);
     previous.removeEventListener('keyup', handleKeyUp);
-    previous.removeEventListener('focusout', handleFocusLeave);
     const own = ownStateRef.current;
     if (own != null) {
       restoreAttribute(previous, 'aria-expanded', own.expanded);
@@ -429,10 +458,14 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
       }
       settledRef.current = {element, mode: current.triggerBehavior};
       unwire();
-      if (element == null || current.triggerBehavior !== 'toggle') {
+      if (element == null) {
         return;
       }
-      if (!isPressPinTrigger(element)) {
+      // Its own focus-leave listener, in any mode: `focusTrigger="never"`
+      // attaches none, and an app hold needs it on any trigger.
+      element.addEventListener('focusout', handleFocusLeave);
+      focusTargetRef.current = element;
+      if (current.triggerBehavior !== 'toggle' || !isPressPinTrigger(element)) {
         return;
       }
       element.addEventListener('click', handlePress);
@@ -440,8 +473,6 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
         element.addEventListener('keydown', handleKeyDown);
         element.addEventListener('keyup', handleKeyUp);
       }
-      // Its own focus-leave listener: `focusTrigger="never"` attaches none.
-      element.addEventListener('focusout', handleFocusLeave);
       ownStateRef.current = {
         expanded: element.getAttribute('aria-expanded'),
         controls: element.getAttribute('aria-controls'),
@@ -466,7 +497,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',
   );
 
@@ -479,7 +510,31 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     if (isPinnedRef.current) {
       setPinned(false);
     }
-  }, [setPinned]);
+    if (isAppHeldRef.current) {
+      setAppHeld(false);
+    }
+  }, [setPinned, setAppHeld]);
+
+  const hold = useCallback(() => {
+    const current = optionsRef.current;
+    if (!current.isEnabled) {
+      return;
+    }
+    setAppHeld(true);
+    armOutsideDismiss();
+    announceName();
+    if (current.isOpen !== undefined) {
+      current.report(true);
+      return;
+    }
+    current.show();
+  }, [setAppHeld, armOutsideDismiss, announceName]);
+
+  const release = useCallback(() => {
+    close();
+  }, [close]);
+
+  const isAppHeld = useCallback(() => isAppHeldRef.current, []);
 
   // Each path that hides a pinned layer drops the pin itself, so a layer that
   // does not show is never reported expanded.
@@ -496,13 +551,18 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     writeAttribute(trigger, 'aria-controls', isLayerOpen ? layerId : null);
   });
 
-  const isPinShown = isToggleMode && isWired && isExpanded;
+  const isPinShown =
+    (isToggleMode && isWired && isExpanded) ||
+    (isAppHeldState && isLayerOpen && isOpen !== false);
 
   return {
     isToggleTrigger,
     isHeldOpen,
     attach,
     unpin,
+    hold,
+    release,
+    isAppHeld,
     handleFocusLeave,
     isPinShown,
     touch: {

package/src/Lightbox/Lightbox.tsx

@@ -55,6 +55,7 @@ import {
 } from '../i18n/useComponentTranslator';
 import english from '../i18n/generated-english/Lightbox/Lightbox.generated';
 import {isRenderable} from '../utils/isRenderable';
+import {prepareFocusReturnOnRemoval} from '../utils/focusReturn';
 
 registerEnglishFallback(english);
 /**
@@ -445,6 +446,23 @@ export function Lightbox({
     }
   }, [isOpen, hasItem]);
 
+  // A viewer that unmounts while open (rendered only while open, or removed
+  // with the rest of a view) never runs the close branch above. Focus the
+  // removal lost goes back to the opener while the opener is still on the
+  // page.
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog == null) {
+      return;
+    }
+    const returnFocusOnRemoval = prepareFocusReturnOnRemoval(dialog);
+    return () => {
+      if (dialog.open) {
+        returnFocusOnRemoval(triggerElementRef.current);
+      }
+    };
+  }, [hasItem]);
+
   const handleClose = useCallback(() => {
     onOpenChange(false);
   }, [onOpenChange]);

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.',
       },
     },