smudgy:widgets — Text & data display

Generated from smudgy v0.5.6 (smudgy-widgets.d.ts @ 1859aed10d75). Index: scriptref.

Display text, raster images, Markdown, progress values, tabular data, and the current session map.

Wrap a tall Table in Scrollable. For a table example, see Add controls and tables to a widget.

export function Text(props?: TextProps, children?: WidgetChildren): SmudgyElement;

A run of (optionally colored) text.

export interface TextProps {
    color?: Bindable<string>;
    size?: Bindable<number>;
    children?: WidgetChildren;
}

Props for a run of text. The children are concatenated as the text content.

• color — A CSS color string.
• size — Text size in pixels.

export function Markdown(props?: MarkdownProps, children?: WidgetChildren): SmudgyElement;

A rendered Markdown document. Children are concatenated as the Markdown source.

export interface MarkdownProps {
    size?: Bindable<number>;
    onLink?: (url: string) => void;
    children?: WidgetChildren;
}

Props for a rendered Markdown document. The children are concatenated as the source.

Styling follows the terminal color scheme. Links render as clickable command chips, and code renders monospace on a panel; a fenced block whose opening fence names a language (like js) is syntax-highlighted.

Links can stand in for MUD commands, two ways:

• Command autolink: a bare <command> renders as a command link that sends that text, so <go north> sends go north and <look> sends look. It is shorthand for [go north](<go north>). Works for word and multi-word commands; a command containing =, /, quotes, or other non-word punctuation (e.g. <say hi!>) is left as literal text; use the explicit form below for those (it also lets the visible label differ from the sent text).
• Explicit link: [label](destination). A bare destination cannot contain spaces ([north gate](go north gate) will not parse), so wrap a spaced destination in angle brackets: [north gate](<go north gate>) sends go north gate. The angle-bracket wrapper may not itself contain <, >, or a newline.

Real URLs (<http://...>) stay ordinary links, and inline code / fenced code blocks are left literal.

• size — Base text size in pixels; heading sizes scale from it. Default 16. The Markdown source itself cannot be bound (it is parsed once); render live values with Text.
• onLink — Called with a link's URL when it is clicked. Defaults to sending the URL to the current session as if typed.

export function ProgressBar(props?: ProgressBarProps, children?: WidgetChildren): SmudgyElement;

A progress/health bar.

export interface ProgressBarProps {
    min?: Bindable<number>;
    max?: Bindable<number>;
    value?: Bindable<number>;
    background?: Bindable<string>;
    color?: Bindable<string>;
    width?: Bindable<WidgetLength>;
    height?: Bindable<WidgetLength>;
    vertical?: boolean;
}

Props for a progress/health bar (a leaf – children are ignored).

• min — Range minimum (default 0).
• max — Range maximum (default 100).
• value — Current value, clamped to [min, max] (default 0).
• background — A CSS color string for the track background.
• color — A CSS color string for the filled bar.
• vertical — Render vertically (width/height are swapped). Default false.

export function Image(props: ImageProps, children?: WidgetChildren): SmudgyElement;

A raster image loaded from src. Set width/height for stable layout.

export interface ImageProps {
    src: Bindable<string>;
    width?: Bindable<WidgetLength>;
    height?: Bindable<WidgetLength>;
    content_fit?: "contain" | "cover" | "fill" | "none" | "scale-down";
    filter_method?: "linear" | "nearest";
    opacity?: Bindable<number>;
    rotation?: number;
    children?: WidgetChildren;
}

Props for a raster image (PNG/JPEG/GIF first frame/WebP; a leaf – children are ignored), loaded asynchronously by the host. While loading (or after a failure) the widget renders an empty box honoring the explicit width/height, so set both for stable layout; under the default "shrink" sizing the widget is 0x0 until the image arrives, then jumps to its intrinsic size.

src grammar:

• "icons/hp.png" / "./hp.png" – relative to the module that created the widget (matching import "./x"). ".." is allowed only in user modules; packages are descend-only and can never leave their package root.
• "@/assets/logo.png" – root-relative: the package root inside a package, or the server's modules/ directory in user scripts and inline aliases/triggers.
• "https://..." / "http://..." – remote, cached per the server's HTTP cache headers. Sandboxed packages need the host covered by their consented net permission.
• "data:image/png;base64,..." – inline bytes, capped at 2 MiB. Each distinct URI is validated and content-hashed once; a rebuilt widget pays only a small bounded re-key per build, but hoisting large data: URIs out of per-frame rebuilds (and out of bindings) is still kinder to memory.
• An absolute path – user scripts and trusted packages only (sandboxed packages need a covering read grant).

A src fed from a store binding is restricted to descend-only relative/@/ forms, data:, and http(s) – never file paths and never .. – because the binding's producer (e.g. the game, via GMCP) is not the widget's author. Failed or denied sources render the empty placeholder and log one warning; SVG sources are not supported yet.

• src — The image source (see the grammar above). Bindable: a store binding swaps the displayed image as the bound value changes.
• width — Width (pixels, "fill", or "shrink"). Default “shrink” – see the layout note above.
• height — Default “shrink”.
• content_fit — How the image fits its box: “contain” (default), “cover”, “fill”, “none”, or “scale-down”.
• filter_method — Texture sampling: “linear” (default, smooth) or “nearest” (pixel art).
• opacity — Opacity, 0..=1. Default 1.
• rotation — Rotation in degrees about the image center (floating: layout keeps the unrotated bounds).
• children — A leaf – children are ignored (present for JSX compatibility).

export function Table(props: TableProps, children?: WidgetChildren): SmudgyElement;

A data table: columns as records, rows as arrays of cells.

export type TableCell =
| SmudgyElement
| string
| number
| boolean
| Binding<any>
| null
| undefined;

One value in a table cell. Elements, text, numbers, and bindings display as content. Null, undefined, and false produce an empty cell; true displays as text.

export interface TableColumnSpec {
    header?: TableCell;
    width?: WidgetLength;
    align_x?: HorizontalAlign;
    align_y?: VerticalAlign;
}

One table column: its header plus optional layout.

• header — The header cell: text or an element.
• width — Column width. Default “shrink”.
• align_x — Horizontal alignment of the column's cells. Default “left”.
• align_y — Vertical alignment of the column's cells. Default “top”.

export interface TableProps {
    columns: TableColumnSpec[];
    rows?: TableCell[][];
    width?: Bindable<WidgetLength>;
    padding?: number;
    separator?: number;
    children?: WidgetChildren;
}

Props for a data table (a leaf; children are ignored).

Supply each row as an array in column order. A bound cell repaints when its value changes. Re-mount the widget when rows are added, removed, or reordered. A row with more cells than columns is invalid; a shorter row is padded with empty cells. Wrap a tall table in Scrollable.

• columns — The columns, in order. Required and non-empty.
• rows — The rows, each an array of cells in column order.
• padding — Cell padding in pixels, both axes.
• separator — Separator line thickness in pixels, both axes.

export function MapView(props?: MapViewProps, children?: WidgetChildren): SmudgyElement;

The map view for the current session.

export interface MapViewProps {
    // View-global knobs, meaningless per-item, so not in MapStyle.
    roomSpacing?: Bindable<number>;
    playerColor?: Bindable<string>;
    showDoors?: Bindable<boolean>;
 
    defaultStyle?: Bindable<MapStyle>;
    styles?: Record<string, MapStyle>;
    apply?: Bindable<MapStyleApplication[]>;
    doors?: Bindable<MapDoorState[]>;
    children?: WidgetChildren;
}

Props for the map view (a leaf). The static styles palette names each look once; apply associates palette entries with rooms/exits and is the intended store-bound hot path (small payloads, no re-mount, zoom/pan preserved).

• roomSpacing — Multiply room coordinates while keeping room glyphs the same size. Default 1.
• showDoors — Render persisted or overridden closed/locked door state. Default true.
• styles — The static named-style palette apply entries reference.

export interface MapStyle {
    roomFill?: string;
    roomStroke?: string;
    roomStrokeWidth?: number;
    roomOpacity?: number;
    roomBorderRadius?: number;
    connectionColor?: string;
    connectionWidth?: number;
    connectionOpacity?: number;
    doorColor?: string;
    crossAreaLabelVisibility?: "always" | "hover" | "never";
    crossAreaLabelBackground?: string;
}

Presentation channels for individual rooms, connections, and doors. Absent fields inherit defaultStyle, then the widget default. Colors are CSS color strings. Nothing here modifies or syncs the underlying map.

• roomOpacity — Multiplies the whole room glyph's opacity. Clamped to 0..=1.
• roomBorderRadius — Rounded-room corner radius in map units, clamped to 0..0.25.
• connectionOpacity — Multiplies the whole connection, including markers and doors. Clamped to 0..=1.
• crossAreaLabelVisibility — When to draw named and redacted cross-area destination labels. The connection stub and marker remain visible. Default “always”.
• crossAreaLabelBackground — Optional CSS color for a padded background behind cross-area labels.

export interface MapExitRef {
    room: RoomNumber;
    direction: ExitDirection;
}

One Connection selected from either endpoint. room+direction (never ConnectionId) disambiguates parallel Connections, reaches the visible half of outbound cross-area links, and survives JSON store bindings.

export interface MapStyleApplication {
    style: string;
    rooms?: RoomNumber[];
    exits?: MapExitRef[];
    area?: AreaId | string;
}

Associates a named style with rooms and/or exits. Later entries win field-by-field over earlier ones and over defaultStyle.

• style — Key into MapViewProps.styles.
• area — Optional scope; entries for other areas are ignored. Accepts a mapper-issued AreaId pair or the area's canonical UUID string. Mapper-issued pairs carry BigInt halves that JSON.stringify rejects (the AreaId caveat), so apply arrays written to session state must scope with the string form — the map:room event's areaId field delivers it ready-made. An entry whose string does not parse as a UUID is skipped (with a one-time warning) rather than applied unscoped.

export interface MapDoorState {
    exit: MapExitRef;
    closed?: boolean;
    locked?: boolean;
}

Semantic door-state override — state, not style (a door's look comes from doorColor in the styles). Omitted fields retain the persisted map value.

export function extractMarkdownLinks(source: string): MarkdownLink[];

The links source contains when read as a Markdown document, in order: exactly the links a Markdown widget shows for it, including bare <command> links, with backslash escapes honored and inline code / fenced code left literal. Use it to act on the same links a widget displays, like running the first link in a room's notes.

export interface MarkdownLink {
    label: string;
    url: string;
}

One link in a Markdown document, as extractMarkdownLinks reports it.

• label — The link's visible text. For a bare <command> link it equals the command; an empty label ([](<look>)) falls back to the destination.
• url — What clicking the link sends: the explicit destination, or for a bare <command> link, the command itself.

Script API reference · ← smudgy:widgets — Controls · smudgy:widgets — Canvas → · Scripting manual