@luigisbox/luma 0.5.0 → 0.7.0

package/src/widgets/listing/query.ts

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

package/src/widgets/listing/stash.ts

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

package/src/widgets/listing/variants.ts

@@ -0,0 +1,111 @@
+// `variants` (a listing's config): the variant groups of the products a
+// listing shows, for a surface that collapses each group into one result
+// (/variants). Asked per result set (its request_key, `guid`) for the
+// products not asked yet: a page's as soon as it is here (the first, each
+// "show more", the pages of a Back restore without a stash of them at
+// once), at most MAX_IDS a request. Never waited for: the listing draws its
+// tiles, and again when the groups land (widgets/listing/element.ts).
+
+import type { Api, VariantGroup } from '../../api';
+import { reportError } from '../../core/health';
+import { lru } from '../../core/storage';
+import type { ListingConfig, ListingResult } from './query';
+
+/** /variants takes at most this many ids. */
+const MAX_IDS = 200;
+/** A failed request's products are asked again by a render this much later, not by every render in an outage. */
+const RETRY_MS = 5000;
+
+/** What a request needs of a result: its result set and its products (a page, or the pages loaded). */
+type Products = Pick<ListingResult, 'guid' | 'hits'>;
+
+interface Groups {
+  /** Ids asked for: answered, in flight, or failed less than RETRY_MS ago. */
+  asked: Set<string>;
+  /** The groups answered, by id: a new map whenever some land (a render compares it). */
+  got: ReadonlyMap<string, VariantGroup>;
+  /** Requests in flight. */
+  out: Set<Promise<void>>;
+}
+/** By result set (a request_key names one listing's request: its fields too), for the page's life (as the listing's result cache). */
+const sets = lru<Groups>(30, Infinity);
+const setOf = (guid: string) => {
+  let s = sets.get(guid);
+  if (!s) sets.set(guid, (s = { asked: new Set(), got: new Map(), out: new Set() }));
+  return s;
+};
+/**
+ * A group's shape, from the API or from storage: nothing else is kept, nothing
+ * coerced. Each sibling becomes a result once a template reads it (a hit's
+ * `@id` at least); a total `Number()` would throw on (`{ toString: null }`) is
+ * none. Anything else: no group, the tile as without one.
+ */
+const group = (g: any): VariantGroup | null =>
+  Array.isArray(g?.siblings) && Number.isFinite(g.total) && g.siblings.every((s: any) => typeof s?.['@id'] === 'string') ? { siblings: g.siblings, total: g.total } : null;
+
+/** The groups of `res`'s products answered so far: the same map until more land. */
+export const groupsOf = (res: Products) => sets.get(res.guid)?.got;
+
+/**
+ * Asks for the groups of `res`'s products not asked yet (all asked: no
+ * request). Settles once every request of its result set in flight has, and
+ * never rejects: what landed is in groupsOf(). An aborted request's
+ * products can be asked again at once (a host re-creating the listing
+ * renders it again in the same task), a failed one's (reported) after
+ * RETRY_MS.
+ */
+export const askVariants = (api: Api, cfg: ListingConfig, res: Products, signal?: AbortSignal): Promise<unknown> => {
+  if (!cfg.variants || !res.guid) return Promise.resolve();
+  const s = setOf(res.guid);
+  const ids = signal?.aborted ? [] : res.hits.map((h) => h['@id']).filter((id) => !s.asked.has(id));
+  for (let i = 0; i < ids.length; i += MAX_IDS) {
+    const chunk = ids.slice(i, i + MAX_IDS);
+    for (const id of chunk) s.asked.add(id);
+    const forget = () => chunk.forEach((id) => s.asked.delete(id));
+    signal?.addEventListener('abort', forget, { once: true });
+    const p: Promise<void> = api
+      .variants!(chunk, res.guid, cfg.variants.fields, signal)
+      .then(
+        (got) => {
+          const next = new Map(s.got);
+          for (const id of chunk) {
+            const g = group(got[id]);
+            if (g) next.set(id, g);
+          }
+          s.got = next;
+        },
+        (e) => {
+          if ((e as Error)?.name === 'AbortError') return;
+          reportError('variants', e);
+          setTimeout(forget, RETRY_MS);
+        },
+      )
+      .finally(() => (s.out.delete(p), signal?.removeEventListener('abort', forget)));
+    s.out.add(p);
+  }
+  return Promise.all(s.out);
+};
+
+/** The groups landed of `res`'s products, for its Back stash: the restored page draws them at once. */
+export const stashGroups = (res: Products) => {
+  const got = groupsOf(res);
+  return res.hits.flatMap((h): [string, VariantGroup][] => {
+    const g = got?.get(h['@id']);
+    return g ? [[h['@id'], g]] : [];
+  });
+};
+
+/** A Back stash's groups (storage: each checked) as answered for `res`'s products. */
+export const seedGroups = (res: Products, stashed: unknown) => {
+  if (!res.guid || !Array.isArray(stashed)) return;
+  const s = setOf(res.guid);
+  const ids = new Set(res.hits.map((h) => h['@id']));
+  const next = new Map(s.got);
+  for (const e of stashed) {
+    const g = ids.has(e?.[0]) ? group(e[1]) : null;
+    if (!g) continue;
+    next.set(e[0], g);
+    s.asked.add(e[0]);
+  }
+  s.got = next;
+};

package/src/widgets/listing/view.ts

@@ -9,8 +9,9 @@
 // bundle turns a click on one into a client-side update (`go(patch)`).
 
 import type { WidgetContext } from '../../main';
-import type { Helpers, SearchScope } from '../../types';
-import { SEARCH } from '../../core/features';
+import type { VariantGroup } from '../../api';
+import type { Helpers, Result, SearchScope } from '../../types';
+import { SEARCH, VARIANTS } from '../../core/features';
 import { fold } from '../../core/fold';
 import { navigable } from '../../core/result';
 import { hasMore, parseRange, type ListingConfig, type ListingResult } from './query';
@@ -62,6 +63,8 @@ export interface ListingView {
   searchGroup?: (name: string, text: string) => void;
   /** A range committed (`setRange` of the scope): from–to, `null` an open end. */
   setRange?: (name: string, from: number | null, to: number | null) => void;
+  /** `variants`: the products' variant groups landed so far, by `@id` (./variants.ts). */
+  variants?: ReadonlyMap<string, VariantGroup>;
 }
 
 /** A DOM id for a facet group of a route: `lbx-plp-g-lbx_price` (names may hold ':' or spaces). */
@@ -83,6 +86,34 @@ const resultOf = <R>(make: (h: any) => R) => {
   };
 };
 
+/**
+ * `variants`: a hit's Result with its variant group (`r.variants`), the same
+ * object for the same hit and group: a tile is drawn again when its group
+ * lands, and only then. Its own computed attributes (`r.c`), which may read
+ * the group.
+ */
+const grouped = VARIANTS ? new WeakMap<VariantGroup, { h: object; r: Result }>() : null;
+export const withGroups = (make: (h: any) => Result, groups: ReadonlyMap<string, VariantGroup>) => {
+  const plain = resultOf(make);
+  return (h: Record<string, any>): Result => {
+    const g = groups.get(h['@id']);
+    if (!g) return plain(h);
+    const was = grouped!.get(g);
+    if (was?.h === h) return was.r;
+    const r = make(h);
+    // Its siblings as results once a template reads them (up to 100 a tile, computed attributes each).
+    let siblings: Result[] | undefined;
+    r.variants = {
+      get siblings() {
+        return (siblings ??= g.siblings.map(make));
+      },
+      total: g.total,
+    };
+    grouped!.set(g, { h, r });
+    return r;
+  };
+};
+
 /** A group's search: the text folded (case, diacritics: "size" finds "Size", "creme" "Crème"), as a substring. */
 const matcher = (text: string) => {
   const t = fold(text.trim());
@@ -222,7 +253,7 @@ export const listingData = (ctx: Pick<WidgetContext<ListingConfig>, 'config' | '
     title: q.title,
     showTitle: !!cfg.showTitle,
     total: res.total,
-    results: res.hits.map(resultOf(ctx.result)),
+    results: res.hits.map(VARIANTS && view.variants ? withGroups(ctx.result, view.variants) : resultOf(ctx.result)),
     quick: SEARCH ? Object.fromEntries(Object.entries(res.quick ?? {}).map(([k, hs]) => [k, hs.map(ctx.result).filter(navigable)])) : {},
     facets,
     ranges,

package/src/widgets/search/first.ts

@@ -3,7 +3,8 @@
 // entry: the query code (route, query building, the answer's shaping) is in
 // lbx-nav, which the listing imports anyway, and not on pages without a listing
 // (the API client's requests are in lbx-core, which the listing loads too).
-import { getApi } from '../../api';
+import { getApi, type Page } from '../../api';
+import { VARIANTS } from '../../core/features';
 import type { GlobalConfigType, SearchConfigType } from '../../types';
 import { quickChannel } from '../listing/flow';
 import { listingQuery, type ListingResult } from '../listing/query';
@@ -11,5 +12,12 @@ import { searchRoute } from './route';
 
 export const searchFirst = (g: GlobalConfigType, cfg: SearchConfigType, url: URL, onProducts?: (r: ListingResult) => void) => {
   const route = searchRoute(cfg);
-  return listingQuery(getApi(g), g, cfg as any, route, route.resolve(url) as any, undefined, undefined, onProducts, quickChannel(route.id));
+  const api = getApi(g);
+  // `variants`: the first page's groups with its facets, as the listing's own
+  // request asks them (the listing finds them asked). Imported here, not
+  // statically: its module is lbx-listing's, which lbx-nav (search while
+  // typing on any page, this boot request) must not wait for. Its chunk
+  // failing is the listing's to report, not an unhandled rejection on the site.
+  const ask = VARIANTS && cfg.variants ? (f: Page) => void import('../listing/variants').then((m) => m.askVariants(api, cfg as any, f), () => {}) : undefined;
+  return listingQuery(api, g, cfg as any, route, route.resolve(url) as any, undefined, undefined, onProducts, quickChannel(route.id), ask);
 };