famapp/docs/tasks/26-customizable-layout.md

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:

{
  "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.