@visulima/tui 0.0.1 → 1.0.0-alpha.10

package/README.md

@@ -1,45 +1,189 @@
-# @visulima/tui
+<!-- START_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+<a href="https://www.anolilab.com/open-source" align="center">
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+  <img src="__assets__/package-og.svg" alt="tui" />
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+</a>
 
-## Purpose
+<h3 align="center">React-based TUI library powered by a native Rust diff engine, drop-in Ink-compatible API</h3>
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@visulima/tui`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+<!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
-## What is OIDC Trusted Publishing?
+<br />
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+<div align="center">
 
-## Setup Instructions
+[![typescript-image][typescript-badge]][typescript-url]
+[![mit licence][license-badge]][license]
+[![npm downloads][npm-downloads-badge]][npm-downloads]
+[![Chat][chat-badge]][chat]
+[![PRs Welcome][prs-welcome-badge]][prs-welcome]
 
-To properly configure OIDC trusted publishing for this package:
+</div>
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+---
 
-## DO NOT USE THIS PACKAGE
+<div align="center">
+    <p>
+        <sup>
+            Daniel Bannert's open source work is supported by the community on <a href="https://github.com/sponsors/prisis">GitHub Sponsors</a>
+        </sup>
+    </p>
+</div>
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+---
 
-## More Information
+## Overview
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+`@visulima/tui` is a React-based terminal UI library with a native Rust diff engine and drop-in [Ink](https://github.com/vadimdemedes/ink)-compatible API. Build rich, interactive CLI applications with React components, hooks, and a familiar developer experience.
 
----
+Based on [ratatat](https://github.com/geoffmiller/ratatat) by Geoff Miller.
+
+## Features
+
+- **Faster than Ink** on mount (1.3-2.3x), competitive on rerender
+- **Drop-in Ink-compatible** React API
+- **Native Rust diff engine** via NAPI for high-throughput rendering
+- **React hooks** for input, focus, clipboard, mouse, scroll, animation, and window size
+- **Rich component library** - Box, Text, Spinner, Select, TextInput, Tabs, ScrollView, and more
+- **Cross-platform** native bindings (macOS, Linux glibc/musl, Windows x64/arm64)
+- **Server-side rendering** via `renderToString`
+- **Testing utilities** with mock streams and frame capture
+
+## Install
+
+```sh
+npm install @visulima/tui react react-reconciler
+```
+
+```sh
+yarn add @visulima/tui react react-reconciler
+```
+
+```sh
+pnpm add @visulima/tui react react-reconciler
+```
+
+## Quick Start
+
+```tsx
+import { render, Box, Text } from "@visulima/tui";
+
+const App = () => (
+    <Box flexDirection="column" padding={1}>
+        <Text bold>Hello, world!</Text>
+        <Text color="green">Powered by a native Rust diff engine</Text>
+    </Box>
+);
+
+render(<App />);
+```
+
+## Hooks
+
+### `useAnimation(options?)`
+
+Drive frame-based or time-based animations with a shared timer. Multiple `useAnimation` calls consolidate into one render cycle.
+
+```tsx
+import { Text, useAnimation } from "@visulima/tui";
+
+const Spinner = () => {
+    const { frame } = useAnimation({ interval: 80 });
+    const characters = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+    return <Text>{characters[frame % characters.length]}</Text>;
+};
+```
+
+| Option     | Type      | Default | Description                                                                                                                 |
+| ---------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `interval` | `number`  | `100`   | Time between ticks in milliseconds.                                                                                         |
+| `isActive` | `boolean` | `true`  | Whether the animation is running. When set to `false`, the animation stops. When toggled back to `true`, values reset to 0. |
+
+Returns `{ frame, time, delta, reset }`. See the [full hooks reference](https://visulima.com/packages/tui/hooks#useanimation) for detailed return values, more examples (sine waves, physics, pausable, reset), and `maxFps` interaction.
+
+## Documentation
+
+Full documentation, API reference, component gallery, and guides are available at:
+
+**[visulima.com/packages/tui](https://visulima.com/packages/tui)**
+
+- [Getting Started](https://visulima.com/packages/tui/getting-started)
+- [Package Map](https://visulima.com/packages/tui/package-map) - Entry points and what they export
+- [Components](https://visulima.com/packages/tui/components) - Box, Text, Spinner, Select, TextInput, and more
+- [Hooks](https://visulima.com/packages/tui/hooks) - useInput, useFocus, useApp, useStdout, and more
+- [Mouse Support](https://visulima.com/packages/tui/mouse) - Click, hover, drag, and scroll events
+- [Scroll](https://visulima.com/packages/tui/scroll) - ScrollView, ScrollList, and overflow handling
+- [Rendering Modes](https://visulima.com/packages/tui/rendering-modes) - Ink-compatible, React, and raw buffer
+- [Ink Compatibility](https://visulima.com/packages/tui/ink-compat) - Migration guide from Ink
+- [Testing](https://visulima.com/packages/tui/testing) - Testing utilities with mock streams
+- [Troubleshooting](https://visulima.com/packages/tui/troubleshooting)
+
+## Performance
+
+| Scenario                   | @visulima/tui |      Ink 6.8 |         Speedup |
+| -------------------------- | ------------: | -----------: | --------------: |
+| Mount + render (simple)    |   3,221 ops/s |  2,694 ops/s | **1.2x faster** |
+| Mount + render (dashboard) |   1,659 ops/s |    718 ops/s | **2.3x faster** |
+| Rerender (simple)          |  19,111 ops/s | 25,743 ops/s |           0.74x |
+
+> Benchmarks use production builds. Run: `pnpm --filter @visulima/tui run build:prod && pnpm vitest bench`
+
+### Kitchen Sink Demo
+
+| Layout                              | Focus                             | Graph                             | Live                            |
+| ----------------------------------- | --------------------------------- | --------------------------------- | ------------------------------- |
+| ![Layout](docs/media/ks-layout.png) | ![Focus](docs/media/ks-focus.png) | ![Graph](docs/media/ks-graph.png) | ![Live](docs/media/ks-live.png) |
+
+| Incremental                                   | UI                          | Static                              | Mouse                             |
+| --------------------------------------------- | --------------------------- | ----------------------------------- | --------------------------------- |
+| ![Incremental](docs/media/ks-incremental.png) | ![UI](docs/media/ks-ui.png) | ![Static](docs/media/ks-static.png) | ![Mouse](docs/media/ks-mouse.png) |
+
+## Related
+
+- [ink](https://github.com/vadimdemedes/ink) - React for interactive command-line apps
+- [ratatat](https://github.com/geoffmiller/ratatat) - The project this library is based on
+- [jacob314/ink](https://github.com/jacob314/ink) - Fork with StyledLine, Region model, and render caching (ported features)
+
+## Supported Node.js Versions
+
+Libraries in this ecosystem make the best effort to track [Node.js' release schedule](https://github.com/nodejs/release#release-schedule).
+Here's [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
+
+## Contributing
+
+If you would like to help take a look at the [list of issues](https://github.com/visulima/visulima/issues) and check our [Contributing](.github/CONTRIBUTING.md) guidelines.
+
+> **Note:** please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
+
+## Credits
+
+- [Daniel Bannert](https://github.com/prisis)
+- [Geoff Miller](https://github.com/geoffmiller) - Original [ratatat](https://github.com/geoffmiller/ratatat) library
+- [Vadym Demedes](https://github.com/vadimdemedes) - [Ink](https://github.com/vadimdemedes/ink) (MIT)
+- [Google LLC / jacob314](https://github.com/jacob314/ink) - StyledLine, Region model, render caching (Apache-2.0)
+- [Zeno Jiricek](https://github.com/nickhudkins/ink-mouse) - Mouse event system (Apache-2.0)
+- [All Contributors](https://github.com/visulima/visulima/graphs/contributors)
+
+## Made with ❤️ at Anolilab
+
+This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Anolilab](https://www.anolilab.com/open-source) is a Development and AI Studio. Contact us at [hello@anolilab.com](mailto:hello@anolilab.com) if you need any help with these technologies or just want to say hi!
+
+## License
+
+The visulima tui is open-sourced software licensed under the [MIT][license]
+
+<!-- badges -->
 
-**Maintained for OIDC setup purposes only**
+[license-badge]: https://img.shields.io/npm/l/@visulima/tui?style=for-the-badge
+[license]: https://github.com/visulima/visulima/blob/main/LICENSE
+[npm-downloads-badge]: https://img.shields.io/npm/dm/@visulima/tui?style=for-the-badge
+[npm-downloads]: https://www.npmjs.com/package/@visulima/tui
+[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
+[prs-welcome]: https://github.com/visulima/visulima/blob/main/.github/CONTRIBUTING.md
+[chat-badge]: https://img.shields.io/discord/932323359193186354.svg?style=for-the-badge
+[chat]: https://discord.gg/TtFJY8xkFK
+[typescript-badge]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]: https://www.typescriptlang.org/

package/dist/core/index.d.ts

@@ -0,0 +1,58 @@
+export { I as InlineLoop, a as InlineOptions, b as InlinePaintFn, c as InputParser, M as MouseEvent, T as TuiApp, d as createInlineLoop } from "../packem_shared/input.d-Bfq7oc06.js";
+import 'eventemitter3';
+/**
+* 2×u32 per-cell back-buffer layout:
+*   buffer[idx * 2]     = charCode  (Unicode codepoint, u32)
+*   buffer[idx * 2 + 1] = attrCode  = (styles &lt;< 16) | (bg &lt;< 8) | fg
+*/
+declare const Cell: {
+  /** Read bg color from an attr slot value (buffer[idx*2+1]) — bits 15:8 */
+  getBg(attributeSlot: number): number;
+  /** Read the char character from a raw char slot value (buffer[idx*2]) */
+  getChar(charSlot: number): string;
+  /** Read fg color from an attr slot value (buffer[idx*2+1]) — bits 7:0 */
+  getFg(attributeSlot: number): number;
+  /** Read styles bitmask from an attr slot value (buffer[idx*2+1]) — bits 23:16 */
+  getStyles(attributeSlot: number): number;
+  /**
+  * Pack a cell into a [charCode, attrCode] tuple.
+  * charCode = char.codePointAt(0)
+  * attrCode = (styles & 0xFF) &lt;< 16 | (bg & 0xFF) &lt;< 8 | (fg & 0xFF)
+  *
+  * Write to buffer as: buffer[idx*2] = charCode; buffer[idx*2+1] = attrCode
+  */
+  pack(char: string, fg?: number, bg?: number, styles?: number): [number, number];
+};
+declare const StyleMasks: {
+  BLINK: number;
+  BOLD: number;
+  DIM: number;
+  HIDDEN: number;
+  INVERT: number;
+  ITALIC: number;
+  STRIKETHROUGH: number;
+  UNDERLINE: number;
+};
+interface TerminalSize {
+  cols: number;
+  rows: number;
+}
+interface RendererInstance {
+  readonly height: number;
+  render: (backBuffer: Uint32Array) => void;
+  renderDiff: (backBuffer: Uint32Array) => string;
+  resize: (width: number, height: number) => void;
+  setRowOffset: (offset: number) => void;
+  readonly width: number;
+  writeRaw: (data: string) => void;
+}
+type RendererConstructor = new (width: number, height: number) => RendererInstance;
+interface TerminalGuardInstance {
+  getSize: () => TerminalSize;
+  leave: () => void;
+}
+type TerminalGuardConstructor = new (mouse?: boolean | undefined | null) => TerminalGuardInstance;
+declare const Renderer: RendererConstructor;
+declare const TerminalGuard: TerminalGuardConstructor;
+declare const terminalSize: () => TerminalSize;
+export { Cell, Renderer, StyleMasks, TerminalGuard, type TerminalSize, terminalSize };

package/dist/core/index.js

@@ -0,0 +1 @@
+import{TuiApp as o}from"../packem_shared/TuiApp-DrjI_i-R.js";import{Cell as t,StyleMasks as m}from"../packem_shared/Cell-BrXn3jxY.js";import{createInlineLoop as l}from"../packem_shared/createInlineLoop-DRNZ7jqH.js";import{InputParser as f}from"../packem_shared/InputParser-rZKjY_7Y.js";import{Renderer as x,TerminalGuard as s,terminalSize as u}from"../packem_shared/Renderer-DJXooAsp.js";export{t as Cell,f as InputParser,x as Renderer,m as StyleMasks,s as TerminalGuard,o as TuiApp,l as createInlineLoop,u as terminalSize};