@appinternalleads/ui 0.2.0

package/dist/esm/components/directory/contract.d.ts

@@ -0,0 +1,286 @@
+import { FILTER_OPS, RANGE_SEPARATOR, type FilterAuthor, type FilterOp, type QueryFilter } from '../../runtime/query';
+/**
+ * **Directory — the contract.** A data-backed record discovery component: connect a relation,
+ * narrow it, open a record.
+ *
+ * The load-bearing rule, and the reason this file exists at all:
+ *
+ * > **Nothing downstream may name a column the connected source did not report.** The discovered
+ * > schema is the vocabulary — for the builder UI, for the configuration, for a user's rule and
+ * > for an agent's rule alike. A Directory is generated *from* a schema, never tailored to one.
+ *
+ * So there are no column names anywhere in this package. `defaultConfigFor()` derives a starting
+ * configuration from whatever was discovered; `validateRule()`/`validateDirectoryConfig()` reject
+ * anything that names a column the schema doesn't have; `OPERATORS_FOR` answers what a column of
+ * *this inferred type* can actually be asked. See `docs/components/directory/DIRECTORY-BUILDER-CONTRACT.md`.
+ */
+/** Open union — Google Sheets is the first source, not the only intended one. */
+export type DirectorySourceKind = 'googleSheets';
+export type DirectorySource = {
+    kind: DirectorySourceKind;
+    /** What the user pasted, kept verbatim so a saved configuration can be reconnected. */
+    url: string;
+    /** The tab actually read. A spreadsheet may have several; the user picks one. */
+    sheetName: string;
+    /** Google's own id for that tab, when the source reports one. */
+    sheetGid?: string;
+    spreadsheetId?: string;
+    /** Human title of the spreadsheet, when the source reports one. */
+    title?: string;
+};
+/** What a column can be asked, inferred from the values — never declared by hand. */
+export type DirectoryColumnType = 'text' | 'number' | 'date' | 'boolean' | 'enum' | 'multi';
+export type DirectoryColumn = {
+    /** The header exactly as the source reported it. Also the key into a record's `data`. */
+    key: string;
+    /** What to show a person. Defaults to `key`; a source may report something friendlier. */
+    label: string;
+    type: DirectoryColumnType;
+    /** At least one row was blank here. */
+    nullable: boolean;
+    /** No row had a value. Such a column is discovered and shown, but cannot be searched or filtered. */
+    empty: boolean;
+    /** First non-blank value, for the discovery table. */
+    sample?: string;
+    /** For `enum`/`multi`: the values actually present, capped. The rule builder offers exactly these. */
+    distinctValues?: string[];
+    /** Rows counted while inferring — the denominator behind the above. */
+    nonEmptyCount: number;
+};
+export type DirectorySchema = {
+    source: DirectorySource;
+    columns: DirectoryColumn[];
+    /** Data rows, excluding the header row. */
+    rowCount: number;
+};
+export type DirectorySortDirection = 'asc' | 'desc';
+export type DirectoryConfig = {
+    title: string;
+    description?: string;
+    /** The row's identity — its heading. Must be a discovered column. */
+    primaryColumn: string;
+    /** Second line under the title, optional. */
+    secondaryColumn?: string;
+    /** One trailing value on the row, optional — the same "one value only" rule `list` follows. */
+    metaColumn?: string;
+    /** Columns the search box looks in. Must be searchable (see `canSearch`). */
+    searchColumns: string[];
+    /** Columns offered as facets in the Directory's own filter row. */
+    filterColumns: string[];
+    /** Columns offered in the sort control. */
+    sortColumns: string[];
+    /** Columns shown as the row list's columns/lines, in order. */
+    visibleColumns: string[];
+    /** Columns shown when a record is opened. */
+    detailColumns: string[];
+    pageSize: number;
+    selection: 'none' | 'single';
+    sort?: {
+        column: string;
+        dir: DirectorySortDirection;
+    };
+    copy: {
+        emptyLabel: string;
+        noResultsLabel: string;
+    };
+};
+/**
+ * **A rule is a condition and a consequence** — `when` something is true of a record, `then` do
+ * this to it. That is what separates layer C from layer B: the configuration says *what fields
+ * exist and how they are shown*, a rule says *what happens to a record that satisfies a
+ * condition*.
+ *
+ * **One primitive, two authors** — the filter contract carried over from `list` (N1) and stated in
+ * `docs/architecture/FILTER-CONTRACT.md`. A rule a person builds and a rule an agent adds mid-run
+ * are the same object; `author` is provenance, not a type, and both are bounded by the same
+ * schema.
+ */
+export type DirectoryCondition = {
+    column: string;
+    op: FilterOp;
+    /** `''` for the valueless operators; `lo..hi` for `between`. */
+    value: string;
+};
+/**
+ * **Only consequences this Directory can actually carry out.**
+ *
+ * Both of these compile to a query the shared runtime executes, which is the bar: an action the
+ * builder can offer but the runtime would ignore is worse than an action that does not exist.
+ * `include` narrows to the matching records; `exclude` removes them (the runtime's negatable
+ * filter). Consequences that would need something Directory does not have today — marking a
+ * record, notifying someone, writing a value back — are listed as `FUTURE_RULE_ACTIONS` and are
+ * deliberately not offered. See `docs/components/directory/DIRECTORY-BUILDER-CONTRACT.md` §C.
+ */
+export type DirectoryActionKind = 'include' | 'exclude';
+export type DirectoryAction = {
+    kind: DirectoryActionKind;
+};
+export declare const RULE_ACTIONS: {
+    kind: DirectoryActionKind;
+    label: string;
+    summary: string;
+}[];
+/** Named so the gap is explicit rather than implied by absence. None is offered by the builder. */
+export declare const FUTURE_RULE_ACTIONS: readonly ["flag the record", "set a value", "notify someone", "route it somewhere"];
+export type DirectoryRule = {
+    /** Stable across edits, so a list of rules can be reordered and re-keyed without surprises. */
+    id: string;
+    when: DirectoryCondition;
+    then: DirectoryAction;
+    author: FilterAuthor;
+    /** A rule can be switched off without being deleted. Absent means on. */
+    enabled?: boolean;
+};
+/** The pre-WHEN/THEN shape, kept loadable so a configuration saved before this pass still opens. */
+export type LegacyDirectoryRule = {
+    column: string;
+    op: FilterOp;
+    value: string;
+    author: FilterAuthor;
+};
+/** Ids are only needed to be distinct within one document; nothing persists across a reload. */
+export declare const newRuleId: () => string;
+/**
+ * Accepts either shape and returns the current one. This is the single entry point for rules
+ * arriving from outside — a saved document, an agent, a paste into the JSON panel — so no caller
+ * has to know that the flat shape ever existed.
+ */
+export declare function normalizeRule(rule: DirectoryRule | LegacyDirectoryRule): DirectoryRule;
+export declare const normalizeRules: (rules: readonly (DirectoryRule | LegacyDirectoryRule)[]) => DirectoryRule[];
+/** A rule with no consequence configured yet — the builder's "+ Add rule" starting point. */
+export declare function blankRule(column: DirectoryColumn, author?: FilterAuthor): DirectoryRule;
+export declare const isRuleOn: (rule: DirectoryRule) => boolean;
+/**
+ * What a column of each inferred type may be asked. A `date` gets before/after (`lt`/`gt`) and a
+ * range; a number gets the same comparisons in its own domain; an enum gets equality against the
+ * values that are actually present; a multi-value cell gets `includes` (one member matches), which
+ * is a different question from `contains` (a substring of the whole cell).
+ */
+export declare const OPERATORS_BY_TYPE: Record<DirectoryColumnType, FilterOp[]>;
+/** Human wording per operator, so the builder never shows a raw token. */
+export declare const OPERATOR_LABELS: Record<FilterOp, string>;
+export declare function operatorsFor(column: DirectoryColumn): FilterOp[];
+/** A column with no values anywhere can be displayed, but there is nothing to search or filter. */
+export declare const canSearch: (c: DirectoryColumn) => boolean;
+export declare const canFilter: (c: DirectoryColumn) => boolean;
+export declare const canSort: (c: DirectoryColumn) => boolean;
+/** Tunables, named rather than sprinkled as literals. Derived from observed shapes, not one sheet. */
+export declare const INFERENCE: {
+    /** A column is numeric/date if this share of its non-blank values parse that way. */
+    readonly typeConfidence: 0.9;
+    /** Past this many distinct values a column is free text, not a category. */
+    readonly maxEnumValues: 25;
+    /** …and a category's distinct count must also be this fraction of its rows, at most. */
+    readonly maxEnumRatio: 0.2;
+    /** A multi-value cell is delimited; this share of non-blank values must contain a delimiter. */
+    readonly multiDelimiterShare: 0.25;
+    /** Cap on the value list offered in the rule builder. */
+    readonly maxDistinctOffered: 50;
+};
+/**
+ * **Discovery.** Header row + data rows in, schema out. Pure — the transport that produced the rows
+ * is the host's business (a Google Sheets read, a CSV upload, anything). No column is special;
+ * none is assumed to exist.
+ */
+export declare function inferColumns(headers: string[], rows: string[][]): DirectoryColumn[];
+export type RuleRejection = 'unknown-column' | 'unsupported-operator' | 'empty-value' | 'bad-range';
+export type RuleCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: RuleRejection;
+    message: string;
+};
+/**
+ * The same check for a person's rule and an agent's, and it takes either a whole rule or just its
+ * condition — the builder validates a condition as it is edited, before there is a rule to speak
+ * of. The consequence needs no validation: `DirectoryActionKind` has no member the runtime cannot
+ * execute, which is the point of keeping that union closed.
+ */
+export declare function validateRule(rule: {
+    when: DirectoryCondition;
+} | {
+    column: string;
+    op?: FilterOp;
+    value?: string;
+}, schema: DirectorySchema): RuleCheck;
+/** Configuration errors, as messages. `[]` means valid. Every entry names a column the schema lacks. */
+export declare function validateDirectoryConfig(config: DirectoryConfig, schema: DirectorySchema): string[];
+/**
+ * Rules → the runtime's filter shape. The condition maps across unchanged — it *is* the filter
+ * primitive — and the consequence becomes `not`: "show only these" is the filter, "hide these" is
+ * its negation. Provenance travels with it. Switched-off rules are left out here rather than
+ * being deleted, so turning one back on costs nothing.
+ */
+export declare function rulesToFilters(rules: readonly DirectoryRule[]): QueryFilter[];
+/**
+ * A starting configuration for *any* discovered schema: the first usable column leads, the text-ish
+ * columns are searchable, the low-cardinality ones become facets, everything with data is visible.
+ * A builder then edits it. Deterministic, and dependent only on what was discovered.
+ */
+export declare function defaultConfigFor(schema: DirectorySchema): DirectoryConfig;
+/**
+ * **Repair a configuration against a schema, rather than reject it.**
+ *
+ * The case this exists for: a configuration saved months ago, reopened against a sheet whose
+ * columns have moved on. `validateDirectoryConfig` says *what is wrong*, which is what the
+ * builder needs; this says *what can still be honoured*, which is what a runtime needs — drop the
+ * keys the source no longer has, drop the ones that cannot do the job asked of them, de-duplicate,
+ * clamp the page size, and fall back to a generated default only where nothing survives.
+ *
+ * It is deliberately total: `normalizeDirectoryConfig(anything, schema)` always returns a config
+ * that `validateDirectoryConfig` accepts. That is the property the portability test pins, and the
+ * reason a saved document can be trusted to open.
+ */
+export declare function normalizeDirectoryConfig(config: Partial<DirectoryConfig>, schema: DirectorySchema): DirectoryConfig;
+/** Rules that survive the schema. Invalid ones are *returned separately*, never dropped silently. */
+export declare function normalizeDirectoryRules(rules: readonly (DirectoryRule | LegacyDirectoryRule)[] | undefined, schema: DirectorySchema): {
+    rules: DirectoryRule[];
+    rejected: {
+        rule: DirectoryRule;
+        reason: RuleRejection;
+        message: string;
+    }[];
+};
+/**
+ * **What a builder exports and a backend will later store.**
+ *
+ * Three things and no more: where the records come from, how they are shown, and what is always
+ * true of them. There is no React state here, no callback, no adapter, no DOM — the test for
+ * whether something belongs is whether it survives `JSON.stringify` and still means the same
+ * thing on another machine.
+ *
+ * `columns` is a *snapshot* of the schema the configuration was built against, and it is optional
+ * on the way in. It is not the source of truth at read time — the live source is — but keeping it
+ * lets a reader see what the configuration expected, and lets a backend diff the two.
+ */
+export declare const DIRECTORY_DOCUMENT_VERSION: "directory/1";
+export type DirectoryDocument = {
+    schema: typeof DIRECTORY_DOCUMENT_VERSION;
+    source: DirectorySource;
+    config: DirectoryConfig;
+    rules: DirectoryRule[];
+    /** The columns as discovered when this was saved. Informational; the live schema wins. */
+    columns?: {
+        key: string;
+        type: DirectoryColumnType;
+    }[];
+};
+/** Build the artefact. Pure, and everything in it is already JSON. */
+export declare function directoryDocument(schema: DirectorySchema, config: DirectoryConfig, rules: readonly DirectoryRule[]): DirectoryDocument;
+/**
+ * Open an artefact against a live schema. The inverse of `directoryDocument` in the only sense
+ * that matters: the Directory it produces behaves the same, without any knowledge of which source
+ * the document was written against.
+ */
+export declare function loadDirectoryDocument(document: Partial<DirectoryDocument> | null | undefined, schema: DirectorySchema): {
+    config: DirectoryConfig;
+    rules: DirectoryRule[];
+    rejected: {
+        rule: DirectoryRule;
+        reason: RuleRejection;
+        message: string;
+    }[];
+};
+export { RANGE_SEPARATOR, FILTER_OPS, type FilterOp, type FilterAuthor };
+//# sourceMappingURL=contract.d.ts.map

package/dist/esm/components/directory/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../../src/components/directory/contract.ts"],"names":[],"mappings":"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"}

package/dist/esm/components/directory/contract.js

@@ -0,0 +1,367 @@
+import { FILTER_OPS, RANGE_SEPARATOR, VALUELESS_FILTER_OPS, } from '../../runtime/query';
+export const RULE_ACTIONS = [
+    { kind: 'include', label: 'show only these records', summary: 'Everything else is hidden.' },
+    { kind: 'exclude', label: 'hide these records', summary: 'Everything else is shown.' },
+];
+/** Named so the gap is explicit rather than implied by absence. None is offered by the builder. */
+export const FUTURE_RULE_ACTIONS = [
+    'flag the record', 'set a value', 'notify someone', 'route it somewhere',
+];
+let ruleSeq = 0;
+/** Ids are only needed to be distinct within one document; nothing persists across a reload. */
+export const newRuleId = () => `r${++ruleSeq}`;
+/**
+ * Accepts either shape and returns the current one. This is the single entry point for rules
+ * arriving from outside — a saved document, an agent, a paste into the JSON panel — so no caller
+ * has to know that the flat shape ever existed.
+ */
+export function normalizeRule(rule) {
+    if ('when' in rule) {
+        return {
+            id: rule.id || newRuleId(),
+            when: { column: rule.when.column, op: rule.when.op, value: rule.when.value ?? '' },
+            then: { kind: rule.then?.kind === 'exclude' ? 'exclude' : 'include' },
+            author: rule.author === 'agent' ? 'agent' : 'user',
+            ...(rule.enabled === false ? { enabled: false } : {}),
+        };
+    }
+    return {
+        id: newRuleId(),
+        when: { column: rule.column, op: rule.op, value: rule.value ?? '' },
+        then: { kind: 'include' },
+        author: rule.author === 'agent' ? 'agent' : 'user',
+    };
+}
+export const normalizeRules = (rules) => rules.map(normalizeRule);
+/** A rule with no consequence configured yet — the builder's "+ Add rule" starting point. */
+export function blankRule(column, author = 'user') {
+    return {
+        id: newRuleId(),
+        when: { column: column.key, op: operatorsFor(column)[0], value: '' },
+        then: { kind: 'include' },
+        author,
+    };
+}
+export const isRuleOn = (rule) => rule.enabled !== false;
+/** Every operator here is executed by `applyFilter` in the shared runtime — none is UI-only. */
+const TEXTUAL = ['contains', 'eq', 'neq', 'startsWith', 'isEmpty', 'isNotEmpty'];
+const ORDERED = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'between', 'isEmpty', 'isNotEmpty'];
+/**
+ * What a column of each inferred type may be asked. A `date` gets before/after (`lt`/`gt`) and a
+ * range; a number gets the same comparisons in its own domain; an enum gets equality against the
+ * values that are actually present; a multi-value cell gets `includes` (one member matches), which
+ * is a different question from `contains` (a substring of the whole cell).
+ */
+export const OPERATORS_BY_TYPE = {
+    text: TEXTUAL,
+    number: ORDERED,
+    date: ORDERED,
+    boolean: ['eq', 'neq'],
+    enum: ['eq', 'neq', 'isEmpty', 'isNotEmpty'],
+    multi: ['includes', 'contains', 'isEmpty', 'isNotEmpty'],
+};
+/** Human wording per operator, so the builder never shows a raw token. */
+export const OPERATOR_LABELS = {
+    eq: 'is', neq: 'is not', contains: 'contains', startsWith: 'starts with',
+    gt: 'after / greater than', gte: 'on or after / at least',
+    lt: 'before / less than', lte: 'on or before / at most',
+    between: 'between', includes: 'includes',
+    isEmpty: 'is empty', isNotEmpty: 'is not empty',
+};
+export function operatorsFor(column) {
+    return OPERATORS_BY_TYPE[column.type];
+}
+/** A column with no values anywhere can be displayed, but there is nothing to search or filter. */
+export const canSearch = (c) => !c.empty && (c.type === 'text' || c.type === 'enum' || c.type === 'multi');
+export const canFilter = (c) => !c.empty;
+export const canSort = (c) => !c.empty;
+/* ── Inference — the schema comes from the data, always ───────────────────── */
+/** Tunables, named rather than sprinkled as literals. Derived from observed shapes, not one sheet. */
+export const INFERENCE = {
+    /** A column is numeric/date if this share of its non-blank values parse that way. */
+    typeConfidence: 0.9,
+    /** Past this many distinct values a column is free text, not a category. */
+    maxEnumValues: 25,
+    /** …and a category's distinct count must also be this fraction of its rows, at most. */
+    maxEnumRatio: 0.2,
+    /** A multi-value cell is delimited; this share of non-blank values must contain a delimiter. */
+    multiDelimiterShare: 0.25,
+    /** Cap on the value list offered in the rule builder. */
+    maxDistinctOffered: 50,
+};
+const DELIMITER = /[,;|]/;
+const BOOLEANS = new Set(['true', 'false', 'yes', 'no', 'y', 'n', '1', '0', 'checked', 'unchecked']);
+/** A bare number is not a date, and `Date.parse` accepts far too much — require date-ish shape. */
+const DATE_SHAPE = /^\s*(\d{1,4}[/-]\d{1,2}[/-]\d{1,4}|\d{4}-\d{2}-\d{2})/;
+function inferType(values) {
+    if (values.length === 0)
+        return { type: 'text' };
+    const n = values.length;
+    const share = (p) => values.filter(p).length / n;
+    if (share(v => v !== '' && !Number.isNaN(Number(v))) >= INFERENCE.typeConfidence)
+        return { type: 'number' };
+    if (share(v => DATE_SHAPE.test(v) && !Number.isNaN(Date.parse(v))) >= INFERENCE.typeConfidence)
+        return { type: 'date' };
+    const distinctSet = new Set(values.map(v => v.toLowerCase()));
+    if (distinctSet.size <= 2 && [...distinctSet].every(v => BOOLEANS.has(v)))
+        return { type: 'boolean' };
+    /* Multi-value before enum: "Paperback, Ebook" has high raw cardinality but few members. */
+    if (share(v => DELIMITER.test(v)) >= INFERENCE.multiDelimiterShare) {
+        const members = new Set();
+        for (const v of values)
+            for (const part of v.split(DELIMITER)) {
+                const p = part.trim();
+                if (p)
+                    members.add(p);
+            }
+        if (members.size <= INFERENCE.maxEnumValues) {
+            return { type: 'multi', distinct: [...members].sort().slice(0, INFERENCE.maxDistinctOffered) };
+        }
+    }
+    const distinct = [...new Set(values)];
+    if (distinct.length <= INFERENCE.maxEnumValues && distinct.length / n <= INFERENCE.maxEnumRatio) {
+        return { type: 'enum', distinct: distinct.sort().slice(0, INFERENCE.maxDistinctOffered) };
+    }
+    return { type: 'text' };
+}
+/**
+ * **Discovery.** Header row + data rows in, schema out. Pure — the transport that produced the rows
+ * is the host's business (a Google Sheets read, a CSV upload, anything). No column is special;
+ * none is assumed to exist.
+ */
+export function inferColumns(headers, rows) {
+    return headers.map((header, i) => {
+        const key = header.trim() || `Column ${i + 1}`;
+        const raw = rows.map(r => (r[i] ?? '').trim());
+        const values = raw.filter(v => v !== '');
+        const { type, distinct } = inferType(values);
+        return {
+            key, label: key, type,
+            nullable: values.length < raw.length,
+            empty: values.length === 0,
+            sample: values[0],
+            distinctValues: distinct,
+            nonEmptyCount: values.length,
+        };
+    });
+}
+/**
+ * The same check for a person's rule and an agent's, and it takes either a whole rule or just its
+ * condition — the builder validates a condition as it is edited, before there is a rule to speak
+ * of. The consequence needs no validation: `DirectoryActionKind` has no member the runtime cannot
+ * execute, which is the point of keeping that union closed.
+ */
+export function validateRule(rule, schema) {
+    const condition = 'when' in rule ? rule.when : rule;
+    const column = schema.columns.find(c => c.key === condition.column);
+    if (!column || !canFilter(column)) {
+        return { ok: false, reason: 'unknown-column', message: `"${condition.column}" is not a column of this source` };
+    }
+    const op = condition.op ?? 'eq';
+    if (!operatorsFor(column).includes(op)) {
+        return { ok: false, reason: 'unsupported-operator', message: `${OPERATOR_LABELS[op] ?? op} does not apply to a ${column.type} column` };
+    }
+    const value = condition.value ?? '';
+    if (value === '' && !VALUELESS_FILTER_OPS.includes(op)) {
+        return { ok: false, reason: 'empty-value', message: 'This rule needs a value' };
+    }
+    if (op === 'between') {
+        const [lo, hi] = value.split(RANGE_SEPARATOR);
+        if (!lo || !hi)
+            return { ok: false, reason: 'bad-range', message: 'A range needs both a start and an end' };
+    }
+    return { ok: true };
+}
+/** Configuration errors, as messages. `[]` means valid. Every entry names a column the schema lacks. */
+export function validateDirectoryConfig(config, schema) {
+    const errors = [];
+    const byKey = new Map(schema.columns.map(c => [c.key, c]));
+    const check = (keys, field, allowed) => {
+        for (const k of keys) {
+            const c = byKey.get(k);
+            if (!c) {
+                errors.push(`${field}: "${k}" is not a column of this source`);
+                continue;
+            }
+            if (allowed && !allowed(c))
+                errors.push(`${field}: "${k}" is a ${c.empty ? 'column with no values' : `${c.type} column`} and cannot be used here`);
+        }
+    };
+    check([config.primaryColumn], 'Primary column');
+    if (config.secondaryColumn)
+        check([config.secondaryColumn], 'Secondary column');
+    if (config.metaColumn)
+        check([config.metaColumn], 'Meta column');
+    check(config.searchColumns, 'Search', canSearch);
+    check(config.filterColumns, 'Filters', canFilter);
+    check(config.sortColumns, 'Sort', canSort);
+    check(config.visibleColumns, 'Visible columns');
+    check(config.detailColumns, 'Detail');
+    if (config.sort)
+        check([config.sort.column], 'Sort', canSort);
+    if (config.pageSize < 1)
+        errors.push('Page size must be at least 1');
+    return errors;
+}
+/**
+ * Rules → the runtime's filter shape. The condition maps across unchanged — it *is* the filter
+ * primitive — and the consequence becomes `not`: "show only these" is the filter, "hide these" is
+ * its negation. Provenance travels with it. Switched-off rules are left out here rather than
+ * being deleted, so turning one back on costs nothing.
+ */
+export function rulesToFilters(rules) {
+    return rules.filter(isRuleOn).map(r => ({
+        column: r.when.column, op: r.when.op, value: r.when.value, author: r.author,
+        ...(r.then.kind === 'exclude' ? { not: true } : {}),
+    }));
+}
+/* ── Defaults — generated from the schema, never from a known sheet ───────── */
+/**
+ * A starting configuration for *any* discovered schema: the first usable column leads, the text-ish
+ * columns are searchable, the low-cardinality ones become facets, everything with data is visible.
+ * A builder then edits it. Deterministic, and dependent only on what was discovered.
+ */
+export function defaultConfigFor(schema) {
+    const withData = schema.columns.filter(c => !c.empty);
+    const primary = (withData.find(c => c.type === 'text') ?? withData[0] ?? schema.columns[0]);
+    const categorical = withData.filter(c => c.type === 'enum' || c.type === 'multi' || c.type === 'boolean');
+    const searchable = withData.filter(canSearch);
+    const noun = 'records';
+    return {
+        title: schema.source.title ?? schema.source.sheetName,
+        primaryColumn: primary.key,
+        secondaryColumn: withData.find(c => c.type === 'text' && c.key !== primary.key)?.key,
+        metaColumn: withData.find(c => c.type === 'date')?.key,
+        searchColumns: searchable.slice(0, 3).map(c => c.key),
+        filterColumns: categorical.slice(0, 3).map(c => c.key),
+        sortColumns: withData.filter(canSort).slice(0, 6).map(c => c.key),
+        visibleColumns: withData.slice(0, 5).map(c => c.key),
+        detailColumns: schema.columns.filter(c => !c.empty).map(c => c.key),
+        pageSize: 20,
+        selection: 'single',
+        sort: withData.some(c => c.type === 'date')
+            ? { column: withData.find(c => c.type === 'date').key, dir: 'desc' }
+            : undefined,
+        copy: {
+            emptyLabel: `No ${noun} yet`,
+            noResultsLabel: `No ${noun} match these rules`,
+        },
+    };
+}
+/* ── Normalisation — a configuration meeting a schema it was not built against ── */
+/**
+ * **Repair a configuration against a schema, rather than reject it.**
+ *
+ * The case this exists for: a configuration saved months ago, reopened against a sheet whose
+ * columns have moved on. `validateDirectoryConfig` says *what is wrong*, which is what the
+ * builder needs; this says *what can still be honoured*, which is what a runtime needs — drop the
+ * keys the source no longer has, drop the ones that cannot do the job asked of them, de-duplicate,
+ * clamp the page size, and fall back to a generated default only where nothing survives.
+ *
+ * It is deliberately total: `normalizeDirectoryConfig(anything, schema)` always returns a config
+ * that `validateDirectoryConfig` accepts. That is the property the portability test pins, and the
+ * reason a saved document can be trusted to open.
+ */
+export function normalizeDirectoryConfig(config, schema) {
+    const fallback = defaultConfigFor(schema);
+    const byKey = new Map(schema.columns.map(c => [c.key, c]));
+    const keep = (keys, allowed) => {
+        if (!Array.isArray(keys))
+            return [];
+        const seen = new Set();
+        return keys.filter((k) => {
+            if (typeof k !== 'string' || seen.has(k))
+                return false;
+            const c = byKey.get(k);
+            if (!c || (allowed && !allowed(c)))
+                return false;
+            seen.add(k);
+            return true;
+        });
+    };
+    const one = (key, allowed) => {
+        if (typeof key !== 'string')
+            return undefined;
+        const c = byKey.get(key);
+        return c && (!allowed || allowed(c)) ? key : undefined;
+    };
+    const search = keep(config.searchColumns, canSearch);
+    const filters = keep(config.filterColumns, canFilter);
+    const sorts = keep(config.sortColumns, canSort);
+    const visible = keep(config.visibleColumns);
+    const detail = keep(config.detailColumns);
+    /* A sort naming a column that is no longer sortable falls back to the default rather than to
+       "unsorted": a configuration that asked for an order still wants one. */
+    const sortColumn = one(config.sort?.column, canSort);
+    return {
+        title: typeof config.title === 'string' && config.title.trim() ? config.title : fallback.title,
+        ...(typeof config.description === 'string' && config.description ? { description: config.description } : {}),
+        primaryColumn: one(config.primaryColumn) ?? fallback.primaryColumn,
+        ...(one(config.secondaryColumn) ? { secondaryColumn: one(config.secondaryColumn) } : {}),
+        ...(one(config.metaColumn) ? { metaColumn: one(config.metaColumn) } : {}),
+        searchColumns: search,
+        filterColumns: filters,
+        sortColumns: sorts,
+        visibleColumns: visible.length ? visible : fallback.visibleColumns,
+        detailColumns: detail.length ? detail : fallback.detailColumns,
+        pageSize: Number.isFinite(config.pageSize) ? Math.min(100, Math.max(1, Math.round(config.pageSize))) : fallback.pageSize,
+        selection: config.selection === 'none' ? 'none' : 'single',
+        ...(sortColumn
+            ? { sort: { column: sortColumn, dir: config.sort?.dir === 'asc' ? 'asc' : 'desc' } }
+            : fallback.sort ? { sort: fallback.sort } : {}),
+        copy: {
+            emptyLabel: config.copy?.emptyLabel || fallback.copy.emptyLabel,
+            noResultsLabel: config.copy?.noResultsLabel || fallback.copy.noResultsLabel,
+        },
+    };
+}
+/** Rules that survive the schema. Invalid ones are *returned separately*, never dropped silently. */
+export function normalizeDirectoryRules(rules, schema) {
+    const kept = [];
+    const rejected = [];
+    for (const raw of rules ?? []) {
+        const r = normalizeRule(raw);
+        const check = validateRule(r, schema);
+        if (check.ok)
+            kept.push(r);
+        else
+            rejected.push({ rule: r, reason: check.reason, message: check.message });
+    }
+    return { rules: kept, rejected };
+}
+/* ── The portable artefact ───────────────────────────────────────────────── */
+/**
+ * **What a builder exports and a backend will later store.**
+ *
+ * Three things and no more: where the records come from, how they are shown, and what is always
+ * true of them. There is no React state here, no callback, no adapter, no DOM — the test for
+ * whether something belongs is whether it survives `JSON.stringify` and still means the same
+ * thing on another machine.
+ *
+ * `columns` is a *snapshot* of the schema the configuration was built against, and it is optional
+ * on the way in. It is not the source of truth at read time — the live source is — but keeping it
+ * lets a reader see what the configuration expected, and lets a backend diff the two.
+ */
+export const DIRECTORY_DOCUMENT_VERSION = 'directory/1';
+/** Build the artefact. Pure, and everything in it is already JSON. */
+export function directoryDocument(schema, config, rules) {
+    return {
+        schema: DIRECTORY_DOCUMENT_VERSION,
+        source: schema.source,
+        config,
+        rules: rules.map(normalizeRule),
+        columns: schema.columns.map(c => ({ key: c.key, type: c.type })),
+    };
+}
+/**
+ * Open an artefact against a live schema. The inverse of `directoryDocument` in the only sense
+ * that matters: the Directory it produces behaves the same, without any knowledge of which source
+ * the document was written against.
+ */
+export function loadDirectoryDocument(document, schema) {
+    const config = normalizeDirectoryConfig(document?.config ?? {}, schema);
+    const { rules, rejected } = normalizeDirectoryRules(document?.rules, schema);
+    return { config, rules, rejected };
+}
+export { RANGE_SEPARATOR, FILTER_OPS };
+//# sourceMappingURL=contract.js.map