@r0hitsharma/dashboard-kit 0.12.0-rohit-fork-ci.1

package/src/charting-interaction.test.ts

@@ -0,0 +1,95 @@
+/**
+ * @vitest-environment jsdom
+ *
+ * Has to render: the bug this guards against is about COMMIT ORDERING
+ * (does a value published this commit reflect a `keyMap` change made in
+ * that same commit?), which a pure-logic test over `aliasesFor` alone
+ * can't observe — React's actual effect-flush order is the thing under
+ * test, matching how `ThemeProvider.test.ts` justifies its own jsdom use.
+ */
+import {
+  DashboardInteractionProvider,
+  useDashboardInteraction,
+  type DashboardInteractionApi,
+} from '@r0hitsharma/charting';
+import { act, cleanup, render } from '@testing-library/react';
+import { createElement, useEffect, type MutableRefObject } from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  useChartingInteraction,
+  type InteractionKeyMap,
+} from './charting-interaction.js';
+import type { InteractionContextValue } from './interaction.js';
+
+afterEach(cleanup);
+
+const KEY_MAP_HIGHLIGHT: InteractionKeyMap = { myAlias: 'highlightedKey' };
+const KEY_MAP_TIME_RANGE: InteractionKeyMap = { myAlias: 'timeRange' };
+
+type Captured = {
+  chartApi: DashboardInteractionApi;
+  interaction: InteractionContextValue;
+};
+
+// Exposed to the test via a ref written inside an effect, not a module-scope
+// binding reassigned during render: the latter is exactly the pattern this
+// PR eliminates from the library code, so the test holds itself to it too.
+function Inner({
+  keyMap,
+  capturedRef,
+}: {
+  keyMap: InteractionKeyMap;
+  capturedRef: MutableRefObject<Captured | null>;
+}) {
+  const chartApi = useDashboardInteraction();
+  const { interaction, InteractionSync } = useChartingInteraction(keyMap);
+
+  useEffect(() => {
+    capturedRef.current = { chartApi, interaction };
+  });
+
+  return createElement(InteractionSync);
+}
+
+function App({
+  keyMap,
+  capturedRef,
+}: {
+  keyMap: InteractionKeyMap;
+  capturedRef: MutableRefObject<Captured | null>;
+}) {
+  return createElement(
+    DashboardInteractionProvider,
+    null,
+    createElement(Inner, { keyMap, capturedRef }),
+  );
+}
+
+describe('ChartingInteractionSync', () => {
+  it('publishes under a keyMap change immediately, in the same commit as a chart value change', () => {
+    const capturedRef: MutableRefObject<Captured | null> = { current: null };
+    const { rerender } = render(
+      createElement(App, { keyMap: KEY_MAP_HIGHLIGHT, capturedRef }),
+    );
+
+    act(() => {
+      capturedRef.current!.chartApi.setHighlightedKey('initial');
+    });
+    expect(capturedRef.current!.interaction.read('myAlias')).toBe('initial');
+
+    // Both happen in the SAME commit: `myAlias` is remapped from
+    // `highlightedKey` to `timeRange`, and `timeRange` itself changes. A
+    // stale (previous-commit) keyMap read would still resolve `myAlias` to
+    // `highlightedKey` here and miss the new value entirely.
+    act(() => {
+      capturedRef.current!.chartApi.setTimeRange({ start: 1, end: 2 });
+      rerender(createElement(App, { keyMap: KEY_MAP_TIME_RANGE, capturedRef }));
+    });
+
+    expect(capturedRef.current!.interaction.read('myAlias')).toEqual({
+      start: 1,
+      end: 2,
+    });
+  });
+});

package/src/charting-interaction.tsx

@@ -0,0 +1,199 @@
+import {
+  useDashboardInteraction,
+  type InteractionKey,
+  type TimeRange,
+} from '@r0hitsharma/charting';
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  type ReactElement,
+  type RefObject,
+} from 'react';
+
+import type { InteractionContextValue } from './interaction.js';
+
+/**
+ * Adapts a manifest's free-form interaction vocabulary onto charting's REAL
+ * per-key store (`DashboardInteractionProvider` / `useDashboardInteraction` /
+ * `useInteractionValue`), so a declarative dashboard cross-filters the same
+ * synced chart group a hand-built one would.
+ *
+ * The reconciliation this file owns: a manifest names keys in an FDC3-shaped
+ * vocabulary (`highlightedAsset`, `selectedTimeRange`) while charting's store
+ * is typed to `highlightedKey` / `timeRange` / `hoveredTimestamp`. The key map
+ * below is the single, declared place that translation happens — not a rename
+ * of either side. Consumers can pass their own map to extend the vocabulary.
+ *
+ * ── Why a bridge rather than calling `useDashboardInteraction` in each widget
+ * Charting's `DashboardInteractionContext` value changes identity on every
+ * pointer move (`hoveredTimestamp` lives in it), so anything that consumes it
+ * re-renders at hover frequency. {@link InteractionSync} is the SOLE consumer:
+ * a null-rendering component that republishes the mapped keys into a tiny
+ * per-key store. A widget that declared `interaction.reads: ['highlightedAsset']`
+ * then re-renders when the highlight changes and at no other time — matching
+ * the discipline of charting's own `useInteractionValue`.
+ */
+export type InteractionKeyMap = Record<string, InteractionKey>;
+
+/**
+ * Default manifest-key -> charting-key aliases. Native charting keys map to
+ * themselves so a manifest may also name them directly.
+ */
+export const DEFAULT_INTERACTION_KEY_MAP: InteractionKeyMap = {
+  highlightedAsset: 'highlightedKey',
+  highlightedKey: 'highlightedKey',
+  selectedTimeRange: 'timeRange',
+  timeRange: 'timeRange',
+  hoveredTimestamp: 'hoveredTimestamp',
+};
+
+export type ChartingInteraction = {
+  /** The generic surface to hand the renderer's `interaction` prop. */
+  interaction: InteractionContextValue;
+  /**
+   * Render ONCE inside a `SyncedChartGroup` / `DashboardInteractionProvider`.
+   * It renders nothing observable; it is the sole subscriber to the
+   * high-frequency charting context and republishes the mapped keys into the
+   * per-key store that {@link interaction} reads.
+   */
+  InteractionSync: () => ReactElement;
+};
+
+type ChartingInteractionSyncProps = {
+  keyMap: InteractionKeyMap;
+  writerRef: RefObject<(key: string, value: unknown) => void>;
+  publish: (key: string, value: unknown) => void;
+};
+
+/**
+ * Module-scope, not a closure created per `useChartingInteraction` call:
+ * hooks nested inside a `useMemo`/`useCallback` are ambiguous to the rules-of
+ * -hooks check (it can't tell they belong to a separate component render, not
+ * the enclosing hook's), so this needs to be a real, statically top-level
+ * component. Everything it needs comes in as props instead of a closure.
+ *
+ * `keyMap` is a plain prop, not a ref synced from a parent effect: React
+ * flushes child effects before parent effects, so a ref updated by
+ * `useChartingInteraction`'s own effect would still hold the PREVIOUS
+ * `keyMap` when this component's effects below run in the commit where it
+ * actually changed. A prop is simply current already.
+ */
+function ChartingInteractionSync({
+  keyMap,
+  writerRef,
+  publish,
+}: ChartingInteractionSyncProps): null {
+  const chart = useDashboardInteraction();
+
+  // Every manifest alias that resolves to `highlightedKey` gets the
+  // charting value republished under it; likewise for the other keys.
+  const aliasesFor = useCallback(
+    (chartingKey: InteractionKey): string[] =>
+      Object.entries(keyMap)
+        .filter(([, target]) => target === chartingKey)
+        .map(([alias]) => alias),
+    [keyMap],
+  );
+
+  useEffect(() => {
+    for (const alias of aliasesFor('highlightedKey')) {
+      publish(alias, chart.highlightedKey ?? undefined);
+    }
+  }, [chart.highlightedKey, publish, aliasesFor]);
+  useEffect(() => {
+    for (const alias of aliasesFor('timeRange')) {
+      publish(alias, chart.timeRange ?? undefined);
+    }
+  }, [chart.timeRange, publish, aliasesFor]);
+  useEffect(() => {
+    for (const alias of aliasesFor('hoveredTimestamp')) {
+      publish(alias, chart.hoveredTimestamp ?? undefined);
+    }
+  }, [chart.hoveredTimestamp, publish, aliasesFor]);
+
+  // The write side, held in a ref so `interaction.write` stays
+  // identity-stable for every consumer.
+  useEffect(() => {
+    writerRef.current = (key: string, value: unknown) => {
+      switch (keyMap[key]) {
+        case 'highlightedKey':
+          chart.setHighlightedKey(value == null ? null : String(value));
+          return;
+        case 'timeRange':
+          chart.setTimeRange((value as TimeRange | null) ?? null);
+          return;
+        case 'hoveredTimestamp':
+          chart.setHoveredTimestamp(value == null ? null : Number(value));
+          return;
+        default:
+          return;
+      }
+    };
+  }, [chart, keyMap, writerRef]);
+
+  return null;
+}
+
+/**
+ * Builds a charting-backed {@link InteractionContextValue}. Call it above a
+ * `SyncedChartGroup`, hand `interaction` to `DashboardRenderer`, and render
+ * `<InteractionSync />` inside the group.
+ */
+export function useChartingInteraction(
+  keyMap: InteractionKeyMap = DEFAULT_INTERACTION_KEY_MAP,
+): ChartingInteraction {
+  const valuesRef = useRef(new Map<string, unknown>());
+  const listenersRef = useRef(new Map<string, Set<() => void>>());
+  const writerRef = useRef<(key: string, value: unknown) => void>(() => {});
+
+  const read = useCallback((key: string) => valuesRef.current.get(key), []);
+
+  const write = useCallback((key: string, value: unknown) => {
+    writerRef.current(key, value);
+  }, []);
+
+  const subscribe = useCallback((key: string, onChange: () => void) => {
+    let listeners = listenersRef.current.get(key);
+    if (!listeners) {
+      listeners = new Set();
+      listenersRef.current.set(key, listeners);
+    }
+    listeners.add(onChange);
+    return () => {
+      listeners.delete(onChange);
+    };
+  }, []);
+
+  const publish = useCallback((key: string, value: unknown) => {
+    if (Object.is(valuesRef.current.get(key), value)) return;
+    valuesRef.current.set(key, value);
+    for (const listener of listenersRef.current.get(key) ?? []) listener();
+  }, []);
+
+  const interaction = useMemo<InteractionContextValue>(
+    () => ({ read, write, subscribe }),
+    [read, write, subscribe],
+  );
+
+  // A stable function identity, so React doesn't unmount/remount
+  // `ChartingInteractionSync` (and its charting subscription) across the
+  // dashboard's renders — as long as `keyMap` doesn't churn identity either.
+  // Pass a memoized `keyMap` (module-scoped, like the default, or your own
+  // `useMemo`); an inline object here remounts the subscription every render,
+  // the same discipline `usePlayback`'s `source` and `useDataTable`'s
+  // `columns` already require of their callers.
+  const InteractionSync = useCallback(
+    () => (
+      <ChartingInteractionSync
+        keyMap={keyMap}
+        writerRef={writerRef}
+        publish={publish}
+      />
+    ),
+    [publish, keyMap],
+  );
+
+  return { interaction, InteractionSync };
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+// The declarative-dashboard schema — the data contract a manifest conforms to.
+export type {
+  DashboardSpec,
+  DashboardDataSources,
+  DataBinding,
+  LayoutDirection,
+  LayoutNode,
+  SplitLayoutNode,
+  ThresholdRule,
+  ThresholdSeverity,
+  WidgetInteraction,
+  WidgetLayoutNode,
+  WidgetNode,
+  WidgetTableColumn,
+} from './schema.js';
+
+// The recursive renderer.
+export {
+  DashboardRenderer,
+  renderLayoutNode,
+  type DashboardRendererProps,
+} from './renderer.js';
+
+// The string -> component registry mechanism + the default generic adapters.
+export {
+  DEFAULT_REGISTRY,
+  UnknownWidget,
+  mergeRegistries,
+  type ComponentRegistry,
+  type RegistryComponent,
+  type RegistryComponentProps,
+} from './registry.js';
+
+// Structural + referential manifest validation, and the agent-exposure query.
+export {
+  collectAgentWritableKeys,
+  dashboardSpecSchema,
+  validateDashboardSpec,
+  type ManifestIssue,
+  type ManifestValidation,
+  type ValidateOptions,
+} from './validate.js';
+
+// The generic interaction surface: the local store + the per-key read hook.
+export {
+  useInteractionField,
+  useLocalInteraction,
+  type InteractionContextValue,
+} from './interaction.js';
+
+// The adapter onto charting's real per-key interaction store.
+export {
+  DEFAULT_INTERACTION_KEY_MAP,
+  useChartingInteraction,
+  type ChartingInteraction,
+  type InteractionKeyMap,
+} from './charting-interaction.js';

package/src/interaction.ts

@@ -0,0 +1,89 @@
+import {
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+
+/**
+ * The interaction surface a manifest's widgets read and write, addressed by
+ * the free-form string keys a `WidgetNode.interaction.reads`/`writes` names.
+ *
+ * This is deliberately a small, transport-agnostic `{read, write, subscribe}`
+ * contract rather than charting's concrete `DashboardInteractionApi` (which is
+ * typed to a fixed set of keys: `timeRange`, `hoveredTimestamp`, `filters`,
+ * `highlightedKey`). A manifest names its OWN vocabulary (`highlightedAsset`,
+ * `selectedTimeRange`, ...); {@link module:charting-interaction} is the adapter
+ * that maps that vocabulary onto charting's real per-key store. Keeping the
+ * engine's contract generic is what lets a consumer back interaction with
+ * charting, with their own store, or with the built-in local store below —
+ * without the engine caring which.
+ */
+export type InteractionContextValue = {
+  read: (key: string) => unknown;
+  write: (key: string, value: unknown) => void;
+  /**
+   * Optional per-key change subscription. When present, widgets reach values
+   * through {@link useInteractionField} rather than calling `read` during
+   * render, so only the widgets bound to a changed key re-render — the same
+   * hover-perf discipline charting's own per-key store enforces.
+   */
+  subscribe?: (key: string, onChange: () => void) => () => void;
+};
+
+type InteractionState = Record<string, unknown>;
+
+/**
+ * A self-contained interaction store backed by React state — the default the
+ * renderer falls back to when no `interaction` prop is supplied. Correct and
+ * cheap for a standalone manifest (a story, a preview) that isn't synced to a
+ * live chart group; for chart-synced interaction, pass the adapter from
+ * {@link module:charting-interaction} instead.
+ */
+export function useLocalInteraction(): InteractionContextValue {
+  const [, setState] = useState<InteractionState>({});
+  // Keep `read`/`write` identity-stable so the context value doesn't change
+  // for reasons other than a real state change.
+  const stateRef = useRef<InteractionState>({});
+
+  const read = useCallback((key: string) => stateRef.current[key], []);
+  const write = useCallback((key: string, value: unknown) => {
+    if (Object.is(stateRef.current[key], value)) return;
+    stateRef.current = { ...stateRef.current, [key]: value };
+    setState(stateRef.current);
+  }, []);
+
+  return useMemo(() => ({ read, write }), [read, write]);
+}
+
+/**
+ * Reads ONE interaction key, subscribing to just that key when the provider
+ * supports it. `key` may be `undefined` (a widget that declares no
+ * `interaction.reads`), in which case this is a no-op returning `undefined`.
+ *
+ * Named `useInteractionField` (not `useInteractionValue`) so a consumer file
+ * can import both this and charting's own `useInteractionValue` without a name
+ * collision.
+ */
+export function useInteractionField(
+  interaction: InteractionContextValue,
+  key: string | undefined,
+): unknown {
+  const { read, subscribe } = interaction;
+
+  const subscribeToKey = useCallback(
+    (onChange: () => void) => {
+      if (!key || !subscribe) return () => {};
+      return subscribe(key, onChange);
+    },
+    [key, subscribe],
+  );
+
+  const getSnapshot = useCallback(
+    () => (key ? read(key) : undefined),
+    [key, read],
+  );
+
+  return useSyncExternalStore(subscribeToKey, getSnapshot, getSnapshot);
+}