@astryxdesign/core 0.7.0-canary.fe57f54 → 0.7.0

package/src/CommandPalette/CommandPaletteList.spec.md

@@ -0,0 +1,189 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:CommandPaletteList
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [behavior, accessibility, public-api, theming]
+verified_by:
+  [
+    packages/core/src/CommandPalette/CommandPaletteList.test.tsx,
+    packages/core/src/CommandPalette/CommandPalette.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/CommandPaletteList.stories.tsx,
+    apps/storybook/rtl-audit/verified-not-applicable.json,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-test-sufficiency,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# CommandPaletteList component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. One named listbox container for result options, rendered by CommandPalette or directly for a standalone results list.                                                   |
+| Behavior                | The root is a `listbox` named by `label` or the translated default; inside CommandPalette it carries the context list id that the query field controls.                               |
+| End-user impact         | Screen-reader users reach a named results list from the query field; overflowing results scroll inside the list instead of growing the palette.                                       |
+| Builder impact          | None. CommandPalette renders its own list; standalone compositions render items and groups directly inside this one.                                                                  |
+| Compatibility/readiness | Observational draft with no runtime change. A standalone caller `id` is overwritten (FR1), an empty list keeps the listbox role (AR4), and the standalone keyboard model remains OQ1. |
+| Review checks           | Reject a second list-id owner, a role or name that consumer props can replace, dropped native or styling inputs, or a list target moved off the scrolling root.                       |
+| Governing rules         | `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface`; WAI-ARIA 1.2 `listbox`.                                                                 |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+CommandPaletteList is the scrolling results container of the command palette.
+Inside CommandPalette it is the listbox the query field controls. Standalone, it
+presents a named results listbox around caller-provided option content.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: observational record only; runtime, DOM, styling, target,
+  and public API are unchanged
+- Controlled/uncontrolled behavior: not applicable; the list holds no state
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The listbox root and its accessible name from `label`, falling back to the
+  translated default.
+- Applying the CommandPalette context list id to the root.
+- Native passthrough, `ref`, and styling-input composition on the root.
+- Block-axis scrolling of overflowing children, with spacing-scale padding and
+  gaps.
+
+**Does not own / non-goals**
+
+- List-id generation, query-field focus, active descendant, arrow-key
+  navigation, hover highlight, Enter selection, search, and the choice between
+  results and the empty state — owned by `component:CommandPalette`.
+- The aggregate List anatomy entry and its `command-palette-list` target mapping
+  — owned by `component:CommandPalette`.
+- Option semantics, state, and activation; group semantics and headings — owned
+  by CommandPaletteItem and CommandPaletteGroup.
+- A standalone composite keyboard model; its direction remains OQ1.
+
+## Public concepts
+
+| Concept         | Closed values or states            | Meaning                                           | Availability by variant/orientation/state | Default                                                     | Owner                          | Stability | Invalid-value behavior                                                   |
+| --------------- | ---------------------------------- | ------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- | ------------------------------ | --------- | ------------------------------------------------------------------------ |
+| Accessible name | caller `label`; translated default | Name announced for the results listbox.           | All uses                                  | `@astryx.commandPalette.list.label` ("Commands" in English) | `component:CommandPaletteList` | Stable    | An empty `label` leaves the listbox unnamed; callers supply a real name. |
+| List identity   | context list id; absent            | DOM id the CommandPalette query field references. | Inside CommandPalette; standalone         | Context id inside CommandPalette; absent standalone         | `component:CommandPalette`     | Stable    | A standalone caller `id` is overwritten (FR1 gap).                       |
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                                          | Basis                                                               | Draft review state                                                                                                               |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | Native props and `ref` reach the listbox root, and consumer `className` and `style` combine with the list target and base styles. Inside CommandPalette the root id is the context list id; standalone, an absent id replaces a caller `id`. | Released source; `architecture:public-component-api/INV5,INV6,INV8` | Ref and styling verified by focused tests; the standalone `id` conflicts with INV5                                               |
+| FR2 | The root exposes `role=listbox` with an accessible name from `label`, falling back to the translated default; consumer `role` and `aria-label` props do not replace them.                                                                    | Released source and docs; WAI-ARIA 1.2 `listbox`                    | Role and name verified by focused tests; consumer-prop precedence is source-verified; the role also applies with no option (AR4) |
+| FR3 | Inside CommandPalette, the query field's `aria-controls` names the listbox id.                                                                                                                                                               | Released source and component docs                                  | Verified by a focused composition test                                                                                           |
+| FR4 | The root lays out children in one column with spacing-scale padding and gaps, grows within a flex parent, caps its height at the parent's height, and scrolls overflowing children inside itself.                                            | Released source and component docs                                  | Source-verified; the scrolling fixture renders it in a browser, but scroll geometry is not yet measured                          |
+
+### Allowed variation
+
+- **AV1 — Children.** Items, groups, and empty states may vary in count, order,
+  and content without changing the listbox root.
+- **AV2 — Layout.** Consumer `xstyle`, class, and style may adjust the root
+  without replacing its role, name, id, or target.
+
+### Representative states
+
+| State                 | Required invariant                                                    | Allowed variation          |
+| --------------------- | --------------------------------------------------------------------- | -------------------------- |
+| Standalone results    | The listbox is named by `label` or the translated default.            | Item count and grouping.   |
+| Inside CommandPalette | The root id equals the query field's `aria-controls` value.           | Results count and groups.  |
+| Overflowing results   | Results scroll inside the list instead of growing past the container. | Container and item height. |
+
+### Transformation and precedence order
+
+- **ORD1 — Root attributes.** Consumer native props, then the component-owned
+  id, `listbox` role, and accessible name.
+- **ORD2 — Styling.** List target, then base styles with `xstyle`, then
+  consumer class, then consumer style.
+
+### Performance and resources
+
+- **PR1 — No work beyond render.** The list adds no state, effect, listener, or
+  observer; it reads translation and CommandPalette context during render only.
+
+## Accessibility contract
+
+- **AR1 — Name.** The listbox takes `label` as its accessible name and falls back
+  to the translated default when `label` is omitted.
+- **AR2 — Relationship.** Inside CommandPalette, the query field controls the
+  listbox through its id; CommandPalette owns focus and keyboard navigation under
+  its combobox model.
+- **AR3 — Standalone gap.** A standalone list exposes a listbox of options with
+  no owning keyboard model. OQ1 must settle that contract before runtime
+  semantics change.
+- **AR4 — Empty content.** The root keeps `role=listbox` when its children contain
+  no option, as in CommandPalette's empty states. WAI-ARIA 1.2 requires a listbox
+  to own options, so this is an open conflict, not a contract.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                  | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| List             | Presents result options in one scrolling column with spacing-scale padding and gap. | Current source and public docs | Supporting     | FR1, FR4           |
+
+## Family and system relationships
+
+- `component:CommandPalette` owns list-id generation, keyboard navigation, hover
+  highlight, the aggregate anatomy, and the `command-palette-list` target
+  mapping; this component applies the id and paints the List.
+- `architecture:public-component-api` owns native passthrough, styling
+  composition, and refs.
+- `architecture:component-theming-surface` owns target qualification and the
+  aggregate List anatomy map.
+- `architecture:component-test-sufficiency` owns the evidence rules behind the
+  verification map below.
+
+## Verification map
+
+| Contract | Verification                                                                            | Representative states                      | Mutation or failure expectation                                                                                | Audit section                      |
+| -------- | --------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1      | `CommandPaletteList.test.tsx`                                                           | standalone root with ref, class, and style | Disconnecting `ref`, or dropping the consumer class or the list target, fails focused DOM assertions.          | `audit:CommandPaletteList/api`     |
+| FR2, AR1 | `CommandPaletteList.test.tsx`                                                           | default and caller label                   | Removing the role or name fails the role and name assertions.                                                  | `audit:CommandPaletteList/a11y`    |
+| FR3, AR2 | `CommandPaletteList.test.tsx`, `CommandPalette.test.tsx`                                | inline CommandPalette                      | Dropping the context id breaks the query-field relationship assertion.                                         | `audit:CommandPaletteList/a11y`    |
+| FR4      | Storybook fixtures, `themingTargets.test.ts`, exact-head accessibility and RTL evidence | standalone list; scrolling palette         | Losing the target fails the target inventory; any new directional behavior requires a non-empty RTL dimension. | `audit:CommandPaletteList/theming` |
+
+## Decision log
+
+None. This draft records current facts and settles no component-local API,
+keyboard, or visual decision.
+
+## Open questions
+
+- **OQ1 — What standalone keyboard contract should CommandPaletteList expose?**
+  (`human-api`) A standalone list exposes a listbox of options but no owning
+  keyboard model. Decide whether a public composite owner supplies that model,
+  the standalone composition takes a different role, or standalone use remains
+  pointer-only presentation.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/CommandPalette/CommandPaletteList.test.tsx

@@ -7,7 +7,10 @@
  */
 
 import {describe, it, expect} from 'vitest';
+import {createRef} from 'react';
 import {render, screen} from '@testing-library/react';
+import {createStaticSource} from '@astryxdesign/core/Typeahead';
+import {CommandPalette} from './CommandPalette';
 import {CommandPaletteList} from './CommandPaletteList';
 
 describe('CommandPaletteList', () => {
@@ -54,4 +57,48 @@ describe('CommandPaletteList', () => {
       'Search results',
     );
   });
+
+  it('is the listbox that the CommandPalette query field controls', async () => {
+    render(
+      <CommandPalette
+        isOpen
+        isInline
+        onOpenChange={() => {}}
+        searchSource={createStaticSource([{id: 'home', label: 'Home'}])}
+      />,
+    );
+
+    const listbox = await screen.findByRole('listbox');
+    expect(listbox.id).not.toBe('');
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-controls',
+      listbox.id,
+    );
+  });
+
+  it('connects ref to the listbox element', () => {
+    const ref = createRef<HTMLDivElement>();
+    render(
+      <CommandPaletteList ref={ref}>
+        <div>Item</div>
+      </CommandPaletteList>,
+    );
+
+    expect(ref.current).toBe(screen.getByRole('listbox'));
+  });
+
+  it('combines consumer className and style with the list theme target', () => {
+    render(
+      <CommandPaletteList className="product-results" style={{minHeight: 120}}>
+        <div>Item</div>
+      </CommandPaletteList>,
+    );
+
+    const listbox = screen.getByRole('listbox');
+    expect(listbox).toHaveClass(
+      'astryx-command-palette-list',
+      'product-results',
+    );
+    expect(listbox).toHaveStyle({minHeight: '120px'});
+  });
 });

package/src/CommandPalette/CommandPaletteList.tsx

@@ -59,8 +59,9 @@ export interface CommandPaletteListProps extends BaseProps<HTMLDivElement> {
  * When used inside CommandPalette, automatically gets the correct
  * ID for aria-controls linking with the input.
  *
- * @compositionHint Place inside CommandPalette, after CommandPaletteInput.
- *   Contains CommandPaletteItem and CommandPaletteGroup children.
+ * @compositionHint CommandPalette renders its own list after its input; render
+ *   this list directly only for a standalone results list. Contains
+ *   CommandPaletteItem and CommandPaletteGroup children.
  *
  * @example
  * ```

package/src/DateInput/TouchDateField.tsx

@@ -1296,7 +1296,9 @@ export function TouchDateField({
         label={t('@astryx.dateInput.dialogLabel')}
         // The picker is a fixed height by construction, so the sheet should be
         // exactly as tall as it is rather than claiming a viewport budget.
-        height="hug">
+        height="hug"
+        // sheetBody owns the inset, including the band under the grab handle.
+        padding={0}>
         <div {...stylex.props(styles.sheetBody)}>{surface}</div>
       </BottomSheet>
       {showsDisabledMessage &&

package/src/DateTimeInput/DateTimeInputTouch.test.tsx

@@ -25,7 +25,7 @@ import {
   beforeEach,
   afterEach,
 } from 'vitest';
-import {useState} from 'react';
+import {Profiler, useState} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {readFileSync} from 'node:fs';
 import {render, screen, fireEvent, within} from '@testing-library/react';
@@ -986,3 +986,62 @@ describe('DateTimeInput touch surface', () => {
     expect(field).toHaveAttribute('aria-expanded', 'false');
   });
 });
+
+describe('DateTimeInput touch surface: no stale commit', () => {
+  // Records what each commit painted, so a value that is corrected one render
+  // later (by an effect) shows up as a stale intermediate frame.
+  function paintedFrames(read: () => string) {
+    const frames: string[] = [];
+    const onRender = () => frames.push(read());
+    return {frames, onRender};
+  }
+
+  it('clears the time display in the same commit as an external clear', () => {
+    const {frames, onRender} = paintedFrames(
+      () => (timeField() as HTMLInputElement).value,
+    );
+    const ui = (value: ISODateTimeString | undefined) => (
+      <Profiler id="field" onRender={onRender}>
+        <DateTimeInput label="Meeting" value={value} onChange={() => {}} />
+      </Profiler>
+    );
+    const {rerender} = render(ui('2026-03-15T10:00' as ISODateTimeString));
+    expect(timeField()).toHaveValue('10:00 AM');
+
+    frames.length = 0;
+    rerender(ui(undefined));
+
+    expect(frames.length).toBeGreaterThan(0);
+    expect(frames).not.toContain('10:00 AM');
+    expect(timeField()).toHaveValue('');
+  });
+
+  it('shows an in-range month in the same commit that narrows max', () => {
+    withMonthLayout(() => {
+      const visibleMonth = () =>
+        ['March', 'April', 'May', 'June']
+          .map(m => `${m} 2026`)
+          .find(label => screen.queryByText(label) != null) ?? '';
+      const {frames, onRender} = paintedFrames(visibleMonth);
+      const ui = (max: ISODateTimeString) => (
+        <Profiler id="field" onRender={onRender}>
+          <DateTimeInput label="Meeting" max={max} onChange={() => {}} />
+        </Profiler>
+      );
+      const {rerender} = render(ui('2026-12-31T23:59' as ISODateTimeString));
+      openDateSheet();
+      const next = screen.getByRole('button', {name: 'Next month'});
+      fireEvent.click(next);
+      fireEvent.click(next);
+      fireEvent.click(next);
+      expect(screen.getByText('June 2026')).toBeInTheDocument();
+
+      frames.length = 0;
+      rerender(ui('2026-04-30T23:59' as ISODateTimeString));
+
+      expect(frames.length).toBeGreaterThan(0);
+      expect(frames).not.toContain('June 2026');
+      expect(screen.getByText('April 2026')).toBeInTheDocument();
+    });
+  });
+});

package/src/DateTimeInput/TouchDateTimeField.tsx

@@ -590,15 +590,25 @@ export function TouchDateTimeField({
   );
   const weekStartsOn = normalizeDayOfWeek(weekStartsOnProp);
 
-  useEffect(() => {
+  // The draft follows the controlled time, and an external clear resets it.
+  // Adjusted during render when the value changes, so no commit paints the
+  // previous draft.
+  const [draftSource, setDraftSource] = useState({
+    time: normalizedValueTime,
+    value: optimisticValue,
+  });
+  // Object.is, matching the dependency comparison of the effect this replaces.
+  if (
+    !Object.is(draftSource.time, normalizedValueTime) ||
+    !Object.is(draftSource.value, optimisticValue)
+  ) {
+    setDraftSource({time: normalizedValueTime, value: optimisticValue});
     if (normalizedValueTime !== undefined) {
-      // eslint-disable-next-line @eslint-react/set-state-in-effect -- mirrors an externally controlled time into the sheet-local draft
       setDraftTime(normalizedValueTime);
     } else if (optimisticValue === undefined) {
-      // eslint-disable-next-line @eslint-react/set-state-in-effect -- external clear resets the sheet-local draft too
       setDraftTime(undefined);
     }
-  }, [normalizedValueTime, optimisticValue]);
+  }
 
   const [anchorMonthIndex] = useState(() =>
     monthIndexOf(selectedDate ?? plainDateToday()),
@@ -614,19 +624,23 @@ export function TouchDateTimeField({
   const [monthIndex, setMonthIndex] = useState(() =>
     clampIndex(anchorMonthIndex, minMonthIndex, maxMonthIndex),
   );
+  // min/max can narrow underneath the mounted sheet. Keep the visible month in
+  // range during render, so no commit shows an out-of-range month; the month
+  // scroller is keyed on the range and remounts at the clamped month.
+  const clampedMonthIndex = clampIndex(
+    monthIndex,
+    minMonthIndex,
+    maxMonthIndex,
+  );
+  // Object.is, matching the dependency comparison of the effect this replaces
+  // (a NaN index would otherwise never compare equal and re-render forever).
+  if (!Object.is(clampedMonthIndex, monthIndex)) {
+    setMonthIndex(clampedMonthIndex);
+  }
   const {year, month} = fromMonthIndex(monthIndex);
   const canStepBack = monthIndex > minMonthIndex;
   const canStepForward = monthIndex < maxMonthIndex;
 
-  useEffect(() => {
-    const clamped = clampIndex(monthIndex, minMonthIndex, maxMonthIndex);
-    if (clamped !== monthIndex) {
-      // eslint-disable-next-line @eslint-react/set-state-in-effect -- min/max can change underneath the mounted sheet; keep the visible month in range
-      setMonthIndex(clamped);
-      scrollerHandleRef.current?.scrollToMonth(clamped, 'auto');
-    }
-  }, [monthIndex, minMonthIndex, maxMonthIndex]);
-
   const dayNames = useMemo(
     () =>
       Array.from({length: 7}, (_, offset) =>
@@ -1464,7 +1478,10 @@ export function TouchDateTimeField({
           isOpen={isSheetOpen}
           onOpenChange={handleSheetOpenChange}
           label={t('@astryx.dateTimeInput.dialogLabel')}
-          height="hug">
+          height="hug"
+          // touchSheetBody owns the inset, including the band under the grab
+          // handle.
+          padding={0}>
           <div {...stylex.props(styles.touchSheetBody)}>{surface}</div>
         </BottomSheet>
         {showsDisabledMessage &&

package/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -227,6 +227,18 @@ export const docs = {
       description:
         'Maximum height in pixels for the popover presentation, for a menu that must fit its rows. Lifts the default 300px cap; the viewport still bounds it.',
     },
+    {
+      name: 'header',
+      type: 'ReactNode',
+      description:
+        'Content above the rows and outside the menu itself — a filter field, a toggle. A menu holds only its rows, so a control that is not a row goes here or in `footer`, never among the rows. It keeps its own keys and presses; Tab moves from it into the menu, and Shift+Tab before its first control closes the menu. The bottom sheet shows it above the actions.',
+    },
+    {
+      name: 'footer',
+      type: 'ReactNode',
+      description:
+        'Content below the rows and outside the menu itself — a "Create" button. Tab from the menu moves into it, and Tab past its last control closes the menu. The bottom sheet shows it below the actions.',
+    },
     {
       name: 'placement',
       type: "'above' | 'below' | 'start' | 'end'",