@spree/dashboard-core 0.1.0

package/src/components/preferences-form.tsx

@@ -0,0 +1,404 @@
+import type { PreferenceField as PreferenceFieldDef } from '@spree/admin-sdk'
+import {
+  Button,
+  Field,
+  FieldGroup,
+  FieldLabel,
+  Input,
+  SecretInput,
+  Switch,
+  Textarea,
+} from '@spree/dashboard-ui'
+import { PlusIcon, TrashIcon } from 'lucide-react'
+import { useId, useMemo, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { CurrencySelect } from './currency-select'
+
+/**
+ * Hydrates a `preferences` hash with each field's default. Used to seed
+ * create-mode forms when the user picks a provider/calculator so the
+ * `<PreferencesForm>` shows sensible starting values instead of blanks.
+ *
+ * `:password` fields are always skipped — the server returns their
+ * defaults as `null`, and even when it doesn't, autofilling a password
+ * field is hostile UX. `contextDefaults` fills schema-declared keys whose
+ * own default is null/undefined — used by callers that know about runtime
+ * context the schema can't express (e.g. the store's default currency).
+ */
+export function defaultPreferences(
+  schema: PreferenceFieldDef[],
+  contextDefaults: Record<string, unknown> = {},
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const field of schema) {
+    if (field.type === 'password') continue
+    if (field.default !== null && field.default !== undefined) {
+      out[field.key] = field.default
+      continue
+    }
+    const ctx = contextDefaults[field.key]
+    if (ctx !== undefined && ctx !== null && ctx !== '') out[field.key] = ctx
+  }
+  return out
+}
+
+interface PreferencesFormProps {
+  schema: PreferenceFieldDef[]
+  values: Record<string, unknown>
+  onChange: (next: Record<string, unknown>) => void
+  /** When true, replaces sensitive `password`-typed fields with a stub label. */
+  redactPasswords?: boolean
+  /** Optional human-readable name overrides keyed by preference key. */
+  labelOverrides?: Record<string, string>
+}
+
+/**
+ * Renders a generic configuration form from a `preference_schema` payload.
+ * Used by the Payment Methods edit sheet and the Promotion editor's action
+ * and rule cards — anywhere we let admins tune a STI subclass's settings
+ * without hard-coding a per-subclass form.
+ *
+ * The schema itself is the source of truth; this component intentionally
+ * stays "dumb" — server-side validation surfaces errors back via the
+ * mutation hook's error handling. Booleans are switches, strings are
+ * inputs, integers/decimals get number inputs, and unknown types fall
+ * back to a plain text input.
+ */
+export function PreferencesForm({
+  schema,
+  values,
+  onChange,
+  redactPasswords = false,
+  labelOverrides,
+}: PreferencesFormProps) {
+  if (!schema?.length) return null
+
+  function setValue(key: string, value: unknown) {
+    if (Object.is(values[key], value)) return
+    onChange({ ...values, [key]: value })
+  }
+
+  return (
+    <FieldGroup>
+      {schema.map((field) => (
+        <PreferenceField
+          key={field.key}
+          field={field}
+          value={values[field.key] ?? field.default}
+          label={labelOverrides?.[field.key]}
+          onChange={(v) => setValue(field.key, v)}
+          redactPasswords={redactPasswords}
+        />
+      ))}
+    </FieldGroup>
+  )
+}
+
+interface PreferenceFieldProps {
+  field: PreferenceFieldDef
+  value: unknown
+  label?: string
+  onChange: (value: unknown) => void
+  redactPasswords?: boolean
+}
+
+export function PreferenceField({
+  field,
+  value,
+  label,
+  onChange,
+  redactPasswords,
+}: PreferenceFieldProps) {
+  const { t, i18n } = useTranslation()
+  const id = `preference-${field.key}`
+  // Localize the field label from the preference key when no explicit
+  // override is given, falling back to a humanized key for custom/extension
+  // preferences that ship no translation.
+  const preferenceKey = `admin.preferences.${field.key}`
+  const displayLabel =
+    label ?? (i18n.exists(preferenceKey) ? t(preferenceKey) : humanizeKey(field.key))
+
+  // Currency-typed preferences (`currency`, `default_currency`,
+  // `display_currency`, …) get the store's CurrencySelect — same
+  // localized `CODE — Full Name` rendering as the rest of admin.
+  if (isCurrencyKey(field.key)) {
+    return (
+      <Field>
+        <FieldLabel htmlFor={id}>{displayLabel}</FieldLabel>
+        <CurrencySelect id={id} value={(value as string) ?? ''} onChange={onChange} />
+      </Field>
+    )
+  }
+
+  // `tiers` preference (Spree::Calculator::TieredPercent /
+  // TieredFlatRate) — a Hash<threshold, value> that the default
+  // hash-as-text input would render as `[object Object]`. Render a row
+  // editor so the merchant can add tier breakpoints directly.
+  if (field.key === 'tiers') {
+    return <TiersEditor value={value} onChange={onChange} />
+  }
+
+  switch (field.type) {
+    case 'boolean':
+      return (
+        <Field>
+          <div className="flex items-start justify-between gap-4">
+            <FieldLabel htmlFor={id} className="cursor-pointer">
+              {displayLabel}
+            </FieldLabel>
+            <Switch id={id} checked={!!value} onCheckedChange={(checked) => onChange(checked)} />
+          </div>
+        </Field>
+      )
+
+    case 'text':
+      return (
+        <Field>
+          <FieldLabel htmlFor={id}>{displayLabel}</FieldLabel>
+          <Textarea
+            id={id}
+            rows={4}
+            value={(value as string) ?? ''}
+            onChange={(e) => onChange(e.target.value)}
+          />
+        </Field>
+      )
+
+    case 'integer':
+    case 'decimal':
+      return (
+        <Field>
+          <FieldLabel htmlFor={id}>{displayLabel}</FieldLabel>
+          <Input
+            id={id}
+            type="number"
+            step={field.type === 'integer' ? 1 : 'any'}
+            value={value === null || value === undefined ? '' : String(value)}
+            onChange={(e) => {
+              const raw = e.target.value
+              if (raw === '') return onChange(null)
+              const parsed = field.type === 'integer' ? parseInt(raw, 10) : parseFloat(raw)
+              onChange(Number.isNaN(parsed) ? null : parsed)
+            }}
+          />
+        </Field>
+      )
+
+    case 'array':
+      // A generic "comma-separated list" works for the common case where
+      // arrays hold IDs or short tokens. Subclasses with structured
+      // arrays (option values, eligible products) ship with custom
+      // editors and don't reach here.
+      return (
+        <Field>
+          <FieldLabel htmlFor={id}>{displayLabel}</FieldLabel>
+          <Input
+            id={id}
+            value={Array.isArray(value) ? value.join(', ') : ((value as string) ?? '')}
+            placeholder={t('admin.components.preferences_form.comma_separated_hint')}
+            onChange={(e) =>
+              onChange(
+                e.target.value
+                  .split(',')
+                  .map((s) => s.trim())
+                  .filter(Boolean),
+              )
+            }
+          />
+          <span className="text-xs text-muted-foreground">
+            {t('admin.components.preferences_form.comma_separated_hint')}
+          </span>
+        </Field>
+      )
+
+    case 'password':
+      return (
+        <SecretInput
+          id={id}
+          label={displayLabel}
+          value={value}
+          onChange={onChange}
+          redactWhenMasked={!!redactPasswords}
+        />
+      )
+
+    default:
+      return (
+        <Field>
+          <FieldLabel htmlFor={id}>{displayLabel}</FieldLabel>
+          <Input
+            id={id}
+            value={(value as string) ?? ''}
+            onChange={(e) => onChange(e.target.value)}
+          />
+        </Field>
+      )
+  }
+}
+
+function humanizeKey(key: string): string {
+  return key
+    .split('_')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+function isCurrencyKey(key: string): boolean {
+  return key === 'currency' || key.endsWith('_currency')
+}
+
+interface TierRowState {
+  /** Stable across edits — used for React keys so input focus survives reorder. */
+  uid: string
+  threshold: string
+  value: string
+}
+
+/**
+ * Editor for `Spree::Calculator::TieredPercent` / `TieredFlatRate`
+ * preferences. The underlying shape is `Hash<threshold, value>` — orders
+ * at or above `threshold` get `value` (% or $ depending on the
+ * calculator).
+ *
+ * Owns its row list locally so the user can add an empty row and fill
+ * it in afterwards — projecting to the hash on every change would drop
+ * empty-threshold rows the moment they're added. Empty rows are
+ * filtered when projecting to the parent's hash value.
+ */
+function TiersEditor({
+  value,
+  onChange,
+}: {
+  value: unknown
+  onChange: (next: Record<string, number>) => void
+}) {
+  const { t } = useTranslation()
+  const idPrefix = useId()
+  // Seed once from the initial value. Subsequent rerenders driven by
+  // parent state (e.g. another preference field changes) keep our row
+  // list intact so the user doesn't lose their in-progress empty rows.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentional one-time seed
+  const initialRows = useMemo(() => parseTiers(value, idPrefix), [])
+  const [rows, setRows] = useState<TierRowState[]>(initialRows)
+
+  function commit(next: TierRowState[]) {
+    setRows(next)
+    const out: Record<string, number> = {}
+    for (const row of next) {
+      const t = row.threshold.trim()
+      if (!t) continue
+      const parsed = Number(row.value)
+      out[t] = Number.isFinite(parsed) ? parsed : 0
+    }
+    onChange(out)
+  }
+
+  function updateRow(uid: string, patch: Partial<Pick<TierRowState, 'threshold' | 'value'>>) {
+    commit(rows.map((row) => (row.uid === uid ? { ...row, ...patch } : row)))
+  }
+
+  function addRow() {
+    commit([
+      ...rows,
+      { uid: `${idPrefix}-${rows.length + 1}-${Date.now()}`, threshold: '', value: '' },
+    ])
+  }
+
+  function removeRow(uid: string) {
+    commit(rows.filter((row) => row.uid !== uid))
+  }
+
+  return (
+    <Field>
+      <FieldLabel>{t('admin.components.preferences_form.tiers.label')}</FieldLabel>
+      <div className="space-y-2">
+        {rows.length === 0 ? (
+          <p className="text-xs text-muted-foreground">
+            {t('admin.components.preferences_form.tiers.empty')}
+          </p>
+        ) : (
+          <div className="grid grid-cols-[1fr_1fr_auto] gap-2">
+            <span className="text-xs font-medium text-muted-foreground">
+              {t('admin.components.preferences_form.tiers.header_threshold')}
+            </span>
+            <span className="text-xs font-medium text-muted-foreground">
+              {t('admin.components.preferences_form.tiers.header_value')}
+            </span>
+            <span />
+            {rows.map((row) => (
+              <TierRow
+                key={row.uid}
+                row={row}
+                onChange={(patch) => updateRow(row.uid, patch)}
+                onRemove={() => removeRow(row.uid)}
+              />
+            ))}
+          </div>
+        )}
+        <Button type="button" variant="outline" size="sm" onClick={addRow}>
+          <PlusIcon className="size-4" />
+          {t('admin.components.preferences_form.tiers.add_tier')}
+        </Button>
+      </div>
+    </Field>
+  )
+}
+
+function TierRow({
+  row,
+  onChange,
+  onRemove,
+}: {
+  row: TierRowState
+  onChange: (patch: Partial<Pick<TierRowState, 'threshold' | 'value'>>) => void
+  onRemove: () => void
+}) {
+  const { t } = useTranslation()
+  return (
+    <>
+      <Input
+        type="number"
+        step="any"
+        min={0}
+        value={row.threshold}
+        placeholder="100"
+        onChange={(e) => onChange({ threshold: e.target.value })}
+      />
+      <Input
+        type="number"
+        step="any"
+        min={0}
+        value={row.value}
+        placeholder="10"
+        onChange={(e) => onChange({ value: e.target.value })}
+      />
+      <Button
+        type="button"
+        size="icon-sm"
+        variant="ghost"
+        onClick={onRemove}
+        aria-label={t('admin.components.preferences_form.tiers.remove_tier')}
+        className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+      >
+        <TrashIcon className="size-4" />
+      </Button>
+    </>
+  )
+}
+
+/**
+ * Normalize whatever shape the server sent — typically `Hash<number,
+ * number>` but JSON serialization stringifies the keys, so we may
+ * receive `{ "100": 10 }` or `{ 100: 10 }`. Either form converts to
+ * `TierRowState[]` for editor state.
+ */
+function parseTiers(value: unknown, idPrefix: string): TierRowState[] {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return []
+  return Object.entries(value as Record<string, unknown>)
+    .map(([threshold, v], i) => ({
+      uid: `${idPrefix}-seed-${i}`,
+      threshold: String(threshold),
+      value: v === null || v === undefined ? '' : String(v),
+    }))
+    .sort((a, b) => Number(a.threshold) - Number(b.threshold))
+}

package/src/components/resource-combobox.tsx

@@ -0,0 +1,126 @@
+import {
+  type ComboboxOption,
+  ResourceCombobox as HeadlessResourceCombobox,
+  type ResourceComboboxProps as HeadlessResourceComboboxProps,
+} from '@spree/dashboard-ui'
+import { useQuery } from '@tanstack/react-query'
+import { useDeferredValue, useMemo, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+
+export type { ComboboxOption } from '@spree/dashboard-ui'
+
+export interface ResourceComboboxProps<T extends ComboboxOption>
+  extends Pick<
+    HeadlessResourceComboboxProps<T>,
+    | 'value'
+    | 'onChange'
+    | 'getOptionLabel'
+    | 'renderOption'
+    | 'placeholder'
+    | 'emptyText'
+    | 'disabled'
+  > {
+  /**
+   * Server-side search. Called as the user types (debounced via React's
+   * `useDeferredValue`). Receives the trimmed query string — returning
+   * `{ data: [] }` for empty queries is a fine default, as is showing
+   * "recent records".
+   */
+  search: (query: string) => Promise<{ data: T[] }>
+
+  /**
+   * Hydrate the currently-selected ID into a record so the trigger can show
+   * its label (e.g. on first render after deep-link reload). Called once
+   * per `value` change. Should return the record listed by ID.
+   */
+  hydrate: (ids: string[]) => Promise<{ data: T[] }>
+
+  /** Stable cache prefix — e.g. `'gift-card-customer-picker'`. */
+  queryKey: string
+
+  /**
+   * Optional client-side predicate applied after fetch/hydrate to hide rows
+   * that should never be selectable (e.g. a category can't be its own parent).
+   * Returning `false` drops the row from the dropdown.
+   */
+  filterOption?: (option: T) => boolean
+}
+
+/**
+ * Search-driven single-select for a remote resource (customers, variants,
+ * stores, …). Wraps `@spree/dashboard-ui`'s pure `<ResourceCombobox>` with
+ * TanStack Query: `search` is called as the user types, `hydrate` resolves
+ * the currently-selected ID into a record on first render.
+ *
+ * Most callsites use this convenience wrapper. Reach for the headless version
+ * in `@spree/dashboard-ui` when the data flow doesn't match this shape
+ * (custom caching layer, local-only filtering, an externally-managed query).
+ */
+export function ResourceCombobox<T extends ComboboxOption>({
+  value,
+  onChange,
+  search,
+  hydrate,
+  queryKey,
+  getOptionLabel,
+  renderOption,
+  placeholder,
+  emptyText,
+  disabled,
+  filterOption,
+}: ResourceComboboxProps<T>) {
+  const { t } = useTranslation()
+  const placeholderLabel = placeholder ?? t('admin.common.search_placeholder')
+  const emptyLabel = emptyText ?? t('admin.common.no_results')
+
+  // Base UI's Combobox owns the input element so it can write the selected
+  // option's label into it on pick. We observe the typed query via
+  // `onInputChange` on the Root rather than controlling
+  // `<ComboboxInput value>` directly — controlling the input blocks Base UI
+  // from updating it on selection.
+  const [input, setInput] = useState('')
+  // Defer the search query so a fast typist doesn't fire one request per
+  // keystroke — React batches the search to the next idle paint.
+  const deferredInput = useDeferredValue(input)
+  const trimmedQuery = deferredInput.trim()
+
+  const { data: searchData } = useQuery({
+    queryKey: [queryKey, 'search', trimmedQuery],
+    queryFn: () => search(trimmedQuery),
+    staleTime: 30_000,
+  })
+
+  // Hydrate the currently selected ID into a record so the trigger shows
+  // its label after a deep-link reload (before the user types anything).
+  // Skipped when the search results already include the ID.
+  const searchHasValue = !!(value && searchData?.data.some((r) => r.id === value))
+  const { data: hydratedData } = useQuery({
+    queryKey: [queryKey, 'hydrate', value],
+    queryFn: () => hydrate([value as string]),
+    enabled: !!value && !searchHasValue,
+    staleTime: 60_000,
+  })
+
+  // Merge: prefer the (possibly fresher) search result if both have the ID.
+  const items = useMemo(() => {
+    const map = new Map<string, T>()
+    for (const r of hydratedData?.data ?? []) map.set(r.id, r)
+    for (const r of searchData?.data ?? []) map.set(r.id, r)
+    const merged = Array.from(map.values())
+    return filterOption ? merged.filter(filterOption) : merged
+  }, [searchData, hydratedData, filterOption])
+
+  return (
+    <HeadlessResourceCombobox
+      value={value}
+      onChange={onChange}
+      items={items}
+      onInputChange={setInput}
+      getOptionLabel={getOptionLabel}
+      renderOption={renderOption}
+      placeholder={placeholderLabel}
+      emptyText={emptyLabel}
+      disabled={disabled}
+    />
+  )
+}

package/src/components/resource-multi-autocomplete.tsx

@@ -0,0 +1,176 @@
+import {
+  type AutocompleteOption,
+  ResourceMultiAutocomplete as HeadlessResourceMultiAutocomplete,
+  type ResourceMultiAutocompleteProps as HeadlessResourceMultiAutocompleteProps,
+} from '@spree/dashboard-ui'
+import { useQuery } from '@tanstack/react-query'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+
+export type { AutocompleteOption } from '@spree/dashboard-ui'
+
+export interface ResourceMultiAutocompleteProps<T extends AutocompleteOption>
+  extends Pick<
+    HeadlessResourceMultiAutocompleteProps<T>,
+    | 'value'
+    | 'onChange'
+    | 'onResolvedOptionsChange'
+    | 'getOptionLabel'
+    | 'placeholder'
+    | 'emptyText'
+    | 'disabled'
+  > {
+  /**
+   * Server-side search. Receives the trimmed query string. Should return
+   * `{ data: T[] }`. Called any time the user types (with debouncing
+   * provided by the caller's queryClient if needed).
+   */
+  search: (query: string) => Promise<{ data: T[] }>
+
+  /**
+   * Hydration query for the IDs in `value` that we don't yet have
+   * details for. Called once per `idsToHydrate` change. Should return
+   * the listed records, in any order — they're keyed by `id`.
+   */
+  hydrate: (ids: string[]) => Promise<{ data: T[] }>
+
+  /** Stable cache key for this picker instance — e.g. `'rule-products'`. */
+  queryKey: string
+
+  /**
+   * Records to seed the dropdown with — shown before the user types
+   * anything. Use when the resource is small enough that the caller
+   * already holds the full list in a cached query (channels, markets,
+   * categories) and the "type to search" UX is overkill. Merges with
+   * `search` results once the user starts typing.
+   */
+  initialItems?: T[]
+}
+
+/**
+ * Search-driven multi-select for a remote resource. Wraps
+ * `@spree/dashboard-ui`'s headless `<ResourceMultiAutocomplete>` with
+ * TanStack Query: `search` fires as the user types; `hydrate` resolves any
+ * selected IDs not yet in the cache so chips render with labels even after
+ * a deep-link reload.
+ *
+ * Most callsites use this convenience wrapper. Reach for the headless
+ * version in `@spree/dashboard-ui` when the data flow doesn't match this
+ * shape (custom caching layer, local-only filtering, externally-managed
+ * query state).
+ */
+export function ResourceMultiAutocomplete<T extends AutocompleteOption>({
+  value,
+  onChange,
+  onResolvedOptionsChange,
+  search,
+  hydrate,
+  queryKey,
+  initialItems,
+  getOptionLabel,
+  placeholder,
+  emptyText,
+  disabled,
+}: ResourceMultiAutocompleteProps<T>) {
+  const [inputValue, setInputValue] = useState('')
+
+  // id → option cache. Survives across search queries so chips don't
+  // flicker when `value` changes. Stored as a `Map` in state so we never
+  // miss a render — TanStack Query's settle re-renders the component,
+  // which re-derives `selectedOptions`/`items` from this.
+  const [cache, setCache] = useState<Map<string, T>>(() => new Map())
+
+  const cacheItems = useCallback((items: T[]) => {
+    setCache((prev) => {
+      let next: Map<string, T> | null = null
+      for (const item of items) {
+        if (prev.get(item.id) === item) continue
+        next ??= new Map(prev)
+        next.set(item.id, item)
+      }
+      return next ?? prev
+    })
+  }, [])
+
+  // Hydrate any selected ID not yet in the cache. Recomputed when `value`
+  // or `cache` changes; the query key only contains the missing ids so
+  // re-toggling a known id doesn't refetch.
+  const idsToHydrate = useMemo(() => value.filter((id) => !cache.has(id)), [value, cache])
+
+  const { data: hydrateData } = useQuery({
+    queryKey: [queryKey, 'hydrate', idsToHydrate],
+    queryFn: () => hydrate(idsToHydrate),
+    enabled: idsToHydrate.length > 0,
+    staleTime: Number.POSITIVE_INFINITY,
+  })
+
+  const trimmedInput = inputValue.trim()
+
+  const { data: searchData, isFetching } = useQuery({
+    queryKey: [queryKey, 'search', trimmedInput],
+    queryFn: () => search(trimmedInput),
+    enabled: trimmedInput.length > 0,
+  })
+
+  // Mirror query results into the local id→option cache via an effect, not
+  // inside `queryFn`. When the picker remounts (filter panel reopens) with
+  // `staleTime: Infinity`, TanStack Query returns the cached result without
+  // re-running `queryFn`, so writes inside `queryFn` are skipped. Reading
+  // `data` here re-fires on every remount.
+  useEffect(() => {
+    if (hydrateData?.data?.length) cacheItems(hydrateData.data)
+  }, [hydrateData, cacheItems])
+
+  useEffect(() => {
+    if (searchData?.data?.length) cacheItems(searchData.data)
+  }, [searchData, cacheItems])
+
+  useEffect(() => {
+    if (initialItems?.length) cacheItems(initialItems)
+  }, [initialItems, cacheItems])
+
+  // Dropdown items — search results (or +initialItems+ when nothing has
+  // been typed yet), then any selected IDs not in results so the user
+  // can deselect chips via the dropdown.
+  const items = useMemo<T[]>(() => {
+    const seen = new Set<string>()
+    const list: T[] = []
+    const base = searchData?.data ?? (trimmedInput.length === 0 ? initialItems : null) ?? []
+    for (const item of base) {
+      if (seen.has(item.id)) continue
+      seen.add(item.id)
+      list.push(item)
+    }
+    for (const id of value) {
+      if (seen.has(id)) continue
+      const cached = cache.get(id)
+      if (cached) {
+        seen.add(id)
+        list.push(cached)
+      }
+    }
+    return list
+  }, [searchData, value, cache, initialItems, trimmedInput])
+
+  // Stub-fallback so chips show their ID until hydration lands.
+  const selectedOptions = useMemo<T[]>(
+    () => value.map((id) => cache.get(id) ?? ({ id } as T)),
+    [value, cache],
+  )
+
+  return (
+    <HeadlessResourceMultiAutocomplete
+      value={value}
+      onChange={onChange}
+      onResolvedOptionsChange={onResolvedOptionsChange}
+      items={items}
+      selectedOptions={selectedOptions}
+      inputValue={inputValue}
+      onInputChange={setInputValue}
+      getOptionLabel={getOptionLabel}
+      placeholder={placeholder}
+      emptyText={emptyText}
+      isFetching={isFetching}
+      disabled={disabled}
+    />
+  )
+}