### Common Setup and Development Commands

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Quick reference for setting up the project, running development servers for different applications, and starting the library in watch mode.

```bash
# Setup
pnpm install

# Development
pnpm run dev              # Vite demo
pnpm run dev:next         # Next.js demo
pnpm run dev:docs         # Documentation
cd packages/use-mask-input && pnpm run dev  # Library watch mode
```

--------------------------------

### Install use-mask-input

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/intro.md

Install the library using npm or yarn.

```bash
npm install use-mask-input
```

--------------------------------

### Run Development Server for Docusaurus

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/README.md

Use this command from the root directory to start the Docusaurus development server. Alternatively, navigate to this directory and use 'npm start'.

```bash
# From root
npm run dev:docs

# Or from this directory
npm start
```

--------------------------------

### Install use-mask-input and TanStack Form

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tanstack-form.md

Install the necessary packages for TanStack Form integration.

```bash
npm install use-mask-input @tanstack/react-form
```

--------------------------------

### Install use-mask-input and Ant Design

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/antd.md

Install the necessary packages for use-mask-input and Ant Design integration.

```bash
npm install use-mask-input antd
```

--------------------------------

### Run Demo Applications

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Starts the development server for the Vite demo app. Use specific commands for other demo apps.

```bash
pnpm run dev
```

```bash
pnpm run dev:next
```

```bash
pnpm run dev:docs
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Installs project dependencies. Ensure you are using pnpm version 10.30.2 or later.

```bash
pnpm install
```

```bash
pnpm --version  # Should be 10.30.2 or later
```

--------------------------------

### Add React-Specific ESLint Rules

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/vite-project/README.md

Install and configure `eslint-plugin-react-x` and `eslint-plugin-react-dom` for React-specific linting. This enhances the ESLint setup for React development.

```javascript
// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}']
    extends: [
      // Other configs...
      // Enable lint rules for React
      reactX.configs['recommended-typescript'],
      // Enable lint rules for React DOM
      reactDom.configs.recommended,
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      // other options...
    },
  },
])
```

--------------------------------

### Run Development Server in Next.js

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/next-project/README.md

Use these commands to start the Next.js development server. Open http://localhost:3000 in your browser to view the application.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Develop Core Library

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Starts the development watch mode for the core 'use-mask-input' library. Navigate to the package directory first.

```bash
cd packages/use-mask-input && pnpm run dev
```

--------------------------------

### JIT Masking Example

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/dynamic-mask.md

Enables Just-In-Time (JIT) masking for a more dynamic user experience, showing the mask as the user types.

```tsx
function JitMaskInput() {
  const mask = useMaskInput({
    mask: '9{4|1}',
    options: {
      jitMasking: true,
    },
  });

  return (
    <input
      type="text"
      ref={mask}
      placeholder="0"
    />
  );
}
```

--------------------------------

### Date Mask (DD/MM/YYYY)

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Example pattern for a date in DD/MM/YYYY format.

```plaintext
99/99/9999
```

--------------------------------

### Basic Phone Input with useMaskInput

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Example of using `useMaskInput` to create a phone number input field with a specific mask pattern.

```tsx
import { useMaskInput } from 'use-mask-input';

function PhoneInput() {
  const ref = useMaskInput({ mask: '(99) 99999-9999' });
  return <input ref={ref} placeholder="(00) 00000-0000" />;
}
```

--------------------------------

### Flexible ID Mask Example

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/dynamic-mask.md

Creates a flexible ID format with variable digit and letter counts.

```tsx
function FlexibleIdInput() {
  const mask = useMaskInput({
    mask: 'ID-9{3,6}-A{1,3}',
  });

  return (
    <input
      type="text"
      ref={mask}
      placeholder="ID-000-ABC"
    />
  );
}
```

--------------------------------

### Dynamic Mask Examples

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Demonstrates dynamic masks using curly-brace repetition syntax for variable-length inputs. This allows for flexible input patterns like a specific number of digits or a range.

```tsx
// Exactly 4 digits after letters
useMaskInput({ mask: 'aa-9{4}' })

// 1 to 10 digits
useMaskInput({ mask: '9{1,10}' })

// 2 letters followed by 4–8 digits
useMaskInput({ mask: 'A{2}-9{4,8}' })

// Email (manual dynamic pattern)
useMaskInput({ mask: '*{1,20}[.*{1,20}][.*{1,20}][.*{1,20}]@*{1,20}[.*{2,6}][.*{1,2}]' })
```

--------------------------------

### Custom ID Mask

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Example of a custom ID format combining letters and numbers.

```plaintext
ID: 999-AAA
```

--------------------------------

### Email Address Mask Example

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/dynamic-mask.md

A flexible email mask pattern supporting various local and domain parts.

```tsx
function EmailInput() {
  const emailMask = useMaskInput({
    mask: '*{1,20}[.*{1,20}][.*{1,20}][.*{1,20}]@*{1,20}[.*{2,6}][.*{1,2}]',
  });

  return (
    <input
      type="email"
      ref={emailMask}
      placeholder="user@example.com"
    />
  );
}
```

--------------------------------

### One or More Characters Mask Example

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/dynamic-mask.md

Use 'A{+}' to accept one or more uppercase letters.

```tsx
function OneOrMoreInput() {
  const mask = useMaskInput({
    mask: 'A{+}',
  });

  return (
    <input
      type="text"
      ref={mask}
      placeholder="ABC"
    />
  );
}
```

--------------------------------

### Turbo Package Filtering

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Examples of using Turbo's --filter flag to target specific packages during build or test commands, optimizing monorepo workflows.

```bash
pnpm run build --filter=use-mask-input
```

```bash
pnpm run test --filter=use-mask-input
```

--------------------------------

### Variable Length Mask Example

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/dynamic-mask.md

Use '9{1,10}' to allow an input of one to ten digits.

```tsx
function VariableLengthInput() {
  const mask = useMaskInput({
    mask: '9{1,10}',
  });

  return (
    <input
      type="text"
      ref={mask}
      placeholder="0"
    />
  );
}
```

--------------------------------

### Email Input with Ant Design

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/antd.md

This example demonstrates how to implement an email input field using Ant Design and use-mask-input. It ensures proper handling of Ant Design's InputRef and type safety.

```tsx
import { Input } from 'antd';
import { useMaskInputAntd } from 'use-mask-input/antd';

function EmailInput() {
  const maskRef = useMaskInputAntd({ mask: 'email' });
  return <Input ref={maskRef} placeholder="name@example.com" />;
}
```

--------------------------------

### TanStack Form Integration with useTanStackFormMask

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Example demonstrating how to integrate useTanStackFormMask with TanStack Form to mask phone and currency inputs. Ensure the form is correctly set up with default values and submission handlers.

```tsx
import { useForm } from '@tanstack/react-form';
import { useTanStackFormMask } from 'use-mask-input';

function MyForm() {
  const maskField = useTanStackFormMask();
  const form = useForm({
    defaultValues: { phone: '', amount: '' },
    onSubmit: async ({ value }) => console.log(value),
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        e.stopPropagation();
        void form.handleSubmit();
      }}
    >
      <form.Field name="phone">
        {(field) => {
          const inputProps = maskField('(99) 99999-9999', {
            name: field.name,
            value: field.state.value,
            onBlur: field.handleBlur,
            onChange: (event) => field.handleChange(event.target.value),
          });
          return <input {...inputProps} placeholder="(00) 00000-0000" />;
        }}
      </form.Field>

      <form.Field name="amount">
        {(field) => {
          const inputProps = maskField(
            'currency',
            {
              name: field.name,
              value: field.state.value,
              onBlur: field.handleBlur,
              onChange: (event) => field.handleChange(event.target.value),
            },
            { prefix: '$ ', groupSeparator: ',', digits: 2, rightAlign: false },
          );
          return <input {...inputProps} placeholder="$ 0.00" />;
        }}
      </form.Field>
    </form>
  );
}
```

--------------------------------

### Product Code Mask Example

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/dynamic-mask.md

Enforces a pattern of two letters followed by four to eight digits.

```tsx
function ProductCodeInput() {
  const mask = useMaskInput({
    mask: 'A{2}-9{4,8}',
  });

  return (
    <input
      type="text"
      ref={mask}
      placeholder="AB-0000"
    />
  );
}
```

--------------------------------

### Testing a Mask Configuration Hook

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

This example demonstrates how to test the `getMaskOptions` function from `maskConfig.ts` using Vitest. It checks the default options returned when no mask is provided.

```typescript
// Example: src/core/maskConfig.spec.ts
import { describe, expect, it } from 'vitest';
import { getMaskOptions } from './maskConfig';

describe('maskConfig', () => {
  describe('getMaskOptions', () => {
    it('returns default options when no mask is provided', () => {
      const options = getMaskOptions();
      expect(options).toEqual({ jitMasking: false });
    });
  });
});

```

--------------------------------

### Standalone Input Masking with withMask

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Examples of using the `withMask` higher-order function for phone and currency inputs. Remember to wrap the consuming components with `React.memo` for optimal performance.

```tsx
import { memo } from 'react';
import { withMask } from 'use-mask-input';

const PhoneInput = memo(() => (
  <input ref={withMask('(99) 99999-9999')} placeholder="(00) 00000-0000" />
));

const CurrencyInput = memo(() => (
  <input
    ref={withMask('currency', {
      prefix: 'R$ ',
      radixPoint: ',',
      groupSeparator: '.',
      digits: 2,
      rightAlign: false,
    })}
  />
));
```

--------------------------------

### Static Mask Examples

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Illustrates various static mask patterns for common input types like phone numbers, dates, credit cards, and custom IDs. Literal characters are always displayed, while pattern characters like '9' and 'A' define input constraints.

```tsx
// Phone
useMaskInput({ mask: '(99) 99999-9999' })

// Date
useMaskInput({ mask: '99/99/9999' })

// Credit card
useMaskInput({ mask: '9999 9999 9999 9999' })

// Brazilian ZIP code
useMaskInput({ mask: '99999-999' })

// License plate (old Brazilian format: letters + digits)
useMaskInput({ mask: 'AAA-9999' })

// Custom ID
useMaskInput({ mask: 'ID: 999-AAA' })
```

--------------------------------

### TanStack Form Integration with withTanStackFormMask

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Example of using `withTanStackFormMask` to mask input props passed as a prop. The consuming component should be memoized with `React.memo`.

```tsx
import { memo } from 'react';
import { withTanStackFormMask } from 'use-mask-input';

const MaskedField = memo(function MaskedField({ inputProps }) {
  const maskedProps = withTanStackFormMask(inputProps, '(99) 99999-9999');
  return <input {...maskedProps} />;
});
```

--------------------------------

### React Hook Form with useHookFormMask Integration

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

An example demonstrating how to use `useHookFormMask` to register multiple masked input fields within a React Hook Form.

```tsx
import { useForm } from 'react-hook-form';
import { useHookFormMask } from 'use-mask-input';

interface FormData {
  phone: string;
  email: string;
  cpf: string;
  amount: string;
}

function MyForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<FormData>();
  const registerWithMask = useHookFormMask(register);

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input
        {...registerWithMask('phone', '(99) 99999-9999', {
          required: 'Phone is required',
        })}
        placeholder="(00) 00000-0000"
      />
      {errors.phone && <span>{errors.phone.message}</span>}

      <input {...registerWithMask('email', 'email')} placeholder="user@example.com" />
      <input {...registerWithMask('cpf', 'cpf')} placeholder="000.000.000-00" />
      <input
        {...registerWithMask('amount', 'currency', {
          prefix: '$ ',
          digits: 2,
        })}
        placeholder="$ 0.00"
      />

      {/* Fields without masks still use regular register */}
      <input {...register('name')} placeholder="Name" />

      <button type="submit">Submit</button>
    </form>
  );
}
```

--------------------------------

### Apply Mask with Options

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/api-reference.md

Applies an input mask using a higher-order function with specific configuration options. Ensure the component is wrapped with `React.memo` for stable ref callback identity. This example demonstrates currency formatting.

```tsx
import { memo } from 'react';
import { withMask } from 'use-mask-input';

const CurrencyInput = memo(() => {
  return (
    <input
      ref={withMask('currency', {
        prefix: 'R$ ',
        radixPoint: ',',
        groupSeparator: '.',
        digits: 2,
        rightAlign: false,
      })}
    />
  );
});
```

--------------------------------

### Alternator Mask Examples

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Define multiple valid mask patterns using the '|' separator or an array. The engine automatically selects the pattern that best matches the current input.

```tsx
useMaskInput({ mask: '(99) 9999-9999|(99) 99999-9999' })
```

```tsx
useMaskInput({ mask: ['9999-9999', '99999-9999'] })
```

```tsx
useMaskInput({ mask: ['9999 9999 9999 9999', '9999 999999 99999'] })
```

```tsx
useMaskInput({ mask: '99/99/9999|99-99-9999|99.99.9999' })
```

```tsx
useMaskInput({ mask: ['AAA-9999', 'AAA9A99'] })
```

--------------------------------

### Example: useHookFormMaskAntd with Ant Design Input

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/api-reference.md

Demonstrates how to use the `useHookFormMaskAntd` hook to create a masked phone number input field within a React Hook Form and Ant Design application.

```tsx
import { Input } from 'antd';
import { useForm } from 'react-hook-form';
import { useHookFormMaskAntd } from 'use-mask-input/antd';

function MyForm() {
  const { register, handleSubmit } = useForm();
  const registerWithMask = useHookFormMaskAntd(register);

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <Input
        {...registerWithMask('phone', '(99) 99999-9999')}
        placeholder="(00) 00000-0000"
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

--------------------------------

### Common Building Commands

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Quick reference for building all packages or a specific package like the library.

```bash
# Building
pnpm run build            # All packages
pnpm run build --filter=use-mask-input  # Library only
```

--------------------------------

### Common Versioning and Release Commands

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Quick reference for creating changesets, bumping package versions, and releasing the library.

```bash
# Versioning
pnpm run changeset        # Create changeset
pnpm run version-packages # Bump versions
pnpm run release          # Publish (automated in CI)
```

--------------------------------

### Zero or More Characters Mask Example

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/dynamic-mask.md

Use '9{}' to accept zero or more digits.

```tsx
function ZeroOrMoreInput() {
  const mask = useMaskInput({
    mask: '9{}',
  });

  return (
    <input
      type="text"
      ref={mask}
      placeholder="123"
    />
  );
}
```

--------------------------------

### Documentation Commands

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Commands to run the documentation site locally or build it. Deployment is automated on releases.

```bash
pnpm run dev:docs
```

```bash
pnpm run build --filter=docs
```

--------------------------------

### Brazilian Phone Mask (Landline)

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Example pattern for Brazilian landline phone numbers.

```plaintext
(99) 9999-9999
```

--------------------------------

### Version Management and Publishing

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Commands for managing package versions and publishing. Create a changeset, then version packages, and finally release.

```bash
pnpm run changeset
```

```bash
pnpm run version-packages
```

```bash
pnpm run release
```

--------------------------------

### Brazilian Phone Mask (Mobile)

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Example pattern for Brazilian mobile phone numbers.

```plaintext
(99) 99999-9999
```

--------------------------------

### Common Testing and Linting Commands

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Quick reference for running all tests, performing type checks, and linting the codebase.

```bash
# Testing
pnpm run test             # All tests
pnpm run type-check       # Type checking
pnpm run lint             # Linting
```

--------------------------------

### Create a Changeset

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Command to initiate the creation of a new changeset file. This process involves selecting packages, choosing a version bump type, and writing a summary of changes.

```bash
pnpm run changeset
```

--------------------------------

### Build All Packages

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Builds all packages within the monorepo. Use --filter to build specific packages.

```bash
pnpm run build
```

```bash
pnpm run build --filter=use-mask-input
```

--------------------------------

### Build Docusaurus Application

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/README.md

Execute this command from the root directory to build the Docusaurus application. You can also run 'npm run build' from this directory.

```bash
# From root
npm run build

# Or from this directory
npm run build
```

--------------------------------

### Currency Input with useMaskInput and Options

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Demonstrates using `useMaskInput` with a 'currency' alias and custom options for formatting, including prefix, group separator, and decimal places.

```tsx
function CurrencyInput() {
  const ref = useMaskInput({
    mask: 'currency',
    options: {
      prefix: 'R$ ',
      groupSeparator: '.',
      radixPoint: ',',
      digits: 2,
      rightAlign: false,
    },
  });
  return <input ref={ref} placeholder="R$ 0,00" />;
}
```

--------------------------------

### Common Cleanup Commands

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Commands to clean up build artifacts, node modules, and other generated files, followed by a re-installation.

```bash
# Cleanup
rm -rf node_modules .turbo dist coverage build .next
pnpm install
```

--------------------------------

### Brazilian Bank Account Mask with Placeholder Customization

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/alias-mask.md

Customize the placeholder for the 'br-bank-account' mask to guide users on the expected format.

```tsx
function BankAccountInput() {
  const bankAccountMask = useMaskInput({
    mask: 'br-bank-account',
  });

  return (
    <input
      type="text"
      ref={bankAccountMask}
      placeholder="(000) 12345678-9"
    />
  );
}
```

--------------------------------

### Configure useMaskInput with Options

Source: https://context7.com/eduardoborges/use-mask-input/llms.txt

Demonstrates how to configure the useMaskInput hook with various options for currency formatting. Ensure Inputmask options are correctly passed to customize behavior like placeholders, unmasking, and formatting.

```tsx
import { useMaskInput } from 'use-mask-input';

const mask = useMaskInput({
  mask: 'currency',
  options: {
    placeholder: '0',          // char for unfilled positions (default "_")
    autoUnmask: false,         // if true, input.value returns raw digits
    removeMaskOnSubmit: true,  // strip mask before form submit
    clearIncomplete: true,     // clear field on blur if incomplete
    prefix: '$ ',
    suffix: ' USD',
    radixPoint: '.',           // decimal separator
    groupSeparator: ',',       // thousands separator
    digits: 2,                 // fractional digit count
    rightAlign: false,         // align text to the right
    min: 0,
    max: 999999,
    inputFormat: 'dd/mm/yyyy', // date input format (datetime alias)
    outputFormat: 'yyyy-mm-dd',// date unmasked output (datetime alias)
    jitMasking: true,          // show mask only as user types
    nullable: true,            // return "" instead of mask when empty
    casing: 'upper',           // 'upper' | 'lower' | 'title'
    oncomplete: () => console.log('mask complete'),
    onincomplete: () => console.log('mask incomplete'),
    oncleared: () => console.log('mask cleared'),
  },
});

```

--------------------------------

### Clean Build Artifacts

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Use this command to remove all 'dist' and '.turbo' directories to ensure a clean build.

```bash
# Clean all build artifacts
find . -name "dist" -type d -exec rm -rf {} +
find . -name ".turbo" -type d -exec rm -rf {} +
```

--------------------------------

### Fixed Length Mask Example

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/dynamic-mask.md

Use 'aa-9{4}' to enforce a pattern of two letters followed by exactly four digits.

```tsx
import { useMaskInput } from 'use-mask-input';

function FixedLengthInput() {
  const mask = useMaskInput({
    mask: 'aa-9{4}',
  });

  return (
    <input
      type="text"
      ref={mask}
      placeholder="AA-0000"
    />
  );
}
```

--------------------------------

### Date Input with useMaskInput and Datetime Alias

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Shows how to use `useMaskInput` with the 'datetime' alias and specify input and output formats for date masking.

```tsx
function DateInput() {
  const ref = useMaskInput({
    mask: 'datetime',
    options: {
      inputFormat: 'dd/mm/yyyy',
      outputFormat: 'yyyy-mm-dd',
    },
  });
  return <input ref={ref} placeholder="DD/MM/YYYY" />;
}
```

--------------------------------

### Force Turbo Build

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Execute a Turbo build, forcing it to ignore the cache. Useful for ensuring a clean build process.

```bash
# Force Turbo to ignore cache
pnpm run build -- --force
```

--------------------------------

### Complex Alternator Mask Example

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/alternator-mask.md

A complex alternator mask combining different character types and formats, such as all letters, all digits, or a mix of digits and letters.

```tsx
function ComplexInput() {
  const complexMask = useMaskInput({
    mask: 'aaaa|9999|9AA9',
  });

  return (
    <input
      type="text"
      ref={complexMask}
      placeholder="AAAA or 0000 or 0AA0"
    />
  );
}
```

--------------------------------

### Run All Tests

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Executes all tests in the project using Vitest. Specific packages can be tested by navigating to their directory first.

```bash
pnpm run test
```

```bash
cd packages/use-mask-input && pnpm run test
```

--------------------------------

### Phone Number Alternator Mask

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/alternator-mask.md

This example demonstrates an alternator mask for phone numbers, supporting both landline and mobile formats with different digit counts.

```tsx
function PhoneInput() {
  const phoneMask = useMaskInput({
    mask: '(99) 9999-9999|(99) 99999-9999',
  });

  return (
    <input
      type="tel"
      ref={phoneMask}
      placeholder="(00) 00000-0000"
    />
  );
}
```

--------------------------------

### useTanStackFormMask with Custom Options

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tanstack-form.md

Shows how to use `useTanStackFormMask` with custom options for formatting, such as currency.

```APIDOC
## useTanStackFormMask with Custom Options

### Description
Allows for advanced masking configurations using an `options` object.

### Example Usage
```tsx
const inputProps = maskField(
  'currency',
  {
    name: field.name,
    value: field.state.value,
    onBlur: field.handleBlur,
    onChange: (event) => field.handleChange(event.target.value),
  },
  {
    prefix: '$ ',
    groupSeparator: ',',
    digits: 2,
    rightAlign: false,
  },
);
```
```

--------------------------------

### Run ESLint with Auto-Fix

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Execute ESLint to check for code style issues and automatically fix them.

```bash
# Run ESLint with auto-fix
cd packages/use-mask-input
pnpm run lint -- --fix
```

--------------------------------

### Optional Mask Examples

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Use square brackets to define optional sections within a mask pattern. This allows for flexible input like optional digits or area codes.

```tsx
useMaskInput({ mask: '(99) [9]9999-9999' })
```

```tsx
useMaskInput({ mask: '[99] 9999-9999' })
```

```tsx
useMaskInput({ mask: '[+99] [9]9999-9999' })
```

```tsx
useMaskInput({ mask: '9999[ 9999][ 9999][ 9999]' })
```

--------------------------------

### Run Tests in Watch Mode

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Execute tests in watch mode for continuous feedback during development. Requires the library to be building in watch mode in a separate terminal.

```bash
# Run tests in watch mode
cd packages/use-mask-input
pnpm run dev  # In one terminal (builds in watch mode)
pnpm exec vitest  # In another terminal (runs tests in watch mode)
```

--------------------------------

### Basic Alternator Mask Syntax

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/alternator-mask.md

Use the pipe character '|' to separate multiple mask patterns. This example accepts either an 8-digit or a 9-digit phone number format.

```tsx
import { useMaskInput } from 'use-mask-input';

function PhoneInput() {
  const phoneMask = useMaskInput({
    mask: '9999-9999|99999-9999',
  });

  return (
    <input
      type="tel"
      ref={phoneMask}
      placeholder="0000-0000"
    />
  );
}
```

--------------------------------

### Package Exports Configuration

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Defines the entry points for the library, including default imports and specific imports for Ant Design components.

```json
{
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.js",
    "require": "./dist/index.cjs"
  },
  "./antd": {
    "types": "./dist/antd.d.ts",
    "import": "./dist/antd.js",
    "require": "./dist/antd.cjs"
  }
}
```

--------------------------------

### Version Packages with Changesets

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Command to process existing changeset files, update package.json versions, regenerate the CHANGELOG.md, and clean up changeset files.

```bash
pnpm run version-packages
```

--------------------------------

### Release Packages

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Command to publish packages to npm, typically by running 'changeset publish'. This is often automated within CI/CD pipelines.

```bash
pnpm run release
```

--------------------------------

### Mixed Pattern Alternator Mask

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tutorial-basics/alternator-mask.md

This example shows an alternator mask that accepts combinations of letters and digits in different patterns, such as three letters, three digits, or a digit followed by two letters.

```tsx
function MixedInput() {
  const mixedMask = useMaskInput({
    mask: '(aaa)|(999)|(9AA)',
  });

  return (
    <input
      type="text"
      ref={mixedMask}
      placeholder="ABC or 123 or 1AB"
    />
  );
}
```

--------------------------------

### Generate Test Coverage

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Runs tests and generates code coverage reports. Reports are saved in the 'coverage/' directory of the respective package.

```bash
cd packages/use-mask-input && pnpm run test
```

--------------------------------

### Apply Input Mask with useMaskInput Hook

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/api-reference.md

Use this hook to get a stable ref callback for applying an input mask. Attach the returned ref to any input element. The callback also exposes `unmaskedValue()`.

```tsx
import { useMaskInput } from 'use-mask-input';

function PhoneInput() {
  const maskRef = useMaskInput({
    mask: '(99) 99999-9999',
  });

  return <input ref={maskRef} placeholder="(00) 00000-0000" />;
}
```

--------------------------------

### Clear Turbo Cache

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Remove the Turbo build cache to force a full rebuild. Use this if you suspect cache-related issues.

```bash
# Clear Turbo cache
rm -rf .turbo
```

--------------------------------

### useTanStackFormMask Hook for TanStack Form

Source: https://context7.com/eduardoborges/use-mask-input/llms.txt

Use this hook to get a stable mask-applying function that merges into TanStack Form field props. Pass the field's name, value, onBlur, and onChange, then spread the result onto the input element.

```tsx
import { useForm } from '@tanstack/react-form';
import { useTanStackFormMask } from 'use-mask-input';

type FormValues = { phone: string; amount: string };

function PaymentForm() {
  const maskField = useTanStackFormMask();
  const form = useForm<FormValues>({
    defaultValues: { phone: '', amount: '' },
    onSubmit: async ({ value }) => console.log(value),
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        e.stopPropagation();
        void form.handleSubmit();
      }}
    >
      <form.Field name="phone">
        {(field) => (
          <input
            {...maskField('(99) 99999-9999', {
              name: field.name,
              value: field.state.value,
              onBlur: field.handleBlur,
              onChange: (e) => field.handleChange(e.target.value),
            })}
            placeholder="(00) 00000-0000"
          />
        )}
      </form.Field>

      <form.Field name="amount">
        {(field) => (
          <input
            {...maskField(
              'currency',
              {
                name: field.name,
                value: field.state.value,
                onBlur: field.handleBlur,
                onChange: (e) => field.handleChange(e.target.value),
              },
              { prefix: '$ ', groupSeparator: ',', digits: 2, rightAlign: false },
            )}
            placeholder="$ 0.00"
          />
        )}
      </form.Field>

      <button type="submit">Pay</button>
    </form>
  );
}
```

--------------------------------

### Basic Input Mask with useMaskInput

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/intro.md

Use the `useMaskInput` hook with a plain input element. It returns a ref callback to attach to your input.

```tsx
import { useMaskInput } from 'use-mask-input';

function PhoneInput() {
  const ref = useMaskInput({ mask: '(99) 99999-9999' });
  return <input ref={ref} />;
}
```

--------------------------------

### useMaskInputAntd Basic Usage

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/docussaurus/static/llm.txt

Integrates use-mask-input with Ant Design Input components for basic masking. Ensure the 'use-mask-input/antd' package is imported.

```tsx
import { Input, Form, Button } from 'antd';
import { useMaskInputAntd } from 'use-mask-input/antd';

// Basic usage
function PhoneInput() {
  const ref = useMaskInputAntd({ mask: '(99) 99999-9999' });
  return <Input ref={ref} placeholder="(00) 00000-0000" />;
}

// With Ant Design Form
function AntdForm() {
  const [form] = Form.useForm();

  const phoneMaskRef = useMaskInputAntd({ mask: '(999) 999-9999' });
  const emailMaskRef = useMaskInputAntd({ mask: 'email' });
  const currencyMaskRef = useMaskInputAntd({
    mask: 'currency',
    options: { prefix: '$ ', radixPoint: '.', digits: 2, groupSeparator: ',', rightAlign: false },
  });

  return (
    <Form form={form} layout="vertical" onFinish={(values) => console.log(values)}>
      <Form.Item name="phone" label="Phone" rules={[{ required: true }]}>
        <Input ref={phoneMaskRef} placeholder="(555) 123-4567" />
      </Form.Item>
      <Form.Item name="email" label="Email" rules={[{ required: true }]}>
        <Input ref={emailMaskRef} placeholder="name@example.com" />
      </Form.Item>
      <Form.Item name="amount" label="Amount">
        <Input ref={currencyMaskRef} placeholder="$ 0.00" />
      </Form.Item>
      <Form.Item>
        <Button type="primary" htmlType="submit">Submit</Button>
      </Form.Item>
    </Form>
  );
}
```

--------------------------------

### Built-in Named Presets (Aliases)

Source: https://context7.com/eduardoborges/use-mask-input/llms.txt

Utilize predefined string aliases for common mask patterns like datetime, email, currency, and more. Custom options can be provided for specific aliases.

```tsx
import { useMaskInput } from 'use-mask-input';

const dateMask = useMaskInput({
  mask: 'datetime',
  options: { inputFormat: 'dd/mm/yyyy', outputFormat: 'yyyy-mm-dd' },
});

const currencyMask = useMaskInput({
  mask: 'currency',
  options: { prefix: 'R$ ', groupSeparator: '.', radixPoint: ',', digits: 2 },
});

const ipMask  = useMaskInput({ mask: 'ip' });
const macMask = useMaskInput({ mask: 'mac' });
const cpfMask = useMaskInput({ mask: 'cpf' });       // 000.000.000-00

// Read datetime in outputFormat
<input ref={dateMask} placeholder="DD/MM/YYYY" />
// dateMask.unmaskedValue() → "2024-06-15" (outputFormat)

<input ref={currencyMask} placeholder="R$ 0,00" />
<input ref={ipMask}  placeholder="192.168.0.1" />
<input ref={macMask} placeholder="00:00:00:00:00:00" />
```

--------------------------------

### useTanStackFormMask Basic Usage

Source: https://github.com/eduardoborges/use-mask-input/blob/main/docs/tanstack-form.md

Demonstrates the basic usage of the `useTanStackFormMask` hook to mask an input field within a TanStack Form.

```APIDOC
## useTanStackFormMask

### Description
`useTanStackFormMask` returns a helper that receives your TanStack input props and returns masked input props with a stable ref callback.

### Method Signature
```typescript
function useTanStackFormMask(): <T extends TanStackFormInputProps>(
  mask: Mask,
  inputProps: T,
  options?: Options
) => UseTanStackFormMaskReturn<T>
```

### Example Usage
```tsx
import { useForm } from '@tanstack/react-form';
import { useTanStackFormMask } from 'use-mask-input';

type FormValues = {
  phone: string;
};

function MyForm() {
  const maskField = useTanStackFormMask();
  const form = useForm({
    defaultValues: { phone: '' } as FormValues,
    onSubmit: async ({ value }) => {
      console.log(value);
    },
  });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        event.stopPropagation();
        void form.handleSubmit();
      }}
    >
      <form.Field name="phone">
        {(field) => {
          const inputProps = maskField(
            '(99) 99999-9999',
            {
              name: field.name,
              value: field.state.value,
              onBlur: field.handleBlur,
              onChange: (event) => field.handleChange(event.target.value),
            },
          );

          return <input {...inputProps} placeholder="(00) 00000-0000" />;
        }}
      </form.Field>
    </form>
  );
}
```
```

--------------------------------

### Lint and Type Check Packages

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Runs ESLint for code linting and performs type checking across all packages. Specific packages can be targeted.

```bash
pnpm run lint
```

```bash
cd packages/use-mask-input && pnpm run lint
```

```bash
pnpm run type-check
```

```bash
cd packages/use-mask-input && pnpm run type-check
```

--------------------------------

### Check Types Without Building

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Perform a type check on the library without initiating a full build. Useful for quickly verifying type integrity.

```bash
# Check types without building
cd packages/use-mask-input
pnpm run type-check
```

--------------------------------

### Configure Type-Aware ESLint Rules

Source: https://github.com/eduardoborges/use-mask-input/blob/main/apps/vite-project/README.md

Update ESLint configuration to enable type-aware lint rules for production applications. Ensure `tsconfig.node.json` and `tsconfig.app.json` are correctly specified.

```javascript
export default defineConfig([
  globalIgnores(['dist']),
  {
    files: ['**/*.{ts,tsx}']
    extends: [
      // Other configs...

      // Remove tseslint.configs.recommended and replace with this
      tseslint.configs.recommendedTypeChecked,
      // Alternatively, use this for stricter rules
      tseslint.configs.strictTypeChecked,
      // Optionally, add this for stylistic rules
      tseslint.configs.stylisticTypeChecked,

      // Other configs...
    ],
    languageOptions: {
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      // other options...
    },
  },
])
```

--------------------------------

### Merge Mask Options

Source: https://github.com/eduardoborges/use-mask-input/blob/main/AGENTS.md

Demonstrates merging default alias options with user-provided options. User options take precedence.

```typescript
getMaskOptions('cpf', { placeholder: '___.___.___-__' })
// Returns: { mask: '999.999.999-99', placeholder: '___.___.___-__', jitMasking: false }
```