@ind3x/cli-screens 1.0.0

package/README.md

@@ -0,0 +1,230 @@
+# @ind3x/cli-screens
+
+A small, zero-dependency, typescript-first, screen stack library intended to mimick the flow of game screens in interactive CLI applications.
+
+<video controls src="docs/assets/screens-demo.mov" title="Ind3x CLI Screens Demo"></video>
+
+The library is architected around four core concepts:
+
+- **Composition over inheritance:** build flows from factories, `sequence()`, and `withTask()`.
+- **Flexibility:** pass typed context and results through navigation, and use `defineScreen()` for custom implementations.
+- **Ease of use:** prefer small factory functions with useful defaults and no required inheritance.
+- **Opinionated behavior:** screens render complete frames, keyboard hooks stay synchronous, asynchronous work belongs in `mount()` or `withTask()`, and an `AbortSignal` handles cancellation.
+
+### Features
+
+- **Stack based navigation:** push, pop, replace, reset, or exit screens while passing typed results back through promises.
+- **Composable flows:** combine built in screens without custom implementations:
+  - `select()` presents typed choices and returns the selected value.
+  - `menu()` presents choices with an optional Back action and selection callback.
+  - `textInput()` collects, validates, and optionally masks text.
+  - `message()` displays content until a configured key dismisses it.
+  - `typewriter()` animates text and optionally dismisses itself when finished.
+  - `sequence()` displays screens in order, including lazily created steps.
+  - `withTask()` displays a screen while a typed asynchronous task runs.
+- **Asynchronous tasks:** display a screen while background work runs.
+- **Shared application context:** make application state available to every screen.
+- **Custom screens:** implement your own lifecycle, rendering, and keyboard hooks.
+- **Styled terminal output:** align text and apply tones to titles, hints, labels, descriptions, prompts, placeholders, and validation messages.
+- **Responsive display:** automatically scroll long choice lists, redraw on size changes.
+
+## Install
+
+```sh
+bun install @ind3x/cli-screens
+```
+
+## Quick Start
+
+```ts
+import { createCli, message, sequence, typewriter } from '@ind3x/cli-screens';
+
+const app = createCli();
+
+const start = sequence([
+  typewriter({
+    text: 'Loading...',
+    charactersPerSecond: 5,
+    autoDismiss: true
+  }),
+  message(`Hello, world!`),
+]);
+
+await app.run(start);
+```
+
+Other examples and use cases can be found in `docs/recipes/`:
+
+- [Basic menu selection screen](docs/recipes/basic-menu-selection.ts)
+- [Using a shared context](docs/recipes/shared-context.ts)
+- [Menu screen from async data](docs/recipes/async-menu-data.ts)
+- [Using `withTask()` hooks](docs/recipes/with-task.ts)
+- [Passing input forward to the next screen](docs/recipes/pass-input-forward.ts)
+- [Retrieving results from `push()` and `back()`](docs/recipes/push-back-results.ts)
+
+`run()` owns terminal setup and cleanup. Ctrl-C and `navigation.exit()` clear the final frame and restore the terminal before resolving the returned promise.
+
+## Screen Navigation
+
+- `await navigation.push(screen)` opens a child and resolves with the value it passes to `back()`.
+- `navigation.back(value?)` closes the current screen. At the root, it exits.
+- `navigation.replace(screen)` replaces the current screen. A caller awaiting the original screen receives the replacement screen's eventual result.
+- `navigation.reset(screen)` atomically replaces the complete stack.
+- `navigation.exit(value?)` exits the app and resolves `run()`.
+
+Pass input forward through screen factory arguments, return results through `push()`/`back()`, and place application-wide services in the typed app context.
+
+## Additional text styling
+
+Display text can be decorated:
+
+```ts
+{
+    value: 'Centered notice',
+    align: 'center',
+    tone: 'accent',
+}
+```
+
+This applies to titles, hints, message text, selection labels and descriptions, text-input prompts and placeholders, validation messages, and typewriter text. Plain strings retain each component's opinionated default presentation.
+
+Alongside the semantic `default`, `accent`, and `muted` tones, the standard ANSI foreground colors are available: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, and their `brightBlack` through `brightWhite` variants.
+
+### Select
+
+```ts
+const port = await navigation.push(
+  select<T>({
+    title: "Port",
+    choices: [
+      { label: "Development", value: 3000 },
+      { label: "Production", value: 8080 },
+    ],
+  }),
+);
+```
+
+`select<T>()` returns the choice value as `T`. Choices may include a `description` or be `disabled`. Long lists automatically scroll to keep the selected choice visible, using the terminal height and indicators for choices above or below the viewport. Set `maxVisible` to impose a smaller item limit.
+
+`menu()` adds a selectable `Back` action after its choices. Set `backLabel` to rename it or `backLabel: false` to hide it, such as on a root menu that already has an explicit exit action. Escape and Backspace also continue to navigate back.
+
+### Text input
+
+```ts
+const token = await navigation.push(
+  textInput({
+    message: "API token",
+    mask: true,
+    validate: (value) => (value.length < 10 ? "Token is too short" : undefined),
+  }),
+);
+```
+
+Escape cancels and produces `undefined`.
+
+### Message
+
+```ts
+await navigation.push(
+  message({
+    title: "Saved",
+    text: "Configuration written.",
+    dismissKeys: ["any"],
+  }),
+);
+```
+
+### Typewriter
+
+```ts
+await navigation.push(
+  typewriter({
+    title: {
+      value: "Introduction",
+      align: "center",
+      tone: "accent",
+    },
+    text: {
+      value: "Your adventure begins...",
+      align: "left",
+    },
+    charactersPerSecond: 30,
+    autoDismiss: true,
+  }),
+);
+```
+
+Animated text is positioned using its completed width, so it does not shift while characters appear.
+
+By default, typing can be completed early with a key press and the screen then prompts for dismissal. Set `autoDismiss: true` to ignore input and close the screen automatically as soon as typing finishes.
+
+### Sequence
+
+Use `sequence()` to display several screens in order without writing a custom controller screen:
+
+```ts
+await app.run(
+  sequence([typewriter({ text: "Welcome to Ind3x" }), () => gameMenuScreen()]),
+);
+```
+
+Each screen advances when it navigates back. A function creates its screen only when that step begins. Exiting the app or removing the sequence prevents later factories from running.
+
+### With task
+
+Use `withTask()` to display any screen while a typed asynchronous task runs:
+
+```ts
+const loading = withTask<AppContext, User[]>(
+  typewriter({ text: "Loading users..." }),
+  async ({ context, signal }) => {
+    return context.api.loadUsers({ signal });
+  },
+);
+
+const users = await navigation.push(loading);
+```
+
+The task owns the decorated screen's lifetime. The visual screen may push a temporary child, but it cannot pop, replace, reset, or exit the decorated flow. Its asynchronous `mount()` work does not delay the task. Successful completion closes the decorator with the task result. Removing the decorator aborts the signal passed to the task. Task and visual-mount errors use the app's normal `onError` behavior or reject `app.run()`.
+
+## Custom screens
+
+Use `defineScreen()` to get contextual typing without inheritance:
+
+```ts
+import { defineScreen, type Screen } from "@ind3x/cli-screens";
+
+type AppContext = {
+  api: ApiClient;
+};
+
+const loadingScreen: Screen<AppContext> = defineScreen<AppContext>({
+  async mount({ context, navigation, signal }) {
+    const games = await context.api.games({ signal });
+    if (!signal.aborted) navigation.replace(gameList({ games }));
+  },
+
+  render({ ui }) {
+    ui.text("Loading...", { tone: "muted" });
+  },
+
+  key(event, { navigation }) {
+    if (event.key === "escape") navigation.back();
+  },
+});
+```
+
+Rendering should be side-effect free. Start requests and timers in `mount()`, store local state in the factory closure, and call `requestRender()` to request a new frame. Each screen receives an `AbortSignal` that is aborted on unmount.
+
+A custom class may implement the structural `Screen<Context, Result>` interface, but no base class is required.
+
+## Development
+
+```sh
+bun install
+bun run test
+```
+
+`bun run test` builds the JavaScript and bundled TypeScript declarations, then runs the unit tests. `bun pm pack --dry-run` shows the files that will be included in a release.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/// <reference types="node" />
+
+export type TextColor = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "brightBlack" | "brightRed" | "brightGreen" | "brightYellow" | "brightBlue" | "brightMagenta" | "brightCyan" | "brightWhite";
+export type TextTone = TextColor | "accent" | "muted" | "default";
+export interface TextOptions {
+	tone?: TextTone;
+}
+export interface DividerOptions extends TextOptions {
+	character?: string;
+}
+export declare class Ui {
+	readonly width: number;
+	readonly height: number;
+	private readonly lines;
+	constructor(width: number, height?: number);
+	/** Formats text with renderer styling without adding it to the frame. */
+	style(value: string, { tone }?: TextOptions): string;
+	text(value: string, { tone }?: TextOptions): void;
+	blank(): void;
+	columns(left: string, right: string, { tone }?: TextOptions): void;
+	divider({ character, tone }?: DividerOptions): void;
+	header(lines: string[]): void;
+	/** @internal Serializes a UI instance for terminal output. */
+	static renderFrame(ui: Ui): string;
+}
+export type Modifiers = {
+	ctrl: boolean;
+	shift: boolean;
+	alt: boolean;
+};
+export type KeyEvent = Modifiers & {
+	sequence: string;
+} & ({
+	key: "text";
+	text: string;
+} | {
+	key: "up" | "down" | "left" | "right" | "enter" | "backspace" | "escape" | "tab" | "unknown";
+});
+declare const screenResult: unique symbol;
+export interface Navigation<Context, CurrentResult = void> {
+	push<Result>(screen: Screen<Context, Result>): Promise<Result | undefined>;
+	back(result?: CurrentResult): void;
+	replace<Result>(screen: Screen<Context, Result>): void;
+	reset<Result>(screen: Screen<Context, Result>): void;
+	exit(result?: unknown): void;
+}
+export interface ScreenEnvironment<Context, Result = void> {
+	readonly context: Readonly<Context>;
+	readonly navigation: Navigation<Context, Result>;
+	readonly signal: AbortSignal;
+	requestRender(): void;
+}
+export interface RenderEnvironment<Context, Result = void> extends ScreenEnvironment<Context, Result> {
+	readonly ui: Ui;
+}
+export interface Screen<Context = any, Result = void> {
+	/** @internal Carries the result type without affecting runtime values. */
+	readonly [screenResult]?: Result;
+	/**
+	 * Called once when this screen is pushed to the stack.
+	 *
+	 * Use this hook to start requests, timers, subscriptions, or other side
+	 * effects. The first render occurs immediately after this hook is invoked;
+	 * the runtime does not wait for a returned promise before rendering. Call
+	 * `requestRender()` when asynchronous state changes should be displayed.
+	 */
+	mount?(environment: ScreenEnvironment<Context, Result>): void | Promise<void>;
+	/**
+	 * Called when the screen needs to draw its complete frame.
+	 *
+	 * Occurs immediately after `mount()` is invoked.
+	 * Further renders occur after navigation transitions, calls to `requestRender()`,
+	 * and terminal resize events.
+	 *
+	 * Rendering should be synchronous and free of side effects. Use `mount()`
+	 * or `key()` for work that changes state, then call `requestRender()`.
+	 */
+	render(environment: RenderEnvironment<Context, Result>): void;
+	/**
+	 * Called when the active screen receives a keyboard event.
+	 *
+	 * Only the screen at the top of the stack receives input. Ctrl-C is handled
+	 * by the app runtime and is not forwarded. This hook is synchronous so
+	 * input ordering and navigation remain predictable. Start asynchronous work
+	 * in a screen pushed from this hook, or explicitly start a detached task.
+	 */
+	key?(event: KeyEvent, environment: ScreenEnvironment<Context, Result>): void;
+	/**
+	 * Called immediately before another screen is pushed above this screen.
+	 *
+	 * This hook runs for `navigation.push()` only. It does not run when the
+	 * screen is replaced, reset, popped, or removed during app shutdown. The
+	 * screen remains mounted but stops receiving renders and input until it is
+	 * resumed.
+	 */
+	suspend?(environment: ScreenEnvironment<Context, Result>): void;
+	/**
+	 * Called when a child screen is popped and this screen becomes active again.
+	 *
+	 * This follows `navigation.back()` from the child, including when that
+	 * child was replaced before eventually going back. It is not called while
+	 * intermediate screens are removed by `replace()`, `reset()`, or app exit.
+	 * A render occurs immediately after this hook.
+	 */
+	resume?(environment: ScreenEnvironment<Context, Result>): void;
+	/**
+	 * Called once just before this screen is permanently discarded.
+	 *
+	 * This occurs on `navigation.back()`, `replace()`, `reset()`, app exit,
+	 * `dispose()`, or fatal runtime error. Its abort signal is aborted before
+	 * this hook runs, so asynchronous work can observe cancellation. During a
+	 * reset or app shutdown, screens are unmounted from the top of the stack
+	 * downward.
+	 *
+	 * The runtime invokes this synchronous hook only once. Cancel asynchronous
+	 * work through the abort signal; do not start cleanup that must be awaited.
+	 */
+	unmount?(environment: ScreenEnvironment<Context, Result>): void;
+}
+/**
+ * Allows a custom screen to be implemented with its own context,
+ * result value, lifecycle hooks, renderer, and navigation methods.
+ *
+ * `defineScreen` does not add runtime behavior.
+ * Use `mount` for side effects, `render` to draw
+ * the current frame, and `key` to respond to input. A screen can return a value
+ * to its parent with `navigation.back(result)`.
+ *
+ * @example
+ * ```ts
+ * type AppContext = { version: string };
+ *
+ * const aboutScreen = defineScreen<AppContext, string>({
+ *     render({ context, ui }) {
+ *         ui.text(`Version ${context.version}`);
+ *         ui.text('Press Enter to continue');
+ *     },
+ *
+ *     key(event, { navigation }) {
+ *         if (event.key === 'enter') {
+ *             navigation.back('dismissed');
+ *         }
+ *     },
+ * });
+ *
+ * const result = await navigation.push(aboutScreen);
+ * // result is string | undefined
+ * ```
+ */
+export declare function defineScreen<Context = any, Result = void>(screen: Screen<Context, Result>): Screen<Context, Result>;
+export interface CliOutput {
+	write(value: string): unknown;
+}
+export interface CliOptions<Context> {
+	context: Context;
+	input?: NodeJS.ReadStream;
+	output?: CliOutput;
+	onError?: (error: unknown) => void;
+}
+declare class ScreenStackApp<Context, ExitResult> {
+	private readonly options;
+	/** Screen stack ordered from the root to the current screen. */
+	private readonly frameStack;
+	private readonly terminal;
+	private runCompletion?;
+	private isRendering;
+	private hasRenderRequest;
+	/** Delays rendering until the current group of screen updates is finished. */
+	private renderBatchDepth;
+	constructor(userOptions: CliOptions<Context>);
+	get isRunning(): boolean;
+	run<Result = ExitResult>(root: Screen<Context, Result>): Promise<Result | undefined>;
+	dispose(): void;
+	private currentFrame;
+	private createFrame;
+	/** Adds a screen to the stack and starts its lifecycle. */
+	private mount;
+	private requestRender;
+	private pushFrame;
+	private back;
+	private replace;
+	private reset;
+	private exit;
+	private render;
+	/** Groups screen updates and renders once after they finish. */
+	private batchRender;
+	private handleKey;
+	private handleSigint;
+	private handleResize;
+	/** Just a wrapper around mount() suspend() resume() to make error calling easier */
+	private runLifecycleHook;
+	private unmount;
+	private reportError;
+	private reportCleanupError;
+	private stop;
+	private cleanupFrames;
+}
+export declare function createCli<Context = void, ExitResult = unknown>(options?: CliOptions<Context>): ScreenStackApp<Context, ExitResult>;
+export type TextAlignment = "left" | "center" | "right";
+export interface DecoratedText {
+	value: string;
+	align?: TextAlignment;
+	tone?: TextTone;
+}
+/**
+ * Text using default presentation, or text with explicit presentation options.
+ */
+export type TextContent = string | DecoratedText;
+export interface Choice<Value> {
+	label: TextContent;
+	value: Value;
+	description?: TextContent;
+	disabled?: boolean;
+}
+export interface SelectOptions<Value> {
+	title?: TextContent;
+	choices: readonly Choice<Value>[];
+	initialIndex?: number;
+	loop?: boolean;
+	subtitle?: TextContent;
+	cancelKeys?: readonly ("escape" | "backspace")[];
+	/** Maximum number of choices shown at once, in addition to terminal limits. */
+	maxVisible?: number;
+}
+export declare function select<Value, Context = any>(options: SelectOptions<Value>): Screen<Context, Value>;
+export interface MenuOptions<Value, Context = any> extends Omit<SelectOptions<Value>, "choices"> {
+	choices: readonly Choice<Value>[];
+	/** Label for the selectable back action. Set to false to hide it. */
+	backLabel?: TextContent | false;
+	onSelect(value: Value, environment: ScreenEnvironment<Context, void>): void;
+}
+export declare function menu<Value, Context = any>(options: MenuOptions<Value, Context>): Screen<Context, void>;
+export type DismissKey = Exclude<KeyEvent["key"], "text" | "unknown"> | "any";
+export interface MessageOptions {
+	title?: TextContent;
+	text: TextContent;
+	hint?: TextContent;
+	dismissKeys?: readonly DismissKey[];
+}
+export declare function message(options: MessageOptions | TextContent): Screen<any, void>;
+/**
+ * A screen to display in a sequence, or a factory that creates one when its
+ * turn begins.
+ */
+export type ScreenSource<Context> = Screen<Context, any> | (() => Screen<Context, any>);
+/**
+ * Creates a screen that displays each supplied screen in order.
+ *
+ * A screen advances when it navigates back. Lazy factories are not invoked
+ * until their turn begins. After the final screen navigates back, the sequence
+ * also navigates back. If the sequence is unmounted or the app exits, no later
+ * screens are created.
+ *
+ * @example
+ * ```ts
+ * await app.run(sequence([
+ *     typewriter({ text: 'Welcome!' }),
+ *     () => gameMenuScreen(),
+ * ]));
+ * ```
+ */
+export declare function sequence<Context = any>(sources: readonly ScreenSource<Context>[]): Screen<Context, void>;
+export interface TextInputOptions {
+	message?: TextContent;
+	initialValue?: string;
+	placeholder?: TextContent;
+	/** Hides entered text using `*` when true or the provided string, without changing the returned value. */
+	mask?: boolean | string;
+	allowEmpty?: boolean;
+	validate?: (value: string) => TextContent | undefined;
+	cancelKeys?: readonly ("escape")[];
+}
+export declare function textInput(options?: TextInputOptions): Screen<any, string>;
+export interface TypewriterOptions {
+	/** Optional heading displayed above the animated text. */
+	title?: TextContent;
+	text: TextContent;
+	charactersPerSecond?: number;
+	/** Automatically closes the screen when typing completes. Defaults to `false`. */
+	autoDismiss?: boolean;
+}
+export declare function typewriter(options: TypewriterOptions): Screen<any, void>;
+export interface TaskEnvironment<Context> {
+	readonly context: Readonly<Context>;
+	readonly signal: AbortSignal;
+}
+export type ScreenTask<Context, Result> = (environment: TaskEnvironment<Context>) => Result | Promise<Result>;
+/**
+ * Displays a screen while an asynchronous task runs.
+ *
+ * The task controls the decorated screen's lifetime. Navigation that would
+ * remove the visual screen is ignored; when the task completes, the decorator
+ * navigates back with the task result. Removing the decorator aborts the signal
+ * supplied to the task and unmounts the visual screen.
+ *
+ * @example
+ * ```ts
+ * const loading = withTask<AppContext, User[]>(
+ *     typewriter({ text: 'Loading users...' }),
+ *     async ({ context, signal }) => {
+ *         return context.api.loadUsers({ signal });
+ *     },
+ * );
+ *
+ * const users = await navigation.push(loading);
+ * ```
+ */
+export declare function withTask<Context = any, Result = void>(screen: Screen<Context, any>, task: ScreenTask<Context, Result>): Screen<Context, Result>;
+
+export {};