@astryxdesign/core 0.6.1 → 0.6.2-canary.023c3e4

package/src/ClickableCard/ClickableCard.test.tsx

@@ -2,6 +2,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import {ClickableCard} from './ClickableCard';
 
 describe('ClickableCard', () => {
@@ -47,6 +48,47 @@ describe('ClickableCard', () => {
     expect(handleClick).toHaveBeenCalledTimes(1);
   });
 
+  it('calls onClick once when the accessible control itself is clicked', () => {
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleClick}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    // Pointer activation aimed at the element carrying the role — what
+    // speech input, assistive technology, and automation dispatch.
+    fireEvent.click(screen.getByRole('button', {name: 'Test card'}));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('passes the card surface as currentTarget for surface clicks', () => {
+    const seen: EventTarget[] = [];
+    render(
+      <ClickableCard
+        label="Test card"
+        onClick={e => seen.push(e.currentTarget)}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    fireEvent.click(screen.getByText('Content'));
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toBe(screen.getByText('Content').parentElement);
+  });
+
+  it('calls onClick exactly once when the surface of an href card is clicked without preventDefault', () => {
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Nav card" href="/settings" onClick={handleClick}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    // The container hook proxies the surface click to the link with
+    // `link.click()`; that synthetic click bubbles back through the card and
+    // must not run the consumer callback a second time.
+    fireEvent.click(screen.getByText('Content'));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
   it('does NOT call onClick when a nested button is clicked', () => {
     const handleCardClick = vi.fn();
     const handleButtonClick = vi.fn();
@@ -86,25 +128,80 @@ describe('ClickableCard', () => {
     expect(link).toHaveAttribute('target', '_blank');
   });
 
-  it('disabled button is disabled', () => {
+  it('disabled button is disabled and the surface runs nothing', () => {
     const handleClick = vi.fn();
     render(
       <ClickableCard label="Disabled" onClick={handleClick} isDisabled>
-        Content
+        <span>Content</span>
       </ClickableCard>,
     );
     const button = screen.getByRole('button', {name: 'Disabled'});
     expect(button).toBeDisabled();
+    fireEvent.click(screen.getByText('Content'));
+    fireEvent.click(button);
+    expect(handleClick).not.toHaveBeenCalled();
   });
 
-  it('disabled link has aria-disabled', () => {
+  it('disabled link has aria-disabled, leaves the tab order, and the surface runs nothing', () => {
+    const handleClick = vi.fn();
     render(
-      <ClickableCard label="Disabled link" href="/settings" isDisabled>
-        Content
+      <ClickableCard
+        label="Disabled link"
+        href="/settings"
+        onClick={handleClick}
+        isDisabled>
+        <span>Content</span>
       </ClickableCard>,
     );
     const link = screen.getByRole('link', {name: 'Disabled link'});
     expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).toHaveAttribute('tabindex', '-1');
+    fireEvent.click(screen.getByText('Content'));
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+
+  it('runs onClick once from the keyboard via the hidden button', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleClick}>
+        <span>Content</span>
+      </ClickableCard>,
+    );
+    await user.tab();
+    expect(screen.getByRole('button', {name: 'Test card'})).toHaveFocus();
+    await user.keyboard('{Enter}');
+    await user.keyboard(' ');
+    expect(handleClick).toHaveBeenCalledTimes(2);
+  });
+
+  it('does NOT call onClick when a nested input is clicked', () => {
+    const handleCardClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleCardClick}>
+        <input aria-label="Quantity" readOnly value="1" />
+      </ClickableCard>,
+    );
+    fireEvent.click(screen.getByRole('textbox', {name: 'Quantity'}));
+    expect(handleCardClick).not.toHaveBeenCalled();
+  });
+
+  it('does NOT call onClick when text inside the card is selected', () => {
+    const handleClick = vi.fn();
+    render(
+      <ClickableCard label="Test card" onClick={handleClick}>
+        <span>Selectable body text</span>
+      </ClickableCard>,
+    );
+    const text = screen.getByText('Selectable body text');
+    const range = document.createRange();
+    range.selectNodeContents(text);
+    const selection = document.getSelection()!;
+    selection.removeAllRanges();
+    selection.addRange(range);
+    fireEvent.click(text);
+    expect(handleClick).not.toHaveBeenCalled();
+    selection.removeAllRanges();
   });
 
   describe('elevation', () => {

package/src/Collapsible/Collapsible.doc.mjs

@@ -82,6 +82,17 @@ export const docs = {
     {name: 'CollapsibleGroup'},
   ],
   usage: {
+    accessibility: [
+      {
+        name: 'Trigger label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Pointer down'],
+        description:
+          'The trigger text must have at least 4.5:1 contrast with the surface behind it. For Pointer down, measure against the pressed overlay the trigger row paints while it is pressed.',
+      },
+    ],
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior. For custom collapsible components, use the `useCollapsible` hook directly (`astryx hook useCollapsible`).',
     bestPractices: [
       { guidance: true, description: 'Use hasDividers on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.' },

package/src/Collapsible/Collapsible.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, within} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {Collapsible} from './Collapsible';
 import {CollapsibleGroup} from './CollapsibleGroup';
 
@@ -615,3 +616,23 @@ describe('Collapsible', () => {
     });
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay on the trigger row while it is pressed', () => {
+    render(
+      <Collapsible trigger="Details">
+        <p>Body</p>
+      </Collapsible>,
+    );
+    expect(hasPressedArm(screen.getByRole('button'))).toBe(true);
+  });
+
+  it('does not press a disabled trigger', () => {
+    render(
+      <Collapsible trigger="Details" isDisabled>
+        <p>Body</p>
+      </Collapsible>,
+    );
+    expect(hasPressedArm(screen.getByRole('button'))).toBe(false);
+  });
+});

package/src/Collapsible/Collapsible.tsx

@@ -48,6 +48,7 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 
 const styles = stylex.create({
   root: {
@@ -411,6 +412,10 @@ export function Collapsible({
           focusOutlineProps.focusVisible(
             styles.trigger,
             density != null && triggerDensity[density],
+            // The system's pressed overlay on the disclosure row. The trigger
+            // has no hover surface of its own, so this is the one background
+            // it paints, and only while it is pressed.
+            !isDisabled && interactionOverlayStyles.pressedBackgroundColor,
             isDisabled && styles.triggerDisabled,
           ),
         )}>

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -73,9 +73,14 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     color: colorVars['--color-text-primary'],
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     padding: 0,

package/src/ComplexSelector/ComplexSelector.tsx

@@ -65,9 +65,14 @@ const styles = stylex.create({
     paddingBlock: spacingVars['--spacing-2'],
     paddingInline: spacingVars['--spacing-3'],
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-label-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-label-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateInput/DateInput.tsx

@@ -99,9 +99,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateInput/NativeDateField.tsx

@@ -100,10 +100,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
-    // Below 16px iOS zooms the page when the field takes focus.
+    // Below 16px iOS zooms the page when the field takes focus. Only iOS
+    // WebKit implements -webkit-touch-callout, so the coarse-pointer floor is
+    // keyed to iOS alone.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],
@@ -112,11 +116,20 @@ const styles = stylex.create({
     // A date control's intrinsic height comes from its inner edit fields, not
     // from `line-height`, so it renders ~2px taller than a text input and its
     // value sits off the shared baseline inside the same flex row. One line
-    // box is exactly what the text field occupies.
-    height: stylex.firstThatWorks(
-      '1lh',
-      `calc(max(1rem, ${typeScaleVars['--text-body-size']}) * ${typeScaleVars['--text-body-leading']})`,
-    ),
+    // box is exactly what the text field occupies. The calc fallback mirrors
+    // the iOS-only floor above; browsers with `1lh` track it for free.
+    height: {
+      default: stylex.firstThatWorks(
+        '1lh',
+        `calc(${typeScaleVars['--text-body-size']} * ${typeScaleVars['--text-body-leading']})`,
+      ),
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': stylex.firstThatWorks(
+          '1lh',
+          `calc(max(1rem, ${typeScaleVars['--text-body-size']}) * ${typeScaleVars['--text-body-leading']})`,
+        ),
+      },
+    },
     // iOS gives date controls their own button-like chrome, with inner
     // spacing and a centred value that no reset of ours can reach.
     WebkitAppearance: 'none',
@@ -187,9 +200,12 @@ const styles = stylex.create({
     // covers — one line of that leading fills its height exactly, which puts
     // the glyphs on the input's own baseline.
     display: 'block',
+    // ...with the input's own iOS floor, so the two baselines stay shared.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     // A tap has to reach the control underneath — that is what raises the

package/src/DateInput/TouchDateField.tsx

@@ -194,10 +194,14 @@ const styles = stylex.create({
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
     // Below 16px iOS zooms the page on focus. The field is focusable even
-    // though it is not typable, so it needs the same floor DateInput has.
+    // though it is not typable, so it needs the same floor DateInput has —
+    // keyed to iOS alone, since only iOS WebKit implements
+    // -webkit-touch-callout.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateRangeInput/DateRangeInput.doc.mjs

@@ -114,7 +114,7 @@ export const docs = {
       name: 'presets',
       type: 'Array<DateRangePreset>',
       description:
-        'Preset ranges shown as quick-select options beside the calendar.',
+        'Preset ranges shown as quick-select options beside the calendar. A preset is disabled when either endpoint violates min, max, or dateConstraints, or when its span violates minRangeSpan or maxRangeSpan.',
     },
     {
       name: 'hasClear',
@@ -178,9 +178,21 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-date-range-input', visualProps: ['size', 'status'], states: ['disabled']},
+      {
+        className: 'astryx-date-range-input',
+        visualProps: ['size', 'status'],
+        states: ['disabled'],
+      },
       {className: 'astryx-date-range-input-toggle-icon', states: ['state']},
-      {className: 'astryx-date-range-input-clear-icon', deprecatedFor: 'input-clear-icon'},
+      {
+        className: 'astryx-date-range-input-clear-icon',
+        deprecatedFor: 'input-clear-icon',
+      },
+      {className: 'astryx-date-range-input-presets'},
+      {
+        className: 'astryx-date-range-input-preset',
+        states: ['selected', 'disabled'],
+      },
     ],
   },
   usage: {
@@ -230,6 +242,12 @@ export const docs = {
         description:
           'Text above the trigger describing what date range is expected.',
       },
+      {
+        name: 'Field surface',
+        required: true,
+        description:
+          'Bordered control containing the calendar toggle, range trigger, and end affordances.',
+      },
       {
         name: 'Trigger button',
         required: true,
@@ -252,6 +270,12 @@ export const docs = {
         required: false,
         description: 'A list of preset range options beside the calendar.',
       },
+      {
+        name: 'Preset button',
+        required: false,
+        description:
+          'A quick-select action for one preset range, reflecting current and disabled states.',
+      },
       {
         name: 'Clear button',
         required: false,
@@ -320,7 +344,8 @@ export const docsDense = {
     isDisabled: 'disable trigger+picker',
     disabledMessage:
       'reason shown in a tooltip on hover/focus when disabled; keeps trigger focusable via aria-disabled',
-    value: 'selected range {start, end} or null; import DateRange type from @astryxdesign/core/DateRangeInput (do not redeclare)',
+    value:
+      'selected range {start, end} or null; import DateRange type from @astryxdesign/core/DateRangeInput (do not redeclare)',
     onChange: 'callback on range change; null on clear',
     min: 'min selectable date: ISODateString template literal type (YYYY-MM-DD); use string literal or cast `as ISODateString`',
     max: 'max selectable date: ISODateString template literal type (YYYY-MM-DD); use string literal or cast `as ISODateString`',
@@ -329,15 +354,18 @@ export const docsDense = {
       'max days a range may span, both endpoints counted (7 = a 7-day window); caps the window from the picked start. Selection-only; does not rewrite an over-wide value',
     minRangeSpan:
       'min days a range must span, both endpoints counted (2 forbids a single-day range); repeated start click commits one day when allowed, otherwise cancels; default 1',
-    presets: 'preset ranges as quick-select options',
+    presets:
+      'preset ranges as quick-select options; disabled when an endpoint or span violates the corresponding constraints',
     hasClear: 'clear button when range is set (default true)',
     placeholder: 'placeholder when empty',
     size: 'trigger size',
     status: 'error/warning/success status',
-    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
+    statusVariant:
+      'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     labelTooltip: 'tooltip via info icon at label end',
     numberOfMonths: 'months in calendar (default 2)',
-    weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
+    weekStartsOn:
+      'first day of week in calendar (0=Sunday, or name e.g. "mon")',
     changeAction:
       'async action fired after onChange; drives optimistic UI updates via useTransition',
     isLoading: 'loading state; disables interaction + shows a spinner',

package/src/DateRangeInput/DateRangeInput.spec.md

@@ -0,0 +1,203 @@
+---
+schema_version: 3
+template_version: 4
+kind: component
+id: component:DateRangeInput
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-14
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/DateRangeInput/DateRangeInput.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:input-fields, family:overlay-dismissal]
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# DateRangeInput component contract
+
+## Intent
+
+DateRangeInput presents one controlled date range through a labeled field surface.
+Its trigger opens a Calendar-backed Popover and may include a list of quick-select
+presets beside that calendar.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive theme targets plus corrected preset constraint
+  enforcement; default appearance, DOM semantics, and public props remain unchanged
+- Controlled/uncontrolled behavior: unchanged; DateRangeInput remains controlled
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The composite date-range field surface and its range-display trigger.
+- The optional preset list, each preset action, and reflection of a preset's current
+  and disabled states.
+- Converting a selected Calendar range or preset into `onChange` and
+  `changeAction` output.
+
+**Does not own / non-goals**
+
+- Label, description, and status presentation — owned by `component:Field` and
+  `component:FieldStatus`.
+- Calendar-grid rendering and date-cell interaction — owned by
+  `component:Calendar`.
+- Layer hosting and dismissal — owned by `component:Popover` and
+  `family:overlay-dismissal`.
+- Shared clear-button presentation — owned by `component:Field`.
+
+## Public concepts
+
+No public prop or value domain is added. This contract records the existing
+preset-list anatomy and its additive theming surface.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                             | Basis                                                     | Review state               |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------- |
+| FR1 | DateRangeInput MUST present the controlled `value` and emit range changes without maintaining a competing selected range.                                                                                                                                                                       | Current source, docs, and focused tests                   | Verified current behavior  |
+| FR2 | When presets are present, each preset remains an independent button in one labeled group; the applied preset reflects current state and a preset whose endpoint violates `min`, `max`, or `dateConstraints`, or whose range violates `minRangeSpan` or `maxRangeSpan`, reflects disabled state. | Current source, accessibility comments, and focused tests | Verified current behavior  |
+| FR3 | The preset group and each preset button expose stable theme targets; selected and disabled are states of the preset-button target rather than separate targets.                                                                                                                                 | `architecture:component-theming-surface`; #5417 demand    | Approved additive contract |
+| FR4 | Adding theme targets MUST NOT change the Popover, Calendar, button, focus, or selection semantics those elements already own.                                                                                                                                                                   | Composition boundary and compatibility goal               | Approved additive contract |
+
+### Allowed variation
+
+- **AV1 — Preset content.** A caller may omit presets or provide any number of
+  labeled ranges.
+- **AV2 — Calendar layout.** Calendar month count, date constraints, and range
+  bounds may vary without changing preset target identity.
+- **AV3 — Theme output.** Themes may restyle the preset group and buttons while
+  the component's button semantics and state remain unchanged.
+
+### Representative states
+
+| State             | Required invariant                                                                                                                          | Allowed variation       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| No presets        | No preset group or preset-button target renders.                                                                                            | Calendar configuration  |
+| Presets, no match | Every button carries the preset target with no selected state.                                                                              | Preset count and labels |
+| Applied preset    | The matching button carries `aria-current="true"` and the target's selected state.                                                          | Selected range          |
+| Disabled preset   | A preset that violates an endpoint date constraint or a range-span constraint is natively disabled and carries the target's disabled state. | Constraint source       |
+
+### Transformation and precedence order
+
+- **ORD1 — Preset state.** Resolve each preset's range once, compare it with the
+  controlled value, evaluate `min`, `max`, and `dateConstraints` against both
+  endpoints, evaluate `minRangeSpan` and `maxRangeSpan` against the full range,
+  then reflect selected and disabled state on the same preset-button target.
+- **ORD2 — Preset activation.** An enabled preset emits the already-resolved range;
+  activation does not resolve the preset again.
+
+Endpoint constraints match Calendar selection: they apply to the preset's start
+and end, not every date between them.
+
+### Performance and resources
+
+No new performance or resource constraint is introduced.
+
+## Accessibility contract
+
+- **AR1 — Preset semantics.** Presets remain native buttons in one labeled group,
+  navigated independently by Tab.
+- **AR2 — Current state.** The applied preset remains exposed with
+  `aria-current="true"`; theme state reflection is additive.
+- **AR3 — Disabled state.** A preset that violates an endpoint date constraint or
+  a range-span constraint remains natively disabled; theme state reflection does
+  not replace that behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                              | Representation authority              | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------------------- | ------------------------------------- | -------------- | ------------------ |
+| Field surface    | Presents one coherent input boundary.                           | Current source and input-field family | Prominent      | FR1                |
+| Calendar popover | Provides range selection without changing field ownership.      | Popover and Calendar components       | Prominent      | FR1, FR4           |
+| Preset sidebar   | Groups optional shortcuts beside the calendar.                  | Current source and public docs        | Supporting     | FR2, FR3           |
+| Preset button    | Presents one quick-select range and its current/disabled state. | Current source and public docs        | Supporting     | FR2–FR4, AR1–AR3   |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Label": {
+    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
+  },
+  "Field surface": {"target": "date-range-input"},
+  "Trigger button": {
+    "none": {
+      "reason": "unsettled: The composite field surface has a target, but the inner range-display button has no separate current target."
+    }
+  },
+  "Calendar icon": {"target": "date-range-input-toggle-icon"},
+  "Calendar popover": {
+    "delegatesTo": {"owner": "component:Popover", "target": "popover"}
+  },
+  "Preset sidebar": {"target": "date-range-input-presets"},
+  "Preset button": {"target": "date-range-input-preset"},
+  "Clear button": {
+    "delegatesTo": {"owner": "component:Field", "target": "input-clear-button"}
+  },
+  "Status message": {
+    "delegatesTo": {"owner": "component:FieldStatus", "target": "field-status"}
+  }
+}
+```
+
+The deprecated `date-range-input-clear-icon` alias remains compatibility metadata;
+the shared `input-clear-icon` target owns the current glyph contract.
+
+## Family and system relationships
+
+- `family:input-fields` owns field sizing, status placement, loading, disabled
+  reasons, and end-control geometry.
+- `family:overlay-dismissal` owns the Popover dismissal stack.
+- `architecture:component-theming-surface` owns target admission, state
+  reflection, and anatomy mapping.
+
+## Verification map
+
+| Contract            | Verification                                                               | Representative states                                                  | Mutation or failure expectation                                             | Audit section                  |
+| ------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------ |
+| FR1, FR2, AR1–AR3   | `DateRangeInput.test.tsx`                                                  | no match, applied preset, endpoint-invalid preset, span-invalid preset | Semantics or state attributes disappear                                     | `audit:DateRangeInput/presets` |
+| FR3, FR4            | `DateRangeInput.test.tsx`, `themingTargets.test.ts`, generated probe theme | group target, selected button, disabled button                         | Target class/state is missing, undocumented, or placed on the wrong element | `audit:DateRangeInput/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                              | all documented anatomy                                                 | Target ownership or anatomy names drift                                     | `audit:DateRangeInput/theming` |
+
+## Decision log
+
+### DEC-1 — Preset group and buttons are public theme anatomy
+
+**Reference:** `component:DateRangeInput/DEC-1`
+**Decider:** cixzhang, 2026-09-14
+
+The optional preset sidebar and each quick-select button are stable,
+consumer-recognizable parts. `date-range-input-presets` belongs on the group
+that owns sidebar presentation; `date-range-input-preset` belongs on each
+button, with selected and disabled reflected as states rather than separate
+targets. The target additions preserve default visuals and button semantics;
+preset constraint enforcement follows FR2 and ORD1–ORD2.
+
+## Open questions
+
+- **OQ1 — Should the inner range-display trigger receive its own target, or remain
+  represented only by the composite field surface?** (`human-api`)
+
+## Content boundary
+
+This file does not duplicate the consumer prop table, usage examples, Calendar or
+Popover contracts, current audit results, or downstream theme implementation.