@revenexx/studio-shared 0.3.2 → 0.3.3

package/dist/runtime/lib/canonicalJson.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A stable string for any JSON value, for comparing two of them (PE-608).
+ *
+ * ## The bug this exists for
+ *
+ * `SavedViewsMenu` decides whether a stored view is the one currently applied
+ * by comparing snapshots, and it compared them with `JSON.stringify`. That
+ * works exactly as long as both sides were built by the same code in the same
+ * order — which stopped being true the moment saved views moved into Postgres.
+ *
+ * `jsonb` does not preserve key order; it normalises it. So a surface that
+ * builds `{ filters, sort }` gets `{ sort, filters }` back from the database,
+ * the two strings differ, and the applied view is never recognised as applied.
+ * Nothing throws and nothing looks broken — the menu simply never marks
+ * anything, and the trigger never shows that a view is in effect. It is the
+ * kind of defect that survives review because the code reads as obviously
+ * correct.
+ *
+ * ## What "canonical" means here
+ *
+ * Object keys sorted, recursively. Arrays left alone, because their order IS
+ * their meaning — `["a","b"]` and `["b","a"]` are different filter values as
+ * far as a query is concerned, and a facet that wants them treated as a set
+ * sorts them before it stores them.
+ *
+ * `undefined` is dropped from objects, exactly as `JSON.stringify` does, so an
+ * absent key and an explicitly-undefined one compare equal. That matters:
+ * `{ queue: undefined }` is what a spread produces for a surface with no queue,
+ * and the server round-trips it as an absent key.
+ */
+/**
+ * Deterministic JSON for `value` — same input, same string, whatever order the
+ * keys arrived in.
+ *
+ * A cycle would make this recurse forever, so it is caught and reported as a
+ * sentinel rather than thrown: the one caller is a comparison in a computed,
+ * and a snapshot is not worth crashing a toolbar over. Two cyclic values
+ * compare equal, which is wrong but harmless — and a snapshot with a cycle
+ * could never have been stored in the first place.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** Do two JSON values mean the same thing, whatever order their keys are in? */
+export declare function sameJson(a: unknown, b: unknown): boolean;

package/dist/runtime/lib/canonicalJson.js

@@ -0,0 +1,38 @@
+export function canonicalJson(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const walk = (input) => {
+    if (input === null) return "null";
+    const type = typeof input;
+    if (type === "number") return Number.isFinite(input) ? String(input) : "null";
+    if (type === "boolean") return String(input);
+    if (type === "string") return JSON.stringify(input);
+    if (type === "undefined" || type === "function" || type === "symbol") return "undefined";
+    if (type === "bigint") return JSON.stringify(String(input));
+    const object = input;
+    if (seen.has(object)) return '"[cycle]"';
+    seen.add(object);
+    try {
+      if (Array.isArray(object)) {
+        return `[${object.map((item) => {
+          const part = walk(item);
+          return part === "undefined" ? "null" : part;
+        }).join(",")}]`;
+      }
+      if (object instanceof Date) return JSON.stringify(object.toISOString());
+      const parts = [];
+      for (const key of Object.keys(object).sort()) {
+        const part = walk(object[key]);
+        if (part === "undefined") continue;
+        parts.push(`${JSON.stringify(key)}:${part}`);
+      }
+      return `{${parts.join(",")}}`;
+    } finally {
+      seen.delete(object);
+    }
+  };
+  const out = walk(value);
+  return out === "undefined" ? "null" : out;
+}
+export function sameJson(a, b) {
+  return canonicalJson(a) === canonicalJson(b);
+}

package/dist/runtime/lib/dashboardIcons.d.ts

@@ -0,0 +1,4 @@
+export declare const DASHBOARD_ICONS: Record<string, unknown>;
+/** Every name the picker may offer, in a stable order. */
+export declare const PICKABLE_ICONS: string[];
+export declare function dashboardIcon(name?: string): unknown;

package/dist/runtime/lib/dashboardIcons.js

@@ -0,0 +1,50 @@
+import {
+  Bag,
+  BillList,
+  Bolt,
+  Box,
+  Card,
+  Cart,
+  ChartSquare,
+  ClipboardList,
+  DangerTriangle,
+  Earth,
+  GraphUp,
+  Hashtag,
+  Home,
+  Layers,
+  List,
+  MagicStick,
+  NotebookMinimalistic,
+  Pulse,
+  Routing,
+  UsersGroupRounded,
+  Widget
+} from "#solar-icons";
+export const DASHBOARD_ICONS = {
+  Bag,
+  BillList,
+  Bolt,
+  Box,
+  Card,
+  Cart,
+  ChartSquare,
+  ClipboardList,
+  DangerTriangle,
+  Earth,
+  GraphUp,
+  Hashtag,
+  Home,
+  Layers,
+  List,
+  MagicStick,
+  NotebookMinimalistic,
+  Pulse,
+  Routing,
+  UsersGroupRounded,
+  Widget
+};
+export const PICKABLE_ICONS = Object.keys(DASHBOARD_ICONS);
+export function dashboardIcon(name) {
+  return name && DASHBOARD_ICONS[name] || Widget;
+}

package/dist/runtime/lib/facets.d.ts

@@ -0,0 +1,200 @@
+/**
+ * One facet model for every way a list gets narrowed (PE-6xx).
+ *
+ * ## Why this exists
+ *
+ * The Commerce Studio grew seven mechanisms for the same job. Five of them
+ * describe the identical thing in different words:
+ *
+ *   - `filters[type=select]`      — a column, a vocabulary, options
+ *   - `filters[type=multi-select]`— the same, several values
+ *   - `filters[type=boolean]`     — the same, two values
+ *   - `filters[type=text]`        — the same column, matched by substring
+ *   - `filters[type=date-range]`  — the same column, bounded
+ *   - `rail.sections[type=facet]` — a column, a vocabulary, options. Again.
+ *   - `rail.sections[type=tree]`  — a column reached through a junction
+ *
+ * Each was rendered by its own control, in its own place, with its own commit
+ * behaviour, and none of them could hold more than one value except the one
+ * type nobody declared. This module is the single shape all of them reduce to,
+ * so a surface declares a dimension once and the CONTROL is a rendering
+ * decision rather than a second grammar.
+ *
+ * ## A facet is a question, not a widget
+ *
+ * `kind` says what shape the answer takes — a set of options, a typed string, a
+ * bounded range, a node in a hierarchy. It does NOT say where the control
+ * lives, because there is only one: the filter panel. An earlier pass gave a
+ * facet a `place` so a catalogue tree could stay pinned in a left rail, and
+ * that hedge put the studio back where it started — two places to look, two
+ * commit rules, and no way for an app author to know which one a dimension
+ * belonged in.
+ *
+ * ## Every facet is multi-valued
+ *
+ * `check` and `tree` hold a LIST. That is the point of the rework: "active or
+ * draft" was not a question the product could ask, because a `select` mapped to
+ * `eq.` and a submenu could only tick one row. Within a facet the values are
+ * OR'd, across facets AND'd — "a draft or a lead, in Germany".
+ *
+ * `text` and `date-range` hold one value each because there is only one to
+ * hold; they are still facets, and they still live in the panel rather than
+ * growing a second control in the toolbar.
+ */
+export type FacetKind = 'check' | 'text' | 'date-range' | 'tree';
+export interface FacetOption {
+    value: string;
+    label: string;
+    /**
+     * How many rows match. Shown where known — "Churned 4" is the difference
+     * between a guess and a decision. Left `undefined` where the surface could
+     * not ask cheaply; a facet with no counts renders bare rather than lying
+     * with a zero.
+     */
+    count?: number;
+    /** Greyed and unclickable, kept visible so the dimension still reads whole. */
+    disabled?: boolean;
+}
+/** One node of a `tree` facet. */
+export interface FacetNode {
+    value: string;
+    label: string;
+    count?: number;
+    children?: FacetNode[];
+}
+export interface Facet {
+    /** Stable id. Namespaces this facet's values in the flat selection. */
+    key: string;
+    label: string;
+    kind: FacetKind;
+    /** `check` — the values on offer. */
+    options?: FacetOption[];
+    /** `tree` — the hierarchy on offer. */
+    nodes?: FacetNode[];
+    /** Placeholder for a `text` facet's input. */
+    placeholder?: string;
+    /** One line under the pane saying what the facet actually matches. */
+    hint?: string;
+    /**
+     * The pane is still loading its options. Renders a skeleton instead of an
+     * empty list, which otherwise reads as "this dimension has no values".
+     */
+    loading?: boolean;
+    /**
+     * One value at a time — picking a second replaces the first.
+     *
+     * For a dimension whose values are alternatives rather than a set. A list's
+     * work queues are the case this exists for: "waiting for approval" AND
+     * "blocked" at once is not a wider question, it is a query that matches
+     * nothing, so offering it as a pair of checkboxes offers a dead end.
+     */
+    single?: boolean;
+}
+/** `{ from, to }`, either side optional. */
+export interface FacetRange {
+    from?: string;
+    to?: string;
+}
+export type FacetValue = string[] | string | FacetRange;
+/**
+ * What is selected, keyed by facet. A map rather than the flat
+ * `"status:active"` array the design system's own panel takes, because `text`
+ * and `date-range` values do not survive being squashed into a string that is
+ * split on its first colon — a typed `"12:30"` or an ISO instant would break
+ * apart. {@link facetValueIds} produces the flat form where a component wants
+ * it (chips, aria labels).
+ */
+export type FacetSelection = Record<string, FacetValue>;
+/**
+ * Is this value "no answer"? The one place that decides, because three
+ * different guesses at it is how a cleared filter keeps narrowing a query.
+ *
+ * `false` is a real answer, not emptiness — a boolean facet whose only tick is
+ * "No" must survive. Which is why this checks the SHAPE and never truthiness.
+ */
+export declare function isEmptyFacetValue(value: FacetValue | null | undefined): boolean;
+/** The selection with every empty entry dropped. What a query should read. */
+export declare function pruneSelection(selection: FacetSelection): FacetSelection;
+/**
+ * How many values are set inside one facet — the badge on its row in the panel.
+ *
+ * A `text` or `date-range` facet counts as one when answered: the badge says
+ * "this dimension is narrowing", and "1" is the honest number for one typed
+ * string. Counting its characters, or a range's two bounds as two, would make
+ * the panel's total disagree with the number of chips beside it.
+ */
+export declare function countInFacet(selection: FacetSelection, key: string): number;
+/** Everything set, across every facet. The count on the toolbar trigger. */
+export declare function countSelected(facets: Facet[], selection: FacetSelection): number;
+/** Depth-first walk, descending only into expanded nodes. */
+export declare function flattenNodes(nodes: FacetNode[], expanded: ReadonlySet<string>): Array<{
+    node: FacetNode;
+    depth: number;
+}>;
+/** Every node, flat and depthless. What a search filters over. */
+export declare function allNodes(nodes: FacetNode[]): FacetNode[];
+/**
+ * The path from a root down to `value`, inclusive. What a chip reads
+ * ("Tools › Hand tools"): a deep node's own label is frequently ambiguous on
+ * its own — three branches of a catalogue each have an "Accessories".
+ */
+export declare function nodePath(nodes: FacetNode[], value: string): FacetNode[] | null;
+/**
+ * The ids on the path ABOVE `value`, so a node selected from a saved view or a
+ * restored URL is revealed rather than left selected and invisible.
+ */
+export declare function expandTo(nodes: FacetNode[], value: string | null | undefined): Set<string>;
+/** The set a fresh tree opens with: the roots, and nothing deeper. */
+export declare function initialExpanded(nodes: FacetNode[]): Set<string>;
+export interface AppliedFacet {
+    /** Flat id, unique across the selection — the chip's `key`. */
+    id: string;
+    facetKey: string;
+    facetLabel: string;
+    /** What the chip says. A tree node carries its path. */
+    label: string;
+    /** The single value this chip removes. `undefined` clears the whole facet. */
+    value?: string;
+}
+/** The flat ids of one facet's values, for a chip `key` or an aria label. */
+export declare function facetValueIds(key: string, value: FacetValue): string[];
+/**
+ * What is filtering right now, in the order the facets are DECLARED rather
+ * than the order they were clicked — a chip strip that reshuffles itself as you
+ * work is one people stop reading.
+ *
+ * `rangeLabel` and `textLabel` are passed in rather than built here: a range
+ * reads through the operator's own date format and a typed string wants
+ * quotation marks the UI language agrees with, and neither belongs in a pure
+ * derivation lib.
+ */
+export declare function appliedFacets(facets: Facet[], selection: FacetSelection, format: {
+    range: (range: FacetRange) => string;
+    text: (value: string) => string;
+}): AppliedFacet[];
+/**
+ * Tick or untick one value of a multi-valued facet, returning a NEW selection.
+ *
+ * A facet whose last value is removed is deleted from the map rather than left
+ * as an empty array: `pruneSelection` would drop it anyway, and a lingering
+ * `{ status: [] }` makes two selections that mean the same thing compare
+ * unequal — which is what a dirty-check and a saved view both rely on.
+ */
+export declare function toggleFacetValue(selection: FacetSelection, key: string, value: string, on: boolean, opts?: {
+    single?: boolean;
+}): FacetSelection;
+/** Set (or clear) a `text` / `date-range` facet, returning a NEW selection. */
+export declare function setFacetValue(selection: FacetSelection, key: string, value: FacetValue): FacetSelection;
+/** Remove one chip. Clears the whole facet for the single-valued kinds. */
+export declare function clearFacetValue(selection: FacetSelection, key: string, value?: string): FacetSelection;
+/**
+ * Do two selections mean the same thing? Drives the Apply button's dot and the
+ * decision to re-query at all.
+ *
+ * Order-insensitive within a facet: ticking A then B and ticking B then A are
+ * the same filter, and a dirty flag that disagreed would offer an Apply that
+ * changes nothing.
+ */
+export declare function sameSelection(a: FacetSelection, b: FacetSelection): boolean;
+/** Deep-enough copy for a draft. The values are strings, arrays and flat pairs. */
+export declare function copySelection(selection: FacetSelection): FacetSelection;

package/dist/runtime/lib/facets.js

@@ -0,0 +1,171 @@
+export function isEmptyFacetValue(value) {
+  if (value === null || value === void 0) return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === "string") return value.trim() === "";
+  if (typeof value === "object") {
+    const range = value;
+    return !range.from?.trim() && !range.to?.trim();
+  }
+  return false;
+}
+export function pruneSelection(selection) {
+  const out = {};
+  for (const [key, value] of Object.entries(selection)) {
+    if (!isEmptyFacetValue(value)) out[key] = value;
+  }
+  return out;
+}
+export function countInFacet(selection, key) {
+  const value = selection[key];
+  if (isEmptyFacetValue(value)) return 0;
+  return Array.isArray(value) ? value.length : 1;
+}
+export function countSelected(facets, selection) {
+  return facets.reduce((n, facet) => n + countInFacet(selection, facet.key), 0);
+}
+export function flattenNodes(nodes, expanded) {
+  const out = [];
+  const walk = (list, depth) => {
+    for (const node of list) {
+      out.push({ node, depth });
+      if (node.children?.length && expanded.has(node.value)) walk(node.children, depth + 1);
+    }
+  };
+  walk(nodes, 0);
+  return out;
+}
+export function allNodes(nodes) {
+  const out = [];
+  const walk = (list) => {
+    for (const node of list) {
+      out.push(node);
+      if (node.children?.length) walk(node.children);
+    }
+  };
+  walk(nodes);
+  return out;
+}
+export function nodePath(nodes, value) {
+  const walk = (list, trail) => {
+    for (const node of list) {
+      const here = [...trail, node];
+      if (node.value === value) return here;
+      if (node.children?.length) {
+        const hit = walk(node.children, here);
+        if (hit) return hit;
+      }
+    }
+    return null;
+  };
+  return walk(nodes, []);
+}
+export function expandTo(nodes, value) {
+  if (!value) return /* @__PURE__ */ new Set();
+  const path = nodePath(nodes, value);
+  if (!path) return /* @__PURE__ */ new Set();
+  return new Set(path.slice(0, -1).map((node) => node.value));
+}
+export function initialExpanded(nodes) {
+  return new Set(nodes.filter((node) => node.children?.length).map((node) => node.value));
+}
+export function facetValueIds(key, value) {
+  if (isEmptyFacetValue(value)) return [];
+  if (Array.isArray(value)) return value.map((one) => `${key}:${one}`);
+  return [`${key}:`];
+}
+function optionLabel(facet, value) {
+  if (facet.kind === "tree") {
+    const path = nodePath(facet.nodes ?? [], value);
+    return path?.length ? path.map((node) => node.label).join(" \u203A ") : value;
+  }
+  return facet.options?.find((option) => option.value === value)?.label ?? value;
+}
+export function appliedFacets(facets, selection, format) {
+  const out = [];
+  for (const facet of facets) {
+    const value = selection[facet.key];
+    if (isEmptyFacetValue(value)) continue;
+    if (Array.isArray(value)) {
+      for (const one of value) {
+        out.push({
+          id: `${facet.key}:${one}`,
+          facetKey: facet.key,
+          facetLabel: facet.label,
+          label: optionLabel(facet, one),
+          value: one
+        });
+      }
+      continue;
+    }
+    out.push({
+      id: `${facet.key}:`,
+      facetKey: facet.key,
+      facetLabel: facet.label,
+      label: typeof value === "string" ? format.text(value) : format.range(value)
+    });
+  }
+  return out;
+}
+export function toggleFacetValue(selection, key, value, on, opts = {}) {
+  if (opts.single) {
+    const next2 = { ...selection };
+    if (on) next2[key] = [value];
+    else delete next2[key];
+    return next2;
+  }
+  const current = selection[key];
+  const set = new Set(Array.isArray(current) ? current : []);
+  if (on) set.add(value);
+  else set.delete(value);
+  const next = { ...selection };
+  if (set.size) next[key] = [...set];
+  else delete next[key];
+  return next;
+}
+export function setFacetValue(selection, key, value) {
+  const next = { ...selection };
+  if (isEmptyFacetValue(value)) delete next[key];
+  else next[key] = value;
+  return next;
+}
+export function clearFacetValue(selection, key, value) {
+  if (value === void 0) {
+    const next = { ...selection };
+    delete next[key];
+    return next;
+  }
+  return toggleFacetValue(selection, key, value, false);
+}
+export function sameSelection(a, b) {
+  const left = pruneSelection(a);
+  const right = pruneSelection(b);
+  const keys = Object.keys(left);
+  if (keys.length !== Object.keys(right).length) return false;
+  for (const key of keys) {
+    const l = left[key];
+    const r = right[key];
+    if (r === void 0) return false;
+    if (Array.isArray(l) !== Array.isArray(r)) return false;
+    if (Array.isArray(l) && Array.isArray(r)) {
+      if (l.length !== r.length) return false;
+      const sorted = [...r].sort();
+      if ([...l].sort().some((one, i) => one !== sorted[i])) return false;
+      continue;
+    }
+    if (typeof l === "string" || typeof r === "string") {
+      if (l !== r) return false;
+      continue;
+    }
+    const lr = l;
+    const rr = r;
+    if ((lr.from ?? "") !== (rr.from ?? "") || (lr.to ?? "") !== (rr.to ?? "")) return false;
+  }
+  return true;
+}
+export function copySelection(selection) {
+  const out = {};
+  for (const [key, value] of Object.entries(selection)) {
+    out[key] = Array.isArray(value) ? [...value] : typeof value === "string" ? value : { ...value };
+  }
+  return out;
+}

package/dist/runtime/lib/gridTracks.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Grid track sizing for the data table's columns.
+ *
+ * A column declares either a fixed size it wants (`'120px'`, `'max-content'`)
+ * or nothing at all, meaning "give it what is left". CSS Grid expresses the
+ * second as an `fr` track, and an `fr` track's automatic minimum is the one
+ * thing that makes it dangerous: `minmax(0,1fr)` may be given ZERO.
+ *
+ * That is not hypothetical. On `/commerce/contacts` thirteen columns declare
+ * 1340px of fixed track, the gaps add 96px, and the container is 1438px — so
+ * the only flexible column, the one holding the record's NAME, was sized 0px
+ * and the last column was clipped by the panel's `overflow: hidden`. The
+ * anchor of every row, invisible, on the surface that needs it most.
+ *
+ * `datatable-ux` already names the rule: a column whose resting state must
+ * stay legible gets a FLOOR, not a share. This applies it to the tracks the
+ * component generates, so a manifest gets it without having to ask — and the
+ * table overflows its box, where a reader can scroll to what was cut off,
+ * rather than silently dropping a column to nothing.
+ */
+/**
+ * The narrowest a flexible column may become.
+ *
+ * Roughly the record-name cell at its minimum: the 28px icon tile, its gap,
+ * and enough left for a truncated word plus the ellipsis that says there is
+ * more. Below this a column stops being a column and becomes a smear.
+ */
+export declare const FLEX_TRACK_FLOOR = "120px";
+/**
+ * One column's declared width, resolved to a track with a floor under it.
+ *
+ * Fixed sizes are left exactly as declared — they are a statement about the
+ * content, and shrinking them is the manifest author's call, not this
+ * function's. Only the flexible ones are touched, and only their minimum.
+ */
+export declare function trackFor(width: string | undefined | null, floor?: string): string;
+/**
+ * The `grid-template-columns` value for a row of columns.
+ *
+ * A row spans `1 / -1` — the first track line to the last — so the tracks are
+ * also how WIDE a row is. Where every column declares a fixed size, they sum to
+ * less than the panel and nothing takes the remainder: on
+ * `/commerce/procurement/purchase-requests` the tracks and their gaps came to
+ * 1486px inside a 1698px box, and the header band and every row background
+ * stopped there while the toolbar and the footer went the whole way. A table
+ * torn off two centimetres short of its own panel.
+ *
+ * So when no column asked for a share, the LAST one absorbs what is left, and
+ * it keeps its declared size as the minimum it may never go below. On these
+ * lists the last column is the row actions — content right-aligned, so the
+ * menu button stays pinned to the right edge and every other column is exactly
+ * where the manifest put it. On a list without one it is the trailing data
+ * column that grows, which is where the eye is least likely to miss the space.
+ */
+export declare function gridTemplateColumns(widths: Array<string | undefined | null>, floor?: string): string;

package/dist/runtime/lib/gridTracks.js

@@ -0,0 +1,29 @@
+export const FLEX_TRACK_FLOOR = "120px";
+const MINMAX_FR = /^minmax\(\s*[^,]+,\s*([\d.]+fr)\s*\)$/i;
+const BARE_FR = /^([\d.]+)fr$/i;
+export function trackFor(width, floor = FLEX_TRACK_FLOOR) {
+  if (!width) return `minmax(${floor},1fr)`;
+  const declared = width.trim();
+  const weighted = MINMAX_FR.exec(declared);
+  if (weighted) return `minmax(${floor},${weighted[1].toLowerCase()})`;
+  const bare = BARE_FR.exec(declared);
+  if (bare) return `minmax(${floor},${bare[1]}fr)`;
+  return declared;
+}
+function isFlexible(track) {
+  return /\dfr\s*\)?$/i.test(track);
+}
+const MINMAX = /^minmax\(\s*([^,]+?)\s*,\s*(.+?)\s*\)$/i;
+function absorbing(track) {
+  const parts = MINMAX.exec(track);
+  return `minmax(${parts ? parts[2] : track},1fr)`;
+}
+export function gridTemplateColumns(widths, floor) {
+  const tracks = widths.map((w) => trackFor(w, floor));
+  if (tracks.length === 0) return "";
+  if (!tracks.some(isFlexible)) {
+    const last = tracks.length - 1;
+    tracks[last] = absorbing(tracks[last]);
+  }
+  return tracks.join(" ");
+}