bank20baht-ui 0.0.9 → 0.0.11

package/README.md

@@ -93,6 +93,40 @@ dep changes, options refetch and the dependent value clears — cascading down c
 `compare` checks against a sibling field (confirm email = `op: 'eq'`), numeric/date-aware,
 skips while either side is empty. Works inside repeater rows and on the server.
 
+### Feature flags — deploy dark, flip a JSON file
+
+```js
+// schema: gate a field / workflow step / rule
+{ order: 9, type: 'text', key: 'promoCode', flag: 'promo' }   // '!promo' = the old path
+
+// host: flags from one static file — edit it, features flip
+el.flags = await fetch('/flags.json').then((r) => r.json());  // { "promo": true }
+```
+
+Flag-off means **not in the schema**: no render, no validation (a dark `required` can't
+block), nothing in the payload. Missing keys count as off, so new features stay dark until
+the file turns them on. Server side: `validateSubmission(applyFlags(schema, flags), data)`
+with the same JSON — `bank20baht-validator` re-exports `applyFlags`.
+
+### File upload
+
+```js
+// schema:
+{ order: 6, type: 'file', key: 'doc', uploader: 'default', accept: '.pdf,image/*', maxSize: 10_485_760 }
+
+// registry — File in, serializable ref out:
+el.registry = {
+  uploaders: { default: async (file) => {
+    const fd = new FormData(); fd.append('file', file);
+    return (await fetch('/api/uploads', { method: 'POST', body: fd })).json();
+  } },
+};
+```
+
+Picking a file uploads immediately; the value becomes `{ name, size, type, url }` — plain
+JSON, chips with remove buttons in the UI, `maxSize`/`accept` validated on both client and
+server. Omit `uploader` for the old capture-only mode.
+
 ### Drafts / autosave (host pattern)
 
 The library is controlled — autosave is three lines in your app:

package/dist/components/baht-form.d.ts

@@ -1,6 +1,6 @@
 import { TemplateResult } from 'lit';
 import { BahtElement } from './base.js';
-import { DerivedFieldState, FormDefinition, Registry, ValidationError } from '../core/types.js';
+import { DerivedFieldState, FeatureFlags, FormDefinition, Registry, ValidationError } from '../core/types.js';
 export interface BahtFormOptions {
     validateOn?: 'change' | 'blur' | 'submit';
 }
@@ -23,6 +23,11 @@ export declare class BahtForm extends BahtElement {
      * the complete schema, views never change the submit payload.
      */
     view?: string;
+    /**
+     * Feature-flag values (spec 01 §12) — fields whose `flag` is off behave as
+     * if they were never in the schema: no render, no validation, no payload.
+     */
+    flags: FeatureFlags;
     /** Edits the user made since the host last set `value` (controlled overlay). */
     private edits;
     private errors;
@@ -36,6 +41,9 @@ export declare class BahtForm extends BahtElement {
     private dynamicOptions;
     private optionsSnapshots;
     private optionsEpoch;
+    /** applyFlags result, memoized on (form, flags) identity. */
+    private flagCache;
+    private get effectiveForm();
     protected willUpdate(changed: Map<PropertyKey, unknown>): void;
     /**
      * Refetch `optionsFrom` options whose dep snapshot changed. Sync fetchers

package/dist/components/baht-workflow.d.ts

@@ -1,6 +1,6 @@
 import { TemplateResult } from 'lit';
 import { BahtElement } from './base.js';
-import { NestedData, Registry, WorkflowDefinition } from '../core/types.js';
+import { FeatureFlags, NestedData, Registry, WorkflowDefinition } from '../core/types.js';
 /**
  * <baht-workflow> — the optional brain (spec 03). Wraps the current form in an
  * internal <baht-form>, evaluates rules on every change, walks the visible forms
@@ -21,17 +21,26 @@ export declare class BahtWorkflow extends BahtElement {
     submitLabel?: string;
     backLabel?: string;
     showBack: boolean;
+    /** Feature-flag values (spec 01 §12): flag-off steps/fields/rules vanish. */
+    flags: FeatureFlags;
+    /** Render a <baht-steps> progress indicator above the current form. */
+    showSteps: boolean;
     private data;
     private derived;
     private current;
     private approvalError;
     private history;
     get currentFormName(): string | null;
+    /** applyFlags result, memoized on (workflow, flags) identity. */
+    private flagCache;
+    private get effectiveWorkflow();
     protected willUpdate(changed: Map<PropertyKey, unknown>): void;
     private reevaluate;
     /** Forms in ascending order whose derived visibility is true. */
     private get visibleForms();
     private get currentForm();
+    /** Where next() would go from here: a formName or 'end' (spec 03 §6). */
+    private get navTarget();
     private get isLast();
     private fieldStatesFor;
     private get formEl();
@@ -43,7 +52,7 @@ export declare class BahtWorkflow extends BahtElement {
      */
     setValue(formName: string, patch: Record<string, unknown>): void;
     next(): void;
-    /** Advance past the current form: submit+complete on the last one, else step forward. */
+    /** Advance past the current form: submit+complete at 'end', else step to navTarget. */
     private advance;
     /** Approve the current approval step (same as pressing its Approve button). */
     approve(): void;

package/dist/components/primitives/baht-file.d.ts

@@ -1,9 +1,22 @@
 import { TemplateResult } from 'lit';
 import { BahtFieldBase } from '../base.js';
+import { UploadedFile } from '../../core/types.js';
 /**
- * Capture only (spec 01 §2): value = File handle(s); the lib never uploads.
+ * File field (spec 01 §2 + §13). Two modes:
+ * - capture (default): value = File handle(s); the lib never uploads.
+ * - upload (`field.uploader` + host `uploader` fn from the registry):
+ *   picking uploads immediately, value becomes serializable UploadedFile
+ *   ref(s), and the control shows chips with remove buttons.
  * maxSize (bytes) is enforced here as a soft filter — oversize files rejected.
  */
 export declare class BahtFile extends BahtFieldBase {
+    /** Resolved registry uploader — <baht-form> injects it when `field.uploader` is set. */
+    uploader?: (file: File) => Promise<UploadedFile>;
+    private uploadingCount;
+    private uploadError;
+    private get refs();
+    private emitRefs;
+    private uploadAll;
+    private onPick;
     protected renderControl(): TemplateResult;
 }

package/dist/components/primitives/baht-steps.d.ts

@@ -0,0 +1,20 @@
+import { TemplateResult } from 'lit';
+import { BahtElement } from '../base.js';
+/**
+ * <baht-steps> — wizard progress indicator (spec 03). Standalone display
+ * primitive: numbered markers + labels, the current one highlighted, done
+ * ones checked. <baht-workflow show-steps> renders it automatically from its
+ * visible forms.
+ */
+export declare class BahtSteps extends BahtElement {
+    /** Step labels in order. */
+    steps: string[];
+    /** 0-based index of the current step. */
+    current: number;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'baht-steps': BahtSteps;
+    }
+}

package/dist/components/primitives/index.d.ts

@@ -42,4 +42,5 @@ export { BahtErrorState } from './baht-error-state.js';
 export { BahtKeyvalueEditor } from './baht-keyvalue-editor.js';
 export { BahtReferencePicker, type ReferenceOption } from './baht-reference-picker.js';
 export { BahtRepeater } from './baht-repeater.js';
+export { BahtSteps } from './baht-steps.js';
 export { TAG_FOR_TYPE } from './tag-map.js';

package/dist/core/engine/graph.d.ts

@@ -0,0 +1,13 @@
+import { NestedData, WorkflowDefinition } from '../types.js';
+/**
+ * The step after `current` given the data: a formName or 'end'. Rules run
+ * (via evaluate) to decide visibility; hidden targets pass through, cycles
+ * of invisible forms end the walk.
+ */
+export declare function resolveNext(workflow: WorkflowDefinition, current: string, data: NestedData): string | 'end';
+/**
+ * The full path a submission takes from the start form to 'end' under this
+ * data — what the server validates against (off-path forms are as good as
+ * skipped). Back-edges that revisit a form stop the walk instead of looping.
+ */
+export declare function walkPath(workflow: WorkflowDefinition, data: NestedData): string[];

package/dist/core/flags.d.ts

@@ -0,0 +1,19 @@
+import { FeatureFlags, FormDefinition, WorkflowDefinition } from './types.js';
+/**
+ * Is a `flag` expression on (spec 01 §12)?
+ * - no flag        -> always on
+ * - 'name'         -> on only while flags.name is true
+ * - '!name'        -> on only while flags.name is NOT true
+ * A missing key counts as false — new features stay dark until the flags
+ * file explicitly turns them on.
+ */
+export declare function flagEnabled(flag: string | undefined, flags: FeatureFlags): boolean;
+/**
+ * Resolve every `flag` in a definition against the current flag values:
+ * flag-off fields/steps/rules come back REMOVED, as if never authored —
+ * they don't render, don't validate, and never reach the payload. Run the
+ * same call server-side (bank20baht-validator re-exports it) with the same
+ * flags JSON so both sides agree. Returns the input untouched when nothing
+ * in it carries a flag.
+ */
+export declare function applyFlags<T extends FormDefinition | WorkflowDefinition>(schema: T, flags?: FeatureFlags): T;

package/dist/core/i18n.d.ts

@@ -12,6 +12,11 @@ export interface MessageCatalog {
     compareGte: string;
     compareLt: string;
     compareLte: string;
+    fileTooLarge: string;
+    fileTypeNotAllowed: string;
+    uploading: string;
+    uploadFailed: string;
+    removeFile: string;
     addRow: string;
     removeRow: string;
     minRows: string;

package/dist/core/index.d.ts

@@ -3,8 +3,10 @@ export { defaultValue } from './defaults.js';
 export { approvalFields } from './approval.js';
 export { validateField } from './validators.js';
 export { resolveViewFields } from './views.js';
+export { applyFlags, flagEnabled } from './flags.js';
 export { setLocale, t } from './i18n.js';
 export type { Locale, MessageCatalog, MessageKey } from './i18n.js';
 export { evaluate } from './engine/evaluate.js';
+export { resolveNext, walkPath } from './engine/graph.js';
 export { evalCondition, readRef } from './engine/conditions.js';
 export { evalValueExpr } from './engine/expressions.js';

package/dist/core/types.d.ts

@@ -52,8 +52,20 @@ export interface FieldDescriptor {
     accept?: string;
     multiple?: boolean;
     maxSize?: number;
+    /**
+     * Registry uploader name (spec 01 §13). With it, picking a file uploads
+     * immediately and the VALUE becomes a serializable UploadedFile ref
+     * (arrays when `multiple`) — without it, capture-only File handles (v1).
+     */
+    uploader?: string;
     text?: string;
     variant?: string;
+    /**
+     * Feature flag gating this field (spec 01 §12): shown only while the flag
+     * is on ('name') or off ('!name'). Flag-off = as if the field were never in
+     * the schema — not rendered, not validated, absent from the payload.
+     */
+    flag?: string;
     fields?: FieldDescriptor[];
     minRows?: number;
     maxRows?: number;
@@ -108,6 +120,8 @@ export interface WorkflowForm extends FormDefinition {
     approval?: ApprovalConfig;
     /** Name of one of this form's `views` to render for this step (display only). */
     view?: string;
+    /** Feature flag gating this whole step (spec 01 §12). */
+    flag?: string;
 }
 export type ConditionOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'isEmpty' | 'isNotEmpty';
 /** Leaf: compare `formName.fieldKey` against a constant or another field. */
@@ -160,12 +174,38 @@ export interface Rule {
     when?: Condition;
     then?: Action[];
     else?: Action[];
+    /** Feature flag gating this rule (spec 01 §12). */
+    flag?: string;
+}
+/** Flag values — typically fetched from one static JSON file (spec 01 §12). */
+export type FeatureFlags = Record<string, boolean>;
+/**
+ * A conditional edge between steps (spec 03 §6). With `transitions` present
+ * the wizard routes as a graph: from a form, the first edge whose `when`
+ * matches wins; `to: 'end'` submits. Forms with no outgoing edges (and
+ * non-matching edge sets) fall back to the next visible form in `order`, so
+ * linear authoring keeps working and branches are added only where needed.
+ */
+export interface Transition {
+    from: string;
+    to: string | 'end';
+    when?: Condition;
+    flag?: string;
 }
 /** A Workflow definition — consumed by <baht-workflow> (spec 00 §4.2). */
 export interface WorkflowDefinition {
     workflowId: string;
     forms: WorkflowForm[];
     rules: Rule[];
+    /** Optional graph routing (spec 03 §6); absent = linear by `order`. */
+    transitions?: Transition[];
+}
+/** Serializable result of a registry uploader (spec 01 §13). */
+export interface UploadedFile {
+    name: string;
+    size: number;
+    type?: string;
+    url: string;
 }
 export interface Registry {
     formatters?: Record<string, (value: unknown) => unknown>;
@@ -173,6 +213,8 @@ export interface Registry {
     validators?: Record<string, (value: unknown) => string | null>;
     /** Option fetchers for `optionsFrom` — receive the form's current flat data. */
     options?: Record<string, (data: Record<string, unknown>) => FieldOption[] | Promise<FieldOption[]>>;
+    /** File uploaders for `uploader` — take the picked File, return its ref. */
+    uploaders?: Record<string, (file: File) => Promise<UploadedFile>>;
 }
 export interface DerivedFieldState {
     visible: boolean;

package/dist/custom-elements.json

@@ -60,6 +60,15 @@
               "description": "Name of a view from `form.views`. Display-only: when set, only that view's\nfields are rendered and validated (the user can only fix what they see),\nbut getData() still returns the FULL form — the server always validates\nthe complete schema, views never change the submit payload.",
               "attribute": "view"
             },
+            {
+              "kind": "field",
+              "name": "flags",
+              "type": {
+                "text": "FeatureFlags"
+              },
+              "default": "{}",
+              "description": "Feature-flag values (spec 01 §12) — fields whose `flag` is off behave as\nif they were never in the schema: no render, no validation, no payload."
+            },
             {
               "kind": "field",
               "name": "edits",
@@ -105,6 +114,25 @@
               "privacy": "private",
               "default": "new Map<string, number>()"
             },
+            {
+              "kind": "field",
+              "name": "flagCache",
+              "type": {
+                "text": "{ form?: FormDefinition; flags?: FeatureFlags; out?: FormDefinition }"
+              },
+              "privacy": "private",
+              "default": "{}",
+              "description": "applyFlags result, memoized on (form, flags) identity."
+            },
+            {
+              "kind": "field",
+              "name": "effectiveForm",
+              "type": {
+                "text": "FormDefinition"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "syncDynamicOptions",
@@ -401,6 +429,25 @@
               "default": "true",
               "attribute": "show-back"
             },
+            {
+              "kind": "field",
+              "name": "flags",
+              "type": {
+                "text": "FeatureFlags"
+              },
+              "default": "{}",
+              "description": "Feature-flag values (spec 01 §12): flag-off steps/fields/rules vanish."
+            },
+            {
+              "kind": "field",
+              "name": "showSteps",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Render a <baht-steps> progress indicator above the current form.",
+              "attribute": "show-steps"
+            },
             {
               "kind": "field",
               "name": "data",
@@ -454,6 +501,25 @@
               },
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "flagCache",
+              "type": {
+                "text": "{\n    workflow?: WorkflowDefinition;\n    flags?: FeatureFlags;\n    out?: WorkflowDefinition;\n  }"
+              },
+              "privacy": "private",
+              "default": "{}",
+              "description": "applyFlags result, memoized on (workflow, flags) identity."
+            },
+            {
+              "kind": "field",
+              "name": "effectiveWorkflow",
+              "type": {
+                "text": "WorkflowDefinition"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "reevaluate",
@@ -483,6 +549,16 @@
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "navTarget",
+              "type": {
+                "text": "string | 'end'"
+              },
+              "privacy": "private",
+              "description": "Where next() would go from here: a formName or 'end' (spec 03 §6).",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "isLast",
@@ -579,7 +655,7 @@
                   }
                 }
               ],
-              "description": "Advance past the current form: submit+complete on the last one, else step forward."
+              "description": "Advance past the current form: submit+complete at 'end', else step to navTarget."
             },
             {
               "kind": "method",
@@ -831,6 +907,15 @@
               },
               "default": "true",
               "fieldName": "showBack"
+            },
+            {
+              "name": "show-steps",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Render a <baht-steps> progress indicator above the current form.",
+              "fieldName": "showSteps"
             }
           ],
           "superclass": {
@@ -3022,9 +3107,98 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Capture only (spec 01 §2): value = File handle(s); the lib never uploads.\nmaxSize (bytes) is enforced here as a soft filter — oversize files rejected.",
+          "description": "File field (spec 01 §2 + §13). Two modes:\n- capture (default): value = File handle(s); the lib never uploads.\n- upload (`field.uploader` + host `uploader` fn from the registry):\n  picking uploads immediately, value becomes serializable UploadedFile\n  ref(s), and the control shows chips with remove buttons.\nmaxSize (bytes) is enforced here as a soft filter — oversize files rejected.",
           "name": "BahtFile",
           "members": [
+            {
+              "kind": "field",
+              "name": "uploader",
+              "type": {
+                "text": "(file: File) => Promise<UploadedFile> | undefined"
+              },
+              "description": "Resolved registry uploader — <baht-form> injects it when `field.uploader` is set."
+            },
+            {
+              "kind": "field",
+              "name": "uploadingCount",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "uploadError",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "refs",
+              "type": {
+                "text": "UploadedFile[]"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "emitRefs",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "refs",
+                  "type": {
+                    "text": "UploadedFile[]"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "uploadAll",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "files",
+                  "type": {
+                    "text": "File[]"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "onPick",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "renderControl",
@@ -7706,6 +7880,73 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/primitives/baht-steps.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "<baht-steps> — wizard progress indicator (spec 03). Standalone display\nprimitive: numbered markers + labels, the current one highlighted, done\nones checked. <baht-workflow show-steps> renders it automatically from its\nvisible forms.",
+          "name": "BahtSteps",
+          "members": [
+            {
+              "kind": "field",
+              "name": "steps",
+              "type": {
+                "text": "string[]"
+              },
+              "default": "[]",
+              "description": "Step labels in order."
+            },
+            {
+              "kind": "field",
+              "name": "current",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "0-based index of the current step.",
+              "attribute": "current"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "current",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "0-based index of the current step.",
+              "fieldName": "current"
+            }
+          ],
+          "superclass": {
+            "name": "BahtElement",
+            "module": "/src/components/base.js"
+          },
+          "tagName": "baht-steps",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "BahtSteps",
+          "declaration": {
+            "name": "BahtSteps",
+            "module": "src/components/primitives/baht-steps.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "baht-steps",
+          "declaration": {
+            "name": "BahtSteps",
+            "module": "src/components/primitives/baht-steps.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/components/primitives/baht-table.ts",
@@ -9531,6 +9772,14 @@
             "module": "./baht-repeater.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "BahtSteps",
+          "declaration": {
+            "name": "BahtSteps",
+            "module": "./baht-steps.js"
+          }
+        },
         {
           "kind": "js",
           "name": "TAG_FOR_TYPE",