@luigisbox/luma 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -5,6 +5,46 @@ before 1.0, a minor version may break the integration API.
 
 ## Unreleased
 
+## 0.7.1 — 2026-11-02
+
+### Fixed
+
+- iOS Safari: swiping Back from a product to a listing showed a blank page
+  for a moment; the swipe now shows the listing.
+
+## 0.7.0 — 2026-10-29
+
+### Added
+
+- `variants: { fields }` on a listing (search, plp; plp inherits it): each
+  result gets its variant group as `r.variants` (`siblings`, `total`) from
+  Luigi's Box. One request per page of results, never waited for: the
+  tiles are drawn again when it arrives. Off by default, built only where
+  a folder's `_config.ts` sets it.
+- Light-DOM autocomplete full screen on a phone: `autocomplete.fullScreen`
+  (`true`, or a media query such as `'(max-width: 767px)'`). A tap on the
+  site's input opens it over the whole screen, with the integration's own
+  markup and CSS. Its template renders its own input, marked
+  `data-lbx-full-screen-input`, and gets `fullScreen`, `state`, `tabs`,
+  `value`, `back()` and `clear()`. Its CSS places it, keyed on
+  `[data-lbx-full-screen]`, with `--lbx-top` and `--lbx-cover` from Luma.
+  Off by default.
+
+### Changed
+
+- The listing reads the result set's key from `request_key` (`guid` is its
+  deprecated name).
+- Autocomplete templates: `sheet` is now `fullScreen`, and the full-screen
+  input's marker `data-lbx-sheet-input` (in an `autocomplete-sheet`
+  override) is now `data-lbx-full-screen-input`. Rename both in templates
+  copied from 0.6.0.
+
+### Fixed
+
+- Full-screen autocomplete on a phone: focus leaving it for the page behind
+  (Tab past its last control, iOS's next-field arrow) closes it. Focus was
+  left on a control it hid.
+
 ## 0.6.0 — 2026-10-20
 
 ### Changed

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.7.0) may change the
+> **Pre-release.** Until 1.0, a minor version (0.8.0) may change the
 > integration API (config keys, template scope, the build); a patch version
-> (0.6.1) only fixes. Depend on `^0.6.0` to take fixes without breaking
+> (0.7.2) only fixes. Depend on `^0.7.1` to take fixes without breaking
 > changes. [`CHANGELOG.md`](CHANGELOG.md) says what each version changed.
 
 ## Core principles
@@ -391,6 +391,59 @@ export default ({ r, i, img, price }: SearchResultScope) => html`
   and twice.
 - **Pagination** is "show more" only: templates get `results`, `more` and
   `showMore`; there are no numbered pages.
+- **Variant groups** (`variants`, a listing's config, off by default): where
+  the surface collapses a product's variants into one result (one tile for a
+  shoe in eight sizes), `r.variants` holds the group's other products
+  (`siblings`, as results, at most 100) and its size with this one
+  (`total`). Luma asks Luigi's Box for them once per page of results, as
+  soon as the page is here, and draws the tiles again when they arrive: a
+  tile shows without them first (`r.variants` is undefined), and stays so if
+  the request fails; a listing restored on Back has them at once. Keep the
+  tile's box the same with and without them (a reserved row, an overlay, or
+  shown on hover and focus, `:hover, :focus-within`), or the rows below move
+  when they arrive; draw them inside the tile's own markup, not a different
+  template branch. `fields` names what each sibling carries; keep it to what
+  the tile shows.
+
+  ```ts
+  // integration/search/_config.ts (plp inherits it): the product's own size in `fields` too
+  export default { /* … */ fields: ['@title', 'web_url', 'size'], variants: { fields: ['size'] } };
+  // integration/_global/_init.ts: the sizes in stock, the product's and its siblings'
+  export default (config) => {
+    config._global.computedAttributes = {
+      ...config._global.computedAttributes,
+      sizes: (r) => [...new Set([r.a.size, ...(r.variants?.siblings ?? []).map((s) => s.a.size)].flat().filter(Boolean))],
+    };
+  };
+  ```
+- **A light-DOM autocomplete full screen on a phone**
+  (`autocomplete.dom: 'light'` with `fullScreen: true`, or a media query of
+  the site's own: `fullScreen: '(max-width: 767px)'`): a tap on the site's
+  input opens the autocomplete over the whole screen instead of a dropdown
+  under the input, and `autocomplete-box` gets `fullScreen: true`
+  (`state: 'idle'` until a phrase is long enough). The template renders its
+  own input, marked `data-lbx-full-screen-input` (`.value=${s.value}`): Luma
+  moves the focus into it and makes what is typed there the query and the
+  site's input's value. `back()` closes it (as Escape and the browser's
+  Back do) and `clear()` empties its input; `tabs` are one per type with
+  results. Keep the input one element in every state (not drawn anew for
+  results), and the tabs `role="tab"` siblings in their `role="tablist"`:
+  the arrow keys move between them. The arrow keys go through the options
+  it shows (the open tab's, whether the others are not drawn or hidden by
+  its CSS). While it is open the dropdown carries `data-lbx-full-screen` (a
+  phone in landscape too), and the integration's CSS places it full screen
+  there: `[data-lbx-full-screen] { inset: 0; top: var(--lbx-top, 0px) }`
+  (Luma sets `--lbx-top` to the visual viewport's top, which iOS moves when
+  it pans the page for the keyboard, and `--lbx-cover` to what Safari's
+  bars and the keyboard cover of its bottom: end the scrolling list with
+  that much space and give it `scroll-padding-bottom: var(--lbx-cover, 0px)`,
+  so its last options are not hidden). Focus leaving it for the page it
+  covers closes it. Without `fullScreen`, a light-DOM dropdown on a phone
+  stays a dropdown. The build includes this only where a file of the
+  integration's repository (a script or `.html` file, not in `node_modules`,
+  `dist` or a hidden folder) has `data-lbx-full-screen-input`. The house
+  design is always full screen on a phone; its templates get the same
+  `fullScreen`.
 - **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
@@ -411,7 +464,9 @@ On by default unless noted; each falls back to what the page would do anyway.
 `emptyValues`, `prerenderWhileTyping` and `contentVisibility`, off by
 default, are in the build only where a file of the integration's repository
 (a script or `.html` file, not in `node_modules`, `dist` or a hidden folder) names them, as `_config.ts` or `_init.ts` does when
-it sets them; a switch on by default that no file names is built as on.
+it sets them; `variants` only where a folder's `_config.ts` sets it (set it
+there, not in `_init.ts`); a switch on by default that no file names is
+built as on.
 
 | Config | What it does | Turn it off when |
 |---|---|---|
@@ -419,9 +474,10 @@ it sets them; a switch on by default that no file names is built as on.
 | `search.prefetchWhileTyping` | the search result is fetched once the typed phrase settles, so Enter shows it at once | |
 | `search.pageWhileTyping` (`'prefetch'`, `'prerender'`, `false`) | the search page of the typed phrase is fetched ahead (Chrome, Edge; Firefox and Safari as they ship it), so Enter from another page skips the site's server render; `'prerender'` renders it ahead as well (Chrome, Edge) | the site cannot take a document request per typed phrase; `'prerender'` only where its tags wait for `prerenderingchange` |
 | `search.queryUrl` (an `_init.ts` hook, off unless set) | where the site's server redirects its search form to the query's page (`/search?q=x` to `/search/x/`), names that page: Enter, the autocomplete's "show all" and a picked query load it directly, without the redirect, and the result fetched while typing is shown there | the form's other fields decide the page, or the site must handle every search itself |
-| `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 | |
+| `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 (not while the page is in the browser's back/forward cache, which restores it from memory), 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 |
+| `variants: { fields }` (opt-in) | each tile's result gets its variant group (`r.variants`, "Templates" above): one request to Luigi's Box per page of results, never waited for | the surface does not collapse variants (every group is a group of one) |
 | `_global.prefetchFilters` | a filter, sort or chip is fetched on hover, touch or focus; in a drawer with `facetsApply: 'staged'`, the selection it holds is fetched once the changes pause, so its apply button shows the results without waiting | |
 | `_global.speculation` | product pages are prerendered on hover (`'prerender'`, `'prefetch'`, `false`) | the site's server or its product-page scripts can't take a render per unfollowed hover |
 

package/build/vite.mjs

@@ -562,11 +562,12 @@ export const featureDefines = (integrationDir) => {
     __LBX_HOST_STYLES__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, 'style-host.css')))),
     __LBX_TRANSLATIONS__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, '_translations.ts')))),
     __LBX_INITS__: has((d) => d.some((f) => existsSync(resolve(integrationDir, f, '_init.ts')))),
-    // Only an integration's templates make a cart button, a filter drawer or a menu (Luma's own have none).
+    // Only an integration's templates make a cart button, a filter drawer, a menu or a light-DOM phone sheet's input (Luma's own have none; its house sheet is not light DOM).
     __LBX_CART__: has(() => inFiles('data-lbx-cart')),
     __LBX_DRAWER__: has(() => inFiles('data-lbx-drawer')),
     __LBX_MENU__: has(() => inFiles('data-lbx-menu')),
     __LBX_DROPDOWN__: has(() => inFiles('data-lbx-dropdown')),
+    __LBX_LIGHT_FULL_SCREEN__: has(() => inFiles('data-lbx-full-screen-input')),
     // Hooks only the integration's code sets (_init.ts, _widget.ts: functions, never in _config.ts).
     __LBX_AC_HOOKS__: has(() => inFiles('onOpen', 'onClose', 'onSelect', 'onReady')),
     __LBX_ON_RENDER__: has(() => inFiles('onRender')),
@@ -577,6 +578,8 @@ export const featureDefines = (integrationDir) => {
     __LBX_EMPTY_VALUES__: has(() => inFiles('emptyValues')),
     __LBX_PRERENDER_TYPING__: has(() => inFiles('prerenderWhileTyping', 'pageWhileTyping')),
     __LBX_CONTENT_VISIBILITY__: has(() => inFiles('contentVisibility')),
+    // A listing's variant groups: the key in a folder's _config.ts (the word alone is common: a catalog field, a comment).
+    __LBX_VARIANTS__: has((d) => d.some((f) => /\bvariants\b["']?\s*[:,}]/.test(existsSync(resolve(integrationDir, f, '_config.ts')) ? readFileSync(resolve(integrationDir, f, '_config.ts'), 'utf8') : ''))),
     // Options on by default: one no file names is on.
     ...Object.fromEntries(ON_BY_DEFAULT.map((k) => [`__LBX_NAMED_${k.replace(/[A-Z]/g, (c) => `_${c}`).toUpperCase()}__`, has(() => inFiles(k))])),
   };

package/docs/ACCESSIBILITY.md

@@ -139,7 +139,13 @@ guessed alt text, and forced colours and the OS setting are honoured.
   through the list puts the on-screen keyboard away: focus moves from the
   input to the sheet (`tabindex="-1"`), Escape still closes it, a tap on the
   input brings the keyboard back; Tab is the browser's; targets are 44 px; Escape and the
-  browser's Back close it.
+  browser's Back close it, and so does focus leaving it for the page it
+  covers (Tab past its last control, Shift+Tab from its first, iOS's
+  next-field arrow): it is never left on a control the sheet hides (2.4.11).
+  A light-DOM integration's full-screen autocomplete (`fullScreen`) gets the same focus, keys,
+  `aria-activedescendant` on its input and Back; a swipe moves the focus to
+  the host (`tabindex="-1"`, `role="group"` named as the input); its roles,
+  names and targets are its template's (§5).
 - **Forced colours**: the selection in `Highlight`/`HighlightText` with an
   outline, the panel (and the sheet) keep a `CanvasText` border, pills,
   chips and "Show all products" an outline.
@@ -164,6 +170,10 @@ guessed alt text, and forced colours and the OS setting are honoured.
   link marked `tabindex="-1"`); a render that removed the focused control (a
   chip, the last "show more") moves it to the region, not `<body>`. A mouse
   click keeps focus where it is.
+- **Variant groups landing** (`variants`): the tiles are drawn again, in
+  steps, with nothing announced and `aria-busy` untouched (the results did
+  not change); focus stays where it is, and in a tile whose template drew
+  other markup with its group, goes to the region, not `<body>`.
 - **Menus** (`[data-lbx-menu]` with `[data-lbx-toggle]`, the integration's
   markup): `aria-expanded` on the menu's button (the toggle with
   `aria-haspopup`/`aria-expanded`, else the first toggle) in every state;
@@ -330,7 +340,20 @@ drawer. The markup is the integration's, so:
   `aria-selected`, `tabindex="-1"`; sections as `role="group"` named by their
   heading; wrappers in between `role="presentation"`; nothing but options and
   groups inside the listbox (a pointer-only "show all" duplicate of Enter:
-  `aria-hidden="true"`, no tab stop). Decorative pictures `alt=""`.
+  `aria-hidden="true"`, no tab stop). Decorative pictures `alt=""`. Full screen on a
+  phone (`fullScreen`): the input marked `data-lbx-full-screen-input` is the combobox
+  (`role="combobox"`, `aria-autocomplete="list"`, `aria-expanded`,
+  `aria-controls` naming the listbox, a name: `inputLabel`); its back and
+  clear controls are buttons with names (`t('closeSearch')`, `t('clear')`)
+  calling `back()` and `clear()`, 44 px; type tabs a `tablist` of
+  `role="tab"` buttons with `aria-selected` (Luma moves between them with the
+  arrow keys: siblings in the tablist; the arrows go through the options
+  it shows, the open tab's); the input one element in every state
+  (drawn anew, it loses the focus and the keyboard); the input's font at
+  least 16 px (iOS zooms into a smaller one); the scrolling list ends with
+  `var(--lbx-cover)` of space and has it as `scroll-padding-bottom`, so an
+  option the keys bring into view is not under the keyboard or Safari's
+  bars (2.4.11).
 - **Listings**: filter groups as `fieldset` + `legend` (or `role="group"`
   with a name); native checkboxes, or links with `role="checkbox"` and
   `aria-checked` (never `aria-checked` on a plain link); chips named by what
@@ -345,7 +368,11 @@ drawer. The markup is the integration's, so:
   a `role="button"` div (Luma adds the keys) but a `<button>` is better.
 - **Tiles**: one link name (the picture `alt=""` when the title is in the same
   link); a struck-through old price says so (`<span class="lbx-sr-only">Was
-  </span>`), and the current one "Now" next to it.
+  </span>`), and the current one "Now" next to it. A variant group
+  (`r.variants`) is drawn inside the tile's own markup, not a different
+  template branch (focus in the tile stays on its link); shown on hover, it
+  shows on focus too (`:hover, :focus-within`), and sibling links have a
+  name and 24 px targets.
 - **Colour**: text at 4.5:1, states not by colour alone, 24 px targets; adopt
   the high-contrast mode (§4) for the colours your CSS sets.
 - **Don't** add `aria-live` to counts (Luma announces), set `tabindex="0"` on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luigisbox/luma",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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/api/ai.ts

@@ -8,10 +8,10 @@
 // Also runs in Node (the edge render service): there the
 // storefront origin is sent explicitly and nothing touches the DOM.
 
-import { PLP, RECOMMENDER, SEARCH } from '../core/features';
+import { PLP, RECOMMENDER, SEARCH, VARIANTS } from '../core/features';
 import { health } from '../core/health';
 import type { GlobalConfigType } from '../types';
-import type { Api, FacetData, Hit, Page } from '.';
+import type { Api, FacetData, Hit, Page, VariantGroup } from '.';
 import { fetchJson, TIMEOUT_MS, tokensFor, untilAborted, visitorId } from './token';
 
 export { untilAborted };
@@ -78,7 +78,8 @@ export const aiApi = (g: GlobalConfigType, origin?: string): Api => {
         return_fields: r.fields?.length ? r.fields : undefined,
       });
       const j = await post(r.endpoint, { channel_id: g.channelId, surface_id: r.surface }, body, signal);
-      return { hits: j.hits ?? [], total: j.total ?? j.total_approx ?? 0, guid: j.guid, cursor: j.next_page_cursor ?? null, status: j.pagination_status ?? 'exhausted' };
+      // `guid` is the deprecated name of `request_key` (it will change meaning).
+      return { hits: j.hits ?? [], total: j.total ?? j.total_approx ?? 0, guid: j.request_key ?? j.guid, cursor: j.next_page_cursor ?? null, status: j.pagination_status ?? 'exhausted' };
     },
 
     // A listing's and a recommender's (core/features.ts): not in a build without one.
@@ -106,5 +107,13 @@ export const aiApi = (g: GlobalConfigType, origin?: string): Api => {
             )
           ).hits ?? []
       : unbuilt,
+
+    // A listing's `variants` (core/features.ts): not in a build whose integration names none.
+    ...(VARIANTS
+      ? {
+          variants: async (ids: string[], key: string, fields: string[] | undefined, signal?: AbortSignal): Promise<Record<string, VariantGroup>> =>
+            (await post('variants', { channel_id: g.channelId }, compact({ ids, request_key: key, return_fields: fields?.length ? fields : undefined }), signal)).variants ?? {},
+        }
+      : {}),
   };
 };

package/src/api/index.ts

@@ -26,7 +26,7 @@ export interface Page {
   hits: Hit[];
   /** Exact when known, else the API's approximation. */
   total: number;
-  /** Identifies the result set; /facets takes it. */
+  /** Identifies the result set (the API's `request_key`); /facets and /variants take it. */
   guid: string;
   /** Cursor of the next page; null when there is none (see status). */
   cursor: string | null;
@@ -68,11 +68,21 @@ export interface RecoRequest {
   fields?: string[];
 }
 
+/** A product's variant group (/variants): the other members, and the group's size with the product. */
+export interface VariantGroup {
+  /** The other members of the group, by `@id`; at most 100. */
+  siblings: Hit[];
+  /** The group's size, the product included (0: not in the catalog). */
+  total: number;
+}
+
 export interface Api {
   search(r: ListingRequest, signal?: AbortSignal): Promise<Page>;
   /** Facets of a result set (its guid): values, no counts. */
   facets(guid: string, facets: { field: string; size?: number }[], signal?: AbortSignal): Promise<Record<string, FacetData>>;
   recommend(r: RecoRequest, signal?: AbortSignal): Promise<Hit[]>;
+  /** The variant groups of products of a result set (its key: `guid`), by `@id`: at most 200 ids. Built only for a listing's `variants`. */
+  variants?(ids: string[], key: string, fields: string[] | undefined, signal?: AbortSignal): Promise<Record<string, VariantGroup>>;
   /** Mint the browser token now, so the first request does not wait for it. */
   warm(): void;
 }

package/src/core/features.ts

@@ -18,6 +18,7 @@ declare const __LBX_CART__: boolean | undefined;
 declare const __LBX_DRAWER__: boolean | undefined;
 declare const __LBX_MENU__: boolean | undefined;
 declare const __LBX_DROPDOWN__: boolean | undefined;
+declare const __LBX_LIGHT_FULL_SCREEN__: boolean | undefined;
 declare const __LBX_AC_HOOKS__: boolean | undefined;
 declare const __LBX_ON_RENDER__: boolean | undefined;
 declare const __LBX_READ_QUERY__: boolean | undefined;
@@ -29,6 +30,7 @@ declare const __LBX_INITS__: boolean | undefined;
 declare const __LBX_EMPTY_VALUES__: boolean | undefined;
 declare const __LBX_PRERENDER_TYPING__: boolean | undefined;
 declare const __LBX_CONTENT_VISIBILITY__: boolean | undefined;
+declare const __LBX_VARIANTS__: boolean | undefined;
 declare const __LBX_NAMED_PRECONNECT_IMAGES__: boolean | undefined;
 declare const __LBX_NAMED_PREFETCH_FILTERS__: boolean | undefined;
 declare const __LBX_NAMED_PRELOAD__: boolean | undefined;
@@ -60,6 +62,8 @@ export const DRAWER = typeof __LBX_DRAWER__ === 'boolean' ? __LBX_DRAWER__ : tru
 export const MENU = typeof __LBX_MENU__ === 'boolean' ? __LBX_MENU__ : true;
 /** `data-lbx-dropdown` in any file of the integration: `<details>` menus in the listing's markup, closed from outside. */
 export const DROPDOWN = typeof __LBX_DROPDOWN__ === 'boolean' ? __LBX_DROPDOWN__ : true;
+/** `data-lbx-full-screen-input` in any file of the integration: a light-DOM autocomplete's own phone sheet (widgets/autocomplete, `fullScreen`). */
+export const LIGHT_FULL_SCREEN = typeof __LBX_LIGHT_FULL_SCREEN__ === 'boolean' ? __LBX_LIGHT_FULL_SCREEN__ : true;
 /** The autocomplete's `onOpen`, `onClose`, `onSelect`, `onReady` named in the integration's code. */
 export const AC_HOOKS = typeof __LBX_AC_HOOKS__ === 'boolean' ? __LBX_AC_HOOKS__ : true;
 /** A listing's `onRender` named in the integration's code. */
@@ -81,10 +85,13 @@ export const INITS = typeof __LBX_INITS__ === 'boolean' ? __LBX_INITS__ : true;
  * or code setting them): a key no file names keeps its default, as only
  * code naming it can change it. `emptyValues`, `prerenderWhileTyping` (or
  * `pageWhileTyping`: prerendering the search page typed for), `contentVisibility`.
+ * `variants` (a listing's products' variant groups, widgets/listing/variants.ts):
+ * the key in a folder's _config.ts only (the word alone is common).
  */
 export const EMPTY_VALUES = typeof __LBX_EMPTY_VALUES__ === 'boolean' ? __LBX_EMPTY_VALUES__ : true;
 export const PRERENDER_TYPING = typeof __LBX_PRERENDER_TYPING__ === 'boolean' ? __LBX_PRERENDER_TYPING__ : true;
 export const CONTENT_VISIBILITY = typeof __LBX_CONTENT_VISIBILITY__ === 'boolean' ? __LBX_CONTENT_VISIBILITY__ : true;
+export const VARIANTS = typeof __LBX_VARIANTS__ === 'boolean' ? __LBX_VARIANTS__ : true;
 /**
  * Server-rendered listings (Luigi's Box's server-side includes): adopting
  * and hydrating the server's markup. Declared, not found in the folders:

package/src/core/integration.ts

@@ -5,7 +5,7 @@
 // templates, translations and helpers the bundle would.
 
 import type { LumaApi, LumaConfigType, LumaInitType } from '../types';
-import { AUTOCOMPLETE, HOST_STYLES, INITS, PLP, RECOMMENDER, SEARCH, TRANSLATIONS } from './features';
+import { AUTOCOMPLETE, HOST_STYLES, INITS, PLP, RECOMMENDER, SEARCH, TRANSLATIONS, VARIANTS } from './features';
 
 export type Lazy<T> = Record<string, () => Promise<T>>;
 
@@ -106,9 +106,14 @@ export const loadConfig = async (files: Pick<IntegrationFiles, 'configs' | 'init
   if (config._global.disabled || !config._global.publishableKey || !config._global.channelId) return null;
   const apps = [AUTOCOMPLETE ? config.autocomplete : null, SEARCH ? config.search : null, PLP ? config.plp : null, ...(RECOMMENDER ? Object.values(config.recommenders ?? {}) : [])];
   if (INITS) for (const app of apps) if (app && !app.disabled && app.initialize && (await (app.initialize as any)(app, Luma)) === false) app.disabled = true;
+  // `variants` comes into a build from a folder's _config.ts only (build/vite.mjs
+  // featureDefines): set by an _init.ts, a build would leave it out unsaid.
+  if (import.meta.env.DEV && (config.search?.variants || config.plp?.variants) && !Object.values(files.configs).some((v: any) => v && typeof v === 'object' && 'variants' in v))
+    console.error("[lbx] variants: set it in a folder's _config.ts; a build leaves it out otherwise");
   // Anything a category page does not set is the search page's.
   const plp = PLP ? config.plp : null;
-  if (plp) for (const k of LISTING) if (plp[k] == null && config.search?.[k] != null) (plp as any)[k] = config.search[k];
+  // `variants` only where the integration names it (core/features.ts): not a key of every entry.
+  if (plp) for (const k of VARIANTS ? [...LISTING, 'variants' as const] : LISTING) if (plp[k] == null && config.search?.[k] != null) (plp as any)[k] = config.search[k];
   if (SEARCH || PLP) for (const l of [config.search, config.plp]) if (l && l.reserveSelector == null && l.anchor) l.reserveSelector = [l.anchor].flat()[0];
   return config;
 };

package/src/types.ts

@@ -16,6 +16,14 @@ export interface Result {
   type: string;
   a: Hit;
   c: Record<string, any>;
+  /**
+   * A listing's `variants`: the other products of this one's variant group
+   * (collapsed into it by the surface), as results (`siblings`, by `@id`, at
+   * most 100), and the group's size with this one (`total`). Undefined until
+   * Luigi's Box has answered (the tile is drawn again then), on the server,
+   * and outside listings.
+   */
+  variants?: { siblings: Result[]; total: number };
 }
 
 /**
@@ -237,6 +245,23 @@ export interface AutocompleteConfigType extends AppConfig<AutocompleteConfigType
   dom?: 'shadow' | 'light';
   hostClass?: string;
   hostId?: string;
+  /**
+   * `dom: 'light'`: the autocomplete full screen on a phone, with the
+   * integration's own markup. `true` where the house design is full screen
+   * (a viewport up to 600 px, or a short touch screen), or a media query of
+   * the site's own (`'(max-width: 767px)'`). There, focus or a tap on the
+   * site's input opens it with what the input holds (templates get
+   * `fullScreen: true`, `state: 'idle'` until a phrase is long enough); the
+   * template renders its own input, marked `data-lbx-full-screen-input`,
+   * which takes the focus and is the combobox there.
+   * The integration's CSS places it, keyed on `[data-lbx-full-screen]` while open
+   * (`inset: 0; top: var(--lbx-top, 0px)`): Luma sets no box on it, only `--lbx-top` (the
+   * visual viewport's top) and `--lbx-cover` (what Safari's bars and the
+   * keyboard cover of its bottom: the list's end space and
+   * `scroll-padding-bottom`). Off by default: a light-DOM dropdown
+   * on a phone stays a dropdown. The house design is always full screen there.
+   */
+  fullScreen?: boolean | string;
   /**
    * What the dropdown lines up with (its left edge and width, just below it).
    * By default the visible search field: the input when it draws its own
@@ -297,6 +322,21 @@ export interface ListingConfigType {
   sorts: string[];
   /** return_fields for the tiles (default: the surface's). */
   fields?: string[];
+  /**
+   * The variant groups of the products shown, for a surface that collapses
+   * them (one result per group: a shoe in eight sizes is one tile): each
+   * tile's result gets the group's other products as `r.variants` (their
+   * `fields`, e.g. the in-stock sizes on hover or focus). Asked from Luigi's
+   * Box once per page of results, as soon as it is here (a page restored on
+   * Back has them with it): the tiles show without them first and are drawn
+   * again when they come, never waited for; without them (an error) they
+   * stay as they are. A tile keeps its box with and without them (a reserved
+   * row, an overlay, on hover or focus): a tile growing when they come moves
+   * the rows below. `fields`: return_fields of the group's products (keep it
+   * to what the tiles show). Off by default; set it in `_config.ts` (the
+   * build includes it only where a folder's `_config.ts` does).
+   */
+  variants?: { fields: string[] };
   /** Always-on filters (e.g. what this storefront may show), AND-ed with the shopper's. */
   baseFilters?: FilterNode;
   /**
@@ -766,11 +806,24 @@ export interface AutocompleteScope extends Helpers {
    * input reaches it (the options stay out of the Tab order).
    */
   allHref: string;
-  // --- The house design (dom: 'shadow'). -------
-  /** 'idle' (the phone sheet before a phrase is long enough), 'results', 'empty' (every type answered nothing). */
+  /** 'idle' (full screen, before a phrase is long enough), 'results', 'empty' (every type answered nothing). */
   state: 'idle' | 'results' | 'empty';
-  /** The phone sheet (full screen, viewport up to 600 px) rather than the panel under the input. */
-  sheet: boolean;
+  /** Full screen on a phone (a light-DOM integration's with the config's `fullScreen`) rather than the dropdown under the input. */
+  fullScreen: boolean;
+  /** Full screen: the tabs, one per type with results (products first); `select()` shows it. The arrow keys go through the open tab's options. */
+  tabs: { kind: string; label: string; selected: boolean; select: () => void }[];
+  /**
+   * Full screen: its own input (`data-lbx-full-screen-input`): its value, placeholder
+   * and name (the site's input's); `clear()` empties it (focus stays in it);
+   * `back()` closes it as Escape and the browser's Back do, the site's
+   * input back to what it held when it opened.
+   */
+  value: string;
+  placeholder: string;
+  inputLabel: string;
+  clear: () => void;
+  back: () => void;
+  // --- The house design (dom: 'shadow'). -------
   /** The panel is at least 1000 px wide: the top product has its own column. */
   wide: boolean;
   /** Query suggestions (pills). */
@@ -781,8 +834,6 @@ export interface AutocompleteScope extends Helpers {
   hero: { r: Result; i: number } | null;
   /** The products after it (at most 6 on the panel). */
   products: { r: Result; i: number }[];
-  /** The phone sheet's tabs: one per type with results (products first); `select()` shows it. */
-  tabs: { kind: string; label: string; selected: boolean; select: () => void }[];
   /** "No results": phrases to try (options), links to browse (options), fallback products (options), the help box. */
   empty: { tries: { r: Result; i: number }[]; browse: { r: Result; i: number }[]; fallback: { r: Result; i: number }[]; help: { title: string; phone: string; tel: string; hours: string } | null };
   /** Pointer over an option: it becomes the selection (the keyboard's too). */
@@ -796,12 +847,6 @@ export interface AutocompleteScope extends Helpers {
   field: (r: Result, name: 'availability' | 'category' | 'oldPrice' | 'meta' | 'price' | 'badge') => string;
   /** The top product's spec rows (`hero.specFields`, at most 4). */
   specs: (r: Result) => { label: string; value: string }[];
-  /** The phone sheet: its input's value, placeholder and name (the site's input's), clearing it, and its back button. */
-  value: string;
-  placeholder: string;
-  inputLabel: string;
-  clear: () => void;
-  back: () => void;
 }
 export interface AutocompleteResultScope extends AutocompleteScope {
   r: Result;