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

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

@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'vitest'
+import {
+  fulfilledQuantities,
+  fulfillmentItemRows,
+  type GroupableFulfillment,
+  type GroupableLineItem,
+  unfulfilledItemRows,
+} from './fulfillment-items'
+
+function lineItem(overrides: Partial<GroupableLineItem> = {}): GroupableLineItem {
+  return {
+    id: 'li_1',
+    name: 'Shirt',
+    options_text: 'Blue / M',
+    quantity: 2,
+    thumbnail_url: 'https://example.test/shirt.jpg',
+    display_price: '$10.00',
+    ...overrides,
+  }
+}
+
+function fulfillment(overrides: Partial<GroupableFulfillment> = {}): GroupableFulfillment {
+  return {
+    status: 'pending',
+    fulfillment_items: [],
+    ...overrides,
+  }
+}
+
+describe('fulfillmentItemRows', () => {
+  it('joins a fulfillment item to its line item for the image and price', () => {
+    const rows = fulfillmentItemRows(
+      fulfillment({
+        fulfillment_items: [{ line_item_id: 'li_1', variant_id: 'variant_1', quantity: 1 }],
+      }),
+      [lineItem()],
+    )
+
+    expect(rows).toEqual([
+      {
+        key: 'li_1',
+        lineItem: expect.objectContaining({ id: 'li_1' }),
+        name: 'Shirt',
+        optionsText: 'Blue / M',
+        thumbnailUrl: 'https://example.test/shirt.jpg',
+        displayPrice: '$10.00',
+        quantity: 1,
+      },
+    ])
+  })
+
+  it('merges several fulfillment items descending from one line item', () => {
+    const rows = fulfillmentItemRows(
+      fulfillment({
+        fulfillment_items: [
+          { line_item_id: 'li_1', quantity: 1 },
+          { line_item_id: 'li_1', quantity: 2 },
+        ],
+      }),
+      [lineItem({ quantity: 3 })],
+    )
+
+    expect(rows).toHaveLength(1)
+    expect(rows[0].quantity).toBe(3)
+  })
+
+  it('falls back to the fulfillment item copy when the line item is missing', () => {
+    const rows = fulfillmentItemRows(
+      fulfillment({
+        fulfillment_items: [
+          { line_item_id: 'li_gone', name: 'Removed item', options_text: 'Red', quantity: 1 },
+        ],
+      }),
+      [],
+    )
+
+    expect(rows[0]).toMatchObject({
+      name: 'Removed item',
+      optionsText: 'Red',
+      thumbnailUrl: null,
+      displayPrice: null,
+    })
+  })
+
+  it('keys an item with no line item by its variant so it still renders', () => {
+    const rows = fulfillmentItemRows(
+      fulfillment({
+        fulfillment_items: [{ variant_id: 'variant_9', name: 'Loose unit', quantity: 1 }],
+      }),
+      [],
+    )
+
+    expect(rows).toHaveLength(1)
+    expect(rows[0].key).toBe('variant_9')
+  })
+})
+
+describe('unfulfilledItemRows', () => {
+  it('reports the quantity no fulfillment claims', () => {
+    const rows = unfulfilledItemRows(
+      [lineItem({ quantity: 5 })],
+      [fulfillment({ fulfillment_items: [{ line_item_id: 'li_1', quantity: 2 }] })],
+    )
+
+    expect(rows).toHaveLength(1)
+    expect(rows[0].quantity).toBe(3)
+  })
+
+  it('sums claims across several fulfillments', () => {
+    const rows = unfulfilledItemRows(
+      [lineItem({ quantity: 4 })],
+      [
+        fulfillment({ fulfillment_items: [{ line_item_id: 'li_1', quantity: 1 }] }),
+        fulfillment({
+          status: 'shipped',
+          fulfillment_items: [{ line_item_id: 'li_1', quantity: 2 }],
+        }),
+      ],
+    )
+
+    expect(rows[0].quantity).toBe(1)
+  })
+
+  it('returns nothing when the fulfillments account for every unit', () => {
+    const rows = unfulfilledItemRows(
+      [lineItem({ quantity: 2 })],
+      [fulfillment({ fulfillment_items: [{ line_item_id: 'li_1', quantity: 2 }] })],
+    )
+
+    expect(rows).toEqual([])
+  })
+
+  it('never reports a negative remainder', () => {
+    const rows = unfulfilledItemRows(
+      [lineItem({ quantity: 1 })],
+      [fulfillment({ fulfillment_items: [{ line_item_id: 'li_1', quantity: 3 }] })],
+    )
+
+    expect(rows).toEqual([])
+  })
+
+  it('ignores fulfillment items that reference no line item', () => {
+    const rows = unfulfilledItemRows(
+      [lineItem({ quantity: 2 })],
+      [fulfillment({ fulfillment_items: [{ variant_id: 'variant_1', quantity: 2 }] })],
+    )
+
+    expect(rows[0].quantity).toBe(2)
+  })
+})
+
+describe('fulfilledQuantities', () => {
+  it('sums units per line item across fulfilled fulfillments', () => {
+    const quantities = fulfilledQuantities([
+      fulfillment({
+        status: 'fulfilled',
+        fulfillment_items: [
+          { line_item_id: 'li_1', variant_id: 'variant_1', quantity: 1 },
+          { line_item_id: 'li_2', variant_id: 'variant_2', quantity: 2 },
+        ],
+      }),
+      fulfillment({
+        status: 'fulfilled',
+        fulfillment_items: [{ line_item_id: 'li_1', variant_id: 'variant_1', quantity: 2 }],
+      }),
+    ])
+
+    expect(quantities.get('li_1')).toBe(3)
+    expect(quantities.get('li_2')).toBe(2)
+  })
+
+  // Canceled fulfillments restock; pending ones have not shipped. Neither
+  // pins an edit.
+  it('ignores fulfillments that have not shipped', () => {
+    const quantities = fulfilledQuantities([
+      fulfillment({
+        status: 'pending',
+        fulfillment_items: [{ line_item_id: 'li_1', variant_id: 'variant_1', quantity: 2 }],
+      }),
+      fulfillment({
+        status: 'canceled',
+        fulfillment_items: [{ line_item_id: 'li_1', variant_id: 'variant_1', quantity: 1 }],
+      }),
+    ])
+
+    expect(quantities.size).toBe(0)
+  })
+
+  // Delivered is downstream of fulfilled — those units are just as gone, and
+  // treating them as available would let an edit remove goods the customer
+  // already has.
+  it('counts units in delivered fulfillments', () => {
+    const quantities = fulfilledQuantities([
+      fulfillment({
+        status: 'delivered',
+        fulfillment_items: [{ line_item_id: 'li_1', variant_id: 'variant_1', quantity: 2 }],
+      }),
+    ])
+
+    expect(quantities.get('li_1')).toBe(2)
+  })
+
+  it('skips fulfillment items that reference no line item', () => {
+    const quantities = fulfilledQuantities([
+      fulfillment({
+        status: 'fulfilled',
+        fulfillment_items: [{ line_item_id: null, variant_id: 'variant_1', quantity: 2 }],
+      }),
+    ])
+
+    expect(quantities.size).toBe(0)
+  })
+})

package/src/lib/fulfillment-items.ts

@@ -0,0 +1,171 @@
+/**
+ * Which line items sit in which fulfillment, and which units nobody has
+ * claimed yet. The order payload describes the two halves separately —
+ * `order.items` is the full basket, each fulfillment carries its own
+ * `fulfillment_items` — so the card has to join them back together to say
+ * what is being shipped where.
+ */
+
+/** The line-item fields the grouping reads. */
+export interface GroupableLineItem {
+  id: string
+  name: string
+  options_text?: string | null
+  quantity: number
+  thumbnail_url?: string | null
+  display_price?: string | null
+  display_total?: string | null
+}
+
+/** The fulfillment-item fields the grouping reads. */
+export interface GroupableFulfillmentItem {
+  line_item_id?: string | null
+  variant_id?: string | null
+  name?: string | null
+  options_text?: string | null
+  quantity: number
+}
+
+/** The fulfillment fields the grouping reads. */
+export interface GroupableFulfillment {
+  status: string
+  fulfillment_items?: GroupableFulfillmentItem[] | null
+}
+
+/**
+ * One row in a fulfillment's (or the unfulfilled group's) item list: the
+ * line item it descends from, plus how many of its units this group holds.
+ */
+export interface FulfillmentItemRow {
+  /** Stable within one group — a line item appears at most once per group. */
+  key: string
+  lineItem: GroupableLineItem | null
+  /** Falls back to the fulfillment item's own copy when the line item is gone. */
+  name: string
+  optionsText: string | null
+  thumbnailUrl: string | null
+  displayPrice: string | null
+  quantity: number
+}
+
+/**
+ * Sums, per line item, how many units every fulfillment claims. Fulfillment
+ * items that reference no line item are skipped — there is nothing to join
+ * them to, and counting them would understate the remainder.
+ */
+function claimedQuantities(fulfillments: GroupableFulfillment[]): Map<string, number> {
+  const claimed = new Map<string, number>()
+
+  for (const fulfillment of fulfillments) {
+    for (const item of fulfillment.fulfillment_items ?? []) {
+      if (!item.line_item_id) continue
+      claimed.set(item.line_item_id, (claimed.get(item.line_item_id) ?? 0) + item.quantity)
+    }
+  }
+
+  return claimed
+}
+
+/**
+ * Sums, per line item, how many units have left the merchant's hands. Those
+ * units are gone, so an edit can neither remove the row nor push its quantity
+ * below them. Delivered counts too — it is downstream of fulfilled. Canceled
+ * fulfillments restock their units and do not count.
+ */
+/**
+ * Fulfillment statuses meaning the goods have left the merchant's hands.
+ * The order-level rollup uses the same two words for "everything has gone
+ * out", so the pages gating order editing share this list.
+ */
+export const GONE_STATUSES = ['fulfilled', 'delivered']
+
+export function fulfilledQuantities(fulfillments: GroupableFulfillment[]): Map<string, number> {
+  const fulfilled = new Map<string, number>()
+
+  for (const fulfillment of fulfillments) {
+    if (!GONE_STATUSES.includes(fulfillment.status)) continue
+
+    for (const item of fulfillment.fulfillment_items ?? []) {
+      if (!item.line_item_id) continue
+      fulfilled.set(item.line_item_id, (fulfilled.get(item.line_item_id) ?? 0) + item.quantity)
+    }
+  }
+
+  return fulfilled
+}
+
+/** Builds a row, preferring the line item's own copy over the fulfillment item's. */
+function buildRow(
+  key: string,
+  lineItem: GroupableLineItem | undefined,
+  fallback: Pick<GroupableFulfillmentItem, 'name' | 'options_text'> | null,
+  quantity: number,
+): FulfillmentItemRow {
+  return {
+    key,
+    lineItem: lineItem ?? null,
+    name: lineItem?.name ?? fallback?.name ?? '',
+    optionsText: lineItem?.options_text ?? fallback?.options_text ?? null,
+    thumbnailUrl: lineItem?.thumbnail_url ?? null,
+    displayPrice: lineItem?.display_price ?? null,
+    quantity,
+  }
+}
+
+/**
+ * The items one fulfillment holds, joined to their line items for the image
+ * and the price the fulfillment item does not carry. Several fulfillment
+ * items can descend from the same line item (units split by on-hand versus
+ * backordered status), so they are merged into a single row.
+ */
+export function fulfillmentItemRows(
+  fulfillment: GroupableFulfillment,
+  lineItems: GroupableLineItem[],
+): FulfillmentItemRow[] {
+  const byId = new Map(lineItems.map((lineItem) => [lineItem.id, lineItem]))
+  const rows = new Map<string, FulfillmentItemRow>()
+
+  for (const item of fulfillment.fulfillment_items ?? []) {
+    // A fulfillment item with no line item still ships; key it by variant so
+    // it renders rather than vanishing.
+    const key = item.line_item_id ?? item.variant_id
+    if (!key) continue
+
+    const existing = rows.get(key)
+    if (existing) {
+      existing.quantity += item.quantity
+      continue
+    }
+
+    rows.set(
+      key,
+      buildRow(
+        key,
+        item.line_item_id ? byId.get(item.line_item_id) : undefined,
+        item,
+        item.quantity,
+      ),
+    )
+  }
+
+  return [...rows.values()]
+}
+
+/**
+ * Line-item units no fulfillment has claimed: the ordered quantity minus what
+ * every fulfillment holds. Only positive remainders are returned, so an order
+ * whose fulfillments account for everything yields an empty list.
+ */
+export function unfulfilledItemRows(
+  lineItems: GroupableLineItem[],
+  fulfillments: GroupableFulfillment[],
+): FulfillmentItemRow[] {
+  const claimed = claimedQuantities(fulfillments)
+
+  return lineItems.flatMap((lineItem) => {
+    const remainder = lineItem.quantity - (claimed.get(lineItem.id) ?? 0)
+    if (remainder <= 0) return []
+
+    return [buildRow(lineItem.id, lineItem, null, remainder)]
+  })
+}

package/src/lib/i18n.ts

@@ -116,8 +116,9 @@ export function reconcileStoreDefaultLocale(
 }
 
 // All non-English core bundles, imported EAGERLY so the active language has its
-// resources synchronously available (registered just after init() below) —
-// no flash, no async race with module-load `i18n.t(...)` calls.
+// resources synchronously available when init() runs below — no flash, no async
+// race with module-load `i18n.t(...)` calls, and the stored language resolves
+// to itself rather than falling back.
 const coreLocales = import.meta.glob<{ default: Record<string, unknown> }>(
   ['../locales/*.json', '!../locales/en.json'],
   { eager: true },
@@ -160,10 +161,23 @@ export function switchLocale(code: string): void {
 // after this side-effect import has settled. The `deep` + `overwrite` flags
 // merge the extension into the base namespace without dropping framework keys.
 //
-// English ships eagerly; `lng` is read from localStorage so a previously
-// chosen language is the initial language on first paint (no flash).
+// `lng` is read from localStorage so a previously chosen language is the
+// initial language on first paint (no flash).
 i18n.use(initReactI18next).init({
-  resources: { en: { translation: en } },
+  // Every bundle is registered up front. Passing `lng` with only English
+  // loaded would resolve the language to the fallback and leave
+  // `resolvedLanguage` stuck on 'en' — which reads as "the stored language
+  // never took effect" and sends the store-default reconciler into a
+  // reload loop.
+  resources: {
+    en: { translation: en },
+    ...Object.fromEntries(
+      Object.entries(coreLocales).map(([path, mod]) => [
+        path.replace('../locales/', '').replace('.json', ''),
+        { translation: mod.default },
+      ]),
+    ),
+  },
   lng: readStoredLocale(),
   fallbackLng: 'en',
   interpolation: { escapeValue: false },
@@ -176,12 +190,6 @@ i18n.use(initReactI18next).init({
     : undefined,
 })
 
-// Register the eager non-English core bundles now that i18next is initialized.
-for (const [path, mod] of Object.entries(coreLocales)) {
-  const code = path.replace('../locales/', '').replace('.json', '')
-  i18n.addResourceBundle(code, 'translation', mod.default, true, true)
-}
-
 // Reflect the active language on the root <html> element so the document
 // advertises the right `lang` (a11y, spellcheck, font selection) and `dir`
 // (RTL for Arabic/Hebrew/etc.). `i18n.dir()` consults i18next's built-in RTL

package/src/lib/import-types.ts

@@ -0,0 +1,25 @@
+import i18n from 'i18next'
+
+/**
+ * The API's type shorthand (`products`), which keys the per-type translations
+ * (`admin.imports.types.<key>`).
+ *
+ * Shorthand values pass through unchanged; the demodulizing is a fallback for
+ * `Spree::Imports::Products`-style values from an older server or a payload
+ * cached before the shorthand landed.
+ */
+export function importTypeKey(type: string | null): string {
+  return (
+    (type ?? '')
+      .split('::')
+      .pop()
+      ?.replace(/([a-z])([A-Z])/g, '$1_$2')
+      .toLowerCase() ?? ''
+  )
+}
+
+/** Translated display name for an import type (`admin.imports.types.<key>`). */
+export function importTypeLabel(type: string | null): string {
+  const key = importTypeKey(type)
+  return key ? i18n.t(`admin.imports.types.${key}`, { defaultValue: key }) : ''
+}

package/src/lib/label-upload-form.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+
+/**
+ * What a label bought outside Spree needs recording against a parcel.
+ *
+ * The carrier is free text: a forwarder's own name is as real a carrier as a
+ * registered one, and an empty value asks the server to detect one from the
+ * number.
+ */
+export const labelUploadFormSchema = z.object({
+  // Trimmed before the length check: every consumer trims before sending, so
+  // validating the raw value would let a field of spaces pass and submit
+  // blank.
+  tracking_number: z.string().trim().min(1),
+  carrier: z.string(),
+  cost: z.string(),
+})
+
+export type LabelUploadFormValues = z.infer<typeof labelUploadFormSchema>
+
+/** What a carrier label plausibly arrives as — mirrors the server allowlist. */
+export const LABEL_ACCEPT = 'application/pdf,image/png,text/plain'

package/src/lib/nav-registry.ts

@@ -1,6 +1,6 @@
 import type { LucideIcon } from 'lucide-react'
 import { type ComponentType, useSyncExternalStore } from 'react'
-import type { SubjectName } from './permissions'
+import type { ActionName, SubjectName } from './permissions'
 
 // ============================================================================
 // Types
@@ -18,8 +18,15 @@ export interface NavVisibilityContext {
 export interface NavEntry {
   /** Stable identifier — used for register/remove/update and as the React key. */
   key: string
-  /** Visible label. */
-  label: string
+  /**
+   * Visible label. Built-in entries should prefer `labelKey` so the sidebar
+   * re-renders on language change; a literal `label` is resolved once at
+   * registration and then frozen. Plugins without translation bundles of their
+   * own can still pass a literal.
+   */
+  label?: string
+  /** i18n key passed to `t(...)` at render time. Takes precedence over `label`. */
+  labelKey?: string
   /**
    * Path template, prefixed with `/$storeId` at render time. Pass paths like
    * `'/orders'`, NOT `/store_abc/orders`. The leading slash is required.
@@ -33,6 +40,13 @@ export interface NavEntry {
   position?: number
   /** CanCanCan subject required to see this item. Omit for always-visible. */
   subject?: SubjectName
+  /**
+   * Action checked against `subject`. Defaults to `'read'`. Entries for pages
+   * that only exist to *change* something should declare `'update'` — every
+   * staff member can read the store record for shell data, so a read gate on
+   * `Spree::Store` shows the item to everyone.
+   */
+  action?: ActionName
   /**
    * State-based visibility gate evaluated at render (top-level entries only),
    * e.g. hide Getting Started once the store's setup tasks are all done.
@@ -92,6 +106,52 @@ function ensureUniqueKey(key: string) {
   }
 }
 
+/**
+ * The label shape both nav registries share: a translation key, or a literal
+ * for plugins that ship no translation bundle of their own.
+ */
+export interface LabelledEntry {
+  key: string
+  label?: string
+  labelKey?: string
+}
+
+/** Throws unless the entry can produce a visible label. */
+export function ensureLabelled(entry: LabelledEntry, kind = 'Nav entry') {
+  if (!entry.label && !entry.labelKey) {
+    throw new Error(`${kind} "${entry.key}" must define either "label" or "labelKey".`)
+  }
+}
+
+/**
+ * Resolve an entry's visible label. Prefer this over inlining the ternary —
+ * the fallbacks used to disagree between call sites, so an entry registered
+ * with neither field rendered blank on one surface and its key on another.
+ *
+ * @param entry Entry from either nav registry.
+ * @param t Translation function used to resolve `labelKey`.
+ * @returns The translated label, the literal, or the key as a last resort.
+ */
+export function resolveNavLabel(entry: LabelledEntry, t: (key: string) => string): string {
+  return entry.labelKey ? t(entry.labelKey) : (entry.label ?? entry.key)
+}
+
+/** Same contract as `resolveNavLabel` for the optional description pair. */
+export function resolveNavDescription(
+  entry: { description?: string; descriptionKey?: string },
+  t: (key: string) => string,
+): string | undefined {
+  return entry.descriptionKey ? t(entry.descriptionKey) : entry.description
+}
+
+/**
+ * Whether `pathname` is `url` or sits beneath it. The `/` boundary matters:
+ * a bare `startsWith` makes `/orders` match `/orders-archive`.
+ */
+export function isPathWithin(pathname: string, url: string): boolean {
+  return pathname === url || pathname.startsWith(`${url}/`)
+}
+
 // ============================================================================
 // Public API
 // ============================================================================
@@ -99,6 +159,7 @@ function ensureUniqueKey(key: string) {
 export const nav: NavMutator = {
   add(entry) {
     ensureUniqueKey(entry.key)
+    ensureLabelled(entry)
     entries.push(entry)
     notify()
   },
@@ -111,6 +172,9 @@ export const nav: NavMutator = {
   update(key, patch) {
     const e = entries.find((x) => x.key === key)
     if (!e) throw new Error(`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 })
     Object.assign(e, patch)
     notify()
   },
@@ -118,6 +182,7 @@ export const nav: NavMutator = {
     const i = findIndex(targetKey)
     if (i === -1) throw new Error(`Nav entry "${targetKey}" not found.`)
     ensureUniqueKey(entry.key)
+    ensureLabelled(entry)
     // Inherit target's position so the relative order survives `getNavEntries`'s sort.
     const target = entries[i]
     const adjusted: NavEntry = {
@@ -131,6 +196,7 @@ export const nav: NavMutator = {
     const i = findIndex(targetKey)
     if (i === -1) throw new Error(`Nav entry "${targetKey}" not found.`)
     ensureUniqueKey(entry.key)
+    ensureLabelled(entry)
     const target = entries[i]
     const adjusted: NavEntry = {
       ...entry,
@@ -141,6 +207,7 @@ export const nav: NavMutator = {
   },
   addChild(parentKey, child) {
     const parent = requireEntry(parentKey)
+    ensureLabelled(child)
     if (parent.children?.some((c) => c.key === child.key)) {
       throw new Error(
         `Nav child "${child.key}" already exists under "${parentKey}". Use nav.updateChild().`,
@@ -168,6 +235,7 @@ export const nav: NavMutator = {
     // reference-equality memoization on the item component.
     const next = [...parent.children]
     next[idx] = { ...next[idx], ...patch }
+    ensureLabelled(next[idx])
     parent.children = next
     notify()
   },