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

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

@@ -1,24 +1,7 @@
 import { useMemo } from 'react'
 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 (usually the raw code).
- *
- * Standalone (non-hook) variant for module-level use outside React.
- */
-export function intlDisplayName(
-  type: Intl.DisplayNamesType,
-  locale: string,
-  code: string,
-): string | undefined {
-  try {
-    return new Intl.DisplayNames([locale, 'en'], { type }).of(code)
-  } catch {
-    return undefined
-  }
-}
+export { intlDisplayName } from '@spree/core'
 
 /**
  * Hook returning a memoized `code -> name` resolver for one `Intl.DisplayNames`

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

@@ -1,3 +1,4 @@
+import type { FileUploadVisibility } from '@spree/core'
 import { useMutation } from '@tanstack/react-query'
 import { getApiClient } from '../api-client'
 
@@ -31,7 +32,7 @@ interface FileUploadOptions {
    * (documents, imports, digital products). Attaching a file never moves it
    * between storage services, so this has to be decided up front.
    */
-  visibility?: 'public' | 'private'
+  visibility?: FileUploadVisibility
 }
 
 export function useFileUpload(options: FileUploadOptions = {}) {

package/src/hooks/use-import.ts

@@ -1,3 +1,4 @@
+import { IMPORT_STATUSES, subsetOf } from '@spree/core'
 import { toastManager } from '@spree/dashboard-ui'
 import {
   type QueryClient,
@@ -20,7 +21,7 @@ import { useTenantId } from '../providers/tenant-provider'
 import { useAuth } from './use-auth'
 
 /** Statuses the wizard polls through — row creation and processing. */
-const ACTIVE_STATUSES = new Set(['completed_mapping', 'processing'])
+const ACTIVE_STATUSES = subsetOf(IMPORT_STATUSES, ['completed_mapping', 'processing'])
 
 const IMPORT_POLL_INTERVAL_MS = 2000
 const ROWS_POLL_INTERVAL_MS = 5000
@@ -49,7 +50,7 @@ const IMPORT_TOUCHED_RESOURCES = [
 
 /** Whether the import's pipeline is still running (the poll's continue predicate). */
 export function isImportActive(status: string | undefined): boolean {
-  return !!status && ACTIVE_STATUSES.has(status)
+  return !!status && ACTIVE_STATUSES.includes(status)
 }
 
 /**

package/src/index.ts

@@ -11,6 +11,17 @@
 //     import { AuthProvider } from '@spree/dashboard-core/providers/auth-provider'
 //     import { useResourceMutation } from '@spree/dashboard-core/hooks/use-resource-mutation'
 
+// Money helpers from @spree/core, offered here as before for plugin authors
+export {
+  currencyParts,
+  fractionToPercent,
+  isPositiveMoney,
+  normalizeMoneyInput,
+  percentOf,
+  percentToFraction,
+  prorateMoney,
+  shiftDecimalPoint,
+} from '@spree/core'
 export * from './api-client'
 // ---------------------------------------------------------------------------
 // Admin SDK client (Vite-aware singleton; reads VITE_SPREE_API_URL at build)
@@ -81,7 +92,6 @@ 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'
@@ -103,9 +113,7 @@ 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'
@@ -115,6 +123,7 @@ export * from './lib/route-registry'
 export * from './lib/search-registry'
 export * from './lib/settings-nav-registry'
 export * from './lib/slot-registry'
+export * from './lib/store-config'
 export * from './lib/table-registry'
 export { ensureTimestampColumns } from './lib/timestamp-columns'
 export * from './lib/type-labels'
@@ -131,6 +140,7 @@ export * from './products/product-form-cards'
 export * from './products/product-form-mapping'
 export * from './products/product-schema'
 export * from './products/product-types'
+export type { SheetSaveHandler } from './products/sheet-save-handlers'
 export * from './products/use-product-form-data'
 export * from './products/variants-matrix'
 export * from './products/video-url'

package/src/lib/currencies.ts

@@ -1,34 +1,2 @@
-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 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: readonly CurrencyCode[] = Object.values(CurrencyCode).filter(
-  (code) => !RETIRED_CURRENCY_CODES.has(code),
-)
+/** @deprecated Import `ACTIVE_CURRENCY_CODES` from `@spree/core`. Removed in 6.1. */
+export { ACTIVE_CURRENCY_CODES as ALL_CURRENCY_CODES } from '@spree/core'

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 {