@xmesh/system-design 0.0.1

package/dist/lit/components/autocomplete/index.d.ts

@@ -0,0 +1,47 @@
+import type { PropertyValues, TemplateResult } from "lit";
+import { XmField } from "../field/index.js";
+import type { SelectOption } from "../select/index.js";
+import type { XmOverlay } from "../overlay/index.js";
+export declare class XmAutocomplete extends XmField {
+    /** Shared option model — `{ label, value, disabled? }` (AD-8a). */
+    options: SelectOption[];
+    /** Native placeholder shown when the query is empty. */
+    placeholder: string;
+    protected _open: boolean;
+    protected _query: string;
+    protected _activeIndex: number;
+    protected _selectedValue: string | number | null;
+    protected _input: HTMLInputElement | null;
+    protected _overlay: XmOverlay | null;
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    private _resolveSeed;
+    /** Typed primitive read for consumers; the inherited string `value` stays in
+        sync for xm-form / ElementInternals. */
+    get selectedValue(): string | number | null;
+    private get _filtered();
+    private get _enabledIndexes();
+    private _onDocPointerDown;
+    private _openList;
+    private _closeList;
+    private _onOverlayClose;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues<this>): void;
+    private _onInput;
+    private _commitSelection;
+    private _selectActive;
+    private _onKeydown;
+    private _nextEnabled;
+    protected renderControl(): TemplateResult;
+    private _renderOption;
+    /** Wrap the matched substring in a highlight mark. The mark carries BOTH a
+        coral ink AND an underline so the cue survives grayscale (NFR-15 — color
+        is never the sole carrier). */
+    private _highlight;
+    private _renderEmpty;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-autocomplete": XmAutocomplete;
+    }
+}

package/dist/lit/components/autocomplete/index.js

@@ -0,0 +1,404 @@
+/*
+  autocomplete/index.ts — <xm-autocomplete>, a filtering select (Story 2.4).
+
+  Extends the SAME pattern as xm-select: it subclasses XmField (chrome) and
+  composes xm-overlay (anchored, non-modal, menu-tier listbox). The only deltas
+  from xm-select are:
+    • the closed control is a TEXT INPUT that filters `options` as you type,
+    • each shown option highlights the matched substring (coral ink + underline,
+      so the cue survives grayscale — color is never the sole carrier, NFR-15),
+    • two typed events: `input` carries the query string, `change` carries the
+      selected option's PRIMITIVE value (AD-8a) — never overloaded onto one key,
+    • a no-match query renders an inline empty-state (sentence-case headline +
+      secondary copy + line icon, no imagery) instead of a blank/closed list.
+
+  NOTE (dependency): xm-empty-state (Epic 4 / FR-149) is not built yet, so the
+  no-match panel renders the empty-state markup INLINE here, using the same
+  line-icon + sentence-case headline + secondary copy pattern. Flagged for
+  consolidation once xm-empty-state ships.
+
+  It does NOT fork the overlay/positioning/focus contract and does NOT reach
+  into the overlay's shadow root (AD-12). Option model is the shared
+  `{ label, value, disabled? }`.
+
+  Keyboard (combobox + listbox APG, AD-9a): typing filters; ↑↓ move the active
+  match (skipping disabled), Home/End jump, Enter selects + closes, Esc closes
+  (routed through the overlay's innermost-Esc, which stopPropagations); focus
+  returns to the input on close.
+
+  Shadow DOM. Lit is a bare `import` (peer dep).
+*/
+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";
+const AUTOCOMPLETE_CSS = new URL("../autocomplete/index.css", import.meta.url).href;
+let XmAutocomplete = class XmAutocomplete extends XmField {
+    constructor() {
+        super(...arguments);
+        /** Shared option model — `{ label, value, disabled? }` (AD-8a). */
+        this.options = [];
+        /** Native placeholder shown when the query is empty. */
+        this.placeholder = "Search…";
+        this._open = false;
+        this._query = "";
+        this._activeIndex = -1;
+        this._selectedValue = null;
+        // ── Open / close ────────────────────────────────────────────────────
+        // Close the open list when a pointer goes down outside this element (the
+        // non-modal overlay provides no light-dismiss of its own).
+        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;
+                document.removeEventListener("pointerdown", this._onDocPointerDown, true);
+                if (detail?.reason !== "escape")
+                    this._input?.focus();
+            }
+        };
+        // ── Input / select ──────────────────────────────────────────────────
+        this._onInput = (e) => {
+            const q = e.target.value;
+            this._query = q;
+            if (!this._open)
+                this._openList();
+            this._activeIndex = this._enabledIndexes[0] ?? -1;
+            this.dispatchEvent(new CustomEvent("input", {
+                bubbles: true,
+                composed: true,
+                detail: { value: q },
+            }));
+        };
+        // ── Keyboard ────────────────────────────────────────────────────────
+        this._onKeydown = (e) => {
+            if (this.nonInteractive)
+                return;
+            if (!this._open) {
+                if (e.key === "ArrowDown" || e.key === "Enter") {
+                    e.preventDefault();
+                    this._openList();
+                }
+                return;
+            }
+            const enabled = this._enabledIndexes;
+            switch (e.key) {
+                case "ArrowDown":
+                    e.preventDefault();
+                    this._activeIndex = this._nextEnabled(this._activeIndex, 1);
+                    break;
+                case "ArrowUp":
+                    e.preventDefault();
+                    this._activeIndex = this._nextEnabled(this._activeIndex, -1);
+                    break;
+                case "Home":
+                    e.preventDefault();
+                    this._activeIndex = enabled[0] ?? -1;
+                    break;
+                case "End":
+                    e.preventDefault();
+                    this._activeIndex = enabled[enabled.length - 1] ?? -1;
+                    break;
+                case "Enter":
+                    e.preventDefault();
+                    // Choosing an option must not bubble to an ancestor xm-form as submit.
+                    e.stopPropagation();
+                    this._selectActive();
+                    break;
+                case "Tab":
+                    this._closeList(false);
+                    break;
+                // Esc handled by the overlay (innermost-only, stopPropagation).
+            }
+        };
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (this.initialValue !== "" && this._selectedValue === null) {
+            this._resolveSeed();
+        }
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (changed.has("options") &&
+            this._selectedValue === null &&
+            this.initialValue !== "") {
+            this._resolveSeed();
+        }
+    }
+    _resolveSeed() {
+        const match = this.options.find((o) => String(o.value) === this.initialValue);
+        if (match) {
+            this._selectedValue = match.value;
+            this._query = match.label;
+            this._value = String(match.value);
+            this.internals.setFormValue(this._value);
+        }
+    }
+    /** Typed primitive read for consumers; the inherited string `value` stays in
+        sync for xm-form / ElementInternals. */
+    get selectedValue() {
+        return this._selectedValue;
+    }
+    // ── Filtering ───────────────────────────────────────────────────────
+    get _filtered() {
+        const q = this._query.trim().toLowerCase();
+        if (q === "")
+            return this.options;
+        return this.options.filter((o) => o.label.toLowerCase().includes(q));
+    }
+    get _enabledIndexes() {
+        const f = this._filtered;
+        return f.map((o, i) => (o.disabled ? -1 : i)).filter((i) => i !== -1);
+    }
+    _openList() {
+        if (this.nonInteractive || this._open)
+            return;
+        this._open = true;
+        this._activeIndex = this._enabledIndexes[0] ?? -1;
+        document.addEventListener("pointerdown", this._onDocPointerDown, true);
+        this.updateComplete.then(() => {
+            const ov = this._overlay;
+            const inp = this._input;
+            if (ov && inp) {
+                ov.anchor = inp;
+                ov.opener = inp;
+                ov.show();
+            }
+        });
+    }
+    _closeList(focusInput = true) {
+        if (!this._open)
+            return;
+        this._open = false;
+        this._activeIndex = -1;
+        document.removeEventListener("pointerdown", this._onDocPointerDown, true);
+        const ov = this._overlay;
+        if (ov?.open)
+            ov.hide("api");
+        if (focusInput)
+            this._input?.focus();
+    }
+    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(".autocomplete__option--active")
+                ?.scrollIntoView({ block: "nearest" });
+        }
+    }
+    _commitSelection(opt) {
+        this._selectedValue = opt.value;
+        this._query = opt.label;
+        // Mark touched so the base's uncontrolled-first re-seed can't clobber the
+        // committed value/label back to `initialValue` (AD-6).
+        this._dirty = true;
+        this._value = String(opt.value);
+        this.internals.setFormValue(this._value);
+        this.dispatchEvent(new CustomEvent("change", {
+            bubbles: true,
+            composed: true,
+            detail: { value: opt.value },
+        }));
+        this._closeList(true);
+    }
+    _selectActive() {
+        const opt = this._filtered[this._activeIndex];
+        if (opt && !opt.disabled)
+            this._commitSelection(opt);
+    }
+    _nextEnabled(from, dir) {
+        const f = this._filtered;
+        const n = f.length;
+        if (n === 0)
+            return -1;
+        let i = from;
+        for (let step = 0; step < n; step++) {
+            i = (i + dir + n) % n;
+            if (!f[i]?.disabled)
+                return i;
+        }
+        return from;
+    }
+    // ── Render ──────────────────────────────────────────────────────────
+    renderControl() {
+        const a = this.controlAria;
+        const filtered = this._filtered;
+        const activeId = this._open && this._activeIndex >= 0
+            ? `${a.id}-opt-${this._activeIndex}`
+            : nothing;
+        return html `
+      <link rel="stylesheet" href="${AUTOCOMPLETE_CSS}" />
+      <div class="autocomplete__control">
+        <input
+          class="autocomplete__input"
+          id=${a.id}
+          type="text"
+          role="combobox"
+          autocomplete="off"
+          aria-autocomplete="list"
+          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}
+          placeholder=${this.placeholder || nothing}
+          name=${this.name || nothing}
+          .value=${this._query}
+          ?disabled=${this.effectiveDisabled}
+          ?readonly=${this.readonly}
+          @input=${this._onInput}
+          @keydown=${this._onKeydown}
+          @focus=${() => {
+            if (!this._open && !this.nonInteractive)
+                this._openList();
+        }}
+        />
+        <span class="autocomplete__chevron ${this._open ? "autocomplete__chevron--open" : ""}">
+          <xm-chevron-down-icon size="16"></xm-chevron-down-icon>
+        </span>
+      </div>
+
+      <xm-overlay
+        mode="non-modal"
+        tier="menu"
+        placement="bottom-start"
+        label=${this.label || "Suggestions"}
+        @xm-overlay-close=${this._onOverlayClose}
+      >
+        ${filtered.length > 0
+            ? html `<ul
+              class="autocomplete__listbox"
+              id="${a.id}-listbox"
+              role="listbox"
+              aria-label=${this.label || "Suggestions"}
+            >
+              ${filtered.map((opt, i) => this._renderOption(opt, i, a.id))}
+            </ul>`
+            : this._renderEmpty(a.id)}
+      </xm-overlay>
+    `;
+    }
+    _renderOption(opt, index, baseId) {
+        const selected = opt.value === this._selectedValue;
+        const active = index === this._activeIndex;
+        const cls = [
+            "autocomplete__option",
+            selected ? "autocomplete__option--selected" : "",
+            active ? "autocomplete__option--active" : "",
+            opt.disabled ? "autocomplete__option--disabled" : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        return html `
+      <li
+        class="${cls}"
+        id="${baseId}-opt-${index}"
+        role="option"
+        aria-selected=${selected ? "true" : "false"}
+        aria-disabled=${opt.disabled ? "true" : nothing}
+        @click=${() => {
+            if (!opt.disabled)
+                this._commitSelection(opt);
+        }}
+        @mousemove=${() => {
+            if (!opt.disabled)
+                this._activeIndex = index;
+        }}
+      >
+        <span class="autocomplete__option-label"
+          >${this._highlight(opt.label)}</span
+        >
+        ${selected
+            ? html `<span class="autocomplete__option-check" aria-hidden="true">
+              <xm-check-icon size="16"></xm-check-icon>
+            </span>`
+            : nothing}
+      </li>
+    `;
+    }
+    /** Wrap the matched substring in a highlight mark. The mark carries BOTH a
+        coral ink AND an underline so the cue survives grayscale (NFR-15 — color
+        is never the sole carrier). */
+    _highlight(label) {
+        const q = this._query.trim();
+        if (q === "")
+            return label;
+        const lower = label.toLowerCase();
+        const idx = lower.indexOf(q.toLowerCase());
+        if (idx === -1)
+            return label;
+        const before = label.slice(0, idx);
+        const matched = label.slice(idx, idx + q.length);
+        const after = label.slice(idx + q.length);
+        return html `${before}<mark class="autocomplete__mark">${matched}</mark
+      >${after}`;
+    }
+    _renderEmpty(baseId) {
+        // Inline empty-state (sentence-case headline + secondary copy + line icon).
+        // Replace with <xm-empty-state> once Epic 4 ships it.
+        return html `
+      <div
+        class="autocomplete__empty"
+        id="${baseId}-listbox"
+        role="listbox"
+        aria-label="No matches"
+      >
+        <span class="autocomplete__empty-icon" aria-hidden="true">
+          <xm-search-icon size="20"></xm-search-icon>
+        </span>
+        <p class="autocomplete__empty-title">No matches</p>
+        <p class="autocomplete__empty-copy">
+          Nothing matches “${this._query}”. Try a different search.
+        </p>
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ attribute: false })
+], XmAutocomplete.prototype, "options", void 0);
+__decorate([
+    property({ type: String })
+], XmAutocomplete.prototype, "placeholder", void 0);
+__decorate([
+    state()
+], XmAutocomplete.prototype, "_open", void 0);
+__decorate([
+    state()
+], XmAutocomplete.prototype, "_query", void 0);
+__decorate([
+    state()
+], XmAutocomplete.prototype, "_activeIndex", void 0);
+__decorate([
+    state()
+], XmAutocomplete.prototype, "_selectedValue", void 0);
+__decorate([
+    query(".autocomplete__input")
+], XmAutocomplete.prototype, "_input", void 0);
+__decorate([
+    query("xm-overlay")
+], XmAutocomplete.prototype, "_overlay", void 0);
+XmAutocomplete = __decorate([
+    customElement("xm-autocomplete")
+], XmAutocomplete);
+export { XmAutocomplete };

package/dist/lit/components/avatar/index.css

@@ -0,0 +1,62 @@
+/* ============================================
+   Avatar — circular identity token.
+
+   <xm-avatar> renders a circular identity chip: initials first,
+   then a Lucide-style person line-icon fallback, with an optional
+   image. No imagery is ever required (UX-DR8). The chip is an
+   opaque raise of the desk — it sits on a surface-container-* tier
+   (NOT a third surface family) with ink --md-sys-color-on-surface
+   matched to that backplate (AD-13). No gradient, no status hue.
+
+   Sizes share the canonical xs|sm|md|lg axis so an avatar lines up
+   with a same-size button / list row (AD-9).
+   ============================================ */
+
+.avatar {
+  --avatar-size: 32px;
+  --avatar-font: var(--md-sys-typescale-label-large-size);
+
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  width: var(--avatar-size);
+  height: var(--avatar-size);
+  flex-shrink: 0;
+  border-radius: var(--md-sys-shape-corner-full);
+  border: 1px solid var(--md-sys-color-outline-variant);
+  background: var(--md-sys-color-surface-container-high);
+  color: var(--md-sys-color-on-surface);
+  overflow: hidden;
+  user-select: none;
+}
+
+.avatar__initials {
+  font-family: var(--md-sys-typescale-label-large-font);
+  font-size: var(--avatar-font);
+  font-weight: 600;
+  line-height: 1;
+  letter-spacing: 0;
+  text-transform: uppercase;
+}
+
+.avatar__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--md-sys-color-on-surface-variant);
+}
+
+.avatar__img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+/* ---------- Sizes — one diameter per shared size axis ---------- */
+.avatar--xs { --avatar-size: 22px; --avatar-font: var(--md-sys-typescale-label-small-size); }
+.avatar--sm { --avatar-size: 28px; --avatar-font: var(--md-sys-typescale-label-medium-size); }
+.avatar--md { --avatar-size: 32px; --avatar-font: var(--md-sys-typescale-label-large-size); }
+.avatar--lg { --avatar-size: 40px; --avatar-font: var(--md-sys-typescale-title-small-size); }

package/dist/lit/components/avatar/index.d.ts

@@ -0,0 +1,19 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+type AvatarSize = "xs" | "sm" | "md" | "lg";
+declare class XmAvatar extends LitElement {
+    title: string;
+    name: string;
+    initials: string;
+    src: string;
+    size: AvatarSize;
+    private get _initials();
+    private get _label();
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-avatar": XmAvatar;
+    }
+}
+export {};

package/dist/lit/components/avatar/index.js

@@ -0,0 +1,112 @@
+/*
+  avatar/index.ts — <xm-avatar>.
+
+  Circular identity token. Resolution order: image (`src`, optional) →
+  initials (`initials`, or derived from `name`) → person line-icon
+  fallback. No imagery is ever required (UX-DR8).
+
+  Authoring:
+    <xm-avatar name="Ada Lovelace"></xm-avatar>
+    <xm-avatar initials="JT" size="lg"></xm-avatar>
+    <xm-avatar size="sm"></xm-avatar>            <!-- icon fallback -->
+
+  Properties:
+    name      string  — full name; initials derived from it, exposed as label
+    initials  string  — explicit initials (overrides derivation)
+    src       string  — optional image URL
+    size      xs|sm|md|lg (default md) — shared control-height axis
+
+  Sits on a surface-container-* tier with on-surface ink (AD-13);
+  no gradient, no status hue (AD-11). Shadow DOM; Lit is a bare `import` (peer dep).
+*/
+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 { LitElement, html, nothing } from "lit";
+import { customElement, property } from "lit/decorators.js";
+const AVATAR_CSS = new URL("../avatar/index.css", import.meta.url).href;
+const deriveInitials = (name) => {
+    const parts = name.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0)
+        return "";
+    if (parts.length === 1)
+        return (parts[0] ?? "").slice(0, 2);
+    const first = parts[0] ?? "";
+    const last = parts[parts.length - 1] ?? "";
+    return (first.charAt(0) + last.charAt(0));
+};
+let XmAvatar = class XmAvatar extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.title = "";
+        this.name = "";
+        this.initials = "";
+        this.src = "";
+        this.size = "md";
+    }
+    get _initials() {
+        return (this.initials || deriveInitials(this.name)).toUpperCase();
+    }
+    get _label() {
+        return this.title || this.name || (this._initials ? this._initials : "User");
+    }
+    render() {
+        const cls = `avatar avatar--${this.size}`;
+        let body;
+        if (this.src) {
+            body = html `<img class="avatar__img" src="${this.src}" alt="${this._label}" />`;
+        }
+        else if (this._initials) {
+            body = html `<span class="avatar__initials" aria-hidden="true">${this._initials}</span>`;
+        }
+        else {
+            body = html `
+        <span class="avatar__icon" aria-hidden="true">
+          <svg viewBox="0 0 24 24" width="60%" height="60%" fill="none"
+               stroke="currentColor" stroke-width="1.8"
+               stroke-linecap="round" stroke-linejoin="round">
+            <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2" />
+            <circle cx="12" cy="7" r="4" />
+          </svg>
+        </span>
+      `;
+        }
+        return html `
+      <link rel="stylesheet" href="${AVATAR_CSS}" />
+      <style>
+        :host {
+          display: inline-flex;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <span
+        class="${cls}"
+        role="img"
+        aria-label=${this._label || nothing}
+      >${body}</span>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmAvatar.prototype, "title", void 0);
+__decorate([
+    property({ type: String })
+], XmAvatar.prototype, "name", void 0);
+__decorate([
+    property({ type: String })
+], XmAvatar.prototype, "initials", void 0);
+__decorate([
+    property({ type: String })
+], XmAvatar.prototype, "src", void 0);
+__decorate([
+    property({ type: String })
+], XmAvatar.prototype, "size", void 0);
+XmAvatar = __decorate([
+    customElement("xm-avatar")
+], XmAvatar);