UiHandle

Every failure throws a UiError whose message begins with a stable code, so a behaviour can match on the code and a log line says what went wrong without a debugger: | code | when | |---|---| | ui.screen.unknown | no screen answers to that name; the message lists the ones that do | | ui.screen.bad-json | the description does not match the contract; the message names the path | | ui.screen.duplicate | push naming a screen already on the stack, or replace naming one below the top | | ui.stack.empty | pop with nothing on the stack | | ui.set.unknown-node | no described screen holds that node id | | ui.set.unknown-prop | that property is not settable; the message lists the ones that are | | ui.set.bad-value | the property is settable and the value is the wrong kind for it | | ui.get.unknown-node | no screen on the stack holds that node id | | ui.get.unknown-prop | that property is not readable; the message lists the ones that are | | ui.get.not-a-field | a text-field property on a node of another role | | ui.locale.unknown | this project ships no locale by that name; the message lists the ones it does | | ui.unavailable | this world has no UI runtime at all | The hud screen is always the bottom entry and is written through {@link HudHandle}, not through set.

Signature

export interface UiHandle {
  /**
   * Register a screen from its description, and return its name.
   *
   * Registering a name that is already live rebuilds it in place, carrying hover, press and
   * focus across by id — the same path hot reload takes. So this is also how a screen is
   * updated wholesale.
   */
  screen(description: UiScreenDescription): string
  /**
   * Put a registered screen on top of the stack.
   *
   * `props` are the screen's own; scalar entries land on its root as `data-*`, so a stylesheet
   * can select on them, and `GET /ui/screens` reports them whole.
   */
  push(name: string, props?: Record<string, unknown>): void
  /** Take the top screen off; returns its name. */
  pop(): string
  /**
   * Pop the top screen and push this one.
   *
   * **Both halves happen or neither does.** A name that is already on the stack is refused
   * with `ui.screen.duplicate` and the stack is left exactly as it was — the runtime cannot
   * hold two instances of one name, and popping before finding that out would lose the screen
   * that was on top while the word promises to swap it. `pop()` down to it, or register the
   * second instance under its own name.
   *
   * **The screen already on top is an update.** It stays where it is and is re-rendered at
   * `props`, as a push with them would render it: nothing is popped, so nothing is lost.
   */
  replace(name: string, props?: Record<string, unknown>): void
  /** The stack, bottom first. `["hud"]` when nothing else is up. */
  stack(): string[]
  /**
   * Write one bound value.
   *
   * Takes the qualified id `GET /ui` reports (`pause:resume`) or the bare author id
   * (`resume`) when exactly one screen on the stack answers to it; an ambiguous bare id is
   * refused rather than guessed at.
   *
   * **Change-gated at the source.** The runtime holds the last value written for every node
   * and property, and a `set` that matches it does nothing at all — no restyle, no relayout,
   * no redraw. A HUD pushing its score at 60 Hz costs nothing on the fifty-nine frames where
   * the score did not change, so a behaviour should write unconditionally rather than
   * keeping its own copy to compare against.
   *
   * `null` clears the binding, and the node goes back to the value its screen was authored
   * with. A `style:` property takes the declaration's text, e.g.
   * `set("bar", "style:width", "62%")`.
   *
   * `text-param:<name>` fills one `{name}` slot of the node's string key (§2.11), e.g.
   * `set("score", "text-param:n", 3)`. **Pass a number as a number**: the plural rule
   * selects on it, so a count written as text would make the plural form depend on how the
   * behaviour spelled its own integer. The text is re-resolved in Rust, so a later
   * {@link UiHandle.setLocale} picks the right form in the new language with no script
   * involvement.
   *
   * **What is written outlives a pop.** The values a screen was `set` are remembered per
   * screen and replayed when it is pushed or replaced back onto the stack, so a menu a
   * behaviour filled in comes back filled in rather than authored. Re-registering the screen
   * with {@link UiHandle.screen} is the other half and goes the other way: a rebuild is the
   * author saying what the screen is now, so the values it carries win and everything written
   * into the old one is forgotten. Clearing one with `null` forgets it too.
   */
  set(id: string, prop: UiProp, value: string | number | boolean | null): void
  /**
   * Read one property of one node back — what a behaviour reads a text field with.
   *
   *     const name = ctx.ui.get("signin:name", "value") as string
   *
   * A read rather than an event, because nothing in this engine delivers a UI action into
   * script: a button activation goes to `WS /stream` and to the editor's feed. An
   * event-delivered value would mean an event bus built for one property, and a behaviour
   * would still keep its own copy to answer "what is in the field now". A read is always
   * current and is the mirror image of `set(id, "value", …)`.
   *
   * Takes the id either way, exactly as {@link UiHandle.set} does.
   *
   * | property | answers |
   * |---|---|
   * | `value` | what a `text-field` holds, as a string |
   * | `length` | how many **characters** it holds, which is what `maxLength` counts |
   * | `caret` | the caret's byte offset into `value` |
   * | `selection` | `[from, to]` byte offsets, or `null` when nothing is selected |
   * | `composition` | the IME preedit in flight, or `null` |
   * | `text` | any node's drawn text, resolved from its key |
   *
   * A password field answers `value` like any other: it is this screen's own script asking.
   * What a password is kept out of is `GET /ui`, which anything on the port can read.
   */
  get(id: string, prop: UiReadable): string | number | [number, number] | null
  /**
   * The locale text keys resolve at.
   *
   * `"base"` when no locale file is active — the scene's own `meta.strings`, in whatever
   * language its author wrote it.
   */
  locale(): string
  /** Every locale this project ships, `"base"` first and the rest sorted. */
  locales(): string[]
  /**
   * `"ltr"` or `"rtl"` for the active locale.
   *
   * A call rather than something a behaviour derives from the tag: which languages read right
   * to left belongs to the locale file, and a script's own table of them is a second copy
   * that goes wrong the first time a project adds one.
   */
  direction(): "ltr" | "rtl"
  /**
   * Switch language.
   *
   * Every text key on the stack is re-resolved in Rust, so this is a re-render rather than a
   * rebuild: a menu that is already up comes back in the other language with its focus, its
   * scroll position and its open dialog intact, and no behaviour runs again.
   *
   * Throws `ui.locale.unknown` when the project ships no locale by that name, with the
   * message listing the ones it does. An unknown locale changes nothing — a screenshot matrix
   * that silently rendered the base language for a locale nobody translated would report a
   * clean pass over a language that does not exist.
   */
  setLocale(tag: string): void
}

Import: import type { UiHandle } from "@argus/api"

Members

Example

The tested fixture fixtures/app/agent.ts.

import type { Behavior } from "@argus/api"

// Sends a nav agent to `props.target` once, then reports arrival through ctx.state so the
// test can read it without polling the crowd directly.
export default {
  init(ctx) {
    ctx.state.arrived = false
    ctx.nav?.goTo(ctx.props.target as [number, number, number])
  },
  update(ctx) {
    if (ctx.nav?.arrived) ctx.state.arrived = true
  },
} satisfies Behavior