@spree/dashboard-core 0.1.0

package/src/plugin.ts

@@ -0,0 +1,222 @@
+// `@spree/dashboard-core/plugin` — the single import plugin authors use.
+//
+// A plugin's entry module calls `defineDashboardPlugin({...})` at import time;
+// the dashboard app imports plugin entries in its bootstrap before the first
+// render. Each registry uses `useSyncExternalStore`, so late registration
+// (after the app has mounted) still re-renders consumers.
+//
+// Example:
+//
+//     import { defineDashboardPlugin } from '@spree/dashboard-core/plugin'
+//     import { Card } from '@spree/dashboard-ui'
+//
+//     function WishlistCount({ product }: { product: { wishlist_count: number } }) {
+//       return <Card>Wishlists: {product.wishlist_count}</Card>
+//     }
+//
+//     defineDashboardPlugin({
+//       nav: [
+//         { key: 'wishlists', label: 'Wishlists', path: '/wishlists', position: 50 },
+//       ],
+//       slots: {
+//         'product.form_sidebar': [
+//           { id: 'wishlist-count', component: WishlistCount, position: 50 },
+//         ],
+//       },
+//       tables: {
+//         products: { add: [{ key: 'wishlist_count', label: 'Wishlists', sortable: true }] },
+//       },
+//       settingsNav: [
+//         { key: 'wishlist-settings', label: 'Wishlists', path: '/wishlists', group: 'integrations' },
+//       ],
+//     })
+
+import type { CustomFieldComponent } from './lib/custom-field-components'
+import { customFieldComponents } from './lib/custom-field-components'
+import type { FormFieldRegistration } from './lib/form-fields-registry'
+import { formFields } from './lib/form-fields-registry'
+import type { NavEntry } from './lib/nav-registry'
+import { nav } from './lib/nav-registry'
+import type { RouteEntry } from './lib/route-registry'
+import { pluginRoutes } from './lib/route-registry'
+import type { SettingsNavEntry, SettingsNavGroup } from './lib/settings-nav-registry'
+import { settingsNav } from './lib/settings-nav-registry'
+import type { SlotEntry } from './lib/slot-registry'
+import { registerSlot } from './lib/slot-registry'
+import type { ColumnDef } from './lib/table-registry'
+import { tables } from './lib/table-registry'
+
+export interface TableMutations {
+  /** Columns to append to the table. Keys must not already exist. */
+  add?: ColumnDef[]
+  /** Column keys to remove. No-op when the column is already gone. */
+  remove?: string[]
+  /** Column patches keyed by column key — `{ totals: { label: 'Net total' } }`. */
+  update?: Record<string, Partial<ColumnDef>>
+}
+
+export interface NavMutations {
+  /** Sidebar entries to add. Each must have a unique `key`. */
+  add?: NavEntry[]
+  /** Entry keys to remove — built-in or plugin. No-op when already gone. */
+  remove?: string[]
+  /**
+   * Patches keyed by entry key — reorder via `position`, rename via `label`,
+   * gate via `subject`. Throws when the key isn't registered, so patch only
+   * entries you know exist (built-ins register before any plugin runs).
+   */
+  update?: Record<string, Partial<Omit<NavEntry, 'key'>>>
+  /**
+   * Children to append under existing top-level entries, keyed by parent key
+   * — e.g. `{ products: [{ key: 'products.brands', … }] }` nests an item in
+   * the built-in Products menu. Preserves the parent's existing children.
+   * Throws when the parent is missing or a child key already exists there.
+   */
+  addChildren?: Record<string, NavEntry[]>
+}
+
+export interface SettingsNavMutations {
+  /** Settings sub-shell entries to add. */
+  add?: SettingsNavEntry[]
+  /** Entry keys to remove. No-op when already gone. */
+  remove?: string[]
+  /** Patches keyed by entry key. Throws when the key isn't registered. */
+  update?: Record<string, Partial<Omit<SettingsNavEntry, 'key'>>>
+}
+
+export interface DashboardPluginConfig {
+  /**
+   * Sidebar entries. The array form adds entries; the object form also
+   * removes or patches existing ones (built-ins included):
+   *
+   *     nav: {
+   *       add: [{ key: 'reviews', label: 'Reviews', path: '/reviews' }],
+   *       remove: ['gift-cards'],
+   *       update: { products: { position: 10 } },
+   *     }
+   */
+  nav?: NavEntry[] | NavMutations
+  /** Settings sub-shell groups (defined before any entry that uses the group key). */
+  settingsNavGroups?: SettingsNavGroup[]
+  /** Settings sub-shell entries — array adds; object form also removes/patches. */
+  settingsNav?: SettingsNavEntry[] | SettingsNavMutations
+  /** Slot extensions keyed by slot name. Each entry must have a unique `id`. */
+  slots?: Record<string, SlotEntry[]>
+  /** Table mutations keyed by table key (see `defineTable`). */
+  tables?: Record<string, TableMutations>
+  /**
+   * Custom routes mounted under `/$storeId/`. Each entry's `path` is relative
+   * (e.g. `/brands`, `/brands/$brandId`). The dashboard's catch-all route at
+   * `/$storeId/*` dispatches based on the splat — your `component` renders
+   * exactly like any first-party route, including TanStack Router's
+   * `useParams()` for path params.
+   */
+  routes?: RouteEntry[]
+  /**
+   * Extension fields on built-in resource forms, keyed by form key (e.g.
+   * `'product'`). Each field hydrates from the fetched resource via `from`
+   * and persists through the form's own Save — render its input from a slot
+   * widget bound via `useHostForm()`.
+   */
+  formFields?: Record<string, FormFieldRegistration[]>
+  /**
+   * Input components for specific custom field definitions, keyed by the
+   * definition's `namespace.key` (e.g. `'specs.color'`). Replaces the
+   * default widget for that definition's `field_type` wherever the
+   * custom-fields card renders it.
+   */
+  customFieldComponents?: Record<string, CustomFieldComponent>
+}
+
+/**
+ * Register all the extensions in `config` against the dashboard's registries.
+ * Call it once per plugin entry module — each registry enforces uniqueness on
+ * its keys, so re-running the same config (or colliding with another plugin's
+ * `key`/`id`) throws with a useful message rather than double-registering.
+ *
+ * Plugins typically call this once from their entry module (e.g.
+ * `src/index.ts`). The dashboard app imports plugin entries during bootstrap.
+ *
+ * @returns nothing — registries are module singletons. To unregister, call the
+ *          relevant `nav.remove` / `removeSlot` / `tables.<key>.removeColumn` /
+ *          `settingsNav.remove` directly.
+ */
+export function defineDashboardPlugin(config: DashboardPluginConfig): void {
+  // Collect errors across every registry call and rethrow once at the end.
+  // A duplicate nav key shouldn't stop the rest of the config (slots, tables,
+  // other nav entries) from registering — plugin authors should see every
+  // problem in their config at once, not whack-a-mole through reload cycles.
+  // Matches the deferred-flush semantics in `table-registry.ts`.
+  const errors: unknown[] = []
+  const safely = <T extends unknown[]>(fn: (...args: T) => void, ...args: T) => {
+    try {
+      fn(...args)
+    } catch (err) {
+      errors.push(err)
+    }
+  }
+
+  if (config.nav) {
+    const m: NavMutations = Array.isArray(config.nav) ? { add: config.nav } : config.nav
+    // add before addChildren so a plugin can add a parent then nest under it.
+    for (const entry of m.add ?? []) safely(nav.add, entry)
+    for (const [parentKey, children] of Object.entries(m.addChildren ?? {})) {
+      for (const child of children) safely(nav.addChild, parentKey, child)
+    }
+    for (const key of m.remove ?? []) safely(nav.remove, key)
+    for (const [key, patch] of Object.entries(m.update ?? {})) safely(nav.update, key, patch)
+  }
+
+  if (config.settingsNavGroups) {
+    for (const group of config.settingsNavGroups) safely(settingsNav.addGroup, group)
+  }
+
+  if (config.settingsNav) {
+    const m: SettingsNavMutations = Array.isArray(config.settingsNav)
+      ? { add: config.settingsNav }
+      : config.settingsNav
+    for (const entry of m.add ?? []) safely(settingsNav.add, entry)
+    for (const key of m.remove ?? []) safely(settingsNav.remove, key)
+    for (const [key, patch] of Object.entries(m.update ?? {})) {
+      safely(settingsNav.update, key, patch)
+    }
+  }
+
+  if (config.slots) {
+    for (const [name, list] of Object.entries(config.slots)) {
+      for (const entry of list) safely(registerSlot, name, entry)
+    }
+  }
+
+  if (config.tables) {
+    for (const [tableKey, mutations] of Object.entries(config.tables)) {
+      const mutator = tables[tableKey]
+      for (const column of mutations.add ?? []) safely(mutator.addColumn, column)
+      for (const key of mutations.remove ?? []) safely(mutator.removeColumn, key)
+      for (const [key, patch] of Object.entries(mutations.update ?? {})) {
+        safely(mutator.updateColumn, key, patch)
+      }
+    }
+  }
+
+  if (config.routes) {
+    for (const entry of config.routes) safely(pluginRoutes.add, entry)
+  }
+
+  if (config.formFields) {
+    for (const [formKey, fields] of Object.entries(config.formFields)) {
+      for (const field of fields) safely(formFields.register, formKey, field)
+    }
+  }
+
+  if (config.customFieldComponents) {
+    for (const [key, component] of Object.entries(config.customFieldComponents)) {
+      safely(customFieldComponents.register, key, component)
+    }
+  }
+
+  if (errors.length === 1) throw errors[0]
+  if (errors.length > 1) {
+    throw new AggregateError(errors, `${errors.length} registration(s) failed`)
+  }
+}

package/src/providers/auth-provider.tsx

@@ -0,0 +1,188 @@
+import type {
+  AdminUser,
+  AuthTokens,
+  InvitationAcceptParams,
+  PasswordResetParams,
+} from '@spree/admin-sdk'
+import { createContext, type ReactNode, useCallback, useEffect, useRef, useState } from 'react'
+import { adminClient } from '../client'
+import { ADMIN_LOCALE_STORAGE_KEY, switchLocale } from '../lib/i18n'
+
+interface AuthContextValue {
+  user: AdminUser | null
+  token: string | null
+  isAuthenticated: boolean
+  isInitializing: boolean
+  isLoading: boolean
+  login: (email: string, password: string) => Promise<void>
+  logout: () => Promise<void>
+  acceptInvitation: (id: string, token: string, params: InvitationAcceptParams) => Promise<void>
+  /**
+   * Consume a password reset token, set the new password, and sign in — the
+   * endpoint issues a session just like login. `requestPasswordReset` (the
+   * step that sends the email) is unauthenticated and lives on `adminClient`.
+   */
+  resetPassword: (token: string, params: PasswordResetParams) => Promise<void>
+  /**
+   * Merge updated fields into the authenticated user (e.g. after a profile
+   * save) so context consumers like the top-bar reflect the change immediately
+   * instead of waiting for the next token refresh. No-op when signed out.
+   */
+  updateUser: (changes: Partial<AdminUser>) => void
+}
+
+export const AuthContext = createContext<AuthContextValue | null>(null)
+
+// Refresh ~30s before the JWT expires (default 5min TTL).
+const REFRESH_INTERVAL_MS = 4 * 60 * 1000 + 30 * 1000
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+  const [token, setToken] = useState<string | null>(null)
+  const [user, setUser] = useState<AdminUser | null>(null)
+  const [isInitializing, setIsInitializing] = useState(true)
+  const [isLoading, setIsLoading] = useState(false)
+  const refreshTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  // Serialize concurrent refresh calls so StrictMode/HMR/401-retry don't double-rotate.
+  const refreshPromiseRef = useRef<Promise<boolean> | null>(null)
+
+  const clearRefreshTimer = useCallback(() => {
+    if (refreshTimerRef.current) {
+      clearTimeout(refreshTimerRef.current)
+      refreshTimerRef.current = null
+    }
+  }, [])
+
+  const applySession = useCallback((accessToken: string, authUser: AdminUser) => {
+    adminClient.setToken(accessToken)
+    setToken(accessToken)
+    setUser(authUser)
+    // The account's saved admin language is the source of truth across devices.
+    // Compare against the persisted choice (not the live i18n.language): if they
+    // already agree, the page booted in the right language and no reload is
+    // needed — this also prevents a reload loop on the periodic token refresh.
+    const code = authUser.selected_locale
+    const stored =
+      typeof localStorage !== 'undefined'
+        ? (localStorage.getItem(ADMIN_LOCALE_STORAGE_KEY) ?? 'en')
+        : 'en'
+    if (code && code !== stored) switchLocale(code)
+  }, [])
+
+  const updateUser = useCallback((changes: Partial<AdminUser>) => {
+    setUser((current) => (current ? { ...current, ...changes } : current))
+  }, [])
+
+  const clearSession = useCallback(() => {
+    adminClient.setToken('')
+    setToken(null)
+    setUser(null)
+    clearRefreshTimer()
+  }, [clearRefreshTimer])
+
+  const doRefresh = useCallback(async (): Promise<boolean> => {
+    try {
+      const res = await adminClient.auth.refresh()
+      applySession(res.token, res.user)
+      return true
+    } catch {
+      clearSession()
+      return false
+    }
+  }, [applySession, clearSession])
+
+  const refreshAccessToken = useCallback((): Promise<boolean> => {
+    if (refreshPromiseRef.current) return refreshPromiseRef.current
+    const promise = doRefresh().finally(() => {
+      refreshPromiseRef.current = null
+    })
+    refreshPromiseRef.current = promise
+    return promise
+  }, [doRefresh])
+
+  const scheduleRefresh = useCallback(() => {
+    clearRefreshTimer()
+    refreshTimerRef.current = setTimeout(async () => {
+      const success = await refreshAccessToken()
+      if (success) scheduleRefresh()
+    }, REFRESH_INTERVAL_MS)
+  }, [refreshAccessToken, clearRefreshTimer])
+
+  const establish = useCallback(
+    async (req: Promise<AuthTokens>) => {
+      setIsLoading(true)
+      try {
+        const res = await req
+        applySession(res.token, res.user)
+        scheduleRefresh()
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [applySession, scheduleRefresh],
+  )
+
+  const login = useCallback(
+    (email: string, password: string) => establish(adminClient.auth.login({ email, password })),
+    [establish],
+  )
+
+  const acceptInvitation = useCallback(
+    (id: string, token: string, params: InvitationAcceptParams) =>
+      establish(adminClient.auth.acceptInvitation(id, token, params)),
+    [establish],
+  )
+
+  const resetPassword = useCallback(
+    (token: string, params: PasswordResetParams) =>
+      establish(adminClient.auth.resetPassword(token, params)),
+    [establish],
+  )
+
+  const logout = useCallback(async () => {
+    try {
+      await adminClient.auth.logout()
+    } catch {
+      // Server unreachable — clear locally; the row will expire naturally.
+    } finally {
+      clearSession()
+    }
+  }, [clearSession])
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: only run on mount
+  useEffect(() => {
+    adminClient.onUnauthorized(async () => {
+      const success = await refreshAccessToken()
+      if (success) scheduleRefresh()
+      return success
+    })
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: only run on mount
+  useEffect(() => {
+    refreshAccessToken()
+      .then((success) => {
+        if (success) scheduleRefresh()
+      })
+      .finally(() => setIsInitializing(false))
+    return clearRefreshTimer
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  return (
+    <AuthContext.Provider
+      value={{
+        user,
+        token,
+        isAuthenticated: !!token,
+        isInitializing,
+        isLoading,
+        login,
+        logout,
+        acceptInvitation,
+        resetPassword,
+        updateUser,
+      }}
+    >
+      {children}
+    </AuthContext.Provider>
+  )
+}

package/src/providers/permission-provider.tsx

@@ -0,0 +1,118 @@
+import type { PermissionRule } from '@spree/admin-sdk'
+import { createContext, type ReactNode, useContext, useEffect, useMemo, useState } from 'react'
+import { adminClient } from '../client'
+import { useAuth } from '../hooks/use-auth'
+import type { ActionName, SubjectName } from '../lib/permissions'
+
+/**
+ * Matcher that mirrors CanCanCan semantics:
+ *   - `manage` action matches any action
+ *   - `all` subject matches any subject
+ *   - Later rules override earlier rules (last-matching-wins)
+ *
+ * Per-record conditions are NOT evaluated — they stay on the server. The
+ * `isConditional` flag indicates that a rule may still be rejected at the
+ * per-record level, so the UI should expect possible 403 from the API.
+ */
+export interface Permissions {
+  can: (action: ActionName, subject: SubjectName) => boolean
+  cannot: (action: ActionName, subject: SubjectName) => boolean
+  /** True if the matching rule has per-record conditions. Caller should expect possible 403. */
+  isConditional: (action: ActionName, subject: SubjectName) => boolean
+}
+
+interface PermissionContextValue {
+  permissions: Permissions
+  rules: PermissionRule[]
+  isLoading: boolean
+}
+
+const PermissionContext = createContext<PermissionContextValue | null>(null)
+
+function ruleMatches(rule: PermissionRule, action: string, subject: string): boolean {
+  const actionMatch = rule.actions.includes(action) || rule.actions.includes('manage')
+  const subjectMatch = rule.subjects.includes(subject) || rule.subjects.includes('all')
+  return actionMatch && subjectMatch
+}
+
+export function buildPermissions(rules: PermissionRule[]): Permissions {
+  const can = (action: ActionName, subject: SubjectName): boolean => {
+    // Walk rules in order — later matching rules override earlier ones
+    let allowed = false
+    for (const rule of rules) {
+      if (ruleMatches(rule, action, subject)) {
+        allowed = rule.allow
+      }
+    }
+    return allowed
+  }
+
+  return {
+    can,
+    cannot: (action, subject) => !can(action, subject),
+    isConditional: (action, subject) => {
+      let conditional = false
+      for (const rule of rules) {
+        if (ruleMatches(rule, action, subject) && rule.allow && rule.has_conditions) {
+          conditional = true
+        }
+      }
+      return conditional
+    },
+  }
+}
+
+/** Empty permissions that deny everything — used before rules are loaded. */
+const EMPTY_PERMISSIONS: Permissions = {
+  can: () => false,
+  cannot: () => true,
+  isConditional: () => false,
+}
+
+export function PermissionProvider({ children }: { children: ReactNode }) {
+  const { isAuthenticated } = useAuth()
+  const [rules, setRules] = useState<PermissionRule[]>([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      setRules([])
+      return
+    }
+
+    let cancelled = false
+    setIsLoading(true)
+    adminClient.me
+      .get()
+      .then((res) => {
+        if (!cancelled) setRules(res.permissions)
+      })
+      .catch(() => {
+        if (!cancelled) setRules([])
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [isAuthenticated])
+
+  const permissions = useMemo(
+    () => (rules.length > 0 ? buildPermissions(rules) : EMPTY_PERMISSIONS),
+    [rules],
+  )
+
+  return (
+    <PermissionContext.Provider value={{ permissions, rules, isLoading }}>
+      {children}
+    </PermissionContext.Provider>
+  )
+}
+
+export function usePermissions(): PermissionContextValue {
+  const ctx = useContext(PermissionContext)
+  if (!ctx) throw new Error('usePermissions must be used within a PermissionProvider')
+  return ctx
+}

package/src/providers/store-provider.tsx

@@ -0,0 +1,111 @@
+import type { Store } from '@spree/admin-sdk'
+import { useQuery } from '@tanstack/react-query'
+import { createContext, type ReactNode, useContext, useEffect, useRef } from 'react'
+import { adminClient } from '../client'
+import { useAuth } from '../hooks/use-auth'
+import { coreLocaleCodes, reconcileStoreDefaultLocale } from '../lib/i18n'
+
+/**
+ * Resource segment of the store query key: the current store lives in the
+ * TanStack cache under `['store', storeId]` (the canonical
+ * `[resource, storeId]` shape). Mutations that change anything the store
+ * payload derives from — setup-task completion, supported locales/currencies —
+ * add `[[STORE_QUERY_RESOURCE]]` to their `useResourceMutation` invalidate
+ * list so every consumer (nav badge, Getting Started, pickers) refreshes.
+ */
+export const STORE_QUERY_RESOURCE = 'store'
+
+interface StoreContextValue {
+  store: Store | null
+  storeId: string
+  isLoading: boolean
+  currencies: string[]
+  /** Locales this store is configured to translate content into. */
+  locales: string[]
+  /** Every locale a merchant may translate content into — the full canonical
+   *  set, independent of which locales the store currently uses. Drives locale
+   *  pickers so a new locale can always be added. */
+  availableLocales: string[]
+  defaultCurrency: string
+  defaultLocale: string
+  /** IANA timezone for the store (e.g. `Europe/Berlin`). Falls back to the
+   *  browser's resolved timezone when the store hasn't loaded yet. */
+  timezone: string
+  refetch: () => Promise<unknown>
+}
+
+const StoreContext = createContext<StoreContextValue | null>(null)
+
+export function StoreProvider({ storeId, children }: { storeId: string; children: ReactNode }) {
+  const { user } = useAuth()
+
+  // Read the account locale through a ref so a `user` identity change (frequent —
+  // every auth update) doesn't re-trigger the locale-fallback effect below.
+  const accountLocaleRef = useRef<string | null>(user?.selected_locale ?? null)
+  accountLocaleRef.current = user?.selected_locale ?? null
+  // Run the store-default fallback only on the FIRST load of each store. A
+  // later refetch (e.g. after saving store settings) must not re-apply it:
+  // that path already owns the locale via `switchAdminLocale`, and re-applying
+  // would race that PATCH and could reload before it lands. Tracking the
+  // storeId it last ran for re-arms it per store, so a multi-store admin still
+  // inherits each store's preferred_admin_locale.
+  const localeFallbackStoreRef = useRef<string | null>(null)
+
+  const query = useQuery({
+    // Keyed per store, so a slow in-flight fetch for a store the route already
+    // left can never clobber the current store's cache entry.
+    queryKey: [STORE_QUERY_RESOURCE, storeId],
+    queryFn: () => adminClient.store.get(),
+  })
+  const store = query.data ?? null
+
+  // Reconcile the admin language against this store's default — adopting it,
+  // or dropping a now-stale auto-applied default — only when no account locale
+  // or genuine personal choice owns it (legacy base_controller parity).
+  useEffect(() => {
+    if (!store || localeFallbackStoreRef.current === storeId) return
+
+    localeFallbackStoreRef.current = storeId
+    reconcileStoreDefaultLocale(
+      store.preferred_admin_locale,
+      storeId,
+      accountLocaleRef.current,
+      coreLocaleCodes(),
+    )
+  }, [store, storeId])
+
+  const currencies = store?.supported_currencies ?? []
+  const locales = store?.supported_locales ?? []
+  const availableLocales = store?.available_locales ?? []
+  const defaultCurrency = store?.default_currency ?? 'USD'
+  const defaultLocale = store?.default_locale ?? 'en'
+  const timezone =
+    store?.preferred_timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC'
+
+  return (
+    <StoreContext.Provider
+      value={{
+        store,
+        storeId,
+        isLoading: query.isLoading,
+        currencies,
+        locales,
+        availableLocales,
+        defaultCurrency,
+        defaultLocale,
+        timezone,
+        refetch: query.refetch,
+      }}
+    >
+      {children}
+    </StoreContext.Provider>
+  )
+}
+
+export function useStore(): StoreContextValue {
+  const context = useContext(StoreContext)
+  if (!context) {
+    throw new Error('useStore must be used within a StoreProvider')
+  }
+  return context
+}

package/src/virtual.d.ts

@@ -0,0 +1,5 @@
+// Ambient declaration for the module synthesized by `spreeDashboardPlugin()`
+// (see src/vite/index.ts). Referenced from src/index.ts so any program that
+// imports @spree/dashboard-core can `import 'virtual:spree-dashboard-plugins'`
+// without its own shim.
+declare module 'virtual:spree-dashboard-plugins'