@elizaos/plugin-form 2.0.3-beta.5 → 2.0.3-beta.7

package/dist/builder.js

@@ -0,0 +1,458 @@
+class ControlBuilder {
+  /** Partial control being built */
+  control;
+  /**
+   * Create a new ControlBuilder.
+   *
+   * @param key - The unique key for this control
+   */
+  constructor(key) {
+    this.control = { key };
+  }
+  // ═══ STATIC FACTORIES ═══
+  // WHY static factories: Cleaner than `new ControlBuilder(key).type('text')`
+  /** Create a generic field builder */
+  static field(key) {
+    return new ControlBuilder(key);
+  }
+  /** Create a text field */
+  static text(key) {
+    return new ControlBuilder(key).type("text");
+  }
+  /** Create an email field */
+  static email(key) {
+    return new ControlBuilder(key).type("email");
+  }
+  /** Create a number field */
+  static number(key) {
+    return new ControlBuilder(key).type("number");
+  }
+  /** Create a boolean (yes/no) field */
+  static boolean(key) {
+    return new ControlBuilder(key).type("boolean");
+  }
+  /** Create a select field with options */
+  static select(key, options) {
+    return new ControlBuilder(key).type("select").options(options);
+  }
+  /** Create a date field */
+  static date(key) {
+    return new ControlBuilder(key).type("date");
+  }
+  /** Create a file upload field */
+  static file(key) {
+    return new ControlBuilder(key).type("file");
+  }
+  // ═══ TYPE ═══
+  /** Set the field type */
+  type(type) {
+    this.control.type = type;
+    return this;
+  }
+  // ═══ BEHAVIOR ═══
+  /** Mark field as required */
+  required() {
+    this.control.required = true;
+    return this;
+  }
+  /** Mark field as optional (default) */
+  optional() {
+    this.control.required = false;
+    return this;
+  }
+  /** Mark field as hidden (extract silently, never ask) */
+  hidden() {
+    this.control.hidden = true;
+    return this;
+  }
+  /** Mark field as sensitive (don't echo value back) */
+  sensitive() {
+    this.control.sensitive = true;
+    return this;
+  }
+  /** Mark field as readonly (can't change after set) */
+  readonly() {
+    this.control.readonly = true;
+    return this;
+  }
+  /** Mark field as accepting multiple values */
+  multiple() {
+    this.control.multiple = true;
+    return this;
+  }
+  // ═══ VALIDATION ═══
+  /** Set regex pattern for validation */
+  pattern(regex) {
+    this.control.pattern = regex;
+    return this;
+  }
+  /** Set minimum value (for numbers) or minimum length (via minLength) */
+  min(n) {
+    this.control.min = n;
+    return this;
+  }
+  /** Set maximum value (for numbers) or maximum length (via maxLength) */
+  max(n) {
+    this.control.max = n;
+    return this;
+  }
+  /** Set minimum string length */
+  minLength(n) {
+    this.control.minLength = n;
+    return this;
+  }
+  /** Set maximum string length */
+  maxLength(n) {
+    this.control.maxLength = n;
+    return this;
+  }
+  /** Set allowed values (enum) */
+  enum(values) {
+    this.control.enum = values;
+    return this;
+  }
+  /** Set select options */
+  options(opts) {
+    this.control.options = opts;
+    return this;
+  }
+  // ═══ AGENT HINTS ═══
+  // WHY agent hints: Help LLM extract values correctly
+  /** Set human-readable label */
+  label(label) {
+    this.control.label = label;
+    return this;
+  }
+  /** Set custom prompt for asking this field */
+  ask(prompt) {
+    this.control.askPrompt = prompt;
+    return this;
+  }
+  /** Set description for LLM context */
+  description(desc) {
+    this.control.description = desc;
+    return this;
+  }
+  /** Add extraction hints (keywords to look for) */
+  hint(...hints) {
+    this.control.extractHints = hints;
+    return this;
+  }
+  /** Set example value for "give me an example" */
+  example(value) {
+    this.control.example = value;
+    return this;
+  }
+  /** Set confidence threshold for auto-acceptance */
+  confirmThreshold(n) {
+    this.control.confirmThreshold = n;
+    return this;
+  }
+  // ═══ FILE OPTIONS ═══
+  /** Set accepted MIME types for file upload */
+  accept(mimeTypes) {
+    this.control.file = { ...this.control.file, accept: mimeTypes };
+    return this;
+  }
+  /** Set maximum file size in bytes */
+  maxSize(bytes) {
+    this.control.file = { ...this.control.file, maxSize: bytes };
+    return this;
+  }
+  /** Set maximum number of files */
+  maxFiles(n) {
+    this.control.file = { ...this.control.file, maxFiles: n };
+    return this;
+  }
+  // ═══ ACCESS ═══
+  /** Set roles that can see/fill this field */
+  roles(...roles) {
+    this.control.roles = roles;
+    return this;
+  }
+  // ═══ DEFAULTS & CONDITIONS ═══
+  /** Set default value */
+  default(value) {
+    this.control.defaultValue = value;
+    return this;
+  }
+  /** Set dependency on another field */
+  dependsOn(field, condition = "exists", value) {
+    this.control.dependsOn = { field, condition, value };
+    return this;
+  }
+  // ═══ DATABASE ═══
+  /** Set database column name (defaults to key) */
+  dbbind(columnName) {
+    this.control.dbbind = columnName;
+    return this;
+  }
+  // ═══ UI ═══
+  /** Set section name for grouping */
+  section(name) {
+    this.control.ui = { ...this.control.ui, section: name };
+    return this;
+  }
+  /** Set display order within section */
+  order(n) {
+    this.control.ui = { ...this.control.ui, order: n };
+    return this;
+  }
+  /** Set placeholder text */
+  placeholder(text) {
+    this.control.ui = { ...this.control.ui, placeholder: text };
+    return this;
+  }
+  /** Set help text */
+  helpText(text) {
+    this.control.ui = { ...this.control.ui, helpText: text };
+    return this;
+  }
+  /** Set custom widget type */
+  widget(type) {
+    this.control.ui = { ...this.control.ui, widget: type };
+    return this;
+  }
+  // ═══ I18N ═══
+  /** Add localized text for a locale */
+  i18n(locale, translations) {
+    this.control.i18n = { ...this.control.i18n, [locale]: translations };
+    return this;
+  }
+  // ═══ META ═══
+  /** Add custom metadata */
+  meta(key, value) {
+    this.control.meta = { ...this.control.meta, [key]: value };
+    return this;
+  }
+  // ═══ BUILD ═══
+  /**
+   * Build the final FormControl.
+   *
+   * Applies defaults and validates the control.
+   *
+   * @returns Complete FormControl object
+   */
+  build() {
+    const key = this.control.key;
+    if (!key) {
+      throw new Error("Control key is required");
+    }
+    const control = {
+      key,
+      label: this.control.label || prettify(key),
+      type: this.control.type || "text",
+      ...this.control
+    };
+    return control;
+  }
+}
+class FormBuilder {
+  /** Partial form being built */
+  form;
+  /**
+   * Create a new FormBuilder.
+   *
+   * @param id - Unique form identifier
+   */
+  constructor(id) {
+    this.form = { id, controls: [] };
+  }
+  // ═══ STATIC FACTORY ═══
+  /** Create a new form builder */
+  static create(id) {
+    return new FormBuilder(id);
+  }
+  // ═══ METADATA ═══
+  /** Set form name */
+  name(name) {
+    this.form.name = name;
+    return this;
+  }
+  /** Set form description */
+  description(desc) {
+    this.form.description = desc;
+    return this;
+  }
+  /** Set form version */
+  version(v) {
+    this.form.version = v;
+    return this;
+  }
+  // ═══ CONTROLS ═══
+  /**
+   * Add a control to the form.
+   *
+   * Accepts either a ControlBuilder (calls .build()) or a FormControl.
+   */
+  control(builder) {
+    const ctrl = builder instanceof ControlBuilder ? builder.build() : builder;
+    this.form.controls?.push(ctrl);
+    return this;
+  }
+  /** Add multiple controls */
+  controls(...builders) {
+    for (const builder of builders) {
+      this.control(builder);
+    }
+    return this;
+  }
+  // ═══ SHORTHAND CONTROLS ═══
+  // WHY shorthands: Quick form prototyping
+  /** Add required text fields */
+  required(...keys) {
+    for (const key of keys) {
+      this.control(ControlBuilder.field(key).required());
+    }
+    return this;
+  }
+  /** Add optional text fields */
+  optional(...keys) {
+    for (const key of keys) {
+      this.control(ControlBuilder.field(key));
+    }
+    return this;
+  }
+  // ═══ PERMISSIONS ═══
+  /** Set roles that can start this form */
+  roles(...roles) {
+    this.form.roles = roles;
+    return this;
+  }
+  /** Allow multiple submissions per user */
+  allowMultiple() {
+    this.form.allowMultiple = true;
+    return this;
+  }
+  // ═══ UX ═══
+  /** Disable undo functionality */
+  noUndo() {
+    this.form.ux = { ...this.form.ux, allowUndo: false };
+    return this;
+  }
+  /** Disable skip functionality */
+  noSkip() {
+    this.form.ux = { ...this.form.ux, allowSkip: false };
+    return this;
+  }
+  /** Disable autofill */
+  noAutofill() {
+    this.form.ux = { ...this.form.ux, allowAutofill: false };
+    return this;
+  }
+  /** Set maximum undo steps */
+  maxUndoSteps(n) {
+    this.form.ux = { ...this.form.ux, maxUndoSteps: n };
+    return this;
+  }
+  // ═══ TTL ═══
+  /** Configure TTL (time-to-live) settings */
+  ttl(config) {
+    this.form.ttl = { ...this.form.ttl, ...config };
+    return this;
+  }
+  // ═══ NUDGE ═══
+  /** Disable nudge messages */
+  noNudge() {
+    this.form.nudge = { ...this.form.nudge, enabled: false };
+    return this;
+  }
+  /** Set inactivity hours before nudge */
+  nudgeAfter(hours) {
+    this.form.nudge = { ...this.form.nudge, afterInactiveHours: hours };
+    return this;
+  }
+  /** Set custom nudge message */
+  nudgeMessage(message) {
+    this.form.nudge = { ...this.form.nudge, message };
+    return this;
+  }
+  // ═══ HOOKS ═══
+  // WHY hooks: Allow consuming plugins to handle form events
+  /** Set task worker to call on session start */
+  onStart(workerName) {
+    this.form.hooks = { ...this.form.hooks, onStart: workerName };
+    return this;
+  }
+  /** Set task worker to call on field change */
+  onFieldChange(workerName) {
+    this.form.hooks = { ...this.form.hooks, onFieldChange: workerName };
+    return this;
+  }
+  /** Set task worker to call when form is ready to submit */
+  onReady(workerName) {
+    this.form.hooks = { ...this.form.hooks, onReady: workerName };
+    return this;
+  }
+  /** Set task worker to call on submission */
+  onSubmit(workerName) {
+    this.form.hooks = { ...this.form.hooks, onSubmit: workerName };
+    return this;
+  }
+  /** Set task worker to call on cancellation */
+  onCancel(workerName) {
+    this.form.hooks = { ...this.form.hooks, onCancel: workerName };
+    return this;
+  }
+  /** Set task worker to call on expiration */
+  onExpire(workerName) {
+    this.form.hooks = { ...this.form.hooks, onExpire: workerName };
+    return this;
+  }
+  /** Set multiple hooks at once */
+  hooks(hooks) {
+    this.form.hooks = { ...this.form.hooks, ...hooks };
+    return this;
+  }
+  // ═══ DEBUG ═══
+  /** Enable debug mode (logs extraction reasoning) */
+  debug() {
+    this.form.debug = true;
+    return this;
+  }
+  // ═══ I18N ═══
+  /** Add localized form text */
+  i18n(locale, translations) {
+    this.form.i18n = { ...this.form.i18n, [locale]: translations };
+    return this;
+  }
+  // ═══ META ═══
+  /** Add custom metadata */
+  meta(key, value) {
+    this.form.meta = { ...this.form.meta, [key]: value };
+    return this;
+  }
+  // ═══ BUILD ═══
+  /**
+   * Build the final FormDefinition.
+   *
+   * Applies defaults and validates the form.
+   *
+   * @returns Complete FormDefinition object
+   */
+  build() {
+    const id = this.form.id;
+    if (!id) {
+      throw new Error("Form id is required");
+    }
+    const form = {
+      id,
+      name: this.form.name || prettify(id),
+      controls: this.form.controls || [],
+      ...this.form
+    };
+    return form;
+  }
+}
+const Form = FormBuilder;
+const C = ControlBuilder;
+function prettify(key) {
+  return key.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+export {
+  C,
+  ControlBuilder,
+  Form,
+  FormBuilder
+};
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/builder.ts"],"sourcesContent":["/**\n * @module builder\n * @description Fluent builder API for defining forms and controls\n *\n * ## Why a Builder API\n *\n * Form definitions can be verbose with many optional fields. The builder\n * API provides:\n *\n * 1. **Type Safety**: Method chaining with TypeScript gives autocomplete\n * 2. **Readability**: Intent is clear from method names\n * 3. **Defaults**: Builder applies sensible defaults\n * 4. **Validation**: Build-time checks for common mistakes\n *\n * ## Usage Examples\n *\n * ### Simple Form\n *\n * ```typescript\n * const form = Form.create('contact')\n *   .name('Contact Form')\n *   .control(C.email('email').required())\n *   .control(C.text('message').required())\n *   .build();\n * ```\n *\n * ### Complex Form\n *\n * ```typescript\n * const registrationForm = Form.create('registration')\n *   .name('User Registration')\n *   .description('Create your account')\n *   .control(\n *     C.email('email')\n *       .required()\n *       .ask('What email should we use for your account?')\n *       .example('user@example.com')\n *   )\n *   .control(\n *     C.text('username')\n *       .required()\n *       .minLength(3)\n *       .maxLength(20)\n *       .pattern('^[a-z0-9_]+$')\n *       .ask('Choose a username (letters, numbers, underscore)')\n *   )\n *   .control(\n *     C.number('age')\n *       .min(13)\n *       .ask('How old are you?')\n *   )\n *   .onSubmit('handle_registration')\n *   .ttl({ minDays: 7, maxDays: 30 })\n *   .build();\n * ```\n *\n * ### Custom Type\n *\n * ```typescript\n * // Register custom type first\n * FormService.registerType('solana_address', {\n *   validate: (v) => ({\n *     valid: /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(String(v)),\n *     error: 'Invalid Solana address'\n *   }),\n *   extractionPrompt: 'a Solana wallet address (Base58 encoded)'\n * });\n *\n * // Use in form\n * const form = Form.create('wallet')\n *   .control(\n *     C.field('walletAddress')\n *       .type('solana_address')\n *       .required()\n *       .label('Wallet Address')\n *       .ask('What is your Solana wallet address?')\n *   )\n *   .build();\n * ```\n *\n * ## Shorthand Exports\n *\n * For convenience:\n * - `Form` is an alias for `FormBuilder`\n * - `C` is an alias for `ControlBuilder`\n *\n * This enables the concise syntax shown in examples.\n */\n\nimport type { JsonValue } from \"@elizaos/core\";\nimport type {\n  FormControl,\n  FormControlDependency,\n  FormControlOption,\n  FormDefinition,\n  FormDefinitionHooks,\n} from \"./types.js\";\n\n// ============================================================================\n// CONTROL BUILDER\n// ============================================================================\n\n/**\n * Fluent builder for FormControl.\n *\n * Create controls with readable, chainable syntax:\n *\n * ```typescript\n * ControlBuilder.email('email').required().ask('What is your email?')\n * ```\n *\n * All methods return `this` for chaining except `build()` which returns\n * the final FormControl.\n */\nexport class ControlBuilder {\n  /** Partial control being built */\n  private control: Partial<FormControl>;\n\n  /**\n   * Create a new ControlBuilder.\n   *\n   * @param key - The unique key for this control\n   */\n  constructor(key: string) {\n    this.control = { key };\n  }\n\n  // ═══ STATIC FACTORIES ═══\n  // WHY static factories: Cleaner than `new ControlBuilder(key).type('text')`\n\n  /** Create a generic field builder */\n  static field(key: string): ControlBuilder {\n    return new ControlBuilder(key);\n  }\n\n  /** Create a text field */\n  static text(key: string): ControlBuilder {\n    return new ControlBuilder(key).type(\"text\");\n  }\n\n  /** Create an email field */\n  static email(key: string): ControlBuilder {\n    return new ControlBuilder(key).type(\"email\");\n  }\n\n  /** Create a number field */\n  static number(key: string): ControlBuilder {\n    return new ControlBuilder(key).type(\"number\");\n  }\n\n  /** Create a boolean (yes/no) field */\n  static boolean(key: string): ControlBuilder {\n    return new ControlBuilder(key).type(\"boolean\");\n  }\n\n  /** Create a select field with options */\n  static select(key: string, options: FormControlOption[]): ControlBuilder {\n    return new ControlBuilder(key).type(\"select\").options(options);\n  }\n\n  /** Create a date field */\n  static date(key: string): ControlBuilder {\n    return new ControlBuilder(key).type(\"date\");\n  }\n\n  /** Create a file upload field */\n  static file(key: string): ControlBuilder {\n    return new ControlBuilder(key).type(\"file\");\n  }\n\n  // ═══ TYPE ═══\n\n  /** Set the field type */\n  type(type: string): this {\n    this.control.type = type;\n    return this;\n  }\n\n  // ═══ BEHAVIOR ═══\n\n  /** Mark field as required */\n  required(): this {\n    this.control.required = true;\n    return this;\n  }\n\n  /** Mark field as optional (default) */\n  optional(): this {\n    this.control.required = false;\n    return this;\n  }\n\n  /** Mark field as hidden (extract silently, never ask) */\n  hidden(): this {\n    this.control.hidden = true;\n    return this;\n  }\n\n  /** Mark field as sensitive (don't echo value back) */\n  sensitive(): this {\n    this.control.sensitive = true;\n    return this;\n  }\n\n  /** Mark field as readonly (can't change after set) */\n  readonly(): this {\n    this.control.readonly = true;\n    return this;\n  }\n\n  /** Mark field as accepting multiple values */\n  multiple(): this {\n    this.control.multiple = true;\n    return this;\n  }\n\n  // ═══ VALIDATION ═══\n\n  /** Set regex pattern for validation */\n  pattern(regex: string): this {\n    this.control.pattern = regex;\n    return this;\n  }\n\n  /** Set minimum value (for numbers) or minimum length (via minLength) */\n  min(n: number): this {\n    this.control.min = n;\n    return this;\n  }\n\n  /** Set maximum value (for numbers) or maximum length (via maxLength) */\n  max(n: number): this {\n    this.control.max = n;\n    return this;\n  }\n\n  /** Set minimum string length */\n  minLength(n: number): this {\n    this.control.minLength = n;\n    return this;\n  }\n\n  /** Set maximum string length */\n  maxLength(n: number): this {\n    this.control.maxLength = n;\n    return this;\n  }\n\n  /** Set allowed values (enum) */\n  enum(values: string[]): this {\n    this.control.enum = values;\n    return this;\n  }\n\n  /** Set select options */\n  options(opts: FormControlOption[]): this {\n    this.control.options = opts;\n    return this;\n  }\n\n  // ═══ AGENT HINTS ═══\n  // WHY agent hints: Help LLM extract values correctly\n\n  /** Set human-readable label */\n  label(label: string): this {\n    this.control.label = label;\n    return this;\n  }\n\n  /** Set custom prompt for asking this field */\n  ask(prompt: string): this {\n    this.control.askPrompt = prompt;\n    return this;\n  }\n\n  /** Set description for LLM context */\n  description(desc: string): this {\n    this.control.description = desc;\n    return this;\n  }\n\n  /** Add extraction hints (keywords to look for) */\n  hint(...hints: string[]): this {\n    this.control.extractHints = hints;\n    return this;\n  }\n\n  /** Set example value for \"give me an example\" */\n  example(value: string): this {\n    this.control.example = value;\n    return this;\n  }\n\n  /** Set confidence threshold for auto-acceptance */\n  confirmThreshold(n: number): this {\n    this.control.confirmThreshold = n;\n    return this;\n  }\n\n  // ═══ FILE OPTIONS ═══\n\n  /** Set accepted MIME types for file upload */\n  accept(mimeTypes: string[]): this {\n    this.control.file = { ...this.control.file, accept: mimeTypes };\n    return this;\n  }\n\n  /** Set maximum file size in bytes */\n  maxSize(bytes: number): this {\n    this.control.file = { ...this.control.file, maxSize: bytes };\n    return this;\n  }\n\n  /** Set maximum number of files */\n  maxFiles(n: number): this {\n    this.control.file = { ...this.control.file, maxFiles: n };\n    return this;\n  }\n\n  // ═══ ACCESS ═══\n\n  /** Set roles that can see/fill this field */\n  roles(...roles: string[]): this {\n    this.control.roles = roles;\n    return this;\n  }\n\n  // ═══ DEFAULTS & CONDITIONS ═══\n\n  /** Set default value */\n  default(value: JsonValue): this {\n    this.control.defaultValue = value;\n    return this;\n  }\n\n  /** Set dependency on another field */\n  dependsOn(\n    field: string,\n    condition: FormControlDependency[\"condition\"] = \"exists\",\n    value?: JsonValue,\n  ): this {\n    this.control.dependsOn = { field, condition, value };\n    return this;\n  }\n\n  // ═══ DATABASE ═══\n\n  /** Set database column name (defaults to key) */\n  dbbind(columnName: string): this {\n    this.control.dbbind = columnName;\n    return this;\n  }\n\n  // ═══ UI ═══\n\n  /** Set section name for grouping */\n  section(name: string): this {\n    this.control.ui = { ...this.control.ui, section: name };\n    return this;\n  }\n\n  /** Set display order within section */\n  order(n: number): this {\n    this.control.ui = { ...this.control.ui, order: n };\n    return this;\n  }\n\n  /** Set placeholder text */\n  placeholder(text: string): this {\n    this.control.ui = { ...this.control.ui, placeholder: text };\n    return this;\n  }\n\n  /** Set help text */\n  helpText(text: string): this {\n    this.control.ui = { ...this.control.ui, helpText: text };\n    return this;\n  }\n\n  /** Set custom widget type */\n  widget(type: string): this {\n    this.control.ui = { ...this.control.ui, widget: type };\n    return this;\n  }\n\n  // ═══ I18N ═══\n\n  /** Add localized text for a locale */\n  i18n(\n    locale: string,\n    translations: {\n      label?: string;\n      description?: string;\n      askPrompt?: string;\n      helpText?: string;\n    },\n  ): this {\n    this.control.i18n = { ...this.control.i18n, [locale]: translations };\n    return this;\n  }\n\n  // ═══ META ═══\n\n  /** Add custom metadata */\n  meta(key: string, value: JsonValue): this {\n    this.control.meta = { ...this.control.meta, [key]: value };\n    return this;\n  }\n\n  // ═══ BUILD ═══\n\n  /**\n   * Build the final FormControl.\n   *\n   * Applies defaults and validates the control.\n   *\n   * @returns Complete FormControl object\n   */\n  build(): FormControl {\n    const key = this.control.key;\n    if (!key) {\n      throw new Error(\"Control key is required\");\n    }\n\n    // Apply defaults\n    const control: FormControl = {\n      key,\n      label: this.control.label || prettify(key),\n      type: this.control.type || \"text\",\n      ...this.control,\n    };\n\n    return control;\n  }\n}\n\n// ============================================================================\n// FORM BUILDER\n// ============================================================================\n\n/**\n * Fluent builder for FormDefinition.\n *\n * Create forms with readable, chainable syntax:\n *\n * ```typescript\n * Form.create('contact')\n *   .name('Contact Form')\n *   .control(C.email('email').required())\n *   .onSubmit('handle_contact')\n *   .build();\n * ```\n */\nexport class FormBuilder {\n  /** Partial form being built */\n  private form: Partial<FormDefinition>;\n\n  /**\n   * Create a new FormBuilder.\n   *\n   * @param id - Unique form identifier\n   */\n  constructor(id: string) {\n    this.form = { id, controls: [] };\n  }\n\n  // ═══ STATIC FACTORY ═══\n\n  /** Create a new form builder */\n  static create(id: string): FormBuilder {\n    return new FormBuilder(id);\n  }\n\n  // ═══ METADATA ═══\n\n  /** Set form name */\n  name(name: string): this {\n    this.form.name = name;\n    return this;\n  }\n\n  /** Set form description */\n  description(desc: string): this {\n    this.form.description = desc;\n    return this;\n  }\n\n  /** Set form version */\n  version(v: number): this {\n    this.form.version = v;\n    return this;\n  }\n\n  // ═══ CONTROLS ═══\n\n  /**\n   * Add a control to the form.\n   *\n   * Accepts either a ControlBuilder (calls .build()) or a FormControl.\n   */\n  control(builder: ControlBuilder | FormControl): this {\n    const ctrl = builder instanceof ControlBuilder ? builder.build() : builder;\n    this.form.controls?.push(ctrl);\n    return this;\n  }\n\n  /** Add multiple controls */\n  controls(...builders: (ControlBuilder | FormControl)[]): this {\n    for (const builder of builders) {\n      this.control(builder);\n    }\n    return this;\n  }\n\n  // ═══ SHORTHAND CONTROLS ═══\n  // WHY shorthands: Quick form prototyping\n\n  /** Add required text fields */\n  required(...keys: string[]): this {\n    for (const key of keys) {\n      this.control(ControlBuilder.field(key).required());\n    }\n    return this;\n  }\n\n  /** Add optional text fields */\n  optional(...keys: string[]): this {\n    for (const key of keys) {\n      this.control(ControlBuilder.field(key));\n    }\n    return this;\n  }\n\n  // ═══ PERMISSIONS ═══\n\n  /** Set roles that can start this form */\n  roles(...roles: string[]): this {\n    this.form.roles = roles;\n    return this;\n  }\n\n  /** Allow multiple submissions per user */\n  allowMultiple(): this {\n    this.form.allowMultiple = true;\n    return this;\n  }\n\n  // ═══ UX ═══\n\n  /** Disable undo functionality */\n  noUndo(): this {\n    this.form.ux = { ...this.form.ux, allowUndo: false };\n    return this;\n  }\n\n  /** Disable skip functionality */\n  noSkip(): this {\n    this.form.ux = { ...this.form.ux, allowSkip: false };\n    return this;\n  }\n\n  /** Disable autofill */\n  noAutofill(): this {\n    this.form.ux = { ...this.form.ux, allowAutofill: false };\n    return this;\n  }\n\n  /** Set maximum undo steps */\n  maxUndoSteps(n: number): this {\n    this.form.ux = { ...this.form.ux, maxUndoSteps: n };\n    return this;\n  }\n\n  // ═══ TTL ═══\n\n  /** Configure TTL (time-to-live) settings */\n  ttl(config: {\n    minDays?: number;\n    maxDays?: number;\n    effortMultiplier?: number;\n  }): this {\n    this.form.ttl = { ...this.form.ttl, ...config };\n    return this;\n  }\n\n  // ═══ NUDGE ═══\n\n  /** Disable nudge messages */\n  noNudge(): this {\n    this.form.nudge = { ...this.form.nudge, enabled: false };\n    return this;\n  }\n\n  /** Set inactivity hours before nudge */\n  nudgeAfter(hours: number): this {\n    this.form.nudge = { ...this.form.nudge, afterInactiveHours: hours };\n    return this;\n  }\n\n  /** Set custom nudge message */\n  nudgeMessage(message: string): this {\n    this.form.nudge = { ...this.form.nudge, message };\n    return this;\n  }\n\n  // ═══ HOOKS ═══\n  // WHY hooks: Allow consuming plugins to handle form events\n\n  /** Set task worker to call on session start */\n  onStart(workerName: string): this {\n    this.form.hooks = { ...this.form.hooks, onStart: workerName };\n    return this;\n  }\n\n  /** Set task worker to call on field change */\n  onFieldChange(workerName: string): this {\n    this.form.hooks = { ...this.form.hooks, onFieldChange: workerName };\n    return this;\n  }\n\n  /** Set task worker to call when form is ready to submit */\n  onReady(workerName: string): this {\n    this.form.hooks = { ...this.form.hooks, onReady: workerName };\n    return this;\n  }\n\n  /** Set task worker to call on submission */\n  onSubmit(workerName: string): this {\n    this.form.hooks = { ...this.form.hooks, onSubmit: workerName };\n    return this;\n  }\n\n  /** Set task worker to call on cancellation */\n  onCancel(workerName: string): this {\n    this.form.hooks = { ...this.form.hooks, onCancel: workerName };\n    return this;\n  }\n\n  /** Set task worker to call on expiration */\n  onExpire(workerName: string): this {\n    this.form.hooks = { ...this.form.hooks, onExpire: workerName };\n    return this;\n  }\n\n  /** Set multiple hooks at once */\n  hooks(hooks: FormDefinitionHooks): this {\n    this.form.hooks = { ...this.form.hooks, ...hooks };\n    return this;\n  }\n\n  // ═══ DEBUG ═══\n\n  /** Enable debug mode (logs extraction reasoning) */\n  debug(): this {\n    this.form.debug = true;\n    return this;\n  }\n\n  // ═══ I18N ═══\n\n  /** Add localized form text */\n  i18n(\n    locale: string,\n    translations: { name?: string; description?: string },\n  ): this {\n    this.form.i18n = { ...this.form.i18n, [locale]: translations };\n    return this;\n  }\n\n  // ═══ META ═══\n\n  /** Add custom metadata */\n  meta(key: string, value: JsonValue): this {\n    this.form.meta = { ...this.form.meta, [key]: value };\n    return this;\n  }\n\n  // ═══ BUILD ═══\n\n  /**\n   * Build the final FormDefinition.\n   *\n   * Applies defaults and validates the form.\n   *\n   * @returns Complete FormDefinition object\n   */\n  build(): FormDefinition {\n    const id = this.form.id;\n    if (!id) {\n      throw new Error(\"Form id is required\");\n    }\n\n    const form: FormDefinition = {\n      id,\n      name: this.form.name || prettify(id),\n      controls: this.form.controls || [],\n      ...this.form,\n    };\n\n    return form;\n  }\n}\n\n// ============================================================================\n// SHORTHAND EXPORTS\n// ============================================================================\n\n/**\n * Shorthand for FormBuilder.create\n *\n * Usage: `Form.create('myForm')...`\n */\nexport const Form = FormBuilder;\n\n/**\n * Shorthand for ControlBuilder factories\n *\n * Usage: `C.email('email').required()`\n */\nexport const C = ControlBuilder;\n\n// ============================================================================\n// UTILITY\n// ============================================================================\n\n/**\n * Convert snake_case or kebab-case to Title Case.\n *\n * Used to generate human-readable labels from field keys.\n *\n * @example prettify('first_name') // \"First Name\"\n * @example prettify('email-address') // \"Email Address\"\n */\nfunction prettify(key: string): string {\n  return key.replace(/[-_]/g, \" \").replace(/\\b\\w/g, (c) => c.toUpperCase());\n}\n"],"mappings":"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","names":[]}

package/dist/builtins.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @module builtins
+ * @description Built-in control types for the Form Plugin
+ *
+ * ## Overview
+ *
+ * This module defines the standard control types that are available out of the box:
+ * - text: Plain text strings
+ * - number: Numeric values (integers or decimals)
+ * - email: Email addresses with format validation
+ * - boolean: Yes/no, true/false values
+ * - select: Choice from predefined options
+ * - date: Date values in various formats
+ * - file: File uploads (handled specially)
+ *
+ * ## Why Built-in Types
+ *
+ * Built-in types provide:
+ * 1. **Consistent validation** across all forms - same rules everywhere
+ * 2. **Sensible defaults** for common field types - less configuration
+ * 3. **LLM extraction hints** optimized for each type - better extraction
+ * 4. **Override protection** to prevent accidental shadowing - safety first
+ *
+ * ## Architecture Decision: ControlType vs TypeHandler
+ *
+ * We use ControlType (not the legacy TypeHandler) because:
+ * - ControlType is the shared interface for all type categories
+ * - ControlType supports composite types (subcontrols)
+ * - ControlType supports external types (activate/confirm)
+ * - TypeHandler is legacy and maintained only for backwards compatibility
+ *
+ * ## Why These Specific Types
+ *
+ * | Type | Why Built-in |
+ * |------|--------------|
+ * | text | Most common field type, catch-all for strings |
+ * | number | Second most common, needs special parsing (commas, $) |
+ * | email | Critical for communication, has clear format rules |
+ * | boolean | Binary choice, many natural language forms (yes/no/true/false) |
+ * | select | Constrained choice, validation against options |
+ * | date | Complex parsing (many formats), needs normalization |
+ * | file | Special handling needed (size, type, storage) |
+ *
+ * ## Extending
+ *
+ * Plugins can register custom types via FormService.registerControlType().
+ * Built-in types can be overridden with { allowOverride: true } option,
+ * but this will log a warning.
+ *
+ * ## Usage
+ *
+ * Built-in types are automatically registered when FormService starts.
+ * You don't need to call registerBuiltinTypes() manually.
+ *
+ * @example
+ * ```typescript
+ * // Check if a type is built-in before overriding
+ * if (isBuiltinType('email')) {
+ *   console.log('Warning: overriding built-in type');
+ *   formService.registerControlType(myEmailType, { allowOverride: true });
+ * }
+ * ```
+ */
+import type { ControlType } from "./types";
+/**
+ * Array of all built-in control types.
+ *
+ * These are registered automatically when FormService starts.
+ * The order doesn't matter; they're looked up by id.
+ *
+ * WHY array + map:
+ * - Array allows easy iteration for registration
+ * - Map provides O(1) lookup for override checks
+ * - Both derived from same source ensures consistency
+ */
+export declare const BUILTIN_TYPES: ControlType[];
+/**
+ * Map of built-in types by id for quick lookup.
+ *
+ * WHY Map (not object):
+ * - Type-safe keys
+ * - O(1) lookup performance
+ * - Clear has/get semantics
+ */
+export declare const BUILTIN_TYPE_MAP: Map<string, ControlType>;
+/**
+ * Register all built-in types with a FormService instance.
+ *
+ * This is called automatically during FormService.start().
+ * You typically don't need to call this directly.
+ *
+ * WHY take a function (not FormService):
+ * - Avoids circular dependency (builtins.ts ↔ service.ts)
+ * - Service passes its registerControlType method
+ * - Clean separation of concerns
+ *
+ * @param registerFn - The FormService.registerControlType method
+ */
+export declare function registerBuiltinTypes(registerFn: (type: ControlType, options?: {
+    allowOverride?: boolean;
+}) => void): void;
+/**
+ * Get a built-in type by id.
+ *
+ * This is a convenience for checking if a type is built-in
+ * before attempting to override it.
+ *
+ * WHY this exists:
+ * - Plugins may want to extend a built-in type
+ * - Checking before override allows informed decisions
+ * - Avoids accidental shadowing
+ *
+ * @param id - The type id to look up
+ * @returns The ControlType if found, undefined otherwise
+ */
+export declare function getBuiltinType(id: string): ControlType | undefined;
+/**
+ * Check if a type id is a built-in type.
+ *
+ * WHY boolean convenience:
+ * - Most callers just need yes/no answer
+ * - Cleaner than checking getBuiltinType() !== undefined
+ *
+ * @param id - The type id to check
+ * @returns true if the type is built-in
+ */
+export declare function isBuiltinType(id: string): boolean;
+//# sourceMappingURL=builtins.d.ts.map

package/dist/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,SAAS,CAAC;AA+a1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,EAQtC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAErD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,CACV,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,KAClC,IAAI,GACR,IAAI,CAIN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjD"}