@agent-native/toolkit 0.201.1 → 0.202.0-nightly-20261006033736

package/src/app/sharing/ResourceAccessScreen.tsx

@@ -0,0 +1,331 @@
+import { useT } from "@agent-native/core/client/i18n";
+import { buildSignInReturnHref } from "@agent-native/core/client/sign-in-return";
+import {
+  ActionButton,
+  Dialog,
+  TextArea,
+} from "@agent-native/toolkit/design-system";
+import { cn } from "@agent-native/toolkit/utils";
+import {
+  IconFileUnknown,
+  IconLock,
+  IconLogin2,
+  IconTrash,
+} from "@tabler/icons-react";
+import {
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from "react";
+
+export type ResourceAccessScreenState =
+  | "denied"
+  | "missing"
+  | "trashed"
+  | "signed-out";
+
+/** Asking the owner for access, on the `denied` state. */
+export interface ResourceAccessScreenRequest {
+  /** The viewer already asked, and their request is open. */
+  sent: boolean;
+  /** Sends the request with an optional note; rejects when it fails. */
+  onRequest: (note: string) => Promise<void>;
+  /** A request is being sent. */
+  sending?: boolean;
+  /** Why the last request failed. */
+  error?: { errorCode: string | null } | null;
+}
+
+export interface ResourceAccessScreenProps {
+  state: ResourceAccessScreenState;
+  /** The app's heading for this state, such as "This page doesn't exist". */
+  title?: ReactNode;
+  description?: ReactNode;
+  /** The account the viewer is signed in as, shown as text. */
+  signedInEmail?: string | null;
+  /** The app's own actions, such as a link back to the viewer's work. */
+  actions?: ReactNode;
+  /** Shows Switch account after the app's actions. */
+  onSwitchAccount?: () => void;
+  /**
+   * Replaces the signed-out state's Sign in, which by default goes to sign-in
+   * and comes back to this link.
+   */
+  onSignIn?: () => void;
+  /** Offers Request access on the `denied` state. */
+  request?: ResourceAccessScreenRequest;
+  /**
+   * The app takes access requests for this kind of resource, so the
+   * signed-out state says signing in is how to ask. It says nothing about
+   * this particular link.
+   */
+  acceptsRequests?: boolean;
+  /** Rendered above the screen, such as a sidebar toggle. */
+  header?: ReactNode;
+  /** Render as the page's `main` landmark when the app shell has none. */
+  landmark?: boolean;
+  className?: string;
+}
+
+const STATE_ICONS = {
+  denied: IconLock,
+  missing: IconFileUnknown,
+  trashed: IconTrash,
+  "signed-out": IconLogin2,
+} satisfies Record<ResourceAccessScreenState, unknown>;
+
+/**
+ * What a link to a resource the viewer can't open says, in place of the
+ * resource. It stays on the link's URL, never redirects, and states the
+ * situation as static content, so focus starts on the heading rather than a
+ * toast or live region.
+ */
+export function ResourceAccessScreen({
+  state,
+  title,
+  description,
+  signedInEmail,
+  actions,
+  onSwitchAccount,
+  onSignIn,
+  request,
+  acceptsRequests = false,
+  header,
+  landmark = false,
+  className,
+}: ResourceAccessScreenProps) {
+  const t = useT();
+  const headingId = useId();
+  const headingRef = useRef<HTMLHeadingElement>(null);
+  const [requestOpen, setRequestOpen] = useState(false);
+  const Icon = STATE_ICONS[state];
+  const Root = landmark ? "main" : "div";
+  const signIn =
+    state === "signed-out"
+      ? (onSignIn ?? (() => window.location.assign(buildSignInReturnHref())))
+      : undefined;
+  const offersRequest = state === "denied" && request !== undefined;
+
+  useEffect(() => {
+    headingRef.current?.focus({ preventScroll: true });
+  }, [state]);
+
+  const defaults = {
+    denied: {
+      title: t("agentChat.accessGate.deniedTitle", {
+        defaultValue: "You don't have access",
+      }),
+      description: request
+        ? request.sent
+          ? t("agentChat.accessGate.requestSent", {
+              defaultValue: "Request sent. The owner has been notified.",
+            })
+          : t("agentChat.accessGate.requestDescription", {
+              defaultValue: "Request access and the owner will be notified.",
+            })
+        : t("agentChat.accessGate.deniedDescription", {
+            defaultValue: "Ask the owner to share it with you.",
+          }),
+    },
+    missing: {
+      title: t("agentChat.accessGate.missingTitle", {
+        defaultValue: "This doesn't exist",
+      }),
+      description: t("agentChat.accessGate.missingDescription", {
+        defaultValue: "The link may be wrong, or it may have been deleted.",
+      }),
+    },
+    trashed: {
+      title: t("agentChat.accessGate.trashedTitle", {
+        defaultValue: "This is in the trash",
+      }),
+      description: t("agentChat.accessGate.trashedDescription", {
+        defaultValue: "Restore it to open it again.",
+      }),
+    },
+    "signed-out": {
+      title: t("agentChat.accessGate.signedOutTitle", {
+        defaultValue: "Sign in to continue",
+      }),
+      description: acceptsRequests
+        ? t("agentChat.accessGate.signedOutRequestDescription", {
+            defaultValue: "Sign in to request access.",
+          })
+        : t("agentChat.accessGate.signedOutDescription", {
+            defaultValue: "Sign in with an account that has access.",
+          }),
+    },
+  }[state];
+
+  return (
+    <Root
+      className={cn("flex min-h-0 flex-1 flex-col", className)}
+      data-access-state={state}
+    >
+      {header}
+      <div className="flex min-h-0 flex-1 items-center justify-center bg-background px-6 py-10">
+        <section
+          aria-labelledby={headingId}
+          className="flex w-full max-w-sm flex-col items-center text-center"
+        >
+          <div
+            aria-hidden="true"
+            className="mb-5 flex size-12 items-center justify-center rounded-xl border border-border bg-muted text-muted-foreground"
+          >
+            <Icon size={22} />
+          </div>
+          <h1
+            ref={headingRef}
+            id={headingId}
+            tabIndex={-1}
+            className="text-2xl font-semibold tracking-normal text-foreground outline-none"
+          >
+            {title ?? defaults.title}
+          </h1>
+          {/* A request's outcome is announced politely when it changes; the
+              state on arrival is read from the focused heading instead. */}
+          <p
+            role={offersRequest ? "status" : undefined}
+            className="mt-3 text-sm leading-6 text-muted-foreground"
+          >
+            {description ?? defaults.description}
+          </p>
+          {signedInEmail ? (
+            <p className="mt-4 break-all text-sm text-muted-foreground">
+              {t("agentChat.accessGate.signedInAs", {
+                email: signedInEmail,
+                defaultValue: "You're signed in as {{email}}",
+              })}
+            </p>
+          ) : null}
+          {signIn || actions || onSwitchAccount || offersRequest ? (
+            <div className="mt-6 flex flex-wrap items-center justify-center gap-2">
+              {signIn ? (
+                <ActionButton onPress={signIn}>
+                  {t("agentChat.accessGate.signIn", {
+                    defaultValue: "Sign in",
+                  })}
+                </ActionButton>
+              ) : null}
+              {offersRequest && !request.sent ? (
+                <ActionButton onPress={() => setRequestOpen(true)}>
+                  {t("agentChat.accessGate.requestAccess", {
+                    defaultValue: "Request access",
+                  })}
+                </ActionButton>
+              ) : null}
+              {actions}
+              {onSwitchAccount ? (
+                <ActionButton emphasis="outline" onPress={onSwitchAccount}>
+                  {t("agentChat.accessGate.switchAccount", {
+                    defaultValue: "Switch account",
+                  })}
+                </ActionButton>
+              ) : null}
+            </div>
+          ) : null}
+        </section>
+      </div>
+      {offersRequest ? (
+        <RequestAccessDialog
+          open={requestOpen}
+          onOpenChange={setRequestOpen}
+          request={request}
+          sentFocusRef={headingRef}
+        />
+      ) : null}
+    </Root>
+  );
+}
+
+function RequestAccessDialog({
+  open,
+  onOpenChange,
+  request,
+  sentFocusRef,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  request: ResourceAccessScreenRequest;
+  sentFocusRef: RefObject<HTMLElement | null>;
+}) {
+  const t = useT();
+  const [note, setNote] = useState("");
+  const [failed, setFailed] = useState(false);
+  // Once sent, Request access is gone, so focus can't return to it.
+  const restoreFocusRef = useRef<HTMLElement | null>(null);
+  const errorCode = failed ? (request.error?.errorCode ?? null) : null;
+
+  const send = async () => {
+    setFailed(false);
+    try {
+      await request.onRequest(note);
+      setNote("");
+      restoreFocusRef.current = sentFocusRef.current;
+      onOpenChange(false);
+    } catch {
+      setFailed(true);
+    }
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) setFailed(false);
+        onOpenChange(next);
+      }}
+      title={t("agentChat.accessGate.requestAccess", {
+        defaultValue: "Request access",
+      })}
+      closeLabel={t("agentChat.accessGate.cancel", { defaultValue: "Cancel" })}
+      size="small"
+      restoreFocusRef={restoreFocusRef}
+      footer={
+        <div className="flex justify-end gap-2">
+          <ActionButton emphasis="outline" onPress={() => onOpenChange(false)}>
+            {t("agentChat.accessGate.cancel", { defaultValue: "Cancel" })}
+          </ActionButton>
+          <ActionButton
+            pending={request.sending}
+            disabled={request.sending}
+            onPress={() => void send()}
+          >
+            {t("agentChat.accessGate.sendRequest", {
+              defaultValue: "Send request",
+            })}
+          </ActionButton>
+        </div>
+      }
+    >
+      <TextArea
+        label={t("agentChat.accessGate.requestNoteLabel", {
+          defaultValue: "Note (optional)",
+        })}
+        placeholder={t("agentChat.accessGate.requestNotePlaceholder", {
+          defaultValue: "Add a note for the owner",
+        })}
+        value={note}
+        onChange={setNote}
+        maxLength={500}
+        rows={3}
+        autoFocus
+        errorMessage={
+          failed
+            ? errorCode === "access_request_rate_limited"
+              ? t("agentChat.accessGate.requestRateLimited", {
+                  defaultValue: "Too many requests right now. Try again later.",
+                })
+              : t("agentChat.accessGate.requestFailed", {
+                  defaultValue: "Couldn't send your request. Try again.",
+                })
+            : undefined
+        }
+        invalid={failed}
+      />
+    </Dialog>
+  );
+}

package/src/app/sharing/ShareButton.spec.tsx

@@ -49,14 +49,37 @@ const sharesData = vi.hoisted(() => ({
   },
 }));
 
+const accessRequestsData = vi.hoisted(() => ({
+  current: [] as unknown[],
+  hasMore: false,
+  isError: false,
+}));
+const refetchRequests = vi.hoisted(() => vi.fn(async () => undefined));
+const approveRequest = vi.hoisted(() => vi.fn());
+const queriedActions = vi.hoisted(() => [] as string[]);
+
 vi.mock("@agent-native/core/client/use-action", () => ({
-  useActionQuery: () => ({
-    data: sharesData.current,
-    isError: sharesError.current,
-    refetch: refetchShares,
-  }),
+  useActionQuery: (name: string) => {
+    queriedActions.push(name);
+    return name === "list-resource-access-requests"
+      ? {
+          data: {
+            requests: accessRequestsData.current,
+            hasMore: accessRequestsData.hasMore,
+          },
+          isError: accessRequestsData.isError,
+          refetch: refetchRequests,
+        }
+      : {
+          data: sharesData.current,
+          isError: sharesError.current,
+          refetch: refetchShares,
+        };
+  },
   useActionMutation: (name: string) => ({
     mutate: name === "share-resource" ? shareMutate : otherMutate,
+    mutateAsync:
+      name === "approve-resource-access-request" ? approveRequest : otherMutate,
   }),
 }));
 
@@ -185,6 +208,12 @@ describe("ShareButton", () => {
     );
     shareMutate.mockReset();
     otherMutate.mockReset();
+    approveRequest.mockReset().mockResolvedValue(undefined);
+    accessRequestsData.current = [];
+    accessRequestsData.hasMore = false;
+    accessRequestsData.isError = false;
+    refetchRequests.mockClear();
+    queriedActions.length = 0;
     refetchShares.mockClear();
     popoverInteractOutsideHandlers.length = 0;
     sheetInteractOutsideHandlers.length = 0;
@@ -1207,6 +1236,143 @@ describe("ShareButton", () => {
     expect(container.textContent).not.toContain("owner@example.com");
   });
 
+  const patRequest = {
+    id: "req-1",
+    generation: 3,
+    state: "pending",
+    requester: { email: "requester@example.test", name: "Pat Example" },
+    note: "Need this for the launch review.",
+    requestedAt: "2026-10-01T10:00:00.000Z",
+    decidedAt: null,
+    grantedRole: null,
+    resource: {
+      type: "document",
+      id: "doc-1",
+      label: "Document",
+      title: "Launch plan",
+      path: "/page/doc-1",
+    },
+  };
+
+  async function renderWithRequests() {
+    await act(async () => {
+      root.render(
+        <TooltipProvider>
+          <QueryClientProvider client={queryClient}>
+            <ShareButton
+              resourceType="document"
+              resourceId="doc-1"
+              peopleTabLabel="People"
+              agentsTabLabel="Agents"
+              peopleAccessLabel="Who has access"
+              agentTabContent={<button type="button">Copy agent prompt</button>}
+            />
+          </QueryClientProvider>
+        </TooltipProvider>,
+      );
+    });
+  }
+
+  async function allowPat() {
+    const allow = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="Allow Pat Example"]',
+    );
+    await act(async () => allow!.click());
+  }
+
+  it("lists access requests above who has access, and Allow grants Viewer", async () => {
+    accessRequestsData.current = [patRequest];
+    await renderWithRequests();
+
+    const text = container.textContent ?? "";
+    expect(text).toContain("Need this for the launch review.");
+    expect(text.indexOf("Access requests")).toBeGreaterThan(-1);
+    expect(text.indexOf("Access requests")).toBeLessThan(
+      text.indexOf("Who has access"),
+    );
+
+    await allowPat();
+    expect(approveRequest).toHaveBeenCalledWith({
+      requestId: "req-1",
+      generation: 3,
+      role: "viewer",
+    });
+  });
+
+  it("reloads the requests when someone else already handled one", async () => {
+    accessRequestsData.current = [patRequest];
+    approveRequest.mockRejectedValueOnce(
+      Object.assign(new Error("stale"), {
+        status: 409,
+        errorCode: "access_request_stale",
+      }),
+    );
+    await renderWithRequests();
+
+    await allowPat();
+
+    expect(refetchRequests).toHaveBeenCalledTimes(1);
+    expect(container.textContent).toContain(
+      "Someone already handled this request, or it changed.",
+    );
+  });
+
+  it("says when the requester couldn't be emailed that they're in", async () => {
+    accessRequestsData.current = [patRequest];
+    approveRequest.mockResolvedValueOnce({
+      state: "approved",
+      role: "viewer",
+      email: "failed",
+    });
+    await renderWithRequests();
+
+    await allowPat();
+
+    expect(container.querySelector('[role="status"]')?.textContent).toBe(
+      "Pat Example has access, but we couldn't email them.",
+    );
+  });
+
+  it("keeps saying the email failed when the list can't reload", async () => {
+    accessRequestsData.current = [patRequest];
+    approveRequest.mockImplementationOnce(async () => {
+      accessRequestsData.isError = true;
+      return { state: "approved", role: "viewer", email: "failed" };
+    });
+    await renderWithRequests();
+
+    await allowPat();
+
+    expect(container.textContent).toContain("Couldn't load access requests.");
+    expect(container.querySelector('[role="status"]')?.textContent).toBe(
+      "Pat Example has access, but we couldn't email them.",
+    );
+  });
+
+  it("says when older requests are past the list", async () => {
+    accessRequestsData.current = [patRequest];
+    accessRequestsData.hasMore = true;
+    await renderWithRequests();
+
+    expect(container.textContent).toContain("Showing the 1 newest requests.");
+  });
+
+  it("doesn't read access requests for someone who can't manage access", async () => {
+    sharesData.current = { ...sharesData.current, role: "viewer" };
+    await act(async () => {
+      root.render(
+        <TooltipProvider>
+          <QueryClientProvider client={queryClient}>
+            <ShareButton resourceType="document" resourceId="doc-1" />
+          </QueryClientProvider>
+        </TooltipProvider>,
+      );
+    });
+
+    expect(container.textContent).toContain("People with access");
+    expect(queriedActions).not.toContain("list-resource-access-requests");
+  });
+
   // Keep the non-source-locale provider test last: react-i18next's global
   // fallback instance otherwise leaks the selected language into tests that
   // intentionally exercise providerless compatibility.

package/src/app/sharing/ShareButton.tsx

@@ -57,6 +57,7 @@ import type {
   UIEvent as ReactUIEvent,
 } from "react";
 
+import { AccessRequestsSection } from "./AccessRequestsSection.js";
 import { AgentShareSection } from "./AgentShareSection.js";
 
 export interface ShareButtonProps {
@@ -462,6 +463,12 @@ function SharePanel(
   const generalAccessLabel =
     props.generalAccessLabel ??
     t("agentChat.share.generalAccess", { defaultValue: "General access" });
+  const accessRequests = canManage ? (
+    <AccessRequestsSection
+      resourceType={props.resourceType}
+      resourceId={props.resourceId}
+    />
+  ) : null;
   const shareLinks = (
     <>
       {props.shareUrl ? (
@@ -586,7 +593,10 @@ function SharePanel(
 
       <div className={cn("mb-4 space-y-4", props.agentTabContent && "order-1")}>
         {!props.agentTabContent ? (
-          <div className="text-sm font-semibold">{peopleAccessLabel}</div>
+          <>
+            {accessRequests}
+            <div className="text-sm font-semibold">{peopleAccessLabel}</div>
+          </>
         ) : null}
         {canManage ? (
           <div className="space-y-2">
@@ -711,7 +721,10 @@ function SharePanel(
         ) : null}
 
         {props.agentTabContent ? (
-          <div className="text-sm font-semibold">{peopleAccessLabel}</div>
+          <>
+            {accessRequests}
+            <div className="text-sm font-semibold">{peopleAccessLabel}</div>
+          </>
         ) : null}
         <ul className="flex list-none flex-col gap-1 p-0 m-0">
           {data?.ownerEmail ? (

package/src/app/sharing/ShareDialog.spec.tsx

@@ -19,9 +19,27 @@ const sharesQuery = {
   refetch: vi.fn(),
 };
 
+const requestsQuery = {
+  data: [] as unknown[],
+  isError: false,
+  refetch: vi.fn(),
+};
+const approveRequest = vi.fn(async () => undefined);
+
 vi.mock("@agent-native/core/client/use-action", () => ({
-  useActionQuery: () => sharesQuery,
-  useActionMutation: () => ({ mutate: vi.fn(), isPending: false }),
+  useActionQuery: (name: string) =>
+    name === "list-resource-access-requests"
+      ? {
+          ...requestsQuery,
+          data: { requests: requestsQuery.data, hasMore: false },
+        }
+      : sharesQuery,
+  useActionMutation: (name: string) => ({
+    mutate: vi.fn(),
+    mutateAsync:
+      name === "approve-resource-access-request" ? approveRequest : vi.fn(),
+    isPending: false,
+  }),
 }));
 vi.mock("@agent-native/core/client/i18n", () => ({
   useT: () => (key: string, values?: Record<string, string>) =>
@@ -51,6 +69,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  requestsQuery.data = [];
   act(() => root.unmount());
   queryClient.clear();
   container.remove();
@@ -195,3 +214,53 @@ describe("ShareDialog primitive normalization", () => {
     expect(onClose).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("ShareDialog access requests", () => {
+  it("lists pending requests above people with access and allows as Viewer", async () => {
+    requestsQuery.data = [
+      {
+        id: "req-1",
+        generation: 3,
+        state: "pending",
+        requester: { email: "requester@example.test", name: "Pat Example" },
+        note: "Need this for the launch review.",
+        requestedAt: "2026-10-01T10:00:00.000Z",
+        decidedAt: null,
+        grantedRole: null,
+        resource: {
+          type: "document",
+          id: "doc-1",
+          label: "Document",
+          title: "Quarterly plan",
+          path: "/page/doc-1",
+        },
+      },
+    ];
+    await renderDialog();
+
+    const text = document.body.textContent ?? "";
+    expect(text).toContain("Pat Example");
+    expect(text).toContain("requester@example.test");
+    expect(text).toContain("Need this for the launch review.");
+    expect(text.indexOf("share.accessRequests")).toBeGreaterThan(-1);
+    expect(text.indexOf("share.accessRequests")).toBeLessThan(
+      text.indexOf("share.peopleWithAccess"),
+    );
+
+    const allow = document.body.querySelector<HTMLButtonElement>(
+      'button[aria-label="agentChat.share.allowRequestFrom"]',
+    );
+    await act(async () => allow?.click());
+    expect(approveRequest).toHaveBeenCalledWith({
+      requestId: "req-1",
+      generation: 3,
+      role: "viewer",
+    });
+  });
+
+  it("shows no requests section when nothing is pending", async () => {
+    await renderDialog();
+
+    expect(document.body.textContent).not.toContain("share.accessRequests");
+  });
+});