uifolio 0.5.1 → 0.5.4

package/cli/uifolio.mjs

@@ -1,37 +1,37 @@
 #!/usr/bin/env node
 /**
- * uifolio — CLI façon shadcn : copie les composants de la librairie
- * dans un autre projet, avec les helpers dont ils dépendent.
+ * uifolio — shadcn-like CLI: copies the library components into another
+ * project, along with the helpers they depend on.
  *
- * Commandes :
- *   uifolio list                          liste des composants disponibles
- *   uifolio init [--cwd dir]              écrit uifolio.json (config cible)
- *   uifolio add <noms...> [options]       copie les composants + helpers,
- *                                        écrit les tokens Tailwind et utilise
- *                                        le composant dans une page
+ * Commands:
+ *   uifolio list                          list available components
+ *   uifolio init [--cwd dir]              write uifolio.json (target config)
+ *   uifolio add <names...> [options]      copy components + helpers, write the
+ *                                        Tailwind tokens and use the
+ *                                        component in a page
  *
- * Options :
- *   --cwd <dir>          projet cible (défaut : répertoire courant)
- *   --dir <chemin>       dossier des composants (défaut : src/components/ui)
- *   --lib <chemin>       dossier des helpers (défaut : src/lib)
- *   --alias <alias>      alias d'import cible (défaut : @)
- *   --color <hex>        couleur primaire, écrite dans les tokens Tailwind (@theme)
- *   --radius <px>        écrit --radius dans uifolio-theme.css
- *   --page <chemin>      fichier où utiliser le composant (créé s'il n'existe pas)
- *   --interactive        force les questions même quand stdin n'est pas un terminal
- *   --force              écrase les fichiers existants
- *   --dry-run            affiche ce qui serait copié sans rien écrire
+ * Options:
+ *   --cwd <dir>          target project (default: current directory)
+ *   --dir <path>         components folder (default: src/components/ui)
+ *   --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>        writes --radius in uifolio-theme.css
+ *   --page <path>        file where the component is used (created if missing)
+ *   --interactive        ask the questions even when stdin is not a terminal
+ *   --force              overwrite existing files
+ *   --dry-run            print what would be copied without writing anything
  *
- * Sans --dir / --page, la CLI demande interactivement (terminal) dans quel
- * dossier copier les composants et dans quel fichier les utiliser.
+ * Without --page, the CLI asks interactively (terminal) where to use them.
+ * The components always land in src/components/ui unless --dir overrides it.
  *
- * Exemples :
- *   node cli/uifolio.mjs add calendar otp --cwd ../mon-projet
+ * Examples:
+ *   node cli/uifolio.mjs add calendar otp --cwd ../my-project
  *   node cli/uifolio.mjs add calendar --color "#10B981" --page src/pages/calendar.tsx
  *   node cli/uifolio.mjs add video-player --alias "#lib" --dry-run
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 import { fileURLToPath } from 'node:url'
@@ -41,21 +41,17 @@ const REGISTRY_SRC = resolve(HERE, '..', 'src')
 const REGISTRY_UI = join(REGISTRY_SRC, 'components', 'ui')
 const CONFIG_NAME = 'uifolio.json'
 
-const LIB_DEPS = ['clsx', 'tailwind-merge'] // cn() — toujours copié avec les helpers
+const LIB_DEPS = ['clsx', 'tailwind-merge'] // cn() — always copied with the helpers
 
 const DEFAULT_ACCENT = '#10b981'
 const DEFAULT_COMPONENTS_DIR = 'src/components/ui'
 const THEME_FILE = 'uifolio-theme.css'
 
-/** Fichiers CSS globaux candidats pour brancher le thème Tailwind. */
+/** Global CSS candidates for wiring the Tailwind theme. */
 const GLOBAL_CSS_CANDIDATES = [
   'src/index.css',
   'src/app.css',
   'src/globals.css',
-  'src/styles.css',
-  'src/main.css',
-  'app/globals.css',
-  'styles/globals.css',
 ]
 
 /* -------------------------------------------------------------------------- */
@@ -96,6 +92,31 @@ function parseArgs(argv) {
   return { positional, flags }
 }
 
+/** A “folder” answer must not be a file path (page.tsx, index.css…). */
+const FILE_LIKE = /\.(?:[cm]?[jt]sx?|css|scss|sass|less|html|json|md|vue|svelte)$/i
+
+function looksLikeFile(value) {
+  return FILE_LIKE.test(value.trim())
+}
+
+/** « ./src/ui/ » → « src/ui » */
+function normalizeComponentsDir(value) {
+  return value.trim().replace(/^\.\//, '').replace(/\/+$/, '')
+}
+
+/** Readable write error instead of a stack trace (EACCES, ENOTDIR…). */
+function writeFailure(error, target) {
+  const reasons = {
+    EACCES: 'permission denied',
+    EPERM: 'permission denied',
+    EROFS: 'read-only filesystem',
+    ENOSPC: 'no space left on device',
+    ENOTDIR: 'a file is in the way',
+    ENOENT: 'path not found',
+  }
+  fail(`Cannot write ${target}: ${reasons[error?.code] ?? error?.message ?? error}.`)
+}
+
 function listComponents() {
   if (!existsSync(REGISTRY_UI)) return []
   return readdirSync(REGISTRY_UI)
@@ -128,7 +149,7 @@ function localImports(source) {
   return [...specifiers]
 }
 
-/** Dépendances npm externes (hors React) d'un fichier source. */
+/** External npm dependencies (excluding React) of a source file. */
 function externalDeps(source) {
   const deps = new Set()
   const importRe = /from\s+['"]([^'"]+)['"]/g
@@ -143,13 +164,14 @@ function externalDeps(source) {
   return [...deps]
 }
 
-/** Nom réellement exporté par le fichier (otp-input → OtpInput). */
+/** Real exported name of the file (otp-input → OtpInput, icon-picker → IconPicker). */
 function componentExportName(source, fallback) {
-  const matches = [...source.matchAll(/export\s+function\s+([A-Z][A-Za-z0-9_]*)/g)].map((match) => match[1])
-  return matches[0] ?? fallback
+  const exported = [...source.matchAll(/export\s+function\s+([A-Z][A-Za-z0-9_]*)/g)].map((match) => match[1])
+  const pascal = fallback.replace(/(^|-)([a-z0-9])/g, (_, __, char) => char.toUpperCase())
+  return exported.find((name) => name === pascal) ?? exported[0] ?? fallback
 }
 
-/** Fichiers .tsx de src/pages/ du projet cible, triés. */
+/** .tsx files under src/pages of the target project, sorted. */
 function listPagesInCwd(cwd) {
   try {
     const pagesDir = join(resolve(cwd), 'src', 'pages')
@@ -163,7 +185,7 @@ function listPagesInCwd(cwd) {
   }
 }
 
-/** Fichiers où l'usage du composant peut atterrir (indices affichés). */
+/** Files where the component usage may land (flags shown). */
 function usageCandidates(cwd) {
   const app = existsSync(join(resolve(cwd), 'src', 'App.tsx')) ? 'src/App.tsx' : null
   const pages = listPagesInCwd(cwd).filter((page) => page !== app)
@@ -172,7 +194,7 @@ function usageCandidates(cwd) {
 
 /**
  * Saisie interactive : uniquement sur un terminal (ou avec --interactive),
- * jamais en CI / pipe sans données, pour ne pas bloquer l'installation.
+ * never in CI / pipe without data, to avoid blocking the installation.
  */
 function createPrompter(flags) {
   const allowed = Boolean(flags.interactive) || process.stdin.isTTY === true
@@ -200,22 +222,36 @@ function createPrompter(flags) {
     }
   })
 
-  return {
-    async ask(question, fallback) {
-      const suffix = fallback ? ` (${fallback})` : ''
-      process.stdout.write(`\n  \x1b[36m?\x1b[0m ${question}${suffix} : `)
-
-      let answer
-      if (queued.length > 0) answer = queued.shift()
-      else if (closed) answer = null
-      else answer = await new Promise((resolveLine) => {
+  async function ask(question, fallback) {
+    const text = question.trim().replace(/\?+$/, '')
+    const suffix = fallback ? ` (${fallback})` : ''
+    process.stdout.write(`\n  \x1b[36m${text}${suffix} ?\x1b[0m `)
+
+    let answer
+    if (queued.length > 0) answer = queued.shift()
+    else if (closed) answer = null
+    else
+      answer = await new Promise((resolveLine) => {
         waiting = resolveLine
       })
 
-      // stdin fermé (pipe sans données) : on garde la valeur par défaut.
-      if (answer === null) return fallback
-      const trimmed = answer.trim()
-      return trimmed === '' ? fallback : trimmed
+    // stdin closed (pipe without data): keep the default value.
+    if (answer === null) return fallback
+    const trimmed = answer.trim()
+    return trimmed === '' ? fallback : trimmed
+  }
+
+  return {
+    ask,
+    /** y / yes / n / no (French values tolerated as fallback). */
+    async confirm(question, fallback = false) {
+      const answer = await ask(question, fallback ? 'Y/n' : 'y/N')
+      const value = String(answer ?? '')
+        .trim()
+        .toLowerCase()
+      if (['y', 'yes', 'o', 'oui'].includes(value)) return true
+      if (['n', 'no', 'non'].includes(value)) return false
+      return fallback
     },
     close() {
       if (closed) return
@@ -226,12 +262,12 @@ function createPrompter(flags) {
 }
 
 /**
- * Résolution transitive : un composant importe des helpers (@/lib/…)
- * qui peuvent eux-mêmes importer d'autres fichiers locaux.
+ * Transitive resolution: a component imports helpers (@/lib/…)
+ * which may themselves import other local files.
  */
 function collectFiles(entryPath, srcRoot) {
   const queue = [entryPath]
-  const visited = new Map() // chemin absolu -> chemin relatif à src/
+  const visited = new Map() // absolute path -> relative path from src/
 
   while (queue.length > 0) {
     const current = queue.shift()
@@ -249,7 +285,7 @@ function collectFiles(entryPath, srcRoot) {
       ]
       const found = candidates.find((candidate) => existsSync(candidate))
       if (found) queue.push(found)
-      else fail(`Import local introuvable : ${specifier} (depuis ${relative(srcRoot, current)})`)
+      else fail(`Local import not found: ${specifier} (from ${relative(srcRoot, current)})`)
     }
   }
 
@@ -282,14 +318,14 @@ function isLightHex(hex) {
 }
 
 /* -------------------------------------------------------------------------- */
-/* Thème Tailwind CSS 4                                                       */
+/* Tailwind CSS 4 theme                                                      */
 /* -------------------------------------------------------------------------- */
 
 /**
  * Les composants utilisent uniquement des classes Tailwind (`bg-primary`,
  * `text-muted-foreground`, `border-border`…). Pour que ces classes existent,
- * Tailwind 4 doit connaître les tokens via `@theme` : un simple `:root`
- * ne génère aucune classe utilitaire.
+ * Tailwind 4 must discover the tokens via `@theme`: a plain `:root`
+ * generates no utility class.
  */
 function buildThemeCss({ accent, radius }) {
   const foreground = isLightHex(accent) ? '#0f172a' : '#ffffff'
@@ -325,7 +361,7 @@ function buildThemeCss({ accent, radius }) {
     '  color-scheme: dark;',
   ]
 
-  return `/* uifolio — tokens Tailwind CSS 4 : les classes bg-primary, text-muted-foreground… viennent d'ici. */
+  return `/* uifolio — Tailwind CSS 4 tokens: bg-primary, text-muted-foreground… come from here. */
 :root {
 ${rootTokens.join('\n')}
 }
@@ -368,7 +404,7 @@ function findGlobalCss(cwd) {
   return null
 }
 
-/** Ajoute `@import './uifolio-theme.css';` juste après l'import de Tailwind. */
+/** Adds `@import './uifolio-theme.css';` right after the Tailwind import. */
 function wireThemeImport(source, specifier) {
   const line = `@import '${specifier}';`
   if (source.includes(specifier)) return source
@@ -379,14 +415,14 @@ function wireThemeImport(source, specifier) {
   return lines.join('\n')
 }
 
-/** `--primary` déjà défini dans un CSS (hex uniquement), sinon null. */
+/** `--primary` already defined in a CSS (hex only), otherwise null. */
 function existingAccent(file) {
   if (!file || !existsSync(file)) return null
   const match = /--primary:\s*(#[0-9a-f]{6})\s*;/i.exec(readFileSync(file, 'utf8'))
   return match ? match[1].toLowerCase() : null
 }
 
-/** `--radius` déjà défini dans un CSS, sinon undefined. */
+/** `--radius` already defined in a CSS, otherwise undefined. */
 function existingRadius(file) {
   if (!file || !existsSync(file)) return undefined
   const match = /--radius:\s*(\d+(?:\.\d+)?)px\s*;/.exec(readFileSync(file, 'utf8'))
@@ -398,20 +434,20 @@ function writeTheme({ cwd, accent, radius, dryRun }) {
   const themeFile = globalCss
     ? join(dirname(globalCss), THEME_FILE)
     : join(cwd, THEME_FILE)
-  // Sans --color / --radius, on garde le thème déjà en place (projet ou UIfolio).
+  // Without --color / --radius, keep the theme already in place (project or UIfolio).
   const finalAccent = accent ?? existingAccent(themeFile) ?? existingAccent(globalCss) ?? DEFAULT_ACCENT
   const finalRadius = radius ?? existingRadius(themeFile)
   const css = buildThemeCss({ accent: finalAccent, radius: finalRadius })
   const label = relative(cwd, themeFile)
 
   if (dryRun) {
-    ok(`[dry-run] thème Tailwind aurait été écrit dans ${label}`)
-    if (globalCss) info(`[dry-run] importé dans ${relative(cwd, globalCss)}`)
+    ok(`[dry-run] Tailwind theme would have been written to ${label}`)
+    if (globalCss) info(`[dry-run] imported in ${relative(cwd, globalCss)}`)
     return
   }
 
   writeFileSync(themeFile, css, 'utf8')
-  ok(`thème Tailwind écrit dans ${label}`)
+  ok(`Tailwind theme written to ${label}`)
   info(`--primary: ${finalAccent}${finalRadius === undefined ? '' : ` · --radius: ${finalRadius}px`}`)
 
   if (globalCss) {
@@ -419,9 +455,9 @@ function writeTheme({ cwd, accent, radius, dryRun }) {
     const specifier = `./${basename(themeFile)}`
     const updated = wireThemeImport(source, specifier)
     if (updated !== source) writeFileSync(globalCss, updated, 'utf8')
-    info(`importé dans ${relative(cwd, globalCss)} — aucune couleur en dur dans les composants`)
+    info(`imported in ${relative(cwd, globalCss)} — no hard-coded colors in the components`)
   } else {
-    info(`Ajoute « @import './${THEME_FILE}'; » en haut de ton CSS global (celui de Tailwind).`)
+    info(`Add "@import './${THEME_FILE}';", at the top of your global CSS (the Tailwind one).`)
   }
 }
 
@@ -429,13 +465,182 @@ function writeTheme({ cwd, accent, radius, dryRun }) {
 /* Usage du composant dans une page                                           */
 /* -------------------------------------------------------------------------- */
 
-/** Chemin d'import relatif, sans extension, en slashs. */
-function importSpecifier(fromDir, target) {
-  const rel = relative(fromDir, target).replace(/\\/g, '/')
-  return rel.startsWith('.') ? rel : `./${rel}`
+/** Import specifier through the project alias: @/components/ui/calendar. */
+function aliasImport(cwd, componentsDir, name, alias) {
+  const relativePath = relative(resolve(cwd), join(resolve(cwd, componentsDir), name))
+    .replace(/\\/g, '/')
+    .replace(/^src\//, '')
+  return `${alias}/${relativePath}`
+}
+
+/**
+ * Example generated with the page: an instance that renders right away.
+ * A bare `<Component />` shows nothing for dialogs, players, radio groups or
+ * the animated wrappers that require children, so these examples carry the
+ * props and data each one needs.
+ */
+const USAGE_EXAMPLES = {
+  'audio-player': {
+    body: `  return (
+    <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 />
+`,
+  },
+  'file-upload': {
+    body: `  return <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."
+    />
+  )
+`,
+  },
+  '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>
+  )
+`,
+  },
+  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>
+  )
+`,
+  },
+  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>
+  )
+`,
+  },
+  motion: {
+    body: `  return (
+    <FadeIn>
+      <p className="text-sm">Fade in on mount.</p>
+    </FadeIn>
+  )
+`,
+  },
+  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}
+    />
+  )
+`,
+  },
 }
 
-/** Insère les imports après le dernier import du fichier. */
+/** 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`,
+    }
+  }
+  return {
+    component,
+    imports: spec.imports ?? [],
+    types: spec.types ?? [],
+    members: spec.members ?? [],
+    code: `function ${component}() {\n${spec.body}}\n`,
+  }
+}
+
+/** 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`
+}
+
+/** 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
@@ -447,7 +652,7 @@ function addImports(source, lines) {
   }
   if (last === -1) return `${missing.join('\n')}\n\n${source}`
 
-  // Un import peut tenir sur plusieurs lignes : on avance jusqu'à la fin.
+  // An import can span several lines: advance to the end of it.
   let end = last
   while (
     end < all.length - 1 &&
@@ -463,7 +668,7 @@ function addImports(source, lines) {
 }
 
 /**
- * Fin de la balise ouvrante du `<` à `start`, sans se laisser piéger par les
+ * End of the opening tag from `<` to `start`, without being tricked by the
  * `>`/apostrophes des attributs et des textes JSX.
  */
 function findOpeningTagEnd(source, start) {
@@ -485,7 +690,7 @@ function findOpeningTagEnd(source, start) {
   return null
 }
 
-/** Ajoute `<Composant />` dans le JSX retourné, sinon un exemple exporté. */
+/** 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))
   if (missing.length === 0) return { source, added: [] }
@@ -502,7 +707,7 @@ function addJsxUsage(source, exportNames) {
     const childIndent = `${indent}  `
     const children = missing.map((name) => `${childIndent}<${name} />`).join('\n')
 
-    // Fragment déjà présent : on insère juste après `<>`.
+    // 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 }
@@ -516,7 +721,7 @@ function addJsxUsage(source, exportNames) {
       return { source: next, added: missing }
     }
 
-    // Élément ouvrant : les composants deviennent ses premiers enfants.
+    // 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 }
   }
@@ -529,48 +734,82 @@ function addJsxUsage(source, exportNames) {
 }
 
 /**
- * Écrit (ou complète) le fichier choisi : imports depuis le dossier réel des
- * composants + appel `<Composant />` dans le JSX.
+ * 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, dryRun }) {
+function writeUsage({ cwd, target, componentsDir, 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 lines = components.map(({ name, exportName }) =>
-    `import { ${exportName} } from '${importSpecifier(dirname(target), join(resolve(cwd, componentsDir), name))}'`,
-  )
+  const entries = components.map((component) => ({
+    exportName: component.exportName,
+    specifier: aliasImport(cwd, componentsDir, component.name, alias),
+    example: exampleFor(component),
+  }))
   const label = relative(cwd, target)
-  const names = components.map((component) => component.exportName)
+
+  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}'`)
+    }
+  }
+
+  const orderedImports = [...imports].sort(
+    (left, right) => Number(left.includes(`'${alias}/`)) - Number(right.includes(`'${alias}/`)),
+  )
 
   if (created) {
     const body = [
-      ...lines,
-      '',
-      `export default function ${names[0]}Page() {`,
-      '  return (',
-      '    <main className="space-y-6 p-6">',
-      ...names.map((name) => `      <${name} />`),
-      '    </main>',
-      '  )',
-      '}',
+      orderedImports.join('\n'),
+      entries.map(({ example }) => example.code.trimEnd()).join('\n\n'),
+      [
+        `export default function ${entries[0].exportName}Page() {`,
+        '  return (',
+        '    <main className="space-y-6 p-6">',
+        ...entries.map(({ example }) => `      <${example.component} />`),
+        '    </main>',
+        '  )',
+        '}',
+      ].join('\n'),
       '',
-    ].join('\n')
+    ].join('\n\n')
     if (!dryRun) {
-      mkdirSync(dirname(target), { recursive: true })
-      writeFileSync(target, body, 'utf8')
+      try {
+        mkdirSync(dirname(target), { recursive: true })
+        writeFileSync(target, body, 'utf8')
+      } catch (error) {
+        writeFailure(error, label)
+      }
     }
-    ok(`${dryRun ? '[dry-run] ' : ''}page créée : ${label}`)
+    ok(`${dryRun ? '[dry-run] ' : ''}page created: ${label}`)
   } else {
     const source = readFileSync(target, 'utf8')
-    const withImports = addImports(source, lines)
-    const { source: updated, added } = addJsxUsage(withImports, names)
-    if (!dryRun) writeFileSync(target, updated, 'utf8')
-    ok(`${dryRun ? '[dry-run] ' : ''}usage ajouté dans ${label}`)
+    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),
+    )
+    if (!dryRun) {
+      try {
+        writeFileSync(target, updated, 'utf8')
+      } catch (error) {
+        writeFailure(error, label)
+      }
+    }
+    ok(`${dryRun ? '[dry-run] ' : ''}usage added to ${label}`)
     if (added.length < names.length) {
       const already = names.filter((name) => !added.includes(name))
-      info(`déjà présent(s), non dupliqué(s) : ${already.join(', ')}`)
+      info(`already present, not duplicated: ${already.join(', ')}`)
     }
   }
 
-  for (const name of names) info(`· <${name} />`)
+  for (const { example } of entries) info(`· <${example.component} />`)
 }
 
 /* -------------------------------------------------------------------------- */
@@ -588,18 +827,18 @@ const ALIASES = {
 
 function commandList() {
   const components = listComponents()
-  if (components.length === 0) fail('Aucun composant trouvé dans le registre.')
-  console.log('\nComposants disponibles :\n')
+  if (components.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`)
   }
-  console.log('\nUsage : uifolio add <nom> [--cwd <projet cible>]\n')
+  console.log('\nUsage: uifolio add <name> [--cwd <target project>]\n')
 }
 
 function commandInit({ flags }) {
   const cwd = resolve(flags.cwd ?? process.cwd())
   const file = join(cwd, CONFIG_NAME)
-  if (existsSync(file) && !flags.force) fail(`${CONFIG_NAME} existe déjà (utilise --force).`)
+  if (existsSync(file) && !flags.force) fail(`${CONFIG_NAME} already exists (use --force).`)
 
   const config = {
     $schema: 'https://uifolio.dev/schema.json',
@@ -608,26 +847,48 @@ function commandInit({ flags }) {
     alias: typeof flags.alias === 'string' ? flags.alias : '@',
   }
   writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
-  ok(`${CONFIG_NAME} écrit dans ${cwd}`)
+  ok(`${CONFIG_NAME} written to ${cwd}`)
   info(`dir: ${config.dir} · lib: ${config.lib} · alias: ${config.alias}`)
-  info('Puis : uifolio add video-player calendar …')
+  info('Next: uifolio add video-player calendar …')
 }
 
 /**
- * Demande le fichier où utiliser le composant, après l'installation.
- * La page proposée par défaut est créée si elle n'existe pas.
+ * Asks where the component should be used, right after installation:
+ * an existing file, a new folder + import file, or no file at all.
  */
-async function chooseUsageTarget({ prompter, cwd, names }) {
+async function chooseUsageTarget({ prompter, cwd, names, exportNames }) {
   const suggestion = `src/pages/${names[0]}.tsx`
+  const pathFormat = `e.g. ${suggestion}`
+  const label = exportNames.join(', ')
   const candidates = usageCandidates(cwd)
-  if (candidates.length > 0) info(`fichiers existants : ${candidates.join(', ')}`)
+  if (candidates.length > 0) info(`existing files: ${candidates.join(', ')}`)
 
-  const answer = await prompter.ask(
-    `Dans quel fichier utiliser ${names.join(', ')} ? « - » pour ne pas l'utiliser`,
-    suggestion,
+  const ready = await prompter.confirm(
+    `Do you already have a file ready to receive the component (${label})`,
+    false,
   )
+
+  let answer
+  if (ready) {
+    answer = await prompter.ask(
+      `In which file should the component (${label}) be copied`,
+      pathFormat,
+    )
+  } else {
+    const create = await prompter.confirm(
+      'Would you like to create a new folder and an import file',
+      true,
+    )
+    if (!create) {
+      info('the component is installed but not used in any file.')
+      return null
+    }
+    answer = await prompter.ask('Please specify the new path', pathFormat)
+  }
+
+  // “ - ”: installation only, like the “no” answer.
   if (!answer || answer === '-') {
-    info('le composant est installé mais n’est utilisé dans aucun fichier.')
+    info('the component is installed but not used in any file.')
     return null
   }
   return resolve(cwd, answer)
@@ -635,7 +896,7 @@ async function chooseUsageTarget({ prompter, cwd, names }) {
 
 async function commandAdd({ positional, flags }) {
   const names = positional.map((name) => ALIASES[name] ?? name)
-  if (names.length === 0) fail('Aucun composant demandé. Ex. : uifolio add calendar otp')
+  if (names.length === 0) fail('No component requested. E.g.: uifolio add calendar otp')
 
   const cwd = resolve(flags.cwd ?? process.cwd())
   const config = readConfig(cwd) ?? {}
@@ -647,33 +908,33 @@ async function commandAdd({ positional, flags }) {
   const colorFlag = typeof flags.color === 'string' ? flags.color : undefined
   const accent = colorFlag === undefined ? null : normalizeHex(colorFlag)
   if (colorFlag !== undefined && !accent) {
-    fail(`Couleur invalide : ${colorFlag}. Utilise un hex comme #10B981.`)
+    fail(`Invalid color: ${colorFlag}. Use a hex value like #10B981.`)
   }
 
   let radius
   if (typeof flags.radius === 'string') {
     radius = Math.round(Number(flags.radius))
     if (!Number.isFinite(radius) || radius < 0 || radius > 24) {
-      fail(`Arrondi invalide : ${flags.radius}. Utilise une valeur entre 0 et 24.`)
+      fail(`Invalid radius: ${flags.radius}. Use a value between 0 and 24.`)
     }
   }
 
   const known = listComponents()
   const unknown = names.filter((name) => !known.includes(name))
   if (unknown.length > 0) {
-    fail(`Composant(s) inconnu(s) : ${unknown.join(', ')}. Lance « uifolio list ».`)
+    fail(`Unknown component(s): ${unknown.join(', ')}. Run "uifolio list".`)
   }
-  if (!dryRun && !existsSync(cwd)) fail(`Répertoire cible introuvable : ${cwd}`)
+  if (!dryRun && !existsSync(cwd)) fail(`Target directory not found: ${cwd}`)
 
   const prompter = createPrompter(flags)
   try {
-    // 1. Dossier d'import des composants.
-    let componentsDir = typeof flags.dir === 'string' ? flags.dir : config.dir ?? DEFAULT_COMPONENTS_DIR
-    if (prompter && typeof flags.dir !== 'string') {
-      const answer = await prompter.ask('Dans quel dossier copier les composants', componentsDir)
-      if (answer) componentsDir = answer
+    // 1. Dossier d'import des composants : toujours src/components/ui.
+    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}).`)
     }
-    componentsDir = componentsDir.replace(/^\.\//, '').replace(/\/+$/, '')
 
     // 2. Copie des fichiers + helpers.
     const deps = new Set(LIB_DEPS)
@@ -701,8 +962,12 @@ async function commandAdd({ positional, flags }) {
         const shouldWrite = force || !existsSync(destination)
         if (shouldWrite) {
           if (!dryRun) {
-            mkdirSync(dirname(destination), { recursive: true })
-            writeFileSync(destination, rewriteAlias(source, targetAlias), 'utf8')
+            try {
+              mkdirSync(dirname(destination), { recursive: true })
+              writeFileSync(destination, rewriteAlias(source, targetAlias), 'utf8')
+            } catch (error) {
+              writeFailure(error, label)
+            }
           }
           written.add(label)
         } else {
@@ -711,27 +976,41 @@ async function commandAdd({ positional, flags }) {
       }
     }
 
-    ok(`${written.size} fichier(s) ${dryRun ? '[dry-run] auraient été copiés' : 'copié(s)'} :`)
+    ok(`${written.size} file(s) ${dryRun ? 'would be copied [dry-run]' : 'copied'}:`)
     for (const label of [...written].sort()) info(`· ${label}`)
     if (skipped.length > 0) {
-      info(`${skipped.length} fichier(s) déjà présent(s), ignoré(s) : ${skipped.join(', ')} (–force pour écraser)`)
+      info(`${skipped.length} file(s) already present, skipped: ${skipped.join(', ')} (use --force to overwrite)`)
     }
 
     // 3. Tokens Tailwind : les classes bg-primary & co fonctionnent partout.
     writeTheme({ cwd, accent, radius, dryRun })
 
-    // 4. Utilisation du composant, après installation.
+    // 4. Component usage, after installation.
     let pageTarget = typeof flags.page === 'string' ? resolve(cwd, flags.page) : null
     if (!pageTarget && prompter) {
-      pageTarget = await chooseUsageTarget({ prompter, cwd, names })
+      pageTarget = await chooseUsageTarget({
+        prompter,
+        cwd,
+        names,
+        exportNames: components.map((component) => component.exportName),
+      })
+    }
+    if (pageTarget) {
+      writeUsage({
+        cwd,
+        target: pageTarget,
+        componentsDir,
+        components,
+        alias: targetAlias,
+        dryRun,
+      })
     }
-    if (pageTarget) writeUsage({ cwd, target: pageTarget, componentsDir, components, dryRun })
 
     if (written.size > 0 || dryRun) {
-      console.log('\n  Dépendances npm détectées :')
+      console.log('\n  Detected npm dependencies:')
       info(`npm install ${[...deps].sort().join(' ')}`)
       if (targetAlias !== '@') {
-        info(`Pense à aligner l'alias ${targetAlias} dans ton tsconfig/vite (remplace de @/).`)
+        info(`Remember to align the ${targetAlias} alias in your tsconfig/vite (instead of @/).`)
       }
       console.log('')
     }
@@ -741,37 +1020,40 @@ async function commandAdd({ positional, flags }) {
 }
 
 /* -------------------------------------------------------------------------- */
-/* Entrée                                                                     */
+/* Prompting                                                                  */
 /* -------------------------------------------------------------------------- */
 
 function usage() {
   console.log(`
-\x1b[1muifolio\x1b[0m — installe les composants UIfolio dans un projet
-
-  \x1b[36muifolio list\x1b[0m                     composants disponibles
-  \x1b[36muifolio init [options]\x1b[0m           écrit uifolio.json dans le projet cible
-  \x1b[36muifolio add <noms...> [options]\x1b[0m  copie les composants + leurs helpers
-
-Options :
-  --cwd <dir>       projet cible (défaut : répertoire courant)
-  --dir <chemin>    dossier composants (défaut : src/components/ui)
-  --lib <chemin>    dossier helpers (défaut : src/lib)
-  --alias <alias>   alias d'import cible (défaut : @)
-  --color <hex>     couleur primaire, écrite dans les tokens Tailwind (@theme)
-  --radius <px>     arrondi global (0–24) dans uifolio-theme.css
-  --page <chemin>   fichier où utiliser le composant (ex : src/pages/calendar.tsx) ;
-                    créé s'il n'existe pas, sinon l'import + <Composant /> y sont ajoutés
-  --interactive     force les questions (dossier, fichier) hors terminal
-  --force           écrase les fichiers existants
-  --dry-run         simule sans écrire
-
-Sans --dir ni --page, la CLI demande dans quel dossier copier les composants
-puis dans quel fichier les utiliser — l'installation ne s'arrête pas à la copie.
-Les couleurs passent par un thème Tailwind CSS 4 (uifolio-theme.css, @theme) :
-les classes bg-primary, text-muted-foreground… restent dans le code.
-
-Exemples :
-  node cli/uifolio.mjs add video-player calendar otp --cwd ../mon-projet
+\x1b[1muifolio\x1b[0m — installs the UIfolio components into a project
+
+  \x1b[36muifolio list\x1b[0m                     list available components
+  \x1b[36muifolio init [options]\x1b[0m           write uifolio.json in the target project
+  \x1b[36muifolio add <names...> [options]\x1b[0m  copy the components + their helpers
+
+Options:
+  --cwd <dir>       target project (default: current directory)
+  --dir <path>      components folder (default: src/components/ui)
+  --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
+  --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.
+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.
+
+Examples:
+  node cli/uifolio.mjs add video-player calendar otp --cwd ../my-project
   node cli/uifolio.mjs add otp --color "#10B981" --radius 8
   node cli/uifolio.mjs add calendar --page src/pages/calendar.tsx
 `)