Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
21.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
const anatomy = [
  {
    name: 'Outline',
    required: true,
    description:
      'Navigation container for the same-page heading links and indicator.',
  },
  {
    name: 'Heading link',
    required: true,
    description:
      'Anchor for one heading, indented by level and marked when active.',
  },
  {
    name: 'Label',
    required: true,
    description: 'Heading text displayed inside its heading link.',
  },
  {
    name: 'Indicator track',
    required: true,
    description: 'Painted vertical rule behind the active indicator.',
  },
  {
    name: 'Active indicator',
    required: true,
    description:
      'Sliding bar positioned beside the currently active heading link.',
  },
];

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */

export const docs = {
  name: 'Outline',
  displayName: 'Outline',
  group: 'Outline',
  category: 'Navigation',
  keywords: [
    'outline',
    'table of contents',
    'toc',
    'heading navigation',
    'scroll spy',
    'documentation',
    'anchors',
    'sliding indicator',
  ],
  playground: {
    defaults: {
      items: [
        {id: 'overview', label: 'Overview', level: 2},
        {id: 'installation', label: 'Installation', level: 2},
        {id: 'configuration', label: 'Configuration', level: 3},
        {id: 'api-reference', label: 'API reference', level: 2},
      ],
    },
  },
  theming: {
    targets: [
      {className: 'astryx-outline', visualProps: ['density']},
      {className: 'astryx-outline-indicator'},
      {
        className: 'astryx-outline-item',
        visualProps: ['level'],
        states: ['active'],
      },
    ],
  },
  components: [
    {
      name: 'Outline',
      displayName: 'Outline',
      description:
        'Document outline navigation with sliding indicator track. Renders a flat heading list as anchor links with a density variant and scroll-spy active state when uncontrolled.',
      props: [
        {
          name: 'items',
          type: 'OutlineItem[]',
          description:
            'Ordered heading items. Each item has id, label, and level (1-6). The id should match the target heading element id.',
          required: true,
        },
        {
          name: 'activeId',
          type: 'string',
          description:
            'Currently active heading id. Providing this prop makes active state controlled and disables built-in scroll-spy.',
        },
        {
          name: 'onActiveIdChange',
          type: '(id: string) => void',
          description:
            'Called when the active item changes from built-in scroll-spy or from an outline link click.',
        },
        {
          name: 'label',
          type: 'string',
          description: 'Accessible label for the nav landmark.',
          default: "'Table of contents'",
        },
        {
          name: 'density',
          type: "'default' | 'compact'",
          description:
            "Density variant controlling item padding. 'compact' for dense UIs, 'default' for standard spacing.",
          default: "'default'",
        },
        {
          name: 'onNavigateStart',
          type: '(id: string) => void',
          description:
            'Called with the item id when navigation begins, before the scroll starts. Pair with onNavigateEnd to drive an arrival effect (flash, ring, pulse) on the target heading.',
        },
        {
          name: 'onNavigateEnd',
          type: '(id: string) => void',
          description:
            'Called with the item id once the navigation resolves - when the smooth scroll settles, or when reduced motion turns it into an instant jump. Fires exactly once per onNavigateStart, including when the user interrupts the scroll, so a "navigating" state can never leak.',
        },
        {
          name: 'offset',
          type: 'number',
          description:
            "Height in px of a fixed header overlaying the top of the scroll root. Shifts both the activation line and the scroll landing by the same amount, so a heading activates exactly where navigating to it puts it - below the header, not underneath it. Composes with each heading's own scroll-margin-top (the header, then the breathing room below it); it does not replace it. Leave at 0 when nothing overlays the content and let scroll-margin-top do the work.",
          default: '0',
        },
        {
          name: 'scrollContainerRef',
          type: 'React.RefObject<HTMLElement | null>',
          description:
            'Scroll container to track, instead of auto-detecting the nearest scrollable ancestor. Use it when content scrolls inside a split pane, modal, or dashboard panel rather than the viewport.',
        },
        {
          name: 'hasScrollOnClick',
          type: 'boolean',
          description:
            'Whether activating an item smooth-scrolls to it. Set to false to own the scrolling yourself (virtualized content, a router): the Outline still updates the active item, the hash, and the navigate callbacks, but performs no scroll.',
          default: 'true',
        },
        {
          name: 'xstyle',
          type: 'StyleXStyles',
          description:
            'StyleX styles for layout customization. Must be a stylex.create() value.',
        },
      ],
      examples: [
        {
          label: 'Basic',
          code: `
import {Outline} from '@astryxdesign/core/Outline';

const items = [
  {id: 'overview', label: 'Overview', level: 2},
  {id: 'installation', label: 'Installation', level: 2},
  {id: 'theming', label: 'Theming', level: 2},
  {id: 'tokens', label: 'Tokens', level: 3},
  {id: 'accessibility', label: 'Accessibility', level: 2},
];

// Uncontrolled: built-in scroll-spy tracks the topmost visible heading.
<Outline items={items} />;
`,
        },
        {
          label: 'Compact (density="compact")',
          code: `
import {Outline} from '@astryxdesign/core/Outline';

// Dense sidebars use the compact variant; the sliding indicator
// automatically matches the shorter item height.
<Outline items={items} density="compact" />;
`,
        },
        {
          label: 'Controlled active section',
          code: `
import {useState} from 'react';
import {Outline} from '@astryxdesign/core/Outline';

function ControlledOutline() {
  const [activeId, setActiveId] = useState('overview');

  // Providing activeId disables built-in scroll-spy; you own the active state.
  return (
    <Outline
      items={items}
      activeId={activeId}
      onActiveIdChange={setActiveId}
    />
  );
}
`,
        },
        {
          label: 'Generate items from markdown',
          code: `
import {Markdown} from '@astryxdesign/core/Markdown';
import {createMarkdownHeadingLinks} from '@astryxdesign/core/Markdown/plugins';
import {Outline, useOutlineFromMarkdown} from '@astryxdesign/core/Outline';

const markdownRootId = 'guide';
const plugins = [
  createMarkdownHeadingLinks({headingIdPrefix: markdownRootId}),
];

function MarkdownOutline({markdown, isStreaming}) {
  // Pass the same plugin entry and finality to Markdown and Outline. Nested
  // headings consume the shared depth-first sequence, while Outline continues
  // to return root headings only.
  const items = useOutlineFromMarkdown(markdown, {
    plugins,
    isFinal: !isStreaming,
  });
  return (
    <>
      <Markdown id={markdownRootId} plugins={plugins}>{markdown}</Markdown>
      <Outline items={items} />
    </>
  );
}
`,
        },
        {
          label: 'Scoped scroll container (split pane, modal, panel)',
          code: `
import {useRef} from 'react';
import {Outline} from '@astryxdesign/core/Outline';

function PanelDocs() {
  const scrollContainerRef = useRef(null);

  // Without scrollContainerRef the outline auto-detects the nearest scrollable
  // ancestor, which is the viewport here - so the highlight would never move.
  return (
    <div style={{display: 'flex'}}>
      <div ref={scrollContainerRef} style={{overflowY: 'auto', height: 480}}>
        <h2 id="overview">Overview</h2>
        {/* ...content... */}
      </div>
      <Outline items={items} scrollContainerRef={scrollContainerRef} offset={64} />
    </div>
  );
}
`,
        },
        {
          label: 'Navigate callbacks (flash the heading on arrival)',
          code: `
import {useState} from 'react';
import {Outline} from '@astryxdesign/core/Outline';

function FlashOnArrival() {
  const [flashId, setFlashId] = useState(null);

  // onNavigateEnd fires once the smooth scroll settles - and once per
  // onNavigateStart even if the user scrolls away mid-jump, so this never
  // gets stuck.
  return (
    <Outline
      items={items}
      onNavigateStart={() => setFlashId(null)}
      onNavigateEnd={id => setFlashId(id)}
    />
  );
}
`,
        },
      ],
    },
  ],
  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. 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.',
      },
    ],
  },
};

/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docsZh = {
  name: 'Outline',
  displayName: 'Outline',
  group: 'Outline',
  theming: {
    targets: [
      {className: 'astryx-outline', visualProps: ['density']},
      {className: 'astryx-outline-indicator'},
      {
        className: 'astryx-outline-item',
        visualProps: ['level'],
        states: ['active'],
      },
    ],
  },
  components: [
    {
      name: 'Outline',
      displayName: 'Outline',
      description:
        '文档大纲导航,带有滑动指示器轨道。将扁平标题列表渲染为锚点链接,支持密度变体和非受控模式下的滚动监听。',
      props: [
        {
          name: 'items',
          type: 'OutlineItem[]',
          description:
            '有序标题项。每项包含 id、label 和 level (1-6)。id 应匹配目标标题元素的 id。',
          required: true,
        },
        {
          name: 'activeId',
          type: 'string',
          description:
            '当前激活的标题 id。提供后组件进入受控模式,并禁用内置滚动监听。',
        },
        {
          name: 'onActiveIdChange',
          type: '(id: string) => void',
          description: '当内置滚动监听或点击大纲链接改变激活项时调用。',
        },
        {
          name: 'label',
          type: 'string',
          description: 'nav 地标的无障碍标签。',
          default: "'Table of contents'",
        },
        {
          name: 'density',
          type: "'default' | 'compact'",
          description:
            "控制项目内边距的密度变体。'compact' 用于紧凑界面,'default' 为标准间距。",
          default: "'default'",
        },
        {
          name: 'onNavigateStart',
          type: '(id: string) => void',
          description:
            '导航开始时(滚动前)调用,传入项目 id。与 onNavigateEnd 搭配可在目标标题上实现到达效果(闪烁、描边、脉冲)。',
        },
        {
          name: 'onNavigateEnd',
          type: '(id: string) => void',
          description:
            '导航结束时调用(平滑滚动停止,或减弱动效将其变为瞬时跳转)。每次 onNavigateStart 必定对应一次调用,包括用户中途手动滚动打断的情况,因此“导航中”状态不会泄漏。',
        },
        {
          name: 'offset',
          type: 'number',
          description:
            '覆盖滚动根顶部的固定顶栏高度(px)。同时位移激活线与滚动落点,因此标题被激活的位置正是点击后停留的位置——落在顶栏下方,而非被顶栏遮住。它与每个标题自身的 scroll-margin-top 叠加(先顶栏,再留白),而非取代它。若没有元素覆盖内容,保持 0,交给 scroll-margin-top 处理。',
          default: '0',
        },
        {
          name: 'scrollContainerRef',
          type: 'React.RefObject<HTMLElement | null>',
          description:
            '要跟踪的滚动容器,替代自动探测最近的可滚动祖先。当内容在分栏、弹窗或面板中滚动而非视口时使用。',
        },
        {
          name: 'hasScrollOnClick',
          type: 'boolean',
          description:
            '激活项目时是否平滑滚动。设为 false 可自行接管滚动(虚拟列表、路由):Outline 仍会更新激活项、hash 和导航回调,但不执行滚动。',
          default: 'true',
        },
        {
          name: 'xstyle',
          type: 'StyleXStyles',
          description:
            '用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。',
        },
      ],
    },
  ],
  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: 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.',
      },
    ],
  },
};

/** @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. 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.',
      },
    ],
  },
  propDescriptions: {
    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.',
    xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
  },
  components: [
    {
      name: 'Outline',
      displayName: 'Outline',
      description:
        '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.',
        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' | '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.',
        xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
      },
    },
  ],
};