@edux-design/comments 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @edux-design/comments
 
+## 0.3.0
+
+### Minor Changes
+
+- Resolve mention menus into their containing dialog by default, with a typed portalContainer override and lifecycle-safe observation of reparenting and disconnected containers. Preserve composer values, mentions, external submission and imperative APIs. Require Menus ^1.1.0 for the checked-item and native Tab contract.
+
+### Patch Changes
+
+- Updated dependencies
+  - @edux-design/menus@1.1.0
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -119,3 +119,5 @@ override the label if needed.
 ## Additional components
 
 [Composer values, focus and external submission](./docs/composer.md).
+
+[Mention menu ownership in Drawers and Modals](./docs/mention-portals.md).

package/dist/index.d.mts

@@ -14,7 +14,7 @@ type CommentAvatarProps$1 = React.HTMLAttributes<HTMLSpanElement> & React.Button
     asButton?: boolean;
 };
 
-declare function CommentMention({ peopleList, onQueryChange }: CommentMentionProps$1): react_jsx_runtime.JSX.Element;
+declare function CommentMention({ peopleList, onQueryChange, portalContainer, }: CommentMentionProps$1): react_jsx_runtime.JSX.Element;
 type CommentMentionPerson$1 = {
     id: string | number;
     name: string;
@@ -25,6 +25,7 @@ type CommentMentionProps$1 = {
     peopleList?: CommentMentionPerson$1[];
     onQueryChange?: (query: string) => void;
     placeholder?: string;
+    portalContainer?: HTMLElement | null;
 };
 
 declare const CommentComposer: React.ForwardRefExoticComponent<Omit<React.FormHTMLAttributes<HTMLFormElement>, "onChange" | "onSubmit"> & {

package/dist/index.d.ts

@@ -14,7 +14,7 @@ type CommentAvatarProps$1 = React.HTMLAttributes<HTMLSpanElement> & React.Button
     asButton?: boolean;
 };
 
-declare function CommentMention({ peopleList, onQueryChange }: CommentMentionProps$1): react_jsx_runtime.JSX.Element;
+declare function CommentMention({ peopleList, onQueryChange, portalContainer, }: CommentMentionProps$1): react_jsx_runtime.JSX.Element;
 type CommentMentionPerson$1 = {
     id: string | number;
     name: string;
@@ -25,6 +25,7 @@ type CommentMentionProps$1 = {
     peopleList?: CommentMentionPerson$1[];
     onQueryChange?: (query: string) => void;
     placeholder?: string;
+    portalContainer?: HTMLElement | null;
 };
 
 declare const CommentComposer: React.ForwardRefExoticComponent<Omit<React.FormHTMLAttributes<HTMLFormElement>, "onChange" | "onSubmit"> & {

package/dist/index.js

@@ -558,36 +558,95 @@ function CommentComposerComponent({
 var CommentComposer = (0, import_react4.forwardRef)(CommentComposerComponent);
 
 // src/elements/CommentMention.jsx
-var import_react6 = __toESM(require("react"));
+var import_react7 = __toESM(require("react"));
 var import_menus = require("@edux-design/menus");
 var import_avatars3 = require("@edux-design/avatars");
+
+// src/elements/useMentionPortalContainer.js
+var import_react6 = require("react");
+function resolveMentionPortalContainer(anchor, override) {
+  const document = anchor?.ownerDocument;
+  if (!document || !anchor.isConnected) return void 0;
+  if (override === null) return void 0;
+  if (override?.isConnected && override.ownerDocument === document)
+    return override;
+  const dialog = anchor.closest(
+    '[role="dialog"], [role="alertdialog"], dialog'
+  );
+  return dialog?.isConnected ? dialog : void 0;
+}
+function useMentionPortalContainer(anchorRef, override, active) {
+  const [container, setContainer] = (0, import_react6.useState)(void 0);
+  (0, import_react6.useLayoutEffect)(() => {
+    let disposed = false;
+    let observer;
+    let observedDocument;
+    const refresh = () => {
+      if (disposed) return;
+      const anchor = anchorRef?.current;
+      const next = resolveMentionPortalContainer(anchor, override);
+      setContainer((previous) => previous === next ? previous : next);
+      const document = anchor?.ownerDocument;
+      if (!active || observedDocument === document) return;
+      observer?.disconnect();
+      observedDocument = document;
+      const MutationObserver = document?.defaultView?.MutationObserver;
+      if (MutationObserver && document.documentElement) {
+        observer = new MutationObserver(refresh);
+        observer.observe(document.documentElement, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+          attributeFilter: ["role"]
+        });
+      }
+    };
+    refresh();
+    return () => {
+      disposed = true;
+      observer?.disconnect();
+    };
+  }, [anchorRef, override, active]);
+  return container;
+}
+
+// src/elements/CommentMention.jsx
 var import_jsx_runtime4 = require("react/jsx-runtime");
-var CommentMention = ({ peopleList = [], onQueryChange }) => {
+var CommentMention = ({
+  peopleList = [],
+  onQueryChange,
+  portalContainer
+}) => {
   const { editor, editorContainerRef, editable = true } = useCommentComposer();
-  const [menuOpen, setMenuOpen] = (0, import_react6.useState)(false);
-  const [query, setQuery] = (0, import_react6.useState)("");
-  const [anchorStyle, setAnchorStyle] = (0, import_react6.useState)({ left: 0, top: 0 });
-  const menuListRef = (0, import_react6.useRef)(null);
-  const rangeRef = (0, import_react6.useRef)(null);
-  const lastQueryRef = (0, import_react6.useRef)("");
-  const dismissedRangeRef = (0, import_react6.useRef)(null);
-  const focusFrameRef = (0, import_react6.useRef)(null);
-  const focusTimeoutRef = (0, import_react6.useRef)(null);
-  const dismissMenu = (0, import_react6.useCallback)(() => {
+  const [menuOpen, setMenuOpen] = (0, import_react7.useState)(false);
+  const mentionPortalContainer = useMentionPortalContainer(
+    editorContainerRef,
+    portalContainer,
+    menuOpen
+  );
+  const [query, setQuery] = (0, import_react7.useState)("");
+  const [anchorStyle, setAnchorStyle] = (0, import_react7.useState)({ left: 0, top: 0 });
+  const menuListRef = (0, import_react7.useRef)(null);
+  const rangeRef = (0, import_react7.useRef)(null);
+  const lastQueryRef = (0, import_react7.useRef)("");
+  const dismissedRangeRef = (0, import_react7.useRef)(null);
+  const focusFrameRef = (0, import_react7.useRef)(null);
+  const focusTimeoutRef = (0, import_react7.useRef)(null);
+  const dismissMenu = (0, import_react7.useCallback)(() => {
     const activeRange = rangeRef.current;
     dismissedRangeRef.current = activeRange ? `${activeRange.from}:${activeRange.to}` : null;
     setMenuOpen(false);
     if (editor && !editor.isDestroyed && editor.isEditable !== false)
       editor.view.focus();
   }, [editor]);
-  const filteredPeople = (0, import_react6.useMemo)(() => {
+  const filteredPeople = (0, import_react7.useMemo)(() => {
     if (!query) return peopleList;
     const lowered = query.toLowerCase();
     return peopleList.filter(
       (person) => person.handle.toLowerCase().startsWith(lowered)
     );
   }, [peopleList, query]);
-  const updateMenuState = (0, import_react6.useCallback)(() => {
+  const updateMenuState = (0, import_react7.useCallback)(() => {
     if (!editor || !editable || editor.isEditable === false) {
       setMenuOpen(false);
       rangeRef.current = null;
@@ -630,7 +689,7 @@ var CommentMention = ({ peopleList = [], onQueryChange }) => {
       onQueryChange("");
     }
   }, [editor, editorContainerRef, onQueryChange, editable]);
-  const handleSelectPerson = (0, import_react6.useCallback)(
+  const handleSelectPerson = (0, import_react7.useCallback)(
     (person) => {
       if (!editor || !editable || editor.isEditable === false || !rangeRef.current)
         return;
@@ -675,14 +734,14 @@ var CommentMention = ({ peopleList = [], onQueryChange }) => {
     },
     [editor, onQueryChange, editable]
   );
-  (0, import_react6.useEffect)(
+  (0, import_react7.useEffect)(
     () => () => {
       cancelAnimationFrame(focusFrameRef.current);
       clearTimeout(focusTimeoutRef.current);
     },
     [editor]
   );
-  (0, import_react6.useEffect)(() => {
+  (0, import_react7.useEffect)(() => {
     if (!editor) return;
     updateMenuState();
     editor.on("transaction", updateMenuState);
@@ -692,7 +751,7 @@ var CommentMention = ({ peopleList = [], onQueryChange }) => {
       editor.off("selectionUpdate", updateMenuState);
     };
   }, [editor, updateMenuState]);
-  (0, import_react6.useEffect)(() => {
+  (0, import_react7.useEffect)(() => {
     if (!editor) return;
     const handleKeyDown = (event) => {
       if (!menuOpen) return;
@@ -717,7 +776,7 @@ var CommentMention = ({ peopleList = [], onQueryChange }) => {
     dom?.addEventListener("keydown", handleKeyDown, true);
     return () => dom?.removeEventListener("keydown", handleKeyDown, true);
   }, [editor, menuOpen, dismissMenu]);
-  const menuContent = (0, import_react6.useMemo)(
+  const menuContent = (0, import_react7.useMemo)(
     () => /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       import_menus.Menu,
       {
@@ -746,6 +805,7 @@ var CommentMention = ({ peopleList = [], onQueryChange }) => {
           sideOffset: 4,
           avoidCollisions: true,
           collisionPadding: 12,
+          container: mentionPortalContainer,
           onCloseAutoFocus: (event) => event.preventDefault()
         },
         children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
@@ -787,7 +847,14 @@ var CommentMention = ({ peopleList = [], onQueryChange }) => {
         )
       }
     ),
-    [filteredPeople, handleSelectPerson, menuOpen, anchorStyle, dismissMenu]
+    [
+      filteredPeople,
+      handleSelectPerson,
+      menuOpen,
+      anchorStyle,
+      dismissMenu,
+      mentionPortalContainer
+    ]
   );
   if (!editor) return null;
   return menuContent;

package/dist/index.mjs

@@ -540,19 +540,78 @@ var CommentComposer = forwardRef2(CommentComposerComponent);
 // src/elements/CommentMention.jsx
 import React4, {
   useMemo as useMemo3,
-  useState as useState3,
+  useState as useState4,
   useCallback,
   useEffect as useEffect3,
   useRef as useRef2
 } from "react";
 import { Menu, MenuList, MenuItem } from "@edux-design/menus";
 import { Avatar as Avatar3 } from "@edux-design/avatars";
+
+// src/elements/useMentionPortalContainer.js
+import { useLayoutEffect, useState as useState3 } from "react";
+function resolveMentionPortalContainer(anchor, override) {
+  const document = anchor?.ownerDocument;
+  if (!document || !anchor.isConnected) return void 0;
+  if (override === null) return void 0;
+  if (override?.isConnected && override.ownerDocument === document)
+    return override;
+  const dialog = anchor.closest(
+    '[role="dialog"], [role="alertdialog"], dialog'
+  );
+  return dialog?.isConnected ? dialog : void 0;
+}
+function useMentionPortalContainer(anchorRef, override, active) {
+  const [container, setContainer] = useState3(void 0);
+  useLayoutEffect(() => {
+    let disposed = false;
+    let observer;
+    let observedDocument;
+    const refresh = () => {
+      if (disposed) return;
+      const anchor = anchorRef?.current;
+      const next = resolveMentionPortalContainer(anchor, override);
+      setContainer((previous) => previous === next ? previous : next);
+      const document = anchor?.ownerDocument;
+      if (!active || observedDocument === document) return;
+      observer?.disconnect();
+      observedDocument = document;
+      const MutationObserver = document?.defaultView?.MutationObserver;
+      if (MutationObserver && document.documentElement) {
+        observer = new MutationObserver(refresh);
+        observer.observe(document.documentElement, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+          attributeFilter: ["role"]
+        });
+      }
+    };
+    refresh();
+    return () => {
+      disposed = true;
+      observer?.disconnect();
+    };
+  }, [anchorRef, override, active]);
+  return container;
+}
+
+// src/elements/CommentMention.jsx
 import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
-var CommentMention = ({ peopleList = [], onQueryChange }) => {
+var CommentMention = ({
+  peopleList = [],
+  onQueryChange,
+  portalContainer
+}) => {
   const { editor, editorContainerRef, editable = true } = useCommentComposer();
-  const [menuOpen, setMenuOpen] = useState3(false);
-  const [query, setQuery] = useState3("");
-  const [anchorStyle, setAnchorStyle] = useState3({ left: 0, top: 0 });
+  const [menuOpen, setMenuOpen] = useState4(false);
+  const mentionPortalContainer = useMentionPortalContainer(
+    editorContainerRef,
+    portalContainer,
+    menuOpen
+  );
+  const [query, setQuery] = useState4("");
+  const [anchorStyle, setAnchorStyle] = useState4({ left: 0, top: 0 });
   const menuListRef = useRef2(null);
   const rangeRef = useRef2(null);
   const lastQueryRef = useRef2("");
@@ -732,6 +791,7 @@ var CommentMention = ({ peopleList = [], onQueryChange }) => {
           sideOffset: 4,
           avoidCollisions: true,
           collisionPadding: 12,
+          container: mentionPortalContainer,
           onCloseAutoFocus: (event) => event.preventDefault()
         },
         children: /* @__PURE__ */ jsx4(
@@ -773,7 +833,14 @@ var CommentMention = ({ peopleList = [], onQueryChange }) => {
         )
       }
     ),
-    [filteredPeople, handleSelectPerson, menuOpen, anchorStyle, dismissMenu]
+    [
+      filteredPeople,
+      handleSelectPerson,
+      menuOpen,
+      anchorStyle,
+      dismissMenu,
+      mentionPortalContainer
+    ]
   );
   if (!editor) return null;
   return menuContent;

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.2.0",
+  "version": "0.3.0",
   "private": false,
   "sideEffects": [
     "**/*.css"
@@ -18,7 +18,7 @@
     "@edux-design/buttons": "*",
     "@edux-design/forms": "*",
     "@edux-design/mentions": "*",
-    "@edux-design/menus": "*",
+    "@edux-design/menus": "^1.1.0",
     "@edux-design/utils": "*"
   },
   "peerDependencies": {
@@ -33,8 +33,6 @@
     "dist",
     "docs",
     "README.md",
-    "CHANGELOG.md",
-    "LICENSE",
-    "LICENSE.md"
+    "CHANGELOG.md"
   ]
 }