bank20baht-ui 0.10.0 → 0.11.0

package/README.md

@@ -154,7 +154,7 @@ 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.
+The `/builder` page of the docs site (`bun run --filter docs dev`) shows the same flow live.
 
 ### i18n — Thai (or any) built-in strings
 
@@ -261,7 +261,7 @@ near-black ink (`#171717`) on white, hairline neutral borders, 44px controls, on
 (`#444FBF`), status as tint pills, hand-drawn koboyo spot illustrations for empty /
 error / upload states, IBM Plex Sans Thai / IBM Plex Mono (load the
 fonts yourself), borders-over-shadows, "paper" easing — plus an opt-in dark theme
-(`<html data-baht-theme="dark">`). 35+ components:
+(`<html data-baht-theme="dark">`). 58 elements:
 
 ```html
 <baht-button variant="secondary" size="sm">Cancel</baht-button>
@@ -275,10 +275,13 @@ fonts yourself), borders-over-shadows, "paper" easing — plus an opt-in dark th
 - **Feedback** — `baht-modal` · `baht-toast` · `baht-alert` · `baht-tooltip` · `baht-progress` ·
   `baht-spinner` · `baht-skeleton`
 - **Inputs** — `baht-rating` · `baht-range` · `baht-otp` · `baht-typeahead` · `baht-reference-picker` ·
-  `baht-keyvalue-editor` (+ the 11 form field primitives). Typed fields debounce keystrokes (150 ms,
-  `debounce` / `options.inputDebounce`); `dropdown` renders its own listbox, never the OS picker.
-- **Structure & nav** — `baht-card` · `baht-fieldset` · `baht-timeline` · `baht-accordion` ·
-  `baht-link` · `baht-breadcrumbs`
+  `baht-keyvalue-editor` · `baht-upload` (+ the 15 form field primitives). Typed fields debounce keystrokes
+  (150 ms, `debounce`); `dropdown` renders its own listbox, never the OS picker.
+- **Stats & charts** — `baht-stat` · `baht-stat-chart` · `baht-meter` · `baht-sparkline` · `baht-bar-chart` ·
+  `baht-line-chart` · `baht-donut-chart` · `baht-heatmap` · `baht-progress-ring`
+- **Structure & nav** — `baht-card` · `baht-fieldset` · `baht-timeline` · `baht-accordion` · `baht-steps` ·
+  `baht-link` · `baht-breadcrumbs` · `baht-avatar` · `baht-code` · `baht-empty-state` · `baht-error-state` ·
+  `baht-loading-overlay`
 
 ## Theming — design tokens + light DOM
 
@@ -305,7 +308,7 @@ Full reference: [docs/theming.md](./docs/theming.md).
 // 1. per-element subpath — one module per tag, plus only what it imports
 import 'bank20baht-ui/components/button'; // <baht-button>
 import { BahtTable } from 'bank20baht-ui/components/table';
-import 'bank20baht-ui/components/form'; // <baht-form> + the 14 field primitives
+import 'bank20baht-ui/components/form'; // <baht-form> + the 15 field primitives
 import 'bank20baht-ui/components/workflow';
 
 // 2. by tag list — each tag is a dynamic import, fetched on demand
@@ -344,7 +347,7 @@ no hand-written type declarations in your app:
 | **Angular** | template binding on properties/events | `CUSTOM_ELEMENTS_SCHEMA`, see below |
 | **Vue 3** | keep Vue from treating `baht-*` as components | `isCustomElement`, see below |
 | **Phoenix / Rails / plain HTML** | it's just HTML — works as-is | none |
-| **Tooling** (Storybook, docgen, custom) | machine-readable API of all 36 elements | read `dist/custom-elements.json` ([CEM standard](https://github.com/webcomponents/custom-elements-manifest)) |
+| **Tooling** (Storybook, docgen, custom) | machine-readable API of all 58 elements | read `dist/custom-elements.json` ([CEM standard](https://github.com/webcomponents/custom-elements-manifest)) |
 
 **VS Code** — `.vscode/settings.json`:
 
@@ -400,21 +403,20 @@ import 'bank20baht-ui';
 `@lit-labs/ssr` is an optional peer dependency (server only). Full guide, limitations
 (light-DOM children, ids, i18n locale) and troubleshooting: [docs/ssr.md](./docs/ssr.md).
 
-## Docs, Storybook, examples
+## Docs
 
-- **Per-component docs**: [`docs/`](./docs/README.md) — one .md per component + framework
-  guides (vanilla / React / Angular).
-- **Storybook**: `pnpm --filter storybook-bahtui dev` → http://localhost:6006.
-- **Copy-out starters**: `examples/vanilla`, `examples/react`, `examples/angular` at the
-  repo root — same workflow JSON in three hosts.
+- **Per-component docs**: [`docs/`](./docs/README.md) — one .md per element + framework
+  guides (vanilla / React / Angular) + theming + SSR.
+- **Docs site with live specimens**: https://bahtui-docs.pages.dev (source: `apps/docs`).
+- **For agents**: the `bahtui-mcp` server (`apps/mcp`) serves these docs and runs the engine on your JSON.
 
-## Field types (13)
+## Field types (17)
 
-`text · textarea · number · email · password · dropdown · multiselect · checkbox · radio · toggle · date ·
-file (capture only, no upload) · label (static)`
+`text · textarea · number · currency · email · password · dropdown · multiselect · tags · checkbox · radio ·
+toggle · date · file · repeater (one level of rows) · label (static) · section (divider)`
 
 Each field descriptor: `{ order, type, key, label, placeholder, width: '1/4'|'1/2'|'3/4'|'full',
-value, disabled, required, options, max_length, min, max, validators[], formatter }`.
+value, disabled, required, options | options_from, max_length, min, max, validators[], formatter, flag }`.
 
 ## Visual Builder
 

package/dist/components/baht-form.js

@@ -17,6 +17,7 @@ import "./primitives/baht-number.js";
 import "./primitives/baht-currency.js";
 import "./primitives/baht-select.js";
 import "./primitives/baht-multiselect.js";
+import "./primitives/baht-tags.js";
 import "./primitives/baht-checkbox.js";
 import "./primitives/baht-radio.js";
 import "./primitives/baht-toggle.js";

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

@@ -0,0 +1,95 @@
+import { PropertyValues, TemplateResult } from 'lit';
+import { BahtFieldBase } from '../field-base.js';
+/**
+ * Creatable chip input: value is `string[]` (unique, trimmed, in entry
+ * order). Type text + Enter or comma to add a chip; Backspace on an empty
+ * input removes the last chip; pasting "a, b, c" adds three at once.
+ *
+ * Suggestions come from `field.options` — the SAME list every other
+ * option-bearing field reads, already resolved by `<baht-form>` when the
+ * descriptor uses `options_from` (spec 01 §1: dynamic options are merged
+ * into `field.options` before the primitive ever sees them, so this
+ * component needs no fetcher of its own). They filter as you type
+ * (case-insensitive, prefix matches first) and exclude tags already chosen.
+ * Free text becomes a chip unless `field.allow_new === false`, in which case
+ * only a suggestion's `key` (matched case-insensitively) can become one.
+ *
+ *   el.field = { type: 'tags', key: 'labels', options: [...], max_items: 5 };
+ *   el.addEventListener('baht-input', (e) => (draft.labels = e.detail.value));
+ *
+ * ARIA: APG editable combobox with list autocomplete, same pattern as
+ * <baht-typeahead> — the input is the combobox, the chips sit before it in
+ * the same control, `aria-activedescendant` walks the listbox.
+ */
+export declare class BahtTags extends BahtFieldBase {
+    private inputText;
+    private open;
+    private activeIndex;
+    /** Transient reason the last chip attempt was refused (max_length /
+     *  max_items / allow_new / duplicate) — cleared on the next successful
+     *  add or edit, never persisted, never blocks anything by itself. */
+    private hint;
+    private inputEl;
+    private readonly onDocMousedown;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /** The host value as canonical tags — a store/host can hand in anything
+     *  (`[1, null]`), and a non-string entry must not crash the render. */
+    private get tags();
+    /** A chip shows the matching option's label when the tag happens to be one
+     *  (case-insensitive) — same fallback the readonly display (`displayValue`)
+     *  already applies; free text with no match shows as typed. */
+    private chipLabel;
+    private get maxLength();
+    private get allowNew();
+    private get suggestions();
+    /** Same id the base label's `for` points at — clicking the field label
+     *  focuses the input natively, no click handler of our own needed. */
+    private get inputId();
+    private get listboxId();
+    private get hintId();
+    /** Base `describedBy` (error/help) plus the transient refusal hint, when
+     *  one is showing. */
+    private get controlDescribedBy();
+    private optionId;
+    /** Why `trimmed` can't join `current` right now, or null when it can —
+     *  same rules bank20baht-validator re-checks server-side. */
+    private rejectionFor;
+    /**
+     * `current` + one more chip, or the reason it was refused — null only for
+     * blank input (nothing worth reporting). Pure (no emit) so `addMany` can
+     * fold several candidates into ONE next array before telling the host,
+     * instead of racing `this.value` across several back-to-back emits.
+     */
+    private nextWithTag;
+    private hintFor;
+    /** Attempt to add one chip; returns whether it landed. A refusal shows a
+     *  brief inline hint instead of failing silently. */
+    private addTag;
+    private removeTag;
+    /** Split pasted / bulk text on commas (and newlines) into separate chips,
+     *  emitted as ONE array (see `nextWithTag`). Reports the last refusal only
+     *  when NOTHING from the paste landed. */
+    private addMany;
+    private listen;
+    private close;
+    private highlight;
+    private commitTyped;
+    private pick;
+    private onInput;
+    private onEnter;
+    private onBackspace;
+    private onArrowDown;
+    private onArrowUp;
+    private onEscape;
+    private onKeydown;
+    private onPaste;
+    private onBlur;
+    protected updated(): void;
+    protected renderControl(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'baht-tags': BahtTags;
+    }
+}

package/dist/components/primitives/baht-tags.js

@@ -0,0 +1,319 @@
+import { nothing as l, html as p } from "lit";
+import { state as d, query as f, customElement as m } from "lit/decorators.js";
+import { live as b } from "lit/directives/live.js";
+import { BahtFieldBase as v } from "../field-base.js";
+import { unlistenOutside as u, listenOutside as x, scrollOptionIntoView as w } from "./listbox.js";
+import { t as r } from "../../core/i18n.js";
+import { normalizeTagsValue as g, optionKeyLookup as I } from "../../core/validators.js";
+var $ = Object.defineProperty, y = Object.getOwnPropertyDescriptor, c = (t, e, i, s) => {
+  for (var o = s > 1 ? void 0 : s ? y(e, i) : e, n = t.length - 1, a; n >= 0; n--)
+    (a = t[n]) && (o = (s ? a(e, i, o) : a(o)) || o);
+  return s && o && $(e, i, o), o;
+};
+const T = 8;
+let h = class extends v {
+  constructor() {
+    super(...arguments), this.inputText = "", this.open = !1, this.activeIndex = -1, this.hint = null, this.onDocMousedown = (t) => {
+      this.contains(t.target) || this.close();
+    };
+  }
+  disconnectedCallback() {
+    u(this.onDocMousedown), super.disconnectedCallback();
+  }
+  willUpdate(t) {
+    super.willUpdate(t);
+    const e = t.get("field");
+    t.has("field") && e !== void 0 && e.key !== this.field.key && (this.inputText = "", this.close());
+  }
+  /** The host value as canonical tags — a store/host can hand in anything
+   *  (`[1, null]`), and a non-string entry must not crash the render. */
+  get tags() {
+    return g(this.value);
+  }
+  /** A chip shows the matching option's label when the tag happens to be one
+   *  (case-insensitive) — same fallback the readonly display (`displayValue`)
+   *  already applies; free text with no match shows as typed. */
+  chipLabel(t) {
+    const e = t.toLowerCase(), i = (this.field.options ?? []).find((s) => s.key.toLowerCase() === e);
+    return (i == null ? void 0 : i.label) ?? t;
+  }
+  get maxLength() {
+    return this.field.max_length ?? 32;
+  }
+  get allowNew() {
+    return this.field.allow_new !== !1;
+  }
+  get suggestions() {
+    const t = this.field.options ?? [], e = new Set(this.tags.map((n) => n.toLowerCase())), i = this.inputText.trim().toLowerCase(), s = [], o = [];
+    for (const n of t) {
+      if (e.has(n.key.toLowerCase())) continue;
+      if (!i) {
+        s.push(n);
+        continue;
+      }
+      const a = n.label.toLowerCase();
+      a.startsWith(i) || n.key.toLowerCase().startsWith(i) ? s.push(n) : (a.includes(i) || n.key.toLowerCase().includes(i)) && o.push(n);
+    }
+    return [...s, ...o].slice(0, T);
+  }
+  /** Same id the base label's `for` points at — clicking the field label
+   *  focuses the input natively, no click handler of our own needed. */
+  get inputId() {
+    return this.controlId;
+  }
+  get listboxId() {
+    return `${this.inputId}-list`;
+  }
+  get hintId() {
+    return `${this.inputId}-hint`;
+  }
+  /** Base `describedBy` (error/help) plus the transient refusal hint, when
+   *  one is showing. */
+  get controlDescribedBy() {
+    const t = this.describedBy, e = [t === l ? "" : t, this.hint ? this.hintId : ""].filter(Boolean);
+    return e.length > 0 ? e.join(" ") : l;
+  }
+  optionId(t) {
+    return `${this.listboxId}-${t}`;
+  }
+  /** Why `trimmed` can't join `current` right now, or null when it can —
+   *  same rules bank20baht-validator re-checks server-side. */
+  rejectionFor(t, e, i) {
+    return e.length > this.maxLength ? "tooLong" : t.some((s) => s.toLowerCase() === i) ? "duplicate" : !this.allowNew && !new Set((this.field.options ?? []).map((o) => o.key.toLowerCase())).has(i) ? "notAllowed" : this.field.max_items !== void 0 && t.length >= this.field.max_items ? "maxItems" : null;
+  }
+  /**
+   * `current` + one more chip, or the reason it was refused — null only for
+   * blank input (nothing worth reporting). Pure (no emit) so `addMany` can
+   * fold several candidates into ONE next array before telling the host,
+   * instead of racing `this.value` across several back-to-back emits.
+   */
+  nextWithTag(t, e) {
+    const i = e.trim();
+    if (!i) return null;
+    const s = i.toLowerCase(), o = this.field.options ?? [], n = I(o).get(s) ?? i, a = this.rejectionFor(t, n, s);
+    return a ? { reason: a } : { tags: g([...t, n], o) };
+  }
+  hintFor(t) {
+    switch (t) {
+      case "tooLong":
+        return r("tagTooLong", { n: this.maxLength });
+      case "duplicate":
+        return r("tagDuplicate");
+      case "notAllowed":
+        return r("tagNotAllowed");
+      case "maxItems":
+        return r("maxItems", { n: this.field.max_items });
+    }
+  }
+  /** Attempt to add one chip; returns whether it landed. A refusal shows a
+   *  brief inline hint instead of failing silently. */
+  addTag(t) {
+    const e = this.nextWithTag(this.tags, t);
+    return e ? "reason" in e ? (this.hint = this.hintFor(e.reason), !1) : (this.hint = null, this.emitInput(e.tags), !0) : !1;
+  }
+  removeTag(t) {
+    var e;
+    this.emitInput(this.tags.filter((i) => i !== t)), (e = this.inputEl) == null || e.focus();
+  }
+  /** Split pasted / bulk text on commas (and newlines) into separate chips,
+   *  emitted as ONE array (see `nextWithTag`). Reports the last refusal only
+   *  when NOTHING from the paste landed. */
+  addMany(t) {
+    let e = this.tags, i = !1, s = null;
+    for (const o of t.split(/[,\n]/)) {
+      const n = this.nextWithTag(e, o);
+      if (n) {
+        if ("reason" in n) {
+          s = n.reason;
+          continue;
+        }
+        e = n.tags, i = !0;
+      }
+    }
+    i ? (this.hint = null, this.emitInput(e)) : s && (this.hint = this.hintFor(s));
+  }
+  listen() {
+    x(this.onDocMousedown);
+  }
+  close() {
+    u(this.onDocMousedown), this.open = !1, this.activeIndex = -1;
+  }
+  highlight(t) {
+    this.activeIndex !== t && (this.activeIndex = t);
+  }
+  commitTyped() {
+    this.addTag(this.inputText) && (this.inputText = ""), this.close();
+  }
+  pick(t) {
+    var e;
+    this.addTag(t.key), this.inputText = "", this.close(), (e = this.inputEl) == null || e.focus();
+  }
+  onInput(t) {
+    this.inputText = t.target.value, this.activeIndex = -1, this.open = !0, this.hint = null, this.listen();
+  }
+  onEnter(t) {
+    t.preventDefault();
+    const e = this.open && this.activeIndex >= 0 ? this.suggestions[this.activeIndex] : void 0;
+    e ? this.pick(e) : this.commitTyped();
+  }
+  onBackspace(t) {
+    this.inputText !== "" || this.tags.length === 0 || (t.preventDefault(), this.removeTag(this.tags[this.tags.length - 1]));
+  }
+  onArrowDown(t) {
+    if (t.preventDefault(), !this.open) {
+      this.open = !0, this.listen();
+      return;
+    }
+    const e = this.suggestions.length;
+    e > 0 && (this.activeIndex = (this.activeIndex + 1) % e);
+  }
+  onArrowUp(t) {
+    t.preventDefault();
+    const e = this.suggestions.length;
+    this.open && e > 0 && (this.activeIndex = (this.activeIndex - 1 + e) % e);
+  }
+  onEscape(t) {
+    this.open && (t.preventDefault(), this.close());
+  }
+  onKeydown(t) {
+    if (!(t.isComposing || t.keyCode === 229))
+      switch (t.key) {
+        case ",":
+          t.preventDefault(), this.commitTyped();
+          break;
+        case "Enter":
+          this.onEnter(t);
+          break;
+        case "Backspace":
+          this.onBackspace(t);
+          break;
+        case "ArrowDown":
+          this.onArrowDown(t);
+          break;
+        case "ArrowUp":
+          this.onArrowUp(t);
+          break;
+        case "Escape":
+          this.onEscape(t);
+          break;
+      }
+  }
+  onPaste(t) {
+    var a;
+    const e = ((a = t.clipboardData) == null ? void 0 : a.getData("text")) ?? "";
+    if (!e.includes(",") && !e.includes(`
+`)) return;
+    t.preventDefault();
+    const i = t.target, s = i.value, o = i.selectionStart ?? s.length, n = i.selectionEnd ?? o;
+    this.addMany(s.slice(0, o) + e + s.slice(n)), this.inputText = "";
+  }
+  onBlur() {
+    this.commitTyped();
+  }
+  updated() {
+    w(this, this.open, this.activeIndex, this.optionId(this.activeIndex));
+  }
+  renderControl() {
+    const t = this.open && this.suggestions.length > 0, e = this.disabled || this.readonly;
+    return p`<div class="baht-tags${this.open ? " baht-tags--open" : ""}">
+      <div class="baht-control baht-tags-control">
+        ${this.tags.map(
+      (i) => p`<span class="baht-tag-chip">
+            <span class="baht-tag-chip-label">${this.chipLabel(i)}</span>
+            ${e ? l : p`<button
+                  type="button"
+                  class="baht-tag-chip-remove"
+                  aria-label=${r("removeTag", { tag: this.chipLabel(i) })}
+                  title=${r("removeTag", { tag: this.chipLabel(i) })}
+                  @click=${() => {
+        this.removeTag(i);
+      }}
+                >
+                  ×
+                </button>`}
+          </span>`
+    )}
+        <input
+          class="baht-tags-input"
+          id=${this.inputId}
+          type="text"
+          autocomplete="off"
+          role="combobox"
+          aria-labelledby=${this.field.label ? this.labelId : l}
+          aria-expanded=${t ? "true" : "false"}
+          aria-controls=${this.listboxId}
+          aria-autocomplete="list"
+          aria-activedescendant=${t && this.activeIndex >= 0 ? this.optionId(this.activeIndex) : l}
+          aria-invalid=${this.invalid}
+          aria-describedby=${this.controlDescribedBy}
+          placeholder=${this.tags.length === 0 ? this.field.placeholder ?? "" : ""}
+          .value=${b(this.inputText)}
+          ?disabled=${e}
+          @input=${(i) => {
+      this.onInput(i);
+    }}
+          @keydown=${(i) => {
+      this.onKeydown(i);
+    }}
+          @paste=${(i) => {
+      this.onPaste(i);
+    }}
+          @blur=${() => {
+      this.onBlur();
+    }}
+        />
+      </div>
+      ${this.hint ? p`<div class="baht-tags-hint" id=${this.hintId} role="status">${this.hint}</div>` : l}
+      <div
+        class="baht-listbox baht-tags-list"
+        id=${this.listboxId}
+        role="listbox"
+        aria-label=${this.field.label ?? ""}
+        ?hidden=${!t}
+      >
+        ${this.suggestions.map(
+      // eslint-disable-next-line lit-a11y/click-events-have-key-events -- keyboard lives on the combobox input (aria-activedescendant pattern)
+      (i, s) => p`<div
+            class="baht-listbox-option${s === this.activeIndex ? " baht-listbox-option--active" : ""}"
+            id=${this.optionId(s)}
+            role="option"
+            aria-selected=${s === this.activeIndex ? "true" : "false"}
+            data-key=${i.key}
+            @mousedown=${(o) => {
+        o.preventDefault();
+      }}
+            @mousemove=${() => {
+        this.highlight(s);
+      }}
+            @click=${() => {
+        this.pick(i);
+      }}
+          >
+            ${i.label}
+          </div>`
+    )}
+      </div>
+    </div>`;
+  }
+};
+c([
+  d()
+], h.prototype, "inputText", 2);
+c([
+  d()
+], h.prototype, "open", 2);
+c([
+  d()
+], h.prototype, "activeIndex", 2);
+c([
+  d()
+], h.prototype, "hint", 2);
+c([
+  f("input")
+], h.prototype, "inputEl", 2);
+h = c([
+  m("baht-tags")
+], h);
+export {
+  h as BahtTags
+};