@djangocfg/widget-media 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reforms.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @djangocfg/widget-media
+
+Media viewers for a conversation or a file preview: a zoom/pan image lightbox,
+mermaid diagrams, markdown for a reader, and read-only code listings.
+
+## Install
+
+```bash
+pnpm add @djangocfg/widget-media @djangocfg/ui-core streamdown
+```
+
+## Exports
+
+**Each viewer is its own subpath, and that is the contract.** The root barrel
+carries the image viewer only; the other three pull a parser or a highlighter,
+and a host mounting a lightbox must not pay for any of them.
+
+| Subpath | What it is | What it costs |
+|---|---|---|
+| `.` | `ImageViewer`, `LazyImageViewer`, its hooks, types and constants | `react-zoom-pan-pinch` |
+| `./diagram` | `LazyDiagram`, `DiagramSource`, `diagramPlugin` | mermaid (~2.5 MB) — **always deferred** |
+| `./markdown` | `Markdown` — for a reader, outside any conversation | streamdown |
+| `./code` | `Code` — a read-only listing | streamdown + shiki |
+| `./i18n` | `MediaCopy`, `DEFAULT_MEDIA_COPY` | — |
+
+```tsx
+import { ImageViewer } from '@djangocfg/widget-media';
+import { LazyDiagram } from '@djangocfg/widget-media/diagram';
+
+<ImageViewer images={[{ name: 'chart.png', src }]} lightbox />
+<LazyDiagram chart={source} streaming={isStreaming} />
+```
+
+## Copy
+
+The package owns its copy, typed. Pass `copy` to override any subset; keys you
+omit fall back to English, so translating one label does not blank the rest.
+
+```tsx
+<ImageViewer images={images} copy={{ zoomIn: 'Приблизить', close: 'Закрыть' }} />
+```
+
+`MediaCopy` is the schema of record — a misspelled key is a `tsc` error, not
+`undefined` rendered into a toolbar button.
+
+## Image viewer
+
+Zoom (wheel + presets 25/50/100/200/400%), pan by drag, rotate 90°, flip H/V,
+fullscreen dialog, keyboard shortcuts (`+`/`-`, `0` reset, `r` rotate),
+progressive loading with LQIP, checkerboard transparency ground, and cached
+dimension display. `LazyImageViewer` ships from the same entry, so choosing it
+costs no extra subpath.
+
+## Verify
+
+```bash
+pnpm --filter @djangocfg/widget-media check-types test
+```

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@djangocfg/widget-media",
+  "version": "0.1.1",
+  "description": "Media viewers for a conversation or a file preview: zoom/pan image lightbox, mermaid diagrams, markdown and code listings",
+  "keywords": [
+    "image-viewer",
+    "lightbox",
+    "mermaid",
+    "markdown",
+    "streamdown",
+    "react",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "widgets/media"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./image-viewer": "./src/image-viewer/index.ts",
+    "./diagram": "./src/diagram/index.ts",
+    "./markdown": "./src/markdown/index.ts",
+    "./code": "./src/code/index.ts",
+    "./i18n": "./src/i18n/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.stories.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@streamdown/code": "^1.1.1",
+    "beautiful-mermaid": "^1.1.3",
+    "react-zoom-pan-pinch": "^3.7.0",
+    "rehype-harden": "^1.1.8",
+    "zustand": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@djangocfg/ui-core": "^2.1.542",
+    "lucide-react": "^0.545.0",
+    "react": "^19.0.0",
+    "streamdown": "^2.6.0"
+  },
+  "devDependencies": {
+    "@djangocfg/typescript-config": "^2.1.542",
+    "@djangocfg/ui-core": "^2.1.542",
+    "@storybook/react-vite": "^10.5.0",
+    "@types/node": "^25.9.5",
+    "@types/react": "19.2.15",
+    "@types/react-dom": "19.2.3",
+    "lucide-react": "0.545.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "storybook": "^10.5.0",
+    "streamdown": "2.6.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/code/code.tsx

@@ -0,0 +1,116 @@
+'use client';
+
+import { code } from '@streamdown/code';
+import { memo } from 'react';
+import { Streamdown } from 'streamdown';
+
+/**
+ * A read-only code listing, outside any conversation.
+ *
+ * Rendered by feeding a fenced block to the same parser the rest of this
+ * package uses, rather than by calling a highlighter directly. That is the
+ * point: the transcript, the document preview and the setup wizard then share
+ * ONE highlighter, one theme and one set of supported languages, and a listing
+ * cannot drift from the code block beside it in a chat message.
+ *
+ * Replaces the retired `@djangocfg/ui-tools/pretty-code`, which was built on Prism while
+ * everything else here is on shiki. Two highlighters in one console means two
+ * themes to keep matched and two answers to "is this language supported".
+ */
+
+/**
+ * A language name shiki understands.
+ *
+ * Deliberately `string` rather than a union imported from the highlighter: the
+ * predecessor exported Prism's own `Language` type, so every call site named
+ * its supplier in its signature and swapping the supplier became a
+ * type-level breaking change. An unknown name degrades to an unhighlighted
+ * listing, which is the same outcome a wrong union member would have produced.
+ */
+export type CodeLanguage = string;
+
+export type CodeVariant = 'card' | 'plain';
+
+/**
+ * Listing scale.
+ *
+ * `sm` (12px) is the wizard's density, where a snippet sits inside a step card
+ * beside prose; `base` (14px) is a standalone listing. The predecessor spelled
+ * this `isCompact`, a boolean that could only ever say "not the default" —
+ * naming both ends means a third density is a value rather than a second flag.
+ */
+export type CodeSize = 'sm' | 'base';
+
+const SIZE_CLASS: Record<CodeSize, string> = {
+  sm: 'text-xs',
+  base: 'text-sm',
+};
+
+export interface CodeProps {
+  /** The source. An object is JSON-serialised, as the predecessor did. */
+  readonly data: string | object;
+  readonly language: CodeLanguage;
+  /**
+   * `card` — its own surface: border, ground, copy control.
+   * `plain` — no chrome, grows to fit. For embedding inside a container that
+   * already scrolls, where a second scroll surface traps the wheel.
+   */
+  readonly variant?: CodeVariant;
+  readonly size?: CodeSize;
+  readonly className?: string;
+}
+
+const PLUGINS = { code };
+
+/** Fences the source. A fence inside the source would end the block early. */
+function fence(source: string, language: string): string {
+  const ticks = '`'.repeat(Math.max(3, longestTickRun(source) + 1));
+  return `${ticks}${language}\n${source}\n${ticks}`;
+}
+
+function longestTickRun(source: string): number {
+  let longest = 0;
+  let current = 0;
+  for (const character of source) {
+    current = character === '`' ? current + 1 : 0;
+    if (current > longest) longest = current;
+  }
+  return longest;
+}
+
+export const Code = memo(
+  ({ data, language, variant = 'card', size = 'base', className }: CodeProps) => {
+    const source = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+    return (
+      <div
+        className={`djc-code djc-code--${variant} ${SIZE_CLASS[size]} ${className ?? ''}`}
+        data-slot="code"
+        data-variant={variant}
+        data-size={size}
+      >
+        <Streamdown
+          mode="static"
+          // The source is complete, so the incomplete-markdown completion a
+          // chat needs would only be guessing at text that will not change.
+          parseIncompleteMarkdown={false}
+          plugins={PLUGINS}
+          // `plain` embeds in a container that already scrolls; a height cap
+          // here would add the second scroll surface the variant exists to
+          // avoid.
+          codeBlockMaxHeight={variant === 'plain' ? Infinity : 400}
+          controls={{ code: variant === 'card' }}
+        >
+          {fence(source, language)}
+        </Streamdown>
+      </div>
+    );
+  },
+  (prev, next) =>
+    prev.data === next.data &&
+    prev.language === next.language &&
+    prev.variant === next.variant &&
+    prev.size === next.size &&
+    prev.className === next.className,
+);
+
+Code.displayName = 'Code';

package/src/code/index.ts

@@ -0,0 +1,10 @@
+// A read-only code listing, rendered through the same parser and highlighter
+// as every other surface here — see `code.tsx` for why that matters.
+
+export {
+  Code,
+  type CodeProps,
+  type CodeLanguage,
+  type CodeVariant,
+  type CodeSize,
+} from './code';

package/src/diagram/diagram-source.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import type { MermaidErrorComponentProps } from 'streamdown';
+
+/**
+ * What a fenced diagram shows when it cannot be drawn.
+ *
+ * Replaces streamdown's default, which paints red-on-red error text with the
+ * source folded into a `<details>`. Two reasons that default is wrong here.
+ *
+ * The source IS the answer. An agent that drew a diagram type our parser does
+ * not cover still said something; an error box says only that we failed, and
+ * hides what was said behind a disclosure.
+ *
+ * And most rejections are not errors at all. A diagram mid-stream is rejected
+ * on every token until its shape closes, so the default would flash a red box
+ * through the whole of a streamed diagram and then replace it with a picture.
+ *
+ * `retry` is deliberately unused: nothing here is transient. Re-running the
+ * same parser over the same source yields the same verdict, and when the source
+ * GROWS streamdown re-renders on its own.
+ */
+export function DiagramSource({ chart }: MermaidErrorComponentProps) {
+  return (
+    <pre className="chat-diagram-source" data-slot="diagram-source">
+      {chart.trim()}
+    </pre>
+  );
+}

package/src/diagram/diagram.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import { useMediaCopy, type MediaCopy } from '../i18n';
+import { isDiagramComplete, renderDiagram } from './render';
+
+export interface DiagramProps {
+  /** Mermaid source, possibly still arriving. */
+  readonly chart: string;
+  /**
+   * Whether the source is still being written.
+   *
+   * Supplied by the caller because only it knows: a fenced block knows its
+   * fence is open, a `show_media` block is finished the moment it exists. The
+   * shape of the source cannot answer this on its own — see `isDiagramComplete`,
+   * which is the second, weaker check applied underneath.
+   */
+  readonly streaming?: boolean;
+  readonly className?: string;
+  /** Override the widget's English copy; omitted keys fall back to defaults. */
+  readonly copy?: Partial<MediaCopy>;
+}
+
+/**
+ * A mermaid diagram, or its source when that is the honest answer.
+ *
+ * Both fallbacks show the SOURCE rather than an error box, because the source
+ * is what the agent actually said. A diagram that cannot be drawn is still an
+ * answer; an error box is not.
+ */
+export function Diagram({ chart, streaming = false, className, copy }: DiagramProps) {
+  const copyText = useMediaCopy(copy);
+
+  // Rendering is the expensive step and `chart` changes on every streamed
+  // token, so the guard is inside the memo: a diagram still being written must
+  // not be parsed at all, not merely have its output discarded.
+  const result = useMemo(() => {
+    if (streaming || !isDiagramComplete(chart)) return null;
+    return renderDiagram(chart);
+  }, [chart, streaming]);
+
+  if (result === null || !result.ok) {
+    return (
+      <pre className={`chat-diagram-source ${className ?? ''}`} data-slot="diagram-source">
+        {chart.trim()}
+      </pre>
+    );
+  }
+
+  return (
+    <div
+      className={`chat-diagram ${className ?? ''}`}
+      data-slot="diagram"
+      // The parser escapes label text into `data-*` attributes, so a model
+      // cannot get markup out of a label and into the document. That is a
+      // security property of a dependency rather than of this file, so it is
+      // pinned by `injection.test.ts` instead of trusted.
+      dangerouslySetInnerHTML={{ __html: result.svg }}
+      role="img"
+      aria-label={copyText.diagram}
+    />
+  );
+}

package/src/diagram/index.ts

@@ -0,0 +1,22 @@
+// Mermaid rendering, reached from both rails a diagram arrives on: a fenced
+// block in prose (the streamdown plugin) and a `show_media` block (the
+// component).
+//
+// EVERYTHING HERE IS DEFERRED. The parser is ~2.5 MB and most transcripts carry
+// no diagram, so a consumer importing this barrel must not pay for one until a
+// diagram appears — `LazyDiagram` splits it behind Suspense and the plugin
+// behind its own async `render`. Pinned by `cost.test.ts`, which walks this
+// file's static graph.
+//
+// The eager `Diagram` and the pure `render` are deliberately NOT re-exported.
+// A barrel re-export is a static edge, so naming them here would pull the
+// parser into every consumer and quietly undo the split — which is exactly what
+// this file did on its first version. Reach for them by their own paths.
+//
+// Deliberately NOT re-exported from the package root — see `@dev/decisions.md`
+// D4. A host rendering a read-only transcript pays for neither.
+
+export type { DiagramProps } from './diagram';
+export { LazyDiagram } from './lazy';
+export { DiagramSource } from './diagram-source';
+export { diagramPlugin, DiagramIncompleteError } from './plugin';

package/src/diagram/lazy.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+/**
+ * Lazy-loaded Diagram.
+ *
+ * The renderer carries `beautiful-mermaid` (~2.5 MB), which no transcript needs
+ * until a diagram actually appears — and most never carry one. Splitting it out
+ * is what keeps the promise that a host rendering a read-only transcript pays
+ * for a parser it does not reach.
+ *
+ * This is the form every CONSUMER should mount. The eager `Diagram` stays
+ * exported for a host that has already decided it wants the chunk, and for the
+ * stories, where a Suspense boundary would only add a frame to assert around.
+ */
+
+import { lazy, Suspense } from 'react';
+
+import type { DiagramProps } from './diagram';
+
+export type { DiagramProps };
+
+const DiagramImpl = lazy(() => import('./diagram').then((mod) => ({ default: mod.Diagram })));
+
+/**
+ * The source, while the renderer arrives.
+ *
+ * The same thing every other fallback here shows, and for the same reason: it
+ * is the answer the agent gave. A spinner would replace content that is already
+ * in hand with a promise of content.
+ */
+function Fallback({ chart }: { readonly chart: string }) {
+  return (
+    <pre className="chat-diagram-source" data-slot="diagram-source">
+      {chart.trim()}
+    </pre>
+  );
+}
+
+export function LazyDiagram(props: DiagramProps) {
+  return (
+    <Suspense fallback={<Fallback chart={props.chart} />}>
+      <DiagramImpl {...props} />
+    </Suspense>
+  );
+}

package/src/diagram/plugin.ts

@@ -0,0 +1,62 @@
+// The streamdown `DiagramPlugin` over our synchronous renderer.
+//
+// May import: streamdown (types only), ./render.
+
+import type { DiagramPlugin } from 'streamdown';
+
+/**
+ * Thrown when the source is not a diagram yet.
+ *
+ * A distinct type because the two rejections mean opposite things to a reader:
+ * an unsupported diagram is final and its source is the answer, while a partial
+ * one is simply not finished. Both fall back to the source, so nothing branches
+ * on this today — it exists so the error surface can tell them apart without
+ * matching on message text.
+ */
+export class DiagramIncompleteError extends Error {
+  constructor() {
+    super('diagram source is incomplete');
+    this.name = 'DiagramIncompleteError';
+  }
+}
+
+/**
+ * A mermaid renderer for `Streamdown`'s plugin slot.
+ *
+ * WHY THE GUARD IS HERE AND NOT IN STREAMDOWN. Streamdown computes whether a
+ * fence is still open and forwards it to the code-block branch as
+ * `isIncomplete` — but the mermaid branch drops it, and its render effect is
+ * keyed on the chart alone. So every streamed token reaches this function, and
+ * the guard has to be ours or there is none.
+ *
+ * That matters because `renderDiagram` does NOT fail on a half-arrived source;
+ * it draws a plausible wrong picture. Rejecting is what keeps the source
+ * showing until the shape closes.
+ *
+ * `initialize` is a no-op: the plugin contract mirrors the mermaid runtime,
+ * which needs configuring before use. Ours reads the theme from CSS variables
+ * baked into the SVG, so there is no state to configure.
+ */
+export const diagramPlugin: DiagramPlugin = {
+  language: 'mermaid',
+  name: 'mermaid',
+  type: 'diagram',
+  getMermaid: () => ({
+    initialize: () => undefined,
+    // The `id` is streamdown's element handle. Ours goes unused: the SVG
+    // carries no ids to collide, which is what lets one diagram be rendered
+    // twice — inline and fullscreen — with no rewriting.
+    render: async (_id: string, source: string) => {
+      // Imported here rather than at the top so the parser is fetched by the
+      // first diagram, not by the transcript that might never contain one. The
+      // contract is already async, so this costs no extra round trip — and it
+      // is what keeps the plugin registrable at the package root without
+      // dragging 2.5 MB along with it.
+      const { isDiagramComplete, renderDiagram } = await import('./render');
+      if (!isDiagramComplete(source)) throw new DiagramIncompleteError();
+      const result = renderDiagram(source);
+      if (!result.ok) throw new Error(result.error);
+      return { svg: result.svg };
+    },
+  }),
+};