@wix/himalaya-cli 0.1544.0 → 0.1546.0

package/templates/retail-store/tier5-src/_shared/read-service.ts

@@ -0,0 +1,255 @@
+import { stashCopy } from './himi-copy.js';
+const offlineReadsEnabled = true;
+import { isNotFound } from './owner-load-error.js';
+import { defineService as register, createReadController, initialReadStatus, type ServiceDefinition, type ReadMetadata, type ReadStatus } from '@himalaya/state';
+
+export interface ReadOptions {
+  cache: 'only-if-cached' | 'reload';
+  onCacheResult(metadata: ReadMetadata): void;
+}
+/** Passed explicitly down the loader's call graph; never a process-global cache mode. */
+export function readOptions(arg: unknown): ReadOptions | undefined {
+  return (arg as { __himiRead?: ReadOptions } | undefined)?.__himiRead;
+}
+
+/** Explicit request context for loaders with their own presentation state (e.g. IAP). */
+export async function policyRead<T>(cache: ReadOptions['cache'], load: (options: ReadOptions) => Promise<T>, localResult?: (data: T) => boolean) {
+  let metadata: ReadMetadata | undefined;
+  const data = await load({ cache, onCacheResult(value) {
+    metadata = metadata ? { ...value, source: metadata.source === 'cache' || value.source === 'cache' ? 'cache' : 'network',
+      cacheable: metadata.cacheable && value.cacheable,
+      fetchedAt: Math.min(metadata.fetchedAt, value.fetchedAt),
+      expiresAt: Math.min(metadata.expiresAt ?? 0, value.expiresAt ?? 0) } : value;
+  } });
+  if (!metadata && localResult?.(data)) metadata = { source: 'local', cacheable: false, fetchedAt: Date.now() };
+  if (!metadata) throw new Error('Read loader did not provide response provenance');
+  return { data, metadata };
+}
+
+type State = Record<string, unknown>;
+type Action = (state: State, arg?: unknown) => State | undefined | Promise<State | undefined>;
+type ReadFailure = Error & { userMessage?: string; signInRequired?: boolean };
+// A record Wix answers 404 for is gone (a delete whose reply was lost): its retained snapshot must
+// not outlive it. Unlike `denied`, it leaves drafts and local controls alone.
+const gone = (error: unknown) => isNotFound(error);
+const denied = (error: unknown) => /HTTP (401|403)\b|forbidden|principal.changed|identity.changed|member access changed/i.test(String(error));
+
+/** Adapts a read-only load reducer. Callers forward readOptions(arg) to every
+ * primary SDK read and let errors reject. Other actions remain ordinary reducers.
+ * The retained snapshot is in memory; persistence belongs exclusively to the
+ * policy-controlled Wix cache, never to generic worker hydration or local-db rows.
+ */
+export function withReadLifecycle(registerService: typeof register = register, loadAction = 'load', options: {
+  errorMessage?(error: unknown): string;
+  /** Only an authored create form or guest shell; never a server-derived fallback. */
+  localResult?(state: State): boolean;
+  /** Additional host-owned scope when a read explicitly addresses another site. */
+  scopeKey?(): string;
+  /** Clear module-owned read sidecars on identity loss, access denial, or disposal. */
+  onInvalidate?(): void;
+  /** Editable fields survive recovery once loaded, and edits during an initial read. */
+  preserveFields?: readonly string[];
+  unavailable?(state: State, status: ReadStatus): State;
+  /** Authored source content only; never return a network mirror or demo fallback here. */
+  authoredFallback?(state: State, status: ReadStatus): State | undefined;
+} = {}): typeof register {
+  if (!offlineReadsEnabled) return registerService;
+  return ((name: string, definition: ServiceDefinition<State>) => {
+    if ((globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input?.__himiOwnerPreview === 'sample') return registerService(name, definition);
+    const load = definition.actions?.[loadAction] as Action | undefined;
+    if (!load || definition.readLifecycle) return registerService(name, definition);
+    let args: Record<string, unknown> = {}, key = '', page: State | undefined, read = initialReadStatus();
+    let replacePage = false;
+    let activeLoad: { promise: Promise<void>; revision: number } | undefined;
+    let startedState: State | undefined;
+    let hadSnapshot = false, accessRevoked = false, accessNeedsSignIn = false;
+    const localResult = options.localResult ?? (value => value.notFound === true);
+    let projectedState: State | undefined;
+    const editedFields = new Set<string>();
+    let service: { getState(): State; readChanged(): Promise<unknown> };
+    const project = (state: State): State => {
+      for (const field of options.preserveFields ?? []) {
+        if (projectedState && JSON.stringify(state[field]) !== JSON.stringify(projectedState[field])) editedFields.add(field);
+      }
+      const value: State = { ...state, ...(replacePage && page ? page : !read.hasSnapshot ? definition.state : {}), readStatus: read };
+      replacePage = false;
+      if (accessRevoked) for (const field of options.preserveFields ?? []) {
+        if (Object.prototype.hasOwnProperty.call(definition.state, field)) value[field] = definition.state[field];
+        else delete value[field];
+      }
+      // Drafts and local controls survive both missing snapshots and pending reads.
+      for (const field of accessRevoked ? [] : Object.keys(state)) {
+        if (options.preserveFields?.includes(field) && (hadSnapshot || editedFields.has(field))) value[field] = state[field];
+        if (/Draft$|^draft$|^quantity$|^selection$|^selected|^expandedIds$|^searchQuery$|^query$|^filter$|^sort$/.test(field) &&
+          (!read.hasSnapshot || (startedState && JSON.stringify(state[field]) !== JSON.stringify(startedState[field])))) value[field] = state[field];
+      }
+      if (!read.hasSnapshot) {
+        const authored = options.authoredFallback?.(value, read);
+        if (authored) return projectedState = { ...authored, readStatus: { ...read, hasLocalContent: true } };
+        const message = read.offline ? 'This content isn’t available offline. Connect to load it.' : read.error;
+        const unavailable = { ...value, status: read.refreshing ? 'loading' : 'error', isLoading: read.refreshing,
+          notLoading: !read.refreshing, busy: !read.refreshing, hideContent: true, errored: !read.refreshing, isErrored: !read.refreshing,
+          notErrored: read.refreshing, found: false, noEntity: true, hideNotFound: true, hideLoading: !read.refreshing, hideLoadError: read.refreshing, error: message, errorText: message, emptyText: message, noEmpty: true };
+        if (accessRevoked) Object.assign(unavailable, { readDenied: true, signInRequired: accessNeedsSignIn, noSignIn: !accessNeedsSignIn });
+        return projectedState = options.unavailable?.(unavailable, read) ?? unavailable;
+      }
+      return projectedState = definition.readPresentation?.(value) ?? value;
+    };
+    const perform = async (cache: ReadOptions['cache'], requestKey: string) => {
+      const requestArgs = requestKey ? JSON.parse(requestKey) as Record<string, unknown> : {};
+      return policyRead(cache, async readContext => {
+      const input = { ...(service?.getState() ?? definition.state), __himiRead: readContext } as State;
+      // Unavailable-state flags added by this adapter are presentation, not a failed
+      // domain read. A reducer that spreads its input must not inherit those flags
+      // and have its successful cached/local result rejected as another failure.
+      for (const field of ['errored', 'isErrored']) {
+        if (!Object.prototype.hasOwnProperty.call(definition.state, field)) delete input[field];
+      }
+      // An unsaved create form is authored local content. Its no-op loader must
+      // receive its declared status, not the adapter's temporary unavailable state.
+      if (!read.hasSnapshot && options.localResult?.(input)) input.status = definition.state.status;
+      const data = await load(input, { ...requestArgs, __himiRead: readContext });
+      if (!data || data.status === 'error' || data.errored === true || data.isErrored === true) {
+        const unauthorized = data?.signInRequired === true || /HTTP 401|unauthori[sz]ed|sign[\s-]?in/i.test(String(data?.error || data?.errorText || ''));
+        const failure = new Error(unauthorized ? 'HTTP 401 unauthorized' : data?.readDenied ? 'HTTP 403 forbidden' : 'Read failed') as ReadFailure;
+        failure.signInRequired = data?.signInRequired === true;
+        const userMessage = data?.error || data?.errorText || data?.emptyText;
+        if (typeof userMessage === 'string' && userMessage.trim()) failure.userMessage = userMessage.trim();
+        throw failure;
+      }
+      delete data.__himiRead;
+      return data;
+      }, localResult);
+    };
+    const controller = createReadController<State>({
+      allowLocal: true, cached: key => perform('only-if-cached', key), fetch: key => perform('reload', key), clearOnError(error) {
+        accessRevoked = denied(error);
+        accessNeedsSignIn = (error as ReadFailure | null)?.signInRequired === true || /HTTP 401|unauthori[sz]ed|sign[\s-]?in/i.test(String(error));
+        const clear = accessRevoked || gone(error);
+        if (clear) options.onInvalidate?.();
+        return clear;
+      }, errorMessage(error) {
+        return (error as ReadFailure | null)?.userMessage || options.errorMessage?.(error) || (accessNeedsSignIn ? 'Sign in to view this content.' : '') || '';
+      },
+      publish(data, status) {
+        // A failed revalidation republishes the controller's retained snapshot. The worker
+        // state can contain newer local changes (for example, another fetched page or a
+        // selected row), so do not replace that state with the older controller page on a
+        // stale/error publication. A first cached paint and a successful refresh still
+        // replace the visible read data.
+        replacePage = status.hasSnapshot && data !== undefined
+          && (!page || (!status.refreshing && !status.stale && !status.error));
+        page = data;
+        read = status;
+        void service?.readChanged();
+      },
+    });
+    const host = (globalThis as { himalaya?: { __subscribeReadLifecycle?(listener: (signal: string) => void): () => void } }).himalaya;
+    let unsubscribeAdapter: (() => void) | undefined;
+    unsubscribeAdapter = host?.__subscribeReadLifecycle?.(signal => {
+      if (signal === 'dispose') { options.onInvalidate?.(); unsubscribeAdapter?.(); return; }
+      if (signal !== 'invalidate') return;
+      options.onInvalidate?.();
+      // Identity invalidation clears the controller's private snapshot, so the
+      // adapter must also forget that its form fields came from a prior user.
+      // Otherwise project() can preserve those fields while the host clears the
+      // shared read state.
+      hadSnapshot = false;
+      accessRevoked = true;
+      accessNeedsSignIn = false;
+      editedFields.clear();
+      page = undefined;
+      read = initialReadStatus();
+      replacePage = true;
+      void service?.readChanged();
+    });
+    const refresh: Action = async (_state, arg) => {
+      stashCopy(arg);
+      if (arg && typeof arg === 'object') {
+        args = { ...arg as Record<string, unknown> };
+        // Localized copy is presentation, not a different backend query.
+        delete args.copy;
+      }
+      const next = JSON.stringify({ ...((globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input ?? {}), ...args, ...(options.scopeKey ? { __readScope: options.scopeKey() } : {}) });
+      // Coalesce through the final state projection, not only the controller's
+      // network task. A module-scope load() and the host's boot/onAppear load()
+      // commonly join the same request; returning when the fetch settles lets the
+      // host snapshot the worker before the first caller's readChanged() publishes.
+      if (key === next && activeLoad && activeLoad.revision === controller.getRevision()) {
+        await activeLoad.promise;
+        await service?.readChanged();
+        return service?.getState();
+      }
+      hadSnapshot = read.hasSnapshot && key === next;
+      key = next;
+      startedState = service?.getState() ?? definition.state;
+      projectedState = startedState; editedFields.clear(); accessRevoked = false; accessNeedsSignIn = false;
+      const load = controller.load(key);
+      const revision = controller.getRevision();
+      const task = (async () => {
+        await load;
+        // Controller publications project through this service action. Await its final
+        // projection before resolving load/retry so hosts that serialize worker actions
+        // cannot render the pre-read state after the request has completed.
+        await service?.readChanged();
+      })();
+      const active = { promise: task, revision };
+      activeLoad = active;
+      try {
+        await task;
+      } finally { if (activeLoad === active) activeLoad = undefined; }
+      return await service?.getState();
+    };
+    service = registerService(name, { ...definition, readLifecycle: { refreshAction: 'refreshRead', statusPath: 'readStatus' },
+      state: { ...definition.state, readStatus: read },
+      actions: { ...definition.actions, ...(loadAction !== "refresh" && definition.actions?.refresh ? { refresh: () => controller.refresh().then(() => undefined) } : {}), [loadAction]: refresh, retry: () => controller.refresh().then(() => undefined),
+        refreshRead: refresh, readChanged: project },
+    });
+    return service;
+  }) as typeof register;
+}
+
+// Generic services keep their existing behavior. A `load` action is not proof
+// that it is a safe, cache-eligible read: local device state and writes often use
+// that name too. Shared read helpers and opted-in screens register through
+// withReadLifecycle explicitly.
+export const defineService: typeof register = register;
+/** Safe opt-in for a service whose load action is a cache-eligible read. */
+export const readService: typeof register = withReadLifecycle();
+
+
+/** Raw read escape hatch for an endpoint without a generated SDK binding. */
+export async function rawRead<T>(method: string, path: string, body?: unknown, options?: ReadOptions): Promise<T> {
+  const api = (globalThis as any).himalaya?.wixApi;
+  if (!api) throw new Error('Wix bridge unavailable');
+  if (!options) return api.call(method, path, body) as Promise<T>;
+  if (!api.read) throw new Error('READ_LIFECYCLE_UNSUPPORTED');
+  const result = await api.read(method, path, body, undefined, { cache: options.cache });
+  options.onCacheResult(result.cache);
+  return result.data as T;
+}
+
+/** Editor recovery refreshes its read eligibility without replacing an open draft
+ * or its concurrency revision. Field values remain owned by the form until the
+ * user explicitly submits or reopens it. Only a new, unsaved form is local data. */
+export function withFormReadLifecycle(registerService: typeof register = register): typeof register {
+  if (!offlineReadsEnabled) return registerService;
+  return ((name: string, definition: ServiceDefinition<State>) => withReadLifecycle(registerService, 'load', {
+    preserveFields: ['title', 'name', 'price', 'sku', 'visible', 'revision', 'category',
+      'description', 'originalDescription', 'descriptionMode', 'descriptionJson', 'descriptionDirty', 'descriptionEdits',
+      'when', 'location', 'excerpt', 'body', 'richContent', 'bodyJson', 'bodyDirty', 'bodyEdits',
+      'detailsOpen', 'coverUrl', 'originalCoverUrl', 'coverPreview', 'isFeatured',
+      'question', 'answer', 'answerFormat', 'answerMode', 'answerJson', 'answerDirty', 'answerEdits', 'categoryId', 'statusValue'],
+    localResult: value => value.mode === 'create' && !value.id,
+  })(name, definition)) as typeof register;
+}
+
+/** Server-derived state is never a generic worker snapshot; explicit drafts may persist. */
+export function withReadPersistence(registerService: typeof register, draftFields: readonly string[] = []): typeof register {
+  if (!offlineReadsEnabled) return registerService;
+  return ((name: string, definition: ServiceDefinition<State>) => registerService(name, {
+    ...definition,
+    notPersisted: [...new Set([...(definition.notPersisted ?? []),
+      ...Object.keys(definition.state).filter(key => !draftFields.includes(key))])],
+  })) as typeof register;
+}

package/templates/retail-store/tier5-src/himi-branded-lite-home/index.ts

@@ -250,7 +250,7 @@ interface State {
   hideFeaturedSkeleton: boolean;
   welcome: string;
   refreshedAt: string;
-  /** The resolved home layout preset (RFC 0045 FragmentSlot discriminator).
+  /** The resolved home layout preset (shared slot discriminator).
    *  Plain string, never a proto enum — a `$service:` casePath decodes it as a
    *  JSON string and unknown values fall through to the shipped defaultCase. */
   effectiveLayout: string;

package/templates/retail-store/tier5-src/himi-branded-lite-orders/index.ts

@@ -161,6 +161,9 @@ function derive(state: State): State {
   });
   return {
     ...state,
+    nextCursor: state.nextCursor ?? "",
+    filterOptions: state.filterOptions ?? [{ id: "all", label: copyParam("collection.all", "All"), selected: true },
+      ...Object.keys(FULFILLMENT).map(label => ({ id: `value:${label}`, label: copyParam(`collection.filter.${label}`, label), selected: false }))],
     displayRows: rows.map((row, index, rows) => {
       // Older owned cache rows retain their original date in meta. Group only
       // adjacent days so pagination and an explicit backend sort remain authoritative.