@luigisbox/luma 0.1.0 → 0.3.0

package/src/core/tiles.ts

@@ -0,0 +1,137 @@
+// Clicks and add-to-carts on our own tiles, seen by the framework: no template
+// says anything about them. Every widget that renders products calls
+// `watch()` on its root once (listings, recommenders, the popup) or `picked()`
+// (the autocomplete's own navigation); the rest follows from the markup:
+//
+// - a product click is a click (any button: a middle click, a modifier opens
+//   a tab, still a click) on a link to a result's URL inside a list of ours
+//   (`[data-lbx-list]`); the result is the one with that URL (the tile's own
+//   when two share it), else, where the integration's link is not `r.c.url`,
+//   the tile's at its position (tiles map to hits by position, as the view
+//   transitions and focus code assume). Other links in a tile (wishlist,
+//   compare) are not product clicks.
+// - an add-to-cart is a click on `[data-lbx-cart]` in a tile (its value: the
+//   quantity, default 1): `_global.addToCart(result, { count, el, event })`
+//   puts it in the site's cart. Without that hook nothing happens (and it
+//   says so).
+//
+// Each is announced as an `lbx:tile` event on document (TileEvent): analytics
+// listens only where the integration's _analytics.ts asks (its `lumaClicks()`,
+// `lumaCarts()` triggers), so a widget brings no analytics code. Analytics may
+// not be listening yet (its chunk and the setup come after the widget's), or
+// the click may leave the page: so each is first queued in sessionStorage, in
+// the click's own task, where analytics claims it, on this page or the next.
+// Not where the integration has no analytics (`_global.analytics` false: the
+// entry sets it where there is no _analytics.ts).
+
+import { reportError } from './health';
+import { session } from './storage';
+import type { GlobalConfigType, Result } from '../types';
+
+/** `detail` of an `lbx:tile` event. */
+export interface TileEvent {
+  /** Its id in the queue. */
+  id: string;
+  kind: 'click' | 'add_to_cart';
+  /** `<type>/@id:<id>`: the result's reference. */
+  reference: string;
+  result: Result;
+  /** Its position in the list (0-based). */
+  index: number;
+  /** Our list: `lbx_search`, `lbx_plp`, `lbx_reco_<name>`, `lbx_autocomplete`. */
+  list: string;
+  count?: number;
+  price?: number;
+  /** The page it happened on, and when (ms epoch): what the event carries, sent later or not. */
+  url: string;
+  at: number;
+}
+export interface Watched {
+  list: string;
+  /** The results the list shows now, in tile order. */
+  results: () => readonly Result[];
+  global: GlobalConfigType;
+}
+
+/** The queue analytics claims from (src/analytics/triggers.ts). */
+export const TILES = 'lbx:tiles';
+const announce = (g: GlobalConfigType, e: Omit<TileEvent, 'id' | 'url' | 'at'>) => {
+  if (g.analytics === false) return;
+  const d = { ...e, id: crypto.randomUUID(), url: location.href, at: Date.now() };
+  session.set(TILES, [...(session.get<TileEvent[]>(TILES) ?? []), d].slice(-20));
+  try {
+    document.dispatchEvent(new CustomEvent('lbx:tile', { detail: d }));
+  } catch (err) {
+    reportError('tile event', err);
+  }
+};
+const reference = (r: Result) => `${r.type || 'product'}/@id:${r.id}`;
+
+/** A result clicked (a link to it, or our own navigation: the autocomplete). */
+export const picked = (r: Result, index: number, list: string, g: GlobalConfigType) => announce(g, { kind: 'click', reference: reference(r), result: r, index, list });
+
+const watched = new WeakSet<Element>();
+/** Product clicks and add-to-carts inside `root` (once per root). */
+export const watch = (root: Element, w: Watched) => {
+  if (watched.has(root)) return;
+  watched.add(root);
+  const on = (e: MouseEvent) => {
+    if (e.type === 'auxclick' && e.button !== 1) return;
+    try {
+      const t = e.target instanceof Element ? e.target : null;
+      const tile = t?.closest('[data-lbx-list] > *');
+      if (!tile || !root.contains(tile)) return;
+      const results = w.results();
+      const tiles = [...tile.parentElement!.children];
+      const at = tiles.indexOf(tile);
+      const cart = t!.closest<HTMLElement>('[data-lbx-cart]');
+      if (cart && tile.contains(cart)) return void (e.type === 'click' && toCart(e, cart, tile, at, tiles.length, results, w));
+      const a = t!.closest<HTMLAnchorElement>('a[href]');
+      if (!a || !tile.contains(a)) return;
+      const r = resultOf(a, at, tiles.length, results);
+      if (r) picked(r.r, r.i, w.list, w.global);
+    } catch (err) {
+      reportError('tile click', err);
+    }
+  };
+  // Capture: before a handler of the tile (or the site's) stops it or navigates.
+  root.addEventListener('click', on as EventListener, true);
+  root.addEventListener('auxclick', on as EventListener, true);
+};
+
+const sameUrl = (r: Result, href: string) => {
+  try {
+    return !!r.c.url && new URL(r.c.url, location.href).href === href;
+  } catch {
+    return false;
+  }
+};
+
+/** The result a link in the tile at `at` leads to. */
+const resultOf = (a: HTMLAnchorElement, at: number, n: number, results: readonly Result[]) => {
+  const same = results.flatMap((r, i) => (sameUrl(r, a.href) ? [{ r, i }] : []));
+  if (same.length) return same.find((x) => x.i === at) ?? same[0];
+  // The integration's link is not r.c.url (its own params): the tile's, where tiles are the results.
+  if (n === results.length && results[at] && a.origin === location.origin && !a.matches('[data-remote], [data-method], [download]')) return { r: results[at], i: at };
+  return null;
+};
+
+const toCart = (e: MouseEvent, el: HTMLElement, tile: Element, at: number, n: number, results: readonly Result[], w: Watched) => {
+  // A cart button inside the tile's link must not follow it.
+  e.preventDefault();
+  e.stopPropagation();
+  const link = [...tile.querySelectorAll<HTMLAnchorElement>('a[href]')].map((a) => resultOf(a, at, n, results)).find(Boolean);
+  const hit = link ?? (n === results.length && results[at] ? { r: results[at], i: at } : null);
+  if (!hit) return reportError('add to cart', 'a [data-lbx-cart] in a tile whose result is unknown (its links lead to no result, and tiles are not the results)');
+  const hook = w.global.addToCart;
+  if (typeof hook !== 'function') return reportError('add to cart', '[data-lbx-cart] needs _global.addToCart (_init.ts or _global/_widget.ts) to put the product in the site\'s cart');
+  const count = Math.max(1, Math.round(Number(el.dataset.lbxCart) || 1));
+  const price = typeof hit.r.c.price === 'number' ? hit.r.c.price : undefined;
+  announce(w.global, { kind: 'add_to_cart', reference: reference(hit.r), result: hit.r, index: hit.i, list: w.list, count, ...(price !== undefined ? { price } : {}) });
+  try {
+    const p = hook(hit.r, { count, el, event: e });
+    if (p && typeof (p as Promise<unknown>).catch === 'function') (p as Promise<unknown>).catch((err) => reportError('addToCart', err));
+  } catch (err) {
+    reportError('addToCart', err);
+  }
+};

package/src/main.ts

@@ -21,10 +21,11 @@ import type { T } from './core/i18n';
 import { failures, holdCss, MAX_FAILURES, painted, reserveCss } from './core/hold';
 import { hostStyle, LISTINGS, loadConfig, loadTranslations, widgetFiles, type IntegrationFiles } from './core/integration';
 import type { Templates } from './core/templates';
-import { plpAccepts, searchAccepts } from './core/routes';
+import { plpAccepts, searchAccepts, searchReadQuery } from './core/routes';
 import { clearEarlyRules, earlyHold, plpRule, searchRule, writeEarlyRules, type EarlyRoute } from './core/early-rules';
 import { askChallenge, storedToken } from './api/token-key';
 import { loadDictionary } from './core/locales';
+import { keepDl } from './core/kept';
 import './core/boot-state'; // the page's state at boot, for lbx-place's reconciler
 import { onFlush, schedule } from './core/scheduler';
 import { onUrlChange, startSensing } from './core/sense';
@@ -153,11 +154,19 @@ function boot(config: LumaConfigType, files: IntegrationFiles) {
     askChallenge(g); // while the minting code loads
     import('./api/token').then((m) => m.warmToken(g)).catch((e) => reportError('token', e));
   };
-  const idle = () => (typeof requestIdleCallback === 'function' ? requestIdleCallback(warm, { timeout: 2000 }) : setTimeout(warm, 200));
-  if (document.readyState === 'complete') idle();
-  else addEventListener('load', idle, { once: true });
+  const afterLoad = (f: () => void) => {
+    const idle = () => (typeof requestIdleCallback === 'function' ? requestIdleCallback(f, { timeout: 2000 }) : setTimeout(f, 200));
+    if (document.readyState === 'complete') idle();
+    else addEventListener('load', idle, { once: true });
+  };
+  afterLoad(warm);
   startSensing();
 
+  // Analytics starts once the page has loaded, or with the first widget (its
+  // setup then listens before a tile is clicked). Set up at the end of boot.
+  let analyticsWanted = false;
+  let startAnalytics = () => void (analyticsWanted = true);
+
   // --- lazy widget loading: code + templates + styles + dictionaries in parallel
   const locale = g.locale ?? 'en';
   const loaded = new Map<string, Promise<Loaded>>();
@@ -165,6 +174,7 @@ function boot(config: LumaConfigType, files: IntegrationFiles) {
     if (loaded.has(id)) return loaded.get(id)!;
     mark(`load ${id}`);
     warm();
+    startAnalytics();
     const support = import('./core/support');
     const p = Promise.all([
       modules[kind]() as Promise<any>,
@@ -404,6 +414,8 @@ function boot(config: LumaConfigType, files: IntegrationFiles) {
   // boot where a popup one is configured (its trigger may fire on any page).
   const recos: Reco[] = [];
   const pages: ((u: URL) => boolean)[] = [];
+  /** Our recommenders by name, and the pages each runs on: where ours runs, the site's of that name is not tracked. */
+  const recoPages = new Map<string, (u: URL) => boolean>();
   for (const [name, rc] of Object.entries(config.recommenders ?? {})) {
     if (rc.disabled) continue;
     const id = `reco-${name}`;
@@ -417,6 +429,7 @@ function boot(config: LumaConfigType, files: IntegrationFiles) {
     recos.push({ id, rc, get: () => load('recommender', id, folders, rc, ['recommender']) });
     const re = !rc.confirm && rc.urlMatch ? setUp(id, () => new RegExp(rc.urlMatch!)) : null;
     pages.push(rc.confirm ? () => true : (u) => (rc.active ? rc.active(u) : !re || re.test(u.pathname)));
+    recoPages.set(name, pages[pages.length - 1]);
   }
   if (recos.length) {
     let asked = false;
@@ -439,5 +452,42 @@ function boot(config: LumaConfigType, files: IntegrationFiles) {
     onFlush(() => recent() && check());
   }
 
+  // --- analytics (src/analytics, lbx-analytics): where the integration has an
+  // _analytics.ts (nothing is sent that it does not say), every page once it
+  // has loaded or with the first widget (its chains on our tiles listen then).
+  // Without one, `analytics: false`: our tiles queue nothing (core/tiles.ts).
+  if (!Object.keys(files.analytics ?? {}).length) g.analytics = false;
+  if (g.analytics !== false) {
+    const here = () => new URL(location.href);
+    const readQ = search ? searchReadQuery(search) : null;
+    const owns = (s: string) => {
+      if (s === 'autocomplete') return !!(ac && !ac.disabled && g.inputSelector);
+      if (s === 'search') return routes.some((r) => r.kind === 'search' && r.accepts(here()));
+      const reco = s.startsWith('recommender:') ? recoPages.get(s.slice(12)) : undefined;
+      return !!reco && !!setUp(`${s} active`, () => reco(here()));
+    };
+    const visit = (u: URL) => {
+      const r = routes.find((x) => x.accepts(u));
+      return !r ? null : r.kind === 'plp' ? `plp:${u.origin}${u.pathname}` : `search:${u.origin}${u.pathname}?${readQ?.(u) ?? ''}`;
+    };
+    let started = false;
+    /** Analytics listens (the setup has run). Until then, a page left keeps its dataLayer pushes for the next one's (core/kept.ts), up to `kept`. */
+    let live = false;
+    let kept = 0;
+    addEventListener('pagehide', () => {
+      if (!live && !(document as any).prerendering) kept = keepDl(g.dataLayer ?? 'dataLayer', kept);
+    });
+    startAnalytics = () => {
+      if (started) return;
+      started = true;
+      import('./analytics/start')
+        .then((m) => m.start({ config, files: files.analytics ?? {}, owns, visit, onUrlChange, kept: () => kept }))
+        .then(() => (live = true))
+        .catch((e) => reportError('analytics', e));
+    };
+    if (analyticsWanted) startAnalytics();
+    else afterLoad(() => startAnalytics());
+  }
+
   schedule();
 }

package/src/types.ts

@@ -94,6 +94,24 @@ export interface GlobalConfigType {
   /** Set in _init.ts: templates read them as r.c.<name>. Defaults: title, url, image, price. */
   computedAttributes?: Record<string, (r: Result) => unknown>;
   translations?: Translations;
+  /**
+   * `false`: no analytics at all, whatever `_analytics.ts` says (README
+   * "Analytics": what is sent is that file's).
+   */
+  analytics?: false;
+  /**
+   * The site's dataLayer, for analytics' `dl()` (default `dataLayer`): here,
+   * not in `_analytics.ts`, because the entry keeps its pushes for the next
+   * page when the visitor leaves before analytics has run.
+   */
+  dataLayer?: string;
+  /**
+   * Puts a product in the site's cart (`_init.ts`, or `_global/_widget.ts`:
+   * only widgets call it): what a click on `[data-lbx-cart]` in one of our
+   * tiles runs (announced to analytics first: `lumaCarts()`). `count`: the
+   * attribute's value (default 1).
+   */
+  addToCart?: (r: Result, o: { count: number; el: HTMLElement; event: MouseEvent }) => unknown;
 }
 
 /**
@@ -227,8 +245,17 @@ export interface AutocompleteConfigType extends AppConfig<AutocompleteConfigType
    * `'input'`: always the input. At least 360 px wide; on a phone (below
    * 480 px) a field spanning most of the screen exactly, else the screen's
    * width.
-   */
-  alignTo?: 'input' | string;
+   *
+   * An object sets the field and, for the house panel (`dom: 'shadow'`), the
+   * page's content column it stays within: `{ field?: 'input' | string;
+   * column?: 'viewport' | string }`. `column`: a selector (the field's
+   * nearest ancestor matching it, else the first element matching it), or
+   * `'viewport'` (the screen less 24 px each side). By default the panel
+   * stays within the field's outermost ancestor that is at least 1000 px
+   * wide and narrower than the screen (a centred page container), else the
+   * screen.
+   */
+  alignTo?: 'input' | string | { field?: 'input' | string; column?: 'viewport' | string };
   /** _init.ts hooks, for sites whose own code reacts to their dropdown opening, closing or a pick. */
   onOpen?: () => void;
   /** Why it closed: a pick, Enter / Escape in the input, focus leaving, a press outside, a route change, … */