@polderlabs/bizar 7.0.4 → 8.1.0

package/bizar-dash/src/web/v8/data/useFetch.ts

@@ -0,0 +1,62 @@
+/**
+ * v8/data/useFetch.ts — React-side `useFetch<T>(url)` hook.
+ *
+ * Returns `{ data, error, loading, refetch }`. Calls `fetchJson` with
+ * an AbortController that's tied to the component lifecycle so an
+ * unmount mid-request doesn't trigger a state update.
+ *
+ * Re-fetches when `url` changes (deep-equal via JSON.stringify — fine
+ * for the small REST surfaces the dashboard uses).
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { fetchJson, FetchError } from './fetcher.js';
+
+export interface UseFetchState<T> {
+  data: T | null;
+  error: Error | null;
+  loading: boolean;
+  refetch: () => void;
+}
+
+export function useFetch<T>(url: string | null): UseFetchState<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [loading, setLoading] = useState<boolean>(Boolean(url));
+  const [tick, setTick] = useState(0);
+  const urlRef = useRef<string | null>(url);
+  urlRef.current = url;
+
+  useEffect(() => {
+    if (!url) {
+      setData(null);
+      setError(null);
+      setLoading(false);
+      return;
+    }
+    const ctrl = new AbortController();
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    fetchJson<T>(url, { signal: ctrl.signal })
+      .then((res) => {
+        if (cancelled) return;
+        setData(res);
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        if (err && typeof err === 'object' && 'name' in err && err.name === 'AbortError') return;
+        setError(err instanceof Error ? err : new FetchError(0, String(err), null));
+        setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+      ctrl.abort();
+    };
+  }, [url, tick]);
+
+  const refetch = useCallback(() => { setTick((n) => n + 1); }, []);
+
+  return { data, error, loading, refetch };
+}

package/bizar-dash/src/web/v8/data/useWebSocket.ts

@@ -0,0 +1,153 @@
+/**
+ * v8/data/useWebSocket.ts — singleton WS client for the v8 dashboard.
+ *
+ * The dashboard server exposes `/ws` (one WebSocket per browser tab).
+ * We open the socket exactly once per page-load and fan-out messages
+ * to every subscriber via a tiny event-bus.
+ *
+ * Why a module-singleton instead of a per-component socket? The
+ * dashboard has at least 7 views that all want live updates — opening
+ * one socket per view would multiply the server's fan-out cost.
+ */
+
+import { useEffect } from 'react';
+import type { WsMessage } from './types.js';
+
+type Listener = (msg: WsMessage) => void;
+
+interface SocketState {
+  socket: WebSocket | null;
+  listeners: Set<Listener>;
+  retries: number;
+  retryTimer: ReturnType<typeof setTimeout> | null;
+  connectedListeners: Set<(connected: boolean) => void>;
+}
+
+const state: SocketState = {
+  socket: null,
+  listeners: new Set(),
+  retries: 0,
+  retryTimer: null,
+  connectedListeners: new Set(),
+};
+
+function url(): string {
+  if (typeof window === 'undefined') return '';
+  const proto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${proto}//${window.location.host}/ws`;
+}
+
+function notifyConnected(connected: boolean): void {
+  for (const fn of state.connectedListeners) {
+    try { fn(connected); } catch { /* swallow */ }
+  }
+}
+
+function connect(): void {
+  if (typeof window === 'undefined') return;
+  if (state.socket && (state.socket.readyState === WebSocket.OPEN || state.socket.readyState === WebSocket.CONNECTING)) return;
+  let sock: WebSocket;
+  try {
+    sock = new WebSocket(url());
+  } catch {
+    scheduleReconnect();
+    return;
+  }
+  state.socket = sock;
+  sock.addEventListener('open', () => {
+    state.retries = 0;
+    notifyConnected(true);
+  });
+  sock.addEventListener('message', (ev) => {
+    let msg: WsMessage;
+    try { msg = JSON.parse(typeof ev.data === 'string' ? ev.data : ''); }
+    catch { return; }
+    for (const fn of state.listeners) {
+      try { fn(msg); } catch { /* swallow listener errors */ }
+    }
+  });
+  sock.addEventListener('close', () => {
+    state.socket = null;
+    notifyConnected(false);
+    scheduleReconnect();
+  });
+  sock.addEventListener('error', () => {
+    // close handler will run after this.
+  });
+}
+
+function scheduleReconnect(): void {
+  if (state.retryTimer) return;
+  const delay = Math.min(30_000, 500 * Math.pow(2, state.retries++));
+  state.retryTimer = setTimeout(() => {
+    state.retryTimer = null;
+    connect();
+  }, delay);
+}
+
+/** Force a reconnect (useful for the topbar "Reconnect" button). */
+export function reconnect(): void {
+  if (state.socket) {
+    try { state.socket.close(); } catch { /* */ }
+    state.socket = null;
+  }
+  state.retries = 0;
+  connect();
+}
+
+/**
+ * Subscribe to every WS message. The listener is called once per
+ * matching message. Cleanup happens on unmount.
+ */
+export function useWsMessages(cb: (msg: WsMessage) => void): void {
+  useEffect(() => {
+    state.listeners.add(cb);
+    if (!state.socket) connect();
+    return () => {
+      state.listeners.delete(cb);
+    };
+  }, [cb]);
+}
+
+/**
+ * Subscribe only to messages whose `type` matches `predicate`. Convenience
+ * over `useWsMessages` for the common case of "just give me X events".
+ */
+export function useWsMessage(
+  predicate: string | string[],
+  cb: (msg: WsMessage) => void,
+): void {
+  const set = Array.isArray(predicate) ? new Set(predicate) : new Set([predicate]);
+  useWsMessages((msg) => {
+    if (typeof msg === 'object' && msg && 'type' in msg && set.has((msg as { type: string }).type)) {
+      cb(msg);
+    }
+  });
+}
+
+/** Track WS connection status (for the topbar live indicator). */
+export function useWsConnected(cb: (connected: boolean) => void): void {
+  useEffect(() => {
+    state.connectedListeners.add(cb);
+    // Seed with current state.
+    cb(state.socket?.readyState === WebSocket.OPEN);
+    return () => {
+      state.connectedListeners.delete(cb);
+    };
+  }, [cb]);
+}
+
+/** Test seam — reset module state. Not exported from the barrel. */
+export function _resetForTests(): void {
+  if (state.socket) {
+    try { state.socket.close(); } catch { /* */ }
+  }
+  state.socket = null;
+  state.listeners.clear();
+  state.connectedListeners.clear();
+  if (state.retryTimer) {
+    clearTimeout(state.retryTimer);
+    state.retryTimer = null;
+  }
+  state.retries = 0;
+}

package/bizar-dash/src/web/v8/main.tsx

@@ -0,0 +1,28 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ThemeProvider } from './ui/theme/ThemeProvider.js';
+import { DensityProvider } from './ui/theme/DensityProvider.js';
+import { App } from './App.js';
+import './ui/styles/globals.css';
+
+/**
+ * v8 entry — mounts the React 18 root with the theme + density providers
+ * wrapping the App. The root element id is `root`; the v7 dashboard mounts
+ * on `root` as well, so the v8 entry is wired from a separate route via
+ * the dashboard server (see PLAN.md §4 for the v8 → v7 migration plan).
+ */
+const container = document.getElementById('root');
+if (container === null) {
+  throw new Error('v8 mount target #root not found in DOM.');
+}
+
+const root = createRoot(container);
+root.render(
+  <StrictMode>
+    <ThemeProvider>
+      <DensityProvider>
+        <App />
+      </DensityProvider>
+    </ThemeProvider>
+  </StrictMode>,
+);

package/bizar-dash/src/web/v8/shell/AppShell.tsx

@@ -0,0 +1,90 @@
+import { forwardRef, type ReactNode } from 'react';
+import { Box } from '../ui/primitives/Box.js';
+import { Topbar } from './Topbar.js';
+import { Sidebar } from './Sidebar.js';
+
+/**
+ * AppShell — the v8 layout skeleton.
+ *
+ *       ┌──────────────────────────────────────────────────┐
+ *       │  Topbar (56px, sticky)                           │
+ *       ├────────────┬─────────────────────────────────────┤
+ *       │  Sidebar   │  SidebarInset (main content)         │
+ *       │  260px     │                                     │
+ *       │            │                                     │
+ *       │            │                                     │
+ *       └────────────┴─────────────────────────────────────┘
+ *
+ * The SidebarInset caps at max-width 1440px (DESIGN.md §7) and centers
+ * itself, with 24px gutters on either side at >=1440px viewports.
+ *
+ * The ref forwarded from `App.tsx` lands on the `<main>` element so the
+ * caller can re-focus it when the route changes (and announce the new
+ * route to screen readers). `tabIndex={-1}` makes `<main>` focusable
+ * without putting it in the keyboard tab order.
+ */
+
+export interface AppShellProps {
+  topbar?: ReactNode;
+  sidebar?: ReactNode;
+  children?: ReactNode;
+}
+
+export const AppShell = forwardRef<HTMLElement, AppShellProps>(function AppShell(
+  { topbar, sidebar, children },
+  ref,
+) {
+  return (
+    <Box
+      className="v8-app-shell"
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        height: '100vh',
+        background: 'var(--bg)',
+        color: 'var(--fg)',
+      }}
+    >
+      {topbar ?? <Topbar />}
+
+      <Box
+        className="v8-app-shell-body"
+        style={{
+          display: 'flex',
+          flex: 1,
+          minHeight: 0, // critical: lets the body actually scroll instead of expanding
+        }}
+      >
+        {sidebar ?? <Sidebar />}
+
+        <Box
+          as="main"
+          ref={ref}
+          id="main"
+          tabIndex={-1}
+          className="v8-sidebar-inset"
+          role="main"
+          style={{
+            flex: 1,
+            minWidth: 0,
+            overflow: 'auto',
+            background: 'var(--bg)',
+            outline: 'none', // visible focus ring handled by :focus-visible
+          }}
+        >
+          <Box
+            className="v8-sidebar-inset-inner"
+            style={{
+              maxWidth: 1440,
+              margin: '0 auto',
+              padding: 'var(--space-6) var(--space-6)',
+              width: '100%',
+            }}
+          >
+            {children}
+          </Box>
+        </Box>
+      </Box>
+    </Box>
+  );
+});

package/bizar-dash/src/web/v8/shell/PageSkeleton.tsx

@@ -0,0 +1,29 @@
+import { Box } from '../ui/primitives/Box.js';
+import { Skeleton } from '../ui/feedback/Skeleton.js';
+import { Stack } from '../ui/primitives/Stack.js';
+
+/**
+ * PageSkeleton — a non-blocking fallback for the lazy Router Suspense
+ * boundary. Renders five skeleton rows that approximate the visual
+ * weight of a typical view header + the first body row.
+ */
+export function PageSkeleton(): JSX.Element {
+  return (
+    <Box
+      role="status"
+      aria-busy="true"
+      aria-live="polite"
+      style={{ padding: 'var(--space-5) var(--space-6)' }}
+    >
+      <Stack gap={5}>
+        <Skeleton height={32} width="40%" />
+        <Skeleton height={16} width="65%" />
+        <Stack gap={2}>
+          <Skeleton height={14} width="100%" />
+          <Skeleton height={14} width="92%" />
+          <Skeleton height={14} width="78%" />
+        </Stack>
+      </Stack>
+    </Box>
+  );
+}