@luigisbox/luma 0.2.0 → 0.4.0

package/README.md

@@ -10,9 +10,9 @@ This package is what an integration is built with. Each integration lives in
 its own repository and depends on `@luigisbox/luma`
 ([Integration repository](#integration-repository)).
 
-> **Pre-release.** Until 1.0, a minor version (0.3.0) may change the
+> **Pre-release.** Until 1.0, a minor version (0.5.0) may change the
 > integration API (config keys, template scope, the build); a patch version
-> (0.2.1) only fixes. Depend on `^0.2.0` to take fixes without breaking
+> (0.4.1) only fixes. Depend on `^0.4.0` to take fixes without breaking
 > changes.
 
 ## Core principles
@@ -331,6 +331,11 @@ export default ({ r, i, img, price }: SearchResultScope) => html`
   `_global.images` (srcset, sizes, the eager first row, placeholders).
 - **Pagination** is "show more" only: templates get `results`, `more` and
   `showMore`; there are no numbered pages.
+- **No results under filters**: the scope still holds the selected groups,
+  their `chips` and `clear`. A template that leaves the facets out when
+  `total` is 0 must keep them (or at least `clear`) while `chips.length` is
+  not 0: otherwise, where no drawer or chips show elsewhere, Back is the
+  shopper's only way to undo the filter.
 - **Translations** are JSON dictionaries per locale (`src/locales/<locale>.json`,
   `{name}` placeholders, plural forms by `Intl.PluralRules` category); only the
   site's locale is loaded. Override keys in `_translations.ts`, keyed by locale:
@@ -348,7 +353,7 @@ On by default unless noted; each falls back to what the page would do anyway.
 |---|---|---|
 | `search.inPlaceQuery` | a new query on the search page renders in place, without a page load | the host's page-view analytics or server-rendered parts of the search page must follow every query |
 | `search.prefetchWhileTyping` | the search result is fetched once the typed phrase settles, so Enter shows it at once | |
-| `restoreOnBack` | Back from a product restores the listing and the followed tile's position | |
+| `restoreOnBack` | Back from a product restores the listing (every page shown) and the followed tile's position, as does the page loaded again within a minute of following a link (a reload, a link whose server redirects back to it); Luma turns the browser's own scroll restoration (`history.scrollRestoration`) off for the listing's history entry until it has placed the page, unless the site set it | |
 | `prefetchNextPage` | "show more" is fetched as the shopper nears the end | |
 | `contentVisibility` (opt-in) | tiles out of view skip style, layout and paint, each at its own measured size: a long list's re-render about halves | keep it off where a tile draws outside its box (a hover panel, a badge hanging out) or holds a `position: fixed` element |
 | `_global.prefetchFilters` | a filter, sort or chip is fetched on hover, touch or focus | |
@@ -400,8 +405,8 @@ collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
 | Event | What `.read()` returns |
 |---|---|
 | `pageView` | the page's reference, or `null` for a page without one. On `lumaPages()`, one pageview per page, sent at once. On any other trigger, one per page that waits for its reference from that trigger (`.timeout(ms)`, default 1000 ms) and is sent without one after that. One `pageView` line per file |
-| `click` | a product click: a reference, or `{ reference }` |
-| `addToCart` | `{ reference, count?, price? }`, or a list of them |
+| `click` | a product click: a reference, or `{ reference, attributedToList? }` |
+| `addToCart` | `{ reference, count?, price?, attributedToList? }`, or a list of them |
 | `purchase` | `{ id?, currency?, items: [{ reference, title, count, total_price, was_discounted? }] }`; sent once per `id`, so a reloaded thank-you page does not count twice |
 | `search`, `autocomplete`, `recommender(name)` | a list from the site's own service: `{ query?, items, filters? }`. Not sent on a page where Luma runs that service itself (the API records Luma's own results) |
 
@@ -423,12 +428,26 @@ collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
 
 | Reader | Reads |
 |---|---|
-| `fromLuma.pageView`, `.click`, `.addToCart` | what Luma's own triggers saw (`lumaPages()`, `lumaClicks()`, `lumaCarts()`). Products are referenced by their catalog `@id` |
-| `fromGa4.addToCart`, `.purchase`, `.click`, `.pageView`, `.search`, `.autocomplete`, `.recommender` | GA4 ecommerce: `add_to_cart`, `purchase`, `select_item`, `view_item`, `view_item_list`. The data is taken from the push's `ecommerce` (or `gtag()`'s parameters), or from the push itself when its `items` are there. Items are referenced by `ref.product(item_id)`; purchases get line totals, and `was_discounted` from `discount` |
+| `fromLuma.pageView`, `.click`, `.addToCart` | what Luma's own triggers saw (`lumaPages()`, `lumaClicks()`, `lumaCarts()`). Products are referenced by their catalog `@id`. Clicks and add-to-carts are in a list (`attributedToList: true`) |
+| `fromGa4.addToCart`, `.purchase`, `.click`, `.pageView`, `.search`, `.autocomplete`, `.recommender` | GA4 ecommerce: `add_to_cart`, `purchase`, `select_item`, `view_item`, `view_item_list`. The data is taken from the push's `ecommerce` (or `gtag()`'s parameters), or from the push itself when its `items` are there. Items are referenced by `ref.product(item_id)`; purchases get line totals, and `was_discounted` from `discount`. `select_item` is a pick from a list (`attributedToList: true`); `add_to_cart` is not |
 
 Each reader belongs to one event: `collect.purchase…read(fromGa4.addToCart)`
 is a type error, and throws when the file runs.
 
+**Clicks and add-to-carts in a list.** Luigi's Box credits a click or an
+add-to-cart to the last search, suggestions, recommendation or listing the
+shopper saw the product in only when the event says it happened in a list:
+`attributedToList: true` from `.read()`, sent as `attributed_to_list: true`.
+A click without it (a bare reference) counts for the product, never for a
+list, so a click on a product page's own link is not credited to a search the
+shopper made earlier. Luma's own tiles always say it (`fromLuma.click`,
+`fromLuma.addToCart`, autocomplete picks included), and so does GA4's
+`select_item` (`fromGa4.click`). A click on the site's own list, read with a
+function of yours, says it when the element is one of that list's results:
+return `{ reference, attributedToList: true }` (below). The list itself must
+be known too: Luma's own results are; the site's own are when the setup
+collects them (`collect.search`, `.autocomplete`, `.recommender(name)`).
+
 **References** follow `<type>/<field>:<value>`
 ([docs](https://docs.luigisbox.ai/analytics/references/)).
 `ref.product(value)` uses the field set by `ref.product.by(field)` (default
@@ -468,8 +487,8 @@ collect.search.on(mutationOf('#results')).once().read(({ element }) => ({
   query: { string: new URLSearchParams(location.search).get('q') ?? '' },
   items: [...element.querySelectorAll('[data-sku]')].map((tile, n) => ({ title: tile.textContent ?? '', type: 'product', reference: ref.product(tile.getAttribute('data-sku')!), position: n + 1 })),
 }));
-// clicks on those results
-collect.click.on(domClick('#results [data-sku] a')).read(({ element }) => ref.product(element.closest('[data-sku]')!.getAttribute('data-sku')!));
+// clicks on those results: in that list
+collect.click.on(domClick('#results [data-sku] a')).read(({ element }) => ({ reference: ref.product(element.closest('[data-sku]')!.getAttribute('data-sku')!), attributedToList: true }));
 // the site's suggestions, from its own API
 collect.autocomplete.on(xhrMatching(({ url }) => url.includes('/suggest'))).read(({ response }) => ({ items: /* … */ [] }));
 // the product page's product, from GA4's view_item

package/docs/ACCESSIBILITY.md

@@ -106,8 +106,13 @@ guessed alt text, and forced colours and the OS setting are honoured.
   they are not results; the help box's phone link is a plain link. "Show all
   products" is a real link (`href`: the
   search page the site's form would submit to) and the open dropdown's one
-  tab stop: Tab from the input reaches it, Shift+Tab goes back, Escape closes
-  and goes back, Tab moves on to the page's next control after the input.
+  tab stop: Tab from the input reaches it (the options' selection cleared:
+  one thing lit), Shift+Tab goes back, Escape closes and goes back, Tab moves
+  on to the page's next control after the input. It is also the arrow keys'
+  last stop after the options (Arrow Up from the input reaches it first),
+  lit as when focused and referenced as the active descendant (it is in the
+  combobox's popup; in our shadow root, said by the status region instead),
+  Enter its search; focus stays in the input.
 - **Status messages**: "Suggestions: N" or "No results for “…”", in a polite
   `role="status"` region inside the dropdown, once typing pauses (700 ms), and
   only when it changes within an opening (not per keystroke).
@@ -123,7 +128,7 @@ guessed alt text, and forced colours and the OS setting are honoured.
   never a faint colour alone: an accent fill (pills), or the tint with an
   accent ring (cards) or edge (rows). Tokens an integration sets
   (`autocomplete.tokens`, its CSS) are its own to keep at 4.5:1 (`yarn luma a11y`).
-- **The phone sheet** (house design, viewport up to 600 px): its own input is
+- **The phone sheet** (house design, viewport up to 600 px, or a short touch screen: a phone in landscape): its own input is
   the combobox (`aria-controls` the listboxes on screen,
   `aria-activedescendant` the selected option: the same shadow root); the
   site's input is left as it was. The back button is named "Close search",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luigisbox/luma",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Luma: Luigi's Box frontend integrations (autocomplete, search, category listings, recommenders) on the Luigi's Box AI API. Pre-release.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/analytics/chain.ts

@@ -26,6 +26,14 @@ export interface AddToCart {
   reference: string;
   count?: number;
   price?: number;
+  /** Added in a list (a tile's cart button): the platform credits it to that list. */
+  attributedToList?: boolean;
+}
+/** One click: what `collect.click` sends (a bare reference: not in a list). */
+export interface Click {
+  reference: string;
+  /** Picked in a list (a search, suggestions, a recommender, a listing): the platform credits it to that list. */
+  attributedToList?: boolean;
 }
 /** A purchase: what `collect.purchase` sends, once per `id`. */
 export interface Purchase {
@@ -42,7 +50,7 @@ export interface List {
 /** What `.read()` returns, per event (null or undefined: nothing sent). */
 export interface Reads {
   pageView: string | null | undefined;
-  click: string | { reference: string };
+  click: string | Click;
   addToCart: AddToCart | AddToCart[];
   purchase: Purchase;
   search: List;

package/src/analytics/collect.ts

@@ -3,9 +3,13 @@
 // - pageView: `pv` per page (./pageview.ts);
 // - search, autocomplete, recommender(name): a `list` event of the site's own
 //   service (`{ query?, items, filters? }`; ours the API records itself);
-// - click: an `interaction` click (a reference, or `{ reference }`);
-// - addToCart: `interaction` add_to_cart per item (`{ reference, count?, price? }` or a list);
+// - click: an `interaction` click (a reference, or `{ reference, attributedToList? }`);
+// - addToCart: `interaction` add_to_cart per item (`{ reference, count?, price?, attributedToList? }` or a list);
 // - purchase: a `transaction` (`{ id?, currency?, items }`), once per id.
+// `attributedToList`: the product was picked in a list (a search, suggestions,
+// a recommender, a listing): sent as `attributed_to_list: true`, the only
+// interactions the platform credits to the last list in the session that
+// held the product. Without it the interaction counts for the product alone.
 
 import { emit } from './outbox';
 import { state } from './setup';
@@ -26,24 +30,27 @@ export const autocomplete = /* @__PURE__ */ surface<'autocomplete'>('autocomplet
 /** The site's own recommender `name` (silent where ours of that name runs): a `list` event. */
 export const recommender = (name: string) => surface<'recommender'>(`recommender:${name}`, list('Recommendation'));
 
-/** A product click: the reference (or `{ reference }`). */
+/** `attributed_to_list: true` where the product was picked in a list (only then: absent is false). */
+const inList = (x: { attributedToList?: boolean } | undefined) => (x?.attributedToList === true ? { attributed_to_list: true } : {});
+
+/** A product click: the reference (or `{ reference, attributedToList? }`). */
 export const click = /* @__PURE__ */ surface<'click'>('click', (p) => {
-  const reference = typeof p === 'string' ? p : p?.reference;
-  if (isRef(reference)) emit({ type: 'interaction', interaction_type: 'click', listing_ab_test: false, reference });
+  const o = typeof p === 'string' ? { reference: p } : p;
+  if (isRef(o?.reference)) emit({ type: 'interaction', interaction_type: 'click', listing_ab_test: false, reference: o.reference, ...inList(o) });
 });
 
 const currency = () => state.g?.currency;
 /** When the last add-to-cart on our tiles was: the site's own push its cart then makes is the same one. */
 let ourCart = 0;
 const OUR_CART_MS = 10_000;
-/** Add-to-cart: `{ reference, count?, price? }` or a list of them. */
+/** Add-to-cart: `{ reference, count?, price?, attributedToList? }` or a list of them. */
 export const addToCart = /* @__PURE__ */ surface<'addToCart'>('addToCart', (p) => {
   const all: (AddToCart & { [OURS]?: true })[] = Array.isArray(p) ? p : [p];
   if (all.some((x) => x?.[OURS])) ourCart = Date.now();
   else if (Date.now() - ourCart < OUR_CART_MS) return void (ourCart = 0);
   for (const x of all) {
     if (!isRef(x?.reference)) continue;
-    emit({ type: 'interaction', interaction_type: 'add_to_cart', listing_ab_test: false, reference: x.reference, ...(x.count ? { count: x.count } : {}), ...(x.price != null && x.price >= 0 ? { price: x.price } : {}), ...(currency() ? { currency: currency() } : {}) });
+    emit({ type: 'interaction', interaction_type: 'add_to_cart', listing_ab_test: false, reference: x.reference, ...(x.count ? { count: x.count } : {}), ...(x.price != null && x.price >= 0 ? { price: x.price } : {}), ...(currency() ? { currency: currency() } : {}), ...inList(x) });
   }
 });
 

package/src/analytics/from-ga4.ts

@@ -56,8 +56,11 @@ export const purchase = /* @__PURE__ */ reader('purchase', (ctx: Ctx) => {
   });
   return items.length ? { id: e.transaction_id, currency: e.currency, items } : null;
 });
-/** select_item: the product clicked. */
-export const click = /* @__PURE__ */ reader('click', first);
+/** select_item (GA4: an item picked from a list): the product clicked, in its list. */
+export const click = /* @__PURE__ */ reader('click', (ctx: Ctx) => {
+  const reference = first(ctx);
+  return reference ? { reference, attributedToList: true } : null;
+});
 /** view_item: the page's product. */
 export const pageView = /* @__PURE__ */ reader('pageView', first);
 /** view_item_list of their search: its items, the query from search_term. */

package/src/analytics/from-luma.ts

@@ -6,7 +6,9 @@
 //   collect.addToCart.on(lumaCarts()).read(fromLuma.addToCart);
 //
 // Our tiles' references are their results' `@id`s (every result has one),
-// whatever ref.product.by() says for the site's own data.
+// whatever ref.product.by() says for the site's own data. Every tile of ours
+// is in a list (a search, suggestions, a recommender, a listing): its clicks
+// and add-to-carts are attributed to it.
 
 import type { TileEvent } from '../core/tiles';
 import { reader } from './chain';
@@ -15,7 +17,7 @@ import type { Page } from './page';
 
 /** A page: no reference of its own. */
 export const pageView = /* @__PURE__ */ reader('pageView', (_: Page) => null);
-/** A click on one of our tiles: the product clicked. */
-export const click = /* @__PURE__ */ reader('click', (t: TileEvent) => t.reference);
+/** A click on one of our tiles: the product clicked, in its list. */
+export const click = /* @__PURE__ */ reader('click', (t: TileEvent) => ({ reference: t.reference, attributedToList: true }));
 /** `[data-lbx-cart]` on one of our tiles: the product, its quantity and price (the site's own push its cart then makes is the same one). */
-export const addToCart = /* @__PURE__ */ reader('addToCart', (t: TileEvent) => ({ reference: t.reference, count: t.count ?? 1, ...(t.price != null ? { price: t.price } : {}), [OURS]: true as const }));
+export const addToCart = /* @__PURE__ */ reader('addToCart', (t: TileEvent) => ({ reference: t.reference, count: t.count ?? 1, ...(t.price != null ? { price: t.price } : {}), attributedToList: true, [OURS]: true as const }));

package/src/analytics/index.ts

@@ -19,6 +19,6 @@ export { user } from './user';
 export { ref } from './ref';
 export { dl, domClick, lumaCarts, lumaClicks, lumaPages, manual, mutationOf, urlChange, xhrMatching } from './triggers';
 export type { DlContext, DomClickContext, ManualContext, MutationContext, UrlChangeContext, XhrContext } from './triggers';
-export type { AddToCart, List, Purchase, Read, Trigger } from './chain';
+export type { AddToCart, Click, List, Purchase, Read, Trigger } from './chain';
 export type { Page } from './page';
 export type { TileEvent } from '../core/tiles';

package/src/core/early-rules.ts

@@ -35,9 +35,22 @@ export interface EarlyRoute {
 const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 // reserveSelector: set by loadConfig (default: the first anchor).
 
-/** Only what the snippet can express: a path regex and a query param (no custom readQuery/active). */
-export const searchRule = (c: SearchConfigType, hostCss: string): EarlyRoute | null =>
-  c.urlMatch && c.queryParam && !c.readQuery && !c.active ? { id: 'search', path: c.urlMatch, need: [c.queryParam], css: holdCss(hostCss, c.reserveSelector!) } : null;
+/** Capture groups in a regex source (its alternation with the empty string always matches). */
+const groups = (re: string) => new RegExp(`${re}|`).exec('')!.length - 1;
+
+/**
+ * Only what the snippet can express (no custom readQuery/active): a path
+ * regex and a query param, or a path regex whose capture group 1 is the query
+ * (/search/<q>/). The snippet cannot check that capture (the bundle decodes
+ * and trims it), so it also holds a blank one (/search/+/); the bundle
+ * rejects that URL and drops the unclaimed hold at boot, as for plpRule's `active`.
+ */
+export const searchRule = (c: SearchConfigType, hostCss: string): EarlyRoute | null => {
+  if (!c.urlMatch || c.readQuery || c.active) return null;
+  const css = holdCss(hostCss, c.reserveSelector!);
+  if (c.queryParam) return { id: 'search', path: c.urlMatch, need: [c.queryParam], css };
+  return groups(c.urlMatch) ? { id: 'search', path: c.urlMatch, css } : null;
+};
 
 /**
  * Param names the category route can express (values are checked by the bundle).

package/src/core/entries.ts

@@ -16,10 +16,14 @@ export const isOwnEntry = (href: string) => own.has(canon(href));
 
 /**
  * A history entry of ours that only stands for something open (the
- * autocomplete's phone sheet): Back closes it, and no router of the host's
- * hears that popstate (the URL is the same). `back` returns true when the
- * popstate was that entry's (set by the widget that pushed it).
+ * autocomplete's phone sheet, the listing's staged filter drawer): Back
+ * closes it, and no router of the host's hears that popstate (the URL is the
+ * same). Each handler returns true when the popstate was its entry's (set by
+ * the widget that pushed it). Returns the removal.
  */
-let back: (() => boolean) | null = null;
-export const onOwnBack = (f: () => boolean) => void (back = f);
-export const ownBack = () => !!back?.();
+const backs = new Set<() => boolean>();
+export const onOwnBack = (f: () => boolean) => (backs.add(f), () => void backs.delete(f));
+export const ownBack = () => {
+  for (const f of backs) if (f()) return true;
+  return false;
+};

package/src/core/stash.ts

@@ -17,21 +17,41 @@ export const navigation = () => {
   }
 };
 
+/**
+ * A listing left for another page, loaded again within this long by a reload
+ * or a navigation from itself (a server round trip: a "compare" or "add to
+ * cart" link that redirects back to the page it came from): the listing as
+ * left, as for Back.
+ */
+export const ROUND_TRIP_MS = 60e3;
+
+/** The page loaded from itself: its referrer is this page (a redirect back keeps the referrer of the page that started it). */
+const fromItself = () => {
+  try {
+    return !!document.referrer && pageKey(document.referrer) === pageKey(location.href);
+  } catch {
+    return false;
+  }
+};
+
 /**
  * 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.
+ * listing left for a product by back/forward, or by a reload or a navigation
+ * from itself within ROUND_TRIP_MS of leaving (`at`: when it was written).
  */
-export const stashFits = (kind: string) => {
+export const stashFits = (kind: string, at = 0) => {
   const t = navigation().type;
-  return kind === 'back' ? t === 'back_forward' : t === 'navigate' || t === 'prerender';
+  if (kind !== 'back') return t === 'navigate' || t === 'prerender';
+  if (t === 'back_forward') return true;
+  return Date.now() - at < ROUND_TRIP_MS && (t === 'reload' || (t === 'navigate' && fromItself()));
 };
 
 /** 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');
+    return !!head && stashFits(head.includes('"kind":"back"') ? 'back' : 'spec', Number(/"at":(\d+)/.exec(head)?.[1]) || 0);
   } catch {
     return false;
   }

package/src/types.ts

@@ -245,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, … */