@spree/dashboard-core 0.1.0

package/src/components/tag-combobox.tsx

@@ -0,0 +1,99 @@
+import {
+  Combobox,
+  ComboboxChip,
+  ComboboxChips,
+  ComboboxChipsInput,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxValue,
+  useComboboxAnchor,
+} from '@spree/dashboard-ui'
+import { useQuery } from '@tanstack/react-query'
+import { useMemo, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { adminClient } from '../client'
+import { useAuth } from '../hooks/use-auth'
+import type { TaggableType } from '../lib/table-registry'
+
+export type { TaggableType }
+
+export function TagCombobox({
+  taggableType,
+  value,
+  onChange,
+  placeholder,
+}: {
+  taggableType: TaggableType
+  value: string[]
+  onChange: (value: string[]) => void
+  placeholder?: string
+}) {
+  const { t } = useTranslation()
+  const resolvedPlaceholder = placeholder ?? t('admin.components.tag_combobox.placeholder')
+  const anchorRef = useComboboxAnchor()
+  const [inputValue, setInputValue] = useState('')
+  const { isAuthenticated } = useAuth()
+
+  const { data } = useQuery({
+    queryKey: ['admin-tags', taggableType],
+    queryFn: () => adminClient.tags.list({ taggable_type: taggableType }),
+    enabled: isAuthenticated,
+    staleTime: 60_000,
+  })
+
+  const existingTags = data?.data?.map((t) => t.name) ?? []
+
+  // Append the typed value as a "Create" candidate so the user can confirm new tags
+  // via the dropdown (in addition to the Enter shortcut).
+  const items = useMemo(() => {
+    const set = new Set([...existingTags, ...value])
+    const trimmed = inputValue.trim()
+    if (trimmed) set.add(trimmed)
+    return Array.from(set)
+  }, [existingTags, value, inputValue])
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter' && inputValue.trim()) {
+      e.preventDefault()
+      const tag = inputValue.trim()
+      if (!value.includes(tag)) onChange([...value, tag])
+      setInputValue('')
+    }
+  }
+
+  return (
+    <Combobox multiple items={items} value={value} onValueChange={onChange}>
+      <ComboboxChips ref={anchorRef}>
+        <ComboboxValue>
+          {(selectedValues: string[]) =>
+            selectedValues.map((tag) => <ComboboxChip key={tag}>{tag}</ComboboxChip>)
+          }
+        </ComboboxValue>
+        <ComboboxChipsInput
+          placeholder={resolvedPlaceholder}
+          value={inputValue}
+          onChange={(e) => setInputValue((e.target as HTMLInputElement).value)}
+          onKeyDown={handleKeyDown}
+        />
+      </ComboboxChips>
+      <ComboboxContent anchor={anchorRef}>
+        <ComboboxEmpty>{t('admin.components.tag_combobox.empty_hint')}</ComboboxEmpty>
+        <ComboboxList>
+          {(tag: string) => {
+            const isSelected = value.includes(tag)
+            const isExisting = existingTags.includes(tag)
+            return (
+              <ComboboxItem key={tag} value={tag}>
+                {isExisting || isSelected
+                  ? tag
+                  : t('admin.components.tag_combobox.create_option', { tag })}
+              </ComboboxItem>
+            )
+          }}
+        </ComboboxList>
+      </ComboboxContent>
+    </Combobox>
+  )
+}

package/src/components/top-bar.tsx

@@ -0,0 +1,210 @@
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  LanguageMenuItems,
+  SidebarTrigger,
+  ThemeMenuItems,
+} from '@spree/dashboard-ui'
+import { Link } from '@tanstack/react-router'
+import {
+  BookOpenIcon,
+  ExternalLinkIcon,
+  LogOutIcon,
+  MailIcon,
+  MessageCircleIcon,
+  SearchIcon,
+  UserIcon,
+} from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+import { useAuth } from '../hooks/use-auth'
+import { useCommandPalette } from '../hooks/use-command-palette'
+import { useSwitchAdminLocale } from '../hooks/use-switch-admin-locale'
+import { getInitials } from '../lib/formatters'
+import { i18n } from '../lib/i18n'
+import { useStore } from '../providers/store-provider'
+
+const IS_MAC = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform ?? '')
+
+/**
+ * Top-bar shell for the admin SPA. Three-slot layout:
+ *   [☰ sidebar toggle]   [global search]   [view store · user menu]
+ *
+ * The search trigger opens the global ⌘K command palette (provider mounted at
+ * the layout root). The keyboard shortcut is registered in the provider, not
+ * here, so it works regardless of focus location.
+ */
+/**
+ * @param uiLocales Admin UI languages for the in-menu switcher. The app owns
+ *   which locale bundles ship (see the dashboard's `getAvailableUiLocales`) and
+ *   injects them here, so this core component stays free of bundle knowledge.
+ */
+export function TopBar({
+  uiLocales = [],
+}: {
+  uiLocales?: ReadonlyArray<{ code: string; name: string }>
+}) {
+  return (
+    <header className="sticky top-0 z-40 flex h-header-height shrink-0 items-center gap-3 bg-background/90 px-4 border-b border-border/50 backdrop-blur supports-[backdrop-filter]:bg-background/75">
+      <SidebarTrigger className="-ml-1 h-8 w-8" />
+
+      <div className="flex flex-1 justify-center">
+        <SearchTrigger />
+      </div>
+
+      <div className="flex items-center gap-2">
+        <ViewStoreLink />
+        <TopBarUser uiLocales={uiLocales} />
+      </div>
+    </header>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Search trigger — opens the global command palette
+// ---------------------------------------------------------------------------
+
+function SearchTrigger() {
+  const { t } = useTranslation()
+  const { setOpen } = useCommandPalette()
+
+  return (
+    <button
+      type="button"
+      onClick={() => setOpen(true)}
+      className="flex w-full max-w-md items-center gap-2 rounded-lg border border-border bg-muted/40 px-2 py-1.5 text-sm text-muted-foreground transition-colors hover:bg-muted"
+    >
+      <SearchIcon className="size-4" />
+      <span className="flex-1 text-left">{t('admin.components.command_palette.placeholder')}</span>
+      <kbd className="hidden rounded border bg-background px-1.5 py-0.5 font-mono text-xs sm:inline-flex">
+        {IS_MAC ? '⌘K' : 'Ctrl+K'}
+      </kbd>
+    </button>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// View Store link
+// ---------------------------------------------------------------------------
+
+function ViewStoreLink() {
+  const { t } = useTranslation()
+  const { store } = useStore()
+  if (!store?.url) return null
+
+  // Best-effort: prefix with https if the URL is just a hostname.
+  const href = /^https?:\/\//.test(store.url) ? store.url : `https://${store.url}`
+
+  return (
+    <Button asChild variant="ghost" size="sm">
+      <a href={href} target="_blank" rel="noreferrer">
+        <ExternalLinkIcon className="size-4" />
+        <span className="hidden sm:inline">{t('admin.account.view_store')}</span>
+      </a>
+    </Button>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// User menu
+// ---------------------------------------------------------------------------
+
+function TopBarUser({ uiLocales }: { uiLocales: ReadonlyArray<{ code: string; name: string }> }) {
+  const { t } = useTranslation()
+  const { user, logout } = useAuth()
+  const { store } = useStore()
+  const switchAdminLocale = useSwitchAdminLocale()
+  if (!user) return null
+
+  const initials = getInitials(user.full_name, user.email)
+
+  // Switching the admin UI language persists to the account, mirrors it into
+  // the auth context, and reloads — see useSwitchAdminLocale for why all three
+  // steps are required.
+  const handleSelectLocale = (code: string) => {
+    void switchAdminLocale(code)
+  }
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          aria-label={t('admin.a11y.user_menu')}
+          className="flex items-center gap-2 rounded-lg p-1 transition-colors hover:bg-accent"
+        >
+          <Avatar className="size-7">
+            {user.avatar_url && <AvatarImage src={user.avatar_url} alt="" />}
+            <AvatarFallback className="bg-primary text-xs text-primary-foreground dark:bg-accent dark:text-foreground">
+              {initials}
+            </AvatarFallback>
+          </Avatar>
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-56" sideOffset={8}>
+        <div className="flex items-center gap-2 p-1.5">
+          <Avatar className="size-8">
+            {user.avatar_url && <AvatarImage src={user.avatar_url} alt="" />}
+            <AvatarFallback className="bg-primary text-xs text-primary-foreground dark:bg-accent dark:text-foreground">
+              {initials}
+            </AvatarFallback>
+          </Avatar>
+          <div className="grid min-w-0 flex-1 text-sm leading-tight">
+            <span className="truncate font-medium text-foreground">
+              {user.full_name || user.email}
+            </span>
+            {user.full_name && (
+              <span className="truncate text-xs text-muted-foreground">{user.email}</span>
+            )}
+          </div>
+        </div>
+        <DropdownMenuSeparator />
+        <ThemeMenuItems />
+        {/* Compact nested submenu; self-hides when < 2 languages are installed. */}
+        <LanguageMenuItems
+          label={t('admin.account.language.label')}
+          locales={uiLocales}
+          value={i18n.language}
+          onSelect={handleSelectLocale}
+        />
+        {uiLocales.length >= 2 && <DropdownMenuSeparator />}
+        {store && (
+          <DropdownMenuItem asChild>
+            <Link
+              to="/$storeId/settings/profile"
+              params={{ storeId: store.id }}
+              className="no-underline"
+            >
+              <UserIcon className="size-4" />
+              {t('admin.account.edit_profile')}
+            </Link>
+          </DropdownMenuItem>
+        )}
+        <DropdownMenuSeparator />
+        <DropdownMenuItem>
+          <BookOpenIcon className="size-4" />
+          {t('admin.account.documentation')}
+        </DropdownMenuItem>
+        <DropdownMenuItem>
+          <MessageCircleIcon className="size-4" />
+          {t('admin.account.community')}
+        </DropdownMenuItem>
+        <DropdownMenuItem>
+          <MailIcon className="size-4" />
+          {t('admin.account.contact_support')}
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem onClick={logout} className="text-destructive focus:text-destructive">
+          <LogOutIcon className="size-4" />
+          {t('admin.account.log_out')}
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}

package/src/hooks/use-auth.ts

@@ -0,0 +1,10 @@
+import { useContext } from 'react'
+import { AuthContext } from '../providers/auth-provider'
+
+export function useAuth() {
+  const context = useContext(AuthContext)
+  if (!context) {
+    throw new Error('useAuth must be used within an AuthProvider')
+  }
+  return context
+}

package/src/hooks/use-command-palette.tsx

@@ -0,0 +1,34 @@
+import { useHotkey } from '@tanstack/react-hotkeys'
+import { createContext, type ReactNode, useContext, useMemo, useState } from 'react'
+
+interface CommandPaletteState {
+  open: boolean
+  setOpen: (open: boolean) => void
+}
+
+const CommandPaletteContext = createContext<CommandPaletteState | null>(null)
+
+/**
+ * Mounts at the app shell so the top-bar trigger, the global ⌘K shortcut, and
+ * the palette dialog itself share a single source of truth without
+ * prop-drilling through layouts.
+ */
+export function CommandPaletteProvider({ children }: { children: ReactNode }) {
+  const [open, setOpen] = useState(false)
+
+  useHotkey('Mod+K', () => {
+    setOpen((prev) => !prev)
+  })
+
+  const value = useMemo<CommandPaletteState>(() => ({ open, setOpen }), [open])
+
+  return <CommandPaletteContext.Provider value={value}>{children}</CommandPaletteContext.Provider>
+}
+
+export function useCommandPalette(): CommandPaletteState {
+  const ctx = useContext(CommandPaletteContext)
+  if (!ctx) {
+    throw new Error('useCommandPalette must be used within a CommandPaletteProvider')
+  }
+  return ctx
+}

package/src/hooks/use-countries.ts

@@ -0,0 +1,15 @@
+import type { Country } from '@spree/admin-sdk'
+import { useQuery } from '@tanstack/react-query'
+import { adminClient } from '../client'
+
+export function useCountries() {
+  const { data, isLoading } = useQuery({
+    queryKey: ['countries'],
+    queryFn: () => adminClient.countries.list({ expand: ['states'] }),
+    staleTime: 1000 * 60 * 30, // 30 minutes — countries rarely change
+  })
+
+  const countries: Country[] = data?.data ?? []
+
+  return { countries, isLoading }
+}

package/src/hooks/use-custom-fields.ts

@@ -0,0 +1,142 @@
+import type {
+  CustomFieldCreateParams,
+  CustomFieldDefinition,
+  CustomFieldDefinitionCreateParams,
+  CustomFieldDefinitionUpdateParams,
+  CustomFieldOwnerType,
+  CustomFieldUpdateParams,
+} from '@spree/admin-sdk'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { adminClient } from '../client'
+import { i18n } from '../lib/i18n'
+import { useResourceMutation } from './use-resource-mutation'
+
+const valuesKey = (ownerType: CustomFieldOwnerType, ownerId: string) =>
+  ['custom-fields', ownerType, ownerId] as const
+
+// Root key used to invalidate every definitions query at once. The
+// per-resource and per-id keys below extend it so TanStack's prefix
+// invalidation catches them.
+export const customFieldDefinitionsRootKey = ['custom-field-definitions'] as const
+
+const definitionsKey = (resourceType: string) =>
+  [...customFieldDefinitionsRootKey, resourceType] as const
+
+const definitionByIdKey = (id: string) => [...customFieldDefinitionsRootKey, 'id', id] as const
+
+export function useCustomFields(ownerType: CustomFieldOwnerType, ownerId: string) {
+  return useQuery({
+    queryKey: valuesKey(ownerType, ownerId),
+    queryFn: () => adminClient.customFields(ownerType, ownerId).list({ limit: 100 }),
+    enabled: !!ownerId,
+  })
+}
+
+export function useCustomFieldDefinitions(resourceType: string) {
+  return useQuery({
+    queryKey: definitionsKey(resourceType),
+    queryFn: () =>
+      adminClient.customFieldDefinitions.list({
+        limit: 100,
+        resource_type_eq: resourceType,
+      }),
+    enabled: !!resourceType,
+  })
+}
+
+export function useCreateCustomField(ownerType: CustomFieldOwnerType, ownerId: string) {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (params: CustomFieldCreateParams) =>
+      adminClient.customFields(ownerType, ownerId).create(params),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: valuesKey(ownerType, ownerId) })
+    },
+  })
+}
+
+export function useUpdateCustomField(ownerType: CustomFieldOwnerType, ownerId: string) {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: ({ id, ...params }: { id: string } & CustomFieldUpdateParams) =>
+      adminClient.customFields(ownerType, ownerId).update(id, params),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: valuesKey(ownerType, ownerId) })
+    },
+  })
+}
+
+export function useDeleteCustomField(ownerType: CustomFieldOwnerType, ownerId: string) {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => adminClient.customFields(ownerType, ownerId).delete(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: valuesKey(ownerType, ownerId) })
+    },
+  })
+}
+
+export function useCustomFieldDefinition(id: string | undefined) {
+  return useQuery({
+    queryKey: id ? definitionByIdKey(id) : [...customFieldDefinitionsRootKey, 'id', 'noop'],
+    queryFn: () => adminClient.customFieldDefinitions.get(id as string),
+    enabled: !!id,
+  })
+}
+
+/**
+ * Settings-page variant — no `resourceType` argument. Invalidates the root
+ * key, which covers every per-resource and per-id definition query.
+ *
+ * Toast + 422 handling come for free via `useResourceMutation`: validation
+ * errors surface inline through `mapSpreeErrorsToForm`, everything else
+ * (network, 5xx) shows a toast.
+ */
+export function useCreateCustomFieldDefinitionForSettings() {
+  return useResourceMutation<CustomFieldDefinition, Error, CustomFieldDefinitionCreateParams>({
+    mutationFn: (params) => adminClient.customFieldDefinitions.create(params),
+    invalidate: [customFieldDefinitionsRootKey],
+    successMessage: i18n.t('admin.custom_field_definitions.messages.created'),
+    errorMessage: i18n.t('admin.custom_field_definitions.errors.failed_to_create'),
+  })
+}
+
+export function useUpdateCustomFieldDefinitionForSettings(id: string) {
+  return useResourceMutation<CustomFieldDefinition, Error, CustomFieldDefinitionUpdateParams>({
+    mutationFn: (params) => adminClient.customFieldDefinitions.update(id, params),
+    invalidate: [customFieldDefinitionsRootKey, definitionByIdKey(id)],
+    successMessage: i18n.t('admin.custom_field_definitions.messages.updated'),
+    errorMessage: i18n.t('admin.custom_field_definitions.errors.failed_to_update'),
+  })
+}
+
+export function useDeleteCustomFieldDefinitionForSettings() {
+  const queryClient = useQueryClient()
+  return useResourceMutation<void, Error, string>({
+    mutationFn: (id) => adminClient.customFieldDefinitions.delete(id),
+    invalidate: [customFieldDefinitionsRootKey],
+    successMessage: i18n.t('admin.custom_field_definitions.messages.deleted'),
+    errorMessage: i18n.t('admin.custom_field_definitions.errors.failed_to_delete'),
+    onSuccess: (_data, id) => {
+      queryClient.removeQueries({ queryKey: definitionByIdKey(id) })
+    },
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Resource-scoped create — pins invalidation to a single `resourceType` so the
+// inline custom-fields card's definitions query re-validates the moment a field
+// is created in place (the create-definition sheet on a record detail page).
+// ---------------------------------------------------------------------------
+
+export function useCreateCustomFieldDefinition(resourceType: string) {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (params: CustomFieldDefinitionCreateParams) =>
+      adminClient.customFieldDefinitions.create(params),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: definitionsKey(resourceType) })
+      queryClient.invalidateQueries({ queryKey: customFieldDefinitionsRootKey })
+    },
+  })
+}

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

@@ -0,0 +1,104 @@
+import { useMutation } from '@tanstack/react-query'
+import SparkMD5 from 'spark-md5'
+import { adminClient } from '../client'
+
+function computeMD5Checksum(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunkSize = 2097152 // 2MB chunks
+    const spark = new SparkMD5.ArrayBuffer()
+    const reader = new FileReader()
+    let currentChunk = 0
+    const chunks = Math.ceil(file.size / chunkSize)
+
+    reader.onload = (e) => {
+      spark.append(e.target!.result as ArrayBuffer)
+      currentChunk++
+
+      if (currentChunk < chunks) {
+        loadNext()
+      } else {
+        // Active Storage expects base64-encoded raw MD5 digest
+        resolve(btoa(spark.end(true)))
+      }
+    }
+
+    reader.onerror = () => reject(reader.error)
+
+    function loadNext() {
+      const start = currentChunk * chunkSize
+      const end = Math.min(start + chunkSize, file.size)
+      reader.readAsArrayBuffer(file.slice(start, end))
+    }
+
+    loadNext()
+  })
+}
+
+interface UploadResult {
+  signedId: string
+  previewUrl: string
+}
+
+function sameOriginIfRailsDisk(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.pathname.startsWith('/rails/active_storage/')) {
+      return parsed.pathname + parsed.search
+    }
+    return url
+  } catch {
+    return url
+  }
+}
+
+export function useDirectUpload() {
+  return useMutation({
+    mutationFn: async (file: File): Promise<UploadResult> => {
+      const checksum = await computeMD5Checksum(file)
+
+      // Step 1: Get presigned upload URL
+      let response: {
+        direct_upload: { url: string; headers: Record<string, string> }
+        signed_id: string
+      }
+      try {
+        response = await adminClient.directUploads.create({
+          blob: {
+            filename: file.name,
+            byte_size: file.size,
+            checksum,
+            content_type: file.type || 'application/octet-stream',
+          },
+        })
+      } catch (err) {
+        throw new Error(`Presign failed: ${err instanceof Error ? err.message : err}`)
+      }
+
+      // Step 2: Upload file directly to storage.
+      //
+      // Active Storage's Disk service issues an absolute URL against the Rails
+      // origin (e.g. http://localhost:3000/rails/active_storage/disk/...). In
+      // dev the SPA runs on a different port and that controller doesn't speak
+      // CORS, so the browser blocks the cross-origin PUT before any response
+      // ("Failed to fetch"). When the URL points at a `/rails/active_storage/`
+      // path we drop the host so the request goes through Vite's `/rails`
+      // proxy and stays same-origin. Production S3 URLs are untouched.
+      const uploadUrl = sameOriginIfRailsDisk(response.direct_upload.url)
+      const uploadResponse = await fetch(uploadUrl, {
+        method: 'PUT',
+        headers: response.direct_upload.headers,
+        body: file,
+      })
+
+      if (!uploadResponse.ok) {
+        const text = await uploadResponse.text().catch(() => '')
+        throw new Error(`Storage upload failed (${uploadResponse.status}): ${text}`)
+      }
+
+      return {
+        signedId: response.signed_id,
+        previewUrl: URL.createObjectURL(file),
+      }
+    },
+  })
+}

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

@@ -0,0 +1,42 @@
+import { useMemo } from 'react'
+import { useTranslation } from 'react-i18next'
+
+/**
+ * Resolves a code to its display name via `Intl.DisplayNames`, localized to a
+ * given UI language. Returns `undefined` when the runtime lacks coverage so
+ * callers can apply their own fallback (the API name, the raw code, etc.).
+ *
+ * Standalone (non-hook) variant for module-level use outside React.
+ */
+export function intlDisplayName(
+  type: Intl.DisplayNamesType,
+  locale: string,
+  code: string,
+): string | undefined {
+  try {
+    return new Intl.DisplayNames([locale, 'en'], { type }).of(code)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Hook returning a memoized `code -> name` resolver for one `Intl.DisplayNames`
+ * type (`currency`, `language`, `region`, …), localized to the **admin UI
+ * language** (`i18n.language`) — NOT the store's content locale — so names
+ * match the rest of the dashboard chrome. Returns `undefined` on a miss; the
+ * caller supplies the fallback (e.g. `?? code`, `?? country.name`).
+ */
+export function useDisplayName(type: Intl.DisplayNamesType) {
+  const { i18n: instance } = useTranslation()
+  const locale = instance.language
+  return useMemo(() => {
+    let formatter: Intl.DisplayNames | undefined
+    try {
+      formatter = new Intl.DisplayNames([locale, 'en'], { type })
+    } catch {
+      formatter = undefined
+    }
+    return (code: string) => formatter?.of(code)
+  }, [locale, type])
+}