@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/DropdownMenu/__tests__/MenuHeaderFooter.a11y.chromium.spec.ts

@@ -31,8 +31,8 @@ test.afterAll(async () => {
 
 const STORY = 'core-dropdownmenu--header-and-footer';
 // The trigger button only: the sub-menu row inside the menu also carries
-// aria-haspopup="menu".
-const TRIGGER = '#storybook-root button[aria-haspopup="menu"]';
+// aria-haspopup. With a header and footer the trigger opens a dialog.
+const TRIGGER = '#storybook-root button[aria-haspopup="dialog"]';
 
 async function openMenu(page: Page) {
   await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`);
@@ -76,7 +76,7 @@ test('typing into the header field filters without moving to a row', async ({
   await expect(page.getByRole('menuitem')).toHaveText(['Design', 'Move to']);
 });
 
-test('Tab walks header, menu, footer, then closes to the trigger', async ({
+test('Tab walks header, menu, footer, and wraps at both ends', async ({
   page,
 }) => {
   const menu = await openMenu(page);
@@ -97,9 +97,44 @@ test('Tab walks header, menu, footer, then closes to the trigger', async ({
   await expect(page.getByTestId('created')).toHaveText('1');
   await expect(menu).toBeVisible();
 
+  // Past the footer's last control, Tab wraps to the header; before the
+  // header's first, Shift+Tab wraps to the footer. The dialog stays open.
   await page.keyboard.press('Tab');
-  await expect(menu).toBeHidden();
-  await expect(page.locator(TRIGGER)).toHaveAttribute('aria-expanded', 'false');
+  await expect(field).toBeFocused();
+  await expect(menu).toBeVisible();
+  await page.keyboard.press('Shift+Tab');
+  await expect(create).toBeFocused();
+  await expect(menu).toBeVisible();
+  await expect(page.locator(TRIGGER)).toHaveAttribute('aria-expanded', 'true');
+});
+
+test('the popover is a modal dialog around the menu, and the trigger points at it', async ({
+  page,
+}) => {
+  const menu = await openMenu(page);
+  const dialog = page.getByRole('dialog', {name: 'Labels'});
+  await expect(dialog).toBeVisible();
+  await expect(dialog).toHaveAttribute('aria-modal', 'true');
+  await expect(
+    dialog.getByRole('menu', {name: 'Labels', exact: true}),
+  ).toBeVisible();
+  await expect(
+    dialog.getByRole('textbox', {name: 'Filter labels'}),
+  ).toBeVisible();
+  await expect(
+    dialog.getByRole('button', {name: 'Create label'}),
+  ).toBeVisible();
+  const trigger = page.locator(TRIGGER);
+  await expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+  const controlsDialog = await trigger.evaluate(el => {
+    const target = document.getElementById(
+      el.getAttribute('aria-controls') ?? '',
+    );
+    const dialogEl = document.querySelector('[role="dialog"]');
+    return target != null && dialogEl != null && target.contains(dialogEl);
+  });
+  expect(controlsDialog).toBe(true);
+  await expect(menu).toBeFocused();
 });
 
 test('Shift+Tab from a row goes straight to the header', async ({page}) => {

package/src/Field/InputClearButton.test.tsx

@@ -25,6 +25,7 @@ import {
   type InputClearButtonProps,
 } from './InputClearButton';
 import {Icon, registerIcons, resetIcons} from '../Icon';
+import {InternationalizationProvider} from '../i18n';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
 import {declaredValue} from '../__tests__/stylexDeclarations';
@@ -95,13 +96,23 @@ describe('InputClearButton public props', () => {
 });
 
 describe('InputClearButton', () => {
-  it('uses the contextual label for the tooltip and accessible name', async () => {
+  it('shows a generic "Clear" tooltip while the accessible name keeps the field label', async () => {
+    // A long field label repeated in the tooltip reads as awkward copy
+    // ("Clear Assigned engineering partner"); the field's own label already
+    // sits beside the glyph. The contextual name stays for assistive tech.
     const showPopover = vi.spyOn(HTMLElement.prototype, 'showPopover');
-    render(<InputClearButton label="Clear Search" onClick={() => {}} />);
+    render(
+      <InputClearButton
+        label="Clear Assigned engineering partner"
+        onClick={() => {}}
+      />,
+    );
 
-    const button = screen.getByRole('button', {name: 'Clear Search'});
+    const button = screen.getByRole('button', {
+      name: 'Clear Assigned engineering partner',
+    });
     const tooltip = screen.getByRole('tooltip', {hidden: true});
-    expect(tooltip).toHaveTextContent(/^Clear Search$/);
+    expect(tooltip).toHaveTextContent(/^Clear$/);
     expect(button.getAttribute('aria-describedby')).toBe(tooltip.id);
 
     fireEvent.mouseEnter(button);
@@ -109,6 +120,20 @@ describe('InputClearButton', () => {
     showPopover.mockRestore();
   });
 
+  it('localizes the tooltip through the catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="en"
+        overrides={{en: {'@astryx.inputClearButton.tooltip': 'Leeren'}}}>
+        <InputClearButton label="Suche leeren" onClick={() => {}} />
+      </InternationalizationProvider>,
+    );
+    expect(screen.getByRole('button', {name: 'Suche leeren'})).toBeTruthy();
+    expect(screen.getByRole('tooltip', {hidden: true})).toHaveTextContent(
+      /^Leeren$/,
+    );
+  });
+
   it('renders a real button with the given accessible label', () => {
     render(<InputClearButton label="Clear" onClick={() => {}} />);
     const button = screen.getByRole('button', {name: 'Clear'});

package/src/Field/InputClearButton.tsx

@@ -4,9 +4,10 @@
 
 /**
  * @file InputClearButton.tsx
- * @input Uses React, Button, and Icon
- * @output Exports the public InputClearButton and an internal popup-aware variant,
- *   both with a contextual tooltip matching their required label.
+ * @input Uses React, Button, Icon, and the i18n translator
+ * @output Exports the public InputClearButton and an internal popup-aware variant.
+ *   Both show the localized generic "Clear" tooltip and keep the caller's
+ *   contextual label as the accessible name.
  * @position Shared primitive. Every input that renders a clear affordance —
  *   TextInput, NumberInput, TimeInput, DateInput, DateTimeInput,
  *   DateRangeInput, Selector, MultiSelector, Typeahead, Tokenizer, FileInput —
@@ -19,6 +20,7 @@ import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Button} from '../Button';
 import {Icon} from '../Icon';
+import {useTranslator} from '../i18n';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -67,7 +69,10 @@ const styles = stylex.create({
 });
 
 export interface InputClearButtonProps {
-  /** Contextual accessible name for the button, such as "Clear Search". */
+  /**
+   * Contextual accessible name for the button, such as "Clear Search". The
+   * visible tooltip is always the localized generic "Clear".
+   */
   label: string;
   onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
   xstyle?: stylex.StyleXStyles;
@@ -83,10 +88,11 @@ interface InternalInputClearButtonProps extends InputClearButtonProps {
 type InputClearButtonRenderProps = InputClearButtonProps &
   Partial<
     Pick<InternalInputClearButtonProps, 'onPointerDown' | 'onClickCapture'>
-  >;
+  > & {tooltip: string};
 
 function renderInputClearButton({
   label,
+  tooltip,
   onClick,
   onPointerDown,
   onClickCapture,
@@ -100,7 +106,11 @@ function renderInputClearButton({
       variant="ghost"
       size="sm"
       label={label}
-      tooltip={label}
+      // The field's label already sits beside the glyph, so the tooltip names
+      // only the action; repeating a long label reads as awkward copy. The
+      // contextual label stays the accessible name, which still contains
+      // the visible word (WCAG 2.5.3, label in name).
+      tooltip={tooltip}
       className={buttonTargetClassName}
       icon={
         <Icon
@@ -128,14 +138,22 @@ function renderInputClearButton({
 }
 
 export function InputClearButton(props: InputClearButtonProps): ReactNode {
-  return renderInputClearButton(props);
+  const t = useTranslator();
+  return renderInputClearButton({
+    ...props,
+    tooltip: t('@astryx.inputClearButton.tooltip'),
+  });
 }
 
 /** Internal variant used while popup-aware clear behavior is rolled out. */
 export function InternalInputClearButton(
   props: InternalInputClearButtonProps,
 ): ReactNode {
-  return renderInputClearButton(props);
+  const t = useTranslator();
+  return renderInputClearButton({
+    ...props,
+    tooltip: t('@astryx.inputClearButton.tooltip'),
+  });
 }
 
 InputClearButton.displayName = 'InputClearButton';

package/src/FieldStatus/__tests__/StatusMessage.a11y.chromium.spec.ts

@@ -168,26 +168,18 @@ async function runState(
   });
 }
 
-test('every expectation is exercised by at least one Core binding state', async ({
-  page,
-}) => {
-  test.setTimeout(4 * 60 * 1000);
-  const cdp = await page.context().newCDPSession(page);
-  const results: BindingResult[] = [];
-  for (const state of CORE_STATUS_MESSAGE_BINDING_STATES) {
-    results.push(await runState(page, cdp, state));
-  }
-  expect(neverExercised(results)).toEqual([]);
-  expect(
-    unmatchedKnownFailures(CORE_STATUS_MESSAGE_KNOWN_FAILURES, results),
-  ).toEqual([]);
-});
+// Each state's result, recorded by its own test below so the whole-suite check
+// at the end reads it instead of measuring every state a second time. A state
+// whose test did not run in this worker (a filtered run, or a worker restarted
+// after a failure) is measured by the whole-suite check itself.
+const recorded = new Map<string, BindingResult>();
 
 for (const state of CORE_STATUS_MESSAGE_BINDING_STATES) {
   test(`${state.binding} [${state.id}] — ${state.summary}`, async ({page}) => {
     test.setTimeout(2 * 60 * 1000);
     const cdp = await page.context().newCDPSession(page);
     const result = await runState(page, cdp, state);
+    recorded.set(state.id, result);
     const report = summarize(STATUS_MESSAGE_PATTERN, [result]);
     // eslint-disable-next-line no-console -- the report is this run's artifact
     console.log(formatReport(report));
@@ -196,3 +188,18 @@ for (const state of CORE_STATUS_MESSAGE_BINDING_STATES) {
     expect(report.counts.unexpectedPass).toBe(0);
   });
 }
+
+test('every expectation is exercised by at least one Core binding state', async ({
+  page,
+}) => {
+  test.setTimeout(4 * 60 * 1000);
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of CORE_STATUS_MESSAGE_BINDING_STATES) {
+    results.push(recorded.get(state.id) ?? (await runState(page, cdp, state)));
+  }
+  expect(neverExercised(results)).toEqual([]);
+  expect(
+    unmatchedKnownFailures(CORE_STATUS_MESSAGE_KNOWN_FAILURES, results),
+  ).toEqual([]);
+});

package/src/FormLayout/FormLayout.tsx

@@ -60,6 +60,7 @@ const styles = stylex.create({
       display: 'flex',
       flexDirection: 'column',
       gap: spacingVars['--spacing-4'],
+      alignItems: 'stretch',
     },
   },
 });

package/src/FormLayout/__snapshots__/FormLayout.test.tsx.snap

@@ -17,7 +17,7 @@ exports[`FormLayout > matches snapshot for horizontal direction 1`] = `
 
 exports[`FormLayout > matches snapshot for horizontal-labels direction 1`] = `
 <div
-  class="astryx-form-layout FormLayout__styles.base xdt5ytf FormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"
+  class="astryx-form-layout FormLayout__styles.base xdt5ytf FormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff x1q32nj3"
   data-direction="horizontal-labels"
   data-testid="layout"
 >

package/src/Grid/Grid.doc.mjs

@@ -27,10 +27,11 @@ export const docs = {
   usage: {
     anatomy,
     description:
-      'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
+      'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. For columns that reflow on small screens, use `columns={{minWidth, max}}`; a numeric `columns` is exactly N columns at every width and never reflows.',
     bestPractices: [
-      { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size: `columns={{minWidth: 280}}`.' },
-      { guidance: true, description: 'Cap the column count with `max` to prevent rows from getting too wide on large screens.' },
+      { guidance: true, description: 'Default to responsive columns for anything that must survive a phone: `columns={{minWidth: 240, max: 4}}` renders at most 4 columns, each at least 240px, and drops to one full-width column when narrow.' },
+      { guidance: false, description: 'Use `columns={4}` for a row that must work on small screens; a number never reflows and renders four narrow tracks on a phone. Reserve numbers for rows that must stay fixed, such as a 7-day week.' },
+      { guidance: true, description: 'Always pair `minWidth` with `max`: `max` caps the count on wide screens and lets the last column shrink to a narrow container; `{minWidth}` alone overflows a phone narrower than `minWidth`.' },
       { guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },
       { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
       { guidance: false, description: 'Use `HStack` with wrapping for grids; use Grid instead.' },
@@ -54,12 +55,12 @@ export const docs = {
       ],
     },
   },
-  description: 'Grid container with fixed or responsive columns.',
+  description: 'Grid container with fixed or responsive columns; `{minWidth, max}` reflows, a number never does.',
   props: [
     {
       name: 'columns',
       type: "number | {minWidth: number, max?: number, repeat?: 'fill' | 'fit'}",
-      description: 'Column configuration. Use a number for fixed columns (e.g. `columns={3}`). Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.',
+      description: 'Column configuration. A number is exactly N equal columns at every width and never reflows (e.g. `columns={3}`); for columns that reflow on small screens, use `{minWidth, max}`. Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.',
     },
     {
       name: 'width',
@@ -129,10 +130,11 @@ export const docsZh = {
   usage: {
     anatomy,
     description:
-      'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
+      'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. For columns that reflow on small screens, use `columns={{minWidth, max}}`; a numeric `columns` is exactly N columns at every width and never reflows.',
     bestPractices: [
-      { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size: `columns={{minWidth: 280}}`.' },
-      { guidance: true, description: 'Cap the column count with `max` to prevent rows from getting too wide on large screens.' },
+      { guidance: true, description: 'Default to responsive columns for anything that must survive a phone: `columns={{minWidth: 240, max: 4}}` renders at most 4 columns, each at least 240px, and drops to one full-width column when narrow.' },
+      { guidance: false, description: 'Use `columns={4}` for a row that must work on small screens; a number never reflows and renders four narrow tracks on a phone. Reserve numbers for rows that must stay fixed, such as a 7-day week.' },
+      { guidance: true, description: 'Always pair `minWidth` with `max`: `max` caps the count on wide screens and lets the last column shrink to a narrow container; `{minWidth}` alone overflows a phone narrower than `minWidth`.' },
       { guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },
       { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
       { guidance: false, description: 'Use `HStack` with wrapping for grids; use Grid instead.' },
@@ -146,10 +148,11 @@ export const docsDense = {
   description: 'CSS Grid-based layout w/ responsive column support.',
   usage: {
     anatomy,
-    description: 'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
+    description: 'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. For columns that reflow on small screens, use `columns={{minWidth, max}}`; a numeric `columns` is exactly N columns at every width and never reflows.',
     bestPractices: [
-      { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size: columns={{minWidth: 280}}.' },
-      { guidance: true, description: 'Cap the column count with max to prevent rows from getting too wide on large screens.' },
+      { guidance: true, description: 'Default to responsive columns for anything that must survive a phone: columns={{minWidth: 240, max: 4}} = at most 4 columns, each >= 240px, one full-width column when narrow.' },
+      { guidance: false, description: 'Use columns={4} for rows that must work on small screens; a number never reflows (4 narrow tracks on a phone). Numbers only for rows that must stay fixed, e.g. a 7-day week.' },
+      { guidance: true, description: 'Always pair minWidth with max: max caps the count on wide screens and lets the last column shrink to a narrow container; {minWidth} alone overflows a phone narrower than minWidth.' },
       { guidance: true, description: 'Use repeat: \'fill\' (the default) for consistent item widths. Use \'fit\' when items should stretch to fill leftover space.' },
       { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
       { guidance: false, description: 'Use HStack with wrapping for grids; use Grid instead.' },

package/src/Grid/Grid.spec.md

@@ -44,36 +44,6 @@ layout, targets, or public API.
 
 Consumer migration instructions belong in consumer docs and release notes.
 
-### DEP-0010 — Deprecate the fixed meaning of numeric `Grid` `columns`
-
-| Field            | Value                                                                                                                                                                                               |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| id               | `DEP-0010`                                                                                                                                                                                          |
-| cleanup          | `CLN-0019`                                                                                                                                                                                          |
-| package          | `@astryxdesign/core`                                                                                                                                                                                |
-| surface          | `Grid` `columns={N}`, which renders exactly N equal tracks (`repeat(N, 1fr)`)                                                                                                                       |
-| old contract     | A numeric `columns` value is an explicit equal-width track count at every width                                                                                                                     |
-| replacement      | `columns={{count: N, isFixed: true}}` keeps exactly N tracks                                                                                                                                        |
-| direct authority | `component:Grid`, with `family:layout-primitives` representative matrix row "Grid / fixed columns". Owners: `cixzhang` (`component:Grid`); `cixzhang`, `imdreamrunner` (`family:layout-primitives`) |
-| warning          | Consumer docs and the release notes name `DEP-0010` and the fixed shape. No runtime warning (`spec:AST-017` FR29)                                                                                   |
-| migration        | Mechanical where the fixed count is wanted: rewrite `columns={N}` to `columns={{count: N, isFixed: true}}`. Keeping the number accepts the new reflow                                               |
-| codemod          | None yet. A preserving codemod is mechanical, but it would opt every caller out of the change it exists to deliver                                                                                  |
-| downstream       | In-repo fixed rows such as week rows use the fixed shape                                                                                                                                            |
-| transition       | no prior transition                                                                                                                                                                                 |
-| state            | `proposed`                                                                                                                                                                                          |
-| open decision    | This record is draft and lists new responsive behavior as a non-goal; the family matrix pins numeric columns as fixed. Both need an owner ruling                                                    |
-| target plan      | `CLN-0019` in the next minor release                                                                                                                                                                |
-
-### CLN-0019 — Numeric `columns` means at most N columns
-
-| Field     | Value                                                                                                                                                                                                 |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| id        | `CLN-0019`                                                                                                                                                                                            |
-| lifecycle | `DEP-0010`                                                                                                                                                                                            |
-| delta     | A numeric `columns` value renders up to N columns of at least 12rem and fewer when the grid is narrower; a `GridSpan` in such a grid takes the full row once the grid has fewer columns than it spans |
-| rollback  | Restore `repeat(N, 1fr)` for numeric `columns` from the final-patch baseline                                                                                                                          |
-| state     | `pending` — lands in a declared minor with its `[breaking]` Changeset                                                                                                                                 |
-
 ## Ownership boundary
 
 **Owns**
@@ -110,6 +80,43 @@ in the canonical `Grid.doc.mjs` and the subordinate `GridSpan.doc.mjs`;
 - A Spanning item may span columns, rows, both, or neither while retaining the
   same target.
 
+### Responsive contract
+
+The `columns` prop decides how many column tracks Grid lays out and whether
+that count changes with the container's width. Other inputs change the result
+only by changing what `columns` has to fit: `width` and `maxWidth` set the
+container width a reflowing shape measures against; an `xstyle`, `className`,
+or `style` that sets the track template (including under a media query)
+replaces the computed one; and a numeric GridSpan wider than the grid's tracks
+makes the browser add implicit tracks to the whole grid, which later items flow
+into. No other prop changes the count.
+
+| `columns`                   | Behavior                                                                                                                                                                                                                                                    | Reflows |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `N` (number)                | Exactly N tracks that share the row equally at every container width; a child wider than its share widens its track and can push the grid past a narrow container.                                                                                          | never   |
+| `{minWidth}`                | As many tracks as fit while each stays at least `minWidth` px wide. A container narrower than `minWidth` keeps one `minWidth`-wide track that overflows it. Empty tracks keep their width.                                                                  | yes     |
+| `{minWidth, repeat: 'fit'}` | As above, and empty tracks collapse so the present items stretch across the row.                                                                                                                                                                            | yes     |
+| `{minWidth, max}`           | Up to `max` tracks, each at least `minWidth` px and never narrower than an equal share of the row; fewer tracks as the container narrows, down to one track that shrinks to the container rather than overflowing it. `repeat: 'fit'` applies the same way. | yes     |
+| omitted, `0`, or negative   | One track.                                                                                                                                                                                                                                                  | never   |
+
+- `gap` and `columnGap` count toward the width a reflowing shape has to fit, so
+  the full count is reached only when the container has room for the tracks and
+  the gaps between them. They never change the count of a numeric `columns`.
+- `height`, `minHeight`, `rowHeight`, `align`, and `justify` size or place the
+  container and its items and do not change the column count.
+- GridSpan spans `k` tracks, or the whole row for `'full'`. `'full'` never
+  adds tracks. A numeric span wider than the grid's current tracks makes the
+  browser add implicit tracks to the grid for the remainder; they persist for
+  every row, items placed before and after the span flow into them, and once
+  they exist `'full'` covers only the explicit tracks. In a reflowing grid keep
+  spans within the smallest count the grid can reach or use `'full'`.
+- For columns that reflow on small screens, use `{minWidth, max}`: `max` is
+  what lets the last track shrink to a narrow container, so `{minWidth}` alone
+  still overflows a phone narrower than `minWidth`. A numeric `columns` never
+  reflows, so a four-up numeric row on a phone renders four narrow tracks, or
+  overflows when a child cannot shrink to its share; that is the fixed
+  contract, not a defect.
+
 ### Representative states
 
 | State          | Required invariant                                        | Allowed variation                                     |
@@ -178,8 +185,19 @@ relationship.
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design,
-layout, accessibility, or API decision.
+### DEC-1 — Numeric `columns` stays fixed; reflow uses the existing object form
+
+**Decider:** `cixzhang`, `2026-10-11`
+
+`columns={N}` means exactly N equal tracks at every width, and a grid that
+reflows on small screens uses `{minWidth, max?, repeat?}`. Two shapes, one
+responsibility each: the number is the fixed contract, the object form is the
+responsive one, and the record and the docs say so where a caller first meets
+`columns`.
+
+Rejected: redefining the number as "at most N" (breaks every released numeric
+grid and needs an opt-out shape); a `{count, isFixed}` shape (duplicates the
+number and the `max` cap).
 
 ## Open questions
 

package/src/Grid/Grid.tsx

@@ -31,7 +31,13 @@ export type GridAlignment = 'start' | 'center' | 'end' | 'stretch';
 /**
  * Column configuration for Grid.
  *
- * - `number` — fixed equal-width columns (e.g. `columns={3}`)
+ * A number means exactly N equal columns at every width; it never reflows, so
+ * `columns={4}` on a phone renders four narrow tracks. For columns that reflow
+ * on small screens, use the object form: `{minWidth: 240, max: 4}` renders at
+ * most four columns, each at least 240px, and fewer when the container is
+ * narrower.
+ *
+ * - `number` — exactly N equal-width columns (e.g. `columns={3}`); never reflows
  * - `object` — responsive columns based on minimum child width:
  *   - `minWidth` — minimum width (px) for each column track
  *   - `repeat` — `'fill'` (default) preserves empty tracks for consistent widths;
@@ -53,9 +59,12 @@ export interface GridProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDivElement>;
   /**
-   * Column configuration.
-   * - `number` — fixed equal-width columns
-   * - `{minWidth, max?, repeat?}` — responsive columns
+   * Column configuration. A number is exactly N equal columns and never
+   * reflows; for columns that reflow on small screens, use
+   * `{minWidth, max}`.
+   * - `number` — exactly N equal-width columns at every width
+   * - `{minWidth, max?, repeat?}` — responsive columns with a px floor and an
+   *   optional cap
    *
    * @see GridColumns
    */

package/src/HoverCard/HoverCard.test.tsx

@@ -18,13 +18,21 @@ import {
   beforeEach,
   afterAll,
 } from 'vitest';
-import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
+import {
+  render,
+  renderHook,
+  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';
+import {useHoverCard} from './useHoverCard';
 import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 
 // Store original matches to restore later
@@ -64,6 +72,43 @@ beforeEach(() => {
   vi.mocked(HTMLElement.prototype.hidePopover).mockClear();
 });
 
+describe('useHoverCard identity', () => {
+  it('keeps callback refs stable across unchanged rerenders', () => {
+    const {result, rerender} = renderHook(() => useHoverCard());
+    const firstRef = result.current.ref;
+    const firstInteractionRef = result.current.interactionRef;
+
+    rerender();
+
+    expect(result.current.ref).toBe(firstRef);
+    expect(result.current.interactionRef).toBe(firstInteractionRef);
+  });
+
+  it('does not rebind trigger listeners on rerender', () => {
+    function Harness() {
+      const card = useHoverCard();
+      return (
+        <div>
+          <span ref={card.ref}>Trigger</span>
+          {card.renderHoverCard(<div>Card</div>)}
+        </div>
+      );
+    }
+    const {getByText, rerender} = render(<Harness />);
+    const trigger = getByText('Trigger');
+    const added: string[] = [];
+    const add = trigger.addEventListener.bind(trigger);
+    trigger.addEventListener = ((type: string, ...rest: unknown[]) => {
+      added.push(type);
+      return (add as (...args: unknown[]) => void)(type, ...rest);
+    }) as typeof trigger.addEventListener;
+
+    rerender(<Harness />);
+
+    expect(added).toEqual([]);
+  });
+});
+
 describe('HoverCard', () => {
   it('renders trigger element', () => {
     render(