basalt-ui 1.41.0 → 2.0.0

package/src/provider/connectivity-provider.tsx

@@ -1,189 +0,0 @@
-/**
- * ConnectivityProvider — aggregates browser online/offline, React Query onlineManager, SSE
- * EventSource, and health-check pings into a single ConnectivityStatus with per-signal detail.
- *
- * Auto-mounted by BasaltProvider with zero consumer setup for basic browser detection.
- * React Query, SSE, and health ping are automatically detected or opt-in via props.
- */
-import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import type { ReactNode } from 'react'
-import { onlineManager } from '@tanstack/react-query'
-import type { ConnectivitySnapshot, ConnectivityProviderProps } from './connectivity-types'
-
-// ── SSR-safe default ────────────────────────────────────────────────────────────────────────────────
-
-const SSR_SNAPSHOT: ConnectivitySnapshot = {
-  status: 'online',
-  details: {
-    browserOnline: true,
-    // Optimistic `true`, matching `browserOnline` — `onlineManager` is a module singleton so it is
-    // always readable, this is the same pre-hydration default as every other signal, never the
-    // "not mounted" case (see `ConnectivitySnapshot['details']['queryOnline']`'s JSDoc).
-    queryOnline: true,
-    sseOpen: null,
-    healthPassing: null,
-  },
-}
-
-// ── Context ─────────────────────────────────────────────────────────────────────────────────────────
-
-export const ConnectivityContext = createContext<ConnectivitySnapshot | null>(null)
-
-// ── Aggregation helper ──────────────────────────────────────────────────────────────────────────────
-
-function computeStatus(details: ConnectivitySnapshot['details']): ConnectivitySnapshot['status'] {
-  if (!details.browserOnline) return 'offline'
-  // Any non-null signal that is explicitly false → degraded
-  if (details.queryOnline === false) return 'degraded'
-  if (details.sseOpen === false) return 'degraded'
-  if (details.healthPassing === false) return 'degraded'
-  return 'online'
-}
-
-// ── Snapshot helpers ────────────────────────────────────────────────────────────────────────────────
-
-function getBrowserOnline(): boolean {
-  return typeof navigator !== 'undefined' ? navigator.onLine : true
-}
-
-function getQueryOnline(): boolean {
-  return onlineManager.isOnline()
-}
-
-// ── Provider ────────────────────────────────────────────────────────────────────────────────────────
-
-export function ConnectivityProvider({
-  children,
-  sseUrl,
-  healthUrl,
-  healthIntervalMs = 30_000,
-  override,
-}: ConnectivityProviderProps & { children: ReactNode }) {
-  // SSR guard — return the optimistic snapshot before hydration
-  const [isClient, setIsClient] = useState(false)
-  useEffect(() => {
-    setIsClient(true)
-  }, [])
-
-  // ── Browser online/offline ────────────────────────────────────────────────────────────────────────
-
-  const [browserOnline, setBrowserOnline] = useState(getBrowserOnline)
-
-  useEffect(() => {
-    if (typeof window === 'undefined') return
-
-    const handleOnline = (): void => setBrowserOnline(true)
-    const handleOffline = (): void => setBrowserOnline(false)
-
-    window.addEventListener('online', handleOnline)
-    window.addEventListener('offline', handleOffline)
-
-    return () => {
-      window.removeEventListener('online', handleOnline)
-      window.removeEventListener('offline', handleOffline)
-    }
-  }, [])
-
-  // ── React Query onlineManager ─────────────────────────────────────────────────────────────────────
-
-  const [queryOnline, setQueryOnline] = useState<boolean>(getQueryOnline)
-
-  useEffect(() => {
-    const unsubscribe = onlineManager.subscribe(() => {
-      setQueryOnline(onlineManager.isOnline())
-    })
-    return unsubscribe
-  }, [])
-
-  // ── SSE ───────────────────────────────────────────────────────────────────────────────────────────
-
-  const [sseOpen, setSseOpen] = useState<boolean | null>(null)
-  const sseRef = useRef<EventSource | null>(null)
-
-  useEffect(() => {
-    if (!sseUrl || typeof window === 'undefined') {
-      setSseOpen(null)
-      return
-    }
-
-    setSseOpen(false) // connecting
-
-    const es = new EventSource(sseUrl)
-    sseRef.current = es
-
-    const handleOpen = (): void => setSseOpen(true)
-    const handleError = (): void => {
-      // readyState: 0=CONNECTING, 1=OPEN, 2=CLOSED
-      setSseOpen(es.readyState === EventSource.OPEN)
-    }
-
-    es.addEventListener('open', handleOpen)
-    es.addEventListener('error', handleError)
-
-    return () => {
-      es.removeEventListener('open', handleOpen)
-      es.removeEventListener('error', handleError)
-      es.close()
-      sseRef.current = null
-    }
-  }, [sseUrl])
-
-  // ── Health ping ───────────────────────────────────────────────────────────────────────────────────
-
-  const [healthPassing, setHealthPassing] = useState<boolean | null>(null)
-  const healthRef = useRef<ReturnType<typeof setInterval> | null>(null)
-
-  const pingHealth = useCallback(async () => {
-    if (!healthUrl) return
-    try {
-      const res = await fetch(healthUrl)
-      setHealthPassing(res.ok)
-    } catch {
-      setHealthPassing(false)
-    }
-  }, [healthUrl])
-
-  useEffect(() => {
-    if (!healthUrl || typeof window === 'undefined') {
-      setHealthPassing(null)
-      return
-    }
-
-    // Initial ping
-    pingHealth()
-
-    // Periodic pings
-    healthRef.current = setInterval(pingHealth, healthIntervalMs)
-
-    return () => {
-      if (healthRef.current !== null) {
-        clearInterval(healthRef.current)
-        healthRef.current = null
-      }
-    }
-  }, [healthUrl, healthIntervalMs, pingHealth])
-
-  // ── Aggregated snapshot ───────────────────────────────────────────────────────────────────────────
-
-  const snapshot: ConnectivitySnapshot = useMemo(() => {
-    const details = {
-      browserOnline: override?.browserOnline ?? browserOnline,
-      queryOnline: override?.queryOnline !== undefined ? override.queryOnline : queryOnline,
-      sseOpen: override?.sseOpen !== undefined ? override.sseOpen : sseOpen,
-      healthPassing: override?.healthPassing !== undefined ? override.healthPassing : healthPassing,
-    }
-    return {
-      status: computeStatus(details),
-      details,
-    }
-  }, [browserOnline, queryOnline, sseOpen, healthPassing, override])
-
-  // SSR → optimistic snapshot
-  if (!isClient) {
-    return (
-      <ConnectivityContext.Provider value={SSR_SNAPSHOT}>{children}</ConnectivityContext.Provider>
-    )
-  }
-
-  return <ConnectivityContext.Provider value={snapshot}>{children}</ConnectivityContext.Provider>
-}

package/src/provider/connectivity-types.ts

@@ -1,42 +0,0 @@
-/**
- * Connectivity types — aggregated online/offline/degraded status with per-signal detail.
- *
- * The ConnectivityProvider aggregates browser navigator.onLine, React Query's onlineManager,
- * an optional SSE EventSource, and an optional health-check endpoint into a single status.
- * Signals that are null (not configured/available) are treated as passing.
- */
-
-export type ConnectivityStatus = 'online' | 'offline' | 'degraded'
-
-export type ConnectivitySnapshot = {
-  status: ConnectivityStatus
-  /** Per-signal breakdown for debugging / detailed indicators */
-  details: {
-    browserOnline: boolean // navigator.onLine
-    // React Query onlineManager — a module-level singleton, so it is always readable regardless of
-    // whether a QueryClient is mounted; never null on the client (the pre-hydration SSR snapshot
-    // reports an optimistic `true`, matching `browserOnline`, rather than an "unknown" null).
-    queryOnline: boolean
-    sseOpen: boolean | null // EventSource readyState === OPEN — null when no sseUrl configured
-    healthPassing: boolean | null // /health ping succeeded — null when no healthUrl configured
-  }
-}
-
-export type ConnectivityOverride = {
-  browserOnline?: boolean
-  queryOnline?: boolean
-  sseOpen?: boolean | null
-  healthPassing?: boolean | null
-}
-
-export type ConnectivityProviderProps = {
-  children: React.ReactNode
-  /** Optional SSE endpoint. When set, an EventSource is opened and its readyState is monitored. */
-  sseUrl?: string
-  /** Optional health-check endpoint. When set, periodic GET requests monitor backend reachability. */
-  healthUrl?: string
-  /** Interval in ms for health pings. Default: 30_000 (30s). */
-  healthIntervalMs?: number
-  /** Override individual signal values for testing / simulation. Non-overridden keys use real signals. */
-  override?: ConnectivityOverride
-}

package/src/provider/use-connectivity.ts

@@ -1,26 +0,0 @@
-/**
- * useConnectivity — reads the aggregated connectivity status from ConnectivityContext.
- *
- * Throws if used outside a ConnectivityProvider. `BasaltProvider` auto-mounts
- * `ConnectivityProvider`, so this hook works with zero setup in the common case. It replaced the
- * former online-status hook that lived on `basalt-ui/state` (see MIGRATING.md).
- *
- * @example
- * const { status, details } = useConnectivity()
- * if (status === 'offline') return <OfflineBanner />
- */
-import { useContext } from 'react'
-import { ConnectivityContext } from './connectivity-provider'
-import type { ConnectivitySnapshot } from './connectivity-types'
-
-export function useConnectivity(): ConnectivitySnapshot {
-  const snapshot = useContext(ConnectivityContext)
-  if (snapshot === null) {
-    throw new Error(
-      'useConnectivity() must be used within a <ConnectivityProvider>. ' +
-        'Wrap your app in <BasaltProvider> (which auto-mounts ConnectivityProvider) ' +
-        'or mount <ConnectivityProvider> manually.',
-    )
-  }
-  return snapshot
-}

package/src/query-devtools.tsx

@@ -1,40 +0,0 @@
-/**
- * `BasaltQueryDevtools` — prod-safe lazy wrapper for @tanstack/react-query-devtools. Folded onto
- * the root barrel alongside `query-client.ts` (C1 consolidation, dropping the `./query` subpath).
- * The devtools package is an OPTIONAL peer — never imported at module evaluation time. The dynamic
- * import() resolves only when rendered in non-production.
- */
-import { lazy, Suspense } from 'react'
-import type { ComponentProps } from 'react'
-import type { ReactQueryDevtools } from '@tanstack/react-query-devtools'
-
-const LazyDevtools = lazy(() =>
-  import('@tanstack/react-query-devtools').then((m) => ({ default: m.ReactQueryDevtools })),
-)
-Object.assign(LazyDevtools, { displayName: 'LazyDevtools' })
-
-/**
- * Lazy, production-excluded wrapper for ReactQueryDevtools. Safe to import unconditionally —
- * the devtools chunk is only resolved when rendered outside of production and the dynamic
- * import fires. In production this returns null immediately.
- *
- * @example
- * import { BasaltQueryDevtools } from 'basalt-ui'
- *
- * function Root() {
- *   return (
- *     <QueryClientProvider client={client}>
- *       {children}
- *       <BasaltQueryDevtools initialIsOpen={false} />
- *     </QueryClientProvider>
- *   )
- * }
- */
-export function BasaltQueryDevtools(props: ComponentProps<typeof ReactQueryDevtools>) {
-  if (process.env['NODE_ENV'] === 'production') return null
-  return (
-    <Suspense fallback={null}>
-      <LazyDevtools {...props} />
-    </Suspense>
-  )
-}