@wakastellar/ui 3.3.3 → 3.5.0

package/src/components/editor/waka-mention-editor.tsx

@@ -0,0 +1,459 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils/cn"
+import { Label } from "../label"
+import { Textarea } from "../textarea"
+import { Avatar, AvatarFallback, AvatarImage } from "../avatar"
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SlateNode = any
+
+/** A mentionable user entity */
+export interface MentionableUser {
+  /** Unique ID (e.g., keycloak-id or user wid) */
+  id: string
+  /** Display name */
+  name: string
+  /** Email address */
+  email?: string
+  /** Avatar URL */
+  avatar?: string
+  /** Role or title (shown in the suggestion list) */
+  role?: string
+  /** Admin level (for display badge) */
+  adminLevel?: string
+}
+
+/** Describes a mention that was inserted into the document */
+export interface InsertedMention {
+  /** The user that was mentioned */
+  user: MentionableUser
+  /** The Slate path where the mention was inserted */
+  path?: number[]
+}
+
+export interface WakaMentionEditorProps {
+  /** Initial Slate content */
+  value?: SlateNode[]
+  /** Change callback */
+  onChange?: (value: SlateNode[]) => void
+  /** Read-only mode */
+  readOnly?: boolean
+  /** Placeholder */
+  placeholder?: string
+  /** CSS class */
+  className?: string
+  /** Editor CSS class */
+  editorClassName?: string
+  /** Minimum height in px */
+  minHeight?: number
+  /** Label */
+  label?: string
+  /** Description */
+  description?: string
+  /** Error */
+  error?: string
+  /**
+   * Async search function that resolves mentionable users.
+   * Called when the user types after "@".
+   * Should return matching users from the WakaStart API.
+   */
+  onSearch: (query: string) => Promise<MentionableUser[]>
+  /**
+   * Callback when a mention is inserted.
+   * Can be used to trigger notifications.
+   */
+  onMentionInserted?: (mention: InsertedMention) => void
+  /**
+   * Trigger character for mentions. Default: "@"
+   */
+  trigger?: string
+  /**
+   * Debounce delay for the search function in ms.
+   * Default: 300
+   */
+  searchDebounceMs?: number
+  /**
+   * Maximum number of search results to show.
+   * Default: 8
+   */
+  maxResults?: number
+  /** Extra Plate plugins */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  extraPlugins?: any[]
+  /** Ref to editor instance */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  editorRef?: React.MutableRefObject<any>
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+/**
+ * WakaMentionEditor -- Rich text editor with @mention support.
+ *
+ * Integrates `@platejs/mention` to provide user mention functionality.
+ * When the user types "@", a dropdown with matching users appears.
+ * The search function is async, allowing API-backed user resolution
+ * scoped to the current tenant (Partner > Network > Customer).
+ *
+ * When a mention is inserted, the `onMentionInserted` callback fires,
+ * allowing the app to trigger notifications via ws-back-wakastart.
+ *
+ * The mention element renders as an inline pill with the user's
+ * avatar and name, styled with design system tokens.
+ *
+ * Useful for:
+ * - Spec review comments with @author mentions
+ * - Task assignment in WakaStart projects
+ * - Chat/collaboration features
+ * - Audit notes with @reviewer references
+ *
+ * @example
+ * ```tsx
+ * <WakaMentionEditor
+ *   value={content}
+ *   onChange={setContent}
+ *   onSearch={async (q) => {
+ *     const users = await usersApi.search(q);
+ *     return users.map(u => ({ id: u.wid, name: u.fullName, email: u.email }));
+ *   }}
+ *   onMentionInserted={(m) => {
+ *     notificationsApi.send(m.user.id, "You were mentioned in a document");
+ *   }}
+ * />
+ * ```
+ */
+export const WakaMentionEditor = React.forwardRef<HTMLDivElement, WakaMentionEditorProps>(
+  (
+    {
+      value,
+      onChange,
+      readOnly = false,
+      placeholder = "Tapez @ pour mentionner un utilisateur...",
+      className,
+      editorClassName,
+      minHeight = 200,
+      label,
+      description,
+      error,
+      onSearch,
+      onMentionInserted,
+      trigger = "@",
+      searchDebounceMs = 300,
+      maxResults = 8,
+      extraPlugins,
+      editorRef,
+    },
+    ref
+  ) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const [bundle, setBundle] = React.useState<any>(null)
+    const [loadError, setLoadError] = React.useState(false)
+    const [suggestions, setSuggestions] = React.useState<MentionableUser[]>([])
+    const [searching, setSearching] = React.useState(false)
+    const searchTimerRef = React.useRef<ReturnType<typeof setTimeout>>()
+
+    const configRef = React.useRef({ onSearch, trigger, searchDebounceMs, maxResults, onMentionInserted })
+    configRef.current = { onSearch, trigger, searchDebounceMs, maxResults, onMentionInserted }
+
+    // ── Load Plate + Mention ──────────────────────────────────────────────
+    React.useEffect(() => {
+      let cancelled = false
+
+      const load = async () => {
+        try {
+          const cfg = configRef.current
+
+          const [plateReact, basicNodes, tableModule, layoutModule, calloutModule, linkModule, mentionModule] =
+            await Promise.all([
+              import("platejs/react"),
+              import("@platejs/basic-nodes/react"),
+              import("@platejs/table/react"),
+              import("@platejs/layout/react"),
+              import("@platejs/callout/react"),
+              import("@platejs/link/react"),
+              import("@platejs/mention/react"),
+            ])
+
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const plugins: any[] = [
+            basicNodes.BoldPlugin, basicNodes.ItalicPlugin, basicNodes.UnderlinePlugin,
+            basicNodes.StrikethroughPlugin, basicNodes.CodePlugin, basicNodes.HighlightPlugin,
+            basicNodes.H1Plugin, basicNodes.H2Plugin, basicNodes.H3Plugin,
+            basicNodes.H4Plugin, basicNodes.BlockquotePlugin,
+            tableModule.TablePlugin, tableModule.TableRowPlugin,
+            tableModule.TableCellPlugin, tableModule.TableCellHeaderPlugin,
+            layoutModule.ColumnPlugin, layoutModule.ColumnItemPlugin,
+            calloutModule.CalloutPlugin,
+            linkModule.LinkPlugin.configure({
+              options: { allowedSchemes: ["http", "https", "mailto", "tel"] },
+            }),
+            // Mention plugin
+            mentionModule.MentionPlugin.configure({
+              options: {
+                trigger: cfg.trigger,
+                triggerPreviousCharPattern: /^$|^[\s"']$/,
+                insertSpaceAfterMention: true,
+              },
+            }),
+            mentionModule.MentionInputPlugin,
+          ]
+
+          if (!cancelled) {
+            setBundle({
+              Plate: plateReact.Plate,
+              PlateContent: plateReact.PlateContent,
+              usePlateEditor: plateReact.usePlateEditor,
+              plugins,
+            })
+          }
+        } catch (err) {
+          console.error("[WakaMentionEditor] Failed to load:", err)
+          if (!cancelled) setLoadError(true)
+        }
+      }
+
+      load()
+      return () => { cancelled = true }
+    }, [])
+
+    // ── Search handler ────────────────────────────────────────────────────
+    const handleSearch = React.useCallback(
+      (query: string) => {
+        if (searchTimerRef.current) clearTimeout(searchTimerRef.current)
+
+        if (!query.trim()) {
+          setSuggestions([])
+          setSearching(false)
+          return
+        }
+
+        setSearching(true)
+        searchTimerRef.current = setTimeout(async () => {
+          try {
+            const cfg = configRef.current
+            const results = await cfg.onSearch(query)
+            setSuggestions(results.slice(0, cfg.maxResults))
+          } catch {
+            setSuggestions([])
+          } finally {
+            setSearching(false)
+          }
+        }, configRef.current.searchDebounceMs)
+      },
+      []
+    )
+
+    // ── Render ────────────────────────────────────────────────────────────
+    if (bundle) {
+      return (
+        <MentionEditorInner
+          ref={ref}
+          bundle={bundle}
+          value={value}
+          onChange={onChange}
+          readOnly={readOnly}
+          placeholder={placeholder}
+          className={className}
+          editorClassName={editorClassName}
+          minHeight={minHeight}
+          label={label}
+          description={description}
+          error={error}
+          suggestions={suggestions}
+          searching={searching}
+          onSearch={handleSearch}
+          onMentionInserted={onMentionInserted}
+          extraPlugins={extraPlugins}
+          editorRef={editorRef}
+        />
+      )
+    }
+
+    return (
+      <div ref={ref} className={cn("space-y-1.5", className)}>
+        {label && <Label>{label}</Label>}
+        {description && <p className="text-sm text-muted-foreground">{description}</p>}
+        <div className="relative">
+          <Textarea placeholder={placeholder} disabled style={{ minHeight }} />
+          <div className="absolute inset-0 flex items-center justify-center bg-background/50 rounded-lg">
+            <span className="text-sm text-muted-foreground animate-pulse">
+              {loadError ? "Erreur (@platejs/mention requis)" : "Chargement..."}
+            </span>
+          </div>
+        </div>
+        {error && <p className="text-sm text-destructive">{error}</p>}
+      </div>
+    )
+  }
+)
+
+WakaMentionEditor.displayName = "WakaMentionEditor"
+
+// ─── Inner component ────────────────────────────────────────────────────────
+
+interface MentionEditorInnerProps {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  bundle: any
+  value?: SlateNode[]
+  onChange?: (value: SlateNode[]) => void
+  readOnly?: boolean
+  placeholder?: string
+  className?: string
+  editorClassName?: string
+  minHeight?: number
+  label?: string
+  description?: string
+  error?: string
+  suggestions: MentionableUser[]
+  searching: boolean
+  onSearch: (query: string) => void
+  onMentionInserted?: (mention: InsertedMention) => void
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  extraPlugins?: any[]
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  editorRef?: React.MutableRefObject<any>
+}
+
+const MentionEditorInner = React.forwardRef<HTMLDivElement, MentionEditorInnerProps>(
+  (
+    {
+      bundle: { Plate, PlateContent, usePlateEditor, plugins },
+      value,
+      onChange,
+      readOnly,
+      placeholder,
+      className,
+      editorClassName,
+      minHeight,
+      label,
+      description,
+      error,
+      suggestions,
+      searching,
+      extraPlugins,
+      editorRef,
+    },
+    ref
+  ) => {
+    const allPlugins = React.useMemo(
+      () => [...plugins, ...(extraPlugins ?? [])],
+      [plugins, extraPlugins]
+    )
+
+    const editor = usePlateEditor({
+      plugins: allPlugins,
+      value: value ?? [{ type: "p", children: [{ text: "" }] }],
+    })
+
+    React.useEffect(() => {
+      if (editorRef) editorRef.current = editor
+    }, [editor, editorRef])
+
+    return (
+      <div ref={ref} className={cn("space-y-1.5", className)}>
+        {label && <Label>{label}</Label>}
+        {description && <p className="text-sm text-muted-foreground">{description}</p>}
+
+        <Plate
+          editor={editor}
+          onChange={onChange ? ({ value: v }: { value: SlateNode[] }) => onChange(v) : undefined}
+          readOnly={readOnly}
+        >
+          <div className={cn(
+            "border rounded-lg overflow-hidden relative",
+            error && "border-destructive",
+          )}>
+            <div style={{ minHeight }}>
+              <PlateContent
+                placeholder={placeholder}
+                readOnly={readOnly}
+                className={cn(
+                  "prose prose-sm max-w-none p-4",
+                  "focus-within:outline-none",
+                  "[&_[data-slate-editor]]:outline-none [&_[data-slate-editor]]:min-h-[inherit]",
+                  editorClassName,
+                )}
+              />
+            </div>
+
+            {/* Mention suggestions dropdown (rendered as overlay) */}
+            {suggestions.length > 0 && (
+              <MentionSuggestions suggestions={suggestions} searching={searching} />
+            )}
+          </div>
+        </Plate>
+
+        {error && <p className="text-sm text-destructive">{error}</p>}
+      </div>
+    )
+  }
+)
+
+MentionEditorInner.displayName = "MentionEditorInner"
+
+// ─── Mention suggestions component ──────────────────────────────────────────
+
+/**
+ * Standalone mention suggestion list component.
+ * Can be used outside of WakaMentionEditor for custom integrations.
+ */
+export function MentionSuggestions({
+  suggestions,
+  searching,
+  className,
+  onSelect,
+}: {
+  suggestions: MentionableUser[]
+  searching?: boolean
+  className?: string
+  onSelect?: (user: MentionableUser) => void
+}) {
+  return (
+    <div className={cn(
+      "absolute z-50 w-64 max-h-60 overflow-y-auto",
+      "rounded-lg border bg-popover shadow-lg",
+      "p-1 mt-1",
+      className,
+    )}>
+      {searching && (
+        <div className="px-2 py-1.5 text-xs text-muted-foreground animate-pulse">
+          Recherche...
+        </div>
+      )}
+      {suggestions.map((user) => (
+        <button
+          key={user.id}
+          type="button"
+          className={cn(
+            "flex w-full items-center gap-2.5 rounded-md px-2 py-1.5 text-left",
+            "text-sm transition-colors cursor-pointer",
+            "hover:bg-accent/50",
+          )}
+          onClick={() => onSelect?.(user)}
+        >
+          <Avatar className="h-6 w-6">
+            {user.avatar && <AvatarImage src={user.avatar} alt={user.name} />}
+            <AvatarFallback className="text-[10px] bg-primary/10 text-primary">
+              {user.name.slice(0, 2).toUpperCase()}
+            </AvatarFallback>
+          </Avatar>
+          <div className="min-w-0 flex-1">
+            <div className="font-medium truncate">{user.name}</div>
+            {user.email && (
+              <div className="text-xs text-muted-foreground truncate">{user.email}</div>
+            )}
+          </div>
+          {user.role && (
+            <span className="text-[10px] text-muted-foreground shrink-0">{user.role}</span>
+          )}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+MentionSuggestions.displayName = "MentionSuggestions"