@x-tech-laboratories/x-libs 0.8.0 → 0.9.0

package/README.md

@@ -33,13 +33,14 @@ Code the X-apps share, published as one npm package, `@x-tech-laboratories/x-lib
 | `web/prefs`, `web/react/prefs`           | Remembered view settings that read as their default when stored corrupt, stale or of the wrong shape; `use_pref` keeps one as component state. |
 | `web/selection`, `web/virtual`, `web/drag` | Picking rows with plain, Ctrl and Shift clicks from a fixed anchor, or as lists of ids with the anchor kept by id, the row an arrow or page key moves to; which rows of a long list a viewport needs; a badge such as "3 tasks" as the drag image. |
 | `web/react/shell`                        | `Shell`: top bar, section links or the app's own sidebar in a `.sidebar-content` box, resizable, theme button, a `status_bar` at the foot, toasts, dialogs and menus, with or without logins (no account UI without a `user`, `logged_out` hiding the sidebar and tools), its phone menu held by the Shell or the app; `use_route`. |
-| `web/react/layout`, `badges`, `states`   | Panels, facts, tiles, cards, tabs, crumbs, steppers, settings rows, `RowActions` and `moved` for ordered lists, `SelectionBar` for picked rows; badges and chips; `use_resource` and its loading states. |
+| `web/react/layout`, `badges`, `states`   | `PageHeading` with a subtitle, icon, banner and actions; panels, facts, tiles, cards, tabs, crumbs, steppers, settings rows, `RowActions` and `moved` for ordered lists, `SelectionBar` for picked rows; badges and chips; `use_resource` with its `status` (idle until `enabled`, loading, loaded, failed), a `watch` that reloads it quietly, and its loading states, `Loaded` taking an `idle` slot. |
 | `web/react/time`                         | `Age`: a time as how long ago, with the full stamp on hover; `use_now`, the time read again each minute. |
 | `web/react/reveal`                       | `use_reveal`: a long list shown a page at a time, the next page added as its end scrolls into view, starting from the count shown before the page was left if given. |
 | `web/react/media`                        | `Avatar`, a round picture or the name's first letter; `MediaTile` and `MediaGrid`: videos, albums or playlists as tiles in a grid or as rows, with text over the picture's corner such as a length, lines under the title, a faded look, and buttons in the corner. |
-| `web/react/menu_button`                  | `MenuButton`: a ⋮ button that opens a menu under itself, even inside a link. |
+| `web/react/menu_button`                  | `MenuButton`: a ⋮ button that opens a menu under itself, even inside a link, saying through `aria-expanded` whether it is open. |
+| `web/react/test_stubs`                   | Stands in for `showPopover`, `hidePopover`, `showModal` and `close`, which jsdom lacks; an app's widget tests import it for its side effects. |
 | `web/react/list_picker`                  | `pick_list_dialog`: adds one thing to any of the app's lists, such as a video to playlists, ticking the lists that hold it and making a new one. |
-| `web/react/controls`, `table`            | Segmented choices, button groups, switches, search boxes that can take focus and follow a value cleared from outside, selects, `CommitInput`, `DateTimeField`, `ColorPicker`, `TreeSelect`; `DataTable` on TanStack Table, sorting by several columns, with columns to move, resize, hide and filter, tree rows, groups under headings, rows the app drags and styles, rows that come sorted from a database, rows worked by keyboard, rows that draw again only when they change, `virtual` rows drawn only where they show, a last column that fills the room left, group headings that hide when the filter empties them, and cards on phones; a pager. |
+| `web/react/controls`, `table`            | Segmented choices, button groups, switches, search boxes that hand on typing as it pauses, submit on Enter or a button, clear on Escape, can take a paste whole, take focus and follow a value cleared from outside, selects, `CommitInput`, `DateTimeField`, `ColorPicker`, `TreeSelect`; `DataTable` on TanStack Table, sorting by several columns, with columns to move, resize, hide and filter, tree rows, groups under headings, rows the app drags and styles, rows that come sorted from a database, rows worked by keyboard, rows that draw again only when they change, `virtual` rows drawn only where they show, a last column that fills the room left, group headings that hide when the filter empties them, and cards on phones; a pager. |
 | `web/react/shortcuts`                    | `use_shortcuts` for keys such as `"mod+z"`, quiet while typing or while a dialog or popover is open; `describe_keys` for help text. |
 | `web/react/tree`                         | `Tree`: nested rows that fold, walk with the arrow keys, reorder by dragging or with Alt and the arrow keys, show several picked, and take drops from outside. |
 | `web/react/toasts`, `dialog`, `menus`, `split` | Toasts with a link or Undo that say how they closed, and `undoable` actions that commit or undo exactly once; modal dialogs with a subtitle, header actions, a full-window size and a `form` whose submit button sends it, and confirm and text dialogs, openable from anywhere; context menus and popovers worked by keyboard, openable from anywhere, their keep-open items ticking at once; resize handles and splits. |

package/dist/web/react/controls.d.ts

@@ -25,10 +25,14 @@ export declare function Switch({ label, checked, on_change, disabled }: SwitchPr
 interface SearchBoxProps {
     label: string;
     value: string;
-    on_input: (value: string) => void;
+    on_input?: (value: string) => void;
+    on_submit?: (value: string) => void;
+    on_paste?: (text: string) => boolean;
+    submit_label?: string;
+    clear_on_submit?: boolean;
     auto_focus?: boolean;
 }
-export declare function SearchBox({ label, value, on_input, auto_focus }: SearchBoxProps): import("react").JSX.Element;
+export declare function SearchBox({ label, value, on_input, on_submit, on_paste, submit_label, clear_on_submit, auto_focus }: SearchBoxProps): import("react").JSX.Element;
 interface SelectProps<Value extends string | number> {
     label: string;
     options: [value: Value, text: string][];

package/dist/web/react/controls.js

@@ -31,27 +31,76 @@ export function Switch({ label, checked, on_change, disabled = false }) {
     }
     return _jsx("input", { type: "checkbox", role: "switch", "aria-label": label, checked: checked, disabled: disabled || busy, onChange: change });
 }
-// A search field that hands on what was typed once typing pauses; the field keeps its own text, so a redraw never wipes typing, and shows a value changed from outside, such as one cleared.
-export function SearchBox({ label, value, on_input, auto_focus = false }) {
+// A search field that hands on what was typed once typing pauses and submits it on Enter; Escape clears it; the field keeps its own text, so a redraw never wipes typing, and shows a value changed from outside, such as one cleared.
+export function SearchBox({ label, value, on_input, on_submit, on_paste, submit_label, clear_on_submit = false, auto_focus = false }) {
     const field = useRef(null);
     const timer = useRef(undefined);
     const handed_on = useRef(value);
+    const submitted = useRef(value);
     useEffect(() => () => clearTimeout(timer.current), []);
     useEffect(() => {
         if (value === handed_on.current || !field.current)
             return;
         clearTimeout(timer.current);
         handed_on.current = value;
+        submitted.current = value;
         field.current.value = value;
     }, [value]);
-    return (_jsx("input", { ref: field, type: "search", className: "filter", placeholder: label, "aria-label": label, defaultValue: value, autoFocus: auto_focus, onChange: (event) => {
-            clearTimeout(timer.current);
-            const text = event.currentTarget.value;
-            timer.current = window.setTimeout(() => {
-                handed_on.current = text;
-                on_input(text);
-            }, 200);
-        } }));
+    function hand_on(text) {
+        clearTimeout(timer.current);
+        if (text === handed_on.current)
+            return;
+        handed_on.current = text;
+        on_input?.(text);
+    }
+    function submit() {
+        const text = field.current?.value ?? "";
+        hand_on(text);
+        submitted.current = clear_on_submit ? "" : text;
+        on_submit?.(text);
+        if (clear_on_submit && field.current) {
+            field.current.value = "";
+            handed_on.current = "";
+        }
+    }
+    function clear() {
+        if (!field.current)
+            return;
+        field.current.value = "";
+        hand_on("");
+        if (submitted.current !== "") {
+            submitted.current = "";
+            on_submit?.("");
+        }
+    }
+    function typed(event) {
+        clearTimeout(timer.current);
+        const text = event.currentTarget.value;
+        // An emptied field goes straight back to everything, taking back what was submitted.
+        if (text === "")
+            return clear();
+        if (!on_input)
+            return;
+        timer.current = window.setTimeout(() => hand_on(text), 200);
+    }
+    function keyed(event) {
+        if (event.key === "Enter") {
+            event.preventDefault();
+            submit();
+        }
+        else if (event.key === "Escape" && event.currentTarget.value !== "") {
+            event.preventDefault();
+            clear();
+        }
+    }
+    function pasted(event) {
+        if (on_paste?.(event.clipboardData.getData("text")))
+            event.preventDefault();
+    }
+    const input = (_jsx("input", { ref: field, type: "search", className: "filter", placeholder: label, "aria-label": label, defaultValue: value, autoFocus: auto_focus, onChange: typed, onKeyDown: keyed, onPaste: on_paste && pasted }));
+    if (!submit_label)
+        return input;
+    return (_jsxs("form", { className: "search-box", role: "search", onSubmit: (event) => { event.preventDefault(); submit(); }, children: [input, _jsx("button", { type: "submit", className: "accent solid", children: submit_label })] }));
 }
 export function Select({ label, options, value, on_change, bare = false }) {
     const change = (event) => {

package/dist/web/react/layout.d.ts

@@ -1,6 +1,16 @@
 import { type MouseEvent, type ReactNode } from "react";
 import type { Tone } from "./badges.tsx";
 export { moved } from "../tables.ts";
+interface PageHeadingProps {
+    title: ReactNode;
+    subtitle?: ReactNode;
+    icon?: ReactNode;
+    banner?: string | ReactNode;
+    actions?: ReactNode;
+    class_name?: string;
+    children?: ReactNode;
+}
+export declare function PageHeading({ title, subtitle, icon, banner, actions, class_name, children }: PageHeadingProps): import("react").JSX.Element;
 interface SectionProps {
     title: ReactNode;
     tools?: ReactNode;

package/dist/web/react/layout.js

@@ -1,7 +1,11 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// The pieces a page is laid out with: panels, facts, tiles, cards, tabs, breadcrumbs, toolbars, steppers, settings rows and list row buttons.
+// The pieces a page is laid out with: the page heading, panels, facts, tiles, cards, tabs, breadcrumbs, toolbars, steppers, settings rows and list row buttons.
 import { Fragment } from "react";
 export { moved } from "../tables.js";
+// A page's heading: an optional banner, the title with its icon and subtitle, and the page's buttons.
+export function PageHeading({ title, subtitle, icon, banner, actions, class_name, children }) {
+    return (_jsxs("header", { className: class_name ? `page-head ${class_name}` : "page-head", children: [typeof banner === "string" ? _jsx("img", { className: "page-banner", src: banner, alt: "", loading: "lazy" }) : banner, _jsxs("div", { className: "page-title spread", children: [_jsxs("div", { className: "page-identity", children: [icon, _jsxs("div", { children: [_jsx("h1", { children: title }), subtitle && _jsx("p", { className: "page-subtitle muted", children: subtitle })] })] }), actions && _jsx("div", { className: "head-actions", children: actions })] }), children] }));
+}
 export function Section({ title, tools, class_name, on_context_menu, children }) {
     return (_jsxs("section", { className: class_name ? `panel ${class_name}` : "panel", onContextMenu: on_context_menu, children: [_jsxs("div", { className: "panel-head", children: [_jsx("h2", { children: title }), tools && _jsx("div", { className: "panel-tools", children: tools })] }), children] }));
 }

package/dist/web/react/media.js

@@ -10,7 +10,7 @@ export function Avatar({ src, name, size = "medium" }) {
 // One video, album or playlist: its picture, its title and a few lines about it.
 export function MediaTile({ title, href, image, corner, lines = [], dimmed = false, actions, lead }) {
     const shown_lines = lines.filter((line) => line !== null && line !== undefined && line !== false && line !== "");
-    return (_jsxs("div", { role: "listitem", className: dimmed ? "media-tile dimmed" : "media-tile", children: [lead !== undefined && _jsx("span", { className: "media-lead", children: lead }), _jsxs("a", { className: "media-picture", href: href, tabIndex: -1, "aria-hidden": "true", children: [image ? _jsx("img", { src: image, alt: "", loading: "lazy" }) : _jsx("span", { className: "media-blank" }), corner && _jsx("span", { className: "media-corner", children: corner })] }), _jsxs("div", { className: "media-text", children: [_jsx("a", { className: "media-title", href: href, children: title }), shown_lines.map((line, index) => _jsx("div", { className: "media-line", children: line }, index))] }), actions && _jsx("div", { className: "media-actions", children: actions })] }));
+    return (_jsxs("div", { role: "listitem", className: dimmed ? "media-tile media-dimmed dimmed" : "media-tile", children: [lead !== undefined && _jsx("span", { className: "media-lead", children: lead }), _jsxs("a", { className: "media-picture", href: href, tabIndex: -1, "aria-hidden": "true", children: [image ? _jsx("img", { src: image, alt: "", loading: "lazy" }) : _jsx("span", { className: "media-blank" }), corner && _jsx("span", { className: "media-corner", children: corner })] }), _jsxs("div", { className: "media-text", children: [_jsx("a", { className: "media-title", href: href, children: title }), shown_lines.map((line, index) => _jsx("div", { className: "media-line", children: line }, index))] }), actions && _jsx("div", { className: "media-actions", children: actions })] }));
 }
 // Tiles side by side filling the width, or one under another as rows with the picture on the left.
 export function MediaGrid({ label, rows = false, children }) {

package/dist/web/react/menu_button.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import { type MenuItem } from "./menus.tsx";
 interface MenuButtonProps {
     label: string;

package/dist/web/react/menu_button.js

@@ -1,12 +1,16 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+// A button that opens a menu under itself, such as the ⋮ on a card; the Shell draws the menu.
+import { useState } from "react";
 import { open_context_menu } from "./menus.js";
 export function MenuButton({ label, items, glyph = "⋮", class_name }) {
-    function open(event) {
+    const [open, set_open] = useState(false);
+    function open_menu(event) {
         // The button may sit inside a link, such as a whole card that opens its video.
         event.preventDefault();
         event.stopPropagation();
         const box = event.currentTarget.getBoundingClientRect();
-        open_context_menu({ clientX: box.left, clientY: box.bottom, preventDefault: () => { } }, typeof items === "function" ? items() : items);
+        set_open(true);
+        open_context_menu({ clientX: box.left, clientY: box.bottom, preventDefault: () => { } }, typeof items === "function" ? items() : items, () => set_open(false));
     }
-    return (_jsx("button", { type: "button", className: class_name ? `icon menu-trigger ${class_name}` : "icon menu-trigger", "aria-label": label, title: label, "aria-haspopup": "menu", onClick: open, children: glyph }));
+    return (_jsx("button", { type: "button", className: class_name ? `icon menu-trigger ${class_name}` : "icon menu-trigger", "aria-label": label, title: label, "aria-haspopup": "menu", "aria-expanded": open, onClick: open_menu, children: glyph }));
 }

package/dist/web/react/menus.d.ts

@@ -18,7 +18,7 @@ export declare function open_context_menu(event: {
     clientX: number;
     clientY: number;
     preventDefault(): void;
-}, items: MenuItem[]): void;
+}, items: MenuItem[], on_close?: () => void): void;
 export declare function ContextMenus(): import("react").JSX.Element | null;
 interface PopoverProps {
     anchor?: HTMLElement | null;

package/dist/web/react/menus.js

@@ -139,14 +139,16 @@ let open_menu = null;
 let next_menu_id = 1;
 const menu_listeners = new Set();
 function publish_menu(menu) {
+    const before = open_menu;
     open_menu = menu;
     for (const listener of menu_listeners)
         listener(open_menu);
+    before?.on_close?.();
 }
-// Opens a menu where the event happened, such as a right-click, replacing any menu already open.
-export function open_context_menu(event, items) {
+// Opens a menu where the event happened, such as a right-click, replacing any menu already open; on_close hears when it closes for any reason.
+export function open_context_menu(event, items, on_close) {
     event.preventDefault();
-    publish_menu({ id: next_menu_id++, x: event.clientX, y: event.clientY, items });
+    publish_menu({ id: next_menu_id++, x: event.clientX, y: event.clientY, items, on_close });
 }
 // Where menus opened from anywhere are drawn; the Shell holds one.
 export function ContextMenus() {

package/dist/web/react/states.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+import type { Watch } from "../watch.ts";
 export declare function Skeleton({ lines }: {
     lines?: number;
 }): import("react").JSX.Element;
@@ -10,18 +11,25 @@ export declare function Failure({ error, retry }: {
     error: unknown;
     retry: () => void;
 }): import("react").JSX.Element;
+export type ResourceStatus = "idle" | "loading" | "loaded" | "failed";
 export interface Resource<Data> {
     data: Data | null;
     error: unknown;
     loading: boolean;
+    status: ResourceStatus;
     reload: (quiet?: boolean) => Promise<void>;
 }
 export interface ResourceOptions {
     refresh_in_milliseconds?: number;
+    enabled?: boolean;
+    watch?: Watch;
 }
 export declare function use_resource<Data>(work: () => Promise<Data>, dependencies: unknown[], options?: ResourceOptions): Resource<Data>;
-export declare function Loaded<Data>({ resource, lines, children }: {
+interface LoadedProps<Data> {
     resource: Resource<Data>;
     lines?: number;
+    idle?: ReactNode;
     children: (data: Data) => ReactNode;
-}): import("react").JSX.Element;
+}
+export declare function Loaded<Data>({ resource, lines, idle, children }: LoadedProps<Data>): import("react").JSX.Element;
+export {};

package/dist/web/react/states.js

@@ -14,35 +14,49 @@ export function Failure({ error, retry }) {
 }
 // Loads what the work fetches whenever the dependencies change, passing a lapsed login on to the page.
 export function use_resource(work, dependencies, options = {}) {
-    const [state, set_state] = useState({ data: null, error: null, loading: true });
+    const enabled = options.enabled ?? true;
+    const [state, set_state] = useState({ data: null, error: null, status: enabled ? "loading" : "idle" });
     const latest_work = useRef(work);
     latest_work.current = work;
     const generation = useRef(0);
     const reload = useCallback((quiet = false) => {
         const mine = ++generation.current;
         if (!quiet)
-            set_state({ data: null, error: null, loading: true });
+            set_state({ data: null, error: null, status: "loading" });
         return latest_work.current().then((data) => { if (mine === generation.current)
-            set_state({ data, error: null, loading: false }); }, (error) => {
+            set_state({ data, error: null, status: "loaded" }); }, (error) => {
             if (pass_login_needed(error) || mine !== generation.current)
                 return;
-            set_state((before) => quiet && before.data !== null ? { ...before, loading: false } : { data: null, error, loading: false });
+            set_state((before) => quiet && before.data !== null ? before : { data: null, error, status: "failed" });
         });
     }, []);
-    useEffect(() => void reload(), dependencies);
     useEffect(() => {
-        if (!options.refresh_in_milliseconds)
+        if (enabled)
+            return void reload();
+        // Turning off drops the load under way and what it showed.
+        generation.current += 1;
+        set_state((before) => before.status === "idle" ? before : { data: null, error: null, status: "idle" });
+    }, [enabled, ...dependencies]);
+    useEffect(() => {
+        if (!options.refresh_in_milliseconds || !enabled)
             return;
         const timer = setInterval(() => { if (document.visibilityState === "visible")
             void reload(true); }, options.refresh_in_milliseconds);
         return () => clearInterval(timer);
-    }, [options.refresh_in_milliseconds]);
-    return { ...state, reload };
+    }, [options.refresh_in_milliseconds, enabled]);
+    useEffect(() => {
+        if (!options.watch || !enabled)
+            return;
+        return options.watch.subscribe(() => void reload(true));
+    }, [options.watch, enabled]);
+    return { ...state, loading: state.status === "loading", reload };
 }
 // Shows a skeleton while the resource first loads, an error with Retry if that fails, and what children build from it after.
-export function Loaded({ resource, lines, children }) {
+export function Loaded({ resource, lines, idle = null, children }) {
     if (resource.data !== null)
         return _jsx(_Fragment, { children: children(resource.data) });
+    if (resource.status === "idle")
+        return _jsx(_Fragment, { children: idle });
     if (resource.error !== null)
         return _jsx(Failure, { error: resource.error, retry: () => void resource.reload() });
     return _jsx(Skeleton, { lines: lines });

package/dist/web/react/test_stubs.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/web/react/test_stubs.js

@@ -0,0 +1,19 @@
+// Stands in for the native popover and modal dialog, which jsdom does not draw; a test imports it for its side effects.
+HTMLElement.prototype.showPopover = function () {
+    this.setAttribute("data-shown", "");
+};
+HTMLElement.prototype.hidePopover = function () {
+    this.removeAttribute("data-shown");
+    this.dispatchEvent(Object.assign(new Event("toggle"), { newState: "closed" }));
+};
+HTMLDialogElement.prototype.showModal = function () {
+    this.setAttribute("open", "");
+};
+HTMLDialogElement.prototype.close = function () {
+    this.removeAttribute("open");
+};
+// jsdom hides every popover, since none ever matches :popover-open, so a shown one is drawn again here.
+const shown_popovers = document.createElement("style");
+shown_popovers.textContent = "[popover][data-shown] { display: block; }";
+document.head.append(shown_popovers);
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-tech-laboratories/x-libs",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Code the X-apps share: agents and their long runs, passwords, durations, and the web page's helpers and widgets",
   "license": "GPL-3.0-or-later",
   "repository": {