@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/Layer/useLayer.test.tsx

@@ -3,15 +3,21 @@
 /**
  * @file useLayer.test.tsx
  * @input Uses vitest, @testing-library/react, useLayer hook
- * @output Unit tests for useLayer show/hide behavior and feature-detection guards
+ * @output Tests for useLayer show/hide feature-detection guards and context-mode positioning
  * @position Testing; validates useLayer.tsx implementation
  *
- * SYNC: When useLayer.tsx changes, update tests to match new behavior
+ * SYNC: When useLayer.tsx changes, update tests accordingly
  */
 
 import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, act} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {useLayer} from './useLayer';
+import type {
+  LayerPlacement,
+  LayerAlignment,
+  ContextRenderProps,
+} from './useLayer';
 
 /**
  * Minimal harness that exposes the imperative show/hide callbacks and renders
@@ -109,3 +115,216 @@ describe('useLayer', () => {
     });
   });
 });
+
+/**
+ * Harness that owns the trigger element.
+ */
+function Harness({
+  placement,
+  alignment,
+  triggerStyle,
+  triggerDir,
+}: {
+  placement: LayerPlacement;
+  alignment: LayerAlignment;
+  triggerStyle?: React.CSSProperties;
+  triggerDir?: string;
+}) {
+  const layer = useLayer({mode: 'context'});
+  return (
+    <>
+      <button
+        type="button"
+        ref={layer.ref}
+        dir={triggerDir}
+        style={triggerStyle}
+        onClick={layer.isOpen ? layer.hide : layer.show}>
+        trigger
+      </button>
+      {layer.render(<span>content</span>, {placement, alignment})}
+    </>
+  );
+}
+
+async function openAndGetStyle(ui: React.ReactElement): Promise<string> {
+  const user = userEvent.setup();
+  const {container, getByRole} = render(ui);
+  await user.click(getByRole('button', {name: 'trigger'}));
+  const popover = container.querySelector('[popover]');
+  return popover?.getAttribute('style') ?? '';
+}
+
+describe('useLayer context positioning', () => {
+  // The mapping uses the self-* logical keyword family, so the emitted
+  // string is direction-independent by construction: the browser resolves
+  // the inline axis against the popover's own inherited direction, and RTL
+  // mirrors with no JS. jsdom has no layout engine, so these tests can only
+  // assert the emitted string — the actual RTL geometry is covered by the
+  // RTL Storybook story (and was verified against the full 12-cell matrix
+  // in a real browser).
+  describe('self-* position-area mapping', () => {
+    it.each([
+      // [placement, alignment, expected position-area]
+      ['above', 'start', 'self-block-start span-self-inline-end'],
+      ['above', 'center', 'self-block-start'],
+      ['above', 'end', 'self-block-start span-self-inline-start'],
+      ['below', 'start', 'self-block-end span-self-inline-end'],
+      ['below', 'center', 'self-block-end'],
+      ['below', 'end', 'self-block-end span-self-inline-start'],
+      ['start', 'start', 'self-inline-start span-self-block-end'],
+      ['start', 'center', 'self-inline-start'],
+      ['start', 'end', 'self-inline-start span-self-block-start'],
+      ['end', 'start', 'self-inline-end span-self-block-end'],
+      ['end', 'center', 'self-inline-end'],
+      ['end', 'end', 'self-inline-end span-self-block-start'],
+    ] as const)(
+      'placement=%s alignment=%s emits position-area %s',
+      async (placement, alignment, expectedArea) => {
+        const style = await openAndGetStyle(
+          <Harness placement={placement} alignment={alignment} />,
+        );
+        expect(style).toMatch(
+          new RegExp(`position-area: ${expectedArea}(;|$)`),
+        );
+        expect(style).not.toContain('justify-self');
+      },
+    );
+
+    it('emits the same string regardless of trigger direction', async () => {
+      const user = userEvent.setup();
+      const first = render(<Harness placement="below" alignment="start" />);
+      await user.click(first.getByRole('button', {name: 'trigger'}));
+      const ltr =
+        first.container.querySelector('[popover]')?.getAttribute('style') ?? '';
+      first.unmount();
+
+      const second = render(
+        <Harness
+          placement="below"
+          alignment="start"
+          triggerDir="rtl"
+          triggerStyle={{direction: 'rtl'}}
+        />,
+      );
+      await user.click(second.getByRole('button', {name: 'trigger'}));
+      const rtl =
+        second.container.querySelector('[popover]')?.getAttribute('style') ??
+        '';
+      // The unique position-anchor id differs per render; the placement
+      // mapping must not.
+      const positionArea = (s: string) => s.match(/position-area:[^;]*/)?.[0];
+      expect(positionArea(rtl)).toBeDefined();
+      expect(positionArea(rtl)).toBe(positionArea(ltr));
+    });
+
+    it('keeps position-try fallbacks intact', async () => {
+      const style = await openAndGetStyle(
+        <Harness placement="below" alignment="start" />,
+      );
+      expect(style).toContain(
+        'position-try-fallbacks: flip-block, flip-inline, flip-block flip-inline',
+      );
+    });
+  });
+
+  describe("positioning='custom' (consumer-authored position styles)", () => {
+    // Consumers like Carousel and Tokenizer keep useLayer's popover behavior
+    // and anchor wiring but position the layer themselves. The opt-out must
+    // suppress every placement-derived style — position-area and the try
+    // fallbacks — so those consumers never need to know which properties
+    // the hook would have emitted.
+    function CustomHarness({
+      triggerStyle,
+      renderProps,
+    }: {
+      triggerStyle?: React.CSSProperties;
+      renderProps: ContextRenderProps;
+    }) {
+      const layer = useLayer({mode: 'context'});
+      return (
+        <>
+          <button
+            type="button"
+            ref={layer.ref}
+            style={triggerStyle}
+            onClick={layer.isOpen ? layer.hide : layer.show}>
+            trigger
+          </button>
+          {layer.render(<span>content</span>, renderProps)}
+        </>
+      );
+    }
+
+    it('keeps the anchor wiring but derives no placement styles', async () => {
+      const style = await openAndGetStyle(
+        <CustomHarness
+          renderProps={{
+            positioning: 'custom',
+            style: {positionArea: 'center'},
+          }}
+        />,
+      );
+      expect(style).toContain('position-anchor');
+      // The consumer-authored area is the only one present…
+      expect(style).toContain('position-area: center');
+      // …and no placement-derived styles leak through.
+      expect(style).not.toContain('position-try-fallbacks');
+    });
+
+    it('ignores placement and alignment when positioning is custom', async () => {
+      // placement/alignment are documented as ignored under custom. Derived
+      // output would be position-area "self-block-end span-self-inline-end";
+      // none of it may appear.
+      const style = await openAndGetStyle(
+        <CustomHarness
+          renderProps={{
+            positioning: 'custom',
+            placement: 'below',
+            alignment: 'start',
+            style: {positionArea: 'center'},
+          }}
+        />,
+      );
+      expect(style).toContain('position-anchor');
+      expect(style).toContain('position-area: center');
+      expect(style).not.toContain('self-block');
+      expect(style).not.toContain('position-try-fallbacks');
+    });
+
+    it('emits only the anchor wiring when custom positioning passes no style at all', async () => {
+      // The strongest suppression probe: with no consumer style in the merge
+      // (Tokenizer's insets-only shape reduces to this in jsdom), nothing can
+      // clobber a leaked derived value — any position-area or try-fallbacks
+      // in the output is a genuine leak.
+      const style = await openAndGetStyle(
+        <CustomHarness renderProps={{positioning: 'custom'}} />,
+      );
+      expect(style).toContain('position-anchor');
+      expect(style).not.toContain('position-area');
+      expect(style).not.toContain('position-try-fallbacks');
+    });
+  });
+
+  it('fixed mode emits no anchor-positioning styles', async () => {
+    function FixedHarness() {
+      const layer = useLayer({mode: 'fixed'});
+      return (
+        <>
+          <button type="button" onClick={layer.show}>
+            opener
+          </button>
+          {layer.render(<span>content</span>, {x: 10, y: 20})}
+        </>
+      );
+    }
+
+    const user = userEvent.setup();
+    const {container, getByRole} = render(<FixedHarness />);
+    await user.click(getByRole('button', {name: 'opener'}));
+
+    const style =
+      container.querySelector('[popover]')?.getAttribute('style') ?? '';
+    expect(style).not.toContain('position-area');
+    expect(style).not.toContain('position-anchor');
+  });
+});

package/src/Layer/useLayer.tsx

@@ -9,7 +9,8 @@
  * @position Core layer utility; used by useHoverCard, useTooltip, etc.
  *
  * SYNC: When modified, update:
- * - /packages/core/src/Layer/Layer.doc.mjs
+ * - /packages/core/src/Layer/useLayer.doc.mjs
+ * - /packages/core/src/Layer/useLayer.test.tsx
  * - /packages/core/src/Layer/index.ts
  */
 
@@ -52,7 +53,9 @@ const styles = stylex.create({
 });
 
 /**
- * Position placement relative to anchor
+ * Position placement relative to anchor.
+ * Logical: start/end resolve against the popover's own inherited direction
+ * via CSS (RTL contexts mirror automatically, no JS involved).
  */
 export type LayerPlacement = 'above' | 'below' | 'start' | 'end';
 
@@ -65,7 +68,31 @@ export type LayerAlignment = 'start' | 'center' | 'end';
  * Render props for context mode (anchor positioning)
  */
 export interface ContextRenderProps {
+  /**
+   * Who authors the layer's position styles.
+   *
+   * `'anchor'` (default): the hook derives CSS anchor-positioning styles —
+   * `position-area` and `position-try-fallbacks` — from the logical
+   * `placement`/`alignment`.
+   *
+   * `'custom'`: the consumer authors its own position styles via `style`
+   * (e.g. explicit `anchor()` insets or an `anchor-size()` cover). The hook
+   * keeps the popover behavior and the `position-anchor` wiring but emits no
+   * placement-derived styles, so direction handling becomes the consumer's
+   * responsibility. `placement`/`alignment` are ignored.
+   *
+   * @default 'anchor'
+   */
+  positioning?: 'anchor' | 'custom';
+  /**
+   * Logical placement relative to the anchor. Ignored when `positioning`
+   * is `'custom'`.
+   */
   placement?: LayerPlacement;
+  /**
+   * Alignment along the placement axis. Ignored when `positioning`
+   * is `'custom'`.
+   */
   alignment?: LayerAlignment;
   /**
    * ARIA role applied to the popover container (e.g. `'tooltip'`). Lets
@@ -252,40 +279,45 @@ export interface FixedLayerReturn {
 }
 
 /**
- * Map placement and alignment to CSS position-area value.
+ * Map logical placement/alignment to a CSS position-area value.
+ *
+ * Uses the self-* logical keyword family: the inline axis resolves against
+ * the popover's own inherited direction (the layer renders inside the
+ * trigger's subtree, so it inherits `direction` and mirrors in RTL with no
+ * JS). The block axis is direction-neutral but must come from the same
+ * keyword family — mixing physical `top` with `self-inline-*` produces an
+ * invalid position-area (computes to `none`, which pins the popover to the
+ * viewport corner because styles.base zeroes the UA margins).
+ *
+ * Note the plain logical family (`inline-start`, no `self-`) is NOT a
+ * substitute: it resolves against the containing block — the page root for
+ * a top-layer popover — so it ignores `direction` set on a subtree, which
+ * is exactly #3389's repro.
  */
 function getPositionArea(
   placement: LayerPlacement = 'above',
   alignment: LayerAlignment = 'center',
 ): string {
-  const placementMap: Record<LayerPlacement, string> = {
-    above: 'top',
-    below: 'bottom',
-    start: 'left',
-    end: 'right',
-  };
-
-  const cssPlacement = placementMap[placement];
-
-  // For above/below, alignment is horizontal
   if (placement === 'above' || placement === 'below') {
+    const block = placement === 'above' ? 'self-block-start' : 'self-block-end';
     if (alignment === 'start') {
-      return `${cssPlacement} span-right`;
+      return `${block} span-self-inline-end`;
     }
     if (alignment === 'end') {
-      return `${cssPlacement} span-left`;
+      return `${block} span-self-inline-start`;
     }
-    return cssPlacement; // center
+    return block; // center
   }
 
-  // For start/end, alignment is vertical
+  const inline =
+    placement === 'start' ? 'self-inline-start' : 'self-inline-end';
   if (alignment === 'start') {
-    return `${cssPlacement} span-bottom`;
+    return `${inline} span-self-block-end`;
   }
   if (alignment === 'end') {
-    return `${cssPlacement} span-top`;
+    return `${inline} span-self-block-start`;
   }
-  return `${cssPlacement} center`;
+  return inline; // center
 }
 
 /**
@@ -321,18 +353,18 @@ export function useLayer(
   const isOpenRef = useRef(false);
 
   const show = useCallback(() => {
-    const el = popoverRef.current;
-    if (el && !isOpenRef.current) {
+    const popover = popoverRef.current;
+    if (popover && !isOpenRef.current) {
       // Finding infra-4: the Popover API is unsupported on Safari <17 and
       // Firefox <125. On those browsers `showPopover` does not exist, so
       // calling it unconditionally throws a TypeError and the layer never
       // opens. Guard behind a feature check; when the API is missing, fall
       // back to plain visibility (the [popover] attribute is inert there, so
       // the element sits in normal flow) so the layer still becomes visible.
-      if (typeof el.showPopover === 'function') {
-        el.showPopover();
+      if (typeof popover.showPopover === 'function') {
+        popover.showPopover();
       } else {
-        el.style.display = 'block';
+        popover.style.display = 'block';
       }
       isOpenRef.current = true;
       setIsOpen(true);
@@ -461,6 +493,7 @@ export function useLayer(
       const {
         placement = 'above',
         alignment = 'center',
+        positioning = 'anchor',
         role,
         xstyle,
         className: extraClassName,
@@ -471,11 +504,17 @@ export function useLayer(
       } = props || {};
 
       // CSS anchor positioning (dynamic, not in StyleX)
-      const anchorStyle: React.CSSProperties = {
-        positionAnchor: anchorId,
-        positionArea: getPositionArea(placement, alignment),
-        positionTryFallbacks: 'flip-block, flip-inline, flip-block flip-inline',
-      };
+      const anchorStyle: React.CSSProperties =
+        positioning === 'custom'
+          ? // Consumer authors its own position styles via `style` — keep
+            // only the anchor wiring, derive nothing from placement.
+            {positionAnchor: anchorId}
+          : {
+              positionAnchor: anchorId,
+              positionArea: getPositionArea(placement, alignment),
+              positionTryFallbacks:
+                'flip-block, flip-inline, flip-block flip-inline',
+            };
 
       const stylexResult = stylex.props(styles.base, xstyle);
       const combinedClassName = extraClassName

package/src/Layout/Layout.test.tsx

@@ -0,0 +1,285 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Layout.test.tsx
+ * @input Uses vitest, @testing-library/react, Layout + layout contexts
+ * @output Characterization tests for the Layout page-shell component
+ * @position Testing; validates slot rendering, context provisioning, and
+ *   divider/padding/height wiring
+ *
+ * SYNC: When Layout.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {use, createRef} from 'react';
+import {Layout} from './Layout';
+import {LayoutHeader} from './LayoutHeader';
+import {LayoutFooter} from './LayoutFooter';
+import {LayoutAreaContext} from './LayoutAreaContext';
+import {LayoutSlotsContext} from './LayoutSlotsContext';
+
+/** Reports which layout area it is rendered inside. */
+function AreaProbe({testid}: {testid: string}) {
+  const area = use(LayoutAreaContext);
+  return <span data-testid={testid}>{String(area)}</span>;
+}
+
+/** Reports the current LayoutSlots record as JSON. */
+function SlotsProbe() {
+  const slots = use(LayoutSlotsContext);
+  return <span data-testid="slots">{JSON.stringify(slots)}</span>;
+}
+
+/** The Layout root is the outermost element rendered by the component. */
+function root(container: HTMLElement): HTMLElement {
+  return container.firstElementChild as HTMLElement;
+}
+
+describe('Layout', () => {
+  describe('content / children resolution', () => {
+    it('renders the content prop', () => {
+      render(<Layout content={<div>main body</div>} />);
+      expect(screen.getByText('main body')).toBeInTheDocument();
+    });
+
+    it('renders children as a shorthand for the content slot', () => {
+      render(
+        <Layout>
+          <div>child body</div>
+        </Layout>,
+      );
+      expect(screen.getByText('child body')).toBeInTheDocument();
+    });
+
+    it('content wins when both content and children are provided', () => {
+      render(
+        <Layout content={<div>from-content</div>}>
+          <div>from-children</div>
+        </Layout>,
+      );
+      expect(screen.getByText('from-content')).toBeInTheDocument();
+      expect(screen.queryByText('from-children')).not.toBeInTheDocument();
+    });
+
+    it('renders an empty shell without crashing when no slots are given', () => {
+      const {container} = render(<Layout />);
+      expect(root(container)).toBeInTheDocument();
+    });
+  });
+
+  describe('slots', () => {
+    it('renders all four surrounding slots plus content', () => {
+      render(
+        <Layout
+          header={<div>the-header</div>}
+          start={<div>the-start</div>}
+          end={<div>the-end</div>}
+          footer={<div>the-footer</div>}
+          content={<div>the-content</div>}
+        />,
+      );
+      expect(screen.getByText('the-header')).toBeInTheDocument();
+      expect(screen.getByText('the-start')).toBeInTheDocument();
+      expect(screen.getByText('the-end')).toBeInTheDocument();
+      expect(screen.getByText('the-footer')).toBeInTheDocument();
+      expect(screen.getByText('the-content')).toBeInTheDocument();
+    });
+
+    it('does not render an area wrapper for an omitted slot', () => {
+      render(<Layout content={<AreaProbe testid="content" />} />);
+      // Only the content probe exists; header/start/end/footer probes absent.
+      expect(screen.getByTestId('content')).toHaveTextContent('content');
+    });
+  });
+
+  describe('LayoutAreaContext provisioning', () => {
+    it('tags each slot with its area name', () => {
+      render(
+        <Layout
+          header={<AreaProbe testid="h" />}
+          start={<AreaProbe testid="s" />}
+          end={<AreaProbe testid="e" />}
+          footer={<AreaProbe testid="f" />}
+          content={<AreaProbe testid="c" />}
+        />,
+      );
+      expect(screen.getByTestId('h')).toHaveTextContent('header');
+      expect(screen.getByTestId('s')).toHaveTextContent('start');
+      expect(screen.getByTestId('e')).toHaveTextContent('end');
+      expect(screen.getByTestId('f')).toHaveTextContent('footer');
+      expect(screen.getByTestId('c')).toHaveTextContent('content');
+    });
+  });
+
+  describe('LayoutSlotsContext provisioning', () => {
+    it('reports which slots are filled to descendants', () => {
+      render(
+        <Layout
+          header={<div>h</div>}
+          start={<div>s</div>}
+          content={<SlotsProbe />}
+        />,
+      );
+      const slots = JSON.parse(screen.getByTestId('slots').textContent ?? '{}');
+      expect(slots).toEqual({
+        hasHeader: true,
+        hasFooter: false,
+        hasStart: true,
+        hasEnd: false,
+      });
+    });
+
+    it('reports all-false when only content is present', () => {
+      render(<Layout content={<SlotsProbe />} />);
+      const slots = JSON.parse(screen.getByTestId('slots').textContent ?? '{}');
+      expect(slots).toEqual({
+        hasHeader: false,
+        hasFooter: false,
+        hasStart: false,
+        hasEnd: false,
+      });
+    });
+
+    it('reports every slot filled', () => {
+      render(
+        <Layout
+          header={<div>h</div>}
+          footer={<div>f</div>}
+          start={<div>s</div>}
+          end={<div>e</div>}
+          content={<SlotsProbe />}
+        />,
+      );
+      const slots = JSON.parse(screen.getByTestId('slots').textContent ?? '{}');
+      expect(slots).toEqual({
+        hasHeader: true,
+        hasFooter: true,
+        hasStart: true,
+        hasEnd: true,
+      });
+    });
+  });
+
+  describe('theme props (class + data attributes)', () => {
+    it('renders the astryx-layout class on the root', () => {
+      const {container} = render(<Layout content={<div>x</div>} />);
+      expect(root(container).className).toContain('astryx-layout');
+    });
+
+    it('defaults data-height to "fill"', () => {
+      const {container} = render(<Layout content={<div>x</div>} />);
+      expect(root(container).getAttribute('data-height')).toBe('fill');
+    });
+
+    it('reflects height="auto" as data-height', () => {
+      const {container} = render(
+        <Layout height="auto" content={<div>x</div>} />,
+      );
+      expect(root(container).getAttribute('data-height')).toBe('auto');
+    });
+  });
+
+  describe('defaultHasDividers → LayoutDividerContext', () => {
+    it('makes headers default to having a divider', () => {
+      render(
+        <Layout
+          defaultHasDividers
+          header={<LayoutHeader>H</LayoutHeader>}
+          content={<div>c</div>}
+        />,
+      );
+      const header = screen.getByText('H').closest('[data-divider]');
+      expect(header).not.toBeNull();
+      expect(header?.getAttribute('data-divider')).toBe('true');
+    });
+
+    it('makes footers default to having a divider', () => {
+      const {container} = render(
+        <Layout
+          defaultHasDividers
+          footer={<LayoutFooter>F</LayoutFooter>}
+          content={<div>c</div>}
+        />,
+      );
+      expect(
+        container.querySelector('.astryx-layout-footer[data-divider]'),
+      ).not.toBeNull();
+    });
+
+    it('does not force dividers when defaultHasDividers is unset', () => {
+      const {container} = render(
+        <Layout
+          header={<LayoutHeader>H</LayoutHeader>}
+          content={<div>c</div>}
+        />,
+      );
+      expect(
+        container.querySelector('.astryx-layout-header[data-divider]'),
+      ).toBeNull();
+    });
+
+    it('an explicit hasDivider={false} on a header overrides the context default', () => {
+      const {container} = render(
+        <Layout
+          defaultHasDividers
+          header={<LayoutHeader hasDivider={false}>H</LayoutHeader>}
+          content={<div>c</div>}
+        />,
+      );
+      expect(
+        container.querySelector('.astryx-layout-header[data-divider]'),
+      ).toBeNull();
+    });
+  });
+
+  describe('padding / contentWidth', () => {
+    it('accepts a numeric padding step without crashing', () => {
+      const {container} = render(<Layout padding={4} content={<div>c</div>} />);
+      expect(root(container)).toBeInTheDocument();
+    });
+
+    it('accepts padding={0} (full bleed) without crashing', () => {
+      const {container} = render(<Layout padding={0} content={<div>c</div>} />);
+      expect(root(container)).toBeInTheDocument();
+    });
+
+    it('accepts a numeric contentWidth without crashing', () => {
+      const {container} = render(
+        <Layout contentWidth={640} content={<div>c</div>} />,
+      );
+      expect(root(container)).toBeInTheDocument();
+    });
+
+    it('accepts a string contentWidth without crashing', () => {
+      const {container} = render(
+        <Layout contentWidth="60ch" content={<div>c</div>} />,
+      );
+      expect(root(container)).toBeInTheDocument();
+    });
+  });
+
+  describe('styling & ref', () => {
+    it('forwards ref to the root div', () => {
+      const ref = createRef<HTMLDivElement>();
+      render(<Layout ref={ref} content={<div>c</div>} />);
+      expect(ref.current).toBeInstanceOf(HTMLDivElement);
+      expect(ref.current?.className).toContain('astryx-layout');
+    });
+
+    it('merges a caller className onto the root', () => {
+      const {container} = render(
+        <Layout className="my-layout" content={<div>c</div>} />,
+      );
+      expect(root(container).className).toContain('my-layout');
+      expect(root(container).className).toContain('astryx-layout');
+    });
+
+    it('merges a caller inline style onto the root', () => {
+      const {container} = render(
+        <Layout style={{outline: '1px solid red'}} content={<div>c</div>} />,
+      );
+      expect(root(container).style.outline).toBe('1px solid red');
+    });
+  });
+});