@xmesh/system-design 0.0.1

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

@@ -0,0 +1,50 @@
+import type { PropertyValues, TemplateResult } from "lit";
+import { XmField } from "../field/index.js";
+import type { XmOverlay } from "../overlay/index.js";
+export interface SelectOption {
+    label: string;
+    value: string | number;
+    disabled?: boolean;
+}
+export declare class XmSelect extends XmField {
+    /** The option model — `{ label, value, disabled? }` shared across
+        select / autocomplete / radio-group so one host handler is safe. */
+    options: SelectOption[];
+    /** Shown on the closed control when nothing is selected. */
+    placeholder: string;
+    protected _open: boolean;
+    protected _activeIndex: number;
+    /** The selected option's PRIMITIVE value (string | number), or null. */
+    protected _selectedValue: string | number | null;
+    protected _control: HTMLElement | null;
+    protected _overlay: XmOverlay | null;
+    private _typeahead;
+    private _typeaheadTimer;
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /** Live read for the closed control + xm-form. The inherited string `value`
+        stays in sync; this returns the typed primitive for consumers that want it. */
+    get selectedValue(): string | number | null;
+    private get _enabledIndexes();
+    private get _selectedLabel();
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues<this>): void;
+    private _onDocPointerDown;
+    private _openList;
+    private _closeList;
+    private _onOverlayClose;
+    private _commitSelection;
+    private _selectActive;
+    private _selectOption;
+    private _onControlKeydown;
+    private _onListKeydown;
+    private _nextEnabled;
+    private _typeAhead;
+    protected renderControl(): TemplateResult;
+    private _renderOption;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-select": XmSelect;
+    }
+}

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

@@ -0,0 +1,390 @@
+/*
+  select/index.ts — <xm-select>, a single-select dropdown (Story 2.3).
+
+  Composes two foundations and re-implements NEITHER:
+    • XmField (Story 1.3) owns the chrome — label / helper / error / required /
+      disabled / focus ring / form association / ARIA association (AD-7).
+    • xm-overlay (Story 1.4) owns the anchored, non-modal listbox — positioning,
+      stacking tier, focus restore, scroll handling (AD-5/AD-12). We drive it
+      through its PUBLIC API only (open / mode / tier / placement / .anchor /
+      .opener / xm-overlay-close) and NEVER reach into its shadow root.
+
+  The closed control shows the selected option's label (or `placeholder`) and a
+  chevron that rotates on open. Activating it opens the listbox; selecting an
+  option commits the option's PRIMITIVE value (string | number), closes the
+  overlay, and restores focus to the control.
+
+  Value contract (AD-6 / AD-8a): uncontrolled-first. The selected primitive is
+  held internally and mirrored into the inherited string `value` (so xm-form and
+  ElementInternals see a stable serialization), while the `change` event carries
+  the real primitive in detail.value — never the option object.
+
+  Keyboard (WAI-ARIA listbox APG, AD-9a): closed → Enter/Space/↓ opens; open →
+  ↑/↓ move the active option (skipping disabled), Home/End jump to first/last
+  enabled, type-ahead matches labels, Enter selects + closes, Esc closes without
+  committing (routed through the overlay's innermost-Esc, which stopPropagations).
+
+  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 SELECT_CSS = new URL("../select/index.css", import.meta.url).href;
+let XmSelect = class XmSelect extends XmField {
+    constructor() {
+        super(...arguments);
+        /** The option model — `{ label, value, disabled? }` shared across
+            select / autocomplete / radio-group so one host handler is safe. */
+        this.options = [];
+        /** Shown on the closed control when nothing is selected. */
+        this.placeholder = "Select…";
+        this._open = false;
+        this._activeIndex = -1;
+        /** The selected option's PRIMITIVE value (string | number), or null. */
+        this._selectedValue = null;
+        this._typeahead = "";
+        this._typeaheadTimer = 0;
+        // ── Open / close ────────────────────────────────────────────────────
+        // Close the open listbox when a pointer goes down anywhere outside this
+        // element (the non-modal overlay has no light-dismiss of its own).
+        this._onDocPointerDown = (e) => {
+            if (!this._open)
+                return;
+            const path = e.composedPath();
+            if (!path.includes(this))
+                this._closeList(false);
+        };
+        this._onOverlayClose = (e) => {
+            const detail = e.detail;
+            // Sync our open state when the overlay self-dismisses (Esc / backdrop).
+            if (this._open) {
+                this._open = false;
+                this._activeIndex = -1;
+                document.removeEventListener("pointerdown", this._onDocPointerDown, true);
+                // The overlay already restored focus to its opener (the control) for
+                // Esc; only steer focus ourselves for non-escape dismissals.
+                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();
+                    // Stop Enter/Space from reaching an ancestor xm-form (Enter-to-submit):
+                    // opening the listbox must not also submit the surrounding form.
+                    e.stopPropagation();
+                    this._openList();
+                }
+                return;
+            }
+            this._onListKeydown(e);
+        };
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // Seed the selection from the uncontrolled `value` attribute (AD-6).
+        if (this.initialValue !== "" && this._selectedValue === null) {
+            const match = this.options.find((o) => String(o.value) === this.initialValue);
+            if (match)
+                this._commitSelection(match.value, false);
+        }
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        // When options arrive after the value seed, resolve the seed once.
+        if (changed.has("options") &&
+            this._selectedValue === null &&
+            this.initialValue !== "") {
+            const match = this.options.find((o) => String(o.value) === this.initialValue);
+            if (match)
+                this._commitSelection(match.value, false);
+        }
+    }
+    /** Live read for the closed control + xm-form. The inherited string `value`
+        stays in sync; this returns the typed primitive for consumers that want it. */
+    get selectedValue() {
+        return this._selectedValue;
+    }
+    get _enabledIndexes() {
+        return this.options
+            .map((o, i) => (o.disabled ? -1 : i))
+            .filter((i) => i !== -1);
+    }
+    get _selectedLabel() {
+        const opt = this.options.find((o) => o.value === this._selectedValue);
+        return opt ? opt.label : "";
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        document.removeEventListener("pointerdown", this._onDocPointerDown, true);
+    }
+    updated(changed) {
+        super.updated?.(changed);
+        // Keep the active option visible when keyboard navigation moves it past the
+        // scrollable listbox fold.
+        if (this._open &&
+            changed.has("_activeIndex") &&
+            this._activeIndex >= 0) {
+            const active = this.renderRoot.querySelector(".select__option--active");
+            active?.scrollIntoView({ block: "nearest" });
+        }
+    }
+    _openList() {
+        if (this.nonInteractive || this._open)
+            return;
+        this._open = true;
+        document.addEventListener("pointerdown", this._onDocPointerDown, true);
+        // Land the active option on the current selection, else first enabled.
+        const selIdx = this.options.findIndex((o) => o.value === this._selectedValue);
+        this._activeIndex =
+            selIdx !== -1 && !this.options[selIdx]?.disabled
+                ? selIdx
+                : this._enabledIndexes[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;
+        document.removeEventListener("pointerdown", this._onDocPointerDown, true);
+        const ov = this._overlay;
+        if (ov?.open)
+            ov.hide("api");
+        if (focusControl)
+            this._control?.focus();
+    }
+    // ── Selection commit ────────────────────────────────────────────────
+    _commitSelection(value, emit = true) {
+        this._selectedValue = value;
+        // Mark touched so the base's uncontrolled-first re-seed can't later clobber
+        // `_value` back to `initialValue` while `_selectedValue`/the label stay put.
+        this._dirty = true;
+        // Mirror into the inherited string value + form value (AD-6a).
+        this._value = String(value);
+        this.internals.setFormValue(this._value);
+        if (emit) {
+            this.dispatchEvent(new CustomEvent("change", {
+                bubbles: true,
+                composed: true,
+                detail: { value },
+            }));
+        }
+    }
+    _selectActive() {
+        const opt = this.options[this._activeIndex];
+        if (!opt || opt.disabled)
+            return;
+        this._commitSelection(opt.value);
+        this._closeList(true);
+    }
+    _selectOption(index) {
+        const opt = this.options[index];
+        if (!opt || opt.disabled)
+            return;
+        this._activeIndex = index;
+        this._commitSelection(opt.value);
+        this._closeList(true);
+    }
+    _onListKeydown(e) {
+        const enabled = this._enabledIndexes;
+        if (enabled.length === 0 && e.key !== "Escape")
+            return;
+        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": {
+                // Commit nothing; let focus leave — close the list.
+                this._closeList(false);
+                break;
+            }
+            // Esc is handled by the overlay (innermost-only, stopPropagation) →
+            // _onOverlayClose syncs our state. No local handler needed.
+            default: {
+                if (e.key.length === 1 && !e.metaKey && !e.ctrlKey && !e.altKey) {
+                    this._typeAhead(e.key);
+                }
+            }
+        }
+    }
+    _nextEnabled(from, dir) {
+        const n = this.options.length;
+        if (n === 0)
+            return -1;
+        let i = from;
+        for (let step = 0; step < n; step++) {
+            i = (i + dir + n) % n;
+            if (!this.options[i]?.disabled)
+                return i;
+        }
+        return from;
+    }
+    _typeAhead(char) {
+        window.clearTimeout(this._typeaheadTimer);
+        this._typeahead += char.toLowerCase();
+        this._typeaheadTimer = window.setTimeout(() => {
+            this._typeahead = "";
+        }, 500);
+        const match = this.options.findIndex((o) => !o.disabled && o.label.toLowerCase().startsWith(this._typeahead));
+        if (match !== -1)
+            this._activeIndex = match;
+    }
+    // ── Render ──────────────────────────────────────────────────────────
+    renderControl() {
+        const a = this.controlAria;
+        const hasSelection = this._selectedValue !== null;
+        const display = hasSelection ? this._selectedLabel : this.placeholder;
+        const activeId = this._open && this._activeIndex >= 0
+            ? `${a.id}-opt-${this._activeIndex}`
+            : nothing;
+        return html `
+      <link rel="stylesheet" href="${SELECT_CSS}" />
+      <button
+        type="button"
+        class="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="select__value ${hasSelection
+            ? ""
+            : "select__value--placeholder"}"
+        >
+          ${display}
+        </span>
+        <span class="select__chevron ${this._open ? "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}
+      >
+        <ul
+          class="select__listbox"
+          id="${a.id}-listbox"
+          role="listbox"
+          aria-label=${this.label || "Options"}
+          @keydown=${(e) => this._onListKeydown(e)}
+        >
+          ${this.options.map((opt, i) => this._renderOption(opt, i, a.id))}
+        </ul>
+      </xm-overlay>
+    `;
+    }
+    _renderOption(opt, index, baseId) {
+        const selected = opt.value === this._selectedValue;
+        const active = index === this._activeIndex;
+        const cls = [
+            "select__option",
+            selected ? "select__option--selected" : "",
+            active ? "select__option--active" : "",
+            opt.disabled ? "select__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=${() => this._selectOption(index)}
+        @mousemove=${() => {
+            if (!opt.disabled)
+                this._activeIndex = index;
+        }}
+      >
+        <span class="select__option-label">${opt.label}</span>
+        ${selected
+            ? html `<span class="select__option-check" aria-hidden="true">
+              <xm-check-icon size="16"></xm-check-icon>
+            </span>`
+            : nothing}
+      </li>
+    `;
+    }
+};
+__decorate([
+    property({ attribute: false })
+], XmSelect.prototype, "options", void 0);
+__decorate([
+    property({ type: String })
+], XmSelect.prototype, "placeholder", void 0);
+__decorate([
+    state()
+], XmSelect.prototype, "_open", void 0);
+__decorate([
+    state()
+], XmSelect.prototype, "_activeIndex", void 0);
+__decorate([
+    state()
+], XmSelect.prototype, "_selectedValue", void 0);
+__decorate([
+    query(".select__control")
+], XmSelect.prototype, "_control", void 0);
+__decorate([
+    query("xm-overlay")
+], XmSelect.prototype, "_overlay", void 0);
+XmSelect = __decorate([
+    customElement("xm-select")
+], XmSelect);
+export { XmSelect };

package/dist/lit/components/sidebar-item/index.css

@@ -0,0 +1,133 @@
+/* ============================================================
+   <SidebarItem /> — chat-list row in the sidebar.
+
+   Two layouts share the same hover/active backgrounds:
+     row     — single-line: [dot] [title]   (sidebar-item.html)
+     stacked — single-line title in chat.html
+
+   Plus a collapsed variant that renders as a 4px stripe rail when the
+   sidebar is in icon-only mode.
+
+   Pairs with components/sidebar-item/index.jsx. The CSS lives on the
+   chat-shell `surface` (the warm dark "desk" / cream in light) and uses
+   `on-surface*` tokens accordingly.
+   ============================================================ */
+
+.sidebar-item {
+  cursor: pointer;
+  border-radius: 8px;
+  transition: background var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard);
+}
+
+/* ---------- Layout: row ---------- */
+.sidebar-item--row {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2-5);
+  padding: 9px var(--s-2-5);
+}
+.sidebar-item--row .sidebar-item__title {
+  font: 500 13px/1.2 var(--md-sys-typescale-body-large-font);
+  color: var(--md-sys-color-on-surface);
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+/* The dot in the row layout is a leading 8px circle; consumers
+   pass showDot to render it filled. The slot is always present so
+   titles align across rows. */
+.sidebar-item--row .sidebar-item__dot {
+  width: 8px; height: 8px;
+  border-radius: 999px;
+  background: transparent;
+  flex-shrink: 0;
+}
+.sidebar-item--row.has-dot .sidebar-item__dot {
+  background: var(--md-sys-color-primary);
+}
+
+/* ---------- Layout: stacked ---------- */
+.sidebar-item--stacked {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-0-5);
+  padding: var(--s-2) var(--s-2-5);
+}
+.sidebar-item--stacked .sidebar-item__title {
+  font: 500 13px/1.25 var(--md-sys-typescale-body-large-font);
+  color: var(--md-sys-color-on-surface);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* ---------- Hover & active (shared across layouts) ----------
+   Hover and active were the same near-black surface-container-lowest, so
+   the two states read identically and reused the vanishing-bubble color.
+   The sidebar rides `surface` (the desk), so both states must be a step ABOVE
+   it to read — surface-container-low equals `surface` in dark and would vanish.
+   Ramp upward: desk → hover (surface-container) → active (surface-container-high,
+   the same raised family the user bubble / composer ride). */
+.sidebar-item:hover,
+.sidebar-item.is-hover {
+  background: var(--md-sys-color-surface-container);
+}
+.sidebar-item.is-active {
+  background: var(--md-sys-color-surface-container-high);
+}
+.sidebar-item:hover .sidebar-item__title,
+.sidebar-item.is-hover .sidebar-item__title,
+.sidebar-item.is-active .sidebar-item__title {
+  color: var(--md-sys-color-on-surface);
+}
+
+/* Dark theme — push the resting title color further into gray so the
+   active item's strong-ink title pops as the brighter, more-white state.
+   Light theme keeps the standard on-surface ramp (already reads as a clear
+   default → strong contrast there). */
+[data-theme="dark"] .sidebar-item:not(.is-active):not(.is-hover):not(:hover) .sidebar-item__title {
+  color: var(--md-sys-color-on-surface-variant);
+}
+
+/* ---------- Collapsed: 4px stripe rail ---------- */
+.sidebar-item--collapsed {
+  width: 24px;
+  height: 4px;
+  padding: 0;
+  border-radius: 2px;
+  background: var(--xm-color-on-surface-soft);
+  opacity: 0.35;
+  transition:
+    opacity var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard),
+    background var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard);
+}
+.sidebar-item--collapsed:hover {
+  background: var(--md-sys-color-on-surface);
+  opacity: 0.6;
+}
+.sidebar-item--collapsed.is-active {
+  background: var(--md-sys-color-on-surface);
+  opacity: 0.85;
+  box-shadow: none;
+}
+.sidebar-item--collapsed > * { display: none; }
+
+/* ---------- Eyebrow: section header above a group of items ----------
+   Renders as an uppercase mono caption on the surface. No hover, no
+   active — it's a label, not a target. */
+.sidebar-item--eyebrow {
+  cursor: default;
+  padding: var(--s-3-5) var(--s-2-5) var(--s-1-5);
+  font:
+    var(--md-sys-typescale-label-small-weight)
+    var(--md-sys-typescale-label-small-size) /
+    var(--md-sys-typescale-label-small-line-height)
+    var(--md-sys-typescale-label-small-font);
+  color: var(--xm-color-on-surface-soft);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  font-family: var(--xm-typescale-mono-font);
+}
+.sidebar-item--eyebrow:hover { background: transparent; }

package/dist/lit/components/sidebar-item/index.d.ts

@@ -0,0 +1,20 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+type SidebarLayout = "row" | "stacked";
+declare class XmSidebarItem extends LitElement {
+    title: string;
+    layout: SidebarLayout;
+    active: boolean;
+    hover: boolean;
+    showDot: boolean;
+    collapsed: boolean;
+    createRenderRoot(): HTMLElement | DocumentFragment;
+    connectedCallback(): void;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-sidebar-item": XmSidebarItem;
+    }
+}
+export {};