@istmx/ui 0.1.3 → 0.1.7

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,37 @@ 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 searchable mobile menu dock with:
37
+
38
+ ```sh
39
+ npx @istmx/ui add mobile-menu-dock
40
+ ```
41
+
42
+ Add the scroll-scrubbed image story with:
43
+
44
+ ```sh
45
+ npx @istmx/ui add scroll-story-cards
46
+ ```
47
+
48
+ Add the interactive pixel cat with:
49
+
50
+ ```sh
51
+ npx @istmx/ui add pixel-cat
52
+ ```
53
+
30
54
  The CLI detects your package manager, copies the editable component to
31
55
  `components/ui/animated-text.tsx`, adds the shared `cn` helper at
32
56
  `lib/utils.ts` if it is missing, and installs any missing dependencies:
33
57
 
34
58
  - [Motion](https://motion.dev/) for animation
35
59
  - [clsx](https://www.npmjs.com/package/clsx) and [tailwind-merge](https://www.npmjs.com/package/tailwind-merge) for class composition
60
+ - `@tabler/icons-react` for components that include Tabler icons
36
61
 
37
62
  Your project should already use React and have Tailwind CSS configured. After
38
63
  installation, the component is yours to edit; your app does not need to import
@@ -94,6 +119,8 @@ in your `components/ui/animated-text.tsx` file.
94
119
  npx @istmx/ui add animated-text --no-install
95
120
  npx @istmx/ui add animated-text --overwrite
96
121
  npx @istmx/ui add image-accordion
122
+ npx @istmx/ui add dock-navigation
123
+ npx @istmx/ui add mobile-menu-dock
97
124
  ```
98
125
 
99
126
  - `--no-install` copies the source and prints the dependency command instead
@@ -103,6 +130,108 @@ npx @istmx/ui add image-accordion
103
130
  Component names accept either hyphens or spaces: `animated-text` or `animated
104
131
  text`.
105
132
 
133
+ ## Scroll Story Cards
134
+
135
+ The CLI copies an editable component to
136
+ `components/ui/scroll-story-cards.tsx`. All cards wait in a separated preview
137
+ dock at the bottom; it clears as soon as the story starts. Scrolling raises
138
+ each narrower, shorter story panel through a shallow curve toward the hero
139
+ center. Its portrait, larger copy, scene color, and Tabler CTA move together.
140
+ The sequence reverses when scrolling backward, then releases directly into
141
+ the following page content after the 400vh story timeline. The Library preview
142
+ can be opened fullscreen to give the scroll scene room on smaller screens.
143
+
144
+ ```tsx
145
+ import ScrollStoryCards, {
146
+ type ScrollStoryCard,
147
+ } from '@/components/ui/scroll-story-cards'
148
+
149
+ const cards: ScrollStoryCard[] = [
150
+ {
151
+ id: 'coast',
152
+ eyebrow: 'South coast',
153
+ title: 'The coast',
154
+ description:
155
+ '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.',
156
+ image: '/images/coast.jpg',
157
+ imageAlt: 'A quiet coastline in late afternoon light',
158
+ color: '#e8e0f4',
159
+ overlayColor: '#cbbce5',
160
+ overlayOpacity: 0.34,
161
+ buttonLabel: 'Explore',
162
+ buttonHref: '/coast',
163
+ },
164
+ {
165
+ id: 'forest',
166
+ title: 'The forest',
167
+ description: 'A new palette carries the story forward.',
168
+ image: '/images/forest.jpg',
169
+ imageAlt: 'Sunlight moving through a green forest',
170
+ color: '#e2eedf',
171
+ overlayColor: '#b9d5ad',
172
+ },
173
+ ]
174
+
175
+ export function Story() {
176
+ return (
177
+ <ScrollStoryCards
178
+ cards={cards}
179
+ eyebrow="Selected stories"
180
+ heading="A collection worth exploring."
181
+ description="Move through the frames by scrolling."
182
+ curveAmount={64}
183
+ cardWidth={156}
184
+ cardHeight={156}
185
+ overlayOpacity={0.38}
186
+ scrollDistance={400}
187
+ />
188
+ )
189
+ }
190
+ ```
191
+
192
+ `ScrollStoryCard` supports `id`, `title`, `description`, `image`, required
193
+ `imageAlt`, and a hex `color` for the scene background. Optional fields are
194
+ `overlayColor` (defaults to `color`), `overlayOpacity`, `buttonLabel`,
195
+ `buttonHref`, and `buttonColor` (defaults to the overlay color). The component
196
+ also accepts `className`, `curveAmount`, `cardWidth`, `cardHeight`,
197
+ `overlayOpacity`, `scrollDistance`, `showCardLabels`, and an optional
198
+ `scrollContainerRef` when the story lives inside a separately scrolling panel.
199
+ Use at least two
200
+ cards to see the continuous color and image transitions. The pinned story
201
+ timeline defaults to 400vh and then releases naturally into the page. The
202
+ moving panels are image-led, narrower, and use light pastel purple,
203
+ green, yellow, blue, and pink scene colors. The CTA uses a Tabler arrow icon and
204
+ subtle hover/press feedback. Reduced-motion preferences remove the lateral arc
205
+ and extra scale and rotation while retaining the vertical scroll sequence.
206
+ `onActiveChange` optionally reports which card is nearest the center; it does
207
+ not control the scroll animation.
208
+
209
+ ## Pixel Cat
210
+
211
+ The CLI copies the interactive cat to `components/ui/pixel-cat.tsx`:
212
+
213
+ ```tsx
214
+ import { PixelCat } from '@/components/ui/pixel-cat'
215
+
216
+ export function CatCard() {
217
+ return (
218
+ <div className="relative h-64 overflow-hidden rounded-xl border p-5">
219
+ <PixelCat breed="orange" position="center" />
220
+ </div>
221
+ )
222
+ }
223
+ ```
224
+
225
+ `PixelCat` supports `size`, `breed`, `palette`, `wandering`, `speed`,
226
+ `boundary`, `position`, `initialPose`, `pose`, `interactive`,
227
+ `cursorInteraction`, `messages`, `showBubble`, `onPet`, `onPoseChange`,
228
+ `padding`, `className`, and `style`. The exported types
229
+ The exports also include `PixelCatProps`, `PixelCatBreed`, `PixelCatPose`,
230
+ `PixelCatPosition`, `CAT_PALETTES`, `CAT_SIZE`, and `CAT_FEET_Y`. It wanders
231
+ within its parent by default; use a relatively positioned parent with a defined
232
+ size. Fixed poses disable automatic pose cycling, and reduced-motion
233
+ preferences pause movement.
234
+
106
235
  ## Image Accordion
107
236
 
108
237
  The CLI copies an editable component to `components/ui/image-accordion.tsx`.
@@ -122,7 +251,11 @@ export function Gallery() {
122
251
  { src: '/images/forest.jpg', alt: 'A forest', title: 'The forest' },
123
252
  { src: '/images/city.jpg', alt: 'A city at dusk', title: 'The city' },
124
253
  { src: '/images/lake.jpg', alt: 'A mountain lake', title: 'The lake' },
125
- { src: '/images/desert.jpg', alt: 'A desert path', title: 'The desert' },
254
+ {
255
+ src: '/images/desert.jpg',
256
+ alt: 'A desert path',
257
+ title: 'The desert',
258
+ },
126
259
  { src: '/images/peaks.jpg', alt: 'Snowy peaks', title: 'The peaks' },
127
260
  ]}
128
261
  visibleCount={5}
@@ -144,5 +277,62 @@ visible stack count are configurable. React, Motion, Tailwind CSS, `clsx`, and
144
277
  `tailwind-merge` are used; React and Tailwind CSS should already be configured
145
278
  in the consuming project.
146
279
 
280
+ ## Dock Navigation
281
+
282
+ Add the reusable, editable dock with:
283
+
284
+ ```sh
285
+ npx @istmx/ui add dock-navigation
286
+ ```
287
+
288
+ It writes `components/ui/dock-navigation.tsx` and installs any missing Motion,
289
+ `clsx`, `tailwind-merge`, and `@tabler/icons-react` packages. The component
290
+ accepts an array of labeled links and React icons. Nearby icons magnify and lift
291
+ with an elastic spring; labels follow the movement, and an optional radial glow
292
+ can be tuned or disabled.
293
+
294
+ ```tsx
295
+ import DockNavigation from '@/components/ui/dock-navigation'
296
+ import {
297
+ IconHome,
298
+ IconUser,
299
+ IconCode,
300
+ IconComponents,
301
+ IconMail,
302
+ } from '@tabler/icons-react'
303
+
304
+ const items = [
305
+ { label: 'Home', href: '/', icon: <IconHome size={19} /> },
306
+ { label: 'About', href: '/about', icon: <IconUser size={19} /> },
307
+ {
308
+ label: 'Projects',
309
+ href: '/projects',
310
+ icon: <IconCode size={19} />,
311
+ },
312
+ {
313
+ label: 'Components',
314
+ href: '/components',
315
+ icon: <IconComponents size={19} />,
316
+ active: true,
317
+ },
318
+ { label: 'Contact', href: '/contact', icon: <IconMail size={19} /> },
319
+ ]
320
+
321
+ export function SiteDock() {
322
+ return (
323
+ <DockNavigation
324
+ items={items}
325
+ label="Main navigation"
326
+ glow={{ color: 'var(--foreground)', opacity: 0.2, blur: 12 }}
327
+ />
328
+ )
329
+ }
330
+ ```
331
+
332
+ Each item takes `label`, `href`, and `icon` (`ReactNode`), with optional
333
+ `active` and `external` flags. Pass custom classes through `className`,
334
+ `itemClassName`, and `iconClassName`; set `glow={false}` to disable the glow.
335
+ The component honors reduced-motion preferences.
336
+
147
337
  The CLI requires Node.js 18 or later. The npm package is `@istmx/ui`; the
148
338
  installed executable is named `istmx`.
package/bin/istmx.mjs CHANGED
@@ -6,10 +6,23 @@ 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.7'
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
+ 'mobile-menu-dock': {
18
+ fileName: 'mobile-menu-dock.tsx',
19
+ dependencies: ['@tabler/icons-react'],
20
+ },
21
+ 'scroll-story-cards': {
22
+ fileName: 'scroll-story-cards.tsx',
23
+ dependencies: ['@tabler/icons-react'],
24
+ },
25
+ 'pixel-cat': { fileName: 'pixel-cat.tsx' },
13
26
  }
14
27
  const DEPENDENCIES = ['motion', 'clsx', 'tailwind-merge']
15
28
  const COMMANDS = {
@@ -172,6 +185,9 @@ async function addComponent(component, options) {
172
185
  `Unknown component "${component}". Available components: ${Object.keys(COMPONENTS).join(', ')}. Run istmx --help to see available components.`,
173
186
  )
174
187
  }
188
+ const componentDependencies = [
189
+ ...new Set([...DEPENDENCIES, ...(definition.dependencies ?? [])]),
190
+ ]
175
191
 
176
192
  const projectPackage = await readProjectPackage()
177
193
  const manager = detectPackageManager(projectPackage)
@@ -192,7 +208,7 @@ async function addComponent(component, options) {
192
208
  await writeRegistryFile(definition.fileName, componentPath, options.overwrite)
193
209
 
194
210
  if (options.noInstall) {
195
- const missing = DEPENDENCIES.filter(
211
+ const missing = componentDependencies.filter(
196
212
  (dependency) => !installedDependencies(projectPackage)[dependency],
197
213
  )
198
214
  if (missing.length > 0) {
@@ -204,7 +220,7 @@ async function addComponent(component, options) {
204
220
  }
205
221
 
206
222
  const installed = installedDependencies(projectPackage)
207
- const missingDependencies = DEPENDENCIES.filter(
223
+ const missingDependencies = componentDependencies.filter(
208
224
  (dependency) => !installed[dependency],
209
225
  )
210
226
 
@@ -218,7 +234,9 @@ async function addComponent(component, options) {
218
234
  console.log(
219
235
  ` ${muted('Import from')} ${cyan(`@/components/ui/${component}`)}`,
220
236
  )
221
- console.log(` ${muted('Dependencies')} ${cyan(DEPENDENCIES.join(', '))}\n`)
237
+ console.log(
238
+ ` ${muted('Dependencies')} ${cyan(componentDependencies.join(', '))}\n`,
239
+ )
222
240
  }
223
241
 
224
242
  const [command, ...argumentsList] = process.argv.slice(2)
@@ -237,7 +255,7 @@ if (command === '--help' || command === '-h' || !command) {
237
255
  console.log(VERSION)
238
256
  } else if (command === 'add') {
239
257
  if (!component || component.startsWith('--')) {
240
- console.error('Choose a component: `istmx add animated-text`.')
258
+ console.error('Choose a component name. Run `istmx --help` to see options.')
241
259
  process.exitCode = 1
242
260
  } else {
243
261
  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.7",
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
+ }