@stimulus-plumbers/controllers 0.2.7 → 0.2.9

package/src/controllers/input_format_controller.js

@@ -0,0 +1,94 @@
+import { Controller } from '@hotwired/stimulus';
+import { setPressed } from '../aria';
+import { attachFormatter } from '../plumbers';
+
+export default class extends Controller {
+  static targets = ['input', 'toggle'];
+  static values = {
+    type: { type: String, default: 'plain' },
+    options: { type: Object, default: {} },
+    revealed: { type: Boolean, default: false },
+  };
+
+  connect() {
+    attachFormatter(this, { type: this.typeValue, options: this.optionsValue });
+    this.format(this.readValue());
+    this.drawToggle();
+  }
+
+  typeValueChanged() {
+    if (!this.formatter) return;
+    attachFormatter(this, { type: this.typeValue, options: this.optionsValue });
+    this.format(this.readValue());
+    this.drawToggle();
+  }
+
+  optionsValueChanged() {
+    if (!this.formatter) return;
+    attachFormatter(this, { type: this.typeValue, options: this.optionsValue });
+    this.format(this.readValue());
+  }
+
+  revealedValueChanged() {
+    if (!this.formatter) return;
+    this.format(this.readValue());
+    this.drawToggle();
+  }
+
+  onChange(event) {
+    this.format(event?.detail?.value ?? '');
+  }
+
+  format(value) {
+    if (!this.formatter) return;
+    this.onFormatting(value);
+  }
+
+  toggle() {
+    if (!this.formatter.maskable() && this.typeValue !== 'password') return;
+    this.revealedValue = !this.revealedValue;
+  }
+
+  onPaste(event) {
+    const raw = event.detail?.text ?? '';
+    if (!this.formatter || !raw) return;
+    const value = this.formatter.normalize(raw);
+    if (!this.formatter.validate(value)) return;
+    this.format(value);
+  }
+
+  drawToggle() {
+    if (!this.hasToggleTarget) return;
+    const hasToggleBehavior = this.formatter?.maskable() || this.typeValue === 'password';
+    this.toggleTarget.hidden = !hasToggleBehavior;
+    if (hasToggleBehavior) setPressed(this.toggleTarget, this.revealedValue);
+  }
+
+  readValue() {
+    if (!this.hasInputTarget) return '';
+    return this.inputTarget instanceof HTMLInputElement ? this.inputTarget.value : this.inputTarget.textContent;
+  }
+
+  onFormatting(raw) {
+    if (!this.formatter) return;
+
+    if (this.typeValue === 'password') {
+      if (this.hasInputTarget) this.inputTarget.type = this.revealedValue ? 'text' : 'password';
+      return;
+    }
+
+    const value = this.formatter.normalize(raw);
+    const formatted =
+      this.revealedValue || !this.formatter.maskable() ? this.formatter.format(value) : this.formatter.mask(value);
+
+    if (this.hasInputTarget) {
+      if (this.inputTarget instanceof HTMLInputElement) {
+        this.inputTarget.value = formatted;
+      } else {
+        this.inputTarget.textContent = formatted;
+      }
+    }
+
+    this.dispatch('formatted', { detail: { value: formatted } });
+  }
+}

package/src/controllers/input_search_controller.js

@@ -0,0 +1,44 @@
+import { Controller } from '@hotwired/stimulus';
+
+export default class extends Controller {
+  static targets = ['input', 'clear'];
+
+  initialize() {
+    this.onInput = this.draw.bind(this);
+    this.onEscape = this.handleEscape.bind(this);
+  }
+
+  connect() {
+    this.draw();
+  }
+
+  inputTargetConnected(input) {
+    input.addEventListener('input', this.onInput);
+    input.addEventListener('keydown', this.onEscape);
+  }
+
+  inputTargetDisconnected(input) {
+    input.removeEventListener('input', this.onInput);
+    input.removeEventListener('keydown', this.onEscape);
+  }
+
+  clear() {
+    if (!this.hasInputTarget) return;
+    this.inputTarget.value = '';
+    this.draw();
+    this.inputTarget.focus();
+    this.inputTarget.dispatchEvent(new Event('input', { bubbles: true }));
+  }
+
+  draw() {
+    if (!this.hasInputTarget || !this.hasClearTarget) return;
+    this.clearTarget.hidden = this.inputTarget.value.length === 0;
+  }
+
+  handleEscape(event) {
+    if (event.key !== 'Escape') return;
+    if (this.inputTarget.value === '') return;
+    event.preventDefault();
+    this.clear();
+  }
+}

package/src/controllers/modal_controller.js

@@ -3,31 +3,34 @@ 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 {
+export default class extends Controller {
   static targets = ['modal', 'overlay'];
 
+  initialize() {
+    this.onCancel = this.close.bind(this);
+  }
+
   connect() {
     if (!this.hasModalTarget) {
       console.error('ModalController requires a modal target. Add data-modal-target="modal" to your element.');
-      return;
     }
+  }
 
-    this.isNativeDialog = this.modalTarget instanceof HTMLDialogElement;
-
+  modalTargetConnected(modal) {
+    this.isNativeDialog = modal instanceof HTMLDialogElement;
     if (this.isNativeDialog) {
-      this.modalTarget.addEventListener('cancel', this.close);
-      this.modalTarget.addEventListener('click', this.handleBackdropClick);
+      modal.addEventListener('cancel', this.onCancel);
+      modal.addEventListener('click', this.onBackdropClick);
     } else {
-      this.focusTrap = new FocusTrap(this.modalTarget, {
-        escapeDeactivates: true,
-      });
+      this.focusTrap = new FocusTrap(modal, { escapeDeactivates: true });
+      attachDismisser(this, { element: modal });
+    }
+  }
 
-      attachDismisser(this, { element: this.modalTarget });
+  modalTargetDisconnected(modal) {
+    if (this.isNativeDialog) {
+      modal.removeEventListener('cancel', this.onCancel);
+      modal.removeEventListener('click', this.onBackdropClick);
     }
   }
 
@@ -35,13 +38,6 @@ export default class ModalController extends Controller {
     this.close();
   };
 
-  disconnect() {
-    if (this.isNativeDialog) {
-      this.modalTarget.removeEventListener('cancel', this.close);
-      this.modalTarget.removeEventListener('click', this.handleBackdropClick);
-    }
-  }
-
   open(event) {
     if (event) event.preventDefault();
     if (!this.hasModalTarget) return;
@@ -89,7 +85,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

@@ -10,12 +10,20 @@ export * from './focus.js';
 export * from './keyboard.js';
 export * from './aria.js';
 
+export { Formatter, FORMATTER_TYPES } from './plumbers/formatter.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 InputSearchController } from './controllers/input_search_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/formatter.js

@@ -0,0 +1,65 @@
+import Plumber from './plumber';
+import { PlainFormatter } from './formatters/plain';
+import { CreditCardFormatter } from './formatters/credit_card';
+import { PhoneFormatter } from './formatters/phone';
+import { CurrencyFormatter } from './formatters/currency';
+import { DateFormatter } from './formatters/date';
+import { TimeFormatter } 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, PlainFormatter],
+  [FORMATTER_TYPES.CREDIT_CARD, CreditCardFormatter],
+  [FORMATTER_TYPES.PHONE, PhoneFormatter],
+  [FORMATTER_TYPES.CURRENCY, CurrencyFormatter],
+  [FORMATTER_TYPES.DATE, DateFormatter],
+  [FORMATTER_TYPES.TIME, TimeFormatter],
+]);
+
+const defaultOptions = {
+  type: FORMATTER_TYPES.PLAIN,
+  options: {},
+};
+
+export class Formatter extends Plumber {
+  static register(type, formatter) {
+    registry.set(type, formatter);
+  }
+
+  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, 'formatter', {
+      get() {
+        return helpers;
+      },
+      configurable: true,
+    });
+  }
+}
+
+export const attachFormatter = (controller, options) => new Formatter(controller, options);

package/src/plumbers/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 CreditCardFormatter = {
+  /**
+   * 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/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 CurrencyFormatter = {
+  /**
+   * 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/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 DateFormatter = {
+  /**
+   * 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 = DateFormatter.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;
+    }
+  },
+};