Build on-screen widgets

Widgets add script-controlled content to a session pane. They are not separate desktop windows. Start with a small view that remains useful beside fast-moving MUD output, and use the client's existing controls when they already solve the problem.

The smudgy:widgets module builds UI trees from component functions. A .tsx module can use JSX; a .ts or .js module can call the same functions directly.

import { createWidget, Column, ProgressBar, Text } from "smudgy:widgets";
 
createWidget("status", (
  <Column padding={8} spacing={4}>
    <Text color="cyan">Ready</Text>
    <ProgressBar value={75} max={100} />
  </Column>
));

createWidget() replaces any widget already mounted under the same name. removeWidget() removes it. Pass a pane through the options argument to mount somewhere other than the main pane.

Ordinary component values are snapshots. Bind shared state when a property should follow later updates:

import { vitals } from "smudgy:state/owner/prompt";
import { createWidget, ProgressBar } from "smudgy:widgets";
 
createWidget("health", (
  <ProgressBar
    value={vitals.bind("hp", { fallback: 0 })}
    max={vitals.bind("maxHp", { fallback: 100 })}
  />
));

Bindings repaint the existing widget. They do not rerun the module or remount the tree. See Shared state, events, and procedures.

• Layout: Column, Row, Stack, Container, Space, Scrollable, and Modal arrange or layer content.
• Controls: Button, Checkbox, Radio, TextEditor, and Tooltip accept input or explain an element.
• Display: Text, Markdown, ProgressBar, Table, and MapView present text, values, records, or the current map.
• Drawing: Canvas renders shape records and runs declared animations.

Use Add controls and tables to a widget for controlled inputs and tabular data. Use Draw and animate a canvas when the interface cannot be expressed clearly with the standard components.

The widget API reference lists every component and property.