@pilotiq/pilotiq 0.1.0

package/src/breadcrumbs.test.ts

@@ -0,0 +1,238 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Pilotiq } from './Pilotiq.js'
+import { Resource } from './Resource.js'
+import { Global }   from './Global.js'
+import { Page }     from './Page.js'
+import { Form }     from './elements/Form.js'
+import { Cluster }  from './Cluster.js'
+import { TextField } from './fields/TextField.js'
+import { Heading }   from './schema/Heading.js'
+import { defaultGlobalViewPage } from './defaultGlobalPages.js'
+import {
+  resourceIndexData,
+  resourceCreateData,
+  resourceEditData,
+  resourceViewData,
+  globalEditData,
+  globalViewData,
+  customPageData,
+} from './pageData.js'
+
+interface BreadcrumbItem { label: string; url?: string }
+interface BreadcrumbMeta { type: string; items: BreadcrumbItem[] }
+
+function findBreadcrumbs(schema: Array<Record<string, unknown>>): BreadcrumbItem[] {
+  const meta = schema.find(s => s['type'] === 'breadcrumbs') as BreadcrumbMeta | undefined
+  assert.ok(meta, 'expected a breadcrumbs element on the page')
+  return meta!.items
+}
+
+class Articles extends Resource {
+  static override label         = 'Articles'
+  static override labelSingular = 'Article'
+  static override slug          = 'articles'
+  // No record loader → resourceEditData / View fall back to the recordId
+  // for the title; that's still valid copy and exercises the unloaded
+  // path. (Loader-backed paths are covered separately.)
+  static override form(form: Form): Form {
+    return form.schema([TextField.make('title')])
+  }
+}
+
+describe('Phase C breadcrumbs — resource pages', () => {
+  it('list page emits Home / Articles with the trailing item unlinked', async () => {
+    const panel = Pilotiq.make('My Panel').path('/admin').resources([Articles])
+    const data = await resourceIndexData(panel, 'articles')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    assert.deepEqual(items, [
+      { label: 'My Panel', url: '/admin' },
+      { label: 'Articles' },
+    ])
+  })
+
+  it('Resource.breadcrumb overrides label in the resource crumb', async () => {
+    class BlogPosts extends Resource {
+      static override label         = 'Blog Posts'
+      static override labelSingular = 'Blog Post'
+      static override slug          = 'blog-posts'
+      // Tighter chain — the breadcrumb reads better as just "Posts".
+      static override breadcrumb    = 'Posts'
+      static override form(form: Form): Form { return form.schema([TextField.make('title')]) }
+    }
+    const panel = Pilotiq.make('My Panel').path('/admin').resources([BlogPosts])
+    const data = await resourceCreateData(panel, 'blog-posts')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    assert.deepEqual(items, [
+      { label: 'My Panel', url: '/admin' },
+      { label: 'Posts', url: '/admin/blog-posts' },
+      { label: 'Create' },
+    ])
+  })
+
+  it('create page appends a "Create" trailing item', async () => {
+    const panel = Pilotiq.make('My Panel').path('/admin').resources([Articles])
+    const data = await resourceCreateData(panel, 'articles')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    assert.deepEqual(items, [
+      { label: 'My Panel', url: '/admin' },
+      { label: 'Articles', url: '/admin/articles' },
+      { label: 'Create' },
+    ])
+  })
+
+  it('view page renders the record title as the trailing item', async () => {
+    class Loaded extends Articles {
+      static override form(form: Form): Form {
+        return form
+          .schema([TextField.make('title')])
+          .loadRecord(async (id) => ({ id, title: `Loaded ${id}` }))
+      }
+    }
+    const panel = Pilotiq.make('My Panel').path('/admin').resources([Loaded])
+    const data = await resourceViewData(panel, 'articles', '7')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    // ViewPage doesn't run loadRecord (only edit pages do); without an
+    // R.model the resourceViewData record is undefined → falls back to
+    // the recordId.
+    assert.deepEqual(items, [
+      { label: 'My Panel', url: '/admin' },
+      { label: 'Articles', url: '/admin/articles' },
+      { label: '7' },
+    ])
+  })
+
+  it('edit page links the title to the view page when registered', async () => {
+    class Loaded extends Articles {
+      static override form(form: Form): Form {
+        return form
+          .schema([TextField.make('title')])
+          .loadRecord(async (id) => ({ id, title: `Loaded ${id}` }))
+      }
+    }
+    const panel = Pilotiq.make('My Panel').path('/admin').resources([Loaded])
+    const data = await resourceEditData(panel, 'articles', '7')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    assert.deepEqual(items, [
+      { label: 'My Panel', url: '/admin' },
+      { label: 'Articles', url: '/admin/articles' },
+      { label: 'Loaded 7', url: '/admin/articles/7' },
+      { label: 'Edit' },
+    ])
+  })
+
+  it('edit page leaves the title unlinked when the resource has no view page', async () => {
+    class NoView extends Articles {
+      static override pages() { return { view: undefined as never } }
+      static override form(form: Form): Form {
+        return form
+          .schema([TextField.make('title')])
+          .loadRecord(async (id) => ({ id, title: `Loaded ${id}` }))
+      }
+    }
+    const panel = Pilotiq.make('My Panel').path('/admin').resources([NoView])
+    const data = await resourceEditData(panel, 'articles', '7')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    // Title rung carries no `url` — pruned ViewPage means no link.
+    const titleRung = items[items.length - 2]!
+    assert.equal(titleRung.label, 'Loaded 7')
+    assert.equal(titleRung.url, undefined)
+    assert.equal(items[items.length - 1]!.label, 'Edit')
+  })
+
+  it('inserts the cluster rung between Home and the resource', async () => {
+    class ContentCluster extends Cluster {
+      static override label = 'Content'
+      static override slug  = 'content'
+    }
+    class Clustered extends Articles {
+      static override cluster = ContentCluster
+    }
+    const panel = Pilotiq.make('My Panel').path('/admin').resources([Clustered])
+    const data = await resourceIndexData(panel, 'articles')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    assert.deepEqual(items, [
+      { label: 'My Panel',  url: '/admin' },
+      { label: 'Content',   url: '/admin/content' },
+      { label: 'Articles' },
+    ])
+  })
+})
+
+describe('Phase C breadcrumbs — global pages', () => {
+  class SiteSettings extends Global {
+    static override label         = 'Site Settings'
+    static override labelSingular = 'Site Settings'
+    static override slug          = 'site-settings'
+    static override form(form: Form): Form {
+      return form.schema([TextField.make('siteName')])
+    }
+  }
+
+  it('emits Home / <Global label> on the edit page', async () => {
+    const panel = Pilotiq.make('My Panel').path('/admin').globals([SiteSettings])
+    const data = await globalEditData(panel, 'site-settings')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    assert.deepEqual(items, [
+      { label: 'My Panel', url: '/admin' },
+      { label: 'Site Settings' },
+    ])
+  })
+
+  it('emits the same chain on the view page', async () => {
+    class WithView extends SiteSettings {
+      static override pages() {
+        return { view: defaultGlobalViewPage(this as unknown as typeof Global) }
+      }
+    }
+    const panel = Pilotiq.make('My Panel').path('/admin').globals([WithView])
+    const data = await globalViewData(panel, 'site-settings')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    assert.deepEqual(items, [
+      { label: 'My Panel', url: '/admin' },
+      { label: 'Site Settings' },
+    ])
+  })
+})
+
+describe('Phase C breadcrumbs — custom pages', () => {
+  it('emits Home / <Page label>', async () => {
+    class Reports extends Page {
+      static override slug  = 'reports'
+      static override label = 'Reports'
+      static override schema() { return [Heading.make('Reports')] }
+    }
+    const panel = Pilotiq.make('My Panel').path('/admin').pages([Reports])
+    const data = await customPageData(panel, 'reports')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    assert.deepEqual(items, [
+      { label: 'My Panel', url: '/admin' },
+      { label: 'Reports' },
+    ])
+  })
+
+  it('a single-rung chain (only Home) is suppressed entirely', async () => {
+    // Constructing a panel with only the dashboard page never triggers
+    // breadcrumbs at all (we don't prepend on the dashboard). Used as
+    // sanity that a "Home" rung alone doesn't render.
+    const panel = Pilotiq.make('My Panel').path('/admin').schema([Heading.make('Hi')])
+    const data = await import('./pageData.js').then(m => m.dashboardData(panel))
+    const schema = data['schemaData'] as Array<Record<string, unknown>>
+    const meta = schema.find(s => s['type'] === 'breadcrumbs')
+    assert.equal(meta, undefined, 'dashboard page should never carry breadcrumbs')
+  })
+})
+
+describe('Phase C breadcrumbs — branding fallback', () => {
+  it('uses branding.title when set', async () => {
+    const panel = Pilotiq.make('My Panel')
+      .path('/admin')
+      .branding({ title: 'Acme Admin' })
+      .resources([Articles])
+    const data = await resourceIndexData(panel, 'articles')
+    const items = findBreadcrumbs(data!['schemaData'] as Array<Record<string, unknown>>)
+    assert.equal(items[0]!.label, 'Acme Admin')
+    assert.equal(items[0]!.url, '/admin')
+  })
+})

package/src/cells/coerce.test.ts

@@ -0,0 +1,85 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { TextInputColumn, ToggleColumn, SelectColumn } from '../columns/index.js'
+import { coerceCellValue, CellCoerceError } from './coerce.js'
+
+describe('coerceCellValue — TextInputColumn', () => {
+  it('passes string values through unchanged for type=text', () => {
+    const col = TextInputColumn.make('title')
+    assert.equal(coerceCellValue(col, 'hello'), 'hello')
+    assert.equal(coerceCellValue(col, ''),      '')
+  })
+
+  it('coerces numeric input to JS number when type=number', () => {
+    const col = TextInputColumn.make('price').type('number')
+    assert.equal(coerceCellValue(col, '42'),   42)
+    assert.equal(coerceCellValue(col, '3.14'), 3.14)
+    assert.equal(coerceCellValue(col, 7),      7)
+  })
+
+  it('returns null for empty number input (clear semantic)', () => {
+    const col = TextInputColumn.make('price').type('number')
+    assert.equal(coerceCellValue(col, ''),   null)
+    assert.equal(coerceCellValue(col, null), null)
+  })
+
+  it('throws CellCoerceError for non-numeric strings on type=number', () => {
+    const col = TextInputColumn.make('price').type('number')
+    assert.throws(() => coerceCellValue(col, 'abc'), CellCoerceError)
+  })
+
+  it('survives null for non-numeric text input (cell cleared)', () => {
+    const col = TextInputColumn.make('title')
+    assert.equal(coerceCellValue(col, null), null)
+  })
+})
+
+describe('coerceCellValue — ToggleColumn', () => {
+  it('accepts native booleans verbatim', () => {
+    const col = ToggleColumn.make('featured')
+    assert.equal(coerceCellValue(col, true),  true)
+    assert.equal(coerceCellValue(col, false), false)
+  })
+
+  it('parses stringified truthy / falsy markers', () => {
+    const col = ToggleColumn.make('featured')
+    assert.equal(coerceCellValue(col, 'true'),  true)
+    assert.equal(coerceCellValue(col, '1'),     true)
+    assert.equal(coerceCellValue(col, 'on'),    true)
+    assert.equal(coerceCellValue(col, 'false'), false)
+    assert.equal(coerceCellValue(col, '0'),     false)
+    assert.equal(coerceCellValue(col, ''),      false)
+  })
+
+  it('coerces numbers via !==0 like the JS truthiness rule', () => {
+    const col = ToggleColumn.make('featured')
+    assert.equal(coerceCellValue(col, 1), true)
+    assert.equal(coerceCellValue(col, 0), false)
+  })
+})
+
+describe('coerceCellValue — SelectColumn', () => {
+  it('returns the value unchanged when it matches an option', () => {
+    const col = SelectColumn.make('status').options({ draft: 'Draft', published: 'Published' })
+    assert.equal(coerceCellValue(col, 'draft'),     'draft')
+    assert.equal(coerceCellValue(col, 'published'), 'published')
+  })
+
+  it('throws on values not in the option set', () => {
+    const col = SelectColumn.make('status').options({ draft: 'Draft' })
+    assert.throws(() => coerceCellValue(col, 'forged'), CellCoerceError)
+  })
+
+  it('rejects empty / null when the column is NOT nullable', () => {
+    const col = SelectColumn.make('status').options({ draft: 'Draft' })
+    assert.throws(() => coerceCellValue(col, null), CellCoerceError)
+    assert.throws(() => coerceCellValue(col, ''),   CellCoerceError)
+  })
+
+  it('returns null for empty / null when the column IS nullable', () => {
+    const col = SelectColumn.make('status').options({ draft: 'Draft' }).nullable()
+    assert.equal(coerceCellValue(col, null), null)
+    assert.equal(coerceCellValue(col, ''),   null)
+  })
+})

package/src/cells/coerce.ts

@@ -0,0 +1,84 @@
+import type { Column } from '../Column.js'
+import type { TextInputColumn } from '../columns/TextInputColumn.js'
+import type { SelectColumn } from '../columns/SelectColumn.js'
+
+/**
+ * Coerce a raw `_cell` PATCH body value into the right shape for the
+ * given column. JSON / urlencoded bodies arrive as strings; this is the
+ * single place we normalize them before validators run + before the
+ * value lands in `R.model.update(id, { [col]: value })`.
+ *
+ * Throws when a `'number'` text input receives a non-numeric string —
+ * the route handler maps the throw to a 422 with a friendly message
+ * (mirrors how form-level coerce surfaces invalid numeric inputs).
+ *
+ *   coerceCellValue(textInputCol, '42')      → 42 when type='number'
+ *   coerceCellValue(textInputCol, '')        → ''
+ *   coerceCellValue(toggleCol,    'true')    → true
+ *   coerceCellValue(toggleCol,    1)         → true
+ *   coerceCellValue(selectCol,    'draft')   → 'draft'
+ *   coerceCellValue(selectCol,    null)      → null     (when nullable)
+ */
+export function coerceCellValue(col: Column, raw: unknown): unknown {
+  switch (col.getColumnType()) {
+    case 'textInput': {
+      const t = (col as TextInputColumn).getInputType()
+      if (t === 'number') {
+        if (raw === null || raw === '' || raw === undefined) return null
+        const n = typeof raw === 'number' ? raw : Number(String(raw).trim())
+        if (Number.isNaN(n)) {
+          throw new CellCoerceError('Must be a number')
+        }
+        return n
+      }
+      // text / email / url / tel — always a string. `null` survives so
+      // a nullable column can be cleared from the cell.
+      if (raw === null || raw === undefined) return null
+      return typeof raw === 'string' ? raw : String(raw)
+    }
+    case 'toggle': {
+      // Accept boolean, number, and the common string truthy markers
+      // ('true', '1', 'on'). Falsy strings ('', 'false', '0') → false.
+      if (typeof raw === 'boolean') return raw
+      if (typeof raw === 'number')  return raw !== 0
+      if (typeof raw === 'string') {
+        const v = raw.toLowerCase().trim()
+        if (v === 'true' || v === '1' || v === 'on' || v === 'yes')  return true
+        if (v === 'false' || v === '0' || v === 'off' || v === 'no' || v === '') return false
+      }
+      return Boolean(raw)
+    }
+    case 'select': {
+      // Validate against the configured option set so a forged body
+      // can't write an arbitrary string. `null` is accepted only when
+      // the column was marked `.nullable()`.
+      const sel = col as SelectColumn
+      const opts = sel.getOptions()
+      if (raw === null || raw === '' || raw === undefined) {
+        // `selectNullable` is internal to SelectColumn — re-derive from
+        // toMeta so we don't have to expose a getter.
+        const meta = sel.toMeta()
+        if (meta.selectNullable) return null
+        throw new CellCoerceError('A value is required')
+      }
+      const value = String(raw)
+      if (!opts.some(o => o.value === value)) {
+        throw new CellCoerceError(`"${value}" is not a valid option`)
+      }
+      return value
+    }
+    default:
+      // Read-only columns can't reach the route (the handler 400s on
+      // `!col.isEditable()`), but stay defensive — return raw verbatim.
+      return raw
+  }
+}
+
+/** Thrown by `coerceCellValue` when the raw value doesn't fit the column.
+ * The route handler catches this and replies with 422 + the message. */
+export class CellCoerceError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CellCoerceError'
+  }
+}

package/src/clusterPaths.ts

@@ -0,0 +1,35 @@
+import type { ResourceClass } from './Resource.js'
+import type { GlobalClass } from './Global.js'
+import type { ClusterClass } from './Cluster.js'
+import type { Page } from './Page.js'
+
+// Lives in its own module so Resource / Global / Page can import the
+// helpers without dragging in Cluster.ts and tripping a cycle.
+
+interface ClusterableChild {
+  cluster?: ClusterClass
+  getSlug(): string
+}
+
+function childBasePath(panelBase: string, child: ClusterableChild): string {
+  const slug = child.getSlug()
+  return child.cluster
+    ? `${panelBase}/${child.cluster.getSlug()}/${slug}`
+    : `${panelBase}/${slug}`
+}
+
+export function resourceBasePath(panelBase: string, R: ResourceClass): string {
+  return childBasePath(panelBase, R)
+}
+
+export function globalBasePath(panelBase: string, G: GlobalClass): string {
+  return childBasePath(panelBase, G)
+}
+
+export function pageBasePath(panelBase: string, P: typeof Page): string {
+  return childBasePath(panelBase, P)
+}
+
+export function clusterBasePath(panelBase: string, C: ClusterClass): string {
+  return `${panelBase}/${C.getSlug()}`
+}

package/src/columns/BadgeColumn.test.ts

@@ -0,0 +1,54 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { BadgeColumn } from './BadgeColumn.js'
+
+describe('BadgeColumn', () => {
+  it('emits columnType:badge with the value→color map', () => {
+    const meta = BadgeColumn.make('status')
+      .colors({ draft: 'gray', published: 'success', archived: 'warning' })
+      .toMeta()
+    assert.equal(meta.columnType, 'badge')
+    assert.deepEqual(meta.badgeColors, {
+      draft: 'gray', published: 'success', archived: 'warning',
+    })
+  })
+
+  it('omits badgeColors when no map is set', () => {
+    const meta = BadgeColumn.make('status').toMeta()
+    assert.equal(meta.columnType, 'badge')
+    assert.equal(meta.badgeColors, undefined)
+  })
+
+  it('inherits all base column builders', () => {
+    const meta = BadgeColumn.make('status').sortable().tooltip('Status').toMeta()
+    assert.equal(meta.sortable, true)
+    assert.equal(meta.tooltip,  'Status')
+  })
+
+  it('successive .colors() calls merge instead of replace', () => {
+    const meta = BadgeColumn.make('status')
+      .colors({ draft: 'gray' })
+      .colors({ published: 'success' })
+      .toMeta()
+    assert.deepEqual(meta.badgeColors, { draft: 'gray', published: 'success' })
+  })
+
+  it('later keys win on collision', () => {
+    const meta = BadgeColumn.make('status')
+      .colors({ pending: 'gray' })
+      .colors({ pending: 'warning' })
+      .toMeta()
+    assert.equal(meta.badgeColors?.['pending'], 'warning')
+  })
+
+  it('composes with formatStateUsing for server-side label rewrites', () => {
+    const col = BadgeColumn.make('status')
+      .colors({ draft: 'gray' })
+      .formatStateUsing((v) => `[${v}]`)
+    const meta = col.toMeta()
+    assert.equal(meta.columnType,   'badge')
+    assert.equal(meta.hasFormatter, true)
+    assert.deepEqual(meta.badgeColors, { draft: 'gray' })
+  })
+})

package/src/columns/BadgeColumn.ts

@@ -0,0 +1,32 @@
+import { Column, type ColumnMeta } from '../Column.js'
+
+/** Badge color preset → tailwind class group. Resolved client-side. */
+export type BadgeColor =
+  | 'gray' | 'primary' | 'success' | 'warning' | 'destructive' | 'info'
+
+/**
+ * Renders the cell value as a colored pill / chip. Use a value→color map
+ * to assign different presets per status: e.g. drafts grey, published
+ * green, archived amber. Unknown values fall back to `gray`.
+ */
+export class BadgeColumn extends Column {
+  protected _colors: Record<string, BadgeColor> = {}
+
+  static override make(name: string): BadgeColumn {
+    const c = new BadgeColumn(name)
+    c.setColumnType('badge')
+    return c
+  }
+
+  /** value-to-color map. */
+  colors(map: Record<string, BadgeColor>): this {
+    this._colors = { ...this._colors, ...map }
+    return this
+  }
+
+  protected override serializeExtras(meta: ColumnMeta): void {
+    if (Object.keys(this._colors).length > 0) {
+      meta.badgeColors = this._colors
+    }
+  }
+}

package/src/columns/BooleanColumn.test.ts

@@ -0,0 +1,41 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { BooleanColumn } from './BooleanColumn.js'
+import { IconColumn } from './IconColumn.js'
+
+describe('BooleanColumn', () => {
+  it('extends IconColumn with default true/false icons', () => {
+    const meta = BooleanColumn.make('featured').toMeta()
+    assert.equal(meta.columnType, 'boolean')
+    assert.equal(meta.iconOptions?.['true']?.icon,  'check-circle-2')
+    assert.equal(meta.iconOptions?.['true']?.color, 'success')
+    assert.equal(meta.iconOptions?.['false']?.icon,  'circle')
+    assert.equal(meta.iconOptions?.['false']?.color, 'muted')
+  })
+
+  it('options() override the defaults', () => {
+    const meta = BooleanColumn.make('active')
+      .options({
+        true:  { icon: 'check', color: 'success' },
+        false: { icon: 'x',     color: 'muted'   },
+      })
+      .toMeta()
+    assert.equal(meta.iconOptions?.['true']?.icon,  'check')
+    assert.equal(meta.iconOptions?.['false']?.icon, 'x')
+  })
+
+  it('is structurally an IconColumn', () => {
+    const c = BooleanColumn.make('featured')
+    assert.equal(c instanceof IconColumn, true)
+  })
+
+  it('inherits the cosmetic chain', () => {
+    const meta = BooleanColumn.make('on')
+      .alignment('center')
+      .tooltip('On / off')
+      .toMeta()
+    assert.equal(meta.alignment, 'center')
+    assert.equal(meta.tooltip,   'On / off')
+  })
+})

package/src/columns/BooleanColumn.ts

@@ -0,0 +1,18 @@
+import { IconColumn } from './IconColumn.js'
+
+/**
+ * Sugar over `IconColumn` that defaults to a check / x rendering for
+ * boolean values. Override the icons / colors via `.options()` if the
+ * defaults don't fit.
+ */
+export class BooleanColumn extends IconColumn {
+  static override make(name: string): BooleanColumn {
+    const c = new BooleanColumn(name)
+    c.setColumnType('boolean')
+    c.options({
+      true:  { icon: 'check-circle-2', color: 'success' },
+      false: { icon: 'circle',         color: 'muted'   },
+    })
+    return c
+  }
+}

package/src/columns/ColorColumn.test.ts

@@ -0,0 +1,37 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { ColorColumn } from './ColorColumn.js'
+
+describe('ColorColumn', () => {
+  it('emits columnType:color with the default rounded shape', () => {
+    const meta = ColorColumn.make('accent').toMeta()
+    assert.equal(meta.columnType, 'color')
+    assert.equal(meta.colorShape, 'rounded')
+    assert.equal(meta.colorHideValue, undefined)
+  })
+
+  it('square() flips the shape', () => {
+    const meta = ColorColumn.make('accent').square().toMeta()
+    assert.equal(meta.colorShape, 'square')
+  })
+
+  it('circle() flips the shape', () => {
+    const meta = ColorColumn.make('accent').circle().toMeta()
+    assert.equal(meta.colorShape, 'circle')
+  })
+
+  it('hideValue() emits the suppress flag', () => {
+    const meta = ColorColumn.make('accent').hideValue().toMeta()
+    assert.equal(meta.colorHideValue, true)
+  })
+
+  it('inherits alignment / tooltip chain from Column', () => {
+    const meta = ColorColumn.make('accent')
+      .alignment('center')
+      .tooltip('Brand color')
+      .toMeta()
+    assert.equal(meta.alignment, 'center')
+    assert.equal(meta.tooltip,   'Brand color')
+  })
+})

package/src/columns/ColorColumn.ts

@@ -0,0 +1,38 @@
+import { Column, type ColumnMeta } from '../Column.js'
+
+/**
+ * Renders the cell as a color swatch — pairs with `ColorPickerField`.
+ * The raw cell value is treated as a CSS color string (HEX, HSL, RGB,
+ * RGBA, named) and applied as the swatch's `background-color`. The
+ * accompanying value text is shown beside the swatch unless
+ * `hideValue()` is set.
+ *
+ *   ColorColumn.make('accent')
+ *     .square()      // shape; default is `rounded()`
+ *     .hideValue()   // chip only
+ */
+export class ColorColumn extends Column {
+  protected _shape:     'rounded' | 'square' | 'circle' = 'rounded'
+  protected _hideValue: boolean = false
+
+  static override make(name: string): ColorColumn {
+    const c = new ColorColumn(name)
+    c.setColumnType('color')
+    return c
+  }
+
+  /** Default — slightly rounded swatch. */
+  rounded(): this { this._shape = 'rounded'; return this }
+  /** Sharp-cornered swatch. */
+  square():  this { this._shape = 'square';  return this }
+  /** Circle swatch. */
+  circle():  this { this._shape = 'circle';  return this }
+
+  /** Drop the value text — render only the swatch. */
+  hideValue(v = true): this { this._hideValue = v; return this }
+
+  protected override serializeExtras(meta: ColumnMeta): void {
+    meta.colorShape = this._shape
+    if (this._hideValue) meta.colorHideValue = true
+  }
+}