@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/core/routes.ts

@@ -0,0 +1,115 @@
+// Which URLs are search / category pages. Pure and tiny: the entry needs it on
+// every URL change (to hold the host's page before it paints).
+
+import type { ParamMap, PlpConfigType, SearchConfigType } from '../types';
+import { reportError } from './health';
+
+/** An integration's URL hook (active, readQuery) that throws: the page is not ours. */
+const guarded = (where: string, f: (u: URL) => boolean) => (u: URL) => {
+  try {
+    return f(u);
+  } catch (e) {
+    reportError(where, e);
+    return false;
+  }
+};
+
+/** Namespace of our own URL params (facets, page, sort we cannot express in the host's). */
+export const P = 'lbx.';
+
+// Tracking params, and the LBX loader's own (_lbx_env=development, …): never a reason to leave a page to the host.
+export const TRACKING = '^(utm_|_lbx_|gclid$|gbraid$|wbraid$|fbclid$|msclkid$|_gl$|mc_(cid|eid)$|srsltid$)';
+const TRACKING_RE = new RegExp(TRACKING);
+
+/** A URL without the params in `ignore` (default: tracking) and without its #hash: the page it shows. */
+export const withoutTracking = (href: string, ignore = TRACKING_RE) => {
+  const u = new URL(href);
+  for (const k of [...u.searchParams.keys()]) if (ignore.test(k)) u.searchParams.delete(k);
+  u.hash = '';
+  return u;
+};
+
+/** decodeURIComponent that never throws (a stray `%` in a hand-typed URL): the raw text instead. */
+const decode = (s: string) => {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+};
+
+/** Most pages a listing appends ("show more"), each one cursor request: a bound on the tiles kept in the page and in a stash. */
+export const MAX_PAGE = 50;
+/** A host page param that means the first page (absent is too): any later page of theirs is theirs to render. */
+export const firstPage = (v: string) => /^0*1$/.test(v.trim());
+
+/** Own keys only: a param named `constructor` or `__proto__` is not a mapped value. */
+export const has = (o: object, k: string) => Object.prototype.hasOwnProperty.call(o, k);
+
+export const searchReadQuery = (c: SearchConfigType) => {
+  if (c.readQuery) {
+    const read = c.readQuery;
+    return (u: URL) => {
+      try {
+        return read(u);
+      } catch (e) {
+        reportError('search readQuery', e);
+        return '';
+      }
+    };
+  }
+  const re = c.urlMatch ? new RegExp(c.urlMatch) : null;
+  return (u: URL) => (c.queryParam ? u.searchParams.get(c.queryParam) : decode((re?.exec(u.pathname)?.[1] ?? '').replace(/\+/g, ' ')))?.trim() || '';
+};
+
+export const searchAccepts = (c: SearchConfigType) => {
+  if (c.active) return guarded('search active', c.active);
+  const re = c.urlMatch ? new RegExp(c.urlMatch) : null;
+  const read = searchReadQuery(c);
+  return guarded('search readQuery', (u: URL) => (!re || re.test(u.pathname)) && !!read(u));
+};
+
+/** Values of a host param, splitting joined lists (filters=new,sale). */
+export const paramValues = (url: URL, param: string, sep?: string) =>
+  url.searchParams
+    .getAll(param)
+    .flatMap((v) => (sep ? v.split(sep) : [v]))
+    .filter(Boolean);
+
+export const flagId = (f: { param: string; value: string }) => `${f.param}=${f.value}`;
+
+/**
+ * A category URL is ours only if every param on it is one we can express;
+ * anything else leaves the page to the host, so no URL ever loses a filter.
+ */
+export const plpAccepts = (c: Pick<PlpConfigType, 'urlMatch' | 'params' | 'active'>) => {
+  const re = new RegExp(c.urlMatch);
+  const pm: ParamMap = c.params ?? {};
+  const ignore = new RegExp(pm.ignore ?? TRACKING);
+  const flags = pm.flags ?? [];
+  const facetParams = pm.facetParams ?? {};
+  const byParam = new Map(Object.entries(facetParams).map(([facet, fp]) => [fp.param, facet]));
+  const ranges = new Set((pm.ranges ?? []).flatMap((r) => [r.min, r.max]));
+  return guarded('plp active', (url: URL) => {
+    if (!(c.active ? c.active(url) : re.test(url.pathname))) return false;
+    for (const k of new Set(url.searchParams.keys())) {
+      const vs = paramValues(url, k, pm.separator);
+      // Our own lbx.* params are written only by our UI.
+      if (!vs.length || k.startsWith(P) || ignore.test(k) || ranges.has(k)) continue;
+      // Pages are appended, never opened (a cursor can only be followed): their
+      // page 2 is theirs to render, their page 1 is ours.
+      if (k === pm.page && vs.every(firstPage)) continue;
+      if (pm.sort && k === pm.sort.param && vs.every((v) => has(pm.sort!.values, v))) continue;
+      if (flags.some((f) => f.param === k) && vs.every((v) => flags.some((f) => f.param === k && f.value === v))) continue;
+      const facet = byParam.get(k);
+      if (facet) {
+        const fp = facetParams[facet];
+        const map = fp.values;
+        // Mapped values (not to ''), or any value where they pass through (slug: false).
+        if (!map || vs.every((v) => (has(map, v) ? !!map[v] : fp.slug === false))) continue;
+      }
+      return false;
+    }
+    return true;
+  });
+};

package/src/core/scheduler.ts

@@ -0,0 +1,83 @@
+// Every signal (URL change, DOM mutation, timer, widget request) collapses into
+// "please reconcile soon". At most one reconcile per animation frame.
+
+import { reportError } from './health';
+
+type Task = () => void;
+
+const tasks = new Set<Task>();
+let pending = false;
+
+const flush = () => {
+  pending = false;
+  for (const t of [...tasks]) {
+    try {
+      t();
+    } catch (e) {
+      reportError('flush', e);
+    }
+  }
+};
+
+export const onFlush = (t: Task) => tasks.add(t);
+
+// Until the first paint the browser runs no frames (no rAF), yet this is when
+// we want to be placed: our listing can then render as soon as its data
+// arrives, and its webfonts get requested while the page is still loading.
+let framesRunning = false;
+const firstPaintDone = () =>
+  framesRunning || (framesRunning = performance.getEntriesByType('paint').length > 0 || document.readyState === 'complete');
+
+export const schedule = () => {
+  if (pending) return;
+  pending = true;
+  // rAF does not run in background tabs or before the first paint; use a timeout there.
+  if (document.visibilityState === 'visible' && firstPaintDone()) requestAnimationFrame(flush);
+  else setTimeout(flush, document.visibilityState === 'visible' ? 16 : 50);
+};
+
+export const scheduleIn = (ms: number) => setTimeout(schedule, ms);
+
+/**
+ * `f` in a task after the next frame has rendered: the page's styles and layout
+ * are clean then, so reading computed styles or sizes costs only what we read,
+ * not a style pass over the whole (host) document. Where no frames run (a
+ * hidden tab, before the first paint) in a task of its own; a tab hidden
+ * meanwhile (rAF waits until it is shown) by a timeout.
+ */
+export const afterFrame = (f: Task) => {
+  if (document.visibilityState !== 'visible') {
+    // A message, not a timer: timers in background tabs wait up to a second.
+    const c = new MessageChannel();
+    c.port1.onmessage = () => f();
+    return c.port2.postMessage(0);
+  }
+  if (!firstPaintDone()) return void setTimeout(f, 16);
+  let done = false;
+  const run = () => !done && ((done = true), f());
+  // Ahead of the page's own queued tasks where the browser can (Chrome's scheduler).
+  const post = (globalThis as any).scheduler?.postTask;
+  requestAnimationFrame(() => (post ? post.call((globalThis as any).scheduler, run, { priority: 'user-blocking' }) : setTimeout(run, 0)));
+  setTimeout(run, 500);
+};
+
+let pendingNow = false;
+/**
+ * Reconcile in the current microtask checkpoint, i.e. before the browser paints.
+ * Used when the host just removed one of our nodes: waiting for the next frame
+ * would paint at least one frame without us (a visible flash).
+ */
+export const scheduleNow = () => {
+  if (pendingNow) return;
+  pendingNow = true;
+  queueMicrotask(() => {
+    pendingNow = false;
+    flush();
+  });
+};
+
+/**
+ * Promise check that survives a replaced global: Zone.js (Angular) swaps
+ * window.Promise after we load, so `instanceof Promise` misses native promises.
+ */
+export const isPromise = <T>(x: unknown): x is Promise<T> => typeof (x as any)?.then === 'function';

package/src/core/sense.ts

@@ -0,0 +1,107 @@
+// Sensing layer. Its only job is to turn host activity into schedule() calls
+// and to notify URL listeners. Correctness does not depend on catching every
+// signal: the reconciler is level-triggered and recomputes from scratch.
+
+import { schedule, scheduleNow } from './scheduler';
+import { reportError } from './health';
+import { ownBack } from './entries';
+import { isOwnNode, OWN_ATTR, ownRemovalsWatched } from './own';
+
+type UrlListener = (url: URL) => void;
+const urlListeners = new Set<UrlListener>();
+let lastHref = location.href;
+
+export const onUrlChange = (l: UrlListener) => {
+  urlListeners.add(l);
+  return () => urlListeners.delete(l);
+};
+
+const checkUrl = () => {
+  if (location.href === lastHref) return;
+  lastHref = location.href;
+  const url = new URL(location.href);
+  // One listener throwing (an integration hook inside it) must not keep the
+  // others, or the reconcile, from hearing about this URL.
+  for (const l of [...urlListeners]) {
+    try {
+      l(url);
+    } catch (e) {
+      reportError('url change', e);
+    }
+  }
+  schedule();
+};
+
+/**
+ * The Navigation API has shown it reports history writes (one of ours fired
+ * currententrychange): a DOM change then needs no look at the URL (a router
+ * that kept the history methods from before our wrappers is reported too).
+ * On a busy page (a carousel) that look was most of our time.
+ */
+let urlReported = false;
+
+const senseUrl = () => {
+  // The Navigation API sees pushState/replaceState from any router, even one
+  // that kept the original methods before we wrapped them, and
+  // navigation.navigate(). But WebKit's (Safari 26.2+) fires no
+  // currententrychange for pushState/replaceState: history is wrapped
+  // everywhere too (always delegating to the original), and checkUrl is a
+  // no-op for a URL it has seen.
+  const nav = (window as any).navigation;
+  let navEvents = 0;
+  if (nav && typeof nav.addEventListener === 'function') nav.addEventListener('currententrychange', () => (navEvents++, checkUrl()));
+  for (const m of ['pushState', 'replaceState'] as const) {
+    const orig = history[m];
+    if ((orig as any).__lbxWrapped) continue;
+    const wrapped = function (this: History, ...args: any[]) {
+      const before = navEvents;
+      const r = (orig as any).apply(this, args);
+      // Chromium reports it in the call: from then on the Navigation API is
+      // trusted with every URL change (WebKit's never reports one here).
+      if (navEvents > before) urlReported = true;
+      queueMicrotask(checkUrl);
+      return r;
+    };
+    (wrapped as any).__lbxWrapped = true;
+    history[m] = wrapped as any;
+  }
+  // Capture, and added before any other listener of ours (startSensing runs
+  // first): a popstate listener that stops the event (core/turbo.ts, on a
+  // back/forward between our states) must not keep the URL change from us.
+  // At the window, capture listeners run before the others; where there is
+  // no Navigation API (Firefox, Safari before 26.2) this is the only signal
+  // of a back/forward (Chromium's currententrychange came before popstate).
+  // Back from an entry that only stood for something of ours being open (the
+  // autocomplete's phone sheet, core/entries.ts): ours alone, first.
+  addEventListener('popstate', (e) => ownBack() && e.stopImmediatePropagation(), true);
+  addEventListener('popstate', checkUrl, true);
+  addEventListener('hashchange', checkUrl, true);
+};
+
+const senseDom = () => {
+  const ownRemoved = (r: MutationRecord) =>
+    [...r.removedNodes].some((n) => n.nodeType === 1 && ((n as Element).hasAttribute(OWN_ATTR) || !!(n as Element).querySelector(`[${OWN_ATTR}]`)));
+  // On the document, not its root element: a host that re-renders the whole
+  // document (React hydrating <html>) replaces documentElement.
+  new MutationObserver((records) => {
+    // The host removed one of our nodes (re-render, hydration): put it back
+    // before the next paint.
+    if (ownRemovalsWatched() && records.some(ownRemoved)) scheduleNow();
+    // Ignore mutations that happen entirely inside our own nodes.
+    for (const r of records) {
+      if (!isOwnNode(r.target)) {
+        schedule();
+        // URL changes without history events (rare) are also caught here,
+        // unless the Navigation API has shown it reports them all.
+        if (!urlReported) checkUrl();
+        return;
+      }
+    }
+  }).observe(document, { childList: true, subtree: true });
+};
+
+export const startSensing = () => {
+  senseUrl();
+  senseDom();
+  addEventListener('pageshow', () => schedule());
+};

package/src/core/speculation.ts

@@ -0,0 +1,59 @@
+// Product pages prerendered (or prefetched) on intent, with the Speculation
+// Rules API (Chrome, Edge 121+): one document rule for the links in our
+// widgets, `moderate` eagerness (~200 ms of hover, pointerdown on touch). The
+// browser keeps at most two such prerenders and drops the oldest, so a
+// handful of hovers never becomes a handful of page renders at once.
+// On by default: `_global.speculation` ('prerender', the default | 'prefetch' | false). In the shared
+// support chunk (core/support.ts): our links exist only once a widget has
+// loaded, so the entry installs the rules with the first widget. No DOM at
+// import (the server renderer imports support too).
+//
+// Links that are not page views are left out: rails-ujs `data-method` /
+// `data-remote` (a GET of a POST action), `rel=nofollow`, downloads, other
+// windows. Our own listing links (filters, sort, pages) are not in the default
+// selector: they are handled in place, not navigated.
+//
+// Our bundle in a prerendered page: it boots there as on any page (window.__lbx
+// guards a second copy); see the takeover's hold timer, which waits for the
+// activation (core/takeover.ts).
+
+import { mark } from './health';
+import type { GlobalConfigType } from '../types';
+
+const LINKS = ':is(lbx-search, lbx-plp) [data-lbx-list] a[href], lbx-reco a[href], [data-lbx="ac-overlay"] a[href]';
+const NOT_A_VIEW = '[data-method], [data-remote], [rel~="nofollow"], [download], [target]:not([target="_self"])';
+
+let installed = false;
+export const speculate = (g: GlobalConfigType, onUrlChange: (f: () => void) => unknown) => {
+  const mode = g.speculation ?? 'prerender';
+  if (installed || (mode !== 'prerender' && mode !== 'prefetch') || !(HTMLScriptElement as any).supports?.('speculationrules')) return;
+  installed = true;
+  const rules = {
+    [mode]: [
+      {
+        source: 'document',
+        where: {
+          and: [
+            { href_matches: ['/*', '/*\\?*'] }, // same origin (relative to the page), with or without a query
+            { selector_matches: g.speculationSelector || LINKS },
+            { not: { selector_matches: NOT_A_VIEW } },
+          ],
+        },
+        eagerness: g.speculationEagerness ?? 'moderate',
+      },
+    ],
+  };
+  let el: HTMLScriptElement | null = null;
+  const put = () => {
+    if (el?.isConnected) return;
+    el = document.createElement('script');
+    el.type = 'speculationrules';
+    el.setAttribute('data-lbx', 'speculation');
+    el.textContent = JSON.stringify(rules);
+    document.head.append(el);
+  };
+  put();
+  // A host that swaps <head> (an SPA visit) may take it: put back on the next URL.
+  onUrlChange(put);
+  mark(`speculation rules: ${mode}`);
+};

package/src/core/stash.ts

@@ -0,0 +1,38 @@
+// A listing result kept in sessionStorage for the next page load of its URL
+// (widgets/listing/stash.ts reads and writes them). The entry only asks
+// whether this load can use one: a search page then does not send its own
+// request before the listing's chunk has read it.
+import { pageKey } from './page';
+
+export const STASH = 'lbx:r:';
+export const stashKey = (href: string) => STASH + pageKey(href);
+
+/** How this document was loaded, and its URL (a later SPA visit is not the load a stash is for). */
+export const navigation = () => {
+  try {
+    const n = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming | undefined;
+    return { type: n?.type ?? 'navigate', url: n?.name || location.href };
+  } catch {
+    return { type: 'navigate', url: location.href };
+  }
+};
+
+/**
+ * Which load a stash kind is for: a typed query's page by a navigation (or a
+ * prerender of it, `prerender` from its start through its activation), a
+ * listing left for a product by back/forward.
+ */
+export const stashFits = (kind: string) => {
+  const t = navigation().type;
+  return kind === 'back' ? t === 'back_forward' : t === 'navigate' || t === 'prerender';
+};
+
+/** A stash this load will likely use (the listing checks it fully). Reads only the start of the entry. */
+export const hasStash = (href: string) => {
+  try {
+    const head = sessionStorage.getItem(stashKey(href))?.slice(0, 60);
+    return !!head && stashFits(head.includes('"kind":"back"') ? 'back' : 'spec');
+  } catch {
+    return false;
+  }
+};

package/src/core/storage.ts

@@ -0,0 +1,45 @@
+// Small caches. No DOM: the edge render service uses them too.
+
+/** sessionStorage as a best-effort JSON store: storage may be unavailable (private mode, quota, Node), never required. */
+export const session = {
+  get<T>(k: string): T | undefined {
+    try {
+      const v = sessionStorage.getItem(k);
+      return v == null ? undefined : (JSON.parse(v) as T);
+    } catch {
+      return undefined;
+    }
+  },
+  set(k: string, v: unknown) {
+    try {
+      if (v === undefined) sessionStorage.removeItem(k);
+      else sessionStorage.setItem(k, JSON.stringify(v));
+    } catch {}
+  },
+};
+
+/**
+ * A bounded memo (least recently used out) whose entries expire: in a
+ * long-running server every distinct URL would otherwise stay forever, and a
+ * "not found" would outlive the catalog change that fixes it.
+ */
+export const lru = <V>(max: number, ttlMs = 10 * 60e3) => {
+  const m = new Map<string, { v: V; at: number }>();
+  return {
+    /** undefined = not cached (store null, not undefined, for a known "nothing"). */
+    get(k: string): V | undefined {
+      const e = m.get(k);
+      if (!e) return undefined;
+      m.delete(k);
+      if (Date.now() - e.at > ttlMs) return undefined;
+      m.set(k, e);
+      return e.v;
+    },
+    set(k: string, v: V) {
+      m.delete(k);
+      m.set(k, { v, at: Date.now() });
+      if (m.size > max) m.delete(m.keys().next().value!);
+    },
+    delete: (k: string) => void m.delete(k),
+  };
+};

package/src/core/styles.ts

@@ -0,0 +1,106 @@
+// Stylesheets we own, one <style data-lbx="styles"> per section, so changing one
+// (a route's host CSS on every takeover step) does not re-parse the others:
+// on a large host DOM a whole-sheet rewrite costs a document-wide style pass.
+// Two kinds of rules:
+//  - component CSS in @layer lbx: any unlayered host CSS beats it, so the host
+//    design wins by default (typography, links, buttons, their tile classes).
+//    The layer is declared first in <head>, so it also ranks below the host's
+//    own layers (Tailwind's utilities): among layers, the first declared loses.
+//    Not on a page React may yet hydrate as a whole (it hydrates <head> too, and
+//    React 18 tolerates extra nodes only at the end): there at the end (not
+//    while <head> is still parsing), and first once React has it.
+//  - host overrides (hide their native autocomplete / results): unlayered and
+//    route-scoped. CSS survives host re-renders, DOM mutations would not.
+// Every sheet is put back when a host re-render drops it (onFlush).
+
+import { documentMayHydrate, hasFiber, watchOwnRemovals } from './own';
+import { onFlush } from './scheduler';
+
+// While <head> is still parsing, on every page: whole-document frameworks
+// announce themselves only at the end of <body>, and the body-start observer
+// puts ours in before anything of the body paints.
+const deferred = () => !document.body;
+
+const sheets = new Map<string, HTMLStyleElement>();
+
+/** The page's CSP nonce (from any script carrying one): a strict style-src blocks our <style>s without it. */
+export const cspNonce = () => (document.querySelector('script[nonce]') as HTMLScriptElement | null)?.nonce || '';
+const styleEl = () => {
+  const s = document.createElement('style');
+  s.setAttribute('data-lbx', 'styles');
+  const n = cspNonce();
+  if (n) s.nonce = n;
+  return s;
+};
+
+let order: HTMLStyleElement | null = null;
+const declareLayer = () => {
+  const head = document.head || document.documentElement;
+  // React has it once it has claimed <head>, or <html> when its root renders
+  // no <head> of its own (Next's app router: Next fills it): hydrated past it.
+  const early = (document.readyState === 'loading' || documentMayHydrate()) && !hasFiber(head) && !hasFiber(document.documentElement);
+  if (order?.isConnected && (early || head.firstElementChild === order)) return;
+  order ??= styleEl();
+  order.textContent = '@layer lbx;';
+  // <head> still parsing on a page React may hydrate as a whole: appended once it is complete (onFlush).
+  if (deferred()) return;
+  if (early) head.append(order);
+  else head.prepend(order);
+};
+
+/** Our sheets into the document: the missing ones (dropped by a host re-render, or deferred). */
+const restore = () => {
+  if (deferred()) return;
+  if (sheets.size) {
+    declareLayer();
+    for (const s of sheets.values()) if (!s.isConnected) (document.head || document.documentElement).append(s);
+  }
+  for (const f of applied.splice(0)) f();
+};
+onFlush(restore);
+
+// Deferred sheets go in the moment <body> starts (then <head> is complete), in
+// a microtask: before anything of the body can paint.
+let bodyWatch: MutationObserver | null = null;
+const watchForBody = () => {
+  if (bodyWatch || document.body) return;
+  bodyWatch = new MutationObserver(() => {
+    if (!document.body) return;
+    bodyWatch!.disconnect();
+    restore();
+  });
+  bodyWatch.observe(document.documentElement, { childList: true });
+};
+
+const applied: (() => void)[] = [];
+/**
+ * Run `f` once our sheets are in the document, i.e. once <head> is complete
+ * (at once, unless it is still being parsed): e.g. only then drop an early
+ * hold's CSS, or add links of ours to <head>.
+ */
+export const whenApplied = (f: () => void) => (deferred() ? (applied.push(f), watchForBody()) : f());
+
+export const setCss = (key: string, css: string | null) => {
+  if (css != null) declareLayer(), watchOwnRemovals(); // first, and back if a head manager removed it
+  const el = sheets.get(key);
+  if (css == null) {
+    el?.remove();
+    sheets.delete(key);
+    return;
+  }
+  const s = el ?? styleEl();
+  if (s.textContent !== css) s.textContent = css;
+  // Back into the document if a host re-render dropped it (onFlush does the same).
+  // At once (a hold must apply before first paint), except mid-<head> on a page
+  // React may hydrate as a whole (React 18 would re-render the document).
+  if (!s.isConnected) {
+    if (deferred()) watchForBody();
+    else (document.head || document.documentElement).append(s);
+  }
+  if (!el) {
+    s.dataset.key = key;
+    sheets.set(key, s);
+  }
+};
+
+export const layered = (css: string) => `@layer lbx {\n${css}\n}`;

package/src/core/support.ts

@@ -0,0 +1,12 @@
+// What every widget needs and the entry does not: the API client,
+// translations and result helpers. One shared chunk, loaded with the first widget.
+export { getApi } from '../api';
+export { widgetContext } from './context';
+export { loadWidgetInits } from './widget-inits';
+export { loadDictionary, translator } from './i18n';
+export { first, plain, resultFactory } from './result';
+export { speculate } from './speculation';
+// Images (./images.ts, ./image-tags.ts, ./image-load.ts): every widget's templates and pages.
+export { imageHelpers } from './image-tags';
+export { firstRowCount, firstRowImages, imageOf } from './images';
+export { preloadImages, settleImages, warmImages } from './image-load';