canopy-ui 0.2.0 → 0.4.0

package/src/chat/useSessionSocket.ts

@@ -0,0 +1,269 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { Message, SessionState, WsEvent } from "./protocol";
+import { prependHistory } from "./history";
+import { sessionReducer } from "./sessionReducer";
+
+const HEARTBEAT_INTERVAL_MS = 20_000;
+const RECONNECT_DELAYS_MS = [1_000, 2_000, 5_000, 10_000];
+const DRAFT_UPDATE_DEBOUNCE_MS = 150;
+
+const INITIAL_STATE: SessionState = {
+  messages: [],
+  active_draft: null,
+  participants: [],
+  presence_user_ids: [],
+  current_user_id: 0,
+};
+
+export interface UseSessionSocketOptions {
+  /** The chat session id (UUID string). */
+  sessionId: string;
+  /**
+   * App-injected WebSocket URL builder. The kit never imports app routing/base
+   * helpers; the container passes one (e.g. canopy's `wsUrl`). Called with the
+   * relative path `ws/canopy-sessions/${sessionId}/`.
+   */
+  wsUrl: (path: string) => string;
+  /**
+   * Optional side-effect callback fired when the server broadcasts a
+   * `session.title_updated` (replaces ace's `notifySessionsUpdated`). The kit
+   * has no opinion on what to do with it.
+   */
+  onTitleUpdated?: () => void;
+}
+
+export interface UseSessionSocketResult {
+  state: SessionState;
+  connected: boolean;
+  sendChat: () => void;
+  stopChat: (messageId: string) => void;
+  updateDraft: (body: string) => void;
+  takeOverDraft: () => void;
+  discardDraft: () => void;
+  prependMessages: (older: Message[]) => void;
+  lastError: string | null;
+}
+
+export function useSessionSocket({
+  sessionId,
+  wsUrl,
+  onTitleUpdated,
+}: UseSessionSocketOptions): UseSessionSocketResult {
+  const [state, setState] = useState<SessionState>(INITIAL_STATE);
+  const [connected, setConnected] = useState(false);
+  const [lastError, setLastError] = useState<string | null>(null);
+
+  const socketRef = useRef<WebSocket | null>(null);
+  const stateRef = useRef<SessionState>(INITIAL_STATE);
+  const reconnectAttemptRef = useRef(0);
+  const heartbeatTimerRef = useRef<number | null>(null);
+  const draftDebounceRef = useRef<number | null>(null);
+  const pendingDraftBodyRef = useRef<string | null>(null);
+  const closedByUserRef = useRef(false);
+  const onTitleUpdatedRef = useRef(onTitleUpdated);
+  // Control frames that must not be lost across a reconnect (currently
+  // only chat.stop). The WS-world analogue of an abortable chat transport.
+  const pendingFramesRef = useRef<{ action: string; data: unknown }[]>([]);
+
+  useEffect(() => {
+    stateRef.current = state;
+  }, [state]);
+
+  useEffect(() => {
+    onTitleUpdatedRef.current = onTitleUpdated;
+  }, [onTitleUpdated]);
+
+  const send = useCallback((frame: { action: string; data: unknown }) => {
+    const ws = socketRef.current;
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(frame));
+      return;
+    }
+    // Queue chat.stop so a stop clicked while the socket is reconnecting
+    // is delivered on next OPEN instead of silently dropped. Draft updates
+    // are intentionally NOT queued — they have a version guard and the
+    // user's next keystroke will refresh the body anyway.
+    if (frame.action === "chat.stop") {
+      pendingFramesRef.current.push(frame);
+    }
+  }, []);
+
+  const applyEvent = useCallback((frame: WsEvent) => {
+    // Side-effect events: handle BEFORE setState so React strict-mode's
+    // double-invocation of the updater doesn't double-fire the effect.
+    if (frame.event === "session.title_updated") {
+      onTitleUpdatedRef.current?.();
+      return;
+    }
+    if (frame.event === "session.error") {
+      setLastError(frame.data.message);
+      if (
+        frame.data.code === "draft_version_mismatch" &&
+        frame.data.detail &&
+        typeof frame.data.detail === "object"
+      ) {
+        // Clear any pending optimistic body so the user's stale local
+        // text doesn't auto-re-send with the new version.
+        pendingDraftBodyRef.current = null;
+        if (draftDebounceRef.current != null) {
+          window.clearTimeout(draftDebounceRef.current);
+          draftDebounceRef.current = null;
+        }
+      }
+    }
+    setState((prev) => sessionReducer(prev, frame));
+  }, []);
+
+  const connect = useCallback(() => {
+    if (closedByUserRef.current) return;
+    const ws = new WebSocket(wsUrl(`ws/canopy-sessions/${sessionId}/`));
+    socketRef.current = ws;
+
+    ws.onopen = () => {
+      setConnected(true);
+      reconnectAttemptRef.current = 0;
+      // Flush any control frames that were queued while the socket was
+      // closed. See `send` above.
+      const queued = pendingFramesRef.current;
+      pendingFramesRef.current = [];
+      for (const frame of queued) {
+        ws.send(JSON.stringify(frame));
+      }
+      if (heartbeatTimerRef.current != null) {
+        window.clearInterval(heartbeatTimerRef.current);
+      }
+      heartbeatTimerRef.current = window.setInterval(() => {
+        send({ action: "presence.heartbeat", data: {} });
+      }, HEARTBEAT_INTERVAL_MS);
+    };
+
+    ws.onmessage = (e) => {
+      try {
+        const frame = JSON.parse(e.data) as WsEvent;
+        applyEvent(frame);
+      } catch {
+        // ignore malformed frames
+      }
+    };
+
+    ws.onclose = () => {
+      setConnected(false);
+      if (heartbeatTimerRef.current != null) {
+        window.clearInterval(heartbeatTimerRef.current);
+        heartbeatTimerRef.current = null;
+      }
+      if (closedByUserRef.current) return;
+      const attempt = reconnectAttemptRef.current;
+      const delay =
+        RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
+      reconnectAttemptRef.current = attempt + 1;
+      window.setTimeout(connect, delay);
+    };
+
+    ws.onerror = () => {
+      // onclose will fire next; nothing to do here.
+    };
+  }, [applyEvent, send, sessionId, wsUrl]);
+
+  useEffect(() => {
+    closedByUserRef.current = false;
+    reconnectAttemptRef.current = 0;
+    connect();
+    return () => {
+      closedByUserRef.current = true;
+      if (heartbeatTimerRef.current != null) {
+        window.clearInterval(heartbeatTimerRef.current);
+      }
+      if (socketRef.current) {
+        socketRef.current.close();
+        socketRef.current = null;
+      }
+    };
+  }, [connect]);
+
+  const sendChat = useCallback(() => {
+    // Flush any pending debounced update first so the committed draft
+    // carries the latest local body.
+    if (draftDebounceRef.current != null) {
+      window.clearTimeout(draftDebounceRef.current);
+      draftDebounceRef.current = null;
+      if (pendingDraftBodyRef.current != null && stateRef.current.active_draft) {
+        send({
+          action: "draft.update",
+          data: {
+            version: stateRef.current.active_draft.version,
+            body: pendingDraftBodyRef.current,
+          },
+        });
+      }
+    }
+    pendingDraftBodyRef.current = null;
+    send({ action: "chat.send", data: {} });
+  }, [send]);
+
+  const stopChat = useCallback(
+    (messageId: string) => {
+      send({ action: "chat.stop", data: { message_id: messageId } });
+    },
+    [send],
+  );
+
+  const updateDraft = useCallback(
+    (body: string) => {
+      // Optimistic local update so the textarea feels snappy.
+      setState((prev) =>
+        prev.active_draft
+          ? { ...prev, active_draft: { ...prev.active_draft, body } }
+          : prev,
+      );
+      pendingDraftBodyRef.current = body;
+      if (draftDebounceRef.current != null) {
+        window.clearTimeout(draftDebounceRef.current);
+      }
+      draftDebounceRef.current = window.setTimeout(() => {
+        draftDebounceRef.current = null;
+        const current = stateRef.current.active_draft;
+        const pending = pendingDraftBodyRef.current;
+        pendingDraftBodyRef.current = null;
+        if (current != null && pending != null) {
+          send({
+            action: "draft.update",
+            data: { version: current.version, body: pending },
+          });
+        }
+      }, DRAFT_UPDATE_DEBOUNCE_MS);
+    },
+    [send],
+  );
+
+  const takeOverDraft = useCallback(() => {
+    send({ action: "draft.take_over", data: {} });
+  }, [send]);
+
+  const discardDraft = useCallback(() => {
+    send({ action: "draft.discard", data: {} });
+  }, [send]);
+
+  const prependMessages = useCallback((older: Message[]) => {
+    // Apply a REST "Load earlier" page into the live socket state. A later
+    // session.state snapshot (e.g. reconnect) resets to the tail — acceptable;
+    // the user re-loads earlier if needed.
+    setState((prev) => {
+      const merged = prependHistory(prev.messages, older);
+      return merged === prev.messages ? prev : { ...prev, messages: merged };
+    });
+  }, []);
+
+  return {
+    state,
+    connected,
+    sendChat,
+    stopChat,
+    updateDraft,
+    takeOverDraft,
+    discardDraft,
+    prependMessages,
+    lastError,
+  };
+}

package/src/chat/useStickyBottom.ts

@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useRef, type RefObject } from "react";
+
+/**
+ * Sticky-bottom auto-scroll for a streaming message list.
+ *
+ * Behaviour:
+ *  - When the user is at (or within `thresholdPx` of) the bottom of the
+ *    scroll container, growth of `dep` (e.g. messages array, streaming
+ *    text length) snaps the view to the new bottom.
+ *  - When the user has scrolled up to read history, growth does NOT
+ *    yank them back. Auto-follow resumes once they scroll back near
+ *    the bottom themselves.
+ *
+ * The "near bottom" predicate is updated in two places:
+ *  - on the user's `scroll` event (so manual scroll-up disables follow)
+ *  - immediately after an auto-scroll write (so we stay sticky even
+ *    though the scroll event for our own write would temporarily make
+ *    `scrollHeight - scrollTop - clientHeight` larger by a few pixels)
+ *
+ * Use "instant" scroll behavior for streaming chunks — smooth scroll
+ * cannot keep up with high-frequency updates and the view drifts.
+ *
+ * Returns:
+ *  - `containerRef`: attach to the scrollable element.
+ *  - `onScroll`: attach to `onScroll` on the same element.
+ *  - `scrollToBottom`: force a snap (e.g. on send).
+ */
+export function useStickyBottom<T>(
+  dep: T,
+  options: { thresholdPx?: number; enabled?: boolean } = {},
+): {
+  containerRef: RefObject<HTMLDivElement | null>;
+  onScroll: () => void;
+  scrollToBottom: () => void;
+} {
+  const { thresholdPx = 100, enabled = true } = options;
+  const containerRef = useRef<HTMLDivElement>(null);
+  // Default true: when the container first mounts there's no history
+  // to read, so the user is "at the bottom" by definition.
+  const wasNearBottomRef = useRef(true);
+
+  const isNearBottom = useCallback(
+    (el: HTMLElement): boolean =>
+      el.scrollHeight - el.scrollTop - el.clientHeight < thresholdPx,
+    [thresholdPx],
+  );
+
+  const onScroll = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    wasNearBottomRef.current = isNearBottom(el);
+  }, [isNearBottom]);
+
+  const scrollToBottom = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+    wasNearBottomRef.current = true;
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const el = containerRef.current;
+    if (!el) return;
+    if (wasNearBottomRef.current) {
+      // "instant" by direct scrollTop write — smooth scroll falls
+      // behind during streaming and the view drifts.
+      el.scrollTop = el.scrollHeight;
+    }
+    // dep is intentionally the only signal that triggers a follow;
+    // it should change whenever the message list grows (length or
+    // the last message's content length).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dep, enabled]);
+
+  return { containerRef, onScroll, scrollToBottom };
+}

package/src/ui/AutoResizeTextarea.tsx

@@ -0,0 +1,61 @@
+import * as React from "react";
+import { cn } from "../lib/cn";
+
+/**
+ * Textarea that auto-sizes to fit its content ONCE — when the content first
+ * loads — then behaves as a normal drag-resizable textarea.
+ *
+ * So the editor opens with every box sized to show all its text (no internal
+ * scrollbars), and after that the user owns each box's size by dragging the
+ * `resize-y` handle. Typing after the initial fit does NOT re-grow/shrink the
+ * box (it scrolls like a normal textarea) — per the desired behavior:
+ * auto-size on open, manual thereafter.
+ *
+ * The fit runs once, keyed on the arrival of content (the value is empty on the
+ * first paint while the template loads, then populated). It re-fits on remount,
+ * so keying the editor by template id sizes a freshly-opened template's boxes.
+ * Tailwind sets `box-sizing: border-box`, so `scrollHeight` includes padding.
+ */
+export const AutoResizeTextarea = React.forwardRef<
+  HTMLTextAreaElement,
+  React.ComponentPropsWithoutRef<"textarea">
+>(({ className, rows = 2, ...props }, forwardedRef) => {
+  const innerRef = React.useRef<HTMLTextAreaElement | null>(null);
+  const fitted = React.useRef(false);
+
+  // Merge forwardedRef + innerRef so callers can still access the element.
+  const ref = React.useCallback(
+    (el: HTMLTextAreaElement | null) => {
+      innerRef.current = el;
+      if (typeof forwardedRef === "function") {
+        forwardedRef(el);
+      } else if (forwardedRef) {
+        (forwardedRef as React.MutableRefObject<HTMLTextAreaElement | null>).current = el;
+      }
+    },
+    [forwardedRef],
+  );
+
+  // Fit exactly once, when content first arrives. `height: auto` collapses the
+  // box so scrollHeight reflects content, then we pin that height. After this
+  // the box is purely manual (resize-y); we never auto-resize again.
+  React.useLayoutEffect(() => {
+    const el = innerRef.current;
+    if (!el || fitted.current) return;
+    if (!el.value) return; // wait until the loaded content populates the value
+    el.style.height = "auto";
+    el.style.height = `${el.scrollHeight}px`;
+    fitted.current = true;
+  }, [props.value]);
+
+  return (
+    <textarea
+      ref={ref}
+      rows={rows}
+      className={cn("resize-y", className?.replace(/\bresize-none\b/g, ""))}
+      {...props}
+    />
+  );
+});
+
+AutoResizeTextarea.displayName = "AutoResizeTextarea";

package/src/ui/dialog.tsx

@@ -0,0 +1,131 @@
+import * as React from "react"
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog"
+import { X } from "lucide-react"
+
+import { cn } from "../lib/cn"
+
+const Dialog = DialogPrimitive.Root
+
+const DialogTrigger = DialogPrimitive.Trigger
+
+const DialogClose = DialogPrimitive.Close
+
+const DialogPortal = ({ children }: { children: React.ReactNode }) => (
+  <DialogPrimitive.Portal>{children}</DialogPrimitive.Portal>
+)
+
+function DialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Backdrop>) {
+  return (
+    <DialogPrimitive.Backdrop
+      data-slot="dialog-overlay"
+      className={cn(
+        "fixed inset-0 z-50 bg-black/80 transition-all data-[ending-style]:opacity-0 data-[starting-style]:opacity-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Popup>) {
+  return (
+    <DialogPrimitive.Portal>
+      <DialogOverlay />
+      <DialogPrimitive.Popup
+        data-slot="dialog-content"
+        className={cn(
+          "fixed top-[50%] left-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border bg-background p-6 shadow-lg transition-all data-[ending-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:scale-95 data-[starting-style]:opacity-0",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <DialogPrimitive.Close className="absolute top-4 right-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:outline-none disabled:pointer-events-none">
+          <X className="h-4 w-4" />
+          <span className="sr-only">Close</span>
+        </DialogPrimitive.Close>
+      </DialogPrimitive.Popup>
+    </DialogPrimitive.Portal>
+  )
+}
+
+function DialogHeader({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn(
+        "flex flex-col gap-1.5 text-center sm:text-left",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogFooter({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        "flex flex-col-reverse sm:flex-row sm:justify-end sm:gap-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Title>) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn(
+        "text-lg font-semibold leading-none tracking-tight",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Description>) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Dialog,
+  DialogPortal,
+  DialogOverlay,
+  DialogTrigger,
+  DialogClose,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+}