nexi-agent 0.1.0 → 0.1.1

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.
Files changed (2) hide show
  1. package/README.md +602 -604
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,604 +1,602 @@
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
- ```tsx
8
- <ThinkingState done="Thought for 3 seconds" rows={[{ primary: "Reading the ticket" }]} />
9
- <StreamingText content="The deploy failed because the API key expired." />
10
- <ApprovalCard questions={[{ q: "Rotate the key now?", type: "radio", options: ["Yes", "Later"] }]} />
11
- ```
12
-
13
- - **43 components:** all 33 from [Beautiful UI](https://www.beautifului.dev), plus 10
14
- more (chat thread, markdown, dialog, toast, avatar…).
15
- - **No hardcoded content.** Every word and every row comes from your props.
16
- - **Fully themeable** through CSS variables, with dark mode built in.
17
- - **Works in any React 18/19 app** (Vite, Next.js App Router, Remix, CRA). Tailwind
18
- is optional.
19
- - **TypeScript-first.** Every component, prop and data type is exported.
20
-
21
- ---
22
-
23
- ## Table of contents
24
-
25
- 1. [Quick start](#1-quick-start)
26
- 2. [Setup](#2-setup)
27
- 3. [What's inside](#3-whats-inside)
28
- 4. [How to use the components](#4-how-to-use-the-components)
29
- 5. [Recipes](#5-recipes)
30
- 6. [Customising](#6-customising)
31
- 7. [Working on this repo](#7-working-on-this-repo)
32
- 8. [Docker](#8-docker)
33
- 9. [Releasing](#9-releasing)
34
- 10. [Troubleshooting](#10-troubleshooting)
35
- 11. [Credits and license](#11-credits-and-license)
36
-
37
- ---
38
-
39
- ## 1. Quick start
40
-
41
- ```bash
42
- npm install github:abiramavarshini-kl/nexi-agent-component-package
43
- ```
44
-
45
- ```tsx
46
- // main.tsx (or your root layout)
47
- import "nexi-agent/styles.css";
48
- import { NexiProvider } from "nexi-agent";
49
-
50
- root.render(
51
- <NexiProvider>
52
- <App />
53
- </NexiProvider>,
54
- );
55
- ```
56
-
57
- ```tsx
58
- // anywhere inside
59
- import { StreamingText } from "nexi-agent";
60
-
61
- <StreamingText content="Hello! I'm your agent." />;
62
- ```
63
-
64
- That's all. To see every component with sample data first, run the
65
- [playground](#the-playground).
66
-
67
- ---
68
-
69
- ## 2. Setup
70
-
71
- ### Requirements
72
-
73
- - React **18 or 19** (`react` and `react-dom` are peer dependencies)
74
- - Node **20+** to build this repo (22 LTS recommended)
75
-
76
- ### Install
77
-
78
- | From | Command | When |
79
- | --- | --- | --- |
80
- | **Git** | `npm install github:abiramavarshini-kl/nexi-agent-component-package` (add `#main` or `#v0.1.0` to pin) | the normal way, until it's on npm. npm builds the package on install. |
81
- | **npm** | `npm install nexi-agent` | once it's published |
82
- | **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 |
83
-
84
- ### Styles: pick one
85
-
86
- | Your app | Add this | Result |
87
- | --- | --- | --- |
88
- | **No Tailwind** (or Tailwind v3) | `import "nexi-agent/styles.css";` once, at the root | precompiled CSS with everything the components need |
89
- | **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 |
90
-
91
- ### The provider
92
-
93
- Wrap your UI in `<NexiProvider>` once. It applies the font, text size and colour
94
- scope (the `.nexi` class) without touching the rest of your page.
95
-
96
- ```tsx
97
- <NexiProvider>…</NexiProvider> // light
98
- <NexiProvider dark>…</NexiProvider> // dark, for this subtree
99
- <NexiProvider contents>…</NexiProvider> // no wrapper box (display: contents)
100
- ```
101
-
102
- ### Fonts (optional)
103
-
104
- The design uses **Inter** and **JetBrains Mono**. Load them in your app (Google
105
- Fonts or `next/font`); otherwise the system fonts are used.
106
-
107
- ```html
108
- <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
109
- ```
110
-
111
- ### Next.js
112
-
113
- It works out of the box: the bundle is marked `"use client"`, so you can import
114
- components straight into App Router pages. Put the CSS import in `app/layout.tsx`.
115
-
116
- ---
117
-
118
- ## 3. What's inside
119
-
120
- ### Conversation
121
-
122
- | Component | What it shows |
123
- | --- | --- |
124
- | `MessageThread` / `Message` | the scrolling chat: user bubbles, agent turns that can hold any component, auto-scroll |
125
- | `StreamingText` | an answer revealed word by word, with inline citations, sources, action buttons and follow-ups |
126
- | `Markdown` | a formatted markdown answer (headings, lists, tables, code); safe, and works while text streams in |
127
- | `ChatComposer` | a compact chat panel with tabs, replies and an input |
128
- | `PromptBar` | a full input: `@` sources, `/` commands, model picker, attachments, dictation |
129
- | `SelectionActions` | highlight text → ask the agent to rewrite it → keep or discard |
130
-
131
- ### Agent activity
132
-
133
- | Component | What it shows |
134
- | --- | --- |
135
- | `ThinkingState` | an expandable reasoning trace (Steps · Reasoning · Search · Coding) |
136
- | `ToolChips` | tool calls as compact rows, plus file-diff chips |
137
- | `TaskRows` | tasks with running / failed / completed status |
138
- | `LoadingState` | a pixel loader with shimmering label and live timer |
139
- | `AgentScreen` | a live view of the agent's screen (image or video stream) |
140
- | `ContextCards` | retrieved document chunks (RAG) and their sources |
141
-
142
- ### Decisions
143
-
144
- | Component | What it shows |
145
- | --- | --- |
146
- | `ApprovalCard` | questions the user answers before the agent acts (human in the loop) |
147
- | `RecommendationCard` | a suggested action with a confidence meter and alternatives |
148
- | `DiffTable` | proposed row additions and removals the user can accept one by one |
149
- | `Dialog` | a confirm or small-form modal |
150
-
151
- ### Data
152
-
153
- | Component | What it shows |
154
- | --- | --- |
155
- | `RecordsTable` | a spreadsheet-style grid: tags, sorting, resizing, AI-calculated columns |
156
- | `FilterTable` | a table filtered by status chips |
157
- | `InsightCards` | a carousel of insights with live charts (`InsightCompareCard`, `InsightAnomalyCard`, `InsightAllocationCard` also work alone) |
158
- | `CodeBlock` | a code listing or unified diff, with copy |
159
- | `Flowchart` | a workflow canvas with draggable step and condition cards |
160
- | `UsageMeter` | tokens or credits used against a limit |
161
-
162
- ### App shell and feedback
163
-
164
- | Component | What it shows |
165
- | --- | --- |
166
- | `SidebarNav` | collapsible workspace switcher, navigation and chat history |
167
- | `SearchList` | a command search with live filtering |
168
- | `EmptyState` | "nothing here yet" or error panels |
169
- | `ToastProvider` / `useToast` | short notifications |
170
- | `FineTuneCard` | an inspector with draggable number fields |
171
- | `GlideMenu` | a menu with a gliding hover highlight |
172
-
173
- ### Atoms (small building blocks)
174
-
175
- `Avatar` · `Badge` · `Button` · `Chip` · `EntityChip` · `Monogram` ·
176
- `ProgressRing` · `SegmentedControl` · `Shimmer` · `StatusPill` · `StreamText` ·
177
- `Switch` · `TextRow` · `Tooltip` · `ValuePill` · `NexiProvider`
178
-
179
- ```tsx
180
- <Badge tone="green" dot>Completed</Badge>
181
- <Button variant="accent" size="sm">Run</Button>
182
- <StatusPill tone="orange">Running</StatusPill>
183
- <Avatar name="Maya Chen" src={photo} status="online" />
184
- <Tooltip content="Copy answer"><button>…</button></Tooltip>
185
- <SegmentedControl options={["Day", "Week"]} value={range} onChange={setRange} />
186
- ```
187
-
188
- ---
189
-
190
- ## 4. How to use the components
191
-
192
- Every component follows the same four conventions. Once you know them, you know
193
- the whole library.
194
-
195
- ### ① Content comes from props, and nothing is built in
196
-
197
- A component without props renders empty, never with placeholder text. Pass your
198
- data:
199
-
200
- ```tsx
201
- <TaskRows
202
- rows={[
203
- { key: "fetch", label: "Fetch invoices", amount: "42 files", status: "done", details: [] },
204
- { key: "match", label: "Match payments", amount: "38 rows", status: "running", step: 2, details: [] },
205
- ]}
206
- />
207
- ```
208
-
209
- ### ② UI words go in `labels`
210
-
211
- Button text, aria-labels and messages like "No results found" have English
212
- defaults. Override any of them, for wording or translation. Some are functions,
213
- so you can handle plurals:
214
-
215
- ```tsx
216
- <DiffTable
217
- rows={rows}
218
- labels={{
219
- apply: (n) => `Apply ${n} edit${n === 1 ? "" : "s"}`,
220
- toggleHint: "Click a row to include or exclude it",
221
- }}
222
- />
223
- ```
224
-
225
- ### ③ User actions come back as callbacks
226
-
227
- | Component | Callbacks |
228
- | --- | --- |
229
- | `PromptBar`, `ChatComposer` | `onSend(text, attachments)`, `onModelChange`, `onAttach(files)`, `onDictate()` |
230
- | `ApprovalCard` | `onSubmitted(answers)`, `onAnswerChange` |
231
- | `StreamingText` | `onFollowUp(text)`, `onAction(i)`, `onDone()` |
232
- | `SelectionActions` | `onAction(action)`: return the rewritten text (or a promise of it); `onKeep`, `onDiscard` |
233
- | `DiffTable` | `onApply(keptRows)` |
234
- | `RecommendationCard` | `onAccept(option)` |
235
- | `RecordsTable` | `onSelectionChange(ids)`, `onCalculate(column)` |
236
- | `SidebarNav` | `onNewChat`, `onPick(id)`, `onNavigate(key)`, `onWorkspaceMenu(key)` |
237
- | `Dialog` | `onConfirm()` (async is fine; return `false` to keep it open), `onOpenChange` |
238
- | `Flowchart` | `onConditionChange`, `onSelect` |
239
- | `Markdown` | `onLinkClick(href)`, `onCopyCode(code)` |
240
-
241
- ### ④ Sample data lives in `nexi-agent/demo`
242
-
243
- Each component has a ready-made fixture, which is useful for prototyping and for
244
- seeing what shape the props take:
245
-
246
- ```tsx
247
- import { RecordsTable } from "nexi-agent";
248
- import { recordsTableDemo } from "nexi-agent/demo";
249
-
250
- <RecordsTable {...recordsTableDemo} />;
251
- ```
252
-
253
- Fixture names are the component name in camelCase plus `Demo` (`approvalCardDemo`,
254
- `promptBarDemo`…). Read them in [`src/demo/`](src/demo). Nothing from `demo` reaches
255
- your bundle unless you import it.
256
-
257
- ### Types
258
-
259
- All props and data types are exported:
260
-
261
- ```ts
262
- import type { ApprovalQuestion, ToolStep, RecordRow, PromptBarProps, ThreadMessage } from "nexi-agent";
263
- ```
264
-
265
- ---
266
-
267
- ## 5. Recipes
268
-
269
- ### A complete chat screen
270
-
271
- ```tsx
272
- import { useState } from "react";
273
- import { EmptyState, LoadingState, Markdown, MessageThread, PromptBar, type ThreadMessage } from "nexi-agent";
274
-
275
- export function Chat() {
276
- const [messages, setMessages] = useState<ThreadMessage[]>([]);
277
- const [busy, setBusy] = useState(false);
278
-
279
- const send = async (text: string) => {
280
- setMessages((m) => [...m, { id: crypto.randomUUID(), role: "user", content: text }]);
281
- setBusy(true);
282
- const reply = await askAgent(text); // your API
283
- setMessages((m) => [...m, { id: crypto.randomUUID(), role: "assistant", name: "Agent", content: <Markdown content={reply} /> }]);
284
- setBusy(false);
285
- };
286
-
287
- return (
288
- <div style={{ display: "flex", flexDirection: "column", height: "100vh", maxWidth: 720, margin: "0 auto" }}>
289
- <MessageThread
290
- className="flex-1"
291
- messages={messages}
292
- empty={<EmptyState title="Ask anything" description="Answers show up here." />}
293
- footer={busy && <LoadingState label="Thinking" />}
294
- />
295
- <PromptBar onSend={send} placeholder="Message the agent…" />
296
- </div>
297
- );
298
- }
299
- ```
300
-
301
- ### Streaming an answer as it arrives
302
-
303
- Keep appending to a string. Both `Markdown` and `StreamingText` handle partial
304
- text.
305
-
306
- ```tsx
307
- const [answer, setAnswer] = useState("");
308
-
309
- const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ prompt }) });
310
- const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
311
- for (;;) {
312
- const { value, done } = await reader.read();
313
- if (done) break;
314
- setAnswer((a) => a + value);
315
- }
316
-
317
- <Markdown content={answer} />; // formatted
318
- <StreamingText content={answer} fill />; // word-by-word reveal + sources / follow-ups
319
- ```
320
-
321
- ### Showing the agent's work
322
-
323
- ```tsx
324
- <ThinkingState
325
- variant="Steps"
326
- active="Working"
327
- done="Finished in 6s"
328
- rows={steps.map((s) => ({ primary: s.title, secondary: s.detail }))}
329
- />
330
-
331
- <ToolChips
332
- steps={[
333
- { icon: "read", label: "Read file", chip: "invoices.csv", mono: true, detail: [{ text: "1,204 rows" }] },
334
- { icon: "run", label: "Run", chip: "npm test", mono: true, detail: [{ text: "✓ 34 passed" }] },
335
- ]}
336
- />
337
- ```
338
-
339
- ### Asking before acting
340
-
341
- ```tsx
342
- <ApprovalCard
343
- questions={[
344
- { q: "Send the reminder emails?", type: "radio", options: ["Send now", "Schedule for 9am"] },
345
- { q: "Who should get them?", type: "check", options: ["Overdue", "Due this week"] },
346
- ]}
347
- onSubmitted={(answers) => agent.resume(answers)}
348
- />
349
- ```
350
-
351
- ### Confirm and notify
352
-
353
- ```tsx
354
- // once, near the root
355
- <ToastProvider>
356
- <App />
357
- </ToastProvider>
358
-
359
- // in any component
360
- const { toast } = useToast();
361
- const [open, setOpen] = useState(false);
362
-
363
- <Dialog
364
- open={open}
365
- onOpenChange={setOpen}
366
- title="Delete this run?"
367
- description="Its logs and outputs will be removed."
368
- destructive
369
- labels={{ confirm: "Delete" }}
370
- onConfirm={async () => {
371
- await deleteRun(id);
372
- toast({ title: "Run deleted", tone: "success" });
373
- }}
374
- />
375
- ```
376
-
377
- ---
378
-
379
- ## 6. Customising
380
-
381
- ### Colours
382
-
383
- Every colour is a CSS variable. Override them globally or for any section:
384
-
385
- ```css
386
- :root {
387
- --accent: oklch(0.58 0.22 300); /* buttons, links, focus */
388
- --accent-ink: oklch(0.5 0.2 300); /* accent-coloured text */
389
- --accent-tint: oklch(0.95 0.03 300); /* soft accent backgrounds */
390
- }
391
-
392
- .billing { --accent: #0f9d58; } /* only inside .billing */
393
- ```
394
-
395
- | Token | Controls |
396
- | --- | --- |
397
- | `--page` `--canvas` `--surface` `--inset` `--field` | backgrounds, from the page down to inputs |
398
- | `--ink` `--ink-2` `--ink-3` | text: primary, secondary, muted |
399
- | `--line` `--line-strong` | borders and dividers |
400
- | `--accent` `--green` `--orange` `--red` (+ `-tint`) | brand and status colours |
401
- | `--tooltip-bg` `--tooltip-fg` | tooltips and chart labels |
402
-
403
- ### Dark mode
404
-
405
- Use `<NexiProvider dark>`, or put `class="dark"` on `<html>` to follow your app's
406
- own theme switch.
407
-
408
- ### Size and spacing
409
-
410
- - Most components accept `className` for margins, width and positioning.
411
- - Cards have a sensible maximum width (about 320–440px); wrap them to size them.
412
- `RecordsTable`, `SidebarNav` and `StreamingText` also accept `fill` to take the
413
- parent's size.
414
- - Atoms take `size` / `tone` / `variant`: `<Badge size="sm" tone="red" variant="outline">`,
415
- `<Button size="xs" variant="quiet">`, `<Avatar size="lg" square>`.
416
-
417
- ### Wording and language
418
-
419
- Use the `labels` prop on any component (see [②](#-ui-words-go-in-labels)).
420
-
421
- ---
422
-
423
- ## 7. Working on this repo
424
-
425
- ### Get going
426
-
427
- ```bash
428
- git clone https://github.com/abiramavarshini-kl/nexi-agent-component-package.git nexi-agent
429
- cd nexi-agent
430
- npm install # installs and builds dist/
431
- npm run playground # opens the docs site at http://localhost:5173
432
- ```
433
-
434
- ### Scripts
435
-
436
- | Command | What it does |
437
- | --- | --- |
438
- | `npm run build` | builds `dist/`: ESM + CJS bundles, type files, `styles.css`, `tailwind.css` |
439
- | `npm test` | builds, then renders every component twice: empty, and with demo data |
440
- | `npm run typecheck` | runs the TypeScript checks |
441
- | `npm run playground` | builds, then starts the playground dev server |
442
- | `npm pack` | creates the `.tgz` file to test-install in another app |
443
-
444
- ### The playground (docs site)
445
-
446
- [`playground/`](playground) is the public docs site: a Vite app with a page per
447
- component (live preview, copyable code, sample data and a props table), an
448
- introduction, an all-on-one-page gallery at `/all`, and dark mode. It uses the
449
- built `dist/`, so after editing `src/`, run `npm run build` and the site updates.
450
-
451
- - **Examples:** `playground/src/examples/<Name>.tsx`. Each file is rendered as the
452
- preview *and* shown as the code, so the two can't disagree.
453
- - **Page list and descriptions:** `playground/src/registry.ts`.
454
- - **Props tables:** generated from the TypeScript source by
455
- `playground/scripts/make-props.mjs` on every `dev`/`build`. Write a `/** comment */`
456
- above a prop and it shows up as the description.
457
-
458
- ### Deploying the docs site (Vercel)
459
-
460
- [`vercel.json`](vercel.json) holds the whole setup, so there's nothing to configure
461
- in the dashboard:
462
-
463
- 1. On [vercel.com](https://vercel.com), **Add New → Project** and import this GitHub
464
- repository.
465
- 2. Leave **Root Directory** as the repo root and the framework preset as **Other**
466
- (`vercel.json` sets the install, build and output commands). Click **Deploy**.
467
- 3. Every push to `main` redeploys the site. Every other branch and pull request gets
468
- its own preview URL.
469
-
470
- To use your own domain, go to **Project → Settings → Domains**.
471
-
472
- To check a deploy locally first: `npm run build && npm --prefix playground run build && npm --prefix playground run preview`.
473
-
474
- ### Day-to-day workflow
475
-
476
- ```bash
477
- # 1. edit src/…
478
- npm test # 2. build + check every component renders
479
- git add -A && git commit -m "…"
480
- git push # dist/ and .tgz files are git-ignored; no packing needed
481
- ```
482
-
483
- You only need `npm pack` to try the package in a separate app.
484
-
485
- ### Project structure
486
-
487
- ```
488
- src/
489
- atoms/ small building blocks (Badge, Button, Avatar, Tooltip…)
490
- primitives/ the main components (ApprovalCard, PromptBar, MessageThread…)
491
- provider/ NexiProvider
492
- demo/ sample data for every component → "nexi-agent/demo"
493
- lib/ cn() class helper, icon shims
494
- styles/ foundation.css: design tokens, theme, animations
495
- index.ts generated export list (don't edit by hand)
496
- scripts/
497
- make-index.mjs regenerates src/index.ts on every build
498
- build-css.mjs builds dist/styles.css and dist/tailwind.css
499
- make-foundation.py regenerates foundation.css from upstream Beautiful UI
500
- test/smoke.test.tsx render test for every component
501
- playground/ the docs site, deployed to Vercel (not published to npm)
502
- vercel.json Vercel build settings for the docs site
503
- ```
504
-
505
- ### Adding a component
506
-
507
- 1. Create `src/primitives/MyThing.tsx` with `export default function MyThing(props)`,
508
- or `src/atoms/MyThing.tsx` with a named export.
509
- 2. Follow the conventions: content props default to empty, UI words go in
510
- `labels`, user actions go out through callbacks, the outer element accepts
511
- `className`, and you export a `MyThingProps` type.
512
- 3. Add `src/demo/MyThing.ts` exporting `myThingDemo`, and re-export it from
513
- `src/demo/index.ts`.
514
- 4. Add `playground/src/examples/MyThing.tsx` (a default-exported example) and a row
515
- in `playground/src/registry.ts`. It gets its own docs page.
516
- 5. Run `npm test`. The export list regenerates automatically, and the test fails
517
- if the component has no demo fixture or crashes.
518
-
519
- ---
520
-
521
- ## 8. Docker
522
-
523
- Docker builds and tests the library, then serves the playground. You don't need
524
- Node on the host.
525
-
526
- ```bash
527
- docker compose up --build playground # nginx gallery → http://localhost:8080
528
- docker compose up -d --build playground # same, in the background
529
- docker compose down # stop
530
-
531
- docker compose --profile dev up --build dev # Vite dev server → http://localhost:5173
532
- ```
533
-
534
- Without Compose:
535
-
536
- ```bash
537
- docker build -t nexi-agent-playground .
538
- docker run --rm -p 8080:80 nexi-agent-playground # → http://localhost:8080
539
-
540
- docker build --target test -t nexi-agent-test . # build + smoke test only
541
- ```
542
-
543
- | Dockerfile stage | Purpose |
544
- | --- | --- |
545
- | `deps` | installs dependencies |
546
- | `build` | builds `dist/` |
547
- | `test` | runs the smoke test (the build fails if a component breaks) |
548
- | `dev` | playground dev server |
549
- | `playground` | builds the playground as static files |
550
- | `web` *(default)* | nginx serving the playground on port 80 |
551
-
552
- ---
553
-
554
- ## 9. Releasing
555
-
556
- **Via Git** (what teammates install with `npm install github:abiramavarshini-kl/nexi-agent-component-package`):
557
-
558
- ```bash
559
- npm version patch # 0.1.0 → 0.1.1; use minor / major for bigger changes
560
- git push --follow-tags # teammates pin with github:abiramavarshini-kl/nexi-agent-component-package#v0.1.1
561
- ```
562
-
563
- **Via npm:**
564
-
565
- ```bash
566
- npm login
567
- npm publish # runs typecheck + build first
568
- # scoped to your organisation: set "name": "@kaaylabs/nexi-agent", then
569
- npm publish --access public # or --access restricted (paid npm plan)
570
- ```
571
-
572
- A version number can't be published twice. Bump it with `npm version` each time.
573
-
574
- ---
575
-
576
- ## 10. Troubleshooting
577
-
578
- | Problem | Fix |
579
- | --- | --- |
580
- | Components appear unstyled | Import `nexi-agent/styles.css` once at the root (or `tailwind.css` for Tailwind v4 apps). |
581
- | A component renders empty | That's by design: pass your content props, or spread its fixture from `nexi-agent/demo`. |
582
- | `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. |
583
- | 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. |
584
- | `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. |
585
- | `useToast must be used inside <ToastProvider>` | Wrap your app (or that part of it) in `<ToastProvider>`. |
586
- | Fonts look different from the screenshots | Load Inter and JetBrains Mono (see [Fonts](#fonts-optional)). |
587
- | `npm run build` fails on Windows | Use Node 20+ and run from the repo root. The build scripts are written to work on Windows. |
588
-
589
- ---
590
-
591
- ## 11. Credits and license
592
-
593
- MIT © Kaaylabs.
594
-
595
- The components are adapted from [Beautiful UI](https://www.beautifului.dev) © 2026
596
- Shane Levine (MIT, see `LICENSE.beautiful-ui`), with shadow styles from
597
- shadow-plugin © Florian Kiem (MIT).
598
-
599
- **Changes from upstream:** all demo content moved out of the components into
600
- `nexi-agent/demo`. Every component takes its text through props and `labels` and
601
- reports actions through callbacks. The commercial icon set was replaced with free
602
- `iconoir-react` icons, and global page styles were scoped to `.nexi`. Added:
603
- `Avatar`, `Badge`, `Tooltip`, `NexiProvider`, `MessageThread`, `Markdown`,
604
- `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: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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nexi-agent",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "React components for AI-agent interfaces — streaming answers, thinking traces, approvals, tool calls, tables and more. Every component is content-free: pass your own data and text through props. Built on Beautiful UI.",
5
5
  "license": "MIT",
6
6
  "author": "Kaaylabs",
@@ -8,7 +8,7 @@
8
8
  "type": "git",
9
9
  "url": "git+https://github.com/abiramavarshini-kl/nexi-agent-component-package.git"
10
10
  },
11
- "homepage": "https://github.com/abiramavarshini-kl/nexi-agent-component-package#readme",
11
+ "homepage": "https://nexi-agent-component-package.vercel.app",
12
12
  "bugs": {
13
13
  "url": "https://github.com/abiramavarshini-kl/nexi-agent-component-package/issues"
14
14
  },