# Symmetric date-range picker — design

**Date:** 2026-05-25
**Task:** t-paliad-248 (Gitea m/paliad#79)
**Inventor:** atlas
**Branch:** `mai/atlas/inventor-symmetric-date`
**Status:** READ-ONLY design. Awaiting head's go/no-go before coder shift.

---

## §0 TL;DR

Today paliad has **three independent date-range schemes** scattered across surfaces:

1. **`/agenda`** — future-only chip row [7|14|30|90 Tage], state `rangeDays`.
2. **`/admin/audit-log`** — past-only `<select>` [24h|7d|30d|custom|all] + manual `<input type="date">` pair.
3. **`/projects/:id/chart`** — symmetric `RangePreset` [1y|2y|all|custom] + manual date pair.

…plus a **fourth, unified `TimeHorizon` contract** (`internal/services/filter_spec.go`, mirrored in `frontend/src/client/views/types.ts`) that's used by the filter-bar, Verlauf, Custom Views, and InboxFilterBar — but its "Anpassen" custom-range chip is still stubbed (`filter-bar/axes.ts:105-112`, marked Phase 2, disabled, "coming soon" tooltip).

The fix is **not** "build a fourth scheme." The fix is to **finish the TimeHorizon contract** (add `past_14d`, `next_14d`, `past_all`, `next_all`), build **one reusable `<DateRangePicker>`** that emits a `TimeSpec`, then migrate the three legacy affordances to it.

**Layout (m's brief, locked):**

```
┌──────────────────────────────────────────────────────────────┐
│ [Zeitraum: Nächste 30 Tage ▾]                                │
└──────────────────────────────────────────────────────────────┘
                ↓ click to open
┌──────────────────────────────────────────────────────────────┐
│  Vergangenheit          (ALLE)          Zukunft              │
│  [Ganze Vergangenheit] [⌖ ALLE] [Ganze Zukunft]              │
│  [90 T] [30 T] [14 T] [7 T]   [7 T] [14 T] [30 T] [90 T]     │
│                                                              │
│  ── oder benutzerdefiniert ──                                │
│  Von [____.____.____]  Bis [____.____.____]   [Anwenden]     │
└──────────────────────────────────────────────────────────────┘
```

**Slice plan:**

- **Slice A** — `<DateRangePicker>` component + 4 new horizon constants (`past_14d`, `next_14d`, `past_all`, `next_all`). Wired onto filter-bar `time` axis first (lights up Verlauf + InboxFilterBar + views simultaneously by replacing the stubbed Phase-2 chip).
- **Slice B** — `/agenda` migrates (highest-traffic standalone consumer).
- **Slice C** — `/admin/audit-log` + `/projects/:id/chart` migrate. Each surface picks the preset subset it cares about.
- **Slice D** *(optional, later)* — upckommentar-style two-handle slicer replaces the inline date-pair for the "custom" mode.

**Hard rules honoured:**

- No new top-level table or migration in Slice A — purely additive enum values + Go switch arms.
- No new dependency in Slice A — slicer is deferred (it's a non-trivial port from Svelte to paliad's plain TSX renderer).
- Backward-compatible URL shape — each surface keeps its current short-alias parser (e.g. `?range=30` → `horizon=next_30d`) and additionally accepts the canonical `?horizon=…&from=…&to=…`.

---

## §1 Current state — every date-range affordance

Cataloguing **every** place a paliad user picks a past/future window, with file:line refs.

### 1.1 `/agenda` — future-only chip row

`frontend/src/agenda.tsx:64-67`:

```tsx
<button className="agenda-chip" data-range="7"  >7 Tage</button>
<button className="agenda-chip" data-range="14" >14 Tage</button>
<button className="agenda-chip" data-range="30" >30 Tage</button>
<button className="agenda-chip" data-range="90" >90 Tage</button>
```

State machine `frontend/src/client/agenda.ts:80-104`:

- `state.rangeDays ∈ {7,14,30,90}` (set `VALID_RANGES`). Default `30`.
- URL: `?range=30&types=…&event_type=…`.
- Fetch: `GET /api/agenda?from=<today>&to=<today+rangeDays-1>&types=…`.
- **Future-only by construction** — m's complaint applies precisely here. No "past 7 days" affordance, no "all" affordance.

### 1.2 `/admin/audit-log` — past-only `<select>` + manual date pair

`frontend/src/admin-audit-log.tsx:50-65`:

```tsx
<select id="audit-range">
  <option value="24h">Letzte 24h</option>
  <option value="7d" selected>Letzte 7 Tage</option>
  <option value="30d">Letzte 30 Tage</option>
  <option value="custom">Benutzerdefiniert</option>
  <option value="all">Alles</option>
</select>
<!-- custom toggles a date-pair: -->
<input type="date" id="audit-from" />
<input type="date" id="audit-to" />
```

State machine `frontend/src/client/admin-audit-log.ts:135-174`:

- `rangePresetToFrom(preset)` converts `"24h" | "7d" | "30d"` → `Date`. `"custom"` reads `from`/`to` inputs. `"all"` clears both bounds.
- URL: `?source=…&range=7d&q=…&from=…&to=…&limit=…&before_ts=…&before_id=…` (cursor-paged).
- **Past-only by construction.** No future-projection — this is an audit log, looking forward makes no sense.

### 1.3 `/projects/:id/chart` — symmetric `RangePreset`

`frontend/src/client/views/types.ts:77-79`:

```ts
range_preset?: "1y" | "2y" | "all" | "custom";
range_from?: string;
range_to?: string;
```

UI `frontend/src/projects-chart.tsx:78-82`:

```tsx
<input type="date" id="projects-chart-range-from" />
<input type="date" id="projects-chart-range-to" />
```

State machine `frontend/src/client/projects-chart.ts:73-118`:

- `rangeFromURL()` → `{preset, from?, to?}` with default `"1y"`.
- "1y" = `today-1y..today+1y`, "2y" = `today-2y..today+2y`, "all" derived from loaded events, "custom" = read inputs.
- URL: `?range=1y&from=YYYY-MM-DD&to=YYYY-MM-DD`.
- **Symmetric around today** by construction — this is a chart, not a filter; the user is panning a viewport, not picking a fan.

### 1.4 `views-editor.tsx` (Custom Views config form)

`frontend/src/views-editor.tsx:102-109`:

```tsx
<select id="editor-time-horizon">
  <option value="next_7d">Nächste 7 Tage</option>
  <option value="next_30d">Nächste 30 Tage</option>
  <option value="next_90d">Nächste 90 Tage</option>
  <option value="past_30d">Letzte 30 Tage</option>
  <option value="past_90d">Letzte 90 Tage</option>
  <option value="any">Beliebig</option>
</select>
```

- Mixes past + future, but only 5 horizons exposed (no 14d, no past_7d, no all).
- Persists into `paliad.user_views.filter_spec` (JSON column) as a `TimeSpec`.
- **This is the closest existing affordance to m's symmetric fan**, but rendered as a plain `<select>` and incomplete.

### 1.5 Filter-bar `time` axis (riemann's t-paliad-163 Phase 1)

`frontend/src/client/filter-bar/axes.ts:65-115`:

- Renders a chip cluster: `[next_7d, next_30d, next_90d, past_30d, any]` (default presets, line 77-79).
- **"Anpassen" chip is disabled** with `coming_soon` tooltip (line 108-112). This is the documented Phase 2 substrate.
- Surfaces declaring axis `time` thread their own preset list via `RenderAxisOpts.timePresets` — e.g. Verlauf overrides to `["past_7d","past_30d","past_90d","any"]` (`frontend/src/client/projects-detail.ts:2310`).

Consumers:
- `/projects/:id` Verlauf (`projects-detail.ts:2296` initial state, 2310 preset override).
- `/views` and `/views/:id` (Custom Views runtime).
- `/inbox` (`InboxFilterBar` flow — t-paliad-138/139 derived inbox).

### 1.6 `horizonBounds()` — the materializer

`frontend/src/client/projects-detail.ts:393-406` mirrors the Go-side `computeViewSpecBounds()` (`internal/services/view_service.go:156-187`):

```ts
case "past_7d":  return { from: offset(-7),  to: offset(1) };
case "past_30d": return { from: offset(-30), to: offset(1) };
case "past_90d": return { from: offset(-90), to: offset(1) };
case "next_7d":  return { from: day,         to: offset(7) };
case "next_30d": return { from: day,         to: offset(30) };
case "next_90d": return { from: day,         to: offset(90) };
default:         return {};
```

(Backend equivalent: `internal/services/view_service.go:160-186`.)

### 1.7 Single-date inputs (NOT date-range — listed for completeness)

These are out of scope but mentioned so the audit is exhaustive:

- `verfahrensablauf.tsx:174` — `#trigger-date` (calculator anchor).
- `fristenrechner.tsx:496,504,616` — `#trigger-date`, `#priority-date`, `#event-date` (calculator).
- `admin-rules-edit.tsx:265` — `#preview-trigger-date`.
- `deadlines-detail.tsx:82` — `#deadline-due-edit` (inline-edit).
- `deadlines-new.tsx:116` — `#deadline-due` (form).
- `appointments-new.tsx`, `appointments-detail.tsx` — `start_at`/`end_at`.
- `projects-detail.tsx:181` — `#smart-timeline-milestone-date` (add-milestone modal).
- `components/ProjectFormFields.tsx:134,138` — `#project-filing-date`, `#project-grant-date`.

### 1.8 Summary matrix

| Surface | Direction | Presets | Custom | URL contract | Default |
|---|---|---|---|---|---|
| `/agenda` | Future | 7\|14\|30\|90 | — | `?range=N` | 30d |
| `/admin/audit-log` | Past | 24h\|7d\|30d\|all + custom | date pair | `?range=…&from=…&to=…` | 7d |
| `/projects/:id/chart` | Symmetric ±N | 1y\|2y\|all + custom | date pair | `?range=…&from=…&to=…` | 1y |
| `/views/:id` editor | Past+Future mix | next_7d\|next_30d\|next_90d\|past_30d\|past_90d\|any | — | persisted JSON | next_30d |
| Filter-bar `time` axis | Past+Future mix | next_7d\|next_30d\|next_90d\|past_30d\|any | **stubbed** | persisted + `?…__time_from=` | per surface |
| Verlauf | Past + any | past_7d\|past_30d\|past_90d\|any | **stubbed** | URL | past_30d |
| InboxFilterBar | Mix | filter-bar default | **stubbed** | URL | per surface |

Three of seven surfaces have **incomplete** custom-range affordances. None of the seven exposes the full symmetric fan m wants.

---

## §2 upckommentar slicer pattern

Verified by reading source at `/home/m/dev/web/upc-kommentar/src/lib/`:

- **`DateRangeSlider.svelte`** (component, 448 lines).
- **`date-range-slider-pure.ts`** (pure-math helpers, 487 lines, fully unit-tested).
- **`InboxFilterBar.svelte`** (host).

### 2.1 What it is

A **two-handle range slider** that wraps `svelte-range-slider-pips` (npm: `svelte-range-slider-pips@4`). The slider's rail is the upckommentar floor (`2023-01-01`) to today, and the two handles define `dateFrom` and `dateTo`. Step is **1 day** regardless of zoom.

Public contract (DateRangeSlider.svelte:57-82):

```ts
interface Props {
  minISO: string;                 // axis lower bound, default 2023-01-01
  maxISO: string;                 // axis upper bound, today
  fromISO: string | null;         // current From (null = parked at min)
  toISO: string | null;           // current To   (null = parked at max)
  onChange: (from, to) => void;   // emits on every slider change
  testid?: string;
  axisWidthPx?: number;           // test override for jsdom
}
```

### 2.2 Anchor rail + granularity

Below the slider rail is a **custom-rendered anchor rail** (the lib's own pips are hidden via `pips={false}` because they're evenly-spaced approximations — issue #42 in upckommentar). Anchor day-numbers come from `pipAnchorsFor(granularity, minDay, maxDay)`:

- **year:** every Jan 1 in range.
- **month:** every 1st-of-month.
- **day:** every Monday.

Edges (`minDay`, `maxDay`) are always anchors so the user can park at the slider's extremes.

Granularity has **+/- zoom buttons** in the top-right of the slider (`year → month → day`), with each level showing more anchors.

### 2.3 Click-to-snap (left half / right half)

`DateRangeSlider.svelte:219-240` + pure helper `endOfPeriodDay()`:

- **Left half of an anchor label** → snap closest handle to **start** of period (the anchor day itself, e.g. Jan 1).
- **Right half of the same label** → snap to **end** of period (Dec 31 for year, last-of-month for month, Sunday for day).
- Keyboard activation falls back to left-half (start-of-period) deterministically.

### 2.4 Label thinning + two-row alternation

`pipLabelStrideFor()` + `pipLabelRow()` (pure helpers):

- Measures rail width via `ResizeObserver`.
- Computes a stride — only every Nth label is rendered.
- Adjacent rendered labels alternate row 0 / row 1 (~1.1em offset down) so they can sit closer horizontally without colliding.

### 2.5 Handle behaviour

- `range=true` draws a colored bar between handles.
- `draggy=true` lets the user drag the **bar itself** to shift the window without changing its width.
- `pushy=true` — handles push each other when crossed.
- `float=true` — tooltip floats above the dragged handle showing `DD.MM.YYYY`.

### 2.6 URL contract on host

`InboxFilterBar.svelte` debounces `onChange` at 250ms, then writes:

```
?date_from=2024-03-15&date_to=2024-09-30
```

When a handle is parked at min/max, that bound is **omitted** from the URL (`valuesToFromTo()` in the pure module). So `?date_from=2024-03-15` alone means "from March 15 onwards, no upper bound."

### 2.7 What's worth borrowing for paliad

| Element | Borrow? | Why |
|---|---|---|
| Two-handle drag | **Yes — but defer to Slice D** | Excellent fine-tune UX. Non-trivial to port without `svelte-range-slider-pips` (or a Svelte ↔ TSX adapter). |
| Anchor rail with click-to-snap | Yes (in Slice D) | Year/month/Monday anchors are the right granularities. |
| Label thinning + two-row alternation | Yes (in Slice D) | Makes the rail readable at any width. |
| Granularity + zoom +/- | Yes (in Slice D) | Single most useful interaction; users don't drag pixel-precise. |
| Epoch-day pure math | Yes — verbatim | The `date-range-slider-pure.ts` module is well-tested and dependency-free. Port to TS in paliad's pure-helper layer. |
| `null` = parked at edge | Yes — already aligned | TimeHorizon's `past_all` / `next_all` map cleanly to "one bound parked at infinity." |
| The library `svelte-range-slider-pips` itself | **No** | Adds a Svelte dependency to a non-Svelte project. Slice D would build a tiny equivalent on top of `<input type="range">` × 2 + CSS — or vendor the lib's pure parts. |

### 2.8 What does NOT apply to paliad

- **Floor at 2023-01-01.** upckommentar starts at the UPC's first day. paliad has decade-old patents and future-projecting deadlines; the axis must extend in both directions. We use `today ± 5 years` as the default visible range with `past_all` / `next_all` chips to escape it.
- **Single granularity locked per session.** upckommentar's UI shows one of year/month/day at a time. paliad's typical use ("next 30 days for the deadline list") doesn't benefit from a zoom; the chips ARE the granularity. Slicer in Slice D only opens when the user picks "Anpassen" — at which point the zoom UI makes sense.

---

## §3 Component design — `<DateRangePicker>`

### 3.1 Public API

```ts
type TimeHorizonExt =
  | "next_7d"  | "next_14d" | "next_30d" | "next_90d" | "next_all"
  | "past_7d"  | "past_14d" | "past_30d" | "past_90d" | "past_all"
  | "any" | "custom";

interface DateRangePickerProps {
  // Current state. The component is fully controlled.
  value: TimeSpec;
  onChange: (next: TimeSpec) => void;

  // Per-surface preset filter — omit a chip by leaving it out of the array.
  // Default: all symmetric chips + "any" + "custom".
  presets?: TimeHorizonExt[];

  // Closed-state button label override. Defaults to the i18n key for value.horizon
  // (e.g. "Letzte 30 Tage"). Override for surfaces that want a heading prefix
  // like "Zeitraum: Letzte 30 Tage".
  labelPrefix?: string;

  // i18n strings consumed via the i18n.ts dictionary. No props for individual labels.
  // Localisation flows through existing data-i18n attributes.

  // Surface tag — used to derive a stable testid and URL-param namespace if
  // the host wires URL serialization through helpers we provide (see §4).
  surface: string;          // e.g. "agenda" | "audit-log" | "filter-bar"

  // Mode — popover (default) or modal (rare).
  mode?: "popover" | "modal";

  // Anchor / placement for popover mode. Defaults to "below".
  placement?: "below" | "above" | "right";
}
```

`TimeSpec` mirrors the existing shape (`internal/services/filter_spec.go:107-112`), extended with the 4 new horizon values:

```ts
interface TimeSpec {
  horizon: TimeHorizonExt;
  field?: "auto" | "created_at";
  from?: string;            // ISO YYYY-MM-DD; set only when horizon === "custom"
  to?: string;
}
```

### 3.2 States

The component is a small state machine:

```
closed ────[click button]────► open
  ▲                              │
  └──[click outside / Esc]───────┘
                                 │
       open ───[click chip]──── closed (commit immediately)
                                 │
       open ───[click "Anpassen"]► custom-editor
                                 │
       custom-editor ─[Anwenden]► closed (commit)
       custom-editor ─[Esc]─────► open
```

- **closed** — single button with current selection label and a chevron `▾`. No outline/highlight unless the value is not the default for this surface.
- **open** — popover anchored below the button (or below-then-flip-up on viewport-bottom). Contains the symmetric chip row + ALL center + "Anpassen" sub-section.
- **custom-editor** — replaces the "Anpassen" link with two `<input type="date">` + "Anwenden" / "Abbrechen" buttons. (In Slice D this becomes the slicer.)

### 3.3 Symmetric chip layout

The popover body — full ASCII sketch:

```
┌─────────────────────────────────────────────────────────────┐
│  ╭ Vergangenheit ────────╮ ╭ ALLES ╮ ╭ Zukunft ───────────╮ │
│  │ [Ganze Vergangenheit] │ │ [⌖]   │ │ [Ganze Zukunft]    │ │
│  │ [Letzte 90 Tage]      │ │       │ │ [Nächste 7 Tage]   │ │
│  │ [Letzte 30 Tage]      │ │       │ │ [Nächste 14 Tage]  │ │
│  │ [Letzte 14 Tage]      │ │       │ │ [Nächste 30 Tage]  │ │
│  │ [Letzte 7 Tage]       │ │       │ │ [Nächste 90 Tage]  │ │
│  ╰───────────────────────╯ ╰───────╯ ╰────────────────────╯ │
│                                                             │
│  ── Anpassen ──────────────────────────────────────────     │
│  Von [____.____.____]  Bis [____.____.____]   [Anwenden]    │
└─────────────────────────────────────────────────────────────┘
```

Visual cues:

- The currently-selected chip gets the **lime accent** (`--color-bg-lime-tint` background, `--color-text` text, `--color-accent` border) — matches existing `.agenda-chip-active` so we don't introduce a new active state.
- The "ALLES" center button is **larger** than the fan chips (44px tall vs. 32px), drawn with a target-style glyph `⌖` (or `∞` — see Q3.B). Inventor pick: `⌖` plus the word "ALLES" beneath. Larger so it reads as "the no-filter affordance," not as one chip among many.
- The two fans are visually **mirrored** — past on the left, future on the right. Both have a "Ganze …" terminal chip at the outer edge (left-most for past_all, right-most for next_all) and decreasing-magnitude chips fanning toward the center. The ordering matches the human intuition: "left = back in time, right = forward in time."
- On viewports < 480px the popover stacks vertically (past fan above, ALL middle, future fan below). On viewports < 360px the popover becomes a modal-feeling slide-up sheet (existing inbox modal CSS pattern reusable).

### 3.4 Sketch of the closed button states

```
default:    ┌─Zeitraum: Nächste 30 Tage ▾─┐
custom:     ┌─Zeitraum: 15.03.2026 – 30.04.2026 ▾─┐
any:        ┌─Zeitraum: Alles ▾─┐
past_all:   ┌─Zeitraum: Ganze Vergangenheit ▾─┐
hover/open: same + outline + bg-accent-tint
```

When the value is **not** the surface default, an additional small `●` dot appears between "Zeitraum:" and the value — the existing universal "filter is non-default" indicator used by the filter-bar.

### 3.5 Keyboard

- `Tab` lands on the button. `Enter`/`Space` opens the popover.
- `Esc` from open state closes it. `Esc` from custom-editor returns to chip view (one level back).
- Chips are focusable buttons in the natural left-to-right reading order: past_all → past_90 → past_30 → past_14 → past_7 → any (center) → next_7 → next_14 → next_30 → next_90 → next_all.
- The custom date inputs are `<input type="date" lang="de">` — gets the OS-native picker on macOS / iOS / Android / Windows. No new custom calendar widget.

### 3.6 Accessibility

- The button has `aria-haspopup="dialog"` and `aria-expanded` toggled on open/close.
- The popover has `role="dialog"` with `aria-label` = `t("date_range.dialog.label")` ("Zeitraum wählen" / "Choose date range").
- Chips are `<button>` with `aria-pressed="true"` on the active one.
- The two fan groups have `role="group"` + `aria-label="Vergangenheit"` / `aria-label="Zukunft"`.

### 3.7 Module layout

```
frontend/src/
├── components/
│   └── DateRangePicker.tsx          ← TSX shell (markup only)
├── client/
│   ├── date-range-picker.ts         ← mount() + state machine + DOM event wiring
│   └── date-range-picker-pure.ts    ← horizon-bounds math, label resolver, parse/serialize
└── styles/
    └── global.css                    ← .date-range-* classes
```

`-pure.ts` is the headless module — fully testable under `bun test`. The boot client in `-picker.ts` consumes it, mirroring the pattern used by `shape-timeline-chart.ts` + `shape-timeline-chart.test.ts` (see memory: t-paliad-173 / gauss).

Pure module exports (preliminary):

```ts
export function horizonBounds(h: TimeHorizonExt, now: Date): { from?: Date; to?: Date }
export function labelForHorizon(h: TimeHorizonExt, lang: "de"|"en"): string
export function labelForCustom(from: string, to: string, lang: "de"|"en"): string
export function parseURL(params: URLSearchParams): TimeSpec
export function serializeURL(spec: TimeSpec, defaults: Partial<TimeSpec>): URLSearchParams
export function isDefault(spec: TimeSpec, default_: TimeSpec): boolean
```

### 3.8 Go-side additions

`internal/services/filter_spec.go`:

```go
// Add four new constants alongside the existing TimeHorizon block.
HorizonNext14d  TimeHorizon = "next_14d"
HorizonPast14d  TimeHorizon = "past_14d"
HorizonNextAll  TimeHorizon = "next_all"
HorizonPastAll  TimeHorizon = "past_all"
```

`internal/services/view_service.go:computeViewSpecBounds()`:

```go
case HorizonNext14d:
    bounds.from = &startOfDay; t := startOfDay.AddDate(0, 0, 14);  bounds.to = &t
case HorizonPast14d:
    f := startOfDay.AddDate(0, 0, -14); bounds.from = &f;          bounds.to = &startOfTomorrow
case HorizonNextAll:
    bounds.from = &startOfDay
    // bounds.to left nil  → "no upper bound"
case HorizonPastAll:
    bounds.to = &startOfTomorrow
    // bounds.from left nil
```

`HorizonNextAll` and `HorizonPastAll` are **one-sided unbounded** — distinct from existing `HorizonAll` (bidirectional unbounded) and `HorizonAny` (no filter at all, same effect as `HorizonAll` for view-spec runtime but different in intent).

`filter_spec.go:validate()` (line 280-292) gains the two new past/next constants in the switch.

### 3.9 i18n keys

Two-language matrix (DE primary, EN secondary):

```
date_range.button.label                 "Zeitraum"               / "Time range"
date_range.button.label.custom          "Von … bis …"            / "From … to …"
date_range.horizon.next_7d              "Nächste 7 Tage"         / "Next 7 days"
date_range.horizon.next_14d             "Nächste 14 Tage"        / "Next 14 days"
date_range.horizon.next_30d             "Nächste 30 Tage"        / "Next 30 days"
date_range.horizon.next_90d             "Nächste 90 Tage"        / "Next 90 days"
date_range.horizon.next_all             "Ganze Zukunft"          / "All future"
date_range.horizon.past_7d              "Letzte 7 Tage"          / "Last 7 days"
date_range.horizon.past_14d             "Letzte 14 Tage"         / "Last 14 days"
date_range.horizon.past_30d             "Letzte 30 Tage"         / "Last 30 days"
date_range.horizon.past_90d             "Letzte 90 Tage"         / "Last 90 days"
date_range.horizon.past_all             "Ganze Vergangenheit"    / "All past"
date_range.horizon.any                  "Alles"                  / "All"
date_range.horizon.custom               "Benutzerdefiniert"      / "Custom"
date_range.dialog.label                 "Zeitraum wählen"        / "Choose date range"
date_range.fan.past.label               "Vergangenheit"          / "Past"
date_range.fan.future.label             "Zukunft"                / "Future"
date_range.center.label                 "Alles"                  / "All"
date_range.custom.from                  "Von"                    / "From"
date_range.custom.to                    "Bis"                    / "To"
date_range.custom.apply                 "Anwenden"               / "Apply"
date_range.custom.cancel                "Abbrechen"              / "Cancel"
date_range.custom.invalid               "Bis-Datum muss nach Von-Datum liegen." / "End date must be after start date."
```

Total: 21 keys × 2 langs = 42 new entries in `i18n.ts`. Existing per-surface keys (`agenda.range.7`, `admin.audit.range.24h`, `views.bar.time.next_30d` etc.) stay until each surface migrates, then get retired.

---

## §4 URL / form serialization contract

### 4.1 Canonical URL shape

The picker writes (and reads) **canonical** params on the host's URL:

```
?horizon=next_30d
?horizon=past_all
?horizon=any           ← omitted if it matches the surface default
?horizon=custom&from=2026-03-15&to=2026-04-30
```

The host page's URL-init code (`bootDateRangePicker(surface, opts)`) calls `parseURL(searchParams)` to derive the initial `TimeSpec`, then calls `serializeURL(spec, defaults)` on every change. Params equal to the surface default are **omitted** so the canonical URL stays short and dedupable — matches the existing `writeParamToURL` pattern in `projects-chart.ts:144-154`.

### 4.2 Backwards-compat aliases

Each migrating surface keeps its existing alias parser for the transition window:

| Surface | Legacy URL | Canonical URL | Adapter |
|---|---|---|---|
| `/agenda` | `?range=30` | `?horizon=next_30d` | `range=N → horizon=next_${N}d` if `N ∈ {7,14,30,90}`, else `next_all` for `N>90`. Read both, write canonical. |
| `/admin/audit-log` | `?range=7d` | `?horizon=past_7d` | `range=24h → horizon=past_1d` (new, see Q5) or kept as `past_7d` fallback. `range=all → horizon=any`. |
| `/projects/:id/chart` | `?range=1y` | `?range=1y` (kept) | **NOT migrated to TimeHorizon** — projects-chart is symmetric-around-today. It uses DateRangePicker only for its **custom**-mode UI (the date-pair → slicer in Slice D). The 1y/2y/all presets stay surface-specific. |

The Go side is unaffected by aliasing — handlers receive whatever shape they always have, and the URL alias adapter lives entirely client-side per surface. **No backend route signature changes** in Slice A.

### 4.3 Custom Views (persisted JSON)

`paliad.user_views.filter_spec` is a JSON column. The TimeSpec extension is additive (new enum values, no shape change). Existing rows continue to validate. Migration not needed.

### 4.4 Form fields (Custom Views editor)

`views-editor.tsx:102-109` migrates from `<select>` to the picker. The form submits the same FormData shape (just one extra key for custom from/to — already plumbed via TimeSpec.from / TimeSpec.to). The Go-side `parseViewForm()` (TBD by coder) gains 4 new acceptable horizon values; existing test cases continue to pass.

---

## §5 Migration plan

### Slice A — substrate + filter-bar `time` axis

**Backend** (single migration not needed — additive constants only):

- `internal/services/filter_spec.go` — 4 new `TimeHorizon` constants + validate switch arms.
- `internal/services/view_service.go` — `computeViewSpecBounds()` 4 new switch cases.
- Pure unit tests for each new horizon (zero DB).

**Frontend**:

- New `frontend/src/components/DateRangePicker.tsx` + boot client + pure module.
- New i18n keys (42 entries).
- `frontend/src/client/filter-bar/axes.ts:renderTimeAxis()` — replace the disabled "Anpassen" stub with the picker. The chip cluster either becomes the picker's open-state (preferred) OR the chips stay flat and the picker only opens on "Anpassen" click (fallback if popover-in-bar is visually noisy). **Inventor pick (R): chips stay flat in the bar; "Anpassen" chip becomes the picker trigger. Picker emits TimeSpec back into the bar's state, same patch path.**

**Surfaces lit up automatically**: Verlauf (`/projects/:id`), Custom Views (`/views`, `/views/:id`), InboxFilterBar (`/inbox`).

**LoC estimate**: ~600 LoC (pure: 180 / boot: 180 / TSX: 100 / CSS: 80 / Go: 30 / tests: 240). Tests-first per `docs/design-paliad-test-strategy-2026-05-19.md`.

### Slice B — `/agenda`

- `agenda.tsx:51-69` — replace chip rows with `<DateRangePicker surface="agenda" presets={["next_7d","next_14d","next_30d","next_90d","next_all","custom"]} />`.
- `client/agenda.ts:85-104` — replace `wireControls()` chip wiring with picker subscription.
- URL alias adapter — accept `?range=N` for back-compat, emit `?horizon=…`.

**LoC**: ~80 LoC delta, mostly deletion.

### Slice C — `/admin/audit-log` + `/projects/:id/chart`

- `admin-audit-log.tsx:50-65` — replace `<select>` + date-pair with `<DateRangePicker surface="audit-log" presets={["past_7d","past_14d","past_30d","past_90d","past_all","custom"]} />`.
- `projects-chart.tsx:75-83` — **wrap** the existing 1y/2y/all presets in a custom-prop variant (a sibling component `<SymmetricRangePicker>` that shares the picker's popover scaffolding but emits the surface-specific `range_preset`). Or — if the head/m prefers — fold 1y/2y/all into TimeHorizon as `sym_1y` / `sym_2y` / `sym_all`. **Inventor pick (R): sibling component**, because symmetric-around-today is conceptually different from past/future fan. See §8 Q1.

**LoC**: ~120 LoC for audit-log, ~80 LoC for projects-chart wrap.

### Slice D *(optional, separate task)* — slicer

- Add `<DateRangeSlicer>` for the custom-editor sub-pane. Built on `<input type="range">` × 2 with a custom anchor rail above, ported from `date-range-slider-pure.ts`.
- Replaces inline date-pair when `horizon === "custom"` and `surface ∈ {agenda, audit-log, filter-bar}`. Projects-chart keeps inline date-pair OR also uses slicer — its choice.
- No new dependency.
- ~400 LoC including pure helpers + DOM scaffolding + tests.

### Per-slice rollout

| Slice | Risk | Surfaces affected | Coder profile |
|---|---|---|---|
| A | Low — additive only | 4 (filter-bar + 3 consumers) | Pattern-fluent Sonnet |
| B | Low | 1 | Same coder |
| C | Medium (projects-chart sibling) | 2 | Same coder |
| D | Medium (new slicer) | 0 (additive on top of A) | Separate task |

---

## §6 Visual decisions

### 6.1 Chip labels

Final labels — bilingual (DE first):

| Chip | DE | EN |
|---|---|---|
| past_all | Ganze Vergangenheit | All past |
| past_90d | Letzte 90 Tage | Last 90 days |
| past_30d | Letzte 30 Tage | Last 30 days |
| past_14d | Letzte 14 Tage | Last 14 days |
| past_7d | Letzte 7 Tage | Last 7 days |
| any (center) | Alles | All |
| next_7d | Nächste 7 Tage | Next 7 days |
| next_14d | Nächste 14 Tage | Next 14 days |
| next_30d | Nächste 30 Tage | Next 30 days |
| next_90d | Nächste 90 Tage | Next 90 days |
| next_all | Ganze Zukunft | All future |
| custom | Anpassen | Customize |

Rationale on "Anpassen" vs "Benutzerdefiniert":
- "Anpassen" matches existing `views.bar.time.custom` key value in `i18n.ts`.
- "Benutzerdefiniert" is used in admin-audit-log's dropdown — verbose, but more accurate.
- (R): **Anpassen** (consistent with filter-bar; six chars vs. eighteen).

### 6.2 Accent / active state

Reuse the existing **lime accent** chip-active state (`--color-bg-lime-tint` background, `--color-accent` border, `--color-text` text). This is the established affordance for the `agenda-chip-active` class — same visual reused, no new accent token.

### 6.3 The "ALLES" center button

A larger, target-glyph button — visually distinct from the fan chips so the user reads it as the "no time filter" exit, not as one chip among many:

```
   ╭──────╮
   │  ⌖   │
   │ ALLES│
   ╰──────╯
```

(R) glyph: `⌖` (Unicode U+2316 POSITION INDICATOR). Alternatives considered: `∞` (too math-y), `⊕` (too connect-y), `▣` (too checkbox-y), no glyph (chip then looks like every other chip). See §8 Q3.B.

### 6.4 Custom-range entry

In Slice A: **inline date-pair below the chip rows**, with an "Anwenden" button that commits + closes the picker. Plain `<input type="date" lang="de">` — gets the OS-native picker.

In Slice D (later): same slot becomes the slicer. The chip rows remain; the slicer collapses under them so the user can switch back to a chip with one click.

### 6.5 Hover / focus

- Chip hover: existing `.agenda-chip:hover` (lighter background tint).
- Chip focus-visible: 2px outline using `--color-accent`.
- Button focus-visible: same.
- Popover entry: 120ms fade-in via `transform: translateY(-4px) → 0` + opacity. Reduced-motion users (prefers-reduced-motion: reduce) get instant show.

### 6.6 Indication that the filter is non-default

The closed button shows a small `●` dot to the left of the label when the value is **not** the surface default. This matches the existing filter-bar non-default-indicator pattern (`frontend/src/client/filter-bar/index.ts` has a similar dot but on the whole bar; we adopt it per-control).

---

## §7 Edge cases

### 7.1 Timezones

All horizon math runs against **UTC `startOfDay`** of `new Date()` — same convention as `horizonBounds()` in `projects-detail.ts:393-406`. The user's browser may be in CEST in summer or CET in winter; the picker still treats "today" as a UTC date for filter purposes. The date-input localizes display (German locale → DD.MM.YYYY) but the underlying ISO is `YYYY-MM-DD` parsed as UTC midnight.

Practical impact: a user in CEST clicking "Letzte 7 Tage" at 01:30 local on 2026-06-15 sees `from=2026-06-07T00:00Z, to=2026-06-15T00:00Z` even though their local clock shows the 15th. This matches every other date-filter in paliad and avoids "the same row vanishes at 01:00 vs. 23:00" surprises. Document the convention in the pure module's header comment.

### 7.2 Far past truncation

`past_all` materialises to `from: nil`. The Go side (view_service.go) treats nil as "no lower bound" — the SQL `WHERE due_date >= ?` clause is omitted. No truncation needed.

For projects-chart's symmetric "all" mode, "all" still means **bounds derived from loaded events** (status quo) — the picker for projects-chart's surface uses the sibling `<SymmetricRangePicker>` which doesn't have `past_all`/`next_all` chips, only `1y/2y/all`.

### 7.3 Overlapping selections — past_7 + next_7 simultaneously?

The picker is **single-select** — one chip active at a time, OR custom mode. m's brief doesn't mention multi-select and the existing TimeSpec is single-valued. Multi-select would require a fundamental contract change. Don't.

If a user genuinely wants "last 7 days OR next 7 days," they use the custom-range with `from=today-7d`, `to=today+7d` — which is what `±1w` would mean. The fact that this is two chip-clicks vs. one isn't a real ergonomic loss.

### 7.4 Custom dates with from > to

Validate client-side: when both inputs are filled and `from > to`, the "Anwenden" button is disabled and a hint appears: "Bis-Datum muss nach Von-Datum liegen" (i18n key `date_range.custom.invalid`). The picker does **not** auto-swap.

### 7.5 Empty inputs in custom mode

If the user clicks "Anpassen" then clicks elsewhere before filling inputs, the picker reverts to whatever horizon was active before (state cached on entry to custom-editor). No "half-custom" state persists.

### 7.6 Surface-specific preset overrides

Each surface declares its own presets via the `presets` prop. The picker hides chips not in the array. The default surface preset (read from `defaults` prop, or hardcoded if absent) is what `serializeURL()` omits from the URL.

Important invariant: `defaults` must be a member of `presets`, OR be a special value like `any` that's always rendered. The component asserts this at boot and falls back to `any` if violated.

### 7.7 Bilingual labels mid-session

`labelForHorizon()` consults the live `i18n.ts` dictionary on every render, so a language toggle updates the picker immediately — including the closed-button label.

### 7.8 Embedded picker inside a filter bar

When the picker is mounted inside `filter-bar`, it should NOT use a full popover overlay — the filter bar already wraps controls. Instead the open-state's chip rows render **inline below the time chip cluster**, expanding the bar's height. This is `mode="inline"` (a third mode beyond popover/modal). Slice A picks this for filter-bar consumers; standalone surfaces (`/agenda`, `/admin/audit-log`) use popover mode.

### 7.9 What happens if a saved Custom View references `past_14d` before Slice A ships?

The JSON validator rejects it (`filter_spec.go:validate()` enum check). Saved views are migration-safe in one direction only — adding new enum values is fine; removing is not. Slice A adds, doesn't remove. No issue.

### 7.10 Race: URL change while picker is open

If the user has the picker open and a URL change happens via another control (e.g. they Cmd-Click a sidebar link), the picker is unmounted naturally with the page navigation. No state to preserve across navigations.

---

## §8 Open questions for m

Per task brief: **no AskUserQuestion**. Material picks escalated via `mai instruct head`; everything else defaults to (R) below. The head decides whether to forward to m or rule on the spot.

### Q1 [MATERIAL — escalate]: How to handle `/projects/:id/chart`?

The chart's range presets are **symmetric around today** (1y / 2y / all = ±1y / ±2y / all-data-bounds), conceptually different from past/future fans. Options:

- **(R) A — sibling component.** Keep a separate `<SymmetricRangePicker>` for the chart surface. Same popover scaffolding, different chip set. Chart's URL stays `?range=1y`. Doesn't add to TimeHorizon.
- **B — fold into TimeHorizon.** Add `sym_1y`, `sym_2y`, `sym_all` constants. Picker prop selects which fan vs. symmetric. Saved views could then express "±1y" too.
- **C — leave the chart as-is.** Don't migrate. Accept the visual inconsistency.

(R) **A.** Symmetric vs fan is a real semantic difference; one component trying to be both is muddier than two components sharing scaffolding. The chart isn't a "filter" — it's a viewport, and viewports legitimately want symmetric panning.

### Q2 [MATERIAL — escalate]: Modal vs popover for the standalone case?

m's brief says "mini modal." Options:

- **(R) A — popover always.** Anchored to the trigger button, click-outside dismiss. In-context, lightweight.
- **B — modal for explicit "open date filter" intent.** Use a centered modal with scrim when the picker is the page's primary filter (e.g. `/admin/audit-log` where date is the most prominent control). Popover for embedded uses.
- **C — modal everywhere.** Strong visual hierarchy, but interrupts the user.

(R) **A.** Modal feels heavy for what is conceptually a chip cluster. The "mini" qualifier in m's wording suggests popover, not full modal. If a surface specifically needs the modal weight, the `mode="modal"` prop is available — but no default surface picks it.

### Q3 [MATERIAL — escalate]: Slice priority — what migrates first?

- **(R) A — filter-bar `time` axis first** (Slice A). Lights up 4 surfaces simultaneously (Verlauf, InboxFilterBar, views runtime, Custom Views editor) by replacing the existing Phase-2 disabled stub.
- **B — `/agenda` first** (per task brief default). Highest-traffic standalone surface, simplest migration.
- **C — both A and B in parallel** (head splits between two coders).

(R) **A.** Filter-bar is the substrate everything else either uses or should use. Lighting it up first turns three downstream surfaces from "almost working" (the stubbed custom-range chip with "coming_soon" tooltip) to "fully working." Agenda then migrates as Slice B, on top of a proven component.

### Q3.B [DEFAULT — no escalation needed]: ALL center button glyph?

- **(R) `⌖`** (POSITION INDICATOR, U+2316). Implies "center / pin to here."
- B `∞` (infinity). Mathy.
- C `⊕` (circled plus). Looks like a button.
- D No glyph, just "ALLES" in bold.

(R) `⌖`. If the head/m doesn't like the unicode lookup, D is the safe fallback.

### Q4 [DEFAULT — no escalation]: Custom-range entry in Slice A?

- **(R)** Inline `<input type="date">` pair, OS-native picker. Slice D adds the slicer.

### Q5 [DEFAULT — no escalation]: Past `24h` in audit-log?

audit-log currently has a `24h` preset; the picker would express this as `past_1d`. Options:

- **(R)** Map legacy `?range=24h` → `?horizon=past_1d`. Add a new `past_1d` constant.
- B Drop `24h` — audit log defaults to `past_7d` like other surfaces. Users wanting "last 24h" use custom mode.

(R) Add `past_1d`. It's a one-line addition and audit-log users genuinely use "last 24h" for incident triage.

(Note: this means the picker actually has 5 past chips + 5 future chips + center + custom = 12 chips total, which fits comfortably in the popover.)

### Q6 [DEFAULT — no escalation]: Slice D (slicer) — separate task or fold in?

- **(R) Separate task.** Slice A-C are independently shippable. Slice D is meaningful design + ~400 LoC and shouldn't gate the main migration.

### Q7 [DEFAULT — no escalation]: Per-surface defaults?

Each migrating surface keeps its current default exactly:

- `/agenda` → `next_30d` (was 30).
- `/admin/audit-log` → `past_7d` (was 7d).
- `/projects/:id` Verlauf → `past_30d` (was past_30d in `projects-detail.ts:2310`).
- `/views/:id` runtime → whatever the saved view has (no change).
- `/inbox` (InboxFilterBar) → whatever filter-bar's surface defines.

### Q8 [DEFAULT — no escalation]: Should `past_14d` and `next_14d` retroactively appear in `views-editor.tsx`'s `<select>`?

(R) **Yes** — once Slice A ships, the `<select>` in `views-editor.tsx` is replaced by the picker (part of Slice A, as filter-bar consumers all flip in one commit). All 12 preset values become available for new Custom Views.

---

## §9 Implementer notes (for the coder shift, if approved)

### Lessons embedded

- **TimeSpec extension is additive only** — Go enum + TS union + i18n keys + horizonBounds switch. No DB migration, no contract break.
- **Pure module is testable under `bun test`** — no DOM needed for horizon math, label resolution, URL serialization. Aim for 95%+ coverage of the pure module before touching the boot client.
- **Reuse `.agenda-chip` styling** — adds no new tokens, no new dark-mode contrast risk (cf. memory t-paliad-150 / fritz — fritz lost 90 minutes to a `var(--token, #hex)` fallback bug because the token wasn't defined in dark mode).
- **`mode="inline"` for filter-bar consumers** — the bar already wraps its own popover-like layout; nesting popovers gets visually noisy.
- **Surface defaults must be members of `presets`** — assert at boot, fail loud in dev, fall back to `any` in prod.

### Recommended coder profile

Pattern-fluent Sonnet. Substrate is well-trodden (TimeSpec/TimeHorizon already lives, chip-cluster CSS exists, URL-codec pattern documented in `projects-chart.ts`). The novel piece is the popover scaffolding — paliad doesn't have a generic Popover primitive today; the picker builds its own DOM-anchored overlay. ~80 LoC of plain JS, no dependency.

### Build hygiene checklist

- `go build ./...` clean
- `go vet ./...` clean
- `go test ./...` clean (existing tests must continue passing — additive constants change zero behaviour)
- `bun run build` clean (i18n scan: 21 new keys added, all `data-i18n` attributes present)
- bun:test covers the pure module (horizon math, label resolver, URL parser/serializer)
- Playwright smoke (manual, not gated): on `/inbox` the time axis "Anpassen" chip is now functional; custom-from/to date pair commits a usable filter.

### Out of scope for the coder

- Slicer (Slice D) — separate task.
- Per-language adjustments beyond DE/EN (per task brief, out of scope).
- Time-of-day picking — separate concern.
- Recurring-event windows — events feed handles separately.
- A generic Popover primitive — extract only if a second consumer appears in the same slice.

### Acceptance criteria for Slice A

1. New `<DateRangePicker>` mounts on filter-bar's `time` axis, replacing the disabled "Anpassen" chip.
2. The 4 new horizon values (`past_14d`, `next_14d`, `past_all`, `next_all`) are accepted by Go's `TimeSpec.validate()` and produce correct `(from, to)` bounds in `computeViewSpecBounds()`.
3. The 4 new horizons round-trip through saved Custom Views (`paliad.user_views.filter_spec` JSON).
4. URL serialization is canonical (`?horizon=…&from=…&to=…`) and surface-default values are omitted.
5. Verlauf (`/projects/:id`), `/views`, `/views/:id`, and `/inbox` continue to function with their existing presets unchanged — they pick up the new picker but don't switch their preset list yet.
6. Pure-module unit tests cover: 12 horizons × bound calculation; URL parse / serialize round-trip; default-omission rule; custom-mode date validation.
7. `bun run build` reports the new i18n keys (no missing-key warnings).
8. No regression in `go test ./internal/services/...` (existing TimeSpec tests stay green).

---

## §10 Material picks summary — escalation message

To be sent via `mai instruct head` after this doc is pushed:

> Three material picks for m on date-range-picker design:
>
> 1. **`/projects/:id/chart` migration** — keep symmetric (1y/2y/all) presets as a sibling component, NOT fold into TimeHorizon. Chart is a viewport, not a filter.
> 2. **Popover vs modal** — popover by default. Modal is a `mode` prop available per surface but no surface picks it in Slice A.
> 3. **Slice A first migrates filter-bar time axis** (lights up Verlauf + InboxFilterBar + Views + Custom-Views-editor simultaneously by un-stubbing the existing "Anpassen" chip), not `/agenda` as the task brief defaulted. `/agenda` is Slice B.
>
> Everything else (chip labels, accent, glyph, custom-mode entry, surface defaults, past_1d for audit, slicer-as-Slice-D, 42 i18n keys) defaults per (R) in §8. Doc at `docs/design-date-range-picker-2026-05-25.md`.

---

*Verified premises (live, before designing):*

- `internal/services/filter_spec.go:107-126` — TimeHorizon enum at 9 values today.
- `internal/services/view_service.go:156-187` — `computeViewSpecBounds()` switches on the same enum.
- `frontend/src/client/views/types.ts:21-33` — TimeHorizon TS mirror; same 9 values.
- `frontend/src/client/filter-bar/axes.ts:65-115` — chip cluster renderer; "Anpassen" stub at line 105-112 marked Phase 2, disabled, "coming_soon" tooltip.
- `frontend/src/agenda.tsx:64-67` — chip row exact values `7|14|30|90`.
- `frontend/src/admin-audit-log.tsx:50-65` — select exact values `24h|7d|30d|custom|all`.
- `frontend/src/projects-chart.tsx:78-82` + `frontend/src/client/projects-chart.ts:73-118` — RangePreset `1y|2y|all|custom`, symmetric around today.
- `frontend/src/views-editor.tsx:102-109` — select exact values `next_7d|next_30d|next_90d|past_30d|past_90d|any`.
- `/home/m/dev/web/upc-kommentar/src/lib/components/DateRangeSlider.svelte` — 448 lines, wraps `svelte-range-slider-pips@4`, custom anchor rail above the lib's hidden pips, click-to-snap left/right halves, granularity year/month/day zoom.
- `/home/m/dev/web/upc-kommentar/src/lib/modules/date-range-slider/date-range-slider-pure.ts` — 487 lines, fully testable pure helpers, dependency-free, portable to paliad's TS.

*Not verified live:* upckommentar.de in a browser (requires author auth; the source code IS the source of truth and was read end-to-end).