@astryxdesign/core 0.6.1 → 0.6.2-canary.2b2113d

package/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts

@@ -0,0 +1,344 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetKeyboard.a11y.browser.spec.ts
+ * @input Built BottomSheet stories and real Chromium/WebKit keyboard input
+ * @output Browser evidence for shared focus delegation, traversal, and native scrolling
+ * @position Cross-browser proof for useScrollableArea's contentOrViewport policy
+ */
+
+import {expect, test, type Page, type Locator} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+// macOS WebKit defaults to text-field traversal. Option+Tab selects its native
+// all-controls traversal, equivalent to enabling Safari's keyboard preference.
+function tabKey(browserName: string, reverse = false): string {
+  return `${browserName === 'webkit' && process.platform === 'darwin' ? 'Alt+' : ''}${reverse ? 'Shift+' : ''}Tab`;
+}
+
+async function mount(page: Page, browserName: string, variant = 'button') {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-bottomsheet--keyboard-delegation&viewMode=story`,
+  );
+  const viewport = page.getByRole('group', {
+    name: 'Keyboard reading',
+    exact: true,
+  });
+  await expect(viewport).toHaveAttribute('data-scrollable-block', 'true');
+  await page.getByLabel('Content case').selectOption(variant);
+  await expect(viewport).toHaveAttribute('tabindex', '0');
+  // WebKit includes the non-modal dialog host in sequential navigation;
+  // Chromium enters its descendants directly. Start immediately before the body.
+  const before =
+    browserName === 'webkit'
+      ? page.getByRole('dialog', {name: 'Keyboard reading', exact: true})
+      : page.getByRole('button', {name: 'Toggle modal', exact: true});
+  await before.focus();
+  return {viewport, before};
+}
+
+for (const variant of ['button', 'link']) {
+  test(`${variant}: forward entry delegates once and reverse traversal exits`, async ({
+    page,
+    browserName,
+  }) => {
+    const {viewport, before} = await mount(page, browserName, variant);
+    const first = page.getByRole(variant === 'button' ? 'button' : 'link', {
+      name: variant === 'button' ? 'First action' : 'First link',
+      exact: true,
+    });
+    await page.keyboard.press(tabKey(browserName));
+    await expect(first).toBeFocused();
+    await expect(viewport).toHaveAttribute('tabindex', '0');
+    await expect(viewport).toHaveAccessibleName('Keyboard reading');
+    await expect(first).toHaveAccessibleName(
+      variant === 'button' ? 'First action' : 'First link',
+    );
+    await page.keyboard.press(tabKey(browserName));
+    await expect(page.getByRole('button', {name: 'Last action'})).toBeFocused();
+    await page.keyboard.press(tabKey(browserName, true));
+    await expect(first).toBeFocused();
+    await page.keyboard.press(tabKey(browserName, true));
+    await expect(before).toBeFocused();
+    await expect(viewport).toHaveAttribute('tabindex', '0');
+    await page.keyboard.press(tabKey(browserName));
+    await expect(first).toBeFocused();
+  });
+}
+
+for (const variant of [
+  'text',
+  'input',
+  'disabled',
+  'nested',
+  'native-scroll',
+  'radiogroup',
+  'slider',
+  'combobox',
+  'listbox',
+  'menu',
+  'grid',
+  'tree',
+  'tablist',
+  'toolbar',
+]) {
+  test(`${variant}: retains a named viewport stop`, async ({
+    page,
+    browserName,
+  }) => {
+    const {viewport, before} = await mount(page, browserName, variant);
+    await page.keyboard.press(tabKey(browserName));
+    await expect(viewport).toBeFocused();
+    await expect(viewport).toHaveAccessibleName('Keyboard reading');
+    await page.keyboard.press(tabKey(browserName, true));
+    await expect(before).toBeFocused();
+  });
+}
+
+async function scrollRange(viewport: Locator) {
+  return viewport.evaluate(element => ({
+    position: element.scrollTop,
+    max: element.scrollHeight - element.clientHeight,
+  }));
+}
+
+for (const key of ['PageDown', 'ArrowDown']) {
+  test(`${key}: reaches both scroll edges after delegation`, async ({
+    page,
+    browserName,
+  }) => {
+    const {viewport} = await mount(page, browserName);
+    await page.keyboard.press(tabKey(browserName));
+    const first = page.getByRole('button', {name: 'First action', exact: true});
+    await expect(first).toBeFocused();
+    for (let count = 0; count < 300; count++) {
+      const {position, max} = await scrollRange(viewport);
+      if (position >= max - 1) {
+        break;
+      }
+      await page.keyboard.press(key, {delay: key === 'ArrowDown' ? 50 : 25});
+    }
+    await expect
+      .poll(async () => {
+        const {position, max} = await scrollRange(viewport);
+        // WebKit can overshoot a native edge while showing rubber-band feedback.
+        return max - position;
+      })
+      .toBeLessThanOrEqual(1);
+    for (let count = 0; count < 300; count++) {
+      if ((await scrollRange(viewport)).position <= 1) {
+        break;
+      }
+      await page.keyboard.press(key === 'PageDown' ? 'PageUp' : 'ArrowUp', {
+        delay: key === 'ArrowDown' ? 50 : 25,
+      });
+    }
+    await expect
+      .poll(async () => (await scrollRange(viewport)).position)
+      .toBeLessThanOrEqual(1);
+    await expect(first).toBeFocused();
+  });
+}
+
+test('pointer and programmatic focus stay on the viewport, including during keydown', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport, before} = await mount(page, browserName);
+  await viewport.focus();
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await viewport.click({position: {x: 4, y: 40}});
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await before.evaluate(element => {
+    element.addEventListener('keydown', event => {
+      if (event instanceof KeyboardEvent && event.key === 'Tab') {
+        event.preventDefault();
+        document
+          .querySelector<HTMLElement>(
+            '[role="group"][aria-label="Keyboard reading"]',
+          )
+          ?.focus();
+      }
+    });
+  });
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+});
+
+test('dynamic eligibility is checked at the next entry without mutation observation', async ({
+  page,
+  browserName,
+}) => {
+  await page.addInitScript(() => {
+    const Original = window.MutationObserver;
+    const observers: MutationObserver[] = [];
+    window.MutationObserver = class extends Original {
+      constructor(callback: MutationCallback) {
+        super(callback);
+        observers.push(this);
+      }
+    };
+    Object.assign(window, {
+      stopMutationObservers: () =>
+        observers.forEach(observer => observer.disconnect()),
+    });
+  });
+  const {viewport, before} = await mount(page, browserName);
+  await page.evaluate(() => {
+    (
+      window as unknown as {stopMutationObservers: () => void}
+    ).stopMutationObservers();
+  });
+  await viewport.focus();
+  const first = page.getByRole('button', {name: 'First action', exact: true});
+  await first.evaluate(element => element.setAttribute('disabled', ''));
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await page.keyboard.press(tabKey(browserName));
+  await expect(page.getByRole('button', {name: 'Last action'})).toBeFocused();
+  await before.focus();
+  await first.evaluate(element => element.removeAttribute('disabled'));
+  await page.keyboard.press(tabKey(browserName));
+  await expect(first).toBeFocused();
+  await before.focus();
+  await viewport.locator('[data-scroll-content]').evaluate(element => {
+    const input = document.createElement('input');
+    input.setAttribute('aria-label', 'Inserted input');
+    element.prepend(input);
+  });
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+  await page.getByLabel('Inserted input').evaluate(element => element.remove());
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await page.keyboard.press(tabKey(browserName));
+  await expect(first).toBeFocused();
+  await before.focus();
+  await first.evaluate(element => element.setAttribute('role', 'combobox'));
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+});
+
+test('modal BottomSheet keeps native focus containment without cycling through the viewport', async ({
+  page,
+  browserName,
+}) => {
+  await mount(page, browserName);
+  await page.getByRole('button', {name: 'Toggle modal', exact: true}).click();
+  const dialog = page.getByRole('dialog', {
+    name: 'Keyboard reading',
+    exact: true,
+  });
+  await expect
+    .poll(async () => dialog.evaluate(element => element.matches(':modal')))
+    .toBe(true);
+  const viewport = page.getByRole('group', {
+    name: 'Keyboard reading',
+    exact: true,
+  });
+  await expect(viewport).toHaveAttribute('data-scrollable-block', 'true');
+  const panel = dialog.locator('.astryx-bottom-sheet');
+  await panel.focus();
+  await page.keyboard.press(tabKey(browserName));
+  const first = page.getByRole('button', {name: 'First action', exact: true});
+  await expect(first).toBeFocused();
+  await page.keyboard.press(tabKey(browserName, true));
+  await expect(viewport).not.toBeFocused();
+  await expect(first).not.toBeFocused();
+  // Native dialog traversal may wrap to another sheet target or browser chrome;
+  // it must never focus the inert background or create a viewport/child loop.
+  await expect(
+    page.getByRole('button', {name: 'Before sheet', includeHidden: true}),
+  ).not.toBeFocused();
+  await expect(viewport).toHaveAttribute('tabindex', '0');
+});
+
+test('fitting text removes the viewport stop while preserving current focus', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport} = await mount(page, browserName, 'text');
+  await viewport.focus();
+  await viewport.locator('[data-scroll-content]').evaluate(element => {
+    element.textContent = 'Short reading content';
+  });
+  await expect(viewport).not.toHaveAttribute('data-scrollable-block', 'true');
+  await expect(viewport).toHaveAttribute('tabindex', '-1');
+  await expect(viewport).toBeFocused();
+});
+
+test('horizontal overflow remains keyboard scrollable after delegation', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport, before} = await mount(page, browserName);
+  await viewport.evaluate(element => {
+    const content = element.querySelector<HTMLElement>('[data-scroll-content]');
+    if (content != null) {
+      content.style.width = `${element.clientWidth + 320}px`;
+    }
+  });
+  await expect(viewport).toHaveAttribute('data-scrollable-inline', 'true');
+  await before.focus();
+  await page.keyboard.press(tabKey(browserName));
+  await expect(
+    page.getByRole('button', {name: 'First action', exact: true}),
+  ).toBeFocused();
+  for (const key of ['ArrowRight', 'ArrowLeft']) {
+    for (let count = 0; count < 100; count++) {
+      const atEdge = await viewport.evaluate(
+        (element, forward) =>
+          forward
+            ? element.scrollLeft >=
+              element.scrollWidth - element.clientWidth - 1
+            : element.scrollLeft <= 1,
+        key === 'ArrowRight',
+      );
+      if (atEdge) {
+        break;
+      }
+      await page.keyboard.press(key, {delay: 50});
+    }
+    await expect
+      .poll(async () =>
+        viewport.evaluate(
+          (element, forward) =>
+            forward
+              ? element.scrollWidth - element.clientWidth - element.scrollLeft
+              : element.scrollLeft,
+          key === 'ArrowRight',
+        ),
+      )
+      .toBeLessThanOrEqual(1);
+  }
+});
+
+test('does not skip an aria-hidden first tab stop to delegate to a later action', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport} = await mount(page, browserName);
+  await page
+    .getByRole('button', {name: 'First action', exact: true})
+    .evaluate(element => {
+      element.setAttribute('aria-hidden', 'true');
+    });
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+});

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.