@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/Layout/LayoutContent.doc.mjs

@@ -14,6 +14,12 @@ export const docs = {
       type: 'ReactNode',
       description: 'Content.',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        'Internal padding using the spacing scale. Overrides the default padding from the layout container.',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -44,6 +50,11 @@ export const docsZh = {
       type: 'ReactNode',
       description: '内容。',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '使用间距比例的内边距。覆盖布局容器的默认内边距。',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -70,6 +81,7 @@ export const docsDense = {
   description: 'Scrollable main content area.',
   propDescriptions: {
     children: 'Content.',
+    padding: 'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable: 'Enable scrollable overflow.',
     label: 'Accessible label for landmark element.',
     role: 'ARIA landmark role.',

package/src/Layout/LayoutPanel.doc.mjs

@@ -20,6 +20,12 @@ export const docs = {
       description: 'Border on the appropriate edge.',
       default: 'false',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        'Internal padding using the spacing scale. Overrides the default padding from the layout container.',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -36,6 +42,18 @@ export const docs = {
       type: 'AriaRole',
       description: 'ARIA landmark role.',
     },
+    {
+      name: 'width',
+      type: 'number | string',
+      description:
+        'Width of the panel. Numbers are treated as pixels, strings are used as-is. Ignored when resizable is provided; the hook controls width.',
+    },
+    {
+      name: 'resizable',
+      type: 'ResizableProps',
+      description:
+        'Resize props from useResizable(). When provided, the hook drives the panel width and a ResizeHandle should be placed adjacent to the panel.',
+    },
   ],
 };
 
@@ -56,6 +74,11 @@ export const docsZh = {
       description: '相应边缘的边框。',
       default: 'false',
     },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '使用间距比例的内边距。覆盖布局容器的默认内边距。',
+    },
     {
       name: 'isScrollable',
       type: 'boolean',
@@ -72,6 +95,18 @@ export const docsZh = {
       type: 'AriaRole',
       description: 'ARIA 地标角色。',
     },
+    {
+      name: 'width',
+      type: 'number | string',
+      description:
+        '面板宽度。数字按像素处理，字符串按原样使用。提供 resizable 时忽略，宽度由 hook 控制。',
+    },
+    {
+      name: 'resizable',
+      type: 'ResizableProps',
+      description:
+        '来自 useResizable() 的调整大小属性。提供时面板宽度由 hook 驱动，应在面板旁放置 ResizeHandle。',
+    },
   ],
 };
 
@@ -83,8 +118,13 @@ export const docsDense = {
   propDescriptions: {
     children: 'Panel content.',
     hasDivider: 'Border on appropriate edge.',
+    padding: 'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable: 'Enable scrollable overflow.',
     label: 'Accessible label for landmark element.',
     role: 'ARIA landmark role.',
+    width:
+      'Panel width. Numbers = pixels, strings as-is. Ignored when resizable provided; hook controls width.',
+    resizable:
+      'Resize props from useResizable(). Hook drives panel width; place ResizeHandle adjacent.',
   },
 };

package/src/Layout/LayoutSlots.test.tsx

@@ -0,0 +1,364 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file LayoutSlots.test.tsx
+ * @input Uses vitest, @testing-library/react, Layout slot components
+ * @output Characterization tests for LayoutHeader, LayoutFooter,
+ *   LayoutContent and LayoutPanel
+ * @position Testing; validates the slot primitives' rendering, landmark roles,
+ *   divider reflection, sizing and context-driven behavior
+ *
+ * SYNC: When LayoutHeader/LayoutFooter/LayoutContent/LayoutPanel change,
+ * update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {createRef} from 'react';
+import {Layout} from './Layout';
+import {LayoutHeader} from './LayoutHeader';
+import {LayoutFooter} from './LayoutFooter';
+import {LayoutContent} from './LayoutContent';
+import {LayoutPanel} from './LayoutPanel';
+import {LayoutDividerContext} from './LayoutDividerContext';
+import {useResizable} from '../Resizable/useResizable';
+
+// =============================================================================
+// LayoutHeader
+// =============================================================================
+
+describe('LayoutHeader', () => {
+  it('renders its children', () => {
+    render(<LayoutHeader>Page title</LayoutHeader>);
+    expect(screen.getByText('Page title')).toBeInTheDocument();
+  });
+
+  it('carries the astryx-layout-header class', () => {
+    const {container} = render(<LayoutHeader>H</LayoutHeader>);
+    expect(
+      container.querySelector('.astryx-layout-header'),
+    ).toBeInTheDocument();
+  });
+
+  it('exposes a landmark role and accessible name', () => {
+    render(
+      <LayoutHeader role="banner" label="Site header">
+        H
+      </LayoutHeader>,
+    );
+    expect(
+      screen.getByRole('banner', {name: 'Site header'}),
+    ).toBeInTheDocument();
+  });
+
+  it('omits data-divider by default', () => {
+    const {container} = render(<LayoutHeader>H</LayoutHeader>);
+    expect(
+      container
+        .querySelector('.astryx-layout-header')
+        ?.hasAttribute('data-divider'),
+    ).toBe(false);
+  });
+
+  it('reflects hasDivider as data-divider="true"', () => {
+    const {container} = render(<LayoutHeader hasDivider>H</LayoutHeader>);
+    expect(
+      container
+        .querySelector('.astryx-layout-header')
+        ?.getAttribute('data-divider'),
+    ).toBe('true');
+  });
+
+  it('inherits the divider default from LayoutDividerContext', () => {
+    const {container} = render(
+      <LayoutDividerContext value={{defaultHasDividers: true}}>
+        <LayoutHeader>H</LayoutHeader>
+      </LayoutDividerContext>,
+    );
+    expect(
+      container
+        .querySelector('.astryx-layout-header')
+        ?.getAttribute('data-divider'),
+    ).toBe('true');
+  });
+
+  it('an explicit hasDivider={false} overrides an inherited true default', () => {
+    const {container} = render(
+      <LayoutDividerContext value={{defaultHasDividers: true}}>
+        <LayoutHeader hasDivider={false}>H</LayoutHeader>
+      </LayoutDividerContext>,
+    );
+    expect(
+      container
+        .querySelector('.astryx-layout-header')
+        ?.hasAttribute('data-divider'),
+    ).toBe(false);
+  });
+
+  it('applies a numeric height to the element style', () => {
+    const {container} = render(<LayoutHeader height={64}>H</LayoutHeader>);
+    const el = container.querySelector('.astryx-layout-header') as HTMLElement;
+    expect(el.getAttribute('style') ?? '').toContain('64px');
+  });
+
+  it('forwards ref to the outer element', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<LayoutHeader ref={ref}>H</LayoutHeader>);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.className).toContain('astryx-layout-header');
+  });
+
+  it('merges a caller className', () => {
+    const {container} = render(
+      <LayoutHeader className="hdr-custom">H</LayoutHeader>,
+    );
+    const el = container.querySelector('.astryx-layout-header') as HTMLElement;
+    expect(el.className).toContain('hdr-custom');
+  });
+
+  it('renders children in an inner wrapper (padding owner), not directly on the root', () => {
+    const {container} = render(<LayoutHeader>Inner</LayoutHeader>);
+    const root = container.querySelector(
+      '.astryx-layout-header',
+    ) as HTMLElement;
+    // Children live in a nested inner wrapper (the padding owner), not on the
+    // divider-owning root itself.
+    const inner = screen.getByText('Inner');
+    expect(inner).not.toBe(root);
+    expect(inner.parentElement).toBe(root);
+    expect(root).toContainElement(inner);
+  });
+});
+
+// =============================================================================
+// LayoutFooter
+// =============================================================================
+
+describe('LayoutFooter', () => {
+  it('renders its children', () => {
+    render(<LayoutFooter>Actions</LayoutFooter>);
+    expect(screen.getByText('Actions')).toBeInTheDocument();
+  });
+
+  it('carries the astryx-layout-footer class', () => {
+    const {container} = render(<LayoutFooter>F</LayoutFooter>);
+    expect(
+      container.querySelector('.astryx-layout-footer'),
+    ).toBeInTheDocument();
+  });
+
+  it('exposes a landmark role and accessible name', () => {
+    render(
+      <LayoutFooter role="contentinfo" label="Page footer">
+        F
+      </LayoutFooter>,
+    );
+    expect(
+      screen.getByRole('contentinfo', {name: 'Page footer'}),
+    ).toBeInTheDocument();
+  });
+
+  it('omits data-divider by default and reflects hasDivider when set', () => {
+    const {container, rerender} = render(<LayoutFooter>F</LayoutFooter>);
+    const sel = '.astryx-layout-footer';
+    expect(container.querySelector(sel)?.hasAttribute('data-divider')).toBe(
+      false,
+    );
+    rerender(<LayoutFooter hasDivider>F</LayoutFooter>);
+    expect(container.querySelector(sel)?.getAttribute('data-divider')).toBe(
+      'true',
+    );
+  });
+
+  it('inherits the divider default from context', () => {
+    const {container} = render(
+      <LayoutDividerContext value={{defaultHasDividers: true}}>
+        <LayoutFooter>F</LayoutFooter>
+      </LayoutDividerContext>,
+    );
+    expect(
+      container
+        .querySelector('.astryx-layout-footer')
+        ?.getAttribute('data-divider'),
+    ).toBe('true');
+  });
+
+  it('forwards ref to the outer element', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<LayoutFooter ref={ref}>F</LayoutFooter>);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.className).toContain('astryx-layout-footer');
+  });
+});
+
+// =============================================================================
+// LayoutContent
+// =============================================================================
+
+describe('LayoutContent', () => {
+  it('renders its children', () => {
+    render(<LayoutContent>Body</LayoutContent>);
+    expect(screen.getByText('Body')).toBeInTheDocument();
+  });
+
+  it('carries the astryx-layout-content class', () => {
+    const {container} = render(<LayoutContent>C</LayoutContent>);
+    expect(
+      container.querySelector('.astryx-layout-content'),
+    ).toBeInTheDocument();
+  });
+
+  it('exposes the main landmark role with an accessible name', () => {
+    render(
+      <LayoutContent role="main" label="Main content">
+        C
+      </LayoutContent>,
+    );
+    expect(
+      screen.getByRole('main', {name: 'Main content'}),
+    ).toBeInTheDocument();
+  });
+
+  it('forwards ref to the element', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<LayoutContent ref={ref}>C</LayoutContent>);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.className).toContain('astryx-layout-content');
+  });
+
+  it('merges caller className and inline style', () => {
+    const {container} = render(
+      <LayoutContent className="body-custom" style={{color: 'rgb(1, 2, 3)'}}>
+        C
+      </LayoutContent>,
+    );
+    const el = container.querySelector('.astryx-layout-content') as HTMLElement;
+    expect(el.className).toContain('body-custom');
+    expect(el.style.color).toBe('rgb(1, 2, 3)');
+  });
+
+  it('renders correctly as the content slot of a Layout (reads slot context)', () => {
+    render(
+      <Layout
+        header={<LayoutHeader>H</LayoutHeader>}
+        content={<LayoutContent role="main">Main</LayoutContent>}
+      />,
+    );
+    expect(screen.getByRole('main')).toHaveTextContent('Main');
+  });
+
+  it('accepts padding={0} (full bleed) and a numeric padding without crashing', () => {
+    const {rerender, container} = render(
+      <LayoutContent padding={0}>C</LayoutContent>,
+    );
+    expect(
+      container.querySelector('.astryx-layout-content'),
+    ).toBeInTheDocument();
+    rerender(<LayoutContent padding={6}>C</LayoutContent>);
+    expect(
+      container.querySelector('.astryx-layout-content'),
+    ).toBeInTheDocument();
+  });
+});
+
+// =============================================================================
+// LayoutPanel
+// =============================================================================
+
+describe('LayoutPanel', () => {
+  it('renders its children', () => {
+    render(<LayoutPanel>Nav</LayoutPanel>);
+    expect(screen.getByText('Nav')).toBeInTheDocument();
+  });
+
+  it('carries the astryx-layout-panel class', () => {
+    const {container} = render(<LayoutPanel>P</LayoutPanel>);
+    expect(container.querySelector('.astryx-layout-panel')).toBeInTheDocument();
+  });
+
+  it('exposes a navigation landmark with an accessible name', () => {
+    render(
+      <LayoutPanel role="navigation" label="Primary">
+        P
+      </LayoutPanel>,
+    );
+    expect(
+      screen.getByRole('navigation', {name: 'Primary'}),
+    ).toBeInTheDocument();
+  });
+
+  it('applies a numeric width to the element style', () => {
+    const {container} = render(<LayoutPanel width={240}>P</LayoutPanel>);
+    const el = container.querySelector('.astryx-layout-panel') as HTMLElement;
+    expect(el.getAttribute('style') ?? '').toContain('240px');
+  });
+
+  it('applies a string width to the element style', () => {
+    const {container} = render(<LayoutPanel width="18rem">P</LayoutPanel>);
+    const el = container.querySelector('.astryx-layout-panel') as HTMLElement;
+    expect(el.getAttribute('style') ?? '').toContain('18rem');
+  });
+
+  it('resizable._size overrides the width prop', () => {
+    function Harness() {
+      const region = useResizable({defaultSize: 300});
+      return (
+        <LayoutPanel width={100} resizable={region.props}>
+          P
+        </LayoutPanel>
+      );
+    }
+    const {container} = render(<Harness />);
+    const el = container.querySelector('.astryx-layout-panel') as HTMLElement;
+    const style = el.getAttribute('style') ?? '';
+    expect(style).toContain('300px');
+    expect(style).not.toContain('100px');
+  });
+
+  it('forwards ref to the element', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<LayoutPanel ref={ref}>P</LayoutPanel>);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.className).toContain('astryx-layout-panel');
+  });
+
+  it('renders as a start-slot panel inside a Layout without crashing', () => {
+    render(
+      <Layout
+        start={
+          <LayoutPanel hasDivider role="navigation" label="Side">
+            Sidebar
+          </LayoutPanel>
+        }
+        content={<LayoutContent>Main</LayoutContent>}
+      />,
+    );
+    expect(screen.getByRole('navigation', {name: 'Side'})).toHaveTextContent(
+      'Sidebar',
+    );
+  });
+
+  it('renders as an end-slot panel inside a Layout without crashing', () => {
+    render(
+      <Layout
+        end={
+          <LayoutPanel hasDivider role="complementary" label="Inspector">
+            Details
+          </LayoutPanel>
+        }
+        content={<LayoutContent>Main</LayoutContent>}
+      />,
+    );
+    expect(
+      screen.getByRole('complementary', {name: 'Inspector'}),
+    ).toHaveTextContent('Details');
+  });
+
+  it('merges a caller className', () => {
+    const {container} = render(
+      <LayoutPanel className="panel-custom">P</LayoutPanel>,
+    );
+    const el = container.querySelector('.astryx-layout-panel') as HTMLElement;
+    expect(el.className).toContain('panel-custom');
+  });
+});

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

@@ -116,4 +116,76 @@ describe('Edge Compensation', () => {
       expect(dismissButton).toHaveAttribute(EDGE_COMP_ATTR);
     });
   });
+
+  // The container's compensation selector is a direct-child combinator:
+  //   :has(> [data-astryx-edge-comp]:last-child)
+  // so an edge-comp marker only counts when it sits on a *direct* child of the
+  // slot. Attaching a tooltip must not bury the marker one level deeper — the
+  // Button uses the tooltip hook (no wrapper element) so the marker stays on the
+  // button itself (#2578).
+  describe('Tooltip attachment preserves marker discoverability', () => {
+    // Resolve the toolbar slot (the flex wrapper that carries the negative
+    // margin) — it is the direct child of the [role="toolbar"] row.
+    const findSlot = (
+      button: HTMLElement,
+      toolbar: HTMLElement,
+    ): HTMLElement => {
+      let node = button;
+      while (node.parentElement && node.parentElement !== toolbar) {
+        node = node.parentElement;
+      }
+      return node;
+    };
+
+    it('keeps the marker on a direct child of the slot without a tooltip', () => {
+      const {container} = render(
+        <Toolbar
+          label="Actions"
+          endContent={
+            <Button
+              label="Close"
+              variant="ghost"
+              isIconOnly
+              icon={<span>x</span>}
+            />
+          }
+        />,
+      );
+      const button = screen.getByRole('button', {name: 'Close'});
+      const toolbar = container.querySelector(
+        '[role="toolbar"]',
+      ) as HTMLElement;
+      const slot = findSlot(button, toolbar);
+      const directMarked = slot.querySelector(`:scope > [${EDGE_COMP_ATTR}]`);
+      expect(directMarked).not.toBeNull();
+    });
+
+    it('keeps the marker on a direct child of the slot when tooltip is set', () => {
+      const {container} = render(
+        <Toolbar
+          label="Actions"
+          endContent={
+            <Button
+              label="Close"
+              variant="ghost"
+              isIconOnly
+              icon={<span>x</span>}
+              tooltip="Close panel"
+            />
+          }
+        />,
+      );
+      const button = screen.getByRole('button', {name: 'Close'});
+      const toolbar = container.querySelector(
+        '[role="toolbar"]',
+      ) as HTMLElement;
+      const slot = findSlot(button, toolbar);
+      // The tooltip is attached via the hook (no wrapper element), so the
+      // marker stays on the button — a direct child of the container's slot —
+      // and the container's direct-child `:has(> [marker]:last-child)` selector
+      // still matches.
+      const directMarked = slot.querySelector(`:scope > [${EDGE_COMP_ATTR}]`);
+      expect(directMarked).not.toBeNull();
+    });
+  });
 });

package/src/Lightbox/Lightbox.doc.mjs

@@ -64,8 +64,13 @@ export const docs = {
       { guidance: false, description: 'Nest interactive content inside captions; keep them plain text.' },
     ],
   },
+  // The lightbox opens via showModal() and renders nothing while closed —
+  // overlay mode gives the Properties preview an open trigger instead of an
+  // empty stage, mirroring MobileNav (#3616).
   playground: {
+    overlay: true,
     defaults: {
+      isOpen: false,
       media: {
         src: 'https://lookaside.facebook.com/assets/astryx/light-scene-horizontal-1.png',
         alt: 'Coastal shoreline with ocean waves',