feat: focusSlot API and cursor lock fix

docs/src/content/docs/getting-started.mdx

@@ -66,12 +66,47 @@ We create a few examples that you can copy paste and use in your project.
 
 ## SlotProps
 
-| Prop              | Type           | Description                |
-| ----------------- | -------------- | -------------------------- |
-| `char`            | string \| null | Character in the slot      |
-| `isActive`        | boolean        | Whether the slot is active |
-| `hasFakeCaret`    | boolean        | Whether to show fake caret |
-| `placeholderChar` | string \| null | Placeholder character      |
+| Prop              | Type           | Description                                                               |
+| ----------------- | -------------- | ------------------------------------------------------------------------- |
+| `char`            | string \| null | Character in the slot                                                     |
+| `isActive`        | boolean        | Whether the slot is active                                                |
+| `hasFakeCaret`    | boolean        | Whether to show fake caret                                                |
+| `placeholderChar` | string \| null | Placeholder character                                                     |
+| `focus`           | () => void     | Focuses the input at this slot's position, suppressing iOS clear behavior |
+
+Each slot exposes a `focus()` method — no ref required. Pass it to `onPress` on a wrapping `Pressable` to let users tap any slot and resume typing from there:
+
+```tsx
+<OTPInput
+  maxLength={6}
+  render={({ slots }) => (
+    <View style={{ flexDirection: 'row', gap: 8 }}>
+      {slots.map((slot, index) => (
+        <Pressable key={index} onPress={slot.focus}>
+          <Slot {...slot} />
+        </Pressable>
+      ))}
+    </View>
+  )}
+/>
+```
+
+## OTPInputRef
+
+Use a `ref` to call imperative methods on the input:
+
+```tsx
+const ref = useRef<OTPInputRef>(null);
+<OTPInput ref={ref} ... />
+```
+
+| Method                     | Description                                                                                   |
+| -------------------------- | --------------------------------------------------------------------------------------------- |
+| `focus()`                  | Focus the input                                                                               |
+| `blur()`                   | Blur the input                                                                                |
+| `clear()`                  | Clear all digits                                                                              |
+| `setValue(value: string)`  | Set the current value programmatically                                                        |
+| `focusSlot(index: number)` | Truncate the value to `index` characters and focus — making slot `index` the new active slot |
 
 ## Web support
 

example/src/App.tsx

@@ -16,6 +16,7 @@ import AppleNativewind from './examples/apple-nativewind';
 import DashedNativewind from './examples/dashed-nativewind';
 import AnimatedDashedNativewind from './examples/animated-dashed-nativewind';
 import AnimatedStripeOTPInput from './examples/animated-stripe-nativewind';
+import FocusSlotExample from './examples/focus-slot';
 
 type TabType = 'regular' | 'nativewind';
 
@@ -30,6 +31,13 @@ export default function App() {
       nativewind: StripeNativewind,
       color: '#6772E5',
     },
+    {
+      title: 'Animated Stripe',
+      description: 'Stripe style with slide-in animation',
+      regular: AnimatedStripeOTPInput,
+      nativewind: AnimatedStripeOTPInput,
+      color: '#8B5CF6',
+    },
     {
       title: 'Apple',
       description: 'iOS-style with rounded corners and shadows',
@@ -59,11 +67,11 @@ export default function App() {
       color: '#8B5CF6',
     },
     {
-      title: 'Animated Stripe',
-      description: 'Stripe style with slide-in animation',
-      regular: AnimatedStripeOTPInput,
-      nativewind: AnimatedStripeOTPInput,
-      color: '#8B5CF6',
+      title: 'Focus Slot',
+      description: 'Tap any slot to focus it using slot.focus()',
+      regular: FocusSlotExample,
+      nativewind: FocusSlotExample,
+      color: '#10B981',
     },
   ];
 
@@ -116,14 +124,14 @@ export default function App() {
             className="mx-5 mt-5 bg-white rounded-2xl shadow-sm"
           >
             <View className="flex-row items-center px-4 py-2 border-b border-slate-200">
-              <View
+              {/* <View
                 className="w-10 h-10 rounded-full items-center justify-center mr-3"
                 style={{ backgroundColor: example.color }}
               >
                 <Text className="text-white text-lg font-bold">
                   {example.title[0]}
                 </Text>
-              </View>
+              </View> */}
               <View className="flex-1">
                 <Text className="text-lg font-semibold text-slate-800 mb-1">
                   {example.title}

example/src/examples/animated-dashed-nativewind.tsx

@@ -1,4 +1,4 @@
-import { View, Text, Alert } from 'react-native';
+import { View, Text, Alert, Pressable } from 'react-native';
 import { OTPInput, type SlotProps } from 'input-otp-native';
 import type { OTPInputRef } from 'input-otp-native';
 import { useRef } from 'react';
@@ -39,9 +39,12 @@ export default function AnimatedDashedOTPInput() {
   );
 }
 
-function Slot({ char, isActive, hasFakeCaret }: SlotProps) {
+function Slot({ char, isActive, hasFakeCaret, focus }: SlotProps) {
   return (
-    <View className="w-12 h-12 mx-2 items-center justify-center">
+    <Pressable
+      onPress={focus}
+      className="w-12 h-12 mx-2 items-center justify-center"
+    >
       {char !== null && (
         <Animated.View
           entering={FadeInDown.springify()
@@ -59,7 +62,7 @@ function Slot({ char, isActive, hasFakeCaret }: SlotProps) {
           'bg-gray-900 h-0.5': isActive,
         })}
       />
-    </View>
+    </Pressable>
   );
 }
 

example/src/examples/animated-stripe-nativewind.tsx

@@ -1,4 +1,4 @@
-import { View, Text, Alert } from 'react-native';
+import { View, Text, Alert, Pressable } from 'react-native';
 import { OTPInput, type SlotProps } from 'input-otp-native';
 import type { OTPInputRef } from 'input-otp-native';
 import { useRef } from 'react';
@@ -18,46 +18,46 @@ export default function AnimatedStripeOTPInput() {
   const ref = useRef<OTPInputRef>(null);
   const onComplete = (code: string) => {
     Alert.alert('Completed with code:', code);
-    ref.current?.clear();
+    // ref.current?.clear();
   };
 
   return (
-    <View>
-      <OTPInput
-        ref={ref}
-        onComplete={onComplete}
-        maxLength={6}
-        render={({ slots }) => (
-          <View className="flex-1 flex-row items-center justify-center my-4">
-            <View className="flex-row">
-              {slots.slice(0, 3).map((slot, idx) => (
-                <Slot key={idx} {...slot} index={idx} />
-              ))}
-            </View>
-            <FakeDash />
-            <View className="flex-row">
-              {slots.slice(3).map((slot, idx) => (
-                <Slot key={idx} {...slot} index={idx + 3} />
-              ))}
-            </View>
+    <OTPInput
+      ref={ref}
+      onComplete={onComplete}
+      maxLength={6}
+      render={({ slots }) => (
+        <View className="flex-1 flex-row items-center justify-center my-4">
+          <View className="flex-row">
+            {slots.slice(0, 3).map((slot, idx) => (
+              <Slot key={idx} {...slot} index={idx} />
+            ))}
           </View>
-        )}
-      />
-    </View>
+          <FakeDash />
+          <View className="flex-row">
+            {slots.slice(3).map((slot, idx) => (
+              <Slot key={idx} {...slot} index={idx + 3} />
+            ))}
+          </View>
+        </View>
+      )}
+    />
   );
 }
 
 function Slot({
   char,
   isActive,
   hasFakeCaret,
+  focus,
   index,
 }: SlotProps & { index: number }) {
   const isFirst = index === 0;
   const isLast = index === 2 || index === 5;
 
   return (
-    <View
+    <Pressable
+      onPress={focus}
       className={cn(
         `w-12 h-16 items-center justify-center bg-gray-50 relative`,
         'border border-gray-200',
@@ -80,7 +80,7 @@ function Slot({
         </Animated.View>
       )}
       {hasFakeCaret && <FakeCaret />}
-    </View>
+    </Pressable>
   );
 }
 

example/src/examples/apple-nativewind.tsx

@@ -1,4 +1,4 @@
-import { View, Text, Alert } from 'react-native';
+import { View, Text, Alert, Pressable } from 'react-native';
 import { OTPInput, type SlotProps } from 'input-otp-native';
 import type { OTPInputRef } from 'input-otp-native';
 import { useRef } from 'react';
@@ -36,9 +36,10 @@ export default function AppleOTPInput() {
   );
 }
 
-function Slot({ char, isActive, hasFakeCaret }: SlotProps) {
+function Slot({ char, isActive, hasFakeCaret, focus }: SlotProps) {
   return (
-    <View
+    <Pressable
+      onPress={focus}
       className={cn(
         'w-[50px] h-[50px] items-center justify-center border border-gray-200 rounded-lg bg-white',
         {
@@ -50,7 +51,7 @@ function Slot({ char, isActive, hasFakeCaret }: SlotProps) {
         <Text className="text-2xl font-medium text-gray-900">{char}</Text>
       )}
       {hasFakeCaret && <FakeCaret />}
-    </View>
+    </Pressable>
   );
 }
 

example/src/examples/apple.tsx

@@ -1,4 +1,11 @@
-import { View, Text, StyleSheet, type ViewStyle, Alert } from 'react-native';
+import {
+  View,
+  Text,
+  StyleSheet,
+  type ViewStyle,
+  Alert,
+  Pressable,
+} from 'react-native';
 import { OTPInput, type SlotProps } from 'input-otp-native';
 import type { OTPInputRef } from 'input-otp-native';
 import { useRef } from 'react';
@@ -38,12 +45,15 @@ export default function AppleOTPInput() {
   );
 }
 
-function Slot({ char, isActive, hasFakeCaret }: SlotProps) {
+function Slot({ char, isActive, hasFakeCaret, focus }: SlotProps) {
   return (
-    <View style={[styles.slot, isActive && styles.activeSlot]}>
+    <Pressable
+      onPress={focus}
+      style={[styles.slot, isActive && styles.activeSlot]}
+    >
       {char !== null && <Text style={styles.char}>{char}</Text>}
       {hasFakeCaret && <FakeCaret />}
-    </View>
+    </Pressable>
   );
 }
 

example/src/examples/dashed-nativewind.tsx

@@ -1,4 +1,4 @@
-import { View, Text, Alert } from 'react-native';
+import { View, Text, Alert, Pressable } from 'react-native';
 import { OTPInput, type SlotProps } from 'input-otp-native';
 import type { OTPInputRef } from 'input-otp-native';
 import { useRef } from 'react';
@@ -38,9 +38,12 @@ export default function DashedOTPInput() {
   );
 }
 
-function Slot({ char, isActive, hasFakeCaret }: SlotProps) {
+function Slot({ char, isActive, hasFakeCaret, focus }: SlotProps) {
   return (
-    <View className="w-12 h-12 mx-2 items-center justify-center">
+    <Pressable
+      onPress={focus}
+      className="w-12 h-12 mx-2 items-center justify-center"
+    >
       {char !== null && (
         <Text className="text-3xl font-medium text-gray-900">{char}</Text>
       )}
@@ -50,7 +53,7 @@ function Slot({ char, isActive, hasFakeCaret }: SlotProps) {
           'bg-gray-900 h-0.5': isActive,
         })}
       />
-    </View>
+    </Pressable>
   );
 }
 

example/src/examples/dashed.tsx

@@ -1,4 +1,11 @@
-import { View, Text, StyleSheet, type ViewStyle, Alert } from 'react-native';
+import {
+  View,
+  Text,
+  StyleSheet,
+  type ViewStyle,
+  Alert,
+  Pressable,
+} from 'react-native';
 import { OTPInput, type SlotProps } from 'input-otp-native';
 import type { OTPInputRef } from 'input-otp-native';
 import { useRef } from 'react';
@@ -38,13 +45,13 @@ export default function DashedOTPInput() {
   );
 }
 
-function Slot({ char, isActive, hasFakeCaret }: SlotProps) {
+function Slot({ char, isActive, hasFakeCaret, focus }: SlotProps) {
   return (
-    <View style={styles.slot}>
+    <Pressable onPress={focus} style={styles.slot}>
       {char !== null && <Text style={styles.char}>{char}</Text>}
       {hasFakeCaret && <FakeCaret />}
       <View style={[styles.underline, isActive && styles.activeUnderline]} />
-    </View>
+    </Pressable>
   );
 }