@wix/himalaya-cli 0.1525.0 → 0.1527.0

package/guides/designing-himi-screens.md

@@ -257,7 +257,7 @@ scroll. *Reach for `SegmentedControl` for 2–4 in-content modes; `Tabs`/tab-bar
 > in the *outer* column, between the pager and the bottom CTA). Its built-in indicator is faint; pair an
 > explicit `PageControl` if the dots need to read.
 
-**Feedback & overlays** — `Banner` for a persistent inline message (with a retry action when a refresh fails over content you kept; a screen with nothing to show uses an error `EmptyState`, see §5);
+**Feedback & overlays** — `Banner` for a persistent inline message (with a retry action when a refresh fails over content you kept; a screen with nothing to show uses an `ErrorState`, see §5);
 `Snackbar` for a transient confirmation; `AlertDialog` for a blocking decision; `BottomSheet` for
 contextual actions/detail; `Tooltip`/`Popover` for a small anchored hint. *Reach for `Snackbar`, not
 `AlertDialog`, to confirm a completed action — don't block on success.* The `Snackbar` COMPONENT draws
@@ -345,7 +345,7 @@ to drive them:
 |---|---|---|
 | **Loading** | `Skeleton` (shape of the eventual content) or `StatefulSection` / `ActivityIndicator` | Required on every screen that loads data asynchronously, and re-checked on every redesign. Prefer a content-shaped `Skeleton` over a bare spinner — it previews the layout. The descriptor renders against the state-skeleton, then repaints as worker state lands. See [Loading states](#loading-states-part-of-the-design) below. |
 | **Empty** | `EmptyState` (`title`, optional `icon` / `subtitle`) **plus a directive action** (`action` + `actionLabel`) | An empty screen is an invitation to act, not a dead end. Give it the next step, for example `"actionLabel": "Add your first item"`. Use `EmptyState` for **every** empty state, so all empty states in the app have the same layout and style. See [Empty states](#empty-states-one-component-one-layout) below. |
-| **Error** | Classified first. Nothing on screen: an `EmptyState` per class (`title` + `subtitle`, **no icon**, an action only for a real recovery). Rows on screen: keep them, add a `Banner` with retry. Field and action errors stay local. | Say what happened in the user's words and offer recovery only when there is one; never a blank screen or a raw error string. See [Error states](#error-states-classify-then-present) below. |
+| **Error** | Classified first. Nothing on screen: an `ErrorState` per class (user-facing `title` + `body`, a `cta` only for a real recovery). Rows on screen: keep them, add a `Banner` with retry. Field and action errors stay local. | Say what happened in the user's words and offer recovery only when there is one; never a blank screen or a raw error string. See [Error states](#error-states-classify-then-present) below. |
 | **Loaded** | the real content | The one everyone remembers to build. |
 
 Bind visibility to worker state with `hidden_path` (`$service:…`/`$item.` data-bound collapse in
@@ -433,13 +433,14 @@ its own recovery.
 | **Field validation** | A value the user typed is not valid. | Beside the field, in its own error slot (see **Inputs & forms** in §3). | "Enter a valid email." | The user corrects the field. No retry. |
 | **Action failure** | A write or a command failed (save, delete, book). | Near the action or the affected content — a line by the button, or a `danger` snackbar (`ui.snackbar({ message, tone: "danger" })`). | "Couldn't save your changes. Try again." | Keep what the user entered; the action itself is the retry. |
 
-- **A screen- or section-level error is an `EmptyState` with no icon.** Set `title` and
-  `subtitle`; leave `icon` out. Add `action` + `actionLabel` only when the user has a useful
-  recovery — retry, reload, the app's auth flow, or the site's join flow when available. Every error then has the same layout and style, as every
-  empty state does. Do not build one by hand from `Icon`, `Text` and `Button` nodes.
-- **One node per class.** iOS and Android do not resolve a `$service:` binding in `EmptyState`
-  `title` or `subtitle`, so the worker cannot swap the text. Give each class the screen can hit its
-  own `EmptyState` with literal copy or `$t:` keys, and gate each one with `hiddenPath` bound to a
+- **A screen- or section-level error is an `ErrorState`.** Set its `variant`, and `title` and
+  `body` when the default copy does not fit. Add a `cta` (with `ctaLabel` when the default label
+  does not fit) only when the user has a useful recovery — retry, reload, the app's auth flow, or
+  the site's join flow when available. Every error then has the same layout and style. Do not
+  build one by hand from `Icon`, `Text` and `Button` nodes.
+- **One node per class.** iOS and Android do not resolve a `$service:` binding in `ErrorState`
+  `title` or `body`, so the worker cannot swap the text. Give each class the screen can hit its
+  own `ErrorState` with literal copy or `$t:` keys, and gate each one with `hiddenPath` bound to a
   worker flag. The worker classifies the failure once and sets the flags — see
   `himi docs recipe-four-state` for the whole pattern.
 - **User-facing language, never the raw error.** Say what happened and what the user can do. Never
@@ -461,17 +462,41 @@ its own recovery.
 
 ```jsonc
 { "id": "orders.error.offline",
-  "body": { "package": "himalaya", "type": "EmptyState",
-    "props": { "title": "Reconnect to the internet",
-               "subtitle": "Connect to the internet, then try again.",
-               "action": { "actionId": "tier5.orders.retry" },
-               "actionLabel": "Try again" } },
+  "body": { "package": "himalaya", "type": "ErrorState",
+    "props": { "variant": "offline",
+               "cta": { "actionId": "tier5.orders.retry" } } },
   "modifiers": { "hiddenPath": "$service:orders.hideOfflineError" } }
 ```
 
-**When an `ErrorState` component ships.** A dedicated `ErrorState` component is planned. When it
-is available, use it in place of the icon-less `EmptyState`. Only the component changes: the
-classes, where each one shows, the copy rules and the recovery rules above stay the same.
+**`ErrorState` draws the same layout on iOS, Android, macOS, web and React Native:** a centred
+glyph, title, body and one primary button, with no icon tile and no card.
+
+| `variant` | Glyph | Title | Body | Button |
+|---|---|---|---|---|
+| `server` (default) | error | Unable to load this content | There was a technical issue on our end. Please wait and try again later. | Try again |
+| `offline` | wifi | Reconnect to the Internet | Connect to the internet, then try again. | Try again |
+| `permission` | error | You need permission to view this screen | none | Contact customer care |
+| `signIn` | person | Sign in to view this content | none | Sign in |
+
+- `title`, `body` and `ctaLabel` replace the copy of the variant, for example
+  `"title": "Unable to load orders"`. Site membership has no variant: use `permission` with your
+  own `title` and `body`. Write the copy as literal text or `$t:` keys: iOS and Android show a
+  `$service:` binding there as raw text, so `himi validate` refuses it.
+- `variantPath` is a `$service:` binding that selects the variant and wins over `variant`. An
+  unknown value (`membership`, `""`) keeps `variant`. It switches only the default copy and glyph:
+  `cta`, `title`, `body` and `ctaLabel` apply to every variant. So one node bound to the worker's
+  `errorKind` covers the kinds that share a button — offline and server, both **Try again** — and
+  sign-in (its own action) and permission (no button) each keep a node of their own.
+- The button draws only when you set `cta`. Leave it out for a permission error.
+- `placement` is `screen` (default, about 96px from the top) or `section` (about 24px).
+
+```jsonc
+{ "id": "orders.error",
+  "body": { "package": "himalaya", "type": "ErrorState",
+    "props": { "variantPath": "$service:orders.errorKind",
+               "cta": { "actionId": "tier5.orders.retry" } } },
+  "modifiers": { "hiddenPath": "$service:orders.hideRetryableError" } }   // offline or server
+```
 
 **Loading & empty states are first-class — use the `Skeleton` and `EmptyState` component types.**
 
@@ -546,7 +571,7 @@ Run this punch list on the screen (it's also a good reviewer checklist):
 
 - [ ] **One** primary action, on the one `accentPrimary` surface?
 - [ ] All four states designed — loading / empty / error / loaded (empty has a directive action; error has a recovery action when one exists)?
-- [ ] Errors classified (offline / server / sign-in / site membership / permission), each an icon-less `EmptyState` with user-facing copy — no raw error text? Empty results shown as empty, not as an error? A failed refresh keeps the content?
+- [ ] Errors classified (offline / server / sign-in / site membership / permission), each an `ErrorState` with user-facing copy — no raw error text? Empty results shown as empty, not as an error? A failed refresh keeps the content?
 - [ ] Loading state matches the loaded layout (a content-shaped `Skeleton` where the layout is known)? For a redesign, was the existing loading state reviewed against the new layout? A static screen has none?
 - [ ] Every value a token — zero literal hex / off-scale spacing / invented type sizes?
 - [ ] Is every user-facing string routed through a copy key with a sensible fallback (`copyOf(key, fallback)` backed by your own `COPY` map; worker strings via `onAppear` params) — none baked directly into the descriptor?

package/guides/himi-test.md

@@ -320,7 +320,7 @@ pretty report:
 "writes": [
   { "screen": "himi_blog_post", "action": "tier5.himiBlogPost.like", "via": "wix", "method": "POST", "path": "/blog/v3/posts/post-0001/like" },
   { "screen": "himi_time", "action": "tier5.himiBookingTime.register", "via": "native", "capability": "himi.wix.registerDirect", "kind": "member-signup", "what": "creates a site member" },
-  { "screen": "himi_time", "action": "tier5.himiBookingTime.bookSelected", "via": "wix", "method": "POST", "path": "/ecom/v1/checkouts" }
+  { "screen": "himi_time", "action": "tier5.himiBookingTime.pickSlot", "via": "wix", "method": "POST", "path": "/ecom/v1/checkouts" }
 ],
 "unreachedWrites": [
   { "screen": "himi_time", "action": "unreached", "via": "native", "capability": "capability.wix_cashier.proceedToPayment", "kind": "payment" }
@@ -354,12 +354,12 @@ Put the owner-approved data-access matrix in `SPEC.md` (or `MOBILE-UX.md`) as a
 | Screen | Role | Reads | Wix writes | Prohibited |
 | --- | --- | --- | --- | --- |
 | himi_blog_post | visitor | posts, comments | none | like, comment |
-| himi_time | visitor | services, slots | `bookSelected`, `POST /bookings/v2/bookings` | signup, payment |
+| himi_time | visitor | services, slots | `pickSlot`, `POST /bookings/v2/bookings` | signup, payment |
 | * | visitor | published content | none | |
 ```
 
 A `Wix writes` cell is `none` (or empty, `-`, `read-only`), or a comma list naming each approved
-write by its **action** (`bookSelected` or `tier5.himiBookingTime.bookSelected`), its **endpoint**
+write by its **action** (`pickSlot` or `tier5.himiBookingTime.pickSlot`), its **endpoint**
 (`POST /bookings/v2/bookings` — exact, with `*` for one path segment such as an id:
 `POST /blog/v3/posts/*/like`), its **capability** (`registerDirect`) or its
 **kind** (`payment`, `signup`). Prose such as "create a booking" approves nothing: it cannot say

package/guides/recipe-dynamic-list.md

@@ -157,8 +157,9 @@ A list loads data, so it ships all four states — the full idiom is
   It shows only while the first load runs with nothing on screen; a pull-to-refresh
   keeps the rows and uses the list's own spinner.
 - **Empty** — an `EmptyState` with a directive action, gated by `notEmpty`.
-- **Error, nothing on screen** — one `EmptyState` per class `classifyError` can
-  return (offline, server, sign-in, site membership, permission), **no icon**, user-facing copy.
+- **Error, nothing on screen** — one `ErrorState` per class `classifyError` can
+  return (offline, server, sign-in, site membership, permission): no icon tile or custom icon
+  (the `variant` picks the glyph), user-facing copy.
   Offline and server get **Try again** → `tier5.products.retry`; sign-in gets
   **Sign in**; membership opens the site's join flow when available; permission gets no action. A list with no sign-in flow maps
   `"signIn"` to `"permission"` — a visitor still gets a 401 or 403 (Bookings
@@ -178,10 +179,9 @@ A list loads data, so it ships all four states — the full idiom is
     "props": { "height": 72, "cornerRadius": 12, "count": 6 } },
   "modifiers": { "hiddenPath": "$service:products.hideLoading" } },
 { "id": "error.server",
-  "body": { "package": "himalaya", "type": "EmptyState",
-    "props": { "title": "Unable to load products",
-               "subtitle": "There was a technical issue on our end. Please wait and try again later.",
-               "action": { "actionId": "tier5.products.retry" }, "actionLabel": "Try again" } },
+  "body": { "package": "himalaya", "type": "ErrorState",
+    "props": { "variant": "server", "title": "Unable to load products",
+               "cta": { "actionId": "tier5.products.retry" } } },
   "modifiers": { "hiddenPath": "$service:products.hideServerError" } }
 ```
 
@@ -234,7 +234,7 @@ word:
 - **Except when page 2 loses access.** A `signIn`, `membership` or `permission` failure on
   `loadMore` is not retryable and the rows already shown are no longer the
   user's to see: clear them and go to the same sign-in, membership or
-  permission `EmptyState` a refresh uses — membership with its join action (`load()` in `himi docs recipe-four-state`). Keep
+  permission `ErrorState` a refresh uses — membership with its join action (`load()` in `himi docs recipe-four-state`). Keep
   page 1 and offer the cursor retry only for `offline` and `server`.
 - APIs that don't page (or v1 fallbacks without cursors) simply never set
   `nextCursor` — the gesture props are safe to leave in place.

package/guides/recipe-four-state.md

@@ -13,7 +13,7 @@ Every data-backed screen has four states, and Himi's idiom renders all of them
 from **one flat layout** — no conditional trees, no separate loading screen. Each
 state is its own node, gated with the `hiddenPath` modifier bound to a worker
 boolean, and the worker derives every flag from one `status` field. The empty state
-and each error class are `EmptyState` nodes, gated the same way.
+is an `EmptyState` node and each error class an `ErrorState` node, gated the same way.
 
 This is the corpus norm: of the in-repo worker bundles, ~3 in 4 model loading,
 more than half model error, and the reference apps (`apps/himi-owner-lite`,
@@ -32,7 +32,7 @@ interface State {
   // hiddenPath hides a node when its flag is TRUE — name flags in the hide direction.
   hideLoading: boolean;      // the skeleton: shown only while loading with nothing on screen
   notEmpty: boolean;         // the EmptyState: shown only when ready with zero rows
-  hideOfflineError: boolean; // one EmptyState per error class …
+  hideOfflineError: boolean; // one ErrorState per error class …
   hideServerError: boolean;
   hideSignInError: boolean;
   hideMembershipError: boolean;
@@ -141,40 +141,40 @@ only when the screen shows the user something different for it.
                "actionLabel": "Add your first product" } },
   "modifiers": { "hiddenPath": "$service:products.notEmpty" } },
 
-// Errors: an EmptyState per class, with NO icon, user-facing copy, and an action
-// only when the user can recover.
+// Errors: an ErrorState per class, with user-facing copy and a `cta` only when the
+// user can recover. `variant` picks the glyph; the authored copy wins over its default.
 { "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.products.retry" },
-               "actionLabel": "Try again" } },
+  "body": { "package": "himalaya", "type": "ErrorState",
+    "props": { "variant": "offline", "title": "Reconnect to the internet",
+               "body": "Connect to the internet, then try again.",
+               "cta": { "actionId": "tier5.products.retry" },
+               "ctaLabel": "Try again" } },
   "modifiers": { "hiddenPath": "$service:products.hideOfflineError" } },
 { "id": "error.server",
-  "body": { "package": "himalaya", "type": "EmptyState",
-    "props": { "title": "Unable to load products",
-               "subtitle": "There was a technical issue on our end. Please wait and try again later.",
-               "action": { "actionId": "tier5.products.retry" },
-               "actionLabel": "Try again" } },
+  "body": { "package": "himalaya", "type": "ErrorState",
+    "props": { "variant": "server", "title": "Unable to load products",
+               "body": "There was a technical issue on our end. Please wait and try again later.",
+               "cta": { "actionId": "tier5.products.retry" },
+               "ctaLabel": "Try again" } },
   "modifiers": { "hiddenPath": "$service:products.hideServerError" } },
 { "id": "error.signIn",
-  "body": { "package": "himalaya", "type": "EmptyState",
-    "props": { "title": "Sign in to view products",
-               "subtitle": "Your session has ended.",
-               "action": { "actionId": "tier5.products.openSignIn" },
-               "actionLabel": "Sign in" } },
+  "body": { "package": "himalaya", "type": "ErrorState",
+    "props": { "variant": "signIn", "title": "Sign in to view products",
+               "body": "Your session has ended.",
+               "cta": { "actionId": "tier5.products.openSignIn" },
+               "ctaLabel": "Sign in" } },
   "modifiers": { "hiddenPath": "$service:products.hideSignInError" } },
 { "id": "error.membership",
-  "body": { "package": "himalaya", "type": "EmptyState",
-    "props": { "title": "Join this site to view products",
-               "subtitle": "Use this site's join flow, or ask the owner for access.",
-               "action": { "actionId": "tier5.products.openJoin" },
-               "actionLabel": "Join this site" } },
+  "body": { "package": "himalaya", "type": "ErrorState",
+    "props": { "variant": "permission", "title": "Join this site to view products",
+               "body": "Use this site's join flow, or ask the owner for access.",
+               "cta": { "actionId": "tier5.products.openJoin" },
+               "ctaLabel": "Join this site" } },
   "modifiers": { "hiddenPath": "$service:products.hideMembershipError" } },
 { "id": "error.permission",           // no action: retrying gives the same answer
-  "body": { "package": "himalaya", "type": "EmptyState",
-    "props": { "title": "You need permission to view this screen",
-               "subtitle": "Ask the owner of this business for access." } },
+  "body": { "package": "himalaya", "type": "ErrorState",
+    "props": { "variant": "permission", "title": "You need permission to view this screen",
+               "body": "Ask the owner of this business for access." } },
   "modifiers": { "hiddenPath": "$service:products.hidePermissionError" } },
 
 // A refresh that failed over rows we kept: say so above the rows, keep the rows.
@@ -193,13 +193,13 @@ only when the screen shows the user something different for it.
 - Ready state is simply the data itself (the list rows, the detail fields) — it
   needs no dedicated marker.
 - **Sign in uses a real auth flow.** A renderer cannot dispatch `himi.wix.*`, so
-  the sign-in `EmptyState` calls an app action that opens its configured auth gate
+  the sign-in `ErrorState` calls an app action that opens its configured auth gate
   or sign-in screen, then reloads after authentication. Do not dispatch
   `himi.wix.signInDirect` from this button: it requires the email and password
   collected by a credential form (`himi docs wix-login-integration`).
 - **Membership is not sign-in.** `NotSiteMember` (Android: `not a member of
   site`) means the account must join this site. Route it to the membership state;
-  wire its action to the app's join/registration UI, or omit the action when no
+  wire its `cta` to the app's join/registration UI, or omit the `cta` when no
   such flow exists. A `403 WDE0027` is NOT membership: Wix Data returns it to a
   signed-in member without access too, so it stays a permission error.
 - **A 403 is a permission error** — the user lacks access and signing in again
@@ -211,29 +211,35 @@ only when the screen shows the user something different for it.
   layout — the same rows at about the same size. `StatefulSection` or
   `ActivityIndicator` are fine where they fit better. A plain `"Loading…"` `Text`
   bound to a worker string (`collapseWhenEmpty: true`) is the minimum, not the goal.
-- **Use `EmptyState` for every empty state and every screen-level error.** It
-  draws one standard layout on every platform with the app's tokens. Only `title`
-  is required. `actionLabel` is required when you set `action`: there is no
-  default label, and `himi validate` reports a missing one. For an error, leave
-  `icon` out.
-- Write the `EmptyState` title and subtitle as literal copy or `$t:` keys. Today,
-  iOS and Android do not resolve a `$service:` binding in those props — which is
-  why each error class is its own node instead of one node with bound text.
+- **Use `EmptyState` for every empty state and `ErrorState` for every screen-level
+  error.** Each draws one standard layout on every platform with the app's tokens.
+  An `EmptyState` needs `title`, and `actionLabel` whenever it has an `action` (there
+  is no default label; `himi validate` reports a missing one). An `ErrorState` needs
+  nothing: its `variant` supplies default copy and a button label.
+- Write the copy as literal text or `$t:` keys. Today, iOS and Android do not
+  resolve a `$service:` binding in those props (`himi validate` refuses one in
+  `ErrorState` copy) — which is why each error class is its own node instead of one
+  node with bound text.
 - **A node for every class `classifyError` can return** — otherwise that failure
   paints a blank screen. A screen with no sign-in flow still gets a 401 when a
   session ends; map `"signIn"` to `"permission"` in its classifier rather than drop
   the node.
-- **When a planned `ErrorState` component ships,** swap the error `EmptyState`
-  nodes for it. The classes, the copy and the recovery rules stay as they are.
+- **Fewer nodes with `variantPath`.** `variantPath: "$service:products.errorKind"`
+  switches only the default copy and glyph; `cta`, `title`, `body` and `ctaLabel`
+  apply to every variant. So `offline` and `server` can share ONE node with the retry
+  `cta` and no authored copy — gate it on one flag `shape()` sets for either
+  (`hideRetryableError: !(blank && (errorKind === "offline" || errorKind === "server"))`),
+  since `hiddenPath` takes a single boolean — while `signIn`, `permission` and
+  `membership` keep their own. See `himi docs designing-himi-screens` → Error states.
 
 ## 3. Which state when
 
 | State | Set where | User affordance |
 |---|---|---|
 | loading | initial state (`status: "loading"`) | content-shaped skeleton; NO retry |
-| error, nothing on screen | `catch` in the first load | the class's `EmptyState`: user-facing copy + a recovery action where one exists |
+| error, nothing on screen | `catch` in the first load | the class's `ErrorState`: user-facing copy + a recovery `cta` where one exists |
 | error, rows on screen | `catch` in a refresh (offline or server) | rows stay; a `Banner` with **Try again** above them |
-| sign-in, membership or permission | `catch` in any load | rows go; the class's `EmptyState` (auth flow, join flow, or no action) |
+| sign-in, membership or permission | `catch` in any load | rows go; the class's `ErrorState` (auth flow, join flow, or no `cta`) |
 | empty | derived: ready + 0 rows | say what *would* fill it, and how |
 | ready | successful fetch | the content |
 

package/guides/recipe-search.md

@@ -66,7 +66,7 @@ not say why there are no rows.
 | Results | Matching rows, result count, and the available sort/filter controls. |
 | 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 | 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, the app's auth flow for sign-in, the site's join flow for `NotSiteMember`, and no action for permission. Retain the query and controls, and keep it distinct from no matches. |
+| Error | Classified as in `himi docs recipe-four-state`: an `ErrorState` per class with user-facing copy, a Try again `cta` only for offline and server, the app's auth flow for sign-in, the site's join flow for `NotSiteMember`, and no `cta` for permission. Retain the query and controls, and keep it distinct from no matches. |
 
 ### Native slot and old-client fallback
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1525.0",
+  "version": "0.1527.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": "4d57d913fdf7e7ed0944f6605a9a5093b4fe45fb1efa09885218796d"
+  "falconPackageHash": "7d4595824e3745b02e52e9cc9c3d3b444992162a8b5792733b07a811"
 }