@mp-lb/mdkit 0.3.2 → 0.3.3

package/src/core/documentEngine.ts

@@ -0,0 +1,175 @@
+import type {
+  MdKitDocumentSnapshot,
+  MdKitDocumentVersionDetail,
+  MdKitDocumentVersionToken,
+  MdKitDocumentWriteResult,
+} from "../document/documentTypes.js";
+
+export type MdKitDocumentRecord = {
+  current: MdKitDocumentSnapshot;
+  versions: MdKitDocumentVersionDetail[];
+};
+
+export type CreateMdKitDocumentRecordInput = {
+  content?: string;
+  now?: string;
+};
+
+export type WriteMdKitDocumentRecordInput = {
+  baseVersion: MdKitDocumentVersionToken;
+  content: string;
+  force?: boolean;
+  label?: string;
+  now?: string;
+};
+
+export type WriteMdKitDocumentRecordResult = {
+  record: MdKitDocumentRecord;
+  result: MdKitDocumentWriteResult;
+};
+
+export type RestoreMdKitDocumentVersionInput = {
+  label?: string;
+  now?: string;
+  versionId: string;
+};
+
+export type RestoreMdKitDocumentVersionResult = {
+  record: MdKitDocumentRecord;
+  restoredVersion: MdKitDocumentVersionDetail;
+  result: MdKitDocumentWriteResult;
+};
+
+const initialVersion = "0";
+
+const createTimestamp = () => new Date().toISOString();
+
+export const normalizeMdKitVersionToken = (
+  version: MdKitDocumentVersionToken | undefined,
+) => (version == null ? null : String(version));
+
+export const detectMdKitDocumentConflict = (input: {
+  baseVersion: MdKitDocumentVersionToken;
+  currentVersion: MdKitDocumentVersionToken;
+}) =>
+  normalizeMdKitVersionToken(input.baseVersion) !==
+  normalizeMdKitVersionToken(input.currentVersion);
+
+const nextVersionToken = (currentVersion: MdKitDocumentVersionToken) => {
+  const current = Number(normalizeMdKitVersionToken(currentVersion));
+
+  return Number.isFinite(current) ? String(current + 1) : createTimestamp();
+};
+
+const createVersionDetail = (input: {
+  content: string;
+  id: string;
+  label?: string;
+  now: string;
+}): MdKitDocumentVersionDetail => ({
+  content: input.content,
+  createdAt: input.now,
+  id: input.id,
+  label: input.label,
+  updatedAt: input.now,
+  version: input.id,
+});
+
+export const createMdKitDocumentRecord = (
+  input: CreateMdKitDocumentRecordInput = {},
+): MdKitDocumentRecord => {
+  const now = input.now ?? createTimestamp();
+  const content = input.content ?? "";
+  const current = {
+    content,
+    updatedAt: now,
+    version: initialVersion,
+  };
+
+  return {
+    current,
+    versions: [
+      createVersionDetail({
+        content,
+        id: initialVersion,
+        label: "Initial",
+        now,
+      }),
+    ],
+  };
+};
+
+export const writeMdKitDocumentRecord = (
+  record: MdKitDocumentRecord,
+  input: WriteMdKitDocumentRecordInput,
+): WriteMdKitDocumentRecordResult => {
+  if (
+    !input.force &&
+    detectMdKitDocumentConflict({
+      baseVersion: input.baseVersion,
+      currentVersion: record.current.version,
+    })
+  ) {
+    return {
+      record,
+      result: {
+        conflict: true,
+        updatedAt: record.current.updatedAt,
+        version: record.current.version,
+      },
+    };
+  }
+
+  const now = input.now ?? createTimestamp();
+  const version = nextVersionToken(record.current.version);
+  const current = {
+    content: input.content,
+    updatedAt: now,
+    version,
+  };
+
+  return {
+    record: {
+      current,
+      versions: [
+        ...record.versions,
+        createVersionDetail({
+          content: input.content,
+          id: version,
+          label: input.label ?? `Version ${version}`,
+          now,
+        }),
+      ],
+    },
+    result: {
+      updatedAt: now,
+      version,
+    },
+  };
+};
+
+export const restoreMdKitDocumentVersion = (
+  record: MdKitDocumentRecord,
+  input: RestoreMdKitDocumentVersionInput,
+): RestoreMdKitDocumentVersionResult => {
+  const restoredVersion = record.versions.find(
+    (version) => version.id === input.versionId,
+  );
+
+  if (!restoredVersion) {
+    throw new Error(`Version not found: ${input.versionId}`);
+  }
+
+  const written = writeMdKitDocumentRecord(record, {
+    baseVersion: record.current.version,
+    content: restoredVersion.content,
+    force: true,
+    label: input.label ?? `Restore ${restoredVersion.id}`,
+    now: input.now,
+  });
+
+  return {
+    ...written,
+    restoredVersion,
+  };
+};

package/src/core/index.ts

@@ -0,0 +1,33 @@
+export {
+  createMdKitDocumentRecord,
+  detectMdKitDocumentConflict,
+  normalizeMdKitVersionToken,
+  restoreMdKitDocumentVersion,
+  writeMdKitDocumentRecord,
+} from "./documentEngine.js";
+export {
+  CheckpointPolicy,
+  measureMdKitEditDistance,
+} from "./checkpointPolicy.js";
+
+export type {
+  CreateMdKitDocumentRecordInput,
+  MdKitDocumentRecord,
+  RestoreMdKitDocumentVersionInput,
+  RestoreMdKitDocumentVersionResult,
+  WriteMdKitDocumentRecordInput,
+  WriteMdKitDocumentRecordResult,
+} from "./documentEngine.js";
+export type {
+  MdKitCheckpointPolicy,
+  MdKitCheckpointPolicyInput,
+  MdKitSmartCheckpointPolicyOptions,
+} from "./checkpointPolicy.js";
+export type {
+  MdKitDocumentSnapshot,
+  MdKitDocumentVersionDetail,
+  MdKitDocumentVersionSummary,
+  MdKitDocumentVersionToken,
+  MdKitDocumentWriteInput,
+  MdKitDocumentWriteResult,
+} from "../document/documentTypes.js";

package/src/document/MdKitConflictPanel.tsx

@@ -0,0 +1,129 @@
+import { useState } from "react";
+import type { MdKitDocumentController } from "./useMdKitDocument";
+import { joinClassNames } from "../ui/joinClassNames";
+
+export type MdKitConflictPanelProps = {
+  className?: string;
+  document: MdKitDocumentController;
+  title?: string;
+};
+
+/**
+ * Base panel for resolving a save conflict. Previews remote and local content
+ * and keeps one side. Renders `null` when the document has no conflict.
+ */
+export const MdKitConflictPanel = ({
+  className,
+  document,
+  title = "Document conflict",
+}: MdKitConflictPanelProps) => {
+  const [pendingAction, setPendingAction] = useState<string | null>(null);
+
+  const [activePreview, setActivePreview] = useState<"local" | "remote">(
+    "remote",
+  );
+
+  if (!document.conflict) {
+    return null;
+  }
+
+  const runAction = async (name: string, action: () => Promise<unknown>) => {
+    setPendingAction(name);
+
+    try {
+      await action();
+    } finally {
+      setPendingAction(null);
+    }
+  };
+
+  const isBusy = pendingAction !== null || document.saveStatus === "saving";
+  const conflictDetails = document.conflictDetails;
+
+  const previewOptions = [
+    {
+      id: "remote" as const,
+      label: "Keep remote",
+      value:
+        conflictDetails?.remoteContent ??
+        "Remote content preview is not available. Keep remote will still reload the latest canonical document.",
+    },
+    {
+      id: "local" as const,
+      label: "Keep local",
+      value: conflictDetails?.localContent ?? document.value,
+    },
+  ];
+
+  const activePreviewOption =
+    previewOptions.find((option) => option.id === activePreview) ??
+    previewOptions[0];
+
+  return (
+    <section className={joinClassNames("mp-lb-mdkit-conflict-panel", className)}>
+      <div className="mp-lb-mdkit-conflict-panel-content">
+        <h2>{title}</h2>
+        <p>
+          Remote changes conflict with local edits. Choose the remote document,
+          or keep your local document by overwriting the remote copy.
+        </p>
+        {document.error ? (
+          <p className="mp-lb-mdkit-conflict-panel-error">{document.error}</p>
+        ) : null}
+        {conflictDetails ? (
+          <p className="mp-lb-mdkit-conflict-panel-meta">
+            Remote version {String(conflictDetails.remoteVersion ?? "none")}
+            {conflictDetails.remoteUpdatedAt
+              ? ` saved ${new Date(
+                  conflictDetails.remoteUpdatedAt,
+                ).toLocaleTimeString()}`
+              : ""}
+          </p>
+        ) : null}
+      </div>
+      <div className="mp-lb-mdkit-conflict-panel-preview">
+        <div className="mp-lb-mdkit-conflict-panel-tabs" role="tablist">
+          {previewOptions.map((option) => (
+            <button
+              key={option.id}
+              type="button"
+              aria-selected={activePreviewOption.id === option.id}
+              className={
+                activePreviewOption.id === option.id
+                  ? "mp-lb-mdkit-conflict-panel-tab mp-lb-mdkit-conflict-panel-tab-active"
+                  : "mp-lb-mdkit-conflict-panel-tab"
+              }
+              role="tab"
+              onClick={() => setActivePreview(option.id)}
+            >
+              {option.label}
+            </button>
+          ))}
+        </div>
+        <textarea
+          aria-label={`${activePreviewOption.label} conflict content`}
+          readOnly
+          value={activePreviewOption.value}
+        />
+      </div>
+      <div className="mp-lb-mdkit-conflict-panel-action-row">
+        <button
+          type="button"
+          className="mp-lb-mdkit-panel-secondary-action"
+          disabled={isBusy}
+          onClick={() => void runAction("reload", document.resync)}
+        >
+          {pendingAction === "reload" ? "Keeping remote..." : "Keep remote"}
+        </button>
+        <button
+          type="button"
+          className="mp-lb-mdkit-panel-secondary-action"
+          disabled={isBusy}
+          onClick={() => void runAction("overwrite", document.forceSave)}
+        >
+          {pendingAction === "overwrite" ? "Keeping local..." : "Keep local"}
+        </button>
+      </div>
+    </section>
+  );
+};

package/src/document/MdKitDocumentToolbar.tsx

@@ -0,0 +1,141 @@
+import { useState } from "react";
+import type { MdKitCollaborationSession } from "./documentTypes";
+import type { MdKitDocumentController } from "./useMdKitDocument";
+import type { MdKitDocumentVersionsController } from "../versioning/useMdKitDocumentVersions";
+import { joinClassNames } from "../ui/joinClassNames";
+
+export type MdKitDocumentToolbarProps = {
+  className?: string;
+  collaboration?: MdKitCollaborationSession | null;
+  document: MdKitDocumentController;
+  onOpenConflict?: () => Promise<void> | void;
+  onOpenVersionHistory?: () => Promise<void> | void;
+  showConflictActions?: boolean;
+  versions?: MdKitDocumentVersionsController | null;
+};
+
+const formatUpdatedAt = (updatedAt: string | null) => {
+  if (!updatedAt) {
+    return "Never saved";
+  }
+
+  return `Saved ${new Date(updatedAt).toLocaleTimeString()}`;
+};
+
+/**
+ * Unstyled workflow controls for a connected document: save/collaboration
+ * status plus entry points for version history and conflict resolution. Starter
+ * UI — drop it for your own controls when it doesn't fit.
+ */
+export const MdKitDocumentToolbar = ({
+  className,
+  collaboration,
+  document,
+  onOpenConflict,
+  onOpenVersionHistory,
+  showConflictActions = false,
+  versions,
+}: MdKitDocumentToolbarProps) => {
+  const [pendingAction, setPendingAction] = useState<string | null>(null);
+  const otherCollaboratorCount = collaboration?.otherParticipants.length ?? 0;
+
+  const runAction = async (name: string, action: () => Promise<unknown>) => {
+    setPendingAction(name);
+
+    try {
+      await action();
+    } finally {
+      setPendingAction(null);
+    }
+  };
+
+  const hasVersionHistory = versions?.hasVersioning ?? false;
+  const hasActiveCollaborators = collaboration?.isCollaborating ?? false;
+  const isBusy = pendingAction !== null || document.saveStatus === "saving";
+
+  const status = document.conflict
+    ? "Conflict"
+    : document.isLoading
+      ? "Loading"
+      : document.saveStatus === "saving"
+        ? "Saving"
+        : document.saveStatus === "pending"
+          ? "Autosave pending"
+          : document.isDirty
+            ? "Unsaved changes"
+            : document.saveStatus === "saved"
+              ? "Saved"
+              : "Idle";
+
+  return (
+    <div
+      className={joinClassNames("mp-lb-mdkit-document-toolbar", className)}
+      data-conflict={document.conflict ? "true" : undefined}
+      data-dirty={document.isDirty ? "true" : undefined}
+      data-save-status={document.saveStatus}
+      data-status={status.toLowerCase().replace(/\s+/g, "-")}
+    >
+      <div className="mp-lb-mdkit-document-toolbar-status">
+        <strong>{status}</strong>
+        <span>{formatUpdatedAt(document.updatedAt)}</span>
+        {hasActiveCollaborators ? (
+          <span>{otherCollaboratorCount + 1} collaborators</span>
+        ) : null}
+      </div>
+      {document.error && !document.conflict ? (
+        <div className="mp-lb-mdkit-document-toolbar-error">{document.error}</div>
+      ) : null}
+      <div className="mp-lb-mdkit-document-toolbar-actions">
+        {hasVersionHistory && onOpenVersionHistory ? (
+          <button
+            type="button"
+            disabled={isBusy || document.conflict || versions?.isLoading}
+            onClick={() =>
+              void runAction("versions", async () => {
+                await versions?.refresh();
+                await onOpenVersionHistory();
+              })
+            }
+          >
+            {versions?.isLoading
+              ? "Loading versions..."
+              : `Version ${String(document.version ?? "none")}`}
+          </button>
+        ) : null}
+        {document.conflict && onOpenConflict ? (
+          <button
+            type="button"
+            className="mp-lb-mdkit-document-toolbar-conflict-trigger"
+            disabled={isBusy}
+            onClick={() =>
+              void runAction("conflict", async () => {
+                await onOpenConflict();
+              })
+            }
+          >
+            Resolve conflict
+          </button>
+        ) : null}
+      </div>
+      {document.conflict && showConflictActions ? (
+        <div className="mp-lb-mdkit-document-toolbar-conflict">
+          <span>Remote changes conflict with local edits.</span>
+          <button
+            type="button"
+            disabled={isBusy}
+            onClick={() => void runAction("reload", document.resync)}
+          >
+            Keep remote
+          </button>
+          <button
+            type="button"
+            disabled={isBusy}
+            onClick={() => void runAction("overwrite", document.forceSave)}
+          >
+            Keep local
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+};

package/src/document/documentTypes.ts

@@ -0,0 +1,89 @@
+import type { HocuspocusProvider } from "@hocuspocus/provider";
+import type * as Y from "yjs";
+
+export type MdKitDocumentVersionToken = string | number | null;
+
+export type MdKitDocumentSnapshot = {
+  content: string;
+  version: MdKitDocumentVersionToken;
+  updatedAt?: string | null;
+};
+
+export type MdKitDocumentWriteInput = {
+  documentId: string;
+  content: string;
+  baseVersion: MdKitDocumentVersionToken;
+  force?: boolean;
+};
+
+export type MdKitDocumentWriteResult =
+  | {
+      version: MdKitDocumentVersionToken;
+      updatedAt?: string | null;
+    }
+  | {
+      conflict: true;
+      version?: MdKitDocumentVersionToken;
+      updatedAt?: string | null;
+    };
+
+export type MdKitDocumentVersionSummary = {
+  id: string;
+  label?: string;
+  createdAt: string;
+  authorLabel?: string | null;
+  updatedAt?: string | null;
+  version?: MdKitDocumentVersionToken;
+};
+
+export type MdKitDocumentVersionDetail = MdKitDocumentVersionSummary & {
+  content: string;
+};
+
+/**
+ * Storage contract the document hooks talk to. Implement it over tRPC, REST, or
+ * anything else; only `readDocument`/`writeDocument` are required, the
+ * checkpoint methods are optional and enable version-history UI.
+ */
+export interface MdKitDocumentAdapter {
+  readDocument(documentId: string): Promise<MdKitDocumentSnapshot>;
+  writeDocument(
+    input: MdKitDocumentWriteInput,
+  ): Promise<MdKitDocumentWriteResult>;
+  resyncDocument?(documentId: string): Promise<MdKitDocumentSnapshot>;
+  listDocumentVersions?(
+    documentId: string,
+  ): Promise<MdKitDocumentVersionSummary[]>;
+  readDocumentVersion?(input: {
+    documentId: string;
+    versionId: string;
+  }): Promise<MdKitDocumentVersionDetail | null>;
+}
+
+export type MdKitCollaborationStatus =
+  | "connecting"
+  | "connected"
+  | "disconnected";
+
+export type MdKitCollaborationParticipant = {
+  id: string;
+  name: string;
+  color?: string;
+  imageUrl?: string;
+};
+
+export type MdKitCollaborationPresence = MdKitCollaborationParticipant & {
+  clientId: number;
+  isLocal: boolean;
+};
+
+export type MdKitCollaborationSession = {
+  collaborator: MdKitCollaborationParticipant;
+  document: Y.Doc;
+  isCollaborating: boolean;
+  otherParticipants: MdKitCollaborationPresence[];
+  participants: MdKitCollaborationPresence[];
+  provider: HocuspocusProvider | null;
+  roomName: string;
+  status: MdKitCollaborationStatus;
+};