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

package/src/lib/currency-amounts.ts

@@ -0,0 +1,172 @@
+import { isDecimalString } from '@spree/core'
+
+/**
+ * Delivery calculators whose price is a plain amount, quoted per currency
+ * through the `amounts` preference. Every other calculator (percent, tiered)
+ * is currency-neutral.
+ */
+export const AMOUNT_BASED_CALCULATORS: readonly string[] = [
+  'flat_rate',
+  'per_item',
+  'digital_delivery',
+]
+
+/** The preferences the per-currency editor owns on those calculators. */
+export const CURRENCY_AMOUNT_KEYS: readonly string[] = ['amount', 'currency', 'amounts']
+
+/**
+ * A stored preference as a decimal string. The API answers with strings; a
+ * number still sitting in preferences saved before 6.0 is read as its digits.
+ */
+function toDecimal(value: unknown): string | null {
+  const text =
+    typeof value === 'number' ? String(value) : typeof value === 'string' ? value.trim() : ''
+  return isDecimalString(text) ? text : null
+}
+
+/** One stored delivery amount and the ISO currency it was entered in. */
+export type ListedAmount = {
+  amount: string
+  currency: string
+}
+
+function amountsHash(
+  preferences: Record<string, unknown> | null | undefined,
+): Record<string, unknown> {
+  const amounts = preferences?.amounts
+  if (!amounts || typeof amounts !== 'object' || Array.isArray(amounts)) return {}
+  return amounts as Record<string, unknown>
+}
+
+function hashKey(amounts: Record<string, unknown>, currency: string): string | undefined {
+  const code = currency.toUpperCase()
+  return Object.keys(amounts).find((key) => key.toUpperCase() === code)
+}
+
+function hashEntry(amounts: Record<string, unknown>, currency: string): unknown {
+  const key = hashKey(amounts, currency)
+  return key === undefined ? undefined : amounts[key]
+}
+
+function writeHashAmount(
+  amounts: Record<string, unknown>,
+  currency: string,
+  value: string | null,
+): void {
+  const existing = hashKey(amounts, currency)
+  if (existing !== undefined) delete amounts[existing]
+  if (value !== null) amounts[currency.toUpperCase()] = value
+}
+
+/** The currency the pre-6.0 single `amount` belongs to. */
+function legacyCurrency(
+  preferences: Record<string, unknown> | null | undefined,
+  defaultCurrency: string,
+): string {
+  if (typeof preferences?.currency === 'string' && preferences.currency.trim() !== '') {
+    return preferences.currency.trim().toUpperCase()
+  }
+  return defaultCurrency.toUpperCase()
+}
+
+/** Whether the per-currency hash holds an amount: from then on it alone decides. */
+function hasAmounts(amounts: Record<string, unknown>): boolean {
+  return Object.values(amounts).some((value) => toDecimal(value) !== null)
+}
+
+/**
+ * The amount a calculator-priced method quotes for one currency — the same
+ * rule the calculator uses. Once the per-currency `amounts` hash holds an
+ * amount it alone decides; the legacy single `amount` quotes its own
+ * currency (the `currency` preference, or the store default when that
+ * preference is blank) only while the hash is empty.
+ *
+ * A pre-6.0 method that names EUR therefore returns 7 for EUR and nothing
+ * for USD.
+ */
+export function amountForCurrency(
+  preferences: Record<string, unknown> | null | undefined,
+  currency: string,
+  defaultCurrency: string,
+): string | null {
+  const code = currency.toUpperCase()
+  const amounts = amountsHash(preferences)
+  if (hasAmounts(amounts)) return toDecimal(hashEntry(amounts, code))
+
+  if (legacyCurrency(preferences, defaultCurrency) !== code) return null
+  return toDecimal(preferences?.amount)
+}
+
+/**
+ * Writes one currency's amount the way the delivery-method editor does: into
+ * the per-currency `amounts` hash, the store default like every other
+ * currency, and a cleared currency removed so the method is not offered in
+ * it.
+ *
+ * The first edit of a method priced with the legacy single `amount` moves
+ * that figure into the hash under its own currency, since the hash alone
+ * decides once it holds an amount, and clears the single amount. Amounts are
+ * written as the exact decimal string typed, which is what the API accepts.
+ */
+export function applyCurrencyAmount(
+  preferences: Record<string, unknown>,
+  currency: string,
+  raw: string,
+  defaultCurrency: string,
+): Record<string, unknown> {
+  const current = amountsHash(preferences)
+  const nextAmounts: Record<string, unknown> = hasAmounts(current) ? { ...current } : {}
+
+  if (!hasAmounts(current)) {
+    const legacy = toDecimal(preferences.amount)
+    if (legacy !== null) nextAmounts[legacyCurrency(preferences, defaultCurrency)] = legacy
+  }
+
+  writeHashAmount(nextAmounts, currency, toDecimal(raw))
+  return { ...preferences, amount: null, amounts: nextAmounts }
+}
+
+/**
+ * Whether a calculator-priced method states an amount in any currency. One
+ * without any would never be offered.
+ */
+export function hasCurrencyAmount(
+  preferences: Record<string, unknown> | null | undefined,
+): boolean {
+  return hasAmounts(amountsHash(preferences)) || toDecimal(preferences?.amount) !== null
+}
+
+/**
+ * Every amount a calculator-priced method quotes, each with the currency it
+ * belongs to. The per-currency `amounts` hash decides once it holds an
+ * amount; the legacy single `amount` stands for its own currency (the
+ * `currency` preference, or the store default) only while the hash is empty.
+ *
+ * A method priced only in a non-default currency therefore returns that
+ * currency's row, not a number that the caller would stamp with the store
+ * default's symbol.
+ */
+export function listedAmounts(
+  preferences: Record<string, unknown> | null | undefined,
+  defaultCurrency: string,
+): ListedAmount[] {
+  const listed: ListedAmount[] = []
+  const defaultCode = defaultCurrency.toUpperCase()
+
+  for (const [code, value] of Object.entries(amountsHash(preferences))) {
+    const parsed = toDecimal(value)
+    if (parsed === null) continue
+    listed.push({ amount: parsed, currency: code.toUpperCase() })
+  }
+
+  const legacyAmount = toDecimal(preferences?.amount)
+  if (listed.length === 0 && legacyAmount !== null) {
+    listed.push({ amount: legacyAmount, currency: legacyCurrency(preferences, defaultCurrency) })
+  }
+
+  return listed.sort((left, right) => {
+    if (left.currency === defaultCode) return -1
+    if (right.currency === defaultCode) return 1
+    return left.currency.localeCompare(right.currency)
+  })
+}

package/src/lib/currency-parts.ts

@@ -1,21 +1,2 @@
-// Resolve a currency code into its symbol + decimal separator under the
-// current locale, with a safe fallback for unknown/invalid currencies.
-// Shared between the server-backed BulkPriceEditor and the form-backed
-// ProductBulkPriceEditor.
-export function currencyParts(
-  currencyCode: string,
-  locale: string,
-): { symbol: string; decimal: string } {
-  try {
-    const parts = new Intl.NumberFormat(locale, {
-      style: 'currency',
-      currency: currencyCode,
-    }).formatToParts(1234.56)
-    return {
-      symbol: parts.find((p) => p.type === 'currency')?.value ?? currencyCode,
-      decimal: parts.find((p) => p.type === 'decimal')?.value ?? '.',
-    }
-  } catch {
-    return { symbol: currencyCode, decimal: '.' }
-  }
-}
+/** @deprecated Import from `@spree/core`. Removed in 6.1. */
+export { currencyParts } from '@spree/core'

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

@@ -1,3 +1,4 @@
+import { FILTER_PREDICATES } from '@spree/core'
 import { type ColumnDef, type FilterRule, parseFilterIds } from './table-registry'
 
 /**
@@ -20,7 +21,9 @@ import { type ColumnDef, type FilterRule, parseFilterIds } from './table-registr
 // `q[xxx_in][]=...` for each item. The chip stores the IDs as a CSV string
 // in `FilterRule.value` so the URL serializer (which already JSON-stringifies
 // FilterRule[]) stays simple.
-const ARRAY_OPERATORS = new Set(['in', 'not_in'])
+const ARRAY_OPERATORS = new Set<string>(
+  Object.values(FILTER_PREDICATES).flatMap((predicates) => predicates.list),
+)
 
 const NEGATING_OPERATORS = new Set(['not_in', 'not_eq'])
 

package/src/lib/form-fields-registry.ts

@@ -30,7 +30,8 @@ const registrations = new Map<string, FormFieldRegistration[]>()
 
 /**
  * Registry of extension fields per built-in form. Form keys match the form's
- * slot prefix — `'product'` for the product detail form. Registered names
+ * slot prefix — `'product'` for the product detail form, `'product.media'` and
+ * `'product.variant'` for the rows of its media and variant lists. Registered names
  * must be unique per form; duplicates throw so two plugins can't silently
  * fight over one attribute.
  */
@@ -96,6 +97,27 @@ export function extensionSubmitValues(
   return out
 }
 
+/** Names of every extension field registered on `formKey`. */
+export function extensionFieldNames(formKey: string): string[] {
+  return (registrations.get(formKey) ?? []).map((registration) => registration.name)
+}
+
+/**
+ * Extension field values carried by one row of a nested list — a media or
+ * variant row of the product form, registered under `'product.media'` /
+ * `'product.variant'`. Only keys the row actually holds are returned, so a
+ * row added after hydration (a fresh upload) sends nothing it never had.
+ */
+export function extensionRowValues(formKey: string, row: unknown): Record<string, unknown> {
+  if (!row || typeof row !== 'object') return {}
+
+  const out: Record<string, unknown> = {}
+  for (const name of extensionFieldNames(formKey)) {
+    if (name in row) out[name] = (row as Record<string, unknown>)[name]
+  }
+  return out
+}
+
 /** Test-only: clear the registry. Not exported from the package index. */
 export function __resetFormFieldsRegistry(): void {
   registrations.clear()

package/src/lib/form-mappers.ts

@@ -1,4 +1,4 @@
-import type { CountryCode } from '@spree/admin-sdk'
+import type { CountryCode } from '@spree/core'
 import type { PanelAccountParams } from '../api-client'
 
 /**

package/src/lib/formatters.ts

@@ -1,4 +1,5 @@
-import { formatMoney, type Price } from '@spree/admin-sdk'
+import type { Price } from '@spree/admin-sdk'
+import { formatMoney } from '@spree/core'
 import { parseISO } from 'date-fns'
 import { formatInTimeZone } from 'date-fns-tz'
 import i18n from 'i18next'
@@ -19,9 +20,8 @@ export function formatPrice(
 }
 
 /**
- * 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.
+ * Formats an API amount (a decimal string) in its currency, or answers
+ * `fallback` when either is missing or `Intl` cannot format the pair.
  */
 export function formatAmount(
   amount: string | null | undefined,
@@ -29,12 +29,8 @@ export function formatAmount(
   locale?: string,
   fallback = '—',
 ): string {
-  if (amount === null || amount === undefined || amount === '' || !currency) return fallback
-  try {
-    return formatMoney(amount, currency, locale) || fallback
-  } catch {
-    return `${amount} ${currency}`
-  }
+  if (!currency) return fallback
+  return formatMoney(amount, currency, locale) || fallback
 }
 
 export function formatStoreDateTime(iso: string, timezone: string) {

package/src/lib/fulfillment-items.ts

@@ -1,3 +1,4 @@
+import { ORDER_FULFILLMENT_STATUSES, subsetOf } from '@spree/core'
 import i18n from 'i18next'
 import { formatMoney } from './formatters'
 
@@ -86,6 +87,16 @@ function claimedQuantities(fulfillments: GroupableFulfillment[]): Map<string, nu
  */
 export const GONE_STATUSES = ['fulfilled', 'delivered']
 
+/** The order-level fulfillment statuses the order lists filter on. */
+export const FILTERABLE_ORDER_FULFILLMENT_STATUSES = subsetOf(ORDER_FULFILLMENT_STATUSES, [
+  'backorder',
+  'canceled',
+  'partial',
+  'unfulfilled',
+  'fulfilled',
+  'delivered',
+])
+
 export function fulfilledQuantities(fulfillments: GroupableFulfillment[]): Map<string, number> {
   const fulfilled = new Map<string, number>()
 

package/src/lib/i18n.ts

@@ -1,6 +1,6 @@
+import { localeEndonym } from '@spree/core'
 import i18n from 'i18next'
 import { initReactI18next } from 'react-i18next'
-import { intlDisplayName } from '../hooks/use-display-name'
 // Relative path, not `@/...`: dashboard-core ships source; the consuming
 // project's `@/*` alias is theirs alone (see Phase 1's rationale).
 import en from '../locales/en.json'
@@ -153,17 +153,6 @@ function localeCodesFromBundlePaths(paths: string[]): string[] {
   return ['en', ...paths.map((path) => path.replace(/^.*\/locales\//, '').replace('.json', ''))]
 }
 
-// Each language's endonym (its own name: `Deutsch`, `中文`). `Intl.DisplayNames`
-// answers in the language's own convention, so some come back lowercase
-// (`français`, `polski`); capitalize the first letter by THAT language's casing
-// rules rather than the current locale's. Scripts without case are unaffected,
-// and an unknown code falls back to itself.
-function localeEndonym(code: string): string {
-  const name = intlDisplayName('language', code, code) ?? code
-
-  return name.charAt(0).toLocaleUpperCase(code) + name.slice(1)
-}
-
 // The languages the running panel can display, as it declared them. `null`
 // until a panel does, which accepts every code — the behaviour before panels
 // declared anything.

package/src/lib/iso-codes.ts

@@ -1,32 +1,15 @@
-import type { CountryCode, CurrencyCode, LocaleCode } from '@spree/admin-sdk'
+import {
+  type CountryCode,
+  type CurrencyCode,
+  isCountryCode,
+  isCurrencyCode,
+  isLocaleCode,
+  type LocaleCode,
+} from '@spree/core'
 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)
-}
+export { isCountryCode, isCurrencyCode, isLocaleCode }
 
 /**
  * A required country field. A form that allows leaving it blank widens it

package/src/lib/money.ts

@@ -1,99 +1,9 @@
-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)
-}
+/** @deprecated Import these from `@spree/core`. Removed in 6.1. */
+export {
+  fractionToPercent,
+  isPositiveMoney,
+  percentOf,
+  percentToFraction,
+  prorateMoney,
+  shiftDecimalPoint,
+} from '@spree/core'

package/src/lib/normalize-money.ts

@@ -1,85 +1,2 @@
-// Normalize a merchant's locale-formatted money input into the canonical
-// decimal string the Admin API expects (`"1234.56"` — period decimal, no
-// grouping). Industry-standard: localization is a presentation concern, so the
-// 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 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
- * a narrow no-break space (U+202F), so we read the real characters rather than
- * assuming `,`/`.`/`" "`.
- */
-function separatorsFor(locale: string): { decimal: string; group: string } {
-  try {
-    const parts = new Intl.NumberFormat(locale, { useGrouping: true }).formatToParts(11111.1)
-    return {
-      decimal: parts.find((p) => p.type === 'decimal')?.value ?? '.',
-      group: parts.find((p) => p.type === 'group')?.value ?? '',
-    }
-  } catch {
-    return { decimal: '.', group: '' }
-  }
-}
-
-/**
- * Converts a locale-formatted amount string to a canonical decimal string.
- *
- * - `"1.234,56"` under `de` → `"1234.56"`
- * - `"1 234,56"` under `fr` → `"1234.56"` (narrow-space grouping)
- * - `"19.99"` under `en` → `"19.99"`
- * - `"19.50"` under `de` → `"19.50"` (a period can't be grouping before two digits)
- * - `""` / whitespace → `""`
- *
- * Strips the locale's group separator and any whitespace, standardizes the
- * decimal separator to `.`, and drops stray characters. Keeps the value as a
- * string throughout — never `Number()`-coerces — to preserve precision.
- *
- * @param raw the merchant's typed value
- * @param locale the display locale the value was entered in (e.g. `de`)
- * @returns canonical `"1234.56"`-form string, or `''` for blank input
- */
-export function normalizeMoneyInput(raw: string | null | undefined, locale: string): string {
-  if (raw == null) return ''
-  const trimmed = raw.trim()
-  if (trimmed === '') return ''
-
-  const { decimal, group } = separatorsFor(locale)
-
-  let out = trimmed
-  // A group separator is always followed by exactly three digits, so a lone
-  // one that is not (`19.50` under `de`) is the merchant typing the other
-  // decimal mark. `1.500` stays ambiguous and is read the locale's way.
-  const groupParts = group.trim() === '' ? [] : out.split(group)
-  if (
-    groupParts.length === 2 &&
-    !out.includes(decimal) &&
-    groupParts[1].replace(/\D/g, '').length !== 3
-  ) {
-    out = groupParts.join(decimal)
-  }
-  // Remove the locale's grouping separator (explicit char) plus any whitespace
-  // (covers narrow/no-break spaces used by some locales as the group char).
-  if (group) out = out.split(group).join('')
-  out = out.replace(/\s/g, '')
-  // Standardize the decimal separator to `.`.
-  if (decimal !== '.') out = out.split(decimal).join('.')
-  // Drop anything that isn't a digit, dot, or minus.
-  out = out.replace(/[^0-9.-]/g, '')
-
-  // Enforce the canonical shape: a single optional leading minus, then digits
-  // with at most one decimal point. Stray separators (`1.2.3`) or interior
-  // minus signs (`12-3.4`) would otherwise reach the API as malformed values.
-  const negative = out.startsWith('-')
-  const digitsAndDots = out.replace(/-/g, '')
-  const firstDot = digitsAndDots.indexOf('.')
-  const canonical =
-    firstDot === -1
-      ? digitsAndDots
-      : `${digitsAndDots.slice(0, firstDot)}.${digitsAndDots.slice(firstDot + 1).replace(/\./g, '')}`
-
-  if (canonical === '' || canonical === '.') return ''
-  return negative ? `-${canonical}` : canonical
-}
+/** @deprecated Import from `@spree/core`. Removed in 6.1. */
+export { normalizeMoneyInput } from '@spree/core'

package/src/lib/return-refunds.ts

@@ -1,6 +1,5 @@
-import { compareMoney, isDecimalString, isZeroMoney, sumMoney } from '@spree/admin-sdk'
+import { compareMoney, isDecimalString, isZeroMoney, prorateMoney, sumMoney } from '@spree/core'
 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 {

package/src/lib/route-registry.ts

@@ -183,6 +183,35 @@ export function matchPluginRoute(
   return null
 }
 
+/**
+ * Whether a registry route outranks the file route the router matched for the
+ * same URL, so it renders in that route's place. The router sends
+ * `/sellers/shopify` to `/sellers/$sellerId`, never to the catch-all, which
+ * would leave a plugin page under a first-party section unreachable.
+ *
+ * Uses the router's own ranking: segment by segment, a fixed segment beats a
+ * `$param`. A registry route therefore takes over only an address where it is
+ * more specific, never a first-party page at its own path or through a
+ * pattern like `/sellers/$id`.
+ *
+ * @param pluginPath the registry route's path, relative to `/$storeId`
+ * @param routerPath the matched file route's path, relative to `/$storeId`
+ */
+export function outranksRouterMatch(pluginPath: string, routerPath: string): boolean {
+  const pluginSegments = pathSegments(pluginPath)
+  const routerSegments = pathSegments(routerPath)
+  for (const [index, pluginSegment] of pluginSegments.entries()) {
+    const pluginFixed = !pluginSegment.startsWith('$')
+    const routerFixed = !(routerSegments[index] ?? '$').startsWith('$')
+    if (pluginFixed !== routerFixed) return pluginFixed
+  }
+  return false
+}
+
+function pathSegments(path: string): string[] {
+  return path.split('/').filter(Boolean)
+}
+
 function isStoreRoute(entry: RouteEntry): entry is StoreRouteEntry {
   return entry.scope === undefined || entry.scope === 'store'
 }

package/src/lib/settings-nav-registry.ts

@@ -1,5 +1,5 @@
 import type { LucideIcon } from 'lucide-react'
-import { useSyncExternalStore } from 'react'
+import { type ComponentType, useSyncExternalStore } from 'react'
 import { ensureLabelled, resolveNavDescription, resolveNavLabel } from './nav-registry'
 import type { ActionName, SubjectName } from './permissions'
 
@@ -75,6 +75,11 @@ export interface SettingsNavEntry {
   action?: ActionName
   /** When true, the page is disabled in the sidebar with a "Soon" badge. */
   comingSoon?: boolean
+  /**
+   * Rendered after the label in the sidebar and on the settings landing page.
+   * A component — not an element — so it can call hooks and return null.
+   */
+  badge?: ComponentType
 }
 
 export interface SettingsNavGroup {