@opentui/react 0.1.52 → 0.1.54

package/README.md

@@ -49,23 +49,68 @@ For optimal TypeScript support, configure your `tsconfig.json`:
 }
 ```
 
+## Table of Contents
+
+- [Core Concepts](#core-concepts)
+  - [Components](#components)
+  - [Styling](#styling)
+- [API Reference](#api-reference)
+  - [createRoot(renderer)](#createrootrenderer)
+  - [render(element, config?)](#renderelement-config-deprecated)
+  - [Hooks](#hooks)
+    - [useRenderer()](#userenderer)
+    - [useKeyboard(handler, options?)](#usekeyboardhandler-options)
+    - [useOnResize(callback)](#useonresizecallback)
+    - [useTerminalDimensions()](#useterminaldimensions)
+    - [useTimeline(options?)](#usetimelineoptions)
+- [Components](#components-1)
+  - [Layout & Display Components](#layout--display-components)
+    - [Text Component](#text-component)
+    - [Box Component](#box-component)
+    - [Scrollbox Component](#scrollbox-component)
+    - [ASCII Font Component](#ascii-font-component)
+  - [Input Components](#input-components)
+    - [Input Component](#input-component)
+    - [Textarea Component](#textarea-component)
+    - [Select Component](#select-component)
+  - [Code & Diff Components](#code--diff-components)
+    - [Code Component](#code-component)
+    - [Line Number Component](#line-number-component)
+    - [Diff Component](#diff-component)
+- [Examples](#examples)
+  - [Login Form](#login-form)
+  - [Counter with Timer](#counter-with-timer)
+  - [System Monitor Animation](#system-monitor-animation)
+  - [Styled Text Showcase](#styled-text-showcase)
+- [Component Extension](#component-extension)
+
 ## Core Concepts
 
 ### Components
 
 OpenTUI React provides several built-in components that map to OpenTUI core renderables:
 
+**Layout & Display:**
+
 - **`<text>`** - Display text with styling
 - **`<box>`** - Container with borders and layout
+- **`<scrollbox>`** - A scrollable box
+- **`<ascii-font>`** - Display ASCII art text with different font styles
+
+**Input Components:**
+
 - **`<input>`** - Text input field
 - **`<textarea>`** - Multi-line text input field
-- **`<code>`** - Code block with syntax highlighting
 - **`<select>`** - Selection dropdown
-- **`<scrollbox>`** - A scrollable box
 - **`<tab-select>`** - Tab-based selection
-- **`<ascii-font>`** - Display ASCII art text with different font styles
 
-Helpers:
+**Code & Diff Components:**
+
+- **`<code>`** - Code block with syntax highlighting
+- **`<line-number>`** - Code display with line numbers, diff highlights, and diagnostics
+- **`<diff>`** - Unified or split diff viewer with syntax highlighting
+
+**Helpers:**
 
 - **`<span>`, `<strong>`, `<em>`, `<u>`, `<b>`, `<i>`, `<br>`** - Text modifiers (_must be used inside of the text component_)
 
@@ -135,7 +180,7 @@ function App() {
 }
 ```
 
-#### `useKeyboard(handler)`
+#### `useKeyboard(handler, options?)`
 
 Handle keyboard events.
 
@@ -153,6 +198,46 @@ function App() {
 }
 ```
 
+**Parameters:**
+
+- `handler`: Callback function that receives a `KeyEvent` object
+- `options?`: Optional configuration object:
+  - `release?`: Boolean to include key release events (default: `false`)
+
+By default, only receives press events (including key repeats with `repeated: true`). Set `options.release` to `true` to also receive release events.
+
+**Example with release events:**
+
+```tsx
+import { useKeyboard } from "@opentui/react"
+import { useState } from "react"
+
+function App() {
+  const [pressedKeys, setPressedKeys] = useState<Set<string>>(new Set())
+
+  useKeyboard(
+    (event) => {
+      setPressedKeys((keys) => {
+        const newKeys = new Set(keys)
+        if (event.eventType === "release") {
+          newKeys.delete(event.name)
+        } else {
+          newKeys.add(event.name)
+        }
+        return newKeys
+      })
+    },
+    { release: true },
+  )
+
+  return (
+    <box>
+      <text>Currently pressed: {Array.from(pressedKeys).join(", ") || "none"}</text>
+    </box>
+  )
+}
+```
+
 #### `useOnResize(callback)`
 
 Handle terminal resize events.
@@ -255,7 +340,9 @@ function App() {
 
 ## Components
 
-### Text Component
+### Layout & Display Components
+
+#### Text Component
 
 Display text with rich formatting.
 
@@ -280,7 +367,7 @@ function App() {
 }
 ```
 
-### Box Component
+#### Box Component
 
 Container with borders and layout capabilities.
 
@@ -316,7 +403,109 @@ function App() {
 }
 ```
 
-### Input Component
+#### Scrollbox Component
+
+A scrollable box.
+
+```tsx
+function App() {
+  return (
+    <scrollbox
+      style={{
+        rootOptions: {
+          backgroundColor: "#24283b",
+        },
+        wrapperOptions: {
+          backgroundColor: "#1f2335",
+        },
+        viewportOptions: {
+          backgroundColor: "#1a1b26",
+        },
+        contentOptions: {
+          backgroundColor: "#16161e",
+        },
+        scrollbarOptions: {
+          showArrows: true,
+          trackOptions: {
+            foregroundColor: "#7aa2f7",
+            backgroundColor: "#414868",
+          },
+        },
+      }}
+      focused
+    >
+      {Array.from({ length: 1000 }).map((_, i) => (
+        <box
+          key={i}
+          style={{ width: "100%", padding: 1, marginBottom: 1, backgroundColor: i % 2 === 0 ? "#292e42" : "#2f3449" }}
+        >
+          <text content={`Box ${i}`} />
+        </box>
+      ))}
+    </scrollbox>
+  )
+}
+```
+
+#### ASCII Font Component
+
+Display ASCII art text with different font styles.
+
+```tsx
+import { useState } from "react"
+
+function App() {
+  const text = "ASCII"
+  const [font, setFont] = useState<"block" | "shade" | "slick" | "tiny">("tiny")
+
+  return (
+    <box style={{ border: true, paddingLeft: 1, paddingRight: 1 }}>
+      <box
+        style={{
+          height: 8,
+          border: true,
+          marginBottom: 1,
+        }}
+      >
+        <select
+          focused
+          onChange={(_, option) => setFont(option?.value)}
+          showScrollIndicator
+          options={[
+            {
+              name: "Tiny",
+              description: "Tiny font",
+              value: "tiny",
+            },
+            {
+              name: "Block",
+              description: "Block font",
+              value: "block",
+            },
+            {
+              name: "Slick",
+              description: "Slick font",
+              value: "slick",
+            },
+            {
+              name: "Shade",
+              description: "Shade font",
+              value: "shade",
+            },
+          ]}
+          style={{ flexGrow: 1 }}
+        />
+      </box>
+
+      <ascii-font text={text} font={font} />
+    </box>
+  )
+}
+```
+
+### Input Components
+
+#### Input Component
 
 Text input field with event handling.
 
@@ -339,7 +528,7 @@ function App() {
 }
 ```
 
-### Textarea Component
+#### Textarea Component
 
 ```tsx
 import type { TextareaRenderable } from "@opentui/core"
@@ -368,38 +557,7 @@ function App() {
 }
 ```
 
-### Code Component
-
-```tsx
-import { RGBA, SyntaxStyle } from "@opentui/core"
-
-const syntaxStyle = SyntaxStyle.fromStyles({
-  keyword: { fg: RGBA.fromHex("#ff6b6b"), bold: true }, // red, bold
-  string: { fg: RGBA.fromHex("#51cf66") }, // green
-  comment: { fg: RGBA.fromHex("#868e96"), italic: true }, // gray, italic
-  number: { fg: RGBA.fromHex("#ffd43b") }, // yellow
-  default: { fg: RGBA.fromHex("#ffffff") }, // white
-})
-
-const codeExample = `function hello() {
-  // This is a comment
-
-  const message = "Hello, world!"
-  const count = 42
-
-  return message + " " + count
-}`
-
-function App() {
-  return (
-    <box style={{ border: true, flexGrow: 1 }}>
-      <code content={codeExample} filetype="javascript" syntaxStyle={syntaxStyle} />
-    </box>
-  )
-}
-```
-
-### Select Component
+#### Select Component
 
 Dropdown selection component.
 
@@ -432,106 +590,101 @@ function App() {
 }
 ```
 
-### Scrollbox Component
+### Code & Diff Components
 
-A scrollable box.
+#### Code Component
 
 ```tsx
+import { RGBA, SyntaxStyle } from "@opentui/core"
+
+const syntaxStyle = SyntaxStyle.fromStyles({
+  keyword: { fg: RGBA.fromHex("#ff6b6b"), bold: true }, // red, bold
+  string: { fg: RGBA.fromHex("#51cf66") }, // green
+  comment: { fg: RGBA.fromHex("#868e96"), italic: true }, // gray, italic
+  number: { fg: RGBA.fromHex("#ffd43b") }, // yellow
+  default: { fg: RGBA.fromHex("#ffffff") }, // white
+})
+
+const codeExample = `function hello() {
+  // This is a comment
+
+  const message = "Hello, world!"
+  const count = 42
+
+  return message + " " + count
+}`
+
 function App() {
   return (
-    <scrollbox
-      style={{
-        rootOptions: {
-          backgroundColor: "#24283b",
-        },
-        wrapperOptions: {
-          backgroundColor: "#1f2335",
-        },
-        viewportOptions: {
-          backgroundColor: "#1a1b26",
-        },
-        contentOptions: {
-          backgroundColor: "#16161e",
-        },
-        scrollbarOptions: {
-          showArrows: true,
-          trackOptions: {
-            foregroundColor: "#7aa2f7",
-            backgroundColor: "#414868",
-          },
-        },
-      }}
-      focused
-    >
-      {Array.from({ length: 1000 }).map((_, i) => (
-        <box
-          key={i}
-          style={{ width: "100%", padding: 1, marginBottom: 1, backgroundColor: i % 2 === 0 ? "#292e42" : "#2f3449" }}
-        >
-          <text content={`Box ${i}`} />
-        </box>
-      ))}
-    </scrollbox>
+    <box style={{ border: true, flexGrow: 1 }}>
+      <code content={codeExample} filetype="javascript" syntaxStyle={syntaxStyle} />
+    </box>
   )
 }
 ```
 
-### ASCII Font Component
+#### Line Number Component
 
-Display ASCII art text with different font styles.
+Display code with line numbers, and optionally add diff highlights or diagnostic indicators.
 
 ```tsx
-import { useState } from "react"
+import type { LineNumberRenderable } from "@opentui/core"
+import { RGBA, SyntaxStyle } from "@opentui/core"
+import { useEffect, useRef } from "react"
 
 function App() {
-  const text = "ASCII"
-  const [font, setFont] = useState<"block" | "shade" | "slick" | "tiny">("tiny")
+  const lineNumberRef = useRef<LineNumberRenderable>(null)
+
+  const syntaxStyle = SyntaxStyle.fromStyles({
+    keyword: { fg: RGBA.fromHex("#C792EA") },
+    string: { fg: RGBA.fromHex("#C3E88D") },
+    number: { fg: RGBA.fromHex("#F78C6C") },
+    default: { fg: RGBA.fromHex("#A6ACCD") },
+  })
+
+  const codeContent = `function fibonacci(n: number): number {
+  if (n <= 1) return n
+  return fibonacci(n - 1) + fibonacci(n - 2)
+}
+
+console.log(fibonacci(10))`
+
+  useEffect(() => {
+    // Add diff highlight - line was added
+    lineNumberRef.current?.setLineColor(1, "#1a4d1a")
+    lineNumberRef.current?.setLineSign(1, { after: " +", afterColor: "#22c55e" })
+
+    // Add diagnostic indicator
+    lineNumberRef.current?.setLineSign(4, { before: "⚠️", beforeColor: "#f59e0b" })
+  }, [])
 
   return (
-    <box style={{ border: true, paddingLeft: 1, paddingRight: 1 }}>
-      <box
-        style={{
-          height: 8,
-          border: true,
-          marginBottom: 1,
-        }}
+    <box style={{ border: true, flexGrow: 1 }}>
+      <line-number
+        ref={lineNumberRef}
+        fg="#6b7280"
+        bg="#161b22"
+        minWidth={3}
+        paddingRight={1}
+        showLineNumbers={true}
+        width="100%"
+        height="100%"
       >
-        <select
-          focused
-          onChange={(_, option) => setFont(option?.value)}
-          showScrollIndicator
-          options={[
-            {
-              name: "Tiny",
-              description: "Tiny font",
-              value: "tiny",
-            },
-            {
-              name: "Block",
-              description: "Block font",
-              value: "block",
-            },
-            {
-              name: "Slick",
-              description: "Slick font",
-              value: "slick",
-            },
-            {
-              name: "Shade",
-              description: "Shade font",
-              value: "shade",
-            },
-          ]}
-          style={{ flexGrow: 1 }}
-        />
-      </box>
-
-      <ascii-font text={text} font={font} />
+        <code content={codeContent} filetype="typescript" syntaxStyle={syntaxStyle} width="100%" height="100%" />
+      </line-number>
     </box>
   )
 }
 ```
 
+For a more complete example with interactive diff highlights and diagnostics, see [`examples/line-number.tsx`](examples/line-number.tsx).
+
+#### Diff Component
+
+Display unified or split-view diffs with syntax highlighting, customizable themes, and line number support. Supports multiple view modes (unified/split), word wrapping, and theme customization.
+
+For a complete interactive example with theme switching and keybindings, see [`examples/diff.tsx`](examples/diff.tsx).
+
 ## Examples
 
 ### Login Form

package/index.js

@@ -4,7 +4,9 @@ import {
   ASCIIFontRenderable,
   BoxRenderable,
   CodeRenderable,
+  DiffRenderable,
   InputRenderable,
+  LineNumberRenderable,
   ScrollBoxRenderable,
   SelectRenderable,
   TabSelectRenderable,
@@ -71,12 +73,14 @@ var baseComponents = {
   box: BoxRenderable,
   text: TextRenderable,
   code: CodeRenderable,
+  diff: DiffRenderable,
   input: InputRenderable,
   select: SelectRenderable,
   textarea: TextareaRenderable,
   scrollbox: ScrollBoxRenderable,
   "ascii-font": ASCIIFontRenderable,
   "tab-select": TabSelectRenderable,
+  "line-number": LineNumberRenderable,
   span: SpanRenderable,
   br: LineBreakRenderable,
   b: BoldSpanRenderable,
@@ -118,15 +122,21 @@ function useEffectEvent(handler) {
 }
 
 // src/hooks/use-keyboard.ts
-var useKeyboard = (handler) => {
+var useKeyboard = (handler, options = { release: false }) => {
   const { keyHandler } = useAppContext();
   const stableHandler = useEffectEvent(handler);
   useEffect(() => {
     keyHandler?.on("keypress", stableHandler);
+    if (options?.release) {
+      keyHandler?.on("keyrelease", stableHandler);
+    }
     return () => {
       keyHandler?.off("keypress", stableHandler);
+      if (options?.release) {
+        keyHandler?.off("keyrelease", stableHandler);
+      }
     };
-  }, [keyHandler]);
+  }, [keyHandler, options.release]);
 };
 // src/hooks/use-renderer.ts
 var useRenderer = () => {

package/jsx-namespace.d.ts

@@ -3,9 +3,11 @@ import type {
   AsciiFontProps,
   BoxProps,
   CodeProps,
+  DiffProps,
   ExtendedIntrinsicElements,
   InputProps,
   LineBreakProps,
+  LineNumberProps,
   OpenTUIComponents,
   ScrollBoxProps,
   SelectProps,
@@ -37,12 +39,14 @@ export namespace JSX {
     text: TextProps
     span: SpanProps
     code: CodeProps
+    diff: DiffProps
     input: InputProps
     textarea: TextareaProps
     select: SelectProps
     scrollbox: ScrollBoxProps
     "ascii-font": AsciiFontProps
     "tab-select": TabSelectProps
+    "line-number": LineNumberProps
     // Text modifiers
     b: SpanProps
     i: SpanProps

package/package.json

@@ -4,7 +4,7 @@
   "main": "index.js",
   "types": "src/index.d.ts",
   "type": "module",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "description": "React renderer for building terminal user interfaces using OpenTUI core",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@opentui/core": "0.1.52",
+    "@opentui/core": "0.1.54",
     "react-reconciler": "^0.32.0"
   },
   "devDependencies": {

package/src/components/index.d.ts

@@ -1,16 +1,18 @@
-import { ASCIIFontRenderable, BoxRenderable, CodeRenderable, InputRenderable, ScrollBoxRenderable, SelectRenderable, TabSelectRenderable, TextareaRenderable, TextRenderable } from "@opentui/core";
+import { ASCIIFontRenderable, BoxRenderable, CodeRenderable, DiffRenderable, InputRenderable, LineNumberRenderable, ScrollBoxRenderable, SelectRenderable, TabSelectRenderable, TextareaRenderable, TextRenderable } from "@opentui/core";
 import type { RenderableConstructor } from "../types/components";
 import { BoldSpanRenderable, ItalicSpanRenderable, LineBreakRenderable, SpanRenderable, UnderlineSpanRenderable } from "./text";
 export declare const baseComponents: {
     box: typeof BoxRenderable;
     text: typeof TextRenderable;
     code: typeof CodeRenderable;
+    diff: typeof DiffRenderable;
     input: typeof InputRenderable;
     select: typeof SelectRenderable;
     textarea: typeof TextareaRenderable;
     scrollbox: typeof ScrollBoxRenderable;
     "ascii-font": typeof ASCIIFontRenderable;
     "tab-select": typeof TabSelectRenderable;
+    "line-number": typeof LineNumberRenderable;
     span: typeof SpanRenderable;
     br: typeof LineBreakRenderable;
     b: typeof BoldSpanRenderable;

package/src/hooks/use-keyboard.d.ts

@@ -1,2 +1,22 @@
 import type { KeyEvent } from "@opentui/core";
-export declare const useKeyboard: (handler: (key: KeyEvent) => void) => void;
+export interface UseKeyboardOptions {
+    /** Include release events - callback receives events with eventType: "release" */
+    release?: boolean;
+}
+/**
+ * Subscribe to keyboard events.
+ *
+ * By default, only receives press events (including key repeats with `repeated: true`).
+ * Use `options.release` to also receive release events.
+ *
+ * @example
+ * // Basic press handling (includes repeats)
+ * useKeyboard((e) => console.log(e.name, e.repeated ? "(repeat)" : ""))
+ *
+ * // With release events
+ * useKeyboard((e) => {
+ *   if (e.eventType === "release") keys.delete(e.name)
+ *   else keys.add(e.name)
+ * }, { release: true })
+ */
+export declare const useKeyboard: (handler: (key: KeyEvent) => void, options?: UseKeyboardOptions) => void;

package/src/reconciler/renderer.js

@@ -53,7 +53,9 @@ import {
   ASCIIFontRenderable,
   BoxRenderable,
   CodeRenderable,
+  DiffRenderable,
   InputRenderable,
+  LineNumberRenderable,
   ScrollBoxRenderable,
   SelectRenderable,
   TabSelectRenderable,
@@ -120,12 +122,14 @@ var baseComponents = {
   box: BoxRenderable,
   text: TextRenderable,
   code: CodeRenderable,
+  diff: DiffRenderable,
   input: InputRenderable,
   select: SelectRenderable,
   textarea: TextareaRenderable,
   scrollbox: ScrollBoxRenderable,
   "ascii-font": ASCIIFontRenderable,
   "tab-select": TabSelectRenderable,
+  "line-number": LineNumberRenderable,
   span: SpanRenderable,
   br: LineBreakRenderable,
   b: BoldSpanRenderable,

package/src/test-utils/test-utils.js

@@ -57,7 +57,9 @@ import {
   ASCIIFontRenderable,
   BoxRenderable,
   CodeRenderable,
+  DiffRenderable,
   InputRenderable,
+  LineNumberRenderable,
   ScrollBoxRenderable,
   SelectRenderable,
   TabSelectRenderable,
@@ -124,12 +126,14 @@ var baseComponents = {
   box: BoxRenderable,
   text: TextRenderable,
   code: CodeRenderable,
+  diff: DiffRenderable,
   input: InputRenderable,
   select: SelectRenderable,
   textarea: TextareaRenderable,
   scrollbox: ScrollBoxRenderable,
   "ascii-font": ASCIIFontRenderable,
   "tab-select": TabSelectRenderable,
+  "line-number": LineNumberRenderable,
   span: SpanRenderable,
   br: LineBreakRenderable,
   b: BoldSpanRenderable,

package/src/types/components.d.ts

@@ -1,4 +1,4 @@
-import type { ASCIIFontOptions, ASCIIFontRenderable, BaseRenderable, BoxOptions, BoxRenderable, CodeOptions, CodeRenderable, InputRenderable, InputRenderableOptions, RenderableOptions, RenderContext, ScrollBoxOptions, ScrollBoxRenderable, SelectOption, SelectRenderable, SelectRenderableOptions, TabSelectOption, TabSelectRenderable, TabSelectRenderableOptions, TextareaOptions, TextareaRenderable, TextNodeOptions, TextNodeRenderable, TextOptions, TextRenderable } from "@opentui/core";
+import type { ASCIIFontOptions, ASCIIFontRenderable, BaseRenderable, BoxOptions, BoxRenderable, CodeOptions, CodeRenderable, DiffRenderable, DiffRenderableOptions, InputRenderable, InputRenderableOptions, LineNumberOptions, LineNumberRenderable, RenderableOptions, RenderContext, ScrollBoxOptions, ScrollBoxRenderable, SelectOption, SelectRenderable, SelectRenderableOptions, TabSelectOption, TabSelectRenderable, TabSelectRenderableOptions, TextareaOptions, TextareaRenderable, TextNodeOptions, TextNodeRenderable, TextOptions, TextRenderable } from "@opentui/core";
 import type React from "react";
 /** Properties that should not be included in the style prop */
 export type NonStyledProps = "id" | "buffered" | "live" | "enableLayout" | "selectable" | "renderAfter" | "renderBefore" | `on${string}`;
@@ -43,6 +43,7 @@ export type TextareaProps = ComponentProps<TextareaOptions, TextareaRenderable>
     focused?: boolean;
 };
 export type CodeProps = ComponentProps<CodeOptions, CodeRenderable>;
+export type DiffProps = ComponentProps<DiffRenderableOptions, DiffRenderable>;
 export type SelectProps = ComponentProps<SelectRenderableOptions, SelectRenderable> & {
     focused?: boolean;
     onChange?: (index: number, option: SelectOption | null) => void;
@@ -57,6 +58,9 @@ export type TabSelectProps = ComponentProps<TabSelectRenderableOptions, TabSelec
     onChange?: (index: number, option: TabSelectOption | null) => void;
     onSelect?: (index: number, option: TabSelectOption | null) => void;
 };
+export type LineNumberProps = ComponentProps<ContainerProps<LineNumberOptions>, LineNumberRenderable> & {
+    focused?: boolean;
+};
 /** Convert renderable constructor to component props with proper style exclusions */
 export type ExtendedComponentProps<TConstructor extends RenderableConstructor, TOptions = ExtractRenderableOptions<TConstructor>> = TOptions & {
     children?: React.ReactNode;