tinky 0.1.0

package/README.md

@@ -0,0 +1,350 @@
+<p align="center">
+  <h1 align="center">Tinky</h1>
+  <p align="center">
+    <strong>React for CLIs, re-imagined with the Taffy layout engine</strong>
+  </p>
+  <p align="center">
+    <a href="./README.zh-CN.md">中文</a> · <a href="./README.ja-JP.md">日本語</a>
+  </p>
+</p>
+
+---
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/tinky.svg)](https://www.npmjs.com/package/tinky)
+
+Tinky is a modern React-based framework for building beautiful and interactive command-line interfaces. It leverages the powerful [Taffy](https://github.com/DioxusLabs/taffy) layout engine to provide **CSS Flexbox and Grid** layout support in the terminal.
+
+## ✨ Features
+
+- 🎨 **React Components** — Build CLIs using familiar React patterns and JSX syntax
+- 📐 **Flexbox & Grid Layout** — Full CSS Flexbox and CSS Grid support powered by Taffy
+- ⌨️ **Keyboard Input** — Built-in hooks for handling keyboard input and focus management
+- 🎯 **Focus Management** — Tab/Shift+Tab navigation with customizable focus behavior
+- 🖼️ **Borders & Backgrounds** — Rich styling with borders, background colors, and more
+- ♿ **Accessibility** — Screen reader support with ARIA attributes
+- 🔄 **Hot Reloading** — Fast development with React DevTools support
+- 📦 **TypeScript First** — Full TypeScript support with comprehensive type definitions
+
+## 📦 Installation
+
+```bash
+# Using npm
+npm install tinky react
+
+# Using yarn
+yarn add tinky react
+
+# Using pnpm
+pnpm add tinky react
+
+# Using bun
+bun add tinky react
+```
+
+## 🚀 Quick Start
+
+```tsx
+import { render, Box, Text } from "tinky";
+
+function App() {
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text color="green" bold>
+        Hello, Tinky! 🎉
+      </Text>
+      <Text>Build beautiful CLIs with React</Text>
+    </Box>
+  );
+}
+
+render(<App />);
+```
+
+## 📚 Components
+
+### Box
+
+The `<Box>` component is a fundamental building block. It's like a `<div>` in the browser, supporting Flexbox and Grid layouts.
+
+```tsx
+import { Box, Text } from "tinky";
+
+// Flexbox layout
+<Box flexDirection="row" gap={2}>
+  <Text>Left</Text>
+  <Text>Right</Text>
+</Box>
+
+// Grid layout
+<Box display="grid" gridTemplateColumns="1fr 2fr 1fr" gap={1}>
+  <Text>Col 1</Text>
+  <Text>Col 2</Text>
+  <Text>Col 3</Text>
+</Box>
+
+// With borders and padding
+<Box borderStyle="round" borderColor="cyan" padding={1}>
+  <Text>Styled Box</Text>
+</Box>
+```
+
+### Text
+
+The `<Text>` component renders styled text with colors, bold, italic, and more.
+
+```tsx
+import { Text } from "tinky";
+
+<Text color="blue">Blue text</Text>
+<Text backgroundColor="red" color="white">Highlighted</Text>
+<Text bold italic underline>Styled text</Text>
+<Text color="#ff6600">Hex colors work too!</Text>
+```
+
+### Static
+
+The `<Static>` component renders static content that won't be updated. Perfect for logs and history.
+
+```tsx
+import { Static, Text } from "tinky";
+
+const logs = ["Log 1", "Log 2", "Log 3"];
+
+<Static items={logs}>{(log, index) => <Text key={index}>{log}</Text>}</Static>;
+```
+
+### Transform
+
+The `<Transform>` component allows you to transform the output of its children.
+
+```tsx
+import { Transform, Text } from "tinky";
+
+<Transform transform={(output) => output.toUpperCase()}>
+  <Text>hello</Text>
+</Transform>;
+// Renders: HELLO
+```
+
+### Newline & Spacer
+
+```tsx
+import { Box, Text, Newline, Spacer } from "tinky";
+
+// Newline - adds vertical space
+<Box flexDirection="column">
+  <Text>Line 1</Text>
+  <Newline count={2} />
+  <Text>Line 2</Text>
+</Box>
+
+// Spacer - flexible space in flex containers
+<Box>
+  <Text>Left</Text>
+  <Spacer />
+  <Text>Right</Text>
+</Box>
+```
+
+## 🪝 Hooks
+
+### useInput
+
+Handle keyboard input in your components.
+
+```tsx
+import { useInput, useApp } from "tinky";
+
+function MyComponent() {
+  const { exit } = useApp();
+
+  useInput((input, key) => {
+    if (key.escape) {
+      exit();
+    }
+    if (key.upArrow) {
+      // Handle up arrow
+    }
+    if (input === "q") {
+      exit();
+    }
+  });
+
+  return <Text>Press 'q' to quit</Text>;
+}
+```
+
+### useApp
+
+Access the app instance to control exit behavior.
+
+```tsx
+import { useApp } from "tinky";
+
+function MyComponent() {
+  const { exit } = useApp();
+
+  // Exit with error
+  exit(new Error("Something went wrong"));
+
+  // Exit normally
+  exit();
+}
+```
+
+### useFocus & useFocusManager
+
+Manage focus for interactive components.
+
+```tsx
+import { useFocus, Box, Text } from "tinky";
+
+function FocusableItem({ label }: { label: string }) {
+  const { isFocused } = useFocus();
+
+  return (
+    <Box borderStyle={isFocused ? "bold" : "single"}>
+      <Text color={isFocused ? "green" : "white"}>{label}</Text>
+    </Box>
+  );
+}
+```
+
+### useStdin, useStdout, useStderr
+
+Direct access to stdin, stdout, and stderr streams.
+
+```tsx
+import { useStdout, useEffect } from "tinky";
+
+function MyComponent() {
+  const { write } = useStdout();
+
+  useEffect(() => {
+    write("Hello from stdout!\n");
+  }, []);
+
+  return null;
+}
+```
+
+## 🎨 Styling
+
+### Flexbox Properties
+
+```tsx
+<Box
+  flexDirection="row" // row, row-reverse, column, column-reverse
+  justifyContent="center" // flex-start, flex-end, center, space-between, space-around
+  alignItems="center" // flex-start, flex-end, center, stretch
+  flexWrap="wrap" // nowrap, wrap, wrap-reverse
+  flexGrow={1}
+  flexShrink={0}
+  gap={2}
+/>
+```
+
+### Grid Properties
+
+```tsx
+<Box
+  display="grid"
+  gridTemplateColumns="1fr 2fr 1fr"
+  gridTemplateRows="auto 1fr"
+  columnGap={1}
+  rowGap={1}
+  justifyItems="center"
+  alignItems="center"
+/>
+```
+
+### Border Styles
+
+```tsx
+<Box borderStyle="single" />   // ┌─┐
+<Box borderStyle="double" />   // ╔═╗
+<Box borderStyle="round" />    // ╭─╮
+<Box borderStyle="bold" />     // ┏━┓
+<Box borderStyle="classic" />  // +--+
+```
+
+### Colors
+
+Tinky supports multiple color formats:
+
+```tsx
+<Text color="red" />                    // Named colors
+<Text color="#ff6600" />                // Hex colors
+<Text color="rgb(255, 102, 0)" />       // RGB colors
+<Text color="ansi256:208" />            // ANSI 256 colors
+```
+
+## 🔧 API Reference
+
+### render(element, options?)
+
+Render a React element to the terminal.
+
+```tsx
+import { render } from "tinky";
+
+const { unmount, waitUntilExit, rerender, clear } = render(<App />, {
+  stdout: process.stdout,
+  stdin: process.stdin,
+  stderr: process.stderr,
+  exitOnCtrlC: true,
+  patchConsole: true,
+});
+
+// Wait for the app to exit
+await waitUntilExit();
+
+// Rerender with new props
+rerender(<App newProp={true} />);
+
+// Unmount the app
+unmount();
+
+// Clear the output
+clear();
+```
+
+### measureElement(ref)
+
+Measure the dimensions of a rendered element.
+
+```tsx
+import { measureElement, Box, useRef, useEffect } from "tinky";
+
+function MyComponent() {
+  const ref = useRef(null);
+
+  useEffect(() => {
+    if (ref.current) {
+      const { width, height } = measureElement(ref.current);
+      console.log(`Size: ${width}x${height}`);
+    }
+  }, []);
+
+  return <Box ref={ref}>Content</Box>;
+}
+```
+
+## 🧪 Testing
+
+Tinky uses Bun for testing. Run the test suite:
+
+```bash
+bun test
+```
+
+## 📄 License
+
+MIT © [ByteLandTechnology](https://github.com/ByteLandTechnology)
+
+## 🙏 Acknowledgements
+
+- [Ink](https://github.com/vadimdemedes/ink) — The original React for CLIs
+- [Taffy](https://github.com/DioxusLabs/taffy) — High-performance CSS layout engine
+- [React](https://reactjs.org/) — The UI library that makes this possible

package/README.zh-CN.md

@@ -0,0 +1,350 @@
+<p align="center">
+  <h1 align="center">Tinky</h1>
+  <p align="center">
+    <strong>使用 Taffy 布局引擎重新构想的 React CLI 框架</strong>
+  </p>
+  <p align="center">
+    <a href="./README.md">English</a> · <a href="./README.ja-JP.md">日本語</a>
+  </p>
+</p>
+
+---
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/tinky.svg)](https://www.npmjs.com/package/tinky)
+
+Tinky 是一个现代化的基于 React 的框架，用于构建美观且交互式的命令行界面。它利用强大的 [Taffy](https://github.com/DioxusLabs/taffy) 布局引擎，在终端中提供 **CSS Flexbox 和 Grid** 布局支持。
+
+## ✨ 特性
+
+- 🎨 **React 组件** — 使用熟悉的 React 模式和 JSX 语法构建 CLI
+- 📐 **Flexbox 和 Grid 布局** — 由 Taffy 驱动的完整 CSS Flexbox 和 CSS Grid 支持
+- ⌨️ **键盘输入** — 内置处理键盘输入和焦点管理的 hooks
+- 🎯 **焦点管理** — Tab/Shift+Tab 导航，可自定义焦点行为
+- 🖼️ **边框和背景** — 丰富的边框、背景色等样式支持
+- ♿ **无障碍访问** — 支持 ARIA 属性的屏幕阅读器
+- 🔄 **热重载** — 支持 React DevTools 的快速开发体验
+- 📦 **TypeScript 优先** — 完整的 TypeScript 支持和类型定义
+
+## 📦 安装
+
+```bash
+# 使用 npm
+npm install tinky react
+
+# 使用 yarn
+yarn add tinky react
+
+# 使用 pnpm
+pnpm add tinky react
+
+# 使用 bun
+bun add tinky react
+```
+
+## 🚀 快速开始
+
+```tsx
+import { render, Box, Text } from "tinky";
+
+function App() {
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text color="green" bold>
+        你好，Tinky！🎉
+      </Text>
+      <Text>用 React 构建漂亮的 CLI</Text>
+    </Box>
+  );
+}
+
+render(<App />);
+```
+
+## 📚 组件
+
+### Box
+
+`<Box>` 组件是基础构建块。它类似于浏览器中的 `<div>`，支持 Flexbox 和 Grid 布局。
+
+```tsx
+import { Box, Text } from "tinky";
+
+// Flexbox 布局
+<Box flexDirection="row" gap={2}>
+  <Text>左边</Text>
+  <Text>右边</Text>
+</Box>
+
+// Grid 布局
+<Box display="grid" gridTemplateColumns="1fr 2fr 1fr" gap={1}>
+  <Text>列 1</Text>
+  <Text>列 2</Text>
+  <Text>列 3</Text>
+</Box>
+
+// 带边框和内边距
+<Box borderStyle="round" borderColor="cyan" padding={1}>
+  <Text>样式化的 Box</Text>
+</Box>
+```
+
+### Text
+
+`<Text>` 组件渲染带样式的文本，支持颜色、粗体、斜体等。
+
+```tsx
+import { Text } from "tinky";
+
+<Text color="blue">蓝色文本</Text>
+<Text backgroundColor="red" color="white">高亮显示</Text>
+<Text bold italic underline>样式化文本</Text>
+<Text color="#ff6600">也支持十六进制颜色！</Text>
+```
+
+### Static
+
+`<Static>` 组件渲染不会更新的静态内容。非常适合日志和历史记录。
+
+```tsx
+import { Static, Text } from "tinky";
+
+const logs = ["日志 1", "日志 2", "日志 3"];
+
+<Static items={logs}>{(log, index) => <Text key={index}>{log}</Text>}</Static>;
+```
+
+### Transform
+
+`<Transform>` 组件允许你转换其子元素的输出。
+
+```tsx
+import { Transform, Text } from "tinky";
+
+<Transform transform={(output) => output.toUpperCase()}>
+  <Text>hello</Text>
+</Transform>;
+// 渲染结果: HELLO
+```
+
+### Newline 和 Spacer
+
+```tsx
+import { Box, Text, Newline, Spacer } from "tinky";
+
+// Newline - 添加垂直空间
+<Box flexDirection="column">
+  <Text>第一行</Text>
+  <Newline count={2} />
+  <Text>第二行</Text>
+</Box>
+
+// Spacer - flex 容器中的弹性空间
+<Box>
+  <Text>左边</Text>
+  <Spacer />
+  <Text>右边</Text>
+</Box>
+```
+
+## 🪝 Hooks
+
+### useInput
+
+在组件中处理键盘输入。
+
+```tsx
+import { useInput, useApp } from "tinky";
+
+function MyComponent() {
+  const { exit } = useApp();
+
+  useInput((input, key) => {
+    if (key.escape) {
+      exit();
+    }
+    if (key.upArrow) {
+      // 处理上箭头
+    }
+    if (input === "q") {
+      exit();
+    }
+  });
+
+  return <Text>按 'q' 退出</Text>;
+}
+```
+
+### useApp
+
+访问应用实例以控制退出行为。
+
+```tsx
+import { useApp } from "tinky";
+
+function MyComponent() {
+  const { exit } = useApp();
+
+  // 带错误退出
+  exit(new Error("出错了"));
+
+  // 正常退出
+  exit();
+}
+```
+
+### useFocus 和 useFocusManager
+
+管理交互式组件的焦点。
+
+```tsx
+import { useFocus, Box, Text } from "tinky";
+
+function FocusableItem({ label }: { label: string }) {
+  const { isFocused } = useFocus();
+
+  return (
+    <Box borderStyle={isFocused ? "bold" : "single"}>
+      <Text color={isFocused ? "green" : "white"}>{label}</Text>
+    </Box>
+  );
+}
+```
+
+### useStdin、useStdout、useStderr
+
+直接访问 stdin、stdout 和 stderr 流。
+
+```tsx
+import { useStdout, useEffect } from "tinky";
+
+function MyComponent() {
+  const { write } = useStdout();
+
+  useEffect(() => {
+    write("来自 stdout 的问候！\n");
+  }, []);
+
+  return null;
+}
+```
+
+## 🎨 样式
+
+### Flexbox 属性
+
+```tsx
+<Box
+  flexDirection="row" // row, row-reverse, column, column-reverse
+  justifyContent="center" // flex-start, flex-end, center, space-between, space-around
+  alignItems="center" // flex-start, flex-end, center, stretch
+  flexWrap="wrap" // nowrap, wrap, wrap-reverse
+  flexGrow={1}
+  flexShrink={0}
+  gap={2}
+/>
+```
+
+### Grid 属性
+
+```tsx
+<Box
+  display="grid"
+  gridTemplateColumns="1fr 2fr 1fr"
+  gridTemplateRows="auto 1fr"
+  columnGap={1}
+  rowGap={1}
+  justifyItems="center"
+  alignItems="center"
+/>
+```
+
+### 边框样式
+
+```tsx
+<Box borderStyle="single" />   // ┌─┐
+<Box borderStyle="double" />   // ╔═╗
+<Box borderStyle="round" />    // ╭─╮
+<Box borderStyle="bold" />     // ┏━┓
+<Box borderStyle="classic" />  // +--+
+```
+
+### 颜色
+
+Tinky 支持多种颜色格式：
+
+```tsx
+<Text color="red" />                    // 命名颜色
+<Text color="#ff6600" />                // 十六进制颜色
+<Text color="rgb(255, 102, 0)" />       // RGB 颜色
+<Text color="ansi256:208" />            // ANSI 256 颜色
+```
+
+## 🔧 API 参考
+
+### render(element, options?)
+
+将 React 元素渲染到终端。
+
+```tsx
+import { render } from "tinky";
+
+const { unmount, waitUntilExit, rerender, clear } = render(<App />, {
+  stdout: process.stdout,
+  stdin: process.stdin,
+  stderr: process.stderr,
+  exitOnCtrlC: true,
+  patchConsole: true,
+});
+
+// 等待应用退出
+await waitUntilExit();
+
+// 使用新 props 重新渲染
+rerender(<App newProp={true} />);
+
+// 卸载应用
+unmount();
+
+// 清除输出
+clear();
+```
+
+### measureElement(ref)
+
+测量已渲染元素的尺寸。
+
+```tsx
+import { measureElement, Box, useRef, useEffect } from "tinky";
+
+function MyComponent() {
+  const ref = useRef(null);
+
+  useEffect(() => {
+    if (ref.current) {
+      const { width, height } = measureElement(ref.current);
+      console.log(`尺寸: ${width}x${height}`);
+    }
+  }, []);
+
+  return <Box ref={ref}>内容</Box>;
+}
+```
+
+## 🧪 测试
+
+Tinky 使用 Bun 进行测试。运行测试套件：
+
+```bash
+bun test
+```
+
+## 📄 许可证
+
+MIT © [ByteLandTechnology](https://github.com/ByteLandTechnology)
+
+## 🙏 致谢
+
+- [Ink](https://github.com/vadimdemedes/ink) — 原版 React CLI 框架
+- [Taffy](https://github.com/DioxusLabs/taffy) — 高性能 CSS 布局引擎
+- [React](https://reactjs.org/) — 使这一切成为可能的 UI 库

package/lib/colorize.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Type representing the target of the color application (foreground or
+ * background).
+ */
+type ColorType = "foreground" | "background";
+/**
+ * Applies a color to a string using Chalk.
+ * Supports named colors, hex codes, RGB values, and ANSI-256 color codes.
+ *
+ * @param str - The string to colorize.
+ * @param color - The color to apply.
+ * @param type - Whether to apply the color to the foreground or background.
+ * @returns The colorized string.
+ */
+export declare const colorize: (str: string, color: string | undefined, type: ColorType) => string;
+export {};