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

package/src/hooks/use-stock-locations.ts

@@ -0,0 +1,131 @@
+import type { PaginationMeta } from '@spree/dashboard-ui'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import i18n from 'i18next'
+import {
+  getApiClient,
+  type PanelStockLocation,
+  type PanelStockLocationCreateParams,
+  type PanelStockLocationParams,
+} from '../api-client'
+import { useResourceKey, useResourceKeyBuilder } from '../lib/query-keys'
+import { useResourceMutation } from './use-resource-mutation'
+
+/**
+ * The registered panel's stock-location resource.
+ *
+ * Throws rather than answering undefined: every hook here is only reachable
+ * from the stock-locations page, and a panel that routes to it without
+ * registering the resource is misconfigured — failing at the call site says
+ * so far more clearly than five separate "cannot read property of
+ * undefined" errors.
+ */
+function resource() {
+  const stockLocations = getApiClient().stockLocations
+  if (!stockLocations) {
+    throw new Error(
+      '@spree/dashboard-core: this panel registered no `stockLocations` resource, so the ' +
+        'stock-locations page cannot load. Add one in setApiClient(), or drop the route.',
+    )
+  }
+  return stockLocations
+}
+
+interface UseStockLocationsParams {
+  page?: number
+  limit?: number
+}
+
+// API caps `limit` at 100. The page is configurable so callers with more
+// than 100 locations can paginate; the typical merchant has a handful.
+export function useStockLocations({ page = 1, limit = 100 }: UseStockLocationsParams = {}) {
+  return useQuery({
+    queryKey: useResourceKey('stock-locations', { page, limit }),
+    queryFn: () => resource().list({ page, limit }),
+  })
+}
+
+export function useStockLocation(id: string | undefined) {
+  return useQuery({
+    queryKey: useResourceKey('stock-locations', id ?? 'noop'),
+    queryFn: () => resource().get(id as string),
+    enabled: !!id,
+  })
+}
+
+export function useCreateStockLocation() {
+  return useResourceMutation<PanelStockLocation, Error, PanelStockLocationCreateParams>({
+    mutationFn: (params) => resource().create(params),
+    invalidate: [['stock-locations']],
+    successMessage: i18n.t('admin.messages.created'),
+    errorMessage: i18n.t('admin.errors.failed_to_create'),
+  })
+}
+
+export function useUpdateStockLocation(id: string) {
+  return useResourceMutation<PanelStockLocation, Error, PanelStockLocationParams>({
+    mutationFn: (params) => resource().update(id, params),
+    invalidate: [['stock-locations'], ['stock-locations', id]],
+    successMessage: i18n.t('admin.messages.updated'),
+    errorMessage: i18n.t('admin.errors.failed_to_update'),
+  })
+}
+
+/**
+ * Update variant that takes the id per call, for lists where every row writes
+ * to a different location (the pickup toggles on a delivery profile).
+ */
+export function useUpdateStockLocationById() {
+  return useResourceMutation<
+    PanelStockLocation,
+    Error,
+    { id: string; params: PanelStockLocationParams }
+  >({
+    mutationFn: ({ id, params }) => resource().update(id, params),
+    invalidate: [['stock-locations']],
+    successMessage: i18n.t('admin.messages.updated'),
+    errorMessage: i18n.t('admin.errors.failed_to_update'),
+  })
+}
+
+export function useDeleteStockLocation() {
+  const queryClient = useQueryClient()
+  const buildKey = useResourceKeyBuilder()
+
+  return useResourceMutation<void, Error, string>({
+    // Guarded: `delete` is optional on the registry, and a panel whose API
+    // does not offer it should not render the action at all.
+    mutationFn: (id) => {
+      const remove = resource().delete
+      if (!remove) throw new Error('This panel cannot delete stock locations.')
+      return remove(id)
+    },
+    invalidate: [['stock-locations']],
+    successMessage: i18n.t('admin.messages.removed'),
+    errorMessage: i18n.t('admin.errors.failed_to_delete'),
+    onSuccess: (_data, id) => {
+      // Drop the individual-resource cache so any open detail view stops
+      // showing stale data after the row is gone.
+      queryClient.removeQueries({ queryKey: buildKey('stock-locations', id) })
+    },
+  })
+}
+
+/**
+ * Whether this panel's API offers deletion at all — the operator's does, a
+ * seller's does not. Drives whether the row action is rendered, so a seller
+ * is never shown a button that cannot work.
+ */
+export function canDeleteStockLocations(): boolean {
+  return typeof getApiClient().stockLocations?.delete === 'function'
+}
+
+/**
+ * One page of locations, for `ResourceTable`'s own query. Not a hook — the
+ * table calls it with the search params it has already parsed.
+ */
+export function listStockLocations(params: Record<string, unknown>) {
+  return resource().list(params) as Promise<{
+    data: PanelStockLocation[]
+    meta: PaginationMeta
+  }>
+}

package/src/hooks/use-switch-admin-locale.ts

@@ -1,5 +1,5 @@
+import { toastManager } from '@spree/dashboard-ui'
 import { useTranslation } from 'react-i18next'
-import { toast } from 'sonner'
 import { adminClient } from '../client'
 import { i18n, markGenuineLocaleChoice, switchLocale } from '../lib/i18n'
 import { useAuth } from './use-auth'
@@ -49,7 +49,7 @@ export function useSwitchAdminLocale() {
         markGenuineLocaleChoice(code)
       }
     } catch {
-      toast.error(t('admin.account.language.update_failed'))
+      toastManager.add({ type: 'error', title: t('admin.account.language.update_failed') })
     }
   }
 }

package/src/hooks/use-visual-viewport-offset.ts

@@ -0,0 +1,61 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * Distance from the bottom of the layout viewport to the bottom of the visual
+ * one, in CSS pixels.
+ *
+ * A `position: fixed; bottom: 0` element anchors to the *layout* viewport. When
+ * the page is pinch-zoomed — or a mobile browser's URL bar is expanded — the
+ * visual viewport is a smaller window onto that layout, so the element sits
+ * below what the merchant can actually see and only appears once they pan or
+ * scroll down to it. Adding this offset to `bottom` keeps a fixed bar on screen
+ * in both cases.
+ *
+ * Returns `0` when the two viewports agree, which is the ordinary desktop case
+ * and costs nothing.
+ *
+ * @param active Pass the consumer's own visibility so the measurement happens
+ *   when it appears — a value read at mount is taken before the element exists
+ *   and never refreshed.
+ */
+export function useVisualViewportOffset(active = true): number {
+  const [offset, setOffset] = useState(0)
+
+  useEffect(() => {
+    if (!active) return
+    const vv = window.visualViewport
+    if (!vv) return
+
+    const update = () => {
+      // `window.innerHeight`, not `documentElement.clientHeight`: `fixed`
+      // positioning resolves against the former, and the two disagree in
+      // exactly the situation this hook exists for — a zoomed or URL-bar-inset
+      // page reports the *visual* height as `clientHeight`, which would make
+      // the offset compute to zero and move nothing.
+      const below = window.innerHeight - (vv.offsetTop + vv.height)
+      setOffset(Math.max(0, Math.round(below)))
+    }
+
+    update()
+    // The two viewports can still disagree on the first frame — a zoom level
+    // restored with the page, or a URL bar that has not settled, both report
+    // stale numbers until layout completes. Re-read once after paint so the
+    // bar is placed correctly without waiting for the user to resize.
+    const raf = requestAnimationFrame(update)
+
+    vv.addEventListener('resize', update)
+    vv.addEventListener('scroll', update)
+    window.addEventListener('resize', update)
+    return () => {
+      cancelAnimationFrame(raf)
+      vv.removeEventListener('resize', update)
+      vv.removeEventListener('scroll', update)
+      window.removeEventListener('resize', update)
+    }
+    // `active` is in the deps so the offset is measured when the consumer
+    // actually appears. Reading it once at mount is too early: the element is
+    // usually not rendered yet, and nothing re-measures when it later shows.
+  }, [active])
+
+  return offset
+}

package/src/index.ts

@@ -11,11 +11,13 @@
 //     import { AuthProvider } from '@spree/dashboard-core/providers/auth-provider'
 //     import { useResourceMutation } from '@spree/dashboard-core/hooks/use-resource-mutation'
 
+export * from './api-client'
 // ---------------------------------------------------------------------------
 // Admin SDK client (Vite-aware singleton; reads VITE_SPREE_API_URL at build)
 // ---------------------------------------------------------------------------
 export { adminClient } from './client'
 export * from './components/address-form-dialog'
+export * from './components/app-shell'
 export * from './components/app-sidebar'
 export * from './components/bulk-action-bar'
 export * from './components/can'
@@ -26,8 +28,11 @@ export * from './components/export-button'
 export * from './components/file-upload-field'
 export * from './components/image-upload-field'
 export * from './components/import-button'
+export * from './components/import-wizard-dialog'
 export * from './components/locale-select'
 export * from './components/market-combobox'
+export * from './components/media-picker-sheet'
+export * from './components/mobile-top-bar'
 export * from './components/nav-main'
 export * from './components/page-header'
 export * from './components/page-tabs'
@@ -36,17 +41,24 @@ export * from './components/resource-combobox'
 export * from './components/resource-multi-autocomplete'
 export * from './components/resource-picker-sheet'
 export * from './components/resource-table'
+export * from './components/route-announcer'
+export * from './components/section-heading'
 export * from './components/settings-sidebar'
+export * from './components/sheet-top-bar'
+export * from './components/sidebar-search'
+export * from './components/sidebar-user'
+export * from './components/skip-link'
 export * from './components/slot'
 export * from './components/store-date-picker'
 export * from './components/store-switcher'
 export * from './components/table-toolbar'
 export * from './components/tag-combobox'
-export * from './components/top-bar'
+export * from './components/top-bar-breadcrumbs'
 // ---------------------------------------------------------------------------
 // Infra hooks
 // ---------------------------------------------------------------------------
 export * from './hooks/use-auth'
+export * from './hooks/use-auto-collapse-sidebar'
 export * from './hooks/use-command-palette'
 export * from './hooks/use-countries'
 export * from './hooks/use-custom-fields'
@@ -56,27 +68,40 @@ export * from './hooks/use-export'
 export * from './hooks/use-global-search'
 export * from './hooks/use-host-form'
 export * from './hooks/use-import'
+export * from './hooks/use-package-types'
 export * from './hooks/use-resource-mutation'
+export * from './hooks/use-stock-locations'
 export * from './hooks/use-switch-admin-locale'
+export * from './hooks/use-visual-viewport-offset'
+export * from './lib/cancel-order-form'
+export * from './lib/create-action-registry'
 // ---------------------------------------------------------------------------
 // Registries — pluggable extension points (nav, route, slot, table,
 // settings-nav, form fields, custom field components)
 // ---------------------------------------------------------------------------
 export * from './lib/custom-field-components'
+export * from './lib/date-presets'
+export * from './lib/delivery-form'
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+export * from './lib/docs'
+export * from './lib/download'
 export * from './lib/filters-to-ransack'
 export * from './lib/form-errors'
 export * from './lib/form-fields-registry'
 export * from './lib/form-mappers'
 export * from './lib/formatters'
+export * from './lib/fulfillment-items'
 // i18n side-effect import bootstraps i18next + React adapter on first import.
 // Consumers that need the singleton (e.g. plugin authors calling
 // `i18n.addResourceBundle`) get it via the named re-export.
 export * from './lib/i18n'
+export * from './lib/import-types'
+export * from './lib/label-upload-form'
 export * from './lib/nav-registry'
 export * from './lib/permissions'
+export * from './lib/progress'
 export * from './lib/query-client'
 export * from './lib/query-keys'
 export * from './lib/route-registry'
@@ -85,13 +110,32 @@ export * from './lib/settings-nav-registry'
 export * from './lib/slot-registry'
 export * from './lib/table-registry'
 export { ensureTimestampColumns } from './lib/timestamp-columns'
+export * from './lib/type-labels'
+export * from './pages/package-types'
+export * from './pages/settings-index'
+export * from './pages/stock-locations'
 // ---------------------------------------------------------------------------
 // Plugin facade — re-exported for convenience; same API as `/plugin` subpath
 // ---------------------------------------------------------------------------
 export * from './plugin'
+export * from './products/currency-parts'
+export * from './products/normalize-customs'
+export * from './products/normalize-money'
+export * from './products/normalize-quantity'
+export * from './products/product-form-cards'
+export * from './products/product-form-mapping'
+export * from './products/product-schema'
+export * from './products/product-types'
+export * from './products/use-product-form-data'
+export * from './products/variants-matrix'
+export * from './products/video-url'
 // ---------------------------------------------------------------------------
 // Providers — must be mounted by the consuming app shell
 // ---------------------------------------------------------------------------
 export * from './providers/auth-provider'
 export * from './providers/permission-provider'
+export * from './providers/sticky-header-provider'
 export * from './providers/store-provider'
+export * from './providers/tenant-provider'
+export * from './schemas/package-type'
+export * from './schemas/stock-location'

package/src/lib/cancel-order-form.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod'
+
+/**
+ * Why an order is being cancelled, and what happens to the money and the
+ * customer.
+ *
+ * Both toggles are always present in the form; which of them a surface
+ * actually renders is its own business — the seller branch accepts no refund
+ * argument at all, so it never shows that one.
+ */
+export const cancelOrderFormSchema = z.object({
+  cancel_reason_id: z.string(),
+  cancel_note: z.string(),
+  refund_payments: z.boolean(),
+  notify_customer: z.boolean(),
+})
+
+export type CancelOrderFormValues = z.infer<typeof cancelOrderFormSchema>
+
+export const CANCEL_ORDER_DEFAULTS: CancelOrderFormValues = {
+  cancel_reason_id: '',
+  cancel_note: '',
+  // Off by default, like the API: releasing the gateway's hold is automatic,
+  // but handing back money already taken is the merchant's call.
+  refund_payments: false,
+  notify_customer: false,
+}

package/src/lib/create-action-registry.ts

@@ -0,0 +1,278 @@
+import type { LucideIcon } from 'lucide-react'
+import { useSyncExternalStore } from 'react'
+import type { SubjectName } from './permissions'
+
+/**
+ * Registry for the command palette's create actions — the rows that turn
+ * "add product" or "new order" into a jump to the matching create page.
+ *
+ * Mirrors `search-registry.ts` and `nav-registry.ts`: a module-singleton
+ * populated at app boot by side-effect modules, read reactively via
+ * `useCreateActions`. Plugins register their own create pages the same way.
+ *
+ * Matching is a concern of `matchCreateActions` below, not of the entry: an
+ * entry only declares what it is called and where it goes.
+ */
+
+export interface CreateActionEntry {
+  /** Stable identifier — register/remove key, React key, and result-value prefix. */
+  key: string
+  /**
+   * i18n key for the singular resource noun, as the merchant would type it
+   * ("Product", "Customer"). Resolved with `t` at match time so typing the
+   * noun works in the merchant's own language.
+   */
+  labelKey: string
+  /**
+   * Extra i18n keys for words that should also match this action — plurals,
+   * synonyms, and abbreviations ("SKU" for a product). Optional.
+   */
+  aliasKeys?: string[]
+  /** Row icon. */
+  icon?: LucideIcon
+  /** CanCanCan subject gating the action. Checked with `create`, not `read`. */
+  subject?: SubjectName
+  /** Lower numbers render first among equally-good matches. */
+  position?: number
+  /**
+   * Destination, given the active store. Either a dedicated create route
+   * (`/${storeId}/products/new`) or an index page with the create sheet open
+   * (`/${storeId}/customers?new=true`).
+   */
+  getRoute: (storeId: string) => { to: string; search?: Record<string, unknown> }
+}
+
+interface CreateActionMutator {
+  /** Register an action. Throws if the key is already registered. */
+  add(entry: CreateActionEntry): void
+  /** Remove an action by key. No-op when missing. */
+  remove(key: string): void
+  /** Patch an existing action. Throws if the key is missing. */
+  update(key: string, patch: Partial<Omit<CreateActionEntry, 'key'>>): void
+}
+
+const entries: CreateActionEntry[] = []
+const listeners = new Set<() => void>()
+let snapshotCache: CreateActionEntry[] | null = null
+
+function notify() {
+  snapshotCache = null
+  for (const l of listeners) l()
+}
+
+/**
+ * The create-action registry. Every mutation notifies subscribers, so a page
+ * rendered through `useCreateActions` reflects it immediately — which is how a
+ * plugin can register its create pages after the app has booted.
+ *
+ * `add` throws on a duplicate key and `update` throws on an unknown one, so a
+ * plugin colliding with a built-in fails loudly instead of silently shadowing
+ * it. `remove` is tolerant, letting teardown run unconditionally.
+ */
+export const createActionRegistry: CreateActionMutator = {
+  add(entry) {
+    if (entries.some((e) => e.key === entry.key)) {
+      throw new Error(
+        `Create action "${entry.key}" already registered. Use createActionRegistry.update().`,
+      )
+    }
+    entries.push(entry)
+    notify()
+  },
+  remove(key) {
+    const i = entries.findIndex((e) => e.key === key)
+    if (i === -1) return
+    entries.splice(i, 1)
+    notify()
+  },
+  update(key, patch) {
+    const e = entries.find((x) => x.key === key)
+    if (!e) throw new Error(`Create action "${key}" not found.`)
+    Object.assign(e, patch)
+    notify()
+  },
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+function getSnapshot(): CreateActionEntry[] {
+  if (!snapshotCache) {
+    snapshotCache = [...entries].sort((a, b) => (a.position ?? 100) - (b.position ?? 100))
+  }
+  return snapshotCache
+}
+
+/** Reactively read the sorted create actions. Re-renders on registry mutation. */
+export function useCreateActions(): CreateActionEntry[] {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/** Test-only: clear the registry. */
+export function __resetCreateActionRegistry(): void {
+  entries.length = 0
+  notify()
+}
+
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+
+/**
+ * i18n key holding the create verbs for the active language, as a
+ * comma-separated list ("add,new,create"). A list rather than one word because
+ * merchants reach for whichever verb comes to mind, and several languages have
+ * more than one natural phrasing.
+ */
+export const CREATE_VERBS_KEY = 'admin.components.command_palette.create.verbs'
+
+export interface CreateActionMatch {
+  entry: CreateActionEntry
+  /** The resolved noun that matched, for rendering the row's label. */
+  noun: string
+  /** Lower sorts first: an exact noun match beats a prefix beats a substring. */
+  rank: number
+}
+
+/**
+ * Scripts written without spaces between words. Restricting the unspaced verb
+ * match to these keeps it from firing on space-delimited languages, where
+ * "address" would otherwise read as the verb "add" plus a noun "ress".
+ */
+const UNSPACED_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u
+
+/**
+ * Strip a leading or trailing verb from an unspaced query, returning the noun
+ * that remains (`''` when the query is just the verb). Returns `null` when the
+ * query carries no verb or isn't written in an unspaced script.
+ */
+function stripUnspacedVerb(query: string, verbs: Set<string>): string | null {
+  if (!UNSPACED_SCRIPT.test(query)) return null
+
+  // Longest first, so a verb that is a prefix of another ("新" vs "新建")
+  // can't strip the shorter match and leave the rest of the verb in the noun.
+  const byLength = [...verbs].sort((a, b) => b.length - a.length)
+
+  for (const verb of byLength) {
+    if (query === verb) return ''
+    if (query.startsWith(verb)) return query.slice(verb.length)
+    if (query.endsWith(verb)) return query.slice(0, -verb.length)
+  }
+  return null
+}
+
+/** Fold case and strip accents so "Rückgabe" matches "ruckgabe". */
+function normalize(value: string): string {
+  return value
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '')
+    .trim()
+}
+
+/**
+ * Turn a raw palette query into the create actions it names.
+ *
+ * Matches "<verb> <noun>" in either order, since languages disagree on which
+ * comes first — English puts the verb first ("add product"), while a merchant
+ * typing Polish or German may not. A bare verb ("new") lists everything
+ * creatable, which doubles as discovery of what this dashboard can create.
+ *
+ * Returns an empty array when the query names no verb, so ordinary searches are
+ * unaffected.
+ */
+/**
+ * The create actions a query names, narrowed to those the signed-in user may
+ * actually create.
+ *
+ * Create is gated on the `create` action rather than `read`: a user who can
+ * list products but not add one should never be offered "New product". Entries
+ * without a subject are ungated.
+ */
+export function permittedCreateActions({
+  query,
+  entries,
+  t,
+  can,
+}: {
+  query: string
+  entries: CreateActionEntry[]
+  t: (key: string) => string
+  can: (action: string, subject: string) => boolean
+}): CreateActionMatch[] {
+  return matchCreateActions({ query, entries, t }).filter(
+    ({ entry }) => !entry.subject || can('create', entry.subject),
+  )
+}
+
+export function matchCreateActions({
+  query,
+  entries,
+  t,
+}: {
+  query: string
+  entries: CreateActionEntry[]
+  t: (key: string) => string
+}): CreateActionMatch[] {
+  const words = normalize(query).split(/\s+/).filter(Boolean)
+  if (words.length === 0) return []
+
+  const verbs = new Set(
+    t(CREATE_VERBS_KEY)
+      .split(',')
+      .map((verb) => normalize(verb))
+      .filter(Boolean),
+  )
+
+  // The verb may lead or trail; strip whichever end carries it and treat the
+  // rest as the noun. Checking the last word only when the first didn't match
+  // keeps "add" + "add-on"-style nouns unambiguous.
+  let noun: string
+  if (verbs.has(words[0])) {
+    noun = words.slice(1).join(' ')
+  } else if (words.length > 1 && verbs.has(words[words.length - 1])) {
+    noun = words.slice(0, -1).join(' ')
+  } else {
+    // Languages that don't put spaces between words — Chinese, Japanese —
+    // arrive as one token ("新建商品"), so word equality never matches. Fall
+    // back to stripping the verb as a prefix or suffix of the whole query.
+    const unspaced = stripUnspacedVerb(normalize(query), verbs)
+    if (unspaced === null) return []
+    noun = unspaced
+  }
+  const matches: CreateActionMatch[] = []
+
+  for (const entry of entries) {
+    const labels = [entry.labelKey, ...(entry.aliasKeys ?? [])].map((key) => t(key))
+    let best: { rank: number; noun: string } | null = null
+
+    for (const label of labels) {
+      const candidate = normalize(label)
+      // A bare verb lists everything; otherwise rank by how squarely the typed
+      // noun lands on this label.
+      const rank = !noun
+        ? 3
+        : candidate === noun
+          ? 0
+          : candidate.startsWith(noun)
+            ? 1
+            : candidate.includes(noun)
+              ? 2
+              : -1
+      if (rank === -1) continue
+      // Always report the primary label, so a row found via an alias still
+      // reads as the resource's real name.
+      if (!best || rank < best.rank) best = { rank, noun: labels[0] }
+    }
+
+    if (best) matches.push({ entry, noun: best.noun, rank: best.rank })
+  }
+
+  return matches.sort(
+    (a, b) => a.rank - b.rank || (a.entry.position ?? 100) - (b.entry.position ?? 100),
+  )
+}