@gooddata/sdk-ui-ext 11.43.0-alpha.1 → 11.43.0-alpha.3

package/esm/share/useAccessList.d.ts

@@ -0,0 +1,51 @@
+import type { IObjectPermissionsObject } from "@gooddata/sdk-backend-spi";
+import { type IGranularAccessGrantee, type IObjectAccessList, type ObjRef } from "@gooddata/sdk-model";
+import { type GeneralAccessValue, type IUiGranteeAsyncOptions } from "@gooddata/sdk-ui-kit";
+import { type IGranteeOverlayEntry } from "./objectShareController.helpers.js";
+import type { IObjectShareControllerState, IObjectShareGrantee } from "./objectShareController.types.js";
+import type { IObjectAccessSummary } from "./types.js";
+/**
+ * The owned access list + optimistic overlay for {@link useObjectShareController}.
+ *
+ * @internal
+ */
+export interface IAccessList {
+    /** Stable serialized key of the current target's ref, or undefined when none. */
+    targetKey: string | undefined;
+    /** The owned list as it applies to the *current* target (undefined while a switch is pending). */
+    currentAccessList: IObjectAccessList | undefined;
+    /** Committed grantee rows overlaid with optimistic intent (add/level/remove). */
+    grantees: IObjectShareGrantee[];
+    /** Sorted, comma-joined committed grantee ids — a stable key for resolution effects. */
+    granteeIdsKey: string;
+    /** Optimistic-aware general access (workspace vs restricted). */
+    generalAccess: GeneralAccessValue;
+    /** Inline access summary (optimistic-aware), or undefined before the first load. */
+    summary: IObjectAccessSummary | undefined;
+    /** Top-level load status surfaced as the controller status. */
+    status: IObjectShareControllerState["status"];
+    /** Error from the initial/target-change load. */
+    loadError: Error | undefined;
+    /** Commit a grant change, toast on success, then background-refresh. False on failure. */
+    commit: (mutate: IGranularAccessGrantee[], successMessage: {
+        id: string;
+    }) => Promise<boolean>;
+    /** Picker loader — available assignees minus already-granted, filtered by query. */
+    loadOptions: (search: string) => Promise<IUiGranteeAsyncOptions>;
+    /** Resolve a grantee id back to the picker's original ObjRef (preserves Uri vs Id ref). */
+    refForId: (id: string) => ObjRef;
+    setOverlay: React.Dispatch<React.SetStateAction<Record<string, IGranteeOverlayEntry>>>;
+    setKnownNames: React.Dispatch<React.SetStateAction<Record<string, string>>>;
+    setOptimisticGeneralAccess: React.Dispatch<React.SetStateAction<GeneralAccessValue | undefined>>;
+}
+/**
+ * Owns the backend access list and its optimistic overlay. The list is fetched
+ * via `useCancelablePromise` then owned locally: mutations patch the overlay and
+ * a background refresh reconciles it, so the grantee list never blanks between a
+ * change and the server response. A target switch is handled by stamping the
+ * fetched list with its target and reading through `currentAccessList`.
+ *
+ * @internal
+ */
+export declare function useAccessList(target: IObjectPermissionsObject | undefined, onSaved: (() => void) | undefined): IAccessList;
+//# sourceMappingURL=useAccessList.d.ts.map

package/esm/share/useAccessList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAccessList.d.ts","sourceRoot":"","sources":["../../src/share/useAccessList.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EACH,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,MAAM,EAEd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,sBAAsB,EAAmB,MAAM,sBAAsB,CAAC;AAI7G,OAAO,EACH,KAAK,oBAAoB,EAM5B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACzG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,iFAAiF;IACjF,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,kGAAkG;IAClG,iBAAiB,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACjD,iFAAiF;IACjF,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,0FAAwF;IACxF,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,aAAa,EAAE,kBAAkB,CAAC;IAClC,oFAAoF;IACpF,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAC1C,+DAA+D;IAC/D,MAAM,EAAE,2BAA2B,CAAC,QAAQ,CAAC,CAAC;IAC9C,iDAAiD;IACjD,SAAS,EAAE,KAAK,GAAG,SAAS,CAAC;IAE7B,0FAA0F;IAC1F,MAAM,EAAE,CAAC,MAAM,EAAE,sBAAsB,EAAE,EAAE,cAAc,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/F,sFAAoF;IACpF,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACjE,2FAA2F;IAC3F,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IAEjC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;IACvF,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5E,0BAA0B,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC,CAAC;CACpG;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CACzB,MAAM,EAAE,wBAAwB,GAAG,SAAS,EAC5C,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAClC,WAAW,CAsRb"}

package/esm/share/useAccessList.js

@@ -0,0 +1,263 @@
+// (C) 2026 GoodData Corporation
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { objRefToString, } from "@gooddata/sdk-model";
+import { useBackendStrict, useCancelablePromise, useWorkspaceStrict } from "@gooddata/sdk-ui";
+import { useToastMessage } from "@gooddata/sdk-ui-kit";
+import { deriveGeneralAccess, deriveWorkspacePermissionLevel } from "./accessSummary.js";
+import { objectShareMessages } from "./messages.js";
+import { assigneeMatchesQuery, granteeId, granteesFromAccessList, mergeOverlay, reconcileOverlay, } from "./objectShareController.helpers.js";
+/**
+ * Owns the backend access list and its optimistic overlay. The list is fetched
+ * via `useCancelablePromise` then owned locally: mutations patch the overlay and
+ * a background refresh reconciles it, so the grantee list never blanks between a
+ * change and the server response. A target switch is handled by stamping the
+ * fetched list with its target and reading through `currentAccessList`.
+ *
+ * @internal
+ */
+export function useAccessList(target, onSaved) {
+    const backend = useBackendStrict();
+    const workspace = useWorkspaceStrict();
+    const toast = useToastMessage();
+    const [accessList, setAccessList] = useState(undefined);
+    const [accessListTarget, setAccessListTarget] = useState(undefined);
+    const [loadStatus, setLoadStatus] = useState(target ? "loading" : "idle");
+    const [loadError, setLoadError] = useState(undefined);
+    // Optimistic overlay keyed by grantee id. Each entry holds the *intended* row
+    // (add/level-change) or a removal, plus a pending flag while the write is in
+    // flight. The backend has read-after-write lag, so we show the intended state
+    // and clear an entry only once a refresh confirms it (or the write fails).
+    const [overlay, setOverlay] = useState({});
+    // Display names learned from the picker; keep a human name on a row after the
+    // optimistic overlay reconciles away (the grant often returns only a raw id).
+    const [knownNames, setKnownNames] = useState({});
+    // Original ObjRef per grantee id, learned from the picker (the access-list id
+    // is a serialized `kind:identifier`, which loses Uri-vs-Id). Reused for writes.
+    const [knownRefs, setKnownRefs] = useState({});
+    // Optimistic general-access override — held from confirm until the fetched list
+    // reflects it, so the radio + summary update instantly.
+    const [optimisticGeneralAccess, setOptimisticGeneralAccess] = useState(undefined);
+    const targetKey = target ? objRefToString(target.ref) : undefined;
+    // The owned list as it applies to the *current* target. A target switch makes
+    // the previous fetch's list stale until the new one lands; gating on the stamp
+    // means everything derived ignores it immediately — no reset effect.
+    const currentAccessList = accessListTarget === targetKey ? accessList : undefined;
+    // Always-current target key, read inside async callbacks that captured an older
+    // one. A background refresh started for the previous target can resolve after a
+    // switch; without this it would stamp the list back to the stale target, leaving
+    // the new target's `currentAccessList` undefined (and, with the load-gated
+    // status, stuck "loading" since its own fetch already settled).
+    const targetKeyRef = useRef(targetKey);
+    targetKeyRef.current = targetKey;
+    // Initial (and target-change) load. Feeds setAccessList once; thereafter we own it.
+    const { result: fetchedList, status: fetchStatus, error: fetchError, } = useCancelablePromise({
+        promise: target
+            ? () => backend.workspace(workspace).objectPermissions().getAccessList(target)
+            : undefined,
+    }, 
+    // Key on the serialized ref, not the ObjRef object — an inline idRef(...) is a
+    // new instance each render and would otherwise refetch forever.
+    [backend, workspace, target?.kind, targetKey]);
+    useEffect(() => {
+        if (fetchStatus === "success" && fetchedList) {
+            // The cancelable promise is keyed on targetKey, so this list is for it.
+            setAccessList(fetchedList);
+            setAccessListTarget(targetKey);
+            setLoadStatus("idle");
+            setLoadError(undefined);
+            setOverlay({}); // a target-change load is authoritative; drop stale overlay
+            setOptimisticGeneralAccess(undefined);
+        }
+        else if (fetchStatus === "error") {
+            setLoadStatus("error");
+            setLoadError(fetchError instanceof Error ? fetchError : new Error(String(fetchError)));
+        }
+        else if (fetchStatus === "loading") {
+            setLoadStatus("loading");
+        }
+    }, [fetchStatus, fetchedList, fetchError, targetKey]);
+    // Background refresh — pulls server truth without nulling the current list,
+    // then reconciles the overlay (clears entries the server now confirms).
+    const refresh = useCallback(async () => {
+        if (!target) {
+            return;
+        }
+        try {
+            const fresh = await backend.workspace(workspace).objectPermissions().getAccessList(target);
+            // The target may have changed while this refresh was in flight. Stamping
+            // a stale target's list now would clobber the new target's stamp and
+            // strand it loading, so drop the result if we've since switched away.
+            if (targetKeyRef.current !== targetKey) {
+                return;
+            }
+            setAccessList(fresh);
+            setAccessListTarget(targetKey);
+            setOverlay((prev) => reconcileOverlay(granteesFromAccessList(fresh), prev));
+            // Drop the optimistic general-access override once the server confirms it.
+            const freshGeneralAccess = deriveGeneralAccess(fresh.grants);
+            setOptimisticGeneralAccess((prev) => (prev === freshGeneralAccess ? undefined : prev));
+        }
+        catch {
+            // The refresh failed, but the mutation that triggered it already
+            // succeeded. The overlay can't be reconciled against fresh data now, so
+            // settle it optimistically: keep each entry's intended state (a `set`
+            // value stays, a `remove` keeps hiding the row) but clear its `pending`
+            // flag. Otherwise rows would spin on "saving"/"removing" forever even
+            // though the change persisted and a success toast was shown.
+            setOverlay((prev) => {
+                let changed = false;
+                const next = {};
+                for (const [id, entry] of Object.entries(prev)) {
+                    if (entry.pending) {
+                        changed = true;
+                        next[id] = { ...entry, pending: false };
+                    }
+                    else {
+                        next[id] = entry;
+                    }
+                }
+                return changed ? next : prev;
+            });
+        }
+    }, [backend, workspace, target, targetKey]);
+    // Committed rows overlaid with optimistic intent; backfill a human name from
+    // the picker cache where the grant only carried a raw id.
+    const grantees = useMemo(() => {
+        if (!currentAccessList) {
+            return [];
+        }
+        const committed = granteesFromAccessList(currentAccessList).map((g) => {
+            const known = knownNames[g.id];
+            return known && g.name === objRefToString(g.granteeRef) ? { ...g, name: known } : g;
+        });
+        return mergeOverlay(committed, overlay);
+    }, [currentAccessList, overlay, knownNames]);
+    const granteeIdsKey = granteesFromAccessList(currentAccessList)
+        .map((g) => g.id)
+        .sort()
+        .join(",");
+    const committedGeneralAccess = useMemo(() => (currentAccessList ? deriveGeneralAccess(currentAccessList.grants) : "RESTRICTED"), [currentAccessList]);
+    const generalAccess = optimisticGeneralAccess ?? committedGeneralAccess;
+    const summary = useMemo(() => {
+        if (!currentAccessList) {
+            return undefined;
+        }
+        return {
+            generalAccess,
+            // While the optimistic override is active we just wrote the workspace
+            // rule as VIEW, so report VIEW rather than the stale fetched grant
+            // (which can still read SHARE through read-after-write lag).
+            workspaceLevel: optimisticGeneralAccess
+                ? "VIEW"
+                : deriveWorkspacePermissionLevel(currentAccessList.grants),
+            granteeCount: grantees.length,
+        };
+    }, [currentAccessList, generalAccess, optimisticGeneralAccess, grantees]);
+    // "success" only once the *current* target's list has actually landed. After a
+    // target switch the stamp clears `currentAccessList` immediately, but
+    // `loadStatus` still reads "idle" from the previous target's completed load
+    // until the effect re-runs — so gating on loadStatus alone would briefly report
+    // "success" with no list, letting the dialog enable mutations and the catalog
+    // row hide both summary and skeleton. Treat "no list for this target yet" as
+    // loading.
+    const status = target
+        ? loadStatus === "error"
+            ? "error"
+            : loadStatus === "loading" || !currentAccessList
+                ? "loading"
+                : "success"
+        : "idle";
+    // Commit a single grant change against the backend, then reconcile via refresh.
+    // Optimistic state is applied by the caller; on failure the caller's rollback
+    // runs and a toast is shown.
+    const commit = useCallback(async (mutate, successMessage) => {
+        if (!target) {
+            return false;
+        }
+        try {
+            await backend
+                .workspace(workspace)
+                .objectPermissions()
+                .manageObjectPermissions(target, mutate);
+            toast.addSuccess(successMessage);
+            onSaved?.();
+            await refresh();
+            return true;
+        }
+        catch {
+            toast.addError(objectShareMessages.toastError);
+            return false;
+        }
+    }, [backend, workspace, target, toast, onSaved, refresh]);
+    // Picker loader — fetches available assignees on demand, filters by the typed
+    // query, excludes anything already granted. Depends only on the grant sources
+    // (accessList, overlay), so its identity changes only when the granted set
+    // actually changes. It must NOT write state that feeds its own deps.
+    const loadOptions = useCallback(async (search) => {
+        if (!target) {
+            return { groups: [], users: [] };
+        }
+        const assignees = await backend
+            .workspace(workspace)
+            .objectPermissions()
+            .getAvailableAssignees(target);
+        const query = search.trim().toLowerCase();
+        const withIds = assignees.map((a) => ({
+            assignee: a,
+            id: granteeId(a.type === "user" ? "user" : "group", a.ref),
+        }));
+        // Remember every assignee's real name + ref so granted rows can show them
+        // even when the access-list grant later returns only a raw id. Safe here:
+        // neither is a dependency of loadOptions, so this won't re-trigger it.
+        setKnownNames((prev) => {
+            const next = { ...prev };
+            for (const { assignee, id } of withIds) {
+                next[id] = assignee.name;
+            }
+            return next;
+        });
+        setKnownRefs((prev) => {
+            const next = { ...prev };
+            for (const { assignee, id } of withIds) {
+                next[id] = assignee.ref;
+            }
+            return next;
+        });
+        const excluded = new Set(mergeOverlay(granteesFromAccessList(currentAccessList), overlay).map((g) => g.id));
+        const selectable = withIds
+            .filter(({ id }) => !excluded.has(id)) // hide anyone already granted
+            .filter(({ assignee }) => assigneeMatchesQuery(assignee, query));
+        return {
+            users: selectable
+                .filter(({ assignee }) => assignee.type === "user")
+                .map(({ assignee, id }) => ({
+                id,
+                kind: "user",
+                name: assignee.name,
+                email: assignee.type === "user" ? assignee.email : undefined,
+            })),
+            groups: selectable
+                .filter(({ assignee }) => assignee.type !== "user")
+                .map(({ assignee, id }) => ({ id, kind: "group", name: assignee.name })),
+        };
+    }, [backend, workspace, target, currentAccessList, overlay]);
+    // Reuse the picker's original ref (preserves UriRef vs IdentifierRef);
+    // fall back to the serialized id only if it wasn't cached.
+    const refForId = useCallback((id) => knownRefs[id] ?? { identifier: id.split(":", 2)[1] }, [knownRefs]);
+    return {
+        targetKey,
+        currentAccessList,
+        grantees,
+        granteeIdsKey,
+        generalAccess,
+        summary,
+        status,
+        loadError,
+        commit,
+        loadOptions,
+        refForId,
+        setOverlay,
+        setKnownNames,
+        setOptimisticGeneralAccess,
+    };
+}

package/esm/share/useLabelScope.d.ts

@@ -0,0 +1,54 @@
+import { type MutableRefObject } from "react";
+import { type IObjectPermissionsObject } from "@gooddata/sdk-backend-spi";
+import type { IObjectAccessList } from "@gooddata/sdk-model";
+import { type LabelScopePrincipal } from "./objectShareController.helpers.js";
+import type { IObjectShareLabel } from "./types.js";
+/**
+ * Per-label access scope for the share dialog: which labels each grantee can
+ * reach, which labels are independently permissionable, and the single write
+ * path that grants/revokes label access.
+ *
+ * @internal
+ */
+export interface ILabelScope {
+    /**
+     * Labels that can actually take a per-label grant (a display form whose
+     * permissions endpoint responded). Until resolution completes, this is the
+     * full `labels` list.
+     */
+    effectiveLabels: IObjectShareLabel[];
+    /**
+     * Whether per-label resolution has finished (the permissionable set + each
+     * grantee's scope are known). False while labels are still loading or the probe
+     * is in flight, and false when label metadata failed to load (scope is then
+     * unknowable, so acting on it would silently orphan real label grants). True
+     * only for a genuinely label-free object. Callers gate every access-changing
+     * control (label edits, Add, remove, general access) on this so they don't act
+     * on the "assume all labels" placeholder.
+     */
+    labelsResolved: boolean;
+    /** Per-grantee label scope: grantee id → label ids in scope (primary always in). */
+    selectedLabelIdsByGrantee: Record<string, string[]>;
+    setSelectedLabelIdsByGrantee: React.Dispatch<React.SetStateAction<Record<string, string[]>>>;
+    /**
+     * Grantee ids whose scope was just written optimistically; the resolution
+     * effect keeps these instead of overwriting them through read-after-write lag.
+     */
+    optimisticScopeRef: MutableRefObject<Set<string>>;
+    /**
+     * The single per-label write path. Diffs `desired` vs `current` over the
+     * permissionable labels and grants/revokes for one principal. Returns false
+     * if any write fails (callers surface the error and roll back).
+     */
+    reconcileLabelScope: (principal: LabelScopePrincipal, desiredLabelIds: ReadonlySet<string>, currentLabelIds: ReadonlySet<string>) => Promise<boolean>;
+}
+/**
+ * Owns label-scope resolution + writes for {@link useObjectShareController}.
+ * Resolves each grantee's scope by fetching every label's access list, tracks
+ * which labels are permissionable, and exposes one reconcile primitive shared by
+ * add / remove / general-access / the labels picker so their behavior can't drift.
+ *
+ * @internal
+ */
+export declare function useLabelScope(target: IObjectPermissionsObject | undefined, targetKey: string | undefined, labels: IObjectShareLabel[], currentAccessList: IObjectAccessList | undefined, granteeIdsKey: string, labelsError: boolean, labelsLoading: boolean): ILabelScope;
+//# sourceMappingURL=useLabelScope.d.ts.map

package/esm/share/useLabelScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLabelScope.d.ts","sourceRoot":"","sources":["../../src/share/useLabelScope.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,gBAAgB,EAAqD,MAAM,OAAO,CAAC;AAEjG,OAAO,EAAE,KAAK,wBAAwB,EAA6B,MAAM,2BAA2B,CAAC;AACrG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG7D,OAAO,EACH,KAAK,mBAAmB,EAI3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAWpD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IACxB;;;;OAIG;IACH,eAAe,EAAE,iBAAiB,EAAE,CAAC;IACrC;;;;;;;;OAQG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB,sFAAoF;IACpF,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACpD,4BAA4B,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7F;;;OAGG;IACH,kBAAkB,EAAE,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAClD;;;;OAIG;IACH,mBAAmB,EAAE,CACjB,SAAS,EAAE,mBAAmB,EAC9B,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,EACpC,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,KACnC,OAAO,CAAC,OAAO,CAAC,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CACzB,MAAM,EAAE,wBAAwB,GAAG,SAAS,EAC5C,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,iBAAiB,EAAE,EAC3B,iBAAiB,EAAE,iBAAiB,GAAG,SAAS,EAChD,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,OAAO,EACpB,aAAa,EAAE,OAAO,GACvB,WAAW,CAoKb"}

package/esm/share/useLabelScope.js

@@ -0,0 +1,160 @@
+// (C) 2026 GoodData Corporation
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { isUnexpectedResponseError } from "@gooddata/sdk-backend-spi";
+import { useBackendStrict, useWorkspaceStrict } from "@gooddata/sdk-ui";
+import { buildLabelMutations, granteesFromAccessList, isGranteeGrantedIn, } from "./objectShareController.helpers.js";
+/**
+ * Whether a label's access-list error means the label is genuinely not
+ * independently permissionable (a definitive 404 / 501), as opposed to a
+ * transient failure (5xx / 403 / network) that should NOT drop a real label.
+ */
+function isNotPermissionable(error) {
+    return isUnexpectedResponseError(error) && (error.httpStatus === 404 || error.httpStatus === 501);
+}
+/**
+ * Owns label-scope resolution + writes for {@link useObjectShareController}.
+ * Resolves each grantee's scope by fetching every label's access list, tracks
+ * which labels are permissionable, and exposes one reconcile primitive shared by
+ * add / remove / general-access / the labels picker so their behavior can't drift.
+ *
+ * @internal
+ */
+export function useLabelScope(target, targetKey, labels, currentAccessList, granteeIdsKey, labelsError, labelsLoading) {
+    const backend = useBackendStrict();
+    const workspace = useWorkspaceStrict();
+    const [selectedLabelIdsByGrantee, setSelectedLabelIdsByGrantee] = useState({});
+    const optimisticScopeRef = useRef(new Set());
+    // Label ids whose permissions endpoint responded — not every display form is
+    // independently permissionable (some 404). `undefined` means "not resolved
+    // yet" (assume all).
+    const [permissionableLabelIds, setPermissionableLabelIds] = useState(undefined);
+    const labelsKey = labels.map((l) => l.id).join(",");
+    // A target switch OR a label-set change invalidates the previous probe's
+    // permissionable set; until the resolution effect re-derives it,
+    // `effectiveLabels` must fall back to all labels rather than filter against
+    // stale ids. Resetting on `labelsKey` too matters when the label set changes
+    // under the same target (e.g. labels finish loading): otherwise the old
+    // permissionable set would briefly mark scope resolved and filter the new
+    // labels against stale ids, so add/share could skip expected per-label grants.
+    useEffect(() => {
+        setPermissionableLabelIds(undefined);
+    }, [targetKey, labelsKey]);
+    // Resolve each grantee's label scope: fetch every label's access list once and
+    // record, per grantee, which labels they appear in (primary label always counts).
+    // Keyed on the committed grantee ids + labels so it re-resolves after add/remove.
+    // `hasAccessList` is a dep too: a list that loads with no named grantees keeps
+    // `granteeIdsKey` empty, so without it the effect would never run and the
+    // permissionable set (404 filtering) would never resolve.
+    const hasAccessList = currentAccessList !== undefined;
+    useEffect(() => {
+        if (!target || labels.length === 0 || !currentAccessList) {
+            return;
+        }
+        let cancelled = false;
+        const committedGranteeIds = granteesFromAccessList(currentAccessList).map((g) => g.id);
+        Promise.all(labels.map((label) => backend
+            .workspace(workspace)
+            .objectPermissions()
+            .getAccessList({ kind: "label", ref: label.ref })
+            .then((list) => ({ label, list }))
+            // Only a definitive 404/501 means the label can't take a per-label
+            // grant. A transient failure (5xx / 403 / network) must NOT drop a
+            // real label — return it without grant info so it stays grantable.
+            .catch((error) => ({ label, transient: !isNotPermissionable(error) })))).then((results) => {
+            if (cancelled) {
+                return;
+            }
+            const resolved = {};
+            for (const id of committedGranteeIds) {
+                resolved[id] = [];
+            }
+            const permissionable = new Set();
+            for (const result of results) {
+                if ("transient" in result) {
+                    // Keep transiently-failed labels permissionable (don't hide a real
+                    // label); skip definitively-not-permissionable ones (404/501).
+                    if (result.transient) {
+                        permissionable.add(result.label.id);
+                    }
+                    continue;
+                }
+                const { label, list } = result;
+                permissionable.add(label.id);
+                for (const id of committedGranteeIds) {
+                    // Primary label is always part of the scope; others are scoped
+                    // only when the grantee actually holds a grant on that label.
+                    if (label.isPrimary || isGranteeGrantedIn(list, id)) {
+                        resolved[id].push(label.id);
+                    }
+                }
+            }
+            setSelectedLabelIdsByGrantee((prev) => {
+                // Keep a just-written optimistic scope through read-after-write lag;
+                // take the freshly-resolved scope for everyone else.
+                const next = { ...resolved };
+                for (const id of optimisticScopeRef.current) {
+                    if (prev[id]) {
+                        next[id] = prev[id];
+                    }
+                }
+                return next;
+            });
+            setPermissionableLabelIds(permissionable);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [backend, workspace, targetKey, labelsKey, granteeIdsKey, hasAccessList]);
+    // A label-set change OR a target switch re-resolves scopes; drop the optimistic-
+    // scope guard so the freshly-resolved scopes aren't held stale. Keying on
+    // labelsKey alone leaked across objects that happen to share a labelsKey (e.g.
+    // during navigation, before the new object's labels load): the prior object's
+    // optimistic entries would then merge over the new object's resolved scopes and
+    // show/save the wrong label grants. targetKey makes the guard per-object.
+    useEffect(() => {
+        optimisticScopeRef.current = new Set();
+    }, [labelsKey, targetKey]);
+    // Only labels whose permissions endpoint responded are scope-controllable; until
+    // resolution completes (permissionableLabelIds undefined) assume all are usable.
+    // While the current target's list isn't loaded yet, ignore a permissionable set
+    // left over from a previous object so we never mis-filter the new labels.
+    const effectiveLabels = useMemo(() => currentAccessList && permissionableLabelIds
+        ? labels.filter((l) => permissionableLabelIds.has(l.id))
+        : labels, [labels, permissionableLabelIds, currentAccessList]);
+    // Resolution is done when the probe has produced a permissionable set, or when
+    // there are genuinely no labels to probe (a label-free object). Until then
+    // callers must treat the scope as unknown (not "all selected").
+    //
+    // Crucially, an EMPTY `labels` list only means "resolved" when labels aren't
+    // still loading and didn't error: while they load, the consumer hasn't passed
+    // them yet (labels === [] with loading true), and on error they can't be known.
+    // Treating either as resolved would let row controls reconcile against an empty
+    // label set and silently orphan real per-label grants. So stay unresolved while
+    // labels are pending, regardless of the current (possibly empty) list.
+    const labelsPending = labelsError || labelsLoading;
+    const labelsResolved = !labelsPending && (labels.length === 0 || permissionableLabelIds !== undefined);
+    // The single per-label write path. Diffs `desired` vs `current` over the
+    // permissionable labels and applies the grants/revokes for one principal
+    // (a grantee, or the all-workspace-users rule). Returns false if ANY write
+    // fails — callers surface the error and roll back, so a partial write never
+    // looks like success (no silent .catch). Used by add, remove, general access
+    // and the labels picker alike, so their label behavior can't drift.
+    const reconcileLabelScope = useCallback(async (principal, desiredLabelIds, currentLabelIds) => {
+        const writes = buildLabelMutations(principal, desiredLabelIds, currentLabelIds, effectiveLabels);
+        if (writes.length === 0) {
+            return true;
+        }
+        const svc = backend.workspace(workspace).objectPermissions();
+        const results = await Promise.allSettled(writes.map((w) => svc.manageObjectPermissions({ kind: "label", ref: w.ref }, [w.grantee])));
+        return results.every((r) => r.status === "fulfilled");
+    }, [effectiveLabels, backend, workspace]);
+    return {
+        effectiveLabels,
+        labelsResolved,
+        selectedLabelIdsByGrantee,
+        setSelectedLabelIdsByGrantee,
+        optimisticScopeRef,
+        reconcileLabelScope,
+    };
+}

package/esm/share/useObjectShare.d.ts

@@ -0,0 +1,50 @@
+import type { IObjectPermissionsObject } from "@gooddata/sdk-backend-spi";
+import type { IObjectShareController } from "./objectShareController.types.js";
+import type { IObjectShareLabel } from "./types.js";
+/**
+ * Options for {@link useObjectShare}.
+ *
+ * @internal
+ */
+export interface IUseObjectShareOptions {
+    /**
+     * Fires after each successful access mutation (add grantee, change level,
+     * remove, general access toggle). Use it to keep UI outside the dialog in
+     * sync with edits made inside it (e.g. refresh an inline access row).
+     */
+    onSaved?: () => void;
+    /**
+     * Labels (display forms) of the shared attribute, enabling the per-grantee
+     * label-scope picker. Omit for objects without labels (e.g. facts).
+     */
+    labels?: IObjectShareLabel[];
+    /**
+     * Whether loading the object's labels failed. While true the controller stays
+     * label-unresolved so every access-changing control is disabled: with the
+     * label set unknown, reconciling access would diff against an empty set and
+     * silently orphan any real per-label grants. Distinct from an object that
+     * genuinely has no labels (omit `labels`), where editing is safe.
+     */
+    labelsError?: boolean;
+    /**
+     * Whether the object's labels are still loading. While true the controller stays
+     * label-unresolved (same gating as `labelsError`): the labels aren't passed yet,
+     * so an empty list must not be mistaken for a label-free object — otherwise row
+     * controls would reconcile against an empty set and orphan real per-label grants.
+     */
+    labelsLoading?: boolean;
+}
+/**
+ * Connected controller hook backing {@link ObjectShareDialog}. Most consumers
+ * do not need this — render `ObjectShareDialog` with plain props and it owns
+ * its controller. Use this hook directly only to share a single access-list
+ * fetch between the dialog and an inline summary row: call it once, read
+ * `state.summary` for the row, and pass the controller into the dialog.
+ *
+ * The hook eagerly fetches the access list on mount so `state.summary` is
+ * usable while the dialog is closed.
+ *
+ * @internal
+ */
+export declare function useObjectShare(target: IObjectPermissionsObject | undefined, options?: IUseObjectShareOptions): IObjectShareController;
+//# sourceMappingURL=useObjectShare.d.ts.map

package/esm/share/useObjectShare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useObjectShare.d.ts","sourceRoot":"","sources":["../../src/share/useObjectShare.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAE1E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC7B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC1B,MAAM,EAAE,wBAAwB,GAAG,SAAS,EAC5C,OAAO,CAAC,EAAE,sBAAsB,GACjC,sBAAsB,CAQxB"}

package/esm/share/useObjectShare.js

@@ -0,0 +1,17 @@
+// (C) 2026 GoodData Corporation
+import { useObjectShareController } from "./useObjectShareController.js";
+/**
+ * Connected controller hook backing {@link ObjectShareDialog}. Most consumers
+ * do not need this — render `ObjectShareDialog` with plain props and it owns
+ * its controller. Use this hook directly only to share a single access-list
+ * fetch between the dialog and an inline summary row: call it once, read
+ * `state.summary` for the row, and pass the controller into the dialog.
+ *
+ * The hook eagerly fetches the access list on mount so `state.summary` is
+ * usable while the dialog is closed.
+ *
+ * @internal
+ */
+export function useObjectShare(target, options) {
+    return useObjectShareController(target, options?.onSaved, options?.labels, options?.labelsError, options?.labelsLoading);
+}

package/esm/share/useObjectShareController.d.ts

@@ -0,0 +1,24 @@
+import type { IObjectPermissionsObject } from "@gooddata/sdk-backend-spi";
+import { type IObjectShareController } from "./objectShareController.types.js";
+import type { IObjectShareLabel } from "./types.js";
+/**
+ * Manages the share dialog state and backend I/O for a single shareable
+ * object.
+ *
+ * The access list is fetched (and re-fetched after every save) via
+ * `useCancelablePromise`; everything that reflects the backend — the grantee
+ * rows, general-access value, summary — is derived from it on render, never
+ * copied into local state. Local state is only the dialog's own transient UI:
+ * the active subview, the add-grantee buffer, the pending general-access
+ * confirm, and an in-flight save flag. Top-level open/close is the consumer's
+ * concern (see {@link ObjectShareDialog}).
+ *
+ * Mutations follow a **commit-on-interaction** model: each access change is
+ * sent immediately; the general-access toggle goes through a confirm step
+ * because it is high-impact. There is no batched Save. The list is fetched
+ * eagerly so `state.summary` also drives an inline access row while closed.
+ *
+ * @internal
+ */
+export declare function useObjectShareController(target: IObjectPermissionsObject | undefined, onSaved?: () => void, labels?: IObjectShareLabel[], labelsError?: boolean, labelsLoading?: boolean): IObjectShareController;
+//# sourceMappingURL=useObjectShareController.d.ts.map

package/esm/share/useObjectShareController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useObjectShareController.d.ts","sourceRoot":"","sources":["../../src/share/useObjectShareController.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAW1E,OAAO,EACH,KAAK,sBAAsB,EAK9B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAIpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,wBAAwB,GAAG,SAAS,EAC5C,OAAO,CAAC,EAAE,MAAM,IAAI,EACpB,MAAM,GAAE,iBAAiB,EAAc,EACvC,WAAW,UAAQ,EACnB,aAAa,UAAQ,GACtB,sBAAsB,CAyZxB"}