@astryxdesign/core 0.7.7-canary.4a8a76e → 0.7.7-canary.4e495ec

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;
 

package/src/Outline/useOutlineFromMarkdown.doc.mjs

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useOutlineFromMarkdown',
+  displayName: 'useOutlineFromMarkdown',
+  keywords: [
+    'outline',
+    'table of contents',
+    'toc',
+    'markdown',
+    'headings',
+    'heading ids',
+    'same-page navigation',
+  ],
+  params: [
+    {
+      name: 'markdown',
+      type: 'string',
+      description:
+        'The Markdown source. Pass the same string you render with Markdown.',
+      required: true,
+    },
+    {
+      name: 'options',
+      type: 'ParseOutlineFromMarkdownOptions',
+      description:
+        'Parse options. Omit them for a document that Markdown renders without plugins.',
+      required: false,
+    },
+    {
+      name: 'options.plugins',
+      type: 'ReadonlyArray<MarkdownPluginEntry>',
+      description:
+        'The ordered Markdown plugin list. Pass the same list to Markdown, so transforms, labels and ids agree. The outline is recomputed when the list reference changes.',
+      required: false,
+    },
+    {
+      name: 'options.isFinal',
+      type: 'boolean',
+      description:
+        "Whether the source is complete. Pass false while Markdown's isStreaming is true, so both apply the same transforms.",
+      default: 'true',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'items',
+      type: 'OutlineItem[]',
+      description:
+        "One item per root heading, in document order, ready for Outline's items prop. id is the id Markdown renders on the heading in a complete document without sources, label is the heading's text, and level is its depth from 1 to 6.",
+    },
+  ],
+  usage: {
+    description:
+      'Extracts the headings of a Markdown string for an Outline next to the rendered document. It uses the parser and heading slugs that Markdown uses, so in a complete document each item links to its heading, and fenced code never counts as a heading. The result is memoized on the source and the options. Outside React, use parseOutlineFromMarkdown.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Pass the same string, plugin list and finality to Markdown and this hook, so items match the rendered headings once the content is complete.',
+      },
+      {
+        guidance: true,
+        description:
+          'Declare the plugin list outside the component or memoize it. A new array on each render recomputes the outline.',
+      },
+      {
+        guidance: true,
+        description:
+          'For several documents on one page, install one createMarkdownHeadingLinks per document with headingIdPrefix, so their ids do not collide.',
+      },
+      {
+        guidance: false,
+        description:
+          'Write the items by hand or find headings with a regular expression. They drift from the rendered ids.',
+      },
+      {
+        guidance: false,
+        description:
+          'Expect every item to have a target while content streams. Markdown reveals text gradually and trims unfinished syntax, so a heading can be absent or have another id until the content is complete.',
+      },
+      {
+        guidance: false,
+        description:
+          "Expect an item to link to a heading that cites a Markdown sources entry. The hook does not receive sources, so the ids differ: for '# Intro [ref]', Markdown renders intro and the hook returns intro-ref.",
+      },
+      {
+        guidance: false,
+        description:
+          'Expect an item for a nested heading, such as one in a blockquote. Only root headings become items.',
+      },
+    ],
+  },
+  relatedComponents: ['Outline', 'Markdown'],
+  importPath: '@astryxdesign/core/Outline',
+  category: 'Navigation',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Headings of a Markdown string as OutlineItem[] for an Outline beside the rendered document. Same parser and heading slugs as Markdown; memoized on source and options.',
+  paramDescriptions: {
+    markdown: 'Markdown source; the same string you render with Markdown.',
+    options: 'parse options; omit for a document without plugins.',
+    'options.plugins':
+      'ordered plugin list; pass the same list to Markdown. New reference recomputes.',
+    'options.isFinal':
+      "whether the source is complete; false while Markdown's isStreaming is true.",
+  },
+  returnDescriptions: {
+    items:
+      'one item per root heading in document order: id is the rendered id in a complete document without sources, label is its text, level is 1-6.',
+  },
+  usage: {
+    description:
+      'Headings of a Markdown string for an Outline next to the rendered document. Same parser and slugs as Markdown, so items link to their headings in a complete document. Outside React, use parseOutlineFromMarkdown.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Pass the same string, plugin list and finality to Markdown and the hook; items match the headings once content is complete.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep the plugin list stable; a new array each render recomputes.',
+      },
+      {
+        guidance: true,
+        description:
+          'Several documents on one page: one createMarkdownHeadingLinks per document with headingIdPrefix.',
+      },
+      {
+        guidance: false,
+        description: 'Write items by hand or find headings with a regex.',
+      },
+      {
+        guidance: false,
+        description:
+          'Expect every item to have a target while content streams; a heading can be absent or have another id until complete.',
+      },
+      {
+        guidance: false,
+        description:
+          'Expect an item to link to a heading that cites a Markdown sources entry; the hook does not receive sources, so the ids differ.',
+      },
+      {
+        guidance: false,
+        description:
+          'Expect items for nested headings; only root headings count.',
+      },
+    ],
+  },
+};

package/src/Outline/useOutlineFromMarkdown.ts

@@ -10,6 +10,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Outline/Outline.doc.mjs
+ * - /packages/core/src/Outline/useOutlineFromMarkdown.doc.mjs
  * - /packages/core/src/Outline/index.ts
  */
 

package/src/Outline/useScrollSpy.ts

@@ -410,9 +410,9 @@ export function useScrollSpy({
     const onSettle = () => finish(true);
     const onManual = () => finish(false);
     const onKeyDown = (event: KeyboardEvent) => {
-      // A key the outline itself consumed (arrow roving focus, Space
-      // activation) is prevented, so the browser will not scroll — it is not a
-      // manual scroll intent and must not cancel the navigation it just began.
+      // The outline prevents the Space key that activates a link. The
+      // browser then does not scroll. So this key is not a manual scroll, and
+      // it does not end the navigation.
       if (!event.defaultPrevented && SCROLL_KEYS.has(event.key)) {
         finish(false);
       }

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -65,7 +65,7 @@ export const docs = {
     {
       name: 'hasClear',
       type: 'boolean',
-      description: 'Show a clear-all button for removing all filters.',
+      description: 'Show a clear-all button that removes every editable filter. Read-only filters stay.',
       default: 'true',
     },
     {
@@ -336,7 +336,7 @@ export const docsZh = {
     {
       name: 'hasClear',
       type: 'boolean',
-      description: '显示清除全部按钮以移除所有过滤器。',
+      description: '显示清除全部按钮，移除可编辑的过滤器，保留只读过滤器。',
       default: 'true',
     },
     {
@@ -507,7 +507,7 @@ export const docsDense = {
     isLabelHidden: 'Visually hides label while keeping accessible.',
     placeholder: 'Text shown when no filters selected.',
     hasAutoFocus: 'Auto-focus input on mount.',
-    hasClear: 'Show clear-all button for removing all filters.',
+    hasClear: 'Show clear-all button; removes editable filters, keeps read-only ones.',
     isReadOnly: 'Prevent adding, editing, or removing filters.',
     isDisabled: 'Disables entire component.',
     status: 'Validation status object w/ type + optional message.',