@freighttech/ui 0.13.18

package/src/backend/utils/__tests__/richTextSanitizer.test.ts

@@ -0,0 +1,57 @@
+import { sanitizeHtmlRichText, sanitizeRichTextHref, sanitizeRichTextPasteContent } from '../richTextSanitizer'
+
+describe('richTextSanitizer', () => {
+  it('keeps basic rich text tags and safe links', () => {
+    expect(
+      sanitizeHtmlRichText('<p>Hello <strong>world</strong> <a href="https://example.com" title="Example">link</a></p>'),
+    ).toBe('<p>Hello <strong>world</strong> <a href="https://example.com" title="Example">link</a></p>')
+  })
+
+  it('removes executable content and unsafe attributes', () => {
+    // <script> is dropped with content (nonTextTags), onclick/style are stripped,
+    // <img> is an allowed tag so it is kept but onerror is stripped and src is preserved.
+    expect(
+      sanitizeHtmlRichText('<p onclick="alert(1)" style="color:red">Hi<script>alert(1)</script><img src=x onerror=alert(2)>there</p>'),
+    ).toBe('<p>Hi<img src="x" />there</p>')
+  })
+
+  it('removes unsafe href values from links', () => {
+    expect(
+      sanitizeHtmlRichText('<a href="java\nscript:alert(1)" target="_blank" rel="opener">Bad link</a>'),
+    ).toBe('<a>Bad link</a>')
+  })
+
+  it('unwraps unknown formatting tags without keeping their attributes', () => {
+    expect(sanitizeHtmlRichText('<custom-element data-x="1"><b>Safe</b></custom-element>')).toBe('<b>Safe</b>')
+  })
+
+  it('normalizes href values by allowlist', () => {
+    expect(sanitizeRichTextHref(' https://example.com/docs ')).toBe('https://example.com/docs')
+    expect(sanitizeRichTextHref('https://example.com/docs?a=1&b=2')).toBe('https://example.com/docs?a=1&b=2')
+    expect(sanitizeRichTextHref('/backend/customers')).toBe('/backend/customers')
+    expect(sanitizeRichTextHref('mailto:test@example.com')).toBe('mailto:test@example.com')
+    expect(sanitizeRichTextHref('javascript:alert(1)')).toBeNull()
+    expect(sanitizeRichTextHref('data:text/html,<script>alert(1)</script>')).toBeNull()
+  })
+
+  it('sanitizes plain text paste when it contains html markup', () => {
+    // <img> is an allowed tag: src is kept, onerror is stripped.
+    // <a href="javascript:…"> has a disallowed scheme so href is removed.
+    expect(
+      sanitizeRichTextPasteContent(
+        '',
+        '<p>Safe text</p><img src="x" onerror="alert(1)"><a href="javascript:alert(2)">Bad link</a>',
+      ),
+    ).toEqual({
+      command: 'insertHTML',
+      value: '<p>Safe text</p><img src="x" /><a>Bad link</a>',
+    })
+  })
+
+  it('keeps non-html plain text paste as text', () => {
+    expect(sanitizeRichTextPasteContent('', 'Plain < not a tag')).toEqual({
+      command: 'insertText',
+      value: 'Plain < not a tag',
+    })
+  })
+})

package/src/backend/utils/api.ts

@@ -0,0 +1,214 @@
+"use client"
+// Simple fetch wrapper that redirects to session refresh on 401 (Unauthorized)
+// Used across UI data utilities to avoid duplication.
+import { flash } from '../FlashMessages'
+import { deserializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { pushOperation } from '../operations/store'
+import { pushPartialIndexWarning } from '../indexes/store'
+import { createScopedHeaderStack } from './scopedHeaderStack'
+
+const scopedHeaders = createScopedHeaderStack()
+
+function mergeHeaders(base: HeadersInit | undefined, scoped: Record<string, string>): Headers {
+  const headers = new Headers(base ?? {})
+  for (const [key, value] of Object.entries(scoped)) {
+    if (headers.has(key)) continue
+    headers.set(key, value)
+  }
+  return headers
+}
+
+function readRedirectOverride(headers: Headers, headerName: string): boolean {
+  return headers.get(headerName) === '0'
+}
+
+export async function withScopedApiHeaders<T>(headers: Record<string, string>, run: () => Promise<T>): Promise<T> {
+  return scopedHeaders.withScopedHeaders(headers, run)
+}
+
+export class UnauthorizedError extends Error {
+  readonly status = 401
+  constructor(message = 'Unauthorized') {
+    super(message)
+    this.name = 'UnauthorizedError'
+  }
+}
+
+export function redirectToSessionRefresh() {
+  if (typeof window === 'undefined') return
+  const current = window.location.pathname + window.location.search
+  // Avoid redirect loops if already on an auth/session route
+  if (window.location.pathname.startsWith('/api/auth')) return
+  // Portal routes have their own customer auth — never redirect to staff login
+  if (/\/[^/]+\/portal(\/|$)/.test(window.location.pathname)) return
+  try {
+    flash('Session expired. Redirecting to sign in…', 'warning')
+    setTimeout(() => {
+      window.location.href = `/api/auth/session/refresh?redirect=${encodeURIComponent(current)}`
+    }, 20)
+  } catch {
+    // no-op
+  }
+}
+
+export class ForbiddenError extends Error {
+  readonly status = 403
+  constructor(message = 'Forbidden') {
+    super(message)
+    this.name = 'ForbiddenError'
+  }
+}
+
+let DEFAULT_FORBIDDEN_ROLES: string[] = ['admin']
+
+export function setAuthRedirectConfig(cfg: { defaultForbiddenRoles?: readonly string[] }) {
+  if (cfg?.defaultForbiddenRoles && cfg.defaultForbiddenRoles.length) {
+    DEFAULT_FORBIDDEN_ROLES = [...cfg.defaultForbiddenRoles].map(String)
+  }
+}
+
+export function redirectToForbiddenLogin(options?: { requiredRoles?: string[] | null; requiredFeatures?: string[] | null }) {
+  if (typeof window === 'undefined') return
+  if (window.location.pathname.startsWith('/login')) return
+  // Portal routes have their own customer auth — never redirect to staff login
+  if (/\/[^/]+\/portal(\/|$)/.test(window.location.pathname)) return
+  try {
+    const current = window.location.pathname + window.location.search
+    const features = options?.requiredFeatures?.filter(Boolean) ?? []
+    const roles = options?.requiredRoles?.filter(Boolean) ?? []
+    const fallbackRoles = DEFAULT_FORBIDDEN_ROLES.filter(Boolean)
+    const effectiveRoles = roles.length ? roles : fallbackRoles
+    const query = features.length
+      ? `requireFeature=${encodeURIComponent(features.join(','))}`
+      : effectiveRoles.length
+        ? `requireRole=${encodeURIComponent(effectiveRoles.map(String).join(','))}`
+        : ''
+    const url = query
+      ? `/login?${query}&redirect=${encodeURIComponent(current)}`
+      : `/login?redirect=${encodeURIComponent(current)}`
+    flash('Insufficient permissions. Redirecting to login…', 'warning')
+    setTimeout(() => { window.location.href = url }, 60)
+  } catch {
+    // no-op
+  }
+}
+
+export async function apiFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+  type FetchType = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+  const originalFetch =
+    typeof window !== 'undefined'
+      ? (window as Window & { __omOriginalFetch?: FetchType }).__omOriginalFetch
+      : undefined
+  const fallbackFetch = (globalThis as typeof globalThis & { fetch?: FetchType }).fetch
+  const baseFetch = originalFetch ?? fallbackFetch
+  if (!baseFetch) {
+    return new Response(
+      JSON.stringify({ error: 'Fetch API is not available in this runtime' }),
+      { status: 503, headers: { 'content-type': 'application/json' } },
+    )
+  }
+  const scoped = scopedHeaders.resolveScopedHeaders()
+  const mergedInit = Object.keys(scoped).length
+    ? { ...(init ?? {}), headers: mergeHeaders(init?.headers, scoped) }
+    : init
+  const requestHeaders = new Headers(mergedInit?.headers)
+  const disableUnauthorizedRedirect = readRedirectOverride(requestHeaders, 'x-om-unauthorized-redirect')
+  const disableForbiddenRedirect = readRedirectOverride(requestHeaders, 'x-om-forbidden-redirect')
+  const res = await baseFetch(input, mergedInit)
+  const pathname = typeof window !== 'undefined' ? window.location.pathname : ''
+  const onLoginPage = pathname.startsWith('/login')
+  const onPortalRoute = /\/[^/]+\/portal(\/|$)/.test(pathname)
+  if (res.status === 401) {
+    // Trigger same redirect flow as protected pages
+    // Skip for staff login page and all portal routes (portal has its own auth)
+    if (!onLoginPage && !onPortalRoute && !disableUnauthorizedRedirect) {
+      redirectToSessionRefresh()
+      // Throw a typed error for callers that might still handle it
+      throw new UnauthorizedError(await res.text().catch(() => 'Unauthorized'))
+    }
+    return res
+  }
+  if (res.status === 403) {
+    // Try to read requiredRoles from JSON body; ignore if not JSON
+    let roles: string[] | null = null
+    let features: string[] | null = null
+    let payload: unknown = null
+    const aclData = await readJsonSafe<Record<string, unknown>>(res.clone(), null)
+    if (aclData && typeof aclData === 'object') {
+      if (Array.isArray(aclData.requiredRoles)) {
+        roles = aclData.requiredRoles.map((r) => String(r))
+      }
+      if (Array.isArray(aclData.requiredFeatures)) {
+        features = aclData.requiredFeatures.map((f) => String(f))
+      }
+      payload = aclData
+    }
+    // Only redirect if not already on login page or a portal route
+    if (!onLoginPage && !onPortalRoute && !disableForbiddenRedirect) {
+      const target =
+        typeof input === 'string'
+          ? input
+          : input instanceof URL
+            ? input.toString()
+            : (typeof Request !== 'undefined' && input instanceof Request)
+              ? input.url
+              : 'unknown'
+      try {
+        // eslint-disable-next-line no-console
+        console.warn('[apiFetch] Forbidden response', {
+          url: target,
+          status: res.status,
+          requiredRoles: roles,
+          requiredFeatures: features,
+          details: payload,
+        })
+      } catch {}
+      const hasAclHints = Boolean((roles && roles.length) || (features && features.length))
+      if (hasAclHints) {
+        redirectToForbiddenLogin({ requiredRoles: roles, requiredFeatures: features })
+      }
+      let msg = 'Forbidden'
+      if (aclData && typeof aclData === 'object') {
+        if (typeof aclData.error === 'string') {
+          msg = aclData.error
+        } else if (typeof aclData.message === 'string') {
+          msg = aclData.message
+        }
+      } else {
+        msg = await res.clone().text().catch(() => 'Forbidden')
+      }
+      throw new ForbiddenError(msg)
+    }
+    // If already on login, just return the response for the caller to handle
+  }
+  try {
+    const header = res.headers.get('x-om-operation')
+    const metadata = deserializeOperationMetadata(header)
+    if (metadata) pushOperation(metadata)
+  } catch {
+    // ignore malformed headers
+  }
+  try {
+    const warningRaw = res.headers.get('x-om-partial-index')
+    if (warningRaw) {
+      const parsed = JSON.parse(warningRaw) as Record<string, unknown>
+      if (parsed && typeof parsed === 'object' && parsed.type === 'partial_index') {
+        const entity = typeof parsed.entity === 'string' ? parsed.entity : String(parsed.entity ?? '')
+        if (entity) {
+          const baseCount = typeof parsed.baseCount === 'number' ? parsed.baseCount : null
+          const indexedCount = typeof parsed.indexedCount === 'number' ? parsed.indexedCount : null
+          const scope = parsed.scope === 'global' ? 'global' : 'scoped'
+          const entityLabel =
+            typeof parsed.entityLabel === 'string' && parsed.entityLabel.trim()
+              ? parsed.entityLabel.trim()
+              : entity
+          pushPartialIndexWarning({ entity, entityLabel, baseCount, indexedCount, scope })
+        }
+      }
+    }
+  } catch {
+    // ignore malformed headers
+  }
+  return res
+}

package/src/backend/utils/apiCall.ts

@@ -0,0 +1,123 @@
+"use client"
+
+import { apiFetch } from './api'
+import { raiseCrudError, readJsonSafe } from './serverErrors'
+import { createScopedHeaderStack } from './scopedHeaderStack'
+
+export type ApiCallOptions<TReturn> = {
+  parse?: (res: Response) => Promise<TReturn | null>
+  fallback?: TReturn | null
+}
+
+export type ApiCallResult<TReturn> = {
+  ok: boolean
+  status: number
+  result: TReturn | null
+  response: Response
+  cacheStatus: 'hit' | 'miss' | null
+}
+
+const scopedRequestHeaders = createScopedHeaderStack()
+
+function mergeHeaders(base: HeadersInit | undefined, extra: Record<string, string>): HeadersInit {
+  if (!base) return extra
+  if (typeof Headers !== 'undefined' && base instanceof Headers) {
+    const merged = new Headers(base)
+    Object.entries(extra).forEach(([key, value]) => merged.set(key, value))
+    return merged
+  }
+  if (Array.isArray(base)) {
+    return [...base, ...Object.entries(extra)]
+  }
+  return { ...(base as Record<string, string>), ...extra }
+}
+
+export async function withScopedApiRequestHeaders<T>(
+  headers: Record<string, string>,
+  run: () => Promise<T>,
+): Promise<T> {
+  return scopedRequestHeaders.withScopedHeaders(headers, run)
+}
+
+export async function apiCall<TReturn = Record<string, unknown>>(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  options?: ApiCallOptions<TReturn>,
+): Promise<ApiCallResult<TReturn>> {
+  const scopedHeaders = scopedRequestHeaders.resolveScopedHeaders()
+  const requestInit = Object.keys(scopedHeaders).length > 0
+    ? { ...(init ?? {}), headers: mergeHeaders(init?.headers, scopedHeaders) }
+    : init
+  const response = await apiFetch(input, requestInit)
+  const parser = options?.parse
+  const fallback = options?.fallback ?? null
+  let result: TReturn | null = null
+  const rawCacheStatus =
+    response.headers?.get?.('x-om-cache') ??
+    response.headers?.get?.('x-cache-status') ??
+    null
+  const cacheStatus = rawCacheStatus === 'hit' || rawCacheStatus === 'miss' ? rawCacheStatus : null
+  try {
+    const source = typeof (response as Response & { clone?: () => Response }).clone === 'function'
+      ? response.clone()
+      : response
+    if (parser) result = await parser(source)
+    else result = await readJsonSafe<TReturn>(source, fallback)
+  } catch {
+    result = fallback
+  }
+  return {
+    ok: response.ok,
+    status: response.status,
+    result,
+    response,
+    cacheStatus,
+  }
+}
+
+export type ApiCallOrThrowOptions<TReturn> = ApiCallOptions<TReturn> & {
+  errorMessage?: string
+}
+
+export async function apiCallOrThrow<TReturn = Record<string, unknown>>(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  options?: ApiCallOrThrowOptions<TReturn>,
+): Promise<ApiCallResult<TReturn>> {
+  const { errorMessage, ...callOptions } = options ?? {}
+  const call = await apiCall<TReturn>(input, init, callOptions)
+  if (!call.ok) {
+    await raiseCrudError(call.response, errorMessage)
+  }
+  return call
+}
+
+export type ReadApiResultOrThrowOptions<TReturn> = ApiCallOrThrowOptions<TReturn> & {
+  allowNullResult?: boolean
+  emptyResultMessage?: string
+}
+
+export async function readApiResultOrThrow<TReturn = Record<string, unknown>>(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  options?: ReadApiResultOrThrowOptions<TReturn> & { allowNullResult?: false },
+): Promise<TReturn>
+export async function readApiResultOrThrow<TReturn = Record<string, unknown>>(
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+  options: ReadApiResultOrThrowOptions<TReturn> & { allowNullResult: true },
+): Promise<TReturn | null>
+export async function readApiResultOrThrow<TReturn = Record<string, unknown>>(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  options?: ReadApiResultOrThrowOptions<TReturn>,
+): Promise<TReturn | null> {
+  const { allowNullResult = false, emptyResultMessage, ...callOptions } = options ?? {}
+  const call = await apiCallOrThrow<TReturn>(input, init, callOptions)
+  if (call.result == null && !allowNullResult) {
+    const fallback =
+      emptyResultMessage ?? callOptions.errorMessage ?? `Missing response payload (${call.status})`
+    throw new Error(fallback)
+  }
+  return call.result
+}

package/src/backend/utils/crud.ts

@@ -0,0 +1,174 @@
+export type SortDir = 'asc' | 'desc'
+
+export type ListResponse<T> = {
+  items: T[]
+  total: number
+  page: number
+  pageSize: number
+  totalPages: number
+}
+
+export type CrudExportFormat = 'csv' | 'json' | 'xml' | 'markdown'
+
+function toQuery(params: Record<string, any>) {
+  const sp = new URLSearchParams()
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined || v === null) continue
+    if (Array.isArray(v)) {
+      if (v.length === 0) continue
+      sp.set(k, v.join(','))
+    } else {
+      sp.set(k, String(v))
+    }
+  }
+  return sp.toString()
+}
+
+export function buildCrudQuery(params: Record<string, any>): string {
+  return toQuery(params)
+}
+
+import { apiCall, readApiResultOrThrow, type ApiCallResult } from './apiCall'
+import { raiseCrudError } from './serverErrors'
+
+function mergeHeaders(base: HeadersInit | undefined, extra: Record<string, string>): HeadersInit {
+  if (!base) return extra
+  const hasHeadersCtor = typeof Headers !== 'undefined'
+  if (hasHeadersCtor && base instanceof Headers) {
+    const merged = new Headers(base)
+    Object.entries(extra).forEach(([key, value]) => merged.set(key, value))
+    return merged
+  }
+  if (Array.isArray(base)) {
+    return [...base, ...Object.entries(extra)]
+  }
+  return { ...(base as Record<string, string>), ...extra }
+}
+
+type CrudRequestExtras<TReturn> = {
+  parseResult?: (res: Response) => Promise<TReturn | null>
+  fallbackResult?: TReturn | null
+  errorMessage?: string
+}
+
+export type CrudRequestInit<TReturn> = Omit<RequestInit, 'body' | 'method'> & CrudRequestExtras<TReturn>
+type CrudDeleteOptions<TReturn> = Omit<RequestInit, 'method' | 'body'> &
+  CrudRequestExtras<TReturn> & {
+    body?: unknown
+    id?: string
+  }
+
+export type CrudResponse<TReturn> = ApiCallResult<TReturn>
+
+export async function fetchCrudList<T>(apiPath: string, params: Record<string, any>, init?: RequestInit): Promise<ListResponse<T>> {
+  const qs = buildCrudQuery(params)
+  return readApiResultOrThrow<ListResponse<T>>(`/api/${apiPath}?${qs}`, init, {
+    errorMessage: 'Failed to fetch list',
+  })
+}
+
+export function buildCrudExportUrl(apiPath: string, params: Record<string, any>, format: CrudExportFormat): string {
+  const qs = buildCrudQuery({ ...params, format })
+  return `/api/${apiPath}?${qs}`
+}
+
+export function buildCrudCsvUrl(apiPath: string, params: Record<string, any>): string {
+  return buildCrudExportUrl(apiPath, params, 'csv')
+}
+
+export async function createCrud<TReturn = Record<string, unknown>>(
+  apiPath: string,
+  body: any,
+  init?: CrudRequestInit<TReturn>,
+): Promise<CrudResponse<TReturn>> {
+  const { parseResult, fallbackResult, errorMessage, headers, ...rest } = init ?? {}
+  const call = await apiCall<TReturn>(
+    `/api/${apiPath}`,
+    {
+      ...rest,
+      method: 'POST',
+      headers: mergeHeaders(headers, { 'content-type': 'application/json' }),
+      body: JSON.stringify(body),
+    },
+    {
+      parse: parseResult,
+      fallback: fallbackResult ?? null,
+    },
+  )
+  if (!call.ok) await raiseCrudError(call.response, errorMessage ?? 'Failed to create')
+  return call
+}
+
+export async function updateCrud<TReturn = Record<string, unknown>>(
+  apiPath: string,
+  body: any,
+  init?: CrudRequestInit<TReturn>,
+): Promise<CrudResponse<TReturn>> {
+  const { parseResult, fallbackResult, errorMessage, headers, ...rest } = init ?? {}
+  const call = await apiCall<TReturn>(
+    `/api/${apiPath}`,
+    {
+      ...rest,
+      method: 'PUT',
+      headers: mergeHeaders(headers, { 'content-type': 'application/json' }),
+      body: JSON.stringify(body),
+    },
+    {
+      parse: parseResult,
+      fallback: fallbackResult ?? null,
+    },
+  )
+  if (!call.ok) await raiseCrudError(call.response, errorMessage ?? 'Failed to update')
+  return call
+}
+
+export async function deleteCrud<TReturn = Record<string, unknown>>(
+  apiPath: string,
+  id: string,
+  init?: CrudRequestInit<TReturn>,
+): Promise<CrudResponse<TReturn>>
+export async function deleteCrud<TReturn = Record<string, unknown>>(
+  apiPath: string,
+  options: CrudDeleteOptions<TReturn>,
+): Promise<CrudResponse<TReturn>>
+export async function deleteCrud<TReturn = Record<string, unknown>>(
+  apiPath: string,
+  idOrOptions: string | CrudDeleteOptions<TReturn>,
+  maybeInit?: CrudRequestInit<TReturn>,
+): Promise<CrudResponse<TReturn>> {
+  if (typeof idOrOptions === 'string') {
+    const { parseResult, fallbackResult, errorMessage, ...rest } = maybeInit ?? {}
+    const call = await apiCall<TReturn>(
+      `/api/${apiPath}?id=${encodeURIComponent(idOrOptions)}`,
+      {
+        ...rest,
+        method: 'DELETE',
+      },
+      {
+        parse: parseResult,
+        fallback: fallbackResult ?? null,
+      },
+    )
+    if (!call.ok) await raiseCrudError(call.response, errorMessage ?? 'Failed to delete')
+    return call
+  }
+  const { parseResult, fallbackResult, errorMessage, headers, body, id, ...rest } = idOrOptions
+  const payload = body ?? (id ? { id } : undefined)
+  const requestHeaders =
+    payload !== undefined ? mergeHeaders(headers, { 'content-type': 'application/json' }) : headers
+  const call = await apiCall<TReturn>(
+    `/api/${apiPath}`,
+    {
+      ...rest,
+      method: 'DELETE',
+      headers: requestHeaders,
+      body: payload !== undefined ? JSON.stringify(payload) : undefined,
+    },
+    {
+      parse: parseResult,
+      fallback: fallbackResult ?? null,
+    },
+  )
+  if (!call.ok) await raiseCrudError(call.response, errorMessage ?? 'Failed to delete')
+  return call
+}

package/src/backend/utils/customFieldColumns.ts

@@ -0,0 +1,118 @@
+import type { ColumnDef } from '@tanstack/react-table'
+import type { FilterFieldType, FilterOption } from '@open-mercato/shared/lib/query/advanced-filter'
+import type { CustomFieldDefDto, CustomFieldVisibility } from './customFieldDefs'
+import { isDefVisible } from './customFieldDefs'
+
+type RawCustomFieldOption = string | number | { value?: unknown; label?: unknown }
+
+export function supportsCustomFieldColumn(def: CustomFieldDefDto): boolean {
+  return def.kind !== 'attachment'
+}
+
+export function mapCustomFieldKindToFilterType(kind: string): FilterFieldType {
+  switch (kind) {
+    case 'boolean':
+      return 'boolean'
+    case 'integer':
+    case 'float':
+      return 'number'
+    case 'date':
+    case 'datetime':
+      return 'date'
+    case 'select':
+    case 'dictionary':
+    case 'currency':
+    case 'relation':
+      return 'select'
+    default:
+      return 'text'
+  }
+}
+
+export function normalizeCustomFieldFilterOptions(options?: RawCustomFieldOption[]): FilterOption[] {
+  if (!Array.isArray(options)) return []
+  return options.map((option) => {
+    if (option && typeof option === 'object' && 'value' in option) {
+      const rawValue = option.value
+      const rawLabel = option.label ?? rawValue
+      return {
+        value: String(rawValue),
+        label: typeof rawLabel === 'string' ? rawLabel : String(rawLabel),
+      }
+    }
+    const value = String(option)
+    return {
+      value,
+      label: value.charAt(0).toUpperCase() + value.slice(1),
+    }
+  })
+}
+
+// Filters and annotates columns with custom-field definitions:
+// - Drops cf_* columns when no definition exists or listVisible === false
+// - Uses definition label as header when header is missing
+export function applyCustomFieldVisibility<T>(columns: ColumnDef<T, any>[], defs: CustomFieldDefDto[], mode: CustomFieldVisibility = 'list'): ColumnDef<T, any>[] {
+  const byKey = new Map(defs.map((d) => [d.key, d]))
+  // First, filter and annotate headers
+  const filtered = columns.filter((c) => {
+    const key = String((c as any).accessorKey || '')
+    if (!key.startsWith('cf_')) return true
+    const cfKey = key.slice(3)
+    const def = byKey.get(cfKey)
+    if (!def) return false
+    if (!supportsCustomFieldColumn(def)) return false
+    if (!isDefVisible(def, mode)) return false
+    const currentHeader = (c as any).header
+    const fallbackHeader = typeof currentHeader === 'string' && currentHeader.trim().length ? currentHeader : key
+    const label = def.label && def.label.trim().length ? def.label : fallbackHeader
+    if (currentHeader == null || typeof currentHeader === 'string') {
+      (c as any).header = label
+    }
+    const existingMeta = ((c as any).meta || {}) as Record<string, unknown>
+    const nextMeta = Object.assign({}, existingMeta, { label })
+    ;(c as any).meta = nextMeta
+    return true
+  })
+
+  // Then, reorder only the cf_* columns by definition priority while preserving
+  // the positions of non-cf columns and the count of cf slots.
+  const cfEntries: Array<{ col: ColumnDef<T, any>; key: string; prio: number }> = []
+  filtered.forEach((c) => {
+    const key = String((c as any).accessorKey || '')
+    if (key.startsWith('cf_')) {
+      const cfKey = key.slice(3)
+      const def = byKey.get(cfKey)
+      cfEntries.push({ col: c, key: cfKey, prio: def?.priority ?? 0 })
+    }
+  })
+  cfEntries.sort((a, b) => a.prio - b.prio)
+  let cfIdx = 0
+  const result = filtered.map((c) => {
+    const key = String((c as any).accessorKey || '')
+    if (!key.startsWith('cf_')) return c
+    const next = cfEntries[cfIdx++]?.col ?? c
+    return next
+  })
+
+  // Append any missing cf columns (defs visible but not present in incoming columns)
+  const existingCfKeys = new Set<string>(result
+    .map((c) => String((c as any).accessorKey || ''))
+    .filter((k) => k.startsWith('cf_'))
+    .map((k) => k.slice(3)))
+
+  const visibleSorted = defs
+    .filter((d) => supportsCustomFieldColumn(d) && isDefVisible(d, mode))
+    .sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0))
+
+  const missing = visibleSorted.filter((d) => !existingCfKeys.has(d.key))
+  for (const d of missing) {
+    const col: ColumnDef<T, any> = {
+      accessorKey: `cf_${d.key}` as any,
+      header: d.label || `cf_${d.key}`,
+      // Respect responsive priority when provided; default leaves it visible
+      meta: { priority: (d as any).priority, label: d.label || `cf_${d.key}` } as any,
+    }
+    result.push(col)
+  }
+  return result
+}