@pilotiq/pilotiq 0.1.0

package/src/fields/TagsInputField.test.ts

@@ -0,0 +1,154 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { TagsInputField, TagsInput } from './TagsInputField.js'
+
+describe('TagsInputField', () => {
+  it('emits fieldType "tagsInput"', async () => {
+    const meta = await TagsInputField.make('tags').toMeta()
+    assert.equal(meta.fieldType, 'tagsInput')
+  })
+
+  it('exports an alias `TagsInput`', () => {
+    assert.equal(TagsInput, TagsInputField)
+  })
+
+  it('default suggestions is an empty array', async () => {
+    const meta = await TagsInputField.make('tags').toMeta()
+    assert.deepEqual(meta['suggestions'], [])
+  })
+
+  it('omits separator/splitKeys/reorderable/maxTags by default', async () => {
+    const meta = await TagsInputField.make('tags').toMeta()
+    assert.equal('separator'   in meta, false)
+    assert.equal('splitKeys'   in meta, false)
+    assert.equal('reorderable' in meta, false)
+    assert.equal('maxTags'     in meta, false)
+  })
+
+  describe('suggestions(static array)', () => {
+    it('emits suggestions verbatim', async () => {
+      const meta = await TagsInputField.make('tags')
+        .suggestions(['react', 'vue', 'svelte'])
+        .toMeta()
+      assert.deepEqual(meta['suggestions'], ['react', 'vue', 'svelte'])
+    })
+
+    it('hasDynamicSuggestions is false for static arrays', () => {
+      const f = TagsInputField.make('tags').suggestions(['a'])
+      assert.equal(f.hasDynamicSuggestions(), false)
+      assert.deepEqual(f.getSuggestions(), ['a'])
+    })
+  })
+
+  describe('suggestions(resolver function)', () => {
+    it('runs the resolver against ctx', async () => {
+      const f = TagsInputField.make('tags').suggestions(({ $get }) => {
+        const stack = $get?.('stack') as string | undefined
+        if (stack === 'fe') return ['react', 'vue']
+        return ['node', 'rails']
+      })
+      assert.equal(f.hasDynamicSuggestions(), true)
+      const meta = await f.toMeta({
+        values: { stack: 'fe' },
+        $get:   (n) => ({ stack: 'fe' } as Record<string, unknown>)[n],
+      })
+      assert.deepEqual(meta['suggestions'], ['react', 'vue'])
+    })
+
+    it('async resolver is awaited', async () => {
+      const f = TagsInputField.make('tags').suggestions(async () => {
+        await new Promise(r => setTimeout(r, 1))
+        return ['async']
+      })
+      const meta = await f.toMeta()
+      assert.deepEqual(meta['suggestions'], ['async'])
+    })
+
+    it('thrown resolver returns empty suggestions + console.warn', async () => {
+      const original = console.warn
+      const calls: unknown[] = []
+      console.warn = (...args: unknown[]) => { calls.push(args) }
+      try {
+        const f = TagsInputField.make('broken').suggestions(() => { throw new Error('boom') })
+        const meta = await f.toMeta()
+        assert.deepEqual(meta['suggestions'], [])
+        assert.equal(calls.length, 1)
+      } finally {
+        console.warn = original
+      }
+    })
+  })
+
+  describe('separator', () => {
+    it('emits when set to a non-default char', async () => {
+      const meta = await TagsInputField.make('tags').separator(';').toMeta()
+      assert.equal(meta['separator'], ';')
+    })
+
+    it('emits null when explicitly disabled', async () => {
+      const meta = await TagsInputField.make('tags').separator(null).toMeta()
+      assert.equal(meta['separator'], null)
+    })
+
+    it('omits when left at the default ","', async () => {
+      const meta = await TagsInputField.make('tags').separator(',').toMeta()
+      assert.equal('separator' in meta, false)
+    })
+  })
+
+  describe('splitKeys', () => {
+    it('emits when overridden', async () => {
+      const meta = await TagsInputField.make('tags').splitKeys(['Enter', 'Tab']).toMeta()
+      assert.deepEqual(meta['splitKeys'], ['Enter', 'Tab'])
+    })
+
+    it('omits when left at the default ["Enter"]', async () => {
+      const meta = await TagsInputField.make('tags').splitKeys(['Enter']).toMeta()
+      assert.equal('splitKeys' in meta, false)
+    })
+  })
+
+  describe('reorderable', () => {
+    it('emits true when enabled', async () => {
+      const meta = await TagsInputField.make('tags').reorderable().toMeta()
+      assert.equal(meta['reorderable'], true)
+    })
+
+    it('omits when explicitly disabled', async () => {
+      const meta = await TagsInputField.make('tags').reorderable(false).toMeta()
+      assert.equal('reorderable' in meta, false)
+    })
+  })
+
+  describe('maxTags', () => {
+    it('emits when set', async () => {
+      const meta = await TagsInputField.make('tags').maxTags(5).toMeta()
+      assert.equal(meta['maxTags'], 5)
+    })
+
+    it('clamps to >= 1 and floors fractional values', () => {
+      const a = TagsInputField.make('a').maxTags(0)
+      const b = TagsInputField.make('b').maxTags(3.7)
+      assert.equal(a.getMaxTags(), 1)
+      assert.equal(b.getMaxTags(), 3)
+    })
+  })
+
+  it('participates in cross-field plumbing (default / required / live / helperText)', async () => {
+    const f = TagsInputField.make('tags')
+      .label('Tags')
+      .required()
+      .default(['draft'])
+      .helperText('Press Enter to add')
+      .live()
+      .suggestions(['draft', 'published'])
+    const meta = await f.toMeta()
+    assert.equal(meta.fieldType,        'tagsInput')
+    assert.equal(meta.required,         true)
+    assert.equal(meta.label,            'Tags')
+    assert.equal(meta['helperText'],    'Press Enter to add')
+    assert.equal(meta['live'],          true)
+    assert.deepEqual(meta['defaultValue'], ['draft'])
+  })
+})

package/src/fields/TagsInputField.ts

@@ -0,0 +1,133 @@
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Suggestions resolver. Simpler shape than `OptionsResolver` because
+ * a tag is its own label — the suggestion list is `string[]`, not
+ * `{value,label}[]`. Layer SelectOption-shaped suggestions later if
+ * a real consumer needs label / value to diverge.
+ */
+export type TagsSuggestionsResolver = (ctx: {
+  $get?:   (name: string) => unknown
+  values?: Record<string, unknown>
+  record?: unknown
+  user?:   unknown
+}) => string[] | Promise<string[]>
+
+async function resolveSuggestions(
+  source:    string[] | TagsSuggestionsResolver,
+  ctx:       RenderContext | undefined,
+  fieldName: string,
+): Promise<string[]> {
+  if (Array.isArray(source)) return source
+  try {
+    return await source({
+      ...(ctx?.$get   ? { $get:   ctx.$get   } : {}),
+      ...(ctx?.values ? { values: ctx.values } : {}),
+      ...(ctx?.record !== undefined ? { record: ctx.record } : {}),
+      ...(ctx?.user   !== undefined ? { user:   ctx.user   } : {}),
+    })
+  } catch (err) {
+    console.warn(`[pilotiq] suggestions() resolver for "${fieldName}" threw:`, err)
+    return []
+  }
+}
+
+/**
+ * Free-text multi-tag input. Value is `string[]`. The client renders
+ * pill-shaped chips per committed tag plus a single inline text input;
+ * pressing Enter (or any of `splitKeys`) commits the current draft to
+ * the chip set. Pasting a string containing `separator` splits into
+ * multiple chips at once. Backspace on an empty draft removes the last
+ * chip.
+ *
+ * Wire format mirrors `KeyValue` — the client serializes the chip set
+ * as a JSON string in a single hidden input and `coerceFormValues`
+ * parses it back into `string[]`. Avoids the multi-input-with-same-name
+ * footguns across `application/x-www-form-urlencoded` and
+ * `multipart/form-data` bodies.
+ */
+export class TagsInputField extends Field {
+  private _suggestions: string[] | TagsSuggestionsResolver = []
+  private _separator:   string | null = ','
+  private _splitKeys:   string[] = ['Enter']
+  private _reorderable = false
+  private _maxTags:     number | null = null
+
+  private constructor(name: string) {
+    super(name, 'tagsInput')
+  }
+
+  static make(name: string): TagsInputField {
+    return new TagsInputField(name)
+  }
+
+  suggestions(opts: string[] | TagsSuggestionsResolver): this {
+    this._suggestions = opts
+    return this
+  }
+
+  /**
+   * Single character that splits a pasted string into multiple tags.
+   * Pass `null` to disable paste-splitting; only `splitKeys` then
+   * commits a draft.
+   */
+  separator(char: string | null): this {
+    this._separator = char
+    return this
+  }
+
+  /**
+   * Keys that commit the current draft to the chip set. Defaults to
+   * `['Enter']`. Common addition: `['Enter', 'Tab', ',']`. The
+   * separator char is automatically treated as a split key as well.
+   */
+  splitKeys(keys: string[]): this {
+    this._splitKeys = keys
+    return this
+  }
+
+  /** Allow chip reorder via native HTML5 drag-and-drop. Off by default — most
+   * tag sets are insertion-ordered or alphabetized, and the chip strip is small
+   * enough that drag affordances are noisy when unused. */
+  reorderable(value: boolean = true): this {
+    this._reorderable = value
+    return this
+  }
+
+  /** Cap the chip count. Surfaces to validation-renderer + client guard. */
+  maxTags(n: number): this {
+    this._maxTags = Math.max(1, Math.floor(n))
+    return this
+  }
+
+  hasDynamicSuggestions(): boolean {
+    return typeof this._suggestions === 'function'
+  }
+
+  getSuggestions(): string[] {
+    return Array.isArray(this._suggestions) ? this._suggestions : []
+  }
+
+  getSeparator(): string | null { return this._separator }
+  getSplitKeys(): string[]      { return this._splitKeys }
+  isReorderable(): boolean      { return this._reorderable }
+  getMaxTags(): number | null   { return this._maxTags }
+
+  override async toMeta(ctx?: RenderContext): Promise<FieldMeta> {
+    const base        = this.buildMeta(ctx)
+    const suggestions = await resolveSuggestions(this._suggestions, ctx, this.name)
+    return {
+      ...base,
+      suggestions,
+      ...(this._separator !== ',' ? { separator: this._separator } : {}),
+      ...(this._splitKeys.length !== 1 || this._splitKeys[0] !== 'Enter'
+            ? { splitKeys: this._splitKeys }
+            : {}),
+      ...(this._reorderable ? { reorderable: true } : {}),
+      ...(this._maxTags     ? { maxTags: this._maxTags } : {}),
+    }
+  }
+}
+
+export const TagsInput = TagsInputField

package/src/fields/TextField.ts

@@ -0,0 +1,24 @@
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+export class TextField extends Field {
+  private _maxLength?: number
+
+  private constructor(name: string) {
+    super(name, 'text')
+  }
+
+  static make(name: string): TextField {
+    return new TextField(name)
+  }
+
+  maxLength(n: number): this { this._maxLength = n; return this }
+  getMaxLength(): number | undefined { return this._maxLength }
+
+  override toMeta(ctx?: RenderContext): FieldMeta {
+    return {
+      ...this.buildMeta(ctx),
+      ...(this._maxLength !== undefined ? { maxLength: this._maxLength } : {}),
+    }
+  }
+}

package/src/fields/TextareaField.test.ts

@@ -0,0 +1,58 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { TextareaField } from './TextareaField.js'
+
+describe('TextareaField', () => {
+  it('emits fieldType "textarea" and rows defaulting to 4', () => {
+    const meta = TextareaField.make('bio').toMeta()
+    assert.equal(meta.fieldType, 'textarea')
+    assert.equal(meta['rows'], 4)
+  })
+
+  it('rows(n) overrides the default', () => {
+    const meta = TextareaField.make('bio').rows(10).toMeta()
+    assert.equal(meta['rows'], 10)
+  })
+
+  it('cols(n) emits cols only when set', () => {
+    const off = TextareaField.make('bio').toMeta()
+    const on  = TextareaField.make('bio').cols(40).toMeta()
+    assert.equal(off['cols'], undefined)
+    assert.equal(on['cols'],  40)
+  })
+
+  it('autosize() emits the flag only when called', () => {
+    const off = TextareaField.make('bio').toMeta()
+    const on  = TextareaField.make('bio').autosize().toMeta()
+    assert.equal(off['autosize'], undefined)
+    assert.equal(on['autosize'],  true)
+  })
+
+  it('autosize(false) is a no-op default', () => {
+    const meta = TextareaField.make('bio').autosize(false).toMeta()
+    assert.equal(meta['autosize'], undefined)
+  })
+
+  it('disableGrammarly() emits the flag only when called', () => {
+    const off = TextareaField.make('bio').toMeta()
+    const on  = TextareaField.make('bio').disableGrammarly().toMeta()
+    assert.equal(off['disableGrammarly'], undefined)
+    assert.equal(on['disableGrammarly'],  true)
+  })
+
+  it('the chainables compose with each other and with rows/required', () => {
+    const meta = TextareaField.make('bio')
+      .rows(8)
+      .cols(60)
+      .autosize()
+      .disableGrammarly()
+      .required()
+      .toMeta()
+    assert.equal(meta['rows'],             8)
+    assert.equal(meta['cols'],             60)
+    assert.equal(meta['autosize'],         true)
+    assert.equal(meta['disableGrammarly'], true)
+    assert.equal(meta.required,            true)
+  })
+})

package/src/fields/TextareaField.ts

@@ -0,0 +1,59 @@
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+export class TextareaField extends Field {
+  private _rows = 4
+  private _cols?: number
+  private _autosize = false
+  private _disableGrammarly = false
+
+  private constructor(name: string) {
+    super(name, 'textarea')
+  }
+
+  static make(name: string): TextareaField {
+    return new TextareaField(name)
+  }
+
+  rows(n: number): this { this._rows = n; return this }
+  getRows(): number { return this._rows }
+
+  /**
+   * HTML `cols` attribute on the underlying `<textarea>`. Sets the
+   * visible character width independent of the parent column / span.
+   * Most apps lean on `rows()` + the field's flex layout instead — pass
+   * `cols(n)` only when you need an explicit character-grid width.
+   */
+  cols(n: number): this { this._cols = n; return this }
+  getCols(): number | undefined { return this._cols }
+
+  /**
+   * Auto-grow the textarea so its height matches the typed content (no
+   * scrollbar until `maxHeight`). Implemented in CSS via the existing
+   * `field-sizing-content` utility on `<Textarea>` — `autosize()` simply
+   * keeps the chrome and unsets the explicit `rows` so the browser can
+   * size to content. Off by default to preserve the legacy fixed-height
+   * look on bare `TextareaField.make(...)`.
+   */
+  autosize(v = true): this { this._autosize = v; return this }
+  isAutosize(): boolean { return this._autosize }
+
+  /**
+   * Add `data-gramm="false"` (plus the matching Grammarly extension
+   * disable attributes) so the third-party browser overlay doesn't mount
+   * on this field. Use for sensitive content (slug source, DB queries,
+   * code snippets) where the overlay's UI corrupts cursor placement.
+   */
+  disableGrammarly(v = true): this { this._disableGrammarly = v; return this }
+  isGrammarlyDisabled(): boolean { return this._disableGrammarly }
+
+  override toMeta(ctx?: RenderContext): FieldMeta {
+    return {
+      ...this.buildMeta(ctx),
+      rows: this._rows,
+      ...(this._cols !== undefined ? { cols: this._cols } : {}),
+      ...(this._autosize ? { autosize: true } : {}),
+      ...(this._disableGrammarly ? { disableGrammarly: true } : {}),
+    }
+  }
+}

package/src/fields/ToggleButtonsField.test.ts

@@ -0,0 +1,106 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { ToggleButtonsField, ToggleButtons } from './ToggleButtonsField.js'
+
+describe('ToggleButtonsField', () => {
+  it('emits fieldType "toggleButtons"', async () => {
+    const meta = await ToggleButtonsField.make('priority').toMeta()
+    assert.equal(meta.fieldType, 'toggleButtons')
+  })
+
+  it('exports an alias `ToggleButtons`', () => {
+    assert.equal(ToggleButtons, ToggleButtonsField)
+  })
+
+  it('does NOT emit an `inline` flag (chips are always horizontal)', async () => {
+    const meta = await ToggleButtonsField.make('x').toMeta()
+    assert.equal('inline' in meta, false)
+  })
+
+  describe('options(static array)', () => {
+    it('emits options array verbatim', async () => {
+      const meta = await ToggleButtonsField.make('priority').options([
+        { value: 'low',  label: 'Low' },
+        { value: 'high', label: 'High' },
+      ]).toMeta()
+      assert.deepEqual(meta['options'], [
+        { value: 'low',  label: 'Low' },
+        { value: 'high', label: 'High' },
+      ])
+    })
+
+    it('hasDynamicOptions is false for static arrays', () => {
+      const f = ToggleButtonsField.make('priority').options([{ value: 'a', label: 'A' }])
+      assert.equal(f.hasDynamicOptions(), false)
+    })
+
+    it('getOptions returns the array', () => {
+      const f = ToggleButtonsField.make('priority').options([{ value: 'a', label: 'A' }])
+      assert.deepEqual(f.getOptions(), [{ value: 'a', label: 'A' }])
+    })
+
+    it('options default to [] when never configured', async () => {
+      const meta = await ToggleButtonsField.make('x').toMeta()
+      assert.deepEqual(meta['options'], [])
+    })
+  })
+
+  describe('options(resolver function)', () => {
+    it('runs the resolver against ctx', async () => {
+      const f = ToggleButtonsField.make('plan').options(({ $get }) => {
+        const tier = $get?.('tier') as string | undefined
+        if (tier === 'pro') return [{ value: 'monthly', label: 'Monthly' }]
+        return [{ value: 'free', label: 'Free' }]
+      })
+      assert.equal(f.hasDynamicOptions(), true)
+      const meta = await f.toMeta({
+        values: { tier: 'pro' },
+        $get:   (n) => ({ tier: 'pro' } as Record<string, unknown>)[n],
+      })
+      assert.deepEqual(meta['options'], [{ value: 'monthly', label: 'Monthly' }])
+    })
+
+    it('async resolver is awaited', async () => {
+      const f = ToggleButtonsField.make('items').options(async () => {
+        await new Promise(r => setTimeout(r, 1))
+        return [{ value: 'a', label: 'A' }]
+      })
+      const meta = await f.toMeta()
+      assert.deepEqual(meta['options'], [{ value: 'a', label: 'A' }])
+    })
+
+    it('thrown resolver returns empty options + console.warn', async () => {
+      const original = console.warn
+      const calls: unknown[] = []
+      console.warn = (...args: unknown[]) => { calls.push(args) }
+      try {
+        const f = ToggleButtonsField.make('broken').options(() => { throw new Error('boom') })
+        const meta = await f.toMeta()
+        assert.deepEqual(meta['options'], [])
+        assert.equal(calls.length, 1)
+      } finally {
+        console.warn = original
+      }
+    })
+  })
+
+  it('participates in cross-field plumbing (default / required / live)', async () => {
+    const f = ToggleButtonsField.make('priority')
+      .label('Priority')
+      .required()
+      .default('medium')
+      .live()
+      .options([
+        { value: 'low',    label: 'Low' },
+        { value: 'medium', label: 'Medium' },
+        { value: 'high',   label: 'High' },
+      ])
+    const meta = await f.toMeta()
+    assert.equal(meta.fieldType,    'toggleButtons')
+    assert.equal(meta.required,     true)
+    assert.equal(meta['defaultValue'], 'medium')
+    assert.equal(meta['live'],      true)
+    assert.equal(meta.label,        'Priority')
+  })
+})

package/src/fields/ToggleButtonsField.ts

@@ -0,0 +1,59 @@
+import { Field, type FieldMeta } from './Field.js'
+import {
+  resolveOptions,
+  disableOptionsTakenInSiblings,
+  type OptionsResolver,
+  type SelectOption,
+} from './optionsResolver.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Single-choice field rendered as a horizontal segmented chip group.
+ * Sugar over `RadioField` with the same `OptionsResolver` shape; the
+ * difference is purely visual — `RadioField` paints a vertical (or
+ * `inline:true`) stack of native radios, `ToggleButtonsField` paints
+ * a row of pill-shaped buttons styled like a segmented control.
+ *
+ * Multi-select is intentionally out of scope in v1; reach for
+ * `CheckboxListField` for that.
+ */
+export class ToggleButtonsField extends Field {
+  private _options: SelectOption[] | OptionsResolver = []
+
+  private constructor(name: string) {
+    super(name, 'toggleButtons')
+  }
+
+  static make(name: string): ToggleButtonsField {
+    return new ToggleButtonsField(name)
+  }
+
+  options(opts: SelectOption[] | OptionsResolver): this {
+    this._options = opts
+    return this
+  }
+
+  getOptions(): SelectOption[] {
+    return Array.isArray(this._options) ? this._options : []
+  }
+
+  hasDynamicOptions(): boolean {
+    return typeof this._options === 'function'
+  }
+
+  override async toMeta(ctx?: RenderContext): Promise<FieldMeta> {
+    const base    = this.buildMeta(ctx)
+    const options = disableOptionsTakenInSiblings(
+      await resolveOptions(this._options, ctx, this.name),
+      this.shouldDisableOptionsTakenInSiblings(),
+      this.name,
+      ctx,
+    )
+    return {
+      ...base,
+      options,
+    }
+  }
+}
+
+export const ToggleButtons = ToggleButtonsField

package/src/fields/ToggleField.ts

@@ -0,0 +1,16 @@
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+export class ToggleField extends Field {
+  private constructor(name: string) {
+    super(name, 'toggle')
+  }
+
+  static make(name: string): ToggleField {
+    return new ToggleField(name)
+  }
+
+  override toMeta(ctx?: RenderContext): FieldMeta {
+    return this.buildMeta(ctx)
+  }
+}