@ind3x/cli-screens 1.0.0 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 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>
+<video controls src="https://github.com/user-attachments/assets/7dbeb7e3-1fba-4b10-94ef-65da7c8e8496" title="Ind3x CLI Screens Demo"></video>
 
 The library is architected around four core concepts:
 
@@ -15,10 +15,13 @@ The library is architected around four core concepts:
 
 - **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:
+  - `confirm()` asks a yes-or-no question and returns a boolean.
   - `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.
+  - `paginate()` displays long text in terminal-sized pages.
+  - `spinner()` displays an animated status indicator.
   - `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.
@@ -59,6 +62,8 @@ Other examples and use cases can be found in `docs/recipes/`:
 - [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)
+- [Paginating long text](docs/recipes/paginate.ts)
+- [Displaying a spinner during a task](docs/recipes/spinner.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)
 
@@ -108,6 +113,21 @@ const port = await navigation.push(
 
 `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.
 
+### Confirm
+
+```ts
+const approved = await navigation.push(
+  confirm({
+    message: "Save your changes?",
+    confirmLabel: "Save",
+    cancelLabel: "Discard",
+    initialValue: true,
+  }),
+);
+```
+
+`confirm()` returns `true` or `false`. Escape and Backspace return `false`.
+
 ### Text input
 
 ```ts
@@ -134,6 +154,30 @@ await navigation.push(
 );
 ```
 
+### Paginate
+
+```ts
+await navigation.push(
+  paginate({
+    title: "Release notes",
+    text: releaseNotes,
+  }),
+);
+```
+
+`paginate()` wraps text to the terminal width and divides it according to the available terminal height. Use the arrow keys to change pages and Escape or Backspace to return.
+
+### Spinner
+
+```ts
+const loading = withTask(
+  spinner({ text: "Loading users..." }),
+  ({ signal }) => api.loadUsers({ signal }),
+);
+```
+
+`spinner()` is a visual primitive and does not manage asynchronous work itself. Compose it with `withTask()` so the task owns the screen's lifetime.
+
 ### Typewriter
 
 ```ts

package/dist/index.d.ts

@@ -208,6 +208,19 @@ export interface DecoratedText {
  * Text using default presentation, or text with explicit presentation options.
  */
 export type TextContent = string | DecoratedText;
+export interface ConfirmOptions {
+	title?: TextContent;
+	message: TextContent;
+	confirmLabel?: TextContent;
+	cancelLabel?: TextContent;
+	initialValue?: boolean;
+}
+/**
+ * Asks the user to confirm or cancel an action.
+ *
+ * Escape and Backspace always return `false`.
+ */
+declare function confirm$1<Context = any>(options: ConfirmOptions | TextContent): Screen<Context, boolean>;
 export interface Choice<Value> {
 	label: TextContent;
 	value: Value;
@@ -240,6 +253,17 @@ export interface MessageOptions {
 	dismissKeys?: readonly DismissKey[];
 }
 export declare function message(options: MessageOptions | TextContent): Screen<any, void>;
+export interface PaginateOptions {
+	title?: TextContent;
+	text: TextContent;
+	initialPage?: number;
+	hint?: string;
+	cancelKeys?: readonly ("escape" | "backspace")[];
+}
+/**
+ * Displays long text one terminal-sized page at a time.
+ */
+export declare function paginate<Context = any>(options: PaginateOptions | TextContent): Screen<Context, void>;
 /**
  * A screen to display in a sequence, or a factory that creates one when its
  * turn begins.
@@ -262,6 +286,19 @@ export type ScreenSource<Context> = Screen<Context, any> | (() => Screen<Context
  * ```
  */
 export declare function sequence<Context = any>(sources: readonly ScreenSource<Context>[]): Screen<Context, void>;
+export interface SpinnerOptions {
+	title?: TextContent;
+	text?: TextContent;
+	frames?: readonly string[];
+	intervalMs?: number;
+}
+/**
+ * Displays an animated status indicator.
+ *
+ * Use with `withTask()` when the spinner should remain visible for the
+ * lifetime of asynchronous work.
+ */
+export declare function spinner(options?: SpinnerOptions | TextContent): Screen<any, void>;
 export interface TextInputOptions {
 	message?: TextContent;
 	initialValue?: string;
@@ -309,4 +346,8 @@ export type ScreenTask<Context, Result> = (environment: TaskEnvironment<Context>
  */
 export declare function withTask<Context = any, Result = void>(screen: Screen<Context, any>, task: ScreenTask<Context, Result>): Screen<Context, Result>;
 
+export {
+	confirm$1 as confirm,
+};
+
 export {};

package/dist/index.js

@@ -2275,6 +2275,7 @@ function createCli(options) {
 function defineScreen(screen) {
   return screen;
 }
+
 // src/renderer/text-content.ts
 function normalizeText(content, defaults = {}) {
   return typeof content === "string" ? { align: "left", tone: "default", ...defaults, value: content } : { align: "left", tone: "default", ...defaults, ...content };
@@ -2427,6 +2428,36 @@ function move(choices, current, direction, loop) {
   return current;
 }
 
+// src/screen/confirm.ts
+function confirm(options) {
+  const settings = typeof options === "string" || "value" in options ? { message: options } : options;
+  const selection = select({
+    choices: [
+      { label: settings.confirmLabel ?? "Yes", value: true },
+      { label: settings.cancelLabel ?? "No", value: false }
+    ],
+    initialIndex: settings.initialValue ?? true ? 0 : 1,
+    cancelKeys: []
+  });
+  return defineScreen({
+    render(environment) {
+      if (settings.title) {
+        renderText(environment.ui, settings.title, { tone: "accent" });
+        environment.ui.blank();
+      }
+      renderText(environment.ui, settings.message);
+      environment.ui.blank();
+      selection.render(environment);
+    },
+    key(event, environment) {
+      if (event.key === "escape" || event.key === "backspace") {
+        environment.navigation.back(false);
+        return;
+      }
+      selection.key?.(event, environment);
+    }
+  });
+}
 // src/screen/menu.ts
 var backAction = Symbol("back");
 function menu(options) {
@@ -2487,6 +2518,50 @@ function message(options) {
     }
   });
 }
+// src/screen/paginate.ts
+function paginate(options) {
+  const settings = typeof options === "string" || "value" in options ? { text: options } : options;
+  const body = normalizeText(settings.text);
+  let currentPage = Math.max(0, Math.floor(settings.initialPage ?? 0));
+  let pageCount = 1;
+  return defineScreen({
+    render({ ui }) {
+      const titleRows = settings.title ? wrapLines(normalizeText(settings.title).value, ui.width).length + 1 : 0;
+      const rowsPerPage = Math.max(1, ui.height - titleRows - 2);
+      const lines = wrapLines(body.value, ui.width);
+      pageCount = Math.max(1, Math.ceil(lines.length / rowsPerPage));
+      currentPage = Math.min(currentPage, pageCount - 1);
+      if (settings.title) {
+        renderText(ui, settings.title, { tone: "accent" });
+        ui.blank();
+      }
+      const start = currentPage * rowsPerPage;
+      const visibleLines = lines.slice(start, start + rowsPerPage);
+      for (const line of visibleLines) {
+        ui.text(alignText(line, body.align, ui.width), { tone: body.tone });
+      }
+      ui.blank();
+      ui.columns(`Page ${currentPage + 1} of ${pageCount}`, settings.hint ?? "←/→ page · Esc return", { tone: "muted" });
+    },
+    key(event, { navigation, requestRender }) {
+      const cancelKeys = settings.cancelKeys ?? ["escape", "backspace"];
+      if (cancelKeys.includes(event.key)) {
+        navigation.back();
+        return;
+      }
+      const direction = event.key === "right" || event.key === "down" ? 1 : event.key === "left" || event.key === "up" ? -1 : 0;
+      const nextPage = Math.max(0, Math.min(pageCount - 1, currentPage + direction));
+      if (nextPage !== currentPage) {
+        currentPage = nextPage;
+        requestRender();
+      }
+    }
+  });
+}
+function wrapLines(value, width) {
+  return value.split(`
+`).flatMap((line) => wrap(line, width));
+}
 // src/screen/sequence.ts
 function sequence(sources) {
   return defineScreen({
@@ -2505,6 +2580,39 @@ function sequence(sources) {
     render() {}
   });
 }
+// src/screen/spinner.ts
+var defaultFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+function spinner(options = {}) {
+  const settings = typeof options === "string" || "value" in options ? { text: options } : options;
+  const body = normalizeText(settings.text ?? "Working...");
+  const frames = settings.frames && settings.frames.length > 0 ? settings.frames : defaultFrames;
+  const intervalMs = Math.max(1, settings.intervalMs ?? 80);
+  let frameIndex = 0;
+  let timer;
+  return defineScreen({
+    mount({ requestRender, signal }) {
+      timer = setInterval(() => {
+        frameIndex = (frameIndex + 1) % frames.length;
+        requestRender();
+      }, intervalMs);
+      signal.addEventListener("abort", () => {
+        if (timer) {
+          clearInterval(timer);
+        }
+        timer = undefined;
+      }, { once: true });
+    },
+    render({ ui }) {
+      if (settings.title) {
+        renderText(ui, settings.title, { tone: "accent" });
+        ui.blank();
+      }
+      const frame = frames[frameIndex] ?? "";
+      const text = `${frame} ${body.value}`;
+      ui.text(alignText(text, body.align, ui.width), { tone: body.tone });
+    }
+  });
+}
 // src/screen/text-input.ts
 function textInput(options = {}) {
   let value = options.initialValue ?? "";
@@ -2724,11 +2832,14 @@ export {
   withTask,
   typewriter,
   textInput,
+  spinner,
   sequence,
   select,
+  paginate,
   message,
   menu,
   defineScreen,
   createCli,
+  confirm,
   Ui
 };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@ind3x/cli-screens",
-  "version": "1.0.0",
+  "version": "1.1.0",
+  "homepage": "https://ind3x.games",
   "packageManager": "bun@1.3.14",
   "author": "contact@ind3x.games",
   "description": "A small screen stack library for interactive CLI applications",
@@ -31,7 +32,7 @@
   },
   "scripts": {
     "build": "bun run build.ts",
-    "test": "bun run build && bun test",
+    "test": "bun run build && bun test --pass-with-no-tests",
     "prepublishOnly": "bun run build",
     "check": "bun pm pack --dry-run"
   },