@datalayer/core 0.0.1 → 0.0.3

package/lib/hooks/useLocationHandles.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useLocation, useParams } from "react-router-dom";
+import { useRunStore } from "../state";
+export const useLocationHandles = () => {
+    const { accountHandle, spaceHandle } = useParams();
+    const { pathname } = useLocation();
+    const runStore = useRunStore();
+    if (pathname.startsWith("/public")) {
+        return {
+            accountHandle: runStore.iam().user?.handle,
+            spaceHandler: runStore.layout().space?.handle,
+        };
+    }
+    return {
+        accountHandle,
+        spaceHandle,
+    };
+};
+export default useLocationHandles;

package/lib/hooks/useNavigate.d.ts

@@ -0,0 +1,2 @@
+export declare const useNavigate: () => (location: string, e?: any, resetPortals?: boolean, options?: any) => void;
+export default useNavigate;

package/lib/hooks/useNavigate.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useNavigate as useRouterNavigate } from "react-router-dom";
+import { useLayoutStore } from '../state';
+export const useNavigate = () => {
+    const routerNavigate = useRouterNavigate();
+    const layoutStore = useLayoutStore();
+    const navigate = (location, e = undefined, resetPortals = true, options = undefined) => {
+        if (e) {
+            e.preventDefault();
+        }
+        if (resetPortals) {
+            layoutStore.resetLeftPortal();
+            layoutStore.resetRightPortal();
+        }
+        window.scrollTo(0, 0);
+        document.body.scrollTop = 0;
+        routerNavigate(location, options);
+    };
+    return navigate;
+};
+export default useNavigate;

package/lib/hooks/useNotebookAIAgent.d.ts

@@ -0,0 +1,8 @@
+import type { IAIAgent } from '../models';
+/**
+ * Get the document AI Agent if any.
+ *
+ * It handles checking the AI Agent is alive so it should only be use once per document.
+ */
+export declare function useNotebookAIAgent(notebookId: string): IAIAgent | undefined;
+export default useNotebookAIAgent;

package/lib/hooks/useNotebookAIAgent.js

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useEffect } from 'react';
+import { useAIAgentStore } from '../state';
+import { useAIAgents } from './useAIAgents';
+/**
+ * Get the document AI Agent if any.
+ *
+ * It handles checking the AI Agent is alive so it should only be use once per document.
+ */
+export function useNotebookAIAgent(notebookId) {
+    const { getAIAgent } = useAIAgents();
+    const { aiAgents, addAIAgent, deleteAIAgent, updateAIAgent } = useAIAgentStore();
+    // Check AI Agent is alive.
+    useEffect(() => {
+        let abortController;
+        const refreshAIAgent = async () => {
+            abortController = new AbortController();
+            try {
+                const response = await getAIAgent(notebookId, { signal: abortController.signal });
+                if (!response.success) {
+                    deleteAIAgent(notebookId);
+                    return;
+                }
+                const currentAgent = aiAgents.find(agent => agent.documentId === notebookId);
+                const runtimeId = response.agent.runtime?.id;
+                if (currentAgent) {
+                    if (currentAgent.runtimeId !== runtimeId) {
+                        updateAIAgent(notebookId, runtimeId);
+                    }
+                }
+                else {
+                    addAIAgent({
+                        documentId: notebookId,
+                        runtimeId,
+                    });
+                }
+            }
+            catch (r) {
+                deleteAIAgent(notebookId);
+            }
+        };
+        const refreshInterval = setInterval(refreshAIAgent, 60_000);
+        return () => {
+            abortController?.abort('Component unmounted');
+            clearInterval(refreshInterval);
+        };
+    }, [aiAgents, notebookId]);
+    const aiAgent = aiAgents.find(aiAgent => aiAgent.documentId === notebookId);
+    return aiAgent;
+}
+export default useNotebookAIAgent;

package/lib/hooks/useOnClickOutside.d.ts

@@ -0,0 +1 @@
+export declare function useOnClickOutside(ref: any, handler: any): void;

package/lib/hooks/useOnClickOutside.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useEffect } from 'react';
+export function useOnClickOutside(ref, handler) {
+    useEffect(() => {
+        const listener = event => {
+            // Do nothing if clicking ref's element or descendent elements
+            if (!ref.current || ref.current.contains(event.target)) {
+                return;
+            }
+            handler(event);
+        };
+        document.addEventListener('mousedown', listener);
+        document.addEventListener('touchstart', listener, { passive: true });
+        return () => {
+            document.removeEventListener('mousedown', listener);
+            document.removeEventListener('touchstart', listener);
+        };
+    }, 
+    // Add ref and handler to effect dependencies
+    // It's worth noting that because passed in handler is a new ...
+    // ... function on every render that will cause this effect ...
+    // ... callback/cleanup to run every render. It's not a big deal ...
+    // ... but to optimize you can wrap handler in useCallback before ...
+    // ... passing it into this hook.
+    [ref, handler]);
+}

package/lib/hooks/useRef.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+/**
+ * There are some situations where we only want to create a new ref if one is not provided to a component
+ * or hook as a prop. However, due to the `rules-of-hooks`, we cannot conditionally make a call to `React.useRef`
+ * only in the situations where the ref is not provided as a prop.
+ * This hook aims to encapsulate that logic, so the consumer doesn't need to be concerned with violating `rules-of-hooks`.
+ * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
+ * @type TRef The type of the RefObject which should be created.
+ */
+export declare function useProvidedRefOrCreate<TRef>(providedRef?: React.RefObject<TRef>): React.RefObject<TRef>;

package/lib/hooks/useRef.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useRef } from 'react';
+/**
+ * There are some situations where we only want to create a new ref if one is not provided to a component
+ * or hook as a prop. However, due to the `rules-of-hooks`, we cannot conditionally make a call to `React.useRef`
+ * only in the situations where the ref is not provided as a prop.
+ * This hook aims to encapsulate that logic, so the consumer doesn't need to be concerned with violating `rules-of-hooks`.
+ * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
+ * @type TRef The type of the RefObject which should be created.
+ */
+export function useProvidedRefOrCreate(providedRef) {
+    const createdRef = useRef(null);
+    return providedRef ?? createdRef;
+}

package/lib/hooks/useRuntimes.d.ts

@@ -0,0 +1,5 @@
+export declare const useRuntimes: () => {
+    mountLocalFolder: (kernelId: string) => void;
+    unmountLocalFolder: (kernelId: string) => void;
+};
+export default useRuntimes;

package/lib/hooks/useRuntimes.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { requestJupyterKernelsExtension } from '../api';
+export const useRuntimes = () => {
+    // Folder Mounting ----------------------------------------------------------
+    const mountLocalFolder = (kernelId) => {
+        requestJupyterKernelsExtension(`jump/${kernelId}`)
+            .then(data => {
+            //        console.log('--- Mount Local Folder', data);
+        })
+            .catch(reason => {
+            console.error(`Error while accessing the jupyter server jupyter_kernels extension.\n${reason}`);
+        });
+    };
+    const unmountLocalFolder = (kernelId) => {
+        requestJupyterKernelsExtension(`jump/${kernelId}`, {
+            method: 'DELETE'
+        })
+            .then(data => {
+            //        console.log('--- Unmount Local Folder', data);
+        })
+            .catch(reason => {
+            console.error(`Error while accessing the jupyter server jupyter_kernels extension.\n${reason}`);
+        });
+    };
+    // --------------------------------------------------------------------------
+    return {
+        mountLocalFolder,
+        unmountLocalFolder
+    };
+};
+export default useRuntimes;

package/lib/hooks/useScreenshot.d.ts

@@ -0,0 +1,21 @@
+type ScreenshotContextType = {
+    closeScreenshot: () => void;
+    displayScreenshot: (nextScreenshot: any) => void;
+};
+export declare const ScreenshotContext: import("react").Context<ScreenshotContextType>;
+export declare function useScreenshot(): ScreenshotContextType;
+/**
+ * The type for the Screenshot context provider.
+ */
+export declare const ScreenshotContextProvider: import("react").Provider<ScreenshotContextType>;
+type IScreenshotProviderProps = {
+    children?: JSX.Element | JSX.Element[];
+    zIndex?: number;
+    disableDarken?: boolean;
+    screenshotSurface?: (qfds: any) => JSX.Element;
+};
+export declare function ScreenshotProvider(props: IScreenshotProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ScreenshotProvider {
+    var defaultProps: IScreenshotProviderProps;
+}
+export {};

package/lib/hooks/useScreenshot.js

@@ -0,0 +1,60 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { createContext, useState, useContext } from 'react';
+import { LayoutScreenshot } from "./layouts";
+export const ScreenshotContext = createContext({
+    closeScreenshot: () => { },
+    displayScreenshot: (nextScreenshot) => { },
+});
+export function useScreenshot() {
+    const context = useContext(ScreenshotContext);
+    if (!context)
+        throw new Error('useContext must be inside a provider with a value.');
+    return context;
+}
+/**
+ * The type for the Screenshot context provider.
+ */
+export const ScreenshotContextProvider = ScreenshotContext.Provider;
+export function ScreenshotProvider(props) {
+    const { children, zIndex, disableDarken, screenshotSurface } = props;
+    const defaultScreenshotSurface = {
+        position: "fixed",
+        top: 0,
+        left: 0,
+        width: '100%',
+        height: '100%',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: disableDarken ? 'initial' : 'rgba(0, 0, 0, 0.5)',
+        zIndex,
+    };
+    const [screenshot, setScreenshot] = useState({
+        open: false,
+        render: (closeScreenshot) => _jsx(_Fragment, {})
+    });
+    const displayScreenshot = (nextScreenshot) => {
+        setScreenshot({
+            open: true,
+            render: nextScreenshot
+        });
+    };
+    const closeScreenshot = () => {
+        setScreenshot({
+            open: false,
+            render: (closeScreenshot) => _jsx(_Fragment, {})
+        });
+    };
+    return (_jsxs(ScreenshotContextProvider, { value: { closeScreenshot, displayScreenshot }, children: [_jsx(LayoutScreenshot, {}), children, screenshot.open &&
+                (screenshotSurface ? (screenshotSurface(screenshot.render(closeScreenshot))) : (_jsx("div", { style: defaultScreenshotSurface, children: screenshot.render(closeScreenshot) })))] }));
+}
+ScreenshotProvider.defaultProps = {
+    children: undefined,
+    disableScreenshot: false,
+    zIndex: 9999,
+    screenshotSurface: undefined,
+};

package/lib/hooks/useToast.d.ts

@@ -0,0 +1,42 @@
+import { type Id } from 'react-toastify';
+import { Notification } from '@jupyterlab/apputils';
+export type ToastProps = {
+    /**
+     * List of associated actions
+     */
+    actions?: Notification.IAction[];
+    /**
+     * Autoclosing behavior - false (not closing automatically) or number (time in milliseconds before hiding the notification)
+     */
+    autoClose?: number | false;
+    /**
+     * Notification type
+     */
+    variant: 'info' | 'success' | 'warning' | 'error';
+};
+export declare const useToast: () => Readonly<{
+    /**
+     * Emit a message as a toast.
+     *
+     * @param message Toast message
+     * @param options Toast option
+     * @returns Toast id
+     */
+    enqueueToast: (message: string, options?: ToastProps) => Id;
+    /**
+     * Dismiss a toast
+     *
+     * @param id Toast id
+     */
+    dismiss: (id?: Id) => void;
+    /**
+     * Track the progress of an asynchronous task
+     * and display a message depending on the outcome.
+     *
+     * @param promise Asynchronous task
+     * @param options Task progress options
+     * @returns Toast id
+     */
+    trackAsyncTask: (promise: Promise<any>, options: Notification.IPromiseOptions<any>) => string | Promise<any>;
+}>;
+export default useToast;

package/lib/hooks/useToast.js

@@ -0,0 +1,141 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import React from 'react';
+import { toast } from 'react-toastify';
+import { Notification } from '@jupyterlab/apputils';
+import { Button } from '@primer/react';
+import { isInsideJupyterLab } from '../utils';
+import { DatalayerThemeProvider } from '../theme';
+const TOAST_POSITION = toast.POSITION.BOTTOM_RIGHT;
+const displayType2Class = {
+    accent: 'primary',
+    link: 'invisible',
+    warn: 'danger',
+    default: 'default'
+};
+/**
+ * Create a button with customized callback in a toast
+ */
+function ToastButton({ action, closeToast }) {
+    const clickHandler = (event) => {
+        action.callback(event);
+        if (!event.defaultPrevented) {
+            closeToast();
+        }
+    };
+    return (_jsx(Button, { title: action.caption ?? action.label, onClick: clickHandler, variant: displayType2Class[action.displayType ?? 'default'], size: "small", children: action.label }));
+}
+/**
+ * Helper function to construct the notification content
+ *
+ * @param message Message to print in the notification
+ * @param closeHandler Function closing the notification
+ * @param actions Toast actions
+ */
+function createContent(message, closeHandler, actions) {
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "jp-toast-message", children: message.split('\n').map((part, index) => (_jsxs(React.Fragment, { children: [index > 0 ? _jsx("br", {}) : null, part] }, `part-${index}`))) }), (actions?.length ?? 0) > 0 && (_jsxs("div", { className: "jp-toast-buttonBar", children: [_jsx("div", { className: "jp-toast-spacer" }), actions.map((action, idx) => {
+                        return (_jsx(DatalayerThemeProvider, { children: _jsx(ToastButton, { action: action, closeToast: closeHandler }, 'button-' + idx) }));
+                    })] }))] }));
+}
+export const useToast = () => {
+    // This CANNOT use React hooks as it is used outside React context.
+    const insideJupyterLab = isInsideJupyterLab();
+    const enqueueToast = (message, options = { variant: 'info' }) => {
+        const { actions, autoClose } = options;
+        switch (options.variant) {
+            case 'info': {
+                return insideJupyterLab
+                    ?
+                        Notification.info(message, {
+                            autoClose: autoClose ?? 5000,
+                            actions
+                        })
+                    : toast.info(({ closeToast }) => createContent(message, () => {
+                        if (closeToast)
+                            closeToast();
+                    }, actions), { autoClose, position: TOAST_POSITION });
+            }
+            case 'success': {
+                return insideJupyterLab
+                    ? Notification.success(message, {
+                        autoClose: autoClose ?? 5000,
+                        actions
+                    })
+                    : toast.success(({ closeToast }) => createContent(message, () => {
+                        if (closeToast)
+                            closeToast();
+                    }, actions), { autoClose, position: TOAST_POSITION });
+            }
+            case 'warning': {
+                return insideJupyterLab
+                    ? Notification.warning(message, {
+                        autoClose: autoClose ?? false,
+                        actions
+                    })
+                    : toast.warning(({ closeToast }) => createContent(message, () => {
+                        if (closeToast)
+                            closeToast();
+                    }, actions), { autoClose: autoClose ?? false, position: TOAST_POSITION });
+            }
+            case 'error': {
+                return insideJupyterLab
+                    ? Notification.error(message, {
+                        autoClose: autoClose ?? false,
+                        actions
+                    })
+                    : toast.error(({ closeToast }) => createContent(message, () => {
+                        if (closeToast)
+                            closeToast();
+                    }, actions), { autoClose: autoClose ?? false, position: TOAST_POSITION });
+            }
+        }
+    };
+    const trackAsyncTask = (promise, options) => {
+        return insideJupyterLab
+            ? Notification.promise(promise, options)
+            : toast.promise(promise, {
+                error: { render: options.error.message, ...options.error.options },
+                pending: options.pending.message,
+                success: { render: options.success.message, ...options.success.options }
+            }, {
+                position: TOAST_POSITION,
+                ...options.pending.options
+            });
+    };
+    return Object.freeze({
+        /**
+         * Emit a message as a toast.
+         *
+         * @param message Toast message
+         * @param options Toast option
+         * @returns Toast id
+         */
+        enqueueToast,
+        /**
+         * Dismiss a toast
+         *
+         * @param id Toast id
+         */
+        dismiss: (id) => {
+            if (insideJupyterLab) {
+                Notification.dismiss(id);
+            }
+            else {
+                toast.dismiss(id);
+            }
+        },
+        /**
+         * Track the progress of an asynchronous task
+         * and display a message depending on the outcome.
+         *
+         * @param promise Asynchronous task
+         * @param options Task progress options
+         * @returns Toast id
+         */
+        trackAsyncTask
+    });
+};
+export default useToast;

package/lib/hooks/useUpload.d.ts

@@ -0,0 +1,7 @@
+export declare const useUploadForm: (url: string) => {
+    uploadAndSubmit: (formData: FormData) => Promise<any>;
+    isSuccess: boolean;
+    isLoading: boolean;
+    progress: number;
+    reset: () => void;
+};

package/lib/hooks/useUpload.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useState } from "react";
+import axios from "axios";
+// import useRun from "./useRun";
+import { useIAMStore } from "../state";
+// TODO reuse useRun hook.
+export const useUploadForm = (url) => {
+    const [isSuccess, setIsSuccess] = useState(false);
+    const [isLoading, setIsLoading] = useState(false);
+    const [progress, setProgress] = useState(0);
+    const { token } = useIAMStore();
+    //  const { requestRun } = useRun();
+    const reset = () => {
+        setIsSuccess(false);
+        setIsLoading(false);
+        setProgress(0);
+    };
+    const uploadAndSubmit = async (formData) => {
+        setIsLoading(true);
+        const { data } = await axios.post(url, formData, {
+            headers: {
+                "Content-Type": "multipart/form-data",
+                Authorization: `Bearer ${token}`
+            },
+            onUploadProgress: (progressEvent) => {
+                const progress = (progressEvent.loaded / progressEvent.total) * 50;
+                setProgress(progress);
+            },
+            onDownloadProgress: (progressEvent) => {
+                const progress = 50 + (progressEvent.loaded / progressEvent.total) * 50;
+                setProgress(progress);
+            },
+        });
+        setProgress(100);
+        await new Promise((resolve) => {
+            setTimeout(() => resolve("success"), 500);
+        });
+        setIsSuccess(true);
+        setProgress(0);
+        return data;
+    };
+    return { uploadAndSubmit, isSuccess, isLoading, progress, reset };
+};

package/lib/hooks/useUser.d.ts

@@ -0,0 +1,3 @@
+import { IUser, IRole } from '../models';
+export declare const useUser: (role?: IRole) => IUser;
+export default useUser;

package/lib/hooks/useUser.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useIAMStore } from '../state';
+const LOGIN_HREF = "/login";
+export const useUser = (role) => {
+    const { user } = useIAMStore();
+    if (role) {
+        if (!user?.roles.includes(role.handle)) {
+            console.log(`User should have role ${role.handle} - Forcing navigation to login page...`);
+            window.location.href = LOGIN_HREF;
+            throw new Error(`User should have role ${role.handle}`);
+        }
+    }
+    if (!user) {
+        console.log('No user found... Forcing navigation to /login');
+        window.location.href = LOGIN_HREF;
+    }
+    return user;
+};
+export default useUser;

package/lib/hooks/useVisibilityObserver.d.ts

@@ -0,0 +1,5 @@
+import { RefObject } from 'react';
+export type VisibilityMap = {
+    [key: string]: boolean;
+};
+export declare function useVisibilityObserver(navigationRef: RefObject<HTMLUListElement>, children: any): VisibilityMap[];

package/lib/hooks/useVisibilityObserver.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useState, useEffect } from 'react';
+export function useVisibilityObserver(navigationRef, children) {
+    const [visibilityMap, setVisibilityMap] = useState({});
+    const handleIntersection = (entries) => {
+        const updatedEntries = {};
+        for (const entry of entries) {
+            const navitemid = entry.target.getAttribute('data-navitemid');
+            if (navitemid) {
+                if (entry.isIntersecting) {
+                    updatedEntries[navitemid] = true;
+                }
+                else {
+                    updatedEntries[navitemid] = false;
+                }
+            }
+        }
+        setVisibilityMap(prev => ({
+            ...prev,
+            ...updatedEntries,
+        }));
+    };
+    useEffect(() => {
+        const observer = new IntersectionObserver(handleIntersection, {
+            root: navigationRef.current,
+            threshold: 1,
+        });
+        if (navigationRef.current) {
+            const navItems = Array.from(navigationRef.current.children);
+            for (const item of navItems) {
+                if (item.getAttribute('data-navitemid')) {
+                    observer.observe(item);
+                }
+            }
+        }
+        return () => observer.disconnect();
+    }, [navigationRef, children]);
+    return [visibilityMap];
+}

package/lib/hooks/useWindowSize.d.ts

@@ -0,0 +1,21 @@
+export declare enum BreakpointSize {
+    XSMALL = "xsmall",
+    SMALL = "small",
+    MEDIUM = "medium",
+    LARGE = "large",
+    XLARGE = "xlarge",
+    XXLARGE = "xxlarge"
+}
+type WindowSize = {
+    width?: number;
+    height?: number;
+    isXSmall?: boolean;
+    isSmall?: boolean;
+    isMedium?: boolean;
+    isLarge?: boolean;
+    isXLarge?: boolean;
+    isXXLarge?: boolean;
+    currentBreakpointSize?: BreakpointSize;
+};
+export declare function useWindowSize(): WindowSize;
+export {};