@wix/himalaya-cli 0.1454.0 → 0.1455.0

package/guides/designing-himi-screens.md

@@ -195,6 +195,12 @@ long-form Ricos content rather than flattening it into text rows.*
 `Picker`/`WheelPicker`, `DatePicker`, `ColorPicker`, `OtpInput`, `ChipsInput`. *Reach for `Toggle` for
 on/off, `SelectionControl` for pick-from-set — not a row of `Button`s.*
 
+**Search** — use a dedicated search screen by default when search starts from a broader context
+(such as Home or a catalog); keep search inline when it only filters the list already on screen.
+Read `himi docs recipe-search` for the dedicated flow, including focus, debounce, result controls,
+return navigation, states, and the documented `$env:topBarSearch` fallback for clients without the
+native top-bar API.
+
 **Validation is a prop on the field, not a reason to reach for `Form`.** Put a `validation` block on
 any `TextField` — loose or wrapped — and the renderer evaluates it with no worker running and no
 round-trip:
@@ -284,7 +290,7 @@ Concrete patterns lifted from real usage:
 - **Screen root** — `withModifiers(root, { padding: { leading: 16, trailing: 16, top: 16, bottom: 40 }, background: { token: "surfacePrimary" } })`. Consistent gutter, comfortable bottom inset.
 - **Row with a leading label and trailing detail** — `hstack({ spacing: 8, children: [ icon, text, spacer(), trailingText ] })`. The `spacer()` does the push; don't hand-pad.
 - **Fill-width controls share a row** — put fill-width controls in **one** `HStack` and let them share it (weight/flex), rather than stacking `fillMaxWidth` elements. This is a real iOS↔Android parity requirement, not a preference — a full-width control alone in an HStack renders differently across platforms.
-- **A screen that owns its top bar (search beside back)** — set `topBar: { leading: "none" }` and put the row in `stickyHeader`: `hstack([ iconButton({ icon: "arrow_left", accessibilityLabel: "Back", action: { actionId: "nav.back", presentation: "back" } }), withModifiers(textField({ placeholder: "Search", … }), { weight: 1 }) ])`. With **both** set, every shell draws no bar and no back control of its own (iOS hides the system bar, Android floats no chevron and reserves no band, web hides its bar on every look), so the row is the only top bar. `leading: "none"` without a `stickyHeader` keeps the bar's title and trailing actions but drops the back control (and the hamburger, for that screen). System back — hardware, gesture, edge swipe, browser — still pops. Any other `leading` value keeps today's chrome (#3486; demo: `gallery_search_topbar`, linked from the gallery's "Lists & data").
+- **A screen that owns its top bar (search beside back)** — set `topBar: { leading: "none" }` and put the row in `stickyHeader`: `hstack([ iconButton({ icon: "arrow_left", accessibilityLabel: "Back", action: { actionId: "nav.back", presentation: "back" } }), withModifiers(textField({ placeholder: "Search", … }), { weight: 1 }) ])`. With **both** set, every shell draws no bar and no back control of its own (iOS hides the system bar, Android floats no chevron and reserves no band, web hides its bar on every look), so the row is the only top bar. `leading: "none"` without a `stickyHeader` keeps the bar's title and trailing actions but drops the back control (and the hamburger, for that screen). System back — hardware, gesture, edge swipe, browser — still pops. Any other `leading` value keeps today's chrome; demo: `gallery_search_topbar`, linked from the gallery's "Lists & data".
 - **Cell list** — `card([ vstack({ spacing: 0, alignment: "leading", children: [ …ListItem cells… ] }) ])`. `spacing: 0` because the cells own their own dividers/padding.
 - **Overlay** — `zstack({ alignment: "center", children: [ backdropImage(cornerRadius 12), withModifiers(label, { padding, background: { token: "accentPrimary" }, cornerRadius: 10 }) ] })`.
 - **Responsive** — `grid({ columns: 1, columnsMedium: 2, spacing: 12 })` for 1-up on phone / 2-up on tablet; `splitView({ primary, detail, primaryMaxWidth: 280 })` for master/detail that stacks on a phone; set `contentMaxWidth` in tokens so wide surfaces keep a readable column instead of running edge-to-edge.

package/guides/hhp.md

@@ -145,6 +145,22 @@ transitions, haptics, and measurement remain explicit native modifiers.
 
 Local HTML images resolve relative to their document and must live in the app's
 declared assets directory. They use the existing content-addressed asset channel.
+The descriptor carries a host-less `/v1/asset/<sha>?app=<id>` URL. iOS and Android
+resolve it against the origin that served the screen; on web it resolves against the page,
+so it loads when the web host is served from the serve origin (`himi run`, `/app/a/<id>`)
+but not yet behind a gateway path prefix or inside an embed.
+
+iOS and Android have no SVG image decoder. When an `<img>` points at a package
+`.svg`, the compiler renders it to a PNG at 3x the SVG's intrinsic size, writes
+the PNG to `<assets>/hhp-raster/<name>.<hash>.png` (a nested name is flattened,
+with `/` written as `__`), and references that PNG on every
+surface. The compiler owns that folder: do not edit it. It does need to be
+committed and pushed with the package. Rasterizing uses the optional image
+toolchain (`sharp`). Without it, the build reuses a committed raster, but only
+one rendered from the SVG's current bytes (the hash in its name). If no such
+raster is committed, `himi hhp lint` and `himi build` fail with
+`HHP-ASSET-SVG`. To fix it, export the image as PNG or WebP, or install `sharp`.
+Images chosen from controller state are not supported yet.
 
 ## SDKs and preview fixtures
 

package/guides/recipe-search.md

@@ -1,5 +1,130 @@
 # Recipe: search & filter a list
 
+## Choose the right search surface
+
+Use a **dedicated search screen by default** when search starts a broader discovery
+flow—for example, the user taps Search from Home or a catalog. Push the search
+screen over the current context so Back returns to the same place, and keep the
+query, sort, and filters with that search session.
+
+Use **inline filtering** when the user is already looking at a list and the query
+only narrows the rows on that screen. The rest of this recipe's original
+`SearchField` + worker example is that inline pattern.
+
+## Dedicated search screen
+
+The dedicated flow has two renderers for one search model:
+
+1. Use the native top-bar search slot (`topBar.searchable`) only when the
+   current client explicitly supports it. This proposed slot belongs in the
+   shell-owned top bar; choose `placement: "bar"` for a pushed search screen so
+   the search field sits beside Back. The slot is **not implemented in the
+   current client schema or renderers**. Treat this shape as a target API; do
+   not expect today's `himi validate` or `himi render` to recognize it.
+2. Until a client supports the slot, provide the `sticky_header` fallback
+   described below. The `$env:topBarSearch` gate hides that row only on a client
+   that actually draws native search.
+
+### Query lifecycle
+
+- **Enter and focus.** From a wider context, push the dedicated search screen
+  and give it a real Back route. With the native slot, seed `focusPath` with a
+  new non-empty token when the screen opens; that focuses the field and opens
+  the keyboard. If the screen has no worker, seed the token through local state.
+- **Debounce.** Let `onChange` update the query and start the search after the
+  user pauses. The proposed native slot uses 250 ms when `debounceMs` is zero
+  or unset; a pending change flushes before `onSubmit`, so the submitted query
+  is current.
+  For the existing inline `SearchField`, set `debounceMs` explicitly (150–300 ms
+  for local filtering; 300–400 ms for a network search).
+- **Clear.** Clear sets the query to `""`, runs `onChange` with the empty value,
+  and returns to the initial state. It is not cancellation and must not invoke
+  `onCancel`.
+- **Submit.** Use `onSubmit` for the keyboard Search action, especially when
+  requests are expensive or search should wait for an explicit commit. It
+  receives the final text as `args.value`; do not issue a duplicate request if
+  the final debounced `onChange` already did so.
+- **Results and controls.** Keep sort, filters, result count, and the result
+  list in the search screen. Bind them to the same worker state as the query.
+  Changing a filter reruns the search without losing the query; changing the
+  query should reset paging/scroll as appropriate. Keep the result count
+  consistent with the currently applied controls.
+- **Return navigation.** Use the shell's Back action to pop the search screen
+  and reveal the prior screen in its existing state. Do not replace the home or
+  catalog route to enter search. If product requirements retain a query across
+  separate visits, persist it intentionally; otherwise start a fresh session.
+
+### Screen states
+
+Model these states separately in the worker; an empty `items` array alone does
+not say why there are no rows.
+
+| State | What to show |
+| --- | --- |
+| 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. |
+| 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. |
+
+### Native slot and old-client fallback
+
+The following pairs the proposed native slot with the supported fallback. The
+`searchable` field is illustrative: current clients do not decode it. The
+`stickyHeader` root is gated, not just its search field, so the whole fallback
+row disappears when native search is drawn. `leading: "none"` lets the fallback
+own the bar on a client without the native slot. On a client that draws native
+search, the shell must interpret this as `leading: "auto"` while search is
+active so the native Back control remains visible.
+
+```ts
+const descriptor = {
+  topBar: {
+    // Native-search clients interpret this as "auto" to keep the shell Back control visible.
+    leading: "none",
+    // Proposed target API; current clients do not decode this yet.
+    searchable: {
+      placement: "bar",
+      placeholder: "Search products",
+      valuePath: "$service:search.query",
+      focusPath: "$service:search.focusToken",
+      debounceMs: 250,
+      onChange: { actionId: "tier5.search.setQuery" },
+      onSubmit: { actionId: "tier5.search.submit" },
+      onCancel: { actionId: "tier5.search.cancel" },
+    },
+  },
+  // Fallback for clients without native search. `hiddenPath` belongs on the sticky header root.
+  stickyHeader: withModifiers(hstack({
+    spacing: 4,
+    children: [
+      iconButton({
+        icon: "arrow_left",
+        accessibilityLabel: "Back",
+        action: { actionId: "nav.back", presentation: "back" },
+      }),
+      withModifiers(searchField({
+        placeholder: "Search products",
+        value: "$service:search.query",
+        debounceMs: 250,
+        onChange: { actionId: "tier5.search.setQuery" },
+      }), { weight: 1 }),
+    ],
+  }), { hiddenPath: "$env:topBarSearch" }),
+};
+```
+
+The gate is a client `$env:` value, not an app configuration flag.
+Clients that do not draw the slot leave the fallback visible. On older clients
+that must open the fallback focused, use a `TextField` with its supported
+`focusPath` and `valuePath`; `SearchField.focusPath` may not exist in those
+binaries. Keep one search row: do not add a
+second visible field outside the gated sticky header.
+
+For the simpler inline list-filter case, continue with the worker-side recipe
+below.
+
 Add a **`SearchField`** above a dynamic list and filter **in the worker** — keep
 the full result set in state, derive the visible rows from a query string. No
 network round-trip per keystroke, instant results, and the empty state can say

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1454.0",
+  "version": "0.1455.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": "eefcf19354e83f21581f78ca930495b7ae70059df5480ba579c463cb"
+  "falconPackageHash": "99c3369e91c6a783a805a9e9b70e2804c74c021c27d655ee2704c9cb"
 }