@istmx/ui 0.1.3 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -27,12 +27,31 @@ Add the image stack component with:
27
27
  npx @istmx/ui add image-accordion
28
28
  ```
29
29
 
30
+ Add the magnifying dock navigation with:
31
+
32
+ ```sh
33
+ npx @istmx/ui add dock-navigation
34
+ ```
35
+
36
+ Add the scroll-scrubbed image story with:
37
+
38
+ ```sh
39
+ npx @istmx/ui add scroll-story-cards
40
+ ```
41
+
42
+ Add the interactive pixel cat with:
43
+
44
+ ```sh
45
+ npx @istmx/ui add pixel-cat
46
+ ```
47
+
30
48
  The CLI detects your package manager, copies the editable component to
31
49
  `components/ui/animated-text.tsx`, adds the shared `cn` helper at
32
50
  `lib/utils.ts` if it is missing, and installs any missing dependencies:
33
51
 
34
52
  - [Motion](https://motion.dev/) for animation
35
53
  - [clsx](https://www.npmjs.com/package/clsx) and [tailwind-merge](https://www.npmjs.com/package/tailwind-merge) for class composition
54
+ - `@tabler/icons-react` for components that include Tabler icons
36
55
 
37
56
  Your project should already use React and have Tailwind CSS configured. After
38
57
  installation, the component is yours to edit; your app does not need to import
@@ -94,6 +113,7 @@ in your `components/ui/animated-text.tsx` file.
94
113
  npx @istmx/ui add animated-text --no-install
95
114
  npx @istmx/ui add animated-text --overwrite
96
115
  npx @istmx/ui add image-accordion
116
+ npx @istmx/ui add dock-navigation
97
117
  ```
98
118
 
99
119
  - `--no-install` copies the source and prints the dependency command instead
@@ -103,6 +123,108 @@ npx @istmx/ui add image-accordion
103
123
  Component names accept either hyphens or spaces: `animated-text` or `animated
104
124
  text`.
105
125
 
126
+ ## Scroll Story Cards
127
+
128
+ The CLI copies an editable component to
129
+ `components/ui/scroll-story-cards.tsx`. All cards wait in a separated preview
130
+ dock at the bottom; it clears as soon as the story starts. Scrolling raises
131
+ each narrower, shorter story panel through a shallow curve toward the hero
132
+ center. Its portrait, larger copy, scene color, and Tabler CTA move together.
133
+ The sequence reverses when scrolling backward, then releases directly into
134
+ the following page content after the 400vh story timeline. The Library preview
135
+ can be opened fullscreen to give the scroll scene room on smaller screens.
136
+
137
+ ```tsx
138
+ import ScrollStoryCards, {
139
+ type ScrollStoryCard,
140
+ } from '@/components/ui/scroll-story-cards'
141
+
142
+ const cards: ScrollStoryCard[] = [
143
+ {
144
+ id: 'coast',
145
+ eyebrow: 'South coast',
146
+ title: 'The coast',
147
+ description:
148
+ '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.',
149
+ image: '/images/coast.jpg',
150
+ imageAlt: 'A quiet coastline in late afternoon light',
151
+ color: '#e8e0f4',
152
+ overlayColor: '#cbbce5',
153
+ overlayOpacity: 0.34,
154
+ buttonLabel: 'Explore',
155
+ buttonHref: '/coast',
156
+ },
157
+ {
158
+ id: 'forest',
159
+ title: 'The forest',
160
+ description: 'A new palette carries the story forward.',
161
+ image: '/images/forest.jpg',
162
+ imageAlt: 'Sunlight moving through a green forest',
163
+ color: '#e2eedf',
164
+ overlayColor: '#b9d5ad',
165
+ },
166
+ ]
167
+
168
+ export function Story() {
169
+ return (
170
+ <ScrollStoryCards
171
+ cards={cards}
172
+ eyebrow="Selected stories"
173
+ heading="A collection worth exploring."
174
+ description="Move through the frames by scrolling."
175
+ curveAmount={64}
176
+ cardWidth={156}
177
+ cardHeight={156}
178
+ overlayOpacity={0.38}
179
+ scrollDistance={400}
180
+ />
181
+ )
182
+ }
183
+ ```
184
+
185
+ `ScrollStoryCard` supports `id`, `title`, `description`, `image`, required
186
+ `imageAlt`, and a hex `color` for the scene background. Optional fields are
187
+ `overlayColor` (defaults to `color`), `overlayOpacity`, `buttonLabel`,
188
+ `buttonHref`, and `buttonColor` (defaults to the overlay color). The component
189
+ also accepts `className`, `curveAmount`, `cardWidth`, `cardHeight`,
190
+ `overlayOpacity`, `scrollDistance`, `showCardLabels`, and an optional
191
+ `scrollContainerRef` when the story lives inside a separately scrolling panel.
192
+ Use at least two
193
+ cards to see the continuous color and image transitions. The pinned story
194
+ timeline defaults to 400vh and then releases naturally into the page. The
195
+ moving panels are image-led, narrower, and use light pastel purple,
196
+ green, yellow, blue, and pink scene colors. The CTA uses a Tabler arrow icon and
197
+ subtle hover/press feedback. Reduced-motion preferences remove the lateral arc
198
+ and extra scale and rotation while retaining the vertical scroll sequence.
199
+ `onActiveChange` optionally reports which card is nearest the center; it does
200
+ not control the scroll animation.
201
+
202
+ ## Pixel Cat
203
+
204
+ The CLI copies the interactive cat to `components/ui/pixel-cat.tsx`:
205
+
206
+ ```tsx
207
+ import { PixelCat } from '@/components/ui/pixel-cat'
208
+
209
+ export function CatCard() {
210
+ return (
211
+ <div className="relative h-64 overflow-hidden rounded-xl border p-5">
212
+ <PixelCat breed="orange" position="center" />
213
+ </div>
214
+ )
215
+ }
216
+ ```
217
+
218
+ `PixelCat` supports `size`, `breed`, `palette`, `wandering`, `speed`,
219
+ `boundary`, `position`, `initialPose`, `pose`, `interactive`,
220
+ `cursorInteraction`, `messages`, `showBubble`, `onPet`, `onPoseChange`,
221
+ `padding`, `className`, and `style`. The exported types
222
+ The exports also include `PixelCatProps`, `PixelCatBreed`, `PixelCatPose`,
223
+ `PixelCatPosition`, `CAT_PALETTES`, `CAT_SIZE`, and `CAT_FEET_Y`. It wanders
224
+ within its parent by default; use a relatively positioned parent with a defined
225
+ size. Fixed poses disable automatic pose cycling, and reduced-motion
226
+ preferences pause movement.
227
+
106
228
  ## Image Accordion
107
229
 
108
230
  The CLI copies an editable component to `components/ui/image-accordion.tsx`.
@@ -122,7 +244,11 @@ export function Gallery() {
122
244
  { src: '/images/forest.jpg', alt: 'A forest', title: 'The forest' },
123
245
  { src: '/images/city.jpg', alt: 'A city at dusk', title: 'The city' },
124
246
  { src: '/images/lake.jpg', alt: 'A mountain lake', title: 'The lake' },
125
- { src: '/images/desert.jpg', alt: 'A desert path', title: 'The desert' },
247
+ {
248
+ src: '/images/desert.jpg',
249
+ alt: 'A desert path',
250
+ title: 'The desert',
251
+ },
126
252
  { src: '/images/peaks.jpg', alt: 'Snowy peaks', title: 'The peaks' },
127
253
  ]}
128
254
  visibleCount={5}
@@ -144,5 +270,62 @@ visible stack count are configurable. React, Motion, Tailwind CSS, `clsx`, and
144
270
  `tailwind-merge` are used; React and Tailwind CSS should already be configured
145
271
  in the consuming project.
146
272
 
273
+ ## Dock Navigation
274
+
275
+ Add the reusable, editable dock with:
276
+
277
+ ```sh
278
+ npx @istmx/ui add dock-navigation
279
+ ```
280
+
281
+ It writes `components/ui/dock-navigation.tsx` and installs any missing Motion,
282
+ `clsx`, `tailwind-merge`, and `@tabler/icons-react` packages. The component
283
+ accepts an array of labeled links and React icons. Nearby icons magnify and lift
284
+ with an elastic spring; labels follow the movement, and an optional radial glow
285
+ can be tuned or disabled.
286
+
287
+ ```tsx
288
+ import DockNavigation from '@/components/ui/dock-navigation'
289
+ import {
290
+ IconHome,
291
+ IconUser,
292
+ IconCode,
293
+ IconComponents,
294
+ IconMail,
295
+ } from '@tabler/icons-react'
296
+
297
+ const items = [
298
+ { label: 'Home', href: '/', icon: <IconHome size={19} /> },
299
+ { label: 'About', href: '/about', icon: <IconUser size={19} /> },
300
+ {
301
+ label: 'Projects',
302
+ href: '/projects',
303
+ icon: <IconCode size={19} />,
304
+ },
305
+ {
306
+ label: 'Components',
307
+ href: '/components',
308
+ icon: <IconComponents size={19} />,
309
+ active: true,
310
+ },
311
+ { label: 'Contact', href: '/contact', icon: <IconMail size={19} /> },
312
+ ]
313
+
314
+ export function SiteDock() {
315
+ return (
316
+ <DockNavigation
317
+ items={items}
318
+ label="Main navigation"
319
+ glow={{ color: 'var(--foreground)', opacity: 0.2, blur: 12 }}
320
+ />
321
+ )
322
+ }
323
+ ```
324
+
325
+ Each item takes `label`, `href`, and `icon` (`ReactNode`), with optional
326
+ `active` and `external` flags. Pass custom classes through `className`,
327
+ `itemClassName`, and `iconClassName`; set `glow={false}` to disable the glow.
328
+ The component honors reduced-motion preferences.
329
+
147
330
  The CLI requires Node.js 18 or later. The npm package is `@istmx/ui`; the
148
331
  installed executable is named `istmx`.
package/bin/istmx.mjs CHANGED
@@ -6,10 +6,19 @@ import { access, mkdir, readFile, writeFile } from 'node:fs/promises'
6
6
  import path from 'node:path'
7
7
  import { fileURLToPath } from 'node:url'
8
8
 
9
- const VERSION = '0.1.3'
9
+ const VERSION = '0.1.6'
10
10
  const COMPONENTS = {
11
11
  'animated-text': { fileName: 'animated-text.tsx' },
12
12
  'image-accordion': { fileName: 'image-accordion.tsx' },
13
+ 'dock-navigation': {
14
+ fileName: 'dock-navigation.tsx',
15
+ dependencies: ['@tabler/icons-react'],
16
+ },
17
+ 'scroll-story-cards': {
18
+ fileName: 'scroll-story-cards.tsx',
19
+ dependencies: ['@tabler/icons-react'],
20
+ },
21
+ 'pixel-cat': { fileName: 'pixel-cat.tsx' },
13
22
  }
14
23
  const DEPENDENCIES = ['motion', 'clsx', 'tailwind-merge']
15
24
  const COMMANDS = {
@@ -172,6 +181,9 @@ async function addComponent(component, options) {
172
181
  `Unknown component "${component}". Available components: ${Object.keys(COMPONENTS).join(', ')}. Run istmx --help to see available components.`,
173
182
  )
174
183
  }
184
+ const componentDependencies = [
185
+ ...new Set([...DEPENDENCIES, ...(definition.dependencies ?? [])]),
186
+ ]
175
187
 
176
188
  const projectPackage = await readProjectPackage()
177
189
  const manager = detectPackageManager(projectPackage)
@@ -192,7 +204,7 @@ async function addComponent(component, options) {
192
204
  await writeRegistryFile(definition.fileName, componentPath, options.overwrite)
193
205
 
194
206
  if (options.noInstall) {
195
- const missing = DEPENDENCIES.filter(
207
+ const missing = componentDependencies.filter(
196
208
  (dependency) => !installedDependencies(projectPackage)[dependency],
197
209
  )
198
210
  if (missing.length > 0) {
@@ -204,7 +216,7 @@ async function addComponent(component, options) {
204
216
  }
205
217
 
206
218
  const installed = installedDependencies(projectPackage)
207
- const missingDependencies = DEPENDENCIES.filter(
219
+ const missingDependencies = componentDependencies.filter(
208
220
  (dependency) => !installed[dependency],
209
221
  )
210
222
 
@@ -218,7 +230,9 @@ async function addComponent(component, options) {
218
230
  console.log(
219
231
  ` ${muted('Import from')} ${cyan(`@/components/ui/${component}`)}`,
220
232
  )
221
- console.log(` ${muted('Dependencies')} ${cyan(DEPENDENCIES.join(', '))}\n`)
233
+ console.log(
234
+ ` ${muted('Dependencies')} ${cyan(componentDependencies.join(', '))}\n`,
235
+ )
222
236
  }
223
237
 
224
238
  const [command, ...argumentsList] = process.argv.slice(2)
@@ -237,7 +251,7 @@ if (command === '--help' || command === '-h' || !command) {
237
251
  console.log(VERSION)
238
252
  } else if (command === 'add') {
239
253
  if (!component || component.startsWith('--')) {
240
- console.error('Choose a component: `istmx add animated-text`.')
254
+ console.error('Choose a component name. Run `istmx --help` to see options.')
241
255
  process.exitCode = 1
242
256
  } else {
243
257
  addComponent(component, options).catch((error) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@istmx/ui",
3
- "version": "0.1.3",
3
+ "version": "0.1.6",
4
4
  "description": "Add editable ISTMX UI components to your project.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -0,0 +1,198 @@
1
+ 'use client'
2
+
3
+ import {
4
+ motion,
5
+ useMotionValue,
6
+ useReducedMotion,
7
+ useSpring,
8
+ useTransform,
9
+ } from 'motion/react'
10
+ import type { MotionValue } from 'motion/react'
11
+ import type { CSSProperties, PointerEvent, ReactNode } from 'react'
12
+ import { cn } from '@/lib/utils'
13
+
14
+ export type DockNavigationItem = {
15
+ label: string
16
+ href: string
17
+ icon: ReactNode
18
+ active?: boolean
19
+ external?: boolean
20
+ }
21
+
22
+ export type DockNavigationProps = {
23
+ items: DockNavigationItem[]
24
+ label?: string
25
+ className?: string
26
+ itemClassName?: string
27
+ iconClassName?: string
28
+ glow?: false | DockNavigationGlow
29
+ }
30
+
31
+ export type DockNavigationGlow = {
32
+ color?: string
33
+ opacity?: number
34
+ blur?: number
35
+ }
36
+
37
+ function DockItem({
38
+ item,
39
+ index,
40
+ pointerX,
41
+ iconClassName,
42
+ itemClassName,
43
+ glowEnabled,
44
+ }: {
45
+ item: DockNavigationItem
46
+ index: number
47
+ pointerX: MotionValue<number>
48
+ iconClassName?: string
49
+ itemClassName?: string
50
+ glowEnabled: boolean
51
+ }) {
52
+ const reduceMotion = useReducedMotion()
53
+ const center = 30 + index * 52
54
+ const scale = useTransform(
55
+ pointerX,
56
+ [center - 84, center - 42, center, center + 42, center + 84],
57
+ [1, 1.08, 1.36, 1.08, 1],
58
+ )
59
+ const smoothScale = useSpring(scale, {
60
+ stiffness: 360,
61
+ damping: 15,
62
+ mass: 0.38,
63
+ })
64
+ const lift = useTransform(
65
+ pointerX,
66
+ [center - 84, center - 42, center, center + 42, center + 84],
67
+ [0, -4, -13, -4, 0],
68
+ )
69
+ const smoothLift = useSpring(lift, {
70
+ stiffness: 340,
71
+ damping: 15,
72
+ mass: 0.38,
73
+ })
74
+ const tooltipY = useTransform(
75
+ () => smoothLift.get() - (smoothScale.get() - 1) * 24,
76
+ )
77
+ const isExternal = item.external ?? /^https?:\/\//.test(item.href)
78
+ const content = (
79
+ <>
80
+ {glowEnabled ? (
81
+ <span
82
+ aria-hidden="true"
83
+ className={cn(
84
+ 'pointer-events-none absolute z-0 size-14 rounded-full bg-[radial-gradient(ellipse_at_center,var(--dock-glow-color)_0%,transparent_72%)] opacity-0 blur-[var(--dock-glow-blur)] transition-opacity duration-300 group-hover/dock:opacity-[var(--dock-glow-opacity)] group-focus-visible/dock:opacity-[var(--dock-glow-opacity)]',
85
+ item.active && 'opacity-[var(--dock-glow-opacity)]',
86
+ )}
87
+ />
88
+ ) : null}
89
+ <motion.span
90
+ style={{
91
+ scale: reduceMotion ? 1 : smoothScale,
92
+ y: reduceMotion ? 0 : smoothLift,
93
+ }}
94
+ whileTap={reduceMotion ? undefined : { rotate: -3 }}
95
+ className={cn(
96
+ 'border-border/70 bg-background text-muted group-hover/dock:border-foreground/55 group-hover/dock:bg-surface/70 group-hover/dock:text-foreground group-focus-visible/dock:border-foreground/55 group-focus-visible/dock:text-foreground relative isolate flex size-11 origin-bottom items-center justify-center overflow-hidden rounded-lg border transition-[border-color,background-color,color]',
97
+ item.active && 'border-foreground/60 bg-surface/70 text-foreground',
98
+ iconClassName,
99
+ )}
100
+ >
101
+ <span
102
+ aria-hidden="true"
103
+ className="pointer-events-none absolute inset-0 z-0 rounded-[inherit] bg-[linear-gradient(145deg,rgba(255,255,255,0.13)_0%,transparent_48%,rgba(0,0,0,0.06)_100%)] opacity-0 transition-opacity duration-200 group-hover/dock:opacity-100 group-focus-visible/dock:opacity-100"
104
+ />
105
+ <span className="relative z-10">{item.icon}</span>
106
+ {item.active ? (
107
+ <motion.span
108
+ layoutId="dock-navigation-active-dot"
109
+ className="bg-foreground absolute -bottom-1.5 size-1 rounded-full"
110
+ transition={
111
+ reduceMotion
112
+ ? { duration: 0 }
113
+ : { type: 'spring', stiffness: 460, damping: 34 }
114
+ }
115
+ />
116
+ ) : null}
117
+ </motion.span>
118
+ <motion.span
119
+ style={{ y: reduceMotion ? 0 : tooltipY }}
120
+ className="border-border/70 bg-background text-foreground pointer-events-none absolute -top-10 left-1/2 -translate-x-1/2 translate-y-1 rounded-md border px-2 py-1 font-mono text-[9px] whitespace-nowrap opacity-0 transition-opacity duration-150 group-hover/dock:translate-y-0 group-hover/dock:opacity-100 group-focus-visible/dock:translate-y-0 group-focus-visible/dock:opacity-100"
121
+ >
122
+ {item.label}
123
+ </motion.span>
124
+ </>
125
+ )
126
+
127
+ const linkClassName = cn(
128
+ 'group/dock relative flex size-11 cursor-pointer items-center justify-center rounded-lg outline-none',
129
+ itemClassName,
130
+ )
131
+
132
+ return (
133
+ <li className="relative flex size-11 items-center justify-center">
134
+ <a
135
+ href={item.href}
136
+ target={isExternal ? '_blank' : undefined}
137
+ rel={isExternal ? 'noreferrer' : undefined}
138
+ aria-label={item.label}
139
+ aria-current={item.active ? 'page' : undefined}
140
+ className={linkClassName}
141
+ >
142
+ {content}
143
+ </a>
144
+ </li>
145
+ )
146
+ }
147
+
148
+ export default function DockNavigation({
149
+ items,
150
+ label = 'Primary navigation',
151
+ className,
152
+ itemClassName,
153
+ iconClassName,
154
+ glow = {},
155
+ }: DockNavigationProps) {
156
+ const pointerX = useMotionValue(-1000)
157
+ const reduceMotion = useReducedMotion()
158
+ const glowOptions = typeof glow === 'object' ? glow : {}
159
+ const glowStyle = {
160
+ '--dock-glow-color': glowOptions.color ?? 'var(--foreground)',
161
+ '--dock-glow-opacity': Math.min(1, Math.max(0, glowOptions.opacity ?? 0.2)),
162
+ '--dock-glow-blur': `${Math.max(0, glowOptions.blur ?? 10)}px`,
163
+ } as CSSProperties
164
+
165
+ function updatePointer(event: PointerEvent<HTMLDivElement>) {
166
+ if (event.pointerType === 'touch' || reduceMotion) return
167
+ const bounds = event.currentTarget.getBoundingClientRect()
168
+ pointerX.set(event.clientX - bounds.left)
169
+ }
170
+
171
+ return (
172
+ <nav aria-label={label}>
173
+ <div
174
+ onPointerMove={updatePointer}
175
+ onPointerLeave={() => pointerX.set(-1000)}
176
+ style={glowStyle}
177
+ className={cn(
178
+ 'border-border/70 bg-background/95 inline-flex rounded-xl border p-2',
179
+ className,
180
+ )}
181
+ >
182
+ <ul className="flex items-end gap-2">
183
+ {items.map((item, index) => (
184
+ <DockItem
185
+ key={`${item.href}-${item.label}`}
186
+ item={item}
187
+ index={index}
188
+ pointerX={pointerX}
189
+ iconClassName={iconClassName}
190
+ itemClassName={itemClassName}
191
+ glowEnabled={glow !== false}
192
+ />
193
+ ))}
194
+ </ul>
195
+ </div>
196
+ </nav>
197
+ )
198
+ }