@pilotiq/pilotiq 0.1.0

package/src/actions/ActionGroup.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Action } from './Action.js'
+import { ActionGroup } from './ActionGroup.js'
+import { resolveSchema, _resetResolverRegistry } from '../schema/resolveSchema.js'
+
+beforeEach(() => _resetResolverRegistry())
+
+describe('ActionGroup builder', () => {
+  it('emits type=actionGroup with sensible defaults', () => {
+    const meta = ActionGroup.make('manage').toMeta()
+    assert.equal(meta.type,      'actionGroup')
+    assert.equal(meta.name,      'manage')
+    assert.equal(meta.label,     'Manage')  // auto-derived
+    assert.equal(meta.placement, 'inline')
+  })
+
+  it('label() / icon() / tooltip() round-trip', () => {
+    const meta = ActionGroup.make('m').label('More').icon('more-horizontal').tooltip('More actions').toMeta()
+    assert.equal(meta.label,   'More')
+    assert.equal(meta.icon,    'more-horizontal')
+    assert.equal(meta.tooltip, 'More actions')
+  })
+
+  it('placement helpers', () => {
+    assert.equal(ActionGroup.make('a').header().toMeta().placement, 'header')
+    assert.equal(ActionGroup.make('a').row().toMeta().placement,    'row')
+    assert.equal(ActionGroup.make('a').bulk().toMeta().placement,   'bulk')
+  })
+
+  it('cosmetic builders round-trip', () => {
+    const meta = ActionGroup.make('a').color('success').size('lg').outlined().iconButton().toMeta()
+    assert.equal(meta.color,    'success')
+    assert.equal(meta.size,     'lg')
+    assert.equal(meta.outlined, true)
+    assert.equal(meta.iconOnly, true)
+  })
+
+  it('actions() stores the children', () => {
+    const g = ActionGroup.make('m').actions([
+      Action.make('export'),
+      Action.make('archive'),
+    ])
+    const children = g.getActions()
+    assert.deepEqual(children.map(a => a.name), ['export', 'archive'])
+  })
+
+  it('actions() flattens nested ActionGroups', () => {
+    const inner = ActionGroup.make('inner').actions([Action.make('a'), Action.make('b')])
+    const outer = ActionGroup.make('outer').actions([Action.make('c'), inner])
+    assert.deepEqual(outer.getActions().map(a => a.name), ['c', 'a', 'b'])
+  })
+
+  it('hasVisibilityRules detects any rule', () => {
+    assert.equal(ActionGroup.make('a').hasVisibilityRules(), false)
+    assert.equal(ActionGroup.make('a').visible(true).hasVisibilityRules(), true)
+  })
+
+  it('evaluate combines visible and hidden via AND', async () => {
+    const g = ActionGroup.make('a').visible(true).hidden(({ user }) => (user as { admin?: boolean })?.admin === false)
+    assert.equal((await g.evaluate({ user: { admin: true  } })).visible, true)
+    assert.equal((await g.evaluate({ user: { admin: false } })).visible, false)
+  })
+
+  it('toMeta emits conditional:true when rules exist', () => {
+    assert.equal(ActionGroup.make('a').toMeta().conditional, undefined)
+    assert.equal(ActionGroup.make('a').visible(true).toMeta().conditional, true)
+  })
+})
+
+describe('ActionGroup through resolveSchema', () => {
+  it('drops the group when its rule resolves to !visible', async () => {
+    const tree = [ActionGroup.make('hidden').visible(false).actions([Action.make('a')])]
+    const result = await resolveSchema(tree)
+    assert.equal(result.length, 0)
+  })
+
+  it('serializes children as meta.children', async () => {
+    const tree = [
+      ActionGroup.make('m').actions([
+        Action.make('export'),
+        Action.make('delete').destructive(),
+      ]),
+    ]
+    const result = await resolveSchema(tree)
+    assert.equal(result[0]!.type, 'actionGroup')
+    assert.equal(result[0]!.children?.length, 2)
+    assert.equal(result[0]!.children![0]!['name'], 'export')
+    assert.equal(result[0]!.children![1]!['destructive'], true)
+  })
+
+  it('child Action visibility rules still apply', async () => {
+    const tree = [
+      ActionGroup.make('m').actions([
+        Action.make('shown'),
+        Action.make('hidden').visible(false),
+      ]),
+    ]
+    const result = await resolveSchema(tree)
+    assert.equal(result[0]!.children?.length, 1)
+    assert.equal(result[0]!.children![0]!['name'], 'shown')
+  })
+
+  it('stamps disabled:true on the group when its disabled rule matches', async () => {
+    const tree = [
+      ActionGroup.make('m').disabled(true).actions([Action.make('a')]),
+    ]
+    const result = await resolveSchema(tree)
+    assert.equal(result[0]!['disabled'], true)
+  })
+})

package/src/actions/ActionGroup.ts

@@ -0,0 +1,173 @@
+import { Element, type ElementMeta } from '../schema/Element.js'
+import {
+  Action,
+  type ActionColor,
+  type ActionSize,
+  type ActionPlacement,
+  type ActionVisibilityContext,
+  type VisibilityRule,
+} from './Action.js'
+
+export interface ActionGroupMeta extends ElementMeta {
+  type:        'actionGroup'
+  name:        string
+  label:       string
+  placement:   ActionPlacement
+  icon?:       string
+  tooltip?:    string
+  color?:      ActionColor
+  size?:       ActionSize
+  outlined?:   boolean
+  iconOnly?:   boolean
+  /** True when the group itself has visibility rules. The renderer checks
+   * `disabled` separately. */
+  conditional?: boolean
+  disabled?:   boolean
+}
+
+/**
+ * `ActionGroup` — a labelled trigger that opens a dropdown of related
+ * actions. Lives wherever a single `Action` can live (header slot,
+ * inline in a Card, etc). Children are `Action[]` (nesting groups inside
+ * groups is supported but renders flat — the inner group's actions are
+ * folded into the parent dropdown).
+ *
+ * Visibility evaluation: each child Action's own `.visible()`/`.hidden()`
+ * rules still apply at render time. The group itself can also opt-in to
+ * group-level visibility via the same builders. When ALL children would
+ * be hidden the group falls back to the disabled-ghost state so the
+ * trigger doesn't disappear unexpectedly — the renderer handles that.
+ */
+export class ActionGroup extends Element {
+  readonly name: string
+
+  protected _label: string
+  protected _icon?: string
+  protected _tooltip?: string
+  protected _placement: ActionPlacement = 'inline'
+
+  // Trigger styling
+  protected _color?: ActionColor
+  protected _size?: ActionSize
+  protected _outlined = false
+  protected _iconOnly = false
+
+  // Visibility
+  protected _visible?: VisibilityRule
+  protected _hidden?: VisibilityRule
+  protected _isDisabled?: VisibilityRule
+
+  private constructor(name: string) {
+    super()
+    this.name = name
+    this._label = name.charAt(0).toUpperCase() + name.slice(1)
+  }
+
+  static make(name: string): ActionGroup {
+    return new ActionGroup(name)
+  }
+
+  // ─── Children ─────────────────────────────────────────
+
+  /** Set the actions inside this group. Accepts plain `Action`s; nested
+   * `ActionGroup`s are accepted but flatten in v1 (their children get
+   * pulled up into this group's dropdown). */
+  actions(items: Array<Action | ActionGroup>): this {
+    const flat: Action[] = []
+    for (const item of items) {
+      if (item instanceof ActionGroup) {
+        flat.push(...item.getActions())
+      } else {
+        flat.push(item)
+      }
+    }
+    this._children = flat
+    return this
+  }
+
+  /** Convenience: the `Action` children only. */
+  getActions(): Action[] {
+    return (this._children ?? []).filter((c): c is Action => c instanceof Action)
+  }
+
+  // ─── Trigger config ───────────────────────────────────
+
+  label(l: string): this { this._label = l; return this }
+  icon(i: string): this  { this._icon  = i; return this }
+  tooltip(t: string): this { this._tooltip = t; return this }
+  color(c: ActionColor): this { this._color = c; return this }
+  size(s: ActionSize): this { this._size = s; return this }
+  outlined(v = true): this { this._outlined = v; return this }
+  iconButton(v = true): this { this._iconOnly = v; return this }
+
+  // ─── Placement ────────────────────────────────────────
+
+  placement(p: ActionPlacement): this { this._placement = p; return this }
+  inline(): this { return this.placement('inline') }
+  row(): this    { return this.placement('row') }
+  bulk(): this   { return this.placement('bulk') }
+  header(): this { return this.placement('header') }
+
+  // ─── Visibility ───────────────────────────────────────
+
+  visible(rule: VisibilityRule): this { this._visible = rule; return this }
+  hidden(rule: VisibilityRule): this  { this._hidden = rule; return this }
+  disabled(rule: VisibilityRule): this { this._isDisabled = rule; return this }
+  authorize(rule: VisibilityRule): this { return this.visible(rule) }
+
+  async evaluate(ctx: ActionVisibilityContext = {}): Promise<{ visible: boolean; disabled: boolean }> {
+    const evalRule = async (rule: VisibilityRule | undefined, fallback: boolean): Promise<boolean> => {
+      if (rule === undefined) return fallback
+      if (typeof rule !== 'function') return rule
+      try {
+        return await rule(ctx)
+      } catch {
+        return !fallback
+      }
+    }
+    const [visibleRaw, hiddenRaw, disabledRaw] = await Promise.all([
+      evalRule(this._visible, true),
+      evalRule(this._hidden, false),
+      evalRule(this._isDisabled, false),
+    ])
+    return {
+      visible:  visibleRaw && !hiddenRaw,
+      disabled: disabledRaw,
+    }
+  }
+
+  hasVisibilityRules(): boolean {
+    return this._visible !== undefined || this._hidden !== undefined || this._isDisabled !== undefined
+  }
+
+  // ─── Getters ──────────────────────────────────────────
+
+  getLabel():     string             { return this._label }
+  getIcon():      string | undefined { return this._icon }
+  getTooltip():   string | undefined { return this._tooltip }
+  getPlacement(): ActionPlacement    { return this._placement }
+  getColor():     ActionColor | undefined { return this._color }
+  getSize():      ActionSize | undefined  { return this._size }
+  isOutlined():   boolean { return this._outlined }
+  isIconOnly():   boolean { return this._iconOnly }
+
+  // ─── Element contract ────────────────────────────────
+
+  override getType(): string { return 'actionGroup' }
+
+  override toMeta(): ActionGroupMeta {
+    return {
+      type:      'actionGroup',
+      name:      this.name,
+      label:     this._label,
+      placement: this._placement,
+      ...(this._icon     ? { icon:     this._icon     } : {}),
+      ...(this._tooltip  ? { tooltip:  this._tooltip  } : {}),
+      ...(this._color    ? { color:    this._color    } : {}),
+      ...(this._size     ? { size:     this._size     } : {}),
+      ...(this._outlined ? { outlined: true           } : {}),
+      ...(this._iconOnly ? { iconOnly: true           } : {}),
+      ...(this.hasVisibilityRules() ? { conditional: true } : {}),
+    }
+  }
+}

package/src/actions/attachFactory.ts

@@ -0,0 +1,172 @@
+import type { Element } from '../schema/Element.js'
+import type { ResourceClass } from '../Resource.js'
+import type { ModelLike, ModelQuery } from '../orm/modelDefaults.js'
+import { getPrimaryKey } from '../orm/modelDefaults.js'
+import { SelectField } from '../fields/SelectField.js'
+
+/** Minimum shape required on the parent record to read related rows
+ *  via the rudder ORM convention. The candidate-picker side uses this
+ *  directly instead of `resolveRelatedQuery` because it doesn't need
+ *  the `ModelLike.relatedQuery` override slot — the override only
+ *  matters at table render time, not for "what's already attached?"
+ *  filtering. */
+interface ParentWithRelated {
+  related(name: string): { paginate(page: number, perPage: number): Promise<{ data: unknown[]; total: number }> }
+}
+
+/**
+ * Internals for `Action.relationAttach / relationDetach /
+ * relationBulkDetach`. Lives in its own module so the relation-manager
+ * factory side of `Action.ts` can call into the M2M-specific helpers
+ * (candidate picker query, attach modal schema) without dragging
+ * `SelectField` / model-defaults imports into the main file. Mirrors
+ * the `importFactory.ts` / `exportFactory.ts` split.
+ *
+ * The picker is intentionally simple in v1 — fetch up to 50 candidates
+ * client-resolved at page render time, filter out already-attached ids
+ * server-side. Document the cap; users with high-cardinality relations
+ * reach for `Resource.globalSearch` semantics or hand-roll an
+ * `Action.handler` with a custom picker UI.
+ */
+
+export interface AttachableRow {
+  /** Stringified primary key of the candidate record. */
+  value: string
+  /** Title text rendered in the picker. Resolved via the related
+   *  Resource's `recordTitleAttribute` chain. */
+  label: string
+}
+
+/**
+ * Read the parent's already-attached ids under `relationship`. Used by
+ * the candidate picker to filter them out (so a user can't accidentally
+ * re-attach the same row). Reads through the parent's `related()`
+ * accessor — not through the related model's `query()` — because the
+ * accessor automatically scopes to the pivot rows for this parent.
+ *
+ * Returns `Set<string>` of stringified primary keys for fast lookup.
+ * Quietly returns an empty set on failure (the picker still works,
+ * just shows everything — the attach route's own duplicate handling
+ * would pick up the dupe).
+ */
+export async function loadAttachedIds(
+  parent:       unknown,
+  relationship: string,
+  relatedModel: ModelLike,
+): Promise<Set<string>> {
+  const p = parent as Partial<ParentWithRelated>
+  if (typeof p?.related !== 'function') return new Set()
+  try {
+    const q   = (p as ParentWithRelated).related(relationship)
+    const pk  = getPrimaryKey(relatedModel)
+    const out = await q.paginate(1, 1000)
+    const ids = new Set<string>()
+    for (const row of out.data) {
+      const id = (row as Record<string, unknown>)[pk]
+      if (id !== undefined && id !== null) ids.add(String(id))
+    }
+    return ids
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * Build the candidate list for the Attach modal's SelectField. Loads
+ * up to `limit` rows from the related model (default 50), filters out
+ * any that are already attached to the parent, and maps each to
+ * `{ value, label }` using the related Resource's record-title chain.
+ *
+ * `recordTitleAttr` is resolved from the related Resource (or falls
+ * back through the standard `name → title → id` chain). The PK comes
+ * from `relatedModel`'s introspection.
+ */
+export async function loadAttachableCandidates(
+  parent:         unknown,
+  relationship:   string,
+  relatedModel:   ModelLike,
+  recordTitleAttr: string | undefined,
+  limit:          number = 50,
+): Promise<AttachableRow[]> {
+  const attached = await loadAttachedIds(parent, relationship, relatedModel)
+
+  // Use the related model's own query (not the relation accessor) so
+  // we see all attachable rows, then subtract attached ids in memory.
+  // For implicit Prisma pivots the accessor doesn't expose a
+  // whereNotIn-on-pivot-keys helper, and even when it does the cost
+  // of fetching ≤ 50 rows + a Set lookup is negligible.
+  const q = (relatedModel as { query?: () => ModelQuery }).query?.()
+  if (!q) return []
+
+  const result = await q.paginate(1, limit + attached.size).catch(() => null)
+  if (!result) return []
+
+  const pk = getPrimaryKey(relatedModel)
+
+  const rows: AttachableRow[] = []
+  for (const row of result.data) {
+    const r  = row as Record<string, unknown>
+    const id = r[pk]
+    if (id === undefined || id === null) continue
+    const idStr = String(id)
+    if (attached.has(idStr)) continue
+    rows.push({ value: idStr, label: deriveLabel(r, recordTitleAttr, idStr) })
+    if (rows.length >= limit) break
+  }
+  return rows
+}
+
+function deriveLabel(
+  record: Record<string, unknown>,
+  attr:   string | undefined,
+  fallback: string,
+): string {
+  const explicit = attr && typeof record[attr] === 'string' ? (record[attr] as string) : undefined
+  if (explicit && explicit.length > 0) return explicit
+  for (const key of ['name', 'title', 'label']) {
+    const v = record[key]
+    if (typeof v === 'string' && v.length > 0) return v
+  }
+  return fallback
+}
+
+/**
+ * Build the modal-form schema for `Action.relationAttach`. A single
+ * `SelectField` named `_attachId` populated by an async resolver that
+ * defers to `loadAttachableCandidates` at render time. Server-side the
+ * resolver runs while the table is being resolved (the parent record
+ * lives on `RenderContext.record` because the manager's list-page mode
+ * stamps it there).
+ *
+ * `recordTitleAttr` defaults to `'name'` when neither the manager nor
+ * the related Resource has set it explicitly. The candidate query
+ * limit is fixed at 50 in v1 — see plan doc for rationale.
+ */
+export function buildAttachModalSchema(deps: {
+  Related:         ResourceClass
+  relationship:    string
+  recordTitleAttr: string | undefined
+  labelSingular:   string
+}): Element[] {
+  const { Related, relationship, recordTitleAttr, labelSingular } = deps
+
+  const select = SelectField.make('_attachId')
+    .label(labelSingular)
+    .required()
+    .options(async (ctx) => {
+      // The resolver runs at schema-resolve time. For a header action
+      // on a manager list page the parent record is at `ctx.record`.
+      const parent = ctx.record
+      if (!parent) return []
+      if (!Related.model) return []
+      const rows = await loadAttachableCandidates(
+        parent,
+        relationship,
+        Related.model,
+        recordTitleAttr,
+      )
+      return rows
+    })
+
+  return [select]
+}

package/src/actions/exportFactory.ts

@@ -0,0 +1,215 @@
+/**
+ * Internals for the `Action.export` / `Action.bulkExport` factories.
+ *
+ * Lives in its own module to keep the cycle between `Action.ts` and
+ * `Table.ts` honest — `Action.export` calls into here via dynamic
+ * import inside the handler, so module-eval order never reads either
+ * side's exports too early.
+ */
+
+import { Table } from '../elements/Table.js'
+import { Column } from '../Column.js'
+import type { ActionContext } from './Action.js'
+import { encodeCsv, type CsvColumn } from '../io/csv.js'
+import { parseTableQuery, type QueryParams } from '../elements/dispatchTable.js'
+
+export type ExportFormat = 'csv' | 'json'
+
+export type ExportColumnSpec =
+  | string
+  | {
+      key:     string
+      label?:  string
+      format?: (value: unknown, record: Record<string, unknown>) => string
+    }
+
+export interface ExportOptions {
+  /** Columns to include. Strings → bare `key` (label = key). Objects
+   *  may add `label` and `format(value, record) => string`. When omitted,
+   *  defaults to every `Column` returned by `R.table()` in declaration
+   *  order, with header label = `Column.getLabel()`. */
+  columns?: ExportColumnSpec[]
+  /** Output filename. Function form receives the action context (so the
+   *  filename can include the user, current filters, etc). Default:
+   *  `${R.slug}-${YYYY-MM-DD}.${format}`. */
+  filename?: string | ((ctx: ActionContext) => string)
+  /** Output format. Default `'csv'`. */
+  format?: ExportFormat
+  /** Records scope:
+   *  - `'all'`      — ignore the current URL state (filters/search/sort)
+   *  - `'filtered'` — apply the current URL state (default; matches the
+   *                   list page the user is looking at)
+   *  - `'page'`     — only export the visible page
+   *
+   *  Bulk variant ignores `scope` and always uses `ctx.records`.
+   */
+  scope?: 'all' | 'filtered' | 'page'
+  /** Hard cap on the row count. Aborts with an error notification when
+   *  exceeded. Default `50_000`. */
+  maxRows?: number
+  /** Pagination chunk size when walking the records handler. Default
+   *  `1_000`. */
+  chunkSize?: number
+}
+
+interface ResolvedColumn {
+  key:    string
+  label:  string
+  format?: (value: unknown, record: Record<string, unknown>) => string
+}
+
+const DEFAULT_MAX_ROWS  = 50_000
+const DEFAULT_CHUNK     = 1_000
+
+/**
+ * Resolve the column spec into a uniform `{ key, label, format? }[]`,
+ * defaulting to every `Column` child on `R.table(Table.make())` when
+ * the spec is omitted.
+ */
+export function resolveExportColumns(
+  spec:    ExportOptions['columns'],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  R:       { table?(t: any): any },
+): ResolvedColumn[] {
+  if (spec && spec.length > 0) {
+    return spec.map(s => typeof s === 'string'
+      ? { key: s, label: s }
+      : { key: s.key, label: s.label ?? s.key, ...(s.format ? { format: s.format } : {}) })
+  }
+  const tableInst = R.table?.(Table.make())
+  if (!tableInst) return []
+  const cols: Column[] = tableInst.getColumns?.() ?? []
+  return cols.map(c => ({ key: c.name, label: c.getLabel?.() ?? c.name }))
+}
+
+/**
+ * Read the URL query record off `ctx.request`. Routes pass a Hono-like
+ * request object whose `.query` is a `Record<string, string>`. Fall
+ * back to `{}` when missing (programmatic dispatches in tests).
+ */
+export function readRequestQuery(ctx: ActionContext): QueryParams {
+  const req = ctx.request as { query?: unknown } | undefined
+  const q = req?.query
+  if (q && typeof q === 'object') return q as QueryParams
+  return {}
+}
+
+/**
+ * Drive the table's `records()` handler in pages until we run out of
+ * rows or hit `maxRows`. Returns the collected raw records (not yet
+ * mapped to row objects).
+ *
+ * Scope behavior:
+ *  - `'all'`:      empty TableContext (no filters/search/sort applied)
+ *  - `'filtered'`: TableContext built from the URL query (filters /
+ *                  search / sort all flow through)
+ *  - `'page'`:     same as `'filtered'` but only the visible page
+ */
+export async function collectExportRows(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  table:    any,
+  ctx:      ActionContext,
+  scope:    ExportOptions['scope'] = 'filtered',
+  maxRows:  number = DEFAULT_MAX_ROWS,
+  chunkSize: number = DEFAULT_CHUNK,
+): Promise<unknown[]> {
+  const handler = table.getRecords?.()
+  if (!handler) {
+    throw new Error('Resource table has no records() handler — cannot export. Set R.model or Table.records(fn).')
+  }
+
+  const baseCtx = scope === 'all' ? {} : buildTableCtxFromQuery(readRequestQuery(ctx), table)
+
+  const collected: unknown[] = []
+  let page = scope === 'page' ? (baseCtx.page ?? 1) : 1
+  const effectivePerPage = scope === 'page' ? (baseCtx.perPage ?? chunkSize) : chunkSize
+
+  while (collected.length <= maxRows) {
+    const result = await handler({ ...baseCtx, page, perPage: effectivePerPage })
+    const rows: unknown[] = Array.isArray(result) ? result : (result?.rows ?? [])
+    collected.push(...rows)
+    if (rows.length < effectivePerPage) break
+    if (scope === 'page') break
+    page++
+  }
+
+  return collected
+}
+
+/**
+ * Build a `TableContext` from a URL-query record by reusing the same
+ * parsing the list page does. Filters mirror onto the table's Filter
+ * children so any `Filter.query()` overrides see them on subsequent
+ * runs (defensive — `loadTableRecords` does the same).
+ */
+function buildTableCtxFromQuery(
+  query: QueryParams,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  table: any,
+): {
+  search?:  string
+  sort?:    { column: string; direction: 'asc' | 'desc' }
+  filters?: Record<string, string>
+  page?:    number
+  perPage?: number
+} {
+  const { search, sort, page, perPage } = parseTableQuery(query)
+
+  const tableFilters = table.getFilters?.() ?? []
+  const filterValues: Record<string, string> = {}
+  const reserved = new Set(['search', 'sort', 'page', 'perPage', 'group'])
+  for (const f of tableFilters) {
+    const name = f.name as string
+    if (reserved.has(name)) continue
+    const v = (query as Record<string, unknown>)[name]
+    if (typeof v === 'string' && v !== '') filterValues[name] = v
+  }
+  for (const f of tableFilters) {
+    const v = filterValues[f.name as string]
+    if (v !== undefined && typeof f.withValue === 'function') f.withValue(v)
+  }
+
+  const out: ReturnType<typeof buildTableCtxFromQuery> = {}
+  if (search !== undefined) out.search = search
+  if (sort !== undefined)   out.sort   = sort
+  if (Object.keys(filterValues).length > 0) out.filters = filterValues
+  if (page !== undefined)    out.page    = page
+  if (perPage !== undefined) out.perPage = perPage
+  return out
+}
+
+/** Build a single CSV/JSON-shaped row by reading each resolved column's
+ *  key off the record (with `format` applied when set). */
+export function buildExportRow(
+  record: unknown,
+  cols:   ReadonlyArray<ResolvedColumn>,
+): Record<string, unknown> {
+  const r = record as Record<string, unknown>
+  const out: Record<string, unknown> = {}
+  for (const col of cols) {
+    const raw = r[col.key]
+    out[col.key] = col.format ? col.format(raw, r) : raw
+  }
+  return out
+}
+
+/** Encode `rows` as the requested format. Object values that survive
+ *  to here go through the CSV escape rules / `JSON.stringify`. */
+export function encodeExport(
+  rows:   ReadonlyArray<Record<string, unknown>>,
+  cols:   ReadonlyArray<ResolvedColumn>,
+  format: ExportFormat,
+): { body: string; contentType: string } {
+  if (format === 'json') {
+    return { body: JSON.stringify(rows, null, 2), contentType: 'application/json' }
+  }
+  const csvCols: CsvColumn[] = cols.map(c => ({ key: c.key, label: c.label }))
+  return { body: encodeCsv(rows, csvCols), contentType: 'text/csv; charset=utf-8' }
+}
+
+/** Default filename: `${slug}-${YYYY-MM-DD}.${ext}`. */
+export function defaultExportFilename(slug: string, format: ExportFormat): string {
+  const date = new Date().toISOString().slice(0, 10)
+  const ext  = format === 'json' ? 'json' : 'csv'
+  return `${slug}-${date}.${ext}`
+}