cleanplate 0.3.1 → 0.3.2

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "cleanplate",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "CleanPlate - A Headless React UI Framework",
   "files": [
     "dist",
-    "docs",
+    "docs/*.md",
     "llms.txt",
     "AGENTS.md",
     "CHANGELOG.md"

package/docs/superpowers/plans/2026-05-10-date-picker.md

@@ -1,955 +0,0 @@
-# Date picker (`Date` form control) implementation plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Replace the three-`Select` `Date` field with a calendar date picker that matches `docs/superpowers/specs/2026-05-10-date-picker-design.md` (staged OK/Cancel, popover + mobile sheet like `Select.tsx`, `date-fns` + tests).
-
-**Architecture:** Pure `date-constraints` + `calendar-matrix` modules (unit-tested first), then `use-date-picker-state` (hook tests), then presentational pieces (`DatePickerHeader`, `DatePickerGrid`, `DatePickerFooter`, month/year lists), then `Date.tsx` composing **Floating UI** shell copied from the `Select.tsx` pattern (same `max-width: 768px` breakpoint, portal, backdrop, `translateY`, body scroll lock). No new UI framework.
-
-**Tech Stack:** React 18, `date-fns` (granular imports), `@floating-ui/react`, SCSS modules (`FormControls.module.scss`), Vitest, `@testing-library/react`, jsdom, `@vitejs/plugin-react` for TSX tests.
-
-**Spec:** `docs/superpowers/specs/2026-05-10-date-picker-design.md`
-
----
-
-## File structure (creates / modifies)
-
-| Path | Role |
-|------|------|
-| `package.json` | Add `date-fns`; add devDeps `vitest`, `@vitest/ui`, `@testing-library/react`, `@testing-library/user-event`, `jsdom`, `@vitejs/plugin-react`, `vite`; add script `"test": "vitest run"`, `"test:watch": "vitest"` |
-| `vitest.config.mts` | Vitest + React plugin + `environment: 'jsdom'` |
-| `src/components/form-controls/date/date-types.ts` | Shared internal types (`CalendarCell`, constraint bag) |
-| `src/components/form-controls/date/normalize-date.ts` | `toCalendarDate`, `calendarDatesEqual`, `formatISODate` |
-| `src/components/form-controls/date/date-constraints.ts` | `isDateUnavailable`, navigation helpers |
-| `src/components/form-controls/date/date-constraints.test.ts` | Unit tests |
-| `src/components/form-controls/date/calendar-matrix.ts` | `buildCalendarWeeks` |
-| `src/components/form-controls/date/calendar-matrix.test.ts` | Unit tests |
-| `src/components/form-controls/date/use-date-picker-state.ts` | State machine |
-| `src/components/form-controls/date/use-date-picker-state.test.tsx` | `renderHook` tests |
-| `src/components/form-controls/date/ScrollPicker.tsx` | Reusable scroll list for month/year |
-| `src/components/form-controls/date/DatePickerHeader.tsx` | Arrows + month/year buttons |
-| `src/components/form-controls/date/DatePickerGrid.tsx` | `role="grid"` month |
-| `src/components/form-controls/date/DatePickerFooter.tsx` | Cancel / OK |
-| `src/components/form-controls/date/DatePickerPanel.tsx` | Composes header/grid/footer + subviews |
-| `src/components/form-controls/date/use-date-picker-shell.ts` | Floating + mobile transitions (mirrors Select numbers) |
-| `src/components/form-controls/Date.tsx` | Public API |
-| `src/components/form-controls/FormControls.module.scss` | `.cp-date-picker-*` (+ reuse select tokens where possible) |
-| `src/stories/form-controls/form-controls.stories.tsx` | New `Date` stories |
-| `CHANGELOG.md` or `README` section | Breaking change note |
-
----
-
-## Constants (keep aligned with Select)
-
-Copy from `src/components/form-controls/Select.tsx`:
-
-- Media query string: **`(max-width: 768px)`**
-- `SELECT_MOBILE_SHEET_MS = 300`, desktop fade `200`
-
-Either **duplicate** in `use-date-picker-shell.ts` / `Date.tsx` with a comment `// Keep in sync with Select.tsx`, or extract `form-controls/constants.ts` in a small refactor task (optional YAGNI: duplicate first).
-
----
-
-### Task 0: Dependencies and Vitest scaffolding
-
-**Files:**
-
-- Modify: `package.json`
-- Create: `vitest.config.mts`
-
-- [ ] **Step 1: Apply `package.json` changes**
-
-Merge into `dependencies`:
-
-```json
-"date-fns": "^4.1.0"
-```
-
-Merge into `devDependencies`:
-
-```json
-"@testing-library/jest-dom": "^6.6.3",
-"@testing-library/react": "^16.3.0",
-"@testing-library/user-event": "^14.6.1",
-"@vitejs/plugin-react": "^4.7.0",
-"@vitest/ui": "^3.2.0",
-"jsdom": "^26.1.0",
-"vite": "^6.4.1",
-"vitest": "^3.2.0"
-```
-
-Add scripts:
-
-```json
-"test": "vitest run",
-"test:watch": "vitest"
-```
-
-Run:
-
-```bash
-npm install
-```
-
-Expected: exits 0; `package-lock.json` updates.
-
-- [ ] **Step 2: Add `vitest.config.mts`**
-
-Create `vitest.config.mts`:
-
-```typescript
-import react from "@vitejs/plugin-react";
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  plugins: [react()],
-  test: {
-    environment: "jsdom",
-    globals: true,
-    include: ["src/**/*.test.{ts,tsx}"],
-    setupFiles: ["./vitest.setup.ts"],
-  },
-});
-```
-
-Create `vitest.setup.ts` at repo root:
-
-```typescript
-import "@testing-library/jest-dom/vitest";
-```
-
-- [ ] **Step 3: Verify empty test suite runs**
-
-Create a throwaway `src/smoke.test.ts`:
-
-```typescript
-import { describe, it, expect } from "vitest";
-
-describe("vitest", () => {
-  it("runs", () => {
-    expect(1).toBe(1);
-  });
-});
-```
-
-Run:
-
-```bash
-npm run test
-```
-
-Expected: **1 passed**.
-
-Delete `src/smoke.test.ts`.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add package.json package-lock.json vitest.config.mts vitest.setup.ts
-git commit -m "chore: add date-fns, Vitest, and Testing Library"
-```
-
----
-
-### Task 1: `normalize-date.ts` — calendar-day helpers
-
-**Files:**
-
-- Create: `src/components/form-controls/date/normalize-date.ts`
-- Create: `src/components/form-controls/date/normalize-date.test.ts`
-
-- [ ] **Step 1: Write failing tests `normalize-date.test.ts`**
-
-```typescript
-import { describe, expect, it } from "vitest";
-import {
-  calendarDatesEqual,
-  formatISODate,
-  toCalendarDate,
-} from "./normalize-date";
-
-describe("toCalendarDate", () => {
-  it("normalizes time to local start of calendar day", () => {
-    const d = new Date(2026, 4, 10, 15, 30, 45);
-    const cal = toCalendarDate(d);
-    expect(cal.getFullYear()).toBe(2026);
-    expect(cal.getMonth()).toBe(4);
-    expect(cal.getDate()).toBe(10);
-    expect(cal.getHours()).toBe(0);
-    expect(cal.getMinutes()).toBe(0);
-    expect(cal.getSeconds()).toBe(0);
-    expect(cal.getMilliseconds()).toBe(0);
-  });
-});
-
-describe("calendarDatesEqual", () => {
-  it("matches same calendar day ignoring time", () => {
-    expect(
-      calendarDatesEqual(new Date(2026, 0, 5, 3), new Date(2026, 0, 5, 22)),
-    ).toBe(true);
-  });
-  it("returns false for different days", () => {
-    expect(calendarDatesEqual(new Date(2026, 0, 5), new Date(2026, 0, 6))).toBe(
-      false,
-    );
-  });
-});
-
-describe("formatISODate", () => {
-  it("formats as YYYY-MM-DD", () => {
-    expect(formatISODate(new Date(2026, 4, 10))).toBe("2026-05-10");
-  });
-  it("zero-pads month and day", () => {
-    expect(formatISODate(new Date(2026, 0, 2))).toBe("2026-01-02");
-  });
-});
-```
-
-Run:
-
-```bash
-npm run test -- src/components/form-controls/date/normalize-date.test.ts
-```
-
-Expected: **FAIL** (module missing).
-
-- [ ] **Step 2: Implement `normalize-date.ts`**
-
-```typescript
-import { format } from "date-fns/format";
-import { startOfDay } from "date-fns/startOfDay";
-
-/** Local calendar midnight for comparisons and hidden-field values. */
-export function toCalendarDate(d: Date): Date {
-  return startOfDay(d);
-}
-
-export function calendarDatesEqual(a: Date | null, b: Date | null): boolean {
-  if (a == null || b == null) return a === b;
-  const ca = toCalendarDate(a).getTime();
-  const cb = toCalendarDate(b).getTime();
-  return ca === cb;
-}
-
-export function formatISODate(d: Date): string {
-  return format(toCalendarDate(d), "yyyy-MM-dd");
-}
-```
-
-Run:
-
-```bash
-npm run test -- src/components/form-controls/date/normalize-date.test.ts
-```
-
-Expected: **PASS**.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/components/form-controls/date/normalize-date.ts src/components/form-controls/date/normalize-date.test.ts
-git commit -m "feat(date-picker): add calendar date normalization helpers"
-```
-
----
-
-### Task 2: `date-constraints.ts`
-
-**Files:**
-
-- Create: `src/components/form-controls/date/date-types.ts`
-- Create: `src/components/form-controls/date/date-constraints.ts`
-- Create: `src/components/form-controls/date/date-constraints.test.ts`
-
-- [ ] **Step 1: Add `date-types.ts`**
-
-```typescript
-/** 0 Sun … 6 Sat — matches date-fns `getDay`. */
-export type Constraints = {
-  minDate?: Date;
-  maxDate?: Date;
-  disabledDates?: Date[];
-  disabledDaysOfWeek?: number[];
-};
-```
-
-- [ ] **Step 2: Write failing tests (subset — expand inline if any fail during TDD)**
-
-`src/components/form-controls/date/date-constraints.test.ts`:
-
-```typescript
-import { describe, expect, it } from "vitest";
-import {
-  clampDateToConstraints,
-  isDateUnavailable,
-  isMonthFullyBeforeMin,
-  isMonthFullyAfterMax,
-} from "./date-constraints";
-import { toCalendarDate } from "./normalize-date";
-
-const constraints = {
-  minDate: toCalendarDate(new Date(2026, 4, 5)),
-  maxDate: toCalendarDate(new Date(2026, 4, 20)),
-  disabledDates: [toCalendarDate(new Date(2026, 4, 12))],
-  disabledDaysOfWeek: [0, 6] as number[],
-};
-
-describe("isDateUnavailable", () => {
-  it("disables before min", () => {
-    expect(isDateUnavailable(new Date(2026, 4, 4), constraints)).toBe(true);
-  });
-  it("disables after max", () => {
-    expect(isDateUnavailable(new Date(2026, 4, 21), constraints)).toBe(true);
-  });
-  it("disables weekday Sunday", () => {
-    expect(isDateUnavailable(new Date(2026, 4, 10), constraints)).toBe(true); // Sun
-  });
-  it("allows enabled weekday inside range", () => {
-    expect(isDateUnavailable(new Date(2026, 4, 7), constraints)).toBe(false); // Thu
-  });
-  it("disables explicit blacklist", () => {
-    expect(isDateUnavailable(new Date(2026, 4, 12), constraints)).toBe(true);
-  });
-});
-
-describe("clampDateToConstraints", () => {
-  it("returns min when before", () => {
-    const d = clampDateToConstraints(new Date(2026, 3, 1), constraints);
-    expect(d.getTime()).toBe(constraints.minDate.getTime());
-  });
-  it("returns max when after", () => {
-    const d = clampDateToConstraints(new Date(2027, 0, 1), constraints);
-    expect(d.getTime()).toBe(constraints.maxDate.getTime());
-  });
-});
-
-describe("month navigation helpers", () => {
-  it("detects month before min", () => {
-    expect(isMonthFullyBeforeMin(new Date(2026, 3, 1), constraints.minDate)).toBe(
-      true,
-    );
-  });
-  it("detects month after max", () => {
-    expect(isMonthFullyAfterMax(new Date(2026, 6, 1), constraints.maxDate)).toBe(
-      true,
-    );
-  });
-});
-```
-
-Run tests — expect **FAIL**.
-
-- [ ] **Step 3: Implement `date-constraints.ts`**
-
-```typescript
-import { endOfMonth } from "date-fns/endOfMonth";
-import { getDay } from "date-fns/getDay";
-import { startOfMonth } from "date-fns/startOfMonth";
-import type { Constraints } from "./date-types";
-import { calendarDatesEqual, toCalendarDate } from "./normalize-date";
-
-function hasMin(minDate?: Date): minDate is Date {
-  return minDate != null;
-}
-
-function hasMax(maxDate?: Date): maxDate is Date {
-  return maxDate != null;
-}
-
-/** True if selecting this calendar date is forbidden. */
-export function isDateUnavailable(d: Date, c: Constraints): boolean {
-  const day = toCalendarDate(d).getTime();
-  if (hasMin(c.minDate) && day < toCalendarDate(c.minDate).getTime()) {
-    return true;
-  }
-  if (hasMax(c.maxDate) && day > toCalendarDate(c.maxDate).getTime()) {
-    return true;
-  }
-  const dow = getDay(toCalendarDate(d));
-  if (c.disabledDaysOfWeek?.includes(dow)) {
-    return true;
-  }
-  if (
-    c.disabledDates?.some((bd) =>
-      calendarDatesEqual(toCalendarDate(bd), toCalendarDate(d)),
-    )
-  ) {
-    return true;
-  }
-  return false;
-}
-
-export function clampDateToConstraints(d: Date, c: Constraints): Date {
-  let x = toCalendarDate(d);
-  if (hasMin(c.minDate) && x.getTime() < toCalendarDate(c.minDate).getTime()) {
-    x = toCalendarDate(c.minDate);
-  }
-  if (hasMax(c.maxDate) && x.getTime() > toCalendarDate(c.maxDate).getTime()) {
-    x = toCalendarDate(c.maxDate);
-  }
-  return x;
-}
-
-export function isMonthFullyBeforeMin(month: Date, minDate?: Date): boolean {
-  if (!hasMin(minDate)) return false;
-  const end = endOfMonth(month);
-  return end.getTime() < toCalendarDate(minDate).getTime();
-}
-
-export function isMonthFullyAfterMax(month: Date, maxDate?: Date): boolean {
-  if (!hasMax(maxDate)) return false;
-  const start = startOfMonth(month);
-  return start.getTime() > toCalendarDate(maxDate).getTime();
-}
-```
-
-Adjust tests if `2026-4-10` weekday differs in local TZ — authors run tests in UTC or fix expected Sunday date. **Freeze expected dates using `new Date(year, monthIndex, day)`** (local) as above; if CI uses weird TZ, add `TZ=UTC` env in npm script optional.
-
-Run:
-
-```bash
-npm run test -- src/components/form-controls/date/date-constraints.test.ts
-```
-
-Expected: **PASS**.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add src/components/form-controls/date/date-types.ts src/components/form-controls/date/date-constraints.ts src/components/form-controls/date/date-constraints.test.ts
-git commit -m "feat(date-picker): add date constraint helpers"
-```
-
----
-
-### Task 3: `calendar-matrix.ts`
-
-**Files:**
-
-- Create: `src/components/form-controls/date/calendar-matrix.ts`
-- Create: `src/components/form-controls/date/calendar-matrix.test.ts`
-
-- [ ] **Step 1: Failing tests**
-
-```typescript
-import { describe, expect, it } from "vitest";
-import { buildCalendarWeeks } from "./calendar-matrix";
-
-describe("buildCalendarWeeks", () => {
-  it("returns 6 rows for May 2026 starting Sunday", () => {
-    const may = new Date(2026, 4, 1);
-    const weeks = buildCalendarWeeks(may, 0);
-    expect(weeks.length >= 5).toBe(true);
-    const flat = weeks.flat();
-    expect(flat.some((c) => c.inCurrentMonth && c.date.getDate() === 1)).toBe(true);
-    expect(flat.some((c) => c.inCurrentMonth && c.date.getDate() === 31)).toBe(true);
-  });
-  it("marks outside-month cells", () => {
-    const may = new Date(2026, 4, 1);
-    const weeks = buildCalendarWeeks(may, 0);
-    const outs = weeks.flat().filter((c) => !c.inCurrentMonth);
-    expect(outs.length).toBeGreaterThan(0);
-  });
-});
-```
-
-- [ ] **Step 2: Implementation**
-
-```typescript
-import { addDays } from "date-fns/addDays";
-import { endOfMonth } from "date-fns/endOfMonth";
-import { isSameMonth } from "date-fns/isSameMonth";
-import { startOfMonth } from "date-fns/startOfMonth";
-import { startOfWeek } from "date-fns/startOfWeek";
-
-export type CalendarCell = {
-  date: Date;
-  inCurrentMonth: boolean;
-};
-
-export function buildCalendarWeeks(
-  displayedMonth: Date,
-  weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6,
-): CalendarCell[][] {
-  const monthStart = startOfMonth(displayedMonth);
-  const gridStart = startOfWeek(monthStart, { weekStartsOn });
-  const monthEnd = endOfMonth(displayedMonth);
-
-  const cells: CalendarCell[] = [];
-  let cursor = gridStart;
-
-  while (cells.length < 42) {
-    cells.push({
-      date: cursor,
-      inCurrentMonth: isSameMonth(cursor, monthStart),
-    });
-    cursor = addDays(cursor, 1);
-    if (cells.length >= 35 && cursor.getTime() > monthEnd.getTime()) {
-      break;
-    }
-    if (cells.length === 42) break;
-  }
-
-  while (cells.length % 7 !== 0) {
-    cells.push({
-      date: cursor,
-      inCurrentMonth: isSameMonth(cursor, monthStart),
-    });
-    cursor = addDays(cursor, 1);
-  }
-
-  const weeks: CalendarCell[][] = [];
-  for (let i = 0; i < cells.length; i += 7) {
-    weeks.push(cells.slice(i, i + 7));
-  }
-  return weeks;
-}
-```
-
-If the loop logic fails tests (boundary), simplify to fixed **42 cells** (6 rows × 7) starting `startOfWeek(startOfMonth)` — always match Google Calendar style.
-
-Run tests; fix implementation until **PASS**.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/components/form-controls/date/calendar-matrix.ts src/components/form-controls/date/calendar-matrix.test.ts
-git commit -m "feat(date-picker): build calendar week matrix"
-```
-
----
-
-### Task 4: `use-date-picker-state.ts` + hook tests
-
-**Files:**
-
-- Create: `src/components/form-controls/date/use-date-picker-state.ts`
-- Create: `src/components/form-controls/date/use-date-picker-state.test.tsx`
-
-**State rules:**
-
-- **Controlled** when `value !== undefined`; **uncontrolled** when `value === undefined`, seed from `defaultValue ?? null`.
-- On **open:** `staged = committed` (controlled: last `value`; uncontrolled: internal committed). If `committed` is null, `staged = firstAvailableFrom(today)` using `clampDateToConstraints(new Date(), c)` then forward **addDays** until `!isDateUnavailable` or **max 120** iterations (fallback: clamped date anyway).
-- **confirm:** assign committed = staged (internal state); call `onChange(staged)`; `isOpen = false`; keep `displayedMonth` as-is unless you prefer syncing — **freeze:** `displayedMonth` unchanged on confirm.
-- **cancel:** `staged = committed`; `isOpen = false` (committed comes from controlled `value` when controlled).
-- **selectDay(d):** `staged = toCalendarDate(d)`; if day not in visible month bucket, **`displayedMonth = startOfMonth(d)`**.
-- Month nav exposes `goPrevMonth` / `goNextMonth` mutating **`displayedMonth`** with **`addMonths`**, clamped so you never navigate into `isMonthFullyBeforeMin` / `isMonthFullyAfterMax` months (skip silently or clamp — **freeze:** clamp to nearest valid month).
-
-- [ ] **Step 1: Write `use-date-picker-state.test.tsx`** (fail first)
-
-Create `src/components/form-controls/date/use-date-picker-state.test.tsx`:
-
-```tsx
-import { act, renderHook } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
-import { useDatePickerState } from "./use-date-picker-state";
-
-describe("useDatePickerState", () => {
-  it("open copies committed calendar day to staged", () => {
-    const d = new Date(2026, 4, 10);
-    const { result } = renderHook(() =>
-      useDatePickerState({
-        value: d,
-        defaultValue: undefined,
-        onChange: vi.fn(),
-        constraints: {},
-      }),
-    );
-    act(() => result.current.open());
-    expect(result.current.isOpen).toBe(true);
-    expect(result.current.staged?.getFullYear()).toBe(2026);
-    expect(result.current.staged?.getMonth()).toBe(4);
-    expect(result.current.staged?.getDate()).toBe(10);
-  });
-
-  it("cancel restores staged from committed after selectDay", () => {
-    const d = new Date(2026, 4, 10);
-    const { result } = renderHook(() =>
-      useDatePickerState({
-        value: d,
-        defaultValue: undefined,
-        onChange: vi.fn(),
-        constraints: {},
-      }),
-    );
-    act(() => result.current.open());
-    act(() => result.current.selectDay(new Date(2026, 4, 18)));
-    expect(result.current.staged?.getDate()).toBe(18);
-    act(() => result.current.cancel());
-    expect(result.current.isOpen).toBe(false);
-    expect(result.current.staged?.getDate()).toBe(10);
-  });
-
-  it("confirm calls onChange and closes", () => {
-    const d = new Date(2026, 4, 10);
-    const fn = vi.fn();
-    const { result } = renderHook(() =>
-      useDatePickerState({
-        value: d,
-        defaultValue: undefined,
-        onChange: fn,
-        constraints: {},
-      }),
-    );
-    act(() => result.current.open());
-    act(() => result.current.selectDay(new Date(2026, 4, 12)));
-    act(() => result.current.confirm());
-    expect(fn).toHaveBeenCalledTimes(1);
-    expect(fn.mock.calls[0][0].getDate()).toBe(12);
-    expect(result.current.isOpen).toBe(false);
-  });
-});
-```
-
-Run:
-
-```bash
-npm run test -- src/components/form-controls/date/use-date-picker-state.test.tsx
-```
-
-Expected: **FAIL** (missing implementation).
-
-- [ ] **Step 2: Implement `use-date-picker-state.ts`**
-
-Create `src/components/form-controls/date/use-date-picker-state.ts`:
-
-```typescript
-import { addDays } from "date-fns/addDays";
-import { addMonths } from "date-fns/addMonths";
-import { startOfMonth } from "date-fns/startOfMonth";
-import { useCallback, useEffect, useState } from "react";
-import type { Constraints } from "./date-types";
-import {
-  clampDateToConstraints,
-  isDateUnavailable,
-  isMonthFullyAfterMax,
-  isMonthFullyBeforeMin,
-} from "./date-constraints";
-import { toCalendarDate } from "./normalize-date";
-
-export type PanelView = "calendar" | "month" | "year";
-
-export interface UseDatePickerStateArgs {
-  value: Date | null | undefined;
-  defaultValue: Date | null | undefined;
-  onChange?: (d: Date | null) => void;
-  constraints: Constraints;
-}
-
-export interface UseDatePickerStateReturn {
-  isOpen: boolean;
-  panelView: PanelView;
-  setPanelView: (v: PanelView) => void;
-  committed: Date | null;
-  staged: Date | null;
-  displayedMonth: Date;
-  open: () => void;
-  close: () => void;
-  cancel: () => void;
-  confirm: () => void;
-  selectDay: (d: Date) => void;
-  clearCommitted: () => void;
-  goPrevMonth: () => void;
-  goNextMonth: () => void;
-  setDisplayedMonthFromYearMonth: (year: number, monthIndex: number) => void;
-}
-
-function firstSelectableFrom(seed: Date, c: Constraints): Date {
-  let x = clampDateToConstraints(seed, c);
-  for (let i = 0; i < 120; i += 1) {
-    if (!isDateUnavailable(x, c)) return x;
-    x = clampDateToConstraints(addDays(x, 1), c);
-  }
-  return x;
-}
-
-/** Snap a calendar month anchor so min/max ranges always show a navigable month. */
-function clampDisplayedMonth(monthStart: Date, c: Constraints): Date {
-  if (isMonthFullyBeforeMin(monthStart, c.minDate) && c.minDate != null) {
-    return startOfMonth(c.minDate);
-  }
-  if (isMonthFullyAfterMax(monthStart, c.maxDate) && c.maxDate != null) {
-    return startOfMonth(c.maxDate);
-  }
-  return monthStart;
-}
-
-export function useDatePickerState(
-  args: UseDatePickerStateArgs,
-): UseDatePickerStateReturn {
-  const controlled = args.value !== undefined;
-
-  const [uncontrolledCommitted, setUncontrolledCommitted] =
-    useState<Date | null>(() =>
-      controlled ? null : args.defaultValue ?? null,
-    );
-
-  const committed = controlled ? args.value ?? null : uncontrolledCommitted;
-
-  const [isOpen, setIsOpen] = useState(false);
-  const [panelView, setPanelView] = useState<PanelView>("calendar");
-  const [staged, setStaged] = useState<Date | null>(null);
-  const [displayedMonth, setDisplayedMonth] = useState<Date>(() =>
-    clampDisplayedMonth(startOfMonth(committed ?? new Date()), args.constraints),
-  );
-
-  useEffect(() => {
-    if (isOpen) return;
-    const anchor = committed ?? new Date();
-    setDisplayedMonth(
-      clampDisplayedMonth(startOfMonth(anchor), args.constraints),
-    );
-  }, [
-    args.constraints,
-    isOpen,
-    committed?.getFullYear?.(),
-    committed?.getMonth?.(),
-    committed?.getDate?.(),
-    controlled,
-    committed,
-  ]);
-
-  const pushCommitted = useCallback(
-    (next: Date | null) => {
-      if (!controlled) setUncontrolledCommitted(next);
-      args.onChange?.(next);
-    },
-    [args, controlled],
-  );
-
-  const close = useCallback(() => {
-    setIsOpen(false);
-    setPanelView("calendar");
-  }, []);
-
-  const open = useCallback(() => {
-    if (committed != null) {
-      const cal = toCalendarDate(committed);
-      setStaged(cal);
-      setDisplayedMonth(
-        clampDisplayedMonth(startOfMonth(cal), args.constraints),
-      );
-    } else {
-      const seed = firstSelectableFrom(new Date(), args.constraints);
-      setStaged(seed);
-      setDisplayedMonth(
-        clampDisplayedMonth(startOfMonth(seed), args.constraints),
-      );
-    }
-    setPanelView("calendar");
-    setIsOpen(true);
-  }, [args.constraints, committed]);
-
-  const cancel = useCallback(() => {
-    setStaged(committed == null ? null : toCalendarDate(committed));
-    close();
-  }, [close, committed]);
-
-  const confirm = useCallback(() => {
-    if (staged == null) {
-      pushCommitted(null);
-    } else {
-      const cal = clampDateToConstraints(staged, args.constraints);
-      if (isDateUnavailable(cal, args.constraints)) {
-        close();
-        return;
-      }
-      pushCommitted(cal);
-    }
-    close();
-  }, [args.constraints, close, pushCommitted, staged]);
-
-  const selectDay = useCallback(
-    (d: Date) => {
-      const cal = clampDateToConstraints(toCalendarDate(d), args.constraints);
-      setStaged(cal);
-      setDisplayedMonth(
-        clampDisplayedMonth(startOfMonth(cal), args.constraints),
-      );
-    },
-    [args.constraints],
-  );
-
-  const clearCommitted = useCallback(() => {
-    pushCommitted(null);
-    setStaged(null);
-    close();
-  }, [close, pushCommitted]);
-
-  const goPrevMonth = useCallback(() => {
-    setDisplayedMonth((prev) =>
-      clampDisplayedMonth(addMonths(prev, -1), args.constraints),
-    );
-  }, [args.constraints]);
-
-  const goNextMonth = useCallback(() => {
-    setDisplayedMonth((prev) =>
-      clampDisplayedMonth(addMonths(prev, 1), args.constraints),
-    );
-  }, [args.constraints]);
-
-  const setDisplayedMonthFromYearMonth = useCallback(
-    (year: number, monthIndex: number) => {
-      setDisplayedMonth(
-        clampDisplayedMonth(
-          startOfMonth(new Date(year, monthIndex, 1)),
-          args.constraints,
-        ),
-      );
-    },
-    [args.constraints],
-  );
-
-  return {
-    isOpen,
-    panelView,
-    setPanelView,
-    committed,
-    staged,
-    displayedMonth,
-    open,
-    close,
-    cancel,
-    confirm,
-    selectDay,
-    clearCommitted,
-    goPrevMonth,
-    goNextMonth,
-    setDisplayedMonthFromYearMonth,
-  };
-}
-```
-
-Run:
-
-```bash
-npm run test -- src/components/form-controls/date/use-date-picker-state.test.tsx
-```
-
-Expected: **PASS**. If **`confirm`** test fails because **`onChange`** is not invoked when controlled: in controlled mode **`pushCommitted` only forwards `args.onChange`** — parent updates **`value`**; re-render updates **`committed`**. **`uncontrolledCommitted`** stays unused when controlled (initial hook state `(controlled ? null : …)` avoids duplicating **`args.value`** in local state).
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/components/form-controls/date/use-date-picker-state.ts src/components/form-controls/date/use-date-picker-state.test.tsx
-git commit -m "feat(date-picker): add useDatePickerState hook"
-```
-
----
-
-### Task 5: Presentational components
-
-Implement in order (each file complete; each gets **one** RTL test file `DatePickerPanel.test.tsx` at end of task):
-
-1. `ScrollPicker.tsx` — `role="listbox"` optional; scroll container; `onPick(value)`.
-2. `DatePickerHeader.tsx` — props: `displayedMonth`, `locale`, `weekStartsOn` irrelevant here; `onPrevMonth`, `onNextMonth`, `prevDisabled`, `nextDisabled`, `onOpenMonth`, `onOpenYear`, `monthLabel`, `yearLabel`.
-3. `DatePickerGrid.tsx` — props: `weeks`, `weekdayLabels`, `staged`, `today`, `isDateDisabled`, `onSelectDay`, `focusedDate`, `onRequestFocus` for keyboard.
-4. `DatePickerFooter.tsx` — Cancel / OK buttons.
-5. `DatePickerPanel.tsx` — switches `panelView` between `calendar | month | year`; wires children.
-
-**Keyboard note:** Implement roving `tabIndex` on gridcells: only one `tabIndex={0}` at a time; arrows move `focusedDate`. Enter/Space stages day. PageUp/Down change month on grid. Home/End jump to first/last **navigable** day in month (skip disabled).
-
-- [ ] **RTL test `DatePickerPanel.test.tsx`:** open panel (wrap with state), click day, click OK — expect `onChange` called once with that date.
-
-- [ ] **Commit:** `feat(date-picker): add DatePickerPanel UI`
-
----
-
-### Task 6: Shell — `useDatePickerFloating` inside `Date.tsx`
-
-Mirror `Select.tsx` lines roughly **253–867** (`useFloating`, `FloatingPortal`, `useClick`, `useDismiss`, transition classes `selectPanelEntered` / `exitAnimating` pattern).
-
-**Concrete requirements:**
-
-- `useDismiss`: `outsidePress` → call state `cancel()` then `onClose` (mirror close sequence).
-- **Escape:** `useDismiss` already listens; pipe to **cancel**.
-- Desktop: **`width: 280`**, **`flip`, `shift`, `offset(4)`, `padding: 8`**, **`autoUpdate`** — **omit** Select’s `size` width-to-reference behavior (spec: fixed **280px**).
-- Mobile: reuse classes **`cp-select-mobile-backdrop`**, **`cp-select-mobile-sheet`**, **`cp-select-mobile-sheet-entered`** OR duplicate with **`cp-date-picker-*`** aliases in SCSS that `@extend` select classes (preferred to avoid divergence).
-
-- [ ] **Commit:** `feat(date-picker): add floating portal and mobile sheet`
-
----
-
-### Task 7: `Date.tsx` public component
-
-Replace `src/components/form-controls/Date.tsx`:
-
-- Props per design spec §9 (**`isDisabled`**, **`readOnly`** optional, **`popoverPlacement`**, **`clearable`**, **`name` hidden ISO**, **`dateFormat`**, **`locale`**, etc.).
-- Trigger: looks like `Select` trigger (reuse `cp-select-field-header` / create `cp-date-picker-trigger` matching height).
-- `readOnly` + `isDisabled` block open.
-- `useId` for ids; `aria-expanded`, `aria-controls`, `aria-invalid` from `error`.
-
-- [ ] **Commit:** `feat(date-picker): replace Date form control with calendar picker`
-
----
-
-### Task 8: SCSS
-
-- Add **`cp-date-picker-*`** tokens; **`--cp-date-picker-panel`** width **280px** on desktop sheet/panel wrapper.
-- Match wireframe: large radius, muted panel background — use existing form token colors where possible.
-- **44px** min tap targets on header arrows and grid cells (`min-height` / `padding`).
-
-- [ ] **Commit:** `style(date-picker): add panel and grid presentation`
-
----
-
-### Task 9: Storybook
-
-In `src/stories/form-controls/form-controls.stories.tsx`, add **`Date`** stories:
-
-- Default controlled with `useState`.
-- **`minDate` / `maxDate`** DOB example.
-- **`disabledDaysOfWeek`**.
-
-Manual: shrink viewport `< 768px` to visually verify sheet.
-
-- [ ] **Commit:** `docs(storybook): add Date picker stories`
-
----
-
-### Task 10: Barrel exports & migration note
-
-- `src/components/form-controls/index.ts` — export **`DateProps`** reflecting new typings (remove old string `onChange`).
-- Root `CHANGELOG.md` (**create** if missing): **Breaking:** `Date` API migration paragraph.
-
-Run:
-
-```bash
-npm run type-check
-npm run test
-npm run storybook
-```
-
-Smoke Storybook `/Date` manually.
-
-- [ ] **Commit:** `docs: document Date picker breaking API change`
-
----
-
-## Spec coverage checklist (plan self-review)
-
-| Spec section | Task |
-|--------------|------|
-| Staged OK / Cancel | Task 4, 5, 6 |
-| Outside dismiss = Cancel | Task 6 (`useDismiss` + cancel) |
-| min/max/disabled weekdays/dates | Task 2, wired in Tasks 5–7 |
-| Popover 280px + flip/shift | Task 6 |
-| Mobile sheet + scroll lock | Task 6–8 |
-| Hidden `YYYY-MM-DD` | Task 7 |
-| `date-fns` granular imports | Tasks 1–3, 7 |
-| ARIA grid + Tab trap | Task 5 (Tab cycle within dialog: implement `onKeyDown` at panel root capturing Tab) |
-| `isDisabled` naming | Task 7 |
-| TDD order | Tasks 1–5 |
-
----
-
-## Execution handoff
-
-**Plan complete** and saved to `docs/superpowers/plans/2026-05-10-date-picker.md`.
-
-Two execution options:
-
-1. **Subagent-Driven (recommended)** — fresh subagent per task; review between tasks (`superpowers:subagent-driven-development`).
-2. **Inline execution** — run tasks in one session (`superpowers:executing-plans`).
-
-Which approach do you want?

package/docs/superpowers/plans/2026-05-10-select-floating-ui.md

@@ -1,122 +0,0 @@
-# Select rebuild — Frozen requirements & implementation plan
-
-> **Frozen as of:** 2026-05-10  
-> **Process:** Implement one numbered phase per session (or PR slice); pause for Storybook review before starting the next. Work stays on the current feature branch.
-
-**Goal:** Replace `Select` with a Floating UI–based control: desktop portalled dropdown with collision-aware positioning; mobile-first bottom sheet for the panel; parity with your written spec plus the decisions below.
-
-**Tech stack:** React 18, existing SCSS (`FormControls.module.scss`), `@floating-ui/react` (must be a **runtime dependency** for the published package—not only devDependency).
-
-**Architecture (short):** Reference element = composite trigger (`button`/`div` pattern matching a11y plan). Floating panel = `FloatingPortal` → `FloatingFocusManager` for desktop; overlay + sheet panel for narrow viewports sharing the same inner list/search shell where possible.
-
-**Testing gate:** Existing Storybook form-controls **Select** story (expand with variants as phases land).
-
----
-
-## Frozen requirements
-
-### Locked from your original spec
-
-- **Modes:** `mode: 'single' | 'multi'` (multi shows removable chips when selected; overflow `+N` after `triggerMaxItems`).
-- **Data:** Static `Option[]`, or async when `options === null` and `onSearch` is provided.
-- **Options:** Shape as in your doc (`value`, `label`, optional `group`, `icon`, `avatar`, `meta`, `disabled`).
-- **Portal:** Dropdown content renders through a portal (`document.body` or `#root`-safe target if we add optional `portalRoot` prop—**frozen default:** `document.body`).
-- **Clear:** Trigger shows × whenever there is a selection; clears all and closes panel.
-- **Search:** Debounced `searchDebounce` (async); search row at top of panel (clear control on search input when non-empty)—matches your inspirations.
-- **Panel (multi):** Select all row with checked / unchecked / **indeterminate** when some visible options are selected; respects disabled options and `maxSelect`.
-- **`maxSelect`:** Enforced in multi only; capped state is visibly disabled before tap; single mode **no-op** (frozen).
-- **Keyboard (desktop dropdown):** ↓ / ↑ move active option; Enter toggles selection; Escape closes and returns focus to trigger; Tab closes (match spec table).
-- **States:** Idle, open (+ search focus behavior per phase notes), loading, error, empty, disabled.
-- **Forms:** Preserve hidden/native submission story where applicable (`name` prop); extend as needed for multi value encoding.
-
-### Former “open items” — now decided
-
-| Item | Decision |
-|------|----------|
-| `maxSelect` in single mode | **No-op** (ignored). |
-| Bottom sheet animation | **CSS-only:** translateY from 100% → 0, **240ms**, `cubic-bezier(0.22, 1, 0.36, 1)`; backdrop fades **160ms**. (Tunable in SCSS only.) |
-| Flip / collision (desktop) | **Yes:** `flip` + `shift` + **`size`** so max height clamps to viewport; scroll inside list. |
-| Error retry | **Manual “Retry”** only after failure (invokes same `onSearch` with last query). No automatic retry loops. |
-| Uncontrolled mode | **Out of scope for v1.** API is controlled: `value` + `onChange`. (Optional `defaultValue` is a future enhancement, not part of this rebuild.) |
-
-### Visual / UX defaults (aligned to your screenshots)
-
-- Multi trigger: chips with per-chip dismiss; comma-joined label text is replaced by chips + overflow.
-- Single trigger: plain text label of selected option (no chip), or placeholder.
-- Checkbox-style row affordance for multi list; highlight row on hover/focus-visible.
-- Icons: **`icon`** uses **Material Symbols names** like the rest of CleanPlate **`Icon`** (your doc said Tabler—**frozen correction:** match existing **`Icon`** / `cleanplate` pattern in this repo, unless you revert this in review).
-
----
-
-## Dependencies
-
-- Move **`@floating-ui/react`** from `devDependencies` to **`dependencies`** in `package.json` before shipping the component (can land in Phase 1 PR).
-
----
-
-## Implementation phases (one todo each — review after)
-
-### Phase 1 — Floating UI desktop shell
-
-- Portal + `useFloating` with `flip`, `shift`, `offset`, `size`, `whileElementsMounted` / `autoUpdate`.
-- Replace in-flow dropdown positioning; dismiss on outside press and Escape (`useDismiss`).
-- **Scope limit:** Static options, existing simple single + multi behaviour, no chips yet beyond current approximation if multi still uses text summary briefly.
-- Storybook: Select still runnable; note known gaps.
-
-### Phase 2 — API & types freeze
-
-- Export `Option` type; deprecate or alias `SelectOption` → `Option` for compat.
-- Add `mode` prop; **`isMulti` maps to `mode`** for one release or deprecate `isMulti` with console warning once (pick minimal churn—frozen approach: **`mode` canonical**, keep `isMulti` as undocumented alias forwarding to `mode` OR remove if you prefer breaking change—default **canonical `mode`** + **`isMulti` deprecated** shim).
-- Storybook controls updated.
-
-### Phase 3 — Multi trigger chips + overflow
-
-- Render first `triggerMaxItems` selections as removable chips; `+N` for remainder.
-- Clear (×) and chevron behaviours per spec.
-
-### Phase 4 — Search (sync + async wiring)
-
-- Search field in panel; **sync:** filters `options` locally, no debounce on static path (debounce still applies only to `onSearch` path per your table).
-- **Async:** when `options === null`, debounced `onSearch(q)`.
-
-### Phase 5 — Async states
-
-- Loading / error / empty UI in list slot; Retry on error only.
-
-### Phase 6 — Groups + rich options
-
-- `groups` sections; icons/avatars/meta; disabled options skipped in keyboard nav and not selectable.
-
-### Phase 7 — Panel bulk actions & `maxSelect`
-
-- Select all / clear all in panel (multi); indeterminate logic for “visible” selectable set respect `disabled` rows.
-- Cap styling and blocked clicks.
-
-### Phase 8 — Keyboard completion
-
-- Arrow navigation through options; Enter to toggle/select; Tab/Escape per frozen table; roving tabindex or Floating UI list patterns.
-
-### Phase 9 — Mobile bottom sheet
-
-- Breakpoint: **`max-width: 768px`** (match common `md` boundary; overrides if you expose `breakpoints` prop later—**frozen: internal constant** first).
-- Sheet uses focus trap compatible with Floating UI dismissal; reuse inner list markup.
-
-### Phase 10 — A11y + Storybook showcases
-
-- `aria-expanded`, `aria-controls`, listbox/combobox roles consistent across modes.
-- Hidden input / form submission validated for multi.
-- Stories: static single/multi, async, groups, chips overflow, maxSelect, error, empty, sheet (viewport toggle).
-
----
-
-## Review checkpoint protocol
-
-After each phase: run **Storybook** (`npm run storybook`), exercise **Select** story (and phase-specific knobs), confirm no regressions in **All controls showcase**, then approve next phase.
-
----
-
-## Out of scope (explicit)
-
-- List virtualization (`react-window`, etc.).
-- Uncontrolled/defaultValue API.
-- Auto-retry on fetch errors.

package/docs/superpowers/specs/2026-05-10-date-picker-design.md

@@ -1,196 +0,0 @@
-# Date picker (`Date` form control) — design spec
-
-**Status:** Approved (chat sign-off 2026-05-10)  
-**Scope:** Replace existing three-`Select` `Date` field with calendar date picker per product requirements.  
-**Stack:** React 18+, `date-fns` (granular imports), `@floating-ui/react` (already in package).
-
----
-
-## 1. Summary
-
-The public **`Date`** export from form controls becomes a **calendar-based date picker**: read-only trigger field, floating **popover** on desktop and **bottom sheet** on mobile (same breakpoint and shell pattern as `Select.tsx`), **Cancel / OK** staged commit, full constraint props, and accessibility per the requirements document. This is a **breaking API** change from the previous day/month/year string model.
-
----
-
-## 2. Goals and non-goals
-
-**In scope** (aligned with `datepicker-requirements.md` and wireframe):
-
-- Single date selection; **staging** in the panel; **OK** commits (fires `onChange`, updates display); **Cancel** / Escape / outside dismiss / overlay tap **revert** to last committed value only.
-- Month grid (7 columns, configurable `weekStartsOn`); **today** distinct from **selected**; **outside-month** cells visible, dimmed; click outside-month **navigates** to that month and **stages** that date.
-- Month and year **chevrons** plus **dropdown** subviews; navigation **clamped** by `minDate` / `maxDate`.
-- Constraints: `minDate`, `maxDate`, `disabledDates`, `disabledDaysOfWeek`.
-- Locale via `date-fns` `Locale` and `weekStartsOn`.
-- Keyboard and ARIA (`grid` / `gridcell`, `aria-selected`, `aria-disabled`, trigger `aria-expanded` / `aria-controls`, focus restoration on close).
-- Responsive: desktop popover (**280px** width, flip/shift, 8px viewport padding); mobile sheet (rounded top corners, dim overlay, no swipe-dismiss), body scroll lock while open.
-
-**Explicitly out of scope** for this component (unchanged from requirements):
-
-- Range / dual calendar, time picker, typed free-form parsing, timezone UI, gestures, inline-only calendar embedding.
-
----
-
-## 3. Breaking changes
-
-Previous behaviour:
-
-- Three `Select` fields; `onChange` emitted **`dd-mm-yyyy`** string; `defaultValue` used `"--"` split pattern.
-
-New behaviour:
-
-- `value` / `defaultValue`: **`Date | null`** (calendar date in **local** timezone; comparisons use **local calendar midnight** consistently — document in implementation and JSDoc).
-- `onChange`: **`(date: Date | null) => void`**.
-- Clearing via trigger **commits `null` immediately** (closes panel if open).
-
-**Migration:** Consumers must replace string state with `Date` (or derive strings at form submit). Optionally use hidden `name` field (see below) for native forms.
-
----
-
-## 4. Architecture (Approach 2)
-
-**Facade + module folder** — keeps a single public **`Date`** / **`DateProps`** while splitting implementation for testability and maintainability.
-
-| Area | Responsibility |
-|------|----------------|
-| `form-controls/Date.tsx` | Public API, field chrome (label, error, `isFluid`, `dataTestId`, ids), wires shell + panel. |
-| `form-controls/date/calendar-matrix.ts` | Builds visible calendar cells / weeks using `date-fns` granular imports only. |
-| `form-controls/date/date-constraints.ts` | `isDisabled`, nav bounds, weekday / blackout rules vs `min`/`max`. |
-| `form-controls/date/use-date-picker-state.ts` | `open`, committed vs staged value, view mode (`calendar` \| `month` \| `year`), actions. |
-| `form-controls/date/DatePickerPanel.tsx` | Header, grid, footer **Cancel** / **OK**. |
-| `form-controls/date/MonthDropdownView.tsx` | Scrollable month list; clamp to allowed months. |
-| `form-controls/date/YearDropdownView.tsx` | Scrollable year list; clamp to allowed years. |
-
-Optional later extractions if files grow: shared **`ScrollPickerList`**; shared **responsive shell** hook extracted from duplication with `Select` (only if duplication hurts — not required in first PR).
-
----
-
-## 5. Tree-shaking notes
-
-- **Runtime:** Always import **`date-fns`** as **named submodule imports** (e.g. `import { format } from 'date-fns/format'` or equivalent tree-shake-friendly entry — follow project ESLint / bundler conventions).
-- **Package layout:** The published library currently uses a **single Rollup entry** (`src/index.js`) that imports `FormControls`; consumers importing the main entry may still include form controls as a group. **True** “only pay for Date” at app level may require a **future** `package.json` **`exports`** subpath (out of scope for this design unless explicitly added in the same effort). This spec still requires **no unnecessary eager imports** inside the date module.
-
----
-
-## 6. Responsive shell (mirror `Select`)
-
-- **Breakpoint:** `(max-width: 768px)` matches `Select.tsx` (`SELECT_MOBILE_SHEET_MEDIA`).
-- **Desktop:** `FloatingPortal` + `useFloating` with `offset`, `flip`, `shift`; popover **width 280px** (not input width); `placement` overridable via prop (default `bottom-start`); `autoUpdate` while open.
-- **Mobile:** Fixed bottom sheet, dim backdrop, `translateY` enter/exit, `transitionend` + timeout fallback, **`document.body.style.overflow = 'hidden'`** while open (same rationale as Select).
-- **Dismiss:** Outside press / overlay tap behave as **Cancel** (discard staged).
-
-SCSS timings and z-index should **reuse or align with** `--cp-select-*` tokens / class patterns in `FormControls.module.scss` to avoid visual regressions and drift.
-
----
-
-## 7. Behaviour details
-
-- **Opening:** Copies **committed → staged**. If no committed value, stage **today** clamped into allowed range, or first allowed day of **`displayedMonth`** if today invalid (implementation picks one deterministic rule — prefer **clamp today**, else **first enabled day of month** visible).
-- **OK:** Applies staged → committed; `onChange(committed)`; close; restore focus per a11y section.
-- **Cancel / Escape / outside dismiss:** Discard staged; close; no `onChange` unless clearing was instantaneous (clear is separate).
-- **Clear:** **Instant** commit `null`, `onChange(null)`, close if open.
-- **Disabled:** No open when `isDisabled`; nav controls and dropdown options respect disabled state for out-of-range or invalid targets.
-- **Hidden input:** If `name` is provided, render `<input type="hidden" name={name}>` with value **`YYYY-MM-DD`** when committed value exists, otherwise empty string.
-
----
-
-## 8. Accessibility
-
-- Trigger: **`aria-expanded`**, **`aria-controls`** referencing panel id; labelled via `label` + `id` pattern consistent with form controls.
-- Mobile sheet container: **`role="dialog"`**, **`aria-modal="true"`**; desktop popover remains focusable-managed surface (exact `role` may be `dialog` or documented pattern consistent with axe rules — implementation verifies with axe in Storybook or CI when available).
-- Grid: **`role="grid"`**, cells **`role="gridcell"`**; **`aria-selected`** on selection; **`tabIndex={-1}`** vs roving tabindex strategy as implemented; **disabled** cells **`aria-disabled="true"`** and not in tab order.
-- **Today** vs **selected**: not color-only (e.g. subtle ring or textual “today” available to SR via `aria-label` on cell).
-- **Focus:** On open, move focus into panel; on close return focus to trigger. **Tab** cycles within the picker while open (**lightweight in-house Tab loop** first; introduce `focus-trap-react` only if manual handling fails review or tests).
-
-Keyboard behaviour matches requirements doc:
-
-| Key | Behaviour |
-|-----|-----------|
-| Tab / Shift+Tab | Cycle within open picker (within surface only while open). |
-| Enter / Space on trigger | Open picker. |
-| Arrows | Move between enabled days / within grid semantics. |
-| Enter / Space on day | Stage date. |
-| Page Up / Down | Previous / next month. |
-| Home / End | First / last day of **currently displayed** month (enabled handling if some days disabled). |
-| Escape | Cancel and close |
-
----
-
-## 9. Props (public API)
-
-Compatible with refined requirements (`datepicker-requirements.md`) with naming aligned to existing form controls where useful:
-
-| Prop | Type | Notes |
-|------|------|--------|
-| `value` | `Date \| null` | Controlled. |
-| `defaultValue` | `Date \| null` | Uncontrolled initial. |
-| `onChange` | `(date: Date \| null) => void` | Fires on **OK** or **instant clear**. |
-| `placeholder` | `string` | Default `Select date`. |
-| `dateFormat` | `string` | Default `MMM dd, yyyy`; use `date-fns` `format`. |
-| `id`, `name` | `string` | `name` enables hidden ISO field. |
-| `minDate`, `maxDate` | `Date` | Inclusive bounds on calendar dates. |
-| `disabledDates` | `Date[]` | Normalized to date-only compare. |
-| `disabledDaysOfWeek` | `number[]` | `0` Sun … `6` Sat. |
-| `locale` | `Locale` | `date-fns` locale. |
-| `weekStartsOn` | `0 \| … \| 6` | Default `0`. |
-| `clearable` | `boolean` | Default `true`. |
-| `disabled` | `boolean` | Align prop name with other controls (`isDisabled` deprecated alias optional — **YAGNI**: use `disabled` only if we standardize; else keep `isDisabled` for consistency with `Select` — **decision: keep `isDisabled`** to match existing `Date.tsx` and `Select.tsx` until a global rename). |
-| `readOnly` | `boolean` | Per requirements. |
-| `label`, `error` | `string` | Match existing field patterns. |
-| `isFluid`, `dataTestId`, `isRequired` | | Preserve from current `Date`. |
-| `popoverPlacement` | `Placement` | `@floating-ui/react`. |
-| `onOpen`, `onClose` | `() => void` | |
-
-**Note:** Requirements used `disabled`; existing components use **`isDisabled`**. This spec **standardizes on `isDisabled`** for continuity with `Select` / prior `Date` until a library-wide rename.
-
----
-
-## 10. Testing (TDD)
-
-**Tooling:** Add **Vitest**, **@testing-library/react**, **jsdom** (+ any minimal config for TSX path aliases).
-
-**Order:**
-
-1. **Unit:** `calendar-matrix.ts`, `date-constraints.ts` — edge cases (leap years, DST boundaries treated as local date-only, boundary min/max months, weekdays).
-2. **Hook / state:** `use-date-picker-state` — open/close, commit/cancel, month/year navigation clamps, staged vs committed.
-3. **RTL:** OK vs Cancel vs outside-click vs Escape; disabled day interaction; clear button commits `null`; optional snapshot of header rendering.
-
-Stories (Storybook): desktop vs mobile layouts, constrained DOB scenario, weekday blackout — scheduled after core tests pass.
-
----
-
-## 11. Dependencies
-
-| Package | Role |
-|---------|------|
-| `date-fns` | **New** dependency — formatting, arithmetic, locale. |
-| `@floating-ui/react` | Existing — positioning. |
-
-No headless UI library.
-
----
-
-## 12. Files to touch (implementation preview)
-
-- Replace `src/components/form-controls/Date.tsx`.
-- Add `src/components/form-controls/date/*` as above.
-- Extend `FormControls.module.scss` for date picker (tokens aligned with select sheet/dropdown).
-- `package.json` — add `date-fns`, test deps, `test` script.
-- Storybook stories under existing form-controls stories pattern.
-- **Changelog / migration note** for breaking `Date` API (where the project publishes changes).
-
----
-
-## 13. Self-review checklist (pre-implementation)
-
-- [x] No unresolved “TBD” in behaviour: focus strategy starts in-house Tab loop; clamp rule for empty-open documented in §7.
-- [x] `isDisabled` vs `disabled` contradiction resolved (**use `isDisabled`**).
-- [x] Timezone stance: **local calendar date only** for v1.
-- [x] Scope fits one implementation plan with optional follow-up for `package.json` exports.
-
----
-
-## 14. References
-
-- Product requirements (authoritative checklist): companion doc `datepicker-requirements.md` (user-provided).
-- Visual: wireframe `assets/Screenshot_2026-05-10_at_3.54.33_PM-29e15a23-18c8-40cb-a7e3-2941980c2d4a.png`.
-- Behavioural reference: `src/components/form-controls/Select.tsx` (responsive shell).