From b0eb52f79244da889e0ca697a4ad8ab594a54fd7 Mon Sep 17 00:00:00 2001
From: Jesse_Chen <chen.yue@mevixaga.com>
Date: Fri, 17 Jul 2026 20:58:13 +0800
Subject: [PATCH] docs: plan birth date picker

---
 .../plans/2026-07-17-birth-date-picker.md     | 439 ++++++++++++++++++
 1 file changed, 439 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-17-birth-date-picker.md

diff --git a/docs/superpowers/plans/2026-07-17-birth-date-picker.md b/docs/superpowers/plans/2026-07-17-birth-date-picker.md
new file mode 100644
index 00000000..ddee222a
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-17-birth-date-picker.md
@@ -0,0 +1,439 @@
+# Birth Date Picker 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 browser-native birth-date input with the user-supplied shadcn Popover + Calendar Date Picker while preserving the existing `YYYY-MM-DD` profile contract.
+
+**Architecture:** Add the official shadcn Base Nova `Calendar` and `Popover` primitives, then compose them in a focused `BirthDatePicker` client component. Keep local-calendar parsing and serialization beside the existing birth-time draft model so every consumer receives the same date-only string without UTC shifts.
+
+**Tech Stack:** Next.js 16, React 19, TypeScript, shadcn Base Nova, Base UI, React DayPicker, date-fns, Lucide, Node test runner.
+
+## Global Constraints
+
+- The closed control follows the exact shadcn composition supplied by the user: `PopoverTrigger render={<Button />}` plus `PopoverContent` containing a single-select `Calendar`.
+- Date values remain `YYYY-MM-DD`; the API payload and database schema do not change.
+- The selectable range is `1900-01-01` through the user's current local date; future dates are disabled.
+- The calendar uses Chinese locale with month and year dropdowns, newest years first.
+- Confirmed birth-time profiles keep the date trigger disabled.
+- Use only existing `frontend/DESIGN.md` tokens and shadcn semantic tokens; add no raw colors.
+- Preserve 44px targets, keyboard operation, focus visibility, and collision-safe popover positioning.
+
+---
+
+### Task 1: Date-only value adapter
+
+**Files:**
+- Modify: `frontend/package.json`
+- Modify: `frontend/package-lock.json`
+- Modify: `frontend/src/lib/birth-time-intake-model.ts`
+- Test: `frontend/tests/birth-time-intake.test.ts`
+
+**Interfaces:**
+- Produces: `parseBirthDate(value: string): Date | undefined`
+- Produces: `formatBirthDate(value: Date): string`
+- Consumes: date-fns `parse`, `format`, and `isValid`
+
+- [ ] **Step 1: Add failing date-only behavior tests**
+
+Extend the existing import and append these Given/When/Then tests:
+
+```ts
+import {
+  assistantIntentCopy,
+  birthTimePersistenceValues,
+  describeBirthTimeDraft,
+  formatBirthDate,
+  isBirthTimeDraftReady,
+  parseBirthDate,
+  type BirthTimeDraft,
+} from "../src/lib/birth-time-intake-model.ts";
+
+test("birth date parsing preserves the local calendar day", () => {
+  const parsed = parseBirthDate("1993-04-17");
+
+  assert.equal(parsed?.getFullYear(), 1993);
+  assert.equal(parsed?.getMonth(), 3);
+  assert.equal(parsed?.getDate(), 17);
+});
+
+test("birth date values round trip leap days and reject invalid input", () => {
+  const leapDay = parseBirthDate("2000-02-29");
+
+  assert.equal(leapDay === undefined ? undefined : formatBirthDate(leapDay), "2000-02-29");
+  assert.equal(parseBirthDate(""), undefined);
+  assert.equal(parseBirthDate("2001-02-29"), undefined);
+});
+```
+
+- [ ] **Step 2: Run the tests in a negative UTC offset and confirm red**
+
+Run:
+
+```bash
+TZ=America/Los_Angeles node --test tests/birth-time-intake.test.ts
+```
+
+Expected: FAIL because `parseBirthDate` and `formatBirthDate` are not exported yet.
+
+- [ ] **Step 3: Install date-fns as a direct dependency**
+
+Run:
+
+```bash
+npm install date-fns
+```
+
+Expected: `package.json` and `package-lock.json` declare `date-fns` directly.
+
+- [ ] **Step 4: Implement strict local-calendar parsing and formatting**
+
+Add to `birth-time-intake-model.ts`:
+
+```ts
+import { format, isValid, parse } from "date-fns";
+
+const birthDatePattern = "yyyy-MM-dd";
+
+export function parseBirthDate(value: string): Date | undefined {
+  if (value === "") return undefined;
+  const parsed = parse(value, birthDatePattern, new Date(2000, 0, 1));
+  if (!isValid(parsed) || format(parsed, birthDatePattern) !== value) return undefined;
+  return parsed;
+}
+
+export function formatBirthDate(value: Date): string {
+  return format(value, birthDatePattern);
+}
+```
+
+- [ ] **Step 5: Run the adapter tests and confirm green**
+
+Run:
+
+```bash
+TZ=America/Los_Angeles node --test tests/birth-time-intake.test.ts
+```
+
+Expected: all birth-time intake tests PASS.
+
+- [ ] **Step 6: Commit the adapter**
+
+```bash
+git add frontend/package.json frontend/package-lock.json frontend/src/lib/birth-time-intake-model.ts frontend/tests/birth-time-intake.test.ts
+git commit -m "feat: add birth date value adapter"
+```
+
+---
+
+### Task 2: shadcn Calendar and Popover primitives
+
+**Files:**
+- Create: `frontend/src/components/ui/calendar.tsx`
+- Create: `frontend/src/components/ui/popover.tsx`
+- Create: `frontend/tests/birth-date-picker-contract.test.ts`
+- Modify: `frontend/package.json`
+- Modify: `frontend/package-lock.json`
+
+**Interfaces:**
+- Produces: `Calendar(props: React.ComponentProps<typeof DayPicker>)`
+- Produces: `Popover`, `PopoverTrigger`, and `PopoverContent`
+- Consumes: the existing `Button`, `buttonVariants`, `cn`, Lucide icons, and shadcn semantic CSS variables.
+
+- [ ] **Step 1: Write the failing primitive contract test**
+
+Create `tests/birth-date-picker-contract.test.ts`:
+
+```ts
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import test from "node:test";
+
+const packageJson = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+
+test("provides the shadcn calendar and popover primitives", () => {
+  assert.equal(existsSync(new URL("../src/components/ui/calendar.tsx", import.meta.url)), true);
+  assert.equal(existsSync(new URL("../src/components/ui/popover.tsx", import.meta.url)), true);
+  assert.match(packageJson, /"react-day-picker"/);
+});
+```
+
+- [ ] **Step 2: Run the primitive contract and confirm red**
+
+Run:
+
+```bash
+node --test tests/birth-date-picker-contract.test.ts
+```
+
+Expected: FAIL because the primitive files and direct dependency do not exist.
+
+- [ ] **Step 3: Add the official Base Nova primitives**
+
+Run from `frontend/`:
+
+```bash
+npx shadcn@latest add calendar popover --yes
+```
+
+Expected: shadcn reads the existing `components.json`, creates `src/components/ui/calendar.tsx` and `src/components/ui/popover.tsx`, reuses the existing `button.tsx`, and adds `react-day-picker` plus required direct dependencies without changing the project style preset.
+
+- [ ] **Step 4: Review generated changes before accepting them**
+
+Run:
+
+```bash
+git diff -- frontend/package.json frontend/package-lock.json frontend/src/components/ui/button.tsx frontend/src/components/ui/calendar.tsx frontend/src/components/ui/popover.tsx
+```
+
+Expected: no overwrite of the project's existing Button behavior; generated Calendar uses `react-day-picker`, and Popover uses the Base UI composition required by `style: base-nova`.
+
+- [ ] **Step 5: Run the primitive contract and TypeScript**
+
+Run:
+
+```bash
+node --test tests/birth-date-picker-contract.test.ts
+npx tsc --noEmit
+```
+
+Expected: both commands PASS.
+
+- [ ] **Step 6: Commit the primitives**
+
+```bash
+git add frontend/package.json frontend/package-lock.json frontend/src/components/ui/calendar.tsx frontend/src/components/ui/popover.tsx frontend/tests/birth-date-picker-contract.test.ts
+git commit -m "feat: add shadcn calendar primitives"
+```
+
+---
+
+### Task 3: BirthDatePicker composition and intake integration
+
+**Files:**
+- Create: `frontend/src/components/birth-date-picker.tsx`
+- Modify: `frontend/src/components/birth-time-intake.tsx`
+- Modify: `frontend/DESIGN.md`
+- Test: `frontend/tests/birth-date-picker-contract.test.ts`
+
+**Interfaces:**
+- Consumes: `parseBirthDate(value: string)` and `formatBirthDate(value: Date)` from Task 1.
+- Consumes: `Calendar`, `Popover`, `PopoverContent`, `PopoverTrigger`, `Button`, `CalendarIcon`, and `zhCN`.
+- Produces: `BirthDatePicker({ value, disabled, onChange })` where `value` is `YYYY-MM-DD` and `onChange` receives `YYYY-MM-DD`.
+
+- [ ] **Step 1: Document the Date Picker primitive before product code**
+
+Extend `frontend/DESIGN.md` Section 5 with:
+
+```md
+### Birth date picker
+
+- **Composition:** shadcn outline Button trigger, Base UI Popover, and a single-select React DayPicker Calendar.
+- **Range:** local dates from 1900-01-01 through today; future dates are disabled. Month and year dropdowns provide direct navigation, with newest years first.
+- **Value:** display Chinese long dates while emitting the existing `YYYY-MM-DD` profile value without UTC conversion.
+- **States:** empty, open, selected, focus-visible, disabled confirmed profile, and unavailable date.
+- **Accessibility:** visible label, explicit trigger naming, 44px targets, keyboard calendar navigation, focus return, and collision-safe popup positioning.
+```
+
+- [ ] **Step 2: Add a failing integration contract**
+
+Append to `birth-date-picker-contract.test.ts`:
+
+```ts
+const intake = readFileSync(new URL("../src/components/birth-time-intake.tsx", import.meta.url), "utf8");
+const pickerUrl = new URL("../src/components/birth-date-picker.tsx", import.meta.url);
+
+test("replaces the native birth date input with the shadcn date picker", () => {
+  assert.equal(existsSync(pickerUrl), true);
+  assert.doesNotMatch(intake, /type="date"/);
+  assert.match(intake, /<BirthDatePicker/);
+  const picker = readFileSync(pickerUrl, "utf8");
+  assert.match(picker, /<PopoverTrigger/);
+  assert.match(picker, /render=\{<Button/);
+  assert.match(picker, /<Calendar/);
+  assert.match(picker, /captionLayout="dropdown"/);
+  assert.match(picker, /startMonth=\{new Date\(1900, 0\)\}/);
+  assert.match(picker, /reverseYears/);
+});
+```
+
+- [ ] **Step 3: Run the integration contract and confirm red**
+
+Run:
+
+```bash
+node --test tests/birth-date-picker-contract.test.ts
+```
+
+Expected: FAIL because `BirthDatePicker` is absent and the native date input remains.
+
+- [ ] **Step 4: Implement the focused picker component**
+
+Create `src/components/birth-date-picker.tsx` with this composition:
+
+```tsx
+"use client";
+
+import { format } from "date-fns";
+import { zhCN } from "date-fns/locale";
+import { CalendarIcon } from "lucide-react";
+import { useId, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import { Calendar } from "@/components/ui/calendar";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { formatBirthDate, parseBirthDate } from "@/lib/birth-time-intake-model";
+
+type BirthDatePickerProps = {
+  readonly value: string;
+  readonly disabled: boolean;
+  readonly onChange: (value: string) => void;
+};
+
+export function BirthDatePicker({ value, disabled, onChange }: BirthDatePickerProps) {
+  const labelId = useId();
+  const valueId = useId();
+  const [open, setOpen] = useState(false);
+  const selected = parseBirthDate(value);
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+
+  return (
+    <div className="grid gap-2">
+      <span id={labelId}>出生日期</span>
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger
+          render={
+            <Button
+              type="button"
+              variant="outline"
+              disabled={disabled}
+              aria-labelledby={`${labelId} ${valueId}`}
+              data-empty={selected === undefined}
+              className="w-full justify-start px-3 text-left font-normal data-[empty=true]:text-muted-foreground"
+            />
+          }
+        >
+          <CalendarIcon aria-hidden="true" />
+          <span id={valueId}>
+            {selected === undefined
+              ? "选择出生日期"
+              : format(selected, "PPP", { locale: zhCN })}
+          </span>
+        </PopoverTrigger>
+        <PopoverContent align="start" className="w-auto p-0">
+          <Calendar
+            key={value || "empty"}
+            mode="single"
+            className="[--cell-size:2.75rem]"
+            locale={zhCN}
+            selected={selected}
+            defaultMonth={selected ?? today}
+            captionLayout="dropdown"
+            navLayout="after"
+            startMonth={new Date(1900, 0)}
+            endMonth={today}
+            reverseYears
+            disabled={{ before: new Date(1900, 0, 1), after: today }}
+            onSelect={(nextDate) => {
+              if (nextDate === undefined) return;
+              onChange(formatBirthDate(nextDate));
+              setOpen(false);
+            }}
+          />
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 5: Replace the native input without changing the patch contract**
+
+In `birth-time-intake.tsx`, import `BirthDatePicker` and replace the first `<label>...</label>` block with:
+
+```tsx
+<BirthDatePicker
+  value={value.date}
+  disabled={isConfirmed}
+  onChange={(date) => onPatch({ date })}
+/>
+```
+
+- [ ] **Step 6: Run targeted contracts and TypeScript**
+
+Run:
+
+```bash
+node --test tests/birth-date-picker-contract.test.ts tests/birth-time-intake.test.ts
+npx tsc --noEmit
+```
+
+Expected: all tests and TypeScript PASS.
+
+- [ ] **Step 7: Commit the composition**
+
+```bash
+git add frontend/DESIGN.md frontend/src/components/birth-date-picker.tsx frontend/src/components/birth-time-intake.tsx frontend/tests/birth-date-picker-contract.test.ts
+git commit -m "feat: replace native birth date input"
+```
+
+---
+
+### Task 4: Real-surface QA and release gates
+
+**Files:**
+- Modify only if QA finds a defect in the files owned by Tasks 1–3.
+
+**Interfaces:**
+- Consumes: the complete BirthDatePicker flow.
+- Produces: browser evidence for selection, dismissal, range constraints, disabled state, and responsive layout.
+
+- [ ] **Step 1: Run the full automated gates**
+
+```bash
+npm test
+npm run lint
+npm run build
+```
+
+Expected: 100% test pass, zero lint errors, and a successful production build.
+
+- [ ] **Step 2: Measure every modified TypeScript file**
+
+```bash
+for file in src/lib/birth-time-intake-model.ts src/components/ui/calendar.tsx src/components/ui/popover.tsx src/components/birth-date-picker.tsx src/components/birth-time-intake.tsx tests/birth-date-picker-contract.test.ts tests/birth-time-intake.test.ts; do
+  awk '!/^[[:space:]]*$/ && !/^[[:space:]]*(\/\/|#|--)/' "$file" | wc -l
+done
+```
+
+Expected: each file is at or below 250 pure lines; no type escape hatch, parameter bloat, negative flag name, or unrelated helper is introduced.
+
+- [ ] **Step 3: Verify the real interaction at 375px, 768px, and 1280px**
+
+At each width, use the in-app browser to:
+
+1. Open the birth date picker and confirm the popup stays inside the viewport.
+2. Confirm Chinese month/year dropdowns and keyboard focus are visible.
+3. Navigate to 1993, select April 17, and confirm the trigger displays `1993年4月17日`.
+4. Confirm the popover closes and the controlled draft contains `1993-04-17`.
+5. Reopen and confirm April 1993 remains selected.
+6. Confirm dates after today and before 1900 are unavailable.
+7. Load a confirmed profile and confirm the trigger cannot open.
+8. Confirm no browser-native date chooser appears.
+
+Expected: every scenario passes with 44px targets, no clipping, no horizontal overflow, and no console errors.
+
+- [ ] **Step 4: Run the visual QA dual-oracle gate**
+
+Provide fresh 375px, 768px, and 1280px evidence to two independent read-only reviewers. One reviews design-system fidelity and visual polish; the other reviews interaction, accessibility, and regression risk.
+
+Expected: both reviewers return PASS. Fix any concrete issue and repeat only the affected evidence.
+
+- [ ] **Step 5: Final diff hygiene**
+
+```bash
+git diff --check
+git status --short
+```
+
+Expected: no whitespace errors; unrelated pre-existing user changes remain untouched and are named in the handoff.