Skip to content

README.md

Latest commit

 

History

History
300 lines (236 loc) · 10.1 KB

README.md

File metadata and controls

300 lines (236 loc) · 10.1 KB

@itiana/dashboard-kit

Real-time dashboard component library for React. Provides a drag-and-drop BentoGrid, KPI cards with trend indicators, streaming charts via SSE, a dark/light theme system, and CSV/JSON export - with zero required configuration.

What Problem It Solves

Building a production real-time dashboard involves wiring together a streaming data layer (SSE reconnect logic, parse errors, backoff), a layout system (drag, resize, responsive columns), live charts that trim old points, and a consistent theme. This library packages all of that as typed, composable primitives so you can focus on your data rather than plumbing.

Features

  • BentoGrid - draggable, resizable widget grid backed by react-grid-layout
  • KpiCard - metric display with trend arrows, target progress bar, status color, and loading skeleton
  • RealTimeChart - line / area / bar chart (recharts) with auto-trimming ring buffer and configurable mode
  • ThemeProvider - dark / light / system theme with localStorage persistence and design token injection
  • useRealTimeData - SSE hook with exponential backoff reconnect, parse error isolation, and clean unmount
  • useExport - download in-memory data as CSV or JSON with field selection and custom headers
  • Adapter layer - pure, independently testable functions: createEventSourceConnection, createReconnectStrategy, serializeToCsv, serializeToJson, downloadBlob

Compatibility

Dependency Tested version Notes
React 18.x React 19 not yet verified
TypeScript 5.x (strict) Required - no plain JS builds
recharts ^2.12 Peer dep via dependencies
react-grid-layout ^1.4 Peer dep via dependencies
Browsers Modern evergreen No SSR / no Node.js environment

Installation

npm install @itiana/dashboard-kit

react-grid-layout requires its CSS. Add both imports to your app entry:

import 'react-grid-layout/css/styles.css';
import 'react-grid-layout/css/animate.css';

Quick Start

import {
  ThemeProvider,
  BentoGrid,
  KpiCard,
  RealTimeChart,
  useRealTimeData,
} from '@itiana/dashboard-kit';
import type { Widget, WidgetLayout, KpiValue, ChartDataPoint } from '@itiana/dashboard-kit';

const widgets: Widget[] = [
  { id: 'w1', type: 'kpi',   title: 'Active Users',  config: {} },
  { id: 'w2', type: 'chart', title: 'Request Rate',   config: {} },
];

const layouts: WidgetLayout[] = [
  { i: 'w1', x: 0, y: 0, w: 3, h: 2 },
  { i: 'w2', x: 3, y: 0, w: 9, h: 4 },
];

const kpi: KpiValue = {
  label: 'Active Users',
  value: 4821,
  trend: 'up',
  trendPercent: 8.4,
  status: 'good',
};

function App() {
  const { data } = useRealTimeData<ChartDataPoint[]>({
    url: import.meta.env.VITE_METRICS_STREAM_URL,
  });

  return (
    <ThemeProvider defaultMode="dark">
      <BentoGrid
        widgets={widgets}
        layouts={layouts}
        renderWidget={(w) => {
          if (w.id === 'w1') return <KpiCard kpi={kpi} />;
          if (w.id === 'w2')
            return (
              <RealTimeChart
                config={{
                  series: [{ key: 'value', name: 'req/s' }],
                  mode: 'area',
                  maxPoints: 120,
                  showGrid: true,
                }}
                data={data ?? []}
              />
            );
          return null;
        }}
      />
    </ThemeProvider>
  );
}

Components API

ThemeProvider

Must wrap the component tree. Supports 'light' | 'dark' | 'system'. Persists choice to localStorage.

<ThemeProvider defaultMode="system" storageKey="my-theme">
  {children}
</ThemeProvider>

Access theme tokens and controls anywhere with useTheme().

Prop Type Default
defaultMode 'light' | 'dark' | 'system' 'system'
storageKey string 'theme'
children ReactNode required

BentoGrid

Draggable, resizable widget container. Requires react-grid-layout CSS (see Installation).

Prop Type Default
widgets Widget[] required
layouts WidgetLayout[] required
renderWidget (w: Widget) => ReactNode required
cols number 12
rowHeight number 80
isDraggable boolean true
isResizable boolean true
onLayoutChange (layouts: WidgetLayout[]) => void –

KpiCard

Displays a single metric with optional trend indicator, target progress bar, status color, and loading skeleton.

<KpiCard
  kpi={{
    label: 'CPU',
    value: 73.2,
    unit: '%',
    status: 'warning',
    trend: 'up',
    trendPercent: 4.1,
    target: 100,
  }}
  onClick={() => drillDown('cpu')}
/>
Prop Type Default
kpi KpiValue required
loading boolean false
onClick () => void –

When onClick is provided, the card renders as a <button> element.

RealTimeChart

Renders a recharts chart that auto-trims its ring buffer to maxPoints.

<RealTimeChart
  config={{
    series: [{ key: 'cpu', name: 'CPU %' }],
    mode: 'line',       // 'line' | 'area' | 'bar'
    maxPoints: 120,
    showGrid: true,
    showLegend: true,
    yAxisDomain: [0, 100],
    animate: false,
  }}
  data={points}
  height={240}
/>
Prop Type Default
config RealTimeChartConfig required
data ChartDataPoint[] required
height number 300
onDataRequest () => ChartDataPoint | null –
className string –

config.mode overrides per-series type. When mode is omitted, the chart type is auto-detected from the series array.

Hooks API

useRealTimeData<T>(options): SSEState<T>

Opens an SSE connection and manages reconnect with exponential backoff + jitter. Closes cleanly on unmount.

const { data, isConnected, error, reconnectCount } =
  useRealTimeData<MetricPayload>({
    url: import.meta.env.VITE_STREAM_URL,
    maxReconnectAttempts: 10,
    reconnectInterval: 1000,
    parseMessage: (raw) => JSON.parse(raw) as MetricPayload,
  });

SSE option contract (SSEOptions<T>):

Field Type Default
url string required
withCredentials boolean false
reconnectInterval number (ms) 1000
maxReconnectAttempts number 10
parseMessage (raw: string) => T JSON.parse
onOpen () => void –
onError (e: Event) => void –

error is typed as RealtimeError:

type RealtimeError =
  | { type: 'transport'; message: string }
  | { type: 'parse';     message: string; rawData?: string }
  | { type: 'configuration'; message: string };

useExport(): UseExportReturn

Downloads in-memory typed data as CSV or JSON.

const { exportData, isExporting, error } = useExport();

await exportData({
  data: rows,
  filename: 'report',
  format: 'csv',
  fields: ['timestamp', 'value'],
  headers: { timestamp: 'Time', value: 'Metric' },
});

ExportOptions<T> contract:

Field Type Default
data T[] required
filename string 'export'
format 'csv' | 'json' 'csv'
fields (keyof T)[] all keys
headers Partial<Record<keyof T, string>> field names

SSR / Next.js Notes

This library is browser-only. It uses EventSource, document, URL.createObjectURL, and localStorage. Do not render any component or call any hook during server-side rendering. Use dynamic imports with ssr: false in Next.js:

const BentoGrid = dynamic(() => import('@itiana/dashboard-kit').then(m => m.BentoGrid), {
  ssr: false,
});

Accessibility

  • KpiCard renders as a <button> with type="button" when onClick is provided, enabling keyboard activation.
  • Progress bars use role="progressbar" with aria-valuenow, aria-valuemin, and aria-valuemax.
  • Loading skeletons set aria-busy="true" on the container.
  • Theme tokens expose sufficient contrast ratios for dark and light modes.

Known Constraints

  • React 19 compatibility is not verified - use React 18.
  • No SSR / no Node.js environment support.
  • useRealTimeData reconnects up to maxReconnectAttempts times; after exhaustion it stops retrying and leaves error set.
  • BentoGrid requires react-grid-layout CSS to be imported manually in the consumer app.
  • The library has no built-in virtualization; very large widget counts (>50) may affect grid performance.

Development

npm install        # install all deps including devDependencies
npm run typecheck  # tsc --noEmit - must pass before committing
npm test           # vitest run - all unit tests
npm run build      # vite library build → dist/
npm run lint       # eslint src __tests__

Release Status

Current version: 0.1.0-alpha. Public API may change before 1.0.

License

MIT - see LICENSE