@ecohouse/ui 0.1.60 → 0.1.62

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>");
+  });
+});

package/src/utils/useHydrated.ts

@@ -0,0 +1,14 @@
+import { useSyncExternalStore } from "react";
+
+const subscribe = () => () => {};
+const getClientSnapshot = () => true;
+const getServerSnapshot = () => false;
+
+/**
+ * `false` during server rendering and hydration, `true` afterwards (and on
+ * client-only mounts). Gate browser-only output such as portals on it so the
+ * first client render matches the server HTML.
+ */
+export function useHydrated(): boolean {
+  return useSyncExternalStore(subscribe, getClientSnapshot, getServerSnapshot);
+}

package/src/utils/useOverlayLayer.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef } from "react";
+import { Platform } from "react-native";
+import { getDocumentOverlayStack, type OverlayLayer, type OverlayLayerKind } from "./overlayStack";
+
+/**
+ * Registers an open overlay on the shared web overlay stack (see
+ * `overlayStack.ts`) so Escape closes only the topmost one. No-op on native.
+ *
+ * The layer is registered once per `active` period; `onEscape` is read from a
+ * ref so a new callback identity does not move the layer to the top again.
+ * Returns `isTopLayer()` for behaviour that only the topmost layer of this kind
+ * should run (e.g. the focus trap of the topmost Modal).
+ */
+export function useOverlayLayer(
+  kind: OverlayLayerKind,
+  active: boolean,
+  onEscape: () => void,
+): () => boolean {
+  const onEscapeRef = useRef(onEscape);
+  onEscapeRef.current = onEscape;
+  const layerRef = useRef<OverlayLayer | null>(null);
+
+  useEffect(() => {
+    if (!active || Platform.OS !== "web" || typeof document === "undefined") return undefined;
+
+    const layer: OverlayLayer = { kind, onEscape: () => onEscapeRef.current() };
+    const stack = getDocumentOverlayStack();
+    const remove = stack.push(layer);
+    layerRef.current = layer;
+
+    return () => {
+      remove();
+      if (layerRef.current === layer) layerRef.current = null;
+    };
+  }, [active, kind]);
+
+  return useCallback(() => {
+    const layer = layerRef.current;
+    return layer !== null && getDocumentOverlayStack().isTop(layer);
+  }, []);
+}

package/src/utils/useWebFocusTrap.ts

@@ -0,0 +1,68 @@
+import { useEffect, type RefObject } from "react";
+import { Platform } from "react-native";
+import { getTabbableElements, getWrappedFocusIndex } from "./focusTrap";
+
+/**
+ * Web dialog focus management: moves focus into `containerRef` when it opens
+ * (unless content already took it, e.g. via `autoFocus`), keeps Tab and
+ * Shift+Tab inside while `isTopLayer()` is true, and returns focus to the
+ * previously focused element on close. The container needs `tabIndex={-1}`.
+ */
+export function useWebFocusTrap(
+  containerRef: RefObject<HTMLElement | null>,
+  active: boolean,
+  isTopLayer: () => boolean,
+): void {
+  useEffect(() => {
+    if (!active || Platform.OS !== "web" || typeof document === "undefined") return undefined;
+    const container = containerRef.current;
+    if (!container) return undefined;
+
+    const previouslyFocused =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    if (!container.contains(document.activeElement)) container.focus({ preventScroll: true });
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Tab" || event.defaultPrevented || !isTopLayer()) return;
+
+      const activeElement = document.activeElement;
+      // Focus inside another portal (e.g. an app popover) is managed there.
+      if (
+        activeElement !== null &&
+        activeElement !== document.body &&
+        !container.contains(activeElement)
+      ) {
+        return;
+      }
+
+      const tabbables = getTabbableElements(container);
+      if (tabbables.length === 0) {
+        event.preventDefault();
+        container.focus({ preventScroll: true });
+        return;
+      }
+
+      const nextIndex = getWrappedFocusIndex(
+        tabbables.length,
+        tabbables.indexOf(activeElement as HTMLElement),
+        event.shiftKey,
+      );
+      if (nextIndex === null) return;
+      event.preventDefault();
+      tabbables[nextIndex].focus();
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+      // Restore focus unless the app already moved it somewhere else on purpose.
+      const current = document.activeElement;
+      if (
+        previouslyFocused?.isConnected &&
+        (current === null || current === document.body || container.contains(current))
+      ) {
+        previouslyFocused.focus({ preventScroll: true });
+      }
+    };
+  }, [active, containerRef, isTopLayer]);
+}

package/src/utils/webToggleKey.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from "vitest";
+import { handleWebToggleKeyDown, type WebToggleKeyEvent } from "./webToggleKey";
+
+const host = {};
+
+function keyEvent(overrides: Partial<WebToggleKeyEvent>): WebToggleKeyEvent {
+  return { key: " ", target: host, currentTarget: host, preventDefault: vi.fn(), ...overrides };
+}
+
+describe("handleWebToggleKeyDown", () => {
+  it("toggles on Space and stops the page from scrolling", () => {
+    const onToggle = vi.fn();
+    const event = keyEvent({});
+
+    expect(handleWebToggleKeyDown(event, onToggle)).toBe(true);
+    expect(onToggle).toHaveBeenCalledTimes(1);
+    expect(event.preventDefault).toHaveBeenCalled();
+  });
+
+  it("supports the legacy Spacebar key name", () => {
+    const onToggle = vi.fn();
+    handleWebToggleKeyDown(keyEvent({ key: "Spacebar" }), onToggle);
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not toggle repeatedly while Space is held down", () => {
+    const onToggle = vi.fn();
+    const event = keyEvent({ repeat: true });
+
+    expect(handleWebToggleKeyDown(event, onToggle)).toBe(true);
+    expect(onToggle).not.toHaveBeenCalled();
+    expect(event.preventDefault).toHaveBeenCalled();
+  });
+
+  it("ignores Space typed into a focusable child", () => {
+    const onToggle = vi.fn();
+    const event = keyEvent({ target: {} });
+
+    expect(handleWebToggleKeyDown(event, onToggle)).toBe(false);
+    expect(onToggle).not.toHaveBeenCalled();
+    expect(event.preventDefault).not.toHaveBeenCalled();
+  });
+
+  it("leaves other keys alone (Enter is already handled by react-native-web)", () => {
+    const onToggle = vi.fn();
+    expect(handleWebToggleKeyDown(keyEvent({ key: "Enter" }), onToggle)).toBe(false);
+    expect(onToggle).not.toHaveBeenCalled();
+  });
+});

package/src/utils/webToggleKey.ts

@@ -0,0 +1,23 @@
+export interface WebToggleKeyEvent {
+  key: string;
+  repeat?: boolean;
+  target?: unknown;
+  currentTarget?: unknown;
+  preventDefault: () => void;
+}
+
+/**
+ * Space activates switches, checkboxes and radios on web. react-native-web only
+ * maps Space to `onPress` for `button` roles, so these controls handle it
+ * themselves. Ignores key repeat and keys from nested focusable children.
+ * Returns whether the event was handled.
+ */
+export function handleWebToggleKeyDown(event: WebToggleKeyEvent, onToggle: () => void): boolean {
+  const isSpace = event.key === " " || event.key === "Spacebar";
+  if (!isSpace || event.target !== event.currentTarget) return false;
+
+  // Stop the page from scrolling even for a held-down key.
+  event.preventDefault();
+  if (!event.repeat) onToggle();
+  return true;
+}