ts-util-core 2.0.0

package/src/types.ts

@@ -0,0 +1,85 @@
+// ---------------------------------------------------------------------------
+// Shared type definitions for ts-util-core
+// ---------------------------------------------------------------------------
+
+/** Supported constraint types declared via the `constraint` HTML attribute. */
+export type ConstraintType =
+  | 'required'
+  | 'date'
+  | 'number'
+  | 'time'
+  | 'upperCase'
+  | 'onlyEn';
+
+/** A record whose values are either a single string or an array of strings. */
+export type FormDataRecord = Record<string, string | string[]>;
+
+// -- AJAX -------------------------------------------------------------------
+
+export interface AjaxRequestParams {
+  url: string;
+  data?: Record<string, unknown>;
+  form?: HTMLElement;
+  ignoreDisabled?: boolean;
+  noblock?: boolean;
+  headers?: Record<string, string>;
+  success?: (data: unknown) => void;
+  error?: (error: Error) => void;
+  complete?: () => void;
+}
+
+export interface AjaxJsonRequestParams<T = unknown> extends Omit<AjaxRequestParams, 'success'> {
+  success?: (data: T) => void;
+}
+
+// -- VIEW -------------------------------------------------------------------
+
+export interface ViewLoadParams extends Omit<AjaxRequestParams, 'success'> {
+  success?: (content: HTMLElement) => void;
+}
+
+// -- MSG --------------------------------------------------------------------
+
+export interface MessageOptions {
+  autoclose?: number;
+  title?: string;
+}
+
+export interface ConfirmButton {
+  label: string;
+  value: string;
+}
+
+// -- Validation -------------------------------------------------------------
+
+export interface ValidationResult {
+  valid: boolean;
+  invalidElements: HTMLElement[];
+  labelNames: string[];
+}
+
+export interface TextareaValidationResult extends ValidationResult {
+  maxlengths: number[];
+}
+
+// -- Formatting -------------------------------------------------------------
+
+export interface Formatter {
+  key: string;
+  format: (element: HTMLInputElement) => void;
+}
+
+// -- Hook / Event Map -------------------------------------------------------
+
+export interface AppEventMap {
+  'ajax:before': { url: string };
+  'ajax:after': { url: string };
+  'ajax:error': { url: string; error: Error };
+  'view:beforeLoad': { context: HTMLElement };
+  'validation:invalid': { labelNames: string[]; elements: HTMLElement[] };
+  'validation:textareaTooLong': {
+    labelNames: string[];
+    maxlengths: number[];
+    elements: HTMLElement[];
+  };
+}

package/src/utils/dom.ts

@@ -0,0 +1,105 @@
+// ---------------------------------------------------------------------------
+// DOM utility functions — vanilla TypeScript replacements for jQuery helpers
+//
+// Design patterns used:
+//   - Facade Pattern : simple API over verbose native DOM methods
+// ---------------------------------------------------------------------------
+
+import type { FormDataRecord } from '../types.js';
+
+/**
+ * Convert all named form elements within a container to a key-value record.
+ *
+ * Replaces the original jQuery-based `formToJSON`.
+ *
+ * @param container - The DOM element containing form inputs.
+ * @param options.ignoreDisabled - Skip disabled elements (default `false`).
+ *
+ * @example
+ * ```ts
+ * const data = formToJSON(document.getElementById('myForm')!);
+ * // { username: "alice", roles: ["admin", "editor"] }
+ * ```
+ */
+export function formToJSON(
+  container: HTMLElement,
+  options: { ignoreDisabled?: boolean } = {},
+): FormDataRecord {
+  const { ignoreDisabled = false } = options;
+
+  const selectors =
+    'input[name], textarea[name], select[name]';
+  let elements = Array.from(
+    container.querySelectorAll<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>(selectors),
+  );
+
+  if (ignoreDisabled) {
+    elements = elements.filter((el) => !el.disabled);
+  }
+
+  const params: FormDataRecord = {};
+
+  for (const el of elements) {
+    const name = el.name;
+    if (!name) continue;
+
+    if (el instanceof HTMLInputElement && el.type === 'checkbox') {
+      if (!(name in params)) params[name] = [];
+      if (el.checked) (params[name] as string[]).push(el.value);
+    } else if (el instanceof HTMLSelectElement && el.multiple) {
+      if (!(name in params)) params[name] = [];
+      const selected = Array.from(el.selectedOptions).map((o) => o.value);
+      (params[name] as string[]).push(...selected);
+    } else if (el instanceof HTMLInputElement && el.type === 'radio') {
+      if (el.checked) params[name] = el.value;
+    } else {
+      const existing = params[name];
+      if (existing === undefined) {
+        params[name] = el.value;
+      } else if (typeof existing === 'string') {
+        params[name] = [existing, el.value];
+      } else {
+        existing.push(el.value);
+      }
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Check whether a value is a valid date.
+ *
+ * Accepts a `Date` object or a string in `yyyy-MM-dd` / `yyyy/MM/dd` format.
+ */
+export function isDateValid(date: Date | string): boolean {
+  if (date instanceof Date) return !isNaN(date.getTime());
+  return /^\d{4}[/-]\d{1,2}[/-]\d{1,2}$/.test(date);
+}
+
+/**
+ * Parse an HTML string into a `DocumentFragment`.
+ */
+export function parseHTML(html: string): DocumentFragment {
+  const template = document.createElement('template');
+  template.innerHTML = html.trim();
+  return template.content;
+}
+
+/**
+ * Smoothly scroll an element into view.
+ */
+export function scrollToElement(element: HTMLElement): void {
+  element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+}
+
+/**
+ * Merge multiple option objects (shallow). Later sources override earlier ones.
+ * A typed, zero-dependency replacement for `$.extend()`.
+ */
+export function defaults<T extends Record<string, unknown>>(
+  base: T,
+  ...overrides: Partial<T>[]
+): T {
+  return Object.assign({}, base, ...overrides);
+}

package/src/utils/sprintf.ts

@@ -0,0 +1,141 @@
+// ---------------------------------------------------------------------------
+// sprintf — printf-style string formatting
+//
+// Design patterns used:
+//   - Pure Function : no side effects, deterministic output
+// ---------------------------------------------------------------------------
+
+interface FormatMatch {
+  match: string;
+  left: boolean;
+  sign: string;
+  pad: string;
+  min: number;
+  precision: number | undefined;
+  code: string;
+  negative: boolean;
+  argument: string;
+}
+
+function convert(m: FormatMatch, nosign = false): string {
+  const sign = nosign ? '' : m.negative ? '-' : m.sign;
+  const padLen = m.min - m.argument.length + 1 - sign.length;
+  const pad = padLen > 0 ? m.pad.repeat(padLen) : '';
+
+  if (!m.left) {
+    return m.pad === '0' || nosign
+      ? sign + pad + m.argument
+      : pad + sign + m.argument;
+  }
+  return m.pad === '0' || nosign
+    ? sign + m.argument + pad.replace(/0/g, ' ')
+    : sign + m.argument + pad;
+}
+
+/**
+ * C-style `sprintf` implementation.
+ *
+ * Supported format specifiers: `%b` `%c` `%d` `%f` `%o` `%s` `%x` `%X` `%%`
+ *
+ * @example
+ * ```ts
+ * sprintf("Hello %s, you are %d years old", "Alice", 30)
+ * // → "Hello Alice, you are 30 years old"
+ *
+ * sprintf("%05d", 42)
+ * // → "00042"
+ * ```
+ */
+export function sprintf(format: string, ...args: unknown[]): string {
+  const exp =
+    /(%([%]|(-)?(\+|\x20)?(0)?(\d+)?(\.(\d)?)?([bcdfosxX])))/g;
+  const matches: FormatMatch[] = [];
+  const strings: string[] = [];
+  let convCount = 0;
+  let matchPosEnd = 0;
+  let result: RegExpExecArray | null;
+
+  while ((result = exp.exec(format)) !== null) {
+    if (result[9]) convCount++;
+
+    const stringPosStart = matchPosEnd;
+    const stringPosEnd = exp.lastIndex - result[0].length;
+    strings.push(format.substring(stringPosStart, stringPosEnd));
+    matchPosEnd = exp.lastIndex;
+
+    const argValue = args[convCount - 1];
+
+    matches.push({
+      match: result[0],
+      left: !!result[3],
+      sign: result[4] || '',
+      pad: result[5] || ' ',
+      min: result[6] ? parseInt(result[6]) : 0,
+      precision: result[8] !== undefined ? parseInt(result[8]) : undefined,
+      code: result[9] || '%',
+      negative: Number(argValue) < 0,
+      argument: String(argValue),
+    });
+  }
+
+  strings.push(format.substring(matchPosEnd));
+
+  if (matches.length === 0) return format;
+  if (args.length < convCount) return format;
+
+  let output = '';
+
+  for (let i = 0; i < matches.length; i++) {
+    const m = matches[i]!;
+    let substitution: string;
+
+    switch (m.code) {
+      case '%':
+        substitution = '%';
+        break;
+      case 'b':
+        m.argument = Math.abs(parseInt(m.argument)).toString(2);
+        substitution = convert(m, true);
+        break;
+      case 'c':
+        m.argument = String.fromCharCode(Math.abs(parseInt(m.argument)));
+        substitution = convert(m, true);
+        break;
+      case 'd':
+        m.argument = String(Math.abs(parseInt(m.argument)));
+        substitution = convert(m);
+        break;
+      case 'f':
+        m.argument = Math.abs(parseFloat(m.argument)).toFixed(
+          m.precision ?? 6,
+        );
+        substitution = convert(m);
+        break;
+      case 'o':
+        m.argument = Math.abs(parseInt(m.argument)).toString(8);
+        substitution = convert(m);
+        break;
+      case 's':
+        m.argument = m.precision
+          ? m.argument.substring(0, m.precision)
+          : m.argument;
+        substitution = convert(m, true);
+        break;
+      case 'x':
+        m.argument = Math.abs(parseInt(m.argument)).toString(16);
+        substitution = convert(m);
+        break;
+      case 'X':
+        m.argument = Math.abs(parseInt(m.argument)).toString(16);
+        substitution = convert(m).toUpperCase();
+        break;
+      default:
+        substitution = m.match;
+    }
+
+    output += strings[i] + substitution;
+  }
+
+  output += strings[matches.length];
+  return output;
+}

package/src/validation/constraints.ts

@@ -0,0 +1,168 @@
+// ---------------------------------------------------------------------------
+// Constraint handlers — individual input behavior decorators
+//
+// Design patterns used:
+//   - Strategy Pattern  : each constraint is an independent strategy object
+//   - Decorator Pattern : constraints add behavior to plain HTML inputs
+//                         via attribute-driven binding
+//   - Registry Pattern  : constraints are registered by name and looked up
+//                         from the `constraint` attribute at runtime
+// ---------------------------------------------------------------------------
+
+import { sprintf } from '../utils/sprintf.js';
+import { isDateValid } from '../utils/dom.js';
+
+/**
+ * A constraint handler defines behavior that is attached to input elements
+ * bearing a matching `constraint` attribute value.
+ *
+ * Each handler is self-contained — it knows how to bind its own events
+ * and how to validate its own input.
+ */
+export interface ConstraintHandler {
+  /** The constraint keyword (e.g. `"date"`, `"number"`). */
+  name: string;
+
+  /**
+   * Called once per matching element to attach event listeners.
+   * This is the **Decorator** step — it augments the element's behavior.
+   */
+  attach(element: HTMLInputElement | HTMLTextAreaElement): void;
+}
+
+// -- Date constraint --------------------------------------------------------
+
+export const dateConstraint: ConstraintHandler = {
+  name: 'date',
+
+  attach(element) {
+    element.addEventListener('change', () => {
+      if (element.value !== '' && !isDateValid(element.value)) {
+        element.value = '';
+      }
+    });
+
+    // Disable IME for date input
+    (element.style as unknown as Record<string, string>)['imeMode'] = 'disabled';
+    element.setAttribute('inputmode', 'numeric');
+  },
+};
+
+// -- Number constraint ------------------------------------------------------
+
+export const numberConstraint: ConstraintHandler = {
+  name: 'number',
+
+  attach(element) {
+    element.addEventListener('keydown', ((event: KeyboardEvent) => {
+      // Allow: backspace, delete, tab, escape, enter, arrows, home, end
+      const allowedKeys = [
+        'Backspace', 'Delete', 'Tab', 'Escape', 'Enter',
+        'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown',
+        'Home', 'End',
+      ];
+      if (allowedKeys.includes(event.key)) return;
+      // Allow Ctrl/Cmd + A/C/V/X
+      if ((event.ctrlKey || event.metaKey) && ['a', 'c', 'v', 'x'].includes(event.key)) return;
+      // Allow digits, dot, minus
+      if (/[\d.\-]/.test(event.key)) return;
+      event.preventDefault();
+    }) as EventListener);
+
+    element.addEventListener('change', () => {
+      const val = element.value;
+      if (!/^-?[0-9]+(\.[0-9]+)?$/.test(val) || /^0\d+$/.test(val)) {
+        element.value = '0';
+      }
+    });
+
+    // Default empty number fields to 0
+    if (element.value === '') {
+      element.value = '0';
+    }
+
+    (element.style as unknown as Record<string, string>)['imeMode'] = 'disabled';
+    element.setAttribute('inputmode', 'decimal');
+  },
+};
+
+// -- Time constraint --------------------------------------------------------
+
+export const timeConstraint: ConstraintHandler = {
+  name: 'time',
+
+  attach(element) {
+    element.addEventListener('blur', () => {
+      const input = element.value;
+      let hour = '00';
+      let minute = '00';
+
+      if (/^\d{1,4}$/.test(input)) {
+        hour = sprintf('%02s', input.substring(0, 2));
+        minute = sprintf('%02s', input.substring(2, 4));
+      } else if (/^\d{0,2}:\d{0,2}$/.test(input)) {
+        const colonIdx = input.indexOf(':');
+        hour = sprintf('%02s', input.substring(0, colonIdx));
+        minute = sprintf('%02s', input.substring(colonIdx + 1));
+      }
+
+      element.value = `${hour}:${minute}`;
+    });
+
+    element.addEventListener('keydown', ((event: KeyboardEvent) => {
+      const allowedKeys = [
+        'Backspace', 'Delete', 'Tab', 'Escape', 'Enter',
+        'ArrowLeft', 'ArrowRight', 'Home', 'End',
+      ];
+      if (allowedKeys.includes(event.key)) return;
+      if ((event.ctrlKey || event.metaKey) && ['a', 'c', 'v', 'x'].includes(event.key)) return;
+      if (/[\d:]/.test(event.key)) return;
+      event.preventDefault();
+    }) as EventListener);
+
+    (element.style as unknown as Record<string, string>)['imeMode'] = 'disabled';
+    element.setAttribute('inputmode', 'numeric');
+  },
+};
+
+// -- UpperCase constraint ---------------------------------------------------
+
+export const upperCaseConstraint: ConstraintHandler = {
+  name: 'upperCase',
+
+  attach(element) {
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+
+    element.addEventListener('keyup', () => {
+      clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        const val = element.value;
+        if (/[a-z]/.test(val)) {
+          element.value = val.toUpperCase();
+        }
+      }, 500);
+    });
+  },
+};
+
+// -- OnlyEn constraint ------------------------------------------------------
+
+export const onlyEnConstraint: ConstraintHandler = {
+  name: 'onlyEn',
+
+  attach(element) {
+    (element.style as unknown as Record<string, string>)['imeMode'] = 'disabled';
+    element.setAttribute('inputmode', 'text');
+    element.setAttribute('lang', 'en');
+  },
+};
+
+// -- All built-in constraints -----------------------------------------------
+
+export const builtInConstraints: ConstraintHandler[] = [
+  dateConstraint,
+  numberConstraint,
+  timeConstraint,
+  upperCaseConstraint,
+  onlyEnConstraint,
+];