@istmx/ui 0.1.12 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +533 -469
  3. package/bin/istmx.mjs +481 -318
  4. package/package.json +27 -27
  5. package/registry/accordion.tsx +186 -0
  6. package/registry/ai-chat-block/ai-chat-block.tsx +456 -460
  7. package/registry/ai-chat-block/ai-chat-input.tsx +694 -694
  8. package/registry/ai-chat-block/attachment.tsx +466 -466
  9. package/registry/ai-chat-block/chat-code-block.tsx +50 -50
  10. package/registry/ai-chat-block/chat-composer.tsx +51 -51
  11. package/registry/ai-chat-block/chat-logo.tsx +18 -18
  12. package/registry/ai-chat-block/chat-message.tsx +161 -161
  13. package/registry/ai-chat-block/chat-sidebar.tsx +273 -273
  14. package/registry/ai-chat-block/chat-user-avatar.tsx +9 -9
  15. package/registry/ai-chat-block/code-highlighter.tsx +342 -357
  16. package/registry/ai-chat-block/default-attachments.tsx +42 -42
  17. package/registry/ai-chat-block/index.ts +30 -30
  18. package/registry/ai-chat-block/message-content.tsx +287 -287
  19. package/registry/ai-chat-block/message-list.tsx +93 -93
  20. package/registry/ai-chat-block/send-button.tsx +102 -102
  21. package/registry/ai-chat-block/types.ts +70 -71
  22. package/registry/ai-chat-block/utils.ts +6 -6
  23. package/registry/ai-chat-block/voice-button.tsx +66 -66
  24. package/registry/alert-dialog.tsx +229 -0
  25. package/registry/alert.tsx +188 -0
  26. package/registry/animated-text.tsx +228 -225
  27. package/registry/aspect-ratio.tsx +32 -0
  28. package/registry/avatar-group.tsx +66 -0
  29. package/registry/avatar.tsx +121 -0
  30. package/registry/badge.tsx +52 -0
  31. package/registry/bento-grid.tsx +438 -433
  32. package/registry/button.tsx +156 -237
  33. package/registry/carousel.tsx +184 -0
  34. package/registry/dock-navigation.tsx +200 -198
  35. package/registry/drift-canvas.tsx +383 -0
  36. package/registry/drift-wall.tsx +361 -0
  37. package/registry/flex-carousel.tsx +1430 -0
  38. package/registry/guided-gallery.tsx +1506 -0
  39. package/registry/image-accordion.tsx +306 -302
  40. package/registry/image-trail.tsx +126 -121
  41. package/registry/infinite-image-canvas.tsx +268 -263
  42. package/registry/input-otp.tsx +332 -0
  43. package/registry/list-card.tsx +130 -0
  44. package/registry/mobile-menu-dock.tsx +216 -211
  45. package/registry/morph-slider.tsx +756 -0
  46. package/registry/pixel-cat.tsx +972 -1020
  47. package/registry/scroll-canvas-cards.tsx +643 -640
  48. package/registry/scroll-parallax-hero.tsx +566 -565
  49. package/registry/scroll-story-cards.tsx +443 -438
  50. package/registry/slider.tsx +163 -0
  51. package/registry/spotlight-grid.tsx +226 -0
  52. package/registry/streaming-text.tsx +269 -278
  53. package/registry/text-reveal.tsx +311 -307
  54. package/registry/user-avatar.tsx +99 -0
  55. package/registry/utils.ts +6 -6
package/README.md CHANGED
@@ -1,469 +1,533 @@
1
- # ISTMX UI
2
-
3
- Editable UI components for your codebase. ISTMX adds the component source to
4
- your project so you can read it, change it, and make it yours.
5
-
6
- **Website:** [aryanonai.vercel.app](https://aryanonai.vercel.app/)
7
-
8
- ## Add a component
9
-
10
- Run the command from your project root:
11
-
12
- ```sh
13
- npx @istmx/ui add animated-text
14
- ```
15
-
16
- Add the practical controls:
17
-
18
- ```sh
19
- npx @istmx/ui add button
20
- ```
21
-
22
- Or use your preferred package manager:
23
-
24
- ```sh
25
- pnpm dlx @istmx/ui add animated-text
26
- yarn dlx @istmx/ui add animated-text
27
- bunx @istmx/ui add animated-text
28
- ```
29
-
30
- Add the image stack component with:
31
-
32
- ```sh
33
- npx @istmx/ui add image-accordion
34
- ```
35
-
36
- Add the pointer-driven image trail with:
37
-
38
- ```sh
39
- npx @istmx/ui add image-trail
40
- ```
41
-
42
- Add the pannable infinite image canvas with:
43
-
44
- ```sh
45
- npx @istmx/ui add infinite-image-canvas
46
- ```
47
-
48
- Add the magnifying dock navigation with:
49
-
50
- ```sh
51
- npx @istmx/ui add dock-navigation
52
- ```
53
-
54
- Add the searchable mobile menu dock with:
55
-
56
- ```sh
57
- npx @istmx/ui add mobile-menu-dock
58
- ```
59
-
60
- Add the scroll-scrubbed image story with:
61
-
62
- ```sh
63
- npx @istmx/ui add scroll-story-cards
64
- ```
65
-
66
- Add the scroll parallax hero with:
67
-
68
- ```sh
69
- npx @istmx/ui add scroll-parallax-hero
70
- ```
71
-
72
- Add the scroll canvas cards with:
73
-
74
- ```sh
75
- npx @istmx/ui add scroll-canvas-cards
76
- ```
77
-
78
- Add the interactive pixel cat with:
79
-
80
- ```sh
81
- npx @istmx/ui add pixel-cat
82
- ```
83
-
84
- Add the streaming AI response text with:
85
-
86
- ```sh
87
- npx @istmx/ui add streaming-text
88
- ```
89
-
90
- Add the complete AI chat block with:
91
-
92
- ```sh
93
- npx @istmx/ui add ai-chat-block
94
- ```
95
-
96
- The CLI detects your package manager, copies the editable component to
97
- `components/ui/animated-text.tsx`, adds the shared `cn` helper at
98
- `lib/utils.ts` if it is missing, and installs any missing dependencies:
99
-
100
- - [Motion](https://motion.dev/) for animation
101
- - [clsx](https://www.npmjs.com/package/clsx) and [tailwind-merge](https://www.npmjs.com/package/tailwind-merge) for class composition
102
- - `@tabler/icons-react` for components that include Tabler icons
103
-
104
- Your project should already use React and have Tailwind CSS configured. After
105
- installation, the component is yours to edit; your app does not need to import
106
- runtime code from `@istmx/ui`.
107
-
108
- The `ai-chat-block` command is a multi-file install. It creates
109
- `components/ai-chat-block/`, including the block, input, sidebar, message,
110
- attachment, streaming, and local utility files. Its helper stays inside that
111
- folder, and the CLI installs any missing Motion, Tabler Icons, clsx, and
112
- tailwind-merge dependencies.
113
-
114
- ## Animated Text
115
-
116
- Import the copied source into your app:
117
-
118
- ```tsx
119
- import AnimatedText from '@/components/ui/animated-text'
120
-
121
- export function Intro() {
122
- return (
123
- <p>
124
- I&apos;m{' '}
125
- <AnimatedText
126
- items={['an AI engineer', 'a full-stack developer', 'a builder']}
127
- effects={['blur', 'fade', 'shimmer']}
128
- interval={2400}
129
- />
130
- </p>
131
- )
132
- }
133
- ```
134
-
135
- Available effects are `blur`, `fade`, `shimmer`, `slide`, and `wave`. Use the
136
- `effect` prop for one effect, or `effects` to combine several. The component
137
- respects the user's reduced-motion setting.
138
-
139
- ### Customize the text and shimmer
140
-
141
- Use `className` to style the wrapper and `textClassName` to style the changing
142
- text. For shimmer, set custom CSS colors with `effectOptions`:
143
-
144
- ```tsx
145
- <AnimatedText
146
- items={['an AI engineer', 'a builder']}
147
- effects={['blur', 'shimmer']}
148
- textClassName="font-semibold"
149
- effectOptions={{
150
- shimmer: {
151
- color: '#71717a',
152
- highlight: '#f4f4f5',
153
- duration: 2.2,
154
- width: 36,
155
- },
156
- }}
157
- />
158
- ```
159
-
160
- Other options include `direction`, `interval`, `speed`, `scale`, and effect
161
- settings for blur, fade, slide, and wave. The full component implementation is
162
- in your `components/ui/animated-text.tsx` file.
163
-
164
- ## Text Reveal
165
-
166
- Install the editable source with:
167
-
168
- ```sh
169
- npx @istmx/ui add text-reveal
170
- ```
171
-
172
- `TextReveal` reveals plain text line by line and character by character. It
173
- supports a viewport-triggered entrance by default, or reversible scroll-linked
174
- animation by passing a Motion value from `useScroll`.
175
-
176
- ```tsx
177
- import TextReveal from '@/components/ui/text-reveal'
178
-
179
- export function Quote() {
180
- return (
181
- <TextReveal
182
- text={'Every word arrives softly,\none character at a time.'}
183
- characterStagger={0.028}
184
- lineStagger={0.2}
185
- duration={0.65}
186
- waveDistance={8}
187
- waveOvershoot={6}
188
- sidewaysDistance={1.5}
189
- blurAmount={6}
190
- opacityFrom={0.08}
191
- opacityPeak={0.72}
192
- scaleFrom={0.96}
193
- scalePeak={1.025}
194
- />
195
- )
196
- }
197
- ```
198
-
199
- Tune `characterStagger`, `lineStagger`, `duration`, `waveDistance`,
200
- `waveOvershoot`, `sidewaysDistance`, `blurAmount`, opacity, and scale props to
201
- shape the reveal. The component keeps words together across natural line wraps
202
- and provides a single screen-reader text string.
203
-
204
- ## Streaming Text
205
-
206
- Install the editable source with:
207
-
208
- ```sh
209
- npx @istmx/ui add streaming-text
210
- ```
211
-
212
- `StreamingText` reveals a string character by character, like a model still
213
- writing its answer. Each new character settles in with a soft micro-interaction
214
- and an optional blinking caret marks the live cursor.
215
-
216
- ```tsx
217
- import StreamingText from '@/components/ui/streaming-text'
218
-
219
- export function Answer({ answer }) {
220
- return (
221
- <StreamingText
222
- text={answer}
223
- speed={42}
224
- effect="blur"
225
- cursor
226
- onComplete={() => console.log('streamed')}
227
- />
228
- )
229
- }
230
- ```
231
-
232
- Choose how characters enter with `effect`: `blur`, `fade`, `slide`, or a
233
- springy `wave`. Tune `speed` (characters per second), `startDelay`,
234
- `glyphDuration`, `blurAmount`, and `slideDistance`. Set `cursorAfterComplete`
235
- to keep the caret, or `loop` to re-stream with a `loopDelay` pause. The
236
- component announces the finished message once through a polite live region and
237
- renders the full string immediately under reduced motion.
238
-
239
- ## CLI options
240
-
241
- ```sh
242
- npx @istmx/ui add animated-text --no-install
243
- npx @istmx/ui add animated-text --overwrite
244
- npx @istmx/ui add button
245
- npx @istmx/ui add text-reveal
246
- npx @istmx/ui add streaming-text
247
- npx @istmx/ui add image-accordion
248
- npx @istmx/ui add image-trail
249
- npx @istmx/ui add infinite-image-canvas
250
- npx @istmx/ui add dock-navigation
251
- npx @istmx/ui add mobile-menu-dock
252
- npx @istmx/ui add pixel-cat
253
- npx @istmx/ui add ai-chat-block
254
- npx @istmx/ui add scroll-story-cards
255
- ```
256
-
257
- - `--no-install` copies the source and prints the dependency command instead
258
- of installing packages.
259
- - `--overwrite` replaces component and helper files that already exist.
260
-
261
- Component names accept either hyphens or spaces: `animated-text` or `animated
262
- text`.
263
-
264
- ## Scroll Story Cards
265
-
266
- The CLI copies an editable component to
267
- `components/ui/scroll-story-cards.tsx`. All cards wait in a separated preview
268
- dock at the bottom; it clears as soon as the story starts. Scrolling raises
269
- each narrower, shorter story panel through a shallow curve toward the hero
270
- center. Its portrait, larger copy, scene color, and Tabler CTA move together.
271
- The sequence reverses when scrolling backward, then releases directly into
272
- the following page content after the 400vh story timeline. The Library preview
273
- can be opened fullscreen to give the scroll scene room on smaller screens.
274
-
275
- ```tsx
276
- import ScrollStoryCards, {
277
- type ScrollStoryCard,
278
- } from '@/components/ui/scroll-story-cards'
279
-
280
- const cards: ScrollStoryCard[] = [
281
- {
282
- id: 'coast',
283
- eyebrow: 'South coast',
284
- title: 'The coast',
285
- description:
286
- 'Soft light settles across the frame while an open horizon leaves room for the story to unfold. The colors shift gently as this portrait approaches the center.',
287
- image: '/images/coast.jpg',
288
- imageAlt: 'A quiet coastline in late afternoon light',
289
- color: '#e8e0f4',
290
- overlayColor: '#cbbce5',
291
- overlayOpacity: 0.34,
292
- buttonLabel: 'Explore',
293
- buttonHref: '/coast',
294
- },
295
- {
296
- id: 'forest',
297
- title: 'The forest',
298
- description: 'A new palette carries the story forward.',
299
- image: '/images/forest.jpg',
300
- imageAlt: 'Sunlight moving through a green forest',
301
- color: '#e2eedf',
302
- overlayColor: '#b9d5ad',
303
- },
304
- ]
305
-
306
- export function Story() {
307
- return (
308
- <ScrollStoryCards
309
- cards={cards}
310
- eyebrow="Selected stories"
311
- heading="A collection worth exploring."
312
- description="Move through the frames by scrolling."
313
- curveAmount={64}
314
- cardWidth={156}
315
- cardHeight={156}
316
- overlayOpacity={0.38}
317
- scrollDistance={400}
318
- />
319
- )
320
- }
321
- ```
322
-
323
- `ScrollStoryCard` supports `id`, `title`, `description`, `image`, required
324
- `imageAlt`, and a hex `color` for the scene background. Optional fields are
325
- `overlayColor` (defaults to `color`), `overlayOpacity`, `buttonLabel`,
326
- `buttonHref`, and `buttonColor` (defaults to the overlay color). The component
327
- also accepts `className`, `curveAmount`, `cardWidth`, `cardHeight`,
328
- `overlayOpacity`, `scrollDistance`, `showCardLabels`, and an optional
329
- `scrollContainerRef` when the story lives inside a separately scrolling panel.
330
- Use at least two
331
- cards to see the continuous color and image transitions. The pinned story
332
- timeline defaults to 400vh and then releases naturally into the page. The
333
- moving panels are image-led, narrower, and use light pastel purple,
334
- green, yellow, blue, and pink scene colors. The CTA uses a Tabler arrow icon and
335
- subtle hover/press feedback. Reduced-motion preferences remove the lateral arc
336
- and extra scale and rotation while retaining the vertical scroll sequence.
337
- `onActiveChange` optionally reports which card is nearest the center; it does
338
- not control the scroll animation.
339
-
340
- ## Pixel Cat
341
-
342
- The CLI copies the interactive cat to `components/ui/pixel-cat.tsx`:
343
-
344
- ```tsx
345
- import { PixelCat } from '@/components/ui/pixel-cat'
346
-
347
- export function CatCard() {
348
- return (
349
- <div className="relative h-64 overflow-hidden rounded-xl border p-5">
350
- <PixelCat breed="orange" position="center" />
351
- </div>
352
- )
353
- }
354
- ```
355
-
356
- `PixelCat` supports `size`, `breed`, `palette`, `wandering`, `speed`,
357
- `boundary`, `position`, `initialPose`, `pose`, `interactive`,
358
- `cursorInteraction`, `messages`, `showBubble`, `onPet`, `onPoseChange`,
359
- `padding`, `className`, and `style`. The exported types
360
- The exports also include `PixelCatProps`, `PixelCatBreed`, `PixelCatPose`,
361
- `PixelCatPosition`, `CAT_PALETTES`, `CAT_SIZE`, and `CAT_FEET_Y`. It wanders
362
- within its parent by default; use a relatively positioned parent with a defined
363
- size. Fixed poses disable automatic pose cycling, and reduced-motion
364
- preferences pause movement.
365
-
366
- ## Image Accordion
367
-
368
- The CLI copies an editable component to `components/ui/image-accordion.tsx`.
369
- Pass any number of image objects; five are visible in the stack by default.
370
- Selecting an image animates it into the preview canvas, moves it to the end of
371
- the collection, and rotates the next image into the visible stack. Set
372
- `visibleCount` to change how many cards are shown.
373
-
374
- ```tsx
375
- import ImageAccordion from '@/components/ui/image-accordion'
376
-
377
- export function Gallery() {
378
- return (
379
- <ImageAccordion
380
- images={[
381
- { src: '/images/coast.jpg', alt: 'Coastal cliffs', title: 'The coast' },
382
- { src: '/images/forest.jpg', alt: 'A forest', title: 'The forest' },
383
- { src: '/images/city.jpg', alt: 'A city at dusk', title: 'The city' },
384
- { src: '/images/lake.jpg', alt: 'A mountain lake', title: 'The lake' },
385
- {
386
- src: '/images/desert.jpg',
387
- alt: 'A desert path',
388
- title: 'The desert',
389
- },
390
- { src: '/images/peaks.jpg', alt: 'Snowy peaks', title: 'The peaks' },
391
- ]}
392
- visibleCount={5}
393
- className="mx-auto max-w-5xl"
394
- cardClassName="rounded-lg"
395
- imageClassName="object-cover"
396
- glow={{ color: '#d4d4d8', opacity: 0.2, blur: 16 }}
397
- transition={{ stiffness: 190, damping: 24, mass: 0.8 }}
398
- />
399
- )
400
- }
401
- ```
402
-
403
- `ImageAccordionItem` supports `id`, `src`, `alt`, `title`, optional
404
- `description`, and per-card `className` and `imageClassName`. The component
405
- also accepts `stackClassName` and `previewClassName`; `glow={false}` disables
406
- the radial hover glow. Its spring, glow color/position/size/opacity/blur, and
407
- visible stack count are configurable. React, Motion, Tailwind CSS, `clsx`, and
408
- `tailwind-merge` are used; React and Tailwind CSS should already be configured
409
- in the consuming project.
410
-
411
- ## Dock Navigation
412
-
413
- Add the reusable, editable dock with:
414
-
415
- ```sh
416
- npx @istmx/ui add dock-navigation
417
- ```
418
-
419
- It writes `components/ui/dock-navigation.tsx` and installs any missing Motion,
420
- `clsx`, `tailwind-merge`, and `@tabler/icons-react` packages. The component
421
- accepts an array of labeled links and React icons. Nearby icons magnify and lift
422
- with an elastic spring; labels follow the movement, and an optional radial glow
423
- can be tuned or disabled.
424
-
425
- ```tsx
426
- import DockNavigation from '@/components/ui/dock-navigation'
427
- import {
428
- IconHome,
429
- IconUser,
430
- IconCode,
431
- IconComponents,
432
- IconMail,
433
- } from '@tabler/icons-react'
434
-
435
- const items = [
436
- { label: 'Home', href: '/', icon: <IconHome size={19} /> },
437
- { label: 'About', href: '/about', icon: <IconUser size={19} /> },
438
- {
439
- label: 'Projects',
440
- href: '/projects',
441
- icon: <IconCode size={19} />,
442
- },
443
- {
444
- label: 'Components',
445
- href: '/components',
446
- icon: <IconComponents size={19} />,
447
- active: true,
448
- },
449
- { label: 'Contact', href: '/contact', icon: <IconMail size={19} /> },
450
- ]
451
-
452
- export function SiteDock() {
453
- return (
454
- <DockNavigation
455
- items={items}
456
- label="Main navigation"
457
- glow={{ color: 'var(--foreground)', opacity: 0.2, blur: 12 }}
458
- />
459
- )
460
- }
461
- ```
462
-
463
- Each item takes `label`, `href`, and `icon` (`ReactNode`), with optional
464
- `active` and `external` flags. Pass custom classes through `className`,
465
- `itemClassName`, and `iconClassName`; set `glow={false}` to disable the glow.
466
- The component honors reduced-motion preferences.
467
-
468
- The CLI requires Node.js 18 or later. The npm package is `@istmx/ui`; the
469
- installed executable is named `istmx`.
1
+ # ISTMX UI
2
+
3
+ Editable UI components and AI Agent MCP integration for your codebase. ISTMX adds the component source directly to your project so you can read it, style it, and make it yours.
4
+
5
+ **Website:** [istmx-ui.vercel.app](https://istmx-ui.vercel.app/)
6
+
7
+ ## Connect AI Agents (OpenCode, Cursor, Claude)
8
+
9
+ Automatically configure OpenCode, Cursor, and Claude Code to search, inspect, and inject components directly into your codebase:
10
+
11
+ ```sh
12
+ npx @istmx/ui mcp connect
13
+ ```
14
+
15
+ Or connect in 1 second with your account email:
16
+
17
+ ```sh
18
+ npx @istmx/ui mcp connect --token=your-email@gmail.com
19
+ ```
20
+
21
+ ## Add a component
22
+
23
+ Run the command from your project root:
24
+
25
+ ```sh
26
+ npx @istmx/ui add button
27
+ npx @istmx/ui add input-otp
28
+ npx @istmx/ui add accordion
29
+ npx @istmx/ui add alert
30
+ npx @istmx/ui add alert-dialog
31
+ npx @istmx/ui add animated-text
32
+ ```
33
+
34
+ Or use your preferred package manager:
35
+
36
+ ```sh
37
+ pnpm dlx @istmx/ui add animated-text
38
+ yarn dlx @istmx/ui add animated-text
39
+ bunx @istmx/ui add animated-text
40
+ ```
41
+
42
+ Add the image stack component with:
43
+
44
+ ```sh
45
+ npx @istmx/ui add image-accordion
46
+ ```
47
+
48
+ Add the pointer-driven image trail with:
49
+
50
+ ```sh
51
+ npx @istmx/ui add image-trail
52
+ ```
53
+
54
+ Add the pannable infinite image canvas with:
55
+
56
+ ```sh
57
+ npx @istmx/ui add infinite-image-canvas
58
+ ```
59
+
60
+ Add the magnifying dock navigation with:
61
+
62
+ ```sh
63
+ npx @istmx/ui add dock-navigation
64
+ ```
65
+
66
+ Add the searchable mobile menu dock with:
67
+
68
+ ```sh
69
+ npx @istmx/ui add mobile-menu-dock
70
+ ```
71
+
72
+ Add the scroll-scrubbed image story with:
73
+
74
+ ```sh
75
+ npx @istmx/ui add scroll-story-cards
76
+ ```
77
+
78
+ Add the scroll parallax hero with:
79
+
80
+ ```sh
81
+ npx @istmx/ui add scroll-parallax-hero
82
+ ```
83
+
84
+ Add the scroll canvas cards with:
85
+
86
+ ```sh
87
+ npx @istmx/ui add scroll-canvas-cards
88
+ ```
89
+
90
+ Add the interactive pixel cat with:
91
+
92
+ ```sh
93
+ npx @istmx/ui add pixel-cat
94
+ ```
95
+
96
+ Add the streaming AI response text with:
97
+
98
+ ```sh
99
+ npx @istmx/ui add streaming-text
100
+ ```
101
+
102
+ Add the complete AI chat block with:
103
+
104
+ ```sh
105
+ npx @istmx/ui add ai-chat-block
106
+ ```
107
+
108
+ The CLI detects your package manager, copies the editable component to
109
+ `components/ui/animated-text.tsx`, adds the shared `cn` helper at
110
+ `lib/utils.ts` if it is missing, and installs any missing dependencies:
111
+
112
+ - [Motion](https://motion.dev/) for animation
113
+ - [clsx](https://www.npmjs.com/package/clsx) and [tailwind-merge](https://www.npmjs.com/package/tailwind-merge) for class composition
114
+ - `@tabler/icons-react` for components that include Tabler icons
115
+
116
+ Your project should already use React and have Tailwind CSS configured. After
117
+ installation, the component is yours to edit; your app does not need to import
118
+ runtime code from `@istmx/ui`.
119
+
120
+ The `ai-chat-block` command is a multi-file install. It creates
121
+ `components/ai-chat-block/`, including the block, input, sidebar, message,
122
+ attachment, streaming, and local utility files. Its helper stays inside that
123
+ folder, and the CLI installs any missing Motion, Tabler Icons, clsx, and
124
+ tailwind-merge dependencies.
125
+
126
+ ## Animated Text
127
+
128
+ Import the copied source into your app:
129
+
130
+ ```tsx
131
+ import AnimatedText from '@/components/ui/animated-text'
132
+
133
+ export function Intro() {
134
+ return (
135
+ <p>
136
+ I&apos;m{' '}
137
+ <AnimatedText
138
+ items={['an AI engineer', 'a full-stack developer', 'a builder']}
139
+ effects={['blur', 'fade', 'shimmer']}
140
+ interval={2400}
141
+ />
142
+ </p>
143
+ )
144
+ }
145
+ ```
146
+
147
+ Available effects are `blur`, `fade`, `shimmer`, `slide`, and `wave`. Use the
148
+ `effect` prop for one effect, or `effects` to combine several. The component
149
+ respects the user's reduced-motion setting.
150
+
151
+ ### Customize the text and shimmer
152
+
153
+ Use `className` to style the wrapper and `textClassName` to style the changing
154
+ text. For shimmer, set custom CSS colors with `effectOptions`:
155
+
156
+ ```tsx
157
+ <AnimatedText
158
+ items={['an AI engineer', 'a builder']}
159
+ effects={['blur', 'shimmer']}
160
+ textClassName="font-semibold"
161
+ effectOptions={{
162
+ shimmer: {
163
+ color: '#71717a',
164
+ highlight: '#f4f4f5',
165
+ duration: 2.2,
166
+ width: 36,
167
+ },
168
+ }}
169
+ />
170
+ ```
171
+
172
+ Other options include `direction`, `interval`, `speed`, `scale`, and effect
173
+ settings for blur, fade, slide, and wave. The full component implementation is
174
+ in your `components/ui/animated-text.tsx` file.
175
+
176
+ ## Text Reveal
177
+
178
+ Install the editable source with:
179
+
180
+ ```sh
181
+ npx @istmx/ui add text-reveal
182
+ ```
183
+
184
+ `TextReveal` reveals plain text line by line and character by character. It
185
+ supports a viewport-triggered entrance by default, or reversible scroll-linked
186
+ animation by passing a Motion value from `useScroll`.
187
+
188
+ ```tsx
189
+ import TextReveal from '@/components/ui/text-reveal'
190
+
191
+ export function Quote() {
192
+ return (
193
+ <TextReveal
194
+ text={'Every word arrives softly,\none character at a time.'}
195
+ characterStagger={0.028}
196
+ lineStagger={0.2}
197
+ duration={0.65}
198
+ waveDistance={8}
199
+ waveOvershoot={6}
200
+ sidewaysDistance={1.5}
201
+ blurAmount={6}
202
+ opacityFrom={0.08}
203
+ opacityPeak={0.72}
204
+ scaleFrom={0.96}
205
+ scalePeak={1.025}
206
+ />
207
+ )
208
+ }
209
+ ```
210
+
211
+ Tune `characterStagger`, `lineStagger`, `duration`, `waveDistance`,
212
+ `waveOvershoot`, `sidewaysDistance`, `blurAmount`, opacity, and scale props to
213
+ shape the reveal. The component keeps words together across natural line wraps
214
+ and provides a single screen-reader text string.
215
+
216
+ ## Streaming Text
217
+
218
+ Install the editable source with:
219
+
220
+ ```sh
221
+ npx @istmx/ui add streaming-text
222
+ ```
223
+
224
+ `StreamingText` reveals a string character by character, like a model still
225
+ writing its answer. Each new character settles in with a soft micro-interaction
226
+ and an optional blinking caret marks the live cursor.
227
+
228
+ ```tsx
229
+ import StreamingText from '@/components/ui/streaming-text'
230
+
231
+ export function Answer({ answer }) {
232
+ return (
233
+ <StreamingText
234
+ text={answer}
235
+ speed={42}
236
+ effect="blur"
237
+ cursor
238
+ onComplete={() => console.log('streamed')}
239
+ />
240
+ )
241
+ }
242
+ ```
243
+
244
+ Choose how characters enter with `effect`: `blur`, `fade`, `slide`, or a
245
+ springy `wave`. Tune `speed` (characters per second), `startDelay`,
246
+ `glyphDuration`, `blurAmount`, and `slideDistance`. Set `cursorAfterComplete`
247
+ to keep the caret, or `loop` to re-stream with a `loopDelay` pause. The
248
+ component announces the finished message once through a polite live region and
249
+ renders the full string immediately under reduced motion.
250
+
251
+ ## CLI options
252
+
253
+ ```sh
254
+ npx @istmx/ui add animated-text --no-install
255
+ npx @istmx/ui add animated-text --overwrite
256
+ npx @istmx/ui add button
257
+ npx @istmx/ui add text-reveal
258
+ npx @istmx/ui add streaming-text
259
+ npx @istmx/ui add image-accordion
260
+ npx @istmx/ui add image-trail
261
+ npx @istmx/ui add infinite-image-canvas
262
+ npx @istmx/ui add dock-navigation
263
+ npx @istmx/ui add mobile-menu-dock
264
+ npx @istmx/ui add pixel-cat
265
+ npx @istmx/ui add ai-chat-block
266
+ npx @istmx/ui add scroll-story-cards
267
+ ```
268
+
269
+ - `--no-install` copies the source and prints the dependency command instead
270
+ of installing packages.
271
+ - `--overwrite` replaces component and helper files that already exist.
272
+
273
+ Component names accept either hyphens or spaces: `animated-text` or `animated
274
+ text`.
275
+
276
+ ## Scroll Story Cards
277
+
278
+ The CLI copies an editable component to
279
+ `components/ui/scroll-story-cards.tsx`. All cards wait in a separated preview
280
+ dock at the bottom; it clears as soon as the story starts. Scrolling raises
281
+ each narrower, shorter story panel through a shallow curve toward the hero
282
+ center. Its portrait, larger copy, scene color, and Tabler CTA move together.
283
+ The sequence reverses when scrolling backward, then releases directly into
284
+ the following page content after the 400vh story timeline. The Library preview
285
+ can be opened fullscreen to give the scroll scene room on smaller screens.
286
+
287
+ ```tsx
288
+ import ScrollStoryCards, {
289
+ type ScrollStoryCard,
290
+ } from '@/components/ui/scroll-story-cards'
291
+
292
+ const cards: ScrollStoryCard[] = [
293
+ {
294
+ id: 'coast',
295
+ eyebrow: 'South coast',
296
+ title: 'The coast',
297
+ description:
298
+ 'Soft light settles across the frame while an open horizon leaves room for the story to unfold. The colors shift gently as this portrait approaches the center.',
299
+ image: '/images/coast.jpg',
300
+ imageAlt: 'A quiet coastline in late afternoon light',
301
+ color: '#e8e0f4',
302
+ overlayColor: '#cbbce5',
303
+ overlayOpacity: 0.34,
304
+ buttonLabel: 'Explore',
305
+ buttonHref: '/coast',
306
+ },
307
+ {
308
+ id: 'forest',
309
+ title: 'The forest',
310
+ description: 'A new palette carries the story forward.',
311
+ image: '/images/forest.jpg',
312
+ imageAlt: 'Sunlight moving through a green forest',
313
+ color: '#e2eedf',
314
+ overlayColor: '#b9d5ad',
315
+ },
316
+ ]
317
+
318
+ export function Story() {
319
+ return (
320
+ <ScrollStoryCards
321
+ cards={cards}
322
+ eyebrow="Selected stories"
323
+ heading="A collection worth exploring."
324
+ description="Move through the frames by scrolling."
325
+ curveAmount={64}
326
+ cardWidth={156}
327
+ cardHeight={156}
328
+ overlayOpacity={0.38}
329
+ scrollDistance={400}
330
+ />
331
+ )
332
+ }
333
+ ```
334
+
335
+ `ScrollStoryCard` supports `id`, `title`, `description`, `image`, required
336
+ `imageAlt`, and a hex `color` for the scene background. Optional fields are
337
+ `overlayColor` (defaults to `color`), `overlayOpacity`, `buttonLabel`,
338
+ `buttonHref`, and `buttonColor` (defaults to the overlay color). The component
339
+ also accepts `className`, `curveAmount`, `cardWidth`, `cardHeight`,
340
+ `overlayOpacity`, `scrollDistance`, `showCardLabels`, and an optional
341
+ `scrollContainerRef` when the story lives inside a separately scrolling panel.
342
+ Use at least two
343
+ cards to see the continuous color and image transitions. The pinned story
344
+ timeline defaults to 400vh and then releases naturally into the page. The
345
+ moving panels are image-led, narrower, and use light pastel purple,
346
+ green, yellow, blue, and pink scene colors. The CTA uses a Tabler arrow icon and
347
+ subtle hover/press feedback. Reduced-motion preferences remove the lateral arc
348
+ and extra scale and rotation while retaining the vertical scroll sequence.
349
+ `onActiveChange` optionally reports which card is nearest the center; it does
350
+ not control the scroll animation.
351
+
352
+ ## Pixel Cat
353
+
354
+ The CLI copies the interactive cat to `components/ui/pixel-cat.tsx`:
355
+
356
+ ```tsx
357
+ import { PixelCat } from '@/components/ui/pixel-cat'
358
+
359
+ export function CatCard() {
360
+ return (
361
+ <div className="relative h-64 overflow-hidden rounded-xl border p-5">
362
+ <PixelCat breed="orange" position="center" />
363
+ </div>
364
+ )
365
+ }
366
+ ```
367
+
368
+ `PixelCat` supports `size`, `breed`, `palette`, `wandering`, `speed`,
369
+ `boundary`, `position`, `initialPose`, `pose`, `interactive`,
370
+ `cursorInteraction`, `messages`, `showBubble`, `onPet`, `onPoseChange`,
371
+ `padding`, `className`, and `style`. The exported types
372
+ The exports also include `PixelCatProps`, `PixelCatBreed`, `PixelCatPose`,
373
+ `PixelCatPosition`, `CAT_PALETTES`, `CAT_SIZE`, and `CAT_FEET_Y`. It wanders
374
+ within its parent by default; use a relatively positioned parent with a defined
375
+ size. Fixed poses disable automatic pose cycling, and reduced-motion
376
+ preferences pause movement.
377
+
378
+ ## Image Accordion
379
+
380
+ The CLI copies an editable component to `components/ui/image-accordion.tsx`.
381
+ Pass any number of image objects; five are visible in the stack by default.
382
+ Selecting an image animates it into the preview canvas, moves it to the end of
383
+ the collection, and rotates the next image into the visible stack. Set
384
+ `visibleCount` to change how many cards are shown.
385
+
386
+ ```tsx
387
+ import ImageAccordion from '@/components/ui/image-accordion'
388
+
389
+ export function Gallery() {
390
+ return (
391
+ <ImageAccordion
392
+ images={[
393
+ { src: '/images/coast.jpg', alt: 'Coastal cliffs', title: 'The coast' },
394
+ { src: '/images/forest.jpg', alt: 'A forest', title: 'The forest' },
395
+ { src: '/images/city.jpg', alt: 'A city at dusk', title: 'The city' },
396
+ { src: '/images/lake.jpg', alt: 'A mountain lake', title: 'The lake' },
397
+ {
398
+ src: '/images/desert.jpg',
399
+ alt: 'A desert path',
400
+ title: 'The desert',
401
+ },
402
+ { src: '/images/peaks.jpg', alt: 'Snowy peaks', title: 'The peaks' },
403
+ ]}
404
+ visibleCount={5}
405
+ className="mx-auto max-w-5xl"
406
+ cardClassName="rounded-lg"
407
+ imageClassName="object-cover"
408
+ glow={{ color: '#d4d4d8', opacity: 0.2, blur: 16 }}
409
+ transition={{ stiffness: 190, damping: 24, mass: 0.8 }}
410
+ />
411
+ )
412
+ }
413
+ ```
414
+
415
+ `ImageAccordionItem` supports `id`, `src`, `alt`, `title`, optional
416
+ `description`, and per-card `className` and `imageClassName`. The component
417
+ also accepts `stackClassName` and `previewClassName`; `glow={false}` disables
418
+ the radial hover glow. Its spring, glow color/position/size/opacity/blur, and
419
+ visible stack count are configurable. React, Motion, Tailwind CSS, `clsx`, and
420
+ `tailwind-merge` are used; React and Tailwind CSS should already be configured
421
+ in the consuming project.
422
+
423
+ ## Guided Gallery
424
+
425
+ Install the focal-aware WebGL gallery with:
426
+
427
+ ```sh
428
+ npx @istmx/ui add guided-gallery
429
+ ```
430
+
431
+ Guided Gallery is an ISTMX adaptation of React Bits’ Flex Carousel. It adds
432
+ focal-aware image crops and per-image notes.
433
+
434
+ The CLI copies `components/ui/guided-gallery.tsx` and installs `ogl` and `torph`
435
+ when missing. Use the play button to start or pause automatic browsing, drag or
436
+ scroll the gallery to choose a slide, and pass a normalized `focalPoint` to
437
+ keep each image's subject in the crop. An optional `note` appears with the
438
+ active caption; captions and the slide count morph as they change.
439
+
440
+ ```tsx
441
+ import { GuidedGallery } from '@/components/ui/guided-gallery'
442
+
443
+ export function PortfolioGallery() {
444
+ return (
445
+ <div className="h-[480px]">
446
+ <GuidedGallery
447
+ items={[
448
+ {
449
+ src: '/images/portrait.jpg',
450
+ alt: 'Portrait in blue light',
451
+ title: 'Afterimage',
452
+ note: 'The focal point keeps the face in frame.',
453
+ focalPoint: { x: 0.42, y: 0.38 },
454
+ },
455
+ ]}
456
+ className="rounded-2xl"
457
+ preset="liquid"
458
+ autoplay
459
+ interval={1.5}
460
+ />
461
+ </div>
462
+ )
463
+ }
464
+ ```
465
+
466
+ `interval` is measured in seconds. The gallery also exposes item data, intro
467
+ and bend presets, card sizing, spacing, image fit and focal points, lens and
468
+ distortion controls, hover behavior, captions, wheel navigation, and
469
+ `onChange`/`onSelect` callbacks.
470
+
471
+ Focal coordinates run from `0` to `1`, measured from the image’s top-left
472
+ corner. `aspect` can override the source ratio when the card needs a fixed
473
+ shape. Keep the gallery inside a parent with a defined height.
474
+
475
+ ## Dock Navigation
476
+
477
+ Add the reusable, editable dock with:
478
+
479
+ ```sh
480
+ npx @istmx/ui add dock-navigation
481
+ ```
482
+
483
+ It writes `components/ui/dock-navigation.tsx` and installs any missing Motion,
484
+ `clsx`, `tailwind-merge`, and `@tabler/icons-react` packages. The component
485
+ accepts an array of labeled links and React icons. Nearby icons magnify and lift
486
+ with an elastic spring; labels follow the movement, and an optional radial glow
487
+ can be tuned or disabled.
488
+
489
+ ```tsx
490
+ import DockNavigation from '@/components/ui/dock-navigation'
491
+ import {
492
+ IconHome,
493
+ IconUser,
494
+ IconCode,
495
+ IconComponents,
496
+ IconMail,
497
+ } from '@tabler/icons-react'
498
+
499
+ const items = [
500
+ { label: 'Home', href: '/', icon: <IconHome size={19} /> },
501
+ { label: 'About', href: '/about', icon: <IconUser size={19} /> },
502
+ {
503
+ label: 'Projects',
504
+ href: '/projects',
505
+ icon: <IconCode size={19} />,
506
+ },
507
+ {
508
+ label: 'Components',
509
+ href: '/components',
510
+ icon: <IconComponents size={19} />,
511
+ active: true,
512
+ },
513
+ { label: 'Contact', href: '/contact', icon: <IconMail size={19} /> },
514
+ ]
515
+
516
+ export function SiteDock() {
517
+ return (
518
+ <DockNavigation
519
+ items={items}
520
+ label="Main navigation"
521
+ glow={{ color: 'var(--foreground)', opacity: 0.2, blur: 12 }}
522
+ />
523
+ )
524
+ }
525
+ ```
526
+
527
+ Each item takes `label`, `href`, and `icon` (`ReactNode`), with optional
528
+ `active` and `external` flags. Pass custom classes through `className`,
529
+ `itemClassName`, and `iconClassName`; set `glow={false}` to disable the glow.
530
+ The component honors reduced-motion preferences.
531
+
532
+ The CLI requires Node.js 18 or later. The npm package is `@istmx/ui`; the
533
+ installed executable is named `istmx`.