@spree/dashboard-core 1.0.0-beta.8 → 1.0.0-rc.2

package/dist/vite/discover.js

@@ -63,6 +63,10 @@ function discoverDashboardPlugins({ root, onWarn }) {
   }
   return discovered;
 }
+function resolveShellRoutesDir(root, packageName) {
+  const require2 = createRequire(path.join(root, "package.json"));
+  return path.join(path.dirname(fs.realpathSync(require2.resolve(packageName))), "routes");
+}
 function resolveManifest(pkg, require2) {
   try {
     return require2.resolve(`${pkg}/package.json`);
@@ -85,5 +89,6 @@ function resolveManifest(pkg, require2) {
 }
 export {
   discoverDashboardPluginManifests,
-  discoverDashboardPlugins
+  discoverDashboardPlugins,
+  resolveShellRoutesDir
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spree/dashboard-core",
   "license": "MIT",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-rc.2",
   "description": "Spree Dashboard framework — registries (table, nav, slot, settings-nav), providers (auth, permission, store), admin SDK client, generic infra hooks, and the defineDashboardPlugin extension API. Developer Preview.",
   "author": "Vendo Connect Inc.",
   "homepage": "https://spreecommerce.org",
@@ -81,8 +81,8 @@
     "typescript": "~6.0.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.5",
-    "@spree/admin-sdk": "^1.0.0-beta.3",
-    "@spree/dashboard-ui": "^1.0.0-beta.8"
+    "@spree/admin-sdk": "^1.0.0-rc.1",
+    "@spree/dashboard-ui": "^1.0.0-rc.2"
   },
   "scripts": {
     "lint": "biome check src",

package/src/components/address-form-dialog.tsx

@@ -100,6 +100,11 @@ const businessSchema = z.object({
 
 type AddressFormValues = z.infer<typeof personalSchema>
 
+/** Address rows validate on `state`; every address form binds `state_code`. */
+const ADDRESS_SERVER_FIELD_ALIASES = { state: 'state_code' } as const satisfies Partial<
+  Record<string, keyof AddressFormValues>
+>
+
 /**
  * Just the fields this dialog reads.
  *
@@ -202,6 +207,9 @@ export function AddressFormDialog({
   })
   const { errors } = form.formState
 
+  const countryCode = form.watch('country_code')
+  const { states, statesRequired } = useCountryStates(countryCode)
+
   // The parent keys the dialog on the address id so a fresh instance mounts
   // for each open, but `address` can also stream in async (loaded after the
   // sheet mounts). Reset only when the *record identity* changes — otherwise a
@@ -225,14 +233,20 @@ export function AddressFormDialog({
     form.setValue('country_code', storeDefaultCountryCode)
   }, [address?.country_code, storeDefaultCountryCode, form])
 
-  const countryCode = form.watch('country_code')
-  const { states } = useCountryStates(countryCode)
   // Show the dropdown whenever the country enumerates subdivisions, not only
   // when it strictly requires one — so a country like Pakistan still lets the
   // user pick a province instead of typing a name that may not match.
   const useStateCombobox = states.length > 0
 
   async function onSubmit(values: AddressFormValues) {
+    if (statesRequired && !values.state_code.trim()) {
+      form.setError('state_code', {
+        type: 'manual',
+        message: requiredMessage('state_code')(),
+      })
+      return
+    }
+
     try {
       await onSave({
         first_name: values.first_name,
@@ -255,7 +269,8 @@ export function AddressFormDialog({
       // Surface server-side 422 validation errors on the matching fields so
       // the dialog reflects whatever the API rejected (e.g. "phone is too
       // short"). Non-validation errors bubble to the parent's toast.
-      if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+      if (!mapSpreeErrorsToForm(err, form.setError, { fieldAliases: ADDRESS_SERVER_FIELD_ALIASES }))
+        throw err
     }
   }
 
@@ -284,6 +299,11 @@ export function AddressFormDialog({
           className="flex flex-col flex-1 overflow-hidden"
         >
           <div className="flex-1 overflow-y-auto p-4">
+            {errors.root?.message && (
+              <p className="mb-4 text-sm text-destructive" role="alert">
+                {errors.root.message}
+              </p>
+            )}
             <FieldGroup>
               {showLabel && (
                 <Field>

package/src/components/can.tsx

@@ -5,7 +5,7 @@ import { usePermissions } from '../providers/permission-provider'
 interface CanProps {
   /** Action name (e.g. "update", "destroy", "manage") */
   I: ActionName
-  /** Subject class name (e.g. "Spree::Product") */
+  /** Subject short name (e.g. "product") — see `Subject` */
   a: SubjectName
   children: ReactNode
   fallback?: ReactNode
@@ -16,7 +16,7 @@ interface CanProps {
  * can perform `I` on `a`, otherwise renders `fallback` (or nothing).
  *
  * Example:
- *   <Can I="destroy" a="Spree::Product">
+ *   <Can I="destroy" a={Subject.Product}>
  *     <Button onClick={handleDelete}>Delete</Button>
  *   </Can>
  *

package/src/components/preferences-form.tsx

@@ -170,8 +170,8 @@ export function PreferenceField({
   }
 
   // `tiers` preference (Spree::Calculator::TieredPercent /
-  // TieredFlatRate) — a Hash<threshold, value> that the default
-  // hash-as-text input would render as `[object Object]`. Render a row
+  // TieredFlatRate) — a list of `{ threshold, value }` objects that the
+  // default array input would render as `[object Object]`. Render a row
   // editor so the merchant can add tier breakpoints directly.
   if (field.key === 'tiers') {
     return <TiersEditor value={value} onChange={onChange} />
@@ -356,6 +356,11 @@ function isMaxKey(key: string): boolean {
   return /(?:^|_)max(?:imum)?(?:_|$)/.test(key)
 }
 
+interface TierValue {
+  threshold: string
+  value: string
+}
+
 interface TierRowState {
   /** Stable across edits — used for React keys so input focus survives reorder. */
   uid: string
@@ -365,21 +370,21 @@ interface TierRowState {
 
 /**
  * Editor for `Spree::Calculator::TieredPercent` / `TieredFlatRate`
- * preferences. The underlying shape is `Hash<threshold, value>` — orders
- * at or above `threshold` get `value` (% or $ depending on the
- * calculator).
+ * preferences. The underlying shape is a list of `{ threshold, value }`
+ * objects — orders at or above `threshold` get `value` (% or $ depending
+ * on the calculator).
  *
  * Owns its row list locally so the user can add an empty row and fill
- * it in afterwards — projecting to the hash on every change would drop
+ * it in afterwards — projecting to the list on every change would drop
  * empty-threshold rows the moment they're added. Empty rows are
- * filtered when projecting to the parent's hash value.
+ * filtered when projecting to the parent's value.
  */
 function TiersEditor({
   value,
   onChange,
 }: {
   value: unknown
-  onChange: (next: Record<string, number>) => void
+  onChange: (next: TierValue[]) => void
 }) {
   const { t } = useTranslation()
   const idPrefix = useId()
@@ -392,14 +397,12 @@ function TiersEditor({
 
   function commit(next: TierRowState[]) {
     setRows(next)
-    const out: Record<string, number> = {}
-    for (const row of next) {
-      const t = row.threshold.trim()
-      if (!t) continue
-      const parsed = Number(row.value)
-      out[t] = Number.isFinite(parsed) ? parsed : 0
-    }
-    onChange(out)
+    // Sent as the strings typed, so the server stores the exact decimal.
+    onChange(
+      next
+        .filter((row) => row.threshold.trim())
+        .map((row) => ({ threshold: row.threshold.trim(), value: row.value.trim() || '0' })),
+    )
   }
 
   function updateRow(uid: string, patch: Partial<Pick<TierRowState, 'threshold' | 'value'>>) {
@@ -471,6 +474,7 @@ function TierRow({
         min={0}
         value={row.threshold}
         placeholder="100"
+        aria-label={t('admin.components.preferences_form.tiers.header_threshold')}
         onChange={(e) => onChange({ threshold: e.target.value })}
       />
       <Input
@@ -479,6 +483,7 @@ function TierRow({
         min={0}
         value={row.value}
         placeholder="10"
+        aria-label={t('admin.components.preferences_form.tiers.header_value')}
         onChange={(e) => onChange({ value: e.target.value })}
       />
       <Button
@@ -495,17 +500,20 @@ function TierRow({
 }
 
 /**
- * Normalize whatever shape the server sent — typically `Hash<number,
- * number>` but JSON serialization stringifies the keys, so we may
- * receive `{ "100": 10 }` or `{ 100: 10 }`. Either form converts to
- * `TierRowState[]` for editor state.
+ * Converts the server's list of `{ threshold, value }` objects into
+ * editor rows. A calculator saved before Spree 6.0 that the upgrade has
+ * not converted yet still sends a hash keyed by threshold, so that shape
+ * is read too.
  */
 function parseTiers(value: unknown, idPrefix: string): TierRowState[] {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return []
-  return Object.entries(value as Record<string, unknown>)
+  if (!value || typeof value !== 'object') return []
+  const pairs: [unknown, unknown][] = Array.isArray(value)
+    ? value.map((tier) => [tier?.threshold, tier?.value])
+    : Object.entries(value as Record<string, unknown>)
+  return pairs
     .map(([threshold, v], i) => ({
       uid: `${idPrefix}-seed-${i}`,
-      threshold: String(threshold),
+      threshold: threshold === null || threshold === undefined ? '' : String(threshold),
       value: v === null || v === undefined ? '' : String(v),
     }))
     .sort((a, b) => Number(a.threshold) - Number(b.threshold))

package/src/components/resource-combobox.tsx

@@ -105,7 +105,10 @@ export function ResourceCombobox<T extends ComboboxOption>({
   const { data: searchData } = useQuery({
     queryKey: [queryKey, tenantId, 'search', trimmedQuery],
     queryFn: () => search(trimmedQuery),
-    staleTime: 30_000,
+    // The cache key is the picker's own, not the resource's, so a mutation
+    // elsewhere (a customer created on another page) never invalidates it.
+    // Every search refetches; cached rows for a repeated term still paint first.
+    staleTime: 0,
   })
 
   // Hydrate the currently selected ID into a record so the trigger shows

package/src/components/settings-sidebar.tsx

@@ -79,10 +79,8 @@ export function SettingsSidebar({
         // the sheet rather than an extension of the nav rail beside it, so it
         // reads as part of the page it is navigating rather than as a second
         // band of chrome.
-        'z-30 hidden h-full shrink-0 overflow-hidden bg-muted text-sidebar-foreground transition-[width,border-color] duration-200 ease-out lg:block',
-        open
-          ? 'lg:w-(--spacing-sidebar-width) border-e border-border-subtle'
-          : 'lg:w-0 border-e-0 border-transparent',
+        'z-30 hidden vh-full shrink-0 overflow-hidden bg-muted m-1.5 rounded-lg text-sidebar-foreground transition-[width,border-color] duration-200 ease-out lg:block',
+        open ? 'lg:w-(--spacing-sidebar-width)' : 'lg:w-0 border-e-0 border-transparent',
       )}
     >
       <div

package/src/components/store-switcher.tsx

@@ -62,7 +62,7 @@ export function StoreSwitcher() {
     return (
       <SidebarMenu>
         <SidebarMenuItem className="h-rail-header-height flex items-center">
-          <div className="flex w-full items-center gap-2 p-1.5">{header}</div>
+          <div className="flex w-full items-center gap-2">{header}</div>
         </SidebarMenuItem>
       </SidebarMenu>
     )

package/src/hooks/use-global-search.ts

@@ -1,5 +1,5 @@
+import { useDebouncedValue } from '@spree/dashboard-ui'
 import { useQueries } from '@tanstack/react-query'
-import { useEffect, useState } from 'react'
 import { useAuth } from '../hooks/use-auth'
 import { type SearchEntry, useSearchEntries } from '../lib/search-registry'
 import { usePermissions } from '../providers/permission-provider'
@@ -66,14 +66,3 @@ export function useGlobalSearch(rawQuery: string) {
     hasResults: groups.length > 0,
   }
 }
-
-function useDebouncedValue<T>(value: T, delayMs: number): T {
-  const [debounced, setDebounced] = useState(value)
-
-  useEffect(() => {
-    const id = setTimeout(() => setDebounced(value), delayMs)
-    return () => clearTimeout(id)
-  }, [value, delayMs])
-
-  return debounced
-}

package/src/lib/filters-to-ransack.test.ts

@@ -5,7 +5,7 @@ import type { ColumnDef, FilterRule } from './table-registry'
 const columns: ColumnDef[] = [
   { key: 'completed_at', label: 'Date', filterType: 'date' },
   { key: 'status', label: 'Status', filterType: 'enum', filterOptions: [] },
-  { key: 'tags', label: 'Tags', filterType: 'tags', taggableType: 'Spree::Product' },
+  { key: 'tags', label: 'Tags', filterType: 'tags', taggableType: 'product' },
   { key: 'sku', label: 'SKU', ransackAttribute: 'master_sku' },
   {
     key: 'companies',

package/src/lib/form-errors.ts

@@ -71,6 +71,7 @@ function hasTranslation(field: string, entry: ValidationErrorDetail): boolean {
  */
 function translatedSummary(
   details: Record<string, Array<string | ValidationErrorDetail>>,
+  fieldAliases?: Record<string, string>,
 ): string | null {
   const sentences: string[] = []
 
@@ -85,7 +86,8 @@ function translatedSummary(
       // would fall through to the server's own sentence.
       if (!hasTranslation(field, entry)) return null
 
-      sentences.push(`${attributeLabel(field)} ${resolveDetailMessage(field, entry)}`.trim())
+      const labelField = fieldAliases?.[field] ?? field
+      sentences.push(`${attributeLabel(labelField)} ${resolveDetailMessage(field, entry)}`.trim())
     }
   }
 
@@ -163,19 +165,30 @@ function attributeLabel(field: string): string {
  * the bare `base` key and any `*.base` key as record-level and route them
  * to root.
  */
+export interface MapSpreeErrorsToFormOptions<TFieldValues extends FieldValues> {
+  /**
+   * Rails attribute names that differ from the form field the input is bound
+   * to. Address validation reports on `state`; the dashboard writes
+   * `state_code`.
+   */
+  fieldAliases?: Partial<Record<string, Path<TFieldValues>>>
+}
+
 export function mapSpreeErrorsToForm<TFieldValues extends FieldValues>(
   error: unknown,
   setError: UseFormSetError<TFieldValues>,
+  options?: MapSpreeErrorsToFormOptions<TFieldValues>,
 ): boolean {
   if (!(error instanceof SpreeError)) return false
 
   const { details, message } = error
+  const fieldAliases = options?.fieldAliases as Record<string, string> | undefined
 
   // The summary banner is the line a merchant actually reads, so it follows
   // their interface language too. It is rebuilt from the translated entries
   // when every one of them translated; a single untranslated code means the
   // server's own sentence is still the more complete summary, and it stays.
-  const summary = (details && translatedSummary(details)) || message
+  const summary = (details && translatedSummary(details, fieldAliases)) || message
   if (summary) {
     setError('root' as Path<TFieldValues>, { type: 'server', message: summary })
   }
@@ -193,9 +206,11 @@ export function mapSpreeErrorsToForm<TFieldValues extends FieldValues>(
   // worse failure mode than redundant root messages.
   for (const [field, entries] of Object.entries(details)) {
     if (!entries?.length) continue
-    if (!isRenderableFieldKey(field)) continue
 
-    setError(field as Path<TFieldValues>, {
+    const formField = (fieldAliases?.[field] ?? field) as string
+    if (!isRenderableFieldKey(formField)) continue
+
+    setError(formField as Path<TFieldValues>, {
       type: 'server',
       message: entries.map((entry) => resolveDetailMessage(field, entry)).join(', '),
     })

package/src/lib/formatters.ts

@@ -11,6 +11,10 @@ export function formatStoreDateTime(iso: string, timezone: string) {
   return formatInTimeZone(parseISO(iso), timezone, 'PPP p')
 }
 
+export function formatStoreDate(iso: string, timezone: string) {
+  return formatInTimeZone(parseISO(iso), timezone, 'PP')
+}
+
 export function getInitials(fullName: string | null | undefined, fallback: string): string {
   const parts = (fullName ?? '').trim().split(/\s+/).filter(Boolean)
   if (parts.length === 0) return fallback.charAt(0)

package/src/lib/permissions.ts

@@ -1,90 +1,89 @@
 /**
- * CanCanCan subject class names — use these constants instead of raw strings
- * to avoid typos in permission checks.
+ * Permission subjects — use these constants instead of raw strings to avoid
+ * typos in permission checks.
  *
- * Matches the Ruby class names serialized by the /api/v3/admin/me endpoint.
+ * Matches the short names the `/me` endpoints serialize (`product`,
+ * `customer`), the same shorthand the rest of the API uses for types.
  */
 export const Subject = {
   All: 'all',
-  Product: 'Spree::Product',
-  ProductType: 'Spree::ProductType',
+  Product: 'product',
+  ProductType: 'product_type',
   // The media library. Authorized as product imagery — a merchant who can edit
   // products can manage the files that illustrate them.
-  Media: 'Spree::Media',
-  Variant: 'Spree::Variant',
-  Order: 'Spree::Order',
-  SavedReport: 'Spree::SavedReport',
-  ReportExport: 'Spree::Exports::Report',
-  Customer: 'Spree::Customer',
-  CustomerGroup: 'Spree::CustomerGroup',
-  AdminUser: 'Spree::AdminUser',
-  ApiKey: 'Spree::ApiKey',
-  AllowedOrigin: 'Spree::AllowedOrigin',
-  Store: 'Spree::Store',
+  Media: 'media',
+  Variant: 'variant',
+  Order: 'order',
+  SavedReport: 'saved_report',
+  ReportExport: 'report',
+  Customer: 'customer',
+  CustomerGroup: 'customer_group',
+  AdminUser: 'admin_user',
+  ApiKey: 'api_key',
+  AllowedOrigin: 'allowed_origin',
+  Store: 'store',
   // The store's packaging vocabulary: the box it ships parcels in, and the
   // cartons, pallets and containers a wholesale order leaves on.
-  PackageType: 'Spree::PackageType',
-  Channel: 'Spree::Channel',
-  OrderRoutingRule: 'Spree::OrderRoutingRule',
-  // Categories are Spree::Category < Spree::Taxon; abilities are published under
-  // the Spree::Taxon subject, so the value stays 'Spree::Taxon' while the key
-  // reads as the user-facing resource name.
-  Category: 'Spree::Taxon',
-  Collection: 'Spree::Collection',
-  OptionType: 'Spree::OptionType',
-  OptionValue: 'Spree::OptionValue',
-  Policy: 'Spree::Policy',
-  TaxCategory: 'Spree::TaxCategory',
-  TaxRate: 'Spree::TaxRate',
-  TaxIdentifier: 'Spree::TaxIdentifier',
-  TaxExemptionCertificate: 'Spree::TaxExemptionCertificate',
-  Company: 'Spree::Company',
-  CompanyAddress: 'Spree::CompanyAddress',
-  CompanyMembership: 'Spree::CompanyMembership',
-  CompanyInvitation: 'Spree::CompanyInvitation',
-  Catalog: 'Spree::Catalog',
-  ReturnReason: 'Spree::ReturnReason',
-  ClaimReason: 'Spree::ClaimReason',
-  RefundReason: 'Spree::RefundReason',
-  OrderCancellationReason: 'Spree::OrderCancellationReason',
-  CustomFieldDefinition: 'Spree::CustomFieldDefinition',
-  Integration: 'Spree::Integration',
-  PaymentMethod: 'Spree::PaymentMethod',
-  DeliveryMethod: 'Spree::DeliveryMethod',
-  DeliveryZone: 'Spree::DeliveryZone',
-  DeliveryProfile: 'Spree::DeliveryProfile',
+  PackageType: 'package_type',
+  Channel: 'channel',
+  OrderRoutingRule: 'order_routing_rule',
+  Category: 'category',
+  Collection: 'collection',
+  OptionType: 'option_type',
+  OptionValue: 'option_value',
+  Policy: 'policy',
+  TaxCategory: 'tax_category',
+  TaxRate: 'tax_rate',
+  TaxIdentifier: 'tax_identifier',
+  TaxExemptionCertificate: 'tax_exemption_certificate',
+  Company: 'company',
+  CompanyAddress: 'company_address',
+  CompanyMembership: 'company_membership',
+  CompanyInvitation: 'company_invitation',
+  Catalog: 'catalog',
+  ReturnReason: 'return_reason',
+  ClaimReason: 'claim_reason',
+  RefundReason: 'refund_reason',
+  OrderCancellationReason: 'order_cancellation_reason',
+  CustomFieldDefinition: 'custom_field_definition',
+  Integration: 'integration',
+  PaymentMethod: 'payment_method',
+  DeliveryMethod: 'delivery_method',
+  DeliveryZone: 'delivery_zone',
+  DeliveryProfile: 'delivery_profile',
   /** @deprecated Use Subject.DeliveryMethod — removed in Spree 6.1. */
-  ShippingMethod: 'Spree::ShippingMethod',
-  StockLocation: 'Spree::StockLocation',
-  StockLevel: 'Spree::StockLevel',
+  ShippingMethod: 'delivery_method',
+  StockLocation: 'stock_location',
+  StockLevel: 'stock_level',
   /** @deprecated Use Subject.StockLevel — removed in Spree 6.1. */
-  StockItem: 'Spree::StockItem',
-  StockTransfer: 'Spree::StockTransfer',
-  StockTransferItem: 'Spree::StockTransferItem',
-  Supplier: 'Spree::Supplier',
-  PurchaseOrder: 'Spree::PurchaseOrder',
-  PurchaseOrderItem: 'Spree::PurchaseOrderItem',
-  PriceList: 'Spree::PriceList',
-  PriceRule: 'Spree::PriceRule',
-  Promotion: 'Spree::Promotion',
-  PromotionAction: 'Spree::PromotionAction',
-  PromotionRule: 'Spree::PromotionRule',
-  GiftCard: 'Spree::GiftCard',
-  GiftCardBatch: 'Spree::GiftCardBatch',
-  StoreCredit: 'Spree::StoreCredit',
-  StoreCreditEvent: 'Spree::StoreCreditEvent',
-  Role: 'Spree::Role',
-  Invitation: 'Spree::Invitation',
-  Market: 'Spree::Market',
-  WebhookEndpoint: 'Spree::WebhookEndpoint',
-  WebhookDelivery: 'Spree::WebhookDelivery',
-  Wishlist: 'Spree::Wishlist',
-  Seller: 'Spree::Seller',
-  CommissionRate: 'Spree::CommissionRate',
-  CommissionRule: 'Spree::CommissionRule',
-  CommissionLine: 'Spree::CommissionLine',
-  SellerPayout: 'Spree::SellerPayout',
-  SellerTransfer: 'Spree::SellerTransfer',
+  StockItem: 'stock_level',
+  StockTransfer: 'stock_transfer',
+  StockTransferItem: 'stock_transfer_item',
+  Supplier: 'supplier',
+  PurchaseOrder: 'purchase_order',
+  PurchaseOrderItem: 'purchase_order_item',
+  PriceList: 'price_list',
+  PriceRule: 'price_rule',
+  Promotion: 'promotion',
+  PromotionAction: 'promotion_action',
+  PromotionRule: 'promotion_rule',
+  GiftCard: 'gift_card',
+  GiftCardBatch: 'gift_card_batch',
+  StoreCredit: 'store_credit',
+  StoreCreditEvent: 'store_credit_event',
+  Role: 'role',
+  Invitation: 'invitation',
+  Market: 'market',
+  WebhookEndpoint: 'webhook_endpoint',
+  EmailTemplate: 'email_template',
+  WebhookDelivery: 'webhook_delivery',
+  Wishlist: 'wishlist',
+  Seller: 'seller',
+  CommissionRate: 'commission_rate',
+  CommissionRule: 'commission_rule',
+  CommissionLine: 'commission_line',
+  SellerPayout: 'seller_payout',
+  SellerTransfer: 'seller_transfer',
 } as const
 
 export type SubjectName = (typeof Subject)[keyof typeof Subject] | string

package/src/lib/table-registry.ts

@@ -84,14 +84,12 @@ export interface ResourceFilterConfig<R extends { id: string } = { id: string }>
 }
 
 /**
- * Models that `TagCombobox` can target for tag autocomplete. The three
- * first-class taggables (Product, Customer, Order) get autocomplete hints, but
- * the union is open — apps can pass any Ruby class string the backend's
- * `TagsController#allowed_taggable_types` accepts (override that method
- * server-side to extend). Use `Subject.Product` etc. to avoid stringly-typed
- * callsites for the built-ins.
+ * Resources that `TagCombobox` can target for tag autocomplete, by API
+ * shorthand. The three first-class taggables get autocomplete hints, but the
+ * union is open — apps can pass the shorthand of any type registered in
+ * `Spree.taggable_types` on the server.
  */
-export type TaggableType = 'Spree::Product' | 'Spree::Customer' | 'Spree::Order' | (string & {})
+export type TaggableType = 'product' | 'customer' | 'order' | (string & {})
 
 /**
  * Column definition. Discriminated union on `filterType`:

package/src/locales/ar.json

@@ -1401,7 +1401,7 @@
       "create_description": "أضف مستودعًا أو متجرًا أو نقطة استلام لتلبية الطلبات منها.",
       "create_label": "إنشاء موقع المخزون",
       "delete_confirm": {
-        "message": "ستتم إزالة {{name}}. لا يتم حذف عناصر المخزون في هذا الموقع.",
+        "message": "ستتم إزالة {{name}}. سيتم حذف مستويات المخزون في هذا الموقع أيضًا.",
         "title": "هل تريد حذف موقع المخزون؟"
       },
       "edit_description": "تحديث الاسم أو العنوان أو الالتقاط أو سياسات المخزون.",
@@ -1575,6 +1575,12 @@
         "slug_placeholder": "product-url-handle"
       },
       "tax_category_placeholder": "Select tax category",
+      "tax": {
+        "apply_to_variants_help": "تنطبق هذه الفئة على كل متغير ليس له فئة ضريبة خاصة به. عند الحفظ، تستخدم هذه المتغيرات هذا الإعداد.",
+        "variant_overrides_heading": "متغيرات لها فئة ضريبة خاصة بها",
+        "variant_overrides_description": "تحتفظ هذه المتغيرات بفئتها حتى تزيل الاستثناء. تتبع بقية المتغيرات فئة المنتج أعلاه.",
+        "clear_variant_override": "استخدام فئة المنتج"
+      },
       "transfers": {
         "create_description": "انقل المخزون بين المواقع، أو استلم مخزونًا جديدًا من مورّد خارجي.",
         "delete_confirm": {

package/src/locales/de.json

@@ -1401,7 +1401,7 @@
       "create_description": "Fügen Sie ein Lager, ein Geschäft oder einen Abholpunkt hinzu, von dem aus Bestellungen abgewickelt werden.",
       "create_label": "Lagerort erstellen",
       "delete_confirm": {
-        "message": "{{name}} wird entfernt. Bestandsartikel an diesem Standort werden nicht gelöscht.",
+        "message": "{{name}} wird entfernt. Bestände an diesem Standort werden ebenfalls gelöscht.",
         "title": "Lagerort löschen?"
       },
       "edit_description": "Aktualisieren Sie Name, Adresse, Abholung oder Bestandsrichtlinien.",
@@ -1576,6 +1576,12 @@
         "slug_placeholder": "produkt-url-handle"
       },
       "tax_category_placeholder": "Steuerkategorie auswählen",
+      "tax": {
+        "apply_to_variants_help": "Diese Kategorie gilt für alle Varianten ohne eigene Steuerkategorie. Beim Speichern übernehmen diese Varianten diese Einstellung.",
+        "variant_overrides_heading": "Varianten mit eigener Steuerkategorie",
+        "variant_overrides_description": "Diese Varianten behalten ihre Kategorie, bis Sie die Ausnahme aufheben. Alle anderen Varianten folgen der Produktkategorie oben.",
+        "clear_variant_override": "Produktkategorie verwenden"
+      },
       "transfers": {
         "create_description": "Bestand zwischen Lagern bewegen oder neuen Bestand von einem externen Lieferanten annehmen.",
         "delete_confirm": {

package/src/locales/en.json

@@ -1403,7 +1403,7 @@
       "create_description": "Add a warehouse, store, or pickup point to fulfill orders from.",
       "create_label": "Create stock location",
       "delete_confirm": {
-        "message": "{{name}} will be removed. Stock levels at this location are not deleted.",
+        "message": "{{name}} will be removed. Stock levels at this location will be deleted as well.",
         "title": "Delete stock location?"
       },
       "edit_description": "Update name, address, pickup, or stock policies.",
@@ -1578,6 +1578,12 @@
         "slug_placeholder": "product-url-handle"
       },
       "tax_category_placeholder": "Select tax category",
+      "tax": {
+        "apply_to_variants_help": "This category applies to every variant that does not have its own tax category. When you save, those variants use this setting.",
+        "variant_overrides_heading": "Variants with their own tax category",
+        "variant_overrides_description": "These variants keep their category until you clear the override. All other variants follow the product category above.",
+        "clear_variant_override": "Use product category"
+      },
       "transfers": {
         "create_description": "Move stock between locations, or receive new stock from an external supplier.",
         "delete_confirm": {

package/src/locales/es.json

@@ -1064,6 +1064,12 @@
         "slug_placeholder": "url-del-producto"
       },
       "tax_category_placeholder": "Seleccionar categoría de impuestos",
+      "tax": {
+        "apply_to_variants_help": "Esta categoría se aplica a cada variante que no tenga su propia categoría fiscal. Al guardar, esas variantes usan esta configuración.",
+        "variant_overrides_heading": "Variantes con categoría fiscal propia",
+        "variant_overrides_description": "Estas variantes conservan su categoría hasta que quite la excepción. El resto siguen la categoría del producto de arriba.",
+        "clear_variant_override": "Usar categoría del producto"
+      },
       "transfers": {
         "create_description": "Mové stock entre ubicaciones o recibí stock nuevo de un proveedor externo.",
         "delete_confirm": {
@@ -1540,7 +1546,7 @@
       "create_description": "Agregá un depósito, un local o un punto de retiro desde el que cumplir pedidos.",
       "create_label": "Crear ubicación de inventario",
       "delete_confirm": {
-        "message": "{{name}} se eliminará. Los niveles de stock de esta ubicación no se borran.",
+        "message": "{{name}} se eliminará. Los niveles de stock de esta ubicación también se eliminarán.",
         "title": "¿Eliminar ubicación de inventario?"
       },
       "edit_description": "Actualizá el nombre, la dirección, el retiro o las políticas de stock.",

package/src/locales/fr.json

@@ -1401,7 +1401,7 @@
       "create_description": "Ajoutez un entrepôt, un magasin ou un point de retrait pour traiter les commandes.",
       "create_label": "Créer un emplacement de stock",
       "delete_confirm": {
-        "message": "{{name}} sera supprimé. Les articles en stock à cet emplacement ne sont pas supprimés.",
+        "message": "{{name}} sera supprimé. Les niveaux de stock à cet emplacement seront également supprimés.",
         "title": "Supprimer l'emplacement de stock ?"
       },
       "edit_description": "Mettez à jour le nom, l'adresse, le retrait ou les politiques de stock.",
@@ -1576,6 +1576,12 @@
         "slug_placeholder": "url-du-produit"
       },
       "tax_category_placeholder": "Sélectionner une catégorie de taxe",
+      "tax": {
+        "apply_to_variants_help": "Cette catégorie s'applique à chaque variante qui n'a pas sa propre catégorie de taxe. À l'enregistrement, ces variantes utilisent ce réglage.",
+        "variant_overrides_heading": "Variantes avec leur propre catégorie de taxe",
+        "variant_overrides_description": "Ces variantes conservent leur catégorie jusqu'à ce que vous supprimiez l'exception. Les autres variantes suivent la catégorie du produit ci-dessus.",
+        "clear_variant_override": "Utiliser la catégorie du produit"
+      },
       "transfers": {
         "create_description": "Déplacer du stock entre les emplacements, ou recevoir du nouveau stock d’un fournisseur externe.",
         "delete_confirm": {

package/src/locales/pl.json

@@ -1418,7 +1418,7 @@
       "create_description": "Dodaj magazyn, sklep lub punkt odbioru, z którego będą realizowane zamówienia.",
       "create_label": "Utwórz lokalizację magazynową",
       "delete_confirm": {
-        "message": "{{name}} zostanie usunięta. Produkty na stanie w tej lokalizacji nie zostaną usunięte.",
+        "message": "{{name}} zostanie usunięta. Poziomy zapasów w tej lokalizacji również zostaną usunięte.",
         "title": "Usunąć lokalizację magazynową?"
       },
       "edit_description": "Zaktualizuj nazwę, adres, odbiór lub zasady dotyczące zapasów.",
@@ -1597,6 +1597,12 @@
         "slug_placeholder": "adres-url-produktu"
       },
       "tax_category_placeholder": "Wybierz kategorię podatkową",
+      "tax": {
+        "apply_to_variants_help": "Ta kategoria dotyczy każdego wariantu bez własnej kategorii podatkowej. Po zapisaniu te warianty korzystają z tego ustawienia.",
+        "variant_overrides_heading": "Warianty z własną kategorią podatkową",
+        "variant_overrides_description": "Te warianty zachowują swoją kategorię, dopóki nie usuniesz wyjątku. Pozostałe warianty stosują kategorię produktu powyżej.",
+        "clear_variant_override": "Użyj kategorii produktu"
+      },
       "transfers": {
         "create_description": "Przenieś zapasy między lokalizacjami lub przyjmij nowy towar od zewnętrznego dostawcy.",
         "delete_confirm": {

package/src/locales/zh-CN.json

@@ -1401,7 +1401,7 @@
       "create_description": "添加仓库、门店或自提点，用于履行订单。",
       "create_label": "创建库存地点",
       "delete_confirm": {
-        "message": "{{name}} 将被移除。此地点的库存项不会被删除。",
+        "message": "{{name}} 将被移除。此地点的库存水平也将被删除。",
         "title": "删除库存地点？"
       },
       "edit_description": "更新名称、地址、自提或库存策略。",
@@ -1575,6 +1575,12 @@
         "slug_placeholder": "product-url-handle"
       },
       "tax_category_placeholder": "选择税务类别",
+      "tax": {
+        "apply_to_variants_help": "此分类适用于未设置专属税务分类的每个变体。保存后，这些变体将使用此设置。",
+        "variant_overrides_heading": "已设置专属税务分类的变体",
+        "variant_overrides_description": "这些变体将保留其分类，直到您清除覆盖。其他变体遵循上方的产品分类。",
+        "clear_variant_override": "使用产品分类"
+      },
       "transfers": {
         "create_description": "在库存地点之间调拨库存，或从外部供应商收货。",
         "delete_confirm": {

package/src/pages/settings-index.tsx

@@ -88,7 +88,7 @@ function SettingsCard({ entry, tenantId }: { entry: SettingsNavEntry; tenantId:
   const description = resolveNavDescription(entry, t)
 
   return (
-    <Card className="p-0 transition-colors hover:bg-accent/80 hover:border-border">
+    <Card className="p-0 transition-colors border-border-subtle hover:bg-accent/80 hover:border-border">
       {/* The whole card is the target — a small title-only link would fail the
           44px minimum on touch and leaves most of the card dead to a click. */}
       {/* Paths come from a runtime registry plugins extend, so they can't be

package/src/products/product-form-cards.tsx

@@ -24,6 +24,8 @@ import {
   useOptionalStore,
 } from '@spree/dashboard-core'
 import {
+  Alert,
+  AlertDescription,
   Button,
   Card,
   CardAction,
@@ -59,6 +61,7 @@ import {
   FolderTreeIcon,
   ImageIcon,
   ImagePlusIcon,
+  InfoIcon,
   LibraryIcon,
   Loader2Icon,
   PencilIcon,
@@ -69,12 +72,20 @@ import {
   WarehouseIcon,
 } from '@spree/dashboard-ui/icons'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { type Control, Controller, type UseFormReturn, useWatch } from 'react-hook-form'
+import {
+  type Control,
+  Controller,
+  type UseFormReturn,
+  useFormState,
+  useWatch,
+} from 'react-hook-form'
 import { useTranslation } from 'react-i18next'
 import { AddVideoDialog } from './add-video-dialog'
 import { InventorySection } from './inventory-section'
 import { MediaEditSheet } from './media-edit-sheet'
 import { ProductBulkPriceEditor } from './product-bulk-price-editor'
+import { variantHasTaxCategoryOverride } from './product-form-mapping'
+import type { VariantFormValues } from './product-schema'
 import type {
   PanelMedia as Media,
   PanelProduct as Product,
@@ -969,13 +980,31 @@ export function CategorizationCard({ form }: FormCardProps) {
       .filter(Boolean)
   }, [selectedProductType?.option_type_labels, selectedProductType?.option_type_ids, optionTypes])
 
+  // Seed type categories only when the merchant picks or changes the product
+  // type — not when an existing product opens and the type record loads async.
+  const previousProductTypeIdRef = useRef<string | null | undefined>(undefined)
+
   useEffect(() => {
     // Only where the panel files products at all: a seller's client registers
     // no categories, so seeding them would dirty the form with ids their API
     // drops on save — an unsaved-changes prompt over a field they cannot see.
     if (!client.categories) return
 
-    const categoryIds = selectedProductType?.category_ids
+    const currentTypeId = selectedProductTypeId ?? null
+
+    if (previousProductTypeIdRef.current === undefined) {
+      previousProductTypeIdRef.current = currentTypeId
+      return
+    }
+
+    if (!currentTypeId || selectedProductType?.id !== currentTypeId) return
+
+    const typeChanged = previousProductTypeIdRef.current !== currentTypeId
+    if (!typeChanged) return
+
+    previousProductTypeIdRef.current = currentTypeId
+
+    const categoryIds = selectedProductType.category_ids
     if (!categoryIds?.length) return
 
     const current = (form.getValues('category_ids') as string[] | undefined) ?? []
@@ -983,7 +1012,7 @@ export function CategorizationCard({ form }: FormCardProps) {
     if (missing.length === 0) return
 
     form.setValue('category_ids', [...current, ...missing], { shouldDirty: true })
-  }, [selectedProductType, form, client.categories])
+  }, [selectedProductTypeId, selectedProductType, form, client.categories])
   // Automatic collections rebuild their members from rules, so a hand-picked
   // membership would be dropped on the next regeneration — offer manual only.
   // Memoized: `initialItems` feeds a useEffect + useMemo inside
@@ -1128,7 +1157,7 @@ export function CategorizationCard({ form }: FormCardProps) {
               control={form.control}
               render={({ field }) => (
                 <TagCombobox
-                  taggableType="Spree::Product"
+                  taggableType="product"
                   value={field.value ?? []}
                   onChange={field.onChange}
                 />
@@ -1149,6 +1178,27 @@ export function TaxCard({ form }: FormCardProps) {
   const { t } = useTranslation()
   const { data: taxCategoriesResponse } = useTaxCategories()
   const taxCategories = taxCategoriesResponse?.data ?? []
+  const variants = useWatch({ control: form.control, name: 'variants' }) ?? []
+  const { dirtyFields } = useFormState({ control: form.control, name: 'tax_category_id' })
+  const showApplyToVariantsNotice = Boolean(dirtyFields.tax_category_id) && variants.length > 1
+  const overrides = useMemo(
+    () =>
+      variants
+        .map((variant, index) => ({ variant, index }))
+        .filter(({ variant }) => variantHasTaxCategoryOverride(variant)),
+    [variants],
+  )
+
+  const clearVariantTaxOverride = (variantIndex: number) => {
+    form.setValue(`variants.${variantIndex}.tax_category_id`, null, { shouldDirty: true })
+  }
+
+  const labelForVariant = (variant: VariantFormValues) => {
+    if (variant.options.length > 0) {
+      return variant.options.map((option) => `${option.name}: ${option.value}`).join(', ')
+    }
+    return variant.sku?.trim() || t('admin.products.variants.default_variant')
+  }
 
   return (
     <Card>
@@ -1158,7 +1208,7 @@ export function TaxCard({ form }: FormCardProps) {
           {t('admin.fields.tax.label')}
         </CardTitle>
       </CardHeader>
-      <CardContent>
+      <CardContent className="space-y-4">
         <Field>
           <FieldLabel>{t('admin.fields.tax_category_id.label')}</FieldLabel>
           <Controller
@@ -1185,6 +1235,48 @@ export function TaxCard({ form }: FormCardProps) {
             )}
           />
         </Field>
+
+        {showApplyToVariantsNotice && (
+          <Alert variant="info">
+            <InfoIcon />
+            <AlertDescription>{t('admin.products.tax.apply_to_variants_help')}</AlertDescription>
+          </Alert>
+        )}
+
+        {overrides.length > 0 && (
+          <div className="rounded-md border bg-muted/30 p-3 text-sm">
+            <p className="font-medium">{t('admin.products.tax.variant_overrides_heading')}</p>
+            <p className="text-muted-foreground mt-1">
+              {t('admin.products.tax.variant_overrides_description')}
+            </p>
+            <ul className="mt-3 space-y-2">
+              {overrides.map(({ variant, index }) => {
+                const categoryName =
+                  taxCategories.find((c) => c.id === variant.tax_category_id)?.name ??
+                  variant.tax_category_id
+                return (
+                  <li
+                    key={variant.id ?? `variant-tax-${index}`}
+                    className="flex flex-wrap items-center justify-between gap-2"
+                  >
+                    <span>
+                      {labelForVariant(variant)}
+                      <span className="text-muted-foreground"> — {categoryName}</span>
+                    </span>
+                    <Button
+                      type="button"
+                      variant="outline"
+                      size="sm"
+                      onClick={() => clearVariantTaxOverride(index)}
+                    >
+                      {t('admin.products.tax.clear_variant_override')}
+                    </Button>
+                  </li>
+                )
+              })}
+            </ul>
+          </div>
+        )}
       </CardContent>
     </Card>
   )

package/src/products/product-form-mapping.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest'
-import { variantToFormValues, variantToWirePayload } from './product-form-mapping'
+import {
+  prepareVariantsTaxForProductSave,
+  variantHasTaxCategoryOverride,
+  variantToFormValues,
+  variantToWirePayload,
+} from './product-form-mapping'
+import type { VariantFormValues } from './product-schema'
 import type { PanelVariant } from './product-types'
 
 // variantToFormValues reads a handful of fields; cast a minimal fixture rather
@@ -70,3 +76,56 @@ describe('variantToFormValues prices', () => {
     expect(values.prices).toEqual([])
   })
 })
+
+describe('variant tax category overrides', () => {
+  const baseVariant = (): VariantFormValues => ({
+    id: 'variant_1',
+    sku: 'SKU-1',
+    barcode: null,
+    position: 0,
+    options: [],
+    weight: null,
+    height: null,
+    width: null,
+    depth: null,
+    weight_unit: null,
+    dimensions_unit: null,
+    hs_code: null,
+    country_of_origin: null,
+    customs_description: null,
+    minimum_order_quantity: null,
+    order_multiple: null,
+    purchase_unit: null,
+    units_per_carton: null,
+    cartons_per_pallet: null,
+    carton_weight: null,
+    carton_package_type_id: null,
+    track_inventory: true,
+    preorderable: false,
+    preorder_ships_at: null,
+    backorder_limit: null,
+    tax_category_id: null,
+    prices: [],
+    stock_levels: [],
+  })
+
+  it('detects a stored override', () => {
+    expect(variantHasTaxCategoryOverride({ ...baseVariant(), tax_category_id: 'taxcat_1' })).toBe(
+      true,
+    )
+    expect(variantHasTaxCategoryOverride(baseVariant())).toBe(false)
+  })
+
+  it('clears inheriting variants and keeps overrides on save prep', () => {
+    const variants = [
+      { ...baseVariant(), tax_category_id: null },
+      { ...baseVariant(), id: 'variant_2', tax_category_id: 'taxcat_override' },
+    ]
+
+    const prepared = prepareVariantsTaxForProductSave(variants, 'taxcat_product')
+
+    expect(prepared[0].tax_category_id).toBeNull()
+    expect(prepared[1].tax_category_id).toBe('taxcat_override')
+    expect(variantToWirePayload(prepared[0], 0).tax_category_id).toBeNull()
+  })
+})

package/src/products/product-form-mapping.ts

@@ -162,6 +162,27 @@ export function productToFormValues(
 // `index` is the variant's array position; we ship `index + 1` so
 // `acts_as_list` persists the 1-indexed order. Form state stays 0-indexed
 // (matches the React array), the API quirk lives only at this boundary.
+/** Variants with a non-null tax category id carry their own category on save. */
+export function variantHasTaxCategoryOverride(variant: VariantFormValues): boolean {
+  return variant.tax_category_id != null && variant.tax_category_id !== ''
+}
+
+/**
+ * Before PATCH, keep overrides as-is and leave inheriting variants at null so
+ * the product-level tax category applies through Variant#tax_category.
+ */
+export function prepareVariantsTaxForProductSave(
+  variants: VariantFormValues[],
+  _productTaxCategoryId: string | null | undefined,
+): VariantFormValues[] {
+  return variants.map((variant) => {
+    if (variantHasTaxCategoryOverride(variant)) {
+      return variant
+    }
+    return { ...variant, tax_category_id: null }
+  })
+}
+
 export function variantToWirePayload(v: VariantFormValues, index: number) {
   // DB columns `sku` and `weight` are NOT NULL with defaults ("", 0.0).
   // The other scalar fields (barcode, dimensions, weight_unit,

package/src/providers/permission-provider.tsx

@@ -121,7 +121,13 @@ export function PermissionProvider({ children }: { children: ReactNode }) {
   // forever. Depend on the tenant id (a string) and rebuild the key inside.
   const tenantId = useTenantId()
   const refresh = useCallback(async () => {
-    await queryClient.invalidateQueries({ queryKey: [PERMISSIONS_RESOURCE, tenantId] })
+    const permissionsKey = [PERMISSIONS_RESOURCE, tenantId]
+    // A refresh asks for the rules as they stand now. A first fetch still in
+    // flight was sent before — in the seller panel, before any seller was
+    // chosen — and with nothing cached TanStack hands that same fetch back
+    // rather than starting another, so it is cancelled first.
+    await queryClient.cancelQueries({ queryKey: permissionsKey })
+    await queryClient.invalidateQueries({ queryKey: permissionsKey })
   }, [queryClient, tenantId])
 
   const permissions = useMemo(

package/src/vite/discover.ts

@@ -125,6 +125,27 @@ export function discoverDashboardPlugins({ root, onWarn }: DiscoverOptions): str
   return discovered
 }
 
+/**
+ * The routes directory of an installed dashboard shell (`@spree/dashboard`,
+ * `@spree/seller-dashboard`), at its real location. The shell's `.` export
+ * maps to a file in `src/`, so `routes/` is its sibling directory.
+ *
+ * The route generator imports these files from the host's `routeTree.gen.ts`.
+ * Under pnpm a package is reached through a `node_modules/<name>` link, while
+ * its own dependencies sit next to its real location under
+ * `node_modules/.pnpm/`. TypeScript does not follow the link for a relative
+ * import, so a route file imported through it cannot see the shell's
+ * dependencies and the host's type check fails. Plugin routes directories
+ * resolve to their real location for the same reason.
+ *
+ * @param root host project root
+ * @param packageName the shell package the host depends on
+ */
+export function resolveShellRoutesDir(root: string, packageName: string): string {
+  const require = createRequire(path.join(root, 'package.json'))
+  return path.join(path.dirname(fs.realpathSync(require.resolve(packageName))), 'routes')
+}
+
 interface HostManifest {
   dependencies?: Record<string, string>
   devDependencies?: Record<string, string>