npm - @xmesh/system-design - Versions diffs - 0.0.1 - Mend

@xmesh/system-design 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (175) hide show

package/README.md +472 -0
package/assets/brand-lockup-dark.svg +9 -0
package/assets/brand-lockup-light.svg +9 -0
package/assets/brand-mark.svg +9 -0
package/colors_and_type.css +11 -0
package/dist/lit/components/alert/index.css +201 -0
package/dist/lit/components/alert/index.d.ts +25 -0
package/dist/lit/components/alert/index.js +191 -0
package/dist/lit/components/app-bar/index.css +80 -0
package/dist/lit/components/app-bar/index.d.ts +19 -0
package/dist/lit/components/app-bar/index.js +120 -0
package/dist/lit/components/artifact/index.css +166 -0
package/dist/lit/components/artifact/index.d.ts +37 -0
package/dist/lit/components/artifact/index.js +294 -0
package/dist/lit/components/autocomplete/index.css +171 -0
package/dist/lit/components/autocomplete/index.d.ts +47 -0
package/dist/lit/components/autocomplete/index.js +404 -0
package/dist/lit/components/avatar/index.css +62 -0
package/dist/lit/components/avatar/index.d.ts +19 -0
package/dist/lit/components/avatar/index.js +112 -0
package/dist/lit/components/avatar-group/index.css +60 -0
package/dist/lit/components/avatar-group/index.d.ts +19 -0
package/dist/lit/components/avatar-group/index.js +97 -0
package/dist/lit/components/badge/index.css +72 -0
package/dist/lit/components/badge/index.d.ts +18 -0
package/dist/lit/components/badge/index.js +115 -0
package/dist/lit/components/brand-mark/index.css +109 -0
package/dist/lit/components/brand-mark/index.d.ts +24 -0
package/dist/lit/components/brand-mark/index.js +116 -0
package/dist/lit/components/breadcrumbs/index.css +91 -0
package/dist/lit/components/breadcrumbs/index.d.ts +19 -0
package/dist/lit/components/breadcrumbs/index.js +104 -0
package/dist/lit/components/bubble/index.css +182 -0
package/dist/lit/components/bubble/index.d.ts +72 -0
package/dist/lit/components/bubble/index.js +617 -0
package/dist/lit/components/button/index.css +342 -0
package/dist/lit/components/button/index.d.ts +32 -0
package/dist/lit/components/button/index.js +202 -0
package/dist/lit/components/card/index.css +99 -0
package/dist/lit/components/card/index.d.ts +20 -0
package/dist/lit/components/card/index.js +133 -0
package/dist/lit/components/chat/index.css +292 -0
package/dist/lit/components/chat/index.d.ts +74 -0
package/dist/lit/components/chat/index.js +589 -0
package/dist/lit/components/checkbox/index.css +126 -0
package/dist/lit/components/checkbox/index.d.ts +21 -0
package/dist/lit/components/checkbox/index.js +138 -0
package/dist/lit/components/chip/index.css +145 -0
package/dist/lit/components/chip/index.d.ts +30 -0
package/dist/lit/components/chip/index.js +230 -0
package/dist/lit/components/chip-group/index.css +19 -0
package/dist/lit/components/chip-group/index.d.ts +24 -0
package/dist/lit/components/chip-group/index.js +171 -0
package/dist/lit/components/code/index.css +42 -0
package/dist/lit/components/code/index.d.ts +12 -0
package/dist/lit/components/code/index.js +68 -0
package/dist/lit/components/composer/index.css +548 -0
package/dist/lit/components/composer/index.d.ts +67 -0
package/dist/lit/components/composer/index.js +713 -0
package/dist/lit/components/data-table/index.css +166 -0
package/dist/lit/components/data-table/index.d.ts +55 -0
package/dist/lit/components/data-table/index.js +390 -0
package/dist/lit/components/dialog/index.css +124 -0
package/dist/lit/components/dialog/index.d.ts +24 -0
package/dist/lit/components/dialog/index.js +199 -0
package/dist/lit/components/divider/index.css +27 -0
package/dist/lit/components/divider/index.d.ts +13 -0
package/dist/lit/components/divider/index.js +67 -0
package/dist/lit/components/empty-state/index.css +69 -0
package/dist/lit/components/empty-state/index.d.ts +21 -0
package/dist/lit/components/empty-state/index.js +123 -0
package/dist/lit/components/expansion-panel/index.css +120 -0
package/dist/lit/components/expansion-panel/index.d.ts +22 -0
package/dist/lit/components/expansion-panel/index.js +174 -0
package/dist/lit/components/field/index.css +223 -0
package/dist/lit/components/field/index.d.ts +106 -0
package/dist/lit/components/field/index.js +388 -0
package/dist/lit/components/file-input/index.css +257 -0
package/dist/lit/components/file-input/index.d.ts +30 -0
package/dist/lit/components/file-input/index.js +298 -0
package/dist/lit/components/form/index.css +29 -0
package/dist/lit/components/form/index.d.ts +38 -0
package/dist/lit/components/form/index.js +192 -0
package/dist/lit/components/grid/index.css +53 -0
package/dist/lit/components/grid/index.d.ts +14 -0
package/dist/lit/components/grid/index.js +82 -0
package/dist/lit/components/kbd/index.css +35 -0
package/dist/lit/components/kbd/index.d.ts +11 -0
package/dist/lit/components/kbd/index.js +43 -0
package/dist/lit/components/list/index.css +15 -0
package/dist/lit/components/list/index.d.ts +28 -0
package/dist/lit/components/list/index.js +188 -0
package/dist/lit/components/list-item/index.css +119 -0
package/dist/lit/components/list-item/index.d.ts +20 -0
package/dist/lit/components/list-item/index.js +127 -0
package/dist/lit/components/menu/index.css +94 -0
package/dist/lit/components/menu/index.d.ts +47 -0
package/dist/lit/components/menu/index.js +386 -0
package/dist/lit/components/navigation-drawer/index.css +114 -0
package/dist/lit/components/navigation-drawer/index.d.ts +29 -0
package/dist/lit/components/navigation-drawer/index.js +218 -0
package/dist/lit/components/overlay/index.css +171 -0
package/dist/lit/components/overlay/index.d.ts +65 -0
package/dist/lit/components/overlay/index.js +566 -0
package/dist/lit/components/pagination/index.css +102 -0
package/dist/lit/components/pagination/index.d.ts +22 -0
package/dist/lit/components/pagination/index.js +184 -0
package/dist/lit/components/primitives/index.css +504 -0
package/dist/lit/components/primitives/index.d.ts +25 -0
package/dist/lit/components/primitives/index.js +283 -0
package/dist/lit/components/progress/index.css +143 -0
package/dist/lit/components/progress/index.d.ts +23 -0
package/dist/lit/components/progress/index.js +180 -0
package/dist/lit/components/radio-group/index.css +178 -0
package/dist/lit/components/radio-group/index.d.ts +35 -0
package/dist/lit/components/radio-group/index.js +292 -0
package/dist/lit/components/select/index.css +151 -0
package/dist/lit/components/select/index.d.ts +50 -0
package/dist/lit/components/select/index.js +390 -0
package/dist/lit/components/sidebar-item/index.css +133 -0
package/dist/lit/components/sidebar-item/index.d.ts +20 -0
package/dist/lit/components/sidebar-item/index.js +105 -0
package/dist/lit/components/skeleton/index.css +81 -0
package/dist/lit/components/skeleton/index.d.ts +19 -0
package/dist/lit/components/skeleton/index.js +119 -0
package/dist/lit/components/slider/index.css +171 -0
package/dist/lit/components/slider/index.d.ts +36 -0
package/dist/lit/components/slider/index.js +302 -0
package/dist/lit/components/snackbar/index.css +279 -0
package/dist/lit/components/snackbar/index.d.ts +33 -0
package/dist/lit/components/snackbar/index.js +195 -0
package/dist/lit/components/stack/index.css +41 -0
package/dist/lit/components/stack/index.d.ts +20 -0
package/dist/lit/components/stack/index.js +103 -0
package/dist/lit/components/switch/index.css +126 -0
package/dist/lit/components/switch/index.d.ts +17 -0
package/dist/lit/components/switch/index.js +116 -0
package/dist/lit/components/table/index.css +85 -0
package/dist/lit/components/table/index.d.ts +25 -0
package/dist/lit/components/table/index.js +139 -0
package/dist/lit/components/tabs/index.css +116 -0
package/dist/lit/components/tabs/index.d.ts +49 -0
package/dist/lit/components/tabs/index.js +320 -0
package/dist/lit/components/text-field/index.css +90 -0
package/dist/lit/components/text-field/index.d.ts +17 -0
package/dist/lit/components/text-field/index.js +101 -0
package/dist/lit/components/textarea/index.css +55 -0
package/dist/lit/components/textarea/index.d.ts +26 -0
package/dist/lit/components/textarea/index.js +124 -0
package/dist/lit/components/tooltip/index.css +37 -0
package/dist/lit/components/tooltip/index.d.ts +31 -0
package/dist/lit/components/tooltip/index.js +196 -0
package/dist/lit/components/validation/index.css +386 -0
package/dist/lit/components/validation/index.d.ts +45 -0
package/dist/lit/components/validation/index.js +318 -0
package/dist/lit/index.d.ts +50 -0
package/dist/lit/index.js +59 -0
package/package.json +81 -0
package/styles/README.md +346 -0
package/styles/_elevation.css +24 -0
package/styles/_fonts.css +6 -0
package/styles/_layout.css +37 -0
package/styles/_primitives.css +154 -0
package/styles/_scroll.css +75 -0
package/styles/_semantic.css +146 -0
package/styles/_space.css +61 -0
package/styles/_type.css +139 -0
package/styles/_xmesh-extensions.css +232 -0
package/styles/index.css +44 -0
package/styles/md3/_color.css +102 -0
package/styles/md3/_elevation.css +26 -0
package/styles/md3/_motion.css +35 -0
package/styles/md3/_shape.css +22 -0
package/styles/md3/_state.css +22 -0
package/styles/md3/_type.css +111 -0

package/dist/lit/components/overlay/index.js ADDED Viewed

@@ -0,0 +1,566 @@
+/*
+  overlay/index.ts — <xm-overlay>, the platform-native overlay foundation.
+  ┌──────────────────────────────────────────────────────────────────────┐
+  │ INTERNAL FOUNDATION (FR-141 / AD-5 / AD-12).                           │
+  │ <xm-overlay> is not a catalog component. It is the single primitive    │
+  │ that xm-dialog, xm-menu, xm-tooltip, xm-select, and xm-autocomplete    │
+  │ COMPOSE so none of them hand-roll divergent stacking, focus-trap, or   │
+  │ positioning. Consumers drive it through the PUBLIC API below — they    │
+  │ never query or style its shadow root, and it never reaches into theirs │
+  │ (AD-12, one-way deps: overlay → tokens, overlay → primitives).         │
+  └──────────────────────────────────────────────────────────────────────┘
+  ── Why platform-native only (the dependency decision, RESOLVED — do not
+     re-litigate: OQ-C → AD-5 / FR-141a) ────────────────────────────────
+    • modal      → native <dialog> + showModal()  (focus-trap + background
+                   `inert` for FREE; we do NOT re-implement a tab cycle)
+    • non-modal  → Popover API (popover="manual", top layer)
+    • positioning→ CSS anchor() / @position-try  (anchored to the consumer's
+                   trigger via a per-instance anchor-name)
+    • scroll-lock→ native (lock <html> overflow while a modal is open)
+  No positioning or focus-trap dependency is bundled. Target is modern
+  evergreen browsers (anchor()/@position-try is Baseline-newly-available:
+  Chrome 125+, Firefox 132+, Safari 26.0+).
+  ── Cross-shadow anchoring (the crux, FR-141) ──────────────────────────
+    CSS `anchor-name` is TREE-SCOPED: a popover in this overlay's shadow root
+    can only resolve an anchor-name set on an element in the SAME tree. A
+    consumer's trigger lives in ANOTHER shadow root, so native anchor() can't
+    see it. When the anchor is cross-root (the common case) the overlay pins a
+    fixed top/left computed from the trigger's getBoundingClientRect() — a
+    built-in, DEPENDENCY-FREE fallback (NOT Floating UI). Same-root anchors
+    keep the pure-CSS anchor() path. Floating UI remains the heavier escape
+    hatch for deep-nested-menu / virtual-row cases only.
+  ── Escape hatch (OFF by default, AD-5a / NFR-16) ──────────────────────
+    A consumer that hits a genuine native edge case — anchor() unavailable,
+    a deep multi-level menu, or virtual-list rows — MAY load Floating UI for
+    THAT component only:
+        import { computePosition, flip, shift } from
+          "https://esm.sh/@floating-ui/dom@1";   // per-consumer escape hatch
+    …and feed the computed top/left to its <xm-overlay> via inline style on
+    a slotted positioner. Such an overlay MUST still declare a `tier` and
+    ride the tier ordering below — it must NEVER invent its own z-index.
+    The DEFAULT build imports NO Floating UI. (Search this file: there is
+    no `@floating-ui` import — that is intentional.)
+  ── PUBLIC API (what consumers compose against) ────────────────────────
+    Attributes / properties
+      open        boolean (reflect)  — declarative open state. Setting it
+                                       true opens, false closes. Also driven
+                                       imperatively by show()/hide().
+      mode        "modal" | "non-modal"   (default "modal")
+                                       modal → <dialog>.showModal() (scrim +
+                                       focus-trap + inert); non-modal → popover.
+      tier        "tooltip"|"menu"|"dialog" (default "dialog")
+                                       fixed stacking tier (see below).
+      placement   "top"|"bottom"|"left"|"right"|"top-start"|"bottom-start"|…
+                                       (default "bottom-start") anchored
+                                       placement for non-modal overlays.
+      .anchor     HTMLElement | null  (PROPERTY, not attribute) the trigger
+                                       to position a non-modal overlay against
+                                       (CSS anchor()). May live in another
+                                       shadow root.
+      .opener     HTMLElement | null  (PROPERTY) element focus is restored to
+                                       on close. Defaults to .anchor, else the
+                                       activeElement at open time. Restores
+                                       cross-shadow-root.
+      label       string             — accessible name for the overlay region.
+    Methods
+      show()      open the overlay (idempotent).
+      hide(reason?: OverlayCloseReason)  close it (idempotent).
+      toggle()    flip open state.
+    Events (bubbles + composed, tier (b) per the shared contract)
+      xm-overlay-open   detail: { tier, mode }
+      xm-overlay-close  detail: { tier, mode, reason }   reason ∈
+                        "escape" | "backdrop" | "api" | "ancestor-closed"
+      A consumer maps xm-overlay-close → its own close/dismiss event.
+    Slots
+      default     overlay content      header  leading region
+      footer      trailing region (action row)
+  ── Stacking tier (fixed, last-opened-wins within a tier — AD-5a) ──────
+    tooltip < menu / select-listbox < dialog. A dialog always paints above a
+    menu; a tooltip never covers a menu. The native top layer already gives
+    last-opened-wins WITHIN one primitive class, but a tooltip popover and a
+    dialog also share the top layer, so tier order is enforced explicitly via
+    `--xm-overlay-z-*` applied to the host (popovers) — modal <dialog>s sit in
+    the top layer above all popovers by spec, which matches `dialog` being the
+    highest tier.
+  ── Innermost-Esc + focus restore (AD-5a / NFR-14) ─────────────────────
+    Esc closes the INNERMOST overlay only: the keydown handler calls
+    stopPropagation() the moment it handles Esc, so one keypress never closes
+    two layers (a popover opened inside a modal closes the popover, not the
+    dialog). Closing a modal closes its descendant popovers (tracked via the
+    opener chain). Focus restores to each layer's opener, innermost-first.
+  ── Tokens (AD-1) ─────────────────────────────────────────────────────
+    Scrim       var(--md-sys-color-scrim) with alpha at the use site (CSS).
+    Surface     inverse-surface family + inverse-on-surface ink (the card
+                stack; AD-13). Elevation level3 (menus/popovers) / level4–5
+                (modals) per DESIGN.md. No blur / backdrop-filter; no gradient.
+  ── shadow-DOM CSS link + BEM (AD-2/3/4) ──────────────────────
+    Lit from lit (never `import "lit"`); CSS <link>
+    inside the shadow root via the built-file-relative new URL(...); BEM block
+    `overlay`, registered in scripts/check-bem.sh STRICT_BLOCKS.
+*/
+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, query } from "lit/decorators.js";
+// Resolve CSS relative to the *built* file:
+// lit/build/components/overlay/index.js → ../overlay/index.css.
+const OVERLAY_CSS = new URL("../overlay/index.css", import.meta.url).href;
+let overlaySeq = 0;
+// Live stack of every open overlay, in open order (last = innermost). Used to
+// route Esc to the innermost layer and to cascade-close descendant popovers
+// when an ancestor (modal) closes.
+const OPEN_STACK = [];
+let XmOverlay = class XmOverlay extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.open = false;
+        this.mode = "modal";
+        this.tier = "dialog";
+        this.placement = "bottom-start";
+        this.label = "";
+        /** 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. */
+        this.anchor = null;
+        /** Element focus is restored to on close. Defaults to `anchor`, else the
+            document's deepest activeElement at open time. */
+        this.opener = null;
+        this._id = `xm-overlay-${++overlaySeq}`;
+        this._anchorName = `--xm-overlay-anchor-${overlaySeq}`;
+        this._restoreFocusTo = null;
+        this._scrollLocked = false;
+        this._wasOpen = false;
+        // Bumped on every _activate so a stale deferred (updateComplete) callback from
+        // a rapid open→close→open within one microtask doesn't double-fire open/show.
+        this._activationSeq = 0;
+        // ── Esc routing (innermost-only) ────────────────────────────────────
+        this._onKeydown = (event) => {
+            if (event.key !== "Escape")
+                return;
+            // Only the innermost open overlay reacts. A capturing listener fires once
+            // per keypress globally; we self-elect by being the last in OPEN_STACK.
+            const innermost = OPEN_STACK[OPEN_STACK.length - 1];
+            if (innermost !== this)
+                return;
+            // We are the innermost: handle and STOP so one Esc never closes two
+            // layers. preventDefault also blocks the native <dialog> cancel path so
+            // we own the close (and its reason/focus restore) uniformly.
+            event.preventDefault();
+            event.stopPropagation();
+            this._deactivate("escape");
+        };
+        // Native <dialog> emits `cancel` on Esc before `close`. We drive Esc through
+        // the capturing handler above, so suppress the native path to avoid a
+        // double-close (and so non-innermost dialogs never self-cancel).
+        this._onDialogCancel = (event) => {
+            event.preventDefault();
+        };
+        this._onDialogClose = () => {
+            // Reached only if something closed the <dialog> outside our API (e.g. form
+            // method=dialog). Sync our state.
+            if (this._wasOpen)
+                this._deactivate("api");
+        };
+        // Light-dismiss for modal: a click on the backdrop (the <dialog> element
+        // itself, outside the surface) closes it. Like Esc, only the innermost open
+        // overlay dismisses — clicking the dialog backdrop while a menu opened from
+        // inside it is open dismisses the menu first, not the whole dialog.
+        this._onDialogClick = (event) => {
+            if (event.target !== this._dialog)
+                return;
+            const innermost = OPEN_STACK[OPEN_STACK.length - 1];
+            if (innermost !== this) {
+                innermost?._deactivate("backdrop");
+                return;
+            }
+            this._deactivate("backdrop");
+        };
+        this._reposition = () => {
+            if (this._wasOpen && this.mode === "non-modal")
+                this._pinToAnchor();
+        };
+    }
+    // The trigger that opened us lives in another shadow root; delegatesFocus
+    // keeps the overlay itself out of the tab order while letting content focus.
+    static { this.shadowRootOptions = {
+        ...LitElement.shadowRootOptions,
+        delegatesFocus: true,
+    }; }
+    render() {
+        const isModal = this.mode === "modal";
+        const cls = `overlay overlay--tier-${this.tier} overlay--${isModal ? "modal" : "non-modal"}`;
+        // The visible surface — shared between the modal <dialog> and the
+        // non-modal popover so the card chrome is authored once.
+        const surface = html `
+      <div class="overlay__surface" part="surface">
+        <slot name="header"></slot>
+        <div class="overlay__body"><slot></slot></div>
+        <slot name="footer"></slot>
+      </div>
+    `;
+        return html `
+      <link rel="stylesheet" href="${OVERLAY_CSS}" />
+      <style>
+        :host {
+          display: contents;
+        }
+        /* Per-instance positioning glue (anchor-name + tier z-index) is set
+           inline so it can carry the runtime anchor reference; the rest of
+           the chrome lives in index.css. */
+        .overlay--non-modal .overlay__popover {
+          z-index: var(${this._tierZVar()});
+          position-anchor: var(--xm-overlay-anchor, ${this._anchorName});
+        }
+        .overlay--non-modal .overlay__popover.overlay__popover--pinned {
+          position-anchor: none;
+        }
+      </style>
+      ${isModal
+            ? html `
+            <dialog
+              id="${this._id}"
+              class="${cls} overlay__dialog"
+              @close=${this._onDialogClose}
+              @cancel=${this._onDialogCancel}
+              @click=${this._onDialogClick}
+            >
+              ${surface}
+            </dialog>
+          `
+            : html `
+            <div
+              id="${this._id}"
+              class="${cls} overlay__popover"
+              popover="manual"
+            >
+              ${surface}
+            </div>
+          `}
+    `;
+    }
+    updated(changed) {
+        if (changed.has("open")) {
+            if (this.open && !this._wasOpen)
+                this._activate();
+            else if (!this.open && this._wasOpen)
+                this._deactivate("api");
+        }
+        if (this.open && (changed.has("anchor") || changed.has("placement"))) {
+            this._applyAnchor();
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        if (this._wasOpen)
+            this._deactivate("api");
+        document.removeEventListener("keydown", this._onKeydown, true);
+    }
+    // ── Public imperative API ───────────────────────────────────────────
+    show() {
+        this.open = true;
+    }
+    hide(reason = "api") {
+        if (!this._wasOpen) {
+            this.open = false;
+            return;
+        }
+        // Route through _deactivate so the close reason is preserved on the event;
+        // the reflected `open` is cleared there.
+        this._deactivate(reason);
+    }
+    toggle() {
+        this.open = !this.open;
+    }
+    // ── Activation ──────────────────────────────────────────────────────
+    _activate() {
+        this._wasOpen = true;
+        // Capture the element to return focus to BEFORE we move focus into the
+        // overlay — but ONLY when this overlay actually moves focus in. A modal
+        // (showModal) traps focus, and a consumer that passed an explicit `opener`
+        // is managing focus; both want it restored on close. A bare non-modal
+        // popover with no opener (e.g. a tooltip shown on hover) never moves focus,
+        // so it must NOT yank focus to the anchor on close (that would steal focus).
+        this._restoreFocusTo =
+            this.mode === "modal"
+                ? this.opener ?? this._deepActiveElement()
+                : this.opener ?? null;
+        OPEN_STACK.push(this);
+        // One capturing keydown listener on the document handles Esc for the whole
+        // stack; it dispatches to the innermost overlay and stops there.
+        document.addEventListener("keydown", this._onKeydown, true);
+        const activation = ++this._activationSeq;
+        // Wait for the dialog/popover element to exist in the shadow root.
+        this.updateComplete.then(() => {
+            // A newer activation (open→close→open within the microtask) superseded
+            // this one — bail so show()/showPopover() and the open event fire once.
+            if (activation !== this._activationSeq)
+                return;
+            if (!this.open)
+                return;
+            if (this.mode === "modal") {
+                const dlg = this._dialog;
+                if (dlg && !dlg.open) {
+                    dlg.showModal(); // focus-trap + background inert, for free
+                    this._lockScroll();
+                }
+            }
+            else {
+                const pop = this._popover;
+                if (pop && !pop.matches(":popover-open")) {
+                    this._applyAnchor();
+                    try {
+                        pop.showPopover();
+                    }
+                    catch {
+                        // Popover may already be open (race) — ignore.
+                    }
+                    // Re-pin once the popover is laid out so offsetWidth/Height are real
+                    // (the cross-root fallback needs the rendered size to place + clamp).
+                    if (pop.classList.contains("overlay__popover--pinned")) {
+                        this._pinToAnchor();
+                    }
+                }
+            }
+            this.dispatchEvent(new CustomEvent("xm-overlay-open", {
+                bubbles: true,
+                composed: true,
+                detail: { tier: this.tier, mode: this.mode },
+            }));
+        });
+    }
+    _deactivate(reason) {
+        if (!this._wasOpen)
+            return;
+        this._wasOpen = false;
+        const idx = OPEN_STACK.indexOf(this);
+        if (idx !== -1)
+            OPEN_STACK.splice(idx, 1);
+        // Each open overlay registers its OWN bound listener, so each must remove
+        // its own — removing only when the stack empties leaks the inner layers'
+        // listeners (and double-fires them on re-open).
+        document.removeEventListener("keydown", this._onKeydown, true);
+        window.removeEventListener("scroll", this._reposition, true);
+        window.removeEventListener("resize", this._reposition);
+        // Cascade: closing a modal closes any popover opened from inside it. Walk
+        // the stack for descendants whose opener resolves to inside this overlay.
+        if (this.mode === "modal") {
+            for (const other of [...OPEN_STACK]) {
+                if (this.contains(other) || this._ownsOpener(other)) {
+                    other._deactivate("ancestor-closed");
+                }
+            }
+        }
+        if (this.mode === "modal") {
+            const dlg = this._dialog;
+            if (dlg?.open)
+                dlg.close();
+            this._unlockScroll();
+        }
+        else {
+            const pop = this._popover;
+            if (pop?.matches(":popover-open")) {
+                try {
+                    pop.hidePopover();
+                }
+                catch {
+                    // Already hidden — ignore.
+                }
+            }
+        }
+        this.open = false;
+        // Innermost-first focus restore: restore to this layer's opener. Because
+        // the stack unwinds innermost-first (Esc hits the innermost first), each
+        // layer restores in turn. Works cross-shadow-root: we hold the element ref.
+        this._restoreFocus();
+        this.dispatchEvent(new CustomEvent("xm-overlay-close", {
+            bubbles: true,
+            composed: true,
+            detail: { tier: this.tier, mode: this.mode, reason },
+        }));
+    }
+    // ── Anchored positioning (CSS anchor()) ─────────────────────────────
+    _applyAnchor() {
+        const pop = this._popover;
+        if (!pop)
+            return;
+        pop.dataset["placement"] = this.placement;
+        if (!this.anchor)
+            return;
+        // CSS anchor-name is TREE-SCOPED: a popover in this overlay's shadow root
+        // can only resolve an anchor-name set on an element in the SAME tree. When
+        // the consumer's trigger lives in another shadow root (the common case),
+        // native anchor() can't see it — so we pin a fixed top/left computed from
+        // the trigger's bounding rect (no dependency). Same-root anchors keep the
+        // pure-CSS anchor() path.
+        if (this._sameTreeScope(this.anchor)) {
+            pop.classList.remove("overlay__popover--pinned");
+            this.anchor.style.setProperty("anchor-name", this._anchorName);
+            pop.style.setProperty("--xm-overlay-anchor", this._anchorName);
+        }
+        else {
+            pop.classList.add("overlay__popover--pinned");
+            this._pinToAnchor();
+            // Keep the pin glued to the trigger while open (scroll/resize).
+            window.addEventListener("scroll", this._reposition, true);
+            window.addEventListener("resize", this._reposition);
+        }
+    }
+    // The popover lives in this element's shadow root; an anchor is in the same
+    // tree scope only if its root node is this shadow root (it never is for a
+    // consumer trigger) — so in practice this is the consumer-supplied-same-root
+    // escape valve. Kept as an explicit check so the native path is taken
+    // whenever it actually can resolve.
+    _sameTreeScope(anchor) {
+        return anchor.getRootNode() === this.renderRoot;
+    }
+    _pinToAnchor() {
+        const pop = this._popover;
+        if (!pop || !this.anchor)
+            return;
+        const a = this.anchor.getBoundingClientRect();
+        // A display:none / zero-size anchor returns an all-zero rect — pinning to it
+        // would land the popover in the top-left corner. Hide instead of mispinning.
+        if (a.width === 0 && a.height === 0) {
+            pop.style.setProperty("visibility", "hidden");
+            return;
+        }
+        // The anchor is fully off-screen — clamping would detach the popover and
+        // leave it floating at a viewport edge with no trigger. Hide it; a later
+        // scroll/resize re-runs this and reveals it once the anchor returns.
+        if (a.bottom <= 0 ||
+            a.top >= window.innerHeight ||
+            a.right <= 0 ||
+            a.left >= window.innerWidth) {
+            pop.style.setProperty("visibility", "hidden");
+            return;
+        }
+        pop.style.removeProperty("visibility");
+        const gap = 4;
+        const w = pop.offsetWidth;
+        const h = pop.offsetHeight;
+        const place = this.placement;
+        const main = place.split("-")[0];
+        const align = place.includes("-") ? place.split("-")[1] : "center";
+        let top;
+        let left;
+        // Cross-axis alignment for a given edge length: start | end | center.
+        const alignAxis = (start, end, size) => align === "end" ? end - size : align === "start" ? start : start + (end - start) / 2 - size / 2;
+        if (main === "top") {
+            top = a.top - h - gap;
+            left = alignAxis(a.left, a.right, w);
+        }
+        else if (main === "left") {
+            left = a.left - w - gap;
+            top = alignAxis(a.top, a.bottom, h);
+        }
+        else if (main === "right") {
+            left = a.right + gap;
+            top = alignAxis(a.top, a.bottom, h);
+        }
+        else {
+            // bottom (default)
+            top = a.bottom + gap;
+            left = alignAxis(a.left, a.right, w);
+        }
+        // Clamp into the viewport so a popover near an edge stays visible.
+        const margin = 8;
+        left = Math.max(margin, Math.min(left, window.innerWidth - w - margin));
+        top = Math.max(margin, Math.min(top, window.innerHeight - h - margin));
+        pop.style.setProperty("--xm-overlay-pin-top", `${Math.round(top)}px`);
+        pop.style.setProperty("--xm-overlay-pin-left", `${Math.round(left)}px`);
+    }
+    // ── Scroll lock (native, no library) ────────────────────────────────
+    _lockScroll() {
+        if (this._scrollLocked)
+            return;
+        this._scrollLocked = true;
+        document.documentElement.style.setProperty("--xm-overlay-scroll-lock", "hidden");
+        document.documentElement.style.overflow = "hidden";
+    }
+    _unlockScroll() {
+        if (!this._scrollLocked)
+            return;
+        this._scrollLocked = false;
+        // Only release if no other modal still holds the lock.
+        const stillModal = OPEN_STACK.some((o) => o.mode === "modal");
+        if (!stillModal) {
+            document.documentElement.style.removeProperty("overflow");
+            document.documentElement.style.removeProperty("--xm-overlay-scroll-lock");
+        }
+    }
+    // ── Focus helpers (cross-shadow-root) ───────────────────────────────
+    _restoreFocus() {
+        const target = this._restoreFocusTo;
+        this._restoreFocusTo = null;
+        if (target && typeof target.focus === "function" && target.isConnected) {
+            target.focus();
+        }
+    }
+    // Pierce shadow roots to find the truly focused element so restore works
+    // when the trigger sits in a nested shadow tree.
+    _deepActiveElement() {
+        let active = document.activeElement;
+        while (active?.shadowRoot?.activeElement) {
+            active = active.shadowRoot.activeElement;
+        }
+        return active instanceof HTMLElement ? active : null;
+    }
+    _ownsOpener(other) {
+        const op = other.opener ?? other.anchor;
+        return op != null && this.contains(op);
+    }
+    _tierZVar() {
+        // Tier → z-index custom property. Modal <dialog>s ride the native top
+        // layer above all popovers; this var orders popovers among themselves so
+        // a menu sits above a tooltip. A FUI-positioned overlay reuses these.
+        return this.tier === "tooltip"
+            ? "--xm-overlay-z-tooltip"
+            : this.tier === "menu"
+                ? "--xm-overlay-z-menu"
+                : "--xm-overlay-z-dialog";
+    }
+};
+__decorate([
+    property({ type: Boolean, reflect: true })
+], XmOverlay.prototype, "open", void 0);
+__decorate([
+    property({ type: String, reflect: true })
+], XmOverlay.prototype, "mode", void 0);
+__decorate([
+    property({ type: String, reflect: true })
+], XmOverlay.prototype, "tier", void 0);
+__decorate([
+    property({ type: String, reflect: true })
+], XmOverlay.prototype, "placement", void 0);
+__decorate([
+    property({ type: String })
+], XmOverlay.prototype, "label", void 0);
+__decorate([
+    query(".overlay__dialog")
+], XmOverlay.prototype, "_dialog", void 0);
+__decorate([
+    query(".overlay__popover")
+], XmOverlay.prototype, "_popover", void 0);
+XmOverlay = __decorate([
+    customElement("xm-overlay")
+], XmOverlay);
+export { XmOverlay };

package/dist/lit/components/pagination/index.css ADDED Viewed

@@ -0,0 +1,102 @@
+/* ============================================
+   <xm-pagination> — numbered page controls.
+   Surface / ink (AD-13): a transparent control row tracing its host surface.
+   Idle controls take var(--md-sys-color-on-surface-variant) ink; the CURRENT
+   page is a coral chip — var(--md-sys-color-primary) fill + var(--md-sys-color-on-primary)
+   ink (matched to the coral fill). Hairline 1px borders only (2px is reserved
+   for drag-active, not used here). Disabled edges use the shared reduced-
+   emphasis treatment — no error color.
+   BEM: block `pagination`; elements `__item` `__page` `__prev` `__next`
+   `__ellipsis`; modifiers `__page--current`, size `--xs|sm|md|lg`.
+   ============================================ */
+.pagination {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-1);
+}
+/* ---------- Shared control chrome ---------- */
+.pagination__item {
+  appearance: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  border: 1px solid var(--md-sys-color-outline-variant);
+  border-radius: var(--md-sys-shape-corner-button);
+  background: transparent;
+  color: var(--md-sys-color-on-surface-variant);
+  font-family: var(--md-sys-typescale-label-large-font);
+  font-weight: 600;
+  cursor: pointer;
+  user-select: none;
+  transition:
+    background var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard),
+    color var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard),
+    border-color var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard),
+    box-shadow var(--md-sys-motion-duration-short3) var(--md-sys-motion-easing-standard);
+}
+.pagination__item:hover {
+  background: color-mix(
+    in oklab,
+    var(--md-sys-color-on-surface) var(--md-sys-state-hover-state-layer-opacity),
+    transparent
+  );
+  color: var(--md-sys-color-on-surface);
+  border-color: var(--md-sys-color-outline);
+}
+.pagination__item:focus {
+  outline: none;
+}
+.pagination__item:focus-visible {
+  outline: none;
+  box-shadow: var(--xm-state-focus-ring);
+}
+.pagination__item svg {
+  flex-shrink: 0;
+}
+/* ---------- Sizes — one shared control height per size ---------- */
+.pagination--xs .pagination__item { min-width: 22px; height: 22px; padding: 0 var(--s-1); font-size: var(--md-sys-typescale-label-small-size); }
+.pagination--sm .pagination__item { min-width: 26px; height: 26px; padding: 0 var(--s-2); font-size: var(--md-sys-typescale-body-small-size); }
+.pagination--md .pagination__item { min-width: 32px; height: 32px; padding: 0 var(--s-2); font-size: var(--md-sys-typescale-body-medium-size); }
+.pagination--lg .pagination__item { min-width: 42px; height: 42px; padding: 0 var(--s-3); font-size: var(--md-sys-typescale-title-small-size); }
+/* ---------- Current page — coral chip ----------
+   The page digit is text on the coral fill, so it uses --xm-color-primary-fill
+   (the darker coral) for WCAG AA, not the lighter --md-sys-color-primary. */
+.pagination__page--current {
+  background: var(--xm-color-primary-fill);
+  border-color: var(--xm-color-primary-fill);
+  color: var(--md-sys-color-on-primary);
+}
+.pagination__page--current:hover {
+  background: var(--xm-color-primary-fill);
+  border-color: var(--xm-color-primary-fill);
+  color: var(--md-sys-color-on-primary);
+}
+/* ---------- Ellipsis ---------- */
+.pagination__ellipsis {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 24px;
+  color: var(--md-sys-color-on-surface-variant);
+  user-select: none;
+}
+/* ---------- Disabled edges — shared reduced emphasis ---------- */
+.pagination__item[disabled] {
+  cursor: not-allowed;
+  color: var(--xm-color-on-surface-disabled);
+  box-shadow: none;
+}
+.pagination__item[disabled]:hover {
+  background: transparent;
+  color: var(--xm-color-on-surface-disabled);
+  border-color: var(--md-sys-color-outline-variant);
+}