add-column-type

# Adding a Table Column Type

A column type is **one file** in `apps/sim/lib/table/column-types/` plus a registry entry. Everything that varies per type — label, icon, storage cast, coercion, validation, conversion compatibility, formatting, editor, filter operators — lives on that one object, so no consumer needs editing.

This was not always true: adding `currency` originally took ~40 edits across 32 `switch` arms and 26 UI branches, each of which failed **silently** when missed. The registry exists to make that impossible, so the rule is absolute: **if you find yourself adding a `case 'yourtype':` anywhere outside `column-types/`, the registry is missing a field. Add the field instead.**

## Hard Rule: the compiler tells you what to do

Do **not** hunt for places to edit. Add your type to the `ColumnType` union first and let `tsc` produce the list:

```bash
cd apps/sim && bun run type-check
```

You will get two errors, naming `column-types/registry.ts` and `column-types/registry.server.ts`. Register in both.

If your type owns metadata, adding its key to `TYPE_SPECIFIC_COLUMN_KEYS` produces two more legitimate errors — `FOREIGN_METADATA_VERB` in `validation.ts` (a `Record` over those keys) and the key's absence from `ColumnDefinition`. Those are the gate working, not sites to "fix".

Any error beyond those four is a site reading a hardcoded type list that should read the registry — fix that site, don't work around it.

## Directory Structure

```
apps/sim/lib/table/column-types/
├── types.ts             # ColumnTypeDefinition — the contract you implement
├── types.server.ts      # ColumnTypeServerDefinition — cell migrations only
├── registry.ts          # Record<ColumnType, …>  ← client-safe, the gate
├── registry.server.ts   # Record<ColumnType, …>  ← adds migrations (drizzle)
├── index.ts             # barrel + accessors (columnTypeOf, columnTypeById, …)
└── {type}.ts            # one file per type — what you write
```

## Step 1: Pick the storage shape

Decide what a cell literally holds in `user_table_rows.data` (JSONB). This drives almost everything else:

| Storage | `jsonbCast` | Notes |
|---------|-------------|-------|
| number  | `'numeric'` | Filters/sorts compare numerically. `currency` does this. |
| ISO string | `'timestamptz'` | `date` does this. |
| string / bool / object | `null` | Text comparison is correct. |

**Prefer an existing primitive over a new shape.** `currency` stores a plain number and keeps its ISO code as *display metadata* — which is why filtering, sorting, uniqueness, and CSV export all reuse the numeric paths untouched, and why re-denominating a column rewrites zero rows.

## Step 2: Add the icon

Create `packages/emcn/src/icons/type-{name}.tsx`, copying the geometry conventions of its siblings exactly:

```tsx
import type { SVGProps } from 'react'

/**
 * Type {name} icon component - {what the glyph is} for {name} columns
 * @param props - SVG properties including className, fill, etc.
 */
export function Type{Pascal}(props: SVGProps<SVGSVGElement>) {
  return (
    <svg
      width='24'
      height='24'
      viewBox='-1.75 -1.5 24 24'
      fill='none'
      stroke='currentColor'
      strokeWidth='1.55'
      strokeLinecap='round'
      strokeLinejoin='round'
      xmlns='http://www.w3.org/2000/svg'
      aria-hidden='true'
      {...props}
    >
      <path d='…' />
    </svg>
  )
}
```

- `viewBox='-1.75 -1.5 24 24'` is the **`type-*` family** value, not the set-wide default. Match the family.
- Center the glyph on the viewBox's optical center (**y = 10.5**, **x = 10.25**) — every sibling does, and a few tenths off is visible at `size-[14px]`.
- Export alphabetically **by component name** in `packages/emcn/src/icons/index.ts`.

## Step 3: Write the type file

`apps/sim/lib/table/column-types/{name}.ts`. Copy the closest existing type and change what differs. Every field is required by the interface, so the compiler enumerates them for you — read the TSDoc in `types.ts` rather than guessing.

The three that are easy to get wrong:

- **`coerce`** is the *single* write-path implementation. The server runs it before persisting **and** the grid runs it to fill the optimistic cache. Accept every shape the value legitimately arrives in (paste, CSV, tool write), because rejecting means the cell is nulled.
- **`isCompatibleWith`** gates type conversion and must read the value **exactly as `coerce` will**, or a conversion will pass its check and then null the cell.
- **`ownedMetadata`** lists the `ColumnDefinition` keys your type owns. Anything you add must also be added to `TYPE_SPECIFIC_COLUMN_KEYS` in `types.ts` and given a phrase in `FOREIGN_METADATA_VERB` in `validation.ts` — both are `Record`-typed, so the compiler will tell you.

## Step 4: Register

Add the entry to `COLUMN_TYPE_REGISTRY` in `registry.ts` **and** `COLUMN_TYPE_SERVER_REGISTRY` in `registry.server.ts`.

`COLUMN_TYPES` is declared in `types.ts` (not derived from the registry — the registry is annotated `Record<ColumnType, …>` against it, which is the gate). `constants.ts` re-exports it, so `columnTypeSchema = z.enum(COLUMN_TYPES)` picks your type up with no edit. **Type-specific metadata does not** — see the next step.

## Step 5: Migrations (only if the stored bytes change)

If converting an existing column **to** your type must rewrite cells, add `migrateCellsTo` in `registry.server.ts`; if converting **away** must rewrite them, add `migrateCellsFrom`.

This is load-bearing, not cosmetic: filters and sorts apply `jsonbCast` to whatever is stored, so leaving a non-castable string behind makes **every query on that column fail** — not merely render oddly.

Prefer set-based SQL. When the transform genuinely needs JS (`currency`'s separator disambiguation), compute the values during the compatibility scan and pass them through `resolved`, then apply them in one batched statement.

## Naming Convention

- Type id: lowercase, singular — `currency`, not `Currency` or `currencies`
- F