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 +779 -602
- package/dist/{chunk-XDNSQ2Q7.js → chunk-LAE5NL7J.js} +284 -4
- package/dist/chunk-LAE5NL7J.js.map +1 -0
- package/dist/demo.cjs +1682 -10
- package/dist/demo.cjs.map +1 -1
- package/dist/demo.d.cts +699 -1
- package/dist/demo.d.ts +699 -1
- package/dist/demo.js +1471 -2
- package/dist/demo.js.map +1 -1
- package/dist/index.cjs +8423 -122
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1703 -3
- package/dist/index.d.ts +1703 -3
- package/dist/index.js +8051 -110
- package/dist/index.js.map +1 -1
- package/dist/styles.css +1 -1
- package/dist/tailwind.css +689 -0
- package/package.json +3 -3
- package/dist/chunk-XDNSQ2Q7.js.map +0 -1
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:
|
|
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
|
-
###
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
`
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
the
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
|
230
|
-
|
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
| `
|
|
234
|
-
| `
|
|
235
|
-
| `
|
|
236
|
-
| `
|
|
237
|
-
| `
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
`
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
---
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
<
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
|
398
|
-
|
|
|
399
|
-
|
|
|
400
|
-
|
|
|
401
|
-
|
|
|
402
|
-
|
|
|
403
|
-
|
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
###
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
```
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
---
|
|
555
|
-
|
|
556
|
-
##
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
|
577
|
-
|
|
|
578
|
-
|
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
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
|
+
**[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.
|