@edux-design/comments 0.1.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @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
+
+- Add mention-aware rich value snapshots, typed composer focus/value/submit controls and external-submit support while preserving the legacy editor element ref and callbacks. Align development with the supported Tiptap 3 peer API.
+
+  Correct controlled-value echo synchronization so rapid typing retains every character. Keep legacy mention fallbacks and model-visible serialization distinct; type existing Comment compound components and provide structural avatar props without relying on an unpublished dependency type.
+
+### Patch Changes
+
+- Updated dependencies
+  - @edux-design/buttons@0.3.0
+
 ## 0.1.4
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,20 @@
 
 Structured comment block for discussion threads, with avatar, metadata, actions, and nested replies.
 
+## Token contract
+
+Comments use the shared numeric and semantic tokens for reusable spacing and
+colour contracts, including `gap-12`, `p-12`, `py-12`, and the existing focus
+and text tokens. The composer keeps a 120px editor height, 20px editor inset,
+40px reply offset, and 220px mention-menu minimum width as explicit
+component-owned geometry because the current theme has no matching declared
+tokens; these values are documented one-offs rather than new semantic tokens.
+
+The 12px composer padding uses the declared `py-12` token, and the 20px/40px
+values are written explicitly (`pl-[20px]` and `mt-[40px]`) so they do not
+depend on Tailwind's undeclared numeric fallback scale. Consumers should import
+`@edux-design/tokens/theme` so shared utilities resolve consistently.
+
 ## Install
 
 ```bash
@@ -101,3 +115,9 @@ override the label if needed.
   </Comment.Actions>
 </Comment>
 ```
+
+## 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

@@ -1,53 +1,168 @@
-import * as react from 'react';
+import React from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _tiptap_core from '@tiptap/core';
 
-/**
- * @typedef {React.HTMLAttributes<HTMLDivElement> & {
- *   author?: React.ReactNode,
- *   timestamp?: React.ReactNode,
- *   avatar?: React.ReactNode,
- *   avatarName?: string,
- *   avatarProps?: import("@edux-design/avatars").AvatarProps,
- *   body?: React.ReactNode,
- *   replies?: React.ReactNode,
- *   variant?: "default" | "resolved",
- *   resolved?: boolean,
- *   onResolve?: (event: React.MouseEvent<HTMLButtonElement>) => void,
- *   editable?: boolean,
- *   children?: React.ReactNode,
- * }} CommentProps
- */
-/**
- * Flexible comment surface with optional avatar, metadata, actions, and replies.
- */
-declare const Comment: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+/** Avatar fields accepted by the comments package's existing Avatar slots. */
+type CommentAvatarProps$1 = React.HTMLAttributes<HTMLSpanElement> & React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    name?: string;
+    initials?: string;
+    src?: string;
+    alt?: string;
+    size?: "small" | "medium" | "large";
+    online?: boolean;
+    backgroundColor?: string;
+    asButton?: boolean;
+};
 
-/**
- * @typedef {React.FormHTMLAttributes<HTMLFormElement> & {
- *   value?: string,
- *   onChange?: (event: React.ChangeEvent<HTMLTextAreaElement>) => void,
- *   onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void,
- *   onCancel?: (event: React.MouseEvent<HTMLButtonElement>) => void,
- *   placeholder?: string,
- *   rows?: number,
- *   disabled?: boolean,
- *   isSubmitting?: boolean,
- *   submitLabel?: string,
- *   cancelLabel?: string,
- *   avatar?: React.ReactNode,
- *   avatarProps?: import("@edux-design/avatars").AvatarProps,
- *   actions?: React.ReactNode,
- *   children?: React.ReactNode,
- * }} CommentComposerProps
- */
-/**
- * Comment composer with avatar, textarea, and action buttons.
- */
-declare const CommentComposer: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+declare function CommentMention({ peopleList, onQueryChange, portalContainer, }: CommentMentionProps$1): react_jsx_runtime.JSX.Element;
+type CommentMentionPerson$1 = {
+    id: string | number;
+    name: string;
+    handle: string;
+    avatarProps?: CommentAvatarProps$1;
+};
+type CommentMentionProps$1 = {
+    peopleList?: CommentMentionPerson$1[];
+    onQueryChange?: (query: string) => void;
+    placeholder?: string;
+    portalContainer?: HTMLElement | null;
+};
 
-declare function CommentMention({ peopleList, onQueryChange, }: {
-    peopleList?: any[];
-    onQueryChange: any;
-}): react_jsx_runtime.JSX.Element;
+declare const CommentComposer: React.ForwardRefExoticComponent<Omit<React.FormHTMLAttributes<HTMLFormElement>, "onChange" | "onSubmit"> & {
+    value?: string;
+    valueFormat?: "html" | "text";
+    richValue?: _tiptap_core.JSONContent;
+    onChange?: (event: {
+        target: {
+            value: string;
+        };
+    }) => void;
+    onValueChange?: (value: CommentComposerValue$1) => void;
+    onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+    onCancel?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    composerRef?: React.Ref<CommentComposerHandle$1>;
+    editorLabel?: string;
+    editorAttributes?: Pick<React.HTMLAttributes<HTMLDivElement>, "id" | "aria-describedby" | "aria-invalid" | "aria-required">;
+    autoFocus?: boolean;
+    externalSubmit?: boolean;
+    submitOnModEnter?: boolean;
+    placeholder?: string;
+    rows?: number;
+    disabled?: boolean;
+    isSubmitting?: boolean;
+    submitLabel?: string;
+    submittingLabel?: string;
+    cancelLabel?: string;
+    avatar?: React.ReactNode;
+    avatarProps?: CommentAvatarProps$1;
+    actions?: React.ReactNode;
+    children?: React.ReactNode;
+} & React.RefAttributes<HTMLDivElement>>;
+type CommentComposerMentionValue$1 = {
+    id: string | number | null;
+    handle: string;
+    label: string;
+};
+type CommentComposerValue$1 = {
+    text: string;
+    legacyText: string;
+    html: string;
+    json: _tiptap_core.JSONContent;
+    mentions: CommentComposerMentionValue$1[];
+    isEmpty: boolean;
+};
+type CommentComposerHandle$1 = {
+    focus: (position?: "start" | "end" | "all" | number) => boolean;
+    clear: () => boolean;
+    getValue: () => CommentComposerValue$1 | null;
+    submit: () => void;
+};
+type CommentComposerProps$1 = Omit<React.FormHTMLAttributes<HTMLFormElement>, "onChange" | "onSubmit"> & {
+    value?: string;
+    valueFormat?: "html" | "text";
+    richValue?: _tiptap_core.JSONContent;
+    onChange?: (event: {
+        target: {
+            value: string;
+        };
+    }) => void;
+    onValueChange?: (value: CommentComposerValue$1) => void;
+    onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+    onCancel?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    composerRef?: React.Ref<CommentComposerHandle$1>;
+    editorLabel?: string;
+    editorAttributes?: Pick<React.HTMLAttributes<HTMLDivElement>, "id" | "aria-describedby" | "aria-invalid" | "aria-required">;
+    autoFocus?: boolean;
+    externalSubmit?: boolean;
+    submitOnModEnter?: boolean;
+    placeholder?: string;
+    rows?: number;
+    disabled?: boolean;
+    isSubmitting?: boolean;
+    submitLabel?: string;
+    submittingLabel?: string;
+    cancelLabel?: string;
+    avatar?: React.ReactNode;
+    avatarProps?: CommentAvatarProps$1;
+    actions?: React.ReactNode;
+    children?: React.ReactNode;
+};
 
-export { Comment, CommentComposer, CommentMention };
+declare const Comment: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    author?: React.ReactNode;
+    timestamp?: React.ReactNode;
+    avatar?: React.ReactNode;
+    avatarName?: string;
+    avatarProps?: CommentAvatarProps$1;
+    body?: React.ReactNode;
+    replies?: React.ReactNode;
+    variant?: "default" | "resolved";
+    resolved?: boolean;
+    onResolve?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    editable?: boolean;
+    children?: React.ReactNode;
+} & React.RefAttributes<HTMLDivElement>> & {
+    Actions: {
+        ({ children, className, ...props }: React.ComponentPropsWithRef<"div">): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Reply: {
+        ({ className, ...props }: React.ComponentPropsWithRef<"button">): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Edit: {
+        ({ className, ...props }: React.ComponentPropsWithRef<"button">): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Resolve: {
+        ({ className, disabled, onClick, label, ...props }: React.ComponentPropsWithRef<"button"> & {
+            label?: React.ReactNode;
+        }): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+};
+type CommentProps$1 = React.HTMLAttributes<HTMLDivElement> & {
+    author?: React.ReactNode;
+    timestamp?: React.ReactNode;
+    avatar?: React.ReactNode;
+    avatarName?: string;
+    avatarProps?: CommentAvatarProps$1;
+    body?: React.ReactNode;
+    replies?: React.ReactNode;
+    variant?: "default" | "resolved";
+    resolved?: boolean;
+    onResolve?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    editable?: boolean;
+    children?: React.ReactNode;
+};
+
+type CommentProps = CommentProps$1;
+type CommentComposerProps = CommentComposerProps$1;
+type CommentComposerHandle = CommentComposerHandle$1;
+type CommentComposerValue = CommentComposerValue$1;
+type CommentComposerMentionValue = CommentComposerMentionValue$1;
+type CommentMentionProps = CommentMentionProps$1;
+type CommentMentionPerson = CommentMentionPerson$1;
+type CommentAvatarProps = CommentAvatarProps$1;
+
+export { Comment, type CommentAvatarProps, CommentComposer, type CommentComposerHandle, type CommentComposerMentionValue, type CommentComposerProps, type CommentComposerValue, CommentMention, type CommentMentionPerson, type CommentMentionProps, type CommentProps };

package/dist/index.d.ts

@@ -1,53 +1,168 @@
-import * as react from 'react';
+import React from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _tiptap_core from '@tiptap/core';
 
-/**
- * @typedef {React.HTMLAttributes<HTMLDivElement> & {
- *   author?: React.ReactNode,
- *   timestamp?: React.ReactNode,
- *   avatar?: React.ReactNode,
- *   avatarName?: string,
- *   avatarProps?: import("@edux-design/avatars").AvatarProps,
- *   body?: React.ReactNode,
- *   replies?: React.ReactNode,
- *   variant?: "default" | "resolved",
- *   resolved?: boolean,
- *   onResolve?: (event: React.MouseEvent<HTMLButtonElement>) => void,
- *   editable?: boolean,
- *   children?: React.ReactNode,
- * }} CommentProps
- */
-/**
- * Flexible comment surface with optional avatar, metadata, actions, and replies.
- */
-declare const Comment: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+/** Avatar fields accepted by the comments package's existing Avatar slots. */
+type CommentAvatarProps$1 = React.HTMLAttributes<HTMLSpanElement> & React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    name?: string;
+    initials?: string;
+    src?: string;
+    alt?: string;
+    size?: "small" | "medium" | "large";
+    online?: boolean;
+    backgroundColor?: string;
+    asButton?: boolean;
+};
 
-/**
- * @typedef {React.FormHTMLAttributes<HTMLFormElement> & {
- *   value?: string,
- *   onChange?: (event: React.ChangeEvent<HTMLTextAreaElement>) => void,
- *   onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void,
- *   onCancel?: (event: React.MouseEvent<HTMLButtonElement>) => void,
- *   placeholder?: string,
- *   rows?: number,
- *   disabled?: boolean,
- *   isSubmitting?: boolean,
- *   submitLabel?: string,
- *   cancelLabel?: string,
- *   avatar?: React.ReactNode,
- *   avatarProps?: import("@edux-design/avatars").AvatarProps,
- *   actions?: React.ReactNode,
- *   children?: React.ReactNode,
- * }} CommentComposerProps
- */
-/**
- * Comment composer with avatar, textarea, and action buttons.
- */
-declare const CommentComposer: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
+declare function CommentMention({ peopleList, onQueryChange, portalContainer, }: CommentMentionProps$1): react_jsx_runtime.JSX.Element;
+type CommentMentionPerson$1 = {
+    id: string | number;
+    name: string;
+    handle: string;
+    avatarProps?: CommentAvatarProps$1;
+};
+type CommentMentionProps$1 = {
+    peopleList?: CommentMentionPerson$1[];
+    onQueryChange?: (query: string) => void;
+    placeholder?: string;
+    portalContainer?: HTMLElement | null;
+};
 
-declare function CommentMention({ peopleList, onQueryChange, }: {
-    peopleList?: any[];
-    onQueryChange: any;
-}): react_jsx_runtime.JSX.Element;
+declare const CommentComposer: React.ForwardRefExoticComponent<Omit<React.FormHTMLAttributes<HTMLFormElement>, "onChange" | "onSubmit"> & {
+    value?: string;
+    valueFormat?: "html" | "text";
+    richValue?: _tiptap_core.JSONContent;
+    onChange?: (event: {
+        target: {
+            value: string;
+        };
+    }) => void;
+    onValueChange?: (value: CommentComposerValue$1) => void;
+    onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+    onCancel?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    composerRef?: React.Ref<CommentComposerHandle$1>;
+    editorLabel?: string;
+    editorAttributes?: Pick<React.HTMLAttributes<HTMLDivElement>, "id" | "aria-describedby" | "aria-invalid" | "aria-required">;
+    autoFocus?: boolean;
+    externalSubmit?: boolean;
+    submitOnModEnter?: boolean;
+    placeholder?: string;
+    rows?: number;
+    disabled?: boolean;
+    isSubmitting?: boolean;
+    submitLabel?: string;
+    submittingLabel?: string;
+    cancelLabel?: string;
+    avatar?: React.ReactNode;
+    avatarProps?: CommentAvatarProps$1;
+    actions?: React.ReactNode;
+    children?: React.ReactNode;
+} & React.RefAttributes<HTMLDivElement>>;
+type CommentComposerMentionValue$1 = {
+    id: string | number | null;
+    handle: string;
+    label: string;
+};
+type CommentComposerValue$1 = {
+    text: string;
+    legacyText: string;
+    html: string;
+    json: _tiptap_core.JSONContent;
+    mentions: CommentComposerMentionValue$1[];
+    isEmpty: boolean;
+};
+type CommentComposerHandle$1 = {
+    focus: (position?: "start" | "end" | "all" | number) => boolean;
+    clear: () => boolean;
+    getValue: () => CommentComposerValue$1 | null;
+    submit: () => void;
+};
+type CommentComposerProps$1 = Omit<React.FormHTMLAttributes<HTMLFormElement>, "onChange" | "onSubmit"> & {
+    value?: string;
+    valueFormat?: "html" | "text";
+    richValue?: _tiptap_core.JSONContent;
+    onChange?: (event: {
+        target: {
+            value: string;
+        };
+    }) => void;
+    onValueChange?: (value: CommentComposerValue$1) => void;
+    onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+    onCancel?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    composerRef?: React.Ref<CommentComposerHandle$1>;
+    editorLabel?: string;
+    editorAttributes?: Pick<React.HTMLAttributes<HTMLDivElement>, "id" | "aria-describedby" | "aria-invalid" | "aria-required">;
+    autoFocus?: boolean;
+    externalSubmit?: boolean;
+    submitOnModEnter?: boolean;
+    placeholder?: string;
+    rows?: number;
+    disabled?: boolean;
+    isSubmitting?: boolean;
+    submitLabel?: string;
+    submittingLabel?: string;
+    cancelLabel?: string;
+    avatar?: React.ReactNode;
+    avatarProps?: CommentAvatarProps$1;
+    actions?: React.ReactNode;
+    children?: React.ReactNode;
+};
 
-export { Comment, CommentComposer, CommentMention };
+declare const Comment: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    author?: React.ReactNode;
+    timestamp?: React.ReactNode;
+    avatar?: React.ReactNode;
+    avatarName?: string;
+    avatarProps?: CommentAvatarProps$1;
+    body?: React.ReactNode;
+    replies?: React.ReactNode;
+    variant?: "default" | "resolved";
+    resolved?: boolean;
+    onResolve?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    editable?: boolean;
+    children?: React.ReactNode;
+} & React.RefAttributes<HTMLDivElement>> & {
+    Actions: {
+        ({ children, className, ...props }: React.ComponentPropsWithRef<"div">): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Reply: {
+        ({ className, ...props }: React.ComponentPropsWithRef<"button">): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Edit: {
+        ({ className, ...props }: React.ComponentPropsWithRef<"button">): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+    Resolve: {
+        ({ className, disabled, onClick, label, ...props }: React.ComponentPropsWithRef<"button"> & {
+            label?: React.ReactNode;
+        }): react_jsx_runtime.JSX.Element;
+        displayName: string;
+    };
+};
+type CommentProps$1 = React.HTMLAttributes<HTMLDivElement> & {
+    author?: React.ReactNode;
+    timestamp?: React.ReactNode;
+    avatar?: React.ReactNode;
+    avatarName?: string;
+    avatarProps?: CommentAvatarProps$1;
+    body?: React.ReactNode;
+    replies?: React.ReactNode;
+    variant?: "default" | "resolved";
+    resolved?: boolean;
+    onResolve?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    editable?: boolean;
+    children?: React.ReactNode;
+};
+
+type CommentProps = CommentProps$1;
+type CommentComposerProps = CommentComposerProps$1;
+type CommentComposerHandle = CommentComposerHandle$1;
+type CommentComposerValue = CommentComposerValue$1;
+type CommentComposerMentionValue = CommentComposerMentionValue$1;
+type CommentMentionProps = CommentMentionProps$1;
+type CommentMentionPerson = CommentMentionPerson$1;
+type CommentAvatarProps = CommentAvatarProps$1;
+
+export { Comment, type CommentAvatarProps, CommentComposer, type CommentComposerHandle, type CommentComposerMentionValue, type CommentComposerProps, type CommentComposerValue, CommentMention, type CommentMentionPerson, type CommentMentionProps, type CommentProps };