@sqlrooms/vega 0.5.1 → 0.7.0

package/README.md

@@ -0,0 +1,117 @@
+A package that provides Vega-Lite visualization components for the SQLRooms framework, allowing you to create interactive data visualizations directly from SQL queries.
+
+## About Vega-Lite
+
+[Vega-Lite](https://vega.github.io/vega-lite/) is a high-level grammar of interactive graphics. It provides a concise, declarative JSON syntax to create an expressive range of visualizations for data analysis and presentation.
+
+Vega-Lite specifications describe visualizations as encoding mappings from data to properties of graphical marks (e.g., points or bars). The Vega-Lite compiler automatically produces visualization components including axes, legends, and scales. This approach allows for concise specifications while giving users control to customize various parts of a visualization.
+
+This package integrates Vega-Lite with SQLRooms, allowing you to easily create data visualizations directly from SQL queries.
+
+## Components
+
+### VegaLiteChart
+
+A React component that renders a Vega-Lite chart with SQL data and responsive sizing.
+
+#### Features
+
+- **SQL-Powered**: Directly use SQL queries to fetch data for your visualizations
+- **Responsive Design**: Multiple sizing options to fit any layout
+- **Aspect Ratio Control**: Maintain visual consistency with customizable aspect ratios
+- **Integration with DuckDB**: Seamlessly works with the SQLRooms DuckDB integration
+
+#### Installation
+
+```bash
+npm install @sqlrooms/vega
+# or
+yarn add @sqlrooms/vega
+```
+
+#### Usage
+
+```tsx
+import {VegaLiteChart} from '@sqlrooms/vega';
+
+// Basic usage
+function MyChart() {
+  return (
+    <VegaLiteChart
+      sqlQuery="SELECT category, count(*) as count FROM sales GROUP BY category"
+      spec={{
+        mark: 'bar',
+        encoding: {
+          x: {field: 'category', type: 'nominal'},
+          y: {field: 'count', type: 'quantitative'},
+        },
+      }}
+    />
+  );
+}
+```
+
+#### Props
+
+| Prop          | Type                          | Default     | Description                                                           |
+| ------------- | ----------------------------- | ----------- | --------------------------------------------------------------------- |
+| `sqlQuery`    | `string`                      | (required)  | The SQL query to fetch data for the chart                             |
+| `spec`        | `string \| VisualizationSpec` | (required)  | The Vega-Lite specification for the chart                             |
+| `width`       | `number \| 'auto'`            | `'auto'`    | The chart width in pixels, or 'auto' to use container width           |
+| `height`      | `number \| 'auto'`            | `'auto'`    | The chart height in pixels, or 'auto' to calculate from aspect ratio  |
+| `aspectRatio` | `number`                      | `3/2`       | The desired width-to-height ratio when dimensions are auto-calculated |
+| `className`   | `string`                      | `undefined` | Additional CSS classes to apply to the container                      |
+
+#### Sizing Options
+
+The chart can be sized in multiple ways:
+
+- **Fixed dimensions**: Provide both width and height as numbers
+- **Fixed width, proportional height**: Provide width as number, height as 'auto'
+- **Fixed height, proportional width**: Provide height as number, width as 'auto'
+- **Fully responsive**: Leave both as 'auto' (default), chart will fill container while maintaining aspect ratio
+
+#### Examples
+
+**Fixed size chart:**
+
+```tsx
+<VegaLiteChart
+  width={600}
+  height={400}
+  sqlQuery="SELECT category, count(*) as count FROM sales GROUP BY category"
+  spec={{
+    mark: 'bar',
+    encoding: {
+      x: {field: 'category', type: 'nominal'},
+      y: {field: 'count', type: 'quantitative'},
+    },
+  }}
+/>
+```
+
+**Responsive chart with 16:9 aspect ratio:**
+
+```tsx
+<VegaLiteChart
+  className="max-w-[600px]"
+  aspectRatio={16 / 9}
+  sqlQuery="SELECT date, value FROM metrics"
+  spec={{
+    mark: 'line',
+    encoding: {
+      x: {field: 'date', type: 'temporal'},
+      y: {field: 'value', type: 'quantitative'},
+    },
+  }}
+/>
+```
+
+## Dependencies
+
+This package depends on:
+
+- `@sqlrooms/duckdb` - For SQL query execution
+- `@sqlrooms/ui` - For UI utilities
+- `@sqlrooms/utils` - For utility functions
+- `react-vega` - For rendering Vega-Lite visualizations

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * {@include ../README.md}
+ * @packageDocumentation
+ */
 export { VegaLiteChart } from './VegaLiteChart';
 export type { VisualizationSpec } from 'react-vega';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EAAC,iBAAiB,EAAC,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EAAC,iBAAiB,EAAC,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,6 @@
+/**
+ * {@include ../README.md}
+ * @packageDocumentation
+ */
 export { VegaLiteChart } from './VegaLiteChart';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC","sourcesContent":["export {VegaLiteChart} from './VegaLiteChart';\nexport type {VisualizationSpec} from 'react-vega';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC","sourcesContent":["/**\n * {@include ../README.md}\n * @packageDocumentation\n */\nexport {VegaLiteChart} from './VegaLiteChart';\nexport type {VisualizationSpec} from 'react-vega';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqlrooms/vega",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.js",
@@ -19,9 +19,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@sqlrooms/duckdb": "0.5.1",
-    "@sqlrooms/ui": "0.5.1",
-    "@sqlrooms/utils": "0.5.1",
+    "@sqlrooms/duckdb": "0.7.0",
+    "@sqlrooms/ui": "0.7.0",
+    "@sqlrooms/utils": "0.7.0",
     "react-vega": "^7.6.0",
     "vega": "^5.31.0",
     "vega-lite": "^5.23.0"
@@ -36,5 +36,5 @@
     "lint": "eslint .",
     "typedoc": "typedoc"
   },
-  "gitHead": "5e41362f1552ee1f8a661c487fe7cdb606cc6d23"
+  "gitHead": "8be65f051c588d3a963f721322429657913b6c63"
 }

package/dist/hooks/useChartDimensions.d.ts

@@ -1,50 +0,0 @@
-/**
- * Represents the dimensions of a chart
- * @interface ChartDimensions
- * @property {number} width - The width of the chart in pixels
- * @property {number} height - The height of the chart in pixels
- */
-export interface ChartDimensions {
-    width: number;
-    height: number;
-}
-/**
- * Props for the useChartDimensions hook
- * @interface UseChartDimensionsProps
- * @property {number | 'auto'} width - The explicitly provided width, or 'auto' for container-based width
- * @property {number | 'auto'} height - The explicitly provided height, or 'auto' for aspect ratio-based height
- * @property {number} aspectRatio - The desired width-to-height ratio when dimensions are auto-calculated
- * @property {React.RefObject<HTMLElement>} containerRef - Reference to the container element
- */
-export interface UseChartDimensionsProps {
-    width: number | 'auto';
-    height: number | 'auto';
-    aspectRatio: number;
-    containerRef: React.RefObject<HTMLElement>;
-}
-/**
- * A hook that calculates chart dimensions based on provided values and container size
- *
- * This hook handles various combinations of width/height specifications:
- * - If both width and height are provided, uses those exact dimensions
- * - If only width is provided, calculates height using the aspect ratio
- * - If only height is provided, calculates width using the aspect ratio
- * - If both are 'auto', uses container width and calculates height using the aspect ratio
- *
- * @param {UseChartDimensionsProps} props - The input parameters for dimension calculation
- * @returns {ChartDimensions} The calculated width and height
- *
- * @example
- * ```tsx
- * const containerRef = useRef<HTMLDivElement>(null);
- * const {width, height} = useChartDimensions({
- *   width: 'auto',
- *   height: 'auto',
- *   aspectRatio: 16/9,
- *   containerRef
- * });
- * // Returns dimensions based on container size
- * ```
- */
-export declare function useChartDimensions({ width, height, aspectRatio, containerRef, }: UseChartDimensionsProps): ChartDimensions;
-//# sourceMappingURL=useChartDimensions.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"useChartDimensions.d.ts","sourceRoot":"","sources":["../../src/hooks/useChartDimensions.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,MAAM,EACN,WAAW,EACX,YAAY,GACb,EAAE,uBAAuB,GAAG,eAAe,CAoB3C"}

package/dist/hooks/useChartDimensions.js

@@ -1,47 +0,0 @@
-import { useMemo } from 'react';
-import { useResizeObserver } from 'usehooks-ts';
-/**
- * A hook that calculates chart dimensions based on provided values and container size
- *
- * This hook handles various combinations of width/height specifications:
- * - If both width and height are provided, uses those exact dimensions
- * - If only width is provided, calculates height using the aspect ratio
- * - If only height is provided, calculates width using the aspect ratio
- * - If both are 'auto', uses container width and calculates height using the aspect ratio
- *
- * @param {UseChartDimensionsProps} props - The input parameters for dimension calculation
- * @returns {ChartDimensions} The calculated width and height
- *
- * @example
- * ```tsx
- * const containerRef = useRef<HTMLDivElement>(null);
- * const {width, height} = useChartDimensions({
- *   width: 'auto',
- *   height: 'auto',
- *   aspectRatio: 16/9,
- *   containerRef
- * });
- * // Returns dimensions based on container size
- * ```
- */
-export function useChartDimensions({ width, height, aspectRatio, containerRef, }) {
-    const { width: containerWidth = 0 } = useResizeObserver({
-        ref: containerRef,
-        box: 'border-box',
-    });
-    return useMemo(() => {
-        if (width !== 'auto' && height !== 'auto') {
-            return { width, height };
-        }
-        if (width !== 'auto') {
-            return { width, height: width / aspectRatio };
-        }
-        if (height !== 'auto') {
-            return { width: height * aspectRatio, height };
-        }
-        const finalWidth = containerWidth;
-        const finalHeight = finalWidth / aspectRatio;
-        return { width: finalWidth, height: finalHeight };
-    }, [containerWidth, aspectRatio, width, height]);
-}
-//# sourceMappingURL=useChartDimensions.js.map

package/dist/hooks/useChartDimensions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"useChartDimensions.js","sourceRoot":"","sources":["../../src/hooks/useChartDimensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,EAAC,MAAM,OAAO,CAAC;AAC9B,OAAO,EAAC,iBAAiB,EAAC,MAAM,aAAa,CAAC;AA4B9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,kBAAkB,CAAC,EACjC,KAAK,EACL,MAAM,EACN,WAAW,EACX,YAAY,GACY;IACxB,MAAM,EAAC,KAAK,EAAE,cAAc,GAAG,CAAC,EAAC,GAAG,iBAAiB,CAAC;QACpD,GAAG,EAAE,YAAY;QACjB,GAAG,EAAE,YAAY;KAClB,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,IAAI,KAAK,KAAK,MAAM,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YAC1C,OAAO,EAAC,KAAK,EAAE,MAAM,EAAC,CAAC;QACzB,CAAC;QACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YACrB,OAAO,EAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAG,WAAW,EAAC,CAAC;QAC9C,CAAC;QACD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACtB,OAAO,EAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,MAAM,EAAC,CAAC;QAC/C,CAAC;QACD,MAAM,UAAU,GAAG,cAAc,CAAC;QAClC,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,CAAC;QAC7C,OAAO,EAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAC,CAAC;IAClD,CAAC,EAAE,CAAC,cAAc,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;AACnD,CAAC"}

package/dist/vega-lite-chart.d.ts

@@ -1,16 +0,0 @@
-import { VisualizationSpec } from 'react-vega';
-/**
- * A component that renders a Vega-Lite chart.
- * @see Vega Lite Chart - https://vega.github.io/vega-lite/
- * @param props - The props for the component.
- * @returns The component.
- * @example
- * <VegaLiteChart sqlQuery="SELECT * FROM my_table" spec={spec} />
- */
-export declare const VegaLiteChart: React.FC<{
-    width?: number;
-    height?: number;
-    sqlQuery: string;
-    spec: string | VisualizationSpec;
-}>;
-//# sourceMappingURL=vega-lite-chart.d.ts.map

package/dist/vega-lite-chart.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"vega-lite-chart.d.ts","sourceRoot":"","sources":["../src/vega-lite-chart.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAW,iBAAiB,EAAC,MAAM,YAAY,CAAC;AAIvD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAAC;CAClC,CAyBA,CAAC"}

package/dist/vega-lite-chart.js

@@ -1,38 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { safeJsonParse } from '@sqlrooms/utils';
-import { arrowTableToJson, useDuckDb } from '@sqlrooms/duckdb';
-import { useEffect, useMemo, useState } from 'react';
-import { VegaLite } from 'react-vega';
-const DATA_NAME = 'queryResult';
-/**
- * A component that renders a Vega-Lite chart.
- * @see Vega Lite Chart - https://vega.github.io/vega-lite/
- * @param props - The props for the component.
- * @returns The component.
- * @example
- * <VegaLiteChart sqlQuery="SELECT * FROM my_table" spec={spec} />
- */
-export const VegaLiteChart = ({ width, height, sqlQuery, spec }) => {
-    const { conn } = useDuckDb();
-    const [data, setData] = useState();
-    const refinedSpec = useMemo(() => {
-        const parsed = typeof spec === 'string' ? safeJsonParse(spec) : spec;
-        if (!parsed)
-            return null;
-        return {
-            ...parsed,
-            data: { name: DATA_NAME },
-        };
-    }, [spec]);
-    useEffect(() => {
-        const fetchData = async () => {
-            const result = await conn.query(sqlQuery);
-            setData({ [DATA_NAME]: arrowTableToJson(result) });
-        };
-        fetchData();
-    }, [sqlQuery, conn]);
-    if (!refinedSpec || !data)
-        return null;
-    return (_jsx("div", { className: "w-full flex flex-col gap-2 overflow-hidden", children: _jsx(VegaLite, { spec: refinedSpec, data: data, width: width, height: height }) }));
-};
-//# sourceMappingURL=vega-lite-chart.js.map

package/dist/vega-lite-chart.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"vega-lite-chart.js","sourceRoot":"","sources":["../src/vega-lite-chart.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAC,MAAM,OAAO,CAAC;AACnD,OAAO,EAAC,QAAQ,EAAoB,MAAM,YAAY,CAAC;AAEvD,MAAM,SAAS,GAAG,aAAa,CAAC;AAEhC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAKrB,CAAC,EAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAC,EAAE,EAAE;IACvC,MAAM,EAAC,IAAI,EAAC,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,EAA2B,CAAC;IAC5D,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE;QAC/B,MAAM,MAAM,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACrE,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACzB,OAAO;YACL,GAAG,MAAM;YACT,IAAI,EAAE,EAAC,IAAI,EAAE,SAAS,EAAC;SACH,CAAC;IACzB,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACX,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,SAAS,GAAG,KAAK,IAAI,EAAE;YAC3B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC1C,OAAO,CAAC,EAAC,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAC,CAAC,CAAC;QACnD,CAAC,CAAC;QACF,SAAS,EAAE,CAAC;IACd,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAErB,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,CACL,cAAK,SAAS,EAAC,4CAA4C,YACzD,KAAC,QAAQ,IAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAI,GACrE,CACP,CAAC;AACJ,CAAC,CAAC"}