create-theokit 1.0.11 → 1.0.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -12,6 +12,7 @@ This project includes TheoKit-aware skills that activate automatically when you
|
|
|
12
12
|
| theokit-agents | `**/*agent*`, `**/*tool*`, `**/*Agent*`, `**/*Tool*` | @Agent, @Tool, @Toolbox decorators, LLM integration |
|
|
13
13
|
| theokit-database | `**/*schema*`, `**/*db*`, `**/drizzle*`, `**/*migration*`, `**/*seed*` | Drizzle ORM, SQLite, schema patterns, migrations |
|
|
14
14
|
| theokit-frontend | `app/**` | File-based routing, layouts, theoFetch, useAgentStream |
|
|
15
|
+
| theokit-ui | `app/**`, `**/*Chat*`, `**/*Sidebar*`, `**/*Theme*` | @theokit/ui components: ChatThread, ChatMessage, CodeBlock, Sidebar, theming |
|
|
15
16
|
| theokit-config | `theo.config*`, `**/*config*` | defineConfig options, plugins, security, storage |
|
|
16
17
|
|
|
17
18
|
### Settings
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: theokit-ui
|
|
3
|
+
description: "@theokit/ui component library — chat UI (ChatThread, ChatMessage, ChatComposer, CodeBlock), theming, providers, sidebar"
|
|
4
|
+
user-invocable: false
|
|
5
|
+
paths:
|
|
6
|
+
- "app/**"
|
|
7
|
+
- "**/*Chat*"
|
|
8
|
+
- "**/*chat*"
|
|
9
|
+
- "**/*Sidebar*"
|
|
10
|
+
- "**/*sidebar*"
|
|
11
|
+
- "**/*theme*"
|
|
12
|
+
- "**/*Theme*"
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# @theokit/ui — AI Chat Component Library
|
|
16
|
+
|
|
17
|
+
`@theokit/ui` is an optional peer dependency. If installed, it provides ready-made components for chat UIs, theming, and layout. **Never build custom equivalents** of components `@theokit/ui` provides.
|
|
18
|
+
|
|
19
|
+
## Package Identity
|
|
20
|
+
|
|
21
|
+
The published package is `@theokit/ui` (NOT `@usetheo/ui` — that was the old name).
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
# Install from npm (preferred)
|
|
25
|
+
npm install @theokit/ui
|
|
26
|
+
|
|
27
|
+
# Or from local tarball (when using source repo)
|
|
28
|
+
cd ../theo-ui && npm pack # produces theokit-ui-X.Y.Z.tgz
|
|
29
|
+
cd ../my-app && npm install ../theo-ui/theokit-ui-X.Y.Z.tgz
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**WARNING: NEVER use `npm link ../theo-ui` or `file:../theo-ui`.** The symlink exposes the sibling's nested `node_modules/react` (typically a different version), causing dual-React: "React Element from an older version" errors, broken hooks (`useState` null), and silent render failures. `resolve.dedupe` in Vite does NOT fix this — the pnpm structure physically has two React copies. Use tarball (`npm pack` → `npm install .tgz`) instead.
|
|
33
|
+
|
|
34
|
+
## Provider Setup (required before using any component)
|
|
35
|
+
|
|
36
|
+
```typescript
|
|
37
|
+
// app/layout.tsx
|
|
38
|
+
import '@theokit/ui/styles.css'
|
|
39
|
+
import { TheoUIProvider, ThemeProvider } from '@theokit/ui'
|
|
40
|
+
|
|
41
|
+
export default function Layout({ children }) {
|
|
42
|
+
return (
|
|
43
|
+
<TheoUIProvider>
|
|
44
|
+
<ThemeProvider>
|
|
45
|
+
{children}
|
|
46
|
+
</ThemeProvider>
|
|
47
|
+
</TheoUIProvider>
|
|
48
|
+
)
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Chat Components
|
|
53
|
+
|
|
54
|
+
### Full Chat Page (typical assembly)
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
import {
|
|
58
|
+
PageShell,
|
|
59
|
+
Sidebar,
|
|
60
|
+
SessionListItem,
|
|
61
|
+
ChatThread,
|
|
62
|
+
ChatMessage,
|
|
63
|
+
ChatMessageContent,
|
|
64
|
+
ChatComposer,
|
|
65
|
+
} from '@theokit/ui'
|
|
66
|
+
import { useAgentStream } from 'theokit/client'
|
|
67
|
+
|
|
68
|
+
function ChatPage() {
|
|
69
|
+
const { status, events, send } = useAgentStream('/api/agents/assistant')
|
|
70
|
+
|
|
71
|
+
return (
|
|
72
|
+
<PageShell sidebar={
|
|
73
|
+
<Sidebar>
|
|
74
|
+
{sessions.map(s => (
|
|
75
|
+
<SessionListItem key={s.id} title={s.title} onClick={() => select(s)} />
|
|
76
|
+
))}
|
|
77
|
+
</Sidebar>
|
|
78
|
+
}>
|
|
79
|
+
<ChatThread>
|
|
80
|
+
{messages.map(m => (
|
|
81
|
+
<ChatMessage key={m.id} role={m.role}>
|
|
82
|
+
<ChatMessageContent markdown={m.content} />
|
|
83
|
+
</ChatMessage>
|
|
84
|
+
))}
|
|
85
|
+
</ChatThread>
|
|
86
|
+
|
|
87
|
+
<ChatComposer
|
|
88
|
+
disabled={status === 'streaming'}
|
|
89
|
+
onSubmit={text => send({ message: text })}
|
|
90
|
+
/>
|
|
91
|
+
</PageShell>
|
|
92
|
+
)
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Individual Components
|
|
97
|
+
|
|
98
|
+
| Component | Purpose | Key Props |
|
|
99
|
+
|-----------|---------|-----------|
|
|
100
|
+
| `ChatThread` | Scrollable message container | `children` (ChatMessage elements) |
|
|
101
|
+
| `ChatMessage` | Single message bubble | `role: 'user' \| 'assistant'`, `children` |
|
|
102
|
+
| `ChatMessageContent` | Markdown + code rendering | `markdown: string` (handles streaming partial) |
|
|
103
|
+
| `CodeBlock` | Syntax-highlighted code | `code: string`, `language?: string` (uses shiki, lazy-loaded) |
|
|
104
|
+
| `ChatComposer` | Message input + submit | `onSubmit: (text) => void`, `disabled?: boolean` |
|
|
105
|
+
| `PageShell` | App layout with sidebar slot | `sidebar?: ReactNode`, `children` |
|
|
106
|
+
| `Sidebar` | Collapsible side panel | `children` |
|
|
107
|
+
| `SessionListItem` | Session entry in sidebar | `title: string`, `onClick`, `active?: boolean` |
|
|
108
|
+
|
|
109
|
+
### Other Useful Components
|
|
110
|
+
|
|
111
|
+
| Component | Purpose |
|
|
112
|
+
|-----------|---------|
|
|
113
|
+
| `Button`, `Input`, `Textarea` | Form primitives (themed) |
|
|
114
|
+
| `ToolCallCard` | Display agent tool invocations |
|
|
115
|
+
| `AgentStream` | Lower-level stream renderer |
|
|
116
|
+
| `ThemeSwitcher` | Light/dark mode toggle |
|
|
117
|
+
| `Avatar` | User/agent avatar |
|
|
118
|
+
| `Alert` | Status messages |
|
|
119
|
+
|
|
120
|
+
## Peer Dependencies (install only what you use)
|
|
121
|
+
|
|
122
|
+
**Chat/markdown path** (most apps need these):
|
|
123
|
+
```bash
|
|
124
|
+
npm install mdast-util-from-markdown mdast-util-to-hast mdast-util-gfm \
|
|
125
|
+
hast-util-to-jsx-runtime hast-util-sanitize hast-util-from-html \
|
|
126
|
+
micromark-extension-gfm unist-util-visit unist-util-visit-parents shiki
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
**DO NOT install** unless you use the specific components:
|
|
130
|
+
- `mermaid` — only for diagram rendering components
|
|
131
|
+
- `katex` — only for math/LaTeX rendering
|
|
132
|
+
- `roughjs` / `perfect-freehand` — only for whiteboard/drawing components
|
|
133
|
+
|
|
134
|
+
## Theming
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
137
|
+
import { defineTheme, ThemeProvider } from '@theokit/ui'
|
|
138
|
+
|
|
139
|
+
// Built-in themes
|
|
140
|
+
import { dracula, oneDark, githubDark, anthropicStyle } from '@theokit/ui'
|
|
141
|
+
|
|
142
|
+
// Custom theme
|
|
143
|
+
const myTheme = defineTheme({
|
|
144
|
+
name: 'my-theme',
|
|
145
|
+
colors: { primary: '#3b82f6', background: '#0a0a0a' },
|
|
146
|
+
})
|
|
147
|
+
|
|
148
|
+
<ThemeProvider theme={myTheme}>
|
|
149
|
+
{children}
|
|
150
|
+
</ThemeProvider>
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Anti-patterns
|
|
154
|
+
|
|
155
|
+
- NEVER build a custom chat message component — use `ChatMessage` + `ChatMessageContent`
|
|
156
|
+
- NEVER build a custom markdown renderer — `ChatMessageContent` handles it (including streaming partial fences)
|
|
157
|
+
- NEVER build a custom code highlighter — `CodeBlock` uses shiki (lazy-loaded)
|
|
158
|
+
- NEVER import from `@usetheo/ui` — that's the deprecated package name; use `@theokit/ui`
|
|
159
|
+
- NEVER use `npm link` or `file:../theo-ui` to install — causes dual-React (use tarball or npm registry)
|
|
160
|
+
- NEVER install ALL peer deps — only install the peers for components you actually use
|
|
161
|
+
- NEVER use components without wrapping in `TheoUIProvider` + `ThemeProvider` first
|