@mp-lb/mdkit 0.3.2 → 0.3.4

package/src/versioning/useMdKitDocumentVersions.ts

@@ -0,0 +1,146 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type {
+  MdKitDocumentAdapter,
+  MdKitDocumentVersionDetail,
+  MdKitDocumentVersionSummary,
+} from "../document/documentTypes";
+
+export type UseMdKitDocumentVersionsOptions = {
+  adapter: Pick<
+    MdKitDocumentAdapter,
+    "listDocumentVersions" | "readDocumentVersion"
+  >;
+  documentId: string | null;
+  enabled?: boolean;
+};
+
+export type MdKitDocumentVersionsController = {
+  error: string | null;
+  hasVersioning: boolean;
+  isLoading: boolean;
+  openVersion: (versionId: string) => Promise<void>;
+  refresh: () => Promise<void>;
+  selectedVersion: MdKitDocumentVersionDetail | null;
+  selectedVersionId: string | null;
+  versions: MdKitDocumentVersionSummary[];
+};
+
+/**
+ * Lists a document's checkpoints and lazily reads checkpoint detail, tracking
+ * loading state for checkpoint-history UI.
+ */
+export const useMdKitDocumentVersions = (
+  options: UseMdKitDocumentVersionsOptions,
+): MdKitDocumentVersionsController => {
+  const { adapter, documentId, enabled = true } = options;
+  const [versions, setVersions] = useState<MdKitDocumentVersionSummary[]>([]);
+
+  const [selectedVersionId, setSelectedVersionId] = useState<string | null>(
+    null,
+  );
+
+  const [selectedVersion, setSelectedVersion] =
+    useState<MdKitDocumentVersionDetail | null>(null);
+
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const hasVersioning =
+    enabled && !!adapter.listDocumentVersions && !!adapter.readDocumentVersion;
+
+  const refresh = useCallback(async () => {
+    if (!hasVersioning || !documentId || !adapter.listDocumentVersions) {
+      setVersions([]);
+      setSelectedVersionId(null);
+      setSelectedVersion(null);
+      setError(null);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const nextVersions = await adapter.listDocumentVersions(documentId);
+      setVersions(nextVersions);
+
+      setSelectedVersionId((currentSelectedVersionId) => {
+        if (
+          !nextVersions.some(
+            (version) => version.id === currentSelectedVersionId,
+          )
+        ) {
+          setSelectedVersion(null);
+          return null;
+        }
+
+        return currentSelectedVersionId;
+      });
+    } catch (err) {
+      setError(`Failed to load versions: ${String(err)}`);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [adapter, documentId, hasVersioning]);
+
+  const openVersion = useCallback(
+    async (versionId: string) => {
+      if (!hasVersioning || !documentId || !adapter.readDocumentVersion) {
+        return;
+      }
+
+      setSelectedVersionId(versionId);
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const nextVersion = await adapter.readDocumentVersion({
+          documentId,
+          versionId,
+        });
+
+        if (!nextVersion) {
+          setSelectedVersion(null);
+          setError("That version is no longer available.");
+          return;
+        }
+
+        setSelectedVersion(nextVersion);
+      } catch (err) {
+        setError(`Failed to load version: ${String(err)}`);
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [adapter, documentId, hasVersioning],
+  );
+
+  useEffect(() => {
+    setSelectedVersionId(null);
+    setSelectedVersion(null);
+    void refresh();
+  }, [documentId, refresh]);
+
+  return useMemo(
+    () => ({
+      error,
+      hasVersioning,
+      isLoading,
+      openVersion,
+      refresh,
+      selectedVersion,
+      selectedVersionId,
+      versions,
+    }),
+    [
+      error,
+      hasVersioning,
+      isLoading,
+      openVersion,
+      refresh,
+      selectedVersion,
+      selectedVersionId,
+      versions,
+    ],
+  );
+};

package/src/yjs/MdKitMarkdownYjs.ts

@@ -0,0 +1,111 @@
+import { getSchema } from "@tiptap/core";
+import { MarkdownManager } from "@tiptap/markdown";
+import {
+  prosemirrorJSONToYXmlFragment,
+  yXmlFragmentToProsemirrorJSON,
+} from "@tiptap/y-tiptap";
+import * as Y from "yjs";
+import { createMdKitTiptapExtensions } from "../markdown/createMdKitTiptapExtensions";
+import {
+  extractYamlFrontMatter,
+  prependYamlFrontMatter,
+} from "../markdown/yamlFrontMatter";
+import { normalizeMarkdownSerialization } from "../markdown/normalizeMarkdownSerialization";
+import { prepareMarkdownForEditorHydration } from "../markdown/prepareMarkdownForEditorHydration";
+
+export type MdKitMarkdownYjsOptions = {
+  fragmentName?: string;
+  ignoreYamlFrontMatter?: boolean;
+};
+
+const defaultMdKitYjsFragmentName = "default";
+const mdKitYjsMetadataMapName = "__mdkit";
+const frontMatterPrefixMetadataKey = "frontMatterPrefix";
+
+const getMdKitYjsFragmentName = (options?: MdKitMarkdownYjsOptions) =>
+  options?.fragmentName ?? defaultMdKitYjsFragmentName;
+
+const getFrontMatterPrefixMetadataKey = (fragmentName: string) =>
+  `${fragmentName}:${frontMatterPrefixMetadataKey}`;
+
+const createMdKitMarkdownManager = () =>
+  new MarkdownManager({
+    extensions: createMdKitTiptapExtensions(),
+    markedOptions: {
+      gfm: true,
+    },
+  });
+
+const createMdKitProseMirrorSchema = () =>
+  getSchema(createMdKitTiptapExtensions());
+
+const markdownToProseMirrorJson = (markdown: string) =>
+  createMdKitMarkdownManager().parse(
+    prepareMarkdownForEditorHydration(markdown),
+  );
+
+const proseMirrorJsonToMarkdown = (json: Record<string, any>) =>
+  normalizeMarkdownSerialization(createMdKitMarkdownManager().serialize(json));
+
+export const replaceMdKitYjsMarkdown = (
+  ydoc: Y.Doc,
+  markdown: string,
+  options?: MdKitMarkdownYjsOptions,
+): Uint8Array => {
+  const fragmentName = getMdKitYjsFragmentName(options);
+  const fragment = ydoc.getXmlFragment(fragmentName);
+  const metadata = ydoc.getMap<string>(mdKitYjsMetadataMapName);
+  const schema = createMdKitProseMirrorSchema();
+  const frontMatter = options?.ignoreYamlFrontMatter
+    ? extractYamlFrontMatter(markdown)
+    : null;
+  const json = markdownToProseMirrorJson(frontMatter?.body ?? markdown);
+  const metadataKey = getFrontMatterPrefixMetadataKey(fragmentName);
+
+  prosemirrorJSONToYXmlFragment(schema, json, fragment);
+
+  if (frontMatter?.frontMatter) {
+    metadata.set(metadataKey, frontMatter.frontMatter.raw);
+  } else {
+    metadata.delete(metadataKey);
+  }
+
+  return Y.encodeStateAsUpdate(ydoc);
+};
+
+export const markdownToMdKitYjs = (
+  markdown: string,
+  options?: MdKitMarkdownYjsOptions,
+): Uint8Array => {
+  const ydoc = new Y.Doc();
+
+  return replaceMdKitYjsMarkdown(ydoc, markdown, options);
+};
+
+export const mdKitYjsToMarkdown = (
+  yjsState: Uint8Array,
+  options?: MdKitMarkdownYjsOptions,
+): string => {
+  const ydoc = new Y.Doc();
+
+  Y.applyUpdate(ydoc, yjsState);
+
+  const fragmentName = getMdKitYjsFragmentName(options);
+  const json = yXmlFragmentToProsemirrorJSON(
+    ydoc.getXmlFragment(fragmentName),
+  );
+  const metadata = ydoc.getMap<string>(mdKitYjsMetadataMapName);
+  const frontMatterRaw =
+    metadata.get(getFrontMatterPrefixMetadataKey(fragmentName)) ?? "";
+
+  return prependYamlFrontMatter(
+    frontMatterRaw,
+    proseMirrorJsonToMarkdown(json),
+  );
+};
+
+export const yjs = {
+  markdownToMdKitYjs,
+  mdKitYjsToMarkdown,
+  replaceMdKitYjsMarkdown,
+};

package/src/yjs/index.ts

@@ -0,0 +1,8 @@
+export {
+  markdownToMdKitYjs,
+  mdKitYjsToMarkdown,
+  replaceMdKitYjsMarkdown,
+  yjs,
+} from "./MdKitMarkdownYjs";
+
+export type { MdKitMarkdownYjsOptions } from "./MdKitMarkdownYjs";

package/docs/.vitepress/config.ts

@@ -1,47 +0,0 @@
-import { defineConfig } from "vitepress";
-
-export default defineConfig({
-  title: "Markdown Editor Kit",
-  description: "Docs for the mdkit markdown editor package",
-  cleanUrls: true,
-  themeConfig: {
-    nav: [
-      { text: "Quick Start", link: "/" },
-      { text: "Plain Text", link: "/plain-text" },
-      { text: "Styling", link: "/styling" },
-      { text: "Shadcn", link: "/shadcn" },
-      { text: "REST", link: "/rest" },
-      { text: "Use Cases", link: "/use-cases" },
-      { text: "Permissions", link: "/permissions" },
-      { text: "Collaboration Persistence", link: "/collaboration-persistence" },
-      { text: "API", link: "/api" },
-      { text: "Architecture", link: "/architecture" },
-    ],
-    sidebar: [
-      {
-        text: "Guide",
-        items: [
-          { text: "Quick Start", link: "/" },
-          { text: "Plain Text Editors", link: "/plain-text" },
-          { text: "Styling", link: "/styling" },
-          { text: "Shadcn Plugin", link: "/shadcn" },
-          { text: "REST Backend", link: "/rest" },
-          { text: "Use Cases", link: "/use-cases" },
-          { text: "Permissions", link: "/permissions" },
-          {
-            text: "Collaboration Persistence",
-            link: "/collaboration-persistence",
-          },
-          { text: "API Reference", link: "/api" },
-          { text: "Architecture", link: "/architecture" },
-        ],
-      },
-    ],
-    socialLinks: [
-      {
-        icon: "github",
-        link: "https://github.com/mp-lb/mdkit",
-      },
-    ],
-  },
-});