@astryxdesign/core 0.1.1 → 0.1.2-canary.3893cd5

package/src/Dialog/Dialog.doc.mjs

@@ -40,13 +40,13 @@ export const docs = {
     {
       name: 'isOpen',
       type: 'boolean',
-      description: 'Whether the dialog is open (required).',
+      description: 'Whether the dialog is open.',
       required: true,
     },
     {
       name: 'onOpenChange',
       type: '(isOpen: boolean) => unknown',
-      description: 'Callback when dialog visibility changes (required).',
+      description: 'Callback when dialog visibility changes.',
       required: true,
     },
     {

package/src/EmptyState/EmptyState.test.tsx

@@ -45,11 +45,13 @@ describe('EmptyState', () => {
       />,
     );
     expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
+    // Description renders as <div> (never <p>) so block content composes safely.
+    expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
   });
 
   it('does not render description when not provided', () => {
-    const {container} = render(<EmptyState title="No results" />);
-    expect(container.querySelector('p')).not.toBeInTheDocument();
+    render(<EmptyState title="No results" />);
+    expect(screen.queryByText('Try adjusting your search.')).toBeNull();
   });
 
   it('renders with icon', () => {

package/src/EmptyState/EmptyState.tsx

@@ -174,13 +174,17 @@ export function EmptyState({
           title,
         )}
         {description != null && (
-          <p
+          // Rendered as <div> (not <p>): description accepts ReactNode and a
+          // <p> cannot legally contain block children, which causes hydration
+          // mismatches. The StyleX style sets margin: 0, so appearance is
+          // unchanged.
+          <div
             {...stylex.props(
               styles.description,
               isCompact && styles.descriptionCompact,
             )}>
             {description}
-          </p>
+          </div>
         )}
       </div>
       {actions != null && (

package/src/HoverCard/HoverCard.doc.mjs

@@ -108,6 +108,7 @@ export const docs = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
     anatomy: [
       {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},
@@ -216,6 +217,7 @@ export const docsZh = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
   },
 };
@@ -233,6 +235,7 @@ export const docsDense = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a block-content HoverCard directly inside phrasing-only contexts (<p>, <label>, heading); it renders inline so block content is invalid HTML there. Wrap surrounding text in a block element instead.' },
     ],
   },
   components: [

package/src/HoverCard/HoverCard.test.tsx

@@ -10,7 +10,10 @@
  */
 
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
+import {renderToString} from 'react-dom/server';
+import {hydrateRoot} from 'react-dom/client';
+import {StrictMode} from 'react';
 import {HoverCard} from './HoverCard';
 
 // Store original matches to restore later
@@ -55,6 +58,17 @@ describe('HoverCard', () => {
     expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
   });
 
+  it('gives the floating layer role="dialog"', () => {
+    render(
+      <HoverCard content={<span>Card content</span>}>
+        <button type="button">Trigger</button>
+      </HoverCard>,
+    );
+    expect(screen.getByRole('dialog', {hidden: true})).toHaveTextContent(
+      'Card content',
+    );
+  });
+
   it('wraps element children in an inline-safe span', () => {
     const {container} = render(
       <p>
@@ -73,6 +87,31 @@ describe('HoverCard', () => {
     expect(paragraph?.querySelector('div')).toBeNull();
   });
 
+  it('renders the floating layer with inline-safe markup (no block elements in a paragraph)', () => {
+    // HoverCard renders its floating layer inline (no portal), so the layer
+    // must be phrasing content to stay valid — and stay put on hydration —
+    // inside a <p>. Assert the layer popover element is a <span> and that the
+    // paragraph contains no <div> descendants at all.
+    const {container} = render(
+      <p>
+        Before{' '}
+        <HoverCard content={<span>Card content</span>}>
+          <a href="#trigger">Trigger</a>
+        </HoverCard>{' '}
+        after
+      </p>,
+    );
+
+    const paragraph = container.querySelector('p');
+    const layer = screen.getByText('Card content').closest('[popover]');
+
+    expect(layer).not.toBeNull();
+    expect(layer?.tagName).toBe('SPAN');
+    // The whole layer subtree lives inside the paragraph with no block boxes.
+    expect(paragraph?.contains(layer as Node)).toBe(true);
+    expect(paragraph?.querySelector('div')).toBeNull();
+  });
+
   it('does not show content initially', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
@@ -84,7 +123,7 @@ describe('HoverCard', () => {
     expect(content).toBeInTheDocument();
   });
 
-  it('applies the theme body font to the portaled layer', () => {
+  it('applies the theme body font to the floating layer', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
         <button type="button">Trigger</button>
@@ -370,4 +409,152 @@ describe('HoverCard', () => {
       expect(onOpenChange).not.toHaveBeenCalledWith(true);
     });
   });
+
+  describe('SSR / hydration', () => {
+    // Regression coverage for the hydration mismatch (#3107). The floating
+    // layer used to be portaled into document.body behind a
+    // `typeof document !== 'undefined'` gate: the server rendered nothing while
+    // the first client render emitted the portal, so the two trees disagreed.
+    //
+    // The layer is now rendered inline as inline-safe phrasing markup (a
+    // `<span popover>`), identically on the server and the client, so there is
+    // nothing for hydration to mismatch.
+
+    it('renders the floating layer in server markup (no document gate)', () => {
+      const html = renderToString(
+        <HoverCard content={<span>Card content</span>}>
+          <button type="button">Trigger</button>
+        </HoverCard>,
+      );
+
+      // The popover element is present in the server output...
+      expect(html).toContain('popover="manual"');
+      expect(html).toContain('Card content');
+      // ...and it is a <span> (inline-safe), not a <div>.
+      expect(html).toMatch(/<span[^>]*popover="manual"/);
+    });
+
+    it('keeps the floating layer inline-safe in server markup inside a paragraph', () => {
+      const html = renderToString(
+        <p>
+          Before{' '}
+          <HoverCard content={<span>Card content</span>}>
+            <a href="#trigger">Trigger</a>
+          </HoverCard>{' '}
+          after
+        </p>,
+      );
+
+      // No <div> is emitted inside the paragraph — the layer and its wrappers
+      // are all phrasing content, so the server string is valid <p> markup that
+      // the browser parser will not reparent (which would itself desync
+      // hydration).
+      expect(html).not.toContain('<div');
+      expect(html).toMatch(/<span[^>]*popover="manual"/);
+    });
+
+    it('server markup matches the first client render (no hydration mismatch)', async () => {
+      const tree = (
+        <StrictMode>
+          <p>
+            Glossary:{' '}
+            <HoverCard content={<span>Definition</span>}>
+              <a href="#term">term</a>
+            </HoverCard>
+            .
+          </p>
+        </StrictMode>
+      );
+
+      const serverHTML = renderToString(tree);
+
+      const container = document.createElement('div');
+      container.innerHTML = serverHTML;
+      document.body.appendChild(container);
+
+      // Capture any hydration diagnostics. React reports hydration mismatches
+      // both through console.error and through onRecoverableError.
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+      const recoverableErrors: unknown[] = [];
+
+      let root: ReturnType<typeof hydrateRoot>;
+      await act(async () => {
+        root = hydrateRoot(container, tree, {
+          onRecoverableError: error => {
+            recoverableErrors.push(error);
+          },
+        });
+      });
+
+      const hydrationErrors = consoleErrorSpy.mock.calls.filter(call =>
+        String(call[0] ?? '')
+          .toLowerCase()
+          .includes('hydrat'),
+      );
+
+      expect(hydrationErrors).toEqual([]);
+      expect(recoverableErrors).toEqual([]);
+
+      await act(async () => {
+        root.unmount();
+      });
+      consoleErrorSpy.mockRestore();
+      container.remove();
+    });
+
+    it('hydrates a default-open hover card without a mismatch', async () => {
+      vi.mocked(HTMLElement.prototype.showPopover).mockClear();
+
+      const tree = (
+        <HoverCard content={<span>Default open</span>} isDefaultOpen>
+          <button type="button">Trigger</button>
+        </HoverCard>
+      );
+
+      const serverHTML = renderToString(tree);
+      // isDefaultOpen must not leak the open state into SSR markup — the open
+      // call happens in an effect after hydration, so the server output is the
+      // same closed markup the first client render produces.
+      expect(serverHTML).toContain('popover="manual"');
+
+      const container = document.createElement('div');
+      container.innerHTML = serverHTML;
+      document.body.appendChild(container);
+
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+      const recoverableErrors: unknown[] = [];
+
+      let root: ReturnType<typeof hydrateRoot>;
+      await act(async () => {
+        root = hydrateRoot(container, tree, {
+          onRecoverableError: error => {
+            recoverableErrors.push(error);
+          },
+        });
+      });
+
+      const hydrationErrors = consoleErrorSpy.mock.calls.filter(call =>
+        String(call[0] ?? '')
+          .toLowerCase()
+          .includes('hydrat'),
+      );
+      expect(hydrationErrors).toEqual([]);
+      expect(recoverableErrors).toEqual([]);
+
+      // The card opens after hydration via the mount effect.
+      await waitFor(() => {
+        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+      });
+
+      await act(async () => {
+        root.unmount();
+      });
+      consoleErrorSpy.mockRestore();
+      container.remove();
+    });
+  });
 });

package/src/HoverCard/HoverCard.tsx

@@ -4,9 +4,9 @@
 
 /**
  * @file HoverCard.tsx
- * @input Uses React, ReactDOM createPortal, useHoverCard hook
+ * @input Uses React, useHoverCard hook
  * @output Exports HoverCard component for hover/focus triggered layers
- * @position Layer component; uses inline-safe trigger wrapper and portals floating layer
+ * @position Layer component; uses inline-safe trigger wrapper and renders the floating layer inline
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/HoverCard/HoverCard.test.tsx
@@ -15,13 +15,7 @@
  * - /packages/cli/templates/blocks/components/HoverCard/ (showcase blocks)
  */
 
-import React, {
-  useCallback,
-  useRef,
-  type ReactElement,
-  type ReactNode,
-} from 'react';
-import {createPortal} from 'react-dom';
+import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {useHoverCard, type HoverCardFocusTrigger} from './useHoverCard';
@@ -245,13 +239,23 @@ export function HoverCard({
     };
   }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
 
-  const renderedHoverCard =
-    typeof document !== 'undefined'
-      ? createPortal(
-          hoverCard.renderHoverCard(content, {xstyle, className, style}),
-          document.body,
-        )
-      : null;
+  // Render the floating layer inline, in the same place on the server and the
+  // client. The layer is a `popover` element opened via the Popover API, so the
+  // browser promotes it to the top layer when shown — that already escapes
+  // ancestor clipping, stacking, and transform containing-block traps, and CSS
+  // anchor positioning resolves the trigger reference regardless of where the
+  // element sits in the DOM, so no portal is needed to "escape" layout.
+  //
+  // The layer renders as inline-safe phrasing markup (a `<span>`, see
+  // useHoverCard), which stays put inside a `<p>` instead of being reparented
+  // by the HTML parser. That keeps the server markup and the first client
+  // render identical, so there is no hydration mismatch — and it preserves the
+  // inline-safety guarantee (no block elements injected into a paragraph).
+  const renderedHoverCard = hoverCard.renderHoverCard(content, {
+    xstyle,
+    className,
+    style,
+  });
 
   // For text-only children: use inline span with ref on wrapper
   if (textOnly) {

package/src/HoverCard/useHoverCard.tsx

@@ -58,8 +58,12 @@ const styles = stylex.create({
     marginInlineStart: spacingVars['--spacing-1'],
     marginInlineEnd: spacingVars['--spacing-1'],
   },
-  // Content wrapper for padding and mouse events
+  // Content wrapper for padding and mouse events.
+  // `display: block` keeps the wrapper a block box even though it renders as a
+  // `span` (the layer uses inline-safe phrasing markup so it is valid inside a
+  // paragraph and produces identical server/client markup).
   content: {
+    display: 'block',
     paddingBlockStart: spacingVars['--spacing-3'],
     paddingBlockEnd: spacingVars['--spacing-3'],
     paddingInlineStart: spacingVars['--spacing-3'],
@@ -234,9 +238,7 @@ function isFocusable(element: HTMLElement): boolean {
  * {hoverCard.renderHoverCard(<ProfileCard user={user} />)}
  * ```
  */
-export function useHoverCard(
-  options: HoverCardOptions = {},
-): HoverCardReturn {
+export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
   const {
     placement = 'above',
     alignment = 'center',
@@ -453,15 +455,16 @@ export function useHoverCard(
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
+        role: 'dialog',
         xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
+        // Render the layer as inline-safe phrasing markup so HoverCard stays
+        // valid (and hydration-stable) inside inline contexts like a `<p>`.
+        as: 'span' as const,
       };
 
       return layer.render(
-        <div
-          {...mergeProps(
-            themeProps('hovercard'),
-            stylex.props(styles.content),
-          )}
+        <span
+          {...mergeProps(themeProps('hovercard'), stylex.props(styles.content))}
           onMouseEnter={() => {
             isHoveringContentRef.current = true;
             clearTimeouts();
@@ -502,7 +505,7 @@ export function useHoverCard(
             scheduleHide();
           }}>
           {children}
-        </div>,
+        </span>,
         renderProps,
       );
     },

package/src/Icon/Icon.doc.mjs

@@ -7,6 +7,14 @@ export const docs = {
   displayName: 'Icon',
   category: 'Content',
   keywords: ["icon","svg","glyph","symbol","pictogram","graphic","vector"],
+  playground: {
+    // `icon` is required and its type can't be auto-generated, so the
+    // properties-tab preview showed "Missing: icon". Seed a valid semantic
+    // icon name so the interactive preview renders.
+    defaults: {
+      icon: 'search',
+    },
+  },
   props: [
     {
       name: 'icon',

package/src/Kbd/Kbd.tsx

@@ -45,7 +45,7 @@ const styles = stylex.create({
     backgroundColor: colorVars['--color-neutral'],
     borderBottomWidth: '2px',
     borderBottomStyle: 'solid',
-    borderBottomColor: colorVars['--color-border'],
+    borderBottomColor: colorVars['--color-border-emphasized'],
     color: colorVars['--color-text-secondary'],
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-supporting-size'],
@@ -146,14 +146,7 @@ export interface KbdProps extends BaseProps<HTMLSpanElement> {
  * <Kbd keys="mod+k" />
  * ```
  */
-export function Kbd({
-  keys,
-  ref,
-  xstyle,
-  className,
-  style,
-  ...rest
-}: KbdProps) {
+export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
   const isMac = useSyncExternalStore(
     subscribeToPlatformChanges,
     detectMac,

package/src/Layer/anchorName.test.ts

@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file anchorName.test.ts
+ * @input Uses vitest, anchorName utilities
+ * @output Unit tests for anchor-name list manipulation helpers
+ * @position Testing; validates anchorName.ts implementation
+ *
+ * SYNC: When anchorName.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+  readAnchorNames,
+  writeAnchorNames,
+  addAnchorName,
+  removeAnchorName,
+} from './anchorName';
+
+function createMockElement(): HTMLElement {
+  const el = document.createElement('div');
+  return el;
+}
+
+describe('readAnchorNames', () => {
+  it('returns empty array for element with no anchor-name', () => {
+    const el = createMockElement();
+    expect(readAnchorNames(el)).toEqual([]);
+  });
+
+  it('reads a single anchor name', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '--layer-1';
+    expect(readAnchorNames(el)).toEqual(['--layer-1']);
+  });
+
+  it('reads multiple comma-separated anchor names', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName =
+      '--layer-1, --layer-2, --layer-3';
+    expect(readAnchorNames(el)).toEqual([
+      '--layer-1',
+      '--layer-2',
+      '--layer-3',
+    ]);
+  });
+
+  it('trims whitespace around names', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName =
+      '  --layer-1 ,  --layer-2  ';
+    expect(readAnchorNames(el)).toEqual(['--layer-1', '--layer-2']);
+  });
+
+  it('returns empty array for empty string value', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '';
+    expect(readAnchorNames(el)).toEqual([]);
+  });
+});
+
+describe('writeAnchorNames', () => {
+  it('writes names as comma-separated list', () => {
+    const el = createMockElement();
+    writeAnchorNames(el, ['--layer-1', '--layer-2']);
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe(
+      '--layer-1, --layer-2',
+    );
+  });
+
+  it('writes empty string for empty array', () => {
+    const el = createMockElement();
+    writeAnchorNames(el, []);
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe('');
+  });
+});
+
+describe('addAnchorName', () => {
+  it('adds name to element with no existing anchors', () => {
+    const el = createMockElement();
+    addAnchorName(el, '--layer-1');
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe(
+      '--layer-1',
+    );
+  });
+
+  it('appends name to existing anchor list', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '--layer-1';
+    addAnchorName(el, '--layer-2');
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe(
+      '--layer-1, --layer-2',
+    );
+  });
+
+  it('does not duplicate an already-present name', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '--layer-1';
+    addAnchorName(el, '--layer-1');
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe(
+      '--layer-1',
+    );
+  });
+
+  it('supports multiple layers sharing one element', () => {
+    const el = createMockElement();
+    addAnchorName(el, '--menu-1');
+    addAnchorName(el, '--menu-2');
+    addAnchorName(el, '--menu-3');
+    expect(readAnchorNames(el)).toEqual(['--menu-1', '--menu-2', '--menu-3']);
+  });
+});
+
+describe('removeAnchorName', () => {
+  it('removes name from a multi-anchor list', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName =
+      '--layer-1, --layer-2, --layer-3';
+    removeAnchorName(el, '--layer-2');
+    expect(readAnchorNames(el)).toEqual(['--layer-1', '--layer-3']);
+  });
+
+  it('removes the last remaining name, leaving empty string', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '--layer-1';
+    removeAnchorName(el, '--layer-1');
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe('');
+  });
+
+  it('is a no-op if name is not present', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName =
+      '--layer-1, --layer-2';
+    removeAnchorName(el, '--layer-3');
+    expect(readAnchorNames(el)).toEqual(['--layer-1', '--layer-2']);
+  });
+
+  it('handles multiple add/remove cycles correctly', () => {
+    const el = createMockElement();
+    addAnchorName(el, '--menu-a');
+    addAnchorName(el, '--menu-b');
+    removeAnchorName(el, '--menu-a');
+    addAnchorName(el, '--menu-c');
+    expect(readAnchorNames(el)).toEqual(['--menu-b', '--menu-c']);
+  });
+});

package/src/Layer/anchorName.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file anchorName.ts
+ * @input HTMLElement with CSS anchor-name property
+ * @output Helpers for managing comma-separated anchor-name lists
+ * @position Utility; used by useLayer for multi-anchor support
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/useLayer.tsx (imports from here)
+ */
+
+/**
+ * CSS `anchor-name` is a comma-separated list, so multiple layers can anchor to
+ * the same element (e.g. several TopNavMegaMenus anchored to one <nav>). These
+ * helpers add/remove a single layer's anchor id without clobbering the others —
+ * overwriting the whole property would break every sibling layer's positioning.
+ */
+
+export function readAnchorNames(el: HTMLElement): string[] {
+  const value =
+    (el.style as unknown as Record<string, string>).anchorName ?? '';
+  return value
+    .split(',')
+    .map(name => name.trim())
+    .filter(Boolean);
+}
+
+export function writeAnchorNames(el: HTMLElement, names: string[]): void {
+  (el.style as unknown as Record<string, string>).anchorName = names.join(', ');
+}
+
+export function addAnchorName(el: HTMLElement, name: string): void {
+  const names = readAnchorNames(el);
+  if (!names.includes(name)) {
+    names.push(name);
+    writeAnchorNames(el, names);
+  }
+}
+
+export function removeAnchorName(el: HTMLElement, name: string): void {
+  writeAnchorNames(
+    el,
+    readAnchorNames(el).filter(existing => existing !== name),
+  );
+}

package/src/Layer/useLayer.doc.mjs

@@ -78,7 +78,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.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. 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.',
     },
   ],
   usage: {
@@ -95,6 +95,11 @@ export const docs = {
         description:
           'Build on higher-level components like Popover, HoverCard, and Tooltip for common overlay patterns.',
       },
+      {
+        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.',
+      },
       {
         guidance: false,
         description:
@@ -125,7 +130,7 @@ 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.',
+    render: 'renders popover element; pass placement/alignment or x/y. Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal.',
   },
   usage: {
     description: