cooterlabs 1.0.2 → 2.1.0

package/README.md

@@ -1,80 +1,263 @@
 # CooterLabs UI Library CLI
 
-A blazingly fast, standalone CLI tool for scaffolding beautiful, accessible, and highly customizable UI components built strictly for React, Vite, and Next.js applications directly into your project via the terminal!
+A standalone CLI for scaffolding the **Aeon Product Design System** — beautiful, accessible, highly customizable React components — directly into your React, Vite, or Next.js project.
 
-It brings components directly to you. We do not provide a generic NPM library package to import elements from. Instead, the actual React TS/JS code is scaffolded straight into your `src/components/ui` folder, meaning you completely own the implementation, styles, and markup.
+It brings components directly to you. This is **not** an importable NPM package: the actual React TS/JS source is scaffolded straight into your `src/components/ui` folder, so you completely own the implementation, styles, and markup. Think shadcn/ui, but for the Aeon design system.
+
+```bash
+npx cooterlabs init        # set up the theme
+npx cooterlabs add button  # scaffold a component
+```
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Commands](#commands)
+  - [`init` — theme setup](#init--theme-setup)
+  - [`add` — scaffold components](#add--scaffold-components)
+- [The shared `cn()` utility](#the-shared-cn-utility)
+- [The Aeon theme](#the-aeon-theme)
+  - [Semantic colors](#semantic-colors)
+  - [Primitive color scales](#primitive-color-scales)
+  - [Typography ramp](#typography-ramp)
+  - [Radius, elevation & focus ring](#radius-elevation--focus-ring)
+- [Component reference](#component-reference)
+- [How it works under the hood](#how-it-works-under-the-hood)
+- [Changelog](#changelog)
+- [License](#license)
+
+---
 
 ## Features
 
-- **✅ Project Detection**: Auto-detects your ecosystem (Next.js App router/Pages router, Vite, Create React App).
-- **✅ TypeScript vs. JavaScript**: Installs `.tsx` component files if you use TypeScript, gracefully falling back to stripped `.jsx` components for vanilla JS environments.
-- **✅ Tailwind Awareness**: Verifies you have Tailwind appropriately installed.
-- **✅ Dependency Auto-Install**: If the component you want needs `framer-motion`, `@radix-ui/react-checkbox` or even just `clsx`, the CLI automatically resolves these dependencies silently for you.
-- **✅ Prettier Formatting**: Uses your project's Prettier settings statically against our components before file creation so the component matches your exact code-style.
-- **✅ Interactive Interface**: Employs interactive menus to let you visually pick the component you want to build inside your project.
+- **Project detection** — auto-detects your ecosystem: Next.js (App router or Pages router), Vite, or Create React App, plus your package manager (`npm`, `pnpm`, `yarn`, `bun`) from lockfiles.
+- **TypeScript vs. JavaScript** — installs `.tsx` component files when TypeScript is detected (via `typescript` dependency or `tsconfig.json`), falling back to `.jsx` otherwise.
+- **Tailwind awareness** — warns if Tailwind CSS isn't detected, since all components are styled with Tailwind utilities.
+- **Dependency auto-install** — each component's runtime dependencies (`@radix-ui/*`, `lucide-react`, `clsx`, `tailwind-merge`) are resolved and installed automatically, collectively, in one pass.
+- **Component dependencies** — components that build on other components (e.g. `select` reuses `input`'s variant styles) automatically pull in what they need.
+- **Shared `cn()` helper** — a single `src/lib/utils.ts` is scaffolded once and shared by every component, with a tailwind-merge config that understands the Aeon type ramp (see [below](#the-shared-cn-utility)).
+- **Prettier formatting** — components are formatted with *your* project's Prettier config before being written, so they match your code style from the first commit.
+- **Interactive interface** — run without arguments to get an autocomplete multi-select of every available component.
 
-## Installation / Usage
+## Requirements
 
-1. Open your terminal at the root of your project directory.
-2. Ensure you have `tailwind-merge` and `clsx` properly configured in a central utility path or installed manually (some components will auto-detect and install these).
+- **React 18+** project (Vite, Next.js, or CRA).
+- **Tailwind CSS v4** for the default `aeon` theme (it's emitted as a v4 `@theme` block). The legacy `zinc` / `slate` themes target Tailwind v3 / shadcn-style HSL variables.
+- Node 18+ (the CLI is an ES module).
 
-### Initialization (Themes & CSS Base)
+---
 
-To swiftly set up a cohesive Tailwind theme and properly configure your base CSS file (e.g. `index.css` or `globals.css`), run:
+## Commands
+
+### `init` — theme setup
+
+Sets up the design-system CSS variables in your base stylesheet (`src/index.css`, `app/globals.css`, or `styles/globals.css` — resolved automatically per framework):
 
 ```bash
-npx cooterlabs init
+npx cooterlabs init          # interactive theme picker
+npx cooterlabs init aeon     # non-interactive, applies the default theme
 ```
 
-This will give you a list of carefully curated designer themes (like `zinc`, `slate`) to apply global default variables (background, foreground, primary borders, etc.) out-of-the-box.
+What it does:
+
+1. Locates (or creates) your base CSS file.
+2. Ensures the Tailwind entry point exists — `@import "tailwindcss";` for v4 themes, the classic `@tailwind base/components/utilities` trio for legacy themes.
+3. Appends the theme block. For **aeon** this is a Tailwind v4 `@theme static { … }` block plus the `alert-timer` keyframes used by the Alert component's auto-dismiss countdown.
+4. If theme variables already exist in the file, it prints the block for you to merge manually instead of clobbering your file.
 
-### Adding Components
+Available themes:
 
-Run the CLI tool without arguments to get an interactive autocomplete prompt:
+| Theme | Format | Description |
+|---|---|---|
+| `aeon` *(default)* | Tailwind v4 `@theme` | The full Aeon Product Design System — colors, type ramp, radii, elevation, focus ring. |
+| `zinc` | v3 / shadcn HSL `:root` vars | Legacy neutral theme. |
+| `slate` | v3 / shadcn HSL `:root` vars | Legacy cool-grey theme. |
+
+### `add` — scaffold components
 
 ```bash
-npx cooterlabs add
+npx cooterlabs add             # interactive multi-select
+npx cooterlabs add button      # one component
+npx cooterlabs add card badge  # ⚠️ one at a time — run twice, or use the picker
+npx cooterlabs add --all       # everything
 ```
 
-If you know exactly what component you want, bypass the interactive wizard and supply the name:
+What it does, per run:
 
-```bash
-# Example: Adding a Button
-npx cooterlabs add button
+1. Detects framework, TypeScript, Tailwind, and package manager.
+2. Expands component requirements — e.g. `add select` also scaffolds `input`, because `select.tsx` imports its shared variant styles from `./input`.
+3. Scaffolds `src/lib/utils.ts` (the shared `cn()` helper) if it doesn't exist yet.
+4. Copies each component into `src/components/ui/` (or `components/ui/` for Next.js without `src/`), formatted with your Prettier config.
+5. Installs the union of all required runtime dependencies in a single package-manager invocation.
+
+Existing files with the same name are overwritten — re-running `add` is also how you *update* a component to the latest version (diff your local changes first if you've customized it).
 
-# Example: Adding an Avatar
-npx cooterlabs add avatar
+---
+
+## The shared `cn()` utility
+
+Every component imports one helper:
+
+```ts
+import { cn } from "../../lib/utils"
 ```
 
-### Install All Components At Once
+The CLI scaffolds this file once, at `src/lib/utils.ts` (or `lib/utils.js`). It is **not** the stock shadcn two-liner — it uses `extendTailwindMerge` to teach tailwind-merge the Aeon font-size ramp:
 
-Need a complete starting block? Add the `--all` flag to scaffold the entire library in one go:
+```ts
+import { clsx, type ClassValue } from "clsx"
+import { extendTailwindMerge } from "tailwind-merge"
 
-```bash
-npx cooterlabs add --all
+const twMerge = extendTailwindMerge({
+    extend: {
+        classGroups: {
+            "font-size": [{ text: ["h1", …, "b4", …, "btn-tiny"] }],
+        },
+    },
+})
+
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs))
+}
+```
+
+**Why this matters:** without it, tailwind-merge treats custom utilities like `text-b4` as text *colors* and silently drops real color classes like `text-white` when they appear together. If you already have your own `lib/utils`, the CLI won't overwrite it — but make sure it includes this classGroups extension or component styles will subtly break.
+
+---
+
+## The Aeon theme
+
+Running `npx cooterlabs init aeon` gives you the complete design system as CSS variables, which Tailwind v4 turns into utilities automatically.
+
+### Semantic colors
+
+`background`, `foreground`, `card`, `popover`, `primary` (deep teal `#0d3435`), `secondary`, `muted`, `accent`, `destructive`, `border`, `input`, `ring` — plus status colors `success`, `info`, `warning`, `error`, each with a `-foreground` pair. Use them as `bg-primary`, `text-muted-foreground`, `border-border`, etc.
+
+### Primitive color scales
+
+Full 50–900 scales for `primary-*`, `grey-*`, `success-*`, `error-*`, `warning-*`, and `info-*` — e.g. `bg-primary-50`, `text-grey-500`, `border-error-200`. Components use these for hover/active/disabled states, so keep them if you retheme.
+
+### Typography ramp
+
+The entire Aeon type ramp ships as `--text-*` variables, each with size, line-height, **and weight** baked in:
+
+| Utilities | Role |
+|---|---|
+| `text-h1` … `text-h5` | Headings (48px/600 → 24px/600) |
+| `text-s1`, `text-s2` | Subtitles |
+| `text-b1` … `text-b4` | Body (regular & medium, 16px & 14px) |
+| `text-c1` … `text-c3` | Captions (12px & 10px) |
+| `text-label` | Form labels |
+| `text-btn-giant` … `text-btn-tiny` | Button text sizes |
+
+Font family: **Inter** (`--font-sans`). Load the font yourself (e.g. via Google Fonts or `@fontsource/inter`) — the theme only declares the stack.
+
+### Radius, elevation & focus ring
+
+- **Radius:** `rounded-xxs` (4px) → `rounded-xl` (24px).
+- **Elevation:** `shadow-100` → `shadow-800`.
+- **Focus ring:** `--shadow-focus` (a 3px `#c2f5f6` halo) — every interactive component uses `focus-visible:shadow-focus` for a consistent, accessible focus style.
+- **`@keyframes alert-timer`:** powers the Alert component's auto-dismiss countdown bar; emitted alongside the theme block.
+
+---
+
+## Component reference
+
+All components live in `components/ui/`, are fully typed, and follow the Aeon size ramp (`giant / large / medium / small / tiny`) where applicable. Radix-based components keep the full Radix composition API.
+
+### Form controls
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `button` | `Button` | `variant`: `filled` \| `outline` \| `clear` · `size`: giant→tiny · `iconOnly` · `asChild` (Radix `Slot`). |
+| `button-group` | `ButtonGroup`, `ButtonGroupItem` | Segmented control matching the button size ramp. |
+| `input` | `Input` (+ exported style maps reused by `select`) | `variant`: `outline` \| `filled` · `size`: `large` \| `medium` · `status`: success/info/warning/error · `helperText` · `icon`. |
+| `textarea` | `Textarea` | Multiline input matching `input` styling. |
+| `select` | `Select`, `SelectTrigger`, `SelectContent`, `SelectItem`, `SelectValue`, `SelectGroup`, … | Radix select styled as an Aeon input; **requires `input`** (auto-installed). |
+| `label` | `Label` | Radix label. |
+| `checkbox` | `Checkbox` | Radix checkbox with indeterminate support. |
+| `radio` | `RadioGroup`, `RadioGroupItem` | Radix radio group. |
+| `toggle` | `Toggle` | Radix switch. |
+
+### Feedback
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `alert` | `Alert`, `AlertTitle`, `AlertDescription`, `AlertActions` | `severity`: default/success/info/warning/error · `variant`: `filled` \| `outline` · `position` (fixed placements) · `duration` (auto-dismiss seconds, pauses on hover, animated countdown) · `onDismiss`. |
+| `badge` | `Badge` | `type`: `badge` \| `chip` (chips are dismissible/selectable) · `variant`: `filled` \| `outline` · `color`: default/success/info/warning/error · `size`: medium/small/tiny · `iconOnly`. |
+| `avatar` | `Avatar`, `AvatarImage`, `AvatarFallback` | Radix avatar, `size`: giant→tiny. |
+| `progress` | `Progress` | Radix progress; `label`: `left` \| `right` percentage label · `disabled`. |
+| `loader` | `Loader` | CSS spinner, `size`: giant→tiny. |
+| `tooltip` | `TooltipProvider`, `Tooltip`, `TooltipTrigger`, `TooltipContent` | Radix dark tooltip. |
+
+### Overlays
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `dialog` | `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, … | Radix dialog (Pop-Up). |
+| `action-sheet` | `ActionSheet`, `ActionSheetTrigger`, `ActionSheetContent`, … | Mobile bottom sheet built on Radix dialog. |
+| `context-menu` | `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`, checkbox/radio items, … | Radix context menu. |
+| `dropdown` | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, … | Radix dropdown menu. |
+
+### Navigation
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `tabs` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | Radix tabs. |
+| `breadcrumb` | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, … | Accessible breadcrumb trail. |
+| `pagination` | `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, … | Page navigation. |
+| `page-control` | `PageControl` | Mobile page-indicator dots. |
+| `stepper` | `Stepper`, `StepperItem`, `StepperSeparator` | Horizontal step indicator. |
+| `navbar-top` | `NavbarTop`, `NavbarTopLeft`, `NavbarTopTitle`, `NavbarTopRight` | Mobile top app bar. |
+| `navbar-bottom` | `NavbarBottom`, `NavbarBottomItem` | Mobile bottom tab bar. |
+| `list` | `List`, `ListHeader`, `ListItem` | Mobile list rows with leading/trailing slots. |
+
+### Layout
+
+| Component | Exports | Key props / notes |
+|---|---|---|
+| `card` | `Card`, `CardImage`, `CardHeader`, `CardFooter`, `CardTitle`, `CardDescription`, … | Composable card wrappers. |
+
+### Example
+
+```tsx
+import { Button } from "@/components/ui/button"
+import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert"
+
+export function Example() {
+    return (
+        <>
+            <Button variant="filled" size="large">Save changes</Button>
+            <Alert severity="success" duration={5} onDismiss={() => {}}>
+                <AlertTitle>Saved</AlertTitle>
+                <AlertDescription>Your changes are live.</AlertDescription>
+            </Alert>
+        </>
+    )
+}
 ```
 
-## Available Components
+---
+
+## How it works under the hood
 
-Currently, the CooterLabs Library ships with the following carefully designed boilerplate components:
+1. `npx cooterlabs add [component]` inspects your filesystem: lockfiles for the package manager, `package.json` deps for the framework, `tsconfig.json` for TypeScript, and Tailwind config/deps for styling support.
+2. Component requirements are expanded (`select` → `input`), then the shared `lib/utils` helper is scaffolded if missing.
+3. Templates are copied from the CLI package into `src/components/ui/` (or `components/ui/`), run through your Prettier config, and written with the right extension.
+4. The union of every selected component's runtime dependencies is installed in one package-manager call, so you only get libraries the components actually use.
 
-- `avatar` - An accessible React image element holding fallback identifiers.
-- `badge` - Tiny status badge elements relying on standard `variant` mappings.
-- `button` - A highly stylized native HTML button leveraging Radix UI primitives (`Slot`).
-- `card` - Content display wrappers comprising headers, footers, body content, and titles.
-- `checkbox` - Robust implementation for accessible `<input type="checkbox"/>` mappings.
-- `input` - Your standard customized HTML `<input />`.
-- `label` - An accessible Radix-backed `<label />`.
-- `textarea` - A matching multiline input variation styling perfectly with standard inputs.
+## Changelog
 
-## How it works under-the-hood
+### 2.1.0
 
-1. When you run `npx cooterlabs add [component]`, the script analyzes your filesystem looking for `pnpm-lock.yaml`, `bun.lockb`, `yarn.lock`, etc., and detects package managers.
-2. It looks for `tsconfig.json` to see if it should copy the raw `.tsx` component files or use regex parsers to strip types for a standard `.jsx` output.
-3. It recursively creates target folders, usually resolving to `src/components/ui` or `components/ui`.
-4. Formatting is applied.
-5. Child dependencies (e.g., `lucide-react`, Radix UI dependencies) required *exclusively* for that component are installed so the codebase isn't overwhelmed with useless imported libraries.
+- **Synced all 28 component templates** with the latest Aeon implementations (updated button/badge/alert variants, refined focus states using `shadow-focus`, tailwind-merge-safe type-ramp classes).
+- **New component: `select`** — Radix select styled as an Aeon input; auto-installs `input`, whose variant styles it reuses.
+- **Shared `cn()` helper** — components now import from `lib/utils` instead of inlining `cn` per file; the CLI scaffolds it (with the type-ramp-aware tailwind-merge config) on first `add`.
+- **Theme update** — the `aeon` theme now ships `--shadow-focus` (shared focus ring) and the `alert-timer` keyframes for Alert auto-dismiss.
 
 ## License
 
-MIT - Grab it, use it, scale it!
+MIT — Grab it, use it, scale it!