@datalayer/core 0.0.1 → 0.0.2

package/lib/hooks/useCellOutputshot.d.ts

@@ -0,0 +1,4 @@
+declare const useCellOutputshot: () => (string | ((node: HTMLDivElement) => void) | {
+    error: undefined;
+})[];
+export default useCellOutputshot;

package/lib/hooks/useCellOutputshot.js

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+import { useState } from 'react';
+import { useCellStore } from '../state';
+import { takeHTMLNodeScreenshot } from '../utils/Screenshot';
+const useCellOutputshot = () => {
+    const [outputshot, setOutputshot] = useState('');
+    const [error, setError] = useState();
+    const { update } = useCellStore();
+    const takeOutputshot = (node) => {
+        takeHTMLNodeScreenshot(node).then(outputshotData => {
+            setOutputshot(outputshotData);
+            update({
+                outputshotData,
+            });
+            return outputshotData;
+        })
+            .catch(reason => setError(reason));
+    };
+    return [
+        outputshot,
+        takeOutputshot,
+        { error }
+    ];
+};
+export default useCellOutputshot;

package/lib/hooks/useContainsFocus.d.ts

@@ -0,0 +1,9 @@
+import { type RefObject } from 'react';
+/**
+ * Determine if a child element of the provided ref is currently focussed.
+ * @param containerRef The ref to the container element.
+ * @param onFocusChange The callback to be called when the focus state changes.
+ * @type T The type of the container element.
+ * @returns The ref to be applied to the container element.
+ */
+export declare const useContainsFocus: <T extends HTMLElement>(containerRef?: RefObject<T>, onFocusChange?: (isFocussed: boolean) => void) => void;

package/lib/hooks/useContainsFocus.js

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+import { useCallback, useEffect, useState } from 'react';
+/**
+ * Determine if a child element of the provided ref is currently focussed.
+ * @param containerRef The ref to the container element.
+ * @param onFocusChange The callback to be called when the focus state changes.
+ * @type T The type of the container element.
+ * @returns The ref to be applied to the container element.
+ */
+export const useContainsFocus = (containerRef, onFocusChange) => {
+    const [isChildFocused, setIsChildFocused] = useState(false);
+    const updateState = useCallback((isFocused) => {
+        if (isFocused !== isChildFocused) {
+            setIsChildFocused(isFocused);
+            onFocusChange?.(isFocused);
+        }
+    }, [isChildFocused, onFocusChange]);
+    useEffect(() => {
+        if (!containerRef) {
+            return;
+        }
+        const handleFocusIn = () => {
+            updateState(true);
+        };
+        const handleFocusOut = (event) => {
+            if (containerRef.current && !containerRef.current.contains(event.relatedTarget)) {
+                updateState(false);
+            }
+        };
+        const container = containerRef.current;
+        if (container) {
+            container.addEventListener('focusin', handleFocusIn, true);
+            container.addEventListener('focusout', handleFocusOut, true);
+            return () => {
+                container.removeEventListener('focusin', handleFocusIn, true);
+                container.removeEventListener('focusout', handleFocusOut, true);
+            };
+        }
+    }, [updateState, containerRef]);
+};

package/lib/hooks/useError.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+export declare const ErrorMessage: React.FC<{
+    message: Array<string> | string | null;
+}>;
+export declare const useError: (initialState: string | null) => {
+    error: string | null;
+    showError: (errorMessage: string | null) => void;
+};
+export default useError;

package/lib/hooks/useError.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+import { useState } from "react";
+import { Flash } from '@primer/react';
+export const ErrorMessage = ({ message }) => {
+    if (message instanceof Array) {
+        return _jsx("div", { children: message.map((m, i) => _jsx(Flash, { variant: "danger", children: m }, i)) });
+    }
+    else {
+        return _jsx(Flash, { variant: "danger", children: message });
+    }
+};
+export const useError = (initialState) => {
+    const [error, setError] = useState(initialState);
+    const showError = (errorMessage) => {
+        setError(errorMessage);
+        window.setTimeout(() => {
+            setError(null);
+        }, 3000);
+    };
+    return { error, showError };
+};
+export default useError;

package/lib/hooks/useExternalScript.d.ts

@@ -0,0 +1,2 @@
+declare const useExternalScript: (url: string) => void;
+export default useExternalScript;

package/lib/hooks/useExternalScript.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+import { useEffect } from "react";
+const useExternalScript = (url) => {
+    useEffect(() => {
+        const head = document.querySelector("head");
+        const script = document.createElement("script");
+        script.setAttribute("src", url);
+        head.appendChild(script);
+        return () => {
+            head.removeChild(script);
+        };
+    }, [url]);
+};
+export default useExternalScript;

package/lib/hooks/useFocusTrap.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+export interface FocusTrapHookSettings {
+    /**
+     * Ref that will be used for the trapping container. If not provided, one will
+     * be created by this hook and returned.
+     */
+    containerRef: React.RefObject<HTMLElement>;
+    /**
+     * Ref for the element that should receive focus when the focus trap is first enabled.
+     * If not provided, one will be created by this hook and returned. Its use is optional.
+     */
+    initialFocusRef?: React.RefObject<HTMLElement>;
+    /**
+     * Set to true to disable the focus trap and clean up listeners. Can be re-enabled at any time.
+     */
+    disabled?: boolean;
+    /**
+     * If true, when this focus trap is cleaned up, restore focus to the element that had focus immediately before the focus trap was enabled. (Default: false)
+     */
+    restoreFocusOnCleanUp?: boolean;
+}
+/**
+ * Hook used to trap focus inside a container. Returns a ref that can be added to the container
+ * that should trap focus.
+ * @param settings {FocusTrapHookSettings}
+ */
+export declare function useFocusTrap(settings?: FocusTrapHookSettings, dependencies?: React.DependencyList): {
+    containerRef: React.RefObject<HTMLElement> | undefined;
+    initialFocusRef: React.RefObject<HTMLElement> | undefined;
+};

package/lib/hooks/useFocusTrap.js

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+import React from 'react';
+import { focusTrap } from '@primer/behaviors';
+/**
+ * Hook used to trap focus inside a container. Returns a ref that can be added to the container
+ * that should trap focus.
+ * @param settings {FocusTrapHookSettings}
+ */
+export function useFocusTrap(settings, dependencies = []) {
+    const containerRef = settings?.containerRef;
+    const initialFocusRef = settings?.initialFocusRef;
+    const disabled = settings?.disabled;
+    const abortController = React.useRef();
+    const previousFocusedElement = React.useRef(null);
+    // If we are enabling a focus trap and haven't already stored the previously focused element
+    // go ahead an do that so we can restore later when the trap is disabled.
+    if (!previousFocusedElement.current && !settings?.disabled) {
+        previousFocusedElement.current = document.activeElement;
+    }
+    // This function removes the event listeners that enable the focus trap and restores focus
+    // to the previously-focused element (if necessary).
+    function disableTrap() {
+        abortController.current?.abort();
+        if (settings?.restoreFocusOnCleanUp && previousFocusedElement.current instanceof HTMLElement) {
+            previousFocusedElement.current.focus();
+            previousFocusedElement.current = null;
+        }
+    }
+    React.useEffect(() => {
+        if (containerRef?.current instanceof HTMLElement) {
+            if (!disabled) {
+                abortController.current = focusTrap(containerRef.current, initialFocusRef?.current ?? undefined);
+                return () => {
+                    disableTrap();
+                };
+            }
+            else {
+                disableTrap();
+            }
+        }
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [containerRef, initialFocusRef, disabled, ...dependencies]);
+    return { containerRef, initialFocusRef };
+}

package/lib/hooks/useIAM.d.ts

@@ -0,0 +1,14 @@
+import { IUser } from '../models';
+export type IAMStateProps = {
+    user?: IUser;
+    token?: string;
+    loginRoute?: string;
+};
+export declare const useIAM: (props?: IAMStateProps) => {
+    user: IUser | undefined;
+    token: string | undefined;
+    loginAndNavigate: (token: string, logout: () => void, refresh: (token: string) => void, navigate?: (location: string, e?: any, resetPortals?: boolean) => void, homeRoute?: string) => Promise<void>;
+    setLogin: (user: IUser, token: string) => void;
+    logout: () => void;
+};
+export default useIAM;

package/lib/hooks/useIAM.js

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+import { useEffect, useState } from 'react';
+import { useCache } from './useCache';
+import { coreStore, useIAMStore, useLayoutStore, useOrganizationStore, useSpaceStore } from '../state';
+import { asUser, ANONYMOUS_USER, ANONYMOUS_USER_TOKEN } from '../models';
+import { requestRunAPI } from '../api';
+export const useIAM = (props = { user: undefined, token: undefined }) => {
+    const { token } = props;
+    const [iamState, setIAMState] = useState(props);
+    const iamStore = useIAMStore();
+    const layoutStore = useLayoutStore();
+    const organizationStore = useOrganizationStore();
+    const spaceStore = useSpaceStore();
+    const { clearAllCaches, whoami } = useCache();
+    const loginAndNavigate = async (token, logout, refresh, navigate, homeRoute) => {
+        try {
+            const resp = await requestRunAPI({
+                url: `${iamStore.iamRunUrl}/api/iam/v1/login`,
+                method: 'POST',
+                body: { token },
+            });
+            if (resp.success && resp.token) {
+                if (resp.is_provided_token_external === true) {
+                    // The provided token is recognized as an external one, so store it as such...
+                    iamStore.setExternalToken(token);
+                }
+                const user = asUser(resp.user);
+                const responseToken = resp.token;
+                setIAMState({ user, token: responseToken });
+                refresh(responseToken);
+                if (navigate && homeRoute) {
+                    navigate(homeRoute);
+                }
+            }
+            else {
+                throw new Error('Invalid Token.');
+            }
+        }
+        catch (error) {
+            if (error.name === 'RunResponseError' &&
+                error.response.status === 401) {
+                console.log('Datalayer IAM has sent a 401 return code.');
+                logout();
+            }
+            throw error;
+        }
+    };
+    const setLogin = (user, token) => {
+        iamStore.setLogin(user, token);
+        setIAMState({
+            user,
+            token,
+        });
+    };
+    const logout = () => {
+        iamStore.logout();
+        layoutStore.reset();
+        organizationStore.updateOrganizations([]);
+        spaceStore.updateSpaces([]);
+        clearAllCaches();
+        setIAMState({ user: ANONYMOUS_USER, token: ANONYMOUS_USER_TOKEN });
+    };
+    useEffect(() => {
+        if (token) {
+            whoami()
+                .then(resp => {
+                if (resp.success) {
+                    const user = asUser(resp.profile);
+                    setIAMState({ user, token });
+                    iamStore.setLogin(user, token);
+                    // TODO centralize user settings management.
+                    const aiagentsRunUrl = user.settings?.aiAgentsUrl;
+                    if (aiagentsRunUrl) {
+                        coreStore.getState().setConfiguration({
+                            aiagentsRunUrl,
+                        });
+                    }
+                }
+            });
+        }
+    }, []);
+    return {
+        user: iamState.user,
+        token: iamState.token,
+        loginAndNavigate,
+        setLogin,
+        logout
+    };
+};
+export default useIAM;

package/lib/hooks/useId.d.ts

@@ -0,0 +1,19 @@
+/**
+ * useId
+ *
+ * Autogenerate IDs to facilitate WAI-ARIA and server rendering.
+ *
+ * Note: The returned ID will initially be `null` and will update after a
+ * component mounts. Users may need to supply their own ID if they need
+ * consistent values for SSR.
+ *
+ * @see Docs https://reach.tech/auto-id
+ */
+declare function useId(idFromProps: string): string;
+declare function useId(idFromProps: number): number;
+declare function useId(idFromProps: string | number): string | number;
+declare function useId(idFromProps: string | undefined | null): string | undefined;
+declare function useId(idFromProps: number | undefined | null): number | undefined;
+declare function useId(idFromProps: string | number | undefined | null): string | number | undefined;
+declare function useId(): string | undefined;
+export { useId };

package/lib/hooks/useId.js

@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+/*
+ * Welcome to @reach/auto-id!
+
+ * Let's see if we can make sense of why this hook exists and its
+ * implementation.
+ *
+ * Some background:
+ *   1. Accessibility APIs rely heavily on element IDs
+ *   2. Requiring developers to put IDs on every element in Reach UI is both
+ *      cumbersome and error-prone
+ *   3. With a component model, we can generate IDs for them!
+ *
+ * Solution 1: Generate random IDs.
+ *
+ * This works great as long as you don't server render your app. When React (in
+ * the client) tries to reuse the markup from the server, the IDs won't match
+ * and React will then recreate the entire DOM tree.
+ *
+ * Solution 2: Increment an integer
+ *
+ * This sounds great. Since we're rendering the exact same tree on the server
+ * and client, we can increment a counter and get a deterministic result between
+ * client and server. Also, JS integers can go up to nine-quadrillion. I'm
+ * pretty sure the tab will be closed before an app never needs
+ * 10 quadrillion IDs!
+ *
+ * Problem solved, right?
+ *
+ * Ah, but there's a catch! React's concurrent rendering makes this approach
+ * non-deterministic. While the client and server will end up with the same
+ * elements in the end, depending on suspense boundaries (and possibly some user
+ * input during the initial render) the incrementing integers won't always match
+ * up.
+ *
+ * Solution 3: Don't use IDs at all on the server; patch after first render.
+ *
+ * What we've done here is solution 2 with some tricks. With this approach, the
+ * ID returned is an empty string on the first render. This way the server and
+ * client have the same markup no matter how wild the concurrent rendering may
+ * have gotten.
+ *
+ * After the render, we patch up the components with an incremented ID. This
+ * causes a double render on any components with `useId`. Shouldn't be a problem
+ * since the components using this hook should be small, and we're only updating
+ * the ID attribute on the DOM, nothing big is happening.
+ *
+ * It doesn't have to be an incremented number, though--we could do generate
+ * random strings instead, but incrementing a number is probably the cheapest
+ * thing we can do.
+ *
+ * Additionally, we only do this patchup on the very first client render ever.
+ * Any calls to `useId` that happen dynamically in the client will be
+ * populated immediately with a value. So, we only get the double render after
+ * server hydration and never again, SO BACK OFF ALRIGHT?
+ */
+/* eslint-disable react-hooks/rules-of-hooks */
+import * as React from "react";
+import { useLayoutEffect } from "react";
+let serverHandoffComplete = false;
+let id = 0;
+function genId() {
+    return ++id;
+}
+// Workaround for https://github.com/webpack/webpack/issues/14814
+// https://github.com/eps1lon/material-ui/blob/8d5f135b4d7a58253a99ab56dce4ac8de61f5dc1/packages/mui-utils/src/useId.ts#L21
+const maybeReactUseId = React["useId".toString()];
+function useId(providedId) {
+    if (maybeReactUseId !== undefined) {
+        let generatedId = maybeReactUseId();
+        return providedId ?? generatedId;
+    }
+    // If this instance isn't part of the initial render, we don't have to do the
+    // double render/patch-up dance. We can just generate the ID and return it.
+    let initialId = providedId ?? (serverHandoffComplete ? genId() : null);
+    let [id, setId] = React.useState(initialId);
+    useLayoutEffect(() => {
+        if (id === null) {
+            // Patch the ID after render. We do this in `useLayoutEffect` to avoid any
+            // rendering flicker, though it'll make the first render slower (unlikely
+            // to matter, but you're welcome to measure your app and let us know if
+            // it's a problem).
+            setId(genId());
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    React.useEffect(() => {
+        if (serverHandoffComplete === false) {
+            // Flag all future uses of `useId` to skip the update dance. This is in
+            // `useEffect` because it goes after `useLayoutEffect`, ensuring we don't
+            // accidentally bail out of the patch-up dance prematurely.
+            serverHandoffComplete = true;
+        }
+    }, []);
+    return providedId ?? id ?? undefined;
+}
+export { useId };

package/lib/hooks/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,3 @@
+import { useEffect } from 'react';
+declare const useIsomorphicLayoutEffect: typeof useEffect;
+export default useIsomorphicLayoutEffect;

package/lib/hooks/useIsomorphicLayoutEffect.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+import { useEffect, useLayoutEffect } from 'react';
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' &&
+    typeof window.document !== 'undefined' &&
+    typeof window.document.createElement !== 'undefined'
+    ? useLayoutEffect
+    : useEffect;
+export default useIsomorphicLayoutEffect;

package/lib/hooks/useJupyterLabTheme.d.ts

@@ -0,0 +1,6 @@
+import { IThemeManager } from '@jupyterlab/apputils';
+export declare enum JupyterLabTheme {
+    LIGHT = "JupyterLab Light",
+    DARK = "JupyterLab Dark"
+}
+export declare const useJupyterLabTheme: (themeManager: IThemeManager) => any;

package/lib/hooks/useJupyterLabTheme.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+import { useEffect, useState } from 'react';
+export var JupyterLabTheme;
+(function (JupyterLabTheme) {
+    JupyterLabTheme["LIGHT"] = "JupyterLab Light";
+    JupyterLabTheme["DARK"] = "JupyterLab Dark";
+})(JupyterLabTheme || (JupyterLabTheme = {}));
+export const useJupyterLabTheme = (themeManager) => {
+    const isLight = themeManager && themeManager.theme ? themeManager.isLight(themeManager.theme) : true;
+    const [theme, setTheme] = useState(isLight ? JupyterLabTheme.LIGHT : JupyterLabTheme.DARK);
+    useEffect(() => {
+        const handleThemeChange = (newTheme, event) => {
+            setTheme(event.newValue);
+        };
+        themeManager?.themeChanged?.connect(handleThemeChange);
+        return () => {
+            themeManager?.themeChanged?.disconnect(handleThemeChange);
+        };
+    }, []);
+    return theme;
+};

package/lib/hooks/useKeyboardEscape.d.ts

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

package/lib/hooks/useKeyboardEscape.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer License
+ */
+import { useCallback, useEffect } from 'react';
+export function useKeyboardEscape(handler) {
+    const handleKeyboardEscape = useCallback(event => {
+        if (event.key === 'Escape') {
+            handler();
+        }
+    }, [handler]);
+    useEffect(() => {
+        document.addEventListener('keydown', handleKeyboardEscape, false);
+        return () => {
+            document.removeEventListener('keydown', handleKeyboardEscape, false);
+        };
+    }, [handleKeyboardEscape]);
+}

package/lib/hooks/useLocationHandles.d.ts

@@ -0,0 +1,10 @@
+export declare const useLocationHandles: () => {
+    accountHandle: string | undefined;
+    spaceHandler: string | undefined;
+    spaceHandle?: undefined;
+} | {
+    accountHandle: string | undefined;
+    spaceHandle: string | undefined;
+    spaceHandler?: undefined;
+};
+export default useLocationHandles;

package/lib/hooks/useLocationHandles.js

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer 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,29 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2021-2024 Datalayer, Inc.
+ *
+ * Datalayer 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;