@webjskit/ui 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# @webjskit/ui
+
+An **AI-first component library** for the web. Source-copied into your project , 
+you own the code.
+
+Two-tier composition designed for AI agents who reason about real HTML +
+function calls, not for a layered React abstraction over every primitive:
+
+- **Tier 1, class-helper functions** (`buttonClass`, `cardClass`,
+  `inputClass`, `labelClass`, `alertClass`, `popoverContentClass`,
+  `accordionItemClass`, `collapsibleTriggerClass`, …). Pure functions that
+  return Tailwind class strings. You spread them onto raw native elements
+ , including `<button class=${buttonClass({ variant: 'outline' })}>`,
+  `<details name="faq" class=${accordionItemClass()}>`, and
+  `<div popover class=${popoverContentClass()}>`, so real native elements
+  participate in form submission, autocomplete, screen readers, the
+  Popover API ancestry, and devtools as themselves.
+- **Tier 2, stateful custom elements** (`<ui-dialog>`, `<ui-alert-dialog>`,
+  `<ui-tabs>`, `<ui-tooltip>`, `<ui-hover-card>`, `<ui-dropdown-menu>`,
+  `<ui-sonner>`, …). Reserved for the behavior the browser still doesn't
+  give you for free: hover-with-delay tooltips, roving-focus keyboard nav
+  for menus and tabs, toast queue with stack and dismiss. Dialog and
+  alert-dialog use a thin custom element on top of the native
+  `<dialog>.showModal()`, focus trap, Escape, and backdrop overlay all
+  come from the platform. Decorate the host, no shadow DOM.
+
+Works with any project that uses Tailwind CSS v4 and supports custom elements:
+webjs, Next, Astro, Vite, SvelteKit, Lit, vanilla HTML, as long as Tailwind
+is configured, the components render correctly. Variant names, sizes, and
+data-attribute conventions mirror shadcn's so an AI agent's existing
+knowledge of shadcn maps directly.
+
+Tier-2 elements extend `Base` (a Node-safe `HTMLElement` shim) from a small
+shared `lib/utils.ts` the CLI writes into your project.
+
+## Install
+
+### Option A : Webjs users (already have `@webjskit/cli`)
+
+Nothing to install. `@webjskit/ui` is a hard dependency of `@webjskit/cli`,
+so a global webjs install already includes it. Apps scaffolded with
+`webjs create` also have it pre-listed in `devDependencies`.
+
+```sh
+webjs ui init
+webjs ui add button card dialog
+```
+
+### Option B : Everyone else (Next, Astro, Vite, SvelteKit, Lit, vanilla, …)
+
+Two npm installs, the CLI and the runtime base class, then run the CLI:
+
+```sh
+npm install -D @webjskit/ui
+npm install @webjskit/core
+npx webjsui init
+npx webjsui add button card dialog
+```
+
+The `webjsui` binary is standalone, it doesn't require `@webjskit/cli`.
+`init` auto-detects your project type (Next / Astro / Vite / Lit / plain)
+and picks sensible defaults.
+
+## What `init` writes
+
+- `components.json`, your project's UI config (aliases, base color, Tailwind path)
+- `lib/utils.ts`, the `cn()` class-merge helper
+- Tailwind tokens + CSS variables appended to your global stylesheet
+
+## What `add` does
+
+Copies the component's `.ts` source into `components/ui/<name>.ts` (or your
+configured alias). Resolves transitive deps via `registryDependencies` and
+auto-installs npm deps like `@floating-ui/dom` for popover-style components.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `webjsui init` | Initialize a project (writes `components.json`, theme CSS, `lib/utils.ts`) |
+| `webjsui add <names...>` | Add components to your project |
+| `webjsui list` | List all available components |
+| `webjsui view <name>` | Print a component's source to stdout |
+| `webjsui diff [name]` | Show diff between your local copy and the registry |
+| `webjsui info` | Print project diagnostics |
+| `webjsui build` | (For registry authors) Compile a custom registry |
+
+## Tag convention
+
+Every component uses a single `ui-` prefix:
+
+```html
+<ui-button variant="default">Click me</ui-button>
+<ui-card>
+  <ui-card-header>
+    <ui-card-title>Title</ui-card-title>
+    <ui-card-description>Description</ui-card-description>
+  </ui-card-header>
+  <ui-card-content>Content here</ui-card-content>
+</ui-card>
+```
+
+## License
+
+MIT

package/bin/webjsui.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/index.js';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@webjskit/ui",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "An AI-first component library - class-helper functions for visuals, custom elements only where state matters. Source-copied into your repo, you own it. Works with any Tailwind v4 project.",
+  "bin": {
+    "webjsui": "bin/webjsui.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./registry/schema": "./src/registry/schema.js",
+    "./utils": "./src/utils/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2",
+    "zod": "^3.24.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vivek7405/webjs.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://ui.webjs.dev",
+  "bugs": "https://github.com/vivek7405/webjs/issues",
+  "license": "MIT",
+  "keywords": [
+    "shadcn",
+    "ui",
+    "web-components",
+    "tailwind",
+    "components",
+    "webjs"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,123 @@
+import { Command } from 'commander';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, basename } from 'node:path';
+import prompts from 'prompts';
+import { execSync } from 'node:child_process';
+import { getConfig } from '../utils/get-config.js';
+import { logger } from '../utils/logger.js';
+import { resolveTree, collectNpmDeps } from '../registry/resolver.js';
+import { DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+
+export const add = new Command()
+  .name('add')
+  .description('Add one or more components to your project')
+  .argument('[components...]', 'component names (e.g. button card dialog)')
+  .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
+  .option('-y, --yes', 'skip overwrite prompts', false)
+  .option('-o, --overwrite', 'overwrite existing files without asking', false)
+  .option('--no-deps', 'skip installing npm dependencies')
+  .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
+  .action(async (components, opts) => {
+    const cwd = opts.cwd;
+    const config = getConfig(cwd);
+    if (!config) {
+      logger.error(`No ${logger.cyan('components.json')} found in ${cwd}.`);
+      logger.info(`Run ${logger.cyan('npx webjsui init')} first.`);
+      process.exit(1);
+    }
+
+    if (!components || components.length === 0) {
+      logger.error('No components specified.');
+      logger.info(`Try ${logger.cyan('npx webjsui add button')} or ${logger.cyan('npx webjsui list')}.`);
+      process.exit(1);
+    }
+
+    const tree = await resolveTree(components, opts.registry);
+    logger.info(`Installing ${logger.bold(components.join(', '))}…`);
+
+    for (const item of tree) {
+      for (const file of item.files || []) {
+        await writeRegistryFile(cwd, config, item, file, opts);
+      }
+    }
+
+    if (opts.deps !== false) {
+      const { dependencies, devDependencies } = collectNpmDeps(tree);
+      // @webjskit/core is always a runtime dep
+      if (!dependencies.includes('@webjskit/core')) dependencies.push('@webjskit/core');
+
+      if (dependencies.length) await installDeps(cwd, dependencies, false);
+      if (devDependencies.length) await installDeps(cwd, devDependencies, true);
+    }
+
+    logger.success('Done.');
+  });
+
+async function writeRegistryFile(cwd, config, item, file, opts) {
+  const target = resolveTarget(cwd, config, item, file);
+  ensureDir(dirname(target));
+
+  if (existsSync(target) && !opts.overwrite && !opts.yes) {
+    const r = await prompts({
+      type: 'confirm',
+      name: 'overwrite',
+      message: `Overwrite ${basename(target)}?`,
+      initial: false,
+    });
+    if (!r.overwrite) {
+      logger.info(`Skipped ${basename(target)}`);
+      return;
+    }
+  }
+
+  writeFileSync(target, file.content || '', 'utf8');
+  logger.success(`Wrote ${relative(cwd, target)}`);
+}
+
+function resolveTarget(cwd, config, item, file) {
+  // explicit `target` wins
+  if (file.target) return join(cwd, file.target);
+
+  const fileName = basename(file.path);
+  const aliases = config.aliases;
+
+  switch (file.type) {
+    case 'registry:ui':
+      return join(cwd, (aliases.ui || 'components/ui').replace(/^@\//, ''), fileName);
+    case 'registry:component':
+      return join(cwd, aliases.components.replace(/^@\//, ''), fileName);
+    case 'registry:lib':
+      return join(cwd, (aliases.lib || 'lib').replace(/^@\//, ''), fileName);
+    case 'registry:hook':
+      return join(cwd, 'hooks', fileName);
+    default:
+      return join(cwd, fileName);
+  }
+}
+
+function relative(cwd, p) {
+  return p.startsWith(cwd) ? p.slice(cwd.length + 1) : p;
+}
+
+function ensureDir(d) {
+  if (!existsSync(d)) mkdirSync(d, { recursive: true });
+}
+
+async function installDeps(cwd, deps, dev) {
+  const manager = detectPackageManager(cwd);
+  const flag = dev ? '-D' : '';
+  const cmd = `${manager.exec} ${manager.add} ${flag} ${deps.join(' ')}`.replace(/\s+/g, ' ').trim();
+  logger.info(`${logger.dim('$')} ${cmd}`);
+  try {
+    execSync(cmd, { cwd, stdio: 'inherit' });
+  } catch (e) {
+    logger.warn(`Dependency install failed. Run manually: ${logger.cyan(cmd)}`);
+  }
+}
+
+function detectPackageManager(cwd) {
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return { exec: 'pnpm', add: 'add' };
+  if (existsSync(join(cwd, 'yarn.lock'))) return { exec: 'yarn', add: 'add' };
+  if (existsSync(join(cwd, 'bun.lockb'))) return { exec: 'bun', add: 'add' };
+  return { exec: 'npm', add: 'install' };
+}

package/src/commands/build.js

@@ -0,0 +1,47 @@
+import { Command } from 'commander';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { registrySchema, registryItemSchema } from '../registry/schema.js';
+import { logger } from '../utils/logger.js';
+
+export const build = new Command()
+  .name('build')
+  .description('Build a custom registry: read registry.json, inline file contents, emit r/*.json')
+  .argument('[file]', 'registry manifest path', 'registry.json')
+  .option('-o, --output <dir>', 'output directory', './r')
+  .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
+  .action((file, opts) => {
+    const cwd = opts.cwd;
+    const manifestPath = resolve(cwd, file);
+    if (!existsSync(manifestPath)) {
+      logger.error(`Manifest not found: ${manifestPath}`);
+      process.exit(1);
+    }
+
+    const raw = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const manifest = registrySchema.parse(raw);
+    const outDir = resolve(cwd, opts.output);
+    if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+
+    const flatIndex = [];
+    for (const item of manifest.items) {
+      const enriched = {
+        $schema: 'https://ui.webjs.dev/schema/registry-item.json',
+        ...item,
+        files: (item.files || []).map((f) => ({
+          ...f,
+          content: f.content ?? readFileSync(resolve(dirname(manifestPath), f.path), 'utf8'),
+        })),
+      };
+      registryItemSchema.parse(enriched);
+      const outPath = join(outDir, `${item.name}.json`);
+      mkdirSync(dirname(outPath), { recursive: true });
+      writeFileSync(outPath, JSON.stringify(enriched, null, 2) + '\n', 'utf8');
+      flatIndex.push({ name: item.name, type: item.type, description: item.description });
+      logger.success(`Built r/${item.name}.json`);
+    }
+
+    writeFileSync(join(outDir, 'index.json'), JSON.stringify(flatIndex, null, 2) + '\n', 'utf8');
+    writeFileSync(join(outDir, 'registry.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    logger.success(`Built ${flatIndex.length} items → ${outDir}`);
+  });

package/src/commands/diff.js

@@ -0,0 +1,39 @@
+import { Command } from 'commander';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { getConfig } from '../utils/get-config.js';
+import { fetchRegistryItem, fetchRegistryIndex, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { logger } from '../utils/logger.js';
+
+export const diff = new Command()
+  .name('diff')
+  .description('Show differences between local components and the registry')
+  .argument('[name]', 'component to diff (omit to show all out-of-date)')
+  .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
+  .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
+  .action(async (name, opts) => {
+    const config = getConfig(opts.cwd);
+    if (!config) {
+      logger.error('No components.json. Run `webjsui init` first.');
+      process.exit(1);
+    }
+
+    const items = name ? [await fetchRegistryItem(name, opts.registry)] : (await fetchRegistryIndex(opts.registry)).filter((i) => i.type === 'registry:ui');
+    const uiDir = config.resolvedPaths.ui;
+    let changed = 0;
+
+    for (const item of items) {
+      for (const file of item.files || []) {
+        const target = join(uiDir, basename(file.path));
+        if (!existsSync(target)) continue;
+        const local = readFileSync(target, 'utf8');
+        if (local !== (file.content || '')) {
+          logger.info(`${logger.bold(item.name)}: ${basename(file.path)} differs from registry`);
+          changed++;
+        }
+      }
+    }
+
+    if (changed === 0) logger.success('All local components match the registry.');
+    else logger.info(`\n${changed} file${changed === 1 ? '' : 's'} differ. Re-add with ${logger.cyan('webjsui add <name> -o')} to overwrite.`);
+  });

package/src/commands/info.js

@@ -0,0 +1,28 @@
+import { Command } from 'commander';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getConfig } from '../utils/get-config.js';
+import { detectProject } from '../utils/detect-project.js';
+import { DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { logger } from '../utils/logger.js';
+
+export const info = new Command()
+  .name('info')
+  .description('Print project diagnostics (config, project type, registry)')
+  .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
+  .action((opts) => {
+    const cwd = opts.cwd;
+    const { type } = detectProject(cwd);
+    const config = getConfig(cwd);
+
+    logger.info(`${logger.bold('Project')}      ${type}`);
+    logger.info(`${logger.bold('cwd')}          ${cwd}`);
+    logger.info(`${logger.bold('Registry')}     ${DEFAULT_REGISTRY_URL}`);
+    logger.info(`${logger.bold('Config')}       ${config ? 'components.json ✔' : 'components.json ✖ (run `webjsui init`)'}`);
+    if (config) {
+      logger.info(`${logger.bold('Base color')}   ${config.tailwind.baseColor}`);
+      logger.info(`${logger.bold('Tailwind CSS')} ${config.tailwind.css}`);
+      logger.info(`${logger.bold('Aliases')}      ${JSON.stringify(config.aliases)}`);
+    }
+    logger.info(`${logger.bold('Tailwind')}     ${existsSync(join(cwd, 'tailwind.config.js')) || existsSync(join(cwd, 'tailwind.config.ts')) ? 'config detected' : '(none: Tailwind v4 uses CSS-only config)'}`);
+  });

package/src/commands/init.js

@@ -0,0 +1,115 @@
+import { Command } from 'commander';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import prompts from 'prompts';
+import { defaultsForProject } from '../utils/detect-project.js';
+import { writeConfig, CONFIG_FILE } from '../utils/get-config.js';
+import { logger } from '../utils/logger.js';
+import { fetchRegistryItem, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+
+const BASE_COLORS = ['neutral', 'stone', 'zinc', 'mauve', 'olive', 'mist', 'taupe'];
+
+export const init = new Command()
+  .name('init')
+  .description('Initialize @webjskit/ui in a project: writes components.json, theme CSS, lib/utils')
+  .option('-c, --cwd <cwd>', 'the working directory', process.cwd())
+  .option('-y, --yes', 'skip confirmation prompts', false)
+  .option('--base-color <color>', `base color (${BASE_COLORS.join('|')})`)
+  .option('--css <path>', 'path to the project Tailwind CSS file')
+  .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
+  .action(async (opts) => {
+    const cwd = opts.cwd;
+    const defaults = defaultsForProject(cwd);
+
+    /** @type {{ baseColor: string, css: string }} */
+    let answers = {
+      baseColor: opts.baseColor || 'neutral',
+      css: opts.css || defaults.tailwindCss,
+    };
+
+    if (!opts.yes) {
+      const r = await prompts(
+        [
+          {
+            type: opts.baseColor ? null : 'select',
+            name: 'baseColor',
+            message: 'Base color?',
+            choices: BASE_COLORS.map((c) => ({ title: c, value: c })),
+            initial: 0,
+          },
+          {
+            type: opts.css ? null : 'text',
+            name: 'css',
+            message: 'Tailwind CSS file path?',
+            initial: defaults.tailwindCss,
+          },
+        ],
+        { onCancel: () => process.exit(1) },
+      );
+      answers = { ...answers, ...r };
+    }
+
+    const config = {
+      $schema: 'https://ui.webjs.dev/schema.json',
+      style: 'default',
+      tailwind: {
+        css: answers.css,
+        baseColor: answers.baseColor,
+        cssVariables: true,
+      },
+      aliases: defaults.aliases,
+      iconLibrary: 'lucide',
+    };
+
+    writeConfig(cwd, config);
+    logger.success(`Wrote ${CONFIG_FILE}`);
+
+    // Pull lib/utils + the chosen theme from the registry and write them in.
+    await writeLibUtils(cwd, defaults.aliases.utils, opts.registry);
+    await writeTheme(cwd, answers.baseColor, answers.css, opts.registry);
+
+    logger.break();
+    logger.success('Done.');
+    logger.info('');
+    logger.info(`Add components with:  ${logger.cyan('npx webjsui add button card dialog')}`);
+  });
+
+async function writeLibUtils(cwd, utilsAlias, registryUrl) {
+  try {
+    const item = await fetchRegistryItem('lib-utils', registryUrl);
+    if (!item.files) return;
+    for (const f of item.files) {
+      // `utils` alias points at e.g. "lib/utils" → we write to lib/utils.ts
+      const target = join(cwd, utilsAlias.replace(/^@\//, '') + '.ts');
+      ensureDir(dirname(target));
+      writeFileSync(target, f.content || '', 'utf8');
+      logger.success(`Wrote ${utilsAlias}.ts`);
+    }
+  } catch (e) {
+    logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write lib/utils.ts manually.`);
+  }
+}
+
+async function writeTheme(cwd, baseColor, cssPath, registryUrl) {
+  try {
+    const item = await fetchRegistryItem(`theme-${baseColor}`, registryUrl);
+    if (!item.files) return;
+    const target = join(cwd, cssPath);
+    ensureDir(dirname(target));
+    const existing = existsSync(target) ? readFileSync(target, 'utf8') : '';
+    const themeBlock = item.files[0]?.content || '';
+    // Idempotent: only append if our marker isn't already present.
+    if (existing.includes('/* @webjskit/ui theme */')) {
+      logger.info(`Theme already present in ${cssPath}: skipping.`);
+      return;
+    }
+    writeFileSync(target, existing + (existing && !existing.endsWith('\n') ? '\n' : '') + themeBlock, 'utf8');
+    logger.success(`Wrote theme into ${cssPath}`);
+  } catch (e) {
+    logger.warn(`Could not fetch theme-${baseColor} (${e.message}). Skipping theme install.`);
+  }
+}
+
+function ensureDir(d) {
+  if (!existsSync(d)) mkdirSync(d, { recursive: true });
+}

package/src/commands/list.js

@@ -0,0 +1,25 @@
+import { Command } from 'commander';
+import { fetchRegistryIndex, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { logger } from '../utils/logger.js';
+
+export const list = new Command()
+  .name('list')
+  .alias('search')
+  .description('List components available in the registry')
+  .argument('[filter]', 'filter by substring')
+  .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
+  .action(async (filter, opts) => {
+    const items = await fetchRegistryIndex(opts.registry);
+    const ui = items.filter((i) => i.type === 'registry:ui');
+    const filtered = filter ? ui.filter((i) => i.name.includes(filter)) : ui;
+    if (!filtered.length) {
+      logger.info('No matches.');
+      return;
+    }
+    for (const i of filtered) {
+      const desc = i.description ? logger.dim(': ' + i.description) : '';
+      logger.info(`  ${logger.cyan(i.name)}${desc}`);
+    }
+    logger.info('');
+    logger.info(`${filtered.length} component${filtered.length === 1 ? '' : 's'}.`);
+  });

package/src/commands/view.js

@@ -0,0 +1,19 @@
+import { Command } from 'commander';
+import { fetchRegistryItem, DEFAULT_REGISTRY_URL } from '../registry/fetcher.js';
+import { logger } from '../utils/logger.js';
+
+export const view = new Command()
+  .name('view')
+  .description("Print a registry item's source to stdout")
+  .argument('<name>', 'component name')
+  .option('--registry <url>', 'registry base URL', DEFAULT_REGISTRY_URL)
+  .action(async (name, opts) => {
+    const item = await fetchRegistryItem(name, opts.registry);
+    logger.info(logger.dim(`# ${item.name}: ${item.type}`));
+    if (item.description) logger.info(logger.dim(`# ${item.description}`));
+    for (const f of item.files || []) {
+      logger.info('');
+      logger.info(logger.dim(`# ${f.path}`));
+      console.log(f.content || '');
+    }
+  });

package/src/index.js

@@ -0,0 +1,32 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { init } from './commands/init.js';
+import { add } from './commands/add.js';
+import { list } from './commands/list.js';
+import { view } from './commands/view.js';
+import { diff } from './commands/diff.js';
+import { info } from './commands/info.js';
+import { build } from './commands/build.js';
+
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+
+const program = new Command()
+  .name('webjsui')
+  .description('AI-first component library: class helpers + custom elements, copied into your project so you own the code')
+  .version(pkg.version, '-v, --version', 'display the version number');
+
+program
+  .addCommand(init)
+  .addCommand(add)
+  .addCommand(list)
+  .addCommand(view)
+  .addCommand(diff)
+  .addCommand(info)
+  .addCommand(build);
+
+program.parse();

package/src/registry/fetcher.js

@@ -0,0 +1,45 @@
+import { registryItemSchema, registryIndexSchema } from './schema.js';
+
+/**
+ * Default registry URL. Override via REGISTRY_URL env var, or per-call.
+ */
+export const DEFAULT_REGISTRY_URL = process.env.REGISTRY_URL || 'https://ui.webjs.dev/registry';
+
+const cache = new Map();
+
+/**
+ * Fetch a registry item by name.
+ *
+ * @param {string} name
+ * @param {string} [baseUrl]
+ */
+export async function fetchRegistryItem(name, baseUrl = DEFAULT_REGISTRY_URL) {
+  const url = `${baseUrl.replace(/\/$/, '')}/${name}.json`;
+  if (cache.has(url)) return cache.get(url);
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch registry item "${name}" from ${url}: HTTP ${res.status}`);
+  }
+  const json = await res.json();
+  const item = registryItemSchema.parse(json);
+  cache.set(url, item);
+  return item;
+}
+
+/**
+ * Fetch the flat registry index (list of all items).
+ *
+ * @param {string} [baseUrl]
+ */
+export async function fetchRegistryIndex(baseUrl = DEFAULT_REGISTRY_URL) {
+  const url = `${baseUrl.replace(/\/$/, '')}/index.json`;
+  if (cache.has(url)) return cache.get(url);
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch registry index from ${url}: HTTP ${res.status}`);
+  }
+  const json = await res.json();
+  const items = registryIndexSchema.parse(json);
+  cache.set(url, items);
+  return items;
+}

package/src/registry/resolver.js

@@ -0,0 +1,40 @@
+import { fetchRegistryItem } from './fetcher.js';
+
+/**
+ * Walk `registryDependencies` transitively. Returns a flat array of items in
+ * install order (deepest dependency first). Cycles are guarded against.
+ *
+ * @param {string[]} names
+ * @param {string} baseUrl
+ */
+export async function resolveTree(names, baseUrl) {
+  /** @type {Map<string, any>} */
+  const seen = new Map();
+  /** @type {any[]} */
+  const ordered = [];
+
+  async function visit(name) {
+    if (seen.has(name)) return;
+    seen.set(name, true);
+    const item = await fetchRegistryItem(name, baseUrl);
+    for (const dep of item.registryDependencies || []) await visit(dep);
+    ordered.push(item);
+  }
+
+  for (const name of names) await visit(name);
+  return ordered;
+}
+
+/**
+ * Collect all npm `dependencies` + `devDependencies` from a resolved tree,
+ * deduplicated. Returns { dependencies, devDependencies }.
+ */
+export function collectNpmDeps(items) {
+  const deps = new Set();
+  const devDeps = new Set();
+  for (const item of items) {
+    for (const d of item.dependencies || []) deps.add(d);
+    for (const d of item.devDependencies || []) devDeps.add(d);
+  }
+  return { dependencies: [...deps], devDependencies: [...devDeps] };
+}

package/src/registry/schema.js

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+
+// Wire-compatible port of shadcn's registry schema.
+// Source: ~/Documents/Projects/shadcn/packages/shadcn/src/registry/schema.ts
+
+export const registryItemTypeSchema = z.enum([
+  'registry:lib',
+  'registry:block',
+  'registry:component',
+  'registry:ui',
+  'registry:hook',
+  'registry:page',
+  'registry:file',
+  'registry:theme',
+  'registry:style',
+  'registry:item',
+  'registry:base',
+  'registry:font',
+  'registry:example',
+  'registry:internal',
+]);
+
+export const registryItemFileSchema = z.discriminatedUnion('type', [
+  z.object({
+    path: z.string(),
+    content: z.string().optional(),
+    type: z.enum(['registry:file', 'registry:page']),
+    target: z.string(),
+  }),
+  z.object({
+    path: z.string(),
+    content: z.string().optional(),
+    type: registryItemTypeSchema.exclude(['registry:file', 'registry:page']),
+    target: z.string().optional(),
+  }),
+]);
+
+export const registryItemTailwindSchema = z.object({
+  config: z
+    .object({
+      content: z.array(z.string()).optional(),
+      theme: z.record(z.string(), z.any()).optional(),
+      plugins: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+export const registryItemCssVarsSchema = z.object({
+  theme: z.record(z.string(), z.string()).optional(),
+  light: z.record(z.string(), z.string()).optional(),
+  dark: z.record(z.string(), z.string()).optional(),
+});
+
+const cssValueSchema = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.array(z.union([z.string(), z.record(z.string(), z.string())])),
+    z.record(z.string(), cssValueSchema),
+  ]),
+);
+
+export const registryItemCssSchema = z.record(z.string(), cssValueSchema);
+export const registryItemEnvVarsSchema = z.record(z.string(), z.string());
+
+export const registryItemCommonSchema = z.object({
+  $schema: z.string().optional(),
+  extends: z.string().optional(),
+  name: z.string(),
+  title: z.string().optional(),
+  author: z.string().min(2).optional(),
+  description: z.string().optional(),
+  dependencies: z.array(z.string()).optional(),
+  devDependencies: z.array(z.string()).optional(),
+  registryDependencies: z.array(z.string()).optional(),
+  files: z.array(registryItemFileSchema).optional(),
+  tailwind: registryItemTailwindSchema.optional(),
+  cssVars: registryItemCssVarsSchema.optional(),
+  css: registryItemCssSchema.optional(),
+  envVars: registryItemEnvVarsSchema.optional(),
+  meta: z.record(z.string(), z.any()).optional(),
+  docs: z.string().optional(),
+  categories: z.array(z.string()).optional(),
+});
+
+export const rawConfigSchema = z
+  .object({
+    $schema: z.string().optional(),
+    style: z.string().default('default'),
+    tailwind: z.object({
+      config: z.string().optional(),
+      css: z.string(),
+      baseColor: z.string().default('neutral'),
+      cssVariables: z.boolean().default(true),
+      prefix: z.string().default('').optional(),
+    }),
+    iconLibrary: z.string().optional().default('lucide'),
+    aliases: z.object({
+      components: z.string().default('components'),
+      utils: z.string().default('lib/utils'),
+      ui: z.string().optional().default('components/ui'),
+      lib: z.string().optional().default('lib'),
+    }),
+    registries: z.record(z.string(), z.any()).optional(),
+  })
+  .strict();
+
+export const registryItemSchema = registryItemCommonSchema.extend({
+  type: registryItemTypeSchema,
+});
+
+export const registrySchema = z.object({
+  name: z.string(),
+  homepage: z.string().optional(),
+  items: z.array(registryItemSchema),
+});
+
+export const registryIndexSchema = z.array(registryItemSchema);

package/src/utils/detect-project.js

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Detect the host project type so we can pick sensible defaults for paths.
+ *
+ * @param {string} cwd
+ * @returns {{ type: 'webjs' | 'next' | 'vite' | 'astro' | 'plain', meta: any }}
+ */
+export function detectProject(cwd = process.cwd()) {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) return { type: 'plain', meta: {} };
+
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+
+  if (deps['@webjskit/server'] || deps['@webjskit/cli'] || existsSync(join(cwd, 'app', 'layout.ts')) || existsSync(join(cwd, 'app', 'layout.js'))) {
+    return { type: 'webjs', meta: { pkg } };
+  }
+  if (deps['next']) return { type: 'next', meta: { pkg } };
+  if (deps['vite'] || deps['@vitejs/plugin-react'] || deps['@vitejs/plugin-vue']) return { type: 'vite', meta: { pkg } };
+  if (deps['astro']) return { type: 'astro', meta: { pkg } };
+
+  return { type: 'plain', meta: { pkg } };
+}
+
+/**
+ * Pick default `aliases` + `tailwind.css` path based on the detected project.
+ *
+ * @param {string} cwd
+ */
+export function defaultsForProject(cwd = process.cwd()) {
+  const { type } = detectProject(cwd);
+  switch (type) {
+    case 'webjs':
+      return {
+        tailwindCss: 'app/globals.css',
+        aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
+      };
+    case 'next':
+      return {
+        tailwindCss: 'app/globals.css',
+        aliases: { components: '@/components', utils: '@/lib/utils', ui: '@/components/ui', lib: '@/lib' },
+      };
+    case 'vite':
+      return {
+        tailwindCss: 'src/index.css',
+        aliases: { components: 'src/components', utils: 'src/lib/utils', ui: 'src/components/ui', lib: 'src/lib' },
+      };
+    case 'astro':
+      return {
+        tailwindCss: 'src/styles/globals.css',
+        aliases: { components: 'src/components', utils: 'src/lib/utils', ui: 'src/components/ui', lib: 'src/lib' },
+      };
+    default:
+      return {
+        tailwindCss: 'styles/globals.css',
+        aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
+      };
+  }
+}

package/src/utils/get-config.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { rawConfigSchema } from '../registry/schema.js';
+
+export const CONFIG_FILE = 'components.json';
+
+/**
+ * Read components.json from the given cwd. Returns null if missing.
+ *
+ * @param {string} cwd
+ */
+export function getConfig(cwd = process.cwd()) {
+  const p = join(cwd, CONFIG_FILE);
+  if (!existsSync(p)) return null;
+  const raw = JSON.parse(readFileSync(p, 'utf8'));
+  const parsed = rawConfigSchema.parse(raw);
+  return {
+    ...parsed,
+    resolvedPaths: resolvePaths(cwd, parsed),
+  };
+}
+
+function resolvePaths(cwd, config) {
+  return {
+    cwd: resolve(cwd),
+    tailwindCss: resolve(cwd, config.tailwind.css),
+    components: resolve(cwd, config.aliases.components.replace(/^@\//, '')),
+    utils: resolve(cwd, config.aliases.utils.replace(/^@\//, '') + '.ts'),
+    ui: resolve(cwd, (config.aliases.ui || 'components/ui').replace(/^@\//, '')),
+    lib: resolve(cwd, (config.aliases.lib || 'lib').replace(/^@\//, '')),
+  };
+}
+
+/**
+ * Write components.json.
+ *
+ * @param {string} cwd
+ * @param {any} config
+ */
+export function writeConfig(cwd, config) {
+  const p = join(cwd, CONFIG_FILE);
+  writeFileSync(p, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}

package/src/utils/index.js

@@ -0,0 +1,3 @@
+export { getConfig, writeConfig, CONFIG_FILE } from './get-config.js';
+export { detectProject, defaultsForProject } from './detect-project.js';
+export { logger } from './logger.js';

package/src/utils/logger.js

@@ -0,0 +1,13 @@
+import kleur from 'kleur';
+
+export const logger = {
+  info: (...args) => console.log(...args),
+  success: (...args) => console.log(kleur.green('✔'), ...args),
+  warn: (...args) => console.log(kleur.yellow('⚠'), ...args),
+  error: (...args) => console.error(kleur.red('✖'), ...args),
+  break: () => console.log(''),
+  dim: (s) => kleur.dim(s),
+  bold: (s) => kleur.bold(s),
+  cyan: (s) => kleur.cyan(s),
+  green: (s) => kleur.green(s),
+};