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

package/src/HoverCard/HoverCard.doc.mjs

@@ -114,7 +114,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.' },
+      { guidance: true, description: 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.' },
     ],
     anatomy: [
       {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},
@@ -229,7 +229,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.' },
+      { guidance: true, description: 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.' },
     ],
   },
 };
@@ -247,7 +247,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.' },
+      { guidance: true, description: 'Prefer a block context over a direct <p>, heading, or link placement. Those placements work when necessary through a corrective portal, but DOM/tab order may differ.' },
     ],
   },
   components: [

package/src/HoverCard/HoverCard.test.tsx

@@ -9,11 +9,21 @@
  * SYNC: When HoverCard.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  beforeEach,
+  afterAll,
+} from 'vitest';
 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 {Button} from '../Button/Button';
+import {Theme, defineTheme} from '../theme';
 import {HoverCard} from './HoverCard';
 
 // Store original matches to restore later
@@ -48,6 +58,11 @@ afterAll(() => {
   (HTMLElement.prototype as any).matches = originalMatches;
 });
 
+beforeEach(() => {
+  vi.mocked(HTMLElement.prototype.showPopover).mockClear();
+  vi.mocked(HTMLElement.prototype.hidePopover).mockClear();
+});
+
 describe('HoverCard', () => {
   it('renders trigger element', () => {
     render(
@@ -58,31 +73,40 @@ describe('HoverCard', () => {
     expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
   });
 
-  it('exposes the floating layer as role="group" when no label is provided', () => {
+  it('exposes the floating layer as role="group" when no label is provided', async () => {
     render(
-      <HoverCard content={<span>Card content</span>}>
+      <HoverCard content={<span>Card content</span>} delay={0}>
         <button type="button">Trigger</button>
       </HoverCard>,
     );
     // A group may validly be unnamed; an unnamed dialog may not. Without a
     // label the layer must not claim the dialog role.
-    expect(screen.getByRole('group', {hidden: true})).toHaveTextContent(
-      'Card content',
-    );
+    expect(screen.queryByRole('group', {hidden: true})).toBeNull();
     expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();
+
+    fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));
+
+    await waitFor(() => {
+      expect(screen.getByRole('group', {hidden: true})).toHaveTextContent(
+        'Card content',
+      );
+    });
   });
 
-  it('exposes the floating layer as a named dialog when label is provided', () => {
+  it('exposes the floating layer as a named dialog when label is provided', async () => {
     render(
-      <HoverCard content={<span>Card content</span>} label="Profile preview">
+      <HoverCard
+        content={<span>Card content</span>}
+        label="Profile preview"
+        delay={0}>
         <button type="button">Trigger</button>
       </HoverCard>,
     );
-    // The layer is hidden while closed, so assert the accessible name via the
-    // aria-label attribute on the role-carrying element (same pattern as the
-    // Popover dialogLabel test) — accname computation returns '' for hidden
-    // elements.
-    const dialog = screen.getByRole('dialog', {hidden: true});
+    expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();
+
+    fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));
+
+    const dialog = await screen.findByRole('dialog', {hidden: true});
     expect(dialog).toHaveAttribute('aria-label', 'Profile preview');
     expect(dialog).toHaveTextContent('Card content');
     expect(screen.queryByRole('group', {hidden: true})).toBeNull();
@@ -104,52 +128,236 @@ describe('HoverCard', () => {
 
     expect(trigger.parentElement?.tagName).toBe('SPAN');
     expect(paragraph?.querySelector('div')).toBeNull();
+    expect(paragraph?.querySelector('template')).not.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.
+  it('portals block content before showing and restores the marker after hiding', async () => {
+    let contentWasPresentAtShow = false;
+    vi.mocked(HTMLElement.prototype.showPopover).mockImplementationOnce(
+      function (this: HTMLElement) {
+        contentWasPresentAtShow =
+          this.textContent?.includes('Block card content') ?? false;
+        popoverOpenState.set(this, true);
+      },
+    );
+    const consoleErrorSpy = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => {});
+
     const {container} = render(
       <p>
         Before{' '}
-        <HoverCard content={<span>Card content</span>}>
-          <a href="#trigger">Trigger</a>
+        <HoverCard
+          content={<div>Block card content</div>}
+          delay={0}
+          hideDelay={0}>
+          Trigger
         </HoverCard>{' '}
         after
       </p>,
     );
 
     const paragraph = container.querySelector('p');
-    const layer = screen.getByText('Card content').closest('[popover]');
+    const trigger = screen.getByText('Trigger');
 
-    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(screen.queryByText('Block card content')).toBeNull();
+    expect(paragraph?.querySelector('template')).not.toBeNull();
     expect(paragraph?.querySelector('div')).toBeNull();
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+
+    fireEvent.mouseEnter(trigger);
+
+    await waitFor(() => {
+      const content = screen.getByText('Block card content');
+      const layer = content.closest('[popover]');
+
+      expect(layer?.tagName).toBe('DIV');
+      expect(layer?.parentElement).toBe(container);
+      expect(paragraph?.contains(content)).toBe(false);
+      expect(contentWasPresentAtShow).toBe(true);
+      expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+      expect(consoleErrorSpy).not.toHaveBeenCalled();
+    });
+
+    fireEvent.mouseLeave(trigger);
+
+    await waitFor(() => {
+      expect(screen.queryByText('Block card content')).toBeNull();
+      expect(paragraph?.querySelector('template')).not.toBeNull();
+    });
+
+    consoleErrorSpy.mockRestore();
   });
 
-  it('does not show content initially', () => {
+  it('hosts the floating layer outside a wrapping link', async () => {
+    // Interactive ancestors capture the layer's own interactions: a card left
+    // inside an <a> puts its links and buttons inside that link, so clicking
+    // one navigates.
     render(
+      <a href="#profile">
+        <HoverCard
+          content={
+            <span>
+              <a href="#inner">Inner link</a>
+            </span>
+          }
+          delay={0}>
+          Trigger
+        </HoverCard>
+      </a>,
+    );
+
+    const link = screen.getByRole('link', {name: /Trigger/});
+    expect(screen.queryByText('Inner link')).toBeNull();
+    fireEvent.mouseEnter(screen.getByText('Trigger'));
+
+    const layer = (await screen.findByText('Inner link')).closest('[popover]');
+
+    expect(layer).not.toBeNull();
+    expect(link.contains(layer as Node)).toBe(false);
+  });
+
+  it('keeps a safe layer inline at its JSX position', async () => {
+    const {container} = render(
+      <>
+        <HoverCard content={<div>Block card content</div>} delay={0}>
+          <button type="button">Trigger</button>
+        </HoverCard>
+        <button type="button">Following control</button>
+      </>,
+    );
+
+    expect(screen.queryByText('Block card content')).toBeNull();
+    fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));
+
+    await waitFor(() => {
+      const layer = screen.getByText('Block card content').closest('[popover]');
+      const following = screen.getByRole('button', {name: 'Following control'});
+
+      expect(layer?.parentElement).toBe(container);
+      expect(layer?.nextElementSibling).toBe(following);
+    });
+  });
+
+  it('does not render content initially', () => {
+    const {container} = render(
       <HoverCard content={<span>Card content</span>}>
         <button type="button">Trigger</button>
       </HoverCard>,
     );
-    // Content is in DOM (popover not open but element exists)
-    const content = screen.queryByText('Card content');
-    expect(content).toBeInTheDocument();
+    expect(screen.queryByText('Card content')).toBeNull();
+    expect(container.querySelector('[popover]')).toBeNull();
+    expect(container.querySelector('template')).not.toBeNull();
+  });
+
+  it('keeps a paragraph portal inside the nearest nested theme scope', async () => {
+    const outerTheme = defineTheme({name: 'hovercard-outer-test'});
+    const innerTheme = defineTheme({
+      name: 'hovercard-inner-test',
+      components: {
+        hovercard: {base: {borderWidth: '7px'}},
+        button: {base: {fontWeight: '700'}},
+      },
+    });
+
+    const {container} = render(
+      <Theme theme={outerTheme}>
+        <Theme theme={innerTheme}>
+          <p>
+            <HoverCard
+              content={<Button label="View profile">View profile</Button>}
+              delay={0}>
+              Trigger
+            </HoverCard>
+          </p>
+        </Theme>
+      </Theme>,
+    );
+
+    fireEvent.mouseEnter(screen.getByText('Trigger'));
+
+    await waitFor(() => {
+      const button = screen.getByText('View profile').closest('button');
+      const layer = button?.closest('[popover]') ?? null;
+      const innerThemeScope = container.querySelector(
+        '[data-astryx-theme="hovercard-inner-test"]',
+      );
+
+      expect(innerThemeScope).not.toBeNull();
+      expect(button).not.toBeNull();
+      expect(layer?.parentElement).toBe(innerThemeScope);
+      expect(innerThemeScope?.contains(layer)).toBe(true);
+      expect(container.querySelector('p')?.contains(layer)).toBe(false);
+    });
+  });
+
+  it('does not freeze computed CSS variables on a paragraph portal', async () => {
+    const variables = new Map([
+      ['--color-neutral', 'rgb(1, 2, 3)'],
+      ['--color-text-primary', 'rgb(250, 251, 252)'],
+    ]);
+    const getComputedStyleSpy = vi
+      .spyOn(window, 'getComputedStyle')
+      .mockImplementation(
+        element =>
+          ({
+            length: variables.size,
+            item: (index: number) => Array.from(variables.keys())[index] ?? '',
+            getPropertyValue: (property: string) =>
+              variables.get(property) ?? '',
+            direction:
+              element.tagName.toLowerCase() === 'template' ? 'rtl' : 'ltr',
+            writingMode:
+              element.tagName.toLowerCase() === 'template'
+                ? 'vertical-rl'
+                : 'horizontal-tb',
+          }) as CSSStyleDeclaration,
+      );
+
+    const {container} = render(
+      <p>
+        <HoverCard
+          content={<Button label="View profile">View profile</Button>}
+          delay={0}>
+          Trigger
+        </HoverCard>
+      </p>,
+    );
+
+    expect(screen.queryByRole('button', {name: 'View profile'})).toBeNull();
+    fireEvent.mouseEnter(screen.getByText('Trigger'));
+
+    await waitFor(() => {
+      const button = screen.getByRole('button', {name: 'View profile'});
+      const layer = button.closest('[popover]');
+
+      expect(layer?.parentElement).toBe(container);
+      expect(container.querySelector('p')?.contains(button)).toBe(false);
+      expect(layer).not.toBeNull();
+      expect(
+        (layer as HTMLElement).style.getPropertyValue('--color-neutral'),
+      ).toBe('');
+      expect(
+        (layer as HTMLElement).style.getPropertyValue('--color-text-primary'),
+      ).toBe('');
+      expect((layer as HTMLElement).style.direction).toBe('rtl');
+      expect((layer as HTMLElement).style.writingMode).toBe('vertical-rl');
+    });
+
+    getComputedStyleSpy.mockRestore();
   });
 
-  it('applies the theme body font to the floating layer', () => {
+  it('applies the theme body font to the floating layer', async () => {
     render(
-      <HoverCard content={<span>Card content</span>}>
+      <HoverCard content={<span>Card content</span>} delay={0}>
         <button type="button">Trigger</button>
       </HoverCard>,
     );
 
-    const layer = screen.getByText('Card content').closest('[popover]');
+    fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));
+    const layer = (await screen.findByText('Card content')).closest(
+      '[popover]',
+    );
     expect(layer).not.toBeNull();
     expect(getComputedStyle(layer as Element).fontFamily).toBe(
       'var(--font-family-body)',
@@ -435,41 +643,57 @@ describe('HoverCard', () => {
     // `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.
+    // Context layers now render the same inert <template> marker on the server
+    // and the first client render. Arbitrary content mounts only when the card
+    // is requested and its final inline/portal position is known.
 
-    it('renders the floating layer in server markup (no document gate)', () => {
-      const html = renderToString(
+    it('renders only the inert marker before and after hydration', async () => {
+      const tree = (
         <HoverCard content={<span>Card content</span>}>
           <button type="button">Trigger</button>
-        </HoverCard>,
+        </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"/);
+      const serverHTML = renderToString(tree);
+      expect(serverHTML).not.toContain('popover=');
+      expect(serverHTML).not.toContain('Card content');
+      expect(serverHTML).toContain('<template');
+
+      const container = document.createElement('div');
+      container.innerHTML = serverHTML;
+      document.body.appendChild(container);
+
+      let root: ReturnType<typeof hydrateRoot>;
+      await act(async () => {
+        root = hydrateRoot(container, tree);
+      });
+
+      expect(container.querySelector('[popover]')).toBeNull();
+      expect(container.querySelector('template')).not.toBeNull();
+
+      await act(async () => {
+        root.unmount();
+      });
+      container.remove();
     });
 
-    it('keeps the floating layer inline-safe in server markup inside a paragraph', () => {
+    it('emits only a valid marker inside a paragraph', () => {
       const html = renderToString(
         <p>
           Before{' '}
-          <HoverCard content={<span>Card content</span>}>
+          <HoverCard content={<div>Block card content</div>}>
             <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).
+      // <template> is inert phrasing/script-supporting content, so the parser
+      // has no block layer or consumer content to reparent out of the <p>.
       expect(html).not.toContain('<div');
-      expect(html).toMatch(/<span[^>]*popover="manual"/);
+      expect(html).not.toContain('popover=');
+      expect(html).not.toContain('Block card content');
+      expect(html).toContain('<template');
     });
 
     it('server markup matches the first client render (no hydration mismatch)', async () => {
@@ -477,7 +701,7 @@ describe('HoverCard', () => {
         <StrictMode>
           <p>
             Glossary:{' '}
-            <HoverCard content={<span>Definition</span>}>
+            <HoverCard content={<div>Definition</div>}>
               <a href="#term">term</a>
             </HoverCard>
             .
@@ -515,6 +739,8 @@ describe('HoverCard', () => {
 
       expect(hydrationErrors).toEqual([]);
       expect(recoverableErrors).toEqual([]);
+      expect(container.querySelector('[popover]')).toBeNull();
+      expect(container.querySelector('template')).not.toBeNull();
 
       await act(async () => {
         root.unmount();
@@ -533,10 +759,10 @@ describe('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"');
+      // isDefaultOpen must not leak the final layer into SSR markup. The marker
+      // hydrates first; the effect then requests and opens the real popover.
+      expect(serverHTML).not.toContain('popover=');
+      expect(serverHTML).toContain('<template');
 
       const container = document.createElement('div');
       container.innerHTML = serverHTML;
@@ -568,6 +794,8 @@ describe('HoverCard', () => {
       await waitFor(() => {
         expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
       });
+      expect(container.querySelector('[popover]')).not.toBeNull();
+      expect(container).toHaveTextContent('Default open');
 
       await act(async () => {
         root.unmount();

package/src/HoverCard/HoverCard.tsx

@@ -6,7 +6,7 @@
  * @file HoverCard.tsx
  * @input Uses React, useHoverCard hook
  * @output Exports HoverCard component for hover/focus triggered layers
- * @position Layer component; uses inline-safe trigger wrapper and renders the floating layer inline
+ * @position Layer component; inline-safe trigger wrapper, floating layer hosted by useLayer
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/HoverCard/HoverCard.test.tsx
@@ -250,18 +250,10 @@ export function HoverCard({
     };
   }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
 
-  // 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).
+  // While closed, useLayer leaves only an inert <template> marker at this JSX
+  // position. When the card needs to open, it uses that marker to keep the
+  // final layer inline when the parent is safe or portal it outside a <p>,
+  // link, or other ancestor that cannot contain it safely.
   const renderedHoverCard = hoverCard.renderHoverCard(content, {
     xstyle,
     className,

package/src/HoverCard/useHoverCard.tsx

@@ -43,11 +43,7 @@ const styles = stylex.create({
     borderRadius: 'var(--_hovercard-radius)',
     boxShadow: shadowVars['--shadow-med'],
   },
-  // Position-based margin styles
-  // 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 wrapper for padding and interaction events.
   content: {
     display: 'block',
     paddingBlockStart: spacingVars['--spacing-3'],
@@ -254,6 +250,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
   const layer = useLayer({
     mode: 'context',
+    lazyMount: true,
     onShow,
     onHide,
   });
@@ -459,7 +456,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
         // Consumer surface style props land on the layer container — the
         // themed surface (bg/radius/shadow) where the theme class lives — so
         // customizing the card targets the same element as the theme. The inner
-        // span keeps `styles.content` for padding.
+        // div keeps `styles.content` for padding.
         xstyle: [
           popoverXstyle,
           layerAnimations[renderPlacement],
@@ -469,13 +466,13 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
           ? `${themeClassName} ${props.className}`
           : themeClassName,
         style: props?.style,
-        // 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,
+        // useLayer mounts only after it has verified or corrected the parent,
+        // so rich HoverCard content can use block-safe markup.
+        as: 'div' as const,
       };
 
       return layer.render(
-        <span
+        <div
           {...stylex.props(styles.content)}
           onMouseEnter={() => {
             isHoveringContentRef.current = true;
@@ -517,7 +514,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
             scheduleHide();
           }}>
           {children}
-        </span>,
+        </div>,
         renderProps,
       );
     },

package/src/InputGroup/groupStyles.ts

@@ -10,6 +10,11 @@
 import * as stylex from '@stylexjs/stylex';
 import {radiusVars, borderVars} from '../theme/tokens.stylex';
 
+// A grouped control may be followed by context-layer infrastructure rather
+// than another control. Neither the inert marker nor the popover is a visual
+// group member, so skip both when finding the trailing edge.
+const IS_LAST_ITEM = ':not(:has(~ *:not([popover]):not(template)))';
+
 export const groupStyles = stylex.create({
   inGroup: {
     flex: 1,
@@ -29,17 +34,11 @@ export const groupStyles = stylex.create({
     },
     borderStartEndRadius: {
       default: 0,
-      ':last-child': radiusVars['--radius-element'],
-      ':has(+ [popover]:last-child)': radiusVars['--radius-element'],
-      ':has(+ [popover] + [popover]:last-child)':
-        radiusVars['--radius-element'],
+      [IS_LAST_ITEM]: radiusVars['--radius-element'],
     },
     borderEndEndRadius: {
       default: 0,
-      ':last-child': radiusVars['--radius-element'],
-      ':has(+ [popover]:last-child)': radiusVars['--radius-element'],
-      ':has(+ [popover] + [popover]:last-child)':
-        radiusVars['--radius-element'],
+      [IS_LAST_ITEM]: radiusVars['--radius-element'],
     },
     ':focus-within': {
       zIndex: 1,

package/src/Item/Item.doc.mjs

@@ -19,6 +19,10 @@ export const docs = {
     targets: [
       {className: 'astryx-item', visualProps: ['density', 'align']},
     ],
+    vars: [
+      {name: '--_item-label-color', description: 'Color of the label line. Unset by default (the label uses the primary text token); a parent sets it to recolor the label it renders, as the destructive dropdown/context menu item does.', default: 'var(--color-text-primary)', private: true},
+      {name: '--_item-description-color', description: 'Companion to --_item-label-color for the secondary description line.', default: 'var(--color-text-secondary)', private: true},
+    ],
   },
   components: [
     {