@mp-lb/mdkit 0.0.1-main.2.1

package/docs/index.md

@@ -0,0 +1,244 @@
+# Quick Start
+
+Markdown Editor Kit is a React package for teams that need more than a bare
+markdown editor widget. It starts with a controlled markdown editor that behaves
+like a textarea, then adds autosave, version history, conflict handling, and
+collaboration through adapters.
+
+```bash
+pnpm add @mp-lb/mdkit
+```
+
+Import the stylesheet once if you want reset-resistant markdown defaults and
+generic fallback styling for the base panels:
+
+```ts
+import "@mp-lb/mdkit/styles.css";
+```
+
+See [Styling](./styling.md) for reset handling, dark mode, fonts, sizing, and
+custom panel styles.
+
+## Basic Editor
+
+`MdKitEditor` is the textarea-like entry point. It has no persistence, no
+version history, and no collaboration. You own the `value` and `onChange` state.
+
+```tsx
+import { useState } from "react";
+import { MdKitEditor } from "@mp-lb/mdkit";
+import "@mp-lb/mdkit/styles.css";
+
+export function MarkdownEditorExample() {
+  const [markdown, setMarkdown] = useState("# Hello markdown");
+
+  return <MdKitEditor value={markdown} onChange={setMarkdown} />;
+}
+```
+
+Use this when you want a local editor, a form field, or a debug surface.
+
+## Connected Editor
+
+The connected workflow combines:
+
+- `useMdKitDocument` for loading, autosave, dirty state, and conflict detection
+- `useMdKitDocumentVersions` for version browsing and restore
+- `useMdKitCollaboration` for Hocuspocus/Yjs collaboration
+- `MdKitDocumentToolbar`, `VersionHistoryPanel`, and `MdKitConflictPanel` for
+  a complete base-panel UI
+
+The TypeScript-first path is tRPC. REST is also supported for high-compatibility
+backends and non-TypeScript stacks.
+
+### Frontend With tRPC
+
+```tsx
+import { useMemo, useState } from "react";
+import {
+  MdKitConflictPanel,
+  MdKitDocumentToolbar,
+  MdKitEditor,
+  VersionHistoryPanel,
+  useMdKitCollaboration,
+  useMdKitDocument,
+  useMdKitDocumentVersions,
+  type MdKitDocumentVersionDetail,
+} from "@mp-lb/mdkit";
+import {
+  createMdKitTrpcAdapter,
+  createMdKitTrpcClient,
+} from "@mp-lb/mdkit/trpc/client";
+
+const documentId = "docs/example.md";
+
+export function ConnectedMarkdownEditor({
+  apiUrl,
+}: {
+  apiUrl: string;
+}) {
+  const [versionHistoryOpen, setVersionHistoryOpen] = useState(false);
+  const [conflictOpen, setConflictOpen] = useState(false);
+
+  const trpc = useMemo(
+    () => createMdKitTrpcClient({ url: `${apiUrl}/trpc` }),
+    [apiUrl],
+  );
+  const adapter = useMemo(() => createMdKitTrpcAdapter({ client: trpc }), [trpc]);
+
+  const document = useMdKitDocument({ adapter, documentId });
+  const versions = useMdKitDocumentVersions({ adapter, documentId });
+  const collaboration = useMdKitCollaboration({
+    collaborator: { id: "user-1", name: "Ada" },
+    documentId,
+    endpoint: `${apiUrl.replace(/^http/, "ws")}/collaboration`,
+  });
+
+  const restoreVersion = async (version: MdKitDocumentVersionDetail) => {
+    await trpc.restoreDocumentVersion.mutate({
+      documentId,
+      versionId: version.id,
+    });
+    await document.resync();
+    await versions.refresh();
+  };
+
+  return (
+    <>
+      <MdKitDocumentToolbar
+        collaboration={collaboration}
+        document={document}
+        versions={versions}
+        onOpenConflict={() => setConflictOpen(true)}
+        onOpenVersionHistory={() => setVersionHistoryOpen(true)}
+      />
+
+      <MdKitEditor
+        collaboration={collaboration}
+        fillHeight
+        readOnly={document.conflict}
+        value={document.value}
+        onChange={document.setContent}
+        onFocusChange={document.setFocused}
+      />
+
+      {versionHistoryOpen ? (
+        <div role="dialog" aria-label="Version history">
+          <VersionHistoryPanel
+            controller={versions}
+            onRestoreVersion={restoreVersion}
+          />
+        </div>
+      ) : null}
+
+      {document.conflict && conflictOpen ? (
+        <div role="dialog" aria-label="Resolve conflict">
+          <MdKitConflictPanel document={document} />
+        </div>
+      ) : null}
+    </>
+  );
+}
+```
+
+The modal shells above are intentionally plain. Put `VersionHistoryPanel` and
+`MdKitConflictPanel` inside your own dialog, drawer, side panel, or editor
+replacement view. If your app uses shadcn/ui, see [Shadcn Plugin](./shadcn.md)
+for the source-installed workflow component.
+
+### Backend With Fastify And tRPC
+
+The backend only needs a store object. Replace `createYourDocumentStore()` with
+Postgres, MongoDB, Redis, files, or any other durable storage.
+
+```ts
+import cors from "@fastify/cors";
+import websocket from "@fastify/websocket";
+import { Database } from "@hocuspocus/extension-database";
+import { Server } from "@hocuspocus/server";
+import { fastifyTRPCPlugin } from "@trpc/server/adapters/fastify";
+import Fastify from "fastify";
+import { createMdKitTrpcRouter } from "@mp-lb/mdkit/trpc/server";
+
+const app = Fastify();
+const store = createYourDocumentStore();
+
+const collaboration = Server.configure({
+  extensions: [
+    new Database({
+      fetch: ({ documentName }) => store.readCollaborationState(documentName),
+      store: ({ documentName, state }) =>
+        store.writeCollaborationState(documentName, state),
+    }),
+  ],
+});
+
+await app.register(cors, { origin: true });
+await app.register(websocket);
+
+await app.register(fastifyTRPCPlugin, {
+  prefix: "/trpc",
+  trpcOptions: {
+    router: createMdKitTrpcRouter(store),
+  },
+});
+
+app.get("/collaboration", { websocket: true }, (socket, request) => {
+  collaboration.handleConnection(socket, request.raw, {});
+});
+
+await app.listen({ port: Number(process.env.PORT ?? 4312) });
+```
+
+The store object implements `MdKitTransportStore`: current document reads and
+writes, version list/read/restore, and optional collaboration state storage. See
+[API Reference](./api.md#transport-helpers).
+
+### REST Compatibility
+
+If you want REST instead of tRPC, use the REST frontend adapter:
+
+```tsx
+import { createMdKitRestAdapter } from "@mp-lb/mdkit";
+
+const adapter = createMdKitRestAdapter({
+  baseUrl: "https://api.example.com/mdkit",
+});
+```
+
+On Fastify, register the matching REST endpoints:
+
+```ts
+import { registerMdKitFastify } from "@mp-lb/mdkit/fastify";
+
+await registerMdKitFastify(app, {
+  prefix: "/mdkit",
+  store,
+});
+```
+
+The mdkit testbench uses this split deliberately: `Connected (panels)` uses the
+REST adapter, while `Connected (shadcn)` uses the tRPC adapter.
+
+## Questions
+
+### Do the backends need to know about each other?
+
+Storage, version history, and collaboration can stay separate. Storage stores
+the current markdown snapshot. Version history stores markdown snapshots.
+Hocuspocus stores live Yjs collaboration state. They only need glue if your
+product wants collaborative edits to automatically become saved markdown
+versions.
+
+### Does mdkit require tRPC or these exact REST endpoints?
+
+No. The frontend hooks only need an `MdKitDocumentAdapter`. You can use REST,
+tRPC, GraphQL, server actions, IndexedDB, Rails, Go, or anything else as long as
+your adapter returns the documented shapes.
+
+### Do I have to use the base panels?
+
+No. The base panels are the fastest way to get a complete workflow working in
+any React app. If you want a fully custom UI, use `useMdKitDocument`,
+`useMdKitDocumentVersions`, and `useMdKitCollaboration` directly and render your
+own controls.

package/docs/shadcn.md

@@ -0,0 +1,118 @@
+# Shadcn Plugin
+
+The core npm package is design-system agnostic. It exports the editor, hooks,
+base panels, types, and generic CSS. It does not export shadcn components at
+runtime.
+
+The shadcn path should be a registry/plugin item. Installing it copies editable
+source into your app, and that source imports your app's own shadcn primitives:
+
+```tsx
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { Textarea } from "@/components/ui/textarea";
+```
+
+That means the workflow component can own polished app UI: toolbar, version
+history dialog, conflict dialog, tabs, buttons, and layout. The underlying state
+still comes from the mdkit hooks. The recommended transport for this path is the
+tRPC adapter from `@mp-lb/mdkit/trpc/client`.
+
+## Intended Shape
+
+The installed component should be one app-local workflow component that you
+render next to `MdKitEditor`.
+
+```tsx
+import {
+  MdKitEditor,
+  useMdKitCollaboration,
+  useMdKitDocument,
+  useMdKitDocumentVersions,
+} from "@mp-lb/mdkit";
+import {
+  createMdKitTrpcAdapter,
+  createMdKitTrpcClient,
+} from "@mp-lb/mdkit/trpc/client";
+import { MdKitConnectedWorkflow } from "@/components/mdkit/mdkit-connected-workflow";
+
+export function EditorScreen() {
+  const client = createMdKitTrpcClient({ url: "/trpc" });
+  const adapter = createMdKitTrpcAdapter({ client });
+  const document = useMdKitDocument({ adapter, documentId });
+  const versions = useMdKitDocumentVersions({ adapter, documentId });
+  const collaboration = useMdKitCollaboration({
+    collaborator,
+    documentId,
+    endpoint: hocuspocusEndpoint,
+  });
+  const restoreVersion = async (version) => {
+    await client.restoreDocumentVersion.mutate({
+      documentId,
+      versionId: version.id,
+    });
+    await document.resync();
+    await versions.refresh();
+  };
+
+  return (
+    <MdKitConnectedWorkflow
+      collaboration={collaboration}
+      document={document}
+      versions={versions}
+      onRestoreVersion={restoreVersion}
+    >
+      <MdKitEditor
+        collaboration={collaboration}
+        readOnly={document.conflict}
+        value={document.value}
+        onChange={document.setContent}
+        onFocusChange={document.setFocused}
+      />
+    </MdKitConnectedWorkflow>
+  );
+}
+```
+
+The shadcn component is deliberately source-installed instead of imported from
+the npm package. That is how shadcn is designed to work: the code lives in your
+app, uses your aliases, and can be edited like any other local component.
+
+## Why Not A Runtime Export?
+
+mdkit should not:
+
+- bundle copies of shadcn primitives
+- depend on shadcn as a package
+- ask you to pass a map of local `Button`, `Dialog`, or `Tabs` components into
+  mdkit
+- ship Tailwind-only wrappers from the npm package and hope your build scans
+  external package source
+
+The npm package stays focused on the durable logic. The registry item owns the
+app-local shadcn composition.
+
+## Fallback Path
+
+If you do not use shadcn, use the base panels from the npm package:
+
+- `MdKitDocumentToolbar`
+- `VersionHistoryPanel`
+- `MdKitConflictPanel`
+
+They render plain semantic HTML with stable `mdkit-*` classes. Import
+`@mp-lb/mdkit/styles.css` for generic fallback styling, or
+replace the CSS entirely. See [Styling](./styling.md#component-styling).
+
+## Status
+
+The mdkit testbench currently contains the reference shadcn workflow component.
+It is the target shape for the future registry/plugin item. Until that registry
+item exists, treat the base panels as the supported published path.

package/docs/styling.md

@@ -0,0 +1,247 @@
+# Styling
+
+`MdKitEditor` can render without package CSS, but most applications should
+import the stylesheet once. It gives the editor a reset-resistant markdown
+baseline and exposes CSS variables for theme changes.
+
+```ts
+import "@mp-lb/mdkit/styles.css";
+```
+
+Without this stylesheet, the editor still works, but headings, lists,
+blockquotes, code blocks, spacing, and focus areas are left to your app's CSS.
+
+## CSS Resets
+
+Many app frameworks include CSS resets. Tailwind Preflight, for example, removes
+default margins and list styling. The package stylesheet restores markdown
+editor defaults under `.mdkit-markdown-editor`, including:
+
+- heading sizes and spacing
+- paragraph spacing
+- unordered and ordered list markers
+- compact list item spacing
+- inline code and code block styling
+- blockquote styling
+- link color
+- full-width editor layout
+
+Import the stylesheet after global reset styles when possible:
+
+```ts
+import "./app.css";
+import "@mp-lb/mdkit/styles.css";
+```
+
+If your bundler or framework controls CSS order differently, make sure the
+mdkit stylesheet is not overridden by a later broad reset such as
+`ul { list-style: none; }`.
+
+## Default Styling
+
+The simplest setup is:
+
+```tsx
+import { MdKitEditor } from "@mp-lb/mdkit";
+import "@mp-lb/mdkit/styles.css";
+
+export function Editor({ markdown, setMarkdown }) {
+  return <MdKitEditor value={markdown} onChange={setMarkdown} />;
+}
+```
+
+The editor fills the available width by default. Use `fillHeight` only when you
+want the editor to fill its parent's height, own its scroll area, and make the
+empty area below the last line clickable.
+
+```tsx
+<MdKitEditor fillHeight value={markdown} onChange={setMarkdown} />
+```
+
+## Custom Styling
+
+The package stylesheet is intentionally controlled through CSS variables. You
+can override them with a class:
+
+```css
+.my-markdown-editor {
+  --hsk-background: #ffffff;
+  --hsk-foreground: #172033;
+  --hsk-muted: #eef1f4;
+  --hsk-muted-foreground: #5b6472;
+  --hsk-border: #d8dee8;
+  --hsk-link: #4f46e5;
+  --hsk-font-family: Inter, system-ui, sans-serif;
+  --hsk-font-size: 16px;
+  --hsk-line-height: 1.7;
+  --hsk-surface-padding: 1rem;
+  --hsk-block-gap: 0.75rem;
+  --hsk-list-item-gap: 0.125rem;
+  --hsk-code-background: #eef1f4;
+  --hsk-code-radius: 0.35rem;
+  --hsk-code-block-radius: 0.75rem;
+}
+```
+
+```tsx
+<MdKitEditor
+  className="my-markdown-editor"
+  value={markdown}
+  onChange={setMarkdown}
+/>
+```
+
+You can also pass variables through `style` when the values are generated at
+runtime:
+
+```tsx
+<MdKitEditor
+  style={{
+    "--hsk-font-family": "ui-serif, Georgia, serif",
+    "--hsk-font-size": "18px",
+    "--hsk-line-height": "1.8",
+  }}
+  value={markdown}
+  onChange={setMarkdown}
+/>
+```
+
+See [`MdKitEditorProps`](./api.md#mdkiteditorprops) for the full component
+props.
+
+## Component Styling
+
+Editor styling and workflow component styling are separate.
+
+`MdKitEditor` is styled through CSS variables on `.mdkit-markdown-editor`.
+Workflow panels such as `MdKitDocumentToolbar`, `MdKitConflictPanel`, and
+`VersionHistoryPanel` are intentionally design-system agnostic. They render raw
+semantic markup with stable `mdkit-*` class names. Without this stylesheet they
+are plain HTML; with this stylesheet they get generic fallback styling: square
+corners, one-pixel borders, clear spacing, and basic buttons.
+
+Style them in your app when you want them to match your product:
+
+```css
+.mdkit-document-toolbar {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  border-bottom: 1px solid var(--border);
+  padding: 0.5rem 0;
+}
+
+.mdkit-document-toolbar-status,
+.mdkit-document-toolbar-actions,
+.mdkit-document-toolbar-conflict {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.mdkit-document-toolbar[data-conflict="true"] {
+  color: #991b1b;
+}
+```
+
+The toolbar class hooks are:
+
+- `.mdkit-document-toolbar`
+- `.mdkit-document-toolbar-status`
+- `.mdkit-document-toolbar-actions`
+- `.mdkit-document-toolbar-error`
+- `.mdkit-document-toolbar-conflict`
+
+It also exposes `data-conflict`, `data-dirty`, and `data-save-status`
+attributes for state-based styling.
+
+Version history and conflict panels use the same fallback panel CSS and expose:
+
+- `.mdkit-version-history-panel`
+- `.mdkit-version-history-header`
+- `.mdkit-version-history-list`
+- `.mdkit-version-history-item`
+- `.mdkit-version-history-preview`
+- `.mdkit-conflict-panel`
+- `.mdkit-conflict-panel-content`
+- `.mdkit-conflict-panel-action-row`
+- `.mdkit-panel-primary-action`
+- `.mdkit-panel-secondary-action`
+
+## Theme Helpers
+
+For app code, CSS variables are usually the simplest integration. The package
+also exports theme helpers when you want to store or generate a theme object:
+
+```tsx
+import {
+  MdKitEditor,
+  createMdKitEditorThemeStyle,
+  darkMdKitEditorTheme,
+} from "@mp-lb/mdkit";
+
+const style = createMdKitEditorThemeStyle({
+  ...darkMdKitEditorTheme,
+  fontFamily: "Inter, system-ui, sans-serif",
+  lineHeight: "1.75",
+});
+
+<MdKitEditor style={style} value={markdown} onChange={setMarkdown} />;
+```
+
+Related exports are listed in the [API reference](./api.md#styling).
+
+## Dark Mode
+
+For class-based dark mode, scope variable overrides to your dark selector:
+
+```css
+.my-markdown-editor {
+  --hsk-background: #ffffff;
+  --hsk-foreground: #172033;
+  --hsk-muted: #eef1f4;
+  --hsk-muted-foreground: #5b6472;
+  --hsk-border: #d8dee8;
+  --hsk-link: #4f46e5;
+  --hsk-code-background: #eef1f4;
+}
+
+.dark .my-markdown-editor {
+  --hsk-background: #0b1220;
+  --hsk-foreground: #e5edf7;
+  --hsk-muted: #172033;
+  --hsk-muted-foreground: #94a3b8;
+  --hsk-border: #314158;
+  --hsk-link: #38bdf8;
+  --hsk-code-background: #111827;
+}
+```
+
+Then apply the class normally:
+
+```tsx
+<MdKitEditor
+  className="my-markdown-editor"
+  value={markdown}
+  onChange={setMarkdown}
+/>
+```
+
+You can also switch theme objects in React:
+
+```tsx
+const style = createMdKitEditorThemeStyle(
+  isDark ? darkMdKitEditorTheme : defaultMdKitEditorTheme,
+);
+
+<MdKitEditor style={style} value={markdown} onChange={setMarkdown} />;
+```
+
+## What Not To Customize First
+
+Prefer changing CSS variables before overriding internal selectors like
+`.hsk-tiptap p` or `.hsk-editor-surface`. Direct selector overrides are still an
+escape hatch, but they couple your app to mdkit's internal DOM.
+
+Use `MdKitThemeEditor` for theme builders, documentation, and debug tooling. It
+is not required for normal editor integration.

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@mp-lb/mdkit",
+  "version": "0.0.1-main.2.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "src/styles.css"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./core": {
+      "source": "./src/core/index.ts",
+      "import": "./dist/core/index.js",
+      "types": "./dist/core/index.d.ts"
+    },
+    "./fastify": {
+      "source": "./src/fastify.ts",
+      "import": "./dist/fastify.js",
+      "types": "./dist/fastify.d.ts"
+    },
+    "./trpc": {
+      "source": "./src/trpc.ts",
+      "import": "./dist/trpc.js",
+      "types": "./dist/trpc.d.ts"
+    },
+    "./styles.css": "./src/styles.css",
+    "./trpc/client": {
+      "source": "./src/trpc/client.ts",
+      "import": "./dist/trpc/client.js",
+      "types": "./dist/trpc/client.d.ts"
+    },
+    "./trpc/server": {
+      "source": "./src/trpc/server.ts",
+      "import": "./dist/trpc/server.js",
+      "types": "./dist/trpc/server.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "@trpc/client": "^11.7.1",
+    "@trpc/server": "^11.7.1",
+    "fastify": "^5.1.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@trpc/client": {
+      "optional": true
+    },
+    "@trpc/server": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@hocuspocus/provider": "^2.15.0",
+    "@tiptap/extension-collaboration": "^3.14.0",
+    "@tiptap/extension-collaboration-caret": "^3.14.0",
+    "@tiptap/extension-link": "^3.14.0",
+    "@tiptap/extension-placeholder": "^3.14.0",
+    "@tiptap/markdown": "^3.20.1",
+    "@tiptap/react": "^3.14.0",
+    "@tiptap/starter-kit": "^3.14.0",
+    "lucide-react": "^0.554.0",
+    "yjs": "^13.6.24",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "6.9.1",
+    "@testing-library/react": "16.3.2",
+    "@trpc/client": "^11.7.1",
+    "@trpc/server": "^11.7.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "dotenv": "^17.4.2",
+    "dotenv-expand": "^13.0.0",
+    "fastify": "^5.1.0",
+    "jsdom": "29.1.1",
+    "vite": "7.2.4",
+    "vitepress": "^1.6.4",
+    "vitest": "4.1.5"
+  },
+  "scripts": {
+    "dev": "tsc --watch --project tsconfig.json",
+    "build": "tsc --project tsconfig.json",
+    "docs:build": "vitepress build docs",
+    "docs:dev": "node scripts/load-docs-env.mjs dev",
+    "docs:preview": "node scripts/load-docs-env.mjs preview",
+    "release:check": "pnpm typecheck && pnpm test && pnpm build && pnpm docs:build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  }
+}