@bastani/atomic 0.5.11 → 0.5.12-0

package/.agents/skills/opentui/references/react/api.md

@@ -0,0 +1,436 @@
+# React API Reference
+
+## Rendering
+
+### createRoot(renderer)
+
+Creates a React root for rendering.
+
+```tsx
+import { createCliRenderer } from "@opentui/core"
+import { createRoot } from "@opentui/react"
+
+const renderer = await createCliRenderer({
+  exitOnCtrlC: false,  // Handle Ctrl+C yourself
+})
+
+const root = createRoot(renderer)
+root.render(<App />)
+```
+
+## Hooks
+
+### useRenderer()
+
+Access the OpenTUI renderer instance.
+
+```tsx
+import { useRenderer } from "@opentui/react"
+import { useEffect } from "react"
+
+function App() {
+  const renderer = useRenderer()
+  
+  useEffect(() => {
+    // Access renderer properties
+    console.log(`Terminal: ${renderer.width}x${renderer.height}`)
+    
+    // Show debug console
+    renderer.console.show()
+    
+    // Access theme mode (dark/light based on terminal settings)
+    console.log(`Theme: ${renderer.themeMode}`)  // "dark" | "light" | null
+  }, [renderer])
+  
+  return <text>Hello</text>
+}
+
+// Listen for theme mode changes
+function ThemedApp() {
+  const renderer = useRenderer()
+  const [theme, setTheme] = useState(renderer.themeMode ?? "dark")
+  
+  useEffect(() => {
+    const handler = (mode: "dark" | "light") => setTheme(mode)
+    renderer.on("theme_mode", handler)
+    return () => renderer.off("theme_mode", handler)
+  }, [renderer])
+  
+  return (
+    <box backgroundColor={theme === "dark" ? "#1a1a2e" : "#ffffff"}>
+      <text fg={theme === "dark" ? "#fff" : "#000"}>
+        Current theme: {theme}
+      </text>
+    </box>
+  )
+}
+```
+
+### useKeyboard(handler, options?)
+
+Handle keyboard events.
+
+```tsx
+import { useKeyboard, useRenderer } from "@opentui/react"
+
+function App() {
+  const renderer = useRenderer()
+  
+  useKeyboard((key) => {
+    if (key.name === "escape") {
+      renderer.destroy()  // Never use process.exit() directly!
+    }
+    if (key.ctrl && key.name === "s") {
+      saveDocument()
+    }
+  })
+  
+  return <text>Press ESC to exit</text>
+}
+
+// With release events
+function GameControls() {
+  const [pressed, setPressed] = useState(new Set<string>())
+  
+  useKeyboard(
+    (event) => {
+      setPressed(keys => {
+        const newKeys = new Set(keys)
+        if (event.eventType === "release") {
+          newKeys.delete(event.name)
+        } else {
+          newKeys.add(event.name)
+        }
+        return newKeys
+      })
+    },
+    { release: true }  // Include release events
+  )
+  
+  return <text>Pressed: {Array.from(pressed).join(", ")}</text>
+}
+```
+
+**Options:**
+- `release?: boolean` - Include key release events (default: false)
+
+**KeyEvent properties:**
+- `name: string` - Key name ("a", "escape", "f1", etc.)
+- `sequence: string` - Raw escape sequence
+- `ctrl: boolean` - Ctrl modifier
+- `shift: boolean` - Shift modifier
+- `meta: boolean` - Alt modifier
+- `option: boolean` - Option modifier (macOS)
+- `eventType: "press" | "release" | "repeat"`
+- `repeated: boolean` - Key is being held
+
+### useOnResize(callback)
+
+Handle terminal resize events.
+
+```tsx
+import { useOnResize } from "@opentui/react"
+
+function App() {
+  useOnResize((width, height) => {
+    console.log(`Resized to ${width}x${height}`)
+  })
+  
+  return <text>Resize the terminal</text>
+}
+```
+
+### useTerminalDimensions()
+
+Get reactive terminal dimensions.
+
+```tsx
+import { useTerminalDimensions } from "@opentui/react"
+
+function ResponsiveLayout() {
+  const { width, height } = useTerminalDimensions()
+  
+  return (
+    <box flexDirection={width > 80 ? "row" : "column"}>
+      <box flexGrow={1}>
+        <text>Width: {width}</text>
+      </box>
+      <box flexGrow={1}>
+        <text>Height: {height}</text>
+      </box>
+    </box>
+  )
+}
+```
+
+### useTimeline(options?)
+
+Create animations with the timeline system.
+
+```tsx
+import { useTimeline } from "@opentui/react"
+import { useEffect, useState } from "react"
+
+function AnimatedBox() {
+  const [width, setWidth] = useState(0)
+  
+  const timeline = useTimeline({
+    duration: 2000,
+    loop: false,
+  })
+  
+  useEffect(() => {
+    timeline.add(
+      { width: 0 },
+      {
+        width: 50,
+        duration: 2000,
+        ease: "easeOutQuad",
+        onUpdate: (anim) => {
+          setWidth(Math.round(anim.targets[0].width))
+        },
+      }
+    )
+  }, [timeline])
+  
+  return <box style={{ width, height: 3, backgroundColor: "#6a5acd" }} />
+}
+```
+
+**Options:**
+- `duration?: number` - Default duration (ms)
+- `loop?: boolean` - Loop the timeline
+- `autoplay?: boolean` - Auto-start (default: true)
+- `onComplete?: () => void` - Completion callback
+- `onPause?: () => void` - Pause callback
+
+**Timeline methods:**
+- `add(target, properties, startTime?)` - Add animation
+- `play()` - Start playback
+- `pause()` - Pause playback
+- `restart()` - Restart from beginning
+
+## Components
+
+### Text Component
+
+```tsx
+<text
+  content="Hello"           // Or use children
+  fg="#FFFFFF"              // Foreground color
+  bg="#000000"              // Background color
+  selectable={true}         // Allow text selection
+>
+  {/* Use nested modifier tags for styling */}
+  <span fg="red">Red</span>
+  <strong>Bold</strong>
+  <em>Italic</em>
+  <u>Underline</u>
+  <br />
+  <a href="https://...">Link</a>
+</text>
+```
+
+> **Note**: Do NOT use `bold`, `italic`, `underline` as props on `<text>`. Use nested modifier tags like `<strong>`, `<em>`, `<u>` instead.
+
+### Box Component
+
+```tsx
+<box
+  // Borders
+  border                    // Enable border
+  borderStyle="single"      // single | double | rounded | bold
+  borderColor="#FFFFFF"
+  title="Title"
+  titleAlignment="center"   // left | center | right
+  
+  // Colors
+  backgroundColor="#1a1a2e"
+  
+  // Layout (see layout/REFERENCE.md)
+  flexDirection="row"
+  justifyContent="center"
+  alignItems="center"
+  gap={2}
+  
+  // Spacing
+  padding={2}
+  paddingTop={1}
+  paddingX={2}              // Horizontal (left + right)
+  paddingY={1}              // Vertical (top + bottom)
+  margin={1}
+  marginX={2}               // Horizontal (left + right)
+  marginY={1}               // Vertical (top + bottom)
+  
+  // Dimensions
+  width={40}
+  height={10}
+  flexGrow={1}
+  
+  // Focus
+  focusable                 // Allow box to receive focus
+  focused={isFocused}       // Controlled focus state
+  
+  // Events
+  onMouseDown={(e) => {}}
+  onMouseUp={(e) => {}}
+  onMouseMove={(e) => {}}
+>
+  {children}
+</box>
+```
+
+### Scrollbox Component
+
+```tsx
+<scrollbox
+  focused                   // Enable keyboard scrolling
+  style={{
+    rootOptions: { backgroundColor: "#24283b" },
+    wrapperOptions: { backgroundColor: "#1f2335" },
+    viewportOptions: { backgroundColor: "#1a1b26" },
+    contentOptions: { backgroundColor: "#16161e" },
+    scrollbarOptions: {
+      showArrows: true,
+      trackOptions: {
+        foregroundColor: "#7aa2f7",
+        backgroundColor: "#414868",
+      },
+    },
+  }}
+>
+  {/* Scrollable content */}
+  {items.map((item, i) => (
+    <box key={i}>
+      <text>{item}</text>
+    </box>
+  ))}
+</scrollbox>
+```
+
+### Input Component
+
+```tsx
+<input
+  value={value}
+  onChange={(newValue) => setValue(newValue)}
+  placeholder="Enter text..."
+  focused                   // Start focused
+  width={30}
+  backgroundColor="#1a1a1a"
+  textColor="#FFFFFF"
+  cursorColor="#00FF00"
+  focusedBackgroundColor="#2a2a2a"
+/>
+```
+
+### Textarea Component
+
+```tsx
+<textarea
+  value={text}
+  onChange={(newValue) => setText(newValue)}
+  placeholder="Enter multiple lines..."
+  focused
+  width={40}
+  height={10}
+  showLineNumbers
+  wrapText
+/>
+```
+
+### Select Component
+
+```tsx
+<select
+  options={[
+    { name: "Option 1", description: "First option", value: "1" },
+    { name: "Option 2", description: "Second option", value: "2" },
+  ]}
+  onChange={(index, option) => setSelected(option)}
+  selectedIndex={0}
+  focused
+  showScrollIndicator
+  height={8}
+/>
+```
+
+### Tab Select Component
+
+```tsx
+<tab-select
+  options={[
+    { name: "Home", description: "Dashboard" },
+    { name: "Settings", description: "Configuration" },
+  ]}
+  onChange={(index, option) => setTab(option)}
+  tabWidth={20}
+  focused
+/>
+```
+
+### ASCII Font Component
+
+```tsx
+<ascii-font
+  text="TITLE"
+  font="tiny"               // tiny | block | slick | shade
+  color="#FFFFFF"
+/>
+```
+
+### Code Component
+
+```tsx
+<code
+  code={sourceCode}
+  language="typescript"
+  showLineNumbers
+  highlightLines={[1, 5, 10]}
+/>
+```
+
+### Line Number Component
+
+```tsx
+<line-number
+  code={sourceCode}
+  language="typescript"
+  startLine={1}
+  highlightedLines={[5]}
+  diagnostics={[
+    { line: 3, severity: "error", message: "Syntax error" }
+  ]}
+/>
+```
+
+### Diff Component
+
+```tsx
+<diff
+  oldCode={originalCode}
+  newCode={modifiedCode}
+  language="typescript"
+  mode="unified"            // unified | split
+  syncScroll                // Sync scroll between split view panes
+  showLineNumbers
+/>
+```
+
+## Type Exports
+
+```tsx
+import type {
+  // Component props
+  TextProps,
+  BoxProps,
+  InputProps,
+  SelectProps,
+  
+  // Hook types
+  KeyEvent,
+  
+  // From core
+  CliRenderer,
+} from "@opentui/react"
+```

package/.agents/skills/opentui/references/react/configuration.md

@@ -0,0 +1,302 @@
+# React Configuration
+
+## Project Setup
+
+### Quick Start
+
+```bash
+bunx create-tui@latest -t react my-app
+cd my-app && bun install
+```
+
+The CLI creates the `my-app` directory for you - it must **not already exist**.
+
+Options: `--no-git` (skip git init), `--no-install` (skip bun install)
+
+### Manual Setup
+
+```bash
+mkdir my-tui && cd my-tui
+bun init
+bun install @opentui/react @opentui/core react
+```
+
+## TypeScript Configuration
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    
+    "jsx": "react-jsx",
+    "jsxImportSource": "@opentui/react",
+    
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"]
+}
+```
+
+**Critical settings:**
+- `jsx: "react-jsx"` - Use the new JSX transform
+- `jsxImportSource: "@opentui/react"` - Import JSX runtime from OpenTUI
+- `module` / `moduleResolution: "NodeNext"` - Recommended for OpenTUI compatibility
+
+### Why DOM lib?
+
+The `DOM` lib is needed for React types. OpenTUI's JSX types extend React's.
+
+## Package Configuration
+
+### package.json
+
+```json
+{
+  "name": "my-tui-app",
+  "type": "module",
+  "scripts": {
+    "start": "bun run src/index.tsx",
+    "dev": "bun --watch run src/index.tsx",
+    "test": "bun test",
+    "build": "bun build src/index.tsx --outdir=dist --target=bun"
+  },
+  "dependencies": {
+    "@opentui/core": "latest",
+    "@opentui/react": "latest",
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": ">=19.0.0",
+    "typescript": "latest"
+  }
+}
+```
+
+## Project Structure
+
+Recommended structure:
+
+```
+my-tui-app/
+├── src/
+│   ├── components/
+│   │   ├── Header.tsx
+│   │   ├── Sidebar.tsx
+│   │   └── MainContent.tsx
+│   ├── hooks/
+│   │   └── useAppState.ts
+│   ├── App.tsx
+│   └── index.tsx
+├── package.json
+└── tsconfig.json
+```
+
+### Entry Point (src/index.tsx)
+
+```tsx
+import { createCliRenderer } from "@opentui/core"
+import { createRoot } from "@opentui/react"
+import { App } from "./App"
+
+const renderer = await createCliRenderer({
+  exitOnCtrlC: true,
+})
+
+createRoot(renderer).render(<App />)
+```
+
+### App Component (src/App.tsx)
+
+```tsx
+import { Header } from "./components/Header"
+import { Sidebar } from "./components/Sidebar"
+import { MainContent } from "./components/MainContent"
+
+export function App() {
+  return (
+    <box flexDirection="column" width="100%" height="100%">
+      <Header />
+      <box flexDirection="row" flexGrow={1}>
+        <Sidebar />
+        <MainContent />
+      </box>
+    </box>
+  )
+}
+```
+
+## Renderer Configuration
+
+### createCliRenderer Options
+
+```tsx
+import { createCliRenderer, ConsolePosition } from "@opentui/core"
+
+const renderer = await createCliRenderer({
+  // Rendering
+  targetFPS: 60,
+  
+  // Behavior
+  exitOnCtrlC: true,        // Set false to handle Ctrl+C yourself
+  autoFocus: true,          // Auto-focus elements on click (default: true)
+  useMouse: true,           // Enable mouse support (default: true)
+  
+  // Debug console
+  consoleOptions: {
+    position: ConsolePosition.BOTTOM,
+    sizePercent: 30,
+    startInDebugMode: false,
+  },
+  
+  // Cleanup
+  onDestroy: () => {
+    // Cleanup code
+  },
+})
+```
+
+## Building for Distribution
+
+### Bundling with Bun
+
+```typescript
+// build.ts
+await Bun.build({
+  entrypoints: ["./src/index.tsx"],
+  outdir: "./dist",
+  target: "bun",
+  minify: true,
+})
+```
+
+Run: `bun run build.ts`
+
+### Creating Executables
+
+```typescript
+// build.ts
+await Bun.build({
+  entrypoints: ["./src/index.tsx"],
+  outdir: "./dist",
+  target: "bun",
+  compile: {
+    target: "bun-darwin-arm64",  // or bun-linux-x64, etc.
+    outfile: "my-app",
+  },
+})
+```
+
+## Environment Variables
+
+Create `.env` for development:
+
+```env
+# Debug settings
+OTUI_SHOW_STATS=false
+SHOW_CONSOLE=false
+
+# App settings
+API_URL=https://api.example.com
+```
+
+Bun auto-loads `.env` files. Access via `process.env`:
+
+```tsx
+const apiUrl = process.env.API_URL
+```
+
+## React DevTools
+
+OpenTUI React supports React DevTools for debugging.
+
+### Setup
+
+1. Install DevTools as a dev dependency (must use version 7):
+   ```bash
+   bun add react-devtools-core@7 -d
+   ```
+
+2. Run DevTools standalone app:
+   ```bash
+   npx react-devtools@7
+   ```
+
+3. Start your app with `DEV=true` environment variable:
+   ```bash
+   DEV=true bun run src/index.tsx
+   ```
+
+**Important**: Auto-connect to DevTools ONLY happens when `DEV=true` is set. Without this environment variable, the DevTools connection code is not loaded.
+
+### How It Works
+
+OpenTUI checks for `process.env["DEV"] === "true"` at startup. When true, it dynamically imports `react-devtools-core` and connects to the standalone DevTools app.
+
+## Testing Configuration
+
+### Test Setup
+
+```typescript
+// src/test-utils.tsx
+import { createTestRenderer } from "@opentui/core/testing"
+import { createRoot } from "@opentui/react"
+
+export async function renderForTest(
+  element: React.ReactElement,
+  options = { width: 80, height: 24 }
+) {
+  const testSetup = await createTestRenderer(options)
+  createRoot(testSetup.renderer).render(element)
+  return testSetup
+}
+```
+
+### Test Example
+
+```typescript
+// src/components/Counter.test.tsx
+import { test, expect } from "bun:test"
+import { renderForTest } from "../test-utils"
+import { Counter } from "./Counter"
+
+test("Counter renders initial value", async () => {
+  const { snapshot } = await renderForTest(<Counter initialValue={5} />)
+  expect(snapshot()).toContain("Count: 5")
+})
+```
+
+## Common Issues
+
+### JSX Types Not Working
+
+Ensure `jsxImportSource` is set:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@opentui/react"
+  }
+}
+```
+
+### React Version Mismatch
+
+Ensure React 19+:
+
+```bash
+bun install react@19 @types/react@19
+```
+
+### Module Resolution Errors
+
+Use `moduleResolution: "bundler"` for Bun compatibility.