# Timeline Batch Add — Design **Date:** 2026-05-13 **Status:** Draft, awaiting user review **Scope:** `adiuvAI/` submodule only ## Problem Adding timeline events today goes through `AddEventDialog.tsx` one event at a time. The dialog already supports a sequential "add then add another" loop, but: - Each event commits immediately on Enter (no client-side staging). - The project picker appears at the bottom, after type/title/date. - Date entry requires opening a calendar popover — keyboard-hostile. - A user planning a project (kickoff + milestones + activities) clicks through the dialog 5–10 times to seed a project's timeline. ## Goal Single dialog session lets the user pick a project, stage multiple timeline events of mixed types, review, and commit the batch. Fully operable without a mouse. ## Non-goals - New backend endpoint. Re-use `trpc.timelineEvents.create` per event. - Reordering staged events. Order is "as added". - Bulk import (CSV/paste). Out of scope. - Cross-project batch. One batch = one project. ## Architecture Refactor `adiuvAI/src/renderer/components/timeline/AddEventDialog.tsx` in place. Same callsites (`routes/timeline.tsx`, `components/projects/ProjectDetail.tsx`), same props (`open`, `onOpenChange`, `defaultProjectId?`, `onRecordHistory?`). Two new shared primitives extracted from this work: - `adiuvAI/src/renderer/lib/parseDate.ts` — pure date parser, locale-aware. - `adiuvAI/src/renderer/components/ui/date-field.tsx` — controlled date input with typed entry + popover fallback. Existing `EditEventDialog.tsx` migrates to `` as part of this work. `TaskFormDialog.tsx` is **out of scope** — it uses `TZDate` plus time-of-day (H/M) selectors, which DateField does not cover. A follow-up pass should add `timezone` + `showTime` props to DateField, then migrate TaskFormDialog. ## State model ```ts type StagedEvent = { id: string; // nanoid, local-only key title: string; type: 'milestone' | 'checkpoint' | 'activity'; date: Date; endDate?: Date; // activity only }; type Mode = { kind: 'add' } | { kind: 'edit'; id: string }; // In AddEventDialog const [projectId, setProjectId] = useState(defaultProjectId ?? ''); const [staged, setStaged] = useState([]); const [mode, setMode] = useState({ kind: 'add' }); // Form fields: const [title, setTitle] = useState(''); const [type, setType] = useState('milestone'); const [date, setDate] = useState(); const [endDate, setEndDate] = useState(); const [focusedRowId, setFocusedRowId] = useState(null); ``` ## Layout ``` ┌─── Add timeline events ─────────────────┐ │ │ │ Project [ Search project… ▾ ] │ ← hidden when defaultProjectId set │ │ locked when staged.length > 0 │ ┌─ Staged list (scrollable, max ~6) ─┐ │ │ │ ✓ Kickoff milestone 15/03 ✕│ │ │ │ ✓ Phase 1 checkpoint 22/03 ✕│ │ │ └───────────────────────────────────┘ │ │ ───────────────────────────────────── │ │ ( Milestone | Checkpoint | Activity ) │ │ [ Event title… ] │ │ [ Date ] [End date ] │ ← end shown only for activity │ │ │ [Cancel] [Add ↵] [Save N] │ └─────────────────────────────────────────┘ ``` States: 1. **Fresh open** — empty staged list with hint text, form ready, focus on project picker (or title if `defaultProjectId`). 2. **N staged, form ready** — staged list visible, form empty, focus on title. 3. **Row focused** — form dimmed (`opacity-50 pointer-events-none`), staged row has focus ring. 4. **Editing row** — form populated from row, "Add ↵" button reads "Update ↵", row in list highlighted. ## Components ### Shared primitives (new) **`lib/parseDate.ts`** — pure functions, no React. ```ts export function parseDate( input: string, prefs: FormatPrefs, baseDate?: Date, ): Date | null; export function parseDateRange( input: string, prefs: FormatPrefs, baseDate?: Date, ): { from: Date; to?: Date } | null; ``` Accepts: - Keywords: `today`, `tomorrow`, `yesterday` (i18n-aware via current `i18n.language`) - Relative: `+Nd`, `+Nw`, `+Nm`, `-Nd` - Weekday names in current UI language (next occurrence): `mon`/`monday`, `lun`/`lunedì`, etc. - Partial date: `DD/MM` or `MM/DD` (per `prefs.dateFormat`) → current year, year-rollover if past - Full date: `DD/MM/YYYY`, `MM/DD/YYYY`, `YYYY-MM-DD` (per prefs) Returns `null` on unparseable. No date library — small regex + native `Date`. **`components/ui/date-field.tsx`** — controlled input. ```ts type DateFieldProps = { value: Date | undefined; onChange: (d: Date | undefined) => void; placeholder?: string; minDate?: Date; autoFocus?: boolean; invalidMessage?: string; className?: string; 'aria-label'?: string; id?: string; onCommit?: (d: Date) => void; // fired on Enter after valid parse }; ``` Internal: text input + calendar icon button → Popover wrapping shadcn `Calendar`. Reads `useFormatPrefs()` internally. Behavior: - Display formatted value (via `formatDate(prefs)`) when input not focused and value valid. - Show raw user text while focused. - Parse on blur and on Enter — if valid, call `onChange(date)`; if invalid, set `aria-invalid="true"` and red ring. - Alt+↓ opens popover. Calendar selection commits via `onChange` and closes popover. - `Enter` inside input: `e.preventDefault()`, parse, call `onChange(parsed)`, then call optional `onCommit?: (d: Date) => void` prop synchronously with the parsed value. Parent uses `onCommit` to stage without relying on `useState` flush. If invalid, no `onCommit` call, no propagation. ### Internal to AddEventDialog (not exported) **``** — shadcn `Command` inside `Popover`. Typeable filter. Disabled when `staged.length > 0` (visual: muted, tooltip "Project locked after first event"). Hidden when `defaultProjectId` set. **``** — `