Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Add countries endpoint, category_ids support, and product tests

Damian Legawiec669133ca02a0
diff --git a/.agents/skills/shadcn/SKILL.md b/.agents/skills/shadcn/SKILL.md
new file mode 100644
index 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 components
diff --git a/.agents/skills/shadcn/agents/openai.yml b/.agents/skills/shadcn/agents/openai.yml
new file mode 100644
index 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.png
new file mode 100644
index 0000000000..547154b97f
Binary files /dev/null and b/.agents/skills/shadcn/assets/shadcn-small.png differ
diff --git a/.agents/skills/shadcn/assets/shadcn.png b/.agents/skills/shadcn/assets/shadcn.png
new file mode 100644
index 0000000000..b7b6814acc
Binary files /dev/null and b/.agents/skills/shadcn/assets/shadcn.png differ
diff --git a/.agents/skills/shadcn/cli.md b/.agents/skills/shadcn/cli.md
new file mode 100644
index 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.md
new file mode 100644
index 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.json
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.ts
index 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.tsx
index 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.json
index 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.rb
index 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 Spree
Spree::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_resource
scope.find_by!(iso: params[:id].upcase)
end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb
index 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 Spree
params.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 Spree
def update_params
p = 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.rb
index 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 fields
class 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 serializers
one :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.rb
new file mode 100644
index 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
+end
diff --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.rb
index 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 do
end
describe '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' do
let(: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 do
end
it '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 variants
expect(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)
end
end
context 'with invalid params' do
- let(:product_params) { { name: '' } }
-
it 'returns validation errors' do
- subject
+ post :create, params: { name: '' }, as: :json
expect(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 do
end
describe '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: :json
expect(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' do
it 'updates product tags' do
patch :update, params: { id: product.prefixed_id, tags: ['new-tag', 'sale'] }, as: :json