react-dashstream 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-dashstream",
-    "version": "0.3.3",
+    "version": "0.3.4",
     "type": "module",
     "author": "Busaud",
     "license": "MIT",

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

@@ -56,6 +56,7 @@ Key props (see **dashstream-core** for full `AIOPsDashboardProps`):
 | `carouselSpeed` | `number` | `0.006` | Rotation speed |
 | `fontFamily` | `string` | — | CSS font-family |
 | `children` | `ReactNode` | — | `Service` children |
+| `skipDataProvider` | `boolean` | — | When `true`, the shell does not wrap itself in `DataProvider` (parent already provides live-data context). Used with **`DatacenterView`** `liveDataHost="datacenter"` or a custom outer `DataProvider`. See **dashstream-live-data**. |
 
 ---
 

package/skills/dashstream-core/SKILL.md

@@ -33,7 +33,7 @@ For specific features, see sibling skills:
 ## Package basics
 
 > **Package**: `react-dashstream` (npm)
-> **Version**: 0.2.0
+> **Version**: 0.3.3
 > **Peer deps**: `react` ^18 || ^19, `react-dom` ^18 || ^19
 > **License**: MIT
 
@@ -95,7 +95,7 @@ ComponentDialog              ← Drill-down with internals + graphs
   ├─ HistoricalGraphPanel    ← Sparkline charts
   └─ CPU3D / Memory3D / DriveBay3D / NetworkBlock3D / ThreadPool3D / Platter3D / Port3D
 
-DataProvider                 ← Polling engine + credentials modal
+DataProvider                 ← Polling engine + credentials modal (may wrap AIOPsDashboard or be hoisted at DatacenterView; see dashstream-live-data)
 
 EventView                    ← Standalone event console (table view)
 
@@ -195,7 +195,7 @@ SAP sub-component helpers: `getServerSubComponents`, `getServerGraphSeries`, `ge
 
 ### Data layer
 
-`DataProvider`, `useAIOpsData`, `useAIOpsDataOptional`, `useQueryResult`, `extractUniqueQueries`, `extractDatacenterMetricQueries`, `defaultDataTransform`
+`DataProvider`, `useAIOpsData`, `useAIOpsDataOptional`, `useQueryResult`, `extractUniqueQueries`, `extractDatacenterMetricQueries`, `mergeLiveDataQueries`, `defaultDataTransform`
 
 ### Datacenter topology map
 
@@ -260,6 +260,7 @@ interface AIOPsDashboardProps {
     dataRefreshInterval?: number;      // Default: 60000
     serviceDataBindings?: Record<string, ServiceMetricBinding[]>;
     eventApiConfig?: EventApiConfig;   // Enable event-to-dashboard bridge
+    skipDataProvider?: boolean;        // Parent already wraps DataProvider (e.g. DatacenterView hoist)
     children: React.ReactNode;
 }
 ```
@@ -328,3 +329,4 @@ Output: `dist/index.js` (ESM), `dist/index.d.ts`, `dist/index.css`.
 10. **`graphSeries` replaces defaults** — When provided, all auto-generated sparklines are removed.
 11. **Event bridge matching** — Node `name` must match event `host` (case-insensitive) for `eventApiConfig` to highlight nodes automatically.
 12. **Theme context** — `EventView` and `CredentialsModal` use `useTheme()`. Without `ThemeProvider`, context defaults to `"dark"`. Wrap the app (or use `EventView`'s `theme` prop) so light dashboards are not paired with a dark event console or lock screen.
+13. **Duplicate `DataProvider`** — If you hoist `DataProvider` (e.g. around `DatacenterView`), set `skipDataProvider` on `AIOPsDashboard` and merge PromQL queries with `mergeLiveDataQueries` so only one provider polls. See **dashstream-live-data** and **dashstream-datacenter-view**.

package/skills/dashstream-datacenter-view/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dashstream-datacenter-view
-description: Build topology maps with DatacenterView, buildings, geography, and drill-down
+description: DatacenterView topology maps, liveDataHost, deferCredentialsUntilDashboard, metricBindings, drill-down AIOPsDashboard
 license: MIT
 compatibility: opencode
 metadata:
@@ -12,8 +12,8 @@ metadata:
 
 - Document `DatacenterView` — SVG topology or geographic map with CSS 3D building markers
 - Explain both array config and declarative JSX composition APIs
-- Cover sites, building variants, connections, metric bindings, and geography
-- Show how drill-down integrates with `AIOPsDashboard`
+- Cover sites, building variants, connections, **`liveDataHost` / `deferCredentialsUntilDashboard`**, `metricBindings`, and geography
+- Show how drill-down integrates with `AIOPsDashboard` and optional hoisted `DataProvider`
 
 ## When to use me
 
@@ -149,17 +149,52 @@ Pass `dataCenters` with embedded `metrics`. No `DataProvider` required.
 
 ## PromQL (live) metrics on markers
 
-1. Wrap the tree in **`DataProvider`** with `config.queries` including every query used by `metricBindings`, collected via `extractDatacenterMetricQueries(metricBindings)` (and merge with queries for any nested `AIOPsDashboard` if you use `aiOpsDashboardProps`).
+1. Provide a **`DataProvider`** whose `config.queries` list includes every PromQL string used by **`metricBindings`**. Use **`extractDatacenterMetricQueries(metricBindings)`**, or **`mergeLiveDataQueries(metricBindings, aiOpsDashboardProps)`** when you also run dashboard live data from the same provider (see below).
 2. Pass **`metricBindings`**: `Record<buildingId, Partial<Record<keyof DatacenterMetrics, DataBinding>>>` — same `DataBinding` shape as service-level bindings (`string` or `{ query, transform? }`).
 3. `DatacenterView` calls `useAIOpsDataOptional()` and merges transformed numbers over each building's static `metrics` (site-level rows aggregate the merged per-building values).
 
-This path is **independent** of `AIOPsDashboard`'s `dataBindings` (which key off service `name` on carousel children).
+Map-level bindings use **building `id`**, not service `name`. Service-level **`dataBindings`** inside the drill-down dashboard still key off **`name`** on carousel children.
+
+---
+
+## Hoisted `DataProvider` (map + dashboard, one poll loop)
+
+Instead of wrapping `DataProvider` yourself, set:
+
+- **`liveDataHost`**: `"dashboard"` (default) — only the drill-down `AIOPsDashboard` mounts `DataProvider` when you open a site (previous behavior).
+- **`liveDataHost`**: `"datacenter"` — `DatacenterView` wraps itself in a **single** `DataProvider` with queries from **`mergeLiveDataQueries(metricBindings, aiOpsDashboardProps)`**. The inner `AIOPsDashboard` receives **`skipDataProvider`** automatically when it would have duplicated live-data wiring.
+
+Optional top-level props (fallbacks use `aiOpsDashboardProps` when omitted):
+
+- **`dataEndpoint`** / **`dataRefreshInterval`** — PromQL base URL and poll interval for the hoisted provider.
+
+### Credentials timing on the map
+
+- **`deferCredentialsUntilDashboard`** (default `false`): when **`liveDataHost="datacenter"`**, if `true`, the credentials modal is deferred until the user is in the **drill-down dashboard** phase (`promptCredentials` tracks map vs dashboard). You stay on the map without a key prompt; after credentials are set, both map and dashboard can use the same context.
+
+Example (shared endpoint, defer modal until drill-down):
+
+```tsx
+<DatacenterView
+    liveDataHost="datacenter"
+    deferCredentialsUntilDashboard
+    metricBindings={mapMetricBindings}
+    dataEndpoint="https://prom.example.com/api/v1/query"
+    aiOpsDashboardProps={{
+        liveData: true,
+        dataEndpoint: "https://prom.example.com/api/v1/query",
+        dataBindings: { /* service name → props */ },
+    }}
+>
+    {/* topology children */}
+</DatacenterView>
+```
 
 ---
 
 ## Drill-down dashboard
 
-`aiOpsDashboardProps` is spread onto the inner `AIOPsDashboard`; `services`, `theme`, `children` (from `renderServices()`), and branding are forced from the selected building so the map stays consistent. Use `aiOpsDashboardProps` for `liveData`, `dataEndpoint`, `dataBindings`, `serviceDataBindings`, etc., for service-level PromQL inside the opened datacenter.
+`aiOpsDashboardProps` is spread onto the inner `AIOPsDashboard`; `services`, `theme`, `children` (from `renderServices()`), and branding are forced from the selected building so the map stays consistent. Use `aiOpsDashboardProps` for `liveData`, `dataEndpoint`, `dataBindings`, `serviceDataBindings`, **`skipDataProvider`** (set automatically when `liveDataHost="datacenter"` supplies the provider), etc., for service-level PromQL inside the opened datacenter.
 
 ---
 
@@ -176,7 +211,11 @@ This path is **independent** of `AIOPsDashboard`'s `dataBindings` (which key off
 | `children` | `ReactNode` | — | Declarative topology (`DatacenterSite`, `TowerDC`, …). When set, `dataCenters` is ignored (dev warning if both are passed) |
 | `dataCenters` | `DatacenterBuildingConfig[]` | `[]` | Flat / JSON-friendly config; required unless `children` is used |
 | `connections` | `DatacenterConnection[]` | `[]` | Link lines between building or site ids |
-| `metricBindings` | `DatacenterMetricBindings` | — | Building id → metric field → PromQL `DataBinding`; needs `DataProvider` + `extractDatacenterMetricQueries` |
+| `metricBindings` | `DatacenterMetricBindings` | — | Building id → metric field → PromQL `DataBinding`; needs `DataProvider` + `extractDatacenterMetricQueries` (or hoisted provider via `liveDataHost`) |
+| `dataEndpoint` | `string` | — | PromQL endpoint for map bindings; falls back to `aiOpsDashboardProps.dataEndpoint` |
+| `dataRefreshInterval` | `number` | — | Poll interval for hoisted provider; falls back to `aiOpsDashboardProps.dataRefreshInterval` |
+| `liveDataHost` | `"dashboard" \| "datacenter"` | `"dashboard"` | Where `DataProvider` mounts: per-drill-down vs merged around `DatacenterView` |
+| `deferCredentialsUntilDashboard` | `boolean` | `false` | With `liveDataHost="datacenter"`, defer credentials modal until drill-down dashboard is active |
 | `dataTransform` | `(raw: unknown) => unknown` | `defaultDataTransform` | Applied to each binding unless overridden per binding |
 | `geography` | `DatacenterGeography` | — | `outlinePathD` + optional `referencePoints` (SVG coords) |
 | `showGeography` | `boolean` | `false` | When true, draws outline + reference points |

package/skills/dashstream-live-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dashstream-live-data
-description: Wire live PromQL data into DashStream dashboards via DataProvider and bindings
+description: Wire live PromQL data via DataProvider, bindings, mergeLiveDataQueries, skipDataProvider, and promptCredentials
 license: MIT
 compatibility: opencode
 metadata:
@@ -11,9 +11,9 @@ metadata:
 ## What I do
 
 - Explain the 4 data binding paths: node props, service dialog metrics, component dialog metrics, and hooks
-- Document `DataProvider`, `dataBindings`, `serviceDataBindings`, and data hooks
+- Document `DataProvider` (`promptCredentials`), `dataBindings`, `serviceDataBindings`, `mergeLiveDataQueries`, `skipDataProvider` on `AIOPsDashboard`, and data hooks
 - Specify the endpoint contract (method, headers, response format)
-- Show patterns for custom transforms and multi-component services
+- Show patterns for custom transforms, multi-component services, and parent-hoisted providers (with **dashstream-datacenter-view**)
 
 ## When to use me
 
@@ -198,6 +198,7 @@ interface DataContextValue {
     lastRefreshError: string | null;
     lastRefreshTime: Date | null;
     credentialsSet: boolean;
+    credentials: Credentials | null;
     setCredentials: (creds: Credentials) => void;
 }
 ```
@@ -222,6 +223,26 @@ import { DataProvider, useAIOpsData } from "react-dashstream";
 </DataProvider>
 ```
 
+### `promptCredentials`
+
+`DataProvider` accepts optional **`promptCredentials`** (default `true`). When `false`, children render but the **credentials modal is hidden** until `promptCredentials` becomes `true`. Polling still waits until credentials exist. Use this when a parent defers the modal (for example `DatacenterView` with `deferCredentialsUntilDashboard`).
+
+---
+
+## Provider placement — dashboard vs parent
+
+| Placement | Who wraps `DataProvider` | Typical use |
+| --------- | ------------------------ | ----------- |
+| **Default** | `AIOPsDashboard` when `liveData`, `dataEndpoint`, and `dataBindings` are set | Standalone 3D dashboard |
+| **Parent** | Your app or **`DatacenterView`** (`liveDataHost="datacenter"`) | One poll loop for map markers + drill-down services; avoids nested providers |
+
+When a parent already mounts `DataProvider` with the **merged** query list:
+
+1. Build queries with **`mergeLiveDataQueries(metricBindings, aiOpsDashboardProps)`** (map-level `DatacenterMetricBindings` plus dashboard `dataBindings` / `serviceDataBindings` when `liveData` is enabled).
+2. Pass **`skipDataProvider={true}`** on `AIOPsDashboard` so it does not create a second provider.
+
+`DatacenterView` can perform both steps when **`liveDataHost="datacenter"`** — see **dashstream-datacenter-view**.
+
 ---
 
 ## Full live-data dashboard example