@bastani/atomic 0.5.11 → 0.5.12-1

package/.agents/skills/opentui/references/components/text-display.md

@@ -0,0 +1,386 @@
+# Text & Display Components
+
+Components for displaying text content in OpenTUI.
+
+## Text Component
+
+The primary component for displaying styled text.
+
+### Basic Usage
+
+```tsx
+// React/Solid
+<text>Hello, World!</text>
+
+// With content prop
+<text content="Hello, World!" />
+
+// Core
+const text = new TextRenderable(renderer, {
+  id: "greeting",
+  content: "Hello, World!",
+})
+```
+
+### Styling (React/Solid)
+
+For React and Solid, use **nested modifier tags** for text styling:
+
+```tsx
+<text fg="#FFFFFF" bg="#000000">
+  <strong>Bold</strong>, <em>italic</em>, and <u>underlined</u>
+</text>
+```
+
+> **Important**: Do NOT use `bold`, `italic`, `underline`, `dim`, `strikethrough` as props on `<text>` — they don't work. Always use nested tags like `<strong>`, `<em>`, `<u>`, or `<span>` with styling.
+
+### Styling (Core) - Text Attributes
+
+```typescript
+import { TextRenderable, TextAttributes } from "@opentui/core"
+
+const text = new TextRenderable(renderer, {
+  content: "Styled",
+  attributes: TextAttributes.BOLD | TextAttributes.UNDERLINE,
+})
+```
+
+**Available attributes:**
+- `TextAttributes.BOLD`
+- `TextAttributes.DIM`
+- `TextAttributes.ITALIC`
+- `TextAttributes.UNDERLINE`
+- `TextAttributes.BLINK`
+- `TextAttributes.INVERSE`
+- `TextAttributes.HIDDEN`
+- `TextAttributes.STRIKETHROUGH`
+
+### Text Selection
+
+```tsx
+<text selectable>
+  This text can be selected by the user
+</text>
+
+<text selectable={false}>
+  This text cannot be selected
+</text>
+```
+
+For copy-on-selection and the full selection API, see `keyboard/REFERENCE.md` (selection).
+
+## Text Modifiers
+
+Inline styling elements that must be used inside `<text>`:
+
+### Span
+
+Inline styled text:
+
+```tsx
+<text>
+  Normal text with <span fg="red">red text</span> inline
+</text>
+```
+
+### Bold/Strong
+
+```tsx
+<text>
+  <strong>Bold text</strong>
+  <b>Also bold</b>
+</text>
+```
+
+### Italic/Emphasis
+
+```tsx
+<text>
+  <em>Italic text</em>
+  <i>Also italic</i>
+</text>
+```
+
+### Underline
+
+```tsx
+<text>
+  <u>Underlined text</u>
+</text>
+```
+
+### Line Break
+
+```tsx
+<text>
+  Line one
+  <br />
+  Line two
+</text>
+```
+
+### Link
+
+```tsx
+<text>
+  Visit <a href="https://example.com">our website</a>
+</text>
+```
+
+### Combined Modifiers
+
+```tsx
+<text>
+  <span fg="#00FF00">
+    <strong>Bold green</strong>
+  </span>
+  and
+  <span fg="#FF0000">
+    <em><u>italic underlined red</u></em>
+  </span>
+</text>
+```
+
+## Styled Text Template (Core)
+
+The `t` template literal for complex styling:
+
+```typescript
+import { t, bold, italic, underline, fg, bg, dim } from "@opentui/core"
+
+const styled = t`
+  ${bold("Bold")} and ${italic("italic")} text.
+  ${fg("#FF0000")("Red text")} with ${bg("#0000FF")("blue background")}.
+  ${dim("Dimmed")} and ${underline("underlined")}.
+`
+
+const text = new TextRenderable(renderer, {
+  content: styled,
+})
+```
+
+### Style Functions
+
+| Function | Description |
+|----------|-------------|
+| `bold(text)` | Bold text |
+| `italic(text)` | Italic text |
+| `underline(text)` | Underlined text |
+| `dim(text)` | Dimmed text |
+| `strikethrough(text)` | Strikethrough text |
+| `fg(color)(text)` | Set foreground color |
+| `bg(color)(text)` | Set background color |
+
+## ASCII Font Component
+
+Display large ASCII art text banners.
+
+### Basic Usage
+
+```tsx
+// React
+<ascii-font text="TITLE" font="tiny" />
+
+// Solid
+<ascii_font text="TITLE" font="tiny" />
+
+// Core
+const title = new ASCIIFontRenderable(renderer, {
+  id: "title",
+  text: "TITLE",
+  font: "tiny",
+})
+```
+
+### Available Fonts
+
+| Font | Description |
+|------|-------------|
+| `tiny` | Compact ASCII font |
+| `block` | Block-style letters |
+| `slick` | Sleek modern style |
+| `shade` | Shaded 3D effect |
+
+### Styling
+
+```tsx
+// React
+<ascii-font
+  text="HELLO"
+  font="block"
+  color="#00FF00"
+/>
+
+// Core
+import { RGBA } from "@opentui/core"
+
+const title = new ASCIIFontRenderable(renderer, {
+  text: "HELLO",
+  font: "block",
+  color: RGBA.fromHex("#00FF00"),
+})
+```
+
+### Example Output
+
+```
+Font: tiny
+╭─╮╭─╮╭─╮╭╮╭╮╭─╮╶╮╶ ╶╮
+│ ││─┘├┤ │╰╯││  │  │
+╰─╯╵  ╰─╯╵  ╵╰─╯╶╯╶╰─╯
+
+Font: block
+█▀▀█ █▀▀█ █▀▀ █▀▀▄
+█  █ █▀▀▀ █▀▀ █  █
+▀▀▀▀ ▀    ▀▀▀ ▀  ▀
+```
+
+## Colors
+
+### Color Formats
+
+```tsx
+// Hex colors
+<text fg="#FF0000">Red</text>
+<text fg="#F00">Short hex</text>
+
+// Named colors
+<text fg="red">Red</text>
+<text fg="blue">Blue</text>
+
+// Transparent
+<text bg="transparent">No background</text>
+```
+
+### RGBA Class
+
+The `RGBA` class from `@opentui/core` can be used in **all frameworks** (Core, React, Solid) for programmatic color manipulation:
+
+```typescript
+import { RGBA } from "@opentui/core"
+
+// From hex string (most common)
+const red = RGBA.fromHex("#FF0000")
+const shortHex = RGBA.fromHex("#F00")       // Short form supported
+
+// From integers (0-255 range for each channel)
+const green = RGBA.fromInts(0, 255, 0, 255)   // r, g, b, a
+const semiGreen = RGBA.fromInts(0, 255, 0, 128) // 50% transparent
+
+// From normalized floats (0.0-1.0 range)
+const blue = RGBA.fromValues(0.0, 0.0, 1.0, 1.0)  // r, g, b, a
+const overlay = RGBA.fromValues(0.1, 0.1, 0.1, 0.7) // Dark semi-transparent
+
+// Common use cases
+const backgroundColor = RGBA.fromHex("#1a1a2e")
+const textColor = RGBA.fromHex("#FFFFFF")
+const borderColor = RGBA.fromInts(122, 162, 247, 255) // Tokyo Night blue
+const shadowColor = RGBA.fromValues(0.0, 0.0, 0.0, 0.5) // 50% black
+```
+
+**When to use each method:**
+- `fromHex()` - When working with design specs or CSS colors
+- `fromInts()` - When you have 8-bit color values (0-255)
+- `fromValues()` - When doing color math or interpolation (normalized 0.0-1.0)
+
+### Using RGBA in React/Solid
+
+```tsx
+// React or Solid - RGBA works with color props
+import { RGBA } from "@opentui/core"
+
+const primaryColor = RGBA.fromHex("#7aa2f7")
+
+function MyComponent() {
+  return (
+    <box backgroundColor={primaryColor} borderColor={primaryColor}>
+      <text fg={RGBA.fromHex("#c0caf5")}>Styled with RGBA</text>
+    </box>
+  )
+}
+```
+
+Most props that accept color strings (`"#FF0000"`, `"red"`) also accept `RGBA` objects directly.
+
+## Text Wrapping
+
+Text wraps based on parent container:
+
+```tsx
+<box width={40}>
+  <text>
+    This long text will wrap when it reaches the edge of the 
+    40-character wide parent container.
+  </text>
+</box>
+```
+
+## Dynamic Content
+
+### React
+
+```tsx
+function Counter() {
+  const [count, setCount] = useState(0)
+  return <text>Count: {count}</text>
+}
+```
+
+### Solid
+
+```tsx
+function Counter() {
+  const [count, setCount] = createSignal(0)
+  return <text>Count: {count()}</text>
+}
+```
+
+### Core
+
+```typescript
+const text = new TextRenderable(renderer, {
+  id: "counter",
+  content: "Count: 0",
+})
+
+// Update later
+text.setContent("Count: 1")
+```
+
+## Gotchas
+
+### Text Modifiers Outside Text
+
+```tsx
+// WRONG - modifiers only work inside <text>
+<box>
+  <strong>Won't work</strong>
+</box>
+
+// CORRECT
+<box>
+  <text>
+    <strong>This works</strong>
+  </text>
+</box>
+```
+
+### Empty Text
+
+```tsx
+// May cause layout issues
+<text></text>
+
+// Better - use space or conditional
+<text>{content || " "}</text>
+```
+
+### Color Format
+
+```tsx
+// WRONG
+<text fg="FF0000">Missing #</text>
+
+// CORRECT
+<text fg="#FF0000">With #</text>
+```

package/.agents/skills/opentui/references/core/REFERENCE.md

@@ -0,0 +1,145 @@
+# OpenTUI Core (@opentui/core)
+
+The foundational library for building terminal user interfaces. Provides an imperative API with all primitives, giving you maximum control over rendering, state, and behavior.
+
+## Overview
+
+OpenTUI Core runs on Bun with native Zig bindings for performance-critical operations:
+- **Renderer**: Manages terminal output, input events, and the rendering loop
+- **Renderables**: Hierarchical UI building blocks with Yoga layout
+- **Constructs**: Declarative wrappers for composing Renderables
+- **FrameBuffer**: Low-level 2D rendering surface for custom graphics
+
+## When to Use Core
+
+Use the core imperative API when:
+- Building a library or framework on top of OpenTUI
+- Need maximum control over rendering and state
+- Want smallest possible bundle size (no React/Solid runtime)
+- Building performance-critical applications
+- Integrating with existing imperative codebases
+
+## When NOT to Use Core
+
+| Scenario | Use Instead |
+|----------|-------------|
+| Familiar with React patterns | `@opentui/react` |
+| Want fine-grained reactivity | `@opentui/solid` |
+| Building typical applications | React or Solid reconciler |
+| Rapid prototyping | React or Solid reconciler |
+
+## Quick Start
+
+### Using create-tui (Recommended)
+
+```bash
+bunx create-tui@latest -t core my-app
+cd my-app
+bun run src/index.ts
+```
+
+The CLI creates the `my-app` directory for you - it must **not already exist**.
+
+**Agent guidance**: Always use autonomous mode with `-t <template>` flag. Never use interactive mode (`bunx create-tui@latest my-app` without `-t`) as it requires user prompts that agents cannot respond to.
+
+### Manual Setup
+
+```bash
+mkdir my-tui && cd my-tui
+bun init
+bun install @opentui/core
+```
+
+```typescript
+import { createCliRenderer, TextRenderable, BoxRenderable } from "@opentui/core"
+
+const renderer = await createCliRenderer()
+
+// Create a box container
+const container = new BoxRenderable(renderer, {
+  id: "container",
+  width: 40,
+  height: 10,
+  border: true,
+  borderStyle: "rounded",
+  padding: 1,
+})
+
+// Create text inside the box
+const greeting = new TextRenderable(renderer, {
+  id: "greeting",
+  content: "Hello, OpenTUI!",
+  fg: "#00FF00",
+})
+
+// Compose the tree
+container.add(greeting)
+renderer.root.add(container)
+```
+
+## Core Concepts
+
+### Renderer
+
+The `CliRenderer` orchestrates everything:
+- Manages the terminal viewport and alternate screen
+- Handles input events (keyboard, mouse, paste)
+- Runs the rendering loop (configurable FPS)
+- Provides the root node for the renderable tree
+
+### Renderables vs Constructs
+
+| Renderables (Imperative) | Constructs (Declarative) |
+|--------------------------|--------------------------|
+| `new TextRenderable(renderer, {...})` | `Text({...})` |
+| Requires renderer at creation | Creates VNode, instantiated later |
+| Direct mutation via methods | Chained calls recorded, replayed on instantiation |
+| Full control | Cleaner composition |
+
+### Storage Options
+
+Renderables can be composed in two ways:
+1. **Imperative**: Create instances, call `.add()` to compose
+2. **Declarative (Constructs)**: Create VNodes, pass children as arguments
+
+## Essential Commands
+
+```bash
+bun install @opentui/core     # Install
+bun run src/index.ts          # Run directly (no build needed)
+bun test                      # Run tests
+```
+
+## Runtime Requirements
+
+OpenTUI runs on Bun and uses Zig for native builds.
+
+```bash
+# Package management
+bun install @opentui/core
+
+# Running
+bun run src/index.ts
+bun test
+
+# Building (only needed for native code changes)
+bun run build
+```
+
+**Zig** is required for building native components.
+
+## In This Reference
+
+- [Configuration](./configuration.md) - Renderer options, environment variables
+- [API](./api.md) - Renderer, Renderables, types, utilities
+- [Patterns](./patterns.md) - Composition, events, state management
+- [Gotchas](./gotchas.md) - Common issues, debugging, limitations
+
+## See Also
+
+- [React](../react/REFERENCE.md) - React reconciler for declarative TUI
+- [Solid](../solid/REFERENCE.md) - Solid reconciler for declarative TUI
+- [Layout](../layout/REFERENCE.md) - Yoga/Flexbox layout system
+- [Components](../components/REFERENCE.md) - Component reference by category
+- [Keyboard](../keyboard/REFERENCE.md) - Input handling and shortcuts
+- [Testing](../testing/REFERENCE.md) - Test renderer and snapshots