@xmesh/system-design 0.0.3 → 0.0.5

package/dist/lit/components/multi-select/index.js

@@ -0,0 +1,497 @@
+/*
+  multi-select/index.ts — <xm-multi-select>, a multiple-value picker (Component-
+  Capability Epic 2, ADR 0014).
+
+  A DEDICATED element (not an xm-select mode — xm-select stays single-value, ADR
+  0014) that composes the inherited foundations and re-implements none of them:
+    • XmField — label / helper / error / required / disabled / focus ring / form
+      association / ARIA association chrome (AD-7).
+    • xm-overlay — the anchored, non-modal listbox panel (AD-5 / AD-12); driven
+      through its PUBLIC API only (mode / tier / placement / .anchor / .opener /
+      xm-overlay-close). Its shadow root is never touched.
+    • xm-checkbox — the per-option selected indicator, rendered PRESENTATIONALLY
+      (`inert` + pointer-events:none): the row owns the click and the a11y, the
+      checkbox only reflects `checked`. A presentational checkbox is never toggled
+      so it never goes dirty, and XmField's uncontrolled-first re-seed keeps its
+      box in sync with `?checked` on every render.
+    • xm-text-field — an optional in-panel search that filters by label substring.
+
+  Value contract (AD-6a / AD-8a): form-associated, multiple selection. `selectedValues`
+  returns the typed Array<primitive>; `change` carries that array in detail.value
+  (never option objects). Form serialization is multiple FormData entries under `name`
+  (matching native <select multiple>); the inherited string `value` mirrors a
+  comma-joined view so plain consumers still read something stable.
+
+  `max` caps the selection: at the cap, unselected options disable (can't grow) while
+  selected options stay removable.
+
+  Keyboard (WAI-ARIA listbox APG, AD-9a): focus stays on the combobox trigger,
+  consistent with xm-select. Closed → Enter/Space/↓ opens; open → ↑/↓ move the active
+  option (skipping disabled + filtered-out), Home/End jump, type-ahead matches labels,
+  Enter/Space TOGGLE the active option and keep the list open (multi), Esc closes
+  (routed through the overlay's innermost-Esc). The search box is pointer-operated;
+  ↑/↓/Enter inside it bridge focus back to the trigger so pointer+keyboard mix cleanly.
+
+  Shadow DOM. Lit is a bare `import` (peer dep). The composed element modules are
+  imported for their registration side-effects, so importing only this element is a
+  self-sufficient drop-in.
+*/
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing } from "lit";
+import { customElement, property, state, query } from "lit/decorators.js";
+import { XmField } from "../field/index.js";
+import "../overlay/index.js";
+import "../checkbox/index.js";
+import "../text-field/index.js";
+import primitivesSheets from "../primitives/index.styles.js";
+import fieldSheets from "../field/index.styles.js";
+import multiSelectSheets from "./index.styles.js";
+/**
+ * @fires change - Fired on every toggle; `detail.value` is the full selection as an Array<primitive>.
+ */
+let XmMultiSelect = class XmMultiSelect extends XmField {
+    constructor() {
+        super(...arguments);
+        /** The option model — `{ label, value, disabled? }` shared with xm-select / radio-group. */
+        this.options = [];
+        /** Shown on the trigger when nothing is selected. */
+        this.placeholder = "Select…";
+        /** Selection cap (0 = uncapped). At the cap, unselected options disable; selected stay removable. */
+        this.max = 0;
+        /** Render the in-panel search filter. */
+        this.searchable = true;
+        this._open = false;
+        this._activeIndex = -1;
+        this._selected = new Set();
+        this._query = "";
+        this._typeahead = "";
+        this._typeaheadTimer = 0;
+        // ── Open / close ────────────────────────────────────────────────────
+        this._onDocPointerDown = (e) => {
+            if (!this._open)
+                return;
+            if (!e.composedPath().includes(this))
+                this._closeList(false);
+        };
+        this._onOverlayClose = (e) => {
+            const detail = e.detail;
+            if (this._open) {
+                this._open = false;
+                this._activeIndex = -1;
+                this._query = "";
+                document.removeEventListener("pointerdown", this._onDocPointerDown, true);
+                if (detail?.reason !== "escape")
+                    this._control?.focus();
+            }
+        };
+        // ── Keyboard (listbox APG) ──────────────────────────────────────────
+        this._onControlKeydown = (e) => {
+            if (this.nonInteractive)
+                return;
+            if (!this._open) {
+                if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
+                    e.preventDefault();
+                    // Opening must not also submit a surrounding xm-form.
+                    e.stopPropagation();
+                    this._openList();
+                }
+                return;
+            }
+            this._onListKeydown(e);
+        };
+        // Inside the pointer-operated search box: bridge arrow/enter back to the trigger so
+        // a keyboard user who landed in the search can navigate + toggle without Tab gymnastics.
+        this._onSearchKeydown = (e) => {
+            switch (e.key) {
+                case "ArrowDown":
+                    e.preventDefault();
+                    this._control?.focus();
+                    this._activeIndex = this._nextNavigable(this._activeIndex, 1);
+                    break;
+                case "ArrowUp":
+                    e.preventDefault();
+                    this._control?.focus();
+                    this._activeIndex = this._nextNavigable(this._activeIndex, -1);
+                    break;
+                case "Enter":
+                    e.preventDefault();
+                    e.stopPropagation();
+                    if (this._activeIndex >= 0)
+                        this._toggleIndex(this._activeIndex);
+                    break;
+            }
+        };
+        this._onSearchInput = (e) => {
+            this._query = e.detail?.value ?? "";
+            // Keep the active option valid after the visible set narrows.
+            if (this._activeIndex >= 0 && !this._navigable.includes(this._activeIndex)) {
+                this._activeIndex = this._navigable[0] ?? -1;
+            }
+        };
+    }
+    // Adopted from build-generated sheets (gen-styles.mjs) — no runtime URL fetch
+    // (ADR 0012). Lit static styles don't merge on override, so subclasses re-include
+    // the chrome (primitives + field) sheets.
+    static { this.styles = [...primitivesSheets, ...fieldSheets, ...multiSelectSheets]; }
+    connectedCallback() {
+        super.connectedCallback();
+        this._seedFromValue();
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // When options arrive after the value seed, resolve the seed once.
+        if (changed.has("options") && !this._dirty && this._selected.size === 0) {
+            this._seedFromValue();
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        document.removeEventListener("pointerdown", this._onDocPointerDown, true);
+    }
+    updated(changed) {
+        super.updated?.(changed);
+        if (this._open &&
+            changed.has("_activeIndex") &&
+            this._activeIndex >= 0) {
+            this.renderRoot
+                .querySelector(".multi-select__option--active")
+                ?.scrollIntoView({ block: "nearest" });
+        }
+    }
+    // ── Public value accessors ──────────────────────────────────────────
+    /** The selected primitives, in option order. The typed multi-value accessor
+        (the inherited string `value` stays a comma-joined mirror for plain consumers). */
+    get selectedValues() {
+        return this.options
+            .filter((o) => this._selected.has(o.value))
+            .map((o) => o.value);
+    }
+    // ── Selection state ─────────────────────────────────────────────────
+    // Seed selection from the uncontrolled `value` attribute — a comma-separated list (AD-6).
+    _seedFromValue() {
+        if (this._dirty || this.initialValue === "")
+            return;
+        const wanted = this.initialValue
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (wanted.length === 0)
+            return;
+        const next = new Set();
+        for (const opt of this.options) {
+            if (wanted.includes(String(opt.value)))
+                next.add(opt.value);
+        }
+        if (next.size > 0) {
+            this._selected = next;
+            this._syncForm();
+        }
+    }
+    get _q() {
+        return this._query.trim().toLowerCase();
+    }
+    _matches(opt) {
+        return !this._q || opt.label.toLowerCase().includes(this._q);
+    }
+    get _atCap() {
+        return this.max > 0 && this._selected.size >= this.max;
+    }
+    _optDisabled(opt) {
+        return !!opt.disabled || (this._atCap && !this._selected.has(opt.value));
+    }
+    /** Original indices of options that are visible (match the query) AND togglable. */
+    get _navigable() {
+        return this.options
+            .map((opt, i) => (this._matches(opt) && !this._optDisabled(opt) ? i : -1))
+            .filter((i) => i !== -1);
+    }
+    get _visibleCount() {
+        return this.options.reduce((n, o) => (this._matches(o) ? n + 1 : n), 0);
+    }
+    _nextNavigable(from, dir) {
+        const nav = this._navigable;
+        if (nav.length === 0)
+            return -1;
+        const pos = nav.indexOf(from);
+        if (pos === -1)
+            return dir === 1 ? nav[0] : nav[nav.length - 1];
+        return nav[(pos + dir + nav.length) % nav.length];
+    }
+    // ── Commit ──────────────────────────────────────────────────────────
+    _toggleValue(value) {
+        if (this.nonInteractive)
+            return;
+        if (this._selected.has(value)) {
+            this._selected.delete(value);
+        }
+        else {
+            if (this._atCap)
+                return;
+            this._selected.add(value);
+        }
+        this._selected = new Set(this._selected);
+        // Mark touched so the base's uncontrolled-first re-seed can't clobber the set.
+        this._dirty = true;
+        this._syncForm();
+        this._emitChange();
+    }
+    _toggleIndex(i) {
+        const opt = this.options[i];
+        if (!opt || this._optDisabled(opt))
+            return;
+        this._activeIndex = i;
+        this._toggleValue(opt.value);
+    }
+    // Multiple FormData entries under `name` (native <select multiple> parity, AD-6a);
+    // the inherited string `value` mirrors a comma-joined view.
+    _syncForm() {
+        this._value = this.selectedValues.map(String).join(",");
+        const fd = new FormData();
+        if (this.name) {
+            for (const v of this.selectedValues)
+                fd.append(this.name, String(v));
+        }
+        this.internals.setFormValue(fd);
+    }
+    _emitChange() {
+        this.dispatchEvent(new CustomEvent("change", {
+            bubbles: true,
+            composed: true,
+            detail: { value: this.selectedValues },
+        }));
+    }
+    _openList() {
+        if (this.nonInteractive || this._open)
+            return;
+        this._open = true;
+        document.addEventListener("pointerdown", this._onDocPointerDown, true);
+        this._activeIndex = this._navigable[0] ?? -1;
+        this.updateComplete.then(() => {
+            const ov = this._overlay;
+            const ctrl = this._control;
+            if (ov && ctrl) {
+                ov.anchor = ctrl;
+                ov.opener = ctrl;
+                ov.show();
+            }
+        });
+    }
+    _closeList(focusControl = true) {
+        if (!this._open)
+            return;
+        this._open = false;
+        this._activeIndex = -1;
+        this._query = "";
+        document.removeEventListener("pointerdown", this._onDocPointerDown, true);
+        const ov = this._overlay;
+        if (ov?.open)
+            ov.hide("api");
+        if (focusControl)
+            this._control?.focus();
+    }
+    _onListKeydown(e) {
+        const nav = this._navigable;
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                this._activeIndex = this._nextNavigable(this._activeIndex, 1);
+                break;
+            case "ArrowUp":
+                e.preventDefault();
+                this._activeIndex = this._nextNavigable(this._activeIndex, -1);
+                break;
+            case "Home":
+                e.preventDefault();
+                this._activeIndex = nav[0] ?? -1;
+                break;
+            case "End":
+                e.preventDefault();
+                this._activeIndex = nav[nav.length - 1] ?? -1;
+                break;
+            case "Enter":
+            case " ":
+                // Toggle the active option; stay open (multi). Don't bubble to xm-form.
+                e.preventDefault();
+                e.stopPropagation();
+                if (this._activeIndex >= 0)
+                    this._toggleIndex(this._activeIndex);
+                break;
+            case "Tab":
+                this._closeList(false);
+                break;
+            // Esc handled by the overlay (innermost-only) → _onOverlayClose syncs us.
+            default:
+                if (e.key.length === 1 && !e.metaKey && !e.ctrlKey && !e.altKey) {
+                    this._typeAhead(e.key);
+                }
+        }
+    }
+    _typeAhead(char) {
+        window.clearTimeout(this._typeaheadTimer);
+        this._typeahead += char.toLowerCase();
+        this._typeaheadTimer = window.setTimeout(() => {
+            this._typeahead = "";
+        }, 500);
+        const match = this._navigable.find((i) => this.options[i].label.toLowerCase().startsWith(this._typeahead));
+        if (match !== undefined)
+            this._activeIndex = match;
+    }
+    // ── Render ──────────────────────────────────────────────────────────
+    renderControl() {
+        const a = this.controlAria;
+        const count = this._selected.size;
+        const activeId = this._open && this._activeIndex >= 0
+            ? `${a.id}-opt-${this._activeIndex}`
+            : nothing;
+        return html `
+      <button
+        type="button"
+        class="multi-select__control"
+        id=${a.id}
+        role="combobox"
+        aria-haspopup="listbox"
+        aria-expanded=${this._open ? "true" : "false"}
+        aria-controls="${a.id}-listbox"
+        aria-activedescendant=${activeId}
+        aria-describedby=${a.describedBy}
+        aria-invalid=${a.invalid ?? "false"}
+        aria-required=${a.required ?? nothing}
+        ?disabled=${this.effectiveDisabled}
+        @click=${() => (this._open ? this._closeList(true) : this._openList())}
+        @keydown=${this._onControlKeydown}
+      >
+        <span
+          class="multi-select__value ${count === 0
+            ? "multi-select__value--placeholder"
+            : ""}"
+        >
+          ${count === 0 ? this.placeholder : `${count} selected`}
+        </span>
+        <span
+          class="multi-select__chevron ${this._open
+            ? "multi-select__chevron--open"
+            : ""}"
+        >
+          <xm-chevron-down-icon size="16"></xm-chevron-down-icon>
+        </span>
+      </button>
+
+      <xm-overlay
+        mode="non-modal"
+        tier="menu"
+        placement="bottom-start"
+        label=${this.label || "Options"}
+        @xm-overlay-close=${this._onOverlayClose}
+      >
+        ${this._open
+            ? html `<div class="multi-select__panel">
+              ${this.searchable
+                ? html `<xm-text-field
+                    class="multi-select__search"
+                    size="sm"
+                    placeholder="Search…"
+                    aria-label="Filter options"
+                    @input=${this._onSearchInput}
+                    @keydown=${this._onSearchKeydown}
+                  ></xm-text-field>`
+                : nothing}
+
+              <ul
+                class="multi-select__listbox"
+                id="${a.id}-listbox"
+                role="listbox"
+                aria-multiselectable="true"
+                aria-label=${this.label || "Options"}
+                @keydown=${(e) => this._onListKeydown(e)}
+              >
+                ${this.options.map((opt, i) => this._renderOption(opt, i, a.id))}
+                ${this._visibleCount === 0
+                ? html `<li class="multi-select__empty" role="presentation">
+                      No matches
+                    </li>`
+                : nothing}
+              </ul>
+            </div>`
+            : nothing}
+      </xm-overlay>
+    `;
+    }
+    _renderOption(opt, index, baseId) {
+        if (!this._matches(opt))
+            return html `${nothing}`;
+        const selected = this._selected.has(opt.value);
+        const disabled = this._optDisabled(opt);
+        const active = index === this._activeIndex;
+        const cls = [
+            "multi-select__option",
+            active ? "multi-select__option--active" : "",
+            disabled ? "multi-select__option--disabled" : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        return html `
+      <li
+        class="${cls}"
+        id="${baseId}-opt-${index}"
+        role="option"
+        aria-selected=${selected ? "true" : "false"}
+        aria-disabled=${disabled ? "true" : nothing}
+        @click=${() => this._toggleIndex(index)}
+        @mousemove=${() => {
+            if (!disabled)
+                this._activeIndex = index;
+        }}
+      >
+        <xm-checkbox
+          class="multi-select__check"
+          ?checked=${selected}
+          inert
+          aria-hidden="true"
+        ></xm-checkbox>
+        <span class="multi-select__option-label">${opt.label}</span>
+      </li>
+    `;
+    }
+};
+__decorate([
+    property({ attribute: false })
+], XmMultiSelect.prototype, "options", void 0);
+__decorate([
+    property({ type: String })
+], XmMultiSelect.prototype, "placeholder", void 0);
+__decorate([
+    property({ type: Number })
+], XmMultiSelect.prototype, "max", void 0);
+__decorate([
+    property({ type: Boolean })
+], XmMultiSelect.prototype, "searchable", void 0);
+__decorate([
+    state()
+], XmMultiSelect.prototype, "_open", void 0);
+__decorate([
+    state()
+], XmMultiSelect.prototype, "_activeIndex", void 0);
+__decorate([
+    state()
+], XmMultiSelect.prototype, "_selected", void 0);
+__decorate([
+    state()
+], XmMultiSelect.prototype, "_query", void 0);
+__decorate([
+    query(".multi-select__control")
+], XmMultiSelect.prototype, "_control", void 0);
+__decorate([
+    query("xm-overlay")
+], XmMultiSelect.prototype, "_overlay", void 0);
+__decorate([
+    query(".multi-select__search")
+], XmMultiSelect.prototype, "_search", void 0);
+XmMultiSelect = __decorate([
+    customElement("xm-multi-select")
+], XmMultiSelect);
+export { XmMultiSelect };

package/dist/lit/components/multi-select/index.styles.js

@@ -0,0 +1,170 @@
+// GENERATED by scripts/gen-styles.mjs — do not edit. Source: lit/components/multi-select/index.css
+// SSR-safe: constructable stylesheets need the DOM, so in a non-DOM context
+// (Node/SSR import) this exports [] instead of throwing. The CSS self-declares
+// the @layer order so the override contract holds even without ./base (AD-2).
+let sheets = [];
+if (typeof CSSStyleSheet !== "undefined") {
+  const sheet = new CSSStyleSheet();
+  sheet.replaceSync(`@layer reset, base, tokens, components, utilities;
+@layer components {
+/* ============================================
+   xm-multi-select — multiple-value picker for XmField (Component-Capability
+   Epic 2, ADR 0014).
+
+   Composes XmField (chrome) + xm-overlay (anchored panel) + xm-checkbox (the
+   per-option selected indicator) + xm-text-field (search). This file styles ONLY
+   the bespoke parts: the closed trigger (a full-bleed <button> inside the base's
+   .field__control wrapper), the chevron, and the panel content (search + listbox)
+   projected into the overlay. Positioning / elevation of the panel is owned by
+   xm-overlay; the option checkbox visual is owned by xm-checkbox.
+
+   Surface & ink (AD-13):
+     • Closed trigger rides the inverse-surface card tier → inverse-on-surface ink,
+       inverse-on-surface-muted for the placeholder.
+     • The panel rows sit on the overlay's inverse-surface panel → ink stays
+       inverse-on-surface; hover/active uses the MD3 state layer.
+     • Selection is carried by the row's xm-checkbox (coral fill), NOT a row tint —
+       so the active (keyboard/hover) highlight never double-signals with selection.
+
+   BEM block: \`multi-select\`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+/* ---------- Closed trigger — full-bleed button in the field wrapper ---------- */
+.multi-select__control {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  flex: 1;
+  min-width: 0;
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  appearance: none;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: var(--md-sys-color-inverse-on-surface);
+  font:
+    var(--md-sys-typescale-body-large-weight)
+    var(--md-sys-typescale-body-large-size) /
+    var(--md-sys-typescale-body-large-line-height)
+    var(--md-sys-typescale-body-large-font);
+  padding: 0 var(--s-3);
+  text-align: left;
+  cursor: pointer;
+}
+.multi-select__control:disabled {
+  cursor: not-allowed;
+}
+
+/* ---------- Value / placeholder ---------- */
+.multi-select__value {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.multi-select__value--placeholder {
+  color: var(--xm-color-inverse-on-surface-muted);
+}
+
+/* ---------- Chevron — rotates on open (short3, standard) ---------- */
+.multi-select__chevron {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--md-sys-color-inverse-on-surface);
+  transition: transform var(--md-sys-motion-duration-short3)
+    var(--md-sys-motion-easing-standard);
+}
+.multi-select__chevron--open {
+  transform: rotate(180deg);
+}
+
+/* ---------- Panel (inside the overlay): search + listbox ---------- */
+.multi-select__panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-2);
+  min-width: 220px;
+}
+.multi-select__search {
+  display: block;
+  width: 100%;
+}
+
+/* ---------- Listbox ---------- */
+.multi-select__listbox {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-0-5);
+  max-height: 280px;
+  overflow-y: auto;
+}
+
+/* ---------- Option rows ---------- */
+.multi-select__option {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  padding: var(--s-1) var(--s-2);
+  border-radius: var(--md-sys-shape-corner-small);
+  color: var(--md-sys-color-inverse-on-surface);
+  font:
+    var(--md-sys-typescale-body-medium-weight)
+    var(--md-sys-typescale-body-medium-size) /
+    var(--md-sys-typescale-body-medium-line-height)
+    var(--md-sys-typescale-body-medium-font);
+  cursor: pointer;
+  user-select: none;
+}
+.multi-select__option-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* The option checkbox is presentational — the row owns the click + a11y. */
+.multi-select__check {
+  flex-shrink: 0;
+  pointer-events: none;
+}
+
+/* Active (keyboard / pointer hover) — the MD3 state layer over the panel ink. */
+.multi-select__option--active {
+  background: color-mix(
+    in oklab,
+    var(--md-sys-color-inverse-on-surface)
+      var(--md-sys-state-hover-state-layer-opacity),
+    transparent
+  );
+}
+
+/* Disabled option (explicitly disabled, or unselected at the \`max\` cap). */
+.multi-select__option--disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* ---------- Empty (no search matches) ---------- */
+.multi-select__empty {
+  list-style: none;
+  padding: var(--s-2) var(--s-2);
+  color: var(--xm-color-inverse-on-surface-muted);
+  font:
+    var(--md-sys-typescale-body-medium-weight)
+    var(--md-sys-typescale-body-medium-size) /
+    var(--md-sys-typescale-body-medium-line-height)
+    var(--md-sys-typescale-body-medium-font);
+}
+
+}`);
+  sheets = [sheet];
+}
+export default sheets;

package/dist/lit/components/navigation-drawer/index.d.ts

@@ -1,6 +1,10 @@
 import { LitElement } from "lit";
 import type { PropertyValues, TemplateResult } from "lit";
-declare class XmNavigationDrawer extends LitElement {
+/**
+ * @fires close - Fired when the element requests to close.
+ */
+export declare class XmNavigationDrawer extends LitElement {
+    static styles: CSSStyleSheet[];
     static shadowRootOptions: ShadowRootInit;
     open: boolean;
     collapsed: boolean;
@@ -26,4 +30,3 @@ declare global {
         "xm-navigation-drawer": XmNavigationDrawer;
     }
 }
-export {};