@xmesh/system-design 0.0.1

package/dist/lit/components/file-input/index.js

@@ -0,0 +1,298 @@
+/*
+  file-input/index.ts — <xm-file-input>, a generic file picker / dropzone (Story 2.9).
+
+  Extends XmField for the chrome (label / helper / error / disabled / form
+  association / focus) and renders a dropzone: clicking (or Enter/Space) opens the
+  native file picker; dragging files over it shows the drag-active state; dropping
+  accepts them. After selection it lists each file's name + formatted size
+  (`412 KB` — number and unit separated by a space, UX-DR4).
+
+  This is the GENERIC picker — explicitly distinct from the shipped, chat-specific
+  xm-file-validation-block (FR-130). Both coexist.
+
+  Value contract (AD-6 / AD-8a): uncontrolled-first. On selection it emits
+  `change` with the bespoke typed payload detail.files: File[] (not the generic
+  value/checked shapes). The selected files are exposed via a public `files`
+  getter; the form value is set from the selection via ElementInternals.
+
+  Borders: the drag-active state is the ONE place a 2px border is allowed
+  (2px solid --md-sys-color-primary) — every other border is hairline 1px
+  (DESIGN.md). Errors render as icon + copy in the message row, never a 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 { html, nothing } from "lit";
+import { customElement, property, state, query } from "lit/decorators.js";
+import { XmField } from "../field/index.js";
+const FILE_INPUT_CSS = new URL("../file-input/index.css", import.meta.url).href;
+const PRIMITIVES_CSS = new URL("../primitives/index.css", import.meta.url).href;
+/** Format bytes as `B` / `KB` / `MB` with one space before the unit (UX-DR4).
+    Decimal units (1 KB = 1000 B) — matches the file-size convention users see in
+    macOS / browsers, so a 412000-byte file reads "412 KB". */
+function formatBytes(bytes) {
+    if (bytes < 1000)
+        return `${bytes} B`;
+    const kb = bytes / 1000;
+    if (kb < 1000)
+        return `${Math.round(kb)} KB`;
+    const mb = kb / 1000;
+    return `${mb < 10 ? mb.toFixed(1) : Math.round(mb)} MB`;
+}
+let XmFileInput = class XmFileInput extends XmField {
+    constructor() {
+        super(...arguments);
+        /** Native accept filter (e.g. ".yml,.json,image/*"). */
+        this.accept = "";
+        /** Allow selecting more than one file. */
+        this.multiple = false;
+        this._files = [];
+        this._dragActive = false;
+        this._onNativeChange = (e) => {
+            const list = e.target.files;
+            this._setFiles(list ? Array.from(list) : []);
+        };
+        this._onKeydown = (e) => {
+            if (e.key === "Enter" || e.key === " " || e.key === "Spacebar") {
+                e.preventDefault();
+                this._openPicker();
+            }
+        };
+        this._onDragOver = (e) => {
+            if (this.nonInteractive)
+                return;
+            e.preventDefault();
+            this._dragActive = true;
+        };
+        this._onDragLeave = (e) => {
+            e.preventDefault();
+            // Only clear drag-active when the pointer actually leaves the dropzone —
+            // crossing between the zone's child elements fires dragleave/dragenter pairs
+            // and would otherwise flicker the 2px border.
+            const related = e.relatedTarget;
+            if (related && e.currentTarget instanceof Node && e.currentTarget.contains(related)) {
+                return;
+            }
+            this._dragActive = false;
+        };
+        this._onDrop = (e) => {
+            if (this.nonInteractive)
+                return;
+            e.preventDefault();
+            this._dragActive = false;
+            const list = e.dataTransfer?.files;
+            if (!list || list.length === 0)
+                return;
+            // Apply the same `accept` filter the native picker enforces (the picker
+            // filters; a drop must not bypass it).
+            const picked = Array.from(list).filter((f) => this._accepts(f));
+            if (picked.length === 0)
+                return;
+            this._setFiles(this.multiple ? picked : picked.slice(0, 1));
+        };
+    }
+    /** Public read contract (AD-6a) — the selected files. */
+    get files() {
+        return this._files;
+    }
+    _setFiles(files) {
+        this._files = files;
+        this._value = files.map((f) => f.name).join(", ");
+        if (files.length === 0) {
+            this.internals.setFormValue(null);
+        }
+        else {
+            const data = new FormData();
+            const key = this.name || "files";
+            for (const f of files)
+                data.append(key, f, f.name);
+            this.internals.setFormValue(data);
+        }
+        this.dispatchEvent(new CustomEvent("change", {
+            bubbles: true,
+            composed: true,
+            detail: { files },
+        }));
+    }
+    _openPicker() {
+        if (this.nonInteractive)
+            return;
+        this._native?.click();
+    }
+    /** Does a dropped file satisfy the `accept` list? Mirrors the native picker so
+        drag-drop and click-to-pick enforce the same filter. */
+    _accepts(file) {
+        const accept = this.accept.trim();
+        if (accept === "")
+            return true;
+        const name = file.name.toLowerCase();
+        const type = file.type.toLowerCase();
+        return accept.split(",").some((raw) => {
+            const token = raw.trim().toLowerCase();
+            if (token === "")
+                return false;
+            if (token.startsWith("."))
+                return name.endsWith(token);
+            if (token.endsWith("/*"))
+                return type.startsWith(token.slice(0, -1));
+            return type === token;
+        });
+    }
+    _removeFile(index) {
+        if (this.nonInteractive)
+            return;
+        const next = this._files.filter((_, i) => i !== index);
+        this._setFiles(next);
+        // Clear the native input so re-picking the same file fires change again.
+        if (this._native)
+            this._native.value = "";
+    }
+    ;
+    render() {
+        const cls = [
+            "file-input",
+            this._dragActive ? "file-input--drag-active" : "",
+            this.effectiveDisabled ? "file-input--disabled" : "",
+            this.isError ? "file-input--error" : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        const helperText = this.isError ? this.error : this.helper;
+        const ctrl = this.controlAria;
+        return html `
+      <link rel="stylesheet" href="${PRIMITIVES_CSS}" />
+      <link rel="stylesheet" href="${FILE_INPUT_CSS}" />
+      <style>
+        :host {
+          display: block;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <div class="${cls}">
+        ${this.label
+            ? html `<label class="file-input__label" id="${ctrl.id}-label">
+              <span class="file-input__label-text">${this.label}</span>
+              ${this.required
+                ? html `<span class="file-input__required" aria-hidden="true"
+                    >*</span
+                  >`
+                : nothing}
+            </label>`
+            : nothing}
+
+        <input
+          class="file-input__native"
+          type="file"
+          accept=${this.accept || nothing}
+          ?multiple=${this.multiple}
+          ?disabled=${this.effectiveDisabled}
+          @change=${this._onNativeChange}
+          tabindex="-1"
+          aria-hidden="true"
+        />
+
+        <div
+          class="file-input__dropzone"
+          id="${ctrl.id}"
+          role="button"
+          tabindex="${this.effectiveDisabled ? -1 : 0}"
+          aria-labelledby="${this.label ? `${ctrl.id}-label` : nothing}"
+          aria-label="${this.label ? nothing : "Choose file or drop here"}"
+          aria-describedby="${helperText ? ctrl.describedBy : nothing}"
+          aria-invalid="${ctrl.invalid ?? nothing}"
+          aria-disabled="${this.effectiveDisabled ? "true" : nothing}"
+          @click=${this._openPicker}
+          @keydown=${this._onKeydown}
+          @dragover=${this._onDragOver}
+          @dragleave=${this._onDragLeave}
+          @drop=${this._onDrop}
+        >
+          <span class="file-input__icon" aria-hidden="true">
+            <xm-paperclip-icon size="18"></xm-paperclip-icon>
+          </span>
+          <span class="file-input__copy">
+            <span class="file-input__primary">
+              ${this._dragActive ? "Drop to upload" : "Choose file or drop here"}
+            </span>
+            <span class="file-input__secondary">
+              ${this.accept
+            ? this.accept
+            : this.multiple
+                ? "One or more files"
+                : "A single file"}
+            </span>
+          </span>
+        </div>
+
+        ${this._files.length > 0
+            ? html `<ul class="file-input__files" aria-live="polite">
+              ${this._files.map((f, i) => html `<li class="file-input__file">
+                  <span class="file-input__file-icon" aria-hidden="true">
+                    <xm-file-glyph-icon size="16"></xm-file-glyph-icon>
+                  </span>
+                  <span class="file-input__file-name">${f.name}</span>
+                  <span class="file-input__file-size"
+                    >${formatBytes(f.size)}</span
+                  >
+                  <button
+                    type="button"
+                    class="file-input__remove"
+                    aria-label="Remove ${f.name}"
+                    ?disabled=${this.effectiveDisabled}
+                    @click=${(e) => {
+                e.stopPropagation();
+                this._removeFile(i);
+            }}
+                  >
+                    <xm-x-icon size="10"></xm-x-icon>
+                  </button>
+                </li>`)}
+            </ul>`
+            : nothing}
+
+        ${helperText
+            ? html `<div
+              class="file-input__message ${this.isError
+                ? "file-input__message--error"
+                : "file-input__message--helper"}"
+              id="${ctrl.describedBy}"
+              role=${this.isError ? "alert" : nothing}
+            >
+              ${this.isError
+                ? html `<span class="file-input__error-icon" aria-hidden="true">
+                    <xm-warn-icon size="14"></xm-warn-icon>
+                  </span>`
+                : nothing}
+              <span class="file-input__message-text">${helperText}</span>
+            </div>`
+            : nothing}
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmFileInput.prototype, "accept", void 0);
+__decorate([
+    property({ type: Boolean })
+], XmFileInput.prototype, "multiple", void 0);
+__decorate([
+    state()
+], XmFileInput.prototype, "_files", void 0);
+__decorate([
+    state()
+], XmFileInput.prototype, "_dragActive", void 0);
+__decorate([
+    query(".file-input__native")
+], XmFileInput.prototype, "_native", void 0);
+XmFileInput = __decorate([
+    customElement("xm-file-input")
+], XmFileInput);
+export { XmFileInput };

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

@@ -0,0 +1,29 @@
+/* ============================================
+   xm-form — field aggregator / orchestrator (Story 2.10).
+
+   Layout-only chrome: a vertical stack of slotted fields with consistent --s-N
+   gaps so fields of the same `size` align (NFR-22). xm-form has NO surface of
+   its own and no bespoke color tokens — each child renders its own XmField
+   chrome, which the form must never restyle (AD-7 / AD-12).
+
+   BEM block: `form`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-5);
+}
+
+/* The slotted action row (a button or button group) sits at the foot of the
+   stack; authors mark it with slot="actions" if they want it grouped + set off
+   from the fields by a single hairline (the system's 1px rule — no surface, just
+   a divider). Default flow already stacks it under the last field. */
+.form ::slotted([slot="actions"]) {
+  display: flex;
+  gap: var(--s-3);
+  align-items: center;
+  margin-top: var(--s-2);
+  padding-top: var(--s-4);
+  border-top: 1px solid var(--md-sys-color-outline-variant);
+}

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

@@ -0,0 +1,38 @@
+import { LitElement } from "lit";
+import type { PropertyValues, TemplateResult } from "lit";
+export interface FormResult {
+    valid: boolean;
+    values: Record<string, unknown>;
+}
+export declare class XmForm extends LitElement {
+    disabled: boolean;
+    readonly: boolean;
+    /** Each touched child's OWN readonly, snapshotted before the form ever sets it,
+        so OR-propagation never clears a child's intrinsic readonly. */
+    private readonly _ownReadonly;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues<this>): void;
+    /** The slotted, form-associated children — discovered via the light DOM, never
+        by querying any child's shadow root (AD-12). */
+    private get _fields();
+    /** Read one child's current value by its kind (toggle / file / value field). */
+    private _readValue;
+    private _isToggle;
+    /** A child is invalid if it carries error copy OR is required-but-empty. */
+    private _isInvalid;
+    /** Public read contract: pull each child's live value at read time (children
+        are uncontrolled — the form does not drive their renders, AD-6). */
+    validate(): FormResult;
+    /** Imperative submit — same path the submit button / Enter take. */
+    submit(): FormResult;
+    private _onChildSubmit;
+    private _onKeydown;
+    private _propagate;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-form": XmForm;
+    }
+}

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

@@ -0,0 +1,192 @@
+/*
+  form/index.ts — <xm-form>, the field aggregator / orchestrator (Story 2.10).
+
+  The CULMINATION of Epic 2: it composes every form-associated field via the
+  AD-6a public contract and reads each child ONLY through its public getters /
+  native form participation — NEVER by reaching into a child's shadow root
+  (AD-12). It is layout-only chrome; each child renders its own XmField chrome,
+  which the form must never re-render or restyle.
+
+  What it owns:
+    • validate(): { valid, values } — iterates the slotted fields, reads each
+      `value` / `checked` / `files` getter keyed by the child's `name`, and
+      aggregates `valid` from each child's validity (required-empty / error copy).
+    • submit path — on a submit button, Enter in a field, or submit() call, it
+      runs validate(), emits a composed `submit` with the same { values, valid }
+      detail (AD-8), and blocks when invalid so the host controls the action and
+      the offending fields keep showing their own icon+copy errors.
+    • disabled / readonly down-propagation with OR semantics (AD-6a): a child is
+      disabled/readonly if EITHER the form or the child sets it; neither source
+      re-enables the other. Disabled rides the base's setFormDisabled() hook;
+      readonly is OR'd against each child's OWN readonly (snapshotted once).
+
+  xm-form is NOT a field — it has no value of its own.
+
+  Shadow DOM (slot projection). 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 } from "lit";
+import { customElement, property } from "lit/decorators.js";
+const FORM_CSS = new URL("../form/index.css", import.meta.url).href;
+let XmForm = class XmForm extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.disabled = false;
+        this.readonly = false;
+        /** Each touched child's OWN readonly, snapshotted before the form ever sets it,
+            so OR-propagation never clears a child's intrinsic readonly. */
+        this._ownReadonly = new WeakMap();
+        // ── Submit triggers ─────────────────────────────────────────────────
+        // A native <form> (or an xm-button[type=submit] dispatching submit) bubbles a
+        // `submit` event; intercept it, run our path, and stop the native navigation.
+        this._onChildSubmit = (e) => {
+            // Don't re-handle our OWN composed submit event.
+            if (e.detail && "valid" in (e.detail ?? {})) {
+                return;
+            }
+            e.preventDefault();
+            e.stopPropagation();
+            this.submit();
+        };
+        this._onKeydown = (e) => {
+            // Enter inside a single-line field submits; leave textarea Enter to insert a
+            // newline (its own behavior), and don't hijack Enter on buttons.
+            if (e.key !== "Enter")
+                return;
+            const target = e.target;
+            const tag = target.tagName.toLowerCase();
+            if (tag === "xm-textarea" || tag === "xm-button" || tag === "button")
+                return;
+            if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey)
+                return;
+            e.preventDefault();
+            this.submit();
+        };
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener("submit", this._onChildSubmit);
+        this.addEventListener("keydown", this._onKeydown);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener("submit", this._onChildSubmit);
+        this.removeEventListener("keydown", this._onKeydown);
+    }
+    updated(changed) {
+        if (changed.has("disabled") || changed.has("readonly")) {
+            this._propagate();
+        }
+    }
+    /** The slotted, form-associated children — discovered via the light DOM, never
+        by querying any child's shadow root (AD-12). */
+    get _fields() {
+        return Array.from(this.children).filter((el) => {
+            return (el instanceof HTMLElement &&
+                // A field carries a name and participates in the value contract.
+                "value" in el &&
+                typeof el.name === "string");
+        });
+    }
+    /** Read one child's current value by its kind (toggle / file / value field). */
+    _readValue(field) {
+        if (typeof field.files !== "undefined" && Array.isArray(field.files)) {
+            return field.files;
+        }
+        // A toggle field reports `checked`; reading checked is only meaningful when
+        // the element actually exposes it as a boolean (checkbox / switch).
+        if (this._isToggle(field))
+            return field.checked === true;
+        return field.value;
+    }
+    _isToggle(field) {
+        const tag = field.tagName.toLowerCase();
+        return tag === "xm-checkbox" || tag === "xm-switch";
+    }
+    /** A child is invalid if it carries error copy OR is required-but-empty. */
+    _isInvalid(field) {
+        if (typeof field.error === "string" && field.error.trim() !== "") {
+            return true;
+        }
+        if (field.required) {
+            const v = this._readValue(field);
+            if (Array.isArray(v))
+                return v.length === 0;
+            if (typeof v === "boolean")
+                return v === false;
+            return v === undefined || v === null || v === "";
+        }
+        return false;
+    }
+    /** Public read contract: pull each child's live value at read time (children
+        are uncontrolled — the form does not drive their renders, AD-6). */
+    validate() {
+        const values = {};
+        let valid = true;
+        for (const field of this._fields) {
+            const name = field.name ?? "";
+            if (name === "")
+                continue;
+            values[name] = this._readValue(field);
+            if (this._isInvalid(field))
+                valid = false;
+        }
+        return { valid, values };
+    }
+    /** Imperative submit — same path the submit button / Enter take. */
+    submit() {
+        const result = this.validate();
+        this.dispatchEvent(new CustomEvent("submit", {
+            bubbles: true,
+            composed: true,
+            detail: result,
+        }));
+        return result;
+    }
+    // ── Disabled / readonly OR-propagation ──────────────────────────────
+    _propagate() {
+        for (const field of this._fields) {
+            // Disabled rides the base's OR hook (never re-enables a self-disabled field).
+            field.setFormDisabled?.(this.disabled);
+            // Readonly: OR against the child's OWN readonly, snapshotted once so the
+            // form never clears a child's intrinsic readonly.
+            if (!this._ownReadonly.has(field)) {
+                this._ownReadonly.set(field, field.readonly === true);
+            }
+            const own = this._ownReadonly.get(field) ?? false;
+            field.readonly = own || this.readonly;
+        }
+    }
+    render() {
+        return html `
+      <link rel="stylesheet" href="${FORM_CSS}" />
+      <style>
+        :host {
+          display: block;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <div class="form">
+        <slot @slotchange=${() => this._propagate()}></slot>
+        <slot name="actions"></slot>
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmForm.prototype, "disabled", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmForm.prototype, "readonly", void 0);
+XmForm = __decorate([
+    customElement("xm-form")
+], XmForm);
+export { XmForm };

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

@@ -0,0 +1,53 @@
+/* ============================================
+   <xm-grid> — N-column (default 12) layout grid.
+
+   Slotted children are grid items (the <slot> is layout-transparent,
+   like xm-chip-group). A child spans N columns by setting the inline
+   custom property --xm-col-span on itself; default span is 1.
+   Optional --xm-col-start for explicit placement. Gutter via
+   gap="…" → --xm-gutter-* (the --s-N-aliased layout tier).
+
+   Below --xm-breakpoint-sm (520px) the grid collapses to a single
+   column. NOTE: the 520px literal is repeated in the @media below
+   because @media cannot read var(--xm-breakpoint-sm); the token in
+   styles/_layout.css is the source of truth (docs/adr/0001).
+
+   BEM block `grid`; modifiers --gap-*. Registered in
+   scripts/check-bem.sh STRICT_BLOCKS.
+   ============================================ */
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(var(--xm-grid-columns, 12), minmax(0, 1fr));
+  gap: var(--xm-gutter-md);
+  /* Inherited ink so currentColor in slotted content reads on the desk
+     surface (AD-13) — also satisfies the --md-sys-* token gate. */
+  color: var(--md-sys-color-on-surface);
+}
+
+.grid--gap-none { gap: var(--xm-gutter-none); }
+.grid--gap-xs   { gap: var(--xm-gutter-xs); }
+.grid--gap-sm   { gap: var(--xm-gutter-sm); }
+.grid--gap-md   { gap: var(--xm-gutter-md); }
+.grid--gap-lg   { gap: var(--xm-gutter-lg); }
+.grid--gap-xl   { gap: var(--xm-gutter-xl); }
+
+/* Per-child placement, authored as inline custom properties on the child.
+   minmax(0, 1fr) + min-width: 0 keeps a wide / unbreakable child from
+   blowing its track out instead of honouring the span. */
+.grid ::slotted(*) {
+  grid-column: var(--xm-col-start, auto) / span var(--xm-col-span, 1);
+  min-width: 0;
+}
+
+/* Compact: collapse to one column. The 520px literal mirrors
+   --xm-breakpoint-sm (styles/_layout.css); @media can't read the token
+   (docs/adr/0001). */
+@media (max-width: 520px) {
+  .grid {
+    grid-template-columns: 1fr;
+  }
+  .grid ::slotted(*) {
+    grid-column: auto;
+  }
+}

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

@@ -0,0 +1,14 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+type GridGap = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+declare class XmGrid extends LitElement {
+    columns: number;
+    gap: GridGap;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-grid": XmGrid;
+    }
+}
+export {};