@hashsome/ui 0.9.0 → 0.10.0

package/dist/entities/nav-dock.d.ts

@@ -1,4 +1,4 @@
-import type { NavItem } from './nav-rail.tsx';
+import { type NavItem } from './nav-rail.tsx';
 export interface NavDockProps {
     /** The pages to link to; `to` is relative to `base`. */
     items: NavItem[];
@@ -6,8 +6,10 @@ export interface NavDockProps {
     base: string;
     /** Adds a light/dark toggle at the end of the dock. Off by default — meant for development or a project that deliberately exposes it, not every kiosk install. */
     showThemeToggle?: boolean;
+    /** How long, in ms, the display may be left alone on a page other than the main one (the item whose `to` is `''`) before it goes back to that page; `false` for never. Any touch, click, key or scroll starts the time again. Defaults to `HashsomeProvider`'s `idleReturn`, which is off unless the app turns it on. */
+    idleReturn?: number | false;
 }
 /** Floating bottom pill for switching between a dashboard's pages. Must be rendered inside a
  * router. `position: fixed`, floating over the page; it reserves the space it takes in the
  * surrounding `Page`, which pads for it. */
-export declare function NavDock({ items, base, showThemeToggle }: NavDockProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare function NavDock({ items, base, showThemeToggle, idleReturn }: NavDockProps): import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/entities/nav-dock.js

@@ -5,11 +5,15 @@ import { NavLink } from 'react-router';
 import { Icon } from '../icon.js';
 import { usePageInset } from '../layout/page.js';
 import { AttentionDot } from './attention-dot.js';
+import { useIdleReturn, useIdleReturnDefault } from '../layout/use-idle-return.js';
+import { mainPath } from './nav-rail.js';
 import { useThemeToggle } from '../provider.js';
 /** Floating bottom pill for switching between a dashboard's pages. Must be rendered inside a
  * router. `position: fixed`, floating over the page; it reserves the space it takes in the
  * surrounding `Page`, which pads for it. */
-export function NavDock({ items, base, showThemeToggle }) {
+export function NavDock({ items, base, showThemeToggle, idleReturn }) {
+    const appDefault = useIdleReturnDefault();
+    useIdleReturn({ to: mainPath(items, base), after: idleReturn ?? appDefault });
     usePageInset('bottom', 88);
     return (_jsxs(Flex, { as: "nav", "aria-label": "Pages", align: "center", gap: 1.5, background: "rail", radius: "full", p: 1.5, shadow: "dock", position: "fixed", css: ({ spacing }) => ({
             bottom: spacing(5),

package/dist/entities/nav-rail.d.ts

@@ -7,6 +7,8 @@ export interface NavItem {
     /** A dot on the item for something on that page that needs a look: `notice` (warm) or `urgent` (red). Nothing by default. */
     attention?: 'notice' | 'urgent';
 }
+/** The path of a dashboard's main page: the item with no path of its own, else its first item. */
+export declare function mainPath(items: NavItem[], base: string): string;
 export interface NavRailProps {
     /** The pages to link to; `to` is relative to `base`. */
     items: NavItem[];
@@ -14,8 +16,10 @@ export interface NavRailProps {
     base: string;
     /** Adds a light/dark toggle at the bottom of the rail. Off by default — meant for development or a project that deliberately exposes it, not every kiosk install. */
     showThemeToggle?: boolean;
+    /** How long, in ms, the display may be left alone on a page other than the main one (the item whose `to` is `''`) before it goes back to that page; `false` for never. Any touch, click, key or scroll starts the time again. Defaults to `HashsomeProvider`'s `idleReturn`, which is off unless the app turns it on. */
+    idleReturn?: number | false;
 }
 /** Fixed left sidebar for switching between a dashboard's pages. Must be rendered inside a
  * router. It is `position: fixed` and reserves its width in the surrounding `Page`, which pads
  * for it so content never sits under it. */
-export declare function NavRail({ items, base, showThemeToggle }: NavRailProps): import("@emotion/react/jsx-runtime").JSX.Element;
+export declare function NavRail({ items, base, showThemeToggle, idleReturn }: NavRailProps): import("@emotion/react/jsx-runtime").JSX.Element;

package/dist/entities/nav-rail.js

@@ -7,10 +7,18 @@ import { usePageInset } from '../layout/page.js';
 import { useThemeToggle } from '../provider.js';
 import { NAV_RAIL } from '../theme/grid.js';
 import { AttentionDot } from './attention-dot.js';
+import { useIdleReturn, useIdleReturnDefault } from '../layout/use-idle-return.js';
+/** The path of a dashboard's main page: the item with no path of its own, else its first item. */
+export function mainPath(items, base) {
+    const main = items.find((item) => item.to === '') ?? items[0];
+    return main?.to ? `${base}/${main.to}` : base;
+}
 /** Fixed left sidebar for switching between a dashboard's pages. Must be rendered inside a
  * router. It is `position: fixed` and reserves its width in the surrounding `Page`, which pads
  * for it so content never sits under it. */
-export function NavRail({ items, base, showThemeToggle }) {
+export function NavRail({ items, base, showThemeToggle, idleReturn }) {
+    const appDefault = useIdleReturnDefault();
+    useIdleReturn({ to: mainPath(items, base), after: idleReturn ?? appDefault });
     usePageInset('left', NAV_RAIL);
     return (_jsxs(Flex, { as: "nav", "aria-label": "Pages", direction: "column", align: "center", gap: 2.5, background: "rail", width: NAV_RAIL, py: 6, position: "fixed", zIndex: "nav", css: { top: 0, bottom: 0, left: 0 }, children: [items.map((item) => (_jsx(NavLink, { to: item.to ? `${base}/${item.to}` : base, end: true, "aria-label": item.attention ? `${item.label}, needs attention` : item.label, title: item.label, children: ({ isActive }) => (_jsxs(Flex, { as: "span", align: "center", justify: "center", width: 44, height: 44, radius: "chrome", cursor: "pointer", position: "relative", color: isActive ? 'accentText' : 'line', ...(isActive ? { background: 'accent' } : {}), children: [_jsx(Icon, { name: item.icon, size: 22 }), item.attention ? _jsx(AttentionDot, { level: item.attention }) : null] })) }, item.to))), showThemeToggle ? _jsx(ThemeToggleButton, {}) : null] }));
 }

package/dist/gallery/props-data.js

@@ -824,6 +824,12 @@ export const COMPONENT_PROPS = {
                 optional: true,
                 type: 'boolean',
             },
+            {
+                doc: "How long, in ms, the display may be left alone on a page other than the main one (the item whose `to` is `''`) before it goes back to that page; `false` for never. Any touch, click, key or scroll starts the time again. Defaults to `HashsomeProvider`'s `idleReturn`, which is off unless the app turns it on.",
+                name: 'idleReturn',
+                optional: true,
+                type: 'number | false',
+            },
         ],
     },
     NavDock: {
@@ -847,6 +853,12 @@ export const COMPONENT_PROPS = {
                 optional: true,
                 type: 'boolean',
             },
+            {
+                doc: "How long, in ms, the display may be left alone on a page other than the main one (the item whose `to` is `''`) before it goes back to that page; `false` for never. Any touch, click, key or scroll starts the time again. Defaults to `HashsomeProvider`'s `idleReturn`, which is off unless the app turns it on.",
+                name: 'idleReturn',
+                optional: true,
+                type: 'number | false',
+            },
         ],
     },
     TopBar: {
@@ -1078,6 +1090,12 @@ export const COMPONENT_PROPS = {
                 optional: true,
                 type: 'EntityRef',
             },
+            {
+                doc: "How long, in ms, a display is left alone on a dashboard's page other than its main one before it goes back to the main page, so a wall display does not stay on the music page for hours. Any touch, click, key or scroll starts the time again, and the main page itself is left alone. It is done by the dashboard's `NavRail` or `NavDock`, which can set their own `idleReturn` (a time, or `false`) over this. Default `false`: off.",
+                name: 'idleReturn',
+                optional: true,
+                type: 'number | false',
+            },
             {
                 doc: 'The app.',
                 name: 'children',

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * from './layout/page.tsx';
 export * from './layout/animated-outlet.tsx';
 export * from './layout/room-header.tsx';
 export { Tile, type TileProps } from './layout/tile.tsx';
+export { useIdleReturn } from './layout/use-idle-return.ts';
 export { TaskTile, taskLine, type TaskState, type TaskTileProps } from './layout/task-tile.tsx';
 export { ConfirmDialog, type ConfirmDialogProps } from './layout/confirm-dialog.tsx';
 export * from './layout/energy-chart.tsx';

package/dist/index.js

@@ -11,6 +11,7 @@ export * from './layout/page.js';
 export * from './layout/animated-outlet.js';
 export * from './layout/room-header.js';
 export { Tile } from './layout/tile.js';
+export { useIdleReturn } from './layout/use-idle-return.js';
 export { TaskTile, taskLine } from './layout/task-tile.js';
 export { ConfirmDialog } from './layout/confirm-dialog.js';
 export * from './layout/energy-chart.js';

package/dist/layout/use-idle-return.d.ts

@@ -0,0 +1,22 @@
+/** The app-wide time a display is left alone before it goes back to a dashboard's main page, set by
+ * `HashsomeProvider`'s `idleReturn`. `false`: it does not. */
+export declare const IdleReturnContext: import("react").Context<number | false>;
+/** Whether it is time to go back: nothing has been touched for `after`. */
+export declare function shouldLeave(now: number, lastTouched: number, after: number): boolean;
+/** The app's own setting for how long a display is left alone before it goes back to a main page: what
+ * `HashsomeProvider`'s `idleReturn` says, `false` when it says nothing. */
+export declare function useIdleReturnDefault(): number | false;
+/**
+ * Takes a wall display back to `to` (a dashboard's main page) once nobody has touched it for `after` ms,
+ * so that a page opened for a while (a music page, say) does not stay up for hours. Any touch, click, key
+ * or scroll anywhere starts the time again; it is counted from arriving on a page that is not `to`, and
+ * on `to` itself nothing happens. The page it leaves replaces itself in the history, so the back button does
+ * not return to it. `false` (or no time) turns it off.
+ *
+ * `NavRail` and `NavDock` do this for the dashboard they are in (see their `idleReturn`); use the hook
+ * directly for a dashboard that builds its own navigation.
+ */
+export declare function useIdleReturn({ to, after }: {
+    to: string;
+    after: number | false | undefined;
+}): void;

package/dist/layout/use-idle-return.js

@@ -0,0 +1,66 @@
+import { createContext, useContext, useEffect, useRef } from 'react';
+import { useLocation, useNavigate } from 'react-router';
+/** The app-wide time a display is left alone before it goes back to a dashboard's main page, set by
+ * `HashsomeProvider`'s `idleReturn`. `false`: it does not. */
+export const IdleReturnContext = createContext(false);
+/** How often the page checks whether it has been left alone long enough, at most. */
+const CHECK_MS = 10_000;
+/** What counts as someone being there: a touch or a click, a key, a scroll or a wheel anywhere on the page. */
+const INTERACTIONS = [
+    'pointerdown',
+    'pointermove',
+    'keydown',
+    'wheel',
+    'touchstart',
+    'scroll',
+];
+/** Whether it is time to go back: nothing has been touched for `after`. */
+export function shouldLeave(now, lastTouched, after) {
+    return now - lastTouched >= after;
+}
+/** The app's own setting for how long a display is left alone before it goes back to a main page: what
+ * `HashsomeProvider`'s `idleReturn` says, `false` when it says nothing. */
+export function useIdleReturnDefault() {
+    return useContext(IdleReturnContext);
+}
+/**
+ * Takes a wall display back to `to` (a dashboard's main page) once nobody has touched it for `after` ms,
+ * so that a page opened for a while (a music page, say) does not stay up for hours. Any touch, click, key
+ * or scroll anywhere starts the time again; it is counted from arriving on a page that is not `to`, and
+ * on `to` itself nothing happens. The page it leaves replaces itself in the history, so the back button does
+ * not return to it. `false` (or no time) turns it off.
+ *
+ * `NavRail` and `NavDock` do this for the dashboard they are in (see their `idleReturn`); use the hook
+ * directly for a dashboard that builds its own navigation.
+ */
+export function useIdleReturn({ to, after }) {
+    const navigate = useNavigate();
+    const { pathname } = useLocation();
+    // Set when the time starts, in the effect below.
+    const lastTouched = useRef(0);
+    const enabled = typeof after === 'number' && after > 0;
+    const away = pathname.replace(/\/$/, '') !== to.replace(/\/$/, '');
+    useEffect(() => {
+        if (!enabled || !away) {
+            return;
+        }
+        lastTouched.current = Date.now();
+        const touched = () => {
+            lastTouched.current = Date.now();
+        };
+        for (const name of INTERACTIONS) {
+            window.addEventListener(name, touched, { passive: true, capture: true });
+        }
+        const check = setInterval(() => {
+            if (shouldLeave(Date.now(), lastTouched.current, after)) {
+                navigate(to, { replace: true });
+            }
+        }, Math.min(CHECK_MS, after / 2));
+        return () => {
+            for (const name of INTERACTIONS) {
+                window.removeEventListener(name, touched, { capture: true });
+            }
+            clearInterval(check);
+        };
+    }, [enabled, away, after, to, navigate]);
+}

package/dist/provider.d.ts

@@ -29,6 +29,8 @@ export interface HashsomeProviderProps {
     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;
+    /** How long, in ms, a display is left alone on a dashboard's page other than its main one before it goes back to the main page, so a wall display does not stay on the music page for hours. Any touch, click, key or scroll starts the time again, and the main page itself is left alone. It is done by the dashboard's `NavRail` or `NavDock`, which can set their own `idleReturn` (a time, or `false`) over this. Default `false`: off. */
+    idleReturn?: number | false;
     /** The app. */
     children: ReactNode;
 }
@@ -44,5 +46,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, debug, sun, children, }: HashsomeProviderProps): import("react").JSX.Element;
+export declare function HashsomeProvider({ url, client, clientOptions, theme, motion, font, density, overrides, debug, sun, idleReturn, children, }: HashsomeProviderProps): import("react").JSX.Element;
 export declare function useClient(): Client;

package/dist/provider.js

@@ -8,6 +8,7 @@ import { DebugContext, debugFromEnv, useDebugState, useFullscreenKept, } from '.
 import { DebugMenu } from './layout/debug-menu.js';
 import { DetailProvider } from './layout/detail-provider.js';
 import { EntityDrawer } from './layout/entity-drawer.js';
+import { IdleReturnContext } from './layout/use-idle-return.js';
 import { UNITS_PER_SPACE } from './theme/density.js';
 import { globalStyles } from './theme/global-styles.js';
 import { applyThemeOverrides, densityTokens } from './theme/overrides.js';
@@ -195,7 +196,7 @@ 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, debug = debugFromEnv(), sun, children, }) {
+export function HashsomeProvider({ url, client, clientOptions, theme = 'dark', motion = 'auto', font = DEFAULT_FONT, density = 'comfortable', overrides, debug = debugFromEnv(), sun, idleReturn = false, children, }) {
     const instance = useMemo(() => client ?? new RemoteClient({ url: url ?? defaultUrl(), ...clientOptions }), [client, url, clientOptions]);
     useMotionMode(motion);
     const debugState = useDebugState();
@@ -215,7 +216,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 }), _jsx(DebugContext.Provider, { value: debugState, children: _jsxs(DetailProvider, { children: [children, _jsx(EntityDrawer, {}), debug ? _jsx(DebugMenu, { configured: theme, sun: sunEntity }) : null] }) })] }) }) }) }));
+    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: _jsx(IdleReturnContext.Provider, { value: idleReturn, children: _jsxs(DetailProvider, { children: [children, _jsx(EntityDrawer, {}), debug ? _jsx(DebugMenu, { configured: theme, sun: sunEntity }) : null] }) }) })] }) }) }) }));
 }
 export function useClient() {
     const client = useContext(HashsomeContext);

package/package.json

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