@hashsome/ui 0.5.0 → 0.7.0

package/dist/layout/board.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from 'react';
+export interface BoardProps {
+    /** How many equal columns the page is divided into. Default 12. */
+    columns?: number;
+    /** `Cell`s, each saying how big it is; the board places them. */
+    children: ReactNode;
+}
+/** 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 declare function Board({ columns, children }: BoardProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export interface CellProps {
+    /** How many columns wide. Default: all of them. */
+    cols?: number;
+    /** How many rows of the board it covers, counting rows as tall as their content (a room is one): `3` ends where the third row does, and the cell is as tall as those rows, whatever is in it (a card in it that is too tall squeezes). `'fill'` starts where the cell is placed and goes down to the bottom of the page (or of the content, if that is longer), whatever rows are beside it; they keep their place. Default 1. */
+    rows?: number | 'fill';
+    /** What is in it, one under the other with the gap between. In a cell of more than one row, or `'fill'`, the last card stretches to the cell's height. */
+    children: ReactNode;
+}
+/** 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 declare function Cell({ cols, rows, children }: CellProps): import("@emotion/react/jsx-runtime").JSX.Element;

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/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';
@@ -101,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/energy-chart.js

@@ -4,6 +4,7 @@ import { useState } from 'react';
 import { useEntityHandle } from '../hooks.js';
 import { useEntityHistory } from '../use-entity-history.js';
 import { usageFromDaily } from './energy-usage.js';
+import { AnimatedNumber, decimalsOf } from './animated-number.js';
 import { useDetail } from './detail-provider.js';
 import { RangeSwitcher, SeriesChart } from './series-chart.js';
 const ENERGY_RANGES = [
@@ -53,9 +54,7 @@ function PowerReading({ entity, fallbackUnit }) {
     const handle = useEntityHandle('sensor', entity);
     const sensor = handle.entity;
     const unit = sensor?.unit ?? fallbackUnit;
-    return (_jsx(Typography, { as: "span", variant: "stat", "aria-live": "off", children: handle.status === 'ready' && sensor?.numeric !== undefined
-            ? `${sensor.numeric} ${unit}`
-            : '—' }));
+    return (_jsx(Typography, { as: "span", variant: "stat", "aria-live": "off", children: handle.status === 'ready' && sensor?.numeric !== undefined ? (_jsx(AnimatedNumber, { value: sensor.numeric, format: (n) => `${n.toFixed(decimalsOf(sensor.numeric ?? 0))} ${unit}` })) : ('—') }));
 }
 function LifetimeEnergy({ entity }) {
     const handle = useEntityHandle('sensor', entity);

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/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] }));

package/dist/layout/tile.js

@@ -5,6 +5,7 @@ import { useEffect, useMemo, useRef, useState, } from 'react';
 import { Icon } from '../icon.js';
 import { RoundButton } from './round-button.js';
 import { statusLabels } from '../status.js';
+import { BADGE } from '../theme/grid.js';
 import { useDrawer } from './use-drawer.js';
 import { EnergyChart } from './energy-chart.js';
 import { HistorySection } from './history-section.js';
@@ -183,9 +184,16 @@ export function Tile({ label, icon, secondary, status = 'ready', active = false,
     const dimColorKey = ready ? 'line' : 'textMuted';
     const cardOpacity = !ready || feedback === 'pending' ? 0.7 : 1;
     const iconBadge = icon ? (_jsx(Flex, { as: motion.span, align: "center", justify: "center", position: "relative", radius: "full", width: 32, height: 32, initial: false, animate: { backgroundColor: iconBg, color: iconColor }, transition: COLOR_TRANSITION, css: { flex: 'none' }, children: _jsx(Icon, { name: icon, size: 16 }) })) : null;
-    return (_jsxs(Flex, { as: motion.div, radius: "card", position: "relative", align: "center", overflow: "hidden", minWidth: 0, "data-status": status, "data-active": accented, "data-solid-accent": solidAccent, "data-fill": fill !== undefined, "data-fill-visible": showFill, "data-overlay": overlay !== undefined, "data-pending": feedback === 'pending', "data-feedback": feedback === 'pending' ? undefined : feedback, 
+    return (_jsxs(Flex, { as: motion.div, radius: "card", position: "relative", align: "center", overflow: "hidden", minWidth: 0, "data-grid-card": true, "data-status": status, "data-active": accented, "data-solid-accent": solidAccent, "data-fill": fill !== undefined, "data-fill-visible": showFill, "data-overlay": overlay !== undefined, "data-pending": feedback === 'pending', "data-feedback": feedback === 'pending' ? undefined : feedback, 
         // A card that mounts (a page opened) is drawn as it is, not animated from nothing.
-        initial: false, animate: { backgroundColor: cardBg, color: cardColor, opacity: cardOpacity }, transition: COLOR_TRANSITION, css: ({ palette }) => feedback === 'error' ? { outline: `2px solid ${palette.danger}`, outlineOffset: -2 } : null, children: [hasFill ? (_jsx(Box, { as: motion.span, position: "absolute", background: "accent", 
+        initial: false, animate: { backgroundColor: cardBg, color: cardColor, opacity: cardOpacity }, transition: COLOR_TRANSITION, css: ({ palette, spacing }) => ({
+            // The badge between its padding, written down rather than left to the content, so a tile is a
+            // whole number of grid modules (12, in the comfortable density) whatever is in it.
+            minHeight: `calc(${spacing(4)} + ${BADGE}px)`,
+            ...(feedback === 'error'
+                ? { outline: `2px solid ${palette.danger}`, outlineOffset: -2 }
+                : {}),
+        }), children: [hasFill ? (_jsx(Box, { as: motion.span, position: "absolute", background: "accent", 
                 // Spans the whole card, including behind `trailing` (e.g. a color-capable light's
                 // picker button) — it's a sibling of the button and `trailing`, not nested inside the
                 // button, specifically so its width isn't capped at the button's own narrower bounds.

package/dist/layout/top-row.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+export interface TopRowProps {
+    /** What goes in the row: the date, the weather, the clock. */
+    children: ReactNode;
+}
+/** The row along the top of a page you build yourself instead of with `TopBar`: its pieces (`DateChip`,
+ * `WeatherChip`, `Clock`, `SystemStatus`) in a line at the right, in the height the grid gives the top
+ * row, with no padding of its own. */
+export declare function TopRow({ children }: TopRowProps): import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/layout/top-row.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "@emotion/react/jsx-runtime";
+/** @jsxImportSource @emotion/react */
+import { Flex } from 'e-prim';
+import { TOP_ROW } from '../theme/grid.js';
+/** The row along the top of a page you build yourself instead of with `TopBar`: its pieces (`DateChip`,
+ * `WeatherChip`, `Clock`, `SystemStatus`) in a line at the right, in the height the grid gives the top
+ * row, with no padding of its own. */
+export function TopRow({ children }) {
+    return (_jsx(Flex, { align: "center", justify: "flex-end", gap: 3, css: { minHeight: TOP_ROW }, children: children }));
+}

package/dist/provider.d.ts

@@ -1,4 +1,4 @@
-import { type Client, type RemoteClientOptions } from '@hashsome/core';
+import { type Client, type EntityRef, type RemoteClientOptions } from '@hashsome/core';
 import { type ReactNode } from 'react';
 import { type Density } from './theme/density.ts';
 import { type ThemeOverrides } from './theme/overrides.ts';
@@ -21,10 +21,14 @@ export interface HashsomeProviderProps {
     font?: string;
     /** `'compact'` for small square displays: tighter spacing, shorter tiles, smaller icon circles. Default `'comfortable'`. */
     density?: Density;
-    /** `'reduced'` turns animations and transitions off, for a slow display, `'full'` keeps them and `'auto'` (the default) leaves things as they are. A device can choose for itself with `?motion=reduced` (or `full`) on the address it opens: the choice is kept on the device, so reloads and links inside the app keep it, and `?motion=auto` forgets it. That wins over this prop. */
+    /** `'reduced'` turns animations and transitions off, for a slow display, `'full'` keeps them and `'auto'` (the default) leaves things as they are. A device can choose for itself with `?motion=reduced` (or `full`) on the address it opens, which wins over this prop. Nothing is kept: it holds while the app is open, moving between its pages, and a reload without the parameter goes back to this prop. */
     motion?: MotionPreference;
     /** Partial changes to the built-in theme — colors per light/dark, radii, typography, spacing, density sizes. Pass a constant defined outside the component: a new object each render rebuilds the theme each render. */
     overrides?: ThemeOverrides;
+    /** Shows the debug menu: a floating button at the bottom left whose popover shows the module grid, makes the page fullscreen and changes the theme, on the device, kept there. Default: on when `HASHSOME_DEBUG=1` (or `true`) was in the environment of `hashsome dev` or `build`. */
+    debug?: boolean;
+    /** The daylight sensor (`on` while the sun is up) the debug menu's Sun theme follows, when `theme` is not a sun schedule already (`theme={{ sun: … }}` names one). Without either, the menu has no Sun choice: Hashsome does not know which entity is the sun. */
+    sun?: EntityRef;
     /** The app. */
     children: ReactNode;
 }
@@ -40,5 +44,5 @@ export interface ThemeModeState {
  * Must be rendered inside `<HashsomeProvider>`. */
 export declare function useThemeToggle(): ThemeModeState;
 /** Connects the tree to the runtime proxy. Render only on the client. */
-export declare function HashsomeProvider({ url, client, clientOptions, theme, motion, font, density, overrides, children, }: HashsomeProviderProps): import("react").JSX.Element;
+export declare function HashsomeProvider({ url, client, clientOptions, theme, motion, font, density, overrides, debug, sun, children, }: HashsomeProviderProps): import("react").JSX.Element;
 export declare function useClient(): Client;