fix: pin code input properly distribute pasted content across digit cells (#749)(#750)

theamiri · AhmedAmineZr · abdelghafour amiri · web-flow · commit d957389f489c · 2026-05-14T11:30:37.000+01:00
* fix(pinCodeInput): properly distribute pasted content across digit cells

* chore(changelog): add demo app changelog entry for pin code paste fix

---------

Co-authored-by: Ahmed Amine Zribi &lt;ahmedamine.zribi@sofrecom.com&gt;
Co-authored-by: abdelghafour amiri &lt;abdelghafour.amiri@sofrecom.com&gt;
diff --git a/app/CHANGELOG.md b/app/CHANGELOG.md
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - [Library] Null check operator used on a null value in all components has isHighContrastEnabled ([#756](https://github.com/Orange-OpenSource/ouds-flutter/issues/756))
 - [DemoApp] Layout Overflow on Demo Screen for component version when system font size is increased for accessibility. ([#748](https://github.com/Orange-OpenSource/ouds-flutter/issues/748))
+- [Library] `Pin code input` Paste of less than 4 characters drops or merges characters ([#749](https://github.com/Orange-OpenSource/ouds-flutter/issues/749))
 
 ## [1.3.0](https://github.com/Orange-OpenSource/ouds-flutter/compare/1.2.0...1.3.0) - 2026-05-08
 ### Added
diff --git a/ouds_core/CHANGELOG.md b/ouds_core/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 ### Fixed
 - [Library] Null check operator used on a null value in all components has isHighContrastEnabled ([#756](https://github.com/Orange-OpenSource/ouds-flutter/issues/756))
+- [Library] `Pin code input` Paste of less than 4 characters drops or merges characters ([#749](https://github.com/Orange-OpenSource/ouds-flutter/issues/749))
 
 ## [1.3.0](https://github.com/Orange-OpenSource/ouds-flutter/compare/1.2.0...1.3.0) - 2026-05-08
 ### Added
diff --git a/ouds_core/lib/components/pin_code_input/digit_input/ouds_digit_input.dart b/ouds_core/lib/components/pin_code_input/digit_input/ouds_digit_input.dart
@@ -108,6 +108,7 @@ class OudsDigitInput extends StatefulWidget {
   final void Function(String, int)? onChanged;
   final OudsPinCodeInputLength length;
   final VoidCallback? onBackspaceOnEmpty;
+  final VoidCallback? onPasteRequested;
 
   OudsDigitInput({
     super.key,
@@ -120,6 +121,7 @@ class OudsDigitInput extends StatefulWidget {
     this.onChanged,
     this.length = OudsPinCodeInputLength.six,
     this.onBackspaceOnEmpty,
+    this.onPasteRequested,
   });
 
   @override
@@ -200,9 +202,42 @@ class _OudsDigitInputState extends State<OudsDigitInput> {
                   keyboardType: widget.digitInputDecoration!.keyboardType == OudsPinCodeInputKeyboardType.numeric
                       ? TextInputType.number
                       : TextInputType.text,
-                  inputFormatters: widget.digitInputDecoration!.keyboardType == OudsPinCodeInputKeyboardType.numeric
-                      ? <TextInputFormatter>[FilteringTextInputFormatter.digitsOnly]
-                      : null,
+                  inputFormatters: <TextInputFormatter>[
+                    // Let a full pasted code arrive intact in one cell so the
+                    // parent's `_distributeCode` can spread it. Without this,
+                    // Flutter's default `maxLength` behaviour would clip.
+                    LengthLimitingTextInputFormatter(widget.length.digits),
+                    if (widget.digitInputDecoration!.keyboardType ==
+                        OudsPinCodeInputKeyboardType.numeric)
+                      FilteringTextInputFormatter.digitsOnly,
+                  ],
+                  // Long-press paste bypasses the TextField entirely: we
+                  // rebuild the platform toolbar but swap the Paste action
+                  // for the parent's clipboard-direct handler.
+                  contextMenuBuilder: widget.onPasteRequested == null
+                      ? null
+                      : (context, editableTextState) {
+                          final items = editableTextState
+                              .contextMenuButtonItems
+                              .map((item) {
+                                if (item.type ==
+                                    ContextMenuButtonType.paste) {
+                                  return ContextMenuButtonItem(
+                                    type: ContextMenuButtonType.paste,
+                                    onPressed: () {
+                                      editableTextState.hideToolbar();
+                                      widget.onPasteRequested!();
+                                    },
+                                  );
+                                }
+                                return item;
+                              })
+                              .toList();
+                          return AdaptiveTextSelectionToolbar.buttonItems(
+                            anchors: editableTextState.contextMenuAnchors,
+                            buttonItems: items,
+                          );
+                        },
                   textAlign: TextAlign.center,
                   maxLines: 1,
                   buildCounter: (_, {required currentLength, required isFocused, required maxLength}) => null, // to hide the counter
diff --git a/ouds_core/lib/components/pin_code_input/ouds_pin_code_input.dart b/ouds_core/lib/components/pin_code_input/ouds_pin_code_input.dart
@@ -14,6 +14,7 @@
 library;
 
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
 import 'package:ouds_core/components/pin_code_input/digit_input/ouds_digit_input.dart';
 import 'package:ouds_core/components/pin_code_input/internal/modifier/ouds_pin_code_input_text_color_modifier.dart';
 import 'package:ouds_core/l10n/gen/ouds_localizations.dart';
@@ -268,6 +269,7 @@ class _OudsPinCodeInputState extends State<OudsPinCodeInput> {
                         }
                       },
                       onBackspaceOnEmpty: () => _handleBackspaceOnEmpty(index),
+                      onPasteRequested: _pasteFromClipboard,
                     ),
                   ),
                 );
@@ -314,39 +316,52 @@ class _OudsPinCodeInputState extends State<OudsPinCodeInput> {
     );
   }
 
-  // This method updates focus between fields, assembles the full PIN code,
-  // and calls the appropriate callbacks:
+  // Handles keyboard-path input from a single cell. Any multi-grapheme value
+  // (soft-keyboard paste suggestion, Cmd+V, OTP autofill) is routed to the
+  // single distribution method `_distributeCode`. Single characters are
+  // written atomically and focus advances or retreats. Long-press paste is
+  // handled entirely outside this method via `_pasteFromClipboard` wired
+  // through each cell's `contextMenuBuilder`.
   void _handleDigitInput(String value, int index) {
     WidgetsBinding.instance.addPostFrameCallback((_) {
       if (!mounted) return;
 
       final totalDigits = widget.length.digits;
-      final controllers = widget.controllers!;
-      var effectiveValue = value;
-      // Case 1: user pasted a code (more than 3 characters)
-      if (value.length > 3) {
-        _handlePaste(value);
+      final controllers = widget.controllers;
+      if (controllers == null) return;
+      if (controllers.length < totalDigits ||
+          _focusNodes.length < totalDigits) {
         return;
       }
 
-      // Case 2: user tried to add another character into a filled field
-      if (value.length == 2) {
-        controllers[index]
-          ..text = value.characters.last
-          ..selection = TextSelection.collapsed(offset: 1);
-        effectiveValue = controllers[index].text;
+      final sanitized = widget.digitInputDecoration.keyboardType ==
+              OudsPinCodeInputKeyboardType.numeric
+          ? value.replaceAll(RegExp(r'\D'), '')
+          : value;
+      final chars = sanitized.characters.toList();
+
+      // Multi-grapheme arrival → treat as paste, redistribute.
+      if (chars.length > 1) {
+        _distributeCode(value);
+        return;
+      }
+
+      final effective = chars.isEmpty ? '' : chars.first;
+      if (controllers[index].text != effective) {
+        controllers[index].value = TextEditingValue(
+          text: effective,
+          selection: TextSelection.collapsed(offset: effective.length),
+        );
       }
 
       final code = _currentCode();
       _emitChanged(code);
 
-      // Case 3: deletion on a filled cell. Move backward so one backspace removes one digit.
-      if (effectiveValue.isEmpty) {
+      if (effective.isEmpty) {
         _requestFocusOnPreviousField(index);
         return;
       }
 
-      // Case 4: normal input  move focus forward
       _requestFocusOnNextFieldOrComplete(
         index: index,
         totalDigits: totalDigits,
@@ -406,31 +421,84 @@ class _OudsPinCodeInputState extends State<OudsPinCodeInput> {
     }
   }
 
-  //handle copy past pin code
-  void _handlePaste(String value) {
+  // ───────────────────────── paste pipeline ─────────────────────────
+  // Three small methods, single responsibility each:
+  //
+  //   _safeReadClipboard  – reads the system clipboard with a hard 2 s
+  //                         timeout; returns null on null/error/timeout.
+  //   _pasteFromClipboard – entrypoint wired to each cell's context-menu
+  //                         "Paste" action; sole long-press paste path.
+  //   _distributeCode     – the ONLY place that writes to the cells. Takes
+  //                         a raw string, sanitises, truncates to PIN
+  //                         length, fills every cell (clearing trailing
+  //                         ones), updates focus, and fires callbacks.
+  //
+  // The keyboard path (`_handleDigitInput`) also delegates to
+  // `_distributeCode` whenever it sees a multi-grapheme value, so all paste
+  // flows converge on one implementation.
+
+  Future<String?> _safeReadClipboard() async {
+    try {
+      final data = await Clipboard.getData(Clipboard.kTextPlain).timeout(
+        const Duration(seconds: 2),
+        onTimeout: () => null,
+      );
+      return data?.text;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  Future<void> _pasteFromClipboard() async {
+    final text = await _safeReadClipboard();
+    if (!mounted) return;
+    if (text == null || text.isEmpty) return;
+    _distributeCode(text);
+  }
+
+  void _distributeCode(String raw) {
     final totalDigits = widget.length.digits;
-    final controllers = widget.controllers!;
-    final sanitized = widget.digitInputDecoration.keyboardType == OudsPinCodeInputKeyboardType.numeric
-        ? value.replaceAll(RegExp(r'\D'), '')
-        : value;
+    final controllers = widget.controllers;
+    if (controllers == null) return;
+    if (controllers.length < totalDigits ||
+        _focusNodes.length < totalDigits) {
+      return;
+    }
+
+    final sanitized = widget.digitInputDecoration.keyboardType ==
+            OudsPinCodeInputKeyboardType.numeric
+        ? raw.replaceAll(RegExp(r'\D'), '')
+        : raw;
+    if (sanitized.isEmpty) return;
+
     final digits = sanitized.characters.take(totalDigits).toList();
+    final filledCount = digits.length;
+
+    // Write every cell — atomic `value =` (sets text + selection in one go)
+    // and explicit empty for cells beyond the pasted range, so a shorter
+    // paste cannot leave stale digits behind.
+    for (int i = 0; i < totalDigits; i++) {
+      final text = i < filledCount ? digits[i] : '';
+      controllers[i].value = TextEditingValue(
+        text: text,
+        selection: TextSelection.collapsed(offset: text.length),
+      );
+    }
 
-    for (int i = 0; i < digits.length; i++) {
-      controllers[i].text = digits[i];
+    if (!_hasEdited) {
+      _hasEdited = true;
     }
 
     final code = _currentCode();
     _emitChanged(code);
 
-    final isComplete = code.length == totalDigits;
-
-    if (isComplete) {
+    if (code.characters.length == totalDigits) {
       for (final node in _focusNodes) {
         node.unfocus();
       }
       widget.onEditingComplete?.call(code);
     } else {
-      final nextIndex = digits.length.clamp(0, totalDigits - 1);
+      final nextIndex = filledCount.clamp(0, totalDigits - 1).toInt();
       _focusNodes[nextIndex].requestFocus();
     }
   }
@@ -476,7 +544,9 @@ class _OudsPinCodeInputState extends State<OudsPinCodeInput> {
     _previousHasFocus = hasAnyFocus;
     final code = _currentCode();
 
-    if (!hasAnyFocus && _hasEdited) {
+    if (!hasAnyFocus &&
+        _hasEdited &&
+        code.characters.length == widget.length.digits) {
       widget.onEditingComplete?.call(code);
     } else if (hasAnyFocus) {
       widget.onChanged?.call(code);
