@glimstone/core 4.0.0 → 4.1.0

package/dist/index.js

@@ -3,6 +3,8 @@ export * from "./appMarks.js";
 export * from "./badge.js";
 export * from "./bubblePosition.js";
 export * from "./button.js";
+export * from "./clipboard.js";
+export * from "./colorNames.js";
 export * from "./colorPicker.js";
 export * from "./controls.js";
 export * from "./dialog.js";
@@ -13,9 +15,12 @@ export * from "./infoTile.js";
 export * from "./inputModality.js";
 export * from "./marks.js";
 export * from "./media.js";
+export * from "./menu.js";
+export * from "./meter.js";
 export * from "./motionNative.js";
 export * from "./numberField.js";
 export * from "./paypal.js";
+export * from "./pill.js";
 export * from "./portalHue.js";
 export * from "./readmeButton.js";
 export * from "./segmentLayout.js";
@@ -29,3 +34,4 @@ export * from "./tipBubble.js";
 export * from "./toastEngine.js";
 export * from "./tooltip.js";
 export * from "./version.js";
+export * from "./window.js";

package/dist/marks.d.ts

@@ -41,6 +41,30 @@ export declare const MARKS: {
         size: number;
         body: string;
     };
+    /** `IconPencil`: the edit button at the end of a menu's heading. */
+    pencil: {
+        viewBox: string;
+        size: number;
+        body: string;
+    };
+    /** `IconEye`: the reveal eye of a PasswordField while the secret is hidden. */
+    eye: {
+        viewBox: string;
+        size: number;
+        body: string;
+    };
+    /** `IconEyeOff`: the same eye once the secret shows, to hide it again. */
+    eyeOff: {
+        viewBox: string;
+        size: number;
+        body: string;
+    };
+    /** `IconCopy`: a CopyField's button. */
+    copy: {
+        viewBox: string;
+        size: number;
+        body: string;
+    };
     /** The small cross that dismisses a toast. */
     dismiss: {
         viewBox: string;

package/dist/marks.js

@@ -48,6 +48,30 @@ export const MARKS = {
         size: 16,
         body: '<path fill-rule="evenodd" clip-rule="evenodd" d="M2.5 3h6A2.5 2.5 0 0 1 11 5.5v6A2.5 2.5 0 0 1 8.5 14h-6A2.5 2.5 0 0 1 0 11.5v-6A2.5 2.5 0 0 1 2.5 3Zm0 2a.5.5 0 0 0-.5.5v6a.5.5 0 0 0 .5.5h6a.5.5 0 0 0 .5-.5v-6a.5.5 0 0 0-.5-.5Z"/><path d="M5 0h6.5A2.5 2.5 0 0 1 14 2.5V9h-2V2.5a.5.5 0 0 0-.5-.5H5Z"/>',
     },
+    /** `IconPencil`: the edit button at the end of a menu's heading. */
+    pencil: {
+        viewBox: "-0.002 -0.001 14.001 14.001",
+        size: 14,
+        body: '<path d="M10.715 -0.000976562c-0.1998 0 -0.3976 0.039922962 -0.5818 0.117424562 -0.18301 0.07702 -0.34892 0.18961 -0.48808 0.331228L1.40732 8.64549c-0.06116 0.06086 -0.10553 0.13651 -0.12879 0.21959L0.0185299 13.3651c-0.0487051 0.1739 0.0001992 0.3606 0.1279281 0.4884 0.12773 0.1277 0.314422 0.1766 0.488369 0.1279l4.500003 -1.26c0.08308 -0.0233 0.15873 -0.0677 0.21959 -0.1288l8.19768 -8.2377 0.0014 -0.00135c0.1399 -0.13917 0.251 -0.30459 0.3269 -0.48679 0.0762 -0.18278 0.1154 -0.37884 0.1154 -0.57686 0 -0.19802 -0.0392 -0.39408 -0.1154 -0.57687 -0.0759 -0.1822 -0.187 -0.34763 -0.3269 -0.48679l-0.0014 -0.00134L11.7859 0.448721c-0.1393 -0.14211 -0.3056 -0.255064 -0.4891 -0.332273 -0.1842 -0.0775016 -0.382 -0.117424562 -0.5818 -0.117424562Z"/>',
+    },
+    /** `IconEye`: the reveal eye of a PasswordField while the secret is hidden. */
+    eye: {
+        viewBox: "0 0 14 14",
+        size: 16,
+        body: '<g><path fill-rule="evenodd" d="M2.9327 3.49099C4.0559 2.68177 5.4556 2 7 2c1.54441 0 2.9441 0.68177 4.0673 1.49099 1.1273 0.81215 2.0197 1.78397 2.5599 2.4369l0.0045 0.00553c0.2413 0.3002 0.3683 0.68062 0.3683 1.06664 0 0.38601 -0.127 0.76644 -0.3683 1.06664l-0.0045 0.00553c-0.5402 0.65292 -1.4326 1.62475 -2.5599 2.43687 -1.1232 0.8092 -2.52289 1.491 -4.0673 1.491 -1.5444 0 -2.9441 -0.6818 -4.0673 -1.491C1.80544 9.69698 0.913028 8.72515 0.37279 8.07223L0.36828 8.0667C0.127025 7.7665 0 7.38607 0 7.00006c0 -0.38602 0.127025 -0.76644 0.36828 -1.06664l0.00451 -0.00553c0.540238 -0.65293 1.43265 -1.62475 2.55991 -2.4369ZM7 9.25c1.24264 0 2.25 -1.00736 2.25 -2.25S8.24264 4.75 7 4.75 4.75 5.75736 4.75 7 5.75736 9.25 7 9.25Z" clip-rule="evenodd"></path></g>',
+    },
+    /** `IconEyeOff`: the same eye once the secret shows, to hide it again. */
+    eyeOff: {
+        viewBox: "0.044 0.044 13.912 13.912",
+        size: 16,
+        body: '<g><path fill-rule="evenodd" d="M0.263638 1.32434c-0.2928929 -0.2929 -0.2928929 -0.767771 0 -1.060664 0.292894 -0.2928929 0.767772 -0.2928929 1.060662 0L3.95291 2.89228c0.90784 -0.49884 1.93998 -0.85203 3.04708 -0.85203 1.53199 0 2.92043 0.67629 4.03461 1.479 1.1182 0.80562 2.0034 1.76963 2.5393 2.41731l0.0045 0.00548c0.2393 0.29779 0.3653 0.67515 0.3653 1.05806s-0.126 0.76028 -0.3653 1.05806l-0.0045 0.00549c-0.4886 0.59054 -1.2677 1.44407 -2.2489 2.20075l2.4114 2.4113c0.2929 0.2929 0.2929 0.7678 0 1.0607 -0.2929 0.2929 -0.7678 0.2929 -1.0607 0L0.263638 1.32434ZM9.01713 7.95651c0.13771 -0.2899 0.21477 -0.61419 0.21477 -0.95649 0 -1.23264 -0.99926 -2.2319 -2.23191 -2.2319 -0.34229 0 -0.66659 0.07705 -0.95649 0.21476l2.97363 2.97363ZM0.426074 5.93656c0.319448 -0.38609 0.763036 -0.88458 1.306096 -1.39491l7.10402 7.10405c-0.58062 0.1961 -1.19587 0.3143 -1.8362 0.3143 -1.53198 0 -2.92042 -0.6763 -4.03459 -1.479C1.8472 9.67534 0.961967 8.71133 0.426074 8.06365L0.4216 8.05816C0.182285 7.76038 0.0562814 7.38301 0.0562814 7.0001S0.182285 6.23983 0.4216 5.94204l0.004474 -0.00548Z" clip-rule="evenodd"></path></g>',
+    },
+    /** `IconCopy`: a CopyField's button. */
+    copy: {
+        viewBox: "2 2 20 20",
+        size: 16,
+        body: '<path d="M20.926 7.074a3.67 3.67 0 0 1 1.074 2.593v8.666a3.667 3.667 0 0 1 -3.667 3.667h-8.666a3.667 3.667 0 0 1 -3.667 -3.667v-8.666q 0 -.053 .005 -.102a3.66 3.66 0 0 1 3.662 -3.565h8.666c.973 0 1.905 .386 2.593 1.074" /><path d="M17.374 3.514a1 1 0 1 1 -1.748 .972c-.221 -.398 -.342 -.486 -.626 -.486h-10c-.548 0 -1 .452 -1 1v9.998c0 .36 .194 .692 .507 .87a1 1 0 1 1 -.99 1.738a3 3 0 0 1 -1.517 -2.606v-10c0 -1.652 1.348 -3 3 -3h10c1.094 0 1.828 .533 2.374 1.514" />',
+    },
     /** The small cross that dismisses a toast. */
     dismiss: {
         viewBox: "0 0 16 16",

package/dist/menu.d.ts

@@ -0,0 +1,107 @@
+export interface MenuItem<G> {
+    label: string;
+    glyph?: G;
+    /** A colour dot where the glyph would stand, such as a label's colour. */
+    color?: string;
+    /** The key that runs the same thing, shown as a key cap at the row's end. */
+    shortcut?: string;
+    /** A figure at the row's end, such as how many files a filter would show. */
+    count?: number;
+    disabled?: boolean;
+    /** Set for an item that is on or off. A checkbox item leaves the menu open,
+     *  so several can be ticked in a row. */
+    checked?: boolean;
+    /** With `checked`: one choice among several. It keeps its glyph, ticks the
+     *  current choice at the end and closes the menu like a plain item. */
+    radio?: boolean;
+    /** Entries that open beside this row. */
+    sub?: MenuEntry<G>[];
+    onSelect?: () => void;
+}
+export interface MenuHead<G> {
+    head: string;
+    /** A pencil at the heading's end, for a group the person keeps themselves,
+     *  such as bookmarks. */
+    edit?: {
+        tip: string;
+        glyph?: G;
+        onSelect: () => void;
+    };
+}
+/** An item, a heading, or "-" for a separator. */
+export type MenuEntry<G> = MenuItem<G> | MenuHead<G> | "-";
+export declare function isMenuHead<G>(entry: MenuEntry<G>): entry is MenuHead<G>;
+/**
+ * Drops the separators a list built from parts ends up with: at either end,
+ * twice in a row and right under a heading. A menu assembled from whatever
+ * applies to the selection then needs no care at each call site.
+ */
+export declare function tidyMenu<G>(entries: readonly MenuEntry<G>[]): MenuEntry<G>[];
+export interface MenuRowView {
+    role: "menuitem" | "menuitemcheckbox" | "menuitemradio";
+    /** What stands before the label. */
+    lead: "box" | "dot" | "glyph" | "blank";
+    /** What stands at the row's end, one thing at most. */
+    end: "submenu" | "tick" | "shortcut" | "count" | null;
+    /** The radio item that is the current choice, washed with the accent. */
+    current: boolean;
+    /** A press leaves the menu open. */
+    staysOpen: boolean;
+}
+/** What one row shows. A row without a glyph keeps the glyph's room, so every label starts at one edge. */
+export declare function menuRowView<G>(item: MenuItem<G>): MenuRowView;
+interface Size {
+    width: number;
+    height: number;
+}
+/**
+ * Where a menu opened at a point goes: at the point, pushed back inside the
+ * window by its own size. `above` stands it on the point instead, for a menu
+ * opened from a bar at the bottom.
+ */
+export declare function placeMenu(x: number, y: number, menu: Size, view: Size, above?: boolean): {
+    left: number;
+    top: number;
+};
+/**
+ * Where a submenu goes: beside its row on the reading side, on the other side
+ * when that has no room, and level with the row as far as the window allows.
+ */
+export declare function placeSubmenu(row: {
+    left: number;
+    right: number;
+    top: number;
+}, menu: Size, view: Size, rtl?: boolean): {
+    left: number;
+    top: number;
+};
+export type MenuMove = "next" | "prev" | "first" | "last" | "in" | "out";
+/** What a key does inside an open menu. Right and left swap under a right-to-left page. */
+export declare function menuMove(key: string, rtl?: boolean): MenuMove | null;
+/** The rows a key can reach, in order: every enabled button of the menu. */
+export declare function menuRows(menu: HTMLElement): HTMLElement[];
+/**
+ * Puts the focus on a menu's first row as it opens. A menu the pointer opened
+ * carries `data-pointer` until a key is pressed in it, and the row shows no
+ * ring or wash meanwhile: the mouse never asked for that focus, and a lit
+ * first row reads as a choice already made.
+ */
+export declare function focusFirstMenuRow(menu: HTMLElement): void;
+/** Moves the focus along a menu's rows, wrapping at both ends. */
+export declare function focusMenuRow(menu: HTMLElement, move: "next" | "prev" | "first" | "last"): void;
+/**
+ * Registers a menu as the open one and closes any other. `close` hears
+ * whether Escape closed it, which hands focus back, or another menu took its
+ * place. Returns the release to call when it closes.
+ */
+export declare function claimMenu(close: (byEscape: boolean) => void): () => void;
+/** Whether a menu is open, for a key handler of the app's that should leave it alone. */
+export declare function menuIsOpen(): boolean;
+/**
+ * Closes a menu on a click anywhere outside the given elements, such as the
+ * menu, its submenu and the control that opened it. A click rather than a
+ * press: the window under a menu reads the press, and while the menu is still
+ * open it knows to stay. Returns the cleanup.
+ */
+export declare function closeMenuOutside(inside: () => (Element | null | undefined)[], close: () => void): () => void;
+export {};

package/dist/menu.js

@@ -0,0 +1,163 @@
+// The model behind ContextMenu and MenuBar: what an entry is, how a list is
+// tidied, what each row shows, where a menu goes on the screen and which key
+// does what. The frameworks only draw it; the glyph type is theirs.
+import { pointerWasLast, trackInputModality } from "./inputModality.js";
+// Listening starts with the module rather than with the first menu, which
+// mounts after the press that opened it and would miss it.
+trackInputModality();
+export function isMenuHead(entry) {
+    return typeof entry === "object" && "head" in entry;
+}
+/**
+ * Drops the separators a list built from parts ends up with: at either end,
+ * twice in a row and right under a heading. A menu assembled from whatever
+ * applies to the selection then needs no care at each call site.
+ */
+export function tidyMenu(entries) {
+    return entries.filter((e, i, all) => {
+        if (e !== "-")
+            return true;
+        const before = all[i - 1];
+        return i > 0 && i < all.length - 1 && before !== "-" && !isMenuHead(before);
+    });
+}
+/** What one row shows. A row without a glyph keeps the glyph's room, so every label starts at one edge. */
+export function menuRowView(item) {
+    const check = item.checked !== undefined;
+    const box = check && !item.radio;
+    const on = item.checked === true;
+    return {
+        role: !check ? "menuitem" : item.radio ? "menuitemradio" : "menuitemcheckbox",
+        lead: box ? "box" : item.color ? "dot" : item.glyph ? "glyph" : "blank",
+        end: item.sub
+            ? "submenu"
+            : item.radio && on
+                ? "tick"
+                : item.shortcut
+                    ? "shortcut"
+                    : item.count !== undefined
+                        ? "count"
+                        : null,
+        current: !!item.radio && on,
+        staysOpen: box,
+    };
+}
+const EDGE = 8;
+/**
+ * Where a menu opened at a point goes: at the point, pushed back inside the
+ * window by its own size. `above` stands it on the point instead, for a menu
+ * opened from a bar at the bottom.
+ */
+export function placeMenu(x, y, menu, view, above = false) {
+    return {
+        left: Math.max(EDGE, Math.min(x, view.width - menu.width - EDGE)),
+        top: above ? Math.max(EDGE, y - menu.height - EDGE) : Math.max(EDGE, Math.min(y, view.height - menu.height - EDGE)),
+    };
+}
+/**
+ * Where a submenu goes: beside its row on the reading side, on the other side
+ * when that has no room, and level with the row as far as the window allows.
+ */
+export function placeSubmenu(row, menu, view, rtl = false) {
+    const after = row.right + 6;
+    const before = row.left - menu.width - 6;
+    const fitsAfter = after + menu.width <= view.width;
+    const fitsBefore = before >= 0;
+    const left = rtl ? (fitsBefore ? before : after) : fitsAfter ? after : before;
+    return { left, top: Math.max(EDGE, Math.min(row.top - 6, view.height - menu.height - EDGE)) };
+}
+/** What a key does inside an open menu. Right and left swap under a right-to-left page. */
+export function menuMove(key, rtl = false) {
+    switch (key) {
+        case "ArrowDown":
+            return "next";
+        case "ArrowUp":
+            return "prev";
+        case "Home":
+            return "first";
+        case "End":
+            return "last";
+        case "ArrowRight":
+            return rtl ? "out" : "in";
+        case "ArrowLeft":
+            return rtl ? "in" : "out";
+    }
+    return null;
+}
+/** The rows a key can reach, in order: every enabled button of the menu. */
+export function menuRows(menu) {
+    return Array.from(menu.querySelectorAll("button:not([disabled])"));
+}
+/**
+ * Puts the focus on a menu's first row as it opens. A menu the pointer opened
+ * carries `data-pointer` until a key is pressed in it, and the row shows no
+ * ring or wash meanwhile: the mouse never asked for that focus, and a lit
+ * first row reads as a choice already made.
+ */
+export function focusFirstMenuRow(menu) {
+    if (pointerWasLast()) {
+        menu.dataset.pointer = "";
+        menu.addEventListener("keydown", () => delete menu.dataset.pointer, { once: true });
+    }
+    menuRows(menu)[0]?.focus();
+}
+/** Moves the focus along a menu's rows, wrapping at both ends. */
+export function focusMenuRow(menu, move) {
+    const rows = menuRows(menu);
+    if (rows.length === 0)
+        return;
+    const last = rows.length - 1;
+    const at = rows.indexOf(document.activeElement);
+    let next = move === "first" ? 0 : move === "last" ? last : at + (move === "next" ? 1 : -1);
+    if (at < 0 && move === "prev")
+        next = last;
+    rows[(next + rows.length) % rows.length].focus();
+}
+// One menu is open at a time in the whole document. Opening one closes the
+// last, and Escape reaches the open one from anywhere, so a window under it
+// keeps its own Escape for later.
+let openMenu = null;
+function onMenuKey(e) {
+    if (e.key !== "Escape" || !openMenu)
+        return;
+    e.preventDefault();
+    openMenu(true);
+}
+/**
+ * Registers a menu as the open one and closes any other. `close` hears
+ * whether Escape closed it, which hands focus back, or another menu took its
+ * place. Returns the release to call when it closes.
+ */
+export function claimMenu(close) {
+    const previous = openMenu;
+    openMenu = close;
+    if (previous && previous !== close)
+        previous(false);
+    else if (!previous)
+        document.addEventListener("keydown", onMenuKey);
+    return () => {
+        if (openMenu !== close)
+            return;
+        openMenu = null;
+        document.removeEventListener("keydown", onMenuKey);
+    };
+}
+/** Whether a menu is open, for a key handler of the app's that should leave it alone. */
+export function menuIsOpen() {
+    return openMenu !== null;
+}
+/**
+ * Closes a menu on a click anywhere outside the given elements, such as the
+ * menu, its submenu and the control that opened it. A click rather than a
+ * press: the window under a menu reads the press, and while the menu is still
+ * open it knows to stay. Returns the cleanup.
+ */
+export function closeMenuOutside(inside, close) {
+    function onClick(e) {
+        const target = e.target;
+        if (!inside().some((el) => el?.contains(target)))
+            close();
+    }
+    document.addEventListener("click", onClick, true);
+    return () => document.removeEventListener("click", onClick, true);
+}

package/dist/meter.d.ts

@@ -0,0 +1,32 @@
+export type MeterSize = "small" | "medium";
+export interface BarView {
+    /** The track's class list. */
+    className: string;
+    /** The fill's width as a CSS percentage, or null while indeterminate. */
+    width: string | null;
+    /** The value in whole percent for aria-valuenow, or null while indeterminate. */
+    percent: number | null;
+}
+export interface MeterOptions {
+    size?: MeterSize;
+    /** From here on the fill is the fault colour. */
+    threshold?: number;
+    /** Slim and grey, for a footer line or a dense list where an accent bar on
+     *  every row would shout. */
+    quiet?: boolean;
+}
+/**
+ * A meter's look. At or past `threshold` the fill turns to the fault colour,
+ * quiet or not, since a disk that is nearly full is a problem to see from
+ * across the room.
+ */
+export declare function meterView(value: number | null | undefined, { size, threshold, quiet }?: MeterOptions): BarView;
+/**
+ * A progress bar's look. The sheen runs only while the work does: it stops
+ * when the bar is paused, finished or failed, since a light still travelling a
+ * finished bar contradicts the number beside it.
+ */
+export declare function progressView(value: number | null | undefined, state?: {
+    paused?: boolean;
+    failed?: boolean;
+}): BarView;

package/dist/meter.js

@@ -0,0 +1,44 @@
+// What a Meter and a ProgressBar show for a value. A meter is a level that
+// stands, such as how full a disk is; a progress bar is work that moves toward
+// its end. Both take a value from 0 to 1, and without one they are busy: the
+// level is still being read, or the work has no measure yet.
+function measure(value) {
+    if (value == null || Number.isNaN(value))
+        return { v: null, width: null, percent: null };
+    const v = Math.min(1, Math.max(0, value));
+    return { v, width: `${Math.round(v * 1000) / 10}%`, percent: Math.round(v * 100) };
+}
+/**
+ * A meter's look. At or past `threshold` the fill turns to the fault colour,
+ * quiet or not, since a disk that is nearly full is a problem to see from
+ * across the room.
+ */
+export function meterView(value, { size = "medium", threshold = 0.9, quiet = false } = {}) {
+    const { v, width, percent } = measure(value);
+    const classes = ["glim-meter", "glim-meter-track", `glim-meter-track--${size}`];
+    if (quiet)
+        classes.push("glim-meter-track--quiet");
+    if (v === null)
+        classes.push("glim-meter-track--busy");
+    else if (v >= threshold)
+        classes.push("glim-meter-track--full");
+    return { className: classes.join(" "), width, percent };
+}
+/**
+ * A progress bar's look. The sheen runs only while the work does: it stops
+ * when the bar is paused, finished or failed, since a light still travelling a
+ * finished bar contradicts the number beside it.
+ */
+export function progressView(value, state = {}) {
+    const { v, width, percent } = measure(value);
+    const classes = ["glim-meter", "glim-progress"];
+    if (v === null)
+        classes.push("glim-progress--busy");
+    if (state.failed)
+        classes.push("glim-progress--failed");
+    else if (state.paused)
+        classes.push("glim-progress--paused");
+    else if (v === 1)
+        classes.push("glim-progress--done");
+    return { className: classes.join(" "), width, percent };
+}

package/dist/pill.d.ts

@@ -0,0 +1,3 @@
+export type PillTone = "neutral" | "state" | "ok" | "warn" | "fail";
+/** The class list of a pill. */
+export declare function pillClassName(tone?: PillTone): string;

package/dist/pill.js

@@ -0,0 +1,7 @@
+// The small data pill of a list row: a size, a date, a state. A Badge says
+// something about the row; a pill is one of its values, so it stays quiet and
+// takes a state colour only as a wash.
+/** The class list of a pill. */
+export function pillClassName(tone = "neutral") {
+    return tone === "neutral" ? "glim-pill" : `glim-pill glim-pill--${tone}`;
+}

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.0";

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.0";

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>
 
+## CastleCommander
+
+CastleCommander'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 | CastleCommander |
+| --- | --- | --- |
+| 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.
+- **CastleCommander:** 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.