@samline/formatter 1.0.1 → 1.1.0

package/README.md

@@ -41,15 +41,15 @@ Requires Node 20+ when bundling. Runtime target is ES2020.
 Use the browser build when you do not have a bundler and need to run the package directly in HTML, Shopify, WordPress, or any traditional template.
 
 ```html
-<script src="https://unpkg.com/@samline/formatter@1.0.1/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/formatter@1.1.0/dist/browser/global.global.js"></script>
 ```
 
-> Pin the version in production. Replace `1.0.1` with the version you ship.
+> Pin the version in production. Replace `1.1.0` with the version you ship.
 
 The browser bundle exposes a single global: `window.Formatter`.
 
 ```html
-<script src="https://unpkg.com/@samline/formatter@1.0.1/dist/browser/global.global.js"></script>
+<script src="https://unpkg.com/@samline/formatter@1.1.0/dist/browser/global.global.js"></script>
 <script>
   const result = window.Formatter.format('5512345678', 'phone')
   console.log(result.formatted) // '55 1234 5678'
@@ -111,7 +111,9 @@ format('4111111111111111', 'creditCardType')
 | `'creditCard'` | Brand-aware grouping | `'4111 1111 1111 1111'`, digits-only raw |
 | `'creditCardType'` | Returns the card brand name | Brand string, digits-only raw from input |
 
-For the full options reference and per-type behavior, see:
+## Documentation
+
+Full API reference, guides, and examples are available at **[samline.github.io/formatter](https://samline.github.io/formatter)**.
 
 | Doc | Purpose |
 | --- | --- |

package/dist/browser/global.d.ts

@@ -1,10 +1,149 @@
 import { FormatGeneralOptions, FormatNumeralOptions, FormatDateOptions, FormatTimeOptions, FormatCreditCardOptions, DatePatternType, TimePatternType } from 'cleave-zen';
 
+/**
+ * # Regex Module
+ *
+ * Validation patterns exposed as public API for form consumers that pair
+ * formatting with validation. Each entry bundles the regex with a ready-to-use
+ * error message so consumers do not have to keep them in sync.
+ *
+ * ## Usage
+ *
+ * **Static (backward compatible):**
+ * ```ts
+ * regex.phone.pattern.test('5512345678')  // true
+ * regex.email.errorMessage                // 'Please enter a valid email address.'
+ * ```
+ *
+ * **Parametric (dynamic):**
+ * ```ts
+ * regex.digits(10).pattern.test('1234567890')  // true
+ * regex.digits(7).pattern.test('1234567')      // true
+ * regex.phone({ length: 10 }).pattern.test('1234567890')
+ * regex.phone({ length: 7 }).pattern.test('1234567')
+ * ```
+ *
+ * **Custom regex:**
+ * ```ts
+ * regex.custom(/^[A-Z]{5}$/, 'Must be 5 uppercase letters').pattern.test('HELLO')
+ * ```
+ *
+ * ## Available Patterns
+ *
+ * | Key | Static | Parametric | Description |
+ * | --- | --- | --- | --- |
+ * | `phone` | ✅ | ✅ `({ length })` | Phone numbers |
+ * | `email` | ✅ | — | Email addresses |
+ * | `rfc` | ✅ | — | Mexican RFC |
+ * | `curp` | ✅ | — | Mexican CURP |
+ * | `cp` | ✅ | — | Mexican postal code (5 digits) |
+ * | `numeral` | ✅ | — | Numbers with separators |
+ * | `onlyNumbers` | ✅ | ✅ `({ length })` | Digits only |
+ * | `digits` | — | ✅ `({ length, min, max })` | Variable digit count |
+ * | `creditCard` | ✅ | ✅ `({ min, max })` | Card numbers |
+ * | `expirationDate` | ✅ | — | MM/YY format |
+ * | `cardCvc` | ✅ | — | 3-4 digit CVC |
+ * | `onlyLetters` | ✅ | — | Letters only |
+ * | `onlyAlphanumeric` | ✅ | — | Letters and numbers |
+ * | `url` | ✅ | ✅ `({ protocol })` | URLs |
+ * | `ipv4` | ✅ | — | IPv4 addresses |
+ * | `ipv6` | ✅ | — | IPv6 addresses |
+ * | `uuid` | ✅ | — | UUID v4 |
+ * | `hexColor` | ✅ | — | Hex color codes |
+ * | `hashtag` | ✅ | — | Social media hashtags |
+ * | `mention` | ✅ | — | Social media mentions |
+ * | `password` | — | ✅ `({ min, max, rules })` | Password strength |
+ * | `custom` | — | ✅ `({ pattern, errorMessage })` | User-defined regex |
+ */
+interface RegexEntry {
+    pattern: RegExp;
+    errorMessage: string;
+}
+interface PhoneParams {
+    length?: number;
+}
+interface DigitsParams {
+    length?: number;
+    min?: number;
+    max?: number;
+}
+interface CreditCardParams {
+    min?: number;
+    max?: number;
+}
+interface UrlParams {
+    protocol?: 'http' | 'https' | 'ftp' | 'all';
+}
+interface PasswordParams {
+    min?: number;
+    max?: number;
+    uppercase?: boolean;
+    lowercase?: boolean;
+    numbers?: boolean;
+    special?: boolean;
+}
+interface CustomParams {
+    pattern: RegExp;
+    errorMessage: string;
+}
+/**
+ * Digits with configurable length.
+ * @example
+ * regex.digits(10).pattern.test('1234567890')     // true
+ * regex.digits({ length: 7 }).pattern.test('1234567') // true
+ * regex.digits({ min: 3, max: 10 }).pattern.test('12345') // true
+ */
+declare function digits(params?: number | DigitsParams): RegexEntry;
+/**
+ * Phone with configurable digit count.
+ *
+ * Also available as static entry: regex.phone.pattern (10 digits)
+ * @example
+ * regex.phone().pattern.test('5512345678')         // true (10 digits)
+ * regex.phone({ length: 7 }).pattern.test('1234567') // true (7 digits)
+ */
+declare function _phoneFn(params?: PhoneParams): RegexEntry;
+/**
+ * Credit card with configurable digit range.
+ *
+ * Also available as static entry: regex.creditCard.pattern (15-16 digits)
+ * @example
+ * regex.creditCard().pattern.test('4111111111111111')      // true (15-16)
+ * regex.creditCard({ min: 13, max: 19 }).pattern.test('1234567890123') // true
+ */
+declare function _creditCardFn(params?: CreditCardParams): RegexEntry;
+/**
+ * URL with configurable protocol.
+ *
+ * Also available as static entry: regex.url.pattern (any protocol)
+ * @example
+ * regex.url().pattern.test('https://example.com')   // true
+ * regex.url({ protocol: 'https' }).pattern.test('https://example.com') // true
+ * regex.url({ protocol: 'https' }).pattern.test('ftp://example.com')  // false
+ */
+declare function _urlFn(params?: UrlParams): RegexEntry;
+/**
+ * Password with configurable strength rules.
+ * @example
+ * regex.password().pattern.test('Passw0rd!')  // true (default: 8+ chars, upper, lower, number)
+ * regex.password({ min: 12, special: true }).pattern.test('MyP@ssw0rd!') // true
+ */
+declare function _passwordFn(params?: PasswordParams): RegexEntry;
+/**
+ * Custom regex provided by the user.
+ * @example
+ * regex.custom(/^[A-Z]{5}$/, 'Must be 5 uppercase letters').pattern.test('HELLO') // true
+ * regex.custom({ pattern: /^\d+$/, errorMessage: 'Numbers only' }).pattern.test('123') // true
+ */
+declare function _customFn(pattern: RegExp, errorMessage?: string): RegexEntry;
+declare function _customFn(params: CustomParams): RegexEntry;
 declare const regex: {
-    readonly phone: {
-        readonly pattern: RegExp;
-        readonly errorMessage: "Please enter a valid 10-digit phone number.";
-    };
+    readonly digits: typeof digits & RegexEntry;
+    readonly phone: typeof _phoneFn & RegexEntry;
+    readonly creditCard: typeof _creditCardFn & RegexEntry;
+    readonly url: typeof _urlFn & RegexEntry;
+    readonly password: typeof _passwordFn & RegexEntry;
+    readonly custom: typeof _customFn & RegexEntry;
     readonly email: {
         readonly pattern: RegExp;
         readonly errorMessage: "Please enter a valid email address.";
@@ -13,6 +152,14 @@ declare const regex: {
         readonly pattern: RegExp;
         readonly errorMessage: "Please enter a valid RFC.";
     };
+    readonly curp: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid CURP.";
+    };
+    readonly cp: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid 5-digit postal code.";
+    };
     readonly numeral: {
         readonly pattern: RegExp;
         readonly errorMessage: "Please enter a valid number.";
@@ -21,17 +168,13 @@ declare const regex: {
         readonly pattern: RegExp;
         readonly errorMessage: "Please enter only numbers.";
     };
-    readonly creditCard: {
-        readonly pattern: RegExp;
-        readonly errorMessage: "Please enter a valid card number.";
-    };
     readonly expirationDate: {
         readonly pattern: RegExp;
-        readonly errorMessage: "Please enter a valid expiration date.";
+        readonly errorMessage: "Please enter a valid expiration date (MM/YY or MM/YYYY).";
     };
     readonly cardCvc: {
         readonly pattern: RegExp;
-        readonly errorMessage: "Please enter a valid CVC.";
+        readonly errorMessage: "Please enter a valid CVC (3-4 digits).";
     };
     readonly onlyLetters: {
         readonly pattern: RegExp;
@@ -41,6 +184,62 @@ declare const regex: {
         readonly pattern: RegExp;
         readonly errorMessage: "Please enter only letters and numbers.";
     };
+    readonly ipv4: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid IPv4 address.";
+    };
+    readonly ipv6: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid IPv6 address.";
+    };
+    readonly uuid: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid UUID.";
+    };
+    readonly hexColor: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid hex color code (e.g., #FFF or #FFFFFF).";
+    };
+    readonly hashtag: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid hashtag (e.g., #example).";
+    };
+    readonly mention: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid mention (e.g., @username).";
+    };
+    readonly postalCode: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid postal code (e.g., 90210 or 90210-1234).";
+    };
+    readonly time24: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid 24-hour time (HH:MM).";
+    };
+    readonly date: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid date (YYYY-MM-DD).";
+    };
+    readonly slug: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid slug (lowercase, hyphens, no spaces).";
+    };
+    readonly username: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid username (3-20 chars, letters, numbers, _ or -).";
+    };
+    readonly macAddress: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid MAC address (e.g., 00:1B:44:11:3A:B7).";
+    };
+    readonly semver: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid semantic version (e.g., 1.2.3).";
+    };
+    readonly base64: {
+        readonly pattern: RegExp;
+        readonly errorMessage: "Please enter a valid Base64 encoded string.";
+    };
 };
 
 type FormatType = 'general' | 'phone' | 'numeral' | 'date' | 'time' | 'creditCard' | 'creditCardType';