@textui/core 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,67 @@
+# @textui/core
+
+The runtime: a reactive store, typed registries, a cell-diffing renderer, hooks,
+and the four host primitives. Everything else in TextUI sits on this.
+
+```bash
+npm install @textui/core
+```
+
+## The one idea
+
+**JSX compiles to data.** `<Row gap={1}/>` and `{ component: 'Row', gap: 1 }` are
+the same value, and the runtime mounts either. A screen can be written in
+TypeScript, loaded from JSON, generated, edited or sent over a wire without the
+runtime changing.
+
+```ts
+import { h, renderToString } from '@textui/core';
+
+console.log(renderToString(
+  h('box', { margin: 1, border: 'single' }, h('text', { content: 'hello' })),
+  { width: 30 },
+));
+```
+
+Capitalized spellings of the primitives exist for JSX - `Box`, `Text`, `Canvas`
+are the strings themselves, so `<Box/>` and `<box/>` produce the identical node.
+
+## What is in here, and what is not
+
+The four primitives - `box`, `text`, `canvas`, `spacer` - are here because the
+layout engine and the painter are the things that reason about them. The
+eighty-seven components built out of them are [`@textui/widgets`](https://github.com/softov/textui/tree/main/packages/widgets),
+a separate package that depends on this one.
+
+That split is not tidiness. An imported component travels on its own node, so a
+screen written in JSX resolves without a registry at all:
+
+```ts
+import { Badge } from '@textui/widgets';
+
+renderToString(h(Badge, { label: 'ok' }), { width: 20 });  // registry empty
+```
+
+The registry is for the case JSX cannot cover - a component named by a string,
+in JSON, a template renderer, or an extension. `render` takes those through its
+`components` option.
+
+## The parts
+
+| | |
+|---|---|
+| Store | One reactive tree addressed by path. A prop can be `{ path: '$/x' }` and the runtime resolves it and redraws when it changes |
+| Registries | Components, commands, keybindings, themes, shells, surfaces, resources - typed, and disposable |
+| Renderer | Diffs cells rather than redrawing frames. `renderOnce` and `renderToString` draw one frame with no terminal at all |
+| Hooks | `useState`, `useEffect`, `useStore`, `useFocus`, `useInterval` and thirty more - module imports, not a second argument |
+| Layers | Dialogs, palettes, toasts and tooltips are entries on five planes, so focus trapping and dismissal are decided once |
+
+## Runtime
+
+No dependencies, and no `node:` imports - this package never touches a
+filesystem or a process. It runs on Node 22+ and on Bun, and would run in a
+browser against a virtual terminal.
+
+## Documentation
+
+<https://softov.github.io/textui/>

package/dist/adapters/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Adapters.
+ *
+ * Nothing here is registered by default. An adapter is a choice - what a kind
+ * means, what opens it, what can be done to it - and choices belong to the
+ * application, not to the library that ships them.
+ *
+ * The adapters that have an opinion about *content* live in
+ * `@textui/documents`, beside the buffers they read and write.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,11 @@
+/**
+ * Adapters.
+ *
+ * Nothing here is registered by default. An adapter is a choice - what a kind
+ * means, what opens it, what can be done to it - and choices belong to the
+ * application, not to the library that ships them.
+ *
+ * The adapters that have an opinion about *content* live in
+ * `@textui/documents`, beside the buffers they read and write.
+ */
+export {};

package/dist/app/app.d.ts

@@ -0,0 +1,200 @@
+import type { CreateAppOptions, InspectorNode, TextUIApp } from '../types/app.js';
+import type { ComponentNode } from '../types/graph.js';
+import type { Disposable } from '../types/disposable.js';
+import type { ResourceAdapter } from '../types/adapter.js';
+import type { Size } from '../types/geometry.js';
+import type { ResolvedTheme } from '../types/theme.js';
+import type { TerminalCapabilities, CapabilityOverrides } from '../types/capabilities.js';
+import type { InputEvent } from '../types/input.js';
+import { Buffer } from '../render/buffer.js';
+import { type Frame } from '../render/diff.js';
+import { createStore } from '../core/store.js';
+import { createEvents } from '../core/events.js';
+import { createWhen } from '../core/when.js';
+import { createComponents } from '../core/components.js';
+import { createServices } from '../core/services.js';
+import { createCommands } from '../core/commands.js';
+import { createKeybindings } from '../core/keybindings.js';
+import { createFocus } from '../core/focus.js';
+import { createLayers } from '../core/layers.js';
+import { createAnimation } from '../core/animation.js';
+import { createI18n } from '../core/i18n.js';
+import { createSurfaces, createLayouts, createShells } from '../core/surfaces.js';
+import { createNavigation } from '../core/navigation.js';
+import { createResources } from '../core/resources.js';
+import { createSyntax } from '../core/syntax.js';
+import { createManifests } from '../core/manifest.js';
+import { createThemes } from '../themes/registry.js';
+export declare class App implements TextUIApp {
+    private options;
+    readonly store: ReturnType<typeof createStore>;
+    readonly events: ReturnType<typeof createEvents>;
+    readonly when: ReturnType<typeof createWhen>;
+    readonly components: ReturnType<typeof createComponents>;
+    readonly themes: ReturnType<typeof createThemes>;
+    readonly services: ReturnType<typeof createServices>;
+    readonly i18n: ReturnType<typeof createI18n>;
+    readonly layouts: ReturnType<typeof createLayouts>;
+    readonly shells: ReturnType<typeof createShells>;
+    readonly animation: ReturnType<typeof createAnimation>;
+    readonly focus: ReturnType<typeof createFocus>;
+    readonly layers: ReturnType<typeof createLayers>;
+    readonly commands: ReturnType<typeof createCommands>;
+    readonly keybindings: ReturnType<typeof createKeybindings>;
+    readonly resources: ReturnType<typeof createResources>;
+    readonly syntax: ReturnType<typeof createSyntax>;
+    readonly surfaces: ReturnType<typeof createSurfaces>;
+    readonly screens: ReturnType<typeof createNavigation>;
+    readonly manifest: ReturnType<typeof createManifests>;
+    readonly terminal: NonNullable<CreateAppOptions['terminal']>;
+    private buffer_;
+    /** The mount holding the top of the screen stack, while there is one. */
+    private screenMount;
+    private root;
+    private frameScheduled;
+    private frameTimer;
+    private running_;
+    private disposed;
+    private themeId;
+    private shellId;
+    private resolvedTheme;
+    private bag;
+    private hovered;
+    /** Focus registrations created from `focusable` props, by focus id. */
+    private declaredFocus;
+    private lastFrame;
+    private renderCount;
+    private runtime;
+    constructor(options?: CreateAppOptions);
+    private requireTerminal;
+    get capabilities(): TerminalCapabilities;
+    get theme(): ResolvedTheme;
+    get size(): Size;
+    get running(): boolean;
+    private publishEnvironment;
+    setTheme(id: string): void;
+    setShell(id: string): void;
+    activeShell(): string;
+    setCapabilityOverrides(overrides: CapabilityOverrides): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    dispose(): void;
+    /**
+     * Swap the root node for another.
+     *
+     * Two paths, because there are two ways a root reaches the screen. With a
+     * shell registered it is a mount like any other and the surface registry
+     * owns it; with no shell at all - which is every application built out of
+     * primitives and nothing else - `rootNode` wraps `options.root` directly and
+     * the registry is never consulted. Setting one and not the other works in
+     * exactly half of the programs that can exist.
+     */
+    setRoot(node: ComponentNode): void;
+    private requestRender;
+    flush(): void;
+    /**
+     * The tree the frame renders: the shell, always, when one is registered.
+     *
+     * `root` is an alternative to *screens*, not to the shell - it is mounted
+     * into `main` at boot. Returning it here instead meant an application built
+     * that way had no shell at all: no canvas background (so a light theme left
+     * the terminal's own dark one behind and only dialogs looked light), no
+     * status surface, no toast host, and `setShell` did nothing.
+     */
+    /**
+     * Put the current screen into its surface.
+     *
+     * A screen is a mount like `root` is a mount: the shell arranges it, the
+     * layouts apply to it, and anything reading the surface registry sees it.
+     * Only the top of the stack is mounted - what a screen underneath keeps is
+     * its store scope, if it asked to, and not its instances.
+     *
+     * Parameters arrive as props. A screen that wants them deeper than its own
+     * signature reads `$/layout/screen/params` instead of forwarding them.
+     */
+    private mountScreen;
+    private rootNode;
+    /**
+     * Layers are composed at the root rather than inside the tree, so an overlay
+     * is never clipped by whatever opened it.
+     */
+    /**
+     * The root node: the shell, plus whatever is on the layers above it.
+     *
+     * The wrapper is unconditional, and that matters more than it looks. If the
+     * root were the bare shell whenever no layer is open, then opening the first
+     * toast would change the root's component - and a changed root is a full
+     * unmount and remount, so every screen would lose its state the moment
+     * anything notified it of anything. One shape, always.
+     */
+    private composeRoot;
+    private layerNode;
+    private rectOf;
+    private stateOf;
+    private renderFrame;
+    /** Overridden by the test harness, which has no bytes to write. */
+    protected emitFrame(frame: Frame): void;
+    private cursorPosition;
+    /**
+     * `focusable` and `onKey` are props on every node, so a plain `box` can take
+     * focus without a hook. Those declarations are reconciled here rather than
+     * during render, because a node that has gone away must lose its
+     * registration - and only the render pass knows which are still mounted.
+     */
+    private syncDeclaredFocusables;
+    private updateFocusRects;
+    private isDirty;
+    buffer(): Buffer;
+    frame(): Frame | null;
+    /**
+     * Input is processed one event at a time, and the tree is re-rendered
+     * between events rather than once at the end of the batch.
+     *
+     * This matters more than it looks. A terminal delivers several keystrokes in
+     * a single read, and a handler closes over the props from its last render -
+     * so without settling in between, typing "ab" quickly makes the handler for
+     * "b" see the state from before "a", and the character is lost. Rendering
+     * per key is what every terminal application does, and the frame diff makes
+     * it cheap.
+     */
+    handleInput(event: InputEvent): void;
+    private dispatchInput;
+    /**
+     * Order matters. A focused text field must see a plain character before any
+     * keybinding does, or typing "q" in a search box quits the application. So
+     * the focused node gets first refusal, then chords, then global handlers.
+     */
+    private handleKey;
+    private handleMouse;
+    /** Innermost box under the pointer first, then outward. */
+    private dispatchMouse;
+    private handleResize;
+    open: TextUIApp['open'];
+    openResource: TextUIApp['openResource'];
+    /**
+     * Fan an adapter out across the registries it touches, and hand back one
+     * disposable for the lot. Order matters: kinds first, so a viewer registered
+     * for `file.data.json` has something to match before anything is classified.
+     */
+    registerAdapter(adapter: ResourceAdapter): Disposable;
+    execute: TextUIApp['execute'];
+    inspect(): InspectorNode | null;
+    stats(): {
+        renders: number;
+        runs: number;
+        instances: number;
+    };
+    private handleError;
+}
+/**
+ * The frame writer is a service rather than an import, so core never depends
+ * on terminal encoding - the test harness and the static renderer simply do
+ * not provide one.
+ */
+export interface FrameWriter {
+    write(frame: Frame): string;
+    invalidate(): void;
+}
+export declare const WRITER_KEY: import("../types/services.js").ServiceKey<FrameWriter>;
+export declare function createApp(options?: CreateAppOptions): App;
+//# sourceMappingURL=app.d.ts.map

package/dist/app/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app/app.ts"],"names":[],"mappings":"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"}