@moloodev/editor-sdk 0.0.0-stage → 0.1.0

package/src/view/hooks.ts

@@ -0,0 +1,260 @@
+import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState, type ReactNode } from "react";
+import { KNOWN_PATTERN_IDS, resolvePatternAppearance } from "@moloodev/platform";
+import type { Doc } from "../crdt";
+import type { Composition, Publication } from "@moloodev/platform";
+import type {
+  EditorLayoutValues,
+  EditorAsset,
+  EditorOperation,
+  EditorRevision,
+  EditorSession,
+  EditorSessionAsset,
+} from "../index";
+
+export type { EditorAsset, EditorSessionAsset, EditorLayoutValues } from "../index";
+import { resetLayoutCommandId } from "../editor-common";
+import type { EditorView } from "../view";
+
+export type EditorDocProjectInput = {
+  doc: Doc | unknown | null;
+  data: Record<string, unknown> | null;
+};
+
+export type EditorOpenBrowserArgs = {
+  mode?: "pick";
+  acceptedTypes?: readonly string[];
+  excludeTypes?: readonly string[];
+  excludeIds?: readonly string[];
+  onPick?: (assets: readonly EditorAsset[]) => void;
+  onDismiss?: () => void;
+};
+
+export type EditorViewBinding = {
+  useTheme(): { theme: "dark" | "light" };
+  useKind(type: string): { id: string; label: string; color: string; icon: string };
+  useKinds(): { id: string; label: string; color: string; icon: string }[];
+  useList(args?: { type?: string }): { data: EditorAsset[] | undefined };
+  useComposition(id: string | null): {
+    data: Composition | undefined;
+    isError: boolean;
+    replace(composition: Composition): void;
+    fetch(): Promise<Composition>;
+    invalidate(): Promise<void>;
+  };
+  usePublication(id: string | null): {
+    data: Publication | undefined;
+    replace(publication: Publication): void;
+    invalidate(): Promise<void>;
+  };
+  useAssetClient(): {
+    listRevisions(id: string): Promise<EditorRevision[]>;
+    confirmBundle(
+      id: string,
+      input: { message: string; reviewed: string },
+    ): Promise<{ composition: Composition; revision: number }>;
+    putPublication(id: string, publication: Publication): Promise<Publication>;
+  };
+  useAssetOpener(): ((target: { id: string; type: string }) => void) | null;
+  useAssetInfo(): {
+    open(options?: { focus?: "revision-message" }): void;
+    setCreateAdapter(adapter: {
+      canCreate: boolean;
+      reason?: string;
+      submit(message: string): Promise<boolean>;
+    } | null): void;
+  };
+  useOpenSession(): {
+    asset: EditorSessionAsset | null;
+    doc: Doc | null;
+    mode: EditorSession["mode"];
+    data: Record<string, unknown> | null;
+    syncStatus: EditorSession["syncStatus"];
+    openBrowser(args?: EditorOpenBrowserArgs): void;
+    closeBrowser(): void;
+  };
+  useEditorHost(): {
+    canManage: boolean;
+    acceptedTypes: readonly string[];
+    openStartDialog(): void;
+    render(input: EditorOperation["host.render"]["body"]): Promise<EditorOperation["host.render"]["success"]>;
+  };
+  useEditorDocProjection<T>(options: {
+    project: (source: EditorDocProjectInput) => T;
+    hydrate: (value: T) => void;
+    onProjectError?: () => void;
+  }): { ready: boolean };
+};
+
+const EditorViewContext = createContext<EditorViewBinding | null>(null);
+
+export function EditorViewProvider({
+  binding,
+  children,
+}: {
+  binding: EditorViewBinding;
+  children: ReactNode;
+}) {
+  return createElement(EditorViewContext.Provider, { value: binding, children });
+}
+
+function useBinding(hook: string): EditorViewBinding {
+  const binding = useContext(EditorViewContext);
+  if (!binding) throw new Error(`${hook} must be used within EditorViewProvider`);
+  return binding;
+}
+
+export function isEditorContentReady(
+  mode: EditorSession["mode"],
+  hasDoc: boolean,
+): boolean {
+  return (mode === "edit" || mode === "read") && hasDoc;
+}
+
+export function shouldShowContentError(
+  contentError: boolean,
+  mode: EditorSession["mode"],
+  hasDoc: boolean,
+): boolean {
+  return contentError && isEditorContentReady(mode, hasDoc);
+}
+
+export function kindOf(type: string) {
+  const entry = resolvePatternAppearance(type);
+  return {
+    id: type,
+    label: entry.label,
+    color: entry.color,
+    icon: entry.icon,
+  };
+}
+
+export function kindsOf() {
+  return KNOWN_PATTERN_IDS.map(kindOf);
+}
+
+export function useTheme() {
+  return useBinding("useTheme").useTheme();
+}
+
+export function useKind(type: string) {
+  return useBinding("useKind").useKind(type);
+}
+
+export function useKinds() {
+  return useBinding("useKinds").useKinds();
+}
+
+export function useList(args: { type?: string } = {}): {
+  data: EditorAsset[] | undefined;
+} {
+  return useBinding("useList").useList(args);
+}
+
+export function useComposition(id: string | null) {
+  return useBinding("useComposition").useComposition(id);
+}
+
+export function usePublication(id: string | null) {
+  return useBinding("usePublication").usePublication(id);
+}
+
+export function useAssetClient() {
+  return useBinding("useAssetClient").useAssetClient();
+}
+
+export function useAssetOpener() {
+  return useBinding("useAssetOpener").useAssetOpener();
+}
+
+export function useAssetInfo() {
+  return useBinding("useAssetInfo").useAssetInfo();
+}
+
+export function useOpenSession() {
+  return useBinding("useOpenSession").useOpenSession();
+}
+
+export function useEditorHost() {
+  return useBinding("useEditorHost").useEditorHost();
+}
+
+export function useEditorDocProjection<T>(options: {
+  project: (source: EditorDocProjectInput) => T;
+  hydrate: (value: T) => void;
+  onProjectError?: () => void;
+}) {
+  return useBinding("useEditorDocProjection").useEditorDocProjection(options);
+}
+
+export function useHostLayout(view: EditorView): {
+  loading: boolean;
+  layout: EditorLayoutValues | null;
+  save(values: EditorLayoutValues): void;
+} {
+  const [loaded, setLoaded] = useState<{
+    view: EditorView;
+    layout: EditorLayoutValues | null;
+  } | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pending = useRef<EditorLayoutValues | null>(null);
+  const ticket = useRef(0);
+  useEffect(() => {
+    const current = ++ticket.current;
+    let active = true;
+    void view.handshake.then(() => view.call["layout.load"]({})).then(
+      (response) => {
+        if (active && current === ticket.current) {
+          setLoaded({ view, layout: response.ok ? response.body.layout : null });
+        }
+      },
+      () => {
+        if (active && current === ticket.current) setLoaded({ view, layout: null });
+      },
+    );
+    return () => {
+      active = false;
+      if (timer.current !== null) clearTimeout(timer.current);
+      timer.current = null;
+      if (pending.current !== null) {
+        const layout = pending.current;
+        pending.current = null;
+        void view.call["layout.save"]({ layout }).catch(() => {});
+      }
+    };
+  }, [view]);
+  useEffect(() => {
+    let active = true;
+    const stop = view.onCommand((commandId) => {
+      if (!active || commandId !== resetLayoutCommandId) return;
+      if (timer.current !== null) clearTimeout(timer.current);
+      timer.current = null;
+      pending.current = null;
+      const current = ++ticket.current;
+      setLoaded(null);
+      void view.call["layout.load"]({}).then(
+        (response) => {
+          if (!active || current !== ticket.current) return;
+          setLoaded({ view, layout: response.ok ? response.body.layout : null });
+        },
+        () => {
+          if (!active || current !== ticket.current) return;
+          setLoaded({ view, layout: null });
+        },
+      );
+    });
+    return () => {
+      active = false;
+      stop();
+    };
+  }, [view]);
+  const save = useCallback((values: EditorLayoutValues) => {
+    if (timer.current !== null) clearTimeout(timer.current);
+    pending.current = values;
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      pending.current = null;
+      void view.call["layout.save"]({ layout: values }).catch(() => {});
+    }, 500);
+  }, [view]);
+  return { loading: loaded?.view !== view, layout: loaded?.view === view ? loaded.layout : null, save };
+}

package/src/view/mount-editor-view.ts

@@ -0,0 +1,36 @@
+import { createElement, type ComponentType } from "react";
+import type { EditorManifest } from "../commands";
+import { connectEditorView, type EditorView } from "../view";
+import { bindThemeClass } from "./theme-class";
+import { createEditorChrome } from "./editor-chrome";
+
+/** Imports outside an iframe stay inert, including server and DOM unit tests. */
+export function mountEditorView(options: {
+  manifest: EditorManifest;
+  layout: Parameters<typeof createEditorChrome>[1];
+  Root: ComponentType<{ view: EditorView }>;
+}): EditorView | null {
+  if (typeof window === "undefined") return null;
+  const parent = new URLSearchParams(window.location.search).get("parent");
+  if (parent === null) return null;
+  const view = connectEditorView({
+    parent,
+    editorId: options.manifest.id,
+    createChannel: () => new MessageChannel(),
+    postMessage: (message, origin, ports) => window.parent.postMessage(message, origin, [...ports]),
+  });
+  bindThemeClass(view, document.documentElement);
+  const root = document.createElement("div");
+  root.id = "root";
+  document.body.append(root);
+  void import("react-dom/client").then(({ createRoot }) => {
+    createRoot(root).render(createElement(options.Root, { view }));
+  });
+  void view.handshake.then(async (reply) => {
+    if (!reply.ok) throw new Error(reply.code);
+    const { chromeManifest } = createEditorChrome(options.manifest, options.layout);
+    const submitted = await view.call["chrome.submit"](chromeManifest);
+    if (!submitted.ok) throw new Error(submitted.code);
+  });
+  return view;
+}

package/src/view/port-binding.ts

@@ -0,0 +1,127 @@
+import { createElement, useCallback, useMemo, useSyncExternalStore, type ReactNode } from "react";
+import type { EditorOperation } from "../index";
+import { RenderFailure, renderCode } from "../render-result";
+import type { EditorView } from "../view";
+import { EditorViewProvider, kindOf, type EditorOpenBrowserArgs, type EditorViewBinding } from "./hooks";
+
+function createPortBinding(view: EditorView, acceptedTypes: readonly string[]): EditorViewBinding {
+  let pending: { args: EditorOpenBrowserArgs } | null = null;
+
+  function closeBrowser() {
+    const previous = pending;
+    pending = null;
+    previous?.args.onDismiss?.();
+  }
+
+  function openBrowser(args?: EditorOpenBrowserArgs) {
+    closeBrowser();
+    if (args?.onPick || args?.onDismiss) {
+      const pick = { args };
+      pending = pick;
+      const body: EditorOperation["host.pick"]["body"] = {};
+      if (args.acceptedTypes !== undefined) body.acceptedTypes = [...args.acceptedTypes];
+      if (args.excludeTypes !== undefined) body.excludeTypes = [...args.excludeTypes];
+      if (args.excludeIds !== undefined) body.excludeIds = [...args.excludeIds];
+      void view.call["host.pick"](body).then((response) => {
+        if (pending !== pick) return;
+        pending = null;
+        if (response.ok && !response.body.cancelled) args.onPick?.(response.body.assets);
+        else args.onDismiss?.();
+      });
+      return;
+    }
+    void view.call["host.openBrowser"](
+      args?.excludeIds === undefined ? {} : { excludeIds: args.excludeIds },
+    );
+  }
+
+  function openStartDialog() {
+    void view.call["host.start"]({});
+  }
+
+  function openAsset(target: { id: string; type: string }) {
+    void view.call["host.openAsset"]({ id: target.id, type: target.type });
+  }
+
+  function setCreateAdapter(adapter: Parameters<ReturnType<EditorViewBinding["useAssetInfo"]>["setCreateAdapter"]>[0]) {
+    if (adapter !== null) throw new Error("setCreateAdapter is not available in iframe views");
+  }
+
+  function useSnapshot() {
+    return useSyncExternalStore(view.subscribe, view.getSnapshot, view.getSnapshot);
+  }
+
+  function unavailable(hook: string): never {
+    useSnapshot();
+    throw new Error(`${hook} is not available in iframe views`);
+  }
+
+  return {
+    useTheme() {
+      const theme = useSnapshot().theme ?? "dark";
+      return useMemo(() => ({ theme }), [theme]);
+    },
+    useKind(type) {
+      useSnapshot();
+      return useMemo(() => kindOf(type), [type]);
+    },
+    useKinds: () => unavailable("useKinds"),
+    useList: () => unavailable("useList"),
+    useComposition: () => unavailable("useComposition"),
+    usePublication: () => unavailable("usePublication"),
+    useAssetClient: () => unavailable("useAssetClient"),
+    useEditorDocProjection: () => unavailable("useEditorDocProjection"),
+    useOpenSession() {
+      const snapshot = useSnapshot();
+      const session = snapshot.session;
+      const doc = session?.asset ? snapshot.doc : null;
+      return useMemo(() => ({
+        asset: session?.asset ?? null,
+        doc,
+        mode: session?.mode ?? "idle",
+        data: session?.data ?? null,
+        syncStatus: session?.syncStatus ?? "offline",
+        openBrowser,
+        closeBrowser,
+      }), [session, doc, openBrowser, closeBrowser]);
+    },
+    useEditorHost() {
+      const canManage = useSnapshot().access?.canManage ?? false;
+      return useMemo(() => ({
+        canManage,
+        acceptedTypes,
+        openStartDialog,
+        render(input: EditorOperation["host.render"]["body"]) {
+          return view.call["host.render"](input).then((response) => {
+            if (response.ok) return response.body;
+            const code = renderCode(response.code);
+            if (code === undefined) throw new Error(response.code);
+            throw new RenderFailure(code);
+          });
+        },
+      }), [canManage, acceptedTypes, openStartDialog, view]);
+    },
+    useAssetOpener() {
+      useSnapshot();
+      return useCallback(openAsset, [openAsset]);
+    },
+    useAssetInfo() {
+      const id = useSnapshot().session?.asset?.id;
+      return useMemo(() => ({
+        open() {
+          if (id !== undefined) void view.call["host.openInfo"]({ id });
+        },
+        setCreateAdapter,
+      }), [id, view, setCreateAdapter]);
+    },
+  };
+}
+
+export function PortEditorView({ view, acceptedTypes, children }: {
+  view: EditorView;
+  acceptedTypes: readonly string[];
+  children: ReactNode;
+}) {
+  const binding = useMemo(() => createPortBinding(view, acceptedTypes), [view, acceptedTypes]);
+  return createElement(EditorViewProvider, { binding, children });
+}

package/src/view/port-commands.ts

@@ -0,0 +1,36 @@
+import { Fragment, createElement, useEffect, useMemo, type ReactNode } from "react";
+import { CommandsProvider, useCommands, type ContributionManifest } from "../commands";
+import { resetLayoutCommandId } from "../editor-common";
+import type { EditorView } from "../view";
+
+export function bindViewCommands(view: EditorView, execute: (commandId: string) => Promise<void>): () => void {
+  return view.onCommand((commandId) => {
+    // useHostLayout reloads the saved layout. The registry has no handler for this id.
+    if (commandId === resetLayoutCommandId) return;
+    void execute(commandId);
+  });
+}
+
+export function shortcutForwarder(view: EditorView) {
+  return (binding: { key: string; commandId: string }): boolean => view.sendShortcut(binding);
+}
+
+function ViewCommands({ view }: { view: EditorView }) {
+  const { execute } = useCommands();
+  useEffect(() => bindViewCommands(view, execute), [view, execute]);
+  return null;
+}
+
+export function PortCommandsProvider({ view, manifests, children }: {
+  view: EditorView;
+  manifests: ContributionManifest[];
+  children: ReactNode;
+}) {
+  const forward = useMemo(() => shortcutForwarder(view), [view]);
+  return createElement(CommandsProvider, {
+    manifests,
+    onKeybinding: forward,
+    children: createElement(Fragment, null,
+      createElement(ViewCommands, { view }), children),
+  });
+}

package/src/view/port.ts

@@ -0,0 +1,35 @@
+import type { EditorPort } from "../channel";
+
+type PortMessage = { readonly data: unknown };
+
+/** Adapts a platform MessagePort to the protocol EditorPort. */
+export function editorPort(port: MessagePort): EditorPort {
+  const listeners = new Map<
+    (event: PortMessage) => void,
+    (event: PortMessage) => void
+  >();
+  return {
+    postMessage(data: unknown) {
+      port.postMessage(data);
+    },
+    start() {
+      port.start();
+    },
+    close() {
+      port.close();
+    },
+    addEventListener(_type, listener) {
+      const wrapped = (event: PortMessage) => {
+        listener({ data: event.data });
+      };
+      listeners.set(listener, wrapped);
+      port.addEventListener("message", wrapped);
+    },
+    removeEventListener(_type, listener) {
+      const wrapped = listeners.get(listener);
+      if (!wrapped) return;
+      listeners.delete(listener);
+      port.removeEventListener("message", wrapped);
+    },
+  };
+}

package/src/view/theme-class.ts

@@ -0,0 +1,11 @@
+import type { EditorView } from "../view";
+
+export function bindThemeClass(view: EditorView, root: {
+  classList: { toggle(token: string, force: boolean): unknown };
+}): () => void {
+  function update() {
+    root.classList.toggle("dark", view.getSnapshot().theme !== "light");
+  }
+  update();
+  return view.subscribe(update);
+}