@ecohouse/ui 0.1.61 → 0.1.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecohouse/ui",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "type": "module",
   "private": false,
   "description": "Cross-platform presentation-only UI components for EcoHouse (React Native + React Native Web)",

package/src/components/Checkbox/Checkbox.tsx

@@ -1,5 +1,6 @@
 import { forwardRef, useMemo, useRef, useState, type ComponentRef, type ReactNode } from "react";
 import {
+  Platform,
   Pressable,
   StyleSheet,
   Text,
@@ -13,6 +14,7 @@ import { CheckIcon } from "../../icons";
 import { colors, inputTypography } from "../../theme";
 import { mergeRefs } from "../../utils/mergeRefs";
 import { useApplyWebClassName } from "../../utils/useApplyWebClassName";
+import { handleWebToggleKeyDown, type WebToggleKeyEvent } from "../../utils/webToggleKey";
 
 export type CheckboxVariant = "default" | "light";
 
@@ -97,6 +99,10 @@ export const Checkbox = forwardRef<ComponentRef<typeof Pressable>, CheckboxProps
       accessibilityRole="checkbox"
       accessibilityLabel={resolvedAccessibilityLabel}
       accessibilityState={{ checked: isActive, disabled }}
+      aria-checked={isActive}
+      {...(Platform.OS === "web" && !disabled
+        ? { onKeyDown: (event: WebToggleKeyEvent) => handleWebToggleKeyDown(event, handlePress) }
+        : null)}
       style={[styles.root, disabled && styles.disabled, style]}
     >
       <View

package/src/components/Counter/Counter.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { clampCounterValue, resolveCounterValue, stepCounterValue } from "./Counter.utils";
+
+describe("resolveCounterValue", () => {
+  it("shows a stored value below min instead of hiding it", () => {
+    expect(resolveCounterValue(0, 1, 1, 10)).toBe(0);
+  });
+
+  it("shows a stored value above max instead of hiding it", () => {
+    expect(resolveCounterValue(12, 1, 1, 10)).toBe(12);
+  });
+
+  it("clamps the uncontrolled value", () => {
+    expect(resolveCounterValue(undefined, 0, 1, 10)).toBe(1);
+  });
+
+  it("falls back to min for a non-finite controlled value", () => {
+    expect(resolveCounterValue(Number.NaN, 5, 1, 10)).toBe(1);
+  });
+});
+
+describe("stepCounterValue", () => {
+  it("steps from an out-of-range value into range instead of skipping min", () => {
+    expect(stepCounterValue(0, 1, 1, 10)).toBe(1);
+    expect(stepCounterValue(12, -1, 1, 10)).toBe(10);
+  });
+
+  it("clamps steps to the bounds", () => {
+    expect(stepCounterValue(9, 5, 1, 10)).toBe(10);
+    expect(stepCounterValue(2, -5, 1)).toBe(1);
+  });
+});
+
+describe("clampCounterValue", () => {
+  it("allows an open upper bound", () => {
+    expect(clampCounterValue(1_000, 0)).toBe(1_000);
+  });
+});

package/src/components/Counter/Counter.tsx

@@ -14,6 +14,7 @@ import { MinusIcon, PlusIcon } from "../../icons";
 import { colors, counterTypography } from "../../theme";
 import { mergeRefs } from "../../utils/mergeRefs";
 import { useApplyWebClassName } from "../../utils/useApplyWebClassName";
+import { clampCounterValue, resolveCounterValue, stepCounterValue } from "./Counter.utils";
 
 export interface CounterProps extends Omit<ViewProps, "style" | "children"> {
   value?: number;
@@ -40,10 +41,6 @@ const webBlurStyle: ViewStyle =
       } as ViewStyle)
     : {};
 
-function clamp(value: number, min: number, max?: number) {
-  return Math.max(min, max === undefined ? value : Math.min(value, max));
-}
-
 export const Counter = forwardRef<ComponentRef<typeof View>, CounterProps>(function Counter(
   {
     value,
@@ -64,9 +61,9 @@ export const Counter = forwardRef<ComponentRef<typeof View>, CounterProps>(funct
   const containerRef = useRef<ComponentRef<typeof View>>(null);
   const isControlled = value !== undefined;
   const [uncontrolledValue, setUncontrolledValue] = useState(() =>
-    clamp(defaultValue ?? min, min, max),
+    clampCounterValue(defaultValue ?? min, min, max),
   );
-  const resolvedValue = clamp(isControlled ? value : uncontrolledValue, min, max);
+  const resolvedValue = resolveCounterValue(value, uncontrolledValue, min, max);
   const resolvedClassName = className?.trim() || undefined;
   const setContainerRef = useMemo(() => mergeRefs(containerRef, forwardedRef), [forwardedRef]);
   const decrementDisabled = disabled || resolvedValue <= min;
@@ -74,8 +71,8 @@ export const Counter = forwardRef<ComponentRef<typeof View>, CounterProps>(funct
 
   useApplyWebClassName(containerRef, resolvedClassName);
 
-  const updateValue = (nextValue: number) => {
-    const next = clamp(nextValue, min, max);
+  const updateValue = (delta: number) => {
+    const next = stepCounterValue(resolvedValue, delta, min, max);
     if (next === resolvedValue) return;
     if (!isControlled) setUncontrolledValue(next);
     onValueChange?.(next);
@@ -85,7 +82,7 @@ export const Counter = forwardRef<ComponentRef<typeof View>, CounterProps>(funct
     <Pressable
       disabled={decrementDisabled}
       hitSlop={hitSlop}
-      onPress={() => updateValue(resolvedValue - step)}
+      onPress={() => updateValue(-step)}
       accessibilityRole="button"
       accessibilityLabel="Decrease value"
       accessibilityState={{ disabled: decrementDisabled }}
@@ -98,7 +95,7 @@ export const Counter = forwardRef<ComponentRef<typeof View>, CounterProps>(funct
     <Pressable
       disabled={incrementDisabled}
       hitSlop={hitSlop}
-      onPress={() => updateValue(resolvedValue + step)}
+      onPress={() => updateValue(step)}
       accessibilityRole="button"
       accessibilityLabel="Increase value"
       accessibilityState={{ disabled: incrementDisabled }}

package/src/components/Counter/Counter.utils.ts

@@ -0,0 +1,28 @@
+export function clampCounterValue(value: number, min: number, max?: number): number {
+  return Math.max(min, max === undefined ? value : Math.min(value, max));
+}
+
+/**
+ * Value the counter displays and steps from. A controlled value is shown as-is,
+ * even outside `min`/`max`, so a stored 0 under `min = 1` is not displayed as 1
+ * while the form still holds 0.
+ */
+export function resolveCounterValue(
+  controlledValue: number | undefined,
+  uncontrolledValue: number,
+  min: number,
+  max?: number,
+): number {
+  if (controlledValue !== undefined && Number.isFinite(controlledValue)) return controlledValue;
+  return clampCounterValue(controlledValue === undefined ? uncontrolledValue : min, min, max);
+}
+
+/** Next value after a step, clamped into range: from 0 with `min = 1`, "+" gives 1, not 2. */
+export function stepCounterValue(
+  current: number,
+  delta: number,
+  min: number,
+  max?: number,
+): number {
+  return clampCounterValue(current + delta, min, max);
+}

package/src/components/DatePicker/DatePicker.tsx

@@ -34,6 +34,7 @@ import {
 } from "../../utils/dateUtils";
 import { mergeRefs } from "../../utils/mergeRefs";
 import { useApplyWebClassName } from "../../utils/useApplyWebClassName";
+import { useOverlayLayer } from "../../utils/useOverlayLayer";
 
 /** Monday-first — override via `monthNames` for other locales. */
 const DEFAULT_MONTH_NAMES = [
@@ -365,20 +366,9 @@ export const DatePicker = forwardRef<ComponentRef<typeof View>, DatePickerProps>
       focusTrigger();
     }, [focusTrigger, setOpen]);
 
-    // Escape closes the calendar and returns focus to the trigger (web only).
-    useEffect(() => {
-      if (Platform.OS !== "web" || !isOpen) return;
-
-      const handleKeyDown = (event: KeyboardEvent) => {
-        if (event.key === "Escape") {
-          event.preventDefault();
-          closeAndFocusTrigger();
-        }
-      };
-
-      document.addEventListener("keydown", handleKeyDown);
-      return () => document.removeEventListener("keydown", handleKeyDown);
-    }, [isOpen, closeAndFocusTrigger]);
+    // Escape closes the calendar and returns focus to the trigger (web only). It is
+    // claimed before a surrounding Modal/Drawer can react, so they stay open.
+    useOverlayLayer("popover", isOpen, closeAndFocusTrigger);
 
     const handleTriggerPress = () => {
       if (disabled) return;
@@ -503,6 +493,7 @@ export const DatePicker = forwardRef<ComponentRef<typeof View>, DatePickerProps>
               accessibilityRole="button"
               accessibilityLabel={resolvedAccessibilityLabel}
               accessibilityState={{ disabled, expanded: isOpen }}
+              aria-expanded={isOpen}
               style={[
                 styles.trigger,
                 usesRangeTrigger && styles.rangeTrigger,

package/src/components/Drawer/Drawer.tsx

@@ -26,6 +26,8 @@ import { CloseIcon } from "../../icons";
 import { colors, fonts } from "../../theme";
 import { mergeRefs } from "../../utils/mergeRefs";
 import { useApplyWebClassName } from "../../utils/useApplyWebClassName";
+import { useHydrated } from "../../utils/useHydrated";
+import { useOverlayLayer } from "../../utils/useOverlayLayer";
 
 export interface DrawerProps {
   /** Controls visibility. */
@@ -84,24 +86,25 @@ export const Drawer = forwardRef<ComponentRef<typeof View>, DrawerProps>(functio
   const animatedWidth = useRef(new Animated.Value(open ? width : 0)).current;
   const animatedBackdrop = useRef(new Animated.Value(open ? 1 : 0)).current;
 
-  useApplyWebClassName(panelRef, resolvedClassName, mounted && Platform.OS === "web");
+  // The portal is client-only; render it after hydration so SSR and the first client render match.
+  const hydrated = useHydrated();
+  const webMounted = mounted && hydrated && Platform.OS === "web";
+
+  useApplyWebClassName(panelRef, resolvedClassName, webMounted);
 
   useEffect(() => {
-    if (!mounted || Platform.OS !== "web") return undefined;
+    if (!webMounted) return undefined;
 
     const previousOverflow = document.body.style.overflow;
     document.body.style.overflow = "hidden";
 
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") onClose();
-    };
-    document.addEventListener("keydown", onKeyDown);
-
     return () => {
       document.body.style.overflow = previousOverflow;
-      document.removeEventListener("keydown", onKeyDown);
     };
-  }, [mounted, onClose]);
+  }, [webMounted]);
+
+  // Escape closes only the topmost overlay, never the Drawer behind an open Select/DatePicker.
+  useOverlayLayer("overlay", webMounted && open, onClose);
 
   const targetWidth = Math.min(width, typeof window !== "undefined" ? window.innerWidth : width);
 
@@ -156,7 +159,7 @@ export const Drawer = forwardRef<ComponentRef<typeof View>, DrawerProps>(functio
 
   // Portal exists only after mounted flips. Animate from 0 on the next frame.
   useEffect(() => {
-    if (Platform.OS !== "web" || !mounted || !open) return undefined;
+    if (!webMounted || !open) return undefined;
 
     const shell = shellRef.current;
     if (shell) {
@@ -172,7 +175,7 @@ export const Drawer = forwardRef<ComponentRef<typeof View>, DrawerProps>(functio
     });
 
     return () => cancelAnimationFrame(frame);
-  }, [mounted, open, targetWidth, playWidth]);
+  }, [webMounted, open, targetWidth, playWidth]);
 
   // Native: animate width + backdrop opacity.
   useEffect(() => {
@@ -262,7 +265,7 @@ export const Drawer = forwardRef<ComponentRef<typeof View>, DrawerProps>(functio
   );
 
   if (Platform.OS === "web") {
-    if (!mounted || typeof document === "undefined") return null;
+    if (!webMounted) return null;
 
     return createPortal(
       <div

package/src/components/Modal/Modal.tsx

@@ -11,6 +11,9 @@ import {
 } from "react-native";
 import { mergeRefs } from "../../utils/mergeRefs";
 import { useApplyWebClassName } from "../../utils/useApplyWebClassName";
+import { useHydrated } from "../../utils/useHydrated";
+import { useOverlayLayer } from "../../utils/useOverlayLayer";
+import { useWebFocusTrap } from "../../utils/useWebFocusTrap";
 
 export interface ModalProps {
   /** Controls visibility. */
@@ -59,6 +62,15 @@ const webRootDomStyle = {
   justifyContent: "center",
 } as const;
 
+/** Focus target on open; the content provides its own focus styles. */
+const webDialogDomStyle = {
+  position: "relative",
+  zIndex: 1,
+  maxWidth: "100%",
+  maxHeight: "100%",
+  outline: "none",
+} as const;
+
 export const Modal = forwardRef<ComponentRef<typeof View>, ModalProps>(function Modal(
   {
     open,
@@ -72,27 +84,29 @@ export const Modal = forwardRef<ComponentRef<typeof View>, ModalProps>(function
   forwardedRef,
 ) {
   const contentRef = useRef<ComponentRef<typeof View>>(null);
+  const dialogRef = useRef<HTMLDivElement | null>(null);
   const setContentRef = useMemo(() => mergeRefs(contentRef, forwardedRef), [forwardedRef]);
   const resolvedClassName = className?.trim() || undefined;
+  // The portal is client-only; render it after hydration so SSR and the first client render match.
+  const hydrated = useHydrated();
+  const webOpen = open && hydrated && Platform.OS === "web";
 
-  useApplyWebClassName(contentRef, resolvedClassName, open && Platform.OS === "web");
+  useApplyWebClassName(contentRef, resolvedClassName, webOpen);
 
   useEffect(() => {
-    if (!open || Platform.OS !== "web") return undefined;
+    if (!webOpen) return undefined;
 
     const previousOverflow = document.body.style.overflow;
     document.body.style.overflow = "hidden";
 
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") onClose();
-    };
-    document.addEventListener("keydown", onKeyDown);
-
     return () => {
       document.body.style.overflow = previousOverflow;
-      document.removeEventListener("keydown", onKeyDown);
     };
-  }, [open, onClose]);
+  }, [webOpen]);
+
+  // Escape closes only the topmost overlay, never the Modal behind an open Select/DatePicker.
+  const isTopLayer = useOverlayLayer("overlay", webOpen, onClose);
+  useWebFocusTrap(dialogRef, webOpen, isTopLayer);
 
   const content = (
     <View
@@ -106,7 +120,7 @@ export const Modal = forwardRef<ComponentRef<typeof View>, ModalProps>(function
 
   // Web: portal + real DOM backdrop so `backdrop-filter` blurs the page behind.
   if (Platform.OS === "web") {
-    if (!open || typeof document === "undefined") return null;
+    if (!webOpen) return null;
 
     return createPortal(
       <div style={webRootDomStyle} role="presentation">
@@ -117,7 +131,13 @@ export const Modal = forwardRef<ComponentRef<typeof View>, ModalProps>(function
           onClick={closeOnBackdropPress ? onClose : undefined}
           style={webBackdropDomStyle}
         />
-        <div style={{ position: "relative", zIndex: 1, maxWidth: "100%", maxHeight: "100%" }}>
+        <div
+          ref={dialogRef}
+          // No aria-modal: Select/DatePicker menus are portaled outside and must stay reachable.
+          role="dialog"
+          tabIndex={-1}
+          style={webDialogDomStyle}
+        >
           {content}
         </div>
       </div>,

package/src/components/RadioButton/RadioButton.tsx

@@ -1,5 +1,6 @@
 import { forwardRef, useMemo, useRef, useState, type ComponentRef, type ReactNode } from "react";
 import {
+  Platform,
   Pressable,
   StyleSheet,
   Text,
@@ -12,6 +13,7 @@ import {
 import { colors, fonts } from "../../theme";
 import { mergeRefs } from "../../utils/mergeRefs";
 import { useApplyWebClassName } from "../../utils/useApplyWebClassName";
+import { handleWebToggleKeyDown, type WebToggleKeyEvent } from "../../utils/webToggleKey";
 
 export type RadioButtonVariant = "default";
 
@@ -81,6 +83,18 @@ export const RadioButton = forwardRef<ComponentRef<typeof Pressable>, RadioButto
         accessibilityRole="radio"
         accessibilityLabel={resolvedAccessibilityLabel}
         accessibilityState={{ selected: isActive, disabled }}
+        // ARIA radios expose their state as aria-checked; react-native-web ignores accessibilityState.
+        {...(Platform.OS === "web"
+          ? {
+              "aria-checked": isActive,
+              ...(disabled
+                ? null
+                : {
+                    onKeyDown: (event: WebToggleKeyEvent) =>
+                      handleWebToggleKeyDown(event, handlePress),
+                  }),
+            }
+          : null)}
         style={[styles.root, disabled && styles.disabled, style]}
       >
         <View style={styles.control}>{isActive ? <View style={styles.dot} /> : null}</View>

package/src/components/Select/Select.tsx

@@ -30,6 +30,7 @@ import { colors, selectTypography } from "../../theme";
 import { mergeRefs } from "../../utils/mergeRefs";
 import { renderStatefulIcon, type StatefulIcon } from "../../utils/renderStatefulIcon";
 import { useApplyWebClassName } from "../../utils/useApplyWebClassName";
+import { useOverlayLayer } from "../../utils/useOverlayLayer";
 
 export type SelectOption = {
   label: string;
@@ -111,6 +112,11 @@ type WebMenuPosition = {
 
 type ItemVisualState = "default" | "hover" | "selected";
 
+/** Web-only listbox semantics for the option list (`listbox` is missing from RN's `Role` type). */
+function webListboxProps(multiple: boolean): ViewProps {
+  return { role: "listbox", "aria-multiselectable": multiple } as unknown as ViewProps;
+}
+
 function itemBackground(state: ItemVisualState): string {
   switch (state) {
     case "hover":
@@ -525,8 +531,12 @@ export const Select = forwardRef<ComponentRef<typeof View>, SelectProps>(
       focusTrigger();
     }, [focusTrigger, setOpen]);
 
+    // Escape closes the menu and returns focus to the trigger (web only). It is
+    // claimed before a surrounding Modal/Drawer can react, so they stay open.
+    useOverlayLayer("popover", isOpen, closeAndFocusTrigger);
+
     // ARIA combobox keyboard pattern (web only): Arrow keys move the highlighted
-    // option, Enter/Space selects it, Escape closes and returns focus to the trigger.
+    // option, Enter/Space selects it.
     useEffect(() => {
       if (Platform.OS !== "web") return;
 
@@ -543,12 +553,6 @@ export const Select = forwardRef<ComponentRef<typeof View>, SelectProps>(
           return;
         }
 
-        if (event.key === "Escape") {
-          event.preventDefault();
-          closeAndFocusTrigger();
-          return;
-        }
-
         if (event.key === "ArrowDown" || event.key === "ArrowUp") {
           event.preventDefault();
           setHoveredValue((current) => {
@@ -602,7 +606,6 @@ export const Select = forwardRef<ComponentRef<typeof View>, SelectProps>(
       filteredOptions,
       hoveredValue,
       multiple,
-      closeAndFocusTrigger,
       focusTrigger,
       handleSelect,
       setOpen,
@@ -691,6 +694,7 @@ export const Select = forwardRef<ComponentRef<typeof View>, SelectProps>(
           contentContainerStyle={styles.optionListContent}
           keyboardShouldPersistTaps="handled"
           showsVerticalScrollIndicator={false}
+          {...(Platform.OS === "web" ? webListboxProps(multiple) : null)}
         >
           {loading ? (
             <View style={styles.statusRow}>
@@ -727,6 +731,9 @@ export const Select = forwardRef<ComponentRef<typeof View>, SelectProps>(
                   }
                   accessibilityRole={multiple ? "checkbox" : "button"}
                   accessibilityState={{ selected: isSelected, checked: isSelected, disabled }}
+                  // react-native-web ignores accessibilityState apart from `disabled`.
+                  role={Platform.OS === "web" ? "option" : undefined}
+                  aria-selected={isSelected}
                   style={[
                     styles.item,
                     {
@@ -773,6 +780,7 @@ export const Select = forwardRef<ComponentRef<typeof View>, SelectProps>(
             accessibilityRole="combobox"
             accessibilityLabel={resolvedAccessibilityLabel}
             accessibilityState={{ disabled, expanded: isOpen }}
+            aria-expanded={isOpen}
             style={[
               styles.trigger,
               {

package/src/components/Toggle/Toggle.tsx

@@ -10,6 +10,7 @@ import {
 import {
   Animated,
   Easing,
+  Platform,
   Pressable,
   StyleSheet,
   Text,
@@ -21,6 +22,7 @@ import {
 import { colors, inputTypography } from "../../theme";
 import { mergeRefs } from "../../utils/mergeRefs";
 import { useApplyWebClassName } from "../../utils/useApplyWebClassName";
+import { handleWebToggleKeyDown, type WebToggleKeyEvent } from "../../utils/webToggleKey";
 
 export interface ToggleProps extends Omit<
   PressableProps,
@@ -115,6 +117,10 @@ export const Toggle = forwardRef<ComponentRef<typeof Pressable>, ToggleProps>(fu
       accessibilityRole="switch"
       accessibilityLabel={resolvedAccessibilityLabel}
       accessibilityState={{ checked: isActive, disabled }}
+      aria-checked={isActive}
+      {...(Platform.OS === "web" && !disabled
+        ? { onKeyDown: (event: WebToggleKeyEvent) => handleWebToggleKeyDown(event, handlePress) }
+        : null)}
       style={[styles.pressable, disabled && styles.disabled, style]}
     >
       <Animated.View

package/src/components/VerificationCodeInput/VerificationCodeInput.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { normalizeVerificationCode, updateVerificationCode } from "./VerificationCodeInput.utils";
+import {
+  isVerificationCodeComplete,
+  normalizeVerificationCode,
+  reconcileVerificationCells,
+  toVerificationCells,
+  updateVerificationCells,
+  verificationCellsToCode,
+} from "./VerificationCodeInput.utils";
 
 describe("normalizeVerificationCode", () => {
   it("keeps digits only and respects the configured length", () => {
@@ -11,32 +18,87 @@ describe("normalizeVerificationCode", () => {
   });
 });
 
-describe("updateVerificationCode", () => {
+describe("toVerificationCells", () => {
+  it("lays a code out over a fixed number of cells", () => {
+    expect(toVerificationCells("12", 4)).toEqual(["1", "2", "", ""]);
+  });
+});
+
+describe("updateVerificationCells", () => {
   it("distributes a pasted code from the selected cell", () => {
-    expect(updateVerificationCode("", 0, "12 34-56", 6)).toEqual({
-      code: "123456",
+    expect(updateVerificationCells(toVerificationCells("", 6), 0, "12 34-56", 6)).toEqual({
+      cells: ["1", "2", "3", "4", "5", "6"],
+      nextFocus: 5,
+    });
+  });
+
+  it("lays a whole pasted code out from the start when a later cell has focus", () => {
+    expect(updateVerificationCells(toVerificationCells("", 6), 4, "123456", 6)).toEqual({
+      cells: ["1", "2", "3", "4", "5", "6"],
+      nextFocus: 5,
+    });
+  });
+
+  it("still fills forward when the pasted digits fit from the focused cell", () => {
+    expect(updateVerificationCells(toVerificationCells("12", 6), 2, "3456", 6)).toEqual({
+      cells: ["1", "2", "3", "4", "5", "6"],
       nextFocus: 5,
     });
   });
 
   it("replaces a selected digit without growing the code", () => {
-    expect(updateVerificationCode("123456", 2, "9", 6)).toEqual({
-      code: "129456",
+    expect(updateVerificationCells(toVerificationCells("123456", 6), 2, "9", 6)).toEqual({
+      cells: ["1", "2", "9", "4", "5", "6"],
       nextFocus: 3,
     });
   });
 
-  it("removes a cleared digit", () => {
-    expect(updateVerificationCode("123456", 2, "", 6)).toEqual({
-      code: "12456",
+  it("leaves a gap when a middle cell is cleared instead of shifting later digits", () => {
+    expect(updateVerificationCells(toVerificationCells("129456", 6), 2, "", 6)).toEqual({
+      cells: ["1", "2", "", "4", "5", "6"],
       nextFocus: 2,
     });
   });
 
-  it("ignores non-numeric input", () => {
-    expect(updateVerificationCode("123", 2, "abc", 6)).toEqual({
-      code: "12",
+  it("fills a gap in place", () => {
+    const update = updateVerificationCells(["1", "2", "", "4", "5", "6"], 2, "3", 6);
+    expect(update.cells).toEqual(["1", "2", "3", "4", "5", "6"]);
+    expect(isVerificationCodeComplete(update.cells)).toBe(true);
+  });
+
+  it("treats non-numeric input as clearing the cell", () => {
+    expect(updateVerificationCells(toVerificationCells("123", 6), 2, "abc", 6)).toEqual({
+      cells: ["1", "2", "", "", "", ""],
       nextFocus: 2,
     });
   });
 });
+
+describe("isVerificationCodeComplete", () => {
+  it("requires every cell to hold a digit", () => {
+    expect(isVerificationCodeComplete(["1", "2", "", "4", "5", "6"])).toBe(false);
+    expect(verificationCellsToCode(["1", "2", "", "4", "5", "6"])).toBe("12456");
+  });
+});
+
+describe("reconcileVerificationCells", () => {
+  it("keeps gaps while the parent echoes the reported code back", () => {
+    const cells = ["1", "2", "", "4", "5", "6"];
+    expect(reconcileVerificationCells(cells, "12456", 6)).toEqual(cells);
+  });
+
+  it("lays out a new value set by the parent", () => {
+    expect(reconcileVerificationCells(["1", "2", "", "4", "5", "6"], "", 6)).toEqual([
+      "",
+      "",
+      "",
+      "",
+      "",
+      "",
+    ]);
+  });
+
+  it("re-lays the code out when the length changes", () => {
+    expect(reconcileVerificationCells(["1", "2", "3"], "123", 4)).toEqual(["1", "2", "3", ""]);
+  });
+});