@edux-design/comments 0.1.4 → 0.2.0

package/docs/composer.md

@@ -0,0 +1,65 @@
+# Comment composer
+
+`CommentComposer` owns the editor presentation and accessible interactions. The host owns comment transport, authorisation, discussion threads, mention lookup and request status.
+
+## Values and mentions
+
+The existing `value` string and `onChange({ target: { value } })` contract remains available. Legacy `onChange` continues to use Tiptap `getText()`: mentions are `@handle` (or `@label`, then `@mention` when neither exists). The new snapshot's `text` uses the full visible mention label `@handle · Name`, suitable for Payload's existing transport body. Plain-text echoes of either form preserve mention nodes and the selection.
+
+`valueFormat="html"` is the backward-compatible default for string input. Set `valueFormat="text"` for literal application text (so `<em>text</em>` remains literal text), and use `richValue` JSON to restore rich drafts. Treating untrusted strings as HTML should be a deliberate host decision.
+
+Use `onValueChange` for a complete editor snapshot:
+
+```jsx
+<CommentComposer
+  value={text}
+  onChange={(event) => setText(event.target.value)}
+  onValueChange={({ text, html, json, mentions, isEmpty }) =>
+    saveDraft({ text, json, mentions })
+  }
+/>
+```
+
+The snapshot has normalised `text`, original `legacyText`, serialised `html`, Tiptap `json`, ordered `mentions` (`{ id, handle, label }`; IDs retain their original string/number type or null), and `isEmpty`. Mentions are read from the document model, including immediately after insertion; no DOM selector, MutationObserver or node-view timing workaround is needed. Snapshot `text` replaces NBSP with ordinary space, removes U+200B–U+200D/U+FEFF and replaces each model line break with one space; it does not trim. Visual node-view layout does not add artificial line breaks. Duplicate mentions remain separate occurrences. Snapshot HTML is editor output, not a general-purpose sanitiser for untrusted HTML.
+
+Use `richValue` with the snapshot's JSON to restore/drive a rich draft without losing mention identities. If both `richValue` and `value` are provided, `richValue` takes precedence. The composer recognises echoes of the most recent 100 model transactions so normal batched/debounced parent updates do not overwrite newer keystrokes; older updates are treated as explicit controlled replacements. This history is bounded even when an observing host never echoes values. Controlled prop replacements do not emit change callbacks. Editor edits and public `clear()` do. An omitted value is uncontrolled and an initially empty editor disables submission.
+
+## Focus and refs
+
+The existing forwarded `ref` still points to the editor's wrapping `HTMLDivElement`. Add `composerRef` for a `CommentComposerHandle`:
+
+| Method                    | Behaviour                                                                                               |
+| ------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `focus(position = 'end')` | Focus the editor at `start`, `end`, `all` or a numeric document position; return success.               |
+| `clear()`                 | Clear content and emit value callbacks; return success. Controlled hosts should echo the cleared value. |
+| `getValue()`              | Return a current `CommentComposerValue`, or `null` before the editor is ready.                          |
+| `submit()`                | Request normal form submission using the same empty/disabled/pending guard as the internal button.      |
+
+`editorLabel` keeps the published default “Comment”; Payload can pass “Write a comment” and labels the multiline textbox directly. `editorAttributes` forwards editable `id`, `aria-describedby`, `aria-invalid` and `aria-required`, including runtime updates. `autoFocus` is opt-in and schedules focus after editor readiness/on re-enabling, with frame cleanup on unmount. Imperative focus requests made before editor readiness are queued. Disabled/pending composers reject focus, clear and submit operations and prevent editing. `getValue` remains available for reading a pending draft. The form exposes `aria-busy` while `isSubmitting` is true. `submittingLabel` defaults to “Posting...” and supports context-specific pending labels.
+
+## External submit
+
+```jsx
+const composerRef = useRef(null);
+
+<CommentComposer
+  id="reply"
+  composerRef={composerRef}
+  externalSubmit
+  submitOnModEnter
+  editorLabel="Reply to this thread"
+  valueFormat="text"
+  value={text}
+  onValueChange={(value) => setText(value.text)}
+  onSubmit={(event) => sendReply(composerRef.current.getValue())}
+/>
+<Button form="reply" type="submit">Send reply</Button>
+```
+
+`externalSubmit` omits only the built-in submit button. Cancellation and action slots remain usable. Associate a native submit button with the form `id`, or call `composerRef.current.submit()`. All routes preserve `onSubmit`'s form event and call `preventDefault` before handing control to the host. The opt-in `submitOnModEnter` enables Control/Command+Enter without overriding ordinary Enter or composition. The native `onKeyDown` handler is composed once before this shortcut, so either it or `onKeyDownCapture` can prevent the package action.
+
+## Layout and theme
+
+The default editor remains 120px high; `rows` sets 30px per row. Colour modes use existing semantic tokens; root padding, border widths and editor height are unchanged when themes switch. The editor transition respects reduced motion. The host supplies the panel width; no portal, application focus trap or transport logic is added. Supply React 19 and the package's declared Tiptap 3 peers consistently.
+
+Storybook includes basic text submission, mention insertion, external submission/focus, rich drafts, disabled/pending states, narrow layout and light/dark colour modes. Interaction plays exercise the real editor, rapid controlled typing, accessible menu selection/Escape, and host-controlled failure/retry without clearing a failed draft.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edux-design/comments",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "private": false,
   "sideEffects": [
     "**/*.css"
@@ -8,30 +8,11 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
-  "scripts": {
-    "lint": "eslint . --max-warnings 0",
-    "build": "tsup src/index.js --format esm,cjs --dts",
-    "dev": "tsup src/index.js --watch --format esm,cjs --dts",
-    "generate:component": "turbo gen react-component",
-    "check-types": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "typescript": "^5.9.2",
-    "tailwindcss": "^4.1.12",
-    "postcss": "^8.5.6",
-    "tsup": "^8.5.0",
-    "@tailwindcss/cli": "^4.1.12",
-    "@tailwindcss/postcss": "^4.1.12",
-    "@tiptap/core": "^2.14.0",
-    "@tiptap/react": "^2.14.0",
-    "@tiptap/starter-kit": "^2.14.0",
-    "@tiptap/extension-placeholder": "^2.14.0"
-  },
   "dependencies": {
     "@edux-design/avatars": "*",
     "@edux-design/buttons": "*",
@@ -47,5 +28,13 @@
     "@tiptap/react": "^3.15.3",
     "@tiptap/starter-kit": "^3.15.3",
     "@tiptap/extension-placeholder": "^3.15.3"
-  }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "LICENSE.md"
+  ]
 }