@wix/himalaya-cli 0.941.0 → 0.943.0

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

@@ -13,7 +13,11 @@ interface Row { id: string; title: string; subtitle: string }
 interface S {
   status: "loading" | "ready";
   conversations: Row[]; emptyText: string;
-  isMock: boolean; notMock: boolean; mockBanner: string;
+  isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
+   *  shows only when the site really has none, and the unavailable one only when the
+   *  query failed. A failed query must never render the sentence that claims the
+   *  customer has no content. */
+  notMockEmpty: boolean; notMockUnavailable: boolean;
 }
 
 // businessDisplayData / participantDisplayData are open maps; pull a human name from
@@ -33,28 +37,27 @@ function norm(c: WixConversation, i: number): Row {
   return { id: c.id || `conv-${i}`, title, subtitle: preview };
 }
 
-const MOCK_BANNER = "Sample content — this site has no messages yet.";
 const MOCK: Row[] = [
   { id: "sample-orders",  title: "Orders",   subtitle: "Your order is on its way — track it here." },
   { id: "sample-support", title: "Support",  subtitle: "Hi! Let us know how we can help." },
   { id: "sample-team",    title: "The Team", subtitle: "Welcome 👋 Thanks for joining us!" },
 ];
 
-function mockState(s: S): S {
-  return { ...s, status: "ready", conversations: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, mockBanner: MOCK_BANNER };
+function mockState(s: S, reason: "empty" | "unavailable"): S {
+  return { ...s, status: "ready", conversations: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
 }
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedInbox", {
-  state: { status: "loading", conversations: [], emptyText: "", isMock: false, notMock: true, mockBanner: "" },
+  state: { status: "loading", conversations: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
   actions: {
     load: async (s) => {
       try {
         const r = await listConversations({ paging: { limit: 50 } });
         const conversations = (r.conversations ?? []).map(norm);
-        if (conversations.length) return { ...s, status: "ready", conversations, emptyText: "", isMock: false, notMock: true, mockBanner: "" };
-        return mockState(s);
+        if (conversations.length) return { ...s, status: "ready", conversations, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
+        return mockState(s, "empty");
       } catch {
-        return mockState(s);
+        return mockState(s, "unavailable");
       }
     },
   },

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

@@ -11,7 +11,11 @@ interface Row { id: string; title: string; subtitle: string }
 interface S {
   status: "loading" | "ready";
   invoices: Row[]; emptyText: string;
-  isMock: boolean; notMock: boolean; mockBanner: string;
+  isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
+   *  shows only when the site really has none, and the unavailable one only when the
+   *  query failed. A failed query must never render the sentence that claims the
+   *  customer has no content. */
+  notMockEmpty: boolean; notMockUnavailable: boolean;
 }
 
 const STATUS_LABEL: Record<string, string> = {
@@ -35,28 +39,27 @@ function norm(v: WixInvoice): Row {
   return { id: v.id || "invoice", title, subtitle };
 }
 
-const MOCK_BANNER = "Sample content — you have no invoices yet.";
 const MOCK: Row[] = [
   { id: "sample-1024", title: "Invoice #1024", subtitle: "Paid · $120.00" },
   { id: "sample-1031", title: "Invoice #1031", subtitle: "Sent · $80.00" },
   { id: "sample-1042", title: "Invoice #1042", subtitle: "Overdue · $45.00" },
 ];
 
-function mockState(s: S): S {
-  return { ...s, status: "ready", invoices: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, mockBanner: MOCK_BANNER };
+function mockState(s: S, reason: "empty" | "unavailable"): S {
+  return { ...s, status: "ready", invoices: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
 }
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedInvoices", {
-  state: { status: "loading", invoices: [], emptyText: "", isMock: false, notMock: true, mockBanner: "" },
+  state: { status: "loading", invoices: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
   actions: {
     load: async (s) => {
       try {
         const r = await queryInvoices({ query: { paging: { limit: 20 } } });
         const invoices = (r.invoices ?? []).filter((v) => v.archived !== true).map(norm);
-        if (invoices.length) return { ...s, status: "ready", invoices, emptyText: "", isMock: false, notMock: true, mockBanner: "" };
-        return mockState(s);
+        if (invoices.length) return { ...s, status: "ready", invoices, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
+        return mockState(s, "empty");
       } catch {
-        return mockState(s);
+        return mockState(s, "unavailable");
       }
     },
   },

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

@@ -13,7 +13,11 @@ interface S {
   status: "loading" | "ready";
   programName: string; unit: string;
   rewards: Row[]; emptyText: string;
-  isMock: boolean; notMock: boolean; mockBanner: string;
+  isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
+   *  shows only when the site really has none, and the unavailable one only when the
+   *  query failed. A failed query must never render the sentence that claims the
+   *  customer has no content. */
+  notMockEmpty: boolean; notMockUnavailable: boolean;
 }
 
 /** "500 points" / "Free" from a reward's requiredPoints. */
@@ -28,7 +32,6 @@ function norm(r: WixLoyaltyReward, unit: string): Row {
   return { id: r.id || r.name || "reward", name: r.name || "Reward", subtitle: pointsLabel(r, unit) };
 }
 
-const MOCK_BANNER = "Sample content — this business hasn't set up a rewards program yet.";
 const MOCK: Row[] = [
   { id: "sample-5off",    name: "$5 off your next order", subtitle: "500 points" },
   { id: "sample-ship",    name: "Free shipping",         subtitle: "300 points" },
@@ -36,12 +39,12 @@ const MOCK: Row[] = [
   { id: "sample-gift",    name: "Free welcome gift",     subtitle: "1,000 points" },
 ];
 
-function mockState(s: S): S {
-  return { ...s, status: "ready", programName: "Rewards", unit: "points", rewards: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, mockBanner: MOCK_BANNER };
+function mockState(s: S, reason: "empty" | "unavailable"): S {
+  return { ...s, status: "ready", programName: "Rewards", unit: "points", rewards: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
 }
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedLoyalty", {
-  state: { status: "loading", programName: "Rewards", unit: "points", rewards: [], emptyText: "", isMock: false, notMock: true, mockBanner: "" },
+  state: { status: "loading", programName: "Rewards", unit: "points", rewards: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
   actions: {
     load: async (s) => {
       try {
@@ -51,10 +54,10 @@ const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedLoyalty
         const programName = (p?.name || "Rewards").trim() || "Rewards";
         const r = await listLoyaltyRewards();
         const rewards = (r.rewards ?? []).filter((x) => x.active !== false).map((x) => norm(x, unit));
-        if (rewards.length) return { ...s, status: "ready", programName, unit, rewards, emptyText: "", isMock: false, notMock: true, mockBanner: "" };
-        return mockState(s);
+        if (rewards.length) return { ...s, status: "ready", programName, unit, rewards, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
+        return mockState(s, "empty");
       } catch {
-        return mockState(s);
+        return mockState(s, "unavailable");
       }
     },
   },

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

@@ -25,7 +25,12 @@ interface Row {
 interface S {
   status: "loading" | "ready";
   items: Row[]; emptyText: string;
-  isMock: boolean; notMock: boolean; mockBanner: string;
+  isMock: boolean; notMock: boolean;
+  /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
+   *  shows only when the site really has none, and the unavailable one only when the
+   *  query failed. A failed query must never render the sentence that claims the
+   *  customer has no content. */
+  notMockEmpty: boolean; notMockUnavailable: boolean;
 }
 
 /** Human "2h ago" / "Yesterday" from an ISO date. */
@@ -79,7 +84,6 @@ function norm(n: MfvNotification): Row {
   };
 }
 
-const MOCK_BANNER = "Sample content — you have no notifications yet.";
 const MOCK: Row[] = [
   { id: "sample-like",    name: "Maya Levin liked your post",           subtitle: "“Weekend pop-up” · 2h ago",  unread: true,  unreadDot: "●", photo: "", initial: "M", dest: "" },
   { id: "sample-comment", name: "Daniel Cohen commented on your post",  subtitle: "“Love this — count me in!” · 5h ago", unread: true,  unreadDot: "●", photo: "", initial: "D", dest: "" },
@@ -88,8 +92,9 @@ const MOCK: Row[] = [
   { id: "sample-offer",   name: "New offer just for you",               subtitle: "15% off your next order · 3d ago", unread: false, unreadDot: "", photo: "", initial: "%", dest: "" },
 ];
 
-function mockState(s: S): S {
-  return { ...s, status: "ready", items: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, mockBanner: MOCK_BANNER };
+function mockState(s: S, reason: "empty" | "unavailable"): S {
+  return { ...s, status: "ready", items: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false,
+    notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable" };
 }
 
 const svc = defineService<S, {
@@ -97,15 +102,15 @@ const svc = defineService<S, {
   markOneRead: (s: S, id: string) => Promise<S>;
   markAll: (s: S) => Promise<S>;
 }>("himiBrandedNotifications", {
-  state: { status: "loading", items: [], emptyText: "", isMock: false, notMock: true, mockBanner: "" },
+  state: { status: "loading", items: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true },
   actions: {
     load: async (s) => {
       try {
         const items = (await queryNotifications(25)).map(norm);
-        if (items.length) return { ...s, status: "ready", items, emptyText: "", isMock: false, notMock: true, mockBanner: "" };
-        return mockState(s);
+        if (items.length) return { ...s, status: "ready", items, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true };
+        return mockState(s, "empty");
       } catch {
-        return mockState(s);
+        return mockState(s, "unavailable");
       }
     },
     // Mark one read; optimistically clear its dot. Real write is best-effort and

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

@@ -21,7 +21,11 @@ interface Row { id: string; name: string; subtitle: string; on: boolean }
 interface S {
   status: "loading" | "ready";
   topics: Row[]; emptyText: string;
-  isMock: boolean; notMock: boolean; mockBanner: string;
+  isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
+   *  shows only when the site really has none, and the unavailable one only when the
+   *  query failed. A failed query must never render the sentence that claims the
+   *  customer has no content. */
+  notMockEmpty: boolean; notMockUnavailable: boolean;
 }
 
 /** A topic delivers unless an explicit MUTED preference silences it. The status
@@ -45,7 +49,6 @@ function norm(t: NotificationTopic, prefs: PreferenceInfo[]): Row {
   return row(t.id || name, name, isOn(t.id, prefs));
 }
 
-const MOCK_BANNER = "Sample content — notification settings will appear here once configured.";
 const MOCK: Row[] = [
   row("sample-orders", "Order updates", true),
   row("sample-bookings", "Bookings & reminders", true),
@@ -53,15 +56,15 @@ const MOCK: Row[] = [
   row("sample-community", "Community activity", true),
 ];
 
-function mockState(s: S): S {
-  return { ...s, status: "ready", topics: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, mockBanner: MOCK_BANNER };
+function mockState(s: S, reason: "empty" | "unavailable"): S {
+  return { ...s, status: "ready", topics: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
 }
 
 const svc = defineService<S, {
   load: (s: S) => Promise<S>;
   toggle: (s: S, p?: { id?: string }) => Promise<S>;
 }>("himiBrandedNotifSettings", {
-  state: { status: "loading", topics: [], emptyText: "", isMock: false, notMock: true, mockBanner: "" },
+  state: { status: "loading", topics: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
   actions: {
     load: async (s) => {
       try {
@@ -71,10 +74,10 @@ const svc = defineService<S, {
         ]);
         const prefs = prefsRes.preferences?.preferencesInfo ?? [];
         const topics = (topicsRes.topics ?? []).map((t) => norm(t, prefs));
-        if (topics.length) return { ...s, status: "ready", topics, emptyText: "", isMock: false, notMock: true, mockBanner: "" };
-        return mockState(s);
+        if (topics.length) return { ...s, status: "ready", topics, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
+        return mockState(s, "empty");
       } catch {
-        return mockState(s);
+        return mockState(s, "unavailable");
       }
     },
     // Flip one topic's On/Off. Optimistic (updates the row immediately); the real

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

@@ -24,7 +24,11 @@ interface S {
   /** The Agenda wire shape, derived from `reservations` on every transition. */
   events: CalendarEvent[];
   emptyText: string;
-  isMock: boolean; notMock: boolean; mockBanner: string;
+  isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
+   *  shows only when the site really has none, and the unavailable one only when the
+   *  query failed. A failed query must never render the sentence that claims the
+   *  customer has no content. */
+  notMockEmpty: boolean; notMockUnavailable: boolean;
 }
 
 const STATUS_LABEL: Record<string, string> = {
@@ -93,7 +97,6 @@ function withEvents(s: S, reservations: Row[]): S {
   return { ...s, reservations, events: eventsOf(reservations) };
 }
 
-const MOCK_BANNER = "Sample content — you have no reservations yet.";
 /** Sample rows sit on days RELATIVE to now, not on frozen "Aug 8" strings: an
  *  Agenda groups by real calendar day, and hardcoded past dates would pile the
  *  whole sample under one stale heading. */
@@ -119,8 +122,8 @@ function mockRows(): Row[] {
   ];
 }
 
-function mockState(s: S): S {
-  return withEvents({ ...s, status: "ready", emptyText: "", isMock: true, notMock: false, mockBanner: MOCK_BANNER }, mockRows());
+function mockState(s: S, reason: "empty" | "unavailable"): S {
+  return withEvents({ ...s, status: "ready", emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"}, mockRows());
 }
 
 /** The reservation id out of a tap. `Agenda.onSelectEvent` dispatches
@@ -138,7 +141,7 @@ const svc = defineService<S, {
   load: (s: S) => Promise<S>;
   cancel: (s: S, p?: unknown) => Promise<S>;
 }>("himiBrandedReservations", {
-  state: { status: "loading", reservations: [], events: [], emptyText: "", isMock: false, notMock: true, mockBanner: "" },
+  state: { status: "loading", reservations: [], events: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
   actions: {
     load: async (s) => {
       try {
@@ -147,11 +150,11 @@ const svc = defineService<S, {
         const r = await queryReservations({ cursorPaging: { limit: 20 }, sort: [{ fieldName: "details.startDate", order: "ASC" }] });
         const reservations = (r.reservations ?? []).map(norm);
         if (reservations.length) {
-          return withEvents({ ...s, status: "ready", emptyText: "", isMock: false, notMock: true, mockBanner: "" }, reservations);
+          return withEvents({ ...s, status: "ready", emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true}, reservations);
         }
-        return mockState(s);
+        return mockState(s, "empty");
       } catch {
-        return mockState(s);
+        return mockState(s, "unavailable");
       }
     },
     // Cancel one upcoming reservation. Optimistic (marks it Canceled immediately);

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

@@ -12,7 +12,11 @@ interface Row { id: string; author: string; stars: string; title: string; body:
 interface S {
   status: "loading" | "ready";
   reviews: Row[]; emptyText: string;
-  isMock: boolean; notMock: boolean; mockBanner: string;
+  isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
+   *  shows only when the site really has none, and the unavailable one only when the
+   *  query failed. A failed query must never render the sentence that claims the
+   *  customer has no content. */
+  notMockEmpty: boolean; notMockUnavailable: boolean;
 }
 
 /** "★★★★☆" from a 0–5 rating (clamped). */
@@ -32,7 +36,6 @@ function norm(v: WixReview): Row {
   };
 }
 
-const MOCK_BANNER = "Sample content — this business has no reviews yet.";
 const MOCK: Row[] = [
   { id: "sample-1", author: "Maya L.",   stars: "★★★★★", title: "Fantastic experience", body: "Best in town — friendly staff and top quality. Highly recommend!" },
   { id: "sample-2", author: "Daniel C.", stars: "★★★★☆", title: "Great value",          body: "Really enjoyed it and will definitely be coming back." },
@@ -40,22 +43,22 @@ const MOCK: Row[] = [
   { id: "sample-4", author: "Amit L.",   stars: "★★★★☆", title: "Solid",                body: "Good quality and quick service. Would order again." },
 ];
 
-function mockState(s: S): S {
-  return { ...s, status: "ready", reviews: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, mockBanner: MOCK_BANNER };
+function mockState(s: S, reason: "empty" | "unavailable"): S {
+  return { ...s, status: "ready", reviews: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
 }
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedReviews", {
-  state: { status: "loading", reviews: [], emptyText: "", isMock: false, notMock: true, mockBanner: "" },
+  state: { status: "loading", reviews: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
   actions: {
     load: async (s) => {
       try {
         const r = await queryReviews({ cursorPaging: { limit: 20 } });
         const raw = (r.reviews ?? r.results ?? []) as WixReview[];
         const reviews = raw.map(norm).filter((x) => x.title || x.body);
-        if (reviews.length) return { ...s, status: "ready", reviews, emptyText: "", isMock: false, notMock: true, mockBanner: "" };
-        return mockState(s);
+        if (reviews.length) return { ...s, status: "ready", reviews, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
+        return mockState(s, "empty");
       } catch {
-        return mockState(s);
+        return mockState(s, "unavailable");
       }
     },
   },

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

@@ -37,7 +37,11 @@ interface Row { id: string; title: string; subtitle: string }
 interface S {
   status: "loading" | "ready";
   channels: Row[]; emptyText: string;
-  isMock: boolean; notMock: boolean; mockBanner: string;
+  isMock: boolean; notMock: boolean; /** #2849 — hiddenWhen() hides on TRUE, so these are inverted: the empty-state banner
+   *  shows only when the site really has none, and the unavailable one only when the
+   *  query failed. A failed query must never render the sentence that claims the
+   *  customer has no content. */
+  notMockEmpty: boolean; notMockUnavailable: boolean;
 }
 
 function norm(c: VodChannel): Row {
@@ -47,24 +51,23 @@ function norm(c: VodChannel): Row {
   return { id: c.id || "channel", title, subtitle: parts.join(" · ") };
 }
 
-const MOCK_BANNER = "Sample content — this site has no Wix Video channels yet.";
 const MOCK: Row[] = [
   { id: "sample-tutorials", title: "Tutorials",       subtitle: "12 videos" },
   { id: "sample-behind",    title: "Behind the Scenes", subtitle: "6 videos" },
   { id: "sample-masterclass", title: "Masterclass",    subtitle: "8 videos · Premium" },
 ];
 
-function mockState(s: S): S {
-  return { ...s, status: "ready", channels: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, mockBanner: MOCK_BANNER };
+function mockState(s: S, reason: "empty" | "unavailable"): S {
+  return { ...s, status: "ready", channels: MOCK.map((r) => ({ ...r })), emptyText: "", isMock: true, notMock: false, notMockEmpty: reason !== "empty", notMockUnavailable: reason !== "unavailable"};
 }
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedVideos", {
-  state: { status: "loading", channels: [], emptyText: "", isMock: false, notMock: true, mockBanner: "" },
+  state: { status: "loading", channels: [], emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true},
   actions: {
     load: async (s) => {
       try {
         const api = wixApi();
-        if (!api) return mockState(s);
+        if (!api) return mockState(s, "unavailable");
         const res = (await api.call("POST", VOD_PUBLIC_GRAPHQL, { query: CHANNEL_LIST_QUERY, variables: {} })) as
           { data?: { channels?: { entities?: VodChannel[] } } } | { channels?: { entities?: VodChannel[] } };
         // The gateway may return the GraphQL envelope ({data:{...}}) or the bridge may
@@ -73,10 +76,10 @@ const svc = defineService<S, { load: (s: S) => Promise<S> }>("himiBrandedVideos"
           (res as { data?: { channels?: { entities?: VodChannel[] } } })?.data?.channels?.entities ??
           (res as { channels?: { entities?: VodChannel[] } })?.channels?.entities ?? [];
         const channels = entities.map(norm);
-        if (channels.length) return { ...s, status: "ready", channels, emptyText: "", isMock: false, notMock: true, mockBanner: "" };
-        return mockState(s);
+        if (channels.length) return { ...s, status: "ready", channels, emptyText: "", isMock: false, notMock: true, notMockEmpty: true, notMockUnavailable: true};
+        return mockState(s, "empty");
       } catch {
-        return mockState(s);
+        return mockState(s, "unavailable");
       }
     },
   },

package/templates/branded-lite/tier5-src/wix-spaces-collections/index.ts

@@ -11,7 +11,12 @@ import {
 } from "@himalaya/wix-stores-collections";
 
 interface Row { id: string; name: string; subtitle: string }
-interface S { status: "loading" | "ready"; collections: Row[]; emptyText: string }
+interface S {
+  status: "loading" | "ready" | "error";
+  collections: Row[];
+  emptyText: string;
+  error: string;
+}
 
 function fromCategory(c: StoreCategory): Row {
   return { id: c.id || "", name: c.name || "Category", subtitle: categoryCount(c) };
@@ -23,26 +28,69 @@ function fromCollection(c: WixCollection): Row {
   return { id: cc.id || cc.name || "collection", name: cc.name || "Collection", subtitle: n != null ? `${n} ${n === 1 ? "product" : "products"}` : "" };
 }
 
-async function loadCollections(): Promise<Row[]> {
+type Loaded = { ok: true; rows: Row[] } | { ok: false; error: string };
+
+async function loadCollections(): Promise<Loaded> {
   try {
     const r = await queryStoreCategories(50);
-    const rows = (r.categories ?? []).map(fromCategory).filter((row) => row.id);
-    if (rows.length) return rows;
-  } catch { /* fall through to V1 */ }
+    // A V3 SUCCESS with zero rows is an empty catalogue, not a reason to try V1, and this is the
+    // line that matters. Written as `if (rows.length) return rows`, a modern (stores-v3) site
+    // that simply has no categories fell through to the V1 call — which `himi sdk
+    // wix-stores-collections` documents as answering HTTP 428 on exactly those sites — and the
+    // catch below turned that 428 into an empty list. The screen then told the visitor "No
+    // categories yet" over a dead endpoint.
+    //
+    // Only a V3 THROW earns the fallback, because a legacy V1-catalogue site is the single case
+    // the fallback exists for.
+    //
+    // WHAT IS ESTABLISHED vs WHAT IS ASSUMED, because the two are not the same here and a
+    // reviewer was right to ask. Established: V1-on-V3 answers HTTP 428 — `himi sdk
+    // wix-stores-collections` documents it and names the message. ASSUMED, and not yet
+    // verified against a live legacy site: that the reverse — the V3 Categories API, a separate
+    // app-namespaced service, called on a Catalog-V1 site — THROWS rather than answering
+    // `200 {}`. If it answers 200-empty, a legacy site stops reaching the fallback and shows
+    // "No categories yet" instead of its collections: the same wrong-empty-state this change
+    // fixes, moved to the other site type.
+    //
+    // It is left as a throw-only fallback deliberately, because the alternative is worse:
+    // falling back on a V3 empty result sends every modern site with a genuinely empty
+    // catalogue into the 428 path, and the catch below now surfaces that as "Couldn't load
+    // categories" over a catalogue that is simply empty. Confirm against a Catalog-V1 site
+    // before changing this; five templates carry this file.
+    return { ok: true, rows: (r.categories ?? []).map(fromCategory).filter((row) => row.id) };
+  } catch { /* V3 unavailable — a legacy V1 site is what the fallback is for */ }
   try {
-    const r = await queryCollections({ query: { paging: { limit: 50 } } } as never);
-    return (((r as unknown as { collections?: WixCollection[] }).collections) ?? []).map(fromCollection);
-  } catch {
-    return [];
+    // No `as never` here: `WixQueryCollectionsRequest.query` is `WixCollectionsQuery`, which
+    // declares `paging`, so this argument type-checks as written. Reach for a cast only when the
+    // types really cannot express the call — silencing them by habit hides the next real
+    // mismatch.
+    const r = await queryCollections({ query: { paging: { limit: 50 } } });
+    return { ok: true, rows: (((r as unknown as { collections?: WixCollection[] }).collections) ?? []).map(fromCollection) };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
   }
 }
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("spacesCollections", {
-  state: { status: "loading", collections: [], emptyText: "" },
+  state: { status: "loading", collections: [], emptyText: "", error: "" },
   actions: {
     load: async () => {
-      const collections = await loadCollections();
-      return { status: "ready", collections, emptyText: collections.length ? "" : "No categories yet" };
+      const res = await loadCollections();
+      if (!res.ok) {
+        // `emptyText` carries the honest line as well as `error`, deliberately: this screen's
+        // descriptor binds only `emptyText`, so writing the failure there is what stops the
+        // visitor being told the catalogue is empty when the call actually failed. `status` and
+        // `error` are what an error-state binding and `himi test` read — bind them when you add
+        // a dedicated error view.
+        const line = "Couldn't load categories. Pull to refresh.";
+        return { status: "error", collections: [], emptyText: line, error: res.error };
+      }
+      return {
+        status: "ready",
+        collections: res.rows,
+        emptyText: res.rows.length ? "" : "No categories yet",
+        error: "",
+      };
     },
   },
 });

package/templates/gym-fitness/tier5-src/wix-spaces-collections/index.ts

@@ -11,7 +11,12 @@ import {
 } from "@himalaya/wix-stores-collections";
 
 interface Row { id: string; name: string; subtitle: string }
-interface S { status: "loading" | "ready"; collections: Row[]; emptyText: string }
+interface S {
+  status: "loading" | "ready" | "error";
+  collections: Row[];
+  emptyText: string;
+  error: string;
+}
 
 function fromCategory(c: StoreCategory): Row {
   return { id: c.id || "", name: c.name || "Category", subtitle: categoryCount(c) };
@@ -23,26 +28,69 @@ function fromCollection(c: WixCollection): Row {
   return { id: cc.id || cc.name || "collection", name: cc.name || "Collection", subtitle: n != null ? `${n} ${n === 1 ? "product" : "products"}` : "" };
 }
 
-async function loadCollections(): Promise<Row[]> {
+type Loaded = { ok: true; rows: Row[] } | { ok: false; error: string };
+
+async function loadCollections(): Promise<Loaded> {
   try {
     const r = await queryStoreCategories(50);
-    const rows = (r.categories ?? []).map(fromCategory).filter((row) => row.id);
-    if (rows.length) return rows;
-  } catch { /* fall through to V1 */ }
+    // A V3 SUCCESS with zero rows is an empty catalogue, not a reason to try V1, and this is the
+    // line that matters. Written as `if (rows.length) return rows`, a modern (stores-v3) site
+    // that simply has no categories fell through to the V1 call — which `himi sdk
+    // wix-stores-collections` documents as answering HTTP 428 on exactly those sites — and the
+    // catch below turned that 428 into an empty list. The screen then told the visitor "No
+    // categories yet" over a dead endpoint.
+    //
+    // Only a V3 THROW earns the fallback, because a legacy V1-catalogue site is the single case
+    // the fallback exists for.
+    //
+    // WHAT IS ESTABLISHED vs WHAT IS ASSUMED, because the two are not the same here and a
+    // reviewer was right to ask. Established: V1-on-V3 answers HTTP 428 — `himi sdk
+    // wix-stores-collections` documents it and names the message. ASSUMED, and not yet
+    // verified against a live legacy site: that the reverse — the V3 Categories API, a separate
+    // app-namespaced service, called on a Catalog-V1 site — THROWS rather than answering
+    // `200 {}`. If it answers 200-empty, a legacy site stops reaching the fallback and shows
+    // "No categories yet" instead of its collections: the same wrong-empty-state this change
+    // fixes, moved to the other site type.
+    //
+    // It is left as a throw-only fallback deliberately, because the alternative is worse:
+    // falling back on a V3 empty result sends every modern site with a genuinely empty
+    // catalogue into the 428 path, and the catch below now surfaces that as "Couldn't load
+    // categories" over a catalogue that is simply empty. Confirm against a Catalog-V1 site
+    // before changing this; five templates carry this file.
+    return { ok: true, rows: (r.categories ?? []).map(fromCategory).filter((row) => row.id) };
+  } catch { /* V3 unavailable — a legacy V1 site is what the fallback is for */ }
   try {
-    const r = await queryCollections({ query: { paging: { limit: 50 } } } as never);
-    return (((r as unknown as { collections?: WixCollection[] }).collections) ?? []).map(fromCollection);
-  } catch {
-    return [];
+    // No `as never` here: `WixQueryCollectionsRequest.query` is `WixCollectionsQuery`, which
+    // declares `paging`, so this argument type-checks as written. Reach for a cast only when the
+    // types really cannot express the call — silencing them by habit hides the next real
+    // mismatch.
+    const r = await queryCollections({ query: { paging: { limit: 50 } } });
+    return { ok: true, rows: (((r as unknown as { collections?: WixCollection[] }).collections) ?? []).map(fromCollection) };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
   }
 }
 
 const svc = defineService<S, { load: (s: S) => Promise<S> }>("spacesCollections", {
-  state: { status: "loading", collections: [], emptyText: "" },
+  state: { status: "loading", collections: [], emptyText: "", error: "" },
   actions: {
     load: async () => {
-      const collections = await loadCollections();
-      return { status: "ready", collections, emptyText: collections.length ? "" : "No categories yet" };
+      const res = await loadCollections();
+      if (!res.ok) {
+        // `emptyText` carries the honest line as well as `error`, deliberately: this screen's
+        // descriptor binds only `emptyText`, so writing the failure there is what stops the
+        // visitor being told the catalogue is empty when the call actually failed. `status` and
+        // `error` are what an error-state binding and `himi test` read — bind them when you add
+        // a dedicated error view.
+        const line = "Couldn't load categories. Pull to refresh.";
+        return { status: "error", collections: [], emptyText: line, error: res.error };
+      }
+      return {
+        status: "ready",
+        collections: res.rows,
+        emptyText: res.rows.length ? "" : "No categories yet",
+        error: "",
+      };
     },
   },
 });