uifolio 0.7.0 → 0.7.1

package/README.md

@@ -39,13 +39,36 @@ Options: `--cwd <dir>`, `--dir <path>` (default `src/components/ui`), `--animati
 `src/components/animations` (override with `--animations`), and the page imports
 them through the `@/` alias. Without `--page`, the CLI asks where to use them:
 
-1. *Do you already have a file ready to receive the component (…component…) (y/N) ?* `yes` → *In which file should the component (…component…) be copied (e.g. src/pages/calendar.tsx) ?*: the import and a ready-to-render example are added without duplication, and the file is created when missing;
+1. *Do you already have a file ready to receive the component (…component…) (y/N) ?* `yes` → *In which file should the component (…component…) be copied (e.g. src/pages/calendar.tsx) ?*: the import and a ready-to-render usage are added without duplication, and the file is created when missing. When the file already exists, the CLI also asks *At which line should the component (…component…) start (the content on that line moves after it) ?* (an empty answer keeps the automatic placement);
 2. `no` → *Would you like to create a new folder and an import file (Y/n) ?* `yes` → *Please specify the new path (e.g. src/pages/calendar.tsx) ?*: the folder and the file are created; `no` → install only, no file is touched.
 
-The example is a small component (`<CalendarExample />` plus its definition)
-that carries the data and props each component needs (items for `Stories` and
-`CommandMenu`, a source for the players, children for the resizable panels…),
-so the component is visible immediately instead of an empty `<Component />`.
+The usage is written **inside the page's own component**, not in a separate
+`<CalendarExample />` helper: the element, its props and the state or data it
+needs (items for `Stories` and `CommandMenu`, a source for the players,
+children for the resizable panels…) are inlined where the component is added,
+so it is visible immediately instead of an empty `<Component />`. The state and
+data go at the top of the component body, before its `return`.
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+import { Choice } from '@/components/ui/choice'
+
+export default function Home() {
+  const [checked, setChecked] = useState(true)
+  return (
+    <main>
+      <Choice
+        checked={checked}
+        onChange={setChecked}
+        label="Email alerts"
+        description="Get a summary every week."
+      />
+    </main>
+  )
+}
+```
 
 Answering `-` to a path question installs the component without creating or
 modifying any page.

package/cli/uifolio.mjs

@@ -815,226 +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': {
-    body: `  return <HorizontalAccordion count={6} />
-`,
+    jsx: '<HorizontalAccordion count={6} />',
   },
   'horizontal-story': {
-    body: `  return (
-    <HorizontalStory
-      count={6}
-      palette={{ mode: 'gradient', from: '#0EA5E9', to: '#8B5CF6' }}
-    />
-  )
+    jsx: `
+<HorizontalStory
+  count={6}
+  palette={{ mode: 'gradient', from: '#0EA5E9', to: '#8B5CF6' }}
+/>
 `,
   },
   'stacking-cards': {
-    body: `  return (
-    <StackingCards count={6} palette={{ mode: 'solid', color: '#10B981' }} />
-  )
-`,
+    jsx: `<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."
-    />
-  )
+    jsx: `
+<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)" />
-  )
-`,
+    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
 }
 
 /**
@@ -1060,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
+  }
+
+  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
 
-    // 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 }
+  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}`
 
-  // 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 }
+  // 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
+  }
+
+  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, 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,
+    ...usageFor(component),
     specifier: aliasImport(cwd, component.dir, component.name, alias),
-    example: exampleFor(component),
   }))
   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}'`)
     }
   }
 
@@ -1133,14 +1209,19 @@ function writeUsage({ cwd, target, 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>',
         '  )',
         '}',
@@ -1158,13 +1239,8 @@ function writeUsage({ cwd, target, 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')
@@ -1173,13 +1249,15 @@ function writeUsage({ cwd, target, 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} />`)
 }
 
 /* -------------------------------------------------------------------------- */
@@ -1277,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')
@@ -1402,12 +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,
         components,
         alias: targetAlias,
         dryRun,
+        line,
       })
     }
 
@@ -1445,7 +1560,8 @@ Options:
   --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
@@ -1455,8 +1571,10 @@ components: they are added to that file, to a new folder + file, or installed
 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.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uifolio",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "CLI that copies React components (calendar, video/audio players, OTP, editor, upload) and their helpers into your project, with Tailwind CSS 4 tokens.",
   "type": "module",
   "license": "MIT",