veloria-ui 0.1.2

package/src/cli/index.ts

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+
+/**
+ * veloria-ui CLI
+ *
+ * Copies Veloria UI components into your project so you own the code.
+ * Works exactly like shadcn/ui's CLI — pick what you want, paste it in.
+ *
+ * By JohnDev19 — https://github.com/JohnDev19/Veloria-UI
+ * Docs: https://veloria-ui.vercel.app/
+ *
+ * Commands:
+ *   veloria-ui init                    — project setup wizard
+ *   veloria-ui add button card modal   — copy components into your project
+ *   veloria-ui list                    — browse all 102 components
+ *   veloria-ui list --category forms   — filter by category
+ *   veloria-ui diff button             — compare local vs latest
+ */
+
+import path from "path";
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import prompts from "prompts";
+import fs from "fs-extra";
+import { execa } from "execa";
+import { REGISTRY, COMPONENTS_BY_NAME, CATEGORIES, type Category } from "./registry";
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const PKG_VERSION: string = (require("../../package.json") as { version: string }).version;
+
+// ─── Banner ───────────────────────────────────────────────────────────────
+
+const banner = `
+${chalk.bold.blue("  ╦  ╦╔═╗╦  ╔═╗╦═╗╦╔═╗")}
+${chalk.bold.blue("  ╚╗╔╝║╣ ║  ║ ║╠╦╝║╠═╣")}
+${chalk.bold.blue("   ╚╝ ╚═╝╩═╝╚═╝╩╚═╩╩ ╩")}
+  ${chalk.dim("Build anything. Ship faster.")}
+  ${chalk.dim("by JohnDev19  ·  https://github.com/JohnDev19/Veloria-UI")}
+`;
+
+// ─── Program ──────────────────────────────────────────────────────────────
+
+const program = new Command();
+
+program
+  .name("veloria-ui")
+  .description("veloria-ui CLI — copy components into your project")
+  .version(PKG_VERSION, "-v, --version")
+  .addHelpText("before", banner);
+
+// ─── init ─────────────────────────────────────────────────────────────────
+
+program
+  .command("init")
+  .description("Set up veloria-ui in your project")
+  .option("--typescript", "Use TypeScript", true)
+  .option("--tailwind", "Configure Tailwind", true)
+  .option("--no-install", "Skip dependency install")
+  .option("-y, --yes", "Skip all prompts, use defaults")
+  .action(async (opts) => {
+    console.log(chalk.bold.blue("\n  Veloria UI Init\n") + chalk.dim("  Let's get you set up…\n"));
+
+    const cwd = process.cwd();
+    const pkgPath = path.join(cwd, "package.json");
+
+    if (!fs.existsSync(pkgPath)) {
+      console.error(chalk.red("\n  No package.json found. Run from your project root.\n"));
+      process.exit(1);
+    }
+
+    const pkg = fs.readJsonSync(pkgPath) as Record<string, unknown>;
+    const isNext = !!((pkg.dependencies as Record<string, string>)?.next ||
+                      (pkg.devDependencies as Record<string, string>)?.next);
+
+    const answers = opts.yes
+      ? { componentsDir: "components/ui", cssPath: isNext ? "app/globals.css" : "src/index.css", pm: detectPM(cwd) }
+      : await prompts([
+          { type: "text",   name: "componentsDir", message: "Where should components go?",      initial: "components/ui" },
+          { type: "text",   name: "cssPath",        message: "Path to your global CSS file?",    initial: isNext ? "app/globals.css" : "src/index.css" },
+          { type: "select", name: "pm",             message: "Package manager?",
+            choices: [{ title: "npm", value: "npm" }, { title: "pnpm", value: "pnpm" },
+                      { title: "yarn", value: "yarn" }, { title: "bun", value: "bun" }] },
+        ]);
+
+    if (!answers.componentsDir) return;
+
+    // Write atlas.config.json
+    fs.writeJsonSync(path.join(cwd, "atlas.config.json"), {
+      $schema: "https://veloria-ui.vercel.app/schema.json",
+      style: "default",
+      typescript: opts.typescript ?? true,
+      tailwind: { config: "tailwind.config.ts", css: answers.cssPath, baseColor: "slate", cssVariables: true },
+      aliases: { components: `@/${answers.componentsDir}`, utils: "@/lib/utils" },
+    }, { spaces: 2 });
+    console.log(chalk.green("  ✓ Created atlas.config.json"));
+
+    // Write lib/utils.ts if missing
+    const utilsPath = path.join(cwd, "lib", "utils.ts");
+    if (!fs.existsSync(utilsPath)) {
+      await fs.ensureDir(path.dirname(utilsPath));
+      await fs.writeFile(utilsPath,
+        `import { type ClassValue, clsx } from "clsx";\nimport { twMerge } from "tailwind-merge";\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n`
+      );
+      console.log(chalk.green("  ✓ Created lib/utils.ts"));
+    }
+
+    // Install core deps
+    if (opts.install !== false) {
+      const pm = answers.pm as string;
+      const spinner = ora(`Installing core deps with ${pm}…`).start();
+      try {
+        const deps = ["clsx", "tailwind-merge", "class-variance-authority", "@radix-ui/react-slot"];
+        const cmd = pm === "pnpm" ? ["pnpm", "add", ...deps]
+                  : pm === "bun"  ? ["bun",  "add", ...deps]
+                  : pm === "yarn" ? ["yarn", "add", ...deps]
+                                  : ["npm",  "install", ...deps];
+        await execa(cmd[0], cmd.slice(1), { cwd });
+        spinner.succeed(chalk.green("Core deps installed"));
+      } catch {
+        spinner.warn(chalk.yellow("Auto-install failed — run manually:"));
+        console.log(chalk.dim("  npm install clsx tailwind-merge class-variance-authority @radix-ui/react-slot\n"));
+      }
+    }
+
+    console.log(`
+${chalk.bold.green("  Veloria UI is ready!")}
+
+  ${chalk.dim("Next steps:")}
+  ${chalk.cyan("1.")} Add components: ${chalk.bold("npx veloria-ui add button card modal")}
+  ${chalk.cyan("2.")} Browse all:     ${chalk.bold("npx veloria-ui list")}
+  ${chalk.cyan("3.")} Docs:           ${chalk.bold("https://veloria-ui.vercel.app/")}
+  ${chalk.cyan("4.")} Issues:         ${chalk.bold("https://github.com/JohnDev19/Veloria-UI/issues")}
+`);
+  });
+
+// ─── add ──────────────────────────────────────────────────────────────────
+
+program
+  .command("add [components...]")
+  .alias("a")
+  .description("Copy one or more components into your project")
+  .option("-d, --dir <path>", "Output directory", "components/ui")
+  .option("--overwrite", "Replace existing files")
+  .option("--no-install", "Skip npm dep install")
+  .action(async (components: string[], opts) => {
+    const cwd = process.cwd();
+
+    if (!components?.length) {
+      console.log(chalk.red("\n  Specify at least one component.\n"));
+      console.log(`  ${chalk.dim("Example:")} ${chalk.cyan("npx veloria-ui add button card modal\n")}`);
+      process.exit(1);
+    }
+
+    // Resolve components + their veloria-ui registry deps
+    const toAdd = new Set<string>();
+    function resolve(name: string) {
+      const key = name.toLowerCase().replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+      const meta = COMPONENTS_BY_NAME.get(key) || COMPONENTS_BY_NAME.get(name);
+      if (!meta) {
+        console.error(chalk.red(`\n  "${name}" not found in the registry.\n`));
+        console.log(`  Run ${chalk.cyan("npx veloria-ui list")} to see what's available.\n`);
+        return;
+      }
+      toAdd.add(meta.name);
+      meta.registryDeps?.forEach(resolve);
+    }
+    components.forEach(resolve);
+    if (!toAdd.size) return;
+
+    const configPath = path.join(cwd, "atlas.config.json");
+    const config = fs.existsSync(configPath)
+      ? fs.readJsonSync(configPath) as { aliases?: { components?: string } }
+      : null;
+    const aliasDir = config?.aliases?.components?.replace(/^@\//, "");
+    const targetDir = path.join(cwd, opts.dir ?? aliasDir ?? "components/ui");
+
+    console.log(chalk.bold.blue("\n  Veloria UI Add\n") + chalk.dim(`  Adding: ${[...toAdd].join(", ")}\n`));
+
+    const allDeps = new Set<string>();
+    for (const name of toAdd) COMPONENTS_BY_NAME.get(name)!.deps.forEach((d) => allDeps.add(d));
+
+    // Write component stubs
+    for (const name of toAdd) {
+      const spinner = ora(`Adding ${chalk.bold(name)}`).start();
+      const pascal = name.split("-").map((p) => p[0].toUpperCase() + p.slice(1)).join("");
+      const dir = path.join(targetDir, name);
+      await fs.ensureDir(dir);
+      const file = path.join(dir, "index.tsx");
+
+      if (fs.existsSync(file) && !opts.overwrite) {
+        spinner.warn(chalk.yellow(`${name} already exists  (--overwrite to replace)`));
+        continue;
+      }
+
+      await fs.writeFile(file,
+`/**
+ * Veloria UI — ${pascal}
+ *
+ * Added by the veloria-ui CLI. This file is yours — edit it however you want.
+ * Re-export from veloria-ui to stay in sync, or paste the full source here
+ * to customise the internals.
+ *
+ * Docs:   https://veloria-ui.vercel.app/components/${name}
+ * Source: https://github.com/JohnDev19/Veloria-UI
+ */
+
+export { ${pascal} } from "veloria-ui";
+export type { ${pascal}Props } from "veloria-ui";
+`);
+      spinner.succeed(chalk.green(`${name}  →  ${path.relative(cwd, file)}`));
+    }
+
+    // Install npm deps
+    if (opts.install !== false && allDeps.size > 0) {
+      const pm = detectPM(cwd);
+      const spinner = ora(`Installing ${allDeps.size} package(s)…`).start();
+      try {
+        const deps = [...allDeps];
+        const cmd = pm === "pnpm" ? ["pnpm", "add", ...deps]
+                  : pm === "bun"  ? ["bun",  "add", ...deps]
+                  : pm === "yarn" ? ["yarn", "add", ...deps]
+                                  : ["npm",  "install", ...deps];
+        await execa(cmd[0], cmd.slice(1), { cwd });
+        spinner.succeed(chalk.green(`Installed: ${deps.join(", ")}`));
+      } catch {
+        spinner.warn(chalk.yellow("Auto-install failed — run manually:"));
+        console.log(chalk.dim(`  npm install ${[...allDeps].join(" ")}\n`));
+      }
+    }
+
+    const exNames = [...toAdd].map((n) => n.split("-").map((p) => p[0].toUpperCase() + p.slice(1)).join("")).join(", ");
+    console.log(`\n${chalk.bold.green("  Done!")}  ${path.relative(cwd, targetDir)}\n\n  ${chalk.cyan(`import { ${exNames} } from "@/components/ui/${[...toAdd][0]}"`)}\n`);
+  });
+
+// ─── list ─────────────────────────────────────────────────────────────────
+
+program
+  .command("list")
+  .alias("ls")
+  .description("List all available components")
+  .option("-c, --category <category>", "Filter by category")
+  .action((opts) => {
+    const filterCat = opts.category?.toLowerCase() as Category | undefined;
+    console.log(chalk.bold.blue("\n  veloria-ui Components\n"));
+
+    const cats = filterCat ? [filterCat] : CATEGORIES;
+    for (const cat of cats) {
+      const items = REGISTRY.filter((c) => c.category === cat);
+      if (!items.length) continue;
+      const label = cat.replace("-", " ").replace(/^\w/, (c) => c.toUpperCase());
+      console.log(chalk.bold(`  ${label} (${items.length})`));
+      for (const c of items) {
+        console.log(`    ${chalk.cyan(c.name.padEnd(22))} ${chalk.dim(c.description)}`);
+      }
+      console.log();
+    }
+
+    console.log(chalk.dim(`  ${REGISTRY.length} components total\n`) +
+      chalk.dim("  Add one: ") + chalk.cyan("npx veloria-ui add <name>\n"));
+  });
+
+// ─── diff ─────────────────────────────────────────────────────────────────
+
+program
+  .command("diff [component]")
+  .description("Compare your local copy to the latest version")
+  .action((component?: string) => {
+    if (!component) {
+      console.log(chalk.dim("\n  Usage: npx veloria-ui diff <component>\n"));
+      return;
+    }
+    console.log(chalk.bold.blue(`\n  diff: ${component}\n`) +
+      chalk.dim("  Comparing local copy to latest in the veloria-ui registry…\n"));
+    // Full diff requires fetching from the registry — tracked here:
+    // https://github.com/JohnDev19/Veloria-UI/issues
+    console.log(chalk.yellow("  ⚠  Registry diff isn't wired up yet."));
+    console.log(chalk.dim(`  Check the latest source at:\n`) +
+      chalk.cyan(`  https://github.com/JohnDev19/Veloria-UI/tree/main/src/components\n`));
+  });
+
+// ─── Error handling ───────────────────────────────────────────────────────
+
+program.on("command:*", (operands) => {
+  console.error(chalk.red(`\n  Unknown command: "${operands[0]}"\n`));
+  program.help();
+  process.exit(1);
+});
+
+program.parse(process.argv);
+
+if (!process.argv.slice(2).length) {
+  console.log(banner);
+  program.help();
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function detectPM(cwd: string): string {
+  if (fs.existsSync(path.join(cwd, "bun.lockb")))      return "bun";
+  if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(cwd, "yarn.lock")))      return "yarn";
+  return "npm";
+}

package/src/cli/registry.ts

@@ -0,0 +1,139 @@
+/**
+ * Veloria UI component registry.
+ *
+ * Every component lives here: name, category, description, and the npm deps
+ * it needs. The `add` command reads this to know what to install.
+ *
+ * — JohnDev19
+ */
+
+export interface ComponentMeta {
+  name: string;
+  category: Category;
+  description: string;
+  deps: string[];
+  /** Other veloria-ui components this one depends on */
+  registryDeps?: string[];
+}
+
+export type Category =
+  | "basic"
+  | "layout"
+  | "navigation"
+  | "forms"
+  | "advanced-forms"
+  | "data-display"
+  | "feedback"
+  | "overlay"
+  | "media"
+  | "utility";
+
+export const REGISTRY: ComponentMeta[] = [
+  // Basic
+  { name: "button",         category: "basic",         description: "Solid, outline, ghost, soft, link, danger variants. Loading state, icon slots.", deps: ["@radix-ui/react-slot", "class-variance-authority", "clsx", "tailwind-merge"] },
+  { name: "icon-button",    category: "basic",         description: "Square or circular icon-only button.", deps: ["@radix-ui/react-slot", "class-variance-authority", "clsx", "tailwind-merge"] },
+  { name: "link",           category: "basic",         description: "Anchor with external link indicator and underline control.", deps: ["@radix-ui/react-slot"] },
+  { name: "badge",          category: "basic",         description: "Compact label — 5 color variants, optional dot.", deps: ["class-variance-authority", "clsx", "tailwind-merge"] },
+  { name: "avatar",         category: "basic",         description: "Image with fallback initials, status ring, 6 sizes.", deps: ["@radix-ui/react-avatar"] },
+  { name: "avatar-group",   category: "basic",         description: "Stacked avatars with overflow count.", deps: ["@radix-ui/react-avatar"], registryDeps: ["avatar"] },
+  { name: "divider",        category: "basic",         description: "Horizontal/vertical separator with optional center label.", deps: ["@radix-ui/react-separator"] },
+  { name: "tag",            category: "basic",         description: "Closable colored tag with icon slot.", deps: [] },
+  { name: "chip",           category: "basic",         description: "Toggleable chip with avatar/icon and remove button.", deps: [] },
+  { name: "tooltip",        category: "basic",         description: "Radix tooltip, all four sides, configurable delay.", deps: ["@radix-ui/react-tooltip"] },
+  // Layout
+  { name: "container",      category: "layout",        description: "Responsive max-width wrapper with padding control.", deps: [] },
+  { name: "stack",          category: "layout",        description: "Flex column/row with gap, align, justify, divider.", deps: [] },
+  { name: "grid",           category: "layout",        description: "CSS Grid with column/row/gap config.", deps: [] },
+  { name: "flex",           category: "layout",        description: "Flex with full directional control.", deps: [] },
+  { name: "section",        category: "layout",        description: "Semantic section with vertical padding presets.", deps: [] },
+  { name: "spacer",         category: "layout",        description: "Invisible spacing element.", deps: [] },
+  { name: "aspect-ratio",   category: "layout",        description: "Radix aspect-ratio container.", deps: ["@radix-ui/react-aspect-ratio"] },
+  { name: "center",         category: "layout",        description: "Flex centering helper.", deps: [] },
+  { name: "scroll-area",    category: "layout",        description: "Custom scrollbar via Radix ScrollArea.", deps: ["@radix-ui/react-scroll-area"] },
+  { name: "masonry",        category: "layout",        description: "CSS multi-column masonry grid.", deps: [] },
+  // Navigation
+  { name: "navbar",         category: "navigation",    description: "Sticky, glass-blur top bar.", deps: [] },
+  { name: "sidebar",        category: "navigation",    description: "Collapsible side nav with width transition.", deps: [] },
+  { name: "menu",           category: "navigation",    description: "Vertical nav menu with active/disabled states.", deps: [] },
+  { name: "dropdown-menu",  category: "navigation",    description: "Full Radix Dropdown with all sub-primitives.", deps: ["@radix-ui/react-dropdown-menu"] },
+  { name: "breadcrumb",     category: "navigation",    description: "Accessible trail with custom separator.", deps: [] },
+  { name: "pagination",     category: "navigation",    description: "Page numbers with ellipsis and prev/next.", deps: [] },
+  { name: "tabs",           category: "navigation",    description: "Line, pills, enclosed variants. Radix powered.", deps: ["@radix-ui/react-tabs"] },
+  { name: "command-palette",category: "navigation",    description: "⌘K command palette.", deps: ["cmdk", "@radix-ui/react-dialog"], registryDeps: ["command-dialog"] },
+  { name: "navigation-menu",category: "navigation",    description: "Radix Navigation Menu for complex navbars.", deps: ["@radix-ui/react-navigation-menu"] },
+  { name: "stepper",        category: "navigation",    description: "Horizontal/vertical multi-step indicator.", deps: [] },
+  // Forms
+  { name: "input",          category: "forms",         description: "Left/right icon slots, sizes, error state.", deps: ["class-variance-authority"] },
+  { name: "textarea",       category: "forms",         description: "Multi-line input with resize control.", deps: [] },
+  { name: "select",         category: "forms",         description: "Full Radix Select with all sub-primitives.", deps: ["@radix-ui/react-select"] },
+  { name: "checkbox",       category: "forms",         description: "With label, description, error state.", deps: ["@radix-ui/react-checkbox"] },
+  { name: "radio-group",    category: "forms",         description: "Per-option labels and descriptions.", deps: ["@radix-ui/react-radio-group"] },
+  { name: "switch",         category: "forms",         description: "Three sizes, label, description.", deps: ["@radix-ui/react-switch"] },
+  { name: "slider",         category: "forms",         description: "Single-thumb range slider.", deps: ["@radix-ui/react-slider"] },
+  { name: "range-slider",   category: "forms",         description: "Dual-thumb slider.", deps: ["@radix-ui/react-slider"], registryDeps: ["slider"] },
+  { name: "date-picker",    category: "forms",         description: "Native date input wrapper.", deps: [] },
+  { name: "time-picker",    category: "forms",         description: "Native time input wrapper.", deps: [] },
+  // Advanced Forms
+  { name: "file-upload",    category: "advanced-forms", description: "Drag-and-drop zone with click-to-upload fallback.", deps: [] },
+  { name: "otp-input",      category: "advanced-forms", description: "PIN/OTP with auto-advance and paste support.", deps: [] },
+  { name: "color-picker",   category: "advanced-forms", description: "Swatches + hex input.", deps: [] },
+  { name: "search-input",   category: "advanced-forms", description: "Search with loading state and clear button.", deps: [] },
+  { name: "password-input", category: "advanced-forms", description: "Password with show/hide toggle.", deps: [] },
+  { name: "combobox",       category: "advanced-forms", description: "Searchable single-value select.", deps: [] },
+  { name: "multi-select",   category: "advanced-forms", description: "Multi-value select with chips.", deps: [] },
+  { name: "form-field",     category: "advanced-forms", description: "Form field wrapper with spacing.", deps: [] },
+  { name: "form-label",     category: "advanced-forms", description: "Label with required/optional indicators.", deps: [] },
+  { name: "form-error",     category: "advanced-forms", description: "Accessible error message.", deps: [] },
+  // Data Display
+  { name: "card",           category: "data-display",  description: "Surface with header/content/footer slots. 5 variants.", deps: [] },
+  { name: "table",          category: "data-display",  description: "Full HTML table system.", deps: [] },
+  { name: "data-table",     category: "data-display",  description: "Sortable data table with loading and empty states.", deps: [] },
+  { name: "list",           category: "data-display",  description: "Simple, bordered, and divided lists.", deps: [] },
+  { name: "list-item",      category: "data-display",  description: "List item with icon and extra slot.", deps: [] },
+  { name: "statistic",      category: "data-display",  description: "Key metric with trend indicator.", deps: [] },
+  { name: "timeline",       category: "data-display",  description: "Vertical events with color-coded icons.", deps: [] },
+  { name: "calendar",       category: "data-display",  description: "Month picker with highlighted dates.", deps: [] },
+  { name: "chart",          category: "data-display",  description: "Chart wrapper — bring your own chart library.", deps: [] },
+  { name: "code-block",     category: "data-display",  description: "Code display with copy button and line numbers.", deps: [] },
+  // Feedback
+  { name: "alert",          category: "feedback",      description: "Info/success/warning/danger with optional dismiss.", deps: ["class-variance-authority"] },
+  { name: "toast",          category: "feedback",      description: "Radix Toast with all sub-primitives.", deps: ["@radix-ui/react-toast"] },
+  { name: "snackbar",       category: "feedback",      description: "Positioned message with action.", deps: [] },
+  { name: "progress",       category: "feedback",      description: "Linear bar with color variants.", deps: ["@radix-ui/react-progress"] },
+  { name: "circular-progress", category: "feedback",   description: "SVG ring with indeterminate mode.", deps: [] },
+  { name: "skeleton",       category: "feedback",      description: "Pulse placeholder for text, rect, circle.", deps: [] },
+  { name: "loading-spinner",category: "feedback",      description: "Accessible SVG spinner.", deps: [] },
+  { name: "empty-state",    category: "feedback",      description: "Icon + title + description + action.", deps: [] },
+  { name: "status-indicator", category: "feedback",    description: "Online/offline/busy/away dot with pulse.", deps: [] },
+  { name: "notification",   category: "feedback",      description: "Notification item with avatar, timestamp, unread dot.", deps: [] },
+  // Overlay
+  { name: "modal",          category: "overlay",       description: "Preset dialog — sm to full size variants.", deps: ["@radix-ui/react-dialog"] },
+  { name: "dialog",         category: "overlay",       description: "Full Radix Dialog primitive suite.", deps: ["@radix-ui/react-dialog"] },
+  { name: "drawer",         category: "overlay",       description: "Slides in from any edge.", deps: ["@radix-ui/react-dialog"] },
+  { name: "popover",        category: "overlay",       description: "Floating panel.", deps: ["@radix-ui/react-popover"] },
+  { name: "hover-card",     category: "overlay",       description: "Rich hover preview.", deps: ["@radix-ui/react-hover-card"] },
+  { name: "context-menu",   category: "overlay",       description: "Right-click menu.", deps: ["@radix-ui/react-context-menu"] },
+  { name: "command-dialog", category: "overlay",       description: "⌘K palette.", deps: ["cmdk", "@radix-ui/react-dialog"] },
+  { name: "sheet",          category: "overlay",       description: "Drawer alias.", deps: ["@radix-ui/react-dialog"], registryDeps: ["drawer"] },
+  { name: "lightbox",       category: "overlay",       description: "Full-screen image overlay.", deps: ["@radix-ui/react-dialog"] },
+  { name: "image-viewer",   category: "overlay",       description: "Lightbox alias.", deps: ["@radix-ui/react-dialog"], registryDeps: ["lightbox"] },
+  // Media
+  { name: "image",          category: "media",         description: "Image with fallback, aspect ratio, fit, caption.", deps: [] },
+  { name: "video-player",   category: "media",         description: "HTML5 video with captions/subtitles support.", deps: [] },
+  { name: "audio-player",   category: "media",         description: "Custom audio UI with seek bar, cover art.", deps: [] },
+  { name: "carousel",       category: "media",         description: "Autoplay, dots, arrows, loop, slidesPerView.", deps: [] },
+  { name: "gallery",        category: "media",         description: "Responsive image grid with click handler.", deps: [] },
+  // Utility
+  { name: "theme-switcher", category: "utility",       description: "Icon / toggle / select variants.", deps: [] },
+  { name: "copy-button",    category: "utility",       description: "Icon or labelled copy button with success feedback.", deps: [] },
+  { name: "keyboard-shortcut", category: "utility",    description: "Styled <kbd> shortcut display.", deps: [] },
+  { name: "resizable-panel",category: "utility",       description: "Drag-to-resize panel with min/max constraints.", deps: [] },
+  { name: "drag-drop-area", category: "utility",       description: "Accessible file drop zone.", deps: [] },
+];
+
+export const COMPONENTS_BY_NAME = new Map(REGISTRY.map((c) => [c.name, c]));
+
+export const CATEGORIES: Category[] = [
+  "basic", "layout", "navigation", "forms", "advanced-forms",
+  "data-display", "feedback", "overlay", "media", "utility",
+];