sol-components 2.1.0

package/README.md

@@ -0,0 +1,7 @@
+# Solid Web Components
+
+## This is a Work In Progress!
+
+See the <a href="https://solidos.github.io/sol-components/">help pages</a> for details.
+
+(c) 2023-2026, Jeff Zucker, may be freely distributed under an MIT or Apache license.

package/core/activate.js

@@ -0,0 +1,27 @@
+// core/activate.js — run a capability's behavior over every element bearing one
+// of its attributes, now and as elements mount. This is what makes a capability
+// attribute (e.g. data-from-query) work on ANY element, component or not: the
+// behavior is injected by a DOM walk, not implemented by the element's class.
+//
+//   activate('[data-from-query]', (el) => …);   // called once per matching element
+
+/**
+ * @param {string} selector — CSS selector for the capability's attribute
+ * @param {(el: Element) => void} fn — wiring run once per matching element
+ * @returns {() => void} stop the observer
+ */
+export function activate(selector, fn) {
+  if (typeof document === 'undefined') return () => {};
+  const seen = new WeakSet();
+  const scan = () => {
+    for (const el of document.querySelectorAll(selector)) {
+      if (seen.has(el)) continue;
+      seen.add(el);
+      try { fn(el); } catch (e) { console.error('[sol-loader] activator error for', selector, e); }
+    }
+  };
+  scan();
+  const mo = new MutationObserver(scan);
+  mo.observe(document.documentElement || document, { childList: true, subtree: true });
+  return () => mo.disconnect();
+}

package/core/adopt.js

@@ -0,0 +1,71 @@
+/**
+ * Style helpers for Constructable Stylesheets + adoptedStyleSheets.
+ *
+ * `sheetFrom(css)` returns a `CSSStyleSheet` on evergreen browsers, or
+ * `null` when the constructor is unavailable (e.g. Jest/node env). Callers
+ * should keep the raw `CSS` string export alongside the sheet so they can
+ * fall back to a `<style>` tag when `sheet` is null.
+ *
+ * `adopt(root, { sheet, css, extra })` wires a shadow root (or document)
+ * with the baseline module sheet (+ any extras). If no sheet is available
+ * it appends `<style>${css}</style>` into the root instead.
+ */
+
+let _supports = null;
+function supports() {
+  if (_supports !== null) return _supports;
+  try {
+    const s = new CSSStyleSheet();
+    _supports = typeof s.replaceSync === 'function';
+  } catch {
+    _supports = false;
+  }
+  return _supports;
+}
+
+export function sheetFrom(css) {
+  if (!supports()) return null;
+  const s = new CSSStyleSheet();
+  s.replaceSync(css);
+  return s;
+}
+
+// Adopt a CSSStyleSheet into `root` (ShadowRoot or Document). When sheets
+// aren't supported, falls back to inserting a <style> with the given css.
+export function adopt(root, { sheet, css, extra = [] } = {}) {
+  const host = root.adoptedStyleSheets !== undefined ? root : null;
+  if (host && sheet) {
+    const sheets = [sheet];
+    const strings = [];
+    for (const e of extra) {
+      if (e instanceof CSSStyleSheet) sheets.push(e);
+      else if (typeof e === 'string') strings.push(e);
+    }
+    host.adoptedStyleSheets = [...host.adoptedStyleSheets, ...sheets];
+    for (const s of strings) appendStyle(root, s);
+    return;
+  }
+  // Fallback path: inline <style> for baseline + extras.
+  if (css) appendStyle(root, css);
+  for (const e of extra) {
+    if (typeof e === 'string') appendStyle(root, e);
+  }
+}
+
+function appendStyle(root, css) {
+  const el = document.createElement('style');
+  el.textContent = css;
+  root.appendChild(el);
+}
+
+// Ensure a named stylesheet exists in the given document/shadow-root head
+// exactly once. Useful for light-DOM components.
+export function ensureDocStyle(root, id, css) {
+  const target = root.nodeType === 11 ? root : (root.ownerDocument || document);
+  if (!target) return;
+  if (target.getElementById?.(id)) return;
+  const el = document.createElement('style');
+  el.id = id;
+  el.textContent = css;
+  (target.head || target).appendChild(el);
+}

package/core/auth-core.js

@@ -0,0 +1,73 @@
+export function originOf(url) {
+  return url.match(/^https?:\/\/[^/]+/)?.[0] || '';
+}
+
+export function baseDomain(host) {
+  const p = host.split('.');
+  return p.length >= 2 ? p.slice(-2).join('.') : host;
+}
+
+export function sessionCoversOrigin(session, origin) {
+  if (!session.info?.isLoggedIn) return false;
+  try {
+    const rHost = new URL(origin).host;
+    const rBase = baseDomain(rHost);
+    for (const ref of [session.info.issuer, session.info.webId]) {
+      if (!ref) continue;
+      const h = new URL(ref).host;
+      if (rHost === h || rHost.endsWith('.' + h) || baseDomain(h) === rBase) return true;
+    }
+  } catch {}
+  return false;
+}
+
+export function isNoAuth(url, noAuthConfig) {
+  try {
+    const origin = new URL(url).origin;
+    if (!noAuthConfig) return false;
+    return Array.isArray(noAuthConfig) ? noAuthConfig.includes(origin) : origin === noAuthConfig;
+  } catch { return false; }
+}
+
+export function getSessionFor(sessions, url, tag, noAuthConfig) {
+  if (!url || isNoAuth(url, noAuthConfig)) return null;
+  const own = sessions.get(tag);
+  if (own?.info?.isLoggedIn) return own;
+  const origin = originOf(url);
+  for (const [, s] of sessions) {
+    if (sessionCoversOrigin(s, origin)) return s;
+  }
+  return own || null;
+}
+
+export function makeFetchFor(sessions, url, tag, noAuthConfig, defaultFetch) {
+  if (isNoAuth(url, noAuthConfig)) return defaultFetch;
+  const session = tag
+    ? getSessionFor(sessions, url, tag, noAuthConfig)
+    : (() => {
+        const origin = originOf(url);
+        for (const [, s] of sessions) {
+          if (sessionCoversOrigin(s, origin)) return s;
+        }
+        return null;
+      })();
+  if (!session?.fetch) return defaultFetch;
+  return (input, init) => session.fetch(input, init);
+}
+
+export function isLoggedInFor(sessions, url, tag, noAuthConfig) {
+  if (!url || isNoAuth(url, noAuthConfig)) return true;
+  const s = getSessionFor(sessions, url, tag, noAuthConfig);
+  return s?.info?.isLoggedIn ?? false;
+}
+
+export function getWebId(sessions, tag = 'default') {
+  return sessions.get(tag)?.info?.webId || null;
+}
+
+export function getFirstLoggedIn(sessions) {
+  for (const s of sessions.values()) {
+    if (s.info?.isLoggedIn) return s;
+  }
+  return null;
+}

package/core/auth-fetch.js

@@ -0,0 +1,154 @@
+/**
+ * core/auth-fetch.js — page-wide authenticated fetch lookup.
+ *
+ * Components that need to fetch resources (sol-query for SPARQL endpoints,
+ * sol-include for documents, the Comunica adapter, …) call getAuthFetch(url)
+ * to obtain a fetch function. If a logged-in <sol-login> is on the page,
+ * its session.fetch is returned; otherwise the global fetch is.
+ *
+ * The component-explicit `login` attribute used by sol-pod / sol-pod-ops /
+ * sol-wac still wins — pass `opts.element` here to plumb that through.
+ *
+ * Lookup is light-DOM only: <sol-login> hidden inside another shadow root
+ * isn't auto-discovered. That's by design — cross-shadow auth has to be
+ * explicit because the host component can't safely guess the user's intent.
+ */
+
+/**
+ * Return a fetch function appropriate for `url`. Always returns a usable
+ * fetch (never null) — callers can use the result without null-checking.
+ *
+ * @param {string} url — the URL the caller is about to fetch
+ * @param {object} [opts]
+ * @param {Element} [opts.element] — explicit sol-login element (overrides lookup)
+ * @param {string}  [opts.tag]     — session tag; defaults to the targeted
+ *                                   element's `side`, else 'default'
+ * @returns {(input: RequestInfo, init?: RequestInit) => Promise<Response>}
+ */
+export function getAuthFetch(url, opts = {}) {
+  const login = opts.element || findFirstSolLogin();
+  // Sessions are keyed by tag — a <sol-login>'s `side`. An explicitly
+  // targeted element selects its own session by that side; auto-discovered
+  // or side-less logins use the 'default' tag.
+  const tag = opts.tag
+    || (opts.element && typeof opts.element.getAttribute === 'function'
+        && opts.element.getAttribute('side'))
+    || 'default';
+  if (login && typeof login.fetchFor === 'function') {
+    try {
+      const f = login.fetchFor(url, tag);
+      if (typeof f === 'function') return f;
+    } catch { /* fall through to adopted / global fetch */ }
+  }
+  // No <sol-login> (or it declined): a host may have adopted a foreign
+  // authenticated fetch via SolidWebComponents.adoptFetch (e.g. PodOS's
+  // authenticatedFetch). Prefer it over the unauthenticated global fetch.
+  const adopted = (typeof window !== 'undefined') && window.SolidWebComponents?.adoptedFetch;
+  if (typeof adopted === 'function') return adopted;
+  // `globalThis.fetch` may be missing in some Node test environments —
+  // return undefined so callers fall back to their own default (most use
+  // `fetchFn = globalThis.fetch` as the parameter default).
+  return typeof globalThis.fetch === 'function' ? globalThis.fetch.bind(globalThis) : undefined;
+}
+
+/**
+ * Find the first <sol-login> in the document, light-DOM only.
+ * Returns null if none is present (or in non-browser environments).
+ */
+function findFirstSolLogin() {
+  if (typeof document === 'undefined') return null;
+  return document.querySelector('sol-login');
+}
+
+/* ── solFetch: auto-prompt fetch wrapper ──────────────────────────────
+ *
+ * solFetch(url, opts) wraps fetch and, when the response indicates auth
+ * is required, dispatches `sol-auth-needed` on document with a Promise
+ * resolver in the detail. A listener (typically <sol-login>) runs the
+ * login UI and resolves the promise; solFetch then retries once.
+ *
+ * Event contract (public API):
+ *
+ *     document.addEventListener('sol-auth-needed', (e) => {
+ *       const { url, response, resolve, reject } = e.detail;
+ *       // Run login UI; call resolve(true) when authed, resolve(false)
+ *       // to give up, reject(err) on error.
+ *     });
+ *
+ * When no `<sol-login>` is mounted, solFetch falls through to a plain
+ * fetch (so swc widgets work in unauthed contexts). When AuthManager
+ * already has a covering session, the first request is authenticated
+ * and `sol-auth-needed` is never fired.
+ *
+ * Frame integration: a frame (dk, etc.) just mounts `<sol-login>` once
+ * — the listener is attached automatically by sol-login's
+ * connectedCallback. The frame supplies `default-issuer` via
+ * `<sol-default default-issuer="…">` or on the sol-login element
+ * itself; sol-login uses it as the auto-login target.
+ */
+
+const AUTH_NEEDED_EVENT = 'sol-auth-needed';
+const AUTH_PROMPT_TIMEOUT_MS = 5 * 60 * 1000;
+
+function getAuthManager() {
+  if (typeof window === 'undefined') return null;
+  return window.SolidWebComponents?.AuthManager?.shared || null;
+}
+
+function hasLoginListener() {
+  if (typeof document === 'undefined') return false;
+  return !!document.querySelector('sol-login');
+}
+
+/** 401 → prompt always. 403 → prompt only when no session is active
+ *  (with an active session, 403 means "logged in but not authorized",
+ *  re-login won't help, so surface the response as-is). */
+function shouldPrompt(response, am) {
+  if (response.status === 401) return true;
+  if (response.status === 403) {
+    if (!am) return true;
+    const anyLoggedIn = [...am.sessions.values()].some(s => s.info?.isLoggedIn);
+    return !anyLoggedIn;
+  }
+  return false;
+}
+
+function awaitAuth(url, response, side) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (ok)  => { if (!settled) { settled = true; resolve(!!ok); } };
+    const fail   = (err) => { if (!settled) { settled = true; reject(err); } };
+    document.dispatchEvent(new CustomEvent(AUTH_NEEDED_EVENT, {
+      bubbles: false, composed: false,
+      detail: { url, response, side, resolve: finish, reject: fail },
+    }));
+    setTimeout(() => finish(false), AUTH_PROMPT_TIMEOUT_MS);
+  });
+}
+
+/**
+ * Authenticated fetch with auto-prompt on 401 (and unauthenticated 403).
+ * @param {string|URL|Request} url
+ * @param {RequestInit} [opts]
+ * @returns {Promise<Response>}
+ */
+export async function solFetch(url, opts) {
+  const am = getAuthManager();
+  const tag = opts?.authTag;
+  const baseFetch = am ? am.fetchFor(url, tag) : (typeof fetch !== 'undefined' ? fetch : null);
+  if (!baseFetch) throw new Error('solFetch: no fetch implementation available');
+
+  const response = await baseFetch(url, opts);
+  if (!shouldPrompt(response, am)) return response;
+  if (!hasLoginListener()) return response;
+
+  const ok = await awaitAuth(url, response, tag);
+  if (!ok) return response;
+
+  const retryFetch = (am ?? getAuthManager())?.fetchFor(url, tag) || baseFetch;
+  return retryFetch(url, opts);
+}
+
+/** Event name listeners subscribe to. Re-exported so callers needn't
+ *  string-match. */
+export const SOL_AUTH_NEEDED = AUTH_NEEDED_EVENT;

package/core/component-mount.js

@@ -0,0 +1,110 @@
+// Shared mount-into-target helper used by:
+//   - core/rdf-render.js renderComponentItem (menu / tabs item rendering)
+//   - web/sol-button.js (declarative launcher in chrome)
+//
+// Both place a custom-element instance inside a per-named wrapper
+// (`<div data-menu-item="<name>" data-keep-alive="true|false">`) under
+// a CSS-selector-addressed `target` element, so multiple consumers can
+// coexist in the same display area and play nicely with keep-alive.
+
+/**
+ * Locate the wrapper a prior mount left in `target` for the given name.
+ * Returns null when none exists.
+ * @param {HTMLElement} target
+ * @param {string} name
+ * @returns {HTMLElement | null}
+ */
+export function findItemWrapper(target, name) {
+  if (!target) return null;
+  const esc = (typeof CSS !== 'undefined' && CSS.escape) ? CSS.escape(name) : name;
+  return target.querySelector(`:scope > [data-menu-item="${esc}"]`);
+}
+
+/**
+ * Hide every other named wrapper inside `target`. The mount model is
+ * "always-persistent tabs" — clicking a menu/button just brings its
+ * own wrapper to the foreground and parks the others. Components are
+ * never torn down on nav-away, so their internal state (login
+ * sessions, scroll position, in-flight fetches, open accordion
+ * panels, etc.) survives across menu switches.
+ */
+export function pruneSiblings(target, activeName) {
+  if (!target) return;
+  const wraps = target.querySelectorAll(':scope > [data-menu-item]');
+  for (const w of wraps) {
+    if (w.dataset.menuItem === activeName) continue;
+    w.hidden = true;
+  }
+}
+
+/**
+ * Mount (or re-show) a component inside `target`, wrapped for
+ * coexistence with siblings.
+ *
+ * Two modes:
+ *   - **Persistent tab** (default, `replace` falsy): each
+ *     `(target, name)` pair is created once and reused — clicking
+ *     back to the same name just unhides the existing wrapper, so
+ *     internal state (login, scroll, in-flight fetches) survives.
+ *   - **Shared / overwrite tab** (`replace: true`): the wrapper for
+ *     `name` is kept across activations but its component is torn
+ *     down and rebuilt with the latest attrs on every call. Useful
+ *     for a single "scratch" pane that multiple sources write into
+ *     (e.g. external menu links, ad-hoc launchers).
+ *
+ * @param {object}      o
+ * @param {HTMLElement} o.target       Where to mount (typically a region pane).
+ * @param {string}      o.name         Wrapper id (data-menu-item value).
+ * @param {string}      o.tag          Custom-element tag of the component.
+ * @param {Iterable<[string, string]>} [o.attrs]  Attributes to set on
+ *                       the new component. Re-applied each call in
+ *                       replace mode; ignored when reusing in
+ *                       persistent mode.
+ * @param {string}      [o.embedClass] Optional CSS class added to the
+ *                       mounted component (e.g. 'sol-menu-embed').
+ * @param {boolean}     [o.replace]    When true, rebuild the inner
+ *                       component on every call (the wrapper itself
+ *                       persists; only its contents are swapped).
+ * @returns {HTMLElement} the wrapper (existing or freshly created).
+ */
+export function mountInTarget({ target, name, tag, attrs, embedClass, replace }) {
+  if (!target || !tag) return null;
+
+  let wrap = findItemWrapper(target, name);
+  if (wrap && !replace) {
+    pruneSiblings(target, name);
+    wrap.hidden = false;
+    fireTabActivate(target, name);
+    return wrap;
+  }
+
+  if (wrap) {
+    // Replace mode: rebuild contents but keep the wrapper itself.
+    wrap.innerHTML = '';
+    wrap.hidden = false;
+  } else {
+    wrap = document.createElement('div');
+    wrap.dataset.menuItem = name;
+    target.appendChild(wrap);
+  }
+  if (replace) wrap.dataset.replace = 'true';
+
+  const el = document.createElement(tag);
+  if (attrs) for (const [k, v] of attrs) el.setAttribute(k, v);
+  if (embedClass) el.classList.add(embedClass);
+  wrap.appendChild(el);
+
+  pruneSiblings(target, name);
+  fireTabActivate(target, name);
+  return wrap;
+}
+
+// Bubble + composed event so menus / buttons elsewhere on the page
+// can sync their active-state visuals without each consumer wiring
+// its own listener on every possible target.
+function fireTabActivate(target, name) {
+  target.dispatchEvent(new CustomEvent('sol-tab-activate', {
+    bubbles: true, composed: true,
+    detail: { name, target },
+  }));
+}

package/core/defaults.js

@@ -0,0 +1,48 @@
+// Shared programmatic defaults — values components fall back to when
+// their own attribute isn't set and no RDF source PropertyValue
+// supplies it. Lives in a singleton <sol-default> element in the host
+// page (see ../web/sol-default.js).
+//
+// CSS-driven knobs (theme, font-size) belong on :root as custom
+// properties, not here. This module is for JS-side values like the
+// CORS proxy URL.
+
+import { register as registerService } from './services.js';
+
+/**
+ * Read the current value of a named default. Returns the matching
+ * attribute on the first <sol-default> element in the document, or
+ * null if no element exists or the attribute isn't set.
+ *
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function getDefault(name) {
+  const el = document.querySelector('sol-default');
+  if (!el) return null;
+  const v = el.getAttribute(name);
+  return v == null ? null : v;
+}
+
+/**
+ * Subscribe to changes on <sol-default>. The handler is invoked with
+ * (name, newValue, oldValue) for each attribute change. Returns an
+ * unsubscribe function — call it on disconnect to remove the listener.
+ *
+ * The event is dispatched by sol-default's attributeChangedCallback
+ * and bubbles up to document, so this works regardless of where the
+ * <sol-default> element sits in the tree.
+ *
+ * @param {(name: string, newValue: string|null, oldValue: string|null) => void} handler
+ * @returns {() => void}
+ */
+export function onDefaultChange(handler) {
+  const fn = (e) => handler(e.detail.name, e.detail.newValue, e.detail.oldValue);
+  document.addEventListener('sol-default-change', fn);
+  return () => document.removeEventListener('sol-default-change', fn);
+}
+
+// Publish shared config as the `defaults` host-service so any component reaches
+// it via window.SolidWebComponents.defaults — no import required. Registered
+// unconditionally; the getters simply return null when no <sol-default> exists.
+registerService('defaults', { get: getDefault, onChange: onDefaultChange });

package/core/define.js

@@ -0,0 +1,15 @@
+// Idempotent wrapper around customElements.define. Prevents a throw when the
+// same tag is registered twice — e.g. when a page loads both the all-in-one
+// bundle and a per-component UMD build, or when a module is re-evaluated by
+// a hot-reloader.
+export function define(name, klass) {
+  if (typeof customElements === 'undefined') return;
+  const existing = customElements.get(name);
+  if (existing) {
+    if (existing !== klass && !window.__SolSuppressDefineWarn) {
+      console.warn(`[sol-components] <${name}> already registered; keeping the existing definition.`);
+    }
+    return;
+  }
+  customElements.define(name, klass);
+}

package/core/display-target.js

@@ -0,0 +1,166 @@
+// Region resolver + mounter for launchers (menu items, sol-button).
+//
+// The model: content/structure lives in Turtle, all display lives in HTML.
+// A launcher decides three things, all resolved here from the DOM:
+//
+//   where    — `region=` on the launcher / a container / <sol-menu> /
+//              <sol-default> (nearest wins). Value is a CSS selector (a
+//              persistent pane the author placed) OR a keyword
+//              (modal | floating | tab | window) that conjures an ephemeral
+//              surface with no author-placed element. A Turtle menu item,
+//              which has no HTML element, is routed by a host that claims it
+//              by id via `data-for`.
+//   how      — the content element: a component tag, a <sol-include> of a
+//              same-origin href, or an <iframe> for an external href.
+//   lifetime — per pane: component → keep-alive wrapper, doc/iframe → replace.
+//
+// No RDF display vocabulary is involved; surfaces survive only as the HTML
+// keyword values above.
+
+import { mountInTarget } from './component-mount.js';
+
+const SURFACE_KEYWORDS = new Set(['modal', 'floating', 'tab', 'window']);
+
+/** True for a cross-origin http(s) URL. */
+export function isExternal(href) {
+  if (!href) return false;
+  try {
+    const u = new URL(href, document.baseURI);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+    return u.origin !== location.origin;
+  } catch {
+    return false;
+  }
+}
+
+/** Content element for a link href: same-origin → trusted sol-include
+ *  (keep-alive); external → iframe (replace). */
+export function contentForHref(href) {
+  return isExternal(href)
+    ? { tag: 'iframe',      attrs: [['src', href]],                                            replace: true }
+    : { tag: 'sol-include', attrs: [['source', href], ['endpoint', href], ['trusted', 'true']], replace: false };
+}
+
+function buildElement(tag, attrs = [], embedClass = null) {
+  const el = document.createElement(tag);
+  for (const [k, v] of attrs) el.setAttribute(k, v);
+  if (embedClass) el.classList.add(embedClass);
+  return el;
+}
+
+function safeQuery(sel) {
+  try { return document.querySelector(sel); } catch { return null; }
+}
+
+// Find a region/host element that claims this item id via `data-for`
+// (space-separated list of ids).
+function claimedRegion(id) {
+  if (!id) return null;
+  for (const el of document.querySelectorAll('[data-for]')) {
+    if ((el.getAttribute('data-for') || '').split(/\s+/).includes(id)) return el;
+  }
+  return null;
+}
+
+/**
+ * Resolve where a launcher's content should go.
+ * @returns {{kind:'element', element:Element} | {kind:'modal'|'floating'|'tab'|'window'} | {kind:null}}
+ */
+export function resolveRegion(launcher, id, fallbackEl = null) {
+  const claimed = claimedRegion(id);
+  if (claimed) return { kind: 'element', element: claimed };
+
+  let value = null;
+  const scope = launcher && launcher.closest ? launcher.closest('[region]') : null;
+  if (scope) value = scope.getAttribute('region');
+  if (!value) {
+    const def = document.querySelector('sol-default[region]');
+    if (def) value = def.getAttribute('region');
+  }
+
+  if (!value) return fallbackEl ? { kind: 'element', element: fallbackEl } : { kind: null };
+
+  const kw = value.toLowerCase();
+  if (SURFACE_KEYWORDS.has(kw)) return { kind: kw };
+  const el = safeQuery(value);
+  if (el) return { kind: 'element', element: el };
+  return fallbackEl ? { kind: 'element', element: fallbackEl } : { kind: null };
+}
+
+/**
+ * Place a launcher's content into its resolved region.
+ *
+ * @param {object} o
+ * @param {Element|null} o.launcher   element initiating (for region cascade)
+ * @param {string|null}  o.id         item id (for data-for routing)
+ * @param {string}       o.name       pane wrapper / surface title
+ * @param {string|null}  o.tag        content element tag
+ * @param {Array<[string,string]>} [o.attrs]
+ * @param {string|null}  o.href       used for tab/window surfaces
+ * @param {string|null}  o.contents   literal HTML
+ * @param {boolean}      [o.replace]  pane lifetime (true = rebuild each time)
+ * @param {string|null}  [o.embedClass]
+ * @param {Element|null} [o.fallbackEl] where to mount if no region resolves
+ * @param {(tag:string)=>void} [o.ensure] lazy-load hook for conjured hosts
+ * @returns {Element|Window|null}
+ */
+export function displayItem({
+  launcher = null, id = null, name = '', tag = null, attrs = [],
+  href = null, contents = null, replace = false, embedClass = null,
+  fallbackEl = null, ensure = null,
+}) {
+  const region = resolveRegion(launcher, id, fallbackEl);
+  const mount = (host) => {
+    if (contents != null) host.innerHTML = contents;
+    else if (tag)        host.appendChild(buildElement(tag, attrs, embedClass));
+  };
+
+  switch (region.kind) {
+    case 'tab':    return href ? window.open(href, '_blank', '') : null;
+    case 'window': return href ? window.open(href, '_blank', 'width=900,height=700,menubar=no,toolbar=no') : null;
+    case 'modal':    return conjure('sol-modal',  name, mount, ensure);
+    case 'floating': return conjure('sol-window', name, mount, ensure);
+    case 'element':  return mountInElement(region.element, { tag, attrs, name, replace, contents, embedClass, mount });
+    default:         return null;
+  }
+}
+
+function mountInElement(element, { tag, attrs, name, replace, contents, embedClass, mount }) {
+  const t = (element.tagName || '').toLowerCase();
+
+  if (t === 'sol-modal') {
+    element.handler = (body) => mount(body);
+    element.open();
+    return element;
+  }
+  if (t === 'sol-window') {
+    mount(element.body || element);
+    return element;
+  }
+  // A pane: literal HTML replaces its content; otherwise a keep-alive (or
+  // replace) named wrapper via the shared mount helper.
+  if (contents != null) { element.innerHTML = contents; return element; }
+  if (!tag) return null;
+  return mountInTarget({ target: element, name, tag, attrs, embedClass, replace });
+}
+
+// Conjure an ephemeral host (sol-modal / sol-window) with no author element.
+// Deferred via whenDefined so open()/body exist once the module upgrades.
+function conjure(hostTag, name, mount, ensure) {
+  if (ensure) ensure(hostTag);
+  const run = () => {
+    const host = document.createElement(hostTag);
+    if (name) host.setAttribute('title', name);
+    if (hostTag === 'sol-modal') {
+      host.handler = (body) => mount(body);
+      host.open();
+    } else {
+      document.body.appendChild(host);
+      mount(host.body || host);
+    }
+    return host;
+  };
+  if (customElements.get(hostTag)) return run();
+  if (typeof customElements !== 'undefined') customElements.whenDefined(hostTag).then(run);
+  return null;
+}