@opengeni/react 0.48.0 → 0.57.0

package/src/components/artifacts/editable-artifact-ui.tsx

@@ -0,0 +1,89 @@
+import type {
+  EditableArtifactSession,
+  EditableArtifactSyncView,
+} from "@opengeni/sdk/editable-artifacts";
+import { useEffect, useState } from "react";
+
+export function useEditableArtifactView(
+  session: EditableArtifactSession,
+): EditableArtifactSyncView {
+  const [view, setView] = useState(() => session.getView());
+  useEffect(() => {
+    setView(session.getView());
+    return session.subscribe(setView);
+  }, [session]);
+  return view;
+}
+
+/** Changes whenever the Worker-resident speculative projection may have changed. */
+export function editableArtifactProjectionKey(view: EditableArtifactSyncView): string {
+  return [
+    view.state,
+    view.cursor,
+    view.headSequence,
+    view.pendingTransactions,
+    view.blockedPending.map((entry) => `${entry.clientTransactionId}:${entry.code}`).join(","),
+  ].join(":");
+}
+
+export function editableArtifactStatusLabel(view: EditableArtifactSyncView): string {
+  switch (view.state) {
+    case "idle":
+    case "connecting":
+      return "Connecting…";
+    case "syncing":
+    case "resyncing":
+      return "Syncing…";
+    case "reconnecting":
+      return "Reconnecting…";
+    case "unsupported":
+      return "This artifact version is not supported";
+    case "failed":
+      if (editableArtifactAccessRevoked(view)) {
+        return "You no longer have access to this artifact";
+      }
+      return view.lastError?.message ?? "Could not open this artifact";
+    case "closed":
+      return "Artifact session closed";
+    case "live":
+      return view.writable ? "Live" : "Live · Read only";
+  }
+}
+
+/** Revoked read authority must hide any projection retained before invalidation. */
+export function editableArtifactAccessRevoked(view: EditableArtifactSyncView): boolean {
+  if (view.state !== "failed" || !view.lastError) return false;
+  return (view.lastError as Error & Readonly<{ code?: unknown }>).code === "permission_changed";
+}
+
+export function EditableArtifactMessage({
+  title,
+  detail,
+  retry,
+}: {
+  title: string;
+  detail: string;
+  retry?: (() => void) | undefined;
+}) {
+  return (
+    <div className="grid h-full min-h-56 place-items-center bg-og-bg p-6 text-center">
+      <div>
+        <p className="text-og-base font-medium text-og-fg">{title}</p>
+        <p className="mt-1 max-w-lg text-og-sm text-og-fg-muted">{detail}</p>
+        {retry ? (
+          <button
+            type="button"
+            onClick={retry}
+            className="mt-3 rounded-og-sm bg-og-accent-deep px-3 py-1.5 text-og-sm font-medium text-og-accent-fg outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent"
+          >
+            Retry
+          </button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+export function asEditableArtifactError(cause: unknown, fallback: string): Error {
+  return cause instanceof Error ? cause : new Error(fallback);
+}

package/src/components/artifacts/editable-artifact-workbench.tsx

@@ -0,0 +1,203 @@
+import {
+  createBrowserEditableArtifactSession,
+  type CreateBrowserEditableArtifactSessionOptions,
+  type EditableArtifactBrowserRuntime,
+  type EditableArtifactSession,
+} from "@opengeni/sdk/editable-artifacts";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { EditableArtifactMessage } from "./editable-artifact-ui";
+import {
+  EditableDocumentArtifactSurface,
+  type EditableDocumentArtifactSurfaceProps,
+} from "./editable-document";
+import {
+  EditablePresentationArtifactSurface,
+  type EditablePresentationArtifactSurfaceProps,
+} from "./editable-presentation";
+import {
+  EditableSpreadsheetArtifactSurface,
+  type EditableSpreadsheetArtifactSurfaceProps,
+} from "./editable-spreadsheet";
+
+export type EditableArtifactWorkbenchProps = Readonly<{
+  session: EditableArtifactSession;
+  document?: Omit<EditableDocumentArtifactSurfaceProps, "session">;
+  spreadsheet?: Omit<EditableSpreadsheetArtifactSurfaceProps, "session">;
+  presentation?: Omit<EditablePresentationArtifactSurfaceProps, "session">;
+}>;
+
+export type EditableArtifactWorkbenchHostProps = Omit<EditableArtifactWorkbenchProps, "session"> &
+  Readonly<{
+    /**
+     * Complete identity of the browser session authority. Change this when the
+     * artifact, deployment, principal, or authorization epoch changes.
+     */
+    sessionKey: string;
+    /** Called for the active keyed lifecycle and again only after replacement or retry. */
+    createSession: () => EditableArtifactSession;
+  }>;
+
+type DefaultBrowserArtifactTransport = Omit<
+  NonNullable<CreateBrowserEditableArtifactSessionOptions["transport"]>,
+  "apiKey" | "fetch" | "headers" | "webSocketFactory"
+> &
+  Readonly<{
+    /** Static deployment auth headers; rotate authorizationEpoch when they change. */
+    headers?: Readonly<Record<string, string>>;
+  }>;
+
+export type BrowserEditableArtifactWorkbenchOptions = Omit<
+  CreateBrowserEditableArtifactSessionOptions,
+  "runtime" | "storage" | "transport"
+> &
+  Readonly<{
+    /** Default module Worker only; custom Worker hosts use EditableArtifactWorkbenchHost. */
+    runtime: Omit<EditableArtifactBrowserRuntime, "workerFactory">;
+    /** Default fetch/WebSocket only; static deployment auth headers are supported. */
+    transport?: DefaultBrowserArtifactTransport;
+  }>;
+
+export type BrowserEditableArtifactWorkbenchProps = Omit<
+  EditableArtifactWorkbenchProps,
+  "session"
+> &
+  Readonly<{ options: BrowserEditableArtifactWorkbenchOptions }>;
+
+/**
+ * One modality-neutral SDK workbench. Embedding hosts keep one route/component;
+ * each artifact still renders through its complete first-party editor surface.
+ */
+export function EditableArtifactWorkbench({
+  session,
+  document,
+  spreadsheet,
+  presentation,
+}: EditableArtifactWorkbenchProps) {
+  switch (session.modality) {
+    case "document":
+      return (
+        <EditableDocumentArtifactSurface
+          {...document}
+          session={session}
+          title={document?.title ?? "Document"}
+        />
+      );
+    case "spreadsheet":
+      return <EditableSpreadsheetArtifactSurface {...spreadsheet} session={session} />;
+    case "presentation":
+      return <EditablePresentationArtifactSurface {...presentation} session={session} />;
+  }
+}
+
+/**
+ * Route/embed composition that owns exactly one SDK session. The host supplies
+ * the authenticated SDK factory; React guarantees replacement and teardown.
+ */
+export function EditableArtifactWorkbenchHost({
+  sessionKey,
+  createSession,
+  document,
+  spreadsheet,
+  presentation,
+}: EditableArtifactWorkbenchHostProps) {
+  const createSessionRef = useRef(createSession);
+  const [retryEpoch, setRetryEpoch] = useState(0);
+  const [state, setState] = useState<
+    | Readonly<{ key: string; session: EditableArtifactSession; error: null }>
+    | Readonly<{ key: string | null; session: null; error: Error | null }>
+  >({ key: null, session: null, error: null });
+
+  useEffect(() => {
+    createSessionRef.current = createSession;
+  }, [createSession]);
+
+  useEffect(() => {
+    let owned: EditableArtifactSession | null = null;
+    setState({ key: sessionKey, session: null, error: null });
+    try {
+      owned = createSessionRef.current();
+      setState({ key: sessionKey, session: owned, error: null });
+    } catch (cause) {
+      setState({
+        key: sessionKey,
+        session: null,
+        error: cause instanceof Error ? cause : new Error("Could not create artifact session"),
+      });
+    }
+    return () => {
+      const closing = owned;
+      owned = null;
+      if (closing) void closing.close().catch(() => undefined);
+    };
+  }, [retryEpoch, sessionKey]);
+
+  const retry = useCallback(() => setRetryEpoch((value) => value + 1), []);
+  const currentError = state.key === sessionKey ? state.error : null;
+  if (state.key === sessionKey && state.session) {
+    return (
+      <EditableArtifactWorkbench
+        session={state.session}
+        {...(document ? { document } : {})}
+        {...(spreadsheet ? { spreadsheet } : {})}
+        {...(presentation ? { presentation } : {})}
+      />
+    );
+  }
+  return (
+    <EditableArtifactMessage
+      title={currentError ? "Could not open this artifact" : "Opening artifact"}
+      detail={currentError?.message ?? "Starting the secure editing session…"}
+      retry={currentError ? retry : undefined}
+    />
+  );
+}
+
+/**
+ * Complete default-browser composition for embedders: verified WASM Worker,
+ * durable IndexedDB state, authenticated live sync, teardown, and the matching
+ * first-party editor. Advanced/custom transports compose the lower-level host.
+ */
+export function BrowserEditableArtifactWorkbench({
+  options,
+  document,
+  spreadsheet,
+  presentation,
+}: BrowserEditableArtifactWorkbenchProps) {
+  const sessionKey = browserSessionKey(options);
+  const createSession = useCallback(() => createBrowserEditableArtifactSession(options), [options]);
+  return (
+    <EditableArtifactWorkbenchHost
+      sessionKey={sessionKey}
+      createSession={createSession}
+      {...(document ? { document } : {})}
+      {...(spreadsheet ? { spreadsheet } : {})}
+      {...(presentation ? { presentation } : {})}
+    />
+  );
+}
+
+function browserSessionKey(options: BrowserEditableArtifactWorkbenchOptions): string {
+  const transport = options.transport
+    ? {
+        ...options.transport,
+        // Credentials must not be copied into React lifecycle keys. The
+        // authorization epoch is the explicit credential/grant rotation fence.
+        headers: options.transport.headers
+          ? Object.keys(options.transport.headers).sort()
+          : undefined,
+      }
+    : null;
+  return JSON.stringify(
+    {
+      baseUrl: options.baseUrl,
+      workspaceId: options.workspaceId,
+      artifact: { id: options.artifact.id, modality: options.artifact.modality },
+      storageAuthority: options.storageAuthority,
+      runtime: options.runtime,
+      replicaId: options.replicaId ?? null,
+      transport,
+    },
+    (_key, value: unknown) => (value instanceof URL ? value.href : value),
+  );
+}