@xmesh/system-design 0.0.1

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

@@ -0,0 +1,124 @@
+/*
+  textarea/index.ts — <xm-textarea>, a multi-line XmField subclass (Story 2.2).
+
+  The only delta from <xm-text-field> is the control: a native <textarea>
+  projected into the base control wrapper via renderControl(), plus `rows`,
+  `auto-grow`, and `max-rows`. Everything else — label row, helper/error row,
+  required marker, focus ring, disabled/readonly/loading, ARIA wiring, form
+  association, and the uncontrolled-first value lifecycle — is inherited from
+  XmField (AD-7), never re-implemented.
+
+  Authoring:
+    <xm-textarea
+      label="Description"
+      rows="4"
+      placeholder="What does this agent do?"
+      helper="Shown on the agent's card."
+    ></xm-textarea>
+
+    <xm-textarea label="Notes" auto-grow max-rows="8"></xm-textarea>
+
+  Value ownership is uncontrolled-first (AD-6): the `value` attribute seeds the
+  initial value once; emitInput / emitChange fire bubbling + composed `input`
+  (per keystroke) and `change` (on commit) with detail.value (AD-8a).
+
+  Keyboard: native <textarea> semantics — Enter inserts a newline, Tab leaves
+  the field (no tab character inserted).
+
+  Shadow DOM. The native <textarea> is already styled by the base's
+  `.field__control textarea` rule; this component's CSS only owns the multi-row
+  geometry. 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, query } from "lit/decorators.js";
+import { XmField } from "../field/index.js";
+const TEXTAREA_CSS = new URL("../textarea/index.css", import.meta.url).href;
+let XmTextarea = class XmTextarea extends XmField {
+    constructor() {
+        super(...arguments);
+        /** Initial visible height in text rows. */
+        this.rows = 3;
+        /** Native placeholder — shown when the live value is empty. */
+        this.placeholder = "";
+        /** Grow the textarea height with content up to `maxRows` (no scroll jitter). */
+        this.autoGrow = false;
+        /** Cap for auto-grow, in rows. Beyond it the textarea scrolls. */
+        this.maxRows = 8;
+        this._onInput = (e) => {
+            this.emitInput(e.target.value);
+            if (this.autoGrow)
+                this._resize();
+        };
+        this._onChange = (e) => {
+            this.emitChange(e.target.value);
+        };
+    }
+    updated(changed) {
+        super.updated?.(changed);
+        if (this.autoGrow)
+            this._resize();
+    }
+    /** Reset then snap to scrollHeight, clamped to maxRows. Reading scrollHeight
+        after a height reset is the only reliable shrink-and-grow measurement;
+        it's a single synchronous layout read per input, not an animation. */
+    _resize() {
+        const ta = this._textarea;
+        if (!ta)
+            return;
+        ta.style.height = "auto";
+        const cs = getComputedStyle(ta);
+        const lineHeight = parseFloat(cs.lineHeight) || 20;
+        const padV = parseFloat(cs.paddingTop) + parseFloat(cs.paddingBottom);
+        const max = lineHeight * this.maxRows + padV;
+        const next = Math.min(ta.scrollHeight, max);
+        ta.style.height = `${next}px`;
+        ta.style.overflowY = ta.scrollHeight > max ? "auto" : "hidden";
+    }
+    renderControl() {
+        const a = this.controlAria;
+        const controlCls = `textarea__control${this.autoGrow ? " textarea__control--auto-grow" : ""}`;
+        return html `
+      <link rel="stylesheet" href="${TEXTAREA_CSS}" />
+      <textarea
+        class="${controlCls}"
+        id=${a.id}
+        rows=${this.rows}
+        .value=${this._value}
+        placeholder=${this.placeholder || nothing}
+        name=${this.name || nothing}
+        aria-describedby=${a.describedBy ?? nothing}
+        aria-invalid=${a.invalid ?? "false"}
+        ?required=${this.required}
+        ?disabled=${this.effectiveDisabled}
+        ?readonly=${this.readonly}
+        @input=${this._onInput}
+        @change=${this._onChange}
+      ></textarea>
+    `;
+    }
+};
+__decorate([
+    property({ type: Number })
+], XmTextarea.prototype, "rows", void 0);
+__decorate([
+    property({ type: String })
+], XmTextarea.prototype, "placeholder", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "auto-grow" })
+], XmTextarea.prototype, "autoGrow", void 0);
+__decorate([
+    property({ type: Number, attribute: "max-rows" })
+], XmTextarea.prototype, "maxRows", void 0);
+__decorate([
+    query(".textarea__control")
+], XmTextarea.prototype, "_textarea", void 0);
+XmTextarea = __decorate([
+    customElement("xm-textarea")
+], XmTextarea);
+export { XmTextarea };

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

@@ -0,0 +1,37 @@
+/* ============================================
+   Tooltip — a small anchored contextual label.
+
+   The surface chrome (inverse-surface fill, inverse-on-surface ink, hairline
+   border, level3 elevation, small radius, edge-flip) is owned by the composed
+   <xm-overlay> in the `tooltip` tier — this file styles only the LABEL the
+   tooltip projects into the overlay, plus the trigger wrapper.
+
+   The label is a neutral, sentence-cased description — NO severity color, no
+   per-severity hue (AD-11). The ink is inverse-on-surface, inherited from the
+   overlay surface; it is restated here so the label reads correctly even if the
+   cascade is interrupted.
+
+   Motion (short3 fade/translate) is owned by the overlay's open transition.
+
+   BEM block: `tooltip`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   Elements: __trigger (the anchored control wrapper), __label (the copy).
+   ============================================ */
+
+.tooltip__trigger {
+  display: inline-flex;
+  align-items: center;
+}
+
+.tooltip__label {
+  display: block;
+  max-width: 240px;
+  /* Compact label scale; sentence case enforced by content, no transform. */
+  font-family: var(--md-sys-typescale-body-small-font);
+  font-size: var(--md-sys-typescale-body-small-size);
+  line-height: var(--md-sys-typescale-body-small-line-height);
+  letter-spacing: var(--md-sys-typescale-body-small-tracking);
+  /* Neutral popover-stack ink (matches the overlay surface). */
+  color: var(--md-sys-color-inverse-on-surface);
+  padding: var(--s-1) var(--s-2);
+  text-wrap: pretty;
+}

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

@@ -0,0 +1,31 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+import type { OverlayPlacement } from "../overlay/index.js";
+export declare class XmTooltip extends LitElement {
+    text: string;
+    placement: OverlayPlacement;
+    openDelay: number;
+    open: boolean;
+    private _visible;
+    private _overlay;
+    private _triggerWrap;
+    private readonly _labelId;
+    private _showTimer;
+    disconnectedCallback(): void;
+    render(): TemplateResult;
+    updated(): void;
+    private _wireDescribedBy;
+    private get _triggerEl();
+    private _onEnter;
+    private _onLeave;
+    private _onFocusIn;
+    private _onFocusOut;
+    private _show;
+    private _hide;
+    private _onOverlayClose;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-tooltip": XmTooltip;
+    }
+}

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

@@ -0,0 +1,196 @@
+/*
+  tooltip/index.ts — <xm-tooltip>, a hover/focus contextual label.
+
+  Composes the xm-overlay foundation (Story 1.4) for anchored positioning and
+  top-layer stacking — it does NOT hand-roll anchoring math or z-index. The
+  overlay runs in the `tooltip` tier (the LOWEST tier: tooltip < menu < dialog),
+  so a tooltip never covers a menu or dialog. We drive the overlay through its
+  PUBLIC API only (mode / tier / placement / .anchor / .opener / show / hide /
+  xm-overlay-close) and never reach into its shadow root (AD-12).
+
+  Behaviour (FR-145 / UX-DR6):
+    • appears on the trigger being HOVERED or keyboard-FOCUSED
+    • dismissed on blur, mouse-leave, and Esc
+    • Esc is owned by the overlay's innermost-only handler (stopPropagation),
+      so Esc dismisses only the tooltip, never a parent menu/dialog (AD-5a)
+
+  A11y (UX-DR7): the label gets role="tooltip" + an id; the trigger references it
+  via aria-describedby. The tooltip is not focusable and never steals focus.
+
+  Copy is a neutral, sentence-cased label — NO severity color (AD-11). The
+  surface is the inverse-surface popover stack (the overlay owns the chrome).
+
+  Authoring:
+    <xm-tooltip text="Copy to clipboard">
+      <xm-button slot="trigger" icon-only aria-label="Copy">…</xm-button>
+    </xm-tooltip>
+  or with rich label content:
+    <xm-tooltip>
+      <button slot="trigger">Help</button>
+      Opens the keyboard shortcut reference.
+    </xm-tooltip>
+
+  Properties:
+    text         plain-string label (alternative to the default slot)
+    placement    overlay placement (default "top")
+    open-delay   ms before showing on hover (default 100; within motion budget)
+    open         reflect-only mirror of the visible state (also a preview hook)
+
+  Shadow DOM. Depends on xm-overlay + tokens (AD-12). 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, query, state } from "lit/decorators.js";
+const TOOLTIP_CSS = new URL("../tooltip/index.css", import.meta.url).href;
+let tooltipSeq = 0;
+let XmTooltip = class XmTooltip extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.text = "";
+        this.placement = "top";
+        this.openDelay = 100;
+        this.open = false;
+        this._visible = false;
+        this._labelId = `xm-tooltip-${++tooltipSeq}`;
+        this._showTimer = 0;
+        // Wire the trigger's aria-describedby to the label id so SRs read the tooltip
+        // as the trigger's description (the tooltip is not in the tab order).
+        this._wireDescribedBy = (e) => {
+            const slot = e.target;
+            const el = slot.assignedElements()[0];
+            if (el)
+                el.setAttribute("aria-describedby", this._labelId);
+        };
+        this._onEnter = () => {
+            window.clearTimeout(this._showTimer);
+            this._showTimer = window.setTimeout(() => this._show(), this.openDelay);
+        };
+        this._onLeave = () => {
+            window.clearTimeout(this._showTimer);
+            this._hide();
+        };
+        // Keyboard focus shows immediately (no hover delay) so it tracks the caret.
+        this._onFocusIn = () => {
+            window.clearTimeout(this._showTimer);
+            this._show();
+        };
+        this._onFocusOut = () => {
+            window.clearTimeout(this._showTimer);
+            this._hide();
+        };
+        // The overlay owns Esc (innermost-only, stopPropagation). When it self-closes
+        // for any reason, sync our state so a later hover re-opens cleanly.
+        this._onOverlayClose = () => {
+            if (this._visible) {
+                this._visible = false;
+                this.open = false;
+            }
+        };
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        window.clearTimeout(this._showTimer);
+    }
+    render() {
+        return html `
+      <link rel="stylesheet" href="${TOOLTIP_CSS}" />
+      <style>
+        :host { display: inline-flex; }
+      </style>
+      <span
+        class="tooltip__trigger"
+        @mouseenter=${this._onEnter}
+        @mouseleave=${this._onLeave}
+        @focusin=${this._onFocusIn}
+        @focusout=${this._onFocusOut}
+      >
+        <slot name="trigger" @slotchange=${this._wireDescribedBy}></slot>
+      </span>
+
+      <xm-overlay
+        mode="non-modal"
+        tier="tooltip"
+        placement=${this.placement}
+        @xm-overlay-close=${this._onOverlayClose}
+      >
+        <div id=${this._labelId} class="tooltip__label" role="tooltip">
+          ${this.text ? this.text : html `<slot></slot>`}
+        </div>
+      </xm-overlay>
+    `;
+    }
+    updated() {
+        // Keep the reflected `open` mirror in sync for preview/static hooks.
+        if (this.open !== this._visible) {
+            if (this.open && !this._visible)
+                this._show();
+            else if (!this.open && this._visible)
+                this._hide();
+        }
+    }
+    get _triggerEl() {
+        const slot = this.renderRoot.querySelector('slot[name="trigger"]');
+        return slot?.assignedElements()[0] ?? this._triggerWrap;
+    }
+    _show() {
+        if (this._visible)
+            return;
+        this._visible = true;
+        this.open = true;
+        this.updateComplete.then(() => {
+            // Guard the deferred show: a hover-out (or focusout) before this microtask
+            // runs sets `_visible=false`; without this check the queued show() would
+            // open a tooltip the component already considers hidden, and no later
+            // _hide() could close it (every _hide early-returns on !_visible).
+            if (!this._visible)
+                return;
+            const ov = this._overlay;
+            const anchor = this._triggerEl;
+            if (ov && anchor) {
+                ov.anchor = anchor;
+                // The tooltip never steals focus, so do not set .opener (no focus
+                // restore needed — focus stays on the trigger throughout).
+                ov.show();
+            }
+        });
+    }
+    _hide() {
+        if (!this._visible)
+            return;
+        this._visible = false;
+        this.open = false;
+        const ov = this._overlay;
+        if (ov?.open)
+            ov.hide("api");
+    }
+};
+__decorate([
+    property({ type: String })
+], XmTooltip.prototype, "text", void 0);
+__decorate([
+    property({ type: String })
+], XmTooltip.prototype, "placement", void 0);
+__decorate([
+    property({ type: Number, attribute: "open-delay" })
+], XmTooltip.prototype, "openDelay", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmTooltip.prototype, "open", void 0);
+__decorate([
+    state()
+], XmTooltip.prototype, "_visible", void 0);
+__decorate([
+    query("xm-overlay")
+], XmTooltip.prototype, "_overlay", void 0);
+__decorate([
+    query(".tooltip__trigger")
+], XmTooltip.prototype, "_triggerWrap", void 0);
+XmTooltip = __decorate([
+    customElement("xm-tooltip")
+], XmTooltip);
+export { XmTooltip };