nexus-shared 2.0.0 → 3.0.0

package/dist/Helpers/ExcelHelpers.js

@@ -0,0 +1,302 @@
+import { ExcelDataType, ExcelRowKind } from "../Interfaces/ExcelInterfaces.js";
+/*
+ * Turning a sheet's columns into inputs, a verify's rows into editable rows and back, and handing the person a file.
+ * Nothing here calls anything: the calls are in Services/ExcelApi.ts.
+ *
+ * Two rules decide every reading below, and both come from the backend:
+ *   - every value travels as **text**, the way it reads in the sheet, because one wire shape serves a verify and an
+ *     import and the import reads it with the same parser that read the file;
+ *   - a choice travels as its **key** and never as an id, so a reference cell is shown as the words the person picked
+ *     and the key beside it is carried through untouched.
+ */
+/** What a spreadsheet file is called in a file picker. */
+export const EXCEL_FILE_ACCEPT = ".xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+/** The field of an editor row that holds the sheet row it came from. Not a column, so no input is drawn for it. */
+export const EXCEL_ROW_NUMBER = "__excelRow";
+/** The field of an editor row that holds each reference column's key, which the person never sees or types. */
+export const EXCEL_ROW_KEYS = "__excelKeys";
+/** The field of an editor row that holds what the verify answered for it, so an edit can be told from an untouched row. */
+export const EXCEL_ROW_SENT = "__excelSent";
+/* Texts of the spreadsheet side. One table, so a word is changed or translated in one place. */
+const DEFAULT_TEXT = {
+    template: "Download template",
+    templateHint: "The file to fill in: every list is a dropdown, and the ids beside a choice fill themselves.",
+    choose: "Choose file",
+    change: "Choose another file",
+    checking: "Checking",
+    nothingPicked: "No file picked yet.",
+    verifyFailed: "The file could not be read.",
+    newRows: "New rows",
+    duplicates: "Already there",
+    duplicateHint: "Nothing here is updated. Edit a row to add it as a new record instead.",
+    toFix: "What needs fixing",
+    whyDuplicate: "Why these are already there",
+    referenceLocked: "Picked in the spreadsheet: this list belongs to the server.",
+    generated: "The file fills this in.",
+    importLabel: "Import",
+    importNothing: "There is no row to import.",
+    importedNone: "Nothing was written.",
+    refused: "Not written",
+    exportWarning: "Export is cut short",
+    close: "Close",
+    startOver: "Start over",
+};
+let texts = { ...DEFAULT_TEXT };
+/** Rewords or translates the spreadsheet side's own texts. Names only what changes. */
+export function configureExcelText(changes) {
+    texts = { ...texts, ...changes };
+}
+/** One of the spreadsheet side's texts. */
+export function excelText(key) {
+    return texts[key];
+}
+/* Columns as inputs */
+/** How wide a column is drawn, by what it holds. The template sizes its own columns the same way. */
+const COLUMN_WIDTH = {
+    [ExcelDataType.Text]: "12rem",
+    [ExcelDataType.Note]: "20rem",
+    [ExcelDataType.WholeNumber]: "8rem",
+    [ExcelDataType.Decimal]: "8rem",
+    [ExcelDataType.Amount]: "9rem",
+    [ExcelDataType.Date]: "9.5rem",
+    [ExcelDataType.DateTime]: "12rem",
+    [ExcelDataType.Time]: "7.5rem",
+    [ExcelDataType.YesNo]: "7rem",
+    [ExcelDataType.List]: "16rem",
+};
+/** The shapes a zone-less moment may be written in, as the backend reads them. */
+const MOMENT_PATTERN = {
+    source: "[0-9]{4}[-/][0-9]{2}[-/][0-9]{2}([ T][0-9]{2}:[0-9]{2}(:[0-9]{2})?)?",
+    message: "Write a date and time as 2026-09-29 14:30.",
+};
+const YES_NO = [
+    { value: "Yes", label: "Yes" },
+    { value: "No", label: "No" },
+];
+/**
+ * One column of a sheet as an input of the review editors. The rules are the ones the sheet told the person about and
+ * no others, so a fix made here is checked the way the file was.
+ *
+ * Three columns are read-only on purpose:
+ * - a **reference**, because its list is the backend's and is picked in the spreadsheet; the cell shows the words the
+ *   person picked and the key travels back untouched (a key read out of an answer is never typed, and never an id);
+ * - a column the **file** fills;
+ * - and a **date and time** is a text box rather than a picker, because the sheet's moment is a zone-less wall clock
+ *   while the picker's value is a UTC moment: a picker here would shift every value by the person's own offset.
+ */
+export function excelColumnInput(column) {
+    const shared = {
+        name: column.field,
+        label: column.header,
+        width: COLUMN_WIDTH[column.dataType] ?? "12rem",
+        ...(column.note ? { hint: column.note } : {}),
+    };
+    const required = column.isRequired === true;
+    const lengths = {
+        ...(column.minLength && column.minLength > 0 ? { minLength: column.minLength } : {}),
+        ...(column.maxLength && column.maxLength > 0 ? { maxLength: column.maxLength } : {}),
+    };
+    const limits = {
+        ...(column.minimum === null || column.minimum === undefined ? {} : { min: column.minimum }),
+        ...(column.maximum === null || column.maximum === undefined ? {} : { max: column.maximum }),
+    };
+    if (column.isReference)
+        return { ...shared, type: "text", readOnly: true, readOnlyMessage: excelText("referenceLocked") };
+    if (column.isReadOnly)
+        return { ...shared, type: "text", readOnly: true, readOnlyMessage: excelText("generated") };
+    switch (column.dataType) {
+        case ExcelDataType.Note:
+            return { ...shared, type: "textarea", rows: 2, required, ...lengths };
+        case ExcelDataType.WholeNumber:
+            return { ...shared, type: "number", required, decimals: 0, ...limits };
+        case ExcelDataType.Decimal:
+            return { ...shared, type: "number", required, ...limits };
+        case ExcelDataType.Amount:
+            return { ...shared, type: "number", required, decimals: 2, fixedDecimals: true, grouping: true, ...limits };
+        case ExcelDataType.Date:
+            return { ...shared, type: "date", required };
+        case ExcelDataType.DateTime:
+            return { ...shared, type: "text", required, pattern: MOMENT_PATTERN, placeholder: "2026-09-29 14:30" };
+        case ExcelDataType.Time:
+            return { ...shared, type: "time", required };
+        case ExcelDataType.YesNo:
+            return { ...shared, type: "dropdown", required, options: YES_NO, searchable: false };
+        default:
+            return { ...shared, type: "text", required, ...lengths };
+    }
+}
+/** Every column of a sheet as the inputs of one editor row, in the order they read. */
+export function excelColumnInputs(columns) {
+    return columns.map(excelColumnInput);
+}
+/* Rows, both ways */
+/** Whether the person edits this column's cell at all, or only reads it. */
+export function isExcelColumnEditable(column) {
+    return column.isReference !== true && column.isReadOnly !== true;
+}
+/**
+ * A verify's rows as the editors' rows: a value per column, the sheet's row number, and - held beside them, never
+ * drawn - each reference column's key and the values the verify answered with.
+ *
+ * A reference cell shows the **words** the person picked, because its key is not something anybody reads or types.
+ */
+export function excelEditorRows(rows, columns) {
+    return rows.map(row => {
+        const keys = {};
+        const editor = { [EXCEL_ROW_NUMBER]: row.number, [EXCEL_ROW_KEYS]: keys, [EXCEL_ROW_SENT]: { ...row.values } };
+        for (const column of columns) {
+            const value = row.values[column.field] ?? null;
+            if (column.isReference) {
+                keys[column.field] = value;
+                editor[column.field] = row.labels?.[column.field] ?? "";
+                continue;
+            }
+            editor[column.field] = toInputValue(column, value);
+        }
+        return editor;
+    });
+}
+/** Which types are drawn by a number box, whose empty value is `null`. */
+const NUMBER_TYPES = new Set([ExcelDataType.WholeNumber, ExcelDataType.Decimal, ExcelDataType.Amount]);
+/**
+ * A cell's text as the input that draws it wants it: a number as a number, a choice unset rather than empty, and
+ * everything else as it reads.
+ *
+ * The three empties are not interchangeable. A number box is empty at `null`; a **dropdown** given `""` treats it as a
+ * value and reports it as one its list no longer offers ("Not found"), so an empty choice has to be left unset; a text
+ * or date box is empty at `""`.
+ */
+function toInputValue(column, value) {
+    if (value === null || value === "")
+        return NUMBER_TYPES.has(column.dataType) ? null : column.dataType === ExcelDataType.YesNo ? undefined : "";
+    switch (column.dataType) {
+        case ExcelDataType.WholeNumber:
+        case ExcelDataType.Decimal:
+        case ExcelDataType.Amount: {
+            const number = Number(value.replace(/,/g, ""));
+            return Number.isFinite(number) ? number : null;
+        }
+        case ExcelDataType.YesNo: {
+            const upper = value.trim().toUpperCase();
+            if (upper === "YES" || upper === "Y" || upper === "TRUE" || upper === "1")
+                return "Yes";
+            if (upper === "NO" || upper === "N" || upper === "FALSE" || upper === "0")
+                return "No";
+            return value;
+        }
+        default:
+            return value;
+    }
+}
+/** A cell as it travels: text, the way it reads in the sheet. A value the editors could not hold is sent back as it came. */
+function toSheetValue(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "boolean")
+        return value ? "Yes" : "No";
+    const written = String(value).trim();
+    return written.length ? written : null;
+}
+/**
+ * Whether a cell still holds what the verify answered for it.
+ *
+ * It is not a comparison of texts, because a cell goes through an input on the way: a sheet that read `38450.50` comes
+ * back from a number box as `38450.5`, and `TRUE` comes back from the Yes/No choice as `Yes`. Both are the same value
+ * and neither is an edit, so the two are compared the way the input holds them.
+ */
+function isSameCell(column, current, sent) {
+    const asSheet = toSheetValue(current);
+    if (asSheet === (sent ?? null))
+        return true;
+    return toInputValue(column, asSheet) === toInputValue(column, sent ?? null);
+}
+/**
+ * The editors' rows as rows to send: every value as text, every reference as the key it came with, and the sheet's own
+ * row number kept so a problem can still name where it is.
+ *
+ * A cell the person did not touch goes back **exactly** as it came, which is what makes the round trip faithful: the
+ * backend reads its own text again, not a number an input rewrote on the way through.
+ */
+export function excelSheetRows(rows, columns) {
+    return rows.map((row, index) => {
+        const keys = (row[EXCEL_ROW_KEYS] ?? {});
+        const sent = (row[EXCEL_ROW_SENT] ?? {});
+        const values = {};
+        const labels = {};
+        for (const column of columns) {
+            if (column.isReference) {
+                values[column.field] = keys[column.field] ?? null;
+                labels[column.field] = toSheetValue(row[column.field]);
+                continue;
+            }
+            values[column.field] = isSameCell(column, row[column.field], sent[column.field]) ? (sent[column.field] ?? null) : toSheetValue(row[column.field]);
+        }
+        const number = Number(row[EXCEL_ROW_NUMBER]);
+        return { number: Number.isFinite(number) && number > 0 ? number : index + 1, values, labels };
+    });
+}
+/** Whether the person changed anything in a row since the verify answered it. */
+export function isExcelRowEdited(row, columns) {
+    const sent = (row[EXCEL_ROW_SENT] ?? {});
+    for (const column of columns) {
+        if (!isExcelColumnEditable(column))
+            continue;
+        if (!isSameCell(column, row[column.field], sent[column.field]))
+            return true;
+    }
+    return false;
+}
+/* What is wrong, in the person's words */
+/** Where a problem is, as the person reads it: the cell, a middle dot, and the column's heading ("B7 - City name"). */
+export function excelProblemPlace(problem) {
+    return problem.cell ? `${problem.cell} ${String.fromCharCode(183)} ${problem.header}` : problem.header;
+}
+/** Every problem of these rows, in the order the rows read. */
+export function excelProblems(rows) {
+    return rows.flatMap(row => row.problems ?? []);
+}
+/** The rows of one kind. */
+export function excelRowsOfKind(rows, ...kinds) {
+    return rows.filter(row => kinds.includes(row.kind));
+}
+/** The rows an import would try to write: the new ones, and the ones still waiting on a fix. */
+export function excelWritableRows(rows) {
+    return excelRowsOfKind(rows, ExcelRowKind.New, ExcelRowKind.Invalid);
+}
+/** More than one of the subject: "cities", "boxes", "rows". An English ending, which a text change can replace. */
+export function excelPlural(subject, plural) {
+    if (plural)
+        return plural;
+    if (/(s|x|z|ch|sh)$/i.test(subject))
+        return `${subject}es`;
+    if (/[^aeiou]y$/i.test(subject))
+        return `${subject.slice(0, -1)}ies`;
+    return `${subject}s`;
+}
+/** A count said in the subject's own words: "1 city", "12 cities". */
+export function excelCount(rows, subject, plural) {
+    if (rows === 1)
+        return `1 ${subject}`;
+    return `${rows.toLocaleString("en-US")} ${excelPlural(subject, plural)}`;
+}
+/**
+ * What to tell the person before an export that will be cut short, as the owner asked: what is on screen, what will be
+ * written, and that filtering is how they get the rest.
+ */
+export function excelExportWarning(rows, limit, subject) {
+    return `The search on screen leaves ${excelCount(rows, subject)}, and one export writes at most ${limit.toLocaleString("en-US")}. The first ${limit.toLocaleString("en-US")} are written and the rest are left out. Search or filter for the rows you need to get them all.`;
+}
+/* The file itself */
+/** Hands the person a file to save, under the name the answer gave it. */
+export function saveExcelFile(download) {
+    const url = URL.createObjectURL(download.blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = download.fileName;
+    link.rel = "noopener";
+    document.body.append(link);
+    link.click();
+    link.remove();
+    // Firefox needs the object URL a moment longer than the click.
+    setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}

package/dist/Helpers/FormStore.d.ts

@@ -209,6 +209,8 @@ export declare class FormStore<TValues extends FormValues = FormValues> {
     /** Inputs that were not there, or were hidden, get their value in the input's type, as a load gives it. */
     private adoptNewInputs;
     private change;
+    /** The inputs whose `dependsOn` names any of `names`. */
+    private followersOf;
     private checkRule;
     private checkAllRules;
     /** Runs the form's own rule; returns the inputs whose message from it changed. */

package/dist/Helpers/FormStore.js

@@ -572,12 +572,19 @@ export class FormStore {
                             write(field, value, "code");
             }
         }
+        // Inputs that follow a changed one (`dependsOn`) draw again with their params read afresh, and their rule is asked
+        // again: a getter may have just made one required, read-only or hidden.
+        const followers = this.followersOf(written);
+        for (const name of followers) {
+            remember(name);
+            this.checkRule(name);
+        }
         // The form's rule runs again: an input it now names, or no longer names, shows the change even if nobody typed in it.
         for (const name of this.checkCross())
             if (!shown.has(name))
                 shown.set(name, this.shownWith(name, crossBefore));
         for (const [name, before] of shown)
-            if (remounted.has(name) || this.shownError(name) !== before)
+            if (remounted.has(name) || followers.has(name) || this.shownError(name) !== before)
                 this.bump(name);
         this.patchStatus({ changed: this.changedNames.size > 0, message: this.formMessage(), problems: this.problemList() });
         this.emit(source === "input" ? written[0] : written.length === 1 ? written[0] : null);
@@ -586,6 +593,17 @@ export class FormStore {
             this.draftDropped = false;
         this.scheduleDraft();
     }
+    /** The inputs whose `dependsOn` names any of `names`. */
+    followersOf(names) {
+        const found = new Set();
+        if (!names.length)
+            return found;
+        const changed = new Set(names);
+        for (const params of this.options.inputs)
+            if (params.dependsOn?.some(name => changed.has(name)))
+                found.add(params.name);
+        return found;
+    }
     checkRule(name) {
         const params = this.inputByName.get(name);
         if (params && isRowsInput(params)) {

package/dist/Helpers/MessageBuilder.js

@@ -11,7 +11,6 @@ const DEFAULT_WORDS = {
     update: { verb: "update", done: "updated", doing: "Updating", object: "the record", sendsValues: true },
     delete: { verb: "delete", done: "deleted", doing: "Deleting", object: "the record" },
     trash: { verb: "move {object} to the trash", done: "moved to the trash", doing: "Moving {object} to the trash", object: "the record" },
-    archive: { verb: "archive", done: "archived", doing: "Archiving", object: "the record" },
     restore: { verb: "restore", done: "restored", doing: "Restoring", object: "the record" },
     recover: { verb: "recover", done: "recovered", doing: "Recovering", object: "the record" },
     flag: { verb: "flag", done: "flagged", doing: "Flagging", object: "the record" },
@@ -44,7 +43,6 @@ const DEFAULT_TEXTS = {
     confirmDetails: {
         delete: "This cannot be undone.",
         trash: "It can be restored from the trash.",
-        archive: "It can be restored from the archive.",
     },
     reasons: {
         network: "The server cannot be reached. Check your internet connection and try again.",

package/dist/Helpers/PopoverHelpers.d.ts

@@ -1,19 +1,29 @@
+/** 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. */
+    /** 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. Returns whether the panel went above.
+ * 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;
-/** Which side of its anchor a list panel opened on. */
-export type PanelSide = "below" | "above";
 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;
@@ -30,14 +40,29 @@ export interface PlaceListPanelOptions {
  * 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.
+ * 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, margin?: number): void;
+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

@@ -2,13 +2,19 @@
  * 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. Returns whether the panel went above.
+ * 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", gap = 4, margin = 8 } = 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;
@@ -16,15 +22,26 @@ export function placeUnderAnchor(panel, anchor, options = {}) {
     const fitsBelow = below + height <= window.innerHeight - margin;
     const top = fitsBelow || above < margin ? below : above;
     const wanted = align === "end" ? anchor.right - width : anchor.left;
-    const left = Math.max(margin, Math.min(wanted, window.innerWidth - width - margin));
+    // 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`;
-    return top !== below;
+    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;
@@ -56,19 +73,32 @@ function setStyle(element, 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.
+ * 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, margin = 8) {
+export function placeAtPoint(panel, x, y, options = {}) {
+    const { margin = 8, arrow = true } = options;
     const width = panel.offsetWidth;
     const height = panel.offsetHeight;
-    let left = x;
-    let top = y;
+    // 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 - width;
+        left = x + lead - width;
     if (top + height > window.innerHeight - margin)
-        top = y - height;
-    panel.style.left = `${Math.round(Math.max(margin, Math.min(left, window.innerWidth - width - margin)))}px`;
-    panel.style.top = `${Math.round(Math.max(margin, Math.min(top, window.innerHeight - height - margin)))}px`;
+        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) {
@@ -89,3 +119,77 @@ export function followAnchor(place) {
 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;
+}

package/dist/Helpers/RowsStore.d.ts

@@ -1,5 +1,5 @@
 import type { InputParams, InputValidationContext, RowsInputProps, RowValue } from "../Interfaces/FormInterfaces.ts";
-export type RowsStoreOptions<TRow extends RowValue = RowValue> = Pick<RowsInputProps<TRow>, "inputs" | "required" | "min" | "max" | "unique" | "validate" | "itemLabel" | "itemLabelPlural" | "rowKey" | "newRow" | "onRowChange"> & {
+export type RowsStoreOptions<TRow extends RowValue = RowValue> = Pick<RowsInputProps<TRow>, "inputs" | "required" | "min" | "max" | "unique" | "validate" | "itemLabel" | "itemLabelPlural" | "rowKey" | "newRow" | "onRowChange" | "deriveRows"> & {
     /** The row's name when there is no `itemLabel`: "Row" in a table, "Item" in sections. */
     fallbackItem?: string;
     /** The user's date settings, so messages write dates the way the fields show them. */
@@ -151,6 +151,12 @@ export declare class RowsStore<TRow extends RowValue = RowValue> {
     private checkEverything;
     /** After a change: repeated values, the rows' own message, the rows to render again, and value listeners. */
     private settle;
+    /**
+     * Values the rows' positions decide rather than the user. Every change funnels through `settle`, so this is the one
+     * place a move, an add, a remove and a keystroke all pass. The patches are written as code writes, which draws only
+     * the cells whose value really changed: a move renumbers its column and leaves focus on the row's own menu.
+     */
+    private derive;
     private bump;
     private touchAllRows;
     private emit;

package/dist/Helpers/RowsStore.js

@@ -526,6 +526,7 @@ export class RowsStore {
     }
     /** After a change: repeated values, the rows' own message, the rows to render again, and value listeners. */
     settle(changed) {
+        this.derive(changed);
         for (const name of this.dirtyUnique)
             this.checkUnique(name, changed);
         this.dirtyUnique.clear();
@@ -535,6 +536,27 @@ export class RowsStore {
         this.refresh();
         this.emit();
     }
+    /**
+     * Values the rows' positions decide rather than the user. Every change funnels through `settle`, so this is the one
+     * place a move, an add, a remove and a keystroke all pass. The patches are written as code writes, which draws only
+     * the cells whose value really changed: a move renumbers its column and leaves focus on the row's own menu.
+     */
+    derive(changed) {
+        const derive = this.options.deriveRows;
+        if (!derive)
+            return;
+        const patches = derive(this.getValue());
+        if (!patches)
+            return;
+        this.entries.forEach((entry, index) => {
+            const patch = patches[index];
+            if (!patch)
+                return;
+            // Depth 1, so a derived value never sets `onRowChange` off: these are the store's own writes, not the user's.
+            for (const [name, value] of Object.entries(patch))
+                this.write(entry.key, name, value, "code", changed, 1);
+        });
+    }
     bump(key) {
         this.versions.set(key, (this.versions.get(key) ?? 0) + 1);
         const listeners = this.rowListeners.get(key);