smudgy:widgets — Text & data display

Generated from smudgy v0.4.2-dev (smudgy-widgets.d.ts @ e96061b683ea). Index: scriptref.

Display text, 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 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 {
    children?: WidgetChildren;
}

Props for the map view (a leaf – props and children are ignored).

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