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

package/src/app/sharing/AccessRequestApprovalPage.tsx

@@ -0,0 +1,307 @@
+import { signOut, useSession } from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
+import {
+  useAccessRequestReview,
+  type AccessRequestReview,
+  type AccessRequestRole,
+} from "@agent-native/core/client/sharing/useAccessRequestReview";
+import {
+  ActionButton,
+  Avatar,
+  Picker,
+  Skeleton,
+  Status,
+} from "@agent-native/toolkit/design-system";
+import { cn } from "@agent-native/toolkit/utils";
+import { useEffect, useId, useRef, useState, type ReactNode } from "react";
+import { Link, useParams } from "react-router";
+
+import { ResourceAccessScreen } from "./ResourceAccessScreen.js";
+
+export interface AccessRequestApprovalPageProps {
+  /**
+   * The request id from the link in the owner's email or notification.
+   * Defaults to the route's `requestId` param.
+   */
+  requestId?: string;
+  /** Replaces Switch account, which by default signs out. */
+  onSwitchAccount?: () => void;
+  /** Rendered above the page, 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 ROLES = ["viewer", "commenter", "editor", "admin"] as const;
+
+/**
+ * Where an access request's email and notification lead: who is asking, for
+ * what, and Allow or Decline. Opening it only reads; the decision is always an
+ * explicit press. Someone who can't manage the resource sees the same
+ * unavailable screen whether or not the request exists.
+ */
+export function AccessRequestApprovalPage({
+  requestId,
+  onSwitchAccount,
+  header,
+  landmark = false,
+  className,
+}: AccessRequestApprovalPageProps) {
+  const t = useT();
+  const params = useParams();
+  const { session } = useSession();
+  const controller = useAccessRequestReview(
+    requestId ?? params.requestId ?? "",
+  );
+  const Root = landmark ? "main" : "div";
+
+  if (controller.isSignedOut) {
+    return (
+      <ResourceAccessScreen
+        state="signed-out"
+        header={header}
+        landmark={landmark}
+        className={className}
+      />
+    );
+  }
+
+  if (controller.isUnavailable) {
+    return (
+      <ResourceAccessScreen
+        state="denied"
+        title={t("agentChat.accessRequest.unavailableTitle", {
+          defaultValue: "You can't review this request",
+        })}
+        description={t("agentChat.accessRequest.unavailableDescription", {
+          defaultValue:
+            "It may have been withdrawn, or this account can't manage access.",
+        })}
+        signedInEmail={session?.email ?? null}
+        onSwitchAccount={onSwitchAccount ?? (() => void signOut())}
+        header={header}
+        landmark={landmark}
+        className={className}
+      />
+    );
+  }
+
+  return (
+    <Root className={cn("flex min-h-0 flex-1 flex-col", className)}>
+      {header}
+      <div className="flex min-h-0 flex-1 items-center justify-center bg-background px-6 py-10">
+        {controller.review ? (
+          <ReviewPanel
+            review={controller.review}
+            decisions={controller.decisions}
+          />
+        ) : controller.isError ? (
+          <section className="flex w-full max-w-sm flex-col items-center text-center">
+            <p role="alert" className="text-sm text-muted-foreground">
+              {t("agentChat.accessRequest.loadFailed", {
+                defaultValue: "Couldn't load this request.",
+              })}
+            </p>
+            <ActionButton
+              emphasis="outline"
+              className="mt-4"
+              onPress={() => void controller.refetch()}
+            >
+              {t("agentChat.accessRequest.retry", { defaultValue: "Retry" })}
+            </ActionButton>
+          </section>
+        ) : (
+          <ReviewSkeleton />
+        )}
+      </div>
+    </Root>
+  );
+}
+
+function ReviewSkeleton() {
+  return (
+    <div aria-hidden="true" className="flex w-full max-w-md flex-col gap-6">
+      <Skeleton height={32} width="80%" />
+      <div className="flex items-center gap-3">
+        <Skeleton shape="circle" width={36} height={36} />
+        <div className="flex flex-1 flex-col gap-2">
+          <Skeleton height={14} width="40%" />
+          <Skeleton height={12} width="60%" />
+        </div>
+      </div>
+      <Skeleton height={14} width="50%" />
+      <div className="flex gap-2">
+        <Skeleton height={36} width={128} />
+        <Skeleton height={36} width={80} />
+        <Skeleton height={36} width={80} />
+      </div>
+    </div>
+  );
+}
+
+function ReviewPanel({
+  review,
+  decisions,
+}: {
+  review: AccessRequestReview;
+  decisions: ReturnType<typeof useAccessRequestReview>["decisions"];
+}) {
+  const t = useT();
+  const headingId = useId();
+  const headingRef = useRef<HTMLHeadingElement>(null);
+  const [role, setRole] = useState<AccessRequestRole>("viewer");
+  const name = review.requester.name?.trim() || review.requester.email;
+  const deciding = decisions.pendingId === review.id;
+  const roleLabel = (value: AccessRequestRole) =>
+    ({
+      viewer: t("agentChat.share.viewer", { defaultValue: "Viewer" }),
+      commenter: t("agentChat.share.commenter", { defaultValue: "Commenter" }),
+      editor: t("agentChat.share.editor", { defaultValue: "Editor" }),
+      admin: t("agentChat.share.admin", { defaultValue: "Admin" }),
+    })[value];
+
+  // A decision removes the buttons that held focus, so the outcome is read
+  // from the heading it moves to.
+  useEffect(() => {
+    headingRef.current?.focus({ preventScroll: true });
+  }, [review.state]);
+
+  // A failure shows as `decisions.error`, and a stale one reloads the request.
+  const decide = (run: () => Promise<void>) =>
+    void run().catch(() => undefined);
+
+  const heading =
+    review.state === "approved"
+      ? t("agentChat.accessRequest.approvedTitle", {
+          defaultValue: "Access allowed",
+        })
+      : review.state === "declined"
+        ? t("agentChat.accessRequest.declinedTitle", {
+            defaultValue: "Request declined",
+          })
+        : t("agentChat.accessRequest.title", {
+            name,
+            defaultValue: "{{name}} is asking for access",
+          });
+
+  const error = decisions.error;
+  const errorText = error
+    ? error.errorCode === "access_request_stale"
+      ? t("agentChat.accessRequest.stale", {
+          defaultValue: "Someone already handled this request, or it changed.",
+        })
+      : (error.message ??
+        t("agentChat.accessRequest.decisionFailed", {
+          defaultValue: "Couldn't save your decision. Try again.",
+        }))
+    : null;
+
+  return (
+    <section
+      aria-labelledby={headingId}
+      className="flex w-full max-w-md flex-col gap-6"
+      data-access-request-state={review.state}
+    >
+      <h1
+        ref={headingRef}
+        id={headingId}
+        tabIndex={-1}
+        className="break-words text-2xl font-semibold tracking-normal text-foreground outline-none"
+      >
+        {heading}
+      </h1>
+
+      <div className="flex items-center gap-3">
+        <Avatar name={name} size="default" className="shrink-0" />
+        <div className="min-w-0 flex-1">
+          <div className="truncate text-sm font-medium text-foreground">
+            {name}
+          </div>
+          {review.requester.name ? (
+            <div className="truncate text-sm text-muted-foreground">
+              {review.requester.email}
+            </div>
+          ) : null}
+        </div>
+        {review.state === "approved" && review.grantedRole ? (
+          <Status tone="neutral" size="compact">
+            {roleLabel(review.grantedRole)}
+          </Status>
+        ) : null}
+      </div>
+
+      <div className="text-sm text-muted-foreground">
+        <span>{review.resource.label}</span>{" "}
+        {review.resource.path ? (
+          <Link
+            to={review.resource.path}
+            className="font-medium text-foreground underline decoration-border underline-offset-4 hover:decoration-foreground"
+          >
+            {review.resource.title}
+          </Link>
+        ) : (
+          <span className="font-medium text-foreground">
+            {review.resource.title}
+          </span>
+        )}
+      </div>
+
+      {review.note ? (
+        <blockquote className="whitespace-pre-wrap break-words border-s-2 border-border ps-3 text-sm text-foreground">
+          {review.note}
+        </blockquote>
+      ) : null}
+
+      {review.state === "pending" ? (
+        <div className="flex flex-wrap items-center gap-2">
+          <Picker
+            mode="select"
+            options={ROLES.map((value) => ({
+              value,
+              label: roleLabel(value),
+            }))}
+            value={role}
+            onChange={(value) => {
+              if (value && (ROLES as readonly string[]).includes(value)) {
+                setRole(value as AccessRequestRole);
+              }
+            }}
+            disabled={deciding}
+            aria-label={t("agentChat.share.role", { defaultValue: "Role" })}
+            className="w-auto"
+          />
+          <ActionButton
+            pending={deciding}
+            disabled={deciding}
+            onPress={() => decide(() => decisions.approve(review, role))}
+          >
+            {t("agentChat.accessRequest.allow", { defaultValue: "Allow" })}
+          </ActionButton>
+          <ActionButton
+            emphasis="outline"
+            disabled={deciding}
+            onPress={() => decide(() => decisions.decline(review))}
+          >
+            {t("agentChat.accessRequest.decline", { defaultValue: "Decline" })}
+          </ActionButton>
+        </div>
+      ) : null}
+
+      {decisions.unemailed?.id === review.id ? (
+        <p role="status" className="text-sm text-muted-foreground">
+          {t("agentChat.accessRequest.emailFailed", {
+            name,
+            defaultValue: "{{name}} has access, but we couldn't email them.",
+          })}
+        </p>
+      ) : null}
+
+      {errorText ? (
+        <p role="alert" className="text-sm text-destructive">
+          {errorText}
+        </p>
+      ) : null}
+    </section>
+  );
+}

package/src/app/sharing/AccessRequestsSection.tsx

@@ -0,0 +1,163 @@
+import { useT } from "@agent-native/core/client/i18n";
+import {
+  useResourceAccessRequests,
+  type AccessRequestReview,
+} from "@agent-native/core/client/sharing/useAccessRequestReview";
+import {
+  ActionButton,
+  Avatar as DesignSystemAvatar,
+} from "@agent-native/toolkit/design-system";
+
+// Allow here grants Viewer; the request's own page offers every role.
+export function AccessRequestsSection({
+  resourceType,
+  resourceId,
+}: {
+  resourceType: string;
+  resourceId: string;
+}) {
+  const t = useT();
+  const { requests, hasMore, isError, refetch, decisions } =
+    useResourceAccessRequests({ resourceType, resourceId });
+  const error = decisions.error;
+  const unemailed = decisions.unemailed;
+  // A decision's outcome stays readable after its row is gone, even when the
+  // list's reload fails: a stale decision, or an email that didn't send.
+  if (!isError && !requests.length && !error && !unemailed) return null;
+  // A failure shows as `decisions.error`, and a stale one reloads the list.
+  const decide = (run: () => Promise<void>) =>
+    void run().catch(() => undefined);
+  return (
+    <div className="space-y-2">
+      {isError ? (
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <span role="alert">
+            {t("agentChat.share.accessRequestsLoadFailed", {
+              defaultValue: "Couldn't load access requests.",
+            })}
+          </span>
+          <ActionButton
+            emphasis="ghost"
+            size="compact"
+            onPress={() => void refetch()}
+          >
+            {t("agentChat.accessRequest.retry", { defaultValue: "Retry" })}
+          </ActionButton>
+        </div>
+      ) : (
+        <>
+          <div className="text-sm font-semibold">
+            {t("agentChat.share.accessRequests", {
+              defaultValue: "Access requests",
+            })}
+          </div>
+          {requests.length ? (
+            <ul className="m-0 flex list-none flex-col gap-1 p-0">
+              {requests.map((request) => (
+                <AccessRequestRow
+                  key={request.id}
+                  request={request}
+                  deciding={decisions.pendingId === request.id}
+                  onAllow={() =>
+                    decide(() => decisions.approve(request, "viewer"))
+                  }
+                  onDecline={() => decide(() => decisions.decline(request))}
+                />
+              ))}
+            </ul>
+          ) : null}
+          {hasMore ? (
+            <p className="text-xs text-muted-foreground">
+              {t("agentChat.share.accessRequestsNewest", {
+                count: requests.length,
+                defaultValue: "Showing the {{count}} newest requests.",
+              })}
+            </p>
+          ) : null}
+        </>
+      )}
+      {unemailed ? (
+        <p role="status" className="text-xs text-muted-foreground">
+          {t("agentChat.accessRequest.emailFailed", {
+            name: unemailed.requester.name?.trim() || unemailed.requester.email,
+            defaultValue: "{{name}} has access, but we couldn't email them.",
+          })}
+        </p>
+      ) : null}
+      {error ? (
+        <p role="alert" className="text-xs text-destructive">
+          {error.errorCode === "access_request_stale"
+            ? t("agentChat.accessRequest.stale", {
+                defaultValue:
+                  "Someone already handled this request, or it changed.",
+              })
+            : (error.message ??
+              t("agentChat.accessRequest.decisionFailed", {
+                defaultValue: "Couldn't save your decision. Try again.",
+              }))}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+function AccessRequestRow({
+  request,
+  deciding,
+  onAllow,
+  onDecline,
+}: {
+  request: AccessRequestReview;
+  deciding: boolean;
+  onAllow: () => void;
+  onDecline: () => void;
+}) {
+  const t = useT();
+  const name = request.requester.name?.trim() || request.requester.email;
+  return (
+    <li className="flex items-start gap-3 px-1 py-1.5 text-sm">
+      <DesignSystemAvatar
+        name={name}
+        size="compact"
+        className="mt-0.5 inline-flex h-7 w-7 shrink-0 text-[11px] font-semibold"
+      />
+      <div className="min-w-0 flex-1">
+        <div className="truncate">{name}</div>
+        {request.requester.name ? (
+          <div className="truncate text-xs text-muted-foreground">
+            {request.requester.email}
+          </div>
+        ) : null}
+        {request.note ? (
+          <div className="line-clamp-2 break-words text-xs text-muted-foreground">
+            {request.note}
+          </div>
+        ) : null}
+      </div>
+      <ActionButton
+        size="compact"
+        pending={deciding}
+        disabled={deciding}
+        onPress={onAllow}
+        aria-label={t("agentChat.share.allowRequestFrom", {
+          name,
+          defaultValue: "Allow {{name}}",
+        })}
+      >
+        {t("agentChat.accessRequest.allow", { defaultValue: "Allow" })}
+      </ActionButton>
+      <ActionButton
+        size="compact"
+        emphasis="ghost"
+        disabled={deciding}
+        onPress={onDecline}
+        aria-label={t("agentChat.share.declineRequestFrom", {
+          name,
+          defaultValue: "Decline {{name}}",
+        })}
+      >
+        {t("agentChat.accessRequest.decline", { defaultValue: "Decline" })}
+      </ActionButton>
+    </li>
+  );
+}

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

@@ -0,0 +1,235 @@
+// @vitest-environment happy-dom
+import { AgentNativeI18nProvider } from "@agent-native/core/client/i18n";
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createToolkitI18nCatalog } from "../i18n.js";
+import {
+  ResourceAccessScreen,
+  type ResourceAccessScreenProps,
+} from "./ResourceAccessScreen.js";
+
+const signInHref = vi.hoisted(() => vi.fn(() => "/_agent-native/sign-in"));
+
+vi.mock("@agent-native/core/client/sign-in-return", () => ({
+  buildSignInReturnHref: signInHref,
+}));
+
+const catalog = createToolkitI18nCatalog({ messages: {} });
+
+describe("ResourceAccessScreen", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  function render(props: ResourceAccessScreenProps, locale = "en-US") {
+    act(() => {
+      root.render(
+        <AgentNativeI18nProvider
+          catalog={catalog}
+          initialLocale={locale}
+          initialPreference={locale}
+          persistPreference={false}
+        >
+          <ResourceAccessScreen {...props} />
+        </AgentNativeI18nProvider>,
+      );
+    });
+  }
+
+  function buttons() {
+    return [...container.querySelectorAll("button")].map(
+      (button) => button.textContent,
+    );
+  }
+
+  it("says the viewer has no access, names their account, and focuses the heading", () => {
+    const onSwitchAccount = vi.fn();
+    render({
+      state: "denied",
+      signedInEmail: "outsider@example.test",
+      actions: <a href="/home">Go to my pages</a>,
+      onSwitchAccount,
+    });
+
+    const heading = container.querySelector("h1");
+    expect(heading?.textContent).toBe("You don't have access");
+    expect(document.activeElement).toBe(heading);
+    expect(
+      container.querySelector("section")?.getAttribute("aria-labelledby"),
+    ).toBe(heading?.id);
+    expect(container.textContent).toContain(
+      "You're signed in as outsider@example.test",
+    );
+    expect(container.querySelector('[role="status"], [aria-live]')).toBeNull();
+    expect(container.querySelector("main")).toBeNull();
+
+    const switchAccount = [...container.querySelectorAll("button")].find(
+      (button) => button.textContent === "Switch account",
+    );
+    act(() => switchAccount?.click());
+    expect(onSwitchAccount).toHaveBeenCalledTimes(1);
+  });
+
+  it("puts the app's actions before Switch account", () => {
+    render({
+      state: "denied",
+      actions: <button type="button">Go to my pages</button>,
+      onSwitchAccount: () => {},
+    });
+
+    expect(buttons()).toEqual(["Go to my pages", "Switch account"]);
+  });
+
+  it("uses the app's heading and description when given", () => {
+    render({
+      state: "missing",
+      title: "This page doesn't exist",
+      description: "Custom description",
+    });
+
+    expect(container.querySelector("h1")?.textContent).toBe(
+      "This page doesn't exist",
+    );
+    expect(container.textContent).toContain("Custom description");
+    expect(buttons()).toEqual([]);
+  });
+
+  it("sends a signed-out visitor to sign-in, which returns to the link", () => {
+    const assign = vi.fn();
+    vi.stubGlobal("location", { ...window.location, assign });
+    render({ state: "signed-out" });
+
+    expect(container.querySelector("h1")?.textContent).toBe(
+      "Sign in to continue",
+    );
+    const signIn = [...container.querySelectorAll("button")].find(
+      (button) => button.textContent === "Sign in",
+    );
+    act(() => signIn?.click());
+    expect(assign).toHaveBeenCalledWith("/_agent-native/sign-in");
+  });
+
+  it("can be the page's main landmark", () => {
+    render({ state: "trashed", landmark: true });
+
+    expect(container.querySelector("main")?.dataset.accessState).toBe(
+      "trashed",
+    );
+    expect(container.querySelector("h1")?.textContent).toBe(
+      "This is in the trash",
+    );
+  });
+
+  function typeInto(element: HTMLTextAreaElement, value: string) {
+    const setter = Object.getOwnPropertyDescriptor(
+      HTMLTextAreaElement.prototype,
+      "value",
+    )?.set;
+    act(() => {
+      setter?.call(element, value);
+      element.dispatchEvent(new Event("input", { bubbles: true }));
+    });
+  }
+
+  function bodyButton(label: string) {
+    return [...document.body.querySelectorAll("button")].find(
+      (button) => button.textContent === label,
+    );
+  }
+
+  it("offers Request access with an optional note, announced politely", async () => {
+    const onRequest = vi.fn(async () => undefined);
+    render({
+      state: "denied",
+      signedInEmail: "outsider@example.test",
+      request: { sent: false, onRequest },
+      onSwitchAccount: () => {},
+    });
+
+    expect(buttons()).toEqual(["Request access", "Switch account"]);
+    expect(container.querySelector('[role="status"]')?.textContent).toBe(
+      "Request access and the owner will be notified.",
+    );
+
+    act(() => bodyButton("Request access")?.click());
+    const note = document.body.querySelector("textarea");
+    expect(note).not.toBeNull();
+    typeInto(note!, "Need this for the launch review.");
+    await act(async () => bodyButton("Send request")?.click());
+
+    expect(onRequest).toHaveBeenCalledWith("Need this for the launch review.");
+    expect(document.body.querySelector("textarea")).toBeNull();
+    await vi.waitFor(() => {
+      expect(document.activeElement).toBe(container.querySelector("h1"));
+    });
+  });
+
+  it("says the request was sent and stops offering another", () => {
+    render({
+      state: "denied",
+      request: { sent: true, onRequest: vi.fn() },
+      onSwitchAccount: () => {},
+    });
+
+    expect(container.querySelector('[role="status"]')?.textContent).toBe(
+      "Request sent. The owner has been notified.",
+    );
+    expect(buttons()).toEqual(["Switch account"]);
+  });
+
+  it("explains a rate limit apart from other failures", async () => {
+    const request = {
+      sent: false,
+      onRequest: vi.fn(async () => {
+        throw new Error("failed");
+      }),
+      error: { errorCode: "access_request_rate_limited" },
+    };
+    render({ state: "denied", request });
+
+    act(() => bodyButton("Request access")?.click());
+    await act(async () => bodyButton("Send request")?.click());
+    expect(document.body.textContent).toContain(
+      "Too many requests right now. Try again later.",
+    );
+
+    render({ state: "denied", request: { ...request, error: null } });
+    await act(async () => bodyButton("Send request")?.click());
+    expect(document.body.textContent).toContain(
+      "Couldn't send your request. Try again.",
+    );
+  });
+
+  it("tells a signed-out visitor that signing in is how to ask", () => {
+    render({ state: "signed-out", acceptsRequests: true });
+
+    expect(container.textContent).toContain("Sign in to request access.");
+  });
+
+  it("translates its own strings", async () => {
+    render({ state: "denied", signedInEmail: "a@example.test" }, "de-DE");
+
+    await vi.waitFor(() => {
+      expect(container.querySelector("h1")?.textContent).toBe(
+        "Du hast keinen Zugriff",
+      );
+    });
+    expect(container.textContent).toContain(
+      "Du bist als a@example.test angemeldet",
+    );
+  });
+});