@ecohouse/ui 0.1.61 → 0.1.63

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