ts-util-core 2.0.0

package/src/core/message.ts

@@ -0,0 +1,212 @@
+// ---------------------------------------------------------------------------
+// MSG module — vanilla DOM dialog system (no 3rd-party dependency)
+//
+// Design patterns used:
+//   - Facade Pattern : simple `info()`, `modal()`, `confirm()` API over
+//                      raw DOM creation + CSS styling
+//   - Strategy Pattern : appearance is controlled via CSS classes, consumers
+//                        can override styling without touching this module
+// ---------------------------------------------------------------------------
+
+import type { MessageOptions } from '../types.js';
+
+const OVERLAY_CLASS = 'rs-msg-overlay';
+const DIALOG_CLASS = 'rs-msg-dialog';
+const TITLE_CLASS = 'rs-msg-title';
+const BODY_CLASS = 'rs-msg-body';
+const BUTTON_BAR_CLASS = 'rs-msg-buttons';
+const BUTTON_CLASS = 'rs-msg-btn';
+
+let injectedStyles = false;
+
+function injectStyles(): void {
+  if (injectedStyles) return;
+  injectedStyles = true;
+
+  const css = `
+    .${OVERLAY_CLASS} {
+      position: fixed; inset: 0;
+      background: rgba(0,0,0,0.4);
+      display: flex; align-items: center; justify-content: center;
+      z-index: 10000;
+      animation: rs-fade-in 0.15s ease-out;
+    }
+    .${DIALOG_CLASS} {
+      background: #fff; border-radius: 8px;
+      box-shadow: 0 8px 32px rgba(0,0,0,0.25);
+      min-width: 300px; max-width: 520px;
+      padding: 0; overflow: hidden;
+      animation: rs-slide-up 0.2s ease-out;
+    }
+    .${TITLE_CLASS} {
+      padding: 16px 20px; font-weight: 600; font-size: 15px;
+      border-bottom: 1px solid #eee;
+    }
+    .${BODY_CLASS} {
+      padding: 20px; font-size: 14px; line-height: 1.6;
+    }
+    .${BUTTON_BAR_CLASS} {
+      padding: 12px 20px; display: flex; justify-content: flex-end; gap: 8px;
+      border-top: 1px solid #eee;
+    }
+    .${BUTTON_CLASS} {
+      padding: 8px 18px; border: 1px solid #ccc; border-radius: 4px;
+      background: #fff; cursor: pointer; font-size: 14px;
+      transition: background 0.15s;
+    }
+    .${BUTTON_CLASS}:hover { background: #f5f5f5; }
+    .${BUTTON_CLASS}[data-primary] {
+      background: #2563eb; color: #fff; border-color: #2563eb;
+    }
+    .${BUTTON_CLASS}[data-primary]:hover { background: #1d4ed8; }
+    @keyframes rs-fade-in { from { opacity: 0; } to { opacity: 1; } }
+    @keyframes rs-slide-up {
+      from { transform: translateY(20px); opacity: 0; }
+      to   { transform: translateY(0);    opacity: 1; }
+    }
+  `;
+
+  const style = document.createElement('style');
+  style.textContent = css;
+  document.head.appendChild(style);
+}
+
+interface DialogHandle {
+  close: () => void;
+  element: HTMLElement;
+}
+
+function createDialog(
+  message: string,
+  options: {
+    title?: string;
+    buttons?: { label: string; value: string; primary?: boolean }[];
+    onButton?: (value: string) => void;
+    modal?: boolean;
+  } = {},
+): DialogHandle {
+  injectStyles();
+
+  const overlay = document.createElement('div');
+  overlay.className = OVERLAY_CLASS;
+
+  const dialog = document.createElement('div');
+  dialog.className = DIALOG_CLASS;
+  dialog.setAttribute('role', 'dialog');
+  dialog.setAttribute('aria-modal', String(!!options.modal));
+
+  // Title
+  if (options.title) {
+    const titleEl = document.createElement('div');
+    titleEl.className = TITLE_CLASS;
+    titleEl.textContent = options.title;
+    dialog.appendChild(titleEl);
+  }
+
+  // Body
+  const body = document.createElement('div');
+  body.className = BODY_CLASS;
+  body.innerHTML = message;
+  dialog.appendChild(body);
+
+  // Buttons
+  if (options.buttons && options.buttons.length > 0) {
+    const bar = document.createElement('div');
+    bar.className = BUTTON_BAR_CLASS;
+
+    for (const btn of options.buttons) {
+      const el = document.createElement('button');
+      el.className = BUTTON_CLASS;
+      el.textContent = btn.label;
+      if (btn.primary) el.setAttribute('data-primary', '');
+      el.addEventListener('click', () => {
+        options.onButton?.(btn.value);
+        close();
+      });
+      bar.appendChild(el);
+    }
+    dialog.appendChild(bar);
+  }
+
+  overlay.appendChild(dialog);
+  document.body.appendChild(overlay);
+
+  // Close on overlay click (if not modal)
+  if (!options.modal) {
+    overlay.addEventListener('click', (e) => {
+      if (e.target === overlay) close();
+    });
+  }
+
+  function close(): void {
+    overlay.remove();
+  }
+
+  return { close, element: overlay };
+}
+
+export class Message {
+  private currentModal: DialogHandle | null = null;
+
+  /**
+   * Show a brief informational message. Auto-closes after `options.autoclose` ms.
+   */
+  info(message: string, options: MessageOptions = {}): DialogHandle {
+    const { autoclose = 5000, title } = options;
+
+    const handle = createDialog(message, { title });
+
+    if (autoclose > 0) {
+      setTimeout(() => handle.close(), autoclose);
+    }
+
+    return handle;
+  }
+
+  /**
+   * Show a modal dialog that must be explicitly dismissed.
+   */
+  modal(message: string, options: MessageOptions = {}): DialogHandle {
+    this.dismissModal();
+
+    const handle = createDialog(message, {
+      title: options.title,
+      modal: true,
+      buttons: [{ label: 'OK', value: 'ok', primary: true }],
+    });
+
+    this.currentModal = handle;
+    return handle;
+  }
+
+  /**
+   * Show a Yes/No confirmation dialog. Executes `onConfirm` if "Yes" is chosen.
+   *
+   * @returns A `DialogHandle` for programmatic control.
+   */
+  confirm(
+    title: string,
+    message: string,
+    onConfirm: () => void,
+  ): DialogHandle {
+    return createDialog(message, {
+      title,
+      modal: true,
+      buttons: [
+        { label: 'Yes', value: 'Y', primary: true },
+        { label: 'No', value: 'N' },
+      ],
+      onButton: (val) => {
+        if (val === 'Y') onConfirm();
+      },
+    });
+  }
+
+  /**
+   * Close the currently open modal (if any).
+   */
+  dismissModal(): void {
+    this.currentModal?.close();
+    this.currentModal = null;
+  }
+}

package/src/core/view.ts

@@ -0,0 +1,101 @@
+// ---------------------------------------------------------------------------
+// VIEW module — load HTML fragments via AJAX and initialize them
+//
+// Design patterns used:
+//   - Observer Pattern  : `beforeLoad` hooks run on every loaded fragment
+//   - Facade Pattern    : `load()` handles fetch → parse → init → inject
+// ---------------------------------------------------------------------------
+
+import type { EventEmitter } from './event-emitter.js';
+import type { AppEventMap, ViewLoadParams } from '../types.js';
+import type { Ajax } from './ajax.js';
+import { parseHTML } from '../utils/dom.js';
+
+export type BeforeLoadHook = (context: HTMLElement) => void;
+
+export class View {
+  private emitter: EventEmitter<AppEventMap>;
+  private ajax: Ajax;
+  private beforeLoadHooks: BeforeLoadHook[] = [];
+
+  constructor(emitter: EventEmitter<AppEventMap>, ajax: Ajax) {
+    this.emitter = emitter;
+    this.ajax = ajax;
+  }
+
+  /**
+   * Register a function that runs on every DOM fragment before it is inserted.
+   *
+   * This is the **Observer pattern** — modules self-register their
+   * initialization logic without the core knowing about them.
+   *
+   * @returns An unregister function.
+   *
+   * @example
+   * ```ts
+   * // Validation module registers itself
+   * VIEW.addBeforeLoad((context) => {
+   *   context.querySelectorAll('[constraint~="date"]').forEach(setupDatepicker);
+   * });
+   *
+   * // Format module registers itself
+   * VIEW.addBeforeLoad((context) => {
+   *   context.querySelectorAll('[format]').forEach(applyMask);
+   * });
+   * ```
+   */
+  addBeforeLoad(hook: BeforeLoadHook): () => void {
+    this.beforeLoadHooks.push(hook);
+    return () => {
+      const idx = this.beforeLoadHooks.indexOf(hook);
+      if (idx !== -1) this.beforeLoadHooks.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Run all registered `beforeLoad` hooks on a DOM element.
+   * Also emits the `view:beforeLoad` event for event-based listeners.
+   */
+  invokeBeforeLoad(context: HTMLElement): void {
+    for (const hook of this.beforeLoadHooks) {
+      hook(context);
+    }
+    this.emitter.emit('view:beforeLoad', { context });
+  }
+
+  /**
+   * Fetch HTML from a URL, run all beforeLoad hooks, then inject into `target`.
+   *
+   * @param target - The container element to inject into.
+   * @param params - Request parameters (url, data, form, etc.).
+   */
+  async load(target: HTMLElement, params: ViewLoadParams): Promise<void> {
+    const { success, ...requestParams } = params;
+
+    await this.ajax.request({
+      ...requestParams,
+      success: async (data) => {
+        const response = data as Response;
+        const html = await response.text();
+        const fragment = parseHTML(html);
+
+        // Wrap in a container so hooks can querySelector on it
+        const wrapper = document.createElement('div');
+        wrapper.appendChild(fragment);
+
+        this.invokeBeforeLoad(wrapper);
+        target.innerHTML = '';
+        target.appendChild(wrapper);
+
+        success?.(wrapper);
+      },
+    });
+  }
+
+  /**
+   * Initialize the entire page body — should be called once on DOMContentLoaded.
+   */
+  initPage(): void {
+    this.invokeBeforeLoad(document.body);
+  }
+}

package/src/formatting/formatters.ts

@@ -0,0 +1,118 @@
+// ---------------------------------------------------------------------------
+// Built-in formatters — vanilla input masking (no 3rd-party dependency)
+//
+// Replaces jquery.maskedinput with a lightweight mask engine.
+//
+// Design patterns used:
+//   - Strategy Pattern : each formatter is an independent strategy
+//   - Template Method  : all formatters share the same `applyMask` core,
+//                        only the mask definition varies
+// ---------------------------------------------------------------------------
+
+import type { Formatter } from '../types.js';
+
+/**
+ * Mask characters:
+ *   `9` → digit (0-9)
+ *   `A` → uppercase letter (A-Z)
+ *   `?` → makes the rest of the mask optional
+ *   Any other character → literal (inserted automatically)
+ */
+function applyMask(element: HTMLInputElement, mask: string): void {
+  // Find the position where `?` appears (optional section starts)
+  const optionalIdx = mask.indexOf('?');
+  const cleanMask = mask.replace('?', '');
+
+  function formatValue(raw: string): string {
+    let result = '';
+    let rawIdx = 0;
+
+    for (let maskIdx = 0; maskIdx < cleanMask.length && rawIdx < raw.length; maskIdx++) {
+      const maskChar = cleanMask[maskIdx]!;
+
+      if (maskChar === '9') {
+        // Expect digit
+        while (rawIdx < raw.length && !/\d/.test(raw[rawIdx]!)) rawIdx++;
+        if (rawIdx < raw.length) {
+          result += raw[rawIdx]!;
+          rawIdx++;
+        } else {
+          break;
+        }
+      } else if (maskChar === 'A') {
+        // Expect uppercase letter
+        while (rawIdx < raw.length && !/[A-Z]/i.test(raw[rawIdx]!)) rawIdx++;
+        if (rawIdx < raw.length) {
+          result += raw[rawIdx]!.toUpperCase();
+          rawIdx++;
+        } else {
+          break;
+        }
+      } else {
+        // Literal — insert it
+        result += maskChar;
+        // If the raw char matches the literal, skip it
+        if (raw[rawIdx] === maskChar) rawIdx++;
+      }
+    }
+
+    return result;
+  }
+
+  function getPlaceholder(): string {
+    const required = optionalIdx >= 0 ? cleanMask.substring(0, optionalIdx) : cleanMask;
+    return required
+      .replace(/9/g, '_')
+      .replace(/A/g, '_');
+  }
+
+  // Set placeholder to show expected format
+  if (!element.placeholder) {
+    element.placeholder = getPlaceholder();
+  }
+
+  element.addEventListener('input', () => {
+    const pos = element.selectionStart ?? 0;
+    const oldLen = element.value.length;
+    element.value = formatValue(element.value);
+    const newLen = element.value.length;
+    // Preserve cursor position intelligently
+    const newPos = pos + (newLen - oldLen);
+    element.setSelectionRange(newPos, newPos);
+  });
+
+  element.addEventListener('blur', () => {
+    element.value = formatValue(element.value);
+  });
+
+  // Format the initial value if present
+  if (element.value) {
+    element.value = formatValue(element.value);
+  }
+}
+
+// -- Built-in formatter definitions -----------------------------------------
+
+/** Taiwan ID number: A123456789 */
+export const idNumberFormatter: Formatter = {
+  key: 'idNumber',
+  format: (el) => applyMask(el, 'A999999999'),
+};
+
+/** Date: YYYY-MM-DD (day is optional via `?`) */
+export const dateFormatter: Formatter = {
+  key: 'date',
+  format: (el) => applyMask(el, '9999-99?-99'),
+};
+
+/** Time: HH:MM */
+export const timeFormatter: Formatter = {
+  key: 'time',
+  format: (el) => applyMask(el, '99:99'),
+};
+
+export const builtInFormatters: Formatter[] = [
+  idNumberFormatter,
+  dateFormatter,
+  timeFormatter,
+];

package/src/formatting/registry.ts

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// Formatter Registry — register and apply input formatters by key
+//
+// Design patterns used:
+//   - Registry Pattern : formatters stored by key, resolved at runtime
+//   - Observer Pattern : integrates with VIEW.addBeforeLoad for auto-init
+//   - Open/Closed      : add new formatters without modifying existing code
+// ---------------------------------------------------------------------------
+
+import type { Formatter } from '../types.js';
+
+/**
+ * Manages input formatters keyed by name.
+ *
+ * Elements declare their desired format via the `format` HTML attribute.
+ * The registry matches elements to their formatter at initialization time.
+ *
+ * @example
+ * ```ts
+ * registry.add({ key: 'phone', format: (el) => applyPhoneMask(el) });
+ *
+ * // In HTML:
+ * // <input type="text" format="phone" />
+ * ```
+ */
+export class FormatterRegistry {
+  private formatters = new Map<string, Formatter>();
+
+  /**
+   * Register a formatter. If a formatter with the same key exists, it is replaced.
+   */
+  add(formatter: Formatter): void {
+    this.formatters.set(formatter.key, formatter);
+  }
+
+  /**
+   * Apply registered formatters to all elements with a `format` attribute
+   * within the given context.
+   *
+   * This is the **beforeLoad hook** — registered with `VIEW.addBeforeLoad`
+   * so dynamically loaded content also gets formatted.
+   */
+  applyAll(context: HTMLElement): void {
+    const elements = context.querySelectorAll<HTMLInputElement>('[format]');
+
+    for (const el of elements) {
+      const key = el.getAttribute('format');
+      if (!key) continue;
+      const formatter = this.formatters.get(key);
+      formatter?.format(el);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+// ---------------------------------------------------------------------------
+// ts-util-core — barrel export
+//
+// This is the main entry point. It wires all modules together and exposes
+// the unified `#` (TS-Util) namespace.
+//
+// Usage with ES modules (recommended):
+//
+//   import { AJAX, VIEW, MSG, Validation, Formatter } from 'ts-util-core';
+//
+//   // or as a single namespace:
+//   import * as RS from 'ts-util-core';
+//   RS.AJAX.request({ url: '/api/save', form: myForm });
+//
+// Usage as a global (for non-module scripts):
+//
+//   The library auto-registers `window.#` (accessed via `window['#']`)
+//   when loaded in a <script> tag without `type="module"`.
+//
+// Design patterns used:
+//   - Facade Pattern  : one import gives access to all features
+//   - Mediator Pattern : the EventEmitter is the central coordinator —
+//                        modules don't reference each other directly,
+//                        they communicate through events
+// ---------------------------------------------------------------------------
+
+// Re-export types for consumers
+export type {
+  ConstraintType,
+  FormDataRecord,
+  AjaxRequestParams,
+  AjaxJsonRequestParams,
+  ViewLoadParams,
+  MessageOptions,
+  Formatter as FormatterDefinition,
+  AppEventMap,
+  ValidationResult,
+  TextareaValidationResult,
+} from './types.js';
+
+export type { ConstraintHandler } from './validation/constraints.js';
+export type { BeforeLoadHook } from './core/view.js';
+
+// Re-export classes for advanced use
+export { EventEmitter } from './core/event-emitter.js';
+export { Ajax } from './core/ajax.js';
+export { View } from './core/view.js';
+export { Message } from './core/message.js';
+export { Validator } from './validation/validator.js';
+export { FormatterRegistry } from './formatting/registry.js';
+
+// Re-export utilities
+export { sprintf } from './utils/sprintf.js';
+export { formToJSON, isDateValid, parseHTML, scrollToElement, defaults } from './utils/dom.js';
+
+// ---------------------------------------------------------------------------
+// Pre-wired singleton instances — the `#` namespace
+// ---------------------------------------------------------------------------
+
+import { EventEmitter } from './core/event-emitter.js';
+import { Ajax } from './core/ajax.js';
+import { View } from './core/view.js';
+import { Message } from './core/message.js';
+import { Validator } from './validation/validator.js';
+import { FormatterRegistry } from './formatting/registry.js';
+import { builtInFormatters } from './formatting/formatters.js';
+import type { AppEventMap } from './types.js';
+
+// 1. Create the shared event bus (Mediator)
+const emitter = new EventEmitter<AppEventMap>();
+
+// 2. Instantiate modules — they receive the emitter, not each other
+const ajax = new Ajax(emitter);
+const view = new View(emitter, ajax);
+const msg = new Message();
+const validator = new Validator(emitter);
+const formatter = new FormatterRegistry();
+
+// 3. Wire cross-module dependencies via hooks (Observer Pattern)
+//    — The Validator tells the AJAX module how to validate forms
+ajax.setValidator((form) => validator.validate(form));
+
+//    — The Validator registers its beforeLoad hook with VIEW
+view.addBeforeLoad((context) => validator.initConstraints(context));
+
+//    — The FormatterRegistry registers its beforeLoad hook with VIEW
+view.addBeforeLoad((context) => formatter.applyAll(context));
+
+// 4. Register built-in formatters
+for (const f of builtInFormatters) {
+  formatter.add(f);
+}
+
+// 5. Export pre-wired instances as the public API
+/** AJAX module — HTTP requests with lifecycle hooks. */
+export const AJAX = ajax;
+
+/** VIEW module — load and initialize HTML fragments. */
+export const VIEW = view;
+
+/** MSG module — dialogs and notifications. */
+export const MSG = msg;
+
+/** Validation module — form validation engine. */
+export const Validation = validator;
+
+/** Formatter module — input masking registry. */
+export const Formatter = formatter;
+
+/** Event bus — subscribe to library-wide lifecycle events. */
+export const Events = emitter;
+
+// ---------------------------------------------------------------------------
+// Auto-initialize on DOMContentLoaded (when running in a browser)
+// ---------------------------------------------------------------------------
+
+if (typeof document !== 'undefined') {
+  const init = () => view.initPage();
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Global registration for non-module environments:  window['#']
+// ---------------------------------------------------------------------------
+
+if (typeof window !== 'undefined') {
+  const ns = {
+    AJAX: ajax,
+    VIEW: view,
+    MSG: msg,
+    Validation: validator,
+    Formatter: formatter,
+    Events: emitter,
+  };
+
+  (window as unknown as Record<string, unknown>)['#'] = ns;
+}