@texuli/spec 0.7.0 → 0.8.0

package/dist/generated/typescript/manifest.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/manifest.schema.json. Do not edit: run the spec generator.
-// Spec 0.7.0, digest 43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2
+// Spec 0.8.0, digest f6b6388280d247eb9c3106a925111f35b90d1ec3b59c23652542f06a9f103daf
 export {};

package/dist/generated/typescript/vocabulary.d.ts

@@ -1,7 +1,7 @@
 /** The built catalog this vocabulary was projected from. */
-export declare const SPEC_CATALOG_HASH = "c6bd7047eba3e1f32e9ed74097c390a58416cf4260267c8958e0ea70821abf35";
+export declare const SPEC_CATALOG_HASH = "598075e391ed95dcba46e120d2fbb706e8ff67d0d5bdeb3c0741f334f439b264";
 /** Every closed component id, sorted. */
-export declare const SPEC_COMPONENT_IDS: readonly ["action-form", "alert", "alert-dialog", "analytics-grid", "app-nav", "badge", "banner", "blocks-code", "blocks-data", "blocks-diagram", "blocks-embed", "blocks-interactive", "blocks-map", "blocks-media", "blocks-structure", "blocks-text", "breadcrumb", "button", "button-group", "callout", "card", "charts-area", "charts-bar", "charts-bubble", "charts-bullet", "charts-canvas-renderer", "charts-cartesian", "charts-combo", "charts-donut", "charts-funnel", "charts-gauge", "charts-geo-map", "charts-geo-point-map", "charts-heatmap", "charts-line", "charts-network", "charts-pie", "charts-progress-ring", "charts-sankey", "charts-scatter", "charts-sparkline", "charts-stacked-bar", "charts-sunburst", "charts-treemap", "chat-message", "chat-thread", "checkbox", "chip", "code", "combobox", "command-palette", "content-layout", "context-menu", "context-menu-trigger", "control-choice", "control-filter", "control-slider", "control-toggle", "data-board", "data-calendar", "data-cohort-table", "data-files", "data-filter-builder", "data-grid", "data-map", "data-notification-inbox", "data-timeline", "data-tree-view", "deck-slide", "description", "detail-panel", "dialog", "document", "drawer", "dropdown-menu", "dropdown-menu-content", "dropdown-menu-item", "dropdown-menu-trigger", "empty-state", "error-state", "field", "field-error", "flow-action", "flow-view", "form", "form-field", "form-submit", "host-region", "hover-card", "hover-card-content", "icon-button", "inline-text", "input", "input-group", "kbd", "kpi", "label", "layout-auth-split", "layout-blog", "layout-card", "layout-chrome", "layout-dashboard-grid", "layout-deck", "layout-doc", "layout-docs", "layout-drawer", "layout-dual-sidebar", "layout-editorial", "layout-grid", "layout-host", "layout-landing", "layout-marketing", "layout-page", "layout-pricing", "layout-row", "layout-settings", "layout-sidebar", "layout-split", "layout-stack", "layout-tile", "layout-top-nav", "layout-wizard", "media-composition-canvas", "media-composition-svg", "media-image", "menubar", "menubar-trigger", "multi-select", "nav-icon", "navigation-menu", "pagination", "popover", "popover-content", "radio", "radio-group", "responsive-modal", "screen-outlet", "select", "select-content", "select-group", "select-item", "select-label", "select-portal", "select-separator", "select-trigger", "select-value", "select-viewport", "sheet", "sidebar", "sortable-list", "split-view", "stat", "stepper", "switch", "table", "tag", "text-counter", "textarea", "time-field", "timeline", "toaster", "tooltip", "workflow-graph"];
+export declare const SPEC_COMPONENT_IDS: readonly ["action-form", "alert", "alert-dialog", "analytics-grid", "app-nav", "badge", "banner", "blocks-code", "blocks-data", "blocks-diagram", "blocks-embed", "blocks-interactive", "blocks-map", "blocks-media", "blocks-structure", "blocks-text", "breadcrumb", "button", "button-group", "callout", "canvas", "card", "charts-area", "charts-bar", "charts-bubble", "charts-bullet", "charts-canvas-renderer", "charts-cartesian", "charts-combo", "charts-donut", "charts-funnel", "charts-gauge", "charts-geo-map", "charts-geo-point-map", "charts-heatmap", "charts-line", "charts-network", "charts-pie", "charts-progress-ring", "charts-sankey", "charts-scatter", "charts-sparkline", "charts-stacked-bar", "charts-sunburst", "charts-treemap", "chat-message", "chat-thread", "checkbox", "chip", "code", "combobox", "command-palette", "content-layout", "context-menu", "context-menu-trigger", "control-choice", "control-filter", "control-slider", "control-toggle", "data-board", "data-calendar", "data-cohort-table", "data-dashboard", "data-dashboard-widget", "data-files", "data-filter-builder", "data-grid", "data-map", "data-notification-inbox", "data-timeline", "data-tree-view", "deck-slide", "description", "detail-panel", "dialog", "document", "drawer", "dropdown-menu", "dropdown-menu-content", "dropdown-menu-item", "dropdown-menu-trigger", "empty-state", "error-state", "field", "field-error", "flow-action", "flow-view", "form", "form-field", "form-submit", "host-region", "hover-card", "hover-card-content", "icon-button", "inline-text", "input", "input-group", "kbd", "kpi", "label", "layout-auth-split", "layout-blog", "layout-card", "layout-chrome", "layout-dashboard-grid", "layout-deck", "layout-doc", "layout-docs", "layout-drawer", "layout-dual-sidebar", "layout-editorial", "layout-grid", "layout-host", "layout-landing", "layout-marketing", "layout-page", "layout-pricing", "layout-row", "layout-settings", "layout-sidebar", "layout-split", "layout-stack", "layout-tile", "layout-top-nav", "layout-wizard", "media-composition-canvas", "media-composition-svg", "media-image", "menubar", "menubar-trigger", "multi-select", "nav-icon", "navigation-menu", "pagination", "popover", "popover-content", "radio", "radio-group", "responsive-modal", "schema-form", "screen-outlet", "select", "select-content", "select-group", "select-item", "select-label", "select-portal", "select-separator", "select-trigger", "select-value", "select-viewport", "sheet", "sidebar", "sortable-list", "split-view", "spreadsheet", "stat", "stepper", "switch", "table", "tag", "text-counter", "textarea", "time-field", "timeline", "toaster", "tooltip", "workflow-graph"];
 export type SpecComponentId = (typeof SPEC_COMPONENT_IDS)[number];
 /** The props a blueprint may set on each component (platform extensions left out). */
 export interface SpecComponentProps {
@@ -139,6 +139,10 @@ export interface SpecComponentProps {
         title?: string;
         tone?: 'info' | 'success' | 'warning' | 'error' | 'brand' | 'neutral';
     };
+    canvas: {
+        canvas: Readonly<Record<string, unknown>>;
+        label?: string;
+    };
     card: {
         href?: string;
         hrefTrust?: 'developer' | 'untrusted';
@@ -493,6 +497,20 @@ export interface SpecComponentProps {
         rows: readonly unknown[];
         valueKind?: 'rate' | 'count';
     };
+    'data-dashboard': {
+        columns?: number;
+        compaction?: 'vertical' | 'none';
+        density?: 'compact' | 'default' | 'comfortable';
+        editable?: boolean;
+        gap?: 'none' | 'small' | 'medium' | 'large';
+        label: string;
+        layout?: readonly unknown[];
+    };
+    'data-dashboard-widget': {
+        place?: Readonly<Record<string, unknown>>;
+        title: string;
+        widgetId: string;
+    };
     'data-files': {
         density?: 'comfortable' | 'compact';
         entries: readonly unknown[];
@@ -985,6 +1003,11 @@ export interface SpecComponentProps {
         side?: 'top' | 'right' | 'bottom' | 'left' | 'start' | 'end' | 'center';
         size?: 'sm' | 'md' | 'lg' | 'xl';
     };
+    'schema-form': {
+        action: string;
+        label?: string;
+        schema: Readonly<Record<string, unknown>>;
+    };
     'screen-outlet': Record<string, never>;
     select: {
         defaultValue?: string;
@@ -1052,6 +1075,10 @@ export interface SpecComponentProps {
         detailLabel?: string;
         listLabel?: string;
     };
+    spreadsheet: {
+        label?: string;
+        sheet: Readonly<Record<string, unknown>>;
+    };
     stat: {
         delta?: string;
         hint?: string;

package/dist/generated/typescript/vocabulary.js

@@ -1,7 +1,7 @@
 // Generated by @texuli/spec from catalog/components.json. Do not edit: run the spec generator.
-// Spec 0.7.0, digest 43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2
+// Spec 0.8.0, digest f6b6388280d247eb9c3106a925111f35b90d1ec3b59c23652542f06a9f103daf
 /** The built catalog this vocabulary was projected from. */
-export const SPEC_CATALOG_HASH = 'c6bd7047eba3e1f32e9ed74097c390a58416cf4260267c8958e0ea70821abf35';
+export const SPEC_CATALOG_HASH = '598075e391ed95dcba46e120d2fbb706e8ff67d0d5bdeb3c0741f334f439b264';
 /** Every closed component id, sorted. */
 export const SPEC_COMPONENT_IDS = [
     'action-form',
@@ -24,6 +24,7 @@ export const SPEC_COMPONENT_IDS = [
     'button',
     'button-group',
     'callout',
+    'canvas',
     'card',
     'charts-area',
     'charts-bar',
@@ -65,6 +66,8 @@ export const SPEC_COMPONENT_IDS = [
     'data-board',
     'data-calendar',
     'data-cohort-table',
+    'data-dashboard',
+    'data-dashboard-widget',
     'data-files',
     'data-filter-builder',
     'data-grid',
@@ -140,6 +143,7 @@ export const SPEC_COMPONENT_IDS = [
     'radio',
     'radio-group',
     'responsive-modal',
+    'schema-form',
     'screen-outlet',
     'select',
     'select-content',
@@ -155,6 +159,7 @@ export const SPEC_COMPONENT_IDS = [
     'sidebar',
     'sortable-list',
     'split-view',
+    'spreadsheet',
     'stat',
     'stepper',
     'switch',

package/dist/generated/typescript/workflow.js

@@ -1,3 +1,3 @@
 // Generated by @texuli/spec from schemas/workflow.schema.json. Do not edit: run the spec generator.
-// Spec 0.7.0, digest 43e44fa9a198d337d686b4e2d86882a06a676ae1e1c1f02d023b3a525795a8b2
+// Spec 0.8.0, digest f6b6388280d247eb9c3106a925111f35b90d1ec3b59c23652542f06a9f103daf
 export {};

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { CAPABILITIES, type Capability, type SpecPropKind, WEB_ONLY_KINDS, WEB_O
 export { ACTION_FIELDS, contractRoot, DATA_BINDING_KEY, SPEC_ACTION_OPS, SPEC_EVENT_NAMES, SPEC_LIMITS, SPEC_PATTERNS, SPEC_PROP_REFS, SPEC_STATE_TYPES, type SpecActionOp, type SpecStateType, STATE_BINDING_KEY, STATE_FIELDS, toDialectSchema, } from './contract.js';
 export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, type DialectHooks, type DialectType, type Schema, type SchemaIssue, validateInstance, } from './dialect.js';
 export type { SpecMigration, SpecMigrationResult } from './migrations/types.js';
+export { checkSourceBinding, isSourceBinding, isSpecSourceDate, SOURCE_BINDING_FIELDS, SOURCE_BINDING_KEY, type SourceBindingContext, type SourceBindingIssue, SPEC_SOURCE_FIELD_TYPES, SPEC_SOURCE_FILTER_OPERATORS, SPEC_SOURCE_LIMITS, SPEC_SOURCE_OPERATIONS, SPEC_SOURCE_PATTERNS, type SpecSourceDescriptor, type SpecSourceField, type SpecSourceFieldType, type SpecSourceFilterOperator, type SpecSourceOperation, } from './source.js';
 export { checkStateSurface, LIST_TEXT_PATTERN, SPEC_CONTROL_STATE_TYPES, SURFACE_PLAYER_CODES, type SurfaceCode, type SurfaceInputs, type SurfaceIssue, surfaceInputs, } from './surface.js';
 export { type SpecDocuments, type SpecFlowInfo, type SpecStateVariable, type TreeOptions, validateBlueprint, validateTree, type WorkflowGraphValidator, } from './validate.js';
 export { SPEC_VERSION } from './version.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export { canonicalJson, sha256 } from "./canonical.js";
 export { CAPABILITIES, WEB_ONLY_KINDS, WEB_ONLY_PROP_NAMES, } from "./catalog.js";
 export { ACTION_FIELDS, contractRoot, DATA_BINDING_KEY, SPEC_ACTION_OPS, SPEC_EVENT_NAMES, SPEC_LIMITS, SPEC_PATTERNS, SPEC_PROP_REFS, SPEC_STATE_TYPES, STATE_BINDING_KEY, STATE_FIELDS, toDialectSchema, } from "./contract.js";
 export { checkSchemaDocument, DIALECT_KEYWORDS, DIALECT_TYPES, DIALECT_URI, validateInstance, } from "./dialect.js";
+export { checkSourceBinding, isSourceBinding, isSpecSourceDate, SOURCE_BINDING_FIELDS, SOURCE_BINDING_KEY, SPEC_SOURCE_FIELD_TYPES, SPEC_SOURCE_FILTER_OPERATORS, SPEC_SOURCE_LIMITS, SPEC_SOURCE_OPERATIONS, SPEC_SOURCE_PATTERNS, } from "./source.js";
 export { checkStateSurface, LIST_TEXT_PATTERN, SPEC_CONTROL_STATE_TYPES, SURFACE_PLAYER_CODES, surfaceInputs, } from "./surface.js";
 export { validateBlueprint, validateTree, } from "./validate.js";
 export { SPEC_VERSION } from "./version.js";

package/dist/migrations/0.7.0-0.8.0.d.ts

@@ -0,0 +1,8 @@
+import type { SpecMigration } from './types.js';
+/**
+ * 0.7.0 → 0.8.0 is additive (PLAN_010 wave 4–6, ADR-012 and ADR-015): it
+ * adds vocabulary (data-source bindings and the other 0.8.0 additions) and
+ * removes nothing. Every 0.7.0 envelope is a valid 0.8.0 envelope, so the
+ * step only stamps `spec`.
+ */
+export declare const migration070to080: SpecMigration;

package/dist/migrations/0.7.0-0.8.0.js

@@ -0,0 +1,11 @@
+/**
+ * 0.7.0 → 0.8.0 is additive (PLAN_010 wave 4–6, ADR-012 and ADR-015): it
+ * adds vocabulary (data-source bindings and the other 0.8.0 additions) and
+ * removes nothing. Every 0.7.0 envelope is a valid 0.8.0 envelope, so the
+ * step only stamps `spec`.
+ */
+export const migration070to080 = Object.freeze({
+    from: '0.7.0',
+    to: '0.8.0',
+    migrate: (envelope) => ({ ...envelope, spec: '0.8.0' }),
+});

package/dist/migrations/index.js

@@ -5,6 +5,7 @@ import { migration030to040 } from "./0.3.0-0.4.0.js";
 import { migration040to050 } from "./0.4.0-0.5.0.js";
 import { migration050to060 } from "./0.5.0-0.6.0.js";
 import { migration060to070 } from "./0.6.0-0.7.0.js";
+import { migration070to080 } from "./0.7.0-0.8.0.js";
 /** The version an envelope without `spec` was written for. */
 export const UNDECLARED_SPEC_VERSION = '0.2.0';
 /** Every step, in order; each `to` is the next step's `from`. */
@@ -14,6 +15,7 @@ export const SPEC_MIGRATIONS = Object.freeze([
     migration040to050,
     migration050to060,
     migration060to070,
+    migration070to080,
 ]);
 /**
  * Bring a blueprint envelope up to `target` (the current spec by default)

package/dist/source.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Data-source bindings (spec 0.8.0, ADR-012 and ADR-015): a sourceable prop
+ * reads rows from a source the host registered,
+ * `{"$source": name, "query": {...}, "map": {...}}`. The schema
+ * (`$defs.sourceBinding`) fixes the closed shape; this module checks a
+ * binding against the host's source descriptors: the name, every field,
+ * operator and value of the query, the page size and the map. It mirrors
+ * `checkSourceQuery` in `@texuli/core/data-source` (the spec cannot import
+ * core: both are L0), and a parity test keeps the two in agreement.
+ * With no descriptors a binding is refused: the spec fails closed.
+ */
+/** The binding key that reads a host data source: `{ "$source": name, … }`. */
+export declare const SOURCE_BINDING_KEY = "$source";
+/** The members a binding takes besides `$source`. */
+export declare const SOURCE_BINDING_FIELDS: readonly ["query", "map"];
+export declare const SPEC_SOURCE_FIELD_TYPES: readonly ["text", "enum", "number", "date", "boolean"];
+export type SpecSourceFieldType = (typeof SPEC_SOURCE_FIELD_TYPES)[number];
+export declare const SPEC_SOURCE_OPERATIONS: readonly ["list", "get", "create", "update", "delete", "search"];
+export type SpecSourceOperation = (typeof SPEC_SOURCE_OPERATIONS)[number];
+/** The `@texuli/data` grid filter model's operators (`$defs.sourceFilter.operator`). */
+export declare const SPEC_SOURCE_FILTER_OPERATORS: readonly ["eq", "neq", "contains", "in", "between", "before", "after", "isEmpty", "isNotEmpty"];
+export type SpecSourceFilterOperator = (typeof SPEC_SOURCE_FILTER_OPERATORS)[number];
+/** Every bound of a binding; the schema writes the static ones too (`tests/source.test.ts`). */
+export declare const SPEC_SOURCE_LIMITS: Readonly<{
+    nameLength: 64;
+    projection: 32;
+    sort: 4;
+    searchLength: 200;
+    filterDepth: 6;
+    filterNodes: 64;
+    filterValues: 100;
+    valueLength: 500;
+    pageSize: 500;
+    mapEntries: 16;
+}>;
+export declare const SPEC_SOURCE_PATTERNS: Readonly<{
+    sourceName: "^[a-z][a-z0-9]*([._-][a-z0-9]+)*$";
+    sourceFieldName: "^[A-Za-z][A-Za-z0-9_]*$";
+}>;
+/** One declared field, as `@texuli/core/data-source` describes it. */
+export interface SpecSourceField {
+    readonly name: string;
+    readonly type: SpecSourceFieldType;
+    readonly options?: readonly string[];
+    readonly filter: readonly SpecSourceFilterOperator[];
+    readonly sort: boolean;
+    readonly editable?: boolean;
+    readonly required?: boolean;
+}
+/**
+ * A host source as plain data: structurally the `SourceDescriptor` of
+ * `@texuli/core/data-source` (`registry.describe()` can be passed as is).
+ */
+export interface SpecSourceDescriptor {
+    readonly name: string;
+    readonly key: string;
+    readonly fields: readonly SpecSourceField[];
+    readonly operations: readonly SpecSourceOperation[];
+    readonly pagination?: 'cursor' | 'offset' | 'none';
+    readonly maxPageSize: number;
+    readonly defaultPageSize?: number;
+}
+/** One semantic problem with a binding; `at` is relative to the binding (`.query.filter`). */
+export interface SourceBindingIssue {
+    readonly code: 'source' | 'unknown-source';
+    readonly at: string;
+    readonly message: string;
+}
+/** What a binding is checked against. */
+export interface SourceBindingContext {
+    /** The host's sources. Omitted: every binding is refused (fail closed). */
+    readonly sources?: readonly SpecSourceDescriptor[];
+    /**
+     * The item fields the bound prop's rows may carry (its item schema's
+     * properties), when known: `map` keys must be among them.
+     */
+    readonly itemFields?: readonly string[];
+}
+/** Whether a value is shaped like a source binding (`$source` as an own key). */
+export declare function isSourceBinding(value: unknown): value is Record<string, unknown>;
+/** Whether `value` is an ISO 8601 date or date-time, or epoch milliseconds. */
+export declare function isSpecSourceDate(value: unknown): boolean;
+/**
+ * Check a binding: its closed shape, then its meaning against the host's
+ * sources (fail closed without them): the name, every field, operator and
+ * value of the query, the page size and the map. One issue per problem, up
+ * to 16. `@texuli/spec`'s validator runs the schema (`$defs.sourceBinding`)
+ * first; `@texuli/catalog` runs this alone.
+ */
+export declare function checkSourceBinding(binding: Record<string, unknown>, context: SourceBindingContext): SourceBindingIssue[];

package/dist/source.js

@@ -0,0 +1,366 @@
+/**
+ * Data-source bindings (spec 0.8.0, ADR-012 and ADR-015): a sourceable prop
+ * reads rows from a source the host registered,
+ * `{"$source": name, "query": {...}, "map": {...}}`. The schema
+ * (`$defs.sourceBinding`) fixes the closed shape; this module checks a
+ * binding against the host's source descriptors: the name, every field,
+ * operator and value of the query, the page size and the map. It mirrors
+ * `checkSourceQuery` in `@texuli/core/data-source` (the spec cannot import
+ * core: both are L0), and a parity test keeps the two in agreement.
+ * With no descriptors a binding is refused: the spec fails closed.
+ */
+import { isRecord } from "./dialect.js";
+/** The binding key that reads a host data source: `{ "$source": name, … }`. */
+export const SOURCE_BINDING_KEY = '$source';
+/** The members a binding takes besides `$source`. */
+export const SOURCE_BINDING_FIELDS = ['query', 'map'];
+export const SPEC_SOURCE_FIELD_TYPES = ['text', 'enum', 'number', 'date', 'boolean'];
+export const SPEC_SOURCE_OPERATIONS = [
+    'list',
+    'get',
+    'create',
+    'update',
+    'delete',
+    'search',
+];
+/** The `@texuli/data` grid filter model's operators (`$defs.sourceFilter.operator`). */
+export const SPEC_SOURCE_FILTER_OPERATORS = [
+    'eq',
+    'neq',
+    'contains',
+    'in',
+    'between',
+    'before',
+    'after',
+    'isEmpty',
+    'isNotEmpty',
+];
+/** Every bound of a binding; the schema writes the static ones too (`tests/source.test.ts`). */
+export const SPEC_SOURCE_LIMITS = Object.freeze({
+    nameLength: 64,
+    projection: 32,
+    sort: 4,
+    searchLength: 200,
+    filterDepth: 6,
+    filterNodes: 64,
+    filterValues: 100,
+    valueLength: 500,
+    pageSize: 500,
+    mapEntries: 16,
+});
+export const SPEC_SOURCE_PATTERNS = Object.freeze({
+    sourceName: '^[a-z][a-z0-9]*([._-][a-z0-9]+)*$',
+    sourceFieldName: '^[A-Za-z][A-Za-z0-9_]*$',
+});
+const FIELD_RE = new RegExp(SPEC_SOURCE_PATTERNS.sourceFieldName, 'u');
+const DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+/** Whether a value is shaped like a source binding (`$source` as an own key). */
+export function isSourceBinding(value) {
+    return isRecord(value) && Object.hasOwn(value, SOURCE_BINDING_KEY);
+}
+/** Whether `value` is an ISO 8601 date or date-time, or epoch milliseconds. */
+export function isSpecSourceDate(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    return (typeof value === 'string' &&
+        value.length <= 35 &&
+        DATE_RE.test(value) &&
+        !Number.isNaN(Date.parse(value)));
+}
+function fits(field, value) {
+    if (value === null)
+        return true;
+    switch (field.type) {
+        case 'text':
+            return typeof value === 'string' && value.length <= SPEC_SOURCE_LIMITS.valueLength;
+        case 'enum':
+            return typeof value === 'string' && (field.options ?? []).includes(value);
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'date':
+            return isSpecSourceDate(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        default:
+            return false;
+    }
+}
+/** The descriptor's field by name, without touching the prototype chain. */
+function fieldOf(source, name) {
+    if (typeof name !== 'string')
+        return undefined;
+    return source.fields.find((field) => field.name === name);
+}
+/** Over the filter's depth or node caps, measured without recursion. */
+function filterOverLimits(input) {
+    const stack = [{ node: input, depth: 1 }];
+    let nodes = 0;
+    while (stack.length > 0) {
+        const { node, depth } = stack.pop();
+        nodes += 1;
+        if (depth > SPEC_SOURCE_LIMITS.filterDepth || nodes > SPEC_SOURCE_LIMITS.filterNodes) {
+            return true;
+        }
+        const children = isRecord(node) ? node.children : undefined;
+        if (!Array.isArray(children))
+            continue;
+        if (nodes + stack.length + children.length > SPEC_SOURCE_LIMITS.filterNodes)
+            return true;
+        for (const child of children)
+            stack.push({ node: child, depth: depth + 1 });
+    }
+    return false;
+}
+const NAME_RE = new RegExp(SPEC_SOURCE_PATTERNS.sourceName, 'u');
+const QUERY_KEYS = ['fields', 'filter', 'sort', 'search', 'pageSize'];
+function isFieldName(value) {
+    return typeof value === 'string' && value.length <= 64 && FIELD_RE.test(value);
+}
+/**
+ * The closed shape of `$defs.sourceBinding`, checked without the schema
+ * document (so `@texuli/catalog` can run it alone): the members, their
+ * types and the static limits. The filter's own members are judged with
+ * its meaning, below.
+ */
+function shapeProblem(binding) {
+    const extra = Object.keys(binding).find((key) => key !== SOURCE_BINDING_KEY && key !== 'query' && key !== 'map');
+    if (extra !== undefined)
+        return { at: `.${extra}`, message: `A data-source binding takes no "${extra}".` };
+    const name = binding[SOURCE_BINDING_KEY];
+    if (typeof name !== 'string' ||
+        name.length > SPEC_SOURCE_LIMITS.nameLength ||
+        !NAME_RE.test(name)) {
+        return {
+            at: `.${SOURCE_BINDING_KEY}`,
+            message: 'A source is named by a source name, never a URL.',
+        };
+    }
+    if (Object.hasOwn(binding, 'map')) {
+        const map = binding.map;
+        if (!isRecord(map) || Object.values(map).some((value) => !isFieldName(value))) {
+            return { at: '.map', message: 'map pairs item fields with source field names.' };
+        }
+    }
+    if (!Object.hasOwn(binding, 'query'))
+        return null;
+    const query = binding.query;
+    if (!isRecord(query))
+        return { at: '.query', message: 'A query is an object.' };
+    const unknown = Object.keys(query).find((key) => !QUERY_KEYS.includes(key));
+    if (unknown !== undefined)
+        return { at: `.query.${unknown}`, message: `A query takes no "${unknown}".` };
+    const { fields, sort, search, pageSize } = query;
+    if (fields !== undefined &&
+        (!Array.isArray(fields) ||
+            fields.length === 0 ||
+            fields.length > SPEC_SOURCE_LIMITS.projection ||
+            !fields.every(isFieldName))) {
+        return {
+            at: '.query.fields',
+            message: `fields lists 1 to ${SPEC_SOURCE_LIMITS.projection} field names.`,
+        };
+    }
+    if (sort !== undefined) {
+        const keyOk = (entry) => isRecord(entry) &&
+            Object.keys(entry).every((key) => key === 'field' || key === 'direction') &&
+            isFieldName(entry.field) &&
+            (entry.direction === undefined || entry.direction === 'asc' || entry.direction === 'desc');
+        if (!Array.isArray(sort) ||
+            sort.length === 0 ||
+            sort.length > SPEC_SOURCE_LIMITS.sort ||
+            !sort.every(keyOk)) {
+            return { at: '.query.sort', message: `sort lists 1 to ${SPEC_SOURCE_LIMITS.sort} keys.` };
+        }
+    }
+    if (search !== undefined &&
+        (typeof search !== 'string' || search.length > SPEC_SOURCE_LIMITS.searchLength)) {
+        return {
+            at: '.query.search',
+            message: `search is text of at most ${SPEC_SOURCE_LIMITS.searchLength} characters.`,
+        };
+    }
+    if (pageSize !== undefined &&
+        (typeof pageSize !== 'number' ||
+            !Number.isInteger(pageSize) ||
+            pageSize < 1 ||
+            pageSize > SPEC_SOURCE_LIMITS.pageSize)) {
+        return {
+            at: '.query.pageSize',
+            message: `pageSize is an integer from 1 to ${SPEC_SOURCE_LIMITS.pageSize}.`,
+        };
+    }
+    return null;
+}
+/**
+ * Check a binding: its closed shape, then its meaning against the host's
+ * sources (fail closed without them): the name, every field, operator and
+ * value of the query, the page size and the map. One issue per problem, up
+ * to 16. `@texuli/spec`'s validator runs the schema (`$defs.sourceBinding`)
+ * first; `@texuli/catalog` runs this alone.
+ */
+export function checkSourceBinding(binding, context) {
+    const issues = [];
+    const fail = (at, message, code = 'source') => {
+        if (issues.length < 16)
+            issues.push({ code, at, message });
+    };
+    const shape = shapeProblem(binding);
+    if (shape) {
+        fail(shape.at, shape.message);
+        return issues;
+    }
+    const name = binding[SOURCE_BINDING_KEY];
+    if (!context.sources) {
+        fail(`.${SOURCE_BINDING_KEY}`, 'No data sources were supplied, so a data-source binding is refused.');
+        return issues;
+    }
+    const source = typeof name === 'string' ? context.sources.find((entry) => entry.name === name) : undefined;
+    if (!source) {
+        fail(`.${SOURCE_BINDING_KEY}`, `The host registered no source "${String(name)}".`, 'unknown-source');
+        return issues;
+    }
+    const lists = source.operations.includes('list') || source.operations.includes('search');
+    if (!lists)
+        fail(`.${SOURCE_BINDING_KEY}`, `"${source.name}" cannot list rows.`);
+    const query = isRecord(binding.query) ? binding.query : {};
+    const known = (value, at) => {
+        const field = fieldOf(source, value);
+        if (!field)
+            fail(at, `"${source.name}" has no "${String(value)}" field.`);
+        return field;
+    };
+    if (Array.isArray(query.fields)) {
+        query.fields.forEach((entry, index) => {
+            known(entry, `.query.fields[${index}]`);
+        });
+    }
+    if (Array.isArray(query.sort)) {
+        const seen = new Set();
+        query.sort.forEach((entry, index) => {
+            if (!isRecord(entry))
+                return;
+            const field = known(entry.field, `.query.sort[${index}].field`);
+            if (!field)
+                return;
+            if (!field.sort)
+                fail(`.query.sort[${index}].field`, `"${field.name}" is not sortable.`);
+            else if (seen.has(field.name))
+                fail(`.query.sort[${index}].field`, `"${field.name}" is sorted twice.`);
+            seen.add(field.name);
+        });
+    }
+    if (typeof query.search === 'string' && !source.operations.includes('search')) {
+        fail('.query.search', `"${source.name}" does not search.`);
+    }
+    if (typeof query.pageSize === 'number' && query.pageSize > source.maxPageSize) {
+        fail('.query.pageSize', `"${source.name}" pages at most ${source.maxPageSize} rows.`);
+    }
+    if (Object.hasOwn(query, 'filter')) {
+        if (filterOverLimits(query.filter)) {
+            fail('.query.filter', `A filter has at most ${SPEC_SOURCE_LIMITS.filterDepth} levels and ${SPEC_SOURCE_LIMITS.filterNodes} nodes.`);
+        }
+        else {
+            checkFilter(query.filter, '.query.filter', source, fail, known);
+        }
+    }
+    if (isRecord(binding.map)) {
+        const entries = Object.entries(binding.map);
+        if (entries.length > SPEC_SOURCE_LIMITS.mapEntries) {
+            fail('.map', `A map has at most ${SPEC_SOURCE_LIMITS.mapEntries} entries.`);
+        }
+        for (const [target, from] of entries) {
+            if (!FIELD_RE.test(target) || target.length > 64) {
+                fail(`.map.${target}`, `"${target}" is not an item field name.`);
+            }
+            else if (context.itemFields && !context.itemFields.includes(target)) {
+                fail(`.map.${target}`, `The rows of this prop have no "${target}" field.`);
+            }
+            known(from, `.map.${target}`);
+        }
+    }
+    return issues;
+}
+/** Recursion is safe here: the depth was capped at 6 first. */
+function checkFilter(node, at, source, fail, known) {
+    if (!isRecord(node)) {
+        fail(at, 'A filter node is an object.');
+        return;
+    }
+    const has = (key) => Object.hasOwn(node, key);
+    const unknown = Object.keys(node).find((key) => !['type', 'field', 'operator', 'value', 'op', 'children'].includes(key));
+    if (unknown !== undefined) {
+        fail(`${at}.${unknown}`, `A filter node takes no "${unknown}".`);
+        return;
+    }
+    if (node.type !== 'group' && node.type !== 'condition') {
+        fail(`${at}.type`, 'A filter node is a "condition" or a "group".');
+        return;
+    }
+    if (node.type === 'group') {
+        const extra = ['field', 'operator', 'value'].find(has);
+        if (extra) {
+            fail(`${at}.${extra}`, `A group takes no "${extra}".`);
+            return;
+        }
+        if (node.op !== 'and' && node.op !== 'or') {
+            fail(`${at}.op`, 'A group is "and" or "or".');
+            return;
+        }
+        if (!Array.isArray(node.children) || node.children.length === 0) {
+            fail(`${at}.children`, 'A group needs at least one child.');
+            return;
+        }
+        node.children.forEach((child, index) => {
+            checkFilter(child, `${at}.children[${index}]`, source, fail, known);
+        });
+        return;
+    }
+    const extra = ['op', 'children'].find(has);
+    if (extra) {
+        fail(`${at}.${extra}`, `A condition takes no "${extra}".`);
+        return;
+    }
+    const field = known(node.field, `${at}.field`);
+    const operator = node.operator;
+    if (!SPEC_SOURCE_FILTER_OPERATORS.includes(operator)) {
+        fail(`${at}.operator`, 'A condition needs a filter operator.');
+        return;
+    }
+    if (!field)
+        return;
+    const op = operator;
+    if (!field.filter.includes(op)) {
+        fail(`${at}.operator`, `"${field.name}" cannot be filtered by "${op}".`);
+        return;
+    }
+    const value = node.value;
+    const here = `${at}.value`;
+    const scalars = (list) => list.every((item) => fits(field, item));
+    if (op === 'isEmpty' || op === 'isNotEmpty') {
+        if (has('value'))
+            fail(here, `${op} takes no value.`);
+    }
+    else if (op === 'in') {
+        if (!Array.isArray(value) ||
+            value.length === 0 ||
+            value.length > SPEC_SOURCE_LIMITS.filterValues ||
+            !scalars(value)) {
+            fail(here, `in needs 1 to ${SPEC_SOURCE_LIMITS.filterValues} values of "${field.name}".`);
+        }
+    }
+    else if (op === 'between') {
+        if (!Array.isArray(value) || value.length !== 2 || value.includes(null) || !scalars(value)) {
+            fail(here, `between needs [low, high] values of "${field.name}".`);
+        }
+    }
+    else if (op === 'contains' &&
+        (typeof value !== 'string' || value === '' || !fits(field, value))) {
+        fail(here, 'contains needs text.');
+    }
+    else if ((op === 'before' || op === 'after') && !isSpecSourceDate(value)) {
+        fail(here, `${op} needs a date.`);
+    }
+    else if (!has('value') || Array.isArray(value) || !fits(field, value)) {
+        fail(here, `${op} needs one value of "${field.name}" (${field.type}).`);
+    }
+}