@djangocfg/ui-tools 2.1.404 → 2.1.408

package/src/tools/Mermaid/utils/mermaid-helpers.ts

@@ -2,33 +2,156 @@
  * Helper utilities for Mermaid diagram rendering
  */
 
-// Utility function to apply text colors to Mermaid SVG
-export const applyMermaidTextColors = (container: HTMLElement, textColor: string) => {
+/**
+ * Read a semantic color token from CSS custom properties.
+ *
+ * Theme tokens (`light.css` / `dark.css`) ship fully-wrapped CSS colors
+ * (`hsl(0 0% 94%)`) — see `ui-core/src/styles/theme/tokens.css`. Older
+ * tokens stored bare HSL components (`0 0% 94%`), so this helper handles
+ * both: complete colors pass through untouched, bare components get
+ * wrapped once. Never double-wrap an already-complete color.
+ *
+ * @param variable CSS custom property name, e.g. `--foreground`.
+ * @param fallback Returned when the variable is empty / unavailable.
+ */
+export const getThemeColor = (variable: string, fallback = ''): string => {
+    if (typeof document === 'undefined') return fallback;
+    const value = getComputedStyle(document.documentElement)
+        .getPropertyValue(variable)
+        .trim();
+    if (!value) return fallback;
+    // Already a complete color (hex / rgb / hsl / oklch / named).
+    if (
+        value.startsWith('#') ||
+        value.startsWith('rgb') ||
+        value.startsWith('hsl(') ||
+        value.startsWith('oklch') ||
+        value.startsWith('oklab') ||
+        value.startsWith('color(') ||
+        value.startsWith('var(')
+    ) {
+        return value;
+    }
+    // Bare HSL components — wrap once.
+    return `hsl(${value})`;
+};
+
+/** Resolve the diagram text color for the given theme. */
+export const getTextColor = (theme: string): string =>
+    theme === 'dark'
+        ? getThemeColor('--foreground', 'hsl(0 0% 98%)')
+        : getThemeColor('--foreground', 'hsl(222.2 84% 4.9%)');
+
+/**
+ * Diagram types whose labels sit on per-section colored backgrounds
+ * (timeline sections, journey tasks, pie slices, mindmap nodes, gitgraph
+ * commits). For these, Mermaid already picks a contrasting label color
+ * from the `cScaleLabel*` / `pie*` theme variables — re-asserting a single
+ * `--foreground` would put dark text on dark boxes (and vice versa).
+ *
+ * We detect them via the wrapper class Mermaid puts on the root `<g>` /
+ * `<svg>` and skip the blanket text override for those SVGs.
+ */
+const SECTION_COLORED_SELECTORS = [
+    '.timeline',
+    '.mindmap',
+    '[id^="mermaid"][aria-roledescription="timeline"]',
+    '[id^="mermaid"][aria-roledescription="journey"]',
+    '[id^="mermaid"][aria-roledescription="mindmap"]',
+    '[id^="mermaid"][aria-roledescription="pie"]',
+];
+
+/** True when the SVG renders a diagram type that colors its own labels. */
+const usesSectionColors = (svg: SVGSVGElement): boolean => {
+    const role = svg.getAttribute('aria-roledescription') ?? '';
+    if (['timeline', 'journey', 'mindmap', 'pie'].includes(role)) return true;
+    return SECTION_COLORED_SELECTORS.some((sel) => svg.querySelector(sel) !== null);
+};
+
+/**
+ * Apply theme text colors to a rendered Mermaid SVG.
+ *
+ * Mermaid's `base` theme bakes `themeVariables` at render time, but text
+ * fill on `<text>` nodes and `color` on foreignObject labels can drift
+ * from our tokens — this re-asserts them after render.
+ *
+ * Diagrams that color their own labels per section (timeline, journey,
+ * mindmap, pie) are skipped: their `themeVariables` already encode
+ * contrasting label colors, so a blanket override would re-introduce the
+ * dark-text-on-dark-box problem.
+ */
+export const applyMermaidTextColors = (container: HTMLElement, textColor: string): void => {
     const svgElement = container.querySelector('svg');
-    if (svgElement) {
-        // SVG text elements use 'fill'
-        svgElement.querySelectorAll('text').forEach((el) => {
-            (el as SVGElement).style.fill = textColor;
-        });
+    if (!svgElement) return;
+    if (usesSectionColors(svgElement)) return;
+    // SVG text elements use 'fill'.
+    svgElement.querySelectorAll('text').forEach((el) => {
+        (el as SVGElement).style.fill = textColor;
+    });
+    // HTML elements inside foreignObject use 'color'.
+    svgElement.querySelectorAll('.nodeLabel, .edgeLabel').forEach((el) => {
+        (el as HTMLElement).style.color = textColor;
+    });
+};
 
-        // HTML elements inside foreignObject use 'color'
-        svgElement.querySelectorAll('.nodeLabel, .edgeLabel').forEach((el) => {
-            (el as HTMLElement).style.color = textColor;
-        });
-    }
+/**
+ * Re-color ER diagram attribute-row backgrounds.
+ *
+ * Mermaid derives the zebra-stripe fills for `.row-rect-odd` /
+ * `.row-rect-even` by lightening `mainBkg` — in dark mode the odd stripe
+ * lands on a light gray (`hsl(0 0% 83%)`) while the attribute text stays
+ * white, so it vanishes. `themeVariables` has no hook for these, so we
+ * re-assert themed fills after render.
+ *
+ * @param container Host element holding the rendered SVG.
+ * @param oddFill   Background for odd attribute rows.
+ * @param evenFill  Background for even attribute rows.
+ */
+export const applyMermaidErRowColors = (
+    container: HTMLElement,
+    oddFill: string,
+    evenFill: string,
+): void => {
+    const svgElement = container.querySelector('svg');
+    if (!svgElement) return;
+    svgElement.querySelectorAll('.row-rect-odd path').forEach((el) => {
+        const fill = (el as SVGElement).getAttribute('fill');
+        if (fill && fill !== 'none') (el as SVGElement).setAttribute('fill', oddFill);
+    });
+    svgElement.querySelectorAll('.row-rect-even path').forEach((el) => {
+        const fill = (el as SVGElement).getAttribute('fill');
+        if (fill && fill !== 'none') (el as SVGElement).setAttribute('fill', evenFill);
+    });
 };
 
-// Detect if diagram is vertical (tall and narrow)
+/**
+ * Detect whether a diagram is vertical (tall and narrow).
+ *
+ * Used to pick a sensible fullscreen fit. Prefers the `viewBox` (stable,
+ * available immediately) and falls back to `getBBox()` only when needed.
+ */
 export const isVerticalDiagram = (svgElement: SVGSVGElement): boolean => {
     const viewBox = svgElement.getAttribute('viewBox');
     if (viewBox) {
-        const [, , width, height] = viewBox.split(' ').map(Number);
-        if (width === undefined || height === undefined) return false;
+        const [, , width, height] = viewBox.split(/\s+/).map(Number);
+        if (
+            width === undefined ||
+            height === undefined ||
+            !Number.isFinite(width) ||
+            !Number.isFinite(height) ||
+            width <= 0
+        ) {
+            return false;
+        }
         return height > width * 1.5;
     }
-    const bbox = svgElement.getBBox?.();
-    if (bbox) {
-        return bbox.height > bbox.width * 1.5;
+    try {
+        const bbox = svgElement.getBBox?.();
+        if (bbox && bbox.width > 0) {
+            return bbox.height > bbox.width * 1.5;
+        }
+    } catch {
+        // getBBox throws if the SVG is not attached / not rendered.
     }
     return false;
 };

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/SchemaFields/FieldRow.tsx

@@ -35,6 +35,8 @@ export function FieldRow({ field, depth, showTreeLine = true }: FieldRowProps) {
     // at smaller text sizes.
     const padLeft = showTreeLine ? depth * 14 : 0;
 
+    const toggle = () => isExpandable && setOpen((v) => !v);
+
     return (
         <div className="bg-background">
             <div
@@ -43,8 +45,16 @@ export function FieldRow({ field, depth, showTreeLine = true }: FieldRowProps) {
                     isExpandable && 'cursor-pointer hover:bg-muted/30',
                 )}
                 style={{ paddingLeft: 12 + padLeft }}
-                onClick={() => isExpandable && setOpen((v) => !v)}
+                onClick={toggle}
+                onKeyDown={(e) => {
+                    if (!isExpandable) return;
+                    if (e.key === 'Enter' || e.key === ' ') {
+                        e.preventDefault();
+                        toggle();
+                    }
+                }}
                 role={isExpandable ? 'button' : undefined}
+                tabIndex={isExpandable ? 0 : undefined}
                 aria-expanded={isExpandable ? open : undefined}
             >
                 <ChevronRight

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/SchemaFields/buildTree.ts

@@ -3,11 +3,12 @@
  *
  *  Handles the OpenAPI 3.x subset we actually see: objects with
  *  ``properties`` + ``required``, arrays with ``items``, enums,
- *  primitives with ``format``. ``allOf`` / ``oneOf`` / ``anyOf`` are
- *  flattened best-effort — we pick the first branch so the UI shows
- *  *a* shape rather than an empty row. Upstream dereferencing
- *  (``dereferenceSchema``) is expected to have resolved ``$ref`` before
- *  this runs.
+ *  primitives with ``format``. ``allOf`` is merged shallowly.
+ *  ``oneOf`` / ``anyOf`` object branches are merged so every variant's
+ *  fields are visible (union of properties); ``required`` is intersected
+ *  so a field optional in one variant is not shown as globally required.
+ *  Non-object unions fall back to the first branch. Upstream
+ *  dereferencing (``dereferenceSchema``) resolves ``$ref`` before this runs.
  */
 
 import type { FieldKind, FieldNode } from './types';
@@ -29,19 +30,40 @@ type JsonSchemaNode = Record<string, unknown> & {
  *  call stack. Anything this deep is unreadable in a docs view anyway. */
 const MAX_DEPTH = 5;
 
-/** Merge ``allOf`` branches into a single pseudo-object. Shallow merge
- *  is enough for the display — deep merge would require semantic JSON
- *  Schema reasoning that we don't need for a read-only viewer. */
-function mergeAllOf(branches: JsonSchemaNode[]): JsonSchemaNode {
+/** Merge object branches into a single pseudo-object. Shallow merge is
+ *  enough for display — deep merge would need semantic JSON Schema
+ *  reasoning we don't want in a read-only viewer.
+ *
+ *  ``intersectRequired`` controls how ``required`` combines: ``allOf`` is
+ *  a conjunction so every branch's required fields apply (union); for
+ *  ``oneOf`` / ``anyOf`` a field is only truly required when *every*
+ *  object branch requires it (intersection). */
+function mergeObjectBranches(
+    branches: JsonSchemaNode[],
+    intersectRequired: boolean,
+): JsonSchemaNode {
     const properties: Record<string, JsonSchemaNode> = {};
-    const required: string[] = [];
-    for (const b of branches) {
+    const objectBranches = branches.filter((b) => b.properties);
+    const requiredSets = objectBranches.map((b) => new Set(b.required ?? []));
+    for (const b of objectBranches) {
         if (b.properties) Object.assign(properties, b.properties);
-        if (Array.isArray(b.required)) required.push(...b.required);
+    }
+    let required: string[];
+    if (intersectRequired && requiredSets.length > 0) {
+        const [first, ...rest] = requiredSets;
+        required = [...first!].filter((k) => rest.every((s) => s.has(k)));
+    } else {
+        required = [...new Set(requiredSets.flatMap((s) => [...s]))];
     }
     return { type: 'object', properties, required };
 }
 
+/** True when every branch is (or describes) an object — i.e. the union
+ *  can be presented as a merged property table. */
+function allObjectBranches(branches: JsonSchemaNode[]): boolean {
+    return branches.every((b) => b.type === 'object' || Boolean(b.properties));
+}
+
 function describeType(node: JsonSchemaNode): { label: string; kind: FieldKind } {
     if (node.type === 'array') {
         const itemLabel = node.items ? describeType(node.items).label : 'any';
@@ -61,16 +83,23 @@ function describeType(node: JsonSchemaNode): { label: string; kind: FieldKind }
 }
 
 function resolveCombinators(node: JsonSchemaNode): JsonSchemaNode {
-    // ``allOf`` → merge shallowly. Other combinators → pick the first
-    // branch (see module docstring rationale).
+    // ``allOf`` → conjunction merge (required is a union).
     if (Array.isArray(node.allOf) && node.allOf.length > 0) {
-        return { ...mergeAllOf(node.allOf), description: node.description };
-    }
-    if (Array.isArray(node.oneOf) && node.oneOf.length > 0) {
-        return { ...node.oneOf[0]!, description: node.description ?? node.oneOf[0]!.description };
+        return { ...mergeObjectBranches(node.allOf, false), description: node.description };
     }
-    if (Array.isArray(node.anyOf) && node.anyOf.length > 0) {
-        return { ...node.anyOf[0]!, description: node.description ?? node.anyOf[0]!.description };
+    // ``oneOf`` / ``anyOf`` of objects → merge so every variant's fields
+    // are visible; required intersected. Non-object unions → first branch.
+    for (const key of ['oneOf', 'anyOf'] as const) {
+        const branches = node[key];
+        if (Array.isArray(branches) && branches.length > 0) {
+            if (branches.length > 1 && allObjectBranches(branches)) {
+                return { ...mergeObjectBranches(branches, true), description: node.description };
+            }
+            return {
+                ...branches[0]!,
+                description: node.description ?? branches[0]!.description,
+            };
+        }
     }
     return node;
 }

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/index.tsx

@@ -53,6 +53,13 @@ export function EndpointDoc({ endpoint, isLoadedInPlayground, onTryIt, schemaId
                 data-endpoint-anchor={anchor}
                 data-schema-id={scopedSchemaId ?? ''}
                 className="scroll-mt-24 py-10 first:pt-0"
+                // ``content-visibility: auto`` lets the browser skip layout
+                // + paint for endpoint cards that are off-screen — a big
+                // win for large specs (hundreds of endpoints) with no
+                // behavioural change. ``contain-intrinsic-size`` supplies a
+                // height estimate so the scrollbar stays stable before a
+                // card is first rendered.
+                style={{ contentVisibility: 'auto', containIntrinsicSize: 'auto 480px' }}
             >
                 <EndpointHeader
                     endpoint={endpoint}

package/src/tools/OpenapiViewer/components/DocsLayout/grouping.ts

@@ -30,10 +30,13 @@ export type SchemaSection = {
 
 const METHOD_ORDER: Record<string, number> = {
     GET: 0,
-    POST: 1,
-    PUT: 2,
-    PATCH: 3,
-    DELETE: 4,
+    HEAD: 1,
+    POST: 2,
+    PUT: 3,
+    PATCH: 4,
+    DELETE: 5,
+    OPTIONS: 6,
+    TRACE: 7,
 };
 
 const methodRank = (ep: ApiEndpoint) => METHOD_ORDER[ep.method] ?? 99;

package/src/tools/OpenapiViewer/constants.ts

@@ -5,6 +5,9 @@ export const HTTP_METHOD_COLORS = {
   PUT: 'warning',
   DELETE: 'error',
   PATCH: 'default',
+  HEAD: 'default',
+  OPTIONS: 'default',
+  TRACE: 'default',
 } as const;
 
 // HTTP status code colors mapping

package/src/tools/OpenapiViewer/hooks/useOpenApiSchema.ts

@@ -10,8 +10,10 @@ import { joinUrl, resolveBaseUrl } from '../utils/url';
 
 type JsonSchemaNode = Record<string, unknown>;
 
-// HTTP methods to extract from OpenAPI schema
-const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const;
+// HTTP methods to extract from OpenAPI schema. Covers the full set of
+// OpenAPI Operation Object keys — ``head`` / ``options`` / ``trace`` are
+// rarer but valid, and silently dropping them hid real endpoints.
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'] as const;
 
 // Extract endpoints from OpenAPI schema (all methods). ``baseUrl`` is
 // resolved by the caller via ``resolveBaseUrl`` — we just paste it onto
@@ -79,14 +81,19 @@ const extractEndpoints = (
           const chosen = chosenContentType ? respContent?.[chosenContentType] : undefined;
           const respSchema = chosen?.schema as JsonSchemaNode | undefined;
 
+          // Hand-written example wins over a synthesised one.
+          const explicit = stringifyExample(explicitMediaExample(chosen));
+
           responses.push({
             code,
             description: (response as any).description || `Response ${code}`,
             contentType: chosenContentType,
             schema: respSchema,
-            example: respSchema
-              ? sampleSchemaJson(respSchema, { skipWriteOnly: true }, specRoot)
-              : undefined,
+            example:
+              explicit ??
+              (respSchema
+                ? sampleSchemaJson(respSchema, { skipWriteOnly: true }, specRoot)
+                : undefined),
           });
         }
       }
@@ -102,13 +109,17 @@ const extractEndpoints = (
         const content = op.requestBody.content;
         const mediaType = content?.['application/json'] || content?.[Object.keys(content || {})[0]];
         const rawSchema = mediaType?.schema as JsonSchemaNode | undefined;
+        // Hand-written example wins over a synthesised one.
+        const explicit = stringifyExample(explicitMediaExample(mediaType));
         requestBody = {
           type: (rawSchema?.type as string | undefined) || 'object',
           description: op.requestBody.description,
           schema: rawSchema,
-          example: rawSchema
-            ? sampleSchemaJson(rawSchema, { skipReadOnly: true }, specRoot)
-            : undefined,
+          example:
+            explicit ??
+            (rawSchema
+              ? sampleSchemaJson(rawSchema, { skipReadOnly: true }, specRoot)
+              : undefined),
         };
       }
 
@@ -132,6 +143,34 @@ const extractEndpoints = (
   return endpoints;
 };
 
+// Pull a hand-written example off a media-type object, if present.
+// OpenAPI lets authors attach a canonical example two ways:
+//   - ``example``  — a single inline value (3.0 + 3.1).
+//   - ``examples`` — a named map of Example Objects (3.0 + 3.1); we use
+//                    the first entry's ``value``.
+// A hand-written example is more trustworthy than a synthesised one, so
+// callers prefer this over ``openapi-sampler`` output.
+const explicitMediaExample = (media: Record<string, unknown> | undefined): unknown => {
+  if (!media) return undefined;
+  if (media.example !== undefined) return media.example;
+  const examples = media.examples as Record<string, { value?: unknown }> | undefined;
+  if (examples && typeof examples === 'object') {
+    for (const ex of Object.values(examples)) {
+      if (ex && typeof ex === 'object' && 'value' in ex) return ex.value;
+    }
+  }
+  return undefined;
+};
+
+const stringifyExample = (value: unknown): string | undefined => {
+  if (value === undefined) return undefined;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return undefined;
+  }
+};
+
 // Get unique categories from endpoints
 const getCategories = (endpoints: ApiEndpoint[]): string[] => {
   const categories = new Set<string>();
@@ -139,7 +178,9 @@ const getCategories = (endpoints: ApiEndpoint[]): string[] => {
   return Array.from(categories).sort();
 };
 
-// Fetch schema from URL
+// Fetch schema from URL. Parses JSON explicitly (rather than
+// ``response.json()``) so a server that returns HTML or YAML yields a
+// readable error instead of an opaque ``SyntaxError: Unexpected token``.
 const fetchSchema = async (url: string): Promise<OpenApiSchema> => {
   const response = await fetch(url, {
     headers: {
@@ -147,9 +188,19 @@ const fetchSchema = async (url: string): Promise<OpenApiSchema> => {
     },
   });
   if (!response.ok) {
-    throw new Error(`Failed to fetch schema: ${response.statusText}`);
+    throw new Error(`Failed to fetch schema (HTTP ${response.status} ${response.statusText})`);
+  }
+  const text = await response.text();
+  try {
+    return JSON.parse(text) as OpenApiSchema;
+  } catch {
+    const looksYaml = /\.ya?ml($|\?)/i.test(url) || /^\s*openapi\s*:/m.test(text);
+    throw new Error(
+      looksYaml
+        ? 'Schema appears to be YAML — only JSON OpenAPI documents are supported.'
+        : 'Schema response is not valid JSON.',
+    );
   }
-  return response.json();
 };
 
 interface UseOpenApiSchemaProps {
@@ -269,17 +320,28 @@ export default function useOpenApiSchema({
       return;
     }
 
+    // Guard against a stale fetch resolving after the user switched
+    // schemas — without it a slow earlier request could flip ``loading``
+    // off (or surface an error) for a schema that is no longer current.
+    let cancelled = false;
+
     fetchSchema(currentSchema.url)
       .then((schema) => {
+        if (cancelled) return;
         setLoadedSchemas((prev) => new Map(prev).set(currentSchema.id, schema));
         consola.success(`Schema loaded: ${currentSchema.name}`);
         setLoading(false);
       })
       .catch((err) => {
+        if (cancelled) return;
         consola.error(`Error loading schema from ${currentSchema.url}:`, err);
         setError(err instanceof Error ? err.message : 'Failed to load schema');
         setLoading(false);
       });
+
+    return () => {
+      cancelled = true;
+    };
   }, [currentSchema, loadedSchemas, preloadAll]);
 
   // Preload every schema (sections-grouping mode). Each schema is fetched

package/src/tools/OpenapiViewer/utils/schemaExport.ts

@@ -23,17 +23,28 @@ import { relativePath, resolveBaseUrl } from './url';
 
 /**
  * Walk a JSON object and replace every ``$ref`` with the resolved value.
- * Shallow circular-ref protection: stops at ``maxDepth`` to avoid infinite
- * recursion on self-referential schemas (common in recursive OpenAPI types).
+ *
+ * Cycle handling: each ``$ref`` currently being expanded is tracked on an
+ * active set. If a ref points back into a ref already on the stack, the
+ * ``$ref`` node is left intact instead of being inlined — downstream
+ * consumers (``openapi-sampler``) resolve it against the raw spec, so a
+ * left-over local ref is harmless and far cheaper than inlining a
+ * recursive type ``maxDepth`` levels deep. ``maxDepth`` is still a hard
+ * backstop for pathologically wide graphs.
  */
-export function dereferenceSchema(schema: OpenApiSchema, maxDepth = 10): OpenApiSchema {
+export function dereferenceSchema(schema: OpenApiSchema, maxDepth = 50): OpenApiSchema {
     const root = schema as unknown as Record<string, unknown>;
 
     function resolveRef(ref: string): unknown {
         // Only handle local refs (#/components/schemas/Foo). External refs are
         // out of scope — the schema we have in memory is already a single file.
         if (!ref.startsWith('#/')) return null;
-        const parts = ref.slice(2).split('/');
+        // JSON Pointer un-escaping: ``~1`` → ``/``, ``~0`` → ``~`` (then
+        // percent-decoding) so component names with slashes resolve.
+        const parts = ref
+            .slice(2)
+            .split('/')
+            .map((p) => decodeURIComponent(p.replace(/~1/g, '/').replace(/~0/g, '~')));
         let node: unknown = root;
         for (const part of parts) {
             if (node && typeof node === 'object' && part in (node as Record<string, unknown>)) {
@@ -45,15 +56,24 @@ export function dereferenceSchema(schema: OpenApiSchema, maxDepth = 10): OpenApi
         return node;
     }
 
+    // Refs currently mid-expansion — detects ``A → B → A`` cycles.
+    const active = new Set<string>();
+
     function walk(value: unknown, depth: number): unknown {
         if (depth > maxDepth) return value;
         if (Array.isArray(value)) return value.map((v) => walk(v, depth + 1));
         if (value && typeof value === 'object') {
             const obj = value as Record<string, unknown>;
             if (typeof obj.$ref === 'string') {
-                const resolved = resolveRef(obj.$ref);
+                const ref = obj.$ref;
+                // Cycle — keep the ref node so the sampler can resolve it.
+                if (active.has(ref)) return obj;
+                const resolved = resolveRef(ref);
                 if (resolved === null) return obj;
-                return walk(resolved, depth + 1);
+                active.add(ref);
+                const out = walk(resolved, depth + 1);
+                active.delete(ref);
+                return out;
             }
             const out: Record<string, unknown> = {};
             for (const [k, v] of Object.entries(obj)) out[k] = walk(v, depth + 1);

package/src/tools/PrettyCode/PrettyCode.client.tsx

@@ -103,7 +103,11 @@ const PrettyCode = ({ data, language, className, mode = 'dark', inline = false,
         style={customBg ? undefined : surfaceStyle}
       >
         <div className="h-full overflow-auto p-4">
-          <p className="text-sm italic" style={{ color: isDarkMode ? '#9ca3af' : undefined }}>
+          <p
+            className="text-sm italic"
+            role="status"
+            style={{ color: isDarkMode ? '#9ca3af' : undefined }}
+          >
             {labels.noContent}
           </p>
         </div>
@@ -270,9 +274,9 @@ const PrettyCode = ({ data, language, className, mode = 'dark', inline = false,
     const inlineBgClass = customBg || (isDarkMode ? '' : 'bg-muted');
     return (
       <Highlight theme={prismTheme} code={contentJson} language={normalizedLanguage as Language}>
-        {({ className, style, tokens, getTokenProps }) => (
+        {({ className: prismClassName, style, tokens, getTokenProps }) => (
           <code
-            className={`${className} ${inlineBgClass} px-2 py-1 rounded ${isCompact ? 'text-xs' : 'text-sm'} font-mono inline-block`}
+            className={`${prismClassName} ${inlineBgClass} px-2 py-1 rounded ${isCompact ? 'text-xs' : 'text-sm'} font-mono inline-block ${className || ''}`}
             style={{
               ...style,
               ...(customBg ? undefined : inlineSurfaceStyle),
@@ -280,11 +284,11 @@ const PrettyCode = ({ data, language, className, mode = 'dark', inline = false,
               fontFamily: 'monospace',
             }}
           >
-            {tokens.map((line) => (
+            {tokens.map((line, i) =>
               line.map((token, key) => (
-                <span key={key} {...getTokenProps({ token })} />
-              ))
-            ))}
+                <span key={`${i}-${key}`} {...getTokenProps({ token })} />
+              )),
+            )}
           </code>
         )}
       </Highlight>
@@ -299,12 +303,7 @@ const PrettyCode = ({ data, language, className, mode = 'dark', inline = false,
     <div
       ref={containerRef}
       className={`group relative ${bgClass} rounded-lg border ${isDarkMode ? '' : 'border-border'} ${className || ''}`}
-      style={{
-        ...(customBg ? undefined : surfaceStyle),
-        // maxHeight caps growth at ``maxLines`` rows; without maxLines we
-        // let the block grow to fit its content (no scroll).
-        ...(maxHeightPx ? { maxHeight: `${maxHeightPx}px` } : null),
-      }}
+      style={customBg ? undefined : surfaceStyle}
     >
       {/* Toolbar: hidden by default, appears on hover. Absolute overlay so it doesn't shift layout.
           scrollIsolation is force-disabled when content fits without scrolling —
@@ -326,14 +325,22 @@ const PrettyCode = ({ data, language, className, mode = 'dark', inline = false,
         </div>
       </div>
 
-      <div className={shouldScroll ? 'h-full overflow-auto' : ''} style={shouldScroll ? { maxHeight: maxHeightPx } : undefined}>
+      <div
+        className={shouldScroll ? 'h-full overflow-auto' : ''}
+        style={shouldScroll ? { maxHeight: maxHeightPx } : undefined}
+        // When the viewer scrolls internally, make it keyboard-reachable
+        // so users without a wheel/trackpad can scroll with arrow keys.
+        {...(shouldScroll
+          ? { tabIndex: 0, role: 'region', 'aria-label': displayLanguage }
+          : {})}
+      >
         <Highlight theme={prismTheme} code={contentJson} language={normalizedLanguage as Language}>
-          {({ className, style, tokens, getLineProps, getTokenProps }) => {
+          {({ className: prismClassName, style, tokens, getLineProps, getTokenProps }) => {
             // Remove background from Prism theme - we use our own via CSS
             const { backgroundColor: _bg, ...restStyle } = style;
             return (
             <pre
-              className={`${className} rounded-lg`}
+              className={`${prismClassName} rounded-lg`}
               style={{
                 ...restStyle,
                 margin: 0,

package/src/tools/PrettyCode/lazy.tsx

@@ -10,7 +10,7 @@
  * import PrettyCode from '@djangocfg/ui-tools/pretty-code'
  */
 
-import { createLazyComponent, LoadingFallback } from '../../components';
+import { createLazyComponent } from '../../components';
 import type { Language } from 'prism-react-renderer';
 
 // ============================================================================

package/src/tools/SpeechRecognition/README.md

@@ -183,7 +183,7 @@ import {
 
 <ChatRoot
   transport={transport}
-  composerToolbarEnd={<VoiceComposerSlot />}
+  composerBlockStart={<VoiceComposerSlot />}
 />
 
 // Header flag-picker is added via ChatLauncher dock slot: