@hotmeshio/long-tail 0.24.2 → 0.25.1

package/build/shared/form-validation/validate-resolver-payload.js

@@ -13,6 +13,7 @@ exports.validateResolverPayload = validateResolverPayload;
  * Semantics per field:
  *   - x-lt-showIf-hidden fields are skipped entirely (a field the submitter
  *     cannot see never blocks submission)
+ *   - x-lt-hidden fields are never required; a value they carry is checked
  *   - required (schema.required membership), with checklist/empty-object rules
  *   - declared-type check (string/number/integer/boolean/array/object)
  *   - enum membership
@@ -50,7 +51,7 @@ function validateResolverForm(schema, formValues, ctx) {
     for (const [field, fieldSchema] of Object.entries(properties)) {
         if (!(0, x_lt_show_if_1.evaluateShowIf)(fieldSchema['x-lt-showIf'], liveCtx))
             continue;
-        const err = (0, field_validator_1.validateField)(formValues[field], fieldSchema, required.has(field), true, liveCtx);
+        const err = (0, field_validator_1.validateField)(formValues[field], fieldSchema, required.has(field) && !(0, x_lt_show_if_1.isHiddenField)(fieldSchema), true, liveCtx);
         if (err)
             errors.push({ field, message: err });
     }

package/build/shared/form-validation/x-lt-help.d.ts

@@ -1,5 +1,5 @@
 /** The token domains a help template may reference. `input` is the invoke-form name for the live values `resolver` also carries. */
-export declare const HELP_DOMAINS: readonly ["escalation", "metadata", "envelope", "payload", "resolver", "lookup", "input"];
+export declare const HELP_DOMAINS: readonly ["escalation", "metadata", "envelope", "payload", "resolver", "lookup", "input", "roster"];
 export type HelpDomain = (typeof HELP_DOMAINS)[number];
 export type HelpTokenContext = Partial<Record<HelpDomain, Record<string, unknown> | null>>;
 /** Replace every `{{domain.path}}` token with its value from the context. */

package/build/shared/form-validation/x-lt-help.js

@@ -17,6 +17,7 @@ exports.defaultHelpMarkdown = defaultHelpMarkdown;
  *   {{payload.category}}                       — the escalation context payload
  *   {{resolver.notes}}                         — the submitted resolver payload
  *   {{lookup.materials.items}}                 — versioned knowledge lookups pinned on the row
+ *   {{roster.orders.outstanding}}              (a roster field's counts, x-lt-roster.ts)
  *
  * Paths reuse the x-lt-bind syntax (`a.b[0].c`). A missing value renders as an
  * em dash. `x-lt-context` is accepted as the plain-text fallback source when
@@ -24,7 +25,7 @@ exports.defaultHelpMarkdown = defaultHelpMarkdown;
  */
 const x_lt_bind_1 = require("./x-lt-bind");
 /** The token domains a help template may reference. `input` is the invoke-form name for the live values `resolver` also carries. */
-exports.HELP_DOMAINS = ['escalation', 'metadata', 'envelope', 'payload', 'resolver', 'lookup', 'input'];
+exports.HELP_DOMAINS = ['escalation', 'metadata', 'envelope', 'payload', 'resolver', 'lookup', 'input', 'roster'];
 const TOKEN_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
 const MISSING_VALUE = '—';
 function formatTokenValue(value) {

package/build/shared/form-validation/x-lt-roster.d.ts

@@ -0,0 +1,92 @@
+import { type HelpTokenContext } from './x-lt-help';
+export declare const X_LT_ROSTER = "x-lt-roster";
+export declare const ROSTER_WIDGET = "roster";
+/** The context domain the counts are read from: `roster.<field>.outstanding`. */
+export declare const ROSTER_DOMAIN = "roster";
+/** The most member rows a query set reads. */
+export declare const ROSTER_QUERY_LIMIT = 200;
+/** The `in` source naming the host row's held keys. */
+export declare const ROSTER_ITEMS_SOURCE = "items";
+/** `query.status` value that reads every status (the default). */
+export declare const ROSTER_ANY_STATUS = "any";
+export declare const ROSTER_STATES: {
+    readonly WAITING: "waiting";
+    readonly IN: "in";
+    readonly FLAGGED: "flagged";
+};
+export type RosterState = (typeof ROSTER_STATES)[keyof typeof ROSTER_STATES];
+export interface RosterQuery {
+    role?: string;
+    roles?: string[];
+    facets?: Record<string, string>;
+    /** A status to narrow to; omitted or `any` reads every status. */
+    status?: string;
+}
+export type RosterExpected = {
+    query: RosterQuery;
+} | {
+    list: string;
+} | {
+    batch: true;
+    labels?: string;
+};
+export interface RosterFlagRule {
+    /** An x-lt-showIf condition over the member row's own context. */
+    when: string | string[];
+    label: string;
+}
+export interface RosterDef {
+    expected: RosterExpected;
+    key?: string;
+    in?: string[];
+    flagged?: RosterFlagRule[];
+}
+/** One member row's token context (the row's own domains). */
+export type RosterRow = HelpTokenContext & {
+    escalation: Record<string, unknown>;
+};
+export interface RosterEntry {
+    key: string;
+    state: RosterState;
+    /** The matching flag rule's label, when flagged. */
+    flag?: string;
+    /** The member row, for a query set. */
+    row?: RosterRow;
+    /** The per-key label value from a batch's `labels` map. */
+    label?: unknown;
+}
+export interface RosterCounts {
+    expected: number;
+    in: number;
+    flagged: number;
+    waiting: number;
+    /** Entries neither in nor flagged: the count a roster guard waits on. */
+    outstanding: number;
+}
+export interface RosterResult {
+    entries: RosterEntry[];
+    counts: RosterCounts;
+}
+/** The field's roster declaration, or undefined when it declares none or an unusable one. */
+export declare function readRosterDef(fieldSchema: Record<string, unknown> | null | undefined): RosterDef | undefined;
+/** Every roster field of a form schema, by field name. */
+export declare function readRosterDefs(schema: Record<string, unknown> | null | undefined): Record<string, RosterDef>;
+/** The roster's member-row query, or null when its set is not a query. */
+export declare function rosterQueryOf(def: RosterDef): RosterQuery | null;
+/** The query's concrete params: facets interpolated, `any` status dropped. Null when the scope is empty. */
+export declare function resolveRosterQuery(query: RosterQuery, ctx: HelpTokenContext): {
+    roles?: string[];
+    facets: Record<string, string>;
+    status?: string;
+    limit: number;
+} | null;
+/** A member row's token context, from a row whose JSON columns are strings or objects. */
+export declare function rosterRowContext(row: Record<string, unknown>): RosterRow;
+/**
+ * Every expected entry with its state, and the counts. `rows` are the
+ * member rows a query set read (ignored for list and batch sets). `ctx` is
+ * the host row's context with the live form values under `resolver`.
+ */
+export declare function computeRoster(def: RosterDef, ctx: HelpTokenContext, rows?: RosterRow[]): RosterResult;
+/** The header line: "3 of 5 in · 1 Missing". */
+export declare function rosterHeadline(result: RosterResult): string;

package/build/shared/form-validation/x-lt-roster.js

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROSTER_STATES = exports.ROSTER_ANY_STATUS = exports.ROSTER_ITEMS_SOURCE = exports.ROSTER_QUERY_LIMIT = exports.ROSTER_DOMAIN = exports.ROSTER_WIDGET = exports.X_LT_ROSTER = void 0;
+exports.readRosterDef = readRosterDef;
+exports.readRosterDefs = readRosterDefs;
+exports.rosterQueryOf = rosterQueryOf;
+exports.resolveRosterQuery = resolveRosterQuery;
+exports.rosterRowContext = rosterRowContext;
+exports.computeRoster = computeRoster;
+exports.rosterHeadline = rosterHeadline;
+/**
+ * x-lt-roster: every member a container row expects, each with its state.
+ * A form field declares `x-lt-widget: "roster"` and an `x-lt-roster` block:
+ *
+ *   "x-lt-roster": {
+ *     "expected": { "query": { "roles": ["packing"], "facets": { "box": "{{escalation.id}}" } } },
+ *     "key": "{{metadata.orderId}}",
+ *     "in": ["items", "resolver.bags"],
+ *     "flagged": [{ "when": "resolver.outcome=missing", "label": "Missing" }]
+ *   }
+ *
+ * The expected set is one of:
+ *   - `query`: member rows matched by role(s) and facets, any status unless
+ *     `status` narrows it. `key` names each row's entry (default its id).
+ *   - `list`: a `domain.path` naming an array of keys on the host row.
+ *   - `batch`: the host row's batch keys; `labels` names a per-key map.
+ *
+ * An entry is `in` when its key is held by the host row (`items`: the
+ * accumulated keys, or a batch's filled keys) or appears in a named context
+ * value (`resolver.<field>`, a string or an array). It is `flagged` when its
+ * member row matches a `flagged` rule, and `waiting` otherwise. In wins over
+ * flagged, so a member flagged on its own row and then added reads in.
+ *
+ * Isomorphic: the dashboard renders the widget and the form's `roster.*`
+ * context from it, and the API layer computes the same counts to evaluate
+ * showIf and the roster submit guard at resolve.
+ */
+const x_lt_bind_1 = require("./x-lt-bind");
+const ctx_path_1 = require("./ctx-path");
+const x_lt_help_1 = require("./x-lt-help");
+const x_lt_show_if_1 = require("./x-lt-show-if");
+exports.X_LT_ROSTER = 'x-lt-roster';
+exports.ROSTER_WIDGET = 'roster';
+/** The context domain the counts are read from: `roster.<field>.outstanding`. */
+exports.ROSTER_DOMAIN = 'roster';
+/** The most member rows a query set reads. */
+exports.ROSTER_QUERY_LIMIT = 200;
+/** The `in` source naming the host row's held keys. */
+exports.ROSTER_ITEMS_SOURCE = 'items';
+/** `query.status` value that reads every status (the default). */
+exports.ROSTER_ANY_STATUS = 'any';
+exports.ROSTER_STATES = { WAITING: 'waiting', IN: 'in', FLAGGED: 'flagged' };
+const DEFAULT_KEY = '{{escalation.id}}';
+const MISSING = '—';
+const BATCH_KEYS = 'batch_keys';
+const BATCH_PENDING = 'batch_pending';
+const ACCUMULATE_KEYS = 'accumulate_keys';
+function isRecord(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function strings(v) {
+    if (typeof v === 'string')
+        return v ? [v] : [];
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((s) => typeof s === 'string' && s.length > 0);
+}
+/** The field's roster declaration, or undefined when it declares none or an unusable one. */
+function readRosterDef(fieldSchema) {
+    const raw = fieldSchema?.[exports.X_LT_ROSTER];
+    if (!isRecord(raw) || !isRecord(raw.expected))
+        return undefined;
+    const e = raw.expected;
+    const hasSource = isRecord(e.query) || typeof e.list === 'string' || e.batch === true;
+    return hasSource ? raw : undefined;
+}
+/** Every roster field of a form schema, by field name. */
+function readRosterDefs(schema) {
+    const properties = isRecord(schema?.properties) ? schema.properties : {};
+    const defs = {};
+    for (const [field, def] of Object.entries(properties)) {
+        const roster = isRecord(def) ? readRosterDef(def) : undefined;
+        if (roster)
+            defs[field] = roster;
+    }
+    return defs;
+}
+/** The roster's member-row query, or null when its set is not a query. */
+function rosterQueryOf(def) {
+    return 'query' in def.expected && isRecord(def.expected.query) ? def.expected.query : null;
+}
+/** The query's concrete params: facets interpolated, `any` status dropped. Null when the scope is empty. */
+function resolveRosterQuery(query, ctx) {
+    const facets = {};
+    for (const [k, v] of Object.entries(query.facets ?? {})) {
+        if (typeof v !== 'string')
+            continue;
+        const resolved = (0, x_lt_help_1.interpolateHelp)(v, ctx);
+        if (!resolved || resolved === MISSING)
+            return null;
+        facets[k] = resolved;
+    }
+    const roles = [...(query.role ? [query.role] : []), ...strings(query.roles)];
+    if (!roles.length && !Object.keys(facets).length)
+        return null;
+    const status = query.status && query.status !== exports.ROSTER_ANY_STATUS ? query.status : undefined;
+    return { ...(roles.length ? { roles } : {}), facets, ...(status ? { status } : {}), limit: exports.ROSTER_QUERY_LIMIT };
+}
+function parseJson(v) {
+    if (isRecord(v))
+        return v;
+    if (typeof v !== 'string' || !v)
+        return null;
+    try {
+        const parsed = JSON.parse(v);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A member row's token context, from a row whose JSON columns are strings or objects. */
+function rosterRowContext(row) {
+    return {
+        escalation: row,
+        metadata: isRecord(row.metadata) ? row.metadata : parseJson(row.metadata),
+        envelope: parseJson(row.envelope),
+        payload: parseJson(row.escalation_payload),
+        resolver: parseJson(row.resolver_payload),
+    };
+}
+/** The keys the host row holds: its accumulated keys, or a batch's filled keys. */
+function heldKeys(ctx) {
+    const metadata = ctx.metadata ?? {};
+    const accumulated = metadata[ACCUMULATE_KEYS];
+    if (Array.isArray(accumulated))
+        return new Set(strings(accumulated));
+    const envelopeItems = (0, x_lt_bind_1.getDeep)(ctx.envelope, 'accumulate_items');
+    if (isRecord(envelopeItems))
+        return new Set(Object.keys(envelopeItems));
+    if (Array.isArray(metadata[BATCH_PENDING])) {
+        const pending = new Set(strings(metadata[BATCH_PENDING]));
+        return new Set(strings(metadata[BATCH_KEYS]).filter((k) => !pending.has(k)));
+    }
+    return new Set();
+}
+function arrivedKeys(def, ctx) {
+    const arrived = new Set();
+    for (const source of def.in ?? [exports.ROSTER_ITEMS_SOURCE]) {
+        const keys = source === exports.ROSTER_ITEMS_SOURCE
+            ? [...heldKeys(ctx)]
+            : strings((0, ctx_path_1.resolveCtxPath)(source, ctx));
+        keys.forEach((k) => arrived.add(k));
+    }
+    return arrived;
+}
+function flagFor(def, row) {
+    if (!row)
+        return undefined;
+    for (const rule of def.flagged ?? []) {
+        const conditions = strings(rule.when);
+        if (!conditions.length || typeof rule.label !== 'string')
+            continue;
+        if ((0, x_lt_show_if_1.evaluateShowIf)(conditions, row))
+            return rule.label;
+    }
+    return undefined;
+}
+/** A row's creation instant in ms; 0 when absent or unreadable. */
+function createdAt(row) {
+    const raw = row.escalation.created_at;
+    const ms = raw instanceof Date ? raw.getTime() : typeof raw === 'string' ? Date.parse(raw) : NaN;
+    return Number.isNaN(ms) ? 0 : ms;
+}
+/**
+ * The expected keys in order, each with its member row (query) or label
+ * (batch). Several rows sharing a key (a member that parked again) read as
+ * one entry on the newest row, so its state and actions follow the live row.
+ */
+function expectedEntries(def, ctx, rows) {
+    const seen = new Set();
+    const out = [];
+    const push = (key, extra = {}) => {
+        if (!key || key === MISSING || seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ key, ...extra });
+    };
+    const e = def.expected;
+    if ('query' in e) {
+        const template = def.key ?? DEFAULT_KEY;
+        const newest = new Map();
+        for (const row of rows) {
+            const key = (0, x_lt_help_1.interpolateHelp)(template, row);
+            const held = newest.get(key);
+            if (!held || createdAt(row) > createdAt(held))
+                newest.set(key, row);
+        }
+        for (const row of rows) {
+            const key = (0, x_lt_help_1.interpolateHelp)(template, row);
+            push(key, { row: newest.get(key) });
+        }
+    }
+    else if ('list' in e) {
+        strings((0, ctx_path_1.resolveCtxPath)(e.list, ctx)).forEach((k) => push(k));
+    }
+    else {
+        const labels = e.labels ? (0, ctx_path_1.resolveCtxPath)(e.labels, ctx) : undefined;
+        for (const key of strings(ctx.metadata?.[BATCH_KEYS])) {
+            push(key, isRecord(labels) && key in labels ? { label: labels[key] } : {});
+        }
+    }
+    return out;
+}
+/**
+ * Every expected entry with its state, and the counts. `rows` are the
+ * member rows a query set read (ignored for list and batch sets). `ctx` is
+ * the host row's context with the live form values under `resolver`.
+ */
+function computeRoster(def, ctx, rows = []) {
+    const arrived = arrivedKeys(def, ctx);
+    const entries = expectedEntries(def, ctx, rows).map((e) => {
+        if (arrived.has(e.key))
+            return { ...e, state: exports.ROSTER_STATES.IN };
+        const flag = flagFor(def, e.row);
+        return flag ? { ...e, state: exports.ROSTER_STATES.FLAGGED, flag } : { ...e, state: exports.ROSTER_STATES.WAITING };
+    });
+    const count = (s) => entries.filter((e) => e.state === s).length;
+    const waiting = count(exports.ROSTER_STATES.WAITING);
+    return {
+        entries,
+        counts: {
+            expected: entries.length,
+            in: count(exports.ROSTER_STATES.IN),
+            flagged: count(exports.ROSTER_STATES.FLAGGED),
+            waiting,
+            outstanding: waiting,
+        },
+    };
+}
+/** The header line: "3 of 5 in · 1 Missing". */
+function rosterHeadline(result) {
+    const { counts } = result;
+    const parts = [`${counts.in} of ${counts.expected} in`];
+    const byFlag = new Map();
+    for (const e of result.entries) {
+        if (e.state === exports.ROSTER_STATES.FLAGGED && e.flag)
+            byFlag.set(e.flag, (byFlag.get(e.flag) ?? 0) + 1);
+    }
+    for (const [flag, n] of byFlag)
+        parts.push(`${n} ${flag}`);
+    return parts.join(' · ');
+}

package/build/shared/form-validation/x-lt-show-if.d.ts

@@ -11,3 +11,11 @@ export declare function evaluateShowIf(condition: unknown, ctx: ShowIfContext |
  * (null, undefined, '', false, or 0). Render and validation share this test.
  */
 export declare function isHiddenIfEmpty(fieldSchema: Record<string, unknown> | undefined, value: unknown): boolean;
+/**
+ * `x-lt-hidden: true`: the field never renders. A value set by the caller
+ * (a workflow default, an API submitter) passes through to the payload and
+ * is checked against the field's type and enum; the field is never required,
+ * since no one on the form can answer it.
+ */
+export declare const X_LT_HIDDEN = "x-lt-hidden";
+export declare function isHiddenField(fieldSchema: Record<string, unknown> | undefined): boolean;

package/build/shared/form-validation/x-lt-show-if.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.X_LT_HIDDEN = void 0;
 exports.evaluateShowIf = evaluateShowIf;
 exports.isHiddenIfEmpty = isHiddenIfEmpty;
+exports.isHiddenField = isHiddenField;
 /**
  * x-lt-showIf — conditional field visibility. A form_schema property may
  * declare `x-lt-showIf: "domain.path"` to show the field only when the value
@@ -21,6 +23,7 @@ exports.isHiddenIfEmpty = isHiddenIfEmpty;
  *   envelope   — the workflow-sent input envelope
  *   escalation — top-level escalation row fields
  *   resolver   — the submitted resolver payload
+ *   roster     (each roster field's counts: `roster.orders.outstanding=0`)
  *
  * A missing or non-string condition always shows the field (opt-in, safe default).
  */
@@ -95,3 +98,13 @@ function isHiddenIfEmpty(fieldSchema, value) {
         return false;
     return value === null || value === undefined || value === '' || value === false || value === 0;
 }
+/**
+ * `x-lt-hidden: true`: the field never renders. A value set by the caller
+ * (a workflow default, an API submitter) passes through to the payload and
+ * is checked against the field's type and enum; the field is never required,
+ * since no one on the form can answer it.
+ */
+exports.X_LT_HIDDEN = 'x-lt-hidden';
+function isHiddenField(fieldSchema) {
+    return fieldSchema?.[exports.X_LT_HIDDEN] === true;
+}

package/build/shared/form-validation/x-lt-submit-guard.d.ts

@@ -23,11 +23,23 @@
  * `autoResolveWhenEmpty` closes the loop: the moment the query is confirmed
  * empty, the claimed parent auto-submits — checked on page-load and after each
  * inline child-resolve — so a set of escalations completes with no extra click.
+ *
+ * A guard may name a roster field instead of a query: the resolve waits while
+ * that roster has outstanding entries (x-lt-roster.ts), so the list the person
+ * works from and the rule that holds the submit are one computation.
+ *
+ *   "x-lt-submit-guard": { "roster": "orders",
+ *                          "message": "{{count}} orders are still unaccounted for" }
+ *
+ * `{{count}}` is the outstanding count. A roster guard never auto-submits.
  */
 import type { EmbedQuery } from './x-lt-query';
 export declare const X_LT_SUBMIT_GUARD = "x-lt-submit-guard";
 export interface SubmitGuardDef {
-    query: EmbedQuery;
+    /** The embedded query that must be empty; absent for a roster guard. */
+    query?: EmbedQuery;
+    /** A roster field whose outstanding entries hold the resolve. */
+    roster?: string;
     /** The gate condition; defaults to true (the only supported mode today). */
     mustBeEmpty?: boolean;
     /** Shown beside the disabled submit. `{{count}}` and `{{domain.path}}` tokens interpolate. */
@@ -36,6 +48,7 @@ export interface SubmitGuardDef {
     autoResolveWhenEmpty?: boolean;
 }
 export declare const SUBMIT_GUARD_DEFAULT_MESSAGE = "{{count}} related items are still pending";
+export declare const ROSTER_GUARD_DEFAULT_MESSAGE = "{{count}} expected items are still outstanding";
 /** The schema's submit-guard, or undefined when it declares none. */
 export declare function readSubmitGuard(schema: Record<string, unknown> | null | undefined): SubmitGuardDef | undefined;
 /**

package/build/shared/form-validation/x-lt-submit-guard.js

@@ -1,16 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUBMIT_GUARD_DEFAULT_MESSAGE = exports.X_LT_SUBMIT_GUARD = void 0;
+exports.ROSTER_GUARD_DEFAULT_MESSAGE = exports.SUBMIT_GUARD_DEFAULT_MESSAGE = exports.X_LT_SUBMIT_GUARD = void 0;
 exports.readSubmitGuard = readSubmitGuard;
 exports.guardBlocks = guardBlocks;
 exports.X_LT_SUBMIT_GUARD = 'x-lt-submit-guard';
 exports.SUBMIT_GUARD_DEFAULT_MESSAGE = '{{count}} related items are still pending';
+exports.ROSTER_GUARD_DEFAULT_MESSAGE = '{{count}} expected items are still outstanding';
 /** The schema's submit-guard, or undefined when it declares none. */
 function readSubmitGuard(schema) {
     const raw = schema?.[exports.X_LT_SUBMIT_GUARD];
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return undefined;
     const guard = raw;
+    if (typeof guard.roster === 'string' && guard.roster)
+        return guard;
     if (!guard.query || typeof guard.query !== 'object')
         return undefined;
     return guard;

package/build/shared/list-schema/aggregate.d.ts

@@ -0,0 +1,19 @@
+import { RELATED_AGGREGATES, type RelatedAggregate, type RelatedColumnDecl } from './types';
+export type RelatedExtreme = typeof RELATED_AGGREGATES.MIN | typeof RELATED_AGGREGATES.MAX;
+/** True for the aggregates that pick one value rather than count. */
+export declare function isExtremeAggregate(aggregate: unknown): aggregate is RelatedExtreme;
+/**
+ * The stored path a min/max `value` template reads: `payload.<path>` for an
+ * items set, `metadata.<key>` for a query set. Null when the template does
+ * not fit the set's source.
+ */
+export declare function relatedValuePath(source: string, value: unknown): string | null;
+/** The key a column's per-host aggregates are stored under in its set's result. */
+export declare function relatedAggregateKey(col: Pick<RelatedColumnDecl, 'aggregate' | 'splitBy' | 'value'>, source: string): string;
+/** A count column's display text, or null when the column declares none for this count. */
+export declare function relatedCountText(display: Record<string, string> | undefined, count: number): string | null;
+/**
+ * The least or greatest of several values: numbers when every value is a
+ * number, otherwise text in code-unit order (ISO instants order as text).
+ */
+export declare function foldExtreme(fold: RelatedAggregate, values: Array<string | number>): string | number | undefined;

package/build/shared/list-schema/aggregate.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExtremeAggregate = isExtremeAggregate;
+exports.relatedValuePath = relatedValuePath;
+exports.relatedAggregateKey = relatedAggregateKey;
+exports.relatedCountText = relatedCountText;
+exports.foldExtreme = foldExtreme;
+const types_1 = require("./types");
+const VALUE_TOKEN = /^\{\{\s*([^{}]+?)\s*\}\}$/;
+const ITEM_PREFIX = 'item.';
+const PATH_SEGMENT = /^[a-zA-Z0-9_]+$/;
+const METADATA_KEY = /^[a-zA-Z0-9_]+$/;
+const COUNT_TOKEN = /\{n\}/g;
+/** True for the aggregates that pick one value rather than count. */
+function isExtremeAggregate(aggregate) {
+    return aggregate === types_1.RELATED_AGGREGATES.MIN || aggregate === types_1.RELATED_AGGREGATES.MAX;
+}
+/**
+ * The stored path a min/max `value` template reads: `payload.<path>` for an
+ * items set, `metadata.<key>` for a query set. Null when the template does
+ * not fit the set's source.
+ */
+function relatedValuePath(source, value) {
+    if (typeof value !== 'string')
+        return null;
+    const token = value.match(VALUE_TOKEN)?.[1];
+    if (!token)
+        return null;
+    if (source === types_1.RELATED_SOURCES.ITEMS) {
+        if (!token.startsWith(`${ITEM_PREFIX}${types_1.SPLIT_PATHS.PAYLOAD}`))
+            return null;
+        const path = token.slice(ITEM_PREFIX.length + types_1.SPLIT_PATHS.PAYLOAD.length);
+        return path && path.split('.').every((s) => PATH_SEGMENT.test(s)) ? `${types_1.SPLIT_PATHS.PAYLOAD}${path}` : null;
+    }
+    if (!token.startsWith(types_1.SPLIT_PATHS.METADATA))
+        return null;
+    const key = token.slice(types_1.SPLIT_PATHS.METADATA.length);
+    return METADATA_KEY.test(key) ? token : null;
+}
+/** The key a column's per-host aggregates are stored under in its set's result. */
+function relatedAggregateKey(col, source) {
+    if (isExtremeAggregate(col.aggregate))
+        return `${col.aggregate}:${relatedValuePath(source, col.value) ?? ''}`;
+    return col.splitBy ?? '';
+}
+/** A count column's display text, or null when the column declares none for this count. */
+function relatedCountText(display, count) {
+    if (!display)
+        return null;
+    const text = display[String(count)] ?? display[types_1.RELATED_DISPLAY_DEFAULT];
+    return text === undefined ? null : text.replace(COUNT_TOKEN, String(count));
+}
+/**
+ * The least or greatest of several values: numbers when every value is a
+ * number, otherwise text in code-unit order (ISO instants order as text).
+ */
+function foldExtreme(fold, values) {
+    if (!values.length)
+        return undefined;
+    const pickMin = fold === types_1.RELATED_AGGREGATES.MIN;
+    if (values.every((v) => typeof v === 'number')) {
+        return pickMin ? Math.min(...values) : Math.max(...values);
+    }
+    const texts = values.map(String).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return pickMin ? texts[0] : texts[texts.length - 1];
+}

package/build/shared/list-schema/index.d.ts

@@ -1,3 +1,5 @@
 export * from './types';
 export { METADATA_KEY, readListSchemaRelations, listSchemaRelationsError, splitPathError } from './validate';
 export { rowTemplateContext, resolveTemplateValue, resolveRelatedFacets } from './template';
+export type { RelatedExtreme } from './aggregate';
+export { isExtremeAggregate, relatedValuePath, relatedAggregateKey, relatedCountText, foldExtreme } from './aggregate';

package/build/shared/list-schema/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveRelatedFacets = exports.resolveTemplateValue = exports.rowTemplateContext = exports.splitPathError = exports.listSchemaRelationsError = exports.readListSchemaRelations = exports.METADATA_KEY = void 0;
+exports.foldExtreme = exports.relatedCountText = exports.relatedAggregateKey = exports.relatedValuePath = exports.isExtremeAggregate = exports.resolveRelatedFacets = exports.resolveTemplateValue = exports.rowTemplateContext = exports.splitPathError = exports.listSchemaRelationsError = exports.readListSchemaRelations = exports.METADATA_KEY = void 0;
 __exportStar(require("./types"), exports);
 var validate_1 = require("./validate");
 Object.defineProperty(exports, "METADATA_KEY", { enumerable: true, get: function () { return validate_1.METADATA_KEY; } });
@@ -25,3 +25,9 @@ var template_1 = require("./template");
 Object.defineProperty(exports, "rowTemplateContext", { enumerable: true, get: function () { return template_1.rowTemplateContext; } });
 Object.defineProperty(exports, "resolveTemplateValue", { enumerable: true, get: function () { return template_1.resolveTemplateValue; } });
 Object.defineProperty(exports, "resolveRelatedFacets", { enumerable: true, get: function () { return template_1.resolveRelatedFacets; } });
+var aggregate_1 = require("./aggregate");
+Object.defineProperty(exports, "isExtremeAggregate", { enumerable: true, get: function () { return aggregate_1.isExtremeAggregate; } });
+Object.defineProperty(exports, "relatedValuePath", { enumerable: true, get: function () { return aggregate_1.relatedValuePath; } });
+Object.defineProperty(exports, "relatedAggregateKey", { enumerable: true, get: function () { return aggregate_1.relatedAggregateKey; } });
+Object.defineProperty(exports, "relatedCountText", { enumerable: true, get: function () { return aggregate_1.relatedCountText; } });
+Object.defineProperty(exports, "foldExtreme", { enumerable: true, get: function () { return aggregate_1.foldExtreme; } });

package/build/shared/list-schema/types.d.ts

@@ -23,6 +23,9 @@ export declare const RELATED_SOURCES: {
 export type RelatedSource = (typeof RELATED_SOURCES)[keyof typeof RELATED_SOURCES];
 export declare const RELATED_AGGREGATES: {
     readonly COUNT: "count";
+    /** The least item or row value: numbers as numbers, everything else as text. */
+    readonly MIN: "min";
+    readonly MAX: "max";
 };
 export type RelatedAggregate = (typeof RELATED_AGGREGATES)[keyof typeof RELATED_AGGREGATES];
 /** How a grouped table folds a plain column across a group's rows. */
@@ -73,10 +76,18 @@ export interface RelatedSetDecl {
     source: RelatedSource;
     query?: RelatedQueryDecl;
 }
+/** A count column's text keyed by count; `default` covers the rest, `{n}` reads the count. */
+export declare const RELATED_DISPLAY_DEFAULT = "default";
 export interface RelatedColumnDecl {
     label: string;
     related: string;
     aggregate?: RelatedAggregate;
+    /** min/max: `{{item.payload.<path>}}` on an items set, `{{metadata.<key>}}` on a query set. */
+    value?: string;
+    /** min/max: how the value renders, as on any facet-table column. */
+    format?: string;
+    /** count: text by count, e.g. `{ "0": "Ready", "default": "Waiting on {n}" }`. */
+    display?: Record<string, string>;
     splitBy?: string;
     labels?: Record<string, string>;
     priority?: 1 | 2 | 3;
@@ -103,9 +114,11 @@ export interface ListSchemaRelations {
     /** The metadata key a facet-table groups by, when declared. */
     groupKey: string | null;
 }
-/** Per-host aggregate for one (set, splitBy) pair. */
+/** Per-host aggregate for one (set, splitBy) pair, or one (set, min/max, value) triple. */
 export interface RelatedHostAggregate {
     count: number;
+    /** min/max: the extreme value among `count` values; absent when none carries one. */
+    value?: string | number;
     /** Split value to count; a null value is keyed by the empty string. */
     splits?: Record<string, number>;
     /** Items whose reciprocal row the viewer cannot read. */
@@ -125,7 +138,7 @@ export interface RelatedSetResult {
     roleLabels?: Record<string, string>;
     /** Query sets: declared roles outside the viewer's full read scope. */
     restricted?: string[];
-    /** Keyed by splitBy ('' when unsplit), then host id. */
+    /** Keyed by relatedAggregateKey (the splitBy, '' when unsplit, or `min:<path>`), then host id. */
     aggregates: Record<string, Record<string, RelatedHostAggregate>>;
 }
 export interface RelatedAggregatesResponse {