@pilotiq/pilotiq 0.1.0

package/src/fields/SelectField.test.ts

@@ -0,0 +1,192 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { SelectField } from './SelectField.js'
+import { TextField } from './TextField.js'
+
+describe('SelectField', () => {
+  it('emits fieldType "select"', async () => {
+    const meta = await SelectField.make('country').toMeta()
+    assert.equal(meta.fieldType, 'select')
+  })
+
+  describe('createOptionForm', () => {
+    it('bare SelectField emits no createOption slot', async () => {
+      const meta = await SelectField.make('categoryId').options([
+        { value: '1', label: 'News' },
+      ]).toMeta()
+      assert.equal('createOption' in meta, false)
+    })
+
+    it('createOptionForm without createOptionUsing throws at meta-build', async () => {
+      const f = SelectField.make('categoryId')
+        .options([])
+        .createOptionForm([TextField.make('name')])
+      await assert.rejects(
+        () => f.toMeta(),
+        /createOptionForm\(\) requires createOptionUsing\(handler\)/,
+      )
+    })
+
+    it('emits createOption slot with formId + schema when fully configured', async () => {
+      const meta = await SelectField.make('categoryId')
+        .options([])
+        .createOptionForm([
+          TextField.make('name'),
+          TextField.make('slug'),
+        ])
+        .createOptionUsing(async ({ name }) => ({
+          value: 'new-id',
+          label: String(name),
+        }))
+        .toMeta()
+
+      const slot = (meta as { createOption?: { formId: string; schema: unknown[]; url?: string } }).createOption
+      assert.ok(slot, 'createOption slot should be present')
+      assert.equal(slot.formId, 'categoryId_create-option')
+      assert.equal(Array.isArray(slot.schema), true)
+      assert.equal(slot.schema.length, 2)
+      // url is filled in by the walker — absent at this layer
+      assert.equal(slot.url, undefined)
+    })
+
+    it('hasCreateOption reflects configuration', () => {
+      const off = SelectField.make('a').options([])
+      const on  = SelectField.make('a').options([])
+        .createOptionForm([TextField.make('name')])
+      assert.equal(off.hasCreateOption(), false)
+      assert.equal(on.hasCreateOption(), true)
+    })
+
+    it('child schema resolves with parent ctx — values flow through', async () => {
+      const f = SelectField.make('categoryId')
+        .options([])
+        .createOptionForm([TextField.make('name').default('seeded')])
+        .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+
+      const meta = await f.toMeta({ values: { irrelevant: 'parent' } })
+      const slot = (meta as { createOption?: { schema: Array<{ defaultValue?: string }> } }).createOption
+      assert.ok(slot)
+      // The child TextField resolved through its own toMeta — defaultValue
+      // flows into FieldMeta.defaultValue (string field). Not asserting the
+      // exact key (TextField may stamp `defaultValue` or not), but the
+      // schema array has length 1 with the right name.
+      assert.equal(slot.schema.length, 1)
+      assert.equal((slot.schema[0] as { name?: string }).name, 'name')
+    })
+
+    describe('createOptionAuthorize', () => {
+      it('default visibility is true (slot stamped)', async () => {
+        const meta = await SelectField.make('a').options([])
+          .createOptionForm([TextField.make('name')])
+          .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+          .toMeta()
+        assert.ok((meta as { createOption?: unknown }).createOption)
+      })
+
+      it('boolean false suppresses the slot', async () => {
+        const meta = await SelectField.make('a').options([])
+          .createOptionForm([TextField.make('name')])
+          .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+          .createOptionAuthorize(false)
+          .toMeta()
+        assert.equal('createOption' in meta, false)
+      })
+
+      it('boolean true keeps the slot', async () => {
+        const meta = await SelectField.make('a').options([])
+          .createOptionForm([TextField.make('name')])
+          .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+          .createOptionAuthorize(true)
+          .toMeta()
+        assert.ok((meta as { createOption?: unknown }).createOption)
+      })
+
+      it('callback rule sees ctx.user', async () => {
+        let seenUser: unknown = undefined
+        const meta = await SelectField.make('a').options([])
+          .createOptionForm([TextField.make('name')])
+          .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+          .createOptionAuthorize((ctx) => { seenUser = ctx.user; return true })
+          .toMeta({ user: { id: 42 } })
+        assert.deepEqual(seenUser, { id: 42 })
+        assert.ok((meta as { createOption?: unknown }).createOption)
+      })
+
+      it('callback returning false suppresses the slot', async () => {
+        const meta = await SelectField.make('a').options([])
+          .createOptionForm([TextField.make('name')])
+          .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+          .createOptionAuthorize(() => false)
+          .toMeta()
+        assert.equal('createOption' in meta, false)
+      })
+
+      it('throwing rule fails CLOSED (slot suppressed)', async () => {
+        const meta = await SelectField.make('a').options([])
+          .createOptionForm([TextField.make('name')])
+          .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+          .createOptionAuthorize(() => { throw new Error('boom') })
+          .toMeta()
+        assert.equal('createOption' in meta, false)
+      })
+
+      it('async callback resolves correctly', async () => {
+        const meta = await SelectField.make('a').options([])
+          .createOptionForm([TextField.make('name')])
+          .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+          .createOptionAuthorize(async () => true)
+          .toMeta()
+        assert.ok((meta as { createOption?: unknown }).createOption)
+      })
+    })
+
+    describe('withCreateOptionUrl', () => {
+      it('round-trips via getCreateOptionUrl', () => {
+        const f = SelectField.make('a').withCreateOptionUrl('/p/_form/x/create-option/a')
+        assert.equal(f.getCreateOptionUrl(), '/p/_form/x/create-option/a')
+      })
+
+      it('emits url into createOption slot when set', async () => {
+        const meta = await SelectField.make('a').options([])
+          .createOptionForm([TextField.make('name')])
+          .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+          .withCreateOptionUrl('/admin/things/_form/parent/create-option/a')
+          .toMeta()
+        const slot = (meta as { createOption?: { url?: string } }).createOption!
+        assert.equal(slot.url, '/admin/things/_form/parent/create-option/a')
+      })
+
+      it('omits url key when no walker has stamped it', async () => {
+        const meta = await SelectField.make('a').options([])
+          .createOptionForm([TextField.make('name')])
+          .createOptionUsing(async () => ({ value: '1', label: 'x' }))
+          .toMeta()
+        const slot = (meta as { createOption?: { url?: string } }).createOption!
+        assert.equal('url' in slot, false)
+      })
+    })
+
+    describe('accessors', () => {
+      it('getCreateOptionForm / Handler / Authorize round-trip', () => {
+        const fields    = [TextField.make('name')]
+        const handler   = async () => ({ value: '1', label: 'x' })
+        const authorize = () => true
+        const f = SelectField.make('a')
+          .createOptionForm(fields)
+          .createOptionUsing(handler)
+          .createOptionAuthorize(authorize)
+        assert.equal(f.getCreateOptionForm(), fields)
+        assert.equal(f.getCreateOptionHandler(), handler)
+        assert.equal(f.getCreateOptionAuthorize(), authorize)
+      })
+
+      it('accessors return undefined when not set', () => {
+        const f = SelectField.make('a')
+        assert.equal(f.getCreateOptionForm(), undefined)
+        assert.equal(f.getCreateOptionHandler(), undefined)
+        assert.equal(f.getCreateOptionAuthorize(), undefined)
+      })
+    })
+  })
+})

package/src/fields/SelectField.ts

@@ -0,0 +1,235 @@
+import { Field, type FieldMeta } from './Field.js'
+import {
+  resolveOptions,
+  disableOptionsTakenInSiblings,
+  type OptionsResolver,
+  type SelectOption,
+} from './optionsResolver.js'
+import type { Element, ElementMeta } from '../schema/Element.js'
+import { resolveSchema, type RenderContext } from '../schema/resolveSchema.js'
+import type {
+  ActionVisibilityContext,
+  VisibilityRule,
+} from '../actions/Action.js'
+
+// Re-export for back-compat — earlier code imported these directly from
+// SelectField. New code should prefer `fields/optionsResolver.ts`.
+export type { OptionsResolver, SelectOption }
+
+/** The new option produced by `createOptionUsing(fn)`. Returns the
+ *  `value` to post back to the parent form and the `label` to display
+ *  in the option list. The handler is user-supplied — pilotiq does not
+ *  auto-create against any model. */
+export interface CreateOptionResult {
+  value: string
+  label: string
+}
+
+/** Server-side handler for `SelectField.createOptionUsing`. Receives the
+ *  modal form's coerced + validated values and the parent form's
+ *  RenderContext (so `ctx.user` etc. are available). Returns the new
+ *  option synchronously or via Promise. Throwing surfaces as a 500 with
+ *  the message in the response body. */
+export type CreateOptionHandler = (
+  values: Record<string, unknown>,
+  ctx:    RenderContext,
+) => CreateOptionResult | Promise<CreateOptionResult>
+
+/** Wire-shape carried on `SelectFieldMeta.createOption` when the field
+ *  has opted into inline create. `url` is filled in by
+ *  `tagSelectCreateOptionUrls` at page-data time; absent when the field
+ *  has no `createOptionForm` set or the authorize rule returned false. */
+export interface CreateOptionMeta {
+  /** Sub-form id, deterministic so the renderer can target it without a
+   *  server round-trip. Format: `${parentFormId}_create-option_${fieldName}`,
+   *  but the parent formId isn't known here — the field just emits a
+   *  formId derived from its own name. The walker rewrites this when it
+   *  has the parent in scope. */
+  formId: string
+  /** Resolved meta for the `createOptionForm` children. Same shape as
+   *  any other element subtree on the wire. */
+  schema: ElementMeta[]
+  /** POST endpoint stamped by `tagSelectCreateOptionUrls` walker. When
+   *  absent, the renderer skips mounting the "+" trigger (no endpoint
+   *  configured for the parent's scope). */
+  url?:   string
+}
+
+export class SelectField extends Field {
+  private _options: SelectOption[] | OptionsResolver = []
+
+  /** Element subtree that renders inside the inline-create modal.
+   *  Resolved at meta-build time via `Promise.all(toMeta)` so dependent
+   *  options and reactive visibility see the parent form's
+   *  `RenderContext`. */
+  private _createOptionForm?:      Element[]
+  /** Server-side handler that returns the new option. Required when
+   *  `createOptionForm` is set — meta-build throws otherwise to catch
+   *  the configuration error early instead of at first click. */
+  private _createOptionHandler?:   CreateOptionHandler
+  /** Visibility rule for the "+" trigger. Default: visible. The
+   *  endpoint re-evaluates the same rule server-side so a tampered
+   *  client can't bypass. Does NOT auto-inherit any `Resource.canCreate` —
+   *  the option being created is rarely the same model as the parent
+   *  form's record. */
+  private _createOptionAuthorize?: VisibilityRule
+  /** POST endpoint stamped at page-data time by `tagSelectCreateOptionUrls`.
+   *  Field-instance state (parallel to `Form.withStateUrl`); read by
+   *  `toMeta` and emitted into the `createOption.url` slot. Absent ⇒ no
+   *  walker has run yet ⇒ renderer skips the trigger. */
+  private _createOptionUrl?: string
+
+  private constructor(name: string) {
+    super(name, 'select')
+  }
+
+  static make(name: string): SelectField {
+    return new SelectField(name)
+  }
+
+  /**
+   * Static option list, or a resolver function for dependent options.
+   * The function form receives `{ $get, $set, record, user, values }`
+   * and runs every resolve — server-canonical, so it's safe to read
+   * from a database.
+   */
+  options(opts: SelectOption[] | OptionsResolver): this {
+    this._options = opts
+    return this
+  }
+
+  /**
+   * Returns the static option array. Returns the empty array when
+   * options are configured as a function — callers wanting the
+   * resolved list should go through `toMeta(ctx)`.
+   */
+  getOptions(): SelectOption[] {
+    return Array.isArray(this._options) ? this._options : []
+  }
+
+  /** Whether options are configured as a (potentially async) resolver. */
+  hasDynamicOptions(): boolean {
+    return typeof this._options === 'function'
+  }
+
+  /**
+   * Inline create-option modal. When set, the rendered SelectField
+   * grows a "+" trigger that opens a Dialog hosting the supplied
+   * sub-form. Submitting POSTs to a scope-derived endpoint that runs
+   * `createOptionUsing` and returns `{ value, label }` for the new
+   * option. The new option is appended to the local options state and
+   * selected; no parent-form roundtrip required.
+   *
+   * Pair with `createOptionUsing(fn)` — both are required for the
+   * trigger to mount. Optionally gate visibility with
+   * `createOptionAuthorize(rule)`.
+   *
+   * Two call shapes:
+   * - Bare array: `createOptionForm([TextField.make('name'), …])`
+   * - Builder fn: `createOptionForm(form => form.schema([…]))` —
+   *   reserved; v1 accepts the array form only.
+   */
+  createOptionForm(elements: Element[]): this {
+    this._createOptionForm = elements
+    return this
+  }
+
+  /** Server-side handler called when the modal form submits. Receives
+   *  coerced + validated values and the parent form's `RenderContext`.
+   *  Returns the new `{ value, label }` option. Throwing surfaces as a
+   *  500 to the modal — typical use is to wrap a model `.create()` and
+   *  format a label. */
+  createOptionUsing(handler: CreateOptionHandler): this {
+    this._createOptionHandler = handler
+    return this
+  }
+
+  /** Visibility gate on the "+" trigger. Same shape as
+   *  `Action.visible / .authorize`. Default: visible. Server re-runs
+   *  the same predicate so URL access can't bypass. */
+  createOptionAuthorize(rule: VisibilityRule): this {
+    this._createOptionAuthorize = rule
+    return this
+  }
+
+  /** True when the field has opted into inline create. */
+  hasCreateOption(): boolean {
+    return this._createOptionForm !== undefined
+  }
+
+  /** Internal accessor used by the route handler at request time. */
+  getCreateOptionForm(): Element[] | undefined { return this._createOptionForm }
+  getCreateOptionHandler(): CreateOptionHandler | undefined { return this._createOptionHandler }
+  getCreateOptionAuthorize(): VisibilityRule | undefined { return this._createOptionAuthorize }
+
+  /** Stamped by `tagSelectCreateOptionUrls` at page-data time. Mirrors
+   *  the `Form.withStateUrl` / `Table.withReorderUrl` pattern. */
+  withCreateOptionUrl(url: string): this {
+    this._createOptionUrl = url
+    return this
+  }
+  getCreateOptionUrl(): string | undefined { return this._createOptionUrl }
+
+  override async toMeta(ctx?: RenderContext): Promise<FieldMeta & { options: SelectOption[]; createOption?: CreateOptionMeta }> {
+    const base    = this.buildMeta(ctx)
+    const options = disableOptionsTakenInSiblings(
+      await resolveOptions(this._options, ctx, this.name),
+      this.shouldDisableOptionsTakenInSiblings(),
+      this.name,
+      ctx,
+    )
+
+    const createOption = await this.buildCreateOptionMeta(ctx)
+
+    return {
+      ...base,
+      options,
+      ...(createOption ? { createOption } : {}),
+    }
+  }
+
+  /** Resolve the createOption slot. Returns undefined when not
+   *  configured OR when the authorize rule rejects. Throws when the
+   *  form is set without a handler — caught at meta-build to surface
+   *  the config error during dev rather than at first click. */
+  private async buildCreateOptionMeta(ctx?: RenderContext): Promise<CreateOptionMeta | undefined> {
+    if (this._createOptionForm === undefined) return undefined
+    if (this._createOptionHandler === undefined) {
+      throw new Error(
+        `SelectField '${this.name}': createOptionForm() requires createOptionUsing(handler) to be set. ` +
+        `Without a handler the modal submit has no destination.`
+      )
+    }
+
+    const visible = await evalCreateOptionAuthorize(this._createOptionAuthorize, ctx)
+    if (!visible) return undefined
+
+    const schema = await resolveSchema(this._createOptionForm, ctx ?? {})
+
+    return {
+      formId: `${this.name}_create-option`,
+      schema,
+      ...(this._createOptionUrl !== undefined ? { url: this._createOptionUrl } : {}),
+    }
+  }
+}
+
+/** Evaluate the authorize rule. Mirrors `Action.evaluate` posture — a
+ *  thrown rule is treated as fail-CLOSED (visible: false) so an
+ *  in-progress predicate change can't accidentally expose the trigger. */
+async function evalCreateOptionAuthorize(
+  rule: VisibilityRule | undefined,
+  ctx:  RenderContext | undefined,
+): Promise<boolean> {
+  if (rule === undefined) return true
+  if (typeof rule !== 'function') return rule
+  const visCtx: ActionVisibilityContext = {}
+  if (ctx?.record !== undefined) visCtx.record = ctx.record
+  if (ctx?.user   !== undefined) visCtx.user   = ctx.user
+  if (ctx?.values !== undefined) visCtx.values = ctx.values
+  try {
+    return await rule(visCtx)
+  } catch {
+    return false
+  }
+}

package/src/fields/SliderField.test.ts

@@ -0,0 +1,50 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { SliderField, Slider } from './SliderField.js'
+import { coerceFormValues } from '../elements/dispatchForm.js'
+
+describe('SliderField', () => {
+  it('emits fieldType "slider"', () => {
+    const meta = SliderField.make('rating').toMeta()
+    assert.equal(meta.fieldType, 'slider')
+  })
+
+  it('exports an alias `Slider`', () => {
+    assert.equal(Slider, SliderField)
+  })
+
+  it('emits min/max/step on meta', () => {
+    const meta = SliderField.make('rating').min(0).max(5).step(0.5).toMeta()
+    assert.equal(meta['min'],  0)
+    assert.equal(meta['max'],  5)
+    assert.equal(meta['step'], 0.5)
+  })
+
+  it('defaults min=0, max=100, step=1', () => {
+    const meta = SliderField.make('x').toMeta()
+    assert.equal(meta['min'],  0)
+    assert.equal(meta['max'],  100)
+    assert.equal(meta['step'], 1)
+  })
+
+  it('emits showValue when set', () => {
+    const meta = SliderField.make('x').showValue().toMeta()
+    assert.equal(meta['showValue'], true)
+  })
+
+  it('omits showValue by default', () => {
+    const meta = SliderField.make('x').toMeta()
+    assert.equal('showValue' in meta, false)
+  })
+
+  it('coerces string body to number via the slider branch', () => {
+    const out = coerceFormValues([SliderField.make('rating')], { rating: '3.5' })
+    assert.equal(out['rating'], 3.5)
+  })
+
+  it('empty body → null', () => {
+    const out = coerceFormValues([SliderField.make('rating')], { rating: '' })
+    assert.equal(out['rating'], null)
+  })
+})

package/src/fields/SliderField.ts

@@ -0,0 +1,53 @@
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Numeric slider. `min`, `max` required at config time (we don't
+ * fall back to 0/100 silently — most use cases have meaningful bounds
+ * and a forgotten `.min()` should surface fast). `step` defaults to 1.
+ *
+ * Value coerces through the same path as `NumberField` — we declare
+ * `fieldType: 'slider'` for the renderer dispatch but `coerceFormValues`
+ * routes both through the number branch.
+ */
+export class SliderField extends Field {
+  private _min = 0
+  private _max = 100
+  private _step = 1
+  private _showValue = false
+
+  private constructor(name: string) {
+    super(name, 'slider')
+  }
+
+  static make(name: string): SliderField {
+    return new SliderField(name)
+  }
+
+  min(n: number): this  { this._min  = n; return this }
+  max(n: number): this  { this._max  = n; return this }
+  step(n: number): this { this._step = n; return this }
+
+  /** Display the current numeric value next to the slider. */
+  showValue(value: boolean = true): this {
+    this._showValue = value
+    return this
+  }
+
+  getMin(): number { return this._min }
+  getMax(): number { return this._max }
+  getStep(): number { return this._step }
+  isShowingValue(): boolean { return this._showValue }
+
+  override toMeta(ctx?: RenderContext): FieldMeta {
+    return {
+      ...this.buildMeta(ctx),
+      min:  this._min,
+      max:  this._max,
+      step: this._step,
+      ...(this._showValue ? { showValue: true } : {}),
+    }
+  }
+}
+
+export const Slider = SliderField

package/src/fields/SlugField.ts

@@ -0,0 +1,24 @@
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+export class SlugField extends Field {
+  private _from?: string
+
+  private constructor(name: string) {
+    super(name, 'slug')
+  }
+
+  static make(name: string): SlugField {
+    return new SlugField(name)
+  }
+
+  from(field: string): this { this._from = field; return this }
+  getFrom(): string | undefined { return this._from }
+
+  override toMeta(ctx?: RenderContext): FieldMeta {
+    return {
+      ...this.buildMeta(ctx),
+      ...(this._from ? { from: this._from } : {}),
+    }
+  }
+}