Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add countries endpoint, category_ids support, and product tests
Damian Legawiec669133ca02a0
diff --git a/.agents/skills/shadcn/SKILL.md b/.agents/skills/shadcn/SKILL.mdnew file mode 100644index 0000000000..1351394fbe--- /dev/null+++ b/.agents/skills/shadcn/SKILL.md@@ -0,0 +1,246 @@+---+name: shadcn+description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".+user-invocable: false+allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)+---++# shadcn/ui++A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.++> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.++## Current Project Context++```json+!`npx shadcn@latest info --json`+```++The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.++## Principles++1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too.+2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.+3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.+4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.++## Critical Rules++These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.++### Styling & Tailwind → [styling.md](./rules/styling.md)++- **`className` for layout, not styling.** Never override component colors or typography.+- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.+- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.+- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.+- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).+- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.+- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.++### Forms & Inputs → [forms.md](./rules/forms.md)++- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.+- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.+- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**+- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.+- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.+- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.++### Component Structure → [composition.md](./rules/composition.md)++- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.+- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md)+- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden.+- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.+- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.+- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.+- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.++### Use Components, Not Custom Markup → [composition.md](./rules/composition.md)++- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.+- **Callouts use `Alert`.** Don't build custom styled divs.+- **Empty states use `Empty`.** Don't build custom empty state markup.+- **Toast via `sonner`.** Use `toast()` from `sonner`.+- **Use `Separator`** instead of `<hr>` or `<div className="border-t">`.+- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.+- **Use `Badge`** instead of custom styled spans.++### Icons → [icons.md](./rules/icons.md)++- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.+- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.+- **Pass icons as objects, not string keys.** `icon={CheckIcon}`, not a string lookup.++### CLI++- **Never decode or fetch preset codes manually.** Pass them directly to `npx shadcn@latest apply --preset <code>` for existing projects, or `npx shadcn@latest init --preset <code>` when initializing.++## Key Patterns++These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.++```tsx+// Form layout: FieldGroup + Field, not div + Label.+<FieldGroup>+ <Field>+ <FieldLabel htmlFor="email">Email</FieldLabel>+ <Input id="email" />+ </Field>+</FieldGroup>++// Validation: data-invalid on Field, aria-invalid on the control.+<Field data-invalid>+ <FieldLabel>Email</FieldLabel>+ <Input aria-invalid />+ <FieldDescription>Invalid email.</FieldDescription>+</Field>++// Icons in buttons: data-icon, no sizing classes.+<Button>+ <SearchIcon data-icon="inline-start" />+ Search+</Button>++// Spacing: gap-*, not space-y-*.+<div className="flex flex-col gap-4"> // correct+<div className="space-y-4"> // wrong++// Equal dimensions: size-*, not w-* h-*.+<Avatar className="size-10"> // correct+<Avatar className="w-10 h-10"> // wrong++// Status colors: Badge variants or semantic tokens, not raw colors.+<Badge variant="secondary">+20.1%</Badge> // correct+<span className="text-emerald-600">+20.1%</span> // wrong+```++## Component Selection++| Need | Use |+| -------------------------- | --------------------------------------------------------------------------------------------------- |+| Button/action | `Button` with appropriate variant |+| Form inputs | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |+| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem` |+| Data display | `Table`, `Card`, `Badge`, `Avatar` |+| Navigation | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination` |+| Overlays | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation) |+| Feedback | `sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner` |+| Command palette | `Command` inside `Dialog` |+| Charts | `Chart` (wraps Recharts) |+| Layout | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible` |+| Empty states | `Empty` |+| Menus | `DropdownMenu`, `ContextMenu`, `Menubar` |+| Tooltips/info | `Tooltip`, `HoverCard`, `Popover` |++## Key Fields++The injected project context contains these key fields:++- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode.+- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top of the file. Always reference this field when advising on the directive.+- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`.+- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.+- **`style`** → component visual treatment (e.g. `nova`, `vega`).+- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props.+- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`.+- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc.+- **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA).+- **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).++See [cli.md — `info` command](./cli.md) for the full field reference.++## Component Docs, Examples, and Usage++Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.++```bash+npx shadcn@latest docs button dialog select+```++**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.++## Workflow++1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.+2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.+3. **Find components** — `npx shadcn@latest search`.+4. **Get docs and examples** — run `npx shadcn@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`.+5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).+6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.+7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.+8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, etc.), ask which registry to use. Never default to a registry on behalf of the user.+9. **Switching presets** — Ask the user first: **overwrite**, **merge**, or **skip**?+ - **Overwrite**: `npx shadcn@latest apply --preset <code>`. Overwrites detected components, fonts, and CSS variables.+ - **Merge**: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.+ - **Skip**: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.+ - **Important**: Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.++## Updating Components++When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**++1. Run `npx shadcn@latest add <component> --dry-run` to see all files that would be affected.+2. For each file, run `npx shadcn@latest add <component> --diff <file>` to see what changed upstream vs local.+3. Decide per file based on the diff:+ - No local changes → safe to overwrite.+ - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.+ - User says "just update everything" → use `--overwrite`, but confirm first.+4. **Never use `--overwrite` without the user's explicit approval.**++## Quick Reference++```bash+# Create a new project.+npx shadcn@latest init --name my-app --preset base-nova+npx shadcn@latest init --name my-app --preset a2r6bw --template vite++# Create a monorepo project.+npx shadcn@latest init --name my-app --preset base-nova --monorepo+npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo++# Initialize existing project.+npx shadcn@latest init --preset base-nova+npx shadcn@latest init --defaults # shortcut: --template=next --preset=nova (base style implied)++# Apply a preset to an existing project.+npx shadcn@latest apply --preset a2r6bw+npx shadcn@latest apply a2r6bw++# Add components.+npx shadcn@latest add button card dialog+npx shadcn@latest add @magicui/shimmer-button+npx shadcn@latest add --all++# Preview changes before adding/updating.+npx shadcn@latest add button --dry-run+npx shadcn@latest add button --diff button.tsx+npx shadcn@latest add @acme/form --view button.tsx++# Search registries.+npx shadcn@latest search @shadcn -q "sidebar"+npx shadcn@latest search @tailark -q "stats"++# Get component docs and example URLs.+npx shadcn@latest docs button dialog select++# View registry item details (for items not yet installed).+npx shadcn@latest view @shadcn/button+```++**Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`+**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo)+**Preset codes:** Version-prefixed base62 strings (e.g. `a2r6bw` or `b0`), from [ui.shadcn.com](https://ui.shadcn.com).++## Detailed References++- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states+- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading+- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, passing icons as objects+- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index+- [rules/base-vs-radix.md](./rules/base-vs-radix.md) — asChild vs render, Select, ToggleGroup, Slider, Accordion+- [cli.md](./cli.md) — Commands, flags, presets, templates+- [customization.md](./customization.md) — Theming, CSS variables, extending componentsdiff --git a/.agents/skills/shadcn/agents/openai.yml b/.agents/skills/shadcn/agents/openai.ymlnew file mode 100644index 0000000000..ab636da86b--- /dev/null+++ b/.agents/skills/shadcn/agents/openai.yml@@ -0,0 +1,5 @@+interface:+ display_name: "shadcn/ui"+ short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI."+ icon_small: "./assets/shadcn-small.png"+ icon_large: "./assets/shadcn.png"diff --git a/.agents/skills/shadcn/assets/shadcn-small.png b/.agents/skills/shadcn/assets/shadcn-small.pngnew file mode 100644index 0000000000..547154b97fBinary files /dev/null and b/.agents/skills/shadcn/assets/shadcn-small.png differdiff --git a/.agents/skills/shadcn/assets/shadcn.png b/.agents/skills/shadcn/assets/shadcn.pngnew file mode 100644index 0000000000..b7b6814accBinary files /dev/null and b/.agents/skills/shadcn/assets/shadcn.png differdiff --git a/.agents/skills/shadcn/cli.md b/.agents/skills/shadcn/cli.mdnew file mode 100644index 0000000000..c3a0f0aa74--- /dev/null+++ b/.agents/skills/shadcn/cli.md@@ -0,0 +1,276 @@+# shadcn CLI Reference++Configuration is read from `components.json`.++> **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Check `packageManager` from project context to choose the right one. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.++> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist. The CLI auto-detects the package manager from the project's lockfile; there is no `--package-manager` flag.++## Contents++- Commands: init, apply, add (dry-run, smart merge), search, view, docs, info, build+- Templates: next, vite, start, react-router, astro+- Presets: named, code, URL formats and fields+- Switching presets++---++## Commands++### `init` — Initialize or create a project++```bash+npx shadcn@latest init [components...] [options]+```++Initializes shadcn/ui in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step.++| Flag | Short | Description | Default |+| ----------------------- | ----- | --------------------------------------------------------- | ------- |+| `--template <template>` | `-t` | Template (next, start, vite, next-monorepo, react-router) | — |+| `--preset [name]` | `-p` | Preset configuration (named, code, or URL) | — |+| `--yes` | `-y` | Skip confirmation prompt | `true` |+| `--defaults` | `-d` | Use defaults (`--template=next --preset=base-nova`) | `false` |+| `--force` | `-f` | Force overwrite existing configuration | `false` |+| `--cwd <cwd>` | `-c` | Working directory | current |+| `--name <name>` | `-n` | Name for new project | — |+| `--silent` | `-s` | Mute output | `false` |+| `--rtl` | | Enable RTL support | — |+| `--reinstall` | | Re-install existing UI components | `false` |+| `--monorepo` | | Scaffold a monorepo project | — |+| `--no-monorepo` | | Skip the monorepo prompt | — |++`npx shadcn@latest create` is an alias for `npx shadcn@latest init`.++### `apply` — Apply a preset to an existing project++```bash+npx shadcn@latest apply [preset] [options]+```++Applies a preset to an existing project, overwriting preset-driven config, fonts, CSS variables, and detected UI components.++| Flag | Short | Description | Default |+| ------------------- | ----- | ------------------------------------------ | ------- |+| `--preset <preset>` | — | Preset configuration (named, code, or URL) | — |+| `--yes` | `-y` | Skip confirmation prompt | `false` |+| `--cwd <cwd>` | `-c` | Working directory | current |+| `--silent` | `-s` | Mute output | `false` |++`[preset]` is a shorthand for `--preset <preset>`. If both are provided, they must match.+If no preset is provided, the CLI offers to open the custom preset builder on `ui.shadcn.com/create`.++### `add` — Add components++> **IMPORTANT:** To compare local components against upstream or to preview changes, ALWAYS use `npx shadcn@latest add <component> --dry-run`, `--diff`, or `--view`. NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically.++```bash+npx shadcn@latest add [components...] [options]+```++Accepts component names, registry-prefixed names (`@magicui/shimmer-button`), URLs, or local paths.++| Flag | Short | Description | Default |+| --------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | ------- |+| `--yes` | `-y` | Skip confirmation prompt | `false` |+| `--overwrite` | `-o` | Overwrite existing files | `false` |+| `--cwd <cwd>` | `-c` | Working directory | current |+| `--all` | `-a` | Add all available components | `false` |+| `--path <path>` | `-p` | Target path for the component | — |+| `--silent` | `-s` | Mute output | `false` |+| `--dry-run` | | Preview all changes without writing files | `false` |+| `--diff [path]` | | Show diffs. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | — |+| `--view [path]` | | Show file contents. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | — |++#### Dry-Run Mode++Use `--dry-run` to preview what `add` would do without writing any files. `--diff` and `--view` both imply `--dry-run`.++```bash+# Preview all changes.+npx shadcn@latest add button --dry-run++# Show diffs for all files (top 5).+npx shadcn@latest add button --diff++# Show the diff for a specific file.+npx shadcn@latest add button --diff button.tsx++# Show contents for all files (top 5).+npx shadcn@latest add button --view++# Show the full content of a specific file.+npx shadcn@latest add button --view button.tsx++# Works with URLs too.+npx shadcn@latest add https://api.npoint.io/abc123 --dry-run++# CSS diffs.+npx shadcn@latest add button --diff globals.css+```++**When to use dry-run:**++- When the user asks "what files will this add?" or "what will this change?" — use `--dry-run`.+- Before overwriting existing components — use `--diff` to preview the changes first.+- When the user wants to inspect component source code without installing — use `--view`.+- When checking what CSS changes would be made to `globals.css` — use `--diff globals.css`.+- When the user asks to review or audit third-party registry code before installing — use `--view` to inspect the source.++> **`npx shadcn@latest add --dry-run` vs `npx shadcn@latest view`:** Prefer `npx shadcn@latest add --dry-run/--diff/--view` over `npx shadcn@latest view` when the user wants to preview changes to their project. `npx shadcn@latest view` only shows raw registry metadata. `npx shadcn@latest add --dry-run` shows exactly what would happen in the user's project: resolved file paths, diffs against existing files, and CSS updates. Use `npx shadcn@latest view` only when the user wants to browse registry info without a project context.++#### Smart Merge from Upstream++See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.++### `search` — Search registries++```bash+npx shadcn@latest search <registries...> [options]+```++Fuzzy search across registries. Also aliased as `npx shadcn@latest list`. Without `-q`, lists all items.++| Flag | Short | Description | Default |+| ------------------- | ----- | ---------------------- | ------- |+| `--query <query>` | `-q` | Search query | — |+| `--limit <number>` | `-l` | Max items per registry | `100` |+| `--offset <number>` | `-o` | Items to skip | `0` |+| `--cwd <cwd>` | `-c` | Working directory | current |++### `view` — View item details++```bash+npx shadcn@latest view <items...> [options]+```++Displays item info including file contents. Example: `npx shadcn@latest view @shadcn/button`.++### `docs` — Get component documentation URLs++```bash+npx shadcn@latest docs <components...> [options]+```++Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content.++Example output for `npx shadcn@latest docs input button`:++```+base radix++input+ docs https://ui.shadcn.com/docs/components/radix/input+ examples https://raw.githubusercontent.com/.../examples/input-example.tsx++button+ docs https://ui.shadcn.com/docs/components/radix/button+ examples https://raw.githubusercontent.com/.../examples/button-example.tsx+```++Some components include an `api` link to the underlying library (e.g. `cmdk` for the command component).++### `diff` — Check for updates++Do not use this command. Use `npx shadcn@latest add --diff` instead.++### `info` — Project information++```bash+npx shadcn@latest info [options]+```++Displays project info and `components.json` configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths.++| Flag | Short | Description | Default |+| ------------- | ----- | ----------------- | ------- |+| `--cwd <cwd>` | `-c` | Working directory | current |++**Project Info fields:**++| Field | Type | Meaning |+| -------------------- | --------- | ------------------------------------------------------------------ |+| `framework` | `string` | Detected framework (`next`, `vite`, `react-router`, `start`, etc.) |+| `frameworkVersion` | `string` | Framework version (e.g. `15.2.4`) |+| `isSrcDir` | `boolean` | Whether the project uses a `src/` directory |+| `isRSC` | `boolean` | Whether React Server Components are enabled |+| `isTsx` | `boolean` | Whether the project uses TypeScript |+| `tailwindVersion` | `string` | `"v3"` or `"v4"` |+| `tailwindConfigFile` | `string` | Path to the Tailwind config file |+| `tailwindCssFile` | `string` | Path to the global CSS file |+| `aliasPrefix` | `string` | Import alias prefix (e.g. `@`, `~`, `@/`) |+| `packageManager` | `string` | Detected package manager (`npm`, `pnpm`, `yarn`, `bun`) |++**Components.json fields:**++| Field | Type | Meaning |+| -------------------- | --------- | ------------------------------------------------------------------------------------------ |+| `base` | `string` | Primitive library (`radix` or `base`) — determines component APIs and available props |+| `style` | `string` | Visual style (e.g. `nova`, `vega`) |+| `rsc` | `boolean` | RSC flag from config |+| `tsx` | `boolean` | TypeScript flag |+| `tailwind.config` | `string` | Tailwind config path |+| `tailwind.css` | `string` | Global CSS path — this is where custom CSS variables go |+| `iconLibrary` | `string` | Icon library — determines icon import package (e.g. `lucide-react`, `@tabler/icons-react`) |+| `aliases.components` | `string` | Component import alias (e.g. `@/components`) |+| `aliases.utils` | `string` | Utils import alias (e.g. `@/lib/utils`) |+| `aliases.ui` | `string` | UI component alias (e.g. `@/components/ui`) |+| `aliases.lib` | `string` | Lib alias (e.g. `@/lib`) |+| `aliases.hooks` | `string` | Hooks alias (e.g. `@/hooks`) |+| `resolvedPaths` | `object` | Absolute file-system paths for each alias |+| `registries` | `object` | Configured custom registries |++**Links fields:**++The `info` output includes a **Links** section with templated URLs for component docs, source, and examples. For resolved URLs, use `npx shadcn@latest docs <component>` instead.++### `build` — Build a custom registry++```bash+npx shadcn@latest build [registry] [options]+```++Builds `registry.json` into individual JSON files for distribution. Default input: `./registry.json`, default output: `./public/r`.++| Flag | Short | Description | Default |+| ----------------- | ----- | ----------------- | ------------ |+| `--output <path>` | `-o` | Output directory | `./public/r` |+| `--cwd <cwd>` | `-c` | Working directory | current |++---++## Templates++| Value | Framework | Monorepo support |+| -------------- | -------------- | ---------------- |+| `next` | Next.js | Yes |+| `vite` | Vite | Yes |+| `start` | TanStack Start | Yes |+| `react-router` | React Router | Yes |+| `astro` | Astro | Yes |+| `laravel` | Laravel | No |++All templates support monorepo scaffolding via the `--monorepo` flag. When passed, the CLI uses a monorepo-specific template directory (e.g. `next-monorepo`, `vite-monorepo`). When neither `--monorepo` nor `--no-monorepo` is passed, the CLI prompts interactively. Laravel does not support monorepo scaffolding.++---++## Presets++Three ways to specify a preset via `--preset`:++1. **Named:** `--preset nova` or `--preset lyra`+2. **Code:** `--preset a2r6bw` (version-prefixed base62 string, e.g. `a2r6bw` or `b0`)+3. **URL:** `--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."`++> **IMPORTANT:** Never try to decode, fetch, or resolve preset codes manually. Preset codes are opaque — pass them directly to `npx shadcn@latest init --preset <code>` and let the CLI handle resolution.+> Use `npx shadcn@latest apply --preset <code>` when overwriting an existing project's preset.++## Switching Presets++Ask the user first: **overwrite**, **merge**, or **skip** existing components?++- **Overwrite / Re-install** → `npx shadcn@latest apply --preset <code>`. Overwrites all detected component files with the new preset styles. Use when the user hasn't customized components.+- **Merge** → `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to get the list of installed components and use the [smart merge workflow](./SKILL.md#updating-components) to update them one by one, preserving local changes. Use when the user has customized components.+- **Skip** → `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS variables, leaves existing components as-is.++Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.diff --git a/.agents/skills/shadcn/customization.md b/.agents/skills/shadcn/customization.mdnew file mode 100644index 0000000000..16954f56b1--- /dev/null+++ b/.agents/skills/shadcn/customization.md@@ -0,0 +1,209 @@+# Customization & Theming++Components reference semantic CSS variable tokens. Change the variables to change every component.++## Contents++- How it works (CSS variables → Tailwind utilities → components)+- Color variables and OKLCH format+- Dark mode setup+- Changing the theme (presets, CSS variables)+- Adding custom colors (Tailwind v3 and v4)+- Border radius+- Customizing components (variants, className, wrappers)+- Checking for updates++---++## How It Works++1. CSS variables defined in `:root` (light) and `.dark` (dark mode).+2. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.+3. Components use these utilities — changing a variable changes all components that reference it.++---++## Color Variables++Every color follows the `name` / `name-foreground` convention. The base variable is for backgrounds, `-foreground` is for text/icons on that background.++| Variable | Purpose |+| -------------------------------------------- | -------------------------------- |+| `--background` / `--foreground` | Page background and default text |+| `--card` / `--card-foreground` | Card surfaces |+| `--primary` / `--primary-foreground` | Primary buttons and actions |+| `--secondary` / `--secondary-foreground` | Secondary actions |+| `--muted` / `--muted-foreground` | Muted/disabled states |+| `--accent` / `--accent-foreground` | Hover and accent states |+| `--destructive` / `--destructive-foreground` | Error and destructive actions |+| `--border` | Default border color |+| `--input` | Form input borders |+| `--ring` | Focus ring color |+| `--chart-1` through `--chart-5` | Chart/data visualization |+| `--sidebar-*` | Sidebar-specific colors |+| `--surface` / `--surface-foreground` | Secondary surface |++Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).++---++## Dark Mode++Class-based toggle via `.dark` on the root element. In Next.js, use `next-themes`:++```tsx+import { ThemeProvider } from "next-themes"++<ThemeProvider attribute="class" defaultTheme="system" enableSystem>+ {children}+</ThemeProvider>+```++---++## Changing the Theme++```bash+# Apply a preset code from ui.shadcn.com.+npx shadcn@latest apply --preset a2r6bw++# Positional shorthand also works.+npx shadcn@latest apply a2r6bw++# Switch to a named preset and overwrite existing components.+npx shadcn@latest apply --preset nova++# Preserve existing components instead.+npx shadcn@latest init --preset nova --force --no-reinstall++# Use a custom theme URL.+npx shadcn@latest apply --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&..."+```++Or edit CSS variables directly in `globals.css`.++---++## Adding Custom Colors++Add variables to the file at `tailwindCssFile` from `npx shadcn@latest info` (typically `globals.css`). Never create a new CSS file for this.++```css+/* 1. Define in the global CSS file. */+:root {+ --warning: oklch(0.84 0.16 84);+ --warning-foreground: oklch(0.28 0.07 46);+}+.dark {+ --warning: oklch(0.41 0.11 46);+ --warning-foreground: oklch(0.99 0.02 95);+}+```++```css+/* 2a. Register with Tailwind v4 (@theme inline). */+@theme inline {+ --color-warning: var(--warning);+ --color-warning-foreground: var(--warning-foreground);+}+```++When `tailwindVersion` is `"v3"` (check via `npx shadcn@latest info`), register in `tailwind.config.js` instead:++```js+// 2b. Register with Tailwind v3 (tailwind.config.js).+module.exports = {+ theme: {+ extend: {+ colors: {+ warning: "oklch(var(--warning) / <alpha-value>)",+ "warning-foreground":+ "oklch(var(--warning-foreground) / <alpha-value>)",+ },+ },+ },+}+```++```tsx+// 3. Use in components.+<div className="bg-warning text-warning-foreground">Warning</div>+```++---++## Border Radius++`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `var(--radius)`, `rounded-md` = `calc(var(--radius) - 2px)`).++---++## Customizing Components++See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.++Prefer these approaches in order:++### 1. Built-in variants++```tsx+<Button variant="outline" size="sm">+ Click+</Button>+```++### 2. Tailwind classes via `className`++```tsx+<Card className="mx-auto max-w-md">...</Card>+```++### 3. Add a new variant++Edit the component source to add a variant via `cva`:++```tsx+// components/ui/button.tsx+warning: "bg-warning text-warning-foreground hover:bg-warning/90",+```++### 4. Wrapper components++Compose shadcn/ui primitives into higher-level components:++```tsx+export function ConfirmDialog({ title, description, onConfirm, children }) {+ return (+ <AlertDialog>+ <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>+ <AlertDialogContent>+ <AlertDialogHeader>+ <AlertDialogTitle>{title}</AlertDialogTitle>+ <AlertDialogDescription>{description}</AlertDialogDescription>+ </AlertDialogHeader>+ <AlertDialogFooter>+ <AlertDialogCancel>Cancel</AlertDialogCancel>+ <AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>+ </AlertDialogFooter>+ </AlertDialogContent>+ </AlertDialog>+ )+}+```++---++## Checking for Updates++```bash+npx shadcn@latest add button --diff+```++To preview exactly what would change before updating, use `--dry-run` and `--diff`:++```bash+npx shadcn@latest add button --dry-run # see all affected files+npx shadcn@latest add button --diff button.tsx # see the diff for a specific file+```++See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full smart merge workflow.diff --git a/.agents/skills/shadcn/evals/evals.json b/.agents/skills/shadcn/evals/evals.jsonnew file mode 100644index 0000000000..0df77e4b9b--- /dev/null+++ b/.agents/skills/shadcn/evals/evals.json@@ -0,0 +1,47 @@+{+ "skill_name": "shadcn",+ "evals": [+ {+ "id": 1,+ "prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as toggle options). Add validation states for required fields.",+ "expected_output": "A React component using FieldGroup, Field, ToggleGroup, data-invalid/aria-invalid validation, gap-* spacing, and semantic colors.",+ "files": [],+ "expectations": [+ "Uses FieldGroup and Field components for form layout instead of raw div with space-y",+ "Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",+ "Uses data-invalid on Field and aria-invalid on the input control for validation states",+ "Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",+ "Uses semantic color tokens (e.g. bg-background, text-muted-foreground, text-destructive) instead of raw colors like bg-red-500",+ "No manual dark: color overrides"+ ]+ },+ {+ "id": 2,+ "prompt": "Create a dialog component for editing a user profile. It should have the user's avatar at the top, input fields for name and bio, and Save/Cancel buttons with appropriate icons. Using shadcn/ui with radix-nova preset and tabler icons.",+ "expected_output": "A React component with DialogTitle, Avatar+AvatarFallback, data-icon on icon buttons, no icon sizing classes, tabler icon imports.",+ "files": [],+ "expectations": [+ "Includes DialogTitle for accessibility (visible or with sr-only class)",+ "Avatar component includes AvatarFallback",+ "Icons on buttons use the data-icon attribute (data-icon=\"inline-start\" or data-icon=\"inline-end\")",+ "No sizing classes on icons inside components (no size-4, w-4, h-4, etc.)",+ "Uses tabler icons (@tabler/icons-react) instead of lucide-react",+ "Uses asChild for custom triggers (radix preset)"+ ]+ },+ {+ "id": 3,+ "prompt": "Create a dashboard component that shows 4 stat cards in a grid. Each card has a title, large number, percentage change badge, and a loading skeleton state. Using shadcn/ui with base-nova preset and lucide icons.",+ "expected_output": "A React component with full Card composition, Skeleton for loading, Badge for changes, semantic colors, gap-* spacing.",+ "files": [],+ "expectations": [+ "Uses full Card composition with CardHeader, CardTitle, CardContent (not dumping everything into CardContent)",+ "Uses Skeleton component for loading placeholders instead of custom animate-pulse divs",+ "Uses Badge component for percentage change instead of custom styled spans",+ "Uses semantic color tokens instead of raw color values like bg-green-500 or text-red-600",+ "Uses gap-* instead of space-y-* or space-x-* for spacing",+ "Uses size-* when width and height are equal instead of separate w-* h-*"+ ]+ }+ ]+}diff --git a/.agents/skills/shadcn/mcp.md b/.agents/skills/shadcn/mcp.mdnew file mode 100644index 0000000000..15b50e91ec--- /dev/null+++ b/.agents/skills/shadcn/mcp.md@@ -0,0 +1,94 @@+# shadcn MCP Server++The CLI includes an MCP server that lets AI assistants search, browse, view, and install components from registries.++---++## Setup++```bash+shadcn mcp # start the MCP server (stdio)+shadcn mcp init # write config for your editor+```++Editor config files:++| Editor | Config file |+|--------|------------|+| Claude Code | `.mcp.json` |+| Cursor | `.cursor/mcp.json` |+| VS Code | `.vscode/mcp.json` |+| OpenCode | `opencode.json` |+| Codex | `~/.codex/config.toml` (manual) |++---++## Tools++> **Tip:** MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), use `npx shadcn@latest info` — there is no MCP equivalent.++### `shadcn:get_project_registries`++Returns registry names from `components.json`. Errors if no `components.json` exists.++**Input:** none++### `shadcn:list_items_in_registries`++Lists all items from one or more registries.++**Input:** `registries` (string[]), `limit` (number, optional), `offset` (number, optional)++### `shadcn:search_items_in_registries`++Fuzzy search across registries.++**Input:** `registries` (string[]), `query` (string), `limit` (number, optional), `offset` (number, optional)++### `shadcn:view_items_in_registries`++View item details including full file contents.++**Input:** `items` (string[]) — e.g. `["@shadcn/button", "@shadcn/card"]`++### `shadcn:get_item_examples_from_registries`++Find usage examples and demos with source code.++**Input:** `registries` (string[]), `query` (string) — e.g. `"accordion-demo"`, `"button example"`++### `shadcn:get_add_command_for_items`++Returns the CLI install command.++**Input:** `items` (string[]) — e.g. `["@shadcn/button"]`++### `shadcn:get_audit_checklist`++Returns a checklist for verifying components (imports, deps, lint, TypeScript).++**Input:** none++---++## Configuring Registries++Registries are set in `components.json`. The `@shadcn` registry is always built-in.++```json+{+ "registries": {+ "@acme": "https://acme.com/r/{name}.json",+ "@private": {+ "url": "https://private.com/r/{name}.json",+ "headers": { "Authorization": "Bearer ${MY_TOKEN}" }+ }+ }+}+```++- Names must start with `@`.+- URLs must contain `{name}`.+- `${VAR}` references are resolved from environment variables.++Community registry index: `https://ui.shadcn.com/r/registries.json`diff --git a/.agents/skills/shadcn/rules/base-vs-radix.md b/.agents/skills/shadcn/rules/base-vs-radix.mdnew file mode 100644index 0000000000..c1ed7d111a--- /dev/null+++ b/.agents/skills/shadcn/rules/base-vs-radix.md@@ -0,0 +1,306 @@+# Base vs Radix++API differences between `base` and `radix`. Check the `base` field from `npx shadcn@latest info`.++## Contents++- Composition: asChild vs render+- Button / trigger as non-button element+- Select (items prop, placeholder, positioning, multiple, object values)+- ToggleGroup (type vs multiple)+- Slider (scalar vs array)+- Accordion (type and defaultValue)++---++## Composition: asChild (radix) vs render (base)++Radix uses `asChild` to replace the default element. Base uses `render`. Don't wrap triggers in extra elements.++**Incorrect:**++```tsx+<DialogTrigger>+ <div>+ <Button>Open</Button>+ </div>+</DialogTrigger>+```++**Correct (radix):**++```tsx+<DialogTrigger asChild>+ <Button>Open</Button>+</DialogTrigger>+```++**Correct (base):**++```tsx+<DialogTrigger render={<Button />}>Open</DialogTrigger>+```++This applies to all trigger and close components: `DialogTrigger`, `SheetTrigger`, `AlertDialogTrigger`, `DropdownMenuTrigger`, `PopoverTrigger`, `TooltipTrigger`, `CollapsibleTrigger`, `DialogClose`, `SheetClose`, `NavigationMenuLink`, `BreadcrumbLink`, `SidebarMenuButton`, `Badge`, `Item`.++---++## Button / trigger as non-button element (base only)++When `render` changes an element to a non-button (`<a>`, `<span>`), add `nativeButton={false}`.++**Incorrect (base):** missing `nativeButton={false}`.++```tsx+<Button render={<a href="/docs" />}>Read the docs</Button>+```++**Correct (base):**++```tsx+<Button render={<a href="/docs" />} nativeButton={false}>+ Read the docs+</Button>+```++**Correct (radix):**++```tsx+<Button asChild>+ <a href="/docs">Read the docs</a>+</Button>+```++Same for triggers whose `render` is not a `Button`:++```tsx+// base.+<PopoverTrigger render={<InputGroupAddon />} nativeButton={false}>+ Pick date+</PopoverTrigger>+```++---++## Select++**items prop (base only).** Base requires an `items` prop on the root. Radix uses inline JSX only.++**Incorrect (base):**++```tsx+<Select>+ <SelectTrigger><SelectValue placeholder="Select a fruit" /></SelectTrigger>+</Select>+```++**Correct (base):**++```tsx+const items = [+ { label: "Select a fruit", value: null },+ { label: "Apple", value: "apple" },+ { label: "Banana", value: "banana" },+]++<Select items={items}>+ <SelectTrigger>+ <SelectValue />+ </SelectTrigger>+ <SelectContent>+ <SelectGroup>+ {items.map((item) => (+ <SelectItem key={item.value} value={item.value}>{item.label}</SelectItem>+ ))}+ </SelectGroup>+ </SelectContent>+</Select>+```++**Correct (radix):**++```tsx+<Select>+ <SelectTrigger>+ <SelectValue placeholder="Select a fruit" />+ </SelectTrigger>+ <SelectContent>+ <SelectGroup>+ <SelectItem value="apple">Apple</SelectItem>+ <SelectItem value="banana">Banana</SelectItem>+ </SelectGroup>+ </SelectContent>+</Select>+```++**Placeholder.** Base uses a `{ value: null }` item in the items array. Radix uses `<SelectValue placeholder="...">`.++**Content positioning.** Base uses `alignItemWithTrigger`. Radix uses `position`.++```tsx+// base.+<SelectContent alignItemWithTrigger={false} side="bottom">++// radix.+<SelectContent position="popper">+```++---++## Select — multiple selection and object values (base only)++Base supports `multiple`, render-function children on `SelectValue`, and object values with `itemToStringValue`. Radix is single-select with string values only.++**Correct (base — multiple selection):**++```tsx+<Select items={items} multiple defaultValue={[]}>+ <SelectTrigger>+ <SelectValue>+ {(value: string[]) => value.length === 0 ? "Select fruits" : `${value.length} selected`}+ </SelectValue>+ </SelectTrigger>+ ...+</Select>+```++**Correct (base — object values):**++```tsx+<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}>+ <SelectTrigger>+ <SelectValue>{(value) => value.name}</SelectValue>+ </SelectTrigger>+ ...+</Select>+```++---++## ToggleGroup++Base uses a `multiple` boolean prop. Radix uses `type="single"` or `type="multiple"`.++**Incorrect (base):**++```tsx+<ToggleGroup type="single" defaultValue="daily">+ <ToggleGroupItem value="daily">Daily</ToggleGroupItem>+</ToggleGroup>+```++**Correct (base):**++```tsx+// Single (no prop needed), defaultValue is always an array.+<ToggleGroup defaultValue={["daily"]} spacing={2}>+ <ToggleGroupItem value="daily">Daily</ToggleGroupItem>+ <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>+</ToggleGroup>++// Multi-selection.+<ToggleGroup multiple>+ <ToggleGroupItem value="bold">Bold</ToggleGroupItem>+ <ToggleGroupItem value="italic">Italic</ToggleGroupItem>+</ToggleGroup>+```++**Correct (radix):**++```tsx+// Single, defaultValue is a string.+<ToggleGroup type="single" defaultValue="daily" spacing={2}>+ <ToggleGroupItem value="daily">Daily</ToggleGroupItem>+ <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>+</ToggleGroup>++// Multi-selection.+<ToggleGroup type="multiple">+ <ToggleGroupItem value="bold">Bold</ToggleGroupItem>+ <ToggleGroupItem value="italic">Italic</ToggleGroupItem>+</ToggleGroup>+```++**Controlled single value:**++```tsx+// base — wrap/unwrap arrays.+const [value, setValue] = React.useState("normal")+<ToggleGroup value={[value]} onValueChange={(v) => setValue(v[0])}>++// radix — plain string.+const [value, setValue] = React.useState("normal")+<ToggleGroup type="single" value={value} onValueChange={setValue}>+```++---++## Slider++Base accepts a plain number for a single thumb. Radix always requires an array.++**Incorrect (base):**++```tsx+<Slider defaultValue={[50]} max={100} step={1} />+```++**Correct (base):**++```tsx+<Slider defaultValue={50} max={100} step={1} />+```++**Correct (radix):**++```tsx+<Slider defaultValue={[50]} max={100} step={1} />+```++Both use arrays for range sliders. Controlled `onValueChange` in base may need a cast:++```tsx+// base.+const [value, setValue] = React.useState([0.3, 0.7])+<Slider value={value} onValueChange={(v) => setValue(v as number[])} />++// radix.+const [value, setValue] = React.useState([0.3, 0.7])+<Slider value={value} onValueChange={setValue} />+```++---++## Accordion++Radix requires `type="single"` or `type="multiple"` and supports `collapsible`. `defaultValue` is a string. Base uses no `type` prop, uses `multiple` boolean, and `defaultValue` is always an array.++**Incorrect (base):**++```tsx+<Accordion type="single" collapsible defaultValue="item-1">+ <AccordionItem value="item-1">...</AccordionItem>+</Accordion>+```++**Correct (base):**++```tsx+<Accordion defaultValue={["item-1"]}>+ <AccordionItem value="item-1">...</AccordionItem>+</Accordion>++// Multi-select.+<Accordion multiple defaultValue={["item-1", "item-2"]}>+ <AccordionItem value="item-1">...</AccordionItem>+ <AccordionItem value="item-2">...</AccordionItem>+</Accordion>+```++**Correct (radix):**++```tsx+<Accordion type="single" collapsible defaultValue="item-1">+ <AccordionItem value="item-1">...</AccordionItem>+</Accordion>+```diff --git a/.agents/skills/shadcn/rules/composition.md b/.agents/skills/shadcn/rules/composition.mdnew file mode 100644index 0000000000..0e105837cb--- /dev/null+++ b/.agents/skills/shadcn/rules/composition.md@@ -0,0 +1,195 @@+# Component Composition++## Contents++- Items always inside their Group component+- Callouts use Alert+- Empty states use Empty component+- Toast notifications use sonner+- Choosing between overlay components+- Dialog, Sheet, and Drawer always need a Title+- Card structure+- Button has no isPending or isLoading prop+- TabsTrigger must be inside TabsList+- Avatar always needs AvatarFallback+- Use Separator instead of raw hr or border divs+- Use Skeleton for loading placeholders+- Use Badge instead of custom styled spans++---++## Items always inside their Group component++Never render items directly inside the content container.++**Incorrect:**++```tsx+<SelectContent>+ <SelectItem value="apple">Apple</SelectItem>+ <SelectItem value="banana">Banana</SelectItem>+</SelectContent>+```++**Correct:**++```tsx+<SelectContent>+ <SelectGroup>+ <SelectItem value="apple">Apple</SelectItem>+ <SelectItem value="banana">Banana</SelectItem>+ </SelectGroup>+</SelectContent>+```++This applies to all group-based components:++| Item | Group |+|------|-------|+| `SelectItem`, `SelectLabel` | `SelectGroup` |+| `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSub` | `DropdownMenuGroup` |+| `MenubarItem` | `MenubarGroup` |+| `ContextMenuItem` | `ContextMenuGroup` |+| `CommandItem` | `CommandGroup` |++---++## Callouts use Alert++```tsx+<Alert>+ <AlertTitle>Warning</AlertTitle>+ <AlertDescription>Something needs attention.</AlertDescription>+</Alert>+```++---++## Empty states use Empty component++```tsx+<Empty>+ <EmptyHeader>+ <EmptyMedia variant="icon"><FolderIcon /></EmptyMedia>+ <EmptyTitle>No projects yet</EmptyTitle>+ <EmptyDescription>Get started by creating a new project.</EmptyDescription>+ </EmptyHeader>+ <EmptyContent>+ <Button>Create Project</Button>+ </EmptyContent>+</Empty>+```++---++## Toast notifications use sonner++```tsx+import { toast } from "sonner"++toast.success("Changes saved.")+toast.error("Something went wrong.")+toast("File deleted.", {+ action: { label: "Undo", onClick: () => undoDelete() },+})+```++---++## Choosing between overlay components++| Use case | Component |+|----------|-----------|+| Focused task that requires input | `Dialog` |+| Destructive action confirmation | `AlertDialog` |+| Side panel with details or filters | `Sheet` |+| Mobile-first bottom panel | `Drawer` |+| Quick info on hover | `HoverCard` |+| Small contextual content on click | `Popover` |++---++## Dialog, Sheet, and Drawer always need a Title++`DialogTitle`, `SheetTitle`, `DrawerTitle` are required for accessibility. Use `className="sr-only"` if visually hidden.++```tsx+<DialogContent>+ <DialogHeader>+ <DialogTitle>Edit Profile</DialogTitle>+ <DialogDescription>Update your profile.</DialogDescription>+ </DialogHeader>+ ...+</DialogContent>+```++---++## Card structure++Use full composition — don't dump everything into `CardContent`:++```tsx+<Card>+ <CardHeader>+ <CardTitle>Team Members</CardTitle>+ <CardDescription>Manage your team.</CardDescription>+ </CardHeader>+ <CardContent>...</CardContent>+ <CardFooter>+ <Button>Invite</Button>+ </CardFooter>+</Card>+```++---++## Button has no isPending or isLoading prop++Compose with `Spinner` + `data-icon` + `disabled`:++```tsx+<Button disabled>+ <Spinner data-icon="inline-start" />+ Saving...+</Button>+```++---++## TabsTrigger must be inside TabsList++Never render `TabsTrigger` directly inside `Tabs` — always wrap in `TabsList`:++```tsx+<Tabs defaultValue="account">+ <TabsList>+ <TabsTrigger value="account">Account</TabsTrigger>+ <TabsTrigger value="password">Password</TabsTrigger>+ </TabsList>+ <TabsContent value="account">...</TabsContent>+</Tabs>+```++---++## Avatar always needs AvatarFallback++Always include `AvatarFallback` for when the image fails to load:++```tsx+<Avatar>+ <AvatarImage src="/avatar.png" alt="User" />+ <AvatarFallback>JD</AvatarFallback>+</Avatar>+```++---++## Use existing components instead of custom markup++| Instead of | Use |+|---|---|+| `<hr>` or `<div className="border-t">` | `<Separator />` |+| `<div className="animate-pulse">` with styled divs | `<Skeleton className="h-4 w-3/4" />` |+| `<span className="rounded-full bg-green-100 ...">` | `<Badge variant="secondary">` |diff --git a/.agents/skills/shadcn/rules/forms.md b/.agents/skills/shadcn/rules/forms.mdnew file mode 100644index 0000000000..f451e2f7bc--- /dev/null+++ b/.agents/skills/shadcn/rules/forms.md@@ -0,0 +1,192 @@+# Forms & Inputs++## Contents++- Forms use FieldGroup + Field+- InputGroup requires InputGroupInput/InputGroupTextarea+- Buttons inside inputs use InputGroup + InputGroupAddon+- Option sets (2–7 choices) use ToggleGroup+- FieldSet + FieldLegend for grouping related fields+- Field validation and disabled states++---++## Forms use FieldGroup + Field++Always use `FieldGroup` + `Field` — never raw `div` with `space-y-*`:++```tsx+<FieldGroup>+ <Field>+ <FieldLabel htmlFor="email">Email</FieldLabel>+ <Input id="email" type="email" />+ </Field>+ <Field>+ <FieldLabel htmlFor="password">Password</FieldLabel>+ <Input id="password" type="password" />+ </Field>+</FieldGroup>+```++Use `Field orientation="horizontal"` for settings pages. Use `FieldLabel className="sr-only"` for visually hidden labels.++**Choosing form controls:**++- Simple text input → `Input`+- Dropdown with predefined options → `Select`+- Searchable dropdown → `Combobox`+- Native HTML select (no JS) → `native-select`+- Boolean toggle → `Switch` (for settings) or `Checkbox` (for forms)+- Single choice from few options → `RadioGroup`+- Toggle between 2–5 options → `ToggleGroup` + `ToggleGroupItem`+- OTP/verification code → `InputOTP`+- Multi-line text → `Textarea`++---++## InputGroup requires InputGroupInput/InputGroupTextarea++Never use raw `Input` or `Textarea` inside an `InputGroup`.++**Incorrect:**++```tsx+<InputGroup>+ <Input placeholder="Search..." />+</InputGroup>+```++**Correct:**++```tsx+import { InputGroup, InputGroupInput } from "@/components/ui/input-group"++<InputGroup>+ <InputGroupInput placeholder="Search..." />+</InputGroup>+```++---++## Buttons inside inputs use InputGroup + InputGroupAddon++Never place a `Button` directly inside or adjacent to an `Input` with custom positioning.++**Incorrect:**++```tsx+<div className="relative">+ <Input placeholder="Search..." className="pr-10" />+ <Button className="absolute right-0 top-0" size="icon">+ <SearchIcon />+ </Button>+</div>+```++**Correct:**++```tsx+import { InputGroup, InputGroupInput, InputGroupAddon } from "@/components/ui/input-group"++<InputGroup>+ <InputGroupInput placeholder="Search..." />+ <InputGroupAddon>+ <Button size="icon">+ <SearchIcon data-icon="inline-start" />+ </Button>+ </InputGroupAddon>+</InputGroup>+```++---++## Option sets (2–7 choices) use ToggleGroup++Don't manually loop `Button` components with active state.++**Incorrect:**++```tsx+const [selected, setSelected] = useState("daily")++<div className="flex gap-2">+ {["daily", "weekly", "monthly"].map((option) => (+ <Button+ key={option}+ variant={selected === option ? "default" : "outline"}+ onClick={() => setSelected(option)}+ >+ {option}+ </Button>+ ))}+</div>+```++**Correct:**++```tsx+import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"++<ToggleGroup spacing={2}>+ <ToggleGroupItem value="daily">Daily</ToggleGroupItem>+ <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>+ <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>+</ToggleGroup>+```++Combine with `Field` for labelled toggle groups:++```tsx+<Field orientation="horizontal">+ <FieldTitle id="theme-label">Theme</FieldTitle>+ <ToggleGroup aria-labelledby="theme-label" spacing={2}>+ <ToggleGroupItem value="light">Light</ToggleGroupItem>+ <ToggleGroupItem value="dark">Dark</ToggleGroupItem>+ <ToggleGroupItem value="system">System</ToggleGroupItem>+ </ToggleGroup>+</Field>+```++> **Note:** `defaultValue` and `type`/`multiple` props differ between base and radix. See [base-vs-radix.md](./base-vs-radix.md#togglegroup).++---++## FieldSet + FieldLegend for grouping related fields++Use `FieldSet` + `FieldLegend` for related checkboxes, radios, or switches — not `div` with a heading:++```tsx+<FieldSet>+ <FieldLegend variant="label">Preferences</FieldLegend>+ <FieldDescription>Select all that apply.</FieldDescription>+ <FieldGroup className="gap-3">+ <Field orientation="horizontal">+ <Checkbox id="dark" />+ <FieldLabel htmlFor="dark" className="font-normal">Dark mode</FieldLabel>+ </Field>+ </FieldGroup>+</FieldSet>+```++---++## Field validation and disabled states++Both attributes are needed — `data-invalid`/`data-disabled` styles the field (label, description), while `aria-invalid`/`disabled` styles the control.++```tsx+// Invalid.+<Field data-invalid>+ <FieldLabel htmlFor="email">Email</FieldLabel>+ <Input id="email" aria-invalid />+ <FieldDescription>Invalid email address.</FieldDescription>+</Field>++// Disabled.+<Field data-disabled>+ <FieldLabel htmlFor="email">Email</FieldLabel>+ <Input id="email" disabled />+</Field>+```++Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`, `NativeSelect`, `InputOTP`.diff --git a/.agents/skills/shadcn/rules/icons.md b/.agents/skills/shadcn/rules/icons.mdnew file mode 100644index 0000000000..bba8102f01--- /dev/null+++ b/.agents/skills/shadcn/rules/icons.md@@ -0,0 +1,101 @@+# Icons++**Always use the project's configured `iconLibrary` for imports.** Check the `iconLibrary` field from project context: `lucide` → `lucide-react`, `tabler` → `@tabler/icons-react`, etc. Never assume `lucide-react`.++---++## Icons in Button use data-icon attribute++Add `data-icon="inline-start"` (prefix) or `data-icon="inline-end"` (suffix) to the icon. No sizing classes on the icon.++**Incorrect:**++```tsx+<Button>+ <SearchIcon className="mr-2 size-4" />+ Search+</Button>+```++**Correct:**++```tsx+<Button>+ <SearchIcon data-icon="inline-start"/>+ Search+</Button>++<Button>+ Next+ <ArrowRightIcon data-icon="inline-end"/>+</Button>+```++---++## No sizing classes on icons inside components++Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons inside `Button`, `DropdownMenuItem`, `Alert`, `Sidebar*`, or other shadcn components. Unless the user explicitly asks for custom icon sizes.++**Incorrect:**++```tsx+<Button>+ <SearchIcon className="size-4" data-icon="inline-start" />+ Search+</Button>++<DropdownMenuItem>+ <SettingsIcon className="mr-2 size-4" />+ Settings+</DropdownMenuItem>+```++**Correct:**++```tsx+<Button>+ <SearchIcon data-icon="inline-start" />+ Search+</Button>++<DropdownMenuItem>+ <SettingsIcon />+ Settings+</DropdownMenuItem>+```++---++## Pass icons as component objects, not string keys++Use `icon={CheckIcon}`, not a string key to a lookup map.++**Incorrect:**++```tsx+const iconMap = {+ check: CheckIcon,+ alert: AlertIcon,+}++function StatusBadge({ icon }: { icon: string }) {+ const Icon = iconMap[icon]+ return <Icon />+}++<StatusBadge icon="check" />+```++**Correct:**++```tsx+// Import from the project's configured iconLibrary (e.g. lucide-react, @tabler/icons-react).+import { CheckIcon } from "lucide-react"++function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) {+ return <Icon />+}++<StatusBadge icon={CheckIcon} />+```diff --git a/.agents/skills/shadcn/rules/styling.md b/.agents/skills/shadcn/rules/styling.mdnew file mode 100644index 0000000000..38d473212b--- /dev/null+++ b/.agents/skills/shadcn/rules/styling.md@@ -0,0 +1,162 @@+# Styling & Customization++See [customization.md](../customization.md) for theming, CSS variables, and adding custom colors.++## Contents++- Semantic colors+- Built-in variants first+- className for layout only+- No space-x-* / space-y-*+- Prefer size-* over w-* h-* when equal+- Prefer truncate shorthand+- No manual dark: color overrides+- Use cn() for conditional classes+- No manual z-index on overlay components++---++## Semantic colors++**Incorrect:**++```tsx+<div className="bg-blue-500 text-white">+ <p className="text-gray-600">Secondary text</p>+</div>+```++**Correct:**++```tsx+<div className="bg-primary text-primary-foreground">+ <p className="text-muted-foreground">Secondary text</p>+</div>+```++---++## No raw color values for status/state indicators++For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.++**Incorrect:**++```tsx+<span className="text-emerald-600">+20.1%</span>+<span className="text-green-500">Active</span>+<span className="text-red-600">-3.2%</span>+```++**Correct:**++```tsx+<Badge variant="secondary">+20.1%</Badge>+<Badge>Active</Badge>+<span className="text-destructive">-3.2%</span>+```++If you need a success/positive color that doesn't exist as a semantic token, use a Badge variant or ask the user about adding a custom CSS variable to the theme (see [customization.md](../customization.md)).++---++## Built-in variants first++**Incorrect:**++```tsx+<Button className="border border-input bg-transparent hover:bg-accent">+ Click me+</Button>+```++**Correct:**++```tsx+<Button variant="outline">Click me</Button>+```++---++## className for layout only++Use `className` for layout (e.g. `max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography. To change colors, use semantic tokens, built-in variants, or CSS variables.++**Incorrect:**++```tsx+<Card className="bg-blue-100 text-blue-900 font-bold">+ <CardContent>Dashboard</CardContent>+</Card>+```++**Correct:**++```tsx+<Card className="max-w-md mx-auto">+ <CardContent>Dashboard</CardContent>+</Card>+```++To customize a component's appearance, prefer these approaches in order:+1. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.+2. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.+3. **CSS variables** — define custom colors in the global CSS file (see [customization.md](../customization.md)).++---++## No space-x-* / space-y-*++Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.++```tsx+<div className="flex flex-col gap-4">+ <Input />+ <Input />+ <Button>Submit</Button>+</div>+```++---++## Prefer size-* over w-* h-* when equal++`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.++---++## Prefer truncate shorthand++`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.++---++## No manual dark: color overrides++Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.++---++## Use cn() for conditional classes++Use the `cn()` utility from the project for conditional or merged class names. Don't write manual ternaries in className strings.++**Incorrect:**++```tsx+<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>+```++**Correct:**++```tsx+import { cn } from "@/lib/utils"++<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>+```++---++## No manual z-index on overlay components++`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Never add `z-50` or `z-[999]`.diff --git a/packages/admin-sdk/src/types/generated/Category.ts b/packages/admin-sdk/src/types/generated/Category.tsindex 7555d6770c..2745cf1ab5 100644--- a/packages/admin-sdk/src/types/generated/Category.ts+++ b/packages/admin-sdk/src/types/generated/Category.ts@@ -6,6 +6,7 @@ import type {CustomField} from '@/types'interface Category {id: string;name: string;+ pretty_name: string;permalink: string;position: number;depth: number;diff --git a/packages/admin/src/components/address-form-dialog.tsx b/packages/admin/src/components/address-form-dialog.tsxindex 12b34f4cf6..29055b4a35 100644--- a/packages/admin/src/components/address-form-dialog.tsx+++ b/packages/admin/src/components/address-form-dialog.tsx@@ -1,6 +1,14 @@import type { Address } from '@spree/admin-sdk'-import { type FormEvent, useMemo, useState } from 'react'+import { type FormEvent, useCallback, useMemo, useState } from 'react'import { Button } from '@/components/ui/button'+import {+ Combobox,+ ComboboxContent,+ ComboboxEmpty,+ ComboboxInput,+ ComboboxItem,+ ComboboxList,+} from '@/components/ui/combobox'import {Sheet,SheetContent,@@ -11,13 +19,6 @@ import {} from '@/components/ui/sheet'import { Field, FieldGroup, FieldLabel } from '@/components/ui/field'import { Input } from '@/components/ui/input'-import {- Select,- SelectContent,- SelectItem,- SelectTrigger,- SelectValue,-} from '@/components/ui/select'import { useCountries } from '@/hooks/use-countries'export interface AddressParams {@@ -48,17 +49,39 @@ export function AddressFormDialog({isPending?: boolean}) {const { countries } = useCountries()+const [selectedCountryIso, setSelectedCountryIso] = useState<string>(address?.country_iso ?? '',)+ const [selectedStateAbbr, setSelectedStateAbbr] = useState<string>(+ address?.state_abbr ?? '',+ )- const selectedCountry = useMemo(+ const countryData = useMemo(() => countries.find((c) => c.iso === selectedCountryIso),[countries, selectedCountryIso],)- const statesRequired = selectedCountry?.states_required ?? false- const states = (selectedCountry as any)?.states ?? []+ const statesRequired = countryData?.states_required ?? false+ const states: Array<{ abbr: string; name: string }> = (countryData as any)?.states ?? []++ // Map ISO → name for the combobox display+ const countryNameByIso = useMemo(() => {+ const map = new Map<string, string>()+ for (const c of countries) map.set(c.iso, c.name)+ return map+ }, [countries])++ const stateNameByAbbr = useMemo(() => {+ const map = new Map<string, string>()+ for (const s of states) map.set(s.abbr, s.name)+ return map+ }, [states])++ const handleCountryChange = useCallback((iso: string) => {+ setSelectedCountryIso(iso)+ setSelectedStateAbbr('')+ }, [])function handleSubmit(e: FormEvent<HTMLFormElement>) {e.preventDefault()@@ -70,126 +93,112 @@ export function AddressFormDialog({address2: fd.get('address2') as string,city: fd.get('city') as string,postal_code: fd.get('postal_code') as string,- country_iso: fd.get('country_iso') as string,- state_abbr: fd.get('state_abbr') as string,+ country_iso: selectedCountryIso,+ state_abbr: statesRequired ? selectedStateAbbr : (fd.get('state_abbr') as string),phone: fd.get('phone') as string,})}+ // Prevent Enter in combobox inputs from submitting the form+ function handleKeyDown(e: React.KeyboardEvent) {+ const target = e.target as HTMLElement+ if (e.key === 'Enter' && (target.getAttribute('role') === 'combobox' || target.closest('[data-slot="combobox-content"]'))) {+ e.preventDefault()+ }+ }+return (<Sheet open={open} onOpenChange={(o) => onOpenChange(o as boolean)}><SheetContent side="right"><SheetHeader>- <SheetTitle>{title}</SheetTitle>- <SheetDescription>Update the address details.</SheetDescription>+ <div>+ <SheetTitle>{title}</SheetTitle>+ <SheetDescription>Update the address details.</SheetDescription>+ </div></SheetHeader>- <form onSubmit={handleSubmit} className="flex flex-col flex-1 overflow-hidden">+ <form onSubmit={handleSubmit} onKeyDown={handleKeyDown} className="flex flex-col flex-1 overflow-hidden"><div className="flex-1 overflow-y-auto p-4"><FieldGroup><div className="grid grid-cols-2 gap-3"><Field>- <FieldLabel htmlFor="addr-fn">First Name</FieldLabel>- <Input- id="addr-fn"- name="first_name"- defaultValue={address?.first_name ?? ''}- />+ <FieldLabel htmlFor="addr-fn">First name</FieldLabel>+ <Input id="addr-fn" name="first_name" defaultValue={address?.first_name ?? ''} /></Field><Field>- <FieldLabel htmlFor="addr-ln">Last Name</FieldLabel>- <Input- id="addr-ln"- name="last_name"- defaultValue={address?.last_name ?? ''}- />+ <FieldLabel htmlFor="addr-ln">Last name</FieldLabel>+ <Input id="addr-ln" name="last_name" defaultValue={address?.last_name ?? ''} /></Field></div><Field><FieldLabel htmlFor="addr-a1">Address</FieldLabel>- <Input- id="addr-a1"- name="address1"- defaultValue={address?.address1 ?? ''}- />+ <Input id="addr-a1" name="address1" defaultValue={address?.address1 ?? ''} /></Field><Field><FieldLabel htmlFor="addr-a2">Apartment, suite, etc.</FieldLabel>- <Input- id="addr-a2"- name="address2"- defaultValue={address?.address2 ?? ''}- />+ <Input id="addr-a2" name="address2" defaultValue={address?.address2 ?? ''} />+ </Field>+ <Field>+ <FieldLabel>Country</FieldLabel>+ <Combobox+ value={selectedCountryIso}+ onValueChange={(v) => handleCountryChange(v as string)}+ itemToStringLabel={(iso) => countryNameByIso.get(iso as string) ?? (iso as string)}+ >+ <ComboboxInput placeholder="Search countries..." />+ <ComboboxContent>+ <ComboboxList>+ {countries.map((c) => (+ <ComboboxItem key={c.iso} value={c.iso}>+ {c.name}+ </ComboboxItem>+ ))}+ <ComboboxEmpty>No countries found</ComboboxEmpty>+ </ComboboxList>+ </ComboboxContent>+ </Combobox></Field><div className="grid grid-cols-2 gap-3"><Field><FieldLabel htmlFor="addr-city">City</FieldLabel>- <Input- id="addr-city"- name="city"- defaultValue={address?.city ?? ''}- />+ <Input id="addr-city" name="city" defaultValue={address?.city ?? ''} /></Field><Field>- <FieldLabel htmlFor="addr-zip">Postal Code</FieldLabel>- <Input- id="addr-zip"- name="postal_code"- defaultValue={address?.postal_code ?? ''}- />+ <FieldLabel>State / Province</FieldLabel>+ {statesRequired && states.length > 0 ? (+ <Combobox+ key={selectedCountryIso}+ value={selectedStateAbbr}+ onValueChange={(v) => setSelectedStateAbbr(v as string)}+ itemToStringLabel={(abbr) => stateNameByAbbr.get(abbr as string) ?? (abbr as string)}+ >+ <ComboboxInput placeholder="Search states..." />+ <ComboboxContent>+ <ComboboxList>+ {states.map((s) => (+ <ComboboxItem key={s.abbr} value={s.abbr}>+ {s.name}+ </ComboboxItem>+ ))}+ <ComboboxEmpty>No states found</ComboboxEmpty>+ </ComboboxList>+ </ComboboxContent>+ </Combobox>+ ) : (+ <Input+ id="addr-state"+ name="state_abbr"+ defaultValue={address?.state_abbr ?? ''}+ />+ )}</Field></div><Field>- <FieldLabel>Country</FieldLabel>- <Select- name="country_iso"- defaultValue={address?.country_iso ?? ''}- onValueChange={setSelectedCountryIso}- >- <SelectTrigger className="w-full">- <SelectValue placeholder="Select country" />- </SelectTrigger>- <SelectContent>- {countries.map((country) => (- <SelectItem key={country.iso} value={country.iso}>- {country.name}- </SelectItem>- ))}- </SelectContent>- </Select>- </Field>- <Field>- <FieldLabel htmlFor="addr-state">State / Province</FieldLabel>- {statesRequired && states.length > 0 ? (- <Select- name="state_abbr"- defaultValue={address?.state_abbr ?? ''}- >- <SelectTrigger className="w-full">- <SelectValue placeholder="Select state" />- </SelectTrigger>- <SelectContent>- {states.map((state: { abbr: string; name: string }) => (- <SelectItem key={state.abbr} value={state.abbr}>- {state.name}- </SelectItem>- ))}- </SelectContent>- </Select>- ) : (- <Input- id="addr-state"- name="state_abbr"- defaultValue={address?.state_abbr ?? ''}- />- )}+ <FieldLabel htmlFor="addr-zip">Postal code</FieldLabel>+ <Input id="addr-zip" name="postal_code" defaultValue={address?.postal_code ?? ''} /></Field><Field><FieldLabel htmlFor="addr-phone">Phone</FieldLabel>- <Input- id="addr-phone"- name="phone"- defaultValue={address?.phone ?? ''}- />+ <Input id="addr-phone" name="phone" defaultValue={address?.phone ?? ''} /></Field></FieldGroup></div>diff --git a/skills-lock.json b/skills-lock.jsonindex 00ca5b6a78..ba7141e6ac 100644--- a/skills-lock.json+++ b/skills-lock.json@@ -4,7 +4,7 @@"shadcn": {"source": "shadcn/ui","sourceType": "github",- "computedHash": "91c02eb706f046fb9d6a061efbb96496e4be751b5b14c283cf82baaa50f3a985"+ "computedHash": "873c67922d80775a9fdf596db7964b579f0408c30ec6e3d11989f6055bbec89f"}}}diff --git a/spree/api/app/controllers/spree/api/v3/admin/countries_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/countries_controller.rbindex cc521c6459..f5e228fd88 100644--- a/spree/api/app/controllers/spree/api/v3/admin/countries_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/countries_controller.rb@@ -17,6 +17,12 @@ module SpreeSpree::Country.all.order(:name)end+ # Return all countries without pagination — there are ~250 and they're+ # needed in full for address form dropdowns.+ def limit+ 1000+ end+def find_resourcescope.find_by!(iso: params[:id].upcase)enddiff --git a/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/products_controller.rbindex cd89c4b06d..b0bb0d6024 100644--- a/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb@@ -68,6 +68,7 @@ module Spreeparams.permit(*Spree::PermittedAttributes.product_attributes,tags: [],+ category_ids: [],variants: [:id, :sku, :barcode, :price, :compare_at_price,:cost_price, :cost_currency,@@ -89,6 +90,13 @@ module Spreedef update_paramsp = permitted_params.to_h.with_indifferent_access+ # Map 6.0 API name (category_ids) to model column (taxon_ids)+ if p.key?(:category_ids)+ p[:taxon_ids] = Array(p.delete(:category_ids)).filter_map do |id|+ id.to_s.include?('_') ? Spree::Taxon.decode_prefixed_id(id) : id+ end+ end+if p.key?(:taxon_ids)other_store_taxon_ids = @resource.taxons.joins(:taxonomy)diff --git a/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rbindex ad66fe89b4..266aefbcdb 100644--- a/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb@@ -5,12 +5,12 @@ module Spree# Admin API Category Serializer# Full category data including admin-only fieldsclass CategorySerializer < V3::CategorySerializer- typelize lft: :number, rgt: :number,+ typelize pretty_name: :string, lft: :number, rgt: :number,hide_from_nav: :boolean, sort_order: :string, rules_match_policy: :string,automatic: :boolean# Admin-only attributes- attributes :lft, :rgt, :hide_from_nav, :sort_order, :rules_match_policy, :automatic+ attributes :pretty_name, :lft, :rgt, :hide_from_nav, :sort_order, :rules_match_policy, :automatic# Override inherited associations to use admin serializersone :parent,diff --git a/spree/api/spec/controllers/spree/api/v3/admin/countries_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/countries_controller_spec.rbnew file mode 100644index 0000000000..2016d2582b--- /dev/null+++ b/spree/api/spec/controllers/spree/api/v3/admin/countries_controller_spec.rb@@ -0,0 +1,104 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Admin::CountriesController, type: :controller do+ render_views++ include_context 'API v3 Admin authenticated'++ before { request.headers.merge!(headers) }++ describe 'GET #index' do+ subject { get :index, as: :json }++ it 'returns countries' do+ subject+ expect(response).to have_http_status(:ok)+ expect(json_response['data']).to be_an(Array)+ expect(json_response['data'].length).to be > 0+ end++ it 'returns ALL countries without pagination truncation' do+ subject+ total_countries = Spree::Country.count+ expect(json_response['data'].length).to eq(total_countries)+ expect(json_response['meta']['total_count']).to eq(total_countries)+ end++ it 'returns countries ordered by name' do+ subject+ names = json_response['data'].map { |c| c['name'] }+ expect(names).to eq(names.sort)+ end++ it 'includes iso and name fields' do+ subject+ country = json_response['data'].first+ expect(country['iso']).to be_present+ expect(country['name']).to be_present+ end++ context 'with expand=states' do+ subject { get :index, params: { expand: 'states' }, as: :json }++ let!(:country_with_states) do+ country = Spree::Country.first || create(:country)+ create(:state, country: country) unless country.states.any?+ country+ end++ it 'includes nested states' do+ subject+ country_data = json_response['data'].find { |c| c['iso'] == country_with_states.iso }+ expect(country_data['states']).to be_an(Array)+ expect(country_data['states'].first['abbr']).to be_present+ expect(country_data['states'].first['name']).to be_present+ end+ end++ context 'without authentication' do+ let(:headers) { {} }++ it 'returns unauthorized' do+ subject+ expect(response).to have_http_status(:unauthorized)+ end+ end+ end++ describe 'GET #show' do+ let!(:country) { Spree::Country.first || create(:country) }++ subject { get :show, params: { id: country.iso }, as: :json }++ it 'returns the country by ISO code' do+ subject+ expect(response).to have_http_status(:ok)+ expect(json_response['iso']).to eq(country.iso)+ expect(json_response['name']).to eq(country.name)+ end++ it 'accepts lowercase ISO code' do+ get :show, params: { id: country.iso.downcase }, as: :json+ expect(response).to have_http_status(:ok)+ expect(json_response['iso']).to eq(country.iso)+ end++ context 'with expand=states' do+ before { create(:state, country: country) unless country.states.any? }++ it 'includes nested states' do+ get :show, params: { id: country.iso, expand: 'states' }, as: :json+ expect(response).to have_http_status(:ok)+ expect(json_response['states']).to be_an(Array)+ expect(json_response['states']).not_to be_empty+ end+ end++ context 'with invalid ISO code' do+ it 'returns not found' do+ get :show, params: { id: 'ZZ' }, as: :json+ expect(response).to have_http_status(:not_found)+ end+ end+ end+enddiff --git a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rbindex ed06a0025d..9c188049aa 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb@@ -151,48 +151,80 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller doenddescribe 'POST #create' do- subject { post :create, params: product_params, as: :json }-before { request.headers.merge!(headers) }let(:tax_category) { create(:tax_category) }let(:shipping_category) { create(:shipping_category) }- let(:product_params) do- {- name: 'New Product',- price: 19.99,- shipping_category_id: shipping_category.id- }- end+ let(:taxonomy) { create(:taxonomy, store: store) }+ let(:category1) { create(:taxon, taxonomy: taxonomy) }+ let(:category2) { create(:taxon, taxonomy: taxonomy) }- it 'creates a product' do- expect { subject }.to change(Spree::Product, :count).by(1)+ it 'creates a minimal product' do+ expect {+ post :create, params: { name: 'Simple Product', price: 19.99, shipping_category_id: shipping_category.id }, as: :json+ }.to change(Spree::Product, :count).by(1)expect(response).to have_http_status(:created)- expect(json_response['name']).to eq('New Product')+ expect(json_response['name']).to eq('Simple Product')end- context 'with nested variants, prices, tags, and taxon_ids' do- let(:taxonomy) { create(:taxonomy, store: store) }- let(:taxon) { create(:taxon, taxonomy: taxonomy) }+ context 'with full payload: multiple variants, multi-currency prices, categories, tags' dolet(:product_params) do{- name: 'Test product',- price: 10.99,+ name: 'Premium T-Shirt',+ description: 'A premium cotton t-shirt',+ status: 'draft',+ price: 29.99,+ compare_at_price: 39.99,+ cost_price: 8.50,+ sku: 'PREM-TEE',shipping_category_id: shipping_category.id,tax_category_id: tax_category.prefixed_id,- taxon_ids: [taxon.prefixed_id],- tags: ['eco', 'best-seller'],+ category_ids: [category1.prefixed_id, category2.prefixed_id],+ tags: ['premium', 'cotton', 'summer'],+ slug: 'premium-t-shirt',+ meta_title: 'Premium T-Shirt',+ meta_description: 'Shop our premium cotton t-shirt',variants: [{- options: [{ name: 'size', value: 'small' }],- sku: 'TEST-SM',- total_on_hand: 10,+ sku: 'PREM-TEE-S',+ options: [{ name: 'size', value: 'Small' }],+ weight: 0.2,+ width: 30,+ height: 40,+ depth: 2,+ weight_unit: 'kg',+ dimensions_unit: 'cm',+ track_inventory: true,+ total_on_hand: 50,+ prices: [+ { currency: 'USD', amount: 29.99, compare_at_amount: 39.99 },+ { currency: 'EUR', amount: 27.99 },+ { currency: 'GBP', amount: 24.99 }+ ]+ },+ {+ sku: 'PREM-TEE-M',+ options: [{ name: 'size', value: 'Medium' }],+ weight: 0.22,track_inventory: true,- weight: 0.5,+ total_on_hand: 100,prices: [- { currency: 'USD', amount: 10.99 },- { currency: 'EUR', amount: 9.99 }+ { currency: 'USD', amount: 29.99 },+ { currency: 'EUR', amount: 27.99 },+ { currency: 'GBP', amount: 24.99 }+ ]+ },+ {+ sku: 'PREM-TEE-L',+ options: [{ name: 'size', value: 'Large' }],+ weight: 0.25,+ track_inventory: true,+ total_on_hand: 75,+ prices: [+ { currency: 'USD', amount: 31.99 },+ { currency: 'EUR', amount: 29.99 },+ { currency: 'GBP', amount: 26.99 }]}]@@ -200,30 +232,65 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller doendit 'creates product with all nested data' do- expect { subject }.to change(Spree::Product, :count).by(1)- .and change(Spree::Variant, :count).by(2) # master + variant+ expect {+ post :create, params: product_params, as: :json+ }.to change(Spree::Product, :count).by(1)+ .and change(Spree::Variant, :count).by(4) # master + 3 variantsexpect(response).to have_http_status(:created)- expect(json_response['name']).to eq('Test product')-- created_product = Spree::Product.find_by(name: 'Test product')- expect(created_product.tag_list).to match_array(['eco', 'best-seller'])- expect(created_product.taxons).to include(taxon)- expect(created_product.tax_category).to eq(tax_category)-- variant = created_product.variants.first- expect(variant.sku).to eq('TEST-SM')- expect(variant.option_values.first.presentation).to eq('small')- expect(variant.prices.count).to be >= 2- expect(variant.prices.find_by(currency: 'EUR').amount.to_f).to eq(9.99)++ created = Spree::Product.find_by(name: 'Premium T-Shirt')+ expect(created).to be_present++ # Product attributes+ expect(created.description.to_plain_text).to include('premium cotton')+ expect(created.status).to eq('draft')+ expect(created.slug).to eq('premium-t-shirt')+ expect(created.meta_title).to eq('Premium T-Shirt')+ expect(created.tax_category).to eq(tax_category)+ expect(created.tag_list).to match_array(['premium', 'cotton', 'summer'])+ expect(created.taxons).to match_array([category1, category2])++ # Master variant+ master = created.master+ expect(master.sku).to eq('PREM-TEE')+ expect(master.price.to_f).to eq(29.99)+ expect(master.compare_at_price.to_f).to eq(39.99)+ expect(master.cost_price.to_f).to eq(8.50)++ # Variants+ expect(created.variants.count).to eq(3)++ small = created.variants.find_by(sku: 'PREM-TEE-S')+ expect(small).to be_present+ expect(small.weight.to_f).to eq(0.2)+ expect(small.width.to_f).to eq(30.0)+ expect(small.height.to_f).to eq(40.0)+ expect(small.depth.to_f).to eq(2.0)+ expect(small.option_values.first.name).to eq('Small')+ expect(small.option_values.first.option_type.name).to eq('size')++ # Multi-currency prices+ expect(small.prices.count).to be >= 3+ expect(small.prices.find_by(currency: 'USD').amount.to_f).to eq(29.99)+ expect(small.prices.find_by(currency: 'USD').compare_at_amount.to_f).to eq(39.99)+ expect(small.prices.find_by(currency: 'EUR').amount.to_f).to eq(27.99)+ expect(small.prices.find_by(currency: 'GBP').amount.to_f).to eq(24.99)++ medium = created.variants.find_by(sku: 'PREM-TEE-M')+ expect(medium).to be_present+ expect(medium.total_on_hand).to eq(100)++ large = created.variants.find_by(sku: 'PREM-TEE-L')+ expect(large).to be_present+ expect(large.prices.find_by(currency: 'USD').amount.to_f).to eq(31.99)+ expect(large.prices.find_by(currency: 'GBP').amount.to_f).to eq(26.99)endendcontext 'with invalid params' do- let(:product_params) { { name: '' } }-it 'returns validation errors' do- subject+ post :create, params: { name: '' }, as: :jsonexpect(response).to have_http_status(:unprocessable_content)expect(json_response['error']['code']).to eq('validation_error')@@ -233,18 +300,133 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller doenddescribe 'PATCH #update' do- subject { patch :update, params: { id: product.prefixed_id, name: 'Updated Name' }, as: :json }-before { request.headers.merge!(headers) }- it 'updates the product' do- subject+ let(:taxonomy) { create(:taxonomy, store: store) }+ let(:category1) { create(:taxon, taxonomy: taxonomy) }+ let(:category2) { create(:taxon, taxonomy: taxonomy) }+ let(:tax_category) { create(:tax_category) }++ it 'updates basic product attributes' do+ patch :update, params: { id: product.prefixed_id, name: 'Updated Name' }, as: :jsonexpect(response).to have_http_status(:ok)expect(json_response['name']).to eq('Updated Name')expect(product.reload.name).to eq('Updated Name')end+ context 'with full payload: name, description, status, categories, tags, SEO, variants with multi-currency prices' do+ let!(:product_to_update) do+ create(:product_with_option_types, stores: [store]).tap do |p|+ p.master.update!(sku: 'OLD-SKU')+ end+ end++ let(:update_params) do+ {+ id: product_to_update.prefixed_id,+ name: 'Updated Premium Shirt',+ description: 'Updated description for the premium shirt',+ status: 'active',+ slug: 'updated-premium-shirt',+ meta_title: 'Updated Premium Shirt | Shop',+ meta_description: 'Buy the updated premium shirt',+ category_ids: [category1.prefixed_id, category2.prefixed_id],+ tags: ['updated', 'premium', 'new-arrival'],+ tax_category_id: tax_category.prefixed_id,+ variants: [+ {+ sku: 'UPD-SHIRT-S',+ options: [{ name: 'size', value: 'Small' }],+ weight: 0.3,+ track_inventory: true,+ prices: [+ { currency: 'USD', amount: 34.99, compare_at_amount: 49.99 },+ { currency: 'EUR', amount: 31.99 },+ { currency: 'GBP', amount: 28.99 }+ ]+ },+ {+ sku: 'UPD-SHIRT-XL',+ options: [{ name: 'size', value: 'XL' }],+ weight: 0.4,+ track_inventory: true,+ prices: [+ { currency: 'USD', amount: 36.99 },+ { currency: 'EUR', amount: 33.99 },+ { currency: 'GBP', amount: 30.99 }+ ]+ }+ ]+ }+ end++ it 'updates product with all nested data' do+ patch :update, params: update_params, as: :json++ expect(response).to have_http_status(:ok)++ updated = product_to_update.reload+ expect(updated.name).to eq('Updated Premium Shirt')+ expect(updated.status).to eq('active')+ expect(updated.slug).to eq('updated-premium-shirt')+ expect(updated.meta_title).to eq('Updated Premium Shirt | Shop')+ expect(updated.tax_category).to eq(tax_category)+ expect(updated.tag_list).to match_array(['updated', 'premium', 'new-arrival'])+ expect(updated.taxons).to match_array([category1, category2])++ # Variants created+ small = updated.variants.find_by(sku: 'UPD-SHIRT-S')+ expect(small).to be_present+ expect(small.weight.to_f).to eq(0.3)+ expect(small.option_values.first.name).to eq('Small')++ # Multi-currency prices on small variant+ expect(small.prices.find_by(currency: 'USD').amount.to_f).to eq(34.99)+ expect(small.prices.find_by(currency: 'USD').compare_at_amount.to_f).to eq(49.99)+ expect(small.prices.find_by(currency: 'EUR').amount.to_f).to eq(31.99)+ expect(small.prices.find_by(currency: 'GBP').amount.to_f).to eq(28.99)++ xl = updated.variants.find_by(sku: 'UPD-SHIRT-XL')+ expect(xl).to be_present+ expect(xl.prices.find_by(currency: 'GBP').amount.to_f).to eq(30.99)+ end+ end++ context 'with category_ids' do+ it 'assigns categories via prefixed IDs' do+ patch :update, params: {+ id: product.prefixed_id,+ category_ids: [category1.prefixed_id, category2.prefixed_id]+ }, as: :json++ expect(response).to have_http_status(:ok)+ expect(product.reload.taxons).to match_array([category1, category2])+ end++ it 'replaces existing categories' do+ product.taxons << category1+ patch :update, params: {+ id: product.prefixed_id,+ category_ids: [category2.prefixed_id]+ }, as: :json++ expect(response).to have_http_status(:ok)+ expect(product.reload.taxons.where(taxonomy: taxonomy)).to eq([category2])+ end++ it 'clears categories when empty array' do+ product.taxons << category1+ patch :update, params: {+ id: product.prefixed_id,+ category_ids: []+ }, as: :json++ expect(response).to have_http_status(:ok)+ expect(product.reload.taxons.where(taxonomy: taxonomy)).to be_empty+ end+ end+context 'with tags' doit 'updates product tags' dopatch :update, params: { id: product.prefixed_id, tags: ['new-tag', 'sale'] }, as: :json