@businessdash/sdk 0.9.60

package/dist/forms-core/validation.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Framework-agnostic, isomorphic form validation + condition evaluation.
+ *
+ * Zero UI deps, zero React, zero DOM. This is the single source of truth every
+ * `<BiabForm>` binding (React / Vue / Svelte / Solid / Qwik / Angular / Element /
+ * vanilla) shares. It is a faithful port of three existing BIAB modules so the
+ * client never disagrees with the server:
+ *
+ *   - `src/server/forms/validate.ts`           — isEmpty / validateValue /
+ *                                                 evalCondition / findMissingRequired
+ *   - `src/app/.../builder/FormPreview.tsx`     — seedInitialData / concurrentRevealCount /
+ *                                                 the or_condition + condition_block walk
+ *   - `biab-dev/src/sdk.ts` validateFormSubmission — the wire-level submission check
+ *
+ * The schema published by `client.forms.schema(slug)` carries the FULL nested
+ * field tree (layout nodes, `condition_block`, `or_condition`, `input_group`,
+ * `flex_row` with `children`, plus the resolved output `key` on each
+ * value-bearing field). These helpers walk that tree, NOT the flattened
+ * `FormFieldDef[]` view.
+ */
+/** A condition clause: one operator (+ optional target value) on a field. */
+export interface FormConditionClause {
+    operator: string;
+    value?: string;
+}
+/** A field's `conditionRule` — supports the modern multi-clause form and the
+ *  legacy single `{ operator, value }` form (read as one clause). */
+export interface FormConditionRule {
+    fieldId?: string;
+    operator?: string;
+    value?: string;
+    clauses?: FormConditionClause[];
+    /** How clauses combine: "all" (default, AND) or "any" (OR). This was missing
+     *  from the type, so a rule the builder saved as "ANY of" silently evaluated
+     *  as "ALL of" once it rendered through the SDK. */
+    match?: "all" | "any";
+    /** Collection pickers store record IDS — compare THIS column of the chosen
+     *  record instead ("__label__" = the displayed label). Resolved by surfaces
+     *  that load the picker's options; unresolved falls back to the raw value. */
+    matchField?: string;
+}
+/**
+ * Structural view of a form field as it arrives on the wire from
+ * `client.forms.schema()`. Deliberately permissive: every binding renders by
+ * `type`, reads the value-bearing fields, and treats the rest as layout. This
+ * mirrors the server `FormField` + the builder's `FieldX`.
+ */
+export interface FormCoreField {
+    id: string;
+    /** Stable output key for the submission payload (preferred over `id`). */
+    key?: string;
+    type: string;
+    label?: string | null;
+    /** Explicit HTML `autocomplete` token for this field (e.g. "email",
+     *  "given-name", "off"). Overrides the SDK's inference. Optional / forward-
+     *  compatible — set by the form builder when present. */
+    autocomplete?: string;
+    required?: boolean;
+    /** Consent semantic for boolean fields — the value must be `true` to submit
+     *  (independent of the toggle/checkbox `display`). */
+    mustBeTrue?: boolean;
+    /**
+     * Render variant for a field whose validated type stays the same:
+     * boolean → toggle/checkbox, checkbox group → dropdown, select → combobox
+     * (the searchable "ComboBox" palette card). Display-only — never affects the
+     * submitted value or its validation.
+     */
+    display?: "toggle" | "checkbox" | "dropdown" | "combobox";
+    /** select / radio / checkbox: accept a free-text "Other…" value outside
+     *  `options` (the options whitelist isn't enforced when on). */
+    allowCustom?: boolean;
+    placeholder?: string;
+    helpText?: string;
+    options?: string[];
+    defaultValue?: string | boolean | number | null;
+    content?: string;
+    stepTitle?: string;
+    outputKey?: string | null;
+    regexPattern?: string;
+    concurrentReveal?: boolean;
+    showGroupLabel?: boolean;
+    children?: FormCoreField[] | null;
+    conditionRule?: FormConditionRule;
+    validation?: {
+        min?: number;
+        max?: number;
+    };
+    sliderConfig?: {
+        min?: number;
+        max?: number;
+        step?: number;
+        unit?: string;
+    };
+    starRatingConfig?: {
+        maxStars?: number;
+        defaultValue?: number;
+    };
+    fileConfig?: {
+        allowedTypes?: string[];
+        maxFiles?: number;
+        maxSize?: number;
+    };
+    /** `icon_select`: which icons may be picked, and the grid width. The value is
+     *  the icon's kebab-case name. */
+    iconConfig?: {
+        set?: "lucide";
+        allowedIcons?: string[];
+        columns?: number;
+    };
+    /** `image_input`: upload OR paste a URL — the value is one URL string. */
+    imageInputConfig?: {
+        allowedTypes?: string[];
+        maxSize?: number;
+        showPreview?: boolean;
+        sources?: "both" | "upload" | "url";
+    };
+    phoneConfig?: {
+        international?: boolean;
+        showFlags?: boolean;
+    };
+    timeConfig?: {
+        mode?: "simple" | "time_block" | "appointment";
+        format?: "12h" | "24h";
+        stepMinutes?: number;
+    };
+    orConditionConfig?: {
+        leftLabel?: string;
+        rightLabel?: string;
+    };
+    /** choice_cards: icon + label options. `single` = radio (value is the chosen
+     *  label string); `multi` = checkbox (value is a string[] of chosen labels).
+     *  Options can also carry richer card content (image/price/etc.) — purely
+     *  display + metadata; the submitted value is always the `label`. */
+    choiceConfig?: {
+        mode?: "single" | "multi";
+        options?: Array<{
+            label: string;
+            icon?: string;
+            imageUrl?: string;
+            price?: string;
+            description?: string;
+            productId?: string;
+            href?: string;
+        }>;
+    };
+    /** bullet_list display element: "bullets" = optional title + plain bullets;
+     *  "details" = icon + heading + description per point. Carries no value. */
+    listConfig?: {
+        variant?: "bullets" | "details";
+        title?: string;
+        items?: Array<{
+            text: string;
+            description?: string;
+            icon?: string;
+        }>;
+    };
+    /** table display element: columns (header/type/align) + rows of cells. A
+     *  "check" column renders ✓/– from a truthy/falsy cell. Carries no value. */
+    tableConfig?: {
+        columns?: Array<{
+            header: string;
+            type?: "text" | "check";
+            align?: "left" | "center" | "right";
+        }>;
+        rows?: Array<{
+            cells: string[];
+        }>;
+        highlightColumn?: number;
+    };
+    /** multi_populator repeater: value is an array of instance records (each keyed
+     *  by the child field ids). `maxInstances` caps the count (default 10). */
+    populatorConfig?: {
+        maxInstances?: number;
+        minInstances?: number;
+        addButtonLabel?: string;
+        itemLabel?: string;
+    };
+    /** measurement field: number + unit. Value is { value, unit, base, baseUnit }. */
+    unitConfig?: {
+        category?: string;
+        units?: string[];
+        mode?: "select" | "fixed";
+        defaultUnit?: string;
+        outputUnit?: string;
+        allowDecimal?: boolean;
+    };
+    /** number field: when false, only whole numbers are accepted. */
+    allowDecimal?: boolean;
+    /** number field: when false, negatives are rejected (enforce >= 0). */
+    allowNegative?: boolean;
+    /** currency field config. */
+    currencyConfig?: {
+        currency?: string;
+        symbol?: string;
+        allowNegative?: boolean;
+        allowDecimal?: boolean;
+    };
+    [key: string]: unknown;
+}
+/** A submission's working data — keyed by field `id` internally. */
+export type FormData = Record<string, unknown>;
+/** A required-field gap, surfaced to the UI for inline error display. */
+export interface MissingField {
+    id: string;
+    label: string;
+}
+/** True when a field's value should be treated as missing for required checks. */
+export declare function isEmpty(field: FormCoreField, value: unknown): boolean;
+/**
+ * Validate one value against its field definition. Returns an error reason
+ * (`"type"`, `"format"`, `"min"`, `"max"`, `"options"`, `"regex"`), or null when
+ * the value conforms. Lenient where the renderer's output is ambiguous (numeric
+ * fields accept numeric strings) so legitimate live submissions never break.
+ * Faithful port of `validateValue` in src/server/forms/validate.ts.
+ */
+export declare function validateValue(field: FormCoreField, value: unknown): string | null;
+/**
+ * A condition passes when its field satisfies ALL clauses (AND). Back-compat: a
+ * legacy single `{ operator, value }` rule is read as one clause. An absent rule
+ * (or one without a `fieldId`) passes. Faithful port of `evalCondition`.
+ */
+export declare function evalCondition(rule: FormConditionRule | undefined, data: FormData): boolean;
+/**
+ * Is a gating container currently visible?
+ *
+ * `condition_block` has always gated on its rule. `input_group` now does too:
+ * at the root of a consecutive form a group IS a page, so a rule there makes the
+ * whole page conditional. Every other type is unconditionally visible — a stray
+ * rule on a text field is ignored rather than hiding it.
+ */
+export declare function isNodeVisible(node: {
+    type?: string;
+    conditionRule?: FormConditionRule;
+}, data: FormData): boolean;
+/**
+ * Returns the required fields that haven't been filled in, evaluated under the
+ * current condition state. A `condition_block` whose rule is false is skipped
+ * with its children; an `or_condition` requires at least one side filled, then
+ * recurses only into filled sides. Non-empty text/number values must also
+ * satisfy the field's regex pattern. Faithful port of FormPreview's
+ * `findMissingRequired`.
+ */
+export declare function findMissingRequired(fields: FormCoreField[], data: FormData): MissingField[];
+/**
+ * For a "concurrent questions" group: how many leading children to reveal. Shows
+ * every already-satisfied child plus the first unsatisfied one (the active
+ * question), so each required field gates the next. Optional/empty fields count
+ * as satisfied. Faithful port of FormPreview's `concurrentRevealCount`.
+ */
+export declare function concurrentRevealCount(children: FormCoreField[], data: FormData): number;
+/**
+ * Walk the field tree once and seed every value-bearing input's id with a
+ * type-appropriate default. Static/layout/container nodes are skipped so no
+ * UUID-keyed empty string leaks into the payload (which the server would reject
+ * as an unknown field). Faithful port of FormPreview's `seedInitialData`.
+ */
+export declare function seedInitialData(fields: FormCoreField[]): FormData;
+/** Flat list of value-bearing fields (depth-first, document order). */
+export declare function flattenValueFields(fields: FormCoreField[]): FormCoreField[];
+/**
+ * Re-key working data (keyed by field `id`) to the published output `key` for
+ * the wire payload. Fields without a published `key` keep their `id`. Only
+ * value-bearing fields present in `data` are emitted.
+ */
+export declare function toSubmissionPayload(fields: FormCoreField[], data: FormData): FormData;
+//# sourceMappingURL=validation.d.ts.map

package/dist/forms-core/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/forms-core/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgBH,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;qEACqE;AACrE,MAAM,WAAW,iBAAiB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC;;wDAEoD;IACpD,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACtB;;kFAE8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;6DAEyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;0DACsD;IACtD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;IAC1D;oEACgE;IAChE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IAClC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,YAAY,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5E,gBAAgB,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,UAAU,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9E;sCACkC;IAClC,UAAU,CAAC,EAAE;QACZ,GAAG,CAAC,EAAE,QAAQ,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE;QAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;KACpC,CAAC;IACF,WAAW,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/D,UAAU,CAAC,EAAE;QACZ,IAAI,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,aAAa,CAAC;QAC/C,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,iBAAiB,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE;;;yEAGqE;IACrE,YAAY,CAAC,EAAE;QACd,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;QAC1B,OAAO,CAAC,EAAE,KAAK,CAAC;YACf,KAAK,EAAE,MAAM,CAAC;YACd,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,IAAI,CAAC,EAAE,MAAM,CAAC;SACd,CAAC,CAAC;KACH,CAAC;IACF;gFAC4E;IAC5E,UAAU,CAAC,EAAE;QACZ,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;QAChC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACrE,CAAC;IACF;iFAC6E;IAC7E,WAAW,CAAC,EAAE;QACb,OAAO,CAAC,EAAE,KAAK,CAAC;YACf,MAAM,EAAE,MAAM,CAAC;YACf,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;YACxB,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;SACpC,CAAC,CAAC;QACH,IAAI,CAAC,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;QAClC,eAAe,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;+EAC2E;IAC3E,eAAe,CAAC,EAAE;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,kFAAkF;IAClF,UAAU,CAAC,EAAE;QACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;QAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC;IACF,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,6BAA6B;IAC7B,cAAc,CAAC,EAAE;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,YAAY,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC;IAEF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,oEAAoE;AACpE,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACd;AAwED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAmFrE;AAwCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,OAAO,GACZ,MAAM,GAAG,IAAI,CAkRf;AA6BD;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE,iBAAiB,GAAG,SAAS,EACnC,IAAI,EAAE,QAAQ,GACZ,OAAO,CAgBT;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC5B,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,iBAAiB,CAAA;CAAE,EAC1D,IAAI,EAAE,QAAQ,GACZ,OAAO,CAKT;AAiCD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,aAAa,EAAE,EACvB,IAAI,EAAE,QAAQ,GACZ,YAAY,EAAE,CAkFhB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,aAAa,EAAE,EACzB,IAAI,EAAE,QAAQ,GACZ,MAAM,CAMR;AA6CD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,QAAQ,CAuBjE;AAQD,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAmB3E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,aAAa,EAAE,EACvB,IAAI,EAAE,QAAQ,GACZ,QAAQ,CAgCV"}