@hashsome/ui 0.9.0 → 0.11.0

package/dist/entities/media-browser.js

@@ -18,6 +18,18 @@ import { useMediaBrowser } from '../use-media-browser.js';
 import { trackMedia, useMediaPending } from './media-pending.js';
 /** The height of the search field, and of the row of tabs it replaces. */
 const SEARCH_HEIGHT = 36;
+/** The name of each kind of thing a search finds, on the chip that narrows the results to it. */
+const KIND_LABELS = {
+    album: 'Albums',
+    artist: 'Artists',
+    track: 'Tracks',
+    playlist: 'Playlists',
+    radio: 'Radio',
+    folder: 'Folders',
+    other: 'Other',
+};
+/** The chip for every kind at once. */
+const ALL_KINDS = 'all';
 const KIND_ICONS = {
     folder: 'lu:folder',
     artist: 'lu:mic-vocal',
@@ -95,9 +107,23 @@ export function MediaBrowser({ entity, onPlay, layout = 'list', search: searchMo
                             }
                         },
                     }
-                    : {}), css: { background: 'none', outline: 'none' } }), onDemand ? (_jsx(PlainButton, { "aria-label": "Close search", title: "Close search", onClick: closeSearch, center: true, css: { flex: 'none' }, children: _jsx(Icon, { name: "lu:x", size: 16 }) })) : browser.query !== '' ? (_jsx(PlainButton, { "aria-label": "Clear search", title: "Clear search", onClick: () => browser.search(''), center: true, css: { flex: 'none' }, children: _jsx(Icon, { name: "lu:x", size: 16 }) })) : null] })) : null;
-    /** The categories (and, with `search='icon'`, the search icon at the end). */
-    const tabsRow = browser.tabs ? (_jsxs(Flex, { align: "center", gap: 3, ...(onDemand ? { minHeight: SEARCH_HEIGHT } : {}), children: [_jsx(Flex, { direction: "column", grow: 1, minWidth: 0, children: _jsx(ChipRow, { tabs: true, options: browser.tabs.map((item) => 
+                    : {}), css: {
+                    background: 'none',
+                    outline: 'none',
+                    // A search field gets a clear button of the browser's own in some browsers, and this one has its own
+                    // (and a button to close it), so the browser's is not drawn.
+                    '&::-webkit-search-cancel-button, &::-webkit-search-decoration': {
+                        WebkitAppearance: 'none',
+                        appearance: 'none',
+                        display: 'none',
+                    },
+                } }), onDemand ? (_jsx(PlainButton, { "aria-label": "Close search", title: "Close search", onClick: closeSearch, center: true, css: { flex: 'none' }, children: _jsx(Icon, { name: "lu:x", size: 16 }) })) : browser.query !== '' ? (_jsx(PlainButton, { "aria-label": "Clear search", title: "Clear search", onClick: () => browser.search(''), center: true, css: { flex: 'none' }, children: _jsx(Icon, { name: "lu:x", size: 16 }) })) : null] })) : null;
+    /** The categories (and, with `search='icon'`, the search icon at the end). While a search has results, the
+     * same row is the kinds to narrow it to: the shelves mean nothing to a search's results, which belong to none. */
+    const tabsRow = browser.tabs ? (_jsxs(Flex, { align: "center", gap: 3, ...(onDemand ? { minHeight: SEARCH_HEIGHT } : {}), children: [_jsx(Flex, { direction: "column", grow: 1, minWidth: 0, children: browser.searching && browser.kindsPending ? (_jsx(KindsSkeleton, {})) : browser.searching && browser.kinds ? (_jsx(ChipRow, { tabs: true, options: [
+                        { value: ALL_KINDS, label: 'All' },
+                        ...browser.kinds.map((kind) => ({ value: kind, label: KIND_LABELS[kind] })),
+                    ], value: browser.kind ?? ALL_KINDS, onChange: (id) => browser.filterBy(id === ALL_KINDS ? undefined : id) })) : (_jsx(ChipRow, { tabs: true, options: browser.tabs.map((item) => 
                     // Inside a shelf the selected tab becomes the way back, so nothing is added to the
                     // layout and nothing below it moves.
                     item.id === browser.activeTab && inside
@@ -107,11 +133,15 @@ export function MediaBrowser({ entity, onPlay, layout = 'list', search: searchMo
                             icon: 'lu:arrow-left',
                             ariaLabel: 'Back',
                         }
-                        : { value: item.id, label: item.title }), value: browser.activeTab, onChange: (id) => id === browser.activeTab && inside ? browser.back() : browser.selectTab(id) }) }), actionsHere, searchTrigger] })) : null;
+                        : { value: item.id, label: item.title }), value: browser.activeTab, onChange: (id) => id === browser.activeTab && inside ? browser.back() : browser.selectTab(id) })) }), actionsHere, searchTrigger] })) : null;
     return (_jsxs(Flex, { direction: "column", gap: 3, minHeight: 0, position: "relative", children: [onDemand ? (_jsx(AnimatePresence, { initial: false, mode: "popLayout", children: _jsx(motion.div, { initial: { opacity: 0, x: fieldShown ? 28 : 0 }, animate: { opacity: 1, x: 0 }, exit: { opacity: 0, x: fieldShown ? 0 : 28 }, transition: { duration: 0.18, ease: 'easeOut' }, children: fieldShown ? search : browser.tabs === undefined ? header : tabsRow }, fieldShown ? 'field' : 'row') })) : (_jsxs(_Fragment, { children: [browser.tabs === undefined ? header : null, search, tabsRow] })), browser.error ? (_jsx(Message, { theater: theater, children: _jsx(Typography, { as: "p", variant: "body", color: "danger", role: "alert", m: 0, children: browser.error }) })) : browser.loading ? (_jsx(BrowseSkeleton, { theater: theater })) : browser.items.length === 0 ? (_jsx(Message, { theater: theater, children: _jsx(Typography, { as: "p", variant: "body", color: "textMuted", m: 0, children: browser.searching ? 'Nothing found.' : 'Nothing here.' }) })) : theater ? (_jsx(FadeScroll, { as: "ul", gap: 4, m: 0, p: 0, pb: 2, css: { ...THEATER_STAGE, listStyle: 'none', scrollSnapType: 'x proximity' }, children: browser.items.map((item, index) => (_jsx("li", { css: { flex: 'none', scrollSnapAlign: 'start' }, children: _jsx(Reveal, { index: browser.searching ? 0 : index, children: _jsx(BrowseCard, { item: item, asked: askedOf(item), queueable: queueable, onOpen: () => browser.open(item), onPlay: () => play(item), onAdd: () => addToQueue(item) }) }) }, `${browser.listKey}:${item.id}`))) })) : (_jsx(Flex, { direction: "column", gap: 1, as: "ul", m: 0, p: 0, minHeight: 0, css: { listStyle: 'none', overflowY: 'auto' }, children: browser.items.map((item, index) => (_jsx("li", { css: { flex: 'none' }, children: _jsx(Reveal, { index: browser.searching ? 0 : index, children: _jsx(BrowseRow, { item: item, asked: askedOf(item), queueable: queueable, onOpen: () => browser.open(item), onPlay: () => play(item), onNext: () => playNext(item), onAdd: () => addToQueue(item) }) }) }, `${browser.listKey}:${item.id}`))) }))] }));
 }
 /** What shows where the list will be while it loads: placeholders shaped like what is coming (cards in
  * the theater layout, rows in the list), in the room the real thing takes, so nothing moves. */
+/** Where the kinds to narrow a search to will be, in the chips' own height, so the list below does not move. */
+function KindsSkeleton() {
+    return (_jsx(Flex, { gap: 2, "aria-busy": "true", css: { height: CHIP_HEIGHT }, children: [40, 78, 74, 70, 62].map((width) => (_jsx(Skeleton, { width: width, height: CHIP_HEIGHT, radius: "full" }, width))) }));
+}
 function BrowseSkeleton({ theater }) {
     return theater ? (_jsx(Flex, { as: "ul", role: "status", "aria-label": "Loading", "aria-busy": "true", gap: 4, m: 0, p: 0, pb: 2, css: { ...THEATER_STAGE, listStyle: 'none', overflow: 'hidden' }, children: Array.from({ length: 12 }, (_, index) => (_jsxs(Flex, { as: "li", direction: "column", gap: 2, css: { flex: 'none', width: CARD_SIZE }, children: [_jsx(Skeleton, { width: CARD_SIZE, height: CARD_SIZE, radius: "card" }), _jsxs(Flex, { direction: "column", gap: 1, px: 1, children: [_jsx(Skeleton, { width: "70%", height: 14 }), _jsx(Skeleton, { width: "45%", height: 12 })] })] }, index))) })) : (_jsx(Flex, { as: "ul", role: "status", "aria-label": "Loading", "aria-busy": "true", direction: "column", gap: 1, m: 0, p: 0, css: { listStyle: 'none' }, children: Array.from({ length: 6 }, (_, index) => (_jsxs(Flex, { as: "li", align: "center", gap: 3, py: 1.5, px: 2, children: [_jsx(Skeleton, { width: 44, height: 44 }), _jsxs(Flex, { direction: "column", gap: 1.5, grow: 1, children: [_jsx(Skeleton, { width: "60%", height: 14 }), _jsx(Skeleton, { width: "35%", height: 12 })] })] }, index))) }));
 }

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/debug-menu.js

@@ -85,6 +85,9 @@ export function DebugMenu({ configured, sun, }) {
     };
     const theme = debug.themeChoice ?? configuredChoice(configured);
     return (_jsxs(Flex, { ref: root, "data-debug-menu": true, 
+        // Over the page and its navigation but under a drawer and its scrim, so opening a drawer covers it
+        // instead of leaving it floating over the drawer.
+        zIndex: "dropdown", 
         // 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.
@@ -92,7 +95,6 @@ export function DebugMenu({ configured, sun, }) {
             position: 'fixed',
             left: INSET,
             bottom: INSET,
-            zIndex: 30,
             width: BUTTON,
             height: BUTTON,
             minHeight: 0,

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/dist/use-media-browser.d.ts

@@ -1,4 +1,4 @@
-import type { BrowseItem, EntityRef } from '@hashsome/core';
+import type { BrowseItem, BrowseKind, EntityRef } from '@hashsome/core';
 export interface MediaBrowserState {
     /** What is listed now. */
     items: BrowseItem[];
@@ -27,6 +27,14 @@ export interface MediaBrowserState {
     query: string;
     /** Lists what matches `text`; an empty string goes back to where the browser was. */
     search(text: string): void;
+    /** The kinds of thing the search found (albums, playlists…), when it found any, so there is something to narrow it to (to a lone kind too, which brings far more of it than the mixed list); in a fixed order. Absent when not searching. While another search is on its way these are the last one's, so what is shown does not flicker as someone types. */
+    kinds: BrowseKind[] | undefined;
+    /** Searching, with no kinds to show yet (the first answer has not come) and nothing from an earlier search to show instead: a placeholder for them. */
+    kindsPending: boolean;
+    /** The kind the results are narrowed to; absent for all of them. */
+    kind: BrowseKind | undefined;
+    /** Narrows the search results to one kind, which asks for more of it than the mixed list has, or back to all of them. */
+    filterBy(kind: BrowseKind | undefined): void;
 }
 /** Walks a player's own media library through the runtime. The top level is read once: shelves
  * become tabs (the first is open to begin with), anything else is a plain list. Below it, a stack

package/dist/use-media-browser.js

@@ -1,6 +1,18 @@
 import { useCallback, useEffect, useState } from 'react';
 import { useReconnects } from './hooks.js';
 import { useClient } from './provider.js';
+/** The order the kinds of a search result are offered in: what is played most, first. */
+const KIND_ORDER = [
+    'track',
+    'playlist',
+    'album',
+    'artist',
+    'radio',
+    'folder',
+    'other',
+];
+/** The kinds among some items, in the order they are offered. */
+const kindsOf = (items) => KIND_ORDER.filter((candidate) => items.some((item) => item.kind === candidate));
 /** A top level that is nothing but folders to look inside is a set of shelves, which read better
  * as tabs than as a list that always looks the same. */
 const isShelves = (items) => items.length >= 2 && items.every((item) => item.expandable && !item.playable);
@@ -16,6 +28,12 @@ export function useMediaBrowser(ref) {
     const [trail, setTrail] = useState([{}]);
     const [text, setText] = useState('');
     const [tab, setTab] = useState();
+    // The kind of result chosen to narrow a search to; only counts while that kind is among the results.
+    const [kindChoice, setKindChoice] = useState();
+    // The search with no kind chosen: it says which kinds there are, and is the list while none is chosen.
+    const [overview, setOverview] = useState(null);
+    // The kinds the last answered search found, kept while the next one is on its way.
+    const [lastKinds, setLastKinds] = useState();
     // Answers are kept with the request they answer, so a stale one is never shown for a new one.
     const [top, setTop] = useState(null);
     const [answer, setAnswer] = useState(null);
@@ -34,13 +52,49 @@ export function useMediaBrowser(ref) {
     const atTop = trail.length === 1;
     const tabs = top && !top.error && isShelves(top.items) ? top.items : undefined;
     const selected = tabs ? (tabs.find((item) => item.id === tab) ?? tabs[0])?.id : undefined;
-    // What to ask for, if anything: a search, a folder, or the open tab. A top level that is not
-    // shelves is already in hand.
+    // The kinds the search found, once it has answered, and the one chosen if it is among them.
+    const overviewKey = `search:${needle}`;
+    const found = searching && overview?.key === overviewKey ? overview : null;
+    const foundKinds = found ? kindsOf(found.items) : undefined;
+    if (!searching && lastKinds !== undefined) {
+        setLastKinds(undefined);
+    }
+    // What to offer: this search's kinds once they are in, the last search's until then.
+    const kinds = searching ? (foundKinds ?? lastKinds) : undefined;
+    const kind = kinds && kindChoice !== undefined && kinds.includes(kindChoice) ? kindChoice : undefined;
+    // What to ask for, if anything: a folder, the open tab, or one kind of a search's results. A top level
+    // that is not shelves is already in hand, and so is the search with no kind chosen.
     const path = atTop ? selected : here.path;
-    const key = searching ? `search:${needle}` : `path:${path ?? ''}`;
+    const key = searching ? `search:${needle}:${kind ?? ''}` : `path:${path ?? ''}`;
     const result = answer?.key === key ? answer : null;
+    // The search with no kind chosen, always: its kinds are the choices, whichever one is showing.
     useEffect(() => {
-        const request = searching ? { search: needle } : path === undefined ? undefined : { path };
+        if (!searching) {
+            return;
+        }
+        let current = true;
+        const timer = setTimeout(() => {
+            client.browse(ref, { search: needle }).then((level) => {
+                if (current) {
+                    setOverview({ key: `search:${needle}`, ...level });
+                    setLastKinds(kindsOf(level.items));
+                }
+            }, (error) => current && setOverview({ key: `search:${needle}`, items: [], error: messageOf(error) }));
+        }, 300);
+        return () => {
+            current = false;
+            clearTimeout(timer);
+        };
+        // oxlint-disable-next-line react/exhaustive-effect-dependencies
+    }, [client, ref, searching, needle, reconnects]);
+    useEffect(() => {
+        const request = searching && kind
+            ? { search: needle, kind }
+            : searching
+                ? undefined
+                : path === undefined
+                    ? undefined
+                    : { path };
         if (!request) {
             return;
         }
@@ -48,18 +102,33 @@ export function useMediaBrowser(ref) {
         const timer = setTimeout(() => {
             client.browse(ref, request).then((level) => current && setAnswer({ key, ...level }), (error) => current && setAnswer({ key, items: [], error: messageOf(error) }));
         }, 
-        // Typing in the search box waits for a pause; opening a folder or a tab does not.
-        searching ? 300 : 0);
+        // Typing in the search box waits for a pause; opening a folder or a tab or choosing a kind does not.
+        0);
         return () => {
             current = false;
             clearTimeout(timer);
         };
         // oxlint-disable-next-line react/exhaustive-effect-dependencies
-    }, [client, ref, key, searching, needle, path, reconnects]);
-    const open = useCallback((item) => setTrail((levels) => [...levels, { path: item.id, title: item.title, item }]), []);
+    }, [client, ref, key, searching, needle, kind, path, reconnects]);
+    // Opening what a search found (an album, a playlist) shows it in place of the results: the search steps
+    // aside, and going back from it returns to the results.
+    const open = useCallback((item) => {
+        const from = text.trim();
+        setTrail((levels) => [
+            ...levels,
+            {
+                path: item.id,
+                title: item.title,
+                item,
+                ...(from !== '' ? { from: { text: from, kind } } : {}),
+            },
+        ]);
+        setText('');
+    }, [text, kind]);
     const selectTab = useCallback((id) => {
         setTab(id);
         setText('');
+        setKindChoice(undefined);
         setTrail([{}]);
     }, []);
     const back = useCallback(() => {
@@ -67,13 +136,18 @@ export function useMediaBrowser(ref) {
             setText('');
             return;
         }
+        const left = trail.at(-1);
         setTrail((levels) => (levels.length > 1 ? levels.slice(0, -1) : levels));
-    }, [text]);
+        if (trail.length > 1 && left?.from !== undefined) {
+            setText(left.from.text);
+            setKindChoice(left.from.kind);
+        }
+    }, [text, trail]);
     // The plain top-level list, when there are no shelves to make tabs of.
-    const listing = !searching && atTop && !tabs ? top : result;
+    const listing = searching && !kind ? found : !searching && atTop && !tabs ? top : result;
     return {
         items: listing?.items ?? [],
-        listKey: searching ? 'search' : `path:${path ?? 'top'}`,
+        listKey: searching ? `search:${kind ?? ''}` : `path:${path ?? 'top'}`,
         title: searching
             ? (result?.title ?? `Results for “${needle}”`)
             : atTop
@@ -91,5 +165,9 @@ export function useMediaBrowser(ref) {
         back,
         query: text,
         search: setText,
+        kinds: kinds && kinds.length >= 1 ? kinds : undefined,
+        kindsPending: searching && foundKinds === undefined && !(lastKinds && lastKinds.length >= 1),
+        kind,
+        filterBy: setKindChoice,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashsome/ui",
-  "version": "0.9.0",
+  "version": "0.11.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.11.0",
     "e-prim": "2.0.1",
     "motion": "13.4.5",
     "react": "19.3.0",