react-dashstream 0.3.1 → 0.3.2

package/README.md

@@ -69,6 +69,21 @@ Click a service to expand its topology. Click a component to drill into its inte
 
 ---
 
+## AI assistant skills
+
+Published with the package under **`skills/`** — each folder is a small, topic-focused reference for coding agents (Cursor, OpenCode, etc.):
+
+| Skill | Focus |
+| ----- | ----- |
+| `dashstream-core` | Package overview, install, theming, exports, types, pitfalls |
+| `dashstream-3d-dashboard` | `AIOPsDashboard`, services, nodes, positioning, connections |
+| `dashstream-live-data` | `DataProvider`, bindings, hooks, endpoint contract |
+| `dashstream-component-dialogs` | Drill-down metrics, internals, sparklines, alerts |
+| `dashstream-event-view` | `EventView`, event API, event-to-dashboard bridge |
+| `dashstream-datacenter-view` | `DatacenterView`, topology, geography, buildings |
+
+---
+
 ## Theme (light / dark)
 
 The dashboard ships with **light** and **dark** visual modes. `AIOPsDashboard` defaults to **light**; the header includes a control to toggle modes.
@@ -139,7 +154,7 @@ See `example/Dashboard.tsx` in this package for a complete two-service example w
 
 The demo app (`src/App.tsx`) uses `example/SaudiMapView.tsx`, a thin wrapper around `DatacenterView` that composes the map with **`DatacenterSite`** / shape components (`TowerDC`, `FlatDC`, …). Scenario data (configs and drill-down services) lives in `example/saudiMapDemoData.tsx`; optional mock metric sliders use `example/DemoMetricPanel.tsx` + `example/DemoMetricPanel.css` (not part of the published package).
 
-**Agent-oriented reference:** see **`dashstream-skill.md`** (section **DatacenterView — topology / geography map**) for props, types, mock vs live data, and composition with `DataProvider`.
+**Agent-oriented reference:** see **`skills/dashstream-datacenter-view/SKILL.md`** for props, types, mock vs live data, and composition with `DataProvider`. Other topics live under **`skills/<name>/SKILL.md`** — see **AI assistant skills** below.
 
 ### Minimal import
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-dashstream",
-    "version": "0.3.1",
+    "version": "0.3.2",
     "type": "module",
     "author": "Busaud",
     "license": "MIT",
@@ -16,7 +16,7 @@
     "files": [
         "dist",
         "README.md",
-        "dashstream-skill.md"
+        "skills"
     ],
     "main": "./dist/index.js",
     "module": "./dist/index.js",

package/skills/dashstream-3d-dashboard/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: dashstream-3d-dashboard
+description: Build 3D carousel dashboards with AIOPsDashboard, services, and nodes
+license: MIT
+compatibility: opencode
+metadata:
+  audience: developers
+  workflow: react
+---
+
+## What I do
+
+- Guide building a 3D carousel dashboard with `AIOPsDashboard`
+- Document `Service`, `ServerNode`, `DatabaseNode`, `WebDispatcherNode`, `MessageServerNode`, `HumanNode`
+- Explain node positioning, connections, and compact offsets
+- Provide minimal and full static dashboard examples
+
+## When to use me
+
+Use this when creating or modifying a 3D dashboard layout — adding services, positioning nodes, or configuring connections.
+
+For live data wiring, see **dashstream-live-data**. For drill-down details, see **dashstream-component-dialogs**.
+
+---
+
+## AIOPsDashboard — the shell
+
+The top-level component that renders the header, carousel, and optional data layer.
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { AIOPsDashboard, Service, ServerNode, DatabaseNode } from "react-dashstream";
+
+<AIOPsDashboard
+    brandName="MY DASHBOARD"
+    brandTag="3D MONITOR"
+    services={[{ name: "Svc", status: "online" }]}
+>
+    <Service name="Svc" status="online" connections={[...]}>
+        {/* nodes go here */}
+    </Service>
+</AIOPsDashboard>
+```
+
+Key props (see **dashstream-core** for full `AIOPsDashboardProps`):
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `brandName` | `string` | `"BUSAUD AIOps"` | Header brand |
+| `brandTag` | `string` | `"3D MONITOR"` | Header tag |
+| `services` | `ServiceMeta[]` | — | Metadata for ServiceDialog panels |
+| `backgroundImage` | `string` | — | Dark mode background |
+| `lightBackgroundImage` | `string` | — | Light mode background |
+| `theme` / `onThemeChange` | `DashboardTheme` | — | Controlled theme |
+| `logoUrl` | `string` | — | Logo image URL |
+| `carouselSpeed` | `number` | `0.006` | Rotation speed |
+| `fontFamily` | `string` | — | CSS font-family |
+| `children` | `ReactNode` | — | `Service` children |
+
+---
+
+## Service — per-service container
+
+Each `Service` wraps one logical service's nodes and connections.
+
+```tsx
+<Service
+    name="My Service"
+    status="online"
+    connections={[
+        { from: [330, 200], to: [200, 380], visibleAtPhase: 3 },
+        { from: [330, 200], to: [460, 380], visibleAtPhase: 3 },
+        { from: [200, 380], to: [330, 520], visibleAtPhase: 4 },
+        { from: [460, 380], to: [330, 520], visibleAtPhase: 4 },
+    ]}
+>
+    {/* compound nodes */}
+</Service>
+```
+
+- `name` must match keys in `dataBindings`, `serviceDataBindings`, and `ServiceMeta.name` exactly.
+- `connections` are `ConnectionConfig[]` — animated SVG dashed lines between node positions.
+
+### ConnectionConfig
+
+```ts
+interface ConnectionConfig {
+    from: [number, number];     // [x, y] matching source node's ex/ey
+    to: [number, number];       // [x, y] matching target node's ex/ey
+    visibleAtPhase?: number;    // Default: 0
+    color?: string;             // Default: "#00e5ff"
+    duration?: string;          // Default: "1.2s"
+}
+```
+
+---
+
+## Compound nodes
+
+All compound nodes share common positioning props:
+
+| Prop | Type | Notes |
+|------|------|-------|
+| `name` | `string` | Display name + event bridge matching key |
+| `subLabel` | `string` | Secondary label below name |
+| `status` | `ComponentStatus` | `"online"` / `"warning"` / `"critical"` / `"offline"` |
+| `ex` | `number` | X position in the ~660×640 scene |
+| `ey` | `number` | Y position in the ~660×640 scene |
+| `compactOffset` | `{ x, y }` | Offset in compact carousel view |
+| `zIndex` | `number` | Z-order layering |
+| `alert` | `AlertConfig` | Callout positioning (see dashstream-component-dialogs) |
+| `dialogMetrics` | `ComponentDialogMetric[]` | Custom gauges (see dashstream-component-dialogs) |
+| `subComponents` | `SubComponentConfig[]` | Custom drill-down internals (see dashstream-component-dialogs) |
+| `graphSeries` | `GraphSeries[]` | Custom sparklines (see dashstream-component-dialogs) |
+
+### ServerNode
+
+```tsx
+<ServerNode
+    ex={200} ey={380}
+    compactOffset={{ x: -30, y: -20 }}
+    zIndex={8}
+    name="SRV-01"
+    subLabel="APP SERVER"
+    status="online"
+    cpuLoad={42}
+    memLoad={60}
+/>
+```
+
+Extra props: `cpuLoad` (number), `memLoad` (number).
+
+### DatabaseNode
+
+```tsx
+<DatabaseNode
+    ex={460} ey={520}
+    compactOffset={{ x: 30, y: 20 }}
+    zIndex={7}
+    name="DB-01"
+    subLabel="PRIMARY"
+    status="online"
+    capacity={55}
+/>
+```
+
+Extra props: `capacity` (number).
+
+### WebDispatcherNode
+
+```tsx
+<WebDispatcherNode
+    ex={330} ey={230}
+    compactOffset={{ x: 0, y: -30 }}
+    zIndex={9}
+    name="WD-01"
+    subLabel="DISPATCHER"
+    status="online"
+    traffic={45}
+/>
+```
+
+Extra props: `traffic` (number).
+
+### MessageServerNode
+
+```tsx
+<MessageServerNode
+    ex={330} ey={230}
+    compactOffset={{ x: 0, y: -30 }}
+    zIndex={9}
+    name="MSG-01"
+    subLabel="MESSAGE SERVER"
+    status="online"
+    queueDepth={30}
+/>
+```
+
+Extra props: `queueDepth` (number).
+
+### HumanNode
+
+```tsx
+<HumanNode
+    ex={330} ey={100}
+    compactOffset={{ x: 0, y: -40 }}
+    zIndex={10}
+    name="USERS"
+    subLabel="500 ACTIVE"
+    status="online"
+/>
+```
+
+---
+
+## Node positioning guide
+
+The topology scene is ~660×640 pixels.
+
+| Layer | Typical `ey` | `visibleAtPhase` | Component |
+| ----- | ------------ | ---------------- | --------- |
+| Users (top) | 100 | 2 | `HumanNode` |
+| Dispatcher | 230 | 2 | `WebDispatcherNode` |
+| App servers | 350–380 | 3 | `ServerNode` |
+| Databases | 500–520 | 4 | `DatabaseNode` |
+
+Center X = `330`. Left/right columns: `200` / `460`. Three-column: `165` / `330` / `495`.
+
+`compactOffset` controls node position in the compact carousel view relative to center.
+
+---
+
+## Usage patterns
+
+### Minimal static dashboard
+
+```tsx
+import "react-dashstream/dist/index.css";
+import { AIOPsDashboard, Service, ServerNode, DatabaseNode } from "react-dashstream";
+
+<AIOPsDashboard brandName="MY DASHBOARD" services={[{ name: "Svc", status: "online" }]}>
+    <Service
+        name="Svc"
+        status="online"
+        connections={[{ from: [330, 200], to: [330, 380], visibleAtPhase: 3 }]}
+    >
+        <ServerNode
+            ex={330} ey={380}
+            compactOffset={{ x: 0, y: 0 }}
+            zIndex={8}
+            name="SRV-01"
+            status="online"
+            cpuLoad={42}
+            memLoad={60}
+        />
+    </Service>
+</AIOPsDashboard>
+```
+
+### Multi-node service
+
+```tsx
+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 },
+                { from: [200, 380], to: [330, 520], visibleAtPhase: 4 },
+                { from: [460, 380], to: [330, 520], visibleAtPhase: 4 },
+            ]}
+        >
+            <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" }}
+            />
+            <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>
+    );
+}
+```
+
+### Multi-component services (flat prefix convention)
+
+When a service has multiple nodes of the same type, use flat prefixed props:
+
+```tsx
+interface ServiceXProps {
+    name: string;
+    status?: ComponentStatus;
+    srv1CpuLoad?: number;
+    srv1MemLoad?: number;
+    srv1Status?: ComponentStatus;
+    srv2CpuLoad?: number;
+    srv2MemLoad?: number;
+    srv2Status?: ComponentStatus;
+    dbCapacity?: number;
+    dbStatus?: ComponentStatus;
+}
+
+function ServiceX({
+    name, status = "online",
+    srv1CpuLoad = 54, srv1MemLoad = 58, srv1Status = "online",
+    srv2CpuLoad = 63, srv2MemLoad = 66, srv2Status = "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} ... />
+            <DatabaseNode name="DB-X1" status={dbStatus}
+                capacity={dbCapacity} ... />
+        </Service>
+    );
+}
+```
+
+Use a consistent convention like `srv1CpuLoad`, `srv2CpuLoad`. The service component maps each prefixed prop to the correct node.

package/skills/dashstream-component-dialogs/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: dashstream-component-dialogs
+description: Configure drill-down dialogs with custom metrics, internals, sparklines, and alerts
+license: MIT
+compatibility: opencode
+metadata:
+  audience: developers
+  workflow: react
+---
+
+## What I do
+
+- Document the ComponentDialog system (gauges, drill-down internals, sparkline graphs)
+- Explain `dialogMetrics`, `subComponents`, and `graphSeries` props
+- Cover automatic threshold-based alerts and custom alert positioning
+- Show how to wire live data into dialog metrics via service props
+
+## When to use me
+
+Use this when customizing what appears in the drill-down panel when a user clicks a node — custom gauges, internal 3D sub-components, sparkline charts, or alert callouts.
+
+---
+
+## Component dialog — default gauges
+
+The **ComponentDialog** appears when clicking a node. Default gauges are derived from node type:
+
+- **Server**: CPU (from `cpuLoad`), Memory (from `memLoad`), Storage
+- **Database**: Capacity (from `capacity`), Memory, Storage
+- **Dispatcher**: Traffic (from `traffic`), Memory, Storage
+- **Message Server**: Queue (from `queueDepth`), Memory, Storage
+
+Default thresholds: warn at 70, critical at 85.
+
+---
+
+## Custom dialogMetrics
+
+Override default gauges with `dialogMetrics` on any compound node:
+
+```tsx
+<ServerNode
+    name="SRV-01"
+    status="online"
+    cpuLoad={67}
+    memLoad={72}
+    ex={200} ey={380}
+    compactOffset={{ x: -30, y: -20 }}
+    zIndex={8}
+    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",
+        },
+    ]}
+/>
+```
+
+```ts
+interface ComponentDialogMetric {
+    id: string;        // Unique key
+    label: string;     // Upper label
+    sublabel: string;  // Lower label
+    value: number;     // 0–100
+    unit?: string;     // Default "%"
+    icon?: "cpu" | "mem" | "disk";  // Default "cpu"
+    warnAt?: number;   // Default 70
+    critAt?: number;   // Default 85
+    color?: string;    // Override bar color (bypasses threshold coloring)
+}
+```
+
+All compound nodes accept `dialogMetrics`: `ServerNode`, `DatabaseNode`, `WebDispatcherNode`, `MessageServerNode`.
+
+**When provided, all default gauges are removed** — you must define every metric you want shown.
+
+---
+
+## Drill-down internals — custom subComponents
+
+When clicking a node, the drill-down shows internal 3D sub-components. Default sub-components are auto-generated per type. Override with `subComponents`:
+
+```tsx
+import { CPU3D, Memory3D, DriveBay3D, ThreadPool3D, NetworkBlock3D, Platter3D, Port3D } 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: "heap", label: "HEAP", status: "warning",
+      element: <Memory3D label="HEAP" usedPercent={92} color="#8855ee" status="warning" /> },
+    { 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" /> },
+    { id: "net", label: "NET", status: "online",
+      element: <NetworkBlock3D label="NET" color="#00e5ff" /> },
+];
+
+<ServerNode subComponents={internals} ... />
+```
+
+```ts
+interface SubComponentConfig {
+    id: string;           // Unique key
+    label: string;        // Display name
+    status: ComponentStatus;  // LED color
+    detail?: string;      // Fault description
+    element: ReactNode;   // 3D element to render
+}
+```
+
+All compound nodes accept `subComponents`. **When provided, all auto-generated sub-components are removed.**
+
+---
+
+## Graph series — custom sparklines
+
+The drill-down's historical panel shows sparkline charts. Default graphs are auto-generated. Override with `graphSeries`:
+
+```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] },
+    { id: "mem",  label: "HEAP",   unit: "%",   color: "#8855ee", data: [60, 65, 72, 78, 82, 75] },
+    { id: "iops", label: "DISK",   unit: "k/s", color: "#ff8c00", data: [12, 15, 22, 18, 25, 20] },
+];
+
+<ServerNode graphSeries={graphs} ... />
+```
+
+```ts
+interface GraphSeries {
+    id: string;       // Unique key
+    label: string;    // Label above sparkline
+    unit: string;     // Suffix
+    color: string;    // Line color
+    data: number[];   // Points (most recent last)
+}
+```
+
+All compound nodes accept `graphSeries`. **When provided, all auto-generated sparklines are removed.**
+
+---
+
+## Alerts — automatic threshold detection
+
+Nodes auto-render `NodeCallout` alerts when metrics breach thresholds:
+
+- **Warning** at 70% → orange callout
+- **Critical** at 85% → red callout
+
+Sources (checked in priority order):
+
+1. `dialogMetrics` values vs their `warnAt`/`critAt`
+2. Context values (`cpuLoad`, `memLoad`, `traffic`, `queueDepth`, `capacity`) vs default thresholds
+
+```tsx
+// Auto-alert from cpuLoad > 85
+<ServerNode cpuLoad={92} memLoad={64}
+    alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+    ... />
+
+// Custom message
+<ServerNode cpuLoad={92}
+    alert={{ msg: "CPU overload — scale out", offsetX: -160, offsetY: -60, align: "left" }}
+    ... />
+
+// Custom thresholds via dialogMetrics
+<ServerNode
+    dialogMetrics={[
+        { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: 67,
+          warnAt: 50, critAt: 75 },
+    ]}
+    alert={{ offsetX: -160, offsetY: -60, align: "left" }}
+    ... />
+```
+
+### Alert prop shape
+
+```ts
+alert?: {
+    msg?: string;         // Custom message (auto-generated if omitted)
+    offsetX?: number;     // X offset from node (default 110)
+    offsetY?: number;     // Y offset from node (default -30)
+    align?: "left" | "right" | "top" | "bottom";  // Default "right"
+    internalRef?: string; // Sub-component ID
+}
+```
+
+Alert `align` options: `"left"`, `"right"`, `"top"`, `"bottom"`.
+
+---
+
+## ServiceDialog — static and live metrics
+
+The **ServiceDialog** panel shows KPIs when a service is expanded.
+
+### Static metrics via ServiceMeta
+
+```tsx
+const services: ServiceMeta[] = [
+    {
+        name: "My Service",
+        status: "online",
+        metrics: [
+            { label: "Uptime", value: "99.99%", color: "#00ff88" },
+            { label: "Avg Latency", value: "8ms", color: "#00e5ff" },
+        ],
+        alerts: [
+            { level: "info", message: "All Systems Nominal" },
+            { level: "warning", message: "High CPU on SRV-01" },
+            { level: "critical", message: "DB connection pool exhausted" },
+        ],
+    },
+];
+```
+
+### Live metrics via serviceDataBindings
+
+See **dashstream-live-data** for `serviceDataBindings` configuration.
+
+---
+
+## Full example — service with all dialog features
+
+```tsx
+import { CPU3D, Memory3D } from "react-dashstream";
+
+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" }}
+                dialogMetrics={[
+                    { id: "cpu", label: "CPU", sublabel: "PROCESSOR", value: cpuLoad ?? 42 },
+                    { id: "mem", label: "MEMORY", sublabel: "HEAP", value: memLoad ?? 60 },
+                ]}
+                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>
+    );
+}
+```