react-dashstream 0.0.6 → 0.0.8

package/README.md

@@ -11,9 +11,9 @@ npm install react-dashstream
 ## Quick start
 
 ```tsx
-import "dashstream/dist/index.css";
-import { AIOPsDashboard, Service, ServerNode, DatabaseNode } from "dashstream";
-import type { ServiceMeta } from "dashstream";
+import "react-dashstream/dist/index.css";
+import { AIOPsDashboard, Service, ServerNode, DatabaseNode } from "react-dashstream";
+import type { ServiceMeta } from "react-dashstream";
 
 const services: ServiceMeta[] = [
     {
@@ -71,130 +71,619 @@ Click a service to expand its topology. Click a component to drill into its inte
 
 ## Full example — multi-service, multi-layer
 
-Two services with different topologies rotating in a 3D carousel.
-This is the example included in `example/Dashboard.tsx` inside this package.
+See `example/Dashboard.tsx` in this package for a complete two-service example with Payment Gateway and Auth Service topologies rotating in a 3D carousel.
+
+---
+
+## External data source monitoring
+
+DashStream can connect to any HTTP monitoring endpoint (Prometheus, Grafana, custom APIs) and feed live values into your dashboard. This section covers **every** data path — from node props to service dialogs, component dialogs, alerts, drill-down internals, and graphs.
+
+### How it works
+
+1. Set `liveData={true}` on `AIOPsDashboard` with `dataEndpoint` and `dataBindings`.
+2. A **credentials modal** appears on first load asking for `access-key` and `access-secret-key` (stored in memory only).
+3. The dashboard polls `GET <endpoint>?query=<encodedQuery>` for each unique query with credentials as HTTP headers.
+4. Resolved values are injected as **props** into child service components matched by `name`.
+5. The header shows **"DATA REFRESH FAILED"** if any queries fail.
+
+### Live data props
+
+| Prop                  | Type                                     | Default       | Description                                            |
+| --------------------- | ---------------------------------------- | ------------- | ------------------------------------------------------ |
+| `liveData`            | `boolean`                                | `false`       | Enable the live data pipeline.                         |
+| `dataEndpoint`        | `string`                                 | —             | Base URL. Queries sent as `GET <url>?query=<encoded>`. |
+| `dataBindings`        | `DataBindings`                           | —             | Maps service → prop → query. See below.                |
+| `dataTransform`       | `(raw) => unknown`                       | Numeric parse | Global transform for raw responses.                    |
+| `dataRefreshInterval` | `number`                                 | `60000`       | Polling interval in ms.                                |
+| `serviceDataBindings` | `Record<string, ServiceMetricBinding[]>` | —             | Live metrics for the service stats dialog.             |
+
+### Endpoint contract
+
+| Aspect       | Requirement                                                     |
+| ------------ | --------------------------------------------------------------- |
+| **Method**   | `GET`                                                           |
+| **URL**      | `<dataEndpoint>?query=<urlEncodedQuery>`                        |
+| **Headers**  | `access-key` and `access-secret-key`                            |
+| **Response** | Plain text body (trimmed). Default transform parses as number.  |
+| **Errors**   | Non-2xx → counted as failure. Partial failures shown in header. |
+
+For JSON responses (e.g. Prometheus), provide a custom `dataTransform`:
+
+```tsx
+dataTransform={(raw) => {
+    const parsed = JSON.parse(String(raw));
+    return parsed?.data?.result?.[0]?.value?.[1] ?? raw;
+}}
+```
+
+---
+
+### 1. Data bindings — injecting live props into nodes
+
+`dataBindings` maps **service name → prop name → query**. Each key in the inner object must match a prop on your service component. The service name must match the child's `name` prop.
+
+A binding can be a bare query string or an object with a custom transform:
+
+```ts
+type DataBinding = string | { query: string; transform?: (raw: unknown) => unknown };
+type DataBindings = Record<string, Record<string, DataBinding>>;
+```
+
+**Example — one service with a server and database:**
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { AIOPsDashboard, Service, ServerNode, DatabaseNode } from "react-dashstream";
+
+function statusFromValue(raw: unknown) {
+    const n = Number(raw);
+    if (n >= 85) return "critical";
+    if (n >= 70) return "warning";
+    return "online";
+}
+
+export default function App() {
+    return (
+        <AIOPsDashboard
+            brandName="LIVE DASHBOARD"
+            services={[{ name: "My Service", status: "online" }]}
+            liveData={true}
+            dataEndpoint="https://prometheus.example.com/api/v1/query"
+            dataRefreshInterval={10000}
+            dataBindings={{
+                "My Service": {
+                    // bare string → parsed as number automatically
+                    cpuLoad: 'cpu_usage{instance="srv-01"}',
+                    memLoad: 'memory_usage{instance="srv-01"}',
+
+                    // object with transform → convert number to status string
+                    status: {
+                        query: 'up{instance="srv-01"}',
+                        transform: statusFromValue,
+                    },
+
+                    // bind database props too
+                    dbCapacity: 'disk_capacity{instance="db-01"}',
+                    dbStatus: {
+                        query: 'disk_capacity{instance="db-01"}',
+                        transform: statusFromValue,
+                    },
+                },
+            }}
+        >
+            <MyService name="My Service" />
+        </AIOPsDashboard>
+    );
+}
+```
+
+The component receives `cpuLoad`, `memLoad`, `status`, `dbCapacity`, and `dbStatus` as live props, overriding their defaults.
+
+#### Multi-component services
+
+When a service has multiple nodes of the same type (e.g. three servers), use a flat naming convention with prefixes. Each binding maps one prop to one query — there is no array or object binding support.
 
 ```tsx
-import "dashstream/dist/index.css";
-import { AIOPsDashboard, Service, HumanNode, WebDispatcherNode, ServerNode, DatabaseNode } from "dashstream";
-import type { ServiceMeta } from "dashstream";
+// Service component — accepts prefixed props for each server
+interface ServiceXProps {
+    name: string;
+    status?: ComponentStatus;
+    srv1CpuLoad?: number;
+    srv1MemLoad?: number;
+    srv1Status?: ComponentStatus;
+    srv2CpuLoad?: number;
+    srv2MemLoad?: number;
+    srv2Status?: ComponentStatus;
+    srv3CpuLoad?: number;
+    srv3MemLoad?: number;
+    srv3Status?: ComponentStatus;
+    dbCapacity?: number;
+    dbStatus?: ComponentStatus;
+}
+
+function ServiceX({
+    name, status = "online",
+    srv1CpuLoad = 54, srv1MemLoad = 58, srv1Status = "online",
+    srv2CpuLoad = 63, srv2MemLoad = 66, srv2Status = "online",
+    srv3CpuLoad = 78, srv3MemLoad = 71, srv3Status = "online",
+    dbCapacity = 68, dbStatus = "online",
+}: ServiceXProps) {
+    return (
+        <Service name={name} status={status} connections={[/* ... */]}>
+            <ServerNode name="SRV-X1" status={srv1Status}
+                cpuLoad={srv1CpuLoad} memLoad={srv1MemLoad} ... />
+            <ServerNode name="SRV-X2" status={srv2Status}
+                cpuLoad={srv2CpuLoad} memLoad={srv2MemLoad} ... />
+            <ServerNode name="SRV-X3" status={srv3Status}
+                cpuLoad={srv3CpuLoad} memLoad={srv3MemLoad} ... />
+            <DatabaseNode name="DB-X1" status={dbStatus}
+                capacity={dbCapacity} ... />
+        </Service>
+    );
+}
+
+// Dashboard — bind each prefixed prop to its query
+<AIOPsDashboard
+    liveData={true}
+    dataEndpoint="https://prometheus.example.com/api/v1/query"
+    dataBindings={{
+        ServiceX: {
+            status: { query: 'status{instance="svcx"}', transform: statusFromValue },
+            srv1CpuLoad: 'cpu_usage{instance="srvx-01"}',
+            srv1MemLoad: 'memory_usage{instance="srvx-01"}',
+            srv1Status: { query: 'status{instance="srvx-01"}', transform: statusFromValue },
+            srv2CpuLoad: 'cpu_usage{instance="srvx-02"}',
+            srv2MemLoad: 'memory_usage{instance="srvx-02"}',
+            srv2Status: { query: 'status{instance="srvx-02"}', transform: statusFromValue },
+            srv3CpuLoad: 'cpu_usage{instance="srvx-03"}',
+            srv3MemLoad: 'memory_usage{instance="srvx-03"}',
+            srv3Status: { query: 'status{instance="srvx-03"}', transform: statusFromValue },
+            dbCapacity: 'disk_capacity{instance="dbx-01"}',
+            dbStatus: { query: 'status{instance="dbx-01"}', transform: statusFromValue },
+        },
+    }}
+    services={[{ name: "ServiceX", status: "online" }]}
+>
+    <ServiceX name="ServiceX" />
+</AIOPsDashboard>
+```
+
+Use a consistent naming convention like `srv1CpuLoad`, `srv2CpuLoad`, etc. The dashboard injects each prefixed prop individually. The service component maps each prop to the correct node.
+
+---
 
-// ── Service metadata (drives the stats dialog) ──────────────────────────
+### 2. Service dialog — live KPI metrics
 
+The **ServiceDialog** is the stats panel that appears when you click a service. It shows KPI rows and alerts.
+
+**Static way** — pass `ServiceMeta` with hardcoded values:
+
+```tsx
 const services: ServiceMeta[] = [
     {
-        name: "Payment Gateway",
-        status: "critical",
-        metrics: [
-            { label: "Service Health", value: "76.3%", color: "#ff8c00" },
-            { label: "Avg Response Time", value: "243ms", color: "#ff8c00" },
-            { label: "Active Connections", value: "1,847", color: "#bb55ff" },
-            { label: "Request Throughput", value: "3.2k req/s", color: "#00e5ff" },
-            { label: "Error Rate", value: "3.81%", color: "#ff2255" },
-        ],
-        alerts: [{ level: "critical", message: "SRV-01 CPU at 99% — immediate action required" }],
-    },
-    {
-        name: "Auth Service",
+        name: "My Service",
         status: "online",
         metrics: [
-            { label: "Service Health", value: "99.9%", color: "#00ff88" },
-            { label: "Avg Response Time", value: "11ms", color: "#00e5ff" },
-            { label: "Active Sessions", value: "8,421", color: "#bb55ff" },
-            { label: "Auth Rate", value: "920 req/s", color: "#00e5ff" },
-            { label: "Failed Logins", value: "0.03%", color: "#00ff88" },
+            { label: "Uptime", value: "99.99%", color: "#00ff88" },
+            { label: "Avg Latency", value: "8ms", color: "#00e5ff" },
+            { label: "Error Rate", value: "0.02%", color: "#00ff88" },
         ],
         alerts: [{ level: "info", message: "All Systems Nominal" }],
     },
 ];
+```
+
+**Live way** — use `serviceDataBindings` to fetch values from your endpoint:
+
+```tsx
+<AIOPsDashboard
+    services={[{ name: "My Service", status: "online" }]}
+    liveData={true}
+    dataEndpoint="https://prometheus.example.com/api/v1/query"
+    dataBindings={{ /* ... */ }}
+    serviceDataBindings={{
+        "My Service": [
+            { label: "CPU Load", query: 'cpu_usage{instance="srv-01"}', unit: "%", color: "#00e5ff" },
+            { label: "Memory",   query: 'memory_usage{instance="srv-01"}', unit: "%", color: "#bb55ff" },
+            { label: "Disk",     query: 'disk_capacity{instance="db-01"}', unit: "%", color: "#ff8c00" },
+        ],
+    }}
+>
+```
+
+Each `ServiceMetricBinding`:
+
+```ts
+interface ServiceMetricBinding {
+    label: string; // Row label
+    query: string; // PromQL query
+    unit?: string; // Suffix (e.g. "%", "ms")
+    color?: string; // Accent color
+    transform?: (raw: unknown) => string; // Custom formatter
+}
+```
 
-// ── Payment Gateway — 4-layer topology ──────────────────────────────────
+When `serviceDataBindings` is provided for a service, live values **replace** the static `ServiceMeta.metrics`.
 
-function PaymentGateway({ name }: { name: string }) {
+---
+
+### 3. Component dialog — custom gauges
+
+The **ComponentDialog** appears when you click a node (server, database, etc.) inside an expanded service. By default it shows CPU, Memory, and Storage gauges derived from the node's props.
+
+**Override these gauges** with the `dialogMetrics` prop on any compound node:
+
+```tsx
+<ServerNode
+    ex={200}
+    ey={380}
+    compactOffset={{ x: -30, y: -20 }}
+    zIndex={8}
+    name="SRV-01"
+    subLabel="APP SERVER"
+    status="online"
+    cpuLoad={67}
+    memLoad={72}
+    dialogMetrics={[
+        { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: 67, unit: "%" },
+        { id: "mem", label: "MEMORY", sublabel: "HEAP USAGE", value: 72, unit: "%" },
+        { id: "iops", label: "IOPS", sublabel: "DISK OPS", value: 45, unit: "k/s", icon: "disk" },
+        {
+            id: "threads",
+            label: "THREADS",
+            sublabel: "ACTIVE",
+            value: 82,
+            unit: "%",
+            warnAt: 60,
+            critAt: 80,
+            icon: "cpu",
+        },
+    ]}
+/>
+```
+
+Each `ComponentDialogMetric`:
+
+```ts
+interface ComponentDialogMetric {
+    id: string; // Unique key
+    label: string; // Upper label (e.g. "CPU")
+    sublabel: string; // Lower label (e.g. "PROCESSOR")
+    value: number; // 0–100 gauge value
+    unit?: string; // Suffix (default "%")
+    icon?: "cpu" | "mem" | "disk"; // Gauge icon (default "cpu")
+    warnAt?: number; // Orange threshold (default 70)
+    critAt?: number; // Red threshold (default 85)
+    color?: string; // Override bar color (bypasses thresholds)
+}
+```
+
+All compound nodes (`ServerNode`, `DatabaseNode`, `WebDispatcherNode`, `MessageServerNode`) accept `dialogMetrics`.
+
+**Live component dialog metrics** — to feed live values into custom gauges, expose each metric value as a prop on your service component and use `dataBindings` to inject them. Then build the `dialogMetrics` array from those live props:
+
+```tsx
+// 1. Define your service component with props for each custom metric
+import { Service, ServerNode } from "react-dashstream";
+import type { ComponentStatus } from "react-dashstream";
+
+interface MyServiceProps {
+    name: string;
+    status?: ComponentStatus;
+    cpuLoad?: number;
+    memLoad?: number;
+    iops?: number;
+    threadCount?: number;
+}
+
+function MyService({
+    name,
+    status = "online",
+    cpuLoad = 42,
+    memLoad = 60,
+    iops = 20,
+    threadCount = 45,
+}: MyServiceProps) {
     return (
         <Service
             name={name}
-            status="critical"
-            connections={[
-                { from: [330, 100], to: [330, 230], visibleAtPhase: 2, color: "#00e5ff" },
-                { from: [330, 230], to: [200, 380], visibleAtPhase: 3 },
-                { from: [330, 230], to: [460, 380], visibleAtPhase: 3 },
-                { from: [200, 380], to: [330, 520], visibleAtPhase: 4, color: "#ff8c00" },
-                { from: [460, 380], to: [330, 520], visibleAtPhase: 4, color: "#ff8c00" },
-            ]}
+            status={status}
+            connections={
+                [
+                    /* ... */
+                ]
+            }
         >
-            <HumanNode
-                ex={330}
-                ey={100}
-                compactOffset={{ x: 0, y: -50 }}
-                zIndex={10}
-                visibleAtPhase={2}
-                color="#00e5ff"
-                scale={1.5}
-            />
-            <WebDispatcherNode
-                ex={330}
-                ey={230}
-                compactOffset={{ x: 0, y: -25 }}
-                zIndex={9}
-                name="GATEWAY"
-                subLabel="HTTP LAYER"
-                status="online"
-                traffic={82}
-                activeRoutes={6}
-                visibleAtPhase={2}
-            />
             <ServerNode
                 ex={200}
                 ey={380}
-                compactOffset={{ x: -30, y: 10 }}
+                compactOffset={{ x: -30, y: -20 }}
                 zIndex={8}
                 name="SRV-01"
-                subLabel="PROCESSOR"
-                status="critical"
-                cpuLoad={99}
-                memLoad={64}
+                subLabel="APP SERVER"
+                status={status}
+                cpuLoad={cpuLoad}
+                memLoad={memLoad}
+                dialogMetrics={[
+                    { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: cpuLoad },
+                    { id: "mem", label: "MEMORY", sublabel: "HEAP", value: memLoad },
+                    {
+                        id: "iops",
+                        label: "IOPS",
+                        sublabel: "DISK OPS",
+                        value: iops,
+                        icon: "disk",
+                        warnAt: 50,
+                        critAt: 80,
+                    },
+                    {
+                        id: "threads",
+                        label: "THREADS",
+                        sublabel: "ACTIVE",
+                        value: threadCount,
+                        icon: "cpu",
+                        warnAt: 60,
+                        critAt: 85,
+                    },
+                ]}
                 alert={{ offsetX: -160, offsetY: -60, align: "left" }}
             />
-            <ServerNode
-                ex={460}
-                ey={380}
-                compactOffset={{ x: 30, y: 10 }}
-                zIndex={8}
-                name="SRV-02"
-                subLabel="PROCESSOR"
-                delay="0.4s"
-                status="online"
-                cpuLoad={38}
-                memLoad={51}
-            />
-            <DatabaseNode
-                ex={330}
-                ey={520}
-                compactOffset={{ x: 0, y: 40 }}
-                zIndex={7}
-                name="PG-DB"
-                subLabel="PRIMARY"
-                color="#ff8c00"
-                status="online"
-                capacity={61}
-            />
         </Service>
     );
 }
 
-// ── Auth Service — 2-layer topology ─────────────────────────────────────
+// 2. Bind each prop to a live query
+<AIOPsDashboard
+    liveData={true}
+    dataEndpoint="https://prometheus.example.com/api/v1/query"
+    dataBindings={{
+        "My Service": {
+            cpuLoad: 'cpu_usage{instance="srv-01"}',
+            memLoad: 'memory_usage{instance="srv-01"}',
+            iops: 'disk_iops{instance="srv-01"}',
+            threadCount: 'active_threads{instance="srv-01"}',
+            status: { query: 'cpu_usage{instance="srv-01"}', transform: statusFromValue },
+        },
+    }}
+    services={[{ name: "My Service", status: "online" }]}
+>
+    <MyService name="My Service" />
+</AIOPsDashboard>;
+```
+
+The dashboard injects `cpuLoad`, `memLoad`, `iops`, and `threadCount` as live props into `MyService`. Those flow into the `dialogMetrics` array, so the component dialog gauges update automatically on every poll cycle. This works for any number of custom metrics — just add a prop for each one.
+
+---
+
+### 4. Alerts — automatic threshold detection
+
+Nodes **automatically** show alert callouts when metrics breach thresholds:
+
+- **Warning** at 70% (orange callout)
+- **Critical** at 85% (red callout)
+
+This works from `cpuLoad`, `memLoad`, `traffic`, `queueDepth`, or `capacity` — no extra code needed:
+
+```tsx
+// This server shows a critical alert automatically because cpuLoad > 85
+<ServerNode
+    ex={200}
+    ey={380}
+    compactOffset={{ x: -30, y: -20 }}
+    zIndex={8}
+    name="SRV-01"
+    subLabel="PROCESSOR"
+    status="online"
+    cpuLoad={92}
+    memLoad={64}
+/>
+```
+
+**Position the callout:**
+
+```tsx
+<ServerNode
+    cpuLoad={92}
+    alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+    ...
+/>
+```
+
+**Custom alert message:**
+
+```tsx
+<ServerNode
+    cpuLoad={92}
+    alert={{ msg: "CPU overload — scale out", offsetX: -160, offsetY: -60, align: "left" }}
+    ...
+/>
+```
+
+**Custom thresholds** via `dialogMetrics`:
+
+```tsx
+<ServerNode
+    dialogMetrics={[
+        { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: 67,
+          warnAt: 50, critAt: 75 },  // Alert triggers at 67% because critAt is 75
+    ]}
+    alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+    ...
+/>
+```
+
+Alert `align` options: `"left"`, `"right"`, `"top"`, `"bottom"`.
+
+---
+
+### 5. Drill-down internals — custom sub-components
+
+When you click a node in expanded view, a **drill-down** opens showing internal sub-components (CPUs, memory sticks, drives, etc.). By default these are auto-generated based on node type.
+
+Provide **custom sub-components** via the `subComponents` prop:
+
+```tsx
+import { ServerNode, CPU3D, Memory3D, DriveBay3D, ThreadPool3D } from "react-dashstream";
+import type { SubComponentConfig } from "react-dashstream";
+
+const internals: SubComponentConfig[] = [
+    {
+        id: "cpu-0",
+        label: "CPU-0",
+        status: "online",
+        element: <CPU3D label="CPU-0" load={67} color="#00e5ff" />,
+    },
+    {
+        id: "cpu-1",
+        label: "CPU-1",
+        status: "warning",
+        element: <CPU3D label="CPU-1" load={88} color="#ff8c00" status="warning" />,
+    },
+    {
+        id: "heap",
+        label: "HEAP",
+        status: "online",
+        element: <Memory3D label="HEAP" usedPercent={72} color="#8855ee" />,
+    },
+    {
+        id: "drive",
+        label: "DRIVE-0",
+        status: "online",
+        element: <DriveBay3D label="DRIVE-0" color="#00e5ff" activity={true} />,
+    },
+    {
+        id: "threads",
+        label: "THREADS",
+        status: "online",
+        element: <ThreadPool3D label="THREADS" color="#00e5ff" />,
+    },
+];
+
+<ServerNode
+    ex={200}
+    ey={380}
+    compactOffset={{ x: -30, y: -20 }}
+    zIndex={8}
+    name="SRV-01"
+    subLabel="APP SERVER"
+    status="online"
+    cpuLoad={67}
+    memLoad={72}
+    subComponents={internals}
+/>;
+```
+
+Each `SubComponentConfig`:
+
+```ts
+interface SubComponentConfig {
+    id: string; // Unique key
+    label: string; // Display name
+    status: ComponentStatus; // Drives LED color
+    detail?: string; // Shown on fault
+    element: ReactNode; // The 3D element to render
+}
+```
+
+Available internal 3D components: `CPU3D`, `Memory3D`, `DriveBay3D`, `NetworkBlock3D`, `ThreadPool3D`, `Platter3D`, `Port3D`.
+
+---
+
+### 6. Graph series — custom sparklines
+
+The drill-down also shows a **historical graph panel** with sparklines. By default, graphs are auto-generated from mock data.
+
+Provide **custom graph data** via the `graphSeries` prop:
+
+```tsx
+import type { GraphSeries } from "react-dashstream";
+
+const graphs: GraphSeries[] = [
+    { id: "cpu", label: "CPU-0", unit: "%", color: "#00e5ff", data: [45, 52, 67, 71, 68, 55, 62] },
+    { id: "mem", label: "HEAP", unit: "%", color: "#8855ee", data: [60, 65, 72, 78, 82, 75, 70] },
+    { id: "iops", label: "DISK", unit: "k/s", color: "#ff8c00", data: [12, 15, 22, 18, 25, 20, 16] },
+];
+
+<ServerNode
+    ex={200}
+    ey={380}
+    compactOffset={{ x: -30, y: -20 }}
+    zIndex={8}
+    name="SRV-01"
+    subLabel="APP SERVER"
+    status="online"
+    cpuLoad={67}
+    memLoad={72}
+    graphSeries={graphs}
+/>;
+```
+
+Each `GraphSeries`:
+
+```ts
+interface GraphSeries {
+    id: string; // Unique key
+    label: string; // Label above the sparkline
+    unit: string; // Suffix (e.g. "%", "kbps")
+    color: string; // Sparkline color
+    data: number[]; // Data points (most recent last)
+}
+```
+
+---
+
+### 7. Putting it all together
+
+A complete example with live data, service dialog metrics, component dialog gauges, sub-components, graphs, and alert positioning:
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { AIOPsDashboard, Service, ServerNode, DatabaseNode, CPU3D, Memory3D } from "react-dashstream";
+import type { ServiceMeta, DataBindings, ServiceMetricBinding } from "react-dashstream";
+
+const services: ServiceMeta[] = [
+    {
+        name: "My Service",
+        status: "online",
+        metrics: [{ label: "Uptime", value: "99.99%", color: "#00ff88" }],
+        alerts: [{ level: "info", message: "All Systems Nominal" }],
+    },
+];
+
+function statusFromValue(raw: unknown) {
+    const n = Number(raw);
+    if (n >= 85) return "critical";
+    if (n >= 70) return "warning";
+    return "online";
+}
+
+const dataBindings: DataBindings = {
+    "My Service": {
+        cpuLoad: 'cpu_usage{instance="srv-01"}',
+        memLoad: 'memory_usage{instance="srv-01"}',
+        status: { query: 'cpu_usage{instance="srv-01"}', transform: statusFromValue },
+        dbCapacity: 'disk_capacity{instance="db-01"}',
+        dbStatus: { query: 'disk_capacity{instance="db-01"}', transform: statusFromValue },
+    },
+};
+
+const serviceDataBindings: Record<string, ServiceMetricBinding[]> = {
+    "My Service": [
+        { label: "CPU Load", query: 'cpu_usage{instance="srv-01"}', unit: "%", color: "#00e5ff" },
+        { label: "Memory", query: 'memory_usage{instance="srv-01"}', unit: "%", color: "#bb55ff" },
+        { label: "Disk", query: 'disk_capacity{instance="db-01"}', unit: "%", color: "#ff8c00" },
+    ],
+};
 
-function AuthService({ name }: { name: string }) {
+function MyService({ name, status, cpuLoad, memLoad, dbCapacity, dbStatus }: any) {
     return (
         <Service
             name={name}
-            status="online"
+            status={status ?? "online"}
             connections={[
-                { from: [200, 200], to: [200, 380], visibleAtPhase: 3 },
-                { from: [460, 200], to: [460, 380], visibleAtPhase: 3 },
-                { from: [200, 380], to: [330, 520], visibleAtPhase: 4, color: "#ff8c00" },
-                { from: [460, 380], to: [330, 520], visibleAtPhase: 4, color: "#ff8c00" },
+                { from: [330, 200], to: [200, 380], visibleAtPhase: 3 },
+                { from: [330, 200], to: [460, 380], visibleAtPhase: 3 },
             ]}
         >
             <ServerNode
@@ -202,46 +691,57 @@ function AuthService({ name }: { name: string }) {
                 ey={380}
                 compactOffset={{ x: -30, y: -20 }}
                 zIndex={8}
-                name="AUTH-01"
-                subLabel="IDENTITY"
-                status="online"
-                cpuLoad={34}
-                memLoad={48}
+                name="SRV-01"
+                subLabel="APP SERVER"
+                status={status ?? "online"}
+                cpuLoad={cpuLoad ?? 42}
+                memLoad={memLoad ?? 60}
+                alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+                subComponents={[
+                    {
+                        id: "cpu",
+                        label: "CPU-0",
+                        status: "online",
+                        element: <CPU3D label="CPU-0" load={cpuLoad ?? 42} />,
+                    },
+                    {
+                        id: "mem",
+                        label: "HEAP",
+                        status: "online",
+                        element: <Memory3D label="HEAP" usedPercent={memLoad ?? 60} />,
+                    },
+                ]}
+                graphSeries={[
+                    { id: "cpu", label: "CPU", unit: "%", color: "#00e5ff", data: [45, 52, 67, 71, 68] },
+                ]}
             />
-            <ServerNode
+            <DatabaseNode
                 ex={460}
                 ey={380}
                 compactOffset={{ x: 30, y: -20 }}
-                zIndex={8}
-                name="AUTH-02"
-                subLabel="SESSION"
-                delay="0.4s"
-                status="online"
-                cpuLoad={29}
-                memLoad={42}
-            />
-            <DatabaseNode
-                ex={330}
-                ey={520}
-                compactOffset={{ x: 0, y: 20 }}
                 zIndex={7}
-                name="AUTH-DB"
+                name="DB-01"
                 subLabel="PRIMARY"
-                color="#ff8c00"
-                status="online"
-                capacity={37}
+                status={dbStatus ?? "online"}
+                capacity={dbCapacity ?? 55}
+                alert={{ offsetX: 160, offsetY: -60, align: "right" }}
             />
         </Service>
     );
 }
 
-// ── Dashboard ───────────────────────────────────────────────────────────
-
 export default function App() {
     return (
-        <AIOPsDashboard brandName="DASHSTREAM" brandTag="EXAMPLE" services={services}>
-            <PaymentGateway name="Payment Gateway" />
-            <AuthService name="Auth Service" />
+        <AIOPsDashboard
+            brandName="MY DASHBOARD"
+            services={services}
+            liveData={true}
+            dataEndpoint="https://prometheus.example.com/api/v1/query"
+            dataRefreshInterval={10000}
+            dataBindings={dataBindings}
+            serviceDataBindings={serviceDataBindings}
+        >
+            <MyService name="My Service" />
         </AIOPsDashboard>
     );
 }
@@ -249,6 +749,57 @@ export default function App() {
 
 ---
 
+### 8. Data hooks
+
+Access live data anywhere inside the dashboard tree:
+
+```tsx
+import { useAIOpsData, useAIOpsDataOptional, useQueryResult } from "react-dashstream";
+
+function CustomWidget() {
+    const { data, isRefreshing, lastRefreshError } = useAIOpsData();
+    const cpu = useQueryResult('cpu_usage{instance="srv-01"}');
+
+    return (
+        <div>
+            {isRefreshing && <span>Refreshing...</span>}
+            {lastRefreshError && <span>{lastRefreshError}</span>}
+            <span>CPU: {String(cpu)}</span>
+        </div>
+    );
+}
+```
+
+| Hook                     | Returns                    | Throws?                      |
+| ------------------------ | -------------------------- | ---------------------------- |
+| `useAIOpsData()`         | Full `DataContextValue`    | Yes — outside `DataProvider` |
+| `useAIOpsDataOptional()` | `DataContextValue \| null` | No                           |
+| `useQueryResult(query)`  | Raw response or `null`     | Yes — outside `DataProvider` |
+
+### 9. Standalone DataProvider
+
+Use the data layer without the full dashboard shell:
+
+```tsx
+import { DataProvider, useAIOpsData } from "react-dashstream";
+
+function MyApp() {
+    return (
+        <DataProvider
+            config={{
+                endpoint: "https://prometheus.example.com/api/v1/query",
+                queries: ['cpu_usage{instance="srv-01"}'],
+                refreshInterval: 15000,
+            }}
+        >
+            <MyContent />
+        </DataProvider>
+    );
+}
+```
+
+---
+
 ## Components
 
 ### Layout
@@ -263,15 +814,15 @@ export default function App() {
 
 These combine `ServiceNode` + 3D model + `componentInfo` into a single element:
 
-| Component           | Key props                                         | Description                                             |
-| ------------------- | ------------------------------------------------- | ------------------------------------------------------- |
-| `ServerNode`        | `status`, `cpuLoad`, `memLoad`, `brandLabel`      | Application server tower with LEDs and CPU/memory bars. |
-| `DatabaseNode`      | `status`, `capacity`                              | Three-platter database cylinder with capacity bar.      |
-| `WebDispatcherNode` | `status`, `traffic`, `activeRoutes`               | Network appliance with 8 port LEDs and traffic metrics. |
-| `MessageServerNode` | `status`, `queueDepth`, `msgsPerSec`, `instances` | Message server with instance LEDs and queue metrics.    |
-| `HumanNode`         | `status`, `scale`                                 | SVG wireframe person icon for user/actor nodes.         |
+| Component           | Key props                                                                                                   | Description                                             |
+| ------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `ServerNode`        | `status`, `cpuLoad`, `memLoad`, `brandLabel`, `dialogMetrics`, `subComponents`, `graphSeries`, `alert`      | App server tower with LEDs and CPU/memory bars.         |
+| `DatabaseNode`      | `status`, `capacity`, `dialogMetrics`, `subComponents`, `graphSeries`, `alert`                              | Three-platter database cylinder with capacity bar.      |
+| `WebDispatcherNode` | `status`, `traffic`, `activeRoutes`, `dialogMetrics`, `subComponents`, `graphSeries`, `alert`               | Network appliance with 8 port LEDs and traffic metrics. |
+| `MessageServerNode` | `status`, `queueDepth`, `msgsPerSec`, `instances`, `dialogMetrics`, `subComponents`, `graphSeries`, `alert` | Message server with instance LEDs and queue metrics.    |
+| `HumanNode`         | `status`, `scale`                                                                                           | SVG wireframe person icon for user/actor nodes.         |
 
-All compound nodes share: `ex`, `ey`, `compactOffset`, `zIndex`, `name`, `subLabel`, `color`, `delay`, `visibleAtPhase`, `alert`.
+All compound nodes share: `ex`, `ey`, `compactOffset`, `zIndex`, `name`, `subLabel`, `color`, `delay`, `visibleAtPhase`.
 
 ### 3D models (low-level)
 
@@ -287,7 +838,7 @@ All 3D models accept: `rotateX`, `rotateY`, `rotateZ`, `scale`, `autoRotate`.
 | --------------- | ------------------------------------ | ---------------------------------------------------------------- |
 | `SyncBridge`    | `synced`, `latencyMs`                | Database replication bridge between primary and standby.         |
 | `NodeCallout`   | `status`, `title`, `msg`, `ex`, `ey` | Alert callout with leader line (auto-rendered by `ServiceNode`). |
-| `HoloBase`      | `size`, `color`, `widthRatio`        | Neon holographic base platform (auto-rendered by `Service`). Position via `baseConfig` on `Service`. |
+| `HoloBase`      | `size`, `color`, `widthRatio`        | Neon holographic base platform (auto-rendered by `Service`).     |
 | `SvgConnection` | `x1`, `y1`, `x2`, `y2`, `show`       | Animated dashed SVG connection line.                             |
 
 ### Dialogs
@@ -319,29 +870,7 @@ Compose compound nodes inside a `Service` container. Each node needs:
 - **`ex`, `ey`** — Position in the expanded topology (pixels from top-left of scene).
 - **`compactOffset`** — Offset from the service center in the compact carousel view.
 - **`zIndex`** — Stacking order (higher tiers get higher values).
-- **`visibleAtPhase`** — When the node fades in during expansion (0–6). Use `2` for top-tier nodes, `3` for middle, etc.
-
-### HoloBase position
-
-The holographic base platform rendered by each `Service` can be repositioned via `baseConfig`:
-
-```tsx
-<Service
-  name="My Service"
-  baseConfig={{
-    size: 90,
-    color: "#00e5ff",
-    widthRatio: 3,
-    expandedX: 330,   // absolute X in expanded view (default: container centre)
-    expandedY: 500,   // absolute Y in expanded view (default: 570)
-    compactOffsetX: 0, // horizontal nudge in compact carousel view
-    compactOffsetY: -20, // vertical nudge in compact carousel view
-  }}
-  ...
->
-```
-
-### Connection lines
+- **`visibleAtPhase`** — When the node fades in during expansion (0–6). Use `2` for top-tier, `3` for middle, etc.
 
 Define connection lines between nodes via the `connections` prop on `Service`:
 
@@ -352,41 +881,6 @@ connections={[
 ]}
 ```
 
-### Alerts
-
-Nodes automatically detect threshold breaches and render alert callouts. Default thresholds:
-
-- **Warning** at 70%
-- **Critical** at 85%
-
-Position the callout with the `alert` prop:
-
-```tsx
-<ServerNode
-  alert={{ offsetX: -160, offsetY: -60, align: "left" }}
-  cpuLoad={99}
-  ...
-/>
-```
-
-### Service dialog
-
-Pass `ServiceMeta` objects to `AIOPsDashboard` via the `services` prop to populate the stats panel that appears when a service is expanded:
-
-```tsx
-const services: ServiceMeta[] = [
-    {
-        name: "My Service",
-        status: "online",
-        metrics: [
-            { label: "Service Health", value: "99.9%", color: "#00ff88" },
-            { label: "Avg Response Time", value: "14ms", color: "#00e5ff" },
-        ],
-        alerts: [{ level: "info", message: "All Systems Nominal" }],
-    },
-];
-```
-
 ---
 
 ## Status types
@@ -407,7 +901,7 @@ type ComponentStatus = "online" | "warning" | "critical" | "offline";
 ## Theme constants
 
 ```ts
-import { STATUS_CFG, HOLO_CYAN, HOLO_BLUE, HOLO_SURFACE, HOLO_GLASS, makeFaceStyles } from "dashstream";
+import { STATUS_CFG, HOLO_CYAN, HOLO_BLUE, HOLO_SURFACE, HOLO_GLASS, makeFaceStyles } from "react-dashstream";
 ```
 
 - `STATUS_CFG` — status-to-color lookup table