@opengeni/react 4.0.2 → 5.0.4-canary.0

package/src/connect-setup.tsx

@@ -0,0 +1,260 @@
+import { useState, type FormEvent } from "react";
+import type { ConnectAttempt, ConnectController } from "@opengeni/connect";
+import { useConnect } from "./connect";
+
+const setupStatus: Record<ConnectAttempt["state"], string> = {
+  ready: "Ready to connect",
+  requires_user_action: "Authorize your account",
+  credential_input: "Enter connection details",
+  provider_wait: "Waiting for authorization",
+  account_selection: "Choose an account",
+  resource_selection: "Choose resources",
+  preview: "Review available operations",
+  installing: "Installing selected operations…",
+  connected_but_incomplete: "Account connected — finish setup",
+  complete: "Connection ready",
+  cancelled: "Setup cancelled",
+  expired: "Setup expired",
+  failed: "Setup could not finish",
+  uncertain: "Setup outcome needs checking",
+};
+
+function deviceVerificationUrl(action: ConnectAttempt["nextAction"]): string | null {
+  if (action.type !== "wait" || !action.verificationUrl) return null;
+  try {
+    const url = new URL(action.verificationUrl);
+    return url.protocol === "https:" && !url.username && !url.password
+      ? action.verificationUrl
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export type ConnectSetupProps = {
+  controller: ConnectController;
+  /** Called synchronously in the click handler so a host can open a popup. */
+  onAuthorize: (attempt: ConnectAttempt) => void | Promise<unknown>;
+  /** Host pagination must retain selections across pages and submit the final set. */
+  onBrowseResources?: (attempt: ConnectAttempt) => void | Promise<unknown>;
+  className?: string;
+};
+
+/** Unstyled setup surface. No provider secrets enter React state. Host owns
+ * chooser, controller lifetime, navigation and recovery after full redirect. */
+export function ConnectSetup(props: ConnectSetupProps) {
+  // Attempt IDs/revisions are not a substitute for actor scope. A host can
+  // recover the same attempt through a replacement controller; never preserve
+  // a previous actor's unsent credential DOM or local errors across that swap.
+  const [scope, setScope] = useState(props.controller);
+  const [generation, setGeneration] = useState(0);
+  if (scope !== props.controller) {
+    setScope(props.controller);
+    setGeneration(generation + 1);
+  }
+  return <ScopedSetup key={generation} {...props} />;
+}
+
+function ScopedSetup({ controller, onAuthorize, onBrowseResources, className }: ConnectSetupProps) {
+  const view = useConnect(controller);
+  const [localError, setLocalError] = useState(false);
+  const invoke = (operation: () => unknown | Promise<unknown>) => {
+    setLocalError(false);
+    try {
+      void Promise.resolve(operation()).catch(() => setLocalError(true));
+    } catch {
+      setLocalError(true);
+    }
+  };
+  const attempt = view.attempt;
+  if (!attempt)
+    return (
+      <section className={className} aria-label="Connection setup">
+        <p role="status">Choose a connection to begin.</p>
+      </section>
+    );
+  const action = attempt.nextAction;
+  const verificationUrl = deviceVerificationUrl(action);
+  const terminal = ["complete", "cancelled", "expired"].includes(attempt.state);
+  const submit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const form = event.currentTarget;
+    const data = new FormData(form);
+    if (view.busy) return;
+    const key = crypto.randomUUID();
+    if (action.type === "credentials") {
+      const values = Object.fromEntries(
+        action.fields.map((field, i) => [field.name, String(data.get(`field-${i}`) ?? "")]),
+      );
+      // Clear the DOM before awaiting remote work; controller never retains values.
+      form.reset();
+      invoke(() => view.advance({ type: "credentials", values }, key));
+    } else if (action.type === "select_account") {
+      const accountId = String(data.get("account") ?? "");
+      if (
+        action.accounts.some((account) => account.id === accountId && account.status !== "disabled")
+      )
+        invoke(() => view.advance({ type: "account", accountId }, key));
+    } else if (action.type === "select_resources") {
+      if (action.cursor) return;
+      const resourceIds = data.getAll("resource").map(String);
+      invoke(() => view.advance({ type: "resources", resourceIds }, key));
+    } else if (action.type === "preview") {
+      const operationIds = data.getAll("operation").map(String);
+      invoke(() =>
+        view.advance(
+          {
+            type: "install",
+            previewId: action.previewId,
+            contentHash: action.contentHash,
+            operationIds,
+          },
+          key,
+        ),
+      );
+    }
+  };
+  return (
+    <section className={className} aria-label="Connection setup" aria-busy={view.busy}>
+      <p>Ownership: {attempt.ownership === "personal" ? "Personal" : "Workspace"}</p>
+      <p role="status">{setupStatus[attempt.state]}</p>
+      {attempt.account && <p>Account: {attempt.account.label}</p>}
+      {(localError || view.error || attempt.error) && (
+        <p role="alert">
+          {attempt.error?.code === "source_changed"
+            ? "The integration source changed. Review the new operations before installing."
+            : "Connection setup could not continue. Refresh its status before trying again."}
+        </p>
+      )}
+      {!terminal && (
+        <form key={`${attempt.id}:${attempt.revision}`} onSubmit={submit} autoComplete="off">
+          <fieldset disabled={view.busy}>
+            <legend>Connection details</legend>
+            {attempt.state === "connected_but_incomplete" && action.type === "none" && (
+              <button
+                type="button"
+                onClick={() => invoke(() => view.advance({ type: "retry" }, crypto.randomUUID()))}
+              >
+                Review integration operations
+              </button>
+            )}
+            {action.type === "credentials" &&
+              action.fields.map((field, i) => (
+                <label key={field.name}>
+                  {field.label}
+                  {field.options ? (
+                    <select name={`field-${i}`} required={field.required} defaultValue="">
+                      <option value="">
+                        {field.required ? "Choose an option" : "No account (public service)"}
+                      </option>
+                      {field.options.map((option) => (
+                        <option key={option.value} value={option.value}>
+                          {option.label}
+                        </option>
+                      ))}
+                    </select>
+                  ) : (
+                    <input
+                      name={`field-${i}`}
+                      type={field.secret ? "password" : "text"}
+                      required={field.required}
+                      autoComplete="off"
+                    />
+                  )}
+                </label>
+              ))}
+            {action.type === "select_account" && (
+              <label>
+                Account
+                <select name="account" required defaultValue="">
+                  <option value="" disabled>
+                    Choose an account
+                  </option>
+                  {action.accounts.map((account) => (
+                    <option
+                      key={account.id}
+                      value={account.id}
+                      disabled={account.status === "disabled"}
+                    >
+                      {account.label} — {account.id} ({account.ownership})
+                    </option>
+                  ))}
+                </select>
+              </label>
+            )}
+            {action.type === "select_resources" &&
+              action.resources.map((resource) => (
+                <label key={resource.id}>
+                  <input type="checkbox" name="resource" value={resource.id} />
+                  {resource.label} ({resource.kind})
+                </label>
+              ))}
+            {action.type === "select_resources" && action.cursor && (
+              <>
+                <p>More resources are available. Review all pages before submitting a selection.</p>
+                {onBrowseResources && (
+                  <button
+                    type="button"
+                    onClick={() => invoke(() => onBrowseResources(structuredClone(attempt)))}
+                  >
+                    Browse all resources
+                  </button>
+                )}
+              </>
+            )}
+            {action.type === "preview" && (
+              <>
+                <p>Select the operations to install.</p>
+                {action.operations.map((operation) => (
+                  <label key={operation.id}>
+                    <input type="checkbox" name="operation" value={operation.id} />
+                    {operation.label} ({operation.kind})
+                  </label>
+                ))}
+              </>
+            )}
+            {["credentials", "select_account", "select_resources", "preview"].includes(
+              action.type,
+            ) && (
+              <button
+                type="submit"
+                disabled={action.type === "select_resources" && Boolean(action.cursor)}
+              >
+                {action.type === "preview" ? "Install selected operations" : "Continue"}
+              </button>
+            )}
+            {action.type === "authorize" && (
+              <button
+                type="button"
+                onClick={() => invoke(() => onAuthorize(structuredClone(attempt)))}
+              >
+                Authorize connection
+              </button>
+            )}
+            {action.type === "wait" && (
+              <>
+                {action.userCode && (
+                  <p>
+                    Verification code: <code>{action.userCode}</code>
+                  </p>
+                )}
+                <p>Complete provider authorization, then check the connection status.</p>
+                {verificationUrl && (
+                  <a href={verificationUrl} target="_blank" rel="noopener noreferrer">
+                    Open provider verification page (new tab)
+                  </a>
+                )}
+              </>
+            )}
+            <button type="button" onClick={() => invoke(() => view.refresh())}>
+              Check status
+            </button>
+            <button type="button" onClick={() => invoke(() => view.cancel(crypto.randomUUID()))}>
+              Cancel setup
+            </button>
+          </fieldset>
+        </form>
+      )}
+    </section>
+  );
+}

package/src/connect.ts

@@ -0,0 +1,48 @@
+// Optional, unstyled React adapter over the shared headless controller.
+// The host owns controller lifetime; unmounting one observer does not cancel an
+// attempt another observer is displaying or a durable backend operation.
+import { useMemo, useSyncExternalStore } from "react";
+import type { ConnectController } from "@opengeni/connect";
+export { ConnectSetup, type ConnectSetupProps } from "./connect-setup";
+export { ConnectChooser, type ConnectChooserProps } from "./connect-chooser";
+export { ConnectAccounts, type ConnectAccountsProps } from "./connect-accounts";
+export { ConnectPanel, type ConnectPanelProps } from "./connect-panel";
+export { DeviceAuthorization, type DeviceAuthorizationProps } from "./device-authorization";
+export {
+  IdentityLinkConsent,
+  type IdentityLinkClient,
+  type IdentityLinkConsentProps,
+} from "./identity-link-consent";
+export { IdentityLinkAccounts, type IdentityLinkAccountsClient } from "./identity-link-accounts";
+
+export type { ConnectSnapshot } from "@opengeni/connect";
+export type {
+  ConnectAccount,
+  ConnectAdvance,
+  ConnectAttempt,
+  ConnectNextAction,
+  ConnectOwnership,
+  ConnectProvider,
+  ConnectResource,
+  ConnectTransport,
+} from "@opengeni/connect";
+
+export function useConnect(controller: ConnectController) {
+  const snapshot = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+  const actions = useMemo(
+    () => ({
+      begin: controller.begin.bind(controller),
+      recover: controller.recover.bind(controller),
+      refresh: controller.refresh.bind(controller),
+      waitForAction: controller.waitForAction.bind(controller),
+      advance: controller.advance.bind(controller),
+      cancel: controller.cancel.bind(controller),
+    }),
+    [controller],
+  );
+  return useMemo(() => ({ ...snapshot, ...actions }), [snapshot, actions]);
+}

package/src/device-authorization.tsx

@@ -0,0 +1,90 @@
+import { useEffect, useRef, useState } from "react";
+import { copyTextToClipboard } from "./clipboard";
+
+export type DeviceAuthorizationProps = {
+  userCode: string;
+  verificationUri: string;
+  providerLabel?: string;
+  description?: string;
+  className?: string;
+  codeAttributes?: Record<`data-${string}`, string>;
+  loadClipboard?: () => Promise<{ copyTextToClipboard(text: string): Promise<boolean> }>;
+  onCopyResult?: (copied: boolean) => void;
+};
+
+/** Optional presentation for the existing model-account device APIs. It neither
+ * owns provider state nor assumes that opening a verification page completed it. */
+export function DeviceAuthorization(props: DeviceAuthorizationProps) {
+  const [copied, setCopied] = useState(false);
+  const [copyError, setCopyError] = useState(false);
+  const generation = useRef(0);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    generation.current++;
+    setCopied(false);
+    setCopyError(false);
+    return () => {
+      // This is a live async-operation counter, not a captured DOM ref.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      generation.current++;
+      if (timer.current) clearTimeout(timer.current);
+    };
+  }, [props.userCode]);
+  async function copy() {
+    const revision = ++generation.current;
+    if (timer.current) clearTimeout(timer.current);
+    setCopied(false);
+    setCopyError(false);
+    try {
+      const clipboard = props.loadClipboard ? await props.loadClipboard() : { copyTextToClipboard };
+      if (revision !== generation.current) return;
+      const success = await clipboard.copyTextToClipboard(props.userCode);
+      if (revision !== generation.current) return;
+      setCopied(success);
+      setCopyError(!success);
+      props.onCopyResult?.(success);
+      if (success)
+        timer.current = setTimeout(() => {
+          if (revision === generation.current) setCopied(false);
+        }, 1600);
+    } catch {
+      if (revision !== generation.current) return;
+      setCopyError(true);
+      props.onCopyResult?.(false);
+    }
+  }
+  let href: string | undefined;
+  try {
+    const url = new URL(props.verificationUri);
+    if (["https:", "http:"].includes(url.protocol) && !url.username && !url.password)
+      href = props.verificationUri;
+  } catch {
+    /* A malformed provider URL must never become an executable link. */
+  }
+  return (
+    <section className={`og-connect ${props.className ?? ""}`} aria-label="Device authorization">
+      <p>{props.description ?? `Enter this code at ${props.providerLabel ?? "the provider"}.`}</p>
+      <div style={{ display: "flex", flexWrap: "wrap", gap: "0.5rem", alignItems: "center" }}>
+        <code {...props.codeAttributes} style={{ overflowWrap: "anywhere" }}>
+          {props.userCode}
+        </code>
+        <button
+          type="button"
+          aria-label={copied ? "Code copied" : "Copy code"}
+          onClick={() => void copy()}
+        >
+          {copied ? "Copied" : "Copy code"}
+        </button>
+        {href ? (
+          <a href={href} target="_blank" rel="noopener noreferrer">
+            Open {props.providerLabel ?? "auth page"}
+          </a>
+        ) : (
+          <span role="alert">Authorization address unavailable.</span>
+        )}
+      </div>
+      {copyError ? <p role="alert">Couldn't copy the code. Copy it manually instead.</p> : null}
+      <p role="status">Waiting for authorization…</p>
+    </section>
+  );
+}

package/src/hooks/use-workspace-capture.ts

@@ -194,8 +194,9 @@ export function useWorkspaceCapture(
           return;
         }
         setDegradedReason(null);
-        // Resolve the changed-file count immediately from the response's stats — the
-        // default-tab signal must not wait on a >2MB manifest-URL hop.
+        // Expose metadata while a large signed manifest downloads. Consumers
+        // must distinguish this pending count from a resolved capture; zero
+        // working-tree files can still have committed-only branch changes.
         setFileCount(res.stats.fileCount);
         // Exactly one of manifest / manifestUrl is non-null (M2 contract). The inline
         // manifest is the <200ms common case; a >2MB manifest is a signed URL hop.

package/src/identity-link-accounts.tsx

@@ -0,0 +1,144 @@
+import { useEffect, useRef, useState } from "react";
+import type { ExternalIdentityLink, ExternalIdentityLinkPage } from "@opengeni/sdk";
+
+export type IdentityLinkAccountsClient = {
+  listIdentityLinks(workspaceId: string, cursor?: string): Promise<ExternalIdentityLinkPage>;
+  revokeIdentityLink(
+    workspaceId: string,
+    linkId: string,
+    expectedRevision: number,
+  ): Promise<ExternalIdentityLink>;
+};
+
+/** Participant-scoped inventory. Revocation never deletes native work or merges
+ * identities. The caller remounts this component when the signed-in user changes. */
+export function IdentityLinkAccounts({
+  client,
+  workspaceId,
+}: {
+  client: IdentityLinkAccountsClient;
+  workspaceId: string;
+}) {
+  const [links, setLinks] = useState<ExternalIdentityLink[]>([]);
+  const [cursor, setCursor] = useState<string | null>(null);
+  const [busy, setBusy] = useState(true);
+  const [error, setError] = useState(false);
+  const [revision, setRevision] = useState(0);
+  const generation = useRef(0);
+  const inFlight = useRef(false);
+  useEffect(() => {
+    const current = ++generation.current;
+    inFlight.current = true;
+    setLinks([]);
+    setCursor(null);
+    setBusy(true);
+    setError(false);
+    void client
+      .listIdentityLinks(workspaceId)
+      .then(
+        (page) => {
+          if (current !== generation.current) return;
+          setLinks(page.links);
+          setCursor(page.nextCursor);
+        },
+        () => {
+          if (current === generation.current) setError(true);
+        },
+      )
+      .finally(() => {
+        if (current === generation.current) {
+          inFlight.current = false;
+          setBusy(false);
+        }
+      });
+    return () => {
+      // Invalidate live async work, rather than cleaning up a captured DOM node.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      generation.current++;
+    };
+  }, [client, workspaceId, revision]);
+
+  async function act(link?: ExternalIdentityLink) {
+    if (inFlight.current || (!link && !cursor)) return;
+    const current = generation.current;
+    inFlight.current = true;
+    setBusy(true);
+    setError(false);
+    try {
+      if (link) {
+        const updated = await client.revokeIdentityLink(workspaceId, link.id, link.revision);
+        if (current === generation.current)
+          setLinks((values) =>
+            values.map((value) => (value.id === updated.id ? { ...value, ...updated } : value)),
+          );
+      } else {
+        const page = await client.listIdentityLinks(workspaceId, cursor!);
+        if (current === generation.current) {
+          setLinks((values) => [
+            ...new Map([...values, ...page.links].map((value) => [value.id, value])).values(),
+          ]);
+          setCursor(page.nextCursor);
+        }
+      }
+    } catch {
+      if (current === generation.current) setError(true);
+    } finally {
+      if (current === generation.current) {
+        inFlight.current = false;
+        setBusy(false);
+      }
+    }
+  }
+  return (
+    <section
+      className="og-connect og-identity-link"
+      aria-label="Linked product access"
+      aria-busy={busy}
+    >
+      <h2>Linked product access</h2>
+      <p>
+        Manage products allowed to act as your account in this organization. Revoking a link stops
+        future linked access; it does not delete your work or undo an operation already started.
+      </p>
+      {error && (
+        <div role="alert">
+          Could not update account links. Reload to see current access.
+          <button type="button" disabled={busy} onClick={() => setRevision((value) => value + 1)}>
+            Reload links
+          </button>
+        </div>
+      )}
+      {busy && <p role="status">Loading account links…</p>}
+      {!busy && !error && links.length === 0 && (
+        <p>No products have linked access to this account.</p>
+      )}
+      <ul>
+        {links.map((link) => (
+          <li key={link.id}>
+            <p>
+              {link.externalIdentity?.source || "Product identity"}{" "}
+              <code>{link.externalIdentity?.externalId ?? link.externalIdentityId}</code>
+            </p>
+            <p>
+              Status: {link.status}.{" "}
+              {link.expiresAt
+                ? `Expires ${new Date(link.expiresAt).toLocaleString()}.`
+                : "No automatic expiry."}
+            </p>
+            <p>{link.permissions.join(", ")}</p>
+            {(link.status === "active" || link.status === "pending") && (
+              <button type="button" disabled={busy} onClick={() => void act(link)}>
+                Revoke access
+              </button>
+            )}
+          </li>
+        ))}
+      </ul>
+      {cursor && (
+        <button type="button" disabled={busy} onClick={() => void act()}>
+          Load more links
+        </button>
+      )}
+    </section>
+  );
+}