controlroom

import { status, distribute, layout, … } from 'controlroom';

function collapse(tree: Layout, collapsed: ReadonlySet<string>): Layout;

function compose(tree: Layout, panes: Panes, size: Frame, state?: Pick<ScreenState, 'panes' | 'focused' | 'scroll'>): string[];

function distribute(total: number, sizes: readonly (number | {
    fr: number;
    min?: number;
})[]): number[];

function extents(tree: Layout, panes: Panes, size: Frame): Map<string, Extent>;

function fit(lines: readonly string[], rect: Pick<Rect, 'width' | 'height'>, at?: number | 'end'): string[];

function hints(keymap: Keymap, labels: Readonly<Record<string, string>>): string;

function initial(tabs?: readonly string[], panes?: readonly string[]): ScreenState;

function layout(tree: Layout, area: Rect, contents?: Contents): Map<string, Rect>;

function open(rt: Runtime, given: ScreenOptions): Screen;

function reduce(state: ScreenState, action: string, extents?: ReadonlyMap<string, Extent>): ScreenState;

function render(pane: Pane, t: number, live: boolean): string[];

class ScreenError extends TypeError {
    readonly fix: string;
    constructor(message: string, fix: string);
}

const processRuntime: () => Runtime;

const status: "reserved";

interface Extent {
    readonly content: number;
    readonly rows: number;
}

interface Frame {
    columns: number;
    rows: number;
    /** Milliseconds since the screen opened, for animated panes. */
    t: number;
    /** Whether animated panes draw their `frame`; a final, settled frame uses each static projection. */
    live: boolean;
}

interface Pane<S = unknown> {
    component: Component<S>;
    state: S;
    label?: string;
    /**
     * Drawn on a live screen only, and left out of the static projection: a hint line or a tab
     * bar means nothing to a pipe, a screen reader or an agent, which get every pane instead (R6).
     */
    liveOnly?: boolean;
}

interface Part {
    /** Defaults to `{ fr: 1 }`. */
    size?: Size;
    content: Layout;
}

interface Rect {
    x: number;
    y: number;
    width: number;
    height: number;
}

interface Runtime extends LoopRuntime {
    readonly stdout: Writer & OutputStream & {
        /** Rows of the terminal, read at every paint so a resize is honoured. */
        readonly rows?: number | undefined;
        on?(event: 'resize', listener: () => void): unknown;
        off?(event: 'resize', listener: () => void): unknown;
    };
    readonly stdin: KeyInput;
}

interface Screen {
    /** What `open()` decided, from roundel's policy. */
    readonly mode: OutputMode;
    /** Whether keys are being read: a `tty` whose stdin can go raw, and nothing else. */
    readonly interactive: boolean;
    readonly state: ScreenState;
    update(pane: string, state: unknown): void;
    /** Text above the live region, written once and never repainted (Ink's `<Static>`). */
    commit(text: string): void;
    /** Run an action as if its key had been pressed: what a static session has instead of keys. */
    dispatch(action: string): void;
    close(): void;
}

interface ScreenOptions {
    /** `'inline'` (the default) keeps the main screen; `'alternate'` takes the whole terminal. */
    screen?: 'inline' | 'alternate';
    /** The panes' arrangement, or a function of the screen state when tabs change what is shown. */
    layout: Layout | ((state: ScreenState) => Layout);
    /** Each pane is a component with its state, or a registered pane (R10) by name with its state. */
    panes: Readonly<Record<string, Pane | {
        pane: string;
        state: unknown;
    }>>;
    /**
     * Key spec → action, as data (caique R2), or the name of a registered keymap (R10). Defaults
     * to the registered `default`. `ctrl+c` is `quit` unless the keymap binds it.
     */
    keymap?: Keymap | string;
    tabs?: readonly string[];
    /** Panes that take focus, in order. */
    focus?: readonly string[];
    /** Whether this run was asked for `--json`. */
    json?: boolean;
    /** Every action, after the screen's own state has taken it: the program's half of the keymap. */
    onAction?(action: string, screen: Screen): void;
    /** R20 — an input line, drawn in one pane of the layout. */
    input?: InputOptions;
}

interface ScreenState {
    readonly tabs: readonly string[];
    readonly active: number;
    /** Panes that take focus, in focus order. */
    readonly panes: readonly string[];
    readonly focused: number;
    readonly collapsed: ReadonlySet<string>;
    /**
     * controlroom-scroll-pane R1 — each pane's first visible row. A pane with no entry, or with
     * `'end'`, is pinned to its bottom and follows new lines, as a log tail does.
     */
    readonly scroll: ReadonlyMap<string, number | 'end'>;
}

interface Split {
    /** `row` places parts left to right; `column` places them top to bottom. */
    direction: 'row' | 'column';
    parts: Part[];
}

type Action = 'tab.next' | 'tab.prev' | 'focus.next' | 'focus.prev' | `tab:${string}` | `toggle:${string}` | 'scroll.up' | 'scroll.down' | 'scroll.pageUp' | 'scroll.pageDown' | 'scroll.top' | 'scroll.bottom' | 'resize';

type Contents = Readonly<Record<string, readonly string[]>>;

type Keymap = Readonly<Record<string, string>>;

type Layout = string | Split;

type Panes = Readonly<Record<string, Pane>>;

type Size = number | {
    fr: number;
    min?: number;
} | 'fit';

type Status = typeof status;