@stimulus-plumbers/controllers 0.2.6 → 0.2.8

package/src/controllers/modal_controller.js

@@ -3,11 +3,6 @@ import { FocusTrap } from '../focus';
 import { announce } from '../aria';
 import { attachDismisser } from '../plumbers';
 
-/**
- * Modal Dialog Controller
- * Implements WAI-ARIA Dialog (Modal) pattern
- * Supports both native <dialog> elements and custom implementations
- */
 export default class ModalController extends Controller {
   static targets = ['modal', 'overlay'];
 
@@ -21,7 +16,7 @@ export default class ModalController extends Controller {
 
     if (this.isNativeDialog) {
       this.modalTarget.addEventListener('cancel', this.close);
-      this.modalTarget.addEventListener('click', this.handleBackdropClick);
+      this.modalTarget.addEventListener('click', this.onBackdropClick);
     } else {
       this.focusTrap = new FocusTrap(this.modalTarget, {
         escapeDeactivates: true,
@@ -38,7 +33,7 @@ export default class ModalController extends Controller {
   disconnect() {
     if (this.isNativeDialog) {
       this.modalTarget.removeEventListener('cancel', this.close);
-      this.modalTarget.removeEventListener('click', this.handleBackdropClick);
+      this.modalTarget.removeEventListener('click', this.onBackdropClick);
     }
   }
 
@@ -89,7 +84,7 @@ export default class ModalController extends Controller {
     announce('Modal closed');
   }
 
-  handleBackdropClick = (event) => {
+  onBackdropClick = (event) => {
     const rect = this.modalTarget.getBoundingClientRect();
     const isOutsideDialog =
       event.clientY < rect.top ||

package/src/controllers/popover_controller.js

@@ -39,7 +39,7 @@ export default class extends Controller {
     await this.load();
   }
 
-  contentLoad() {
+  canLoad() {
     if (this.hasContentTarget && this.contentTarget.tagName.toLowerCase() === 'turbo-frame') {
       if (this.hasUrlValue) this.contentTarget.setAttribute('src', this.urlValue);
       return false;

package/src/index.js

@@ -11,11 +11,16 @@ export * from './keyboard.js';
 export * from './aria.js';
 
 // Export Stimulus controllers
-export { default as ModalController } from './controllers/modal_controller.js';
-export { default as DismisserController } from './controllers/dismisser_controller.js';
-export { default as FlipperController } from './controllers/flipper_controller.js';
-export { default as PopoverController } from './controllers/popover_controller.js';
 export { default as CalendarMonthController } from './controllers/calendar_month_controller.js';
 export { default as CalendarMonthObserverController } from './controllers/calendar_month_observer_controller.js';
-export { default as DatepickerController } from './controllers/datepicker_controller.js';
+export { default as ClipboardController } from './controllers/clipboard_controller.js';
+export { default as ComboboxDateController } from './controllers/combobox_date_controller.js';
+export { default as ComboboxDropdownController } from './controllers/combobox_dropdown_controller.js';
+export { default as ComboboxTimeController } from './controllers/combobox_time_controller.js';
+export { default as DismisserController } from './controllers/dismisser_controller.js';
+export { default as FlipperController } from './controllers/flipper_controller.js';
+export { default as InputComboboxController } from './controllers/input_combobox_controller.js';
+export { default as InputFormatController } from './controllers/input_format_controller.js';
+export { default as ModalController } from './controllers/modal_controller.js';
 export { default as PannerController } from './controllers/panner_controller.js';
+export { default as PopoverController } from './controllers/popover_controller.js';

package/src/plumbers/combobox_dropdown.js

@@ -0,0 +1,60 @@
+import Plumber from './plumber';
+
+export class ComboboxDropdown extends Plumber {
+  constructor(controller, options = {}) {
+    super(controller, options);
+    this.debounceTimer = null;
+    this.abortController = null;
+  }
+
+  fuzzyFilter(listbox, query) {
+    const needle = query.toLowerCase();
+    let visible = 0;
+    listbox.querySelectorAll('[role="option"]').forEach((opt) => {
+      const match = this.fuzzyMatch(needle, opt.textContent.trim().toLowerCase());
+      opt.hidden = !match;
+      if (match) visible++;
+    });
+    return visible;
+  }
+
+  fuzzyMatch(needle, haystack) {
+    let ni = 0;
+    for (let i = 0; i < haystack.length && ni < needle.length; i++) {
+      if (haystack[i] === needle[ni]) ni++;
+    }
+    return ni === needle.length;
+  }
+
+  scheduleFetch(query, delay, callback) {
+    clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => this.fetch(query, callback), delay);
+  }
+
+  async fetch(query, { url, field, onLoading, onLoaded, onError }) {
+    this.abortController?.abort();
+    this.abortController = new AbortController();
+    onLoading?.(true);
+    const fetchUrl = new URL(url, window.location.href);
+    fetchUrl.searchParams.set(field, query);
+    try {
+      const res = await fetch(fetchUrl, {
+        signal: this.abortController.signal,
+        headers: { Accept: 'text/html', 'X-Requested-With': 'XMLHttpRequest' },
+      });
+      if (!res.ok) throw new Error(`${res.status}`);
+      onLoaded?.(await res.text());
+    } catch (err) {
+      if (err.name !== 'AbortError') onError?.(err);
+    } finally {
+      onLoading?.(false);
+    }
+  }
+
+  cancel() {
+    clearTimeout(this.debounceTimer);
+    this.abortController?.abort();
+  }
+}
+
+export const initComboboxDropdown = (controller, options) => new ComboboxDropdown(controller, options);

package/src/plumbers/content_loader.js

@@ -6,7 +6,7 @@ const defaultOptions = {
   url: '',
   reload: 'never',
   stale: 3600,
-  onLoad: 'contentLoad',
+  onLoad: 'canLoad',
   onLoading: 'contentLoading',
   onLoaded: 'contentLoaded',
 };
@@ -20,7 +20,7 @@ export class ContentLoader extends Plumber {
    * @param {string} [options.url=''] - URL to fetch content from
    * @param {string} [options.reload='never'] - Reload strategy ('never', 'always', or 'stale')
    * @param {number} [options.stale=3600] - Seconds before content becomes stale
-   * @param {string} [options.onLoad='contentLoad'] - Callback name to check if loadable
+   * @param {string} [options.onLoad='canLoad'] - Callback name to check if loadable
    * @param {string} [options.onLoading='contentLoading'] - Callback name to load content
    * @param {string} [options.onLoaded='contentLoaded'] - Callback name after loading
    */

package/src/plumbers/index.js

@@ -3,8 +3,10 @@
  */
 
 export { initCalendar } from './calendar';
+export { initComboboxDropdown } from './combobox_dropdown';
 export { attachContentLoader } from './content_loader';
 export { attachDismisser } from './dismisser';
 export { attachFlipper } from './flipper';
+export { attachInputFormat } from './input_format';
 export { attachShifter } from './shifter';
 export { attachVisibility } from './visibility';

package/src/plumbers/input_format/formatters/credit_card.js

@@ -0,0 +1,69 @@
+/**
+ * Validates a credit card number string using the Luhn algorithm.
+ *
+ * Starting from the rightmost digit, double every second digit. If doubling
+ * produces a number greater than 9, subtract 9 from it. Sum all digits.
+ * A valid card number produces a total divisible by 10.
+ *
+ * @param {string} digits - Digit-only string (no spaces or dashes)
+ * @returns {boolean} true if the number passes the Luhn check
+ */
+function luhn(digits) {
+  let sum = 0;
+  let alternate = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let n = parseInt(digits[i], 10);
+    if (alternate) {
+      n *= 2;
+      if (n > 9) n -= 9;
+    }
+    sum += n;
+    alternate = !alternate;
+  }
+  return sum % 10 === 0;
+}
+
+/** Strips all non-digit characters from raw input */
+const STRIP_NON_DIGITS = /\D/g;
+
+/** Matches a valid card digit count (13–19 digits, no other characters) */
+const VALID_CARD_LENGTH = /^\d{13,19}$/;
+
+/** Captures groups of up to 4 characters followed by at least one more character */
+const GROUP_FOUR_DIGITS = /(.{4})(?=.)/g;
+
+export const CreditCardInputFormatter = {
+  /**
+   * Converts raw input to the canonical stored form: digits only, no separators.
+   * e.g. '4242 4242 4242 4242' → '4242424242424242'
+   * @param {string} raw - Raw input (may contain spaces, dashes, etc.)
+   * @returns {string} Digit-only string, or '' for non-string input
+   */
+  normalize(raw) {
+    if (typeof raw !== 'string') return '';
+    return raw.replace(STRIP_NON_DIGITS, '');
+  },
+
+  /**
+   * Validates the canonical card number using length and Luhn checks.
+   * Expects the output of normalize() — digits only.
+   * @param {string} value - Canonical value from normalize()
+   * @returns {boolean}
+   */
+  validate(value) {
+    if (typeof value !== 'string') return false;
+    if (!VALID_CARD_LENGTH.test(value)) return false;
+    return luhn(value);
+  },
+
+  /**
+   * Formats a canonical card number for display: groups of 4 separated by spaces.
+   * e.g. '4242424242424242' → '4242 4242 4242 4242'
+   * @param {string} value - Canonical value from normalize()
+   * @returns {string} Formatted display string, or '' for non-string input
+   */
+  format(value) {
+    if (typeof value !== 'string') return '';
+    return value.replace(GROUP_FOUR_DIGITS, '$1 ');
+  },
+};

package/src/plumbers/input_format/formatters/currency.js

@@ -0,0 +1,87 @@
+/** Strips everything except digits, period, comma, and negative sign */
+const STRIP_NON_NUMERIC = /[^\d.,-]/g;
+
+/** Matches a valid canonical amount: optional negative sign, digits, optional decimal part */
+const VALID_AMOUNT_PATTERN = /^-?\d+(\.\d+)?$/;
+
+export const CurrencyInputFormatter = {
+  /**
+   * Converts raw input to the canonical stored form: a plain decimal number string.
+   * Handles US format (1,234.56), European format (1.234,56), and integers ($1,000).
+   * The heuristic for ambiguous comma-only input: ≤2 digits after comma → decimal
+   * separator; 3 digits after → thousands separator.
+   * @param {string} raw - Raw input (may contain currency symbols, separators)
+   * @returns {string} Canonical decimal string (e.g. '1234.56'), or '' for non-string/empty
+   */
+  normalize(raw) {
+    if (typeof raw !== 'string') return '';
+    const stripped = raw.replace(STRIP_NON_NUMERIC, '');
+    if (!stripped) return '';
+    const lastComma = stripped.lastIndexOf(',');
+    const lastDot = stripped.lastIndexOf('.');
+
+    if (lastComma > -1 && lastDot > -1) {
+      // Both present: the later one is the decimal separator
+      if (lastComma > lastDot) {
+        // European: 1.234,56 — comma is decimal, dot is thousands
+        return stripped.replace(/\./g, '').replace(',', '.');
+      }
+      // US: 1,234.56 — dot is decimal, comma is thousands
+      return stripped.replace(/,/g, '');
+    }
+
+    if (lastComma > -1) {
+      // Comma only: 1-2 digits after = decimal separator; 3 digits after = thousands separator
+      const afterComma = stripped.slice(lastComma + 1);
+      if (afterComma.length <= 2) return stripped.replace(',', '.');
+      return stripped.replace(/,/g, '');
+    }
+
+    // Dot only or no separator
+    return stripped;
+  },
+
+  /**
+   * Validates the canonical amount: optional negative sign, integer digits,
+   * and an optional decimal part of any length.
+   * @param {string} value - Canonical value from normalize()
+   * @returns {boolean}
+   */
+  validate(value) {
+    if (typeof value !== 'string') return false;
+    return VALID_AMOUNT_PATTERN.test(value);
+  },
+
+  /**
+   * Formats a canonical amount for display using Intl.NumberFormat.
+   * Fraction digit defaults come from the currency itself (e.g. JPY uses 0,
+   * USD uses 2, KWD uses 3) — no hardcoded overrides unless opts.fractionDigits
+   * is explicitly provided.
+   * @param {string} value - Canonical value from normalize()
+   * @param {Object} [opts={}] - Options
+   * @param {string} [opts.locale='en-US'] - BCP 47 locale tag
+   * @param {string} [opts.currency='USD'] - ISO 4217 currency code
+   * @param {number} [opts.fractionDigits] - Override min and max fraction digits
+   * @returns {string} Formatted currency string, or value as-is for non-numeric input
+   */
+  format(value, opts = {}) {
+    if (typeof value !== 'string') return '';
+    const num = parseFloat(value);
+    if (isNaN(num)) return value;
+    const locale = opts.locale || 'en-US';
+    const currency = opts.currency || 'USD';
+    const fractionOpts =
+      opts.fractionDigits !== undefined
+        ? { minimumFractionDigits: opts.fractionDigits, maximumFractionDigits: opts.fractionDigits }
+        : {};
+    try {
+      return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+        ...fractionOpts,
+      }).format(num);
+    } catch {
+      return value;
+    }
+  },
+};

package/src/plumbers/input_format/formatters/date.js

@@ -0,0 +1,98 @@
+/** Matches an ISO 8601 date: YYYY-MM-DD */
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Matches a date with separators: number-sep-number-sep-number (/, -, or .) */
+const SEPARATED_DATE_PATTERN = /^(\d{1,4})[/\-.](\d{1,2})[/\-.](\d{1,4})$/;
+
+/** Strips all non-digit characters (used when extracting 8-digit compact dates) */
+const STRIP_NON_DIGITS = /\D/g;
+
+export const DateInputFormatter = {
+  /**
+   * Converts raw input to the canonical stored form: ISO 8601 YYYY-MM-DD.
+   * Accepts a variety of common date formats:
+   *   - YYYY-MM-DD (ISO, returned unchanged)
+   *   - MM/DD/YYYY, DD/MM/YYYY, YYYY/MM/DD (with /, -, or . separators)
+   *   - YYYYMMDD (8 compact digits, first 4 digits treated as year)
+   * When the first component of a separated date is 4 digits, it is treated as the year.
+   * Otherwise, MM/DD/YYYY ordering is assumed.
+   * @param {string} raw - Raw input in any supported format
+   * @returns {string} ISO date string (YYYY-MM-DD), or '' for non-string input
+   */
+  normalize(raw) {
+    if (typeof raw !== 'string') return '';
+    const trimmed = raw.trim();
+
+    // Already ISO YYYY-MM-DD
+    if (ISO_DATE_PATTERN.test(trimmed)) return trimmed;
+
+    // Date with separators: MM/DD/YYYY, DD/MM/YYYY, or YYYY/MM/DD
+    const sepMatch = trimmed.match(SEPARATED_DATE_PATTERN);
+    if (sepMatch) {
+      const [, a, b, c] = sepMatch;
+      if (a.length === 4) {
+        return `${a}-${b.padStart(2, '0')}-${c.padStart(2, '0')}`;
+      }
+      if (c.length === 4) {
+        // Default MM/DD/YYYY assumption
+        return `${c}-${a.padStart(2, '0')}-${b.padStart(2, '0')}`;
+      }
+    }
+
+    // 8 pure digits: YYYYMMDD or MMDDYYYY
+    const digits = trimmed.replace(STRIP_NON_DIGITS, '');
+    if (digits.length === 8) {
+      const potentialYear = parseInt(digits.slice(0, 4), 10);
+      if (potentialYear >= 1000 && potentialYear <= 9999) {
+        return `${digits.slice(0, 4)}-${digits.slice(4, 6)}-${digits.slice(6, 8)}`;
+      }
+      return `${digits.slice(4, 8)}-${digits.slice(0, 2)}-${digits.slice(2, 4)}`;
+    }
+
+    return trimmed;
+  },
+
+  /**
+   * Validates the input, accepting any format supported by normalize().
+   * Internally normalizes to ISO form first, then checks calendar validity.
+   * e.g. validate('04/13/2025') → true, validate('2025-02-29') → false (not a leap year)
+   * @param {string} value - Input in any format (ISO, MM/DD/YYYY, etc.)
+   * @returns {boolean}
+   */
+  validate(value) {
+    if (typeof value !== 'string') return false;
+    const iso = DateInputFormatter.normalize(value);
+    if (!ISO_DATE_PATTERN.test(iso)) return false;
+    const date = new Date(`${iso}T00:00:00Z`);
+    return !isNaN(date.getTime()) && date.toISOString().startsWith(iso);
+  },
+
+  /**
+   * Formats an ISO date string for display using Intl.DateTimeFormat.
+   * All Intl options are configurable; defaults produce MM/DD/YYYY in en-US.
+   * @param {string} value - Canonical ISO date string (YYYY-MM-DD) from normalize()
+   * @param {Object} [opts={}] - Options
+   * @param {string} [opts.locale='en-US'] - BCP 47 locale tag
+   * @param {string} [opts.timeZone='UTC'] - IANA time zone
+   * @param {string} [opts.year='numeric'] - Intl year format
+   * @param {string} [opts.month='2-digit'] - Intl month format
+   * @param {string} [opts.day='2-digit'] - Intl day format
+   * @returns {string} Formatted date string, or value as-is for invalid input
+   */
+  format(value, opts = {}) {
+    if (typeof value !== 'string') return '';
+    const date = new Date(`${value}T00:00:00Z`);
+    if (isNaN(date.getTime())) return value;
+    const locale = opts.locale || 'en-US';
+    try {
+      return new Intl.DateTimeFormat(locale, {
+        year: opts.year || 'numeric',
+        month: opts.month || '2-digit',
+        day: opts.day || '2-digit',
+        timeZone: opts.timeZone || 'UTC',
+      }).format(date);
+    } catch {
+      return value;
+    }
+  },
+};

package/src/plumbers/input_format/formatters/phone.js

@@ -0,0 +1,73 @@
+/**
+ * Map of E.164 country calling code → expected local digit count.
+ * Key: calling code string (without '+').
+ * Value: local number digit count (excluding the country code).
+ *
+ * Example: '1' → 10 means USA/Canada use a 10-digit local number
+ * (3-digit area code + 7-digit subscriber number).
+ *
+ * Extend this object to add formatting support for additional countries.
+ */
+const DIALING_CODE_LOCAL_DIGITS = {
+  1: 10, // USA, Canada, and NANP countries
+};
+
+/** Strips all non-digit characters */
+const STRIP_NON_DIGITS = /\D/g;
+
+/** Matches an E.164 international phone number: + followed by 7–15 digits */
+const E164_PATTERN = /^\+\d{7,15}$/;
+
+export const PhoneInputFormatter = {
+  /**
+   * Converts raw input to canonical form.
+   * If input starts with '+', produces E.164 (+digits); otherwise strips to digits only.
+   * e.g. '(555) 123-4567' → '5551234567', '+1 555 123 4567' → '+15551234567'
+   * @param {string} raw - Raw input (may contain spaces, dashes, parentheses, etc.)
+   * @returns {string} Canonical string, or '' for non-string input
+   */
+  normalize(raw) {
+    if (typeof raw !== 'string') return '';
+    const hasPlus = raw.trimStart().startsWith('+');
+    const digits = raw.replace(STRIP_NON_DIGITS, '');
+    return hasPlus ? `+${digits}` : digits;
+  },
+
+  /**
+   * Validates the canonical phone number.
+   * Accepts E.164 format or a local number whose digit count appears in DIALING_CODE_LOCAL_DIGITS.
+   * @param {string} value - Canonical value from normalize()
+   * @returns {boolean}
+   */
+  validate(value) {
+    if (typeof value !== 'string') return false;
+    if (E164_PATTERN.test(value)) return true;
+    const digits = value.replace(STRIP_NON_DIGITS, '');
+    return Object.values(DIALING_CODE_LOCAL_DIGITS).includes(digits.length);
+  },
+
+  /**
+   * Formats a canonical phone number for display.
+   * Recognises numbers matching entries in DIALING_CODE_LOCAL_DIGITS.
+   * e.g. '5551234567' → '(555) 123-4567', '+15551234567' → '+1 (555) 123-4567'
+   * Returns value unchanged for unrecognised international numbers.
+   * @param {string} value - Canonical value from normalize()
+   * @returns {string} Formatted display string, or '' for non-string input
+   */
+  format(value) {
+    if (typeof value !== 'string') return '';
+    const digits = value.replace(STRIP_NON_DIGITS, '');
+    for (const [code, localDigits] of Object.entries(DIALING_CODE_LOCAL_DIGITS)) {
+      if (digits.length === localDigits) {
+        // Local number without country code prefix
+        return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
+      }
+      const totalWithCode = localDigits + code.length;
+      if (digits.length === totalWithCode && digits.startsWith(code)) {
+        const local = digits.slice(code.length);
+        return `+${code} (${local.slice(0, 3)}) ${local.slice(3, 6)}-${local.slice(6)}`;
+      }
+    }
+    return value;
+  },
+};

package/src/plumbers/input_format/formatters/plain.js

@@ -0,0 +1,10 @@
+export const PlainInputFormatter = {
+  normalize(raw) {
+    if (typeof raw !== 'string') return '';
+    return raw;
+  },
+
+  validate() {
+    return true;
+  },
+};

package/src/plumbers/input_format/formatters/time.js

@@ -0,0 +1,62 @@
+/** Matches a 24-hour time: HH:MM */
+const H24_PATTERN = /^([01]?\d|2[0-3]):([0-5]\d)$/;
+
+export const TimeInputFormatter = {
+  /**
+   * Converts raw input to canonical 24-hour form: HH:MM.
+   * Accepts HH:MM (24h) and h:mm AM/PM (12h).
+   * @param {string} raw
+   * @returns {string} "HH:MM" or "" for invalid input
+   */
+  normalize(raw) {
+    if (typeof raw !== 'string') return '';
+    const trimmed = raw.trim();
+
+    if (H24_PATTERN.test(trimmed)) {
+      const [h, m] = trimmed.split(':');
+      return `${String(parseInt(h, 10)).padStart(2, '0')}:${m}`;
+    }
+
+    // h:mm AM/PM
+    const ampm = trimmed.match(/^(\d{1,2}):(\d{2})\s*(AM|PM)$/i);
+    if (ampm) {
+      let h = parseInt(ampm[1], 10);
+      const m = ampm[2];
+      const period = ampm[3].toUpperCase();
+      if (period === 'AM') h = h === 12 ? 0 : h;
+      else h = h === 12 ? 12 : h + 12;
+      if (h > 23 || parseInt(m, 10) > 59) return '';
+      return `${String(h).padStart(2, '0')}:${m}`;
+    }
+
+    return '';
+  },
+
+  /**
+   * Validates that the value is a parseable time.
+   * @param {string} value
+   * @returns {boolean}
+   */
+  validate(value) {
+    return TimeInputFormatter.normalize(value) !== '';
+  },
+
+  /**
+   * Formats a canonical HH:MM value for display.
+   * @param {string} value - Canonical "HH:MM" from normalize()
+   * @param {Object} [opts={}]
+   * @param {string} [opts.format='h12'] - 'h12' or 'h24'
+   * @returns {string}
+   */
+  format(value, opts = {}) {
+    if (typeof value !== 'string') return '';
+    const match = value.match(/^(\d{2}):(\d{2})$/);
+    if (!match) return value;
+    const h = parseInt(match[1], 10);
+    const m = match[2];
+    if (opts.format === 'h24') return `${String(h).padStart(2, '0')}:${m}`;
+    const period = h < 12 ? 'AM' : 'PM';
+    const displayH = h % 12 || 12;
+    return `${displayH}:${m} ${period}`;
+  },
+};

package/src/plumbers/input_format/index.js

@@ -0,0 +1,90 @@
+import Plumber from '../plumber';
+import { PlainInputFormatter } from './formatters/plain';
+import { CreditCardInputFormatter } from './formatters/credit_card';
+import { PhoneInputFormatter } from './formatters/phone';
+import { CurrencyInputFormatter } from './formatters/currency';
+import { DateInputFormatter } from './formatters/date';
+import { TimeInputFormatter } from './formatters/time';
+
+export { PlainInputFormatter } from './formatters/plain';
+export { CreditCardInputFormatter } from './formatters/credit_card';
+export { PhoneInputFormatter } from './formatters/phone';
+export { CurrencyInputFormatter } from './formatters/currency';
+export { DateInputFormatter } from './formatters/date';
+export { TimeInputFormatter } from './formatters/time';
+
+export const FORMATTER_TYPES = {
+  PLAIN: 'plain',
+  CREDIT_CARD: 'creditCard',
+  PHONE: 'phone',
+  CURRENCY: 'currency',
+  DATE: 'date',
+  TIME: 'time',
+};
+
+const registry = new Map([
+  [FORMATTER_TYPES.PLAIN, PlainInputFormatter],
+  [FORMATTER_TYPES.CREDIT_CARD, CreditCardInputFormatter],
+  [FORMATTER_TYPES.PHONE, PhoneInputFormatter],
+  [FORMATTER_TYPES.CURRENCY, CurrencyInputFormatter],
+  [FORMATTER_TYPES.DATE, DateInputFormatter],
+  [FORMATTER_TYPES.TIME, TimeInputFormatter],
+]);
+
+const defaultOptions = {
+  type: FORMATTER_TYPES.PLAIN,
+  options: {},
+};
+
+export class InputFormat extends Plumber {
+  /**
+   * Registers a custom input formatter for a given type identifier.
+   * @param {string} type - The type identifier (e.g. 'iban')
+   * @param {Object} formatter - Object with normalize, validate, and optionally format/mask methods
+   */
+  static register(type, formatter) {
+    registry.set(type, formatter);
+  }
+
+  /**
+   * Creates a new InputFormat plumber instance.
+   * @param {Object} controller - Stimulus controller instance
+   * @param {Object} [options] - Configuration options
+   * @param {string} [options.type='plain'] - Formatter type identifier
+   * @param {Object} [options.options={}] - Type-specific options (e.g. locale, currency)
+   */
+  constructor(controller, options = {}) {
+    super(controller, options);
+    this.type = options.type ?? defaultOptions.type;
+    this.options = options.options ?? defaultOptions.options;
+    this.enhance();
+  }
+
+  enhance() {
+    const context = this;
+    const formatter = registry.get(context.type) ?? registry.get(FORMATTER_TYPES.PLAIN);
+
+    const helpers = {
+      normalize: (raw) => formatter.normalize?.(raw, context.options) ?? (typeof raw === 'string' ? raw : ''),
+      validate: (value) => formatter.validate?.(value, context.options) ?? true,
+      format: (value) => formatter.format?.(value, context.options) ?? (typeof value === 'string' ? value : ''),
+      mask: (value) => formatter.mask?.(value, context.options) ?? null,
+      maskable: () => typeof formatter.mask === 'function',
+    };
+
+    Object.defineProperty(this.controller, 'inputFormat', {
+      get() {
+        return helpers;
+      },
+      configurable: true,
+    });
+  }
+}
+
+/**
+ * Factory function to create and attach an InputFormat plumber to a controller.
+ * @param {Object} controller - Stimulus controller instance
+ * @param {Object} [options] - Configuration options
+ * @returns {InputFormat} InputFormat plumber instance
+ */
+export const attachInputFormat = (controller, options) => new InputFormat(controller, options);