base-themes 0.1.1 → 0.1.3

package/examples/next/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "base-themes-next-example",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "next dev -H 0.0.0.0 -p 3001",
+    "build": "next build",
+    "start": "next start -H 0.0.0.0 -p 3001"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.5.0",
+    "base-themes": "file:../..",
+    "next": "^16.0.6",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "~6.0.2"
+  },
+  "overrides": {
+    "postcss": "^8.5.10"
+  }
+}

package/examples/next/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2023"
+    ],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/examples/registry-copy/README.md

@@ -0,0 +1,73 @@
+# Registry Copy Example
+
+This example demonstrates how tools and agents can consume `base-themes/registry.json` to inspect the package registry, plan a source-copy install, preview copied files, and diagnose a consumer app.
+
+The script mirrors the published `base-themes` CLI and resolves component names, `block:<name>` requests, and `theme:<style>` requests. It prints:
+
+- package dependencies
+- global and token CSS files
+- block source files and shared block CSS
+- component source files
+- requested and available theme variants
+- registry item imports and hosted item URLs for agent workflows
+
+## Run
+
+From the repository root:
+
+```bash
+npm run example:registry-copy -- button select block:dashboard-shell theme:enterprise
+npm run example:registry-copy -- plan button select block:dashboard-shell theme:enterprise --json
+npm run example:registry-copy -- add button select block:dashboard-shell theme:enterprise --target . --dry-run --json
+npm run example:registry-copy -- doctor examples/vite --json
+```
+
+Or run the script directly:
+
+```bash
+node examples/registry-copy/plan-copy.mjs button select block:dashboard-shell theme:enterprise
+node examples/registry-copy/plan-copy.mjs list --json
+node examples/registry-copy/plan-copy.mjs plan button select block:dashboard-shell theme:enterprise --json
+node examples/registry-copy/plan-copy.mjs add button select block:dashboard-shell theme:enterprise --target . --dry-run
+node examples/registry-copy/plan-copy.mjs doctor examples/vite
+```
+
+The published package also exposes the same planner through the `base-themes` CLI:
+
+```bash
+npx base-themes list
+npx base-themes list --json
+npx base-themes plan button select block:dashboard-shell theme:enterprise
+npx base-themes plan button select block:dashboard-shell theme:enterprise --json
+npx base-themes add button select block:dashboard-shell theme:enterprise --target . --dry-run
+npx base-themes add button select block:dashboard-shell theme:enterprise --target . --dry-run --json
+npx base-themes doctor .
+npx base-themes doctor . --json
+```
+
+`add` runs the conservative copy path for users who want source files in their app. It copies only registry-listed files, skips existing files by default, and requires `--force` before overwriting.
+
+`doctor` is meant for a consumer app root. It reports missing dependencies, the CSS import, and theme attributes, then prints the next fix and bug-report link for failed checks.
+
+Example output:
+
+```text
+Base Themes registry copy plan
+Components: button, select, progress, meter
+Blocks: dashboard-shell
+Themes: enterprise
+Dependencies: @base-ui/react, clsx, lucide-react
+Style files: src/index.css, src/styles/tokens.css, src/styles/themes.css, ...
+Block files:
+- src/blocks/DashboardShell.tsx
+- src/blocks/Blocks.css
+Component files:
+- src/components/ui/Button.tsx
+- src/components/ui/Button.css
+...
+Registry item imports:
+- button: base-themes/registry/items/button.json
+- theme:enterprise: base-themes/registry/items/theme-enterprise.json
+```
+
+`plan` is intentionally a planner. `add` is intentionally conservative: source-copy tools should still decide lockfile behavior and app-specific formatting explicitly.

package/examples/registry-copy/plan-copy.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { createDoctorReport, createRegistryAdd, createRegistryPlan, formatDoctorReport, formatRegistryAdd, formatRegistryList, formatRegistryPlan, loadRegistry } from '../../scripts/registry-plan.mjs'
+
+const registry = loadRegistry()
+const [maybeCommand, ...rest] = process.argv.slice(2)
+
+function printHelp() {
+  console.log(`Registry Copy Example
+
+Usage:
+  node examples/registry-copy/plan-copy.mjs list [--json]
+  node examples/registry-copy/plan-copy.mjs plan <component...> [block:<block-name>...] [theme:<style>...] [--json]
+  node examples/registry-copy/plan-copy.mjs add <component...> [block:<block-name>...] [theme:<style>...] [--target <dir>] [--dry-run] [--force] [--json]
+  node examples/registry-copy/plan-copy.mjs doctor [project-root] [--json]
+
+Backwards-compatible shorthand:
+  node examples/registry-copy/plan-copy.mjs <component...> [block:<block-name>...] [theme:<style>...] [--json]
+
+Examples:
+  node examples/registry-copy/plan-copy.mjs button select block:dashboard-shell theme:enterprise
+  node examples/registry-copy/plan-copy.mjs plan button select block:dashboard-shell theme:enterprise --json
+  node examples/registry-copy/plan-copy.mjs add button select block:dashboard-shell theme:enterprise --target . --dry-run
+`)
+}
+
+function parseRegistryArgs(args) {
+  const requested = []
+  const options = {}
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === '--dry-run') {
+      options.dryRun = true
+      continue
+    }
+    if (arg === '--force') {
+      options.force = true
+      continue
+    }
+    if (arg === '--json') {
+      options.json = true
+      continue
+    }
+    if (arg === '--target') {
+      const target = args[index + 1]
+      if (!target) throw new Error('Missing value for --target')
+      options.target = target
+      index += 1
+      continue
+    }
+    if (arg.startsWith('--target=')) {
+      options.target = arg.slice('--target='.length)
+      continue
+    }
+    if (arg.startsWith('--')) throw new Error(`Unknown registry-copy option: ${arg}`)
+    requested.push(arg)
+  }
+
+  return { requested, options }
+}
+
+function printResult(value, json, formatter) {
+  console.log(json ? JSON.stringify(value, null, 2) : formatter(value))
+}
+
+function failWithUsage(message, usage) {
+  if (message) console.error(message)
+  console.error(usage)
+  process.exit(1)
+}
+
+if (!maybeCommand || maybeCommand === 'help' || maybeCommand === '--help' || maybeCommand === '-h') {
+  printHelp()
+  process.exit(0)
+}
+
+const knownCommands = new Set(['list', 'plan', 'add', 'doctor'])
+const command = knownCommands.has(maybeCommand) ? maybeCommand : 'plan'
+const args = command === 'plan' && !knownCommands.has(maybeCommand) ? [maybeCommand, ...rest] : rest
+
+if (command === 'list') {
+  const json = args.includes('--json')
+  const unknownArgs = args.filter((arg) => arg !== '--json')
+  if (unknownArgs.length > 0) failWithUsage(`Unknown list option: ${unknownArgs[0]}`, 'Usage: node examples/registry-copy/plan-copy.mjs list [--json]')
+  printResult(registry, json, formatRegistryList)
+  process.exit(0)
+}
+
+if (command === 'plan') {
+  let parsed
+  try {
+    parsed = parseRegistryArgs(args)
+  } catch (error) {
+    failWithUsage(error.message, 'Usage: node examples/registry-copy/plan-copy.mjs plan <component...> [block:<block-name>...] [theme:<style>...] [--json]')
+  }
+
+  if (parsed.requested.length === 0) failWithUsage(undefined, 'Usage: node examples/registry-copy/plan-copy.mjs plan <component...> [block:<block-name>...] [theme:<style>...] [--json]')
+
+  const plan = createRegistryPlan(registry, parsed.requested)
+  printResult(plan, parsed.options.json, formatRegistryPlan)
+  process.exit(plan.ok ? 0 : 1)
+}
+
+if (command === 'add') {
+  let parsed
+  try {
+    parsed = parseRegistryArgs(args)
+  } catch (error) {
+    failWithUsage(error.message, 'Usage: node examples/registry-copy/plan-copy.mjs add <component...> [block:<block-name>...] [theme:<style>...] [--target <dir>] [--dry-run] [--force] [--json]')
+  }
+
+  if (parsed.requested.length === 0) failWithUsage(undefined, 'Usage: node examples/registry-copy/plan-copy.mjs add <component...> [block:<block-name>...] [theme:<style>...] [--target <dir>] [--dry-run] [--force] [--json]')
+
+  const result = createRegistryAdd(registry, parsed.requested, parsed.options)
+  printResult(result, parsed.options.json, formatRegistryAdd)
+  process.exit(result.ok ? 0 : 1)
+}
+
+if (command === 'doctor') {
+  const json = args.includes('--json')
+  const positional = args.filter((arg) => arg !== '--json')
+  if (positional.some((arg) => arg.startsWith('--'))) failWithUsage(`Unknown doctor option: ${positional.find((arg) => arg.startsWith('--'))}`, 'Usage: node examples/registry-copy/plan-copy.mjs doctor [project-root] [--json]')
+  if (positional.length > 1) failWithUsage(undefined, 'Usage: node examples/registry-copy/plan-copy.mjs doctor [project-root] [--json]')
+  const root = positional[0] ?? process.cwd()
+  const report = createDoctorReport(root)
+  printResult(report, json, formatDoctorReport)
+  process.exit(report.ok ? 0 : 1)
+}
+
+failWithUsage(`Unknown command: ${command}`, 'Usage: node examples/registry-copy/plan-copy.mjs help')

package/examples/theme-customization/README.md

@@ -0,0 +1,26 @@
+# Base Themes Theme Customization Example
+
+This Vite example shows how to customize Base Themes from the public package surface. It imports the package CSS once, then overrides semantic CSS tokens for brand color, radius, font, and density.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://localhost:5178`.
+
+## Verify
+
+```bash
+npm run build
+```
+
+The example intentionally imports only documented package paths:
+
+- `base-themes`
+- `base-themes/styles.css`
+- `base-themes/registry.json`
+
+Use it when validating token changes, custom brand overrides, or docs that explain `data-style`, `data-theme`, and CSS variable customization.

package/examples/theme-customization/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en" data-theme="light" data-style="bento">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Base Themes Theme Customization Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>