@xmesh/system-design 0.0.1

package/dist/lit/components/navigation-drawer/index.js

@@ -0,0 +1,218 @@
+/*
+  navigation-drawer/index.ts — <xm-navigation-drawer>, the side navigation panel.
+
+  <xm-navigation-drawer> — an edge-anchored navigation container that hosts
+  xm-sidebar-item children. Belongs to the INVERSE-SURFACE family (the card
+  stack), carries the directional drawer shadow, and supports modal (focus-
+  trapped, scrim, inert background) and persistent / collapsed-rail modes.
+
+  Authoring:
+    <xm-navigation-drawer open modal>
+      <xm-sidebar-item title="Overview" active></xm-sidebar-item>
+      <xm-sidebar-item title="Activity"></xm-sidebar-item>
+    </xm-navigation-drawer>
+    el.addEventListener("close", () => (el.open = false));
+
+  Properties:
+    open        boolean (reflected) — declarative open state
+    collapsed   boolean (reflected) — icon-rail mode (persistent)
+    modal       boolean (reflected) — trap focus + inert background + scrim
+    label       string — accessible name for the drawer region
+
+  Events:
+    close       bare component dismiss signal (bubbles + composed, no detail).
+
+  ── Overlay composition (AD-5 / AD-5a — the decision) ──────────────────────
+  xm-overlay's modal mode is a CENTERED card (margin:auto, max-width 560px); it
+  has no edge-placement mode, and AD-12 forbids restyling its shadow root. So
+  the drawer renders its OWN native <dialog> in EDGE layout and reuses the
+  IDENTICAL platform-native modal contract that xm-overlay itself codifies:
+    • showModal()        → focus-trap + background `inert`, for free (AD-5)
+    • <dialog>::backdrop → the scrim
+    • opener capture + .focus() restore on close (NFR-14)
+    • innermost-only Esc: the native top layer routes Esc to the topmost modal;
+      we handle `cancel`, preventDefault, close, dispatch `close`, and
+      stopPropagation so one keypress never closes an enclosing layer (AD-5a)
+    • dialog tier: a modal <dialog> rides the native top layer above every
+      popover by spec — exactly what `dialog` being the highest tier means, so
+      no z-index is invented (AD-5a)
+  This is the same mechanism xm-overlay's own modal path uses — there is no
+  divergent focus-trap or positioning dependency (NFR-16). Persistent / rail
+  mode renders an <aside> with no showModal().
+
+  Shadow DOM; Lit from lit; sibling CSS via the built-
+  file-relative new URL(...). BEM block `nav-drawer` (differs from the element
+  name). Hosts light-DOM xm-sidebar-item children unchanged (AD-12); the panel
+  remaps the surface role tokens so those items read on inverse-surface.
+*/
+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 } from "lit/decorators.js";
+// Resolve CSS relative to the *built* file:
+// lit/build/components/navigation-drawer/index.js → ../...
+const NAV_DRAWER_CSS = new URL("../navigation-drawer/index.css", import.meta.url).href;
+let XmNavigationDrawer = class XmNavigationDrawer extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.open = false;
+        this.collapsed = false;
+        this.modal = false;
+        this.label = "Navigation";
+        this._restoreFocusTo = null;
+        this._wasOpen = false;
+        // Native <dialog> emits `cancel` on Esc. We own the close (and its focus
+        // restore + event) and stopPropagation so one Esc never closes an enclosing
+        // layer — innermost-only (AD-5a).
+        this._onDialogCancel = (event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            this.open = false;
+        };
+        this._onDialogClose = () => {
+            // Reached if the dialog closed outside our API; sync state.
+            if (this._wasOpen) {
+                this._wasOpen = false;
+                this._restoreFocus();
+                this.open = false;
+                this._emitClose();
+            }
+        };
+        // Backdrop click closes the modal drawer.
+        this._onDialogClick = (event) => {
+            if (event.target === this._dialog) {
+                this.open = false;
+            }
+        };
+    }
+    static { this.shadowRootOptions = {
+        ...LitElement.shadowRootOptions,
+        delegatesFocus: true,
+    }; }
+    render() {
+        const cls = [
+            "nav-drawer",
+            this.open ? "nav-drawer--open" : "",
+            this.collapsed ? "nav-drawer--collapsed" : "",
+            this.modal ? "nav-drawer--modal" : "nav-drawer--persistent",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        const panel = html `
+      <nav class="nav-drawer__panel" aria-label=${this.label}>
+        <slot></slot>
+      </nav>
+    `;
+        return html `
+      <link rel="stylesheet" href="${NAV_DRAWER_CSS}" />
+      <style>
+        :host {
+          display: contents;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      ${this.modal
+            ? html `
+            <dialog
+              class="${cls} nav-drawer__dialog"
+              aria-label=${this.label}
+              @cancel=${this._onDialogCancel}
+              @close=${this._onDialogClose}
+              @click=${this._onDialogClick}
+            >
+              ${panel}
+            </dialog>
+          `
+            : html `
+            <aside class="${cls}" aria-hidden=${this.open ? nothing : "true"}>
+              ${panel}
+            </aside>
+          `}
+    `;
+    }
+    updated(changed) {
+        if (changed.has("open") || changed.has("modal")) {
+            if (this.modal) {
+                if (this.open && !this._wasOpen)
+                    this._activateModal();
+                else if (!this.open && this._wasOpen)
+                    this._deactivateModal();
+            }
+            else if (!this.open && this._wasOpen) {
+                // Switched out of modal while open, or closed persistently.
+                this._wasOpen = false;
+            }
+            else if (this.open) {
+                this._wasOpen = true;
+            }
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        if (this._wasOpen)
+            this._deactivateModal(false);
+    }
+    // ── Modal activation (native <dialog> contract) ─────────────────────
+    _activateModal() {
+        this._wasOpen = true;
+        this._restoreFocusTo = this._deepActiveElement();
+        this.updateComplete.then(() => {
+            const dlg = this._dialog;
+            if (dlg && !dlg.open && this.open && this.modal) {
+                dlg.showModal(); // focus-trap + background inert, for free (AD-5)
+            }
+        });
+    }
+    _deactivateModal(dispatch = true) {
+        this._wasOpen = false;
+        const dlg = this._dialog;
+        if (dlg?.open)
+            dlg.close();
+        this._restoreFocus();
+        if (dispatch)
+            this._emitClose();
+    }
+    // ── close event ─────────────────────────────────────────────────────
+    _emitClose() {
+        this.dispatchEvent(new CustomEvent("close", { bubbles: true, composed: true }));
+    }
+    // ── Focus restore (cross-shadow-root) ───────────────────────────────
+    _restoreFocus() {
+        const target = this._restoreFocusTo;
+        this._restoreFocusTo = null;
+        if (target && typeof target.focus === "function" && target.isConnected) {
+            target.focus();
+        }
+    }
+    _deepActiveElement() {
+        let active = document.activeElement;
+        while (active?.shadowRoot?.activeElement) {
+            active = active.shadowRoot.activeElement;
+        }
+        return active instanceof HTMLElement ? active : null;
+    }
+};
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmNavigationDrawer.prototype, "open", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmNavigationDrawer.prototype, "collapsed", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmNavigationDrawer.prototype, "modal", void 0);
+__decorate([
+    property({ type: String })
+], XmNavigationDrawer.prototype, "label", void 0);
+__decorate([
+    query(".nav-drawer__dialog")
+], XmNavigationDrawer.prototype, "_dialog", void 0);
+XmNavigationDrawer = __decorate([
+    customElement("xm-navigation-drawer")
+], XmNavigationDrawer);

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

@@ -0,0 +1,171 @@
+/* ============================================
+   <xm-overlay> — platform-native overlay foundation.
+
+   The single surface that xm-dialog / xm-menu / xm-tooltip / xm-select /
+   xm-autocomplete compose. Modal mode is a native <dialog> (its ::backdrop
+   is the scrim); non-modal mode is a Popover-API element in the top layer,
+   anchored with CSS anchor() / @position-try.
+
+   Surface is the card tier — inverse-surface fill + inverse-on-surface ink
+   (AD-13). Elevation level3 for popovers/menus, level4–5 for modals
+   (DESIGN.md). Scrim is var(--md-sys-color-scrim) with alpha at this use
+   site. No blur / backdrop-filter; no gradient.
+
+   BEM block: `overlay`. Registered in scripts/check-bem.sh STRICT_BLOCKS.
+   Modifiers: --modal / --non-modal · --tier-tooltip / --tier-menu /
+   --tier-dialog. Elements: __dialog (native <dialog>), __popover (popover
+   element), __surface (the card chrome), __body (content region).
+   ============================================ */
+
+/* ---------- Native <dialog> (modal) ---------- */
+/* The <dialog> element is the positioning + top-layer host; its visible card
+   is .overlay__surface inside it. The dialog box itself is transparent so the
+   surface owns the chrome. */
+.overlay__dialog {
+  margin: auto;
+  padding: 0;
+  max-width: min(92vw, 560px);
+  max-height: 86vh;
+  border: none;
+  background: transparent;
+  color: var(--md-sys-color-inverse-on-surface);
+  overflow: visible;
+}
+
+/* The scrim — flat token-alpha fill (DESIGN.md: scrim is pure black, alpha
+   applied at the callsite). No blur. */
+.overlay__dialog::backdrop {
+  background: color-mix(in oklab, var(--md-sys-color-scrim) 48%, transparent);
+  animation: overlay-fade var(--md-sys-motion-duration-short4)
+    var(--md-sys-motion-easing-standard);
+}
+
+/* ---------- Popover (non-modal, anchored) ---------- */
+.overlay__popover {
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: var(--md-sys-color-inverse-on-surface);
+  overflow: visible;
+  /* Top-layer popover, positioned against the viewport. anchor() resolves
+     against the per-instance position-anchor set inline. @position-try flips
+     the popover when it would overflow the viewport. */
+  position: fixed;
+  position-try-fallbacks: flip-block, flip-inline;
+}
+
+/* Native anchor() path — used when the anchor element lives in the SAME tree
+   scope as the popover (anchor-name is tree-scoped). data-placement is set by
+   the element at open time; inset: auto resets so only the chosen edges bind. */
+.overlay__popover[data-placement^="bottom"] {
+  inset: auto;
+  top: anchor(bottom);
+  left: anchor(left);
+  margin-block-start: var(--s-1);
+}
+.overlay__popover[data-placement^="top"] {
+  inset: auto;
+  bottom: anchor(top);
+  left: anchor(left);
+  margin-block-end: var(--s-1);
+}
+.overlay__popover[data-placement^="right"] {
+  inset: auto;
+  left: anchor(right);
+  top: anchor(top);
+  margin-inline-start: var(--s-1);
+}
+.overlay__popover[data-placement^="left"] {
+  inset: auto;
+  right: anchor(left);
+  top: anchor(top);
+  margin-inline-end: var(--s-1);
+}
+
+/* Cross-root fallback path — when the consumer's trigger is in ANOTHER shadow
+   root, CSS anchor-name is NOT visible to this popover (tree-scoped). The
+   element computes a fixed top/left from the trigger's bounding rect (no
+   dependency) and pins them via these custom properties; anchor() is skipped.
+   This is the built-in, dependency-free fallback — Floating UI (the heavier
+   escape hatch) is only for deep/virtual cases, never the common cross-root
+   one. */
+.overlay__popover.overlay__popover--pinned {
+  inset: auto;
+  top: var(--xm-overlay-pin-top, 0);
+  left: var(--xm-overlay-pin-left, 0);
+  position-try-fallbacks: none;
+}
+
+/* ---------- The card surface (shared) ---------- */
+.overlay__surface {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  box-sizing: border-box;
+  border: 1px solid var(--md-sys-color-outline-variant);
+  border-radius: var(--md-sys-shape-corner-large);
+  background: var(--md-sys-color-inverse-surface);
+  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);
+}
+
+/* Elevation per tier: dialogs lift highest (level5), menus/select-listbox
+   sit at popover height (level3), tooltips are the quietest layer (level3
+   too — they never cover a menu, but read as a raised chip). */
+.overlay--modal .overlay__surface {
+  box-shadow: var(--md-sys-elevation-level5);
+  min-width: min(86vw, 320px);
+}
+.overlay--non-modal.overlay--tier-menu .overlay__surface {
+  box-shadow: var(--md-sys-elevation-level3);
+  min-width: 180px;
+}
+.overlay--non-modal.overlay--tier-dialog .overlay__surface {
+  box-shadow: var(--md-sys-elevation-level3);
+}
+.overlay--tier-tooltip .overlay__surface {
+  box-shadow: var(--md-sys-elevation-level3);
+  border-radius: var(--md-sys-shape-corner-small);
+  max-width: 260px;
+}
+
+/* ---------- Content region ---------- */
+.overlay__body {
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  overflow: auto;
+  padding: var(--s-5);
+}
+.overlay--tier-tooltip .overlay__body,
+.overlay--tier-menu .overlay__body {
+  padding: var(--s-2);
+}
+
+/* ---------- Open transition (short4, standard) ---------- */
+@keyframes overlay-fade {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+.overlay__dialog[open],
+.overlay__popover:popover-open {
+  animation: overlay-fade var(--md-sys-motion-duration-short4)
+    var(--md-sys-motion-easing-standard);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .overlay__dialog[open],
+  .overlay__popover:popover-open,
+  .overlay__dialog::backdrop {
+    animation: none;
+  }
+}

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

@@ -0,0 +1,65 @@
+import { LitElement } from "lit";
+import type { PropertyValues, TemplateResult } from "lit";
+export type OverlayTier = "tooltip" | "menu" | "dialog";
+export type OverlayMode = "modal" | "non-modal";
+export type OverlayPlacement = "top" | "bottom" | "left" | "right" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end" | "right-start" | "right-end";
+export type OverlayCloseReason = "escape" | "backdrop" | "api" | "ancestor-closed";
+export interface OverlayCloseDetail {
+    tier: OverlayTier;
+    mode: OverlayMode;
+    reason: OverlayCloseReason;
+}
+export interface OverlayOpenDetail {
+    tier: OverlayTier;
+    mode: OverlayMode;
+}
+export declare class XmOverlay extends LitElement {
+    static shadowRootOptions: ShadowRootInit;
+    open: boolean;
+    mode: OverlayMode;
+    tier: OverlayTier;
+    placement: OverlayPlacement;
+    label: string;
+    /** Trigger element to anchor a non-modal overlay against (CSS anchor()).
+        A property, not an attribute — it is an element reference, possibly from
+        another shadow root. */
+    anchor: HTMLElement | null;
+    /** Element focus is restored to on close. Defaults to `anchor`, else the
+        document's deepest activeElement at open time. */
+    opener: HTMLElement | null;
+    private _dialog;
+    private _popover;
+    private readonly _id;
+    private readonly _anchorName;
+    private _restoreFocusTo;
+    private _scrollLocked;
+    private _wasOpen;
+    private _activationSeq;
+    render(): TemplateResult;
+    protected updated(changed: PropertyValues<this>): void;
+    disconnectedCallback(): void;
+    show(): void;
+    hide(reason?: OverlayCloseReason): void;
+    toggle(): void;
+    private _activate;
+    private _deactivate;
+    private _onKeydown;
+    private _onDialogCancel;
+    private _onDialogClose;
+    private _onDialogClick;
+    private _applyAnchor;
+    private _sameTreeScope;
+    private _reposition;
+    private _pinToAnchor;
+    private _lockScroll;
+    private _unlockScroll;
+    private _restoreFocus;
+    private _deepActiveElement;
+    private _ownsOpener;
+    private _tierZVar;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-overlay": XmOverlay;
+    }
+}