uifolio 0.6.0 → 0.7.1

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)
@@ -33,19 +34,30 @@
 
 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. */
@@ -146,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'))
@@ -154,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
@@ -164,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)
     }
   }
@@ -305,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)
@@ -778,192 +815,205 @@ function aliasImport(cwd, componentsDir, name, alias) {
  * the animated wrappers that require children, so these examples carry the
  * props and data each one needs.
  */
+/**
+ * Usage generated with the page: an instance that renders right away, inlined
+ * where the component is added. A bare `<Component />` shows nothing for
+ * dialogs, players, radio groups or the animated wrappers that require
+ * children, so these usages carry the props, data and state each one needs.
+ * `setup` holds the statements (hooks, data) that live in the component body,
+ * `jsx` is the element inserted at the chosen line.
+ */
 const USAGE_EXAMPLES = {
   'audio-player': {
-    body: `  return (
-    <AudioPlayer
-      src="/sample.wav"
-      title="Test signal"
-      subtitle="Generated loop · 8 s · WAV"
-      accent="#10B981"
-    />
-  )
+    jsx: `
+<AudioPlayer
+  src="/sample.wav"
+  title="Test signal"
+  subtitle="Generated loop · 8 s · WAV"
+  accent="#10B981"
+/>
 `,
   },
   'video-player': {
-    body: `  return <VideoPlayer sources="/sample-720.mp4" aspectRatio="16/9" muted loop />
-`,
+    jsx: '<VideoPlayer sources="/sample-720.mp4" aspectRatio="16/9" muted loop />',
   },
   'file-upload': {
-    body: `  return <FileUpload accept="image/*,video/*" maxSizeMb={25} maxFiles={3} />
-`,
+    jsx: '<FileUpload accept="image/*,video/*" maxSizeMb={25} maxFiles={3} />',
   },
   choice: {
     imports: ["import { useState } from 'react'"],
-    body: `  const [checked, setChecked] = useState(true)
-
-  return (
-    <Choice
-      checked={checked}
-      onChange={setChecked}
-      label="Email alerts"
-      description="Get a summary every week."
-    />
-  )
+    setup: 'const [checked, setChecked] = useState(true)',
+    jsx: `
+<Choice
+  checked={checked}
+  onChange={setChecked}
+  label="Email alerts"
+  description="Get a summary every week."
+/>
 `,
   },
   'command-menu': {
     imports: ["import { useState } from 'react'"],
-    body: `  const [open, setOpen] = useState(false)
-
-  return (
-    <div className="space-y-3">
-      <button
-        type="button"
-        onClick={() => setOpen(true)}
-        className="rounded-full bg-primary px-4 py-2 text-xs font-medium text-primary-foreground"
-      >
-        Open the palette
-      </button>
-      <CommandMenu
-        open={open}
-        onOpenChange={setOpen}
-        items={[
-          { id: 'home', label: 'Home', group: 'Navigation', action: () => {} },
-          { id: 'components', label: 'Components', group: 'Navigation', action: () => {} },
-        ]}
-      />
-    </div>
-  )
+    setup: 'const [open, setOpen] = useState(false)',
+    jsx: `
+<div className="space-y-3">
+  <button
+    type="button"
+    onClick={() => setOpen(true)}
+    className="rounded-full bg-primary px-4 py-2 text-xs font-medium text-primary-foreground"
+  >
+    Open the palette
+  </button>
+  <CommandMenu
+    open={open}
+    onOpenChange={setOpen}
+    items={[
+      { id: 'home', label: 'Home', group: 'Navigation', action: () => {} },
+      { id: 'components', label: 'Components', group: 'Navigation', action: () => {} },
+    ]}
+  />
+</div>
 `,
   },
   stories: {
     imports: ["import { useState } from 'react'"],
     types: ['StoryItem'],
-    body: `  const [open, setOpen] = useState(false)
-  const items: StoryItem[] = [
-    { type: 'image', src: '/story-1.svg', title: 'Dawn', duration: 5000 },
-    { type: 'text', title: 'Text only', text: 'A story can be plain text.', duration: 5000 },
-  ]
-
-  return (
-    <div className="space-y-3">
-      <button
-        type="button"
-        onClick={() => setOpen(true)}
-        className="rounded-full bg-primary px-4 py-2 text-xs font-medium text-primary-foreground"
-      >
-        Open the stories
-      </button>
-      <Stories items={items} open={open} onOpenChange={setOpen} />
-    </div>
-  )
+    setup: `
+const [open, setOpen] = useState(false)
+const items: StoryItem[] = [
+  { type: 'image', src: '/story-1.svg', title: 'Dawn', duration: 5000 },
+  { type: 'text', title: 'Text only', text: 'A story can be plain text.', duration: 5000 },
+]
+`,
+    jsx: `
+<div className="space-y-3">
+  <button
+    type="button"
+    onClick={() => setOpen(true)}
+    className="rounded-full bg-primary px-4 py-2 text-xs font-medium text-primary-foreground"
+  >
+    Open the stories
+  </button>
+  <Stories items={items} open={open} onOpenChange={setOpen} />
+</div>
 `,
   },
   resizable: {
     members: ['ResizablePanel', 'ResizableHandle'],
-    body: `  return (
-    <ResizablePanelGroup className="h-64 rounded-xl border">
-      <ResizablePanel className="p-4">Left panel</ResizablePanel>
-      <ResizableHandle />
-      <ResizablePanel className="p-4">Right panel</ResizablePanel>
-    </ResizablePanelGroup>
-  )
+    jsx: `
+<ResizablePanelGroup className="h-64 rounded-xl border">
+  <ResizablePanel className="p-4">Left panel</ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel className="p-4">Right panel</ResizablePanel>
+</ResizablePanelGroup>
 `,
   },
   motion: {
-    body: `  return (
-    <FadeIn>
-      <p className="text-sm">Fade in on mount.</p>
-    </FadeIn>
-  )
+    jsx: `
+<FadeIn>
+  <p className="text-sm">Fade in on mount.</p>
+</FadeIn>
+`,
+  },
+  'horizontal-accordion': {
+    jsx: '<HorizontalAccordion count={6} />',
+  },
+  'horizontal-story': {
+    jsx: `
+<HorizontalStory
+  count={6}
+  palette={{ mode: 'gradient', from: '#0EA5E9', to: '#8B5CF6' }}
+/>
 `,
   },
+  'stacking-cards': {
+    jsx: `<StackingCards count={6} palette={{ mode: 'solid', color: '#10B981' }} />`,
+  },
+  'scroll-text': {
+    jsx: `
+<ScrollText
+  prefix="C"
+  text="Colors light up letter by letter as you scroll."
+/>
+`,
+  },
+  'image-crossfade': {
+    jsx: '<ImageCrossfade overlay="linear-gradient(to top, rgba(0,0,0,0.7), transparent)" />',
+  },
   table: {
     imports: ["import { useState } from 'react'"],
     members: ['type TableColumn'],
-    body: `  const [selected, setSelected] = useState<string[]>([])
-  type Row = { id: string; name: string; status: string; total: number }
-  const rows: Row[] = [
-    { id: 'finanx', name: 'Finanx', status: 'Active', total: 0 },
-    { id: 'facebook', name: 'Facebook', status: 'Active', total: 408221304 },
-  ]
-  const columns: TableColumn<Row>[] = [
-    { key: 'name', header: 'Name', cell: (row) => row.name },
-    { key: 'status', header: 'Status', cell: (row) => row.status },
-    { key: 'total', header: 'Total received', cell: (row) => row.total },
-  ]
-
-  return (
-    <Table
-      rows={rows}
-      columns={columns}
-      rowKey={(row) => row.id}
-      selectable
-      selectedKeys={selected}
-      onSelectionChange={setSelected}
-    />
-  )
+    setup: `
+const [selected, setSelected] = useState<string[]>([])
+type Row = { id: string; name: string; status: string; total: number }
+const rows: Row[] = [
+  { id: 'finanx', name: 'Finanx', status: 'Active', total: 0 },
+  { id: 'facebook', name: 'Facebook', status: 'Active', total: 408221304 },
+]
+const columns: TableColumn<Row>[] = [
+  { key: 'name', header: 'Name', cell: (row) => row.name },
+  { key: 'status', header: 'Status', cell: (row) => row.status },
+  { key: 'total', header: 'Total received', cell: (row) => row.total },
+]
+`,
+    jsx: `
+<Table
+  rows={rows}
+  columns={columns}
+  rowKey={(row) => row.id}
+  selectable
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+/>
 `,
   },
 }
 
-/** Example component written next to the page, plus the imports it needs. */
-function exampleFor({ name, exportName }) {
-  const spec = USAGE_EXAMPLES[name]
-  const component = `${exportName}Example`
-  if (!spec) {
-    return {
-      component,
-      imports: [],
-      types: [],
-      members: [],
-      code: `function ${component}() {\n  return <${exportName} />\n}\n`,
-    }
-  }
+/** Template block → lines, without the leading/trailing empty lines. */
+function blockLines(text) {
+  if (text === undefined) return []
+  return text.replace(/^\n/, '').replace(/\n$/, '').split('\n')
+}
+
+/** Usage written for a component: imports, setup statements and JSX element. */
+function usageFor({ name, exportName }) {
+  const spec = USAGE_EXAMPLES[name] ?? {}
   return {
-    component,
+    exportName,
     imports: spec.imports ?? [],
     types: spec.types ?? [],
     members: spec.members ?? [],
-    code: `function ${component}() {\n${spec.body}}\n`,
+    setup: blockLines(spec.setup),
+    jsx: blockLines(spec.jsx ?? `<${exportName} />`),
   }
 }
 
-/** Appends the example components that are not in the file yet. */
-function addExamples(source, examples) {
-  const missing = examples.filter(
-    ({ component }) => !new RegExp(`function\\s+${component}\\s*\\(`).test(source),
-  )
-  if (missing.length === 0) return source
-  return `${source.trimEnd()}\n\n${missing.map(({ code }) => code.trimEnd()).join('\n\n')}\n`
+/** Prefixes every non-empty line with `indent`. */
+function indentLines(lines, indent) {
+  return lines.map((line) => (line.trim() === '' ? '' : `${indent}${line}`))
 }
 
-/** Inserts the imports after the last import of the file. */
-function addImports(source, lines) {
-  const missing = lines.filter((line) => !source.includes(line))
-  if (missing.length === 0) return source
-
-  const all = source.split('\n')
-  let last = -1
-  for (let index = 0; index < all.length; index += 1) {
-    if (/^\s*import\s/.test(all[index])) last = index
-  }
-  if (last === -1) return `${missing.join('\n')}\n\n${source}`
-
-  // An import can span several lines: advance to the end of it.
-  let end = last
-  while (
-    end < all.length - 1 &&
-    end - last < 20 &&
-    !/from\s+['"][^'"]+['"];?\s*$/.test(all[end]) &&
-    !/^import\s+['"][^'"]+['"];?\s*$/.test(all[end])
-  ) {
-    end += 1
+/**
+ * Setup statements, deduplicated (two usages may declare the same state).
+ * Only whole top-level statements are compared: the indented continuation
+ * lines (array entries, closing brackets) always stay with their block.
+ */
+function uniqueSetup(entries) {
+  const seen = new Set()
+  const lines = []
+  for (const entry of entries) {
+    for (const line of entry.setup) {
+      const key = line.trim()
+      if (key === '') continue
+      const statement = line === line.trimStart() && !/^[)\]}]/.test(key)
+      if (statement) {
+        if (seen.has(key)) continue
+        seen.add(key)
+      }
+      lines.push(line)
+    }
   }
-
-  all.splice(end + 1, 0, ...missing)
-  return all.join('\n')
+  return lines
 }
 
 /**
@@ -989,71 +1039,168 @@ function findOpeningTagEnd(source, start) {
   return null
 }
 
-/** Adds `<Composant />` in the returned JSX, otherwise an exported demo. */
-function addJsxUsage(source, exportNames) {
-  const missing = exportNames.filter((name) => !new RegExp(`<${name}[\\s/>]`).test(source))
+/**
+ * Default insertion point: the first child of the returned root element, so the
+ * usage lands inside the existing layout instead of next to it. A self-closing
+ * root cannot receive a sibling, so it is wrapped in a fragment first.
+ */
+function defaultInsertion(source) {
+  const returnMatch = /\breturn\b/.exec(source)
+  const lineOf = (at) => source.slice(0, at).split('\n').length - 1
+  if (!returnMatch) return { source, index: source.split('\n').length - 1 }
+
+  let cursor = returnMatch.index + returnMatch[0].length
+  while (cursor < source.length && /[\s(]/.test(source[cursor])) cursor += 1
+  if (source[cursor] !== '<') return { source, index: lineOf(returnMatch.index) }
+
+  const tag = findOpeningTagEnd(source, cursor)
+  if (!tag) return { source, index: lineOf(cursor) }
+
+  const rootLine = lineOf(cursor)
+  if (source.startsWith('<>', cursor) || !tag.selfClosing) return { source, index: rootLine + 1 }
+
+  const lineStart = source.lastIndexOf('\n', cursor) + 1
+  const indent = /^\s*/.exec(source.slice(lineStart, cursor))?.[0] ?? ''
+  const element = source.slice(cursor, tag.end + 1)
+  const childIndent = `${indent}  `
+  const wrapped = `<>\n${childIndent}${element}\n${indent}</>`
+  return {
+    source: `${source.slice(0, cursor)}${wrapped}${source.slice(tag.end + 1)}`,
+    index: rootLine + 1,
+  }
+}
+
+/** A page whose component has no JSX return yet: the usage becomes a component. */
+function appendUsage(source, entries) {
+  const children = []
+  entries.forEach((entry, position) => {
+    if (position > 0) children.push('')
+    children.push(...indentLines(entry.jsx, '      '))
+  })
+  // A default export already exists: a second one would be invalid syntax.
+  const signature = /\bexport\s+default\b/.test(source)
+    ? `export function ${entries[0].exportName}Usage() {`
+    : 'export default function Page() {'
+  const code = [
+    signature,
+    ...indentLines(uniqueSetup(entries), '  '),
+    '  return (',
+    '    <main className="space-y-6 p-6">',
+    ...children,
+    '    </main>',
+    '  )',
+    '}',
+  ].join('\n')
+  return { source: `${source.trimEnd()}\n\n${code}\n`, added: entries.map((entry) => entry.exportName) }
+}
+
+/**
+ * Inserts the usages at `line` (1-based, in the file as it is before the imports
+ * are added): the content sitting on that line moves right after the inserted
+ * blocks. The setup statements (useState, data…) go at the top of the enclosing
+ * component body, before its `return`, where they can actually run.
+ */
+function insertUsage(source, entries, line) {
+  const missing = entries.filter(
+    ({ exportName }) => !new RegExp(`<${exportName}[\\s/>]`).test(source),
+  )
   if (missing.length === 0) return { source, added: [] }
 
-  const returnMatch = /\breturn\b/.exec(source)
-  let cursor = returnMatch ? returnMatch.index + returnMatch[0].length : -1
-  while (cursor !== -1 && cursor < source.length && /[\s(]/.test(source[cursor])) cursor += 1
-  const rootIndex = cursor !== -1 && source[cursor] === '<' ? cursor : -1
-  const tag = rootIndex === -1 ? null : findOpeningTagEnd(source, rootIndex)
-
-  if (tag) {
-    const lineStart = source.lastIndexOf('\n', rootIndex) + 1
-    const indent = /^\s*/.exec(source.slice(lineStart, rootIndex))?.[0] ?? ''
-    const childIndent = `${indent}  `
-    const children = missing.map((name) => `${childIndent}<${name} />`).join('\n')
-
-    // Fragment already present: insert right after `<>`.
-    if (source.startsWith('<>', rootIndex)) {
-      const next = `${source.slice(0, rootIndex + 2)}\n${children}${source.slice(rootIndex + 2)}`
-      return { source: next, added: missing }
-    }
+  if (line === undefined && !/\breturn\b[\s\S]*?<[A-Za-z>]/.test(source)) {
+    return appendUsage(source, missing)
+  }
+
+  const prepared = line === undefined ? defaultInsertion(source) : { source, index: line - 1 }
+  const lines = prepared.source.split('\n')
+  let index = Math.max(0, Math.min(prepared.index, lines.length))
 
-    // Racine auto-fermante : on l'enveloppe dans un fragment.
-    if (tag.selfClosing) {
-      const element = source.slice(rootIndex, tag.end + 1)
-      const next =
-        `${source.slice(0, rootIndex)}<>\n${children}\n${indent}${element}\n${indent}</>${source.slice(tag.end + 1)}`
-      return { source: next, added: missing }
+  const baseLine = lines[index] ?? lines[index - 1] ?? ''
+  const indent = /^\s*/.exec(baseLine)?.[0] ?? ''
+
+  const block = []
+  for (const entry of missing) {
+    if (block.length > 0) block.push('')
+    block.push(...indentLines(entry.jsx, indent))
+  }
+
+  const setup = uniqueSetup(missing)
+  if (setup.length > 0) {
+    // The enclosing `return` first, otherwise the enclosing function body.
+    let setupIndex = -1
+    for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+      if (/^\s*return\b/.test(lines[cursor])) {
+        setupIndex = cursor
+        break
+      }
     }
+    if (setupIndex === -1) {
+      for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+        if (/^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+[\w$]+/.test(lines[cursor])) {
+          setupIndex = cursor + 1
+          break
+        }
+      }
+    }
+    const setupIndent =
+      setupIndex === -1 ? indent : /^\s*/.exec(lines[setupIndex] ?? '')?.[0] ?? indent
+    if (setupIndex === -1) setupIndex = index
+    lines.splice(setupIndex, 0, ...indentLines(setup, setupIndent))
+    if (setupIndex <= index) index += setup.length
+  }
 
-    // Opening element: the components become its first children.
-    const next = `${source.slice(0, tag.end + 1)}\n${children}${source.slice(tag.end + 1)}`
-    return { source: next, added: missing }
+  lines.splice(index, 0, ...block)
+  return { source: lines.join('\n'), added: missing.map((entry) => entry.exportName) }
+}
+
+/** Inserts the imports after the last import of the file. */
+function addImports(source, lines) {
+  const missing = lines.filter((line) => !source.includes(line))
+  if (missing.length === 0) return source
+
+  const all = source.split('\n')
+  let last = -1
+  for (let index = 0; index < all.length; index += 1) {
+    if (/^\s*import\s/.test(all[index])) last = index
+  }
+  if (last === -1) return `${missing.join('\n')}\n\n${source}`
+
+  // An import can span several lines: advance to the end of it.
+  let end = last
+  while (
+    end < all.length - 1 &&
+    end - last < 20 &&
+    !/from\s+['"][^'"]+['"];?\s*$/.test(all[end]) &&
+    !/^import\s+['"][^'"]+['"];?\s*$/.test(all[end])
+  ) {
+    end += 1
   }
 
-  // JSX introuvable (page sans `return` JSX) : on laisse un exemple utilisable.
-  const example = missing
-    .map((name) => `\nexport function ${name}Example() {\n  return <${name} />\n}\n`)
-    .join('\n')
-  return { source: `${source.trimEnd()}\n${example}`, added: missing }
+  all.splice(end + 1, 0, ...missing)
+  return all.join('\n')
 }
 
 /**
  * Writes (or completes) the chosen file: `@/` imports from the real folder of
- * the components, a working example (`<CalendarExample />`) and its definition.
+ * the components, then the usage inlined in the page (JSX + state), either at
+ * the requested line or inside the returned element.
  */
-function writeUsage({ cwd, target, componentsDir, components, alias, dryRun }) {
+function writeUsage({ cwd, target, components, alias, dryRun, line }) {
   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),
-    example: exampleFor(component),
+    ...usageFor(component),
+    specifier: aliasImport(cwd, component.dir, component.name, alias),
   }))
   const label = relative(cwd, target)
 
   const imports = new Set()
-  for (const { exportName, specifier, example } of entries) {
-    for (const line of example.imports) imports.add(line)
-    imports.add(`import { ${[exportName, ...example.members].join(', ')} } from '${specifier}'`)
-    if (example.types.length > 0) {
-      imports.add(`import type { ${example.types.join(', ')} } from '${specifier}'`)
+  for (const { exportName, specifier, imports: extraImports, types, members } of entries) {
+    for (const importLine of extraImports) imports.add(importLine)
+    imports.add(`import { ${[exportName, ...members].join(', ')} } from '${specifier}'`)
+    if (types.length > 0) {
+      imports.add(`import type { ${types.join(', ')} } from '${specifier}'`)
     }
   }
 
@@ -1062,14 +1209,19 @@ function writeUsage({ cwd, target, componentsDir, components, alias, dryRun }) {
   )
 
   if (created) {
+    const children = []
+    entries.forEach((entry, position) => {
+      if (position > 0) children.push('')
+      children.push(...indentLines(entry.jsx, '      '))
+    })
     const body = [
       orderedImports.join('\n'),
-      entries.map(({ example }) => example.code.trimEnd()).join('\n\n'),
       [
         `export default function ${entries[0].exportName}Page() {`,
+        ...indentLines(uniqueSetup(entries), '  '),
         '  return (',
         '    <main className="space-y-6 p-6">',
-        ...entries.map(({ example }) => `      <${example.component} />`),
+        ...children,
         '    </main>',
         '  )',
         '}',
@@ -1087,13 +1239,8 @@ function writeUsage({ cwd, target, componentsDir, components, alias, dryRun }) {
     ok(`${dryRun ? '[dry-run] ' : ''}page created: ${label}`)
   } else {
     const source = readFileSync(target, 'utf8')
-    const withImports = addImports(source, [...imports])
-    const names = entries.map(({ example }) => example.component)
-    const { source: withUsage, added } = addJsxUsage(withImports, names)
-    const updated = addExamples(
-      withUsage,
-      entries.map(({ example }) => example),
-    )
+    const { source: withUsage, added } = insertUsage(source, entries, line)
+    const updated = addImports(withUsage, [...imports])
     if (!dryRun) {
       try {
         writeFileSync(target, updated, 'utf8')
@@ -1102,13 +1249,15 @@ function writeUsage({ cwd, target, componentsDir, components, alias, dryRun }) {
       }
     }
     ok(`${dryRun ? '[dry-run] ' : ''}usage added to ${label}`)
-    if (added.length < names.length) {
-      const already = names.filter((name) => !added.includes(name))
+    if (added.length < entries.length) {
+      const already = entries
+        .map((entry) => entry.exportName)
+        .filter((name) => !added.includes(name))
       info(`already present, not duplicated: ${already.join(', ')}`)
     }
   }
 
-  for (const { example } of entries) info(`· <${example.component} />`)
+  for (const { exportName } of entries) info(`· <${exportName} />`)
 }
 
 /* -------------------------------------------------------------------------- */
@@ -1122,15 +1271,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')
 }
 
@@ -1142,12 +1302,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 …')
 }
 
@@ -1193,6 +1355,31 @@ async function chooseUsageTarget({ prompter, cwd, names, exportNames }) {
   return resolve(cwd, answer)
 }
 
+/**
+ * Asks where the usage starts in an existing file. The content sitting on that
+ * line moves right after the inserted component, so an empty answer keeps the
+ * automatic placement (inside the returned element).
+ */
+async function askInsertLine({ prompter, cwd, target, label }) {
+  const source = readFileSync(target, 'utf8')
+  const lineCount = source.split('\n').length
+  const suggested = defaultInsertion(source).index + 1
+  info(`${relative(cwd, target)} has ${lineCount} lines.`)
+
+  for (;;) {
+    const answer = await prompter.ask(
+      `At which line should the component (${label}) start (the content on that line moves after it)`,
+      String(suggested),
+    )
+    const text = String(answer ?? '').trim()
+    // Empty answer (or the suggestion): automatic placement, no forced line.
+    if (text === '' || text === String(suggested)) return undefined
+    const value = Number.parseInt(text, 10)
+    if (Number.isInteger(value) && value >= 1 && value <= lineCount + 1) return value
+    warn(`Invalid line: ${text}. Use a number between 1 and ${lineCount + 1}.`)
+  }
+}
+
 async function commandAdd({ positional, flags }) {
   const names = positional.map((name) => ALIASES[name] ?? name)
   if (names.length === 0) fail('No component requested. E.g.: uifolio add calendar otp')
@@ -1227,13 +1414,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)
@@ -1243,14 +1438,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)
 
@@ -1298,13 +1505,24 @@ async function commandAdd({ positional, flags }) {
       })
     }
     if (pageTarget) {
+      const existing =
+        existsSync(pageTarget) && statSync(pageTarget).isFile()
+      let line
+      if (existing && prompter) {
+        line = await askInsertLine({
+          prompter,
+          cwd,
+          target: pageTarget,
+          label: components.map((component) => component.exportName).join(', '),
+        })
+      }
       writeUsage({
         cwd,
         target: pageTarget,
-        componentsDir,
         components,
         alias: targetAlias,
         dryRun,
+        line,
       })
     }
 
@@ -1336,21 +1554,27 @@ 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)
   --radius <px>     global radius (0–24) in uifolio-theme.css
   --page <path>     file where the component is used (e.g. src/pages/calendar.tsx);
-                    created if missing, otherwise the import + <Component /> are added
+                    created if missing, otherwise the import and the usage are inlined
+                    (the CLI asks on which line the component starts)
   --interactive     ask the questions outside a terminal
   --force           overwrite existing files
   --dry-run         simulate without writing
 
 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
+usage is written inside the page's own component, with the props, data and
+state each component needs, so it shows immediately. When the file already
+exists, the CLI asks on which line the component starts: the content on that
+line moves right after it.
 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. When Tailwind is
 missing, "add" installs it (with your lockfile's package manager), creates the
@@ -1361,6 +1585,7 @@ 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
 `)