@graphein/react 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sachin Patney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @graphein/react
+
+> The React wrapper for [Graphein](https://github.com/spatney/graphein) — a beautiful,
+> high-performance, **agent-first** data visualization library.
+
+Install alongside `react` (18+, a peer dependency):
+
+```bash
+npm install @graphein/react react
+```
+
+```tsx
+import { Chart } from '@graphein/react';
+import type { ChartSpec } from 'graphein';
+
+const spec: ChartSpec = {
+  type: 'bar',
+  data: [
+    { quarter: 'Q1', revenue: 240 },
+    { quarter: 'Q2', revenue: 310 },
+    { quarter: 'Q3', revenue: 280 },
+    { quarter: 'Q4', revenue: 360 },
+  ],
+  encoding: { x: { field: 'quarter' }, y: { field: 'revenue' } },
+};
+
+export function Dashboard() {
+  return (
+    <div style={{ height: 360 }}>
+      <Chart spec={spec} />
+    </div>
+  );
+}
+```
+
+`<Chart spec={…} />` renders into a fill-by-default container; pass a new `spec`
+to update in place, and it tears down on unmount. For headless control over your
+own element, use the `useChart(spec)` hook (returns a ref to attach).
+
+## Documentation
+
+- [README](https://github.com/spatney/graphein#readme)
+- [Agent Guide](https://github.com/spatney/graphein/blob/main/docs/agent-guide.md)
+- [Spec Reference](https://github.com/spatney/graphein/blob/main/docs/spec-reference.md)
+
+MIT © Sachin Patney

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+import { RefObject, CSSProperties, ReactElement } from 'react';
+import { ChartInstance, SelectionStore, SelectionChangeListener, ChartSpec, DashboardInstance, DashboardSpec, SelectionValue } from 'graphein';
+export { ChartInstance, ChartSpec, DashboardInstance, DashboardSpec, SelectionChangeListener, SelectionStore, SelectionValue, createSelectionStore } from 'graphein';
+
+interface UseChartOptions {
+    /** Called with the live instance after each mount and update. */
+    onReady?: (instance: ChartInstance) => void;
+    /**
+     * A shared selection bus. Pass the same store to several charts (or a
+     * dashboard) to link them — cross-highlight / cross-filter. Should be stable
+     * across renders (e.g. `useMemo(() => createSelectionStore(), [])`); changing
+     * its identity remounts the chart.
+     */
+    store?: SelectionStore;
+    /** Called whenever any selection this chart is bound to changes. */
+    onSelectionChange?: SelectionChangeListener;
+}
+/**
+ * Mount an Graphein chart into a DOM node and keep it in sync with `spec`.
+ *
+ * Returns a ref to attach to the container element. The chart is created on
+ * mount, re-rendered via `instance.update()` whenever `spec` changes identity,
+ * and torn down on unmount. The effect lifecycle is StrictMode-safe (double
+ * mount → destroy → mount produces no leaked instances or duplicate renders).
+ *
+ * ```tsx
+ * const ref = useChart(spec);
+ * return <div ref={ref} style={{ width: '100%', height: 360 }} />;
+ * ```
+ */
+declare function useChart<T extends HTMLElement = HTMLDivElement>(spec: ChartSpec, options?: UseChartOptions): RefObject<T | null>;
+
+interface ChartProps extends UseChartOptions {
+    /** The Graphein chart spec to render. */
+    spec: ChartSpec;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Declarative React wrapper around the Graphein core runtime.
+ *
+ * Renders a container `<div>` that fills its parent (override via `style`) and
+ * draws `spec` into it. Pass a new `spec` to update; unmounting tears the chart
+ * down. Give the parent an explicit size for best results.
+ *
+ * ```tsx
+ * <div style={{ height: 360 }}>
+ *   <Chart spec={{ type: 'line', data, encoding: { x, y } }} />
+ * </div>
+ * ```
+ */
+declare function Chart({ spec, className, style, ...options }: ChartProps): ReactElement;
+
+interface UseDashboardOptions {
+    /** Called with the live instance after each mount and update. */
+    onReady?: (instance: DashboardInstance) => void;
+    /**
+     * A shared selection bus. Omit to let the dashboard own one internally; pass
+     * one (stable across renders) to drive it from React via {@link useSelection}
+     * or to link it with standalone charts. Changing its identity remounts.
+     */
+    store?: SelectionStore;
+    /** Called whenever any selection in the dashboard changes. */
+    onSelectionChange?: SelectionChangeListener;
+}
+/**
+ * Mount an Graphein dashboard into a DOM node and keep it in sync with `spec`.
+ *
+ * Mirrors {@link useChart}: created on mount, updated in place when `spec`
+ * changes identity, torn down on unmount, StrictMode-safe.
+ *
+ * ```tsx
+ * const ref = useDashboard(dashboardSpec);
+ * return <div ref={ref} style={{ width: '100%' }} />;
+ * ```
+ */
+declare function useDashboard<T extends HTMLElement = HTMLDivElement>(spec: DashboardSpec, options?: UseDashboardOptions): RefObject<T | null>;
+
+interface DashboardProps extends UseDashboardOptions {
+    /** The Graphein dashboard spec to render. */
+    spec: DashboardSpec;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Declarative React wrapper around the Graphein dashboard runtime.
+ *
+ * Renders a container `<div>` (full width by default; height comes from the
+ * dashboard's grid rows) and draws `spec` into it. Pass a new `spec` to update;
+ * unmounting tears it down. Auto-wires cross-interaction unless `spec` opts out.
+ *
+ * ```tsx
+ * <Dashboard spec={{ type: 'dashboard', data, views, interactions: 'auto' }} />
+ * ```
+ */
+declare function Dashboard({ spec, className, style, ...options }: DashboardProps): ReactElement;
+
+/** Anything that exposes a selection bus: a store, or a chart/dashboard instance. */
+type SelectionSource = SelectionStore | {
+    store: SelectionStore;
+} | null | undefined;
+/**
+ * Read and write a named selection as React state.
+ *
+ * Pass a shared {@link SelectionStore} (or a chart/dashboard instance, which
+ * exposes one as `.store`) plus the param name. Returns the current value and a
+ * setter that publishes to the bus — driving cross-highlight / cross-filter
+ * across every visual bound to that store.
+ *
+ * ```tsx
+ * const store = useMemo(() => createSelectionStore(), []);
+ * const [region, setRegion] = useSelection(store, 'region');
+ * // …
+ * <Dashboard spec={spec} store={store} />
+ * <button onClick={() => setRegion({ kind: 'set', field: 'region', values: ['West'] })}>
+ *   West
+ * </button>
+ * ```
+ */
+declare function useSelection(source: SelectionSource, name: string): [SelectionValue | null, (value: SelectionValue | null) => void];
+
+/**
+ * @graphein/react — a thin React wrapper around the `graphein` runtime.
+ *
+ * `<Chart spec={…} />` for a single chart or `<Dashboard spec={…} />` for a
+ * cross-interacting page; the `useChart` / `useDashboard` hooks give headless
+ * control over your own container, and `useSelection` reads/writes a selection
+ * as React state. Core spec/instance types are re-exported for convenience.
+ */
+
+declare const VERSION = "0.0.0";
+
+export { Chart, type ChartProps, Dashboard, type DashboardProps, type SelectionSource, type UseChartOptions, type UseDashboardOptions, VERSION, useChart, useDashboard, useSelection };

package/dist/index.js

@@ -0,0 +1,172 @@
+// src/Chart.ts
+import { createElement } from "react";
+
+// src/useChart.ts
+import { useEffect, useRef } from "react";
+import {
+  render
+} from "graphein";
+function useChart(spec, options = {}) {
+  const ref = useRef(null);
+  const instanceRef = useRef(null);
+  const specRef = useRef(spec);
+  specRef.current = spec;
+  const onReadyRef = useRef(options.onReady);
+  onReadyRef.current = options.onReady;
+  const onSelectionChangeRef = useRef(options.onSelectionChange);
+  onSelectionChangeRef.current = options.onSelectionChange;
+  const storeRef = useRef(options.store);
+  storeRef.current = options.store;
+  const skipNextUpdate = useRef(true);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const instance = render(
+      el,
+      specRef.current,
+      storeRef.current ? { store: storeRef.current } : void 0
+    );
+    instanceRef.current = instance;
+    const offSelection = instance.on(
+      "selectionchange",
+      (name, value) => onSelectionChangeRef.current?.(name, value)
+    );
+    skipNextUpdate.current = true;
+    onReadyRef.current?.(instance);
+    return () => {
+      offSelection();
+      instance.destroy();
+      instanceRef.current = null;
+    };
+  }, [options.store]);
+  useEffect(() => {
+    if (skipNextUpdate.current) {
+      skipNextUpdate.current = false;
+      return;
+    }
+    const instance = instanceRef.current;
+    if (!instance) return;
+    instance.update(spec);
+    onReadyRef.current?.(instance);
+  }, [spec]);
+  return ref;
+}
+
+// src/Chart.ts
+var FILL = { width: "100%", height: "100%" };
+function Chart({ spec, className, style, ...options }) {
+  const ref = useChart(spec, options);
+  return createElement("div", {
+    ref,
+    className,
+    style: style ? { ...FILL, ...style } : FILL
+  });
+}
+
+// src/Dashboard.ts
+import { createElement as createElement2 } from "react";
+
+// src/useDashboard.ts
+import { useEffect as useEffect2, useRef as useRef2 } from "react";
+import {
+  renderDashboard
+} from "graphein";
+function useDashboard(spec, options = {}) {
+  const ref = useRef2(null);
+  const instanceRef = useRef2(null);
+  const specRef = useRef2(spec);
+  specRef.current = spec;
+  const onReadyRef = useRef2(options.onReady);
+  onReadyRef.current = options.onReady;
+  const onSelectionChangeRef = useRef2(options.onSelectionChange);
+  onSelectionChangeRef.current = options.onSelectionChange;
+  const storeRef = useRef2(options.store);
+  storeRef.current = options.store;
+  const skipNextUpdate = useRef2(true);
+  useEffect2(() => {
+    const el = ref.current;
+    if (!el) return;
+    const instance = renderDashboard(
+      el,
+      specRef.current,
+      storeRef.current ? { store: storeRef.current } : void 0
+    );
+    instanceRef.current = instance;
+    const offSelection = instance.on(
+      "selectionchange",
+      (name, value) => onSelectionChangeRef.current?.(name, value)
+    );
+    skipNextUpdate.current = true;
+    onReadyRef.current?.(instance);
+    return () => {
+      offSelection();
+      instance.destroy();
+      instanceRef.current = null;
+    };
+  }, [options.store]);
+  useEffect2(() => {
+    if (skipNextUpdate.current) {
+      skipNextUpdate.current = false;
+      return;
+    }
+    const instance = instanceRef.current;
+    if (!instance) return;
+    instance.update(spec);
+    onReadyRef.current?.(instance);
+  }, [spec]);
+  return ref;
+}
+
+// src/Dashboard.ts
+var FILL2 = { width: "100%" };
+function Dashboard({ spec, className, style, ...options }) {
+  const ref = useDashboard(spec, options);
+  return createElement2("div", {
+    ref,
+    className,
+    style: style ? { ...FILL2, ...style } : FILL2
+  });
+}
+
+// src/useSelection.ts
+import { useCallback, useEffect as useEffect3, useState } from "react";
+function resolveStore(source) {
+  if (!source) return null;
+  return "store" in source ? source.store : source;
+}
+function useSelection(source, name) {
+  const store = resolveStore(source);
+  const [value, setValue] = useState(() => store?.get(name) ?? null);
+  useEffect3(() => {
+    if (!store) {
+      setValue(null);
+      return;
+    }
+    setValue(store.get(name) ?? null);
+    const unsubscribe = store.subscribe((changed, next) => {
+      if (changed === name) setValue(next);
+    });
+    return unsubscribe;
+  }, [store, name]);
+  const set = useCallback(
+    (next) => {
+      store?.set(name, next ?? null);
+    },
+    [store, name]
+  );
+  return [value, set];
+}
+
+// src/index.ts
+import { createSelectionStore } from "graphein";
+var VERSION = "0.0.0";
+export {
+  Chart,
+  Dashboard,
+  VERSION,
+  createSelectionStore,
+  useChart,
+  useDashboard,
+  useSelection
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/Chart.ts","../src/useChart.ts","../src/Dashboard.ts","../src/useDashboard.ts","../src/useSelection.ts","../src/index.ts"],"sourcesContent":["import { createElement, type CSSProperties, type ReactElement } from 'react';\r\nimport type { ChartSpec } from 'graphein';\r\nimport { useChart, type UseChartOptions } from './useChart';\r\n\r\nexport interface ChartProps extends UseChartOptions {\r\n  /** The Graphein chart spec to render. */\r\n  spec: ChartSpec;\r\n  className?: string;\r\n  style?: CSSProperties;\r\n}\r\n\r\nconst FILL: CSSProperties = { width: '100%', height: '100%' };\r\n\r\n/**\r\n * Declarative React wrapper around the Graphein core runtime.\r\n *\r\n * Renders a container `<div>` that fills its parent (override via `style`) and\r\n * draws `spec` into it. Pass a new `spec` to update; unmounting tears the chart\r\n * down. Give the parent an explicit size for best results.\r\n *\r\n * ```tsx\r\n * <div style={{ height: 360 }}>\r\n *   <Chart spec={{ type: 'line', data, encoding: { x, y } }} />\r\n * </div>\r\n * ```\r\n */\r\nexport function Chart({ spec, className, style, ...options }: ChartProps): ReactElement {\r\n  const ref = useChart<HTMLDivElement>(spec, options);\r\n  return createElement('div', {\r\n    ref,\r\n    className,\r\n    style: style ? { ...FILL, ...style } : FILL,\r\n  });\r\n}\r\n","import { useEffect, useRef, type RefObject } from 'react';\r\nimport {\r\n  render,\r\n  type ChartInstance,\r\n  type ChartSpec,\r\n  type SelectionChangeListener,\r\n  type SelectionStore,\r\n} from 'graphein';\r\n\r\nexport interface UseChartOptions {\r\n  /** Called with the live instance after each mount and update. */\r\n  onReady?: (instance: ChartInstance) => void;\r\n  /**\r\n   * A shared selection bus. Pass the same store to several charts (or a\r\n   * dashboard) to link them — cross-highlight / cross-filter. Should be stable\r\n   * across renders (e.g. `useMemo(() => createSelectionStore(), [])`); changing\r\n   * its identity remounts the chart.\r\n   */\r\n  store?: SelectionStore;\r\n  /** Called whenever any selection this chart is bound to changes. */\r\n  onSelectionChange?: SelectionChangeListener;\r\n}\r\n\r\n/**\r\n * Mount an Graphein chart into a DOM node and keep it in sync with `spec`.\r\n *\r\n * Returns a ref to attach to the container element. The chart is created on\r\n * mount, re-rendered via `instance.update()` whenever `spec` changes identity,\r\n * and torn down on unmount. The effect lifecycle is StrictMode-safe (double\r\n * mount → destroy → mount produces no leaked instances or duplicate renders).\r\n *\r\n * ```tsx\r\n * const ref = useChart(spec);\r\n * return <div ref={ref} style={{ width: '100%', height: 360 }} />;\r\n * ```\r\n */\r\nexport function useChart<T extends HTMLElement = HTMLDivElement>(\r\n  spec: ChartSpec,\r\n  options: UseChartOptions = {},\r\n): RefObject<T | null> {\r\n  const ref = useRef<T | null>(null);\r\n  const instanceRef = useRef<ChartInstance | null>(null);\r\n  // Hold the latest spec / callback in refs so the mount effect (which runs\r\n  // once) always reads current values without re-subscribing.\r\n  const specRef = useRef(spec);\r\n  specRef.current = spec;\r\n  const onReadyRef = useRef(options.onReady);\r\n  onReadyRef.current = options.onReady;\r\n  const onSelectionChangeRef = useRef(options.onSelectionChange);\r\n  onSelectionChangeRef.current = options.onSelectionChange;\r\n  const storeRef = useRef(options.store);\r\n  storeRef.current = options.store;\r\n  const skipNextUpdate = useRef(true);\r\n\r\n  useEffect(() => {\r\n    const el = ref.current;\r\n    if (!el) return;\r\n    const instance = render(\r\n      el,\r\n      specRef.current,\r\n      storeRef.current ? { store: storeRef.current } : undefined,\r\n    );\r\n    instanceRef.current = instance;\r\n    const offSelection = instance.on('selectionchange', (name, value) =>\r\n      onSelectionChangeRef.current?.(name, value),\r\n    );\r\n    // The update effect runs once right after this on mount; skip that pass so\r\n    // we don't redundantly re-render the freshly created chart.\r\n    skipNextUpdate.current = true;\r\n    onReadyRef.current?.(instance);\r\n    return () => {\r\n      offSelection();\r\n      instance.destroy();\r\n      instanceRef.current = null;\r\n    };\r\n  }, [options.store]);\r\n\r\n  useEffect(() => {\r\n    if (skipNextUpdate.current) {\r\n      skipNextUpdate.current = false;\r\n      return;\r\n    }\r\n    const instance = instanceRef.current;\r\n    if (!instance) return;\r\n    instance.update(spec);\r\n    onReadyRef.current?.(instance);\r\n  }, [spec]);\r\n\r\n  return ref;\r\n}\r\n","import { createElement, type CSSProperties, type ReactElement } from 'react';\r\nimport type { DashboardSpec } from 'graphein';\r\nimport { useDashboard, type UseDashboardOptions } from './useDashboard';\r\n\r\nexport interface DashboardProps extends UseDashboardOptions {\r\n  /** The Graphein dashboard spec to render. */\r\n  spec: DashboardSpec;\r\n  className?: string;\r\n  style?: CSSProperties;\r\n}\r\n\r\nconst FILL: CSSProperties = { width: '100%' };\r\n\r\n/**\r\n * Declarative React wrapper around the Graphein dashboard runtime.\r\n *\r\n * Renders a container `<div>` (full width by default; height comes from the\r\n * dashboard's grid rows) and draws `spec` into it. Pass a new `spec` to update;\r\n * unmounting tears it down. Auto-wires cross-interaction unless `spec` opts out.\r\n *\r\n * ```tsx\r\n * <Dashboard spec={{ type: 'dashboard', data, views, interactions: 'auto' }} />\r\n * ```\r\n */\r\nexport function Dashboard({ spec, className, style, ...options }: DashboardProps): ReactElement {\r\n  const ref = useDashboard<HTMLDivElement>(spec, options);\r\n  return createElement('div', {\r\n    ref,\r\n    className,\r\n    style: style ? { ...FILL, ...style } : FILL,\r\n  });\r\n}\r\n","import { useEffect, useRef, type RefObject } from 'react';\r\nimport {\r\n  renderDashboard,\r\n  type DashboardInstance,\r\n  type DashboardSpec,\r\n  type SelectionChangeListener,\r\n  type SelectionStore,\r\n} from 'graphein';\r\n\r\nexport interface UseDashboardOptions {\r\n  /** Called with the live instance after each mount and update. */\r\n  onReady?: (instance: DashboardInstance) => void;\r\n  /**\r\n   * A shared selection bus. Omit to let the dashboard own one internally; pass\r\n   * one (stable across renders) to drive it from React via {@link useSelection}\r\n   * or to link it with standalone charts. Changing its identity remounts.\r\n   */\r\n  store?: SelectionStore;\r\n  /** Called whenever any selection in the dashboard changes. */\r\n  onSelectionChange?: SelectionChangeListener;\r\n}\r\n\r\n/**\r\n * Mount an Graphein dashboard into a DOM node and keep it in sync with `spec`.\r\n *\r\n * Mirrors {@link useChart}: created on mount, updated in place when `spec`\r\n * changes identity, torn down on unmount, StrictMode-safe.\r\n *\r\n * ```tsx\r\n * const ref = useDashboard(dashboardSpec);\r\n * return <div ref={ref} style={{ width: '100%' }} />;\r\n * ```\r\n */\r\nexport function useDashboard<T extends HTMLElement = HTMLDivElement>(\r\n  spec: DashboardSpec,\r\n  options: UseDashboardOptions = {},\r\n): RefObject<T | null> {\r\n  const ref = useRef<T | null>(null);\r\n  const instanceRef = useRef<DashboardInstance | null>(null);\r\n  const specRef = useRef(spec);\r\n  specRef.current = spec;\r\n  const onReadyRef = useRef(options.onReady);\r\n  onReadyRef.current = options.onReady;\r\n  const onSelectionChangeRef = useRef(options.onSelectionChange);\r\n  onSelectionChangeRef.current = options.onSelectionChange;\r\n  const storeRef = useRef(options.store);\r\n  storeRef.current = options.store;\r\n  const skipNextUpdate = useRef(true);\r\n\r\n  useEffect(() => {\r\n    const el = ref.current;\r\n    if (!el) return;\r\n    const instance = renderDashboard(\r\n      el,\r\n      specRef.current,\r\n      storeRef.current ? { store: storeRef.current } : undefined,\r\n    );\r\n    instanceRef.current = instance;\r\n    const offSelection = instance.on('selectionchange', (name, value) =>\r\n      onSelectionChangeRef.current?.(name, value),\r\n    );\r\n    skipNextUpdate.current = true;\r\n    onReadyRef.current?.(instance);\r\n    return () => {\r\n      offSelection();\r\n      instance.destroy();\r\n      instanceRef.current = null;\r\n    };\r\n  }, [options.store]);\r\n\r\n  useEffect(() => {\r\n    if (skipNextUpdate.current) {\r\n      skipNextUpdate.current = false;\r\n      return;\r\n    }\r\n    const instance = instanceRef.current;\r\n    if (!instance) return;\r\n    instance.update(spec);\r\n    onReadyRef.current?.(instance);\r\n  }, [spec]);\r\n\r\n  return ref;\r\n}\r\n","import { useCallback, useEffect, useState } from 'react';\r\nimport type { SelectionStore, SelectionValue } from 'graphein';\r\n\r\n/** Anything that exposes a selection bus: a store, or a chart/dashboard instance. */\r\nexport type SelectionSource =\r\n  | SelectionStore\r\n  | { store: SelectionStore }\r\n  | null\r\n  | undefined;\r\n\r\nfunction resolveStore(source: SelectionSource): SelectionStore | null {\r\n  if (!source) return null;\r\n  return 'store' in source ? source.store : source;\r\n}\r\n\r\n/**\r\n * Read and write a named selection as React state.\r\n *\r\n * Pass a shared {@link SelectionStore} (or a chart/dashboard instance, which\r\n * exposes one as `.store`) plus the param name. Returns the current value and a\r\n * setter that publishes to the bus — driving cross-highlight / cross-filter\r\n * across every visual bound to that store.\r\n *\r\n * ```tsx\r\n * const store = useMemo(() => createSelectionStore(), []);\r\n * const [region, setRegion] = useSelection(store, 'region');\r\n * // …\r\n * <Dashboard spec={spec} store={store} />\r\n * <button onClick={() => setRegion({ kind: 'set', field: 'region', values: ['West'] })}>\r\n *   West\r\n * </button>\r\n * ```\r\n */\r\nexport function useSelection(\r\n  source: SelectionSource,\r\n  name: string,\r\n): [SelectionValue | null, (value: SelectionValue | null) => void] {\r\n  const store = resolveStore(source);\r\n  const [value, setValue] = useState<SelectionValue | null>(() => store?.get(name) ?? null);\r\n\r\n  useEffect(() => {\r\n    if (!store) {\r\n      setValue(null);\r\n      return;\r\n    }\r\n    setValue(store.get(name) ?? null);\r\n    const unsubscribe = store.subscribe((changed, next) => {\r\n      if (changed === name) setValue(next);\r\n    });\r\n    return unsubscribe;\r\n  }, [store, name]);\r\n\r\n  const set = useCallback(\r\n    (next: SelectionValue | null) => {\r\n      store?.set(name, next ?? null);\r\n    },\r\n    [store, name],\r\n  );\r\n\r\n  return [value, set];\r\n}\r\n","/**\r\n * @graphein/react — a thin React wrapper around the `graphein` runtime.\r\n *\r\n * `<Chart spec={…} />` for a single chart or `<Dashboard spec={…} />` for a\r\n * cross-interacting page; the `useChart` / `useDashboard` hooks give headless\r\n * control over your own container, and `useSelection` reads/writes a selection\r\n * as React state. Core spec/instance types are re-exported for convenience.\r\n */\r\nexport { Chart, type ChartProps } from './Chart';\r\nexport { useChart, type UseChartOptions } from './useChart';\r\nexport { Dashboard, type DashboardProps } from './Dashboard';\r\nexport { useDashboard, type UseDashboardOptions } from './useDashboard';\r\nexport { useSelection, type SelectionSource } from './useSelection';\r\nexport { createSelectionStore } from 'graphein';\r\nexport type {\r\n  ChartSpec,\r\n  ChartInstance,\r\n  DashboardSpec,\r\n  DashboardInstance,\r\n  SelectionStore,\r\n  SelectionValue,\r\n  SelectionChangeListener,\r\n} from 'graphein';\r\n\r\nexport const VERSION = '0.0.0';\r\n"],"mappings":"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","names":["createElement","useEffect","useRef","FILL","createElement","useEffect"]}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@graphein/react",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Graphein React wrapper — declarative <Chart spec={...} /> for the Graphein visualization engine.",
+  "license": "MIT",
+  "author": "Sachin Patney <sachin.patney@gmail.com>",
+  "homepage": "https://github.com/spatney/graphein/tree/main/packages/react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spatney/graphein.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/spatney/graphein/issues"
+  },
+  "keywords": [
+    "react",
+    "visualization",
+    "charts",
+    "dataviz",
+    "graphein",
+    "agent",
+    "declarative"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepack": "tsup"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "graphein": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  }
+}