@istmx/ui 0.0.0-stage → 0.1.1

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
@@ -1,3 +1,30 @@
1
- # Temporary Holding Version
1
+ # ISTMX UI CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The ISTMX CLI adds editable UI component source files to your project and
4
+ installs the dependencies they need.
5
+
6
+ ## Add a component
7
+
8
+ Run one of these from your project root:
9
+
10
+ ```sh
11
+ npx @istmx/ui add animated-text
12
+ pnpm dlx @istmx/ui add animated-text
13
+ yarn dlx @istmx/ui add animated-text
14
+ bunx @istmx/ui add animated-text
15
+ ```
16
+
17
+ The CLI displays each step as it runs, writes the component to
18
+ `components/ui/animated-text.tsx`, adds the shared `cn` helper at
19
+ `lib/utils.ts` when it is missing, detects the project's package manager, and
20
+ installs any missing `motion`, `clsx`, and `tailwind-merge` dependencies. The
21
+ component uses Tailwind utility classes, so your app should already have
22
+ Tailwind CSS configured.
23
+
24
+ ## Options
25
+
26
+ - `--no-install` writes the source files and prints the dependency command.
27
+ - `--overwrite` replaces existing component and helper files.
28
+
29
+ The package is dependency free and requires Node.js 18 or later. Its executable
30
+ name is `istmx` after the `@istmx/ui` package is installed.
package/bin/istmx.mjs ADDED
@@ -0,0 +1,241 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { spawnSync } from 'node:child_process'
4
+ import { constants, existsSync } from 'node:fs'
5
+ import { access, mkdir, readFile, writeFile } from 'node:fs/promises'
6
+ import path from 'node:path'
7
+ import { fileURLToPath } from 'node:url'
8
+
9
+ const VERSION = '0.1.1'
10
+ const DEPENDENCIES = ['motion', 'clsx', 'tailwind-merge']
11
+ const COMMANDS = {
12
+ npm: ['install'],
13
+ pnpm: ['add'],
14
+ yarn: ['add'],
15
+ bun: ['add'],
16
+ }
17
+ const CURRENT_DIRECTORY = process.cwd()
18
+ const PACKAGE_DIRECTORY = path.resolve(
19
+ path.dirname(fileURLToPath(import.meta.url)),
20
+ '..',
21
+ )
22
+ const REGISTRY_DIRECTORY = path.join(PACKAGE_DIRECTORY, 'registry')
23
+ const USE_COLOR = Boolean(process.stdout.isTTY && !process.env.NO_COLOR)
24
+
25
+ const color = (code, value) =>
26
+ USE_COLOR ? `\u001B[${code}m${value}\u001B[0m` : value
27
+ const cyan = (value) => color('36;1', value)
28
+ const muted = (value) => color('2', value)
29
+ const green = (value) => color('32;1', value)
30
+ const red = (value) => color('31;1', value)
31
+
32
+ function printHeader() {
33
+ console.log(`\n${cyan('◆ ISTMX')} ${muted(`/ source installer v${VERSION}`)}`)
34
+ console.log(muted(' Editable components, added to your codebase.\n'))
35
+ }
36
+
37
+ function printStep(label) {
38
+ console.log(`${cyan('◇')} ${label}`)
39
+ }
40
+
41
+ function printSuccess(label) {
42
+ console.log(`${green('✔')} ${label}`)
43
+ }
44
+
45
+ function printHelp() {
46
+ printHeader()
47
+ console.log(`Usage:
48
+
49
+ istmx add <component> [--no-install] [--overwrite]
50
+ istmx --help
51
+ istmx --version
52
+
53
+ Options:
54
+ --no-install Write component files without installing dependencies
55
+ --overwrite Replace component files that already exist
56
+
57
+ Components:
58
+ animated-text`)
59
+ }
60
+
61
+ function detectPackageManager(projectPackage) {
62
+ const userAgent = process.env.npm_config_user_agent ?? ''
63
+ const managerFromUserAgent = userAgent.match(/^(npm|pnpm|yarn|bun)\//)?.[1]
64
+
65
+ if (managerFromUserAgent) return managerFromUserAgent
66
+
67
+ const managerFromPackage =
68
+ typeof projectPackage.packageManager === 'string'
69
+ ? projectPackage.packageManager.match(/^(npm|pnpm|yarn|bun)@/)?.[1]
70
+ : undefined
71
+
72
+ if (managerFromPackage) return managerFromPackage
73
+
74
+ const lockfiles = [
75
+ ['pnpm-lock.yaml', 'pnpm'],
76
+ ['yarn.lock', 'yarn'],
77
+ ['bun.lock', 'bun'],
78
+ ['bun.lockb', 'bun'],
79
+ ['package-lock.json', 'npm'],
80
+ ]
81
+
82
+ for (const [lockfile, manager] of lockfiles) {
83
+ if (existsSync(path.join(CURRENT_DIRECTORY, lockfile))) return manager
84
+ }
85
+
86
+ return 'npm'
87
+ }
88
+
89
+ async function readProjectPackage() {
90
+ const packagePath = path.join(CURRENT_DIRECTORY, 'package.json')
91
+ try {
92
+ const content = await readFile(packagePath, 'utf8')
93
+ return JSON.parse(content)
94
+ } catch (error) {
95
+ if (error instanceof SyntaxError) {
96
+ throw new Error('Could not parse the project package.json.')
97
+ }
98
+ throw new Error('Run `istmx add` from a project folder with package.json.')
99
+ }
100
+ }
101
+
102
+ function installedDependencies(projectPackage) {
103
+ return {
104
+ ...projectPackage.dependencies,
105
+ ...projectPackage.devDependencies,
106
+ ...projectPackage.optionalDependencies,
107
+ }
108
+ }
109
+
110
+ function dependencyCommand(manager, dependencies) {
111
+ return [manager, ...COMMANDS[manager], ...dependencies]
112
+ }
113
+
114
+ async function writeRegistryFile(sourceName, targetPath, overwrite) {
115
+ const content = await readFile(
116
+ path.join(REGISTRY_DIRECTORY, sourceName),
117
+ 'utf8',
118
+ )
119
+ await mkdir(path.dirname(targetPath), { recursive: true })
120
+
121
+ try {
122
+ await access(targetPath, constants.F_OK)
123
+ if (!overwrite) {
124
+ console.log(
125
+ `${muted('·')} Kept existing ${path.relative(CURRENT_DIRECTORY, targetPath)}`,
126
+ )
127
+ return false
128
+ }
129
+ } catch {
130
+ // Target file does not exist yet.
131
+ }
132
+
133
+ await writeFile(targetPath, content, 'utf8')
134
+ printSuccess(`Added ${path.relative(CURRENT_DIRECTORY, targetPath)}`)
135
+ return true
136
+ }
137
+
138
+ function installDependencies(manager, dependencies) {
139
+ if (dependencies.length === 0) {
140
+ printSuccess('Dependencies are already present.')
141
+ return true
142
+ }
143
+
144
+ const [command, ...args] = dependencyCommand(manager, dependencies)
145
+ printStep(`Installing dependencies with ${manager}`)
146
+ console.log(` ${muted(dependencies.join(' · '))}`)
147
+ const result = spawnSync(command, args, {
148
+ cwd: CURRENT_DIRECTORY,
149
+ stdio: 'inherit',
150
+ shell: process.platform === 'win32',
151
+ })
152
+
153
+ if (result.status === 0) {
154
+ printSuccess('Dependencies installed.')
155
+ return true
156
+ }
157
+
158
+ return false
159
+ }
160
+
161
+ async function addComponent(component, options) {
162
+ if (component !== 'animated-text') {
163
+ throw new Error(
164
+ `Unknown component "${component}". Run istmx --help to see available components.`,
165
+ )
166
+ }
167
+
168
+ const projectPackage = await readProjectPackage()
169
+ const manager = detectPackageManager(projectPackage)
170
+ printHeader()
171
+ console.log(
172
+ `${muted('Adding')} ${cyan(component)} ${muted('to your project')}\n`,
173
+ )
174
+ printStep('Writing editable source files')
175
+ const componentPath = path.join(
176
+ CURRENT_DIRECTORY,
177
+ 'components',
178
+ 'ui',
179
+ 'animated-text.tsx',
180
+ )
181
+ const utilityPath = path.join(CURRENT_DIRECTORY, 'lib', 'utils.ts')
182
+
183
+ await writeRegistryFile('utils.ts', utilityPath, options.overwrite)
184
+ await writeRegistryFile('animated-text.tsx', componentPath, options.overwrite)
185
+
186
+ if (options.noInstall) {
187
+ const missing = DEPENDENCIES.filter(
188
+ (dependency) => !installedDependencies(projectPackage)[dependency],
189
+ )
190
+ if (missing.length > 0) {
191
+ printStep('Install the required dependencies manually')
192
+ console.log(` ${cyan(dependencyCommand(manager, missing).join(' '))}`)
193
+ }
194
+ printSuccess('Source files are ready.')
195
+ return
196
+ }
197
+
198
+ const installed = installedDependencies(projectPackage)
199
+ const missingDependencies = DEPENDENCIES.filter(
200
+ (dependency) => !installed[dependency],
201
+ )
202
+
203
+ if (!installDependencies(manager, missingDependencies)) {
204
+ throw new Error(
205
+ `Dependency installation failed. Run ${dependencyCommand(manager, missingDependencies).join(' ')} and try again.`,
206
+ )
207
+ }
208
+
209
+ console.log(`\n${green('Done!')} ${component} is ready to edit.`)
210
+ console.log(
211
+ ` ${muted('Import from')} ${cyan('@/components/ui/animated-text')}`,
212
+ )
213
+ console.log(` ${muted('Dependencies')} ${cyan(DEPENDENCIES.join(', '))}\n`)
214
+ }
215
+
216
+ const [command, component, ...argumentsList] = process.argv.slice(2)
217
+ const options = {
218
+ noInstall: argumentsList.includes('--no-install'),
219
+ overwrite: argumentsList.includes('--overwrite'),
220
+ }
221
+
222
+ if (command === '--help' || command === '-h' || !command) {
223
+ printHelp()
224
+ } else if (command === '--version' || command === '-v') {
225
+ console.log(VERSION)
226
+ } else if (command === 'add') {
227
+ if (!component || component.startsWith('--')) {
228
+ console.error('Choose a component: `istmx add animated-text`.')
229
+ process.exitCode = 1
230
+ } else {
231
+ addComponent(component, options).catch((error) => {
232
+ console.error(`\n${red('✖')} ${error.message}`)
233
+ process.exitCode = 1
234
+ })
235
+ }
236
+ } else {
237
+ console.error(
238
+ `${red('✖')} Unknown command "${command}". Run istmx --help for usage.`,
239
+ )
240
+ process.exitCode = 1
241
+ }
package/package.json CHANGED
@@ -1,6 +1,27 @@
1
1
  {
2
2
  "name": "@istmx/ui",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Add editable ISTMX UI components to your project.",
5
+ "type": "module",
6
+ "bin": {
7
+ "istmx": "bin/istmx.mjs"
8
+ },
9
+ "files": [
10
+ "bin",
11
+ "registry"
12
+ ],
13
+ "engines": {
14
+ "node": ">=18"
15
+ },
16
+ "publishConfig": {
17
+ "access": "public"
18
+ },
19
+ "keywords": [
20
+ "istmx",
21
+ "ui",
22
+ "components",
23
+ "cli",
24
+ "source-first"
25
+ ],
26
+ "license": "MIT"
27
+ }
@@ -0,0 +1,215 @@
1
+ 'use client'
2
+
3
+ import { useEffect, useState } from 'react'
4
+ import type { CSSProperties } from 'react'
5
+ import { AnimatePresence, motion, useReducedMotion } from 'motion/react'
6
+ import { cn } from '@/lib/utils'
7
+
8
+ const DEFAULT_ITEMS = [
9
+ 'an AI Engineer',
10
+ 'a Full-Stack Developer',
11
+ 'a Student',
12
+ 'a Mobile Developer',
13
+ ]
14
+
15
+ const DIRECTIONS = {
16
+ up: { enter: 5, exit: -5 },
17
+ down: { enter: -5, exit: 5 },
18
+ left: { enter: 7, exit: -7 },
19
+ right: { enter: -7, exit: 7 },
20
+ none: { enter: 0, exit: 0 },
21
+ } as const
22
+
23
+ export type AnimatedTextEffect = 'blur' | 'shimmer' | 'fade' | 'slide' | 'wave'
24
+ export type AnimatedTextDirection = keyof typeof DIRECTIONS
25
+ export type AnimatedTextEffectOptions = {
26
+ blur?: { amount?: number }
27
+ fade?: { from?: number }
28
+ slide?: { distance?: number }
29
+ shimmer?: { duration?: number; width?: number }
30
+ wave?: { amplitude?: number; stagger?: number }
31
+ }
32
+
33
+ export type AnimatedTextProps = {
34
+ items?: string[]
35
+ prefix?: string
36
+ effect?: AnimatedTextEffect
37
+ effects?: AnimatedTextEffect[]
38
+ effectOptions?: AnimatedTextEffectOptions
39
+ scale?: number
40
+ direction?: AnimatedTextDirection
41
+ interval?: number
42
+ speed?: number
43
+ className?: string
44
+ textClassName?: string
45
+ }
46
+
47
+ export function AnimatedText({
48
+ items = DEFAULT_ITEMS,
49
+ prefix,
50
+ effect = 'blur',
51
+ effects = [effect],
52
+ effectOptions,
53
+ scale,
54
+ direction = 'up',
55
+ interval = 2600,
56
+ speed = 0.32,
57
+ className,
58
+ textClassName,
59
+ }: AnimatedTextProps) {
60
+ const [itemIndex, setItemIndex] = useState(0)
61
+ const shouldReduceMotion = useReducedMotion()
62
+ const values = items.length > 0 ? items : ['']
63
+ const currentItem = values[itemIndex % values.length]
64
+ const offset = DIRECTIONS[direction]
65
+ const activeEffects = new Set(effects)
66
+ const hasBlur = activeEffects.has('blur')
67
+ const hasFade = activeEffects.has('fade') || hasBlur
68
+ const hasSlide = activeEffects.has('slide') || hasBlur
69
+ const blurAmount = Math.max(0, effectOptions?.blur?.amount ?? 5)
70
+ const fadeFrom = Math.min(1, Math.max(0, effectOptions?.fade?.from ?? 0))
71
+ const shimmerDuration = Math.max(0.1, effectOptions?.shimmer?.duration ?? 2.6)
72
+ const shimmerWidth = Math.min(
73
+ 80,
74
+ Math.max(5, effectOptions?.shimmer?.width ?? 30),
75
+ )
76
+ const slideDistance = Math.max(
77
+ 0,
78
+ effectOptions?.slide?.distance ?? Math.abs(offset.enter),
79
+ )
80
+ const waveAmplitude = Math.max(0, effectOptions?.wave?.amplitude ?? 4)
81
+ const waveStagger = Math.max(0, effectOptions?.wave?.stagger ?? 0.025)
82
+ const scaleFrom =
83
+ typeof scale === 'number' &&
84
+ Number.isFinite(scale) &&
85
+ scale > 0 &&
86
+ scale !== 1
87
+ ? scale
88
+ : undefined
89
+ const shimmerEnabled = activeEffects.has('shimmer') && !shouldReduceMotion
90
+ const waveEnabled = activeEffects.has('wave')
91
+ const enterX =
92
+ direction === 'left' || direction === 'right'
93
+ ? Math.sign(offset.enter) * slideDistance
94
+ : 0
95
+ const enterY =
96
+ direction === 'up' || direction === 'down'
97
+ ? Math.sign(offset.enter) * slideDistance
98
+ : 0
99
+ const exitX =
100
+ direction === 'left' || direction === 'right'
101
+ ? Math.sign(offset.exit) * slideDistance
102
+ : 0
103
+ const exitY =
104
+ direction === 'up' || direction === 'down'
105
+ ? Math.sign(offset.exit) * slideDistance
106
+ : 0
107
+ const initialState = {
108
+ ...(hasFade ? { opacity: fadeFrom } : {}),
109
+ ...(hasSlide ? { x: enterX, y: enterY } : {}),
110
+ ...(hasBlur ? { filter: 'blur(' + blurAmount + 'px)' } : {}),
111
+ ...(scaleFrom !== undefined ? { scale: scaleFrom } : {}),
112
+ }
113
+ const animateState = {
114
+ ...(hasFade ? { opacity: 1 } : {}),
115
+ ...(hasSlide ? { x: 0, y: 0 } : {}),
116
+ ...(hasBlur ? { filter: 'blur(0px)' } : {}),
117
+ ...(scaleFrom !== undefined ? { scale: 1 } : {}),
118
+ ...(shimmerEnabled ? { backgroundPosition: ['100% 0', '-120% 0'] } : {}),
119
+ }
120
+ const exitState = {
121
+ ...(hasFade ? { opacity: fadeFrom } : {}),
122
+ ...(hasSlide ? { x: exitX, y: exitY } : {}),
123
+ ...(hasBlur ? { filter: 'blur(' + blurAmount + 'px)' } : {}),
124
+ ...(scaleFrom !== undefined ? { scale: scaleFrom } : {}),
125
+ }
126
+
127
+ useEffect(() => {
128
+ if (shouldReduceMotion || values.length < 2 || interval <= 0) return
129
+
130
+ const timer = window.setInterval(() => {
131
+ setItemIndex((index) => (index + 1) % values.length)
132
+ }, interval)
133
+
134
+ return () => window.clearInterval(timer)
135
+ }, [interval, shouldReduceMotion, values.length])
136
+
137
+ return (
138
+ <span
139
+ className={cn(
140
+ 'relative inline-flex min-h-5 items-center overflow-hidden align-top text-sm sm:text-base',
141
+ className,
142
+ )}
143
+ aria-live="polite"
144
+ aria-atomic="true"
145
+ >
146
+ {prefix ? <span className="mr-1.5 shrink-0">{prefix}</span> : null}
147
+ <AnimatePresence mode="wait" initial={false}>
148
+ <motion.span
149
+ key={itemIndex + ':' + currentItem}
150
+ initial={shouldReduceMotion ? false : initialState}
151
+ animate={animateState}
152
+ exit={shouldReduceMotion ? { opacity: 0 } : exitState}
153
+ transition={{
154
+ duration: shouldReduceMotion ? 0 : speed,
155
+ ease: 'easeOut',
156
+ ...(shimmerEnabled
157
+ ? {
158
+ backgroundPosition: {
159
+ duration: shimmerDuration,
160
+ ease: 'easeInOut',
161
+ repeat: Infinity,
162
+ },
163
+ }
164
+ : {}),
165
+ }}
166
+ className={cn(
167
+ 'font-medium whitespace-nowrap',
168
+ activeEffects.has('shimmer') &&
169
+ (shimmerEnabled
170
+ ? 'bg-[linear-gradient(100deg,var(--muted)_var(--shimmer-start),var(--foreground)_50%,var(--muted)_var(--shimmer-end))] bg-[length:220%_100%] bg-clip-text text-transparent'
171
+ : 'text-foreground'),
172
+ textClassName,
173
+ )}
174
+ style={
175
+ {
176
+ '--shimmer-start': 50 - shimmerWidth / 2 + '%',
177
+ '--shimmer-end': 50 + shimmerWidth / 2 + '%',
178
+ } as CSSProperties
179
+ }
180
+ >
181
+ {waveEnabled ? (
182
+ <>
183
+ <span className="sr-only">{currentItem}</span>
184
+ <span aria-hidden="true" className="inline-flex">
185
+ {Array.from(currentItem).map((character, index) => (
186
+ <motion.span
187
+ key={index + '-' + character}
188
+ initial={shouldReduceMotion ? false : { y: waveAmplitude }}
189
+ animate={
190
+ shouldReduceMotion
191
+ ? { y: 0 }
192
+ : { y: [waveAmplitude, -waveAmplitude * 0.75, 0] }
193
+ }
194
+ transition={{
195
+ duration: shouldReduceMotion ? 0 : speed * 0.7,
196
+ delay: shouldReduceMotion ? 0 : index * waveStagger,
197
+ ease: 'easeOut',
198
+ }}
199
+ className="inline-block"
200
+ >
201
+ {character === ' ' ? '\u00a0' : character}
202
+ </motion.span>
203
+ ))}
204
+ </span>
205
+ </>
206
+ ) : (
207
+ currentItem
208
+ )}
209
+ </motion.span>
210
+ </AnimatePresence>
211
+ </span>
212
+ )
213
+ }
214
+
215
+ export default AnimatedText
@@ -0,0 +1,6 @@
1
+ import { clsx, type ClassValue } from 'clsx'
2
+ import { twMerge } from 'tailwind-merge'
3
+
4
+ export function cn(...inputs: ClassValue[]) {
5
+ return twMerge(clsx(inputs))
6
+ }