canopy-ui 0.3.0 → 0.6.0

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/presence/PresenceBadge.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { PresenceBadge } from './PresenceBadge'
+import type { Viewer } from './usePresence'
+
+// NOTE ON CONVENTION: canopy-web has no @testing-library/jest-dom and no
+// user-event package. Assertions use toBeTruthy(), interactions use
+// fireEvent, and every DOM test carries the `@vitest-environment jsdom`
+// docblock above — the vitest config sets no global environment. Do not
+// introduce toBeInTheDocument() here; it will not exist.
+
+const viewer = (n: number, over: Partial<Viewer> = {}): Viewer => ({
+  email: `u${n}@x.com`,
+  name: `User ${n}`,
+  subLocation: 'run overview',
+  idle: false,
+  self: false,
+  ...over,
+})
+
+describe('PresenceBadge', () => {
+  afterEach(cleanup)
+
+  it('renders nothing when you are the only viewer', () => {
+    const { container } = render(<PresenceBadge viewers={[viewer(1, { self: true })]} />)
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('renders nothing when the roster is empty', () => {
+    const { container } = render(<PresenceBadge viewers={[]} />)
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('shows at most three avatars and collapses the rest into +N', () => {
+    render(<PresenceBadge viewers={[viewer(1), viewer(2), viewer(3), viewer(4), viewer(5)]} />)
+    expect(screen.getByText('+2')).toBeTruthy()
+  })
+
+  it('labels the control with the viewer count for screen readers', () => {
+    render(<PresenceBadge viewers={[viewer(1), viewer(2)]} />)
+    expect(screen.getByRole('button', { name: /2 people viewing this page/i })).toBeTruthy()
+  })
+
+  it('expands to a named list on click, listing you first and marked', () => {
+    render(<PresenceBadge viewers={[viewer(1), viewer(2, { self: true, name: 'Me' })]} />)
+    fireEvent.click(screen.getByRole('button'))
+    expect(screen.getByText(/Me/)).toBeTruthy()
+    expect(screen.getByText('(you)')).toBeTruthy()
+    expect(screen.getByText('User 1')).toBeTruthy()
+  })
+
+  it('marks idle viewers in the expanded list', () => {
+    render(<PresenceBadge viewers={[viewer(1, { idle: true }), viewer(2)]} />)
+    fireEvent.click(screen.getByRole('button'))
+    expect(screen.getByText('idle')).toBeTruthy()
+  })
+})

package/src/presence/PresenceBadge.tsx

@@ -0,0 +1,105 @@
+import { useEffect, useRef, useState } from 'react'
+import { avatarFor } from './avatar'
+import type { Viewer } from './usePresence'
+
+const MAX_AVATARS = 3
+
+/**
+ * Collapsed viewer cluster that expands into a named list.
+ *
+ * Renders nothing when you are alone — a badge that permanently reads "1"
+ * is noise, and the account menu already tells you who you are.
+ */
+export function PresenceBadge({ viewers }: { viewers: Viewer[] }) {
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!open) return
+    const onDown = (e: MouseEvent) => {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false)
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    document.addEventListener('mousedown', onDown)
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('mousedown', onDown)
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [open])
+
+  if (viewers.length < 2) return null
+
+  // You first, then everyone else in roster order.
+  const ordered = [...viewers].sort((a, b) => Number(b.self) - Number(a.self))
+  const shown = ordered.slice(0, MAX_AVATARS)
+  const overflow = ordered.length - shown.length
+
+  return (
+    <div className="relative" ref={rootRef}>
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        aria-expanded={open}
+        aria-label={`${viewers.length} people viewing this page`}
+        className="flex items-center -space-x-2 rounded-full p-0.5 hover:opacity-90"
+      >
+        {shown.map((v) => {
+          const { initials, colorClass } = avatarFor(v.email, v.name)
+          return (
+            <span
+              key={v.email}
+              className={`inline-flex h-6 w-6 items-center justify-center rounded-full
+                ring-2 ring-card text-[10px] font-semibold text-white ${colorClass}
+                ${v.idle ? 'opacity-45' : ''}`}
+            >
+              {initials}
+            </span>
+          )
+        })}
+        {overflow > 0 && (
+          <span
+            className="inline-flex h-6 w-6 items-center justify-center rounded-full
+              bg-muted ring-2 ring-card text-[10px] font-semibold text-muted-foreground"
+          >
+            +{overflow}
+          </span>
+        )}
+      </button>
+
+      {open && (
+        <div
+          className="absolute right-0 z-50 mt-2 w-64 rounded-md border border-border
+            bg-card p-1 shadow-md"
+        >
+          {ordered.map((v) => {
+            const { initials, colorClass } = avatarFor(v.email, v.name)
+            return (
+              <div key={v.email} className="flex items-center gap-2 rounded px-2 py-1.5">
+                <span
+                  className={`inline-flex h-6 w-6 shrink-0 items-center justify-center
+                    rounded-full text-[10px] font-semibold text-white ${colorClass}
+                    ${v.idle ? 'opacity-45' : ''}`}
+                >
+                  {initials}
+                </span>
+                <span className="min-w-0 flex-1">
+                  <span className="block truncate text-sm text-foreground">
+                    {v.name || v.email}
+                    {v.self && <span className="ml-1 text-muted-foreground">(you)</span>}
+                  </span>
+                  <span className="block truncate text-xs text-muted-foreground">
+                    {v.subLocation}
+                  </span>
+                </span>
+                {v.idle && <span className="text-[10px] text-muted-foreground">idle</span>}
+              </div>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/presence/avatar.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { avatarFor } from './avatar'
+
+describe('avatarFor', () => {
+  it('takes initials from a two-part display name', () => {
+    expect(avatarFor('alice@x.com', 'Alice Chen').initials).toBe('AC')
+  })
+
+  it('falls back to the email local-part when there is no name', () => {
+    expect(avatarFor('bob.ali@x.com', '').initials).toBe('BA')
+  })
+
+  it('produces a single initial for a one-word identity', () => {
+    expect(avatarFor('ace@x.com', 'ACE').initials).toBe('A')
+  })
+
+  it('is deterministic: the same email is always the same color', () => {
+    expect(avatarFor('alice@x.com', 'Alice Chen').colorClass)
+      .toBe(avatarFor('alice@x.com', 'Different Name').colorClass)
+  })
+
+  it('color is a deterministic function of email via djb2', () => {
+    const email = 'alice@example.com'
+    const COLORS = [
+      'bg-sky-600',
+      'bg-emerald-600',
+      'bg-violet-600',
+      'bg-amber-600',
+      'bg-rose-600',
+      'bg-teal-600',
+      'bg-indigo-600',
+      'bg-fuchsia-600',
+    ]
+
+    // Compute expected color using djb2 formula
+    let h = 5381
+    for (let i = 0; i < email.length; i++) h = ((h << 5) + h + email.charCodeAt(i)) | 0
+    const expectedColorClass = COLORS[Math.abs(h) % COLORS.length]
+
+    expect(avatarFor(email, 'Any Name').colorClass).toBe(expectedColorClass)
+  })
+})

package/src/presence/avatar.ts

@@ -0,0 +1,36 @@
+// Fixed palette. Chosen for legibility against white text in both themes;
+// index is picked by a stable hash of the email so a person keeps one color
+// everywhere, in every app, across sessions.
+const COLORS = [
+  'bg-sky-600',
+  'bg-emerald-600',
+  'bg-violet-600',
+  'bg-amber-600',
+  'bg-rose-600',
+  'bg-teal-600',
+  'bg-indigo-600',
+  'bg-fuchsia-600',
+]
+
+function hash(value: string): number {
+  // djb2. Not cryptographic — we only need stable bucketing.
+  let h = 5381
+  for (let i = 0; i < value.length; i++) h = ((h << 5) + h + value.charCodeAt(i)) | 0
+  return Math.abs(h)
+}
+
+/**
+ * Initials + a stable color class for one person.
+ *
+ * Color keys on email rather than display name so changing your name does
+ * not change your color out from under people who have learned it.
+ */
+export function avatarFor(email: string, name: string): { initials: string; colorClass: string } {
+  const source = (name || email.split('@')[0] || '?').trim()
+  const words = source.split(/[\s._-]+/).filter(Boolean)
+  const initials =
+    words.length >= 2
+      ? (words[0][0] + words[1][0]).toUpperCase()
+      : (words[0]?.[0] ?? '?').toUpperCase()
+  return { initials, colorClass: COLORS[hash(email) % COLORS.length] }
+}

package/src/presence/index.ts

@@ -0,0 +1,4 @@
+export { PresenceBadge } from './PresenceBadge'
+export { usePresence, type Viewer, type UsePresenceOptions } from './usePresence'
+export { pageKeyFor, type PageLocation, type RouteRule } from './pageKey'
+export { avatarFor } from './avatar'

package/src/presence/pageKey.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { pageKeyFor, type RouteRule } from './pageKey'
+
+const ACE_RULES: RouteRule[] = [
+  {
+    pattern: /^\/w\/([^/]+)\/opps\/([^/]+)\/runs\/([^/]+)\/steps\/([^/]+)/,
+    build: (m) => ({ workspace: m[1], resource: `opp:${m[2]}/${m[3]}`, subLocation: m[4] }),
+  },
+  {
+    pattern: /^\/w\/([^/]+)\/opps\/([^/]+)\/runs\/([^/]+)/,
+    build: (m) => ({ workspace: m[1], resource: `opp:${m[2]}/${m[3]}`, subLocation: 'run overview' }),
+  },
+  {
+    pattern: /^\/w\/([^/]+)\/activity/,
+    build: (m) => ({ workspace: m[1], resource: 'activity', subLocation: 'Activity' }),
+  },
+]
+
+describe('pageKeyFor', () => {
+  it('collapses every step of a run onto one key, keeping the step as sub-location', () => {
+    const a = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-001/steps/idea-to-pdd', ACE_RULES)
+    const b = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-001', ACE_RULES)
+    expect(a?.pageKey).toBe('ace:dimagi-team:opp:bednet/run-001')
+    expect(b?.pageKey).toBe(a?.pageKey)
+    expect(a?.subLocation).toBe('idea-to-pdd')
+    expect(b?.subLocation).toBe('run overview')
+  })
+
+  it('keeps different runs of the same opp on different keys', () => {
+    const a = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-001', ACE_RULES)
+    const b = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-002', ACE_RULES)
+    expect(a?.pageKey).not.toBe(b?.pageKey)
+  })
+
+  it('namespaces by app so two apps never collide', () => {
+    const ace = pageKeyFor('ace', '/w/dimagi-team/activity', ACE_RULES)
+    const canopy = pageKeyFor('canopy', '/w/dimagi-team/activity', ACE_RULES)
+    expect(ace?.pageKey).toBe('ace:dimagi-team:activity')
+    expect(canopy?.pageKey).toBe('canopy:dimagi-team:activity')
+  })
+
+  it('returns null for unmatched routes rather than a catch-all key', () => {
+    expect(pageKeyFor('ace', '/totally/unknown', ACE_RULES)).toBeNull()
+  })
+
+  it('is order-sensitive: the first matching rule wins', () => {
+    const loose: RouteRule[] = [
+      { pattern: /^\/w\/([^/]+)\/opps/, build: (m) => ({ workspace: m[1], resource: 'opps', subLocation: 'Opps' }) },
+      ...ACE_RULES,
+    ]
+    expect(pageKeyFor('ace', '/w/x/opps/bednet/runs/run-001', loose)?.pageKey).toBe('ace:x:opps')
+  })
+})

package/src/presence/pageKey.ts

@@ -0,0 +1,37 @@
+/** A resolved presence location: which roster to join, and where in it you are. */
+export interface PageLocation {
+  /** `<app>:<workspace|global>:<resource>` — the roster identity. */
+  pageKey: string
+  /** Human-readable position within the resource, for the expanded panel. */
+  subLocation: string
+}
+
+export interface RouteRule {
+  pattern: RegExp
+  build: (m: RegExpMatchArray) => { workspace: string; resource: string; subLocation: string }
+}
+
+/**
+ * Resolve a pathname to a presence location. Pure — the single place
+ * grouping correctness lives.
+ *
+ * Rules are evaluated in order and the first match wins, so more specific
+ * patterns must be listed before looser ones.
+ *
+ * Returns null when nothing matches. Callers render no badge in that case;
+ * grouping every unrecognised route under one catch-all key would put
+ * unrelated strangers in the same roster.
+ */
+export function pageKeyFor(
+  app: string,
+  pathname: string,
+  rules: RouteRule[],
+): PageLocation | null {
+  for (const rule of rules) {
+    const m = pathname.match(rule.pattern)
+    if (!m) continue
+    const { workspace, resource, subLocation } = rule.build(m)
+    return { pageKey: `${app}:${workspace}:${resource}`, subLocation }
+  }
+  return null
+}

package/src/presence/usePresence.test.ts

@@ -0,0 +1,130 @@
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { usePresence } from './usePresence'
+
+class FakeSocket {
+  static last: FakeSocket | null = null
+  static OPEN = 1
+  readyState = 0
+  sent: string[] = []
+  onopen: (() => void) | null = null
+  onmessage: ((e: { data: string }) => void) | null = null
+  onclose: (() => void) | null = null
+  constructor(public url: string) {
+    FakeSocket.last = this
+  }
+  send(frame: string) {
+    this.sent.push(frame)
+  }
+  close() {
+    this.readyState = 3
+  }
+  open() {
+    this.readyState = FakeSocket.OPEN
+    this.onopen?.()
+  }
+  deliver(payload: unknown) {
+    this.onmessage?.({ data: JSON.stringify(payload) })
+  }
+}
+
+beforeEach(() => {
+  vi.stubGlobal('WebSocket', FakeSocket as unknown as typeof WebSocket)
+  vi.useFakeTimers()
+})
+afterEach(() => {
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+  FakeSocket.last = null
+})
+
+const LOC = { pageKey: 'ace:ws:opp:a/run-001', subLocation: 'run overview' }
+
+describe('usePresence', () => {
+  it('sends presence.enter once the socket opens', () => {
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    expect(JSON.parse(FakeSocket.last!.sent[0])).toEqual({
+      type: 'presence.enter',
+      page_key: LOC.pageKey,
+      sub_location: LOC.subLocation,
+    })
+  })
+
+  it('exposes the roster the server broadcasts', () => {
+    const { result } = renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    act(() =>
+      FakeSocket.last!.deliver({
+        event: 'presence.roster',
+        data: {
+          page_key: LOC.pageKey,
+          viewers: [{ email: 'a@x.com', name: 'A', sub_location: 'idea-to-pdd', idle: false, self: true }],
+        },
+      }),
+    )
+    expect(result.current.viewers).toEqual([
+      { email: 'a@x.com', name: 'A', subLocation: 'idea-to-pdd', idle: false, self: true },
+    ])
+  })
+
+  it('ignores a roster for a page key it is no longer on', () => {
+    const { result } = renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    act(() =>
+      FakeSocket.last!.deliver({
+        event: 'presence.roster',
+        data: { page_key: 'ace:ws:opp:STALE/run-999', viewers: [
+          { email: 'z@x.com', name: 'Z', sub_location: '', idle: false, self: false }] },
+      }),
+    )
+    expect(result.current.viewers).toEqual([])
+  })
+
+  it('re-enters without reconnecting when the location changes', () => {
+    const { rerender } = renderHook(
+      ({ location }) => usePresence({ url: 'ws://x/ws/presence/', location }),
+      { initialProps: { location: LOC } },
+    )
+    act(() => FakeSocket.last!.open())
+    const socket = FakeSocket.last!
+    rerender({ location: { pageKey: 'ace:ws:activity', subLocation: 'Activity' } })
+    expect(FakeSocket.last).toBe(socket) // same socket, no reconnect
+    expect(JSON.parse(socket.sent[socket.sent.length - 1])).toEqual({
+      type: 'presence.enter',
+      page_key: 'ace:ws:activity',
+      sub_location: 'Activity',
+    })
+  })
+
+  it('heartbeats every 20 seconds', () => {
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    act(() => void vi.advanceTimersByTime(20_000))
+    expect(JSON.parse(FakeSocket.last!.sent[1])).toEqual({ type: 'presence.heartbeat', idle: false })
+  })
+
+  it('clears the roster and sends nothing when there is no location', () => {
+    const { result } = renderHook(() =>
+      usePresence({ url: 'ws://x/ws/presence/', location: null }),
+    )
+    expect(result.current.viewers).toEqual([])
+    expect(FakeSocket.last).toBeNull()
+  })
+
+  it('swallows a synchronous WebSocket constructor throw and stays on an empty roster', () => {
+    class ThrowingSocket {
+      constructor() {
+        throw new Error('mixed content: refused to connect to insecure WebSocket')
+      }
+    }
+    vi.stubGlobal('WebSocket', ThrowingSocket as unknown as typeof WebSocket)
+
+    let hook!: ReturnType<typeof renderHook<{ viewers: unknown[] }, void>>
+    expect(() => {
+      hook = renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    }).not.toThrow()
+    expect(hook.result.current.viewers).toEqual([])
+  })
+})