1ch 0.1.0

package/README.md

@@ -0,0 +1,280 @@
+# 1ch
+
+**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 `┼`.
+
+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.
+
+```tsx
+import { TermUI, TBox, TVStack, TTable, TBar } from "1ch";
+import "1ch/style.css";
+
+function Dashboard() {
+  return (
+    <TermUI width={60}>
+      <TBox title="Server Status">
+        <TVStack gap={1}>
+          <TBar label="CPU" value={73} max={100} />
+          <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 },
+            ]}
+            data={[
+              { service: "api-gateway", status: "UP", uptime: "14d 3h" },
+              { service: "worker-pool", status: "UP", uptime: "14d 3h" },
+              { service: "cache", status: "WARN", uptime: "2h 41m" },
+            ]}
+          />
+        </TVStack>
+      </TBox>
+    </TermUI>
+  );
+}
+```
+
+## Why
+
+- **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.
+
+## Installation
+
+```bash
+npm install 1ch react react-dom
+```
+
+## Components
+
+React components that render through a custom reconciler. No DOM elements - they produce `LayoutFn` internally.
+
+### Layout
+
+| 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                                   |
+
+### Data
+
+| 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 (`▁▂▃▄▅▆▇█`)                                     |
+
+### Interactive
+
+| Component    | What it does                       |
+| ------------ | ---------------------------------- |
+| `TTabs`      | Clickable tab bar with `onSelect`  |
+| `TButton`    | Clickable styled button            |
+| `TStatusbar` | Footer bar with left/right content |
+
+### Documents
+
+| 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 |
+
+## Imperative API
+
+If you don't want React components, every layout primitive has a function equivalent that returns a `LayoutFn`:
+
+```typescript
+import { box, vstack, table, code, bar, hstack } from "1ch";
+
+const layout = vstack(
+  box(
+    vstack(
+      bar(73, 100, 40),
+      table(
+        [
+          { key: "name", header: "Name", width: 20 },
+          { key: "value", header: "Value", width: 10 },
+        ],
+        [
+          { name: "requests", value: "1.2k/s" },
+          { name: "errors", value: "0.03%" },
+        ]
+      )
+    ),
+    { title: "Metrics" }
+  ),
+  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
+
+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.
+
+```tsx
+import {
+  TermThemeProvider,
+  TermUI,
+  parseThemeSpec,
+  defaultThemeSpec,
+} from "1ch";
+
+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);
+```
+
+## 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>
+
+        <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>
+  );
+}
+```
+
+## License
+
+MIT