@djangocfg/ui-tools 2.1.376 → 2.1.377

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.376",
+  "version": "2.1.377",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -156,8 +156,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.376",
-    "@djangocfg/ui-core": "^2.1.376",
+    "@djangocfg/i18n": "^2.1.377",
+    "@djangocfg/ui-core": "^2.1.377",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -211,10 +211,10 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.376",
+    "@djangocfg/i18n": "^2.1.377",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.376",
-    "@djangocfg/ui-core": "^2.1.376",
+    "@djangocfg/typescript-config": "^2.1.377",
+    "@djangocfg/ui-core": "^2.1.377",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/Chat/README.md

@@ -342,6 +342,48 @@ Options:
 The hook only fires on the `true → false` edge — flipping `enabled`
 mid-stream won't steal focus.
 
+## Draft sanitation (pre-submit)
+
+`useChatComposer.submit()` cleans the draft before handing it to your
+`onSubmit` — mirroring what ChatGPT / Claude / Telegram ship. The
+helper is also exported standalone for custom composers:
+
+```ts
+import { sanitizeDraft, isSubmittableDraft } from '@djangocfg/ui-tools'
+
+sanitizeDraft('  \n\nhello   world​\n  ')   // → 'hello   world'
+isSubmittableDraft('   \n  ')                     // → false
+```
+
+### Rules (intentionally minimal)
+
+| Rule | Action | Why |
+|---|---|---|
+| Trim outer whitespace | ✅ | Stray newlines/spaces at the edges are never intentional. |
+| Normalise `\r\n` / `\r` → `\n` | ✅ | Deterministic shape for LLM tokeniser + markdown render. |
+| Strip ZWSP / ZWNJ / ZWJ / BOM | ✅ | Pasted from rich web pages, invisible, break tokenisation. |
+| **Collapse internal whitespace runs** | ❌ | Would mangle code indentation. |
+| **Cap consecutive blank lines** | ❌ | Could be intentional separator (markdown / structured prompt). |
+| **Strip bidi overrides** (LRM/RLM/U+202A..E) | ❌ | Legitimately used in Arabic/Hebrew RTL content. |
+| Touch tabs vs spaces, emoji, mentions, URLs | ❌ | Passthrough. |
+
+Idempotent: `sanitizeDraft(sanitizeDraft(x)) === sanitizeDraft(x)`.
+
+### Escape hatch — `preserveExactValue`
+
+Niche flows (clipboard inspector, raw-prompt debug tool) want
+byte-perfect passthrough. Opt out per-composer:
+
+```ts
+const composer = useChatComposer({
+  onSubmit,
+  preserveExactValue: true,   // skip sanitation; raw textarea value goes through
+})
+```
+
+`canSubmit` still gates on `value.trim().length > 0` in this mode —
+an empty message is rarely intentional even when sanitation is off.
+
 ## Attachment renderers (registry)
 
 `<Attachments>` and `<ChatRoot>` accept a per-type renderer map. Default tile is used when no renderer matches. Plug in heavy viewers (`LazyAudioPlayer`, `LazyImageViewer`, `LazyMap`) host-side without forcing `ui-tools/Chat` to depend on them.
@@ -532,6 +574,9 @@ type ToolPayloadMatcher, type ToolPayloadFallback
 // Lightbox helpers
 collectImageAttachments
 
+// Draft sanitation (pre-submit cleanup; see "Draft sanitation" above)
+sanitizeDraft, isSubmittableDraft
+
 // Context
 ChatProvider, useChatContext, useChatContextOptional,
 type ComposerHandle
@@ -563,6 +608,12 @@ LazyChat
 | `↓`                | Recall next                             |
 | `Esc`              | (host-bound) cancel stream              |
 
+> **Custom composers built on `MarkdownEditor`:** pass `onSubmit` to
+> the editor for the same behaviour. A React `onKeyDown` wrapper does
+> NOT reliably intercept Enter before Tiptap commits the HardBreak
+> — see `MarkdownEditor/README.md#submit-on-enter` for the full
+> incident write-up and the keymap-extension fix.
+
 ## Performance
 
 - **Token coalescing.** `createTokenBuffer` aggregates stream chunks within ~16ms before dispatching → ≤1 render per frame.

package/src/tools/Chat/hooks/useChatComposer.ts

@@ -13,6 +13,7 @@ import {
 
 import type { ChatAttachment } from '../types';
 import { LIMITS } from '../config';
+import { sanitizeDraft } from '../utils/sanitizeDraft';
 
 export interface UseChatComposerOptions {
   onSubmit: (content: string, attachments: ChatAttachment[]) => void | Promise<void>;
@@ -34,6 +35,14 @@ export interface UseChatComposerOptions {
    * exactly as before. Plan64.
    */
   persistKey?: string;
+  /**
+   * Skip pre-submit draft sanitation (trim + line-ending normalise +
+   * zero-width strip). Default `false` — sanitation matches what
+   * ChatGPT / Claude / Telegram ship and is what consumers want 99% of
+   * the time. Set to `true` for niche flows that need byte-perfect
+   * passthrough (clipboard inspector, raw-prompt debug tool).
+   */
+  preserveExactValue?: boolean;
 }
 
 export interface UseChatComposerReturn {
@@ -73,6 +82,7 @@ export function useChatComposer(options: UseChatComposerOptions): UseChatCompose
     history = { enabled: true, size: LIMITS.composerHistorySize },
     onPasteFiles,
     persistKey,
+    preserveExactValue = false,
   } = options;
 
   // Hydrate draft from sessionStorage on mount when a key is provided.
@@ -135,26 +145,39 @@ export function useChatComposer(options: UseChatComposerOptions): UseChatCompose
   }, []);
 
   const submit = useCallback(async () => {
-    const trimmed = value.trim();
-    if ((!trimmed && attachments.length === 0) || isSubmitting || disabled) return;
+    // Sanitise BEFORE the empty-guard so a draft of only whitespace
+    // (`   \n\n   `) is treated as empty — saves a round trip for
+    // "send" attempts that would produce nothing.
+    //
+    // sanitizeDraft is intentionally conservative: trim outer
+    // whitespace, normalise line endings, strip zero-width chars.
+    // It does NOT collapse internal whitespace or cap blank lines
+    // (would break code indentation / intentional separators). See
+    // utils/sanitizeDraft.ts for the full ruleset + rationale.
+    //
+    // The cleaned text is what reaches `onSubmit` (matches ChatGPT /
+    // Claude / Telegram behaviour — the bubble shows what the user
+    // last saw, sans accidental trailing whitespace). Niche callers
+    // can opt out via `preserveExactValue`.
+    const cleaned = preserveExactValue ? value : sanitizeDraft(value);
+    if ((!cleaned && attachments.length === 0) || isSubmitting || disabled) return;
     setIsSubmitting(true);
     try {
-      if (history.enabled !== false && trimmed) {
+      if (history.enabled !== false && cleaned) {
         const buf = historyRef.current.items;
-        if (buf[buf.length - 1] !== trimmed) {
-          buf.push(trimmed);
+        if (buf[buf.length - 1] !== cleaned) {
+          buf.push(cleaned);
           if (buf.length > (history.size ?? LIMITS.composerHistorySize)) buf.shift();
         }
         historyRef.current.index = -1;
       }
       const snapshot = [...attachments];
-      const text = value;
       reset();
-      await onSubmit(text, snapshot);
+      await onSubmit(cleaned, snapshot);
     } finally {
       setIsSubmitting(false);
     }
-  }, [value, attachments, isSubmitting, disabled, history, onSubmit, reset]);
+  }, [value, attachments, isSubmitting, disabled, history, onSubmit, reset, preserveExactValue]);
 
   const addAttachment = useCallback(
     (a: ChatAttachment) => {
@@ -236,8 +259,17 @@ export function useChatComposer(options: UseChatComposerOptions): UseChatCompose
     [onPasteFiles],
   );
 
+  // canSubmit mirrors what submit() will actually do — gate the Send
+  // button on the post-sanitation result so a whitespace-only draft
+  // renders Send as disabled (no false-hope affordance).
+  // preserveExactValue callers fall back to raw .trim() — they
+  // opted out of sanitation, but we still don't enable Send on a
+  // pure-whitespace draft (an empty message is rarely intentional).
   const canSubmit =
-    !disabled && !isSubmitting && (value.trim().length > 0 || attachments.length > 0);
+    !disabled && !isSubmitting && (
+      (preserveExactValue ? value.trim().length : sanitizeDraft(value).length) > 0
+      || attachments.length > 0
+    );
 
   return {
     value,

package/src/tools/Chat/index.ts

@@ -113,6 +113,11 @@ export {
 export { useChatLightbox, type UseChatLightboxReturn, type ChatLightboxState } from './hooks';
 export { collectImageAttachments } from './utils/collectImageAttachments';
 
+// Draft sanitation — trim, collapse runs, strip zero-width chars.
+// Wire into your composer's submit handler / Send-button gate so
+// empty-after-cleanup drafts don't fire bogus messages.
+export { sanitizeDraft, isSubmittableDraft } from './utils/sanitizeDraft';
+
 // Dev logger (consola-based, namespace "chat:*")
 export { getChatLogger, type ChatLogger, type ChatLogScope } from './core/logger';
 

package/src/tools/Chat/utils/sanitizeDraft.ts

@@ -0,0 +1,72 @@
+/**
+ * sanitizeDraft — minimal pre-submit cleanup for chat-composer drafts.
+ *
+ * Mirrors the conservative behaviour ChatGPT / Claude / Telegram
+ * actually ship: clean the obvious junk the user didn't intend to
+ * send, touch nothing that *could* be intentional.
+ *
+ * **What we DO touch:**
+ *
+ *   1. Trim leading/trailing whitespace (spaces, tabs, newlines,
+ *      NBSP). The user typing `\n\n   hello   \n` meant `hello`.
+ *   2. Normalise line endings — `\r\n` / `\r` → `\n`. Pasted Windows
+ *      / old-mac text gets the same internal shape, so the LLM
+ *      tokeniser and markdown renderer see one canonical form.
+ *   3. Strip zero-width / invisible characters that web-paste
+ *      smuggles in: ZWSP (U+200B), ZWNJ (U+200C), ZWJ (U+200D),
+ *      BOM / ZWNBSP (U+FEFF). They're invisible, break LLM
+ *      tokenisation, and the user never meant to type them.
+ *
+ * **What we DO NOT touch (and why):**
+ *
+ *   - **Internal whitespace runs** (3+ spaces, tabs, blank lines).
+ *     Code indentation depends on these. ChatGPT preserves them as
+ *     typed — "  if (x):\n    return" stays four-space-indented.
+ *     Collapsing them is the path to subtly broken code snippets.
+ *
+ *   - **Bidi override marks** (U+200E LRM, U+200F RLM, U+202A..U+202E).
+ *     Legitimately used in Arabic / Hebrew / mixed-direction text.
+ *     Stripping silently breaks RTL users. If a specific deployment
+ *     wants to block them as a security measure, do it at that layer
+ *     with explicit user-visible feedback.
+ *
+ *   - **Tabs vs spaces** beyond rule 1. Could be either code or
+ *     prose; without parsing markdown we can't tell.
+ *
+ *   - **Emoji, mentions, URLs, code spans** — passthrough text.
+ *
+ * The function is intentionally tiny — every rule earns its keep
+ * with a concrete "user pasted X from Y, got nonsense" story.
+ *
+ * **Idempotent**: `sanitizeDraft(sanitizeDraft(x)) === sanitizeDraft(x)`.
+ */
+export function sanitizeDraft(input: string): string {
+  if (!input) return '';
+
+  // Strip zero-width invisibles. Done FIRST so the trim below sees
+  // the real content edges — a stray ZWSP at the start would
+  // otherwise count as non-whitespace and survive the trim.
+  // U+200B ZWSP, U+200C ZWNJ, U+200D ZWJ, U+FEFF BOM/ZWNBSP.
+  let s = input.replace(/[​‌‍]/g, '');
+
+  // Normalise line endings.
+  s = s.replace(/\r\n?/g, '\n');
+
+  // Trim outer whitespace (includes \n, \t, NBSP via String.trim).
+  s = s.trim();
+
+  return s;
+}
+
+/**
+ * Convenience predicate: true when the draft is non-empty AFTER
+ * sanitation. Use to gate Send buttons / Enter submits so an empty
+ * or whitespace-only draft never produces a real message.
+ *
+ * Cheaper than sanitizeDraft(input).length > 0 only marginally —
+ * we still allocate the cleaned string. Kept as a named helper for
+ * call-site clarity.
+ */
+export function isSubmittableDraft(input: string): boolean {
+  return sanitizeDraft(input).length > 0;
+}

package/src/tools/MarkdownEditor/MarkdownEditor.tsx

@@ -13,6 +13,7 @@ import {
 } from 'lucide-react';
 import { createMentionSuggestion } from './createMentionSuggestion';
 import { mentionPresets } from './mentionPresets';
+import { SubmitOnEnter } from './submitOnEnter';
 import type { MentionAttrs, MentionConfig } from './types';
 import './styles.css';
 
@@ -68,6 +69,25 @@ export interface MarkdownEditorProps {
   mentions?: MentionConfig;
   /** Called when mentioned IDs change */
   onMentionIdsChange?: (ids: string[]) => void;
+  /**
+   * Called when the user presses Enter (without Shift, no IME
+   * composition, no mention popover open). When set, Enter submits
+   * and Shift+Enter inserts a newline — ChatGPT / Telegram chat
+   * behaviour. When omitted, Enter behaves as Tiptap default
+   * (HardBreak).
+   *
+   * Implementation lives in `submitOnEnter.ts` — it's a Tiptap
+   * keymap extension, NOT a React wrapper handler. Wrapper-level
+   * onKeyDown fires AFTER ProseMirror's keymap commits HardBreak in
+   * the same tick; routing through the extension lets us intercept
+   * before HardBreak runs.
+   *
+   * Return value (optional): truthy / undefined = consume the key
+   * (default). Return `false` from onSubmit to let Tiptap fall
+   * through to HardBreak — useful for guards like "don't submit an
+   * empty draft".
+   */
+  onSubmit?: () => boolean | void;
 }
 
 // ── Component ──
@@ -82,7 +102,15 @@ export function MarkdownEditor({
   showToolbar = true,
   mentions,
   onMentionIdsChange,
+  onSubmit,
 }: MarkdownEditorProps) {
+  // Keep the latest onSubmit in a ref so the Tiptap extension's
+  // keymap closure always calls the freshest handler — Tiptap's
+  // useEditor initialises extensions ONCE on first render. Without
+  // the ref the extension would call a stale onSubmit (e.g. one
+  // that references an outdated `value`).
+  const onSubmitRef = useRef(onSubmit);
+  onSubmitRef.current = onSubmit;
   const isExternalUpdate = useRef(false);
 
   // ── Dev-mode trap detector ──
@@ -115,6 +143,18 @@ export function MarkdownEditor({
       StarterKit.configure({ heading: { levels: [1, 2, 3] } }),
       Placeholder.configure({ placeholder }),
       Markdown,
+      // SubmitOnEnter — when the consumer wired an onSubmit, intercept
+      // Enter at the keymap level (before StarterKit's HardBreak).
+      // The extension calls through `onSubmitRef.current` so handler
+      // identity changes don't require an editor rebuild. See
+      // submitOnEnter.ts for the keymap-vs-wrapper-handler rationale.
+      SubmitOnEnter.configure({
+        onSubmit: () => {
+          const h = onSubmitRef.current;
+          if (!h) return false; // no handler → let Tiptap insert HardBreak
+          return h();
+        },
+      }),
     ];
 
     if (mentions) {

package/src/tools/MarkdownEditor/README.md

@@ -58,6 +58,7 @@ import '@djangocfg/ui-tools/dist.css';
 | `showToolbar` | `boolean` | `true` | Show formatting toolbar |
 | `mentions` | `MentionConfig` | — | `@`-mention autocomplete config |
 | `onMentionIdsChange` | `(ids: string[]) => void` | — | Called when mentioned IDs change |
+| `onSubmit` | `() => boolean \| void` | — | Enter handler — when set, Enter submits and Shift+Enter inserts a newline (ChatGPT / Telegram chat behaviour). Return `false` to fall back to default HardBreak. See [Submit on Enter](#submit-on-enter) below. |
 
 ### `MentionConfig` fields
 
@@ -142,6 +143,39 @@ Either `id` or `label` may be empty strings if upstream config didn't populate t
 
 > Mentions are write-only: the markdown isn't parsed back into mention nodes on `setContent`. After submit/reset, the editor receives a plain string — fine for chat composers.
 
+## Submit on Enter
+
+For chat composers you usually want **Enter = send**, **Shift+Enter = newline** — ChatGPT / Telegram / Slack behaviour. Pass an `onSubmit` and that's what you get:
+
+```tsx
+<MarkdownEditor
+  value={text}
+  onChange={setText}
+  onSubmit={() => {
+    if (!text.trim()) return false   // fall back to HardBreak
+    void send(text)
+    // returning undefined (or true) consumes the key — newline isn't inserted
+  }}
+/>
+```
+
+### How it works (and why a Tiptap extension, not a React onKeyDown)
+
+The implementation lives in `submitOnEnter.ts` — a Tiptap `Extension` that registers a keyboard shortcut via `addKeyboardShortcuts`. It runs **inside ProseMirror's keymap pipeline at higher priority than StarterKit's HardBreak**, so we intercept Enter **before** the hard-break transaction is dispatched.
+
+A naïve wrapper handler (`<div onKeyDownCapture={...}>` calling `preventDefault`) does NOT work reliably: ProseMirror's keymap is a plugin inside the editor, which fires its handler in the same event tick as the React capture phase but **commits the HardBreak transaction before React's stopPropagation gets a chance to matter**. The user sees a hard-break flash in, then the next Enter submits — the "first Enter inserts newline" bug we shipped before this extension landed.
+
+### Behaviour details
+
+| Key | Behaviour |
+|---|---|
+| `Enter` | Calls `onSubmit()`. Returns `true`/`undefined` ⇒ consume. Returns `false` ⇒ fall through to HardBreak. |
+| `Shift+Enter` | Always inserts a newline. Bound to `() => false` so the chain falls through cleanly. |
+| Mention popover open | Enter is given to the suggestion plugin (it picks the active item) — detected by querying `.markdown-mention-list`. |
+| IME composition | Native browser composition events are not intercepted (Tiptap handles them upstream). |
+
+The handler is captured via a ref inside `MarkdownEditor`, so swapping `onSubmit` between renders is safe — the latest closure always fires, no editor rebuild needed.
+
 ## Dependencies
 
 All Tiptap packages and `@floating-ui/dom` are direct dependencies — no extra installs needed.

package/src/tools/MarkdownEditor/submitOnEnter.ts

@@ -0,0 +1,67 @@
+// SubmitOnEnter — Tiptap extension that hooks ProseMirror's keymap
+// before StarterKit's HardBreak so Enter consistently submits and
+// Shift+Enter inserts a newline (ChatGPT / Telegram behaviour).
+//
+// Why an extension and not a wrapper `onKeyDown` handler:
+//
+//   Tiptap registers its keymaps inside the ProseMirror keymap
+//   plugin, which runs in the ProseMirror dispatch pipeline. A React
+//   `onKeyDown` / `onKeyDownCapture` on a wrapper div fires AFTER
+//   ProseMirror has already committed the HardBreak transaction in
+//   the same event tick — so calling `preventDefault()` there is too
+//   late: the user sees a hard-break flash in, the React handler
+//   then runs its preventDefault, and the next Enter submits.
+//
+//   Registering the keybinding via `addKeyboardShortcuts` puts us in
+//   the same keymap pipeline at a higher priority than StarterKit's
+//   default Enter binding, so we intercept before HardBreak runs.
+//
+// The handler also respects IME composition and the mention popover
+// (Tiptap's suggestion plugin captures Enter when its popover is
+// open — we mirror that by checking `.markdown-mention-list` in the
+// DOM; same predicate the wrapper used).
+
+import { Extension } from '@tiptap/core';
+
+export interface SubmitOnEnterOptions {
+  /** Fired when Enter is pressed without Shift, no IME composition,
+   *  and no mention popover open. Return `true` to consume the key
+   *  (default behaviour), `false` to let ProseMirror handle it (i.e.
+   *  fall back to HardBreak). */
+  onSubmit: () => boolean | void;
+}
+
+export const SubmitOnEnter = Extension.create<SubmitOnEnterOptions>({
+  name: 'submitOnEnter',
+
+  addOptions() {
+    return {
+      // Default no-op — explicit consumer must override. We never
+      // intercept Enter unless an onSubmit is wired, so leaving the
+      // extension installed with no handler is safe.
+      onSubmit: () => false,
+    };
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      Enter: () => {
+        // Mention suggestion popover owns Enter while open.
+        // The suggestion plugin renders the list with this class
+        // (see createMentionSuggestion.ts).
+        if (typeof document !== 'undefined' && document.querySelector('.markdown-mention-list')) {
+          return false;
+        }
+        const result = this.options.onSubmit();
+        // Default: consume the key (true). Only let it fall through
+        // to HardBreak if onSubmit explicitly returned false.
+        return result !== false;
+      },
+      // Shift+Enter — always insert a newline. Tiptap's StarterKit
+      // already binds this to HardBreak; we re-bind to `false` (not
+      // handled) so the chain falls through cleanly even if other
+      // extensions try to grab Shift+Enter.
+      'Shift-Enter': () => false,
+    };
+  },
+});

package/dist/ChatRoot-F5XXERXU.cjs

@@ -1,14 +0,0 @@
-'use strict';
-
-var chunkUVIFD3TH_cjs = require('./chunk-UVIFD3TH.cjs');
-require('./chunk-XACCHZH2.cjs');
-require('./chunk-OLISEQHS.cjs');
-
-
-
-Object.defineProperty(exports, "ChatRoot", {
-  enumerable: true,
-  get: function () { return chunkUVIFD3TH_cjs.ChatRoot; }
-});
-//# sourceMappingURL=ChatRoot-F5XXERXU.cjs.map
-//# sourceMappingURL=ChatRoot-F5XXERXU.cjs.map

package/dist/ChatRoot-T7D7QRCH.mjs

@@ -1,5 +0,0 @@
-export { ChatRoot } from './chunk-JXBEKSNT.mjs';
-import './chunk-NWUT327A.mjs';
-import './chunk-N2XQF2OL.mjs';
-//# sourceMappingURL=ChatRoot-T7D7QRCH.mjs.map
-//# sourceMappingURL=ChatRoot-T7D7QRCH.mjs.map