ngx-t-forms-types 0.0.30 → 0.0.34

package/dist/skillet/members/mat-options.d.ts

@@ -0,0 +1,187 @@
+import { s } from '@hashbrownai/core';
+import { DataSources } from '../../interfaces/formInput/APIDataFetchingConfigurationInterface.js';
+import type { FormInputBasicOptionInterface } from '../../interfaces/formInput/FormInputBasicOptionInterface.js';
+/**
+ * The `matOptions` member: where a control's value and its options come from.
+ *
+ * ## Why this is a factory, and why it produces a draft
+ *
+ * `APIDataFetchingConfigurationInterface` requires `_id`, `name`,
+ * `httpEndPoint`, `httpMethod`, `postFormData` and `backEndConfig`. A model
+ * asked for that will happily produce `httpEndPoint:
+ * 'https://api.example.com/departments'` and a plausible `_id`, and the result
+ * is a form that looks correct and is entirely broken — it points at an
+ * endpoint that does not exist. Of everything in these schemas, that is the
+ * failure most likely to reach production unnoticed, because nothing about the
+ * output looks wrong.
+ *
+ * The form builder never asks a human to do this either. The editor row for
+ * this property is `apiEndpointConfig`, backed by `postmanCollectionConfig` and
+ * `httpGetDataFunction` — the author PICKS an endpoint from a collection
+ * supplied at runtime. So the model picks too: {@link createMatOptionsSchema}
+ * takes the endpoints and workflows available in the caller's context and emits
+ * an enumeration over their ids. A source that has no candidates is not offered
+ * at all, which is why the branches are conditional rather than always present.
+ *
+ * The consequence is that this schema produces a {@link MatOptionsDraft}, not a
+ * `MatDataOptionsInterface`: an api draft carries the id of an endpoint, and
+ * the application expands it into the stored configuration before the form is
+ * validated. That expansion is the caller's job and there is no way around it —
+ * the full configuration is simply not knowable from a prompt.
+ *
+ * ## Deliberate narrowing
+ *
+ * `options` is declared as `Array<FormInputBasicOptionInterface |
+ * DynamicObjectInterface>`. The second branch is an index signature, which
+ * Skillet cannot express and a model has no basis for inventing, so only the
+ * `{ label, value }` shape is offered.
+ *
+ * A `mongoPipeline` source carries `pipeline: any[]` — a raw aggregation
+ * pipeline. Selecting the workflow is offered; authoring the pipeline is not.
+ */
+/** An endpoint the caller has available for the model to choose between. */
+export interface AvailableApiEndpoint {
+    /** The persisted `_id` of the endpoint configuration. */
+    id: string;
+    /** Human name, shown to the model so it can choose on meaning, not on id. */
+    name: string;
+    /** What the endpoint returns, if known. Sharpens the choice considerably. */
+    description?: string;
+}
+/** A workflow whose data pipeline the caller has available. */
+export interface AvailableWorkflow {
+    id: string;
+    name: string;
+}
+export interface MatOptionsSchemaOptions {
+    /**
+     * Endpoints the model may select for an `api` source. Omit, or pass an empty
+     * list, and the `api` branch is not offered — which is the safe default,
+     * because the alternative is a hallucinated URL.
+     */
+    apiEndpoints?: readonly AvailableApiEndpoint[];
+    /** Workflows the model may select for a `mongoPipeline` source. */
+    workflows?: readonly AvailableWorkflow[];
+}
+export interface LocalSourceDraft {
+    source: DataSources.Local;
+    inputSourceId: string;
+    allowManualValueEntry: boolean;
+}
+export interface CustomOptionsSourceDraft {
+    source: DataSources.CustomOptions;
+}
+export interface ApiSourceDraft {
+    source: DataSources.Api;
+    endpointId: string;
+    allowManualValueEntry: boolean;
+}
+export interface MongoSourceDraft {
+    source: DataSources.MongoDb;
+    workflowId: string;
+}
+export type ValueSourceDraft = LocalSourceDraft | CustomOptionsSourceDraft | ApiSourceDraft | MongoSourceDraft;
+export interface MatOptionsDraft {
+    optionType: 'user' | null;
+    options: FormInputBasicOptionInterface[];
+    fetch: {
+        value: ValueSourceDraft | null;
+        options: ValueSourceDraft | null;
+    };
+}
+/**
+ * Builds the `matOptions` schema for the sources available to the caller.
+ *
+ * @param options endpoints and workflows the model may choose between. Both
+ *   default to empty, which offers only the sources a model can author outright
+ *   and cannot get factually wrong.
+ */
+export declare function createMatOptionsSchema(options?: MatOptionsSchemaOptions): s.ObjectType<{
+    optionType: import("@hashbrownai/core/src/schema/base").SchemaForUnion<"user" | null>;
+    options: s.ArrayType<s.ObjectType<{
+        label: s.StringType;
+        value: s.StringType;
+    }>>;
+    fetch: s.ObjectType<{
+        value: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+            source: DataSources.Local;
+            inputSourceId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.CustomOptions;
+        } | {
+            source: DataSources.Api;
+            endpointId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.MongoDb;
+            workflowId: string;
+        } | null>;
+        options: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+            source: DataSources.Local;
+            inputSourceId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.CustomOptions;
+        } | {
+            source: DataSources.Api;
+            endpointId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.MongoDb;
+            workflowId: string;
+        } | null>;
+    }>;
+}>;
+/**
+ * The default `matOptions` schema: no external endpoints or workflows, so it
+ * offers only the sources a model can author correctly from a prompt alone.
+ *
+ * Callers holding a real endpoint collection should build their own with
+ * {@link createMatOptionsSchema} rather than reaching for this one.
+ */
+export declare const matOptionsSchema: s.ObjectType<{
+    optionType: import("@hashbrownai/core/src/schema/base").SchemaForUnion<"user" | null>;
+    options: s.ArrayType<s.ObjectType<{
+        label: s.StringType;
+        value: s.StringType;
+    }>>;
+    fetch: s.ObjectType<{
+        value: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+            source: DataSources.Local;
+            inputSourceId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.CustomOptions;
+        } | {
+            source: DataSources.Api;
+            endpointId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.MongoDb;
+            workflowId: string;
+        } | null>;
+        options: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+            source: DataSources.Local;
+            inputSourceId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.CustomOptions;
+        } | {
+            source: DataSources.Api;
+            endpointId: string;
+            allowManualValueEntry: boolean;
+        } | {
+            source: DataSources.MongoDb;
+            workflowId: string;
+        } | null>;
+    }>;
+}>;
+/**
+ * Members of a generated `matOptions` the application must expand.
+ *
+ * `endpointId` and `workflowId` are draft-only keys that do not exist on
+ * `MatDataOptionsInterface` at all — Joi rejects unknown keys, so a draft that
+ * reaches the validator unexpanded fails outright rather than degrading.
+ */
+export declare const MAT_OPTIONS_DRAFT_COMPLETION: readonly ["matOptions.fetch.value|options.endpointId (expanded to the stored APIDataFetchingConfiguration)", "matOptions.fetch.value|options.workflowId (expanded to the stored pipeline configuration)", "matOptions.fetch.value|options.inputSourceId (resolved from formControlName to an input id)"];

package/dist/skillet/members/mat-options.js

@@ -0,0 +1,92 @@
+import { s } from '@hashbrownai/core';
+import { DataSources } from '../../interfaces/formInput/APIDataFetchingConfigurationInterface.js';
+import { describe } from '../internal/editor-guidance.js';
+// --- schema -----------------------------------------------------------------
+const optionSchema = s.object('A selectable option.', {
+    label: s.string('The text shown to the user. It may change freely.'),
+    value: s.string("The value stored when this option is chosen: a single word with no spaces ('urgent', 'capex'), kept stable once the form is live. A decision gate compares the stored value, not the label, and splits its expression on spaces."),
+});
+/** Renders the endpoint list into prose so the model chooses on meaning. */
+function describeCandidates(lead, candidates) {
+    const lines = candidates.map((c) => c.description ? `${c.id} (${c.name}: ${c.description})` : `${c.id} (${c.name})`);
+    return `${lead} Choose by meaning, not by position: ${lines.join('; ')}.`;
+}
+function sourceBranches(slot, options) {
+    const localLead = slot === 'value'
+        ? 'Takes its value from another field on this form.'
+        : 'Takes its options from another field on this form.';
+    const endpoints = options.apiEndpoints ?? [];
+    const workflows = options.workflows ?? [];
+    // Built by conditional spread rather than by pushing onto an array: a `push`
+    // would have to widen every branch to the shape of the first two, which
+    // erases the per-branch typing that `s.Infer` needs to reconstruct the union.
+    return [
+        s.object(describe(localLead, 'matOptions', 'fetch', slot, 'source'), {
+            source: s.literal(DataSources.Local),
+            inputSourceId: s.string('The formControlName of the field on this form to read from. It must be a field that actually exists in the form being authored.'),
+            allowManualValueEntry: s.boolean('Only meaningful on the value slot of a field whose dataType is object or array (an mSCOA, a multiple-input table). An inherited value of that shape can arrive partly filled in — only some mSCOA segments, rows missing a column — and this decides whether the user may finish it. True leaves the field editable: whenever the inherited value changes, only what actually changed is applied over it and whatever the user added is kept. False locks the field. Choose false unless the field is object- or array-shaped AND the source field is expected to supply only part of it. It has no effect on a scalar field or on an options slot, where the inherited value always wins.'),
+        }),
+        s.object('Uses a fixed list of options authored into the form itself.', {
+            source: s.literal(DataSources.CustomOptions),
+        }),
+        ...(endpoints.length
+            ? [
+                s.object('Fetches from a configured API endpoint.', {
+                    source: s.literal(DataSources.Api),
+                    endpointId: s.enumeration(describeCandidates('Which configured endpoint to call.', endpoints), endpoints.map((e) => e.id)),
+                    allowManualValueEntry: s.boolean('Whether the user may supply what the endpoint does not. On a scalar field: true lets a value they type stand whenever the endpoint contributes nothing (no response, an empty one, a failed request), and a non-empty response always wins over what they typed. On a field whose dataType is object or array (an mSCOA, a multiple-input table): true leaves the field editable so they can finish a response that arrives incomplete — rows missing a column, only some mSCOA segments — and each new response is applied over the live value as a delta, so what the endpoint sends updates and what the user added is kept. False locks the field, which is the right choice whenever the endpoint answers completely.'),
+                }),
+            ]
+            : []),
+        ...(workflows.length
+            ? [
+                s.object('Fetches through a workflow data pipeline.', {
+                    source: s.literal(DataSources.MongoDb),
+                    workflowId: s.enumeration(describeCandidates('Which workflow supplies the data.', workflows), workflows.map((w) => w.id)),
+                }),
+            ]
+            : []),
+    ];
+}
+/**
+ * Builds the `matOptions` schema for the sources available to the caller.
+ *
+ * @param options endpoints and workflows the model may choose between. Both
+ *   default to empty, which offers only the sources a model can author outright
+ *   and cannot get factually wrong.
+ */
+export function createMatOptionsSchema(options = {}) {
+    const valueSource = s.anyOf(sourceBranches('value', options));
+    const optionsSource = s.anyOf(sourceBranches('options', options));
+    return s.object('Where this control gets its value and the options it offers. Only set this on a control that actually reads from somewhere; a plain text input does not.', {
+        optionType: s.anyOf([
+            s.literal('user'),
+            s.nullish(),
+        ]),
+        options: s.array(describe('The fixed options offered by this control, for a short list fixed by policy. Fill this in only when the options source is a custom list; leave it empty otherwise. Never retype a list a system already owns — departments, suppliers, users, cost centres — as custom options; it goes stale.', 'matOptions', 'options'), optionSchema),
+        fetch: s.object('Where the value and the options are read from.', {
+            value: s.anyOf([valueSource, s.nullish()]),
+            options: s.anyOf([optionsSource, s.nullish()]),
+        }),
+    });
+}
+/**
+ * The default `matOptions` schema: no external endpoints or workflows, so it
+ * offers only the sources a model can author correctly from a prompt alone.
+ *
+ * Callers holding a real endpoint collection should build their own with
+ * {@link createMatOptionsSchema} rather than reaching for this one.
+ */
+export const matOptionsSchema = createMatOptionsSchema();
+/**
+ * Members of a generated `matOptions` the application must expand.
+ *
+ * `endpointId` and `workflowId` are draft-only keys that do not exist on
+ * `MatDataOptionsInterface` at all — Joi rejects unknown keys, so a draft that
+ * reaches the validator unexpanded fails outright rather than degrading.
+ */
+export const MAT_OPTIONS_DRAFT_COMPLETION = [
+    'matOptions.fetch.value|options.endpointId (expanded to the stored APIDataFetchingConfiguration)',
+    'matOptions.fetch.value|options.workflowId (expanded to the stored pipeline configuration)',
+    'matOptions.fetch.value|options.inputSourceId (resolved from formControlName to an input id)',
+];

package/dist/skillet/members/mscoa.d.ts

@@ -0,0 +1,182 @@
+import { s } from '@hashbrownai/core';
+import type { AccountingBasis, DualCashExclusionMatchMode } from '../../interfaces/formInput/IMscoaAccount.js';
+import { AssertNever } from '../internal/coupling.js';
+/**
+ * The `mscoaConfig` member: how a municipal SCOA account picker is set up.
+ *
+ * One `mscoaSelection` element asks a user to pick accounts out of the chart of
+ * accounts, segment by segment. This object says which segments it asks for,
+ * how each account is labelled back to them, which accounting basis is being
+ * captured, and — for a dual basis — when the cash side is not actually
+ * required.
+ *
+ * ## Why this produces a draft
+ *
+ * `IScoaInputConfig` requires `inputs: ScoaInnerInput[]`, and a
+ * `ScoaInnerInput` is a whole `FormColumnInputs` carrying its own `id` plus a
+ * `linkedSegmentId` pointing at a segment row that does not exist until the
+ * segments themselves have been assigned ids. Asking a model for that is asking
+ * it to invent two sets of identifiers and then cross-reference them, which it
+ * will do, plausibly and wrongly. So `inputs` is not offered here at all; the
+ * application supplies `inputs: []` when it completes the draft, and the
+ * builder's own "additional inputs" editor is where those are authored.
+ *
+ * The same reasoning retires `id` from segments and from exclusion rules. Both
+ * are row keys stamped by the builder's record editors (`uuidv4()` at the point
+ * of save), never typed by a human — which is exactly why `id` and `sectionId`
+ * sit in `SYSTEM_OWNED_INPUT_MEMBERS` one level up. A model-authored id is at
+ * best noise and at worst a collision with a row that already exists.
+ *
+ * ## Draft-completion obligations
+ *
+ * Before this output can be handed to `validateMscoaInputConfig`, the caller
+ * must:
+ *
+ * 1. add `inputs: []` — required by `MscoaInputConfigSchema` and deliberately
+ *    absent here;
+ * 2. stamp an `id` on every entry of `segments`, `cashSegments` and
+ *    `dualCashExclusion.rules`;
+ * 3. strip the nulls standing in for absent optional members — Joi rejects a
+ *    `null` where it declared an optional string.
+ *
+ * None of the three is optional, and none of them is knowable from a prompt.
+ *
+ * ## Deliberate narrowing
+ *
+ * `IScoaInputConfig` also declares `label` and `hint`. `MscoaInputConfigSchema`
+ * does not, and a Joi object rejects unknown keys by default — so emitting
+ * either would fail the very validation this schema exists to pass. The visible
+ * label of the control is the input's own `label` member, one level up. Joi
+ * wins, and they are omitted.
+ *
+ * `accountValueLabel` is narrowed from `string` to the pool the settings panel
+ * offers, derived from {@link MSCOA_ACCOUNT_VALUE_LABEL_OPTIONS} at evaluation
+ * rather than retyped — the same treatment the enum-backed nodes get, for the
+ * same reason: a hand-copied list is a list that drifts.
+ *
+ * `segment` is asked for on every segment row, although the interface types it
+ * `string | undefined`. The builder's segment form declares it
+ * `Validators.required`, so a row without one cannot be saved by hand either.
+ * Narrower than the interface is the permitted direction; wider is not.
+ */
+export interface MscoaSegmentDraft {
+    segment: string;
+    customSegment: string | null;
+    label: string;
+    readOnly: boolean;
+    singleSelect: boolean;
+    additionalAccounts: string[];
+    inheritValueFromAccrual: boolean | null;
+    vatSelectonActive: boolean | null;
+    segmentExtension: boolean;
+}
+export interface MscoaDualCashExclusionRuleDraft {
+    pattern: string;
+    flags: string | null;
+    matchField: string | null;
+    segment: string | null;
+    description: string | null;
+}
+export interface MscoaDualCashExclusionDraft {
+    rules: MscoaDualCashExclusionRuleDraft[] | null;
+    matchMode: DualCashExclusionMatchMode | null;
+}
+export interface MscoaConfigDraft {
+    segments: MscoaSegmentDraft[];
+    cashSegments: MscoaSegmentDraft[] | null;
+    accountValueLabel: string;
+    accountingBasis: AccountingBasis | null;
+    extensionAccountsForSegments: string[];
+    showAllSegments: boolean;
+    dualCashExclusion: MscoaDualCashExclusionDraft | null;
+}
+/**
+ * `DualCashExclusionMatchMode` is a string-union type with no runtime object to
+ * read, so its members are restated under {@link exhaustive} rather than
+ * derived — drop one and this stops compiling.
+ */
+export declare const DUAL_CASH_MATCH_MODE_VALUES: readonly ["any", "all"];
+/**
+ * The `mscoaConfig` schema.
+ *
+ * A plain const, not a factory: nothing in here is chosen from candidates the
+ * caller holds. The one member that draws on a fixed pool — `accountValueLabel`
+ * — reads that pool out of this package at evaluation.
+ *
+ * ## Where the editor guidance is attached, and where it is not
+ *
+ * There is exactly ONE editor row for this whole object, at path
+ * `['mscoaConfig']`: a composite `MscoaConfig` editor that replaced eight
+ * separate rows (accountingBasis, accountValueLabel, showAllSegments, segments,
+ * cashSegments, the two dual-cash members and extensionAccountsForSegments).
+ * So {@link describe} is called once, on the object the row actually edits, and
+ * the members below carry authored descriptions only.
+ *
+ * That is a deliberate choice rather than an oversight. Calling
+ * `describe(base, 'mscoaConfig')` on each member compiles and would append the
+ * same forty-word hint — ending in "Opens a guided setup", which is advice for
+ * someone looking at a settings panel — to all seven of them. Layering it once,
+ * on the composite, says the same thing in one place.
+ */
+export declare const mscoaConfigSchema: s.ObjectType<{
+    accountingBasis: import("@hashbrownai/core/src/schema/base").SchemaForUnion<AccountingBasis | null>;
+    segments: s.ArrayType<s.ObjectType<{
+        segment: s.StringType;
+        customSegment: import("@hashbrownai/core/src/schema/base").SchemaForUnion<string | null>;
+        label: s.StringType;
+        readOnly: s.BooleanType;
+        singleSelect: s.BooleanType;
+        additionalAccounts: s.ArrayType<s.StringType>;
+        inheritValueFromAccrual: import("@hashbrownai/core/src/schema/base").SchemaForUnion<boolean | null>;
+        vatSelectonActive: import("@hashbrownai/core/src/schema/base").SchemaForUnion<boolean | null>;
+        segmentExtension: s.BooleanType;
+    }>>;
+    cashSegments: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+        segment: string;
+        customSegment: string | null;
+        label: string;
+        readOnly: boolean;
+        singleSelect: boolean;
+        additionalAccounts: string[];
+        inheritValueFromAccrual: boolean | null;
+        vatSelectonActive: boolean | null;
+        segmentExtension: boolean;
+    }[] | null>;
+    accountValueLabel: s.EnumType<string[]>;
+    showAllSegments: s.BooleanType;
+    extensionAccountsForSegments: s.ArrayType<s.StringType>;
+    dualCashExclusion: import("@hashbrownai/core/src/schema/base").SchemaForUnion<{
+        rules: {
+            pattern: string;
+            flags: string | null;
+            matchField: string | null;
+            segment: string | null;
+            description: string | null;
+        }[] | null;
+        matchMode: "any" | "all" | null;
+    } | null>;
+}>;
+/**
+ * The schema produces the draft it declares.
+ *
+ * Same shape of check as `_NoDraftDrift` in `input-members.ts`, and there for
+ * the same reason: the expansion from draft to `IScoaInputConfig` belongs to
+ * the caller, but the draft itself stays pinned to the node that generates it.
+ * Loosen a member below and this fails here rather than three layers away.
+ */
+export type _NoMscoaDraftDrift = AssertNever<[
+    s.Infer<typeof mscoaConfigSchema>
+] extends [MscoaConfigDraft] ? never : 'mscoaConfig'>;
+/**
+ * Members of a generated `mscoaConfig` the application must supply before Joi
+ * will accept it.
+ *
+ * `inputs` is the notable one: `MscoaInputConfigSchema` REQUIRES it, and the
+ * model is never asked for it, so a draft that is not expanded fails
+ * validation rather than merely losing a detail. An empty array satisfies it —
+ * the segments' inner inputs are generated from the segments themselves.
+ *
+ * `dualCashExclusion.rules[].id` is deliberately absent from this list: Joi
+ * marks that one optional, so leaving it unset is valid.
+ */
+export declare const MSCOA_DRAFT_COMPLETION: readonly ["mscoaConfig.inputs (application supplies; an empty array is valid)", "mscoaConfig.segments[].id", "mscoaConfig.cashSegments[].id"];

package/dist/skillet/members/mscoa.js

@@ -0,0 +1,129 @@
+import { s } from '@hashbrownai/core';
+import { MSCOA_ACCOUNT_VALUE_LABEL_OPTIONS } from '../../interfaces/FormBuilder/inputConfig/ElementEditConfig.js';
+import { exhaustive, optional } from '../internal/coupling.js';
+import { describe, describeIn } from '../internal/editor-guidance.js';
+import { accountingBasisSchema } from '../shared-types.js';
+// --- the account-label pool -------------------------------------------------
+/**
+ * The fields an account may be displayed by, read off the option pool the
+ * unified MSCOA setup editor renders for `accountValueLabel`.
+ */
+const ACCOUNT_VALUE_LABEL_ENTRIES = MSCOA_ACCOUNT_VALUE_LABEL_OPTIONS.map((option) => option.value);
+/** Compares a label to its value ignoring case, spacing and punctuation. */
+const flatten = (text) => text.replace(/[^a-z0-9]/gi, '').toLowerCase();
+/**
+ * The handful of entries whose label says something their value does not.
+ *
+ * `internal/editor-guidance` rejects editor `options` as a description source
+ * on the evidence that the labels merely restate the values. That holds for
+ * most of this pool too — `SCOAAccount` is labelled "SCOA Account", `SA34B` is
+ * labelled "SA34B" — and those are dropped here rather than repeated. What is
+ * left is the residue that genuinely disambiguates: `AccountNumber` is the
+ * FULL account number and `AccountNumberShortened` is the one an administrator
+ * calls "the account number", which is not a distinction a model can recover
+ * from the two identifiers alone.
+ */
+const ACCOUNT_VALUE_LABEL_GLOSS = MSCOA_ACCOUNT_VALUE_LABEL_OPTIONS.filter((option) => flatten(option.label) !== flatten(option.value))
+    .map((option) => `${option.value} is "${option.label}"`)
+    .join('; ');
+// --- schema -----------------------------------------------------------------
+/**
+ * `DualCashExclusionMatchMode` is a string-union type with no runtime object to
+ * read, so its members are restated under {@link exhaustive} rather than
+ * derived — drop one and this stops compiling.
+ */
+export const DUAL_CASH_MATCH_MODE_VALUES = exhaustive()(['any', 'all']);
+/**
+ * One segment row: which slice of the chart of accounts the user picks from,
+ * and how that pick behaves.
+ *
+ * Shared by `segments` and `cashSegments` rather than split into two nodes.
+ * Two members are basis-specific (`inheritValueFromAccrual` is meaningless off
+ * the cash side, `vatSelectonActive` off the ITEM segment), and Skillet cannot
+ * express conditional applicability structurally — so, as with `min` and `max`
+ * on the input members, the condition is stated in the description where it can
+ * still stop a model setting a flag that cannot mean anything.
+ */
+const segmentSchema = s.object('One segment of the chart of accounts the user picks an account from.', {
+    segment: s.string('The segment key exactly as the chart of accounts spells it, upper case — ITEM, FUNCTION, FUND, PROJECT, REGION and so on. The real list comes from the loaded account tree, so use the key the municipality actually publishes rather than inventing a plausible one. On an extension row this names the segment being extended.'),
+    customSegment: optional(s.string('The upper-cased key an extension row stores its accounts under, derived from the label (a row labelled "Retention" is keyed RETENTION). Leave null on an ordinary segment, which is keyed by its segment key instead.')),
+    label: s.string('The heading shown above this row in the account chart, in title case. Name what the user is choosing, not the segment code.'),
+    readOnly: s.boolean('Whether the row is displayed but cannot be changed by the user. Set this on a segment whose account is fixed by policy or copied from elsewhere.'),
+    singleSelect: s.boolean('True when the row captures one account only. False adds a second account to every row in this table, so the user picks a debit and a credit pair. ITEM is the only segment that carries two legs; every other segment holds the same account on both sides. So set it false on ITEM alone, and only when the form genuinely captures both sides.'),
+    additionalAccounts: s.array('Extra account columns shown on this row, named exactly as they appear in extensionAccountsForSegments on this same configuration. A name that is not in that list renders nothing. Leave empty when the row needs no extra columns.', s.string('An extension-account name declared in extensionAccountsForSegments.')),
+    inheritValueFromAccrual: optional(s.boolean('Cash rows only: copies the account selected on the matching accrual row instead of asking again. Leave null on an accrual segment.')),
+    // The member really is spelled `vatSelectonActive` in the stored shape. It
+    // is not corrected here: renaming it would silently drop the flag on every
+    // form already persisted with it.
+    vatSelectonActive: optional(s.boolean('Adds the VAT-status column to the account chart. It applies to the ITEM segment, which is the only one carrying a VAT treatment; leave null elsewhere.')),
+    segmentExtension: s.boolean('True for an extra level authored under a segment rather than a segment of the published chart. An extension row is keyed by customSegment and may reuse a segment key another row already claims; an ordinary row may not.'),
+});
+/**
+ * One cash-exclusion rule.
+ *
+ * These are the only members here with per-property guidance to draw on: the
+ * `mscoaConfig` row opens a composite editor, and its `secondaryElementEditorConfig`
+ * carries a hand-written hint for each of `pattern`, `flags`, `matchField`,
+ * `segment` and `description`. {@link describeIn} reads them from that secondary editor
+ * rather than from the top-level index — see `internal/editor-guidance` for why
+ * those rows are indexed under the row that opens them instead of being
+ * prefixed with its path.
+ */
+const dualCashExclusionRuleSchema = s.object('One condition under which the cash side is not required.', {
+    pattern: s.string(describeIn('A JavaScript regular expression, written without the surrounding slashes, tested against each selected accrual account.', ['mscoaConfig'], 'pattern')),
+    flags: optional(s.string(describeIn('Regular-expression flags for the pattern above. Leave null for an exact-case match.', ['mscoaConfig'], 'flags'))),
+    matchField: optional(s.enumeration(describeIn('Overrides, for THIS rule only, the labelled field the pattern is tested against; accountValueLabel above is the default. Set it when the condition keys off something the control does not display — a description field, say, on a control that shows account numbers. Leave null otherwise, which is the usual case.', ['mscoaConfig'], 'matchField'), ACCOUNT_VALUE_LABEL_ENTRIES)),
+    segment: optional(s.string(describeIn('Restricts the test to the accounts chosen for one accrual segment, named by its upper-cased segment key. It must be a segment this configuration actually declares — a scope nothing declares can never match. Leave null to test every accrual segment.', ['mscoaConfig'], 'segment'))),
+    description: optional(s.string(describeIn('A note for administrators explaining the business intent of this condition. It is never shown to the person filling in the form.', ['mscoaConfig'], 'description'))),
+});
+/**
+ * The `mscoaConfig` schema.
+ *
+ * A plain const, not a factory: nothing in here is chosen from candidates the
+ * caller holds. The one member that draws on a fixed pool — `accountValueLabel`
+ * — reads that pool out of this package at evaluation.
+ *
+ * ## Where the editor guidance is attached, and where it is not
+ *
+ * There is exactly ONE editor row for this whole object, at path
+ * `['mscoaConfig']`: a composite `MscoaConfig` editor that replaced eight
+ * separate rows (accountingBasis, accountValueLabel, showAllSegments, segments,
+ * cashSegments, the two dual-cash members and extensionAccountsForSegments).
+ * So {@link describe} is called once, on the object the row actually edits, and
+ * the members below carry authored descriptions only.
+ *
+ * That is a deliberate choice rather than an oversight. Calling
+ * `describe(base, 'mscoaConfig')` on each member compiles and would append the
+ * same forty-word hint — ending in "Opens a guided setup", which is advice for
+ * someone looking at a settings panel — to all seven of them. Layering it once,
+ * on the composite, says the same thing in one place.
+ */
+export const mscoaConfigSchema = s.object(describe('How this control asks the user to select a municipal SCOA account.', 'mscoaConfig'), {
+    accountingBasis: optional(accountingBasisSchema),
+    segments: s.array('The accrual segments the user picks an account for, in the order they should appear. At least one is required, and this is the list the control is built from — an empty one gives the user nothing to choose. A budget capture usually asks for all seven segments of the chart.', segmentSchema, { minItems: 1 }),
+    cashSegments: optional(s.array('The segments captured on the cash side. Only meaningful when the accounting basis is cash or dual; leave null for an accrual-only input. A cash row that mirrors an accrual one should normally set inheritValueFromAccrual rather than ask the user twice.', segmentSchema)),
+    accountValueLabel: s.enumeration(`Which field of the account identifies it to the user, everywhere this control shows one. Choose the field an administrator would read back in the chart of accounts. ${ACCOUNT_VALUE_LABEL_GLOSS}.`, ACCOUNT_VALUE_LABEL_ENTRIES),
+    showAllSegments: s.boolean('True reflects every segment of the loaded account tree, read-only, instead of only the ones listed here — the application reconciles the list against the tree, so segments authored here are kept but not exclusive. False shows exactly the segments listed and nothing else, which is the usual choice.'),
+    extensionAccountsForSegments: s.array('Names of extra account columns this control offers on top of the ordinary account, each becoming a column on the chart. A segment opts into one by naming it in its own additionalAccounts. Leave empty when the control captures ordinary accounts only.', s.string('An extension-account name, such as a counter-account this form also captures.')),
+    dualCashExclusion: optional(s.object('Dual basis only: when the cash side is NOT required, despite the basis asking for both. Leave null to require both sides always, which is the default behaviour and the right answer unless the form has a stated exception.', {
+        rules: optional(s.array('The conditions tested against the accounts the user selected on the accrual side. A rule whose pattern does not compile never matches, so it can never suppress the cash side by accident.', dualCashExclusionRuleSchema)),
+        matchMode: optional(s.enumeration("How the rules combine into one verdict: 'any' suppresses cash as soon as one rule matches, 'all' only when every rule does. Absent behaves as 'any'.", [...DUAL_CASH_MATCH_MODE_VALUES])),
+    })),
+});
+/**
+ * Members of a generated `mscoaConfig` the application must supply before Joi
+ * will accept it.
+ *
+ * `inputs` is the notable one: `MscoaInputConfigSchema` REQUIRES it, and the
+ * model is never asked for it, so a draft that is not expanded fails
+ * validation rather than merely losing a detail. An empty array satisfies it —
+ * the segments' inner inputs are generated from the segments themselves.
+ *
+ * `dualCashExclusion.rules[].id` is deliberately absent from this list: Joi
+ * marks that one optional, so leaving it unset is valid.
+ */
+export const MSCOA_DRAFT_COMPLETION = [
+    'mscoaConfig.inputs (application supplies; an empty array is valid)',
+    'mscoaConfig.segments[].id',
+    'mscoaConfig.cashSegments[].id',
+];

package/dist/skillet/members/pagination.d.ts

@@ -0,0 +1,59 @@
+import { s } from '@hashbrownai/core';
+/**
+ * The `paginationSelectionConfig` member: how a paged selection table lists and
+ * identifies its records.
+ *
+ * ## This member has no interface behind it
+ *
+ * Unusually, nothing in this package declares `paginationSelectionConfig` on a
+ * form input. It exists as a key in `AllFormInputPrimaryKeys`, and as
+ * `paginationSelectionConfigSchema` in `schemas/FormInputSchema.ts`, but no
+ * member of the `FormColumnInputs` intersection has that name — which is why it
+ * falls under `UnbackedInputMember` in `input-members.ts`.
+ *
+ * That matters here rather than being trivia: the `_NoValueDrift` assertion
+ * resolves an unbacked key to `unknown`, and everything is assignable to
+ * `unknown`, so the compiler cannot check this node against anything. The Joi
+ * schema is therefore the ONLY thing holding it, and it is followed literally.
+ * A description that drifts from `paginationSelectionConfigSchema` will not
+ * fail the build the way the backed members do; it will fail validation at
+ * runtime.
+ *
+ * ## Why this is a draft
+ *
+ * Each column carries a required `id`, a builder-assigned row key, handled as
+ * every other assigned identifier is: omitted here and stamped on expansion.
+ *
+ * `primaryIdentifierKey` is omitted outright. It is an array of key-tree nodes
+ * built by the settings panel from a real sample document, and the editor row
+ * says an unset value means `_id` is used — so an absent one is both authorable
+ * and correct, whereas a model inventing tree nodes is neither.
+ */
+export interface PaginationColumnDraft {
+    key: string;
+    label: string;
+}
+export interface PaginationSelectionConfigDraft {
+    useLocalPagination: boolean | null;
+    columns: PaginationColumnDraft[];
+}
+export declare const paginationSelectionConfigDraftSchema: s.ObjectType<{
+    useLocalPagination: import("@hashbrownai/core/src/schema/base").SchemaForUnion<boolean | null>;
+    columns: s.ArrayType<s.ObjectType<{
+        key: s.StringType;
+        label: s.StringType;
+    }>>;
+}>;
+/**
+ * The node produces the draft it declares.
+ *
+ * This is the only compile-time check available for this member — see the note
+ * above about it having no interface to be checked against.
+ */
+export type _NoPaginationDraftDrift = [
+    s.Infer<typeof paginationSelectionConfigDraftSchema>
+] extends [PaginationSelectionConfigDraft] ? never : [
+    'paginationSelectionConfigDraftSchema drifted from PaginationSelectionConfigDraft'
+];
+/** Members of a generated config the application must supply. */
+export declare const PAGINATION_DRAFT_COMPLETION: readonly ["paginationSelectionConfig.columns[].id"];