@astryxdesign/core 0.1.0-canary.f94dd07 → 0.1.1-canary.a514b99

package/src/Icon/Icon.doc.mjs

@@ -17,7 +17,7 @@ export const docs = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: 'Color variant mapped to XDS icon color tokens.',
+      description: 'Color variant mapped to Astryx icon color tokens.',
       default: "'inherit'",
     },
     {
@@ -62,7 +62,7 @@ export const docsZh = {
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: '映射到 XDS 图标颜色令牌的颜色变体。',
+      description: '映射到 Astryx 图标颜色令牌的颜色变体。',
       default: "'inherit'",
     },
     {
@@ -96,7 +96,7 @@ export const docsZh = {
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
   description:
-    'Renders icons w/ XDS design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
+    'Renders icons w/ Astryx design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
   usage: {
     description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
     bestPractices: [
@@ -113,7 +113,7 @@ export const docsDense = {
   },
   propDescriptions: {
     icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
-    color: 'Color variant mapped to XDS icon color tokens.',
+    color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
   },
 };

package/src/Item/Item.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
   ],
   usage: {
     description:
-      'A single, flexible item primitive that unifies the "start content + label + description + end content" pattern across XDS. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',
+      'A single, flexible item primitive that unifies the "start content + label + description + end content" pattern across Astryx. Use it wherever you need a structured row: dropdown menus, selectors, contact lists, notifications, file browsers, and activity feeds.',
     bestPractices: [
       {guidance: true, description: 'Use named slots (startContent, label, description, endContent) for the common layout. These cover the 80% case.'},
       {guidance: true, description: 'Use density="compact" for menus and dense lists, "balanced" for standard rows, and "spacious" for roomier layouts.'},
@@ -104,7 +104,7 @@ export const docsZh = {
   ],
   usage: {
     description:
-      '通用项目原语，统一 XDS 中 "起始内容 + 标签 + 描述 + 结束内容" 的布局模式。适用于下拉菜单、选择器、联系人列表、通知、文件浏览器和活动流等场景。',
+      '通用项目原语，统一 Astryx 中 "起始内容 + 标签 + 描述 + 结束内容" 的布局模式。适用于下拉菜单、选择器、联系人列表、通知、文件浏览器和活动流等场景。',
     bestPractices: [
       {guidance: true, description: '使用命名插槽（startContent、label、description、endContent）处理常见布局。'},
       {guidance: true, description: '菜单和密集列表使用 density="compact"，标准行使用 "balanced"，宽松布局使用 "spacious"。'},

package/src/Layout/Layout.doc.mjs

@@ -29,7 +29,8 @@ export const docs = {
     {
       name: 'content',
       type: 'ReactNode',
-      description: 'Main content area (center).',
+      description:
+        'Main content area (center). Children passed to `<Layout>` render here too — `<Layout>{main}</Layout>` is shorthand for `<Layout content={main} />`.',
       slotElements: [
         {
           __element: 'LayoutContent',

package/src/Layout/Layout.tsx

@@ -157,6 +157,16 @@ export interface LayoutProps extends Omit<BaseProps, 'content'> {
    * Inline styles to apply to the root element.
    */
   style?: React.CSSProperties;
+
+  /**
+   * Children are a shorthand for the `content` slot:
+   * `<Layout>{main}</Layout>` is equivalent to `<Layout content={main} />`.
+   * The surrounding zones (`header`/`start`/`end`/`footer`) stay explicit
+   * props. If both `content` and `children` are provided, `content` wins.
+   * Accepting children keeps the natural `<Layout>…</Layout>` form from
+   * rendering a blank shell.
+   */
+  children?: ReactNode;
 }
 
 /**
@@ -222,6 +232,7 @@ function AreaProvider({
  * ```
  */
 export function Layout({
+  children,
   content,
   contentWidth,
   defaultHasDividers,
@@ -237,6 +248,9 @@ export function Layout({
   style,
 }: LayoutProps) {
   const isFill = height === 'fill';
+  // Children are a shorthand for the content slot; an explicit `content` prop
+  // wins when both are provided.
+  const resolvedContent = content ?? children;
 
   const dividerCtxValue = useMemo(
     () => (defaultHasDividers != null ? {defaultHasDividers} : null),
@@ -287,7 +301,7 @@ export function Layout({
             )}>
             <AreaProvider area="start">{start}</AreaProvider>
             <div {...stylex.props(...stackItem({size: 'fill'}))}>
-              <AreaProvider area="content">{content}</AreaProvider>
+              <AreaProvider area="content">{resolvedContent}</AreaProvider>
             </div>
             <AreaProvider area="end">{end}</AreaProvider>
           </div>

package/src/Layout/__tests__/childrenAsContent.test.tsx

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file childrenAsContent.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Verifies Layout renders children as a shorthand for the content slot
+ *   (so the natural `<Layout>…</Layout>` form never renders a blank shell), with
+ *   an explicit `content` prop taking precedence.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Layout} from '../Layout';
+import {LayoutContent} from '../LayoutContent';
+
+describe('Layout children-as-content', () => {
+  it('renders nested children in the content slot', () => {
+    render(
+      <Layout>
+        <LayoutContent>
+          <span data-testid="body">Body</span>
+        </LayoutContent>
+      </Layout>,
+    );
+    expect(screen.getByTestId('body')).toBeInTheDocument();
+  });
+
+  it('renders bare children (no LayoutContent wrapper) too', () => {
+    render(
+      <Layout>
+        <span data-testid="bare">Bare</span>
+      </Layout>,
+    );
+    expect(screen.getByTestId('bare')).toBeInTheDocument();
+  });
+
+  it('lets an explicit content prop win over children', () => {
+    render(
+      <Layout content={<span data-testid="slot">Slot</span>}>
+        <span data-testid="child">Child</span>
+      </Layout>,
+    );
+    expect(screen.getByTestId('slot')).toBeInTheDocument();
+    expect(screen.queryByTestId('child')).not.toBeInTheDocument();
+  });
+
+  it('still supports the canonical slot-only API', () => {
+    render(
+      <Layout
+        content={
+          <LayoutContent>
+            <span data-testid="canon">Canonical</span>
+          </LayoutContent>
+        }
+      />,
+    );
+    expect(screen.getByTestId('canon')).toBeInTheDocument();
+  });
+});

package/src/Link/Link.doc.mjs

@@ -99,7 +99,7 @@ export const docs = {
       isHiddenFromOverview: true,
       displayName: 'Link Provider',
       description:
-        'Provider that sets the default link component for all XDS link-rendering components in the subtree. ' +
+        'Provider that sets the default link component for all Astryx link-rendering components in the subtree. ' +
         'Wrap your app root to replace native <a> elements with your framework router (Next.js Link, React Router Link, etc.).',
       props: [
         {
@@ -226,7 +226,7 @@ export const docsZh = {
       isHiddenFromOverview: true,
       displayName: 'Link Provider',
       description:
-        '为子树中所有 XDS 链接组件设置默认链接组件的 Provider。',
+        '为子树中所有 Astryx 链接组件设置默认链接组件的 Provider。',
       props: [
         {
           name: 'component',
@@ -310,7 +310,7 @@ export const docsDense = {
       isHiddenFromOverview: true,
       displayName: 'Link Provider',
       description:
-        'Provider setting default link component for all XDS links in subtree.',
+        'Provider setting default link component for all Astryx links in subtree.',
       propDescriptions: {
         component: 'Component for all link elements',
         children: 'Subtree',

package/src/Link/LinkProvider.doc.mjs

@@ -10,7 +10,7 @@ export const docs = {
   isHiddenFromOverview: true,
   keywords: ['link', 'provider', 'router', 'nextjs', 'client-side-routing'],
   usage: {
-    description: 'Wraps your app to replace the default <a> tag with a framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+    description: 'Wraps your app to replace the default <a> tag with a framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
   },
   props: [
     {name: 'component', type: 'LinkComponentType', required: true, description: 'Link component to use for all link elements in the subtree (e.g. Next.js Link).'},
@@ -20,9 +20,9 @@ export const docs = {
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
-  description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+  description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
   usage: {
-    description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+    description: 'Wraps app to replace default <a> tag w/ framework-specific link component (e.g. Next.js Link) for client-side routing across all Astryx components.',
   },
   propDescriptions: {
     component: 'link component for all link elements in subtree (e.g. Next.js Link)',

package/src/Markdown/Markdown.doc.mjs

@@ -131,7 +131,7 @@ export const docs = {
   },
   usage: {
     description:
-      'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
+      'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
@@ -294,7 +294,7 @@ export const docsZh = {
   },
   usage: {
     description:
-      'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
+      'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
@@ -306,10 +306,10 @@ export const docsZh = {
 
 export const docsDense = {
   description:
-    'Renders markdown string as XDS-styled components. Use for user-generated content, AI responses, docs. Headings, lists, tables, code, citations w/ consistent styling.',
+    'Renders markdown string as Astryx-styled components. Use for user-generated content, AI responses, docs. Headings, lists, tables, code, citations w/ consistent styling.',
   usage: {
     description:
-      'Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
+      'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
       { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
       { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },

package/src/Outline/Outline.doc.mjs

@@ -228,7 +228,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 via IntersectionObserver topmost-visible-heading; controlled with activeId; smooth-scroll on click.',
+    '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.',
   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.',

package/src/Outline/Outline.test.tsx

@@ -37,7 +37,13 @@ describe('parseOutlineFromMarkdown', () => {
       parseOutlineFromMarkdown(
         '## **Install** `@astryxdesign/core`\n\n```\n# Not a heading\n```',
       ),
-    ).toEqual([{id: 'install-astryxdesign-core', label: 'Install @astryxdesign/core', level: 2}]);
+    ).toEqual([
+      {
+        id: 'install-astryxdesign-core',
+        label: 'Install @astryxdesign/core',
+        level: 2,
+      },
+    ]);
   });
 
   it('deduplicates generated ids', () => {
@@ -87,7 +93,7 @@ describe('Outline', () => {
     ).not.toHaveAttribute('aria-current');
   });
 
-  it('smooth-scrolls and reports active id on click', async () => {
+  it('smooth-scrolls and defers the indicator until the scroll settles when uncontrolled', async () => {
     const user = userEvent.setup();
     const target = document.createElement('h2');
     target.id = 'install';
@@ -101,6 +107,47 @@ describe('Outline', () => {
       behavior: 'smooth',
       block: 'start',
     });
+    // Uncontrolled: the indicator is deferred during the programmatic scroll,
+    // so it has not moved to the clicked item yet.
+    expect(
+      screen.getByRole('link', {name: 'Installation'}),
+    ).not.toHaveAttribute('aria-current', 'true');
+
+    // When the scroll settles, the indicator lands on the clicked item.
+    act(() => {
+      window.dispatchEvent(new Event('scrollend'));
+    });
+    expect(onActiveIdChange).toHaveBeenCalledWith('install');
+    expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
+      'aria-current',
+      'true',
+    );
+
+    document.body.removeChild(target);
+  });
+
+  it('reports active id on click when controlled', async () => {
+    const user = userEvent.setup();
+    const target = document.createElement('h2');
+    target.id = 'install';
+    document.body.appendChild(target);
+    const onActiveIdChange = vi.fn();
+
+    render(
+      <Outline
+        items={items}
+        activeId="intro"
+        onActiveIdChange={onActiveIdChange}
+      />,
+    );
+    await user.click(screen.getByRole('link', {name: 'Installation'}));
+
+    expect(target.scrollIntoView).toHaveBeenCalledWith({
+      behavior: 'smooth',
+      block: 'start',
+    });
+    // Controlled: there is no built-in scroll-spy, so the consumer owns the
+    // active state and must be notified on click.
     expect(onActiveIdChange).toHaveBeenCalledWith('install');
 
     document.body.removeChild(target);
@@ -122,11 +169,7 @@ describe('Outline', () => {
 
   it('renders with density="compact"', () => {
     render(
-      <Outline
-        items={items}
-        density="compact"
-        data-testid="outline-compact"
-      />,
+      <Outline items={items} density="compact" data-testid="outline-compact" />,
     );
     expect(screen.getByTestId('outline-compact').className).toContain(
       'compact',
@@ -201,50 +244,45 @@ describe('Outline', () => {
     ).not.toHaveAttribute('aria-current');
   });
 
-  it('updates uncontrolled active id from IntersectionObserver', () => {
-    let observerCallback: IntersectionObserverCallback | undefined;
-
-    class MockIntersectionObserver {
-      observe = vi.fn();
-      disconnect = vi.fn();
-
-      constructor(callback: IntersectionObserverCallback) {
-        observerCallback = callback;
-      }
-    }
-
-    vi.stubGlobal('IntersectionObserver', MockIntersectionObserver);
-
+  it('updates uncontrolled active id from scroll position', () => {
     const intro = document.createElement('h2');
     intro.id = 'intro';
+    const install = document.createElement('h3');
+    install.id = 'install';
     const api = document.createElement('h3');
     api.id = 'api';
-    document.body.append(intro, api);
+    document.body.append(intro, install, api);
 
-    const onActiveIdChange = vi.fn();
-    render(<Outline items={items} onActiveIdChange={onActiveIdChange} />);
+    // Not at the bottom of the page.
+    Object.defineProperty(document.documentElement, 'scrollHeight', {
+      value: 4000,
+      configurable: true,
+    });
 
-    const entry: IntersectionObserverEntry = {
-      target: api,
-      isIntersecting: true,
-      boundingClientRect: {top: 12} as DOMRectReadOnly,
-      intersectionRatio: 1,
-      intersectionRect: {} as DOMRectReadOnly,
-      rootBounds: null,
-      time: 0,
-    };
+    // intro + install have scrolled above the activation line (top <= 0);
+    // api is still below it, so install is the last passed heading.
+    vi.spyOn(intro, 'getBoundingClientRect').mockReturnValue({
+      top: -200,
+    } as DOMRect);
+    vi.spyOn(install, 'getBoundingClientRect').mockReturnValue({
+      top: -10,
+    } as DOMRect);
+    vi.spyOn(api, 'getBoundingClientRect').mockReturnValue({
+      top: 400,
+    } as DOMRect);
 
-    act(() => {
-      observerCallback?.([entry], {} as IntersectionObserver);
-    });
+    const onActiveIdChange = vi.fn();
+    // The hook resolves the active id from scroll position on mount.
+    render(<Outline items={items} onActiveIdChange={onActiveIdChange} />);
 
-    expect(screen.getByRole('link', {name: 'API'})).toHaveAttribute(
+    expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
       'true',
     );
-    expect(onActiveIdChange).toHaveBeenCalledWith('api');
+    expect(onActiveIdChange).toHaveBeenCalledWith('install');
 
     document.body.removeChild(intro);
+    document.body.removeChild(install);
     document.body.removeChild(api);
   });
 });

package/src/Outline/Outline.tsx

@@ -217,8 +217,9 @@ function getIndentStyle(level: number) {
  * indentation based on each heading level. Features a sliding indicator
  * track that animates to the active item.
  *
- * When `activeId` is omitted, it observes heading elements by id and marks
- * the topmost visible heading active.
+ * When `activeId` is omitted, it tracks scroll position and marks the last
+ * heading whose top has passed its activation line (its scroll-margin-top)
+ * active — defaulting to the first item at the top and the last at the bottom.
  *
  * @example
  * ```
@@ -246,7 +247,12 @@ export function Outline({
 }: OutlineProps) {
   const rootRef = useRef<HTMLElement | null>(null);
   const LinkComponent = useLinkComponent();
-  const [resolvedActiveId, setActiveId] = useScrollSpy({
+  const isControlled = activeId !== undefined;
+  const {
+    activeId: resolvedActiveId,
+    setActiveId,
+    lockActiveId,
+  } = useScrollSpy({
     activeId,
     items,
     onActiveIdChange,
@@ -256,8 +262,9 @@ export function Outline({
   const handleClick =
     (id: string) => (event: React.MouseEvent<HTMLElement>) => {
       const target = document.getElementById(id);
-      setActiveId(id);
 
+      // Let the browser handle modified clicks (open in new tab, etc.) and
+      // missing targets without touching the active state.
       if (
         target == null ||
         event.defaultPrevented ||
@@ -271,6 +278,18 @@ export function Outline({
 
       event.preventDefault();
       window.history.pushState(null, '', `#${id}`);
+
+      // Move the indicator to the clicked item in a single step. Controlled
+      // consumers own the active state (notify only); uncontrolled mode pins
+      // the active id and suppresses scroll-spy until the next manual scroll,
+      // so the click is honored — even for short/last sections — and the
+      // indicator doesn't chase the smooth scroll through other sections.
+      if (isControlled) {
+        setActiveId(id);
+      } else {
+        lockActiveId(id);
+      }
+
       target.scrollIntoView({behavior: 'smooth', block: 'start'});
     };