@pilotiq/pilotiq 0.1.0 → 0.3.0

package/src/elements/dispatchForm.ts

@@ -180,6 +180,18 @@ export async function dispatchFormSubmit<R = unknown>(
  *
  * Other field types are passed through untouched.
  */
+/** Remove every occurrence of any character in `chars` from `value`.
+ *  O(n) — uses a Set for membership lookup. Multi-codepoint entries
+ *  in `chars` (e.g. an emoji passed as one mask token) are matched
+ *  whole; the function compares against `Array.from(value)` so
+ *  surrogate pairs round-trip correctly. */
+function stripChars(value: string, chars: string[]): string {
+  const set = new Set(chars)
+  let out = ''
+  for (const ch of value) if (!set.has(ch)) out += ch
+  return out
+}
+
 export function coerceFormValues(
   elements: Element[],
   body:     Record<string, unknown>,
@@ -384,6 +396,22 @@ export function coerceFormValues(
         // text/textarea/email/select/slug — leave as string.
         break
     }
+
+    // `TextField.stripCharacters([…])` — applies after type-specific
+    // coercion so the persisted value never carries the listed
+    // characters. Duck-typed: any Field whose `getStripCharacters?`
+    // returns a non-empty list opts in. Skipped for non-strings (the
+    // pre-coerce switch may have produced numbers / booleans / arrays).
+    const stripper = (field as { getStripCharacters?: () => string[] | undefined }).getStripCharacters
+    if (typeof stripper === 'function') {
+      const chars = stripper.call(field)
+      if (chars && chars.length > 0) {
+        const cur = out[name]
+        if (typeof cur === 'string' && cur.length > 0) {
+          out[name] = stripChars(cur, chars)
+        }
+      }
+    }
   })
   return out
 }

package/src/fields/BuilderField.ts

@@ -462,9 +462,46 @@ export class BuilderField extends Field {
    */
   reorderAction(b: RowButton): this { this._buttons.reorder = b; return this }
 
-  /** Customize the per-row collapse chevron. */
+  /**
+   * Customize the per-row collapse chevron. Applies to BOTH states by
+   * default — the open chevron and the collapsed chevron share the
+   * override unless `expandAction(...)` is also set, in which case
+   * `collapseAction` covers only the open state and `expandAction`
+   * covers the collapsed state. Mirrors `RepeaterField.collapseAction`.
+   */
   collapseAction(b: RowButton): this { this._buttons.collapse = b; return this }
 
+  /**
+   * Customize the per-row chevron when the row is currently *collapsed*.
+   * Sibling of `collapseAction` for the closed-state glyph. Mirrors
+   * `RepeaterField.expandAction`.
+   */
+  expandAction(b: RowButton): this { this._buttons.expand = b; return this }
+
+  /**
+   * Mount an "Expand all" button in the field header. Opt-in: calling
+   * without args shows the button with default chrome; pass a
+   * `RowButton` to override icon / label / tooltip / color. Auto-arms
+   * `collapsible()`. In `accordion()` mode the button opens the first
+   * visible row. Mirrors `RepeaterField.expandAllAction`.
+   */
+  expandAllAction(button?: RowButton): this {
+    this._buttons.expandAll = button ?? RowButton.make()
+    this._collapsible = true
+    return this
+  }
+
+  /**
+   * Mount a "Collapse all" button in the field header. Opt-in (calling
+   * enables; pass a `RowButton` to customize). Auto-arms `collapsible()`.
+   * Mirrors `RepeaterField.collapseAllAction`.
+   */
+  collapseAllAction(button?: RowButton): this {
+    this._buttons.collapseAll = button ?? RowButton.make()
+    this._collapsible = true
+    return this
+  }
+
   // ─── Read-only access ────────────────────────────────
 
   override getChildren(): undefined {

package/src/fields/FileUploadField.test.ts

@@ -56,6 +56,52 @@ describe('FileUploadField', () => {
     assert.equal('uploadUrl' in meta, false)
   })
 
+  describe('image editor (Phase A)', () => {
+    it('imageEditor() stamps imageEditor:true', () => {
+      const meta = FileUploadField.make('photo').imageEditor().toMeta()
+      assert.equal(meta['imageEditor'], true)
+    })
+
+    it('imageEditor() absent by default', () => {
+      const meta = FileUploadField.make('photo').toMeta()
+      assert.equal('imageEditor' in meta, false)
+    })
+
+    it('imageEditorAspectRatioOptions() stamps options array', () => {
+      const opts = [{ ratio: 16 / 9, label: 'Widescreen' }, { ratio: 1, label: 'Square' }]
+      const meta = FileUploadField.make('photo').imageEditor().imageEditorAspectRatioOptions(opts).toMeta()
+      assert.deepEqual(meta['imageEditorAspectRatioOptions'], opts)
+    })
+
+    it('circleCropper() stamps circleCropper:true', () => {
+      const meta = FileUploadField.make('photo').imageEditor().circleCropper().toMeta()
+      assert.equal(meta['circleCropper'], true)
+    })
+
+    it('automaticallyCropImagesToAspectRatio() stamps flag', () => {
+      const meta = FileUploadField.make('photo').imageEditor().automaticallyCropImagesToAspectRatio().toMeta()
+      assert.equal(meta['automaticallyCropImagesToAspectRatio'], true)
+    })
+
+    it('automaticallyResize() stamps width+height', () => {
+      const meta = FileUploadField.make('photo').automaticallyResize(800, 600).toMeta()
+      assert.deepEqual(meta['automaticallyResize'], { width: 800, height: 600 })
+    })
+
+    it('avatar() sets imageEditor + circleCropper + multiple:false', () => {
+      const meta = FileUploadField.make('avatar').avatar().toMeta()
+      assert.equal(meta['imageEditor'],    true)
+      assert.equal(meta['circleCropper'],  true)
+      assert.equal(meta['multiple'],       false)
+    })
+
+    it('avatar() does not override an explicit multiple(true)', () => {
+      // avatar() forces multiple false — explicit multiple() after avatar() wins
+      const meta = FileUploadField.make('avatar').avatar().multiple(true).toMeta()
+      assert.equal(meta['multiple'], true)
+    })
+  })
+
   describe('coerceFormValues', () => {
     it('passes URL string through (single mode)', () => {
       const out = coerceFormValues(

package/src/fields/FileUploadField.ts

@@ -1,6 +1,15 @@
 import { Field, type FieldMeta } from './Field.js'
 import type { RenderContext } from '../schema/resolveSchema.js'
 
+export type PanelLayout = 'list' | 'grid' | 'integrated'
+
+export interface AspectRatioOption {
+  /** Numeric ratio, e.g. `16/9`, `4/3`, `1` for square. */
+  ratio: number
+  /** Human-readable label shown in the editor picker, e.g. `'Widescreen'`. */
+  label: string
+}
+
 /**
  * File upload. The field stores the resolved upload's URL string —
  * `string` for single-file mode, `string[]` for multi.
@@ -17,6 +26,16 @@ export class FileUploadField extends Field {
   private _multiple = false
   private _preview = true
   private _directory?: string
+  private _downloadable = false
+  private _openable = false
+  private _reorderable = false
+  private _appendFiles = false
+  private _panelLayout: PanelLayout = 'list'
+  private _imageEditor = false
+  private _imageEditorAspectRatioOptions?: AspectRatioOption[]
+  private _circleCropper = false
+  private _automaticallyCropImagesToAspectRatio = false
+  private _automaticallyResize?: { width: number; height: number }
 
   private constructor(name: string) {
     super(name, 'fileUpload')
@@ -45,20 +64,89 @@ export class FileUploadField extends Field {
    */
   directory(d: string): this { this._directory = d; return this }
 
+  /** Add a download button to each uploaded file item. */
+  downloadable(value: boolean = true): this { this._downloadable = value; return this }
+
+  /** Make the file thumbnail/icon link to the file (open in new tab). */
+  openable(value: boolean = true): this { this._openable = value; return this }
+
+  /** Allow files to be reordered via drag-and-drop. Only useful with `multiple()`. */
+  reorderable(value: boolean = true): this { this._reorderable = value; return this }
+
+  /**
+   * Append new uploads to the existing file list instead of replacing it.
+   * By default new picks replace the current value. Combine with `multiple()`.
+   */
+  appendFiles(value: boolean = true): this { this._appendFiles = value; return this }
+
+  /** Display layout for the uploaded file list. `'grid'` shows square tiles; `'integrated'` embeds the upload button as a tile. */
+  panelLayout(layout: PanelLayout): this { this._panelLayout = layout; return this }
+
+  /** Open a crop/resize modal after the user selects an image, before it is uploaded. */
+  imageEditor(value: boolean = true): this { this._imageEditor = value; return this }
+
+  /** Aspect ratio presets shown in the image editor picker. */
+  imageEditorAspectRatioOptions(options: AspectRatioOption[]): this { this._imageEditorAspectRatioOptions = options; return this }
+
+  /** Render a circular crop overlay in the image editor. */
+  circleCropper(value: boolean = true): this { this._circleCropper = value; return this }
+
+  /**
+   * When aspect ratio options are configured, automatically apply the first
+   * ratio and skip showing the editor UI unless the user explicitly opens it.
+   */
+  automaticallyCropImagesToAspectRatio(value: boolean = true): this { this._automaticallyCropImagesToAspectRatio = value; return this }
+
+  /**
+   * Resize the image to the given dimensions on the server after upload.
+   * Requires `@rudderjs/image` to be installed and the upload adapter to
+   * forward the `resize_width` / `resize_height` FormData fields.
+   */
+  automaticallyResize(width: number, height: number): this { this._automaticallyResize = { width, height }; return this }
+
+  /**
+   * Shorthand for `.imageEditor().circleCropper().multiple(false)`.
+   * Ideal for single avatar / profile-picture fields.
+   */
+  avatar(value: boolean = true): this {
+    if (value) { this._imageEditor = true; this._circleCropper = true; this._multiple = false }
+    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 }
+  isDownloadable(): boolean { return this._downloadable }
+  isOpenable(): boolean { return this._openable }
+  isReorderable(): boolean { return this._reorderable }
+  doesAppendFiles(): boolean { return this._appendFiles }
+  getPanelLayout(): PanelLayout { return this._panelLayout }
+  hasImageEditor(): boolean { return this._imageEditor }
+  getImageEditorAspectRatioOptions(): AspectRatioOption[] | undefined { return this._imageEditorAspectRatioOptions }
+  hasCircleCropper(): boolean { return this._circleCropper }
+  doesAutomaticallyCrop(): boolean { return this._automaticallyCropImagesToAspectRatio }
+  getAutomaticallyResize(): { width: number; height: number } | undefined { return this._automaticallyResize }
 
   override toMeta(ctx?: RenderContext): FieldMeta {
     return {
       ...this.buildMeta(ctx),
       multiple: this._multiple,
       preview:  this._preview,
-      ...(this._accept   ? { accept: this._accept }    : {}),
+      ...(this._accept     ? { accept: this._accept }     : {}),
       ...(this._maxSize !== undefined ? { maxSize: this._maxSize } : {}),
-      ...(this._directory ? { directory: this._directory } : {}),
+      ...(this._directory  ? { directory: this._directory }  : {}),
+      ...(this._downloadable           ? { downloadable: true }             : {}),
+      ...(this._openable               ? { openable: true }                 : {}),
+      ...(this._reorderable            ? { reorderable: true }              : {}),
+      ...(this._appendFiles            ? { appendFiles: true }              : {}),
+      ...(this._panelLayout !== 'list' ? { panelLayout: this._panelLayout } : {}),
+      ...(this._imageEditor ? { imageEditor: true } : {}),
+      ...(this._imageEditorAspectRatioOptions?.length ? { imageEditorAspectRatioOptions: this._imageEditorAspectRatioOptions } : {}),
+      ...(this._circleCropper ? { circleCropper: true } : {}),
+      ...(this._automaticallyCropImagesToAspectRatio ? { automaticallyCropImagesToAspectRatio: true } : {}),
+      ...(this._automaticallyResize ? { automaticallyResize: this._automaticallyResize } : {}),
       // `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

package/src/fields/RepeaterField.ts

@@ -588,9 +588,53 @@ export class RepeaterField extends Field {
    */
   reorderAction(b: RowButton): this { this._buttons.reorder = b; return this }
 
-  /** Customize the per-row collapse chevron. */
+  /**
+   * Customize the per-row collapse chevron. Applies to BOTH states by
+   * default — the open chevron and the collapsed chevron share the
+   * override unless `expandAction(...)` is also set, in which case
+   * `collapseAction` covers only the open state and `expandAction`
+   * covers the collapsed state.
+   */
   collapseAction(b: RowButton): this { this._buttons.collapse = b; return this }
 
+  /**
+   * Customize the per-row chevron when the row is currently *collapsed*
+   * (i.e. the "click me to expand" state). Sibling of `collapseAction`
+   * for the closed-state glyph; without this, both states fall through
+   * to `collapseAction` (back-compat) and ultimately to the default
+   * chevron pair (right when collapsed, down when open).
+   */
+  expandAction(b: RowButton): this { this._buttons.expand = b; return this }
+
+  /**
+   * Mount an "Expand all" button in the field header — clicking it opens
+   * every collapsed row. Opt-in: calling without args shows the button
+   * with the default icon (chevron-down) + label ("Expand all"); pass a
+   * `RowButton` to override icon / label / tooltip / color.
+   *
+   * Auto-arms `collapsible()` since the affordance is meaningless without
+   * collapsible rows. In `accordion()` mode the button opens the first
+   * visible row (accordion's "only one open" invariant survives).
+   */
+  expandAllAction(button?: RowButton): this {
+    this._buttons.expandAll = button ?? RowButton.make()
+    this._collapsible = true
+    return this
+  }
+
+  /**
+   * Mount a "Collapse all" button in the field header — clicking it
+   * collapses every open row. Opt-in (calling enables; pass a
+   * `RowButton` to customize). Auto-arms `collapsible()`. In `accordion()`
+   * mode the button closes the currently-open row, leaving everything
+   * collapsed.
+   */
+  collapseAllAction(button?: RowButton): this {
+    this._buttons.collapseAll = button ?? RowButton.make()
+    this._collapsible = true
+    return this
+  }
+
   /**
    * Per-row action buttons rendered in each row's header alongside the
    * built-in clone/delete strip. Useful for "Mark featured", "Send test",

package/src/fields/RowButton.test.ts

@@ -98,6 +98,63 @@ describe('RepeaterField row-action customizers', () => {
     assert.equal(r.getButton('delete')!.getColor(), 'destructive')
     assert.equal(r.getButton('clone'), undefined)
   })
+
+  test('expandAction lands on meta.buttons.expand (separate from collapseAction)', () => {
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .collapsible()
+      .collapseAction(RowButton.make().icon('chevron-down'))
+      .expandAction(RowButton.make().icon('chevron-right').tooltip('Open'))
+      .toMeta() as { buttons?: { collapse?: { icon?: string }; expand?: { icon?: string; tooltip?: string } } }
+    assert.deepEqual(meta.buttons?.collapse, { icon: 'chevron-down' })
+    assert.deepEqual(meta.buttons?.expand,   { icon: 'chevron-right', tooltip: 'Open' })
+  })
+
+  test('expandAllAction() with no arg flips on the slot with empty defaults', () => {
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .expandAllAction()
+      .toMeta()
+    assert.deepEqual(meta.buttons?.expandAll, {})
+    assert.equal(meta.collapsible, true, 'expandAllAction() auto-arms collapsible()')
+  })
+
+  test('expandAllAction(button) keeps the override and still auto-arms collapsible', () => {
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .expandAllAction(RowButton.make().label('Open everything').icon('chevrons-down'))
+      .toMeta() as { buttons?: { expandAll?: { label?: string; icon?: string } }; collapsible?: boolean }
+    assert.deepEqual(meta.buttons?.expandAll, { label: 'Open everything', icon: 'chevrons-down' })
+    assert.equal(meta.collapsible, true)
+  })
+
+  test('collapseAllAction() with no arg flips on the slot and auto-arms collapsible', () => {
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .collapseAllAction()
+      .toMeta()
+    assert.deepEqual(meta.buttons?.collapseAll, {})
+    assert.equal(meta.collapsible, true)
+  })
+
+  test('collapseAllAction(button) routes through the override', () => {
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .collapseAllAction(RowButton.make().label('Hide all').color('muted'))
+      .toMeta() as { buttons?: { collapseAll?: { label?: string; color?: string } } }
+    assert.deepEqual(meta.buttons?.collapseAll, { label: 'Hide all', color: 'muted' })
+  })
+
+  test('non-customized field omits the new slots entirely', () => {
+    // Bare field never serializes any of the four new slots — back-compat
+    // for renderers that read `meta.buttons` and assume only the original
+    // seven keys are reachable.
+    const meta = Repeater.make('items')
+      .schema([TextField.make('text')])
+      .collapsible()
+      .toMeta() as { buttons?: unknown }
+    assert.equal(meta.buttons, undefined)
+  })
 })
 
 describe('BuilderField row-action customizers', () => {
@@ -146,4 +203,17 @@ describe('BuilderField row-action customizers', () => {
       .toMeta() as { buttons?: unknown }
     assert.deepEqual(r.buttons, b.buttons)
   })
+
+  test('expandAction / expandAllAction / collapseAllAction land on Builder meta with the same kind keys', () => {
+    const meta = Builder.make('blocks')
+      .blocks([Block.make('hero').schema([TextField.make('title')])])
+      .expandAction(RowButton.make().icon('chevron-right'))
+      .expandAllAction(RowButton.make().label('Open everything'))
+      .collapseAllAction()
+      .toMeta()
+    assert.deepEqual(meta.buttons?.expand,      { icon: 'chevron-right' })
+    assert.deepEqual(meta.buttons?.expandAll,   { label: 'Open everything' })
+    assert.deepEqual(meta.buttons?.collapseAll, {})
+    assert.equal(meta.collapsible, true, 'Builder bulk setters auto-arm collapsible()')
+  })
 })

package/src/fields/RowButton.ts

@@ -107,9 +107,16 @@ export class RowButton {
 }
 
 /**
- * Slot id for one of the seven built-in row chrome buttons. The renderer
+ * Slot id for one of the built-in row chrome buttons. The renderer
  * looks these up in `meta.buttons[kind]` to merge customizer overrides
  * onto its hardcoded defaults.
+ *
+ * `expand` is the per-row sibling of `collapse` — used when the row is
+ * currently collapsed so authors can override icon/label/tooltip
+ * separately for each state. `expandAll` / `collapseAll` are the bulk
+ * field-header buttons; presence of either slot is what flips the
+ * matching button into existence (different from the always-rendered
+ * per-row chrome — see `RepeaterField.expandAllAction` for posture).
  */
 export type RowButtonKind =
   | 'add'
@@ -119,6 +126,9 @@ export type RowButtonKind =
   | 'moveDown'
   | 'reorder'
   | 'collapse'
+  | 'expand'
+  | 'expandAll'
+  | 'collapseAll'
 
 export type RowButtonsMeta = {
   [K in RowButtonKind]?: RowButtonMeta

package/src/fields/TextField.test.ts

@@ -0,0 +1,168 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { TextField } from './TextField.js'
+import { Action } from '../actions/Action.js'
+import { resolveSchema } from '../schema/resolveSchema.js'
+import { coerceFormValues } from '../elements/dispatchForm.js'
+import { formatWithMask } from '../react/fields/textInputControls.js'
+
+describe('TextField rich affordances (audit gap #3)', () => {
+  describe('password / revealable', () => {
+    it('emits password + revealable flags only when set', () => {
+      const a = TextField.make('p').password().revealable().toMeta()
+      assert.equal(a['password'],   true)
+      assert.equal(a['revealable'], true)
+
+      const b = TextField.make('p').toMeta()
+      assert.equal(b['password'],   undefined)
+      assert.equal(b['revealable'], undefined)
+    })
+
+    it('disarms with explicit false', () => {
+      const a = TextField.make('p').password(false).toMeta()
+      assert.equal(a['password'], undefined)
+    })
+  })
+
+  describe('copyable', () => {
+    it('flag emits and message defaults are sparse', () => {
+      const a = TextField.make('x').copyable().toMeta()
+      assert.equal(a['copyable'],     true)
+      assert.equal(a['copyMessage'],  undefined)
+
+      const b = TextField.make('x').copyable('Got it').toMeta()
+      assert.equal(b['copyable'],     true)
+      assert.equal(b['copyMessage'],  'Got it')
+    })
+  })
+
+  describe('mask', () => {
+    it('emits the pattern verbatim', () => {
+      const a = TextField.make('phone').mask('(999) 999-9999').toMeta()
+      assert.equal(a['mask'], '(999) 999-9999')
+    })
+  })
+
+  describe('datalist', () => {
+    it('emits a defensive copy of the values array', () => {
+      const values = ['gmail.com', 'outlook.com']
+      const a = TextField.make('email').datalist(values).toMeta()
+      const out = a['datalist'] as string[]
+      assert.deepEqual(out, values)
+      // Mutating the original after the fact must not leak in.
+      values.push('yahoo.com')
+      assert.deepEqual(a['datalist'], ['gmail.com', 'outlook.com'])
+    })
+  })
+
+  describe('stripCharacters', () => {
+    it('accepts a string of single chars', () => {
+      const a = TextField.make('phone').stripCharacters('()- ').toMeta()
+      assert.deepEqual(a['stripCharacters'], ['(', ')', '-', ' '])
+    })
+
+    it('accepts an explicit array', () => {
+      const a = TextField.make('phone').stripCharacters(['(', ')']).toMeta()
+      assert.deepEqual(a['stripCharacters'], ['(', ')'])
+    })
+
+    it('omits when empty', () => {
+      const a = TextField.make('x').stripCharacters('').toMeta()
+      assert.equal(a['stripCharacters'], undefined)
+    })
+
+    it('strips configured chars during coerce', () => {
+      const f = TextField.make('phone').stripCharacters('()- ')
+      const out = coerceFormValues([f], { phone: '(415) 555-1212' })
+      assert.equal(out['phone'], '4155551212')
+    })
+
+    it('coerce no-ops when not configured', () => {
+      const f = TextField.make('plain')
+      const out = coerceFormValues([f], { plain: 'a-b-c' })
+      assert.equal(out['plain'], 'a-b-c')
+    })
+
+    it('coerce skips non-string values', () => {
+      const f = TextField.make('plain').stripCharacters('-')
+      const out = coerceFormValues([f], { plain: 42 as unknown as string })
+      assert.equal(out['plain'], 42)
+    })
+  })
+
+  describe('inputMode + autocapitalize', () => {
+    it('emits each attribute when set', () => {
+      const a = TextField.make('q').inputMode('search').autocapitalize('off').toMeta()
+      assert.equal(a['inputMode'],      'search')
+      assert.equal(a['autocapitalize'], 'off')
+    })
+
+    it('omits each attribute when unset', () => {
+      const a = TextField.make('q').toMeta()
+      assert.equal(a['inputMode'],      undefined)
+      assert.equal(a['autocapitalize'], undefined)
+    })
+  })
+
+  describe('prefixAction / suffixAction', () => {
+    it('resolves bound Actions through resolveSchema as ActionMetas', async () => {
+      const result = await resolveSchema([
+        TextField.make('apiKey')
+          .prefixAction(Action.make('generate').icon('plus'))
+          .suffixAction(Action.make('rotate').icon('refresh')),
+      ])
+      const meta = result[0]!
+      const pre = meta['prefixAction'] as Record<string, unknown> | undefined
+      const suf = meta['suffixAction'] as Record<string, unknown> | undefined
+      assert.equal(pre?.['type'], 'action')
+      assert.equal(pre?.['name'], 'generate')
+      assert.equal(suf?.['type'], 'action')
+      assert.equal(suf?.['name'], 'rotate')
+    })
+
+    it('drops a hidden Action from the slot', async () => {
+      const result = await resolveSchema([
+        TextField.make('q').prefixAction(Action.make('hide').visible(false)),
+      ])
+      assert.equal(result[0]!['prefixAction'], undefined)
+    })
+
+    it('omits the slots when not configured', async () => {
+      const result = await resolveSchema([TextField.make('q')])
+      assert.equal(result[0]!['prefixAction'], undefined)
+      assert.equal(result[0]!['suffixAction'], undefined)
+    })
+  })
+})
+
+describe('formatWithMask (client mask helper)', () => {
+  it('formats a US phone via the documented alphabet', () => {
+    assert.equal(formatWithMask('4155551212', '(999) 999-9999'), '(415) 555-1212')
+  })
+
+  it('emits literals even with no remaining input', () => {
+    assert.equal(formatWithMask('415', '(999) 999-9999'), '(415) ')
+  })
+
+  it('skips characters that do not match the token kind', () => {
+    assert.equal(formatWithMask('a4b1c5', '999'), '415')
+  })
+
+  it('handles alpha tokens', () => {
+    assert.equal(formatWithMask('xy12', 'aa-99'), 'xy-12')
+  })
+
+  it('any-token (*) accepts any character', () => {
+    assert.equal(formatWithMask('a1b2', '****'), 'a1b2')
+  })
+
+  it('does NOT double-emit literals already typed by the user', () => {
+    assert.equal(formatWithMask('(415)5551212', '(999) 999-9999'), '(415) 555-1212')
+  })
+
+  it('returns input unchanged when mask is empty', () => {
+    assert.equal(formatWithMask('hello', ''), '')
+  })
+})
+