@spree/dashboard-core 1.0.0-rc.2 → 1.0.0-rc.4

package/src/components/resource-table.tsx

@@ -56,6 +56,7 @@ import {
 import { createPortal } from 'react-dom'
 import { useTranslation } from 'react-i18next'
 import { z } from 'zod/v4'
+import { runtimeListParams } from '../api-client'
 import { useAuth } from '../hooks/use-auth'
 import { useVisualViewportOffset } from '../hooks/use-visual-viewport-offset'
 import { filtersToRansack } from '../lib/filters-to-ransack'
@@ -176,8 +177,11 @@ interface ResourceTableProps<T> {
    * `[webhookDeliveriesTableKey(endpointId)]`).
    */
   queryKey: string | readonly unknown[]
-  /** Function that calls the SDK to fetch data */
-  queryFn: (params: Record<string, unknown>) => Promise<{ data: T[]; meta: PaginationMeta }>
+  /**
+   * Function that calls the SDK to fetch data. Its params are built at runtime
+   * from the table's columns and filters, so any typed SDK list method fits.
+   */
+  queryFn: (params: never) => Promise<{ data: T[]; meta: PaginationMeta }>
   /** Current search params from the route */
   searchParams: ResourceSearch
   /** Title displayed in the toolbar header. Overrides the table definition's title. */
@@ -401,7 +405,7 @@ export function ResourceTable<T extends Record<string, any>>({
 
       Object.assign(params, filtersToRansack(filters as FilterRule[], allColumns))
 
-      return queryFn(params)
+      return queryFn(runtimeListParams(params))
     },
     enabled: !!token,
   })

package/src/components/table-toolbar.tsx

@@ -1177,17 +1177,19 @@ function InlineValueList({
     }))
   }, [isCurrency, currencies, isTags, tags.data, resources.data, column.filterResource, query])
 
-  // Selected values ride at the top so a choice made before searching does not
-  // disappear the moment the query stops matching it.
+  // Values already selected when the list opens ride at the top, so an active
+  // filter is visible without scrolling. The set is frozen at mount: ticking a
+  // box must not move rows under the pointer.
+  const [pinned] = useState(() => selected)
   const ordered = useMemo(() => {
-    const chosen = options.filter((option) => selected.includes(option.value))
-    const rest = options.filter((option) => !selected.includes(option.value))
+    const chosen = options.filter((option) => pinned.includes(option.value))
+    const rest = options.filter((option) => !pinned.includes(option.value))
     // Not truncated: a list cut at ten looks like a list of ten, and a
     // vocabulary of forty tags would silently lose thirty with nothing on
     // screen to say so. The container scrolls instead, so the scrollbar
     // reports how much more there is — and searching narrows it.
     return [...chosen, ...rest]
-  }, [options, selected])
+  }, [options, pinned])
 
   if (!isCurrency && (tags.isLoading || resources.isLoading)) {
     return (
@@ -1507,6 +1509,7 @@ function FilterPanel({
             behind the panel is already showing the result. */}
         {field && multi && column && (
           <InlineValueList
+            key={column.key}
             column={column}
             tenantId={tenantId}
             query={query}

package/src/hooks/use-display-name.ts

@@ -4,7 +4,7 @@ import { useTranslation } from 'react-i18next'
 /**
  * Resolves a code to its display name via `Intl.DisplayNames`, localized to a
  * given UI language. Returns `undefined` when the runtime lacks coverage so
- * callers can apply their own fallback (the API name, the raw code, etc.).
+ * callers can apply their own fallback (usually the raw code).
  *
  * Standalone (non-hook) variant for module-level use outside React.
  */
@@ -25,7 +25,7 @@ export function intlDisplayName(
  * type (`currency`, `language`, `region`, …), localized to the **admin UI
  * language** (`i18n.language`) — NOT the store's content locale — so names
  * match the rest of the dashboard chrome. Returns `undefined` on a miss; the
- * caller supplies the fallback (e.g. `?? code`, `?? country.name`).
+ * caller supplies the fallback (e.g. `?? code`).
  */
 export function useDisplayName(type: Intl.DisplayNamesType) {
   const { i18n: instance } = useTranslation()
@@ -37,6 +37,14 @@ export function useDisplayName(type: Intl.DisplayNamesType) {
     } catch {
       formatter = undefined
     }
-    return (code: string) => formatter?.of(code)
+    // `of` throws a RangeError for a malformed code (a legacy `english`), so
+    // such a code reads as unnamed rather than breaking the page.
+    return (code: string) => {
+      try {
+        return formatter?.of(code)
+      } catch {
+        return undefined
+      }
+    }
   }, [locale, type])
 }

package/src/hooks/use-file-upload.ts

@@ -0,0 +1,51 @@
+import { useMutation } from '@tanstack/react-query'
+import { getApiClient } from '../api-client'
+
+interface UploadResult {
+  signedId: string
+  previewUrl: string
+}
+
+// Active Storage's Disk service issues an absolute URL against the Rails
+// origin (e.g. http://localhost:3000/rails/active_storage/disk/...). In dev the
+// SPA runs on a different port and that controller doesn't speak CORS, so the
+// browser blocks the cross-origin PUT before any response ("Failed to fetch").
+// When the URL points at a `/rails/active_storage/` path we drop the host so
+// the request goes through Vite's `/rails` proxy and stays same-origin.
+// Production storage URLs are untouched.
+function sameOriginIfRailsDisk(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.pathname.startsWith('/rails/active_storage/')) {
+      return parsed.pathname + parsed.search
+    }
+    return url
+  } catch {
+    return url
+  }
+}
+
+interface FileUploadOptions {
+  /**
+   * `private` for files only ever served through an authorized link
+   * (documents, imports, digital products). Attaching a file never moves it
+   * between storage services, so this has to be decided up front.
+   */
+  visibility?: 'public' | 'private'
+}
+
+export function useFileUpload(options: FileUploadOptions = {}) {
+  return useMutation({
+    mutationFn: async (file: File): Promise<UploadResult> => {
+      const uploadFile = getApiClient().uploadFile
+      if (!uploadFile) throw new Error('This panel cannot upload files.')
+
+      const { signed_id } = await uploadFile(file, {
+        visibility: options.visibility ?? 'public',
+        resolveUploadUrl: sameOriginIfRailsDisk,
+      })
+
+      return { signedId: signed_id, previewUrl: URL.createObjectURL(file) }
+    },
+  })
+}

package/src/hooks/use-import.ts

@@ -90,12 +90,12 @@ function imports() {
 /** Create-time parameters beyond the ones every import shares. */
 export type ImportCreateExtras = Omit<
   PanelImportCreateParams,
-  'type' | 'attachment' | 'preferred_delimiter' | 'results_url'
+  'type' | 'attachment_signed_id' | 'delimiter' | 'results_url'
 >
 
 export interface CreateImportInput {
   type: string
-  /** Signed blob id of the already direct-uploaded CSV (see `FileUploadField`). */
+  /** The `signed_id` of the already uploaded CSV (see `FileUploadField`). */
   signedId: string
   preferredDelimiter?: PanelImportDelimiter
   /**
@@ -111,7 +111,7 @@ export interface CreateImportInput {
 }
 
 /**
- * Creates the import from a direct-uploaded CSV; the response is in the
+ * Creates the import from an uploaded CSV; the response is in the
  * `mapping` state and carries the mapping payload.
  */
 export function useCreateImport() {
@@ -128,8 +128,8 @@ export function useCreateImport() {
       imports().create({
         ...params,
         type,
-        attachment: signedId,
-        preferred_delimiter: preferredDelimiter,
+        attachment_signed_id: signedId,
+        delimiter: preferredDelimiter,
         // The import-done email deep-links back to the wizard (`?import=<id>`
         // appended server-side). Only honored when this origin is on the
         // store's allowed-origins list.

package/src/hooks/use-money-locale.ts

@@ -0,0 +1,14 @@
+import { useTranslation } from 'react-i18next'
+
+/**
+ * The locale money is shown and typed in: the dashboard language of the person
+ * using it, whatever the currency or market. Someone who writes `1.234,56`
+ * types that for dollars too, and the field reads it back the same way it
+ * displayed it. The API only ever receives canonical `"1234.56"`.
+ *
+ * @returns a BCP 47 locale such as `de` or `en`
+ */
+export function useMoneyLocale(): string {
+  const { i18n } = useTranslation()
+  return i18n.language || 'en'
+}

package/src/index.ts

@@ -33,6 +33,7 @@ export * from './components/locale-select'
 export * from './components/market-combobox'
 export * from './components/media-picker-sheet'
 export * from './components/mobile-top-bar'
+export * from './components/money'
 export * from './components/nav-main'
 export * from './components/page-header'
 export * from './components/page-tabs'
@@ -62,12 +63,13 @@ export * from './hooks/use-auto-collapse-sidebar'
 export * from './hooks/use-command-palette'
 export * from './hooks/use-countries'
 export * from './hooks/use-custom-fields'
-export * from './hooks/use-direct-upload'
 export * from './hooks/use-display-name'
 export * from './hooks/use-export'
+export * from './hooks/use-file-upload'
 export * from './hooks/use-global-search'
 export * from './hooks/use-host-form'
 export * from './hooks/use-import'
+export * from './hooks/use-money-locale'
 export * from './hooks/use-package-types'
 export * from './hooks/use-resource-mutation'
 export * from './hooks/use-stock-locations'
@@ -79,6 +81,7 @@ export * from './lib/create-action-registry'
 // Registries — pluggable extension points (nav, route, slot, table,
 // settings-nav, form fields, custom field components)
 // ---------------------------------------------------------------------------
+export * from './lib/currency-parts'
 export * from './lib/custom-field-components'
 export * from './lib/date-presets'
 export * from './lib/delivery-form'
@@ -98,12 +101,16 @@ export * from './lib/fulfillment-items'
 // `i18n.addResourceBundle`) get it via the named re-export.
 export * from './lib/i18n'
 export * from './lib/import-types'
+export * from './lib/iso-codes'
 export * from './lib/label-upload-form'
+export * from './lib/money'
 export * from './lib/nav-registry'
+export * from './lib/normalize-money'
 export * from './lib/permissions'
 export * from './lib/progress'
 export * from './lib/query-client'
 export * from './lib/query-keys'
+export * from './lib/return-refunds'
 export * from './lib/route-registry'
 export * from './lib/search-registry'
 export * from './lib/settings-nav-registry'
@@ -118,9 +125,7 @@ export * from './pages/stock-locations'
 // Plugin facade — re-exported for convenience; same API as `/plugin` subpath
 // ---------------------------------------------------------------------------
 export * from './plugin'
-export * from './products/currency-parts'
 export * from './products/normalize-customs'
-export * from './products/normalize-money'
 export * from './products/normalize-quantity'
 export * from './products/product-form-cards'
 export * from './products/product-form-mapping'

package/src/lib/currencies.ts

@@ -1,15 +1,34 @@
+import { CurrencyCode } from '@spree/admin-sdk'
+
+// Replaced currencies Spree still accepts so orders priced in them stay
+// valid, but which no merchant should pick for new pricing.
+const RETIRED_CURRENCY_CODES: ReadonlySet<string> = new Set([
+  'BYR',
+  'CUC',
+  'EEK',
+  'HRK',
+  'LTL',
+  'LVL',
+  'MRO',
+  'MTL',
+  'SKK',
+  'SLL',
+  'STD',
+  'TMM',
+  'VEF',
+  'ZMK',
+  'ZWD',
+  'ZWL',
+  'ZWN',
+  'ZWR',
+])
+
 /**
- * Every ISO 4217 currency code the runtime knows about — the active-currency
- * counterpart to the Rails admin's `Money::Currency.table` list. Used for
- * contexts where the merchant can pick *any* currency (a market's currency)
- * rather than one the store already supports. Degrades to an empty list on
- * runtimes without `Intl.supportedValuesOf`, so callers fall back to
- * `supported_currencies`.
+ * Every currency Spree accepts that is still in use. Used for contexts where
+ * the merchant can pick *any* currency (a market's currency) rather than one
+ * the store already supports. The list ships with the SDK, so a currency a
+ * newer server adds appears once the dashboard is upgraded with it.
  */
-export const ALL_CURRENCY_CODES: string[] = (() => {
-  try {
-    return Intl.supportedValuesOf('currency')
-  } catch {
-    return []
-  }
-})()
+export const ALL_CURRENCY_CODES: readonly CurrencyCode[] = Object.values(CurrencyCode).filter(
+  (code) => !RETIRED_CURRENCY_CODES.has(code),
+)

package/src/lib/form-mappers.ts

@@ -1,3 +1,4 @@
+import type { CountryCode } from '@spree/admin-sdk'
 import type { PanelAccountParams } from '../api-client'
 
 /**
@@ -91,7 +92,7 @@ export function editableAddressToStockLocationParams(values: {
   address2?: string | null
   city?: string | null
   postal_code?: string | null
-  country_code?: string | null
+  country_code?: CountryCode | null
   state_code?: string | null
   phone?: string | null
 }) {
@@ -135,12 +136,31 @@ export function accountFormToParams(values: {
     first_name: values.first_name ?? undefined,
     last_name: values.last_name ?? undefined,
     selected_locale: blankToUndefined(values.selected_locale),
-    ...avatarParam(values.avatar_signed_id, values.avatar_cleared),
+    ...signedIdParam('avatar', values.avatar_signed_id, values.avatar_cleared),
   }
 }
 
-function avatarParam(signedId: string | null, cleared: boolean) {
-  if (signedId) return { avatar: signedId }
-  if (cleared) return { avatar: null }
+/**
+ * The write for one attachment slot, under the API's `<slot>_signed_id` name:
+ * a fresh upload sends its signed id, an explicit clear sends `null` to remove
+ * the file, and an untouched field is left out entirely.
+ */
+export function signedIdParam<Slot extends string>(
+  slot: Slot,
+  signedId: string | null | undefined,
+): Partial<Record<`${Slot}_signed_id`, string>>
+export function signedIdParam<Slot extends string>(
+  slot: Slot,
+  signedId: string | null | undefined,
+  cleared: boolean | undefined,
+): Partial<Record<`${Slot}_signed_id`, string | null>>
+export function signedIdParam<Slot extends string>(
+  slot: Slot,
+  signedId: string | null | undefined,
+  cleared?: boolean,
+): Partial<Record<`${Slot}_signed_id`, string | null>> {
+  const key = `${slot}_signed_id` as `${Slot}_signed_id`
+  if (signedId) return { [key]: signedId } as Record<`${Slot}_signed_id`, string>
+  if (cleared) return { [key]: null } as Record<`${Slot}_signed_id`, null>
   return {}
 }

package/src/lib/formatters.ts

@@ -1,10 +1,40 @@
-import type { Price } from '@spree/admin-sdk'
+import { formatMoney, type Price } from '@spree/admin-sdk'
 import { parseISO } from 'date-fns'
 import { formatInTimeZone } from 'date-fns-tz'
+import i18n from 'i18next'
 
-export function formatPrice(price: Pick<Price, 'amount' | 'currency' | 'display_amount'> | null) {
-  if (!price) return '—'
-  return price.display_amount ?? `${price.currency} ${price.amount}`
+export { formatMoney }
+
+/**
+ * A price's amount in its currency, in the admin's own number format. A unit
+ * price keeps a fraction of a cent. `display_amount` is accepted and ignored
+ * so callers built against the old shape keep compiling.
+ */
+export function formatPrice(
+  price: (Pick<Price, 'amount' | 'currency'> & { display_amount?: string | null }) | null,
+  locale: string = i18n.language || 'en',
+) {
+  if (!price?.amount || !price.currency) return '—'
+  return formatMoney(price.amount, price.currency, locale, { unitPrice: true })
+}
+
+/**
+ * Formats an API amount (a decimal string) in its currency, falling back to
+ * the bare number for a currency `Intl` does not know, and to `fallback` when
+ * either is missing.
+ */
+export function formatAmount(
+  amount: string | null | undefined,
+  currency: string | null | undefined,
+  locale?: string,
+  fallback = '—',
+): string {
+  if (amount === null || amount === undefined || amount === '' || !currency) return fallback
+  try {
+    return formatMoney(amount, currency, locale) || fallback
+  } catch {
+    return `${amount} ${currency}`
+  }
 }
 
 export function formatStoreDateTime(iso: string, timezone: string) {

package/src/lib/fulfillment-items.test.ts

@@ -14,7 +14,8 @@ function lineItem(overrides: Partial<GroupableLineItem> = {}): GroupableLineItem
     options_text: 'Blue / M',
     quantity: 2,
     thumbnail_url: 'https://example.test/shirt.jpg',
-    display_price: '$10.00',
+    price: '10.00',
+    currency: 'USD',
     ...overrides,
   }
 }

package/src/lib/fulfillment-items.ts

@@ -1,3 +1,6 @@
+import i18n from 'i18next'
+import { formatMoney } from './formatters'
+
 /**
  * Which line items sit in which fulfillment, and which units nobody has
  * claimed yet. The order payload describes the two halves separately —
@@ -14,8 +17,8 @@ export interface GroupableLineItem {
   options_text?: string | null
   quantity: number
   thumbnail_url?: string | null
-  display_price?: string | null
-  display_total?: string | null
+  price?: string | null
+  currency?: string | null
 }
 
 /** The fulfillment-item fields the grouping reads. */
@@ -130,7 +133,10 @@ function buildRow(
     name: copy?.name ?? fallback?.name ?? '',
     optionsText: copy?.options_text ?? fallback?.options_text ?? null,
     thumbnailUrl: copy?.thumbnail_url ?? null,
-    displayPrice: copy?.display_price ?? null,
+    displayPrice:
+      copy?.price && copy.currency
+        ? formatMoney(copy.price, copy.currency, i18n.language || 'en', { unitPrice: true })
+        : null,
     quantity,
   }
 }

package/src/lib/i18n.ts

@@ -10,7 +10,7 @@ import en from '../locales/en.json'
 // made anywhere is honored on the next paint.
 export const ADMIN_LOCALE_STORAGE_KEY = 'spree-admin-locale'
 
-// Marks the locale key as auto-applied from a store's `preferred_admin_locale`
+// Marks the locale key as auto-applied from a store's `admin_locale`
 // (vs an explicit choice). Holds the storeId whose default is currently in
 // effect, so crossing into a different store can re-apply that store's default
 // while a genuine choice (switcher/profile/login) still wins everywhere. Mirrors
@@ -69,10 +69,10 @@ function readStoredLocale(): string {
 }
 
 /**
- * Reconcile the admin UI language against a store's `preferred_admin_locale`
+ * Reconcile the admin UI language against a store's `admin_locale`
  * fallback (legacy `base_controller` parity), for an admin with no genuine
  * personal choice. Encodes the precedence:
- *   account selected_locale > genuine stored choice > store preferred_admin_locale > 'en'
+ *   account selected_locale > genuine stored choice > store admin_locale > 'en'
  *
  * No-op when a higher tier owns the language (an account locale, or a genuine
  * stored choice — locale key set without an auto-marker). Otherwise drives the
@@ -83,7 +83,7 @@ function readStoredLocale(): string {
  *   - already matching → nothing changes.
  * Reloads (via the boot path) only when the displayed language actually changes.
  *
- * @param code        the store's current `preferred_admin_locale`
+ * @param code        the store's current `admin_locale`
  * @param storeId     the store being entered
  * @param accountLocale  the account's `selected_locale` (null when unset)
  * @param supported   locale codes the dashboard ships a bundle for

package/src/lib/iso-codes.ts

@@ -0,0 +1,47 @@
+import type { CountryCode, CurrencyCode, LocaleCode } from '@spree/admin-sdk'
+import i18n from 'i18next'
+import { z } from 'zod/v4'
+
+/**
+ * Whether a value has the shape of an ISO 3166-1 alpha-2 country code.
+ *
+ * Shape only: the connected server holds the authoritative list and rejects
+ * a code it does not know, while the SDK's `CountryCode` list is fixed when it
+ * is built. Checking against that copy would hide or reject a code an older or
+ * newer server accepts. This is the one place a plain string becomes a
+ * `CountryCode`.
+ */
+export function isCountryCode(value: unknown): value is CountryCode {
+  return typeof value === 'string' && /^[A-Z]{2}$/.test(value)
+}
+
+/** Whether a value has the shape of an ISO 4217 currency code. See `isCountryCode`. */
+export function isCurrencyCode(value: unknown): value is CurrencyCode {
+  return typeof value === 'string' && /^[A-Z]{3}$/.test(value)
+}
+
+/**
+ * Whether a value has the shape of a locale code: an ISO 639-1 language,
+ * optionally with a region (`en`, `pt-BR`, `es-419`). See `isCountryCode`.
+ */
+export function isLocaleCode(value: unknown): value is LocaleCode {
+  return typeof value === 'string' && /^[a-z]{2,3}(-[A-Z0-9]{2,3})?$/.test(value)
+}
+
+/**
+ * A required country field. A form that allows leaving it blank widens it
+ * with `.or(z.literal(''))` and sends `value || null` (or `|| undefined`).
+ */
+export const countryCodeSchema = z.custom<CountryCode>(isCountryCode, {
+  error: () => i18n.t('admin.validation.country_required'),
+})
+
+/** A required currency field. See `countryCodeSchema`. */
+export const currencyCodeSchema = z.custom<CurrencyCode>(isCurrencyCode, {
+  error: () => i18n.t('admin.validation.currency_required'),
+})
+
+/** A required locale field. See `countryCodeSchema`. */
+export const localeCodeSchema = z.custom<LocaleCode>(isLocaleCode, {
+  error: () => i18n.t('admin.validation.locale_required'),
+})

package/src/lib/money.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import {
+  fractionToPercent,
+  isPositiveMoney,
+  percentOf,
+  percentToFraction,
+  prorateMoney,
+  shiftDecimalPoint,
+} from './money'
+
+describe('shiftDecimalPoint', () => {
+  it('moves the point exactly, without float noise', () => {
+    expect(shiftDecimalPoint('0.077', 2)).toBe('7.7')
+    expect(shiftDecimalPoint('7.7', -2)).toBe('0.077')
+    expect(shiftDecimalPoint('0.07', 2)).toBe('7')
+    expect(shiftDecimalPoint('1', 2)).toBe('100')
+    expect(shiftDecimalPoint('100', -2)).toBe('1')
+    expect(shiftDecimalPoint('-0.5', 2)).toBe('-50')
+    expect(shiftDecimalPoint('0', -2)).toBe('0')
+  })
+
+  it('leaves a value that is not a decimal string alone', () => {
+    expect(shiftDecimalPoint('abc', 2)).toBe('abc')
+  })
+})
+
+describe('fractionToPercent / percentToFraction', () => {
+  it('round-trips and keeps blanks blank', () => {
+    expect(fractionToPercent('0.23')).toBe('23')
+    expect(percentToFraction('23')).toBe('0.23')
+    expect(percentToFraction('7.25')).toBe('0.0725')
+    expect(fractionToPercent(null)).toBe('')
+    expect(percentToFraction('')).toBe('')
+  })
+})
+
+describe('percentOf', () => {
+  it('rounds to the currency decimals', () => {
+    expect(percentOf('19.99', '10', 'USD')).toBe('2.00')
+    expect(percentOf('100', '12.5', 'USD')).toBe('12.50')
+    expect(percentOf('1000', '0.05', 'JPY')).toBe('1')
+    expect(percentOf('1.005', '50', 'KWD')).toBe('0.503')
+  })
+})
+
+describe('isPositiveMoney', () => {
+  it('is true only for an amount above zero', () => {
+    expect(isPositiveMoney('0.01')).toBe(true)
+    expect(isPositiveMoney('0.00')).toBe(false)
+    expect(isPositiveMoney('-1')).toBe(false)
+    expect(isPositiveMoney(null)).toBe(false)
+    expect(isPositiveMoney('abc')).toBe(false)
+  })
+})
+
+describe('prorateMoney', () => {
+  it('shares an amount across units, rounded to the currency', () => {
+    expect(prorateMoney('10.00', 1, 3, 'USD')).toBe('3.33')
+    expect(prorateMoney('10.00', 2, 3, 'USD')).toBe('6.67')
+    expect(prorateMoney('10.00', 3, 3, 'USD')).toBe('10.00')
+    expect(prorateMoney('1000', 1, 3, 'JPY')).toBe('333')
+  })
+})