@ecohouse/ui 0.1.60 → 0.1.62

package/src/components/VerificationCodeInput/VerificationCodeInput.tsx

@@ -22,7 +22,13 @@ import {
 } from "react-native";
 import { colors, fonts } from "../../theme";
 import { useApplyWebClassName } from "../../utils/useApplyWebClassName";
-import { normalizeVerificationCode, updateVerificationCode } from "./VerificationCodeInput.utils";
+import {
+  isVerificationCodeComplete,
+  reconcileVerificationCells,
+  toVerificationCells,
+  updateVerificationCells,
+  verificationCellsToCode,
+} from "./VerificationCodeInput.utils";
 
 const DEFAULT_LENGTH = 6;
 const DESKTOP_CELL_WIDTH = 54.333335876464844;
@@ -85,17 +91,18 @@ export const VerificationCodeInput = forwardRef<
 ) {
   const safeLength = Math.max(1, Math.floor(length));
   const isControlled = typeof value === "string";
-  const [uncontrolledValue, setUncontrolledValue] = useState(() =>
-    normalizeVerificationCode(defaultValue, safeLength),
-  );
+  // Fixed-length cells, so clearing a middle cell leaves a gap instead of shifting digits.
+  const [cellsState, setCellsState] = useState(() => toVerificationCells(defaultValue, safeLength));
   const [focusedIndex, setFocusedIndex] = useState<number | null>(null);
   const { width: viewportWidth } = useWindowDimensions();
   const rootRef = useRef<ComponentRef<typeof View>>(null);
   const inputRefs = useRef<Array<ComponentRef<typeof TextInput> | null>>([]);
-  const currentCode = normalizeVerificationCode(
-    isControlled ? value : uncontrolledValue,
+  const cells = reconcileVerificationCells(
+    cellsState,
+    isControlled ? value : verificationCellsToCode(cellsState),
     safeLength,
   );
+  const currentCode = verificationCellsToCode(cells);
 
   useApplyWebClassName(rootRef, className);
 
@@ -108,37 +115,35 @@ export const VerificationCodeInput = forwardRef<
   );
 
   const commit = useCallback(
-    (nextValue: string) => {
-      const normalized = normalizeVerificationCode(nextValue, safeLength);
-
-      if (!isControlled) {
-        setUncontrolledValue(normalized);
-      }
+    (nextCells: string[]) => {
+      // Kept in controlled mode too, so gaps survive while the parent echoes the value back.
+      setCellsState(nextCells);
+      const code = verificationCellsToCode(nextCells);
 
-      onValueChange?.(normalized);
+      onValueChange?.(code);
 
-      if (normalized.length === safeLength) {
-        onComplete?.(normalized);
+      if (isVerificationCodeComplete(nextCells)) {
+        onComplete?.(code);
       }
     },
-    [isControlled, onComplete, onValueChange, safeLength],
+    [onComplete, onValueChange],
   );
 
   useImperativeHandle(
     forwardedRef,
     () => ({
       clear: () => {
-        commit("");
+        commit(toVerificationCells("", safeLength));
         focus(0);
       },
       focus,
     }),
-    [commit, focus],
+    [commit, focus, safeLength],
   );
 
   const handleChange = (index: number, input: string) => {
-    const update = updateVerificationCode(currentCode, index, input, safeLength);
-    commit(update.code);
+    const update = updateVerificationCells(cells, index, input, safeLength);
+    commit(update.cells);
     focus(update.nextFocus);
   };
 
@@ -148,9 +153,9 @@ export const VerificationCodeInput = forwardRef<
   ) => {
     const key = event.nativeEvent.key;
 
-    if (key === "Backspace" && !currentCode[index] && index > 0) {
-      const update = updateVerificationCode(currentCode, index - 1, "", safeLength);
-      commit(update.code);
+    if (key === "Backspace" && !cells[index] && index > 0) {
+      const update = updateVerificationCells(cells, index - 1, "", safeLength);
+      commit(update.cells);
       focus(index - 1);
       return;
     }
@@ -223,7 +228,7 @@ export const VerificationCodeInput = forwardRef<
                 Platform.OS === "android" ? styles.cellAndroid : null,
                 inputStyle,
               ]}
-              value={currentCode[index] ?? ""}
+              value={cells[index] ?? ""}
             />
           );
         })}

package/src/components/VerificationCodeInput/VerificationCodeInput.utils.ts

@@ -2,33 +2,73 @@ export function normalizeVerificationCode(value: string, length: number): string
   return value.replace(/\D/g, "").slice(0, Math.max(1, length));
 }
 
-export interface VerificationCodeUpdate {
-  code: string;
+/** Fills cells from the start of `code`; one entry per cell, `""` marks an empty cell. */
+export function toVerificationCells(code: string, length: number): string[] {
+  const safeLength = Math.max(1, length);
+  const digits = normalizeVerificationCode(code, safeLength);
+  return Array.from({ length: safeLength }, (_, index) => digits[index] ?? "");
+}
+
+/** The code reported to consumers: the entered digits in cell order, gaps skipped. */
+export function verificationCellsToCode(cells: readonly string[]): string {
+  return cells.join("");
+}
+
+export function isVerificationCodeComplete(cells: readonly string[]): boolean {
+  return cells.length > 0 && cells.every((cell) => cell !== "");
+}
+
+/**
+ * Keeps the displayed cells, including gaps, while they still produce `code`;
+ * otherwise (a new value from the parent, or a new length) lays `code` out again.
+ */
+export function reconcileVerificationCells(
+  cells: readonly string[],
+  code: string,
+  length: number,
+): string[] {
+  const safeLength = Math.max(1, length);
+  const normalized = normalizeVerificationCode(code, safeLength);
+  if (cells.length === safeLength && verificationCellsToCode(cells) === normalized) {
+    return [...cells];
+  }
+  return toVerificationCells(normalized, safeLength);
+}
+
+export interface VerificationCellsUpdate {
+  cells: string[];
   nextFocus: number;
 }
 
-export function updateVerificationCode(
-  currentCode: string,
+/**
+ * Applies input typed or pasted into cell `index`. Clearing a cell leaves a gap
+ * instead of shifting later digits left; pasted digits fill forward from `index`.
+ */
+export function updateVerificationCells(
+  currentCells: readonly string[],
   index: number,
   input: string,
   length: number,
-): VerificationCodeUpdate {
+): VerificationCellsUpdate {
   const safeLength = Math.max(1, length);
   const safeIndex = Math.min(Math.max(0, index), safeLength - 1);
-  const current = normalizeVerificationCode(currentCode, safeLength);
+  const cells = Array.from({ length: safeLength }, (_, cellIndex) => {
+    const cell = currentCells[cellIndex] ?? "";
+    return /^\d$/.test(cell) ? cell : "";
+  });
   const insertedDigits = normalizeVerificationCode(input, safeLength - safeIndex);
 
   if (!insertedDigits) {
-    return {
-      code: `${current.slice(0, safeIndex)}${current.slice(safeIndex + 1)}`,
-      nextFocus: safeIndex,
-    };
+    cells[safeIndex] = "";
+    return { cells, nextFocus: safeIndex };
   }
 
+  Array.from(insertedDigits).forEach((digit, offset) => {
+    cells[safeIndex + offset] = digit;
+  });
+
   return {
-    code: `${current.slice(0, safeIndex)}${insertedDigits}${current.slice(
-      safeIndex + insertedDigits.length,
-    )}`.slice(0, safeLength),
+    cells,
     nextFocus: Math.min(safeIndex + insertedDigits.length, safeLength - 1),
   };
 }

package/src/icons/PaymentCard/PaymentCardIcon.tsx

@@ -0,0 +1,14 @@
+import Svg, { Path } from "react-native-svg";
+import { colors } from "../../theme";
+import type { IconProps } from "../types";
+import { PAYMENT_CARD_PATH } from "./paymentCardPath";
+
+export function PaymentCardIcon({ size = 16, color = colors.grey100 }: IconProps) {
+  return (
+    <Svg width={size} height={size} viewBox="0 0 16 16" fill="none">
+      <Path d={PAYMENT_CARD_PATH} fill={color} />
+    </Svg>
+  );
+}
+
+export { PAYMENT_CARD_PATH } from "./paymentCardPath";

package/src/icons/PaymentCard/PaymentCardIcon.web.tsx

@@ -0,0 +1,13 @@
+import { colors } from "../../theme";
+import type { IconProps } from "../types";
+import { PAYMENT_CARD_PATH } from "./paymentCardPath";
+
+export function PaymentCardIcon({ size = 16, color = colors.grey100 }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 16 16" fill="none" aria-hidden>
+      <path d={PAYMENT_CARD_PATH} fill={color} />
+    </svg>
+  );
+}
+
+export { PAYMENT_CARD_PATH } from "./paymentCardPath";

package/src/icons/PaymentCard/index.ts

@@ -0,0 +1 @@
+export { PaymentCardIcon, PAYMENT_CARD_PATH } from "./PaymentCardIcon";

package/src/icons/PaymentCard/paymentCardPath.ts

@@ -0,0 +1,3 @@
+/** Filled payment card icon path — 16×16 viewBox. */
+export const PAYMENT_CARD_PATH =
+  "M4.66536 10H6.66536C6.84218 10 7.01174 9.9298 7.13677 9.80478C7.26179 9.67975 7.33203 9.51019 7.33203 9.33337C7.33203 9.15656 7.26179 8.98699 7.13677 8.86197C7.01174 8.73695 6.84218 8.66671 6.66536 8.66671H4.66536C4.48855 8.66671 4.31898 8.73695 4.19396 8.86197C4.06894 8.98699 3.9987 9.15656 3.9987 9.33337C3.9987 9.51019 4.06894 9.67975 4.19396 9.80478C4.31898 9.9298 4.48855 10 4.66536 10ZM12.6654 3.33337H3.33203C2.8016 3.33337 2.29289 3.54409 1.91782 3.91916C1.54274 4.29423 1.33203 4.80294 1.33203 5.33337V11.3334C1.33203 11.8638 1.54274 12.3725 1.91782 12.7476C2.29289 13.1227 2.8016 13.3334 3.33203 13.3334H12.6654C13.1958 13.3334 13.7045 13.1227 14.0796 12.7476C14.4546 12.3725 14.6654 11.8638 14.6654 11.3334V5.33337C14.6654 4.80294 14.4546 4.29423 14.0796 3.91916C13.7045 3.54409 13.1958 3.33337 12.6654 3.33337ZM13.332 11.3334C13.332 11.5102 13.2618 11.6798 13.1368 11.8048C13.0117 11.9298 12.8422 12 12.6654 12H3.33203C3.15522 12 2.98565 11.9298 2.86063 11.8048C2.7356 11.6798 2.66536 11.5102 2.66536 11.3334V7.33337H13.332V11.3334ZM13.332 6.00004H2.66536V5.33337C2.66536 5.15656 2.7356 4.98699 2.86063 4.86197C2.98565 4.73695 3.15522 4.66671 3.33203 4.66671H12.6654C12.8422 4.66671 13.0117 4.73695 13.1368 4.86197C13.2618 4.98699 13.332 5.15656 13.332 5.33337V6.00004Z";

package/src/icons/Receipt/ReceiptIcon.tsx

@@ -0,0 +1,14 @@
+import Svg, { Path } from "react-native-svg";
+import { colors } from "../../theme";
+import type { IconProps } from "../types";
+import { RECEIPT_PATH } from "./receiptPath";
+
+export function ReceiptIcon({ size = 16, color = colors.grey100 }: IconProps) {
+  return (
+    <Svg width={size} height={size} viewBox="0 0 16 16" fill="none">
+      <Path d={RECEIPT_PATH} fill={color} />
+    </Svg>
+  );
+}
+
+export { RECEIPT_PATH } from "./receiptPath";

package/src/icons/Receipt/ReceiptIcon.web.tsx

@@ -0,0 +1,13 @@
+import { colors } from "../../theme";
+import type { IconProps } from "../types";
+import { RECEIPT_PATH } from "./receiptPath";
+
+export function ReceiptIcon({ size = 16, color = colors.grey100 }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 16 16" fill="none" aria-hidden>
+      <path d={RECEIPT_PATH} fill={color} />
+    </svg>
+  );
+}
+
+export { RECEIPT_PATH } from "./receiptPath";

package/src/icons/Receipt/index.ts

@@ -0,0 +1 @@
+export { ReceiptIcon, RECEIPT_PATH } from "./ReceiptIcon";

package/src/icons/Receipt/receiptPath.ts

@@ -0,0 +1,3 @@
+/** Filled receipt icon path — 16×16 viewBox. */
+export const RECEIPT_PATH =
+  "M6.66667 5.33337H10.6667C10.8435 5.33337 11.013 5.26314 11.1381 5.13811C11.2631 5.01309 11.3333 4.84352 11.3333 4.66671C11.3333 4.4899 11.2631 4.32033 11.1381 4.1953C11.013 4.07028 10.8435 4.00004 10.6667 4.00004H6.66667C6.48986 4.00004 6.32029 4.07028 6.19526 4.1953C6.07024 4.32033 6 4.4899 6 4.66671C6 4.84352 6.07024 5.01309 6.19526 5.13811C6.32029 5.26314 6.48986 5.33337 6.66667 5.33337ZM5.33333 8.00004H10.6667C10.8435 8.00004 11.013 7.9298 11.1381 7.80478C11.2631 7.67975 11.3333 7.51019 11.3333 7.33337C11.3333 7.15656 11.2631 6.98699 11.1381 6.86197C11.013 6.73695 10.8435 6.66671 10.6667 6.66671H5.33333C5.15652 6.66671 4.98695 6.73695 4.86193 6.86197C4.7369 6.98699 4.66667 7.15656 4.66667 7.33337C4.66667 7.51019 4.7369 7.67975 4.86193 7.80478C4.98695 7.9298 5.15652 8.00004 5.33333 8.00004ZM5.33333 10.6667H10.6667C10.8435 10.6667 11.013 10.5965 11.1381 10.4714C11.2631 10.3464 11.3333 10.1769 11.3333 10C11.3333 9.82323 11.2631 9.65366 11.1381 9.52864C11.013 9.40361 10.8435 9.33337 10.6667 9.33337H5.33333C5.15652 9.33337 4.98695 9.40361 4.86193 9.52864C4.7369 9.65366 4.66667 9.82323 4.66667 10C4.66667 10.1769 4.7369 10.3464 4.86193 10.4714C4.98695 10.5965 5.15652 10.6667 5.33333 10.6667ZM13.3333 1.33337H2.66667C2.48986 1.33337 2.32029 1.40361 2.19526 1.52864C2.07024 1.65366 2 1.82323 2 2.00004V14C2 14.1238 2.03448 14.2452 2.09957 14.3505C2.16466 14.4558 2.25779 14.541 2.36852 14.5963C2.47926 14.6517 2.60323 14.6751 2.72654 14.664C2.84984 14.6529 2.96762 14.6077 3.06667 14.5334L4.44667 13.5L5.82 14.5334C5.9354 14.6199 6.07575 14.6667 6.22 14.6667C6.36425 14.6667 6.5046 14.6199 6.62 14.5334L8 13.5L9.38 14.5334C9.4954 14.6199 9.63575 14.6667 9.78 14.6667C9.92425 14.6667 10.0646 14.6199 10.18 14.5334L11.5533 13.5L12.9333 14.5334C13.0329 14.6075 13.1511 14.6525 13.2748 14.6631C13.3985 14.6737 13.5226 14.6495 13.6333 14.5934C13.7433 14.538 13.8357 14.4532 13.9005 14.3485C13.9652 14.2438 13.9996 14.1232 14 14V2.00004C14 1.82323 13.9298 1.65366 13.8047 1.52864C13.6797 1.40361 13.5101 1.33337 13.3333 1.33337ZM12.6667 12.6667L11.9533 12.1334C11.8379 12.0468 11.6976 12 11.5533 12C11.4091 12 11.2687 12.0468 11.1533 12.1334L9.78 13.1667L8.4 12.1334C8.2846 12.0468 8.14425 12 8 12C7.85575 12 7.7154 12.0468 7.6 12.1334L6.22 13.1667L4.84667 12.1334C4.73127 12.0468 4.59091 12 4.44667 12C4.30242 12 4.16206 12.0468 4.04667 12.1334L3.33333 12.6667V2.66671H12.6667V12.6667Z";

package/src/icons/index.ts

@@ -102,9 +102,11 @@ export { NotificationQrCodeIcon } from "./NotificationQrCode";
 export { NotificationSuccessIcon } from "./NotificationSuccess";
 export { NotificationWarningIcon } from "./NotificationWarning";
 export { PhoneIcon } from "./Phone";
+export { PaymentCardIcon } from "./PaymentCard";
 export { PlusIcon } from "./Plus";
 export { MinusIcon } from "./Minus";
 export { RefreshIcon } from "./Refresh";
+export { ReceiptIcon } from "./Receipt";
 export { RefundStatusIcon } from "./RefundStatus";
 export { SearchIcon } from "./Search";
 export { SettingsIcon } from "./Settings";

package/src/icons/registry.ts

@@ -90,8 +90,10 @@ import { NotificationQrCodeIcon } from "./NotificationQrCode";
 import { NotificationSuccessIcon } from "./NotificationSuccess";
 import { NotificationWarningIcon } from "./NotificationWarning";
 import { PhoneIcon } from "./Phone";
+import { PaymentCardIcon } from "./PaymentCard";
 import { PlusIcon } from "./Plus";
 import { RefreshIcon } from "./Refresh";
+import { ReceiptIcon } from "./Receipt";
 import { RefundStatusIcon } from "./RefundStatus";
 import { SearchIcon } from "./Search";
 import { SettingsIcon } from "./Settings";
@@ -191,12 +193,14 @@ export const icons = {
   notificationSuccess: NotificationSuccessIcon,
   notificationWarning: NotificationWarningIcon,
   paw: PawIcon,
+  paymentCard: PaymentCardIcon,
   phone: PhoneIcon,
   qrCode: QrCodeIcon,
   quietHours: QuietHoursIcon,
   ratingStar: RatingStarIcon,
   plus: PlusIcon,
   refresh: RefreshIcon,
+  receipt: ReceiptIcon,
   refundStatus: RefundStatusIcon,
   search: SearchIcon,
   saveHeart: SaveHeartIcon,

package/src/index.ts

@@ -225,8 +225,10 @@ export {
   NotificationSuccessIcon,
   NotificationWarningIcon,
   PhoneIcon,
+  PaymentCardIcon,
   PlusIcon,
   RefreshIcon,
+  ReceiptIcon,
   RefundStatusIcon,
   SearchIcon,
   SettingsIcon,
@@ -291,6 +293,11 @@ export {
 } from "./theme";
 export type { GreyStep } from "./theme";
 
-export { abbreviateMonthName, formatDate, formatDateDayShortMonth } from "./utils/dateUtils";
+export {
+  abbreviateMonthName,
+  abbreviateMonthNames,
+  formatDate,
+  formatDateDayShortMonth,
+} from "./utils/dateUtils";
 export { resolvePopoverAlign } from "./utils/popoverAlign";
 export type { PopoverAlign, ResolvePopoverAlignOptions } from "./utils/popoverAlign";

package/src/theme/typography.ts

@@ -47,12 +47,12 @@ export const segmentedToggleTypography = {
   letterSpacing: 0,
 } as const;
 
-/** Language switcher trigger and option labels — SemiBold 14, tracking 3%. */
+/** Language switcher trigger and option labels — SemiBold 14, 18px line-height, tracking 3%. */
 export const languageSwitcherTypography = {
   fontFamily: fonts.sans,
   fontSize: 14,
   fontWeight: "600" as const,
-  lineHeight: 14,
+  lineHeight: 18,
   letterSpacing: 0.42,
 } as const;
 

package/src/utils/dateUtils.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { abbreviateMonthNames, formatDateDayShortMonth } from "./dateUtils";
+
+const ARMENIAN_MONTHS = [
+  "Հունվար",
+  "Փետրվար",
+  "Մարտ",
+  "Ապրիլ",
+  "Մայիս",
+  "Հունիս",
+  "Հուլիս",
+  "Օգոստոս",
+  "Սեպտեմբեր",
+  "Հոկտեմբեր",
+  "Նոյեմբեր",
+  "Դեկտեմբեր",
+];
+
+const ENGLISH_MONTHS = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December",
+];
+
+describe("abbreviateMonthNames", () => {
+  it("gives Armenian January and June distinct abbreviations", () => {
+    const abbreviations = abbreviateMonthNames(ARMENIAN_MONTHS);
+
+    expect(abbreviations[0]).toBe("Հունվ");
+    expect(abbreviations[5]).toBe("Հունի");
+    expect(abbreviations[6]).toBe("Հուլ");
+    expect(new Set(abbreviations).size).toBe(12);
+  });
+
+  it("keeps three letters when they are already unique", () => {
+    expect(abbreviateMonthNames(ENGLISH_MONTHS)).toEqual([
+      "Jan",
+      "Feb",
+      "Mar",
+      "Apr",
+      "May",
+      "Jun",
+      "Jul",
+      "Aug",
+      "Sep",
+      "Oct",
+      "Nov",
+      "Dec",
+    ]);
+  });
+
+  it("stops at the full name when two names are identical", () => {
+    expect(abbreviateMonthNames(["Same", "Same"])).toEqual(["Same", "Same"]);
+  });
+});
+
+describe("formatDateDayShortMonth", () => {
+  it("formats Armenian January and June unambiguously", () => {
+    expect(formatDateDayShortMonth(new Date(2026, 0, 15), ARMENIAN_MONTHS)).toBe("15 Հունվ 2026");
+    expect(formatDateDayShortMonth(new Date(2026, 5, 15), ARMENIAN_MONTHS)).toBe("15 Հունի 2026");
+    expect(formatDateDayShortMonth(new Date(2026, 6, 15), ARMENIAN_MONTHS)).toBe("15 Հուլ 2026");
+  });
+});

package/src/utils/dateUtils.ts

@@ -76,9 +76,37 @@ export function abbreviateMonthName(monthName: string, letterCount = 3): string
   return chars.slice(0, end).join("");
 }
 
-/** "15 Հուլ 2026" — day + abbreviated month + year for range triggers. */
+/**
+ * Abbreviates every month name to at least `letterCount` letters, adding letters
+ * where two months would otherwise share an abbreviation: Armenian
+ * «Հունվար» / «Հունիս» become «Հունվ» / «Հունի» instead of both «Հուն».
+ */
+export function abbreviateMonthNames(monthNames: readonly string[], letterCount = 3): string[] {
+  return monthNames.map((name, index) => {
+    const maxLetters = abbreviatedLetterCount(name);
+    let count = letterCount;
+    while (
+      count < maxLetters &&
+      monthNames.some(
+        (other, otherIndex) =>
+          otherIndex !== index &&
+          abbreviateMonthName(other, count) === abbreviateMonthName(name, count),
+      )
+    ) {
+      count += 1;
+    }
+    return abbreviateMonthName(name, count);
+  });
+}
+
+/** Letter count of `monthName`, counting the Armenian digraph «ու» as one letter. */
+function abbreviatedLetterCount(monthName: string): number {
+  return Array.from(monthName.replace(/ու/g, "u")).length;
+}
+
+/** "15 Հուլ 2026" — day + unambiguous abbreviated month + year for range triggers. */
 export function formatDateDayShortMonth(date: Date, monthNames: string[], letterCount = 3): string {
-  const month = abbreviateMonthName(monthNames[date.getMonth()] ?? "", letterCount);
+  const month = abbreviateMonthNames(monthNames, letterCount)[date.getMonth()] ?? "";
   return `${date.getDate()} ${month} ${date.getFullYear()}`;
 }
 

package/src/utils/focusTrap.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { getWrappedFocusIndex } from "./focusTrap";
+
+describe("getWrappedFocusIndex", () => {
+  it("wraps Tab from the last element to the first", () => {
+    expect(getWrappedFocusIndex(3, 2, false)).toBe(0);
+  });
+
+  it("wraps Shift+Tab from the first element to the last", () => {
+    expect(getWrappedFocusIndex(3, 0, true)).toBe(2);
+  });
+
+  it("leaves Tab between inner elements to the browser", () => {
+    expect(getWrappedFocusIndex(3, 1, false)).toBeNull();
+    expect(getWrappedFocusIndex(3, 1, true)).toBeNull();
+  });
+
+  it("enters from the dialog container itself in either direction", () => {
+    expect(getWrappedFocusIndex(3, -1, false)).toBe(0);
+    expect(getWrappedFocusIndex(3, -1, true)).toBe(2);
+  });
+
+  it("has nothing to move to without focusable content", () => {
+    expect(getWrappedFocusIndex(0, -1, false)).toBeNull();
+  });
+});

package/src/utils/focusTrap.ts

@@ -0,0 +1,39 @@
+const TABBABLE_SELECTOR = [
+  "a[href]",
+  "area[href]",
+  "button",
+  "input:not([type='hidden'])",
+  "select",
+  "textarea",
+  "iframe",
+  "[contenteditable='true']",
+  "[tabindex]",
+].join(",");
+
+/** Focusable elements inside `container` that Tab can reach, in DOM order. */
+export function getTabbableElements(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>(TABBABLE_SELECTOR)).filter(
+    (element) =>
+      element.tabIndex >= 0 &&
+      !element.hasAttribute("disabled") &&
+      element.getAttribute("aria-hidden") !== "true" &&
+      element.getClientRects().length > 0,
+  );
+}
+
+/**
+ * Index to move focus to when Tab would leave the trap, or `null` when the
+ * browser's own Tab order already stays inside. `currentIndex` is `-1` when
+ * focus is on the container itself (or outside it).
+ */
+export function getWrappedFocusIndex(
+  count: number,
+  currentIndex: number,
+  backwards: boolean,
+): number | null {
+  if (count === 0) return null;
+  if (currentIndex === -1) return backwards ? count - 1 : 0;
+  if (backwards && currentIndex === 0) return count - 1;
+  if (!backwards && currentIndex === count - 1) return 0;
+  return null;
+}