@datalayer/core 1.1.66 → 1.2.10

package/lib/components/sharing/SharingEditor.js

@@ -4,9 +4,14 @@ import { Box } from '@datalayer/primer-addons';
 import { FormControl, Text, Textarea } from '@primer/react';
 export const EMPTY_SHARING_PAYLOAD = {
     access: {
-        view: { userUids: [], teamUids: [], organizationUids: [] },
-        update: { userUids: [], teamUids: [], organizationUids: [] },
-        execute: { userUids: [], teamUids: [], organizationUids: [] },
+        view: { userUids: [], teamUids: [], organizationUids: [], agentUids: [] },
+        update: { userUids: [], teamUids: [], organizationUids: [], agentUids: [] },
+        execute: {
+            userUids: [],
+            teamUids: [],
+            organizationUids: [],
+            agentUids: [],
+        },
     },
 };
 const stringify = (value) => {
@@ -17,7 +22,7 @@ const stringify = (value) => {
         return '{}';
     }
 };
-export function SharingEditor({ value, onChange, label = 'Sharing', caption = 'Edit the sharing payload. Each access level (view/update/execute) can grant access to user, team, and organization UIDs.', rows = 10, disabled = false, }) {
+export function SharingEditor({ value, onChange, label = 'Sharing', caption = 'Edit the sharing payload. Each access level (view/update/execute) can grant access to user, team, organization, and agent UIDs.', rows = 10, disabled = false, }) {
     const initial = useMemo(() => stringify(value), [value]);
     const [raw, setRaw] = useState(initial);
     const [error, setError] = useState(null);

package/lib/components/sharing/index.d.ts

@@ -5,5 +5,6 @@ export * from '../principal/PrincipalBanner';
 export { buildPrincipalProfilePath, PrincipalDetailsOverlay, } from '../principal/PrincipalDetailsOverlay';
 export type { PrincipalDetailsOverlayProps } from '../principal/PrincipalDetailsOverlay';
 export * from '../principal/PrincipalSwitcherMenu';
+export * from './sandboxSharing';
 export * from './ShareAccessComponent';
 export * from './SharingEditor';

package/lib/components/sharing/index.js

@@ -8,5 +8,6 @@ export * from '../principal/PrincipalBadge.js';
 export * from '../principal/PrincipalBanner.js';
 export { buildPrincipalProfilePath, PrincipalDetailsOverlay, } from '../principal/PrincipalDetailsOverlay.js';
 export * from '../principal/PrincipalSwitcherMenu.js';
+export * from './sandboxSharing.js';
 export * from './ShareAccessComponent.js';
 export * from './SharingEditor.js';

package/lib/components/sharing/sandboxSharing.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Where a sandbox's sharing lives.
+ *
+ * A sandbox is a runtime underneath, and Runtimes owns who it is shared with:
+ * `GET|PUT /api/runtimes/v1/runtimes/{name}/sharing`, answering an `access`
+ * document in exactly the shape `ShareAccessDialog` reads. So the dialog
+ * talks to Runtimes directly and there is no transport to write.
+ *
+ * The one thing worth a function of its own is **which name**. A sandbox has
+ * two: the handle its session holds (`sb_…`) and the runtime's own, and
+ * Runtimes' routes take the second. Sending the first gets a `403` that reads
+ * as "you are not the owner" — the confusion that made the CLI's sharing
+ * commands unusable until September 2026, and the reason this is written down
+ * once rather than spelled out at each call site.
+ *
+ * @module components/sharing/sandboxSharing
+ */
+/**
+ * The sharing URL for a sandbox, or `undefined` when there is nothing to ask.
+ *
+ * Answers `undefined` rather than a broken URL for a sandbox with no runtime
+ * behind it — a browser or local kernel, or a binding still reserving — so a
+ * caller can use the answer itself to decide whether to offer sharing at all.
+ */
+export declare const sandboxSharingUrl: (runtimesUrl: string | undefined | null, runtimeName: string | undefined | null) => string | undefined;
+export default sandboxSharingUrl;

package/lib/components/sharing/sandboxSharing.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Where a sandbox's sharing lives.
+ *
+ * A sandbox is a runtime underneath, and Runtimes owns who it is shared with:
+ * `GET|PUT /api/runtimes/v1/runtimes/{name}/sharing`, answering an `access`
+ * document in exactly the shape `ShareAccessDialog` reads. So the dialog
+ * talks to Runtimes directly and there is no transport to write.
+ *
+ * The one thing worth a function of its own is **which name**. A sandbox has
+ * two: the handle its session holds (`sb_…`) and the runtime's own, and
+ * Runtimes' routes take the second. Sending the first gets a `403` that reads
+ * as "you are not the owner" — the confusion that made the CLI's sharing
+ * commands unusable until September 2026, and the reason this is written down
+ * once rather than spelled out at each call site.
+ *
+ * @module components/sharing/sandboxSharing
+ */
+/**
+ * The sharing URL for a sandbox, or `undefined` when there is nothing to ask.
+ *
+ * Answers `undefined` rather than a broken URL for a sandbox with no runtime
+ * behind it — a browser or local kernel, or a binding still reserving — so a
+ * caller can use the answer itself to decide whether to offer sharing at all.
+ */
+export const sandboxSharingUrl = (runtimesUrl, runtimeName) => {
+    const base = String(runtimesUrl ?? '').trim();
+    const name = String(runtimeName ?? '').trim();
+    if (!base || !name) {
+        return undefined;
+    }
+    return `${base.replace(/\/+$/, '')}/api/runtimes/v1/runtimes/${encodeURIComponent(name)}/sharing`;
+};
+export default sandboxSharingUrl;

package/lib/components/spaces/SpaceDetailsOverlay.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A space's details: the card, and the overlay that opens it from a click on
+ * the space's name.
+ *
+ * Built the way {@link PrincipalDetailsOverlay} is — the name is the anchor,
+ * the card is shared — so a table's Owner and Space columns open the same kind
+ * of thing and read the same way.
+ *
+ * @module components/spaces/SpaceDetailsOverlay
+ */
+import type { JSX } from 'react';
+export type SpaceDetailsOverlayProps = {
+    uid?: string;
+    displayName: string;
+    handle?: string;
+    accountHandle?: string;
+    description?: string;
+    variant?: string;
+    isPublic?: boolean;
+    /**
+     * Show a route some other way than through the router of this subtree.
+     *
+     * The same escape hatch as the principal card's: an editor embedded under a
+     * `MemoryRouter` of its own hands the route to the view that has the
+     * application's routes. Left out, the route is followed with `useNavigate`.
+     */
+    onNavigate?: (path: string) => void;
+};
+/**
+ * The card of a space, on its own — its mark, identity, and the way to it.
+ */
+export declare function SpaceDetailsCard({ uid, displayName, handle, accountHandle, description, variant, isPublic, onNavigate, }: SpaceDetailsOverlayProps): JSX.Element;
+/**
+ * A space's details, shown from a click on its name.
+ *
+ * The name is the anchor; clicking it opens the shared {@link SpaceDetailsCard}.
+ */
+export declare function SpaceDetailsOverlay(props: SpaceDetailsOverlayProps): JSX.Element;
+export default SpaceDetailsOverlay;

package/lib/components/spaces/SpaceDetailsOverlay.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ActionMenu, Box, Button, Label, Text, ThemeProvider, } from '@primer/react';
+import { SpaceIcon } from '@primer/octicons-react';
+import { useNavigate } from '../../hooks/index.js';
+import { buildSpaceDetailsPath } from './spaceDisplayModel.js';
+function normalize(value) {
+    return (value || '').trim();
+}
+/**
+ * The card of a space, on its own — its mark, identity, and the way to it.
+ */
+export function SpaceDetailsCard({ uid, displayName, handle, accountHandle, description, variant, isPublic, onNavigate, }) {
+    const navigate = useNavigate();
+    const targetPath = buildSpaceDetailsPath({ accountHandle, handle });
+    const go = () => {
+        if (!targetPath) {
+            return;
+        }
+        if (onNavigate) {
+            onNavigate(targetPath);
+        }
+        else {
+            navigate(targetPath);
+        }
+    };
+    const normalizedHandle = normalize(handle);
+    const normalizedAccount = normalize(accountHandle).replace(/^@+/, '');
+    const normalizedUid = normalize(uid);
+    const normalizedDisplayName = normalize(displayName) || normalizedHandle || normalizedUid || 'Space';
+    // The address the space is reached at, as it reads in the location bar.
+    const address = normalizedAccount && normalizedHandle
+        ? `@${normalizedAccount}/${normalizedHandle}`
+        : normalizedHandle;
+    return (_jsxs(Box, { sx: { display: 'grid', gap: 3, p: 4, minWidth: 360 }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(Box, { "aria-hidden": "true", sx: {
+                            display: 'inline-flex',
+                            alignItems: 'center',
+                            justifyContent: 'center',
+                            width: 40,
+                            height: 40,
+                            flexShrink: 0,
+                            borderRadius: 2,
+                            bg: 'accent.subtle',
+                            color: 'accent.fg',
+                        }, children: _jsx(SpaceIcon, { size: 20 }) }), _jsxs(Box, { sx: { display: 'grid', gap: 0.5, minWidth: 0 }, children: [_jsx(Text, { sx: { fontWeight: 'semibold' }, children: normalizedDisplayName }), address ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: address })) : null] })] }), _jsxs(Box, { sx: {
+                    display: 'grid',
+                    gridTemplateColumns: '110px 1fr',
+                    gap: 1,
+                    alignItems: 'baseline',
+                }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Kind" }), _jsx(Text, { sx: { fontSize: 1 }, children: "space" }), normalizedHandle ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Handle" }), _jsx(Text, { sx: { fontSize: 1 }, children: normalizedHandle })] })) : null, normalizedAccount ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Account" }), _jsxs(Text, { sx: { fontSize: 1 }, children: ["@", normalizedAccount] })] })) : null, normalize(variant) ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Variant" }), _jsx(Text, { sx: { fontSize: 1 }, children: normalize(variant) })] })) : null, typeof isPublic === 'boolean' ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Visibility" }), _jsx(Label, { size: "small", variant: isPublic ? 'success' : 'secondary', sx: { justifySelf: 'start', width: 'fit-content' }, children: isPublic ? 'Public' : 'Private' })] })) : null, _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Description" }), _jsx(Text, { sx: { fontSize: 1 }, children: normalize(description) || 'N/A' }), normalizedUid ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "UID" }), _jsx(Text, { sx: { fontSize: 1 }, children: normalizedUid })] })) : null] }), _jsx(Box, { sx: { display: 'flex', justifyContent: 'flex-end', gap: 2 }, children: _jsx(Button, { size: "small", onClick: go, disabled: !targetPath, children: "View Space" }) })] }));
+}
+/**
+ * A space's details, shown from a click on its name.
+ *
+ * The name is the anchor; clicking it opens the shared {@link SpaceDetailsCard}.
+ */
+export function SpaceDetailsOverlay(props) {
+    const normalizedDisplayName = normalize(props.displayName) ||
+        normalize(props.handle) ||
+        normalize(props.uid) ||
+        'Space';
+    return (_jsx(ThemeProvider, { children: _jsxs(ActionMenu, { children: [_jsx(ActionMenu.Anchor, { children: _jsx(Box, { as: "button", type: "button", title: normalizedDisplayName, sx: {
+                            fontWeight: 'semibold',
+                            color: 'accent.fg',
+                            textDecoration: 'underline',
+                            background: 'transparent',
+                            border: 0,
+                            padding: 0,
+                            margin: 0,
+                            cursor: 'pointer',
+                            maxWidth: '100%',
+                            overflow: 'hidden',
+                            textOverflow: 'ellipsis',
+                            whiteSpace: 'nowrap',
+                            textAlign: 'left',
+                            ':hover': {
+                                textDecoration: 'underline',
+                            },
+                        }, children: normalizedDisplayName }) }), _jsx(ActionMenu.Overlay, { width: "large", children: _jsx(SpaceDetailsCard, { ...props }) })] }) }));
+}
+export default SpaceDetailsOverlay;

package/lib/components/spaces/SpaceDisplay.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SpaceDisplay – common display for the space a thing lives in: the space's
+ * name, clickable, opening a {@link SpaceDetailsOverlay} whose button goes to
+ * the space's page.
+ *
+ * The companion of {@link Principal}, for a table's Space column, and built
+ * for a table's arithmetic: a hundred rows in three spaces cost no request per
+ * row. A space is found, in order:
+ *
+ * 1. among the spaces the account has already loaded (`useUserSpaces`, the
+ *    query the item tables already run, children included — which is how a
+ *    row that knows only its item still finds its space);
+ * 2. in the in-memory {@link useSpaceCacheStore}, which paints a space that
+ *    any earlier view resolved;
+ * 3. over the network by uid (`useSpace`) — only once the loaded list has
+ *    answered without it, and every row naming that uid shares the request.
+ *
+ * @module components/spaces/SpaceDisplay
+ */
+import * as React from 'react';
+import { type SpaceDescriptor } from './spaceDisplayModel';
+export type SpaceDisplayProps = {
+    /** Whatever the row knows of its space; see {@link SpaceDescriptor}. */
+    space: SpaceDescriptor;
+    /** Whether the space mark precedes the name. */
+    showIcon?: boolean;
+    iconSize?: number;
+    gap?: number;
+    /** Maximum length of the handle or uid shown before the name resolves. */
+    placeholderMaxLength?: number;
+    /** What is shown when the row names no space at all. */
+    emptyText?: string;
+    /** See {@link SpaceDetailsOverlayProps.onNavigate}. */
+    onNavigate?: (path: string) => void;
+    sx?: any;
+};
+export declare const SpaceDisplay: React.FC<SpaceDisplayProps>;
+export default SpaceDisplay;

package/lib/components/spaces/SpaceDisplay.js

@@ -0,0 +1,92 @@
+import { 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.
+ */
+/**
+ * SpaceDisplay – common display for the space a thing lives in: the space's
+ * name, clickable, opening a {@link SpaceDetailsOverlay} whose button goes to
+ * the space's page.
+ *
+ * The companion of {@link Principal}, for a table's Space column, and built
+ * for a table's arithmetic: a hundred rows in three spaces cost no request per
+ * row. A space is found, in order:
+ *
+ * 1. among the spaces the account has already loaded (`useUserSpaces`, the
+ *    query the item tables already run, children included — which is how a
+ *    row that knows only its item still finds its space);
+ * 2. in the in-memory {@link useSpaceCacheStore}, which paints a space that
+ *    any earlier view resolved;
+ * 3. over the network by uid (`useSpace`) — only once the loaded list has
+ *    answered without it, and every row naming that uid shares the request.
+ *
+ * @module components/spaces/SpaceDisplay
+ */
+import * as React from 'react';
+import { Text } from '@primer/react';
+import { SpaceIcon } from '@primer/octicons-react';
+import { Box } from '@datalayer/primer-addons';
+import { useCache } from '../../hooks/index.js';
+import { useSpaceCacheStore } from '../../hooks/useSpaceCacheStore.js';
+import { useIAMStore } from '../../state/index.js';
+import { SpaceDetailsOverlay } from './SpaceDetailsOverlay.js';
+import { findSpace, indexSpaces, resolveSpace, toCachedSpace, } from './spaceDisplayModel.js';
+export const SpaceDisplay = ({ space, showIcon = true, iconSize = 16, gap = 1, placeholderMaxLength, emptyText = '—', onNavigate, sx, }) => {
+    const { uid, rootId, itemUid, handle, accountHandle, displayName } = space;
+    const { useUserSpaces, useSpace } = useCache();
+    const { user } = useIAMStore();
+    // 1. The spaces already loaded, indexed once per answer of the query.
+    const spacesQuery = useUserSpaces();
+    const index = React.useMemo(() => indexSpaces(spacesQuery.data), [spacesQuery.data]);
+    const listed = React.useMemo(() => toCachedSpace(findSpace(index, { uid, rootId, itemUid, handle, accountHandle })), [index, uid, rootId, itemUid, handle, accountHandle]);
+    // 2. A snapshot some earlier view resolved.
+    const givenUid = String(uid || '').trim();
+    const givenRootId = String(rootId || '').trim();
+    const cached = useSpaceCacheStore(state => {
+        const key = givenUid ||
+            listed?.uid ||
+            (givenRootId ? state.uidByRootId[givenRootId] : '');
+        return key ? state.spaces[key] : undefined;
+    });
+    const upsertSpace = useSpaceCacheStore(state => state.upsertSpace);
+    // 3. The network, last, and not while the list that may know it is loading.
+    const fetchUid = user &&
+        givenUid &&
+        !spacesQuery.isLoading &&
+        !listed &&
+        !cached?.displayName
+        ? givenUid
+        : '';
+    const fetchedQuery = useSpace(fetchUid);
+    const fetched = React.useMemo(() => toCachedSpace(fetchedQuery.data), [fetchedQuery.data]);
+    const found = listed ?? fetched;
+    const resolved = resolveSpace({
+        descriptor: space,
+        found,
+        cached,
+        placeholderMaxLength,
+    });
+    // Remember what was actually resolved — never a placeholder — so the next
+    // view paints it at once.
+    React.useEffect(() => {
+        if (found?.uid) {
+            upsertSpace(found);
+        }
+    }, [found, upsertSpace]);
+    const canName = Boolean(resolved.uid || resolved.handle || String(displayName || '').trim());
+    if (!canName) {
+        const waiting = Boolean(user) &&
+            spacesQuery.isLoading &&
+            Boolean(givenRootId || String(itemUid || '').trim());
+        return (_jsx(Text, { sx: { color: 'fg.muted', ...sx }, children: waiting ? '…' : emptyText }));
+    }
+    return (_jsxs(Box, { sx: {
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap,
+            minWidth: 0,
+            maxWidth: '100%',
+            ...sx,
+        }, children: [showIcon ? (_jsx(Box, { as: "span", "aria-hidden": "true", sx: { display: 'inline-flex', color: 'fg.muted', flexShrink: 0 }, children: _jsx(SpaceIcon, { size: iconSize }) })) : null, _jsx(SpaceDetailsOverlay, { uid: resolved.uid, displayName: resolved.displayName, handle: resolved.handle, accountHandle: resolved.accountHandle, description: resolved.description, variant: resolved.variant, isPublic: resolved.isPublic, onNavigate: onNavigate })] }));
+};
+export default SpaceDisplay;

package/lib/components/spaces/index.d.ts

@@ -0,0 +1,4 @@
+export * from './SpaceDisplay';
+export { SpaceDetailsCard, SpaceDetailsOverlay } from './SpaceDetailsOverlay';
+export type { SpaceDetailsOverlayProps } from './SpaceDetailsOverlay';
+export * from './spaceDisplayModel';

package/lib/components/spaces/index.js

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export * from './SpaceDisplay.js';
+export { SpaceDetailsCard, SpaceDetailsOverlay } from './SpaceDetailsOverlay.js';
+export * from './spaceDisplayModel.js';

package/lib/components/spaces/spaceDisplayModel.d.ts

@@ -0,0 +1,93 @@
+/**
+ * What a space display needs to know, said without rendering anything.
+ *
+ * Apart from the components so the rules — how a row names its space, how a
+ * space is found among the ones already loaded, where its page is — can be
+ * tested without a DOM, a router or a query client.
+ *
+ * @module components/spaces/spaceDisplayModel
+ */
+import type { CachedSpace } from '../../hooks/useSpaceCacheStore';
+/**
+ * How a row names the space it belongs to — whatever it happens to know.
+ *
+ * Tables reach their rows by different roads, and each road knows something
+ * different: a table scoped to one space knows that space's uid; a row from
+ * the cross-space listing knows only its item, which carries its space's Solr
+ * id as `_root_`; a dataset knows its `spaceUid`. Any one of them is enough.
+ */
+export type SpaceDescriptor = {
+    /** The space uid. */
+    uid?: string | null;
+    /** The space's Solr id, which an item carries as `_root_`. */
+    rootId?: string | null;
+    /** The uid of an item in the space, found among the loaded spaces' children. */
+    itemUid?: string | null;
+    /**
+     * The space handle. Handles repeat across accounts — everybody has a
+     * `library` — so it is matched together with `accountHandle`, and only
+     * when no uid was given.
+     */
+    handle?: string | null;
+    /** The account the space is addressed under. */
+    accountHandle?: string | null;
+    /** A name the row already has, shown until the space is resolved. */
+    displayName?: string | null;
+};
+/** Loaded spaces, looked up every way a row can name one. */
+export type SpaceIndex = {
+    byUid: ReadonlyMap<string, unknown>;
+    byRootId: ReadonlyMap<string, unknown>;
+    byItemUid: ReadonlyMap<string, unknown>;
+    byAccountAndHandle: ReadonlyMap<string, unknown>;
+};
+/** A space as a display shows it: the cached fields, a name, and its page. */
+export type ResolvedSpace = Omit<CachedSpace, 'uid' | 'updatedAt'> & {
+    uid?: string;
+    /** The space's name, or a placeholder derived from its handle or uid. */
+    displayName: string;
+    /** Where the space's page is, when both handles are known. */
+    path: string | null;
+    /** Whether the name is the space's own rather than a placeholder. */
+    resolved: boolean;
+};
+/** The uid of a space as the spacer API returns it, raw or converted. */
+export declare const spaceUidOf: (space: any) => string;
+/**
+ * The account a space is addressed under: its organization, else its owner.
+ *
+ * The same order the web application's `resolveSpaceAccountHandle` reads, so
+ * a link built here and a link built there go to the same page.
+ */
+export declare const spaceAccountHandleOf: (space: any) => string;
+/** A space as the cache keeps it, out of a spacer payload, raw or converted. */
+export declare const toCachedSpace: (space: unknown) => CachedSpace | undefined;
+/**
+ * Index loaded spaces by uid, Solr id, the uids of their items, and
+ * account/handle.
+ *
+ * Memoised on the array: a query answers with the same array until it
+ * refetches, so a table of a hundred rows builds the index once, not a hundred
+ * times.
+ */
+export declare const indexSpaces: (spaces: readonly unknown[] | null | undefined) => SpaceIndex;
+/** The loaded space a descriptor names, if any. */
+export declare const findSpace: (index: SpaceIndex, descriptor: SpaceDescriptor) => unknown | undefined;
+/** Where a space's page is: `/<account>/<space>`, or nothing without both. */
+export declare const buildSpaceDetailsPath: ({ accountHandle, handle, }: {
+    accountHandle?: string | null;
+    handle?: string | null;
+}) => string | null;
+/**
+ * What a display shows for a descriptor, given what is known of its space.
+ *
+ * The space's own fields win over the snapshot remembered from an earlier
+ * view, which win over what the row said; the row's name is shown only until
+ * the space's own is known, and a handle or uid stands in before either.
+ */
+export declare const resolveSpace: ({ descriptor, found, cached, placeholderMaxLength, }: {
+    descriptor: SpaceDescriptor;
+    found?: CachedSpace;
+    cached?: CachedSpace;
+    placeholderMaxLength?: number;
+}) => ResolvedSpace;

package/lib/components/spaces/spaceDisplayModel.js

@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+const DEFAULT_PLACEHOLDER_MAX_LENGTH = 12;
+const text = (value) => typeof value === 'string'
+    ? value.trim()
+    : value === null || value === undefined
+        ? ''
+        : String(value).trim();
+const bareHandle = (value) => text(value).replace(/^@+/, '');
+const firstText = (...values) => {
+    for (const value of values) {
+        const candidate = text(value);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return '';
+};
+const truncate = (value, maxLength) => maxLength > 0 && value.length > maxLength
+    ? `${value.slice(0, maxLength)}…`
+    : value;
+/** The uid of a space as the spacer API returns it, raw or converted. */
+export const spaceUidOf = (space) => firstText(space?.uid, space?.uid_s, space?.id);
+/**
+ * The account a space is addressed under: its organization, else its owner.
+ *
+ * The same order the web application's `resolveSpaceAccountHandle` reads, so
+ * a link built here and a link built there go to the same page.
+ */
+export const spaceAccountHandleOf = (space) => bareHandle(firstText(space?.accountHandle, space?.organization?.handle, space?.organization?.handle_s, space?.organization_handle, space?.organization_handle_s, space?.account_handle, space?.account_handle_s, space?.owner?.handle, space?.owner?.handle_s, space?.owner_handle, space?.owner_handle_s));
+/** A space as the cache keeps it, out of a spacer payload, raw or converted. */
+export const toCachedSpace = (space) => {
+    const raw = space;
+    const uid = spaceUidOf(raw);
+    if (!uid) {
+        return undefined;
+    }
+    const isPublic = raw?.public_b ?? raw?.public;
+    return {
+        uid,
+        rootId: text(raw?.id) || undefined,
+        handle: firstText(raw?.handle_s, raw?.handle) || undefined,
+        displayName: firstText(raw?.name_t, raw?.name) || undefined,
+        description: firstText(raw?.description_t, raw?.description) || undefined,
+        variant: firstText(raw?.variant_s, raw?.variant) || undefined,
+        isPublic: typeof isPublic === 'boolean' ? isPublic : undefined,
+        accountHandle: spaceAccountHandleOf(raw) || undefined,
+    };
+};
+const EMPTY_SPACES = Object.freeze([]);
+const INDEXES = new WeakMap();
+/**
+ * Index loaded spaces by uid, Solr id, the uids of their items, and
+ * account/handle.
+ *
+ * Memoised on the array: a query answers with the same array until it
+ * refetches, so a table of a hundred rows builds the index once, not a hundred
+ * times.
+ */
+export const indexSpaces = (spaces) => {
+    const list = Array.isArray(spaces) ? spaces : EMPTY_SPACES;
+    const known = INDEXES.get(list);
+    if (known) {
+        return known;
+    }
+    const byUid = new Map();
+    const byRootId = new Map();
+    const byItemUid = new Map();
+    const byAccountAndHandle = new Map();
+    for (const space of list) {
+        const raw = space;
+        const uid = spaceUidOf(raw);
+        if (!uid) {
+            continue;
+        }
+        byUid.set(uid, space);
+        const rootId = text(raw?.id);
+        if (rootId) {
+            byRootId.set(rootId, space);
+        }
+        const handle = firstText(raw?.handle_s, raw?.handle);
+        const account = spaceAccountHandleOf(raw);
+        if (handle && account) {
+            byAccountAndHandle.set(`${account}/${handle}`, space);
+        }
+        // The spaces listing carries each space's items as children, which is the
+        // only place a row from the cross-space listing can learn its space from
+        // when it did not keep `_root_`.
+        if (Array.isArray(raw?.items)) {
+            for (const item of raw.items) {
+                const itemUid = text(item?.uid);
+                if (itemUid) {
+                    byItemUid.set(itemUid, space);
+                }
+            }
+        }
+    }
+    const index = {
+        byUid,
+        byRootId,
+        byItemUid,
+        byAccountAndHandle,
+    };
+    INDEXES.set(list, index);
+    return index;
+};
+/** The loaded space a descriptor names, if any. */
+export const findSpace = (index, descriptor) => {
+    const uid = text(descriptor.uid);
+    if (uid && index.byUid.has(uid)) {
+        return index.byUid.get(uid);
+    }
+    const rootId = text(descriptor.rootId);
+    if (rootId && index.byRootId.has(rootId)) {
+        return index.byRootId.get(rootId);
+    }
+    const itemUid = text(descriptor.itemUid);
+    if (itemUid && index.byItemUid.has(itemUid)) {
+        return index.byItemUid.get(itemUid);
+    }
+    // A uid is authoritative: when one was given and is not loaded, a space
+    // that merely shares its handle is not the same space.
+    const handle = text(descriptor.handle);
+    const account = bareHandle(descriptor.accountHandle);
+    if (!uid && handle && account) {
+        return index.byAccountAndHandle.get(`${account}/${handle}`);
+    }
+    return undefined;
+};
+/** Where a space's page is: `/<account>/<space>`, or nothing without both. */
+export const buildSpaceDetailsPath = ({ accountHandle, handle, }) => {
+    const account = bareHandle(accountHandle);
+    const space = text(handle);
+    if (!account || !space) {
+        return null;
+    }
+    return `/${encodeURIComponent(account)}/${encodeURIComponent(space)}`;
+};
+/**
+ * What a display shows for a descriptor, given what is known of its space.
+ *
+ * The space's own fields win over the snapshot remembered from an earlier
+ * view, which win over what the row said; the row's name is shown only until
+ * the space's own is known, and a handle or uid stands in before either.
+ */
+export const resolveSpace = ({ descriptor, found, cached, placeholderMaxLength = DEFAULT_PLACEHOLDER_MAX_LENGTH, }) => {
+    const uid = firstText(descriptor.uid, found?.uid, cached?.uid) || undefined;
+    const handle = firstText(found?.handle, cached?.handle, descriptor.handle) || undefined;
+    const accountHandle = bareHandle(firstText(found?.accountHandle, cached?.accountHandle, descriptor.accountHandle)) || undefined;
+    const ownName = firstText(found?.displayName, cached?.displayName);
+    const displayName = ownName ||
+        text(descriptor.displayName) ||
+        truncate(firstText(handle, uid), placeholderMaxLength) ||
+        'Space';
+    const isPublic = typeof found?.isPublic === 'boolean' ? found.isPublic : cached?.isPublic;
+    return {
+        uid,
+        rootId: firstText(found?.rootId, cached?.rootId, descriptor.rootId) || undefined,
+        handle,
+        accountHandle,
+        displayName,
+        description: firstText(found?.description, cached?.description) || undefined,
+        variant: firstText(found?.variant, cached?.variant) || undefined,
+        isPublic,
+        path: buildSpaceDetailsPath({ accountHandle, handle }),
+        resolved: Boolean(ownName),
+    };
+};

package/lib/hooks/cacheConverters.d.ts

@@ -5,13 +5,6 @@
  * @returns The converted snapshot object.
  */
 export declare function asCodeSandboxSnapshot(s: any): any;
-/**
- * Convert a raw page payload into its client shape.
- *
- * @param s - The raw page payload from the API.
- * @returns The converted page object.
- */
-export declare const asPage: (s: any) => any;
 /**
  * Convert a raw space payload into its client shape.
  *