trix-ui 0.2.2 → 0.2.4

package/README.md

@@ -1,306 +1,306 @@
-<!-- # trix-ui
-
-A small, registry-driven CLI that installs minimal, accessible UI components into your app.
-
-## Install
-
-Use it with npx or install as a dev dependency.
-
-```bash
-npx trix-ui init
-```
-
-```bash
-npm install -D trix-ui
-ui init
-```
-
-## Quickstart
-
-```bash
-npx trix-ui init
-npx trix-ui add button card dialog
-npx trix-ui add-section hero
-npx trix-ui add-wrapper glow-wrapper
-npx trix-ui remove button
-npx trix-ui remove --section hero
-npx trix-ui remove --wrapper glow-wrapper
-npx trix-ui list
-npx trix-ui list --type sections
-npx trix-ui list --type wrappers
-npx trix-ui doctor
-```
-
-## How it works (detailed)
-
-### High-level model
-`trix-ui` is a registry-driven CLI. It installs UI assets into your app by copying
-templates and recording those installs in a lockfile. The registry is a JSON catalog
-of components, sections, wrappers, and composites. Each entry describes:
-- which template files to copy
-- where those files should land in your project
-- any local or npm dependencies
-
-### Core files and directories
-When you run `ui init`, the CLI prepares a project for installs:
-- `trix-ui.json` (config)
-- `components/ui`, `components/sections`, `components/wrappers`, `components/composites`
-- `lib/utils.ts`
-- `styles/globals.css`
-- `.ui/lock.json` (install tracking)
-
-The lockfile is the source of truth for what the CLI has installed and is used
-to safely remove files later.
-
-### Data flow (install)
-1. Resolve working directory (`--cwd` or `process.cwd()`).
-2. Load config from `trix-ui.json` (merged with defaults).
-3. Load registry (bundled by default or local if configured).
-4. Load lockfile (creates empty lockfile if none exists).
-5. Validate inputs (normalize names and verify registry entries).
-6. Analyze dependencies:
-   - `dependencies.local` installs other registry components first.
-   - `dependencies.npm` are collected for optional install.
-7. Handle conflicts (existing files/lockfile entries) with prompts, or `--force`.
-8. Copy templates into target paths.
-9. Update lockfile with installed entries and files.
-10. Optionally install npm dependencies (`--skip-deps` to skip).
-
-### Dependency resolution
-- **Local dependencies** (`dependencies.local`) are other registry components and
-  are installed before sections/wrappers/composites.
-- **NPM dependencies** (`dependencies.npm`) are optional and can be installed
-  by the CLI via your package manager.
-
-### Conflict handling
-If a target file already exists or an entry is in the lockfile:
-- Default: skip and warn.
-- `--force`: overwrite files and update lockfile entries.
-- `--yes`: auto-confirm prompts.
-
-### Safe removal
-- `ui remove` and related commands remove only files tracked in `.ui/lock.json`.
-- `--force` removes files based on registry targets even if not tracked.
-
-### Registry resolution
-- **Bundled registry** (default): packaged with the CLI (`registry/index.json`).
-- **Local registry**: configure `registry` in `trix-ui.json` to point to a custom
-  registry file (and optional templates path).
-
-### Tokens and path resolution
-Registry `target` fields support tokens:
-`{{components}}`, `{{sections}}`, `{{wrappers}}`, `{{composites}}`, `{{lib}}`, `{{styles}}`.
-Tokens are resolved using `trix-ui.json` paths, then converted to absolute paths.
-Note: `{{lib}}` resolves to the `paths.utils` file path.
-
-### Doctor command
-`ui doctor` checks:
-- config presence and validity
-- required directories/files
-- registry load errors
-- lockfile existence
-
-## Commands
-
-- `ui init` - Creates `trix-ui.json`, `components/ui`, `lib/utils.ts`, `styles/globals.css`, and `.ui/lock.json`.
-- `ui add <component...>` - Copies templates into `components/ui` and updates `.ui/lock.json`.
-- `ui add-section <section...>` - Copies section templates into `components/sections` and updates `.ui/lock.json`.
-- `ui add-wrapper <wrapper...>` - Copies wrapper templates into `components/wrappers` and updates `.ui/lock.json`.
-- `ui add-composite <composite...>` - Copies composite templates into `components/composites` and updates `.ui/lock.json`.
-- `ui remove <component...>` - Removes only files tracked in `.ui/lock.json` (safe by default).
-- `ui remove --section <section...>` - Removes only section files tracked in `.ui/lock.json` (safe by default).
-- `ui remove --wrapper <wrapper...>` - Removes only wrapper files tracked in `.ui/lock.json` (safe by default).
-- `ui remove --composite <composite...>` - Removes only composite files tracked in `.ui/lock.json` (safe by default).
-- `ui list` - Lists registry components, sections, wrappers, and composites.
-- `ui list --type sections` - Lists registry sections only.
-- `ui list --type wrappers` - Lists registry wrappers only.
-- `ui list --type composites` - Lists registry composites only.
-- `ui doctor` - Checks config, registry, and required files.
-
-## Config (trix-ui.json)
-
-```json
-{
-  "registry": {
-    "type": "bundled"
-  },
-  "paths": {
-    "components": "components/ui",
-    "sections": "components/sections",
-    "wrappers": "components/wrappers",
-    "composites": "components/composites",
-    "utils": "lib/utils.ts",
-    "styles": "styles/globals.css"
-  },
-  "barrel": false
-}
-```
-
-Notes:
-- `registry.type`:
-  - `bundled` uses the registry packaged with the CLI (default).
-- Set `barrel: true` and run `ui init --barrel` to create `components/ui/index.ts`.
-
-## Registry format
-
-`registry/index.json`:
-
-```json
-{
-  "version": 1,
-  "components": [
-    {
-      "name": "button",
-      "description": "Button with variants and focus ring.",
-      "files": [
-        {
-          "source": "components/ui/button.tsx",
-          "target": "{{components}}/button.tsx"
-        }
-      ],
-      "dependencies": {
-        "npm": ["clsx", "tailwind-merge"]
-      }
-    }
-  ],
-  "sections": [
-    {
-      "name": "hero",
-      "description": "Hero section with headline, bullets, and CTAs.",
-      "files": [
-        {
-          "source": "sections/hero.tsx",
-          "target": "{{sections}}/hero.tsx"
-        }
-      ],
-      "dependencies": {
-        "local": ["badge", "button"]
-      }
-    }
-  ],
-  "wrappers": [
-    {
-      "name": "glow-wrapper",
-      "description": "Glow effect wrapper for highlighting key components.",
-      "files": [
-        {
-          "source": "wrappers/glow-wrapper.tsx",
-          "target": "{{wrappers}}/glow-wrapper.tsx"
-        }
-      ]
-    }
-  ],
-  "composites": [
-    {
-      "name": "marketing-stack",
-      "description": "Composite layout for stacked marketing sections.",
-      "files": [
-        {
-          "source": "composites/marketing-stack.tsx",
-          "target": "{{composites}}/marketing-stack.tsx"
-        }
-      ],
-      "dependencies": {
-        "local": ["button", "card"]
-      }
-    }
-  ]
-}
-```
-
-- `source` is relative to `templates/`.
-- `target` supports tokens: `{{components}}`, `{{sections}}`, `{{wrappers}}`, `{{composites}}`, `{{lib}}`, `{{styles}}`.
-- `dependencies.local` installs registry components before the section, wrapper, or composite.
-- `dependencies.npm` are printed after install; you install them manually.
-
-## Add a new component
-
-1. Create a template in `templates/components/ui/<name>.tsx`.
-2. Add a registry entry in `registry/index.json`.
-3. Run `ui add <name>` in your app.
-
-## Add a new section
-
-1. Create a template in `templates/sections/<name>.tsx`.
-2. Add a registry entry in `registry/index.json` under `sections`.
-3. Run `ui add-section <name>` in your app.
-
-## Add a new wrapper
-
-1. Create a template in `templates/wrappers/<name>.tsx`.
-2. Add a registry entry in `registry/index.json` under `wrappers`.
-3. Run `ui add-wrapper <name>` in your app.
-
-## Add a new composite
-
-1. Create a template in `templates/composites/<name>.tsx`.
-2. Add a registry entry in `registry/index.json` under `composites`.
-3. Run `ui add-composite <name>` in your app.
-
-## Tailwind setup
-
-Add CSS variables in `styles/globals.css` (installed by `ui init`).
-In your Tailwind config, map colors to CSS variables, for example:
-
-```ts
-export default {
-  theme: {
-    extend: {
-      colors: {
-        border: "hsl(var(--border))",
-        input: "hsl(var(--input))",
-        ring: "hsl(var(--ring))",
-        background: "hsl(var(--background))",
-        foreground: "hsl(var(--foreground))",
-        primary: {
-          DEFAULT: "hsl(var(--primary))",
-          foreground: "hsl(var(--primary-foreground))"
-        },
-        secondary: {
-          DEFAULT: "hsl(var(--secondary))",
-          foreground: "hsl(var(--secondary-foreground))"
-        },
-        muted: {
-          DEFAULT: "hsl(var(--muted))",
-          foreground: "hsl(var(--muted-foreground))"
-        },
-        accent: {
-          DEFAULT: "hsl(var(--accent))",
-          foreground: "hsl(var(--accent-foreground))"
-        },
-        destructive: {
-          DEFAULT: "hsl(var(--destructive))",
-          foreground: "hsl(var(--destructive-foreground))"
-        },
-        card: {
-          DEFAULT: "hsl(var(--card))",
-          foreground: "hsl(var(--card-foreground))"
-        },
-        popover: {
-          DEFAULT: "hsl(var(--popover))",
-          foreground: "hsl(var(--popover-foreground))"
-        }
-      },
-      borderRadius: {
-        lg: "var(--radius)",
-        md: "calc(var(--radius) - 2px)",
-        sm: "calc(var(--radius) - 4px)"
-      }
-    }
-  }
-}
-```
-
-## Troubleshooting
-
-`ui doctor` reports common issues:
-- missing `trix-ui.json`
-- missing `components/ui` directory
-- missing `lib/utils.ts` or `styles/globals.css`
-- registry load failures
-- missing `.ui/lock.json`
-
-## Notes
-
-- Requires Node 18+ for built-in `fetch`.
-- Paths are stored in `.ui/lock.json` relative to the project root for Windows/Mac safety. -->
+<!-- # trix-ui
+
+A small, registry-driven CLI that installs minimal, accessible UI components into your app.
+
+## Install
+
+Use it with npx or install as a dev dependency.
+
+```bash
+npx trix-ui init
+```
+
+```bash
+npm install -D trix-ui
+ui init
+```
+
+## Quickstart
+
+```bash
+npx trix-ui init
+npx trix-ui add button card dialog
+npx trix-ui add-section hero
+npx trix-ui add-wrapper glow-wrapper
+npx trix-ui remove button
+npx trix-ui remove --section hero
+npx trix-ui remove --wrapper glow-wrapper
+npx trix-ui list
+npx trix-ui list --type sections
+npx trix-ui list --type wrappers
+npx trix-ui doctor
+```
+
+## How it works (detailed)
+
+### High-level model
+`trix-ui` is a registry-driven CLI. It installs UI assets into your app by copying
+templates and recording those installs in a lockfile. The registry is a JSON catalog
+of components, sections, wrappers, and composites. Each entry describes:
+- which template files to copy
+- where those files should land in your project
+- any local or npm dependencies
+
+### Core files and directories
+When you run `ui init`, the CLI prepares a project for installs:
+- `trix-ui.json` (config)
+- `components/ui`, `components/sections`, `components/wrappers`, `components/composites`
+- `lib/utils.ts`
+- `styles/globals.css`
+- `.ui/lock.json` (install tracking)
+
+The lockfile is the source of truth for what the CLI has installed and is used
+to safely remove files later.
+
+### Data flow (install)
+1. Resolve working directory (`--cwd` or `process.cwd()`).
+2. Load config from `trix-ui.json` (merged with defaults).
+3. Load registry (bundled by default or local if configured).
+4. Load lockfile (creates empty lockfile if none exists).
+5. Validate inputs (normalize names and verify registry entries).
+6. Analyze dependencies:
+   - `dependencies.local` installs other registry components first.
+   - `dependencies.npm` are collected for optional install.
+7. Handle conflicts (existing files/lockfile entries) with prompts, or `--force`.
+8. Copy templates into target paths.
+9. Update lockfile with installed entries and files.
+10. Optionally install npm dependencies (`--skip-deps` to skip).
+
+### Dependency resolution
+- **Local dependencies** (`dependencies.local`) are other registry components and
+  are installed before sections/wrappers/composites.
+- **NPM dependencies** (`dependencies.npm`) are optional and can be installed
+  by the CLI via your package manager.
+
+### Conflict handling
+If a target file already exists or an entry is in the lockfile:
+- Default: skip and warn.
+- `--force`: overwrite files and update lockfile entries.
+- `--yes`: auto-confirm prompts.
+
+### Safe removal
+- `ui remove` and related commands remove only files tracked in `.ui/lock.json`.
+- `--force` removes files based on registry targets even if not tracked.
+
+### Registry resolution
+- **Bundled registry** (default): packaged with the CLI (`registry/index.json`).
+- **Local registry**: configure `registry` in `trix-ui.json` to point to a custom
+  registry file (and optional templates path).
+
+### Tokens and path resolution
+Registry `target` fields support tokens:
+`{{components}}`, `{{sections}}`, `{{wrappers}}`, `{{composites}}`, `{{lib}}`, `{{styles}}`.
+Tokens are resolved using `trix-ui.json` paths, then converted to absolute paths.
+Note: `{{lib}}` resolves to the `paths.utils` file path.
+
+### Doctor command
+`ui doctor` checks:
+- config presence and validity
+- required directories/files
+- registry load errors
+- lockfile existence
+
+## Commands
+
+- `ui init` - Creates `trix-ui.json`, `components/ui`, `lib/utils.ts`, `styles/globals.css`, and `.ui/lock.json`.
+- `ui add <component...>` - Copies templates into `components/ui` and updates `.ui/lock.json`.
+- `ui add-section <section...>` - Copies section templates into `components/sections` and updates `.ui/lock.json`.
+- `ui add-wrapper <wrapper...>` - Copies wrapper templates into `components/wrappers` and updates `.ui/lock.json`.
+- `ui add-composite <composite...>` - Copies composite templates into `components/composites` and updates `.ui/lock.json`.
+- `ui remove <component...>` - Removes only files tracked in `.ui/lock.json` (safe by default).
+- `ui remove --section <section...>` - Removes only section files tracked in `.ui/lock.json` (safe by default).
+- `ui remove --wrapper <wrapper...>` - Removes only wrapper files tracked in `.ui/lock.json` (safe by default).
+- `ui remove --composite <composite...>` - Removes only composite files tracked in `.ui/lock.json` (safe by default).
+- `ui list` - Lists registry components, sections, wrappers, and composites.
+- `ui list --type sections` - Lists registry sections only.
+- `ui list --type wrappers` - Lists registry wrappers only.
+- `ui list --type composites` - Lists registry composites only.
+- `ui doctor` - Checks config, registry, and required files.
+
+## Config (trix-ui.json)
+
+```json
+{
+  "registry": {
+    "type": "bundled"
+  },
+  "paths": {
+    "components": "components/ui",
+    "sections": "components/sections",
+    "wrappers": "components/wrappers",
+    "composites": "components/composites",
+    "utils": "lib/utils.ts",
+    "styles": "styles/globals.css"
+  },
+  "barrel": false
+}
+```
+
+Notes:
+- `registry.type`:
+  - `bundled` uses the registry packaged with the CLI (default).
+- Set `barrel: true` and run `ui init --barrel` to create `components/ui/index.ts`.
+
+## Registry format
+
+`registry/index.json`:
+
+```json
+{
+  "version": 1,
+  "components": [
+    {
+      "name": "button",
+      "description": "Button with variants and focus ring.",
+      "files": [
+        {
+          "source": "components/ui/button.tsx",
+          "target": "{{components}}/button.tsx"
+        }
+      ],
+      "dependencies": {
+        "npm": ["clsx", "tailwind-merge"]
+      }
+    }
+  ],
+  "sections": [
+    {
+      "name": "hero",
+      "description": "Hero section with headline, bullets, and CTAs.",
+      "files": [
+        {
+          "source": "sections/hero.tsx",
+          "target": "{{sections}}/hero.tsx"
+        }
+      ],
+      "dependencies": {
+        "local": ["badge", "button"]
+      }
+    }
+  ],
+  "wrappers": [
+    {
+      "name": "glow-wrapper",
+      "description": "Glow effect wrapper for highlighting key components.",
+      "files": [
+        {
+          "source": "wrappers/glow-wrapper.tsx",
+          "target": "{{wrappers}}/glow-wrapper.tsx"
+        }
+      ]
+    }
+  ],
+  "composites": [
+    {
+      "name": "marketing-stack",
+      "description": "Composite layout for stacked marketing sections.",
+      "files": [
+        {
+          "source": "composites/marketing-stack.tsx",
+          "target": "{{composites}}/marketing-stack.tsx"
+        }
+      ],
+      "dependencies": {
+        "local": ["button", "card"]
+      }
+    }
+  ]
+}
+```
+
+- `source` is relative to `templates/`.
+- `target` supports tokens: `{{components}}`, `{{sections}}`, `{{wrappers}}`, `{{composites}}`, `{{lib}}`, `{{styles}}`.
+- `dependencies.local` installs registry components before the section, wrapper, or composite.
+- `dependencies.npm` are printed after install; you install them manually.
+
+## Add a new component
+
+1. Create a template in `templates/components/ui/<name>.tsx`.
+2. Add a registry entry in `registry/index.json`.
+3. Run `ui add <name>` in your app.
+
+## Add a new section
+
+1. Create a template in `templates/sections/<name>.tsx`.
+2. Add a registry entry in `registry/index.json` under `sections`.
+3. Run `ui add-section <name>` in your app.
+
+## Add a new wrapper
+
+1. Create a template in `templates/wrappers/<name>.tsx`.
+2. Add a registry entry in `registry/index.json` under `wrappers`.
+3. Run `ui add-wrapper <name>` in your app.
+
+## Add a new composite
+
+1. Create a template in `templates/composites/<name>.tsx`.
+2. Add a registry entry in `registry/index.json` under `composites`.
+3. Run `ui add-composite <name>` in your app.
+
+## Tailwind setup
+
+Add CSS variables in `styles/globals.css` (installed by `ui init`).
+In your Tailwind config, map colors to CSS variables, for example:
+
+```ts
+export default {
+  theme: {
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))"
+        },
+        secondary: {
+          DEFAULT: "hsl(var(--secondary))",
+          foreground: "hsl(var(--secondary-foreground))"
+        },
+        muted: {
+          DEFAULT: "hsl(var(--muted))",
+          foreground: "hsl(var(--muted-foreground))"
+        },
+        accent: {
+          DEFAULT: "hsl(var(--accent))",
+          foreground: "hsl(var(--accent-foreground))"
+        },
+        destructive: {
+          DEFAULT: "hsl(var(--destructive))",
+          foreground: "hsl(var(--destructive-foreground))"
+        },
+        card: {
+          DEFAULT: "hsl(var(--card))",
+          foreground: "hsl(var(--card-foreground))"
+        },
+        popover: {
+          DEFAULT: "hsl(var(--popover))",
+          foreground: "hsl(var(--popover-foreground))"
+        }
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+`ui doctor` reports common issues:
+- missing `trix-ui.json`
+- missing `components/ui` directory
+- missing `lib/utils.ts` or `styles/globals.css`
+- registry load failures
+- missing `.ui/lock.json`
+
+## Notes
+
+- Requires Node 18+ for built-in `fetch`.
+- Paths are stored in `.ui/lock.json` relative to the project root for Windows/Mac safety. -->