@djangocfg/ui-tools 2.1.241 → 2.1.242

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.241",
+  "version": "2.1.242",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -85,26 +85,34 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.241",
-    "@djangocfg/ui-core": "^2.1.241",
+    "@djangocfg/i18n": "^2.1.242",
+    "@djangocfg/ui-core": "^2.1.242",
+    "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "tailwindcss": "^4.1.18",
-    "zustand": "^5.0.0",
-    "consola": "^3.4.2"
+    "zustand": "^5.0.0"
   },
   "dependencies": {
-    "@rpldy/uploady": "^1.8.5",
+    "@tiptap/core": "^3.20.1",
+    "@tiptap/react": "^3.20.1",
+    "@tiptap/starter-kit": "^3.20.1",
+    "@tiptap/extension-placeholder": "^3.20.1",
+    "@tiptap/extension-mention": "^3.20.1",
+    "@tiptap/suggestion": "^3.20.1",
+    "@tiptap/markdown": "^3.20.1",
+    "@tiptap/pm": "^3.20.1",
     "@rjsf/core": "^6.1.2",
     "@rjsf/utils": "^6.1.2",
     "@rjsf/validator-ajv8": "^6.1.2",
+    "@rpldy/uploady": "^1.8.5",
     "@vidstack/react": "next",
     "@wavesurfer/react": "^1.0.12",
-    "monaco-editor": "^0.55.1",
     "maplibre-gl": "^4.7.1",
     "media-icons": "next",
     "mermaid": "^11.12.0",
+    "monaco-editor": "^0.55.1",
     "prism-react-renderer": "^2.4.1",
     "react-json-tree": "^0.20.0",
     "react-lottie-player": "^2.1.0",
@@ -120,10 +128,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.241",
+    "@djangocfg/i18n": "^2.1.242",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.241",
-    "@djangocfg/ui-core": "^2.1.241",
+    "@djangocfg/typescript-config": "^2.1.242",
+    "@djangocfg/ui-core": "^2.1.242",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

package/src/tools/MarkdownEditor/MarkdownEditor.story.tsx

@@ -0,0 +1,119 @@
+import { defineStory } from '@djangocfg/playground';
+import { MarkdownEditor } from './MarkdownEditor';
+import { useState } from 'react';
+import type { MentionConfig } from './types';
+
+export default defineStory({
+  title: 'Tools/Markdown Editor',
+  component: MarkdownEditor,
+  description: 'WYSIWYG markdown editor with Tiptap. Supports headings, lists, mentions, and more.',
+});
+
+const SAMPLE_MARKDOWN = `# Character Bio
+
+**Type:** Maltipoo (apricot coat)
+**Age:** 3 years
+
+## Visual Design
+
+Medium-small Maltipoo, compact and agile.
+
+- Sharp, intelligent eyes (dark brown)
+- Simple collar (hides micro-gear)
+- Expressions shift quickly
+
+## Personality
+
+> Pixar Note: Her face must carry duality.
+
+1. Emotionally guarded
+2. Independent and decisive
+3. Dry sense of humor
+`;
+
+const MENTION_ITEMS: MentionConfig = {
+  items: [
+    { id: '1', label: 'Alice', description: 'Protagonist', thumbnail: 'https://i.pravatar.cc/48?u=alice' },
+    { id: '2', label: 'Bob', description: 'Antagonist', thumbnail: 'https://i.pravatar.cc/48?u=bob' },
+    { id: '3', label: 'Charlie', description: 'Side character', thumbnail: 'https://i.pravatar.cc/48?u=charlie' },
+    { id: '4', label: 'Diana', description: 'Narrator' },
+    { id: '5', label: 'Eve', description: 'Mystery character' },
+  ],
+};
+
+export function Default() {
+  const [value, setValue] = useState(SAMPLE_MARKDOWN);
+  return (
+    <div style={{ maxWidth: 700 }}>
+      <MarkdownEditor value={value} onChange={setValue} />
+      <RawPreview value={value} />
+    </div>
+  );
+}
+
+export function WithMentions() {
+  const [value, setValue] = useState('Hello @Alice! This scene features @Bob too.\n\nType @ to mention characters.');
+  const [ids, setIds] = useState<string[]>([]);
+
+  return (
+    <div style={{ maxWidth: 700 }}>
+      <MarkdownEditor
+        value={value}
+        onChange={setValue}
+        mentions={MENTION_ITEMS}
+        onMentionIdsChange={setIds}
+        placeholder="Describe the scene... Use @ to mention characters"
+      />
+      {ids.length > 0 && (
+        <div style={{ marginTop: 8, fontSize: 12, opacity: 0.6 }}>
+          Mentioned IDs: {ids.join(', ')}
+        </div>
+      )}
+      <RawPreview value={value} />
+    </div>
+  );
+}
+
+export function Empty() {
+  const [value, setValue] = useState('');
+  return (
+    <div style={{ maxWidth: 600 }}>
+      <MarkdownEditor value={value} onChange={setValue} placeholder="Start writing..." />
+    </div>
+  );
+}
+
+export function Disabled() {
+  return (
+    <div style={{ maxWidth: 600 }}>
+      <MarkdownEditor value="This editor is **read-only**." onChange={() => {}} disabled />
+    </div>
+  );
+}
+
+export function NoToolbar() {
+  const [value, setValue] = useState('Plain text without toolbar.\n\nStill supports **markdown** shortcuts.');
+  return (
+    <div style={{ maxWidth: 600 }}>
+      <MarkdownEditor value={value} onChange={setValue} showToolbar={false} />
+    </div>
+  );
+}
+
+export function Compact() {
+  const [value, setValue] = useState('Short note');
+  return (
+    <div style={{ maxWidth: 400 }}>
+      <MarkdownEditor value={value} onChange={setValue} minHeight={60} placeholder="Quick note..." />
+    </div>
+  );
+}
+
+function RawPreview({ value }: { value: string }) {
+  return (
+    <details style={{ marginTop: 16 }}>
+      <summary style={{ cursor: 'pointer', opacity: 0.5, fontSize: 12 }}>Raw markdown</summary>
+      <pre style={{ fontSize: 11, opacity: 0.6, whiteSpace: 'pre-wrap', marginTop: 8 }}>{value}</pre>
+    </details>
+  );
+}

package/src/tools/MarkdownEditor/MarkdownEditor.tsx

@@ -0,0 +1,174 @@
+'use client';
+
+import { useEditor, EditorContent, type Editor } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+import Placeholder from '@tiptap/extension-placeholder';
+import Mention from '@tiptap/extension-mention';
+import { Markdown } from '@tiptap/markdown';
+import type { AnyExtension } from '@tiptap/core';
+import { useEffect, useRef, useMemo } from 'react';
+import {
+  Bold, Italic, Strikethrough, Heading1, Heading2, Heading3,
+  List, ListOrdered, Quote, Minus, Code, type LucideIcon,
+} from 'lucide-react';
+import { createMentionSuggestion } from './createMentionSuggestion';
+import type { MentionConfig } from './types';
+import './styles.css';
+
+// ── Helpers ──
+
+interface MarkdownManager {
+  serialize: (json: Record<string, unknown>) => string;
+}
+
+function getMarkdown(editor: Editor): string {
+  const storage = editor.storage.markdown as { manager?: MarkdownManager } | undefined;
+  if (!storage?.manager) return editor.getText();
+  return storage.manager.serialize(editor.getJSON());
+}
+
+function extractMentionIds(editor: Editor): string[] {
+  const ids: string[] = [];
+  editor.state.doc.descendants((node) => {
+    if (node.type.name === 'mention' && node.attrs.id) {
+      ids.push(node.attrs.id as string);
+    }
+  });
+  return [...new Set(ids)];
+}
+
+// ── Types ──
+
+export interface MarkdownEditorProps {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  minHeight?: number;
+  className?: string;
+  disabled?: boolean;
+  showToolbar?: boolean;
+  /** @mention autocomplete config */
+  mentions?: MentionConfig;
+  /** Called when mentioned IDs change */
+  onMentionIdsChange?: (ids: string[]) => void;
+}
+
+// ── Component ──
+
+export function MarkdownEditor({
+  value,
+  onChange,
+  placeholder = 'Write markdown...',
+  minHeight = 120,
+  className = '',
+  disabled = false,
+  showToolbar = true,
+  mentions,
+  onMentionIdsChange,
+}: MarkdownEditorProps) {
+  const isExternalUpdate = useRef(false);
+
+  const extensions = useMemo(() => {
+    const exts: AnyExtension[] = [
+      StarterKit.configure({ heading: { levels: [1, 2, 3] } }),
+      Placeholder.configure({ placeholder }),
+      Markdown,
+    ];
+
+    if (mentions) {
+      exts.push(
+        Mention.configure({
+          HTMLAttributes: { class: 'markdown-mention' },
+          suggestion: createMentionSuggestion(mentions),
+          renderText: ({ node }) => `@${node.attrs.label}`,
+        }),
+      );
+    }
+
+    return exts;
+  }, [placeholder, mentions]);
+
+  const editor = useEditor({
+    immediatelyRender: false,
+    editable: !disabled,
+    extensions,
+    content: value,
+    onUpdate: ({ editor }) => {
+      if (isExternalUpdate.current) return;
+      onChange(getMarkdown(editor));
+
+      if (onMentionIdsChange) {
+        onMentionIdsChange(extractMentionIds(editor));
+      }
+    },
+    editorProps: {
+      attributes: {
+        class: 'markdown-editor-content focus:outline-none text-sm',
+        style: `min-height: ${minHeight}px`,
+      },
+    },
+  });
+
+  useEffect(() => {
+    if (!editor) return;
+    const current = getMarkdown(editor);
+    if (current !== value) {
+      isExternalUpdate.current = true;
+      editor.commands.setContent(value);
+      isExternalUpdate.current = false;
+    }
+  }, [value, editor]);
+
+  const wrapperClass = `markdown-editor rounded-md border border-input bg-background ${disabled ? 'opacity-60' : ''} ${className}`.trim();
+
+  return (
+    <div className={wrapperClass}>
+      {showToolbar && editor && <MarkdownToolbar editor={editor} />}
+      <div className="px-3 py-2">
+        <EditorContent editor={editor} />
+      </div>
+    </div>
+  );
+}
+
+// ── Toolbar ──
+
+interface ToolbarItem {
+  icon: LucideIcon;
+  action: () => void;
+  active: boolean;
+  title: string;
+}
+
+function MarkdownToolbar({ editor }: { editor: Editor }) {
+  const items = useMemo<(ToolbarItem | null)[]>(() => [
+    { icon: Bold, title: 'Bold', action: () => editor.chain().focus().toggleBold().run(), active: editor.isActive('bold') },
+    { icon: Italic, title: 'Italic', action: () => editor.chain().focus().toggleItalic().run(), active: editor.isActive('italic') },
+    { icon: Strikethrough, title: 'Strike', action: () => editor.chain().focus().toggleStrike().run(), active: editor.isActive('strike') },
+    { icon: Code, title: 'Code', action: () => editor.chain().focus().toggleCode().run(), active: editor.isActive('code') },
+    null,
+    { icon: Heading1, title: 'H1', action: () => editor.chain().focus().toggleHeading({ level: 1 }).run(), active: editor.isActive('heading', { level: 1 }) },
+    { icon: Heading2, title: 'H2', action: () => editor.chain().focus().toggleHeading({ level: 2 }).run(), active: editor.isActive('heading', { level: 2 }) },
+    { icon: Heading3, title: 'H3', action: () => editor.chain().focus().toggleHeading({ level: 3 }).run(), active: editor.isActive('heading', { level: 3 }) },
+    null,
+    { icon: List, title: 'Bullet list', action: () => editor.chain().focus().toggleBulletList().run(), active: editor.isActive('bulletList') },
+    { icon: ListOrdered, title: 'Ordered list', action: () => editor.chain().focus().toggleOrderedList().run(), active: editor.isActive('orderedList') },
+    { icon: Quote, title: 'Quote', action: () => editor.chain().focus().toggleBlockquote().run(), active: editor.isActive('blockquote') },
+    { icon: Minus, title: 'Divider', action: () => editor.chain().focus().setHorizontalRule().run(), active: false },
+  ], [editor]);
+
+  return (
+    <div className="flex items-center gap-0.5 px-2 py-1.5 border-b border-border">
+      {items.map((item, i) => {
+        if (!item) return <div key={i} className="w-px h-4 bg-border mx-1" />;
+        const Icon = item.icon;
+        const btnClass = `markdown-toolbar-btn ${item.active ? 'active' : ''}`;
+        return (
+          <button key={i} type="button" onClick={item.action} title={item.title} className={btnClass}>
+            <Icon style={{ width: 14, height: 14 }} />
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/tools/MarkdownEditor/MentionList.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import { forwardRef, useImperativeHandle, useState, useCallback, useEffect, type KeyboardEvent } from 'react';
+import type { MentionItem } from './types';
+
+export interface MentionListRef {
+  onKeyDown: (event: KeyboardEvent) => boolean;
+}
+
+interface MentionListProps {
+  items: MentionItem[];
+  command: (item: MentionItem) => void;
+}
+
+export const MentionList = forwardRef<MentionListRef, MentionListProps>(
+  ({ items, command }, ref) => {
+    const [selectedIndex, setSelectedIndex] = useState(0);
+
+    useEffect(() => setSelectedIndex(0), [items]);
+
+    const select = useCallback(
+      (index: number) => {
+        const item = items[index];
+        if (item) command(item);
+      },
+      [items, command],
+    );
+
+    useImperativeHandle(ref, () => ({
+      onKeyDown: (event: KeyboardEvent) => {
+        if (event.key === 'ArrowUp') {
+          setSelectedIndex((i) => (i + items.length - 1) % items.length);
+          return true;
+        }
+        if (event.key === 'ArrowDown') {
+          setSelectedIndex((i) => (i + 1) % items.length);
+          return true;
+        }
+        if (event.key === 'Enter') {
+          select(selectedIndex);
+          return true;
+        }
+        return false;
+      },
+    }));
+
+    if (items.length === 0) return null;
+
+    return (
+      <div className="markdown-mention-list">
+        {items.map((item, i) => {
+          const isSelected = i === selectedIndex;
+          const cls = `markdown-mention-item ${isSelected ? 'selected' : ''}`;
+          return (
+            <button key={item.id} type="button" className={cls} onClick={() => select(i)}>
+              {item.thumbnail && (
+                <img src={item.thumbnail} alt="" className="markdown-mention-avatar" />
+              )}
+              <div className="markdown-mention-info">
+                <span className="markdown-mention-name">{item.label}</span>
+                {item.description && (
+                  <span className="markdown-mention-desc">{item.description}</span>
+                )}
+              </div>
+            </button>
+          );
+        })}
+      </div>
+    );
+  },
+);
+
+MentionList.displayName = 'MentionList';

package/src/tools/MarkdownEditor/README.md

@@ -0,0 +1,68 @@
+# MarkdownEditor
+
+WYSIWYG markdown editor based on Tiptap. Renders markdown visually (headings, lists, blockquotes) while editing, serializes to markdown string.
+
+## Features
+
+- Visual headings (H1, H2, H3) with proper sizing
+- Bold, italic, strikethrough, inline code
+- Bullet and ordered lists
+- Blockquotes with left border
+- Horizontal rules
+- Toolbar with icon buttons
+- Markdown input/output (stored as plain markdown string)
+- SSR-safe (`immediatelyRender: false`)
+
+## Quick Start
+
+```tsx
+import { MarkdownEditor } from '@djangocfg/ui-tools';
+
+function MyComponent() {
+  const [bio, setBio] = useState('# Hello\n\nThis is **markdown**.');
+
+  return (
+    <MarkdownEditor
+      value={bio}
+      onChange={setBio}
+      placeholder="Write something..."
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | Markdown string |
+| `onChange` | `(value: string) => void` | — | Called on every change |
+| `placeholder` | `string` | `'Write markdown...'` | Placeholder text |
+| `minHeight` | `number` | `120` | Min height in px |
+| `className` | `string` | — | Additional CSS class |
+| `disabled` | `boolean` | `false` | Read-only mode |
+| `showToolbar` | `boolean` | `true` | Show formatting toolbar |
+| `mentions` | `MentionConfig` | — | @mention autocomplete config |
+| `onMentionIdsChange` | `(ids: string[]) => void` | — | Called when mentioned IDs change |
+
+## Mentions
+
+```tsx
+<MarkdownEditor
+  value={text}
+  onChange={setText}
+  mentions={{
+    items: [
+      { id: '1', label: 'Alice', thumbnail: '/alice.jpg' },
+      { id: '2', label: 'Bob', description: 'Antagonist' },
+    ],
+  }}
+  onMentionIdsChange={(ids) => console.log('Mentioned:', ids)}
+/>
+```
+
+Type `@` to trigger autocomplete. Mentions render as inline chips.
+
+## Dependencies
+
+All Tiptap packages are included as direct dependencies — no extra installs needed.

package/src/tools/MarkdownEditor/createMentionSuggestion.ts

@@ -0,0 +1,81 @@
+import { ReactRenderer } from '@tiptap/react';
+import type { SuggestionOptions } from '@tiptap/suggestion';
+import { MentionList, type MentionListRef } from './MentionList';
+import type { MentionItem, MentionConfig } from './types';
+
+export function createMentionSuggestion(
+  config: MentionConfig,
+): Omit<SuggestionOptions<MentionItem>, 'editor'> {
+  const { maxItems = 5, trigger = '@' } = config;
+
+  return {
+    char: trigger,
+
+    items: ({ query }) => {
+      const q = query.toLowerCase();
+      return config.items
+        .filter((item) => item.label.toLowerCase().includes(q))
+        .slice(0, maxItems);
+    },
+
+    render: () => {
+      let component: ReactRenderer<MentionListRef> | null = null;
+      let popup: HTMLDivElement | null = null;
+
+      return {
+        onStart: (props) => {
+          component = new ReactRenderer(MentionList, {
+            props: {
+              items: props.items,
+              command: (item: MentionItem) => {
+                props.command({ id: item.id, label: item.label });
+              },
+            },
+            editor: props.editor,
+          });
+
+          popup = document.createElement('div');
+          popup.style.cssText = 'position: absolute; z-index: 99999;';
+          popup.appendChild(component.element);
+
+          const rect = props.clientRect?.();
+          if (rect) {
+            popup.style.top = `${rect.bottom + window.scrollY + 4}px`;
+            popup.style.left = `${rect.left + window.scrollX}px`;
+          }
+
+          document.body.appendChild(popup);
+        },
+
+        onUpdate: (props) => {
+          component?.updateProps({
+            items: props.items,
+            command: (item: MentionItem) => {
+              props.command({ id: item.id, label: item.label });
+            },
+          });
+
+          const rect = props.clientRect?.();
+          if (rect && popup) {
+            popup.style.top = `${rect.bottom + window.scrollY + 4}px`;
+            popup.style.left = `${rect.left + window.scrollX}px`;
+          }
+        },
+
+        onKeyDown: (props) => {
+          if (props.event.key === 'Escape') {
+            popup?.remove();
+            component?.destroy();
+            return true;
+          }
+          return component?.ref?.onKeyDown(props.event as unknown as React.KeyboardEvent) ?? false;
+        },
+
+        onExit: () => {
+          popup?.remove();
+          component?.destroy();
+        },
+      };
+    },
+  };
+}

package/src/tools/MarkdownEditor/index.ts

@@ -0,0 +1,3 @@
+export { MarkdownEditor } from './MarkdownEditor';
+export type { MarkdownEditorProps } from './MarkdownEditor';
+export type { MentionItem, MentionConfig } from './types';