equilibria-react 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# equilibria-react
+
+React components for the [Equilibria Engine](https://github.com/Kinetonomics-Equilibria/KGJS-Equilibria) — styled, drop-in chart cards with lifecycle management, error handling, and responsive sizing.
+
+## Installation
+
+```bash
+npm install equilibria-react equilibria-engine-js
+```
+
+### Required CSS
+
+Import the engine and component styles in your app's entry point:
+
+```tsx
+import "equilibria-engine-js/dist/style.css";  // Engine theme
+import "katex/dist/katex.min.css";              // Math typography
+import "equilibria-react/dist/style.css";       // Card styles
+```
+
+## Quick Start
+
+### `<EquilibriaCard />` — Drop-in styled card
+
+```tsx
+import { EquilibriaCard } from 'equilibria-react';
+
+const config = {
+  params: [{ name: "price", value: 10, min: 0, max: 20, round: 0.1 }],
+  calcs: { revenue: "price * 5" },
+  layout: {
+    OneGraph: {
+      graph: {
+        xAxis: { title: "Quantity", min: 0, max: 20 },
+        yAxis: { title: "Price ($)", min: 0, max: 20 },
+        objects: [
+          { type: "Point", def: { x: "10", y: "price", color: "blue", draggable: true } }
+        ]
+      }
+    }
+  }
+};
+
+function App() {
+  return (
+    <EquilibriaCard
+      config={config}
+      title="Interactive Pricing"
+      description="Drag the point to adjust price"
+      variant="elevated"
+    />
+  );
+}
+```
+
+### `<EquilibriaChart />` — Minimal (no card chrome)
+
+```tsx
+import { EquilibriaChart } from 'equilibria-react';
+
+function App() {
+  return (
+    <EquilibriaChart
+      config={config}
+      style={{ width: '100%', maxWidth: 600 }}
+      onReady={() => console.log('Chart rendered')}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+### `useEquilibria()` — Full control hook
+
+```tsx
+import { useEquilibria } from 'equilibria-react';
+
+function CustomChart({ config }) {
+  const { containerRef, isReady, error, retry } = useEquilibria(config);
+
+  return (
+    <div>
+      {!isReady && !error && <p>Loading...</p>}
+      {error && <button onClick={retry}>Retry</button>}
+      <div ref={containerRef} style={{ width: '100%' }} />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### `<EquilibriaCard />` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `object` | **required** | Engine config (JSON/parsed YAML) |
+| `options` | `KineticGraphOptions` | `{}` | Engine constructor options |
+| `title` | `string` | — | Card title |
+| `description` | `string` | — | Subtitle text |
+| `footer` | `ReactNode` | — | Footer content slot |
+| `variant` | `'elevated' \| 'outlined' \| 'flat'` | `'elevated'` | Visual style |
+| `loading` | `boolean` | auto | Override loading state |
+| `errorFallback` | `ReactNode \| (err) => ReactNode` | built-in | Custom error UI |
+| `className` | `string` | — | Additional CSS class |
+| `style` | `CSSProperties` | — | Inline styles |
+| `onError` | `(err) => void` | — | Error callback |
+| `onReady` | `() => void` | — | Fires after mount |
+
+### `<EquilibriaChart />` Props
+
+All of the above **except** `title`, `description`, `footer`, `variant`, `loading`, and `errorFallback`.
+
+## Theming
+
+Override CSS custom properties to match your design system:
+
+```css
+:root {
+  --eq-card-bg: #1a1a2e;
+  --eq-card-border: #2d2d44;
+  --eq-card-radius: 16px;
+  --eq-card-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
+  --eq-title-color: #e0e0e0;
+  --eq-description-color: #9090a0;
+  --eq-error-bg: #2d1b1b;
+  --eq-error-color: #ff6b6b;
+  --eq-skeleton-color: #2d2d44;
+}
+```
+
+These properties are scoped to the `equilibria-react` components and won't affect the engine's own `--kg-*` variables.
+
+## License
+
+MIT

package/dist/EquilibriaCard.d.ts

@@ -0,0 +1,9 @@
+import { EquilibriaCardProps } from './types';
+
+/**
+ * Styled card component wrapping the Equilibria engine.
+ * Includes title, description, loading skeleton, error state, and footer slot.
+ *
+ * This is the recommended "drop-in" component for rendering charts.
+ */
+export declare function EquilibriaCard({ config, options, className, style, onError: _onError, onReady: _onReady, title, description, footer, loading: loadingOverride, errorFallback, variant, }: EquilibriaCardProps): import("react/jsx-runtime").JSX.Element;

package/dist/EquilibriaChart.d.ts

@@ -0,0 +1,11 @@
+import { EquilibriaChartProps } from './types';
+
+/**
+ * Minimal chart component — mounts the Equilibria engine into a div container
+ * with no additional chrome. Use this when you want full control over the
+ * surrounding UI and only need the graph itself.
+ *
+ * For a styled wrapper with title, description, loading state, and error
+ * handling, use `<EquilibriaCard />` instead.
+ */
+export declare function EquilibriaChart({ config, options, className, style, onError, onReady, }: EquilibriaChartProps): import("react/jsx-runtime").JSX.Element;

package/dist/equilibria-react.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});require("equilibria-engine-js/dist/style.css");require("katex/dist/katex.min.css");const n=require("react/jsx-runtime"),a=require("react"),N=require("equilibria-engine-js");function y(d,m){const h=a.useRef(null),s=a.useRef(null),[f,i]=a.useState(null),[u,t]=a.useState(null),[l,o]=a.useState(!1),c=a.useCallback(()=>{if(s.current){try{s.current.destroy()}catch{}s.current=null,i(null),o(!1)}t(null);const k=h.current;if(!(!k||!d))try{const r=new N.KineticGraph(d,m);r.on("error",_=>{t(_ instanceof Error?_:new Error(String(_)))}),r.mount(k),s.current=r,i(r),o(!0)}catch(r){const _=r instanceof Error?r:new Error(String(r));t(_),o(!1)}},[d,m]);a.useEffect(()=>(c(),()=>{if(s.current){try{s.current.destroy()}catch{}s.current=null,i(null),o(!1)}}),[c]);const C=a.useCallback(()=>{c()},[c]);return{containerRef:h,instance:f,error:u,isReady:l,retry:C}}const g="_chartContainer_k1m9p_61",x="_chartContainerLoading_k1m9p_69",q="_chartContainerReady_k1m9p_75",v="_card_k1m9p_83",b="_header_k1m9p_130",S="_title_k1m9p_134",B="_description_k1m9p_144",I="_chartArea_k1m9p_153",L="_skeleton_k1m9p_163",M="_skeletonHidden_k1m9p_175",P="_skeletonPulse_k1m9p_180",$="_errorContainer_k1m9p_202",A="_errorIcon_k1m9p_226",H="_errorMessage_k1m9p_233",w="_retryButton_k1m9p_243",G="_footer_k1m9p_271",e={chartContainer:g,chartContainerLoading:x,chartContainerReady:q,card:v,"card--elevated":"_card--elevated_k1m9p_98","card--outlined":"_card--outlined_k1m9p_106","card--flat":"_card--flat_k1m9p_117",header:b,title:S,description:B,chartArea:I,skeleton:L,skeletonHidden:M,skeletonPulse:P,"eq-shimmer":"_eq-shimmer_k1m9p_1",errorContainer:$,"fade-in":"_fade-in_k1m9p_1",errorIcon:A,errorMessage:H,retryButton:w,footer:G};function J({config:d,options:m,className:h,style:s,onError:f,onReady:i}){const{containerRef:u,error:t,isReady:l}=y(d,m);a.useEffect(()=>{t&&f&&f(t)},[t,f]),a.useEffect(()=>{l&&i&&i()},[l,i]);const o=[e.chartContainer,!l||t?e.chartContainerLoading:e.chartContainerReady,h].filter(Boolean).join(" ");return n.jsx("div",{ref:u,className:o,style:s})}function K({config:d,options:m,className:h,style:s,onError:f,onReady:i,title:u,description:t,footer:l,loading:o,errorFallback:c,variant:C="elevated"}){const{containerRef:k,error:r,isReady:_,retry:R}=y(d,m),j=o!==void 0?o:!_&&!r,E=[e.card,e[`card--${C}`],h].filter(Boolean).join(" ");let p=null;return r&&(c?p=typeof c=="function"?c(r):c:p=n.jsxs("div",{className:e.errorContainer,children:[n.jsx("div",{className:e.errorIcon,children:"⚠"}),n.jsx("p",{className:e.errorMessage,children:r.message||"Failed to render chart"}),n.jsx("button",{className:e.retryButton,onClick:R,children:"Retry"})]})),n.jsxs("div",{className:E,style:s,children:[(u||t)&&n.jsxs("div",{className:e.header,children:[u&&n.jsx("h3",{className:e.title,children:u}),t&&n.jsx("p",{className:e.description,children:t})]}),n.jsxs("div",{className:e.chartArea,children:[n.jsx("div",{className:`${e.skeleton} ${!j||r?e.skeletonHidden:""}`,children:n.jsx("div",{className:e.skeletonPulse})}),r&&p,n.jsx("div",{ref:k,className:`${e.chartContainer} ${j||r?e.chartContainerLoading:e.chartContainerReady}`})]}),l&&n.jsx("div",{className:e.footer,children:l})]})}exports.EquilibriaCard=K;exports.EquilibriaChart=J;exports.useEquilibria=y;

package/dist/equilibria-react.es.js

@@ -0,0 +1,140 @@
+import "equilibria-engine-js/dist/style.css";
+import "katex/dist/katex.min.css";
+import { jsx as a, jsxs as k } from "react/jsx-runtime";
+import { useRef as v, useState as y, useCallback as g, useEffect as N } from "react";
+import { KineticGraph as L } from "equilibria-engine-js";
+function E(l, m) {
+  const u = v(null), t = v(null), [h, c] = y(null), [d, n] = y(null), [i, o] = y(!1), s = g(() => {
+    if (t.current) {
+      try {
+        t.current.destroy();
+      } catch {
+      }
+      t.current = null, c(null), o(!1);
+    }
+    n(null);
+    const f = u.current;
+    if (!(!f || !l))
+      try {
+        const r = new L(l, m);
+        r.on("error", (_) => {
+          n(_ instanceof Error ? _ : new Error(String(_)));
+        }), r.mount(f), t.current = r, c(r), o(!0);
+      } catch (r) {
+        const _ = r instanceof Error ? r : new Error(String(r));
+        n(_), o(!1);
+      }
+  }, [l, m]);
+  N(() => (s(), () => {
+    if (t.current) {
+      try {
+        t.current.destroy();
+      } catch {
+      }
+      t.current = null, c(null), o(!1);
+    }
+  }), [s]);
+  const p = g(() => {
+    s();
+  }, [s]);
+  return { containerRef: u, instance: h, error: d, isReady: i, retry: p };
+}
+const q = "_chartContainer_k1m9p_61", $ = "_chartContainerLoading_k1m9p_69", j = "_chartContainerReady_k1m9p_75", A = "_card_k1m9p_83", H = "_header_k1m9p_130", M = "_title_k1m9p_134", P = "_description_k1m9p_144", w = "_chartArea_k1m9p_153", x = "_skeleton_k1m9p_163", S = "_skeletonHidden_k1m9p_175", b = "_skeletonPulse_k1m9p_180", G = "_errorContainer_k1m9p_202", K = "_errorIcon_k1m9p_226", z = "_errorMessage_k1m9p_233", D = "_retryButton_k1m9p_243", J = "_footer_k1m9p_271", e = {
+  chartContainer: q,
+  chartContainerLoading: $,
+  chartContainerReady: j,
+  card: A,
+  "card--elevated": "_card--elevated_k1m9p_98",
+  "card--outlined": "_card--outlined_k1m9p_106",
+  "card--flat": "_card--flat_k1m9p_117",
+  header: H,
+  title: M,
+  description: P,
+  chartArea: w,
+  skeleton: x,
+  skeletonHidden: S,
+  skeletonPulse: b,
+  "eq-shimmer": "_eq-shimmer_k1m9p_1",
+  errorContainer: G,
+  "fade-in": "_fade-in_k1m9p_1",
+  errorIcon: K,
+  errorMessage: z,
+  retryButton: D,
+  footer: J
+};
+function X({
+  config: l,
+  options: m,
+  className: u,
+  style: t,
+  onError: h,
+  onReady: c
+}) {
+  const { containerRef: d, error: n, isReady: i } = E(l, m);
+  N(() => {
+    n && h && h(n);
+  }, [n, h]), N(() => {
+    i && c && c();
+  }, [i, c]);
+  const o = [
+    e.chartContainer,
+    !i || n ? e.chartContainerLoading : e.chartContainerReady,
+    u
+  ].filter(Boolean).join(" ");
+  return /* @__PURE__ */ a(
+    "div",
+    {
+      ref: d,
+      className: o,
+      style: t
+    }
+  );
+}
+function Y({
+  config: l,
+  options: m,
+  className: u,
+  style: t,
+  onError: h,
+  onReady: c,
+  title: d,
+  description: n,
+  footer: i,
+  loading: o,
+  errorFallback: s,
+  variant: p = "elevated"
+}) {
+  const { containerRef: f, error: r, isReady: _, retry: B } = E(l, m), R = o !== void 0 ? o : !_ && !r, I = [
+    e.card,
+    e[`card--${p}`],
+    u
+  ].filter(Boolean).join(" ");
+  let C = null;
+  return r && (s ? C = typeof s == "function" ? s(r) : s : C = /* @__PURE__ */ k("div", { className: e.errorContainer, children: [
+    /* @__PURE__ */ a("div", { className: e.errorIcon, children: "⚠" }),
+    /* @__PURE__ */ a("p", { className: e.errorMessage, children: r.message || "Failed to render chart" }),
+    /* @__PURE__ */ a("button", { className: e.retryButton, onClick: B, children: "Retry" })
+  ] })), /* @__PURE__ */ k("div", { className: I, style: t, children: [
+    (d || n) && /* @__PURE__ */ k("div", { className: e.header, children: [
+      d && /* @__PURE__ */ a("h3", { className: e.title, children: d }),
+      n && /* @__PURE__ */ a("p", { className: e.description, children: n })
+    ] }),
+    /* @__PURE__ */ k("div", { className: e.chartArea, children: [
+      /* @__PURE__ */ a("div", { className: `${e.skeleton} ${!R || r ? e.skeletonHidden : ""}`, children: /* @__PURE__ */ a("div", { className: e.skeletonPulse }) }),
+      r && C,
+      /* @__PURE__ */ a(
+        "div",
+        {
+          ref: f,
+          className: `${e.chartContainer} ${R || r ? e.chartContainerLoading : e.chartContainerReady}`
+        }
+      )
+    ] }),
+    i && /* @__PURE__ */ a("div", { className: e.footer, children: i })
+  ] });
+}
+export {
+  Y as EquilibriaCard,
+  X as EquilibriaChart,
+  E as useEquilibria
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+
+export { EquilibriaChart } from './EquilibriaChart';
+export { EquilibriaCard } from './EquilibriaCard';
+export { useEquilibria } from './useEquilibria';
+export type { EquilibriaChartProps, EquilibriaCardProps, CardVariant } from './types';
+export type { UseEquilibriaReturn, UseEquilibriaOptions } from './useEquilibria';

package/dist/style.css

@@ -0,0 +1 @@
+:root{--eq-card-bg: rgba(255, 255, 255, .75);--eq-card-border: rgba(255, 255, 255, .5);--eq-card-shadow-color: rgba(99, 102, 241, .08);--eq-card-shadow: 0 8px 32px var(--eq-card-shadow-color), inset 0 0 0 1px var(--eq-card-border);--eq-card-shadow-hover: 0 14px 48px rgba(99, 102, 241, .15), inset 0 0 0 1px var(--eq-card-border);--eq-card-blur: 16px;--eq-card-radius: 20px;--eq-card-padding: 1.75rem;--eq-font-family: "Inter", system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;--eq-title-color: #0f172a;--eq-title-size: 1.2rem;--eq-title-weight: 600;--eq-description-color: #475569;--eq-description-size: .95rem;--eq-error-bg: rgba(254, 226, 226, .8);--eq-error-color: #991b1b;--eq-error-border: rgba(248, 113, 113, .3);--eq-skeleton-bg: rgba(241, 245, 249, .6);--eq-skeleton-color-1: rgba(99, 102, 241, .08);--eq-skeleton-color-2: rgba(168, 85, 247, .08);--eq-skeleton-color-3: rgba(236, 72, 153, .08)}@media (prefers-color-scheme: dark){:root{--eq-card-bg: rgba(15, 23, 42, .65);--eq-card-border: rgba(255, 255, 255, .06);--eq-card-shadow-color: rgba(0, 0, 0, .4);--eq-card-shadow: 0 8px 32px var(--eq-card-shadow-color), inset 0 0 0 1px var(--eq-card-border);--eq-card-shadow-hover: 0 14px 48px rgba(0, 0, 0, .6), inset 0 0 0 1px rgba(255, 255, 255, .12);--eq-title-color: #f8fafc;--eq-description-color: #94a3b8;--eq-error-bg: rgba(127, 29, 29, .4);--eq-error-color: #fca5a5;--eq-error-border: rgba(248, 113, 113, .2);--eq-skeleton-bg: rgba(30, 41, 59, .5);--eq-skeleton-color-1: rgba(99, 102, 241, .15);--eq-skeleton-color-2: rgba(168, 85, 247, .15);--eq-skeleton-color-3: rgba(236, 72, 153, .15)}}._chartContainer_k1m9p_61{width:100%;min-height:120px;position:relative;transition:opacity .8s cubic-bezier(.16,1,.3,1),filter .8s cubic-bezier(.16,1,.3,1)}._chartContainerLoading_k1m9p_69{opacity:0!important;filter:blur(8px)!important;pointer-events:none!important}._chartContainerReady_k1m9p_75{opacity:1!important;filter:blur(0)!important;pointer-events:auto!important}._card_k1m9p_83{font-family:var(--eq-font-family);background:var(--eq-card-bg);backdrop-filter:blur(var(--eq-card-blur));-webkit-backdrop-filter:blur(var(--eq-card-blur));border-radius:var(--eq-card-radius);overflow:hidden;transition:box-shadow .4s cubic-bezier(.16,1,.3,1),transform .4s cubic-bezier(.16,1,.3,1)}._card_k1m9p_83:hover{transform:translateY(-2px)}._card--elevated_k1m9p_98{box-shadow:var(--eq-card-shadow)}._card--elevated_k1m9p_98:hover{box-shadow:var(--eq-card-shadow-hover)}._card--outlined_k1m9p_106{box-shadow:inset 0 0 0 1px var(--eq-card-border);background:transparent;backdrop-filter:none;-webkit-backdrop-filter:none}._card--outlined_k1m9p_106:hover{box-shadow:inset 0 0 0 1px #6366f180}._card--flat_k1m9p_117{box-shadow:none;background:transparent;backdrop-filter:none;-webkit-backdrop-filter:none}._card--flat_k1m9p_117:hover{transform:none}._header_k1m9p_130{padding:var(--eq-card-padding) var(--eq-card-padding) 0}._title_k1m9p_134{margin:0;font-family:var(--eq-font-family);font-size:var(--eq-title-size);font-weight:var(--eq-title-weight);color:var(--eq-title-color);line-height:1.4;letter-spacing:-.02em}._description_k1m9p_144{margin:.4rem 0 0;font-size:var(--eq-description-size);color:var(--eq-description-color);line-height:1.6}._chartArea_k1m9p_153{position:relative;padding:var(--eq-card-padding);min-height:200px;display:flex;flex-direction:column}._skeleton_k1m9p_163{position:absolute;inset:var(--eq-card-padding);border-radius:12px;overflow:hidden;background:var(--eq-skeleton-bg);opacity:1;transition:opacity .6s cubic-bezier(.16,1,.3,1),transform .6s cubic-bezier(.16,1,.3,1);z-index:2;pointer-events:none}._skeletonHidden_k1m9p_175{opacity:0;transform:scale(.98)}._skeletonPulse_k1m9p_180{width:100%;height:100%;background:linear-gradient(100deg,transparent 20%,var(--eq-skeleton-color-1) 35%,var(--eq-skeleton-color-2) 50%,var(--eq-skeleton-color-3) 65%,transparent 80%);background-size:300% 100%;animation:_eq-shimmer_k1m9p_1 2.5s cubic-bezier(.4,0,.2,1) infinite}@keyframes _eq-shimmer_k1m9p_1{0%{background-position:200% 0}to{background-position:-100% 0}}._errorContainer_k1m9p_202{position:absolute;inset:var(--eq-card-padding);display:flex;flex-direction:column;align-items:center;justify-content:center;gap:1rem;padding:2rem 1.5rem;background:var(--eq-error-bg);backdrop-filter:blur(8px);-webkit-backdrop-filter:blur(8px);border:1px solid var(--eq-error-border);border-radius:12px;text-align:center;z-index:3;animation:_fade-in_k1m9p_1 .4s ease-out}@keyframes _fade-in_k1m9p_1{0%{opacity:0;transform:translateY(5px)}to{opacity:1;transform:translateY(0)}}._errorIcon_k1m9p_226{font-size:2rem;line-height:1;color:var(--eq-error-color);filter:drop-shadow(0 0 8px rgba(248,113,113,.4))}._errorMessage_k1m9p_233{margin:0;font-family:var(--eq-font-family);font-size:.95rem;color:var(--eq-error-color);max-width:320px;word-break:break-word;font-weight:500}._retryButton_k1m9p_243{-webkit-appearance:none;-moz-appearance:none;appearance:none;background:var(--eq-error-color);color:#fff;font-family:var(--eq-font-family);font-size:.85rem;font-weight:600;padding:.5rem 1.2rem;border:none;border-radius:8px;cursor:pointer;box-shadow:0 4px 12px #991b1b33;transition:transform .2s ease,box-shadow .2s ease,background .2s ease}._retryButton_k1m9p_243:hover{background:#7f1d1d;transform:translateY(-1px);box-shadow:0 6px 16px #991b1b4d}._retryButton_k1m9p_243:active{transform:translateY(1px);box-shadow:0 2px 8px #991b1b33}._footer_k1m9p_271{padding:0 var(--eq-card-padding) var(--eq-card-padding);font-family:var(--eq-font-family);font-size:var(--eq-description-size);color:var(--eq-description-color);border-top:1px solid var(--eq-card-border);margin-top:0;padding-top:var(--eq-card-padding)}

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+import { CSSProperties, ReactNode } from 'react';
+import { KineticGraphOptions } from 'equilibria-engine-js';
+
+/**
+ * Props for the minimal EquilibriaChart component.
+ */
+export interface EquilibriaChartProps {
+    /** Engine configuration object (parsed JSON/YAML). */
+    config: Record<string, unknown>;
+    /** Engine options passed to the KineticGraph constructor. */
+    options?: KineticGraphOptions;
+    /** Additional CSS class name applied to the chart container. */
+    className?: string;
+    /** Inline styles applied to the chart container. */
+    style?: CSSProperties;
+    /** Callback fired when the engine encounters an error during mount. */
+    onError?: (error: Error) => void;
+    /** Callback fired after the engine successfully mounts and renders. */
+    onReady?: () => void;
+}
+/**
+ * Card style variants.
+ */
+export type CardVariant = 'elevated' | 'outlined' | 'flat';
+/**
+ * Props for the styled EquilibriaCard component.
+ */
+export interface EquilibriaCardProps extends EquilibriaChartProps {
+    /** Card title displayed above the chart. */
+    title?: string;
+    /** Subtitle / description displayed below the title. */
+    description?: string;
+    /** Footer content rendered below the chart. */
+    footer?: ReactNode;
+    /** Override the loading state (auto-detected by default). */
+    loading?: boolean;
+    /** Custom error UI. Can be a ReactNode or a render function receiving the error. */
+    errorFallback?: ReactNode | ((error: Error) => ReactNode);
+    /** Card container style variant. Default: 'elevated'. */
+    variant?: CardVariant;
+}

package/dist/useEquilibria.d.ts

@@ -0,0 +1,25 @@
+import { KineticGraph, KineticGraphOptions } from 'equilibria-engine-js';
+
+export interface UseEquilibriaOptions extends KineticGraphOptions {
+}
+export interface UseEquilibriaReturn {
+    /** Ref to attach to the container div element. */
+    containerRef: React.RefObject<HTMLDivElement>;
+    /** The KineticGraph instance (null until mounted). */
+    instance: KineticGraph | null;
+    /** Error caught during mount, if any. */
+    error: Error | null;
+    /** Whether the engine has successfully mounted. */
+    isReady: boolean;
+    /** Manually retry mounting after an error. */
+    retry: () => void;
+}
+/**
+ * Core hook that manages the KineticGraph lifecycle.
+ *
+ * - Creates and mounts the engine when the ref is attached
+ * - Destroys the engine on unmount
+ * - Re-mounts when the config identity changes
+ * - Surfaces errors and loading state
+ */
+export declare function useEquilibria(config: Record<string, unknown>, options?: UseEquilibriaOptions): UseEquilibriaReturn;

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "equilibria-react",
+    "version": "0.1.0",
+    "description": "React components for the Equilibria Engine — styled, drop-in chart cards with lifecycle management",
+    "type": "module",
+    "main": "dist/equilibria-react.cjs.js",
+    "module": "dist/equilibria-react.es.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/equilibria-react.es.js",
+            "require": "./dist/equilibria-react.cjs.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./dist/style.css": "./dist/style.css"
+    },
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "preview": "vite preview"
+    },
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0",
+        "equilibria-engine-js": "^1.0.0"
+    },
+    "devDependencies": {
+        "@types/react": "^18.2.0",
+        "@types/react-dom": "^18.2.0",
+        "react": "^18.2.0",
+        "react-dom": "^18.2.0",
+        "equilibria-engine-js": "file:../equilibria-engine-js",
+        "typescript": "^5.2.2",
+        "vite": "^4.4.9",
+        "vite-plugin-dts": "^3.5.3"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Kinetonomics-Equilibria/equilibria-react.git"
+    },
+    "author": "Jarryd Bentley",
+    "license": "MIT",
+    "keywords": [
+        "equilibria",
+        "react",
+        "charts",
+        "economics",
+        "graphs",
+        "d3",
+        "interactive"
+    ]
+}