Initial Commit

openspec/changes/enterprise-react-rich-text/proposal.md

@@ -0,0 +1,83 @@
+# OpenSpec Change: enterprise-react-rich-text
+
+- **Change ID**: enterprise-react-rich-text
+- **Package**: `@suaveplan/react-rich-text`
+- **Category**: react
+- **Target path**: `react/media/react-rich-text`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-rich-text.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-rich-text` on genesis from scratch at enterprise quality. Tiptap-based rich-text WYSIWYG: `RichTextEditor` (composite), `EditorEngine`, `Toolbar`, `EditorContent`, `SlashCommandMenu`, `MentionList`, `BubbleMenu`, hooks (`useRichText`, `useMentions`, `useSlashCommands`), markdown round-trip, slash-command registry, and typed state. Genesis adds the missing `BubbleMenu` story, extends test coverage to 100%, and adds Playwright E2E.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `RichTextError` |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n for toolbar/placeholder |
+| `zod` (`catalog:forms`) | Config schemas |
+| `@opentelemetry/api` (`catalog:observability`) | `rich_text.submit` span |
+
+External: `@tiptap/core catalog:editor`, `@tiptap/react catalog:editor`, `@tiptap/starter-kit catalog:editor`, `@tiptap/extension-mention catalog:editor`, `@tiptap/extension-placeholder catalog:editor`, `@tiptap/extension-link catalog:editor`, `@tiptap/pm catalog:editor`, `@tiptap/suggestion catalog:editor`, `tslib catalog:build`. React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+RichTextEditor, EditorContent, Toolbar, BubbleMenu, SlashCommandMenu, MentionList
+useRichText, useMentions, useSlashCommands
+htmlToMarkdown, markdownToHtml
+filterSlashCommands, groupCommandsByCategory, executeSlashCommand
+
+// Types
+FormatState, FormatMark, BlockType, HeadingLevel, MarkdownShortcutRule,
+MentionItem, SlashCommand, SlashCommandCategory
+```
+
+---
+
+## New additions for genesis
+
+1. **`RichTextError`** — codes: `RICH_TEXT_INIT_FAILED`, `RICH_TEXT_PARSE_FAILED`.
+2. **`BubbleMenu` story** — default, formatting, playground.
+3. **100% test coverage** — all branches in `editor-engine` and all hooks.
+4. **Playwright E2E** — type text, apply bold, verify output; type `/` → slash menu; type `@` → mention list.
+
+---
+
+## File layout
+
+```text
+react/media/react-rich-text/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    editor-engine/ (ts + types + md + test + index)
+    editor-content/ (tsx + types + md + test + stories + index)
+    toolbar/ (tsx + types + md + test + stories + index)
+    bubble-menu/ (tsx + types + md + test + stories + index)
+    slash-command-menu/ (tsx + types + md + test + stories + index)
+    mention-list/ (tsx + types + md + test + stories + index)
+    rich-text-editor/ (tsx + types + md + test + stories + index)
+    hooks/
+      use-rich-text/ use-mentions/ use-slash-commands/
+    types/
+  e2e/
+    rich-text.spec.ts
+```