@wix/himalaya-cli 0.942.0 → 0.944.0

package/guides/component-reference.json

@@ -101,7 +101,7 @@
       "bindings": [
         "text"
       ],
-      "propsSource": "export type TextProps = TextContent & {\n  style?: TokenName;\n  /** Foreground color token (default \"textPrimary\"). */\n  color?: TokenName;\n  /** Tail-truncate after N lines (absent = unlimited). */\n  maxLines?: number;\n  /** Lever D — a live time value (countdown/relative) the OS ticks with no refresh.\n   *  When present it OVERRIDES `text`. Widget-safe render only. */\n  timeRef?: WidgetTimeRef;\n  /** Render `text` as a constrained Markdown subset. */\n  markdown?: boolean;\n  /** Capability enrichments. */\n  textAlign?: \"leading\" | \"center\" | \"trailing\" | \"justify\";\n  /** Base writing direction. \"auto\" (or \"rtl\") makes a bidi paragraph resolve +\n   *  align by its own strong-directional content (Hebrew/Arabic → right-aligned,\n   *  RTL layout), matching per-message direction in chat bubbles. Absent/\"ltr\" =\n   *  the current left-to-right behavior. Both renderers honor it (parity). */\n  textDirection?: \"auto\" | \"ltr\" | \"rtl\";\n  decoration?: \"underline\" | \"strikethrough\";\n  lineSpacing?: number;\n  /** Per-item gate (usually an `$item.` field pre-substituted per row): when it\n   *  resolves empty, the text collapses to zero size instead of taking layout. */\n  collapseWhenEmpty?: boolean;\n  /** Motion grammar (Batch 1, item 4) — count-up tween for a numeric value on\n   *  change; non-numeric values render instantly. Gated by reduced motion. */\n  animateValue?: boolean;\n  /** Motion grammar — reveal the (post-substitution literal) text word-by-word,\n   *  once per distinct content, like a chat assistant \"typing\" its reply. Each\n   *  content animates a single time (progress is remembered), so list re-renders\n   *  and scrolls don't restart it. Gated by reduced motion (snaps to full).\n   *  Both renderers honor it (parity). Default nil/false. */\n  animateReveal?: boolean;\n};"
+      "propsSource": "export type TextProps = TextContent & {\n  style?: TokenName;\n  /** Foreground color token (default \"textPrimary\"). */\n  color?: TokenName;\n  /** Tail-truncate after N lines (absent = unlimited). */\n  maxLines?: number;\n  /** Lever D — a live time value (countdown/relative) the OS ticks with no refresh.\n   *  When present it OVERRIDES `text`. Widget-safe render only. */\n  timeRef?: WidgetTimeRef;\n  /** Render `text` as a constrained Markdown subset. */\n  markdown?: boolean;\n  /** Capability enrichments. */\n  textAlign?: \"leading\" | \"center\" | \"trailing\" | \"justify\";\n  /** Base writing direction. \"auto\" (or \"rtl\") makes a bidi paragraph resolve +\n   *  align by its own strong-directional content (Hebrew/Arabic → right-aligned,\n   *  RTL layout), matching per-message direction in chat bubbles. Absent/\"ltr\" =\n   *  the current left-to-right behavior. Both renderers honor it (parity). */\n  textDirection?: \"auto\" | \"ltr\" | \"rtl\";\n  decoration?: \"underline\" | \"strikethrough\";\n  /** EXTRA SPACE BETWEEN LINES, in points/px — added ON TOP of the line height the `style`\n   *  token already sets. It is NOT a multiple: `lineSpacing: 6` means six points of extra\n   *  leading, not six times the font size, and every renderer agrees on that. To\n   *  change the line height as a ratio of the font size, set the typography token's `line`\n   *  instead; that is where a body style's 1.4/1.7 lives. Absent/0 = the token's own line\n   *  height, which is the right answer for almost every screen. */\n  lineSpacing?: number;\n  /** Per-item gate (usually an `$item.` field pre-substituted per row): when it\n   *  resolves empty, the text collapses to zero size instead of taking layout. */\n  collapseWhenEmpty?: boolean;\n  /** Motion grammar (Batch 1, item 4) — count-up tween for a numeric value on\n   *  change; non-numeric values render instantly. Gated by reduced motion. */\n  animateValue?: boolean;\n  /** Motion grammar — reveal the (post-substitution literal) text word-by-word,\n   *  once per distinct content, like a chat assistant \"typing\" its reply. Each\n   *  content animates a single time (progress is remembered), so list re-renders\n   *  and scrolls don't restart it. Gated by reduced motion (snaps to full).\n   *  Both renderers honor it (parity). Default nil/false. */\n  animateReveal?: boolean;\n};"
     },
     {
       "name": "Image",
@@ -139,6 +139,44 @@
         "focusPath",
         "errorPath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "string",
+          "note": "The typed text, clamped to maxLength by the renderer.",
+          "divergences": [
+            {
+              "arms": [
+                "ios",
+                "android",
+                "web"
+              ],
+              "kind": "additive",
+              "actual": "additionally injects `fieldId` when the text field is inside a Form, so one worker action can serve several fields.",
+              "reason": "Additive, not conflicting, and shipped bundles already duck-type it. Every arm guards on the field actually being registered in a Form, so a standalone TextField still sends no `fieldId`. Still a divergence rather than a promoted contract key because RN does not send it and the contract does not require it."
+            }
+          ]
+        },
+        {
+          "callback": "onSubmit",
+          "key": "value",
+          "encoding": "string",
+          "note": "The field's current text at return-key time.",
+          "divergences": [
+            {
+              "arms": [
+                "ios",
+                "android",
+                "web"
+              ],
+              "kind": "additive",
+              "actual": "additionally injects `fieldId` when the text field is inside a Form, so one worker action can serve several fields.",
+              "reason": "Additive, not conflicting, and shipped bundles already duck-type it. Every arm guards on the field actually being registered in a Form, so a standalone TextField still sends no `fieldId`. Still a divergence rather than a promoted contract key because RN does not send it and the contract does not require it."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface TextFieldProps {\n  placeholder?: string;\n  /** LITERAL initial text. Renderers paint it verbatim — a `$service:` sentinel\n   *  here shows the raw token to the user. Bind `valuePath` instead. */\n  value?: string;\n  /** `$service:`/`$item.` binding → live text from the worker (overrides `value`).\n   *  Adopted while the field is NOT focused; an empty worker value (a draft reset\n   *  after send/post/submit) is adopted even mid-focus, so a cleared draft empties\n   *  the field without the worker ever fighting the caret. */\n  valuePath?: string;\n  onChange?: Action;\n  /** Text input enrichments. */\n  keyboard?: Keyboard;\n  secure?: boolean;\n  multilineMaxLines?: number;\n  maxLength?: number;\n  autoCapitalization?: AutoCapitalization;\n  onSubmit?: Action;\n  /** Keyboard control. `suggestions: \"off\"` kills autocorrect + the suggestion\n   *  strip. `submitLabel` paints the return key and, with `onSubmit`, fires it —\n   *  submitting dismisses the keyboard except for `\"next\"`, which keeps it up so\n   *  a worker can move focus on. */\n  suggestions?: Suggestions;\n  submitLabel?: SubmitLabel;\n  /** `$service:` binding → a TOKEN the worker changes to focus this field. Focus\n   *  is requested whenever the resolved value becomes a new NON-EMPTY value\n   *  (the first seed included, so a non-empty init focuses on open). Use a\n   *  monotonic nonce — `String(Date.now())` — since a latched boolean cannot\n   *  re-fire. Blur is the keyboard-dismiss capability, not a token here. */\n  focusPath?: string;\n  /** Accessory & state enrichments. */\n  leadingIcon?: IconRef;\n  trailingIcon?: IconRef;\n  clearButton?: boolean;\n  helperText?: string;\n  error?: boolean;\n  prefix?: string;\n  suffix?: string;\n  /** Drop the default rounded-border chrome so a caller background shows (composer pill). */\n  borderless?: boolean;\n  /** Declarative syntactic rules the RENDERER evaluates, so they hold with no\n   *  worker running (Tier 0-4) and with no bridge round-trip. Before this,\n   *  validation was reachable only by wrapping the field in `Form` -> `FormField`\n   *  - the shape the design guide steers you away from for hero flows. */\n  validation?: Validation;\n  /** `$service:`/`$item.` binding -> a worker-computed error string. Non-empty =\n   *  invalid. This is how SEMANTIC and CROSS-FIELD errors (\"passwords don't\n   *  match\", \"email taken\") reach the same error slot, with the same styling and\n   *  a11y wiring, as the declarative ones. Wins over `validation.message`. */\n  errorPath?: string;\n  /** LITERAL error string for a server-rendered screen with no worker to bind.\n   *  Lower precedence than `errorPath`, higher than the rules. */\n  errorText?: string;\n}"
     },
     {
@@ -148,6 +186,23 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "boolean",
+          "note": "The NEXT state, not the previous one.",
+          "divergences": [
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "additive",
+              "actual": "additionally injects `fieldId` when the control is inside a Form — via bindingForBool, for a Toggle nested in a FormField."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface ToggleProps {\n  label?: string;\n  value: boolean;\n  /** `$service:`/`$item.` binding → a live bool (overrides `value`). */\n  valuePath?: string;\n  onChange?: Action;\n  /** #1047 — ON-state track color token (default: `accentPrimary`). Setting any\n   *  appearance prop switches to a custom-drawn control so a host can match its own\n   *  switch and keep the screen OTA (vs the `intents:` escape hatch). */\n  trackOn?: TokenName;\n  /** #1047 — OFF-state track color token (default: system/`surfaceTertiary`). */\n  trackOff?: TokenName;\n  /** #1047 — thumb color token (default: white). */\n  thumb?: TokenName;\n  /** #1047 — track width (pt/dp/px). Absent = system size. */\n  width?: number;\n  /** #1047 — track height (pt/dp/px). Absent = system size. */\n  height?: number;\n}"
     },
     {
@@ -157,6 +212,25 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "int",
+          "note": "The clamped next value. A no-change step must not dispatch.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "rn"
+              ],
+              "kind": "params-mirror",
+              "actual": "mirrors the value into `params` as a NUMBER.",
+              "reason": "Violates rule 2 — `Action.params` is `map<string,string>`. Harmless through the JS hosts, wrong on the wire."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface StepperProps {\n  value: number;\n  /** `$service:`/`$item.` binding → a live integer (overrides `value`). */\n  valuePath?: string;\n  min?: number;\n  max?: number;\n  onChange?: Action;\n}"
     },
     {
@@ -238,6 +312,24 @@
       "category": "Form primitives",
       "propsType": "PickerProps",
       "bindings": [],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedId",
+          "encoding": "string",
+          "note": "The chosen option's id — an enum the reducer switches on, never an index.",
+          "divergences": [
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "probe",
+              "actual": "inside a FormField, the non-text kinds store into the form bag and RETURN without dispatching — the renderer's own code.",
+              "reason": "A formField({kind:'picker'}) onChange is a dead action on iOS while every other arm fires it."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "optionsPath",
@@ -256,6 +348,39 @@
       "category": "Form primitives",
       "propsType": "DatePickerProps",
       "bindings": [],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "unix-seconds-string",
+          "note": "Unix SECONDS, string-encoded so the params mirror stays legal. iOS ships `valueUnix` as an int instead; RN ships nothing. The normative key is `value` because that is what three of four arms already use for every other scalar control.",
+          "divergences": [
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "wrong-key",
+              "actual": "sends `valueUnix` as an int instead of the contract's `value`.",
+              "reason": "Only web conforms. This is the widest split in the vocabulary and the clearest argument for the file."
+            },
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "no-payload",
+              "actual": "dispatches the bare action with no date at all."
+            },
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "probe",
+              "actual": "inside a FormField, the non-text kinds store into the form bag and RETURN without dispatching — the renderer's own code.",
+              "reason": "A formField({kind:'picker'}) onChange is a dead action on iOS while every other arm fires it."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "mode",
@@ -308,6 +433,20 @@
       "category": "Search & filter",
       "propsType": "SearchFieldProps",
       "bindings": [],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "string",
+          "note": "Debounced by `debounceMs` before dispatch."
+        },
+        {
+          "callback": "onSubmit",
+          "key": "value",
+          "encoding": "string",
+          "note": "These two rows share a control and key, so they are NOT independently gated: a payload observation cannot say which callback produced it, and a helper-mediated dispatch does not name the callback at the write site at all. The gate proves the callback is still referenced in the component that dispatches, not that this callback carries the payload."
+        }
+      ],
       "propsSource": "export interface SearchFieldProps {\n  placeholder?: string;\n  value?: string;\n  onChange?: Action;\n  onSubmit?: Action;\n  debounceMs?: number;\n}"
     },
     {
@@ -318,6 +457,24 @@
         "optionsPath",
         "selectedIds"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedIds",
+          "encoding": "string-array",
+          "note": "The full selection AFTER the toggle, not the chip that moved.",
+          "divergences": [
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "params-mirror",
+              "actual": "mirrors `selectedIds` into `params` as an ARRAY.",
+              "reason": "Rule-2 violation."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface FilterChipsProps {\n  chips: FilterChip[];\n  /** Literal ids, or a binding-aware `$service:`/`$item.` live selection. */\n  selectedIds?: string[];\n  multiSelect?: boolean;\n  onChange?: Action;\n  /** `$service:` binding → a live options array (overrides `chips`). */\n  optionsPath?: string;\n}"
     },
     {
@@ -329,6 +486,13 @@
         "activeColorPath",
         "selectedId"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedId",
+          "encoding": "string"
+        }
+      ],
       "notImplemented": {
         "props": [
           "style"
@@ -349,6 +513,13 @@
         "optionsPath",
         "selectedId"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedId",
+          "encoding": "string"
+        }
+      ],
       "propsSource": "export interface SegmentedControlProps {\n  options: TabItem[];\n  /** Literal id, or a binding-aware `$service:`/`$item.` live selection. */\n  selectedId: string;\n  onChange?: Action;\n  /** `$service:` binding → a live options array (overrides `options`). */\n  optionsPath?: string;\n}"
     },
     {
@@ -456,6 +627,40 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "double",
+          "note": "Range mode additionally sends `upperValue`.",
+          "divergences": [
+            {
+              "arms": [
+                "web"
+              ],
+              "kind": "no-payload",
+              "actual": "dispatches the bare action — the renderer's own code — with no injected value."
+            },
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "no-payload",
+              "actual": "renders a static visual and never dispatches at all.",
+              "reason": "RN Slider is unimplemented rather than divergent; listed so the gap is counted, not hidden."
+            },
+            {
+              "arms": [
+                "ios",
+                "android"
+              ],
+              "kind": "additive",
+              "actual": "range mode additionally sends `upperValue` beside `value`.",
+              "reason": "Additive, and the contract's Slider note already describes it. Same problem as groupId: allowed by a hard-coded list rather than declared."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "debounceMs"
@@ -475,6 +680,38 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "boolean",
+          "note": "The next checked state. iOS additionally sends `groupId` for radio groups.",
+          "divergences": [
+            {
+              "arms": [
+                "web"
+              ],
+              "kind": "no-payload",
+              "actual": "dispatches the bare action — the renderer's own code — with no injected value."
+            },
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "params-mirror",
+              "actual": "mirrors the value into `params` as a BOOLEAN."
+            },
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "additive",
+              "actual": "additionally sends `groupId` so a radio group can identify which set changed.",
+              "reason": "Additive, not conflicting. It was previously hard-coded as an allowed key in the gate, which put it outside the contract — the one place this PR claims is the single source of truth."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface SelectionControlProps {\n  label?: string;\n  value?: boolean;\n  kind?: \"checkbox\" | \"radio\";\n  /** Radios sharing a `groupId` are mutually exclusive. */\n  groupId?: string;\n  onChange?: Action;\n  /** \"$service:\"/\"$item.\" binding → bool (overrides `value`). */\n  valuePath?: string;\n  disabled?: boolean;\n  /** Checkbox tri-state (renders a dash); ignored for radio. */\n  indeterminate?: boolean;\n}"
     },
     {
@@ -592,6 +829,23 @@
       "bindings": [
         "valuesPath"
       ],
+      "dispatches": [
+        {
+          "callback": "onRemove",
+          "key": "value",
+          "encoding": "string",
+          "note": "The removed chip's value.",
+          "divergences": [
+            {
+              "arms": [
+                "web"
+              ],
+              "kind": "no-payload",
+              "actual": "dispatches the bare action — the renderer's own code — with no injected value."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "onAdd"
@@ -660,6 +914,41 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "int",
+          "note": "1-based star index.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "rn"
+              ],
+              "kind": "params-only",
+              "actual": "writes the value into `params` ONLY, never `args`.",
+              "reason": "Survives only because the Tier-5 hosts merge params into args. Any consumer reading `args` — which rule 1 says is the payload map — gets nothing."
+            },
+            {
+              "arms": [
+                "ios"
+              ],
+              "kind": "encoding",
+              "actual": "sends `value` as .double where the contract says int."
+            },
+            {
+              "arms": [
+                "web",
+                "rn"
+              ],
+              "kind": "params-mirror",
+              "actual": "stringifies the 1-based index into `params` (`String(i + 1)`) for a control the contract declares `int`.",
+              "reason": "Rule 2 permits a params mirror only for string-encoded values, and Rating is int. The earlier expression heuristic missed it because `String(i + 1)` does not look like a literal — it surfaced only once rule 2 keyed off the declared encoding."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface RatingProps {\n  value?: number;\n  max?: number;\n  interactive?: boolean;\n  onChange?: Action;\n  color?: TokenName;\n  icon?: IconRef;\n  valuePath?: string;\n}"
     },
     {
@@ -744,6 +1033,31 @@
         "optionsPath",
         "selectedId"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "selectedId",
+          "encoding": "string",
+          "divergences": [
+            {
+              "arms": [
+                "rn"
+              ],
+              "kind": "params-wrong-key",
+              "actual": "writes `params.value = String(id)` but `args.selectedId = id` — a different key in each map.",
+              "reason": "Conforms on `args` (rule 1) but the params mirror uses the wrong key, so a params-reading consumer sees a key no other arm sends."
+            },
+            {
+              "arms": [
+                "web"
+              ],
+              "kind": "no-payload",
+              "actual": "renders a static window of options and never dispatches — the case has no onAction.",
+              "reason": "Unimplemented on web rather than divergent. Surfaced by the missing-site assertion; the other four it reported were blind spots in the scan, now fixed."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface WheelPickerProps {\n  options?: PickerOption[];\n  /** Literal option id, or binding-aware `$service:`/`$item.` live id. */\n  selectedId?: string;\n  onChange?: Action;\n  optionsPath?: string;\n}"
     },
     {
@@ -753,6 +1067,25 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "string",
+          "note": "Hex, including the leading '#'.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "rn"
+              ],
+              "kind": "params-only",
+              "actual": "writes the value into `params` ONLY, never `args`.",
+              "reason": "Survives only because the Tier-5 hosts merge params into args. Any consumer reading `args` — which rule 1 says is the payload map — gets nothing."
+            }
+          ]
+        }
+      ],
       "propsSource": "export interface ColorPickerProps {\n  value?: string;\n  onChange?: Action;\n  swatches?: string[];\n  label?: string;\n  valuePath?: string;\n}"
     },
     {
@@ -762,6 +1095,44 @@
       "bindings": [
         "valuePath"
       ],
+      "dispatches": [
+        {
+          "callback": "onChange",
+          "key": "value",
+          "encoding": "string",
+          "note": "The assembled code. Only RN dispatches today; web, iOS and Android render the boxes read-only.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "ios",
+                "android"
+              ],
+              "kind": "no-payload",
+              "actual": "renders the digit boxes without wiring onChange — the control dispatches nothing.",
+              "reason": "Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it."
+            }
+          ]
+        },
+        {
+          "callback": "onComplete",
+          "key": "value",
+          "encoding": "string",
+          "note": "Fires once the last box is filled, carrying the same assembled code as onChange. Declared separately because it is a second public callback — leaving it out left one outside the contract.",
+          "divergences": [
+            {
+              "arms": [
+                "web",
+                "ios",
+                "android"
+              ],
+              "kind": "no-payload",
+              "actual": "renders the digit boxes without wiring onChange — the control dispatches nothing.",
+              "reason": "Unimplemented rather than divergent, but it must be declared: leaving OtpInput out of the contract is what let the gate whitelist RN's payload without checking it."
+            }
+          ]
+        }
+      ],
       "notImplemented": {
         "props": [
           "onChange",