@edux-design/comments 0.1.4 → 0.3.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/docs/mention-portals.md

@@ -0,0 +1,105 @@
+# Mention menus in dialogs
+
+`CommentMention` automatically portals its menu into the nearest connected
+`[role="dialog"]`, `[role="alertdialog"]` or native `<dialog>` containing its
+editor. This keeps menu pointer and keyboard interaction inside an owning modal
+Drawer or Modal. Outside a dialog, the menu uses its ordinary document-body
+portal.
+
+```jsx
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button>Open comments</Button>
+  </DrawerTrigger>
+  <DrawerContent aria-label="Comments" aria-describedby={undefined}>
+    <DrawerHeader>
+      <ModalTitle>Comments</ModalTitle>
+    </DrawerHeader>
+    <DrawerBody>
+      <CommentComposer
+        value={draft}
+        valueFormat="text"
+        onChange={(event) => setDraft(event.target.value)}
+        onValueChange={setSnapshot}
+      >
+        <CommentMention peopleList={people} onQueryChange={setQuery} />
+      </CommentComposer>
+    </DrawerBody>
+  </DrawerContent>
+</Drawer>
+```
+
+Import the Drawer components from `@edux-design/drawers`, `Button` from
+`@edux-design/buttons`, and the composer and mention components from
+`@edux-design/comments`. `ModalTitle` from `@edux-design/modals` supplies the shared
+Dialog title in the Drawer header. Modal components have the same automatic
+ownership behaviour.
+
+## Optional portal override
+
+| `portalContainer`                                 | Behaviour                                                               |
+| ------------------------------------------------- | ----------------------------------------------------------------------- |
+| Omitted or `undefined`                            | Find the nearest owning dialog; otherwise use the body portal.          |
+| Connected `HTMLElement` in the editor's document  | Portal into that element. It takes precedence over automatic ownership. |
+| `null`                                            | Explicitly use the ordinary body portal.                                |
+| Detached element or element from another document | Ignore the override and use automatic ownership.                        |
+
+Pass the committed element itself, rather than a ref object. A callback ref stored
+in state makes the element available after mount:
+
+```jsx
+const [mentionHost, setMentionHost] = React.useState(null);
+
+<ModalContent>
+  <ModalHeader>
+    <ModalTitle>Comments</ModalTitle>
+    <ModalDescription>Discuss the current draft.</ModalDescription>
+  </ModalHeader>
+  <ModalBody>
+    <CommentComposer>
+      <CommentMention
+        peopleList={people}
+        portalContainer={mentionHost ?? undefined}
+      />
+    </CommentComposer>
+    <div ref={setMentionHost} />
+  </ModalBody>
+</ModalContent>;
+```
+
+Use `?? undefined` when a not-yet-mounted callback ref should retain automatic
+ownership. Passing its initial `null` directly requests the body portal. Keep a
+custom host inside the active modal's interactive surface. A body portal or a host
+outside that modal remains subject to the modal's pointer and focus restrictions.
+
+Ownership resolves after refs commit. While a mention query is active, it follows
+editor reparenting, dialog role changes, and removal of an override element.
+Nested dialogs select the nearest owning dialog. Each composer resolves its own
+owner. Tracking stops when the query closes and when the composer unmounts.
+
+## Interaction and values
+
+Typing `@query` filters the supplied people by handle and calls `onQueryChange`.
+Consumers continue to own asynchronous lookup, permissions and persistence.
+Pointer activation or ArrowDown/ArrowUp followed by Enter inserts one mention,
+closes the menu, and returns focus to the editor. Escape first dismisses an open
+mention menu and returns focus to the editor; a subsequent Escape can close the
+owning dialog according to that dialog's existing policy.
+
+The mention menu retains `trapFocus={false}` and
+`disableOutsidePointerEvents={false}`. The owning Drawer or Modal retains its
+normal focus trap and outside-pointer blocking. Disabled or submitting composers
+do not offer editable mention interaction.
+
+Portal ownership does not change the composer model or submission contract.
+`onValueChange` and `composerRef.current.getValue()` continue returning `text`,
+`legacyText`, `html`, `json`, `mentions` and `isEmpty`. Existing `onChange`,
+`onSubmit`, `onCancel`, `externalSubmit`, `submitOnModEnter`, editor labels,
+autofocus, avatar/actions/children, and all composer handle methods remain
+available. See [Composer values, focus and external submission](./composer.md).
+
+The Storybook **Content / Comment Mention Portals** stories exercise real modal
+Drawers and Modals, pointer and keyboard selection, Escape ordering, nested and
+changing owners, overrides, independent composers, asynchronous people, locked
+states, and a dark narrow Drawer. They use synthetic people and strict
+accessibility checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edux-design/comments",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "private": false,
   "sideEffects": [
     "**/*.css"
@@ -8,36 +8,17 @@
   "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": "*",
     "@edux-design/forms": "*",
     "@edux-design/mentions": "*",
-    "@edux-design/menus": "*",
+    "@edux-design/menus": "^1.1.0",
     "@edux-design/utils": "*"
   },
   "peerDependencies": {
@@ -47,5 +28,11 @@
     "@tiptap/react": "^3.15.3",
     "@tiptap/starter-kit": "^3.15.3",
     "@tiptap/extension-placeholder": "^3.15.3"
-  }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md"
+  ]
 }