@pilotiq/pilotiq 0.1.0

package/src/fields/FileUploadField.test.ts

@@ -0,0 +1,97 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { FileUploadField, FileUpload } from './FileUploadField.js'
+import { coerceFormValues } from '../elements/dispatchForm.js'
+
+describe('FileUploadField', () => {
+  it('emits fieldType "fileUpload"', () => {
+    const meta = FileUploadField.make('cover').toMeta()
+    assert.equal(meta.fieldType, 'fileUpload')
+  })
+
+  it('exports an alias `FileUpload`', () => {
+    assert.equal(FileUpload, FileUploadField)
+  })
+
+  it('default flags: multiple=false, preview=true', () => {
+    const meta = FileUploadField.make('x').toMeta()
+    assert.equal(meta['multiple'], false)
+    assert.equal(meta['preview'],  true)
+  })
+
+  it('emits accept / maxSize / directory only when set', () => {
+    const a = FileUploadField.make('x').toMeta()
+    assert.equal('accept'    in a, false)
+    assert.equal('maxSize'   in a, false)
+    assert.equal('directory' in a, false)
+
+    const b = FileUploadField.make('x')
+      .accept(['image/png', 'image/jpeg'])
+      .maxSize(5_000_000)
+      .directory('articles/covers')
+      .toMeta()
+    assert.deepEqual(b['accept'], ['image/png', 'image/jpeg'])
+    assert.equal(b['maxSize'], 5_000_000)
+    assert.equal(b['directory'], 'articles/covers')
+  })
+
+  it('multiple() flips to multi-file mode', () => {
+    const meta = FileUploadField.make('x').multiple().toMeta()
+    assert.equal(meta['multiple'], true)
+  })
+
+  it('preview(false) suppresses thumbnail', () => {
+    const meta = FileUploadField.make('x').preview(false).toMeta()
+    assert.equal(meta['preview'], false)
+  })
+
+  it('emits uploadUrl from RenderContext', () => {
+    const meta = FileUploadField.make('x').toMeta({ uploadUrl: '/admin/_uploads' })
+    assert.equal(meta['uploadUrl'], '/admin/_uploads')
+  })
+
+  it('omits uploadUrl when ctx does not supply one', () => {
+    const meta = FileUploadField.make('x').toMeta()
+    assert.equal('uploadUrl' in meta, false)
+  })
+
+  describe('coerceFormValues', () => {
+    it('passes URL string through (single mode)', () => {
+      const out = coerceFormValues(
+        [FileUploadField.make('cover')],
+        { cover: '/uploads/abc.png' },
+      )
+      assert.equal(out['cover'], '/uploads/abc.png')
+    })
+
+    it('passes string[] through (multi mode)', () => {
+      const out = coerceFormValues(
+        [FileUploadField.make('files').multiple()],
+        { files: ['/uploads/a.png', '/uploads/b.png'] },
+      )
+      assert.deepEqual(out['files'], ['/uploads/a.png', '/uploads/b.png'])
+    })
+
+    it('decodes JSON-array string into string[]', () => {
+      const out = coerceFormValues(
+        [FileUploadField.make('files').multiple()],
+        { files: '["/uploads/a.png","/uploads/b.png"]' },
+      )
+      assert.deepEqual(out['files'], ['/uploads/a.png', '/uploads/b.png'])
+    })
+
+    it('empty string → null', () => {
+      const out = coerceFormValues(
+        [FileUploadField.make('cover')],
+        { cover: '' },
+      )
+      assert.equal(out['cover'], null)
+    })
+
+    it('missing key → null', () => {
+      const out = coerceFormValues([FileUploadField.make('cover')], {})
+      assert.equal(out['cover'], null)
+    })
+  })
+})

package/src/fields/FileUploadField.ts

@@ -0,0 +1,71 @@
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * File upload. The field stores the resolved upload's URL string —
+ * `string` for single-file mode, `string[]` for multi.
+ *
+ * The actual upload mechanism is a separate POST endpoint. The renderer
+ * picks a file → POSTs multipart to the panel's `_uploads` route → the
+ * adapter (`localUpload` / S3 / etc.) writes the file → the route
+ * returns `{ ok, url }` → the renderer stashes that URL in the form
+ * state. On submit, the field value is just that URL.
+ */
+export class FileUploadField extends Field {
+  private _accept?: string[]
+  private _maxSize?: number
+  private _multiple = false
+  private _preview = true
+  private _directory?: string
+
+  private constructor(name: string) {
+    super(name, 'fileUpload')
+  }
+
+  static make(name: string): FileUploadField {
+    return new FileUploadField(name)
+  }
+
+  /** Restrict accepted MIME types — passed verbatim to the file input + validated server-side. */
+  accept(mimes: string[]): this { this._accept = mimes; return this }
+
+  /** Max upload size in bytes. Server-side enforced; client-side surfaces the limit too. */
+  maxSize(bytes: number): this { this._maxSize = bytes; return this }
+
+  /** Switch to multi-file mode. Value becomes `string[]` instead of `string`. */
+  multiple(value: boolean = true): this { this._multiple = value; return this }
+
+  /** Show a thumbnail / file-name preview when the value is set. Default true. */
+  preview(value: boolean = true): this { this._preview = value; return this }
+
+  /**
+   * Sub-directory hint passed to the adapter. Adapters honor this
+   * differently (`localUpload` writes to `<root>/<directory>/...`,
+   * S3 prepends to the key, etc.).
+   */
+  directory(d: string): this { this._directory = d; return this }
+
+  getAccept(): string[] | undefined { return this._accept }
+  getMaxSize(): number | undefined { return this._maxSize }
+  isMultiple(): boolean { return this._multiple }
+  hasPreview(): boolean { return this._preview }
+  getDirectory(): string | undefined { return this._directory }
+
+  override toMeta(ctx?: RenderContext): FieldMeta {
+    return {
+      ...this.buildMeta(ctx),
+      multiple: this._multiple,
+      preview:  this._preview,
+      ...(this._accept   ? { accept: this._accept }    : {}),
+      ...(this._maxSize !== undefined ? { maxSize: this._maxSize } : {}),
+      ...(this._directory ? { directory: this._directory } : {}),
+      // `uploadUrl` is stamped via RenderContext by the page-data
+      // builders. Without it the renderer falls back to a clear error
+      // ("no upload URL configured"); the route handler (and therefore
+      // the URL) is registered alongside the panel.
+      ...(ctx?.uploadUrl ? { uploadUrl: ctx.uploadUrl } : {}),
+    }
+  }
+}
+
+export const FileUpload = FileUploadField

package/src/fields/HiddenField.test.ts

@@ -0,0 +1,27 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { HiddenField, Hidden } from './HiddenField.js'
+
+describe('HiddenField', () => {
+  it('emits fieldType "hidden"', () => {
+    const meta = HiddenField.make('source').toMeta()
+    assert.equal(meta.fieldType, 'hidden')
+    assert.equal(meta.name,      'source')
+  })
+
+  it('exports an alias `Hidden`', () => {
+    assert.equal(Hidden, HiddenField)
+  })
+
+  it('supports default value', () => {
+    const meta = HiddenField.make('csrf').default('xyz').toMeta()
+    assert.equal(meta.defaultValue, 'xyz')
+  })
+
+  it('inherits the cross-field plumbing (label, etc.)', () => {
+    const meta = HiddenField.make('x').label('Internal').toMeta()
+    // label always emits, even though renderer ignores it for hidden type
+    assert.equal(meta.label, 'Internal')
+  })
+})

package/src/fields/HiddenField.ts

@@ -0,0 +1,28 @@
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * A non-rendered field that round-trips a value through the form
+ * without exposing it to the user. Useful for source-attribution
+ * stamps, CSRF round-trips, computed values that the server needs to
+ * see, etc.
+ *
+ * Distinct from `Form`'s built-in `_formId` discriminator — that's
+ * framework chrome. `Hidden` is for app-level state.
+ */
+export class HiddenField extends Field {
+  private constructor(name: string) {
+    super(name, 'hidden')
+  }
+
+  static make(name: string): HiddenField {
+    return new HiddenField(name)
+  }
+
+  override toMeta(ctx?: RenderContext): FieldMeta {
+    return this.buildMeta(ctx)
+  }
+}
+
+/** Public alias so callers can write `Hidden.make()`. */
+export const Hidden = HiddenField

package/src/fields/KeyValueField.test.ts

@@ -0,0 +1,105 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { KeyValueField, KeyValue } from './KeyValueField.js'
+import { coerceFormValues } from '../elements/dispatchForm.js'
+
+describe('KeyValueField', () => {
+  it('emits fieldType "keyValue"', () => {
+    const meta = KeyValueField.make('headers').toMeta()
+    assert.equal(meta.fieldType, 'keyValue')
+  })
+
+  it('exports an alias `KeyValue`', () => {
+    assert.equal(KeyValue, KeyValueField)
+  })
+
+  it('emits keyLabel/valueLabel/addLabel defaults', () => {
+    const meta = KeyValueField.make('x').toMeta()
+    assert.equal(meta['keyLabel'],   'Key')
+    assert.equal(meta['valueLabel'], 'Value')
+    assert.equal(meta['addLabel'],   'Add row')
+  })
+
+  it('emits custom labels when set', () => {
+    const meta = KeyValueField.make('x')
+      .keyLabel('Header')
+      .valueLabel('Setting')
+      .addLabel('Add header')
+      .toMeta()
+    assert.equal(meta['keyLabel'],   'Header')
+    assert.equal(meta['valueLabel'], 'Setting')
+    assert.equal(meta['addLabel'],   'Add header')
+  })
+
+  it('emits reorderable only when set', () => {
+    assert.equal('reorderable' in KeyValueField.make('x').toMeta(),                      false)
+    assert.equal(KeyValueField.make('x').reorderable().toMeta()['reorderable'],          true)
+  })
+
+  describe('coerceFormValues', () => {
+    it('parses JSON string body to object', () => {
+      const out = coerceFormValues(
+        [KeyValueField.make('headers')],
+        { headers: '{"X-Source":"admin","X-Trace":"abc"}' },
+      )
+      assert.deepEqual(out['headers'], { 'X-Source': 'admin', 'X-Trace': 'abc' })
+    })
+
+    it('passes already-object values through', () => {
+      const out = coerceFormValues(
+        [KeyValueField.make('headers')],
+        { headers: { foo: 'bar' } },
+      )
+      assert.deepEqual(out['headers'], { foo: 'bar' })
+    })
+
+    it('filters out the empty placeholder row { "": "" }', () => {
+      const out = coerceFormValues(
+        [KeyValueField.make('headers')],
+        { headers: '{"":"","real":"value"}' },
+      )
+      assert.deepEqual(out['headers'], { real: 'value' })
+    })
+
+    it('preserves rows with empty value but non-empty key', () => {
+      const out = coerceFormValues(
+        [KeyValueField.make('h')],
+        { h: '{"key":""}' },
+      )
+      assert.deepEqual(out['h'], { key: '' })
+    })
+
+    it('empty string body → {}', () => {
+      const out = coerceFormValues(
+        [KeyValueField.make('h')],
+        { h: '' },
+      )
+      assert.deepEqual(out['h'], {})
+    })
+
+    it('null body → {}', () => {
+      const out = coerceFormValues(
+        [KeyValueField.make('h')],
+        { h: null },
+      )
+      assert.deepEqual(out['h'], {})
+    })
+
+    it('malformed JSON → {}', () => {
+      const out = coerceFormValues(
+        [KeyValueField.make('h')],
+        { h: '{not-json' },
+      )
+      assert.deepEqual(out['h'], {})
+    })
+
+    it('stringifies non-string values', () => {
+      const out = coerceFormValues(
+        [KeyValueField.make('h')],
+        { h: { count: 5 } },
+      )
+      assert.deepEqual(out['h'], { count: '5' })
+    })
+  })
+})

package/src/fields/KeyValueField.ts

@@ -0,0 +1,55 @@
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Edits a flat `Record<string, string>`. Server-canonical shape:
+ *
+ *   { "X-Source": "admin", "X-Trace": "abc123" }
+ *
+ * The client serializes the map as a JSON string in a hidden input on
+ * submit; `coerceFormValues` parses it back into an object. Keeping
+ * the wire-format JSON dodges the bracket-notation parser footguns
+ * across `application/x-www-form-urlencoded` and `multipart/form-data`.
+ */
+export class KeyValueField extends Field {
+  private _keyLabel = 'Key'
+  private _valueLabel = 'Value'
+  private _addLabel = 'Add row'
+  private _reorderable = false
+
+  private constructor(name: string) {
+    super(name, 'keyValue')
+  }
+
+  static make(name: string): KeyValueField {
+    return new KeyValueField(name)
+  }
+
+  keyLabel(label: string): this   { this._keyLabel = label; return this }
+  valueLabel(label: string): this { this._valueLabel = label; return this }
+  addLabel(label: string): this   { this._addLabel = label; return this }
+
+  /**
+   * Show up/down arrow controls per row. Drag-and-drop ordering not
+   * shipped in v1 — call back to up/down only when the persisted
+   * order matters.
+   */
+  reorderable(value: boolean = true): this { this._reorderable = value; return this }
+
+  getKeyLabel(): string { return this._keyLabel }
+  getValueLabel(): string { return this._valueLabel }
+  getAddLabel(): string { return this._addLabel }
+  isReorderable(): boolean { return this._reorderable }
+
+  override toMeta(ctx?: RenderContext): FieldMeta {
+    return {
+      ...this.buildMeta(ctx),
+      keyLabel:    this._keyLabel,
+      valueLabel:  this._valueLabel,
+      addLabel:    this._addLabel,
+      ...(this._reorderable ? { reorderable: true } : {}),
+    }
+  }
+}
+
+export const KeyValue = KeyValueField

package/src/fields/MarkdownField.test.ts

@@ -0,0 +1,167 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  MarkdownField,
+  DEFAULT_MARKDOWN_TOOLBAR,
+} from './MarkdownField.js'
+
+describe('MarkdownField', () => {
+  it('emits fieldType "markdown"', () => {
+    const meta = MarkdownField.make('body').toMeta()
+    assert.equal(meta.fieldType, 'markdown')
+  })
+
+  it('defaults to the full toolbar', () => {
+    const meta = MarkdownField.make('body').toMeta({ hasUploadAdapter: true })
+    assert.deepEqual(
+      meta['toolbarButtons'],
+      [...DEFAULT_MARKDOWN_TOOLBAR],
+    )
+  })
+
+  it('omits minHeight/maxHeight/fileAttachments* by default', () => {
+    const meta = MarkdownField.make('body').toMeta()
+    assert.equal('minHeight' in meta, false)
+    assert.equal('maxHeight' in meta, false)
+    assert.equal('fileAttachmentsDirectory'  in meta, false)
+    assert.equal('fileAttachmentsVisibility' in meta, false)
+  })
+
+  describe('toolbarButtons()', () => {
+    it('replaces the toolbar entirely with the given list', () => {
+      const meta = MarkdownField.make('body')
+        .toolbarButtons(['bold', 'italic', 'link'])
+        .toMeta({ hasUploadAdapter: true })
+      assert.deepEqual(meta['toolbarButtons'], ['bold', 'italic', 'link'])
+    })
+
+    it('preserves order from the user-supplied list', () => {
+      const meta = MarkdownField.make('body')
+        .toolbarButtons(['link', 'codeBlock', 'bold'])
+        .toMeta({ hasUploadAdapter: true })
+      assert.deepEqual(meta['toolbarButtons'], ['link', 'codeBlock', 'bold'])
+    })
+
+    it('empty array ships a chrome-less editor', () => {
+      const meta = MarkdownField.make('body').toolbarButtons([]).toMeta()
+      assert.deepEqual(meta['toolbarButtons'], [])
+    })
+  })
+
+  describe('disableToolbarButtons()', () => {
+    it('drops listed buttons from the default toolbar', () => {
+      const meta = MarkdownField.make('body')
+        .disableToolbarButtons(['attachFiles', 'codeBlock'])
+        .toMeta({ hasUploadAdapter: true })
+      assert.equal((meta['toolbarButtons'] as string[]).includes('attachFiles'), false)
+      assert.equal((meta['toolbarButtons'] as string[]).includes('codeBlock'),   false)
+      assert.equal((meta['toolbarButtons'] as string[]).includes('bold'),        true)
+    })
+
+    it('chains with toolbarButtons() — drops from the most-recently-set list', () => {
+      const meta = MarkdownField.make('body')
+        .toolbarButtons(['bold', 'italic', 'link'])
+        .disableToolbarButtons(['italic'])
+        .toMeta({ hasUploadAdapter: true })
+      assert.deepEqual(meta['toolbarButtons'], ['bold', 'link'])
+    })
+
+    it('no-ops on buttons that are not in the current list', () => {
+      const meta = MarkdownField.make('body')
+        .toolbarButtons(['bold'])
+        .disableToolbarButtons(['attachFiles'])
+        .toMeta({ hasUploadAdapter: true })
+      assert.deepEqual(meta['toolbarButtons'], ['bold'])
+    })
+  })
+
+  describe('attachFiles strip', () => {
+    it('strips attachFiles from toolbar when no upload adapter is configured', () => {
+      const meta = MarkdownField.make('body').toMeta()
+      const toolbar = meta['toolbarButtons'] as string[]
+      assert.equal(toolbar.includes('attachFiles'), false)
+      // every other default button survives
+      assert.equal(toolbar.length, DEFAULT_MARKDOWN_TOOLBAR.length - 1)
+    })
+
+    it('keeps attachFiles when ctx.hasUploadAdapter is true', () => {
+      const meta = MarkdownField.make('body').toMeta({ hasUploadAdapter: true })
+      const toolbar = meta['toolbarButtons'] as string[]
+      assert.equal(toolbar.includes('attachFiles'), true)
+    })
+
+    it('strips attachFiles when uploadUrl is set but adapter flag is not', () => {
+      // Mirrors the "URL stamped but no adapter" failure mode that
+      // should hide the optional affordance.
+      const meta = MarkdownField.make('body').toMeta({ uploadUrl: '/admin/_uploads' })
+      const toolbar = meta['toolbarButtons'] as string[]
+      assert.equal(toolbar.includes('attachFiles'), false)
+      // uploadUrl is also withheld so the renderer can't accidentally
+      // try to POST to a route that has no adapter wired up.
+      assert.equal('uploadUrl' in meta, false)
+    })
+
+    it('emits uploadUrl on meta only when both ctx fields are present', () => {
+      const meta = MarkdownField.make('body').toMeta({
+        uploadUrl:        '/admin/_uploads',
+        hasUploadAdapter: true,
+      })
+      assert.equal(meta['uploadUrl'], '/admin/_uploads')
+    })
+  })
+
+  describe('minHeight / maxHeight', () => {
+    it('emits minHeight when set', () => {
+      const meta = MarkdownField.make('body').minHeight('200px').toMeta()
+      assert.equal(meta['minHeight'], '200px')
+    })
+
+    it('emits maxHeight when set', () => {
+      const meta = MarkdownField.make('body').maxHeight('600px').toMeta()
+      assert.equal(meta['maxHeight'], '600px')
+    })
+  })
+
+  describe('fileAttachmentsDirectory / fileAttachmentsVisibility', () => {
+    it('forwards directory + visibility to meta', () => {
+      const meta = MarkdownField.make('body')
+        .fileAttachmentsDirectory('articles')
+        .fileAttachmentsVisibility('public')
+        .toMeta()
+      assert.equal(meta['fileAttachmentsDirectory'], 'articles')
+      assert.equal(meta['fileAttachmentsVisibility'], 'public')
+    })
+  })
+
+  describe('cross-field plumbing (Plan #6 inheritance)', () => {
+    it('placeholder / required / helperText / default flow through buildMeta', () => {
+      const meta = MarkdownField.make('body')
+        .placeholder('Write in markdown…')
+        .required()
+        .helperText('Markdown formatting supported')
+        .default('# Hello')
+        .toMeta()
+      assert.equal(meta.placeholder, 'Write in markdown…')
+      assert.equal(meta.required, true)
+      assert.equal(meta['helperText'], 'Markdown formatting supported')
+      assert.equal(meta['defaultValue'], '# Hello')
+    })
+  })
+
+  describe('getters', () => {
+    it('expose internal config for tests / introspection', () => {
+      const f = MarkdownField.make('body')
+        .toolbarButtons(['bold', 'italic'])
+        .minHeight('100px')
+        .maxHeight('500px')
+        .fileAttachmentsDirectory('articles')
+        .fileAttachmentsVisibility('private')
+      assert.deepEqual([...f.getToolbarButtons()], ['bold', 'italic'])
+      assert.equal(f.getMinHeight(), '100px')
+      assert.equal(f.getMaxHeight(), '500px')
+      assert.equal(f.getFileAttachmentsDirectory(),  'articles')
+      assert.equal(f.getFileAttachmentsVisibility(), 'private')
+    })
+  })
+})