@hashsome/ui 0.4.0 → 0.6.0

package/dist/layout/board.js

@@ -0,0 +1,85 @@
+import { jsx as _jsx } from "@emotion/react/jsx-runtime";
+/** @jsxImportSource @emotion/react */
+import { Box } from 'e-prim';
+import { useLayoutEffect, useRef, useState } from 'react';
+/** A page laid out on a grid, for a dashboard made for one device. The page is `columns` equal columns
+ * (a gap between them) and rows as tall as what is in them, with twice that gap between rows. Nothing
+ * says where a cell goes: each `Cell` only says how big it is, and the board puts it in the first
+ * place it fits, in the order written. Every card is a whole number of grid modules tall and every gap
+ * is 3, so whatever the board makes stays on the grid. It takes the height that is left of the page.
+ * Opt in: a page of plain flex columns keeps working the same. */
+export function Board({ columns = 12, children }) {
+    return (_jsx(Box, { "data-board": true, position: "relative", css: ({ density }) => ({
+            display: 'grid',
+            gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+            gridAutoRows: 'max-content',
+            alignContent: 'start',
+            // Twice as far between rows as between columns and inside a cell: a row is a group (a room), and
+            // groups read as groups.
+            columnGap: density.space,
+            rowGap: density.space * 2,
+            // The height of its rows, or the page's if that is more: it grows into what is left, and never
+            // shrinks below its content (the page scrolls instead).
+            flex: '1 0 auto',
+            minWidth: 0,
+        }), children: children }));
+}
+/** Something on a `Board`, and how big it is: `cols` wide and `rows` tall. Where it goes is the board's
+ * business. A room is one cell (its header and its tiles), a player beside three of them is one that
+ * covers three rows, or fills. */
+export function Cell({ cols, rows = 1, children }) {
+    const ref = useRef(null);
+    const fill = rows === 'fill';
+    const [height, setHeight] = useState(0);
+    // `fill`: as tall as from where the cell starts to the bottom of the board, or to the end of the
+    // others' content if that is further. The others' content, not its own: it is what is being set.
+    useLayoutEffect(() => {
+        const cell = ref.current;
+        const board = cell?.parentElement;
+        if (!fill || !cell || !board) {
+            return;
+        }
+        const measure = () => {
+            const others = [...board.children].filter((child) => child !== cell);
+            const bottom = Math.max(board.clientHeight, ...others.map((child) => child.offsetTop + child.offsetHeight));
+            const next = Math.max(0, Math.floor(bottom - cell.offsetTop));
+            setHeight((current) => (Math.abs(current - next) < 1 ? current : next));
+        };
+        measure();
+        if (typeof ResizeObserver === 'undefined') {
+            return;
+        }
+        const observer = new ResizeObserver(measure);
+        observer.observe(board);
+        for (const child of board.children) {
+            observer.observe(child);
+        }
+        return () => observer.disconnect();
+    });
+    const span = typeof rows === 'number' ? rows : 1;
+    const stretches = fill || span > 1;
+    const column = (gap) => ({
+        display: 'flex',
+        flexDirection: 'column',
+        gap,
+        '& > [data-grid-card]:last-child': stretches ? { flexGrow: 1 } : undefined,
+    });
+    return (_jsx(Box, { ref: ref, "data-cell": true, css: ({ density }) => ({
+            gridColumn: cols === undefined ? '1 / -1' : `span ${cols}`,
+            gridRow: span > 1 ? `span ${span}` : undefined,
+            minWidth: 0,
+            // A cell takes the height of what is in it, unless it is meant to reach across rows.
+            alignSelf: stretches ? 'stretch' : 'start',
+            // One that reaches across rows, or fills, takes the height the page and the others give it; its
+            // own content does not size them (a player taller than three rooms squeezes, it does not
+            // stretch the third, or push the page past its bottom).
+            contain: stretches ? 'size' : undefined,
+            ...(fill ? { position: 'relative' } : column(density.space)),
+        }), children: fill ? (_jsx(Box, { position: "absolute", css: ({ density }) => ({
+                top: 0,
+                left: 0,
+                right: 0,
+                height: height > 0 ? height : '100%',
+                ...column(density.space),
+            }), children: children })) : (children) }));
+}

package/dist/layout/debug-menu.d.ts

@@ -0,0 +1,11 @@
+/** @jsxImportSource @emotion/react */
+import type { EntityRef } from '@hashsome/core';
+import type { ThemeMode } from '../provider.tsx';
+/** A floating button at the bottom left, for working on a dashboard on the device it is for: its
+ * popover shows the module grid over the page, makes the page fullscreen, and changes the theme
+ * (light, dark, the system's, and the sun's when the project has a sun entity). What it sets is kept on the device. Only there when
+ * `HashsomeProvider` has `debug` on (`HASHSOME_DEBUG=1`), and not exported. */
+export declare function DebugMenu({ configured, sun, }: {
+    configured?: ThemeMode;
+    sun?: EntityRef | undefined;
+}): import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/layout/debug-menu.js

@@ -0,0 +1,99 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
+import { Flex, Typography } from 'e-prim';
+import { useEffect, useRef, useState } from 'react';
+import { THEME_CHOICES, useDebug } from '../debug.js';
+import { Icon } from '../icon.js';
+import { ChipRow } from './drawer-controls.js';
+import { PlainButton } from './plain-button.js';
+const THEME_LABELS = {
+    light: 'Light',
+    dark: 'Dark',
+    system: 'System',
+    sun: 'Sun',
+};
+const ON_OFF = [
+    { value: 'off', label: 'Off' },
+    { value: 'on', label: 'On' },
+];
+/** The theme the project configured, as the menu's own choice, for showing which is in effect when
+ * the menu has not chosen. A schedule by the clock is none of them. */
+function configuredChoice(configured) {
+    if (configured === undefined) {
+        return 'dark';
+    }
+    if (typeof configured === 'string') {
+        return configured;
+    }
+    return 'sun' in configured ? 'sun' : undefined;
+}
+function Row({ label, children }) {
+    return (_jsxs(Flex, { direction: "column", gap: 2, children: [_jsx(Typography, { as: "span", variant: "label", color: "textMuted", children: label }), children] }));
+}
+/** A floating button at the bottom left, for working on a dashboard on the device it is for: its
+ * popover shows the module grid over the page, makes the page fullscreen, and changes the theme
+ * (light, dark, the system's, and the sun's when the project has a sun entity). What it sets is kept on the device. Only there when
+ * `HashsomeProvider` has `debug` on (`HASHSOME_DEBUG=1`), and not exported. */
+export function DebugMenu({ configured, sun, }) {
+    const debug = useDebug();
+    const [open, setOpen] = useState(false);
+    const root = useRef(null);
+    const [isFull, setIsFull] = useState(() => typeof document !== 'undefined' && document.fullscreenElement !== null);
+    const canFullscreen = typeof document !== 'undefined' && document.fullscreenEnabled === true;
+    useEffect(() => {
+        const onChange = () => setIsFull(document.fullscreenElement !== null);
+        document.addEventListener('fullscreenchange', onChange);
+        return () => document.removeEventListener('fullscreenchange', onChange);
+    }, []);
+    // Closes on a touch anywhere else, and on Escape.
+    useEffect(() => {
+        if (!open) {
+            return;
+        }
+        const away = (event) => {
+            if (root.current && !root.current.contains(event.target)) {
+                setOpen(false);
+            }
+        };
+        const escape = (event) => {
+            if (event.key === 'Escape') {
+                setOpen(false);
+            }
+        };
+        document.addEventListener('pointerdown', away);
+        document.addEventListener('keydown', escape);
+        return () => {
+            document.removeEventListener('pointerdown', away);
+            document.removeEventListener('keydown', escape);
+        };
+    }, [open]);
+    const toggleFullscreen = (on) => {
+        // Asked for in the touch itself: a browser only allows it as the answer to one.
+        if (on) {
+            void document.documentElement
+                .requestFullscreen({ navigationUI: 'hide' })
+                .catch(() => undefined);
+        }
+        else if (document.fullscreenElement) {
+            void document.exitFullscreen().catch(() => undefined);
+        }
+        debug.setFullscreen(on);
+    };
+    const theme = debug.themeChoice ?? configuredChoice(configured);
+    return (_jsxs(Flex, { ref: root, "data-debug-menu": true, 
+        // As big as the button, whatever the page's own rules say: the document shell makes every `div`
+        // that is a child of `body` at least as tall as the window (`body > div { min-height: 100% }`),
+        // which this is, and the button would sit at the top of it.
+        css: {
+            position: 'fixed',
+            left: 12,
+            bottom: 12,
+            zIndex: 30,
+            width: 40,
+            height: 40,
+            minHeight: 0,
+        }, children: [open ? (_jsxs(Flex, { role: "dialog", "aria-label": "Debug", direction: "column", gap: 4, background: "surface", radius: "row", shadow: "drawer", p: 4, width: 288, css: { position: 'absolute', left: 0, bottom: 52, boxSizing: 'border-box' }, children: [_jsx(Row, { label: "Show grid", children: _jsx(ChipRow, { options: ON_OFF, value: debug.grid ? 'on' : 'off', onChange: (value) => debug.setGrid(value === 'on') }) }), _jsx(Row, { label: "Fullscreen", children: canFullscreen ? (_jsx(ChipRow, { options: ON_OFF, value: isFull ? 'on' : 'off', onChange: (value) => toggleFullscreen(value === 'on') })) : (_jsx(Typography, { as: "span", variant: "secondary", color: "textMuted", children: "Not available in this browser." })) }), _jsx(Row, { label: "Theme", children: _jsx(ChipRow
+                        // The sun only if the project has one to follow.
+                        , { 
+                            // The sun only if the project has one to follow.
+                            options: THEME_CHOICES.filter((choice) => choice !== 'sun' || sun !== undefined).map((choice) => ({ value: choice, label: THEME_LABELS[choice] })), value: theme, onChange: (value) => debug.setThemeChoice(value) }) })] })) : null, _jsx(PlainButton, { "aria-label": "Debug menu", title: "Debug menu", "aria-expanded": open, onClick: () => setOpen((current) => !current), center: true, radius: "full", background: "surface", color: "textMuted", shadow: "dock", width: 40, height: 40, css: { flex: 'none' }, children: _jsx(Icon, { name: "lu:bug", size: 18 }) })] }));
+}

package/dist/layout/detail-provider.d.ts

@@ -4,11 +4,13 @@ interface DetailState {
     header: ReactNode;
     body: ReactNode;
     expanded: boolean;
+    /** Stays at full size: the drawer has no button to collapse it. */
+    locked: boolean;
 }
 interface DetailContextValue {
     detail: DetailState | null;
-    /** `expanded` opens it at full size instead of the side panel. */
-    openDetail: (id: string, header: ReactNode, body: ReactNode, expanded?: boolean) => void;
+    /** `expanded` opens it at full size instead of the side panel; `locked` keeps it there, with no button to collapse it. */
+    openDetail: (id: string, header: ReactNode, body: ReactNode, expanded?: boolean, locked?: boolean) => void;
     /** Keeps an already-open drawer's content live; a no-op for any other `id`. */
     updateDetail: (id: string, header: ReactNode, body: ReactNode) => void;
     closeDetail: () => void;

package/dist/layout/detail-provider.js

@@ -4,8 +4,8 @@ const DetailContext = createContext(null);
 /** Backs the single shared `EntityDrawer`; instantiated once by `HashsomeProvider`. */
 export function DetailProvider({ children }) {
     const [detail, setDetail] = useState(null);
-    const openDetail = useCallback((id, header, body, expanded = false) => {
-        setDetail({ id, header, body, expanded });
+    const openDetail = useCallback((id, header, body, expanded = false, locked = false) => {
+        setDetail({ id, header, body, expanded: expanded || locked, locked });
     }, []);
     const updateDetail = useCallback((id, header, body) => {
         setDetail((current) => (current && current.id === id ? { ...current, header, body } : current));

package/dist/layout/drawer-controls.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
 import { Box, Flex, Typography } from 'e-prim';
 import { motion } from 'motion/react';
 import { MarqueeText } from './marquee-text.js';
-import { useEffect, useRef } from 'react';
+import { useEffect, useId, useRef, } from 'react';
 import { Icon } from '../icon.js';
 import { FadeScroll } from './fade-scroll.js';
 import { RoundButton } from './round-button.js';
@@ -36,6 +36,7 @@ export function StepButton({ icon, label, delta, holdDelta = delta * 10, onStep,
  * `fill` shows accent up to the value; a `gradient` track stays vivid up to the value and dims past it instead (no marker or thumb). */
 export function ValueBar({ label, value, min, max, keyStep, round = 1, gradient, height = 28, onDrag, onCommit, }) {
     const dragging = useRef(false);
+    const lastDrag = useRef(null);
     const fraction = max === min ? 0 : (value - min) / (max - min);
     const pct = Math.min(1, Math.max(0, fraction)) * 100;
     const clampValue = (v) => Math.min(max, Math.max(min, v));
@@ -64,16 +65,31 @@ export function ValueBar({ label, value, min, max, keyStep, round = 1, gradient,
         width: "100%", height: height, radius: "full", background: "surface", border: !gradient, cursor: "pointer", overflow: "hidden", css: { touchAction: 'none', ...(gradient ? { backgroundImage: gradient } : {}) }, onPointerDown: (event) => {
             dragging.current = true;
             event.currentTarget.setPointerCapture?.(event.pointerId);
-            onDrag(valueAt(event));
+            lastDrag.current = valueAt(event);
+            onDrag(lastDrag.current);
         }, onPointerMove: (event) => {
             if (dragging.current) {
-                onDrag(valueAt(event));
+                lastDrag.current = valueAt(event);
+                onDrag(lastDrag.current);
             }
         }, onPointerUp: (event) => {
             if (dragging.current) {
                 dragging.current = false;
                 onCommit(valueAt(event));
             }
+        }, 
+        // A touch the browser took or lost never ends with a release. Ending the drag with the last
+        // value the finger reached lets whoever holds it let go, instead of leaving it held for good.
+        onPointerCancel: () => {
+            if (dragging.current) {
+                dragging.current = false;
+                onCommit(lastDrag.current ?? value);
+            }
+        }, onLostPointerCapture: () => {
+            if (dragging.current) {
+                dragging.current = false;
+                onCommit(lastDrag.current ?? value);
+            }
         }, onKeyDown: onKeyDown, children: gradient ? (_jsx(Box, { as: motion.span, position: "absolute", background: "surface", initial: false, animate: { left: `${Math.max(pct, 4)}%` }, transition: { duration: 0 }, css: { top: 0, bottom: 0, right: 0, opacity: 0.72, pointerEvents: 'none' } })) : (_jsx(Box, { as: motion.span, position: "absolute", background: "accent", initial: false, animate: { width: `${pct}%` }, transition: { duration: 0 }, css: { top: 0, bottom: 0, left: 0 } })) }));
 }
 /** One round power icon button with two states: filled with the accent while on, neutral while off. */
@@ -85,19 +101,31 @@ export const CHIP_HEIGHT = 28;
 /** A wrapping row of pill choices (modes, presets) with the selected one filled. With `tabs` it is
  * a tab list (the selected chip is the open tab) that never wraps: too many to fit scroll sideways. */
 export function ChipRow({ options, value, onChange, tabs = false, }) {
+    // The accent behind the selected chip is one pill that glides to the next; its own id, so two rows
+    // on a page do not share it.
+    const pill = useId();
     // Tabs scroll sideways when there are more than fit, and fade at the edge that has more.
     const Wrap = tabs ? FadeScroll : Flex;
     return (_jsx(Wrap, { gap: 2, ...(tabs ? { role: 'tablist' } : {}), css: tabs
-            ? { flexShrink: 0, scrollbarWidth: 'none', '&::-webkit-scrollbar': { display: 'none' } }
-            : { flexWrap: 'wrap' }, children: options.map((option) => {
+            ? {
+                flexShrink: 0,
+                isolation: 'isolate',
+                scrollbarWidth: 'none',
+                '&::-webkit-scrollbar': { display: 'none' },
+            }
+            : { flexWrap: 'wrap', isolation: 'isolate' }, children: options.map((option) => {
             const selected = option.value === value;
             return (_jsxs(Flex, { as: "button", type: "button", ...(tabs ? { role: 'tab', 'aria-selected': selected } : { 'aria-pressed': selected }), ...(option.ariaLabel ? { 'aria-label': option.ariaLabel } : {}), onClick: () => onChange(option.value), align: "center", gap: 1.5, radius: "full", cursor: "pointer", 
                 // A fixed height, not the text's: an emoji is drawn from another font with a taller line,
                 // which would make this one chip taller than the rest.
-                height: CHIP_HEIGHT, px: 3, background: selected ? 'accent' : 'surface', color: selected ? 'accentText' : 'text', css: {
+                height: CHIP_HEIGHT, px: 3, background: "surface", color: selected ? 'accentText' : 'text', css: {
                     flex: 'none',
+                    position: 'relative',
                     whiteSpace: 'nowrap',
-                    transition: 'background-color 160ms ease, color 160ms ease',
-                }, children: [option.icon ? _jsx(Icon, { name: option.icon, size: 14 }) : null, _jsx(Typography, { as: "span", variant: "body", css: { minWidth: 0, maxWidth: 220 }, children: _jsx(MarqueeText, { children: option.label }) })] }, option.value));
+                    transition: 'color 160ms ease',
+                }, children: [selected ? (_jsx(Box, { as: motion.span, layoutId: pill, position: "absolute", radius: "full", background: "accent", transition: { type: 'spring', duration: 0.32, bounce: 0.12 }, 
+                        // Above every chip's own background, whichever way it is going: a later chip paints over
+                        // an earlier one's pill otherwise.
+                        css: { inset: 0, zIndex: 1 } })) : null, _jsxs(Flex, { as: "span", align: "center", gap: 1.5, position: "relative", minWidth: 0, css: { zIndex: 2 }, children: [option.icon ? _jsx(Icon, { name: option.icon, size: 14 }) : null, _jsx(Typography, { as: "span", variant: "body", css: { minWidth: 0, maxWidth: 220 }, children: _jsx(MarqueeText, { children: option.label }) })] })] }, option.value));
         }) }));
 }

package/dist/layout/entity-drawer.js

@@ -68,7 +68,7 @@ export function EntityDrawer() {
                         // its default `min-height: auto` can win out and push it past the stretched height
                         // instead of scrolling internally. `height: '100%'` here is well-defined regardless
                         // (the wrapper's `inset: 0` gives it an unambiguous content-box size).
-                        height: "100%", minHeight: 0, maxHeight: "100%", overflow: "auto", p: 5, css: { pointerEvents: 'auto' }, children: [_jsxs(Flex, { justify: "space-between", align: "center", gap: 2.5, mb: 4, children: [detail.header, _jsxs(Flex, { gap: 1.5, grow: 0, children: [_jsx(DrawerActionButton, { icon: expanded ? 'lu:minimize-2' : 'lu:maximize-2', label: expanded ? 'Collapse' : 'Expand', onClick: toggleExpanded }), _jsx(DrawerActionButton, { icon: "lu:x", label: "Close", onClick: closeDetail })] })] }), detail.body] }, "hash-drawer") })] })) : null }));
+                        height: "100%", minHeight: 0, maxHeight: "100%", overflow: "auto", p: 5, css: { pointerEvents: 'auto' }, children: [_jsxs(Flex, { justify: "space-between", align: "center", gap: 2.5, mb: 4, children: [detail.header, _jsxs(Flex, { gap: 1.5, grow: 0, children: [detail.locked ? null : (_jsx(DrawerActionButton, { icon: expanded ? 'lu:minimize-2' : 'lu:maximize-2', label: expanded ? 'Collapse' : 'Expand', onClick: toggleExpanded })), _jsx(DrawerActionButton, { icon: "lu:x", label: "Close", onClick: closeDetail })] })] }), detail.body] }, "hash-drawer") })] })) : null }));
 }
 const ACTION_BACKGROUND = 'surfaceRaised';
 const ACTION_COLOR = 'text';

package/dist/layout/grid-overlay.d.ts

@@ -0,0 +1,6 @@
+/** Draws the grid over the page it sits in (the `Page`, when the debug menu has it on): a faint
+ * line at every module, a stronger one at every tile pitch, and a box round every card (anything
+ * marked `data-grid-card`) with its height in modules, green when its top and height are on the grid
+ * and red when they are not. For laying out a dashboard for one device: see where things fall, and
+ * what to change. Never takes a touch. */
+export declare function GridOverlay(): import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/layout/grid-overlay.js

@@ -0,0 +1,143 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
+/** @jsxImportSource @emotion/react */
+import { useTheme } from '@emotion/react';
+import { Box } from 'e-prim';
+import { useLayoutEffect, useRef, useState } from 'react';
+import { gridMetrics, offGrid } from '../theme/grid.js';
+const SAME = (a, b) => a !== null && JSON.stringify(a) === JSON.stringify(b);
+/** The viewport the page has now (it is smaller than the screen while the browser shows bars), the
+ * screen, both in CSS px, and the pixel ratio: multiply by it for the panel's own pixels. */
+function describeDevice() {
+    const ratio = Math.round(window.devicePixelRatio * 100) / 100;
+    return `viewport ${window.innerWidth}×${window.innerHeight} · screen ${window.screen.width}×${window.screen.height} @${ratio}`;
+}
+/** Draws the grid over the page it sits in (the `Page`, when the debug menu has it on): a faint
+ * line at every module, a stronger one at every tile pitch, and a box round every card (anything
+ * marked `data-grid-card`) with its height in modules, green when its top and height are on the grid
+ * and red when they are not. For laying out a dashboard for one device: see where things fall, and
+ * what to change. Never takes a touch. */
+export function GridOverlay() {
+    const theme = useTheme();
+    const metrics = gridMetrics(theme.density.space);
+    const { module, tilePitch } = metrics;
+    const ref = useRef(null);
+    const [view, setView] = useState(null);
+    useLayoutEffect(() => {
+        const host = ref.current?.parentElement;
+        if (!host) {
+            return;
+        }
+        let frame = 0;
+        const measure = () => {
+            const style = getComputedStyle(host);
+            const centered = host.dataset['centered'] ?? '';
+            const [slack = 0, slackBelow = 0] = centered.split(' ').map(Number);
+            // The grid spans the whole page, its padding included: it starts at the page's edge, less the
+            // sliver centering left over, so the padding is its first modules and the cards start after it.
+            const top = slack;
+            const box = host.getBoundingClientRect();
+            const next = {
+                top,
+                width: host.scrollWidth,
+                height: host.scrollHeight - slack - slackBelow,
+                content: {
+                    left: parseFloat(style.paddingLeft),
+                    top: parseFloat(style.paddingTop) - slack,
+                    right: parseFloat(style.paddingRight),
+                    bottom: parseFloat(style.paddingBottom) - slackBelow,
+                },
+                centered,
+                device: describeDevice(),
+                cards: [...host.querySelectorAll('[data-grid-card]')].map((card) => {
+                    const rect = card.getBoundingClientRect();
+                    const x = rect.left - box.left + host.scrollLeft;
+                    const y = rect.top - box.top + host.scrollTop - top;
+                    return {
+                        x: Math.round(x * 10) / 10,
+                        y: Math.round(y * 10) / 10,
+                        width: Math.round(rect.width * 10) / 10,
+                        height: Math.round(rect.height * 10) / 10,
+                        off: offGrid(y, rect.height, module),
+                    };
+                }),
+            };
+            setView((current) => (SAME(current, next) ? current : next));
+        };
+        const schedule = () => {
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(measure);
+        };
+        schedule();
+        window.addEventListener('resize', schedule);
+        const resize = typeof ResizeObserver === 'undefined' ? undefined : new ResizeObserver(schedule);
+        resize?.observe(host);
+        // What the page is made of changing (a card appearing, a size changing): not this overlay's own.
+        const mutations = new MutationObserver((records) => {
+            if (records.some((record) => !ref.current?.contains(record.target))) {
+                schedule();
+            }
+        });
+        mutations.observe(host, { subtree: true, childList: true, attributes: true });
+        return () => {
+            cancelAnimationFrame(frame);
+            window.removeEventListener('resize', schedule);
+            resize?.disconnect();
+            mutations.disconnect();
+        };
+    }, [module]);
+    // A line every module, unless that is too fine to read, then every gap (3 modules).
+    const minor = module >= 3.5 ? module : module * 3;
+    const off = view?.cards.filter((card) => card.off).length ?? 0;
+    const [top = 0, bottom = 0] = (view?.centered ?? '').split(' ').map(Number);
+    return (_jsx(Box, { ref: ref, "data-grid-overlay": true, "aria-hidden": "true", css: { display: 'contents' }, children: view ? (_jsxs(_Fragment, { children: [_jsxs(Box, { position: "absolute", css: {
+                        left: 0,
+                        top: view.top,
+                        width: view.width,
+                        height: view.height,
+                        pointerEvents: 'none',
+                        zIndex: 4,
+                        backgroundImage: [
+                            `linear-gradient(to bottom, rgba(0, 150, 255, 0.5) 1px, transparent 1px)`,
+                            `linear-gradient(to right, rgba(0, 150, 255, 0.5) 1px, transparent 1px)`,
+                            `linear-gradient(to bottom, rgba(0, 150, 255, 0.12) 1px, transparent 1px)`,
+                            `linear-gradient(to right, rgba(0, 150, 255, 0.12) 1px, transparent 1px)`,
+                        ].join(', '),
+                        backgroundSize: [
+                            `100% ${tilePitch}px`,
+                            `${tilePitch}px 100%`,
+                            `100% ${minor}px`,
+                            `${minor}px 100%`,
+                        ].join(', '),
+                    }, children: [_jsx(Box, { position: "absolute", css: {
+                                left: view.content.left,
+                                top: view.content.top,
+                                right: view.content.right,
+                                bottom: view.content.bottom,
+                                outline: '1px dashed rgba(0, 150, 255, 0.9)',
+                            } }), view.cards.map((card) => (_jsx(Box, { position: "absolute", css: {
+                                left: card.x,
+                                top: card.y,
+                                width: card.width,
+                                height: card.height,
+                                boxSizing: 'border-box',
+                                outline: `1px solid ${card.off ? '#ef4444' : '#22c55e'}`,
+                                outlineOffset: -1,
+                                color: card.off ? '#ef4444' : '#22c55e',
+                                font: '600 9px/1 system-ui, sans-serif',
+                                padding: 2,
+                                overflow: 'hidden',
+                            }, children: card.height >= 14 ? `${Math.round((card.height / module) * 10) / 10}u` : null }, `${card.x}:${card.y}:${card.width}:${card.height}`)))] }), _jsx(Box, { position: "fixed", css: {
+                        // Clear of the debug menu's button, which is how the grid is turned on.
+                        left: 60,
+                        bottom: 8,
+                        zIndex: 100,
+                        pointerEvents: 'none',
+                        // On a narrow screen it wraps instead of running off the edge.
+                        maxWidth: 'calc(100vw - 68px)',
+                        background: 'rgba(0, 0, 0, 0.78)',
+                        color: '#fff',
+                        font: '600 11px/1.3 system-ui, sans-serif',
+                        padding: '4px 8px',
+                        borderRadius: 6,
+                    }, children: `grid · 1u = ${Math.round(module * 100) / 100}px · gap 3u · tile ${Math.round(metrics.tile / module)}u · ${off === 0 ? 'all on grid' : `${off} off grid`}${top + bottom > 0 ? ` · centered +${top}/${bottom}px` : ''}${view.device ? ` · ${view.device}` : ''}` })] })) : null }));
+}

package/dist/layout/hold-progress.d.ts

@@ -1,2 +1,8 @@
-/** The thin line along a card's top edge that fills while a press is being timed as a hold. */
-export declare function HoldProgress(): import("@emotion/react/jsx-runtime").JSX.Element;
+export interface HoldProgressProps {
+    /** Which edge of the card the line runs along. Default `top`. */
+    edge?: 'top' | 'bottom';
+    /** A literal CSS color for the line, alpha included. Left out, a half-faded muted text color. */
+    color?: string;
+}
+/** The thin line along a card's edge that fills while a press is being timed as a hold. */
+export declare function HoldProgress({ edge, color }: HoldProgressProps): import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/layout/hold-progress.js

@@ -1,9 +1,25 @@
 import { jsx as _jsx } from "@emotion/react/jsx-runtime";
 /** @jsxImportSource @emotion/react */
+import { keyframes } from '@emotion/react';
 import { Box } from 'e-prim';
-import { motion } from 'motion/react';
 import { HOLD_MS } from './use-hold.js';
-/** The thin line along a card's top edge that fills while a press is being timed as a hold. */
-export function HoldProgress() {
-    return (_jsx(Box, { as: motion.span, position: "absolute", height: 2, background: "textMuted", initial: { width: '0%' }, animate: { width: '100%' }, transition: { duration: HOLD_MS / 1000, ease: 'linear' }, css: { top: 0, left: 0, opacity: 0.5, pointerEvents: 'none' } }));
+/** Grows the line from its left end by scaling it, which the browser animates on its own, without
+ * the page's JavaScript or a layout for each frame: on a slow display, animating the width is what
+ * made the hold look stuck. */
+const fill = keyframes({
+    from: { transform: 'scaleX(0)' },
+    to: { transform: 'scaleX(1)' },
+});
+/** The thin line along a card's edge that fills while a press is being timed as a hold. */
+export function HoldProgress({ edge = 'top', color }) {
+    return (_jsx(Box, { as: "span", "data-keep-motion": "", position: "absolute", width: "100%", height: 2, ...(color ? {} : { background: 'textMuted' }), css: {
+            [edge]: 0,
+            left: 0,
+            opacity: color ? 1 : 0.5,
+            ...(color ? { backgroundColor: color } : {}),
+            pointerEvents: 'none',
+            transformOrigin: 'left center',
+            willChange: 'transform',
+            animation: `${fill} ${HOLD_MS}ms linear forwards`,
+        } }));
 }

package/dist/layout/page.d.ts

@@ -12,6 +12,12 @@ export interface PageProps {
 /** The page every dashboard renders into: padded by the density's spacing, a column with gaps,
  * exactly viewport height, and scrolling inside itself (the document never scrolls — the entity
  * drawer is `position: fixed` and relies on that). It pads further for a `NavRail` or `NavDock`
- * the dashboard includes. Render it once, in the app's root layout. */
+ * the dashboard includes. Render it once, in the app's root layout.
+ *
+ * The debug menu (`HASHSOME_DEBUG=1`) can draw the module grid over the page, spanning all of it (its
+ * padding is the grid's first three modules), with every card boxed green or red by whether it sits on
+ * the grid: for laying a dashboard out for one device. The height is rarely a whole number of grid
+ * modules; what is left over (under one module) is shared between the top and the bottom padding, so the
+ * content sits centered and the grid stays whole. */
 export declare function Page({ children, height }: PageProps): import("@emotion/react/jsx-runtime").JSX.Element;
 export {};

package/dist/layout/page.js

@@ -1,7 +1,11 @@
-import { jsx as _jsx } from "@emotion/react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
 /** @jsxImportSource @emotion/react */
+import { useTheme } from '@emotion/react';
 import { Flex } from 'e-prim';
-import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useState, } from 'react';
+import { useDebug } from '../debug.js';
+import { centeringOffsets, gridMetrics } from '../theme/grid.js';
+import { GridOverlay } from './grid-overlay.js';
+import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 const InsetContext = createContext(null);
 /** Reserves `size` px of the surrounding `Page`'s edge for something fixed over it (`NavRail`,
  * `NavDock`), so content never sits under it. A no-op outside a `Page`. */
@@ -12,7 +16,13 @@ export function usePageInset(side, size) {
 /** The page every dashboard renders into: padded by the density's spacing, a column with gaps,
  * exactly viewport height, and scrolling inside itself (the document never scrolls — the entity
  * drawer is `position: fixed` and relies on that). It pads further for a `NavRail` or `NavDock`
- * the dashboard includes. Render it once, in the app's root layout. */
+ * the dashboard includes. Render it once, in the app's root layout.
+ *
+ * The debug menu (`HASHSOME_DEBUG=1`) can draw the module grid over the page, spanning all of it (its
+ * padding is the grid's first three modules), with every card boxed green or red by whether it sits on
+ * the grid: for laying a dashboard out for one device. The height is rarely a whole number of grid
+ * modules; what is left over (under one module) is shared between the top and the bottom padding, so the
+ * content sits centered and the grid stays whole. */
 export function Page({ children, height = '100dvh' }) {
     const [insets, setInsets] = useState({ left: 0, bottom: 0 });
     const reserve = useCallback((side, size) => {
@@ -20,10 +30,37 @@ export function Page({ children, height = '100dvh' }) {
         return () => setInsets((current) => ({ ...current, [side]: 0 }));
     }, []);
     const value = useMemo(() => reserve, [reserve]);
-    return (_jsx(InsetContext.Provider, { value: value, children: _jsx(Flex, { as: "main", direction: "column", height: height, overflow: "auto", gap: 3, p: 3, css: ({ spacing }) => ({
+    // The debug menu's "Show grid" draws the module grid over the page, for laying a dashboard out.
+    const showGrid = useDebug().grid;
+    // What is left of the height after whole modules goes half to the top padding and half to the
+    // bottom one (in whole pixels, so edges stay crisp).
+    const theme = useTheme();
+    const space = theme.density?.space;
+    const main = useRef(null);
+    const [centered, setCentered] = useState({ top: 0, bottom: 0 });
+    useLayoutEffect(() => {
+        const element = main.current;
+        if (!element || space === undefined) {
+            return;
+        }
+        const measure = () => {
+            const next = centeringOffsets(element.clientHeight - 2 * space - insets.bottom, gridMetrics(space).module);
+            setCentered((current) => current.top === next.top && current.bottom === next.bottom ? current : next);
+        };
+        measure();
+        window.addEventListener('resize', measure);
+        const resize = typeof ResizeObserver === 'undefined' ? undefined : new ResizeObserver(measure);
+        resize?.observe(element);
+        return () => {
+            window.removeEventListener('resize', measure);
+            resize?.disconnect();
+        };
+    }, [space, insets.bottom]);
+    return (_jsx(InsetContext.Provider, { value: value, children: _jsxs(Flex, { as: "main", ref: main, "data-centered": `${centered.top} ${centered.bottom}`, direction: "column", height: height, overflow: "auto", position: "relative", gap: 3, p: 3, css: ({ spacing }) => ({
                 // The padding of one space, plus room for a nav that is fixed over the page.
                 paddingLeft: `calc(${spacing(3)} + ${insets.left}px)`,
-                paddingBottom: `calc(${spacing(3)} + ${insets.bottom}px)`,
+                paddingTop: `calc(${spacing(3)} + ${centered.top}px)`,
+                paddingBottom: `calc(${spacing(3)} + ${insets.bottom + centered.bottom}px)`,
                 boxSizing: 'border-box',
-            }), children: children }) }));
+            }), children: [children, showGrid ? _jsx(GridOverlay, {}) : null] }) }));
 }

package/dist/layout/room-header.js

@@ -4,7 +4,7 @@ import { Box, Flex, Typography } from 'e-prim';
 import { Icon } from '../icon.js';
 /** The header that starts a room: muted icon and title, a hairline, and readouts on the right. Put it above a `Grid` (or any tiles); it adds its own space above, so consecutive rooms read as groups. */
 export function RoomHeader({ title, icon, readouts }) {
-    return (_jsxs(Flex, { as: "header", align: "center", color: "textMuted", minHeight: 32, mt: 3, gap: 3, 
+    return (_jsxs(Flex, { as: "header", "data-grid-card": true, align: "center", color: "textMuted", minHeight: 32, mt: 3, gap: 3, 
         // A header starts a new group: the extra space sits on top of the screen's own gap, so a
         // room reads as header + its tiles rather than as evenly spaced rows.
         css: { '&:first-child': { marginTop: 0 } }, children: [icon ? _jsx(Icon, { name: icon, size: 16 }) : null, _jsx(Typography, { as: "h2", variant: "roomTitle", color: "textMuted", css: { margin: 0 }, children: title }), _jsx(Box, { as: "span", background: "border", css: { flex: 1, height: 1 } }), readouts ? (_jsx(Flex, { align: "center", color: "textMuted", css: ({ density }) => ({ gap: density.space * 1.5 }), children: readouts })) : null] }));