@dealdeploy/skl 0.1.6 → 0.1.8

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

@@ -0,0 +1,143 @@
+# OpenTUI Components
+
+Reference for all OpenTUI components, organized by category. Components are available in all three frameworks (Core, React, Solid) with slight API differences.
+
+## When to Use
+
+Use this reference when you need to find the right component category or compare naming across Core, React, and Solid.
+
+## Component Categories
+
+| Category | Components | File |
+|----------|------------|------|
+| Text & Display | text, ascii-font, styled text | [text-display.md](./text-display.md) |
+| Containers | box, scrollbox, borders | [containers.md](./containers.md) |
+| Inputs | input, textarea, select, tab-select | [inputs.md](./inputs.md) |
+| Code & Diff | code, line-number, diff, markdown | [code-diff.md](./code-diff.md) |
+
+## Component Chooser
+
+```
+Need a component?
+├─ Styled text or ASCII art -> text-display.md
+├─ Containers, borders, scrolling -> containers.md
+├─ Forms or input controls -> inputs.md
+└─ Code blocks, diffs, line numbers, markdown -> code-diff.md
+```
+
+## Component Naming
+
+Components have different names across frameworks:
+
+| Concept | Core (Class) | React (JSX) | Solid (JSX) |
+|---------|--------------|-------------|-------------|
+| Text | `TextRenderable` | `<text>` | `<text>` |
+| Box | `BoxRenderable` | `<box>` | `<box>` |
+| ScrollBox | `ScrollBoxRenderable` | `<scrollbox>` | `<scrollbox>` |
+| Input | `InputRenderable` | `<input>` | `<input>` |
+| Textarea | `TextareaRenderable` | `<textarea>` | `<textarea>` |
+| Select | `SelectRenderable` | `<select>` | `<select>` |
+| Tab Select | `TabSelectRenderable` | `<tab-select>` | `<tab_select>` |
+| ASCII Font | `ASCIIFontRenderable` | `<ascii-font>` | `<ascii_font>` |
+| Code | `CodeRenderable` | `<code>` | `<code>` |
+| Line Number | `LineNumberRenderable` | `<line-number>` | `<line_number>` |
+| Diff | `DiffRenderable` | `<diff>` | `<diff>` |
+| Markdown | `MarkdownRenderable` | `<markdown>` | `<markdown>` |
+
+**Note**: Solid uses underscores (`tab_select`) while React uses hyphens (`tab-select`).
+
+## Common Properties
+
+All components share these layout properties (see [Layout](../layout/REFERENCE.md)):
+
+```tsx
+// Positioning
+position="relative" | "absolute"
+left, top, right, bottom
+
+// Dimensions
+width, height
+minWidth, maxWidth, minHeight, maxHeight
+
+// Flexbox
+flexDirection, flexGrow, flexShrink, flexBasis
+justifyContent, alignItems, alignSelf
+flexWrap, gap
+
+// Spacing
+padding, paddingTop, paddingRight, paddingBottom, paddingLeft
+paddingX, paddingY              // Axis shorthand (horizontal/vertical)
+margin, marginTop, marginRight, marginBottom, marginLeft
+marginX, marginY                // Axis shorthand (horizontal/vertical)
+
+// Display
+display="flex" | "none"
+overflow="visible" | "hidden" | "scroll"
+zIndex
+```
+
+## Quick Examples
+
+### Core (Imperative)
+
+```typescript
+import { createCliRenderer, TextRenderable, BoxRenderable } from "@opentui/core"
+
+const renderer = await createCliRenderer()
+
+const box = new BoxRenderable(renderer, {
+  id: "container",
+  border: true,
+  padding: 2,
+})
+
+const text = new TextRenderable(renderer, {
+  id: "greeting",
+  content: "Hello!",
+  fg: "#00FF00",
+})
+
+box.add(text)
+renderer.root.add(box)
+```
+
+### React
+
+```tsx
+import { createCliRenderer } from "@opentui/core"
+import { createRoot } from "@opentui/react"
+
+function App() {
+  return (
+    <box border padding={2}>
+      <text fg="#00FF00">Hello!</text>
+    </box>
+  )
+}
+
+const renderer = await createCliRenderer()
+createRoot(renderer).render(<App />)
+```
+
+### Solid
+
+```tsx
+import { render } from "@opentui/solid"
+
+function App() {
+  return (
+    <box border padding={2}>
+      <text fg="#00FF00">Hello!</text>
+    </box>
+  )
+}
+
+render(() => <App />)
+```
+
+## See Also
+
+- [Core API](../core/api.md) - Imperative component classes
+- [React API](../react/api.md) - React component props
+- [Solid API](../solid/api.md) - Solid component props
+- [Layout](../layout/REFERENCE.md) - Layout system details

package/.agents/skills/opentui/references/components/code-diff.md

@@ -0,0 +1,496 @@
+# Code & Diff Components
+
+Components for displaying code with syntax highlighting and diffs in OpenTUI.
+
+## Code Component
+
+Display syntax-highlighted code blocks.
+
+### Basic Usage
+
+```tsx
+// React
+<code
+  code={`function hello() {
+  console.log("Hello, World!");
+}`}
+  language="typescript"
+/>
+
+// Solid
+<code
+  code={sourceCode}
+  language="javascript"
+/>
+
+// Core
+const codeBlock = new CodeRenderable(renderer, {
+  id: "code",
+  code: sourceCode,
+  language: "typescript",
+})
+```
+
+### Supported Languages
+
+OpenTUI uses Tree-sitter for syntax highlighting. Common languages:
+- `typescript`, `javascript`
+- `python`
+- `rust`
+- `go`
+- `json`
+- `html`, `css`
+- `markdown`
+- `bash`, `shell`
+
+### Styling
+
+```tsx
+<code
+  code={sourceCode}
+  language="typescript"
+  backgroundColor="#1a1a2e"
+  showLineNumbers
+/>
+```
+
+### onHighlight Callback
+
+Intercept and modify syntax highlights before rendering:
+
+```tsx
+// Core
+const codeBlock = new CodeRenderable(renderer, {
+  id: "code",
+  code: sourceCode,
+  language: "typescript",
+  onHighlight: (highlights, context) => {
+    // Add custom highlights
+    highlights.push([10, 20, "custom.error", {}])
+    return highlights
+  },
+})
+
+// React/Solid
+<code
+  code={sourceCode}
+  language="typescript"
+  onHighlight={(highlights, context) => {
+    // context: { content, filetype, syntaxStyle }
+    // Modify and return highlights array
+    return highlights.filter(h => h[2] !== "comment")
+  }}
+/>
+```
+
+**Callback signature:**
+- `highlights: SimpleHighlight[]` - Array of `[start, end, scope, metadata]`
+- `context: { content, filetype, syntaxStyle }` - Highlighting context
+- Return modified highlights array or `undefined` to use original
+
+Supports async callbacks for fetching additional highlight data.
+
+## Line Number Component
+
+Code display with line numbers, highlighting, and diagnostics.
+
+### Basic Usage
+
+```tsx
+// React
+<line-number
+  code={sourceCode}
+  language="typescript"
+/>
+
+// Solid (note underscore)
+<line_number
+  code={sourceCode}
+  language="typescript"
+/>
+
+// Core
+const codeView = new LineNumberRenderable(renderer, {
+  id: "code-view",
+  code: sourceCode,
+  language: "typescript",
+})
+```
+
+### Line Number Options
+
+```tsx
+// React
+<line-number
+  code={sourceCode}
+  language="typescript"
+  startLine={1}              // Starting line number
+  showLineNumbers={true}     // Display line numbers
+/>
+
+// Solid
+<line_number
+  code={sourceCode}
+  language="typescript"
+  startLine={1}
+  showLineNumbers={true}
+/>
+```
+
+### Line Highlighting
+
+Highlight specific lines:
+
+```tsx
+// React
+<line-number
+  code={sourceCode}
+  language="typescript"
+  highlightedLines={[5, 10, 15]}  // Highlight these lines
+/>
+
+// Solid
+<line_number
+  code={sourceCode}
+  language="typescript"
+  highlightedLines={[5, 10, 15]}
+/>
+```
+
+### Diagnostics
+
+Show errors, warnings, and info on specific lines:
+
+```tsx
+// React
+<line-number
+  code={sourceCode}
+  language="typescript"
+  diagnostics={[
+    { line: 3, severity: "error", message: "Unexpected token" },
+    { line: 7, severity: "warning", message: "Unused variable" },
+    { line: 12, severity: "info", message: "Consider using const" },
+  ]}
+/>
+
+// Solid
+<line_number
+  code={sourceCode}
+  language="typescript"
+  diagnostics={[
+    { line: 3, severity: "error", message: "Unexpected token" },
+  ]}
+/>
+```
+
+**Diagnostic severity levels:**
+- `error` - Red indicator
+- `warning` - Yellow indicator
+- `info` - Blue indicator
+- `hint` - Gray indicator
+
+### Diff Highlighting
+
+Show added/removed lines:
+
+```tsx
+<line-number
+  code={sourceCode}
+  language="typescript"
+  addedLines={[5, 6, 7]}      // Green background
+  removedLines={[10, 11]}     // Red background
+/>
+```
+
+## Diff Component
+
+Unified or split diff viewer with syntax highlighting.
+
+### Basic Usage
+
+```tsx
+// React
+<diff
+  oldCode={originalCode}
+  newCode={modifiedCode}
+  language="typescript"
+/>
+
+// Solid
+<diff
+  oldCode={originalCode}
+  newCode={modifiedCode}
+  language="typescript"
+/>
+
+// Core
+const diffView = new DiffRenderable(renderer, {
+  id: "diff",
+  oldCode: originalCode,
+  newCode: modifiedCode,
+  language: "typescript",
+})
+```
+
+### Display Modes
+
+```tsx
+// Unified diff (default)
+<diff
+  oldCode={old}
+  newCode={new}
+  mode="unified"
+/>
+
+// Split/side-by-side diff
+<diff
+  oldCode={old}
+  newCode={new}
+  mode="split"
+/>
+```
+
+### Options
+
+```tsx
+<diff
+  oldCode={originalCode}
+  newCode={modifiedCode}
+  language="typescript"
+  mode="unified"
+  showLineNumbers
+  context={3}                // Lines of context around changes
+/>
+```
+
+### Styling
+
+```tsx
+<diff
+  oldCode={old}
+  newCode={new}
+  addedLineColor="#2d4f2d"   // Background for added lines
+  removedLineColor="#4f2d2d" // Background for removed lines
+  unchangedLineColor="transparent"
+/>
+```
+
+## Markdown Component
+
+Render markdown content with syntax highlighting for code blocks.
+
+### Basic Usage
+
+```tsx
+// React
+<markdown
+  content={markdownText}
+  syntaxStyle={mySyntaxStyle}
+/>
+
+// Solid
+<markdown
+  content={markdownText}
+  syntaxStyle={mySyntaxStyle}
+/>
+
+// Core
+import { MarkdownRenderable } from "@opentui/core"
+
+const md = new MarkdownRenderable(renderer, {
+  id: "markdown",
+  content: "# Hello\n\nThis is **markdown**.",
+  syntaxStyle: mySyntaxStyle,
+})
+```
+
+### Options
+
+```tsx
+<markdown
+  content={markdownText}
+  syntaxStyle={syntaxStyle}
+  treeSitterClient={client}  // Optional: custom tree-sitter client
+  conceal={true}             // Hide markdown syntax characters
+  streaming={true}           // Enable streaming mode for incremental updates
+/>
+```
+
+### Custom Node Rendering
+
+```tsx
+// Core
+const md = new MarkdownRenderable(renderer, {
+  id: "markdown",
+  content: "# Custom Heading",
+  syntaxStyle,
+  renderNode: (node, ctx, defaultRender) => {
+    if (node.type === "heading") {
+      // Return custom renderable for headings
+      return new TextRenderable(ctx, {
+        content: `>> ${node.content} <<`,
+      })
+    }
+    return null // Use default rendering
+  },
+})
+```
+
+### Streaming Mode
+
+For real-time content like LLM output:
+
+```tsx
+const [content, setContent] = useState("")
+
+// Append text as it arrives
+useEffect(() => {
+  llmStream.on("token", (token) => {
+    setContent(c => c + token)
+  })
+}, [])
+
+<markdown
+  content={content}
+  syntaxStyle={syntaxStyle}
+  streaming={true}  // Optimizes for incremental updates
+/>
+```
+
+## Use Cases
+
+### Code Editor
+
+```tsx
+function CodeEditor() {
+  const [code, setCode] = useState(`function hello() {
+  console.log("Hello!");
+}`)
+  
+  return (
+    <box flexDirection="column" height="100%">
+      <box height={1}>
+        <text>editor.ts</text>
+      </box>
+      <textarea
+        value={code}
+        onChange={setCode}
+        language="typescript"
+        showLineNumbers
+        flexGrow={1}
+        focused
+      />
+    </box>
+  )
+}
+```
+
+### Code Review
+
+```tsx
+function CodeReview({ oldCode, newCode }) {
+  return (
+    <box flexDirection="column" height="100%">
+      <box height={1} backgroundColor="#333">
+        <text>Changes in src/utils.ts</text>
+      </box>
+      <diff
+        oldCode={oldCode}
+        newCode={newCode}
+        language="typescript"
+        mode="split"
+        showLineNumbers
+      />
+    </box>
+  )
+}
+```
+
+### Syntax-Highlighted Preview
+
+```tsx
+function MarkdownPreview({ content }) {
+  // Extract code blocks from markdown
+  const codeBlocks = extractCodeBlocks(content)
+  
+  return (
+    <scrollbox height={20}>
+      {codeBlocks.map((block, i) => (
+        <box key={i} marginBottom={1}>
+          <code
+            code={block.code}
+            language={block.language}
+          />
+        </box>
+      ))}
+    </scrollbox>
+  )
+}
+```
+
+### Error Display
+
+```tsx
+function ErrorView({ errors, code }) {
+  const diagnostics = errors.map(err => ({
+    line: err.line,
+    severity: "error",
+    message: err.message,
+  }))
+  
+  return (
+    <line-number
+      code={code}
+      language="typescript"
+      diagnostics={diagnostics}
+      highlightedLines={errors.map(e => e.line)}
+    />
+  )
+}
+```
+
+## Gotchas
+
+### Solid Uses Underscores
+
+```tsx
+// React
+<line-number />
+
+// Solid
+<line_number />
+```
+
+### Language Required for Highlighting
+
+```tsx
+// No highlighting (plain text)
+<code code={text} />
+
+// With highlighting
+<code code={text} language="typescript" />
+```
+
+### Large Files
+
+For very large files, consider:
+- Pagination or virtual scrolling
+- Loading only visible portion
+- Using `scrollbox` wrapper
+
+```tsx
+<scrollbox height={30}>
+  <line-number
+    code={largeFile}
+    language="typescript"
+  />
+</scrollbox>
+```
+
+### Tree-sitter Loading
+
+Syntax highlighting requires Tree-sitter grammars. If highlighting isn't working:
+
+1. Check the language is supported
+2. Verify grammars are installed
+3. Check `OTUI_TREE_SITTER_WORKER_PATH` if using custom path