@hashsome/ui 0.5.0 → 0.7.0

package/dist/provider.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { RemoteClient } from '@hashsome/core';
+import { RemoteClient, } from '@hashsome/core';
 import { Global, ThemeProvider as EmotionThemeProvider } from '@emotion/react';
 import { ThemeProvider } from 'e-prim';
 import { MotionGlobalConfig } from 'motion/react';
-import { createContext, useContext, useEffect, useMemo, useState, useSyncExternalStore, } from 'react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, useSyncExternalStore, } from 'react';
+import { DebugContext, debugFromEnv, useDebugState, useFullscreenKept, } from './debug.js';
+import { DebugMenu } from './layout/debug-menu.js';
 import { DetailProvider } from './layout/detail-provider.js';
 import { EntityDrawer } from './layout/entity-drawer.js';
 import { UNITS_PER_SPACE } from './theme/density.js';
@@ -51,22 +53,13 @@ export function useThemeToggle() {
     }
     return value;
 }
-const MOTION_KEY = 'hashsome:motion';
-/** What this device chose for motion: `?motion=reduced` or `?motion=full` on the address (which is
- * also remembered), or what an earlier visit remembered. `?motion=auto` forgets it. */
-function motionFromDevice() {
+/** What the address asks for motion: `?motion=reduced` or `?motion=full`. Nothing is kept, and the
+ * app reads it once, when it starts, so moving between pages inside the app keeps it and a reload
+ * without it does not. `?motion=auto` (or anything else) leaves it to the prop. */
+function motionFromAddress() {
     try {
         const asked = new URLSearchParams(window.location.search).get('motion');
-        if (asked === 'reduced' || asked === 'full') {
-            localStorage.setItem(MOTION_KEY, asked);
-            return asked;
-        }
-        if (asked === 'auto') {
-            localStorage.removeItem(MOTION_KEY);
-            return undefined;
-        }
-        const kept = localStorage.getItem(MOTION_KEY);
-        return kept === 'reduced' || kept === 'full' ? kept : undefined;
+        return asked === 'reduced' || asked === 'full' ? asked : undefined;
     }
     catch {
         return undefined;
@@ -77,7 +70,7 @@ function motionFromDevice() {
  * transitions and animations too. */
 function useMotionMode(preference) {
     const [mode] = useState(() => {
-        const chosen = motionFromDevice() ?? preference;
+        const chosen = motionFromAddress() ?? preference;
         MotionGlobalConfig.skipAnimations = chosen === 'reduced';
         if (typeof document !== 'undefined') {
             if (chosen === 'reduced') {
@@ -102,6 +95,22 @@ function rememberedSun() {
         return undefined;
     }
 }
+/** The sun entity a theme follows, if it is a sun schedule. */
+function sunOf(mode) {
+    return typeof mode === 'object' && 'sun' in mode ? mode.sun : undefined;
+}
+/** The theme in effect: what the debug menu chose, if it chose, else what the project configured.
+ * The sun is the project's: the one its theme follows, or the `sun` it gave. Without one there is no
+ * sun to follow, so that choice (kept from a visit that had one) leaves the configured theme as it was. */
+function chosenTheme(configured, choice, sun) {
+    if (choice === null) {
+        return configured;
+    }
+    if (choice === 'sun') {
+        return sun === undefined ? configured : { sun };
+    }
+    return choice;
+}
 /** Resolves the configured mode: `'system'` against the live OS/browser preference (updating if it
  * changes while open — a kiosk tablet left running overnight should follow a scheduled OS-level dark
  * mode, for example), a time range against the clock (re-checked at each boundary and whenever the
@@ -151,7 +160,12 @@ function useThemeMode(mode, client) {
             document.removeEventListener('visibilitychange', onVisible);
         };
     }, [from, to]);
-    const sun = useSyncExternalStore((onChange) => (sunRef ? client.subscribe(sunRef, onChange) : () => undefined), () => (sunRef ? client.getEntity(sunRef) : undefined), () => undefined);
+    // Memoized, like every other `subscribe` given to `useSyncExternalStore` (see hooks.ts): a new
+    // function each render makes React resubscribe, which against a remote runtime is an unsubscribe and
+    // a subscribe whose reply is a new entity object, which renders again, without end.
+    const subscribeSun = useCallback((onChange) => (sunRef ? client.subscribe(sunRef, onChange) : () => undefined), [client, sunRef]);
+    const readSun = useCallback(() => (sunRef ? client.getEntity(sunRef) : undefined), [client, sunRef]);
+    const sun = useSyncExternalStore(subscribeSun, readSun, () => undefined);
     const sunDown = sunIsDown(sun);
     useEffect(() => {
         if (sunDown === undefined) {
@@ -181,10 +195,14 @@ function useThemeMode(mode, client) {
     return { resolved, toggle: () => setOverride(resolved === 'dark' ? 'light' : 'dark') };
 }
 /** Connects the tree to the runtime proxy. Render only on the client. */
-export function HashsomeProvider({ url, client, clientOptions, theme = 'dark', motion = 'auto', font = DEFAULT_FONT, density = 'comfortable', overrides, children, }) {
+export function HashsomeProvider({ url, client, clientOptions, theme = 'dark', motion = 'auto', font = DEFAULT_FONT, density = 'comfortable', overrides, debug = debugFromEnv(), sun, children, }) {
     const instance = useMemo(() => client ?? new RemoteClient({ url: url ?? defaultUrl(), ...clientOptions }), [client, url, clientOptions]);
     useMotionMode(motion);
-    const themeMode = useThemeMode(theme, instance);
+    const debugState = useDebugState();
+    useFullscreenKept(debugState.fullscreen, debugState.setFullscreen);
+    // The debug menu can choose a theme over the configured one; the sun is the project's own entity.
+    const sunEntity = sunOf(theme) ?? sun;
+    const themeMode = useThemeMode(chosenTheme(theme, debug ? debugState.themeChoice : null, sunEntity), instance);
     // Memoized: Emotion recomputes the merged theme (and every `css` prop) when the function changes.
     const withDensity = useMemo(() => (outer) => ({ ...outer, density: densityTokens(density, overrides) }), [density, overrides]);
     useGoogleFont(font);
@@ -197,7 +215,7 @@ export function HashsomeProvider({ url, client, clientOptions, theme = 'dark', m
         instance.connect();
         return () => instance.close();
     }, [instance]);
-    return (_jsx(HashsomeContext.Provider, { value: instance, children: _jsx(ThemeModeContext.Provider, { value: themeMode, children: _jsx(ThemeProvider, { theme: resolvedTheme, children: _jsxs(EmotionThemeProvider, { theme: withDensity, children: [_jsx(Global, { styles: globalStyles }), _jsxs(DetailProvider, { children: [children, _jsx(EntityDrawer, {})] })] }) }) }) }));
+    return (_jsx(HashsomeContext.Provider, { value: instance, children: _jsx(ThemeModeContext.Provider, { value: themeMode, children: _jsx(ThemeProvider, { theme: resolvedTheme, children: _jsxs(EmotionThemeProvider, { theme: withDensity, children: [_jsx(Global, { styles: globalStyles }), _jsx(DebugContext.Provider, { value: debugState, children: _jsxs(DetailProvider, { children: [children, _jsx(EntityDrawer, {}), debug ? _jsx(DebugMenu, { configured: theme, sun: sunEntity }) : null] }) })] }) }) }) }));
 }
 export function useClient() {
     const client = useContext(HashsomeContext);

package/dist/theme/grid.d.ts

@@ -0,0 +1,30 @@
+/** The icon badge a tile starts with, in px: the one size in a tile that does not scale with density. */
+export declare const BADGE = 32;
+/** The height of a room header, in px. */
+export declare const HEADER = 32;
+/** The height of the top row, in px: the clock's line and the tallest things beside it (the switcher, the
+ * scene buttons), with no padding of its own, so its content sits as far from the page's edge as
+ * everything else does. Sizes that do not scale with density are multiples of 8, so they are whole
+ * modules in both (4px and 2.67px). */
+export declare const TOP_ROW = 40;
+/** The vertical grid every card sits on. The module is the theme's spacing unit (a third of a
+ * space: 4px in comfortable density, 2.67px in compact), so the gap between cards is always 3
+ * modules, and a tile and a header are whole numbers of them in either density. Sizes are in px;
+ * `pitch` is a card's height plus the gap that follows it, and a card spanning n pitches is n heights
+ * and n-1 gaps tall. */
+export interface GridMetrics {
+    module: number;
+    gap: number;
+    tile: number;
+    header: number;
+    tilePitch: number;
+    headerPitch: number;
+}
+export declare function gridMetrics(space: number): GridMetrics;
+/** Whether a box's top edge, measured from the grid's origin, or its height is off the module grid. Browsers round to the pixel, so a little under a pixel is still on it. */
+export declare function offGrid(top: number, height: number, module: number): boolean;
+/** How a height's leftover (what is under one module after as many whole ones as fit) is shared between the top and the bottom padding: half each, in whole pixels, the odd one to the bottom. `available` is the height inside the page's padding. */
+export declare function centeringOffsets(available: number, module: number): {
+    top: number;
+    bottom: number;
+};

package/dist/theme/grid.js

@@ -0,0 +1,38 @@
+import { UNITS_PER_SPACE } from './density.js';
+/** The icon badge a tile starts with, in px: the one size in a tile that does not scale with density. */
+export const BADGE = 32;
+/** The height of a room header, in px. */
+export const HEADER = 32;
+/** The height of the top row, in px: the clock's line and the tallest things beside it (the switcher, the
+ * scene buttons), with no padding of its own, so its content sits as far from the page's edge as
+ * everything else does. Sizes that do not scale with density are multiples of 8, so they are whole
+ * modules in both (4px and 2.67px). */
+export const TOP_ROW = 40;
+export function gridMetrics(space) {
+    const module = space / UNITS_PER_SPACE;
+    // A tile is its badge between two spacing-unit-2 paddings.
+    const tile = BADGE + 4 * module;
+    return {
+        module,
+        gap: space,
+        tile,
+        header: HEADER,
+        tilePitch: tile + space,
+        headerPitch: HEADER + space,
+    };
+}
+/** Whether a box's top edge, measured from the grid's origin, or its height is off the module grid. Browsers round to the pixel, so a little under a pixel is still on it. */
+export function offGrid(top, height, module) {
+    const tolerance = Math.max(0.5, module * 0.15);
+    const off = (value) => {
+        const rest = Math.abs(value) % module;
+        return Math.min(rest, module - rest) > tolerance;
+    };
+    return off(top) || off(height);
+}
+/** How a height's leftover (what is under one module after as many whole ones as fit) is shared between the top and the bottom padding: half each, in whole pixels, the odd one to the bottom. `available` is the height inside the page's padding. */
+export function centeringOffsets(available, module) {
+    const leftover = available > 0 ? Math.floor(available % module) : 0;
+    const top = Math.floor(leftover / 2);
+    return { top, bottom: leftover - top };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashsome/ui",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Design system components and hooks",
   "type": "module",
   "exports": {
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "@emotion/react": "11.14.0",
-    "@hashsome/core": "0.5.0",
+    "@hashsome/core": "0.7.0",
     "e-prim": "2.0.1",
     "motion": "13.4.5",
     "react": "19.3.0",