1ch 0.1.0 → 0.3.0

package/README.md

@@ -2,9 +2,15 @@
 
 **Terminal UI components for React.** For those who'd rather be in the terminal.
 
-Every UI framework treats the browser as a canvas of infinite resolution. This one doesn't. The smallest unit is one character cell. A button is `[ OK ]`. A progress bar is `████░░░░`. A table border is `│` and `─` and `┼`.
+![1ch dashboard example](https://raw.githubusercontent.com/twoabove/1ch/main/demo/assets/demo.png)
 
-The web primitives that make it work are almost embarrassingly simple: a monospace font, `white-space: pre`, and `ch` units. That's the entire rendering engine.
+The smallest unit is one character cell. A button is `[ OK ]`. A progress bar is `████░░░░`. A table border is `│` and `─` and `┼`. The whole thing is a grid.
+
+```bash
+npm install 1ch react react-dom
+```
+
+## What it looks like
 
 ```tsx
 import { TermUI, TBox, TVStack, TTable, TBar } from "1ch";
@@ -19,9 +25,9 @@ function Dashboard() {
           <TBar label="MEM" value={4.2} max={8} />
           <TTable
             columns={[
-              { key: "service", header: "Service", width: 20 },
-              { key: "status", header: "Status", width: 10 },
-              { key: "uptime", header: "Uptime", width: 12 },
+              { key: "service", width: 20 },
+              { key: "status", width: 10 },
+              { key: "uptime", width: 12 },
             ]}
             data={[
               { service: "api-gateway", status: "UP", uptime: "14d 3h" },
@@ -36,70 +42,93 @@ function Dashboard() {
 }
 ```
 
-## Why
+<!-- TODO: Add screenshot of the above rendering -->
 
-- **Dense.** Every character is content or structure. Nothing is decorative. You can always tell where one element ends and another begins because the grid enforces it.
-- **React-native.** Not a wrapper around a terminal emulator. Custom React reconciler that turns a component tree into character grids. React handles lifecycle, hooks, state. The reconciler handles layout.
-- **Responsive.** All layout is lazy - functions of width, not pre-computed blocks. Resize the container and everything reflows.
-- **Themeable.** Full token system: palette, semantic, syntax, markdown, component colors. Light/dark/system. Runtime-switchable. End-user JSON theming with validation.
-- **Three input formats.** Render React components, or feed it markdown, HTML, or JSON and get terminal layouts back.
+## Why this exists
 
-## Installation
+Most UI components are styled `<div>`s pretending to be something else. Terminal UIs skip the pretense - every character is either content or structure, and the grid makes boundaries obvious.
 
-```bash
-npm install 1ch react react-dom
-```
+Under the hood, 1ch uses a custom React reconciler that turns your component tree into character grids. React handles lifecycle, hooks, state. The reconciler handles layout. Resize the container and everything reflows.
 
 ## Components
 
-React components that render through a custom reconciler. No DOM elements - they produce `LayoutFn` internally.
+**Layout** - `TVStack`, `THStack`, `TBox`, `TSeparator`, `TBlank`, `TLine`, `TSpan`
 
-### Layout
+**Data** - `TTable`, `TTree`, `TList`, `TCode`, `TUnifiedDiff`, `TDiffCompute`, `TBar`, `TSpark`
 
-| Component    | What it does                                         |
-| ------------ | ---------------------------------------------------- |
-| `TVStack`    | Vertical stack with optional `gap`                   |
-| `THStack`    | Horizontal stack with optional `gap` and `widths`    |
-| `TBox`       | Bordered box with optional `title` and `borderColor` |
-| `TSeparator` | Horizontal line                                      |
-| `TBlank`     | Empty line                                           |
-| `TLine`      | Single-line container                                |
-| `TSpan`      | Inline styled text                                   |
+**Interactive** - `TTabs`, `TButton`, `TStatusbar`
 
-### Data
+**Documents** - `TMarkdown`, `THtml`, `TJson`
 
-| Component | What it does                                               |
-| --------- | ---------------------------------------------------------- |
-| `TTable`  | Bordered table with column widths, wrapping, header colors |
-| `TTree`   | Nested tree view with `├─` and `└─` branch characters      |
-| `TList`   | Bulleted or numbered list                                  |
-| `TCode`   | Syntax-highlighted code block in a box                     |
-| `TDiff`   | Colored diff output                                        |
-| `TBar`    | Progress bar (`████░░░░`)                                  |
-| `TSpark`  | Sparkline (`▁▂▃▄▅▆▇█`)                                     |
+The document components accept raw strings. Feed `TMarkdown` a markdown string, `THtml` an HTML string, or `TJson` a JSON object, and you get terminal-styled output back.
 
-### Interactive
+## A more complete example
 
-| Component    | What it does                       |
-| ------------ | ---------------------------------- |
-| `TTabs`      | Clickable tab bar with `onSelect`  |
-| `TButton`    | Clickable styled button            |
-| `TStatusbar` | Footer bar with left/right content |
+```tsx
+import { TermUI, TBox, TCode, TTabs, TTab, TTable, TBar, TVStack } from "1ch";
+import "1ch/style.css";
 
-### Documents
+function App() {
+  const [tab, setTab] = useState(0);
 
-| Component   | What it does                               |
-| ----------- | ------------------------------------------ |
-| `TMarkdown` | Renders markdown string as terminal layout |
-| `THtml`     | Renders HTML string as terminal layout     |
-| `TJson`     | Renders structured JSON as terminal layout |
+  return (
+    <TermUI width={80}>
+      <TTabs active={tab} onSelect={setTab}>
+        <TTab name="Overview">
+          <TBox title="Status">
+            <TVStack>
+              <TBar label="CPU" value={73} max={100} />
+              <TBar label="MEM" value={4.2} max={8} />
+            </TVStack>
+          </TBox>
+        </TTab>
 
-## Imperative API
+        <TTab name="Logs">
+          <TTable
+            columns={[
+              { key: "time", width: 12 },
+              { key: "level", width: 8 },
+              { key: "message", width: 40 },
+            ]}
+            data={[
+              {
+                time: "14:03:21",
+                level: "INFO",
+                message: "Server started on :3000",
+              },
+              {
+                time: "14:03:22",
+                level: "INFO",
+                message: "Connected to database",
+              },
+              { time: "14:05:01", level: "WARN", message: "Slow query: 2.3s" },
+            ]}
+          />
+        </TTab>
 
-If you don't want React components, every layout primitive has a function equivalent that returns a `LayoutFn`:
+        <TTab name="Config">
+          <TCode
+            code={`export default {
+  port: 3000,
+  database: "postgres://localhost/app",
+  cache: { ttl: 300, max: 1000 },
+};`}
+            language="typescript"
+            title="config.ts"
+          />
+        </TTab>
+      </TTabs>
+    </TermUI>
+  );
+}
+```
+
+## Don't want React? Skip it.
+
+Every component has an imperative equivalent that returns a layout function. Call it with a width and get a character grid back.
 
 ```typescript
-import { box, vstack, table, code, bar, hstack } from "1ch";
+import { box, vstack, table, code, bar } from "1ch";
 
 const layout = vstack(
   box(
@@ -121,57 +150,12 @@ const layout = vstack(
   code(`console.log("hello")`, { language: "javascript" })
 );
 
-// Materialize at any width
-const block: Block = layout(80);
-```
-
-### Available builders
-
-**Layout:** `box`, `hstack`, `vstack`, `separator`, `blank`, `lines`
-
-**Data:** `table`, `tree`, `list`, `code`, `diff`
-
-**Widgets:** `tabs`, `statusbar`, `badge`, `bar`, `spark`
-
-**Text:** `pad`, `hl`, `padLine`
-
-## Document Pipeline
-
-Feed it markdown, HTML, or JSON. Get terminal layouts back.
-
-```tsx
-import { TermDocument } from "1ch";
-
-// Markdown
-<TermDocument
-  source={{ format: "markdown", value: "# Hello\n\nSome **bold** text." }}
-  width={60}
-/>
-
-// HTML
-<TermDocument
-  source={{ format: "html", value: "<h1>Hello</h1><p>Some text.</p>" }}
-  width={60}
-/>
-
-// Or use the functions directly
-import { fromMarkdown, fromHtml, fromJson } from "1ch";
-
-const layout = fromMarkdown("# Hello\n\n- one\n- two", { theme });
 const block = layout(80);
 ```
 
-### HTML support
+## Theming
 
-Supported tags: `h1`-`h6`, `p`, `ul`, `ol`, `li`, `table` (with `thead`/`tbody`/`tr`/`th`/`td`), `blockquote`, `hr`, `pre`, `div`, `section`, `article`, `main`, `header`, `footer`, `nav`.
-
-`<term>` acts as an optional root - if present, only its subtree renders.
-
-Color attributes: `color`, `data-color`, `marker-color`, `header-color`, `border-color`, `text-color`. Values can be theme keys (`yellow`, `cyan`) or CSS colors (`#56b6c2`).
-
-## Theme System
-
-Two built-in themes (dark and light), runtime-switchable, fully customizable via JSON.
+Dark and light themes built in, and are switchable at runtime. You can override everything via JSON - palette, semantic colors, syntax highlighting, markdown rendering, component tokens. Use `parseThemeSpec()` to check the JSON before applying it.
 
 ```tsx
 import {
@@ -184,96 +168,14 @@ import {
 const parsed = parseThemeSpec(userThemeJson);
 const spec = parsed.ok ? parsed.theme : defaultThemeSpec;
 
-function App() {
-  return (
-    <TermThemeProvider initialTheme={spec} initialMode="system">
-      <TermUI width={80}>{/* components inherit the theme */}</TermUI>
-    </TermThemeProvider>
-  );
-}
-```
-
-A `ThemeSpec` defines both light and dark modes. Each mode has:
-
-- **Palette** - 10 ANSI-like colors (black, red, green, yellow, blue, magenta, cyan, white, brightBlack, brightWhite)
-- **Semantic** - UI intent (border, info, success, warn, danger, frameBg, frameFg, etc.)
-- **Syntax** - Code highlighting (keyword, string, number, comment, function, type, punctuation)
-- **Markdown** - Document rendering (headings h1-h6, paragraph, lists, tables, quotes, code)
-- **Components** - Widget colors (tabs, statusbar, badge, button)
-
-Use `validateThemeSpec()` to check user-provided JSON before applying it.
-
-## Hooks
-
-```typescript
-import { useSpinner, useTick, useTermWidth, useStreamingText } from "1ch";
-
-// Animated braille spinner
-const spinner = useSpinner(80);
-
-// Interval counter for animations
-const tick = useTick(500);
-
-// Measure container width in character units (uses ResizeObserver)
-const ref = useRef(null);
-const width = useTermWidth(ref, 80);
-
-// Streaming text with lerp (detects appends, doesn't restart)
-const displayed = useStreamingText(streamingText, 0.08);
+<TermThemeProvider initialTheme={spec} initialMode="system">
+  <TermUI width={80}>{/* components inherit the theme */}</TermUI>
+</TermThemeProvider>;
 ```
 
-## Putting It Together
-
-```tsx
-import { TermUI, TBox, TCode, TTabs, TTab, TTable, TBar, TVStack } from "1ch";
-import "1ch/style.css";
-
-function App() {
-  const [tab, setTab] = useState(0);
-
-  return (
-    <TermUI width={80}>
-      <TTabs active={tab} onSelect={setTab}>
-        <TTab name="Overview">
-          <TBox title="Status">
-            <TVStack>
-              <TBar label="CPU" value={73} max={100} />
-              <TBar label="MEM" value={4.2} max={8} />
-            </TVStack>
-          </TBox>
-        </TTab>
-
-        <TTab name="Logs">
-          <TTable
-            columns={[
-              { key: "time", header: "Time", width: 12 },
-              { key: "level", header: "Level", width: 8 },
-              { key: "message", header: "Message", width: 40 },
-            ]}
-            data={[
-              { time: "14:03:21", level: "INFO", message: "Server started on :3000" },
-              { time: "14:03:22", level: "INFO", message: "Connected to database" },
-              { time: "14:05:01", level: "WARN", message: "Slow query: 2.3s" },
-            ]}
-          />
-        </TTab>
+## Docs
 
-        <TTab name="Config">
-          <TCode
-            code={`export default {
-  port: 3000,
-  database: "postgres://localhost/app",
-  cache: { ttl: 300, max: 1000 },
-};`}
-            language="typescript"
-            title="config.ts"
-          />
-        </TTab>
-      </TTabs>
-    </TermUI>
-  );
-}
-```
+Full API reference, theme spec details, hooks (`useSpinner`, `useTick`, `useTermWidth`, `useStreamingText`), and the document pipeline - all in the [docs](1ch.app) (coming soon).
 
 ## License