@oh-my-pi/pi-tui 18.2.3 → 18.2.5

package/dist/types/components/form.d.ts

@@ -0,0 +1,130 @@
+import type { MouseRoutable, SgrMouseEvent } from "../mouse.js";
+import { type Component, type Focusable } from "../tui.js";
+import { Input } from "./input.js";
+import { type SelectItem, SelectList, type SelectListTheme } from "./select-list.js";
+/** Styling hooks used by the reusable form-field layout. */
+export interface FormFieldTheme {
+    label(text: string): string;
+    description(text: string): string;
+    error(text: string): string;
+    hint(text: string): string;
+}
+/** Interactive control accepted by {@link FormField}. */
+export type FormControl = Component & Partial<Focusable> & {
+    handleInput(data: string): void;
+    pasteText?(text: string): void;
+};
+/** Declarative label, help, preview, and footer content surrounding a control. */
+export interface FormFieldOptions {
+    theme: FormFieldTheme;
+    label?: string;
+    description?: string;
+    details?: readonly Component[];
+    previewLabel?: string;
+    preview?: Component;
+    hint?: string;
+    /** Read-only rows rendered after the control and before the interaction hint. */
+    summary?: readonly Component[];
+    footer?: Component;
+    /** Insert a blank row before the field's label/description/detail content. */
+    leadingSpace?: boolean;
+    spaceBeforeControl?: boolean;
+    spaceAfterControl?: boolean;
+}
+/**
+ * Layout and focus adapter for one form control. The control remains a normal
+ * component; this class only owns shared form chrome and local mouse routing.
+ */
+export declare class FormField implements Component, Focusable, MouseRoutable {
+    #private;
+    readonly control: FormControl;
+    constructor(control: FormControl, options: FormFieldOptions);
+    get focused(): boolean;
+    get debugChildren(): readonly Component[];
+    set focused(value: boolean);
+    setUseTerminalCursor(useTerminalCursor: boolean): void;
+    /** Show a bounded, single-line validation or submission error. */
+    setError(message: string | undefined): void;
+    handleInput(data: string): void;
+    pasteText(text: string): void;
+    /** Translate a field-local row to its control-local row, excluding all surrounding chrome. */
+    controlLineAt(line: number): number | undefined;
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+    render(width: number): readonly string[];
+    setIgnoreTight(ignore: boolean): this;
+    invalidate(): void;
+    dispose(): void;
+}
+/** Behavior used when a single-line field is submitted with an empty value. */
+export type EmptyInputBehavior = "submit" | "cancel" | "reject";
+/** Options for a validated, cancellable single-line field. */
+export interface TextFormFieldOptions extends Omit<FormFieldOptions, "preview"> {
+    initialValue?: string;
+    secret?: boolean;
+    prompt?: string;
+    empty?: EmptyInputBehavior;
+    emptyError?: string;
+    validate?: (value: string) => string | undefined;
+    onSubmit(value: string): void | Promise<void>;
+    onCancel(): void;
+    /** Schedule a frame after an asynchronous submit settles. */
+    requestRender?: () => void;
+}
+/**
+ * Single-line form field backed by {@link Input}. Validation and thrown submit
+ * errors stay visible on the field; empty-value policy is explicit per caller.
+ */
+export declare class TextFormField extends FormField {
+    #private;
+    readonly input: Input;
+    constructor(options: TextFormFieldOptions);
+    getValue(): string;
+    setValue(value: string): void;
+    /** Validate and submit the current value according to the configured empty policy. */
+    submit(): void;
+}
+/** Options for a SelectList-backed form field with optional live preview. */
+export interface SelectFormFieldOptions extends Omit<FormFieldOptions, "preview"> {
+    items: ReadonlyArray<SelectItem>;
+    currentValue?: string;
+    maxVisible?: number;
+    selectTheme: SelectListTheme;
+    getPreview?: () => string;
+    onSelectionChange?: (value: string) => void | Promise<void>;
+    onSubmit(value: string): void | Promise<void>;
+    onCancel(): void;
+    /** Schedule a frame after an asynchronous preview update settles. */
+    requestRender?: () => void;
+}
+/** SelectList field that centralizes selection, cancellation, preview refresh, and mouse routing. */
+export declare class SelectFormField extends FormField {
+    #private;
+    readonly selectList: SelectList;
+    constructor(options: SelectFormFieldOptions);
+    invalidate(): void;
+}
+/** Options for focus and input dispatch across several composable fields. */
+export interface FormOptions {
+    fields: readonly FormField[];
+    onCancel(): void;
+    isCancel?: (data: string) => boolean;
+}
+/**
+ * Small form controller for multi-field surfaces. It owns focus traversal,
+ * field-local mouse routing, and cancellation while fields retain submit policy.
+ */
+export declare class Form implements Component, Focusable, MouseRoutable {
+    #private;
+    constructor(options: FormOptions);
+    get focused(): boolean;
+    get debugChildren(): readonly Component[];
+    set focused(value: boolean);
+    setUseTerminalCursor(useTerminalCursor: boolean): void;
+    handleInput(data: string): void;
+    pasteText(text: string): void;
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+    render(width: number): readonly string[];
+    setIgnoreTight(ignore: boolean): this;
+    invalidate(): void;
+    dispose(): void;
+}

package/dist/types/components/image.d.ts

@@ -22,10 +22,10 @@ export declare const DEFAULT_MAX_INLINE_IMAGES = 8;
  * Bounds how many inline images render as live terminal graphics at once.
  *
  * Terminal graphics protocols — Kitty especially — keep every transmitted image
- * in a per-terminal store and re-draw placements as content scrolls; text-clear
- * escapes (`CSI 2 J` / `CSI 3 J`) do not remove them. Unbounded, a session that
- * shows many images piles up placements plus store memory and leaves ghosts in
- * scrollback.
+ * in a per-screen store and re-draw placements as content scrolls; placements
+ * that left the viewport survive text-clear escapes (`CSI 2 J`). Unbounded, a
+ * session that shows many images piles up placements plus store memory and
+ * leaves ghosts in scrollback.
  *
  * The budget keeps the most recent `cap` images live and demotes older ones to
  * their text fallback. Demotion needs a full redraw (so off-screen rows are
@@ -115,9 +115,9 @@ export declare class ImageBudget {
     takeResetPurgeIds(): readonly number[];
     /** Image ids to delete from the terminal this frame; clears the pending set. */
     takePurgeIds(): readonly number[];
-    /** All image ids believed to be loaded in the terminal store; clears tracking. */
+    /** All image ids believed to be loaded in any screen's store; clears tracking. */
     takeAllTransmittedIds(): readonly number[];
-    /** Whether `imageId`'s data still needs to be transmitted to the terminal. */
+    /** Whether `imageId`'s data still needs to be transmitted to the surface the in-flight pass paints. */
     shouldTransmit(imageId: number): boolean;
     /**
      * Record a direct-placement image's source pixel geometry so the renderer
@@ -170,11 +170,12 @@ export declare class ImageBudget {
         lastEpoch: number;
     }>;
     /**
-     * Queue a one-time transmit for `imageId`. No-op if already transmitted, so a
-     * repeated call (e.g. a width-change re-render) never re-sends the data.
+     * Queue a one-time transmit for `imageId` on the surface the in-flight pass
+     * paints. No-op if that surface already holds the data, so a repeated call
+     * (e.g. a width-change re-render) never re-sends it.
      */
     enqueueTransmit(imageId: number, sequence: string): void;
-    /** Whether a frame has image data queued but not yet written to the terminal. */
+    /** Whether the in-flight pass's surface has image data queued but not yet written. */
     hasPendingTransmits(): boolean;
     /**
      * True when the budget has nothing in flight on either surface: no live images
@@ -183,15 +184,16 @@ export declare class ImageBudget {
      * observe pass only then — a partial tree walk would under-count display order.
      */
     get quiescent(): boolean;
-    /** Transmit sequences to write before this frame's placements; clears the queue. */
+    /** Transmit sequences to write before this frame's placements on its surface; clears that queue. */
     takeTransmits(): readonly string[];
     /**
-     * Drop transmit tracking so every still-live image re-enqueues its data
-     * (`a=t`) on the next render. Recovers when the terminal dropped the original
-     * transmit — e.g. Ghostty discarding graphics sent during its post-startup
-     * window — where a placement-only replay can never bind a Unicode placeholder.
-     * Pair with a component invalidate + forced repaint so the data and placement
-     * re-emit together; keeps no base64 in budget state (the transmit-once design).
+     * Drop the normal screen's transmit tracking so every still-live image
+     * re-enqueues its data (`a=t`) on the next render. Recovers when the terminal
+     * dropped the original transmit — e.g. Ghostty discarding graphics sent during
+     * its post-startup window — where a placement-only replay can never bind a
+     * Unicode placeholder. Pair with a component invalidate + forced repaint so
+     * the data and placement re-emit together; keeps no base64 in budget state
+     * (the transmit-once design).
      */
     forgetTransmitted(): void;
 }

package/dist/types/components/key-value-list.d.ts

@@ -0,0 +1,24 @@
+import type { Component } from "../tui.js";
+/** One label/value entry in a {@link KeyValueList}. */
+export interface KeyValueRow {
+    readonly label: string;
+    readonly value: string;
+    readonly labelStyle?: (text: string) => string;
+    readonly valueStyle?: (text: string) => string;
+}
+/** Explicit sizing and wrapping policy for a key/value list. */
+export interface KeyValueListOptions {
+    readonly indent?: string;
+    readonly labelWidth: number;
+    readonly gap?: string;
+    readonly minValueWidth?: number;
+    readonly labelOverflow?: "allow" | "truncate";
+}
+/** A bounded ANSI-aware label/value list with replaceable rows and aligned wrapped continuations. */
+export declare class KeyValueList implements Component {
+    #private;
+    constructor(rows: readonly KeyValueRow[], options: KeyValueListOptions);
+    setRows(rows: readonly KeyValueRow[]): boolean;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/components/layout/geometry.d.ts

@@ -0,0 +1,73 @@
+import type { MouseRoutable } from "../../mouse.js";
+import type { Component } from "../../tui.js";
+/** Alignment within space allocated by a layout component. */
+export type LayoutAlignment = "start" | "center" | "end";
+/** Insets reserved inside a layout child's allocated rectangle. */
+export interface LayoutInsets {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/** Insets normalized to finite, non-negative terminal-cell counts. */
+export interface NormalizedLayoutInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Rectangle in coordinates local to a layout component. */
+export interface LayoutRect {
+    row: number;
+    col: number;
+    width: number;
+    height: number;
+}
+/** Lazy layout child, evaluated only when the child is visible. */
+export type LayoutRenderer = (width: number, height: number | undefined) => readonly string[];
+/** A concrete component or a lazy renderer used as a layout child. */
+export type LayoutContent = Component | LayoutRenderer;
+/** Static text or a late-bound layout decoration, useful for theme-colored rules. */
+export type LayoutDecoration = string | (() => string);
+/** A component whose parent may assign a local row budget before rendering. */
+export interface HeightConstrainedComponent extends Component {
+    setHeight(height: number | undefined): void;
+}
+/** One fixed or growing constraint consumed by {@link allocateLayoutSpace}. */
+export interface LayoutAllocation {
+    fixed?: number;
+    grow?: number;
+    min?: number;
+    max?: number;
+}
+/** Clamp an external size to a finite, non-negative integer cell count. */
+export declare function layoutSize(value: number | undefined, fallback?: number): number;
+/** Normalize an optional external size while preserving `undefined`. */
+export declare function optionalLayoutSize(value: number | undefined): number | undefined;
+/** Clamp a proportional layout input to a finite, non-negative number. */
+export declare function layoutRatio(value: number | undefined, fallback: number): number;
+/** Resolve static or late-bound layout decoration text. */
+export declare function layoutDecorationText(decoration: LayoutDecoration | undefined): string;
+/**
+ * Allocate bounded integer cells across fixed and growing children. When the
+ * minimums cannot fit, later children collapse first so output stays bounded.
+ */
+export declare function allocateLayoutSpace(items: readonly LayoutAllocation[], available: number): number[];
+/** Normalize every inset to a finite, non-negative integer cell count. */
+export declare function layoutInsets(insets: LayoutInsets | undefined): NormalizedLayoutInsets;
+/** Compare optional inset objects by their normalized terminal geometry. */
+export declare function equalLayoutInsets(left: LayoutInsets | undefined, right: LayoutInsets | undefined): boolean;
+/** Offset content within spare cells according to an alignment. */
+export declare function layoutAlignmentOffset(space: number, alignment: LayoutAlignment): number;
+/** Narrow a concrete-or-lazy child to a concrete component. */
+export declare function isLayoutComponent(content: LayoutContent): content is Component;
+/** Narrow a layout child to a component accepting a row budget. */
+export declare function isHeightConstrainedComponent(content: LayoutContent): content is HeightConstrainedComponent;
+/** Narrow a layout child to a mouse-routable component. */
+export declare function isLayoutMouseRoutable(content: LayoutContent): content is Component & MouseRoutable;
+/** Return concrete children once each, preserving their first layout order. */
+export declare function uniqueLayoutComponents(contents: readonly LayoutContent[]): readonly Component[];
+/** Fit one ANSI-styled row to an exact terminal-cell width. */
+export declare function fitLayoutLine(line: string, width: number): string;
+/** Render a concrete or lazy child with an optional local height budget. */
+export declare function renderLayoutContent(content: LayoutContent, width: number, height: number | undefined): readonly string[];

package/dist/types/components/layout/row.d.ts

@@ -0,0 +1,55 @@
+import type { MouseRoutable, SgrMouseEvent } from "../../mouse.js";
+import type { Component } from "../../tui.js";
+import { type LayoutAlignment, type LayoutContent, type LayoutDecoration, type LayoutInsets, type LayoutRect } from "./geometry.js";
+/** One child and its horizontal sizing and alignment constraints. */
+export interface RowChild {
+    content: LayoutContent;
+    width?: number;
+    grow?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    padding?: LayoutInsets;
+    align?: LayoutAlignment;
+}
+/** Construction options for {@link Row}. */
+export interface RowOptions {
+    children: readonly RowChild[];
+    height?: number;
+    gap?: LayoutDecoration;
+    prefix?: LayoutDecoration;
+    suffix?: LayoutDecoration;
+    align?: LayoutAlignment;
+}
+/** A child hit translated into that child's local coordinates. */
+export interface RowHit {
+    index: number;
+    content: LayoutContent;
+    line: number;
+    col: number;
+    rect: LayoutRect;
+}
+/**
+ * Horizontal component layout with fixed/proportional slots, exact row budgets,
+ * ANSI-aware clipping, alignment, and local mouse-coordinate translation.
+ */
+export declare class Row implements Component, MouseRoutable {
+    #private;
+    constructor(options: RowOptions);
+    /** Concrete component children exposed to the debug tree. */
+    get debugChildren(): readonly Component[];
+    /** Last-rendered content rectangle for `index`, excluding its padding. */
+    childRect(index: number): LayoutRect | undefined;
+    /** Replace the row's children without recreating the layout component. */
+    setChildren(children: readonly RowChild[]): void;
+    /** Set the exact rendered row count, or clear it to use natural height. */
+    setHeight(height: number | undefined): void;
+    /** Update outer and inter-child decorations. */
+    setDecorations(prefix: LayoutDecoration | undefined, gap: LayoutDecoration | undefined, suffix: LayoutDecoration | undefined): void;
+    setIgnoreTight(ignore: boolean): this;
+    invalidate(): void;
+    dispose(): void;
+    /** Translate a row-local point into a child's local coordinates. */
+    locate(line: number, col: number): RowHit | undefined;
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+    render(width: number): readonly string[];
+}

package/dist/types/components/layout/split-pane.d.ts

@@ -0,0 +1,80 @@
+import type { MouseRoutable, SgrMouseEvent } from "../../mouse.js";
+import type { Component } from "../../tui.js";
+import { type LayoutAlignment, type LayoutContent, type LayoutDecoration, type LayoutRect } from "./geometry.js";
+/** Pane selected when a split collapses below its width constraints. */
+export type PaneSide = "left" | "right";
+/** Fixed or proportional sizing constraints for the left pane. */
+export interface SplitPaneSize {
+    fixed?: number;
+    ratio?: number;
+    min?: number;
+    max?: number;
+}
+/** Construction options for {@link SplitPane}. */
+export interface SplitPaneOptions {
+    left: LayoutContent;
+    right: LayoutContent;
+    leftSize?: SplitPaneSize;
+    rightMinWidth?: number;
+    splitAt?: number;
+    narrowPane?: PaneSide;
+    height?: number;
+    prefix?: LayoutDecoration;
+    divider?: LayoutDecoration;
+    suffix?: LayoutDecoration;
+    align?: LayoutAlignment;
+}
+/** Resolved pane mode and local rectangles for a width. */
+export interface SplitPaneGeometry {
+    mode: "split" | "narrow";
+    left?: LayoutRect;
+    right?: LayoutRect;
+    dividerCol?: number;
+}
+/** A pane hit translated into the pane child's local coordinates. */
+export interface SplitPaneHit {
+    pane: PaneSide;
+    content: LayoutContent;
+    line: number;
+    col: number;
+    rect: LayoutRect;
+}
+/**
+ * Adaptive two-pane layout over {@link Row}. It owns width bounds, an optional
+ * narrow fallback, exact height budgets, and pane-local mouse translation.
+ */
+export declare class SplitPane implements Component, MouseRoutable {
+    #private;
+    constructor(options: SplitPaneOptions);
+    /** Concrete pane children exposed to the debug tree. */
+    get debugChildren(): readonly Component[];
+    /** Mode used by the last render. */
+    get mode(): "split" | "narrow";
+    /** Left-pane content width from the last render. */
+    get leftWidth(): number;
+    /** Right-pane content width from the last render. */
+    get rightWidth(): number;
+    /** Column where the divider begins in the last split render. */
+    get dividerCol(): number | undefined;
+    /** Set the exact pane row budget, or clear it to use natural height. */
+    setHeight(height: number | undefined): void;
+    /** Change which pane is shown in narrow mode; `undefined` disables collapse. */
+    setNarrowPane(pane: PaneSide | undefined): void;
+    /** Update fixed/proportional left-pane constraints. */
+    setLeftSize(size: SplitPaneSize): void;
+    /** Update the minimum width at which both panes may be shown. */
+    setSplitAt(width: number): void;
+    /** Update the minimum content width reserved for the right pane. */
+    setRightMinWidth(width: number): void;
+    /** Update outer and divider decorations. */
+    setDecorations(prefix: LayoutDecoration | undefined, divider: LayoutDecoration | undefined, suffix: LayoutDecoration | undefined): void;
+    /** Resolve split/narrow geometry without rendering either pane. */
+    measure(width: number): SplitPaneGeometry;
+    /** Translate a split-local point into pane-local coordinates. */
+    locate(line: number, col: number): SplitPaneHit | undefined;
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+    setIgnoreTight(ignore: boolean): this;
+    invalidate(): void;
+    dispose(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/components/layout/stack.d.ts

@@ -0,0 +1,50 @@
+import type { MouseRoutable, SgrMouseEvent } from "../../mouse.js";
+import type { Component } from "../../tui.js";
+import { type LayoutAlignment, type LayoutContent, type LayoutInsets, type LayoutRect } from "./geometry.js";
+/** One child and its vertical row-budget constraints. */
+export interface StackChild {
+    content: LayoutContent;
+    height?: number;
+    grow?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    padding?: LayoutInsets;
+    align?: LayoutAlignment;
+}
+/** Construction options for {@link Stack}. */
+export interface StackOptions {
+    children: readonly StackChild[];
+    height?: number;
+    align?: LayoutAlignment;
+}
+/** A stack hit translated into the child's local coordinates. */
+export interface StackHit {
+    index: number;
+    content: LayoutContent;
+    line: number;
+    col: number;
+    rect: LayoutRect;
+}
+/**
+ * Vertical component layout with fixed and growing regions, exact height
+ * budgets, ANSI-aware clipping, padding, and local mouse translation.
+ */
+export declare class Stack implements Component, MouseRoutable {
+    #private;
+    constructor(options: StackOptions);
+    /** Concrete component children exposed to the debug tree. */
+    get debugChildren(): readonly Component[];
+    /** Last-rendered content rectangle for `index`, excluding its padding. */
+    childRect(index: number): LayoutRect | undefined;
+    /** Replace the stack's children without recreating the layout component. */
+    setChildren(children: readonly StackChild[]): void;
+    /** Set the exact total row budget, or clear it to use natural height. */
+    setHeight(height: number | undefined): void;
+    setIgnoreTight(ignore: boolean): this;
+    invalidate(): void;
+    dispose(): void;
+    /** Translate a stack-local point into a child's local coordinates. */
+    locate(line: number, col: number): StackHit | undefined;
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+    render(width: number): readonly string[];
+}

package/dist/types/components/menu-selection.d.ts

@@ -0,0 +1,71 @@
+/** Describes how a menu identifies, searches, disables, and confirms its items. */
+export interface MenuSelectionAdapter<T> {
+    /** Stable identity used to retain selection while data or filtering changes. */
+    getKey: (item: T) => string;
+    /** Searchable text used by the default fuzzy filter. */
+    getSearchText: (item: T) => string;
+    /** Disabled items remain visible but are skipped by navigation and cannot activate. */
+    isDisabled?: (item: T) => boolean;
+    /** Items returning true require two activation requests without an intervening state change. */
+    requiresConfirmation?: (item: T) => boolean;
+    /** Optional domain-specific filtering/ranking. */
+    filter?: (items: readonly T[], query: string) => readonly T[];
+}
+/** Result of requesting activation of the current menu item. */
+export type MenuActivation<T> = {
+    kind: "empty";
+} | {
+    kind: "disabled";
+    item: T;
+} | {
+    kind: "pending";
+    item: T;
+} | {
+    kind: "confirmed";
+    item: T;
+};
+/** A viewport over variable-height items. */
+export interface MenuWindow {
+    startIndex: number;
+    endIndex: number;
+    /** Number of visual rows before startIndex, for scrollbar positioning. */
+    rowOffset: number;
+    /** Total visual rows across every item. */
+    totalRows: number;
+}
+/**
+ * Pick a selection-centered, contiguous window whose visual rows fit `rowBudget`.
+ * A selected item taller than the budget is retained and clipped by the renderer.
+ */
+export declare function getMenuWindow(rowCounts: readonly number[], selectedIndex: number, rowBudget: number): MenuWindow;
+/**
+ * Controlled menu data, filtering, selection, disabled-row navigation, and
+ * confirmation state. Renderers remain domain-owned and consume `visibleItems`.
+ */
+export declare class MenuSelection<T> {
+    #private;
+    readonly adapter: MenuSelectionAdapter<T>;
+    constructor(items: readonly T[], adapter: MenuSelectionAdapter<T>, initialKey?: string);
+    get items(): readonly T[];
+    get visibleItems(): readonly T[];
+    get query(): string;
+    get selectedIndex(): number;
+    get selectedItem(): T | undefined;
+    get selectedKey(): string | undefined;
+    get pendingKey(): string | undefined;
+    isDisabled(item: T): boolean;
+    isPending(item: T): boolean;
+    /** Replace controlled data, retaining the selected key when it remains visible. */
+    setItems(items: readonly T[], selectedKey?: string | undefined): boolean;
+    /** Set the query and retain the selected key when it survives filtering. */
+    setQuery(query: string, retainSelection?: boolean): boolean;
+    /** Select a visible row, coercing disabled rows to the nearest enabled row. */
+    setSelectedIndex(index: number, direction?: -1 | 1): boolean;
+    setSelectedKey(key: string): boolean;
+    /** Move by item count, optionally wrapping at list edges. */
+    move(delta: number, wrap?: boolean): boolean;
+    moveToBoundary(boundary: "first" | "last"): boolean;
+    /** Clear a pending confirmation. Returns true only when one was cleared. */
+    cancelConfirmation(): boolean;
+    requestActivation(index?: number): MenuActivation<T>;
+}

package/dist/types/components/metric.d.ts

@@ -0,0 +1,44 @@
+import type { Component } from "../tui.js";
+/** One preformatted metric. Domain-specific number, cost, and quota policy stays with the caller. */
+export interface MetricSpec {
+    /** Undefined omits the metric; an empty string and zero-like strings remain observable values. */
+    readonly value: string | undefined;
+    /** Optional icon or label placed before the value. */
+    readonly leading?: string;
+    /** Separator between `leading` and `value`. */
+    readonly separator?: string;
+    /** Higher-priority metrics survive first when a row uses `drop` overflow. */
+    readonly priority?: number;
+    /** Render-time styling for the complete metric. */
+    readonly style?: (text: string) => string;
+}
+/** Width behavior for an inline metric row. */
+export type MetricOverflow = "allow" | "drop" | "truncate" | "wrap";
+/** Presentation options shared by {@link formatMetricRow} and {@link MetricRow}. */
+export interface MetricRowOptions {
+    readonly separator?: string;
+    readonly overflow?: MetricOverflow;
+    readonly maxWidth?: number;
+    readonly paddingX?: number;
+    readonly paddingY?: number;
+    readonly style?: (text: string) => string;
+}
+/** Format one metric without imposing domain-specific value policy. */
+export declare function formatMetric(metric: MetricSpec): string | undefined;
+/**
+ * Join metrics in declaration order. `drop` removes the lowest-priority metric
+ * first (rightmost on ties); `truncate` clips the complete row. `wrap` is
+ * applied by {@link MetricRow}, where the component owns the available width.
+ */
+export declare function formatMetricRow(metrics: readonly MetricSpec[], options?: MetricRowOptions): string;
+/**
+ * Component form of an inline metric row. It delegates ANSI-aware wrapping,
+ * padding, theme invalidation, and stable unchanged-render arrays to {@link Text}.
+ */
+export declare class MetricRow implements Component {
+    #private;
+    constructor(metrics: readonly MetricSpec[], options?: MetricRowOptions);
+    setMetrics(metrics: readonly MetricSpec[]): boolean;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/components/progress-bar.d.ts

@@ -0,0 +1,36 @@
+import type { Component } from "../tui.js";
+/** Explicit glyph and styling policy for a progress bar. */
+export interface ProgressBarStyle {
+    readonly filled: string;
+    readonly empty: string;
+    readonly indeterminate?: string;
+    readonly styleFilled?: (text: string) => string;
+    readonly styleEmpty?: (text: string) => string;
+    readonly styleIndeterminate?: (text: string) => string;
+    readonly styleBar?: (text: string) => string;
+}
+/** Layout and labeling policy for a progress bar. */
+export interface ProgressBarOptions {
+    readonly min?: number;
+    readonly max?: number;
+    readonly minWidth?: number;
+    readonly maxWidth?: number;
+    readonly prefix?: string;
+    readonly suffix?: string;
+    readonly showPercentage?: boolean;
+    readonly percentageSeparator?: string;
+    readonly formatPercentage?: (fraction: number) => string;
+    readonly style: ProgressBarStyle;
+}
+/** Normalize a progress value to a clamped fraction, preserving undefined as indeterminate. */
+export declare function progressFraction(value: number | undefined, min?: number, max?: number): number | undefined;
+/** Render a single progress bar line; `width` is the inner bar width before frame and percentage chrome. */
+export declare function renderProgressBar(value: number | undefined, width: number, options: ProgressBarOptions): string;
+/** Mutable progress component whose `render(width)` bounds the complete framed and labeled line to `width`. */
+export declare class ProgressBar implements Component {
+    #private;
+    constructor(value: number | undefined, options: ProgressBarOptions);
+    setValue(value: number | undefined): boolean;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}