@stigmer/react 3.1.7 → 3.1.9

package/src/sharing/useShareAgent.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+import { useCallback, useState, type ReactNode } from "react";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+import type { DetailAction } from "../resource-detail/types.js";
+import { ShareAgentDialog } from "./ShareAgentDialog.js";
+
+/** Arguments for {@link useShareAgent}. */
+export interface UseShareAgentArgs {
+  /**
+   * The agent whose sharing is managed, or `null` while it is still
+   * loading. When `null`, {@link UseShareAgentReturn.action} is `null`
+   * and the dialog renders nothing — safe to call before the resource
+   * is ready.
+   */
+  readonly agent: Agent | null;
+  /**
+   * Builds the absolute public chat URL for the shared agent. The host
+   * application owns URL construction (its configured public origin may
+   * differ from the rendering origin — e.g. the desktop app). When
+   * omitted, the dialog falls back to the relative `/chat/<org>/<slug>`.
+   */
+  readonly buildShareUrl?: (org: string, slug: string) => string;
+  /**
+   * Called after any sharing change is persisted. Hosts typically pass
+   * the agent data hook's `refetch`.
+   */
+  readonly onSharingChanged?: () => void;
+  /** Menu-item label. @default "Share" */
+  readonly label?: string;
+}
+
+/** Return value of {@link useShareAgent}. */
+export interface UseShareAgentReturn {
+  /**
+   * A ready-to-spread {@link DetailAction} for a kebab/overflow menu, or
+   * `null` when the agent is unavailable or the user lacks `can_edit`.
+   * Lives in the `"sharing"` group, beside "Manage access".
+   */
+  readonly action: DetailAction | null;
+  /** The {@link ShareAgentDialog} node — render it once in the host tree. */
+  readonly dialog: ReactNode;
+  /** Imperatively open the dialog. */
+  readonly open: () => void;
+  /** Whether the dialog is currently open. */
+  readonly isOpen: boolean;
+}
+
+/**
+ * Wires the Share dialog to a kebab/overflow menu — the same trigger
+ * shape as {@link useManageAccess}, its conceptual sibling: Manage access
+ * governs who can *read* the blueprint; Share governs who can *chat* with
+ * the running agent (billed to the owning org).
+ *
+ * Owns the open-state and the `can_edit` gate — the same permission the
+ * AgentShare create/apply handlers enforce on the referenced agent, so
+ * the action never appears to a user whose changes would be rejected.
+ * Returns a `null` action while the agent is loading or the user cannot
+ * edit, so the host can unconditionally fold `action` into its actions
+ * array.
+ *
+ * @example
+ * ```tsx
+ * const share = useShareAgent({
+ *   agent,
+ *   buildShareUrl: (org, slug) => `${appOrigin}/chat/${org}/${slug}`,
+ *   onSharingChanged: refetch,
+ * });
+ * // ...
+ * <ResourceDetailShell actions={share.action ? [...actions, share.action] : actions} ... />
+ * {share.dialog}
+ * ```
+ */
+export function useShareAgent({
+  agent,
+  buildShareUrl,
+  onSharingChanged,
+  label = "Share",
+}: UseShareAgentArgs): UseShareAgentReturn {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const agentId = agent?.metadata?.id ?? null;
+  const { allowed: canEdit } = useCheckPermission(
+    agentId ? { kind: "agent", id: agentId } : null,
+    "can_edit",
+  );
+
+  const open = useCallback(() => setIsOpen(true), []);
+
+  const action: DetailAction | null =
+    agent && canEdit
+      ? { id: "share", label, group: "sharing", onAction: open }
+      : null;
+
+  const dialog = agent ? (
+    <ShareAgentDialog
+      open={isOpen}
+      onOpenChange={setIsOpen}
+      agent={agent}
+      buildShareUrl={buildShareUrl}
+      onSharingChanged={onSharingChanged}
+    />
+  ) : null;
+
+  return { action, dialog, open, isOpen };
+}

package/src/sharing/useShareToolReadiness.ts

@@ -0,0 +1,131 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { useStigmer } from "../hooks.js";
+import { useDeploymentMode } from "../deployment-mode.js";
+import type { AgentShareDraft } from "./useSaveAgentShare.js";
+
+/**
+ * Readiness of a share's tool credentials for visitor executions.
+ *
+ * - `na` — nothing to check: the agent uses no MCP tools, sharing is
+ *   off, the audience is org (bindings are public-audience only), or
+ *   the deployment cannot serve guest chat (local mode).
+ * - `needs-credentials` — the agent uses MCP tools but the share has no
+ *   environments bound: visitors' tool calls will fail until the owner
+ *   binds credentials.
+ * - `checking` — lookups in flight.
+ * - `ready` — every environment bound to the share is shared with the
+ *   organization.
+ * - `blocked` — one or more bound environments are private; their
+ *   `org/slug` references are listed for the hint copy.
+ */
+export type ShareToolReadiness =
+  | { readonly status: "na" }
+  | { readonly status: "needs-credentials" }
+  | { readonly status: "checking" }
+  | { readonly status: "ready" }
+  | { readonly status: "blocked"; readonly privateEnvironments: readonly string[] };
+
+const NA: ShareToolReadiness = { status: "na" };
+const NEEDS_CREDENTIALS: ShareToolReadiness = { status: "needs-credentials" };
+
+/**
+ * Data hook that checks whether a tool-using shared agent's credentials
+ * will work for visitors — i.e. whether the share binds environments
+ * (`environment_refs`) and each one is shared with the organization
+ * (`visibility_org`).
+ *
+ * Guest executions receive credentials exclusively from the share's own
+ * `environment_refs`, resolved through the org-shared environment seam
+ * (decision 011 — the agent's default instance stays pristine and is
+ * never consulted). So a tool-using agent with an empty binding list is
+ * *guaranteed* broken for visitors, and this hook says so explicitly
+ * (`needs-credentials`) instead of staying silent — the gap that made
+ * session 12's misconfiguration invisible until a visitor's first
+ * message failed.
+ *
+ * The check runs only when the share is enabled with a public audience
+ * (org-audience shares reject bindings at the proto boundary), the
+ * deployment is cloud (local mode has no guest runtime or secret
+ * gating), and the agent declares MCP server usages. All lookups run as
+ * the owner viewing the dialog, who can read the bound environments.
+ */
+export function useShareToolReadiness(
+  agent: Agent,
+  draft: AgentShareDraft,
+): ShareToolReadiness {
+  const stigmer = useStigmer();
+  const deploymentMode = useDeploymentMode();
+  const [checked, setChecked] = useState<ShareToolReadiness>(NA);
+
+  const hasMcpTools = (agent.spec?.mcpServerUsages?.length ?? 0) > 0;
+  const applicable =
+    draft.enabled &&
+    draft.audience === "public" &&
+    deploymentMode === "cloud" &&
+    hasMcpTools;
+
+  // Stable key for the effect: the visibility lookups depend only on
+  // which environments are bound, not on the array's identity.
+  const refsKey = useMemo(
+    () => draft.environmentRefs.map((ref) => `${ref.org}/${ref.slug}`).join(","),
+    [draft.environmentRefs],
+  );
+
+  const shouldFetch = applicable && refsKey !== "";
+
+  useEffect(() => {
+    if (!shouldFetch) {
+      setChecked(NA);
+      return;
+    }
+
+    let cancelled = false;
+    setChecked({ status: "checking" });
+
+    (async (): Promise<ShareToolReadiness> => {
+      const privateRefs: string[] = [];
+      for (const ref of refsKey.split(",")) {
+        const [org, slug] = ref.split("/");
+        try {
+          const env = await stigmer.environment.getByReference({ org, slug });
+          if (
+            env.metadata?.visibility !== ApiResourceVisibility.visibility_org
+          ) {
+            privateRefs.push(ref);
+          }
+        } catch {
+          // Unreadable ref (deleted, foreign): the runtime's merge will
+          // skip it for visitors too — surface it as blocking.
+          privateRefs.push(ref);
+        }
+      }
+
+      return privateRefs.length === 0
+        ? { status: "ready" }
+        : { status: "blocked", privateEnvironments: privateRefs };
+    })().then(
+      (result) => {
+        if (!cancelled) setChecked(result);
+      },
+      () => {
+        // The hint is best-effort pre-flight advice — a failed check must
+        // never block the dialog. The runtime error path still diagnoses.
+        if (!cancelled) setChecked(NA);
+      },
+    );
+
+    return () => {
+      cancelled = true;
+    };
+  }, [shouldFetch, refsKey, stigmer]);
+
+  if (!applicable) return NA;
+  // Zero bindings needs no lookup: a tool-using agent without bound
+  // credentials is broken for visitors by construction.
+  if (refsKey === "") return NEEDS_CREDENTIALS;
+  return checked;
+}

package/src/sharing/useSharedAgentProfile.ts

@@ -0,0 +1,132 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import {
+  GetSharedProfileRequestSchema,
+  type SharedAgentProfile,
+} from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/io_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+import type { SharingAudience } from "./useSaveAgentShare.js";
+
+/** Options for {@link useSharedAgentProfile}. */
+export interface UseSharedAgentProfileOptions {
+  /**
+   * Which resolution path to use.
+   *
+   * - `"public"` (default) — the anonymous `getSharedProfile` RPC. An
+   *   org-audience share answers NOT_FOUND here by design.
+   * - `"org"` — the authenticated `getSharedProfileForMember` RPC, which
+   *   resolves org-audience shares for signed-in members of the owning
+   *   organization (and public shares too). Requires a `StigmerProvider`
+   *   whose client carries the member's token.
+   */
+  readonly audience?: SharingAudience;
+
+  /**
+   * Share-link token from the URL's `?k=` parameter (public path only).
+   *
+   * Required when the share link has been locked with a rotatable token;
+   * harmless on plain links. On a locked link a missing or rotated-away
+   * token resolves to `profile === null`, indistinguishable from an
+   * agent that does not exist.
+   */
+  readonly linkToken?: string;
+}
+
+/** Return value of {@link useSharedAgentProfile}. */
+export interface UseSharedAgentProfileReturn {
+  /**
+   * The shared agent's public profile, or `null` while loading, on
+   * error, or when the agent is not shared.
+   */
+  readonly profile: SharedAgentProfile | null;
+  /** `true` while the initial fetch or a refetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the profile from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a shared agent's public profile by the org and
+ * slug from the share URL (the share's slug — it defaults to the
+ * agent's, so existing links resolve unchanged).
+ *
+ * By default this hook calls the `getSharedProfile` endpoint, which is
+ * **public** — it requires no authentication. The server returns a
+ * trimmed projection safe for anonymous visitors: name, description,
+ * icon, and the default instance id needed to start a session
+ * (an identifier, not a capability — session creation still requires
+ * an authorized token, e.g. a guest token from `createGuestAuth`).
+ * With `{ audience: "org" }` it calls the authenticated
+ * `getSharedProfileForMember` endpoint instead, which resolves
+ * org-members-only shares for a signed-in member.
+ *
+ * **Not-shared handling:** the server answers NOT_FOUND for "this
+ * agent does not exist", "this agent is not shared", and (on the
+ * member path) "you are not a member of this organization" — all
+ * indistinguishable by design so a share URL leaks nothing. The hook
+ * maps that to `profile === null` without raising an error, matching
+ * `useAgent`'s not-found convention:
+ * `profile === null && !isLoading && !error` means unavailable.
+ *
+ * Pass `null` for either `org` or `slug` to skip fetching (stable
+ * no-op) — useful while route params are still resolving.
+ *
+ * **Note**: Although authentication is not required by the server,
+ * the hook still requires a `StigmerProvider` ancestor because it
+ * needs the transport configuration (API base URL) to make the
+ * request.
+ *
+ * @example
+ * ```tsx
+ * const { profile, isLoading, error } = useSharedAgentProfile(org, slug);
+ *
+ * if (isLoading) return <Spinner />;
+ * if (error) return <ErrorCard error={error} />;
+ * if (!profile) return <AgentUnavailable />;
+ *
+ * return <h1>{profile.name}</h1>;
+ * ```
+ */
+export function useSharedAgentProfile(
+  org: string | null,
+  slug: string | null,
+  options?: UseSharedAgentProfileOptions,
+): UseSharedAgentProfileReturn {
+  const stigmer = useStigmer();
+  const audience = options?.audience ?? "public";
+  const linkToken = options?.linkToken ?? "";
+
+  const fetchFn =
+    org && slug
+      ? async () => {
+          try {
+            // The member path is tokenless by contract: org-audience access
+            // is gated by live membership, and token-locked public shares
+            // deliberately refuse there (see getSharedProfileForMember).
+            return audience === "org"
+              ? await stigmer.agentShare.getSharedProfileForMember({ org, slug })
+              : await stigmer.agentShare.getSharedProfile(
+                  create(GetSharedProfileRequestSchema, { org, slug, linkToken }),
+                );
+          } catch (err) {
+            if (isNotFound(err)) return null;
+            throw err;
+          }
+        }
+      : null;
+
+  const { data: profile, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [org, slug, audience, linkToken, stigmer],
+    null as SharedAgentProfile | null,
+  );
+
+  return { profile, isLoading, isRefetching, error, refetch };
+}

package/src/switch/Switch.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link Switch}. */
+export interface SwitchProps {
+  /** Whether the switch is on. */
+  readonly checked: boolean;
+  /** Called with the next value when the user toggles the switch. */
+  readonly onCheckedChange: (checked: boolean) => void;
+  /** When `true`, the switch is shown but non-interactive. */
+  readonly disabled?: boolean;
+  /**
+   * Accessible name. Required unless `aria-labelledby` points at a
+   * visible label element.
+   */
+  readonly "aria-label"?: string;
+  /** ID of the element that labels this switch. */
+  readonly "aria-labelledby"?: string;
+  /** Element ID, for association with an external `<label htmlFor>`. */
+  readonly id?: string;
+  /** Additional CSS classes for the root button. */
+  readonly className?: string;
+}
+
+/**
+ * Accessible on/off toggle following the WAI-ARIA Switch pattern.
+ *
+ * Built on a native `<button role="switch">` so Space/Enter activation,
+ * focus, and disabled semantics come from the platform. `aria-checked`
+ * reflects the state for assistive technology.
+ *
+ * Use a switch only for instant binary state changes that take effect
+ * immediately (e.g. enabling sharing) — not for choices that need a
+ * separate save step (use radios or a select for those).
+ *
+ * The visible track is compact; an invisible expanded hit area keeps the
+ * touch target at ~44px without disturbing layout. All visual properties
+ * flow through `--stgm-*` design tokens, and the thumb transition is
+ * suppressed under `prefers-reduced-motion`.
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   checked={sharing.enabled}
+ *   onCheckedChange={(next) => save({ ...sharing, enabled: next })}
+ *   aria-label="Enable sharing"
+ * />
+ * ```
+ */
+export function Switch({
+  checked,
+  onCheckedChange,
+  disabled,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledby,
+  id,
+  className,
+}: SwitchProps) {
+  return (
+    <button
+      type="button"
+      role="switch"
+      id={id}
+      aria-checked={checked}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledby}
+      disabled={disabled}
+      onClick={() => onCheckedChange(!checked)}
+      className={cn(
+        // Track. `relative` anchors both the thumb and the expanded hit area.
+        // Off state uses the form-control token (`--stgm-input`), NOT
+        // `bg-muted`: muted matches the popover surface in dark presets, which
+        // made the track invisible inside dialogs. Both track fills are
+        // registered as surface pairs in the theme contrast contract
+        // (@stigmer/theme contract/pairs.ts), so every preset is audited.
+        "relative inline-flex h-5 w-9 shrink-0 items-center rounded-full transition-colors",
+        "motion-reduce:transition-none",
+        checked ? "bg-primary" : "bg-input",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:pointer-events-none disabled:opacity-50",
+        // Expanded invisible hit area (~44px tall) for touch targets.
+        "after:absolute after:-inset-3 after:content-['']",
+        className,
+      )}
+    >
+      <span
+        aria-hidden="true"
+        className={cn(
+          "pointer-events-none block size-4 rounded-full bg-background shadow-sm transition-transform",
+          "motion-reduce:transition-none",
+          checked ? "translate-x-[18px]" : "translate-x-0.5",
+        )}
+      />
+    </button>
+  );
+}

package/src/switch/__tests__/Switch.test.tsx

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { Switch } from "../Switch";
+
+afterEach(cleanup);
+
+describe("Switch", () => {
+  it("renders as role=switch with aria-checked reflecting state", () => {
+    const { rerender } = render(
+      <Switch checked={false} onCheckedChange={() => {}} aria-label="Enable sharing" />,
+    );
+
+    const el = screen.getByRole("switch", { name: "Enable sharing" });
+    expect(el.getAttribute("aria-checked")).toBe("false");
+
+    rerender(
+      <Switch checked onCheckedChange={() => {}} aria-label="Enable sharing" />,
+    );
+    expect(el.getAttribute("aria-checked")).toBe("true");
+  });
+
+  it("calls onCheckedChange with the next value on click", () => {
+    const onCheckedChange = vi.fn();
+    render(
+      <Switch checked={false} onCheckedChange={onCheckedChange} aria-label="Enable sharing" />,
+    );
+
+    screen.getByRole("switch").click();
+    expect(onCheckedChange).toHaveBeenCalledTimes(1);
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+  });
+
+  it("calls onCheckedChange(false) when toggling off", () => {
+    const onCheckedChange = vi.fn();
+    render(
+      <Switch checked onCheckedChange={onCheckedChange} aria-label="Enable sharing" />,
+    );
+
+    screen.getByRole("switch").click();
+    expect(onCheckedChange).toHaveBeenCalledWith(false);
+  });
+
+  it("is a native button, so Space/Enter activation comes from the platform", () => {
+    render(
+      <Switch checked={false} onCheckedChange={() => {}} aria-label="Enable sharing" />,
+    );
+
+    const el = screen.getByRole("switch");
+    // happy-dom does not synthesize click from keydown; assert the native
+    // button element carries the behavior instead of re-implementing it.
+    expect(el.tagName).toBe("BUTTON");
+    expect(el.getAttribute("type")).toBe("button");
+  });
+
+  it("does not fire when disabled", () => {
+    const onCheckedChange = vi.fn();
+    render(
+      <Switch
+        checked={false}
+        onCheckedChange={onCheckedChange}
+        disabled
+        aria-label="Enable sharing"
+      />,
+    );
+
+    const el = screen.getByRole("switch") as HTMLButtonElement;
+    expect(el.disabled).toBe(true);
+    el.click();
+    expect(onCheckedChange).not.toHaveBeenCalled();
+  });
+
+  it("fills the track with the contract-audited surface tokens", () => {
+    // bg-input (off) / bg-primary (on) are registered as surface pairs in
+    // the @stigmer/theme contrast contract — bg-muted is NOT valid here (it
+    // matches the popover surface in dark presets, making the track
+    // invisible inside dialogs).
+    const { rerender } = render(
+      <Switch checked={false} onCheckedChange={() => {}} aria-label="Enable sharing" />,
+    );
+
+    const el = screen.getByRole("switch");
+    expect(el.className).toContain("bg-input");
+    expect(el.className).not.toContain("bg-muted");
+
+    rerender(
+      <Switch checked onCheckedChange={() => {}} aria-label="Enable sharing" />,
+    );
+    expect(el.className).toContain("bg-primary");
+  });
+
+  it("supports aria-labelledby for external labels", () => {
+    render(
+      <>
+        <span id="share-label">Enable sharing</span>
+        <Switch
+          checked={false}
+          onCheckedChange={() => {}}
+          aria-labelledby="share-label"
+        />
+      </>,
+    );
+
+    expect(
+      screen.getByRole("switch", { name: "Enable sharing" }),
+    ).toBeTruthy();
+  });
+});

package/src/switch/index.ts

@@ -0,0 +1,2 @@
+export { Switch } from "./Switch.js";
+export type { SwitchProps } from "./Switch.js";