# 26 — Customizable layout + widget configuration

## Goal

Inside any dashboard, the user can enter edit mode, drag-and-resize widgets on a 12-col grid, add new widgets via a picker that runs the configurator step, configure existing widgets after the fact, remove widgets, and reset to defaults. Layout persists per dashboard.

## Why

Combines the drag/resize mechanic with the per-widget configurator. Because every widget is uniformly configurable (per task 04), there is no special case — adding a `lists.list` widget pointed at a specific list goes through the same path as adding a `core.activity` widget with default config.

## Depends on

- 25 (multiple dashboards — operates on `dashboards.layout`)

## Scope

### Edit mode

- "Edit dashboard" button in the dashboard header. Toggles edit mode.
- In edit mode: each widget gets a drag handle (top edge) and a resize handle (bottom-right). Each widget gets a kebab with **Configure**, **Remove**.
- Header shows **Save** (enabled when dirty) and **Cancel**. Cancel reverts unsaved changes. Save persists `dashboards.layout` via server action and exits edit mode.
- ESC = cancel.

### Grid

- `react-grid-layout` (purpose-built; the boring-but-correct choice). 12 cols on desktop. Auto-pack on add.
- Per-widget `minSize` / `maxSize` enforced from the registry.
- Mobile: edit mode is desktop-only in v1. Mobile renders the read-only single-column derivation from task 20.

### Add widget (picker)

A two-step modal. Step 1 lists every registered widget grouped by `category`, with `title` + `description`. Step 2 (always present, even when trivial) is the configurator — see below. After confirming, the widget is appended at the bottom of the grid.

### Configurator

For a given widget definition:

1. Call `widget.resolveConfigOptions(ctx)` to fetch the picker's data (e.g. user's accessible calendars).
2. Render an auto-generated form from `widget.configSchema`:
   - For selection fields shaped `"all" | string[]`: a multi-select with an "All" toggle. Default value = `"all"`.
   - For numbers / strings / enums: corresponding inputs.
   - Use the schema's descriptions / `meta` for labels.
3. Validate on submit; reject silently-invalid configs.

Same component is reused for **Configure** on an already-placed widget. Re-runs `resolveConfigOptions`, prefilled with current config.

### Persistence shape

`dashboards.layout` schema unchanged from task 25:

```jsonc
{
  "version": 1,
  "widgets": [
    {
      "widgetId": "lists.list",
      "config": { "listIds": ["..."], "showCompleted": false },
      "x": 0,
      "y": 0,
      "w": 6,
      "h": 4,
    },
  ],
}
```

Save action validates each widget's config against its registered `configSchema`, rejecting the whole save if any invalid.

### Reset to defaults

Per-dashboard "Reset to defaults" in the header kebab. Replaces `layout.widgets` with the registry's `defaultPriority`-ordered seeded set, packed by `defaultSize` — the same logic task 20 uses for null layouts.

### "New widgets available" affordance

When the registry contains widgets the user has never placed on _any_ dashboard, surface a small badge on the "+" picker button. Doesn't auto-add anything.

## Out of scope

- Mobile edit mode.
- Inline widget config (config is always picker-driven, never per-cell).
- Cross-dashboard widget cloning.
- Widget marketplaces / non-registry widgets.
- Animated transitions between layouts.

## Acceptance criteria

- [ ] Drag and resize update layout positions; Save persists; Cancel reverts.
- [ ] Adding a widget always runs the configurator step. For widgets with `configSchema = z.object({})`, the step shows "No options" and a single Add button.
- [ ] The picker shows every widget the registry provides; adding a widget defined by a freshly-installed module just works without touching `_core`.
- [ ] Configure on an existing widget re-uses the same form and persists the change on save.
- [ ] Removing a widget removes only that widget; other instances of the same `widgetId` on the same dashboard are unaffected (same widgetId can appear N times).
- [ ] Reset-to-defaults restores the registry-default layout.
- [ ] A user can have multiple `lists.list` widgets on a single dashboard pointing at different lists. Confirms the per-instance config story end-to-end.
- [ ] Save action rejects invalid configs and surfaces the validation error in-form.