@datalayer/core 1.2.25 → 1.2.26

package/lib/client/constants.d.ts

@@ -12,6 +12,7 @@ export declare const ItemTypes: {
     readonly NOTEBOOK: "notebook";
     readonly LEXICAL: "document";
     readonly DECK: "deck";
+    readonly SPREADSHEET: "spreadsheet";
     readonly EXERCISE: "exercise";
     readonly CELL: "cell";
     readonly SPACE: "space";

package/lib/client/constants.js

@@ -16,6 +16,8 @@ export const ItemTypes = {
     NOTEBOOK: 'notebook',
     LEXICAL: 'document',
     DECK: 'deck',
+    // A spreadsheet drawn by `@datalayer/cells`: its content is a CellsWorkbook.
+    SPREADSHEET: 'spreadsheet',
     EXERCISE: 'exercise',
     CELL: 'cell',
     SPACE: 'space',

package/lib/hooks/useCache.d.ts

@@ -306,6 +306,12 @@ export declare const queryKeys: {
         /** Under the detail: saving the deck refreshes whether it is stale. */
         readonly video: (deckId: string) => readonly ["decks", "detail", string, "video"];
     };
+    readonly spreadsheets: {
+        readonly all: () => readonly ["spreadsheets"];
+        readonly details: () => readonly ["spreadsheets", "detail"];
+        readonly detail: (id: string) => readonly ["spreadsheets", "detail", string];
+        readonly bySpace: (spaceId: string) => readonly ["spreadsheets", "space", string];
+    };
     readonly cells: {
         readonly all: () => readonly ["cells"];
         readonly details: () => readonly ["cells", "detail"];
@@ -835,6 +841,24 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
         spec: unknown;
     }, unknown>;
     useDeleteDeckVideo: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
+    useSpreadsheet: (spreadsheetId: string) => import("@tanstack/react-query").UseQueryResult<any, Error>;
+    useSpreadsheetsBySpace: (spaceId: string) => import("@tanstack/react-query").UseQueryResult<any, Error>;
+    useCreateSpreadsheet: () => import("@tanstack/react-query").UseMutationResult<any, Error, {
+        spaceId: string;
+        name: string;
+        description?: string;
+        workbook: unknown;
+    }, unknown>;
+    useUpdateSpreadsheet: () => import("@tanstack/react-query").UseMutationResult<any, Error, {
+        id: string;
+        name: string;
+        description: string;
+    }, unknown>;
+    useUpdateSpreadsheetModel: () => import("@tanstack/react-query").UseMutationResult<any, Error, {
+        id: string;
+        workbook: unknown;
+    }, unknown>;
+    useCloneSpreadsheet: () => import("@tanstack/react-query").UseMutationResult<any, Error, string, unknown>;
     useDocument: (documentId: string) => import("@tanstack/react-query").UseQueryResult<any, Error>;
     useDocumentsBySpace: (spaceId: string) => import("@tanstack/react-query").UseQueryResult<any, Error>;
     useCreateDocument: () => import("@tanstack/react-query").UseMutationResult<any, Error, {
@@ -1464,6 +1488,12 @@ export declare const useCache: ({ loginRoute }?: CacheProps) => {
             /** Under the detail: saving the deck refreshes whether it is stale. */
             readonly video: (deckId: string) => readonly ["decks", "detail", string, "video"];
         };
+        readonly spreadsheets: {
+            readonly all: () => readonly ["spreadsheets"];
+            readonly details: () => readonly ["spreadsheets", "detail"];
+            readonly detail: (id: string) => readonly ["spreadsheets", "detail", string];
+            readonly bySpace: (spaceId: string) => readonly ["spreadsheets", "space", string];
+        };
         readonly cells: {
             readonly all: () => readonly ["cells"];
             readonly details: () => readonly ["cells", "detail"];

package/lib/hooks/useCache.js

@@ -372,6 +372,13 @@ export const queryKeys = {
         /** Under the detail: saving the deck refreshes whether it is stale. */
         video: (deckId) => [...queryKeys.decks.detail(deckId), 'video'],
     },
+    // Spreadsheets: `@datalayer/cells` workbooks, kept as items of a space.
+    spreadsheets: {
+        all: () => ['spreadsheets'],
+        details: () => [...queryKeys.spreadsheets.all(), 'detail'],
+        detail: (id) => [...queryKeys.spreadsheets.details(), id],
+        bySpace: (spaceId) => [...queryKeys.spreadsheets.all(), 'space', spaceId],
+    },
     // Cells
     cells: {
         all: () => ['cells'],
@@ -1101,6 +1108,46 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         };
     };
+    /**
+     * A spreadsheet: a space item whose content is a `@datalayer/cells`
+     * workbook (`CellsWorkbook`), written through the documents routes the way
+     * a Studio app's definition is. `workbook` is the parsed JSON when the
+     * answer inlined it (`GET /lexicals/{uid}` does, a listing does not), and
+     * `undefined` otherwise — never a guess, so an editor cannot open on a
+     * listing's row and draw an empty grid it would then save.
+     */
+    const toSpreadsheet = (raw) => {
+        let workbook = undefined;
+        if (typeof raw.model_s === 'string' && raw.model_s.trim()) {
+            workbook = JSON.parse(raw.model_s);
+        }
+        return {
+            id: raw.uid,
+            type: 'spreadsheet',
+            name: raw.name_t,
+            description: raw.description_t,
+            tags: Array.isArray(raw.tags_ss) ? raw.tags_ss : [],
+            workbook,
+            public: raw.is_public_b ?? false,
+            creationDate: raw.creation_ts_dt
+                ? new Date(raw.creation_ts_dt)
+                : undefined,
+            lastUpdateDate: raw.last_update_ts_dt
+                ? new Date(raw.last_update_ts_dt)
+                : undefined,
+            lastPublicationDate: raw.published_ts_dt
+                ? new Date(raw.published_ts_dt)
+                : undefined,
+            owner: toItemOwner(raw),
+            space: {
+                handle: raw.handle_s,
+            },
+            organization: {
+                id: raw.organization_uid_s,
+                handle: raw.organization_handle_s,
+            },
+        };
+    };
     const toDocument = (doc) => {
         const owner = toItemOwner(doc);
         return {
@@ -1404,6 +1451,8 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             // read no type and no name, and drew itself as a nameless notebook.
             case 'deck':
                 return toDeck(item);
+            case 'spreadsheet':
+                return toSpreadsheet(item);
             case 'document':
                 return toDocument(item);
             case 'exercise':
@@ -2734,6 +2783,167 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         });
     };
     // ============================================================================
+    // Spreadsheet Hooks
+    // ============================================================================
+    //
+    // A spreadsheet is a space item of type `spreadsheet` whose content is a
+    // `@datalayer/cells` workbook. It has no routes of its own: it is created,
+    // read, renamed, saved and cloned through the documents routes
+    // (`/lexicals`, `documentType=spreadsheet`), as a Studio app is, and Spacer
+    // refuses a body that is not a workbook.
+    /**
+     * Get a spreadsheet by id, its workbook inlined as `workbook`.
+     */
+    const useSpreadsheet = (spreadsheetId) => {
+        return useQuery({
+            queryKey: queryKeys.spreadsheets.detail(spreadsheetId),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/lexicals/${spreadsheetId}`,
+                    method: 'GET',
+                });
+                if (resp.success && resp.document) {
+                    if (resp.document.type_s !== 'spreadsheet') {
+                        throw new Error('This item is not a spreadsheet.');
+                    }
+                    return toSpreadsheet(resp.document);
+                }
+                if (resp?.code === 'FORBIDDEN') {
+                    throw new Error(resp.message || 'Not authorized to access this spreadsheet');
+                }
+                throw new Error(resp.message || 'Failed to fetch spreadsheet');
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!spreadsheetId,
+        });
+    };
+    /**
+     * Get the spreadsheets of a space. A row carries no workbook: the detail
+     * cache is not seeded from it.
+     */
+    const useSpreadsheetsBySpace = (spaceId) => {
+        return useQuery({
+            queryKey: queryKeys.spreadsheets.bySpace(spaceId),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/spaces/${spaceId}/items/types/spreadsheet`,
+                    method: 'GET',
+                });
+                if (resp.success && resp.items) {
+                    return resp.items.map((raw) => toSpreadsheet(raw));
+                }
+                return [];
+            },
+            ...LIST_QUERY_OPTIONS,
+            enabled: !!spaceId,
+        });
+    };
+    /**
+     * Create a spreadsheet from a workbook: the starter one, or one the
+     * person brings. Sent as the uploaded file, which Spacer checks.
+     */
+    const useCreateSpreadsheet = () => {
+        return useMutation({
+            mutationFn: async ({ spaceId, name, description, workbook, }) => {
+                const formData = new FormData();
+                formData.append('spaceId', spaceId);
+                formData.append('documentType', 'spreadsheet');
+                formData.append('name', name);
+                formData.append('description', description || '');
+                formData.append('file', new File([JSON.stringify(workbook)], `${name}.cells.json`, {
+                    type: 'application/json',
+                }));
+                return uploadDocument(formData);
+            },
+            onSuccess: resp => {
+                if (resp.success && resp.document) {
+                    // The answer carries no model: the editor reads the spreadsheet
+                    // from the server rather than from a seeded, empty detail.
+                    queryClient.invalidateQueries({
+                        queryKey: queryKeys.spreadsheets.detail(resp.document.uid),
+                    });
+                    queryClient.refetchQueries({
+                        queryKey: queryKeys.spreadsheets.all(),
+                    });
+                    queryClient.refetchQueries({ queryKey: queryKeys.items.all() });
+                }
+            },
+        });
+    };
+    /**
+     * Update a spreadsheet's name and description.
+     */
+    const useUpdateSpreadsheet = () => {
+        return useMutation({
+            mutationFn: async ({ id, name, description, }) => {
+                return requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/lexicals/${id}`,
+                    method: 'PUT',
+                    body: { name, description },
+                });
+            },
+            onSuccess: (resp, spreadsheet) => {
+                if (resp.success) {
+                    queryClient.invalidateQueries({
+                        queryKey: queryKeys.spreadsheets.detail(spreadsheet.id),
+                    });
+                    queryClient.invalidateQueries({
+                        queryKey: queryKeys.spreadsheets.all(),
+                    });
+                }
+            },
+        });
+    };
+    /**
+     * Replace a spreadsheet's workbook, whole. A refusal (a workbook Spacer
+     * does not accept) is thrown, not answered as a success.
+     */
+    const useUpdateSpreadsheetModel = () => {
+        return useMutation({
+            mutationFn: async ({ id, workbook, }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/lexicals/${id}/model`,
+                    method: 'PUT',
+                    body: { model: workbook },
+                });
+                if (!resp.success) {
+                    throw new Error(resp.message || 'The spreadsheet was not saved.');
+                }
+                return resp;
+            },
+            onSuccess: (_, variables) => {
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.spreadsheets.detail(variables.id),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.spreadsheets.all(),
+                });
+            },
+        });
+    };
+    /**
+     * Clone a spreadsheet into the caller's library: the reuse the library
+     * counts for a published one.
+     */
+    const useCloneSpreadsheet = () => {
+        return useMutation({
+            mutationFn: async (spreadsheetId) => {
+                return requestDatalayer({
+                    url: `${configuration.spacerUrl}/api/spacer/v1/lexicals/${spreadsheetId}/clone`,
+                    method: 'POST',
+                });
+            },
+            onSuccess: resp => {
+                if (resp.success && resp.document) {
+                    queryClient.refetchQueries({
+                        queryKey: queryKeys.spreadsheets.all(),
+                    });
+                    queryClient.refetchQueries({ queryKey: queryKeys.items.all() });
+                }
+            },
+        });
+    };
+    // ============================================================================
     // Document Hooks
     // ============================================================================
     /**
@@ -3196,6 +3406,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                     queryKey: queryKeys.documents.detail(itemId),
                 });
                 queryClient.removeQueries({ queryKey: queryKeys.decks.detail(itemId) });
+                queryClient.removeQueries({
+                    queryKey: queryKeys.spreadsheets.detail(itemId),
+                });
                 queryClient.removeQueries({ queryKey: queryKeys.cells.detail(itemId) });
                 queryClient.removeQueries({
                     queryKey: queryKeys.lessons.detail(itemId),
@@ -3210,6 +3423,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 queryClient.invalidateQueries({ queryKey: queryKeys.notebooks.all() });
                 queryClient.invalidateQueries({ queryKey: queryKeys.documents.all() });
                 queryClient.invalidateQueries({ queryKey: queryKeys.decks.all() });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.spreadsheets.all(),
+                });
                 queryClient.invalidateQueries({ queryKey: queryKeys.cells.all() });
                 queryClient.invalidateQueries({ queryKey: queryKeys.lessons.all() });
                 queryClient.invalidateQueries({ queryKey: queryKeys.exercises.all() });
@@ -8692,6 +8908,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useSavedDeckVideo,
         useSaveDeckVideo,
         useDeleteDeckVideo,
+        // Spreadsheets
+        useSpreadsheet,
+        useSpreadsheetsBySpace,
+        useCreateSpreadsheet,
+        useUpdateSpreadsheet,
+        useUpdateSpreadsheetModel,
+        useCloneSpreadsheet,
         // Documents
         useDocument,
         useDocumentsBySpace,

package/lib/state/substates/NavigationState.js

@@ -311,10 +311,11 @@ export function viewForRoute(route, current) {
 }
 /**
  * `/<account>/<space>/<kind>[/…]` for the kinds a space shows beside the
- * Agentify sidebar — decks, courses and what a course is made of. The
+ * Agentify sidebar — decks, spreadsheets (Cells), courses and what a course
+ * is made of. The
  * documentation (`/docs/…`) is never an account.
  */
-const AGENTIFY_SPACE_PAGE = /^\/(?!docs\/)[^/]+\/[^/]+\/(?:decks|courses|course|lessons|exercises|assignments)(?:\/|$)/;
+const AGENTIFY_SPACE_PAGE = /^\/(?!docs\/)[^/]+\/[^/]+\/(?:decks|spreadsheets|courses|course|lessons|exercises|assignments)(?:\/|$)/;
 /** `/<account>/courses`: an account's courses, beside the Agentify sidebar. */
 const AGENTIFY_ACCOUNT_PAGE = /^\/(?!docs\/)[^/]+\/courses$/;
 /** Whether a page may be the one a shell returns to. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/core",
-    "version": "1.2.25",
+    "version": "1.2.26",
     "type": "module",
     "workspaces": [
         ".",