bank20baht-ui 0.0.7 → 0.0.8

package/README.md

@@ -67,6 +67,45 @@ Value is an array of row objects (`getData().items → [{ name, qty }, …]`). R
 the UI (`minRows`/`maxRows` bound the count), each row validates its sub-fields — errors come
 back as `items[0].name`, on both the client and `bank20baht-validator`. One level deep only.
 
+### Dependent / async dropdowns
+
+```js
+// schema — functions never live in JSON, only registry names:
+{ order: 2, type: 'dropdown', key: 'amphoe', optionsFrom: 'amphoeFor', optionsDeps: ['province'] }
+
+// registry:
+el.registry = {
+  options: { amphoeFor: (data) => fetch(`/api/amphoe?p=${data.province}`).then(r => r.json()) },
+};
+```
+
+Options resolve from the registry with the form's current data (sync or Promise). When a
+dep changes, options refetch and the dependent value clears — cascading down chains
+(จังหวัด → อำเภอ → ตำบล).
+
+### Cross-field validation
+
+```js
+{ order: 2, type: 'date', key: 'end',
+  validators: [{ type: 'compare', op: 'gte', field: 'start' }] }
+```
+
+`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.
+
+### Drafts / autosave (host pattern)
+
+The library is controlled — autosave is three lines in your app:
+
+```js
+el.addEventListener('baht-change', (e) => localStorage.setItem(key, JSON.stringify(e.detail.data)));
+// (workflow: listen to baht-data-change instead)
+el.value = JSON.parse(localStorage.getItem(key) ?? '{}'); // restore on mount
+// clear the key after the server accepts the submission
+```
+
+See `apps/web`'s render page for a working restore/discard/clear-on-submit flow.
+
 ### i18n — Thai (or any) built-in strings
 
 All built-in strings — validation messages, Next/Submit/Back, the approval step —

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

@@ -32,7 +32,23 @@ export declare class BahtForm extends BahtElement {
      * which drops focus and makes continuous typing impossible.
      */
     private controls;
+    /** Resolved dynamic options + the dep snapshot / fetch epoch they belong to. */
+    private dynamicOptions;
+    private optionsSnapshots;
+    private optionsEpoch;
     protected willUpdate(changed: Map<PropertyKey, unknown>): void;
+    /**
+     * Refetch `optionsFrom` options whose dep snapshot changed. Sync fetchers
+     * land immediately; async ones re-render on resolve (stale responses are
+     * dropped by epoch).
+     */
+    private syncDynamicOptions;
+    /**
+     * A user edit invalidates every field whose optionsDeps include the edited
+     * key — their values reset to defaults, cascading down chains
+     * (province -> district -> subdistrict).
+     */
+    private clearDependents;
     private get sortedFields();
     private stateFor;
     private valueFor;

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

@@ -1,4 +1,9 @@
 import { Condition, NestedData } from '../types.js';
 /** Read a "formName.fieldKey" reference out of nested data. */
 export declare function readRef(data: NestedData, ref: string): unknown;
+/**
+ * Ordering used by rule conditions AND the `compare` validator: numeric when
+ * both sides coerce, date-aware, else lexicographic. Null = not comparable.
+ */
+export declare function compareValues(a: unknown, b: unknown): number | null;
 export declare function evalCondition(cond: Condition | undefined, data: NestedData): boolean;

package/dist/core/i18n.d.ts

@@ -6,6 +6,12 @@ export interface MessageCatalog {
     max: string;
     pattern: string;
     email: string;
+    compareEq: string;
+    compareNe: string;
+    compareGt: string;
+    compareGte: string;
+    compareLt: string;
+    compareLte: string;
     addRow: string;
     removeRow: string;
     minRows: string;

package/dist/core/types.d.ts

@@ -5,11 +5,20 @@ export interface FieldOption {
     key: string;
     label: string;
 }
-/** Declarative validator (spec 01 §4). `custom` resolves `fn` from the registry. */
+/** Ordering/equality ops available to the `compare` validator. */
+export type CompareOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+/**
+ * Declarative validator (spec 01 §4). `custom` resolves `fn` from the
+ * registry; `compare` checks this value against a sibling field's value
+ * (same form — or same row inside a repeater) and skips while the sibling
+ * is empty or unknown.
+ */
 export interface ValidatorSpec {
-    type: 'required' | 'minLength' | 'maxLength' | 'min' | 'max' | 'pattern' | 'email' | 'custom';
+    type: 'required' | 'minLength' | 'maxLength' | 'min' | 'max' | 'pattern' | 'email' | 'compare' | 'custom';
     value?: unknown;
     fn?: string;
+    op?: CompareOp;
+    field?: string;
     message?: string;
 }
 /** One item of `field_data[]` (spec 01 §1). */
@@ -26,6 +35,14 @@ export interface FieldDescriptor {
     disabled?: boolean;
     required?: boolean;
     options?: FieldOption[];
+    /** Registry name resolving this field's options from current form data. */
+    optionsFrom?: string;
+    /**
+     * Same-form field keys this field's options depend on. When one changes
+     * (user edit), the options refetch and this field's value clears —
+     * cascading through chained dependents (province -> district -> …).
+     */
+    optionsDeps?: string[];
     maxLength?: number;
     minLength?: number;
     min?: number | string;
@@ -154,6 +171,8 @@ export interface Registry {
     formatters?: Record<string, (value: unknown) => unknown>;
     /** Return null when valid, or an error message string. */
     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[]>>;
 }
 export interface DerivedFieldState {
     visible: boolean;

package/dist/core/validators.d.ts

@@ -2,7 +2,9 @@ import { FieldDescriptor, Registry, ValidationError } from './types.js';
 /**
  * Validate one field's value against its declarative validators (spec 01 §4).
  * Empty + not required = valid (other validators only run on non-empty values).
- * Repeaters (spec 01 §10) additionally check row bounds and recurse into each
- * row's sub-fields, prefixing keys as `key[i].subKey`.
+ * `data` is the surrounding flat form data — only `compare` validators read
+ * it; omitting it skips them. Repeaters (spec 01 §10) additionally check row
+ * bounds and recurse into each row's sub-fields, prefixing keys as
+ * `key[i].subKey` (each row is its own compare context).
  */
-export declare function validateField(field: FieldDescriptor, value: unknown, registry?: Registry): ValidationError[];
+export declare function validateField(field: FieldDescriptor, value: unknown, registry?: Registry, data?: Record<string, unknown>): ValidationError[];

package/dist/custom-elements.json

@@ -86,6 +86,55 @@
               "default": "new Map<string, HTMLElement & Record<string, unknown>>()",
               "description": "One control element per field key, reused across renders. Recreating them\nevery render (the naive approach) replaces the DOM node on each keystroke,\nwhich drops focus and makes continuous typing impossible."
             },
+            {
+              "kind": "field",
+              "name": "dynamicOptions",
+              "privacy": "private",
+              "default": "new Map<string, FieldOption[]>()",
+              "description": "Resolved dynamic options + the dep snapshot / fetch epoch they belong to."
+            },
+            {
+              "kind": "field",
+              "name": "optionsSnapshots",
+              "privacy": "private",
+              "default": "new Map<string, string>()"
+            },
+            {
+              "kind": "field",
+              "name": "optionsEpoch",
+              "privacy": "private",
+              "default": "new Map<string, number>()"
+            },
+            {
+              "kind": "method",
+              "name": "syncDynamicOptions",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Refetch `optionsFrom` options whose dep snapshot changed. Sync fetchers\nland immediately; async ones re-render on resolve (stale responses are\ndropped by epoch)."
+            },
+            {
+              "kind": "method",
+              "name": "clearDependents",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "changedKey",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "A user edit invalidates every field whose optionsDeps include the edited\nkey — their values reset to defaults, cascading down chains\n(province -> district -> subdistrict)."
+            },
             {
               "kind": "field",
               "name": "sortedFields",