@wix/himalaya-cli 0.960.0 → 0.962.0

package/templates/beauty-salon-owner/tier5-src/_shared/aria-widget-model.ts

@@ -0,0 +1,331 @@
+// The typed view model an Aria response widget becomes, once the envelope
+// envelope scanner has lifted it out of the assistant's prose.
+//
+// The load-bearing observation, read off the reference catalogue: EIGHT of the
+// fourteen kinds share one skeleton — `text` + `options[]` + a primary and a
+// secondary button. So this is one normalized model with variations, not
+// fourteen parsers, and the per-kind work in `aria-widget-kinds.ts` stays small.
+//
+// Everything here is PURE. No network, no worker state, no globals — which is
+// what lets the whole catalogue be tested without booting a bundle.
+
+/** The fourteen documented kinds, plus the arm that keeps the screen alive when
+ *  the service ships a fifteenth.
+ *
+ *  `UNKNOWN` is not a failure mode, it is the forward-compatibility contract:
+ *  the service can add a widget type any day, and an owner must see the
+ *  assistant's prose rather than a broken screen. The generic card upgrades
+ *  this arm
+ *  to a generic card; the contract here is only that it never throws and never
+ *  blanks. */
+export type WidgetKind =
+  | "SINGLE_SELECT"
+  | "MULTI_SELECT"
+  | "SINGLE_SELECT_BUTTON"
+  | "RADIO_BUTTON"
+  | "PLANS"
+  | "PREMIUM_UPSELL"
+  | "VISUAL_DISPLAY"
+  | "AUTOCOMPLETE"
+  | "ITEMS_SELECTION"
+  | "QUESTIONNAIRE"
+  | "CHART"
+  | "TODO_PLAN"
+  | "ASYNC_TOOL"
+  | "OAUTH_REQUIRED"
+  | "UNKNOWN";
+
+/** Every kind above, in declaration order. Exported because two other things
+ *  must agree with this union exactly and cannot read a TypeScript type at
+ *  runtime: the `FragmentSlot` case ids in the descriptor, and the
+ *  test that pins them to it. */
+export const WIDGET_KINDS: readonly WidgetKind[] = [
+  "SINGLE_SELECT",
+  "MULTI_SELECT",
+  "SINGLE_SELECT_BUTTON",
+  "RADIO_BUTTON",
+  "PLANS",
+  "PREMIUM_UPSELL",
+  "VISUAL_DISPLAY",
+  "AUTOCOMPLETE",
+  "ITEMS_SELECTION",
+  "QUESTIONNAIRE",
+  "CHART",
+  "TODO_PLAN",
+  "ASYNC_TOOL",
+  "OAUTH_REQUIRED",
+  "UNKNOWN",
+];
+
+/** One selectable row.
+ *
+ *  Every field is present and scalar, always — never optional, never null. That
+ *  is not tidiness, it is a hard requirement of the renderer: `$item.`
+ *  substitutes WHOLE prop values only, a missing field fails substitution for
+ *  the entire row, and a non-scalar stringifies to `""`. The existing transcript
+ *  bubbles already carry fixed `link1..3Label/Url/Hidden` slots for exactly this
+ *  reason (`aria-chat.ts`). A row that omits `subtitle` renders nothing at all
+ *  rather than rendering without a subtitle. */
+export interface WidgetOption {
+  title: string;
+  subtitle: string;
+  text: string;
+  value: string;
+  pictureUrl: string;
+  buttonLabel: string;
+  /** The per-option button's `respondText`, before selection substitution. */
+  respondText: string;
+  preselected: boolean;
+  /** The option button's own destination, when it has one instead of a
+   *  `respondText`. `mobileAction.link` / `.externalLink`. Raw — disclosure is
+   *  the caller's job, through the one existing helper. */
+  actionUrl: string;
+  /** `mobileAction.screen.id` — an in-app destination rather than a url. */
+  actionScreenId: string;
+  /** What to say when `actionScreenId` names a screen this app does not have.
+   *  The catalogue ships exactly that case, and dropping it left an option that
+   *  navigates nowhere and explains nothing. */
+  notSupportedText: string;
+  /** PLANS writes each plan's benefits as `list: [{text, icon}]`. Joined to one
+   *  scalar because an option row is `$item.`-templated and a nested array
+   *  substitutes as `""`; the structured form rides in `extra` for the kinds
+   *  that want icons. Empty for every other kind. */
+  listText: string;
+}
+
+/** A footer button. Same all-fields-present rule as `WidgetOption`. */
+export interface WidgetButton {
+  label: string;
+  /** What to send back when tapped, before `<SELECTED>` substitution. */
+  respondText: string;
+  /** `primaryButton.disableIfNothingSelected` — the multi-select gate. */
+  disableIfEmpty: boolean;
+  /** `mobileAction.externalLink` / `mobileAction.link`. Raw and UNCHECKED here:
+   *  disclosure is the view's job and reuses the existing `hostOf`/`isWixHost`/
+   *  `disclosedLabel` machinery in `aria-chat.ts`, which already survives the
+   *  two defeats that check was hardened against. Normalizing is not vetting,
+   *  and this
+   *  model must not grow a second URL check. */
+  externalUrl: string;
+}
+
+/** The normalized widget. One shape for all fifteen arms.
+ *
+ *  `extra` carries the per-kind fields that do not fit the shared skeleton —
+ *  chart slices, todo items, questionnaire questions, the async job id. Kept as
+ *  an untyped bag on purpose: the kinds that need it each have their own issue
+ *  and will type their own slice of it there, rather than this
+ *  file growing fourteen optional members that fourteen renderers must ignore. */
+export interface NormalizedWidget {
+  kind: WidgetKind;
+  text: string;
+  bottomText: string;
+  badge: string;
+  options: WidgetOption[];
+  primary: WidgetButton | null;
+  secondary: WidgetButton | null;
+  extra: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Reading an untrusted payload
+// ---------------------------------------------------------------------------
+//
+// Widget payloads are model-influenced content off the wire. Every reader below
+// answers with a usable value for ANY input — including `null`, an array where
+// an object was expected, and a number where a string was. Nothing here throws,
+// because the one thing worse than a widget that renders wrong is a chat screen
+// that stops rendering.
+
+/** May this url be handed to the system opener?
+ *
+ *  `http(s)` only. A widget button's destination is MODEL OUTPUT and is
+ *  reachable by prompt injection through content this owner does not control
+ *  — a review, an enquiry, a product description. The transcript's own links
+ *  are already restricted to `http(s)` by the extractor that finds them, but
+ *  a widget url arrives straight off the payload, so before this it reached
+ *  the opener after nothing but a `trim()`.
+ *
+ *  That matters more than it looks: the opener takes ANY scheme, so a payload
+ *  could name `tel:`, `sms:`, a `wix://` deep link, or a scheme some other
+ *  app on the device registered. Disclosure changes the LABEL beside the
+ *  button; it does not stop the navigation.
+ *
+ *  Exported so it can be tested directly: through the worker the guard is
+ *  INVISIBLE — a refused url and a url whose opener throws both leave the
+ *  state untouched, so a test driving the action cannot tell them apart.
+ *
+ *  Anchored and case-insensitive: `HTTPS:` is the same scheme, and
+ *  `javascript:void(0)//https://x` must not pass on a substring. */
+export function isWebUrl(url: string): boolean {
+  return /^https?:\/\//i.test(url.trim());
+}
+
+/** A plain object, or `null` for anything else — arrays included. `typeof []`
+ *  is `"object"`, so the array test is doing real work here. */
+export function objectAt(v: unknown): Record<string, unknown> | null {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+/** A display string, whether the wire wrote it bare or wrapped.
+ *
+ *  QUESTIONNAIRE writes every label as `{ text: "…" }` — question titles,
+ *  subtitles, each option's title and subtitle. Every other kind writes them
+ *  bare. Reading only the bare form turned a whole questionnaire into a shape
+ *  with the right question COUNT and no prompts or choices in it: a renderer
+ *  would have shown an empty form, and the count assertion would still pass.
+ *
+ *  Accepts either, at any depth of one. */
+export function textOf(v: unknown): string {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  const o = objectAt(v);
+  return o && typeof o.text === "string" ? o.text : "";
+}
+
+/** `textOf` for a key on a container. */
+export function textAt(o: Record<string, unknown> | null, key: string): string {
+  return o ? textOf(o[key]) : "";
+}
+
+/** A string, or `""`. Numbers and booleans are stringified — the service does
+ *  send a bare number for a value now and then, and dropping it would lose the
+ *  option's identity rather than merely its label. */
+export function stringAt(o: Record<string, unknown> | null, key: string): string {
+  if (!o) return "";
+  const v = o[key];
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return "";
+}
+
+/** A boolean, or `false`. Only a real `true` counts: a truthy string would make
+ *  `"false"` mean true, which is the wrong way for a preselection to fail. */
+export function boolAt(o: Record<string, unknown> | null, key: string): boolean {
+  return !!o && o[key] === true;
+}
+
+/** An array of plain objects, or `[]`. Non-object entries are dropped rather
+ *  than coerced: a string in an options array has no value to select by, and a
+ *  row that selects nothing is worse than a row that is not there. */
+export function objectsAt(o: Record<string, unknown> | null, key: string): Record<string, unknown>[] {
+  if (!o) return [];
+  const v = o[key];
+  if (!Array.isArray(v)) return [];
+  const out: Record<string, unknown>[] = [];
+  for (const e of v) {
+    const obj = objectAt(e);
+    if (obj) out.push(obj);
+  }
+  return out;
+}
+
+/** A badge's display text. The service sends `{text, type, skin}`; only the
+ *  text reaches the model, because `type` and `skin` are Wix-design-system
+ *  tokens with no counterpart in Himi's vocabulary. */
+export function badgeTextOf(o: Record<string, unknown> | null): string {
+  return stringAt(objectAt(o?.badge), "text");
+}
+
+/** One button, or `null` when the key is absent.
+ *
+ *  `null` rather than an empty button is the whole point: the view hides the
+ *  footer
+ *  row on `null`, and an all-empty button would paint a tappable control with no
+ *  label that sends an empty string. */
+export function buttonAt(o: Record<string, unknown> | null, key: string): WidgetButton | null {
+  const b = objectAt(o?.[key]);
+  if (!b) return null;
+  const action = objectAt(b.mobileAction);
+  return {
+    label: stringAt(b, "label"),
+    respondText: stringAt(b, "respondText"),
+    disableIfEmpty: boolAt(b, "disableIfNothingSelected"),
+    // Two spellings for one concept, and both are live in the catalogue:
+    // PREMIUM_UPSELL sends `externalLink`, CHART sends `link`.
+    externalUrl: stringAt(action, "externalLink") || stringAt(action, "link"),
+  };
+}
+
+/** The shared option skeleton — the eight-kind commonality this model is built
+ *  around. Per-kind normalizers reshape what comes out; none of them re-reads
+ *  the wire format. */
+export function optionsOf(o: Record<string, unknown> | null): WidgetOption[] {
+  return objectsAt(o, "options").map((opt) => {
+    // `button` is the usual spelling; VISUAL_DISPLAY's variant card uses
+    // `primaryButton`, the same name the widget-level footer uses.
+    const button = objectAt(opt.button) ?? objectAt(opt.primaryButton);
+    const action = objectAt(button?.mobileAction);
+    // A variant card carries its label under `sections`, not as a flat title.
+    const sections = objectsAt(opt, "sections");
+    const first = sections[0] ?? null;
+    return {
+      title: textAt(opt, "title") || textAt(first, "title"),
+      subtitle: textAt(opt, "subtitle") || textAt(first, "subtitle"),
+      text: textAt(opt, "text"),
+      value: stringAt(opt, "value"),
+      pictureUrl: stringAt(objectAt(opt.picture), "url"),
+      buttonLabel: stringAt(button, "label"),
+      respondText: stringAt(button, "respondText"),
+      preselected: boolAt(opt, "isPreselected"),
+      actionUrl: stringAt(action, "externalLink") || stringAt(action, "link"),
+      actionScreenId: stringAt(objectAt(action?.screen), "id"),
+      notSupportedText: textAt(objectAt(action?.notSupported), "description"),
+      listText: objectsAt(opt, "list").map((x) => textOf(x)).filter(Boolean).join("\n"),
+    };
+  });
+}
+
+/** An empty widget of the given kind. The base every normalizer starts from, and
+ *  the answer for a payload that could not be read at all. */
+export function emptyWidget(kind: WidgetKind, text = ""): NormalizedWidget {
+  return { kind, text, bottomText: "", badge: "", options: [], primary: null, secondary: null, extra: {} };
+}
+
+// ---------------------------------------------------------------------------
+// `<SELECTED>` substitution
+// ---------------------------------------------------------------------------
+
+/** The tokens the service writes into a `respondText` where the owner's choice
+ *  belongs: `"Use <SELECTED>"` becomes `"Use Sunny Deals"`.
+ *
+ *  TWO spellings, both live in the reference catalogue — `<SELECTED>` five
+ *  times, `<VALUES>` three (RADIO_BUTTON's primary button, and each PLANS
+ *  option's). Handling only the first sent the owner's own words back with
+ *  `<VALUES>` still in them, which is the failure mode this substitution
+ *  exists to prevent, just wearing the other name. */
+export const SELECTED_TOKEN = "<SELECTED>";
+export const VALUES_TOKEN = "<VALUES>";
+/** Matches either. A regex for `split` only — never for `replace`, whose `$`
+ *  semantics are the reason this is a split in the first place. */
+const SELECTION_TOKENS = /<SELECTED>|<VALUES>/g;
+
+/** Put the selection into a `respondText`.
+ *
+ *  Lives here, as a pure string function, rather than in the worker — so the
+ *  cases that actually bite can be tested exhaustively without booting a bundle.
+ *
+ *  Three decisions worth stating, because each is a case the naive version gets
+ *  wrong:
+ *
+ *  - **`split`/`join`, not `replaceAll`.** The replacement is a selected VALUE:
+ *    model-influenced text off the wire. `String.replaceAll` reads `$` in its
+ *    replacement as a SUBSTITUTION PATTERN, so a value containing `$&` splices
+ *    the matched `<SELECTED>` back in, `` $` `` splices the text before it, and
+ *    `$$` collapses to one `$`. A price like `"$5 $& up"` would come back
+ *    mangled. `split`/`join` has no such syntax and inserts the value literally.
+ *    (It is NOT about re-scanning: `replaceAll` with a string replacement does
+ *    not re-read its own output, so a value merely containing the literal
+ *    `<SELECTED>` is safe either way. An earlier draft of this comment claimed
+ *    otherwise and the mutation test proved it wrong.)
+ *  - **No token means no substitution.** The service sends plenty of
+ *    `respondText` values with no placeholder at all; they are sent verbatim.
+ *  - **An empty selection collapses the token** rather than leaving it visible.
+ *    Sending the owner's own words back with `<SELECTED>` still in them is the
+ *    one outcome that reads as a bug to the person who sees it. */
+export function substituteSelection(respondText: string, selected: string[]): string {
+  if (!respondText) return "";
+  const parts = respondText.split(SELECTION_TOKENS);
+  if (parts.length === 1) return respondText;
+  return parts.join(selected.join(", "));
+}