@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/types.ts

@@ -0,0 +1,778 @@
+// Integration config types. `_config.ts` holds JSON-safe
+// values only (it is parsed as JSON), `_init.ts` sets anything that needs code
+// (functions, computed attributes) and may mutate the config it is given.
+
+import type { FilterNode, Hit } from './api';
+import type { Position } from './core/reconciler';
+import type { ImageInfo, ImageOptions } from './core/images';
+
+export type { FilterNode, Hit, ImageInfo, ImageOptions, Position };
+
+/** A result as templates see it: `a` = the hit's fields (flat, as discovery returns them), `c` = computed attributes. */
+export interface Result {
+  /** `@id`, e.g. "product/<id>". */
+  id: string;
+  /** `@type`: product, category, brand, … */
+  type: string;
+  a: Hit;
+  c: Record<string, any>;
+}
+
+/**
+ * Nested dictionary; `{name}` placeholders. A plural is an object of
+ * `Intl.PluralRules` categories (`zero`, `one`, `two`, `few`, `many`,
+ * `other`; `other` required), picked by the `count` param in the locale:
+ * `{ one: '{count} produkt', few: '{count} produkty', many: '{count} produktów', other: '{count} produktu' }`.
+ */
+export interface Dictionary {
+  [key: string]: string | Dictionary;
+}
+/** Keyed by locale: `{ de: { search: { sort: 'Sortieren' } } }`. */
+export type Translations = Record<string, Dictionary>;
+
+export interface GlobalConfigType {
+  /** Luigi's Box AI publishable key (pub_<env>_<region>_…), bound to the channel and the site's origins. */
+  publishableKey: string;
+  /** Channel (serving destination), lbn_… */
+  channelId: string;
+  /** API region, from the key: 'eu1'. */
+  region?: string;
+  /** Dictionary + number formatting locale ('de', 'cs', 'en'). Default 'en'. */
+  locale?: string;
+  /** ISO 4217, for price(). */
+  currency?: string;
+  /** Intl.NumberFormat options for price(), e.g. { trailingZeroDisplay: 'stripIfInteger' }. */
+  priceFormat?: Intl.NumberFormatOptions & { trailingZeroDisplay?: 'auto' | 'stripIfInteger' };
+  /** Catalog type of products (default 'product'). */
+  itemType?: string;
+  /** The site's search input(s); autocomplete binds to whatever matches. */
+  inputSelector?: string;
+  disabled?: boolean;
+  /**
+   * Speculation Rules (Chrome, Edge): our product links (listings,
+   * recommenders, the autocomplete's links) are prerendered, or prefetched,
+   * when the shopper shows intent (`moderate`: ~200 ms of hover, pointerdown on
+   * touch; the browser keeps two at a time). The product page is then shown at
+   * once on the click. It costs the site's server a page render per intent
+   * that may not be followed, and the product page's scripts run in it before
+   * it is shown. Default 'prerender'; `false` turns it off (e.g. a site whose
+   * servers or product-page scripts can't take speculative views), 'prefetch'
+   * fetches the HTML only.
+   */
+  speculation?: 'prerender' | 'prefetch' | false;
+  /** Links speculation applies to (CSS). Default: links in our result lists (`[data-lbx-list]`), recommenders and the autocomplete dropdown. */
+  speculationSelector?: string;
+  /** `moderate` (default: hover, pointerdown) or `conservative` (pointerdown / touchstart only). */
+  speculationEagerness?: 'moderate' | 'conservative';
+  /** Preconnect to the product image host (learnt from the first results) on later page loads. Default true. */
+  preconnectImages?: boolean;
+  /** Product images: srcset, the eager first row, the box's size, placeholders, preloads (`image()` / `img()` in templates). */
+  images?: ImagesConfig;
+  /**
+   * Filter clicks that render at once (search and category listings): when
+   * the shopper shows intent on one of our controls leading to another state
+   * of the listing (a facet value, a flag, a sort, a chip, "clear all", the
+   * next page: the pointer resting on it ~100 ms, pointerdown on touch,
+   * keyboard focus), page 1 of that state's products is fetched. The click
+   * renders it in the next frame (the facets of the new result follow). The
+   * control's state is its URL: a link's `href`, or `data-lbx-href` (the
+   * scope's `link.href`) on any other element, e.g. a checkbox's `<label>`.
+   * 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.
+   */
+  prefetchFilters?: boolean;
+  /**
+   * The high-contrast mode's switch (the previous-generation Luma's "High-contrast mode"
+   * button) at the start of every listing: visually hidden until it has focus,
+   * unless the visitor's OS asks for a contrast preference or the mode is on.
+   * The mode itself follows `prefers-contrast: more` without it (pure CSS,
+   * docs/ACCESSIBILITY.md). Default false.
+   */
+  contrastToggle?: boolean;
+  /** Set in _init.ts: templates read them as r.c.<name>. Defaults: title, url, image, price. */
+  computedAttributes?: Record<string, (r: Result) => unknown>;
+  translations?: Translations;
+  /**
+   * `false`: no analytics at all, whatever `_analytics.ts` says (README
+   * "Analytics": what is sent is that file's).
+   */
+  analytics?: false;
+  /**
+   * The site's dataLayer, for analytics' `dl()` (default `dataLayer`): here,
+   * not in `_analytics.ts`, because the entry keeps its pushes for the next
+   * page when the visitor leaves before analytics has run.
+   */
+  dataLayer?: string;
+  /**
+   * Puts a product in the site's cart (`_init.ts`, or `_global/_widget.ts`:
+   * only widgets call it): what a click on `[data-lbx-cart]` in one of our
+   * tiles runs (announced to analytics first: `lumaCarts()`). `count`: the
+   * attribute's value (default 1).
+   */
+  addToCart?: (r: Result, o: { count: number; el: HTMLElement; event: MouseEvent }) => unknown;
+}
+
+/**
+ * Product images, JSON. The template
+ * helpers `img(r, i)` / `image(r, i)` build every attribute from it.
+ */
+export interface ImagesConfig {
+  /**
+   * srcset candidates built from the image URL (`r.c.image`): `match` is a
+   * regex on it (default: the whole URL); each candidate is the URL with
+   * `match` replaced (`$1`… are its groups). Either named sizes, descriptor ->
+   * replacement (`{ "240w": "/thumb_base_$1", "480w": "/thumb_$1" }`, or `1x` /
+   * `2x`), or a resizer: `pattern` with `{w}` for each of `widths`
+   * (`"$1?width={w}"`, `[200, 400, 800]`). A URL it does not match gets no srcset.
+   */
+  srcset?: { match?: string; candidates?: Record<string, string>; pattern?: string; widths?: number[] };
+  /** The `sizes` attribute for w descriptors: the tile image's rendered width per viewport (`(min-width: 992px) 232px, 50vw`). */
+  sizes?: string;
+  /** The image box's intrinsic size, as width/height attributes (its aspect ratio before the image arrives: no layout shift). Default 400 x 400. */
+  width?: number;
+  height?: number;
+  /**
+   * The first row of a listing: eager, fetchpriority=high, preloaded. A
+   * number (the first N), or columns per viewport min-width
+   * (`{ "0": 2, "576": 3, "1400": 4 }`, read with matchMedia). Default
+   * `{ "0": 2, "768": 3, "1200": 4 }`. The rest is lazy.
+   */
+  firstRow?: number | Record<string, number>;
+  /** Catalog fields (or computed attributes) holding a placeholder: a dominant colour (CSS hex / rgb / hsl), a tiny image URL. Default: the neutral skeleton. */
+  placeholder?: { color?: string; image?: string } | false;
+  /** Preload the first row (`<link rel=preload as=image>`): from the server's fragment, the bundle when it has the result, a Back restore. Default true. */
+  preload?: boolean;
+  /** Lazy images fade in on load (not under reduced motion; never the first row). Default true. */
+  fade?: boolean;
+  /** Results fetched ahead (typing, a hovered filter): warm the first N of their images at low priority. Default 0 (off). */
+  warm?: number;
+}
+
+interface AppConfig<Self> {
+  disabled?: boolean;
+  translations?: Translations;
+  /** Set in the app's _init.ts: overrides of _global.computedAttributes for this app only. */
+  computedAttributes?: Record<string, (r: Result) => unknown>;
+  /** The app's _init.ts. Return false to not start this app. */
+  initialize?: (config: Self, Luma: LumaApi) => void | boolean | Promise<void | boolean>;
+}
+
+export interface AutocompleteConfigType extends AppConfig<AutocompleteConfigType> {
+  /** Search surface (lbs_search_…); autocomplete is the same surface with a partial query. */
+  surface: string;
+  /** One request per type, in parallel; groups render in this order. */
+  types: { type: string; size: number; fields?: string[]; filters?: FilterNode }[];
+  /**
+   * The shortest phrase that asks anything (default 0: the first letter asks,
+   * on the keystroke; one-letter phrases are cached). An empty phrase never asks.
+   */
+  minChars?: number;
+  /**
+   * Request pacing. A phrase of up to `instantChars`
+   * characters (default 3) asks on the keystroke. A longer one asks once
+   * typing pauses for `debounceMs` (default 300: longer than the 150-250 ms
+   * between a steady typist's keys, so a word typed in one go is one request,
+   * not one per key), but at least every `maxWaitMs` (default 800) while the
+   * keys keep coming, so the dropdown follows a fast typist at a calm cadence.
+   * A phrase already answered (backspacing, retyping) shows at once.
+   */
+  instantChars?: number;
+  debounceMs?: number;
+  maxWaitMs?: number;
+  /** A host element whose colour the dropdown uses as accent (its background, else its text colour). */
+  accentFrom?: string;
+  /**
+   * The house design's colours, font and corners (`dom: 'shadow'`). Five are
+   * sampled from the
+   * page (font, fg, bg, accent, radius); the rest are derived from them. A
+   * value here replaces the sampled or derived one (`--lbx-<name>` in the
+   * dropdown's shadow root: an integration's `style-autocomplete.css` can set
+   * the same properties on `:host`). `onAccent` follows `accent` (white, or
+   * near-black on a light accent) unless set.
+   * `{ "accent": "#1a73e8", "font": "Inter, sans-serif", "line": "#d0d0d0" }`
+   */
+  tokens?: Partial<Record<'font' | 'fg' | 'bg' | 'accent' | 'radius' | 'muted' | 'line' | 'soft' | 'tint' | 'tintStrong' | 'onAccent' | 'ok' | 'radiusRow' | 'radiusTile', string>>;
+  /**
+   * The house design's top product (the first product result, its own
+   * column). `variant`: 'image' (default, a large picture) or 'spec'
+   * (technical catalogues: a small picture, then up to 4 of `specFields` as
+   * label / value rows; a label is the translation `autocomplete.specs.<field>`,
+   * else the field's name). `badgeField`: a result field shown as a pill on
+   * the picture (e.g. a catalog label: "New", "Sale"); none by default.
+   */
+  hero?: { variant?: 'image' | 'spec'; specFields?: string[]; badgeField?: string };
+  /** The products beside the top product: 'grid' (default, 2 columns of cards) or 'list' (rows: picture, title over meta, stock, price). */
+  productLayout?: 'grid' | 'list';
+  /**
+   * Result fields (or computed attributes, `r.c`) the house design's product
+   * cards show; each optional, a missing value is not drawn. `availability`:
+   * a text, or true / a positive number for "In stock" (`autocomplete.inStock`);
+   * `category`: the text after the stock; `oldPrice`: struck through beside
+   * the price; `meta`: the line under the title in the list layout (a part
+   * number); `price`: the price instead of `r.c.price`. A price that is a
+   * number is formatted (`price()`); a text (a computed attribute in the
+   * shop's own format, "1.099,-") is shown as it is. None by default.
+   */
+  productFields?: { availability?: string; category?: string; oldPrice?: string; meta?: string; price?: string };
+  /**
+   * "No results" in the house design (its own layout): `tryQueries`, phrases offered as chips (handed to the site's
+   * search); `browse`, links (`{ title, url }`); `fallback`, products from
+   * the whole shop in a strip apart, labelled as not results: `null`
+   * (default: no strip) or `{ query, size }` (a fixed product search, asked
+   * once per page). The help box shows when the translation
+   * `autocomplete.help.phone` is set.
+   */
+  emptyState?: { tryQueries?: string[]; browse?: { title: string; url: string }[]; fallback?: { query: string; size?: number } | null };
+  /**
+   * 'shadow' (default): our own markup and CSS in a shadow root.
+   * 'light': the dropdown is a light-DOM element, so the site's own CSS styles
+   * it (a 1:1 port of an existing design); `hostClass` / `hostId` go on it and
+   * the integration's autocomplete styles go into the document.
+   */
+  dom?: 'shadow' | 'light';
+  hostClass?: string;
+  hostId?: 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
+   * border or shadow, else its nearest ancestor up to its form (at most 4
+   * levels) that draws one (a border, a shadow or a background) and is the
+   * field rather than the bar around it (at least the input's width, not much
+   * taller, not as wide as the page); else the input. A selector: the input's
+   * nearest ancestor matching it (across shadow roots), else the input.
+   * `'input'`: always the input. At least 360 px wide; on a phone (below
+   * 480 px) a field spanning most of the screen exactly, else the screen's
+   * width.
+   */
+  alignTo?: 'input' | string;
+  /** _init.ts hooks, for sites whose own code reacts to their dropdown opening, closing or a pick. */
+  onOpen?: () => void;
+  /** Why it closed: a pick, Enter / Escape in the input, focus leaving, a press outside, a route change, … */
+  onClose?: (reason: 'select' | 'enter' | 'escape' | 'back' | 'blur' | 'outside' | 'navigate' | 'empty' | 'hidden' | 'api') => void;
+  onSelect?: (r: Result | null) => void;
+  /** _init.ts: receives the dropdown's controls once it has started (e.g. for the site's own code that opens or closes it). */
+  onReady?: (controls: { close: () => void; reposition: () => void }) => void;
+}
+
+/** Where a listing lives, and what it shows. */
+export interface ListingConfigType {
+  /** Anchor candidates, most specific first. */
+  anchor: string | string[];
+  position: Position;
+  /** Wait until the anchor is stable this long (frameworks that re-render after load). */
+  settleMs?: number;
+  /** Element that reserves our remembered height (default: the anchor). */
+  reserveSelector?: string;
+  /** Fail-safe: show the host's page if ours has not rendered after this long (default 4000). */
+  holdTimeoutMs?: number;
+  /** Discovery surface: lbs_search_… for search, lbs_collection_… for category pages. */
+  surface: string;
+  /** Hits per page: the first page, and each "show more". */
+  size: number;
+  /** Faceted fields, in sidebar order. Range facets (numbers) are detected from the facets response. */
+  facets: string[];
+  /** Values per terms facet (default 50). */
+  facetSize?: number;
+  /**
+   * With a filter on, also list each facet's values that the page has without
+   * the shopper's filters, marked `empty` (sites that grey them out rather than
+   * hide them). One more facets request per scope or query (and its fields).
+   */
+  emptyValues?: boolean;
+  /** Sorts as field:direction ('lbx:price:asc'); '' = relevance. Labels: translations <app>.sorts. */
+  sorts: string[];
+  /** return_fields for the tiles (default: the surface's). */
+  fields?: string[];
+  /** Always-on filters (e.g. what this storefront may show), AND-ed with the shopper's. */
+  baseFilters?: FilterNode;
+  /**
+   * _init.ts: after each render (e.g. to keep the site's document title in step).
+   * `shown`: the results loaded; `page`: the pages loaded (1, plus one per "show more"). */
+  onRender?: (info: { route: string; query: string; total: number; shown: number; page: number; url: URL }) => void;
+  /** Host classes for our element, so it sits in the site's own container/grid. */
+  rootClass?: string;
+  /** Show the query / category name as a heading. */
+  showTitle?: boolean;
+  /** On/off filters of our own (in the URL as lbx.flag=<id>); labels: translations <app>.flags.<id>. */
+  flags?: { id: string; filter: FilterNode }[];
+  /**
+   * A click on a link of ours to another page (a product) remembers the
+   * listing (every page loaded, trimmed to `fields`) and where the shopper was, in
+   * sessionStorage; Back to that URL then renders it at once, at the same
+   * tile, and refreshes it in the background. Default true.
+   */
+  restoreOnBack?: boolean;
+  /** Near the end of the loaded tiles (~70%), the next page is fetched from the cursor, so "show more" appends at once. Default true. */
+  prefetchNextPage?: boolean;
+  /**
+   * Tiles out of view skip their style, layout and paint (`content-visibility:
+   * auto`), each at its own measured size: a long list's re-render about
+   * halves (a production integration's unstyled stub page, a sort after 136 tiles: style,
+   * layout and paint 243 → 144 ms, longest task 124 -> 85 ms at 4x CPU).
+   * Opt-in: every tile is then contained, always (paint: nothing of it shows
+   * outside its box, a hover panel or a badge hanging out is cut; its own
+   * stacking context; a `position: fixed` inside it is fixed to the tile;
+   * margins no longer collapse through it), and tiles a "show more" added
+   * out of view stand in at the first tile's size until they come near.
+   * Default false.
+   */
+  contentVisibility?: boolean;
+  /**
+   * 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",
+   * "768": "instant" }` (staged on phones). Outside an open drawer every
+   * change is instant.
+   */
+  facetsApply?: 'instant' | 'staged' | Record<string, 'instant' | 'staged'>;
+  /** Facet groups: collapsible (accordion) and searchable. */
+  facetGroups?: FacetGroupsConfig;
+  /**
+   * The step of a range facet's slider and inputs, by facet name (default 1):
+   * `{ "lbx:price": 10 }`. An arrow key moves a thumb by one step, Page Up /
+   * Page Down by a tenth of the range (whole steps).
+   */
+  rangeSteps?: Record<string, number>;
+}
+
+/** `facetGroups` of a listing (JSON). */
+export interface FacetGroupsConfig {
+  /**
+   * Which groups start open: `true` (all, the default), `false` (none), or
+   * the first N of the sidebar; per viewport min-width (`{ "0": false,
+   * "1024": 3 }`: closed on phones, the first three open on desktops). A
+   * group with a selection starts open; the shopper's toggles are kept for
+   * the visit (another category or query starts anew). Templates get each
+   * group's `open`, `toggle` and `id`.
+   */
+  open?: boolean | number | Record<string, boolean | number>;
+  /** Facet fields whose group gets a search box over its values (client-side, as typed; case and diacritics ignored). */
+  search?: string[];
+  /** A group's search box only from this many values (default 10). */
+  searchMin?: number;
+}
+
+export interface SearchConfigType extends AppConfig<SearchConfigType>, ListingConfigType {
+  /** Pathname regex of search pages; omitted = any page with the query param. */
+  urlMatch?: string;
+  /** Query param holding the query ('q'). Without it, capture group 1 of urlMatch is the query. */
+  queryParam?: string;
+  /** _init.ts overrides for URLs a regex cannot describe. */
+  active?: (url: URL) => boolean;
+  readQuery?: (url: URL) => string;
+  /** Extra result types shown above the results (category and brand tiles), one request each. */
+  quick?: { type: string; size: number; fields?: string[] }[];
+  /**
+   * On the search page, a new query from the site's search form (the form
+   * holding `_global.inputSelector`: Enter, its button, and the autocomplete's
+   * Enter / "show all" / query suggestions, which submit it) is shown in
+   * place: a new history entry and our listing re-rendered, no page load.
+   * Default true. false: every search is a page load, e.g. where the site's
+   * search page has server-rendered parts outside our listing that must follow
+   * the query, or page-view analytics that must fire per search.
+   */
+  inPlaceQuery?: boolean;
+  /**
+   * While the shopper types in `_global.inputSelector` (on any page), once the
+   * phrase settles (`prefetchDelayMs`, default 300) the search page's result
+   * for the URL their form would submit to is fetched: Enter on the search page
+   * renders it without a request, and a page load of it (from another page)
+   * within `prefetchMaxAgeMs` renders it from sessionStorage. One in flight,
+   * the latest two kept; not offline, with Save-Data or on 2G. Default true.
+   */
+  prefetchWhileTyping?: boolean;
+  prefetchDelayMs?: number;
+  /** How long a result fetched while typing is used (ms; older: asked anew). Default 120000. */
+  prefetchMaxAgeMs?: number;
+  /**
+   * Also prerender the search page (Speculation Rules: Chrome, Edge) of the
+   * phrase whose result was just fetched while typing, if it is still the one
+   * typed, so Enter from another page activates a page already rendered. One
+   * at a time (a newer phrase replaces it). It costs a host page render on
+   * the site's server per settled phrase, and runs the site's scripts in it:
+   * analytics that do not wait for `prerenderingchange` count a page view the
+   * shopper may never see. Not on the search page when `inPlaceQuery` is on.
+   * Default false.
+   */
+  prerenderWhileTyping?: boolean;
+  /** Speculation Rules eagerness of that list rule: 'immediate' (default) or 'eager'. */
+  prerenderEagerness?: 'immediate' | 'eager';
+}
+
+/**
+ * A page's own facets (plp `facetsFor`): the fields to facet, in order, and
+ * optionally the sidebar's group order for templates (`layout`: fields plus
+ * the integration's own group keys, e.g. a group of flags).
+ */
+export interface FacetLayout {
+  facets: string[];
+  layout?: string[];
+}
+
+/** A category page's scope (collection_filters) and title; null = not ours. */
+export type CategoryFilter = { scope: FilterNode; title: string } | null;
+
+/** How the host's own URL parameters map onto listing state (JSON-safe). */
+export interface ParamMap {
+  /**
+   * The host's page param. Luma opens every listing on its first page and
+   * appends the next ones ("show more"; cursors cannot jump to page N): a URL
+   * with their page 1 is ours, a later page of theirs is left to their own
+   * listing. Our UI never writes it (it drops it with any change).
+   */
+  page?: string;
+  sort?: { param: string; values: Record<string, string> };
+  /** On/off host params with a fixed value; labels: translations plp.flags["param=value"]. */
+  flags?: { param: string; value: string; filter: FilterNode }[];
+  /**
+   * Facet field -> the host param carrying it. `values`: their value -> ours
+   * (a value mapped to '' is one we cannot express: such a URL stays theirs);
+   * `slug: false`: values as they are (with `values`: the unmapped ones);
+   * neither: slugs of our values (looked up in the category's facet values).
+   */
+  facetParams?: Record<string, { param: string; slug?: boolean; values?: Record<string, string> }>;
+  separator?: string;
+  /** Read-only host params turned into a range filter, passed through unchanged. */
+  ranges?: { min: string; max: string; field: string }[];
+  /** Regex of params that never block a takeover (tracking). */
+  ignore?: string;
+}
+
+export interface PlpConfigType extends AppConfig<PlpConfigType>, Partial<ListingConfigType> {
+  /** Pathname regex of category pages. */
+  urlMatch: string;
+  /**
+   * _init.ts: narrows urlMatch for URLs a regex cannot describe (the bundle
+   * only: the snippet's rules are JSON, so they match on urlMatch alone, and
+   * the bundle drops a hold on a page `active` rejects at boot).
+   */
+  active?: (url: URL) => boolean;
+  /**
+   * false: no early-hold rule for category pages. Needed only when urlMatch
+   * over-matches (`active` narrows it) and style-host.css would hide something
+   * on the pages it over-matches (it must hit only elements of the category
+   * page). Default: a rule.
+   */
+  earlyHold?: boolean;
+  params?: ParamMap;
+  /**
+   * Category record lookup: the record of `type` (default 'category') whose
+   * `field` equals the page URL's path (no trailing slash; `absolute`: origin + path),
+   * through the listing's own collection surface.
+   */
+  lookup?: { type?: string; field: string; absolute?: boolean };
+  /** _init.ts: category record -> filter. */
+  toFilter?: (category: Hit) => CategoryFilter;
+  /** _init.ts: filter straight from the URL (no lookup). */
+  fromUrl?: (url: URL) => CategoryFilter;
+  /**
+   * _init.ts: this page's facets, when they depend on the category (its own
+   * technical parameters), instead of `facets`. It runs in the server
+   * renderer too (no DOM there): what it returns must not depend on the
+   * browser, or a server-rendered page's markup changes on its first client
+   * render. May return a promise (e.g. waiting for the host's page); null or
+   * undefined = `facets`. Selected fields not in the list still get their group.
+   */
+  facetsFor?: (url: URL, category: { scope?: FilterNode; title: string; filters: Record<string, string[]> }) => FacetLayout | null | undefined | Promise<FacetLayout | null | undefined>;
+}
+
+export interface RecommenderConfigType extends AppConfig<RecommenderConfigType> {
+  /** Recommender surface (lbs_recommender_…): it decides the model. */
+  surface: string;
+  /** Object type recommended (default: _global.itemType). */
+  type?: string;
+  size: number;
+  /** return_fields the tiles need (keeps the response small). */
+  fields?: string[];
+  /** Inline widget: pathname regex, anchor, placement. */
+  urlMatch?: string;
+  anchor?: string | string[];
+  position?: Position;
+  settleMs?: number;
+  /** Height reserved while loading. */
+  reserve?: number;
+  /** Host classes for the widget's element, so it sits in the site's grid (e.g. 'col-12'). */
+  rootClass?: string;
+  /** Popup widget, opened on "added to cart": the host's success notice selector. */
+  confirm?: string;
+  /** Max time from the add-to-cart click to the notice (default 10000). */
+  windowMs?: number;
+  /** _init.ts overrides. */
+  active?: (url: URL) => boolean;
+  /** _init.ts: anchors read from the page, as typed identities ("product/<id>"); [] = no widget. */
+  items?: () => string[];
+  /** Anchors are also excluded (on top of the API's own exclusion); default false. */
+  excludeItems?: boolean;
+  /** _init.ts, popup: the anchor (typed identity) being added when this click target is an add-to-cart control. */
+  intent?: (target: Element) => string | null;
+}
+
+export interface LumaConfigType {
+  _global: GlobalConfigType;
+  autocomplete?: AutocompleteConfigType;
+  search?: SearchConfigType;
+  plp?: PlpConfigType;
+  recommenders?: Record<string, RecommenderConfigType>;
+}
+
+/** What inits receive as their second argument. */
+export interface LumaApi {
+  version: string;
+  config: LumaConfigType;
+}
+
+export type LumaInitType = (config: LumaConfigType, Luma: LumaApi) => void | boolean | Promise<void | boolean>;
+
+/**
+ * `_widget.ts` of a folder: loaded with the widget that uses the folder (its
+ * chunk), and run once, before that widget's context is made: the place for
+ * hooks only a widget calls (computedAttributes, toFilter, onRender, onOpen…),
+ * which in `_init.ts` ship and run on every page. `_global/_widget.ts` gets
+ * the whole config, a widget folder's its own. Its return value is ignored
+ * (a widget that loads runs; disable one in `_init.ts`).
+ */
+export type LumaWidgetInitType<C = LumaConfigType> = (config: C, Luma: LumaApi) => void | Promise<void>;
+
+// --- Template scopes: what a template-*.ts function receives. -------------
+
+/** Available in every template. */
+export interface Helpers {
+  /** Translate: the widget's keys first (search.sort, …), then the bare key. */
+  t: (key: string, params?: Record<string, unknown>) => string;
+  /** A number as a price in the site's locale and currency. */
+  price: (n: unknown) => string;
+  /** A field's text (its first value when it is a list), for attributes and alt text. */
+  plain: (s: unknown) => string;
+  first: (v: unknown) => any;
+  /** Another template of the widget, with this scope plus props. */
+  include: (name: string, props?: Record<string, unknown>) => unknown;
+  /** A result's image attributes (`_global.images`): src, srcset, sizes, width/height, loading, fetchpriority, `ph` (its box's placeholder style). */
+  image: (r: Result, i: number, opts?: ImageOptions) => ImageInfo;
+  /** A complete `<img>` in its placeholder box (`<span class="lbx-img" data-lbx-ph>`); nothing without an image. */
+  img: (r: Result, i: number, opts?: ImageOptions) => unknown;
+}
+
+/**
+ * A UI action: `go(link)` applies it; `href` is the URL it leads to. Put it on
+ * the control as a link's `href`, or as `data-lbx-href` on any other element
+ * (a checkbox's `<label>`, a button): intent on it then prefetches that state
+ * (`_global.prefetchFilters`).
+ */
+export interface Link {
+  patch: Record<string, unknown>;
+  href: string;
+}
+
+export interface SearchScope extends Helpers {
+  message: string | null;
+  query: string;
+  title: string;
+  showTitle: boolean;
+  /** 'search' or 'plp'. */
+  route: string;
+  total: number;
+  /**
+   * What is loaded, in order: the first page, then every page "show more"
+   * appended (`showMore`). There is no numbered page: a listing opens on its
+   * first page and grows.
+   */
+  results: Result[];
+  /** Search pages: results of the `quick` types (category, brand tiles), by type. */
+  quick: Record<string, Result[]>;
+  /**
+   * Text facets (range facets are in `ranges`). Values are links: href = the
+   * URL with the value toggled. No counts: the API returns none; `rank` is the
+   * value's place in the API's order (most frequent first); `empty`
+   * (`emptyValues`): none of the filtered results has it.
+   */
+  facets: ({
+    name: string;
+    label: string;
+    selected: number;
+    /** `match`: the group's search text finds it (always true without text). */
+    values: ({ value: string; label: string; checked: boolean; rank: number; match: boolean; empty?: boolean } & Link)[];
+    /**
+     * The group's search box (`facetGroups.search`, from `searchMin` values),
+     * else null: its `text`, how many values it `matches`, and `set(text)`
+     * (re-renders, no request; the count is announced once typing pauses).
+     * Label the input (`t('facetSearch', { facet })`).
+     */
+    search: { text: string; matches: number; set: (text: string) => void } | null;
+  } & FacetGroup)[];
+  /** The sidebar's groups in order: facet names (text and range) plus any group keys of the page's `layout`. */
+  layout: string[];
+  ranges: ({
+    name: string;
+    label: string;
+    min: number;
+    max: number;
+    from: number;
+    to: number;
+    active: boolean;
+    /** Unit shown next to the values (translations: units.<facet>). */
+    unit: string;
+    /** The slider's and the inputs' step (`rangeSteps`, default 1). */
+    step: number;
+    clear: Link;
+    /**
+     * Commit a range: one request (or, in a staged drawer, held until its
+     * Apply). An end at its bound is open (`null`); both at their bounds
+     * clears the filter. Call it when the shopper lets go (a slider's
+     * `change`, an input's `change` or Enter), never on every move.
+     */
+    set: (from: number | null, to: number | null) => void;
+    setFrom: (from: number | null) => void;
+    setTo: (to: number | null) => void;
+  } & FacetGroup)[];
+  flags: ({ id: string; label: string; checked: boolean } & Link)[];
+  /**
+   * Active filters, each with the link that removes it: its facet's `title`
+   * and its `value` ("Colour" and "White": render "Title: value"; a flag is its
+   * own title, `value` ''). `label` is the value alone for a facet value, and
+   * "Title: from–to" for a range.
+   */
+  chips: ({ kind: 'facet' | 'range' | 'flag'; name: string; title: string; value: string; label: string } & Link)[];
+  /** Removes every filter; null when none is active. */
+  clear: Link | null;
+  sorts: ({ value: string; label: string; selected: boolean } & Link)[];
+  sort: string;
+  /** Another page can be appended (`showMore`): the result set goes on. */
+  more: boolean;
+  /** Path of the page (for host links such as a login redirect). */
+  path: string;
+  facetsOpen: boolean;
+  /** The products are shown, their facets still on the way (a render follows): a template may hold their place. */
+  facetsPending: boolean;
+  /** The quick types are on their way, not waited for (they do not sit above the products here): a render follows with them. */
+  quickPending: boolean;
+  /** How the open filter drawer applies changes at this width (`facetsApply`). */
+  facetsApply: 'instant' | 'staged';
+  /** The open drawer holds changes not applied yet (staged): its apply button commits them. */
+  pending: boolean;
+  /**
+   * View state of this listing that is not in the URL (a group's "show more",
+   * a facet's search text), by the template's own keys. Empty on the server
+   * and on a new visit (another category or query); `setUi` re-renders.
+   */
+  ui: Record<string, unknown>;
+  setUi: (key: string, value: unknown) => void;
+  /** Click handler for a link: applies its patch client-side (in the server render: a no-op). */
+  go: (link: Link | null) => (e: Event) => void;
+  toggleFacet: (name: string, value: string) => void;
+  toggleFlag: (id: string) => void;
+  setSort: (sort: string) => void;
+  /**
+   * "Show more": the next page appended to `results`, from the cursor (one
+   * request; prefetched as the shopper nears the end, `prefetchNextPage`).
+   * No URL change and no history entry. Bind it as `@click=${s.showMore}` on
+   * a `<button data-lbx-more>` (`data-lbx-more`: intent on it prefetches the
+   * page too): from the keyboard, focus moves on to the first new tile.
+   */
+  showMore: (e?: Event) => void;
+  /** Range facet: set from–to (null = open end); both null clears it. */
+  setRange: (name: string, from: number | null, to: number | null) => void;
+}
+/**
+ * A facet group's accordion state (`facetGroups.open`): open or not, the
+ * toggle, and an `id` for the region it shows (put `aria-controls=${id}` on
+ * a `<button aria-expanded=${open}>` and `id=${id}` on the region).
+ */
+export interface FacetGroup {
+  id: string;
+  open: boolean;
+  toggle: () => void;
+}
+
+/**
+ * search-range-default: one range facet's dual-thumb slider and its two
+ * number inputs (`include('search-range-default', { range })`), kept in sync
+ * as the shopper moves them and committed on release (`range.set`).
+ */
+export interface SearchRangeScope extends SearchScope {
+  range: SearchScope['ranges'][number];
+}
+
+/** search-result-default: one result, `i` its position (0 = first). */
+export interface SearchResultScope extends SearchScope {
+  r: Result;
+  i: number;
+}
+
+export interface AutocompleteScope extends Helpers {
+  query: string;
+  /** One group per configured type that has results, in config order; `kind` is the type. */
+  groups: { kind: string; label: string; rows: { r: Result; i: number }[] }[];
+  /** Rows of one type ([] when none). */
+  byType: (type: string) => { r: Result; i: number }[];
+  count: number;
+  /** Index of the keyboard-selected row, -1 = none. */
+  active: number;
+  choose: (i: number) => void;
+  submitAll: () => void;
+  /**
+   * The search page of what is typed: the URL the site's search form would
+   * submit to ('' without a GET form). "Show all products" is a link to it
+   * (`href`), so it is a link to assistive technology, opens in a new tab, and
+   * is the dropdown's one tab stop: mark it `data-lbx-all` and Tab from the
+   * 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). */
+  state: 'idle' | 'results' | 'empty';
+  /** The phone sheet (full screen, viewport up to 600 px) rather than the panel under the input. */
+  sheet: boolean;
+  /** The panel is at least 1000 px wide: the top product has its own column. */
+  wide: boolean;
+  /** Query suggestions (pills). */
+  phrases: { r: Result; i: number }[];
+  /** One group per other non-product type with results, in config order (the list column; on a phone, tabs). */
+  lists: { kind: string; label: string; rows: { r: Result; i: number }[] }[];
+  /** The first product (the top product), or null. */
+  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). */
+  hover: (i: number, e?: PointerEvent) => void;
+  /** Pointer off that option: a selection the pointer made is cleared (a keyboard one stays). */
+  unhover: (i: number, e?: PointerEvent) => void;
+  /** The house design's config: `hero`, `productLayout`, and a product's optional fields. */
+  heroVariant: 'image' | 'spec';
+  productLayout: 'grid' | 'list';
+  /** A result's optional fields (`productFields`, `hero`): '' when it has none. */
+  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;
+  i: number;
+  /** How the house design draws the option: a pill, a list row, the top product, a product card or row, a phone row, a compact fallback card, a chip, a browse link. */
+  as?: 'pill' | 'row' | 'hero' | 'card' | 'line' | 'mhero' | 'mproduct' | 'mrow' | 'compact' | 'try' | 'browse';
+}
+
+export interface RecommenderScope extends Helpers {
+  results: Result[];
+  /** Popup only. */
+  close?: () => void;
+}
+export interface RecommenderResultScope extends RecommenderScope {
+  r: Result;
+  i: number;
+}