@textui/kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Softov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @textui/kit
+
+Build a terminal UI in TypeScript. One install, one import.
+
+```bash
+npm install @textui/kit
+```
+
+```tsx
+import { render, Box, Text, useState, useInput } from '@textui/kit';
+
+function App() {
+  const [count, setCount] = useState(0);
+  useInput((e) => { if (e.name === '+') { setCount((c) => c + 1); return true; } });
+
+  return (
+    <Box border="round" padding={1} direction="column">
+      <Text bold>Count: {count}</Text>
+      <Text dim>Press + to increment, ctrl+c to quit</Text>
+    </Box>
+  );
+}
+
+const { waitUntilExit } = render(<App />);
+await waitUntilExit();
+console.log('App exited');
+```
+
+## What this package is
+
+The runtime ([`@textui/core`](https://github.com/softov/textui/tree/main/packages/core)), a terminal to put it on
+([`@textui/terminal`](https://github.com/softov/textui/tree/main/packages/terminal)), and `render`. Every other name here is
+re-exported from those two - importing from them directly is the same thing
+with a longer name.
+
+`render` mounts and keeps running. It returns a handle rather than a promise,
+so the application is up before the next line:
+
+| | |
+|---|---|
+| `app` | Commands, themes, focus, the store - everything hello world did not need |
+| `waitUntilExit()` | Resolves when the application stops, however it stopped |
+| `unmount()` | Stop, put the terminal back, resolve `waitUntilExit` |
+| `rerender(node)` | Swap the root |
+
+For one frame and no terminal - a report, `--help`, a test - use `renderOnce`
+or `renderToString` instead. Those return; this one runs.
+
+## ctrl+c
+
+Handled, and it has to be handled as a **key rather than a signal**. The
+terminal is in raw mode from the moment the app starts, and raw mode is
+exactly the mode where ctrl+c stops being SIGINT and becomes the byte `0x03` -
+so process signal handlers never fire.
+
+`exitOnCtrlC: false` gives you the key instead, which is what an editor with
+unsaved work wants.
+
+## Components
+
+The catalog is a separate install:
+
+```bash
+npm install @textui/widgets
+```
+
+```tsx
+import { Card, Badge } from '@textui/widgets';
+```
+
+Nothing to register. `<Card/>` compiles to a node that carries the imported
+function, and the runtime uses that in preference to any registry - so
+importing a component *is* registering it. That is why the catalog is not
+bundled here: a screen made of `Box` and `Text` should not carry eighty
+components it never mentions.
+
+The one case that needs a registry is a screen named in data, where a string
+has to resolve to something:
+
+```tsx
+import { registerBuiltins } from '@textui/widgets';
+
+render(<App />, { onBoot: registerBuiltins });
+```
+
+## Runtime
+
+No dependencies outside the two packages it re-exports, and no `node:` imports
+of its own. Node 22+ and Bun.
+
+## Documentation
+
+<https://softov.github.io/textui/>

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One package to build a terminal UI with.
+ *
+ * The runtime, a terminal to put it on, and `render`. Nothing of its own
+ * except that function - every other name here is re-exported from
+ * `@textui/core` or `@textui/terminal`, and importing from those directly is
+ * the same thing with a longer name.
+ *
+ * The component catalog is deliberately **not** here. `@textui/widgets` is a
+ * separate install because an imported component registers itself just by
+ * being imported, so nothing needs to know about it in advance - and a
+ * hello world made of `Box` and `Text` should not carry eighty components it
+ * never mentions.
+ */
+export * from '@textui/core';
+export * from '@textui/terminal';
+export { render } from './render.js';
+export type { RenderOptions, RenderHandle } from './render.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * One package to build a terminal UI with.
+ *
+ * The runtime, a terminal to put it on, and `render`. Nothing of its own
+ * except that function - every other name here is re-exported from
+ * `@textui/core` or `@textui/terminal`, and importing from those directly is
+ * the same thing with a longer name.
+ *
+ * The component catalog is deliberately **not** here. `@textui/widgets` is a
+ * separate install because an imported component registers itself just by
+ * being imported, so nothing needs to know about it in advance - and a
+ * hello world made of `Box` and `Text` should not carry eighty components it
+ * never mentions.
+ */
+export * from '@textui/core';
+export * from '@textui/terminal';
+export { render } from './render.js';

package/dist/jsx-dev-runtime.d.ts

@@ -0,0 +1,2 @@
+export * from '@textui/core/jsx-dev-runtime';
+//# sourceMappingURL=jsx-dev-runtime.d.ts.map

package/dist/jsx-dev-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-dev-runtime.d.ts","sourceRoot":"","sources":["../src/jsx-dev-runtime.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC"}

package/dist/jsx-dev-runtime.js

@@ -0,0 +1 @@
+export * from '@textui/core/jsx-dev-runtime';

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,9 @@
+/**
+ * So `jsxImportSource: "textui"` works.
+ *
+ * Without this a JSX file has to point its transform at `@textui/core`, which
+ * means installing a second package to compile a file that imports one - and
+ * under a strict node_modules layout it is not even resolvable.
+ */
+export * from '@textui/core/jsx-runtime';
+//# sourceMappingURL=jsx-runtime.d.ts.map

package/dist/jsx-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-runtime.d.ts","sourceRoot":"","sources":["../src/jsx-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,0BAA0B,CAAC"}

package/dist/jsx-runtime.js

@@ -0,0 +1,8 @@
+/**
+ * So `jsxImportSource: "textui"` works.
+ *
+ * Without this a JSX file has to point its transform at `@textui/core`, which
+ * means installing a second package to compile a file that imports one - and
+ * under a strict node_modules layout it is not even resolvable.
+ */
+export * from '@textui/core/jsx-runtime';

package/dist/render.d.ts

@@ -0,0 +1,43 @@
+import type { ComponentNode, CreateAppOptions, TerminalAdapter, TextUIApp } from '@textui/core';
+import type { NodeAdapterOptions } from '@textui/terminal';
+/**
+ * Mount a component on the terminal and keep it there.
+ *
+ * `createApp(...).start()` is what this is, with the two lines of ceremony
+ * that every program repeated - build a terminal, hand it the root - moved
+ * behind the call. The app is still on the handle, because everything past
+ * hello world is reached through it.
+ *
+ * One-shot rendering is `renderOnce` and `renderToString`. This one runs.
+ */
+export interface RenderOptions extends Omit<CreateAppOptions, 'terminal' | 'root'> {
+    /** Render onto this instead of the process's terminal. */
+    terminal?: TerminalAdapter;
+    stdin?: NodeAdapterOptions['stdin'];
+    stdout?: NodeAdapterOptions['stdout'];
+    /**
+     * Unmount on ctrl+c. On by default.
+     *
+     * It has to be handled as a key, not a signal. The terminal is in raw mode
+     * from the moment the app starts, and raw mode is precisely the mode where
+     * ctrl+c stops being SIGINT and becomes the byte 0x03 - so the process
+     * signal handlers never fire, and an application that does not read the key
+     * cannot be quit from the keyboard at all.
+     *
+     * Turn it off to handle the key yourself: an editor with unsaved work should
+     * ask rather than obey.
+     */
+    exitOnCtrlC?: boolean;
+}
+export interface RenderHandle {
+    /** Commands, themes, focus, the store - everything hello world did not need. */
+    app: TextUIApp;
+    /** Resolves when the application stops, however it stopped. */
+    waitUntilExit(): Promise<void>;
+    /** Stop, put the terminal back, and resolve `waitUntilExit`. */
+    unmount(): Promise<void>;
+    /** Swap the root for another node. */
+    rerender(node: ComponentNode): void;
+}
+export declare function render(node: ComponentNode, options?: RenderOptions): RenderHandle;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEhG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;;;;;;;GASG;AAEH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,MAAM,CAAC;IAChF,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,KAAK,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,GAAG,EAAE,SAAS,CAAC;IACf,+DAA+D;IAC/D,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,gEAAgE;IAChE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;CACrC;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CA4CrF"}

package/dist/render.js

@@ -0,0 +1,41 @@
+import { createApp, WRITER_KEY } from '@textui/core';
+import { createNodeTerminal, createWriter } from '@textui/terminal';
+export function render(node, options = {}) {
+    const { terminal: given, stdin, stdout, exitOnCtrlC = true, ...rest } = options;
+    const terminal = given ?? createNodeTerminal({
+        ...(stdin ? { stdin } : {}),
+        ...(stdout ? { stdout } : {}),
+    });
+    const app = createApp({ ...rest, terminal, root: node });
+    // Every application wrote this line and none of them had a choice about it:
+    // without a writer the app renders frames and puts none of them anywhere.
+    // Provide it again afterwards to use your own.
+    app.services.provide(WRITER_KEY, createWriter(terminal.capabilities()));
+    let settle;
+    let fail;
+    const exited = new Promise((resolve, reject) => { settle = resolve; fail = reject; });
+    let stopping = null;
+    const unmount = () => {
+        stopping ??= app.stop().then(() => { settle?.(); }, (err) => { fail?.(err); });
+        return stopping;
+    };
+    // Before `start`, so this sees the key first. That ordering is the whole
+    // difference between "ctrl+c quits" and "ctrl+c quits unless something else
+    // got there", and a program you cannot leave is worse than one that leaves
+    // too eagerly - `exitOnCtrlC: false` is there for the other case.
+    if (exitOnCtrlC) {
+        terminal.onInput((event) => {
+            if (event.type === 'key' && event.ctrl && event.name === 'c')
+                void unmount();
+        });
+    }
+    app.start().catch((err) => { fail?.(err); });
+    return {
+        app,
+        waitUntilExit: () => exited,
+        unmount,
+        rerender(next) {
+            app.setRoot(next);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@textui/kit",
+  "version": "0.1.0",
+  "description": "One install for TextUI - the runtime, a terminal, and render",
+  "keywords": [
+    "terminal",
+    "tui",
+    "cli",
+    "jsx",
+    "ui",
+    "console",
+    "text-ui",
+    "ink-alternative",
+    "no-dependencies"
+  ],
+  "homepage": "https://softov.github.io/textui/",
+  "bugs": {
+    "url": "https://github.com/softov/textui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/softov/textui.git",
+    "directory": "packages/facade"
+  },
+  "license": "MIT",
+  "author": "Softov <softov@brbyte.com>",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-dev-runtime.d.ts",
+      "import": "./dist/jsx-dev-runtime.js"
+    }
+  },
+  "dependencies": {
+    "@textui/terminal": "^0.1.0",
+    "@textui/core": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * One package to build a terminal UI with.
+ *
+ * The runtime, a terminal to put it on, and `render`. Nothing of its own
+ * except that function - every other name here is re-exported from
+ * `@textui/core` or `@textui/terminal`, and importing from those directly is
+ * the same thing with a longer name.
+ *
+ * The component catalog is deliberately **not** here. `@textui/widgets` is a
+ * separate install because an imported component registers itself just by
+ * being imported, so nothing needs to know about it in advance - and a
+ * hello world made of `Box` and `Text` should not carry eighty components it
+ * never mentions.
+ */
+export * from '@textui/core';
+export * from '@textui/terminal';
+export { render } from './render.js';
+export type { RenderOptions, RenderHandle } from './render.js';

package/src/jsx-dev-runtime.ts

@@ -0,0 +1 @@
+export * from '@textui/core/jsx-dev-runtime';

package/src/jsx-runtime.ts

@@ -0,0 +1,8 @@
+/**
+ * So `jsxImportSource: "textui"` works.
+ *
+ * Without this a JSX file has to point its transform at `@textui/core`, which
+ * means installing a second package to compile a file that imports one - and
+ * under a strict node_modules layout it is not even resolvable.
+ */
+export * from '@textui/core/jsx-runtime';

package/src/render.ts

@@ -0,0 +1,92 @@
+import { createApp, WRITER_KEY } from '@textui/core';
+import type { ComponentNode, CreateAppOptions, TerminalAdapter, TextUIApp } from '@textui/core';
+import { createNodeTerminal, createWriter } from '@textui/terminal';
+import type { NodeAdapterOptions } from '@textui/terminal';
+
+/**
+ * Mount a component on the terminal and keep it there.
+ *
+ * `createApp(...).start()` is what this is, with the two lines of ceremony
+ * that every program repeated - build a terminal, hand it the root - moved
+ * behind the call. The app is still on the handle, because everything past
+ * hello world is reached through it.
+ *
+ * One-shot rendering is `renderOnce` and `renderToString`. This one runs.
+ */
+
+export interface RenderOptions extends Omit<CreateAppOptions, 'terminal' | 'root'> {
+  /** Render onto this instead of the process's terminal. */
+  terminal?: TerminalAdapter;
+  stdin?: NodeAdapterOptions['stdin'];
+  stdout?: NodeAdapterOptions['stdout'];
+  /**
+   * Unmount on ctrl+c. On by default.
+   *
+   * It has to be handled as a key, not a signal. The terminal is in raw mode
+   * from the moment the app starts, and raw mode is precisely the mode where
+   * ctrl+c stops being SIGINT and becomes the byte 0x03 - so the process
+   * signal handlers never fire, and an application that does not read the key
+   * cannot be quit from the keyboard at all.
+   *
+   * Turn it off to handle the key yourself: an editor with unsaved work should
+   * ask rather than obey.
+   */
+  exitOnCtrlC?: boolean;
+}
+
+export interface RenderHandle {
+  /** Commands, themes, focus, the store - everything hello world did not need. */
+  app: TextUIApp;
+  /** Resolves when the application stops, however it stopped. */
+  waitUntilExit(): Promise<void>;
+  /** Stop, put the terminal back, and resolve `waitUntilExit`. */
+  unmount(): Promise<void>;
+  /** Swap the root for another node. */
+  rerender(node: ComponentNode): void;
+}
+
+export function render(node: ComponentNode, options: RenderOptions = {}): RenderHandle {
+  const { terminal: given, stdin, stdout, exitOnCtrlC = true, ...rest } = options;
+  const terminal = given ?? createNodeTerminal({
+    ...(stdin ? { stdin } : {}),
+    ...(stdout ? { stdout } : {}),
+  });
+
+  const app = createApp({ ...rest, terminal, root: node });
+
+  // Every application wrote this line and none of them had a choice about it:
+  // without a writer the app renders frames and puts none of them anywhere.
+  // Provide it again afterwards to use your own.
+  app.services.provide(WRITER_KEY, createWriter(terminal.capabilities()));
+
+  let settle: (() => void) | undefined;
+  let fail: ((err: unknown) => void) | undefined;
+  const exited = new Promise<void>((resolve, reject) => { settle = resolve; fail = reject; });
+  let stopping: Promise<void> | null = null;
+
+  const unmount = (): Promise<void> => {
+    stopping ??= app.stop().then(() => { settle?.(); }, (err: unknown) => { fail?.(err); });
+    return stopping;
+  };
+
+  // Before `start`, so this sees the key first. That ordering is the whole
+  // difference between "ctrl+c quits" and "ctrl+c quits unless something else
+  // got there", and a program you cannot leave is worse than one that leaves
+  // too eagerly - `exitOnCtrlC: false` is there for the other case.
+  if (exitOnCtrlC) {
+    terminal.onInput((event) => {
+      if (event.type === 'key' && event.ctrl && event.name === 'c') void unmount();
+    });
+  }
+
+  app.start().catch((err: unknown) => { fail?.(err); });
+
+  return {
+    app,
+    waitUntilExit: () => exited,
+    unmount,
+    rerender(next) {
+      app.setRoot(next);
+    },
+  };
+}