@opengeni/react 4.0.2 → 5.0.2-canary.0

package/src/connect-accounts.tsx

@@ -0,0 +1,171 @@
+import { useEffect, useRef, useState } from "react";
+import type { ConnectAccount, ConnectController } from "@opengeni/connect";
+import { useConnect } from "./connect";
+
+export type ConnectAccountsProps = {
+  controller: ConnectController;
+  className?: string;
+  /** Enables explicit account-bound reconnect. Host supplies the exact destination. */
+  returnUrl?: string;
+};
+
+/** Local credential revocation only. Unknown or changed versions must be
+ * refreshed; this component never retries a destructive operation implicitly. */
+export function ConnectAccounts(props: ConnectAccountsProps) {
+  const [scope, setScope] = useState(props.controller);
+  const [generation, setGeneration] = useState(0);
+  if (scope !== props.controller) {
+    setScope(props.controller);
+    setGeneration(generation + 1);
+  }
+  return <ScopedAccounts key={generation} {...props} />;
+}
+
+function ScopedAccounts({ controller, className, returnUrl }: ConnectAccountsProps) {
+  const view = useConnect(controller);
+  const [accounts, setAccounts] = useState<ConnectAccount[] | null>(null);
+  const [selected, setSelected] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(false);
+  const [reload, setReload] = useState(0);
+  const mutation = useRef<AbortController | null>(null);
+  useEffect(() => () => mutation.current?.abort(), []);
+  useEffect(() => {
+    const abort = new AbortController();
+    setAccounts(null);
+    setSelected(null);
+    setError(false);
+    void Promise.resolve()
+      .then(() => {
+        abort.signal.throwIfAborted();
+        return controller.transport.accounts(controller.workspaceId, { signal: abort.signal });
+      })
+      .then((result) => {
+        if (!abort.signal.aborted) setAccounts(structuredClone(result));
+      })
+      .catch(() => {
+        if (!abort.signal.aborted) setError(true);
+      });
+    return () => abort.abort();
+  }, [controller, reload]);
+
+  const disconnect = async (account: ConnectAccount) => {
+    const expectedVersion = account.version;
+    if (
+      mutation.current ||
+      view.busy ||
+      expectedVersion === undefined ||
+      !Number.isSafeInteger(expectedVersion) ||
+      expectedVersion < 1
+    )
+      return;
+    const abort = new AbortController();
+    mutation.current = abort;
+    setBusy(true);
+    setError(false);
+    try {
+      await controller.transport.disconnect(controller.workspaceId, account.id, {
+        expectedVersion,
+        signal: abort.signal,
+      });
+      if (!abort.signal.aborted) setReload((value) => value + 1);
+    } catch {
+      if (!abort.signal.aborted) {
+        // Outcome may be unknown. Drop the inventory so a second click cannot
+        // replay against the stale selection; let the host reload live state.
+        setAccounts(null);
+        setError(true);
+      }
+    } finally {
+      if (!abort.signal.aborted) {
+        mutation.current = null;
+        setBusy(false);
+        setSelected(null);
+      }
+    }
+  };
+  const reconnect = async (account: ConnectAccount) => {
+    if (!returnUrl || mutation.current || view.busy) return;
+    setError(false);
+    try {
+      await controller.begin({
+        providerId: account.providerId,
+        ownership: account.ownership,
+        reconnectAccountId: account.id,
+        returnUrl,
+        idempotencyKey: crypto.randomUUID(),
+      });
+    } catch {
+      setError(true);
+    }
+  };
+
+  return (
+    <section
+      className={className}
+      aria-label="Connected accounts"
+      aria-busy={busy || view.busy || (!accounts && !error)}
+    >
+      {error && (
+        <p role="alert">Account state could not be confirmed. Reload before trying again.</p>
+      )}
+      {!accounts && !error && <p role="status">Loading accounts…</p>}
+      {accounts?.length === 0 && <p role="status">No connected accounts.</p>}
+      {accounts && accounts.length > 0 && (
+        <ul>
+          {accounts.map((account) => (
+            <li key={`${account.providerId}:${account.id}`}>
+              <span>
+                {account.label} — {account.providerId} — {account.ownership} —{" "}
+                {account.status.replaceAll("_", " ")}
+              </span>
+              {returnUrl && (
+                <button
+                  type="button"
+                  disabled={busy || view.busy || account.status === "disabled"}
+                  onClick={() => void reconnect(account)}
+                >
+                  Reconnect {account.label}
+                </button>
+              )}
+              {selected === `${account.providerId}:${account.id}` ? (
+                <div role="group" aria-label={`Disconnect ${account.label}`}>
+                  <p>
+                    This removes local OpenGeni access. It does not revoke consent at the provider.
+                  </p>
+                  <button
+                    type="button"
+                    disabled={busy || view.busy}
+                    onClick={() => void disconnect(account)}
+                  >
+                    Confirm disconnect
+                  </button>
+                  <button type="button" disabled={busy} onClick={() => setSelected(null)}>
+                    Keep account
+                  </button>
+                </div>
+              ) : (
+                <button
+                  type="button"
+                  disabled={
+                    busy ||
+                    view.busy ||
+                    account.status === "disabled" ||
+                    !Number.isSafeInteger(account.version) ||
+                    account.version! < 1
+                  }
+                  onClick={() => setSelected(`${account.providerId}:${account.id}`)}
+                >
+                  Disconnect {account.label}
+                </button>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+      <button type="button" disabled={busy} onClick={() => setReload((value) => value + 1)}>
+        Reload accounts
+      </button>
+    </section>
+  );
+}

package/src/connect-chooser.tsx

@@ -0,0 +1,144 @@
+import { useEffect, useState, type FormEvent } from "react";
+import type { ConnectController, ConnectProvider } from "@opengeni/connect";
+import { useConnect } from "./connect";
+
+export type ConnectChooserProps = {
+  controller: ConnectController;
+  /** Exact host return string; no completion parameters are added. */
+  returnUrl: string;
+  className?: string;
+};
+
+/** Catalog readiness is supplied by the authenticated backend, never inferred
+ * from the existence of a provider definition. Host replaces the controller on
+ * actor/workspace change. This form does not open OAuth windows itself. */
+export function ConnectChooser(props: ConnectChooserProps) {
+  // Remount scope-local selections synchronously when the controller changes,
+  // before effects can expose a previous actor's inventory for one frame.
+  const [scope, setScope] = useState(props.controller);
+  const [generation, setGeneration] = useState(0);
+  if (scope !== props.controller) {
+    setScope(props.controller);
+    setGeneration(generation + 1);
+  }
+  return <ScopedChooser key={generation} {...props} />;
+}
+
+function ScopedChooser({ controller, returnUrl, className }: ConnectChooserProps) {
+  const view = useConnect(controller);
+  const [catalog, setCatalog] = useState<ConnectProvider[] | null>(null);
+  const [failed, setFailed] = useState(false);
+  const [load, setLoad] = useState(0);
+  const [providerId, setProviderId] = useState("");
+  const [ownership, setOwnership] = useState("");
+  useEffect(() => {
+    const abort = new AbortController();
+    setCatalog(null);
+    setFailed(false);
+    setProviderId("");
+    setOwnership("");
+    // Promise boundary also handles a synchronously throwing injected transport.
+    void Promise.resolve()
+      .then(() => {
+        abort.signal.throwIfAborted();
+        return controller.transport.catalog(controller.workspaceId, { signal: abort.signal });
+      })
+      .then((providers) => {
+        if (!abort.signal.aborted) setCatalog(structuredClone(providers));
+      })
+      .catch(() => {
+        if (!abort.signal.aborted) setFailed(true);
+      });
+    return () => abort.abort();
+  }, [controller, load]);
+  const provider = catalog?.find((entry) => entry.id === providerId);
+  const canBegin =
+    provider?.readiness === "available" &&
+    (ownership === "personal" || ownership === "workspace") &&
+    provider.ownership.includes(ownership);
+  const submit = (event: FormEvent) => {
+    event.preventDefault();
+    if (!canBegin || view.busy || (ownership !== "personal" && ownership !== "workspace")) return;
+    setFailed(false);
+    try {
+      void controller
+        .begin({ providerId, ownership, returnUrl, idempotencyKey: crypto.randomUUID() })
+        .catch(() => setFailed(true));
+    } catch {
+      setFailed(true);
+    }
+  };
+  return (
+    <section
+      className={className}
+      aria-label="Choose a connection"
+      aria-busy={view.busy || (!catalog && !failed)}
+    >
+      {failed && (
+        <p role="alert">
+          Connections could not be loaded or started. Check setup status before retrying.
+        </p>
+      )}
+      {!catalog && !failed && <p role="status">Loading connections…</p>}
+      {catalog?.length === 0 && <p role="status">No connections are available.</p>}
+      {Boolean(catalog?.length) && (
+        <form onSubmit={submit}>
+          <fieldset disabled={view.busy}>
+            <legend>Provider and ownership</legend>
+            <label>
+              Provider
+              <select
+                required
+                value={providerId}
+                onChange={(event) => {
+                  setProviderId(event.target.value);
+                  setOwnership("");
+                }}
+              >
+                <option value="" disabled>
+                  Choose a provider
+                </option>
+                {catalog!.map((entry) => (
+                  <option
+                    key={entry.id}
+                    value={entry.id}
+                    disabled={entry.readiness !== "available" || entry.ownership.length === 0}
+                  >
+                    {entry.label} — {entry.id} ({entry.readiness.replaceAll("_", " ")})
+                  </option>
+                ))}
+              </select>
+            </label>
+            {provider && (
+              <label>
+                Ownership
+                <select
+                  required
+                  value={ownership}
+                  onChange={(event) => setOwnership(event.target.value)}
+                >
+                  <option value="" disabled>
+                    Choose ownership
+                  </option>
+                  {provider.ownership.map((choice) => (
+                    <option key={choice} value={choice}>
+                      {choice === "personal"
+                        ? "Personal — owned by you"
+                        : "Workspace — shared connection"}
+                    </option>
+                  ))}
+                </select>
+              </label>
+            )}
+            <button type="submit" disabled={!canBegin}>
+              Start setup
+            </button>
+          </fieldset>
+        </form>
+      )}
+      <button type="button" disabled={view.busy} onClick={() => setLoad(load + 1)}>
+        Reload providers
+      </button>
+    </section>
+  );
+}

package/src/connect-panel.tsx

@@ -0,0 +1,29 @@
+import { ConnectAccounts } from "./connect-accounts";
+import { ConnectChooser } from "./connect-chooser";
+import { ConnectSetup, type ConnectSetupProps } from "./connect-setup";
+
+export type ConnectPanelProps = ConnectSetupProps & {
+  returnUrl: string;
+  title?: string;
+  showAccounts?: boolean;
+};
+
+/** Optional composition over the same unstyled surfaces. Import
+ * @opengeni/react/connect.css for styling; the host retains navigation,
+ * transport, actor admission, and controller lifetime. */
+export function ConnectPanel({
+  returnUrl,
+  title = "Connections",
+  showAccounts = true,
+  className,
+  ...setup
+}: ConnectPanelProps) {
+  return (
+    <div className={["og-connect", className].filter(Boolean).join(" ")}>
+      <h2>{title}</h2>
+      <ConnectChooser controller={setup.controller} returnUrl={returnUrl} />
+      <ConnectSetup {...setup} />
+      {showAccounts && <ConnectAccounts controller={setup.controller} returnUrl={returnUrl} />}
+    </div>
+  );
+}

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]);
+}