react-dashstream 0.0.7 → 0.0.9

package/README.md

@@ -71,376 +71,728 @@ 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,
-    HumanNode,
-    WebDispatcherNode,
-    ServerNode,
-    DatabaseNode,
-} from "react-dashstream";
-import type { ServiceMeta } from "react-dashstream";
+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"}',
 
-// ── Service metadata (drives the stats dialog) ──────────────────────────
+                    // 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
+// 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.
+
+---
+
+### 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" }],
     },
 ];
+```
 
-// ── Payment Gateway — 4-layer topology ──────────────────────────────────
+**Live way** — use `serviceDataBindings` to fetch values from your endpoint:
 
-function PaymentGateway({ name }: { name: string }) {
-    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" },
-            ]}
-        >
-            <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 }}
-                zIndex={8}
-                name="SRV-01"
-                subLabel="PROCESSOR"
-                status="critical"
-                cpuLoad={99}
-                memLoad={64}
-                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>
-    );
+```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
+}
+```
+
+When `serviceDataBindings` is provided for a service, live values **replace** the static `ServiceMeta.metrics`.
+
+---
+
+### 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:
 
-// ── Auth Service — 2-layer topology ─────────────────────────────────────
+```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 AuthService({ name }: { name: string }) {
+function MyService({
+    name,
+    status = "online",
+    cpuLoad = 42,
+    memLoad = 60,
+    iops = 20,
+    threadCount = 45,
+}: MyServiceProps) {
     return (
         <Service
             name={name}
-            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" },
-            ]}
+            status={status}
+            connections={
+                [
+                    /* ... */
+                ]
+            }
         >
             <ServerNode
                 ex={200}
                 ey={380}
                 compactOffset={{ x: -30, y: -20 }}
                 zIndex={8}
-                name="AUTH-01"
-                subLabel="IDENTITY"
-                status="online"
-                cpuLoad={34}
-                memLoad={48}
-            />
-            <ServerNode
-                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"
-                subLabel="PRIMARY"
-                color="#ff8c00"
-                status="online"
-                capacity={37}
+                name="SRV-01"
+                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" }}
             />
         </Service>
     );
 }
 
-// ── Dashboard ───────────────────────────────────────────────────────────
-
-export default function App() {
-    return (
-        <AIOPsDashboard brandName="DASHSTREAM" brandTag="EXAMPLE" services={services}>
-            <PaymentGateway name="Payment Gateway" />
-            <AuthService name="Auth Service" />
-        </AIOPsDashboard>
-    );
-}
+// 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.
+
 ---
 
-## External data source monitoring
+### 4. Alerts — automatic threshold detection
 
-DashStream supports live data from any HTTP-accessible monitoring backend (Prometheus, Grafana, custom APIs, etc.) via built-in interval polling. When enabled, the dashboard polls your endpoint with PromQL-style queries, authenticates with header-based credentials, and automatically injects resolved values as props into your service components.
+Nodes **automatically** show alert callouts when metrics breach thresholds:
 
-### How it works
+- **Warning** at 70% (orange callout)
+- **Critical** at 85% (red callout)
+
+This works from `cpuLoad`, `memLoad`, `traffic`, `queueDepth`, or `capacity` — no extra code needed:
 
-1. Set `liveData={true}` on `AIOPsDashboard` along with `dataEndpoint` and `dataBindings`.
-2. On first load, a **credentials modal** prompts for an `access-key` and `access-secret-key` (stored in memory only — never persisted).
-3. The dashboard polls `GET <dataEndpoint>?query=<encodedQuery>` for each unique query, sending credentials as HTTP headers.
-4. Resolved values are automatically injected as props into child service components matched by `name`.
-5. The header shows a **"DATA REFRESH FAILED"** indicator if any queries fail.
+```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}
+/>
+```
 
-### Enabling live data
+**Position the callout:**
 
 ```tsx
-import "react-dashstream/dist/index.css";
-import { AIOPsDashboard, Service, ServerNode, DatabaseNode } from "react-dashstream";
+<ServerNode
+    cpuLoad={92}
+    alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+    ...
+/>
+```
 
-export default function App() {
-    return (
-        <AIOPsDashboard
-            brandName="LIVE MONITOR"
-            services={services}
-            liveData={true}
-            dataEndpoint="https://prometheus.example.com/api/v1/query"
-            dataRefreshInterval={30000}
-            dataBindings={{
-                "My Service": {
-                    cpuLoad: 'cpu_usage{instance="srv-01"}',
-                    memLoad: 'memory_usage{instance="srv-01"}',
-                    status: {
-                        query: 'up{instance="srv-01"}',
-                        transform: (v) => (Number(v) > 0 ? "online" : "offline"),
-                    },
-                },
-            }}
-            dataTransform={(raw) => {
-                const n = Number(raw);
-                return isNaN(n) ? raw : n;
-            }}
-            serviceDataBindings={{
-                "My Service": [
-                    { label: "Uptime", query: 'uptime{svc="my-service"}', unit: "%", color: "#00ff88" },
-                    { label: "Latency", query: 'latency{svc="my-service"}', unit: "ms", color: "#00e5ff" },
-                    {
-                        label: "Error Rate",
-                        query: 'error_rate{svc="my-service"}',
-                        unit: "%",
-                        color: "#ff2255",
-                    },
-                ],
-            }}
-        >
-            <Service name="My Service" status="online" connections={[]}>
-                <ServerNode
-                    ex={200}
-                    ey={380}
-                    compactOffset={{ x: -30, y: -20 }}
-                    zIndex={8}
-                    name="SRV-01"
-                    subLabel="APP SERVER"
-                    status="online"
-                    cpuLoad={0}
-                    memLoad={0}
-                />
-                <DatabaseNode
-                    ex={460}
-                    ey={380}
-                    compactOffset={{ x: 30, y: -20 }}
-                    zIndex={7}
-                    name="DB-01"
-                    subLabel="PRIMARY"
-                    status="online"
-                    capacity={55}
-                />
-            </Service>
-        </AIOPsDashboard>
-    );
-}
+**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" }}
+    ...
+/>
 ```
 
-### Live data props reference
+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:
 
-| Prop                  | Type                                     | Description                                                                                     |
-| --------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `liveData`            | `boolean`                                | Enable the live data pipeline. Default `false`.                                                 |
-| `dataEndpoint`        | `string`                                 | Base URL of the monitoring endpoint. Queries are sent as `GET <endpoint>?query=<encodedQuery>`. |
-| `dataBindings`        | `DataBindings`                           | Maps service name → prop name → PromQL query. Resolved values are injected as component props.  |
-| `dataTransform`       | `(raw: unknown) => unknown`              | Global transform applied to every raw response. Defaults to numeric parsing.                    |
-| `dataRefreshInterval` | `number`                                 | Polling interval in milliseconds. Default `60000` (1 minute).                                   |
-| `serviceDataBindings` | `Record<string, ServiceMetricBinding[]>` | Maps service name → metric rows for the service stats dialog.                                   |
+```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" />,
+    },
+];
 
-### Data bindings
+<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 binding maps a prop name on a child service component to a query. Bindings can be a bare query string (uses the global `dataTransform`) or an object with a per-binding `transform`:
+Each `SubComponentConfig`:
 
 ```ts
-type DataBinding = string | { query: string; transform?: (raw: unknown) => unknown };
-type DataBindings = Record<string, Record<string, DataBinding>>;
+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
+}
 ```
 
-The service name key must match the `name` prop on the corresponding child component. When the polled response arrives, the transform is applied and the result is injected as the named prop, overriding any static default.
+Available internal 3D components: `CPU3D`, `Memory3D`, `DriveBay3D`, `NetworkBlock3D`, `ThreadPool3D`, `Platter3D`, `Port3D`.
 
-### Service metric bindings
+---
 
-These bind KPI rows in the **ServiceDialog** (the stats panel shown when a service is expanded) to live queries:
+### 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 ServiceMetricBinding {
-    label: string; // Row label (e.g. "Uptime")
-    query: string; // PromQL query string
-    unit?: string; // Unit suffix (e.g. "%", "ms")
-    color?: string; // Accent color for the row
-    transform?: (raw: unknown) => string; // Custom formatter
+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)
 }
 ```
 
-When `serviceDataBindings` is provided, live metric values replace the static `ServiceMeta.metrics` for that service.
+---
 
-### Endpoint contract
+### 7. Putting it all together
 
-Your monitoring endpoint must satisfy this contract:
+A complete example with live data, service dialog metrics, component dialog gauges, sub-components, graphs, and alert positioning:
 
-| Aspect             | Requirement                                                                                                                |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| **Method**         | `GET`                                                                                                                      |
-| **URL format**     | `<dataEndpoint>?query=<urlEncodedQuery>`                                                                                   |
-| **Auth headers**   | `access-key` and `access-secret-key`                                                                                       |
-| **Response body**  | Plain text or JSON. The default transform parses the trimmed body as a number; non-numeric values are returned as strings. |
-| **Error handling** | Non-2xx responses are counted as failures. Partial failures are reported in the header.                                    |
+```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";
 
-If your backend returns structured JSON (e.g. Prometheus instant-query format), provide a custom `dataTransform` to extract the scalar value:
+const services: ServiceMeta[] = [
+    {
+        name: "My Service",
+        status: "online",
+        metrics: [{ label: "Uptime", value: "99.99%", color: "#00ff88" }],
+        alerts: [{ level: "info", message: "All Systems Nominal" }],
+    },
+];
 
-```tsx
-dataTransform={(raw) => {
-    const parsed = JSON.parse(String(raw));
-    return parsed?.data?.result?.[0]?.value?.[1] ?? raw;
-}}
+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 MyService({ name, status, cpuLoad, memLoad, dbCapacity, dbStatus }: any) {
+    return (
+        <Service
+            name={name}
+            status={status ?? "online"}
+            connections={[
+                { from: [330, 200], to: [200, 380], visibleAtPhase: 3 },
+                { from: [330, 200], to: [460, 380], visibleAtPhase: 3 },
+            ]}
+        >
+            <ServerNode
+                ex={200}
+                ey={380}
+                compactOffset={{ x: -30, y: -20 }}
+                zIndex={8}
+                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] },
+                ]}
+            />
+            <DatabaseNode
+                ex={460}
+                ey={380}
+                compactOffset={{ x: 30, y: -20 }}
+                zIndex={7}
+                name="DB-01"
+                subLabel="PRIMARY"
+                status={dbStatus ?? "online"}
+                capacity={dbCapacity ?? 55}
+                alert={{ offsetX: 160, offsetY: -60, align: "right" }}
+            />
+        </Service>
+    );
+}
+
+export default function App() {
+    return (
+        <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>
+    );
+}
 ```
 
-### Using the data hooks directly
+---
 
-For advanced use cases, you can access the live data context anywhere inside the dashboard tree:
+### 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, lastRefreshTime } = useAIOpsData();
-
-    const cpuValue = useQueryResult('cpu_usage{instance="srv-01"}');
+    const { data, isRefreshing, lastRefreshError } = useAIOpsData();
+    const cpu = useQueryResult('cpu_usage{instance="srv-01"}');
 
     return (
         <div>
             {isRefreshing && <span>Refreshing...</span>}
-            {lastRefreshError && <span>Error: {lastRefreshError}</span>}
-            <span>CPU: {String(cpuValue)}</span>
+            {lastRefreshError && <span>{lastRefreshError}</span>}
+            <span>CPU: {String(cpu)}</span>
         </div>
     );
 }
 ```
 
-| Hook                     | Description                                                                                         |
-| ------------------------ | --------------------------------------------------------------------------------------------------- |
-| `useAIOpsData()`         | Returns the full `DataContextValue`. Throws if called outside a live-data dashboard.                |
-| `useAIOpsDataOptional()` | Returns `DataContextValue` or `null` if no `DataProvider` is present. Safe in dual-mode components. |
-| `useQueryResult(query)`  | Returns the raw response for a specific query string, or `null` if not yet fetched.                 |
+| Hook                     | Returns                    | Throws?                      |
+| ------------------------ | -------------------------- | ---------------------------- |
+| `useAIOpsData()`         | Full `DataContextValue`    | Yes — outside `DataProvider` |
+| `useAIOpsDataOptional()` | `DataContextValue \| null` | No                           |
+| `useQueryResult(query)`  | Raw response or `null`     | Yes — outside `DataProvider` |
 
-### Standalone DataProvider
+### 9. Standalone DataProvider
 
-You can use `DataProvider` directly for custom layouts that don't use the full `AIOPsDashboard` shell:
+Use the data layer without the full dashboard shell:
 
 ```tsx
 import { DataProvider, useAIOpsData } from "react-dashstream";
 
-function MyCustomDashboard() {
+function MyApp() {
     return (
         <DataProvider
             config={{
                 endpoint: "https://prometheus.example.com/api/v1/query",
-                queries: ['cpu_usage{instance="srv-01"}', 'memory_usage{instance="srv-01"}'],
+                queries: ['cpu_usage{instance="srv-01"}'],
                 refreshInterval: 15000,
             }}
         >
-            <MyCustomContent />
+            <MyContent />
         </DataProvider>
     );
 }
@@ -462,15 +814,15 @@ function MyCustomDashboard() {
 
 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)
 
@@ -518,7 +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.
+- **`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`:
 
@@ -529,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