@kungal/editor-core 0.2.0

package/README.md

@@ -0,0 +1,100 @@
+# @kungal/editor-core
+
+The **framework-agnostic core** of KunEditor. Pure TypeScript — no Vue, no
+React. It owns the Milkdown/ProseMirror mechanism (nodes, marks, input rules,
+keymaps, markdown (de)serialization, plugin wiring) and exposes it through
+small **adapter contracts** the host fills in.
+
+Ships dual ESM/CJS with type declarations.
+
+## The one idea
+
+> **The editor ships the mechanism; the host injects the policy.**
+
+The editor does not know where an image upload goes, how an `@mention` resolves
+to a user, what stickers exist, or how a toast is shown. Those are per-host
+*policy*, passed in as adapters:
+
+```ts
+import type { KunEditorAdapters } from '@kungal/editor-core'
+
+const adapters: KunEditorAdapters = {
+  uploadImage: (file) => api.uploadTopicImage(file),   // → Promise<url>
+  searchMentionUsers: (q) => oauth.searchUsers(q),     // → Promise<MentionUser[]>
+  notify: (msg, level) => toast(msg, level),
+}
+```
+
+Omit an adapter and the matching plugin simply isn't wired — that is how the
+"image-free" editor (galgame 简介) is expressed: no `uploadImage`, no upload/
+paste/sticker paths, no special-casing.
+
+## What's here today
+
+| Export | Purpose |
+| --- | --- |
+| `KunEditorAdapters` | the policy bundle a host passes (`uploadImage` / `searchMentionUsers` / `stickerSource` / `notify`) |
+| `UploadImage`, `SearchMentionUsers`, `StickerSource`, `Notify` | the individual adapter function types |
+| `MentionUser`, `StickerItem`, `StickerPack` | the data shapes crossing the boundary |
+| `KunEditorFeatures`, `KunEditorLocale` | feature toggles + UI language |
+| `MENTION_SCHEME` (`kungal-user:`) | the markdown link scheme shared with the server |
+
+The Milkdown plugin ports land incrementally — see
+[`../../docs/architecture.md`](../../docs/architecture.md) § migration.
+
+## The `/preset` subpath — the Milkdown plugins
+
+The main entry above is deliberately **light**: types + `MENTION_SCHEME`, zero
+runtime deps, so the server can import the `@mention` scheme without installing
+Milkdown. The actual Milkdown plugins live behind a separate subpath that pulls
+in the peers:
+
+```ts
+import { createKunEditorPlugins } from '@kungal/editor-core/preset'
+
+// The single call the render layer makes — assembles the Milkdown baseline
+// (commonmark/gfm/history/listener/clipboard/indent/trailing) with the KunEditor
+// plugins, wiring each optional one only when its feature/adapter is present.
+editor.use(createKunEditorPlugins(adapters, features, { locale: 'zh-cn' }))
+```
+
+Landed so far — each a **factory**, never a module-level singleton bound to one
+host:
+
+**P1** (pure — no host policy):
+
+| Export (from `/preset`) | Syntax / behaviour |
+| --- | --- |
+| `createSpoilerPlugin()` | `\|\|hidden\|\|` inline node + `$remark` round-trip |
+| `createKatexPlugins()` | inline `$…$` and block `$$…$$` LaTeX (KaTeX) |
+| `createCodeBlockPlugins(opts)` | CodeMirror code block: theme, languages, toolbar, `latex` preview |
+| `createStopLinkPlugin()` | Space clears the active link mark |
+
+**P2** (adapter-driven):
+
+| Export (from `/preset`) | Syntax / behaviour | Host policy |
+| --- | --- | --- |
+| `createUploadPlugin(uploadImage, opts)` | paste / drop / toolbar image upload | `uploadImage(file) → url` (+ optional `notify`) |
+| `createMentionPlugin()` | `[@name](kungal-user:id)` mention atom | schema is pure; the `@` dropdown (P3) uses `searchMentionUsers` |
+| `createQuotePlugin()` | `[label](kungal-reply:refId)` inline reference atom | host inserts via `insertQuoteCommand({ refId, label })` |
+
+Stickers have **no core plugin** — a sticker is a plain image node, so the picker
+is a render-layer view (P3) that reads the `stickerSource` adapter and inserts an
+image. The `<KunEditor>` Vue component + toolbar + plugin views land in P3.
+
+## Peer dependencies (and why)
+
+`@milkdown/kit` and `@milkdown/prose` are **peer** dependencies, not bundled.
+ProseMirror MUST resolve to a single runtime instance — a second
+`prosemirror-model` copy silently breaks schema/node identity. Keeping Milkdown
+as a peer means the host owns the one copy. `katex`, `codemirror`, the
+`@codemirror/*` packages and `@lezer/highlight` are **optional** peers, needed
+only if you enable the katex / code-block plugins (i.e. import `/preset`).
+
+## Build & test
+
+```bash
+pnpm --filter @kungal/editor-core build      # tsup → dist (esm + cjs + d.ts)
+pnpm --filter @kungal/editor-core typecheck
+pnpm --filter @kungal/editor-core test       # vitest — headless markdown round-trip
+```

package/dist/chunk-KY2VN6IQ.js

@@ -0,0 +1,8 @@
+// src/index.ts
+var MENTION_SCHEME = "kungal-user:";
+var QUOTE_SCHEME = "kungal-reply:";
+var KUN_EDITOR_CORE_VERSION = "0.0.0";
+
+export { KUN_EDITOR_CORE_VERSION, MENTION_SCHEME, QUOTE_SCHEME };
+//# sourceMappingURL=chunk-KY2VN6IQ.js.map
+//# sourceMappingURL=chunk-KY2VN6IQ.js.map

package/dist/chunk-KY2VN6IQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AAYO,IAAM,cAAA,GAAiB;AAMvB,IAAM,YAAA,GAAe;AAErB,IAAM,uBAAA,GAA0B","file":"chunk-KY2VN6IQ.js","sourcesContent":["// @kungal/editor-core — public entry.\n//\n// STATUS: scaffold. The adapter contracts (the stable public surface) are\n// defined and exported now; the Milkdown plugin ports land incrementally per\n// docs/architecture.md § migration. Consumers should code against the types\n// below — those are the contract that will not churn as plugins move over.\n\nexport * from './types'\n\n// Markdown scheme used to encode an @mention as a plain link the server can\n// render + parse: `[@name](kungal-user:<id>)`. Lives here (not the plugin) so\n// hosts and the server can share the exact string. See ./plugins/mention.\nexport const MENTION_SCHEME = 'kungal-user:'\n\n// Markdown scheme for an inline reference (reply quote): `[label](kungal-reply:<refId>)`.\n// Like MENTION_SCHEME, shared with the server renderer so both agree on the\n// exact string. The reference is opaque here — the host decides what `refId` /\n// `label` mean (see docs/architecture.md § the reply-quote question, option 1).\nexport const QUOTE_SCHEME = 'kungal-reply:'\n\nexport const KUN_EDITOR_CORE_VERSION = '0.0.0'\n\n// ── The Milkdown plugins live in the `./preset` subpath ──────────────────────\n// This main entry stays light on purpose: types + MENTION_SCHEME, ZERO runtime\n// deps, so the server (which only needs the @mention scheme string) can import\n// it without installing @milkdown/kit / katex / codemirror.\n//\n// The composed Milkdown bundle and the individual plugin factories are exported\n// from `@kungal/editor-core/preset` (they pull in the peer deps):\n//\n//   import { createKunEditorPlugins } from '@kungal/editor-core/preset'\n//\n// P1 landed (docs/architecture.md § migration): spoiler, katex, code-block,\n// stop-link — each a factory (createXxxPlugin), never a host-bound singleton.\n// P2 adds the adapter-driven plugins (upload / mention / sticker).\n"]}

package/dist/index.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+// src/index.ts
+var MENTION_SCHEME = "kungal-user:";
+var QUOTE_SCHEME = "kungal-reply:";
+var KUN_EDITOR_CORE_VERSION = "0.0.0";
+
+exports.KUN_EDITOR_CORE_VERSION = KUN_EDITOR_CORE_VERSION;
+exports.MENTION_SCHEME = MENTION_SCHEME;
+exports.QUOTE_SCHEME = QUOTE_SCHEME;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAYO,IAAM,cAAA,GAAiB;AAMvB,IAAM,YAAA,GAAe;AAErB,IAAM,uBAAA,GAA0B","file":"index.cjs","sourcesContent":["// @kungal/editor-core — public entry.\n//\n// STATUS: scaffold. The adapter contracts (the stable public surface) are\n// defined and exported now; the Milkdown plugin ports land incrementally per\n// docs/architecture.md § migration. Consumers should code against the types\n// below — those are the contract that will not churn as plugins move over.\n\nexport * from './types'\n\n// Markdown scheme used to encode an @mention as a plain link the server can\n// render + parse: `[@name](kungal-user:<id>)`. Lives here (not the plugin) so\n// hosts and the server can share the exact string. See ./plugins/mention.\nexport const MENTION_SCHEME = 'kungal-user:'\n\n// Markdown scheme for an inline reference (reply quote): `[label](kungal-reply:<refId>)`.\n// Like MENTION_SCHEME, shared with the server renderer so both agree on the\n// exact string. The reference is opaque here — the host decides what `refId` /\n// `label` mean (see docs/architecture.md § the reply-quote question, option 1).\nexport const QUOTE_SCHEME = 'kungal-reply:'\n\nexport const KUN_EDITOR_CORE_VERSION = '0.0.0'\n\n// ── The Milkdown plugins live in the `./preset` subpath ──────────────────────\n// This main entry stays light on purpose: types + MENTION_SCHEME, ZERO runtime\n// deps, so the server (which only needs the @mention scheme string) can import\n// it without installing @milkdown/kit / katex / codemirror.\n//\n// The composed Milkdown bundle and the individual plugin factories are exported\n// from `@kungal/editor-core/preset` (they pull in the peer deps):\n//\n//   import { createKunEditorPlugins } from '@kungal/editor-core/preset'\n//\n// P1 landed (docs/architecture.md § migration): spoiler, katex, code-block,\n// stop-link — each a factory (createXxxPlugin), never a host-bound singleton.\n// P2 adds the adapter-driven plugins (upload / mention / sticker).\n"]}

package/dist/index.d.cts

@@ -0,0 +1,7 @@
+export { K as KunEditorAdapters, a as KunEditorFeatures, b as KunEditorLocale, M as MentionUser, N as Notify, c as NotifyLevel, S as SearchMentionUsers, d as StickerItem, e as StickerPack, f as StickerSource, U as UploadImage } from './types-B_iVOftJ.cjs';
+
+declare const MENTION_SCHEME = "kungal-user:";
+declare const QUOTE_SCHEME = "kungal-reply:";
+declare const KUN_EDITOR_CORE_VERSION = "0.0.0";
+
+export { KUN_EDITOR_CORE_VERSION, MENTION_SCHEME, QUOTE_SCHEME };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { K as KunEditorAdapters, a as KunEditorFeatures, b as KunEditorLocale, M as MentionUser, N as Notify, c as NotifyLevel, S as SearchMentionUsers, d as StickerItem, e as StickerPack, f as StickerSource, U as UploadImage } from './types-B_iVOftJ.js';
+
+declare const MENTION_SCHEME = "kungal-user:";
+declare const QUOTE_SCHEME = "kungal-reply:";
+declare const KUN_EDITOR_CORE_VERSION = "0.0.0";
+
+export { KUN_EDITOR_CORE_VERSION, MENTION_SCHEME, QUOTE_SCHEME };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { KUN_EDITOR_CORE_VERSION, MENTION_SCHEME, QUOTE_SCHEME } from './chunk-KY2VN6IQ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}