nexus-shared 1.1.21 → 3.0.0

package/dist/Helpers/NumberHelpers.js

@@ -0,0 +1,202 @@
+/** Default locale for number text. Fixed rather than the browser's, so server-rendered text matches the browser's. */
+export const DEFAULT_NUMBER_LOCALE = "en-US";
+/** Most digits a number field takes. A JavaScript number holds 15 significant digits exactly; beyond that, digits change. */
+export const MAX_NUMBER_DIGITS = 15;
+const symbolsByLocale = new Map();
+const formatters = new Map();
+// Direction marks some locales put around a minus sign; they are invisible and never part of the number.
+const BIDI_MARKS = /[\u061c\u200e\u200f]/g;
+// U+2212, the typographic minus sign some locales use.
+const MINUS_SIGN = "\u2212";
+const SPACES = /\s/g;
+/** The decimal and group separators of a locale. */
+export function getNumberSymbols(locale = DEFAULT_NUMBER_LOCALE) {
+    let symbols = symbolsByLocale.get(locale);
+    if (!symbols) {
+        const parts = new Intl.NumberFormat(locale).formatToParts(1234567.5);
+        symbols = {
+            decimal: parts.find(part => part.type === "decimal")?.value ?? ".",
+            group: parts.find(part => part.type === "group")?.value ?? ",",
+        };
+        symbolsByLocale.set(locale, symbols);
+    }
+    return symbols;
+}
+/**
+ * Formats a number for display: `formatNumber(1250, { decimals: 2, fixedDecimals: true, grouping: true })` gives "1,250.00".
+ * Returns "" for `null`, `undefined`, and `NaN`. Digits are always 0–9, and the minus sign is "-", so the text can be typed back.
+ */
+export function formatNumber(value, options = {}) {
+    if (value === null || value === undefined || !Number.isFinite(value))
+        return "";
+    const { decimals, fixedDecimals = false, grouping = false, locale = DEFAULT_NUMBER_LOCALE } = options;
+    const maxDecimals = decimals ?? MAX_NUMBER_DIGITS;
+    const minDecimals = fixedDecimals ? maxDecimals : 0;
+    const key = `${locale}|${minDecimals}|${maxDecimals}|${grouping}`;
+    let formatter = formatters.get(key);
+    if (!formatter) {
+        formatter = new Intl.NumberFormat(locale, {
+            numberingSystem: "latn",
+            useGrouping: grouping,
+            minimumFractionDigits: minDecimals,
+            maximumFractionDigits: maxDecimals,
+        });
+        formatters.set(key, formatter);
+    }
+    // Rounded first, the same way as roundDecimal, which also turns -0.001 into 0 rather than "-0".
+    return formatter.format(roundDecimal(value, maxDecimals)).replace(BIDI_MARKS, "").replace(MINUS_SIGN, "-");
+}
+/**
+ * Reads a number written in the locale's format: "1,250.50" gives 1250.5, and in `de-DE` "1.250,50" does.
+ * Returns `null` for empty text (also a lone minus sign or decimal separator) and `NaN` for text that is not a number.
+ */
+export function parseNumber(text, locale = DEFAULT_NUMBER_LOCALE) {
+    const { decimal, group } = getNumberSymbols(locale);
+    let clean = (text ?? "").replace(BIDI_MARKS, "").replace(SPACES, "").replace(MINUS_SIGN, "-");
+    if (group.trim())
+        clean = clean.replaceAll(group, "");
+    if (decimal !== ".")
+        clean = clean.replace(decimal, ".");
+    if (/^-?\.?$/.test(clean))
+        return null;
+    if (!/^-?(?:\d+\.?\d*|\.\d+)$/.test(clean))
+        return Number.NaN;
+    return Number(clean) || 0;
+}
+/** Counts the digits in text, to keep numbers within `MAX_NUMBER_DIGITS`. */
+export function countDigits(text) {
+    let count = 0;
+    for (const char of text)
+        if (char >= "0" && char <= "9")
+            count++;
+    return count;
+}
+/**
+ * Whether text typed so far can become a valid number: "", "-", "12.", and ".5" can; "1.2.3" and "12a" cannot.
+ * The text is edit text: digits, at most one decimal separator, and a leading minus sign, with no group separators.
+ */
+export function isPartialNumber(text, decimal, rules) {
+    let index = 0;
+    if (text.startsWith("-")) {
+        if (!rules.negative)
+            return false;
+        index = 1;
+    }
+    let digits = 0;
+    let fraction = -1;
+    for (; index < text.length; index++) {
+        const char = text.charAt(index);
+        if (char >= "0" && char <= "9") {
+            digits++;
+            if (fraction >= 0)
+                fraction++;
+        }
+        else if (char === decimal && fraction < 0 && rules.decimals !== 0) {
+            fraction = 0;
+        }
+        else {
+            return false;
+        }
+    }
+    return digits <= MAX_NUMBER_DIGITS && (rules.decimals === undefined || fraction <= rules.decimals);
+}
+/**
+ * Removes what cannot be part of a number from text that reached the field unchecked (an input method, autofill, a drop),
+ * keeping the caret where it was relative to the text that stays. Digits are never removed.
+ */
+export function cleanNumberText(text, caret, decimal, rules) {
+    let output = "";
+    let nextCaret = caret;
+    let hasDecimal = false;
+    for (let index = 0; index < text.length; index++) {
+        const char = text.charAt(index) === MINUS_SIGN ? "-" : text.charAt(index);
+        const keep = (char >= "0" && char <= "9") ||
+            (char === "-" && output === "" && rules.negative) ||
+            (char === decimal && !hasDecimal && rules.decimals !== 0);
+        if (keep) {
+            output += char;
+            if (char === decimal)
+                hasDecimal = true;
+        }
+        else if (index < caret) {
+            nextCaret--;
+        }
+    }
+    return { text: output, caret: nextCaret };
+}
+/**
+ * Takes the number out of pasted text, such as "Rs 1,250.50", "1 250,50 €", or "-12%", and returns it as edit text
+ * ("1250.50"). Returns `null` when the text holds no single clear number, so a paste never turns into a wrong value.
+ */
+export function readPastedNumber(text, locale = DEFAULT_NUMBER_LOCALE) {
+    const { decimal, group } = getNumberSymbols(locale);
+    let clean = text.replace(BIDI_MARKS, "").replace(SPACES, "").replaceAll(MINUS_SIGN, "-");
+    if (group.trim())
+        clean = clean.replaceAll(group, "");
+    const first = clean.search(/\d/);
+    if (first < 0)
+        return null;
+    let start = first;
+    // A decimal separator before the first digit belongs to the number (".5"), unless it ends a word ("Rs.1250").
+    if (clean[start - 1] === decimal && !/[\p{L}.]/u.test(clean[start - 2] ?? ""))
+        start--;
+    if (clean[start - 1] === "-")
+        start--;
+    const last = clean.search(/\d\D*$/) + 1;
+    const number = clean.slice(start, last);
+    const valid = new RegExp(`^-?(?:\\d+(?:${escapeRegExp(decimal)}\\d*)?|${escapeRegExp(decimal)}\\d+)$`);
+    return valid.test(number) ? number : null;
+}
+/**
+ * Rounds to a number of decimal places the way people do: 1.005 → 1.01, and -2.5 → -3.
+ * Works on the number's shortest decimal text, so binary fractions such as 1.005 (stored as 1.00499…) round up.
+ */
+export function roundDecimal(value, digits) {
+    if (!Number.isFinite(value))
+        return value;
+    const [mantissa, exponent = "0"] = String(Math.abs(value)).split("e");
+    const shifted = Math.round(Number(`${mantissa}e${Number(exponent) + digits}`));
+    const rounded = Number(`${shifted}e${Number(exponent) - digits}`);
+    if (Number.isNaN(rounded))
+        return value;
+    return (value < 0 ? -rounded : rounded) || 0;
+}
+/** Keeps a value within `min` and `max`, each optional. */
+export function clampNumber(value, min, max) {
+    if (min !== undefined && value < min)
+        return min;
+    if (max !== undefined && value > max)
+        return max;
+    return value;
+}
+/** Digits after the decimal point of a number: 0.25 → 2, 1e-7 → 7. */
+export function countDecimals(value) {
+    const match = /(?:\.(\d+))?(?:e([+-]\d+))?$/.exec(String(value));
+    return Math.max(0, (match?.[1]?.length ?? 0) - Number(match?.[2] ?? 0));
+}
+/**
+ * The next value for an arrow key or a +/− button. Values move along the grid of `step` from `min` (or 0), so 2.3 with
+ * step 1 goes up to 3, and stay within `min` and `max`. An empty field starts at 0, or at the limit nearest to 0.
+ */
+export function stepNumber(value, direction, options = {}) {
+    const { min, max, decimals } = options;
+    const size = Math.abs(options.step ?? 1) || 1;
+    if (value === null || Number.isNaN(value)) {
+        const start = clampNumber(0, min, max);
+        if (start !== 0)
+            return start;
+        value = 0;
+    }
+    const base = min ?? 0;
+    const precision = Math.max(countDecimals(size), countDecimals(value), countDecimals(base));
+    // Rounded first, so float noise (0.30000000000000004 steps) does not skip or repeat a step.
+    const offset = roundDecimal((value - base) / size, 9);
+    const index = direction > 0 ? Math.floor(offset) + 1 : Math.ceil(offset) - 1;
+    let next = clampNumber(roundDecimal(base + index * size, precision), min, max);
+    if (decimals !== undefined)
+        next = roundDecimal(next, decimals);
+    return next;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/Helpers/Permissions.d.ts

@@ -0,0 +1,62 @@
+import type { ApiEndpoint, ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
+/** An app's permission rules. Subclasses answer `can`, and call `changed()` when the user's rights change. */
+export declare abstract class Permissions {
+    /** Whether the user may call this endpoint. */
+    abstract can(endpoint: ApiEndpoint): boolean;
+    /** Whether the rules are known yet. While they load, components show placeholders rather than "not allowed". */
+    get ready(): boolean;
+    /** Tells the page the rules changed (a sign-in, another branch), so buttons and lists show or hide. */
+    protected changed(): void;
+}
+/** Everyone may do everything. The rules until an app registers its own. */
+export declare class AllowAllPermissions extends Permissions {
+    can(): boolean;
+}
+/** One action a Nexus user may call, as the backend sends them (`AccessActions`, or the layout's `accessActions`). */
+export interface NexusAccessAction {
+    controllerName: string;
+    actionName: string;
+    /** The backend's `EHttpMethods` number (Get 0, Put 1, Delete 2, Post 3, Patch 6), or the method's name. */
+    httpMethod: number | string;
+    /** The modules the action belongs to: `NexusModule` flags, combined. */
+    modules: number;
+}
+/**
+ * The controller and the action of an endpoint's path, as a Nexus backend names them: "Room/Detail/{id}" is the
+ * `Detail` action of the `Room` controller. Values in braces are left out.
+ */
+export declare function endpointAction(path: string): {
+    controller: string;
+    action: string;
+};
+/**
+ * The Nexus rules: the user may call an endpoint when their access actions hold its controller, action, and method,
+ * for its module. Endpoints of the app's own routes (`NexusModule.None`) are always allowed.
+ *
+ * @example
+ * const permissions = definePermissions(new NexusPermissions());
+ * permissions.setActions(layout.accessActions);   // after sign-in, from the backend
+ */
+export declare class NexusPermissions extends Permissions {
+    private actions;
+    /** `actions`: the user's access actions, or `null` while they load. */
+    constructor(actions?: readonly NexusAccessAction[] | null);
+    get ready(): boolean;
+    /** Replaces the user's access actions, such as after sign-in or a switch of branch. `null`: not known yet. */
+    setActions(actions: readonly NexusAccessAction[] | null): void;
+    private index;
+    can(endpoint: ApiEndpoint<ApiModuleValue>): boolean;
+}
+/**
+ * Registers the app's permission rules, once, in a module the root layout loads (the same place as its API modules).
+ * Returns them, so the app can keep a handle to update them after sign-in.
+ */
+export declare function definePermissions<T extends Permissions>(permissions: T): T;
+/** The app's permission rules: the registered ones, or `AllowAllPermissions`. */
+export declare function getPermissions(): Permissions;
+/** Whether the user may call this endpoint, by the app's rules. */
+export declare function canCall(endpoint: ApiEndpoint | null | undefined): boolean;
+/** For `useSyncExternalStore`: listens for new rules or changed rights. */
+export declare function subscribePermissions(listener: () => void): () => void;
+/** For `useSyncExternalStore`: a number that changes whenever the rules do. */
+export declare const permissionsVersion: () => number;

package/dist/Helpers/Permissions.js

@@ -0,0 +1,133 @@
+/*
+ * Permissions: may the user call this endpoint? Components ask before they show a button or a list (the CRUD's Add,
+ * Delete, and its Trash list), so a user sees only what they may do; the server still checks every call.
+ *
+ * `Permissions` is the interface an app implements, for its own backend's rules; `NexusPermissions` reads the Nexus
+ * backend's access actions. Register one with `definePermissions`. Until then everything is allowed, which suits an
+ * app without sign-in.
+ */
+/** An app's permission rules. Subclasses answer `can`, and call `changed()` when the user's rights change. */
+export class Permissions {
+    /** Whether the rules are known yet. While they load, components show placeholders rather than "not allowed". */
+    get ready() {
+        return true;
+    }
+    /** Tells the page the rules changed (a sign-in, another branch), so buttons and lists show or hide. */
+    changed() {
+        if (current === this)
+            notify();
+    }
+}
+/** Everyone may do everything. The rules until an app registers its own. */
+export class AllowAllPermissions extends Permissions {
+    can() {
+        return true;
+    }
+}
+const NEXUS_METHODS = { GET: 0, PUT: 1, DELETE: 2, POST: 3, PATCH: 6 };
+function methodName(method) {
+    if (typeof method === "string")
+        return method.toUpperCase();
+    return Object.keys(NEXUS_METHODS).find(name => NEXUS_METHODS[name] === method);
+}
+/**
+ * The controller and the action of an endpoint's path, as a Nexus backend names them: "Room/Detail/{id}" is the
+ * `Detail` action of the `Room` controller. Values in braces are left out.
+ */
+export function endpointAction(path) {
+    const parts = path.split("/").filter(part => part && !part.startsWith("{"));
+    const action = parts.pop() ?? "";
+    return { controller: parts.join("/"), action };
+}
+const actionKey = (controller, action, method) => `${controller.toLowerCase()}|${action.toLowerCase()}|${method}`;
+/**
+ * The Nexus rules: the user may call an endpoint when their access actions hold its controller, action, and method,
+ * for its module. Endpoints of the app's own routes (`NexusModule.None`) are always allowed.
+ *
+ * @example
+ * const permissions = definePermissions(new NexusPermissions());
+ * permissions.setActions(layout.accessActions);   // after sign-in, from the backend
+ */
+export class NexusPermissions extends Permissions {
+    actions = null;
+    /** `actions`: the user's access actions, or `null` while they load. */
+    constructor(actions = null) {
+        super();
+        if (actions)
+            this.index(actions);
+    }
+    get ready() {
+        return this.actions !== null;
+    }
+    /** Replaces the user's access actions, such as after sign-in or a switch of branch. `null`: not known yet. */
+    setActions(actions) {
+        if (actions)
+            this.index(actions);
+        else
+            this.actions = null;
+        this.changed();
+    }
+    index(actions) {
+        const map = new Map();
+        for (const item of actions) {
+            const method = methodName(item.httpMethod);
+            if (!method || !item.controllerName || !item.actionName)
+                continue;
+            const key = actionKey(item.controllerName, item.actionName, method);
+            const list = map.get(key);
+            if (list)
+                list.push(Number(item.modules) || 0);
+            else
+                map.set(key, [Number(item.modules) || 0]);
+        }
+        this.actions = map;
+    }
+    // Any module value, whichever type the app registers: a number is read as flags, text as it is.
+    can(endpoint) {
+        if (endpoint.module === 0)
+            return true;
+        if (!this.actions)
+            return false;
+        const { controller, action } = endpointAction(endpoint.path);
+        const modules = this.actions.get(actionKey(controller, action, endpoint.method));
+        if (!modules)
+            return false;
+        const module = endpoint.module;
+        // An action's modules are flags: it belongs to every module whose bit is set.
+        return modules.some(flags => (typeof module === "number" ? (flags & module) === module : String(flags) === String(module)));
+    }
+}
+let current = new AllowAllPermissions();
+let version = 0;
+const listeners = new Set();
+function notify() {
+    version++;
+    for (const listener of listeners)
+        listener();
+}
+/**
+ * Registers the app's permission rules, once, in a module the root layout loads (the same place as its API modules).
+ * Returns them, so the app can keep a handle to update them after sign-in.
+ */
+export function definePermissions(permissions) {
+    current = permissions;
+    notify();
+    return permissions;
+}
+/** The app's permission rules: the registered ones, or `AllowAllPermissions`. */
+export function getPermissions() {
+    return current;
+}
+/** Whether the user may call this endpoint, by the app's rules. */
+export function canCall(endpoint) {
+    return Boolean(endpoint) && current.can(endpoint);
+}
+/** For `useSyncExternalStore`: listens for new rules or changed rights. */
+export function subscribePermissions(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/** For `useSyncExternalStore`: a number that changes whenever the rules do. */
+export const permissionsVersion = () => version;

package/dist/Helpers/PopoverHelpers.d.ts

@@ -0,0 +1,68 @@
+/** Which side of its anchor a panel opened on: `below` carries its arrow on its top edge, `above` on its bottom edge. */
+export type PanelSide = "below" | "above";
+export type PopoverAlign = "start" | "end";
+export interface PlaceUnderAnchorOptions {
+    /** Which edge of the anchor the panel lines up with. Default `start` (the left edge). */
+    align?: PopoverAlign;
+    /** Space between the anchor and the panel, in pixels. Default 4, or the arrow's reach while it is drawn. */
+    gap?: number;
+    /** Space kept from the window's edges, in pixels. Default 8. */
+    margin?: number;
+    /**
+     * Draws an arrow on the panel's edge, aimed at the middle of the anchor. Default true: a panel opened from a button
+     * says which button. Pass false for a panel that opens flush under a field and is read as part of it.
+     */
+    arrow?: boolean;
+    /**
+     * What the arrow points at, when the panel lines up with more than that: the half of a split button that opened it.
+     * Default: the anchor itself.
+     */
+    arrowAt?: DOMRect;
+}
+/**
+ * Places a panel under an anchor, or above it when there is no room below, aligned to the anchor's start or end
+ * edge and kept inside the window, with an arrow aimed at the anchor. Returns whether the panel went above.
+ */
+export declare function placeUnderAnchor(panel: HTMLElement, anchor: DOMRect, options?: PlaceUnderAnchorOptions): boolean;
+export interface PlaceListPanelOptions {
+    /** The side of an earlier call, kept while it has `minHeight` of room, so a list that loads more items does not jump across its anchor. */
+    side?: PanelSide;
+    /** The tallest the panel may be, in pixels. Default 360. */
+    maxHeight?: number;
+    /** A side is used while at least this much room is there, in pixels; with less, the other side is used when it has more. Default 180. */
+    minHeight?: number;
+    /** Space between the anchor and the panel, in pixels. Default 4. */
+    gap?: number;
+    /** Space kept from the window's edges, in pixels. Default 8. */
+    margin?: number;
+}
+/**
+ * Places a list panel under its anchor, at least as wide as the anchor, or above it when the room below is short and
+ * there is more above. The panel's height is capped to the room on its side, so a long list scrolls inside the window
+ * instead of running past it. Returns the side, to pass back while the panel stays open.
+ *
+ * It draws no arrow: the panel is as wide as the field and sits flush under it, so it is already read as that field's
+ * list, and an arrow over a field's own border would look like a fault.
+ */
+export declare function placeListPanel(panel: HTMLElement, anchor: DOMRect, options?: PlaceListPanelOptions): PanelSide;
+export interface PlaceAtPointOptions {
+    /** Space kept from the window's edges, in pixels. Default 8. */
+    margin?: number;
+    /**
+     * Draws an arrow with its tip on the point, so the menu says where it was opened. Default true. The panel then
+     * stands the arrow's reach away from the point, and its corner no longer sits on it.
+     */
+    arrow?: boolean;
+}
+/**
+ * Places a panel at a point, such as where the user right-clicked: to the right of and below the point when there
+ * is room, otherwise to the left of or above it, and never past the window's edges. With an arrow, the panel is set
+ * back far enough along both axes for the arrow's tip to land on the point.
+ */
+export declare function placeAtPoint(panel: HTMLElement, x: number, y: number, options?: PlaceAtPointOptions): void;
+/** Runs `place` again, once per frame at most, while the page scrolls or the window changes size. Returns the stop function. */
+export declare function followAnchor(place: () => void): () => void;
+/** Whether the popover is shown. Safe on browsers without popover support, where it is never "open". */
+export declare function isPopoverOpen(panel: HTMLElement | null): boolean;
+/** How far the arrow reaches past the panel's edge: its depth, less the panel's border it is drawn over. */
+export declare const ARROW_REACH: number;

package/dist/Helpers/PopoverHelpers.js

@@ -0,0 +1,195 @@
+/*
+ * Placing native popovers. A panel is a fixed [popover] element; these helpers set its top and left once it is shown,
+ * keep it inside the window, and move it again while the page scrolls. They measure offsetWidth and offsetHeight,
+ * which ignore the panel's opening transform.
+ *
+ * A panel that belongs to a button or to a place also gets an arrow, so the panel is read as that button's panel and
+ * not as a dialog from nowhere. These helpers work out where the arrow goes, because they are the only code that
+ * knows both rectangles; `.nx-popover` draws it from what they write (see "The arrow" below).
+ */
+/**
+ * Places a panel under an anchor, or above it when there is no room below, aligned to the anchor's start or end
+ * edge and kept inside the window, with an arrow aimed at the anchor. Returns whether the panel went above.
+ */
+export function placeUnderAnchor(panel, anchor, options = {}) {
+    const { align = "start", margin = 8, arrow = true } = options;
+    // The arrow needs its reach between the panel and the anchor, or it would be drawn over the anchor.
+    const gap = Math.max(options.gap ?? 4, arrow ? ARROW_REACH : 0);
+    const width = panel.offsetWidth;
+    const height = panel.offsetHeight;
+    const below = anchor.bottom + gap;
+    const above = anchor.top - gap - height;
+    const fitsBelow = below + height <= window.innerHeight - margin;
+    const top = fitsBelow || above < margin ? below : above;
+    const wanted = align === "end" ? anchor.right - width : anchor.left;
+    // The arrow points at the middle of what it belongs to. The panel's own style is read once: this runs again on
+    // every animation frame while the page scrolls under an open panel.
+    const target = options.arrowAt ?? anchor;
+    const middle = (target.left + target.right) / 2;
+    const style = getComputedStyle(panel);
+    const left = Math.max(margin, Math.min(arrow ? centred(panel, target, wanted, width, middle, style) : wanted, window.innerWidth - width - margin));
+    panel.style.top = `${Math.round(top)}px`;
+    panel.style.left = `${Math.round(left)}px`;
+    const side = top === below ? "below" : "above";
+    const box = { left: Math.round(left), top: Math.round(top), width, height };
+    aimArrow(panel, side, box, arrow ? { at: middle, facing: side === "below" ? target.bottom : target.top, room: gap } : null, style);
+    return side === "above";
+}
+/**
+ * Places a list panel under its anchor, at least as wide as the anchor, or above it when the room below is short and
+ * there is more above. The panel's height is capped to the room on its side, so a long list scrolls inside the window
+ * instead of running past it. Returns the side, to pass back while the panel stays open.
+ *
+ * It draws no arrow: the panel is as wide as the field and sits flush under it, so it is already read as that field's
+ * list, and an arrow over a field's own border would look like a fault.
+ */
+export function placeListPanel(panel, anchor, options = {}) {
+    const { maxHeight = 360, minHeight = 180, gap = 4, margin = 8 } = options;
+    const roomBelow = window.innerHeight - anchor.bottom - gap - margin;
+    const roomAbove = anchor.top - gap - margin;
+    const enough = Math.min(minHeight, maxHeight);
+    let side = options.side ?? (roomBelow >= enough || roomBelow >= roomAbove ? "below" : "above");
+    // An earlier side is kept while it has room. When the anchor grows (chips wrapping in a dropdown's box) or the page
+    // moves until that side has less than minHeight, and the other side has more, the panel moves across instead of
+    // shrinking to nothing.
+    const room = side === "below" ? roomBelow : roomAbove;
+    const otherRoom = side === "below" ? roomAbove : roomBelow;
+    if (room < enough && otherRoom > room)
+        side = side === "below" ? "above" : "below";
+    // Runs after every render of an open list: styles are written only when they change.
+    setStyle(panel, "minWidth", `${Math.round(Math.min(anchor.width, window.innerWidth - 2 * margin))}px`);
+    setStyle(panel, "maxHeight", `${Math.max(0, Math.floor(Math.min(maxHeight, side === "below" ? roomBelow : roomAbove)))}px`);
+    const width = panel.offsetWidth;
+    const height = panel.offsetHeight;
+    const top = side === "below" ? anchor.bottom + gap : anchor.top - gap - height;
+    const left = Math.max(margin, Math.min(anchor.left, window.innerWidth - width - margin));
+    setStyle(panel, "top", `${Math.round(top)}px`);
+    setStyle(panel, "left", `${Math.round(left)}px`);
+    return side;
+}
+function setStyle(element, property, value) {
+    if (element.style[property] !== value)
+        element.style[property] = value;
+}
+/**
+ * Places a panel at a point, such as where the user right-clicked: to the right of and below the point when there
+ * is room, otherwise to the left of or above it, and never past the window's edges. With an arrow, the panel is set
+ * back far enough along both axes for the arrow's tip to land on the point.
+ */
+export function placeAtPoint(panel, x, y, options = {}) {
+    const { margin = 8, arrow = true } = options;
+    const width = panel.offsetWidth;
+    const height = panel.offsetHeight;
+    // The tip sits `lead` along the panel's edge and `ARROW_REACH` out from it, so the panel starts that much back.
+    const lead = arrow ? arrowLead(panel) : 0;
+    const reach = arrow ? ARROW_REACH : 0;
+    let left = x - lead;
+    let top = y + reach;
+    if (left + width > window.innerWidth - margin)
+        left = x + lead - width;
+    if (top + height > window.innerHeight - margin)
+        top = y - reach - height;
+    const placed = {
+        left: Math.round(Math.max(margin, Math.min(left, window.innerWidth - width - margin))),
+        top: Math.round(Math.max(margin, Math.min(top, window.innerHeight - height - margin))),
+        width,
+        height,
+    };
+    panel.style.left = `${placed.left}px`;
+    panel.style.top = `${placed.top}px`;
+    const side = placed.top >= y ? "below" : "above";
+    aimArrow(panel, side, placed, arrow ? { at: x, facing: y, room: reach } : null);
+}
+/** Runs `place` again, once per frame at most, while the page scrolls or the window changes size. Returns the stop function. */
+export function followAnchor(place) {
+    let frame = 0;
+    const reposition = () => {
+        cancelAnimationFrame(frame);
+        frame = requestAnimationFrame(place);
+    };
+    window.addEventListener("scroll", reposition, { capture: true, passive: true });
+    window.addEventListener("resize", reposition);
+    return () => {
+        cancelAnimationFrame(frame);
+        window.removeEventListener("scroll", reposition, { capture: true });
+        window.removeEventListener("resize", reposition);
+    };
+}
+/** Whether the popover is shown. Safe on browsers without popover support, where it is never "open". */
+export function isPopoverOpen(panel) {
+    return Boolean(panel && typeof panel.matches === "function" && panel.matches(":popover-open"));
+}
+/* ---------------------------------------------------------------------------------------------------------------
+ * The arrow
+ *
+ * An isosceles tail on the panel's edge, drawn in the panel's own border and background, so the two read as one
+ * shape in every theme: `.nx-popover[data-nx-arrow]::before` and `::after` in Nexus.Theme.Picker.css. These
+ * functions write the two things only the placement knows: which edge carries the tail (`data-nx-arrow`) and where
+ * along that edge its tip sits (`--nx-popover-arrow-x`). Both are cleared when it would point at nothing, and no
+ * component has to take part.
+ * ------------------------------------------------------------------------------------------------------------- */
+/** The arrow's base, across the panel's edge. Keep in step with `--nx-popover-arrow` in the `.nx-popover` rule. */
+const ARROW_BASE = 26;
+/** The arrow's depth, out from the panel's edge. Keep in step with `--nx-popover-arrow-depth`. */
+const ARROW_DEPTH = 11;
+/** Half the arrow's base: how far from its tip each foot stands. */
+const ARROW_HALF = ARROW_BASE / 2;
+/** How far the arrow reaches past the panel's edge: its depth, less the panel's border it is drawn over. */
+export const ARROW_REACH = ARROW_DEPTH - 1;
+/**
+ * How far along the panel's edge the arrow's tip has to stay: its own half base, the panel's rounded corner, and two
+ * pixels more, so a foot never stands on the curve and the tail is never read as a torn-off corner.
+ */
+function arrowLead(panel) {
+    const style = panel instanceof HTMLElement ? getComputedStyle(panel) : panel;
+    return (parseFloat(style.borderTopLeftRadius) || 0) + ARROW_HALF + 2;
+}
+/**
+ * Where a panel starts along its edge so that its arrow stands on the middle of the anchor.
+ *
+ * The tip may not stand on a rounded corner, so it keeps `lead` from each end of the panel. An **icon button** is
+ * narrower than two leads, so a panel lined up with it would hold the tip short of its middle: the panel slides
+ * along its edge instead, past the end of the button, by half the button's width at most.
+ *
+ * A **wide anchor keeps its alignment**, whatever the arrow can reach. A menu belongs at the start of the row,
+ * the cell, or the field it opened from - sliding it to the middle of a 900px row would move it right across the
+ * page - so the arrow aims as far as it can there and is left out when that is more than half a base off, which is
+ * what it did before any of this. The window's edges still win over both.
+ */
+function centred(panel, anchor, wanted, width, at, style) {
+    const lead = arrowLead(style);
+    // Only a button too small to be aimed at while the panel lines up with it is worth moving the panel for.
+    if (anchor.width >= lead * 2 || width < lead * 2)
+        return wanted;
+    // The far end carries a pixel more than the lead: `width` is offsetWidth, a whole number, while the panel itself
+    // is fractionally wider, which would otherwise leave the foot that much nearer the curve than the lead promises.
+    return Math.min(Math.max(wanted, at - width + lead + 1), at - lead);
+}
+/**
+ * Aims the panel's arrow, or leaves it out. The tip is kept clear of the panel's rounded corners, and the arrow is
+ * left out when it would point at nothing: the target is off the window, the panel is too narrow to carry an arrow
+ * clear of its corners, the panel was pushed along its edge until the tip is more than half a base from the target,
+ * or it was pushed away from the target across the edge.
+ */
+function aimArrow(panel, side, box, aim, drawn = getComputedStyle(panel)) {
+    if (aim) {
+        const lead = arrowLead(drawn);
+        const x = Math.min(Math.max(aim.at - box.left, lead), box.width - lead);
+        const edge = side === "below" ? box.top : box.top + box.height;
+        const tip = box.left + x;
+        const points = box.width >= lead * 2 && Math.abs(tip - aim.at) <= ARROW_HALF && Math.abs(edge - aim.facing) <= aim.room + 1;
+        if (points && onScreen(aim.facing, aim.at)) {
+            panel.dataset.nxArrow = side;
+            // An absolutely placed arrow starts at the panel's padding box, so the border it is drawn over comes off here.
+            const inside = x - (parseFloat(drawn.borderLeftWidth) || 0);
+            panel.style.setProperty("--nx-popover-arrow-x", `${Math.round(inside * 10) / 10}px`);
+            return;
+        }
+    }
+    delete panel.dataset.nxArrow;
+    panel.style.removeProperty("--nx-popover-arrow-x");
+}
+/** Whether what the arrow points at is still in the window: a button scrolled out of sight gets no arrow. */
+function onScreen(across, along) {
+    return across >= 0 && across <= window.innerHeight && along >= 0 && along <= window.innerWidth;
+}