nexi-agent 0.1.1 → 0.2.0

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/README.md CHANGED
@@ -1,602 +1,779 @@
1
- # nexi-agent
2
-
3
- **React components for building AI-agent interfaces:** chat threads, streaming
4
- answers, reasoning traces, tool calls, approvals, task progress, data tables and
5
- more. You install them, import them, and pass in your own data.
6
-
7
- **[Browse every component live →](https://nexi-agent-component-package.vercel.app)** (previews, copyable code and props)
8
-
9
- ```tsx
10
- <ThinkingState done="Thought for 3 seconds" rows={[{ primary: "Reading the ticket" }]} />
11
- <StreamingText content="The deploy failed because the API key expired." />
12
- <ApprovalCard questions={[{ q: "Rotate the key now?", type: "radio", options: ["Yes", "Later"] }]} />
13
- ```
14
-
15
- - **43 components:** all 33 from [Beautiful UI](https://www.beautifului.dev), plus 10
16
- more (chat thread, markdown, dialog, toast, avatar…).
17
- - **No hardcoded content.** Every word and every row comes from your props.
18
- - **Fully themeable** through CSS variables, with dark mode built in.
19
- - **Works in any React 18/19 app** (Vite, Next.js App Router, Remix, CRA). Tailwind
20
- is optional.
21
- - **TypeScript-first.** Every component, prop and data type is exported.
22
-
23
- ---
24
-
25
- ## Table of contents
26
-
27
- 1. [Quick start](#1-quick-start)
28
- 2. [Setup](#2-setup)
29
- 3. [What's inside](#3-whats-inside)
30
- 4. [How to use the components](#4-how-to-use-the-components)
31
- 5. [Recipes](#5-recipes)
32
- 6. [Customising](#6-customising)
33
- 7. [Working on this repo](#7-working-on-this-repo)
34
- 8. [Docker](#8-docker)
35
- 9. [Releasing](#9-releasing)
36
- 10. [Troubleshooting](#10-troubleshooting)
37
- 11. [Credits and license](#11-credits-and-license)
38
-
39
- ---
40
-
41
- ## 1. Quick start
42
-
43
- ```bash
44
- npm install nexi-agent
45
- ```
46
-
47
- ```tsx
48
- // main.tsx (or your root layout)
49
- import "nexi-agent/styles.css";
50
- import { NexiProvider } from "nexi-agent";
51
-
52
- root.render(
53
- <NexiProvider>
54
- <App />
55
- </NexiProvider>,
56
- );
57
- ```
58
-
59
- ```tsx
60
- // anywhere inside
61
- import { StreamingText } from "nexi-agent";
62
-
63
- <StreamingText content="Hello! I'm your agent." />;
64
- ```
65
-
66
- That's all. To see every component with sample data first, open the
67
- [docs site](https://nexi-agent-component-package.vercel.app).
68
-
69
- ---
70
-
71
- ## 2. Setup
72
-
73
- ### Requirements
74
-
75
- - React **18 or 19** (`react` and `react-dom` are peer dependencies)
76
- - Node **20+** to build this repo (22 LTS recommended)
77
-
78
- ### Install
79
-
80
- | From | Command | When |
81
- | --- | --- | --- |
82
- | **npm** | `npm install nexi-agent` | the normal way |
83
- | **Git** | `npm install github:abiramavarshini-kl/nexi-agent-component-package` (add `#main` or `#v0.1.0` to pin) | an unreleased commit or branch. npm builds the package on install. |
84
- | **A local file** | in this repo: `npm run build && npm pack`, then in your app: `npm install ../path/nexi-agent-0.1.0.tgz` | testing unreleased changes in another app |
85
-
86
- ### Styles: pick one
87
-
88
- | Your app | Add this | Result |
89
- | --- | --- | --- |
90
- | **No Tailwind** (or Tailwind v3) | `import "nexi-agent/styles.css";` once, at the root | precompiled CSS with everything the components need |
91
- | **Tailwind v4** | in your main CSS, after `@import "tailwindcss";`: `@import "nexi-agent/tailwind.css";` | one combined build; you can also use our tokens (`bg-surface`, `text-ink-2`, `shadow-card`…) in your own markup |
92
-
93
- ### The provider
94
-
95
- Wrap your UI in `<NexiProvider>` once. It applies the font, text size and colour
96
- scope (the `.nexi` class) without touching the rest of your page.
97
-
98
- ```tsx
99
- <NexiProvider>…</NexiProvider> // light
100
- <NexiProvider dark>…</NexiProvider> // dark, for this subtree
101
- <NexiProvider contents>…</NexiProvider> // no wrapper box (display: contents)
102
- ```
103
-
104
- ### Fonts (optional)
105
-
106
- The design uses **Inter** and **JetBrains Mono**. Load them in your app (Google
107
- Fonts or `next/font`); otherwise the system fonts are used.
108
-
109
- ```html
110
- <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
111
- ```
112
-
113
- ### Next.js
114
-
115
- It works out of the box: the bundle is marked `"use client"`, so you can import
116
- components straight into App Router pages. Put the CSS import in `app/layout.tsx`.
117
-
118
- ---
119
-
120
- ## 3. What's inside
121
-
122
- ### Conversation
123
-
124
- | Component | What it shows |
125
- | --- | --- |
126
- | `MessageThread` / `Message` | the scrolling chat: user bubbles, agent turns that can hold any component, auto-scroll |
127
- | `StreamingText` | an answer revealed word by word, with inline citations, sources, action buttons and follow-ups |
128
- | `Markdown` | a formatted markdown answer (headings, lists, tables, code); safe, and works while text streams in |
129
- | `ChatComposer` | a compact chat panel with tabs, replies and an input |
130
- | `PromptBar` | a full input: `@` sources, `/` commands, model picker, attachments, dictation |
131
- | `SelectionActions` | highlight text → ask the agent to rewrite it → keep or discard |
132
-
133
- ### Agent activity
134
-
135
- | Component | What it shows |
136
- | --- | --- |
137
- | `ThinkingState` | an expandable reasoning trace (Steps · Reasoning · Search · Coding) |
138
- | `ToolChips` | tool calls as compact rows, plus file-diff chips |
139
- | `TaskRows` | tasks with running / failed / completed status |
140
- | `LoadingState` | a pixel loader with shimmering label and live timer |
141
- | `AgentScreen` | a live view of the agent's screen (image or video stream) |
142
- | `ContextCards` | retrieved document chunks (RAG) and their sources |
143
-
144
- ### Decisions
145
-
146
- | Component | What it shows |
147
- | --- | --- |
148
- | `ApprovalCard` | questions the user answers before the agent acts (human in the loop) |
149
- | `RecommendationCard` | a suggested action with a confidence meter and alternatives |
150
- | `DiffTable` | proposed row additions and removals the user can accept one by one |
151
- | `Dialog` | a confirm or small-form modal |
152
-
153
- ### Data
154
-
155
- | Component | What it shows |
156
- | --- | --- |
157
- | `RecordsTable` | a spreadsheet-style grid: tags, sorting, resizing, AI-calculated columns |
158
- | `FilterTable` | a table filtered by status chips |
159
- | `InsightCards` | a carousel of insights with live charts (`InsightCompareCard`, `InsightAnomalyCard`, `InsightAllocationCard` also work alone) |
160
- | `CodeBlock` | a code listing or unified diff, with copy |
161
- | `Flowchart` | a workflow canvas with draggable step and condition cards |
162
- | `UsageMeter` | tokens or credits used against a limit |
163
-
164
- ### App shell and feedback
165
-
166
- | Component | What it shows |
167
- | --- | --- |
168
- | `SidebarNav` | collapsible workspace switcher, navigation and chat history |
169
- | `SearchList` | a command search with live filtering |
170
- | `EmptyState` | "nothing here yet" or error panels |
171
- | `ToastProvider` / `useToast` | short notifications |
172
- | `FineTuneCard` | an inspector with draggable number fields |
173
- | `GlideMenu` | a menu with a gliding hover highlight |
174
-
175
- ### Atoms (small building blocks)
176
-
177
- `Avatar` · `Badge` · `Button` · `Chip` · `EntityChip` · `Monogram` ·
178
- `ProgressRing` · `SegmentedControl` · `Shimmer` · `StatusPill` · `StreamText` ·
179
- `Switch` · `TextRow` · `Tooltip` · `ValuePill` · `NexiProvider`
180
-
181
- ```tsx
182
- <Badge tone="green" dot>Completed</Badge>
183
- <Button variant="accent" size="sm">Run</Button>
184
- <StatusPill tone="orange">Running</StatusPill>
185
- <Avatar name="Maya Chen" src={photo} status="online" />
186
- <Tooltip content="Copy answer"><button>…</button></Tooltip>
187
- <SegmentedControl options={["Day", "Week"]} value={range} onChange={setRange} />
188
- ```
189
-
190
- ---
191
-
192
- ## 4. How to use the components
193
-
194
- Every component follows the same four conventions. Once you know them, you know
195
- the whole library.
196
-
197
- ### ① Content comes from props, and nothing is built in
198
-
199
- A component without props renders empty, never with placeholder text. Pass your
200
- data:
201
-
202
- ```tsx
203
- <TaskRows
204
- rows={[
205
- { key: "fetch", label: "Fetch invoices", amount: "42 files", status: "done", details: [] },
206
- { key: "match", label: "Match payments", amount: "38 rows", status: "running", step: 2, details: [] },
207
- ]}
208
- />
209
- ```
210
-
211
- ### ② UI words go in `labels`
212
-
213
- Button text, aria-labels and messages like "No results found" have English
214
- defaults. Override any of them, for wording or translation. Some are functions,
215
- so you can handle plurals:
216
-
217
- ```tsx
218
- <DiffTable
219
- rows={rows}
220
- labels={{
221
- apply: (n) => `Apply ${n} edit${n === 1 ? "" : "s"}`,
222
- toggleHint: "Click a row to include or exclude it",
223
- }}
224
- />
225
- ```
226
-
227
- ### ③ User actions come back as callbacks
228
-
229
- | Component | Callbacks |
230
- | --- | --- |
231
- | `PromptBar`, `ChatComposer` | `onSend(text, attachments)`, `onModelChange`, `onAttach(files)`, `onDictate()` |
232
- | `ApprovalCard` | `onSubmitted(answers)`, `onAnswerChange` |
233
- | `StreamingText` | `onFollowUp(text)`, `onAction(i)`, `onDone()` |
234
- | `SelectionActions` | `onAction(action)`: return the rewritten text (or a promise of it); `onKeep`, `onDiscard` |
235
- | `DiffTable` | `onApply(keptRows)` |
236
- | `RecommendationCard` | `onAccept(option)` |
237
- | `RecordsTable` | `onSelectionChange(ids)`, `onCalculate(column)` |
238
- | `SidebarNav` | `onNewChat`, `onPick(id)`, `onNavigate(key)`, `onWorkspaceMenu(key)` |
239
- | `Dialog` | `onConfirm()` (async is fine; return `false` to keep it open), `onOpenChange` |
240
- | `Flowchart` | `onConditionChange`, `onSelect` |
241
- | `Markdown` | `onLinkClick(href)`, `onCopyCode(code)` |
242
-
243
- ### ④ Sample data lives in `nexi-agent/demo`
244
-
245
- Each component has a ready-made fixture, which is useful for prototyping and for
246
- seeing what shape the props take:
247
-
248
- ```tsx
249
- import { RecordsTable } from "nexi-agent";
250
- import { recordsTableDemo } from "nexi-agent/demo";
251
-
252
- <RecordsTable {...recordsTableDemo} />;
253
- ```
254
-
255
- Fixture names are the component name in camelCase plus `Demo` (`approvalCardDemo`,
256
- `promptBarDemo`…). Read them in [`src/demo/`](src/demo). Nothing from `demo` reaches
257
- your bundle unless you import it.
258
-
259
- ### Types
260
-
261
- All props and data types are exported:
262
-
263
- ```ts
264
- import type { ApprovalQuestion, ToolStep, RecordRow, PromptBarProps, ThreadMessage } from "nexi-agent";
265
- ```
266
-
267
- ---
268
-
269
- ## 5. Recipes
270
-
271
- ### A complete chat screen
272
-
273
- ```tsx
274
- import { useState } from "react";
275
- import { EmptyState, LoadingState, Markdown, MessageThread, PromptBar, type ThreadMessage } from "nexi-agent";
276
-
277
- export function Chat() {
278
- const [messages, setMessages] = useState<ThreadMessage[]>([]);
279
- const [busy, setBusy] = useState(false);
280
-
281
- const send = async (text: string) => {
282
- setMessages((m) => [...m, { id: crypto.randomUUID(), role: "user", content: text }]);
283
- setBusy(true);
284
- const reply = await askAgent(text); // your API
285
- setMessages((m) => [...m, { id: crypto.randomUUID(), role: "assistant", name: "Agent", content: <Markdown content={reply} /> }]);
286
- setBusy(false);
287
- };
288
-
289
- return (
290
- <div style={{ display: "flex", flexDirection: "column", height: "100vh", maxWidth: 720, margin: "0 auto" }}>
291
- <MessageThread
292
- className="flex-1"
293
- messages={messages}
294
- empty={<EmptyState title="Ask anything" description="Answers show up here." />}
295
- footer={busy && <LoadingState label="Thinking" />}
296
- />
297
- <PromptBar onSend={send} placeholder="Message the agent…" />
298
- </div>
299
- );
300
- }
301
- ```
302
-
303
- ### Streaming an answer as it arrives
304
-
305
- Keep appending to a string. Both `Markdown` and `StreamingText` handle partial
306
- text.
307
-
308
- ```tsx
309
- const [answer, setAnswer] = useState("");
310
-
311
- const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ prompt }) });
312
- const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
313
- for (;;) {
314
- const { value, done } = await reader.read();
315
- if (done) break;
316
- setAnswer((a) => a + value);
317
- }
318
-
319
- <Markdown content={answer} />; // formatted
320
- <StreamingText content={answer} fill />; // word-by-word reveal + sources / follow-ups
321
- ```
322
-
323
- ### Showing the agent's work
324
-
325
- ```tsx
326
- <ThinkingState
327
- variant="Steps"
328
- active="Working"
329
- done="Finished in 6s"
330
- rows={steps.map((s) => ({ primary: s.title, secondary: s.detail }))}
331
- />
332
-
333
- <ToolChips
334
- steps={[
335
- { icon: "read", label: "Read file", chip: "invoices.csv", mono: true, detail: [{ text: "1,204 rows" }] },
336
- { icon: "run", label: "Run", chip: "npm test", mono: true, detail: [{ text: "✓ 34 passed" }] },
337
- ]}
338
- />
339
- ```
340
-
341
- ### Asking before acting
342
-
343
- ```tsx
344
- <ApprovalCard
345
- questions={[
346
- { q: "Send the reminder emails?", type: "radio", options: ["Send now", "Schedule for 9am"] },
347
- { q: "Who should get them?", type: "check", options: ["Overdue", "Due this week"] },
348
- ]}
349
- onSubmitted={(answers) => agent.resume(answers)}
350
- />
351
- ```
352
-
353
- ### Confirm and notify
354
-
355
- ```tsx
356
- // once, near the root
357
- <ToastProvider>
358
- <App />
359
- </ToastProvider>
360
-
361
- // in any component
362
- const { toast } = useToast();
363
- const [open, setOpen] = useState(false);
364
-
365
- <Dialog
366
- open={open}
367
- onOpenChange={setOpen}
368
- title="Delete this run?"
369
- description="Its logs and outputs will be removed."
370
- destructive
371
- labels={{ confirm: "Delete" }}
372
- onConfirm={async () => {
373
- await deleteRun(id);
374
- toast({ title: "Run deleted", tone: "success" });
375
- }}
376
- />
377
- ```
378
-
379
- ---
380
-
381
- ## 6. Customising
382
-
383
- ### Colours
384
-
385
- Every colour is a CSS variable. Override them globally or for any section:
386
-
387
- ```css
388
- :root {
389
- --accent: oklch(0.58 0.22 300); /* buttons, links, focus */
390
- --accent-ink: oklch(0.5 0.2 300); /* accent-coloured text */
391
- --accent-tint: oklch(0.95 0.03 300); /* soft accent backgrounds */
392
- }
393
-
394
- .billing { --accent: #0f9d58; } /* only inside .billing */
395
- ```
396
-
397
- | Token | Controls |
398
- | --- | --- |
399
- | `--page` `--canvas` `--surface` `--inset` `--field` | backgrounds, from the page down to inputs |
400
- | `--ink` `--ink-2` `--ink-3` | text: primary, secondary, muted |
401
- | `--line` `--line-strong` | borders and dividers |
402
- | `--accent` `--green` `--orange` `--red` (+ `-tint`) | brand and status colours |
403
- | `--tooltip-bg` `--tooltip-fg` | tooltips and chart labels |
404
-
405
- ### Dark mode
406
-
407
- Use `<NexiProvider dark>`, or put `class="dark"` on `<html>` to follow your app's
408
- own theme switch.
409
-
410
- ### Size and spacing
411
-
412
- - Most components accept `className` for margins, width and positioning.
413
- - Cards have a sensible maximum width (about 320–440px); wrap them to size them.
414
- `RecordsTable`, `SidebarNav` and `StreamingText` also accept `fill` to take the
415
- parent's size.
416
- - Atoms take `size` / `tone` / `variant`: `<Badge size="sm" tone="red" variant="outline">`,
417
- `<Button size="xs" variant="quiet">`, `<Avatar size="lg" square>`.
418
-
419
- ### Wording and language
420
-
421
- Use the `labels` prop on any component (see [②](#-ui-words-go-in-labels)).
422
-
423
- ---
424
-
425
- ## 7. Working on this repo
426
-
427
- ### Get going
428
-
429
- ```bash
430
- git clone https://github.com/abiramavarshini-kl/nexi-agent-component-package.git nexi-agent
431
- cd nexi-agent
432
- npm install # installs and builds dist/
433
- npm run playground # opens the docs site at http://localhost:5173
434
- ```
435
-
436
- ### Scripts
437
-
438
- | Command | What it does |
439
- | --- | --- |
440
- | `npm run build` | builds `dist/`: ESM + CJS bundles, type files, `styles.css`, `tailwind.css` |
441
- | `npm test` | builds, then renders every component twice: empty, and with demo data |
442
- | `npm run typecheck` | runs the TypeScript checks |
443
- | `npm run playground` | builds, then starts the playground dev server |
444
- | `npm pack` | creates the `.tgz` file to test-install in another app |
445
-
446
- ### The playground (docs site)
447
-
448
- [`playground/`](playground) is the public docs site: a Vite app with a page per
449
- component (live preview, copyable code, sample data and a props table), an
450
- introduction, an all-on-one-page gallery at `/all`, and dark mode. It uses the
451
- built `dist/`, so after editing `src/`, run `npm run build` and the site updates.
452
-
453
- - **Examples:** `playground/src/examples/<Name>.tsx`. Each file is rendered as the
454
- preview *and* shown as the code, so the two can't disagree.
455
- - **Page list and descriptions:** `playground/src/registry.ts`.
456
- - **Props tables:** generated from the TypeScript source by
457
- `playground/scripts/make-props.mjs` on every `dev`/`build`. Write a `/** comment */`
458
- above a prop and it shows up as the description.
459
-
460
- ### Deploying the docs site (Vercel)
461
-
462
- [`vercel.json`](vercel.json) holds the whole setup, so there's nothing to configure
463
- in the dashboard:
464
-
465
- 1. On [vercel.com](https://vercel.com), **Add New → Project** and import this GitHub
466
- repository.
467
- 2. Leave **Root Directory** as the repo root and the framework preset as **Other**
468
- (`vercel.json` sets the install, build and output commands). Click **Deploy**.
469
- 3. Every push to `main` redeploys the site. Every other branch and pull request gets
470
- its own preview URL.
471
-
472
- To use your own domain, go to **Project → Settings → Domains**.
473
-
474
- To check a deploy locally first: `npm run build && npm --prefix playground run build && npm --prefix playground run preview`.
475
-
476
- ### Day-to-day workflow
477
-
478
- ```bash
479
- # 1. edit src/…
480
- npm test # 2. build + check every component renders
481
- git add -A && git commit -m "…"
482
- git push # dist/ and .tgz files are git-ignored; no packing needed
483
- ```
484
-
485
- You only need `npm pack` to try the package in a separate app.
486
-
487
- ### Project structure
488
-
489
- ```
490
- src/
491
- atoms/ small building blocks (Badge, Button, Avatar, Tooltip…)
492
- primitives/ the main components (ApprovalCard, PromptBar, MessageThread…)
493
- provider/ NexiProvider
494
- demo/ sample data for every component → "nexi-agent/demo"
495
- lib/ cn() class helper, icon shims
496
- styles/ foundation.css: design tokens, theme, animations
497
- index.ts generated export list (don't edit by hand)
498
- scripts/
499
- make-index.mjs regenerates src/index.ts on every build
500
- build-css.mjs builds dist/styles.css and dist/tailwind.css
501
- make-foundation.py regenerates foundation.css from upstream Beautiful UI
502
- test/smoke.test.tsx render test for every component
503
- playground/ the docs site, deployed to Vercel (not published to npm)
504
- vercel.json Vercel build settings for the docs site
505
- ```
506
-
507
- ### Adding a component
508
-
509
- 1. Create `src/primitives/MyThing.tsx` with `export default function MyThing(props)`,
510
- or `src/atoms/MyThing.tsx` with a named export.
511
- 2. Follow the conventions: content props default to empty, UI words go in
512
- `labels`, user actions go out through callbacks, the outer element accepts
513
- `className`, and you export a `MyThingProps` type.
514
- 3. Add `src/demo/MyThing.ts` exporting `myThingDemo`, and re-export it from
515
- `src/demo/index.ts`.
516
- 4. Add `playground/src/examples/MyThing.tsx` (a default-exported example) and a row
517
- in `playground/src/registry.ts`. It gets its own docs page.
518
- 5. Run `npm test`. The export list regenerates automatically, and the test fails
519
- if the component has no demo fixture or crashes.
520
-
521
- ---
522
-
523
- ## 8. Docker
524
-
525
- Docker builds and tests the library, then serves the playground. You don't need
526
- Node on the host.
527
-
528
- ```bash
529
- docker compose up --build playground # nginx gallery → http://localhost:8080
530
- docker compose up -d --build playground # same, in the background
531
- docker compose down # stop
532
-
533
- docker compose --profile dev up --build dev # Vite dev server → http://localhost:5173
534
- ```
535
-
536
- Without Compose:
537
-
538
- ```bash
539
- docker build -t nexi-agent-playground .
540
- docker run --rm -p 8080:80 nexi-agent-playground # → http://localhost:8080
541
-
542
- docker build --target test -t nexi-agent-test . # build + smoke test only
543
- ```
544
-
545
- | Dockerfile stage | Purpose |
546
- | --- | --- |
547
- | `deps` | installs dependencies |
548
- | `build` | builds `dist/` |
549
- | `test` | runs the smoke test (the build fails if a component breaks) |
550
- | `dev` | playground dev server |
551
- | `playground` | builds the playground as static files |
552
- | `web` *(default)* | nginx serving the playground on port 80 |
553
-
554
- ---
555
-
556
- ## 9. Releasing
557
-
558
- The package is on npm as [`nexi-agent`](https://www.npmjs.com/package/nexi-agent).
559
- To release a new version:
560
-
561
- ```bash
562
- npm version patch # 0.1.0 → 0.1.1; use minor / major for bigger changes
563
- git push --follow-tags # pushes the commit and the v0.1.1 tag
564
- npm login # once per machine
565
- npm publish # runs typecheck + build, then asks you to confirm with 2FA
566
- ```
567
-
568
- A version number can't be published twice, so bump it with `npm version` each time.
569
- Publishing needs 2FA on the npm account. The docs site redeploys from `main` on
570
- its own, so there's nothing to do there.
571
-
572
- ---
573
-
574
- ## 10. Troubleshooting
575
-
576
- | Problem | Fix |
577
- | --- | --- |
578
- | Components appear unstyled | Import `nexi-agent/styles.css` once at the root (or `tailwind.css` for Tailwind v4 apps). |
579
- | A component renders empty | That's by design: pass your content props, or spread its fixture from `nexi-agent/demo`. |
580
- | `Invalid hook call` / two copies of React | Make sure your app has a single React. With a linked local package, add `resolve: { dedupe: ["react", "react-dom"] }` to your Vite config. |
581
- | Your app still shows old behaviour after reinstalling a `.tgz` | The version didn't change, so npm reused its cache. Delete `node_modules/nexi-agent` and install again. |
582
- | `npm warn allow-scripts … nexi-agent (prepare: npm run build)` when installing from Git | Harmless: npm has already built the package while fetching it from GitHub. You don't need to approve the script. |
583
- | `useToast must be used inside <ToastProvider>` | Wrap your app (or that part of it) in `<ToastProvider>`. |
584
- | Fonts look different from the screenshots | Load Inter and JetBrains Mono (see [Fonts](#fonts-optional)). |
585
- | `npm run build` fails on Windows | Use Node 20+ and run from the repo root. The build scripts are written to work on Windows. |
586
-
587
- ---
588
-
589
- ## 11. Credits and license
590
-
591
- MIT © Kaaylabs.
592
-
593
- The components are adapted from [Beautiful UI](https://www.beautifului.dev) © 2026
594
- Shane Levine (MIT, see `LICENSE.beautiful-ui`), with shadow styles from
595
- shadow-plugin © Florian Kiem (MIT).
596
-
597
- **Changes from upstream:** all demo content moved out of the components into
598
- `nexi-agent/demo`. Every component takes its text through props and `labels` and
599
- reports actions through callbacks. The commercial icon set was replaced with free
600
- `iconoir-react` icons, and global page styles were scoped to `.nexi`. Added:
601
- `Avatar`, `Badge`, `Tooltip`, `NexiProvider`, `MessageThread`, `Markdown`,
602
- `EmptyState`, `Dialog`, `ToastProvider`, `UsageMeter` and the playground.
1
+ # nexi-agent
2
+
3
+ **React components for building AI-agent interfaces:** chat threads, streaming
4
+ answers, reasoning traces, tool calls, approvals, task progress, data tables and
5
+ more. You install them, import them, and pass in your own data.
6
+
7
+ **[Browse every component live →](https://nexi-agent-component-package.vercel.app)** (previews, copyable code and props)
8
+
9
+ ```tsx
10
+ <ThinkingState done="Thought for 3 seconds" rows={[{ primary: "Reading the ticket" }]} />
11
+ <StreamingText content="The deploy failed because the API key expired." />
12
+ <ApprovalCard questions={[{ q: "Rotate the key now?", type: "radio", options: ["Yes", "Later"] }]} />
13
+ ```
14
+
15
+ - **43 components:** all 33 from [Beautiful UI](https://www.beautifului.dev), plus 10
16
+ more (chat thread, markdown, dialog, toast, avatar…).
17
+ - **No hardcoded content.** Every word and every row comes from your props.
18
+ - **Fully themeable** through CSS variables, with dark mode built in.
19
+ - **Works in any React 18/19 app** (Vite, Next.js App Router, Remix, CRA). Tailwind
20
+ is optional.
21
+ - **TypeScript-first.** Every component, prop and data type is exported.
22
+
23
+ ---
24
+
25
+ ## Table of contents
26
+
27
+ 1. [Quick start](#1-quick-start)
28
+ 2. [Setup](#2-setup)
29
+ 3. [What's inside](#3-whats-inside)
30
+ 4. [How to use the components](#4-how-to-use-the-components)
31
+ 5. [Recipes](#5-recipes)
32
+ 6. [Customising](#6-customising)
33
+ 7. [Working on this repo](#7-working-on-this-repo)
34
+ 8. [Docker](#8-docker)
35
+ 9. [Releasing](#9-releasing)
36
+ 10. [Troubleshooting](#10-troubleshooting)
37
+ 11. [Credits and license](#11-credits-and-license)
38
+
39
+ ---
40
+
41
+ ## 1. Quick start
42
+
43
+ ```bash
44
+ npm install nexi-agent
45
+ ```
46
+
47
+ ```tsx
48
+ // main.tsx (or your root layout)
49
+ import "nexi-agent/styles.css";
50
+ import { NexiProvider } from "nexi-agent";
51
+
52
+ root.render(
53
+ <NexiProvider>
54
+ <App />
55
+ </NexiProvider>,
56
+ );
57
+ ```
58
+
59
+ ```tsx
60
+ // anywhere inside
61
+ import { StreamingText } from "nexi-agent";
62
+
63
+ <StreamingText content="Hello! I'm your agent." />;
64
+ ```
65
+
66
+ That's all. To see every component with sample data first, open the
67
+ [docs site](https://nexi-agent-component-package.vercel.app).
68
+
69
+ ---
70
+
71
+ ## 2. Setup
72
+
73
+ ### Requirements
74
+
75
+ - React **18 or 19** (`react` and `react-dom` are peer dependencies)
76
+ - Node **20+** to build this repo (22 LTS recommended)
77
+
78
+ ### Install
79
+
80
+ | From | Command | When |
81
+ | --- | --- | --- |
82
+ | **npm** | `npm install nexi-agent` | the normal way |
83
+ | **Git** | `npm install github:kaaylabs-v2/nexi-components` (add `#main` or `#v0.1.0` to pin) | an unreleased commit or branch. npm builds the package on install. |
84
+ | **A local file** | in this repo: `npm run build && npm pack`, then in your app: `npm install ../path/nexi-agent-0.1.0.tgz` | testing unreleased changes in another app |
85
+
86
+ ### Styles: pick one
87
+
88
+ | Your app | Add this | Result |
89
+ | --- | --- | --- |
90
+ | **No Tailwind** (or Tailwind v3) | `import "nexi-agent/styles.css";` once, at the root | precompiled CSS with everything the components need |
91
+ | **Tailwind v4** | in your main CSS, after `@import "tailwindcss";`: `@import "nexi-agent/tailwind.css";` | one combined build; you can also use our tokens (`bg-surface`, `text-ink-2`, `shadow-card`…) in your own markup |
92
+
93
+ ### The provider
94
+
95
+ Wrap your UI in `<NexiProvider>` once. It applies the font, text size and colour
96
+ scope (the `.nexi` class) without touching the rest of your page.
97
+
98
+ ```tsx
99
+ <NexiProvider>…</NexiProvider> // light
100
+ <NexiProvider dark>…</NexiProvider> // dark, for this subtree
101
+ <NexiProvider contents>…</NexiProvider> // no wrapper box (display: contents)
102
+ ```
103
+
104
+ ### Fonts (optional)
105
+
106
+ The design uses **Inter** and **JetBrains Mono**. Load them in your app (Google
107
+ Fonts or `next/font`); otherwise the system fonts are used.
108
+
109
+ ```html
110
+ <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
111
+ ```
112
+
113
+ ### Next.js
114
+
115
+ It works out of the box: the bundle is marked `"use client"`, so you can import
116
+ components straight into App Router pages. Put the CSS import in `app/layout.tsx`.
117
+
118
+ ---
119
+
120
+ ## 3. What's inside
121
+
122
+ ### Conversation
123
+
124
+ | Component | What it shows |
125
+ | --- | --- |
126
+ | `MessageThread` / `Message` | the scrolling chat: user bubbles, agent turns that can hold any component, auto-scroll |
127
+ | `StreamingText` | an answer revealed word by word, with inline citations, sources, action buttons and follow-ups |
128
+ | `Markdown` | a formatted markdown answer (headings, lists, tables, code); safe, and works while text streams in |
129
+ | `ChatComposer` | a compact chat panel with tabs, replies and an input |
130
+ | `PromptBar` | a full input: `@` sources, `/` commands, model picker, attachments, dictation |
131
+ | `SelectionActions` | highlight text → ask the agent to rewrite it → keep or discard |
132
+
133
+ ### Agent activity
134
+
135
+ | Component | What it shows |
136
+ | --- | --- |
137
+ | `ThinkingState` | an expandable reasoning trace (Steps · Reasoning · Search · Coding) |
138
+ | `ToolChips` | tool calls as compact rows, plus file-diff chips |
139
+ | `TaskRows` | tasks with running / failed / completed status |
140
+ | `LoadingState` | a pixel loader with shimmering label and live timer |
141
+ | `AgentScreen` | a live view of the agent's screen (image or video stream) |
142
+ | `ContextCards` | retrieved document chunks (RAG) and their sources |
143
+
144
+ ### Decisions
145
+
146
+ | Component | What it shows |
147
+ | --- | --- |
148
+ | `ApprovalCard` | questions the user answers before the agent acts (human in the loop) |
149
+ | `RecommendationCard` | a suggested action with a confidence meter and alternatives |
150
+ | `DiffTable` | proposed row additions and removals the user can accept one by one |
151
+ | `Dialog` | a confirm or small-form modal |
152
+
153
+ ### Data
154
+
155
+ | Component | What it shows |
156
+ | --- | --- |
157
+ | `RecordsTable` | a spreadsheet-style grid: tags, sorting, resizing, AI-calculated columns |
158
+ | `FilterTable` | a table filtered by status chips |
159
+ | `InsightCards` | a carousel of insights with live charts (`InsightCompareCard`, `InsightAnomalyCard`, `InsightAllocationCard` also work alone) |
160
+ | `CodeBlock` | a code listing or unified diff, with copy |
161
+ | `Flowchart` | a workflow canvas with draggable step and condition cards |
162
+ | `UsageMeter` | tokens or credits used against a limit |
163
+
164
+ ### App shell and feedback
165
+
166
+ | Component | What it shows |
167
+ | --- | --- |
168
+ | `SidebarNav` | collapsible workspace switcher, navigation and chat history |
169
+ | `SearchList` | a command search with live filtering |
170
+ | `EmptyState` | "nothing here yet" or error panels |
171
+ | `ToastProvider` / `useToast` | short notifications |
172
+ | `FineTuneCard` | an inspector with draggable number fields |
173
+ | `GlideMenu` | a menu with a gliding hover highlight |
174
+
175
+ ### Effects
176
+
177
+ Animated pieces for landing pages, dashboards and agent shells. They use the same
178
+ tokens, so they follow your theme and dark mode, add no dependencies, and respect
179
+ `prefers-reduced-motion`.
180
+
181
+ | Component | What it shows |
182
+ | --- | --- |
183
+ | `MovingBorder` | a button with a glow travelling around its border |
184
+ | `HoverBorderGradient` | a pill with an orbiting border highlight that floods with accent on hover |
185
+ | `StatefulButton` | a button that shows loading, then success or error, from the promise `onClick` returns |
186
+ | `EncryptedText` | text that scrambles through random glyphs before locking in |
187
+ | `FlipWords` | cycles words inside a sentence with a blur-in, drift-out transition |
188
+ | `Typewriter` | types styled words behind a blinking caret, optionally looping |
189
+ | `SpotlightCard` | a card with a pointer-following light that reveals a dot pattern |
190
+ | `GlareCard` | a card that tilts toward the pointer with a glare and holographic sheen |
191
+ | `AnimatedTooltip` | an avatar stack whose tooltips swing with the pointer |
192
+ | `Meteors` | a card with meteors streaking across its background |
193
+ | `GridBackground` | a grid, small-grid or dot background that fades at the edges |
194
+ | `FileUpload` | a drop zone with a lifting upload tile and file detail cards |
195
+ | `FloatingDock` | a dock whose icons magnify as the pointer approaches |
196
+ | `AnimatedTabs` | tabs with a gliding pill and a stacked deck of panels |
197
+ | `BentoGrid` / `BentoGridItem` | a responsive grid of feature tiles; tiles can span columns |
198
+ | `Timeline` | entries with sticky titles and a beam that fills as you scroll |
199
+ | `AuroraBackground` | soft bands of colour drifting behind the content |
200
+ | `BackgroundBeams` | a fan of faint curved lines with pulses of colour racing along them |
201
+ | `Sparkles` | a canvas of tiny particles that twinkle and drift |
202
+ | `LampEffect` | a bar of light that switches on and throws a cone onto the heading |
203
+ | `Card3D` / `Card3DItem` | a card that turns toward the pointer while its layers lift off by their own depth |
204
+ | `InfiniteMovingCards` | quote cards scrolling in an endless loop, paused on hover |
205
+ | `NavbarMenu` | a pill nav with one dropdown panel that glides between items |
206
+ | `AnimatedModal` | a trigger whose label slides to an icon, opening a modal that tips into place |
207
+ | `LinkPreview` | an inline link that springs up a preview card on hover |
208
+ | `ImagesSlider` | a full-bleed slideshow with content on top, autoplay, arrows and dots |
209
+ | `CardsCarousel` | a sideways-scrolling row of story cards that open into a modal |
210
+ | `AnimatedTestimonials` | a loose photo stack beside a quote whose words blur into focus |
211
+ | `BackgroundGradient` | a frame of colour that slowly turns around any content, with a glow that brightens on hover |
212
+ | `BackgroundGradientAnimation` | large blurred orbs drifting over a gradient field, one trailing the pointer |
213
+ | `WavyBackground` | ribbons of colour undulating across a canvas |
214
+ | `BackgroundBoxes` | a perspective floor of tiles that light up as the pointer passes |
215
+ | `BeamsWithCollision` | streaks of light falling and bursting into sparks on the floor |
216
+ | `BackgroundLines` | long flowing curves that draw themselves in colour |
217
+ | `BackgroundRippleEffect` | a grid where a click sends a ring of light spreading out |
218
+ | `DottedGlowBackground` | a grid of faint dots, some breathing with a coloured glow |
219
+ | `GlowingStars` | a card topped with a field of stars that flare up; hover sweeps light across them |
220
+ | `ShootingStars` | a night sky of twinkling stars with shooting stars streaking across |
221
+ | `Vortex` | glowing particles swirling around the centre, leaving light trails |
222
+ | `BackgroundCubesGrid` | a floor of cubes that rise toward the pointer |
223
+ | `Spotlight` | a beam of light that swings in from a corner and settles across the content |
224
+ | `SpotlightNew` | two banks of soft stage lights swaying from the top corners |
225
+ | `CanvasRevealEffect` | a card that floods with a matrix of glowing dots on hover |
226
+ | `SvgMaskEffect` | a lens that follows the pointer and reveals a second layer of content |
227
+ | `TracingBeam` | a rail beside long content with a beam that traces along as you scroll |
228
+ | `GlowingEffect` | an arc of colour on a card's border that follows the nearby pointer |
229
+ | `ScrollPathsEffect` | ribbons of colour that draw in and converge as you scroll (our take on the Google Gemini Effect) |
230
+ | `Scales` | a panel framed by rulers whose ticks react to the pointer |
231
+ | `ImagesBadge` | a pill badge whose thumbnails fan out on hover |
232
+ | `ParallaxHeroImages` | pictures floating around a headline at different depths, shifting with the pointer |
233
+ | `ChromaticImage` | an image whose colour channels split apart toward the pointer |
234
+ | `LiquidGlass` | a frosted, edge-refracting glass pane for any colourful background |
235
+ | `ImageGenerationLoader` | an image that develops from blurry grain to sharp behind a scan line, with a live percentage |
236
+ | `DitherShader` | retro ordered dithering of a moving plasma field or any image, drawn on a plain canvas |
237
+ | `Marquee3D` | a tilted wall of pictures whose columns drift in opposite directions |
238
+
239
+ ### Cards
240
+
241
+ | Component | What it shows |
242
+ | --- | --- |
243
+ | `CardHoverEffect` | a grid of link cards with one highlight that slides between them |
244
+ | `CardStack` | a deck of cards where the top one slips to the back every few seconds or on click |
245
+ | `WobbleCard` | a bold card that leans after the pointer while its content drifts the other way |
246
+ | `FocusCards` | picture cards where hovering one blurs the rest and reveals its title |
247
+ | `ExpandableCard` | a list of rows that each grow into a full detail card |
248
+ | `DraggableCards` | picture cards you can pick up, fling and drop on a table |
249
+ | `CometCard` | a weighty card that tips toward the pointer with a streak of light across it |
250
+ | `CipherCard` | a card of scrambled characters revealed in a glow around the pointer (our take on the Evervault Card) |
251
+ | `DirectionAwareHover` | a picture card whose caption slides in from the edge the pointer entered |
252
+ | `TooltipCard` | inline text that floats a rich card beside the pointer |
253
+ | `Keyboard` | an on-screen keyboard whose keys sink on click or real key presses |
254
+ | `Terminal` | a terminal window that plays back a typed session with output |
255
+ | `AsciiArt` | any image turned into character art, typed in row by row |
256
+ | `PixelatedCanvas` | an image as chunky pixels that the pointer pushes aside |
257
+ | `CloudShader` | soft clouds drifting across a sky, drawn on a canvas (a lightweight stand-in for a shader) |
258
+ | `WebcamPixelGrid` | the viewer's camera as a grid of dots, after they click to start |
259
+ | `Carousel3D` | picture slides in a row; the current one tilts toward the pointer while its neighbours fall back |
260
+ | `LayoutGrid` | a mosaic of pictures where the chosen one grows out of the grid to tell its story |
261
+ | `Pin3D` | a card that tips back on hover as a beam rises with ripples and a link tag |
262
+ | `Compare` | two images with a glowing divider to drag, hover or auto-sweep between them |
263
+
264
+ ### Scroll and parallax
265
+
266
+ | Component | What it shows |
267
+ | --- | --- |
268
+ | `ParallaxScroll` | a three-column photo wall whose columns drift apart as you scroll |
269
+ | `StickyScrollReveal` | scrolling sections beside a pinned panel that swaps to match the one in focus |
270
+ | `LaptopScroll` | a CSS-drawn laptop whose lid opens and screen grows as you scroll (our take on Macbook Scroll) |
271
+ | `ContainerScrollAnimation` | a device frame that rises from tipped-back to upright as you scroll |
272
+ | `HeroParallax` | a headline over rows of product shots that straighten and glide sideways on scroll |
273
+
274
+ ### Text
275
+
276
+ | Component | What it shows |
277
+ | --- | --- |
278
+ | `TextHoverEffect` | a huge outlined word that draws itself in and glows in colour under the pointer |
279
+ | `HeroHighlight` / `Highlight` | a dot-grid hero that brightens around the pointer, with a marker-sweep Highlight for key words |
280
+ | `TextRevealCard` | a card whose muted line wipes into a bright second line under the pointer |
281
+ | `ContainerTextFlip` | a word in a raised box that resizes as it flips to the next word |
282
+ | `LayoutTextFlip` | a fixed phrase with a word card that flips upward and resizes smoothly |
283
+ | `ColourfulText` | letters in many colours that reshuffle with a hopping ripple |
284
+ | `SquigglyText` | text that wobbles like a hand-drawn cartoon, via an SVG noise filter |
285
+ | `CanvasText` | big lettering filled with flowing bands of colour drawn on a canvas |
286
+ | `TextFlippingBoard` | a split-flap board whose tiles riffle to each new message |
287
+ | `ContainerCover` | a framed word that hits warp speed on hover, with racing light streaks |
288
+ | `PointerHighlight` | a selection box drawn around words by a cursor as they scroll into view |
289
+
290
+ ### Buttons
291
+
292
+ | Component | What it shows |
293
+ | --- | --- |
294
+ | `EffectButton` | one button, nine CSS effects: shimmer, glow, sketch, lift, outline, gradient, invert, spotlight and arrow |
295
+ | `MagneticButton` | a button that leans toward the pointer, with a label that leans a little further |
296
+ | `NoiseBackground` | drifting colour washes under film grain, as a fill or a glowing rim |
297
+
298
+ ### Navigation
299
+
300
+ | Component | What it shows |
301
+ | --- | --- |
302
+ | `FloatingNavbar` | a pill nav that hides while you scroll down and returns when you scroll up |
303
+ | `ResizableNavbar` | a full-width header that tucks into a frosted floating bar on scroll, with a mobile menu |
304
+ | `StickyBanner` | an announcement strip pinned to the top that slides away on scroll and folds shut when dismissed |
305
+ | `Notch` | a black status pill that springs open into a detail panel |
306
+
307
+ ### Inputs
308
+
309
+ | Component | What it shows |
310
+ | --- | --- |
311
+ | `SignupForm` / `GlowInput` | a sign-up card whose fields glow around the pointer, with provider buttons |
312
+ | `GooeyInput` | a round search button that stretches into a field like a drop of liquid |
313
+
314
+ ### Pointer
315
+
316
+ | Component | What it shows |
317
+ | --- | --- |
318
+ | `FollowingPointer` | a custom arrow with a name tag that replaces the cursor inside an area |
319
+ | `Lens` | a round magnifier that shows a zoomed copy of any content under the pointer |
320
+
321
+ ### Maps and globes
322
+
323
+ | Component | What it shows |
324
+ | --- | --- |
325
+ | `WorldMap` | a dotted world map with arcs that draw themselves between places |
326
+ | `ArcGlobe` | a night-side globe with arcs streaking between cities and ripples where they land |
327
+ | `Globe` | a dotted, lit 3D globe with glowing markers that you can spin |
328
+
329
+ ### Atoms (small building blocks)
330
+
331
+ `Avatar` · `Badge` · `Button` · `Chip` · `EntityChip` · `Monogram` ·
332
+ `ProgressRing` · `SegmentedControl` · `Shimmer` · `StatusPill` · `StreamText` ·
333
+ `Switch` · `TextRow` · `Tooltip` · `ValuePill` · `NexiProvider`
334
+
335
+ ```tsx
336
+ <Badge tone="green" dot>Completed</Badge>
337
+ <Button variant="accent" size="sm">Run</Button>
338
+ <StatusPill tone="orange">Running</StatusPill>
339
+ <Avatar name="Maya Chen" src={photo} status="online" />
340
+ <Tooltip content="Copy answer"><button>…</button></Tooltip>
341
+ <SegmentedControl options={["Day", "Week"]} value={range} onChange={setRange} />
342
+ ```
343
+
344
+ ---
345
+
346
+ ## 4. How to use the components
347
+
348
+ Every component follows the same four conventions. Once you know them, you know
349
+ the whole library.
350
+
351
+ ### ① Content comes from props, and nothing is built in
352
+
353
+ A component without props renders empty, never with placeholder text. Pass your
354
+ data:
355
+
356
+ ```tsx
357
+ <TaskRows
358
+ rows={[
359
+ { key: "fetch", label: "Fetch invoices", amount: "42 files", status: "done", details: [] },
360
+ { key: "match", label: "Match payments", amount: "38 rows", status: "running", step: 2, details: [] },
361
+ ]}
362
+ />
363
+ ```
364
+
365
+ ### ② UI words go in `labels`
366
+
367
+ Button text, aria-labels and messages like "No results found" have English
368
+ defaults. Override any of them, for wording or translation. Some are functions,
369
+ so you can handle plurals:
370
+
371
+ ```tsx
372
+ <DiffTable
373
+ rows={rows}
374
+ labels={{
375
+ apply: (n) => `Apply ${n} edit${n === 1 ? "" : "s"}`,
376
+ toggleHint: "Click a row to include or exclude it",
377
+ }}
378
+ />
379
+ ```
380
+
381
+ ### ③ User actions come back as callbacks
382
+
383
+ | Component | Callbacks |
384
+ | --- | --- |
385
+ | `PromptBar`, `ChatComposer` | `onSend(text, attachments)`, `onModelChange`, `onAttach(files)`, `onDictate()` |
386
+ | `ApprovalCard` | `onSubmitted(answers)`, `onAnswerChange` |
387
+ | `StreamingText` | `onFollowUp(text)`, `onAction(i)`, `onDone()` |
388
+ | `SelectionActions` | `onAction(action)`: return the rewritten text (or a promise of it); `onKeep`, `onDiscard` |
389
+ | `DiffTable` | `onApply(keptRows)` |
390
+ | `RecommendationCard` | `onAccept(option)` |
391
+ | `RecordsTable` | `onSelectionChange(ids)`, `onCalculate(column)` |
392
+ | `SidebarNav` | `onNewChat`, `onPick(id)`, `onNavigate(key)`, `onWorkspaceMenu(key)` |
393
+ | `Dialog` | `onConfirm()` (async is fine; return `false` to keep it open), `onOpenChange` |
394
+ | `Flowchart` | `onConditionChange`, `onSelect` |
395
+ | `Markdown` | `onLinkClick(href)`, `onCopyCode(code)` |
396
+ | `StatefulButton` | `onClick(e)`: return a promise to drive the loading → success / error states |
397
+ | `FileUpload` | `onChange(files)` |
398
+ | `AnimatedTabs` | `onValueChange(value)` |
399
+ | `AnimatedModal` | `onOpenChange(open)`; `footer` can be a function that receives `close` |
400
+ | `NavbarMenu` | `onNavigate(href, event)` |
401
+ | `CardsCarousel` | `onOpen(card, index)` |
402
+ | `BackgroundRippleEffect` | `onCellClick(row, col)` |
403
+ | `ImagesBadge` | `onClick()` (or pass `href`) |
404
+ | `CardHoverEffect`, `FocusCards` | `onSelect(item, index)` |
405
+ | `ExpandableCard` | `onOpen(item, index)` |
406
+ | `Keyboard` | `onKeyPress(key)` |
407
+ | `FloatingNavbar`, `ResizableNavbar` | `onNavigate(href, event)` |
408
+ | `StickyBanner` | `onClose()` |
409
+ | `Notch` | `onExpandedChange(expanded)` |
410
+ | `SignupForm` | `onSubmit(values, event)`, `onProvider(id)` |
411
+ | `GooeyInput` | `onChange(value)`, `onSubmit(value)` |
412
+ | `ImageGenerationLoader` | `onComplete()` |
413
+ | `Carousel3D` | `onAction(slide, index)`, `onIndexChange(index)` |
414
+ | `LayoutGrid` | `onSelect(card, index)` (both `null` when closed) |
415
+ | `Compare` | `onChange(position)` |
416
+ | `Pin3D` | `onClick(event)` (or pass `href`) |
417
+
418
+ ### ④ Sample data lives in `nexi-agent/demo`
419
+
420
+ Each component has a ready-made fixture, which is useful for prototyping and for
421
+ seeing what shape the props take:
422
+
423
+ ```tsx
424
+ import { RecordsTable } from "nexi-agent";
425
+ import { recordsTableDemo } from "nexi-agent/demo";
426
+
427
+ <RecordsTable {...recordsTableDemo} />;
428
+ ```
429
+
430
+ Fixture names are the component name in camelCase plus `Demo` (`approvalCardDemo`,
431
+ `promptBarDemo`…). Read them in [`src/demo/`](src/demo). Nothing from `demo` reaches
432
+ your bundle unless you import it.
433
+
434
+ ### Types
435
+
436
+ All props and data types are exported:
437
+
438
+ ```ts
439
+ import type { ApprovalQuestion, ToolStep, RecordRow, PromptBarProps, ThreadMessage } from "nexi-agent";
440
+ ```
441
+
442
+ ---
443
+
444
+ ## 5. Recipes
445
+
446
+ ### A complete chat screen
447
+
448
+ ```tsx
449
+ import { useState } from "react";
450
+ import { EmptyState, LoadingState, Markdown, MessageThread, PromptBar, type ThreadMessage } from "nexi-agent";
451
+
452
+ export function Chat() {
453
+ const [messages, setMessages] = useState<ThreadMessage[]>([]);
454
+ const [busy, setBusy] = useState(false);
455
+
456
+ const send = async (text: string) => {
457
+ setMessages((m) => [...m, { id: crypto.randomUUID(), role: "user", content: text }]);
458
+ setBusy(true);
459
+ const reply = await askAgent(text); // your API
460
+ setMessages((m) => [...m, { id: crypto.randomUUID(), role: "assistant", name: "Agent", content: <Markdown content={reply} /> }]);
461
+ setBusy(false);
462
+ };
463
+
464
+ return (
465
+ <div style={{ display: "flex", flexDirection: "column", height: "100vh", maxWidth: 720, margin: "0 auto" }}>
466
+ <MessageThread
467
+ className="flex-1"
468
+ messages={messages}
469
+ empty={<EmptyState title="Ask anything" description="Answers show up here." />}
470
+ footer={busy && <LoadingState label="Thinking" />}
471
+ />
472
+ <PromptBar onSend={send} placeholder="Message the agent…" />
473
+ </div>
474
+ );
475
+ }
476
+ ```
477
+
478
+ ### Streaming an answer as it arrives
479
+
480
+ Keep appending to a string. Both `Markdown` and `StreamingText` handle partial
481
+ text.
482
+
483
+ ```tsx
484
+ const [answer, setAnswer] = useState("");
485
+
486
+ const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ prompt }) });
487
+ const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
488
+ for (;;) {
489
+ const { value, done } = await reader.read();
490
+ if (done) break;
491
+ setAnswer((a) => a + value);
492
+ }
493
+
494
+ <Markdown content={answer} />; // formatted
495
+ <StreamingText content={answer} fill />; // word-by-word reveal + sources / follow-ups
496
+ ```
497
+
498
+ ### Showing the agent's work
499
+
500
+ ```tsx
501
+ <ThinkingState
502
+ variant="Steps"
503
+ active="Working"
504
+ done="Finished in 6s"
505
+ rows={steps.map((s) => ({ primary: s.title, secondary: s.detail }))}
506
+ />
507
+
508
+ <ToolChips
509
+ steps={[
510
+ { icon: "read", label: "Read file", chip: "invoices.csv", mono: true, detail: [{ text: "1,204 rows" }] },
511
+ { icon: "run", label: "Run", chip: "npm test", mono: true, detail: [{ text: "✓ 34 passed" }] },
512
+ ]}
513
+ />
514
+ ```
515
+
516
+ ### Asking before acting
517
+
518
+ ```tsx
519
+ <ApprovalCard
520
+ questions={[
521
+ { q: "Send the reminder emails?", type: "radio", options: ["Send now", "Schedule for 9am"] },
522
+ { q: "Who should get them?", type: "check", options: ["Overdue", "Due this week"] },
523
+ ]}
524
+ onSubmitted={(answers) => agent.resume(answers)}
525
+ />
526
+ ```
527
+
528
+ ### Confirm and notify
529
+
530
+ ```tsx
531
+ // once, near the root
532
+ <ToastProvider>
533
+ <App />
534
+ </ToastProvider>
535
+
536
+ // in any component
537
+ const { toast } = useToast();
538
+ const [open, setOpen] = useState(false);
539
+
540
+ <Dialog
541
+ open={open}
542
+ onOpenChange={setOpen}
543
+ title="Delete this run?"
544
+ description="Its logs and outputs will be removed."
545
+ destructive
546
+ labels={{ confirm: "Delete" }}
547
+ onConfirm={async () => {
548
+ await deleteRun(id);
549
+ toast({ title: "Run deleted", tone: "success" });
550
+ }}
551
+ />
552
+ ```
553
+
554
+ ---
555
+
556
+ ## 6. Customising
557
+
558
+ ### Colours
559
+
560
+ Every colour is a CSS variable. Override them globally or for any section:
561
+
562
+ ```css
563
+ :root {
564
+ --accent: oklch(0.58 0.22 300); /* buttons, links, focus */
565
+ --accent-ink: oklch(0.5 0.2 300); /* accent-coloured text */
566
+ --accent-tint: oklch(0.95 0.03 300); /* soft accent backgrounds */
567
+ }
568
+
569
+ .billing { --accent: #0f9d58; } /* only inside .billing */
570
+ ```
571
+
572
+ | Token | Controls |
573
+ | --- | --- |
574
+ | `--page` `--canvas` `--surface` `--inset` `--field` | backgrounds, from the page down to inputs |
575
+ | `--ink` `--ink-2` `--ink-3` | text: primary, secondary, muted |
576
+ | `--line` `--line-strong` | borders and dividers |
577
+ | `--accent` `--green` `--orange` `--red` (+ `-tint`) | brand and status colours |
578
+ | `--tooltip-bg` `--tooltip-fg` | tooltips and chart labels |
579
+
580
+ ### Dark mode
581
+
582
+ Use `<NexiProvider dark>`, or put `class="dark"` on `<html>` to follow your app's
583
+ own theme switch.
584
+
585
+ ### Size and spacing
586
+
587
+ - Most components accept `className` for margins, width and positioning.
588
+ - Cards have a sensible maximum width (about 320–440px); wrap them to size them.
589
+ `RecordsTable`, `SidebarNav` and `StreamingText` also accept `fill` to take the
590
+ parent's size.
591
+ - Atoms take `size` / `tone` / `variant`: `<Badge size="sm" tone="red" variant="outline">`,
592
+ `<Button size="xs" variant="quiet">`, `<Avatar size="lg" square>`.
593
+
594
+ ### Wording and language
595
+
596
+ Use the `labels` prop on any component (see [②](#-ui-words-go-in-labels)).
597
+
598
+ ---
599
+
600
+ ## 7. Working on this repo
601
+
602
+ ### Get going
603
+
604
+ ```bash
605
+ git clone https://github.com/kaaylabs-v2/nexi-components.git nexi-agent
606
+ cd nexi-agent
607
+ npm install # installs and builds dist/
608
+ npm run playground # opens the docs site at http://localhost:5173
609
+ ```
610
+
611
+ ### Scripts
612
+
613
+ | Command | What it does |
614
+ | --- | --- |
615
+ | `npm run build` | builds `dist/`: ESM + CJS bundles, type files, `styles.css`, `tailwind.css` |
616
+ | `npm test` | builds, then renders every component twice: empty, and with demo data |
617
+ | `npm run typecheck` | runs the TypeScript checks |
618
+ | `npm run playground` | builds, then starts the playground dev server |
619
+ | `npm pack` | creates the `.tgz` file to test-install in another app |
620
+
621
+ ### The playground (docs site)
622
+
623
+ [`playground/`](playground) is the public docs site: a Vite app with a page per
624
+ component (live preview, copyable code, sample data and a props table), an
625
+ introduction, an all-on-one-page gallery at `/all`, and dark mode. It uses the
626
+ built `dist/`, so after editing `src/`, run `npm run build` and the site updates.
627
+
628
+ - **Examples:** `playground/src/examples/<Name>.tsx`. Each file is rendered as the
629
+ preview *and* shown as the code, so the two can't disagree.
630
+ - **Page list and descriptions:** `playground/src/registry.ts`.
631
+ - **Props tables:** generated from the TypeScript source by
632
+ `playground/scripts/make-props.mjs` on every `dev`/`build`. Write a `/** comment */`
633
+ above a prop and it shows up as the description.
634
+
635
+ ### Deploying the docs site (Vercel)
636
+
637
+ [`vercel.json`](vercel.json) holds the whole setup, so there's nothing to configure
638
+ in the dashboard:
639
+
640
+ 1. On [vercel.com](https://vercel.com), **Add New → Project** and import this GitHub
641
+ repository.
642
+ 2. Leave **Root Directory** as the repo root and the framework preset as **Other**
643
+ (`vercel.json` sets the install, build and output commands). Click **Deploy**.
644
+ 3. Every push to `main` redeploys the site. Every other branch and pull request gets
645
+ its own preview URL.
646
+
647
+ To use your own domain, go to **Project → Settings → Domains**.
648
+
649
+ To check a deploy locally first: `npm run build && npm --prefix playground run build && npm --prefix playground run preview`.
650
+
651
+ ### Day-to-day workflow
652
+
653
+ ```bash
654
+ # 1. edit src/…
655
+ npm test # 2. build + check every component renders
656
+ git add -A && git commit -m "…"
657
+ git push # dist/ and .tgz files are git-ignored; no packing needed
658
+ ```
659
+
660
+ You only need `npm pack` to try the package in a separate app.
661
+
662
+ ### Project structure
663
+
664
+ ```
665
+ src/
666
+ atoms/ small building blocks (Badge, Button, Avatar, Tooltip…)
667
+ primitives/ the main components (ApprovalCard, PromptBar, MessageThread…)
668
+ effects/ animated pieces (MovingBorder, SpotlightCard, Timeline…)
669
+ provider/ NexiProvider
670
+ demo/ sample data for every component → "nexi-agent/demo"
671
+ lib/ cn() class helper, icon shims
672
+ styles/ foundation.css: design tokens, theme, animations
673
+ index.ts generated export list (don't edit by hand)
674
+ scripts/
675
+ make-index.mjs regenerates src/index.ts on every build
676
+ build-css.mjs builds dist/styles.css and dist/tailwind.css
677
+ make-foundation.py regenerates foundation.css from upstream Beautiful UI
678
+ test/smoke.test.tsx render test for every component
679
+ playground/ the docs site, deployed to Vercel (not published to npm)
680
+ vercel.json Vercel build settings for the docs site
681
+ ```
682
+
683
+ ### Adding a component
684
+
685
+ 1. Create `src/primitives/MyThing.tsx` (or `src/effects/MyThing.tsx` for an animated
686
+ piece) with `export default function MyThing(props)`, or `src/atoms/MyThing.tsx`
687
+ with a named export.
688
+ 2. Follow the conventions: content props default to empty, UI words go in
689
+ `labels`, user actions go out through callbacks, the outer element accepts
690
+ `className`, and you export a `MyThingProps` type.
691
+ 3. Add `src/demo/MyThing.ts` exporting `myThingDemo`, and re-export it from
692
+ `src/demo/index.ts`.
693
+ 4. Add `playground/src/examples/MyThing.tsx` (a default-exported example) and a row
694
+ in `playground/src/registry.ts`. It gets its own docs page.
695
+ 5. Run `npm test`. The export list regenerates automatically, and the test fails
696
+ if the component has no demo fixture or crashes.
697
+
698
+ ---
699
+
700
+ ## 8. Docker
701
+
702
+ Docker builds and tests the library, then serves the playground. You don't need
703
+ Node on the host.
704
+
705
+ ```bash
706
+ docker compose up --build playground # nginx gallery → http://localhost:8080
707
+ docker compose up -d --build playground # same, in the background
708
+ docker compose down # stop
709
+
710
+ docker compose --profile dev up --build dev # Vite dev server → http://localhost:5173
711
+ ```
712
+
713
+ Without Compose:
714
+
715
+ ```bash
716
+ docker build -t nexi-agent-playground .
717
+ docker run --rm -p 8080:80 nexi-agent-playground # → http://localhost:8080
718
+
719
+ docker build --target test -t nexi-agent-test . # build + smoke test only
720
+ ```
721
+
722
+ | Dockerfile stage | Purpose |
723
+ | --- | --- |
724
+ | `deps` | installs dependencies |
725
+ | `build` | builds `dist/` |
726
+ | `test` | runs the smoke test (the build fails if a component breaks) |
727
+ | `dev` | playground dev server |
728
+ | `playground` | builds the playground as static files |
729
+ | `web` *(default)* | nginx serving the playground on port 80 |
730
+
731
+ ---
732
+
733
+ ## 9. Releasing
734
+
735
+ The package is on npm as [`nexi-agent`](https://www.npmjs.com/package/nexi-agent).
736
+ To release a new version:
737
+
738
+ ```bash
739
+ npm version patch # 0.1.0 → 0.1.1; use minor / major for bigger changes
740
+ git push --follow-tags # pushes the commit and the v0.1.1 tag
741
+ npm login # once per machine
742
+ npm publish # runs typecheck + build, then asks you to confirm with 2FA
743
+ ```
744
+
745
+ A version number can't be published twice, so bump it with `npm version` each time.
746
+ Publishing needs 2FA on the npm account. The docs site redeploys from `main` on
747
+ its own, so there's nothing to do there.
748
+
749
+ ---
750
+
751
+ ## 10. Troubleshooting
752
+
753
+ | Problem | Fix |
754
+ | --- | --- |
755
+ | Components appear unstyled | Import `nexi-agent/styles.css` once at the root (or `tailwind.css` for Tailwind v4 apps). |
756
+ | A component renders empty | That's by design: pass your content props, or spread its fixture from `nexi-agent/demo`. |
757
+ | `Invalid hook call` / two copies of React | Make sure your app has a single React. With a linked local package, add `resolve: { dedupe: ["react", "react-dom"] }` to your Vite config. |
758
+ | Your app still shows old behaviour after reinstalling a `.tgz` | The version didn't change, so npm reused its cache. Delete `node_modules/nexi-agent` and install again. |
759
+ | `npm warn allow-scripts … nexi-agent (prepare: npm run build)` when installing from Git | Harmless: npm has already built the package while fetching it from GitHub. You don't need to approve the script. |
760
+ | `useToast must be used inside <ToastProvider>` | Wrap your app (or that part of it) in `<ToastProvider>`. |
761
+ | Fonts look different from the screenshots | Load Inter and JetBrains Mono (see [Fonts](#fonts-optional)). |
762
+ | `npm run build` fails on Windows | Use Node 20+ and run from the repo root. The build scripts are written to work on Windows. |
763
+
764
+ ---
765
+
766
+ ## 11. Credits and license
767
+
768
+ MIT © Kaaylabs.
769
+
770
+ The components are adapted from [Beautiful UI](https://www.beautifului.dev) © 2026
771
+ Shane Levine (MIT, see `LICENSE.beautiful-ui`), with shadow styles from
772
+ shadow-plugin © Florian Kiem (MIT).
773
+
774
+ **Changes from upstream:** all demo content moved out of the components into
775
+ `nexi-agent/demo`. Every component takes its text through props and `labels` and
776
+ reports actions through callbacks. The commercial icon set was replaced with free
777
+ `iconoir-react` icons, and global page styles were scoped to `.nexi`. Added:
778
+ `Avatar`, `Badge`, `Tooltip`, `NexiProvider`, `MessageThread`, `Markdown`,
779
+ `EmptyState`, `Dialog`, `ToastProvider`, `UsageMeter` and the playground.