Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

12.0 KB
Raw Blame
import type { ReactNode } from 'react'
import { ensureTimestampColumns } from './timestamp-columns'

// ============================================================================
// Types
// ============================================================================

/** Shared shape — every column has these regardless of filter type. */
interface ColumnDefBase<T = any> {
  key: string
  label: string
  /**
   * One sentence explaining what the column means, shown from an info icon
   * beside the header. For a figure whose name is not self-evident — what
   * counts as "available", which units are "reserved" — where the alternative
   * is a merchant guessing. Leave it off a column that explains itself.
   */
  labelHint?: string
  sortable?: boolean
  filterable?: boolean
  default?: boolean
  /**
   * What a `boolean` column's two states are called, where the domain has
   * better words than Yes and No — "Active" and "Inactive" on a catalog. The
   * filter control then says what the rows say, instead of asking a question
   * the column never posed. Ignored by every other filter type.
   */
  booleanLabels?: { true: string; false: string }
  /** Ransack attribute name if different from key (e.g., 'master_sku' for 'sku') */
  ransackAttribute?: string
  /** Send `ransackAttribute` as a Ransack scope: bare key, no operator suffix. */
  ransackScope?: boolean
  /** Custom cell renderer. If omitted, renders `row[key]` as text. */
  render?: (row: T) => ReactNode
  /**
   * `expand` value the list request needs while this column is visible
   * (e.g. `'custom_fields'`). ResourceTable unions the values across
   * visible columns into the `expand` query param.
   */
  expand?: string
  /** Cell className */
  className?: string
  /** Whether this column is displayable in the table. Set to false for filter-only columns. */
  displayable?: boolean
  /**
   * Surface this column as a always-visible control in the toolbar, beside the
   * search field, instead of only inside the filter popover.
   *
   * For the handful of filters an operator reaches for constantly — a status,
   * a date range — the popover costs an open, an "Add filter", a field pick, a
   * value pick and an Apply. A quick filter is the same `FilterRule` reached in
   * one click, so it shares the URL state, the chips and the export with
   * everything set the long way.
   *
   * Only `enum`/`boolean` (multi-select) and `date` (relative presets) render
   * one; the flag is ignored on other filter types.
   */
  quickFilter?: boolean
}

/**
 * Config for `filterType: 'resource'` — drives a `<ResourceMultiAutocomplete>`
 * inside the filter panel and hydrates labels in the active-filter chip.
 *
 * `search` is called as the user types. `hydrate` resolves currently-selected
 * IDs (deep-link reload, navigating back to the page) to records so the chip
 * can show human-readable names instead of raw prefixed IDs.
 */
export interface ResourceFilterConfig<R extends { id: string } = { id: string }> {
  /**
   * Leads every cache entry the filter creates, ahead of the tenant. Naming
   * it after the resource (`'markets'`) lets that resource's writes, which
   * invalidate `[resource, tenant]`, refresh the filter's lists too.
   */
  queryKey: string
  search: (query: string) => Promise<{ data: R[] }>
  hydrate: (ids: string[]) => Promise<{ data: R[] }>
  getOptionLabel: (option: R) => string
  placeholder?: string
  emptyText?: string
  /**
   * Fetches the whole list, for a resource small enough to show in full —
   * a store's warehouses, its channels. It is fetched once and cached under
   * `[queryKey, tenant, 'all']`; the filter narrows it as the operator types
   * and labels its chips from it, without further requests. Use the same
   * request as the resource's own full-list hook, which shares that key.
   * Leave it off for anything that could run to hundreds of rows.
   */
  listAll?: () => Promise<{ data: R[] }>
  /**
   * How long fetched options stay fresh, in milliseconds. Raise it for
   * rarely-changing resources whose writes invalidate `queryKey`.
   */
  staleTime?: number
}

/**
 * Resources that `TagCombobox` can target for tag autocomplete, by API
 * shorthand. The three first-class taggables get autocomplete hints, but the
 * union is open — apps can pass the shorthand of any type registered in
 * `Spree.taggable_types` on the server.
 */
export type TaggableType = 'product' | 'customer' | 'order' | (string & {})

/**
 * Column definition. Discriminated union on `filterType`:
 *   - `'enum'`     → `filterOptions` is **required**
 *   - `'resource'` → `filterResource` is **required** (multi-select picker)
 *   - `'tags'`     → `taggableType` is **required** (drives TagCombobox)
 *   - other types  → all variant fields must be omitted
 */
export type ColumnDef<T = any> =
  | (ColumnDefBase<T> & {
      filterType?: 'string' | 'boolean' | 'number' | 'date' | 'currency' | 'locale'
      filterOptions?: never
      filterResource?: never
      taggableType?: never
    })
  | (ColumnDefBase<T> & {
      filterType: 'enum'
      filterOptions: { value: string; label: string }[]
      filterResource?: never
      taggableType?: never
    })
  | (ColumnDefBase<T> & {
      filterType: 'resource'
      filterOptions?: never
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      filterResource: ResourceFilterConfig<any>
      taggableType?: never
    })
  | (ColumnDefBase<T> & {
      filterType: 'tags'
      filterOptions?: never
      filterResource?: never
      taggableType: TaggableType
    })

export interface FilterRule {
  id: string
  field: string
  operator: string
  /**
   * For array-valued operators (`in`, `not_in`) and the `'resource'` filter
   * type, the IDs are encoded as a trimmed CSV string. Use `parseFilterIds`
   * to decode and `ids.join(',')` to encode — keeps URL serialization simple.
   */
  value: string
}

export function parseFilterIds(value: string): string[] {
  return value
    .split(',')
    .map((s) => s.trim())
    .filter(Boolean)
}

export interface SortOption {
  field: string
  direction: 'asc' | 'desc'
}

export interface TableDef<T = any> {
  key: string
  title?: string
  /**
   * One line under the title saying what the list is for. Worth writing for
   * anything a merchant meets for the first time — catalogs, price lists,
   * transfers — and worth leaving off a list that explains itself.
   */
  description?: string
  /**
   * Documentation for the feature, appended to `description` as a "Learn more"
   * link. A path is relative to the user guide (`'catalogs'`); a full URL is
   * used as given, so a plugin can point at its own docs.
   */
  docsPath?: string
  columns: ColumnDef<T>[]
  searchParam?: string
  searchPlaceholder?: string
  defaultSort?: SortOption
  emptyIcon?: ReactNode
  emptyMessage?: string
}

// ============================================================================
// Registry
// ============================================================================

const registry = new Map<string, TableDef>()

/**
 * Queued mutations against tables that haven't been `defineTable`-d yet.
 *
 * Built-in tables register via side-effect imports in route files
 * (`import '@/tables/products'`) — they only execute when the route loads.
 * Plugin authors who call `tables.products.addColumn(...)` from their
 * boot-time entry module would race with that lazy registration. To avoid
 * forcing every plugin to know which routes have loaded, mutations on an
 * unregistered table are queued and replayed by `defineTable` when the
 * table appears.
 *
 * Mutations on tables that NEVER register stay in the queue and never fire,
 * which is the right semantics: a plugin extending an optional feature
 * shouldn't crash when that feature isn't installed.
 */
const pending = new Map<string, Array<(t: TableDef) => void>>()

function enqueue(tableKey: string, fn: (t: TableDef) => void) {
  const list = pending.get(tableKey) ?? []
  list.push(fn)
  pending.set(tableKey, list)
}

function flushPending(tableKey: string, table: TableDef) {
  const queue = pending.get(tableKey)
  if (!queue) return
  pending.delete(tableKey)
  // Iterate the full queue even if individual mutations throw. A plugin that
  // registers a duplicate column shouldn't silently drop every later mutation
  // for the same table — collect errors and surface them all.
  const errors: unknown[] = []
  for (const fn of queue) {
    try {
      fn(table)
    } catch (err) {
      errors.push(err)
    }
  }
  if (errors.length === 1) throw errors[0]
  if (errors.length > 1) {
    throw new AggregateError(errors, `${errors.length} mutation(s) failed for table "${tableKey}"`)
  }
}

export function defineTable<T = any>(key: string, def: Omit<TableDef<T>, 'key'>): TableDef<T> {
  const tableDef = {
    ...def,
    key,
    columns: ensureTimestampColumns(def.columns),
  } as TableDef<T>
  registry.set(key, tableDef)
  flushPending(key, tableDef as TableDef)
  return tableDef
}

export function getTable<T = any>(key: string): TableDef<T> {
  const table = registry.get(key)
  if (!table)
    throw new Error(`Table "${key}" is not registered. Call defineTable("${key}", ...) first.`)
  return table as TableDef<T>
}

// ============================================================================
// Mutation API — allows extensions to modify registered tables
// ============================================================================

export const tables = new Proxy({} as Record<string, TableMutator>, {
  get(_target, key: string) {
    return createMutator(key)
  },
})

interface TableMutator {
  addColumn<T = any>(column: ColumnDef<T>): void
  removeColumn(key: string): void
  updateColumn<T = any>(key: string, updates: Partial<ColumnDef<T>>): void
}

function applyAddColumn(table: TableDef, column: ColumnDef) {
  if (table.columns.some((c) => c.key === column.key)) {
    throw new Error(
      `Column "${column.key}" already exists in table "${table.key}". Use updateColumn() instead.`,
    )
  }
  table.columns.push(column)
}

function applyRemoveColumn(table: TableDef, key: string) {
  table.columns = table.columns.filter((c) => c.key !== key)
}

function applyUpdateColumn(table: TableDef, key: string, updates: Partial<ColumnDef>) {
  const col = table.columns.find((c) => c.key === key)
  if (!col) throw new Error(`Column "${key}" not found in table "${table.key}".`)
  Object.assign(col, updates)
}

function createMutator(tableKey: string): TableMutator {
  return {
    addColumn(column) {
      const table = registry.get(tableKey)
      if (table) applyAddColumn(table, column as ColumnDef)
      else enqueue(tableKey, (t) => applyAddColumn(t, column as ColumnDef))
    },
    removeColumn(key) {
      const table = registry.get(tableKey)
      if (table) applyRemoveColumn(table, key)
      else enqueue(tableKey, (t) => applyRemoveColumn(t, key))
    },
    updateColumn(key, updates) {
      const table = registry.get(tableKey)
      if (table) applyUpdateColumn(table, key, updates as Partial<ColumnDef>)
      else enqueue(tableKey, (t) => applyUpdateColumn(t, key, updates as Partial<ColumnDef>))
    },
  }
}

/** Test-only: clear the registry and any pending mutations. */
export function __resetTableRegistry(): void {
  registry.clear()
  pending.clear()
}

// ============================================================================
// Helpers
// ============================================================================

/** Get columns that are displayable (not filter-only) */
export function getDisplayableColumns<T = any>(table: TableDef<T>): ColumnDef<T>[] {
  return table.columns.filter((c) => c.displayable !== false)
}

/** Get default visible column keys */
export function getDefaultColumnKeys(table: TableDef): string[] {
  return getDisplayableColumns(table)
    .filter((c) => c.default)
    .map((c) => c.key)
}

/** Get columns that can be filtered */
export function getFilterableColumns(table: TableDef): ColumnDef[] {
  return table.columns.filter((c) => c.filterable)
}

/** Get columns that can be sorted */
export function getSortableColumns(table: TableDef): ColumnDef[] {
  return table.columns.filter((c) => c.sortable)
}