@luigisbox/luma 0.6.0 → 0.7.1

package/src/widgets/autocomplete/index.ts

@@ -18,7 +18,7 @@ import { borrow, liveRegion, useContrast } from '../../core/a11y';
 import { luminanceOf, readable } from '../../core/color';
 import { defaultSubmitter, formDataOf } from '../../core/default-button';
 import { onOwnBack } from '../../core/entries';
-import { AC_HOOKS, ANALYTICS, QUERY_URL } from '../../core/features';
+import { AC_HOOKS, ANALYTICS, LIGHT_FULL_SCREEN, QUERY_URL } from '../../core/features';
 import { mark, reportError } from '../../core/health';
 import { modalOf } from '../../core/own';
 import { byName, view } from '../../core/templates';
@@ -268,7 +268,8 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
   const toTop = () => {
     // Our scroll, not the finger's: a finger at rest on the list is no swipe, the same finger's drag
     // after it still is. Review (PR 26): a new result set's reset put the keyboard away.
-    if (swipe && scrolled.has(swipe.list)) swipe.ours = true;
+    // A light-DOM sheet's list is the host: whichever of its elements scrolls.
+    if (swipe && (LIGHT_FULL_SCREEN && light ? [...scrolled].some((el) => swipe!.list.contains(el)) : scrolled.has(swipe.list))) swipe.ours = true;
     for (const el of scrolled) if (el.isConnected) el.scrollTop = 0;
     scrolled.clear();
   };
@@ -303,8 +304,13 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     }
   };
 
-  /** The house design's phone sheet applies here (shadow DOM, a phone's viewport). */
-  const phone = () => !light && typeof matchMedia === 'function' && matchMedia(SHEET_MEDIA).matches;
+  /**
+   * Where the phone sheet applies (a media query): the house design's on a
+   * phone's viewport; a light-DOM integration's only with `fullScreen` (its own
+   * markup: `true` on a phone's viewport, or its own query), never without.
+   */
+  const sheetMedia = !light ? SHEET_MEDIA : !LIGHT_FULL_SCREEN ? 'not all' : ac.fullScreen === true ? SHEET_MEDIA : ac.fullScreen || 'not all';
+  const phone = () => typeof matchMedia === 'function' && matchMedia(sheetMedia).matches;
 
   /** Our shadow root on `el` with our CSS; the box templates render into. */
   const shadowBox = (el: HTMLElement, ...before: Node[]) => {
@@ -334,7 +340,9 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       // The UA popover's height: fit-content makes a fixed panel the site pins
       // with top + bottom (a full-height sheet on phones) grow past the screen
       // instead of scrolling. Zero specificity: any site rule still wins.
-      setCss('ac:light', ':where([data-lbx="ac-overlay"]) { height: auto; }');
+      // Its width and margin too: a phone sheet the site pins with `inset: 0`
+      // fills the screen, not fit-content and centred (the dropdown's width is inline).
+      setCss('ac:light', ':where([data-lbx="ac-overlay"]) { height: auto; width: auto; margin: 0; }');
       ctx.styles.forEach((c, i) => setCss(`itg:autocomplete:${i}`, c));
       box = host;
       host.append(live.el); // the templates render after it
@@ -412,8 +420,10 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
         if (!(el instanceof Element)) return;
         if (el.scrollTop > 0) scrolled.add(el);
         else scrolled.delete(el);
-        if (swipe?.list === el && swipe.ours) swipe.ours = false;
-        else if (swipe?.list === el && (!swipe.cancelled || performance.now() - swipe.cancelled < SWIPE_SCROLL_MS)) putKeyboardAway();
+        if (!swipe || !(LIGHT_FULL_SCREEN && light ? swipe.list.contains(el) : swipe.list === el)) return;
+        if (swipe.ours) swipe.ours = false;
+        // A light-DOM sheet's sideways band (its tabs) scrolls in it too: only a list that went down.
+        else if ((!LIGHT_FULL_SCREEN || !light || el.scrollTop > 0) && (!swipe.cancelled || performance.now() - swipe.cancelled < SWIPE_SCROLL_MS)) putKeyboardAway();
       },
       { capture: true, passive: true },
     );
@@ -424,11 +434,13 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     // pill band's sideways drag is not the list. Focus goes to the sheet
     // (tabindex -1), not <body>: Escape and Tab still work from a hardware
     // keyboard. Bug (iOS 26 Safari): with the keyboard up, its bar and the
-    // address bar above it, the sheet kept half the screen.
+    // address bar above it, the sheet kept half the screen. A light-DOM
+    // sheet: its list is the host (whichever of its elements scrolls), and
+    // focus goes to the host.
     const putKeyboardAway = () => {
       swipe = null;
       if (!mirror || focused() !== mirror) return;
-      const panel = mirror.closest<HTMLElement>('.sheet[tabindex]');
+      const panel = mirror.closest<HTMLElement>('.sheet[tabindex]') ?? (LIGHT_FULL_SCREEN && light ? host : null);
       if (panel) panel.focus({ preventScroll: true });
       else mirror.blur(); // an integration's own sheet template
     };
@@ -439,7 +451,8 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
         const e = ev as PointerEvent;
         swipe = null;
         if (!sheet || !finger(e)) return;
-        const list = e.composedPath().find((x) => x instanceof Element && x.matches('.sh-list, .sheet .empty')) as Element | undefined;
+        const path = e.composedPath();
+        const list = LIGHT_FULL_SCREEN && light ? (mirror && path.includes(mirror) ? undefined : host!) : (path.find((x) => x instanceof Element && x.matches('.sh-list, .sheet .empty')) as Element | undefined);
         if (list) swipe = { list, x: e.clientX, y: e.clientY, moved: false };
       },
       { capture: true, passive: true },
@@ -534,6 +547,8 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
    */
   /** What Safari's bars and the keyboard cover of the sheet (px, --lbx-cover), -1 while it is not open. */
   let cover = -1;
+  /** A light-DOM sheet's top (px, --lbx-top: the visual viewport's), -1 while it is not open. */
+  let sheetTop = -1;
   /** A clamp of the scrolled lists is queued (one for a keyboard going down, not one per frame of it). */
   let clamping = false;
   const position = (frame = false, m?: ReturnType<typeof measure>) => {
@@ -548,14 +563,19 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       // they and the keyboard cover (--lbx-cover) ends the list as space, so
       // its last row and "Show all" scroll clear of them. Bug (iOS 26/27):
       // the list stopped above the bars, a blank strip down to the keys.
+      // A light-DOM sheet is placed by the integration's CSS (`position:
+      // fixed; inset: 0; top: var(--lbx-top)`): only that top and what is
+      // covered (--lbx-cover) are ours.
       const vv = window.visualViewport;
       const top = Math.round(vv?.offsetTop ?? 0);
       const h = Math.round(vv?.height ?? innerHeight);
       const full = Math.max(h, innerHeight - top);
-      s.top = `${top}px`;
-      s.left = `${Math.round(vv?.offsetLeft ?? 0)}px`;
-      s.width = `${Math.round(vv?.width ?? innerWidth)}px`;
-      s.height = `${full}px`;
+      if (!LIGHT_FULL_SCREEN || !light) {
+        s.top = `${top}px`;
+        s.left = `${Math.round(vv?.offsetLeft ?? 0)}px`;
+        s.width = `${Math.round(vv?.width ?? innerWidth)}px`;
+        s.height = `${full}px`;
+      } else if (top !== sheetTop) s.setProperty('--lbx-top', `${(sheetTop = top)}px`);
       if (full - h !== cover) {
         // Less covered (the keyboard going down): the end space shrinks, and iOS WebKit kept a list
         // scrolled into it there, its rows stuck above a blank strip, not scrollable back (iOS 27
@@ -630,6 +650,8 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     aria?.restore();
     aria = null;
   };
+  /** Option `i`'s element, in the root the options render into. */
+  const rowOf = (i: number) => (box.getRootNode() as Document | ShadowRoot).getElementById(idOf(i));
   /**
    * The selected row (the screen reader's focus stays on the input). An id
    * reference resolves only in the input's own tree, never across a shadow
@@ -648,7 +670,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
   const markActive = (say = true) => {
     const all = active === ALL ? allLink() : null;
     if (all && !all.id) all.id = idOf(ALL);
-    const row = all ?? (active >= 0 ? (box.getRootNode() as Document | ShadowRoot).getElementById(idOf(active)) : null);
+    const row = all ?? (active >= 0 ? rowOf(active) : null);
     if (sheet && mirror) {
       if (row) mirror.setAttribute('aria-activedescendant', row.id);
       else mirror.removeAttribute('aria-activedescendant');
@@ -811,7 +833,8 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
   const idle = (f: () => void) => afterFrame(() => (typeof requestIdleCallback === 'function' ? requestIdleCallback(f, { timeout: 300 }) : setTimeout(f, 0)));
 
   /**
-   * The phone sheet (house design): full screen over the page,
+   * The phone sheet (the house design's, a light-DOM integration's with
+   * `fullScreen`: its markup, placed by its CSS): full screen over the page,
    * opened when the site's input gets focus. Its own input takes the focus
    * at once (in the tap's task: iOS shows its keyboard only for a focus in
    * the gesture) with what the site's input holds; it is the combobox there.
@@ -826,9 +849,20 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       tab = '';
       before = i.value;
       place();
-      sampleTokens(i, i);
-      // Below the visible part, its background (position).
-      host!.style.background = 'var(--lbx-c-bg, var(--lbx-bg))';
+      if (LIGHT_FULL_SCREEN && light) {
+        // The dropdown's inline box (inset: auto, its top, left and width) would beat the integration's CSS.
+        // Focusable: a swipe's keyboard put away leaves the focus here (putKeyboardAway), named as the house sheet's panel.
+        host!.style.inset = host!.style.width = '';
+        host!.tabIndex = -1;
+        host!.setAttribute('role', 'group');
+        host!.setAttribute('aria-label', labelOf(i));
+        // What its CSS keys on (`[data-lbx-full-screen]`): where the sheet opens is Luma's media query, a phone in landscape too.
+        host!.setAttribute('data-lbx-full-screen', '');
+      } else {
+        sampleTokens(i, i);
+        // Below the visible part, its background (position).
+        host!.style.background = 'var(--lbx-c-bg, var(--lbx-bg))';
+      }
       // What the site's input holds now, not what the sheet's held when it last
       // closed (letters typed into the site's input before the hand-off, a
       // value the site's page set since).
@@ -845,7 +879,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       cancelAnimationFrame(raf);
       position();
       render(); // with what the site's input holds
-      mirror = (box as ShadowRoot | HTMLElement).querySelector<HTMLInputElement>('[data-lbx-sheet-input]');
+      mirror = box.querySelector<HTMLInputElement>('[data-lbx-full-screen-input]');
     }
     if (mirror) {
       mirror.focus();
@@ -890,6 +924,8 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       then?.();
       return;
     }
+    // Our Back already on its way (a second focus outside, Escape twice): one Back. Review: two left the page in Chromium.
+    if (afterBack) return;
     const done = then ?? (() => {});
     afterBack = done;
     pendingReason = reason;
@@ -928,7 +964,12 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       entry = false; // left in history (the same URL) unless Back took it
       setCss('ac:sheet', null);
       host!.style.height = '';
-      host!.style.background = 'transparent';
+      if (LIGHT_FULL_SCREEN && light) {
+        host!.style.inset = 'auto'; // the dropdown's again (position sets its top and left)
+        host!.style.removeProperty('--lbx-top');
+        sheetTop = -1;
+        for (const a of ['role', 'aria-label', 'data-lbx-full-screen']) host!.removeAttribute(a);
+      } else host!.style.background = 'transparent';
       host!.style.removeProperty('--lbx-cover');
       cover = -1;
       host!.removeAttribute('data-lbx-short');
@@ -946,6 +987,8 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     if (AC_HOOKS) hook('onClose', ac.onClose, reason);
   };
 
+  /** The site's input's name: the sheet's input's (and a light-DOM sheet's own, its panel's). */
+  const labelOf = (i: HTMLInputElement | null) => i?.getAttribute('aria-label') || i?.placeholder || t('label');
   /** The sheet input's value the last render drew (its clear button). */
   let drawnValue = '';
   /** Rows as templates get them: the result and its index in `items`. */
@@ -972,7 +1015,8 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
     // The arrow keys' order: pills, the lists in config order, the
     // top product, the products in reading order; in the sheet, the pills and
     // the open tab's options; with no results, phrases to try, links, picks.
-    // A light-DOM integration's own markup keeps the config order.
+    // A light-DOM integration's own markup keeps the config order (its sheet:
+    // of the options its markup shows, read at the key: step).
     const phrases = byType('query');
     order = light
       ? rows.map((x) => x.i)
@@ -1000,7 +1044,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
       submitAll: () => submitAll(),
       allHref: searchHref(input, sheet ? (mirror?.value ?? '') : undefined),
       state,
-      sheet,
+      fullScreen: sheet,
       wide,
       phrases,
       lists,
@@ -1030,7 +1074,7 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
           .slice(0, 4),
       value,
       placeholder: input?.placeholder ?? '',
-      inputLabel: input?.getAttribute('aria-label') || input?.placeholder || t('label'),
+      inputLabel: labelOf(input),
       clear: () => {
         if (!mirror) return;
         mirror.value = '';
@@ -1419,7 +1463,11 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
    * other way round.
    */
   const step = (by: 1 | -1) => {
-    const stops = !sheet && allLink() ? [...order, ALL] : order;
+    let stops = !sheet && allLink() ? [...order, ALL] : order;
+    // A light-DOM sheet: the options its markup shows (the open tab's, drawn alone or the others hidden by
+    // its CSS; all of them without tabs), read in response to the key. Review: a template without tabs had
+    // its other types' options out of the arrows' reach (the house sheet's open-tab order).
+    if (LIGHT_FULL_SCREEN && light && sheet) stops = stops.filter((i) => rowOf(i)?.getClientRects().length);
     const n = stops.length + 1; // positions: -1 (back in input) .. stops.length-1
     const at = stops.indexOf(active);
     const next = ((at + by + 1 + n) % n) - 1;
@@ -1539,6 +1587,11 @@ export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
   };
 
   const onFocusIn = once<'focusin'>((_, target) => {
+    // Focus gone from the open sheet to the page it covers (Tab past its last
+    // control, Shift+Tab from its first, iOS's next-field arrow): closed, the
+    // focus seen. Review: Tab left it on a hidden control, Escape not heard.
+    // Not the site's input (the tap's hand-off), nor <body> (the keyboard put away).
+    if (sheet && open && target instanceof Element && target !== input && !inOverlay(target)) return leave('blur');
     if (!matches(target) || quietFocus) return;
     engage(target);
   });

package/src/widgets/autocomplete/template-autocomplete-box.ts

@@ -27,7 +27,7 @@ export const showAll = (s: AutocompleteScope) =>
     : html`<button type="button" class="all" data-lbx-part="ac-all" data-lbx-all @click=${() => s.submitAll()}>${s.t('showAllProducts')}${ARROW}</button>`;
 
 export default (s: AutocompleteScope) => {
-  if (s.sheet) return s.include('autocomplete-sheet');
+  if (s.fullScreen) return s.include('autocomplete-sheet');
   const opt = (row: { r: any; i: number }, as: string) => s.include('autocomplete-result-default', { r: row.r, i: row.i, as });
   const key = (row: { r: any; i: number }) => `${row.i}:${row.r.id}`;
   const list = s.phrases.length > 0 || s.lists.length > 0;

package/src/widgets/autocomplete/template-autocomplete-empty.ts

@@ -16,7 +16,7 @@ export default (s: AutocompleteScope) => {
   const opt = (row: { r: any; i: number }, as: string) => s.include('autocomplete-result-default', { r: row.r, i: row.i, as });
   const helpBox = help
     ? html`<div class="help">
-        ${s.sheet
+        ${s.fullScreen
           ? html`<span class="help-text"><span class="help-title">${help.title}</span>${help.hours ? html`<span class="help-hours">${help.hours}</span>` : nothing}</span>
               <a class="call" href=${`tel:${help.tel}`}><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="6" y="2" width="12" height="20" rx="2.5"></rect><path d="M11 18h2"></path></svg>${s.t('call')}<span class="sr"> ${help.phone}</span></a>`
           : html`<span class="phone-ico" aria-hidden="true"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"><rect x="6" y="2" width="12" height="20" rx="2.5"></rect><path d="M11 18h2"></path></svg></span>
@@ -43,9 +43,9 @@ export default (s: AutocompleteScope) => {
       </div>
       ${fallback.length
         ? html`<div class="strip">
-            <div class="strip-head"><span class="note-wrap"><span class="f-title" id="lbx-ac-g-fallback">${s.t('fallbackTitle')}</span><span class="f-note" id="lbx-ac-g-fallback-note">${s.t('fallbackNote')}</span></span>${s.sheet ? nothing : POWERED(s.t)}</div>
+            <div class="strip-head"><span class="note-wrap"><span class="f-title" id="lbx-ac-g-fallback">${s.t('fallbackTitle')}</span><span class="f-note" id="lbx-ac-g-fallback-note">${s.t('fallbackNote')}</span></span>${s.fullScreen ? nothing : POWERED(s.t)}</div>
             <div class="fb" role="listbox" id="lbx-ac-fallback" aria-labelledby="lbx-ac-g-fallback lbx-ac-g-fallback-note">${fallback.map((x) => opt(x, 'compact'))}</div>
-            ${s.sheet ? POWERED(s.t) : nothing}
+            ${s.fullScreen ? POWERED(s.t) : nothing}
           </div>`
         : html`<div class="e-foot">${POWERED(s.t)}</div>`}
     </div>

package/src/widgets/autocomplete/template-autocomplete-sheet.ts

@@ -38,7 +38,7 @@ export default (s: AutocompleteScope) => {
         <button type="button" class="icon back" aria-label=${s.t('closeSearch')} @click=${() => s.back()}>
           <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M19 12H5M11 6l-6 6 6 6"></path></svg>
         </button>
-        <input class="sh-input" data-lbx-sheet-input type="text" enterkeyhint="search" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false"
+        <input class="sh-input" data-lbx-full-screen-input type="text" enterkeyhint="search" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false"
           role="combobox" aria-autocomplete="list" aria-expanded=${controls ? 'true' : 'false'} aria-controls=${controls || nothing}
           aria-label=${s.inputLabel} placeholder=${s.placeholder} .value=${s.value} />
         ${s.value

package/src/widgets/listing/element.ts

@@ -15,7 +15,7 @@
 
 import { borrow, liveRegion, useContrast } from '../../core/a11y';
 import { activateByKey, byKeyboard, focusables, trapTab } from '../../core/a11y-keys';
-import { CONTENT_VISIBILITY, DRAWER, DROPDOWN, MENU, NAMED_FADE, NAMED_PRECONNECT_IMAGES, NAMED_PREFETCH_FILTERS, NAMED_PREFETCH_NEXT_PAGE, NAMED_PRELOAD, NAMED_RESTORE_ON_BACK, ON_RENDER, SEARCH, SSR } from '../../core/features';
+import { CONTENT_VISIBILITY, DRAWER, DROPDOWN, MENU, NAMED_FADE, NAMED_PRECONNECT_IMAGES, NAMED_PREFETCH_FILTERS, NAMED_PREFETCH_NEXT_PAGE, NAMED_PRELOAD, NAMED_RESTORE_ON_BACK, ON_RENDER, SEARCH, SSR, VARIANTS } from '../../core/features';
 import { mark, reportError } from '../../core/health';
 import { claim } from '../../core/reconciler';
 import { afterLayout, rememberHeight } from '../../core/hold';
@@ -38,11 +38,12 @@ import { specKey } from '../../core/stash';
 import { firstRequest, hasMore, listingMore, listingQuery, type ListingConfig, type ListingResult } from './query';
 import { flowKey, notAbove, onQuickLanded, quickChannel } from './flow';
 import { firstPages, SETTLE_MS, targetOf, thrifty, watchIntent } from './intent';
-import type { Page } from '../../api';
-import { atWidth, CV_CSS, DIM_MS, LOADING_CSS, listingData, ssrStateId, viewport, type ListingView, type SsrState } from './view';
+import type { Page, VariantGroup } from '../../api';
+import { atWidth, CV_CSS, DIM_MS, LOADING_CSS, listingData, ssrStateId, withGroups, viewport, type ListingView, type SsrState } from './view';
 import { dropStash, peekStash, readStash, removeStash, writeStash, type Stash } from './stash';
 import { adoptScroll, holdScroll, keepViewport, leavingLink, nearEnd, preconnectImages, releaseScroll, restoreScroll, scrollSpot } from './instant';
 import { watch } from '../../core/tiles';
+import { askVariants, groupsOf, seedGroups, stashGroups } from './variants';
 
 /** A re-render answered within DIM_MS (no dim shown) fades its list in from this opacity, over FADE_MS. */
 const FADE_FROM = 0.6;
@@ -108,7 +109,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
   useContrast();
   const query = (q: Query, signal?: AbortSignal, pre?: Page, onProducts?: (r: ListingResult) => void) => {
     const t0 = performance.now();
-    const p = listingQuery(ctx.api, ctx.global, cfg, route, q, signal, pre, onProducts, SEARCH ? quickChannel(route.id) : undefined);
+    // `variants`: the first page's groups asked for as soon as it is here, with its facets' request.
+    const p = listingQuery(ctx.api, ctx.global, cfg, route, q, signal, pre, onProducts, SEARCH ? quickChannel(route.id) : undefined, VARIANTS && cfg.variants ? (f) => void askVariants(ctx.api, cfg, f, signal) : undefined);
     // A whole listing (not a first page fetched already): how long a fresh one takes here.
     if (!pre) p.then((r) => !r.partial && observe(performance.now() - t0), () => {});
     return p;
@@ -233,6 +235,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     else if (stashed) {
       seeded.set(pageKey(location.href), stashed.query);
       cache.set(keyOf(stashed.query), stashed.result);
+      // `variants`: the groups it was left with, drawn with it (nothing asked).
+      if (VARIANTS) seedGroups(stashed.result, stashed.groups);
       mark(`${route.id} from stash (${stashed.kind}, ${stashed.result.hits.length} hits)`);
       // A prerendered page reads (and drops) it in a copy of sessionStorage; at
       // its activation the opener's storage, still holding it, comes back: used once.
@@ -399,7 +403,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     private hiddenAt = 0;
     /** scrollY when a Back stash was last written (leave()): the page hidden from there is stashed already. */
     private leftAt = -1;
-    private onPageHide = () => {
+    private onPageHide = (e: PageTransitionEvent) => {
       this.hiddenAt = Date.now();
       // Left with more than the first page shown, not by a link of ours (a
       // reload, their menu, the address bar): stashed too, so a reload within
@@ -408,6 +412,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       // shorter than where the shopper was). Into the back/forward cache
       // too: it may be evicted there (then Back is a page load).
       if (restoreOn && (this.last?.page ?? 0) > 1 && this.leftAt !== Math.round(scrollY)) this.leave();
+      // Into the back/forward cache: the browser's restoration on again (instant.ts `holdScroll`).
+      if (e.persisted) releaseScroll();
     };
     /**
      * Restored from the back/forward cache (pageshow, persisted): the page is as
@@ -420,14 +426,13 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      */
     private onPageShow = (e: PageTransitionEvent) => {
       if (!e.persisted) return;
-      // Where the shopper was: the browser's own restoration is off for the
-      // entry (holdScroll), and iOS Safari reads scrollY 0 at this event
-      // even when it restores it. Placed again, then the browser's back on.
+      // Where the shopper was: iOS Safari reads scrollY 0 at this event even
+      // when it restores it. Placed again (the browser's restoration is on
+      // again since pagehide, a host's own setting kept).
       const st = peekStash(location.href);
       dropStash(location.href);
       mark(`${route.id} restored from the back/forward cache`);
-      if (st?.kind === 'back' && st.scroll && tk.state === 'ours') restoreScroll(this, st.scroll, releaseScroll);
-      else releaseScroll();
+      if (st?.kind === 'back' && st.scroll && tk.state === 'ours') restoreScroll(this, st.scroll);
       const away = this.hiddenAt ? Date.now() - this.hiddenAt : 0;
       if (away > BFCACHE_STALE_MS && this.last && this.lastQ && this.lastQ === this.current) this.revalidate(this.lastQ, this.last, new URL(location.href), this.href);
     };
@@ -1187,7 +1192,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       this.leftAt = Math.round(scrollY);
       // The browser's own restoration off for this entry: Luma places the page after its render (holdScroll).
       const sr = holdScroll();
-      if (writeStash(location.href, { kind: 'back', route: route.id, query: this.lastQ, result: { ...this.last, quickPending: undefined }, scroll: scrollSpot(this, a), sr })) mark(`${route.id} stashed for back`);
+      if (writeStash(location.href, { kind: 'back', route: route.id, query: this.lastQ, result: { ...this.last, quickPending: undefined }, scroll: scrollSpot(this, a), sr, groups: VARIANTS && cfg.variants ? stashGroups(this.last) : undefined })) mark(`${route.id} stashed for back`);
       else releaseScroll();
     }
 
@@ -1414,6 +1419,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       if (res !== this.last || q !== this.lastQ || !hasMore(res) || nextOf.has(res)) return;
       mark(`${route.id} prefetch page ${res.page + 1}`);
       more(q, res).catch(() => {}); // a failed one: the click asks again
+      // `variants`: its products' groups too (more() asks once), so "show more" draws them with its tiles.
+      if (VARIANTS && cfg.variants) more(q, res).then((r) => askVariants(ctx.api, cfg, r, this.ctrl?.signal), () => {});
     }
 
     private render(q: Query, res: ListingResult, url: URL) {
@@ -1579,7 +1586,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       const self = this;
       return {
         ...ctx.helpers,
-        ...listingData(ctx, route, url, q, res, this.message, this.view()),
+        ...listingData(ctx, route, url, q, res, this.message, VARIANTS && cfg.variants ? { ...this.view(), variants: (this.groups$?.res === res ? this.groups$ : (this.groups$ = { res, map: groupsOf(res) })).map } : this.view()),
         facetsOpen: matchMedia('(min-width: 768px)').matches,
         // actions
         go: (link: Link | null) => (e: Event) => {
@@ -1628,6 +1635,9 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     }
 
     private draw(q: Query, res: ListingResult, url: URL) {
+      // `variants`: the groups of these products, asked for now (those not
+      // asked yet), never waited for: finish() draws them when they land.
+      if (VARIANTS && cfg.variants) askVariants(ctx.api, cfg, res, this.ctrl?.signal);
       // A first render in steps of these same products (shown before their
       // facets): it goes on with the facets, not a render of them all at once.
       if (this.stepping?.hits === res.hits) return this.stepping.take(q, res, url);
@@ -1961,6 +1971,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     }
     /** Tiles in the viewport (an IntersectionObserver), whether the list's last one is above it, the grid's columns (read with layout clean). */
     private seen = new Set<Element>();
+    /** `variants`: the groups the last scope of a result was built with (its map grows in steps as they land: finish()). */
+    declare private groups$: { res: ListingResult; map?: ReadonlyMap<string, VariantGroup> } | undefined;
     private past = false;
     private cols = 1;
     private io: IntersectionObserver | null = null;
@@ -1992,6 +2004,52 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       this.drawn$ = { hits: res.hits, n: res.hits.length };
       this.lastQ = q;
       this.afterA11y();
+      // `variants`: drawn again once the groups of these products asked for
+      // have landed (now: during a render in steps), if they are still shown
+      // (a later render of other products draws its own).
+      if (VARIANTS && cfg.variants)
+        askVariants(ctx.api, cfg, res, this.ctrl?.signal).then(() => {
+          const got = groupsOf(res);
+          const had = this.groups$?.map;
+          if (!got || had === got) return;
+          // In steps, as a shown listing's re-render (each tile whose group
+          // landed runs its template again): the tiles in view first, then
+          // as many a frame as BUDGET holds by what one cost.
+          const tiles = this.querySelector('[data-lbx-list]')?.children;
+          const ids = res.hits.map((h, i) => [tiles && this.seen.has(tiles[i]) ? 0 : 1, h['@id']] as const).filter(([, id]) => got.has(id) && had?.get(id) !== got.get(id)).sort((a, b) => a[0] - b[0]).map(([, id]) => id);
+          const N = res.hits.length;
+          let n = 0;
+          let per = this.tileMs || 3;
+          let frames = 0;
+          const step = () => {
+            if (this.last !== res || this.drawn$?.hits !== res.hits || this.groups$?.res !== res || !this.drawn) return;
+            // STEP tiles first, to measure one (a tile drawn anew with its group
+            // costs what a new tile does: the tiles' cost learnt from a render
+            // in steps was 0.3 ms for 2 ms tiles, one step of all of them); then
+            // as a re-render in steps: as many as BUDGET holds with the tiles
+            // there run again, not even one, a third of the rest.
+            const room = Math.floor((BUDGET - RERUN * per * N) / per);
+            const k = Math.min(ids.length - n, !frames ? STEP : room >= 1 ? room : Math.ceil((ids.length - n) / 3));
+            const map = n + k >= ids.length ? got : new Map([...(this.groups$.map ?? []), ...ids.slice(n, n + k).map((id) => [id, got.get(id)!] as const)]);
+            n += k;
+            this.groups$ = { res, map };
+            // A tile's template may draw other markup with its group: focus in one replaced goes to the region, not the page's start.
+            const at = document.activeElement;
+            this.focusWas = at && at !== this && this.contains(at) ? at : null;
+            const t0 = performance.now();
+            // Only the results change: the scope is not built again (as setUi). A
+            // template throwing on the groups hands the page back, as a render does, and no step follows.
+            this.guarded(() => {
+              this.renderOrRebuild((this.drawn = { ...this.drawn!, results: res.hits.map(withGroups(ctx.result, map)) }));
+              this.afterA11y();
+              per = Math.max(0.5, (performance.now() - t0) / (k + RERUN * (N - k)));
+              frames++;
+              if (n < ids.length) afterFrame(step);
+              else mark(`${route.id} variants in ${frames} frames`);
+            });
+          };
+          step();
+        });
       const info = { route: route.id, query: q.title, total: res.total, shown: res.hits.length, page: res.page, url };
       // A prerendered page (a search typed on the page before) is not seen
       // yet: the hook (titles, and often the site's analytics) runs when it

package/src/widgets/listing/instant.ts

@@ -106,8 +106,10 @@ export const restoreScroll = (root: Element, s: Spot, after?: () => void) => {
  * after its render. The browser's restoration ran before it, on a page not
  * grown to the stashed pages yet, and could land after Luma's place too.
  * Only from `auto`: a host that set it (Turbo, a router) keeps its own.
- * Back on (`releaseScroll`) once Luma has placed the page, or when the
- * document moves on within itself (an SPA's navigation: theirs to restore).
+ * Back on (`releaseScroll`) once Luma has placed the page, when the
+ * document moves on within itself (an SPA's navigation: theirs to restore),
+ * or as the page goes into the back/forward cache (restored from memory:
+ * iOS Safari's swipe Back shows the page behind only with it on).
  */
 let ownScroll = false;
 /** Off for this entry, when it is the browser's (or already ours): 1, for the stash's `sr`. */
@@ -121,8 +123,16 @@ export const holdScroll = (): 1 | undefined => {
     return undefined;
   }
 };
-/** A page loaded on an entry Luma turned it off for (the stash's `sr`): Luma's to turn back on. */
-export const adoptScroll = () => void (ownScroll = true);
+/**
+ * A page loaded on an entry Luma turned it off for (the stash's `sr`): Luma's
+ * to turn back on. Off again where it was turned on as the page went into
+ * the back/forward cache (the page evicted from it since): the browser's
+ * restoration stops here, Luma places the page.
+ */
+export const adoptScroll = () => {
+  ownScroll = true;
+  holdScroll();
+};
 /** Back to the browser's, if Luma turned it off. */
 export const releaseScroll = () => {
   if (!ownScroll) return;

package/src/widgets/listing/query.ts

@@ -10,7 +10,7 @@ import { facetFields, type Query, type Route } from './state';
 import { lru } from '../../core/storage';
 import { reportError } from '../../core/health';
 import { MAX_PAGE } from '../../core/routes';
-import { EMPTY_VALUES } from '../../core/features';
+import { EMPTY_VALUES, VARIANTS } from '../../core/features';
 
 const num = (s: string | undefined) => (s === undefined || s === '' ? null : Number(s));
 /** A range filter value `min|max` (either end may be empty). */
@@ -156,9 +156,11 @@ export const firstRequest = (g: GlobalConfigType, cfg: ListingConfig, route: Rou
  * need their result set's guid and so a request after them. `onQuick`: the
  * quick types never wait for (where they do not sit above the products):
  * the result comes without them if they are not here yet (`quickPending`),
- * and they land in it later, `onQuick` called with it then.
+ * and they land in it later, `onQuick` called with it then. `onFirst`: the
+ * first page as soon as it is here, with the facets' request (`variants`:
+ * its products' groups are asked for then, not after the facets).
  */
-export const listingQuery = async (api: Api, g: GlobalConfigType, cfg: ListingConfig, route: Route, q: Query, signal?: AbortSignal, pre?: Page, onProducts?: (r: ListingResult) => void, onQuick?: (r: ListingResult) => void): Promise<ListingResult> => {
+export const listingQuery = async (api: Api, g: GlobalConfigType, cfg: ListingConfig, route: Route, q: Query, signal?: AbortSignal, pre?: Page, onProducts?: (r: ListingResult) => void, onQuick?: (r: ListingResult) => void, onFirst?: (p: Page) => void): Promise<ListingResult> => {
   // A range selection over a field that may not be a numeric one (a page's
   // own facet, e.g. a parameter holding its numbers as text): if the API facets
   // it as terms, the range is the values within it, from the values of the
@@ -259,6 +261,8 @@ export const listingQuery = async (api: Api, g: GlobalConfigType, cfg: ListingCo
       : {};
   // Optional too: without them no value shows as empty.
   const all = EMPTY_VALUES && cfg.emptyValues && narrowed ? allOf().catch(() => undefined) : undefined;
+  // Extras after what the listing waits for (its facets' requests are out).
+  if (VARIANTS) onFirst?.(first);
   // The products now, the facets when they come: a request (theirs needs
   // this result set's guid) the shopper would otherwise wait for.
   const early: ListingResult | null =

package/src/widgets/listing/stash.ts

@@ -20,6 +20,7 @@
 
 import { navigation, specKey, STASH, stashFits, stashKey } from '../../core/stash';
 import { pageKey } from '../../core/page';
+import { VARIANTS } from '../../core/features';
 import type { ListingResult } from './query';
 import { queryKey, type Query } from './state';
 import type { Spot } from './instant';
@@ -39,6 +40,8 @@ export interface Stash {
   scroll?: Spot;
   /** back: Luma turned the browser's own scroll restoration off for the entry left (`history.scrollRestoration`): back on once restored. */
   sr?: 1;
+  /** back, `variants`: the groups of the products shown (./variants.ts), drawn with them. Storage: checked when read. */
+  groups?: unknown;
   /** Read only: too old to render from, where the shopper was is all that is used. */
   stale?: true;
 }
@@ -114,9 +117,15 @@ export const removeStash = (key: string) => {
 };
 
 /** Under the page's URL (`back`) or the query (`spec`). false: too big, or storage refused it. */
-export const writeStash = (href: string, s: Omit<Stash, 'v' | 'at'>) => {
+export const writeStash = (href: string, s: Omit<Stash, 'v' | 'at'>) =>
+  // Too big with the products' variant groups (extras): stashed without them rather than not at all.
+  put(href, s) || (VARIANTS ? !!s.groups && put(href, { ...s, groups: undefined }) : false);
+
+const put = (href: string, s: Omit<Stash, 'v' | 'at'>) => {
   try {
-    const json = JSON.stringify({ at: Date.now(), v: 1, kind: s.kind, ttl: s.ttl, route: s.route, query: s.query, result: s.result, scroll: s.scroll, sr: s.sr });
+    // `at` and `kind` first: pruning reads them without parsing the rest.
+    const { kind, ...rest } = s;
+    const json = JSON.stringify({ at: Date.now(), v: 1, kind, ...rest });
     if (json.length > MAX_CHARS) return false;
     const key = s.kind === 'spec' ? specKey(s.route, s.query.q ?? '') : stashKey(href);
     const others = entries(key);