@close-by/clay 0.2.7 → 0.2.8

package/README.md

@@ -18,4 +18,4 @@ export default function () {
 bunx clay hello.ts
 ```
 
-Docs: [Getting started](https://github.com/closeby-corp/clay/blob/main/docs/getting-started.md).
+Docs: shipped with the package at `node_modules/@close-by/clay/docs/`. See [getting-started.md](docs/getting-started.md) after install.

package/docs/README.md

@@ -0,0 +1,80 @@
+# Clay Documentation
+
+Server-driven UI for TypeScript, inspired by [NiceGUI](https://nicegui.io/).
+
+You write imperative `ui.*` code on the server. Clay owns a per-client element tree and syncs it to a thin React + ShadCN client over WebSocket.
+
+For coding agents: the repo-root [llms.txt](../llms.txt) is a short map of these guides.
+
+## Guides
+
+| Doc | Description |
+|-----|-------------|
+| [Getting started](./getting-started.md) | Install, `clay` CLI, create a page |
+| [Boot: CLI vs library](./boot.md) | Production `ui.run` path, `clientDir`, `_run.ts`, reload stubs |
+| [Tailwind](./tailwind.md) | Zero-config utilities from page modules; optional tokens |
+| [Sample app](./tutorial.md) | Step-by-step tasks list, then two pages + shell |
+| [Concepts](./concepts.md) | Mental model: sessions, elements, patches; **canonical `state`/`auto`/`timer` recipe**; reactive `let` alternative |
+| [Browser APIs](./browser-apis.md) | Prefer `ui.clipboard` / hash / `openExternal` — never `window` in page code |
+| [Production & security](./production.md) | Auth, server exposure, rate limits, boot parity |
+| [Ops patterns](./ops-patterns.md) | Dense consoles: chips, master–detail, feeds, sensitive logs, auth nav |
+| [API reference](./api.md) | `ui.*`, `Element` methods, `reactive`, helpers |
+| [Elements](./elements.md) | All element types and props |
+| [WebSocket protocol](./protocol.md) | Client ↔ server message formats |
+| [Architecture](./architecture.md) | Packages, data flow, and ownership |
+| [Examples](./examples.md) | Demo apps and patterns |
+| [Reactive `let`](./reactive-let.md) | NiceGUI-style `let` transform (opt-in `--reactive-let`) |
+| [AI UI](./ai.md) | `ui.ai.*` visual AI primitives (no model runtime) |
+| [DuckDB](./duckdb.md) | Multi-DB DuckDB wrapper (`@close-by/clay-duckdb`) |
+| [Kibana](./kibana.md) | Kibana REST + ES search (`@close-by/clay-kibana`) |
+| [ClickHouse](./clickhouse.md) | Multi-connection ClickHouse wrapper (`@close-by/clay-clickhouse`) |
+
+## Quick start
+
+```bash
+bun install
+bun run build:client   # monorepo: build + copy client into @close-by/clay-cli
+bun run clay hello.ts
+# → http://localhost:3000
+```
+
+Outside the monorepo: `bun run pack:publishable` then install the `dist-pack/*.tgz` set (see [Getting started](./getting-started.md)), or `bun add @close-by/clay-cli @close-by/clay` once published. Maintainers: `bun run publish:dry` / `publish:npm` (order core → … → cli). Shipped CLI includes prebuilt client assets — no separate `build:client` after install.
+
+```typescript
+// hello.ts
+import { ui } from '@close-by/clay';
+
+ui.run(() => {
+  let count = 0;
+  const label = ui.label(`Count: ${count}`);
+
+  ui.row(() => {
+    ui.button('-', {
+      onClick: () => {
+        count--;
+        label.setText(`Count: ${count}`);
+      },
+    });
+    ui.button('+', {
+      onClick: () => {
+        count++;
+        label.setText(`Count: ${count}`);
+      },
+    });
+  });
+});
+```
+
+Multi-page with shell:
+
+```bash
+bun run clay ./pages --app --title "My App"
+```
+
+Or library-style entry (`loadPages` + `ui.run({ app })`) — see [Getting started](./getting-started.md).
+
+## Naming
+
+Public Clay APIs and the wire protocol use **camelCase** (`onClick`, `bindValue`, `setText`, element `type: "button"`).
+
+React/ShadCN components inside `@close-by/clay-client` stay PascalCase because React requires it — that layer is an implementation detail.

package/docs/ai.md

@@ -0,0 +1,65 @@
+# AI UI (`ui.ai.*`)
+
+Visual, data-driven primitives for AI-native interfaces. Callers pass props (messages, tools, status, text) and handle events (`onSubmit`, `onApprove`, …). **No AI SDK / model runtime** lives inside clay.
+
+Inspired by [Beautiful UI](https://www.beautifului.dev/) patterns; reimplemented with clay factories + ShadCN/Tailwind on the client.
+
+## Quick start
+
+```ts
+import { ui } from '@close-by/clay';
+
+ui.ai.chat({
+  tabs: [{ id: 'flavors', label: 'Flavors' }],
+  activeTab: 'flavors',
+  messages: [
+    { id: '1', role: 'user', text: 'Compare mint chip…' },
+    {
+      id: '2',
+      role: 'assistant',
+      text: 'Mint chip is up 12%.',
+      thinking: [{ kind: 'reasoning', title: 'Comparison', durationMs: 2000 }],
+    },
+  ],
+  onSubmit: (text) => {
+    // App owns state; patch via chat.setMessages(...) or refreshable
+  },
+});
+
+ui.ai.promptBar({
+  placeholder: 'Ask…',
+  sources: [{ id: 'v1', label: 'Vanilla 1' }],
+  models: [{ id: 'gpt', label: 'GPT' }],
+  onSubmit: (value) => {},
+});
+```
+
+Demo gallery: `/examples/ai` (`AiDemo.ts`).
+
+**State note:** `ui.ai.chat` is intentionally imperative (`var messages` + `chat.setMessages`). Surrounding controls can use `ui.state`; do not wrap the whole chat in `ui.auto` (remounts the composer). See [Ops patterns — ai.chat](./ops-patterns.md#uiaichat-and-state).
+
+## Wire types
+
+| `ui.ai.*` | Wire `type` | Notes |
+|-----------|-------------|--------|
+| `loader` | `aiLoader` | Variants: `drive` / `dots` / `orbit` / `pixel`; optional `startedAt` elapsed |
+| `thinking` | `aiThinking` | Expandable step traces (`steps` / `reasoning` / `search` / `coding`) |
+| `message` | `aiMessage` | Role, markdown/text, sources, actions, follow-ups, `streaming?` |
+| `chat` | `aiChat` | Tabs + messages + composer; `AiChatElement` owns `setMessages` / `setActiveTab` |
+| `promptBar` | `aiPromptBar` | Textarea, @sources, /commands, model picker, dictate stub |
+| `codeBlock` | `aiCodeBlock` | Filename + optional streaming cue (Shiki) |
+| `approval` | `aiApproval` | HITL option cards |
+| `toolChips` | `aiToolChips` | Compact tool / edit chips |
+| `tasks` | `aiTasks` | Nested running / failed / completed rows |
+| `recommendation` | `aiRecommendation` | Confidence + alternatives |
+| `context` | `aiContext` | Retrieved chunks + sources |
+| `diffTable` | `aiDiffTable` | Compact proposed-edit table (not DataTable) |
+| `insights` | `aiInsights` | Paged insight cards |
+| `selectionActions` | `aiSelectionActions` | Selection text + action strip |
+| `fineTune` | `aiFineTune` | Inspector-style field editors → `onChange` |
+
+**Skipped overlaps:** use `ui.dataTable` for records/filter tables, `ui.app` for sidebar nav, `ui.command` for search.
+
+## Events (common)
+
+`submit`, `followUp`, `action`, `tabChange`, `sourceRemove`, `modelChange`, `command`, `dictate`, `approve`, `reject`, `chipClick`, `taskClick`, `accept`, `alternative`, `chunkClick`, `rowClick`, `indexChange`, `prompt`, `change`, `toggle`.