@wix/himalaya-cli 0.1465.0 → 0.1466.0

package/guides/recipe-search.md

@@ -64,9 +64,9 @@ not say why there are no rows.
 | Initial, no query | Search prompt plus useful recent queries, categories, or suggestions. Avoid presenting this as a failed search. |
 | Loading | First load: a skeleton or progress state. Refresh: keep current results visible and show a compact progress indicator when possible. |
 | Results | Matching rows, result count, and the available sort/filter controls. |
-| No matches | Explain that the current query or filters found nothing; offer Clear or a way to adjust them. |
+| No matches | An `EmptyState` explaining that the current query or filters found nothing; offer a way to adjust them, and Clear only where the field is controlled (the native slot) — the inline `SearchField` is uncontrolled, so Clear there empties the query but not the field. |
 | Empty catalog | Explain that the catalog itself has no items yet, independent of the query; provide a useful browse/back action. |
-| Error | Show an error with Retry, retain the query and controls, and keep it distinct from no matches. |
+| Error | Classified as in `himi docs recipe-four-state`: an icon-less `EmptyState` per class with user-facing copy, Try again only for offline and server, Sign in for sign-in, no action for permission. Retain the query and controls, and keep it distinct from no matches. |
 
 ### Native slot and old-client fallback
 
@@ -170,7 +170,12 @@ interface PostsState {
   all: PostRow[];        // the full fetched set — NOT bound by the descriptor
   items: PostRow[];      // ← itemsPath binds here; always derived from all + query
   query: string;
-  loadingText: string; emptyText: string; error: string; notErrored: boolean;
+  hideNoPosts: boolean;  // the EmptyState for "loaded, and there is nothing at all"
+  hideNoMatches: boolean; // the EmptyState for "there are posts, none match the query"
+  errorKind: "" | "offline" | "server" | "signIn" | "permission";  // classifyError(e)
+  hideLoading: boolean; hideOfflineError: boolean; hideServerError: boolean;
+  hideSignInError: boolean; hidePermissionError: boolean;
+  hideRefreshError: boolean;                    // hiddenPath flags, as in recipe-four-state
 }
 
 function visible(all: PostRow[], query: string): PostRow[] {
@@ -186,31 +191,103 @@ function queryFrom(arg: unknown): string {
   return String(a?.value ?? a?.text ?? a?.query ?? "");
 }
 
+// Actions are not serialized: the user can type while load() is in flight, and the
+// action that finishes last writes the whole state. So the latest query lives outside
+// the state, and every fetch applies it when it returns.
+let currentQuery = "";
+
+// The SearchField is uncontrolled: it opens empty, so the query must start over too.
+// `load` (opening the screen) resets it; a query typed while that fetch is in flight
+// still wins. `retry` keeps it.
+load: async (s) => { currentQuery = ""; return loadList(s); },
+
+// After defineService: a cold boot restores the persisted `query` AND the `items` and
+// empty flags derived from it. Re-derive them for an empty query before anything paints.
+const booted = (svc as unknown as { getState?: () => Record<string, unknown> | undefined }).getState?.();
+if (booted && typeof booted === "object") {
+  Object.assign(booted, shape({ ...(booted as Partial<PostsState>), query: "", items: undefined }));
+}
+
 // actions:
 search: (s, arg) => {
   const query = queryFrom(arg);
+  currentQuery = query;
   const items = visible(s.all, query);
-  return shape({ ...s, query, items });   // shape() recomputes emptyText from items+query
+  return shape({ ...s, query, items });   // shape() recomputes the empty flags from all+items+query
 },
-clear: (s) => shape({ ...s, query: "", items: s.all }),
+clear: (s) => { currentQuery = ""; return shape({ ...s, query: "", items: s.all }); },
 ```
 
-- `load()` fetches once, fills `all`, and sets `items = visible(all, query)`.
+- `load()` fetches once, fills `all`, and sets `items = visible(all, currentQuery)`.
+  On a `signIn` or `permission` failure it clears **`all` as well as `items`** —
+  `search`, `clear` and `retry` rebuild rows from `all`, so rows left there come
+  back on the next keystroke.
 - The shipped Blog v3 `WixPost` type includes `categoryIds` and both Wix-image and
   embed-thumbnail media projections. Normalize them without a local cast:
   `coverUrl: post.media?.wixMedia?.image?.url ?? post.media?.embedMedia?.thumbnail?.url ?? ""`
   and `categoryIds: post.categoryIds ?? []`.
-- **`emptyText` should distinguish** "no data at all" from "no matches":
-  `query ? `No matches for “${query}”.` : "No posts yet."` — recompute it in
-  `shape()` wherever items change.
+- **Two empty states, both `EmptyState`**: "no data at all" and "no matches" are
+  different screens. Search's `shape()` takes four-state's flags with one change:
+  `blank` is `all.length === 0`, not `items.length === 0` — `items` is the filtered
+  view, so a query with no matches over rows kept after a failed refresh must not
+  read as "nothing loaded" and show the full-screen error. In `shape()`, wherever
+  items change, recompute
+  `hideNoPosts = !(status === "ready" && all.length === 0)` and
+  `hideNoMatches = !(all.length > 0 && items.length === 0)` — no `status` check,
+  because the user can still search the rows kept after a failed refresh. Their
+  copy is static — an `EmptyState` cannot bind its text on native — and the
+  no-matches one has no action: the `SearchField` is uncontrolled, so a "Clear
+  search" button would empty the worker's query while the field still shows it:
+
+```jsonc
+{ "id": "empty.noPosts",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "icon": "inbox", "title": "No posts yet",
+               "subtitle": "New posts will show up here." } },
+  "modifiers": { "hiddenPath": "$service:posts.hideNoPosts" } },
+{ "id": "empty.noMatches",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "icon": "search", "title": "No posts match your search",
+               "subtitle": "Try a different word." } },
+  "modifiers": { "hiddenPath": "$service:posts.hideNoMatches" } }
+```
+
+## 3. Loading, error and retry
+
+A searchable list loads data, so it carries the four states of
+`himi docs recipe-four-state`:
+
+- **Loading** — a `Skeleton` shaped like the result rows, gated by `hideLoading`,
+  while the first `load()` runs. The search field is usable at once.
+- **Error, nothing loaded** — one `EmptyState` per class `classifyError` can
+  return, **no icon**, user-facing copy; offline and server get **Try again** →
+  `tier5.posts.retry`, sign-in gets **Sign in**, permission gets no action. The
+  `catch` sets `errorKind` from `classifyError(e)`; it never shows `e.message`.
+- **Retry keeps the query.** `retry` re-runs `load()` and then re-applies
+  `currentQuery` — not `s.query`, which is the query from when the retry
+  STARTED — so what the user typed during the fetch is not lost.
+- **No matches is not an error.** A successful search with zero results shows the
+  no-matches `EmptyState` ("No posts match your search"), with no action and no retry.
+
+```ts
+retry: async (s) => {
+  const next = await load(s);                            // classified on failure
+  // Lost access clears the rows; any other failure keeps them for the Banner.
+  const lostAccess = next.errorKind === "signIn" || next.errorKind === "permission";
+  const all = lostAccess ? [] : next.all;
+  return shape({ ...next, all, query: currentQuery, items: visible(all, currentQuery) });
+},
+```
 
-## 3. Server-side search (large datasets)
+## 4. Server-side search (large datasets)
 
 In-worker filtering is right up to a few hundred rows. Past that, make `search`
 re-query the API with the term (most Wix domain query endpoints take a filter,
 e.g. blog `queryPosts` — check `himi sdk wix-<domain>`), keep `status: "loading"`
 during the round-trip, and debounce higher (300–400ms). The descriptor does not
-change — only the action's body.
+change — only the action's body. A failed server-side search **keeps the query and
+the results already on screen** and shows the refresh `Banner` with **Try again**,
+which runs the same query again.
 
 ## Gotchas
 
@@ -231,6 +308,6 @@ change — only the action's body.
 ## See also
 
 - `himi docs recipe-dynamic-list` — the list this recipe filters.
-- `himi docs recipe-four-state` — the emptyText/error/loading strings.
+- `himi docs recipe-four-state` — the loading, classified error and retry idiom.
 - `himi components SearchField` / `FilterChips` / `Tabs`.
 - `.agents/skills/himalaya/examples/search-list.*` (written into the app by `himi init` / `himi agent-init`) — this recipe, runnable.

package/guides/recipe-voice-journal.md

@@ -36,6 +36,21 @@ export async function finishVoiceJournal(sessionId: string) {
 }
 ```
 
+**States.** Recording reads no remote data, so the journal screen needs no network
+loading or error states — but it does have states the user must see:
+
+- **Unavailable** (`status: "unavailable"` — no microphone, permission denied, or a
+  host without capture): an icon-less `EmptyState` that says recording is not
+  available and gives the next step the platform offers (for example, how to allow
+  the microphone). No **Try again**: the same call fails the same way until the
+  user changes something.
+- **Processing** (transcription, diarization): a progress or a placeholder line on
+  the entry, never a blocking spinner; a processing failure keeps the audio and
+  shows the entry without a transcript.
+- **Saved entries list**: reading `local-db` is local and quick, so it needs no
+  skeleton; an empty journal is an `EmptyState` with a "Record your first entry"
+  action.
+
 The SDUI layer can use the existing list, text, button, progress, audio/media, and state-binding
 components for recording, transcript detail, search, deferred processing, summaries, categories,
 delete, and export. Generate summaries and structured categories with `@himalaya/on-device-ai`

package/guides/search-list-t5.descriptor.json

@@ -33,54 +33,115 @@
             "id": "loading",
             "body": {
               "package": "himalaya",
-              "type": "Text",
+              "type": "Skeleton",
               "props": {
-                "text": "$service:posts.loadingText",
-                "style": "body",
-                "color": "textSecondary",
-                "collapseWhenEmpty": true
+                "height": 56,
+                "cornerRadius": 12,
+                "count": 5
               }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideLoading"
+            }
+          },
+          {
+            "id": "empty.no_posts",
+            "body": {
+              "package": "himalaya",
+              "type": "EmptyState",
+              "props": {
+                "icon": "doc",
+                "title": "No posts yet",
+                "subtitle": "Posts you publish show up here."
+              }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideNoPosts"
+            }
+          },
+          {
+            "id": "empty.no_matches",
+            "body": {
+              "package": "himalaya",
+              "type": "EmptyState",
+              "props": {
+                "icon": "search",
+                "title": "No posts match your search",
+                "subtitle": "Try a different word."
+              }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideNoMatches"
+            }
+          },
+          {
+            "id": "error.offline",
+            "body": {
+              "package": "himalaya",
+              "type": "EmptyState",
+              "props": {
+                "title": "Reconnect to the internet",
+                "subtitle": "Connect to the internet, then try again.",
+                "action": {
+                  "actionId": "tier5.posts.retry"
+                },
+                "actionLabel": "Try again"
+              }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideOfflineError"
             }
           },
           {
-            "id": "empty",
+            "id": "error.server",
             "body": {
               "package": "himalaya",
-              "type": "Text",
+              "type": "EmptyState",
               "props": {
-                "text": "$service:posts.emptyText",
-                "style": "body",
-                "color": "textSecondary",
-                "collapseWhenEmpty": true
+                "title": "Unable to load posts",
+                "subtitle": "There was a technical issue on our end. Please wait and try again later.",
+                "action": {
+                  "actionId": "tier5.posts.retry"
+                },
+                "actionLabel": "Try again"
               }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideServerError"
             }
           },
           {
-            "id": "error",
+            "id": "error.permission",
             "body": {
               "package": "himalaya",
-              "type": "Text",
+              "type": "EmptyState",
               "props": {
-                "text": "$service:posts.error",
-                "style": "body",
-                "color": "danger",
-                "collapseWhenEmpty": true
+                "title": "You need permission to view this screen",
+                "subtitle": "Ask the owner of this blog for access."
               }
+            },
+            "modifiers": {
+              "hiddenPath": "$service:posts.hidePermissionError"
             }
           },
           {
-            "id": "retry",
+            "id": "error.refresh",
             "body": {
               "package": "himalaya",
-              "type": "Button",
+              "type": "Banner",
               "props": {
-                "title": "Retry",
-                "style": "secondary",
-                "size": "sm",
-                "action": { "actionId": "tier5.posts.retry" }
+                "severity": "warning",
+                "title": "Couldn't refresh",
+                "message": "Showing what was loaded before.",
+                "action": {
+                  "actionId": "tier5.posts.retry"
+                },
+                "actionLabel": "Try again"
               }
             },
-            "modifiers": { "hiddenPath": "$service:posts.notErrored" }
+            "modifiers": {
+              "hiddenPath": "$service:posts.hideRefreshError"
+            }
           },
           {
             "id": "posts_list",

package/guides/search-list.service.ts

@@ -6,8 +6,9 @@
 // the current query, and let the SearchField's debounced onChange action swap
 // what the single bound path holds. The descriptor never rebinds anything.
 //
-// Builds on the dynamic-list recipe (worker owns the array, four-state display
-// strings) — see examples/dynamic-list.* for that base. Declares "wix_api".
+// Builds on the dynamic-list recipe (worker owns the array, one hiddenPath flag per
+// state, classified errors) — see examples/dynamic-list.* for that base. A retry
+// keeps the user's query. Declares "wix_api".
 
 import { defineService } from "@wix/himalaya/state";
 import { queryPosts, type WixPost } from "@wix/himalaya/wix-blog";
@@ -20,15 +21,24 @@ interface PostRow {
   categoryIds: string[];
 }
 
+// A public blog has no sign-in flow, so a 401 reads as "permission" here.
+type ErrorKind = "" | "offline" | "server" | "permission";
+
 interface PostsState {
   status: "loading" | "ready" | "error";
   all: PostRow[];   // the full fetched set — NOT bound by the descriptor
   items: PostRow[]; // ← itemsPath binds here; ALWAYS derived from all + query
   query: string;
-  loadingText: string;
-  emptyText: string; // distinguishes "no data" from "no matches"
-  error: string;
-  notErrored: boolean;
+  errorKind: ErrorKind;
+  // hiddenPath flags (hide when TRUE) — see `himi docs recipe-four-state`
+  hideLoading: boolean;
+  hideNoPosts: boolean;   // EmptyState: the blog has no posts at all
+  hideNoMatches: boolean; // EmptyState: posts exist, none match the query (not an error)
+  notEmpty: boolean;      // false while either EmptyState shows
+  hideOfflineError: boolean;
+  hideServerError: boolean;
+  hidePermissionError: boolean;
+  hideRefreshError: boolean;
 }
 
 function normalize(raw: WixPost): PostRow {
@@ -54,38 +64,78 @@ function shape(s: Partial<PostsState>): PostsState {
   const all = s.all ?? [];
   const query = s.query ?? "";
   const items = s.items ?? visible(all, query);
+  const errorKind: ErrorKind = status === "error" ? (s.errorKind || "server") : "";
+  const blank = all.length === 0; // nothing loaded to keep
   return {
     status,
     all,
     items,
     query,
-    loadingText: status === "loading" ? "Loading posts…" : "",
-    emptyText:
-      status === "ready" && items.length === 0
-        ? query
-          ? `No matches for “${query}”.`
-          : "No posts yet."
-        : "",
-    error: s.error ?? "",
-    notErrored: status !== "error",
+    errorKind,
+    // Two EmptyStates, not one bound Text: iOS/Android do not bind EmptyState text.
+    hideNoPosts: !(status === "ready" && blank),
+    // Over rows kept after a failed refresh too: no matches is still empty, not an error.
+    hideNoMatches: !(!blank && items.length === 0),
+    notEmpty: !((status === "ready" && blank) || (!blank && items.length === 0)),
+    hideLoading: !(status === "loading" && blank),
+    hideOfflineError: !(blank && errorKind === "offline"),
+    hideServerError: !(blank && errorKind === "server"),
+    hidePermissionError: !(blank && errorKind === "permission"),
+    hideRefreshError: !(!blank && (errorKind === "offline" || errorKind === "server")),
   };
 }
 
+// The HTTP status rides in the message: `HTTP 503: …` on a device, `Wix 503 for …`
+// under `himi test` / `himi render`. Only a transport failure is "offline".
+const STATUS = /\b(?:HTTP|Wix) (\d{3})\b/;
+// No answer at all — what a dropped connection says on every platform.
+const TRANSPORT = /NSURLErrorDomain|(?:UnknownHost|Connect|SocketTimeout|NoRouteToHost|SSLHandshake)Exception|Failed to connect|Unable to resolve host|Connection (?:refused|reset)|Network is unreachable|Software caused connection abort|ECONNRESET|ETIMEDOUT|EPIPE|Broken pipe|stream was reset|unexpected end of stream|timed out|^timeout$|Failed to fetch|NetworkError|^(?:TypeError: )?Load failed$|net::ERR_|^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/i;
+// Android reports an unknown host as the bare hostname (`users.wix.com`) — hence the last form.
+// No session on the device: the native bridge refuses before any request leaves.
+// A pinned site with no member session: iOS `siteNotPermitted(requested: "account", …)`,
+// Android `site account is not the bound site …`; the web host `HTTP 501: {"error":"webwix_owner_no_session"}`.
+const SIGNED_OUT = /wixApi not enabled|session unavailable|PRINCIPAL_CHANGED|not signed in|siteNotPermitted\(requested: "account"|site account is not the bound site|webwix_owner_no_session/i;
+
+// The same classifier as `himi docs recipe-four-state`, except that a public screen with no sign-in flow shows the permission state for a sign-in failure.
+function classifyError(e: unknown): ErrorKind {
+  const msg = String((e as Error)?.message ?? e ?? "");
+  const code = String((e as { code?: unknown })?.code ?? "");
+  const status = Number(STATUS.exec(msg)?.[1] ?? 0);
+  if (status === 401) return "permission";
+  if (status === 403) return "permission";
+  if (SIGNED_OUT.test(msg)) return "permission";
+  if (code === "offline_write_blocked") return "offline"; // a write refused before it left
+  // A web call that never reached Wix arrives as
+  // `HTTP 502: {"error":"webwix_direct_failed","detail":"Failed to fetch"}` — judge its detail.
+  if (status && !msg.includes("webwix_direct_failed")) return "server";
+  if (TRANSPORT.test(msg)) return "offline";
+  return "server"; // a bug or a malformed row is not the user's connection
+}
+
 // The SearchField onChange arg shape varies by surface — read it defensively.
 function queryFrom(arg: unknown): string {
   const a = arg as { value?: string; text?: string; query?: string } | undefined;
   return String(a?.value ?? a?.text ?? a?.query ?? "");
 }
 
-async function loadList(): Promise<PostsState> {
+// Actions are not serialized: the user can type while load() is in flight, and the
+// action that finishes last writes the whole state. So the latest query lives outside
+// the state, and the fetch applies it when it returns — a retry or a slow first load
+// never throws away what the user typed.
+let currentQuery = "";
+
+async function loadList(s: Partial<PostsState>): Promise<PostsState> {
   try {
     const res = await queryPosts({ query: { paging: { limit: 100 } } });
     const all = ((res as { posts?: WixPost[] }).posts ?? [])
       .map(normalize)
       .filter((r) => r.id);
-    return shape({ status: "ready", all, query: "" });
+    return shape({ status: "ready", all, query: currentQuery });
   } catch (e) {
-    return shape({ status: "error", all: [], error: String((e as Error)?.message ?? e) });
+    const errorKind = classifyError(e);
+    // Keep what was loaded on a refresh failure; clear it when access is gone.
+    const all = errorKind === "permission" ? [] : s.all ?? [];
+    return shape({ status: "error", all, query: currentQuery, errorKind });
   }
 }
 
@@ -97,17 +147,29 @@ const svc = defineService<PostsState, {
 }>("posts", {
   state: shape({ status: "loading" }),
   actions: {
-    load: async () => loadList(),
-    retry: async () => loadList(),
+    // `load` opens the screen, and the uncontrolled SearchField opens empty: start the
+    // query over too. A query typed while this fetch is in flight still wins.
+    load: async (s) => { currentQuery = ""; return loadList(s); },
+    retry: async (s) => loadList(s),
     // In-worker filter: swap what the bound `items` path holds. For datasets past
     // a few hundred rows, make this re-query the API instead (same descriptor).
     search: (s, arg) => {
       const query = queryFrom(arg);
+      currentQuery = query;
       return shape({ ...s, query, items: visible(s.all, query) });
     },
-    clear: (s) => shape({ ...s, query: "", items: s.all }),
+    clear: (s) => { currentQuery = ""; return shape({ ...s, query: "", items: s.all }); },
   },
 });
 
+// The SearchField is uncontrolled and shows empty on a cold boot, but the runtime restores the
+// persisted snapshot: last run's `query`, and the `items` and empty flags derived from it. Re-derive
+// them in place for an empty query before anything paints, or the list stays filtered by text the
+// field does not show until the first fetch settles.
+const booted = (svc as unknown as { getState?: () => Record<string, unknown> | undefined }).getState?.();
+if (booted && typeof booted === "object") {
+  Object.assign(booted, shape({ ...(booted as Partial<PostsState>), query: "", items: undefined }));
+}
+
 svc.load(); // fetch once at boot; searching never re-fetches
 export { svc };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1465.0",
+  "version": "0.1466.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "19e0653508dd0a35a2413578ca22c6452471d39f3797b2cd827fb652"
+  "falconPackageHash": "45c573391083ede76066e2c3b621e23db07135b7ad8781d653f59629"
 }