@astryxdesign/core 0.1.7 → 0.1.8-canary.c5fa19b

package/src/Icon/Icon.tsx

@@ -111,51 +111,64 @@ const colorStyles = stylex.create({
 /**
  * Size styles for direct SVG icon components.
  * Uses width/height only — SVG components handle their own viewBox scaling.
+ *
+ * Sizes are expressed in `rem` (relative to the root font-size) so icons scale
+ * in step with text when the document font-size changes, matching the rest of
+ * the design system's rem-based type scale. Values are the px-equivalents at a
+ * 16px root: 12px → 0.75rem, 16px → 1rem, 20px → 1.25rem, 24px → 1.5rem.
  */
 const sizeStyles = stylex.create({
   xsm: {
-    width: 12,
-    height: 12,
+    width: '0.75rem',
+    height: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
+    width: '1rem',
+    height: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
+    width: '1.25rem',
+    height: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
+    width: '1.5rem',
+    height: '1.5rem',
   },
 });
 
 /**
  * Size styles for string-based (registry) icons.
  * Includes fontSize so that 1em-based icons from the registry scale correctly.
+ *
+ * Expressed in `rem` for the same reason as {@link sizeStyles} — icons track the
+ * root font-size instead of being locked to absolute pixels.
  */
 const spanSizeStyles = stylex.create({
+  /* eslint-disable @astryx/no-hardcoded-styles -- fontSize here sizes 1em-based
+     registry SVGs to the icon box; icons use their own 12/16/20/24 scale, not
+     the 14px-anchored textSizeVars type scale. Values are rem so icons track
+     the root font-size. */
   xsm: {
-    width: 12,
-    height: 12,
-    fontSize: 12,
+    width: '0.75rem',
+    height: '0.75rem',
+    fontSize: '0.75rem',
   },
   sm: {
-    width: 16,
-    height: 16,
-    fontSize: 16,
+    width: '1rem',
+    height: '1rem',
+    fontSize: '1rem',
   },
   md: {
-    width: 20,
-    height: 20,
-    fontSize: 20,
+    width: '1.25rem',
+    height: '1.25rem',
+    fontSize: '1.25rem',
   },
   lg: {
-    width: 24,
-    height: 24,
-    fontSize: 24,
+    width: '1.5rem',
+    height: '1.5rem',
+    fontSize: '1.5rem',
   },
+  /* eslint-enable @astryx/no-hardcoded-styles */
 });
 
 // =============================================================================
@@ -194,13 +207,57 @@ export interface IconProps extends Omit<
   color?: IconColor;
   /**
    * The size of the icon.
-   * - 'xsm': 12px
-   * - 'sm': 16px
-   * - 'md': 20px
-   * - 'lg': 24px
+   * - 'xsm': 0.75rem (12px at a 16px root)
+   * - 'sm': 1rem (16px at a 16px root)
+   * - 'md': 1.25rem (20px at a 16px root)
+   * - 'lg': 1.5rem (24px at a 16px root)
    * @default 'md'
    */
   size?: IconSize;
+  /**
+   * Accessible name for the icon. Set this only when the icon is MEANINGFUL on
+   * its own — a standalone status glyph or an icon-only indicator with no
+   * adjacent text conveying the same information. Providing it exposes the icon
+   * to assistive tech as `role="img"` with this string as the accessible name
+   * (via `aria-label`) and drops the default `aria-hidden="true"`.
+   *
+   * Omit it (the default) for decorative icons — the common case, e.g. an icon
+   * beside a text label — and the icon stays hidden from assistive tech
+   * (`aria-hidden="true"`). An empty string (`''`) is treated the same as
+   * omitting it (decorative), since an empty accessible name is meaningless.
+   *
+   * Don't set `label` when an interactive parent (Button, IconButton, link)
+   * already names the control — that produces a duplicate announcement.
+   *
+   * @example
+   * ```
+   * // Meaningful, standalone icon
+   * <Icon icon="success" label="Completed" />
+   *
+   * // Decorative icon (default) — omit label
+   * <Icon icon="search" />
+   * ```
+   */
+  label?: string;
+}
+
+/**
+ * Derives the ARIA attributes for an icon from its `label` prop.
+ *
+ * - Non-empty `label` → meaningful image: `role="img"` + `aria-label`, and no
+ *   `aria-hidden` (an `aria-hidden` element is removed from the accessibility
+ *   tree, so its accessible name would be ignored).
+ * - Omitted or empty `label` → decorative default: `aria-hidden="true"`.
+ *
+ * The result is spread BEFORE `{...props}` in both render modes so an explicit
+ * `aria-hidden` / `role` / `aria-label` from the consumer always wins.
+ */
+function getIconA11yProps(
+  label: string | undefined,
+): {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'} {
+  return label != null && label !== ''
+    ? {role: 'img', 'aria-label': label}
+    : {'aria-hidden': 'true'};
 }
 
 // =============================================================================
@@ -219,9 +276,14 @@ export function Icon({
   icon,
   color = 'inherit',
   size = 'md',
+  label,
   ref,
   ...props
 }: IconProps) {
+  // Derive ARIA from `label`: decorative (aria-hidden) by default, or a
+  // meaningful image (role="img" + aria-label) when `label` is non-empty.
+  const a11yProps = getIconA11yProps(label);
+
   // String mode: resolve from icon registry, wrap in styled span
   if (typeof icon === 'string') {
     return (
@@ -229,6 +291,7 @@ export function Icon({
         name={icon}
         color={color}
         size={size}
+        a11yProps={a11yProps}
         spanProps={props}
       />
     );
@@ -239,7 +302,10 @@ export function Icon({
   return (
     <IconComponent
       ref={ref}
-      aria-hidden="true"
+      // Derived a11y (decorative default or meaningful `label`) is spread
+      // BEFORE {...props} so an explicit aria-hidden/role/aria-label from the
+      // consumer still wins as an escape hatch.
+      {...a11yProps}
       {...mergeProps(
         themeProps('icon', {size, color}),
         stylex.props(styles.root, colorStyles[color], sizeStyles[size]),
@@ -266,11 +332,13 @@ function IconFromRegistry({
   name,
   color,
   size,
+  a11yProps,
   spanProps,
 }: {
   name: IconName;
   color: IconColor;
   size: IconSize;
+  a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};
   spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;
 }) {
   const resolvedIcon = getIcon(name);
@@ -281,11 +349,11 @@ function IconFromRegistry({
 
   return (
     <span
-      // Decorative by default, but placed BEFORE the prop spread so consumers
-      // can override it (e.g. `aria-hidden={false}` + `role="img"` +
-      // `aria-label`) to expose a meaningful standalone icon. This matches
-      // component-mode Icon, which already sets aria-hidden before its spread.
-      aria-hidden="true"
+      // Derived a11y — decorative (aria-hidden) by default, or a meaningful
+      // image (role="img" + aria-label) when `label` is set. Placed BEFORE the
+      // prop spread so consumers can still override it with explicit
+      // aria-hidden/role/aria-label. This mirrors component-mode Icon.
+      {...a11yProps}
       {...(spanProps as React.HTMLAttributes<HTMLSpanElement>)}
       {...mergeProps(
         themeProps('icon', {size, color}),

package/src/Item/Item.doc.mjs

@@ -28,7 +28,7 @@ export const docs = {
       props: [
         {name: 'label', type: 'ReactNode', description: 'Primary text identifying this item. Accepts string (auto-truncated) or ReactNode (for rich content).', required: true},
         {name: 'marker', type: 'ReactNode', description: 'Marker rendered before startContent as a direct flex child. Use for list bullets/counters that need custom baseline alignment.'},
-        {name: 'startContent', type: 'ReactNode', description: 'Content rendered before the label/description area, such as an icon, avatar, or checkbox.', slotElements: [{__element: 'Avatar', props: {name: 'Ada Lovelace', size: 'xsmall'}}, {__element: 'Icon', props: {icon: 'info', size: 'sm', color: 'secondary'}}]},
+        {name: 'startContent', type: 'ReactNode', description: 'Content rendered before the label/description area, such as an icon, avatar, or checkbox.', slotElements: [{__element: 'Avatar', props: {name: 'Ada Lovelace', size: 'sm'}}, {__element: 'Icon', props: {icon: 'info', size: 'sm', color: 'secondary'}}]},
         {name: 'description', type: 'ReactNode', description: 'Secondary text: subtitle, description, or supporting info.'},
         {name: 'endContent', type: 'ReactNode', description: 'Content rendered after the label/description area, such as badges, metadata, timestamps, or action buttons.', slotElements: [{__element: 'Badge', props: {label: 3}}, {__element: 'Text', props: {color: 'secondary'}, children: '2h ago'}]},
         {name: 'as', type: "'div' | 'li' | 'span'", description: 'HTML element to render as the root.', default: "'div'"},

package/src/NumberInput/NumberInput.doc.mjs

@@ -82,12 +82,12 @@ export const docs = {
     {
       name: 'startIcon',
       type: 'IconType',
-      description: 'Icon to display at the start of the input. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon to display at the start of the input. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon to display before the label text. See `npx astryx docs icons` for valid semantic names.',
+      description: 'Icon to display before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'status',

package/src/Outline/Outline.doc.mjs

@@ -72,6 +72,38 @@ export const docs = {
           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',
@@ -137,6 +169,51 @@ function MarkdownOutline({markdown}) {
   const items = useOutlineFromMarkdown(markdown);
   return <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)}
+    />
+  );
+}
 `,
         },
       ],
@@ -144,14 +221,17 @@ function MarkdownOutline({markdown}) {
   ],
   usage: {
     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.',
+      '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.',
     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.'},
+      {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.'},
     ],
   },
 };
@@ -205,6 +285,33 @@ export const docsZh = {
           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',
@@ -230,7 +337,7 @@ export const docsZh = {
 /** @type {import('../docs-types').TranslationDoc} */
 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 scroll-margin-top line; first item at top, last at bottom); controlled with activeId; smooth-scroll on click that pins the active item until the next manual scroll.',
+    '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.',
   usage: {
     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.',
@@ -239,8 +346,11 @@ export const docsDense = {
       {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.'},
+      {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: {
@@ -249,6 +359,11 @@ export const docsDense = {
     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: [
@@ -256,13 +371,18 @@ export const docsDense = {
       name: 'Outline',
       displayName: 'Outline',
       description:
-        'Document outline nav with sliding indicator. Renders heading anchors with a density variant and manages scroll-spy active state when uncontrolled.',
+        '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.',
       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.',
       },
     },