@istmx/ui 0.1.11 → 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 -463
  3. package/bin/istmx.mjs +481 -314
  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 -0
  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,463 +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 interactive pixel cat with:
73
-
74
- ```sh
75
- npx @istmx/ui add pixel-cat
76
- ```
77
-
78
- Add the streaming AI response text with:
79
-
80
- ```sh
81
- npx @istmx/ui add streaming-text
82
- ```
83
-
84
- Add the complete AI chat block with:
85
-
86
- ```sh
87
- npx @istmx/ui add ai-chat-block
88
- ```
89
-
90
- The CLI detects your package manager, copies the editable component to
91
- `components/ui/animated-text.tsx`, adds the shared `cn` helper at
92
- `lib/utils.ts` if it is missing, and installs any missing dependencies:
93
-
94
- - [Motion](https://motion.dev/) for animation
95
- - [clsx](https://www.npmjs.com/package/clsx) and [tailwind-merge](https://www.npmjs.com/package/tailwind-merge) for class composition
96
- - `@tabler/icons-react` for components that include Tabler icons
97
-
98
- Your project should already use React and have Tailwind CSS configured. After
99
- installation, the component is yours to edit; your app does not need to import
100
- runtime code from `@istmx/ui`.
101
-
102
- The `ai-chat-block` command is a multi-file install. It creates
103
- `components/ai-chat-block/`, including the block, input, sidebar, message,
104
- attachment, streaming, and local utility files. Its helper stays inside that
105
- folder, and the CLI installs any missing Motion, Tabler Icons, clsx, and
106
- tailwind-merge dependencies.
107
-
108
- ## Animated Text
109
-
110
- Import the copied source into your app:
111
-
112
- ```tsx
113
- import AnimatedText from '@/components/ui/animated-text'
114
-
115
- export function Intro() {
116
- return (
117
- <p>
118
- I&apos;m{' '}
119
- <AnimatedText
120
- items={['an AI engineer', 'a full-stack developer', 'a builder']}
121
- effects={['blur', 'fade', 'shimmer']}
122
- interval={2400}
123
- />
124
- </p>
125
- )
126
- }
127
- ```
128
-
129
- Available effects are `blur`, `fade`, `shimmer`, `slide`, and `wave`. Use the
130
- `effect` prop for one effect, or `effects` to combine several. The component
131
- respects the user's reduced-motion setting.
132
-
133
- ### Customize the text and shimmer
134
-
135
- Use `className` to style the wrapper and `textClassName` to style the changing
136
- text. For shimmer, set custom CSS colors with `effectOptions`:
137
-
138
- ```tsx
139
- <AnimatedText
140
- items={['an AI engineer', 'a builder']}
141
- effects={['blur', 'shimmer']}
142
- textClassName="font-semibold"
143
- effectOptions={{
144
- shimmer: {
145
- color: '#71717a',
146
- highlight: '#f4f4f5',
147
- duration: 2.2,
148
- width: 36,
149
- },
150
- }}
151
- />
152
- ```
153
-
154
- Other options include `direction`, `interval`, `speed`, `scale`, and effect
155
- settings for blur, fade, slide, and wave. The full component implementation is
156
- in your `components/ui/animated-text.tsx` file.
157
-
158
- ## Text Reveal
159
-
160
- Install the editable source with:
161
-
162
- ```sh
163
- npx @istmx/ui add text-reveal
164
- ```
165
-
166
- `TextReveal` reveals plain text line by line and character by character. It
167
- supports a viewport-triggered entrance by default, or reversible scroll-linked
168
- animation by passing a Motion value from `useScroll`.
169
-
170
- ```tsx
171
- import TextReveal from '@/components/ui/text-reveal'
172
-
173
- export function Quote() {
174
- return (
175
- <TextReveal
176
- text={'Every word arrives softly,\none character at a time.'}
177
- characterStagger={0.028}
178
- lineStagger={0.2}
179
- duration={0.65}
180
- waveDistance={8}
181
- waveOvershoot={6}
182
- sidewaysDistance={1.5}
183
- blurAmount={6}
184
- opacityFrom={0.08}
185
- opacityPeak={0.72}
186
- scaleFrom={0.96}
187
- scalePeak={1.025}
188
- />
189
- )
190
- }
191
- ```
192
-
193
- Tune `characterStagger`, `lineStagger`, `duration`, `waveDistance`,
194
- `waveOvershoot`, `sidewaysDistance`, `blurAmount`, opacity, and scale props to
195
- shape the reveal. The component keeps words together across natural line wraps
196
- and provides a single screen-reader text string.
197
-
198
- ## Streaming Text
199
-
200
- Install the editable source with:
201
-
202
- ```sh
203
- npx @istmx/ui add streaming-text
204
- ```
205
-
206
- `StreamingText` reveals a string character by character, like a model still
207
- writing its answer. Each new character settles in with a soft micro-interaction
208
- and an optional blinking caret marks the live cursor.
209
-
210
- ```tsx
211
- import StreamingText from '@/components/ui/streaming-text'
212
-
213
- export function Answer({ answer }) {
214
- return (
215
- <StreamingText
216
- text={answer}
217
- speed={42}
218
- effect="blur"
219
- cursor
220
- onComplete={() => console.log('streamed')}
221
- />
222
- )
223
- }
224
- ```
225
-
226
- Choose how characters enter with `effect`: `blur`, `fade`, `slide`, or a
227
- springy `wave`. Tune `speed` (characters per second), `startDelay`,
228
- `glyphDuration`, `blurAmount`, and `slideDistance`. Set `cursorAfterComplete`
229
- to keep the caret, or `loop` to re-stream with a `loopDelay` pause. The
230
- component announces the finished message once through a polite live region and
231
- renders the full string immediately under reduced motion.
232
-
233
- ## CLI options
234
-
235
- ```sh
236
- npx @istmx/ui add animated-text --no-install
237
- npx @istmx/ui add animated-text --overwrite
238
- npx @istmx/ui add button
239
- npx @istmx/ui add text-reveal
240
- npx @istmx/ui add streaming-text
241
- npx @istmx/ui add image-accordion
242
- npx @istmx/ui add image-trail
243
- npx @istmx/ui add infinite-image-canvas
244
- npx @istmx/ui add dock-navigation
245
- npx @istmx/ui add mobile-menu-dock
246
- npx @istmx/ui add pixel-cat
247
- npx @istmx/ui add ai-chat-block
248
- npx @istmx/ui add scroll-story-cards
249
- ```
250
-
251
- - `--no-install` copies the source and prints the dependency command instead
252
- of installing packages.
253
- - `--overwrite` replaces component and helper files that already exist.
254
-
255
- Component names accept either hyphens or spaces: `animated-text` or `animated
256
- text`.
257
-
258
- ## Scroll Story Cards
259
-
260
- The CLI copies an editable component to
261
- `components/ui/scroll-story-cards.tsx`. All cards wait in a separated preview
262
- dock at the bottom; it clears as soon as the story starts. Scrolling raises
263
- each narrower, shorter story panel through a shallow curve toward the hero
264
- center. Its portrait, larger copy, scene color, and Tabler CTA move together.
265
- The sequence reverses when scrolling backward, then releases directly into
266
- the following page content after the 400vh story timeline. The Library preview
267
- can be opened fullscreen to give the scroll scene room on smaller screens.
268
-
269
- ```tsx
270
- import ScrollStoryCards, {
271
- type ScrollStoryCard,
272
- } from '@/components/ui/scroll-story-cards'
273
-
274
- const cards: ScrollStoryCard[] = [
275
- {
276
- id: 'coast',
277
- eyebrow: 'South coast',
278
- title: 'The coast',
279
- description:
280
- '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.',
281
- image: '/images/coast.jpg',
282
- imageAlt: 'A quiet coastline in late afternoon light',
283
- color: '#e8e0f4',
284
- overlayColor: '#cbbce5',
285
- overlayOpacity: 0.34,
286
- buttonLabel: 'Explore',
287
- buttonHref: '/coast',
288
- },
289
- {
290
- id: 'forest',
291
- title: 'The forest',
292
- description: 'A new palette carries the story forward.',
293
- image: '/images/forest.jpg',
294
- imageAlt: 'Sunlight moving through a green forest',
295
- color: '#e2eedf',
296
- overlayColor: '#b9d5ad',
297
- },
298
- ]
299
-
300
- export function Story() {
301
- return (
302
- <ScrollStoryCards
303
- cards={cards}
304
- eyebrow="Selected stories"
305
- heading="A collection worth exploring."
306
- description="Move through the frames by scrolling."
307
- curveAmount={64}
308
- cardWidth={156}
309
- cardHeight={156}
310
- overlayOpacity={0.38}
311
- scrollDistance={400}
312
- />
313
- )
314
- }
315
- ```
316
-
317
- `ScrollStoryCard` supports `id`, `title`, `description`, `image`, required
318
- `imageAlt`, and a hex `color` for the scene background. Optional fields are
319
- `overlayColor` (defaults to `color`), `overlayOpacity`, `buttonLabel`,
320
- `buttonHref`, and `buttonColor` (defaults to the overlay color). The component
321
- also accepts `className`, `curveAmount`, `cardWidth`, `cardHeight`,
322
- `overlayOpacity`, `scrollDistance`, `showCardLabels`, and an optional
323
- `scrollContainerRef` when the story lives inside a separately scrolling panel.
324
- Use at least two
325
- cards to see the continuous color and image transitions. The pinned story
326
- timeline defaults to 400vh and then releases naturally into the page. The
327
- moving panels are image-led, narrower, and use light pastel purple,
328
- green, yellow, blue, and pink scene colors. The CTA uses a Tabler arrow icon and
329
- subtle hover/press feedback. Reduced-motion preferences remove the lateral arc
330
- and extra scale and rotation while retaining the vertical scroll sequence.
331
- `onActiveChange` optionally reports which card is nearest the center; it does
332
- not control the scroll animation.
333
-
334
- ## Pixel Cat
335
-
336
- The CLI copies the interactive cat to `components/ui/pixel-cat.tsx`:
337
-
338
- ```tsx
339
- import { PixelCat } from '@/components/ui/pixel-cat'
340
-
341
- export function CatCard() {
342
- return (
343
- <div className="relative h-64 overflow-hidden rounded-xl border p-5">
344
- <PixelCat breed="orange" position="center" />
345
- </div>
346
- )
347
- }
348
- ```
349
-
350
- `PixelCat` supports `size`, `breed`, `palette`, `wandering`, `speed`,
351
- `boundary`, `position`, `initialPose`, `pose`, `interactive`,
352
- `cursorInteraction`, `messages`, `showBubble`, `onPet`, `onPoseChange`,
353
- `padding`, `className`, and `style`. The exported types
354
- The exports also include `PixelCatProps`, `PixelCatBreed`, `PixelCatPose`,
355
- `PixelCatPosition`, `CAT_PALETTES`, `CAT_SIZE`, and `CAT_FEET_Y`. It wanders
356
- within its parent by default; use a relatively positioned parent with a defined
357
- size. Fixed poses disable automatic pose cycling, and reduced-motion
358
- preferences pause movement.
359
-
360
- ## Image Accordion
361
-
362
- The CLI copies an editable component to `components/ui/image-accordion.tsx`.
363
- Pass any number of image objects; five are visible in the stack by default.
364
- Selecting an image animates it into the preview canvas, moves it to the end of
365
- the collection, and rotates the next image into the visible stack. Set
366
- `visibleCount` to change how many cards are shown.
367
-
368
- ```tsx
369
- import ImageAccordion from '@/components/ui/image-accordion'
370
-
371
- export function Gallery() {
372
- return (
373
- <ImageAccordion
374
- images={[
375
- { src: '/images/coast.jpg', alt: 'Coastal cliffs', title: 'The coast' },
376
- { src: '/images/forest.jpg', alt: 'A forest', title: 'The forest' },
377
- { src: '/images/city.jpg', alt: 'A city at dusk', title: 'The city' },
378
- { src: '/images/lake.jpg', alt: 'A mountain lake', title: 'The lake' },
379
- {
380
- src: '/images/desert.jpg',
381
- alt: 'A desert path',
382
- title: 'The desert',
383
- },
384
- { src: '/images/peaks.jpg', alt: 'Snowy peaks', title: 'The peaks' },
385
- ]}
386
- visibleCount={5}
387
- className="mx-auto max-w-5xl"
388
- cardClassName="rounded-lg"
389
- imageClassName="object-cover"
390
- glow={{ color: '#d4d4d8', opacity: 0.2, blur: 16 }}
391
- transition={{ stiffness: 190, damping: 24, mass: 0.8 }}
392
- />
393
- )
394
- }
395
- ```
396
-
397
- `ImageAccordionItem` supports `id`, `src`, `alt`, `title`, optional
398
- `description`, and per-card `className` and `imageClassName`. The component
399
- also accepts `stackClassName` and `previewClassName`; `glow={false}` disables
400
- the radial hover glow. Its spring, glow color/position/size/opacity/blur, and
401
- visible stack count are configurable. React, Motion, Tailwind CSS, `clsx`, and
402
- `tailwind-merge` are used; React and Tailwind CSS should already be configured
403
- in the consuming project.
404
-
405
- ## Dock Navigation
406
-
407
- Add the reusable, editable dock with:
408
-
409
- ```sh
410
- npx @istmx/ui add dock-navigation
411
- ```
412
-
413
- It writes `components/ui/dock-navigation.tsx` and installs any missing Motion,
414
- `clsx`, `tailwind-merge`, and `@tabler/icons-react` packages. The component
415
- accepts an array of labeled links and React icons. Nearby icons magnify and lift
416
- with an elastic spring; labels follow the movement, and an optional radial glow
417
- can be tuned or disabled.
418
-
419
- ```tsx
420
- import DockNavigation from '@/components/ui/dock-navigation'
421
- import {
422
- IconHome,
423
- IconUser,
424
- IconCode,
425
- IconComponents,
426
- IconMail,
427
- } from '@tabler/icons-react'
428
-
429
- const items = [
430
- { label: 'Home', href: '/', icon: <IconHome size={19} /> },
431
- { label: 'About', href: '/about', icon: <IconUser size={19} /> },
432
- {
433
- label: 'Projects',
434
- href: '/projects',
435
- icon: <IconCode size={19} />,
436
- },
437
- {
438
- label: 'Components',
439
- href: '/components',
440
- icon: <IconComponents size={19} />,
441
- active: true,
442
- },
443
- { label: 'Contact', href: '/contact', icon: <IconMail size={19} /> },
444
- ]
445
-
446
- export function SiteDock() {
447
- return (
448
- <DockNavigation
449
- items={items}
450
- label="Main navigation"
451
- glow={{ color: 'var(--foreground)', opacity: 0.2, blur: 12 }}
452
- />
453
- )
454
- }
455
- ```
456
-
457
- Each item takes `label`, `href`, and `icon` (`ReactNode`), with optional
458
- `active` and `external` flags. Pass custom classes through `className`,
459
- `itemClassName`, and `iconClassName`; set `glow={false}` to disable the glow.
460
- The component honors reduced-motion preferences.
461
-
462
- The CLI requires Node.js 18 or later. The npm package is `@istmx/ui`; the
463
- 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`.