4d:I[707087,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/2rwy6tq861e-y.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/2hlz_ivp-qrnh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2zoahorp76dll.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1d0aij627lbx2.js","/_next/static/immutable/chunks/1ud4fi_ghnsx-.js"],"RegistryDependencies"] 4e:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/2rwy6tq861e-y.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/2hlz_ivp-qrnh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2zoahorp76dll.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1d0aij627lbx2.js","/_next/static/immutable/chunks/1ud4fi_ghnsx-.js"],"FilesView"] 4f:T178c,import { col as _col, resolveColumns } from "./col"; import { presets } from "./presets"; import { deserializeSchema, migrateSchemaJSON, serializeSchema, } from "./serialize"; import { validateSchema } from "./validate"; /** * Column builder factories and presets for defining table schemas. * * **Primitive factories** — choose based on the data type of the column: * - `col.string()` — text data (`string`) * - `col.number()` — numeric data (`number`) * - `col.boolean()` — boolean data (`boolean`) * - `col.timestamp()` — date/time data (`Date`) * - `col.enum(values)` — string union (`T[number]`) * - `col.array(item)` — array of values (`U[]`) * - `col.record()` — key-value map (`Record`) * * **Presets** — pre-configured builders for common log table patterns: * - `col.presets.logLevel(values)` — severity levels * - `col.presets.httpMethod(values)` — HTTP verbs * - `col.presets.httpStatus(codes?)` — HTTP status codes * - `col.presets.duration(unit?, slider?)` — timing / latency * - `col.presets.timestamp()` — sortable timestamp with timerange filter * - `col.presets.traceId()` — trace / request ID (code display, not filterable) * - `col.presets.pathname()` — URL path with text search * * @example * ```ts * import { col, createTableSchema } from "@/lib/table-schema"; * * export const tableSchema = createTableSchema({ * level: col.presets.logLevel(LEVELS).description("Log severity"), * date: col.presets.timestamp().label("Date").size(200).sheet(), * latency: col.presets.duration("ms").label("Latency").sortable().size(110).sheet(), * status: col.presets.httpStatus().label("Status").size(60), * method: col.presets.httpMethod(METHODS).size(69), * host: col.string().label("Host").size(125).sheet(), * headers: col.record().label("Headers").hidden().sheet(), * }); * ``` */ export const col = { ..._col, presets }; export type { ColBuilder, ColKind, ColRenderers, ColumnDescriptor, ColumnDescriptorCommon, DatePresetDescriptor, DisplayConfig, DisplayDescriptor, FilterDescriptor, FilterType, InferTableType, JsonValue, OptionDescriptor, Provenance, ResolvedColumn, ResolvedColumnEntry, SchemaJSON, SchemaJSONVersion, SerializableDisplayConfig, SheetConfig, SheetDescriptor, TableSchemaDefinition, } from "./types"; export { resolveColumn, resolveColumns } from "./col"; export { NAMED_DISPLAY_TYPES, applyRenderers, isNamedDisplayType, type ApplyRenderersOptions, type NamedDisplayType, type RendererOverrides, } from "./renderers"; export { generateColumns } from "./generators/columns"; export { generateFilterFields } from "./generators/filter-fields"; export { generateFilterSchema } from "./generators/filter-schema"; export { generateSheetFields } from "./generators/sheet-fields"; export { SCHEMA_JSON_VERSION, deserializeSchema, migrateSchemaJSON, serializeSchema, } from "./serialize"; export { DEFAULT_CAPABILITIES, MANIFEST_LIMITS, TABLE_MANIFEST_VERSION, TableManifestError, createRowAccessors, createTableManifest, createTableManifestHandler, fetchTableManifest, isSafeColumnKey, manifestETag, parseTableManifest, type FetchManifestOptions, type ManifestHandlerOptions, type ParseManifestOptions, type RowAccessors, } from "./manifest"; export { type TableCapabilities, type TableChartConfig, type TableManifest, type TableManifestDefaults, } from "./manifest"; export { manifestToModule, pullManifestModule, type SnapshotOptions, } from "./snapshot"; /** * Derive defaultColumnVisibility from the schema. * Returns { [key]: false } for every column marked with .hidden(). */ export function getDefaultColumnVisibility( schema: import("./types").TableSchemaDefinition, ): Record { const visibility: Record = {}; for (const { key, hidden } of resolveColumns(schema)) { if (hidden) visibility[key] = false; } return visibility; } /** * Create a table schema from a map of col.* builders. * * The returned object holds the definition and exposes: * - `toJSON()` — serializes the schema to a function-free JSON descriptor, * suitable for AI agents, MCP tools, and `JSON.stringify`. * * Use `createTableSchema.fromJSON(json)` to reconstruct a schema from a * JSON descriptor (e.g. one generated by an AI agent). Custom renderers * (display.cell, filter.component, sheet.component) are not serialized and * must be applied manually on top of the reconstructed builders. * * @example * ```ts * export const tableSchema = createTableSchema({ * level: col.enum(LEVELS).label("Level").defaultOpen().sheet(), * date: col.timestamp().label("Date").sortable().size(200).sheet(), * }); * * export type ColumnSchema = InferTableType; * * // Serialize for an AI agent or MCP tool * const json = tableSchema.toJSON(); * // JSON.stringify(tableSchema) also works — toJSON() is called automatically * * // Reconstruct from AI-generated JSON * const schema = createTableSchema.fromJSON(json); * ``` */ export function createTableSchema< T extends import("./types").TableSchemaDefinition, >(definition: T): { definition: T; toJSON(): import("./types").SchemaJSON } { validateSchema(definition); return { definition, toJSON() { return serializeSchema(definition); }, }; } /** * Reconstruct a schema from a JSON descriptor. * * Takes `unknown` on purpose: the builder pastes user-typed text in here, and * the cache replays JSON written by an older build. `migrateSchemaJSON` brings * older versions forward and throws on anything unrecognisable, so the cast * that used to sit on untrusted input is gone. */ createTableSchema.fromJSON = ( json: unknown, ): { definition: import("./types").TableSchemaDefinition; toJSON(): import("./types").SchemaJSON; } => { return createTableSchema(deserializeSchema(migrateSchemaJSON(json))); }; 50:T4495,import type { DatePreset, Option, } from "@/components/data-table/types"; import type { ColBuilder, ColKind, ColRenderers, ColumnDescriptor, ColumnDescriptorCommon, DatePresetDescriptor, DisplayDescriptor, FilterDescriptor, FilterType, OptionDescriptor, Provenance, ResolvedColumn, ResolvedColumnEntry, SheetConfig, TableSchemaDefinition, } from "./types"; // ── Per-kind defaults — the ONE definition ────────────────────────────────── /** * The default cell display for a column kind. * * This is the single definition. `infer.ts`, `generators/sheet-fields.ts`, and * `serialize.ts` each used to carry their own copy, and the third disagreed * with the other two. */ export function defaultDisplayForKind(kind: ColKind): DisplayDescriptor { switch (kind) { case "number": return { type: "number" }; case "boolean": case "select": return { type: "boolean" }; case "timestamp": return { type: "timestamp" }; case "enum": case "array": return { type: "badge" }; case "string": case "record": return { type: "text" }; } } const MANUAL: Provenance = { source: "manual" }; /** * Drop keys whose value is `undefined`. * * Descriptors have to be canonical: `JSON.stringify` erases an explicit * `undefined`, so a descriptor carrying one compares unequal to its own round * trip under `toStrictEqual` and under any key-based comparison, while looking * identical through `JSON`. `display("number", { unit: undefined })` — which * `col.presets.duration()` produces whenever no unit is given — is the case * that actually occurs. * * Exported for `infer.ts`, which builds descriptors outside the builder and so * has to hold the same invariant. */ export function compact>(object: T): T { const result = {} as Record; for (const [key, value] of Object.entries(object)) { if (value !== undefined) result[key] = value; } return result as T; } /** * Strip caller-supplied `Option`s down to their serializable fields. * * `Option.value` is `string | boolean | number | undefined`, but an option with * no value cannot be selected, cannot be encoded into filter state, and would * vanish from the descriptor on `JSON.stringify` — so it is dropped here, * at construction, rather than disappearing later at serialization time. */ function toOptionDescriptors(options: readonly Option[]): OptionDescriptor[] { const result: OptionDescriptor[] = []; for (const option of options) { if (option.value === undefined) continue; result.push({ label: option.label, value: option.value }); } return result; } /** Store preset bounds as ISO instants so they survive JSON. */ function toPresetDescriptor(preset: DatePreset): DatePresetDescriptor { return { label: preset.label, shortcut: preset.shortcut, from: preset.from.toISOString(), to: preset.to.toISOString(), }; } /** Revive a serialized preset back into the `DatePreset` the UI consumes. */ export function fromPresetDescriptor( descriptor: DatePresetDescriptor, ): DatePreset { return { label: descriptor.label, shortcut: descriptor.shortcut, from: new Date(descriptor.from), to: new Date(descriptor.to), }; } // ── The builder ───────────────────────────────────────────────────────────── /** * Build a `ColBuilder` over an explicit descriptor + renderers pair. * * Exported because `deserializeSchema` reconstructs builders by handing a * descriptor straight back — no per-field replay of the fluent chain. */ export function createColBuilder( descriptor: ColumnDescriptor, renderers: ColRenderers = {}, ): ColBuilder { // The implementation uses loose parameter types to satisfy all overload // signatures at once. TypeScript enforces the constraints at call sites // via the ColBuilder interface overloads, not here. const next = ( patch: Partial, rendererPatch?: ColRenderers, ): ColBuilder => createColBuilder( { ...descriptor, ...patch } as ColumnDescriptor, rendererPatch ? compact({ ...renderers, ...rendererPatch }) : renderers, ); /** Return `renderers` without the named closures. */ const withoutRenderers = (...keys: (keyof ColRenderers)[]): ColRenderers => { const result = { ...renderers }; for (const key of keys) delete result[key]; return result; }; const builder = { get _descriptor() { return descriptor; }, get _renderers() { return renderers; }, label(text: string): ColBuilder { return next({ label: text }); }, description(text: string): ColBuilder { return next({ description: text }); }, display(type: string, options?: Record): ColBuilder { // "custom" is not a descriptor state — the closure goes to the renderers // half and the descriptor keeps whatever serializable display it had, so // it is already the correct fallback for the sheet and for toJSON(). if (type === "custom") { const { cell, colorMap } = options as { cell: ColRenderers["cell"]; colorMap?: Record; }; return next( colorMap ? { display: { ...descriptor.display, colorMap, } as DisplayDescriptor, } : {}, { cell }, ); } const display = compact( options ? { type, ...options } : { type }, ) as DisplayDescriptor; return next({ display }); }, filterable( type?: string, options?: Record, ): ColBuilder { const filterType = (type || descriptor.filter?.type || "input") as FilterType; const existing = descriptor.filter; const sameType = filterType === existing?.type; const { component, options: rawOptions, presets: rawPresets, ...rest } = (options ?? {}) as { component?: ColRenderers["filterComponent"]; options?: Option[]; presets?: DatePreset[]; min?: number; max?: number; unit?: string; }; const filter: FilterDescriptor = { type: filterType, defaultOpen: existing?.defaultOpen ?? false, commandDisabled: existing?.commandDisabled ?? false, // Preserve auto-derived options when the filter type stays the same // and no explicit options are provided by the caller. ...(sameType && existing?.options ? { options: existing.options } : {}), ...compact(rest), ...(rawOptions ? { options: toOptionDescriptors(rawOptions) } : {}), ...(rawPresets ? { presets: rawPresets.map(toPresetDescriptor) } : sameType && existing?.presets ? { presets: existing.presets } : {}), }; return next( { filter }, component ? { filterComponent: component } : undefined, ); }, notFilterable(): ColBuilder { return createColBuilder( { ...descriptor, filter: null }, // The filter component is meaningless without a filter. withoutRenderers("filterComponent"), ); }, defaultOpen(): ColBuilder { if (!descriptor.filter) return next({}); return next({ filter: { ...descriptor.filter, defaultOpen: true }, }); }, commandDisabled(): ColBuilder { if (!descriptor.filter) return next({}); return next({ filter: { ...descriptor.filter, commandDisabled: true }, }); }, hidden(): ColBuilder { return next({ hidden: true }); }, hideHeader(): ColBuilder { return next({ hideHeader: true }); }, resizable(): ColBuilder { return next({ resizable: true }); }, size(px: number): ColBuilder { return next({ size: px }); }, minSize(px: number): ColBuilder { return next({ minSize: px }); }, sortable(): ColBuilder { return next({ sortable: true }); }, optional(): ColBuilder { return next({ optional: true }); }, sheet(sheetConfig?: SheetConfig): ColBuilder { const { component, condition, ...sheetDescriptor } = sheetConfig ?? {}; return next( { sheet: compact(sheetDescriptor) }, compact({ sheetComponent: component, sheetCondition: condition }), ); }, sheetOnly(): ColBuilder { return createColBuilder( { ...descriptor, hidden: true, filter: null, enableHiding: false, }, withoutRenderers("filterComponent"), ); }, } as ColBuilder; return builder; } /** * Attach provenance to a builder. * * Internal to this package — `col.presets.*` records which preset produced the * column and with what arguments, and `infer.ts` records which heuristic fired. * `schemaToTypeScript` reads this instead of pattern-matching the descriptor. */ export function withProvenance( builder: ColBuilder, provenance: Provenance, ): ColBuilder { return createColBuilder( { ...builder._descriptor, provenance }, builder._renderers, ); } // ── The public read model ─────────────────────────────────────────────────── /** * Read a column's complete state — both halves — through one public accessor. * * Prefer this over reaching into `_descriptor` / `_renderers`, which are * `@internal` and may change shape. */ // `any` on the filter-type parameter: callers hold builders of every filter // type at once, and the read model does not depend on which one it is. export function resolveColumn( builder: ColBuilder, ): ResolvedColumn { return { ...builder._descriptor, renderers: builder._renderers }; } /** `resolveColumn` over a whole definition, preserving key insertion order. */ export function resolveColumns( definition: TableSchemaDefinition, ): ResolvedColumnEntry[] { return Object.entries(definition).map(([key, builder]) => ({ key, ...resolveColumn(builder), })); } // ── Factories ─────────────────────────────────────────────────────────────── /** The descriptor every `col.*` factory starts from, before kind-specific bits. */ function base(kind: ColKind): ColumnDescriptorCommon { return { optional: false, label: "", display: defaultDisplayForKind(kind), hidden: false, enableHiding: true, hideHeader: false, resizable: false, sortable: false, filter: null, sheet: null, provenance: MANUAL, }; } /** * A string column. * * - Data type: `string` * - Default display: `"text"` (plain text with overflow tooltip) * - Default filter: `"input"` (text search) * - Allowed filters: `"input"` * * @example * col.string().label("Host").size(125).sheet() * col.string().label("Message").notFilterable().optional().hidden() */ function string(): ColBuilder { return createColBuilder({ ...base("string"), kind: "string", filter: { type: "input", defaultOpen: false, commandDisabled: false }, }); } /** * A numeric column. * * - Data type: `number` * - Default display: `"number"` (formatted, with optional unit) * - Default filter: `"input"` (exact match) * - Allowed filters: `"input"` | `"slider"` | `"checkbox"` * - Use `"slider"` for continuous values (latency, file size) * - Use `"checkbox"` for discrete values (HTTP status codes, port numbers) * * @example * col.number().label("Latency").display("number", { unit: "ms" }).filterable("slider", { min: 0, max: 5000 }).sortable() * col.number().label("Status").filterable("checkbox", { options: [{ label: "200", value: 200 }] }) */ function number(): ColBuilder { return createColBuilder({ ...base("number"), kind: "number", filter: { type: "input", defaultOpen: false, commandDisabled: false }, }); } /** * A boolean column. * * - Data type: `boolean` * - Default display: `"boolean"` (checkmark / dash icon) * - Default filter: `"checkbox"` with `true` / `false` options pre-wired * - Allowed filters: `"checkbox"` * * @example * col.boolean().label("Cache Hit").defaultOpen() */ function boolean(): ColBuilder { return createColBuilder({ ...base("boolean"), kind: "boolean", filter: { type: "checkbox", defaultOpen: false, commandDisabled: false, options: [ { label: "true", value: true }, { label: "false", value: false }, ], }, }); } /** * A timestamp column. * * - Data type: `Date` * - Default display: `"timestamp"` (relative time, absolute datetime on hover) * - Default filter: `"timerange"` (date range picker) * - Allowed filters: `"timerange"` * * @example * col.timestamp().label("Date").sortable().commandDisabled().size(200).sheet() */ function timestamp(): ColBuilder { return createColBuilder({ ...base("timestamp"), kind: "timestamp", filter: { type: "timerange", defaultOpen: false, commandDisabled: true }, }); } /** * An enum column from a `readonly string[]` union. * * - Data type: `T[number]` (union of the provided string literals) * - Default display: `"badge"` (colored chip) * - Default filter: `"checkbox"` with options auto-derived from `values` * - Allowed filters: `"checkbox"` * * Checkbox options are auto-derived from `values` by default. Override them via * `.filterable("checkbox", { options: [...] })` when you need custom labels, * icons, or a subset of values. * * @param values - `as const` array of allowed string values * * @example * col.enum(LEVELS).label("Level").defaultOpen() * col.enum(LEVELS).label("Level").filterable("checkbox", { * options: LEVELS.map(v => ({ label: v, value: v })), // override labels * }) */ function colEnum( values: T, ): ColBuilder { return createColBuilder({ ...base("enum"), kind: "enum", enumValues: values, filter: { type: "checkbox", defaultOpen: false, commandDisabled: false, options: Array.from(values).map((v) => ({ label: v, value: v })), }, }); } /** * An array column, typically used for multi-value enum fields. * * - Data type: `U[]` where `U` is the item builder's type * - Default display: `"badge"` (colored chip per value) * - Default filter: `"checkbox"` * - Allowed filters: `"checkbox"` * * Most commonly used as `col.array(col.enum(values))` for tags / regions / labels. * `col.array(col.string())` is equally valid — the item type is recorded, so a * `string[]` column stays a `string[]` column across a JSON round trip. * * @param itemBuilder - A `ColBuilder` describing the array item type * * @example * col.array(col.enum(REGIONS)).label("Regions").filterable("checkbox", { * options: REGIONS.map(r => ({ label: r, value: r })), * }) */ function array( itemBuilder: ColBuilder, ): ColBuilder { return createColBuilder({ ...base("array"), kind: "array", arrayItem: itemBuilder._descriptor, filter: { type: "checkbox", defaultOpen: false, commandDisabled: false }, }); } /** * A key-value record column. * * - Data type: `Record` * - Default display: `"text"` * - Not filterable (`F = never`) * * Use for metadata maps, HTTP headers, environment variables, etc. * Typically rendered with a custom sheet component (key-value table / tabs). * * @example * col.record().label("Headers").hidden().sheet({ * component: (row) => , * className: "flex-col items-start w-full gap-1", * }) */ function record(): ColBuilder, never> { return createColBuilder, never>({ ...base("record"), kind: "record", }); } /** * A row-selection checkbox column. * * - Data type: `boolean` (selected state) * - Not filterable (`F = never`) * - Not shown in sheet or filters * - Renders a checkbox in both the header (select all) and each row * * @example * col.select().label("Select") */ function select(): ColBuilder { return createColBuilder({ ...base("select"), kind: "select", label: "Select", enableHiding: false, size: 40, }); } export const col = { string, number, boolean, timestamp, enum: colEnum, array, record, select, }; 51:T2372,import { col, withProvenance } from "./col"; import type { ColBuilder, FilterType, JsonValue } from "./types"; /** * Tag a preset-built column so `schemaToTypeScript` can re-emit the exact call * instead of reverse-engineering it from the descriptor's shape. */ function tag( preset: string, args: readonly (JsonValue | undefined)[], builder: ColBuilder, ): ColBuilder { // Trailing omitted args are dropped so the re-emitted call matches what the // author wrote: `duration("ms")`, not `duration("ms", undefined)`. An omitted // arg in the *middle* becomes `null`, which the emitter prints as `undefined` // — `undefined` inside a JSON array does not survive `JSON.stringify`. const trimmed = [...args]; while (trimmed.length > 0 && trimmed[trimmed.length - 1] === undefined) { trimmed.pop(); } return withProvenance(builder, { source: "preset", preset, args: trimmed.map((a) => (a === undefined ? null : a)), }); } const DEFAULT_HTTP_STATUS_CODES = [ 200, 201, 204, 301, 302, 400, 401, 403, 404, 422, 429, 500, 502, 503, 504, ]; /** * Pre-configured column builders for patterns common in log and observability tables. * * Every preset returns a `ColBuilder` with sensible defaults already applied. * All builders remain fully customizable — chain additional methods to override * any default (label, size, display, sheet, etc.). * * @example * ```ts * const tableSchema = createTableSchema({ * level: col.presets.logLevel(LEVELS).description("Log severity"), * date: col.presets.timestamp().label("Date").size(200).sheet(), * latency: col.presets.duration("ms").label("Latency").sortable().size(110).sheet(), * status: col.presets.httpStatus().label("Status").size(60), * method: col.presets.httpMethod(METHODS).size(69), * path: col.presets.pathname().label("Path").size(130).sheet(), * traceId: col.presets.traceId().label("Request ID").hidden().sheet(), * }); * ``` */ export const presets = { /** * A log severity level column. * * Defaults: enum + badge display + checkbox filter + `defaultOpen`. * Checkbox options are auto-derived from `values` — no need to map them manually. * * @param values - The allowed severity levels, e.g. `["error", "warn", "info", "debug"] as const` * * @example * ```ts * col.presets.logLevel(LEVELS) * .label("Level") * .description("Log severity: error > warn > info > debug") * .size(27) * ``` */ logLevel( values: T, ): ColBuilder { return tag( "logLevel", [values as readonly string[]], col .enum(values) .label("Level") .filterable("checkbox", { options: values.map((v) => ({ label: v, value: v })), }) .defaultOpen(), ); }, /** * An HTTP method column. * * Defaults: enum + plain text display + checkbox filter. * Options are auto-derived from `values`. * * @param values - The allowed HTTP methods, e.g. `["GET", "POST", "PUT", "DELETE"] as const` * * @example * ```ts * col.presets.httpMethod(METHODS).size(69) * ``` */ httpMethod( values: T, ): ColBuilder { return tag( "httpMethod", [values as readonly string[]], col .enum(values) .label("Method") .display("text") .filterable("checkbox", { options: values.map((v) => ({ label: v, value: v })), }), ); }, /** * An HTTP status code column. * * Defaults: number + checkbox filter with a standard set of common status codes. * Pass a custom `codes` array to override the defaults. * * Default codes: 200, 201, 204, 301, 302, 400, 401, 403, 404, 422, 429, 500, 502, 503, 504 * * @param codes - Override the default status code options * * @example * ```ts * col.presets.httpStatus().label("Status").size(60) * col.presets.httpStatus([200, 400, 500]).label("Status") // custom codes * ``` */ httpStatus( codes?: number[], ): ColBuilder { return tag( "httpStatus", [codes as readonly number[] | undefined], col .number() .label("Status") .filterable("checkbox", { options: (codes ?? DEFAULT_HTTP_STATUS_CODES).map((code) => ({ label: String(code), value: code, })), }), ); }, /** * A duration / latency / timing column. * * Defaults: number + formatted number display with unit + slider filter * with bounds `{ min: 0, max: 5000 }`. * * @param unit - Unit label shown after the value, e.g. `"ms"`, `"s"`, `"µs"` * @param slider - Override the slider bounds (default: `{ min: 0, max: 5000 }`) * * @example * ```ts * col.presets.duration("ms").label("Latency").sortable().size(110).sheet() * col.presets.duration("s", { min: 0, max: 60 }).label("Response time") * ``` */ duration( unit?: string, slider?: { min: number; max: number }, ): ColBuilder { return tag( "duration", [unit, slider], col .number() .label("Duration") .display("number", { unit }) .filterable("slider", slider ?? { min: 0, max: 5000 }), ); }, /** * A timestamp column. * * Defaults: Date + relative timestamp display (absolute on hover) + * timerange filter + sortable. * * @example * ```ts * col.presets.timestamp().label("Date").commandDisabled().size(200).sheet() * ``` */ timestamp(): ColBuilder { return tag( "timestamp", [], col.timestamp().label("Timestamp").display("timestamp").sortable(), ); }, /** * A trace / span / request ID column. * * Defaults: string + monospace code display + not filterable. * Typically hidden in the table and shown only in the row detail drawer. * * @example * ```ts * col.presets.traceId().label("Request ID").hidden().sheet({ skeletonClassName: "w-64" }) * ``` */ traceId(): ColBuilder { return tag( "traceId", [], col.string().label("Trace ID").display("code").notFilterable(), ); }, /** * A URL pathname column. * * Defaults: string + plain text display + input (text search) filter. * * @example * ```ts * col.presets.pathname().size(130).sheet() * ``` */ pathname(): ColBuilder { return tag( "pathname", [], col.string().label("Pathname").filterable("input"), ); }, /** * A latency column with heatmap visualization. * * Defaults: number + heatmap display with unit + slider filter * with bounds `{ min: 0, max: 5000 }` + sortable. * * @param unit - Unit label shown after the value, e.g. `"ms"`, `"s"`, `"µs"` * @param slider - Override the slider bounds (default: `{ min: 0, max: 5000 }`) * * @example * ```ts * col.presets.latency("ms").label("Latency").size(110).sheet() * col.presets.latency("s", { min: 0, max: 60 }).label("Response time") * ``` */ latency( unit?: string, slider?: { min: number; max: number }, ): ColBuilder { const bounds = slider ?? { min: 0, max: 5000 }; return tag( "latency", [unit, slider], col .number() .label("Latency") .display("heatmap", { unit, min: bounds.min, max: bounds.max }) .filterable("slider", bounds) .sortable(), ); }, /** * A health/score column with gauge visualization. * * Defaults: number + gauge display (0–100) + sortable. * * @param range - Override the min/max range (default: `{ min: 0, max: 100 }`) * * @example * ```ts * col.presets.health().label("Health") * col.presets.health({ min: 0, max: 1000 }).label("Score") * ``` */ health(range?: { min: number; max: number; }): ColBuilder { const { min = 0, max = 100 } = range ?? {}; return tag( "health", [range], col.number().label("Health").display("gauge", { min, max }).sortable(), ); }, /** * A progress column with bar visualization. * * Defaults: number + bar display (0–100) + sortable. * * @param range - Override the min/max range (default: `{ min: 0, max: 100 }`) * * @example * ```ts * col.presets.progress().label("Progress") * col.presets.progress({ min: 0, max: 1000 }).label("Completion") * ``` */ progress(range?: { min: number; max: number; }): ColBuilder { const { min = 0, max = 100 } = range ?? {}; return tag( "progress", [range], col.number().label("Progress").display("bar", { min, max }).sortable(), ); }, }; 52:Tc0b,import { resolveColumns } from "./col"; import type { TableSchemaDefinition } from "./types"; /** * Validates a table schema definition and throws a descriptive error on the * first violation found. * * Called automatically by `createTableSchema()` — no need to call manually. * * Catches errors that the TypeScript type system cannot prevent: * - Missing label (`.label()` was never called) * - Slider `min` greater than `max` * * These checks run for both the TypeScript-authored path (`createTableSchema({...})`) * and the AI-generated path (`createTableSchema.fromJSON(json)`). */ export function validateSchema(definition: TableSchemaDefinition): void { for (const c of resolveColumns(definition)) { const { key } = c; // 1. Label is required — col.* factories default to label: "" if (!c.label) { throw new Error( `[createTableSchema] Column "${key}" is missing a label.\n` + ` Fix: .label("${key[0]!.toUpperCase()}${key.slice(1)}")`, ); } // 2. Number checkbox filter requires explicit options — the number factory // has no value list to auto-derive from, so an empty options list would // render a filter with no checkboxes (a silent no-op in the UI). if ( c.kind === "number" && c.filter?.type === "checkbox" && (!c.filter.options || c.filter.options.length === 0) ) { throw new Error( `[createTableSchema] Column "${key}": checkbox filter on a number column requires explicit options.\n` + ` Fix: .filterable("checkbox", { options: [{ label: "200", value: 200 }, ...] })`, ); } // 3. Slider bounds must be valid — type system requires { min, max } to be // passed but cannot enforce min < max if (c.filter?.type === "slider") { const { min, max } = c.filter; if (min === undefined || max === undefined) { throw new Error( `[createTableSchema] Column "${key}": slider filter is missing min/max bounds.\n` + ` Fix: .filterable("slider", { min: 0, max: 100 })`, ); } if (min > max) { throw new Error( `[createTableSchema] Column "${key}": slider min (${min}) must be less than max (${max}).\n` + ` Fix: swap the values — .filterable("slider", { min: ${max}, max: ${min} })`, ); } } // 4. A sheet-only column cannot carry a filter. `.sheetOnly()` is the only // chain step that sets `enableHiding: false` on a hideable column, and // it clears the filter, so no builder can produce this combination — // only hand-written or AI-generated JSON can. It has no chain form, // which means `schemaToTypeScript` would have to drop one half of it. if (c.enableHiding === false && c.hidden && c.filter !== null) { throw new Error( `[createTableSchema] Column "${key}": a sheet-only column cannot have a filter.\n` + ` Fix: drop the filter (.sheetOnly() implies it), or make the column filterable and hidden instead.`, ); } } } 53:T2026,import { createColBuilder, defaultDisplayForKind } from "./col"; import type { ColKind, ColumnDescriptor, DisplayDescriptor, FilterDescriptor, Provenance, SchemaJSON, SchemaJSONVersion, SheetDescriptor, TableSchemaDefinition, } from "./types"; /** The current `SchemaJSON` version. Bump alongside a `migrateSchemaJSON` step. */ export const SCHEMA_JSON_VERSION: SchemaJSONVersion = 1; // ── Serialization ─────────────────────────────────────────────────────────── // // The descriptor IS the serializable state, so serialization is a rename of the // key and nothing else. There is no projection to keep in sync, which is why // `unit`, `presets`, and `resizable` can no longer be silently dropped. export function serializeSchema(definition: TableSchemaDefinition): SchemaJSON { return { version: SCHEMA_JSON_VERSION, columns: Object.entries(definition).map(([key, builder]) => ({ key, ...builder._descriptor, })), }; } // ── Deserialization ───────────────────────────────────────────────────────── // // Descriptors are stored verbatim, so reconstruction hands the descriptor // straight back to the builder. The old ~40-branch replay of the fluent chain // — including the `enableHiding === false && hidden ⇒ .sheetOnly()` inference // archaeology — is gone. // // Limitation, unchanged: renderers (display cell, filter component, sheet // component/condition) are closures and cannot be serialized. A deserialized // column falls back to its descriptor's display, which is why the descriptor // keeps a real display type even when a custom renderer was supplied. export function deserializeSchema(json: SchemaJSON): TableSchemaDefinition { const definition: TableSchemaDefinition = {}; for (const { key, ...descriptor } of json.columns) { definition[key] = createColBuilder(descriptor as ColumnDescriptor, {}); } return definition; } // ── Migration ─────────────────────────────────────────────────────────────── const COL_KINDS: readonly ColKind[] = [ "string", "number", "boolean", "timestamp", "enum", "array", "record", "select", ]; function isRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } function asKind(value: unknown, key: unknown): ColKind { if (COL_KINDS.includes(value as ColKind)) return value as ColKind; // Falling back is better than throwing — one bad column should not make a // whole saved schema unloadable — but it is a real loss, so say so. if (value !== undefined) { console.warn( `[migrateSchemaJSON] Column ${JSON.stringify(key)} has unknown kind ` + `${JSON.stringify(value)}. Falling back to "string".`, ); } return "string"; } /** * Normalize an array column's item descriptor. * * v1 nests a full `ColumnDescriptor`; v0 carried only `{ dataType, enumValues }` * under `arrayItemType` — and, for non-enum items, nothing at all, which is * exactly how `string[]` columns used to collapse into `string` columns. */ function normalizeArrayItem(raw: unknown): ColumnDescriptor { const { key: _key, ...item } = normalizeColumn(raw); return item as ColumnDescriptor; } function isProvenance(value: unknown): value is Provenance { if (!isRecord(value)) return false; return ( value.source === "manual" || (value.source === "preset" && typeof value.preset === "string" && Array.isArray(value.args)) || (value.source === "inferred" && typeof value.rule === "string") ); } /** * Normalize one column from either version into a complete `ColumnDescriptor`. * * v1 payloads go through this too rather than being trusted: `fromJSON` accepts * user-typed text, so "it says version 1" is not evidence that its columns are * well-formed. Every required field is filled or defaulted here, which is what * makes the unchecked `as SchemaJSON` cast on untrusted input unnecessary. */ function normalizeColumn(raw: unknown): ColumnDescriptor & { key: string } { const c = isRecord(raw) ? raw : {}; // v1 writes `kind`; v0 wrote `dataType`. const kind = asKind(c.kind ?? c.dataType, c.key); // v0 wrote `{ type: "text" }` for custom displays and omitted `unit`, // `presets`, and `resizable` entirely. Nothing can recover those — the // migration fills the type-required defaults and stops there. const display = isRecord(c.display) ? (c.display as DisplayDescriptor) : defaultDisplayForKind(kind); // Carried through wholesale, like `display` and `sheet`. Whitelisting the // optional fields here would reintroduce exactly the hand-maintained // projection this split removed from `serializeSchema` — a new // `FilterDescriptor` field would be dropped on migration and nothing would // say so. Only the three required fields are coerced, because they must exist. const filter: FilterDescriptor | null = isRecord(c.filter) ? { ...(c.filter as Partial), type: (c.filter.type ?? "input") as FilterDescriptor["type"], defaultOpen: c.filter.defaultOpen === true, commandDisabled: c.filter.commandDisabled === true, } : null; const sheet: SheetDescriptor | null = isRecord(c.sheet) ? (c.sheet as SheetDescriptor) : null; const common = { label: typeof c.label === "string" ? c.label : "", ...(typeof c.description === "string" ? { description: c.description } : {}), optional: c.optional === true, display, ...(typeof c.size === "number" ? { size: c.size } : {}), ...(typeof c.minSize === "number" ? { minSize: c.minSize } : {}), hidden: c.hidden === true, enableHiding: c.enableHiding !== false, hideHeader: c.hideHeader === true, // v0 had no `resizable` at all, so it defaults to false there; v1 writes it. resizable: c.resizable === true, sortable: c.sortable === true, filter, sheet, provenance: (isProvenance(c.provenance) ? c.provenance : { source: "manual" }) as Provenance, }; const key = typeof c.key === "string" ? c.key : ""; if (kind === "enum") { return { key, ...common, kind: "enum", enumValues: Array.isArray(c.enumValues) ? (c.enumValues as string[]) : [], }; } if (kind === "array") { return { key, ...common, kind: "array", // v1 nests a full descriptor under `arrayItem`; v0 carried only // `{ dataType, enumValues }` under `arrayItemType`. arrayItem: normalizeArrayItem(c.arrayItem ?? c.arrayItemType), }; } return { key, ...common, kind } as ColumnDescriptor & { key: string }; } /** * Bring untrusted schema JSON up to the current version. * * `SchemaJSON` is persisted (the builder cache) and pasted by hand into the * schema editor, so every entry point that accepts it must run through here * first. This is the one hand-written conversion the descriptor split * deliberately keeps. * * v0 (no `version` field) → v1: `dataType` → `kind`, `arrayItemType` → * recursive `arrayItem`, and the newly-required `resizable`, `enableHiding`, * `hideHeader`, and `provenance` get their defaults. * * @throws if `json` is not an object with a `columns` array. */ export function migrateSchemaJSON(json: unknown): SchemaJSON { if (!isRecord(json) || !Array.isArray(json.columns)) { throw new Error( "[migrateSchemaJSON] Expected an object with a `columns` array.", ); } if (json.version !== undefined && json.version !== SCHEMA_JSON_VERSION) { throw new Error( `[migrateSchemaJSON] Unknown schema version ${JSON.stringify(json.version)}. ` + `This build understands version ${SCHEMA_JSON_VERSION}.`, ); } return { version: SCHEMA_JSON_VERSION, columns: json.columns.map(normalizeColumn), }; } 54:T55ad,import type { ActionDescriptor } from "@/lib/actions/types"; import { sanitizeActionDescriptors } from "@/lib/actions/validate"; import type { ActionValidationOptions } from "@/lib/actions/validate"; import { migrateSchemaJSON } from "./serialize"; import type { SchemaJSON } from "./types"; /** * The table manifest — what an endpoint says about itself. * * This is the missing half of the headless story. The schema was already * serializable, but every consumer built it locally from TypeScript, so * "point the table at a URL" was never actually possible. A manifest is that * URL's answer: the schema, which column identifies a row, what the server can * and cannot compute, and what may be done to a row. * * It is fetched over the network from a server the app may not own, so * `parseTableManifest` treats every field as untrusted and bounded. */ /** Bump alongside a migration step in `parseTableManifest`. */ export const TABLE_MANIFEST_VERSION = 1; /** * What the endpoint can compute. * * The client used to assume all of it. An endpoint that cannot group facets or * count matching rows had no way to say so, and the UI had no way to degrade — * it simply rendered empty filters and a blank count. Each flag here is a thing * the table will stop asking for, or compute on the client instead. */ export type TableCapabilities = { /** `meta.facets` is populated. When false, facet counts come from loaded rows. */ facets: boolean; /** * The columns the server can facet, when it can only do some. Omitted means * "every filterable column". */ facetedColumns?: readonly string[]; /** `meta.totalRowCount` is meaningful. */ totalRowCount: boolean; /** `meta.filterRowCount` is meaningful. */ filterRowCount: boolean; /** `meta.chartData` is populated. When false, the chart slot is not rendered. */ chart: boolean; /** `prevCursor` is honoured — the precondition for live mode. */ backwardPagination: boolean; /** `meta.actions` and the per-row `_actions` stamp are populated. */ actions: boolean; }; /** * The conservative reading of an endpoint that said nothing. * * Everything optional is off: a table that renders no chart against a server * that has one is a missing feature, while a table that renders a chart against * a server that has none is a broken screen. */ export const DEFAULT_CAPABILITIES: TableCapabilities = { facets: false, totalRowCount: false, filterRowCount: false, chart: false, backwardPagination: false, actions: false, }; /** * How the timeline chart is drawn. * * `meta.chartData` is `{ timestamp, [series]: number }[]`, and until now which * column it bucketed, which series it carried, and what colour each series took * were all decided in app code. A table pointed at an endpoint has none of that, * so the endpoint states it. */ export type TableChartConfig = { /** The timestamp column the buckets are over. Must be a column in the schema. */ columnKey: string; /** The numeric series in each point, in stacking order. */ series: { key: string; label?: string; color?: string }[]; /** Bucket width in milliseconds, when the endpoint has a fixed one. */ intervalMs?: number; }; export type TableManifestDefaults = { sort?: { id: string; desc: boolean }; size?: number; columnVisibility?: Record; }; export type TableManifest = { version: number; schema: SchemaJSON; /** * The column that identifies a row on the wire. * * Actions key rows by it and the sheet resolves the open row through it. It * used to be a closure written by hand at each call site * (`getRowId={(row) => row.uuid}`), which is exactly the kind of thing a * pointed-at table cannot supply. */ primaryKey: string; /** * A human name for a row, as a template over column keys: * `"{method} {pathname}"`. Used for accessible labels, never for identity. */ rowLabel?: string; capabilities: TableCapabilities; /** Present when `capabilities.chart` is true. */ chart?: TableChartConfig; actions?: ActionDescriptor[]; defaults?: TableManifestDefaults; }; /** * Build a manifest from a table schema. * * The server side of the contract. `createTableSchema(...)` already produces * the `SchemaJSON`; this names the row identity and states what the endpoint * can actually compute, which are the two things the schema alone never said. */ export function createTableManifest(config: { schema: { toJSON(): SchemaJSON } | SchemaJSON; primaryKey: string; rowLabel?: string; capabilities?: Partial; chart?: TableChartConfig; actions?: ActionDescriptor[]; defaults?: TableManifestDefaults; }): TableManifest { const schema = "toJSON" in config.schema ? config.schema.toJSON() : config.schema; if (!schema.columns.some((column) => column.key === config.primaryKey)) { // Caught here rather than at the client, which would only be able to blank // the table and say the endpoint was wrong. throw new TableManifestError( `primaryKey ${JSON.stringify(config.primaryKey)} is not a column in the schema`, ); } return { version: TABLE_MANIFEST_VERSION, schema, primaryKey: config.primaryKey, ...(config.rowLabel ? { rowLabel: config.rowLabel } : {}), capabilities: { ...DEFAULT_CAPABILITIES, ...config.capabilities }, ...(config.chart ? { chart: config.chart } : {}), ...(config.actions?.length ? { actions: config.actions } : {}), ...(config.defaults ? { defaults: config.defaults } : {}), }; } // ── Bounds ────────────────────────────────────────────────────────────────── /** * Caps on an incoming manifest. * * A remote schema drives column generation, filter rendering and URL state, so * an unbounded one is a way to hang the tab. These are deliberately far above * any real table. */ export const MANIFEST_LIMITS = { maxColumns: 200, maxKeyLength: 200, maxLabelLength: 500, maxActions: 50, } as const; /** * Path segments that reach an object's prototype rather than its own data. * * Column keys are server-authored. `definition[key] = builder` with a * `"__proto__"` key does not add an own property — it reassigns the object's * prototype, so the column silently vanishes from every `Object.keys` consumer * with none of the warnings every other rejected input here produces. As a * `primaryKey` it is worse: `getRowId` returns `"[object Object]"` for every * row, collapsing selection and bulk actions onto a single id. */ const RESERVED_SEGMENTS: ReadonlySet = new Set([ "__proto__", "constructor", "prototype", ]); /** True when every segment of a dotted key addresses own data. */ export function isSafeColumnKey(key: string): boolean { return key.split(".").every((segment) => !RESERVED_SEGMENTS.has(segment)); } export class TableManifestError extends Error { constructor(message: string, options?: ErrorOptions) { super(message, options); this.name = "TableManifestError"; } } function isRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } function parseCapabilities(value: unknown): TableCapabilities { if (!isRecord(value)) return { ...DEFAULT_CAPABILITIES }; const facetedColumns = Array.isArray(value.facetedColumns) ? value.facetedColumns.filter( (key): key is string => typeof key === "string" && key.length <= MANIFEST_LIMITS.maxKeyLength, ) : undefined; return { facets: value.facets === true, ...(facetedColumns ? { facetedColumns } : {}), totalRowCount: value.totalRowCount === true, filterRowCount: value.filterRowCount === true, chart: value.chart === true, backwardPagination: value.backwardPagination === true, actions: value.actions === true, }; } function parseDefaults( value: unknown, keys: ReadonlySet, ): TableManifestDefaults | undefined { if (!isRecord(value)) return undefined; const defaults: TableManifestDefaults = {}; if (isRecord(value.sort) && typeof value.sort.id === "string") { // A default sort on a column that does not exist would be written straight // into the URL and then fail to resolve against the table. if (keys.has(value.sort.id)) { defaults.sort = { id: value.sort.id, desc: value.sort.desc === true }; } } if ( typeof value.size === "number" && Number.isInteger(value.size) && value.size > 0 ) { defaults.size = value.size; } if (isRecord(value.columnVisibility)) { const visibility: Record = {}; for (const [key, visible] of Object.entries(value.columnVisibility)) { if (keys.has(key) && typeof visible === "boolean") { visibility[key] = visible; } } if (Object.keys(visibility).length > 0) { defaults.columnVisibility = visibility; } } return Object.keys(defaults).length > 0 ? defaults : undefined; } function parseChart( value: unknown, keys: ReadonlySet, warn: (message: string) => void, ): TableChartConfig | undefined { if (!isRecord(value)) return undefined; if (typeof value.columnKey !== "string" || !keys.has(value.columnKey)) { // Without a column to bucket over there is nothing to draw, and a chart // pinned to a column that no longer exists is worse than no chart. warn("Dropped the chart config: `columnKey` names no column in the schema"); return undefined; } const series = (Array.isArray(value.series) ? value.series : []) .filter( (item): item is Record => isRecord(item) && typeof item.key === "string" && item.key.length > 0 && item.key.length <= MANIFEST_LIMITS.maxKeyLength, ) .slice(0, MANIFEST_LIMITS.maxColumns) .map((item) => ({ key: item.key as string, ...(typeof item.label === "string" ? { label: item.label } : {}), ...(typeof item.color === "string" ? { color: item.color } : {}), })); if (series.length === 0) { warn("Dropped the chart config: it declares no series"); return undefined; } return { columnKey: value.columnKey, series, ...(typeof value.intervalMs === "number" && value.intervalMs > 0 ? { intervalMs: value.intervalMs } : {}), }; } export type ParseManifestOptions = { /** Passed to the action validator — see `sanitizeActionDescriptors`. */ actionValidation?: ActionValidationOptions; /** Called with anything dropped, so a host can log it. */ onWarning?: (message: string) => void; }; /** * Validate and normalize an untrusted manifest. * * Throws only for the failures that leave nothing renderable — a missing * schema, no columns, no usable primary key. Everything else is repaired or * dropped with a warning, because one bad column should not blank the table. */ export function parseTableManifest( value: unknown, options?: ParseManifestOptions, ): TableManifest { const warn = options?.onWarning ?? (() => {}); if (!isRecord(value)) { throw new TableManifestError("Manifest is not an object"); } // `migrateSchemaJSON` already normalizes every descriptor field and brings // older versions forward, so this only has to add the bounds it does not. Its // own rejection is re-thrown as a `TableManifestError` so that a caller has // one error type to catch for "this endpoint did not answer with a manifest". let schema: SchemaJSON; try { schema = migrateSchemaJSON(value.schema); } catch (cause) { throw new TableManifestError( `Manifest schema is not usable: ${cause instanceof Error ? cause.message : String(cause)}`, { cause }, ); } if (schema.columns.length === 0) { throw new TableManifestError("Manifest schema has no columns"); } if (schema.columns.length > MANIFEST_LIMITS.maxColumns) { throw new TableManifestError( `Manifest schema has ${schema.columns.length} columns, over the limit of ${MANIFEST_LIMITS.maxColumns}`, ); } const seenKeys = new Set(); const columns = schema.columns.filter((column) => { if (column.key.length === 0) { warn("Dropped a column with an empty key"); return false; } if (column.key.length > MANIFEST_LIMITS.maxKeyLength) { warn(`Dropped column ${JSON.stringify(column.key)}: key too long`); return false; } if (!isSafeColumnKey(column.key)) { warn(`Dropped column ${JSON.stringify(column.key)}: reserved key`); return false; } // An empty label is not merely ugly: `createTableSchema.fromJSON` rejects // it, which throws inside the component and blanks the whole table. if (column.label.length === 0) { warn(`Dropped column ${JSON.stringify(column.key)}: empty label`); return false; } if (column.label.length > MANIFEST_LIMITS.maxLabelLength) { warn(`Dropped column ${JSON.stringify(column.key)}: label too long`); return false; } // The definition is keyed by column key, so a duplicate would silently // overwrite the first with no diagnostic. if (seenKeys.has(column.key)) { warn(`Dropped column ${JSON.stringify(column.key)}: duplicate key`); return false; } seenKeys.add(column.key); return true; }); if (columns.length === 0) { throw new TableManifestError("Manifest schema has no usable columns"); } const keys = new Set(columns.map((column) => column.key)); const primaryKey = typeof value.primaryKey === "string" && keys.has(value.primaryKey) ? value.primaryKey : null; if (!primaryKey) { throw new TableManifestError( "Manifest primaryKey is missing or names a column that does not exist", ); } const capabilities = parseCapabilities(value.capabilities); const { actions, rejected } = sanitizeActionDescriptors( Array.isArray(value.actions) ? value.actions.slice(0, MANIFEST_LIMITS.maxActions) : undefined, options?.actionValidation, ); for (const rejection of rejected) { warn(`Dropped action ${rejection.id}: ${rejection.reason}`); } return { version: TABLE_MANIFEST_VERSION, schema: { version: schema.version, columns }, primaryKey, ...(typeof value.rowLabel === "string" && value.rowLabel.length <= MANIFEST_LIMITS.maxLabelLength ? { rowLabel: value.rowLabel } : {}), capabilities, ...(() => { const chart = parseChart(value.chart, keys, warn); return chart ? { chart } : {}; })(), ...(actions.length > 0 ? { actions } : {}), ...(() => { const defaults = parseDefaults(value.defaults, keys); return defaults ? { defaults } : {}; })(), }; } // ── ETag ──────────────────────────────────────────────────────────────────── /** * FNV-1a over the serialized manifest. * * A schema changes on deploy, not per request, so the point of the ETag is to * turn the client's revalidation into a 304 rather than a re-download. A * non-cryptographic hash is the right tool: this guards cache freshness, not * integrity. */ export function manifestETag(manifest: TableManifest): string { const json = JSON.stringify(manifest); let hash = 0x811c9dc5; for (let i = 0; i < json.length; i++) { hash ^= json.charCodeAt(i); hash = Math.imul(hash, 0x01000193) >>> 0; } return `"${hash.toString(16)}-${json.length.toString(16)}"`; } // ── Server ────────────────────────────────────────────────────────────────── export type ManifestHandlerOptions = { /** * `Cache-Control` for the response. The default revalidates every time and * relies on the ETag for the cheap path, which is the safe default for * something that changes on deploy without a version in its URL. */ cacheControl?: string; /** Extra response headers — CORS, most likely. */ headers?: Record; }; /** * A `Request → Response` handler serving the manifest, with ETag revalidation. * * Pass a function rather than a value when the manifest depends on the request * — per-tenant columns, or actions that depend on the caller's permissions. */ export function createTableManifestHandler( manifest: TableManifest | ((request: Request) => TableManifest), options?: ManifestHandlerOptions, ) { return async function handler(request: Request): Promise { const resolved = typeof manifest === "function" ? manifest(request) : manifest; const etag = manifestETag(resolved); const headers: Record = { "content-type": "application/json", etag, "cache-control": options?.cacheControl ?? "no-cache", ...options?.headers, }; // `If-None-Match` may carry a list, and a proxy may have weakened the tag. const ifNoneMatch = request.headers.get("if-none-match"); if (ifNoneMatch) { const candidates = ifNoneMatch .split(",") .map((value) => value.trim().replace(/^W\//, "")); if (candidates.includes(etag) || candidates.includes("*")) { return new Response(null, { status: 304, headers }); } } return new Response(JSON.stringify(resolved), { status: 200, headers }); }; } // ── Client ────────────────────────────────────────────────────────────────── export type FetchManifestOptions = ParseManifestOptions & { headers?: HeadersInit | (() => HeadersInit | Promise); credentials?: RequestCredentials; fetch?: typeof fetch; signal?: AbortSignal; }; /** * Fetch and validate a manifest. * * Deliberately not wired to React Query here — the manifest is needed *before* * the query layer exists, because the URL-state adapter is built from it. */ export async function fetchTableManifest( url: string, options?: FetchManifestOptions, ): Promise { const doFetch = options?.fetch ?? fetch; const headers = typeof options?.headers === "function" ? await options.headers() : options?.headers; const response = await doFetch(url, { headers, credentials: options?.credentials, signal: options?.signal, }); if (!response.ok) { throw new TableManifestError( `Could not load the table manifest from ${url}: ${response.status} ${response.statusText}`.trim(), ); } let payload: unknown; try { payload = await response.json(); } catch (cause) { throw new TableManifestError( `The table manifest at ${url} is not valid JSON`, { cause }, ); } return parseTableManifest(payload, options); } // ── Row accessors ─────────────────────────────────────────────────────────── /** Reads a possibly-dotted key path off a row. */ function readPath(row: unknown, path: string): unknown { if (row === null || typeof row !== "object") return undefined; if (!isSafeColumnKey(path)) return undefined; const record = row as Record; // Rows may carry the dotted key literally — `createDrizzleHandler` projects // `"timing.dns"` as a flat property — so the exact key wins before walking. if (Object.hasOwn(record, path)) return record[path]; if (!path.includes(".")) return undefined; let current: unknown = row; for (const segment of path.split(".")) { if (current === null || typeof current !== "object") return undefined; // Own data only. `isSafeColumnKey` is a name list and cannot catch // `"meta.toString"`, which otherwise resolves an inherited method — the // same value on every row, collapsing every row id onto one. if (!Object.hasOwn(current, segment)) return undefined; current = (current as Record)[segment]; } return current; } export type RowAccessors = { /** The row's wire identity, from `manifest.primaryKey`. */ getRowId: (row: TRow) => string; /** * A human name for the row, from `manifest.rowLabel`. `undefined` when the * manifest declared none — callers then fall back to static copy rather than * reading an internal id out loud. */ getRowLabel?: (row: TRow) => string; }; /** * Derive `getRowId` / `getRowLabel` from a manifest. * * These were hand-written closures at every call site * (`getRowId={(row) => row.uuid}`), which a table pointed at an endpoint cannot * supply. `rowLabel` is a template over column keys — `"{method} {pathname}"` — * with unknown keys left as written, so a typo is visible rather than silent. */ export function createRowAccessors( manifest: Pick, ): RowAccessors { const getRowId = (row: TRow): string => { const value = readPath(row, manifest.primaryKey); // Coerced rather than asserted: the id addresses a row in the DOM and on // the wire, and a numeric primary key is perfectly ordinary. return value === null || value === undefined ? "" : String(value); }; const template = manifest.rowLabel; if (!template) return { getRowId }; return { getRowId, getRowLabel: (row: TRow): string => template.replace(/\{([^{}]+)\}/g, (match, key: string) => { const value = readPath(row, key.trim()); return value === null || value === undefined ? match : String(value); }), }; } 55:T157b,import { createColBuilder } from "./col"; import { isSafeColumnKey } from "./manifest"; import type { ColRenderers, ColumnDescriptor, TableSchemaDefinition, } from "./types"; /** * Attaching renderers to a schema that came over the wire. * * `serialize.ts` is explicit that the four renderers — the display cell, the * filter component, the sheet component and its condition — are closures and * cannot be serialized. A deserialized column therefore falls back to whatever * named display its descriptor carries, which is why the descriptor keeps a * real display type even when a custom renderer was originally supplied. * * The named displays (`badge`, `bar`, `status-code`, `level-indicator`, …) * already cover most of what a table needs, and they travel as data. This * module is the escape hatch for the rest: an app pointed at a remote schema * supplies the handful of columns it wants to draw itself, by key, and keeps * every other column's declarative rendering. * * @example * ```ts * const { definition } = createTableSchema.fromJSON(manifest.schema); * const withRenderers = applyRenderers(definition, { * pathname: { cell: (value) => }, * timing: { sheetComponent: (row) => }, * }); * ``` */ /** Renderer closures to attach, keyed by column key. */ export type RendererOverrides = Record; export type ApplyRenderersOptions = { /** * Called for an override whose key is not in the schema. * * Worth listening to: a remote schema can drop a column between deploys, and * an override left behind for it is silently dead. The default warns to the * console rather than throwing, because one stale override should not blank * a table. */ onUnknownKey?: (key: string) => void; /** * Called for a schema column whose key cannot be used. * * A separate channel from {@link onUnknownKey} because the two say opposite * things: one means "your override names nothing", the other means "the * schema's own column is unusable". Reporting a dropped column through the * override warning sends the reader looking for a stale override that does * not exist. */ onUnusableColumn?: (key: string) => void; }; function defaultOnUnknownKey(key: string): void { console.warn( `[applyRenderers] no column ${JSON.stringify(key)} in the schema — ` + `the override will not be used. Did the endpoint's schema change?`, ); } function defaultOnUnusableColumn(key: string): void { console.warn( `[applyRenderers] dropped schema column ${JSON.stringify(key)}: the key ` + `reaches an object prototype, so it cannot address a column.`, ); } /** * Return a copy of `definition` with the given renderers attached. * * Non-mutating: builders are immutable, so each overridden column is rebuilt * over the same descriptor with the merged renderers. Columns with no override * are passed through by reference. * * Only the renderer keys present in an override are set; passing * `{ cell }` leaves an existing `sheetComponent` alone. */ export function applyRenderers( definition: TableSchemaDefinition, overrides: RendererOverrides, options?: ApplyRenderersOptions, ): TableSchemaDefinition { const onUnknownKey = options?.onUnknownKey ?? defaultOnUnknownKey; const onUnusableColumn = options?.onUnusableColumn ?? defaultOnUnusableColumn; const keys = Object.keys(overrides); if (keys.length === 0) return definition; for (const key of keys) { // `in` walks the prototype chain, so `toString` would read as a column. if (!Object.hasOwn(definition, key)) onUnknownKey(key); } const result: TableSchemaDefinition = {}; for (const [key, builder] of Object.entries(definition)) { // Skipped before any assignment, not merely excluded from overrides: // `result["__proto__"] = builder` invokes the setter and reassigns the // result's prototype rather than adding a column, so the column vanishes // from every `Object.keys` consumer with no diagnostic. Guarding only the // override lookup still ran that assignment on the pass-through path. if (!isSafeColumnKey(key)) { onUnusableColumn(key); continue; } const override = Object.hasOwn(overrides, key) ? overrides[key] : undefined; if (!override) { result[key] = builder; continue; } result[key] = createColBuilder( builder._descriptor as ColumnDescriptor, // The descriptor is untouched: an override changes how a column draws, // never what it is. `toJSON()` on the result still round-trips. { ...builder._renderers, ...override }, ); } return result; } /** * The display types a schema can name without shipping code. * * Exported so a tool — a schema builder UI, an agent writing a schema, a * validator — can enumerate what is available declaratively before reaching * for {@link applyRenderers}. */ export const NAMED_DISPLAY_TYPES = [ "text", "code", "boolean", "star", "badge", "timestamp", "number", "bar", "heatmap", "gauge", "status-code", "level-indicator", ] as const; export type NamedDisplayType = (typeof NAMED_DISPLAY_TYPES)[number]; /** Is this display type one the renderer can draw from the descriptor alone? */ export function isNamedDisplayType(type: string): type is NamedDisplayType { return (NAMED_DISPLAY_TYPES as readonly string[]).includes(type); } 56:T119d,import { parseTableManifest, type TableManifest } from "./manifest"; /** * Freezing a manifest into the app at build time. * * Fetching the manifest at runtime is one round trip before the table can draw * anything. A snapshot removes it: check the endpoint's answer into the repo, * pass it as `initialManifest`, and the first paint has a schema while the * query revalidates behind it. * * The trade is explicit rather than hidden. A snapshot is a copy, so it goes * stale when the endpoint changes — which is exactly why `useTableManifest` * still revalidates instead of trusting it forever, and why the generated file * records where and when it came from. */ export type SnapshotOptions = { /** The URL it came from, recorded in the header comment. */ source?: string; /** Name of the exported const. Defaults to `manifest`. */ exportName?: string; /** * Import specifier for the `TableManifest` type. Defaults to the registry * path; set it to wherever the schema block landed in the consuming app * (`@/lib/table-schema`, most likely). */ typeImport?: string; /** * Timestamp for the header comment. Injectable so the output is * deterministic in tests, and so a build can stamp its own commit time. */ generatedAt?: Date | string; }; const DEFAULT_TYPE_IMPORT = "@/lib/table-schema"; /** A JS identifier, so the generated module actually parses. */ function assertIdentifier(name: string): void { if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) { throw new Error( `exportName ${JSON.stringify(name)} is not a valid identifier`, ); } } /** * Render a manifest as a TypeScript module. * * The manifest is re-parsed on the way in: a snapshot is generated from a live * endpoint's response, so it goes through the same validation as one consumed * at runtime. Freezing an invalid manifest into the repo would only move the * failure to a place where nobody is looking for it. */ export function manifestToModule( manifest: unknown, options?: SnapshotOptions, ): string { const exportName = options?.exportName ?? "manifest"; assertIdentifier(exportName); const parsed: TableManifest = parseTableManifest(manifest); const typeImport = options?.typeImport ?? DEFAULT_TYPE_IMPORT; const generatedAt = options?.generatedAt instanceof Date ? options.generatedAt.toISOString() : options?.generatedAt; const provenance = [ " * Generated by `manifestToModule`. Do not edit by hand.", options?.source ? ` * Source: ${options.source}` : null, generatedAt ? ` * Generated: ${generatedAt}` : null, " *", " * This is a snapshot. The table still revalidates it at runtime, so an", " * endpoint whose schema has moved on will correct itself — but regenerate", " * this file when that happens, or every first paint starts from stale", " * columns.", ].filter((line): line is string => line !== null); return [ "/**", ...provenance, " */", "", // Built with `JSON.stringify` rather than an interpolated string literal: // it escapes the specifier properly, and it keeps this line from reading as // a real import to any tool that scans this file's own imports. `import type { TableManifest } from ${JSON.stringify(typeImport)};`, "", `export const ${exportName}: TableManifest = ${JSON.stringify(parsed, null, 2)};`, "", ].join("\n"); } /** * Fetch a manifest and render it as a module, ready to write to disk. * * The whole `dtf pull` step, minus the file write — which is left to the * caller so this stays runtime-agnostic and needs no filesystem access. * * @example * ```ts * // scripts/pull-manifest.ts * import { writeFileSync } from "node:fs"; * import { pullManifestModule } from "@/lib/table-schema"; * * const url = "https://api.example.com/logs/schema"; * writeFileSync("src/app/logs/manifest.ts", await pullManifestModule(url)); * ``` */ export async function pullManifestModule( url: string, options?: SnapshotOptions & { headers?: HeadersInit; fetch?: typeof fetch; }, ): Promise { const doFetch = options?.fetch ?? fetch; const response = await doFetch(url, { headers: options?.headers }); if (!response.ok) { throw new Error( `Could not pull the manifest from ${url}: ${response.status} ${response.statusText}`.trim(), ); } return manifestToModule(await response.json(), { source: url, generatedAt: new Date(), ...options, }); } 57:T3be0,import { compact, defaultDisplayForKind } from "./col"; import { SCHEMA_JSON_VERSION } from "./serialize"; import type { ColKind, ColumnDescriptor, DisplayDescriptor, FilterDescriptor, SchemaJSON, } from "./types"; /** A descriptor plus the key it will be registered under. */ type InferredColumn = ColumnDescriptor & { key: string }; // Unix ms timestamps are 13-digit numbers (> Sep 2001, < Nov 2286) const UNIX_MS_MIN = 1_000_000_000_000; const UNIX_MS_MAX = 9_999_999_999_999; function isIso8601(value: string): boolean { return ( /^\d{4}-\d{2}-\d{2}(T[\d:.Z+\-]+)?$/.test(value) && !isNaN(Date.parse(value)) ); } function isUnixMs(value: number): boolean { return ( Number.isInteger(value) && value >= UNIX_MS_MIN && value <= UNIX_MS_MAX ); } /** Convert camelCase, snake_case, or kebab-case key to a human-readable label. */ function keyToLabel(key: string): string { let label = key.replace(/[-_]/g, " "); label = label.replace(/([a-z])([A-Z])/g, "$1 $2"); return label.replace(/\b\w/g, (c) => c.toUpperCase()); } /** * The fields every inferred column shares. `display` comes from the one * `defaultDisplayForKind` in `col.ts` — this module used to carry its own copy. */ function inferredCommon( label: string, kind: ColKind, filter: FilterDescriptor | null, rule: string, ) { return { label, optional: false, display: defaultDisplayForKind(kind) as DisplayDescriptor, hidden: false, enableHiding: true, hideHeader: false, resizable: false, sortable: false, filter, sheet: {} as { label?: string }, provenance: { source: "inferred" as const, rule }, }; } function makeDescriptor( key: string, label: string, kind: Exclude, filter: FilterDescriptor | null, rule: string, ): InferredColumn { return { key, ...inferredCommon(label, kind, filter, rule), kind }; } /** Split a key into lowercase words, handling camelCase, snake_case, and kebab-case. */ function keyToWords(key: string): string[] { return key .replace(/([a-z])([A-Z])/g, "$1_$2") .split(/[-_]/) .map((w) => w.toLowerCase()) .filter(Boolean); } const ID_WORDS = new Set(["id", "uuid", "hash", "token", "key"]); const CODE_WORDS = new Set([ "path", "url", "uri", "endpoint", "route", "host", "link", "href", "website", ]); const LATENCY_WORDS = new Set([ "latency", "duration", "elapsed", "delay", "wait", "ttfb", "rtt", "ping", ]); const SIZE_WORDS = new Set(["size", "bytes", "length"]); const LEVEL_WORDS = new Set(["level", "severity"]); const TRACE_ID_WORDS = new Set(["trace", "span", "request"]); const FAVORITE_WORDS = new Set(["favorite", "starred", "bookmarked", "pinned"]); const EMAIL_WORDS = new Set(["email", "mail"]); const STATUS_WORDS = new Set(["status", "state"]); const HEALTH_WORDS = new Set([ "health", "score", "rating", "accuracy", "uptime", ]); const PROGRESS_WORDS = new Set(["progress", "completion", "percentage"]); const HP_WORDS = new Set(["hp", "hitpoints"]); /** Semantic color mapping for status-like enum values. */ const STATUS_COLORS: Record = { active: "#22c55e", completed: "#22c55e", success: "#22c55e", published: "#22c55e", approved: "#22c55e", pending: "#f59e0b", draft: "#f59e0b", inactive: "#f59e0b", paused: "#f59e0b", error: "#ef4444", failed: "#ef4444", rejected: "#ef4444", cancelled: "#ef4444", archived: "#6b7280", deleted: "#6b7280", disabled: "#6b7280", }; /** Neutral palette for enum values without semantic meaning. */ const NEUTRAL_PALETTE = [ "#6366f1", "#8b5cf6", "#ec4899", "#14b8a6", "#f97316", "#06b6d4", "#84cc16", "#eab308", "#ef4444", "#64748b", ]; /** Generate a colorMap for enum values, using semantic colors where possible. */ function generateColorMap(values: readonly string[]): Record { const colorMap: Record = {}; let neutralIdx = 0; for (const value of values) { const lower = value.toLowerCase(); if (STATUS_COLORS[lower]) { colorMap[value] = STATUS_COLORS[lower]; } else { colorMap[value] = NEUTRAL_PALETTE[neutralIdx % NEUTRAL_PALETTE.length]!; neutralIdx++; } } return colorMap; } /** Post-process an inferred descriptor with smart display/config heuristics. */ function enhanceDescriptor(descriptor: InferredColumn): InferredColumn { const words = keyToWords(descriptor.key); const joined = words.join(""); const d = { ...descriptor }; const hasIdWord = words.some((w) => ID_WORDS.has(w)); const hasCodeWord = words.some((w) => CODE_WORDS.has(w)); const hasLatencyWord = words.some((w) => LATENCY_WORDS.has(w)) || joined.includes("responsetime"); const hasSizeWord = words.some((w) => SIZE_WORDS.has(w)); const hasLevelWord = words.some((w) => LEVEL_WORDS.has(w)); const isTraceId = hasIdWord && words.some((w) => TRACE_ID_WORDS.has(w)); const hasFavoriteWord = words.some((w) => FAVORITE_WORDS.has(w)); const hasEmailWord = words.some((w) => EMAIL_WORDS.has(w)); const hasStatusWord = words.some((w) => STATUS_WORDS.has(w)); const hasHealthWord = words.some((w) => HEALTH_WORDS.has(w)); const hasProgressWord = words.some((w) => PROGRESS_WORDS.has(w)); const hasHpWord = words.some((w) => HP_WORDS.has(w)); // ID-like columns → code display, not sortable if (hasIdWord) { d.display = { type: "code" }; d.sortable = false; // Trace/span/request IDs → hidden, not filterable (matches col.presets.traceId()) if (isTraceId) { d.hidden = true; d.filter = null; } } // Favorite/starred booleans → star display, hide column header else if (hasFavoriteWord && d.kind === "boolean") { d.display = { type: "star" }; d.hideHeader = true; } // Email columns → code display else if (hasEmailWord && d.kind === "string") { d.display = { type: "code" }; } // Path/URL-like columns → code display else if (hasCodeWord) { d.display = { type: "code" }; } // Latency-like number columns → heatmap with ms unit, sortable else if (hasLatencyWord && d.kind === "number") { // `compact` for the same reason the builder uses it: a zero-variance // sample gives the column an `input` filter with no bounds, and a display // carrying `min: undefined` is not the canonical form of one that omits it. d.display = compact({ type: "heatmap", unit: "ms", min: d.filter?.min, max: d.filter?.max, }) as DisplayDescriptor; d.sortable = true; } // Size-like number columns → number with B unit, sortable else if (hasSizeWord && d.kind === "number") { d.display = { type: "number", unit: "B" }; d.sortable = true; } // Health/score/rating → gauge display (min always 0 for visual baseline) else if (hasHealthWord && d.kind === "number") { d.display = compact({ type: "gauge", min: 0, max: d.filter?.max, }) as DisplayDescriptor; d.sortable = true; } // HP/hitpoints → bar display (min always 0 for visual baseline) else if (hasHpWord && d.kind === "number") { d.display = compact({ type: "bar", min: 0, max: d.filter?.max, }) as DisplayDescriptor; d.sortable = true; } // Progress/completion → bar display (min always 0 for visual baseline) else if (hasProgressWord && d.kind === "number") { d.display = compact({ type: "bar", min: 0, max: d.filter?.max, }) as DisplayDescriptor; d.sortable = true; } // Sortable defaults by type (unless ID-like) if (!hasIdWord) { if (d.kind === "timestamp" || d.kind === "number") { d.sortable = true; } } // Log level / severity enums: expand filter by default (matches col.presets.logLevel()) if (hasLevelWord && d.kind === "enum" && d.filter) { d.filter = { ...d.filter, defaultOpen: true }; } // Status/state enums → semantic colorMap on badge display if (hasStatusWord && d.kind === "enum") { d.display = { type: "badge", colorMap: generateColorMap(d.enumValues) }; } // Column sizing defaults const sizeDefaults: Record = { boolean: 100, timestamp: 220, number: 120, enum: 130, }; if (sizeDefaults[d.kind] !== undefined) { d.size = sizeDefaults[d.kind]; } return d; } /** Infer the item descriptor of an array column from its flattened items. */ function inferArrayItem(items: unknown[]): ColumnDescriptor { const common = (kind: ColKind, rule: string) => inferredCommon("", kind, null, rule); if (items.length === 0) { return { ...common("string", "array-item:empty"), kind: "string" }; } if (items.every((v) => typeof v === "string")) { const distinct = new Set(items as string[]); if (distinct.size <= 10) { return { ...common("enum", "array-item:enum"), kind: "enum", enumValues: Array.from(distinct), }; } return { ...common("string", "array-item:string"), kind: "string" }; } if (items.every((v) => typeof v === "number")) { return { ...common("number", "array-item:number"), kind: "number" }; } if (items.every((v) => typeof v === "boolean")) { return { ...common("boolean", "array-item:boolean"), kind: "boolean" }; } return { ...common("string", "array-item:mixed"), kind: "string" }; } function inferColDescriptor(key: string, values: unknown[]): InferredColumn { const label = keyToLabel(key); const nonNull = values.filter((v) => v !== null && v !== undefined); if (nonNull.length === 0) { return makeDescriptor( key, label, "string", { type: "input", defaultOpen: false, commandDisabled: false }, "empty-column", ); } // Timestamp: ISO 8601 strings if (nonNull.every((v) => typeof v === "string" && isIso8601(v as string))) { return makeDescriptor( key, label, "timestamp", { type: "timerange", defaultOpen: false, commandDisabled: true }, "iso8601-string", ); } // Timestamp: Unix ms numbers if (nonNull.every((v) => typeof v === "number" && isUnixMs(v as number))) { return makeDescriptor( key, label, "timestamp", { type: "timerange", defaultOpen: false, commandDisabled: true }, "unix-ms-number", ); } // Boolean — options match `col.boolean()` exactly. Inference used to omit // them and let `generateFilterFields` derive "Yes"/"No", while the factory // baked in "true"/"false": two construction paths producing different filter // options for the same column kind. The codegen round trip cannot hold while // they disagree, because no chain step can clear the factory's options. if (nonNull.every((v) => v === true || v === false)) { return makeDescriptor( key, label, "boolean", { type: "checkbox", defaultOpen: false, commandDisabled: false, options: [ { label: "true", value: true }, { label: "false", value: false }, ], }, "boolean", ); } // Number if (nonNull.every((v) => typeof v === "number")) { const nums = nonNull as number[]; const min = Math.min(...nums); const max = Math.max(...nums); const filter: FilterDescriptor = min !== max ? { type: "slider", defaultOpen: false, commandDisabled: false, min, max, } : { type: "input", defaultOpen: false, commandDisabled: false }; return makeDescriptor(key, label, "number", filter, "number"); } // Array — the item type is always described, so a `string[]` column with more // distinct values than the enum threshold stays a `string[]` column. if (nonNull.every((v) => Array.isArray(v))) { const allItems = (nonNull as unknown[][]) .flat() .filter((v) => v !== null && v !== undefined); const arrayItem = inferArrayItem(allItems); const filter: FilterDescriptor | null = arrayItem.kind === "enum" ? { type: "checkbox", defaultOpen: false, commandDisabled: false, options: arrayItem.enumValues.map((v) => ({ label: v, value: v })), } : null; return { key, ...inferredCommon(label, "array", filter, "array"), kind: "array", arrayItem, }; } // Record (plain object, non-array) if (nonNull.every((v) => typeof v === "object" && !Array.isArray(v))) { return makeDescriptor(key, label, "record", null, "record"); } // String: check if enum (≤ 10 distinct values) if (nonNull.every((v) => typeof v === "string")) { const distinct = new Set(nonNull as string[]); if (distinct.size <= 10) { const enumValues = Array.from(distinct); return { key, ...inferredCommon( label, "enum", { type: "checkbox", defaultOpen: false, commandDisabled: false, options: enumValues.map((v) => ({ label: v, value: v })), }, "string-enum", ), kind: "enum", enumValues, }; } return makeDescriptor( key, label, "string", { type: "input", defaultOpen: false, commandDisabled: false }, "string", ); } // Fallback: mixed or unrecognised types — warn and treat as string const types = [ ...new Set(nonNull.map((v) => (Array.isArray(v) ? "array" : typeof v))), ]; console.warn( `[inferSchemaFromJSON] Column "${key}" has mixed or ambiguous types (${types.join(", ")}). ` + `Falling back to string input filter.`, ); return makeDescriptor( key, label, "string", { type: "input", defaultOpen: false, commandDisabled: false }, "mixed-fallback", ); } /** * Infer a SchemaJSON from an array of plain data objects. * * Walks all rows, collects per-key values, and infers the best ColKind and * FilterType for each column using these heuristics: * - `timestamp`: ISO 8601 strings or Unix-ms numbers * - `boolean`: all values strictly true/false * - `number`: all non-null values are typeof "number" * - `enum`: strings with ≤ 10 distinct values across the sample * - `array`: values are arrays (item type inferred recursively) * - `record`: values are plain objects (non-array) * - `string`: fallback * * Number columns with min ≠ max get a "slider" filter; otherwise "input". */ export function inferSchemaFromJSON(data: unknown[]): SchemaJSON { if (!Array.isArray(data) || data.length === 0) { return { version: SCHEMA_JSON_VERSION, columns: [] }; } // Collect all keys and their values across rows (preserving insertion order) const keyValues = new Map(); for (const row of data) { if (typeof row !== "object" || row === null || Array.isArray(row)) continue; for (const [key, value] of Object.entries(row as Record)) { if (!keyValues.has(key)) keyValues.set(key, []); keyValues.get(key)!.push(value); } } const columns = Array.from(keyValues.entries()).map(([key, values]) => enhanceDescriptor(inferColDescriptor(key, values)), ); return { version: SCHEMA_JSON_VERSION, columns }; } 58:T263a,import { col } from "./col"; import { presets } from "./presets"; import type { ColBuilder, ColumnDescriptor, ColumnDescriptorCommon, DatePresetDescriptor, JsonValue, SchemaJSON, } from "./types"; /** * Emit the `col.*` / `col.presets.*` factory call a descriptor came from, and * produce the descriptor that call yields on its own. * * Provenance is recorded at construction, so this reads it instead of * pattern-matching the descriptor's shape back into a guess at the preset. */ function factoryFor(c: ColumnDescriptor): { source: string; baseline: ColumnDescriptor; } { if (c.provenance.source === "preset") { const factory = presets[c.provenance.preset as keyof typeof presets]; if (typeof factory === "function") { const args = c.provenance.args; // Re-running the preset with its recorded arguments gives the exact // baseline the author started from, so the chain below emits only what // they actually changed. const builder = ( factory as (...a: unknown[]) => ColBuilder )(...args.map((a) => (a === null ? undefined : a))); return { source: `col.presets.${c.provenance.preset}(${args.map(emitValue).join(", ")})`, baseline: builder._descriptor, }; } // Unknown preset name (schema written by a newer build) — fall through to // the primitive factory rather than emitting a call that will not compile. } if (c.kind === "enum") { return { source: `col.enum([${c.enumValues.map(emitValue).join(", ")}])`, baseline: col.enum(c.enumValues)._descriptor, }; } if (c.kind === "array") { const item = factoryFor(c.arrayItem); const itemChain = chainFor(c.arrayItem, item.baseline); // `col.array()` requires an item builder — emitting a bare `col.array()` // is what used to produce code that did not compile. const itemSource = item.source + itemChain.join(""); return { source: `col.array(${itemSource})`, baseline: col.array(rebuild(c.arrayItem))._descriptor, }; } const factory = col[c.kind] as () => ColBuilder; return { source: `col.${c.kind}()`, baseline: factory()._descriptor }; } /** Rebuild a builder from a descriptor — used to seed `col.array`'s baseline. */ function rebuild(c: ColumnDescriptor): ColBuilder { if (c.kind === "enum") return col.enum(c.enumValues); if (c.kind === "array") return col.array(rebuild(c.arrayItem)); return (col[c.kind] as () => ColBuilder)(); } function emitValue(value: JsonValue | readonly string[] | undefined): string { if (value === undefined || value === null) return "undefined"; // Arrays are spaced by hand so preset args (`logLevel(["a", "b"])`) match the // per-value assembly used elsewhere (`col.enum(["a", "b"])`) — bare // `JSON.stringify` would emit one of them without spaces. if (Array.isArray(value)) { return `[${value.map((v) => emitValue(v as JsonValue)).join(", ")}]`; } return JSON.stringify(value); } /** * Emit a timerange preset. * * The descriptor stores `from`/`to` as ISO strings so they survive JSON, but * `.filterable("timerange", { presets })` takes `DatePreset`s holding real * `Date`s — printing the descriptor verbatim produced code that threw * `preset.from.toISOString is not a function` on the first run. */ function emitDatePreset(preset: DatePresetDescriptor): string { return ( `{ label: ${JSON.stringify(preset.label)}, ` + `shortcut: ${JSON.stringify(preset.shortcut)}, ` + `from: new Date(${JSON.stringify(preset.from)}), ` + `to: new Date(${JSON.stringify(preset.to)}) }` ); } /** Emit an object literal with unquoted keys, matching the docs' house style. */ function emitObject(entries: Record): string { const parts = Object.entries(entries) .filter(([, v]) => v !== undefined) .map(([k, v]) => `${k}: ${JSON.stringify(v)}`); return `{ ${parts.join(", ")} }`; } function sameJSON(a: unknown, b: unknown): boolean { return JSON.stringify(a ?? null) === JSON.stringify(b ?? null); } /** * One emitter per serializable descriptor field. * * The `-?` plus full key coverage means adding a field to * `ColumnDescriptorCommon` without adding an emitter here is a **compile * error**, not a silently dropped chain step. */ type Emitter = ( value: ColumnDescriptorCommon[K], baseline: ColumnDescriptor, descriptor: ColumnDescriptor, ) => string[]; type EmitterMap = { [K in keyof ColumnDescriptorCommon]-?: Emitter }; const EMITTERS: EmitterMap = { label: (value) => [`.label(${JSON.stringify(value)})`], description: (value) => value === undefined ? [] : [`.description(${JSON.stringify(value)})`], display: (value) => { const { type, ...options } = value as { type: string } & Record< string, unknown >; const hasOptions = Object.values(options).some((v) => v !== undefined); return [ hasOptions ? `.display(${JSON.stringify(type)}, ${emitObject(options)})` : `.display(${JSON.stringify(type)})`, ]; }, filter: (value) => { if (value === null) return [".notFilterable()"]; const parts: string[] = []; const { type, defaultOpen, commandDisabled, options, presets, ...rest } = value; if (type === "checkbox") { parts.push( options ? `.filterable("checkbox", { options: [${options .map((o) => emitObject({ label: o.label, value: o.value })) .join(", ")}] })` : `.filterable("checkbox")`, ); } else if (type === "slider") { parts.push(`.filterable("slider", ${emitObject(rest)})`); } else if (type === "timerange") { parts.push( presets ? `.filterable("timerange", { presets: [${presets .map(emitDatePreset) .join(", ")}] })` : `.filterable("timerange")`, ); } else { parts.push(`.filterable("input")`); } if (defaultOpen) parts.push(".defaultOpen()"); if (commandDisabled) parts.push(".commandDisabled()"); return parts; }, sheet: (value) => { if (value === null) return []; const args = emitObject(value as Record); return [args === "{ }" ? ".sheet()" : `.sheet(${args})`]; }, size: (value) => (value === undefined ? [] : [`.size(${value})`]), minSize: (value) => (value === undefined ? [] : [`.minSize(${value})`]), hidden: (value) => (value ? [".hidden()"] : []), hideHeader: (value) => (value ? [".hideHeader()"] : []), resizable: (value) => (value ? [".resizable()"] : []), sortable: (value) => (value ? [".sortable()"] : []), optional: (value) => (value ? [".optional()"] : []), // `enableHiding: false` together with `hidden` is exactly `.sheetOnly()`; // on its own it is only reachable via `col.select()`, whose baseline already // has it, so nothing needs emitting. enableHiding: (value, _baseline, descriptor) => value === false && descriptor.hidden ? [".sheetOnly()"] : [], // Not a chain step — provenance is how the factory call was chosen. provenance: () => [], }; /** * The order chain steps are emitted in. Listed explicitly because `.sheetOnly()` * clears the filter and must come after `.filterable()` would have set it. */ export const EMIT_ORDER: (keyof ColumnDescriptorCommon)[] = [ "label", "description", "display", "filter", "enableHiding", "sortable", "hidden", "hideHeader", "resizable", "optional", "size", "minSize", "sheet", ]; /** Emit only the steps where the descriptor differs from the factory baseline. */ function chainFor(c: ColumnDescriptor, baseline: ColumnDescriptor): string[] { const parts: string[] = []; for (const key of EMIT_ORDER) { const value = c[key]; if (sameJSON(value, baseline[key])) continue; // `.sheetOnly()` already implies `.hidden()` and `.notFilterable()`. // // The `filter === null` check is the whole reason this branch is safe: // without it, any descriptor shaped like a sheet-only column had its // filter dropped from the emitted source, silently. `validateSchema` // rejects that combination, so it can only arrive here through a raw // `SchemaJSON` that never went through a schema — and then the filter is // emitted rather than swallowed. if ( c.enableHiding === false && c.hidden && c.filter === null && baseline.enableHiding !== false && (key === "hidden" || key === "filter") ) { continue; } const emit = EMITTERS[key] as Emitter; parts.push(...emit(value as never, baseline, c)); } return parts; } /** * Convert a `SchemaJSON` descriptor to a `createTableSchema(...)` TypeScript * source code string. * * The output is ready to copy-paste into a project that imports from * `@/lib/table-schema`. Custom cell renderers are not serialized, so the * emitted chain uses the descriptor's fallback display for those columns. * * @example * ```ts * const ts = schemaToTypeScript(tableSchema.toJSON()); * // → 'import { createTableSchema, col } from "@/lib/table-schema"; ...' * ``` */ export function schemaToTypeScript(json: SchemaJSON): string { const lines: string[] = [ 'import { createTableSchema, col } from "@/lib/table-schema";', "", "export const schema = createTableSchema({", ]; for (const { key, ...descriptor } of json.columns) { const c = descriptor as ColumnDescriptor; const { source, baseline } = factoryFor(c); const chain = [source, ...chainFor(c, baseline)].join("\n "); lines.push(` ${key}: ${chain},`); } lines.push("});"); return lines.join("\n"); } 59:Ted4,import type { ColBuilder, ColKind, FilterType, TableSchemaDefinition, } from "../table-schema/types"; export type { ColKind, FilterType }; /** The member type of a checkbox filter: the item type for an array column. */ type FilterItem = NonNullable extends readonly (infer U)[] ? U : NonNullable; /** * The value one column's filter accepts, from its `ColBuilder`. * * Mirrors `normalize`: dispatch is on the declared filter type, and the * member type comes from the column's data type — so a checkbox on * `col.enum(LEVELS)` only accepts members of `LEVELS`. Distributes over `F`, * so a column whose filter type was never narrowed (`col.number()` allows * three) accepts any of them. * * A checkbox on a non-scalar member type is `never`: `col.array()` takes any * item builder, so `col.array(col.record())` type-checks, but `normalize` has * nothing to compare a record against. Advertising the member type there * would promise a filter the engine cannot plan. */ export type FilterValueFor = F extends "input" ? NonNullable extends number ? number : string : F extends "checkbox" ? [FilterItem] extends [Scalar] ? FilterItem | readonly FilterItem[] : never : F extends "slider" ? number | readonly [number, number] : F extends "timerange" ? Date | readonly [Date, Date] : never; /** * The filter values a table schema accepts, keyed by filterable column. * * Columns that are `.notFilterable()` (or `col.record()` / `col.select()`, * which never are) are absent, so a key typo or a guard on an unfilterable * column is a compile error — the same rule `defineActions` enforces at * runtime for a `when` clause. */ export type FilterValues = { [K in keyof TSchema as TSchema[K] extends ColBuilder ? [F] extends [never] ? never : K : never]: TSchema[K] extends ColBuilder ? FilterValueFor : never; }; /** A value a filter can compare against. */ export type Scalar = string | number | boolean; /** * A column's declared filter semantics, flattened to plain data. * * This is the whole input to the normalization table. Backends never see * anything else about a column, which is what stops them re-deriving semantics * from the runtime shape of a value. */ export type FilterSpec = { /** Dot-notation — the ONE identity space, matching the table schema key. */ key: string; type: FilterType; kind: ColKind; /** Present when `kind === "array"`. */ itemKind?: ColKind; options?: readonly Scalar[]; min?: number; max?: number; }; /** * The canonical, backend-neutral operation set. * * CLOSED union — exactly six members. Every backend implements all six with an * exhaustive switch and no default branch, so adding a seventh is a compile * error at every backend rather than a silent fallthrough. That is the point of * the design, not a defect: a new op is a breaking change to every engine. */ export type FilterOp = /** Case-insensitive substring match. */ | { op: "substring"; key: string; value: string } | { op: "equals"; key: string; value: Scalar } /** Scalar column, value ∈ set. */ | { op: "oneOf"; key: string; values: Scalar[] } /** Array column, column ∩ set ≠ ∅. */ | { op: "overlaps"; key: string; values: Scalar[] } /** Inclusive on both ends. */ | { op: "numberRange"; key: string; min: number; max: number } /** Inclusive on both ends. */ | { op: "dateRange"; key: string; from: Date; to: Date }; /** Restrict which keys `plan` / `matches` consider. */ export type FilterSelection = { only?: readonly string[]; exclude?: readonly string[]; }; 5a:T1bbf,import type { ColKind, FilterOp, FilterSpec, Scalar } from "./types"; /** Unix ms timestamps are 13-digit numbers (> Sep 2001, < Nov 2286). */ const UNIX_MS_MIN = 1_000_000_000_000; /** * Is this filter value active? * * Inactive means "the user has not filtered on this column": absent, cleared, * an empty multi-select, or a value that cannot be compared at all. This was * written four slightly different ways across four engines. */ export function isActive(value: unknown): boolean { if (value === null || value === undefined) return false; if (typeof value === "string") return value.length > 0; if (typeof value === "number") return !Number.isNaN(value); if (value instanceof Date) return !Number.isNaN(value.getTime()); if (Array.isArray(value)) { // ANY usable member makes the filter active. `normalize` drops the members // it cannot use, so requiring all of them to be usable would make one blank // entry silently delete the whole filter — and inconsistently, since // `["abc", 500]` on a slider degenerates to 500 while `["", 500]` vanished. return value.some(isActive); } return true; } /** Coerce to a `Date`, or `null` if it cannot be one. */ function asDate(value: unknown): Date | null { if (value instanceof Date) { return Number.isNaN(value.getTime()) ? null : value; } // superjson revives Dates, but MCP args and LLM output arrive as ISO strings // or epoch millis. if (typeof value === "string" || typeof value === "number") { // Epoch millis that arrived as a string: `new Date("1700000000000")` is an // Invalid Date while `new Date(1700000000000)` is not. The command palette // serializes timeranges with `getTime()`, and JSON has no Date type, so // this shape is common. The magnitude test disambiguates it from a bare // year like "2024", which `Date` should keep parsing as a year. if (typeof value === "string" && /^\d+$/.test(value)) { const millis = Number(value); if (millis >= UNIX_MS_MIN) { const date = new Date(millis); return Number.isNaN(date.getTime()) ? null : date; } } const date = new Date(value); return Number.isNaN(date.getTime()) ? null : date; } return null; } function asNumber(value: unknown): number | null { if (typeof value === "number") return Number.isNaN(value) ? null : value; if (typeof value === "string" && value.trim() !== "") { const parsed = Number(value); return Number.isNaN(parsed) ? null : parsed; } return null; } function asScalar(value: unknown): Scalar | null { if ( typeof value === "string" || typeof value === "number" || typeof value === "boolean" ) { return value; } return null; } function asArray(value: unknown): unknown[] { return Array.isArray(value) ? value : [value]; } function asBoolean(value: unknown): boolean | null { if (typeof value === "boolean") return value; if (value === "true") return true; if (value === "false") return false; return null; } /** * Coerce one checkbox member to the column's declared type. * * The URL layer, MCP args, and LLM output all deliver `["200", "500"]` for a * numeric column. Without this, the SQL backend received * `inArray(integerColumn, ["200", "500"])` and depended on Postgres casting the * literals, and `coerce()` — the entry point documented as producing validated * values — handed back strings for a number column. */ function asDeclaredScalar(kind: ColKind, value: unknown): Scalar | null { switch (kind) { case "number": return asNumber(value); case "boolean": return asBoolean(value); default: { const scalar = asScalar(value); return scalar === null ? null : String(scalar); } } } function startOfDay(date: Date): Date { const result = new Date(date); result.setHours(0, 0, 0, 0); return result; } function endOfDay(date: Date): Date { const result = new Date(date); result.setHours(23, 59, 59, 999); return result; } /** * Turn one declared filter and its value into a canonical op. * * This is the whole design. Dispatch is on the **declared** `(type, kind)` * pair — never on the runtime shape of `value`. A numeric checkbox is * `{ type: "checkbox", kind: "number" }`, so `[200, 500]` can only become * `oneOf`; `numberRange` is unreachable from a checkbox and * `BETWEEN 200 AND 500` is therefore unrepresentable. Backends never see array * length, so length-based dispatch has nowhere to live. * * Returns `null` when the filter is inactive or the value cannot be coerced * into the declared shape. */ export function normalize(spec: FilterSpec, value: unknown): FilterOp | null { if (!isActive(value)) return null; const { key } = spec; switch (spec.type) { case "input": { // A number column's text box is an exact match, not a substring search — // substring matching on a stringified number makes "5" match 1500. if (spec.kind === "number") { const parsed = asNumber(Array.isArray(value) ? value[0] : value); return parsed === null ? null : { op: "equals", key, value: parsed }; } const raw = Array.isArray(value) ? value[0] : value; const text = asScalar(raw); return text === null ? null : { op: "substring", key, value: String(text) }; } case "checkbox": { // For an array column the members are compared against the *item* type. const memberKind = spec.kind === "array" ? (spec.itemKind ?? "string") : spec.kind; const values = asArray(value) .map((member) => asDeclaredScalar(memberKind, member)) .filter((v): v is Scalar => v !== null); if (values.length === 0) return null; // An array column is a set on both sides — overlap, not membership. return spec.kind === "array" ? { op: "overlaps", key, values } : { op: "oneOf", key, values }; } case "slider": { const numbers = asArray(value) .map(asNumber) .filter((v): v is number => v !== null); if (numbers.length === 0) return null; // A single-handle slider is a degenerate range, not an equality — the // two disagree once the column holds non-integers. const [first, second] = numbers; const min = first!; const max = second ?? first!; return { op: "numberRange", key, min: Math.min(min, max), max: Math.max(min, max), }; } case "timerange": { const dates = asArray(value) .map(asDate) .filter((v): v is Date => v !== null); if (dates.length === 0) return null; // One date means "that whole day". if (dates.length === 1) { return { op: "dateRange", key, from: startOfDay(dates[0]!), to: endOfDay(dates[0]!), }; } const [from, to] = dates; return from!.getTime() <= to!.getTime() ? { op: "dateRange", key, from: from!, to: to! } : { op: "dateRange", key, from: to!, to: from! }; } } } 5b:Td2c,import type { FilterOp, Scalar } from "./types"; /** * Read a possibly dotted key off a row. * * Table schema keys are dot-notation (`"timing.dns"`). Rows may store that * either as a literal flat key or as a nested object, so both are tried — * a flat hit wins, since that is the wire shape. */ export function getValueAtKey(row: unknown, key: string): unknown { if (row === null || typeof row !== "object") return undefined; const flat = (row as Record)[key]; if (flat !== undefined) return flat; if (!key.includes(".")) return undefined; let current: unknown = row; for (const part of key.split(".")) { if (current === null || typeof current !== "object") return undefined; current = (current as Record)[part]; } return current; } function sameScalar(cell: unknown, value: Scalar): boolean { if (cell === value) return true; // The URL layer can only produce strings, so a number column filtered from a // link arrives as one. Compare by string as a last resort rather than by // coercing, which would make `0 == false` true. if ( (typeof cell === "number" || typeof cell === "boolean") && typeof value === "string" ) { return String(cell) === value; } if (typeof cell === "string" && typeof value !== "string") { return cell === String(value); } return false; } function asComparableNumber(cell: unknown): number | null { if (typeof cell === "number") return Number.isNaN(cell) ? null : cell; if (typeof cell === "string" && cell.trim() !== "") { const parsed = Number(cell); return Number.isNaN(parsed) ? null : parsed; } return null; } function asComparableTime(cell: unknown): number | null { if (cell instanceof Date) { return Number.isNaN(cell.getTime()) ? null : cell.getTime(); } if (typeof cell === "string" || typeof cell === "number") { const time = new Date(cell).getTime(); return Number.isNaN(time) ? null : time; } return null; } /** * Evaluate one canonical op against one cell value. * * Exhaustive over `FilterOp` with no default branch — a seventh op fails to * compile here rather than silently passing every row. */ export function evaluateOp(op: FilterOp, cell: unknown): boolean { switch (op.op) { case "substring": { if (cell === null || cell === undefined) return false; // Case-insensitive, matching the SQL side's `ilike`. return String(cell).toLowerCase().includes(op.value.toLowerCase()); } case "equals": return sameScalar(cell, op.value); case "oneOf": return op.values.some((value) => sameScalar(cell, value)); case "overlaps": { // The column is a set. A scalar cell is treated as a one-element set so // a single-value column still matches — this is where the infinite route // used to look only at `row[key][0]`. const cells = Array.isArray(cell) ? cell : [cell]; return cells.some((item) => op.values.some((value) => sameScalar(item, value)), ); } case "numberRange": { const value = asComparableNumber(cell); return value !== null && value >= op.min && value <= op.max; } case "dateRange": { const time = asComparableTime(cell); return ( time !== null && time >= op.from.getTime() && time <= op.to.getTime() ); } } } 5c:T232f,import { resolveColumns } from "../table-schema/col"; import type { ColumnDescriptor, SchemaJSON, TableSchemaDefinition, } from "../table-schema/types"; import { evaluateOp, getValueAtKey } from "./evaluate"; import { isActive, normalize } from "./normalize"; import type { FilterOp, FilterSelection, FilterSpec, FilterValues, Scalar, } from "./types"; export { evaluateOp, getValueAtKey } from "./evaluate"; export { isActive, normalize } from "./normalize"; export type { ColKind, FilterOp, FilterSelection, FilterSpec, FilterType, FilterValueFor, FilterValues, Scalar, } from "./types"; /** * Where a `Filters` gets its declarations. * * `SchemaJSON` is here so the declaration can cross the `"use client"` boundary * as data: `table-schema.tsx` cannot be imported server-side, but its * `toJSON()` can. */ export type FilterSource = | TableSchemaDefinition | SchemaJSON | readonly FilterSpec[]; /** * `TValues` is the shape of the values these semantics accept, keyed by * filterable column. It is `FilterValues` when built from * a table schema definition and the loose `Record` from * `SchemaJSON` or specs, where nothing about the columns is known at compile * time. Search params stay untyped either way — `plan` / `matches` take what * the wire delivers — but declarations written by hand (an action's `when` * guard) and the output of `coerce` are checked against it. */ export interface Filters> { readonly specs: readonly FilterSpec[]; /** Look up one column's declaration. */ spec(key: string): FilterSpec | undefined; /** * Values → canonical ops. Never guesses from the shape of a value. * Inactive and unknown keys are dropped. */ plan( values: Record, selection?: FilterSelection, ): FilterOp[]; /** In-memory predicate. Replaces `filterData` and `filterGenericData`. */ matches( values: Record, row: unknown, selection?: FilterSelection, ): boolean; /** Filter a whole collection. */ apply( rows: readonly TRow[], values: Record, selection?: FilterSelection, ): TRow[]; /** * A TanStack `ColumnDef.filterFn`. Returns a *function*, so nothing has to be * registered on the table via `filterFns: { inDateRange, arrSome }`. */ filterFn( key: string, ): | (( row: { getValue: (id: string) => unknown }, columnId: string, value: unknown, ) => boolean) | undefined; /** Validate and coerce untrusted input (AI structured output, MCP args). */ coerce(raw: Record): Partial; } // ── Deriving specs ────────────────────────────────────────────────────────── function specFromDescriptor( key: string, column: Pick & Partial, "arrayItem">>, ): FilterSpec | null { const { filter } = column; if (!filter) return null; const spec: FilterSpec = { key, type: filter.type, kind: column.kind, }; if (column.kind === "array" && column.arrayItem) { spec.itemKind = column.arrayItem.kind; } if (filter.options) { spec.options = filter.options.map((option) => option.value); } if (filter.min !== undefined) spec.min = filter.min; if (filter.max !== undefined) spec.max = filter.max; return spec; } function isSchemaJSON(source: FilterSource): source is SchemaJSON { return ( !Array.isArray(source) && typeof source === "object" && source !== null && Array.isArray((source as SchemaJSON).columns) ); } function toSpecs(source: FilterSource): FilterSpec[] { if (Array.isArray(source)) { return [...(source as readonly FilterSpec[])]; } if (isSchemaJSON(source)) { const specs: FilterSpec[] = []; for (const column of source.columns) { const spec = specFromDescriptor(column.key, column); if (spec) specs.push(spec); } return specs; } const specs: FilterSpec[] = []; for (const column of resolveColumns(source as TableSchemaDefinition)) { const spec = specFromDescriptor(column.key, column); if (spec) specs.push(spec); } return specs; } function isSelected(key: string, selection?: FilterSelection): boolean { if (selection?.exclude?.includes(key)) return false; if (selection?.only && !selection.only.includes(key)) return false; return true; } // ── Coercion ──────────────────────────────────────────────────────────────── function coerceValue(spec: FilterSpec, raw: unknown): unknown { // Round-tripping through `normalize` is the coercion: if the declared // semantics cannot make an op out of it, it is not a usable filter value. const op = normalize(spec, raw); if (!op) return undefined; switch (op.op) { case "substring": return op.value; case "equals": return op.value; case "oneOf": case "overlaps": { // Drop values outside the declared option set — an LLM will happily // invent an enum member that does not exist. if (!spec.options) return op.values; const allowed = op.values.filter((value) => spec.options!.some((option) => String(option) === String(value)), ); return allowed.length > 0 ? allowed : undefined; } case "numberRange": { // Clamp to the declared bounds. `coerce` is the untrusted-input entry // point, and an LLM asked for "slow requests" will happily produce // `[0, 99999]` against a slider declared `{ min: 0, max: 5000 }`. const lower = spec.min ?? -Infinity; const upper = spec.max ?? Infinity; const min = Math.min(Math.max(op.min, lower), upper); const max = Math.min(Math.max(op.max, lower), upper); return [min, max]; } case "dateRange": return [op.from, op.to]; } } // ── Entry point ───────────────────────────────────────────────────────────── /** * Build the one interpretation of a table's filter semantics. * * Every engine — SQL, in-memory, TanStack — goes through this, so a column's * declared `(FilterType, ColKind)` pair is honoured identically everywhere * instead of being re-derived from whatever the value happened to look like at * runtime. * * Built from a table schema definition, the result knows which columns are * filterable and what each accepts (`FilterValues`); from `SchemaJSON` or * specs it is untyped. */ export function defineFilters( source: TSchema, ): Filters>; export function defineFilters(source: FilterSource): Filters; export function defineFilters(source: FilterSource): Filters { const specs = toSpecs(source); const byKey = new Map(specs.map((spec) => [spec.key, spec])); const plan = ( values: Record, selection?: FilterSelection, ): FilterOp[] => { const ops: FilterOp[] = []; for (const [key, value] of Object.entries(values)) { if (!isSelected(key, selection)) continue; const spec = byKey.get(key); if (!spec) continue; const op = normalize(spec, value); if (op) ops.push(op); } return ops; }; const matches = ( values: Record, row: unknown, selection?: FilterSelection, ): boolean => plan(values, selection).every((op) => evaluateOp(op, getValueAtKey(row, op.key)), ); return { specs, spec: (key) => byKey.get(key), plan, matches, apply: (rows, values, selection) => { const ops = plan(values, selection); if (ops.length === 0) return [...rows]; return rows.filter((row) => ops.every((op) => evaluateOp(op, getValueAtKey(row, op.key))), ); }, filterFn: (key) => { const spec = byKey.get(key); if (!spec) return undefined; return (row, columnId, value) => { const op = normalize(spec, value); // An inactive filter matches everything, which is what TanStack expects // when a column filter is present but empty. if (!op) return true; return evaluateOp(op, row.getValue(columnId)); }; }, coerce: (raw) => { const result: Record = {}; for (const spec of specs) { const value = raw[spec.key]; if (!isActive(value)) continue; const coerced = coerceValue(spec, value); if (coerced !== undefined) result[spec.key] = coerced; } return result; }, }; } export type { Scalar as FilterScalar }; 5d:T2bf3,"use client"; import { DataTableCellBadge, DataTableCellBar, DataTableCellBoolean, DataTableCellCode, DataTableCellGauge, DataTableCellHeatmap, DataTableCellLevelIndicator, DataTableCellNumber, DataTableCellStar, DataTableCellStatusCode, DataTableCellText, DataTableCellTimestamp, } from "@/components/data-table/data-table-cell"; import { DataTableColumnHeader } from "@/components/data-table/data-table-column-header"; import { Checkbox } from "@/components/ui/checkbox"; import { defineFilters } from "@/lib/filters"; import type { DataTableFeatures } from "@/lib/table/features"; import type { ColumnDef, RowData } from "@tanstack/react-table"; import type { ComponentProps, JSX } from "react"; import { resolveColumns } from "../col"; import type { DisplayDescriptor, TableSchemaDefinition } from "../types"; /** * Render the cell based on the display config. */ function renderCell( display: DisplayDescriptor, value: unknown, context?: { min: number; max: number }, ): JSX.Element | null { const fallback = ; const colorMap = "colorMap" in display ? display.colorMap : undefined; switch (display.type) { case "text": { const hex = colorMap?.[String(value)]; return typeof value === "string" || typeof value === "number" ? ( ) : ( fallback ); } case "code": { const hex = colorMap?.[String(value)]; return typeof value === "string" || typeof value === "number" ? ( ) : ( fallback ); } case "number": { const hex = colorMap?.[String(value)]; return typeof value === "number" ? ( ) : ( fallback ); } case "timestamp": { const hex = colorMap?.[String(value)]; return value instanceof Date || typeof value === "string" || typeof value === "number" ? ( ) : ( fallback ); } case "badge": { if (Array.isArray(value)) { return (

{value.map((item, i) => ( ))}

); } const hex = colorMap?.[String(value)]; return typeof value === "string" || typeof value === "number" ? ( ) : ( fallback ); } case "boolean": { const hex = colorMap?.[String(value)]; return typeof value === "boolean" ? ( ) : ( fallback ); } case "star": { return typeof value === "boolean" ? ( ) : ( fallback ); } case "status-code": { const hex = colorMap?.[String(value)]; return typeof value === "number" ? ( ) : ( fallback ); } case "level-indicator": { const hex = colorMap?.[String(value)]; return typeof value === "string" ? ( ) : ( fallback ); } case "heatmap": { const { min = 0, max = 100 } = context ?? {}; return typeof value === "number" ? ( ) : ( fallback ); } case "bar": { const { min = 0, max = 100 } = context ?? {}; return typeof value === "number" ? ( ) : ( fallback ); } case "gauge": { const { min = 0, max = 100 } = context ?? {}; return typeof value === "number" ? ( ) : ( fallback ); } } } /** * The one interpretation of `.size()` / `.minSize()` / `.resizable()`: * * - `.minSize(px)` — a flexing column with a floor: it absorbs the table's * leftover width but never compresses below `px`. * - `.size(px)` without `.resizable()` — locked: min/max pin the rendered * width, so only an unsized column can flex. * - `.size(px)` with `.resizable()` — `px` is the initial width only. */ function sizingFor(config: { size?: number; minSize?: number; resizable: boolean; }): { size?: number; minSize?: number; maxSize?: number } { if (config.minSize !== undefined) { return { minSize: config.minSize, ...(config.size !== undefined ? { size: config.size } : {}), }; } if (config.size === undefined) return {}; if (config.resizable) return { size: config.size }; return { size: config.size, minSize: config.size, maxSize: config.size }; } /** * The header checkbox's third state, spelled for both libraries. * * `ui/checkbox` resolves from whichever library the project was initialized * with, and they disagree: Radix takes `checked="indeterminate"`, Base UI * types `checked` as a boolean and takes a separate `indeterminate` flag. * Setting both is the only form that compiles and renders on either — hence * the cast, the one place this file steps around a props type. In the partial * state Radix does receive the extra `indeterminate` and forwards it to its * `