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

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,8 @@ 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',
     },
     {
@@ -173,17 +174,20 @@ export const docs = {
     {
       name: 'menuWidth',
       type: 'number',
-      description: 'Maximum width for the operator/value dropdown menu in pixels.',
+      description:
+        'Maximum width for the operator/value dropdown menu in pixels.',
     },
     {
       name: 'maxOperatorMenuItems',
       type: 'number',
-      description: 'Maximum number of items displayed in the operator dropdown.',
+      description:
+        'Maximum number of items displayed in the operator dropdown.',
     },
     {
       name: 'tokenOverflowBehavior',
       type: "'none' | 'unfocusedInline' | 'unfocusedLayer'",
-      description: 'Controls how tokens overflow when the container is too narrow. Forwarded to Tokenizer.',
+      description:
+        'Controls how tokens overflow when the container is too narrow. Forwarded to Tokenizer.',
       default: "'none'",
     },
     {
@@ -202,6 +206,25 @@ export const docs = {
       description:
         'StyleX styles for layout customization. Must be a stylex.create() value.',
     },
+    {
+      name: 'experimental',
+      type: "{presentation?: 'popover' | 'bottom-sheet' | 'adaptive'}",
+      stability: 'experimental',
+      description:
+        "Experimental options: anything in this object may change or be removed in a patch release, and omitting it keeps the stable behavior. presentation (default 'popover') chooses how the field presents filter editing. popover is the tokenizer field with its typeahead and the editor popover. bottom-sheet makes the whole field one trigger showing display-only filter tokens: it opens a Filters sheet listing the filters as rows that edit or remove a filter, with Add filter, Done, and Clear all (which asks first and keeps read-only filters); an Add filter sheet with the fields (or the content search with inline suggestions) opens above it, and a value step that stages operator → value and confirms from its footer opens above that. Dismissing a step reveals the one beneath. List values edit through the Tokenizer's own sheet. adaptive uses the bottom sheet on compact touch screens and the popover otherwise, resolved the same way Selector resolves it. In the sheet presentation menuWidth and tokenOverflowBehavior have no surface to act on and warn in development.",
+    },
+  ],
+  examples: [
+    {
+      label: 'Touch sheet on compact screens (experimental)',
+      code: `const [filters, setFilters] = useState([]);
+<PowerSearch
+  config={config}
+  filters={filters}
+  onChange={next => setFilters(next)}
+  experimental={{presentation: 'adaptive'}}
+/>`,
+    },
   ],
   // `config` and `filters` are custom values the docsite preview cannot
   // generate automatically. Keep this small, but include an initial token so
@@ -276,6 +299,22 @@ export const docs = {
   },
   theming: {
     targets: [{className: 'astryx-power-search'}],
+    vars: [
+      {
+        name: '--_power-search-sheet-hit-inset',
+        description:
+          "Outset of the invisible hit area of the touch sheet's icon-sized actions (the Filters header's Add filter and each row's remove button), applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the action to a 44px touch target without changing what is drawn.",
+        default: '0px',
+        private: true,
+      },
+      {
+        name: '--_power-search-sheet-hit-content',
+        description:
+          'Whether the touch sheet\'s invisible hit overlay exists. `none` on a fine pointer, so no ::after is generated and hover still reaches the action; `""` on a coarse one, where the overlay provides the 44px touch target.',
+        default: 'none',
+        private: true,
+      },
+    ],
   },
 };
 
@@ -336,7 +375,7 @@ export const docsZh = {
     {
       name: 'hasClear',
       type: 'boolean',
-      description: '显示清除全部按钮以移除所有过滤器。',
+      description: '显示清除全部按钮，移除可编辑的过滤器，保留只读过滤器。',
       default: 'true',
     },
     {
@@ -439,6 +478,13 @@ export const docsZh = {
       type: 'StyleXStyles',
       description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。',
     },
+    {
+      name: 'experimental',
+      type: "{presentation?: 'popover' | 'bottom-sheet' | 'adaptive'}",
+      stability: 'experimental',
+      description:
+        "实验性选项：此对象中的任何内容都可能在补丁版本中更改或移除；省略它即保持稳定行为。presentation（默认 'popover'）决定字段如何呈现筛选编辑：popover 为带有预输入和编辑弹出层的标记字段；bottom-sheet 将整个字段变为一个显示只读筛选标记的触发按钮——点按后打开列出筛选项的「筛选」面板，每行可编辑或移除筛选（含添加筛选、完成、全部清除；全部清除会先确认，并保留只读筛选）；列出字段（或带内联建议的内容搜索）的「添加筛选」面板在其上方打开，按运算符 → 值暂存并在底部确认的取值步骤再在其上方打开。关闭某一步会露出下方的那一步。列表值通过 Tokenizer 自身的面板编辑。adaptive 在紧凑触摸屏上使用底部面板，其他情况使用 popover，解析方式与 Selector 相同。在底部面板呈现中，menuWidth 和 tokenOverflowBehavior 没有作用对象，并会在开发环境中发出警告。",
+    },
   ],
   usage: {
     description:
@@ -507,7 +553,8 @@ 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.',
@@ -532,5 +579,7 @@ export const docsDense = {
     size: 'Search input+token size.',
     xstyle:
       'StyleX styles for layout customization. Must be stylex.create() value.',
+    experimental:
+      "Experimental; may change in a patch. presentation: 'popover' (default, tokenizer field + editor popover) | 'bottom-sheet' (one trigger with display-only tokens + stacked Filters / Add filter / value sheets; rows remove inline; Clear all confirms, keeps read-only; list values via Tokenizer's sheet) | 'adaptive' (sheet on compact touch, else popover).",
   },
 };