@wix/himalaya-cli 0.1498.0 → 0.1499.0

package/templates/branded-lite/tier5-src/_shared/himi-store-categories.ts

@@ -0,0 +1,102 @@
+// Store categories for the Branded Lite Shop chip row and the Home "Shop by category"
+// rail — one reader, so both list the same categories in the same order.
+//
+// Catalog V3 Categories first, V1 collections only when V3 THROWS (a legacy V1 site):
+// a V3 success with zero rows is an empty catalogue, and V1 on a V3 site answers 428.
+// Same rule as wix-spaces-collections; see the reasoning there.
+import { categoryImage, queryCollections, queryStoreCategories, type StoreCategoriesResponse, type StoreCategory, type WixCollection } from "@himalaya/wix-stores-collections";
+import { wixMediaUrl } from "@himalaya/wix-media";
+
+export interface StoreCategoryCard {
+  id: string;
+  name: string;
+  image: string;
+  hasImage: boolean;
+  noImage: boolean;
+}
+
+/** "All Products" is a Wix system collection — every product is in it, so it is
+ *  the Shop's own "All" chip, not a category a shopper picks. */
+const SYSTEM_NAMES = ["all products"];
+const SYSTEM_COLLECTION_IDS = ["00000000-000000-000000-000000000001"];
+
+function card(id: string, name: string, image: string): StoreCategoryCard {
+  return { id, name, image, hasImage: !!image, noImage: !image };
+}
+
+function fromCategory(c: StoreCategory): StoreCategoryCard {
+  return card(c.id ?? "", (c.name ?? "").trim(), categoryImage(c));
+}
+
+function fromCollection(c: WixCollection): StoreCategoryCard {
+  const raw = c as unknown as { id?: string; name?: string; media?: { mainMedia?: { image?: { url?: string }; thumbnail?: { url?: string } } } };
+  const media = raw.media?.mainMedia;
+  return card(raw.id ?? "", (raw.name ?? "").trim(), wixMediaUrl(media?.image?.url ?? media?.thumbnail?.url ?? ""));
+}
+
+function visible(rows: StoreCategoryCard[]): StoreCategoryCard[] {
+  const seen = new Set<string>();
+  return rows.filter((r) => {
+    if (!r.id || !r.name || SYSTEM_COLLECTION_IDS.includes(r.id) || SYSTEM_NAMES.includes(r.name.toLowerCase()) || seen.has(r.id)) return false;
+    seen.add(r.id);
+    return true;
+  });
+}
+
+const PAGE_SIZE = 50;
+const MAX_PAGES = 100;
+
+async function loadLegacyCategories(): Promise<StoreCategoryCard[]> {
+  const cards: StoreCategoryCard[] = [];
+  const seen = new Set<string>();
+  let offset = 0;
+  let total: number | undefined;
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const r = await queryCollections({ query: { paging: { limit: PAGE_SIZE, offset } } });
+    const rows = r.collections ?? [];
+    const reportedTotal = r.totalResults ?? r.metadata?.total;
+    if (reportedTotal != null) total = Math.max(total ?? 0, reportedTotal);
+    if (!rows.length) {
+      if (total != null && seen.size < total) throw new Error("Category pagination is incomplete");
+      return visible(cards);
+    }
+    const priorCount = seen.size;
+    rows.forEach(row => { if (row.id) seen.add(row.id); });
+    if (page > 0 && seen.size === priorCount) throw new Error("Category pagination made no progress");
+    cards.push(...rows.filter(c => c.visible !== false).map(fromCollection));
+    offset += rows.length;
+    if (total != null ? offset >= total : rows.length < PAGE_SIZE) {
+      if (total != null && seen.size < total) throw new Error("Category pagination is incomplete");
+      return visible(cards);
+    }
+  }
+  throw new Error("Category pagination exceeded the page limit");
+}
+
+/** The store's browsable categories in site order. Rejects incomplete reads so callers
+ *  can retain their last good catalog instead of invalidating a later category. */
+export async function loadStoreCategories(): Promise<StoreCategoryCard[]> {
+  let r: StoreCategoriesResponse;
+  try {
+    r = await queryStoreCategories(PAGE_SIZE);
+  } catch { return loadLegacyCategories(); /* Only the initial failure can identify a legacy V1 site. */ }
+  const cards: StoreCategoryCard[] = [];
+  const cursors = new Set<string>();
+  const seen = new Set<string>();
+  let total = 0;
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const categories = r.categories ?? [];
+    categories.forEach(c => { if (c.id) seen.add(c.id); });
+    total = Math.max(total, r.pagingMetadata?.total ?? 0);
+    cards.push(...categories.filter(c => c.visible !== false).map(fromCategory));
+    const next = r.pagingMetadata?.cursors?.next;
+    if (!next) {
+      if (seen.size < total) throw new Error("Category pagination is incomplete");
+      return visible(cards);
+    }
+    if (cursors.has(next)) throw new Error("Category pagination repeated a cursor");
+    cursors.add(next);
+    if (page + 1 < MAX_PAGES) r = await queryStoreCategories(PAGE_SIZE, next);
+  }
+  throw new Error("Category pagination exceeded the page limit");
+}

package/templates/branded-lite/tier5-src/_shared/himi-store-facets.ts

@@ -0,0 +1,478 @@
+// Shared store sort + filter + product card, for the Branded Lite Shop and Search
+// screens (ported from the BARE fashion template's bare-facets / bare-product-card).
+//
+// Each screen owns its SCOPE (a category, a search query) and fetches it; this module
+// only narrows and orders the rows inside that scope, on the device: a price bucket
+// and up to three of the store's own product options (Color, Size, …). The sort picker
+// and the filter panel are BottomSheets on the screen itself, not navigation modals —
+// a modal is a separate screen with its own worker, and state does not cross screens.
+//
+// Every user-facing string goes through copyParam / copyTemplate, so a copy pack
+// retitles them like any other worker string.
+import { normalizeFormattedPrice, productImage, productOptions, productPrice, type StoreProduct } from "./himi-store.js";
+import { readSavedProducts, toggleSavedProduct } from "./himi-store-saved.js";
+import { cleanTitle, initials } from "./himi-text.js";
+import { copyParam, copyTemplate } from "./himi-copy.js";
+import { formatCurrency } from "./engine-intl.js";
+
+/** The layout has no nested repeater inside a grid cell, so swatches ride in five
+ *  fixed slots; a product with more colours shows the first five. */
+const MAX_SWATCHES = 5;
+/** Rows revealed per page. The scope is already on the device; paging keeps the
+ *  first paint and every list diff small. */
+export const PAGE_SIZE = 24;
+
+export interface Chip { id: string; label: string }
+export interface Option extends Chip { selected: boolean; notSelected: boolean }
+export type Panel = "none" | "filters" | "sort";
+export type View = "grid" | "list";
+export type Density = "comfortable" | "compact";
+
+const SORT_IDS = ["recommended", "newest", "price_asc", "price_desc", "name_asc", "name_desc"] as const;
+const SORT_FALLBACK: Record<(typeof SORT_IDS)[number], string> = {
+  recommended: "Recommended",
+  newest: "Newest",
+  price_asc: "Price: low to high",
+  price_desc: "Price: high to low",
+  name_asc: "Name: A–Z",
+  name_desc: "Name: Z–A",
+};
+export function sorts(): Chip[] {
+  return SORT_IDS.map((id) => ({ id, label: copyParam(`storeFacets.sort.${id}`, SORT_FALLBACK[id]) }));
+}
+
+export interface ProductCard {
+  id: string;
+  name: string;
+  image: string;
+  hasImage: boolean;
+  noImage: boolean;
+  initial: string;
+  price: string;
+  /** The pre-discount price, struck through; "" when the product is not on sale. */
+  wasPrice: string;
+  onSale: boolean;
+  notOnSale: boolean;
+  saved: boolean;
+  notSaved: boolean;
+  swatch1: string; swatch2: string; swatch3: string; swatch4: string; swatch5: string;
+  swatch1Hidden: boolean; swatch2Hidden: boolean; swatch3Hidden: boolean; swatch4Hidden: boolean; swatch5Hidden: boolean;
+  noSwatches: boolean;
+  /** Hides the Sale tag / swatch row when it has nothing to show. */
+  noTagRow: boolean;
+  /** The Wix price before any App Store presentation rewrites `price`. */
+  commercePrice: string;
+  /** Original Wix sale metadata retained when App Store presentation hides it. */
+  commerceWasPrice?: string;
+  detailScreenId: string;
+}
+
+/** A product plus the facts the filters and sorts read. */
+export interface Row {
+  card: ProductCard;
+  price: number;
+  created: string;
+  name: string;
+  options: Record<string, string[]>;
+}
+
+/** The sort + filter + view slice of a screen's state. */
+export interface FacetState {
+  sort: string;
+  sortOptions: Option[];
+  sortLabel: string;
+  panel: Panel;
+  filtersOpen: boolean;
+  sortOpen: boolean;
+  filterLabel: string;
+  activeFilters: number;
+  noActiveFilters: boolean;
+  priceChips: Chip[];
+  priceSelected: string[];
+  hidePrice: boolean;
+  opt1Name: string; opt1Chips: Chip[]; opt1Selected: string[]; hideOpt1: boolean;
+  opt2Name: string; opt2Chips: Chip[]; opt2Selected: string[]; hideOpt2: boolean;
+  opt3Name: string; opt3Chips: Chip[]; opt3Selected: string[]; hideOpt3: boolean;
+  view: View;
+  density: Density;
+  hideGrid: boolean;
+  hideList: boolean;
+  hideComfortable: boolean;
+  hideCompact: boolean;
+  /** How many matched rows are revealed. */
+  visible: number;
+  /** Changes whenever filters or scope reset paging, so a reused visible count is a new cursor. */
+  cursorEpoch: number;
+  /** Every matched row's card, in sort order; `results` is its revealed prefix. */
+  matched: number;
+  results: ProductCard[];
+  /** Paging cursor: "more" while unrevealed rows remain, "" when exhausted. */
+  nextCursor: string;
+  noMore: boolean;
+  showLabel: string;
+}
+
+export const FACETS_BOOT: FacetState = {
+  sort: "recommended", sortOptions: [], sortLabel: "",
+  panel: "none", filtersOpen: false, sortOpen: false, filterLabel: "", activeFilters: 0, noActiveFilters: true,
+  priceChips: [], priceSelected: [], hidePrice: true,
+  opt1Name: "", opt1Chips: [], opt1Selected: [], hideOpt1: true,
+  opt2Name: "", opt2Chips: [], opt2Selected: [], hideOpt2: true,
+  opt3Name: "", opt3Chips: [], opt3Selected: [], hideOpt3: true,
+  view: "grid", density: "comfortable", hideGrid: false, hideList: true, hideComfortable: false, hideCompact: true,
+  visible: PAGE_SIZE, cursorEpoch: 0, matched: 0, results: [], nextCursor: "", noMore: true, showLabel: "",
+};
+
+// ---------------------------------------------------------------------------
+// Reading products — V1 and V3 shapes, defensively (the SDK type covers neither
+// sale price nor creation date; a missing field degrades to "not on sale", never NaN).
+// ---------------------------------------------------------------------------
+
+interface PriceBag { price?: number; discountedPrice?: number; currency?: string; formatted?: { price?: string; discountedPrice?: string } }
+interface V3Range { minValue?: { amount?: string; formattedAmount?: string; currency?: string } }
+interface RawPrices { price?: PriceBag; priceData?: PriceBag; actualPriceRange?: V3Range; compareAtPriceRange?: V3Range; currency?: string }
+
+/** Engine-safe money (engine-intl): watch runtimes have no ECMA-402. */
+export function money(n: number, currency: string | undefined): string {
+  if (!Number.isFinite(n)) return "";
+  return currency ? formatCurrency(n, currency) : n.toFixed(2);
+}
+
+/** Now / was / numeric price. V1 carries the sale on `discountedPrice`; V3 carries the
+ *  pre-discount figure on `compareAtPriceRange`. Wix's own formatted strings win. */
+function prices(p: StoreProduct): { now: string; was: string; value: number; currency?: string } {
+  const raw = p as unknown as RawPrices;
+  const bag = raw.price ?? raw.priceData;
+  if (bag && typeof bag.price === "number") {
+    const sale = bag.discountedPrice;
+    const discounted = typeof sale === "number" && sale < bag.price;
+    return discounted
+      ? { now: bag.formatted?.discountedPrice ? normalizeFormattedPrice(bag.formatted.discountedPrice) : money(sale, bag.currency), was: bag.formatted?.price ? normalizeFormattedPrice(bag.formatted.price) : money(bag.price, bag.currency), value: sale, currency: bag.currency }
+      : { now: productPrice(p), was: "", value: bag.price, currency: bag.currency };
+  }
+  const now = Number(raw.actualPriceRange?.minValue?.amount);
+  const was = Number(raw.compareAtPriceRange?.minValue?.amount);
+  const currency = raw.actualPriceRange?.minValue?.currency ?? raw.currency;
+  const discounted = Number.isFinite(now) && Number.isFinite(was) && now < was;
+  return {
+    now: productPrice(p),
+    was: discounted ? (raw.compareAtPriceRange?.minValue?.formattedAmount ? normalizeFormattedPrice(raw.compareAtPriceRange.minValue.formattedAmount) : money(was, currency)) : "",
+    value: Number.isFinite(now) ? now : 0,
+    currency,
+  };
+}
+
+export function currencyOf(p: StoreProduct): string | undefined {
+  return prices(p).currency;
+}
+
+function savedIds(): Set<string> {
+  try { return new Set(readSavedProducts().map((row) => row.id)); } catch { return new Set(); }
+}
+
+function swatchFields(hexes: string[], onSale: boolean) {
+  const s = hexes.filter(Boolean).slice(0, MAX_SWATCHES);
+  return {
+    noSwatches: s.length === 0, noTagRow: !onSale && s.length === 0,
+    swatch1: s[0] ?? "", swatch2: s[1] ?? "", swatch3: s[2] ?? "", swatch4: s[3] ?? "", swatch5: s[4] ?? "",
+    swatch1Hidden: !s[0], swatch2Hidden: !s[1], swatch3Hidden: !s[2], swatch4Hidden: !s[3], swatch5Hidden: !s[4],
+  };
+}
+
+export function productCard(p: StoreProduct, saved: Set<string> = savedIds()): ProductCard {
+  const { now, was } = prices(p);
+  const groups = productOptions(p);
+  const color = groups.find((g) => g.kind === "color");
+  const name = cleanTitle(p.name) || copyParam("storeFacets.untitled", "Product");
+  const image = productImage(p);
+  const id = p.id ?? "";
+  const onSale = !!was;
+  return {
+    id, name, image, hasImage: !!image, noImage: !image, initial: initials(name),
+    price: now, wasPrice: was, onSale, notOnSale: !onSale,
+    saved: saved.has(id), notSaved: !saved.has(id),
+    ...swatchFields((color?.choices ?? []).map((c) => c.colorCode ?? ""), onSale),
+    commercePrice: now,
+    detailScreenId: "himi_product",
+  };
+}
+
+/** Option name → choice labels, from either catalog. */
+function optionsOf(p: StoreProduct): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const g of productOptions(p)) {
+    const values = g.choices.map((c) => c.label.trim()).filter(Boolean);
+    if (g.name.trim() && values.length) out[g.name.trim()] = values;
+  }
+  return out;
+}
+
+export function toRow(p: StoreProduct, saved?: Set<string>): Row {
+  const card = productCard(p, saved);
+  const raw = p as unknown as { createdDate?: string; _createdDate?: string };
+  return { card, price: prices(p).value, created: raw.createdDate ?? raw._createdDate ?? "", name: card.name.toLowerCase(), options: optionsOf(p) };
+}
+
+export function toRows(products: StoreProduct[]): Row[] {
+  const saved = savedIds();
+  return products.map((p) => toRow(p, saved)).filter((r) => r.card.id);
+}
+
+// ---------------------------------------------------------------------------
+// Facets
+// ---------------------------------------------------------------------------
+
+/** Round price buckets over the scope's price span and cap the filter sheet at eight chips. */
+function priceBuckets(scope: Row[], currency: string | undefined): Chip[] {
+  const max = Math.max(0, ...scope.map((r) => r.price));
+  if (max <= 0) return [];
+  const ordinaryStep = max <= 100 ? 25 : max <= 200 ? 50 : max <= 500 ? 100 : 250;
+  const target = max / 8;
+  const magnitude = 10 ** Math.floor(Math.log10(target));
+  const normalized = target / magnitude;
+  const scaledStep = (normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10) * magnitude;
+  const step = Math.max(ordinaryStep, scaledStep);
+  const edges: number[] = [];
+  for (let e = step; e < max; e += step) edges.push(e);
+  if (edges.length === 0) return [];
+  const m = (n: number) => money(n, currency).replace(/\.00$/, "");
+  const chips: Chip[] = [{ id: `0-${edges[0]}`, label: copyTemplate("storeFacets.priceUnder", "Under {price}", { price: m(edges[0]) }) }];
+  for (let i = 1; i < edges.length; i++) chips.push({ id: `${edges[i - 1]}-${edges[i]}`, label: `${m(edges[i - 1])} – ${m(edges[i])}` });
+  chips.push({ id: `${edges[edges.length - 1]}-`, label: copyTemplate("storeFacets.priceOver", "Over {price}", { price: m(edges[edges.length - 1]) }) });
+  return chips;
+}
+
+/** A bucket's label from its own id, for a selection the current buckets no longer offer. */
+function bucketLabel(id: string, currency: string | undefined): string {
+  const [lo, hi] = id.split("-");
+  const m = (n: number) => money(n, currency).replace(/\.00$/, "");
+  if (!hi) return copyTemplate("storeFacets.priceOver", "Over {price}", { price: m(Number(lo) || 0) });
+  if (!Number(lo)) return copyTemplate("storeFacets.priceUnder", "Under {price}", { price: m(Number(hi)) });
+  return `${m(Number(lo))} – ${m(Number(hi))}`;
+}
+
+function inBucket(price: number, id: string): boolean {
+  const [lo, hi] = id.split("-");
+  return price >= (Number(lo) || 0) && (!hi ? true : price < Number(hi));
+}
+
+const SIZE_ORDER = ["XXS", "XS", "S", "M", "L", "XL", "XXL", "XXXL"];
+/** Clothing sizes in size order; anything else keeps the store's order. */
+function sortChoices(values: string[]): string[] {
+  const rank = (v: string) => SIZE_ORDER.indexOf(v.trim().toUpperCase());
+  return values.every((v) => rank(v) >= 0) ? values.slice().sort((a, b) => rank(a) - rank(b)) : values;
+}
+
+function optionFacets(scope: Row[]): { name: string; chips: Chip[] }[] {
+  const seen = new Map<string, Set<string>>();
+  for (const r of scope) {
+    for (const [name, values] of Object.entries(r.options)) {
+      const set = seen.get(name) ?? new Set<string>();
+      values.forEach((v) => set.add(v));
+      seen.set(name, set);
+    }
+  }
+  return [...seen.entries()].map(([name, set]) => ({
+    name,
+    chips: sortChoices([...set]).map((v) => ({ id: v, label: v })),
+  }));
+}
+
+const SLOT_KEYS = [
+  ["opt1Name", "opt1Chips", "opt1Selected", "hideOpt1"],
+  ["opt2Name", "opt2Chips", "opt2Selected", "hideOpt2"],
+  ["opt3Name", "opt3Chips", "opt3Selected", "hideOpt3"],
+] as const;
+
+/** Plain code-unit order, not localeCompare: watch runtimes have no ECMA-402. ISO dates
+ *  sort correctly this way, and names are already lower-cased. */
+const cmp = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+
+function sortRows(list: Row[], sort: string): Row[] {
+  const out = list.slice();
+  switch (sort) {
+    case "newest": return out.sort((a, b) => cmp(b.created, a.created));
+    case "price_asc": return out.sort((a, b) => a.price - b.price);
+    case "price_desc": return out.sort((a, b) => b.price - a.price);
+    case "name_asc": return out.sort((a, b) => cmp(a.name, b.name));
+    case "name_desc": return out.sort((a, b) => cmp(b.name, a.name));
+    default: return out;
+  }
+}
+
+export function option(c: Chip, on: boolean): Option {
+  return { ...c, selected: on, notSelected: !on };
+}
+
+export function countText(n: number): string {
+  return n === 1 ? copyParam("storeFacets.countOne", "1 product") : copyTemplate("storeFacets.countMany", "{count} products", { count: n });
+}
+
+/** Narrow `scope` by the selected filters, order it by the selected sort, and reveal
+ *  the first `visible` rows. Facets follow the scope, but a selection is the shopper's and
+ *  outlives it: the scope grows a page at a time and a search narrows it, so a price bucket
+ *  the new span no longer draws, or an option a narrowed scope no longer carries, keeps
+ *  filtering and stays on screen as a chip the shopper can turn off. Options are matched by
+ *  name, never by slot, so a facet moving to another slot keeps its selection. */
+export function applyFacets<T extends FacetState>(s: T, scope: Row[], currency: string | undefined): T {
+  const buckets = priceBuckets(scope, currency);
+  const priceSelected = s.priceSelected.slice();
+  const priceChips = [...buckets, ...priceSelected.filter((id) => !buckets.some((c) => c.id === id)).map((id) => ({ id, label: bucketLabel(id, currency) }))];
+  const chosen = new Map<string, string[]>();
+  SLOT_KEYS.forEach(([nameK, , selK]) => { if (s[nameK] && s[selK].length) chosen.set(s[nameK], s[selK]); });
+  const offered = optionFacets(scope).map((f) => {
+    const keep = (chosen.get(f.name) ?? []).filter((v) => !f.chips.some((c) => c.id === v));
+    return { name: f.name, chips: [...f.chips, ...keep.map((v) => ({ id: v, label: v }))] };
+  });
+  for (const [name, values] of chosen) {
+    if (!offered.some((f) => f.name === name)) offered.push({ name, chips: values.map((v) => ({ id: v, label: v })) });
+  }
+  // Slots are addressed by index (selectOpt1..3), so a facet keeps the slot it is in while
+  // it exists — a page landing under an open sheet never moves it under the shopper's finger.
+  // A selected facet always has a slot; free slots take the rest in first-seen order.
+  const byName = (name: string) => offered.find((f) => f.name === name);
+  const facets: ({ name: string; chips: Chip[] } | undefined)[] = SLOT_KEYS.map(([nameK]) => (s[nameK] ? byName(s[nameK]) : undefined));
+  const placed = () => new Set(facets.filter(Boolean).map((f) => f!.name));
+  for (const name of chosen.keys()) {
+    if (placed().has(name)) continue;
+    let slot = facets.findIndex((f) => !f);
+    if (slot < 0) slot = facets.map((f) => !!f && chosen.has(f.name)).lastIndexOf(false);
+    if (slot >= 0) facets[slot] = byName(name);
+  }
+  for (const f of offered) {
+    if (placed().has(f.name)) continue;
+    const slot = facets.findIndex((x) => !x);
+    if (slot < 0) break;
+    facets[slot] = f;
+  }
+  const next: T = { ...s, priceChips, priceSelected, hidePrice: priceChips.length === 0 };
+  SLOT_KEYS.forEach(([nameK, chipsK, selK, hideK], i) => {
+    const f = facets[i];
+    next[nameK] = f?.name ?? "";
+    next[chipsK] = f?.chips ?? [];
+    next[selK] = f ? chosen.get(f.name) ?? [] : [];
+    next[hideK] = !f;
+  });
+
+  const optionFilters = SLOT_KEYS
+    .map(([nameK, , selK]) => ({ name: next[nameK], values: next[selK] }))
+    .filter((f) => f.name && f.values.length);
+  const matched = scope.filter((r) =>
+    (priceSelected.length === 0 || priceSelected.some((id) => inBucket(r.price, id)))
+    && optionFilters.every((f) => (r.options[f.name] ?? []).some((v) => f.values.includes(v))));
+
+  const saved = savedIds();
+  const ordered = sortRows(matched, s.sort).map((r) => ({ ...r.card, saved: saved.has(r.card.id), notSaved: !saved.has(r.card.id) }));
+  const visible = Math.max(PAGE_SIZE, s.visible);
+  const active = priceSelected.length + optionFilters.reduce((n, f) => n + f.values.length, 0);
+  const choices = sorts();
+  next.matched = ordered.length;
+  next.visible = visible;
+  next.results = ordered.slice(0, visible);
+  // The renderer requests each cursor at most once. Include the filter/scope
+  // epoch as well as the visible page so a reset to page one is still new.
+  next.nextCursor = ordered.length > visible ? `${s.cursorEpoch}:${visible}` : "";
+  next.noMore = ordered.length <= visible;
+  next.sortOptions = choices.map((c) => option(c, c.id === s.sort));
+  next.sortLabel = (choices.find((c) => c.id === s.sort) ?? choices[0]).label;
+  next.filtersOpen = s.panel === "filters";
+  next.sortOpen = s.panel === "sort";
+  next.activeFilters = active;
+  next.noActiveFilters = active === 0;
+  next.filterLabel = active
+    ? copyTemplate("storeFacets.filterActive", "Filter ({count})", { count: active })
+    : copyParam("storeFacets.filter", "Filter");
+  next.showLabel = copyTemplate("storeFacets.show", "Show {count}", { count: countText(ordered.length) });
+  next.hideGrid = s.view !== "grid";
+  next.hideList = s.view !== "list";
+  next.hideComfortable = s.density !== "comfortable";
+  next.hideCompact = s.density !== "compact";
+  return next;
+}
+
+// ---------------------------------------------------------------------------
+// View preference (grid / list, comfortable / compact) — device KV, shared by Shop and
+// Search so the shopper's choice holds on both. A failed read or write never blocks.
+// ---------------------------------------------------------------------------
+
+type StorageLike = { getItem(key: string): string | null; setItem(key: string, value: string): void };
+const VIEW_KEY = "himi-store:view:v1";
+function storage(): StorageLike | undefined {
+  const host = globalThis as { himalaya?: { storage?: StorageLike }; localStorage?: StorageLike };
+  return host.himalaya?.storage ?? host.localStorage;
+}
+export function readViewPrefs(): { view: View; density: Density } {
+  try {
+    const raw = JSON.parse(storage()?.getItem(VIEW_KEY) ?? "{}") as { view?: unknown; density?: unknown };
+    return { view: raw.view === "list" ? "list" : "grid", density: raw.density === "compact" ? "compact" : "comfortable" };
+  } catch {
+    return { view: "grid", density: "comfortable" };
+  }
+}
+function writeViewPrefs(view: View, density: Density): void {
+  try { storage()?.setItem(VIEW_KEY, JSON.stringify({ view, density })); } catch { /* keep in memory */ }
+}
+
+// ---------------------------------------------------------------------------
+// Action argument readers + the shared actions
+// ---------------------------------------------------------------------------
+
+/** A tapped row's `{ id }` param — tolerant of a bare string. */
+export function idOf(arg: unknown): string {
+  return typeof arg === "string" ? arg : String((arg as { id?: unknown } | undefined)?.id ?? "");
+}
+
+/** A FilterChips `onChange` payload's selected ids. */
+export function selected(arg: unknown): string[] {
+  const ids = (arg as { selectedIds?: unknown } | undefined)?.selectedIds;
+  return Array.isArray(ids) ? ids.filter((x): x is string => typeof x === "string") : [];
+}
+
+function selectedId(arg: unknown): string {
+  return String((arg as { selectedId?: unknown } | undefined)?.selectedId ?? "");
+}
+
+/** Toggle one card's saved state in the shared saved-products store. Throws when
+ *  storage fails, so the caller keeps its state and the heart never lies. */
+export function toggleSaved(cards: ProductCard[], id: string): void {
+  const card = cards.find((c) => c.id === id);
+  if (!card) return;
+  toggleSavedProduct({ id: card.id, name: card.name, price: card.commercePrice || card.price, image: card.image,
+    wasPrice: card.commerceWasPrice ?? card.wasPrice,
+    swatches: [card.swatch1, card.swatch2, card.swatch3, card.swatch4, card.swatch5].filter(Boolean) });
+}
+
+/** The sort / filter / view actions, identical on every screen that has the sheets.
+ *  A change of sort or filter starts the reveal over at the first page. */
+export function facetActions<T extends FacetState>(derive: (s: T) => T) {
+  const first = (s: T) => ({ visible: PAGE_SIZE, cursorEpoch: s.cursorEpoch + 1 });
+  return {
+    // Choosing a sort applies it and closes the sort sheet.
+    sort: (s: T, arg?: unknown): T => {
+      const id = idOf(arg);
+      if (!SORT_IDS.includes(id as (typeof SORT_IDS)[number])) return s;
+      return derive({ ...s, ...first(s), sort: id, panel: "none" });
+    },
+    openFilters: (s: T): T => derive({ ...s, panel: "filters" }),
+    openSort: (s: T): T => derive({ ...s, panel: "sort" }),
+    closePanel: (s: T): T => derive({ ...s, panel: "none" }),
+    selectPrice: (s: T, arg?: unknown): T => derive({ ...s, ...first(s), priceSelected: selected(arg) }),
+    selectOpt1: (s: T, arg?: unknown): T => derive({ ...s, ...first(s), opt1Selected: selected(arg) }),
+    selectOpt2: (s: T, arg?: unknown): T => derive({ ...s, ...first(s), opt2Selected: selected(arg) }),
+    selectOpt3: (s: T, arg?: unknown): T => derive({ ...s, ...first(s), opt3Selected: selected(arg) }),
+    clearFilters: (s: T): T => derive({ ...s, ...first(s), priceSelected: [], opt1Selected: [], opt2Selected: [], opt3Selected: [] }),
+    showMore: (s: T): T => (s.noMore ? s : derive({ ...s, visible: s.visible + PAGE_SIZE })),
+    setView: (s: T, arg?: unknown): T => {
+      const view = selectedId(arg);
+      if (view !== "grid" && view !== "list") return s;
+      writeViewPrefs(view, s.density);
+      return derive({ ...s, view });
+    },
+    setDensity: (s: T, arg?: unknown): T => {
+      const density = selectedId(arg);
+      if (density !== "comfortable" && density !== "compact") return s;
+      writeViewPrefs(s.view, density);
+      return derive({ ...s, density });
+    },
+  };
+}