@sqlrooms/cosmos 0.4.2 → 0.5.1

package/dist/CosmosSlice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CosmosSlice.js","sourceRoot":"","sources":["../src/CosmosSlice.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @fileoverview Cosmos graph visualization state management using Zustand.\n * This module provides state management and control functions for the Cosmos graph visualization.\n */\n\nimport {Graph, GraphConfigInterface} from '@cosmograph/cosmos';\nimport {\n  createSlice,\n  useBaseProjectStore,\n  type ProjectState,\n} from '@sqlrooms/project-builder';\nimport type {BaseProjectConfig} from '@sqlrooms/project-config';\nimport type {StateCreator} from 'zustand';\nimport {CosmosSliceConfig} from './CosmosSliceConfig';\nimport {produce} from 'immer';\n\n/**\n * Core state interface for the Cosmos graph visualization.\n * Contains the graph instance, simulation state, and all control functions.\n */\nexport type CosmosSliceState = {\n  cosmos: {\n    /** The current graph instance */\n    graph: Graph | null;\n    /** Whether the physics simulation is currently running */\n    isSimulationRunning: boolean;\n    /** Creates a new graph instance in the specified container */\n    createGraph: (container: HTMLDivElement) => void;\n    /** Toggles the physics simulation on/off */\n    toggleSimulation: () => void;\n    /** Adjusts the view to fit all nodes */\n    fitView: () => void;\n    /** Starts the simulation with initial energy */\n    startWithEnergy: () => void;\n    /** Cleans up and removes the current graph */\n    destroyGraph: () => void;\n    /** Updates the simulation configuration parameters */\n    updateSimulationConfig: (\n      config: Partial<CosmosSliceConfig['cosmos']>,\n    ) => void;\n    /** Updates the graph's visual configuration */\n    updateGraphConfig: (config: Partial<GraphConfigInterface>) => void;\n    /** Updates the graph's data (points, links, colors, etc.) */\n    updateGraphData: (data: {\n      pointPositions?: Float32Array;\n      pointColors?: Float32Array;\n      pointSizes?: Float32Array;\n      linkIndexes?: Float32Array;\n      linkColors?: Float32Array;\n    }) => void;\n    /** Sets the currently focused point by its index */\n    setFocusedPoint: (index: number | undefined) => void;\n    /** Sets the zoom level of the graph view */\n    setZoomLevel: (level: number) => void;\n  };\n};\n\n/**\n * Combined type representing the full project state including Cosmos functionality.\n * Merges the base project state with Cosmos-specific state and configuration.\n */\nexport type ProjectStateWithCosmos = ProjectState<\n  BaseProjectConfig & CosmosSliceConfig\n> &\n  CosmosSliceState;\n\n/**\n * Creates a Zustand slice for managing Cosmos graph state.\n * This slice handles graph creation, destruction, configuration, and data updates.\n *\n * @returns A state creator function for the Cosmos slice\n */\nexport function createCosmosSlice(): StateCreator<CosmosSliceState> {\n  return createSlice<BaseProjectConfig & CosmosSliceConfig, CosmosSliceState>(\n    (set, get) => ({\n      cosmos: {\n        graph: null,\n        isSimulationRunning: true,\n\n        createGraph: (container: HTMLDivElement) => {\n          // Clean up old graph if it exists\n          const oldGraph = get().cosmos.graph;\n          if (oldGraph) {\n            oldGraph.pause();\n            oldGraph.destroy();\n          }\n\n          // Create and configure new graph\n          const graph = new Graph(container);\n          const config = get().project.config.cosmos;\n          graph.setConfig(config);\n          graph.start();\n\n          set((state) =>\n            produce(state, (draft) => {\n              draft.cosmos.graph = graph;\n            }),\n          );\n        },\n\n        toggleSimulation: () => {\n          const {graph} = get().cosmos;\n          if (!graph) return;\n\n          if (graph.isSimulationRunning) {\n            graph.pause();\n            set((state) =>\n              produce(state, (draft) => {\n                draft.cosmos.isSimulationRunning = false;\n              }),\n            );\n          } else {\n            graph.restart();\n            set((state) =>\n              produce(state, (draft) => {\n                draft.cosmos.isSimulationRunning = true;\n              }),\n            );\n          }\n        },\n\n        fitView: () => {\n          const {graph} = get().cosmos;\n          if (!graph) return;\n          graph.fitView();\n        },\n\n        startWithEnergy: () => {\n          const {graph} = get().cosmos;\n          if (!graph) return;\n          graph.start(1);\n          set((state) =>\n            produce(state, (draft) => {\n              draft.cosmos.isSimulationRunning = true;\n            }),\n          );\n        },\n\n        updateSimulationConfig: (\n          config: Partial<CosmosSliceConfig['cosmos']>,\n        ) => {\n          const {graph} = get().cosmos;\n\n          set((state) =>\n            produce(state, (draft) => {\n              Object.assign(draft.project.config.cosmos, config);\n              if (graph) {\n                graph.setConfig(draft.project.config.cosmos);\n              }\n            }),\n          );\n        },\n\n        updateGraphConfig: (config: Partial<GraphConfigInterface>) => {\n          const {graph} = get().cosmos;\n\n          set((state) =>\n            produce(state, (draft) => {\n              Object.assign(draft.project.config.cosmos, config);\n              if (graph) {\n                graph.setConfig(draft.project.config.cosmos);\n              }\n            }),\n          );\n        },\n\n        updateGraphData: (data) => {\n          const {graph} = get().cosmos;\n          if (!graph) return;\n\n          if (data.pointPositions) {\n            graph.setPointPositions(data.pointPositions);\n          }\n          if (data.pointColors) {\n            graph.setPointColors(data.pointColors);\n          }\n          if (data.pointSizes) {\n            graph.setPointSizes(data.pointSizes);\n          }\n          if (data.linkIndexes) {\n            graph.setLinks(data.linkIndexes);\n          }\n          if (data.linkColors) {\n            graph.setLinkColors(data.linkColors);\n          }\n\n          graph.render();\n        },\n\n        setFocusedPoint: (index) => {\n          const {graph} = get().cosmos;\n          if (!graph) return;\n          graph.setFocusedPointByIndex(index);\n        },\n\n        setZoomLevel: (level) => {\n          const {graph} = get().cosmos;\n          if (!graph) return;\n          graph.setZoomLevel(level);\n        },\n\n        destroyGraph: () => {\n          const {graph} = get().cosmos;\n          if (!graph) return;\n          // TODO: this should be happening in cosmos\n          if ((graph as any).store.div?.firstChild) {\n            (graph as any).store.div.innerHTML = '';\n          }\n          graph.pause();\n          graph.destroy();\n          set((state) =>\n            produce(state, (draft) => {\n              draft.cosmos.graph = null;\n              draft.cosmos.isSimulationRunning = false;\n            }),\n          );\n        },\n      },\n    }),\n  );\n}\n\n/**\n * Hook to access the Cosmos store with proper typing.\n * Provides type-safe access to the combined project and Cosmos state.\n *\n * @template T The type of the selected state slice\n * @param selector A function that selects a portion of the state\n * @returns The selected state portion\n *\n * @example\n * ```typescript\n * const graph = useStoreWithCosmos(state => state.cosmos.graph);\n * const isRunning = useStoreWithCosmos(state => state.cosmos.isSimulationRunning);\n * ```\n */\nexport function useStoreWithCosmos<T>(\n  selector: (state: ProjectStateWithCosmos) => T,\n): T {\n  return useBaseProjectStore<\n    BaseProjectConfig & CosmosSliceConfig,\n    ProjectStateWithCosmos,\n    T\n  >((state) => selector(state as ProjectStateWithCosmos));\n}\n"]}

package/dist/CosmosSliceConfig.d.ts

@@ -0,0 +1,209 @@
+import { z } from 'zod';
+/**
+ * Zod schema for validating and configuring the Cosmos graph visualization.
+ * This schema defines all available configuration options and their types.
+ *
+ * The configuration is divided into several categories:
+ *
+ * Node Appearance:
+ * - `pointSizeScale`: Controls the size of nodes
+ * - `scalePointsOnZoom`: Enables dynamic node sizing based on zoom level
+ *
+ * Link Appearance:
+ * - `renderLinks`: Toggles link visibility
+ * - `linkWidthScale`: Controls link thickness
+ * - `linkArrows`: Toggles directional arrows
+ * - `linkArrowsSizeScale`: Controls arrow size
+ * - `curvedLinks`: Toggles curved/straight links
+ *
+ * Physics Simulation:
+ * - `simulationGravity`: Central gravitational force (0.25)
+ * - `simulationRepulsion`: Node repulsion force (1.0)
+ * - `simulationLinkSpring`: Link spring force (1.0)
+ * - `simulationLinkDistance`: Natural link length (10)
+ * - `simulationFriction`: Movement damping (0.85)
+ * - `simulationDecay`: Simulation cooling rate (1000)
+ *
+ * @example Basic configuration
+ * ```typescript
+ * const config: CosmosSliceConfig = {
+ *   cosmos: {
+ *     pointSizeScale: 1.2,
+ *     scalePointsOnZoom: true,
+ *     renderLinks: true,
+ *     linkWidthScale: 1.5,
+ *     simulationGravity: 0.25
+ *   }
+ * };
+ * ```
+ *
+ * @example Directed graph with curved links
+ * ```typescript
+ * const directedGraphConfig: CosmosSliceConfig = {
+ *   cosmos: {
+ *     linkArrows: true,
+ *     linkArrowsSizeScale: 1.2,
+ *     curvedLinks: true,
+ *     simulationLinkDistance: 15,
+ *     simulationLinkSpring: 1.2
+ *   }
+ * };
+ * ```
+ *
+ * @example High-performance configuration for large graphs
+ * ```typescript
+ * const largeGraphConfig: CosmosSliceConfig = {
+ *   cosmos: {
+ *     simulationGravity: 0.1,
+ *     simulationRepulsion: 0.8,
+ *     simulationFriction: 0.9,
+ *     simulationDecay: 2000,
+ *     scalePointsOnZoom: false
+ *   }
+ * };
+ * ```
+ */
+export declare const CosmosSliceConfig: z.ZodObject<{
+    cosmos: z.ZodObject<{
+        /**
+         * Scale factor for point (node) sizes in the graph.
+         * Values > 1 make nodes larger, values < 1 make them smaller.
+         * @default 1.1
+         */
+        pointSizeScale: z.ZodNumber;
+        /**
+         * When true, nodes will dynamically resize based on the current zoom level.
+         * This helps maintain visual clarity at different zoom levels.
+         * @default true
+         */
+        scalePointsOnZoom: z.ZodBoolean;
+        /**
+         * Controls whether links (edges) between nodes are displayed.
+         * @default true
+         */
+        renderLinks: z.ZodBoolean;
+        /**
+         * Scale factor for link (edge) width.
+         * Values > 1 make links thicker, values < 1 make them thinner.
+         * @default 1
+         */
+        linkWidthScale: z.ZodNumber;
+        /**
+         * Scale factor for the size of directional arrows on links.
+         * Only applies when linkArrows is true.
+         * @default 1
+         */
+        linkArrowsSizeScale: z.ZodNumber;
+        /**
+         * When true, displays arrows indicating link direction.
+         * Useful for directed graphs.
+         * @default false
+         */
+        linkArrows: z.ZodBoolean;
+        /**
+         * When true, links are rendered as curved Bezier paths.
+         * When false, links are straight lines.
+         * @default false
+         */
+        curvedLinks: z.ZodBoolean;
+        /**
+         * Controls the strength of the central gravitational force.
+         * Higher values pull nodes more strongly toward the center.
+         * @default 0.25
+         */
+        simulationGravity: z.ZodNumber;
+        /**
+         * Controls how strongly nodes repel each other.
+         * Higher values create more space between unconnected nodes.
+         * @default 1.0
+         */
+        simulationRepulsion: z.ZodNumber;
+        /**
+         * Controls the strength of the spring force between linked nodes.
+         * Higher values pull connected nodes more tightly together.
+         * @default 1.0
+         */
+        simulationLinkSpring: z.ZodNumber;
+        /**
+         * The natural or resting length of links between nodes.
+         * Higher values create more spacing between connected nodes.
+         * @default 10
+         */
+        simulationLinkDistance: z.ZodNumber;
+        /**
+         * Controls how quickly node movement decays.
+         * Higher values (closer to 1) create more damped movement.
+         * @default 0.85
+         */
+        simulationFriction: z.ZodNumber;
+        /**
+         * Controls how quickly the simulation stabilizes.
+         * Lower values result in longer, smoother transitions.
+         * @default 1000
+         */
+        simulationDecay: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        pointSizeScale: number;
+        renderLinks: boolean;
+        linkWidthScale: number;
+        curvedLinks: boolean;
+        linkArrows: boolean;
+        linkArrowsSizeScale: number;
+        simulationDecay: number;
+        simulationGravity: number;
+        simulationRepulsion: number;
+        simulationLinkSpring: number;
+        simulationLinkDistance: number;
+        simulationFriction: number;
+        scalePointsOnZoom: boolean;
+    }, {
+        pointSizeScale: number;
+        renderLinks: boolean;
+        linkWidthScale: number;
+        curvedLinks: boolean;
+        linkArrows: boolean;
+        linkArrowsSizeScale: number;
+        simulationDecay: number;
+        simulationGravity: number;
+        simulationRepulsion: number;
+        simulationLinkSpring: number;
+        simulationLinkDistance: number;
+        simulationFriction: number;
+        scalePointsOnZoom: boolean;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    cosmos: {
+        pointSizeScale: number;
+        renderLinks: boolean;
+        linkWidthScale: number;
+        curvedLinks: boolean;
+        linkArrows: boolean;
+        linkArrowsSizeScale: number;
+        simulationDecay: number;
+        simulationGravity: number;
+        simulationRepulsion: number;
+        simulationLinkSpring: number;
+        simulationLinkDistance: number;
+        simulationFriction: number;
+        scalePointsOnZoom: boolean;
+    };
+}, {
+    cosmos: {
+        pointSizeScale: number;
+        renderLinks: boolean;
+        linkWidthScale: number;
+        curvedLinks: boolean;
+        linkArrows: boolean;
+        linkArrowsSizeScale: number;
+        simulationDecay: number;
+        simulationGravity: number;
+        simulationRepulsion: number;
+        simulationLinkSpring: number;
+        simulationLinkDistance: number;
+        simulationFriction: number;
+        scalePointsOnZoom: boolean;
+    };
+}>;
+export type CosmosSliceConfig = z.infer<typeof CosmosSliceConfig>;
+export declare function createDefaultCosmosConfig(): CosmosSliceConfig;
+//# sourceMappingURL=CosmosSliceConfig.d.ts.map

package/dist/CosmosSliceConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CosmosSliceConfig.d.ts","sourceRoot":"","sources":["../src/CosmosSliceConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAuBtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,eAAO,MAAM,iBAAiB;;QAE1B;;;;WAIG;;QAGH;;;;WAIG;;QAKH;;;WAGG;;QAGH;;;;WAIG;;QAGH;;;;WAIG;;QAKH;;;;WAIG;;QAKH;;;;WAIG;;QAOH;;;;WAIG;;QAGH;;;;WAIG;;QAGH;;;;WAIG;;QAKH;;;;WAIG;;QAKH;;;;WAIG;;QAKH;;;;WAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAOL,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,wBAAgB,yBAAyB,IAAI,iBAAiB,CAI7D"}

package/dist/CosmosSliceConfig.js

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+/**
+ * Default configuration values for the Cosmos graph visualization.
+ * These values provide a balanced starting point for most graph visualizations.
+ */
+const DEFAULT_COSMOS_CONFIG = {
+    pointSizeScale: 1.1,
+    scalePointsOnZoom: true,
+    simulationGravity: 0.25,
+    simulationRepulsion: 1.0,
+    simulationLinkSpring: 1.0,
+    simulationLinkDistance: 10,
+    simulationFriction: 0.85,
+    simulationDecay: 1000,
+    renderLinks: true,
+    linkArrows: false,
+    curvedLinks: false,
+    linkWidthScale: 1,
+    linkArrowsSizeScale: 1,
+};
+/**
+ * Zod schema for validating and configuring the Cosmos graph visualization.
+ * This schema defines all available configuration options and their types.
+ *
+ * The configuration is divided into several categories:
+ *
+ * Node Appearance:
+ * - `pointSizeScale`: Controls the size of nodes
+ * - `scalePointsOnZoom`: Enables dynamic node sizing based on zoom level
+ *
+ * Link Appearance:
+ * - `renderLinks`: Toggles link visibility
+ * - `linkWidthScale`: Controls link thickness
+ * - `linkArrows`: Toggles directional arrows
+ * - `linkArrowsSizeScale`: Controls arrow size
+ * - `curvedLinks`: Toggles curved/straight links
+ *
+ * Physics Simulation:
+ * - `simulationGravity`: Central gravitational force (0.25)
+ * - `simulationRepulsion`: Node repulsion force (1.0)
+ * - `simulationLinkSpring`: Link spring force (1.0)
+ * - `simulationLinkDistance`: Natural link length (10)
+ * - `simulationFriction`: Movement damping (0.85)
+ * - `simulationDecay`: Simulation cooling rate (1000)
+ *
+ * @example Basic configuration
+ * ```typescript
+ * const config: CosmosSliceConfig = {
+ *   cosmos: {
+ *     pointSizeScale: 1.2,
+ *     scalePointsOnZoom: true,
+ *     renderLinks: true,
+ *     linkWidthScale: 1.5,
+ *     simulationGravity: 0.25
+ *   }
+ * };
+ * ```
+ *
+ * @example Directed graph with curved links
+ * ```typescript
+ * const directedGraphConfig: CosmosSliceConfig = {
+ *   cosmos: {
+ *     linkArrows: true,
+ *     linkArrowsSizeScale: 1.2,
+ *     curvedLinks: true,
+ *     simulationLinkDistance: 15,
+ *     simulationLinkSpring: 1.2
+ *   }
+ * };
+ * ```
+ *
+ * @example High-performance configuration for large graphs
+ * ```typescript
+ * const largeGraphConfig: CosmosSliceConfig = {
+ *   cosmos: {
+ *     simulationGravity: 0.1,
+ *     simulationRepulsion: 0.8,
+ *     simulationFriction: 0.9,
+ *     simulationDecay: 2000,
+ *     scalePointsOnZoom: false
+ *   }
+ * };
+ * ```
+ */
+export const CosmosSliceConfig = z.object({
+    cosmos: z.object({
+        /**
+         * Scale factor for point (node) sizes in the graph.
+         * Values > 1 make nodes larger, values < 1 make them smaller.
+         * @default 1.1
+         */
+        pointSizeScale: z.number().describe('Scale factor for point sizes'),
+        /**
+         * When true, nodes will dynamically resize based on the current zoom level.
+         * This helps maintain visual clarity at different zoom levels.
+         * @default true
+         */
+        scalePointsOnZoom: z
+            .boolean()
+            .describe('Dynamically resize points based on zoom level'),
+        /**
+         * Controls whether links (edges) between nodes are displayed.
+         * @default true
+         */
+        renderLinks: z.boolean().describe('Control links displaying'),
+        /**
+         * Scale factor for link (edge) width.
+         * Values > 1 make links thicker, values < 1 make them thinner.
+         * @default 1
+         */
+        linkWidthScale: z.number().describe('Scale factor for link width'),
+        /**
+         * Scale factor for the size of directional arrows on links.
+         * Only applies when linkArrows is true.
+         * @default 1
+         */
+        linkArrowsSizeScale: z
+            .number()
+            .describe('Scale factor for link arrows size'),
+        /**
+         * When true, displays arrows indicating link direction.
+         * Useful for directed graphs.
+         * @default false
+         */
+        linkArrows: z
+            .boolean()
+            .describe('Control displaying link direction arrows'),
+        /**
+         * When true, links are rendered as curved Bezier paths.
+         * When false, links are straight lines.
+         * @default false
+         */
+        curvedLinks: z
+            .boolean()
+            .describe('Render links as curved bezier paths instead of straight lines'),
+        /**
+         * Controls the strength of the central gravitational force.
+         * Higher values pull nodes more strongly toward the center.
+         * @default 0.25
+         */
+        simulationGravity: z.number().describe('Gravity force in the simulation'),
+        /**
+         * Controls how strongly nodes repel each other.
+         * Higher values create more space between unconnected nodes.
+         * @default 1.0
+         */
+        simulationRepulsion: z.number().describe('Repulsion force between nodes'),
+        /**
+         * Controls the strength of the spring force between linked nodes.
+         * Higher values pull connected nodes more tightly together.
+         * @default 1.0
+         */
+        simulationLinkSpring: z
+            .number()
+            .describe('Spring force for links between nodes'),
+        /**
+         * The natural or resting length of links between nodes.
+         * Higher values create more spacing between connected nodes.
+         * @default 10
+         */
+        simulationLinkDistance: z
+            .number()
+            .describe('Target distance between linked nodes'),
+        /**
+         * Controls how quickly node movement decays.
+         * Higher values (closer to 1) create more damped movement.
+         * @default 0.85
+         */
+        simulationFriction: z
+            .number()
+            .describe('Friction coefficient in the simulation'),
+        /**
+         * Controls how quickly the simulation stabilizes.
+         * Lower values result in longer, smoother transitions.
+         * @default 1000
+         */
+        simulationDecay: z
+            .number()
+            .describe('Decay coefficient in the simulation. Use smaller values if you want the simulation to "cool down" slower.'),
+    }),
+});
+export function createDefaultCosmosConfig() {
+    return {
+        cosmos: DEFAULT_COSMOS_CONFIG,
+    };
+}
+//# sourceMappingURL=CosmosSliceConfig.js.map

package/dist/CosmosSliceConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CosmosSliceConfig.js","sourceRoot":"","sources":["../src/CosmosSliceConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB;;;GAGG;AACH,MAAM,qBAAqB,GAAgC;IACzD,cAAc,EAAE,GAAG;IACnB,iBAAiB,EAAE,IAAI;IACvB,iBAAiB,EAAE,IAAI;IACvB,mBAAmB,EAAE,GAAG;IACxB,oBAAoB,EAAE,GAAG;IACzB,sBAAsB,EAAE,EAAE;IAC1B,kBAAkB,EAAE,IAAI;IACxB,eAAe,EAAE,IAAI;IACrB,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,KAAK;IACjB,WAAW,EAAE,KAAK;IAClB,cAAc,EAAE,CAAC;IACjB,mBAAmB,EAAE,CAAC;CAC0B,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf;;;;WAIG;QACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QAEnE;;;;WAIG;QACH,iBAAiB,EAAE,CAAC;aACjB,OAAO,EAAE;aACT,QAAQ,CAAC,+CAA+C,CAAC;QAE5D;;;WAGG;QACH,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;QAE7D;;;;WAIG;QACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QAElE;;;;WAIG;QACH,mBAAmB,EAAE,CAAC;aACnB,MAAM,EAAE;aACR,QAAQ,CAAC,mCAAmC,CAAC;QAEhD;;;;WAIG;QACH,UAAU,EAAE,CAAC;aACV,OAAO,EAAE;aACT,QAAQ,CAAC,0CAA0C,CAAC;QAEvD;;;;WAIG;QACH,WAAW,EAAE,CAAC;aACX,OAAO,EAAE;aACT,QAAQ,CACP,+DAA+D,CAChE;QAEH;;;;WAIG;QACH,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;QAEzE;;;;WAIG;QACH,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;QAEzE;;;;WAIG;QACH,oBAAoB,EAAE,CAAC;aACpB,MAAM,EAAE;aACR,QAAQ,CAAC,sCAAsC,CAAC;QAEnD;;;;WAIG;QACH,sBAAsB,EAAE,CAAC;aACtB,MAAM,EAAE;aACR,QAAQ,CAAC,sCAAsC,CAAC;QAEnD;;;;WAIG;QACH,kBAAkB,EAAE,CAAC;aAClB,MAAM,EAAE;aACR,QAAQ,CAAC,wCAAwC,CAAC;QAErD;;;;WAIG;QACH,eAAe,EAAE,CAAC;aACf,MAAM,EAAE;aACR,QAAQ,CACP,2GAA2G,CAC5G;KAC2D,CAAC;CAClE,CAAC,CAAC;AAGH,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,MAAM,EAAE,qBAAqB;KAC9B,CAAC;AACJ,CAAC","sourcesContent":["import {z} from 'zod';\nimport {GraphConfigInterface} from '@cosmograph/cosmos';\n\n/**\n * Default configuration values for the Cosmos graph visualization.\n * These values provide a balanced starting point for most graph visualizations.\n */\nconst DEFAULT_COSMOS_CONFIG: CosmosSliceConfig['cosmos'] = {\n  pointSizeScale: 1.1,\n  scalePointsOnZoom: true,\n  simulationGravity: 0.25,\n  simulationRepulsion: 1.0,\n  simulationLinkSpring: 1.0,\n  simulationLinkDistance: 10,\n  simulationFriction: 0.85,\n  simulationDecay: 1000,\n  renderLinks: true,\n  linkArrows: false,\n  curvedLinks: false,\n  linkWidthScale: 1,\n  linkArrowsSizeScale: 1,\n} as const satisfies Partial<GraphConfigInterface>;\n\n/**\n * Zod schema for validating and configuring the Cosmos graph visualization.\n * This schema defines all available configuration options and their types.\n *\n * The configuration is divided into several categories:\n *\n * Node Appearance:\n * - `pointSizeScale`: Controls the size of nodes\n * - `scalePointsOnZoom`: Enables dynamic node sizing based on zoom level\n *\n * Link Appearance:\n * - `renderLinks`: Toggles link visibility\n * - `linkWidthScale`: Controls link thickness\n * - `linkArrows`: Toggles directional arrows\n * - `linkArrowsSizeScale`: Controls arrow size\n * - `curvedLinks`: Toggles curved/straight links\n *\n * Physics Simulation:\n * - `simulationGravity`: Central gravitational force (0.25)\n * - `simulationRepulsion`: Node repulsion force (1.0)\n * - `simulationLinkSpring`: Link spring force (1.0)\n * - `simulationLinkDistance`: Natural link length (10)\n * - `simulationFriction`: Movement damping (0.85)\n * - `simulationDecay`: Simulation cooling rate (1000)\n *\n * @example Basic configuration\n * ```typescript\n * const config: CosmosSliceConfig = {\n *   cosmos: {\n *     pointSizeScale: 1.2,\n *     scalePointsOnZoom: true,\n *     renderLinks: true,\n *     linkWidthScale: 1.5,\n *     simulationGravity: 0.25\n *   }\n * };\n * ```\n *\n * @example Directed graph with curved links\n * ```typescript\n * const directedGraphConfig: CosmosSliceConfig = {\n *   cosmos: {\n *     linkArrows: true,\n *     linkArrowsSizeScale: 1.2,\n *     curvedLinks: true,\n *     simulationLinkDistance: 15,\n *     simulationLinkSpring: 1.2\n *   }\n * };\n * ```\n *\n * @example High-performance configuration for large graphs\n * ```typescript\n * const largeGraphConfig: CosmosSliceConfig = {\n *   cosmos: {\n *     simulationGravity: 0.1,\n *     simulationRepulsion: 0.8,\n *     simulationFriction: 0.9,\n *     simulationDecay: 2000,\n *     scalePointsOnZoom: false\n *   }\n * };\n * ```\n */\nexport const CosmosSliceConfig = z.object({\n  cosmos: z.object({\n    /**\n     * Scale factor for point (node) sizes in the graph.\n     * Values > 1 make nodes larger, values < 1 make them smaller.\n     * @default 1.1\n     */\n    pointSizeScale: z.number().describe('Scale factor for point sizes'),\n\n    /**\n     * When true, nodes will dynamically resize based on the current zoom level.\n     * This helps maintain visual clarity at different zoom levels.\n     * @default true\n     */\n    scalePointsOnZoom: z\n      .boolean()\n      .describe('Dynamically resize points based on zoom level'),\n\n    /**\n     * Controls whether links (edges) between nodes are displayed.\n     * @default true\n     */\n    renderLinks: z.boolean().describe('Control links displaying'),\n\n    /**\n     * Scale factor for link (edge) width.\n     * Values > 1 make links thicker, values < 1 make them thinner.\n     * @default 1\n     */\n    linkWidthScale: z.number().describe('Scale factor for link width'),\n\n    /**\n     * Scale factor for the size of directional arrows on links.\n     * Only applies when linkArrows is true.\n     * @default 1\n     */\n    linkArrowsSizeScale: z\n      .number()\n      .describe('Scale factor for link arrows size'),\n\n    /**\n     * When true, displays arrows indicating link direction.\n     * Useful for directed graphs.\n     * @default false\n     */\n    linkArrows: z\n      .boolean()\n      .describe('Control displaying link direction arrows'),\n\n    /**\n     * When true, links are rendered as curved Bezier paths.\n     * When false, links are straight lines.\n     * @default false\n     */\n    curvedLinks: z\n      .boolean()\n      .describe(\n        'Render links as curved bezier paths instead of straight lines',\n      ),\n\n    /**\n     * Controls the strength of the central gravitational force.\n     * Higher values pull nodes more strongly toward the center.\n     * @default 0.25\n     */\n    simulationGravity: z.number().describe('Gravity force in the simulation'),\n\n    /**\n     * Controls how strongly nodes repel each other.\n     * Higher values create more space between unconnected nodes.\n     * @default 1.0\n     */\n    simulationRepulsion: z.number().describe('Repulsion force between nodes'),\n\n    /**\n     * Controls the strength of the spring force between linked nodes.\n     * Higher values pull connected nodes more tightly together.\n     * @default 1.0\n     */\n    simulationLinkSpring: z\n      .number()\n      .describe('Spring force for links between nodes'),\n\n    /**\n     * The natural or resting length of links between nodes.\n     * Higher values create more spacing between connected nodes.\n     * @default 10\n     */\n    simulationLinkDistance: z\n      .number()\n      .describe('Target distance between linked nodes'),\n\n    /**\n     * Controls how quickly node movement decays.\n     * Higher values (closer to 1) create more damped movement.\n     * @default 0.85\n     */\n    simulationFriction: z\n      .number()\n      .describe('Friction coefficient in the simulation'),\n\n    /**\n     * Controls how quickly the simulation stabilizes.\n     * Lower values result in longer, smoother transitions.\n     * @default 1000\n     */\n    simulationDecay: z\n      .number()\n      .describe(\n        'Decay coefficient in the simulation. Use smaller values if you want the simulation to \"cool down\" slower.',\n      ),\n  } satisfies Partial<Record<keyof GraphConfigInterface, unknown>>),\n});\nexport type CosmosSliceConfig = z.infer<typeof CosmosSliceConfig>;\n\nexport function createDefaultCosmosConfig(): CosmosSliceConfig {\n  return {\n    cosmos: DEFAULT_COSMOS_CONFIG,\n  };\n}\n"]}

package/dist/hooks/useHoverState.d.ts

@@ -17,18 +17,18 @@ export type HoverState = {
  * - Track which point is currently being hovered
  * - Store the hover position coordinates
  * - Clear the hover state
+ * - Provide event handlers for hover-related graph interactions
  *
  * @example
  * ```tsx
  * const Graph = () => {
  *   const calcRelativeCoords = useRelativeCoordinates(containerRef);
- *   const { hoveredPoint, onPointMouseOver, clearHoverState } = useHoverState(calcRelativeCoords);
+ *   const { hoveredPoint, eventHandlers } = useHoverState(calcRelativeCoords);
  *
  *   return (
  *     <div ref={containerRef}>
  *       <CosmosGraph
- *         onPointMouseOver={onPointMouseOver}
- *         onPointMouseOut={clearHoverState}
+ *         config={eventHandlers}
  *       />
  *       {hoveredPoint && (
  *         <Tooltip
@@ -42,14 +42,17 @@ export type HoverState = {
  * ```
  *
  * @param calcRelativeCoordinates - A function that converts client coordinates to container-relative coordinates
- * @returns An object containing the hover state and handlers
+ * @returns An object containing the hover state and event handlers for the graph
  */
 export declare const useHoverState: (calcRelativeCoordinates: ReturnType<typeof useRelativeCoordinates>) => {
     /** The current hover state, containing the index and position of the hovered point, or null if no point is hovered */
     hoveredPoint: HoverState;
-    /** Handler to be called when a point is hovered. Updates the hover state with the point's index and position */
-    onPointMouseOver: (index: number, pointPosition: [number, number], event: MouseEvent | D3DragEvent<HTMLCanvasElement, undefined, import("@cosmograph/cosmos/dist/modules/Store").Hovered> | D3ZoomEvent<HTMLCanvasElement, undefined> | undefined) => void;
-    /** Handler to clear the hover state, typically called when the mouse leaves a point */
-    clearHoverState: () => void;
+    /** Event handlers for hover-related graph interactions */
+    eventHandlers: {
+        onPointMouseOver: (index: number, pointPosition: [number, number], event: MouseEvent | D3DragEvent<HTMLCanvasElement, undefined, import("@cosmograph/cosmos/dist/modules/Store").Hovered> | D3ZoomEvent<HTMLCanvasElement, undefined> | undefined) => void;
+        onPointMouseOut: () => void;
+        onZoomStart: () => void;
+        onDragStart: () => void;
+    };
 };
 //# sourceMappingURL=useHoverState.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useHoverState.d.ts","sourceRoot":"","sources":["../../src/hooks/useHoverState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,sBAAsB,EAAC,MAAM,cAAc,CAAC;AAKpD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5B,GAAG,IAAI,CAAC;AAET;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,aAAa,4BACC,UAAU,CAAC,OAAO,sBAAsB,CAAC;IAwBhE,sHAAsH;;IAEtH,gHAAgH;;IAEhH,uFAAuF;;CAG1F,CAAC"}
+{"version":3,"file":"useHoverState.d.ts","sourceRoot":"","sources":["../../src/hooks/useHoverState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,sBAAsB,EAAC,MAAM,cAAc,CAAC;AAKpD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5B,GAAG,IAAI,CAAC;AAET;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,aAAa,4BACC,UAAU,CAAC,OAAO,sBAAsB,CAAC;IAkChE,sHAAsH;;IAEtH,0DAA0D;;;;;;;CAG7D,CAAC"}

package/dist/hooks/useHoverState.js

@@ -1,4 +1,4 @@
-import { useState, useCallback } from 'react';
+import { useState, useCallback, useMemo } from 'react';
 import { hasClientCoordinates } from '../utils/coordinates';
 /**
  * A custom hook that manages hover state for graph points.
@@ -7,18 +7,18 @@ import { hasClientCoordinates } from '../utils/coordinates';
  * - Track which point is currently being hovered
  * - Store the hover position coordinates
  * - Clear the hover state
+ * - Provide event handlers for hover-related graph interactions
  *
  * @example
  * ```tsx
  * const Graph = () => {
  *   const calcRelativeCoords = useRelativeCoordinates(containerRef);
- *   const { hoveredPoint, onPointMouseOver, clearHoverState } = useHoverState(calcRelativeCoords);
+ *   const { hoveredPoint, eventHandlers } = useHoverState(calcRelativeCoords);
  *
  *   return (
  *     <div ref={containerRef}>
  *       <CosmosGraph
- *         onPointMouseOver={onPointMouseOver}
- *         onPointMouseOut={clearHoverState}
+ *         config={eventHandlers}
  *       />
  *       {hoveredPoint && (
  *         <Tooltip
@@ -32,7 +32,7 @@ import { hasClientCoordinates } from '../utils/coordinates';
  * ```
  *
  * @param calcRelativeCoordinates - A function that converts client coordinates to container-relative coordinates
- * @returns An object containing the hover state and handlers
+ * @returns An object containing the hover state and event handlers for the graph
  */
 export const useHoverState = (calcRelativeCoordinates) => {
     const [hoveredPoint, setHoveredPoint] = useState(null);
@@ -45,13 +45,17 @@ export const useHoverState = (calcRelativeCoordinates) => {
         }
     }, [calcRelativeCoordinates]);
     const clearHoverState = useCallback(() => setHoveredPoint(null), []);
+    const eventHandlers = useMemo(() => ({
+        onPointMouseOver,
+        onPointMouseOut: clearHoverState,
+        onZoomStart: clearHoverState,
+        onDragStart: clearHoverState,
+    }), [onPointMouseOver, clearHoverState]);
     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,
+        /** Event handlers for hover-related graph interactions */
+        eventHandlers,
     };
 };
 //# sourceMappingURL=useHoverState.js.map

package/dist/hooks/useHoverState.js.map

@@ -1 +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"}
+{"version":3,"file":"useHoverState.js","sourceRoot":"","sources":["../../src/hooks/useHoverState.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAC,MAAM,OAAO,CAAC;AACrD,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,MAAM,aAAa,GAAG,OAAO,CAC3B,GAAG,EAAE,CAAC,CAAC;QACL,gBAAgB;QAChB,eAAe,EAAE,eAAe;QAChC,WAAW,EAAE,eAAe;QAC5B,WAAW,EAAE,eAAe;KAC7B,CAAC,EACF,CAAC,gBAAgB,EAAE,eAAe,CAAC,CACpC,CAAC;IAEF,OAAO;QACL,sHAAsH;QACtH,YAAY;QACZ,0DAA0D;QAC1D,aAAa;KACd,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import {useRelativeCoordinates} from '@sqlrooms/ui';\nimport {useState, useCallback, useMemo} from 'react';\nimport {hasClientCoordinates} from '../utils/coordinates';\nimport {GraphConfigInterface} from '@cosmograph/cosmos';\n\n/**\n * Represents the state of a hovered point in the graph.\n * When a point is hovered, contains its index and position coordinates.\n * When no point is hovered, the state is null.\n */\nexport type HoverState = {\n  /** The index of the hovered point in the graph data array */\n  index: number;\n  /** The [x, y] coordinates of the hovered point relative to the container */\n  position: [number, number];\n} | null;\n\n/**\n * A custom hook that manages hover state for graph points.\n *\n * This hook provides functionality to:\n * - Track which point is currently being hovered\n * - Store the hover position coordinates\n * - Clear the hover state\n * - Provide event handlers for hover-related graph interactions\n *\n * @example\n * ```tsx\n * const Graph = () => {\n *   const calcRelativeCoords = useRelativeCoordinates(containerRef);\n *   const { hoveredPoint, eventHandlers } = useHoverState(calcRelativeCoords);\n *\n *   return (\n *     <div ref={containerRef}>\n *       <CosmosGraph\n *         config={eventHandlers}\n *       />\n *       {hoveredPoint && (\n *         <Tooltip\n *           x={hoveredPoint.position[0]}\n *           y={hoveredPoint.position[1]}\n *         />\n *       )}\n *     </div>\n *   );\n * };\n * ```\n *\n * @param calcRelativeCoordinates - A function that converts client coordinates to container-relative coordinates\n * @returns An object containing the hover state and event handlers for the graph\n */\nexport const useHoverState = (\n  calcRelativeCoordinates: ReturnType<typeof useRelativeCoordinates>,\n) => {\n  const [hoveredPoint, setHoveredPoint] = useState<HoverState>(null);\n\n  const onPointMouseOver: GraphConfigInterface['onPointMouseOver'] =\n    useCallback(\n      (\n        index: number,\n        _pointPosition: [number, number],\n        event: MouseEvent | TouchEvent,\n      ) => {\n        if (hasClientCoordinates(event)) {\n          setHoveredPoint({\n            index,\n            position: calcRelativeCoordinates(event.clientX, event.clientY),\n          });\n        }\n      },\n      [calcRelativeCoordinates],\n    );\n\n  const clearHoverState = useCallback(() => setHoveredPoint(null), []);\n\n  const eventHandlers = useMemo(\n    () => ({\n      onPointMouseOver,\n      onPointMouseOut: clearHoverState,\n      onZoomStart: clearHoverState,\n      onDragStart: clearHoverState,\n    }),\n    [onPointMouseOver, clearHoverState],\n  );\n\n  return {\n    /** The current hover state, containing the index and position of the hovered point, or null if no point is hovered */\n    hoveredPoint,\n    /** Event handlers for hover-related graph interactions */\n    eventHandlers,\n  };\n};\n"]}