@axzydev/axzy_ui_system 1.3.0 → 1.3.1

package/src/components/molecules/masked-input/masked-input.tsx

@@ -0,0 +1,244 @@
+import React, { useRef, useState, useMemo } from "react";
+import clsx from "clsx";
+import ITInput from "@/components/atoms/input/input";
+import { ITMaskedInputProps } from "./masked-input.props";
+
+type Token = "9" | "A" | "a" | "x" | "*";
+
+type MaskRule =
+  | { type: "token"; token: Token }
+  | { type: "literal"; char: string };
+
+const TOKEN_SET = /[9Aax*]/;
+
+function parseMask(mask: string): MaskRule[] {
+  return mask.split("").map((ch) =>
+    TOKEN_SET.test(ch)
+      ? { type: "token", token: ch as Token }
+      : { type: "literal", char: ch }
+  );
+}
+
+function matchToken(token: Token, ch: string): boolean {
+  switch (token) {
+    case "9":
+      return /\d/.test(ch);
+    case "A":
+    case "a":
+      return /[A-Za-z]/.test(ch);
+    case "x":
+      return /[A-Za-z0-9]/.test(ch);
+    case "*":
+      return ch.length > 0;
+    default:
+      return false;
+  }
+}
+
+function extract(input: string, rules: MaskRule[], maskChar: string): string {
+  let raw = "";
+  let slot = 0;
+  for (const ch of input) {
+    while (slot < rules.length && rules[slot].type === "literal") slot++;
+    if (slot >= rules.length) break;
+    const rule = rules[slot];
+    if (
+      rule.type === "token" &&
+      ch !== maskChar &&
+      matchToken(rule.token, ch)
+    ) {
+      raw += rule.token === "A" ? ch.toUpperCase() : ch;
+      slot++;
+    }
+  }
+  return raw;
+}
+
+function format(raw: string, rules: MaskRule[], maskChar: string): string {
+  let out = "";
+  let idx = 0;
+  for (const rule of rules) {
+    if (rule.type === "literal") {
+      out += rule.char;
+    } else {
+      const ch = raw[idx];
+      out += ch !== undefined ? ch : maskChar;
+      idx++;
+    }
+  }
+  return out;
+}
+
+function countConsumed(input: string, rules: MaskRule[], upto: number, maskChar: string): number {
+  let slot = 0;
+  let n = 0;
+  for (let i = 0; i < upto && i < input.length; i++) {
+    const ch = input[i];
+    while (slot < rules.length && rules[slot].type === "literal") slot++;
+    if (slot >= rules.length) break;
+    const rule = rules[slot];
+    if (rule.type === "token" && ch !== maskChar && matchToken(rule.token, ch)) {
+      n++;
+      slot++;
+    }
+  }
+  return n;
+}
+
+function caretAfter(n: number, rules: MaskRule[]): number {
+  let pos = 0;
+  let consumed = 0;
+  for (const rule of rules) {
+    if (rule.type === "token") {
+      consumed++;
+      if (consumed > n) break;
+    }
+    pos++;
+  }
+  return pos;
+}
+
+/**
+ * Text input that applies a formatting mask while the user types, exposing only
+ * the clean (raw) value through `onChange`.
+ *
+ * The mask is defined by a pattern string. Tokens are filled by the user and
+ * any other character acts as an auto-inserted literal separator. Empty slots
+ * are painted with `placeholderChar`, so the mask is always visible.
+ *
+ * @example
+ * ```tsx
+ * <ITMaskedInput
+ *   name="code"
+ *   mask="xxxx-xxxx-xxxx"
+ *   label="Código"
+ *   onChange={(e) => setCode(e.target.value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ITMaskedInput
+ *   name="phone"
+ *   mask="(999) 999-9999"
+ *   pattern={/^\d{10}$/}
+ *   onChange={(e) => setPhone(e.target.value)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <ITMaskedInput
+ *   name="card"
+ *   mask="9999-9999-9999-9999"
+ *   onComplete={(card) => validateCard(card)}
+ * />
+ * ```
+ */
+export default function ITMaskedInput({
+  name,
+  mask,
+  value,
+  onChange,
+  onBlur,
+  onComplete,
+  pattern,
+  placeholderChar = "_",
+  variant = "primary",
+  size = "md",
+  label,
+  disabled = false,
+  required,
+  touched,
+  error,
+  className,
+  containerClassName,
+  iconLeft,
+  iconRight,
+  autoFocus = false,
+}: ITMaskedInputProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const rawRef = useRef<string>(value ?? "");
+  const isControlled = value !== undefined;
+
+  const [internalRaw, setInternalRaw] = useState<string>(value ?? "");
+  const [invalidPattern, setInvalidPattern] = useState(false);
+
+  const rules = useMemo(() => parseMask(mask), [mask]);
+  const tokenCount = useMemo(() => rules.filter((r) => r.type === "token").length, [rules]);
+
+  const raw = isControlled ? (value ?? "") : internalRaw;
+  const display = useMemo(() => format(raw, rules, placeholderChar), [raw, rules, placeholderChar]);
+
+  const scheduleCaret = (caret: number) => {
+    const inputEl = containerRef.current?.querySelector("input");
+    if (!inputEl) return;
+    requestAnimationFrame(() => {
+      if (document.activeElement === inputEl) {
+        const pos = Math.min(caret, inputEl.value.length);
+        inputEl.setSelectionRange(pos, pos);
+      }
+    });
+  };
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const el = e.target as HTMLInputElement;
+    const inputVal = el.value ?? "";
+    const caretBefore = el.selectionStart ?? inputVal.length;
+
+    const nextRaw = extract(inputVal, rules, placeholderChar);
+    const targetCaret = caretAfter(
+      countConsumed(inputVal, rules, caretBefore, placeholderChar),
+      rules
+    );
+
+    if (nextRaw !== rawRef.current) {
+      rawRef.current = nextRaw;
+      setInternalRaw(nextRaw);
+      onChange?.({ target: { name, value: nextRaw } });
+      if (nextRaw.length === tokenCount && nextRaw.length > 0) {
+        onComplete?.(nextRaw);
+      }
+      if (invalidPattern) setInvalidPattern(false);
+    }
+
+    scheduleCaret(targetCaret);
+  };
+
+  const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+    if (pattern && rawRef.current.length > 0 && !pattern.test(rawRef.current)) {
+      setInvalidPattern(true);
+    }
+    onBlur?.(e);
+  };
+
+  const resolvedError = invalidPattern
+    ? typeof error === "string"
+      ? error
+      : "Formato inválido"
+    : error;
+
+  return (
+    <div ref={containerRef} className={clsx("w-full", className)}>
+      <ITInput
+        name={name}
+        type="text"
+        label={label}
+        value={display}
+        onChange={handleChange}
+        onBlur={(e) => handleBlur(e as React.FocusEvent<HTMLInputElement>)}
+        maxLength={mask.length}
+        variant={variant}
+        size={size}
+        disabled={disabled}
+        required={required}
+        touched={touched}
+        error={resolvedError}
+        containerClassName={containerClassName}
+        iconLeft={iconLeft}
+        iconRight={iconRight}
+        autoFocus={autoFocus}
+      />
+    </div>
+  );
+}

package/src/index.ts

@@ -21,6 +21,7 @@ import ITChip from "./components/atoms/chip/chip";
 import ITChipInput from "./components/molecules/chip-input/chip-input";
 import ITDropdownMenu from "./components/molecules/dropdown-menu/dropdown-menu";
 import ITField from "./components/molecules/field/field";
+import ITMaskedInput from "./components/molecules/masked-input/masked-input";
 import ITMultiSelect from "./components/molecules/multi-select/multi-select";
 import ITConfirmDialog from "./components/organisms/confirm-dialog/confirm-dialog";
 import ITDataTable from "./components/organisms/data-table/dataTable";
@@ -75,6 +76,7 @@ import type { ITConfirmDialogProps } from "./components/organisms/confirm-dialog
 import type { ITAccordionProps, ITAccordionItem } from "./components/molecules/accordion/accordion.props";
 import type { ITDropdownMenuProps, ITDropdownMenuItem } from "./components/molecules/dropdown-menu/dropdown-menu.props";
 import type { ITFieldProps } from "./components/molecules/field/field.props";
+import type { ITMaskedInputProps } from "./components/molecules/masked-input/masked-input.props";
 import type { ITMultiSelectProps, ITMultiSelectOption } from "./components/molecules/multi-select/multi-select.props";
 import type { ITDataTableFetchParams, ITDataTableProps, ITDataTableResponse } from "./components/organisms/data-table/dataTable.props";
 import type { ITDatePickerProps } from "./components/molecules/date-picker/date-picker.props";
@@ -140,7 +142,7 @@ export {
   ITAlert, ITAvatar, ITBadget, ITBreadcrumbs, ITButton,
   ITCalendar,
   ITCard, ITCheckbox, ITChip, ITChipInput, ITConfirmDialog, ITDataTable, ITDatePicker,
-  ITDropdownMenu, ITField, ITMultiSelect,
+  ITDropdownMenu, ITField, ITMaskedInput, ITMultiSelect,
   ITDialog, ITDivider, ITDrawer,
   ITDropfile, ITEmptyState, ITFlex, ITFormBuilder, ITFormHeader, ITGrid, ITImage, ITInput, ITLayout,
   ITLoader,   ITNavbar, ITPage, ITPageHeader, ITPagination, ITPopover, ITProgress,
@@ -161,7 +163,7 @@ export {
     ITBreadcrumbItem, ITBreadcrumbsProps, ITButtonProps,
     ITCalendarProps,
     ITCardProps, ITCheckboxProps, ITChipProps, ITChipInputProps, ITConfirmDialogProps,
-    ITDropdownMenuItem, ITDropdownMenuProps, ITFieldProps, ITMultiSelectOption, ITMultiSelectProps,
+    ITDropdownMenuItem, ITDropdownMenuProps, ITFieldProps, ITMaskedInputProps, ITMultiSelectOption, ITMultiSelectProps,
     ITDataTableFetchParams, ITDataTableProps, ITDataTableResponse, ITDatePickerProps,
     ITDialogProps, ITDividerProps, ITDrawerProps,
     ITEmptyStateProps, ITFlexProps,

package/src/showcases/FormShowcases.tsx

@@ -13,6 +13,7 @@ import {
   ITFormBuilder,
   ITWysiwyg,
   ITField,
+  ITMaskedInput,
   ITMultiSelect,
   ITChipInput,
   ITBadget,
@@ -1913,3 +1914,180 @@ export const ChipInputShowcase = () => {
     />
   );
 };
+
+// 15. ITMaskedInput Showcase
+const MaskedDemo = ({
+  title,
+  mask,
+  pattern,
+  hint,
+  initial,
+}: {
+  title: string;
+  mask: string;
+  pattern?: RegExp;
+  hint?: string;
+  initial?: string;
+}) => {
+  const [raw, setRaw] = useState<string>(initial ?? "");
+  const [complete, setComplete] = useState<string | null>(null);
+  return (
+    <div>
+      <h4 className="text-sm font-bold text-slate-700 mb-2">{title}</h4>
+      <ITMaskedInput
+        name={title.toLowerCase().replace(/\s+/g, "_")}
+        label={mask}
+        mask={mask}
+        pattern={pattern}
+        value={raw}
+        onChange={(e) => {
+          setRaw(e.target.value);
+          setComplete(null);
+        }}
+        onComplete={(v) => setComplete(v)}
+      />
+      <p className="mt-1.5 text-xs font-mono text-slate-500">
+        raw: {raw || "(vacío)"}
+        {complete && <span className="text-emerald-600 ml-2">✓ completo</span>}
+        {hint && <span className="text-slate-400 ml-2">· {hint}</span>}
+      </p>
+    </div>
+  );
+};
+
+export const MaskedInputShowcase = () => {
+  const [code, setCode] = useState<string>("");
+  const [variant, setVariant] = useState<any>("primary");
+  const [size, setSize] = useState<any>("md");
+  const [disabled, setDisabled] = useState(false);
+  const [withError, setWithError] = useState(false);
+
+  const codeExample = `<ITMaskedInput\n  name="code"\n  label="Código de activación"\n  mask="xxxx-xxxx-xxxx"\n  variant="${variant}"\n  size="${size}"\n  disabled={${disabled}}\n  onChange={(e) => setCode(e.target.value)}\n/>`;
+
+  return (
+    <ShowcaseLayout
+      title="ITMaskedInput"
+      description="Input de texto con máscara de formato: teclea solo caracteres útiles y los separadores se insertan solos (xxxx-xxxx-xxxx, (999) 999-9999, etc.)."
+      code={codeExample}
+      demo={
+        <div className="w-full max-w-sm">
+          <ITMaskedInput
+            name="showcase_masked"
+            label="Código de activación"
+            mask="xxxx-xxxx-xxxx"
+            value={code}
+            variant={variant}
+            size={size}
+            disabled={disabled}
+            error={withError}
+            onChange={(e) => setCode(e.target.value)}
+          />
+          {code && (
+            <p className="mt-2 text-xs text-slate-500 font-mono">
+              Valor actual (raw): {code || "—"}
+            </p>
+          )}
+        </div>
+      }
+      controls={
+        <>
+          <ITSelect
+            name="masked_variant_ctrl"
+            label="Tema de Color"
+            value={variant}
+            onChange={(e: any) => setVariant(e.target.value)}
+            options={[
+              { label: "Primary", value: "primary" },
+              { label: "Secondary", value: "secondary" },
+              { label: "Success", value: "success" },
+              { label: "Danger", value: "danger" },
+              { label: "Warning", value: "warning" },
+              { label: "Info", value: "info" },
+            ]}
+          />
+          <ITSelect
+            name="masked_size_ctrl"
+            label="Tamaño"
+            value={size}
+            onChange={(e: any) => setSize(e.target.value)}
+            options={[
+              { label: "Small", value: "sm" },
+              { label: "Medium", value: "md" },
+              { label: "Large", value: "lg" },
+            ]}
+          />
+          <div className="flex items-center justify-between pt-2">
+            <span className="text-sm font-semibold text-gray-700">Deshabilitado</span>
+            <ITSlideToggle isOn={disabled} onToggle={setDisabled} activeColor="danger" size="sm" />
+          </div>
+          <div className="flex items-center justify-between">
+            <span className="text-sm font-semibold text-gray-700">Error</span>
+            <ITSlideToggle isOn={withError} onToggle={setWithError} activeColor="danger" size="sm" />
+          </div>
+        </>
+      }
+      gallery={
+        <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-6">
+          <MaskedDemo
+            title="Código alfanumérico"
+            mask="xxxx-xxxx-xxxx"
+            hint="Escribe: ABC1-2345"
+          />
+          <MaskedDemo
+            title="Número de tarjeta"
+            mask="9999-9999-9999-9999"
+            hint="Escribe 16 dígitos"
+          />
+          <MaskedDemo
+            title="Teléfono"
+            mask="(999) 999-9999"
+            pattern={/^\d{10}$/}
+            hint="Regex /^\\d{10}$/"
+          />
+          <MaskedDemo
+            title="Código postal"
+            mask="99999"
+            hint="Ejemplo: 44100"
+          />
+          <MaskedDemo
+            title="CVV / OTP"
+            mask="999"
+            hint="3 dígitos, onComplete"
+          />
+          <MaskedDemo
+            title="Clave con letras en MAYÚSCULA"
+            mask="A-A-A-999"
+            hint="Token A auto-mayúscula"
+            initial="ABC123"
+          />
+        </div>
+      }
+      doc={{
+        summary: "Input con máscara: value/onChange entregan solo los caracteres útiles y los separadores se auto-insertan.",
+        description:
+          "Define el patrón con tokens (9=dígito, A=letra mayúscula, a=letra, x=alfanumérico, *=cualquiera) y literales (todo lo demás). Los huecos vacíos se pintan con placeholderChar ('_').",
+        examples: [
+          '<ITMaskedInput name="code" mask="xxxx-xxxx-xxxx" onChange={(e) => setCode(e.target.value)} />',
+          '<ITMaskedInput name="phone" mask="(999) 999-9999" pattern={/^\\d{10}$/} onChange={setPhone} />',
+          '<ITMaskedInput name="card" mask="9999-9999-9999-9999" onComplete={validateCard} />',
+        ],
+        props: [
+          { name: "mask", type: "string", required: true, description: "Patrón de la máscara (tokens + literales)." },
+          { name: "value", type: "string", description: "Valor limpio (raw): solo caracteres útiles." },
+          { name: "onChange", type: "(e) => void", description: "e.target.value = raw sin separadores." },
+          { name: "onComplete", type: "(value) => void", description: "Dispara al llenar toda la máscara." },
+          { name: "pattern", type: "RegExp", description: "Validación full-match del raw en blur." },
+          { name: "placeholderChar", type: "string", default: '"_"', description: "Relleno de slots vacíos." },
+          { name: "variant", type: "ColorsTypes", default: '"primary"', description: "Color de acento." },
+          { name: "size", type: '"sm" | "md" | "lg"', default: '"md"', description: "Tamaño del input." },
+          { name: "error", type: "string | boolean", description: "Estado de error." },
+        ],
+        notes: [
+          "Los tokens A guardan letras en mayúsculas automáticamente.",
+          "Borrar un separador lo vuelve a insertar; el cursor se conserva en la posición correcta.",
+          "El cursor se preserva también al editar en medio de la máscara.",
+        ],
+      }}
+    />
+  );
+};