@wix/himalaya-cli 0.1613.0 → 0.1615.0

package/templates/salon-spa/tier5-src/_shared/collection-service.ts

@@ -0,0 +1,400 @@
+import { defineService as register, type ServiceDefinition } from '@himalaya/state';
+import { COLLECTIONS, COLLECTION_CHROME_MIN_ITEMS, initialCollection, normalizeCollection, projectCollection, collectionId, collectionActionsLabel, type CollectionRow } from './collection-contract.js';
+import { localPreferences, type PreferenceRuntime } from './local-preferences.js';
+import { copyParam, stashCopy } from './himi-copy.js';
+import { createCollectionQuery, type CollectionQuerySource, type CollectionQueryState } from './collection-query.js';
+
+export interface CollectionSaving {
+  read(): string[];
+  write(ids: string[], rows: Record<string, unknown>[]): void;
+}
+type State = Record<string, unknown>;
+interface BackendCollection {
+  restorePagesOnLoad?: boolean;
+  /** Sees the load action's argument (the screen's onAppear params) BEFORE the query runs. A returned
+   *  `{ filter, sort }` resets the criteria for that load (a screen that always opens on one view). */
+  onLoad?(arg: unknown): CollectionCriteriaReset | void;
+  controller: ReturnType<typeof createCollectionQuery<CollectionRow>>;
+  apply(state: State, page: CollectionQueryState<CollectionRow>): State;
+}
+/** A filter and a sort set together (`collectionCriteria`, `onLoad`). Values the collection's contract does
+ *  not list are ignored. */
+export interface CollectionCriteriaReset { filter?: string; sort?: string; query?: string }
+type Reducer = (s: State, ...args: unknown[]) => State | undefined | Promise<State | undefined>;
+const object = (x: unknown): State => x && typeof x === 'object' && !Array.isArray(x) ? x as State : {};
+const str = (arg: unknown, key: string): string => typeof arg === 'string' ? arg : String(object(arg)[key] ?? '');
+
+/** The toolbar count line — "12 dishes", or "3 of 12 dishes" while a filter narrows the list.
+ *
+ *  It used to read "12 / 12 loaded" and "2 / 2 results" ([branded-lite-qa] #3002): the numbers
+ *  described the implementation (a client-side filter over a fetched page) rather than what the
+ *  customer is looking at, and the slash-and-suffix wrapped onto two lines on web. When the
+ *  backend total is unknown the count shown is simply what is shown; the "Load more" button is
+ *  what says there is more. */
+export function collectionSummary(o: { shown: number; loaded: number; total?: number; backend?: boolean; noun?: [string, string] }): string {
+  const [one, many] = o.noun ?? [copyParam('collection.itemOne', 'item'), copyParam('collection.itemMany', 'items')];
+  const whole = o.backend ? (typeof o.total === 'number' ? o.total : o.shown) : o.loaded;
+  const noun = (whole === 1 ? one : many);
+  return o.shown < whole ? `${o.shown} ${copyParam('collection.of', 'of')} ${whole} ${noun}` : `${o.shown} ${o.shown === 1 ? one : many}`;
+}
+
+/** Opt-in decorator. Domain reducers remain authoritative; collection preferences
+ * survive reducers which replace their entire state, including async refreshes. */
+export function decorateCollection(name: string, def: { state: State; actions?: Record<string, Reducer> }, saving?: CollectionSaving, backend?: BackendCollection) {
+  const config = COLLECTIONS[name];
+  if (!config) return def;
+  const runtime = (globalThis as { himalaya?: PreferenceRuntime }).himalaya;
+  let instanceId = '';
+  if (config.instanceInput) {
+    let instance = runtime?.input?.[config.instanceInput];
+    try { if (typeof instance === 'string') instance = JSON.parse(instance); } catch { instance = undefined; }
+    const id = object(instance).id;
+    if (typeof id === 'string' && id.length > 0 && id.length <= 256) instanceId = id;
+  }
+  // Dynamic collections must never read the shared service-level key. Without
+  // a configured instance identity they remain session-only.
+  const persisted = localPreferences(`collection.${name}${config.instanceInput ? `.${encodeURIComponent(instanceId)}` : ''}`,
+    value => normalizeCollection(config, value), config.instanceInput && !instanceId ? {} : runtime);
+  let prefs = persisted.read();
+  let lastUndo: string[] | undefined;
+  let generation = 0;
+  let previewId = '';
+  let filtersPresented = false;
+  let viewName = '';
+  let viewMessage = '';
+  let saveMessage = '';
+  const syncSaved = () => {
+    if (!saving) return;
+    try {
+      const ids = saving.read();
+      if (JSON.stringify(ids) !== JSON.stringify(prefs.savedIds)) lastUndo = undefined;
+      prefs.savedIds = ids;
+    } catch { prefs.savedIds = []; }
+  };
+  /** Navigation can open a collection in a useful, reviewable context. Keep
+   * this input additive and constrained to the same criteria the collection UI
+   * can select; arbitrary route values must never become backend filters. */
+  /** Labels of the worker-listed filter choices (`filterValuesFrom`), minus the "All" row. */
+  const listedFilters = (state: State): string[] => config.filterValuesFrom && Array.isArray(state[config.filterValuesFrom])
+    ? (state[config.filterValuesFrom] as unknown[]).flatMap(row => {
+      const r = row && typeof row === 'object' ? row as Record<string, unknown> : {};
+      return typeof r.label === 'string' && r.id !== '' ? [r.label] : [];
+    })
+    : [];
+  let pendingFilter = '';
+  const applyNavigationCriteria = (arg: unknown, state: State): boolean => {
+    const input = object(arg);
+    let changed = false;
+    if (Object.prototype.hasOwnProperty.call(input, 'collectionQuery')) {
+      prefs.query = String(input.collectionQuery ?? '').slice(0, 256);
+      changed = true;
+    }
+    if (Object.prototype.hasOwnProperty.call(input, 'collectionSort')) {
+      const sort = String(input.collectionSort ?? '');
+      if (sort === 'default' || sort === 'az' || sort === 'za') { prefs.sort = sort; changed = true; }
+    }
+    if (Object.prototype.hasOwnProperty.call(input, 'collectionFilter')) {
+      const filter = String(input.collectionFilter ?? '');
+      const configured = config.filterValues ?? [];
+      const rows = Array.isArray(state[config.rows]) ? state[config.rows] as CollectionRow[] : [];
+      const derived = config.filter ? rows.map(row => String(row[config.filter!] ?? '')).filter(Boolean) : [];
+      const known = listedFilters(state);
+      const allowed = filter === 'all' || filter === 'saved' ||
+        (filter.startsWith('value:') && [...configured, ...derived, ...known].includes(filter.slice(6)));
+      if (allowed) { prefs.filter = filter; changed = true; }
+      // A worker-listed choice (e.g. a blog category) may not have loaded yet at boot:
+      // hold it and settle it against the list once the list arrives, instead of
+      // discarding a valid deep link before load().
+      else if (filter.startsWith('value:') && config.filterValuesFrom && known.length === 0) pendingFilter = filter;
+    }
+    if (changed) {
+      prefs.selectedIds = [];
+      prefs.selecting = false;
+      persisted.write(prefs);
+    }
+    return changed;
+  };
+  // A worker's module-level `svc.load()` has no action argument. Navigation
+  // params are injected into `himalaya.input` before module evaluation, so
+  // apply the same constrained criteria here before that boot request reads
+  // `prefs`. The load wrapper below still handles hosts that pass criteria as
+  // an explicit action argument.
+  applyNavigationCriteria(runtime?.input, def.state);
+  const derive = (s: State): State => {
+    syncSaved();
+    const rows = Array.isArray(s[config.rows]) ? (s[config.rows] as CollectionRow[]).filter(x => x && typeof x === 'object') : [];
+    const known = listedFilters(s);
+    if (pendingFilter && known.length) {
+      if (known.includes(pendingFilter.slice(6))) { prefs.filter = pendingFilter; persisted.write(prefs); }
+      pendingFilter = '';
+    }
+    const projected = projectCollection(rows, config, prefs, !!backend && config.backendQuery === true, known);
+    projected.items.forEach(row => {
+      row.collectionSelectLabel = row.collectionSelected ? copyParam('collection.selected', 'Selected') : copyParam('collection.select', 'Select');
+      // the save toggle names the action it WILL take for this row. The
+      // old static "Save / unsave" made the owner work out the row's state.
+      row.collectionSaveLabel = row.collectionSaved ? copyParam('collection.unsave', 'Remove from saved') : copyParam('collection.save', 'Save');
+      row.collectionActionsLabel = collectionActionsLabel(String(row.collectionTitle ?? ''),
+        copyParam('collection.itemActionsFor', 'Actions for {title}'), copyParam('collection.itemActions', 'Item actions'));
+    });
+    if (previewId && !rows.some(row => collectionId(row) === previewId)) previewId = '';
+    const filterChoices = [{ id: 'all', label: copyParam('collection.all', 'All') }, { id: 'saved', label: copyParam('collection.saved', 'Saved') },
+      ...projected.filters.map(label => ({ id: `value:${label}`, label: copyParam(`collection.filter.${label}`, label) }))];
+    const loading = s.status === 'loading' || s.isLoading === true;
+    // Older domain reducers expose `errored` rather than `isErrored`; backend
+    // adapters can also intentionally keep their display status "ready" while
+    // the query controller carries a recoverable failure. Treat each shape as
+    // one collection state so the shared UI never renders a blank catalog.
+    const backendState = backend?.controller.getState();
+    const provisional = backendState?.provisional === true;
+    const errored = s.status === 'error' || s.isErrored === true || s.errored === true || backendState?.status === 'error';
+    const domainError = typeof s.error === 'string' ? s.error.trim() : '';
+    const queryError = typeof backendState?.error === 'string' ? backendState.error.trim() : '';
+    // Some domains carry their failure sentence in `emptyText` (portfolio, podcasts);
+    // the screen folds that node into this block, so keep the domain's own words.
+    const domainEmptyError = errored && typeof s.emptyText === 'string' ? s.emptyText.trim() : '';
+    const errorMessage = queryError || domainError || domainEmptyError || copyParam('collection.loadError', 'This collection could not load. Try again.');
+    const canRetry = !!backend || typeof def.actions?.refresh === 'function' || typeof def.actions?.load === 'function' || typeof def.actions?.collectionRetry === 'function';
+    // Wix refused the visitor: retrying cannot help, signing in can.
+    const signInRequired = errored && s.signInRequired === true;
+    // "the source has nothing" and "your filter matched nothing" are
+    // different states. Only the second may offer "Clear filters", and the list chrome
+    // (view, refine, chips, counter, search) means nothing over a source with no rows.
+    // Loaded-row collections hold the whole source in `rows`, so zero rows IS an empty
+    // source. A backend query returns only matches, so zero rows is source-empty only
+    // when nothing narrowed it.
+    // Anything the customer (or the domain) narrowed the result by. While narrowed, zero rows
+    // is "your filter matched nothing" and the controls that got them here must stay.
+    // The DOMAIN's own filter (config.narrowedBy, e.g. blog category) narrowed the rows: the
+    // domain owns that empty state and its clear action. The shared "Clear filters" block
+    // cannot reset a domain filter, so it never shows for one.
+    const domainNarrowed = !!config.narrowedBy && !!s[config.narrowedBy];
+    // A default view is what the screen opens on; anything else is the member's own
+    // narrowing, which keeps the chrome (and the Clear that undoes it) on screen.
+    // "All" and the collection's own default (e.g. Upcoming) are both un-narrowed: Clear
+    // resets to "All", so showing it on either would offer a reset that changes nothing.
+    const narrowed = !!prefs.query.trim() || (prefs.filter !== 'all' && prefs.filter !== initialCollection(config).filter) || domainNarrowed;
+    const sourceEmpty = !loading && !errored && rows.length === 0 &&
+      (!(backend && config.backendQuery) || !narrowed) && !domainNarrowed;
+    const emptySourceText = (typeof s.emptyText === 'string' && s.emptyText.trim()) || copyParam('collection.emptySource', 'Nothing here yet');
+    // Chrome is noise over a small un-narrowed list (fewer than COLLECTION_CHROME_MIN_ITEMS
+    // records, no further page), over an empty source, and before the FIRST load or an
+    // un-narrowed failure. A re-query while typing keeps it (and the search field's focus).
+    const hideChrome = (!narrowed && !s.nextCursor && projected.loaded < COLLECTION_CHROME_MIN_ITEMS)
+      || sourceEmpty || ((loading || errored) && rows.length === 0 && !narrowed);
+    // Kept with the state, so a cold boot restored from disk shows its last page and revalidates behind it.
+    const collectionShown = backend?.controller.shownPage();
+    return { ...s, ...(backend ? { collectionShown: collectionShown ?? null } : {}), collection: { ...prefs, ...projected,
+      hideChrome, noActiveCriteria: !narrowed,
+      viewName, viewMessage, saveMessage, noSavedViews: prefs.savedViews.length === 0,
+      cursor: s.pageError === true || s.loadingMore === true ? '' : s.nextCursor,
+      noMore: !s.nextCursor || s.pageError === true || s.loadingMore === true,
+      noPageError: s.pageError !== true,
+      // Rows read from the device ahead of the live read are shown as they are: "saved offline" is what stays on
+      // screen when the live read failed, not a first visit that is still loading.
+      noOffline: s.fromCache !== true || provisional,
+      noError: !errored,
+      noRetry: !canRetry || signInRequired,
+      noSignIn: !signInRequired,
+      errorTitle: signInRequired ? copyParam('collection.signInTitle', 'Sign in to see this') : copyParam('collection.loadErrorTitle', 'This collection could not load'),
+      errorMessage,
+      // A skeleton only with nothing to show: a search re-running over the rows on screen keeps them.
+      noLoading: !loading || rows.length > 0,
+      // De-dup against a domain that paints its OWN empty block (screen-kit emptyBlock is
+      // gated on the domain's top-level `noEmpty`): only one empty state ever shows.
+      noEmptySource: !sourceEmpty || s.noEmpty === false,
+      emptySourceText,
+      hideList: prefs.view !== 'list', hideGrid: prefs.view !== 'grid',
+      hideComfortable: prefs.density !== 'comfortable', hideCompact: prefs.density !== 'compact',
+      selectingLabel: prefs.selecting ? copyParam('collection.done', 'Done') : copyParam('collection.select', 'Select'),
+      noSelection: !prefs.selecting, noUndo: !lastUndo,
+      cannotSaveSelected: !prefs.selectedIds.length || prefs.selectedIds.some(id => !rows.some(row => collectionId(row) === id)),
+      filtersPresented, previewPresented: !!previewId, preview: projected.items.filter(row => row.collectionId === previewId),
+      persistenceLabel: persisted.available ? copyParam('collection.onDevice', 'Saved on this device') : copyParam('collection.sessionOnly', 'Choices last for this session'),
+      noEmpty: loading || errored || sourceEmpty || domainNarrowed || projected.items.length > 0,
+      summary: backend && config.backendQuery && s.fromCache && !provisional
+        ? copyParam('collection.cached', 'Saved offline · may be outdated')
+        : collectionSummary({ shown: projected.items.length, loaded: projected.loaded, backend: !!(backend && config.backendQuery),
+          total: typeof s.total === 'number' ? s.total : undefined, noun: config.countNoun
+            ? [copyParam(`collection.${name}.countOne`, config.countNoun[0]), copyParam(`collection.${name}.countMany`, config.countNoun[1])] : undefined }),
+      selectedSummary: `${prefs.selectedIds.length} ${copyParam('collection.selected', 'selected')}`,
+      filterChoices,
+      chips: config.filterValues ? filterChoices.filter(choice => ['all', 'saved', prefs.filter].includes(choice.id)) : filterChoices,
+    } };
+  };
+  const actions: Record<string, Reducer> = {};
+  for (const [key, action] of Object.entries(def.actions ?? {})) {
+    actions[key] = (s, ...args) => {
+      stashCopy(args[0]);
+      const actionState = key === 'load' && applyNavigationCriteria(args[0], s) ? derive(s) : s;
+      // A new data request invalidates older requests, while presentation actions
+      // are merged at completion rather than clobbered by a captured state.
+      const isQuery = /^(load|refresh|retry|search|clearSearch)$/.test(key);
+      const previous = generation;
+      const revision = isQuery ? ++generation : generation;
+      const result = action(actionState, ...args);
+      const finish = (next: State | undefined) => {
+        // Some workers deduplicate onAppear against their boot request and return
+        // the identical state. A no-op must not supersede the request it joined.
+        if (next === actionState) {
+          if (revision !== generation) return undefined;
+          if (isQuery) generation = previous;
+          return derive(next);
+        }
+        return next === undefined || revision !== generation ? undefined : derive(next);
+      };
+      return result && typeof (result as Promise<unknown>).then === 'function'
+        ? (result as Promise<State | undefined>).then(finish) : finish(result as State | undefined);
+    };
+  }
+  const change = (update: (arg: unknown, s: State) => void): Reducer => (s, arg) => {
+    syncSaved();
+    const criteriaBefore = criteriaKey();
+    const before = [...prefs.savedIds], undoBefore = lastUndo;
+    update(arg, s);
+    if (saving && JSON.stringify(before) !== JSON.stringify(prefs.savedIds)) {
+      try {
+        saving.write(prefs.savedIds, Array.isArray(s[config.rows]) ? s[config.rows] as CollectionRow[] : []);
+        saveMessage = '';
+      } catch {
+        prefs.savedIds = before; lastUndo = undoBefore;
+        saveMessage = copyParam('collection.saveError', 'Could not save this change. Try again.');
+      }
+    }
+    persisted.write(prefs);
+    if (backend && config.backendQuery && criteriaBefore !== criteriaKey()) return backend.controller.query(criteria()).then(() => undefined);
+    return derive(s);
+  };
+  /** Filter and sort in ONE criteria change, so a tab that sets both runs one query, not two. */
+  const setCriteria = (arg: unknown): void => {
+    const input = object(arg);
+    const sort = String(input.sort ?? '');
+    if (sort === 'default' || sort === 'az' || sort === 'za') prefs.sort = sort;
+    const filter = String(input.filter ?? '');
+    if (filter === 'all' || (filter.startsWith('value:') && (config.filterValues ?? []).includes(filter.slice(6)))) prefs.filter = filter;
+    // A screen with no search field clears a query an older screen persisted, or it narrows every view for good.
+    if (typeof input.query === 'string') prefs.query = input.query.slice(0, 256);
+  };
+  const criteria = () => ({ query: prefs.query, sort: prefs.sort, filter: prefs.filter, savedIds: prefs.filter === 'saved' ? prefs.savedIds : [] });
+  const criteriaKey = () => JSON.stringify(criteria());
+  actions.collectionDismissFilters = change(() => { filtersPresented = false; });
+  actions.collectionFilters = change(() => { filtersPresented = !filtersPresented; });
+  actions.collectionPreview = change(arg => { previewId = str(arg, 'id'); });
+  actions.collectionDismissPreview = change(() => { previewId = ''; });
+  actions.collectionView = change(arg => { const value = str(arg, 'selectedId'); if (value === 'list' || value === 'grid') prefs.view = value; });
+  actions.collectionDensity = change(arg => { const value = str(arg, 'selectedId'); if (value === 'compact' || value === 'comfortable') prefs.density = value; });
+  actions.collectionSort = change(arg => { const value = str(arg, 'selectedId'); if (value === 'default' || value === 'az' || value === 'za') prefs.sort = value; });
+  actions.collectionFilter = change(arg => { const values = object(arg).selectedIds; prefs.filter = Array.isArray(values) && typeof values[0] === 'string' ? values[0] : 'all'; });
+  actions.collectionSearch = change(arg => { prefs.query = str(arg, 'value').slice(0, 256); });
+  actions.collectionCriteria = change(arg => setCriteria(arg));
+  actions.collectionViewName = change(arg => { viewName = str(arg, 'value').slice(0, 40); viewMessage = ''; });
+  actions.collectionRememberView = change(() => {
+    const name = viewName.trim();
+    if (!name) { viewMessage = copyParam('collection.nameRequired', 'Give this view a name'); return; }
+    const existing = prefs.savedViews.findIndex(v => v.name.toLocaleLowerCase() === name.toLocaleLowerCase());
+    if (existing < 0 && prefs.savedViews.length >= 8) { viewMessage = copyParam('collection.viewLimit', 'Remove a saved view to add another (maximum 8)'); return; }
+    const { view, density, sort, query, filter } = prefs;
+    const entry = { id: `view-${existing < 0 ? prefs.savedViews.length : existing}`, name, view, density, sort, query, filter };
+    if (existing < 0) prefs.savedViews.push(entry); else prefs.savedViews[existing] = entry;
+    viewName = ''; viewMessage = copyParam('collection.viewSaved', 'View saved');
+  });
+  actions.collectionApplyView = change(arg => {
+    const view = prefs.savedViews.find(v => v.id === str(arg, 'id'));
+    if (!view) return;
+    const { query, filter, sort, density, view: mode } = view;
+    prefs = { ...prefs, query, filter, sort, density, view: mode, selectedIds: [], selecting: false };
+    filtersPresented = false; previewId = '';
+  });
+  actions.collectionRemoveView = change(arg => {
+    prefs.savedViews = prefs.savedViews.filter(v => v.id !== str(arg, 'id')).map((v, i) => ({ ...v, id: `view-${i}` }));
+  });
+  actions.collectionClear = change(() => { prefs.query = ''; prefs.filter = 'all'; prefs.sort = 'default'; });
+  actions.collectionSelecting = change(() => { prefs.selecting = !prefs.selecting; if (!prefs.selecting) prefs.selectedIds = []; });
+  const known = (s: State, id: string) => !!id && Array.isArray(s[config.rows]) && (s[config.rows] as CollectionRow[]).some(row => collectionId(row) === id);
+  actions.collectionSelect = change((arg, s) => { const id = str(arg, 'id'); if (known(s, id)) prefs.selectedIds = prefs.selectedIds.includes(id) ? prefs.selectedIds.filter(x => x !== id) : [...prefs.selectedIds, id]; });
+  actions.collectionSave = change((arg, s) => { const id = str(arg, 'id'); if (!known(s, id)) return; lastUndo = [...prefs.savedIds]; prefs.savedIds = prefs.savedIds.includes(id) ? prefs.savedIds.filter(x => x !== id) : [...prefs.savedIds, id]; });
+  actions.collectionSaveSelected = change((_arg, s) => { if (!prefs.selectedIds.length || prefs.selectedIds.some(id => !known(s, id))) return; lastUndo = [...prefs.savedIds]; prefs.savedIds = [...new Set([...prefs.savedIds, ...prefs.selectedIds.filter(id => known(s, id))])]; prefs.selecting = false; prefs.selectedIds = []; });
+  actions.collectionUndo = change(() => { if (lastUndo) prefs.savedIds = lastUndo; lastUndo = undefined; });
+  if (backend) {
+    actions.collectionDataChanged = s => derive(backend.apply(s, backend.controller.getState()));
+    actions.load = (_s, arg) => {
+      stashCopy(arg); syncSaved(); applyNavigationCriteria(arg, _s);
+      const reset = backend.onLoad?.(arg);
+      if (reset) { setCriteria(reset); persisted.write(prefs); }
+      // A load of what the screen already shows is the screen coming back: it revalidates behind its rows.
+      return backend.controller.query(criteria(), backend.restorePagesOnLoad, true).then(() => undefined);
+    };
+    actions.refresh = (_s, arg) => {
+      stashCopy(arg); syncSaved();
+      return backend.controller.query(criteria()).then(() => undefined);
+    };
+    actions.loadMore = () => backend.controller.loadMore().then(() => undefined);
+    actions.retry = actions.collectionRetry = () => backend.controller.retry().then(() => undefined);
+    actions.search = actions.collectionSearch;
+    actions.clearSearch = actions.collectionClear;
+  }
+  // Non-paged collections retain their domain-owned retry behavior. The shared
+  // error surface only points at an existing load/refresh reducer; it never
+  // invents a fetch or claims that a retry happened.
+  if (!actions.collectionRetry && !backend) {
+    const retry = actions.refresh ?? actions.load;
+    if (retry) actions.collectionRetry = retry;
+  }
+  return { state: derive(def.state), actions };
+}
+
+/** Domain-owned page source with shared query controls. Publishing uses a normal
+ * reducer and reads the private controller snapshot, never an SDUI payload. */
+export function defineBackendCollection<S extends object, Row extends object>(name: string, options: {
+  register?: typeof register;
+  /** Explicit mutation preflight; unrelated collection services keep their current reducers. */
+  onlineWrites?: boolean;
+  /** Where the offline refusal is written (default `actionMessage`) — the field the screen shows next to the action. */
+  onlineWriteMessageFields?: readonly string[];
+  /** Revalidate already opened pages on navigation return; explicit refresh resets. */
+  restorePagesOnLoad?: boolean;
+  /** The load action's argument (onAppear params beyond `copy`), before the query runs — for a
+   *  domain setting that rides the descriptor, e.g. My Bookings' `weeklyGoal`. */
+  onLoad?(arg: unknown): CollectionCriteriaReset | void;
+  state: S;
+  source: CollectionQuerySource<Row>;
+  apply(state: S, page: CollectionQueryState<Row>): S;
+  saving?: CollectionSaving;
+  actions?: Record<string, (state: S, ...args: unknown[]) => S | undefined | Promise<S | undefined>>;
+}) {
+  let publish: (() => unknown) | undefined;
+  const controller = createCollectionQuery(options.source, () => { publish?.(); });
+  const definition = decorateCollection(name, { state: options.state as State, actions: options.actions as Record<string, Reducer> | undefined }, options.saving, {
+    restorePagesOnLoad: options.restorePagesOnLoad,
+    onLoad: options.onLoad,
+    controller: controller as unknown as BackendCollection['controller'],
+    apply: (state, page) => options.apply(state as S, page as unknown as CollectionQueryState<Row>) as State,
+  });
+  // Compatibility starters retain their existing mutation behavior; accept the
+  // current authoring contract without enabling the offline-write rollout.
+  const handle = (options.register ?? register)(name, definition);
+  // Registration restored the state a cold boot saved: the page it showed is this run's, before the first load. Only
+  // when the service's own rows came back with it: a bundle that keeps them out of the restore (its `notHydrated`)
+  // starts its first load as before, never from rows it chose not to restore. Rows that came back empty are the
+  // list's own only when the page it showed was empty too; a page with rows means they were kept out.
+  const restored = (handle as { getState?: () => State }).getState?.();
+  const rowsKey = COLLECTIONS[name]?.rows;
+  const restoredRows = rowsKey ? restored?.[rowsKey] : undefined;
+  const shownItems = (restored?.collectionShown as { state?: { items?: unknown } } | undefined)?.state?.items;
+  const shownEmpty = Array.isArray(shownItems) && shownItems.length === 0;
+  if (Array.isArray(restoredRows) && (restoredRows.length > 0 || shownEmpty)) controller.seed(restored?.collectionShown);
+  publish = () => handle.collectionDataChanged();
+  return handle;
+}
+
+/** Keep the domain service's existing TypeScript API. Extra collection verbs are
+ * dispatched through SDUI and do not widen the native capability surface. */
+export const defineService: typeof register = ((name: string, def: ServiceDefinition<unknown>) =>
+  register(name, { ...def, ...decorateCollection(name, def as unknown as { state: State; actions?: Record<string, Reducer> }) } as ServiceDefinition<State>)) as typeof register;
+
+/** Domains can supply their existing saved-items store without putting domain
+ * data or mutations in the shared collection layer. */
+export function withCollectionSaving(saving: CollectionSaving): typeof register {
+  return ((name: string, def: ServiceDefinition<unknown>) =>
+    register(name, decorateCollection(name, def as unknown as { state: State; actions?: Record<string, Reducer> }, saving))) as typeof register;
+}

package/templates/salon-spa/tier5-src/_shared/detail-presence.ts

@@ -0,0 +1,51 @@
+// Whether a detail screen's entity is there — the worker half of the shared not-found
+// state (the `detailNotFound` descriptor builder).
+//
+// A detail screen's descriptor asks two questions, both as `hiddenWhen` flags:
+//   • `noEntity`     → hide the entity's content AND its actions (Like, Follow, Send…)
+//   • `hideNotFound` → hide the not-found state
+// Four answers exist, and only one of them shows the not-found state:
+//   loading  — a loading line (`hideLoading` false); no content, no actions, no verdict
+//   found    — content + actions shown
+//   missing  — not-found shown, content + actions hidden
+//   failed   — a load-error line (`hideLoadError` false); no content, no actions
+// A load that FAILS for any reason other than "not found" is `failed`, never `missing`:
+// an offline device must not tell the user their invoice was deleted.
+
+export type Presence = "loading" | "found" | "missing" | "failed";
+
+export interface PresenceFlags {
+  found: boolean;
+  notFound: boolean;
+  noEntity: boolean;
+  hideNotFound: boolean;
+  hideLoading: boolean;
+  hideLoadError: boolean;
+}
+
+export function presence(p: Presence): PresenceFlags {
+  return {
+    found: p === "found", notFound: p === "missing", noEntity: p !== "found", hideNotFound: p !== "missing",
+    hideLoading: p !== "loading", hideLoadError: p !== "failed",
+  };
+}
+
+/** The entity id the host baked into this detail screen (`himi.open` params). */
+export function detailInputId(): string {
+  const v = (globalThis as { himalaya?: { input?: { id?: unknown } } }).himalaya?.input?.id;
+  return typeof v === "string" ? v.trim() : "";
+}
+
+/** True when a Wix read failed because the record does not exist: the SDK rejects
+ *  with "HTTP <code>: <body>", so an HTTP 404, or Wix's `NOT_FOUND` error code. A bare
+ *  "not found" in a message is NOT enough — "capability wix_api not found" or "Method
+ *  not found" is a broken integration, and must not tell the user the record is gone. */
+export function isNotFoundError(error: unknown): boolean {
+  const msg = String((error as { message?: unknown } | null)?.message ?? error ?? "");
+  return /\bHTTP\s*404\b/.test(msg) || /\bNOT_FOUND\b/.test(msg);
+}
+
+/** `missing` for a not-found failure, `failed` (claim nothing) otherwise. */
+export function presenceAfterError(error: unknown): PresenceFlags {
+  return presence(isNotFoundError(error) ? "missing" : "failed");
+}

package/templates/salon-spa/tier5-src/_shared/empty-flags.ts

@@ -0,0 +1,33 @@
+// Empty-collection flags for descriptors.
+//
+// A bound Grid/LazyList with zero rows still renders a zero-height box, and a stack
+// allocates its `spacing` between CHILDREN, not between painted children — so every
+// empty list left a full gap of blank on the screen (the measure pass's `dead-gap`, on
+// iOS and Android as much as on web). `hiddenWhen` hides on a TRUE scalar only, and an
+// empty array is not one, so a descriptor cannot gate a list on its own rows.
+//
+// `withEmptyFlags(def, { rows: "noRows" })` derives `noRows = rows is empty` into the
+// initial state and after EVERY action (sync or async), so a builder can write
+// `hiddenWhen(grid(...), "$service:svc.noRows")` without each reducer remembering to.
+type State = Record<string, unknown>;
+type Action = (s: State, ...args: unknown[]) => unknown;
+
+export function withEmptyFlags<D extends { state: object; actions?: object }>(def: D, flags: Record<string, string>): D {
+  const derive = <T>(s: T): T => {
+    if (!s || typeof s !== "object") return s;
+    const out = { ...(s as State) };
+    for (const [rows, flag] of Object.entries(flags)) {
+      const v = out[rows];
+      out[flag] = !Array.isArray(v) || v.length === 0;
+    }
+    return out as T;
+  };
+  const actions: Record<string, Action> = {};
+  for (const [name, action] of Object.entries((def.actions ?? {}) as Record<string, Action>)) {
+    actions[name] = (s, ...args) => {
+      const r = action(s, ...args);
+      return r && typeof (r as Promise<unknown>).then === "function" ? (r as Promise<unknown>).then(derive) : derive(r);
+    };
+  }
+  return { ...def, state: derive(def.state), actions } as D;
+}