uifolio 0.5.5 → 0.7.0

package/cli/uifolio.mjs

@@ -13,6 +13,7 @@
  * Options:
  *   --cwd <dir>          target project (default: current directory)
  *   --dir <path>         components folder (default: src/components/ui)
+ *   --animations <path>  animations folder (default: src/components/animations)
  *   --lib <path>         helpers folder (default: src/lib)
  *   --alias <alias>      target import alias (default: @)
  *   --color <hex>        primary color, written in the Tailwind tokens (@theme)
@@ -31,20 +32,32 @@
  *   node cli/uifolio.mjs add video-player --alias "#lib" --dry-run
  */
 
+import { execFileSync } from 'node:child_process'
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
-import { basename, dirname, join, relative, resolve } from 'node:path'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 import { fileURLToPath } from 'node:url'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const REGISTRY_SRC = resolve(HERE, '..', 'src')
 const REGISTRY_UI = join(REGISTRY_SRC, 'components', 'ui')
+const REGISTRY_ANIMATIONS = join(REGISTRY_SRC, 'components', 'animations')
 const CONFIG_NAME = 'uifolio.json'
 
+/** Stand-alone animations (the providers/contexts are helpers, not entries). */
+const ANIMATION_NAMES = [
+  'horizontal-accordion',
+  'horizontal-story',
+  'image-crossfade',
+  'scroll-text',
+  'stacking-cards',
+]
+
 const LIB_DEPS = ['clsx', 'tailwind-merge'] // cn() — always copied with the helpers
 
 const DEFAULT_ACCENT = '#10b981'
 const DEFAULT_COMPONENTS_DIR = 'src/components/ui'
+const DEFAULT_ANIMATIONS_DIR = 'src/components/animations'
 const THEME_FILE = 'uifolio-theme.css'
 
 /** Global CSS candidates for wiring the Tailwind theme. */
@@ -52,8 +65,32 @@ const GLOBAL_CSS_CANDIDATES = [
   'src/index.css',
   'src/app.css',
   'src/globals.css',
+  'src/styles/globals.css',
+  'src/styles/index.css',
+  'src/main.css',
+  'src/style.css',
+  'app/globals.css',
 ]
 
+/** Folders never scanned when looking for the project's stylesheets. */
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  'public',
+  '.git',
+  '.next',
+  '.vite',
+  '.turbo',
+])
+
+const MAX_SCAN_DEPTH = 6
+
+/** A Tailwind CSS 4 entrypoint: `@import 'tailwindcss';` or `@tailwind base;`. */
+const TAILWIND_ENTRY = /@import\s+['"]tailwindcss(?:[^'"]*)['"]|@tailwind\s+base/
+
 /* -------------------------------------------------------------------------- */
 /* Utilitaires                                                                */
 /* -------------------------------------------------------------------------- */
@@ -67,6 +104,10 @@ function ok(message) {
   console.log(`\x1b[32m✓\x1b[0m ${message}`)
 }
 
+function warn(message) {
+  console.log(`\x1b[33m!\x1b[0m ${message}`)
+}
+
 function info(message) {
   console.log(`  ${message}`)
 }
@@ -117,7 +158,7 @@ function writeFailure(error, target) {
   fail(`Cannot write ${target}: ${reasons[error?.code] ?? error?.message ?? error}.`)
 }
 
-function listComponents() {
+function listUiComponents() {
   if (!existsSync(REGISTRY_UI)) return []
   return readdirSync(REGISTRY_UI)
     .filter((name) => name.endsWith('.tsx'))
@@ -125,6 +166,24 @@ function listComponents() {
     .sort()
 }
 
+function listAnimationComponents() {
+  if (!existsSync(REGISTRY_ANIMATIONS)) return []
+  return ANIMATION_NAMES.filter((name) => existsSync(join(REGISTRY_ANIMATIONS, `${name}.tsx`)))
+}
+
+function listComponents() {
+  return [...listUiComponents(), ...listAnimationComponents()].sort()
+}
+
+/** Absolute entry + destination kind of a registry name. */
+function registryEntry(name) {
+  const ui = join(REGISTRY_UI, `${name}.tsx`)
+  if (existsSync(ui)) return { path: ui, kind: 'ui' }
+  const animation = join(REGISTRY_ANIMATIONS, `${name}.tsx`)
+  if (existsSync(animation)) return { path: animation, kind: 'animations' }
+  return null
+}
+
 function readConfig(cwd) {
   const file = join(cwd, CONFIG_NAME)
   if (!existsSync(file)) return null
@@ -135,14 +194,19 @@ function readConfig(cwd) {
   }
 }
 
-/** Extrait les imports locaux (alias) d'un fichier source. */
+/** Local imports (alias or relative) of a source file. */
 function localImports(source) {
   const specifiers = new Set()
   const importRe = /(?:from\s+|import\s*\(\s*|import\s+)['"]([^'"]+)['"]/g
   let match
   while ((match = importRe.exec(source)) !== null) {
     const specifier = match[1]
-    if (specifier.startsWith('@/') || specifier.startsWith('~/')) {
+    if (
+      specifier.startsWith('@/') ||
+      specifier.startsWith('~/') ||
+      specifier.startsWith('./') ||
+      specifier.startsWith('../')
+    ) {
       specifiers.add(specifier)
     }
   }
@@ -276,12 +340,14 @@ function collectFiles(entryPath, srcRoot) {
 
     const source = readFileSync(current, 'utf8')
     for (const specifier of localImports(source)) {
-      const base = specifier.replace(/^[@~]\//, '')
+      const base = specifier.startsWith('.')
+        ? resolve(dirname(current), specifier)
+        : join(srcRoot, specifier.replace(/^[@~]\//, ''))
       const candidates = [
-        join(srcRoot, `${base}.ts`),
-        join(srcRoot, `${base}.tsx`),
-        join(srcRoot, base, 'index.ts'),
-        join(srcRoot, base, 'index.tsx'),
+        `${base}.ts`,
+        `${base}.tsx`,
+        join(base, 'index.ts'),
+        join(base, 'index.tsx'),
       ]
       const found = candidates.find((candidate) => existsSync(candidate))
       if (found) queue.push(found)
@@ -389,19 +455,276 @@ ${darkTokens.join('\n')}
 `
 }
 
-/** CSS global du projet (celui qui importe Tailwind), sinon null. */
+/** Every stylesheet of the project, outside the build/ignored folders. */
+function listCssFiles(cwd) {
+  const found = []
+  const walk = (dir, depth) => {
+    if (depth > MAX_SCAN_DEPTH) return
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith('.') || IGNORED_DIRS.has(entry.name)) continue
+        walk(full, depth + 1)
+      } else if (/\.css$/i.test(entry.name)) {
+        found.push(full)
+      }
+    }
+  }
+  walk(resolve(cwd), 0)
+  return found.sort()
+}
+
+/**
+ * CSS global du projet: celui qui importe Tailwind en priorité, quel que soit
+ * son chemin (src/index.css, src/styles/globals.css, app/globals.css…).
+ */
 function findGlobalCss(cwd) {
-  for (const candidate of GLOBAL_CSS_CANDIDATES) {
-    const file = join(cwd, candidate)
-    if (!existsSync(file)) continue
-    const source = readFileSync(file, 'utf8')
-    if (/@import\s+['"]tailwindcss|@tailwind\b/.test(source)) return file
+  const known = GLOBAL_CSS_CANDIDATES.map((candidate) => join(resolve(cwd), candidate))
+  const candidates = [...new Set([...known, ...listCssFiles(cwd)])].filter((file) =>
+    existsSync(file),
+  )
+  const withTailwind = candidates.find((file) => TAILWIND_ENTRY.test(readFileSync(file, 'utf8')))
+  return withTailwind ?? candidates[0] ?? null
+}
+
+/** A dependency of the target project's manifest? */
+function hasDependency(cwd, name) {
+  const file = join(cwd, 'package.json')
+  if (!existsSync(file)) return false
+  try {
+    const manifest = JSON.parse(readFileSync(file, 'utf8'))
+    return ['dependencies', 'devDependencies', 'peerDependencies'].some((key) =>
+      Boolean(manifest[key]?.[name]),
+    )
+  } catch {
+    return false
   }
-  for (const candidate of GLOBAL_CSS_CANDIDATES) {
-    const file = join(cwd, candidate)
-    if (existsSync(file)) return file
+}
+
+/**
+ * Tailwind must be installed *and* imported by a CSS file: writing the tokens
+ * is not enough, without Tailwind the classes (bg-primary, fixed…) do not exist.
+ */
+function tailwindStatus(cwd, globalCss) {
+  const hasTailwind = hasDependency(cwd, 'tailwindcss')
+  const hasEntry =
+    Boolean(globalCss) &&
+    existsSync(globalCss) &&
+    TAILWIND_ENTRY.test(readFileSync(globalCss, 'utf8'))
+  return { hasDependency: hasTailwind, hasEntry }
+}
+
+/** Package manager of the target project, from its lockfile. */
+function packageManager(cwd, dev = true) {
+  const flag = dev ? ['-D'] : []
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return { command: 'pnpm', args: ['add', ...flag] }
+  if (existsSync(join(cwd, 'yarn.lock'))) return { command: 'yarn', args: ['add', ...flag] }
+  if (existsSync(join(cwd, 'bun.lockb')) || existsSync(join(cwd, 'bun.lock'))) {
+    return { command: 'bun', args: ['add', ...(dev ? ['-d'] : [])] }
   }
-  return null
+  return { command: 'npm', args: ['install', ...flag] }
+}
+
+/**
+ * The components import npm packages (clsx, lucide-react, hls.js…): install the
+ * ones missing from the manifest so the copied files compile right away.
+ */
+function installDependencies({ cwd, deps, dryRun }) {
+  const missing = [...deps].filter((dep) => !hasDependency(cwd, dep)).sort()
+  const manager = packageManager(cwd, false)
+  const command = [manager.command, ...manager.args, ...missing].join(' ')
+  if (missing.length === 0) return { missing, command }
+
+  if (dryRun) {
+    info(`[dry-run] ${command}`)
+    return { missing, command }
+  }
+  // Not a JS project: nothing to install into, print the command instead.
+  if (!existsSync(join(cwd, 'package.json'))) return { missing, command }
+
+  info(`Installing the npm dependencies: ${command}`)
+  try {
+    execFileSync(manager.command, [...manager.args, ...missing], {
+      cwd,
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+    })
+  } catch {
+    warn('The automatic install failed: run the command above yourself.')
+    return { missing, command }
+  }
+  ok(`Installed: ${missing.join(', ')}`)
+  return { missing: [], command }
+}
+
+const VITE_CONFIGS = [
+  'vite.config.ts',
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.mts',
+  'vite.config.cjs',
+  'vite.config.cts',
+]
+
+/** Modules that load the global CSS in a Vite/React project. */
+const ENTRY_MODULES = [
+  'src/main.tsx',
+  'src/main.jsx',
+  'src/main.ts',
+  'src/main.js',
+  'src/index.tsx',
+  'src/index.jsx',
+  'app/layout.tsx',
+  'app/layout.jsx',
+]
+
+function findFirst(cwd, names) {
+  return names.map((name) => join(cwd, name)).find((file) => existsSync(file)) ?? null
+}
+
+/** Adds `import tailwindcss from '@tailwindcss/vite'` and `tailwindcss()`. */
+function wireViteConfig(source) {
+  if (source.includes('@tailwindcss/vite')) return source
+  const plugins = /plugins\s*:\s*\[/.exec(source)
+  if (!plugins) return null
+  const at = plugins.index + plugins[0].length
+  const next = `${source.slice(0, at)}tailwindcss(), ${source.slice(at)}`
+  const lines = next.split('\n')
+  const lastImport = lines.reduce((last, line, index) => (/^\s*import\s/.test(line) ? index : last), -1)
+  const importLine = "import tailwindcss from '@tailwindcss/vite'"
+  if (lastImport === -1) return `${importLine}\n${next}`
+  lines.splice(lastImport + 1, 0, importLine)
+  return lines.join('\n')
+}
+
+/** Creates the Tailwind entrypoint when the project has no stylesheet at all. */
+function defaultCssPath(cwd) {
+  if (existsSync(join(cwd, 'src'))) return join(cwd, 'src', 'index.css')
+  if (existsSync(join(cwd, 'app'))) return join(cwd, 'app', 'globals.css')
+  return join(cwd, 'index.css')
+}
+
+/**
+ * Installs Tailwind CSS 4 and wires it (CSS entry, entry module, Vite plugin)
+ * when the target project does not have it. Without Tailwind no utility class
+ * exists, so the components would render unstyled.
+ */
+function setupTailwind({ cwd, globalCss, dryRun }) {
+  // Not a JS project (or nothing to install into): keep the manual instructions.
+  if (!existsSync(join(cwd, 'package.json'))) {
+    return { globalCss, reason: 'no-package' }
+  }
+
+  const usesVite = Boolean(findFirst(cwd, VITE_CONFIGS)) || hasDependency(cwd, 'vite')
+  const manager = packageManager(cwd)
+  const packages = usesVite ? ['tailwindcss', '@tailwindcss/vite'] : ['tailwindcss']
+  const command = [manager.command, ...manager.args, ...packages].join(' ')
+
+  if (!hasDependency(cwd, 'tailwindcss')) {
+    if (dryRun) info(`[dry-run] ${command}`)
+    else info(`Tailwind CSS missing, installing it: ${command}`)
+  }
+  if (!dryRun && !hasDependency(cwd, 'tailwindcss')) {
+    try {
+      execFileSync(manager.command, [...manager.args, ...packages], {
+        cwd,
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+      })
+      ok('Tailwind CSS installed')
+    } catch {
+      warn('The automatic install failed.')
+      return { globalCss, reason: 'install-failed' }
+    }
+  }
+
+  // 1. A stylesheet that imports Tailwind.
+  let cssFile = globalCss
+  if (!cssFile) {
+    cssFile = defaultCssPath(cwd)
+    if (dryRun) {
+      info(`[dry-run] create ${relative(cwd, cssFile)} with "@import 'tailwindcss';"`)
+    } else {
+      mkdirSync(dirname(cssFile), { recursive: true })
+      writeFileSync(cssFile, "@import 'tailwindcss';\n", 'utf8')
+      ok(`Tailwind entry created: ${relative(cwd, cssFile)}`)
+    }
+  } else if (!TAILWIND_ENTRY.test(readFileSync(cssFile, 'utf8'))) {
+    if (dryRun) {
+      info(`[dry-run] add "@import 'tailwindcss';" to ${relative(cwd, cssFile)}`)
+    } else {
+      const source = readFileSync(cssFile, 'utf8')
+      writeFileSync(cssFile, `@import 'tailwindcss';\n\n${source}`, 'utf8')
+      ok(`Tailwind imported in ${relative(cwd, cssFile)}`)
+    }
+  }
+
+  // 2. That stylesheet must be loaded by the app entry.
+  const entryModule = findFirst(cwd, ENTRY_MODULES)
+  const loadsCss = Boolean(entryModule) && readFileSync(entryModule, 'utf8').includes(basename(cssFile))
+  if (entryModule && !loadsCss) {
+    if (dryRun) {
+      info(`[dry-run] import ${basename(cssFile)} in ${relative(cwd, entryModule)}`)
+    } else {
+      const specifier = relative(dirname(entryModule), cssFile).replace(/\\/g, '/')
+      const source = readFileSync(entryModule, 'utf8')
+      writeFileSync(
+        entryModule,
+        `import '${specifier.startsWith('.') ? '' : './'}${specifier}'\n${source}`,
+        'utf8',
+      )
+      ok(`CSS imported in ${relative(cwd, entryModule)}`)
+    }
+  }
+
+  // 3. Vite only runs Tailwind through its plugin.
+  if (usesVite) {
+    const config = findFirst(cwd, VITE_CONFIGS)
+    if (!config) {
+      warn('No vite.config.* found: add tailwindcss() to your Vite plugins.')
+    } else {
+      const source = readFileSync(config, 'utf8')
+      const updated = wireViteConfig(source)
+      if (updated === null) {
+        warn(`Add the tailwindcss() plugin in ${relative(cwd, config)} (no "plugins: [" found).`)
+      } else if (updated !== source && dryRun) {
+        info(`[dry-run] add tailwindcss() to ${relative(cwd, config)}`)
+      } else if (updated !== source) {
+        writeFileSync(config, updated, 'utf8')
+        ok(`tailwindcss() plugin added to ${relative(cwd, config)}`)
+      }
+    }
+  } else {
+    info('Tailwind 4 also needs @tailwindcss/postcss in your PostCSS config.')
+  }
+
+  return { globalCss: cssFile, reason: dryRun ? 'dry-run' : 'ready' }
+}
+
+/** Actionable steps instead of a silent unstyled page. */
+function reportMissingTailwind({ cwd, globalCss, themeFile, status }) {
+  const cssLabel = globalCss ? relative(cwd, globalCss) : 'your global CSS'
+  const specifier = globalCss
+    ? `./${relative(dirname(globalCss), themeFile).replace(/\\/g, '/')}`
+    : `./${THEME_FILE}`
+  console.log('')
+  if (!status.hasDependency) {
+    const manager = packageManager(cwd)
+    warn('Tailwind CSS is not installed in this project: the components will render unstyled.')
+    info([manager.command, ...manager.args, 'tailwindcss', '@tailwindcss/vite'].join(' '))
+    info(`Then add "@import 'tailwindcss';" at the top of ${cssLabel}`)
+    info('and tailwindcss() to the Vite plugins (plugins: [react(), tailwindcss()]).')
+  } else {
+    warn(`Tailwind CSS is installed but ${cssLabel} does not import it yet.`)
+    info(`Add "@import 'tailwindcss';" at the top of ${cssLabel}.`)
+  }
+  info(`Then "@import '${specifier}';", or re-run "uifolio add" to wire it automatically.`)
 }
 
 /** Adds `@import './uifolio-theme.css';` right after the Tailwind import. */
@@ -430,7 +753,16 @@ function existingRadius(file) {
 }
 
 function writeTheme({ cwd, accent, radius, dryRun }) {
-  const globalCss = findGlobalCss(cwd)
+  let globalCss = findGlobalCss(cwd)
+
+  // Install + wire Tailwind first: the tokens alone style nothing.
+  if (!tailwindStatus(cwd, globalCss).hasEntry) {
+    console.log('')
+    info('Tailwind CSS is not set up in this project: configuring it.')
+    globalCss = setupTailwind({ cwd, globalCss, dryRun }).globalCss
+  }
+
+  const status = tailwindStatus(cwd, globalCss)
   const themeFile = globalCss
     ? join(dirname(globalCss), THEME_FILE)
     : join(cwd, THEME_FILE)
@@ -450,15 +782,19 @@ function writeTheme({ cwd, accent, radius, dryRun }) {
   ok(`Tailwind theme written to ${label}`)
   info(`--primary: ${finalAccent}${finalRadius === undefined ? '' : ` · --radius: ${finalRadius}px`}`)
 
-  if (globalCss) {
-    const source = readFileSync(globalCss, 'utf8')
-    const specifier = `./${basename(themeFile)}`
-    const updated = wireThemeImport(source, specifier)
-    if (updated !== source) writeFileSync(globalCss, updated, 'utf8')
-    info(`imported in ${relative(cwd, globalCss)} — no hard-coded colors in the components`)
-  } else {
-    info(`Add "@import './${THEME_FILE}';", at the top of your global CSS (the Tailwind one).`)
+  // The tokens only matter once Tailwind actually generates the utilities:
+  // without a `@import 'tailwindcss'`, wiring the theme would look installed
+  // and still render an unstyled page.
+  if (!status.hasEntry) {
+    reportMissingTailwind({ cwd, globalCss, themeFile, status })
+    return
   }
+
+  const source = readFileSync(globalCss, 'utf8')
+  const specifier = `./${basename(themeFile)}`
+  const updated = wireThemeImport(source, specifier)
+  if (updated !== source) writeFileSync(globalCss, updated, 'utf8')
+  info(`imported in ${relative(cwd, globalCss)} — no hard-coded colors in the components`)
 }
 
 /* -------------------------------------------------------------------------- */
@@ -578,6 +914,40 @@ const USAGE_EXAMPLES = {
       <p className="text-sm">Fade in on mount.</p>
     </FadeIn>
   )
+`,
+  },
+  'horizontal-accordion': {
+    body: `  return <HorizontalAccordion count={6} />
+`,
+  },
+  'horizontal-story': {
+    body: `  return (
+    <HorizontalStory
+      count={6}
+      palette={{ mode: 'gradient', from: '#0EA5E9', to: '#8B5CF6' }}
+    />
+  )
+`,
+  },
+  'stacking-cards': {
+    body: `  return (
+    <StackingCards count={6} palette={{ mode: 'solid', color: '#10B981' }} />
+  )
+`,
+  },
+  'scroll-text': {
+    body: `  return (
+    <ScrollText
+      prefix="C"
+      text="Colors light up letter by letter as you scroll."
+    />
+  )
+`,
+  },
+  'image-crossfade': {
+    body: `  return (
+    <ImageCrossfade overlay="linear-gradient(to top, rgba(0,0,0,0.7), transparent)" />
+  )
 `,
   },
   table: {
@@ -737,14 +1107,14 @@ function addJsxUsage(source, exportNames) {
  * Writes (or completes) the chosen file: `@/` imports from the real folder of
  * the components, a working example (`<CalendarExample />`) and its definition.
  */
-function writeUsage({ cwd, target, componentsDir, components, alias, dryRun }) {
+function writeUsage({ cwd, target, components, alias, dryRun }) {
   if (existsSync(target) && statSync(target).isDirectory()) {
     fail(`${relative(cwd, target)} is a folder: give a file (e.g. src/pages/${components[0].name}.tsx).`)
   }
   const created = !existsSync(target)
   const entries = components.map((component) => ({
     exportName: component.exportName,
-    specifier: aliasImport(cwd, componentsDir, component.name, alias),
+    specifier: aliasImport(cwd, component.dir, component.name, alias),
     example: exampleFor(component),
   }))
   const label = relative(cwd, target)
@@ -823,15 +1193,26 @@ const ALIASES = {
   shortcuts: 'command-menu',
   upload: 'file-upload',
   video: 'video-player',
+  storytelling: 'horizontal-story',
+  stacking: 'stacking-cards',
 }
 
 function commandList() {
-  const components = listComponents()
-  if (components.length === 0) fail('No component found in the registry.')
+  const components = listUiComponents()
+  const animations = listAnimationComponents()
+  if (components.length === 0 && animations.length === 0) {
+    fail('No component found in the registry.')
+  }
   console.log('\nAvailable components:\n')
   for (const name of components) {
     console.log(`  \x1b[36m${name.padEnd(20)}\x1b[0m src/components/ui/${name}.tsx`)
   }
+  if (animations.length > 0) {
+    console.log('\nAvailable animations:\n')
+    for (const name of animations) {
+      console.log(`  \x1b[36m${name.padEnd(20)}\x1b[0m src/components/animations/${name}.tsx`)
+    }
+  }
   console.log('\nUsage: uifolio add <name> [--cwd <target project>]\n')
 }
 
@@ -843,12 +1224,14 @@ function commandInit({ flags }) {
   const config = {
     $schema: 'https://uifolio.dev/schema.json',
     dir: typeof flags.dir === 'string' ? flags.dir : DEFAULT_COMPONENTS_DIR,
+    animations:
+      typeof flags.animations === 'string' ? flags.animations : DEFAULT_ANIMATIONS_DIR,
     lib: typeof flags.lib === 'string' ? flags.lib : 'src/lib',
     alias: typeof flags.alias === 'string' ? flags.alias : '@',
   }
   writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
   ok(`${CONFIG_NAME} written to ${cwd}`)
-  info(`dir: ${config.dir} · lib: ${config.lib} · alias: ${config.alias}`)
+  info(`dir: ${config.dir} · animations: ${config.animations} · lib: ${config.lib} · alias: ${config.alias}`)
   info('Next: uifolio add video-player calendar …')
 }
 
@@ -928,13 +1311,21 @@ async function commandAdd({ positional, flags }) {
 
   const prompter = createPrompter(flags)
   try {
-    // 1. Dossier d'import des composants : toujours src/components/ui.
+    // 1. Dossiers d'import : composants, animations et helpers.
     const componentsDir = normalizeComponentsDir(
       typeof flags.dir === 'string' ? flags.dir : config.dir ?? DEFAULT_COMPONENTS_DIR,
     )
     if (looksLikeFile(componentsDir)) {
       fail(`"${componentsDir}" is a file: give a folder (e.g. ${DEFAULT_COMPONENTS_DIR}).`)
     }
+    const animationsDir = normalizeComponentsDir(
+      typeof flags.animations === 'string'
+        ? flags.animations
+        : config.animations ?? DEFAULT_ANIMATIONS_DIR,
+    )
+    if (looksLikeFile(animationsDir)) {
+      fail(`"${animationsDir}" is a file: give a folder (e.g. ${DEFAULT_ANIMATIONS_DIR}).`)
+    }
 
     // 2. Copie des fichiers + helpers.
     const deps = new Set(LIB_DEPS)
@@ -944,14 +1335,26 @@ async function commandAdd({ positional, flags }) {
     const components = []
 
     for (const name of names) {
-      const entry = join(REGISTRY_UI, `${name}.tsx`)
-      const files = collectFiles(entry, REGISTRY_SRC)
-      components.push({ name, exportName: componentExportName(readFileSync(entry, 'utf8'), name) })
+      const entry = registryEntry(name)
+      const files = collectFiles(entry.path, REGISTRY_SRC)
+      const dir = entry.kind === 'animations' ? animationsDir : componentsDir
+      components.push({
+        name,
+        exportName: componentExportName(readFileSync(entry.path, 'utf8'), name),
+        dir,
+      })
 
       for (const [absolute, relativePath] of files) {
-        const isUi = relativePath.startsWith(join('components', 'ui'))
-        const destinationRoot = isUi ? resolve(cwd, componentsDir) : resolve(cwd, libDir)
-        const destination = join(destinationRoot, relativePath.replace(/^(components\/ui|lib)\//, ''))
+        const segments = relativePath.split(sep)
+        const kind = segments[0] === 'components' ? segments[1] : segments[0]
+        const destinationRoot =
+          kind === 'ui'
+            ? resolve(cwd, componentsDir)
+            : kind === 'animations'
+              ? resolve(cwd, animationsDir)
+              : resolve(cwd, libDir)
+        const inner = kind === 'lib' ? relativePath.slice('lib'.length + 1) : segments.slice(2).join(sep)
+        const destination = join(destinationRoot, inner)
         if (destinations.has(destination)) continue
         destinations.add(destination)
 
@@ -982,7 +1385,10 @@ async function commandAdd({ positional, flags }) {
       info(`${skipped.length} file(s) already present, skipped: ${skipped.join(', ')} (use --force to overwrite)`)
     }
 
-    // 3. Tokens Tailwind : les classes bg-primary & co fonctionnent partout.
+    // 3. npm dependencies imported by the copied files.
+    const dependencies = installDependencies({ cwd, deps, dryRun })
+
+    // 4. Tokens Tailwind : les classes bg-primary & co fonctionnent partout.
     writeTheme({ cwd, accent, radius, dryRun })
 
     // 4. Component usage, after installation.
@@ -999,19 +1405,18 @@ async function commandAdd({ positional, flags }) {
       writeUsage({
         cwd,
         target: pageTarget,
-        componentsDir,
         components,
         alias: targetAlias,
         dryRun,
       })
     }
 
-    if (written.size > 0 || dryRun) {
+    if (targetAlias !== '@') {
+      info(`Remember to align the ${targetAlias} alias in your tsconfig/vite (instead of @/).`)
+    }
+    if (dependencies.missing.length > 0 && !dryRun && written.size > 0) {
       console.log('\n  Detected npm dependencies:')
-      info(`npm install ${[...deps].sort().join(' ')}`)
-      if (targetAlias !== '@') {
-        info(`Remember to align the ${targetAlias} alias in your tsconfig/vite (instead of @/).`)
-      }
+      info(dependencies.command)
       console.log('')
     }
   } finally {
@@ -1034,6 +1439,7 @@ function usage() {
 Options:
   --cwd <dir>       target project (default: current directory)
   --dir <path>      components folder (default: src/components/ui)
+  --animations <path>  animations folder (default: src/components/animations)
   --lib <path>      helpers folder (default: src/lib)
   --alias <alias>   target import alias (default: @)
   --color <hex>     primary color, written in the Tailwind tokens (@theme)
@@ -1046,14 +1452,22 @@ Options:
 
 Without --page, the CLI asks whether a file is already ready to receive the
 components: they are added to that file, to a new folder + file, or installed
-only. Files go to src/components/ui (override with --dir) and the page imports
-them through the alias (@/components/ui/...). The page also gets a working
-example, with the data and props each component needs, so it shows immediately.
+only. Components go to src/components/ui (override with --dir), animations to
+src/components/animations (override with --animations), and the page imports
+them through the alias (@/components/ui/..., @/components/animations/...). The
+page also gets a working example, with the data and props each component needs,
+so it shows immediately.
 Colors go through a Tailwind CSS 4 theme (uifolio-theme.css, @theme), so classes
-like bg-primary and text-muted-foreground stay in the code.
+like bg-primary and text-muted-foreground stay in the code. When Tailwind is
+missing, "add" installs it (with your lockfile's package manager), creates the
+CSS entry, imports it in the app entry and adds the tailwindcss() Vite plugin;
+without Tailwind no utility class exists and the components render unstyled.
+The npm packages the components import (clsx, lucide-react, hls.js…) are
+installed too, as runtime dependencies, when the manifest lacks them.
 
 Examples:
   node cli/uifolio.mjs add video-player calendar otp --cwd ../my-project
+  node cli/uifolio.mjs add horizontal-accordion storytelling --cwd ../my-project
   node cli/uifolio.mjs add otp --color "#10B981" --radius 8
   node cli/uifolio.mjs add calendar --page src/pages/calendar.tsx
 `)