@mp-lb/mdkit 0.3.1 → 0.3.3

package/docs/plain-text.md

@@ -1,131 +0,0 @@
-# Plain Text Editors
-
-MDKit's connected workflow is not limited to `MdKitEditor`. The document hooks
-and backend adapters work with serialized text, so you can bring a plain text,
-code, JSON, or custom text editor and still use the same storage, autosave,
-checkpoint history, restore, and conflict handling.
-
-The one major exception is collaboration. Collaboration is currently a
-markdown/Tiptap capability because it depends on Yjs, ProseMirror, and the
-Tiptap collaboration extensions.
-
-## What Works
-
-Any editor can plug into the connected workflow if it behaves like a controlled
-text input:
-
-```tsx
-type TextEditorProps = {
-  value: string;
-  onChange(value: string): void;
-  onFocusChange?(focused: boolean): void;
-  readOnly?: boolean;
-};
-```
-
-That is enough for:
-
-- loading the current document
-- autosave
-- dirty state
-- conflict detection
-- force save
-- remote resync
-- checkpoint history
-- checkpoint restore
-
-The editor does not need to know about MDKit internals. It only needs to receive
-`document.value` and call `document.setContent`.
-
-## Example
-
-```tsx
-import {
-  MdKitConflictPanel,
-  MdKitDocumentToolbar,
-  VersionHistoryPanel,
-  useMdKitDocument,
-  useMdKitDocumentVersions,
-  type MdKitDocumentAdapter,
-} from "@mp-lb/mdkit";
-
-function PlainTextDocument({
-  adapter,
-  documentId,
-}: {
-  adapter: MdKitDocumentAdapter;
-  documentId: string;
-}) {
-  const document = useMdKitDocument({
-    adapter,
-    debounceMs: 1000,
-    documentId,
-  });
-  const versions = useMdKitDocumentVersions({ adapter, documentId });
-
-  return (
-    <>
-      <MdKitDocumentToolbar document={document} versions={versions} />
-
-      <textarea
-        readOnly={document.conflict}
-        value={document.value}
-        onBlur={() => document.setFocused(false)}
-        onChange={(event) => document.setContent(event.currentTarget.value)}
-        onFocus={() => document.setFocused(true)}
-      />
-
-      <MdKitConflictPanel document={document} />
-      <VersionHistoryPanel controller={versions} />
-    </>
-  );
-}
-```
-
-Use the same backend adapter you would use for markdown. The document content is
-still just `content: string`.
-
-## Backend Shape
-
-You do not need a separate backend for plain text documents. A single MDKit
-backend can expose:
-
-- document read/write
-- checkpoint list/read/restore
-- optional collaboration websocket routes
-- optional collaboration state persistence
-
-Plain text editors use the document and checkpoint APIs. Markdown collaborative
-editors additionally use the collaboration websocket and Yjs persistence.
-
-The underlying database layout is application-owned. It is reasonable to store
-markdown and plain text documents in the same documents table, or in separate
-tables if your product needs that. MDKit only requires a stable `documentId`,
-`content`, and an opaque revision token.
-
-## Collaboration Boundary
-
-Do not pass `useMdKitCollaboration` to a plain text editor. The current
-collaboration adapter is for `MdKitEditor` because that editor knows how to bind
-Tiptap to a Yjs document and render remote cursors.
-
-For plain text documents:
-
-- keep using `useMdKitDocument`
-- omit `useMdKitCollaboration`
-- omit collaboration UI
-- rely on optimistic conflicts and resync for multi-client safety
-
-If MDKit later adds a collaboration-capable CodeMirror, Monaco, or textarea
-adapter, that should be a new editor-specific capability. The generic text
-workflow does not need to change.
-
-## Testbench
-
-The testbench includes a connected stack named
-`Storage + checkpoints (plain text)`. It reuses the same checkpoints backend as
-the markdown stack, stores content under `docs/plain-text.txt`, and renders a
-controlled textarea instead of `MdKitEditor`.
-
-Use it to verify that plain text can autosave, create checkpoints, restore
-history, and avoid collaboration UI.

package/docs/rest.md

@@ -1,98 +0,0 @@
-# REST Backend
-
-Use REST when you want the quick-start frontend without tRPC. The editor,
-toolbar, conflict panel, checkpoint panel, and collaboration hook are the same.
-The difference is the backend transport.
-
-If your backend uses Fastify, mdkit can register the REST routes for you. If you
-use another server framework, implement the same endpoint shape shown below.
-
-## Frontend Wiring
-
-Use the connected frontend from the [Quick Start](./index.md#frontend-with-trpc).
-Keep the same component structure, but change the transport-specific pieces:
-
-- replace the tRPC adapter with `createMdKitRestAdapter`, using a REST base URL
-  such as `${apiUrl}/mdkit`
-- point collaboration at `${apiUrl.replace(/^http/, "ws")}/mdkit/collaboration`
-- point the restore callback at `POST /mdkit/versions/:versionId/restore`
-
-`createMdKitRestAdapter` covers current-document reads, writes, resync,
-checkpoint listing, and checkpoint detail reads. Restore is separate because it
-is not part of `MdKitDocumentAdapter` yet.
-
-## Fastify Backend
-
-```ts
-import cors from "@fastify/cors";
-import websocket from "@fastify/websocket";
-import { Database } from "@hocuspocus/extension-database";
-import { Server } from "@hocuspocus/server";
-import Fastify from "fastify";
-import { CheckpointPolicy } from "@mp-lb/mdkit/core";
-import {
-  createMdKitBackend,
-  type MdKitBackendStore,
-} from "@mp-lb/mdkit/server";
-import { registerMdKitFastify } from "@mp-lb/mdkit/fastify";
-
-const app = Fastify();
-const store: MdKitBackendStore = createYourDocumentStore();
-
-const mdkit = createMdKitBackend({
-  store,
-  checkpointPolicy: CheckpointPolicy.smart(),
-});
-
-const collaboration = Server.configure({
-  extensions: [
-    new Database({
-      fetch: ({ documentName }) => mdkit.readCollaborationState(documentName),
-      store: ({ documentName, state }) =>
-        mdkit.writeCollaborationState(documentName, state),
-    }),
-  ],
-});
-
-await app.register(cors, { origin: true });
-await app.register(websocket);
-
-await registerMdKitFastify(app, {
-  prefix: "/mdkit",
-  store: mdkit,
-});
-
-app.get("/mdkit/collaboration", { websocket: true }, (socket, request) => {
-  collaboration.handleConnection(socket, request.raw, {});
-});
-
-app.addHook("onClose", async () => {
-  await collaboration.destroy();
-});
-
-await app.listen({ port: Number(process.env.PORT ?? 4312) });
-```
-
-The store object is still your application boundary. It connects mdkit's REST
-routes to your database and owns metadata, permissions, tenancy, and durable
-Yjs storage. Mdkit applies the checkpoint policy and calls your store's
-checkpoint creation method when needed. See
-[`createMdKitBackend`](./api.md#createmdkitbackend).
-
-## Endpoint Shape
-
-If you are not using Fastify, implement these routes with your server framework:
-
-| Method | Path | Behavior |
-| --- | --- | --- |
-| `GET` | `/mdkit/documents?documentId=...` | Read the current document. |
-| `PUT` | `/mdkit/documents?documentId=...` | Write current content with `baseVersion`. |
-| `POST` | `/mdkit/documents/resync?documentId=...` | Force a fresh current-document read. |
-| `GET` | `/mdkit/versions?documentId=...` | List checkpoints as `{ versions }`. |
-| `GET` | `/mdkit/versions/:versionId?documentId=...` | Read one checkpoint. |
-| `POST` | `/mdkit/versions/:versionId/restore?documentId=...` | Restore one checkpoint. |
-
-The REST frontend adapter expects the same JSON shapes as
-`MdKitDocumentAdapter`. Write conflicts should return the conflict body with
-HTTP `409`; the adapter treats that as a successful mdkit response so the editor
-can show the conflict workflow.

package/docs/shadcn.md

@@ -1,125 +0,0 @@
-# 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, checkpoint
-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,
-    debounceMs: 1000,
-    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 `mp-lb-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.