bank20baht-ui 0.0.6 → 0.0.8

package/README.md

@@ -35,6 +35,94 @@ npm i bank20baht-ui
 `<baht-form>` is a **dumb controlled component**: props in → UI → `baht-change` out. No buttons, no
 cross-field logic, no fetch. Your app owns the state (mutate the JSON, feed it back).
 
+### Views — show a subset of one form
+
+Define named display projections on the schema (e.g. per user role); select one with the
+`view` attribute:
+
+```js
+el.form = {
+  ...form,
+  views: [{ name: 'summary', fields: ['age', 'firstName'] }], // view order = display order
+};
+el.view = 'summary'; // or <baht-form view="summary">; unset = full form
+```
+
+Views are **client-side display only**: the view picks which fields render (and validate —
+the user can only fix what they see), but `getData()` still returns the full form and the
+server (`bank20baht-validator`) always validates the complete schema. In a workflow, set
+`view: 'summary'` on a step's form to pin the view that step renders.
+
+### Repeater — line items / repeating rows
+
+```js
+{ order: 5, type: 'repeater', key: 'items', label: 'Line items', minRows: 1,
+  fields: [
+    { order: 1, type: 'text',   key: 'name', width: '1/2', required: true },
+    { order: 2, type: 'number', key: 'qty',  width: '1/4', min: 1 },
+  ] }
+```
+
+Value is an array of row objects (`getData().items → [{ name, qty }, …]`). Rows add/remove in
+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 —
+come from one catalog:
+
+```js
+import { setLocale } from 'bank20baht-ui';
+
+setLocale('th'); // built-ins: 'en' (default), 'th'
+setLocale('th', { required: 'ห้ามว่าง' }); // locale + your own overrides
+```
+
+Call it once before mounting. Per-field `message` and label attributes
+(`next-label`, `approval.approveLabel`, …) still win over the catalog. The server can
+localize too: `bank20baht-validator` re-exports `setLocale`, so validation issues come
+back in the same language the client shows.
+
 ## Quick start — wizard with rules (Level 2)
 
 ```js

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

@@ -16,6 +16,13 @@ export declare class BahtForm extends BahtElement {
     options: BahtFormOptions;
     /** L2 (workflow) derived per-field UI state, keyed by field key. Optional. */
     fieldStates: Record<string, DerivedFieldState>;
+    /**
+     * Name of a view from `form.views`. Display-only: when set, only that view's
+     * fields are rendered and validated (the user can only fix what they see),
+     * but getData() still returns the FULL form — the server always validates
+     * the complete schema, views never change the submit payload.
+     */
+    view?: string;
     /** Edits the user made since the host last set `value` (controlled overlay). */
     private edits;
     private errors;
@@ -25,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/components/baht-workflow.d.ts

@@ -16,9 +16,10 @@ export declare class BahtWorkflow extends BahtElement {
     value: NestedData;
     registry: Registry;
     validateGate: boolean;
-    nextLabel: string;
-    submitLabel: string;
-    backLabel: string;
+    /** Label attributes beat the i18n catalog; unset = t('next')/t('submit')/t('back'). */
+    nextLabel?: string;
+    submitLabel?: string;
+    backLabel?: string;
     showBack: boolean;
     private data;
     private derived;

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

@@ -0,0 +1,33 @@
+import { TemplateResult } from 'lit';
+import { BahtFieldBase } from '../base.js';
+import { ValidationError } from '../../core/types.js';
+/**
+ * <baht-repeater> — array-of-rows control (spec 01 §10). `value` is an array
+ * of row objects; every row renders the same `field.fields` sub-descriptors
+ * (one level deep — nested repeaters are skipped). Controlled like every
+ * primitive: edits emit the WHOLE array via `baht-input`; the host re-feeds.
+ */
+export declare class BahtRepeater extends BahtFieldBase {
+    /** Row-scoped errors from the host form, keyed `key[i].subKey`. */
+    rowErrors: ValidationError[];
+    /**
+     * One control per `${rowIndex}:${subKey}`, reused across renders so typing
+     * doesn't drop focus (same trick as <baht-form>, NOTES round 27). Cleared
+     * when the descriptor changes or row indexes shift (remove).
+     */
+    private controls;
+    protected willUpdate(changed: Map<PropertyKey, unknown>): void;
+    private get rows();
+    private get subFields();
+    private patchRow;
+    private addRow;
+    private removeRow;
+    private errorFor;
+    private renderSub;
+    protected renderControl(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'baht-repeater': BahtRepeater;
+    }
+}

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

@@ -1,4 +1,3 @@
-import { FieldType } from '../../core/types.js';
 export { BahtButton, type ButtonVariant, type ButtonSize } from './baht-button.js';
 export { renderIcon, isIconName, type IconName } from './icons.js';
 export { BahtBadge, type BadgeTone } from './baht-badge.js';
@@ -42,5 +41,5 @@ export { BahtEmptyState } from './baht-empty-state.js';
 export { BahtErrorState } from './baht-error-state.js';
 export { BahtKeyvalueEditor } from './baht-keyvalue-editor.js';
 export { BahtReferencePicker, type ReferenceOption } from './baht-reference-picker.js';
-/** field descriptor `type` -> primitive tag (used by <baht-form> and the builder). */
-export declare const TAG_FOR_TYPE: Record<FieldType, string>;
+export { BahtRepeater } from './baht-repeater.js';
+export { TAG_FOR_TYPE } from './tag-map.js';

package/dist/components/primitives/tag-map.d.ts

@@ -0,0 +1,7 @@
+import { FieldType } from '../../core/types.js';
+/**
+ * field descriptor `type` -> primitive tag (used by <baht-form>, <baht-repeater>
+ * and the builder). Lives in its own module so baht-repeater can read it
+ * without importing the primitives barrel (which would be circular).
+ */
+export declare const TAG_FOR_TYPE: Record<FieldType, string>;

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

@@ -0,0 +1,48 @@
+export interface MessageCatalog {
+    required: string;
+    minLength: string;
+    maxLength: string;
+    min: string;
+    max: string;
+    pattern: string;
+    email: string;
+    compareEq: string;
+    compareNe: string;
+    compareGt: string;
+    compareGte: string;
+    compareLt: string;
+    compareLte: string;
+    addRow: string;
+    removeRow: string;
+    minRows: string;
+    maxRows: string;
+    next: string;
+    submit: string;
+    back: string;
+    step: string;
+    approve: string;
+    reject: string;
+    decision: string;
+    comment: string;
+    commentRequiredSuffix: string;
+    decisionRequired: string;
+    commentRequired: string;
+    nothingToReview: string;
+    yes: string;
+    no: string;
+    emptyValue: string;
+}
+export type MessageKey = keyof MessageCatalog;
+export type Locale = 'en' | 'th';
+/**
+ * Switch every built-in string to a locale, optionally patching single keys:
+ *
+ *   setLocale('th')                              // all Thai
+ *   setLocale('th', { required: 'ห้ามว่าง' })    // Thai + one custom message
+ *
+ * Global and synchronous — set it before mounting (or before validating on
+ * the server). Components read the catalog at render time.
+ */
+export declare function setLocale(locale: Locale, overrides?: Partial<MessageCatalog>): void;
+/** Resolve one catalog string, interpolating `{param}` placeholders. */
+export declare function t(key: MessageKey, params?: Record<string, unknown>): string;

package/dist/core/index.d.ts

@@ -2,6 +2,9 @@ export * from './types.js';
 export { defaultValue } from './defaults.js';
 export { approvalFields } from './approval.js';
 export { validateField } from './validators.js';
+export { resolveViewFields } from './views.js';
+export { setLocale, t } from './i18n.js';
+export type { Locale, MessageCatalog, MessageKey } from './i18n.js';
 export { evaluate } from './engine/evaluate.js';
 export { evalCondition, readRef } from './engine/conditions.js';
 export { evalValueExpr } from './engine/expressions.js';

package/dist/core/types.d.ts

@@ -1,15 +1,24 @@
 /** Control types supported by v1 (spec 01 §2). */
-export type FieldType = 'text' | 'textarea' | 'number' | 'email' | 'dropdown' | 'multiselect' | 'checkbox' | 'radio' | 'toggle' | 'date' | 'file' | 'label';
+export type FieldType = 'text' | 'textarea' | 'number' | 'email' | 'dropdown' | 'multiselect' | 'checkbox' | 'radio' | 'toggle' | 'date' | 'file' | 'label' | 'repeater';
 export type FieldWidth = '1/4' | '1/2' | '3/4' | 'full';
 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;
@@ -37,14 +54,30 @@ export interface FieldDescriptor {
     maxSize?: number;
     text?: string;
     variant?: string;
+    fields?: FieldDescriptor[];
+    minRows?: number;
+    maxRows?: number;
+    addLabel?: string;
     validators?: ValidatorSpec[];
     formatter?: string;
 }
+/**
+ * A named, client-side-only projection of a form: which fields to show, in
+ * what order (e.g. per user role). Display sugar only — the submit payload is
+ * always the full form and the server always validates the complete schema.
+ */
+export interface FormViewSpec {
+    name: string;
+    /** field keys included, in display order; keys absent from field_data are ignored */
+    fields: string[];
+}
 /** A Form definition — consumed standalone by <baht-form> (spec 00 §4.1). */
 export interface FormDefinition {
     formId: string;
     formName: string;
     field_data: FieldDescriptor[];
+    /** Optional named display subsets; select one via <baht-form view="...">. */
+    views?: FormViewSpec[];
 }
 export type ApprovalDecision = 'approved' | 'rejected';
 /** Comment box policy on an approval step. */
@@ -73,6 +106,8 @@ export interface WorkflowForm extends FormDefinition {
      */
     kind?: 'form' | 'approval';
     approval?: ApprovalConfig;
+    /** Name of one of this form's `views` to render for this step (display only). */
+    view?: 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. */
@@ -136,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,5 +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).
+ * `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/core/views.d.ts

@@ -0,0 +1,12 @@
+import { FieldDescriptor, FormDefinition } from './types.js';
+/**
+ * Resolve the fields a consumer of `form` should DISPLAY. Views are
+ * client-side projections only — data and server validation always cover the
+ * full form.
+ *
+ * - No `view` → every field, sorted by `order` (the full form).
+ * - A known view → only its fields, in the order the view lists them.
+ * - An unknown view → `null`; the caller decides the fallback (<baht-form>
+ *   warns and shows the full form).
+ */
+export declare function resolveViewFields(form: FormDefinition, view?: string): FieldDescriptor[] | null;