@pilotiq/pilotiq 0.1.0

package/src/entries/BadgeEntry.ts

@@ -0,0 +1,39 @@
+import { Entry, type EntryMeta } from './Entry.js'
+import type { BadgeColor } from '../columns/BadgeColumn.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Read-only sibling of `BadgeColumn`. Renders the resolved state value as
+ * a colored pill. Pair with `.colors({ value: BadgeColor })` to map each
+ * value to a preset; unknown values fall back to `gray`.
+ *
+ * @example
+ * BadgeEntry.make('status').colors({ draft: 'gray', published: 'success', archived: 'warning' })
+ */
+export class BadgeEntry extends Entry {
+  private _colors: Record<string, BadgeColor> = {}
+
+  private constructor(name: string) {
+    super(name)
+  }
+
+  static make(name: string): BadgeEntry {
+    return new BadgeEntry(name)
+  }
+
+  /** value→color preset map. Unknown values render as `gray`. */
+  colors(map: Record<string, BadgeColor>): this {
+    this._colors = { ...this._colors, ...map }
+    return this
+  }
+
+  protected override getEntryType(): string { return 'badge' }
+
+  override async toMeta(ctx?: RenderContext): Promise<EntryMeta> {
+    const meta = await Promise.resolve(super.toMeta(ctx)) as EntryMeta & { colors?: Record<string, BadgeColor> }
+    if (Object.keys(this._colors).length > 0) {
+      meta.colors = this._colors
+    }
+    return meta
+  }
+}

package/src/entries/CodeEntry.test.ts

@@ -0,0 +1,40 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { CodeEntry } from './CodeEntry.js'
+
+describe('CodeEntry', () => {
+  it('emits entryType:code and resolves value from record[name]', () => {
+    const meta = CodeEntry.make('payload').toMeta({
+      record: { payload: '{"a":1}' },
+    })
+    assert.equal(meta.entryType, 'code')
+    assert.equal(meta.value,     '{"a":1}')
+    assert.equal('language' in meta, false)
+  })
+
+  it('emits language hint when set', () => {
+    const meta = CodeEntry.make('payload').language('json').toMeta({
+      record: { payload: '{}' },
+    })
+    assert.equal(meta.language, 'json')
+  })
+
+  it('inherits copyable / tooltip from base Entry', () => {
+    const meta = CodeEntry.make('snippet')
+      .language('ts')
+      .copyable()
+      .tooltip('Latest payload')
+      .toMeta({ record: { snippet: 'const x = 1' } })
+    assert.equal(meta.tooltip, 'Latest payload')
+    assert.deepEqual(meta.copyable, {})
+  })
+
+  it('supports formatStateUsing for object → string conversion', () => {
+    const meta = CodeEntry.make('config')
+      .language('json')
+      .formatStateUsing(v => JSON.stringify(v, null, 2))
+      .toMeta({ record: { config: { a: 1 } } })
+    assert.equal(meta._formatted, '{\n  "a": 1\n}')
+  })
+})

package/src/entries/CodeEntry.ts

@@ -0,0 +1,52 @@
+import { Entry, type EntryMeta } from './Entry.js'
+
+export interface CodeEntryMeta extends EntryMeta {
+  language?: string
+}
+
+/**
+ * Read-only sibling of `CodeEditorField` — renders the resolved value as
+ * `<pre><code>` with a monospace font. Pairs with `Resource.detail()` for
+ * showing user-supplied code, JSON blobs, or config snippets.
+ *
+ * v1 ships **without bundled syntax highlighting** to keep the core
+ * package small. Pass a `language()` hint and a consumer can register a
+ * highlighter via the existing rich-text renderer registry pattern (or
+ * the upcoming `@pilotiq/codemirror` adapter's read-only mode); without
+ * a registered highlighter the entry renders plain monospaced text.
+ *
+ *   CodeEntry.make('payload').language('json').copyable()
+ *
+ * Honors all the inherited chrome (`color / size / weight / tooltip /
+ * copyable`), though `weight` is rarely useful on code blocks.
+ *
+ * For PHP arrays / JS objects, set `formatStateUsing(JSON.stringify)`
+ * to control the wire shape — entries don't auto-stringify objects.
+ */
+export class CodeEntry extends Entry {
+  private _language?: string
+
+  private constructor(name: string) {
+    super(name)
+  }
+
+  static make(name: string): CodeEntry {
+    return new CodeEntry(name)
+  }
+
+  /**
+   * Language hint passed through to the meta (`'json' | 'ts' | 'html' |
+   * …`). Plays the same role as `CodeEditorField.language()` — opaque to
+   * the framework, consumed by an optional highlighter registered by
+   * the consumer.
+   */
+  language(id: string): this { this._language = id; return this }
+
+  protected override getEntryType(): string { return 'code' }
+
+  override toMeta(ctx?: Parameters<Entry['toMeta']>[0]): CodeEntryMeta {
+    const meta = super.toMeta(ctx) as CodeEntryMeta
+    if (this._language !== undefined) meta.language = this._language
+    return meta
+  }
+}

package/src/entries/ColorEntry.ts

@@ -0,0 +1,63 @@
+import { Entry, type EntryMeta } from './Entry.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+export type ColorEntryShape = 'square' | 'rounded' | 'circle'
+
+/**
+ * Read-only swatch entry — sibling of `ColorPickerField`. The state value
+ * is a CSS color string (`#aabbcc`, `rgb(…)`, `oklch(…)`, …) rendered as
+ * a colored chip. The raw value is shown beside the chip by default; toggle
+ * with `.copyable()` for click-to-copy on the value text.
+ *
+ * @example
+ * ColorEntry.make('brandColor').dimensions(24).circle()
+ */
+export class ColorEntry extends Entry {
+  private _width  = 24
+  private _height = 24
+  private _shape: ColorEntryShape = 'rounded'
+  private _showValue = true
+
+  private constructor(name: string) {
+    super(name)
+  }
+
+  static make(name: string): ColorEntry {
+    return new ColorEntry(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._shape = 'square';  return this }
+  rounded(): this { this._shape = 'rounded'; return this }
+  circle(): this  { this._shape = 'circle';  return this }
+
+  /** Hide the raw color string next to the swatch (chip only). */
+  hideValue(v = true): this { this._showValue = !v; return this }
+
+  protected override getEntryType(): string { return 'color' }
+
+  override async toMeta(ctx?: RenderContext): Promise<EntryMeta> {
+    const meta = await Promise.resolve(super.toMeta(ctx)) as EntryMeta & {
+      colorWidth?:  number
+      colorHeight?: number
+      colorSize?:   number
+      colorShape?:  ColorEntryShape
+      showValue?:   boolean
+    }
+    meta.colorWidth  = this._width
+    meta.colorHeight = this._height
+    meta.colorShape  = this._shape
+    if (this._width === this._height) meta.colorSize = this._width
+    if (!this._showValue)             meta.showValue = false
+    return meta
+  }
+}

package/src/entries/ComponentEntry.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveSchema, _resetResolverRegistry } from '../schema/resolveSchema.js'
+import { ComponentEntry } from './ComponentEntry.js'
+import type { EntryMeta } from './Entry.js'
+
+beforeEach(() => _resetResolverRegistry())
+
+describe('ComponentEntry — wire shape', () => {
+  it('serializes with entryType=component', async () => {
+    const out = await resolveSchema(
+      [ComponentEntry.make('location').component('CoordinatesMap')],
+      { record: { location: { lat: 51.5, lng: -0.13 } } },
+    )
+    const m = out[0] as EntryMeta & { component?: string }
+    assert.equal(m.entryType, 'component')
+    assert.equal(m.component, 'CoordinatesMap')
+  })
+
+  it('passes the resolved value through unchanged', async () => {
+    const out = await resolveSchema(
+      [ComponentEntry.make('location').component('CoordinatesMap')],
+      { record: { location: { lat: 51.5, lng: -0.13 } } },
+    )
+    const m = out[0] as EntryMeta
+    assert.deepEqual(m.value, { lat: 51.5, lng: -0.13 })
+  })
+
+  it('value is undefined when record is missing the attribute', async () => {
+    const out = await resolveSchema(
+      [ComponentEntry.make('coords').component('Map')],
+      { record: { other: 1 } },
+    )
+    assert.equal((out[0] as EntryMeta).value, undefined)
+  })
+})
+
+describe('ComponentEntry — fluent vs subclass', () => {
+  class CoordinatesMap extends ComponentEntry {
+    static override componentName = 'CoordinatesMap'
+  }
+
+  it('subclass form picks up static componentName', async () => {
+    const out = await resolveSchema(
+      [CoordinatesMap.make('location')],
+      { record: { location: { lat: 1, lng: 2 } } },
+    )
+    const m = out[0] as EntryMeta & { component?: string }
+    assert.equal(m.component, 'CoordinatesMap')
+  })
+
+  it('instance .component() overrides the static', async () => {
+    const out = await resolveSchema(
+      [CoordinatesMap.make('location').component('OtherMap')],
+      { record: { location: { lat: 1, lng: 2 } } },
+    )
+    assert.equal((out[0] as EntryMeta & { component?: string }).component, 'OtherMap')
+  })
+
+  it('falls back to entry name when no static + no instance setter', async () => {
+    const out = await resolveSchema(
+      [ComponentEntry.make('location')],
+      { record: { location: 'x' } },
+    )
+    assert.equal((out[0] as EntryMeta & { component?: string }).component, 'location')
+  })
+})
+
+describe('ComponentEntry — inherits Entry surface', () => {
+  it('label / helperText / tooltip / inlineLabel', async () => {
+    const out = await resolveSchema(
+      [
+        ComponentEntry.make('location')
+          .component('Map')
+          .label('Where')
+          .helperText('lat/lng pair')
+          .tooltip('Stored as a JSON object')
+          .inlineLabel(),
+      ],
+      { record: { location: 'x' } },
+    )
+    const m = out[0] as EntryMeta
+    assert.equal(m.label,       'Where')
+    assert.equal(m.helperText,  'lat/lng pair')
+    assert.equal(m.tooltip,     'Stored as a JSON object')
+    assert.equal(m.inlineLabel, true)
+  })
+
+  it('honors state(path) for nested values', async () => {
+    const out = await resolveSchema(
+      [ComponentEntry.make('mapData').component('Map').state('venue.coords')],
+      { record: { venue: { coords: { lat: 5, lng: 9 } } } },
+    )
+    assert.deepEqual((out[0] as EntryMeta).value, { lat: 5, lng: 9 })
+  })
+
+  it('honors state(fn) for computed values', async () => {
+    const out = await resolveSchema(
+      [
+        ComponentEntry.make('mapData').component('Map').state((r) => ({
+          lat:   (r as { lat: number }).lat,
+          lng:   (r as { lng: number }).lng,
+          label: (r as { name: string }).name,
+        })),
+      ],
+      { record: { lat: 1, lng: 2, name: 'HQ' } },
+    )
+    assert.deepEqual((out[0] as EntryMeta).value, { lat: 1, lng: 2, label: 'HQ' })
+  })
+
+  it('formatStateUsing still stamps _formatted', async () => {
+    const out = await resolveSchema(
+      [
+        ComponentEntry.make('coords')
+          .component('Map')
+          .formatStateUsing((v) => `(${(v as { lat: number }).lat},${(v as { lng: number }).lng})`),
+      ],
+      { record: { coords: { lat: 1, lng: 2 } } },
+    )
+    assert.equal((out[0] as EntryMeta)._formatted, '(1,2)')
+  })
+
+  it('honors visible(false) — drops the entry', async () => {
+    const out = await resolveSchema(
+      [ComponentEntry.make('coords').component('Map').visible(false)],
+      { record: { coords: 'x' } },
+    )
+    assert.equal(out.length, 0)
+  })
+
+  it('honors columnSpan() under a parent grid', async () => {
+    const out = await resolveSchema(
+      [ComponentEntry.make('coords').component('Map').columnSpan(3)],
+      { record: { coords: 'x' } },
+    )
+    assert.deepEqual((out[0] as EntryMeta)._layout, { columnSpan: 3 })
+  })
+})
+
+describe('ComponentEntry — registry', () => {
+  it('register + lookup round-trip', async () => {
+    const { registerEntryComponents, getEntryComponent, _resetEntryRegistryForTests } =
+      await import('./registry.js')
+    _resetEntryRegistryForTests()
+    const Stub = () => null
+    registerEntryComponents({ Stub: Stub as never })
+    assert.equal(getEntryComponent('Stub'), Stub)
+    assert.equal(getEntryComponent('Missing'), undefined)
+    _resetEntryRegistryForTests()
+  })
+
+  it('skips falsy entries on register (defensive)', async () => {
+    const { registerEntryComponents, getEntryComponent, _resetEntryRegistryForTests } =
+      await import('./registry.js')
+    _resetEntryRegistryForTests()
+    registerEntryComponents({ Bad: undefined as never })
+    assert.equal(getEntryComponent('Bad'), undefined)
+  })
+
+  it('multiple register calls merge', async () => {
+    const { registerEntryComponents, getEntryComponent, _resetEntryRegistryForTests } =
+      await import('./registry.js')
+    _resetEntryRegistryForTests()
+    const A = () => null
+    const B = () => null
+    registerEntryComponents({ A: A as never })
+    registerEntryComponents({ B: B as never })
+    assert.equal(getEntryComponent('A'), A)
+    assert.equal(getEntryComponent('B'), B)
+    _resetEntryRegistryForTests()
+  })
+})

package/src/entries/ComponentEntry.ts

@@ -0,0 +1,95 @@
+import { Entry, type EntryMeta } from './Entry.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Escape-hatch infolist entry. Hands rendering off to a user-supplied
+ * React component registered via `registerEntryComponents()`. Useful
+ * when the built-in entries (Text/Badge/Icon/Image/KeyValue/Color) don't
+ * fit — a coordinates map, an audit-trail timeline, an embedded chart.
+ *
+ * Two usage patterns mirror the `View` widget shape:
+ *
+ * **Subclass form** — extend `ComponentEntry` so the component reference
+ * lives as a static on a stable class:
+ *
+ *   import { ComponentEntry } from '@pilotiq/pilotiq'
+ *   export class CoordinatesMap extends ComponentEntry {
+ *     static componentName = 'CoordinatesMap'
+ *   }
+ *
+ *   // bootstrap/providers.ts
+ *   registerEntryComponents({ CoordinatesMap })
+ *
+ *   // Resource.detail()
+ *   CoordinatesMap.make('location').label('Where')
+ *
+ * **Fluent form** — for one-off cases where a subclass is overkill:
+ *
+ *   ComponentEntry.make('location').component('CoordinatesMap')
+ *
+ * The component receives `{ value, record }` as its sole props — `value`
+ * is the entry's resolved state value (honors `.state(path | fn)` like
+ * any other entry) and `record` is the full loaded record. Components
+ * are looked up at render through the entry-component registry (see
+ * `@pilotiq/pilotiq/entries`).
+ */
+export class ComponentEntry extends Entry {
+  /**
+   * Component name used to look up the registered React component at
+   * render time. Subclasses set this as a static; the fluent form sets
+   * it via `.component(name)`.
+   *
+   * (Despite the name, this is a *string key* into the runtime registry,
+   * not a component reference itself — keeps `ComponentEntry` shippable
+   * through `viewProps` and avoids the `_components.ts` manifest walker,
+   * mirroring the `View` widget convention.)
+   */
+  static componentName?: string
+
+  protected _componentName?: string
+
+  // Public for `make()`'s `new this(name)` factory call from subclasses —
+  // a protected ctor here breaks `class Foo extends ComponentEntry {}; Foo.make('x')`
+  // because the typeof Foo signature wouldn't satisfy `new (name) => ComponentEntry`.
+  constructor(name: string) {
+    super(name)
+  }
+
+  static make(
+    this: new (name: string) => ComponentEntry,
+    name: string,
+  ): ComponentEntry {
+    return new this(name)
+  }
+
+  /** Set / override the registered component name. */
+  component(name: string): this {
+    this._componentName = name
+    return this
+  }
+
+  protected override getEntryType(): string { return 'component' }
+
+  /** Resolve the effective component name (instance > static > fallback to entry name). */
+  getComponentName(): string {
+    if (this._componentName) return this._componentName
+    const ctor = this.constructor as { componentName?: string }
+    if (ctor.componentName) return ctor.componentName
+    // Last resort — use the entry's `name`, mirroring `View.getId()`'s
+    // fallback. The renderer surfaces a "component not registered" error
+    // when the registry doesn't carry it.
+    return this._name
+  }
+
+  /**
+   * Builds the wire meta with `entryType: 'component'` plus the
+   * registered component-name lookup key. Inherits `value`, `label`,
+   * chrome, and `_formatted` from `Entry.toMeta` — the renderer wraps
+   * the user component in `<EntryShell>` for label / helperText / tooltip
+   * / copyable parity with every other entry leaf.
+   */
+  override toMeta(ctx?: RenderContext): EntryMeta & { component: string } {
+    const meta = super.toMeta(ctx) as EntryMeta
+    return { ...meta, component: this.getComponentName() }
+  }
+}