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

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,3 +1,6 @@
+import type { CurrencyCode } from '@spree/admin-sdk'
+import { isCurrencyCode } from './iso-codes'
+
 /**
  * Every ISO 4217 currency code the runtime knows about — the active-currency
  * counterpart to the Rails admin's `Money::Currency.table` list. Used for
@@ -6,9 +9,9 @@
  * runtimes without `Intl.supportedValuesOf`, so callers fall back to
  * `supported_currencies`.
  */
-export const ALL_CURRENCY_CODES: string[] = (() => {
+export const ALL_CURRENCY_CODES: CurrencyCode[] = (() => {
   try {
-    return Intl.supportedValuesOf('currency')
+    return Intl.supportedValuesOf('currency').filter(isCurrencyCode)
   } catch {
     return []
   }

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,45 @@
+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 server holds the authoritative list and rejects a code it
+ * does not know, so the dashboard does not ship a second copy of it. 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')
+  })
+})

package/src/lib/money.ts

@@ -0,0 +1,99 @@
+import { compareMoney, decimalPlaces, isDecimalString, sumMoney } from '@spree/admin-sdk'
+
+/** Whether an amount is a decimal string above zero. Blank or malformed is not. */
+export function isPositiveMoney(value: string | null | undefined): boolean {
+  return isDecimalString(value) && compareMoney(value, '0') > 0
+}
+
+/**
+ * Moves the decimal point of a decimal string by whole places, exactly, and
+ * writes the result without trailing zeros ("0.077" shifted by 2 is "7.7").
+ * Anything that is not a decimal string comes back unchanged.
+ */
+export function shiftDecimalPoint(value: string, places: number): string {
+  if (!isDecimalString(value)) return value
+
+  const negative = value.startsWith('-')
+  const [whole, fraction = ''] = (negative ? value.slice(1) : value).split('.')
+  let digits = whole + fraction
+  let point = whole.length + places
+  if (point < 0) {
+    digits = '0'.repeat(-point) + digits
+    point = 0
+  }
+  digits = digits.padEnd(point, '0')
+
+  const integer = digits.slice(0, point).replace(/^0+(?=\d)/, '') || '0'
+  const decimals = digits.slice(point).replace(/0+$/, '')
+  const text = decimals ? `${integer}.${decimals}` : integer
+  return negative && /[1-9]/.test(text) ? `-${text}` : text
+}
+
+/** A fraction rate ("0.23") as the percentage a merchant reads ("23"). Blank stays blank. */
+export function fractionToPercent(fraction: string | null | undefined): string {
+  return fraction == null || fraction === '' ? '' : shiftDecimalPoint(fraction, 2)
+}
+
+/** A typed percentage ("23") as the fraction rate the API stores ("0.23"). Blank stays blank. */
+export function percentToFraction(percent: string | null | undefined): string {
+  return percent == null || percent === '' ? '' : shiftDecimalPoint(percent.trim(), -2)
+}
+
+function scaled(value: string): { units: bigint; scale: number } {
+  const negative = value.startsWith('-')
+  const [whole, fraction = ''] = (negative ? value.slice(1) : value).split('.')
+  const units = BigInt(whole + fraction)
+  return { units: negative ? -units : units, scale: fraction.length }
+}
+
+/**
+ * numerator / denominator, where the numerator carries `scale` decimals,
+ * rounded half away from zero to the currency's decimals.
+ */
+function roundToCurrency(
+  numerator: bigint,
+  scale: number,
+  denominator: bigint,
+  currency: string,
+): string {
+  const places = decimalPlaces(currency)
+  const negative = numerator < 0n !== denominator < 0n
+  let dividend = numerator < 0n ? -numerator : numerator
+  let divisor = denominator < 0n ? -denominator : denominator
+  if (scale > places) divisor *= 10n ** BigInt(scale - places)
+  else dividend *= 10n ** BigInt(places - scale)
+
+  let units = dividend / divisor
+  if ((dividend % divisor) * 2n >= divisor) units += 1n
+
+  const text = shiftDecimalPoint((negative ? -units : units).toString(), -places)
+  return sumMoney([text], currency)
+}
+
+/**
+ * A percentage of an amount, exactly, rounded half away from zero to the
+ * currency's decimals ("10" percent of "19.99" USD is "2.00").
+ */
+export function percentOf(amount: string, percent: string, currency: string): string {
+  const left = scaled(amount)
+  const right = scaled(percent)
+  // The percentage is a hundredth, so the product carries two more places.
+  return roundToCurrency(left.units * right.units, left.scale + right.scale + 2, 1n, currency)
+}
+
+/**
+ * The share of an amount that `part` of `whole` units carries ("10.00" for 1
+ * of 3 is "3.33"), rounded half away from zero to the currency's decimals.
+ */
+export function prorateMoney(
+  amount: string,
+  part: number,
+  whole: number,
+  currency: string,
+): string {
+  if (!Number.isInteger(part) || !Number.isInteger(whole) || whole === 0) {
+    throw new Error(`Cannot prorate ${part} of ${whole}`)
+  }
+  const { units, scale } = scaled(amount)
+  return roundToCurrency(units * BigInt(part), scale, BigInt(whole), currency)
+}

package/src/{products → lib}/normalize-money.ts

@@ -4,8 +4,8 @@
 // dashboard converts here, in the browser, and never relies on the server to
 // parse comma-vs-period. See docs/plans/5.5-client-side-money-normalization.md.
 //
-// The locale is the currency's display locale (its market locale, e.g. EUR →
-// `de`), so the same locale drives both display formatting and this parse.
+// The locale is the admin's own (`useMoneyLocale`), the same one the field is
+// displayed in, so a value reads back exactly as it was shown.
 
 /**
  * Derives a locale's decimal and group separators via `Intl`. `fr` groups with

package/src/lib/return-refunds.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import { paidForUnits, returnOwesNothing, returnRefundSummary } from './return-refunds'
+
+const figures = {
+  status: 'received',
+  refund_total: '20.00',
+  refunded_total: '0.00',
+}
+
+describe('returnRefundSummary', () => {
+  it('reports what is owed until money goes back', () => {
+    expect(returnRefundSummary(figures, 'USD', 'en')).toEqual({ kind: 'owed', amount: '$20.00' })
+  })
+
+  it('names the full amount when less went back than was owed', () => {
+    expect(
+      returnRefundSummary(
+        {
+          ...figures,
+          status: 'refunded',
+          refunded_total: '15.00',
+        },
+        'USD',
+        'en',
+      ),
+    ).toEqual({ kind: 'refunded_short', amount: '$15.00', total: '$20.00' })
+  })
+
+  it('reports a full refund', () => {
+    expect(
+      returnRefundSummary(
+        {
+          ...figures,
+          status: 'refunded',
+          refunded_total: '20.00',
+        },
+        'USD',
+        'en',
+      ),
+    ).toEqual({ kind: 'refunded', amount: '$20.00' })
+  })
+})
+
+describe('returnOwesNothing', () => {
+  it('is true only for a zero amount', () => {
+    expect(returnOwesNothing('0.00')).toBe(true)
+    expect(returnOwesNothing('0.01')).toBe(false)
+  })
+})
+
+describe('paidForUnits', () => {
+  it('shares the paid amount and tax across the chosen units', () => {
+    const line = { quantity: 3, discounted_amount: '9.00', additional_tax_total: '1.00' }
+    expect(paidForUnits(line, 1, 'USD')).toBe('3.33')
+    expect(paidForUnits(line, 3, 'USD')).toBe('10.00')
+  })
+
+  it('is blank when nothing is chosen or the amount is unknown', () => {
+    expect(paidForUnits({ quantity: 2, discounted_amount: '5.00' }, 0, 'USD')).toBe('')
+    expect(paidForUnits({ quantity: 2, discounted_amount: null }, 1, 'USD')).toBe('')
+  })
+})

package/src/lib/return-refunds.ts

@@ -0,0 +1,70 @@
+import { compareMoney, isDecimalString, isZeroMoney, sumMoney } from '@spree/admin-sdk'
+import { formatMoney } from './formatters'
+import { prorateMoney } from './money'
+
+/** True when a received return is owed nothing, so completing it moves no money. */
+export function returnOwesNothing(refundableTotal: string): boolean {
+  return isZeroMoney(refundableTotal)
+}
+
+export type ReturnRefundFigures = {
+  status: string
+  refund_total: string
+  refunded_total: string
+}
+
+/**
+ * What a return's card reports: what it is owed until money goes back, then
+ * what actually went back — which a merchant keeping a restocking fee makes
+ * less than it was owed, so that case also names the full amount. Money that
+ * went back counts even before the return is marked refunded: a refund that
+ * succeeded on one payment and was declined on the next leaves it received.
+ *
+ * A return carries no currency of its own, so the caller passes its order's.
+ * Without one the amounts come back as the API wrote them.
+ */
+export function returnRefundSummary(
+  returnRecord: ReturnRefundFigures,
+  currency?: string,
+  locale?: string,
+):
+  | { kind: 'owed'; amount: string }
+  | { kind: 'refunded'; amount: string }
+  | { kind: 'refunded_short'; amount: string; total: string } {
+  const format = (amount: string) => (currency ? formatMoney(amount, currency, locale) : amount)
+
+  if (returnRecord.status !== 'refunded' && isZeroMoney(returnRecord.refunded_total)) {
+    return { kind: 'owed', amount: format(returnRecord.refund_total) }
+  }
+
+  if (compareMoney(returnRecord.refunded_total || '0', returnRecord.refund_total || '0') < 0) {
+    return {
+      kind: 'refunded_short',
+      amount: format(returnRecord.refunded_total),
+      total: format(returnRecord.refund_total),
+    }
+  }
+
+  return { kind: 'refunded', amount: format(returnRecord.refunded_total) }
+}
+
+/**
+ * What the customer paid, tax included, for `quantity` units of a line — the
+ * refund a claim offers until the merchant types their own. Blank when the
+ * line's amounts are unknown.
+ */
+export function paidForUnits(
+  line: {
+    quantity: number
+    discounted_amount?: string | null
+    additional_tax_total?: string | null
+  },
+  quantity: number,
+  currency: string,
+): string {
+  if (quantity <= 0 || line.quantity <= 0 || !isDecimalString(line.discounted_amount)) return ''
+
+  const tax = isDecimalString(line.additional_tax_total) ? line.additional_tax_total : '0'
+  const paid = sumMoney([line.discounted_amount, tax])
+  return prorateMoney(paid, quantity, line.quantity, currency)
+}