@fairyhunter13/opentui-core 0.1.91 → 0.1.94

package/docs/renderables-vs-constructs.md

@@ -1,159 +0,0 @@
-# Renderables vs Constructs
-
-Lets look at two ways of composing Renderables, imperative and declarative.
-Assume we want to create a simple "login" form with a username and password input.
-
-## Imperative
-
-Creates concrete `Renderable` instances with a `RenderContext` and composes via `add()`. State/behavior are mutated directly on instances (setters/methods), with mouse/key events bubbling upward through `processMouseEvent` for example.
-
-```typescript
-import { BoxRenderable, TextRenderable, InputRenderable, createCliRenderer, type RenderContext } from "@fairyhunter13/opentui-core"
-
-const renderer = await createCliRenderer()
-
-const loginForm = new BoxRenderable(renderer, {
-  id: "login-form",
-  width: 20,
-  height: 10,
-  padding: 1,
-})
-
-// Compose renderables to a single renderable.
-// Needs a RendererContext at creation time.
-function createLabeledInput(renderer: RenderContext, props: { label: string; placeholder: string; id: string }) {
-  const labeledInput = new BoxRenderable(renderer, {
-    id: `${props.id}-labeled-input`,
-    flexDirection: "row",
-    backgroundColor: "gray",
-  })
-
-  labeledInput.add(
-    new TextRenderable(renderer, {
-      id: `${props.id}-label`,
-      content: props.label + " ",
-    }),
-  )
-  labeledInput.add(
-    new InputRenderable(renderer, {
-      id: `${props.id}-input`,
-      placeholder: props.placeholder,
-      backgroundColor: "white",
-      textColor: "black",
-      cursorColor: "blue",
-      focusedBackgroundColor: "orange",
-      width: 20,
-    }),
-  )
-
-  return labeledInput
-}
-
-const labeledUsername = createLabeledInput(renderer, {
-  id: "username",
-  label: "Username:",
-  placeholder: "Enter your username...",
-})
-loginForm.add(labeledUsername)
-
-// Now it becomse difficult to focus. because it is in a container.
-// This does not work:
-labeledUsername.focus()
-
-// Needs to be:
-labeledUsername.getRenderable("username-input")?.focus()
-
-const labeledPassword = createLabeledInput(renderer, {
-  id: "password",
-  label: "Password:",
-  placeholder: "Enter your password...",
-})
-loginForm.add(labeledPassword)
-
-// Compose a button component
-function createButton(props: { content: string; onClick: () => void; id: string }) {
-  const box = new BoxRenderable(renderer, {
-    id: `${props.id}-button`,
-    border: true,
-    backgroundColor: "gray",
-    onMouseDown: props.onClick,
-  })
-  const text = new TextRenderable(renderer, {
-    id: `${props.id}-button-text`,
-    content: props.content,
-    selectable: false,
-  })
-  box.add(text)
-  return box
-}
-
-const buttons = new BoxRenderable(renderer, {
-  id: "buttons",
-  flexDirection: "row",
-  padding: 1,
-  width: 20,
-})
-buttons.add(createButton({ id: "register", content: "Register", onClick: () => {} }))
-buttons.add(createButton({ id: "login", content: "Login", onClick: () => {} }))
-loginForm.add(buttons)
-
-renderer.root.add(loginForm)
-```
-
-## Declarative
-
-Builds an allegedly lightweight VNode graph using functional constructs that return VNodes; no instances exist until `instantiate(ctx, vnode)` is called. During instantiation, children are flattened, renderables are created and added, and any chained method/property calls made on VNodes are replayed on the created instance. `delegate(mapping, vnode)` can annotate the VNode so selected APIs (e.g., `focus`, `add`) are later routed to a specific descendant when the instance is created.
-
-```typescript
-import { Text, Input, Box, createCliRenderer, delegate, instantiate } from "@fairyhunter13/opentui-core"
-
-const renderer = await createCliRenderer()
-
-function LabeledInput(props: { id: string; label: string; placeholder: string }) {
-  return delegate(
-    {
-      focus: `${props.id}-input`,
-    },
-    Box(
-      { flexDirection: "row" },
-      Text({ content: props.label + " " }),
-      Input({
-        id: `${props.id}-input`,
-        placeholder: props.placeholder,
-        width: 20,
-        backgroundColor: "white",
-        textColor: "black",
-        cursorColor: "blue",
-        focusedBackgroundColor: "orange",
-      }),
-    ),
-  )
-}
-
-function Button(props: { id: string; content: string; onClick: () => void }) {
-  return Box(
-    {
-      border: true,
-      backgroundColor: "gray",
-      onMouseDown: props.onClick,
-    },
-    Text({ content: props.content, selectable: false }),
-  )
-}
-
-const usernameInput = LabeledInput({ id: "username", label: "Username:", placeholder: "Enter your username..." })
-usernameInput.focus()
-
-const loginForm = Box(
-  { width: 20, height: 10, padding: 1 },
-  usernameInput,
-  LabeledInput({ id: "password", label: "Password:", placeholder: "Enter your password..." }),
-  Box(
-    { flexDirection: "row", padding: 1, width: 20 },
-    Button({ id: "login", content: "Login", onClick: () => {} }),
-    Button({ id: "register", content: "Register", onClick: () => {} }),
-  ),
-)
-
-renderer.root.add(loginForm)
-```

package/docs/tree-sitter.md

@@ -1,311 +0,0 @@
-# Tree-Sitter
-
-## Adding Custom Parsers
-
-There are two ways to add custom parsers to your application:
-
-### 1. Global Default Parsers (Recommended)
-
-Use `addDefaultParsers()` to add parsers globally before initializing any clients. This is useful when you want all Tree-Sitter clients in your application to support the same languages.
-
-```typescript
-import { addDefaultParsers, getTreeSitterClient } from "@fairyhunter13/opentui-core"
-
-// Add Python parser globally
-addDefaultParsers([
-  {
-    filetype: "python",
-    wasm: "https://github.com/tree-sitter/tree-sitter-python/releases/download/v0.23.6/tree-sitter-python.wasm",
-    queries: {
-      highlights: ["https://raw.githubusercontent.com/tree-sitter/tree-sitter-python/master/queries/highlights.scm"],
-    },
-  },
-])
-
-// Now all clients will have Python support
-const client = getTreeSitterClient()
-await client.initialize()
-
-// Highlight Python code
-const pythonCode = 'def hello():\n    print("world")'
-const result = await client.highlightOnce(pythonCode, "python")
-```
-
-### 2. Per-Client Parsers
-
-Use `client.addFiletypeParser()` to add parsers to a specific client instance. This is useful when different parts of your application need different language support.
-
-```typescript
-import { TreeSitterClient } from "@fairyhunter13/opentui-core"
-
-const client = new TreeSitterClient({ dataPath: "./cache" })
-await client.initialize()
-
-// Add Rust parser to this specific client
-client.addFiletypeParser({
-  filetype: "rust",
-  wasm: "https://github.com/tree-sitter/tree-sitter-rust/releases/download/v0.23.2/tree-sitter-rust.wasm",
-  queries: {
-    highlights: ["https://raw.githubusercontent.com/tree-sitter/tree-sitter-rust/master/queries/highlights.scm"],
-  },
-})
-
-// Highlight Rust code
-const rustCode = 'fn main() {\n    println!("Hello, world!");\n}'
-const result = await client.highlightOnce(rustCode, "rust")
-```
-
-## Parser Configuration Structure
-
-The `FiletypeParserOptions` interface defines how to configure a parser:
-
-```typescript
-interface FiletypeParserOptions {
-  filetype: string // The filetype identifier (e.g., "python", "rust")
-  wasm: string // URL or local file path to the .wasm parser file
-  queries: {
-    highlights: string[] // Array of URLs or local file paths to .scm query files
-  }
-}
-```
-
-## Finding Parsers and Queries
-
-### Official Tree-Sitter Parsers
-
-Most popular languages have official parsers:
-
-```typescript
-// Official parsers follow this pattern:
-const parserUrl =
-  "https://github.com/tree-sitter/tree-sitter-{language}/releases/download/v{version}/tree-sitter-{language}.wasm"
-
-// Examples:
-// Python: https://github.com/tree-sitter/tree-sitter-python/releases/download/v0.23.6/tree-sitter-python.wasm
-// Rust: https://github.com/tree-sitter/tree-sitter-rust/releases/download/v0.23.2/tree-sitter-rust.wasm
-// Go: https://github.com/tree-sitter/tree-sitter-go/releases/download/v0.23.4/tree-sitter-go.wasm
-```
-
-### Finding Highlight Queries
-
-Highlight queries are usually found in the parser repository's `queries/` directory:
-
-```typescript
-// Official queries:
-const queryUrl = "https://raw.githubusercontent.com/tree-sitter/tree-sitter-{language}/master/queries/highlights.scm"
-
-// Or from nvim-treesitter (often more comprehensive):
-const nvimQueryUrl =
-  "https://raw.githubusercontent.com/nvim-treesitter/nvim-treesitter/master/queries/{language}/highlights.scm"
-```
-
-### Combining Multiple Queries
-
-Some languages require multiple query files. For example, TypeScript uses JavaScript queries plus TypeScript-specific queries:
-
-```typescript
-addDefaultParsers([
-  {
-    filetype: "typescript",
-    wasm: "https://github.com/tree-sitter/tree-sitter-typescript/releases/download/v0.23.2/tree-sitter-typescript.wasm",
-    queries: {
-      highlights: [
-        // Base ECMAScript/JavaScript queries
-        "https://raw.githubusercontent.com/nvim-treesitter/nvim-treesitter/master/queries/ecma/highlights.scm",
-        // TypeScript-specific queries
-        "https://raw.githubusercontent.com/nvim-treesitter/nvim-treesitter/master/queries/typescript/highlights.scm",
-      ],
-    },
-  },
-])
-```
-
-## Using Local Files
-
-For better performance and offline support, you can bundle parsers and queries with your application:
-
-```typescript
-// Using Bun's file import
-import pythonWasm from "./parsers/tree-sitter-python.wasm" with { type: "file" }
-import pythonHighlights from "./queries/python/highlights.scm" with { type: "file" }
-
-addDefaultParsers([
-  {
-    filetype: "python",
-    wasm: pythonWasm,
-    queries: {
-      highlights: [pythonHighlights],
-    },
-  },
-])
-```
-
-## Automated Parser Management
-
-You can automate parser downloads and import generation using the `updateAssets` utility. This is especially useful when supporting multiple languages or integrating parser management into your build pipeline.
-
-### Creating a Parser Configuration
-
-Create a `parsers-config.json` file in your project:
-
-```json
-{
-  "parsers": [
-    {
-      "filetype": "python",
-      "wasm": "https://github.com/tree-sitter/tree-sitter-python/releases/download/v0.23.6/tree-sitter-python.wasm",
-      "queries": {
-        "highlights": ["https://raw.githubusercontent.com/tree-sitter/tree-sitter-python/master/queries/highlights.scm"]
-      }
-    },
-    {
-      "filetype": "rust",
-      "wasm": "https://github.com/tree-sitter/tree-sitter-rust/releases/download/v0.23.2/tree-sitter-rust.wasm",
-      "queries": {
-        "highlights": ["https://raw.githubusercontent.com/tree-sitter/tree-sitter-rust/master/queries/highlights.scm"]
-      }
-    }
-  ]
-}
-```
-
-### Integrating into Build Pipeline
-
-#### CLI Usage
-
-Add the update script to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "prebuild": "bun node_modules/@fairyhunter13/opentui-core/lib/tree-sitter/assets/update.ts --config ./parsers-config.json --assets ./src/parsers --output ./src/parsers.ts",
-    "build": "bun build ./src/index.ts"
-  }
-}
-```
-
-#### Programmatic Usage
-
-Or call it programmatically in your build script:
-
-```typescript
-import { updateAssets } from "@fairyhunter13/opentui-core"
-
-await updateAssets({
-  configPath: "./parsers-config.json",
-  assetsDir: "./src/parsers",
-  outputPath: "./src/parsers.ts",
-})
-```
-
-### Using Generated Parsers
-
-The script generates a TypeScript file with all parsers pre-configured:
-
-```typescript
-import { addDefaultParsers, getTreeSitterClient } from "@fairyhunter13/opentui-core"
-import { getParsers } from "./parsers" // Generated file
-
-addDefaultParsers(getParsers())
-
-const client = getTreeSitterClient()
-await client.initialize()
-
-const result = await client.highlightOnce('def hello():\n    print("world")', "python")
-```
-
-## Complete Example: Adding Multiple Languages
-
-```typescript
-import { addDefaultParsers, getTreeSitterClient, SyntaxStyle } from "@fairyhunter13/opentui-core"
-
-// Add support for multiple languages before initializing
-addDefaultParsers([
-  {
-    filetype: "python",
-    wasm: "https://github.com/tree-sitter/tree-sitter-python/releases/download/v0.23.6/tree-sitter-python.wasm",
-    queries: {
-      highlights: ["https://raw.githubusercontent.com/tree-sitter/tree-sitter-python/master/queries/highlights.scm"],
-    },
-  },
-  {
-    filetype: "rust",
-    wasm: "https://github.com/tree-sitter/tree-sitter-rust/releases/download/v0.23.2/tree-sitter-rust.wasm",
-    queries: {
-      highlights: ["https://raw.githubusercontent.com/tree-sitter/tree-sitter-rust/master/queries/highlights.scm"],
-    },
-  },
-  {
-    filetype: "go",
-    wasm: "https://github.com/tree-sitter/tree-sitter-go/releases/download/v0.23.4/tree-sitter-go.wasm",
-    queries: {
-      highlights: ["https://raw.githubusercontent.com/tree-sitter/tree-sitter-go/master/queries/highlights.scm"],
-    },
-  },
-])
-
-// Initialize the client
-const client = getTreeSitterClient()
-await client.initialize()
-
-// Use with different languages
-const syntaxStyle = new SyntaxStyle()
-
-const pythonResult = await client.highlightOnce('def hello():\n    print("world")', "python")
-
-const rustResult = await client.highlightOnce('fn main() {\n    println!("Hello");\n}', "rust")
-
-const goResult = await client.highlightOnce('func main() {\n    fmt.Println("Hello")\n}', "go")
-```
-
-## Using with CodeRenderable
-
-The `CodeRenderable` component automatically uses the Tree-Sitter client for syntax highlighting:
-
-```typescript
-import { CodeRenderable, getTreeSitterClient } from "@fairyhunter13/opentui-core"
-
-// Initialize the client with custom parsers
-const client = getTreeSitterClient()
-await client.initialize()
-
-// Create a code renderable
-const codeBlock = new CodeRenderable("code-1", {
-  content: 'def hello():\n    print("world")',
-  filetype: "python",
-  width: 40,
-  height: 10,
-})
-
-// The CodeRenderable will automatically use the Tree-Sitter client
-// to highlight the code
-```
-
-## Caching
-
-Parser and query files are automatically cached in the `dataPath` directory to avoid re-downloading them.
-You can customize the cache location when creating a client:
-
-```typescript
-const client = new TreeSitterClient({
-  dataPath: "./my-custom-cache",
-})
-```
-
-## File Type Resolution
-
-OpenTUI provides utilities to automatically determine filetypes from file paths:
-
-```typescript
-import { pathToFiletype, extToFiletype } from "@fairyhunter13/opentui-core"
-
-// Get filetype from file path
-const ft1 = pathToFiletype("src/main.rs") // "rust"
-const ft2 = pathToFiletype("app.py") // "python"
-
-// Get filetype from extension
-const ft3 = extToFiletype("ts") // "typescript"
-const ft4 = extToFiletype("js") // "javascript"
-```
-
-Built-in mappings include: `js`, `jsx`, `ts`, `tsx`, `py`, `rb`, `go`, `rs`, `c`, `cpp`, `html`, `css`, and more.