veloria-ui 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -7,6 +7,602 @@ This project follows [Semantic Versioning](https://semver.org).
 
 ---
 
+## [0.1.5] — 2026-03-17
+
+### `veloria-ui/motion` — Animated presence system
+
+A new zero-dependency animation sub-path built entirely on the **Web Animations API**. No additional `npm install` required — it ships inside the `veloria-ui` package and adds `0 bytes` to your bundle unless you actually import it.
+
+Import from `veloria-ui/motion`:
+
+```ts
+import {
+  Animated, MotionPresence, withMotion, useMotion,
+  MotionModal, MotionDrawer, MotionCard, MotionToast,
+  stagger, PRESETS, DURATIONS,
+} from "veloria-ui/motion";
+```
+
+---
+
+#### Architecture — 9 files, one entry point
+
+| File | Purpose |
+|------|---------|
+| `types.ts` | All TypeScript types — `MotionPreset`, `MotionConfig`, `MotionProps` |
+| `presets.ts` | 16 named presets as WAAPI keyframe arrays. Each preset < 200 bytes. |
+| `engine.ts` | Core runner — resolves config, checks `prefers-reduced-motion`, runs `element.animate()`, handles abort/cancel |
+| `useMotion.ts` | React hook — attach enter/exit to a ref, tracks visible state, fires `onExitComplete` |
+| `Animated.tsx` | `<Animated show motion>` — conditional element with animated enter/exit |
+| `MotionPresence.tsx` | `<MotionPresence motion>` — manages enter/exit for children that mount/unmount |
+| `withMotion.ts` | HOC — wraps any component to add a `motion` prop, watches `open` prop or runs on mount |
+| `components.tsx` | Pre-wrapped `MotionModal`, `MotionDrawer`, `MotionToast`, `MotionCard`, etc. |
+| `index.ts` | Single barrel export |
+
+---
+
+#### 16 animation presets
+
+| Preset | Description |
+|--------|-------------|
+| `fade` | Simple opacity fade |
+| `fade-up` | Fade in from below |
+| `fade-down` | Fade in from above |
+| `fade-left` | Fade in from the right |
+| `fade-right` | Fade in from the left |
+| `fade-scale` | Fade + scale from 95% |
+| `slide-up` | Translate from 100% below, no fade |
+| `slide-down` | Translate from 100% above |
+| `slide-left` | Translate from 100% right |
+| `slide-right` | Translate from 100% left |
+| `zoom` | Scale from 50% with fade |
+| `zoom-out` | Scale from 110% with fade |
+| `flip` | 3D Y-axis perspective flip |
+| `flip-x` | 3D X-axis perspective flip |
+| `bounce` | Elastic entrance with spring easing overshoot |
+| `none` | No animation (useful for `prefers-reduced-motion` overrides) |
+
+---
+
+#### `prefers-reduced-motion` — automatic
+
+The engine checks `window.matchMedia("(prefers-reduced-motion: reduce)")` before every animation. When the user has requested reduced motion:
+
+- All keyframe animations are skipped entirely
+- Elements are made immediately visible/hidden instead
+- No JavaScript timing or RAF overhead
+- SSR-safe (returns `false` on the server)
+
+---
+
+#### Pre-wrapped components
+
+Ready-to-use `Motion*` variants of the most common Veloria UI components. Import and use as drop-in replacements — the `motion` prop is the only addition:
+
+```tsx
+import {
+  MotionModal, MotionDrawer, MotionSheet, MotionDialog,
+  MotionPopover, MotionHoverCard,
+  MotionToast, MotionSnackbar, MotionBannerAlert,
+  MotionCard, MotionAlert,
+} from "veloria-ui/motion";
+```
+
+All wrappers are lazy — unused ones are fully tree-shaken from your bundle.
+
+---
+
+#### `<Animated>` — conditional presence
+
+```tsx
+import { Animated } from "veloria-ui/motion";
+
+// Shorthand preset
+<Animated show={isVisible} motion="fade-up">
+  <p>Animates in and out</p>
+</Animated>
+
+// Full config
+<Animated show={isVisible} motion={{ preset: "fade-scale", duration: 300, delay: 100 }}>
+  <Card>Delayed entrance</Card>
+</Animated>
+
+// keepMounted — stays in DOM, just hidden
+<Animated show={isVisible} motion="fade" keepMounted>
+  <ExpensivePanel />
+</Animated>
+```
+
+---
+
+#### `<MotionPresence>` — unmount with exit animation
+
+```tsx
+import { MotionPresence } from "veloria-ui/motion";
+
+<MotionPresence motion="zoom" onExitComplete={() => console.log("gone")}>
+  {isOpen && <Panel key="panel" />}
+</MotionPresence>
+```
+
+The child must have a stable `key` prop. When the child is removed from the tree, `MotionPresence` plays its exit animation before removing it from the DOM.
+
+---
+
+#### `withMotion()` — HOC for your local components
+
+```tsx
+import { withMotion } from "veloria-ui/motion";
+import { Modal } from "@/components/ui/modal";  // your local copy
+
+const MotionModal = withMotion(Modal, { visibleProp: "open" });
+
+<MotionModal motion="fade-scale" open={isOpen} onOpenChange={setOpen} title="Hello" />
+```
+
+`withMotion` watches the `visibleProp` (default `"open"`) and plays enter/exit when it changes. For non-overlay components, pass `{ visibleProp: null }` to animate only on mount.
+
+---
+
+#### `stagger()` — staggered list animations
+
+```tsx
+import { Animated, stagger } from "veloria-ui/motion";
+
+{items.map((item, i) => (
+  <Animated key={item.id} motion={{ preset: "fade-up", delay: stagger(i, 60) }}>
+    <Card>{item.name}</Card>
+  </Animated>
+))}
+// item 0: delay 0ms, item 1: delay 60ms, item 2: delay 120ms…
+```
+
+---
+
+#### `useMotion()` — hook for custom elements
+
+```tsx
+import { useMotion } from "veloria-ui/motion";
+
+function MyPanel({ show }: { show: boolean }) {
+  const { ref, isVisible } = useMotion({
+    show,
+    motion: "slide-up",
+    onExitComplete: () => console.log("exit done"),
+  });
+
+  if (!isVisible) return null;
+
+  return <div ref={ref as React.RefObject<HTMLDivElement>}>Content</div>;
+}
+```
+
+---
+
+#### Imperative API
+
+```tsx
+import { animate, resolveConfig } from "veloria-ui/motion";
+
+// Run an animation directly on a DOM element — no React required
+const config = resolveConfig("slide-up");
+await animate({ el: document.getElementById("my-div")!, config, phase: "enter" });
+```
+
+---
+
+#### `tsup.config.ts` — new motion entry
+
+A dedicated tsup entry `{ motion: "src/motion/index.ts" }` produces `dist/motion.mjs` and `dist/motion.js`. The entry is completely separate from the main bundle so projects that don't use it pay zero cost.
+
+---
+
+#### `package.json` — new `./motion` export
+
+```json
+"./motion": {
+  "types":   "./dist/motion.d.ts",
+  "import":  "./dist/motion.mjs",
+  "require": "./dist/motion.js"
+}
+```
+
+No new `dependencies` or `peerDependencies` added — the motion system has zero runtime dependencies beyond React.
+
+### CLI — Three major UX enhancements
+
+---
+
+#### `veloria-ui add` — Interactive component picker
+
+Running `veloria-ui add` with no component names now launches a full interactive picker instead of printing a usage hint. The picker is a two-step flow built on `prompts` multiselect:
+
+**Step 1 — Category select**
+
+A multiselect showing all 10 categories with a live `installed/total` counter so you can see at a glance which areas of your project already have components:
+
+```
+? Which categories do you want to browse?
+  ❯ ◉ Basic              2/11 installed
+    ◯ Forms              0/14 installed
+    ◉ Feedback           1/16 installed
+    ◯ Data Display       0/22 installed
+```
+
+**Step 2 — Component select per category**
+
+For each chosen category, a multiselect shows every component with:
+- A `✓` prefix on components that are already installed in your project
+- A truncated description so you know what you're selecting
+- A `[+deps]` hint on components that will auto-pull registry dependencies
+
+```
+? Basic components
+  ❯ ✓  button        Solid, outline, ghost, soft, link, classic variants…
+     ◯  badge         Compact label — solid, outline, soft, classic…
+     ◯  avatar-group  Stacked avatars with overflow count  [+deps]
+     ✓  tooltip       Radix tooltip, all four sides…
+```
+
+Already-installed components are pre-ticked but will be skipped (not re-copied) unless `--force` is passed. A summary line at the end tells you exactly which components were skipped and why.
+
+**New `--dry-run` flag for `add`**
+
+Added to both the interactive and direct modes. Shows what files would be written and which npm packages would be installed, without touching anything:
+
+```bash
+npx veloria-ui add button modal --dry-run
+npx veloria-ui add --dry-run   # works with interactive picker too
+```
+
+Output:
+```
+  Dry run — no files written.
+
+  Would copy to: components/ui/
+    button/index.tsx
+    modal/index.tsx
+
+  Would install: @radix-ui/react-slot, @radix-ui/react-dialog, clsx, …
+```
+
+---
+
+#### `veloria-ui remove` — Uninstall components
+
+New command (alias: `rm`) to remove installed components cleanly.
+
+```bash
+npx veloria-ui remove button
+npx veloria-ui remove button card modal
+npx veloria-ui rm avatar-group   # alias
+```
+
+**Dependent check** — before removing, the CLI scans your other installed components for `registryDeps` entries that point to what you are about to remove. If any are found, it warns you:
+
+```
+  ⚠  The following installed components depend on what you're removing:
+
+    avatar-group  →  depends on  avatar
+    command-palette  →  depends on  command-dialog
+
+  Remove anyway? (dependents may break)  › No
+```
+
+Pass `--force` to skip the warning and remove unconditionally.
+
+**File preview** — shows exactly which files and directories will be deleted before asking for confirmation:
+
+```
+  Files to be removed:
+    components/ui/button/index.tsx
+    components/ui/button/  (directory)
+```
+
+**Lock cleanup** — removes the component entry from `veloria.lock.json` automatically, keeping your lock file accurate.
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `<components...>` | One or more component names to remove |
+| `-y, --yes` | Skip confirmation prompt |
+| `--force` | Remove even if other components depend on it |
+
+```bash
+# Remove a single component
+npx veloria-ui remove button
+
+# Remove multiple at once
+npx veloria-ui remove button card modal
+
+# Remove without confirmation
+npx veloria-ui remove skeleton --yes
+
+# Remove even if dependents exist
+npx veloria-ui remove avatar --force
+```
+
+---
+
+#### `add` — Dependency graph display
+
+Every `veloria-ui add` invocation (interactive or direct) now prints a structured dependency tree before the confirmation prompt. The tree shows:
+
+- Which components you explicitly selected
+- Which components are being auto-pulled via `registryDeps` (shown in yellow with an `(auto — registry dep)` label)
+- Which npm packages will be installed as peer dependencies
+
+```
+  Adding 3 components (2 selected + 1 auto)
+
+  ├── command-bar
+  │   └── command-dialog  (auto — registry dep)
+  └── avatar-group
+      └── avatar  (auto — registry dep)
+
+  npm peer deps
+  ├── cmdk
+  ├── @radix-ui/react-dialog
+  └── @radix-ui/react-avatar
+```
+
+For components with no registry deps or npm deps, the output is minimal:
+
+```
+  Adding 1 component
+
+  └── button
+
+  npm peer deps
+  ├── @radix-ui/react-slot
+  ├── class-variance-authority
+  ├── clsx
+  └── tailwind-merge
+```
+
+This replaces the previous flat `Peer deps: …` line and makes the install plan fully transparent before anything is written to disk.
+
+---
+
+### Bug Fixes
+
+- `add` with `--force` on a component that pulls `registryDeps` now correctly overwrites the dep files too, not only the top-level component.
+- `upgrade` hint at the bottom of `list` now correctly says `npx veloria-ui add` (not `add <n>`) to reflect the new interactive mode.
+
+### React Hook Form Adapter — `veloria-ui/rhf`
+
+A new optional sub-path export that provides zero-boilerplate `Controller` wrappers for every Veloria UI form component. Import from `veloria-ui/rhf` — requires `react-hook-form ^7.0.0` as an optional peer dependency.
+
+**11 wrappers shipped:**
+
+| Wrapper | Wraps | Notes |
+|---------|-------|-------|
+| `RhfInput` | `Input` + `FormField` | All `InputProps` forwarded (size, leftElement, rightElement…) |
+| `RhfTextArea` | `TextArea` + `FormField` | Full resize/rows control |
+| `RhfSelect` | Radix `Select` + `FormField` | `onValueChange` bridged to `field.onChange` |
+| `RhfCheckbox` | `Checkbox` + `FormField` | Boolean field — `checked` ↔ `field.value` |
+| `RhfSwitch` | `Switch` + `FormField` | Same boolean mapping as `RhfCheckbox` |
+| `RhfRadioGroup` | `RadioGroup` + `FormField` | `onValueChange` → `field.onChange` |
+| `RhfSlider` | `Slider` + `FormField` | Stores plain `number`, converts to `number[]` internally |
+| `RhfCombobox` | `Combobox` + `FormField` | `onChange` bridged to `field.onChange` |
+| `RhfMultiSelect` | `MultiSelect` + `FormField` | Field value is `string[]` |
+| `RhfRatingInput` | `RatingInput` + `FormField` | Numeric value |
+| `RhfOTPInput` | `OTPInput` + `FormField` | String value |
+
+Every wrapper automatically maps `fieldState.error` to the component's `invalid` prop and renders `<FormError>` with the message. All original visual props (`size`, `placeholder`, `disabled`, `label`, etc.) pass straight through — no new API surface to learn.
+
+**Usage:**
+
+```tsx
+import { useForm } from "react-hook-form";
+import { RhfInput, RhfSelect, RhfCheckbox } from "veloria-ui/rhf";
+
+const { control, handleSubmit } = useForm<{ email: string; role: string; agree: boolean }>();
+
+<form onSubmit={handleSubmit(onSubmit)}>
+  <RhfInput    name="email"  control={control} label="Email" type="email" />
+  <RhfSelect   name="role"   control={control} label="Role"  options={roles} />
+  <RhfCheckbox name="agree"  control={control} label="I agree to the terms" />
+</form>
+```
+
+### Build
+
+- `veloria-ui/rhf` entry added to `exports` map in `package.json`
+- New tsup build target for `src/rhf/index.ts` (CJS + ESM + DTS)
+- `react-hook-form` added to `sharedExternal` — never bundled
+- `veloria-ui` itself added to `sharedExternal` — prevents self-resolution error during the RHF build pass
+- All `Rhf*.tsx` files import from `../index` (relative source path) rather than `"veloria-ui"` package name — eliminates circular resolve during build
+
+### Infrastructure
+
+- `.npmrc` added with `public-hoist-pattern[]=tsup` and `public-hoist-pattern[]=typescript` so `pnpm install` always hoists build tool binaries to `node_modules/.bin` — fixes `tsup: not found` on Replit and similar isolated-store environments
+- `react-hook-form ^7.0.0` added as optional peer dependency
+
+### New Components (5)
+
+**`DataGrid`** (`data-display`)
+A spreadsheet-grade table built entirely without external grid libraries. Implements row virtualisation with a configurable overscan so 100k-row datasets render at 60fps. Columns are resizable by dragging the right edge of any header. Cells are editable on double-click with Tab-to-next-cell navigation and Enter/Escape to commit/cancel. Supports multi-column sorting (click header to cycle asc/desc), row selection via a `selectedRows` Set, right-click-to-copy on any cell, a `render` slot per column for custom cell content, and animated skeleton loading rows. Zero external dependencies beyond React.
+
+```tsx
+<DataGrid
+  columns={[
+    { key: "name",  header: "Name",   sortable: true,  editable: true, width: 200 },
+    { key: "email", header: "Email",  sortable: true,  width: 260 },
+    { key: "role",  header: "Role",   editable: true },
+    { key: "status", header: "Status", render: (v) => <Badge>{String(v)}</Badge> },
+  ]}
+  rows={users}
+  height={480}
+  onChange={setUsers}
+  selectedRows={selected}
+  onRowSelect={setSelected}
+/>
+```
+
+**`RichTextEditor`** (`advanced-forms`)
+A Tiptap-based editor styled to match the design system. Toolbar covers headings (H1–H3), bold, italic, underline, strikethrough, inline code, text alignment (left/center/right), bullet list, ordered list, blockquote, code block with syntax highlighting via `lowlight`, link, undo/redo. A `BubbleMenu` appears on text selection for quick bold/italic/link access. Controlled via `value`/`onChange` (HTML string). Supports `minHeight`, `maxHeight` (scrollable), `disabled`, `placeholder`, and `autofocus`. All toolbar icons are inline SVG — no icon library dependency.
+
+```tsx
+<RichTextEditor
+  value={html}
+  onChange={setHtml}
+  placeholder="Write something…"
+  minHeight={300}
+/>
+```
+
+**`DateRangePicker`** (`forms`)
+A full custom two-calendar date range popover — not a wrapper around a native `<input type="date">`. Renders two side-by-side month grids (configurable to one with `numberOfMonths={1}`). Selection is two-click: first click sets the anchor, second sets the end. Hover preview shows the in-range highlight as you move the cursor. Edge days (from/to) get a filled primary circle; in-range days get a tinted background strip with squared-off edges connecting to the edge circles. Supports `minDate`, `maxDate`, a `disabledDates` predicate, and a `format` override for the trigger label. Clear button appears once a range is set.
+
+```tsx
+<DateRangePicker
+  value={range}
+  onChange={setRange}
+  numberOfMonths={2}
+  placeholder="Select date range"
+/>
+```
+
+**`CommandBar`** (`overlay`)
+A persistent ⌘K command bar in the style of Linear/Vercel. Renders as a floating dialog at 20% from the top. Registers `Cmd+K` / `Ctrl+K` globally via a `useCommandBar` hook that can also be called standalone. Actions are grouped, searchable by label/description/keywords, and can carry keyboard shortcut hints rendered as `<kbd>` chips. The empty-state query shows recent actions (passed as `recentIds`). Built on cmdk + Radix Dialog. Footer row shows ↑↓ navigate, ↵ select, ⌘K to open.
+
+```tsx
+<CommandBar
+  actions={actions}
+  recentIds={recentActionIds}
+  open={open}
+  onOpenChange={setOpen}
+/>
+```
+
+**`MultiStepForm`** (`advanced-forms`)
+A compound component that wires Stepper + form state + per-step async validation + animated slide transitions into a single coherent API. Each step definition can include a `validate` function returning an error map; the nav button won't advance until it resolves cleanly. Shared form data accumulates across steps and is handed to `onComplete` at the end. The `useMultiStepForm` hook exposes `setField`, `setError`, `clearError`, `next`, `back`, `goTo`, and `progress` to any child. The stepper renders in two layouts: `"top"` (horizontal with connector lines) and `"left"` (vertical sidebar). Completed steps are clickable to jump back. `MultiStepFormNav` renders the Back/Continue buttons with a progress bar above them.
+
+```tsx
+<MultiStepForm steps={steps} onComplete={handleSubmit} stepperPosition="top">
+  <MultiStepFormStepPanel>
+    <AccountFields />
+  </MultiStepFormStepPanel>
+  <MultiStepFormStepPanel>
+    <ProfileFields />
+  </MultiStepFormStepPanel>
+  <MultiStepFormStepPanel>
+    <ReviewStep />
+  </MultiStepFormStepPanel>
+  <MultiStepFormNav />
+</MultiStepForm>
+```
+
+### Registry
+
+Five new entries added to `src/cli/registry.ts` under `// ── v0.1.7 additions`. See `registry-additions.ts` for the exact entries to splice in.
+
+### Dependencies added (peer, optional per component)
+
+| Component | New deps |
+|-----------|----------|
+| `RichTextEditor` | `@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/extension-placeholder`, `@tiptap/extension-link`, `@tiptap/extension-underline`, `@tiptap/extension-text-align`, `@tiptap/extension-code-block-lowlight`, `lowlight` |
+| `DateRangePicker` | `@radix-ui/react-popover` (already peer dep) |
+| `CommandBar` | `cmdk`, `@radix-ui/react-dialog` (already peer deps) |
+| `DataGrid` | none |
+| `MultiStepForm` | none |
+
+---
+
+## [0.1.4] — 2026-03-17
+
+### CLI
+
+#### `veloria-ui upgrade` — new command
+
+Reads `veloria.config.json`, discovers every component you have installed, checks each one against the latest upstream source on GitHub, and prompts you to upgrade those that have changed. Modelled on `npm outdated` but for copied source files — the first component library to ship this natively.
+
+**Discovery** — scans your components directory for sub-folders matching registry names, then cross-references `veloria.lock.json` to catch any components stored at non-standard paths. No manual component list needed.
+
+**Three-state staleness model** powered by `veloria.lock.json` (written/updated by `add` and `upgrade`):
+
+| State | Meaning |
+|-------|---------|
+| `up-to-date` | Upstream hash matches the hash recorded at install time |
+| `upstream-changed` | Upstream changed since install, but your local file is unmodified — safe to auto-upgrade |
+| `diverged` | Both upstream and your local file have changed — warned before overwriting |
+| `no-lock` | Component pre-dates the lock file; falls back to raw content comparison |
+
+**Interactive prompt per outdated component** — shows `+N -N` change counts and offers three choices: upgrade, show full diff first (then decide), or skip.
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `[component]` | Upgrade a single named component |
+| `-y, --yes` / `--all` | Upgrade all outdated non-interactively (skips diverged unless `--force`) |
+| `--check` | Dry-run — report status only, make no changes |
+| `--force` | Overwrite even diverged (locally modified) components |
+| `--json` | Machine-readable JSON status report |
+
+```bash
+# Check what's outdated (no changes)
+npx veloria-ui upgrade --check
+
+# Interactive upgrade — prompts per component
+npx veloria-ui upgrade
+
+# Upgrade a single component
+npx veloria-ui upgrade button
+
+# Upgrade everything non-interactively
+npx veloria-ui upgrade --all
+
+# CI status report
+npx veloria-ui upgrade --check --json
+```
+
+**`veloria.lock.json`** — new file written by `add` and updated by `upgrade`. Records the SHA-256 of each component's upstream source at install time, the upstream URL, and timestamps. Commit this file — it's what makes three-state upgrade detection possible.
+
+#### `add` — updated
+
+- Now fetches and writes real upstream source (not stubs) when GitHub is reachable.
+- Records the upstream content hash and URL in `veloria.lock.json` at add time.
+- Added `--force` flag to overwrite existing local files.
+
+#### `diff` — updated
+
+- The "To update" hint at the end of diff output now points to `npx veloria-ui upgrade <component>` instead of `add --force`.
+
+---
+
+## [0.1.4] — 2026-03-17
+
+### CLI
+
+#### `veloria-ui diff <component>` — now fully implemented
+
+Previously this command printed a "not implemented yet" warning. It is now a fully working line-by-line diff engine:
+
+- **Fetches upstream source** directly from the GitHub raw API (`raw.githubusercontent.com`) — no npm registry round-trip needed.
+- **Locates your local copy** automatically by reading `veloria.config.json` (falls back to `components/ui/<n>/index.tsx` and several other candidate paths).
+- **Myers diff algorithm** — the same LCS-based algorithm used by Git. Produces the minimal edit set between your local file and the upstream source.
+- **Unified-style terminal output** — colour-coded hunks (`+` in green, `-` in red) with configurable context lines, summary counts, and `···` separators between hunks.
+- **`--json` flag** — machine-readable JSON output containing the full diff array and summary, suitable for CI pipelines or editor integrations.
+- **`--context <n>` flag** — control how many context lines appear around each change (default: 3).
+- **Graceful error handling** — clear messages when the component is not found locally (with an `add` hint), when the upstream fetch fails (with the checked URLs listed), or when the component name is unknown.
+- **Multi-path resolution** — tries both a dedicated `<Component>.tsx` file and the category `index.tsx` to handle components that are co-located with siblings.
+
+```bash
+# Basic usage
+npx veloria-ui diff button
+
+# More context around changes
+npx veloria-ui diff modal --context 6
+
+# CI-friendly JSON output
+npx veloria-ui diff input --json
+```
+
+---
+
 ## [0.1.3] — 2026-03-16 (Edited)
 
 ### Branding & Naming