@svgrid/ui 0.2.0 → 0.3.0

package/README.md

@@ -1,25 +1,43 @@
 # @svgrid/ui
 
 Add [SvGrid UI](https://www.svgrid.com/docs/help/ui-components) components to your
-app in one command:
+app - and see them - in one command:
 
 ```sh
-npx @svgrid/ui add calendar
+npx @svgrid/ui try calendar     # open it in a throwaway sandbox, no project needed
+npx @svgrid/ui add calendar     # write the recipe into your app + install the dep
 ```
 
 ## How it works
 
 `@svgrid/ui` is a **recipe scaffolder**, not a component library. `add` writes a
 minimal, ready-to-edit `.svelte` starter into your project that imports from
-[`@svgrid/grid`](https://www.npmjs.com/package/@svgrid/grid), then makes sure the
-package is a dependency and prints the install command. The components themselves
-live in `@svgrid/grid` - you get bug fixes and new features by bumping the package,
-while the file `add` drops in is yours to style and wire however you like.
+[`@svgrid/grid`](https://www.npmjs.com/package/@svgrid/grid), and installs the
+package for you. The components themselves live in `@svgrid/grid` - you get bug
+fixes and new features by bumping the package, while the file `add` drops in is
+yours to style and wire however you like. Each recipe is a self-contained demo, so
+`try` and `--preview` can render it immediately.
+
+## See it immediately
+
+```sh
+# zero setup: spins up a sandbox and opens the component in your browser
+npx @svgrid/ui try button
+
+# in your own SvelteKit app: also writes a /preview/button route
+npx @svgrid/ui add button --preview
+#   -> start your dev server, open http://localhost:5173/preview/button
+```
+
+`try` needs no project - it caches a tiny Vite + Svelte sandbox under your temp
+dir (so repeat runs are instant) and opens the browser. `--preview` drops a
+`src/routes/preview/<id>` page (plus a `/preview` index) into an existing
+SvelteKit app so it renders in your running dev server.
 
 ## Usage
 
 ```sh
-# add one component
+# add one component (installs @svgrid/grid)
 npx @svgrid/ui add calendar
 
 # add several, into a custom folder
@@ -28,8 +46,8 @@ npx @svgrid/ui add calendar time-picker --dir src/lib/ui
 # add a whole family
 npx @svgrid/ui add date-time
 
-# install the dependency automatically (default: just prints the command)
-npx @svgrid/ui add calendar --install
+# just write files, don't run the package manager
+npx @svgrid/ui add calendar --no-install
 
 # see what you can add
 npx @svgrid/ui list
@@ -39,9 +57,10 @@ npx @svgrid/ui list
 
 | Flag             | Description                                                              |
 | ---------------- | ------------------------------------------------------------------------ |
+| `--preview`, `-p`| (with `add`) Also write a `src/routes/preview/<id>` route so you can see it in your dev server. SvelteKit apps only. |
 | `--dir <path>`   | Where to write files. Default: `src/lib/components/ui` (or `componentsDir` in a project `svgrid.json`). |
 | `--force`        | Overwrite files that already exist.                                      |
-| `--install`      | Run your package manager to install deps instead of just printing it.    |
+| `--no-install`   | Skip installing the dependency; just print the install command.          |
 
 ## Components
 

package/index.mjs

@@ -1,23 +1,26 @@
 #!/usr/bin/env node
 // @svgrid/ui - add SvGrid UI components to your app, one command at a time.
 //
-//   npx @svgrid/ui add calendar
+//   npx @svgrid/ui add calendar               # add a component (installs the dep)
+//   npx @svgrid/ui add button --preview        # + a /preview/button route to see it
+//   npx @svgrid/ui try button                  # zero-setup: open it in a sandbox
 //   npx @svgrid/ui add calendar time-picker --dir src/lib/ui
-//   npx @svgrid/ui add date-time            # the whole date/time family
+//   npx @svgrid/ui add date-time               # the whole date/time family
 //   npx @svgrid/ui list
 //
 // Recipe-scaffolder model: `add` writes a minimal, ready-to-EDIT .svelte starter
-// that imports from `@svgrid/grid` (which you own and can change), then makes
-// sure the package is a dependency and prints the install command. It does NOT
-// vendor library source - the components live in `@svgrid/grid`.
+// that imports from `@svgrid/grid` (which you own and can change). Each recipe is
+// a self-contained demo, so `--preview` (in your app) and `try` (in a throwaway
+// sandbox) can render it immediately - "one command and see it".
 //
 // Zero runtime dependencies - Node built-ins only.
 
-import { cp, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { cp, mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { stdin, stdout } from 'node:process'
+import { tmpdir } from 'node:os'
+import { stdout } from 'node:process'
 import { spawnSync } from 'node:child_process'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -43,12 +46,16 @@ const PMS = [
 ]
 
 function parseArgs(argv) {
-  const args = { _: [], dir: null, force: false, install: false, help: false, js: false }
+  // install defaults ON: an added component imports @svgrid/grid, so it should
+  // work right away. `--no-install` opts out (just prints the command).
+  const args = { _: [], dir: null, force: false, install: true, preview: false, help: false, js: false }
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '--help' || a === '-h') args.help = true
     else if (a === '--force' || a === '-f') args.force = true
     else if (a === '--install') args.install = true
+    else if (a === '--no-install') args.install = false
+    else if (a === '--preview' || a === '-p') args.preview = true
     else if (a === '--js') args.js = true
     else if (a === '--ts') args.js = false
     else if (a === '--dir' || a === '-d') args.dir = argv[++i]
@@ -82,6 +89,25 @@ function expand(registry, token) {
   return item ? [item] : []
 }
 
+/** Resolve tokens -> unique items in order; exits with a helpful error on unknowns. */
+function collectItems(registry, tokens) {
+  const items = new Map()
+  const unknown = []
+  for (const tok of tokens) {
+    const matched = expand(registry, tok)
+    if (!matched.length) unknown.push(tok)
+    for (const it of matched) items.set(it.id, it)
+  }
+  if (unknown.length) {
+    stdout.write(
+      `${color('red', '✖')} Unknown component(s): ${unknown.join(', ')}\n` +
+        `  See ${color('cyan', 'npx @svgrid/ui list')} for the available set.\n`,
+    )
+    process.exit(1)
+  }
+  return [...items.values()]
+}
+
 /** Walk up from `start` to the nearest directory containing a package.json. */
 function findProjectRoot(start) {
   let dir = start
@@ -93,6 +119,11 @@ function findProjectRoot(start) {
   }
 }
 
+/** A SvelteKit app has file-based routes, so we can drop in a /preview route. */
+function isSvelteKit(root) {
+  return !!root && (existsSync(join(root, 'svelte.config.js')) || existsSync(join(root, 'src', 'routes')))
+}
+
 function detectPm(root) {
   if (!root) return PMS.find((p) => p.id === 'npm')
   return PMS.find((p) => existsSync(join(root, p.lock))) ?? PMS.find((p) => p.id === 'npm')
@@ -140,28 +171,123 @@ async function ensureDeps(projectRoot, deps) {
   return added
 }
 
+/** A valid JS identifier for a component id (time-picker -> C_time_picker). */
+function toIdent(id) {
+  return 'C_' + id.replace(/[^a-zA-Z0-9]/g, '_')
+}
+
+function esc(s) {
+  return String(s ?? '').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/** A SvelteKit `/preview/<id>` page that renders the recipe you just added, so
+ *  you can open it in your dev server. Import is relative to the recipe on disk,
+ *  so it works whether or not the recipe lives under $lib. */
+async function writePreviewRoutes(projectRoot, dest, items, force) {
+  const routesRoot = join(projectRoot, 'src', 'routes', 'preview')
+  const urls = []
+  for (const it of items) {
+    const file = it.files?.[0]
+    if (!file) continue
+    const routeDir = join(routesRoot, it.id)
+    await mkdir(routeDir, { recursive: true })
+    const routeFile = join(routeDir, '+page.svelte')
+    urls.push('/preview/' + it.id)
+    if (existsSync(routeFile) && !force) continue
+    let rel = relative(routeDir, join(dest, file.write)).split('\\').join('/')
+    if (!rel.startsWith('.')) rel = './' + rel
+    await writeFile(
+      routeFile,
+      `<script lang="ts">
+  // Auto-generated by @svgrid/ui to preview the ${it.id} recipe. Yours to edit.
+  import Demo from '${rel}'
+</script>
+
+<div class="svui-preview">
+  <a class="svui-preview__back" href="/preview">&larr; all components</a>
+  <h1 class="svui-preview__title">${esc(it.title ?? it.id)}</h1>
+  <p class="svui-preview__desc">${esc(it.description ?? '')}</p>
+  <div class="svui-preview__stage">
+    <Demo />
+  </div>
+</div>
+
+<style>
+  .svui-preview { max-width: 880px; margin: 0 auto; padding: 32px 24px; font-family: system-ui, sans-serif; }
+  .svui-preview__back { font-size: 13px; color: #6366f1; text-decoration: none; }
+  .svui-preview__title { margin: 12px 0 4px; font-size: 24px; }
+  .svui-preview__desc { margin: 0 0 20px; color: #64748b; font-size: 14px; }
+  .svui-preview__stage { display: flex; flex-wrap: wrap; gap: 12px; align-items: flex-start; padding: 28px; border: 1px solid #e2e8f0; border-radius: 12px; background: #fff; }
+</style>
+`,
+    )
+  }
+  await writePreviewIndex(routesRoot)
+  return urls
+}
+
+/** (Re)generate /preview - an index of every component preview present on disk. */
+async function writePreviewIndex(routesRoot) {
+  let entries = []
+  try {
+    entries = await readdir(routesRoot, { withFileTypes: true })
+  } catch {
+    return
+  }
+  const ids = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort()
+  const links = ids.map((id) => `    <a class="svui-index__link" href="/preview/${id}">${esc(id)}</a>`).join('\n')
+  await writeFile(
+    join(routesRoot, '+page.svelte'),
+    `<script lang="ts">
+  // Auto-generated by @svgrid/ui. Lists the component previews you've added.
+</script>
+
+<div class="svui-index">
+  <h1>Component previews</h1>
+  <div class="svui-index__grid">
+${links}
+  </div>
+</div>
+
+<style>
+  .svui-index { max-width: 880px; margin: 0 auto; padding: 32px 24px; font-family: system-ui, sans-serif; }
+  .svui-index h1 { font-size: 22px; }
+  .svui-index__grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(160px, 1fr)); gap: 10px; margin-top: 16px; }
+  .svui-index__link { padding: 12px 14px; border: 1px solid #e2e8f0; border-radius: 10px; text-decoration: none; color: #0f172a; font-size: 14px; }
+  .svui-index__link:hover { border-color: #6366f1; color: #6366f1; }
+</style>
+`,
+  )
+}
+
 function printHelp() {
   stdout.write(`
 ${color('bold', '@svgrid/ui')} - add SvGrid UI components to your app
 
 ${color('bold', 'Usage')}
-  npx @svgrid/ui add <component...> [--dir <path>] [--force] [--install]
+  npx @svgrid/ui add <component...> [--dir <path>] [--preview] [--force] [--no-install]
+  npx @svgrid/ui try <component...>
   npx @svgrid/ui list
 
 ${color('bold', 'Commands')}
-  ${color('cyan', 'add')}   Write a ready-to-edit recipe for each component into your project.
-  ${color('cyan', 'list')}  Show the components you can add.
+  ${color('cyan', 'add')}    Write a ready-to-edit recipe for each component into your project
+         (and install @svgrid/grid). Add ${color('cyan', '--preview')} to also drop a /preview route.
+  ${color('cyan', 'try')}    Open the component(s) in a throwaway sandbox - no project needed.
+  ${color('cyan', 'list')}   Show the components you can add.
 
 ${color('bold', 'Options')}
+  --preview, -p  (add) Also write a src/routes/preview/<id> route so you can see it
+                 in your running dev server. SvelteKit apps only.
   --dir <path>   Where to write files (default: src/lib/components/ui, or the
                  "componentsDir" in a project svgrid.json).
   --force        Overwrite files that already exist.
-  --install      Run the package manager to install deps (default: just print it).
+  --no-install   Do not run the package manager; just print the install command.
 
 ${color('bold', 'Examples')}
-  npx @svgrid/ui add calendar
+  npx @svgrid/ui try button
+  npx @svgrid/ui add button --preview
   npx @svgrid/ui add calendar time-picker --dir src/lib/ui
-  npx @svgrid/ui add date-time --install
+  npx @svgrid/ui add date-time
 `)
 }
 
@@ -177,7 +303,8 @@ async function cmdList(registry) {
       stdout.write(`  ${color('cyan', id.padEnd(18))} ${color('dim', g.items.join(', '))}\n`)
     }
   }
-  stdout.write(`\n${color('dim', 'Add one with:')} npx @svgrid/ui add ${registry.items[0]?.id ?? 'calendar'}\n\n`)
+  stdout.write(`\n${color('dim', 'Add one with:')} npx @svgrid/ui add ${registry.items[0]?.id ?? 'calendar'}\n`)
+  stdout.write(`${color('dim', 'Or just see it:')} npx @svgrid/ui try ${registry.items[0]?.id ?? 'calendar'}\n\n`)
 }
 
 async function cmdAdd(registry, tokens, args) {
@@ -185,22 +312,7 @@ async function cmdAdd(registry, tokens, args) {
     stdout.write(`${color('red', '✖')} Nothing to add. Try: ${color('cyan', 'npx @svgrid/ui list')}\n`)
     process.exit(1)
   }
-
-  // Resolve tokens -> unique items.
-  const items = new Map()
-  const unknown = []
-  for (const tok of tokens) {
-    const matched = expand(registry, tok)
-    if (!matched.length) unknown.push(tok)
-    for (const it of matched) items.set(it.id, it)
-  }
-  if (unknown.length) {
-    stdout.write(
-      `${color('red', '✖')} Unknown component(s): ${unknown.join(', ')}\n` +
-        `  See ${color('cyan', 'npx @svgrid/ui list')} for the available set.\n`,
-    )
-    process.exit(1)
-  }
+  const items = collectItems(registry, tokens)
 
   const cwd = process.cwd()
   const projectRoot = findProjectRoot(cwd)
@@ -210,7 +322,7 @@ async function cmdAdd(registry, tokens, args) {
   const written = []
   const skipped = []
   const deps = new Set()
-  for (const it of items.values()) {
+  for (const it of items) {
     for (const d of it.deps ?? []) deps.add(d)
     for (const file of it.files ?? []) {
       const outPath = join(dest, file.write)
@@ -228,19 +340,20 @@ async function cmdAdd(registry, tokens, args) {
   for (const f of written) stdout.write(`  ${color('green', '+')} ${relFromCwd(cwd, join(dest, f))}\n`)
   for (const f of skipped)
     stdout.write(`  ${color('yellow', '•')} ${f} ${color('dim', 'already exists (use --force to overwrite)')}\n`)
-  if (!written.length) {
+  if (!written.length && !args.preview) {
     stdout.write(`\n${color('yellow', '!')} No files written.\n\n`)
     return
   }
 
-  // Ensure deps + install.
+  // Ensure deps + install (on by default; --no-install just prints the command).
   const added = await ensureDeps(projectRoot, [...deps])
   const pm = detectPm(projectRoot)
   if (added.length) {
     if (args.install && projectRoot) {
       stdout.write(`\n${color('dim', `Installing with ${pm.id}...`)}\n`)
-      const [bin, ...rest] = pm.add.split(' ')
-      const res = spawnSync(bin, [...rest, ...added], { cwd: projectRoot, stdio: 'inherit', shell: true })
+      // Single shell string (not bin + args[]) so Node doesn't warn DEP0190
+      // under shell:true; the tokens here are fixed pm commands + npm package ids.
+      const res = spawnSync(`${pm.add} ${added.join(' ')}`, { cwd: projectRoot, stdio: 'inherit', shell: true })
       if (res.status !== 0) {
         stdout.write(`${color('yellow', '!')} Install failed - run it yourself: ${color('cyan', `${pm.add} ${added.join(' ')}`)}\n`)
       }
@@ -251,8 +364,22 @@ async function cmdAdd(registry, tokens, args) {
     stdout.write(`\n${color('dim', `${[...deps].join(', ')} already in package.json.`)}\n`)
   }
 
+  // Optional preview route(s).
+  if (args.preview) {
+    if (isSvelteKit(projectRoot)) {
+      const urls = await writePreviewRoutes(projectRoot, dest, items, args.force)
+      stdout.write(`\n${color('green', '✔')} Preview route(s) written. Start your dev server and open:\n`)
+      for (const u of urls) stdout.write(`  ${color('cyan', u)}\n`)
+    } else {
+      stdout.write(
+        `\n${color('yellow', '!')} --preview needs a SvelteKit app (src/routes). ` +
+          `To see it with zero setup: ${color('cyan', `npx @svgrid/ui try ${items[0].id}`)}\n`,
+      )
+    }
+  }
+
   // Usage hint.
-  const first = [...items.values()][0]
+  const first = items[0]
   stdout.write(`\n${color('green', '✔')} Added ${written.length} file(s). They're yours - edit away.\n`)
   if (first) {
     stdout.write(`  ${color('dim', 'Use it:')} import { ${exportName(first.id)} } from '@svgrid/grid'\n`)
@@ -260,6 +387,109 @@ async function cmdAdd(registry, tokens, args) {
   stdout.write(`\n${color('dim', 'Docs:')} https://www.svgrid.com/docs/help/ui-components\n\n`)
 }
 
+/** `try` - render the component(s) in a throwaway Vite + Svelte sandbox and open
+ *  the browser. No project needed. The sandbox is cached under the OS temp dir so
+ *  repeat runs skip the install. */
+async function cmdTry(registry, tokens) {
+  if (!tokens.length) {
+    stdout.write(`${color('red', '✖')} Nothing to try. Try: ${color('cyan', 'npx @svgrid/ui try button')}\n`)
+    process.exit(1)
+  }
+  const items = collectItems(registry, tokens)
+  const sandbox = join(tmpdir(), 'svgrid-ui-try')
+  const src = join(sandbox, 'src')
+  await mkdir(src, { recursive: true })
+
+  // Base app (mirrors the known-good minimal Vite + Svelte 5 setup).
+  await writeFile(
+    join(sandbox, 'package.json'),
+    JSON.stringify(
+      {
+        name: 'svgrid-ui-try',
+        private: true,
+        version: '0.0.0',
+        type: 'module',
+        scripts: { dev: 'vite' },
+        dependencies: { '@svgrid/grid': 'latest' },
+        devDependencies: { '@sveltejs/vite-plugin-svelte': '^7.0.0', svelte: '^5.55.5', vite: '^8.0.10' },
+      },
+      null,
+      2,
+    ) + '\n',
+  )
+  await writeFile(
+    join(sandbox, 'vite.config.js'),
+    `import { svelte } from '@sveltejs/vite-plugin-svelte'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({ plugins: [svelte()] })\n`,
+  )
+  await writeFile(
+    join(sandbox, 'svelte.config.js'),
+    `import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'\n\nexport default { preprocess: vitePreprocess() }\n`,
+  )
+  await writeFile(
+    join(sandbox, 'index.html'),
+    `<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="UTF-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1.0" />\n    <title>@svgrid/ui preview</title>\n  </head>\n  <body>\n    <div id="app"></div>\n    <script type="module" src="/src/main.js"></script>\n  </body>\n</html>\n`,
+  )
+  await writeFile(
+    join(src, 'main.js'),
+    `import { mount } from 'svelte'\nimport App from './App.svelte'\n\nexport default mount(App, { target: document.getElementById('app') })\n`,
+  )
+
+  // Copy each recipe (all its files) and render the primary one.
+  const imports = []
+  const sections = []
+  for (const it of items) {
+    let primary
+    for (const file of it.files ?? []) {
+      await cp(join(RECIPES_DIR, file.from), join(src, file.write))
+      primary ??= file.write
+    }
+    if (!primary) continue
+    const ident = toIdent(it.id)
+    imports.push(`  import ${ident} from './${primary}'`)
+    sections.push(`    <section class="svui-try__item">\n      <h2>${esc(it.title ?? it.id)}</h2>\n      <${ident} />\n    </section>`)
+  }
+  await writeFile(
+    join(src, 'App.svelte'),
+    `<script lang="ts">
+${imports.join('\n')}
+</script>
+
+<main class="svui-try">
+  <header class="svui-try__head">
+    <strong>@svgrid/ui preview</strong>
+    <span>${esc(items.map((i) => i.id).join(', '))}</span>
+  </header>
+${sections.join('\n')}
+</main>
+
+<style>
+  :global(body) { margin: 0; background: #f8fafc; }
+  .svui-try { max-width: 960px; margin: 0 auto; padding: 32px 24px; font-family: system-ui, sans-serif; }
+  .svui-try__head { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: 24px; color: #64748b; }
+  .svui-try__item { padding: 28px; border: 1px solid #e2e8f0; border-radius: 12px; background: #fff; margin-bottom: 16px; }
+  .svui-try__item h2 { margin: 0 0 16px; font-size: 15px; color: #334155; }
+</style>
+`,
+  )
+
+  // Install only when the sandbox isn't already provisioned.
+  const provisioned =
+    existsSync(join(sandbox, 'node_modules', '@svgrid', 'grid')) && existsSync(join(sandbox, 'node_modules', 'vite'))
+  if (!provisioned) {
+    stdout.write(`\n${color('dim', 'Setting up preview sandbox (first run installs deps)...')}\n`)
+    const res = spawnSync('npm install', { cwd: sandbox, stdio: 'inherit', shell: true })
+    if (res.status !== 0) {
+      stdout.write(`${color('red', '✖')} Sandbox install failed.\n`)
+      process.exit(1)
+    }
+  }
+
+  stdout.write(
+    `\n${color('green', '▶')} Opening ${color('cyan', items.map((i) => i.id).join(', '))} ${color('dim', '(Ctrl+C to stop)')}\n`,
+  )
+  spawnSync('npx vite --open', { cwd: sandbox, stdio: 'inherit', shell: true })
+}
+
 /** Component export name from its id (calendar -> SvCalendar, time-picker ->
  *  SvTimePicker). */
 function exportName(id) {
@@ -287,12 +517,15 @@ async function main() {
       return cmdList(registry)
     case 'add':
       return cmdAdd(registry, rest, args)
+    case 'try':
+    case 'preview':
+      return cmdTry(registry, rest)
     default:
       // Treat a bare component id as `add <id>` for convenience.
       if (resolveItem(registry, command) || registry.groups?.[command]) {
         return cmdAdd(registry, [command, ...rest], args)
       }
-      stdout.write(`${color('red', '✖')} Unknown command "${command}". Try ${color('cyan', 'add')} or ${color('cyan', 'list')}.\n`)
+      stdout.write(`${color('red', '✖')} Unknown command "${command}". Try ${color('cyan', 'add')}, ${color('cyan', 'try')} or ${color('cyan', 'list')}.\n`)
       process.exit(1)
   }
 }

package/package.json

@@ -4,7 +4,7 @@
     "type": "commercial",
     "url": "https://svgrid.com/pricing"
   },
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Add SvGrid UI components to your app in one command: npx @svgrid/ui add calendar",
   "type": "module",
   "license": "MIT",