@pilotiq/pilotiq 0.1.0

package/src/entries/Entry.ts

@@ -0,0 +1,304 @@
+import { Element, type ElementMeta } from '../schema/Element.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Per-record formatter callback. Receives the resolved state value and the
+ * full record; returns the rendered string. Runs server-side at resolve
+ * time — output is stamped on `EntryMeta._formatted` so the renderer can
+ * skip re-running the format spec.
+ */
+export type EntryFormatStateHandler = (
+  value:  unknown,
+  record: Record<string, unknown>,
+) => string
+
+/**
+ * Override for `Entry.resolveValue`. String form is dotted-path traversal
+ * (`'author.name'`, `'tags.0.name'`); function form runs the user handler
+ * with the full record. Used for joins, computed columns, or anywhere the
+ * value isn't `record[name]`.
+ */
+export type EntryStateResolver =
+  | string
+  | ((record: Record<string, unknown>) => unknown)
+
+/** Built-in formatters — same shape as `ColumnFormat` so the renderer
+ *  reuses `applyColumnFormat()` unchanged. */
+export type EntryFormat =
+  | { kind: 'dateTime'; pattern?: string }
+  | { kind: 'since' }
+  | { kind: 'money';    currency: string; locale?: string }
+  | { kind: 'numeric';  decimals?: number; locale?: string }
+  | { kind: 'limit';    chars: number }
+
+export type EntryWeight = 'normal' | 'medium' | 'semibold' | 'bold'
+export type EntryColor  = 'default' | 'muted' | 'primary' | 'destructive' | 'success' | 'warning' | 'info'
+export type EntrySize   = 'xs' | 'sm' | 'base' | 'lg' | 'xl'
+
+/**
+ * JSON shape sent to the client for every entry. Subclasses extend the
+ * union via `entryType` (`'text' | 'badge' | 'icon' | 'image'`) and
+ * tack on subclass-specific keys without further widening.
+ */
+export interface EntryMeta extends ElementMeta {
+  type:        'entry'
+  entryType:   string
+  name:        string
+  label:       string
+  value:       unknown
+  inlineLabel?: boolean
+  default?:    string
+  helperText?: string
+  tooltip?:    string
+  weight?:     EntryWeight
+  color?:      EntryColor
+  size?:       EntrySize
+  format?:     EntryFormat
+  copyable?:   { label?: string }
+  /**
+   * Server-evaluated `formatStateUsing` output. The renderer prefers this
+   * over re-applying `format` when present (mirrors the `Column._formatted`
+   * convention from Plan #2).
+   */
+  _formatted?: string
+  lineClamp?:  number
+  wrap?:       boolean
+}
+
+/**
+ * Read-only sibling of `Field`. Renders a label-value pair on `ViewPage`
+ * (or anywhere `Resource.detail()` returns elements).
+ *
+ * Entries resolve their value from `ctx.record[name]` at meta-build time
+ * — they're inert templates with no input components, no validators, no
+ * submit chrome. The cosmetic surface (`color / weight / size / tooltip`)
+ * mirrors the `Column` chrome so rows of a table and detail-page entries
+ * stay visually consistent.
+ *
+ * Subclasses set the `entryType` discriminator (`'text' | 'badge' | …`)
+ * which the renderer dispatches on; everything else lives on the base.
+ */
+export abstract class Entry extends Element {
+  protected _name: string
+  protected _label?: string
+  protected _inlineLabel = false
+  protected _default?: string
+  protected _helperText?: string
+  protected _tooltip?: string
+  protected _weight?: EntryWeight
+  protected _color?:  EntryColor
+  protected _size?:   EntrySize
+  protected _format?: EntryFormat
+  protected _formatState?: EntryFormatStateHandler
+  protected _state?: EntryStateResolver
+  protected _copyable?: { label?: string }
+  protected _lineClamp?: number
+  protected _wrap = false
+
+  protected constructor(name: string) {
+    super()
+    this._name = name
+  }
+
+  /** Subclasses set the wire-side discriminator (`'text' | 'badge' | …`). */
+  protected abstract getEntryType(): string
+
+  getType(): string { return 'entry' }
+  getName(): string { return this._name }
+
+  // ─── Chrome ───────────────────────────────────────────
+
+  /** Override the auto-derived label. Default = startCase of `name`. */
+  label(text: string): this { this._label = text; return this }
+
+  /** Render label to the left of the value rather than above it. */
+  inlineLabel(v = true): this { this._inlineLabel = v; return this }
+
+  /** Fallback string when the resolved value is null / undefined / empty. */
+  default(s: string): this { this._default = s; return this }
+  /** Alias matching the field-side spelling. */
+  placeholder(s: string): this { return this.default(s) }
+
+  helperText(text: string): this { this._helperText = text; return this }
+  tooltip(text: string): this   { this._tooltip = text; return this }
+
+  weight(w: EntryWeight): this { this._weight = w; return this }
+  color(c: EntryColor): this   { this._color = c; return this }
+  size(s: EntrySize): this     { this._size = s; return this }
+
+  /** Truncate the value with an ellipsis when it spills onto more than `n`
+   *  lines (CSS `-webkit-line-clamp`). Mutually exclusive with `wrap()`. */
+  lineClamp(n: number): this { this._lineClamp = n; return this }
+
+  /** Allow the value to wrap onto multiple lines. Without this the value
+   *  is rendered with `whitespace-nowrap`. */
+  wrap(v = true): this { this._wrap = v; return this }
+
+  // ─── Built-in formatters (mirrors Column) ─────────────
+
+  dateTime(pattern?: string): this {
+    this._format = pattern ? { kind: 'dateTime', pattern } : { kind: 'dateTime' }
+    return this
+  }
+
+  since(): this {
+    this._format = { kind: 'since' }
+    return this
+  }
+
+  money(currency: string, locale?: string): this {
+    this._format = locale ? { kind: 'money', currency, locale } : { kind: 'money', currency }
+    return this
+  }
+
+  numeric(opts: { decimals?: number; locale?: string } = {}): this {
+    this._format = {
+      kind: 'numeric',
+      ...(opts.decimals !== undefined ? { decimals: opts.decimals } : {}),
+      ...(opts.locale   !== undefined ? { locale:   opts.locale   } : {}),
+    }
+    return this
+  }
+
+  limit(chars: number): this {
+    this._format = { kind: 'limit', chars }
+    return this
+  }
+
+  /** Per-record formatter — receives the resolved state value and the full
+   *  record, returns the display string. Wins over `format` when both are
+   *  set (output stamped on `_formatted`). */
+  formatStateUsing(fn: EntryFormatStateHandler): this {
+    this._formatState = fn
+    return this
+  }
+
+  /** Render a copy-icon button next to the value. v1 copies via the
+   *  client `navigator.clipboard.writeText` of the *raw* state value, or
+   *  the formatted string when `formatStateUsing` is set. */
+  copyable(label?: string): this {
+    this._copyable = label !== undefined ? { label } : {}
+    return this
+  }
+
+  /**
+   * Override the default `record[name]` lookup. String form does dotted-
+   * path traversal — `'author.name'`, `'tags.0.label'`; missing
+   * intermediates resolve to `undefined`. Function form runs the
+   * user-supplied accessor with the full record.
+   *
+   * The entry's `name` still drives the auto-derived label and the wire-
+   * side discriminator key, so use `.label(...)` alongside when the path
+   * doesn't read well as a heading.
+   *
+   * @example
+   * TextEntry.make('authorName').state('author.name').label('Author')
+   * TextEntry.make('total').state(r => Number(r.subtotal) + Number(r.tax))
+   */
+  state(resolver: EntryStateResolver): this {
+    this._state = resolver
+    return this
+  }
+
+  // ─── Resolution ───────────────────────────────────────
+
+  /** Read the state value out of the loaded record. Honors `state()`
+   *  override (string dotted-path or accessor fn) when set; otherwise
+   *  falls back to `record[name]`. */
+  resolveValue(ctx?: RenderContext): unknown {
+    const record = ctx?.record as Record<string, unknown> | undefined
+    if (record === undefined || record === null) return undefined
+    if (this._state === undefined) return record[this._name]
+    if (typeof this._state === 'function') {
+      try { return this._state(record) }
+      catch { return undefined }
+    }
+    return readDottedPath(record, this._state)
+  }
+
+  /** Default label = startCase of the attribute name. */
+  protected deriveLabel(): string {
+    if (this._label !== undefined) return this._label
+    if (!this._name) return ''
+    return this._name
+      .replace(/([A-Z])/g, ' $1')
+      .replace(/[_-]+/g, ' ')
+      .replace(/^./, c => c.toUpperCase())
+      .trim()
+  }
+
+  /**
+   * Build the wire-side meta. Subclasses override to add type-specific
+   * keys; all should call `super.toMeta(ctx)` first and spread.
+   *
+   * Async because `formatStateUsing` may want to await a lookup; v1
+   * callers pass synchronous handlers but the contract leaves room.
+   */
+  toMeta(ctx?: RenderContext): EntryMeta | Promise<EntryMeta> {
+    const value  = this.resolveValue(ctx)
+    const record = (ctx?.record ?? {}) as Record<string, unknown>
+
+    const meta: EntryMeta = {
+      type:      'entry',
+      entryType: this.getEntryType(),
+      name:      this._name,
+      label:     this.deriveLabel(),
+      value,
+    }
+    if (this._inlineLabel)               meta.inlineLabel = true
+    if (this._default !== undefined)     meta.default     = this._default
+    if (this._helperText !== undefined)  meta.helperText  = this._helperText
+    if (this._tooltip !== undefined)     meta.tooltip     = this._tooltip
+    if (this._weight !== undefined)      meta.weight      = this._weight
+    if (this._color  !== undefined)      meta.color       = this._color
+    if (this._size   !== undefined)      meta.size        = this._size
+    if (this._format !== undefined)      meta.format      = this._format
+    if (this._copyable !== undefined)    meta.copyable    = this._copyable
+    if (this._lineClamp !== undefined)   meta.lineClamp   = this._lineClamp
+    if (this._wrap)                      meta.wrap        = true
+
+    if (this._formatState) {
+      try {
+        meta._formatted = this._formatState(value, record)
+      } catch {
+        // Fail-soft — drop the formatted string and let the client fall
+        // back to the raw value or built-in `format`. Matches the
+        // posture of `Column.formatStateUsing` (errors don't crash the
+        // page-data builder).
+      }
+    }
+
+    return meta
+  }
+}
+
+/** Type guard mirroring `isServerDataElement` / `isRepeaterField`. Lets
+ *  walkers branch on entries without `instanceof`-tripping over Vite
+ *  module-cache duplication (`feedback_vite_ssr_module_dup_instanceof`). */
+export function isEntry(el: Element): el is Entry {
+  return el.getType() === 'entry'
+}
+
+/** Walk a dotted path against an arbitrary record / array shape; bail to
+ *  `undefined` on any missing intermediate. Numeric segments index into
+ *  arrays. Inlined here rather than reused from `dispatchForm.ts` because
+ *  Entry has no other dependency on the form pipeline and keeping the
+ *  schema layer free of submit-side imports avoids a cycle. */
+function readDottedPath(record: Record<string, unknown>, path: string): unknown {
+  if (path === '') return record
+  const segments = path.split('.')
+  let cur: unknown = record
+  for (const seg of segments) {
+    if (cur === null || cur === undefined) return undefined
+    if (Array.isArray(cur)) {
+      const idx = Number(seg)
+      if (!Number.isInteger(idx)) return undefined
+      cur = cur[idx]
+    } else if (typeof cur === 'object') {
+      cur = (cur as Record<string, unknown>)[seg]
+    } else {
+      return undefined
+    }
+  }
+  return cur
+}

package/src/entries/IconEntry.ts

@@ -0,0 +1,49 @@
+import { Entry, type EntryMeta } from './Entry.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/** Per-value icon mapping. `icon` is a registry name (`getIcon(name)`);
+ *  `color` is one of the standard column-color tokens; `label` overrides
+ *  the accessible label (defaults to the raw value). */
+export interface IconEntryOption {
+  icon:   string
+  color?: string
+  label?: string
+}
+
+/**
+ * Read-only sibling of `IconColumn` / `BooleanColumn`. Renders an icon
+ * for the resolved state value via a value→icon map. Use for status
+ * indicators on detail pages (active/inactive, paid/unpaid, …).
+ *
+ * @example
+ * IconEntry.make('verified').options({
+ *   true:  { icon: 'check-circle', color: 'success', label: 'Verified' },
+ *   false: { icon: 'x-circle',     color: 'destructive', label: 'Unverified' },
+ * })
+ */
+export class IconEntry extends Entry {
+  private _options: Record<string, IconEntryOption> = {}
+
+  private constructor(name: string) {
+    super(name)
+  }
+
+  static make(name: string): IconEntry {
+    return new IconEntry(name)
+  }
+
+  options(map: Record<string, IconEntryOption>): this {
+    this._options = { ...this._options, ...map }
+    return this
+  }
+
+  protected override getEntryType(): string { return 'icon' }
+
+  override async toMeta(ctx?: RenderContext): Promise<EntryMeta> {
+    const meta = await Promise.resolve(super.toMeta(ctx)) as EntryMeta & { options?: Record<string, IconEntryOption> }
+    if (Object.keys(this._options).length > 0) {
+      meta.options = this._options
+    }
+    return meta
+  }
+}

package/src/entries/ImageEntry.ts

@@ -0,0 +1,61 @@
+import { Entry, type EntryMeta } from './Entry.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+export type ImageEntryShape = 'square' | 'rounded' | 'circle'
+
+/**
+ * Read-only sibling of `ImageColumn` / the `Image` display prime, but
+ * record-bound. The state value is the image URL; `.width(px) / .height(px)`
+ * (or the `.dimensions(px)` square sugar) control the rendered size;
+ * `.square() / .rounded() / .circle()` pick the border-radius shape.
+ *
+ * `Entry.size(EntrySize)` is inherited but doesn't affect image rendering
+ * — it's the text-size token used by `TextEntry`. Use `dimensions()` for
+ * pixel sizing instead.
+ *
+ * @example
+ * ImageEntry.make('avatarUrl').dimensions(96).circle()
+ */
+export class ImageEntry extends Entry {
+  private _width  = 64
+  private _height = 64
+  private _imageShape: ImageEntryShape = 'rounded'
+
+  private constructor(name: string) {
+    super(name)
+  }
+
+  static make(name: string): ImageEntry {
+    return new ImageEntry(name)
+  }
+
+  width(px: number): this  { this._width  = px; return this }
+  height(px: number): this { this._height = px; return this }
+
+  /** Square sugar — sets width and height to the same pixel value. */
+  dimensions(px: number): this {
+    this._width  = px
+    this._height = px
+    return this
+  }
+
+  square(): this  { this._imageShape = 'square';  return this }
+  rounded(): this { this._imageShape = 'rounded'; return this }
+  circle(): this  { this._imageShape = 'circle';  return this }
+
+  protected override getEntryType(): string { return 'image' }
+
+  override async toMeta(ctx?: RenderContext): Promise<EntryMeta> {
+    const meta = await Promise.resolve(super.toMeta(ctx)) as EntryMeta & {
+      imageSize?:  number
+      imageWidth?: number
+      imageHeight?: number
+      imageShape?: ImageEntryShape
+    }
+    meta.imageWidth  = this._width
+    meta.imageHeight = this._height
+    meta.imageShape  = this._imageShape
+    if (this._width === this._height) meta.imageSize = this._width
+    return meta
+  }
+}

package/src/entries/KeyValueEntry.ts

@@ -0,0 +1,47 @@
+import { Entry, type EntryMeta } from './Entry.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Read-only sibling of `KeyValueField`. Renders a `Record<string, unknown>`
+ * (or any plain object) as a two-column key/value table. Useful for debug
+ * surfaces — request headers, webhook payloads, settings blobs.
+ *
+ * The state value at `ctx.record[name]` may be:
+ *   - a plain object → rendered as key→value rows
+ *   - a JSON string  → parsed and rendered (admin-trusted; non-JSON falls
+ *     through as a single "value" entry)
+ *   - null / undefined / empty → renders the `default()` placeholder
+ *
+ * Values that are themselves objects / arrays are stringified via JSON
+ * for compactness; primitives render as their string form.
+ *
+ * @example
+ * KeyValueEntry.make('headers').keyLabel('Header').valueLabel('Value')
+ */
+export class KeyValueEntry extends Entry {
+  private _keyLabel   = 'Key'
+  private _valueLabel = 'Value'
+
+  private constructor(name: string) {
+    super(name)
+  }
+
+  static make(name: string): KeyValueEntry {
+    return new KeyValueEntry(name)
+  }
+
+  keyLabel(label: string): this   { this._keyLabel = label; return this }
+  valueLabel(label: string): this { this._valueLabel = label; return this }
+
+  protected override getEntryType(): string { return 'keyValue' }
+
+  override async toMeta(ctx?: RenderContext): Promise<EntryMeta> {
+    const meta = await Promise.resolve(super.toMeta(ctx)) as EntryMeta & {
+      keyLabel?:   string
+      valueLabel?: string
+    }
+    meta.keyLabel   = this._keyLabel
+    meta.valueLabel = this._valueLabel
+    return meta
+  }
+}