@spree/dashboard-core 0.1.0

package/src/hooks/use-export.ts

@@ -0,0 +1,75 @@
+import type { Export, ExportCreateParams } from '@spree/admin-sdk'
+import { useMutation } from '@tanstack/react-query'
+import { toast } from 'sonner'
+import { adminClient } from '../client'
+import { downloadFromApi } from '../lib/download'
+import { i18n } from '../lib/i18n'
+import { useAuth } from './use-auth'
+
+const POLL_INTERVAL_MS = 2000
+const POLL_TIMEOUT_MS = 5 * 60 * 1000
+
+class ExportTimeoutError extends Error {
+  constructor() {
+    super('Export timed out')
+    this.name = 'ExportTimeoutError'
+  }
+}
+
+async function pollUntilDone(id: string): Promise<Export> {
+  const deadline = Date.now() + POLL_TIMEOUT_MS
+
+  while (Date.now() < deadline) {
+    const exp = await adminClient.exports.get(id)
+    if (exp.done) return exp
+    await new Promise<void>((resolve) => setTimeout(resolve, POLL_INTERVAL_MS))
+  }
+
+  throw new ExportTimeoutError()
+}
+
+async function downloadExportFile(exp: Export, token: string | null): Promise<void> {
+  if (!exp.download_url) throw new Error('Export has no download_url')
+
+  await downloadFromApi(token, exp.download_url, exp.filename ?? 'export.csv')
+}
+
+/**
+ * Queue a CSV export and drive it to completion: create → poll → download.
+ * On poll timeout, falls back to the email-link path —
+ * `Spree::ExportMailer.export_done` already covers that server-side.
+ */
+export function useExport() {
+  const { token } = useAuth()
+
+  return useMutation({
+    mutationFn: async (params: ExportCreateParams) => {
+      // Per-invocation id so concurrent exports don't collide on a single
+      // sticky toast.
+      const toastId = `export-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+      toast.loading(i18n.t('admin.components.export_button.preparing'), { id: toastId })
+
+      try {
+        const created = await adminClient.exports.create(params)
+        const finished = await pollUntilDone(created.id)
+        await downloadExportFile(finished, token)
+        toast.success(i18n.t('admin.components.export_button.downloaded'), { id: toastId })
+        return finished
+      } catch (err) {
+        if (err instanceof ExportTimeoutError) {
+          toast.info(i18n.t('admin.components.export_button.email_fallback'), {
+            id: toastId,
+          })
+        } else {
+          toast.error(
+            i18n.t('admin.components.export_button.failed', {
+              message: err instanceof Error ? err.message : String(err),
+            }),
+            { id: toastId },
+          )
+        }
+        throw err
+      }
+    },
+  })
+}

package/src/hooks/use-global-search.ts

@@ -0,0 +1,79 @@
+import { useQueries } from '@tanstack/react-query'
+import { useEffect, useState } from 'react'
+import { useAuth } from '../hooks/use-auth'
+import { type SearchEntry, useSearchEntries } from '../lib/search-registry'
+import { usePermissions } from '../providers/permission-provider'
+import { useStore } from '../providers/store-provider'
+
+const RESULT_LIMIT = 5
+const MIN_QUERY_LENGTH = 2
+const DEBOUNCE_MS = 200
+const GC_TIME_MS = 60_000
+const STALE_TIME_MS = 30_000
+
+export interface SearchGroup {
+  entry: SearchEntry
+  items: unknown[]
+}
+
+/**
+ * One parallel `?q[search]=…&limit=5` query per registered, permitted search
+ * entry — products, orders, customers, promotions, and anything a plugin adds.
+ * Each resource defines a `search` Ransack scope server-side that does
+ * multi-field LIKE matching, so we pass a single `search` param and let the
+ * server decide what to match.
+ *
+ * The query is debounced so a fast typist doesn't fan out a wave of in-flight
+ * requests; results are cached briefly (and scoped by user + store) so backspace
+ * feels instant but they don't pile up or leak across users or stores.
+ */
+export function useGlobalSearch(rawQuery: string) {
+  // Trim once: the cache key and the server query must match what `enabled`
+  // gates on, or " hello" and "hello" fan out as separate cache entries and the
+  // stray space leaks into the `cont` predicate (`LIKE %hello %`), missing rows.
+  const query = useDebouncedValue(rawQuery, DEBOUNCE_MS).trim()
+  const enabled = query.length >= MIN_QUERY_LENGTH
+  const entries = useSearchEntries()
+  const { permissions, isLoading: permissionsLoading } = usePermissions()
+  const { storeId } = useStore()
+  const { user } = useAuth()
+
+  const permitted = entries.filter((e) => !e.subject || permissions.can('read', e.subject))
+
+  const results = useQueries({
+    queries: permitted.map((entry) => ({
+      // Scope by user so a logout→login on the same store can't serve the
+      // previous user's cached results from React Query.
+      queryKey: ['cmdk', user?.id, storeId, entry.key, query],
+      queryFn: () => entry.fetch(query, RESULT_LIMIT),
+      enabled,
+      gcTime: GC_TIME_MS,
+      staleTime: STALE_TIME_MS,
+    })),
+  })
+
+  const groups: SearchGroup[] = permitted
+    .map((entry, i) => ({ entry, items: results[i]?.data ?? [] }))
+    .filter((g) => g.items.length > 0)
+
+  return {
+    groups,
+    // Treat the permission fetch as loading: until rules land, every gated
+    // entry is filtered out and no queries run, so without this the palette
+    // would flash "no results" before search has effectively started.
+    isLoading: enabled && (permissionsLoading || results.some((r) => r.isLoading)),
+    isEnabled: enabled,
+    hasResults: groups.length > 0,
+  }
+}
+
+function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value)
+
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delayMs)
+    return () => clearTimeout(id)
+  }, [value, delayMs])
+
+  return debounced
+}

package/src/hooks/use-host-form.ts

@@ -0,0 +1,34 @@
+import { type FieldValues, type UseFormReturn, useFormContext } from 'react-hook-form'
+
+/**
+ * The react-hook-form instance of the built-in resource form a slot widget is
+ * rendered inside (e.g. the product detail form for `product.form_sidebar`).
+ * Fields registered against it — `form.register(...)` or `<Controller>` —
+ * hydrate, dirty-track, and persist through the host page's own Save button;
+ * the widget ships no save logic of its own.
+ *
+ * Only forms that opt in provide a host form (they wrap themselves in RHF's
+ * `FormProvider`). Slots on pages without a page-wide form (orders,
+ * customers) have none — calling this there throws. Use
+ * `useOptionalHostForm()` for widgets that render in both kinds of context.
+ */
+export function useHostForm<
+  TFieldValues extends FieldValues = FieldValues,
+>(): UseFormReturn<TFieldValues> {
+  const form = useFormContext<TFieldValues>()
+  if (!form) {
+    throw new Error(
+      'useHostForm() must be rendered inside a resource form that exposes its form context ' +
+        '(e.g. a product.form_sidebar slot widget). This page has no host form — ' +
+        'use useOptionalHostForm() and fall back to your own state + API save.',
+    )
+  }
+  return form
+}
+
+/** Like {@link useHostForm}, but returns `null` when there is no host form. */
+export function useOptionalHostForm<
+  TFieldValues extends FieldValues = FieldValues,
+>(): UseFormReturn<TFieldValues> | null {
+  return useFormContext<TFieldValues>() ?? null
+}

package/src/hooks/use-import.ts

@@ -0,0 +1,62 @@
+import type { Import, ImportCreateParams, ImportType } from '@spree/admin-sdk'
+import { useMutation } from '@tanstack/react-query'
+import { adminClient } from '../client'
+import { downloadFromApi } from '../lib/download'
+import { useStore } from '../providers/store-provider'
+import { useAuth } from './use-auth'
+
+export interface CreateImportInput {
+  type: ImportType
+  /** Signed blob id of the already direct-uploaded CSV (see `FileUploadField`). */
+  signedId: string
+  preferredDelimiter?: ImportCreateParams['preferred_delimiter']
+}
+
+/**
+ * Creates the import from a direct-uploaded CSV; the response is in the
+ * `mapping` state and carries the mapping payload.
+ */
+export function useCreateImport() {
+  const { storeId } = useStore()
+
+  return useMutation({
+    mutationFn: ({ type, signedId, preferredDelimiter }: CreateImportInput): Promise<Import> =>
+      adminClient.imports.create({
+        type,
+        attachment: signedId,
+        preferred_delimiter: preferredDelimiter,
+        // The import-done email deep-links back to the wizard (`?import=<id>`
+        // appended server-side). Only honored when this origin is on the
+        // store's allowed-origins list.
+        results_url: `${window.location.origin}/${storeId}/settings/imports`,
+      }),
+  })
+}
+
+/** Downloads the CSV template for an import type. */
+export function useDownloadImportTemplate() {
+  const { token } = useAuth()
+
+  return useMutation({
+    mutationFn: (type: ImportType) =>
+      downloadFromApi(
+        token,
+        `/api/v3/admin/imports/template?type=${encodeURIComponent(type)}`,
+        'import_template.csv',
+      ),
+  })
+}
+
+/** Downloads the originally uploaded CSV of an import — the audit trail. */
+export function useDownloadImportOriginal() {
+  const { token } = useAuth()
+
+  return useMutation({
+    mutationFn: (imp: Import) =>
+      downloadFromApi(
+        token,
+        imp.original_file_url ?? `/api/v3/admin/imports/${imp.id}/download`,
+        imp.original_filename ?? 'import.csv',
+      ),
+  })
+}

package/src/hooks/use-resource-mutation.ts

@@ -0,0 +1,99 @@
+import { SpreeError } from '@spree/admin-sdk'
+import {
+  type QueryKey,
+  type UseMutationOptions,
+  useMutation,
+  useQueryClient,
+} from '@tanstack/react-query'
+import { toast } from 'sonner'
+import { i18n } from '../lib/i18n'
+import { withStoreScope } from '../lib/query-keys'
+import { useStore } from '../providers/store-provider'
+
+interface UseResourceMutationOptions<TData, TError, TVariables>
+  extends Omit<UseMutationOptions<TData, TError, TVariables>, 'onSuccess' | 'onError'> {
+  /**
+   * Query keys to invalidate after success. Pass logical keys without
+   * storeId (e.g. `[['channels'], ['channels', id]]`) — the hook injects the
+   * current storeId at position 1 automatically so invalidation matches the
+   * store-scoped keys used by `ResourceTable` and other queries.
+   *
+   * Mutations that change setup-task state (see `Spree.store_setup_tasks` on
+   * the backend) must also invalidate `[STORE_QUERY_RESOURCE]` so the Getting
+   * Started checklist and the nav progress badge stay live.
+   */
+  invalidate?: QueryKey[]
+  /** Toast on success. Pass `false` to disable. Default `'Saved'`. */
+  successMessage?: string | false
+  /**
+   * Toast on error. Pass `false` to disable. Default `'Something went wrong'`.
+   *
+   * 422 validation errors never toast — callers that surface them inline via
+   * `mapSpreeErrorsToForm` would otherwise show the same problem twice. The
+   * toast is reserved for failures the form can't render (network, 5xx,
+   * auth, gateway).
+   */
+  errorMessage?: string | false
+  /** Forwarded onSuccess callback. Runs after invalidation + toast. */
+  onSuccess?: UseMutationOptions<TData, TError, TVariables>['onSuccess']
+  /** Forwarded onError callback. Runs after error toast. */
+  onError?: UseMutationOptions<TData, TError, TVariables>['onError']
+}
+
+/**
+ * Wrapper around `useMutation` that bundles the two patterns every resource
+ * mutation needs: query invalidation and success/error toasts.
+ *
+ * Replaces the per-page `try/catch + toast.success/toast.error` boilerplate.
+ *
+ * ```ts
+ * const updateProduct = useResourceMutation({
+ *   mutationFn: (params) => adminClient.products.update(id, params),
+ *   invalidate: [productQueryKey(id), productsQueryKey],
+ *   successMessage: 'Product saved',
+ *   errorMessage: 'Failed to save product',
+ * })
+ * ```
+ */
+export function useResourceMutation<TData = unknown, TError = Error, TVariables = void>(
+  options: UseResourceMutationOptions<TData, TError, TVariables>,
+) {
+  const queryClient = useQueryClient()
+  const { storeId } = useStore()
+  const {
+    invalidate,
+    successMessage = i18n.t('admin.messages.saved'),
+    errorMessage = i18n.t('admin.errors.generic'),
+    onSuccess,
+    onError,
+    ...rest
+  } = options
+
+  return useMutation<TData, TError, TVariables>({
+    ...rest,
+    onSuccess: (data, variables, onMutateResult, ctx) => {
+      if (invalidate) {
+        for (const key of invalidate) {
+          queryClient.invalidateQueries({ queryKey: withStoreScope(key, storeId) })
+        }
+      }
+      if (successMessage !== false) {
+        toast.success(successMessage)
+      }
+      return onSuccess?.(data, variables, onMutateResult, ctx)
+    },
+    onError: (error, variables, onMutateResult, ctx) => {
+      if (errorMessage !== false && !isValidationError(error)) {
+        toast.error(errorMessage)
+      }
+      return onError?.(error, variables, onMutateResult, ctx)
+    },
+  })
+}
+
+// 422 with `details` means the model rejected the payload (e.g., "Code can't
+// be blank"). The form renders these next to the offending input via
+// `mapSpreeErrorsToForm`, so toasting the same thing would just be noise.
+function isValidationError(error: unknown): boolean {
+  return error instanceof SpreeError && error.status === 422
+}

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

@@ -0,0 +1,55 @@
+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'
+
+/**
+ * Returns a function that switches the admin UI language and makes it stick.
+ *
+ * Switching the UI language is a three-step operation that every entry point
+ * (top-bar switcher, profile form, store settings) must perform identically:
+ *
+ *  1. Persist `selected_locale` to the ACCOUNT (`PATCH /me`) — not just
+ *     localStorage. The auth provider treats the account's `selected_locale`
+ *     as the cross-device source of truth and reverts a localStorage-only
+ *     switch on the next session bootstrap.
+ *  2. Mirror the change into the auth context so the in-memory user (top-bar,
+ *     etc.) reflects it immediately instead of waiting for the next refresh.
+ *  3. `switchLocale` persists the choice and reloads so every module-load
+ *     `i18n.t(...)` label re-resolves in the new language.
+ *
+ * A failed PATCH leaves localStorage and the page untouched (no desync) and
+ * surfaces an error toast. Fully a no-op only when the account ALREADY records
+ * `code` and the UI is already displaying it — otherwise the account is brought
+ * in sync even if the UI happens to match (e.g. the language was applied via the
+ * store-default fallback, which writes localStorage but leaves the account
+ * `selected_locale` null), and the page reloads only when the displayed language
+ * actually changes.
+ *
+ * @returns an async `switchAdminLocale(code)` performing the full sequence
+ */
+export function useSwitchAdminLocale() {
+  const { t } = useTranslation()
+  const { user, updateUser } = useAuth()
+
+  return async (code: string): Promise<void> => {
+    // Already adopted on the account AND on screen — nothing to do.
+    if (code === user?.selected_locale && code === i18n.language) return
+    try {
+      const { user: updated } = await adminClient.me.update({ selected_locale: code })
+      updateUser(updated)
+      if (code !== i18n.language) {
+        // Displayed language changes — persist the genuine choice + reload.
+        switchLocale(code)
+      } else {
+        // Already on screen: no reload, but still record it as a GENUINE choice
+        // (clearing any store-default auto-marker) so a later store switch can't
+        // override what the admin explicitly picked.
+        markGenuineLocaleChoice(code)
+      }
+    } catch {
+      toast.error(t('admin.account.language.update_failed'))
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,97 @@
+/// <reference path="./virtual.d.ts" />
+// @spree/dashboard-core — Spree Dashboard framework.
+//
+// The extension API for plugin authors. Consumers import flat from this barrel:
+//
+//     import { useAuth, defineTable, registerSlot, nav } from '@spree/dashboard-core'
+//
+// Or use the focused entry points:
+//
+//     import { defineDashboardPlugin } from '@spree/dashboard-core/plugin'
+//     import { AuthProvider } from '@spree/dashboard-core/providers/auth-provider'
+//     import { useResourceMutation } from '@spree/dashboard-core/hooks/use-resource-mutation'
+
+// ---------------------------------------------------------------------------
+// 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-sidebar'
+export * from './components/bulk-action-bar'
+export * from './components/can'
+export * from './components/country-combobox'
+export * from './components/country-state-fields'
+export * from './components/currency-select'
+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/locale-select'
+export * from './components/market-combobox'
+export * from './components/nav-main'
+export * from './components/page-header'
+export * from './components/page-tabs'
+export * from './components/preferences-form'
+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/settings-sidebar'
+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'
+// ---------------------------------------------------------------------------
+// Infra hooks
+// ---------------------------------------------------------------------------
+export * from './hooks/use-auth'
+export * from './hooks/use-command-palette'
+export * from './hooks/use-countries'
+export * from './hooks/use-custom-fields'
+export * from './hooks/use-direct-upload'
+export * from './hooks/use-display-name'
+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-resource-mutation'
+export * from './hooks/use-switch-admin-locale'
+// ---------------------------------------------------------------------------
+// Registries — pluggable extension points (nav, route, slot, table,
+// settings-nav, form fields, custom field components)
+// ---------------------------------------------------------------------------
+export * from './lib/custom-field-components'
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+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'
+// 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/nav-registry'
+export * from './lib/permissions'
+export * from './lib/query-client'
+export * from './lib/query-keys'
+export * from './lib/route-registry'
+export * from './lib/search-registry'
+export * from './lib/settings-nav-registry'
+export * from './lib/slot-registry'
+export * from './lib/table-registry'
+export { ensureTimestampColumns } from './lib/timestamp-columns'
+// ---------------------------------------------------------------------------
+// Plugin facade — re-exported for convenience; same API as `/plugin` subpath
+// ---------------------------------------------------------------------------
+export * from './plugin'
+// ---------------------------------------------------------------------------
+// Providers — must be mounted by the consuming app shell
+// ---------------------------------------------------------------------------
+export * from './providers/auth-provider'
+export * from './providers/permission-provider'
+export * from './providers/store-provider'

package/src/lib/custom-field-components.ts

@@ -0,0 +1,56 @@
+import type { CustomFieldDefinition } from '@spree/admin-sdk'
+import type { ComponentType } from 'react'
+
+/**
+ * Props a custom field input component receives from the custom-fields card.
+ * The component is a controlled input: render `value`, call `onChange` with
+ * the next value — hydration and persistence are the card's concern (the
+ * page form's Save for products/categories, the card's own Save elsewhere).
+ */
+export interface CustomFieldComponentProps {
+  /** DOM id — wire it to your input for the card's `<label htmlFor>`. */
+  id: string
+  ariaLabel: string
+  value: unknown
+  onChange: (value: unknown) => void
+  /** The full definition (field_type, config, namespace, key, …). */
+  definition: CustomFieldDefinition
+}
+
+export type CustomFieldComponent = ComponentType<CustomFieldComponentProps>
+
+const components = new Map<string, CustomFieldComponent>()
+
+/**
+ * Replace the input widget for a specific custom field definition, keyed by
+ * its `namespace.key` identity (e.g. `'specs.color'`). When no component is
+ * registered for a definition, the default widget for its `field_type`
+ * renders — registering is purely additive.
+ *
+ * Keying by the definition's own identity (rather than a separate component
+ * ID the definition would reference) means there's no stringly-typed
+ * indirection to typo: the plugin that ships the definition registers the
+ * component for it in the same breath.
+ */
+export const customFieldComponents = {
+  register(namespaceDotKey: string, component: CustomFieldComponent): void {
+    if (components.has(namespaceDotKey)) {
+      throw new Error(`A custom field component is already registered for "${namespaceDotKey}".`)
+    }
+    components.set(namespaceDotKey, component)
+  },
+
+  get(namespaceDotKey: string): CustomFieldComponent | undefined {
+    return components.get(namespaceDotKey)
+  },
+
+  /** Remove a registered component. No-op when absent. */
+  remove(namespaceDotKey: string): void {
+    components.delete(namespaceDotKey)
+  },
+}
+
+/** Test-only: clear the registry. Not exported from the package index. */
+export function __resetCustomFieldComponents(): void {
+  components.clear()
+}

package/src/lib/download.ts

@@ -0,0 +1,49 @@
+const API_BASE_URL = import.meta.env.VITE_SPREE_API_URL || ''
+
+/**
+ * Resolve `urlOrPath` (a path or absolute URL) against the API base and
+ * report whether it targets the trusted API origin. Origins are computed
+ * lazily so importing this module never touches `window` (node test envs).
+ */
+function resolveApiUrl(urlOrPath: string): { url: string; sameOrigin: boolean } {
+  const url = /^https?:\/\//.test(urlOrPath) ? urlOrPath : `${API_BASE_URL}${urlOrPath}`
+  const apiOrigin = API_BASE_URL ? new URL(API_BASE_URL).origin : window.location.origin
+  const sameOrigin = new URL(url, window.location.origin).origin === apiOrigin
+  return { url, sameOrigin }
+}
+
+/**
+ * Authed fetch → Blob URL download for JWT-protected endpoints — a top-level
+ * navigation cannot carry the in-memory token. Only requests to the API
+ * origin get the `Authorization` header and cookies, so the token can't leak
+ * to a third-party host (e.g. a URL echoed back by the server). The filename
+ * comes from `Content-Disposition` when present, else `fallbackName`.
+ */
+export async function downloadFromApi(
+  token: string | null,
+  urlOrPath: string,
+  fallbackName: string,
+): Promise<void> {
+  const { url, sameOrigin } = resolveApiUrl(urlOrPath)
+  const headers: Record<string, string> = {}
+  if (sameOrigin && token) headers.Authorization = `Bearer ${token}`
+
+  const response = await fetch(url, {
+    headers,
+    credentials: sameOrigin ? 'include' : 'omit',
+  })
+  if (!response.ok) throw new Error(`Download failed: ${response.status}`)
+
+  const disposition = response.headers.get('Content-Disposition')
+  const filename = disposition?.match(/filename="?([^";]+)"?/)?.[1] ?? fallbackName
+
+  const blob = await response.blob()
+  const objectUrl = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = objectUrl
+  anchor.download = filename
+  document.body.appendChild(anchor)
+  anchor.click()
+  anchor.remove()
+  URL.revokeObjectURL(objectUrl)
+}

package/src/lib/filters-to-ransack.ts

@@ -0,0 +1,47 @@
+import { type ColumnDef, type FilterRule, parseFilterIds } from './table-registry'
+
+/**
+ * Convert toolbar `FilterRule[]` state into a flat Ransack predicate hash:
+ *
+ *   [{ field: 'name', operator: 'cont', value: 'shirt' }]
+ *
+ * becomes
+ *
+ *   { name_cont: 'shirt' }
+ *
+ * Columns can override the predicate target via `ransackAttribute` (e.g.
+ * the `sku` column on products filters through `master_sku_cont`).
+ *
+ * The output shape is what both the list endpoints (after
+ * `transformListParams` wraps each key in `q[...]`) and the export endpoint
+ * (which stores the hash as `search_params`) expect.
+ */
+// Array-valued operators get a `[]` suffix so `transformListParams` emits
+// `q[xxx_in][]=...` for each item. The chip stores the IDs as a CSV string
+// in `FilterRule.value` so the URL serializer (which already JSON-stringifies
+// FilterRule[]) stays simple.
+const ARRAY_OPERATORS = new Set(['in', 'not_in'])
+
+export function filtersToRansack(
+  filters: FilterRule[],
+  columns: ColumnDef[],
+): Record<string, string | string[]> {
+  const out: Record<string, string | string[]> = {}
+  for (const filter of filters) {
+    const col = columns.find((c) => c.key === filter.field)
+    // `filterType: 'tags'` rides on the polymorphic `tags` association exposed
+    // via `acts_as_taggable_on`. Predicates target the join's `name` column
+    // (`tags_name_in`), not the column key (`tags_in`), so default the
+    // ransack alias here when one isn't explicitly set.
+    const fallback = col?.filterType === 'tags' ? 'tags_name' : filter.field
+    const ransackKey = col?.ransackAttribute ?? fallback
+    const key = `${ransackKey}_${filter.operator}`
+    if (ARRAY_OPERATORS.has(filter.operator)) {
+      const ids = parseFilterIds(filter.value)
+      if (ids.length > 0) out[key] = ids
+    } else {
+      out[key] = filter.value
+    }
+  }
+  return out
+}