@djangocfg/ui-tools 2.1.303 → 2.1.307

package/src/components/markdown/MarkdownMessage/MarkdownMessage.story.tsx

@@ -545,6 +545,109 @@ export const KitchenSink = () => (
   </div>
 );
 
+// Soft line breaks — `remark-breaks` enabled. LLMs (Claude / GPT) and
+// chat users routinely write "joke punchline / poem stanza / dialogue"
+// blocks separated by a single `\n` rather than a blank line. CommonMark
+// would collapse those into one run-on paragraph; the chat convention
+// (ChatGPT, Slack, Discord, Linear) preserves them as `<br>`. This
+// story is the regression case for that.
+const SOFT_BREAK_JOKE = `Приходит программист к врачу:
+— Доктор, я со всеми общаюсь только через мессенджер. Даже с женой.
+— И что жена говорит?
+— Подождите, сейчас напишу и спрошу… 😄`;
+
+const SOFT_BREAK_POEM = `Roses are red,
+Violets are blue,
+This line is short,
+And so are you.`;
+
+const SOFT_BREAK_DIALOGUE = `Customer: Why is my code not working?
+Support: Have you tried turning it off and on again?
+Customer: I'm a software engineer.
+Support: Have you tried turning it off and on again?`;
+
+export const SoftLineBreaks = () => (
+  <div className="mx-auto max-w-2xl space-y-6 p-6">
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">Joke (assistant bubble)</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Single <code>\n</code> between lines should render as line
+        breaks, not collapse onto one row. This was the user-reported
+        regression — LLM punchlines surfaced as a wall of text.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="assistant" content={SOFT_BREAK_JOKE} rules={subtleRules} />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">Poem (user bubble)</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Same payload on the saturated user palette. Each line stays on
+        its own row.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="user" content={SOFT_BREAK_POEM} rules={onPrimaryRules} />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">Dialogue (assistant bubble)</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Speaker turns separated by single newlines.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="assistant" content={SOFT_BREAK_DIALOGUE} rules={subtleRules} />
+      </div>
+    </div>
+  </div>
+);
+
+// Plugin sampler — emoji shortcodes, smart typography, external link
+// hardening. Verifies the three "lightweight chat" plugins added next
+// to remark-breaks: remark-emoji, remark-smartypants, rehype-
+// external-links. Each plugin contributes one transform; this story
+// makes them visible in isolation.
+const PLUGIN_SAMPLER = `### Plugin sampler
+
+Emoji shortcodes work inline: :rocket: :tada: :+1: — alongside Unicode 🎉.
+
+Smart typography: "double quotes", 'single quotes', em-dash --, ellipsis...
+
+External link should open in a new tab: [Anthropic](https://anthropic.com).
+Internal-style link stays in place: [#section](#section).
+
+A line above —
+soft break here — should still wrap (one \\n only).
+And then a normal paragraph below.`;
+
+export const ChatPlugins = () => (
+  <div className="mx-auto max-w-2xl space-y-6 p-6">
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">Assistant bubble</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Three plugins firing at once: <code>remark-emoji</code>,
+        <code>remark-smartypants</code>, <code>rehype-external-links</code>.
+        Hover the Anthropic link — it should carry <code>target=_blank</code>
+        and <code>rel=noopener noreferrer</code> automatically.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="assistant" content={PLUGIN_SAMPLER} rules={subtleRules} />
+      </div>
+    </div>
+
+    <div>
+      <h3 className="mb-2 text-sm font-semibold">User bubble</h3>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Same payload on the saturated palette.
+      </p>
+      <div className="rounded-lg border border-border bg-card p-4">
+        <ChatBubble role="user" content={PLUGIN_SAMPLER} rules={onPrimaryRules} />
+      </div>
+    </div>
+  </div>
+);
+
 // Mermaid diagrams. Live-renders the fence body via the <Mermaid>
 // tool (lazy-loaded). Useful as a manual smoke test for: (1) the
 // `language === 'mermaid'` branch in components.tsx, (2) the SVG

package/src/components/markdown/MarkdownMessage/MarkdownMessage.tsx

@@ -2,9 +2,13 @@
 
 import React from 'react';
 import ReactMarkdown from 'react-markdown';
+import rehypeExternalLinks from 'rehype-external-links';
 import rehypeRaw from 'rehype-raw';
 import rehypeSanitize from 'rehype-sanitize';
+import remarkBreaks from 'remark-breaks';
+import remarkEmoji from 'remark-emoji';
 import remarkGfm from 'remark-gfm';
+import remarkSmartypants from 'remark-smartypants';
 import type { Components } from 'react-markdown';
 
 import { useCollapsibleContent } from '../useCollapsibleContent';
@@ -197,11 +201,32 @@ export const MarkdownMessage: React.FC<MarkdownMessageProps> = ({
         } as React.CSSProperties}
       >
         <ReactMarkdown
-          remarkPlugins={[remarkGfm]}
+          // Remark plugin order is load-bearing:
+          //   1. `remark-gfm` — tables, strikethrough, autolinks, task lists.
+          //   2. `remark-breaks` — chat convention: single `\n` → `<br>`
+          //      (ChatGPT / Slack / Discord / Linear). CommonMark's
+          //      default would collapse those into one paragraph and
+          //      LLM punchlines / poems / dialogue would render as a
+          //      run-on line. Goes BEFORE smartypants so quotes that
+          //      land at line breaks still get the curly treatment.
+          //   3. `remark-smartypants` — typographic substitutions:
+          //      "..." → …, -- → —, "x" → "x". Cheap "humanized"
+          //      polish à la Medium / Substack.
+          //   4. `remark-emoji` — `:smile:` → 😄 (GitHub / Linear
+          //      shortcode style). Leaves Unicode emoji untouched.
+          remarkPlugins={[remarkGfm, remarkBreaks, remarkSmartypants, remarkEmoji]}
           // rehype-raw parses inline HTML in the source; rehype-sanitize
           // (with our extended schema) runs after to keep XSS guards
           // (no scripts, no on* handlers, no javascript: urls).
-          rehypePlugins={[rehypeRaw, [rehypeSanitize, schema]]}
+          // rehype-external-links runs LAST so it tags every <a> that
+          // sanitize let through — externals get target=_blank +
+          // rel=noopener noreferrer in one pass, instead of every
+          // custom `a` renderer reimplementing the rule.
+          rehypePlugins={[
+            rehypeRaw,
+            [rehypeSanitize, schema],
+            [rehypeExternalLinks, { target: '_blank', rel: ['noopener', 'noreferrer'] }],
+          ]}
           components={components}
           // urlTransform runs in remark-rehype before sanitize. Without
           // overriding it, react-markdown's default strips `href` for

package/src/components/markdown/MarkdownMessage/README.md

@@ -0,0 +1,111 @@
+# MarkdownMessage
+
+Chat-tuned, read-only markdown renderer. Drop-in for any chat bubble — assistant or user.
+
+```tsx
+import { MarkdownMessage } from '@djangocfg/ui-tools';
+
+<MarkdownMessage content={text} isUser={false} />
+```
+
+## What it gives you
+
+| Feature | Source |
+|---|---|
+| GitHub Flavored Markdown — tables, strikethrough, autolinks, task lists | `remark-gfm` |
+| Single `\n` becomes a hard line break (chat convention) | `remark-breaks` |
+| Smart typography — `"…"` → `"…"`, `--` → `—`, `...` → `…` | `remark-smartypants` |
+| Emoji shortcodes — `:rocket:` → 🚀 | `remark-emoji` |
+| External links auto-tagged with `target="_blank" rel="noopener noreferrer"` | `rehype-external-links` |
+| Inline HTML, parsed and sanitized (XSS-safe) | `rehype-raw` + `rehype-sanitize` |
+| Syntax-highlighted code fences with copy button | `<PrettyCode>` |
+| Mermaid diagrams (` ```mermaid ` fence) with click-to-fullscreen | `<Mermaid>` |
+| Custom URL schemes via declarative `linkRules` | `./linkRules.ts` |
+| Plain-text fast path — short messages skip the markdown pipeline | `./plainText.ts` |
+| Optional collapsible "Read more" for long replies | `useCollapsibleContent` |
+| User vs assistant palette via `isUser` flag | semantic theme tokens |
+
+## Why these plugins
+
+Chat bubbles aren't documents. We picked plugins that fix the gap between CommonMark
+and how people actually type in chats:
+
+- **`remark-breaks`** — CommonMark collapses single newlines into spaces. LLMs and
+  users routinely write joke punchlines, poems, and dialogue separated by single
+  newlines. Without this, "— Доктор, я общаюсь только через мессенджер.\n— Что жена
+  говорит?" renders as one run-on line. ChatGPT, Slack, Discord, Linear all do this.
+- **`remark-smartypants`** — Cheap "humanized" polish: ASCII quotes become typographic
+  quotes, double-dash becomes em-dash, three dots become an ellipsis. Same rule as
+  Medium / Substack. Applied before emoji so quotes around shortcodes still curl.
+- **`remark-emoji`** — Shortcode → Unicode (`:tada:` → 🎉). Already-Unicode emoji
+  pass through untouched.
+- **`rehype-external-links`** — One pass at the end tags every `<a>` that survived
+  sanitize. Replaces ad-hoc `target=_blank` checks in the `a` renderer; works for
+  custom `linkRules`-supplied anchors too.
+
+Plugin order in `MarkdownMessage.tsx` is load-bearing — see the inline comment.
+
+## Plain-text fast path
+
+`MarkdownMessage` looks at the content and decides:
+
+- **Short, single-paragraph, no markdown markers** → render as flat
+  `<div whitespace-pre-wrap>`. Cheaper, preserves newlines verbatim, doesn't
+  parse `*stars*` or `#hash` that the user happened to type.
+- **Anything else** → full ReactMarkdown pipeline.
+
+Override with `plainText={true | false}` if you know better than the heuristic
+(common case: user-typed bubbles always pass `plainText` so their `*` stays as `*`).
+
+## Custom URL schemes (`linkRules`)
+
+`linkRules` is the supported way to plug in app-specific URL handlers (`cmdop://`,
+`obsidian://`, custom file links, mention chips). Each rule:
+
+- declares its `protocols` (whitelisted into the sanitizer);
+- optionally `preprocess`es the source string;
+- `match`es an href and `render`s a custom node.
+
+```tsx
+const rules: LinkRule[] = [
+  {
+    name: 'cmdop-machine-mention',
+    protocols: ['cmdop'],
+    match: (href) => href.startsWith('cmdop://machine/'),
+    render: ({ href, children }) => <MentionChip id={href} label={children} />,
+  },
+];
+
+<MarkdownMessage content="Talk to [Server-A](cmdop://machine/abc-123)" linkRules={rules} />
+```
+
+The plain `a` renderer keeps its palette and typography; `linkRules` only fires
+when both the `protocols` and the `match` predicate accept the href. See
+`linkRules.ts` for the sanitize-extension logic.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `MarkdownMessage.tsx` | Main component — composes plugins, runs heuristic, renders |
+| `components.tsx` | The `Components` map — typography, lists, table, code, blockquote, hr |
+| `CodeBlock.tsx` | Code-fence renderer (`PrettyCode`) + plain `<pre>` fallback |
+| `linkRules.ts` | Declarative custom-URL primitive — schema & helpers |
+| `plainText.ts` | `looksLikePlainProse` heuristic + `extractTextFromChildren` utility |
+| `sanitize.ts` | Extended rehype-sanitize schema + `urlTransform` builder |
+| `CollapseToggle.tsx` | "Read more / Show less" affordance for long replies |
+| `MarkdownMessage.story.tsx` | Storybook — kitchen sink, link rules, mermaid, soft breaks, plugin sampler |
+
+## Stories
+
+Open the storybook and look at:
+
+- `Markdown Message / Link Rules` — declarative `linkRules` API in three modes.
+- `Markdown Message / Chat Bubbles` — plain-text fast path vs heuristic vs long reply.
+- `Markdown Message / Soft Line Breaks` — the `remark-breaks` regression case (joke,
+  poem, dialogue).
+- `Markdown Message / Chat Plugins` — emoji shortcodes, smart typography, external
+  link tagging, in one bubble.
+- `Markdown Message / Kitchen Sink` — every block element together, used to spot
+  spacing regressions at a glance.
+- `Markdown Message / Mermaid Diagrams` — flowchart + sequence diagram in a bubble.

package/src/components/markdown/MarkdownMessage/components.tsx

@@ -51,16 +51,21 @@ export function createMarkdownComponents(
     ),
     li: ({ children }) => <li className="break-words">{children}</li>,
 
-    a: ({ href, children }) => (
+    // `target` / `rel` for external links are NOT set here — the
+    // rehype-external-links plugin tags them on the rehype side, so
+    // every `<a>` that sanitize let through gets the same security
+    // treatment regardless of which renderer (default vs linkRules
+    // override) emitted it. Doing it twice here would just duplicate
+    // attributes; doing it only here would miss the linkRules path.
+    a: ({ href, children, ...rest }) => (
       <a
+        {...rest}
         href={href}
         className={`${textSize} ${
           isUser
             ? 'text-white/90 underline hover:text-white'
             : 'text-primary underline hover:text-primary/80'
         } transition-colors break-all`}
-        target={href?.startsWith('http') ? '_blank' : undefined}
-        rel={href?.startsWith('http') ? 'noopener noreferrer' : undefined}
       >
         {children}
       </a>