@boba-cli/dsl 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,738 @@
+import { Cmd, Msg, Model } from '@boba-cli/tea';
+import { Style } from '@boba-cli/chapstick';
+export { Style } from '@boba-cli/chapstick';
+import { Spinner, SpinnerModel } from '@boba-cli/spinner';
+export { Spinner, dot, ellipsis, line, meter, miniDot, moon, points, pulse } from '@boba-cli/spinner';
+import { EchoMode, ValidateFunc, TextInputModel } from '@boba-cli/textinput';
+export { CursorMode, EchoMode, TextInputModel, ValidateFunc } from '@boba-cli/textinput';
+
+/**
+ * View node types for the view DSL.
+ * @public
+ */
+type ViewNode = string | TextNode | LayoutNode | ComponentView;
+/**
+ * Text node with chainable style methods.
+ *
+ * @remarks
+ * Text nodes provide a fluent API for applying terminal styling to text content.
+ * All styling methods return a new {@link TextNode} instance, allowing for method chaining.
+ *
+ * @example
+ * ```typescript
+ * text('Hello').bold().foreground('#ff79c6')
+ * text('Warning').dim().italic()
+ * ```
+ *
+ * @public
+ */
+interface TextNode {
+    /** Internal discriminator for type narrowing. */
+    readonly _type: 'text';
+    /** The text content to display. */
+    readonly content: string;
+    /** Whether bold styling is applied. */
+    readonly _bold: boolean;
+    /** Whether dim styling is applied. */
+    readonly _dim: boolean;
+    /** Whether italic styling is applied. */
+    readonly _italic: boolean;
+    /** Foreground color (hex or named color). */
+    readonly _foreground: string | undefined;
+    /** Background color (hex or named color). */
+    readonly _background: string | undefined;
+    /**
+     * Apply bold styling to the text.
+     * @returns A new {@link TextNode} with bold styling applied.
+     */
+    bold(): TextNode;
+    /**
+     * Apply dim styling to the text.
+     * @returns A new {@link TextNode} with dim styling applied.
+     */
+    dim(): TextNode;
+    /**
+     * Apply italic styling to the text.
+     * @returns A new {@link TextNode} with italic styling applied.
+     */
+    italic(): TextNode;
+    /**
+     * Set the foreground color.
+     * @param color - Hex color (e.g., '#ff79c6') or named color
+     * @returns A new {@link TextNode} with the foreground color applied.
+     */
+    foreground(color: string): TextNode;
+    /**
+     * Set the background color.
+     * @param color - Hex color (e.g., '#282a36') or named color
+     * @returns A new {@link TextNode} with the background color applied.
+     */
+    background(color: string): TextNode;
+}
+/**
+ * Layout node for stacking views vertically or horizontally.
+ *
+ * @remarks
+ * Layout nodes arrange child views in either a vertical stack ({@link vstack})
+ * or horizontal stack ({@link hstack}). Children are rendered with optional
+ * spacing between them.
+ *
+ * @example
+ * ```typescript
+ * vstack(
+ *   text('Line 1'),
+ *   text('Line 2')
+ * )
+ *
+ * hstack(
+ *   text('Left'),
+ *   text('Right')
+ * )
+ * ```
+ *
+ * @public
+ */
+interface LayoutNode {
+    /** Layout direction: 'vstack' for vertical, 'hstack' for horizontal. */
+    readonly _type: 'vstack' | 'hstack';
+    /** Child view nodes to arrange. */
+    readonly children: ViewNode[];
+    /** Spacing between children (in newlines for vstack, spaces for hstack). */
+    readonly spacing: number;
+}
+/**
+ * Component view wrapper containing rendered output from a TEA component.
+ *
+ * @remarks
+ * Component views are returned by the builder when registering components
+ * via {@link AppBuilder.component}. They contain the pre-rendered string
+ * output from the component's `view()` method.
+ *
+ * @example
+ * ```typescript
+ * createApp()
+ *   .component('spinner', spinner())
+ *   .view(({ components }) => components.spinner)
+ *   //                        ^^^^^^^^^^^^^^^^^ ComponentView
+ * ```
+ *
+ * @public
+ */
+interface ComponentView {
+    /** Internal discriminator for type narrowing. */
+    readonly _type: 'component';
+    /** The rendered view string from the component. */
+    readonly view: string;
+}
+/**
+ * Component builder interface for wrapping TEA components.
+ *
+ * @remarks
+ * Component builders provide an adapter between TEA components (which follow
+ * the Model-Update-View pattern) and the DSL. When you register a component
+ * via {@link AppBuilder.component}, you provide a `ComponentBuilder` that
+ * handles initialization, updates, and rendering.
+ *
+ * @example
+ * ```typescript
+ * const spinnerBuilder: ComponentBuilder<SpinnerModel> = {
+ *   init: () => {
+ *     const model = new SpinnerModel()
+ *     return [model, model.tick()]
+ *   },
+ *   update: (model, msg) => model.update(msg),
+ *   view: (model) => model.view(),
+ * }
+ * ```
+ *
+ * @typeParam M - The model type managed by this component
+ *
+ * @public
+ */
+interface ComponentBuilder<M> {
+    /**
+     * Initialize the component and return the initial model and command.
+     * @returns A tuple of [initial model, initial command]
+     */
+    init(): [M, Cmd<Msg>];
+    /**
+     * Update the component with a message.
+     * @param model - The current component model
+     * @param msg - The message to process
+     * @returns A tuple of [next model, next command]
+     */
+    update(model: M, msg: Msg): [M, Cmd<Msg>];
+    /**
+     * Render the component to a string.
+     * @param model - The current component model
+     * @returns The rendered view string
+     */
+    view(model: M): string;
+}
+/**
+ * Event context passed to key event handlers.
+ *
+ * @remarks
+ * The event context provides access to the current application state and
+ * component views, along with methods to update state or quit the application.
+ * It's passed to handlers registered via {@link AppBuilder.onKey}.
+ *
+ * @example
+ * ```typescript
+ * createApp()
+ *   .state({ count: 0 })
+ *   .onKey('up', ({ state, update }) => {
+ *     update({ count: state.count + 1 })
+ *   })
+ *   .onKey('q', ({ quit }) => quit())
+ * ```
+ *
+ * @typeParam State - The application state type
+ * @typeParam Components - Record of registered components
+ *
+ * @public
+ */
+interface EventContext<State, Components extends Record<string, unknown>> {
+    /** Current application state. */
+    readonly state: State;
+    /** Current component views (rendered strings). */
+    readonly components: {
+        [K in keyof Components]: ComponentView;
+    };
+    /**
+     * Update state with a partial patch (shallow merge).
+     * @param patch - Partial state object to merge with current state
+     */
+    update(patch: Partial<State>): void;
+    /**
+     * Replace entire state with a new value.
+     * @param newState - The new complete state
+     */
+    setState(newState: State): void;
+    /**
+     * Quit the application gracefully.
+     */
+    quit(): void;
+}
+/**
+ * Key handler function type.
+ *
+ * @remarks
+ * Key handlers are registered via {@link AppBuilder.onKey} and receive an
+ * {@link EventContext} with the current state and component views. Handlers
+ * can update state or quit the application.
+ *
+ * @typeParam State - The application state type
+ * @typeParam Components - Record of registered components
+ *
+ * @public
+ */
+type KeyHandler<State, Components extends Record<string, unknown>> = (ctx: EventContext<State, Components>) => void;
+/**
+ * View function type.
+ *
+ * @remarks
+ * The view function is registered via {@link AppBuilder.view} and is called
+ * on every render cycle. It receives the current state and component views,
+ * and returns a {@link ViewNode} tree to display.
+ *
+ * @typeParam State - The application state type
+ * @typeParam Components - Record of registered components
+ *
+ * @public
+ */
+type ViewFunction<State, Components extends Record<string, unknown>> = (ctx: {
+    state: State;
+    components: {
+        [K in keyof Components]: ComponentView;
+    };
+}) => ViewNode;
+/**
+ * Built application ready to run.
+ *
+ * @remarks
+ * An `App` is created by calling {@link AppBuilder.build}. It provides a
+ * `run()` method to start the application event loop and a `getModel()` escape
+ * hatch to access the underlying TEA model for advanced use cases.
+ *
+ * @typeParam State - The application state type
+ * @typeParam _Components - Record of registered components (phantom type)
+ *
+ * @public
+ */
+interface App<State, _Components extends Record<string, unknown>> {
+    /**
+     * Run the application and block until it quits.
+     * @returns A promise resolving to the final application state
+     */
+    run(): Promise<{
+        state: State;
+    }>;
+    /**
+     * Get the underlying TEA model (escape hatch for advanced use cases).
+     * @returns The generated TEA Model from `@boba-cli/tea`
+     */
+    getModel(): Model<Msg>;
+}
+
+/**
+ * Builder for creating declarative CLI applications.
+ *
+ * @example
+ * ```typescript
+ * const app = createApp()
+ *   .state({ count: 0 })
+ *   .component('spinner', spinner())
+ *   .onKey('q', ({ quit }) => quit())
+ *   .view(({ state, components }) => vstack(
+ *     text('Count: ' + state.count),
+ *     components.spinner
+ *   ))
+ *   .build()
+ *
+ * await app.run()
+ * ```
+ *
+ * @public
+ */
+declare class AppBuilder<State = undefined, Components extends Record<string, unknown> = Record<string, never>> {
+    #private;
+    private constructor();
+    /**
+     * Create a new AppBuilder instance.
+     * @internal
+     */
+    static create(): AppBuilder<undefined, Record<string, never>>;
+    /**
+     * Set the initial application state.
+     *
+     * @remarks
+     * This should typically be called early in the builder chain. If called after
+     * registering key handlers or a view function, those will be preserved but
+     * their type information will be updated to reflect the new state type.
+     *
+     * @example
+     * ```typescript
+     * createApp()
+     *   .state({ count: 0, name: 'World' })
+     * ```
+     *
+     * @typeParam S - The application state type
+     * @param initial - The initial state object
+     * @returns A new {@link AppBuilder} with the state type parameter set
+     *
+     * @public
+     */
+    state<S>(initial: S): AppBuilder<S, Components>;
+    /**
+     * Register a component with a unique key.
+     *
+     * @remarks
+     * Components are TEA models wrapped in a {@link ComponentBuilder} that
+     * manages their lifecycle. The component's rendered view is available in
+     * the view function via `components[key]`.
+     *
+     * @example
+     * ```typescript
+     * createApp()
+     *   .component('loading', spinner())
+     *   .component('input', textInput())
+     * ```
+     *
+     * @typeParam K - The component key (string literal type)
+     * @typeParam M - The component model type
+     * @param key - Unique identifier for this component
+     * @param builder - Component builder implementing init/update/view
+     * @returns A new {@link AppBuilder} with the component registered
+     *
+     * @public
+     */
+    component<K extends string, M>(key: K, builder: ComponentBuilder<M>): AppBuilder<State, Components & Record<K, M>>;
+    /**
+     * Register a key handler.
+     *
+     * @remarks
+     * Key handlers receive an {@link EventContext} with the current state and
+     * components. Multiple keys can be bound to the same handler by passing an
+     * array of key strings. Key strings support modifiers like 'ctrl+c', 'alt+enter'.
+     *
+     * @example
+     * ```typescript
+     * createApp()
+     *   .onKey('q', ({ quit }) => quit())
+     *   .onKey(['up', 'k'], ({ state, update }) => update({ index: state.index - 1 }))
+     *   .onKey('ctrl+c', ({ quit }) => quit())
+     * ```
+     *
+     * @param keys - Single key string or array of key strings
+     * @param handler - Function to call when any of the keys are pressed
+     * @returns A new {@link AppBuilder} with the key handler registered
+     *
+     * @public
+     */
+    onKey(keys: string | string[], handler: KeyHandler<State, Components>): AppBuilder<State, Components>;
+    /**
+     * Set the view function.
+     *
+     * @remarks
+     * The view function is called on every render cycle and receives the current
+     * state and component views. It should return a {@link ViewNode} tree
+     * describing the UI to display.
+     *
+     * @example
+     * ```typescript
+     * createApp()
+     *   .view(({ state, components }) => vstack(
+     *     text('Hello ' + state.name),
+     *     components.spinner
+     *   ))
+     * ```
+     *
+     * @param fn - Function that returns a {@link ViewNode} tree
+     * @returns A new {@link AppBuilder} with the view function set
+     *
+     * @public
+     */
+    view(fn: ViewFunction<State, Components>): AppBuilder<State, Components>;
+    /**
+     * Build the application.
+     *
+     * @remarks
+     * Finalizes the builder chain and creates an {@link App} instance ready
+     * to run. This method must be called after setting a view function via
+     * {@link AppBuilder.view}.
+     *
+     * @throws Error if no view function has been set
+     *
+     * @returns The built {@link App} ready to run
+     *
+     * @public
+     */
+    build(): App<State, Components>;
+}
+/**
+ * Create a new application builder.
+ *
+ * @example
+ * ```typescript
+ * const app = createApp()
+ *   .state({ count: 0 })
+ *   .onKey('q', ({ quit }) => quit())
+ *   .view(({ state }) => text('Count: ' + state.count))
+ *   .build()
+ * ```
+ *
+ * @public
+ */
+declare function createApp(): AppBuilder<undefined, Record<string, never>>;
+
+/**
+ * Create a text node with chainable style methods.
+ *
+ * @remarks
+ * Text nodes support fluent styling via methods like `bold()`,
+ * `dim()`, `italic()`, `foreground()`, and `background()`.
+ *
+ * @example
+ * ```typescript
+ * text('Hello').bold().foreground('#ff79c6')
+ * text('Warning').dim()
+ * ```
+ *
+ * @param content - The text content to display
+ * @returns A new {@link TextNode}
+ *
+ * @public
+ */
+declare function text(content: string): TextNode;
+/**
+ * Create a vertical stack layout.
+ *
+ * @remarks
+ * Arranges child views vertically with newlines between them. Children are
+ * rendered in order from top to bottom.
+ *
+ * @example
+ * ```typescript
+ * vstack(
+ *   text('Line 1'),
+ *   text('Line 2'),
+ *   text('Line 3')
+ * )
+ * ```
+ *
+ * @param children - View nodes to stack vertically
+ * @returns A new {@link LayoutNode} with vertical stacking
+ *
+ * @public
+ */
+declare function vstack(...children: ViewNode[]): LayoutNode;
+/**
+ * Create a horizontal stack layout.
+ *
+ * @remarks
+ * Arranges child views horizontally on the same line. Children are
+ * rendered in order from left to right.
+ *
+ * @example
+ * ```typescript
+ * hstack(
+ *   text('Left'),
+ *   text(' | '),
+ *   text('Right')
+ * )
+ * ```
+ *
+ * @param children - View nodes to stack horizontally
+ * @returns A new {@link LayoutNode} with horizontal stacking
+ *
+ * @public
+ */
+declare function hstack(...children: ViewNode[]): LayoutNode;
+/**
+ * Create empty vertical space.
+ *
+ * @remarks
+ * Useful for adding vertical spacing between sections of your UI.
+ *
+ * @example
+ * ```typescript
+ * vstack(
+ *   text('Header'),
+ *   spacer(2),
+ *   text('Content')
+ * )
+ * ```
+ *
+ * @param height - Number of blank lines to insert (default: 1)
+ * @returns A string containing the specified number of newlines
+ *
+ * @public
+ */
+declare function spacer(height?: number): string;
+/**
+ * Create a divider line.
+ *
+ * @remarks
+ * Renders a horizontal line using a repeated character.
+ *
+ * @example
+ * ```typescript
+ * vstack(
+ *   text('Section 1'),
+ *   divider(),
+ *   text('Section 2'),
+ *   divider('=', 50)
+ * )
+ * ```
+ *
+ * @param char - Character to repeat (default: '─')
+ * @param width - Number of times to repeat the character (default: 40)
+ * @returns A string containing the divider line
+ *
+ * @public
+ */
+declare function divider(char?: string, width?: number): string;
+/**
+ * Conditionally render a node.
+ *
+ * @remarks
+ * Returns the node if the condition is true, otherwise returns an empty string.
+ *
+ * @example
+ * ```typescript
+ * vstack(
+ *   text('Always visible'),
+ *   when(state.showHelp, text('Help text'))
+ * )
+ * ```
+ *
+ * @param condition - Boolean condition to test
+ * @param node - View node to render if condition is true
+ * @returns The node if condition is true, empty string otherwise
+ *
+ * @public
+ */
+declare function when(condition: boolean, node: ViewNode): ViewNode;
+/**
+ * Choose between two nodes based on condition.
+ *
+ * @remarks
+ * Returns one node if the condition is true, another if false.
+ *
+ * @example
+ * ```typescript
+ * vstack(
+ *   choose(
+ *     state.isLoading,
+ *     text('Loading...').dim(),
+ *     text('Ready!').bold()
+ *   )
+ * )
+ * ```
+ *
+ * @param condition - Boolean condition to test
+ * @param ifTrue - View node to render if condition is true
+ * @param ifFalse - View node to render if condition is false
+ * @returns Either ifTrue or ifFalse depending on condition
+ *
+ * @public
+ */
+declare function choose(condition: boolean, ifTrue: ViewNode, ifFalse: ViewNode): ViewNode;
+/**
+ * Map items to view nodes.
+ *
+ * @remarks
+ * Transforms an array of items into an array of view nodes. The render
+ * function receives each item and its index.
+ *
+ * @example
+ * ```typescript
+ * vstack(
+ *   ...map(state.items, (item, index) =>
+ *     text(`${index + 1}. ${item.name}`)
+ *   )
+ * )
+ * ```
+ *
+ * @typeParam T - The type of items in the array
+ * @param items - Array of items to map
+ * @param render - Function to transform each item into a view node
+ * @returns Array of view nodes
+ *
+ * @public
+ */
+declare function map<T>(items: T[], render: (item: T, index: number) => ViewNode): ViewNode[];
+
+/**
+ * Render a view node tree to a string.
+ *
+ * @remarks
+ * Recursively renders a {@link ViewNode} tree into a terminal-ready string.
+ * Handles text styling, layout stacking, and component views. This function
+ * is typically called internally by the DSL, but can be used directly for
+ * testing or custom rendering.
+ *
+ * @example
+ * ```typescript
+ * const tree = vstack(
+ *   text('Hello').bold(),
+ *   text('World').foreground('#ff79c6')
+ * )
+ * const output = render(tree)
+ * console.log(output)
+ * ```
+ *
+ * @param node - The view node tree to render
+ * @returns A string ready to display in the terminal
+ *
+ * @public
+ */
+declare function render(node: ViewNode): string;
+
+/**
+ * Options for the spinner component builder.
+ *
+ * @remarks
+ * Configure the spinner animation and styling when creating a spinner component.
+ *
+ * @public
+ */
+interface SpinnerBuilderOptions {
+    /**
+     * Spinner animation to use (default: `line`).
+     *
+     * @remarks
+     * Available spinners include `line`, `dot`, `miniDot`,
+     * `pulse`, `points`, `moon`, `meter`, and `ellipsis`.
+     */
+    spinner?: Spinner;
+    /**
+     * Style for rendering the spinner.
+     *
+     * @remarks
+     * Uses `Style` from `@boba-cli/chapstick` to apply terminal colors and formatting.
+     */
+    style?: Style;
+}
+/**
+ * Create a spinner component builder.
+ *
+ * @remarks
+ * Creates a {@link ComponentBuilder} wrapping the `@boba-cli/spinner` package.
+ * The spinner automatically animates and can be styled with custom colors.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const app = createApp()
+ *   .component('loading', spinner())
+ *   .view(({ components }) => components.loading)
+ *   .build()
+ * ```
+ *
+ * @example
+ * With custom styling:
+ * ```typescript
+ * const app = createApp()
+ *   .component('loading', spinner({
+ *     style: new Style().foreground('#50fa7b')
+ *   }))
+ *   .view(({ components }) => hstack(
+ *     components.loading,
+ *     text('Loading...')
+ *   ))
+ *   .build()
+ * ```
+ *
+ * @param options - Configuration options for the spinner
+ * @returns A {@link ComponentBuilder} ready to use with {@link AppBuilder.component}
+ *
+ * @public
+ */
+declare function spinner(options?: SpinnerBuilderOptions): ComponentBuilder<SpinnerModel>;
+
+/**
+ * Options for the textInput component builder.
+ * @public
+ */
+interface TextInputBuilderOptions {
+    /** Placeholder text shown when input is empty. */
+    placeholder?: string;
+    /** Width constraint for the input field. */
+    width?: number;
+    /** Echo mode for input display (Normal, Password, or None). */
+    echoMode?: EchoMode;
+    /** Character limit for input. */
+    charLimit?: number;
+    /** Prompt string shown before the input. */
+    prompt?: string;
+    /** Style for the prompt. */
+    promptStyle?: Style;
+    /** Style for the input text. */
+    textStyle?: Style;
+    /** Style for the placeholder text. */
+    placeholderStyle?: Style;
+    /** Validation function. */
+    validate?: ValidateFunc;
+}
+/**
+ * Create a textInput component builder.
+ *
+ * @example
+ * ```typescript
+ * const app = createApp()
+ *   .component('nameInput', textInput({
+ *     placeholder: 'Enter your name...',
+ *     width: 40,
+ *     validate: (value) => value.length < 3 ? new Error('Too short') : null
+ *   }))
+ *   .view(({ components }) => components.nameInput)
+ *   .build()
+ * ```
+ *
+ * @public
+ */
+declare function textInput(options?: TextInputBuilderOptions): ComponentBuilder<TextInputModel>;
+
+export { type App, AppBuilder, type ComponentBuilder, type ComponentView, type EventContext, type KeyHandler, type LayoutNode, type SpinnerBuilderOptions, type TextInputBuilderOptions, type TextNode, type ViewFunction, type ViewNode, choose, createApp, divider, hstack, map, render, spacer, spinner, text, textInput, vstack, when };