@luigisbox/luma 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,73 @@ before 1.0, a minor version may break the integration API.
 
 ## Unreleased
 
+## 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
+
+- Phone sheet: a swipe through the results puts the keyboard away. The sheet
+  stays open and grows to the full screen. A tap on its input brings the
+  keyboard back.
+- Phone sheet: no tab bar when only one type has results.
+- Phone sheet: "Show all products" is at the end of the list, no longer a bar
+  pinned above the keyboard.
+- Phone sheet: the list (and the no-results column) runs on behind Safari's
+  floating bars and the keyboard, down to the bottom of the screen. Its end
+  scrolls clear of them.
+- Staged filter drawer (`facetsApply: 'staged'`): the held selection is
+  fetched in the background once the changes pause, so the apply button
+  shows the results without waiting. The results still change only on
+  apply. Off with `_global.prefetchFilters: false`, Save-Data or 2G.
+- Staged filter drawer: apply marks the swap. The old list fades out, the
+  new products fade in, and a status at the top of the listing says
+  "Filters applied · 9 products" for 2.5 s. Translation key
+  `search.applied`; CSS variables `--lbx-applied-bg`, `--lbx-applied-fg`,
+  `--lbx-applied-top`, `--lbx-applied-offset`, or
+  `[data-lbx-applied-cue]::part(pill)`;
+  `data-lbx-applied` on the listing meanwhile.
+
+### Fixed
+
+- Autocomplete "No results": `emptyState` phrases and browse links keep their
+  config text and URL when `computedAttributes` override `title` or `url`.
+  Before, a browse link could have no URL, and a tap on it did nothing.
+- Autocomplete, phone sheet, no results: each "browse" link is one row again,
+  its chevron at the right, not on a line under the title. The links' wrapper
+  is now `.e-links` (was `.browse`, the class each link also has).
+
 ## 0.5.0 — 2026-10-19
 
 Upgrading from 0.4.0: read **Changed** first.

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.6.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.5.1) only fixes. Depend on `^0.5.0` to take fixes without breaking
+> (0.7.1) only fixes. Depend on `^0.7.0` 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 |
 |---|---|---|
@@ -422,7 +477,8 @@ it sets them; a switch on by default that no file names is built as on.
 | `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 | |
+| `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 |
 
 ### Analytics

package/build/vite.mjs

@@ -91,6 +91,8 @@ export const chunkOf = (id) => {
   if (/\/src\/core\/(reconciler|recommenders)\.ts$/.test(id)) return 'lbx-place';
   // The listing's high-contrast toggle: only a site that turns it on loads it (widgets/listing/element.ts).
   if (/\/src\/core\/contrast-toggle\.ts$/.test(id)) return 'lbx-contrast';
+  // An Apply's cue in a staged drawer: asked for when such a drawer opens (widgets/listing/element.ts).
+  if (/\/src\/widgets\/listing\/applied\.ts$/.test(id)) return 'lbx-applied';
   // The search page's own: not in lbx-listing, which a category page loads too
   // (2.1 kB gzip it never ran).
   if (/\/src\/widgets\/search\/index\.ts$/.test(id)) return 'lbx-search';
@@ -560,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')),
@@ -575,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

@@ -134,8 +134,18 @@ guessed alt text, and forced colours and the OS setting are honoured.
   `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",
   the clear button "Clear"; the type tabs are a `tablist` (arrow keys move
-  between them); Tab is the browser's; targets are 44 px; Escape and the
-  browser's Back close it.
+  between them), shown for two types or more (one type: no tabs, its
+  listbox named by the type, "Products"); a finger's vertical swipe
+  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, 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.
@@ -160,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;
@@ -180,6 +194,18 @@ guessed alt text, and forced colours and the OS setting are honoured.
   focus staying on the control. With `facetsApply: 'staged'` its
   changes wait for `[data-lbx-drawer="apply"]`; closing it otherwise discards
   them (the scope's `pending` says whether there is anything to apply).
+  Apply's result is said in Luma's status region as "Filters applied" and
+  the count (translation `search.applied`, WCAG 4.1.3), and shown for 2.5 s
+  in a pill at the listing's top with the same words (hidden from assistive
+  technology: it repeats the status region; white on dark, at least 10:1
+  over any page behind it; opaque in the high-contrast mode and in forced
+  colours, with a border there; taps go through it; it wraps rather than
+  cuts its words at 320 px or 200% text, and follows a larger default font
+  size; it moves no content). While the applied results load, the
+  old list is dimmed as a busy one is: not at all in the high-contrast
+  mode, to 60% in forced colours. The new tiles fade in; they also rise
+  unless reduced motion is asked for. The pill may overlap the top of the
+  drawer's opener, where focus returns, for its 2.5 s; it never hides it.
   The build includes the drawer 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-drawer` (written
   literally, as in a template).
@@ -213,7 +239,8 @@ guessed alt text, and forced colours and the OS setting are honoured.
 - Built-in templates: the pager is a native "Show more" button with a
   "Showing N of M" line (no numbered pages); tile pictures are decorative
   (`alt=""`: the link reads as its title and price once); targets of at least
-  24 px; no fade under reduced motion; tiles reflow to one column at 320 px.
+  24 px; no fade under reduced motion (except a staged drawer's Apply: its
+  new tiles fade in, without rising); tiles reflow to one column at 320 px.
 
 ### Recommenders (`widgets/recommender/`)
 
@@ -232,7 +259,9 @@ guessed alt text, and forced colours and the OS setting are honoured.
   reset cannot remove it there).
 - **Reduced motion**: the hold's loading bar stands still, the listing's
   dim while a re-render loads comes without its fade and the new results
-  without their fade-in, no smooth scrolling of ours.
+  without their fade-in, no smooth scrolling of ours. One exception: after
+  a staged drawer's Apply the new tiles still fade in (opacity only, nothing
+  moves), so the swap the shopper confirmed is seen.
 - `.lbx-sr-only`: a class for text that only screen readers read (e.g. "Was"
   before an old price), defined for every widget and in server-rendered CSS.
 
@@ -311,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
@@ -326,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.5.0",
+  "version": "0.7.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/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/locales/cs.json

@@ -53,6 +53,7 @@
     "label": "Výsledky vyhledávání",
     "shown": "Zobrazeno {shown} z {total}",
     "drawer": "Filtry",
+    "applied": "Filtry použity · {results}",
     "removeFilter": "Odebrat filtr: {label}",
     "chosen": "Vybrané filtry",
     "clearAll": "Zrušit vše",

package/src/locales/de.json

@@ -51,6 +51,7 @@
     "label": "Suchergebnisse",
     "shown": "{shown} von {total} angezeigt",
     "drawer": "Filter",
+    "applied": "Filter angewendet · {results}",
     "removeFilter": "Filter entfernen: {label}",
     "chosen": "Ausgewählte Filter",
     "clearAll": "Alle entfernen",

package/src/locales/en.json

@@ -51,6 +51,7 @@
     "label": "Search results",
     "shown": "Showing {shown} of {total}",
     "drawer": "Filters",
+    "applied": "Filters applied · {results}",
     "removeFilter": "Remove filter: {label}",
     "chosen": "Selected filters",
     "clearAll": "Clear all",

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 };
 }
 
 /**
@@ -80,7 +88,9 @@ export interface GlobalConfigType {
    * Two in flight, the latest intent wins; 20 per category or query; none
    * offline, with Save-Data or on 2G; range sliders never. A hover that is
    * not followed costs one search request (no render, no hook, no analytics
-   * event). Default true.
+   * event). In a drawer that stages (`facetsApply`), the selection it holds
+   * is fetched the same way once the changes pause, for its apply button.
+   * Default true.
    */
   prefetchFilters?: boolean;
   /**
@@ -235,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
@@ -295,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;
   /**
@@ -333,10 +375,22 @@ export interface ListingConfigType {
    * How a change inside the open filter drawer (`[data-lbx-drawer-panel]`,
    * opened by `[data-lbx-drawer="open"]`) applies. 'instant' (default): at
    * once, as in a sidebar. 'staged': held in the drawer (it shows the pending
-   * selection, the scope's `pending` is true, nothing is fetched) until its
-   * apply button (`[data-lbx-drawer="apply"]`) commits them in one request
-   * and one history entry; closing it otherwise (`[data-lbx-drawer="close"]`,
-   * Escape) discards them. Per viewport min-width, e.g. `{ "0": "staged",
+   * selection, the scope's `pending` is true, the results behind it do not
+   * change) until its apply button (`[data-lbx-drawer="apply"]`) commits them
+   * in one request and one history entry; closing it otherwise
+   * (`[data-lbx-drawer="close"]`, Escape) discards them. Once the changes
+   * pause, the held selection's results are fetched in the background
+   * (unless `_global.prefetchFilters` is false, with Save-Data or on 2G),
+   * so Apply shows them without waiting; nothing is shown and `onRender`
+   * does not run before Apply. Apply's swap is marked: the old list fades
+   * out, the new tiles come in, and a status at the listing's top says what
+   * was applied ("Filters applied · 9 products", translation
+   * `search.applied`) for 2.5 s, in `[data-lbx-applied-cue]`'s shadow root
+   * (out of reach of the site's resets; themed with `--lbx-applied-bg`,
+   * `--lbx-applied-fg`, `--lbx-applied-top` for a sticky header's height,
+   * `--lbx-applied-offset` to sit below a heading at the listing's top, or
+   * restyled with `[data-lbx-applied-cue]::part(pill)`), with
+   * `data-lbx-applied` on the listing meanwhile for the site's own CSS. Per viewport min-width, e.g. `{ "0": "staged",
    * "768": "instant" }` (staged on phones). Outside an open drawer every
    * change is instant.
    */
@@ -752,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). */
@@ -767,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). */
@@ -782,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;