fix(chat): portal through one hydration-safe Portal (CHAT-50) (#97)

* fix(chat): portal through one hydration-safe Portal (CHAT-50)

* chore(changeset): one-line summaries for the portal and nanoid changes

Author: rpvilo

.changeset/drop-nanoid.md

@@ -2,4 +2,4 @@
 "@intentface/chat": patch
 ---
 
-Drop the `nanoid` dependency. The default attachment `convert` now uses the file's blob URL as its id, so `@floating-ui/dom` is the package's only runtime dependency. Ids are still unique per item, including the same file added twice; nothing in the package parses them, and a custom `convert` can still supply its own.
+- Remove the `nanoid` dependency; attachment ids are now the file's blob URL.

.changeset/portal-hydration.md

@@ -0,0 +1,5 @@
+---
+"@intentface/chat": patch
+---
+
+- [Composer] Fix a hydration mismatch when `Composer.Popover` or an overlay `Composer.Panel` is server-rendered.

packages/chat/src/composer/panel.tsx

@@ -21,7 +21,7 @@
 // data-ending-style (+ data-side/data-align when positioned) — animate with CSS or Motion.
 
 import { Children, type ReactNode, type RefObject, useCallback, useRef } from "react";
-import { createPortal } from "react-dom";
+import { Portal } from "../internal/portal";
 import type { PrimitiveProps } from "../internal/primitive-props";
 import {
   type AnchorAlign,
@@ -121,9 +121,5 @@ export const ComposerPanel = ({
     },
   );
 
-  if (positioned) {
-    if (typeof document === "undefined") return null;
-    return createPortal(element, document.body);
-  }
-  return element;
+  return positioned ? <Portal>{element}</Portal> : element;
 };

packages/chat/src/composer/popover.tsx

@@ -12,7 +12,7 @@
 // a flip, and a --anchor-available-height var so the list caps height + scrolls.
 
 import { Children, type ReactNode, useCallback, useRef } from "react";
-import { createPortal } from "react-dom";
+import { Portal } from "../internal/portal";
 import type { PrimitiveProps } from "../internal/primitive-props";
 import { useAnchorPositioning } from "../internal/render/positioning";
 import { useRenderElement } from "../internal/render/useRenderElement";
@@ -88,6 +88,5 @@ export const ComposerPopover = ({
   // Stays mounted (positioning only runs while open, so a closed popover just
   // holds its last position). Open/closed is exposed as data-open/data-closed
   // for the styled layer to animate against — same as the other parts.
-  if (typeof document === "undefined") return null;
-  return createPortal(element, document.body);
+  return <Portal>{element}</Portal>;
 };

packages/chat/src/internal/portal.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import { type ReactNode, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+
+// The one way the package portals. A portal can't be server-rendered — there is
+// no document to portal into — so the first client render must stay empty too,
+// or hydration won't match. useSyncExternalStore renders the server snapshot
+// (false) while hydrating and re-renders with the client one right after; a
+// client-only mount gets true straight away.
+const getSnapshot = () => true;
+const getServerSnapshot = () => false;
+const subscribe = () => () => {};
+const useHydrated = () => useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+export type PortalProps = {
+  children?: ReactNode;
+  container?: Element | null;
+};
+
+export const Portal = ({ children, container }: PortalProps) => {
+  const hydrated = useHydrated();
+  if (!hydrated) return null;
+  return createPortal(children, container ?? document.body);
+};

packages/chat/src/tabs/anchored.tsx

@@ -2,8 +2,8 @@
 
 import type { ReactNode } from "react";
 import { createContext, use, useCallback, useRef, useState } from "react";
-import { createPortal } from "react-dom";
 import { useIsomorphicLayoutEffect } from "../internal/iso-layout-effect";
+import { Portal } from "../internal/portal";
 import type { PrimitiveProps } from "../internal/primitive-props";
 import type { AnchorAlign, AnchorSide } from "../internal/render/positioning";
 import { useAnchorPositioning } from "../internal/render/positioning";
@@ -81,11 +81,6 @@ export const TabsPortal = ({ children, container, keepMounted = false }: TabsPor
   const store = useTabsContextStore();
   const open = useTabsStore(store, selectValue) !== null;
 
-  // There is no document to portal into during a server render, and reaching
-  // for one during the first client render would not match it.
-  const [hydrated, setHydrated] = useState(false);
-  useIsomorphicLayoutEffect(() => setHydrated(true), []);
-
   // Kept mounted through the exit, so the surface can animate away instead of
   // blinking out. Popup reports when that has finished.
   const { mounted, setMounted, transitionStatus } = useTransitionStatus(open);
@@ -96,11 +91,12 @@ export const TabsPortal = ({ children, container, keepMounted = false }: TabsPor
     onExitFinished: () => setMounted(false),
   };
 
-  if (!hydrated || (!mounted && !keepMounted)) return null;
+  if (!mounted && !keepMounted) return null;
 
-  return createPortal(
-    <SurfaceTransitionContext value={transition}>{children}</SurfaceTransitionContext>,
-    container ?? document.body,
+  return (
+    <Portal container={container}>
+      <SurfaceTransitionContext value={transition}>{children}</SurfaceTransitionContext>
+    </Portal>
   );
 };
 

packages/chat/tests/portal-hydration.test.tsx

@@ -0,0 +1,47 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { act } from "react";
+import { hydrateRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { Composer } from "../src/composer";
+
+// Portaled parts must hydrate cleanly: the server can't render a portal, so the
+// first client render must match its empty output, then portal (CHAT-50).
+
+const App = () => (
+  <Composer.Root onSubmit={() => {}}>
+    <Composer.Panel>
+      <p>panel</p>
+    </Composer.Panel>
+    <Composer.Popover>
+      <p>popover</p>
+    </Composer.Popover>
+    <Composer.Container>
+      <Composer.Textarea aria-label="Message" />
+    </Composer.Container>
+  </Composer.Root>
+);
+
+describe("portaled parts", () => {
+  let root: Root | null = null;
+  afterEach(() => {
+    act(() => root?.unmount());
+    root = null;
+    document.body.innerHTML = "";
+  });
+
+  test("server-render nothing, hydrate without a mismatch, then portal into the body", async () => {
+    const container = document.createElement("div");
+    container.innerHTML = renderToString(<App />);
+    document.body.append(container);
+    expect(container.querySelector("[data-composer-panel], [data-composer-popover]")).toBeNull();
+
+    const errors: unknown[] = [];
+    await act(async () => {
+      root = hydrateRoot(container, <App />, { onRecoverableError: (error) => errors.push(error) });
+    });
+
+    expect(errors).toEqual([]);
+    expect(document.querySelector("body > [data-composer-panel]")?.textContent).toBe("panel");
+    expect(document.querySelector("body > [data-composer-popover]")?.textContent).toBe("popover");
+  });
+});