@revenexx/studio-shared 0.3.1 → 0.3.3

package/dist/runtime/composables/useDashboards.js

@@ -0,0 +1,143 @@
+import { computed, ref } from "vue";
+export class DashboardApiError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "DashboardApiError";
+  }
+}
+export function useDashboards(scope, options = {}) {
+  const base = options.base ?? "/api/cockpit";
+  const auth = usePlatformAuth();
+  const tenant = usePlatformTenant();
+  const key = (name) => `studio.dashboards.${scope}.${name}`;
+  const dashboards = useState(key("list"), () => []);
+  const defaultId = useState(key("defaultId"), () => null);
+  const loaded = useState(key("loaded"), () => false);
+  const loading = useState(key("loading"), () => false);
+  const saving = useState(key("saving"), () => false);
+  const error = useState(key("error"), () => null);
+  const inFlight = ref(null);
+  async function headers() {
+    const token = await auth.getToken();
+    if (!token) throw new DashboardApiError(401, "Not signed in.");
+    if (!tenant.slug.value) await tenant.load();
+    const slug = tenant.slug.value;
+    if (!slug) throw new DashboardApiError(400, "No active tenant.");
+    return { Authorization: `Bearer ${token}`, "X-Revenexx-Tenant": slug };
+  }
+  function fail(err) {
+    const e = err;
+    const status = e.status ?? e.statusCode ?? e.response?.status ?? 0;
+    const message = e.data?.statusMessage ?? e.data?.message ?? e.statusMessage ?? e.message ?? "The dashboard service did not answer.";
+    throw new DashboardApiError(status, message);
+  }
+  async function call(path, init = {}) {
+    try {
+      return await $fetch(`${base}${path}`, {
+        method: init.method ?? "GET",
+        headers: await headers(),
+        query: init.query,
+        body: init.body
+      });
+    } catch (err) {
+      if (err instanceof DashboardApiError) throw err;
+      fail(err);
+    }
+  }
+  function replace(updated) {
+    const idx = dashboards.value.findIndex((d) => d.id === updated.id);
+    dashboards.value = idx === -1 ? [...dashboards.value, updated] : dashboards.value.map((d) => d.id === updated.id ? updated : d);
+  }
+  async function run(force) {
+    loading.value = true;
+    error.value = null;
+    try {
+      const res = await call("/dashboards", { query: { scope } });
+      dashboards.value = res.dashboards;
+      defaultId.value = res.defaultDashboardId;
+      loaded.value = true;
+    } catch (err) {
+      error.value = err.message;
+      if (force) throw err;
+    } finally {
+      loading.value = false;
+    }
+    return dashboards.value;
+  }
+  async function load(force = false) {
+    if (inFlight.value) return inFlight.value;
+    if (loaded.value && !force) return dashboards.value;
+    inFlight.value = run(force);
+    try {
+      return await inFlight.value;
+    } finally {
+      inFlight.value = null;
+    }
+  }
+  async function create(payload) {
+    saving.value = true;
+    try {
+      const created = await call("/dashboards", { method: "POST", body: { ...payload, scope } });
+      replace(created);
+      return created;
+    } finally {
+      saving.value = false;
+    }
+  }
+  async function save(id, payload) {
+    const current = dashboards.value.find((d) => d.id === id);
+    saving.value = true;
+    try {
+      const updated = await call(`/dashboards/${id}`, {
+        method: "PATCH",
+        // The version travels with every write: a stale one is a 409 rather
+        // than a silent overwrite of the other tab's edit.
+        body: { ...payload, version: payload.version ?? current?.version }
+      });
+      replace(updated);
+      return updated;
+    } finally {
+      saving.value = false;
+    }
+  }
+  async function remove(id) {
+    await call(`/dashboards/${id}`, { method: "DELETE" });
+    dashboards.value = dashboards.value.filter((d) => d.id !== id);
+    if (defaultId.value === id) defaultId.value = null;
+  }
+  async function duplicate(id) {
+    const copy = await call(`/dashboards/${id}/duplicate`, { method: "POST" });
+    replace(copy);
+    return copy;
+  }
+  async function setDefault(id) {
+    await call(`/dashboards/${id ?? "none"}/default`, { method: "PUT", body: { scope } });
+    defaultId.value = id;
+    dashboards.value = dashboards.value.map((d) => ({ ...d, isDefault: d.id === id }));
+  }
+  function resolve(slug) {
+    const list = dashboards.value;
+    if (!list.length) return null;
+    if (slug) {
+      const named = list.find((d) => d.slug === slug);
+      if (named) return named;
+    }
+    return list.find((d) => d.id === defaultId.value) ?? list[0] ?? null;
+  }
+  return {
+    scope,
+    dashboards: computed(() => dashboards.value),
+    defaultId: computed(() => defaultId.value),
+    loading: computed(() => loading.value),
+    saving: computed(() => saving.value),
+    error: computed(() => error.value),
+    load,
+    resolve,
+    create,
+    save,
+    remove,
+    duplicate,
+    setDefault
+  };
+}

package/dist/runtime/composables/useSavedViews.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Saved-views storage provider — the DEFAULT (PE-608).
+ *
+ * ## Why this is a seam and not just an API call
+ *
+ * `SavedViewsMenu` ships inside `@revenexx/studio-shared`, which is published
+ * into hosts that have no cockpit backend: the standalone Commerce Studio dev
+ * host, and anything else that installs the module for its DataTable. So the
+ * component cannot reach for `/api/cockpit/saved-views` — it would 404 in every
+ * host but one, and the control would be permanently broken there.
+ *
+ * Same shape as `usePlatformAuth`, `usePlatformTenant` and `useMediaLibrary`:
+ * this file is the default, registered at `priority: -1`, and the cockpit ships
+ * a same-named app-level composable that wins. Here, views are kept in
+ * `localStorage`, which is exactly what the menu did before — so a bare host
+ * behaves as it always has, and only the cockpit gains the account-backed copy.
+ *
+ * ## Why `id` exists in a localStorage implementation
+ *
+ * The server keys a view by a uuid and the menu deletes by it. Making the local
+ * store agree means the component has one code path instead of two, and a
+ * `name`-keyed delete cannot be quietly wrong about which of two views with the
+ * same name it removed. The id is derived from the surface and the name, which
+ * is stable across reloads and is all the uniqueness a browser-local store has.
+ */
+/** One named snapshot of how a list was narrowed. */
+export interface StoredSavedView {
+    id: string;
+    name: string;
+    snapshot: unknown;
+}
+export interface SavedViewsStore {
+    /** Read this surface's views. Never throws — a failure is an empty list. */
+    list: (surface: string) => Promise<StoredSavedView[]>;
+    /** Save under a name, replacing what that name held. */
+    save: (surface: string, name: string, snapshot: unknown) => Promise<StoredSavedView>;
+    remove: (surface: string, id: string) => Promise<void>;
+    /**
+     * Does this store survive a new browser? The menu says so in one line, so
+     * "saved to your account" and "saved in this browser only" stay honest.
+     */
+    readonly durable: boolean;
+}
+export declare function useSavedViews(): SavedViewsStore;

package/dist/runtime/composables/useSavedViews.js

@@ -0,0 +1,44 @@
+function localId(surface, name) {
+  return `local:${surface}::${name}`;
+}
+function readAll(surface) {
+  try {
+    if (typeof window === "undefined") return [];
+    const raw = window.localStorage.getItem(surface);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((v) => !!v && typeof v === "object" && typeof v.name === "string").map((v) => ({ id: localId(surface, v.name), name: v.name, snapshot: v.snapshot }));
+  } catch {
+    return [];
+  }
+}
+function writeAll(surface, views) {
+  try {
+    if (typeof window === "undefined") return;
+    window.localStorage.setItem(surface, JSON.stringify(
+      views.map((v) => ({ name: v.name, snapshot: v.snapshot }))
+    ));
+  } catch {
+  }
+}
+export function useSavedViews() {
+  return {
+    durable: false,
+    async list(surface) {
+      return readAll(surface);
+    },
+    async save(surface, name, snapshot) {
+      const views = readAll(surface);
+      const entry = { id: localId(surface, name), name, snapshot };
+      const at = views.findIndex((v) => v.name === name);
+      if (at >= 0) views.splice(at, 1, entry);
+      else views.push(entry);
+      writeAll(surface, views);
+      return entry;
+    },
+    async remove(surface, id) {
+      writeAll(surface, readAll(surface).filter((v) => v.id !== id));
+    }
+  };
+}

package/dist/runtime/composables/useStickyListView.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The narrowing a list was left in, kept across a page change (PE-608).
+ *
+ * Leaving a list to open a record — or to check another one — and coming back
+ * to an unfiltered table is the small tax every operator pays repeatedly: they
+ * re-tick the same facets, re-pick the same sort, and do it again the next
+ * time. The state is already a snapshot (it is what a saved view stores), so
+ * remembering the last one per surface costs nothing new.
+ *
+ * ## Why `sessionStorage` and not `localStorage`
+ *
+ * This is the decision worth arguing, because both are defensible and only one
+ * of them is safe by default.
+ *
+ * A sticky filter is a known way to lose people. An operator opens Orders, sees
+ * three rows out of twenty-three thousand, and concludes the data is gone —
+ * because the filter that did it was set last Tuesday and nothing on screen
+ * looks like an answer to "why is this list short". That is a support ticket,
+ * and a scary one.
+ *
+ * Two things make it safe here rather than merely convenient:
+ *
+ *  1. **It is visible.** The chip strip under the toolbar names every applied
+ *     value and the trigger is lit. A restored narrowing announces itself; the
+ *     version of this feature that is dangerous is the one you cannot see.
+ *  2. **It ends with the tab.** `sessionStorage` survives a navigation and a
+ *     reload — which is what "come back to the list" means — and is gone when
+ *     the tab closes. Tomorrow morning is a fresh list. `localStorage` would
+ *     carry Friday's filter into Monday, and `localStorage` is also what the
+ *     saved views deliberately stopped being: a durable narrowing is a thing
+ *     you NAME and store on your account, not something a list does to you.
+ *
+ * So: sticky within a session, explicit across them. Swapping the two is one
+ * identifier if that trade ever reads differently.
+ *
+ * ## What it does not do
+ *
+ * It does not write the URL. A link to a list is a link to the list, not to how
+ * one person last left it — pasting a narrowed URL into a ticket and having a
+ * colleague see something else is worse than either behaviour here. The queue
+ * pills are the linkable half, and they already carry `?queue=` on purpose.
+ */
+export interface StickyListView<T> {
+    /**
+     * The snapshot this surface was last left in, or `null`.
+     *
+     * Read once, deliberately: a surface restores on mount and owns its state
+     * from then on. A reactive value here would fight the surface for it.
+     */
+    read: () => T | null;
+    /** Remember the current snapshot. Call it whenever the surface's state moves. */
+    write: (snapshot: T) => void;
+    /** Forget this surface's state — what a "reset" should also do. */
+    clear: () => void;
+}
+/**
+ * @param key A stable identifier for the surface — the same route pattern the
+ *   saved views are keyed by, so two lists never share a memory.
+ */
+export declare function useStickyListView<T>(key: string): StickyListView<T>;

package/dist/runtime/composables/useStickyListView.js

@@ -0,0 +1,32 @@
+const VERSION = 1;
+export function useStickyListView(key) {
+  const storageKey = `commerce.listState.${key}`;
+  return {
+    read() {
+      try {
+        if (typeof window === "undefined") return null;
+        const raw = window.sessionStorage.getItem(storageKey);
+        if (!raw) return null;
+        const parsed = JSON.parse(raw);
+        if (!parsed || parsed.v !== VERSION) return null;
+        return parsed.snapshot ?? null;
+      } catch {
+        return null;
+      }
+    },
+    write(snapshot) {
+      try {
+        if (typeof window === "undefined") return;
+        window.sessionStorage.setItem(storageKey, JSON.stringify({ v: VERSION, snapshot }));
+      } catch {
+      }
+    },
+    clear() {
+      try {
+        if (typeof window === "undefined") return;
+        window.sessionStorage.removeItem(storageKey);
+      } catch {
+      }
+    }
+  };
+}

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;