@ecohouse/ui 0.1.61 → 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/index.ts

@@ -293,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/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;
+}

package/src/utils/overlayStack.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createOverlayStack,
+  type OverlayEventTarget,
+  type OverlayKeyboardEvent,
+} from "./overlayStack";
+
+type Listener = (event: OverlayKeyboardEvent) => void;
+
+/** Minimal `document` stand-in: capture listeners run before bubble listeners. */
+function createFakeDocument() {
+  const listeners: Array<{ listener: Listener; capture: boolean }> = [];
+
+  const target: OverlayEventTarget = {
+    addEventListener: (_type, listener, capture) => {
+      listeners.push({ listener, capture });
+    },
+    removeEventListener: (_type, listener, capture) => {
+      const index = listeners.findIndex(
+        (entry) => entry.listener === listener && entry.capture === capture,
+      );
+      if (index !== -1) listeners.splice(index, 1);
+    },
+  };
+
+  /**
+   * `appListener` stands for an app's own `document` keydown listener (bubble
+   * phase); `targetListener` for a handler on the focused element, which runs
+   * between the capture and bubble phases.
+   */
+  const pressKey = (key: string, appListener?: Listener, targetListener?: Listener) => {
+    let defaultPrevented = false;
+    let stopped = false;
+    const event: OverlayKeyboardEvent = {
+      key,
+      get defaultPrevented() {
+        return defaultPrevented;
+      },
+      preventDefault: () => {
+        defaultPrevented = true;
+      },
+      stopImmediatePropagation: () => {
+        stopped = true;
+      },
+    };
+    const ordered = [
+      ...listeners.filter((entry) => entry.capture).map((entry) => entry.listener),
+      ...(targetListener ? [targetListener] : []),
+      ...listeners.filter((entry) => !entry.capture).map((entry) => entry.listener),
+      ...(appListener ? [appListener] : []),
+    ];
+    for (const listener of ordered) {
+      if (stopped) break;
+      listener(event);
+    }
+    return event;
+  };
+
+  return { target, pressKey, listenerCount: () => listeners.length };
+}
+
+describe("createOverlayStack", () => {
+  it("closes a popover without closing the modal behind it", () => {
+    const fakeDocument = createFakeDocument();
+    const stack = createOverlayStack(fakeDocument.target);
+    const closeModal = vi.fn();
+    const closeSelect = vi.fn();
+    const appListener = vi.fn();
+
+    stack.push({ kind: "overlay", onEscape: closeModal });
+    stack.push({ kind: "popover", onEscape: closeSelect });
+
+    const event = fakeDocument.pressKey("Escape", appListener);
+
+    expect(closeSelect).toHaveBeenCalledTimes(1);
+    expect(closeModal).not.toHaveBeenCalled();
+    // An app's own dialog listening on `document` does not see the event either.
+    expect(appListener).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("closes a popover first even when it registered before its overlay", () => {
+    // React runs a child's effects before its parent's: a Select that is open on
+    // mount inside a Modal registers before the Modal does.
+    const fakeDocument = createFakeDocument();
+    const stack = createOverlayStack(fakeDocument.target);
+    const closeModal = vi.fn();
+    const closeSelect = vi.fn();
+    const select = { kind: "popover" as const, onEscape: closeSelect };
+    const modal = { kind: "overlay" as const, onEscape: closeModal };
+
+    stack.push(select);
+    stack.push(modal);
+    fakeDocument.pressKey("Escape");
+
+    expect(closeSelect).toHaveBeenCalledTimes(1);
+    expect(closeModal).not.toHaveBeenCalled();
+    expect(stack.isTop(select)).toBe(true);
+    expect(stack.isTop(modal)).toBe(true);
+  });
+
+  it("closes the overlay once the popover above it is gone", () => {
+    const fakeDocument = createFakeDocument();
+    const stack = createOverlayStack(fakeDocument.target);
+    const closeModal = vi.fn();
+    const closeSelect = vi.fn();
+
+    stack.push({ kind: "overlay", onEscape: closeModal });
+    const removeSelect = stack.push({ kind: "popover", onEscape: closeSelect });
+    removeSelect();
+
+    fakeDocument.pressKey("Escape");
+
+    expect(closeSelect).not.toHaveBeenCalled();
+    expect(closeModal).toHaveBeenCalledTimes(1);
+  });
+
+  it("closes only the topmost of two stacked overlays", () => {
+    const fakeDocument = createFakeDocument();
+    const stack = createOverlayStack(fakeDocument.target);
+    const closeDrawer = vi.fn();
+    const closeModal = vi.fn();
+
+    stack.push({ kind: "overlay", onEscape: closeDrawer });
+    const modal = { kind: "overlay" as const, onEscape: closeModal };
+    stack.push(modal);
+
+    fakeDocument.pressKey("Escape");
+
+    expect(closeModal).toHaveBeenCalledTimes(1);
+    expect(closeDrawer).not.toHaveBeenCalled();
+    expect(stack.isTop(modal)).toBe(true);
+  });
+
+  it("leaves an overlay open when content inside it already handled Escape", () => {
+    const fakeDocument = createFakeDocument();
+    const stack = createOverlayStack(fakeDocument.target);
+    const closeModal = vi.fn();
+    stack.push({ kind: "overlay", onEscape: closeModal });
+
+    fakeDocument.pressKey("Escape", undefined, (event) => event.preventDefault());
+
+    expect(closeModal).not.toHaveBeenCalled();
+  });
+
+  it("ignores other keys", () => {
+    const fakeDocument = createFakeDocument();
+    const stack = createOverlayStack(fakeDocument.target);
+    const closeSelect = vi.fn();
+    const appListener = vi.fn();
+    stack.push({ kind: "popover", onEscape: closeSelect });
+
+    const event = fakeDocument.pressKey("Enter", appListener);
+
+    expect(closeSelect).not.toHaveBeenCalled();
+    expect(appListener).toHaveBeenCalledTimes(1);
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("only listens on the document while a layer is open", () => {
+    const fakeDocument = createFakeDocument();
+    const stack = createOverlayStack(fakeDocument.target);
+
+    const removeFirst = stack.push({ kind: "overlay", onEscape: vi.fn() });
+    const removeSecond = stack.push({ kind: "popover", onEscape: vi.fn() });
+    expect(fakeDocument.listenerCount()).toBe(2);
+
+    removeFirst();
+    removeFirst();
+    expect(fakeDocument.listenerCount()).toBe(2);
+
+    removeSecond();
+    expect(fakeDocument.listenerCount()).toBe(0);
+  });
+});

package/src/utils/overlayStack.ts

@@ -0,0 +1,105 @@
+/**
+ * Escape handling for stacked web overlays. One Escape closes one layer: an
+ * open popover first, otherwise the most recently opened overlay. So closing a
+ * Select inside a Modal leaves the Modal open, and a Modal opened over a
+ * Drawer closes before the Drawer.
+ *
+ * - `popover` layers (Select, DatePicker menus) claim Escape in the capture
+ *   phase and stop it, so neither our overlays nor an app's own `document`
+ *   listeners close the dialog behind the popover. Popovers always win over
+ *   overlays: React registers a child popover that is open on mount before
+ *   its parent Modal, so push order alone is not reliable between the kinds.
+ * - `overlay` layers (Modal, Drawer) react once the event bubbled to
+ *   `document`, and skip events already handled (`defaultPrevented`), so
+ *   content inside them can keep them open by calling `preventDefault()`.
+ */
+
+export type OverlayLayerKind = "overlay" | "popover";
+
+export interface OverlayLayer {
+  readonly kind: OverlayLayerKind;
+  onEscape: () => void;
+}
+
+export interface OverlayKeyboardEvent {
+  readonly key: string;
+  readonly defaultPrevented: boolean;
+  preventDefault: () => void;
+  stopImmediatePropagation: () => void;
+}
+
+export interface OverlayEventTarget {
+  addEventListener: (
+    type: "keydown",
+    listener: (event: OverlayKeyboardEvent) => void,
+    capture: boolean,
+  ) => void;
+  removeEventListener: (
+    type: "keydown",
+    listener: (event: OverlayKeyboardEvent) => void,
+    capture: boolean,
+  ) => void;
+}
+
+export interface OverlayStack {
+  /** Adds `layer` on top; returns a function that removes it again. */
+  push: (layer: OverlayLayer) => () => void;
+  /** Whether `layer` is the most recently opened layer of its kind. */
+  isTop: (layer: OverlayLayer) => boolean;
+}
+
+export function createOverlayStack(target: OverlayEventTarget): OverlayStack {
+  const layers: OverlayLayer[] = [];
+  const top = (kind: OverlayLayerKind) => {
+    for (let index = layers.length - 1; index >= 0; index -= 1) {
+      if (layers[index].kind === kind) return layers[index];
+    }
+    return undefined;
+  };
+
+  const handleCapture = (event: OverlayKeyboardEvent) => {
+    const layer = top("popover");
+    if (event.key !== "Escape" || event.defaultPrevented || !layer) return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    layer.onEscape();
+  };
+
+  const handleBubble = (event: OverlayKeyboardEvent) => {
+    const layer = top("overlay");
+    if (event.key !== "Escape" || event.defaultPrevented || !layer) return;
+    event.preventDefault();
+    layer.onEscape();
+  };
+
+  return {
+    push(layer) {
+      layers.push(layer);
+      if (layers.length === 1) {
+        target.addEventListener("keydown", handleCapture, true);
+        target.addEventListener("keydown", handleBubble, false);
+      }
+
+      return () => {
+        const index = layers.indexOf(layer);
+        if (index === -1) return;
+        layers.splice(index, 1);
+        if (layers.length === 0) {
+          target.removeEventListener("keydown", handleCapture, true);
+          target.removeEventListener("keydown", handleBubble, false);
+        }
+      };
+    },
+    isTop: (layer) => top(layer.kind) === layer,
+  };
+}
+
+let documentStack: OverlayStack | null = null;
+
+/** The shared stack bound to `document`; web only. */
+export function getDocumentOverlayStack(): OverlayStack {
+  if (!documentStack) {
+    documentStack = createOverlayStack(document as unknown as OverlayEventTarget);
+  }
+  return documentStack;
+}

package/src/utils/useHydrated.test.ts

@@ -0,0 +1,14 @@
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { useHydrated } from "./useHydrated";
+
+function Probe() {
+  return createElement("span", null, useHydrated() ? "client" : "server");
+}
+
+describe("useHydrated", () => {
+  it("is false while rendering on the server, so portals are left out of the SSR HTML", () => {
+    expect(renderToString(createElement(Probe))).toBe("<span>server</span>");
+  });
+});