Dashboard

The snap-grid plate. Sizes itself to its content height (host it in a vertical scroll view); in the FOCUS posture it renders the focused tile alone, filling focusHeight. Content height is `rows × the row unit + gaps`. A FIXED unit lands no integer row count on an arbitrary plate, so under DashboardFit.viewport — the default, on every board (Dashboard.d.ts EVERY BOARD FILLS ONE VIEW, 2026-10-01, #968) — the unit is SOLVED against fitHeight, the host surface's measured height (dashboardFitUnit): `rows × unit + gaps` is exactly the plate, stretching with no ceiling and shrinking every tile in proportion until the first one reaches its KIND's minimum (minHeightOf); only then does the board hold that unit and scroll. Below 600 a row is never less than an eighth of the plate. A host that cannot measure degrades to the fixed unit. DashboardFit.rows opts out. ARRANGE UNDER FILL: the unit is FROZEN from a pointer layout gesture's start to its end, so the resize corner stays under the finger and the snap pitch never moves mid-drag; on release the board re-solves and every tile glides to its new rect at the move band. A keyboard step re-solves at once — there is no gesture to hold a pitch for — and the snap-grid overlay always draws the resolved pitch. Arrange mode: a TOUCH or PEN layout gesture begins with a HOLD (2026-08-24); a MOUSE press arms on its drag instead — past the pan slop it moves or resizes at once, with no hold (ARM BEFORE MOVE split by pointer class, #934), because a mouse press never scrolls the board and the hold guarded nothing there. A hold anywhere on the tile — the injected drag grip included, since it carries no recognizer of its own — lifts it for reorder, splicing the order LIVE by hit-testing the tile under the pointer; a hold on the bottom-end resize corner — the RESOLVED `--touch` square (DesignTokens.touch: 44 on touch, 32 at a fine pointer, #696) — (2px accent border on the end + bottom edges) commits whole grid steps through onResize (the bus clamps 2…12 × 1…8). The corner absorbs its own pointer, so the two can never contend for one press. The hold is not a flourish. A pan-started drag loses the gesture arena to any enclosing scrollable on every DOWNWARD gesture — a vertical drag recognizer claims the pointer at `kTouchSlop` while a pan waits for `kPanSlop`, twice as far — so the corner could be dragged sideways and never down, and the grip could not move a tile toward the bottom of the plate. A delayed recognizer accepts on a timer, before any movement, which is the only arming that makes the vertical axis reachable at all. A quick flick still falls through to the plate's scroll. Arrange motion (the Dashboard.d.ts 2026-08-23 amendment): placement changes GLIDE — every non-dragged tile and its resize corner tween position and size at the move band, so the live splice, each resize step, and surviving ids across a preset/visibility change read as tiles making room. The dragged tile leaves grid flow: it lifts (kDashboardLiftScale, quick band), paints above every sibling, and tracks the pointer by its grab offset while its destination cell renders the applied-grammar placeholder; release settles it in at the move band. Selection-tick haptics per committed splice/resize step. Reduced motion zeroes durations via AppMotion; the lift, the placeholder, and the haptics remain — state indication, not decoration. A RE-SOLVE IS NOT A PLACEMENT (Dashboard.d.ts THE CHROME ABOVE THE PLATE; THE DESK POSTURE, #735). The same glide carries two causes: an ARRANGE move — the placements changed (a splice, a resize step, a board switch, a visibility toggle) or a layout gesture was released — and a plate RE-SOLVE, where the placements did not change and the plate's measure did (the chip row, the arrange banner or the board tab row above it; a width). On touch both glide. At the desk a re-solve CUTS to its new layout — every tile gliding under the pointer when a search keystroke raises the chip row reads as the board moving on its own — while an arrange move keeps the move band, because there the user IS placing tiles. Arrange completion (the Dashboard.d.ts 2026-08-24 amendment): a LAYOUT GESTURE's pointer inside kDashboardAutoScrollBand of the hosting scroll viewport's top/bottom edge auto-scrolls the board (linear ramp to kDashboardAutoScrollMaxVelocity; stays on under reduced motion — function, not decoration; a grid hosted in no scrollable simply doesn't). BOTH gestures ride it (2026-09-03): a lift re-tests its splice as content moves, and a resize spends what the board scrolled as drag travel, so a corner dragged past the viewport edge keeps sizing instead of being lost until the pointer lifts. A drag over unoccupied plate space splices to the END of the order. The grip and resize corner are real focusable controls — arrows move one order step / resize one grid step (each press one gesture through the same boundaries), Escape fires onExitArrange. Arrange draws the snap grid as hairline gutter rules (every seam; never in the settled read tree). A held tile eases to kDashboardPreLiftScale over the hold delay (dropped under reduced motion). seam sets the gutter, the board's inset and who draws the rules (THE THREE SEAMS, DashboardSeam). The grid owns the welded rules and the welded and open seams' one card; tileBuilder passes the same seam to `DashboardTile.seam` so each tile shapes its own card and head. TWO WIDTHS: the LAYOUT width is the plate the grid is given, and the tracks divide it. The BAND width (bandWidth) decides the column count and every collapsed span — the plate's own width, unless the host holds it: a record pane that PUSHES the board holds it at the plate's width before the pane docked (Dashboard.d.ts THE RECORD PANE HAS THREE POSTURES AT >=960), so the board narrows without re-flowing.

The dashboard tile shell — THE HOUSE CARD with its card head (or the readout face) over the body slot, or the never-blank empty face when emptyReason is set. THE BOARD IS CARDS IN THE WORKSPACE (`Dashboard.d.ts`, Contained, 2026-09-29, #895). In seam: * `carded` — the tile IS a card: DesignTokens.paper, the DesignTokens.cardEdge hairline, DesignTokens.rM corners its content is clipped to, DesignTokens.sh1. The edge takes layout space, as the web kit's CSS border does, so the content sits one hairline in. * `welded` — the BOARD is the card: the tile paints the card's paper and no frame of its own, and the grid draws each tile's rule into the 1px gutter around it, so neighbors share one. * `open` — the board is one card, a paper field: the tile draws no frame, separated from its neighbors by space alone. When the tile SOURCES an applied filter (isFilterSource) a 2px accent edge runs its inline-start side, INSET INSIDE the card and clipped by its corners, in every seam, head included. It takes layout space too: a table row's own 2px selection edge sits beside it, never beneath it — a FILTER table tile's normal posture is a source whose rows are selected. THE CARD HEAD (face DashboardTileFace.card): DesignTokens.cardHeadH (48) tall, no fill of its own, padded 16 at the inline start and 12 at the end, members 10 apart, over a DesignTokens.hair rule in EVERY seam — a hairline inside the card. In order: drag grip (arrange only, injected by the grid via dragGrip) · index (the data role at 11, ink40, hidden below 3 columns) · title (THE TITLE ROLE, ink, sentence case, VERBATIM — the kit renders the string it is given and never transforms it) · the drill breadcrumb (an applied AppChip whose ✕ clears the drill) · the slack · legend (a chart content's, on ONE line — `Charts.d.ts` THE LEGEND RIDES THE CARD HEAD) · meta (the label role, ink40, hidden below 4 columns) · Add · the focus toggle, the head's ONE QUIET ICON ACTION (kDashboardHeadActionDesk at the desk, the `--touch` 44 on touch). THE READOUT FACE (face DashboardTileFace.readout): no head band and no rule. The tile pads the KPI (THE FRAME PADS, kpiPadding) and draws its LABEL LINE — the grip in arrange, title in the KPI label style, the focus toggle at its end — then the KPI, in the posture rowSpan gives it through KitKpiPostureScope: stacked at two rows or more, inline at one. The index, the meta, the breadcrumb and Add do not render. The tile is its body's frame in every seam: a table in the body draws no box of its own (Dashboard.d.ts A TABLE IN A TILE BODY DRAWS NO FRAME OF ITS OWN), which the body declares to it through a kit-internal scope. THE TRAILING CONTROL IS SINGLE AND CONSTANT (the 2026-08-21 owner amendment): the focus toggle alone at every span, PINNED to the trailing corner — the slack sits between the title and the meta cluster, never after the toggle. Retirement applies to index and meta only. Under pressure the title and the meta cluster split the remaining room EVENLY, each ellipsizing within its half — strict title-first yield is not expressible in one flex pass without either un-pinning the corner control or letting the cluster overflow it, and a loose Flexible's cap is its allocation, so biasing the weights would clip the meta at rest instead. While arrange is on the BODY ignores pointers — outside arrange mode a tap always means data; inside it, none does. THE TILE BODY IS THE SCROLL BOX (Dashboard.d.ts, 2026-09-27). The body's behavior is DECLARED by its content through fillsBody, never detected from its constraints: * `false` (the default) — the body scrolls child vertically at its own height, never less than the body's. The scroller takes the ambient physics, so its edge overscroll CHAINS to the board exactly as a tile scroller's does (THE BOARD SCROLLS ITSELF): nothing here contains it. * `true` — the body hands child its exact box and clips, and the child scrolls itself: a table, a map, a chart platter, or any host content that is its own scroller. The empty face ignores fillsBody: it fills the body and scrolls within it when a short tile cannot hold it, in both postures. A TILE BODY INSETS FLOW CONTENT (Dashboard.d.ts, 2026-09-29). inset DECLARES the body's padding, and a null one is inferred from fillsBody (resolvedInset): content that fills the body's exact box owns its edge and stays flush, while content the body scrolls is inset by kDashboardTileContentInset. In the scrolling body the inset is the scroll view's own padding, so the content scrolls under it and its last line rests one inset above the frame. The empty face and a readout ignore it. A stat card in the body draws no frame of its own (Card.d.ts THE TILE IS A STAT CARD'S FRAME), through the same kit-internal scope a table reads. A TILE BODY MAY LEAD WITH A BAND (Dashboard.d.ts, 2026-10-01, #882). band is a row of members (stats, say) laid inside the body above its content: one row of EQUAL tracks kDashboardTileContentInset apart, each member stretched to the tallest, padded by the content inset on its top and both inline sides and set the same inset above the content, whatever the body's own inset. The band holds still; the content takes the rest (a fillsBody table stays flush beneath it). It stays over the empty face, a readout ignores it, and under arrange it takes no tap.

The single screen-level freshness line (Δ12): "as of {last sync}" plus a `caution` "Syncing…" chip **while a cycle is in flight** — once per screen, never per unit. This chip (not the pull-to-refresh arc, Δ15) carries the ongoing in-flight state; it resolves independently when the sync lands or times out. FRESHNESS IS A LIVE REGION (`Charts.d.ts` `FreshnessLineProps`, #1428): the line is one `Semantics(liveRegion: true)` node — polite.

The dashboard view pattern. Hosts DashboardGrid + DashboardTile inside RecordsChrome (one narrowing, one chip row — the bus's range and viewport ride as synthetic chips) with the TRANSIENT modeline carrying Clear-all's "filters cleared" + Undo for its moment (transient-only, Dashboard.d.ts 2026-08-24 — the four standing segments and the posture word are deleted), and the pop-out detail pane in its DECK posture below the threshold (the record stays beside the plate, never over it). THE RECORD PANE HAS THREE POSTURES AT >=960 (`Dashboard.d.ts`, 2026-09-25) — detailPosture: PUSH docks the pane in flow and holds the board's columns and collapsed spans at the BAND width, the plate's width before the pane docked, so only the tracks shrink; OVERLAY floats the same pane over the board's inline-end edge and leaves the layout alone; AUTO, the default, pushes while a pushed track stays at or above kDashboardReadableTrack and overlays below it. The pane is kAppDetailPaneWidth (`--dv-pane-w`) wide, measured against this surface, never the viewport. A WIDE MAP TILE OPENS ITS PIN IN ITS OWN PANE instead, and ONE RECORD IS OPEN AT A TIME across the two: the pattern holds the record a tile's own pane shows (DashboardTilePaneScope), with Escape and predictive back. ONE TAP MEANING PER TILE, ONE SELECTION MECHANISM (`Dashboard.d.ts`, 2026-09-25): a tile that shows a table or a map builds its content with `DashboardTableTile` or `DashboardMapTile`, so its primary tap has ONE declared meaning — FILTER or OPEN — and a row filter is a key scope on the bus, never a second selection state. A key dimension no facet column carries gets its chip here, labeled by its def's DashboardTileDef.emitLabel. The one-deep arrange-gesture undo rides the BAR (relocated with the band's standing removal): a transient labeled Undo affordance inline-start of the arrange toggle, present only while an undo is armed — not a resting action, so the charter's two-action ceiling stands. THE BOARD SCROLLS ITSELF (`Dashboard.d.ts` 2026-09-24): the plate is the board's OWN vertical scroller, under the chip row, the board tab row and the arrange banner, which stay put — and beside a docked pane, which never scrolls with it. Fill (fit) removes most overflow; for the rest: a tile scroller's vertical overscroll at its edge CHAINS into the board (a fling hands over its remaining velocity), tile bodies run under clamping physics so a bounce cannot absorb that edge, and with no overscroll indicator so a drag that chains does not stretch the tile too, the board carries an always-visible, draggable thumb exactly while it overflows (past kDashboardOverflowTolerance), and it tells its tiles so through DashboardBoardScope — the map tile's cue to cooperate. No scroll mode, and no entering arrange to scroll. T is the FACET vocabulary's row type — the canonical record set the chip row and filter panel read. Tiles hold their own row types inside their defs' closures.

What the dashboard BOARD tells the tiles on it about its own scroll (`Dashboard.d.ts` THE BOARD SCROLLS ITSELF, 2026-09-24): whether it overflows its plate, so the board's own scroller has somewhere to go, and the VISIBLE plate's plateHeight. The map tile is the reader it exists for. A map takes every one-finger drag and every wheel turn, so on a board that scrolls it must leave the board a way to scroll (`Dashboard.d.ts` MAPS NEVER TRAP THE BOARD): at the desk it COOPERATES (`AppMapView.gestureHandling`, `MapView.d.ts` COOPERATIVE GESTURES), and on touch it stays direct and never renders taller than plateHeight less the scroll band (A MAP ON A BOARD TAKES ONE FINGER, `DashboardMapTile.gestureHandling`). Read it with the context a tile is built in, and a tile def's own builder context is fine: DashboardGrid builds every tile in its own layout context, which sits below the scope, and it keys its built-tile cache on overflows, so a tile it has cached rebuilds the moment the board starts or stops overflowing. plateHeight is not in that key — it moves with every resize and every frame a deck rises — so read it from a widget's OWN build, whose dependency rebuilds it without the grid: ```dart builder: (context, bus, mode) => DashboardTileContent( child: AppMapView<T>( mode: geo, pins: pins, gestureHandling: DashboardBoardScope.overflowsOf(context) ? MapGestureHandling.cooperative : MapGestureHandling.direct, ), ), ``` `RecordsDashboard` publishes it from its board scroller's own metrics, the one place that KNOWS whether the board scrolls, and decides it past kDashboardOverflowTolerance. The grid cannot: under the deck hold it lays out against the plate it held, not the shorter one the deck left, and a board that scrolls above a deck is exactly where a map must cooperate. A host composing DashboardGrid in a scroller of its own publishes it the same way; with no scope at all the answer is false, the direct default.

One labeled section: an optional label (the label role in DesignTokens.ink60), an optional note rendered as a kit AppBanner, and the section's child, each labelGap apart. Stack several in a LabeledSectionStack, which spaces them by sectionGap. Inside a dashboard tile the section takes the tile's content inset like any flow content (`Dashboard.d.ts` A TILE BODY INSETS FLOW CONTENT), so it pads nothing of its own. ```dart LabeledSectionStack( children: [ LabeledSection(label: 'Dashboards', child: AppCardGrid.category(...)), LabeledSection(label: 'Records', child: AppCardGrid.category(...)), ], ) ```