@spree/dashboard-core 0.13.0 → 1.0.0-beta.1

package/src/lib/permissions.ts

@@ -7,39 +7,84 @@
 export const Subject = {
   All: 'all',
   Product: 'Spree::Product',
+  ProductType: 'Spree::ProductType',
+  // The media library. Authorized as product imagery — a merchant who can edit
+  // products can manage the files that illustrate them.
+  Media: 'Spree::Media',
   Variant: 'Spree::Variant',
   Order: 'Spree::Order',
+  SavedReport: 'Spree::SavedReport',
+  ReportExport: 'Spree::Exports::Report',
   Customer: 'Spree::User',
   CustomerGroup: 'Spree::CustomerGroup',
   AdminUser: 'Spree::AdminUser',
   ApiKey: 'Spree::ApiKey',
   AllowedOrigin: 'Spree::AllowedOrigin',
   Store: 'Spree::Store',
+  // The store's packaging vocabulary: the box it ships parcels in, and the
+  // cartons, pallets and containers a wholesale order leaves on.
+  PackageType: 'Spree::PackageType',
   Channel: 'Spree::Channel',
   OrderRoutingRule: 'Spree::OrderRoutingRule',
   // Categories are Spree::Category < Spree::Taxon; abilities are published under
   // the Spree::Taxon subject, so the value stays 'Spree::Taxon' while the key
   // reads as the user-facing resource name.
   Category: 'Spree::Taxon',
+  Collection: 'Spree::Collection',
   OptionType: 'Spree::OptionType',
   OptionValue: 'Spree::OptionValue',
+  Policy: 'Spree::Policy',
   TaxCategory: 'Spree::TaxCategory',
-  CustomFieldDefinition: 'Spree::MetafieldDefinition',
+  TaxRate: 'Spree::TaxRate',
+  TaxIdentifier: 'Spree::TaxIdentifier',
+  TaxExemptionCertificate: 'Spree::TaxExemptionCertificate',
+  Company: 'Spree::Company',
+  CompanyAddress: 'Spree::CompanyAddress',
+  CompanyMembership: 'Spree::CompanyMembership',
+  CompanyInvitation: 'Spree::CompanyInvitation',
+  Catalog: 'Spree::Catalog',
+  ReturnReason: 'Spree::ReturnReason',
+  ClaimReason: 'Spree::ClaimReason',
+  RefundReason: 'Spree::RefundReason',
+  OrderCancellationReason: 'Spree::OrderCancellationReason',
+  CustomFieldDefinition: 'Spree::CustomFieldDefinition',
+  Integration: 'Spree::Integration',
   PaymentMethod: 'Spree::PaymentMethod',
+  DeliveryMethod: 'Spree::DeliveryMethod',
+  DeliveryZone: 'Spree::DeliveryZone',
+  DeliveryProfile: 'Spree::DeliveryProfile',
+  /** @deprecated Use Subject.DeliveryMethod — removed in Spree 6.1. */
   ShippingMethod: 'Spree::ShippingMethod',
   StockLocation: 'Spree::StockLocation',
+  StockLevel: 'Spree::StockLevel',
+  /** @deprecated Use Subject.StockLevel — removed in Spree 6.1. */
   StockItem: 'Spree::StockItem',
   StockTransfer: 'Spree::StockTransfer',
+  StockTransferItem: 'Spree::StockTransferItem',
+  Supplier: 'Spree::Supplier',
+  PurchaseOrder: 'Spree::PurchaseOrder',
+  PurchaseOrderItem: 'Spree::PurchaseOrderItem',
   PriceList: 'Spree::PriceList',
   PriceRule: 'Spree::PriceRule',
   Promotion: 'Spree::Promotion',
   PromotionAction: 'Spree::PromotionAction',
   PromotionRule: 'Spree::PromotionRule',
   GiftCard: 'Spree::GiftCard',
+  GiftCardBatch: 'Spree::GiftCardBatch',
+  StoreCredit: 'Spree::StoreCredit',
+  StoreCreditEvent: 'Spree::StoreCreditEvent',
+  Role: 'Spree::Role',
+  Invitation: 'Spree::Invitation',
   Market: 'Spree::Market',
   WebhookEndpoint: 'Spree::WebhookEndpoint',
   WebhookDelivery: 'Spree::WebhookDelivery',
   Wishlist: 'Spree::Wishlist',
+  Seller: 'Spree::Seller',
+  CommissionRate: 'Spree::CommissionRate',
+  CommissionRule: 'Spree::CommissionRule',
+  CommissionLine: 'Spree::CommissionLine',
+  SellerPayout: 'Spree::SellerPayout',
+  SellerTransfer: 'Spree::SellerTransfer',
 } as const
 
 export type SubjectName = (typeof Subject)[keyof typeof Subject] | string

package/src/lib/progress.ts

@@ -0,0 +1,18 @@
+/** A count of finished items out of a total — an onboarding checklist, say. */
+export interface ProgressCounts {
+  done: number
+  total: number
+}
+
+/**
+ * How far through a checklist something is, as a percentage for a progress bar.
+ *
+ * An empty checklist counts as complete rather than as nothing done: a
+ * marketplace that asks nothing of its sellers has no outstanding work, and
+ * `done / total` would be NaN.
+ */
+export function progressPercentage({ done, total }: ProgressCounts): number {
+  if (total <= 0) return 100
+
+  return Math.round((done / total) * 100)
+}

package/src/lib/query-keys.ts

@@ -1,26 +1,26 @@
 import type { QueryKey } from '@tanstack/react-query'
 import { useCallback } from 'react'
-import { useStore } from '../providers/store-provider'
+import { useTenantId } from '../providers/tenant-provider'
 
 /**
  * Canonical TanStack query-key shape for every dashboard resource:
  *
- *     [resource, storeId, ...rest]
+ *     [resource, tenantId, ...rest]
  *
  * Use `useResourceKey` (the hook) from inside React components to build
- * store-scoped keys — it reads `storeId` from `<StoreProvider>` so callers
- * never spell it themselves:
+ * tenant-scoped keys — it reads the id from `<TenantProvider>` (falling back
+ * to `<StoreProvider>`) so callers never spell it themselves:
  *
  *     useQuery({ queryKey: useResourceKey('channels', id), ... })
  *
- * The bare `resourceKey()` helper is the same builder without the storeId
+ * The bare `resourceKey()` helper is the same builder without the tenant id
  * dependency — keep it for non-hook contexts (tests, build-time defaults).
  *
  * Lists: `useResourceKey('channels')`
  * Singletons: `useResourceKey('channels', id)`
  * Nested: `useResourceKey('products', productId, 'variants')`
  *
- * For invalidation inside `useResourceMutation`, the storeId is auto-injected
+ * For invalidation inside `useResourceMutation`, the tenant id is auto-injected
  * — pass the logical key without it:
  *
  *     invalidate: [['channels'], ['channels', id]]
@@ -30,12 +30,12 @@ export function resourceKey(resource: string, ...rest: ReadonlyArray<unknown>):
 }
 
 /**
- * Hook variant of `resourceKey` that auto-injects the current `storeId` from
- * `<StoreProvider>`. The default way to build query keys in dashboard hooks.
+ * Hook variant of `resourceKey` that auto-injects the current tenant id from
+ * `<TenantProvider>`. The default way to build query keys in dashboard hooks.
  */
 export function useResourceKey(resource: string, ...rest: ReadonlyArray<unknown>): QueryKey {
-  const { storeId } = useStore()
-  return [resource, storeId, ...rest]
+  const tenantId = useTenantId()
+  return [resource, tenantId, ...rest]
 }
 
 /**
@@ -50,10 +50,10 @@ export function useResourceKey(resource: string, ...rest: ReadonlyArray<unknown>
  *     })
  */
 export function useResourceKeyBuilder() {
-  const { storeId } = useStore()
+  const tenantId = useTenantId()
   return useCallback(
-    (resource: string, ...rest: ReadonlyArray<unknown>): QueryKey => [resource, storeId, ...rest],
-    [storeId],
+    (resource: string, ...rest: ReadonlyArray<unknown>): QueryKey => [resource, tenantId, ...rest],
+    [tenantId],
   )
 }
 

package/src/lib/sample-csv.ts

@@ -0,0 +1,21 @@
+/**
+ * Import types that ship a populated example CSV in Spree's
+ * `core/db/sample_data`. Keyed by the API's type shorthand (`"products"`),
+ * which is also the CSV's filename stem.
+ *
+ * Only used to decide whether to render the download link — the file itself is
+ * served by each panel's own `imports/example` endpoint, which pins the URL to
+ * the installed Spree version. A type missing from this list simply hides the link;
+ * the endpoint is the authority and 404s for anything it has no example for.
+ */
+const TYPES_WITH_SAMPLE_CSV = new Set([
+  'products',
+  'customers',
+  'product_translations',
+  'price_list_prices',
+])
+
+/** Whether an import type has an example CSV to offer. */
+export function hasSampleCsv(type: string): boolean {
+  return TYPES_WITH_SAMPLE_CSV.has(type)
+}

package/src/lib/search-registry.ts

@@ -48,8 +48,12 @@ export interface SearchEntry<T = unknown> {
   getKey: (item: T) => string
   /** Render one result row's inner content (icon/thumbnail + label + badges). */
   renderRow: (item: T) => ReactNode
-  /** Resolve the destination for a clicked result, given the active store. */
-  getRoute: (item: T, storeId: string) => { to: string }
+  /**
+   * Resolve the destination for a clicked result, given the active store.
+   * `search` carries route search params — needed by resources edited in a
+   * deep-linked sheet rather than on a page of their own.
+   */
+  getRoute: (item: T, storeId: string) => { to: string; search?: Record<string, unknown> }
 }
 
 interface SearchMutator {

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

@@ -1,6 +1,7 @@
 import type { LucideIcon } from 'lucide-react'
 import { useSyncExternalStore } from 'react'
-import type { SubjectName } from './permissions'
+import { ensureLabelled, resolveNavDescription, resolveNavLabel } from './nav-registry'
+import type { ActionName, SubjectName } from './permissions'
 
 /**
  * Registry for the settings sub-shell sidebar. Mirrors `nav-registry.ts` but
@@ -22,6 +23,19 @@ export interface SettingsNavEntry {
   label?: string
   /** i18n key passed to `t(...)` at render time. Takes precedence over `label`. */
   labelKey?: string
+  /**
+   * One-line summary of what the page is for. Shown on the settings landing
+   * page under the entry's label; the sidebar ignores it.
+   */
+  description?: string
+  /** i18n key for `description`, resolved at render. Takes precedence over it. */
+  descriptionKey?: string
+  /**
+   * Extra terms that match this entry in settings search, beyond its label.
+   * Merchants search for the word they know ("VAT", "SKU", "CORS") rather than
+   * the page's name, so list those synonyms here.
+   */
+  keywords?: string[]
   /**
    * Path template, prefixed with `/$storeId/settings` at render time. Pass paths
    * like `'/general'` or `'/staff'`, NOT `/store_abc/settings/general`. The
@@ -36,6 +50,13 @@ export interface SettingsNavEntry {
   position?: number
   /** CanCanCan subject required to see this item. Omit for always-visible. */
   subject?: SubjectName
+  /**
+   * Action checked against `subject`. Defaults to `'read'`. Settings pages
+   * that only exist to *change* something (store settings, emails) should
+   * declare `'update'` — every staff member can read the store record for
+   * shell data, so a read check would show them a page they cannot use.
+   */
+  action?: ActionName
   /** When true, the page is disabled in the sidebar with a "Soon" badge. */
   comingSoon?: boolean
 }
@@ -81,9 +102,7 @@ function notify() {
 
 export const settingsNav: SettingsNavMutator = {
   add(entry) {
-    if (!entry.label && !entry.labelKey) {
-      throw new Error(`Settings nav entry "${entry.key}" must define either "label" or "labelKey".`)
-    }
+    ensureLabelled(entry, 'Settings nav entry')
     if (entries.some((e) => e.key === entry.key)) {
       throw new Error(`Settings nav entry "${entry.key}" already registered.`)
     }
@@ -99,17 +118,14 @@ export const settingsNav: SettingsNavMutator = {
   update(key, patch) {
     const e = entries.find((x) => x.key === key)
     if (!e) throw new Error(`Settings nav entry "${key}" not found.`)
+    // Validate a copy before touching the stored entry: a patch that removes
+    // both label fields must leave the registry as it was, not half-applied.
+    ensureLabelled({ ...e, ...patch }, 'Settings nav entry')
     Object.assign(e, patch)
-    // Re-validate the merged entry — the patch could remove both label fields.
-    if (!e.label && !e.labelKey) {
-      throw new Error(`Settings nav entry "${e.key}" must define either "label" or "labelKey".`)
-    }
     notify()
   },
   addGroup(group) {
-    if (!group.label && !group.labelKey) {
-      throw new Error(`Settings nav group "${group.key}" must define either "label" or "labelKey".`)
-    }
+    ensureLabelled(group, 'Settings nav group')
     if (groups.some((g) => g.key === group.key)) {
       throw new Error(`Settings nav group "${group.key}" already registered.`)
     }
@@ -150,6 +166,83 @@ export function useSettingsNav() {
   return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 }
 
+/**
+ * Whether a settings entry matches a search term. Label, description and the
+ * entry's own `keywords` all count, so the word a merchant knows ("VAT",
+ * "CORS") reaches the page named something else. Shared by the settings
+ * sidebar and the settings landing page so both filter identically.
+ *
+ * @param entry Entry to test.
+ * @param term Search text; matching is case-insensitive and ignores surrounding space.
+ * @param t Translation function used to resolve `labelKey`/`descriptionKey`.
+ * @returns True when the entry matches, or when the term is blank.
+ */
+export function settingsEntryMatches(
+  entry: SettingsNavEntry,
+  term: string,
+  t: (key: string) => string,
+): boolean {
+  const needle = term.trim().toLowerCase()
+  if (!needle) return true
+
+  const haystack = [
+    resolveNavLabel(entry, t),
+    resolveNavDescription(entry, t),
+    ...(entry.keywords ?? []),
+  ]
+  return haystack.some((value) => value?.toLowerCase().includes(needle))
+}
+
+/**
+ * Drop entries the current staff member cannot reach. Exported because the
+ * sidebar and the settings landing page must agree on what a role can see —
+ * a private copy on either surface is how one starts showing a card the other
+ * hides.
+ */
+export function filterSettingsByPermissions(
+  snapshot: SettingsNavSnapshot,
+  permissions: { can: (action: string, subject: string) => boolean },
+): SettingsNavSnapshot {
+  return regroup(snapshot, (entry) =>
+    !entry.subject ? true : permissions.can(entry.action ?? 'read', entry.subject),
+  )
+}
+
+/** Narrow the nav to entries matching the merchant's search. */
+export function filterSettingsByQuery(
+  snapshot: SettingsNavSnapshot,
+  query: string,
+  t: (key: string) => string,
+): SettingsNavSnapshot {
+  return regroup(snapshot, (entry) => settingsEntryMatches(entry, query, t))
+}
+
+/** Rebuild a snapshot from the entries passing `keep`, dropping emptied groups. */
+function regroup(
+  snapshot: SettingsNavSnapshot,
+  keep: (entry: SettingsNavEntry) => boolean,
+): SettingsNavSnapshot {
+  const groups = snapshot.groups
+    .map(({ group, entries }) => ({ group, entries: entries.filter(keep) }))
+    .filter((g) => g.entries.length > 0)
+  return { groups, all: groups.flatMap((g) => g.entries) }
+}
+
+/**
+ * Whether any settings entry is reachable for these permissions. The Settings
+ * launcher in the primary sidebar uses this so a role with no settings
+ * authority never opens an empty shell.
+ */
+export function hasVisibleSettingsEntries(permissions: unknown): boolean {
+  const can = (permissions as { can?: (action: string, subject: string) => boolean } | undefined)
+    ?.can
+  if (typeof can !== 'function') return false
+
+  return getSnapshot().all.some(
+    (entry) => !entry.subject || can(entry.action ?? 'read', entry.subject),
+  )
+}
+
 /** Test-only: clear the registry. */
 export function __resetSettingsNavRegistry(): void {
   entries.length = 0

package/src/lib/storefront.ts

@@ -0,0 +1,19 @@
+import type { Store } from '@spree/admin-sdk'
+
+/**
+ * Resolves the storefront URL to link to from admin "View store" affordances,
+ * or `null` when no storefront URL is configured.
+ *
+ * The serialized `store.url` always resolves — the backend falls back to the
+ * store's formatted URL — so gate on the explicit `preferred_storefront_url`
+ * preference: only return a link once a real storefront has been set.
+ *
+ * @param store the current store, or null/undefined while it loads
+ * @returns an absolute URL, or null when the store has no configured storefront
+ */
+export function storefrontHref(store: Store | null | undefined): string | null {
+  if (!store?.preferred_storefront_url) return null
+
+  // Best-effort: prefix with https if the URL is just a hostname.
+  return /^https?:\/\//.test(store.url) ? store.url : `https://${store.url}`
+}

package/src/lib/table-registry.ts

@@ -9,17 +9,53 @@ import { ensureTimestampColumns } from './timestamp-columns'
 interface ColumnDefBase<T = any> {
   key: string
   label: string
+  /**
+   * One sentence explaining what the column means, shown from an info icon
+   * beside the header. For a figure whose name is not self-evident — what
+   * counts as "available", which units are "reserved" — where the alternative
+   * is a merchant guessing. Leave it off a column that explains itself.
+   */
+  labelHint?: string
   sortable?: boolean
   filterable?: boolean
   default?: boolean
+  /**
+   * What a `boolean` column's two states are called, where the domain has
+   * better words than Yes and No — "Active" and "Inactive" on a catalog. The
+   * filter control then says what the rows say, instead of asking a question
+   * the column never posed. Ignored by every other filter type.
+   */
+  booleanLabels?: { true: string; false: string }
   /** Ransack attribute name if different from key (e.g., 'master_sku' for 'sku') */
   ransackAttribute?: string
+  /** Send `ransackAttribute` as a Ransack scope: bare key, no operator suffix. */
+  ransackScope?: boolean
   /** Custom cell renderer. If omitted, renders `row[key]` as text. */
   render?: (row: T) => ReactNode
+  /**
+   * `expand` value the list request needs while this column is visible
+   * (e.g. `'custom_fields'`). ResourceTable unions the values across
+   * visible columns into the `expand` query param.
+   */
+  expand?: string
   /** Cell className */
   className?: string
   /** Whether this column is displayable in the table. Set to false for filter-only columns. */
   displayable?: boolean
+  /**
+   * Surface this column as a always-visible control in the toolbar, beside the
+   * search field, instead of only inside the filter popover.
+   *
+   * For the handful of filters an operator reaches for constantly — a status,
+   * a date range — the popover costs an open, an "Add filter", a field pick, a
+   * value pick and an Apply. A quick filter is the same `FilterRule` reached in
+   * one click, so it shares the URL state, the chips and the export with
+   * everything set the long way.
+   *
+   * Only `enum`/`boolean` (multi-select) and `date` (relative presets) render
+   * one; the flag is ignored on other filter types.
+   */
+  quickFilter?: boolean
 }
 
 /**
@@ -37,6 +73,14 @@ export interface ResourceFilterConfig<R extends { id: string } = { id: string }>
   getOptionLabel: (option: R) => string
   placeholder?: string
   emptyText?: string
+  /**
+   * Fetches the whole list, for a resource small enough to show in full —
+   * a store's warehouses, its channels. The control then opens as a plain
+   * list of options instead of an empty box waiting to be typed into, and
+   * still searches once the operator types. Leave it off for anything that
+   * could run to hundreds of rows.
+   */
+  listAll?: () => Promise<{ data: R[] }>
 }
 
 /**
@@ -110,6 +154,18 @@ export interface SortOption {
 export interface TableDef<T = any> {
   key: string
   title?: string
+  /**
+   * One line under the title saying what the list is for. Worth writing for
+   * anything a merchant meets for the first time — catalogs, price lists,
+   * transfers — and worth leaving off a list that explains itself.
+   */
+  description?: string
+  /**
+   * Documentation for the feature, appended to `description` as a "Learn more"
+   * link. A path is relative to the user guide (`'catalogs'`); a full URL is
+   * used as given, so a plugin can point at its own docs.
+   */
+  docsPath?: string
   columns: ColumnDef<T>[]
   searchParam?: string
   searchPlaceholder?: string

package/src/lib/type-labels.test.ts

@@ -0,0 +1,68 @@
+import i18n from 'i18next'
+import { beforeAll, describe, expect, it } from 'vitest'
+import { permissionGroupLabel, typeDescription, typeLabel } from './type-labels'
+
+beforeAll(async () => {
+  await i18n.init({
+    lng: 'en',
+    resources: {
+      en: {
+        translation: {
+          admin: {
+            types: {
+              promotion_rule: {
+                item_total: { name: 'Item total', description: 'Order total meets these criteria' },
+                // A type whose translation names it but says nothing more.
+                first_order: { name: 'First order' },
+              },
+              permission_group: { catalog: { name: 'Catalog' } },
+            },
+          },
+        },
+      },
+    },
+  })
+})
+
+describe('typeLabel', () => {
+  it('prefers the translation over the API label', () => {
+    expect(typeLabel('promotion_rule', 'item_total', 'Item Total (from API)')).toBe('Item total')
+  })
+
+  it('falls back to the API label for a type it has no translation for', () => {
+    // The extension case: a gem ships a Ruby rule but no dashboard locales.
+    expect(typeLabel('promotion_rule', 'wishlist_count', 'Wishlist count')).toBe('Wishlist count')
+  })
+
+  it('falls back to the code when the API sends nothing usable', () => {
+    expect(typeLabel('promotion_rule', 'wishlist_count')).toBe('wishlist_count')
+    expect(typeLabel('promotion_rule', 'wishlist_count', '   ')).toBe('wishlist_count')
+  })
+})
+
+describe('typeDescription', () => {
+  it('prefers the translation over the API description', () => {
+    expect(typeDescription('promotion_rule', 'item_total', 'from API')).toBe(
+      'Order total meets these criteria',
+    )
+  })
+
+  it('falls back to the API description when only the name is translated', () => {
+    expect(typeDescription('promotion_rule', 'first_order', 'Must be their first order')).toBe(
+      'Must be their first order',
+    )
+  })
+
+  it('returns an empty string rather than the code when nothing describes the type', () => {
+    // Descriptions are optional helper copy — a bare code would read as noise.
+    expect(typeDescription('promotion_rule', 'wishlist_count')).toBe('')
+  })
+})
+
+describe('permissionGroupLabel', () => {
+  it('translates a known group and falls back for an unknown one', () => {
+    expect(permissionGroupLabel('catalog', 'Catalog (API)')).toBe('Catalog')
+    expect(permissionGroupLabel('logistics', 'Logistics')).toBe('Logistics')
+    expect(permissionGroupLabel('logistics')).toBe('logistics')
+  })
+})

package/src/lib/type-labels.ts

@@ -0,0 +1,78 @@
+import i18n from 'i18next'
+
+/**
+ * Type catalog families the Admin API exposes. Each entry on the wire carries
+ * a stable snake_case `type` code; the `label`/`description` beside it are a
+ * fallback for clients without their own translation, not the source of
+ * truth. The dashboard renders the code through its own locale files and
+ * reaches for the fallback only when it has no key — which is what an
+ * extension gem shipping a Ruby type but no dashboard locales gets.
+ */
+export type TypeFamily =
+  | 'promotion_rule'
+  | 'promotion_action'
+  | 'calculator'
+  | 'order_routing_rule'
+  | 'collection_rule'
+  | 'price_rule'
+  | 'commission_rule'
+  | 'delivery_method_rule'
+  | 'seller_requirement'
+  | 'integration'
+  | 'permission'
+
+type Facet = 'name' | 'description'
+
+function i18nKey(family: TypeFamily, code: string, facet: Facet): string {
+  return `admin.types.${family}.${code}.${facet}`
+}
+
+/**
+ * Localized name for an API type code.
+ *
+ * @param family which type catalog the code belongs to
+ * @param code the stable snake_case type code (e.g. `item_total`, `flat_rate`)
+ * @param fallback the API-provided label, used when no translation exists
+ * @returns the localized name, the fallback, or the bare code
+ */
+export function typeLabel(family: TypeFamily, code: string, fallback?: string | null): string {
+  const key = i18nKey(family, code, 'name')
+  if (i18n.exists(key)) return i18n.t(key)
+  return fallback?.trim() || code
+}
+
+/**
+ * Localized description for an API type code.
+ *
+ * Returns an empty string when neither a translation nor a fallback exists —
+ * descriptions are optional helper copy, so callers render nothing rather
+ * than a bare code.
+ *
+ * @param family which type catalog the code belongs to
+ * @param code the stable snake_case type code
+ * @param fallback the API-provided description, used when no translation exists
+ * @returns the localized description, the fallback, or an empty string
+ */
+export function typeDescription(
+  family: TypeFamily,
+  code: string,
+  fallback?: string | null,
+): string {
+  const key = i18nKey(family, code, 'description')
+  if (i18n.exists(key)) return i18n.t(key)
+  return fallback?.trim() || ''
+}
+
+/**
+ * Localized label for a group of permission catalog entries, keyed by the
+ * group code the API returns (`catalog`, `orders`, …).
+ *
+ * @param code the group code
+ * @param fallback the API-provided group label
+ * @returns the localized group label, the fallback, or the bare code
+ */
+export function permissionGroupLabel(code: string, fallback?: string | null): string {
+  const key = `admin.types.permission_group.${code}.name`
+  if (i18n.exists(key)) return i18n.t(key)
+  return fallback?.trim() || code
+}