bank20baht-ui 0.2.3 → 0.2.5

package/README.md

@@ -53,6 +53,13 @@ the user can only fix what they see), but `getData()` still returns the full for
 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.
 
+### Read-only display
+
+`<baht-form readonly>` shows a submission instead of editing it: values as text, option
+labels instead of keys, chips for multi-picks, Yes/No, no help text, "Not provided" for
+blanks. Same grid, same widths. `displayValue(field, value)` from `bank20baht-ui/engine`
+gives you the same formatting for tables.
+
 ### Repeater — line items / repeating rows
 
 ```js
@@ -223,6 +230,7 @@ Geist / Geist Mono, borders-over-shadows, "paper" easing — plus a dark theme
 ```
 
 - **Data (server-side paging)** — `baht-table` · `baht-list` · `baht-pagination` · `baht-filter`.
+  `baht-table` ships a ServiceNow-style column picker with dot-walking into reference columns (`requester.department`) and emits `baht-columns-change` so the host can persist the layout.
   `items` is one page; `baht-page-change` asks your app to fetch the next one.
 - **Feedback** — `baht-modal` · `baht-toast` · `baht-alert` · `baht-tooltip` · `baht-progress` ·
   `baht-spinner` · `baht-skeleton`
@@ -284,6 +292,11 @@ React 19+ sets non-string JSX props as DOM properties, so object props (`form`,
 @Component({ schemas: [CUSTOM_ELEMENTS_SCHEMA], /* … */ })
 ```
 
+Bind `readonly` as an attribute (`[attr.readonly]="x ? '' : null"`), not a property — Angular
+rewrites `[readonly]` to the native `readOnly`. Zoneless Angular may connect an element before
+binding its props; since 0.2.3 every field primitive renders empty until `field` arrives. Full
+list of gotchas: [docs/frameworks/angular.md](./docs/frameworks/angular.md#gotchas).
+
 **Vue 3** — `vite.config.ts`:
 
 ```ts

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

@@ -79,6 +79,7 @@ export declare class BahtForm extends BahtElement {
      * `renderField`/`.baht-error`). No-op for 'change'/'submit' modes. */
     private onFieldBlur;
     private renderField;
+    private renderReadonlyField;
     protected render(): TemplateResult;
 }
 declare global {

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

@@ -1,6 +1,23 @@
 import { TemplateResult } from 'lit';
 import { BahtElement } from '../base.js';
 export type CellRenderer = (value: unknown, row: Record<string, unknown>) => unknown;
+/**
+ * One column: a plain label, or a reference column with its own fields that
+ * the picker can dot-walk into (`requester.department`). Fields nest.
+ */
+export type ColumnSpec = {
+    label: string;
+    fields?: ColumnMap;
+};
+export type ColumnMap = Record<string, string | ColumnSpec>;
+/** What the picker committed: dotted keys plus the labels the header shows. */
+export type ColumnsChangeDetail = {
+    visibleColumns: string[];
+    columns: Array<{
+        key: string;
+        label: string;
+    }>;
+};
 /**
  * Server-side data table. `items` is ONE page of rows — the component never
  * slices or fetches; on `baht-page-change` the host fetches the next page and
@@ -25,9 +42,24 @@ export type CellRenderer = (value: unknown, row: Record<string, unknown>) => unk
  * Available/Selected dual-list modal (add/remove, reorder, Select all/Clear
  * all) derived from `columns` (or the first row's keys), no host wiring
  * required. Set `t.columnPicker = false` (JS property — a boolean attribute
- * can't express "off") to hide it:
+ * can't express "off") to hide it. OK emits `baht-columns-change` with the
+ * chosen keys and their labels; persist that and feed it back as
+ * `visibleColumns` to remember a person's layout:
+ *
+ *   t.addEventListener('baht-columns-change', (e) => save(e.detail.visibleColumns));
  *
- *   t.addEventListener('baht-columns-change', (e) => console.log(e.detail.visibleColumns));
+ * Dot-walking (spec: reference columns). A column may declare `fields`, in
+ * which case the picker lets the person expand it and pick a sub-field —
+ * the key becomes `requester.department`, the header reads
+ * "Requested by › Department", and the cell resolves the path on the row.
+ * Rows whose values are plain objects get the same treatment automatically
+ * when no `columns` map is given.
+ *
+ *   t.columns = {
+ *     number: 'Number',
+ *     requester: { label: 'Requested by', fields: { name: 'Name', department: 'Department' } },
+ *   };
+ *   t.visibleColumns = ['number', 'requester.name'];
  *
  * `visibleColumns` still works standalone for a host-controlled subset (no
  * refetch) — pass it explicitly and the built-in picker (if also enabled)
@@ -36,8 +68,8 @@ export type CellRenderer = (value: unknown, row: Record<string, unknown>) => unk
 export declare class BahtTable extends BahtElement {
     /** Rows of the CURRENT page. */
     items: Record<string, unknown>[];
-    /** column key -> display name; omitted = derive keys from the first row. */
-    columns: Record<string, string>;
+    /** column key -> display name, or a reference column with `fields` (property); empty = derive keys from the first row (`snake_case` -> `Title Case`). */
+    columns: ColumnMap;
     loading: boolean;
     error: boolean;
     errorMessage: string;
@@ -50,9 +82,9 @@ export declare class BahtTable extends BahtElement {
     rowKey: string;
     /** Rows emit baht-row-click + get hover/keyboard affordances. */
     clickable: boolean;
-    /** Custom cell renderers by column key (functions — a property, never JSON). */
+    /** Custom cell renderers by column key, dotted keys included (functions — a property, never JSON). */
     renderers: Record<string, CellRenderer>;
-    /** Subset + order of `columns` to render; empty/omitted = show all. */
+    /** Subset + order of columns to render (dotted keys allowed); empty/omitted = show all top-level columns. */
     visibleColumns: string[];
     /** Built-in "Columns" toggle — derives its options from `columns`/rows. Set `column-picker="false"` to hide it. */
     columnPicker: boolean;
@@ -70,22 +102,44 @@ export declare class BahtTable extends BahtElement {
     /** Highlighted (not yet moved) options in each list. */
     private pickAvail;
     private pickSel;
+    /** Reference columns unfolded in the Available tree (dot-walk). */
+    private expanded;
     private readonly onPickerKeydown;
     disconnectedCallback(): void;
+    protected willUpdate(changed: Map<PropertyKey, unknown>): void;
+    /** The declared map, or one derived from the first row (nested objects become reference columns). */
+    private get spec();
+    /** Walk a dotted key through the spec; undefined when no such column exists. */
+    private specAt;
+    private isReference;
+    private childrenOf;
+    /** Every pickable key, reference fields included (`requester`, `requester.name`, ...). */
+    private allPaths;
     private get allColumnKeys();
     private get columnKeys();
+    /** "Requested by › Department" for a dotted key; the plain label otherwise. */
+    private labelFor;
+    /** The row's value at a dotted key (`requester.department`). */
+    private static valueAt;
     private openPicker;
     private closePicker;
     private static selectedValues;
+    private toggleAvail;
+    private toggleExpanded;
     private addToSelected;
     private removeFromSelected;
     private moveSelected;
     private confirmPicker;
-    private labelFor;
     private emitRow;
     private cell;
     private renderBody;
     private renderColumnToggle;
+    /**
+     * One row of the Available tree. A reference column gets an expander that
+     * unfolds its fields (the dot-walk); every row is a toggle button so the
+     * list works from the keyboard without the native multi-select.
+     */
+    private renderAvailRow;
     private renderColumnModal;
     protected render(): TemplateResult;
 }

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

@@ -2,7 +2,7 @@ export { BahtButton, type ButtonVariant, type ButtonSize } from './baht-button.j
 export { renderIcon, isIconName, type IconName } from './icons.js';
 export { BahtBadge, type BadgeTone } from './baht-badge.js';
 export { BahtCode, type CodeVariant } from './baht-code.js';
-export { BahtTable, type CellRenderer } from './baht-table.js';
+export { BahtTable, type CellRenderer, type ColumnMap, type ColumnSpec, type ColumnsChangeDetail, } from './baht-table.js';
 export { BahtList, type ListItem } from './baht-list.js';
 export { BahtPagination } from './baht-pagination.js';
 export { BahtModal } from './baht-modal.js';

package/dist/core/display.d.ts

@@ -0,0 +1,23 @@
+import { FieldDescriptor, FieldOption } from './types.js';
+export type DisplayValue = {
+    kind: 'empty';
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'chips';
+    items: string[];
+}
+/** Repeater rows: one entry per row, each a list of `label: value` pairs. */
+ | {
+    kind: 'rows';
+    rows: Array<Array<{
+        label: string;
+        text: string;
+    }>>;
+};
+/**
+ * The read-only rendering of one field's value. `options` overrides the
+ * descriptor's own list when they were resolved dynamically (`optionsFrom`).
+ */
+export declare function displayValue(field: FieldDescriptor, value: unknown, options?: FieldOption[] | undefined): DisplayValue;

package/dist/core/i18n.d.ts

@@ -37,6 +37,8 @@ export interface MessageCatalog {
     yes: string;
     no: string;
     emptyValue: string;
+    /** Placeholder option of a dropdown. */
+    choose: string;
     rowCount: string;
 }
 export type MessageKey = keyof MessageCatalog;

package/dist/core/index.d.ts

@@ -10,3 +10,4 @@ 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';
+export { displayValue, type DisplayValue } from './display.js';

package/dist/custom-elements.json

@@ -348,6 +348,36 @@
                   }
                 }
               ]
+            },
+            {
+              "kind": "method",
+              "name": "renderReadonlyField",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "field",
+                  "type": {
+                    "text": "FieldDescriptor"
+                  }
+                },
+                {
+                  "name": "width",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "visible",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
             }
           ],
           "events": [
@@ -8348,7 +8378,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Server-side data table. `items` is ONE page of rows — the component never\nslices or fetches; on `baht-page-change` the host fetches the next page and\nre-feeds `items`/`page`. While that fetch runs, set `loading` to show\nskeleton rows.\n\n  const t = document.querySelector('baht-table');\n  t.columns = { name: 'Name', created_at: 'Created' };\n  t.items = pageRows;                 // current page only\n  t.loading = false; t.page = 1; t.totalPages = 12;\n  t.addEventListener('baht-page-change', (e) => fetchPage(e.detail.page));\n  t.addEventListener('baht-row-click', (e) => open(e.detail.id));\n\nSet `cursor-mode` for cursor-based APIs (no total count) — the footer\nbecomes a Prev/Next pair gated by `has-next`/`has-prev`, and the host\nlistens for `baht-cursor-change` instead of `baht-page-change`:\n\n  t.cursorMode = true; t.hasNext = true; t.hasPrev = false;\n  t.addEventListener('baht-cursor-change', (e) => fetchPage(e.detail.direction));\n\nA built-in \"Columns\" button is ON by default — it opens a ServiceNow-style\nAvailable/Selected dual-list modal (add/remove, reorder, Select all/Clear\nall) derived from `columns` (or the first row's keys), no host wiring\nrequired. Set `t.columnPicker = false` (JS property — a boolean attribute\ncan't express \"off\") to hide it:\n\n  t.addEventListener('baht-columns-change', (e) => console.log(e.detail.visibleColumns));\n\n`visibleColumns` still works standalone for a host-controlled subset (no\nrefetch) — pass it explicitly and the built-in picker (if also enabled)\nstarts from that selection and keeps emitting updates for it.",
+          "description": "Server-side data table. `items` is ONE page of rows — the component never\nslices or fetches; on `baht-page-change` the host fetches the next page and\nre-feeds `items`/`page`. While that fetch runs, set `loading` to show\nskeleton rows.\n\n  const t = document.querySelector('baht-table');\n  t.columns = { name: 'Name', created_at: 'Created' };\n  t.items = pageRows;                 // current page only\n  t.loading = false; t.page = 1; t.totalPages = 12;\n  t.addEventListener('baht-page-change', (e) => fetchPage(e.detail.page));\n  t.addEventListener('baht-row-click', (e) => open(e.detail.id));\n\nSet `cursor-mode` for cursor-based APIs (no total count) — the footer\nbecomes a Prev/Next pair gated by `has-next`/`has-prev`, and the host\nlistens for `baht-cursor-change` instead of `baht-page-change`:\n\n  t.cursorMode = true; t.hasNext = true; t.hasPrev = false;\n  t.addEventListener('baht-cursor-change', (e) => fetchPage(e.detail.direction));\n\nA built-in \"Columns\" button is ON by default — it opens a ServiceNow-style\nAvailable/Selected dual-list modal (add/remove, reorder, Select all/Clear\nall) derived from `columns` (or the first row's keys), no host wiring\nrequired. Set `t.columnPicker = false` (JS property — a boolean attribute\ncan't express \"off\") to hide it. OK emits `baht-columns-change` with the\nchosen keys and their labels; persist that and feed it back as\n`visibleColumns` to remember a person's layout:\n\n  t.addEventListener('baht-columns-change', (e) => save(e.detail.visibleColumns));\n\nDot-walking (spec: reference columns). A column may declare `fields`, in\nwhich case the picker lets the person expand it and pick a sub-field —\nthe key becomes `requester.department`, the header reads\n\"Requested by › Department\", and the cell resolves the path on the row.\nRows whose values are plain objects get the same treatment automatically\nwhen no `columns` map is given.\n\n  t.columns = {\n    number: 'Number',\n    requester: { label: 'Requested by', fields: { name: 'Name', department: 'Department' } },\n  };\n  t.visibleColumns = ['number', 'requester.name'];\n\n`visibleColumns` still works standalone for a host-controlled subset (no\nrefetch) — pass it explicitly and the built-in picker (if also enabled)\nstarts from that selection and keeps emitting updates for it.",
           "name": "BahtTable",
           "members": [
             {
@@ -8364,10 +8394,10 @@
               "kind": "field",
               "name": "columns",
               "type": {
-                "text": "Record<string, string>"
+                "text": "ColumnMap"
               },
               "default": "{}",
-              "description": "column key -> display name; omitted = derive keys from the first row."
+              "description": "column key -> display name, or a reference column with `fields` (property); empty = derive keys from the first row (`snake_case` -> `Title Case`)."
             },
             {
               "kind": "field",
@@ -8460,7 +8490,7 @@
                 "text": "Record<string, CellRenderer>"
               },
               "default": "{}",
-              "description": "Custom cell renderers by column key (functions — a property, never JSON)."
+              "description": "Custom cell renderers by column key, dotted keys included (functions — a property, never JSON)."
             },
             {
               "kind": "field",
@@ -8469,7 +8499,7 @@
                 "text": "string[]"
               },
               "default": "[]",
-              "description": "Subset + order of `columns` to render; empty/omitted = show all."
+              "description": "Subset + order of columns to render (dotted keys allowed); empty/omitted = show all top-level columns."
             },
             {
               "kind": "field",
@@ -8575,12 +8605,104 @@
               "privacy": "private",
               "default": "[]"
             },
+            {
+              "kind": "field",
+              "name": "expanded",
+              "type": {
+                "text": "string[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "Reference columns unfolded in the Available tree (dot-walk)."
+            },
             {
               "kind": "field",
               "name": "onPickerKeydown",
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "spec",
+              "type": {
+                "text": "ColumnMap"
+              },
+              "privacy": "private",
+              "description": "The declared map, or one derived from the first row (nested objects become reference columns).",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "specAt",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "ColumnSpec | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "path",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Walk a dotted key through the spec; undefined when no such column exists."
+            },
+            {
+              "kind": "method",
+              "name": "isReference",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "path",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "childrenOf",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "path",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "allPaths",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string[]"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "prefix",
+                  "default": "''"
+                }
+              ],
+              "description": "Every pickable key, reference fields included (`requester`, `requester.name`, ...)."
+            },
             {
               "kind": "field",
               "name": "allColumnKeys",
@@ -8599,6 +8721,51 @@
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "method",
+              "name": "labelFor",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "path",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "\"Requested by › Department\" for a dotted key; the plain label otherwise."
+            },
+            {
+              "kind": "method",
+              "name": "valueAt",
+              "privacy": "private",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "unknown"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "row",
+                  "type": {
+                    "text": "Record<string, unknown>"
+                  }
+                },
+                {
+                  "name": "path",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "The row's value at a dotted key (`requester.department`)."
+            },
             {
               "kind": "method",
               "name": "openPicker",
@@ -8638,6 +8805,42 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "toggleAvail",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "key",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "toggleExpanded",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "key",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "addToSelected",
@@ -8686,24 +8889,6 @@
                 }
               }
             },
-            {
-              "kind": "method",
-              "name": "labelFor",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "string"
-                }
-              },
-              "parameters": [
-                {
-                  "name": "key",
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ]
-            },
             {
               "kind": "method",
               "name": "emitRow",
@@ -8780,6 +8965,31 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "renderAvailRow",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "key",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "depth",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "One row of the Available tree. A reference column gets an expander that\nunfolds its fields (the dot-walk); every row is a toggle button so the\nlist works from the keyboard without the native multi-select."
+            },
             {
               "kind": "method",
               "name": "renderColumnModal",
@@ -10086,6 +10296,30 @@
             "module": "./baht-table.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "ColumnMap",
+          "declaration": {
+            "name": "ColumnMap",
+            "module": "./baht-table.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ColumnSpec",
+          "declaration": {
+            "name": "ColumnSpec",
+            "module": "./baht-table.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ColumnsChangeDetail",
+          "declaration": {
+            "name": "ColumnsChangeDetail",
+            "module": "./baht-table.js"
+          }
+        },
         {
           "kind": "js",
           "name": "BahtList",