@sqlrooms/cosmos 0.4.2

package/dist/hooks/useHoverState.js

@@ -0,0 +1,57 @@
+import { useState, useCallback } from 'react';
+import { hasClientCoordinates } from '../utils/coordinates';
+/**
+ * A custom hook that manages hover state for graph points.
+ *
+ * This hook provides functionality to:
+ * - Track which point is currently being hovered
+ * - Store the hover position coordinates
+ * - Clear the hover state
+ *
+ * @example
+ * ```tsx
+ * const Graph = () => {
+ *   const calcRelativeCoords = useRelativeCoordinates(containerRef);
+ *   const { hoveredPoint, onPointMouseOver, clearHoverState } = useHoverState(calcRelativeCoords);
+ *
+ *   return (
+ *     <div ref={containerRef}>
+ *       <CosmosGraph
+ *         onPointMouseOver={onPointMouseOver}
+ *         onPointMouseOut={clearHoverState}
+ *       />
+ *       {hoveredPoint && (
+ *         <Tooltip
+ *           x={hoveredPoint.position[0]}
+ *           y={hoveredPoint.position[1]}
+ *         />
+ *       )}
+ *     </div>
+ *   );
+ * };
+ * ```
+ *
+ * @param calcRelativeCoordinates - A function that converts client coordinates to container-relative coordinates
+ * @returns An object containing the hover state and handlers
+ */
+export const useHoverState = (calcRelativeCoordinates) => {
+    const [hoveredPoint, setHoveredPoint] = useState(null);
+    const onPointMouseOver = useCallback((index, _pointPosition, event) => {
+        if (hasClientCoordinates(event)) {
+            setHoveredPoint({
+                index,
+                position: calcRelativeCoordinates(event.clientX, event.clientY),
+            });
+        }
+    }, [calcRelativeCoordinates]);
+    const clearHoverState = useCallback(() => setHoveredPoint(null), []);
+    return {
+        /** The current hover state, containing the index and position of the hovered point, or null if no point is hovered */
+        hoveredPoint,
+        /** Handler to be called when a point is hovered. Updates the hover state with the point's index and position */
+        onPointMouseOver,
+        /** Handler to clear the hover state, typically called when the mouse leaves a point */
+        clearHoverState,
+    };
+};
+//# sourceMappingURL=useHoverState.js.map

package/dist/hooks/useHoverState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHoverState.js","sourceRoot":"","sources":["../../src/hooks/useHoverState.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,QAAQ,EAAE,WAAW,EAAC,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAC,oBAAoB,EAAC,MAAM,sBAAsB,CAAC;AAe1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,uBAAkE,EAClE,EAAE;IACF,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAAa,IAAI,CAAC,CAAC;IAEnE,MAAM,gBAAgB,GACpB,WAAW,CACT,CACE,KAAa,EACb,cAAgC,EAChC,KAA8B,EAC9B,EAAE;QACF,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,eAAe,CAAC;gBACd,KAAK;gBACL,QAAQ,EAAE,uBAAuB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC;aAChE,CAAC,CAAC;QACL,CAAC;IACH,CAAC,EACD,CAAC,uBAAuB,CAAC,CAC1B,CAAC;IAEJ,MAAM,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAErE,OAAO;QACL,sHAAsH;QACtH,YAAY;QACZ,gHAAgH;QAChH,gBAAgB;QAChB,uFAAuF;QACvF,eAAe;KAChB,CAAC;AACJ,CAAC,CAAC"}

package/dist/hooks/useRelativeCoordinates.d.ts

@@ -0,0 +1,2 @@
+export declare const useRelativeCoordinates: (containerRef: React.RefObject<HTMLElement>) => (x: number, y: number) => [number, number];
+//# sourceMappingURL=useRelativeCoordinates.d.ts.map

package/dist/hooks/useRelativeCoordinates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRelativeCoordinates.d.ts","sourceRoot":"","sources":["../../src/hooks/useRelativeCoordinates.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,iBACnB,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,SAGpC,MAAM,KAAK,MAAM,KAAG,CAAC,MAAM,EAAE,MAAM,CAO1C,CAAC"}

package/dist/hooks/useRelativeCoordinates.js

@@ -0,0 +1,10 @@
+import { useCallback } from 'react';
+export const useRelativeCoordinates = (containerRef) => {
+    return useCallback((x, y) => {
+        if (!containerRef.current)
+            return [0, 0];
+        const rect = containerRef.current.getBoundingClientRect();
+        return [x - rect.left, y - rect.top];
+    }, [containerRef]);
+};
+//# sourceMappingURL=useRelativeCoordinates.js.map

package/dist/hooks/useRelativeCoordinates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRelativeCoordinates.js","sourceRoot":"","sources":["../../src/hooks/useRelativeCoordinates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,OAAO,CAAC;AAElC,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,YAA0C,EAC1C,EAAE;IACF,OAAO,WAAW,CAChB,CAAC,CAAS,EAAE,CAAS,EAAoB,EAAE;QACzC,IAAI,CAAC,YAAY,CAAC,OAAO;YAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,qBAAqB,EAAE,CAAC;QAC1D,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC,EACD,CAAC,YAAY,CAAC,CACf,CAAC;AACJ,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @sqlrooms/cosmos - A React wrapper for the Cosmograph visualization library
+ *
+ * This package provides React components and hooks for creating interactive graph visualizations
+ * using the Cosmograph WebGL-based graph visualization library. It includes components for
+ * rendering graphs, managing graph state, and controlling graph interactions.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { CosmosGraph, CosmosGraphControls } from '@sqlrooms/cosmos';
+ *
+ * const MyGraph = () => {
+ *   return (
+ *     <div style={{ width: '800px', height: '600px' }}>
+ *       <CosmosGraph
+ *         config={graphConfig}
+ *         pointPositions={positions}
+ *         pointColors={colors}
+ *         pointSizes={sizes}
+ *       >
+ *         <CosmosGraphControls />
+ *       </CosmosGraph>
+ *     </div>
+ *   );
+ * };
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { CosmosGraph } from './CosmosGraph';
+export { CosmosGraphControls } from './CosmosGraphControls';
+/**
+ * A component that provides fine-grained controls for the graph simulation parameters.
+ * Must be used within a CosmosGraph component as it relies on the CosmosGraphContext.
+ *
+ * Features:
+ * - Slider controls for gravity, repulsion, link strength, link distance, friction, and decay
+ * - Real-time parameter adjustment with immediate visual feedback
+ * - Tooltips with parameter descriptions
+ * - Customizable positioning
+ *
+ * @example Basic usage
+ * ```tsx
+ * <CosmosGraph {...graphProps}>
+ *   <CosmosSimulationControls />
+ * </CosmosGraph>
+ * ```
+ *
+ * @example Custom positioning
+ * ```tsx
+ * <CosmosGraph {...graphProps}>
+ *   <CosmosSimulationControls className="absolute bottom-4 left-4" />
+ * </CosmosGraph>
+ * ```
+ */
+export { CosmosSimulationControls } from './CosmosSimulationControls';
+export type { CosmosGraphProps } from './CosmosGraph';
+export { useCosmosGraph } from './CosmosGraphContext';
+export { useGraph, useHoverState, useGraphConfig } from './hooks';
+export type { HoverState } from './hooks/useHoverState';
+export type { WithClientCoordinates } from './utils/coordinates';
+export { hasClientCoordinates } from './utils/coordinates';
+/**
+ * Zod schema for validating and describing graph simulation configuration parameters.
+ *
+ * Available parameters:
+ * - `simulationGravity` (number): Gravity force in the simulation. Controls how strongly nodes are pulled toward the center.
+ * - `simulationRepulsion` (number): Repulsion force between nodes. Higher values make nodes push away from each other more strongly.
+ * - `simulationLinkSpring` (number): Spring force for links between nodes. Higher values make connected nodes pull together more strongly.
+ * - `simulationLinkDistance` (number): Target distance between linked nodes. Defines the natural length of links in the simulation.
+ * - `simulationFriction` (number): Friction coefficient in the simulation. Higher values make node movement more damped.
+ * - `simulationDecay` (number): Decay coefficient in the simulation. Lower values make the simulation "cool down" more slowly.
+ *
+ * @example
+ * ```tsx
+ * import { CosmosSimulationConfigSchema } from '@sqlrooms/cosmos';
+ *
+ * const config = {
+ *   simulationGravity: 0.1,
+ *   simulationRepulsion: 1.0,
+ *   simulationLinkSpring: 1.0,
+ *   simulationLinkDistance: 10,
+ *   simulationFriction: 0.85,
+ *   simulationDecay: 1000
+ * };
+ *
+ * // Validate the config
+ * const validConfig = CosmosSimulationConfigSchema.parse(config);
+ * ```
+ */
+export { CosmosSimulationConfigSchema } from './config';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAC,wBAAwB,EAAC,MAAM,4BAA4B,CAAC;AACpE,YAAY,EAAC,gBAAgB,EAAC,MAAM,eAAe,CAAC;AAGpD,OAAO,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAC,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAC,MAAM,SAAS,CAAC;AAChE,YAAY,EAAC,UAAU,EAAC,MAAM,uBAAuB,CAAC;AAGtD,YAAY,EAAC,qBAAqB,EAAC,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAC,4BAA4B,EAAC,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,92 @@
+/**
+ * @sqlrooms/cosmos - A React wrapper for the Cosmograph visualization library
+ *
+ * This package provides React components and hooks for creating interactive graph visualizations
+ * using the Cosmograph WebGL-based graph visualization library. It includes components for
+ * rendering graphs, managing graph state, and controlling graph interactions.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { CosmosGraph, CosmosGraphControls } from '@sqlrooms/cosmos';
+ *
+ * const MyGraph = () => {
+ *   return (
+ *     <div style={{ width: '800px', height: '600px' }}>
+ *       <CosmosGraph
+ *         config={graphConfig}
+ *         pointPositions={positions}
+ *         pointColors={colors}
+ *         pointSizes={sizes}
+ *       >
+ *         <CosmosGraphControls />
+ *       </CosmosGraph>
+ *     </div>
+ *   );
+ * };
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Components
+export { CosmosGraph } from './CosmosGraph';
+export { CosmosGraphControls } from './CosmosGraphControls';
+/**
+ * A component that provides fine-grained controls for the graph simulation parameters.
+ * Must be used within a CosmosGraph component as it relies on the CosmosGraphContext.
+ *
+ * Features:
+ * - Slider controls for gravity, repulsion, link strength, link distance, friction, and decay
+ * - Real-time parameter adjustment with immediate visual feedback
+ * - Tooltips with parameter descriptions
+ * - Customizable positioning
+ *
+ * @example Basic usage
+ * ```tsx
+ * <CosmosGraph {...graphProps}>
+ *   <CosmosSimulationControls />
+ * </CosmosGraph>
+ * ```
+ *
+ * @example Custom positioning
+ * ```tsx
+ * <CosmosGraph {...graphProps}>
+ *   <CosmosSimulationControls className="absolute bottom-4 left-4" />
+ * </CosmosGraph>
+ * ```
+ */
+export { CosmosSimulationControls } from './CosmosSimulationControls';
+// Context and hooks
+export { useCosmosGraph } from './CosmosGraphContext';
+export { useGraph, useHoverState, useGraphConfig } from './hooks';
+export { hasClientCoordinates } from './utils/coordinates';
+// Configuration
+/**
+ * Zod schema for validating and describing graph simulation configuration parameters.
+ *
+ * Available parameters:
+ * - `simulationGravity` (number): Gravity force in the simulation. Controls how strongly nodes are pulled toward the center.
+ * - `simulationRepulsion` (number): Repulsion force between nodes. Higher values make nodes push away from each other more strongly.
+ * - `simulationLinkSpring` (number): Spring force for links between nodes. Higher values make connected nodes pull together more strongly.
+ * - `simulationLinkDistance` (number): Target distance between linked nodes. Defines the natural length of links in the simulation.
+ * - `simulationFriction` (number): Friction coefficient in the simulation. Higher values make node movement more damped.
+ * - `simulationDecay` (number): Decay coefficient in the simulation. Lower values make the simulation "cool down" more slowly.
+ *
+ * @example
+ * ```tsx
+ * import { CosmosSimulationConfigSchema } from '@sqlrooms/cosmos';
+ *
+ * const config = {
+ *   simulationGravity: 0.1,
+ *   simulationRepulsion: 1.0,
+ *   simulationLinkSpring: 1.0,
+ *   simulationLinkDistance: 10,
+ *   simulationFriction: 0.85,
+ *   simulationDecay: 1000
+ * };
+ *
+ * // Validate the config
+ * const validConfig = CosmosSimulationConfigSchema.parse(config);
+ * ```
+ */
+export { CosmosSimulationConfigSchema } from './config';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,aAAa;AACb,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAC,wBAAwB,EAAC,MAAM,4BAA4B,CAAC;AAGpE,oBAAoB;AACpB,OAAO,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAC,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAC,MAAM,SAAS,CAAC;AAKhE,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,gBAAgB;AAChB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAC,4BAA4B,EAAC,MAAM,UAAU,CAAC"}

package/dist/utils/coordinates.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Interface for objects that contain client coordinates.
+ * Typically used with mouse or pointer events.
+ */
+export type WithClientCoordinates = {
+    /** The horizontal coordinate relative to the client area */
+    clientX: number;
+    /** The vertical coordinate relative to the client area */
+    clientY: number;
+};
+/**
+ * Type guard that checks if an unknown value has client coordinates.
+ *
+ * This function performs a runtime check to ensure that an object has valid
+ * clientX and clientY number properties. It's useful for handling events
+ * that may or may not include coordinate information.
+ *
+ * @example
+ * ```ts
+ * const handleEvent = (event: unknown) => {
+ *   if (hasClientCoordinates(event)) {
+ *     // TypeScript now knows event has clientX and clientY
+ *     console.log(event.clientX, event.clientY);
+ *   }
+ * };
+ * ```
+ *
+ * @param event - The value to check for client coordinates
+ * @returns A type predicate indicating if the value has client coordinates
+ */
+export declare const hasClientCoordinates: (event: unknown) => event is WithClientCoordinates;
+//# sourceMappingURL=coordinates.d.ts.map

package/dist/utils/coordinates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinates.d.ts","sourceRoot":"","sources":["../../src/utils/coordinates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,UACxB,OAAO,KACb,KAAK,IAAI,qBASX,CAAC"}

package/dist/utils/coordinates.js

@@ -0,0 +1,29 @@
+/**
+ * Type guard that checks if an unknown value has client coordinates.
+ *
+ * This function performs a runtime check to ensure that an object has valid
+ * clientX and clientY number properties. It's useful for handling events
+ * that may or may not include coordinate information.
+ *
+ * @example
+ * ```ts
+ * const handleEvent = (event: unknown) => {
+ *   if (hasClientCoordinates(event)) {
+ *     // TypeScript now knows event has clientX and clientY
+ *     console.log(event.clientX, event.clientY);
+ *   }
+ * };
+ * ```
+ *
+ * @param event - The value to check for client coordinates
+ * @returns A type predicate indicating if the value has client coordinates
+ */
+export const hasClientCoordinates = (event) => {
+    return (typeof event === 'object' &&
+        event !== null &&
+        'clientX' in event &&
+        'clientY' in event &&
+        typeof event.clientX === 'number' &&
+        typeof event.clientY === 'number');
+};
+//# sourceMappingURL=coordinates.js.map

package/dist/utils/coordinates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinates.js","sourceRoot":"","sources":["../../src/utils/coordinates.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,KAAc,EACkB,EAAE;IAClC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QAClB,SAAS,IAAI,KAAK;QAClB,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QACjC,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAClC,CAAC;AACJ,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@sqlrooms/cosmos",
+  "version": "0.4.2",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "type": "module",
+  "private": false,
+  "author": "Ilya Boyandin <ilya@boyandin.me>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sqlrooms/sqlrooms.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cosmograph/cosmos": "2.0.0-beta.22",
+    "@sqlrooms/ui": "0.4.2",
+    "lucide-react": "^0.474.0",
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-dom": "*"
+  },
+  "scripts": {
+    "dev": "tsc -w",
+    "build": "tsc",
+    "lint": "eslint .",
+    "typedoc": "typedoc"
+  },
+  "gitHead": "c71b75c7c6f391e0760803bcac674b8a59368922"
+}