@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

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/InputGroup/InputGroup.doc.mjs

@@ -92,7 +92,7 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Use text addons to show units, prefixes, or suffixes that clarify the input format (e.g., "$", "kg", "https://").'},
       {guidance: true, description: 'Use InputGroupText for static prefixes/suffixes like "$", "kg", or "https://".'},
-      {guidance: true, description: 'Set isLabelHidden on the inner input and let the group label be visible.'},
+      {guidance: true, description: "Keep each inner input's label specific; grouped inputs automatically combine the group label with their own label and inherit the group description/status context."},
       {guidance: false, description: 'Don\'t put multiple text inputs in one group; use separate fields instead.'},
       {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs; it\'s for a single input with decorations.'},
     ],
@@ -114,7 +114,7 @@ export const docsDense = {
     bestPractices: [
       {guidance: true, description: 'Use text addons to show units, prefixes, or suffixes that clarify input format (e.g. "$", "kg", "https://").'},
       {guidance: true, description: 'Use InputGroupText for static prefixes/suffixes like "$", "kg", or "https://".'},
-      {guidance: true, description: 'Set isLabelHidden on the inner input and let the group label be visible.'},
+      {guidance: true, description: "Keep each inner input's label specific; grouped inputs combine the group label with their own label and inherit group description/status."},
       {guidance: false, description: 'Don\'t put multiple text inputs in one group; use separate fields instead.'},
       {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs; it\'s for a single input with decorations.'},
     ],

package/src/InputGroup/InputGroup.test.tsx

@@ -14,35 +14,113 @@ import {render, screen} from '@testing-library/react';
 import {InputGroup} from './InputGroup';
 import {InputGroupText} from './InputGroupText';
 import {TextInput} from '../TextInput';
+import {NumberInput} from '../NumberInput';
 
 describe('InputGroup', () => {
-  it('renders a group with aria-label', () => {
+  it('names the group via the label element (forms-14)', () => {
     render(
       <InputGroup label="Price">
         <InputGroupText>$</InputGroupText>
-        <TextInput
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
+      </InputGroup>,
+    );
+
+    // The group is named by the field label via aria-labelledby (not a
+    // duplicated aria-label). The label is rendered as a <span> (not a literal
+    // <label>, which can't name a group) and carries no orphaned htmlFor.
+    const group = screen.getByRole('group', {name: 'Price'});
+    expect(group).toBeInTheDocument();
+    expect(group).not.toHaveAttribute('aria-label');
+    const label = screen.getByText('Price');
+    expect(label.tagName).toBe('SPAN');
+    expect(label.closest('label')).toBeNull();
+    expect(label).not.toHaveAttribute('for');
+    expect(group.getAttribute('aria-labelledby')).toBe(label.id);
+  });
+
+  it('associates group description and status through aria-describedby', () => {
+    render(
+      <InputGroup
+        label="Price"
+        description="Enter the amount in USD"
+        status={{type: 'error', message: 'Price is required'}}>
+        <InputGroupText>$</InputGroupText>
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
+      </InputGroup>,
+    );
+
+    const group = screen.getByRole('group', {name: 'Price'});
+    const describedBy = group.getAttribute('aria-describedby');
+    expect(describedBy).toBeTruthy();
+    expect(describedBy!.split(' ')).toHaveLength(2);
+    expect(describedBy).toContain(
+      screen.getByText('Enter the amount in USD').id,
+    );
+    expect(describedBy).toContain(screen.getByText('Price is required').id);
+  });
+
+  it('labels grouped TextInput from the group and inner input labels', () => {
+    render(
+      <InputGroup
+        label="Price"
+        description="Enter the amount in USD"
+        status={{type: 'error', message: 'Price is required'}}>
+        <InputGroupText>$</InputGroupText>
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
+      </InputGroup>,
+    );
+
+    const group = screen.getByRole('group', {name: 'Price'});
+    const groupLabelID = group.getAttribute('aria-labelledby');
+    const describedBy = group.getAttribute('aria-describedby');
+    const input = screen.getByRole('textbox', {name: 'Price Amount'});
+    const labelledByIDs =
+      input.getAttribute('aria-labelledby')?.split(' ') ?? [];
+
+    expect(labelledByIDs).toHaveLength(2);
+    expect(labelledByIDs[0]).toBe(groupLabelID);
+    expect(document.getElementById(labelledByIDs[1])).toHaveTextContent(
+      'Amount',
+    );
+    expect(input).not.toHaveAttribute('aria-label');
+    expect(input).toHaveAttribute('aria-describedby', describedBy);
+  });
+
+  it('labels grouped NumberInput from the group and inner input labels', () => {
+    render(
+      <InputGroup label="Budget" description="Whole dollars only">
+        <InputGroupText>$</InputGroupText>
+        <NumberInput
           label="Amount"
           isLabelHidden
-          value=""
+          value={null}
           onChange={() => {}}
         />
       </InputGroup>,
     );
 
-    const group = screen.getByRole('group');
-    expect(group).toBeInTheDocument();
-    expect(group).toHaveAttribute('aria-label', 'Price');
+    const group = screen.getByRole('group', {name: 'Budget'});
+    const groupLabelID = group.getAttribute('aria-labelledby');
+    const input = screen.getByRole('spinbutton', {name: 'Budget Amount'});
+    const labelledByIDs =
+      input.getAttribute('aria-labelledby')?.split(' ') ?? [];
+
+    expect(labelledByIDs).toHaveLength(2);
+    expect(labelledByIDs[0]).toBe(groupLabelID);
+    expect(document.getElementById(labelledByIDs[1])).toHaveTextContent(
+      'Amount',
+    );
+    expect(input).not.toHaveAttribute('aria-label');
+    expect(input).toHaveAttribute(
+      'aria-describedby',
+      group.getAttribute('aria-describedby'),
+    );
   });
 
   it('renders the visible label', () => {
     render(
       <InputGroup label="Price">
-        <TextInput
-          label="Amount"
-          isLabelHidden
-          value=""
-          onChange={() => {}}
-        />
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
       </InputGroup>,
     );
 
@@ -53,12 +131,7 @@ describe('InputGroup', () => {
     render(
       <InputGroup label="Price">
         <InputGroupText>$</InputGroupText>
-        <TextInput
-          label="Amount"
-          isLabelHidden
-          value=""
-          onChange={() => {}}
-        />
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
       </InputGroup>,
     );
 
@@ -68,12 +141,7 @@ describe('InputGroup', () => {
   it('renders the input', () => {
     render(
       <InputGroup label="Price">
-        <TextInput
-          label="Amount"
-          isLabelHidden
-          value=""
-          onChange={() => {}}
-        />
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
       </InputGroup>,
     );
 
@@ -97,12 +165,7 @@ describe('InputGroup', () => {
   it('applies data-testid', () => {
     render(
       <InputGroup label="Price" data-testid="price-group">
-        <TextInput
-          label="Amount"
-          isLabelHidden
-          value=""
-          onChange={() => {}}
-        />
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
       </InputGroup>,
     );
 
@@ -112,12 +175,7 @@ describe('InputGroup', () => {
   it('renders description text', () => {
     render(
       <InputGroup label="Price" description="Enter the price in USD">
-        <TextInput
-          label="Amount"
-          isLabelHidden
-          value=""
-          onChange={() => {}}
-        />
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
       </InputGroup>,
     );
 
@@ -129,12 +187,7 @@ describe('InputGroup', () => {
       <InputGroup
         label="Price"
         status={{type: 'error', message: 'Price is required'}}>
-        <TextInput
-          label="Amount"
-          isLabelHidden
-          value=""
-          onChange={() => {}}
-        />
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
       </InputGroup>,
     );
 
@@ -144,12 +197,7 @@ describe('InputGroup', () => {
   it('renders with hidden label', () => {
     render(
       <InputGroup label="Price" isLabelHidden>
-        <TextInput
-          label="Amount"
-          isLabelHidden
-          value=""
-          onChange={() => {}}
-        />
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
       </InputGroup>,
     );
 
@@ -160,24 +208,14 @@ describe('InputGroup', () => {
   it('renders with different sizes', () => {
     const {rerender} = render(
       <InputGroup label="Price" size="sm">
-        <TextInput
-          label="Amount"
-          isLabelHidden
-          value=""
-          onChange={() => {}}
-        />
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
       </InputGroup>,
     );
     expect(screen.getByRole('textbox')).toBeInTheDocument();
 
     rerender(
       <InputGroup label="Price" size="lg">
-        <TextInput
-          label="Amount"
-          isLabelHidden
-          value=""
-          onChange={() => {}}
-        />
+        <TextInput label="Amount" isLabelHidden value="" onChange={() => {}} />
       </InputGroup>,
     );
     expect(screen.getByRole('textbox')).toBeInTheDocument();

package/src/InputGroup/InputGroup.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file InputGroup.tsx
- * @input Uses React, StyleX, theme tokens, InputGroupContext
- * @output Exports InputGroup component
+ * @input Uses React, StyleX, theme tokens, InputGroupContext, Field
+ * @output Exports InputGroup component with group label/description ARIA wiring
  * @position Groups input with prefix/suffix addons; consumed by index.ts
  *
  * Children (TextInput, NumberInput) consume the InputGroup context
@@ -156,9 +156,22 @@ export function InputGroup({
 }: InputGroupProps) {
   const size = useSize(sizeProp, 'md');
   const inputId = useId();
+  const labelID = useId();
+  const descriptionID = useId();
   const statusMessageId = useId();
 
-  const contextValue = useMemo(() => ({isInGroup: true as const}), []);
+  const describedByIDs =
+    [
+      description ? descriptionID : null,
+      status?.message ? statusMessageId : null,
+    ]
+      .filter(Boolean)
+      .join(' ') || undefined;
+
+  const contextValue = useMemo(
+    () => ({isInGroup: true as const, labelID, describedByIDs}),
+    [labelID, describedByIDs],
+  );
 
   return (
     <InputGroupContext value={contextValue}>
@@ -168,6 +181,9 @@ export function InputGroup({
           isLabelHidden={isLabelHidden}
           description={description}
           inputID={inputId}
+          labelID={labelID}
+          descriptionID={description ? descriptionID : undefined}
+          isGroupLabel
           isOptional={isOptional}
           isRequired={isRequired}
           isDisabled={isDisabled}
@@ -185,7 +201,8 @@ export function InputGroup({
           <div
             ref={ref}
             role="group"
-            aria-label={label}
+            aria-labelledby={labelID}
+            aria-describedby={describedByIDs}
             data-testid={testId}
             {...rest}
             {...mergeProps(