@zuilib/text-editor 0.0.0 → 0.0.2

package/README.md

@@ -1,57 +1,161 @@
 # @zuilib/text-editor
 
-Markdown editor for ZUI Design System — a React component built on [Lexical](https://lexical.dev/) with markdown shortcuts, code highlighting, checklists, and raw/rich/view modes.
+Markdown editor for ZUI built on [Lexical](https://lexical.dev/): rich editing with shortcuts, raw markdown mode, read-only view, checklists, and fenced code highlighting.
+
+## When to use
+
+- Notes, comments, or docs fields stored as **markdown strings**
+- Controlled `value` / `onChange` integration with forms or autosave
+- WYSIWYG-style editing without leaving markdown as the source of truth
+
+## Prerequisites
+
+Peer dependencies (install in the consuming app):
+
+| Package | Version |
+|---------|---------|
+| `react`, `react-dom` | `^18.0.0 \|\| ^19.0.0` |
+| `lexical` | `^0.35.0` |
+| `@lexical/react` | `^0.35.0` |
+| `@lexical/markdown` | `^0.35.0` |
+| `@lexical/rich-text` | `^0.35.0` |
+| `@lexical/code` | `^0.35.0` |
+| `@lexical/list` | `^0.35.0` |
+| `@lexical/link` | `^0.35.0` |
+| `@zuilib/core` | workspace / published — import core styles |
 
 ## Installation
 
 ```bash
-pnpm add @zuilib/text-editor @zuilib/core lexical @lexical/react @lexical/markdown @lexical/rich-text @lexical/code @lexical/list @lexical/link
+pnpm add @zuilib/text-editor @zuilib/core \
+  lexical @lexical/react @lexical/markdown @lexical/rich-text \
+  @lexical/code @lexical/list @lexical/link
+```
+
+Monorepo:
+
+```json
+{
+  "dependencies": {
+    "@zuilib/text-editor": "workspace:*",
+    "@zuilib/core": "workspace:*",
+    "lexical": "^0.35.0",
+    "@lexical/react": "^0.35.0",
+    "@lexical/markdown": "^0.35.0",
+    "@lexical/rich-text": "^0.35.0",
+    "@lexical/code": "^0.35.0",
+    "@lexical/list": "^0.35.0",
+    "@lexical/link": "^0.35.0"
+  }
+}
 ```
 
-## Usage
+## Import rules
+
+| Rule | Detail |
+|------|--------|
+| **Named export** | `import { MarkdownEditor } from '@zuilib/text-editor'` |
+| **Types** | `import type { MarkdownEditorProps } from '@zuilib/text-editor'` |
+| **Styles** | `import '@zuilib/text-editor/styles.css'` and `@zuilib/core/styles.css` |
+| **Controlled** | Always pass `value` + `onChange` for persisted content |
+| **Mode switches** | Switching `edit-raw` → `edit-md` re-mounts Lexical with latest markdown (cursor-safe) |
+
+## Exports
+
+| Subpath | Exports |
+|---------|---------|
+| `@zuilib/text-editor` | `MarkdownEditor` (default re-exported as named), `MarkdownEditorProps` |
+| `@zuilib/text-editor/styles.css` | Editor chrome + Lexical theme classes |
+
+## Quick start
 
 ```tsx
 import { useState } from 'react'
-import { MarkdownEditor } from '@zuilib/text-editor'
+import '@zuilib/core/styles.css'
 import '@zuilib/text-editor/styles.css'
+import { MarkdownEditor } from '@zuilib/text-editor'
 
 function Notes() {
-  const [value, setValue] = useState('# Hello\n\n- [ ] Try me')
-
-  return <MarkdownEditor value={value} onChange={setValue} />
+  const [value, setValue] = useState('# Hello\n\n- [ ] Try checklists')
+
+  return (
+    <MarkdownEditor
+      value={value}
+      onChange={setValue}
+      placeholder="Start writing…"
+    />
+  )
 }
 ```
 
 ## Modes
 
+| `mode` | UI | `onChange` |
+|--------|-----|------------|
+| `'edit-md'` (default) | Lexical rich editor + markdown shortcuts | Emits markdown string |
+| `'edit-raw'` | Plain `<textarea>` with markdown source | Emits markdown string |
+| `'view'` | Read-only rendered content | No editing (`onChange` unused) |
+
 ```tsx
-// Rich markdown editing (default) — shortcuts like `#`, `- [ ]`, ``` `
-<MarkdownEditor mode="edit-md" value={value} onChange={setValue} />
+<MarkdownEditor mode="edit-md" value={md} onChange={setMd} />
+<MarkdownEditor mode="edit-raw" value={md} onChange={setMd} />
+<MarkdownEditor mode="view" value={md} />
+```
+
+Toggle modes in parent state; the editor preserves content via an internal ref when remounting Lexical after raw editing.
+
+## Props (`MarkdownEditorProps`)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | `''` | Markdown source (controlled) |
+| `onChange` | `(value: string) => void` | — | Called on every edit |
+| `mode` | `'edit-md' \| 'edit-raw' \| 'view'` | `'edit-md'` | Editing surface |
+| `placeholder` | `string` | `'Start writing...'` | Empty state hint |
+| `readOnly` | `boolean` | `false` | Disables editing in Lexical modes |
+| `autoFocus` | `boolean` | `false` | Focus on mount |
+| `className` | `string` | — | Root wrapper class |
+
+## Markdown features
+
+**Shortcuts (edit-md):** headings (`#`), lists, blockquote, links, fenced code (via `CodeBlockShortcutPlugin`), checklists (`- [ ]` via `ChecklistShortcutPlugin`).
 
-// Raw markdown in a plain textarea
-<MarkdownEditor mode="edit-raw" value={value} onChange={setValue} />
+**Built-in plugins:** history (undo/redo), lists, checklists, links, markdown sync (`MarkdownSyncPlugin`), code highlighting (`CodeHighlightPlugin`).
 
-// Read-only rendered view
-<MarkdownEditor mode="view" value={value} />
+**Not included:** file uploads, collaborative editing, or custom Lexical node registration — extend by forking or wrapping `MarkdownEditor`.
+
+## Form integration
+
+With `@zuilib/form`:
+
+```tsx
+<FormField control={form.control} name="body">
+  {({ field }) => (
+    <MarkdownEditor
+      value={field.value}
+      onChange={field.onChange}
+      mode="edit-md"
+    />
+  )}
+</FormField>
 ```
 
-## Props
+Ensure both CSS entry points are loaded in the app layout.
 
-- `value`: `string` — markdown source
-- `onChange`: `(value: string) => void`
-- `mode`: `'edit-md' | 'edit-raw' | 'view'` (default `'edit-md'`)
-- `placeholder`: `string` (default `'Start writing...'`)
-- `readOnly`: `boolean`
-- `autoFocus`: `boolean`
-- `className`: `string`
+## Architecture notes (for extenders)
 
-## Features
+- Source: `src/MarkdownEditor.tsx`, plugins under `src/plugins/`
+- Lexical namespace: `ZuiTextEditor`
+- Markdown import/export uses `@lexical/markdown` transformers (`CHECK_LIST` prioritized for import)
+- `edit-raw` bypasses Lexical; switching back to `edit-md` captures `latestValueRef` and bumps `mountKey` to avoid cursor jumps
 
-- Markdown shortcuts: headings, lists, checklists, code blocks, quotes, links
-- Syntax-highlighted fenced code blocks
-- Undo/redo history
-- Cursor-stable mode switching between raw and rich editing
+## Related packages
 
-## License
+- `@zuilib/core` — design tokens and base styles
+- `@zuilib/form` — react-hook-form wiring
 
-MIT
+## Build (maintainers)
+
+```bash
+pnpm --filter @zuilib/text-editor build
+```

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ElementNode, NodeKey, EditorConfig, SerializedElementNode, LexicalNode } from 'lexical';
+import { MultilineElementTransformer } from '@lexical/markdown';
 
 type Props = Readonly<{
     value?: string;
@@ -11,4 +13,45 @@ type Props = Readonly<{
 }>;
 declare function MarkdownEditor({ value, onChange, placeholder, readOnly, className, mode, autoFocus, }: Props): react_jsx_runtime.JSX.Element;
 
-export { MarkdownEditor, type Props as MarkdownEditorProps };
+type SerializedFrontmatterNode = SerializedElementNode;
+/**
+ * A block node holding a document's YAML frontmatter — the metadata section
+ * delimited by `---` lines at the very top of a markdown file (as used by
+ * Claude skills, static-site generators, etc.).
+ *
+ * Content is stored as plain TextNode children separated by LineBreakNodes, so
+ * `getTextContent()` yields the raw YAML with `\n` line separators — exactly
+ * what the FRONTMATTER transformer re-serializes on export.
+ */
+declare class FrontmatterNode extends ElementNode {
+    static getType(): string;
+    static clone(node: FrontmatterNode): FrontmatterNode;
+    constructor(key?: NodeKey);
+    createDOM(config: EditorConfig): HTMLElement;
+    updateDOM(): boolean;
+    static importJSON(_serializedNode: SerializedFrontmatterNode): FrontmatterNode;
+    exportJSON(): SerializedFrontmatterNode;
+    isInline(): false;
+    canBeEmpty(): boolean;
+    canIndent(): false;
+}
+declare function $createFrontmatterNode(): FrontmatterNode;
+declare function $isFrontmatterNode(node: LexicalNode | null | undefined): node is FrontmatterNode;
+/**
+ * Markdown transformer for a leading YAML frontmatter block:
+ *
+ * ```
+ * ---
+ * name: my-skill
+ * description: ...
+ * ---
+ * ```
+ *
+ * Import only claims the block when it's the very first thing in the document
+ * (frontmatter is defined as leading metadata); a `---` fence appearing later
+ * falls through to normal handling. Must be ordered before other multiline
+ * transformers so its `export` runs first for a FrontmatterNode.
+ */
+declare const FRONTMATTER: MultilineElementTransformer;
+
+export { $createFrontmatterNode, $isFrontmatterNode, FRONTMATTER, FrontmatterNode, MarkdownEditor, type Props as MarkdownEditorProps, type SerializedFrontmatterNode };

package/dist/index.js

@@ -192,6 +192,86 @@ function MarkdownSyncPlugin({
   return null;
 }
 
+// src/nodes/FrontmatterNode.ts
+import {
+  $applyNodeReplacement,
+  $createLineBreakNode,
+  $createTextNode,
+  ElementNode
+} from "lexical";
+var FrontmatterNode = class _FrontmatterNode extends ElementNode {
+  static getType() {
+    return "frontmatter";
+  }
+  static clone(node) {
+    return new _FrontmatterNode(node.__key);
+  }
+  constructor(key) {
+    super(key);
+  }
+  createDOM(config) {
+    const dom = document.createElement("div");
+    const className = config.theme.frontmatter;
+    dom.className = typeof className === "string" ? className : "zui-frontmatter";
+    return dom;
+  }
+  updateDOM() {
+    return false;
+  }
+  static importJSON(_serializedNode) {
+    return $createFrontmatterNode();
+  }
+  exportJSON() {
+    return {
+      ...super.exportJSON(),
+      type: "frontmatter",
+      version: 1
+    };
+  }
+  isInline() {
+    return false;
+  }
+  canBeEmpty() {
+    return false;
+  }
+  canIndent() {
+    return false;
+  }
+};
+function $createFrontmatterNode() {
+  return $applyNodeReplacement(new FrontmatterNode());
+}
+function $isFrontmatterNode(node) {
+  return node instanceof FrontmatterNode;
+}
+var FRONTMATTER_DELIMITER = /^---\s*$/;
+var FRONTMATTER = {
+  dependencies: [FrontmatterNode],
+  export: (node) => {
+    if (!$isFrontmatterNode(node)) return null;
+    const body = node.getTextContent();
+    return body ? `---
+${body}
+---` : "---\n---";
+  },
+  regExpStart: FRONTMATTER_DELIMITER,
+  regExpEnd: FRONTMATTER_DELIMITER,
+  replace: (rootNode, children, _startMatch, _endMatch, linesInBetween, isImport) => {
+    if (!isImport || children != null || linesInBetween == null) return false;
+    if (rootNode.getChildrenSize() !== 0) return false;
+    const lines = [...linesInBetween];
+    while (lines.length > 0 && lines[0].length === 0) lines.shift();
+    while (lines.length > 0 && lines[lines.length - 1].length === 0) lines.pop();
+    const node = $createFrontmatterNode();
+    lines.forEach((line, index) => {
+      if (index > 0) node.append($createLineBreakNode());
+      node.append($createTextNode(line));
+    });
+    rootNode.append(node);
+  },
+  type: "multiline-element"
+};
+
 // src/theme.ts
 var editorTheme = {
   ltr: "text-left",
@@ -261,12 +341,13 @@ var editorTheme = {
     url: "text-blue-500",
     variable: "text-blue-500"
   },
-  quote: "border-l-4 border-border pl-4 italic"
+  quote: "border-l-4 border-border pl-4 italic",
+  frontmatter: "zui-frontmatter"
 };
 
 // src/MarkdownEditor.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
-var SYNC_TRANSFORMERS = [CHECK_LIST, ...TRANSFORMERS];
+var SYNC_TRANSFORMERS = [FRONTMATTER, CHECK_LIST, ...TRANSFORMERS];
 var SHORTCUT_TRANSFORMERS = TRANSFORMERS.filter((t) => t !== CODE);
 function onError(error) {
   console.error(error);
@@ -279,7 +360,8 @@ var editorNodes = [
   CodeNode,
   CodeHighlightNode,
   AutoLinkNode,
-  LinkNode
+  LinkNode,
+  FrontmatterNode
 ];
 function ReadOnlyPlugin({ readOnly }) {
   const [editor] = useLexicalComposerContext5();
@@ -387,5 +469,9 @@ function MarkdownEditor({
   ] }) }, mountKey);
 }
 export {
+  $createFrontmatterNode,
+  $isFrontmatterNode,
+  FRONTMATTER,
+  FrontmatterNode,
   MarkdownEditor
 };

package/dist/styles.css

@@ -64,6 +64,22 @@
   transform: rotate(45deg);
 }
 
+/* Frontmatter (YAML metadata block delimited by --- at the top of a doc) */
+.zui-frontmatter {
+  display: block;
+  white-space: pre-wrap;
+  margin: 0 0 1rem;
+  padding: 0.75rem 1rem;
+  border: 1px solid currentColor;
+  border-radius: 0.375rem;
+  border-left-width: 3px;
+  font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas,
+    'Liberation Mono', monospace;
+  font-size: 0.8125rem;
+  line-height: 1.6;
+  opacity: 0.7;
+}
+
 .zui-text-editor-textarea {
   width: 100%;
   height: 100%;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuilib/text-editor",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "ZUI — A markdown editor component wrapping Lexical",
   "type": "module",
   "main": "./dist/index.js",
@@ -54,4 +54,4 @@
     "react",
     "typescript"
   ]
-}
+}