@djangocfg/ui-tools 2.1.298 → 2.1.300

package/README.md

@@ -28,7 +28,7 @@ This package contains heavy components that are loaded lazily to keep your initi
 | `@djangocfg/ui-tools` | Heavy tools with lazy loading |
 | `@djangocfg/ui-nextjs` | Next.js apps (extends ui-core) |
 
-## Tools (14)
+## Tools (15)
 
 | Tool | Bundle Size | Description |
 |------|-------------|-------------|
@@ -42,6 +42,7 @@ This package contains heavy components that are loaded lazily to keep your initi
 | `LottiePlayer` | ~200KB | Lottie animation player |
 | `AudioPlayer` | ~200KB | Audio player with WaveSurfer.js |
 | `VideoPlayer` | ~150KB | Professional video player with Vidstack |
+| `MarkdownMessage` | ~120KB | Read-only chat-tuned markdown renderer (GFM, syntax highlighting, mermaid, declarative `linkRules` for custom URL schemes) |
 | `JsonTree` | ~100KB | JSON visualization with modes (full/compact/inline) |
 | `Gallery` | ~50KB | Image/video gallery with carousel, grid, lightbox |
 | `ImageViewer` | ~50KB | Image viewer with zoom/pan/rotate/flip and gallery navigation |
@@ -558,11 +559,134 @@ const schema = {
 />
 ```
 
+## Markdown Message
+
+Read-only markdown renderer tuned for chat / agent transcripts. Built
+on `react-markdown` + `remark-gfm` + `rehype-sanitize`, with a few
+chat-specific affordances on top:
+
+- Syntax-highlighted code blocks with a hover-revealed Copy button
+  (delegates to `PrettyCode` from this package).
+- Mermaid diagram rendering for ` ```mermaid ` fences.
+- Plain-text fast path: when content has no markdown syntax we skip
+  ReactMarkdown entirely and just render the string with
+  `whitespace: pre-line`. Cheaper, identical visual.
+- Optional collapsible "Read more..." for long messages.
+- User vs assistant styling modes (`isUser` prop).
+- **`linkRules` API** — declarative handling of custom URL schemes
+  (e.g. `cmdop://machine/<uuid>` → render as a chip; `obsidian://`
+  → open in a viewer). One prop replaces the per-consumer
+  custom-`a`/sanitize/urlTransform boilerplate.
+
+```tsx
+import { MarkdownMessage } from '@djangocfg/ui-tools';
+
+<MarkdownMessage
+  content="# Hello\n\nThis is **bold** text and `inline code`."
+  isCompact={false}
+/>
+
+// Chat user message — primary-tinted bubble styling
+<MarkdownMessage content={msg} isUser />
+
+// Long content with "Read more..."
+<MarkdownMessage
+  content={longText}
+  collapsible
+  maxLength={300}
+  maxLines={5}
+/>
+```
+
+### Custom URL schemes — `linkRules`
+
+For any chat that emits its own URL schemes — `cmdop://machine/<uuid>`
+mention chips, `obsidian://open?path=…` deep-links, custom file
+viewers — the recommended approach is `linkRules`:
+
+```tsx
+import { MarkdownMessage, type LinkRule } from '@djangocfg/ui-tools';
+
+const machineMention: LinkRule = {
+  name: 'machine-mention',
+  protocols: ['cmdop'],
+
+  // Optional: rewrite the source markdown before render. Useful when
+  // your composer adds a decorative `@` outside the link
+  // (`@[label](href)`) — the chip itself reads as the mention
+  // indicator, so rendering "@<chip>" looks like "@@label".
+  preprocess: (source) =>
+    source.replace(
+      /(^|[^A-Za-z0-9_])@(\[[^\]]+\]\(cmdop:\/\/machine\/[^)\s]+\))/g,
+      '$1$2',
+    ),
+
+  // Predicate against the resolved href.
+  match: (href) => href.startsWith('cmdop://machine/'),
+
+  // Render whatever you want. `children` is the link's React label.
+  render: ({ href, children, isUser }) => {
+    const id = href.slice('cmdop://machine/'.length);
+    return <MentionChip id={id} isUser={isUser}>{children}</MentionChip>;
+  },
+};
+
+<MarkdownMessage
+  content="Talk to @[Vps-audi](cmdop://machine/abc-123) about deployment."
+  linkRules={[machineMention]}
+/>
+```
+
+#### Why `linkRules` and not just `customComponents.a`
+
+Three concerns have to be aligned for a custom URL scheme to make it
+intact to your renderer, and `customComponents` alone covers only one
+of them:
+
+| Concern | What goes wrong without help |
+|---|---|
+| **Sanitize whitelist** | `rehype-sanitize` strips href values for any protocol it doesn't recognise — your renderer receives `href={undefined}`. |
+| **`urlTransform`** | `react-markdown`'s default `urlTransform` runs *before* sanitize and blanks unrecognised schemes the same way — sanitize whitelist is moot if this layer already nuked the href. |
+| **Source preprocess** | Your composer might emit a shape like `@[label](cmdop://...)`; the leading `@` lives outside the link and needs to be stripped before render or the chip ends up next to a literal `@`. |
+
+`linkRules` collapses all three into a single declaration:
+- `protocols` is unioned into the sanitize schema.
+- The same protocol opts in the `urlTransform`.
+- `preprocess` runs ahead of render.
+- `match` + `render` replace the per-rule `<a>`.
+
+You can still pass `customComponents` and `extraHrefProtocols`
+alongside; rules win on URLs they `match`, everything else falls
+through to your `customComponents.a` (or the built-in chat anchor).
+
+### Anatomy
+
+The component lives at `src/components/markdown/MarkdownMessage/`:
+
+```
+MarkdownMessage/
+├── MarkdownMessage.tsx     # composition only
+├── types.ts                # MarkdownMessageProps + LinkRule
+├── sanitize.ts             # buildSchema + buildUrlTransform
+├── components.tsx          # createMarkdownComponents (h/p/ul/a/pre/...)
+├── CodeBlock.tsx           # code block with copy button + fallback
+├── CollapseToggle.tsx      # "Read more..." button
+├── linkRules.ts            # rule application helpers
+├── plainText.ts            # hasMarkdownSyntax + extractTextFromChildren
+└── index.ts                # public re-exports
+```
+
+Decomposed in 2.1.299 to keep concerns flat and reviewable. Public
+contract (`MarkdownMessage`, `MarkdownMessageProps`, `LinkRule`,
+`extractTextFromChildren`) re-exported from
+`@djangocfg/ui-tools` directly.
+
 ## Components
 
 | Component | Description |
 |-----------|-------------|
-| `Markdown` | Markdown renderer with GFM support |
+| `MarkdownMessage` | Read-only markdown renderer with custom-URL-scheme support via `linkRules` (see above) |
+| `Markdown` | Generic markdown renderer with GFM support |
 
 ## Stores
 

package/dist/{DocsLayout-74WIW7L3.mjs → DocsLayout-MWRKNFXR.mjs}

@@ -1,4 +1,4 @@
-import { deduplicateEndpoints, dereferenceSchema, resolveBaseUrl, usePlaygroundContext, toMarkdown, toCompactJson, toRawJson, formatBytes, MarkdownMessage, CODE_SAMPLE_TARGETS, buildHarRequest, resolveAbsolute, renderSnippet, PrettyCode_default, relativePath, endpointToMarkdown, isValidJson, findApiKeyById, parseRequestHeaders, UrlBuilder, sampleSchemaJson, joinUrl } from './chunk-2BBXP3DH.mjs';
+import { deduplicateEndpoints, dereferenceSchema, resolveBaseUrl, usePlaygroundContext, toMarkdown, toCompactJson, toRawJson, formatBytes, MarkdownMessage, CODE_SAMPLE_TARGETS, buildHarRequest, resolveAbsolute, renderSnippet, PrettyCode_default, relativePath, endpointToMarkdown, isValidJson, findApiKeyById, parseRequestHeaders, UrlBuilder, sampleSchemaJson, joinUrl } from './chunk-CKD7GNE5.mjs';
 import { JsonTree_default } from './chunk-LFWQ36LJ.mjs';
 import './chunk-SSUOENAZ.mjs';
 import { __name } from './chunk-CGILA3WO.mjs';
@@ -3459,5 +3459,5 @@ var DocsLayout = /* @__PURE__ */ __name(() => {
 }, "DocsLayout");
 
 export { DocsLayout };
-//# sourceMappingURL=DocsLayout-74WIW7L3.mjs.map
-//# sourceMappingURL=DocsLayout-74WIW7L3.mjs.map
+//# sourceMappingURL=DocsLayout-MWRKNFXR.mjs.map
+//# sourceMappingURL=DocsLayout-MWRKNFXR.mjs.map