@astryxdesign/core 0.4.1 → 0.4.2-canary.356d2f9

package/src/Layer/layerHost.test.ts

@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layerHost.test.ts
+ * @input Tests resolveLayerPortalTarget
+ * @output Coverage for when and where a layer is portaled
+ * @position Test for /packages/core/src/Layer/layerHost.ts
+ */
+
+import {describe, it, expect, afterEach} from 'vitest';
+import {resolveLayerPortalTarget} from './layerHost';
+
+function mount(html: string): HTMLElement {
+  const root = document.createElement('div');
+  root.id = 'root';
+  root.innerHTML = html;
+  document.body.appendChild(root);
+  return root;
+}
+
+afterEach(() => {
+  document.getElementById('root')?.remove();
+});
+
+describe('resolveLayerPortalTarget', () => {
+  it('returns null without an inline parent', () => {
+    expect(resolveLayerPortalTarget(null)).toBeNull();
+  });
+
+  it('returns null when the intended inline position is already safe', () => {
+    const root = mount(
+      '<div id="host"><template id="marker"></template></div>',
+    );
+    const target = resolveLayerPortalTarget(root.querySelector('#host'));
+
+    expect(target).toBeNull();
+  });
+
+  it.each([
+    ['paragraph', '<p><template></template></p>'],
+    ['heading', '<h2><template></template></h2>'],
+    ['link', '<a href="#x"><template></template></a>'],
+    ['button', '<button><template></template></button>'],
+    ['label', '<label><template></template></label>'],
+    ['data', '<data><template></template></data>'],
+    ['definition', '<dfn><template></template></dfn>'],
+    ['meter', '<meter><template></template></meter>'],
+    ['output', '<output><template></template></output>'],
+    ['progress', '<progress><template></template></progress>'],
+    [
+      'nested inline formatting',
+      '<p><em><b><template id="marker"></template></b></em></p>',
+    ],
+  ])('walks out of a %s', (_name, markup) => {
+    const root = mount(`<div id="host">${markup}</div>`);
+    const marker = root.querySelector('template');
+    const target = resolveLayerPortalTarget(marker?.parentElement ?? null);
+
+    expect(target).toBe(root.querySelector('#host'));
+  });
+
+  it('walks past a safe wrapper nested inside an unsafe ancestor', () => {
+    const root = mount(
+      '<div id="host"><a href="#x"><div id="inline"><template></template></div></a></div>',
+    );
+    const target = resolveLayerPortalTarget(root.querySelector('#inline'));
+
+    expect(target).toBe(root.querySelector('#host'));
+  });
+
+  it.each([
+    [
+      'table row',
+      '<table><tbody><tr><template></template></tr></tbody></table>',
+    ],
+    ['list', '<ul><template></template></ul>'],
+    ['select', '<select><template></template></select>'],
+    ['heading group', '<hgroup><template></template></hgroup>'],
+  ])('walks out of a structural %s', (_name, markup) => {
+    const root = mount(`<div id="host">${markup}</div>`);
+    const marker = root.querySelector('template');
+    const target = resolveLayerPortalTarget(marker?.parentElement ?? null);
+
+    expect(target).toBe(root.querySelector('#host'));
+  });
+
+  it('stops at the nearest safe ancestor rather than the body', () => {
+    const root = mount(
+      '<section id="outer"><li id="host"><p><span id="t">t</span></p></li></section>',
+    );
+    const marker = root.querySelector('#t');
+    const target = resolveLayerPortalTarget(marker?.parentElement ?? null);
+
+    // The nearest safe ancestor keeps the layer inside the trigger's theme
+    // scope and next to it in the tab order.
+    expect(target).toBe(root.querySelector('#host'));
+    expect(target).not.toBe(document.body);
+  });
+});

package/src/Layer/layerHost.ts

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layerHost.ts
+ * @input Uses the layer's intended inline parent element
+ * @output Exports resolveLayerPortalTarget, the corrective portal target
+ * @position Layer utility; used by useLayer to place the popover in the DOM
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/layerHost.test.ts
+ */
+
+/**
+ * Ancestors a layer must not be hosted inside.
+ *
+ * Two overlapping reasons, both verified in Chrome:
+ *
+ * 1. The HTML parser owns server markup. `<p>` and the heading-ish elements
+ *    take phrasing content only, so a block element inside one makes the
+ *    parser close the paragraph and reparent the rest — the layer's content
+ *    ends up in the page instead of the popover. A nested `<a>` triggers the
+ *    same tearing through the adoption agency algorithm.
+ * 2. Interactive ancestors capture the layer's own interactions. A card
+ *    hosted inside an `<a>` or `<button>` puts its links and buttons inside
+ *    that control: clicking one navigates the wrapping link, and every
+ *    focusable in the card joins the control's own tab stop.
+ *
+ * Inline formatting elements are on the list for a third, milder reason: a
+ * layer hosted in one inherits its typography (font-size, text-align), so a
+ * card in a 13px centered paragraph renders 13px and centered.
+ */
+const UNSAFE_HOSTS = new Set([
+  // Phrasing-content-only containers
+  'p',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'dt',
+  'pre',
+  'legend',
+  'data',
+  'dfn',
+  'meter',
+  'output',
+  'progress',
+  'option',
+  'optgroup',
+  // Structural containers whose direct children are restricted. An inert
+  // <template> marker is valid script-supporting content in these positions,
+  // but the eventual div/span layer is not.
+  'table',
+  'thead',
+  'tbody',
+  'tfoot',
+  'tr',
+  'colgroup',
+  'ul',
+  'ol',
+  'menu',
+  'dl',
+  'select',
+  'datalist',
+  'picture',
+  'hgroup',
+  'ruby',
+  'rt',
+  'rp',
+  // Interactive containers
+  'a',
+  'button',
+  'label',
+  'summary',
+  // Inline formatting context
+  'span',
+  'em',
+  'strong',
+  'b',
+  'i',
+  'u',
+  's',
+  'small',
+  'mark',
+  'code',
+  'kbd',
+  'samp',
+  'var',
+  'sub',
+  'sup',
+  'abbr',
+  'cite',
+  'q',
+  'time',
+  'bdi',
+  'bdo',
+  'ins',
+  'del',
+]);
+
+/**
+ * Return the corrective portal target for a layer's intended inline parent.
+ *
+ * A null result means the inline parent and all of its ancestors are safe, so
+ * the layer should stay at its JSX position. Otherwise the result is the
+ * nearest element outside every unsafe ancestor around that position.
+ *
+ * Walking up from the actual render position (rather than the trigger, or
+ * portaling to `document.body`) keeps the two things a layer inherits there:
+ *
+ * - **Theme.** Theme scopes live on DOM ancestors. Staying as close as
+ *   possible to the intended render position preserves their component rules
+ *   and custom properties; `document.body` may sit outside a nested scope.
+ * - **Tab order.** Sequential focus follows DOM order, so a host near the
+ *   trigger keeps the layer's focusables next to it. (`show()` also passes
+ *   the trigger as the popover's invoker `source`, which pins focus order to
+ *   the invoker in browsers that support it.)
+ *
+ * The outermost unsafe ancestor matters. A safe div may itself sit inside an
+ * anchor; stopping at that div would still put the layer's buttons inside the
+ * link. Walking the whole chain ensures the target is outside both.
+ */
+export function resolveLayerPortalTarget(
+  inlineParent: HTMLElement | null,
+): HTMLElement | null {
+  if (!inlineParent) {
+    return null;
+  }
+
+  let outermostUnsafe: HTMLElement | null = null;
+  let node: HTMLElement | null = inlineParent;
+  while (node) {
+    if (UNSAFE_HOSTS.has(node.tagName.toLowerCase())) {
+      outermostUnsafe = node;
+    }
+    node = node.parentElement;
+  }
+
+  return outermostUnsafe?.parentElement ?? null;
+}

package/src/Layer/useLayer.doc.mjs

@@ -42,6 +42,13 @@ export const docs = {
         'Whether clicking outside should dismiss the layer using native popover light-dismiss behavior.',
       default: 'false',
     },
+    {
+      name: 'lazyMount',
+      type: 'boolean',
+      description:
+        'Context mode only. Wait until show() to resolve the inline/portal position and mount content; hide unmounts the content while the inert marker remains.',
+      default: 'false',
+    },
   ],
   returns: [
     {
@@ -79,7 +86,7 @@ export const docs = {
       name: 'render',
       type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
       description:
-        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. Pass `offset` (a CSS length; a number is px) in context mode for clearance from the anchor: it applies to both edges of the placement axis, so the gap survives a flip. Layers are flush by default. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. Pass `offset` (a CSS length; a number is px) in context mode for clearance from the anchor: it applies to both edges of the placement axis, so the gap survives a flip. Layers are flush by default. Context mode first renders an inert `<template>` marker in matching server and client markup. The final layer stays at that JSX position if its parent is safe; otherwise it is portaled to the nearest ancestor outside paragraphs, links, buttons, inline formatting, and structurally restricted containers. The nearest safe host keeps CSS custom properties inheriting live, while the layer preserves direction and writing mode from its JSX position. By default this resolution occurs after hydration so closed-layer DOM remains available; `lazyMount` defers it until `show()` and unmounts the content again on hide while the marker remains. The Popover API promotes the layer to the top layer when shown, so it escapes ancestor clipping and stacking wherever it is hosted. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.',
     },
   ],
   usage: {
@@ -99,7 +106,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Rely on the Popover API top layer to escape ancestor clipping and stacking: render the layer inline (no portal) so it inherits the trigger\'s theme cascade and keeps a natural focus order. Use `as: "span"` when the layer must be valid inside inline contexts like a paragraph.',
+          "Rely on the Popover API top layer to escape ancestor clipping and stacking, and host the layer near its trigger rather than in the body so it inherits the trigger's theme cascade and keeps a natural focus order.",
       },
       {
         guidance: false,
@@ -123,6 +130,8 @@ export const docsDense = {
     onShow: 'fires when layer becomes visible.',
     onHide: 'fires when layer hides.',
     lightDismiss: 'whether native outside-click light-dismiss is enabled.',
+    lazyMount:
+      'context only: defer position resolution/content mounting until show; unmount on hide.',
   },
   returnDescriptions: {
     ref: 'trigger ref for context mode; undefined in fixed mode.',
@@ -131,7 +140,8 @@ export const docsDense = {
     hide: 'hide layer.',
     isOpen: 'whether layer is open.',
     id: 'unique ARIA id.',
-    render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring, which becomes yours). `offset` (context mode) = clearance from the anchor as a CSS length (number = px), applied to both edges of the placement axis so it survives a flip; layers are flush by default. Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal. Viewport overflow: flips to opposite side; centered layers also slide along the alignment axis (span fallbacks).',
+    render:
+      'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring, which becomes yours). `offset` (context mode) = clearance from the anchor as a CSS length (number = px), applied to both edges of the placement axis so it survives a flip; layers are flush by default. Context mode begins with an inert `<template>` marker for stable SSR/hydration, then keeps the final layer inline at a safe JSX position or portals it to the nearest safe ancestor; CSS custom properties keep inheriting from that host while direction and writing mode are preserved from the JSX position. `lazyMount` waits for show and unmounts content on hide while the marker remains. The Popover API top layer escapes clipping/stacking wherever it is hosted. Viewport overflow: flips to opposite side; centered layers also slide along the alignment axis (span fallbacks).',
   },
   usage: {
     description:
@@ -150,7 +160,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'Rely on the Popover API top layer to escape clipping/stacking: render inline (no portal) to inherit the trigger theme cascade and natural focus order. Use `as: "span"` when the layer must be valid in inline contexts like a paragraph.',
+          'Rely on the Popover API top layer to escape clipping/stacking; host the layer near its trigger (not in the body) to inherit the trigger theme cascade and natural focus order.',
       },
       {
         guidance: false,