@kanaries/graphic-walker 0.3.10 → 0.3.12

package/dist/interfaces.d.ts

@@ -1,4 +1,4 @@
-import { Config as VgConfig } from 'vega';
+import { Config as VgConfig, View } from 'vega';
 import { Config as VlConfig } from 'vega-lite';
 export type DeepReadonly<T extends Record<keyof any, any>> = {
     readonly [K in keyof T]: T[K] extends Record<keyof any, any> ? DeepReadonly<T[K]> : T[K];
@@ -191,6 +191,16 @@ export declare enum ISegmentKey {
 export type IThemeKey = 'vega' | 'g2';
 export type IDarkMode = 'media' | 'light' | 'dark';
 export type VegaGlobalConfig = VgConfig | VlConfig;
+export interface IVegaChartRef {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    innerWidth: number;
+    innerHeight: number;
+    view: View;
+    canvas: HTMLCanvasElement | null;
+}
 export interface IChartExportResult<T extends 'svg' | 'data-url' = 'svg' | 'data-url'> {
     mode: T;
     title: string;
@@ -201,14 +211,81 @@ export interface IChartExportResult<T extends 'svg' | 'data-url' = 'svg' | 'data
         rowIndex: number;
         width: number;
         height: number;
+        canvasWidth: number;
+        canvasHeight: number;
         data: string;
+        canvas(): HTMLCanvasElement | null;
     }[];
+    container(): HTMLDivElement | null;
 }
 interface IExportChart {
     <T extends Extract<IChartExportResult['mode'], 'svg'>>(mode?: T): Promise<IChartExportResult<T>>;
     <T extends IChartExportResult['mode']>(mode: T): Promise<IChartExportResult<T>>;
 }
+export interface IChartListExportResult<T extends 'svg' | 'data-url' = 'svg' | 'data-url'> {
+    mode: T;
+    total: number;
+    index: number;
+    data: IChartExportResult<T>;
+    hasNext: boolean;
+}
+interface IExportChartList {
+    <T extends Extract<IChartExportResult['mode'], 'svg'>>(mode?: T): AsyncGenerator<IChartListExportResult<T>, void, unknown>;
+    <T extends IChartExportResult['mode']>(mode: T): AsyncGenerator<IChartListExportResult<T>, void, unknown>;
+}
+/**
+ * The status of the current chart.
+ * * `computing`: _GraphicWalker_ is computing the data view.
+ * * `rendering`: _GraphicWalker_ is rendering the chart.
+ * * `idle`: rendering is finished.
+ * * `error`: an error occurs during the process above.
+ */
+export type IRenderStatus = 'computing' | 'rendering' | 'idle' | 'error';
 export interface IGWHandler {
+    /** length of the "chart" tab list */
+    chartCount: number;
+    /** current selected chart index */
+    chartIndex: number;
+    /** Switches to the specified chart */
+    openChart: (index: number) => void;
+    /**
+     * Returns the status of the current chart.
+     *
+     * It is computed by the following rules:
+     * - If _GraphicWalker_ is computing the data view, it returns `computing`.
+     * - If _GraphicWalker_ is rendering the chart, it returns `rendering`.
+     * - If rendering is finished, it returns `idle`.
+     * - If an error occurs during the process above, it returns `error`.
+     */
+    get renderStatus(): IRenderStatus;
+    /**
+     * Registers a callback function to listen to the status change of the current chart.
+     *
+     * @param {(renderStatus: IRenderStatus) => void} cb - the callback function
+     * @returns {() => void} a dispose function to remove this callback
+     */
+    onRenderStatusChange: (cb: (renderStatus: IRenderStatus) => void) => (() => void);
+    /**
+     * Exports the current chart.
+     *
+     * @param {IChartExportResult['mode']} [mode='svg'] - the export mode, either `svg` or `data-url`
+     */
     exportChart: IExportChart;
+    /**
+     * Exports all charts.
+     *
+     * @param {IChartExportResult['mode']} [mode='svg'] - the export mode, either `svg` or `data-url`
+     * @returns {AsyncGenerator<IChartListExportResult, void, unknown>} an async generator to iterate over all charts
+     * @example
+     * ```ts
+     * for await (const chart of gwRef.current.exportChartList()) {
+     *     console.log(chart);
+     * }
+     * ```
+     */
+    exportChartList: IExportChartList;
+}
+export interface IGWHandlerInsider extends IGWHandler {
+    updateRenderStatus: (renderStatus: IRenderStatus) => void;
 }
 export {};

package/dist/renderer/pureRenderer.d.ts

@@ -1,13 +1,5 @@
-import React from 'react';
-import type { IDarkMode, IRow, IThemeKey, DraggableFieldState, IVisualConfig } from '../interfaces';
-import type { IReactVegaHandler } from '../vis/react-vega';
-interface IPureRendererProps {
-    name?: string;
-    themeKey?: IThemeKey;
-    dark?: IDarkMode;
-    rawData?: IRow[];
-    visualState: DraggableFieldState;
-    visualConfig: IVisualConfig;
-}
-declare const _default: React.MemoExoticComponent<React.ForwardRefExoticComponent<Pick<IPureRendererProps & React.RefAttributes<IReactVegaHandler>, "key" | keyof IPureRendererProps> & React.RefAttributes<IReactVegaHandler>>>;
+/// <reference types="react" />
+declare const _default: ((props: object) => JSX.Element) & {
+    displayName: string;
+};
 export default _default;

package/dist/utils/chartIndexControl.d.ts

@@ -0,0 +1,7 @@
+interface IUseChartIndexControlOptions {
+    count: number;
+    index: number;
+    onChange: (index: number) => void;
+}
+export declare const useChartIndexControl: (options: IUseChartIndexControlOptions) => void;
+export {};

package/dist/utils/vegaApiExport.d.ts

@@ -1,10 +1,4 @@
-import { type ForwardedRef, type MutableRefObject } from "react";
-import type { View } from "vega";
+import { type ForwardedRef, type MutableRefObject, RefObject } from "react";
 import type { IReactVegaHandler } from "../vis/react-vega";
-export declare const useVegaExportApi: (name: string | undefined, viewsRef: MutableRefObject<{
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-    view: View;
-}[]>, ref: ForwardedRef<IReactVegaHandler>) => void;
+import type { IVegaChartRef } from "../interfaces";
+export declare const useVegaExportApi: (name: string | undefined, viewsRef: MutableRefObject<IVegaChartRef[]>, ref: ForwardedRef<IReactVegaHandler>, renderTaskRefs: MutableRefObject<Promise<unknown>[]>, containerRef: RefObject<HTMLDivElement>) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanaries/graphic-walker",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "scripts": {
     "dev:front_end": "vite --host",
     "dev": "npm run dev:front_end",
@@ -36,7 +36,6 @@
   "dependencies": {
     "@headlessui/react": "^1.7.12",
     "@heroicons/react": "^2.0.8",
-    "@kanaries/graphic-walker": "0.3.9",
     "@kanaries/react-beautiful-dnd": "0.0.2",
     "@kanaries/web-data-loader": "^0.1.7",
     "autoprefixer": "^10.3.5",

package/src/components/appRoot.tsx

@@ -1,24 +1,72 @@
-import React, { createContext, forwardRef, useImperativeHandle, type ForwardedRef, useContext } from "react";
-import type { IGWHandler } from "../interfaces";
+import React, { createContext, forwardRef, useImperativeHandle, type ForwardedRef, useContext, type ComponentType, type RefObject } from "react";
+import type { IChartExportResult, IGWHandler, IGWHandlerInsider, IRenderStatus } from "../interfaces";
 
-const AppRootContext = createContext<ForwardedRef<IGWHandler>>(null!);
+const AppRootContext = createContext<ForwardedRef<IGWHandlerInsider>>(null);
 
-export const useAppRootContext = () => {
-    return useContext(AppRootContext);
+export const useAppRootContext = (): RefObject<IGWHandlerInsider> => {
+    const context = useContext(AppRootContext);
+    if (context && 'current' in context) {
+        return context;
+    }
+    return {
+        current: null,
+    };
 };
 
-const AppRoot = forwardRef<IGWHandler, { children: any }>(({ children }, ref) => {
+const AppRoot = forwardRef<IGWHandlerInsider, { children: any }>(({ children }, ref) => {
     useImperativeHandle(ref, () => {
+        let renderStatus: IRenderStatus = 'idle';
+        let onRenderStatusChangeHandlers: ((status: IRenderStatus) => void)[] = [];
+        const addRenderStatusChangeListener = (cb: typeof onRenderStatusChangeHandlers[number]): (() => void) => {
+            onRenderStatusChangeHandlers.push(cb);
+            const dispose = () => {
+                onRenderStatusChangeHandlers = onRenderStatusChangeHandlers.filter(which => which !== cb);
+            };
+            return dispose;
+        };
+        const updateRenderStatus = (status: IRenderStatus) => {
+            if (renderStatus === status) {
+                return;
+            }
+            renderStatus = status;
+            onRenderStatusChangeHandlers.forEach(cb => cb(renderStatus));
+        };
         return {
-            exportChart: (async mode => {
+            get renderStatus() {
+                return renderStatus;
+            },
+            onRenderStatusChange: addRenderStatusChangeListener,
+            updateRenderStatus,
+            chartCount: 1,
+            chartIndex: 0,
+            openChart() {},
+            exportChart: (async (mode: IChartExportResult['mode'] = 'svg') => {
                 return {
                     mode,
                     title: '',
                     nCols: 0,
                     nRows: 0,
                     charts: [],
+                    container: () => null,
                 };
             }) as IGWHandler['exportChart'],
+            exportChartList: (async function * exportChartList (mode: IChartExportResult['mode'] = 'svg') {
+                yield {
+                    mode,
+                    total: 1,
+                    completed: 0,
+                    index: 0,
+                    data: {
+                        mode,
+                        title: '',
+                        nCols: 0,
+                        nRows: 0,
+                        charts: [],
+                        container: () => null,
+                    },
+                    hasNext: false,
+                };
+            }) as IGWHandler['exportChartList'],
         };
     }, []);
 
@@ -29,4 +77,14 @@ const AppRoot = forwardRef<IGWHandler, { children: any }>(({ children }, ref) =>
     );
 });
 
+export const withAppRoot = <P extends object>(Component: ComponentType<any>) => {
+    return (props: P) => {
+        return (
+            <AppRoot>
+                <Component {...props} />
+            </AppRoot>
+        );
+    };
+};
+
 export default AppRoot;

package/src/index.tsx

@@ -1,4 +1,4 @@
-import React, { forwardRef } from "react";
+import React, { type ForwardedRef, forwardRef } from "react";
 import { DOM } from "@kanaries/react-beautiful-dnd";
 import { observer } from "mobx-react-lite";
 import App, { IGWProps } from "./App";
@@ -6,7 +6,7 @@ import { StoreWrapper } from "./store/index";
 import { FieldsContextWrapper } from "./fields/fieldsContext";
 import { ShadowDom } from "./shadow-dom";
 import AppRoot from "./components/appRoot";
-import type { IGWHandler } from "./interfaces";
+import type { IGWHandler, IGWHandlerInsider } from "./interfaces";
 
 import "./empty_sheet.css";
 
@@ -24,7 +24,7 @@ export const GraphicWalker = observer(forwardRef<IGWHandler, IGWProps>((props, r
 
     return (
         <StoreWrapper keepAlive={props.keepAlive} storeRef={storeRef}>
-            <AppRoot ref={ref}>
+            <AppRoot ref={ref as ForwardedRef<IGWHandlerInsider>}>
                 <ShadowDom onMount={handleMount} onUnmount={handleUnmount}>
                     <FieldsContextWrapper>
                         <App {...props} />

package/src/interfaces.ts

@@ -1,4 +1,4 @@
-import {Config as VgConfig} from 'vega';
+import {Config as VgConfig, View} from 'vega';
 import {Config as VlConfig} from 'vega-lite';
 
 export type DeepReadonly<T extends Record<keyof any, any>> = {
@@ -225,6 +225,17 @@ export type IDarkMode = 'media' | 'light' | 'dark';
 
 export type VegaGlobalConfig = VgConfig | VlConfig;
 
+export interface IVegaChartRef {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    innerWidth: number;
+    innerHeight: number;
+    view: View;
+    canvas: HTMLCanvasElement | null;
+}
+
 export interface IChartExportResult<T extends 'svg' | 'data-url' = 'svg' | 'data-url'> {
     mode: T;
     title: string;
@@ -235,8 +246,12 @@ export interface IChartExportResult<T extends 'svg' | 'data-url' = 'svg' | 'data
         rowIndex: number;
         width: number;
         height: number;
+        canvasWidth: number;
+        canvasHeight: number;
         data: string;
+        canvas(): HTMLCanvasElement | null;
     }[];
+    container(): HTMLDivElement | null;
 }
 
 interface IExportChart {
@@ -244,6 +259,73 @@ interface IExportChart {
     <T extends IChartExportResult['mode']>(mode: T): Promise<IChartExportResult<T>>;
 }
 
+export interface IChartListExportResult<T extends 'svg' | 'data-url' = 'svg' | 'data-url'> {
+    mode: T;
+    total: number;
+    index: number;
+    data: IChartExportResult<T>;
+    hasNext: boolean;
+}
+
+interface IExportChartList {
+    <T extends Extract<IChartExportResult['mode'], 'svg'>>(mode?: T): AsyncGenerator<IChartListExportResult<T>, void, unknown>;
+    <T extends IChartExportResult['mode']>(mode: T): AsyncGenerator<IChartListExportResult<T>, void, unknown>;
+}
+
+/**
+ * The status of the current chart.
+ * * `computing`: _GraphicWalker_ is computing the data view.
+ * * `rendering`: _GraphicWalker_ is rendering the chart.
+ * * `idle`: rendering is finished.
+ * * `error`: an error occurs during the process above.
+ */
+export type IRenderStatus = 'computing' | 'rendering' | 'idle' | 'error';
+
 export interface IGWHandler {
+    /** length of the "chart" tab list */
+    chartCount: number;
+    /** current selected chart index */
+    chartIndex: number;
+    /** Switches to the specified chart */
+    openChart: (index: number) => void;
+    /**
+     * Returns the status of the current chart.
+     * 
+     * It is computed by the following rules:
+     * - If _GraphicWalker_ is computing the data view, it returns `computing`.
+     * - If _GraphicWalker_ is rendering the chart, it returns `rendering`.
+     * - If rendering is finished, it returns `idle`.
+     * - If an error occurs during the process above, it returns `error`.
+     */
+    get renderStatus(): IRenderStatus;
+    /**
+     * Registers a callback function to listen to the status change of the current chart.
+     * 
+     * @param {(renderStatus: IRenderStatus) => void} cb - the callback function
+     * @returns {() => void} a dispose function to remove this callback
+     */
+    onRenderStatusChange: (cb: (renderStatus: IRenderStatus) => void) => (() => void);
+    /**
+     * Exports the current chart.
+     * 
+     * @param {IChartExportResult['mode']} [mode='svg'] - the export mode, either `svg` or `data-url`
+     */
     exportChart: IExportChart;
+    /**
+     * Exports all charts.
+     * 
+     * @param {IChartExportResult['mode']} [mode='svg'] - the export mode, either `svg` or `data-url`
+     * @returns {AsyncGenerator<IChartListExportResult, void, unknown>} an async generator to iterate over all charts
+     * @example
+     * ```ts
+     * for await (const chart of gwRef.current.exportChartList()) {
+     *     console.log(chart);
+     * }
+     * ```
+     */
+    exportChartList: IExportChartList;
+}
+
+export interface IGWHandlerInsider extends IGWHandler {
+    updateRenderStatus: (renderStatus: IRenderStatus) => void;
 }

package/src/renderer/hooks.ts

@@ -3,6 +3,7 @@ import { unstable_batchedUpdates } from 'react-dom';
 import type { DeepReadonly, IFilterField, IRow, IViewField } from '../interfaces';
 import { applyFilter, applyViewQuery, transformDataService } from '../services';
 import { getMeaAggKey } from '../utils';
+import { useAppRootContext } from '../components/appRoot';
 
 
 interface UseRendererProps {
@@ -26,8 +27,11 @@ export const useRenderer = (props: UseRendererProps): UseRendererResult => {
 
     const [viewData, setViewData] = useState<IRow[]>([]);
 
+    const appRef = useAppRootContext();
+
     useEffect(() => {
         const taskId = ++taskIdRef.current;
+        appRef.current?.updateRenderStatus('computing');
         setComputing(true);
         applyFilter(data, filters)
             .then((data) => {
@@ -53,6 +57,7 @@ export const useRenderer = (props: UseRendererProps): UseRendererResult => {
                 if (taskId !== taskIdRef.current) {
                     return;
                 }
+                appRef.current?.updateRenderStatus('rendering');
                 unstable_batchedUpdates(() => {
                     setComputing(false);
                     setViewData(data);
@@ -61,6 +66,7 @@ export const useRenderer = (props: UseRendererProps): UseRendererResult => {
                 if (taskId !== taskIdRef.current) {
                     return;
                 }
+                appRef.current?.updateRenderStatus('error');
                 console.error(err);
                 unstable_batchedUpdates(() => {
                     setComputing(false);

package/src/renderer/index.tsx

@@ -8,6 +8,7 @@ import { IReactVegaHandler } from '../vis/react-vega';
 import { unstable_batchedUpdates } from 'react-dom';
 import { useRenderer } from './hooks';
 import { initEncoding, initVisualConfig } from '../store/visualSpecStore';
+import { useChartIndexControl } from '../utils/chartIndexControl';
 
 interface RendererProps {
     themeKey?: IThemeKey;
@@ -60,6 +61,12 @@ const Renderer = forwardRef<IReactVegaHandler, RendererProps>(function (props, r
         }
     }, [waiting, vizStore]);
 
+    useChartIndexControl({
+        count: visList.length,
+        index: visIndex,
+        onChange: idx => vizStore.selectVisualization(idx),
+    });
+
     const handleGeomClick = useCallback(
         (values: any, e: any) => {
             e.stopPropagation();

package/src/renderer/pureRenderer.tsx

@@ -3,7 +3,7 @@ import { unstable_batchedUpdates } from 'react-dom';
 import { toJS } from 'mobx';
 import { observer } from 'mobx-react-lite';
 import { ShadowDom } from '../shadow-dom';
-import AppRoot from '../components/appRoot';
+import { withAppRoot } from '../components/appRoot';
 import type { IDarkMode, IViewField, IRow, IThemeKey, DraggableFieldState, IVisualConfig } from '../interfaces';
 import type { IReactVegaHandler } from '../vis/react-vega';
 import SpecRenderer from './specRenderer';
@@ -79,23 +79,21 @@ const PureRenderer = forwardRef<IReactVegaHandler, IPureRendererProps>(function
     }, [waiting]);
 
     return (
-        <AppRoot>
-            <ShadowDom>
-                <div className="relative">
-                    <SpecRenderer
-                        name={name}
-                        loading={waiting}
-                        data={viewData}
-                        ref={ref}
-                        themeKey={themeKey}
-                        dark={dark}
-                        draggableFieldState={visualState}
-                        visualConfig={visualConfig}
-                    />
-                </div>
-            </ShadowDom>
-        </AppRoot>
+        <ShadowDom>
+            <div className="relative">
+                <SpecRenderer
+                    name={name}
+                    loading={waiting}
+                    data={viewData}
+                    ref={ref}
+                    themeKey={themeKey}
+                    dark={dark}
+                    draggableFieldState={visualState}
+                    visualConfig={visualConfig}
+                />
+            </div>
+        </ShadowDom>
     );
 });
 
-export default observer(PureRenderer);
+export default observer(withAppRoot(PureRenderer));

package/src/utils/chartIndexControl.ts

@@ -0,0 +1,39 @@
+import { useEffect } from "react";
+import { useAppRootContext } from "../components/appRoot";
+
+
+interface IUseChartIndexControlOptions {
+    count: number;
+    index: number;
+    onChange: (index: number) => void;
+}
+
+export const useChartIndexControl = (options: IUseChartIndexControlOptions): void => {
+    const appRef = useAppRootContext();
+    
+    useEffect(() => {
+        if (appRef.current) {
+            appRef.current.chartCount = options.count;
+            appRef.current.chartIndex = options.index;
+            appRef.current.openChart = function (index: number) {
+                if (index === this.chartIndex) {
+                    return;
+                } else if (Number.isInteger(index) && index >= 0 && index < this.chartCount) {
+                    options.onChange(index);
+                } else {
+                    console.warn(`Invalid chart index: ${index}`);
+                }
+            };
+        }
+    });
+
+    useEffect(() => {
+        return () => {
+            if (appRef.current) {
+                appRef.current.chartCount = 1;
+                appRef.current.chartIndex = 0;
+                appRef.current.openChart = () => {};
+            }
+        };
+    }, []);
+};