@edux-design/comments 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @edux-design/comments
 
+## 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
+
+- Added hooks and callbacks for consumer support
+
 ## 0.1.3
 
 ### 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
@@ -13,17 +27,19 @@ npm i @edux-design/comments @edux-design/avatars
 ```jsx
 import { Comment } from "@edux-design/comments";
 import { CommentComposer } from "@edux-design/comments";
+import { CommentMention } from "@edux-design/comments";
 
 export function Example() {
+  const [resolved, setResolved] = React.useState(false);
+
   return (
     <Comment
       author="Alex Johnson"
       timestamp="2h ago"
       body="Left a few notes on the introduction. Let me know if you want me to draft the edits."
       avatarProps={{ name: "Alex Johnson" }}
-      onResolve={() => {
-        // mark resolved in your app state
-      }}
+      resolved={resolved}
+      onResolve={() => setResolved((prev) => !prev)}
       replies={
         <Comment
           author="Taylor"
@@ -47,6 +63,7 @@ export function Example() {
 ```jsx
 export function ComposerExample() {
   const [value, setValue] = React.useState("");
+  const [query, setQuery] = React.useState("");
 
   return (
     <CommentComposer
@@ -55,7 +72,50 @@ export function ComposerExample() {
       onSubmit={() => setValue("")}
       onCancel={() => setValue("")}
       avatarProps={{ name: "Alex Johnson" }}
-    />
+    >
+      <CommentMention
+        peopleList={[
+          { id: "alex", name: "Alex Johnson", handle: "alex" },
+          { id: "priya", name: "Priya Singh", handle: "priya" },
+        ]}
+        onQueryChange={setQuery}
+      />
+      <div className="mt-8 text-xs text-fg-subtle">
+        Mention query: <span className="font-semibold">{query || "—"}</span>
+      </div>
+    </CommentComposer>
   );
 }
 ```
+
+## Mentions
+
+`CommentMention` handles the in-editor mention menu and emits the active query via
+`onQueryChange` when the user types `@query` at the cursor. Debounce behavior is
+left to the consumer.
+
+```jsx
+import { CommentComposer, CommentMention } from "@edux-design/comments";
+
+<CommentComposer value={value} onChange={(event) => setValue(event.target.value)}>
+  <CommentMention peopleList={people} onQueryChange={setQuery} />
+</CommentComposer>;
+```
+
+## Resolve / Re-open
+
+`Comment.Resolve` swaps label and styling based on the resolved state. You can
+override the label if needed.
+
+```jsx
+<Comment resolved={isResolved} onResolve={toggleResolved}>
+  <Comment.Actions>
+    <Comment.Resolve />
+    <Comment.Resolve label="Re-open thread" />
+  </Comment.Actions>
+</Comment>
+```
+
+## Additional components
+
+[Composer values, focus and external submission](./docs/composer.md).

package/dist/index.d.mts

@@ -1,52 +1,167 @@
-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 }: 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;
+};
 
-declare function CommentMention({ peopleList, }: {
-    peopleList?: 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,52 +1,167 @@
-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 }: 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;
+};
 
-declare function CommentMention({ peopleList, }: {
-    peopleList?: 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 };