diff --git a/skill/opentui/SKILL.md b/skill/opentui/SKILL.md index c8542d7..49dc315 100644 --- a/skill/opentui/SKILL.md +++ b/skill/opentui/SKILL.md @@ -43,6 +43,8 @@ Cross-cutting concepts in `./references//` have `REFERENCE.md` as the e - Building components -> `api.md` + `components/.md` - Setting up project -> `configuration.md` - Layout/positioning -> `layout/REFERENCE.md` + - Keyboard/input handling -> `keyboard/REFERENCE.md` + - Animations -> `animation/REFERENCE.md` - Troubleshooting -> `gotchas.md` + `testing/REFERENCE.md` ### Example Paths @@ -85,7 +87,8 @@ Display content? ├─ ASCII art banner/title -> components/text-display.md (ascii-font) ├─ Code with syntax highlighting -> components/code-diff.md ├─ Diff viewer (unified/split) -> components/code-diff.md -└─ Line numbers with diagnostics -> components/code-diff.md +├─ Line numbers with diagnostics -> components/code-diff.md +└─ Markdown content (streaming) -> components/code-diff.md (markdown) ``` ### "I need user input" @@ -185,7 +188,7 @@ For component naming differences and text modifiers, see `components/REFERENCE.m | Text & Display | `./references/components/text-display.md` | text, ascii-font, styled text | | Containers | `./references/components/containers.md` | box, scrollbox, borders | | Inputs | `./references/components/inputs.md` | input, textarea, select, tab-select | -| Code & Diff | `./references/components/code-diff.md` | code, line-number, diff | +| Code & Diff | `./references/components/code-diff.md` | code, line-number, diff, markdown | ## Resources diff --git a/skill/opentui/references/animation/REFERENCE.md b/skill/opentui/references/animation/REFERENCE.md index 35bbd04..26dd954 100644 --- a/skill/opentui/references/animation/REFERENCE.md +++ b/skill/opentui/references/animation/REFERENCE.md @@ -422,3 +422,10 @@ useEffect(() => { return () => clearInterval(interval) }, []) ``` + +## See Also + +- [React API](../react/api.md) - `useTimeline` hook reference +- [Solid API](../solid/api.md) - `useTimeline` hook reference +- [Core API](../core/api.md) - `AnimationEngine` and `Timeline` classes +- [Layout Patterns](../layout/patterns.md) - Animated positioning and transitions diff --git a/skill/opentui/references/components/REFERENCE.md b/skill/opentui/references/components/REFERENCE.md index 971fa3b..0834960 100644 --- a/skill/opentui/references/components/REFERENCE.md +++ b/skill/opentui/references/components/REFERENCE.md @@ -13,7 +13,7 @@ Use this reference when you need to find the right component category or compare | 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 | [code-diff.md](./code-diff.md) | +| Code & Diff | code, line-number, diff, markdown | [code-diff.md](./code-diff.md) | ## Component Chooser @@ -22,7 +22,7 @@ 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 -> code-diff.md +└─ Code blocks, diffs, line numbers, markdown -> code-diff.md ``` ## Component Naming @@ -42,6 +42,7 @@ Components have different names across frameworks: | Code | `CodeRenderable` | `` | `` | | Line Number | `LineNumberRenderable` | `` | `` | | Diff | `DiffRenderable` | `` | `` | +| Markdown | `MarkdownRenderable` | `` | `` | **Note**: Solid uses underscores (`tab_select`) while React uses hyphens (`tab-select`). @@ -65,7 +66,9 @@ 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" diff --git a/skill/opentui/references/components/code-diff.md b/skill/opentui/references/components/code-diff.md index 105ccc8..41a2b34 100644 --- a/skill/opentui/references/components/code-diff.md +++ b/skill/opentui/references/components/code-diff.md @@ -54,6 +54,42 @@ OpenTUI uses Tree-sitter for syntax highlighting. Common languages: /> ``` +### 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 + { + // 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. @@ -239,6 +275,88 @@ const diffView = new DiffRenderable(renderer, { /> ``` +## Markdown Component + +Render markdown content with syntax highlighting for code blocks. + +### Basic Usage + +```tsx +// React + + +// Solid + + +// Core +import { MarkdownRenderable } from "@opentui/core" + +const md = new MarkdownRenderable(renderer, { + id: "markdown", + content: "# Hello\n\nThis is **markdown**.", + syntaxStyle: mySyntaxStyle, +}) +``` + +### Options + +```tsx + +``` + +### 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) + }) +}, []) + + +``` + ## Use Cases ### Code Editor diff --git a/skill/opentui/references/components/containers.md b/skill/opentui/references/components/containers.md index 5d38704..75ed5e7 100644 --- a/skill/opentui/references/components/containers.md +++ b/skill/opentui/references/components/containers.md @@ -105,8 +105,12 @@ Boxes are flex containers by default: paddingRight={2} paddingBottom={1} paddingLeft={2} + paddingX={2} // Horizontal (left + right) + paddingY={1} // Vertical (top + bottom) margin={1} marginTop={1} + marginX={2} // Horizontal (left + right) + marginY={1} // Vertical (top + bottom) > Spaced content @@ -141,6 +145,31 @@ Boxes are flex containers by default: ``` +### Focusable Boxes + +By default, Box elements are not focusable. Set the `focusable` prop to enable focus behavior: + +```tsx +// Make a box focusable - it can receive focus via mouse click + + Click to focus + + +// Controlled focus state +const [focused, setFocused] = useState(false) + + + {focused ? "Focused!" : "Not focused"} + +``` + +When a focusable Box is clicked, focus bubbles up from the click target to the nearest focusable parent. Use `event.preventDefault()` in `onMouseDown` to prevent auto-focus. + ## ScrollBox Component A scrollable container for content that exceeds the viewport. diff --git a/skill/opentui/references/keyboard/REFERENCE.md b/skill/opentui/references/keyboard/REFERENCE.md index e34d659..1cfb0eb 100644 --- a/skill/opentui/references/keyboard/REFERENCE.md +++ b/skill/opentui/references/keyboard/REFERENCE.md @@ -397,11 +397,57 @@ renderer.keyInput.on("paste", (text: string) => { }) ``` -### React/Solid +### Solid + +Solid provides a dedicated `usePaste` hook: ```tsx -// Currently handled through the global keyboard listener -// or via input component's onChange +import { usePaste } from "@opentui/solid" + +function App() { + usePaste((event) => { + console.log("Pasted:", event.text) + }) + + return Paste something +} +``` + +> **Note**: `usePaste` is **Solid-only**. React does not have this hook - handle paste via the Core event emitter or input component's `onChange`. + +## Clipboard API (OSC 52) + +Copy text to the system clipboard using OSC 52 escape sequences. Works over SSH and in most modern terminal emulators. + +### Core + +```typescript +// Copy to clipboard +const success = renderer.copyToClipboardOSC52("text to copy") + +// Check if OSC 52 is supported +if (renderer.isOsc52Supported()) { + renderer.copyToClipboardOSC52("Hello!") +} + +// Clear clipboard +renderer.clearClipboardOSC52() + +// Target specific clipboard (X11) +import { ClipboardTarget } from "@opentui/core" +renderer.copyToClipboardOSC52("text", ClipboardTarget.Primary) // X11 primary +renderer.copyToClipboardOSC52("text", ClipboardTarget.Clipboard) // System clipboard (default) +``` + +### From Selection + +The Selection object provides a convenience method: + +```tsx +// Solid +useSelectionHandler((selection) => { + selection.copyToClipboard() // Uses OSC 52 internally +}) ``` ## Focus and Input Components @@ -456,3 +502,10 @@ Key detection may vary over SSH. Test on target environments. ### Multiple Handlers Multiple `useKeyboard` calls all receive events. Coordinate handlers to prevent conflicts. + +## See Also + +- [React API](../react/api.md) - `useKeyboard` hook reference +- [Solid API](../solid/api.md) - `useKeyboard` hook reference +- [Input Components](../components/inputs.md) - Focus management with input, textarea, select +- [Testing](../testing/REFERENCE.md) - Simulating key presses in tests diff --git a/skill/opentui/references/layout/patterns.md b/skill/opentui/references/layout/patterns.md index 77e6b8f..bea5ad7 100644 --- a/skill/opentui/references/layout/patterns.md +++ b/skill/opentui/references/layout/patterns.md @@ -410,3 +410,35 @@ function Divider() { Section 2 ``` + +### Axis Shorthand Props + +Use `paddingX`/`paddingY` and `marginX`/`marginY` for horizontal/vertical spacing: + +```tsx +// Horizontal padding (left + right) + + 4 chars padding left and right + + +// Vertical padding (top + bottom) + + 2 lines padding top and bottom + + +// Horizontal margin for centering-like effect + + Indented content + + +// Combined for card-like spacing + + Nicely spaced card + +``` + +These are shorthand for: +- `paddingX={n}` = `paddingLeft={n}` + `paddingRight={n}` +- `paddingY={n}` = `paddingTop={n}` + `paddingBottom={n}` +- `marginX={n}` = `marginLeft={n}` + `marginRight={n}` +- `marginY={n}` = `marginTop={n}` + `marginBottom={n}` diff --git a/skill/opentui/references/react/api.md b/skill/opentui/references/react/api.md index 90d025f..66deca9 100644 --- a/skill/opentui/references/react/api.md +++ b/skill/opentui/references/react/api.md @@ -37,10 +37,33 @@ function App() { // 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 Hello } + +// 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 ( + + + Current theme: {theme} + + + ) +} ``` ### useKeyboard(handler, options?) @@ -233,13 +256,21 @@ function AnimatedBox() { // 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) => {}} diff --git a/skill/opentui/references/react/configuration.md b/skill/opentui/references/react/configuration.md index 20fea0d..7c3b4e9 100644 --- a/skill/opentui/references/react/configuration.md +++ b/skill/opentui/references/react/configuration.md @@ -146,6 +146,8 @@ const renderer = await createCliRenderer({ // 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: { diff --git a/skill/opentui/references/react/gotchas.md b/skill/opentui/references/react/gotchas.md index 0622916..f4241cb 100644 --- a/skill/opentui/references/react/gotchas.md +++ b/skill/opentui/references/react/gotchas.md @@ -24,6 +24,17 @@ function App() { `renderer.destroy()` restores the terminal (exits alternate screen, restores cursor, etc.) before exiting. +### Signal Handling + +OpenTUI automatically handles cleanup for these signals: +- `SIGINT` (Ctrl+C), `SIGTERM`, `SIGQUIT` - Standard termination +- `SIGHUP` - Terminal closed/hangup +- `SIGBREAK` - Ctrl+Break (Windows) +- `SIGPIPE` - Broken pipe (output closed) +- `SIGBUS`, `SIGFPE` - Hardware errors + +This ensures terminal state is restored even on unexpected termination. If you need custom signal handling, use `exitOnCtrlC: false` and handle signals yourself while still calling `renderer.destroy()`. + ## JSX Configuration ### Missing jsxImportSource diff --git a/skill/opentui/references/react/patterns.md b/skill/opentui/references/react/patterns.md index 10331ab..9636543 100644 --- a/skill/opentui/references/react/patterns.md +++ b/skill/opentui/references/react/patterns.md @@ -169,13 +169,16 @@ function AutoFocusInput() { ### Global Shortcuts ```tsx -import { useKeyboard } from "@opentui/react" +import { useKeyboard, useRenderer } from "@opentui/react" function App() { + const renderer = useRenderer() + useKeyboard((key) => { - // Quit on Escape or Ctrl+C + // Quit on Escape or Ctrl+C - use renderer.destroy(), never process.exit() if (key.name === "escape" || (key.ctrl && key.name === "c")) { - process.exit(0) + renderer.destroy() + return } // Toggle help on ? diff --git a/skill/opentui/references/solid/api.md b/skill/opentui/references/solid/api.md index e8384db..267069c 100644 --- a/skill/opentui/references/solid/api.md +++ b/skill/opentui/references/solid/api.md @@ -85,10 +85,31 @@ function App() { onMount(() => { console.log(`Terminal: ${renderer.width}x${renderer.height}`) renderer.console.show() + + // Access theme mode (dark/light based on terminal settings) + console.log(`Theme: ${renderer.themeMode}`) // "dark" | "light" | null }) return Hello } + +// Listen for theme mode changes +function ThemedApp() { + const renderer = useRenderer() + const [theme, setTheme] = createSignal(renderer.themeMode ?? "dark") + + onMount(() => { + renderer.on("theme_mode", (mode: "dark" | "light") => setTheme(mode)) + }) + + return ( + + + Current theme: {theme()} + + + ) +} ``` ### useKeyboard(handler, options?) @@ -189,20 +210,39 @@ function ResponsiveLayout() { ### useSelectionHandler(handler) -Handle text selection events. +Handle text selection events. Solid-only hook - React does not have this. ```tsx import { useSelectionHandler } from "@opentui/solid" +import type { Selection } from "@opentui/core" function SelectableText() { - useSelectionHandler((selection) => { - console.log("Selected:", selection.text) + const [selected, setSelected] = createSignal("") + + useSelectionHandler((selection: Selection) => { + const text = selection.getSelectedText() + if (text) { + setSelected(text) + // Copy to clipboard if needed + selection.copyToClipboard() + } }) - return Select this text + return ( + + Select this text with your mouse + Selected: {selected()} + + ) } ``` +**Selection properties/methods:** +- `getSelectedText(): string` - Get the selected text content +- `copyToClipboard(): void` - Copy selection to system clipboard (via OSC 52) +- `start: ConsolePosition` - Selection start position +- `end: ConsolePosition` - Selection end position + ### useTimeline(options?) Create animations with the timeline system. @@ -282,13 +322,21 @@ function AnimatedBox() { // Spacing padding={2} + 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) => {}} diff --git a/skill/opentui/references/solid/configuration.md b/skill/opentui/references/solid/configuration.md index 19d2793..3c3dd89 100644 --- a/skill/opentui/references/solid/configuration.md +++ b/skill/opentui/references/solid/configuration.md @@ -150,6 +150,8 @@ render(() => , { // Behavior exitOnCtrlC: true, + autoFocus: true, // Auto-focus elements on click (default: true) + useMouse: true, // Enable mouse support (default: true) // Debug console consoleOptions: { diff --git a/skill/opentui/references/testing/REFERENCE.md b/skill/opentui/references/testing/REFERENCE.md index 277feba..ab278ec 100644 --- a/skill/opentui/references/testing/REFERENCE.md +++ b/skill/opentui/references/testing/REFERENCE.md @@ -605,3 +605,10 @@ bun test # Not from repo root for package-specific tests ``` + +## See Also + +- [Core API](../core/api.md) - `createTestRenderer` and renderable classes +- [React Configuration](../react/configuration.md) - React test setup +- [Solid Configuration](../solid/configuration.md) - Solid test setup +- [Keyboard](../keyboard/REFERENCE.md) - Simulating key events in tests