Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

11.7 KB
Raw Blame

Dashboard Widgets & Layouts (client/src/components/dashboard/)

Dashboard widgets are registered in widgetRegistry.jsx — each entry has { id, label, Component, width, defaultH?, gate? }. The Dashboard page renders the active layout's widget list from this registry; named layouts persist in data/dashboard-layouts.json (owned by server/services/dashboardLayouts.js) and are managed via GET/PUT/DELETE /api/dashboard/layouts. Built-in layouts (default, focus, morning-review, ops) are seeded on first read and cannot be deleted.

Grid positions: layouts also carry a grid: [{ id, x, w, order, h?, fixedH? }] array — column placement on a 12-column grid plus a reading/packing sequence. When grid is empty (legacy/unmigrated layouts) the renderer auto-flows widgets using synthesizeGrid based on each widget's width keyword and defaultH. The "Arrange" button on the Dashboard enters edit mode where every widget exposes a move (top-right) and resize (bottom-right) handle; a move snaps horizontally to columns and re-inserts the cell into the sequence at the rank its dropped pixel position implies (rankAtPixel → insertAtOrder), renumbering order densely. Save persists to the active layout's grid. The grid renderer collapses to a single-column stack below 640px container width, rendered in reading order (order, then x as a tiebreak) — never grid-array order, which nothing keeps sorted.

One vertical coordinate (#4133). There is no stored row position. Horizontal placement is declared (x/w); vertical placement belongs entirely to packVertically, which lays cells out in pixels, and order says only which cell packs first. That is why a gesture never has to reconcile "where the cell says it is" with "where it is drawn" — only one of those exists. Persisted layouts predating this carried { x, y, w, h }; sanitizeGridItem/sequenceGrid in server/services/dashboardLayouts.js still derive order from a legacy y on read (shape-probed, not version-flagged), and scripts/migrations/269-dashboard-grid-order.js rewrites the file on disk. A new widget-seeding migration must append { id, x, w, order, h }, not { x, y, w, h } — the older seed migrations (029/030/033/070/145/156/191) still compute y because they only ever run on pre-269 files.

Height is measured, not declared. h is NOT the rendered height. A cell measures its widget's natural height with a ResizeObserver and packVertically positions everything in pixels — each cell floats up to just below the nearest already-placed cell that shares a column. That's what stops an 80px card from reserving a 400px slot and leaving a band of dead whitespace across the row. h survives as the pre-measurement fallback (first paint) and as what an older client — which knows nothing about fixedH — reads out of a saved layout, so every drag commit refreshes it from the measurement via withMeasuredHeights. A cell whose height the user actually dragged carries fixedH: true and keeps h exactly, clipping content the way the whole grid used to; the ⌃⌄ handle (edit mode, pinned cells only) hands the height back to the content. defaultH in the registry is likewise only a first-paint ballpark.

The desktop handles are keyboard gestures too (#7263). Move and resize are grab toggles, not pointer-only affordances: Enter/Space lifts the cell, the arrows step it, Enter/Space drops it and Escape puts it back — deliberately the same state machine dnd-kit gives the mobile reorder handle, so both feel like one feature. There is one placement path, not two: beginGesture freezes the same snapshot for either input, stepGhost snaps in the same units the pointer drag rounds to (a column; a rank or a row), finishGesture applies the same applyGhost and the same fixedH rule, and the preview a keyboard step draws IS the commit. Only where the next ghost comes from differs — a pixel delta, or one arrow press. The single divergence is deliberate: a horizontal move step leaves order alone, where the drag re-derives it from rankAtPixel every frame, so ↑/↓ owns the sequence outright and no press has a second effect the user can't see coming. The grid's role="status" region narrates each step (the drag doesn't narrate — it's already visible to whoever is doing it), and aria-pressed carries grabbed/idle. A new handle wired with onPointerDown alone is a WCAG 2.1.1 failure, not a nice-to-have: it announces an action through its aria-label and then does nothing, which reads as broken rather than unavailable. DashboardGrid.test.jsx fails on any <DragHandle> in the source that takes onPointerDown without onKeyDown. A keyboard grab is modal, which a pointer drag is not — it stays open until the user acts, so anything that can end Arrange mode under it has to cancel it explicitly: unmounting a focused handle (Save/Cancel, or a rotation crossing the breakpoint) fires no blur, and the abandoned ghost would go on overriding the preview so the grid draws a placement the user already cancelled. One effect watching editable/isMobile owns that.

Mobile editing. Free-form move/resize is desktop-only (a phone has no room for positional editing), but reordering works on mobile: edit mode swaps the two grid handles for a single reorder handle. The 1-D sort goes through @dnd-kit/sortable — the same PointerSensor + KeyboardSensor + verticalListSortingStrategy pairing as cos/tabs/TasksTab.jsx and universeBuilder/InfluenceChipsInput.jsx — which is what supplies touch, keyboard (space to lift, arrows to move), multi-pointer safety, screen-reader announcements and edge auto-scroll. Do not hand-roll a pointer gesture for this; the free-form 2-D drag stays hand-rolled only because arbitrary grid placement is not what a sortable list does. Use dndTransformToCss from client/src/lib/dndTransform.js in the style object, never @dnd-kit/utilities.

On drop, onDragEnd re-flows the whole grid through reflowToOrder so its reading order matches the new stack order, preserving each widget's w/h. That means a mobile reorder re-packs the desktop layout into row-flow — the only coherent way to express a one-dimensional edit as column placement, and the edit-mode hint says so. synthesizeGrid is built on the same helper. The handle keeps touch-action: none; without it the browser claims the pointer stream for scrolling and the gesture never starts.

One source of truth for the mobile/desktop seam. DashboardGrid measures its own container (useContainerWidth), which page padding makes narrower than the viewport — so a Tailwind sm: breakpoint disagrees with it in a ~30px band. Anything outside the grid that needs to know which affordance is live (the Dashboard's edit-mode hint) reads it from the onLayoutModeChange callback, never from a CSS breakpoint.

A widget lays out by CONTAINER query, never by viewport breakpoint. A tile is ~250px wide on a 2560px screen, so every viewport sm:/md:/lg: inside it is unconditionally true and pins the widest layout into the narrowest column. This bites hardest when a component built for a full-width page is reused as a widget — TaskAddForm (via QuickTaskWidget) kept its wide row and squeezed the description textarea to one character per line. Put @container on the component's own root, not on the grid cell, and prefix its layout classes @sm:/@md:/@lg:: the same component also renders in drawers, settings panels and full-width pages that provide no container ancestor, where a cell-level container would leave every @ variant permanently unmatched. Viewport breakpoints remain correct for hover-vs-touch affordances (md:opacity-0 md:group-hover:opacity-100), which really are about the device, not the box — but a widget that needs one has to say so in the allowlist, because client/src/dashboardWidgetContainerConventions.test.js fails on any bare sm:/md:/lg:/xl:/2xl: variant in a component widgetRegistry.jsx lazy-imports. It scans the registry's own modules, not their whole import closure: a shared primitive that also renders on a real page has a viewport of its own to answer to. @container also brings contain: layout style inline-size, which makes the element a containing block for position: fixed descendants — the same trap the Drawer convention documents. A widget that draws a fixed overlay from inside itself has to portal it to <body> (Modal's usePortal), or it will be sized and clipped to the cell.

Widget order lives in the grid. saveGridEdit rewrites the layout's widgets array into readingOrderIds(grid) so LayoutEditor lists widgets in the order the dashboard actually shows them. By default reconcileGrid iterates the grid and uses widgets only for membership — position edits survive a widget toggle or a rename. LayoutEditor's Move up/down buttons therefore have to say so explicitly: save/commitDuplicate pass reordered, which isReordered() derives by comparing the draft list against the unmovedOrder ref — the order the draft would have had if the user had never pressed Move (add appends to it, remove filters it, move deliberately doesn't touch it). That baseline can't be reconstructed from the widget list after the fact, since nothing in it records which widgets were added this session or in what order; keeping it means a move-up-then-back nets out to false while a just-added widget being moved, or any reorder in a layout that started empty, still reads as true, and Dashboard.jsx forwards it as reconcileGrid(base, widgets, { reorder }), which re-flows the reconciled grid to the list order. Never infer that flag by comparing widgets to readingOrderIds(grid) — layouts arranged before saveGridEdit started syncing the two can already disagree, so inferring would re-pack a carefully arranged desktop layout on the first unrelated save (#4132).

When adding a new dashboard widget:

  1. Add a { id, label, Component, width, defaultH?, needs?, gate? } entry to WIDGETS in widgetRegistry.jsx. Use a stable id (kebab-case) — it's the contract stored in layouts. Pick defaultH from the widget's rough content height (default 4); it only has to be close, since the cell measures itself once painted.
  2. If the widget needs dashboard data (apps/health), read it from the dashboardState prop — do NOT issue a duplicate fetch from inside the widget — and list the streams it (or its gate) reads in needs. The page fetches only the streams the active layout's widgets need, and passes dashboardState only to widgets that declare needs; a widget without it gets no prop, so it is not re-rendered as each stream lands.
  3. If the widget only makes sense in some cases (e.g. only when apps exist), add a gate: (state) => boolean predicate.
  4. Add the widget id to the built-in default layout in server/services/dashboardLayouts.js if it should appear out of the box.
  5. Users can toggle widgets on/off per layout via the Dashboard's layout picker → Edit, and arrange/resize them via the "Arrange" button.

First paint comes from a local copy (dashboardBoot.js). The last server-confirmed layouts response is cached in localStorage, so a reload paints the user's grid and starts its widget chunks before GET /api/dashboard/layouts returns, and data reads wait until a layout is known so they never queue the layouts read behind them on a phone's handful of HTTP/1.1 connections. The cached copy is display-only: the picker, Arrange and the editor stay hidden until the server's copy lands, and the cache is never written back.

Switching layouts is also wired into the ⌘K palette — it synthesizes a Dashboard: <name> command per layout at palette-open time, so any layout the user creates is instantly keyboard-reachable without further registration.