@hotmeshio/long-tail 0.23.1 → 0.24.0

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

@@ -5,6 +5,7 @@ exports.readScanSink = readScanSink;
 exports.sameScanValue = sameScanValue;
 exports.resolveScanExpected = resolveScanExpected;
 exports.scanSinkError = scanSinkError;
+exports.scanTargetCount = scanTargetCount;
 exports.applyScanToField = applyScanToField;
 exports.pickScanSink = pickScanSink;
 exports.wantsScanSubmit = wantsScanSubmit;
@@ -27,7 +28,9 @@ exports.scanFieldsFilled = scanFieldsFilled;
  * Root `x-lt-scan-submit: true` submits once every required scan field is
  * filled and the form validates. A string field is replaced by a scan; an
  * array field appends, and with `multiplicity: "count"` a value expected n
- * times takes n scans.
+ * times takes n scans. `prompt` is the empty array field's instruction (the
+ * field description when absent); the field reads `n of N` against the same
+ * expected list that admits each scan, or `maxItems`.
  */
 const ctx_path_1 = require("./ctx-path");
 exports.X_LT_SCAN = 'x-lt-scan';
@@ -50,6 +53,7 @@ function readScanSink(fieldSchema) {
         ...(expect?.length ? { expect } : {}),
         expectError: typeof cfg['expect-error'] === 'string' ? cfg['expect-error'] : DEFAULT_EXPECT_ERROR,
         multiplicity: cfg.multiplicity === 'count' ? 'count' : 'once',
+        ...(typeof cfg.prompt === 'string' && cfg.prompt.trim() ? { prompt: cfg.prompt } : {}),
     };
 }
 /** Manufacturer barcodes compare as GTINs, so a UPC-A matches its 14-digit form. */
@@ -102,6 +106,21 @@ function scanSinkError(value, fieldSchema, ctx) {
     }
     return undefined;
 }
+/**
+ * How many scans complete an array field: the scans its expected list admits
+ * (each listing under 'count', each distinct value otherwise), else
+ * `maxItems`, else null. The checklist and the admission gate share it.
+ */
+function scanTargetCount(fieldSchema, ctx) {
+    const sink = readScanSink(fieldSchema);
+    if (sink) {
+        const expected = resolveScanExpected(sink, ctx);
+        if (expected !== null)
+            return sink.multiplicity === 'count' ? expected.length : new Set(expected).size;
+    }
+    const max = fieldSchema?.maxItems;
+    return typeof max === 'number' ? max : null;
+}
 /** What a scan does to a field: the next value, or the error to show (nothing written). */
 function applyScanToField(current, scan, fieldSchema, ctx) {
     const sink = readScanSink(fieldSchema);

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

@@ -0,0 +1,3 @@
+export * from './types';
+export { METADATA_KEY, readListSchemaRelations, listSchemaRelationsError, splitPathError } from './validate';
+export { rowTemplateContext, resolveTemplateValue, resolveRelatedFacets } from './template';

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

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+__exportStar(require("./types"), exports);
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "METADATA_KEY", { enumerable: true, get: function () { return validate_1.METADATA_KEY; } });
+Object.defineProperty(exports, "readListSchemaRelations", { enumerable: true, get: function () { return validate_1.readListSchemaRelations; } });
+Object.defineProperty(exports, "listSchemaRelationsError", { enumerable: true, get: function () { return validate_1.listSchemaRelationsError; } });
+Object.defineProperty(exports, "splitPathError", { enumerable: true, get: function () { return validate_1.splitPathError; } });
+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; } });

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

@@ -0,0 +1,14 @@
+import { type HelpTokenContext } from '../form-validation/x-lt-help';
+/** The template domains of one escalation row, JSON-string columns parsed. */
+export declare function rowTemplateContext(row: Record<string, unknown>): HelpTokenContext;
+/**
+ * Resolve one facet value. A lone `{{token}}` keeps the value's own JSON type
+ * (a numeric facet matches a numeric facet); a mixed template interpolates to
+ * a string; a literal passes through. Undefined when a token is missing.
+ */
+export declare function resolveTemplateValue(value: unknown, ctx: HelpTokenContext): unknown;
+/**
+ * Resolve a related query's match against a host row: every required facet
+ * (null when any is missing), plus each `narrow` facet the row resolves.
+ */
+export declare function resolveRelatedFacets(facets: Record<string, unknown>, ctx: HelpTokenContext, narrow?: Record<string, unknown>): Record<string, unknown> | null;

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

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rowTemplateContext = rowTemplateContext;
+exports.resolveTemplateValue = resolveTemplateValue;
+exports.resolveRelatedFacets = resolveRelatedFacets;
+const x_lt_bind_1 = require("../form-validation/x-lt-bind");
+const x_lt_help_1 = require("../form-validation/x-lt-help");
+const SINGLE_TOKEN = /^\{\{\s*([^{}]+?)\s*\}\}$/;
+const ANY_TOKEN = /\{\{\s*[^{}]+?\s*\}\}/;
+const MISSING_VALUE = '—';
+function parseJsonObject(value) {
+    if (value && typeof value === 'object')
+        return value;
+    if (typeof value !== 'string' || !value)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The template domains of one escalation row, JSON-string columns parsed. */
+function rowTemplateContext(row) {
+    return {
+        escalation: row,
+        metadata: row.metadata ?? {},
+        envelope: parseJsonObject(row.envelope) ?? {},
+        payload: parseJsonObject(row.escalation_payload) ?? {},
+        resolver: parseJsonObject(row.resolver_payload) ?? {},
+    };
+}
+function readToken(path, ctx) {
+    const dot = path.indexOf('.');
+    const domain = (dot === -1 ? path : path.slice(0, dot));
+    if (!x_lt_help_1.HELP_DOMAINS.includes(domain))
+        return undefined;
+    const root = ctx[domain];
+    if (dot === -1)
+        return root ?? undefined;
+    try {
+        return (0, x_lt_bind_1.getDeep)(root, path.slice(dot + 1));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve one facet value. A lone `{{token}}` keeps the value's own JSON type
+ * (a numeric facet matches a numeric facet); a mixed template interpolates to
+ * a string; a literal passes through. Undefined when a token is missing.
+ */
+function resolveTemplateValue(value, ctx) {
+    if (typeof value !== 'string')
+        return value;
+    const single = value.match(SINGLE_TOKEN);
+    if (single) {
+        const raw = readToken(single[1], ctx);
+        return raw === null || raw === '' ? undefined : raw;
+    }
+    if (!ANY_TOKEN.test(value))
+        return value;
+    const text = (0, x_lt_help_1.interpolateHelp)(value, ctx);
+    return text.includes(MISSING_VALUE) ? undefined : text;
+}
+/**
+ * Resolve a related query's match against a host row: every required facet
+ * (null when any is missing), plus each `narrow` facet the row resolves.
+ */
+function resolveRelatedFacets(facets, ctx, narrow) {
+    const out = {};
+    for (const [key, value] of Object.entries(facets)) {
+        const resolved = resolveTemplateValue(value, ctx);
+        if (resolved === undefined)
+            return null;
+        out[key] = resolved;
+    }
+    for (const [key, value] of Object.entries(narrow ?? {})) {
+        const resolved = resolveTemplateValue(value, ctx);
+        if (resolved !== undefined)
+            out[key] = resolved;
+    }
+    return out;
+}

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

@@ -0,0 +1,154 @@
+/**
+ * Related sets on a role's list schema. A set is named once under
+ * `x-lt-related`; columns (`related`) and row details (`x-lt-row-detail`)
+ * reference it by name. The server reads the declaration from the stored
+ * list schema, never from the caller.
+ *
+ *   items  the host row's accumulated or batch items, each read through its
+ *          payload or its reciprocal row
+ *   query  rows in other roles that share facets with the host row; facet
+ *          values are `{{domain.path}}` templates over the host row
+ */
+export declare const LIST_SCHEMA_KEYS: {
+    readonly RELATED: "x-lt-related";
+    readonly COLUMNS: "x-lt-columns";
+    readonly ROW_DETAIL: "x-lt-row-detail";
+    readonly GROUP_BY: "x-lt-group-by";
+    readonly LAYOUT: "x-lt-layout";
+};
+export declare const RELATED_SOURCES: {
+    readonly ITEMS: "items";
+    readonly QUERY: "query";
+};
+export type RelatedSource = (typeof RELATED_SOURCES)[keyof typeof RELATED_SOURCES];
+export declare const RELATED_AGGREGATES: {
+    readonly COUNT: "count";
+};
+export type RelatedAggregate = (typeof RELATED_AGGREGATES)[keyof typeof RELATED_AGGREGATES];
+/** How a grouped table folds a plain column across a group's rows. */
+export declare const GROUP_FOLDS: {
+    readonly FIRST: "first";
+    readonly MIN: "min";
+    readonly MAX: "max";
+    readonly SUM: "sum";
+    readonly COUNT: "count";
+    /** The distinct values, in row order, joined: "standard, express". */
+    readonly DISTINCT: "distinct";
+};
+export type GroupFold = (typeof GROUP_FOLDS)[keyof typeof GROUP_FOLDS];
+/** Split prefixes. `role` splits a query set by the related row's role. */
+export declare const SPLIT_PATHS: {
+    readonly ROLE: "role";
+    readonly METADATA: "metadata.";
+    readonly PAYLOAD: "payload.";
+    readonly RECIPROCAL_METADATA: "reciprocal.metadata.";
+};
+export declare const RELATED_LIMITS: {
+    readonly MAX_SETS: 4;
+    readonly MAX_QUERY_ROLES: 12;
+    readonly MAX_ROW_DETAIL_SECTIONS: 4;
+    readonly MAX_HOSTS: 100;
+    readonly ROWS_DEFAULT: 25;
+    readonly ROWS_MAX: 100;
+};
+/** The table layout that renders related columns, row details, and groups. */
+export declare const FACET_TABLE_LAYOUT = "facet-table";
+export interface RelatedQueryDecl {
+    /** Related roles, in display order. Exclusive with `segment`. */
+    roles?: string[];
+    /** A Pace Board sequence by its first role; resolves to the ordered chain. */
+    segment?: string;
+    /** Facet containment; string values may be `{{domain.path}}` templates. */
+    facets?: Record<string, unknown>;
+    /**
+     * Facets that narrow the match when the host row carries a value, and
+     * drop away when it does not: a lane narrows its tub's look-ahead to its
+     * own service level, a tub without lanes keeps the whole destination.
+     */
+    narrow?: Record<string, unknown>;
+    /** Default `pending`. */
+    status?: string;
+}
+export interface RelatedSetDecl {
+    source: RelatedSource;
+    query?: RelatedQueryDecl;
+}
+export interface RelatedColumnDecl {
+    label: string;
+    related: string;
+    aggregate?: RelatedAggregate;
+    splitBy?: string;
+    labels?: Record<string, string>;
+    priority?: 1 | 2 | 3;
+    /** CSS width, as on any facet-table column. */
+    width?: string;
+}
+export interface RowDetailColumnDecl {
+    label: string;
+    value: string;
+    format?: string;
+    priority?: 1 | 2 | 3;
+}
+export interface RowDetailSectionDecl {
+    related: string;
+    label?: string;
+    columns: RowDetailColumnDecl[];
+    limit?: number;
+}
+/** The validated, normalized related declaration of one list schema. */
+export interface ListSchemaRelations {
+    sets: Record<string, RelatedSetDecl>;
+    columns: RelatedColumnDecl[];
+    rowDetail: RowDetailSectionDecl[];
+    /** The metadata key a facet-table groups by, when declared. */
+    groupKey: string | null;
+}
+/** Per-host aggregate for one (set, splitBy) pair. */
+export interface RelatedHostAggregate {
+    count: 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. */
+    hidden?: number;
+    /** A host whose facet templates resolved to nothing; the set did not run. */
+    unresolved?: boolean;
+}
+export interface RelatedSetResult {
+    source: RelatedSource;
+    /**
+     * The roles whose rows the set reads, which a list follows for live
+     * changes: a query set's resolved roles in order, or the roles of an item
+     * set's readable reciprocal rows when a column splits by them.
+     */
+    roles?: string[];
+    /** Query sets: role titles, keyed by role. */
+    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. */
+    aggregates: Record<string, Record<string, RelatedHostAggregate>>;
+}
+export interface RelatedAggregatesResponse {
+    version: number | null;
+    sets: Record<string, RelatedSetResult>;
+}
+export interface RelatedItemEntry {
+    itemKey: string;
+    payload?: unknown;
+    at?: string;
+    actor?: string;
+    reciprocalId?: string;
+}
+export interface RelatedRow {
+    /** Items sets only. */
+    item?: RelatedItemEntry;
+    /** The reciprocal row (items) or the related row (query); null when unreadable. */
+    escalation: Record<string, unknown> | null;
+}
+export interface RelatedRowsResponse {
+    source: RelatedSource;
+    rows: RelatedRow[];
+    total: number;
+    restricted?: string[];
+    roleLabels?: Record<string, string>;
+}

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

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Related sets on a role's list schema. A set is named once under
+ * `x-lt-related`; columns (`related`) and row details (`x-lt-row-detail`)
+ * reference it by name. The server reads the declaration from the stored
+ * list schema, never from the caller.
+ *
+ *   items  the host row's accumulated or batch items, each read through its
+ *          payload or its reciprocal row
+ *   query  rows in other roles that share facets with the host row; facet
+ *          values are `{{domain.path}}` templates over the host row
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FACET_TABLE_LAYOUT = exports.RELATED_LIMITS = exports.SPLIT_PATHS = exports.GROUP_FOLDS = exports.RELATED_AGGREGATES = exports.RELATED_SOURCES = exports.LIST_SCHEMA_KEYS = void 0;
+exports.LIST_SCHEMA_KEYS = {
+    RELATED: 'x-lt-related',
+    COLUMNS: 'x-lt-columns',
+    ROW_DETAIL: 'x-lt-row-detail',
+    GROUP_BY: 'x-lt-group-by',
+    LAYOUT: 'x-lt-layout',
+};
+exports.RELATED_SOURCES = {
+    ITEMS: 'items',
+    QUERY: 'query',
+};
+exports.RELATED_AGGREGATES = {
+    COUNT: 'count',
+};
+/** How a grouped table folds a plain column across a group's rows. */
+exports.GROUP_FOLDS = {
+    FIRST: 'first',
+    MIN: 'min',
+    MAX: 'max',
+    SUM: 'sum',
+    COUNT: 'count',
+    /** The distinct values, in row order, joined: "standard, express". */
+    DISTINCT: 'distinct',
+};
+/** Split prefixes. `role` splits a query set by the related row's role. */
+exports.SPLIT_PATHS = {
+    ROLE: 'role',
+    METADATA: 'metadata.',
+    PAYLOAD: 'payload.',
+    RECIPROCAL_METADATA: 'reciprocal.metadata.',
+};
+exports.RELATED_LIMITS = {
+    MAX_SETS: 4,
+    MAX_QUERY_ROLES: 12,
+    MAX_ROW_DETAIL_SECTIONS: 4,
+    MAX_HOSTS: 100,
+    ROWS_DEFAULT: 25,
+    ROWS_MAX: 100,
+};
+/** The table layout that renders related columns, row details, and groups. */
+exports.FACET_TABLE_LAYOUT = 'facet-table';

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

@@ -0,0 +1,12 @@
+import { type ListSchemaRelations } from './types';
+/** A metadata key: interpolated as a JSON path, so strictly validated. */
+export declare const METADATA_KEY: RegExp;
+/** The split paths a set's source accepts. */
+export declare function splitPathError(source: string, splitBy: string): string | null;
+/**
+ * Validate and normalize the related declaration of a list schema. Throws on
+ * an invalid declaration; keys outside this vocabulary stay opaque.
+ */
+export declare function readListSchemaRelations(schema: unknown): ListSchemaRelations;
+/** The declaration's first error, or null when valid. */
+export declare function listSchemaRelationsError(schema: unknown): string | null;

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

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METADATA_KEY = void 0;
+exports.splitPathError = splitPathError;
+exports.readListSchemaRelations = readListSchemaRelations;
+exports.listSchemaRelationsError = listSchemaRelationsError;
+const types_1 = require("./types");
+/** A metadata key: interpolated as a JSON path, so strictly validated. */
+exports.METADATA_KEY = /^[a-zA-Z0-9_]+$/;
+const SET_NAME = /^[a-zA-Z][a-zA-Z0-9_-]{0,47}$/;
+const PATH_SEGMENT = /^[a-zA-Z0-9_]+$/;
+class ListSchemaError extends Error {
+}
+function fail(message) {
+    throw new ListSchemaError(message);
+}
+function isObj(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/** True when a dotted path has only plain segments. */
+function isPlainPath(path) {
+    return path.length > 0 && path.split('.').every((s) => PATH_SEGMENT.test(s));
+}
+/** The split paths a set's source accepts. */
+function splitPathError(source, splitBy) {
+    if (source === types_1.RELATED_SOURCES.QUERY) {
+        if (splitBy === types_1.SPLIT_PATHS.ROLE)
+            return null;
+        if (splitBy.startsWith(types_1.SPLIT_PATHS.METADATA) && exports.METADATA_KEY.test(splitBy.slice(types_1.SPLIT_PATHS.METADATA.length)))
+            return null;
+        return `splitBy "${splitBy}" on a query set must be "role" or "metadata.<key>"`;
+    }
+    if (splitBy.startsWith(types_1.SPLIT_PATHS.PAYLOAD) && isPlainPath(splitBy.slice(types_1.SPLIT_PATHS.PAYLOAD.length)))
+        return null;
+    if (splitBy.startsWith(types_1.SPLIT_PATHS.RECIPROCAL_METADATA)
+        && exports.METADATA_KEY.test(splitBy.slice(types_1.SPLIT_PATHS.RECIPROCAL_METADATA.length)))
+        return null;
+    return `splitBy "${splitBy}" on an items set must be "payload.<path>" or "reciprocal.metadata.<key>"`;
+}
+function readSet(name, raw) {
+    if (!SET_NAME.test(name))
+        fail(`x-lt-related name "${name}" must start with a letter (letters, digits, _ or -)`);
+    if (!isObj(raw))
+        fail(`x-lt-related.${name} must be an object`);
+    if (raw.source === types_1.RELATED_SOURCES.ITEMS) {
+        if (raw.query !== undefined)
+            fail(`x-lt-related.${name}: an items set takes no query`);
+        return { source: types_1.RELATED_SOURCES.ITEMS };
+    }
+    if (raw.source !== types_1.RELATED_SOURCES.QUERY)
+        fail(`x-lt-related.${name}.source must be "items" or "query"`);
+    const q = raw.query;
+    if (!isObj(q))
+        fail(`x-lt-related.${name}.query is required for a query set`);
+    const hasRoles = q.roles !== undefined;
+    const hasSegment = q.segment !== undefined;
+    if (hasRoles === hasSegment)
+        fail(`x-lt-related.${name}.query takes exactly one of roles or segment`);
+    if (hasRoles) {
+        const roles = q.roles;
+        if (!Array.isArray(roles) || roles.length === 0 || roles.length > types_1.RELATED_LIMITS.MAX_QUERY_ROLES
+            || !roles.every(isNonEmptyString)) {
+            fail(`x-lt-related.${name}.query.roles must be 1..${types_1.RELATED_LIMITS.MAX_QUERY_ROLES} role names`);
+        }
+    }
+    else if (!isNonEmptyString(q.segment)) {
+        fail(`x-lt-related.${name}.query.segment must be a role name`);
+    }
+    if (!isObj(q.facets) || Object.keys(q.facets).length === 0) {
+        fail(`x-lt-related.${name}.query.facets must name at least one facet`);
+    }
+    for (const [key, value] of Object.entries(q.facets)) {
+        if (!exports.METADATA_KEY.test(key))
+            fail(`x-lt-related.${name}.query.facets key "${key}" must be letters, digits or _`);
+        if (value === null || typeof value === 'object')
+            fail(`x-lt-related.${name}.query.facets.${key} must be a scalar or template`);
+    }
+    if (q.narrow !== undefined) {
+        if (!isObj(q.narrow) || Object.keys(q.narrow).length === 0)
+            fail(`x-lt-related.${name}.query.narrow must name at least one facet`);
+        for (const [key, value] of Object.entries(q.narrow)) {
+            if (!exports.METADATA_KEY.test(key))
+                fail(`x-lt-related.${name}.query.narrow key "${key}" must be letters, digits or _`);
+            if (key in q.facets)
+                fail(`x-lt-related.${name}.query.narrow.${key} is already a required facet`);
+            if (value === null || typeof value === 'object')
+                fail(`x-lt-related.${name}.query.narrow.${key} must be a scalar or template`);
+        }
+    }
+    if (q.status !== undefined && !isNonEmptyString(q.status))
+        fail(`x-lt-related.${name}.query.status must be a status`);
+    return {
+        source: types_1.RELATED_SOURCES.QUERY,
+        query: {
+            ...(hasRoles ? { roles: [...q.roles] } : { segment: q.segment }),
+            facets: { ...q.facets },
+            ...(q.narrow !== undefined ? { narrow: { ...q.narrow } } : {}),
+            ...(q.status !== undefined ? { status: q.status } : {}),
+        },
+    };
+}
+function readRelatedColumn(raw, sets, at) {
+    const name = raw.related;
+    if (!isNonEmptyString(name) || !sets[name])
+        fail(`${at}.related must name a set declared in x-lt-related`);
+    if (raw.aggregate !== undefined && raw.aggregate !== types_1.RELATED_AGGREGATES.COUNT)
+        fail(`${at}.aggregate must be "count"`);
+    if (raw.splitBy !== undefined) {
+        if (!isNonEmptyString(raw.splitBy))
+            fail(`${at}.splitBy must be a path`);
+        const err = splitPathError(sets[name].source, raw.splitBy);
+        if (err)
+            fail(`${at}: ${err}`);
+    }
+    if (raw.labels !== undefined && (!isObj(raw.labels) || !Object.values(raw.labels).every((v) => typeof v === 'string'))) {
+        fail(`${at}.labels must map values to display text`);
+    }
+    return raw;
+}
+function readRowDetail(raw, sets) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > types_1.RELATED_LIMITS.MAX_ROW_DETAIL_SECTIONS) {
+        fail(`x-lt-row-detail must be 1..${types_1.RELATED_LIMITS.MAX_ROW_DETAIL_SECTIONS} sections`);
+    }
+    return raw.map((section, i) => {
+        const at = `x-lt-row-detail[${i}]`;
+        if (!isObj(section))
+            fail(`${at} must be an object`);
+        if (!isNonEmptyString(section.related) || !sets[section.related])
+            fail(`${at}.related must name a set declared in x-lt-related`);
+        if (!Array.isArray(section.columns) || section.columns.length === 0)
+            fail(`${at}.columns must list at least one column`);
+        for (const [j, col] of section.columns.entries()) {
+            if (!isObj(col) || !isNonEmptyString(col.label) || typeof col.value !== 'string') {
+                fail(`${at}.columns[${j}] needs a label and a value template`);
+            }
+        }
+        if (section.limit !== undefined && (!Number.isInteger(section.limit) || section.limit < 1
+            || section.limit > types_1.RELATED_LIMITS.ROWS_MAX)) {
+            fail(`${at}.limit must be 1..${types_1.RELATED_LIMITS.ROWS_MAX}`);
+        }
+        return section;
+    });
+}
+function readGroupKey(schema) {
+    const raw = schema[types_1.LIST_SCHEMA_KEYS.GROUP_BY];
+    if (raw === undefined || schema[types_1.LIST_SCHEMA_KEYS.LAYOUT] !== types_1.FACET_TABLE_LAYOUT)
+        return null;
+    const key = typeof raw === 'string' && raw.startsWith(types_1.SPLIT_PATHS.METADATA) ? raw.slice(types_1.SPLIT_PATHS.METADATA.length) : '';
+    if (!exports.METADATA_KEY.test(key))
+        fail('x-lt-group-by on a facet-table must be "metadata.<key>"');
+    return key;
+}
+const FOLDS = new Set(Object.values(types_1.GROUP_FOLDS));
+/**
+ * Validate and normalize the related declaration of a list schema. Throws on
+ * an invalid declaration; keys outside this vocabulary stay opaque.
+ */
+function readListSchemaRelations(schema) {
+    const empty = { sets: {}, columns: [], rowDetail: [], groupKey: null };
+    if (!isObj(schema))
+        return empty;
+    const rawSets = schema[types_1.LIST_SCHEMA_KEYS.RELATED];
+    const sets = {};
+    if (rawSets !== undefined) {
+        if (!isObj(rawSets))
+            fail('x-lt-related must map set names to declarations');
+        const names = Object.keys(rawSets);
+        if (names.length === 0 || names.length > types_1.RELATED_LIMITS.MAX_SETS)
+            fail(`x-lt-related must declare 1..${types_1.RELATED_LIMITS.MAX_SETS} sets`);
+        for (const name of names)
+            sets[name] = readSet(name, rawSets[name]);
+    }
+    const columns = [];
+    const rawColumns = schema[types_1.LIST_SCHEMA_KEYS.COLUMNS];
+    if (Array.isArray(rawColumns)) {
+        rawColumns.forEach((col, i) => {
+            if (!isObj(col))
+                return;
+            if (col.related !== undefined)
+                columns.push(readRelatedColumn(col, sets, `x-lt-columns[${i}]`));
+            if (col.group !== undefined && (typeof col.group !== 'string' || !FOLDS.has(col.group))) {
+                fail(`x-lt-columns[${i}].group must be one of ${[...FOLDS].join(', ')}`);
+            }
+        });
+    }
+    return { sets, columns, rowDetail: readRowDetail(schema[types_1.LIST_SCHEMA_KEYS.ROW_DETAIL], sets), groupKey: readGroupKey(schema) };
+}
+/** The declaration's first error, or null when valid. */
+function listSchemaRelationsError(schema) {
+    try {
+        readListSchemaRelations(schema);
+        return null;
+    }
+    catch (err) {
+        if (err instanceof ListSchemaError)
+            return err.message;
+        throw err;
+    }
+}

package/build/shared/roles/segment.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pace Board sequences: each line of stations a deployment composes with
+ * `parent_role`, over the ops-visible roles. One definition for the board
+ * and for list queries that name a segment.
+ */
+export interface SequenceRole {
+    role: string;
+    parent_role?: string | null;
+    ops_visible?: boolean | null;
+}
+export interface SequenceStation<R extends SequenceRole> {
+    role: R;
+    depth: number;
+}
+export interface RoleSequence<R extends SequenceRole> {
+    origin: R;
+    stations: SequenceStation<R>[];
+}
+/** Breadth-first from each root, longest sequence first. */
+export declare function buildRoleSequences<R extends SequenceRole>(roles: R[]): RoleSequence<R>[];
+/** The ordered roles of the sequence that starts at `origin`, or null. */
+export declare function segmentRoles<R extends SequenceRole>(roles: R[], origin: string): string[] | null;

package/build/shared/roles/segment.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Pace Board sequences: each line of stations a deployment composes with
+ * `parent_role`, over the ops-visible roles. One definition for the board
+ * and for list queries that name a segment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRoleSequences = buildRoleSequences;
+exports.segmentRoles = segmentRoles;
+/** Breadth-first from each root, longest sequence first. */
+function buildRoleSequences(roles) {
+    const opsRoles = roles.filter((r) => r.ops_visible);
+    const roleMap = new Map(opsRoles.map((r) => [r.role, r]));
+    const visited = new Set();
+    // Roots: no parent, or a parent outside the ops set.
+    const roots = opsRoles.filter((r) => !r.parent_role || !roleMap.has(r.parent_role));
+    const sequences = roots.map((root) => {
+        const stations = [];
+        const queue = [{ role: root, depth: 0 }];
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (visited.has(item.role.role))
+                continue;
+            visited.add(item.role.role);
+            stations.push(item);
+            opsRoles
+                .filter((c) => c.parent_role === item.role.role && !visited.has(c.role))
+                .forEach((c) => queue.push({ role: c, depth: item.depth + 1 }));
+        }
+        return { origin: root, stations };
+    });
+    // Unreachable roles (cycles, dangling parents) each stand alone.
+    opsRoles
+        .filter((r) => !visited.has(r.role))
+        .forEach((r) => sequences.push({ origin: r, stations: [{ role: r, depth: 0 }] }));
+    return sequences.sort((a, b) => b.stations.length - a.stations.length || a.origin.role.localeCompare(b.origin.role));
+}
+/** The ordered roles of the sequence that starts at `origin`, or null. */
+function segmentRoles(roles, origin) {
+    const sequence = buildRoleSequences(roles).find((s) => s.origin.role === origin);
+    return sequence ? sequence.stations.map((s) => s.role.role) : null;
+}