@glimstone/core 4.0.0 → 4.1.1

package/dist/selectModel.d.ts

@@ -38,6 +38,23 @@ export declare function selectRootClass(width: SelectWidth): string;
 /** The trigger's classes. `wrap` lets a long value run onto a second line, for one whose end says as much as its start, such as a path. */
 export declare function selectTriggerClass(size: SelectSize, wrap: boolean): string;
 export declare function selectContentClass(glyphs: boolean): string;
+/**
+ * Which rows an open list draws. `menu` takes a context menu's, so an app with
+ * both shows one kind of menu row.
+ */
+export type SelectRows = "list" | "menu";
+export interface SelectRowParts {
+    content: string;
+    item: string;
+    /** The glyph's room, or null where no row of a list has one. A menu row keeps it always. */
+    glyph: string | null;
+    label: string;
+    check: string;
+    caret: string;
+    heading: string;
+}
+/** The classes of an open list and its rows. */
+export declare function selectRowParts(rows: SelectRows, glyphs: boolean): SelectRowParts;
 /** A field defaults to `fill`, the smaller sizes to `steady`. */
 export declare function defaultWidth(size: SelectSize): SelectWidth;
 export declare const SELECT_POSITIONING: {

package/dist/selectModel.js

@@ -24,6 +24,29 @@ export function selectTriggerClass(size, wrap) {
 export function selectContentClass(glyphs) {
     return `glim-select-content glim-fade${glyphs ? " glim-select-content--glyphs" : ""}`;
 }
+/** The classes of an open list and its rows. */
+export function selectRowParts(rows, glyphs) {
+    const content = selectContentClass(glyphs);
+    return rows === "menu"
+        ? {
+            content: `${content} glim-select-content--menu`,
+            item: "glim-menu-item",
+            glyph: "glim-menu-glyph",
+            label: "glim-menu-label",
+            check: "glim-menu-end glim-menu-tick",
+            caret: "glim-menu-end glim-menu-caret",
+            heading: "glim-menu-head",
+        }
+        : {
+            content,
+            item: "glim-select-item",
+            glyph: glyphs ? "glim-select-glyph" : null,
+            label: "glim-select-label",
+            check: "glim-select-check",
+            caret: "glim-select-caret",
+            heading: "glim-select-heading",
+        };
+}
 /** A field defaults to `fill`, the smaller sizes to `steady`. */
 export function defaultWidth(size) {
     return size === "field" ? "fill" : "steady";

package/dist/selector.d.ts

@@ -34,7 +34,7 @@ export declare const MAX_PINNED_WIDTH = 352;
  */
 export declare function pinnedWidth(widest: number, count: number, room: number, gap: number): number;
 /** The id of a tab in a strip that switches `panelId`; the panel names itself after it. */
-export declare function selectorTabId(panelId: string, itemId: string): string;
+export declare function selectorTabId(panelId: string, itemId: string | number): string;
 /**
  * The label axis a selector follows. The page-level strips are tabs, the
  * smaller ones stand in form rows beside buttons, and the column of tiles
@@ -56,7 +56,7 @@ export declare function nextFocusIndex(key: SelectorNavKey, current: number, cou
  */
 export declare function rovedIndex(disabled: boolean[], activeIndex: number): number;
 /** The value of a "many" selector once `id` is toggled, in the items' order. */
-export declare function toggleSelection(value: readonly string[], id: string, order: readonly string[]): string[];
+export declare function toggleSelection<V>(value: readonly V[], id: V, order: readonly V[]): V[];
 /**
  * Moves the focus for a key press inside `track` and returns the segment it
  * landed on, or null when the key is not one the strip answers. Disabled

package/dist/sidebarRow.d.ts

@@ -9,6 +9,10 @@ export interface SidebarRowInput {
     hueIndex?: number;
     /** The figure on the row; nothing shows at zero. */
     count?: number;
+    /** Something stands beside the link in the row, so it is never centred. */
+    framed?: boolean;
+    /** A tree's row: stepped in by its level, with a smaller glyph and gap. */
+    depth?: number;
 }
 export interface SidebarRowView {
     className: string;

package/dist/sidebarRow.js

@@ -15,14 +15,19 @@ export function sidebarRowView(r) {
     const showLabel = !hidesLabel(mode);
     const reactive = mode === "reactive";
     const hued = r.hueIndex !== undefined;
+    const tree = r.depth !== undefined;
+    // A tree's depth and a slot's control mean nothing in the middle of the row.
+    const centred = !showLabel && !r.framed && !tree;
     const style = {
         ...(hued ? hueVars(r.hueIndex) : {}),
+        ...(tree ? { "--nav-depth": String(r.depth) } : {}),
         ...(reactive ? { "--reactive-chars": String(labelWidth(r.label)) } : {}),
     };
     return {
         className: [
             "glim-nav-row",
-            !showLabel && "glim-nav-row--centred",
+            centred && "glim-nav-row--centred",
+            tree && "glim-nav-row--tree",
             reactive && "glim-reactive",
             hued && "glim-hue glim-hue-icon",
             r.active && "glim-active",

package/dist/table.d.ts

@@ -0,0 +1,12 @@
+export interface TableColumn {
+    /** Which field of a row the column shows. */
+    key: string;
+    /** The column's heading. A table with no heading at all draws no header row. */
+    label?: string;
+    /** Sets the column at the end, in figures that line up (rule 7). */
+    end?: boolean;
+    /** `muted` for a quiet column, `accent` for what changes. */
+    tone?: "muted" | "accent";
+}
+/** The classes of a cell. */
+export declare function tableCellClass(column: TableColumn): string;

package/dist/table.js

@@ -0,0 +1,5 @@
+// What a table is handed, and the classes its cells wear.
+/** The classes of a cell. */
+export function tableCellClass(column) {
+    return [column.end && "glim-table-end glim-num", column.tone && `glim-table-${column.tone}`].filter(Boolean).join(" ");
+}

package/dist/toastEngine.d.ts

@@ -5,10 +5,16 @@ export declare const TOAST_DURATION_MS = 4000;
  *  viewport. Without a cap, a held Enter key grows the stack off-screen, where
  *  its cards still block clicks on the page. */
 export declare const MAX_VISIBLE_TOASTS = 4;
+/** A button on a toast, such as Undo. A press runs it and dismisses the toast. */
+export interface ToastAction {
+    label: string;
+    onClick: () => void;
+}
 export interface ToastEntry {
     id: string;
     message: string;
     severity: ToastSeverity;
+    action?: ToastAction;
     /** What is left of the duration, authoritative only while paused
      *  (expiresAt === null). */
     remainingMs: number;
@@ -26,6 +32,7 @@ export declare function addToast(list: ToastEntry[], toast: {
     id: string;
     message: string;
     severity: ToastSeverity;
+    action?: ToastAction;
 }, now: number, durationMs?: number, maxVisible?: number): ToastEntry[];
 /** Removes one toast and leaves the others alone. Unknown ids are ignored. */
 export declare function removeToast(list: ToastEntry[], id: string): ToastEntry[];
@@ -54,6 +61,11 @@ export declare function applyEngagement(prev: Readonly<ToastEngagement>, kind: T
     next: ToastEngagement;
     engaged: boolean;
 };
+/**
+ * A message cut after each slash, for a <wbr> between the parts, so a path breaks
+ * at a folder rather than inside a name.
+ */
+export declare function softBreaks(message: string): string[];
 /** Quiet mode filters by severity: it hides routine successes, never warnings
  *  or failures. */
 export declare function shouldShowToast(severity: ToastSeverity, quiet: boolean): boolean;

package/dist/toastEngine.js

@@ -24,6 +24,7 @@ export function addToast(list, toast, now, durationMs = TOAST_DURATION_MS, maxVi
         id: toast.id,
         message: toast.message,
         severity: toast.severity,
+        action: toast.action,
         remainingMs: durationMs,
         expiresAt: now + durationMs,
     };
@@ -76,6 +77,13 @@ export function applyEngagement(prev, kind, active) {
     const next = { ...prev, [kind]: active };
     return { next, engaged: next.hover || next.focus };
 }
+/**
+ * A message cut after each slash, for a <wbr> between the parts, so a path breaks
+ * at a folder rather than inside a name.
+ */
+export function softBreaks(message) {
+    return message.split(/(?<=[/\\])/);
+}
 /** Quiet mode filters by severity: it hides routine successes, never warnings
  *  or failures. */
 export function shouldShowToast(severity, quiet) {

package/dist/tree.d.ts

@@ -0,0 +1,38 @@
+export interface TreeNode<G = unknown> {
+    /** Unique in the tree, such as a path. */
+    id: string;
+    label: string;
+    /** Whether the row can open. Its children are asked for the first time it does. */
+    hasChildren?: boolean;
+    glyph?: G;
+    /** Takes the glyph's place while the row is open. */
+    openGlyph?: G;
+    /** Attributes for the row, such as a data hook. */
+    attrs?: Record<string, string>;
+}
+export interface TreeRow<G = unknown> {
+    node: TreeNode<G>;
+    /** From 1, as aria-level counts. */
+    level: number;
+    position: number;
+    siblings: number;
+    parent: string | null;
+    open: boolean;
+}
+/** The rows on show, top to bottom. The top level's children are filed under null. */
+export declare function treeRows<G>(children: ReadonlyMap<string | null, readonly TreeNode<G>[]>, open: readonly string[]): TreeRow<G>[];
+export type TreeStep = {
+    focus: string;
+} | {
+    open: string;
+} | {
+    close: string;
+};
+/**
+ * What a key does on the row at `at`, or null when the tree does not answer it.
+ * Right and left swap under a right-to-left page. A letter goes to the next row
+ * starting with it, wrapping at the end.
+ */
+export declare function treeStep<G>(rows: readonly TreeRow<G>[], at: number, key: string, rtl?: boolean): TreeStep | null;
+/** Puts the focus on a row. */
+export declare function focusTreeRow(tree: HTMLElement, id: string): void;

package/dist/tree.js

@@ -0,0 +1,57 @@
+// The model behind Tree: which rows are on show and what a key does there. The
+// frameworks hold the children and draw the rows; the glyph type is theirs.
+/** The rows on show, top to bottom. The top level's children are filed under null. */
+export function treeRows(children, open) {
+    const rows = [];
+    const walk = (parent, level) => {
+        const nodes = children.get(parent) ?? [];
+        nodes.forEach((node, i) => {
+            const isOpen = !!node.hasChildren && open.includes(node.id);
+            rows.push({ node, level, position: i + 1, siblings: nodes.length, parent, open: isOpen });
+            if (isOpen)
+                walk(node.id, level + 1);
+        });
+    };
+    walk(null, 1);
+    return rows;
+}
+/**
+ * What a key does on the row at `at`, or null when the tree does not answer it.
+ * Right and left swap under a right-to-left page. A letter goes to the next row
+ * starting with it, wrapping at the end.
+ */
+export function treeStep(rows, at, key, rtl = false) {
+    const row = rows[at];
+    const focus = (target) => (target ? { focus: target.node.id } : null);
+    switch (key) {
+        case "ArrowDown":
+            return focus(rows[at + 1]);
+        case "ArrowUp":
+            return focus(rows[at - 1]);
+        case "Home":
+            return focus(rows[0]);
+        case "End":
+            return focus(rows[rows.length - 1]);
+        case "ArrowRight":
+        case "ArrowLeft": {
+            const inward = key === (rtl ? "ArrowLeft" : "ArrowRight");
+            if (inward) {
+                if (!row.node.hasChildren)
+                    return null;
+                return row.open ? focus(rows[at + 1]?.parent === row.node.id ? rows[at + 1] : undefined) : { open: row.node.id };
+            }
+            if (row.open)
+                return { close: row.node.id };
+            return row.parent === null ? null : { focus: row.parent };
+        }
+    }
+    if (key.length !== 1 || key === " ")
+        return null;
+    const letter = key.toLowerCase();
+    const after = [...rows.slice(at + 1), ...rows.slice(0, at)];
+    return focus(after.find((r) => r.node.label.toLowerCase().startsWith(letter)));
+}
+/** Puts the focus on a row. */
+export function focusTreeRow(tree, id) {
+    tree.querySelector(`[data-tree-id="${CSS.escape(id)}"]`)?.focus();
+}

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * The version every GlimStone package carries, so an app's Version card names
  * the one it runs. All packages share it and move together.
  */
-export declare const GLIMSTONE_VERSION = "4.0.0";
+export declare const GLIMSTONE_VERSION = "4.1.1";

package/dist/version.js

@@ -2,4 +2,4 @@
  * The version every GlimStone package carries, so an app's Version card names
  * the one it runs. All packages share it and move together.
  */
-export const GLIMSTONE_VERSION = "4.0.0";
+export const GLIMSTONE_VERSION = "4.1.1";

package/dist/window.d.ts

@@ -0,0 +1,29 @@
+export type WindowSize = "normal" | "wide" | "full";
+export interface WindowActionBase {
+    /** The forward action, filled with the accent. Its presence makes the way out Cancel rather than Close. */
+    primary?: boolean;
+    /** This action already leaves the window, such as Done, so no Cancel or Close is added. */
+    wayOut?: boolean;
+}
+/**
+ * The foot's buttons in order. A window whose foot has anything in it can be
+ * left from there: without a way out among its actions it gets Cancel when
+ * one of them goes forward and Close otherwise, before the others, so the
+ * forward action stays last.
+ */
+export declare function windowFoot<A extends WindowActionBase>(actions: readonly A[], hasStart: boolean, wayOut: {
+    cancel: A;
+    close: A;
+}): A[];
+/**
+ * Puts a window on the stack. Escape closes the one in front and Tab stays
+ * inside it. Returns the removal, to call however the window closes.
+ */
+export declare function stackWindow(card: () => HTMLElement | null, close: () => void): () => void;
+/** Whether a window is open, for a key handler of the app's that should leave the page alone. */
+export declare function windowIsOpen(): boolean;
+/**
+ * Where focus goes as a window opens: its first field, so typing can start at
+ * once, or else the last button of its foot, the forward action.
+ */
+export declare function windowFocusTarget(card: HTMLElement): HTMLElement | null;

package/dist/window.js

@@ -0,0 +1,62 @@
+// What every Window shares, whatever it holds ("Windows" in the design
+// language): a foot that always offers a way out, a stack in which Escape and
+// Tab belong to the window in front, and where focus lands when one opens.
+import { keepTabInside } from "./dialog.js";
+import { menuIsOpen } from "./menu.js";
+/**
+ * The foot's buttons in order. A window whose foot has anything in it can be
+ * left from there: without a way out among its actions it gets Cancel when
+ * one of them goes forward and Close otherwise, before the others, so the
+ * forward action stays last.
+ */
+export function windowFoot(actions, hasStart, wayOut) {
+    if ((actions.length === 0 && !hasStart) || actions.some((a) => a.wayOut))
+        return [...actions];
+    return [actions.some((a) => a.primary) ? wayOut.cancel : wayOut.close, ...actions];
+}
+const stack = [];
+// A key that an open menu or a Select inside the window already handled is
+// left alone, so Escape closes one thing at a time from the front.
+function onKey(e) {
+    const top = stack[stack.length - 1];
+    if (!top || e.defaultPrevented)
+        return;
+    if (e.key === "Escape") {
+        if (menuIsOpen())
+            return;
+        e.preventDefault();
+        top.close();
+    }
+    else if (e.key === "Tab")
+        keepTabInside(top.card(), e);
+}
+/**
+ * Puts a window on the stack. Escape closes the one in front and Tab stays
+ * inside it. Returns the removal, to call however the window closes.
+ */
+export function stackWindow(card, close) {
+    const entry = { card, close };
+    stack.push(entry);
+    if (stack.length === 1)
+        document.addEventListener("keydown", onKey);
+    return () => {
+        const at = stack.indexOf(entry);
+        if (at >= 0)
+            stack.splice(at, 1);
+        if (stack.length === 0)
+            document.removeEventListener("keydown", onKey);
+    };
+}
+/** Whether a window is open, for a key handler of the app's that should leave the page alone. */
+export function windowIsOpen() {
+    return stack.length > 0;
+}
+const FIELD = 'input:not([type="file"]):not([type="hidden"]):not([disabled]), textarea:not([disabled])';
+/**
+ * Where focus goes as a window opens: its first field, so typing can start at
+ * once, or else the last button of its foot, the forward action.
+ */
+export function windowFocusTarget(card) {
+    const foot = card.querySelectorAll(".glim-modal-foot button:not([disabled])");
+    return card.querySelector(FIELD) ?? foot[foot.length - 1] ?? null;
+}

package/glyph-map.md

@@ -13,6 +13,7 @@
 | Show, reveal | `IconEye` | `IconEye`, standard | `IconEye`, standard |
 | Hide again | `IconEyeOff` | `IconEyeOff`, standard | `IconEyeOff`, standard |
 | Reset to the default | `IconRefresh` | `IconClearSelection`, switch | `IconRefresh`, standard |
+| Reset one row of a colour card to its defaults | `IconResetArrow` | `IconResetArrow` in `AccentCard.tsx`, switch | none |
 | Retry, reload, refresh | `IconRetry` | `IconRefresh`, switch | `IconRetry`, standard |
 | Upload | `IconUpload` | `IconUpload`, standard | `IconUpload`, standard |
 | Import, read in | `IconImport` | `IconImport`, standard | `IconImport`, standard |
@@ -82,6 +83,8 @@
 | Write to us | `IconMail` | `IconMail`, standard | `IconMail`, standard |
 | Send a test | `IconSendTest` | `IconCheck`, switch | `IconSendTest`, standard |
 | Buy the author a coffee | `IconCoffee` | `IconCoffee`, standard | none |
+| Give through PayPal | `IconPayPal` | `IconPayPal` in `donateMarks.tsx`, switch | `IconPayPal` in `donateMarks.tsx`, switch |
+| Give from a crypto wallet | `IconBitcoin` | `IconBitcoin` in `donateMarks.tsx`, switch | `IconBitcoin` in `donateMarks.tsx`, switch |
 | A protection is on, turn it on | `IconShieldOn` | `IconShieldOn`, standard | `IconShieldOn`, standard |
 | A protection is off, turn it off | `IconShieldOff` | `IconShieldOff`, standard | `IconShieldOff`, standard |
 | Store uncompressed | `IconCompressOff` | `IconCompressOff`, standard | none |
@@ -125,6 +128,22 @@
 | A subtitle file | `IconFileSubtitles` | none | `IconFileSubtitles` before a subtitle file, standard |
 | A description or another text file | `IconFileText` | none | `IconFileText` before a description or a text file, standard |
 | A file, an attachment | `IconFile` | none | `IconFile` before any other file, standard |
+| A RAW photo straight from the camera | `IconFileRaw` | none | none |
+| A design or vector graphic | `IconFileDesign` | none | none |
+| A playlist | `IconFilePlaylist` | none | none |
+| A PDF document | `IconFilePdf` | none | none |
+| A text document from an office suite | `IconFileDoc` | none | none |
+| A spreadsheet | `IconFileSheet` | none | none |
+| A presentation | `IconFileSlides` | none | none |
+| An e-book | `IconBook` | none | none |
+| A disk image or virtual disk | `IconDisc` | none | none |
+| A program or installable package | `IconFileProgram` | none | none |
+| A font | `IconFont` | none | none |
+| A checksum or signature | `IconHash` | none | none |
+| A torrent or magnet link | `IconMagnet` | none | none |
+| A 3D model or CAD drawing | `IconCube` | none | none |
+| A calendar or contact card | `IconCalendar` | none | none |
+| A backup, temporary or unfinished file | `IconHourglass` | none | none |
 | Instances, other boxes | `IconFleet` | `IconFleet`, standard | `IconFleet`, standard |
 | Collector, taking links in | `IconCollector` | none | `IconCollector`, standard |
 | Accounts | `IconAccounts` | none | `IconAccounts`, standard |
@@ -365,10 +384,39 @@ FireSquire wears seven glyphs on the buttons of its pre-reboot check and on the
 
 <br>
 
+## CannonCommander
+
+CannonCommander's new interface draws every glyph from the assortment. The rows below are the meanings that came into it with the file manager, and the others follow once its screens are built.
+
+| Meaning | GlimStone | CannonCommander |
+| --- | --- | --- |
+| Reset one row of a colour card to its defaults | `IconResetArrow` | `IconResetArrow`, standard |
+| Give through PayPal | `IconPayPal` | `IconPayPal`, standard |
+| Give from a crypto wallet | `IconBitcoin` | `IconBitcoin`, standard |
+| A RAW photo straight from the camera | `IconFileRaw` | `IconFileRaw`, standard |
+| A design or vector graphic | `IconFileDesign` | `IconFileDesign`, standard |
+| A playlist | `IconFilePlaylist` | `IconFilePlaylist`, standard |
+| A PDF document | `IconFilePdf` | `IconFilePdf`, standard |
+| A text document from an office suite | `IconFileDoc` | `IconFileDoc`, standard |
+| A spreadsheet | `IconFileSheet` | `IconFileSheet`, standard |
+| A presentation | `IconFileSlides` | `IconFileSlides`, standard |
+| An e-book | `IconBook` | `IconBook`, standard |
+| A disk image or virtual disk | `IconDisc` | `IconDisc`, standard |
+| A program or installable package | `IconFileProgram` | `IconFileProgram`, standard |
+| A font | `IconFont` | `IconFont`, standard |
+| A checksum or signature | `IconHash` | `IconHash`, standard |
+| A torrent or magnet link | `IconMagnet` | `IconMagnet`, standard |
+| A 3D model or CAD drawing | `IconCube` | `IconCube`, standard |
+| A calendar or contact card | `IconCalendar` | `IconCalendar`, standard |
+| A backup, temporary or unfinished file | `IconHourglass` | `IconHourglass`, standard |
+
+<br>
+
 ## Where each app keeps its glyphs
 
 - **ArrowLoop:** `scripts/gen_glyphs.py` writes the app's glyphs, and the Look settings glyphs come from it, for the web and, through `scripts/gen_glyph_data.py`, for the phone. `web/src/lib/glyphName.ts` maps a translation key to a glyph name, and a key it does not know keeps its text.
 - **BombVault:** `scripts/gen_glyphs.py` writes `web/src/components/glyphs.tsx` and `navGlyphs.tsx` from a copy of `glyphs.json` at 16px; the phone app shows the web launcher and uses the same files. `glyphFor.tsx` maps a translation key to a glyph when a button passes none; a button that passes one wins.
+- **CannonCommander:** the frontend maps a file's kind to a glyph name through `prototype/src/formats.json` and draws the entry from `glyphs.json` through `@glimstone/vue`.
 - **FireSquire:** `firesquire-glyphs.js` beside its scripts holds a copy of every entry it draws, the square viewBox and the drawing, and names the GlimStone release it came from. `plugin/test/glyphs.test.js` checks that every glyph a button asks for is in the copy.
 - **KnightLoader:** `web/scripts/gen-glyphs.mjs` writes `web/src/lib/glyphs.tsx` at 22px with the ink at three quarters of the box; the Android app has no SVG and shows tinted bitmaps rendered from the same list into `mobile/assets/`. Every call site passes its glyph; Settings page glyphs are mapped in `pages/settings/pageIcons.tsx`. The browser extension copies the eye and a few others in `extension/src/`.
 - **ShipLog:** `include/glyphs.php` holds a copy of every entry it draws. `shiplog.page` uses them on the settings page, and `shiplog.Docker.page` hands four of them to `scripts/docker.js` for the changelog window.