@wix/himalaya-cli 0.1582.0 → 0.1584.0

package/templates/branded-lite/tier5-src/himi-booking-services/index.ts

@@ -1,22 +1,32 @@
 // Tier-5 bundle: himi-booking — customer-facing services catalog.
 //
-// Visitors browse the site's Wix Bookings services in the business's own order (the
-// order of the site's Book Online page), narrowed by category chips and a name search.
-// Each row carries what the service record has: photo, name, tagline, a Class or
-// Course tag, and duration and price in the same words as the service screen. "Book"
-// shows only where online booking by time is possible. The worker exposes explicit
-// flags so the descriptor renders loading, empty, error and loaded states without raw
-// JavaScript conditions in the screen tree.
+// Visitors browse every Wix Bookings service of the site, grouped by category under a small
+// title, in the business's own order (the order of the site's Book Online page). The category
+// chips are anchors, not filters: a tap scrolls the list to its category's title, and the chip
+// of the category at the top of the list lights up while the member scrolls. A name search
+// keeps the grouping. With two or more locations a pin limits the list to the services offered
+// at one location; the choice is shared with the Agenda and Choose Time screens. Each row
+// carries what the service record has: photo, name, tagline, a Class or Course tag, and
+// duration and price in the same words as the service screen. "Book" shows only where online
+// booking by time is possible. The worker exposes explicit flags so the descriptor renders
+// loading, empty, error and loaded states without raw JavaScript conditions in the screen tree.
+import { defineService } from "@himalaya/state";
 import { defineBackendCollection } from "../_shared/collection-service.js";
 import { COLLECTION_CHROME_MIN_ITEMS } from "../_shared/collection-contract.js";
 import { queryServiceCategories, queryServices, type WixService } from "@himalaya/wix-bookings";
 import { categoryName, courseDatesText, courseHasEnded, serviceDurationText, servicePriceLine, type BookingLabel } from "../_shared/himi-bookings.js";
 import { formatServicePrice } from "../_shared/wix-service-price.js";
 import { getAll, upsert, type DbEntity } from "@himalaya/local-db";
+import { get as getAppInfo } from "@himalaya/app-info";
+import { atLeast } from "../_shared/member-account-routes.js";
 import { initials } from "../_shared/himi-text.js";
 import { copyParam, copyTemplate } from "../_shared/himi-copy.js";
 import { offsetPage } from "../_shared/offset-page.js";
 import { wixMediaUrl } from "@himalaya/wix-media";
+import {
+  distinctChoices, effectiveLocation, locationMenu, readSharedLocation, serviceLocationChoices, writeSharedLocation,
+  type LocationChoice, type LocationOptionRow, type SharedLocation,
+} from "../_shared/booking-location.js";
 
 // Offline-first (data-offline): the services catalog is a public read-through —
 // paint the last-synced rows from the on-device store first (instant, works
@@ -52,6 +62,8 @@ interface Row {
   hasImage: boolean;
   noImage: boolean;
   category: string;
+  /** The category's identity: its Wix id, else "name:<name>"; "" for a service with no category. */
+  categoryKey: string;
   /** The category's place in the business's order; -1 when the record has none. */
   categoryOrder: number;
   /** The row's place in the business's order when it was read (the offline copy is sorted by it). */
@@ -74,8 +86,13 @@ interface Row {
   bookA11y: string;
   /** The row's spoken name: name, type tag, tagline and meta. */
   a11y: string;
+  /** Where the service is offered, as location choices (`serviceLocationChoices`). */
+  locations: LocationChoice[];
 }
 
+/** A row of the bound list: a category's title, or a service under it. */
+type ListRow = Row & { isSection: boolean; notSection: boolean; sectionTitle: string };
+
 interface CategoryChip { id: string; label: string }
 
 interface S {
@@ -87,8 +104,12 @@ interface S {
   loadingMore?: boolean;
   total?: number;
   fromCache?: boolean;
+  /** The services read (Branded Web prints `results` as it is): every location, no titles. */
   all: Row[];
   results: Row[];
+  /** What the Services list shows: each category's title row, then its services, at the chosen
+   *  location. Title rows are `cat:<category id>`, service rows the service id. */
+  listRows: ListRow[];
   emptyText: string;
   countLabel: string;
   errored: boolean;
@@ -97,23 +118,39 @@ interface S {
   notLoading: boolean;
   hasResults: boolean;
   noEmpty: boolean;
+  /** One anchor chip per category the list shows, in the list's order. */
   categoryChips: CategoryChip[];
   hideCategories: boolean;
+  /** The chip of the category at the top of the list (or the one tapped last). */
+  activeCategory: string;
+  /** "<row id>|<n>": the list scrolls that row to the top when this changes; "" scrolls nothing. */
+  scrollTo: string;
   /** Loading with no rows to show: the skeleton stands in for the list. */
   hideRows: boolean;
-  /** The no-match line: a search miss, or a chosen category with nothing in it. */
+  /** The no-match line of a search. */
   noMatchText: string;
-  /** Which way out the no-match block offers: Clear Search (a query), else Show All. */
+  /** A search is typed: the no-match block offers Clear Search. */
   hasQuery: boolean;
   noQuery: boolean;
   /** The chips' spoken name, from the copy pack (a descriptor accessibilityLabel is not rewritten). */
   categoriesLabel: string;
-}
-
-function strOf(arg: unknown): string {
-  if (typeof arg === "string") return arg;
-  const a = arg as { value?: string; text?: string } | undefined;
-  return a?.value ?? a?.text ?? "";
+  // The location picker (two or more locations only): `locationMenu()` in booking-location.ts.
+  locationOptions: LocationOptionRow[];
+  locationLabel: string;
+  locationA11y: string;
+  hasLocationMenu: boolean;
+  noLocationMenu: boolean;
+  locationActive: boolean;
+  noLocationActive: boolean;
+  locationSheetOpen: boolean;
+  /** A location is chosen and none of the services read is offered there. */
+  locationEmpty: boolean;
+  notLocationEmpty: boolean;
+  locationEmptyText: string;
+  /** The location this list was last limited to, kept with the state so a cold boot shows the
+   *  same list before the shared choice is read again. */
+  chosenLocationId: string;
+  chosenLocationLabel: string;
 }
 
 /** The list's copy keys for the shared price, duration and course-date lines. */
@@ -183,6 +220,23 @@ function categoryOrder(value: unknown): number {
   return typeof order === "number" && Number.isFinite(order) ? order : -1;
 }
 
+/** A category's identity: its id, else its name (a string category, a name-only reference). */
+function categoryKeyOf(id: unknown, name: string): string {
+  if (!name) return "";
+  return typeof id === "string" && id ? id : `name:${name}`;
+}
+
+/** The service's category. A Wix Bookings v2 service has ONE category (`category`), so a service
+ *  shows under its one category. Should a payload ever carry several (`categories`), the rule is
+ *  the same on every surface: the first one only, never a copy of the row under each. */
+function categoryOf(service: WixService): { key: string; name: string; order: number } {
+  const raw = service as { category?: unknown; categories?: unknown };
+  const first = raw.category ?? (Array.isArray(raw.categories) ? raw.categories[0] : undefined);
+  const name = categoryName(first);
+  const id = first && typeof first === "object" ? (first as { id?: unknown }).id : undefined;
+  return { key: categoryKeyOf(id, name), name, order: categoryOrder(first) };
+}
+
 function typeTagOf(type: unknown): string {
   if (type === "CLASS") return copyParam("services.tagClass", "Class");
   if (type === "COURSE") return copyParam("services.tagCourse", "Course");
@@ -226,11 +280,13 @@ function norm(service: WixService): Row {
   const tagline = typeof service.tagLine === "string" ? service.tagLine.trim() : "";
   const canBook = service.onlineBooking?.enabled !== false && !isCourse;
   const request = service.onlineBooking?.requireManualApproval === true;
+  const category = categoryOf(service);
   return {
     id,
     name,
-    category: categoryName(service.category),
-    categoryOrder: categoryOrder(service.category),
+    category: category.name,
+    categoryKey: category.key,
+    categoryOrder: category.order,
     subtitle: bits.length ? bits.join(" · ") : "Choose a time",
     // WS-C — canonical param-less detail screenId; the descriptor row binds the
     // separate `id` field as a first-class nav param (no more baked suffixes).
@@ -250,6 +306,7 @@ function norm(service: WixService): Row {
     bookCta: bookCtaFor(request),
     bookA11y: bookLabel(name, request),
     a11y: spokenName({ name, typeTag, endedText, tagline, meta }),
+    locations: serviceLocationChoices((service as { locations?: unknown }).locations),
   };
 }
 
@@ -263,6 +320,7 @@ function withRowDefaults(row: Partial<Row>, shownEnded?: string): Row {
   const tagline = str(row.tagline);
   const meta = str(row.meta);
   const canBook = row.canBook === true;
+  const category = str(row.category);
   const courseSchedule = row.courseSchedule;
   const endedText = courseSchedule && courseHasEnded({ schedule: courseSchedule }, Date.now())
     ? copyParam("services.ended", "Ended", shownEnded || str(row.endedText) || "Ended") : "";
@@ -276,7 +334,8 @@ function withRowDefaults(row: Partial<Row>, shownEnded?: string): Row {
     image,
     hasImage: !!image,
     noImage: !image,
-    category: str(row.category),
+    category,
+    categoryKey: str(row.categoryKey) || categoryKeyOf("", category),
     categoryOrder: typeof row.categoryOrder === "number" ? row.categoryOrder : -1,
     tagline,
     typeTag,
@@ -287,50 +346,49 @@ function withRowDefaults(row: Partial<Row>, shownEnded?: string): Row {
     noBook: !canBook,
     bookCta: str(row.bookCta) || bookCtaFor(false),
     bookA11y: str(row.bookA11y) || bookLabel(name),
+    // Recomputed, not restored: a course that ended since the row was saved says so.
     a11y: spokenName({ name, typeTag, endedText, tagline, meta }),
+    locations: Array.isArray(row.locations) ? row.locations.filter((l) => !!l && typeof l.key === "string" && !!l.key) : [],
   };
 }
 
-// ---- Category chips ---------------------------------------------------------------
+// ---- Categories -------------------------------------------------------------------
 // The site's categories, read once per worker in the background — never holding back the
-// services page — in the owner's order. When the read lands, the chips repaint. A failed read
-// is tried again at most once a minute. Until it succeeds, the categories of the latest rows
-// loaded with no filter and no query stand in, ordered by `category.sortOrder`.
-let siteCategories: string[] | undefined;
+// services read — give the business's order of the groups. When the read lands, the list
+// repaints. A failed read is tried again at most once a minute. Until it succeeds, the groups
+// follow each row's `category.sortOrder` (the order the services read already sorts by).
+interface SiteCategory { key: string; name: string }
+let siteCategories: SiteCategory[] | undefined;
 let categoriesInFlight = false;
 let categoriesFailedAt = 0;
 const CATEGORY_RETRY_MS = 60_000;
-const rowCategories = new Map<string, number>();
 /** A restored Ended label bridges only the first live page after boot, because an app that sends no
  *  copy pack gives no sign that none is coming: after it, current copy (pack or stock) decides. */
 let restoredEndedBridge = true;
 
-/** Repaint the chips only, on the state already shown. Re-deriving from the query controller
- *  would publish its working state, which a revalidation deliberately holds back (a restored list
- *  would flash to the skeleton, or shrink to page 1, until every page is back). */
+/** The title row of the services with no category (last, and only beside other groups). */
+const UNCATEGORIZED = "cat:none";
+const sectionIdOf = (key: string): string => (key ? `cat:${encodeURIComponent(key)}` : UNCATEGORIZED);
+
+/** Repaint on the state already shown. Re-deriving from the query controller would publish its
+ *  working state, which a revalidation deliberately holds back (a restored list would flash to
+ *  the skeleton, or shrink to page 1, until every page is back). */
 function republish(): void {
   (svc as unknown as { categoriesLanded?: () => unknown }).categoriesLanded?.();
 }
 
-function withChips(s: S): S {
-  const collection = (s as unknown as { collection?: { filter?: unknown; query?: unknown; hideChrome?: unknown } }).collection;
-  const filter = typeof collection?.filter === "string" ? collection.filter : "all";
-  // Restored rows stand in for the categories when the read failed before any live page — only
-  // rows of the whole list (no category, no query), or the stand-in would be one category.
-  const whole = filter === "all" && !(typeof collection?.query === "string" && collection.query.trim());
-  // Not while a load is out: the rows on screen may still be a previous search's.
-  if (!siteCategories?.length && rowCategories.size === 0 && whole && s.isLoading !== true) rememberRowCategories((s.results ?? []).map((row) => withRowDefaults(row)));
-  const chips = categoryChips(filter);
-  return { ...s, categoryChips: chips, hideCategories: collection?.hideChrome === true || (chips.length < 3 && !filter.startsWith("value:")) };
-}
-
 function startCategoriesRead(): void {
   if (siteCategories || categoriesInFlight) return;
   if (categoriesFailedAt && Date.now() - categoriesFailedAt < CATEGORY_RETRY_MS) return;
   categoriesInFlight = true;
   queryServiceCategories().then((res) => {
-    const names = (res.categories ?? []).map((category) => categoryName(category)).filter(Boolean);
-    siteCategories = [...new Set(names)];
+    const out: SiteCategory[] = [];
+    for (const category of res.categories ?? []) {
+      const name = categoryName(category);
+      const key = categoryKeyOf(category.id, name);
+      if (key && !out.some((c) => c.key === key)) out.push({ key, name });
+    }
+    siteCategories = out;
   }, () => {
     categoriesFailedAt = Date.now();
   }).then(() => {
@@ -339,42 +397,173 @@ function startCategoriesRead(): void {
   });
 }
 
-function rememberRowCategories(rows: Row[]): void {
+interface Section { id: string; title: string; rows: Row[] }
+
+/** The rows grouped by their one category: the business's order of categories (the categories
+ *  read, else each row's category sortOrder, else first seen), each group in the rows' own order,
+ *  and the services with no category last. A category with no row has no group. */
+function sectionsOf(rows: Row[]): Section[] {
+  const site = siteCategories ?? [];
+  const groups = new Map<string, Section & { rank: number; order: number; seen: number }>();
   for (const row of rows) {
-    if (row.category && !rowCategories.has(row.category)) rowCategories.set(row.category, row.categoryOrder);
+    // A row that names a category the read also has joins it, whatever shape its reference had.
+    let index = row.categoryKey ? site.findIndex((c) => c.key === row.categoryKey) : -1;
+    if (index < 0 && row.category) index = site.findIndex((c) => c.name === row.category);
+    const key = index >= 0 ? site[index].key : row.categoryKey;
+    const id = sectionIdOf(key);
+    let group = groups.get(id);
+    if (!group) {
+      group = { id, title: index >= 0 ? site[index].name : row.category, rows: [], rank: index, order: row.categoryOrder, seen: groups.size };
+      groups.set(id, group);
+    }
+    group.rows.push(row);
   }
+  const place = (g: { id: string; rank: number; order: number; seen: number }): number[] =>
+    g.id === UNCATEGORIZED ? [2, 0, g.seen] : g.rank >= 0 ? [0, g.rank, g.seen] : [1, g.order < 0 ? Number.MAX_SAFE_INTEGER : g.order, g.seen];
+  return [...groups.values()]
+    .sort((a, b) => { const pa = place(a), pb = place(b); return pa[0] - pb[0] || pa[1] - pb[1] || pa[2] - pb[2]; })
+    .map(({ id, title, rows: groupRows }) => ({
+      id, title: id === UNCATEGORIZED ? copyParam("services.otherCategory", "Other services") : title, rows: groupRows,
+    }));
+}
+
+const BLANK_ROW: Omit<Row, "id"> = {
+  name: "", subtitle: "", detailScreenId: "", initial: "", image: "", hasImage: false, noImage: true,
+  category: "", categoryKey: "", categoryOrder: -1, tagline: "", typeTag: "", noTypeTag: true, endedText: "", meta: "",
+  canBook: false, noBook: true, bookCta: "", bookA11y: "", a11y: "", locations: [],
+};
+
+// ---- Anchors -------------------------------------------------------------------------
+// A chip tap scrolls the list to its category's title row (`scrollTo`, a new "|n" each tap, so a
+// second tap on the same chip scrolls again) and lights that chip. The list reports the row at
+// its top when the MEMBER scrolls (`topItemChanged`); its category's chip lights up.
+let activeCategory = "";
+/** The member has tapped a chip or scrolled the list: the lit chip is theirs. Until then it is the
+ *  first category, whatever order the rows arrived in — the catalog's first rows can come before
+ *  the business's category order, and the first chip of THAT list stayed lit over the real top. */
+let activeChosen = false;
+let scrollTarget = "";
+let jumps = 0;
+let quietUntil = 0;
+/** How long a jump the worker asked for takes to settle: a top-row report inside it is the jump's
+ *  own (the renderers suppress those, this is the belt to their braces). */
+const JUMP_SETTLE_MS = 900;
+
+// ---- Location ------------------------------------------------------------------------
+/** The member's choice (shared with Agenda and Choose Time through the on-device store). */
+let chosenLocation: SharedLocation = { id: "", label: "" };
+/** Every location the whole catalog is offered at: a search narrows the rows, never the menu. */
+let catalogLocations: LocationChoice[] = [];
+let locationSheet = false;
+
+/** The first runtime whose LazyList jumps to a row (`scrollToItemPath`) and reports the row at its
+ *  top (`onTopItemChange`). An older native binary ignores both, so its chips would light without
+ *  moving the list: they are hidden there, and the grouped list with its titles stays. Web is served
+ *  with the release's own renderer, so it always has them. */
+export const ANCHORS_MIN_BINARY = "1.8.0";
+let anchorsOk: boolean | undefined;
+async function anchorsSupported(): Promise<boolean> {
+  const info = await getAppInfo().catch(() => undefined);
+  if (!info || (info.platform !== "ios" && info.platform !== "android" && info.platform !== "macos")) return true;
+  return atLeast(info.binaryVersion, ANCHORS_MIN_BINARY);
 }
 
-function categoryNames(): string[] {
-  if (siteCategories?.length) return siteCategories;
-  const listed = [...rowCategories.entries()].map(([name, order], index) => ({ name, order, index }));
-  listed.sort((a, b) => (a.order < 0 ? Infinity : a.order) - (b.order < 0 ? Infinity : b.order) || a.index - b.index);
-  return listed.map((entry) => entry.name);
+async function readLocation(): Promise<void> {
+  chosenLocation = await readSharedLocation();
+  anchorsOk ??= await anchorsSupported();
 }
 
-function categoryChips(filter: string): CategoryChip[] {
-  const names = categoryNames();
-  const chosen = filter.startsWith("value:") ? filter.slice(6) : "";
-  // The chosen category stays, so the customer can always go back to All.
-  const all = chosen && !names.includes(chosen) ? [...names, chosen] : names;
-  return [{ id: "all", label: copyParam("services.allCategories", "All") }, ...all.map((name) => ({ id: `value:${name}`, label: name }))];
+function argOf(p: unknown, key: string): string {
+  const a = p as Record<string, unknown> | undefined;
+  const v = a?.[key] ?? (a?.args as Record<string, unknown> | undefined)?.[key] ?? (a?.params as Record<string, unknown> | undefined)?.[key];
+  return typeof v === "string" ? v.trim() : "";
 }
 
+/** Everything the list shows, rebuilt from the rows read and the module's choices. */
+function display(s: S): S {
+  const rows = Array.isArray(s.results) ? s.results : [];
+  const loading = s.isLoading === true;
+  const errored = s.errored === true;
+  const choices = catalogLocations;
+  const locationKey = effectiveLocation(choices, chosenLocation.id);
+  const shown = locationKey ? rows.filter((row) => (row.locations ?? []).some((l) => l.key === locationKey)) : rows;
+  const sections = sectionsOf(shown);
+  // Titles once there is something to tell apart: never over a list with no category at all.
+  const titled = sections.length > 1 || (sections.length === 1 && sections[0].id !== UNCATEGORIZED);
+  const listRows: ListRow[] = sections.flatMap((section) => [
+    ...(titled ? [{ ...BLANK_ROW, id: section.id, isSection: true, notSection: false, sectionTitle: section.title }] : []),
+    ...section.rows.map((row) => ({ ...row, isSection: false, notSection: true, sectionTitle: "" })),
+  ]);
+  const chips = titled && sections.length >= 2 ? sections.map((section) => ({ id: section.id, label: section.title })) : [];
+  // No chips (a reload in flight, a single group): the lit chip waits for the list to come back.
+  if (chips.length && (!activeChosen || !chips.some((chip) => chip.id === activeCategory))) activeCategory = chips[0]!.id;
+  const target = scrollTarget.split("|")[0];
+  if (scrollTarget && !listRows.some((row) => row.id === target)) scrollTarget = "";
+  // The same rule as the shared `collection.hideChrome`: no search or chips over a short,
+  // un-narrowed list, an empty source, or before the first rows arrive.
+  const narrowed = s.hasQuery === true;
+  const sourceEmpty = !loading && !errored && rows.length === 0 && !narrowed;
+  const hideChrome = (!narrowed && !s.nextCursor && rows.length < COLLECTION_CHROME_MIN_ITEMS) || sourceEmpty
+    || ((loading || errored) && rows.length === 0 && !narrowed);
+  const locationEmpty = !loading && !errored && !!locationKey && rows.length > 0 && shown.length === 0;
+  const menu = locationMenu(choices, chosenLocation.id);
+  return {
+    ...s,
+    listRows,
+    categoryChips: chips,
+    hideCategories: hideChrome || chips.length < 2 || anchorsOk === false,
+    activeCategory,
+    scrollTo: scrollTarget,
+    ...menu,
+    locationSheetOpen: locationSheet && menu.hasLocationMenu,
+    locationEmpty,
+    notLocationEmpty: !locationEmpty,
+    locationEmptyText: locationEmpty ? copyTemplate("services.locationEmptyText", "There are no services at {location}.", { location: menu.locationLabel }) : "",
+    chosenLocationId: chosenLocation.id,
+    chosenLocationLabel: chosenLocation.label,
+  };
+}
+
+/** The section a row of the list belongs to: a title row is its own; a service, its group's. */
+function sectionOfRow(listRows: ListRow[], id: string): string {
+  let section = "";
+  for (const row of listRows) {
+    if (row.isSection) section = row.id;
+    if (row.id === id) return section;
+  }
+  return "";
+}
+
+const PAGE = 100;
+/** Grouping and anchors need the whole catalog: every page is read up front, up to this many
+ *  (1,000 services). A bigger catalog keeps a cursor, and the list pages the rest as before. */
+const MAX_PAGES = 10;
+
+// A cold boot takes these from `state`, never from the last run: a jump the last run asked for
+// would scroll the restored list on its first frame, and a sheet would reopen.
+const registerServices = ((name: string, def: Parameters<typeof defineService>[1]) =>
+  defineService(name, { ...def, notHydrated: ["scrollTo", "locationSheetOpen"], perVisit: ["scrollTo", "locationSheetOpen"] } as never)) as typeof defineService;
+
 const svc = defineBackendCollection<S, Row>("himiBookingServices", {
+  register: registerServices,
   restorePagesOnLoad: true,
   onLoad() {
     // Copy is stashed before this hook. Repaint restored labels immediately, even
     // when the background query holds the old page through a slow or failed read.
     (svc as unknown as { normalizeRestored?: () => unknown }).normalizeRestored?.();
   },
-  state: { status: "loading", query: "", all: [], results: [], emptyText: "", countLabel: "", errored: false,
+  state: { status: "loading", query: "", all: [], results: [], listRows: [], emptyText: "", countLabel: "", errored: false,
     notErrored: true, isLoading: true, notLoading: false, hasResults: false, noEmpty: true,
-    categoryChips: [], hideCategories: true, hideRows: false, noMatchText: "", hasQuery: false, noQuery: true, categoriesLabel: "" },
+    categoryChips: [], hideCategories: true, activeCategory: "", scrollTo: "", hideRows: false, noMatchText: "", hasQuery: false, noQuery: true,
+    categoriesLabel: "", locationOptions: [], locationLabel: "", locationA11y: "", hasLocationMenu: false, noLocationMenu: true,
+    locationActive: false, noLocationActive: true, locationSheetOpen: false, locationEmpty: false, notLocationEmpty: true,
+    locationEmptyText: "", chosenLocationId: "", chosenLocationLabel: "" },
   source: {
     id: row => row.id,
     errorMessage: () => copyParam("services.errorText", "Services could not be loaded."),
     async cached(criteria) {
       if (criteria.query || criteria.filter !== "all" || criteria.sort !== "default") return undefined;
+      await readLocation();
       return { items: await readCachedRows(), nextCursor: "", metadata: { fromCache: true } };
     },
     async fetch(criteria, cursor) {
@@ -386,25 +575,105 @@ const svc = defineBackendCollection<S, Row>("himiBookingServices", {
       const sort = criteria.sort === "default"
         ? [{ fieldName: "category.sortOrder", order: "ASC" as const }, { fieldName: "sortOrder", order: "ASC" as const }, { fieldName: "id", order: "ASC" as const }]
         : [{ fieldName: "name", order: criteria.sort === "za" ? "DESC" as const : "ASC" as const }, { fieldName: "id", order: "ASC" as const }];
-      if (!cursor) startCategoriesRead();
-      const res = await queryServices({ query: { filter, paging: { limit: 50, offset: Number(cursor || 0) }, sort } });
-      const raw = res.services ?? [];
-      const offset = Number(cursor || 0);
-      const items = raw.filter(row => !!row.id).map((service, index) => ({ ...norm(service), position: offset + index }));
+      if (!cursor) {
+        startCategoriesRead();
+        // Read again on every load and appearance: Agenda or Choose Time may have changed it.
+        await readLocation();
+        // The menu offers the whole catalog's places, and a search or category read lists only its
+        // matches: a cold boot into a persisted search takes them from the device's copy of the list.
+        if (catalogLocations.length === 0 && (criteria.query || criteria.filter !== "all")) {
+          catalogLocations = distinctChoices((await readCachedRows()).flatMap((row) => row.locations));
+        }
+      }
+      const items: Row[] = [];
+      let offset = Number(cursor || 0);
+      let next = "";
+      let total: number | undefined;
+      for (let page = 0; page < MAX_PAGES; page++) {
+        let res;
+        try {
+          res = await queryServices({ query: { filter, paging: { limit: PAGE, offset }, sort } });
+        } catch (error) {
+          // A later page failing keeps the pages already read: the list pages the rest (and says
+          // so if it fails again). The first page failing is the read failing.
+          if (page === 0) throw error;
+          next = String(offset);
+          break;
+        }
+        const raw = res.services ?? [];
+        items.push(...raw.filter(row => !!row.id).map((service, index) => ({ ...norm(service), position: offset + index })));
+        const paged = offsetPage(String(offset), raw.length, PAGE, res.pagingMetadata);
+        next = paged.nextCursor;
+        total = paged.total ?? total;
+        if (!next) break;
+        offset = Number(next);
+      }
       // Only a read of the whole list in the business's order is saved: the offline copy is read
       // back as that list, and a narrowed or re-sorted read's positions are not positions in it.
       if (!criteria.query && !criteria.filter.startsWith("value:") && criteria.sort === "default") await writeCachedRows(items);
-      return { items, ...offsetPage(cursor, raw.length, 50, res.pagingMetadata), metadata: { fromCache: false } };
+      return { items, nextCursor: next, ...(total === undefined ? {} : { total }), metadata: { fromCache: false } };
     },
   },
   actions: {
-    categoriesLanded: (s) => withChips(s),
-    // Normalize old snapshots and refresh Ended/copy before revalidation settles.
-    // A missing `noBook` must never show Book on a restored course.
+    categoriesLanded: (s) => display(s),
+    // A snapshot saved by an older worker comes back without the new row fields; a missing
+    // `noBook` would show Book on a course until the live read. Give restored rows the defaults,
+    // and the restored list its groups and the location it was limited to.
     normalizeRestored: (s) => {
-      const rows = Array.isArray(s.results) ? s.results : [];
-      const fixed = rows.map((row) => withRowDefaults(row as Partial<Row>));
-      return { ...s, results: fixed, all: fixed };
+      const rows = (Array.isArray(s.results) ? s.results : []).map((row) => withRowDefaults(row as Partial<Row>));
+      if (typeof s.chosenLocationId === "string" && s.chosenLocationId) {
+        chosenLocation = { id: s.chosenLocationId, label: typeof s.chosenLocationLabel === "string" ? s.chosenLocationLabel : "" };
+      }
+      if (!s.query) catalogLocations = distinctChoices(rows.flatMap((row) => row.locations));
+      return display({ ...s, results: rows, all: rows });
+    },
+    // A chip: scroll to its category and light it. Re-tapping the lit chip deselects it on every
+    // renderer (`selectedIds: []`): that is the same chip again, so it scrolls again.
+    scrollToCategory: (s, p) => {
+      const ids = (p as { selectedIds?: unknown } | undefined)?.selectedIds
+        ?? ((p as { args?: { selectedIds?: unknown } } | undefined)?.args?.selectedIds);
+      const picked = Array.isArray(ids) && typeof ids[0] === "string" ? ids[0] : activeCategory;
+      if (!(s.categoryChips ?? []).some((chip) => chip.id === picked)) return s;
+      activeCategory = picked;
+      activeChosen = true;
+      scrollTarget = `${picked}|${++jumps}`;
+      quietUntil = Date.now() + JUMP_SETTLE_MS;
+      return display(s);
+    },
+    // The row at the top of the list after the member scrolled: its category's chip lights up.
+    topItemChanged: (s, p) => {
+      if (Date.now() < quietUntil) return s;
+      const rows = Array.isArray(s.listRows) ? s.listRows : [];
+      // A search miss or an empty location has no category to follow.
+      if (!rows.some((row) => !row.isSection)) return s;
+      const section = sectionOfRow(rows, argOf(p, "id"));
+      if (!section || !(s.categoryChips ?? []).some((chip) => chip.id === section)) return s;
+      activeCategory = section;
+      activeChosen = true;
+      // The member has moved on from the last jump: a re-render never scrolls back to it.
+      scrollTarget = "";
+      return display(s);
+    },
+    openLocations: (s) => {
+      locationSheet = true;
+      return display(s);
+    },
+    closeLocations: (s) => {
+      if (!locationSheet) return s;
+      locationSheet = false;
+      return display(s);
+    },
+    // A row of the location sheet: "" is every location. Agenda and Choose Time read it too.
+    selectLocation: async (s, p) => {
+      const id = argOf(p, "locationId");
+      const choice = catalogLocations.find((c) => c.key === id);
+      chosenLocation = id && choice ? { id, label: choice.label } : { id: "", label: "" };
+      locationSheet = false;
+      scrollTarget = "";
+      // Not awaited (it never throws): the state returned is this dispatch's own, so no later commit
+      // — a revalidation landing during a native round trip — is overwritten by it.
+      void writeSharedLocation(chosenLocation);
+      return display(s);
     },
   },
   apply(s, page) {
@@ -415,27 +684,17 @@ const svc = defineBackendCollection<S, Row>("himiBookingServices", {
     const shown = new Map((restoredEndedBridge && Array.isArray(s.results) ? s.results : []).map((row) => [row.id, row.endedText]));
     const rows = page.items.map((item) => withRowDefaults(item, shown.get(item.id)));
     if (page.metadata?.fromCache === false && !loading && !errored) restoredEndedBridge = false;
-    // The stand-in categories come from the accepted rows of the whole list (a superseded
-    // response never reaches apply): a live page replaces them, the device's copy only fills a gap.
-    if (!page.criteria.query && page.criteria.filter === "all" && rows.length > 0) {
-      // Only a settled page: while a page reloads, the list may still hold the previous
-      // (searched) rows under the new criteria.
-      if (page.metadata?.fromCache !== true) { if (!loading) { rowCategories.clear(); rememberRowCategories(rows); } }
-      else if (rowCategories.size === 0) rememberRowCategories(rows);
-    }
-    // The same rule as the shared `collection.hideChrome`: no search or chips over a short,
-    // un-narrowed list, an empty source, or before the first rows arrive.
     const filtered = page.criteria.filter.startsWith("value:");
     const hasQuery = !!page.criteria.query.trim();
-    const narrowed = hasQuery || filtered;
-    const sourceEmpty = !loading && !errored && rows.length === 0 && !narrowed;
-    const hideChrome = (!narrowed && !page.nextCursor && rows.length < COLLECTION_CHROME_MIN_ITEMS) || sourceEmpty
-      || ((loading || errored) && rows.length === 0 && !narrowed);
-    const chips = categoryChips(page.criteria.filter);
-    return { ...s, status: loading ? "loading" : "ready", query: page.criteria.query, all: rows, results: rows,
-      categoryChips: chips, hideCategories: hideChrome || (chips.length < 3 && !filtered), hideRows: loading && rows.length === 0,
-      noMatchText: hasQuery ? copyParam("services.noMatchText", "No services match your search.")
-        : copyParam("services.categoryEmptyText", "There are no services in this category."),
+    // The menu offers every location of the whole catalog: a settled live read replaces it, the
+    // device's copy only fills a gap (a superseded response never reaches apply).
+    if (!hasQuery && !filtered && rows.length > 0) {
+      const live = page.metadata?.fromCache !== true;
+      if ((live && !loading) || catalogLocations.length === 0) catalogLocations = distinctChoices(rows.flatMap((row) => row.locations));
+    }
+    return display({ ...s, status: loading ? "loading" : "ready", query: page.criteria.query, all: rows, results: rows,
+      hideRows: loading && rows.length === 0,
+      noMatchText: copyParam("services.noMatchText", "No services match your search."),
       hasQuery, noQuery: !hasQuery, categoriesLabel: copyParam("services.categoriesLabel", "Service categories"),
       nextCursor: page.nextCursor, complete: page.complete, total: page.total, loadingMore: page.loadingMore, pageError: page.pageError,
       fromCache: page.metadata?.fromCache === true, errored, notErrored: !errored, isLoading: loading, notLoading: !loading,
@@ -444,17 +703,17 @@ const svc = defineBackendCollection<S, Row>("himiBookingServices", {
       emptyText: errored ? copyParam("services.errorText", "Services could not be loaded.")
         : loading || rows.length > 0 ? ""
         : hasQuery ? copyParam("services.noMatchText", "No services match your search.")
-        : filtered ? copyParam("services.categoryEmptyText", "There are no services in this category.")
-        : copyParam("services.emptyText", "There are no services to book yet.") };
+        : copyParam("services.emptyText", "There are no services to book yet.") });
   },
 });
-// The old chrome could persist a "saved" filter (there is no Saved chip now) or an A-Z sort
-// (there is no Refine now): both go back to the business's own view before the first read.
+// The old chrome could persist a "saved" filter (there is no Saved chip now), a category filter
+// (the chips are anchors now, the list always shows every category) or an A-Z sort (there is no
+// Refine now): all go back to the business's own whole view before the first read.
 type Retired = { getState?: () => { collection?: { filter?: unknown; sort?: unknown } };
   collectionFilter?: (arg: unknown) => unknown; collectionSort?: (arg: unknown) => unknown };
 const retired = svc as unknown as Retired;
 const persisted = retired.getState?.()?.collection;
-if (persisted?.filter === "saved") void retired.collectionFilter?.({ selectedIds: ["all"] });
+if (typeof persisted?.filter === "string" && persisted.filter !== "all") void retired.collectionFilter?.({ selectedIds: ["all"] });
 if (typeof persisted?.sort === "string" && persisted.sort !== "default") void retired.collectionSort?.({ selectedId: "default" });
 svc.load();
 export { svc };