@rovula/ui 0.0.76 → 0.0.78

package/src/components/MaskedTextInput/MaskedTextInput.tsx

@@ -0,0 +1,391 @@
+import React, {
+  FC,
+  forwardRef,
+  useCallback,
+  useImperativeHandle,
+  useRef,
+  useState,
+  useEffect,
+} from "react";
+import TextInput, { InputProps } from "../TextInput/TextInput";
+import { cn } from "@/utils/cn";
+
+export type MaskRule = {
+  pattern: RegExp;
+  placeholder: string;
+  isLiteral?: boolean;
+  validator?: (char: string) => boolean;
+};
+
+export type MaskedTextInputProps = InputProps & {
+  mask?: string;
+  maskChar?: string;
+  showMask?: boolean;
+  guide?: boolean;
+  keepCharPositions?: boolean;
+  rules?: Record<string, RegExp | ((char: string) => boolean)>;
+  onMaskedChange?: (value: string, rawValue: string) => void;
+};
+
+// Kendo UI style mask patterns
+export const MASK_PATTERNS = {
+  PHONE: "(000) 000-0000",
+  PHONE_INTL: "+000 000 000 0000",
+  CREDIT_CARD: "0000 0000 0000 0000",
+  DATE: "00/00/0000",
+  TIME: "00:00",
+  SSN: "000-00-0000",
+  ZIP_CODE: "00000",
+  ZIP_CODE_EXT: "00000-0000",
+  CURRENCY: "$000,000.00",
+  PERCENTAGE: "000%",
+  LICENSE_PLATE: "AAA-0000",
+  PRODUCT_CODE: "AA-0000-AA",
+  ALPHANUMERIC: "AAAA-0000",
+} as const;
+
+// Kendo UI mask rules
+const KENDO_RULES: Record<string, { pattern: RegExp; placeholder: string }> = {
+  "0": { pattern: /[0-9]/, placeholder: "0" }, // Any digit 0-9
+  "9": { pattern: /[0-9\s]/, placeholder: "9" }, // Any digit 0-9 or space
+  "#": { pattern: /[0-9\s+\-]/, placeholder: "#" }, // Any digit, space, +, or -
+  L: { pattern: /[a-zA-Z]/, placeholder: "L" }, // Any letter
+  "?": { pattern: /[a-zA-Z\s]/, placeholder: "?" }, // Any letter or space
+  "&": { pattern: /[^\s]/, placeholder: "&" }, // Any character except space
+  C: { pattern: /./, placeholder: "C" }, // Any character including space
+  A: { pattern: /[a-zA-Z0-9]/, placeholder: "A" }, // Any alphanumeric
+  a: { pattern: /[a-zA-Z0-9\s]/, placeholder: "a" }, // Any alphanumeric or space
+};
+
+// Helper function to create mask pattern from string using Kendo UI rules
+const createMaskPattern = (
+  mask: string,
+  customRules?: Record<string, RegExp | ((char: string) => boolean)>
+): MaskRule[] => {
+  const rules = { ...KENDO_RULES, ...customRules };
+  const pattern: MaskRule[] = [];
+  let i = 0;
+
+  while (i < mask.length) {
+    const char = mask[i];
+
+    if (char === "\\" && i + 1 < mask.length) {
+      // Escaped character - treat as literal
+      const nextChar = mask[i + 1];
+      pattern.push({
+        pattern: new RegExp(`^${nextChar}$`),
+        placeholder: nextChar,
+        isLiteral: true,
+      });
+      i += 2;
+    } else if (rules[char]) {
+      // Apply Kendo rule
+      const rule = rules[char];
+      if (typeof rule === "function") {
+        pattern.push({
+          pattern: /./, // Accept any character, validate with function
+          placeholder: char,
+          validator: rule,
+        });
+      } else if (rule instanceof RegExp) {
+        pattern.push({
+          pattern: rule,
+          placeholder: char,
+        });
+      } else {
+        pattern.push({
+          pattern: rule.pattern,
+          placeholder: rule.placeholder,
+        });
+      }
+      i++;
+    } else {
+      // Literal character
+      pattern.push({
+        pattern: new RegExp(`^${char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`),
+        placeholder: char,
+        isLiteral: true,
+      });
+      i++;
+    }
+  }
+
+  return pattern;
+};
+
+// Helper function to apply mask to value using Kendo UI rules
+const applyMask = (
+  value: string,
+  maskPattern: MaskRule[],
+  maskChar: string = "_",
+  showMask: boolean = true,
+  guide: boolean = true
+): string => {
+  let maskedValue = "";
+  let valueIndex = 0;
+
+  for (let i = 0; i < maskPattern.length; i++) {
+    const rule = maskPattern[i];
+
+    if (rule.isLiteral) {
+      // Literal character - always add
+      maskedValue += rule.placeholder;
+    } else {
+      // Input character - find next valid character
+      let foundValid = false;
+      while (valueIndex < value.length) {
+        const char = value[valueIndex];
+        valueIndex++;
+
+        // Check with validator function first if exists
+        const isValid = rule.validator
+          ? rule.validator(char)
+          : rule.pattern.test(char);
+
+        if (isValid) {
+          maskedValue += char;
+          foundValid = true;
+          break;
+        }
+        // Skip invalid characters and continue searching
+      }
+
+      if (!foundValid && guide && showMask) {
+        // No valid character found, fill with placeholder
+        maskedValue += maskChar;
+      } else if (!foundValid) {
+        // No placeholder needed, stop building the mask
+        break;
+      }
+    }
+  }
+
+  return maskedValue;
+};
+
+// Helper function to extract raw value from masked value
+const extractRawValue = (
+  maskedValue: string,
+  maskPattern: MaskRule[]
+): string => {
+  let rawValue = "";
+
+  for (let i = 0; i < maskedValue.length && i < maskPattern.length; i++) {
+    const rule = maskPattern[i];
+    const char = maskedValue[i];
+
+    if (!rule.isLiteral) {
+      // Only include non-literal characters in raw value
+      rawValue += char;
+    }
+  }
+
+  return rawValue;
+};
+
+// Helper function to get cursor position after masking
+const getCursorPosition = (
+  maskedValue: string,
+  rawInputLength: number,
+  maskPattern: MaskRule[]
+): number => {
+  let inputCount = 0;
+  let cursorPos = 0;
+
+  for (let i = 0; i < maskPattern.length && i < maskedValue.length; i++) {
+    const rule = maskPattern[i];
+    const char = maskedValue[i];
+
+    if (rule.isLiteral) {
+      cursorPos = i + 1;
+    } else {
+      inputCount++;
+      cursorPos = i + 1;
+
+      if (inputCount >= rawInputLength) {
+        break;
+      }
+    }
+  }
+
+  return cursorPos;
+};
+
+export const MaskedTextInput = forwardRef<
+  HTMLInputElement,
+  MaskedTextInputProps
+>(
+  (
+    {
+      mask,
+      maskChar = "_",
+      showMask = true,
+      guide = true,
+      keepCharPositions = false,
+      rules,
+      onMaskedChange,
+      onChange,
+      value,
+      defaultValue,
+      ...props
+    },
+    ref
+  ) => {
+    const inputRef = useRef<HTMLInputElement>(null);
+    const [maskedValue, setMaskedValue] = useState<string>("");
+    const [rawValue, setRawValue] = useState<string>("");
+
+    // Parse mask pattern using Kendo UI rules
+    const maskPattern = React.useMemo(() => {
+      if (!mask) return null;
+
+      return createMaskPattern(mask, rules);
+    }, [mask, rules]);
+
+    // Initialize values
+    useEffect(() => {
+      const initialValue = value || defaultValue || "";
+      if (maskPattern && initialValue) {
+        const masked = applyMask(
+          initialValue as string,
+          maskPattern,
+          maskChar,
+          showMask,
+          guide
+        );
+        const raw = extractRawValue(masked, maskPattern);
+        setMaskedValue(masked);
+        setRawValue(raw);
+      } else {
+        setMaskedValue(initialValue as string);
+        setRawValue(initialValue as string);
+      }
+    }, [maskPattern, maskChar, showMask, guide, value, defaultValue]);
+
+    useImperativeHandle(ref, () => inputRef?.current as HTMLInputElement);
+
+    const handleChange = useCallback(
+      (event: React.ChangeEvent<HTMLInputElement>) => {
+        const inputValue = event.target.value;
+
+        if (!maskPattern) {
+          setMaskedValue(inputValue);
+          setRawValue(inputValue);
+          onChange?.(event);
+          onMaskedChange?.(inputValue, inputValue);
+          return;
+        }
+
+        const newMaskedValue = applyMask(
+          inputValue,
+          maskPattern,
+          maskChar,
+          showMask,
+          guide
+        );
+        const newRawValue = extractRawValue(newMaskedValue, maskPattern);
+
+        setMaskedValue(newMaskedValue);
+        setRawValue(newRawValue);
+
+        // Create synthetic event with masked value
+        const syntheticEvent = {
+          ...event,
+          target: {
+            ...event.target,
+            value: newMaskedValue,
+          },
+        } as React.ChangeEvent<HTMLInputElement>;
+
+        onChange?.(syntheticEvent);
+        onMaskedChange?.(newMaskedValue, newRawValue);
+
+        // Set cursor position after state update
+        setTimeout(() => {
+          if (inputRef.current) {
+            const rawLength = newRawValue.replace(/[_\s]/g, "").length;
+            const newCursorPos = getCursorPosition(
+              newMaskedValue,
+              rawLength,
+              maskPattern
+            );
+            inputRef.current.setSelectionRange(newCursorPos, newCursorPos);
+          }
+        }, 0);
+      },
+      [maskPattern, maskChar, showMask, guide, onChange, onMaskedChange]
+    );
+
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLInputElement>) => {
+        if (!maskPattern) {
+          props.onKeyDown?.(event);
+          return;
+        }
+
+        const { key, ctrlKey, metaKey } = event;
+        const input = event.target as HTMLInputElement;
+        const cursorPos = input.selectionStart || 0;
+
+        // Allow navigation and editing keys
+        if (
+          key === "Backspace" ||
+          key === "Delete" ||
+          key === "ArrowLeft" ||
+          key === "ArrowRight" ||
+          key === "Home" ||
+          key === "End" ||
+          key === "Tab" ||
+          key.length > 1 || // Allow other special keys
+          ctrlKey ||
+          metaKey
+        ) {
+          props.onKeyDown?.(event);
+          return;
+        }
+
+        // Find the next non-literal position from cursor
+        let targetPos = cursorPos;
+        while (
+          targetPos < maskPattern.length &&
+          maskPattern[targetPos].isLiteral
+        ) {
+          targetPos++;
+        }
+
+        // Check if we have a valid position and the key matches
+        if (targetPos < maskPattern.length) {
+          const targetRule = maskPattern[targetPos];
+
+          // Check with validator function first if exists
+          const isValid = targetRule.validator
+            ? targetRule.validator(key)
+            : targetRule.pattern.test(key);
+
+          if (!isValid) {
+            event.preventDefault();
+            return;
+          }
+        }
+
+        props.onKeyDown?.(event);
+      },
+      [maskPattern, props]
+    );
+
+    return (
+      <TextInput
+        {...props}
+        ref={inputRef}
+        value={maskedValue}
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        className={cn(props.className)}
+      />
+    );
+  }
+);
+
+MaskedTextInput.displayName = "MaskedTextInput";
+
+export default MaskedTextInput;

package/src/components/MaskedTextInput/README.md

@@ -0,0 +1,202 @@
+# MaskedTextInput Component
+
+A powerful masked input component following Kendo UI masking rules with full TypeScript support.
+
+## Features
+
+- ✅ Kendo UI compatible mask rules (0, 9, #, L, ?, &, C, A, a)
+- ✅ Custom mask rules support (RegExp or function-based)
+- ✅ Proper cursor positioning
+- ✅ Automatic literal character insertion
+- ✅ Smart character validation
+- ✅ Raw value extraction
+- ✅ Full TypeScript support
+
+## Kendo UI Mask Rules
+
+| Rule | Description | Example |
+|------|-------------|---------|
+| `0` | Any digit 0-9 (required) | `000-000-0000` |
+| `L` | Any letter (a-z, A-Z) (required) | `LLL-LLLL` |
+| `A` | Any alphanumeric (required) | `AAAA-0000` |
+| `#` | Digit, space, +, or - | `#00-000-0000` |
+| `9` | Any digit or space (optional) ⚠️ | `999-999-9999` |
+| `?` | Any letter or space (optional) ⚠️ | `???-????` |
+| `a` | Any alphanumeric or space (optional) ⚠️ | `aaaa-aaaa` |
+| `&` | Any character except space | `&&&-&&&` |
+| `C` | Any character including space | `CCC CCC` |
+
+> ⚠️ **Note on Optional Rules (9, ?, a):** These rules accept space, making the position optional. Pressing space will skip to the next position. Use `guide={false}` for better UX with optional rules.
+
+## Usage
+
+### Basic Usage
+
+```tsx
+import { MaskedTextInput, MASK_PATTERNS } from '@rovula/ui';
+
+// Phone number
+<MaskedTextInput 
+  label="Phone Number" 
+  mask={MASK_PATTERNS.PHONE}
+/>
+
+// Custom mask
+<MaskedTextInput 
+  label="License Plate" 
+  mask="AAA-0000"
+/>
+```
+
+### With Callbacks
+
+```tsx
+const [maskedValue, setMaskedValue] = useState("");
+const [rawValue, setRawValue] = useState("");
+
+<MaskedTextInput 
+  label="Phone" 
+  mask="(000) 000-0000"
+  onMaskedChange={(masked, raw) => {
+    setMaskedValue(masked); // "(123) 456-7890"
+    setRawValue(raw);       // "1234567890"
+  }}
+/>
+```
+
+### Custom Rules
+
+```tsx
+// Using RegExp - only digits 3-9
+<MaskedTextInput 
+  mask="~-~-~" 
+  rules={{
+    "~": /[3-9]/
+  }}
+/>
+
+// Using function - only uppercase letters
+<MaskedTextInput 
+  mask="*-*-*" 
+  rules={{
+    "*": (char: string) => char === char.toUpperCase() && /[A-Z]/.test(char)
+  }}
+/>
+
+// Multiple custom rules
+<MaskedTextInput 
+  mask="~*-~*-~*" 
+  rules={{
+    "~": /[0-9]/,           // Digit
+    "*": /[A-Z]/            // Uppercase letter
+  }}
+/>
+```
+
+### Escaping Characters
+
+Use backslash `\` to escape mask characters and treat them as literals:
+
+```tsx
+<MaskedTextInput mask="\0\0\0-0000" />
+// Result: "000-1234" (first 000 is literal)
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mask` | `string` | - | Mask pattern using Kendo UI rules |
+| `maskChar` | `string` | `"_"` | Placeholder character for empty positions |
+| `showMask` | `boolean` | `true` | Show mask placeholders |
+| `guide` | `boolean` | `true` | Show guide placeholders |
+| `rules` | `Record<string, RegExp \| Function>` | - | Custom mask rules |
+| `onMaskedChange` | `(masked: string, raw: string) => void` | - | Callback with masked and raw values |
+
+## Pre-defined Patterns
+
+```tsx
+export const MASK_PATTERNS = {
+  PHONE: "(000) 000-0000",
+  PHONE_INTL: "+000 000 000 0000",
+  CREDIT_CARD: "0000 0000 0000 0000",
+  DATE: "00/00/0000",
+  TIME: "00:00",
+  SSN: "000-00-0000",
+  ZIP_CODE: "00000",
+  ZIP_CODE_EXT: "00000-0000",
+  CURRENCY: "$000,000.00",
+  PERCENTAGE: "000%",
+  LICENSE_PLATE: "AAA-0000",
+  PRODUCT_CODE: "AA-0000-AA",
+  ALPHANUMERIC: "AAAA-0000",
+};
+```
+
+## Examples
+
+### Phone Number
+```tsx
+<MaskedTextInput mask="(000) 000-0000" label="Phone" />
+// Input: 1234567890
+// Display: (123) 456-7890
+```
+
+### License Plate
+```tsx
+<MaskedTextInput mask="LLL-0000" label="License Plate" />
+// Input: ABC1234
+// Display: ABC-1234
+```
+
+### Mixed Pattern
+```tsx
+<MaskedTextInput mask="AA-0000-AA" label="Product Code" />
+// Input: AB1234CD
+// Display: AB-1234-CD
+```
+
+### Optional Input (with space)
+```tsx
+<MaskedTextInput 
+  mask="999-999-9999" 
+  label="Optional Phone" 
+  guide={false}
+/>
+// Input: 123 (then press space to skip)
+// Display: 123-   -    (spaces are allowed)
+// Good for: Optional/partial input
+```
+
+## Technical Details
+
+### How It Works
+
+1. **Input Processing**: Characters are validated against mask rules
+2. **Literal Insertion**: Static characters are automatically added
+3. **Cursor Management**: Cursor is positioned correctly after input
+4. **Value Extraction**: Raw value (without literals) is maintained
+
+### Key Improvements
+
+- ✅ Fixed typing issues - can now type in all mask patterns
+- ✅ Fixed cursor positioning - cursor stays in correct position
+- ✅ Improved character validation - better handling of invalid input
+- ✅ Smart literal skipping - automatically moves past literal characters
+- ✅ Better performance - optimized mask application logic
+
+## Browser Support
+
+Works in all modern browsers that support ES6+ and React 16.8+.
+
+## TypeScript
+
+Fully typed with TypeScript. Export types:
+
+```tsx
+import type { 
+  MaskedTextInputProps, 
+  MaskRule 
+} from '@rovula/ui';
+```
+

package/src/components/MaskedTextInput/index.ts

@@ -0,0 +1,3 @@
+export { default } from "./MaskedTextInput";
+export type { MaskedTextInputProps, MaskRule } from "./MaskedTextInput";
+export { MASK_PATTERNS } from "./MaskedTextInput";