@threadlabs/looma 0.3.1 → 0.5.0

package/README.md

@@ -1,23 +1,54 @@
 # @threadlabs/looma
 
-The public Looma package. Install it once, then import only the framework and
-feature subpaths your application uses.
+Looma's components, written once as [Declarative HTML Components](https://nextwebwg.org/html-next/)
+and shipped three ways: as HTML, as Vue components, and as plain DOM factories.
 
 ```sh
 pnpm add @threadlabs/looma
 ```
 
+## Vue
+
+```ts
+import "@threadlabs/looma/tokens.css";
+import "@threadlabs/looma/vue.css";
+import { Button, TopBar } from "@threadlabs/looma/vue";
+```
+
+The Vue components are ordinary Vue 3.5 single-file components, compiled to JavaScript with
+declarations; the `.vue` sources ship beside them. They depend on Vue and Looma only.
+
+The editor is Tiptap-based and needs `@tiptap/vue-3@^2.11.5`:
+
 ```ts
-import { openOverlay } from "@threadlabs/looma";
-import { TopBar } from "@threadlabs/looma/vue";
 import { LoomaEditor } from "@threadlabs/looma/vue/editor";
+import { getDefaultEditorExtensions } from "@threadlabs/looma/editor/extensions";
 ```
 
-Vue and Tiptap are optional to the package as a whole. `/vue` needs only Vue 3.5
-or newer. Looma's `/editor` and `/vue/editor` surfaces are Tiptap-backed and
-ship Looma's concrete extension set within those subpaths. `/vue/editor` consumers
-must also install `@tiptap/vue-3@^2.11.5`; `LoomaEditor` owns the Tiptap lifecycle,
-formatting toolbar, slash menu, bounded mention suggestions, image insertion,
-and table editing. `/editor/ui`
-is the low-level UI-only boundary. See the
-repository getting-started guide for the full CSS and adapter setup.
+The editor components' event and geometry types, without Tiptap, are in
+`@threadlabs/looma/editor/ui`.
+
+## HTML
+
+```html
+<link rel="stylesheet" href="…/@threadlabs/looma/tokens.css">
+<script type="module">
+  import "@threadlabs/looma";
+</script>
+
+<ui-stack gap="m">
+  <ui-button variant="solid">Save</ui-button>
+</ui-stack>
+```
+
+Importing the package registers every component with the
+[HTML Next runtime](https://www.npmjs.com/package/@nextwebwg/declarative-components), which turns
+each `<ui-*>` element into its native root. Each component's styles are scoped to it; the token
+stylesheet is the only stylesheet to include. Without a build, link components one by one from
+`@threadlabs/looma/components/<tag>/<tag>.html`.
+
+## Theming
+
+Components read design tokens (`--ui-*` custom properties) from `tokens.css` and a theme
+(`theme-light.css`, `theme-dark.css`, `theme-high-contrast.css`), and each exposes its own
+`--ui-<component>-*` properties. Set them on the component or any ancestor.

package/components/shared/editor.js

@@ -0,0 +1,69 @@
+export const backgrounds = [
+  ["background-none", "Default", ""], ["background-gray", "Gray", "#f3f4f6"],
+  ["background-yellow", "Yellow", "#fef3c7"], ["background-blue", "Blue", "#dbeafe"],
+  ["background-green", "Green", "#dcfce7"], ["background-red", "Red", "#fee2e2"],
+];
+
+// Serialized from Looma's framework-neutral icon catalog. Keeping the icon nodes here lets the
+// migration controllers stay directly importable in a browser without introducing a bundler-only
+// package resolution step.
+export const icons = {
+  "align-left": [["path", { d: "M21 5H3" }], ["path", { d: "M15 12H3" }], ["path", { d: "M17 19H3" }]],
+  "align-center": [["path", { d: "M21 5H3" }], ["path", { d: "M17 12H7" }], ["path", { d: "M19 19H5" }]],
+  "align-right": [["path", { d: "M21 5H3" }], ["path", { d: "M21 12H9" }], ["path", { d: "M21 19H7" }]],
+  rows: [["rect", { width: "18", height: "18", x: "3", y: "3", rx: "2" }], ["path", { d: "M21 9H3" }], ["path", { d: "M21 15H3" }]],
+  columns: [["rect", { width: "18", height: "18", x: "3", y: "3", rx: "2" }], ["path", { d: "M9 3v18" }], ["path", { d: "M15 3v18" }]],
+  table: [["path", { d: "M9 3H5a2 2 0 0 0-2 2v4m6-6h10a2 2 0 0 1 2 2v4M9 3v18m0 0h10a2 2 0 0 0 2-2V9M9 21H5a2 2 0 0 1-2-2V9m0 0h18" }]],
+  "chevron-down": [["path", { d: "m6 9 6 6 6-6" }]],
+  "panel-top": [["rect", { width: "18", height: "18", x: "3", y: "3", rx: "2" }], ["path", { d: "M3 9h18" }]],
+  "panel-bottom": [["rect", { width: "18", height: "18", x: "3", y: "3", rx: "2" }], ["path", { d: "M3 15h18" }]],
+  "panel-left": [["rect", { width: "18", height: "18", x: "3", y: "3", rx: "2" }], ["path", { d: "M9 3v18" }]],
+  "panel-right": [["rect", { width: "18", height: "18", x: "3", y: "3", rx: "2" }], ["path", { d: "M15 3v18" }]],
+  eraser: [["path", { d: "M21 21H8a2 2 0 0 1-1.42-.587l-3.994-3.999a2 2 0 0 1 0-2.828l10-10a2 2 0 0 1 2.829 0l5.999 6a2 2 0 0 1 0 2.828L12.834 21" }], ["path", { d: "m5.082 11.09 8.828 8.828" }]],
+  merge: [["path", { d: "m8 6 4-4 4 4" }], ["path", { d: "M12 2v10.3a4 4 0 0 1-1.172 2.872L4 22" }], ["path", { d: "m20 22-5-5" }]],
+  split: [["path", { d: "M16 3h5v5" }], ["path", { d: "M8 3H3v5" }], ["path", { d: "M12 22v-8.3a4 4 0 0 0-1.172-2.872L3 3" }], ["path", { d: "m15 9 6-6" }]],
+  trash: [["path", { d: "M10 11v6" }], ["path", { d: "M14 11v6" }], ["path", { d: "M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6" }], ["path", { d: "M3 6h18" }], ["path", { d: "M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2" }]],
+  plus: [["path", { d: "M5 12h14" }], ["path", { d: "M12 5v14" }]],
+  "grip-vertical": [["circle", { cx: "9", cy: "12", r: "1" }], ["circle", { cx: "9", cy: "5", r: "1" }], ["circle", { cx: "9", cy: "19", r: "1" }], ["circle", { cx: "15", cy: "12", r: "1" }], ["circle", { cx: "15", cy: "5", r: "1" }], ["circle", { cx: "15", cy: "19", r: "1" }]],
+  "grip-horizontal": [["circle", { cx: "12", cy: "9", r: "1" }], ["circle", { cx: "19", cy: "9", r: "1" }], ["circle", { cx: "5", cy: "9", r: "1" }], ["circle", { cx: "12", cy: "15", r: "1" }], ["circle", { cx: "19", cy: "15", r: "1" }], ["circle", { cx: "5", cy: "15", r: "1" }]],
+  "heading-1": [["path", { d: "M4 12h8" }], ["path", { d: "M4 18V6" }], ["path", { d: "M12 18V6" }], ["path", { d: "m17 12 3-2v8" }]],
+  pilcrow: [["path", { d: "M13 4v16" }], ["path", { d: "M17 4v16" }], ["path", { d: "M19 4H9.5a4.5 4.5 0 0 0 0 9H13" }]],
+  quote: [["path", { d: "M16 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1v2a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z" }], ["path", { d: "M5 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1v2a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z" }]],
+};
+
+export function normalizeAnchor(value) {
+  if (!value || typeof value !== "object") return null;
+  const finite = (candidate) => typeof candidate === "number" && Number.isFinite(candidate) ? candidate : null;
+  const x = finite(value.x); const y = finite(value.y); const width = finite(value.width); const height = finite(value.height);
+  const left = finite(value.left) ?? x; const top = finite(value.top) ?? y;
+  const right = finite(value.right) ?? (left !== null && width !== null ? left + width : null);
+  const bottom = finite(value.bottom) ?? (top !== null && height !== null ? top + height : null);
+  return left === null || top === null || right === null || bottom === null ? null : { left, top, right, bottom };
+}
+
+export function viewport() {
+  const visual = window.visualViewport;
+  const left = visual?.offsetLeft ?? 0; const top = visual?.offsetTop ?? 0;
+  const width = visual?.width ?? window.innerWidth; const height = visual?.height ?? window.innerHeight;
+  return { left, top, width, height, right: left + width, bottom: top + height };
+}
+
+/**
+ * Places a floating menu below its anchor (or above, when there is more room), or as a bottom sheet on
+ * narrow screens.
+ */
+export function positionMenu(element, rect, width) {
+  if (!rect) return;
+  const view = viewport();
+  Object.assign(element.style, { position: "fixed", zIndex: "500" });
+  if (window.innerWidth < 768) {
+    const height = Math.min(320, Math.max(0, view.height - 56));
+    Object.assign(element.style, { left: `${view.left}px`, right: "", bottom: "", top: `${view.top + view.height - height - 56}px`, width: `${view.width}px`, maxHeight: `${height}px` });
+    return;
+  }
+  const below = view.bottom - rect.bottom - 8;
+  const above = rect.top - view.top - 8;
+  const top = below >= 320 || below >= above ? rect.bottom + 8 : rect.top - 328;
+  const left = Math.max(view.left + 8, Math.min(rect.left, view.right - width - 8));
+  Object.assign(element.style, { top: `${Math.max(view.top + 8, top)}px`, left: `${left}px`, right: "", bottom: "", width: `${width}px`, maxHeight: "" });
+}

package/components/shared/input-modality.js

@@ -0,0 +1,20 @@
+const initialized = new WeakSet();
+
+/**
+ * Marks the document `data-ui-input-modality="touch"` once the user actually touches it, rather than
+ * guessing from capability media queries: hybrid devices keep compact pointer affordances until then.
+ * Idempotent per document; touch is sticky once observed.
+ */
+export function trackInputModality(document) {
+  if (initialized.has(document)) return;
+  initialized.add(document);
+  const markTouch = () => {
+    if (document.documentElement.getAttribute("data-ui-input-modality") === "touch") return;
+    document.documentElement.setAttribute("data-ui-input-modality", "touch");
+    document.dispatchEvent(new CustomEvent("ui-input-modality-change", { detail: { modality: "touch" } }));
+  };
+  document.addEventListener("pointerdown", (event) => {
+    if (event.pointerType === "touch") markTouch();
+  }, { capture: true, passive: true });
+  document.addEventListener("touchstart", markTouch, { capture: true, passive: true });
+}

package/components/shared/overlay.js

@@ -0,0 +1,281 @@
+const stacks = new WeakMap();
+let anchorSequence = 0;
+const anchorBindings = new WeakMap();
+
+function stateFor(document) {
+  let state = stacks.get(document);
+  if (state) return state;
+  state = { records: [], modalCount: 0, listening: false };
+  stacks.set(document, state);
+  return state;
+}
+
+function syncScrollLock(document, state) {
+  document.documentElement.toggleAttribute("data-ui-scroll-lock", state.modalCount > 0);
+  if (state.modalCount > 0) document.documentElement.style.overflow = "hidden";
+  else document.documentElement.style.removeProperty("overflow");
+}
+
+function requestClose(document, reason, trigger) {
+  const record = stateFor(document).records.at(-1);
+  if (!record || (record.dismissible === false && (reason === "escape" || reason === "light-dismiss"))) return false;
+  record.requestClose(reason, trigger);
+  return true;
+}
+
+function ensureListeners(document, state) {
+  if (state.listening) return;
+  state.onKeydown = (event) => {
+    if (event.key === "Escape") requestClose(document, "escape", "keyboard");
+  };
+  state.onPointerdown = (event) => {
+    const top = state.records.at(-1);
+    if (!top || top.dismissible === false) return;
+    const boundary = [top.element, ...(top.relatedElements ?? [])];
+    // A modal dialog's ::backdrop reports the dialog itself as the target; a press outside its box is outside.
+    const rect = top.element.getBoundingClientRect();
+    const onBackdrop = event.target === top.element
+      && (event.clientX < rect.left || event.clientX > rect.right || event.clientY < rect.top || event.clientY > rect.bottom);
+    if (!onBackdrop && event.composedPath().some((target) => target instanceof Node && boundary.some((element) => element.contains(target)))) return;
+    requestClose(document, "light-dismiss", "pointer");
+  };
+  document.addEventListener("keydown", state.onKeydown);
+  document.addEventListener("pointerdown", state.onPointerdown, true);
+  state.listening = true;
+}
+
+function removeListeners(document, state) {
+  if (!state.listening || state.records.length) return;
+  document.removeEventListener("keydown", state.onKeydown);
+  document.removeEventListener("pointerdown", state.onPointerdown, true);
+  state.listening = false;
+}
+
+export function openOverlay(record) {
+  const document = record.element.ownerDocument;
+  const state = stateFor(document);
+  closeOverlay(document, record.id);
+  state.records.push(record);
+  if (record.modal) {
+    state.modalCount += 1;
+    syncScrollLock(document, state);
+  }
+  ensureListeners(document, state);
+}
+
+export function closeOverlay(document, id) {
+  const state = stateFor(document);
+  const index = state.records.findIndex((record) => record.id === id);
+  if (index >= 0) {
+    const [record] = state.records.splice(index, 1);
+    if (record?.modal) {
+      state.modalCount = Math.max(0, state.modalCount - 1);
+      syncScrollLock(document, state);
+    }
+  }
+  removeListeners(document, state);
+}
+
+export function requestTopOverlayClose(document, reason, trigger) {
+  return requestClose(document, reason, trigger);
+}
+
+function topLayerOpen(surface) {
+  try { return surface.matches(":popover-open"); } catch { return !surface.hidden; }
+}
+
+function show(surface) {
+  surface.setAttribute("popover", "manual");
+  surface.hidden = false;
+  if (typeof surface.showPopover === "function" && !topLayerOpen(surface)) {
+    try { surface.showPopover(); } catch {}
+  }
+}
+
+function hide(surface) {
+  if (typeof surface.hidePopover === "function" && topLayerOpen(surface)) {
+    try { surface.hidePopover(); } catch {}
+  }
+  surface.hidden = true;
+}
+
+function bindAnchor(anchor, name) {
+  const binding = anchorBindings.get(anchor) ?? { original: anchor.style.getPropertyValue("anchor-name"), names: new Set() };
+  binding.names.add(name);
+  anchorBindings.set(anchor, binding);
+  anchor.style.setProperty("anchor-name", [binding.original, ...binding.names].filter(Boolean).join(", "));
+}
+
+function unbindAnchor(anchor, name) {
+  const binding = anchorBindings.get(anchor);
+  if (!binding) return;
+  binding.names.delete(name);
+  if (binding.names.size) anchor.style.setProperty("anchor-name", [binding.original, ...binding.names].filter(Boolean).join(", "));
+  else {
+    if (binding.original) anchor.style.setProperty("anchor-name", binding.original);
+    else anchor.style.removeProperty("anchor-name");
+    anchorBindings.delete(anchor);
+  }
+}
+
+function viewport(owner) {
+  const visual = owner.visualViewport;
+  const left = visual?.offsetLeft ?? 0;
+  const top = visual?.offsetTop ?? 0;
+  const width = visual?.width ?? owner.innerWidth;
+  const height = visual?.height ?? owner.innerHeight;
+  return { left, top, right: left + width, bottom: top + height, width, height };
+}
+
+function clamp(rect, bounds, gutter) {
+  const availableWidth = Math.max(0, bounds.width - gutter * 2);
+  const availableHeight = Math.max(0, bounds.height - gutter * 2);
+  const left = rect.width > availableWidth ? bounds.left + gutter : Math.min(Math.max(rect.left, bounds.left + gutter), bounds.right - gutter - rect.width);
+  const top = rect.height > availableHeight ? bounds.top + gutter : Math.min(Math.max(rect.top, bounds.top + gutter), bounds.bottom - gutter - rect.height);
+  return { x: left - rect.left, y: top - rect.top };
+}
+
+// Entry transitions scale and nudge the surface; measure its untransformed layout box so a position
+// computed mid-animation is not shrunk or offset (offsetWidth/Height ignore transforms).
+function layoutRect(surface) {
+  const box = surface.getBoundingClientRect();
+  const width = surface.offsetWidth || box.width;
+  const height = surface.offsetHeight || box.height;
+  const left = box.left + (box.width - width) / 2;
+  const top = box.top + (box.height - height) / 2;
+  return { left, top, right: left + width, bottom: top + height, width, height };
+}
+
+function fallbackPosition(surface, anchor, placement, gap, viewportGap, surfaceRect = layoutRect(surface)) {
+  const bounds = viewport(surface.ownerDocument.defaultView);
+  const preferTop = placement.startsWith("top");
+  const preferEnd = placement.endsWith("end");
+  const below = bounds.bottom - anchor.bottom - viewportGap;
+  const above = anchor.top - bounds.top - viewportGap;
+  const useTop = preferTop ? !(above < surfaceRect.height + gap && below > above) : below < surfaceRect.height + gap && above > below;
+  const top = useTop ? anchor.top - surfaceRect.height - gap : anchor.bottom + gap;
+  const left = preferEnd ? anchor.right - surfaceRect.width : anchor.left;
+  const shift = clamp({ left, top, right: left + surfaceRect.width, bottom: top + surfaceRect.height, width: surfaceRect.width, height: surfaceRect.height }, bounds, viewportGap);
+  surface.style.left = `${Math.round(left + shift.x)}px`;
+  surface.style.top = `${Math.round(top + shift.y)}px`;
+  surface.style.right = "auto";
+  surface.style.bottom = "auto";
+}
+
+export function createAnchoredSurface(surface, options = {}) {
+  const owner = surface.ownerDocument.defaultView;
+  let placement = options.placement ?? "bottom-start";
+  const gap = Math.max(0, options.gap ?? 4);
+  const viewportGap = Math.max(0, options.viewportGap ?? 8);
+  const nativeAnchor = owner.CSS?.supports?.("anchor-name: --ui-anchor-test") && owner.CSS.supports("position-anchor: --ui-anchor-test") && owner.CSS.supports("top: anchor(bottom)");
+  const anchorName = `--ui-anchor-${++anchorSequence}`;
+  let anchor = options.anchor ?? null;
+  let point = null;
+  let open = false;
+  let frame = null;
+  let abort = null;
+  let sizeObserver = null;
+  surface.setAttribute("popover", "manual");
+  surface.dataset.uiPositioning = nativeAnchor ? "anchor" : "fallback";
+  surface.style.position = "fixed";
+  surface.style.margin = "0";
+  const bind = (next) => {
+    if (anchor) unbindAnchor(anchor, anchorName);
+    anchor = next;
+    if (anchor) {
+      bindAnchor(anchor, anchorName);
+      surface.style.setProperty("position-anchor", anchorName);
+    } else surface.style.removeProperty("position-anchor");
+  };
+  const position = () => {
+    frame = null;
+    if (!open) return;
+    if (point) {
+      fallbackPosition(surface, { left: point.x, right: point.x, top: point.y, bottom: point.y, width: 0, height: 0 }, "bottom-start", gap, viewportGap);
+      return;
+    }
+    if (!anchor) return;
+    let rect;
+    if (nativeAnchor) {
+      const blockEnd = placement.startsWith("bottom");
+      const inlineEnd = placement.endsWith("end");
+      surface.style.top = blockEnd ? `calc(anchor(bottom) + ${gap}px)` : "auto";
+      surface.style.bottom = blockEnd ? "auto" : `calc(anchor(top) + ${gap}px)`;
+      surface.style.left = inlineEnd ? "auto" : "anchor(left)";
+      surface.style.right = inlineEnd ? "anchor(right)" : "auto";
+      surface.style.setProperty("position-try-fallbacks", "flip-block, flip-inline");
+      rect = layoutRect(surface);
+      if (!rect.width || !rect.height) return;
+      const shift = clamp(rect, viewport(owner), viewportGap);
+      if (!shift.x && !shift.y) return;
+    }
+    fallbackPosition(surface, anchor.getBoundingClientRect(), placement, gap, viewportGap, rect);
+  };
+  const schedule = () => {
+    if (open && frame === null) frame = owner.requestAnimationFrame(position);
+  };
+  const syncListeners = () => {
+    const needed = open && (point || anchor);
+    if (!needed) {
+      abort?.abort();
+      abort = null;
+      return;
+    }
+    if (abort) return;
+    abort = new AbortController();
+    const signal = abort.signal;
+    owner.addEventListener("resize", schedule, { passive: true, signal });
+    owner.addEventListener("scroll", schedule, { passive: true, capture: true, signal });
+    owner.visualViewport?.addEventListener("resize", schedule, { passive: true, signal });
+    owner.visualViewport?.addEventListener("scroll", schedule, { passive: true, signal });
+  };
+  const observeSize = () => {
+    if (sizeObserver || !owner.ResizeObserver) return;
+    sizeObserver = new owner.ResizeObserver(schedule);
+    sizeObserver.observe(surface);
+  };
+  const stopSize = () => { sizeObserver?.disconnect(); sizeObserver = null; };
+  bind(anchor);
+  return {
+    setAnchor(next) { point = null; bind(next); syncListeners(); schedule(); },
+    setPlacement(next) { placement = next || "bottom-start"; schedule(); },
+    show() { point = null; open = true; syncListeners(); show(surface); position(); schedule(); observeSize(); },
+    showAtPoint(next) { point = next; open = true; syncListeners(); show(surface); position(); schedule(); observeSize(); },
+    hide() { open = false; point = null; syncListeners(); stopSize(); if (frame !== null) owner.cancelAnimationFrame(frame); frame = null; hide(surface); },
+    refresh: schedule,
+    destroy() { open = false; abort?.abort(); abort = null; stopSize(); if (frame !== null) owner.cancelAnimationFrame(frame); frame = null; hide(surface); bind(null); },
+  };
+}
+
+/**
+ * Resolves `for`-style ID references that may not exist yet. `get(id)` returns the element or, when
+ * it is missing, watches the document and calls `onLate` once an element with that ID appears
+ * (examples, templates, and frameworks often render the trigger after the overlay).
+ */
+export function createIdResolver(document, onLate) {
+  let observer = null;
+  let waiting = "";
+  const stop = () => {
+    observer?.disconnect();
+    observer = null;
+    waiting = "";
+  };
+  const get = (id) => {
+    const found = id ? document.getElementById(id) : null;
+    if (found || !id) {
+      if (waiting) stop();
+      return found;
+    }
+    if (waiting === id) return null;
+    stop();
+    waiting = id;
+    observer = new MutationObserver(() => {
+      if (!document.getElementById(waiting)) return;
+      stop();
+      onLate();
+    });
+    observer.observe(document.documentElement, { childList: true, subtree: true, attributes: true, attributeFilter: ["id"] });
+    return null;
+  };
+  return { get, stop };
+}

package/components/shared/trigger.js

@@ -0,0 +1,17 @@
+/**
+ * Reports what caused the next change on a component: a `change` event is a plain Event, so the
+ * keyboard or pointer that preceded it is remembered here. Returns [take, stop].
+ */
+export function trackTrigger(host) {
+  let trigger = "programmatic";
+  const offKey = host.on("keydown", (event) => {
+    if (event.key === " " || event.key === "Enter" || event.key.startsWith("Arrow")) trigger = "keyboard";
+  });
+  const offPointer = host.on("pointerdown", () => { trigger = "pointer"; });
+  const take = () => {
+    const current = trigger;
+    trigger = "programmatic";
+    return current;
+  };
+  return [take, () => { offKey(); offPointer(); }];
+}

package/components/ui-affordance-scope/ui-affordance-scope.html

@@ -0,0 +1,22 @@
+<template component="ui-affordance-scope" controller="./ui-affordance-scope.js">
+  <defs>
+    <prop name="nearRadius" type="number" default="16">How close, in pixels, the pointer must come to reveal an affordance.</prop>
+    <state name="engaged" :value="false"></state>
+  </defs>
+  <span><slot></slot></span>
+  <style>
+    :host {
+      display: contents;
+      --ui-affordance-scope-engaged: 0;
+    }
+
+    :host-state([engaged]) {
+      --ui-affordance-scope-engaged: 1;
+    }
+
+    /* A component that sets its display still honours the hidden attribute on its root. */
+    :host[hidden] {
+      display: none;
+    }
+  </style>
+</template>

package/components/ui-affordance-scope/ui-affordance-scope.js

@@ -0,0 +1,76 @@
+function distance(point, rect) {
+  const dx = Math.max(rect.left - point.x, 0, point.x - rect.right);
+  const dy = Math.max(rect.top - point.y, 0, point.y - rect.bottom);
+  return Math.hypot(dx, dy);
+}
+
+export default function controller(host) {
+  const element = host.element;
+  const owner = element.ownerDocument.defaultView;
+  let anchors = [];
+  let frame = null;
+  let point = null;
+  let dirty = false;
+  let nearRadius = Number(host.state.nearRadius ?? 16);
+  const clear = () => {
+    for (const anchor of anchors) anchor.element.removeAttribute("data-ui-proximity");
+    host.state.engaged = false;
+  };
+  const measure = () => {
+    anchors = Array.from(element.querySelectorAll("[data-ui-affordance]"))
+      .filter((anchor) => !anchor.hasAttribute("disabled") && anchor.getAttribute("aria-disabled") !== "true")
+      .map((anchor) => ({ element: anchor, rect: anchor.getBoundingClientRect() }));
+    dirty = false;
+  };
+  const update = () => {
+    frame = null;
+    if (dirty) measure();
+    if (!point) {
+      clear();
+      return;
+    }
+    let engaged = false;
+    for (const anchor of anchors) {
+      const near = distance(point, anchor.rect) <= nearRadius;
+      anchor.element.toggleAttribute("data-ui-proximity", near);
+      if (near) anchor.element.setAttribute("data-ui-proximity", "near");
+      engaged ||= near;
+    }
+    host.state.engaged = engaged;
+  };
+  const schedule = () => {
+    if (frame === null) frame = owner.requestAnimationFrame(update);
+  };
+  const invalidate = () => {
+    dirty = true;
+    schedule();
+  };
+  const onPointermove = (event) => {
+    point = event.pointerType === "touch" ? null : { x: event.clientX, y: event.clientY };
+    schedule();
+  };
+  const observer = new MutationObserver(invalidate);
+  observer.observe(element, { childList: true, subtree: true, attributes: true, attributeFilter: ["data-ui-affordance", "disabled", "aria-disabled"] });
+  element.ownerDocument.addEventListener("pointermove", onPointermove, { passive: true });
+  owner.addEventListener("resize", invalidate, { passive: true });
+  owner.addEventListener("scroll", invalidate, { passive: true, capture: true });
+  owner.visualViewport?.addEventListener("resize", invalidate, { passive: true });
+  owner.visualViewport?.addEventListener("scroll", invalidate, { passive: true });
+  const stop = host.effect(() => {
+    const configured = Number(host.state.nearRadius ?? 16);
+    nearRadius = Number.isFinite(configured) ? Math.max(0, configured) : 16;
+    invalidate();
+  });
+  measure();
+  return () => {
+    stop();
+    observer.disconnect();
+    element.ownerDocument.removeEventListener("pointermove", onPointermove);
+    owner.removeEventListener("resize", invalidate);
+    owner.removeEventListener("scroll", invalidate, true);
+    owner.visualViewport?.removeEventListener("resize", invalidate);
+    owner.visualViewport?.removeEventListener("scroll", invalidate);
+    if (frame !== null) owner.cancelAnimationFrame(frame);
+    clear();
+  };
+}

package/components/ui-avatar/ui-avatar.html

@@ -0,0 +1,59 @@
+<template component="ui-avatar" controller="./ui-avatar.js">
+  <defs>
+    <prop name="src" type="string">Image URL.</prop>
+    <prop name="alt" type="string" default="">alt token.</prop>
+    <prop name="name" type="string" default="">name token.</prop>
+    <prop name="fallback" type="string" default="">fallback token.</prop>
+    <state name="hasImage" :value="false"></state>
+    <state name="hasAuthoredImage" :value="false"></state>
+    <state name="initials" :value="'?'"></state>
+  </defs>
+  <span>
+    <slot></slot>
+    <img class="image" $ref="image" :src="src" alt="" aria-hidden="true" :hidden="hasAuthoredImage or not hasImage">
+    <span class="fallback" :aria-hidden="hasImage" :hidden="hasImage" $value="initials"></span>
+  </span>
+  <style>
+    :host {
+      display: inline-grid;
+      place-items: center;
+      overflow: hidden;
+      inline-size: 2.5rem;
+      block-size: 2.5rem;
+      border-radius: 999px;
+      border: 1px solid var(--ui-avatar-border, var(--ui-border-strong));
+      background: var(--ui-avatar-surface, var(--ui-accent-soft));
+      color: var(--ui-avatar-text, var(--ui-accent-solid));
+      font: inherit;
+      font-size: 0.875rem;
+      font-weight: 600;
+      text-transform: uppercase;
+    }
+
+    .image,
+    :slotted(img) {
+      grid-area: 1 / 1;
+      inline-size: 100%;
+      block-size: 100%;
+      object-fit: cover;
+    }
+
+    .fallback {
+      grid-area: 1 / 1;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      inline-size: 100%;
+      block-size: 100%;
+    }
+
+    [hidden] {
+      display: none;
+    }
+
+    /* A component that sets its display still honours the hidden attribute on its root. */
+    :host[hidden] {
+      display: none;
+    }
+  </style>
+</template>

package/components/ui-avatar/ui-avatar.js

@@ -0,0 +1,47 @@
+function toInitials(value) {
+  const tokens = (value || "").trim().split(/\s+/).filter((token) => token.length > 0);
+  if (tokens.length === 0) return "?";
+  if (tokens.length === 1) return tokens[0].slice(0, 2).toUpperCase();
+  return `${tokens[0][0] ?? ""}${tokens[1][0] ?? ""}`.toUpperCase();
+}
+
+// Shows an authored <img>, else the `src` image, else initials, and tracks whether the image loaded.
+export default function controller(host) {
+  const element = host.element;
+  const managed = host.refs.image;
+  let active;
+  const onLoad = () => { host.state.hasImage = true; };
+  const onError = () => { host.state.hasImage = false; };
+  const watch = (image) => {
+    if (image === active) return;
+    active?.removeEventListener("load", onLoad);
+    active?.removeEventListener("error", onError);
+    active = image;
+    active.addEventListener("load", onLoad);
+    active.addEventListener("error", onError);
+    host.state.hasImage = active.complete && active.naturalWidth > 0;
+  };
+  const apply = () => {
+    const authored = Array.from(element.querySelectorAll("img")).find((image) => image !== managed);
+    host.state.hasAuthoredImage = Boolean(authored);
+    watch(authored ?? managed);
+    if (authored) {
+      authored.hidden = !host.state.hasImage;
+      element.removeAttribute("role");
+      element.removeAttribute("aria-label");
+    } else {
+      element.setAttribute("role", "img");
+      element.setAttribute("aria-label", host.state.alt || host.state.name || "Avatar");
+    }
+    host.state.initials = host.state.fallback || toInitials(host.state.name || host.state.alt);
+  };
+  const observer = new MutationObserver(apply);
+  observer.observe(element, { childList: true });
+  const stop = host.effect(apply);
+  return () => {
+    stop();
+    observer.disconnect();
+    active?.removeEventListener("load", onLoad);
+    active?.removeEventListener("error", onError);
+  };
+}