awesome-auth-input 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 awesome-auth-input contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,255 @@
+# awesome-auth-input
+
+A headless, accessible, and fully-typed React component for OTP/auth code inputs with support for numeric, alphabetic, and custom validation patterns.
+
+## Features
+
+- **Headless** - Bring your own styles, no CSS included
+- **Accessible** - Full keyboard navigation, screen reader support, ARIA labels
+- **Flexible validation** - Numeric, alphabetic, alphanumeric, or custom regex patterns
+- **Controlled & uncontrolled** - Works both ways
+- **Auto-submit** - Optional auto-submit when all fields are filled
+- **Form integration** - Hidden input for native form submission
+- **Password mode** - Mask input characters
+- **Paste support** - Paste codes directly
+- **TypeScript** - Fully typed with exported types
+- **Zero dependencies** - Only React as a peer dependency
+
+## Installation
+
+```bash
+npm install awesome-auth-input
+```
+
+```bash
+yarn add awesome-auth-input
+```
+
+```bash
+pnpm add awesome-auth-input
+```
+
+## Quick Start
+
+```tsx
+import { AuthCode } from 'awesome-auth-input';
+
+function OTPInput() {
+  return (
+    <AuthCode.Group onComplete={(code) => console.log('Code:', code)}>
+      <AuthCode.Input index={0} />
+      <AuthCode.Input index={1} />
+      <AuthCode.Input index={2} />
+      <AuthCode.Input index={3} />
+      <AuthCode.Input index={4} />
+      <AuthCode.Input index={5} />
+    </AuthCode.Group>
+  );
+}
+```
+
+## API Reference
+
+### `<AuthCode.Group>`
+
+The root component that manages state and validation for auth code inputs.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | The `<AuthCode.Input>` components |
+| `name` | `string` | - | Name attribute for form submission |
+| `validation` | `ValidationPattern` | `{ type: "numeric" }` | Validation pattern for input characters |
+| `autoSubmit` | `boolean` | `true` | Auto-submit the form when all fields are filled |
+| `onComplete` | `(value: string) => void` | - | Callback when all fields are filled |
+| `value` | `string` | - | Controlled value |
+| `onValueChange` | `(value: string) => void` | - | Callback when value changes |
+| `defaultValue` | `string` | - | Initial value for uncontrolled mode |
+| `type` | `"text" \| "password"` | `"text"` | Input type (text shows, password masks) |
+| `disabled` | `boolean` | `false` | Disable all inputs |
+
+Plus all standard `div` props (className, style, etc.)
+
+### `<AuthCode.Input>`
+
+Individual input field for a single character. Must be used within `<AuthCode.Group>`.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `index` | `number` | **Required.** Position of this input (0-based) |
+
+Plus most standard `input` props (className, style, onKeyDown, etc.)
+
+### Validation Patterns
+
+```tsx
+// Numeric only (default)
+<AuthCode.Group validation={{ type: "numeric" }} />
+
+// Alphabetic only (a-z, A-Z)
+<AuthCode.Group validation={{ type: "alpha" }} />
+
+// Alphanumeric (letters and numbers)
+<AuthCode.Group validation={{ type: "alphanumeric" }} />
+
+// Custom validation with regex
+<AuthCode.Group
+  validation={{
+    type: "custom",
+    regex: /^[A-Z]$/,        // Validation regex
+    pattern: "[A-Z]{1}",      // HTML pattern attribute
+    inputMode: "text"         // Virtual keyboard hint
+  }}
+/>
+```
+
+## Examples
+
+### Controlled Component
+
+```tsx
+import { useState } from 'react';
+import { AuthCode } from 'awesome-auth-input';
+
+function ControlledOTP() {
+  const [code, setCode] = useState('');
+
+  return (
+    <>
+      <AuthCode.Group
+        value={code}
+        onValueChange={setCode}
+        onComplete={(value) => verifyCode(value)}
+      >
+        <AuthCode.Input index={0} />
+        <AuthCode.Input index={1} />
+        <AuthCode.Input index={2} />
+        <AuthCode.Input index={3} />
+      </AuthCode.Group>
+      <button onClick={() => setCode('')}>Clear</button>
+    </>
+  );
+}
+```
+
+### Form Integration
+
+```tsx
+import { AuthCode } from 'awesome-auth-input';
+
+function OTPForm() {
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault();
+      const formData = new FormData(e.currentTarget);
+      console.log('OTP:', formData.get('otp'));
+    }}>
+      <AuthCode.Group name="otp" autoSubmit>
+        <AuthCode.Input index={0} />
+        <AuthCode.Input index={1} />
+        <AuthCode.Input index={2} />
+        <AuthCode.Input index={3} />
+        <AuthCode.Input index={4} />
+        <AuthCode.Input index={5} />
+      </AuthCode.Group>
+      <button type="submit">Verify</button>
+    </form>
+  );
+}
+```
+
+### Password/PIN Mode
+
+```tsx
+<AuthCode.Group type="password">
+  <AuthCode.Input index={0} />
+  <AuthCode.Input index={1} />
+  <AuthCode.Input index={2} />
+  <AuthCode.Input index={3} />
+</AuthCode.Group>
+```
+
+### With Separator
+
+```tsx
+<AuthCode.Group>
+  <AuthCode.Input index={0} />
+  <AuthCode.Input index={1} />
+  <AuthCode.Input index={2} />
+  <span className="separator">-</span>
+  <AuthCode.Input index={3} />
+  <AuthCode.Input index={4} />
+  <AuthCode.Input index={5} />
+</AuthCode.Group>
+```
+
+### Custom Styling
+
+The component is completely unstyled. Add your own CSS:
+
+```css
+.otp-group {
+  display: flex;
+  gap: 8px;
+}
+
+.otp-input {
+  width: 48px;
+  height: 56px;
+  text-align: center;
+  font-size: 24px;
+  border: 2px solid #ccc;
+  border-radius: 8px;
+}
+
+.otp-input:focus {
+  outline: none;
+  border-color: #0070f3;
+  box-shadow: 0 0 0 3px rgba(0, 112, 243, 0.15);
+}
+```
+
+```tsx
+<AuthCode.Group className="otp-group">
+  <AuthCode.Input index={0} className="otp-input" />
+  <AuthCode.Input index={1} className="otp-input" />
+  {/* ... */}
+</AuthCode.Group>
+```
+
+## TypeScript
+
+Types are exported for your convenience:
+
+```tsx
+import type {
+  AuthCodeGroupProps,
+  AuthCodeInputProps,
+  ValidationPattern,
+  CustomValidation,
+} from 'awesome-auth-input';
+```
+
+## Keyboard Navigation
+
+- **Arrow Left/Right** - Navigate between inputs
+- **Backspace** - Delete current character and move to previous
+- **Ctrl/Cmd + Backspace** - Clear all inputs
+- **Enter** - Submit the form
+- **Paste** - Paste code from clipboard (auto-fills all fields)
+
+## Accessibility
+
+- Proper ARIA labels for each input
+- Focus management with roving tabindex
+- Screen reader announcements
+- Respects `prefers-reduced-motion`
+- Works with password managers (disabled with data attributes)
+
+## Browser Support
+
+- Chrome, Firefox, Safari, Edge (latest versions)
+- Mobile browsers with virtual keyboards
+
+## License
+
+MIT

package/dist/AuthCode/OneTimePassword.d.ts

@@ -0,0 +1,159 @@
+import { type ReactNode } from "react";
+interface AuthCodeCustomField {
+    /**
+     * The child components, typically `<AuthCode.Input>` components.
+     *
+     * All `<AuthCode.Input>` components must be direct or nested children of `<AuthCode.Group>`.
+     */
+    children: ReactNode;
+    /**
+     * A string specifying a name for the input control. This name is submitted
+     * along with the control's value when the form data is submitted.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#name
+     */
+    name?: string;
+    /**
+     * Specifies what type of validation the user agent has to provide for each
+     * character input. Allows "numeric", "alpha", "alphanumeric", or a custom
+     * validation pattern with regex.
+     *
+     * @defaultValue `{ type: "numeric" }`
+     *
+     * @example
+     * ```tsx
+     * // Numeric only (default)
+     * <AuthCode.Group validation={{ type: "numeric" }} />
+     *
+     * // Alphabetic only
+     * <AuthCode.Group validation={{ type: "alpha" }} />
+     *
+     * // Custom validation
+     * <AuthCode.Group
+     *   validation={{
+     *     type: "custom",
+     *     regex: /^[A-Z]$/,
+     *     pattern: "[A-Z]{1}",
+     *     inputMode: "text"
+     *   }}
+     * />
+     * ```
+     */
+    validation?: ValidationPattern;
+    /**
+     * Whether or not the component should attempt to automatically submit when
+     * all fields are filled. If the field is associated with an HTML `form`
+     * element, the form's `requestSubmit` method will be called.
+     *
+     * @defaultValue `true`
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit
+     */
+    autoSubmit?: boolean;
+    /**
+     * When the `autoSubmit` prop is set to `true`, this callback will be fired
+     * before attempting to submit the associated form. It will be called whether
+     * or not a form is located, or if submission is not allowed.
+     *
+     * The callback receives the complete auth code value as a string.
+     *
+     * @example
+     * ```tsx
+     * <AuthCode.Group
+     *   onComplete={(value) => {
+     *     console.log('Code entered:', value);
+     *     verifyCode(value);
+     *   }}
+     * />
+     * ```
+     */
+    onComplete?: (value: string) => void;
+    /**
+     * The controlled value of the field. When provided, the component operates
+     * in controlled mode. This string's value, if present, must match the total
+     * number of `<AuthCode.Input>` components.
+     *
+     * @example
+     * ```tsx
+     * const [code, setCode] = useState('');
+     * <AuthCode.Group value={code} onValueChange={setCode} />
+     * ```
+     */
+    value?: string;
+    /**
+     * A callback fired whenever the field value changes. This callback is called
+     * with the complete auth code value as a string.
+     *
+     * Use this prop together with `value` to create a controlled component.
+     */
+    onValueChange?: (value: string) => void;
+    /**
+     * The initial value of the uncontrolled field. When provided without `value`,
+     * the component operates in uncontrolled mode.
+     *
+     * @example
+     * ```tsx
+     * <AuthCode.Group defaultValue="123" />
+     * ```
+     */
+    defaultValue?: string;
+    /**
+     * The type of control to render. Allows "text" or "password".
+     *
+     * When set to "password", the input characters will be masked.
+     *
+     * @defaultValue `"text"`
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#type
+     */
+    type?: "text" | "password";
+    /**
+     * Whether or not the input elements are disabled.
+     *
+     * When set to `true`, all `<AuthCode.Input>` components will be disabled
+     * and users will not be able to interact with them.
+     *
+     * @defaultValue `false`
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled
+     */
+    disabled?: boolean;
+}
+interface AuthCodeFieldProps extends AuthCodeCustomField, Omit<React.ComponentProps<"div">, keyof AuthCodeCustomField> {
+}
+declare const AuthCodeField: import("react").ForwardRefExoticComponent<Omit<AuthCodeFieldProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare const AuthCodeHiddenInput: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & import("react").RefAttributes<HTMLInputElement>>;
+/**
+ * Input component for entering a single character of the auth code.
+ *
+ * **Must be used within `<AuthCode.Group>`**
+ *
+ * @example
+ *
+ * <AuthCode.Group>
+ *   <AuthCode.Input index={0} />
+ *   <AuthCode.Input index={1} />
+ * </AuthCode.Group>
+ *  */
+export declare function AuthCodeInput({ index, ...props }: AuthCodeInputProps): import("react/jsx-runtime").JSX.Element;
+type InputMode = "text" | "numeric" | "none";
+type ValidationPattern = ({
+    type: "custom";
+} & CustomValidation) | {
+    type: "alpha";
+} | {
+    type: "alphanumeric";
+} | {
+    type: "numeric";
+};
+type CustomValidation = {
+    regex: RegExp;
+    pattern: string;
+    inputMode: InputMode;
+};
+interface AuthCodeInputProps extends Omit<React.ComponentProps<"input">, "value" | "placeholder" | "disabled" | "autoComplete" | "defaultValue" | "type"> {
+    index: number;
+}
+export { AuthCodeField as Group, AuthCodeInput as Input, AuthCodeHiddenInput as HiddenInput, };
+export type { AuthCodeFieldProps as AuthCodeGroupProps, AuthCodeInputProps, ValidationPattern, CustomValidation, };
+//# sourceMappingURL=OneTimePassword.d.ts.map

package/dist/AuthCode/OneTimePassword.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OneTimePassword.d.ts","sourceRoot":"","sources":["../../src/AuthCode/OneTimePassword.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,SAAS,EAKf,MAAM,OAAO,CAAC;AAGf,UAAU,mBAAmB;IAC3B;;;;OAIG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,kBACR,SAAQ,mBAAmB,EACzB,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,mBAAmB,CAAC;CAAG;AAEnE,QAAA,MAAM,aAAa,4HAyPlB,CAAC;AAEF,QAAA,MAAM,mBAAmB,sNAyBvB,CAAC;AAEH;;;;;;;;;;;MAWM;AACN,wBAAgB,aAAa,CAAC,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,EAAE,kBAAkB,2CAkKpE;AAgHD,KAAK,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAE7C,KAAK,iBAAiB,GAClB,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,gBAAgB,CAAC,GACvC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,KAAK,gBAAgB,GAAG;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;CACtB,CAAC;AAEF,UAAU,kBACR,SAAQ,IAAI,CACV,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,EAC3B,OAAO,GACP,aAAa,GACb,UAAU,GACV,cAAc,GACd,cAAc,GACd,MAAM,CACT;IACD,KAAK,EAAE,MAAM,CAAC;CACf;AAgED,OAAO,EACL,aAAa,IAAI,KAAK,EACtB,aAAa,IAAI,KAAK,EACtB,mBAAmB,IAAI,WAAW,GACnC,CAAC;AAEF,YAAY,EACV,kBAAkB,IAAI,kBAAkB,EACxC,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,CAAC"}

package/dist/AuthCode/index.d.ts

@@ -0,0 +1,3 @@
+export * from './OneTimePassword';
+export { Group as default } from './OneTimePassword';
+//# sourceMappingURL=index.d.ts.map

package/dist/AuthCode/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/AuthCode/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,KAAK,IAAI,OAAO,EAAE,MAAM,mBAAmB,CAAC"}