@datalayer/core 1.1.60 → 1.2.10

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

@@ -1,19 +1,74 @@
+import type { JSX } from 'react';
 export type ItemAccessLevel = 'view' | 'update' | 'execute';
-type PrincipalKind = 'personal' | 'team' | 'organization';
+/**
+ * Who a resource can be shared with. `agent` is a service agent: sharing with
+ * one grants that agent alone — the grant is matched on the agent's own uid,
+ * never on the people who can act through it — so it is a principal in its own
+ * right rather than a shorthand for its organization.
+ */
+type PrincipalKind = 'personal' | 'team' | 'organization' | 'agent';
+/**
+ * One level the dialog offers, and what it is called. A resource whose
+ * service grants other levels than view, update and execute names its own —
+ * a benchmark's Reviewer and Runner, for one.
+ */
+export type AccessLevelOption = {
+    level: string;
+    label: string;
+};
+type SharingLevelPayload = {
+    userUids?: string[];
+    teamUids?: string[];
+    organizationUids?: string[];
+    agentUids?: string[];
+};
+type SharingPayload = {
+    access?: Partial<Record<string, SharingLevelPayload>>;
+};
+export type ShareAccessTransport = {
+    load: () => Promise<Record<string, any>>;
+    save: (sharing: SharingPayload) => Promise<void>;
+};
 export type ShareAccessComponentProps = {
     isOpen: boolean;
     requestUrl?: string;
+    transport?: ShareAccessTransport;
     resourceLabel: string;
     resourceName?: string;
     resourceDescription?: string;
     expanded?: boolean;
     onSharingAccessRestrictedChange?: (restricted: boolean, message?: string) => void;
-    defaultAccessLevel?: ItemAccessLevel;
+    defaultAccessLevel?: string;
+    /** The levels offered, lowest first; view, update and execute when not named. */
+    levels?: readonly AccessLevelOption[];
     principalKinds?: readonly PrincipalKind[];
     displayMode?: 'dialog' | 'inline';
     onClose: () => void;
 };
-export declare function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resourceName, resourceDescription: _resourceDescription, expanded, onSharingAccessRestrictedChange, defaultAccessLevel, principalKinds, displayMode, onClose, }: ShareAccessComponentProps): JSX.Element | null;
+type AccessByLevel = Record<string, {
+    userUids: string[];
+    teamUids: string[];
+    organizationUids: string[];
+    agentUids: string[];
+}>;
+type ACLPrincipalEntry = {
+    kind: PrincipalKind;
+    uid: string;
+    levels: string[];
+};
+type OwnerPrincipal = {
+    kind: PrincipalKind;
+    uid: string;
+    handle: string;
+    displayName: string;
+    avatarUrl?: string;
+    origin?: string;
+    accountHandle?: string;
+};
+export declare function extractOwnerPrincipals(payload: any): OwnerPrincipal[];
+export declare function buildAclEntries(state: AccessByLevel, principalKinds: readonly PrincipalKind[]): ACLPrincipalEntry[];
+export declare function hydrateAccessFromSharing(sharing: SharingPayload, levels: readonly AccessLevelOption[]): AccessByLevel;
+export declare function ShareAccessComponent({ isOpen, requestUrl, transport, resourceLabel, resourceName, resourceDescription: _resourceDescription, expanded, onSharingAccessRestrictedChange, defaultAccessLevel, levels, principalKinds, displayMode, onClose, }: ShareAccessComponentProps): JSX.Element | null;
 export default ShareAccessComponent;
 export declare const ShareAccessDialog: typeof ShareAccessComponent;
 export type ShareAccessDialogProps = ShareAccessComponentProps;

package/lib/components/sharing/ShareAccessComponent.js

@@ -1,8 +1,4 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the Modified BSD License.
- */
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { ChevronDownIcon, ChevronUpIcon, KeyIcon, PersonIcon, OrganizationIcon, PeopleIcon, } from '@primer/octicons-react';
 import { Box } from '@datalayer/primer-addons';
@@ -14,17 +10,17 @@ import { PrincipalBadge } from '../principal/PrincipalBadge.js';
 // ---------------------------------------------------------------------------
 // Constants.
 // ---------------------------------------------------------------------------
-const ACCESS_LEVELS = ['view', 'update', 'execute'];
+const DEFAULT_ACCESS_LEVELS = [
+    { level: 'view', label: 'Viewer' },
+    { level: 'update', label: 'Editor' },
+    { level: 'execute', label: 'Executor' },
+];
 const DEFAULT_PRINCIPAL_KINDS = [
     'personal',
     'team',
     'organization',
+    'agent',
 ];
-const ACCESS_LEVEL_LABELS = {
-    view: 'Viewer',
-    update: 'Editor',
-    execute: 'Executor',
-};
 // ---------------------------------------------------------------------------
 // String / payload helpers.
 // ---------------------------------------------------------------------------
@@ -44,6 +40,9 @@ function normalizePrincipalKind(kindRaw) {
     if (kind === 'organization' || kind === 'org') {
         return 'organization';
     }
+    if (kind === 'agent') {
+        return 'agent';
+    }
     return 'personal';
 }
 function toTitleCase(value) {
@@ -84,6 +83,9 @@ function ensurePrincipalDisplayName(kind, ...candidates) {
     if (kind === 'team') {
         return 'Team';
     }
+    if (kind === 'agent') {
+        return 'Agent';
+    }
     return 'Principal';
 }
 function formatPrincipalHandle(kind, handle, accountHandle) {
@@ -113,7 +115,7 @@ function principalKey(kind, uid) {
 // ---------------------------------------------------------------------------
 // Owner extraction (preserves all current fallbacks).
 // ---------------------------------------------------------------------------
-function extractOwnerPrincipals(payload) {
+export function extractOwnerPrincipals(payload) {
     const ownersFromSharing = Array.isArray(payload?.sharing?.owners)
         ? payload.sharing.owners
         : [];
@@ -136,7 +138,11 @@ function extractOwnerPrincipals(payload) {
         payload?.resource?.owner ||
         payload?.sharing?.owner ||
         {};
-    const ownerUid = pickFirstString(ownerPayload?.uid, ownerPayload?.owner_uid, ownerPayload?.ownerUid, ownerPayload?.id, payload?.owner_uid, payload?.ownerUid);
+    const ownerUid = pickFirstString(ownerPayload?.uid, ownerPayload?.owner_uid, ownerPayload?.ownerUid, ownerPayload?.id, payload?.owner_uid, payload?.ownerUid, 
+    // Runtimes names a sandbox's owner inside its `sharing` document rather
+    // than beside it. Without this the dialog draws no owner at all, which
+    // reads as a resource nobody owns.
+    payload?.sharing?.owner_uid, payload?.sharing?.ownerUid);
     const ownerHandle = pickFirstString(ownerPayload?.handle_s, ownerPayload?.handle, ownerPayload?.owner_handle, ownerPayload?.ownerHandle, payload?.owner_handle, payload?.ownerHandle);
     const kindFromOwnerPayload = normalizePrincipalKind(pickFirstString(ownerPayload?.kind, ownerPayload?.type, ownerPayload?.principal_kind, ownerPayload?.principalKind, payload?.owner_kind, payload?.ownerKind, payload?.owner_type, payload?.ownerType));
     const accountHandle = pickFirstString(ownerPayload?.organization_handle_s, ownerPayload?.organizationHandle, ownerPayload?.organization_handle, payload?.space?.organization_handle_s, payload?.space?.organizationHandle, payload?.space?.organization_handle);
@@ -216,19 +222,20 @@ function extractOwnerPrincipals(payload) {
 // ---------------------------------------------------------------------------
 // AccessByLevel helpers.
 // ---------------------------------------------------------------------------
-function emptyAccessByLevel() {
-    return {
-        view: { userUids: [], teamUids: [], organizationUids: [] },
-        update: { userUids: [], teamUids: [], organizationUids: [] },
-        execute: { userUids: [], teamUids: [], organizationUids: [] },
-    };
+function emptyAccessByLevel(levels) {
+    return Object.fromEntries(levels.map(({ level }) => [
+        level,
+        { userUids: [], teamUids: [], organizationUids: [], agentUids: [] },
+    ]));
 }
 function bucketFor(kind) {
     return kind === 'personal'
         ? 'userUids'
         : kind === 'team'
             ? 'teamUids'
-            : 'organizationUids';
+            : kind === 'agent'
+                ? 'agentUids'
+                : 'organizationUids';
 }
 function hasPrincipal(state, level, kind, uid) {
     const lower = uid.toLowerCase();
@@ -250,17 +257,15 @@ function withPrincipalAdded(state, level, kind, uid) {
 function withPrincipalRemoved(state, kind, uid) {
     const lower = uid.toLowerCase();
     const bucket = bucketFor(kind);
-    const next = {
-        view: { ...state.view },
-        update: { ...state.update },
-        execute: { ...state.execute },
-    };
-    for (const level of ACCESS_LEVELS) {
-        next[level][bucket] = next[level][bucket].filter(value => value.toLowerCase() !== lower);
-    }
-    return next;
+    return Object.fromEntries(Object.entries(state).map(([level, principals]) => [
+        level,
+        {
+            ...principals,
+            [bucket]: principals[bucket].filter(value => value.toLowerCase() !== lower),
+        },
+    ]));
 }
-function buildAclEntries(state, principalKinds) {
+export function buildAclEntries(state, principalKinds) {
     const allowed = new Set(principalKinds);
     const byPrincipal = new Map();
     const upsert = (kind, uid, level) => {
@@ -277,10 +282,11 @@ function buildAclEntries(state, principalKinds) {
             existing.levels.push(level);
         }
     };
-    for (const level of ACCESS_LEVELS) {
+    for (const level of Object.keys(state)) {
         state[level].userUids.forEach(uid => upsert('personal', uid, level));
         state[level].teamUids.forEach(uid => upsert('team', uid, level));
         state[level].organizationUids.forEach(uid => upsert('organization', uid, level));
+        state[level].agentUids.forEach(uid => upsert('agent', uid, level));
     }
     return Array.from(byPrincipal.values()).sort((a, b) => {
         if (a.kind !== b.kind) {
@@ -289,28 +295,20 @@ function buildAclEntries(state, principalKinds) {
         return a.uid.localeCompare(b.uid);
     });
 }
-function hydrateAccessFromSharing(sharing) {
+export function hydrateAccessFromSharing(sharing, levels) {
     const access = sharing.access || {};
-    const view = access.view || {};
-    const update = access.update || {};
-    const execute = access.execute || {};
-    return {
-        view: {
-            userUids: [...(view.userUids || [])],
-            teamUids: [...(view.teamUids || [])],
-            organizationUids: [...(view.organizationUids || [])],
-        },
-        update: {
-            userUids: [...(update.userUids || [])],
-            teamUids: [...(update.teamUids || [])],
-            organizationUids: [...(update.organizationUids || [])],
-        },
-        execute: {
-            userUids: [...(execute.userUids || [])],
-            teamUids: [...(execute.teamUids || [])],
-            organizationUids: [...(execute.organizationUids || [])],
-        },
-    };
+    return Object.fromEntries(levels.map(({ level }) => {
+        const given = access[level] || {};
+        return [
+            level,
+            {
+                userUids: [...(given.userUids || [])],
+                teamUids: [...(given.teamUids || [])],
+                organizationUids: [...(given.organizationUids || [])],
+                agentUids: [...(given.agentUids || [])],
+            },
+        ];
+    }));
 }
 // ---------------------------------------------------------------------------
 // Avatar shimmer (used while a user row is being hydrated).
@@ -329,6 +327,38 @@ function AvatarShimmer({ size = 20 }) {
             },
         } }));
 }
+// ---------------------------------------------------------------------------
+// Row components.
+// ---------------------------------------------------------------------------
+/**
+ * An agent's avatar. A service agent has no picture, handle or banner of its
+ * own — it is a credential, not a person — so it is drawn as a key rather than
+ * pushed through the personal/team/organization avatar system.
+ */
+function AgentAvatar({ size = 20 }) {
+    return (_jsx(Box, { sx: {
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: size,
+            height: size,
+            borderRadius: 2,
+            bg: 'canvas.subtle',
+            color: 'fg.muted',
+            flexShrink: 0,
+        }, "aria-label": "Agent", children: _jsx(KeyIcon, { size: Math.max(12, Math.round(size * 0.6)) }) }));
+}
+/** An agent as it appears in a row of principals: key, name, and the label
+ * that says what it is, so an agent is never mistaken for a person. */
+function AgentPrincipalChip({ displayName, size = 20, }) {
+    return (_jsxs(Box, { sx: {
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 1,
+            minWidth: 0,
+            flexWrap: 'wrap',
+        }, children: [_jsx(AgentAvatar, { size: size }), _jsx(Text, { sx: { minWidth: 0 }, children: displayName }), _jsx(Label, { size: "small", children: "Agent" })] }));
+}
 function OwnerPrincipalRow({ ownerPrincipal, cache, showAvatarSkeleton = false, isPlatformAdmin, }) {
     const entry = cache[principalKey(ownerPrincipal.kind, ownerPrincipal.uid)] || {};
     const cachedHandle = entry.handle;
@@ -369,7 +399,7 @@ function AccessPrincipalRow({ entry, cache, showAvatarSkeleton = false, isPlatfo
             alignItems: 'center',
             gap: 1,
             flexWrap: 'wrap',
-        }, children: showAvatarSkeleton ? (_jsxs(_Fragment, { children: [_jsx(AvatarShimmer, { size: 20 }), _jsx(Text, { children: resolvedDisplayName })] })) : (_jsx(PrincipalBadge, { principal: {
+        }, children: showAvatarSkeleton ? (_jsxs(_Fragment, { children: [_jsx(AvatarShimmer, { size: 20 }), _jsx(Text, { children: resolvedDisplayName })] })) : entry.kind === 'agent' ? (_jsx(AgentPrincipalChip, { displayName: resolvedDisplayName })) : (_jsx(PrincipalBadge, { principal: {
                 kind: entry.kind,
                 uid: entry.uid,
                 displayName: resolvedDisplayName,
@@ -382,7 +412,7 @@ function AccessPrincipalRow({ entry, cache, showAvatarSkeleton = false, isPlatfo
 // ---------------------------------------------------------------------------
 // Main component.
 // ---------------------------------------------------------------------------
-export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resourceName, resourceDescription: _resourceDescription, expanded = false, onSharingAccessRestrictedChange, defaultAccessLevel = 'view', principalKinds = DEFAULT_PRINCIPAL_KINDS, displayMode = 'dialog', onClose, }) {
+export function ShareAccessComponent({ isOpen, requestUrl, transport, resourceLabel, resourceName, resourceDescription: _resourceDescription, expanded = false, onSharingAccessRestrictedChange, defaultAccessLevel = 'view', levels = DEFAULT_ACCESS_LEVELS, principalKinds = DEFAULT_PRINCIPAL_KINDS, displayMode = 'dialog', onClose, }) {
     void _resourceDescription;
     const { token, user } = useIAMStore();
     const { configuration } = useCoreStore();
@@ -393,7 +423,8 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
     const [isSaving, setIsSaving] = useState(false);
     const [isExpanded, setIsExpanded] = useState(expanded);
     const [selectedAccessLevel, setSelectedAccessLevel] = useState(defaultAccessLevel);
-    const [access, setAccess] = useState(emptyAccessByLevel());
+    const levelLabels = useMemo(() => Object.fromEntries(levels.map(({ level, label }) => [level, label])), [levels]);
+    const [access, setAccess] = useState(() => emptyAccessByLevel(levels));
     const [ownerPrincipals, setOwnerPrincipals] = useState([]);
     const [shareablePrincipals, setShareablePrincipals] = useState([]);
     const [isLoadingShareable, setIsLoadingShareable] = useState(false);
@@ -432,7 +463,7 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
         onSharingAccessRestrictedChange,
     ]);
     // ----- Derived -----
-    const canRequest = Boolean(requestUrl && token);
+    const canRequest = Boolean(token && (requestUrl || transport));
     const canSearchPrincipals = Boolean(configuration?.iamUrl && token);
     const iamUrl = configuration?.iamUrl;
     const principalKindsSet = useMemo(() => new Set(principalKinds), [principalKinds]);
@@ -492,7 +523,7 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
             userHydrationMissesRef.current = new Set();
             return;
         }
-        if (!canRequest || !requestUrl) {
+        if (!canRequest) {
             setIsLoading(false);
             setIsSharingAccessConfirmed(false);
             return;
@@ -507,14 +538,18 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
             setIsSharingAccessConfirmed(false);
             setSharingAccessMessage(null);
             try {
-                const response = await fetch(requestUrl, {
-                    method: 'GET',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        Authorization: `Bearer ${token}`,
-                    },
-                });
-                const payload = await response.json();
+                const response = transport
+                    ? null
+                    : await fetch(requestUrl, {
+                        method: 'GET',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            Authorization: `Bearer ${token}`,
+                        },
+                    });
+                const payload = transport
+                    ? await transport.load()
+                    : await response.json();
                 const message = payload?.detail ||
                     payload?.message ||
                     `Unable to load ${resourceLabel.toLowerCase()} sharing.`;
@@ -522,19 +557,19 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
                     if (!cancelled && isSharingAuthorizationMessage(message)) {
                         setSharingAccessMessage(message);
                         setIsSharingAccessConfirmed(true);
-                        setAccess(emptyAccessByLevel());
+                        setAccess(emptyAccessByLevel(levels));
                         setOwnerPrincipals([]);
                         return;
                     }
                     throw new Error(message);
                 }
-                if (!response.ok) {
+                if (response && !response.ok) {
                     if (response.status === 403 ||
                         isSharingAuthorizationMessage(message)) {
                         if (!cancelled) {
                             setSharingAccessMessage(message);
                             setIsSharingAccessConfirmed(true);
-                            setAccess(emptyAccessByLevel());
+                            setAccess(emptyAccessByLevel(levels));
                             setOwnerPrincipals([]);
                         }
                         return;
@@ -546,7 +581,7 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
                 }
                 const sharing = (payload?.sharing || {});
                 const owners = extractOwnerPrincipals(payload);
-                const hydrated = hydrateAccessFromSharing(sharing);
+                const hydrated = hydrateAccessFromSharing(sharing, levels);
                 setOwnerPrincipals(owners);
                 owners.forEach(owner => {
                     mergePrincipalCacheEntry(owner.kind, owner.uid, {
@@ -585,9 +620,11 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
         isOpen,
         canRequest,
         requestUrl,
+        transport,
         token,
         resourceLabel,
         resourceName,
+        levels,
         mergePrincipalCacheEntry,
     ]);
     // ----- Fetch shareable principals on open -----
@@ -1009,30 +1046,29 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
     ]);
     // ----- Auto-save on access change after hydration -----
     const saveAccess = useCallback(async (snapshot) => {
-        if (!canRequest || !requestUrl) {
+        if (!canRequest) {
             return;
         }
         setIsSaving(true);
         try {
             const body = {
-                access: {
-                    view: {
-                        userUids: snapshot.view.userUids,
-                        teamUids: snapshot.view.teamUids,
-                        organizationUids: snapshot.view.organizationUids,
-                    },
-                    update: {
-                        userUids: snapshot.update.userUids,
-                        teamUids: snapshot.update.teamUids,
-                        organizationUids: snapshot.update.organizationUids,
+                access: Object.fromEntries(Object.entries(snapshot).map(([level, principals]) => [
+                    level,
+                    {
+                        userUids: principals.userUids,
+                        teamUids: principals.teamUids,
+                        organizationUids: principals.organizationUids,
+                        agentUids: principals.agentUids,
                     },
-                    execute: {
-                        userUids: snapshot.execute.userUids,
-                        teamUids: snapshot.execute.teamUids,
-                        organizationUids: snapshot.execute.organizationUids,
-                    },
-                },
+                ])),
             };
+            if (transport) {
+                await transport.save(body);
+                enqueueToastRef.current(`${resourceLabel} sharing updated.`, {
+                    variant: 'success',
+                });
+                return;
+            }
             const response = await fetch(requestUrl, {
                 method: 'PUT',
                 headers: {
@@ -1073,7 +1109,7 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
         finally {
             setIsSaving(false);
         }
-    }, [canRequest, requestUrl, token, resourceLabel]);
+    }, [canRequest, requestUrl, token, resourceLabel, transport]);
     useEffect(() => {
         if (!hasHydratedSharingRef.current) {
             return;
@@ -1161,7 +1197,8 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
         const otherUsers = filtered.filter(p => p.kind === 'personal' && p.uid !== selfUid);
         const orgs = filtered.filter(p => p.kind === 'organization');
         const teams = filtered.filter(p => p.kind === 'team');
-        return { self, otherUsers, orgs, teams };
+        const agents = filtered.filter(p => p.kind === 'agent');
+        return { self, otherUsers, orgs, teams, agents };
     }, [shareablePrincipals, principalKindsSet, user?.uid]);
     useEffect(() => {
         if (isOpen) {
@@ -1184,7 +1221,9 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
             ? PersonIcon
             : principal.kind === 'organization'
                 ? OrganizationIcon
-                : PeopleIcon;
+                : principal.kind === 'agent'
+                    ? KeyIcon
+                    : PeopleIcon;
         return (_jsxs(Box, { as: "button", type: "button", onClick: () => {
                 if (!alreadyAdded) {
                     addPrincipal(principal.kind, principal.uid);
@@ -1214,7 +1253,7 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
                         alignItems: 'center',
                         gap: 2,
                         minWidth: 0,
-                    }, children: [_jsx(PrincipalAvatar, { kind: principal.kind, avatarUrl: principal.avatarUrl || undefined, alt: displayName, size: 22 }), _jsxs(Box, { sx: { display: 'grid', minWidth: 0 }, children: [_jsxs(Box, { sx: {
+                    }, children: [principal.kind === 'agent' ? (_jsx(AgentAvatar, { size: 22 })) : (_jsx(PrincipalAvatar, { kind: principal.kind, avatarUrl: principal.avatarUrl || undefined, alt: displayName, size: 22 })), _jsxs(Box, { sx: { display: 'grid', minWidth: 0 }, children: [_jsxs(Box, { sx: {
                                         display: 'inline-flex',
                                         alignItems: 'center',
                                         gap: 1,
@@ -1262,7 +1301,9 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
                             alignItems: 'flex-start',
                             justifyContent: 'space-between',
                             gap: 2,
-                        }, children: [_jsx(Box, { sx: { display: 'grid', gap: 1 }, children: _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: ["Share ", resourceName || `this ${resourceLabel.toLowerCase()}`, ". Pick a principal below \u2014 they will be granted the selected access level."] }) }), _jsxs(ActionMenu, { children: [_jsxs(Box, { sx: { display: 'inline-flex', alignItems: 'center', gap: 1 }, children: [_jsx(ActionMenu.Anchor, { children: _jsxs(Button, { variant: "default", size: "small", leadingVisual: KeyIcon, disabled: isSaving || isReadOnly, children: ["Access: ", ACCESS_LEVEL_LABELS[selectedAccessLevel]] }) }), _jsx(Button, { variant: "invisible", size: "small", leadingVisual: isExpanded ? ChevronUpIcon : ChevronDownIcon, onClick: () => setIsExpanded(previous => !previous), "aria-label": isExpanded ? 'Shrink sharing details' : 'Expand sharing details', children: isExpanded ? 'Shrink details' : 'Expand details' })] }), _jsx(ActionMenu.Overlay, { width: "small", children: _jsx(ActionList, { selectionVariant: "single", children: ACCESS_LEVELS.map(level => (_jsx(ActionList.Item, { selected: selectedAccessLevel === level, onSelect: () => setSelectedAccessLevel(level), children: ACCESS_LEVEL_LABELS[level] }, level))) }) })] })] }), !isExpanded && (_jsxs(Box, { sx: {
+                        }, children: [_jsx(Box, { sx: { display: 'grid', gap: 1 }, children: _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: ["Share ", resourceName || `this ${resourceLabel.toLowerCase()}`, ". Pick a principal below \u2014 they will be granted the selected access level."] }) }), _jsxs(ActionMenu, { children: [_jsxs(Box, { sx: { display: 'inline-flex', alignItems: 'center', gap: 1 }, children: [_jsx(ActionMenu.Anchor, { children: _jsxs(Button, { variant: "default", size: "small", leadingVisual: KeyIcon, disabled: isSaving || isReadOnly, children: ["Access:", ' ', levelLabels[selectedAccessLevel] || selectedAccessLevel] }) }), _jsx(Button, { variant: "invisible", size: "small", leadingVisual: isExpanded ? ChevronUpIcon : ChevronDownIcon, onClick: () => setIsExpanded(previous => !previous), "aria-label": isExpanded
+                                                    ? 'Shrink sharing details'
+                                                    : 'Expand sharing details', children: isExpanded ? 'Shrink details' : 'Expand details' })] }), _jsx(ActionMenu.Overlay, { width: "small", children: _jsx(ActionList, { selectionVariant: "single", children: levels.map(({ level, label }) => (_jsx(ActionList.Item, { selected: selectedAccessLevel === level, onSelect: () => setSelectedAccessLevel(level), children: label }, level))) }) })] })] }), !isExpanded && (_jsxs(Box, { sx: {
                             px: 3,
                             py: 2,
                             borderRadius: 2,
@@ -1272,7 +1313,7 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
                             bg: 'canvas.default',
                             display: 'grid',
                             gap: 1,
-                        }, children: [_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Sharing details are collapsed." }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: [aclEntries.length, " principal", aclEntries.length === 1 ? '' : 's', " currently granted access."] })] })), isExpanded && (_jsxs(_Fragment, { children: [_jsxs(Box, { sx: {
+                        }, children: [_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Sharing details are collapsed." }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: [aclEntries.length, " principal", aclEntries.length === 1 ? '' : 's', ' ', "currently granted access."] })] })), isExpanded && (_jsxs(_Fragment, { children: [_jsxs(Box, { sx: {
                                     px: 3,
                                     py: 2,
                                     borderRadius: 2,
@@ -1303,11 +1344,16 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
                                             alignItems: 'center',
                                             justifyContent: 'space-between',
                                             gap: 2,
-                                        }, children: [_jsx(Text, { sx: { fontSize: 1, fontWeight: 600 }, children: "Share with\u2026" }), isLoadingShareable && (_jsxs(Box, { sx: { display: 'inline-flex', alignItems: 'center', gap: 1 }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Loading\u2026" })] }))] }), !isLoadingShareable &&
+                                        }, children: [_jsx(Text, { sx: { fontSize: 1, fontWeight: 600 }, children: "Share with\u2026" }), isLoadingShareable && (_jsxs(Box, { sx: {
+                                                    display: 'inline-flex',
+                                                    alignItems: 'center',
+                                                    gap: 1,
+                                                }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Loading\u2026" })] }))] }), !isLoadingShareable &&
                                         groupedShareable.self.length === 0 &&
                                         groupedShareable.otherUsers.length === 0 &&
                                         groupedShareable.orgs.length === 0 &&
-                                        groupedShareable.teams.length === 0 ? (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "No principals available to share with." })) : (_jsxs(Box, { sx: { display: 'grid', gap: 2 }, children: [renderShareableGroup('You', groupedShareable.self), renderShareableGroup('Other users', groupedShareable.otherUsers), renderShareableGroup('Your organizations', groupedShareable.orgs), renderShareableGroup('Your teams', groupedShareable.teams)] }))] }), _jsxs(Box, { sx: {
+                                        groupedShareable.teams.length === 0 &&
+                                        groupedShareable.agents.length === 0 ? (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "No principals available to share with." })) : (_jsxs(Box, { sx: { display: 'grid', gap: 2 }, children: [renderShareableGroup('You', groupedShareable.self), renderShareableGroup('Other users', groupedShareable.otherUsers), renderShareableGroup('Your organizations', groupedShareable.orgs), renderShareableGroup('Your teams', groupedShareable.teams), renderShareableGroup('Agents', groupedShareable.agents)] }))] }), _jsxs(Box, { sx: {
                                     px: 3,
                                     py: 2,
                                     borderRadius: 2,
@@ -1350,14 +1396,13 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
                                                         display: 'inline-flex',
                                                         alignItems: 'center',
                                                         gap: 2,
-                                                    }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Searching\u2026" })] })) : searchResults.length === 0 ? (_jsx(Box, { sx: { px: 3, py: 2 }, children: _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "No principals found." }) })) : (_jsx(ActionList, { children: searchResults.map(result => (_jsxs(ActionList.Item, { onSelect: () => handleSearchResultSelect(result), children: [_jsx(ActionList.LeadingVisual, { children: _jsx(PrincipalAvatar, { kind: result.kind, avatarUrl: result.avatarUrl, alt: result.displayName, size: 18 }) }), _jsxs(Box, { sx: {
+                                                    }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Searching\u2026" })] })) : searchResults.length === 0 ? (_jsx(Box, { sx: { px: 3, py: 2 }, children: _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "No principals found." }) })) : (_jsx(ActionList, { children: searchResults.map(result => (_jsxs(ActionList.Item, { onSelect: () => handleSearchResultSelect(result), children: [_jsx(ActionList.LeadingVisual, { children: result.kind === 'agent' ? (_jsx(AgentAvatar, { size: 18 })) : (_jsx(PrincipalAvatar, { kind: result.kind, avatarUrl: result.avatarUrl, alt: result.displayName, size: 18 })) }), _jsxs(Box, { sx: {
                                                                     display: 'inline-flex',
                                                                     alignItems: 'center',
                                                                     gap: 1,
                                                                     flexWrap: 'wrap',
                                                                 }, children: [_jsx(Text, { children: result.displayName }), result.kind === 'personal' && (_jsx(Label, { size: "small", variant: "secondary", children: result.origin ||
-                                                                            principalCache[principalKey('personal', result.uid)]
-                                                                                ?.origin ||
+                                                                            principalCache[principalKey('personal', result.uid)]?.origin ||
                                                                             'Datalayer' }))] }), _jsxs(ActionList.Description, { variant: "block", children: ["@", result.handle] })] }, principalKey(result.kind, result.uid)))) })) }))] })] }), _jsxs(Box, { sx: {
                                     px: 3,
                                     py: 2,
@@ -1393,7 +1438,7 @@ export function ShareAccessComponent({ isOpen, requestUrl, resourceLabel, resour
                                                             flexWrap: 'wrap',
                                                             gap: 1,
                                                             justifyContent: 'flex-end',
-                                                        }, children: entry.levels.map(level => (_jsx(Label, { size: "small", variant: "secondary", children: ACCESS_LEVEL_LABELS[level] }, level))) }), _jsx(Button, { size: "small", variant: "invisible", onClick: () => removePrincipal(entry.kind, entry.uid), disabled: isSaving, children: "Remove" })] }, principalKey(entry.kind, entry.uid)))) })) })] })] }))] }), _jsxs(Box, { sx: {
+                                                        }, children: entry.levels.map(level => (_jsx(Label, { size: "small", variant: "secondary", children: levelLabels[level] || level }, level))) }), _jsx(Button, { size: "small", variant: "invisible", onClick: () => removePrincipal(entry.kind, entry.uid), disabled: isSaving, children: "Remove" })] }, principalKey(entry.kind, entry.uid)))) })) })] })] }))] }), _jsxs(Box, { sx: {
                     display: 'flex',
                     justifyContent: 'flex-end',
                     alignItems: 'center',

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

@@ -1,8 +1,29 @@
+/**
+ * SharingEditor — inline editor for the sharing payload shape used by
+ * `ShareAccessComponent` ACL endpoints.
+ *
+ * Unlike `ShareAccessComponent` (which is bound to a server-side resource
+ * via `requestUrl`), this component edits a free-form
+ * `{ access: { view/update/execute: { userUids, teamUids, organizationUids,
+ * agentUids } } }`
+ * blob in memory. It is intended for "create" flows where the resource does
+ * not yet exist and the sharing payload must be POSTed alongside the rest of
+ * the configuration.
+ *
+ * This is a scaffold: it currently exposes a structured JSON editor with
+ * validation and the canonical default shape. Future iterations can replace
+ * the textarea with the same principal-picker UI used by
+ * `ShareAccessComponent`.
+ */
+import type { JSX } from 'react';
 export type SharingAccessLevel = 'view' | 'update' | 'execute';
 export type SharingLevelPayload = {
     userUids?: string[];
     teamUids?: string[];
     organizationUids?: string[];
+    /** Service agents. A grant here is to that agent alone, matched on its own
+     * uid, never to the people who can act through it. */
+    agentUids?: string[];
 };
 export type SharingPayload = {
     access?: Partial<Record<SharingAccessLevel, SharingLevelPayload>>;