@wix/himalaya-cli 0.1007.0 → 0.1008.0

package/guides/component-reference.json

@@ -126,9 +126,10 @@
       "category": "Core",
       "propsType": "ButtonProps",
       "bindings": [
+        "disabledPath",
         "title"
       ],
-      "propsSource": "export interface ButtonProps {\n  /** Button label — binding-aware (\"$item.\"/\"$service:\") on web, iOS and Android. */\n  title: string;\n  action: Action;\n  style?: string;\n  /** Literal only, NOT bindable: a `\"$service:…\"` string here fails `validate`, and there is no\n   *  `disabledPath`. To disable from worker state, author two buttons — the live one and a\n   *  `disabled: true` copy — and swap them with complementary `modifiers.hiddenPath` flags\n   *  (e.g. `canSubmit` / `cannotSubmit`); also guard the action so a stray tap is a no-op. */\n  disabled?: boolean;\n  /** Capability enrichments. */\n  leadingIcon?: IconRef;\n  trailingIcon?: IconRef;\n  loading?: boolean;\n  size?: \"sm\" | \"md\" | \"lg\";\n  fullWidth?: boolean;\n  iconOnly?: boolean;\n  /** #1049 — corner radius; reshapes the button (overrides the forced pill). */\n  cornerRadius?: number;\n  /** #1049 — minimum height (pt/dp/px). */\n  minHeight?: number;\n}"
+      "propsSource": "export interface ButtonProps {\n  /** Button label — binding-aware (\"$item.\"/\"$service:\") on web, iOS and Android. */\n  title: string;\n  action: Action;\n  style?: string;\n  /** LITERAL disabled state. A `\"$service:…\"` string here fails `validate` (the wire type is\n   *  bool) — bind `disabledPath` instead. */\n  disabled?: boolean;\n  /** #3117 — `$service:`/`$item.` binding → a live bool that disables the button while true\n   *  (e.g. a submit while a request is in flight). Binding-aware. OR'd with `disabled`,\n   *  `loading` and an enclosing Form's validity: a bound `false` never re-enables a button one\n   *  of those disabled, and an unresolved binding leaves the literal in charge. */\n  disabledPath?: string;\n  /** Capability enrichments. */\n  leadingIcon?: IconRef;\n  trailingIcon?: IconRef;\n  loading?: boolean;\n  size?: \"sm\" | \"md\" | \"lg\";\n  fullWidth?: boolean;\n  iconOnly?: boolean;\n  /** #1049 — corner radius; reshapes the button (overrides the forced pill). */\n  cornerRadius?: number;\n  /** #1049 — minimum height (pt/dp/px). */\n  minHeight?: number;\n}"
     },
     {
       "name": "TextField",

package/guides/component-reference.md

@@ -40,7 +40,7 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 | `Text` | Core | `text` |
 | `Image` | Core | `url`, `initials`, `contentDescription` |
 | `Icon` | Core | — |
-| `Button` | Core | `title` |
+| `Button` | Core | `disabledPath`, `title` |
 | `TextField` | Core | `valuePath`, `focusPath`, `errorPath` |
 | `Toggle` | Core | `valuePath` |
 | `Stepper` | Core | `valuePath` |
@@ -486,11 +486,14 @@ export interface ButtonProps {
   title: string;
   action: Action;
   style?: string;
-  /** Literal only, NOT bindable: a `"$service:…"` string here fails `validate`, and there is no
-   *  `disabledPath`. To disable from worker state, author two buttons — the live one and a
-   *  `disabled: true` copy — and swap them with complementary `modifiers.hiddenPath` flags
-   *  (e.g. `canSubmit` / `cannotSubmit`); also guard the action so a stray tap is a no-op. */
+  /** LITERAL disabled state. A `"$service:…"` string here fails `validate` (the wire type is
+   *  bool) — bind `disabledPath` instead. */
   disabled?: boolean;
+  /** #3117 — `$service:`/`$item.` binding → a live bool that disables the button while true
+   *  (e.g. a submit while a request is in flight). Binding-aware. OR'd with `disabled`,
+   *  `loading` and an enclosing Form's validity: a bound `false` never re-enables a button one
+   *  of those disabled, and an unresolved binding leaves the literal in charge. */
+  disabledPath?: string;
   /** Capability enrichments. */
   leadingIcon?: IconRef;
   trailingIcon?: IconRef;

package/guides/recipe-form-submit.md

@@ -158,6 +158,11 @@ shape (heading swap, `savedScreenId`, back-navigation).
   defensively (`String(v ?? "")`, `v === true`).
 - **Disable double-submit UX-side is not needed** — actions serialize per worker;
   but DO return a `saving` status if the write is slow so the UI can reflect it.
+  To grey the submit out meanwhile, keep a boolean beside it (e.g. `busy: true`
+  while the write runs) and bind the submit button's `disabledPath:
+  "$service:<svc>.busy"` — `disabledPath` wants a bool, not the `status` string.
+  It only ever ADDS a reason to be disabled: a bound `false` never re-enables a
+  submit the form's own validation is holding.
 - **`himi render` shows the initial (empty) form** — prefill bindings resolve to
   initial state; a real submit needs the pushed preview or a device drive.
 

package/guides/release-notes.md

@@ -14,6 +14,22 @@ areas, always in the same order, so you can skim for the one you care about.
 
 ---
 
+## 2026-09-24
+
+### Getting started & the CLI
+
+- **`himi template trim --keep <ids>` cuts a scaffolded template down to the screens you want,
+  then proves it still validates.** A starter template ships every screen in one generated
+  `dev/index.ts` — about 1.8 MB for `gym-fitness` and 4.5 MB for `branded-lite` — so trimming by
+  hand meant deleting blocks from that file and then hunting down every navigation row and worker
+  that still pointed at them. The command removes the other screens, their `linkableScreens`,
+  tab, drawer and deep-link entries, and the `tier5-src/` workers no kept screen uses, then runs
+  `himi validate --strict` and puts every file back if it fails. A kept screen that links to a
+  removed one is refused unless you pass `--links follow` (keep those too) or `--links drop`
+  (remove the taps), and `--dry-run` prints the plan without writing. `himi docs trim-a-template`
+  no longer tells you `validate --strict` catches a tab pointing at a deleted screen: it does not,
+  and `himi test` is what reports it. (#3149)
+
 ## 2026-09-18
 
 ### Logic, data & SDKs

package/guides/templates.md

@@ -85,7 +85,9 @@ back to the offline copy — so it never hard-fails. Then run the normal loop
 **`branded-lite` is a full reference, not a small starter.** After `himi init --template
 branded-lite`, trim it or mine it rather than deleting `tier5-src/` + `dev/` and starting from
 blank. **Trim** when most of the approved `SPEC.md` is screens the template already has: delete
-the rest. **Mine** when few of its screens match: keep the `tier5-src/_shared/` helpers and the
+the rest with `himi template trim --keep <screen ids> --links drop`, which removes the other
+screens, their navigation rows and the workers nothing else uses, and rolls back unless
+`himi validate --strict` still passes (`--dry-run` shows the plan first). **Mine** when few of its screens match: keep the `tier5-src/_shared/` helpers and the
 Wix worker chains, and write your own screens in `dev/index.ts` — the file holds every screen
 as a raw descriptor (megabytes for the full templates), so replacing it is often faster than
 editing it. Both paths, and how `dev/index.ts`, `tier5-src/`, and `navigation.linkableScreens`

package/guides/trim-a-template.md

@@ -13,7 +13,10 @@ away the live Wix wiring the template exists to give you. Vertical overlays reth
 copy/tokens; they do not shrink the screen count. There are two ways to keep that wiring:
 
 - **Trim it** when the approved `SPEC.md` is mostly screens the template already has: keep
-  those, **delete what the plan does not need** ([How to trim](#how-to-trim)).
+  those, **delete what the plan does not need**. `himi template trim --keep <ids>` does the whole
+  cut for you and proves it with `himi validate --strict`
+  ([Trim with one command](#trim-with-one-command)); the manual steps are
+  [below](#how-to-trim-by-hand) for when it refuses.
 - **Mine it** when the app's screens are its own and few template screens match — the
   realistic case for a multi-megabyte file of nested descriptors. Keep the worker layer,
   replace the screens ([Or mine it](#or-mine-it-keep-the-wix-plumbing-write-your-own-screens)).
@@ -32,10 +35,71 @@ A screen is not one file. After `himi init`, these three must agree:
 | `dev/index.ts` `SCREENS` map | The descriptors, as raw objects. After `himi init` the file is **yours** ("this file is yours now") — edit it, cut it down, or replace it. |
 | `config.ts` `navigation.linkableScreens` | Deep-link / tab targets. `himalaya://screen/<id>` resolves **only** if the id is listed here. Tab roots also appear under `navigation.tabBar.items`. |
 
-`himi validate --strict` fails if a tab/linkable id has no descriptor, or a descriptor
-has no worker when it declares `logicBundle`.
-
-## How to trim
+`himi validate --strict` fails when a descriptor declares a `logicBundle` whose worker is gone.
+It does **not** check navigation against the screens: a `tabBar` item or `linkableScreens` id
+with no descriptor passes `validate --strict` cleanly — only `himi test` reports it, as
+`nav-target-missing`. So a hand trim that forgets `config.ts` ships a tab that opens nothing,
+with a green validate. `himi template trim` checks this itself.
+
+## Trim with one command
+
+```sh
+himi template trim --keep himi_shop,himi_product,himi_cart,himi_account --dry-run      # the plan, nothing written
+himi template trim --keep himi_shop,himi_product,himi_cart,himi_account --links drop   # do it
+```
+
+Run it in (or point `--content` at) the app `himi init --template` scaffolded — not the
+template itself, which it refuses. `--keep` takes `SCREENS` ids and templated route ids (the
+part before the brackets: `himi_product` for `himi_product[_{id}]`). The home screen is always
+kept, and so is any screen the navigation pins — a drawer or sidebar body
+(`contentScreenId`, which is how the owner templates draw their menu) or a drawer header's or
+footer's target; both are listed under `implicit`. It prints one JSON report and:
+
+- **deletes** every other `SCREENS` and `TEMPLATED` entry whole, so the blocks you keep stay
+  byte for byte as they were;
+- **prunes navigation**: `linkableScreens` (a kept screen whose parent was removed is
+  re-parented to its nearest kept ancestor, and moved to a remaining tab when its tab went),
+  `tabBar`, `drawer` and `sidebar` items (a section header left with no rows goes too), deep
+  links, top-bar actions, surface destinations, and exact ids in `workerSubtreeScreens`;
+- **removes** each `tier5-src/<worker>/` no kept screen still uses. Workers are shared between
+  screens, so a worker stays as long as one kept screen points at it; `tier5-src/_shared/`
+  always stays;
+- **proves it**: runs `himi validate --strict`, and checks the rewritten navigation for any id it
+  removed. If either fails, every file and worker directory is put back exactly as it was and
+  the command exits `1`; `--force` keeps the trimmed tree anyway. While it runs, the originals
+  sit in `.himi/trim-backup/`, which is deleted once the trim validates (and kept under
+  `--force`). A failure while *writing* the trim (a worker directory it cannot move, say) is
+  always put back, `--force` or not — `--force` keeps a finished trim, never a half-done one.
+
+**Links between screens.** A kept screen that opens a removed one (a `himi.open` whose
+`screenId` is a literal) would be a dead tap, so by default the trim is **refused** — and the
+refusal lists both ways out:
+
+- `--links follow` keeps every screen the kept ones link to, as well (`addedByLinks` says which
+  link pulled each one in). On a branded home this grows quickly: the account screen alone links
+  to a dozen others.
+- `--links drop` removes the taps instead: the buttons, rows, cards, menu rows and top-bar
+  actions that open a removed screen, a list whose every row would open one, and a home
+  section that holds nothing else (its row leaves the home's modules too). Home modules for a
+  vertical whose screens you removed (a bookings "Up next" once the booking screens are gone)
+  are dropped as well. `droppedLinks` names every node it took.
+
+A screen id that is computed at runtime — `$item.detailScreenId`, or a worker building
+`"himi_product_" + id` — cannot be judged from the descriptors. The trim searches the kept
+workers' code for ids of removed screens instead and lists them under `warnings.workerRefs`
+(`tier5-src/himi-store-shop/index.ts:83 → himi_product`): add those ids to `--keep` if the tap
+should keep working.
+
+It **refuses** (exit `2`, nothing written) when `--keep` is missing or names an id the app does
+not serve (the report lists the ones it does), when the app's `dev/index.ts` or `config.ts` is
+no longer in the shape `himi init` writes (a block, the `navigation` object or
+`workerSubtreeScreens` that is not plain JSON), when kept screens link to removed ones and no `--links` was given, when no tab would be
+left, and when dropping links would leave a kept screen empty or cannot reach a link. Then trim
+by hand, below.
+
+Afterwards: `himi render <each kept screen>`, then `himi test`.
+
+## How to trim by hand
 
 1. **Inventory against `SPEC.md`.** List the screen ids you will keep (home + the
    verticals in the approved plan + account/profile if the app signs in). Everything
@@ -48,14 +112,14 @@ has no worker when it declares `logicBundle`.
    serve). Leave the file's import of `config` and the default export intact.
 4. **Remove navigation.** In `config.ts`, drop those ids from `linkableScreens`. If you
    drop a tab root, also remove its `tabBar.items` entry (keep at least one tab).
-5. **Prove it.** `himi validate --strict` then `himi render <kept-home-id>`. A leftover
-   `linkableScreens` id with no `SCREENS` key, or a `SCREENS` key whose worker dir is
-   gone, is the usual miss.
+5. **Prove it.** `himi validate --strict`, `himi render <kept-home-id>`, then `himi test`. A
+   `SCREENS` key whose worker dir is gone fails validate; a leftover `linkableScreens` or tab id
+   with no `SCREENS` key does not — `himi test` is what reports it (`nav-target-missing`).
 
-Worked example — keep Home + Shop + Account from branded-lite:
+Worked example — keep Home + Shop + Account from branded-lite (what the command above does):
 
-- Keep `tier5-src/himi-branded-lite-home/`, `himi-branded-lite-shop/` (and the store
-  workers it calls), `himi-store-account/` / `himi-branded-lite-account/`.
+- Keep `tier5-src/himi-branded-lite-home/`, `himi-store-shop/` (and the store workers it
+  calls, such as `himi-store-product/` for the product page), and `himi-store-account/`.
 - Delete bookings/events/blog/forum/CMS/spaces worker dirs you are not shipping.
 - `SCREENS` keeps `himi_branded_home`, `himi_shop`, `himi_product`, `himi_cart`,
   `himi_account`, … and drops `himi_services`, `himi_events`, …

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1007.0",
+  "version": "0.1008.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": [
@@ -65,5 +65,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "65e6a5e768e3d17f2b360d6fc1601cc92b0fff459a87b02b588c643a"
+  "falconPackageHash": "6e55785cc22d09405bcfbeb88665d72ea523bdea1bd2bcc60ea1a435"
 }