smudgy:widgets

Generated from smudgy v0.4.0 (smudgy-widgets.d.ts @ fef07a6b0601). Index: scriptref.

Script-driven UI: build widget trees from the components below (directly or with JSX in a .tsx module) and put them on screen with createWidget. Import from smudgy:widgets.

export function createWidget(
    name: string,
    element: SmudgyElement,
    options?: CreateWidgetOptions,
): void;

Put a widget on screen (or replace the one already mounted under name). Re-mounting an existing name keeps its enabled state, and moves the widget when options.pane changes.

export function removeWidget(name: string): void;

Remove a previously-mounted named widget.

export interface CreateWidgetOptions {
    pane?: Pane | string;
}

Options for createWidget.

• pane — The session pane to mount into: a Pane handle from smudgy:core, or a pane name ("main" is the main pane). Defaults to the main pane.

export function Column(props?: ColumnProps, children?: WidgetChildren): SmudgyElement;

A vertical layout. Children are laid out top-to-bottom.

export interface ColumnProps {
    width?: Bindable<WidgetLength>;
    height?: Bindable<WidgetLength>;
    spacing?: Bindable<number>;
    padding?: Bindable<number>;
    children?: WidgetChildren;
}

Props common to the linear layout containers.

• spacing — Gap between children, in pixels.
• padding — Padding around the children, in pixels.

export function Row(props?: RowProps, children?: WidgetChildren): SmudgyElement;

A horizontal layout. Children are laid out left-to-right.

export type RowProps = ColumnProps;

export function Stack(props?: StackProps, children?: WidgetChildren): SmudgyElement;

A layering layout. Children are stacked front-to-back.

export interface StackProps {
    width?: Bindable<WidgetLength>;
    height?: Bindable<WidgetLength>;
    children?: WidgetChildren;
}

Props for the layering container (children stack front-to-back).

export function Container(props?: ContainerProps, children?: WidgetChildren): SmudgyElement;

A single-child wrapper with alignment/background. Only the first child is used.

export interface ContainerProps {
    width?: Bindable<WidgetLength>;
    height?: Bindable<WidgetLength>;
    align_x?: HorizontalAlign;
    align_y?: VerticalAlign;
    background?: Bindable<string>;
    children?: WidgetChildren;
}

Props for the single-child wrapper. Only the first child is used.

• background — A CSS color string for the background.

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 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 Button(props?: ButtonProps, children?: WidgetChildren): SmudgyElement;

A clickable button.

export interface ButtonProps {
    width?: Bindable<WidgetLength>;
    height?: Bindable<WidgetLength>;
    variant?: ButtonVariant;
    onPress?: () => void;
    children?: WidgetChildren;
}

Props for a clickable button. A single non-text child is used as the label element; otherwise the text children are rendered as the label.

• variant — Emphasis style. Default “subtle”.
• onPress — Called when the button is pressed.

export type ButtonVariant = "primary" | "secondary" | "subtle" | "link";

A button emphasis variant, mapping to the theme's named button styles.

export function Scrollable(props?: ScrollableProps, children?: WidgetChildren): SmudgyElement;

A scrollable single-child viewport. Only the first child is used.

export interface ScrollableProps {
    width?: Bindable<WidgetLength>;
    height?: Bindable<WidgetLength>;
    direction?: ScrollDirection;
    anchor?: "start" | "end";
    children?: WidgetChildren;
}

Props for a scrollable single-child viewport. Only the first child is used.

• direction — Scroll axis. Default “vertical”.
• anchor — Where the view rests. “end” sticks to the bottom (or right, when horizontal) so growing content keeps its newest line visible. Default “start”.

export type ScrollDirection = "vertical" | "horizontal" | "both";

A scroll axis. Vertical by default.

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 Modal(props?: ModalProps, children?: WidgetChildren): SmudgyElement;

A modal: a dimmed, input-blocking backdrop under a centered single child.

export interface ModalProps {
    onDismiss?: () => void;
    background?: Bindable<string>;
    children?: WidgetChildren;
}

Props for a modal: a dimmed, input-blocking backdrop under a centered content box. The single child is the content box (style it with a Container).

• onDismiss — Called when the backdrop is clicked. If omitted, the backdrop blocks input but does not dismiss.
• background — A CSS color string for the backdrop. Default translucent black.

export function TextEditor(props?: TextEditorProps, children?: WidgetChildren): SmudgyElement;

A multi-line text editor. Read its text via the onChange callback.

export interface TextEditorProps {
    id?: string;
    value?: string;
    onChange?: (text: string) => void;
    placeholder?: string;
    height?: WidgetLength;
    padding?: number;
    size?: number;
    children?: WidgetChildren;
}

Props for a multi-line text editor (a leaf – children are ignored).

• id — A stable identity for the editing buffer: two editors with different ids edit independently. Omitted, sibling editors are still kept distinct.
• value — The editor's starting text. In-progress edits are preserved; a script reload resets the editor to value.
• onChange — Called with the full text on each edit (not on cursor/selection movements).
• placeholder — Placeholder shown when empty.
• height — Viewport height. When set, taller text scrolls. Unset, the editor grows to fit its content.
• padding — Padding around the text, in pixels.
• size — Text size in pixels.

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.

export type Element = SmudgyElement;

export type Length = WidgetLength;

export type Children = WidgetChildren;

export type Bindable<T> = T | Binding<T>;

A prop that takes a value or a live state binding (handle.bind(...) from smudgy:core). Bound props track the published value on their own – the widget repaints on each update, with no handler and no re-mount.

export type HorizontalAlign = "left" | "start" | "center" | "right" | "end";

Horizontal alignment within a container.

export type VerticalAlign = "top" | "start" | "center" | "bottom" | "end";

Vertical alignment within a container.

interface SmudgyElement {
    readonly __smudgyWidgetElement: true;
}

One piece of on-screen UI, returned by every component below. Build it, nest it as a child of another component, or mount it with createWidget; it is not inspectable from JS.

type WidgetLength = number | "fill" | "shrink";

A size: a number of pixels, "fill" (take all available space), or "shrink" (hug the contents).

type WidgetChild =
| SmudgyElement
| string
| number
| boolean
| null
| undefined
| import("smudgy:core").Binding<any>;

Anything a component accepts as a child: another element, text (a string or number), a state binding (rendered as live text – see bind() in smudgy:core), or null/undefined/false (dropped, so cond && <Text/> works), plus arrays of the above (flattened).

type WidgetChildren = WidgetChild | WidgetChild[];

export function jsx(type: unknown, props: Record<string, unknown>, key?: unknown): SmudgyElement;

The automatic-JSX factory for elements.

export function jsxs(type: unknown, props: Record<string, unknown>, key?: unknown): SmudgyElement;

The automatic-JSX factory for elements with multiple children.

export function Fragment(props: { children?: WidgetChildren }): SmudgyElement;

Groups children with no wrapper element (<>...</>).

export namespace JSX {
    type Element = SmudgyElement;
    // No host string tags -- every JSX tag must be a widget component function.
    interface IntrinsicElements {}
    interface ElementChildrenAttribute {
        children: {};
    }
}

The JSX namespace TypeScript resolves for jsxImportSource: "smudgy:widgets".

This describes a type returned from a function on this page. Typically you'll never construct it directly.

interface WidgetsApi {
    Column: typeof Column;
    Row: typeof Row;
    Stack: typeof Stack;
    Container: typeof Container;
    Text: typeof Text;
    ProgressBar: typeof ProgressBar;
    Scrollable: typeof Scrollable;
    Markdown: typeof Markdown;
    Modal: typeof Modal;
    TextEditor: typeof TextEditor;
    Button: typeof Button;
    MapView: typeof MapView;
    createWidget: typeof createWidget;
    removeWidget: typeof removeWidget;
    extractMarkdownLinks: typeof extractMarkdownLinks;
}

The default export bundles every member above.

The module's default export (api).

const api: WidgetsApi;

Script API reference · smudgy:core — Sessions & output · smudgy:core — Lines & buffer · smudgy:core — Shared state & events · GMCP · smudgy:core — Automations · smudgy:core — Saved automations · smudgy:core — Panes · Mapper · smudgy:params