raffel 1.1.49 → 1.1.51-next.ce68de0

package/dist/docs/ui/assets/raffel-docs.css

@@ -684,6 +684,16 @@
       gap: 0;
     }
 
+    /* Drop the (empty) TOC gutter on endpoint views so the operation's
+       two-column content — docs + samples panel — can use the full width. */
+    .main-shell.main-shell-no-toc {
+      grid-template-columns: minmax(0, 1fr);
+    }
+
+    .main-shell.main-shell-no-toc .toc {
+      display: none;
+    }
+
     /* ========== SIDEBAR ========== */
     .sidebar {
       background: var(--sidebar-bg);
@@ -3535,6 +3545,39 @@
 
     .http-code-copy:hover { color: var(--text-color); border-color: var(--text-muted); }
 
+    /* Right panel (third column): keep request/response samples dark & legible
+       regardless of the active theme, matching ReDoc's sample column. */
+    .endpoint-right .endpoint-right-section + .endpoint-right-section {
+      margin-top: 24px;
+    }
+
+    .endpoint-right .http-code-samples {
+      background: rgba(0,0,0,0.25);
+      border-color: rgba(255,255,255,0.1);
+    }
+
+    .endpoint-right .http-code-samples .code-tabs {
+      background: rgba(0,0,0,0.2);
+      border-color: rgba(255,255,255,0.1);
+    }
+
+    .endpoint-right .http-code-sample-pre {
+      color: var(--code-panel-text);
+    }
+
+    .endpoint-right .code-tab {
+      color: #90a4ae;
+    }
+
+    .endpoint-right .code-tab.active {
+      background: rgba(255,255,255,0.12);
+      color: #fff;
+    }
+
+    .endpoint-right .response-subhead {
+      color: #90a4ae;
+    }
+
     /* ========== TRY IT OUT ========== */
     .try-it-out {
       background: rgba(0,0,0,0.2);

package/dist/docs/ui/assets/raffel-docs.js

@@ -1385,20 +1385,76 @@ function renderCodeExamples(endpoint, data) {
     return wrap;
 }
 // Append a JSON example block to a container.
-function appendJsonExample(container, value, label = 'Example') {
-    if (value === null || value === undefined)
-        return;
-    const head = doc.createElement('div');
-    head.className = 'response-subhead';
-    head.style.marginTop = '12px';
-    head.textContent = label;
-    container.appendChild(head);
-    const pre = doc.createElement('pre');
-    pre.className = 'http-code-sample-pre';
-    pre.style.border = '1px solid var(--border-color)';
-    pre.style.borderRadius = '8px';
-    pre.textContent = JSON.stringify(value, null, 2);
-    container.appendChild(pre);
+// Syntax-highlight a JSON value into HTML using the .sample-json token classes.
+function highlightJsonHtml(value) {
+    let json = JSON.stringify(value, null, 2);
+    if (json === undefined)
+        return '';
+    json = json.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return json.replace(/("(?:\\.|[^"\\])*"(\s*:)?|\b(?:true|false|null)\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g, (match, _token, colon) => {
+        let cls = 'json-number';
+        if (match[0] === '"')
+            cls = colon ? 'json-key' : 'json-string';
+        else if (match === 'true' || match === 'false')
+            cls = 'json-boolean';
+        else if (match === 'null')
+            cls = 'json-null';
+        return `<span class="${cls}">${match}</span>`;
+    });
+}
+// Right-panel response samples: one status tab per response, each showing the
+// generated JSON example (colorized) — ReDoc's response sample switcher.
+function renderResponseSamples(responses) {
+    const wrap = doc.createElement('div');
+    const tabs = doc.createElement('div');
+    tabs.className = 'sample-tabs';
+    const contents = doc.createElement('div');
+    contents.className = 'sample-contents';
+    const entries = Object.entries(responses);
+    entries.forEach(([status, resp], index) => {
+        const statusClass = status.startsWith('2') ? 'status-2xx'
+            : status.startsWith('4') ? 'status-4xx'
+                : status.startsWith('5') ? 'status-5xx'
+                    : '';
+        const tab = doc.createElement('button');
+        tab.type = 'button';
+        tab.className = `sample-tab ${statusClass}${index === 0 ? ' active' : ''}`;
+        tab.textContent = status;
+        const content = doc.createElement('div');
+        content.className = `sample-content${index === 0 ? ' active' : ''}`;
+        const ct = resp.content ? Object.keys(resp.content)[0] : null;
+        const schema = ct ? resp.content[ct]?.schema : null;
+        const example = schema ? generateExampleFromSchema(schema) : null;
+        if (example !== null && example !== undefined) {
+            if (ct) {
+                const typeLine = doc.createElement('div');
+                typeLine.className = 'sample-content-type';
+                typeLine.textContent = ct;
+                content.appendChild(typeLine);
+            }
+            const pre = doc.createElement('pre');
+            pre.className = 'sample-json';
+            pre.innerHTML = highlightJsonHtml(example);
+            content.appendChild(pre);
+        }
+        else {
+            const empty = doc.createElement('div');
+            empty.className = 'no-example';
+            empty.textContent = resp.description || 'No response body.';
+            content.appendChild(empty);
+        }
+        tab.onclick = () => {
+            tabs.querySelectorAll('.sample-tab').forEach((t) => t.classList.remove('active'));
+            contents.querySelectorAll('.sample-content').forEach((c) => c.classList.remove('active'));
+            tab.classList.add('active');
+            content.classList.add('active');
+        };
+        tabs.appendChild(tab);
+        contents.appendChild(content);
+    });
+    wrap.appendChild(tabs);
+    wrap.appendChild(contents);
+    return wrap;
 }
 function renderSchemaTree(parent, schema, depth = 0) {
     if (!schema)
@@ -1541,7 +1597,6 @@ function renderResponseAccordion(status, resp, openByDefault) {
         sub.textContent = `Response Body${contentType ? ` · ${contentType}` : ''}`;
         block.appendChild(sub);
         renderSchemaTree(block, schema);
-        appendJsonExample(block, generateExampleFromSchema(schema));
         body.appendChild(block);
     }
     if (!body.children.length) {
@@ -1562,6 +1617,15 @@ function renderEndpointDetails(endpoint) {
     appendProtocolConsole(container, { doc, spec, wsSpec, streamsSpec, jsonrpcSpec, activeProtocol, endpoint, data, esc, escapeAttr });
     const appendMany = (items) => items.forEach(([title, value]) => appendSchemaSubsection(container, title, value));
     if (activeProtocol === 'http') {
+        // Two-column operation layout (ReDoc-style): the left column carries the
+        // contract (params + schemas + responses); the right column is a sticky
+        // dark panel with the request samples and response examples.
+        const content = doc.createElement('div');
+        content.className = 'endpoint-content';
+        const left = doc.createElement('div');
+        left.className = 'endpoint-left';
+        const right = doc.createElement('div');
+        right.className = 'endpoint-right';
         const params = (data.parameters ?? []);
         if (params.length > 0) {
             const section = doc.createElement('div');
@@ -1578,7 +1642,7 @@ function renderEndpointDetails(endpoint) {
                 if (inGroup.length > 0)
                     section.appendChild(renderParamGroup(title, inGroup));
             });
-            container.appendChild(section);
+            left.appendChild(section);
         }
         const reqBody = data.requestBody;
         if (reqBody?.content) {
@@ -1586,12 +1650,10 @@ function renderEndpointDetails(endpoint) {
             section.className = 'endpoint-subsection';
             const contentType = Object.keys(reqBody.content)[0];
             section.innerHTML = `<div class="subsection-label">REQUEST BODY${reqBody.required ? ' <span style="color:#ef4444">required</span>' : ''}${contentType ? ` · ${esc(contentType)}` : ''}</div>`;
-            const content = reqBody.content[contentType];
-            if (content?.schema) {
-                renderSchemaTree(section, content.schema);
-                appendJsonExample(section, generateExampleFromSchema(content.schema));
-            }
-            container.appendChild(section);
+            const bodyContent = reqBody.content[contentType];
+            if (bodyContent?.schema)
+                renderSchemaTree(section, bodyContent.schema);
+            left.appendChild(section);
         }
         const responses = data.responses;
         if (responses && Object.keys(responses).length > 0) {
@@ -1611,14 +1673,25 @@ function renderEndpointDetails(endpoint) {
                 if (first)
                     first.classList.add('open');
             }
-            container.appendChild(section);
+            left.appendChild(section);
+        }
+        // Right column: request samples (cURL / JavaScript / Python / Rust).
+        const samplesSection = doc.createElement('div');
+        samplesSection.className = 'endpoint-right-section';
+        samplesSection.innerHTML = '<div class="endpoint-right-header">Request samples</div>';
+        samplesSection.appendChild(renderCodeExamples(endpoint, data));
+        right.appendChild(samplesSection);
+        // Right column: response samples (JSON examples per status code).
+        if (responses && Object.keys(responses).length > 0) {
+            const respSamples = doc.createElement('div');
+            respSamples.className = 'endpoint-right-section';
+            respSamples.innerHTML = '<div class="endpoint-right-header">Response samples</div>';
+            respSamples.appendChild(renderResponseSamples(responses));
+            right.appendChild(respSamples);
         }
-        // Request samples (cURL / JavaScript / Python / Rust)
-        const examplesSection = doc.createElement('div');
-        examplesSection.className = 'endpoint-subsection';
-        examplesSection.innerHTML = '<div class="subsection-label">REQUEST SAMPLES</div>';
-        examplesSection.appendChild(renderCodeExamples(endpoint, data));
-        container.appendChild(examplesSection);
+        content.appendChild(left);
+        content.appendChild(right);
+        container.appendChild(content);
     }
     if (activeProtocol === 'websocket') {
         appendInfoGrid(container, [['Channel Type', data.type], ['Path', endpoint.path]]);
@@ -1901,23 +1974,35 @@ function pageNavCard(entry, label, direction) {
     button.onclick = () => setDocsPage(entry.path);
     return button;
 }
+function setTocColumn(visible) {
+    const shell = doc.querySelector?.('.main-shell');
+    if (shell)
+        shell.classList.toggle('main-shell-no-toc', !visible);
+}
 function renderToc(root) {
     const toc = byId('pageToc');
     if (!toc)
         return;
     toc.textContent = '';
-    if (tocConfig.enabled === false)
+    if (tocConfig.enabled === false) {
+        setTocColumn(false);
         return;
-    if (root.querySelector?.('[data-markdown-ignore-all="true"]'))
+    }
+    if (root.querySelector?.('[data-markdown-ignore-all="true"]')) {
+        setTocColumn(false);
         return;
+    }
     const min = Number(tocConfig.minLevel ?? 2);
     const max = Number(tocConfig.maxLevel ?? 3);
     const headings = Array.from(root.querySelectorAll('h1,h2,h3,h4,h5,h6') ?? []).filter((heading) => {
         const level = Number(heading.tagName.slice(1));
         return heading.id && level >= min && level <= max && heading.dataset?.markdownIgnore !== 'true';
     });
-    if (headings.length === 0)
+    if (headings.length === 0) {
+        setTocColumn(false);
         return;
+    }
+    setTocColumn(true);
     const title = doc.createElement('div');
     title.className = 'toc-title';
     title.textContent = 'On this page';

package/dist/docs/ui/runtime/index.js

@@ -1385,20 +1385,76 @@ function renderCodeExamples(endpoint, data) {
     return wrap;
 }
 // Append a JSON example block to a container.
-function appendJsonExample(container, value, label = 'Example') {
-    if (value === null || value === undefined)
-        return;
-    const head = doc.createElement('div');
-    head.className = 'response-subhead';
-    head.style.marginTop = '12px';
-    head.textContent = label;
-    container.appendChild(head);
-    const pre = doc.createElement('pre');
-    pre.className = 'http-code-sample-pre';
-    pre.style.border = '1px solid var(--border-color)';
-    pre.style.borderRadius = '8px';
-    pre.textContent = JSON.stringify(value, null, 2);
-    container.appendChild(pre);
+// Syntax-highlight a JSON value into HTML using the .sample-json token classes.
+function highlightJsonHtml(value) {
+    let json = JSON.stringify(value, null, 2);
+    if (json === undefined)
+        return '';
+    json = json.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return json.replace(/("(?:\\.|[^"\\])*"(\s*:)?|\b(?:true|false|null)\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g, (match, _token, colon) => {
+        let cls = 'json-number';
+        if (match[0] === '"')
+            cls = colon ? 'json-key' : 'json-string';
+        else if (match === 'true' || match === 'false')
+            cls = 'json-boolean';
+        else if (match === 'null')
+            cls = 'json-null';
+        return `<span class="${cls}">${match}</span>`;
+    });
+}
+// Right-panel response samples: one status tab per response, each showing the
+// generated JSON example (colorized) — ReDoc's response sample switcher.
+function renderResponseSamples(responses) {
+    const wrap = doc.createElement('div');
+    const tabs = doc.createElement('div');
+    tabs.className = 'sample-tabs';
+    const contents = doc.createElement('div');
+    contents.className = 'sample-contents';
+    const entries = Object.entries(responses);
+    entries.forEach(([status, resp], index) => {
+        const statusClass = status.startsWith('2') ? 'status-2xx'
+            : status.startsWith('4') ? 'status-4xx'
+                : status.startsWith('5') ? 'status-5xx'
+                    : '';
+        const tab = doc.createElement('button');
+        tab.type = 'button';
+        tab.className = `sample-tab ${statusClass}${index === 0 ? ' active' : ''}`;
+        tab.textContent = status;
+        const content = doc.createElement('div');
+        content.className = `sample-content${index === 0 ? ' active' : ''}`;
+        const ct = resp.content ? Object.keys(resp.content)[0] : null;
+        const schema = ct ? resp.content[ct]?.schema : null;
+        const example = schema ? generateExampleFromSchema(schema) : null;
+        if (example !== null && example !== undefined) {
+            if (ct) {
+                const typeLine = doc.createElement('div');
+                typeLine.className = 'sample-content-type';
+                typeLine.textContent = ct;
+                content.appendChild(typeLine);
+            }
+            const pre = doc.createElement('pre');
+            pre.className = 'sample-json';
+            pre.innerHTML = highlightJsonHtml(example);
+            content.appendChild(pre);
+        }
+        else {
+            const empty = doc.createElement('div');
+            empty.className = 'no-example';
+            empty.textContent = resp.description || 'No response body.';
+            content.appendChild(empty);
+        }
+        tab.onclick = () => {
+            tabs.querySelectorAll('.sample-tab').forEach((t) => t.classList.remove('active'));
+            contents.querySelectorAll('.sample-content').forEach((c) => c.classList.remove('active'));
+            tab.classList.add('active');
+            content.classList.add('active');
+        };
+        tabs.appendChild(tab);
+        contents.appendChild(content);
+    });
+    wrap.appendChild(tabs);
+    wrap.appendChild(contents);
+    return wrap;
 }
 function renderSchemaTree(parent, schema, depth = 0) {
     if (!schema)
@@ -1541,7 +1597,6 @@ function renderResponseAccordion(status, resp, openByDefault) {
         sub.textContent = `Response Body${contentType ? ` · ${contentType}` : ''}`;
         block.appendChild(sub);
         renderSchemaTree(block, schema);
-        appendJsonExample(block, generateExampleFromSchema(schema));
         body.appendChild(block);
     }
     if (!body.children.length) {
@@ -1562,6 +1617,15 @@ function renderEndpointDetails(endpoint) {
     appendProtocolConsole(container, { doc, spec, wsSpec, streamsSpec, jsonrpcSpec, activeProtocol, endpoint, data, esc, escapeAttr });
     const appendMany = (items) => items.forEach(([title, value]) => appendSchemaSubsection(container, title, value));
     if (activeProtocol === 'http') {
+        // Two-column operation layout (ReDoc-style): the left column carries the
+        // contract (params + schemas + responses); the right column is a sticky
+        // dark panel with the request samples and response examples.
+        const content = doc.createElement('div');
+        content.className = 'endpoint-content';
+        const left = doc.createElement('div');
+        left.className = 'endpoint-left';
+        const right = doc.createElement('div');
+        right.className = 'endpoint-right';
         const params = (data.parameters ?? []);
         if (params.length > 0) {
             const section = doc.createElement('div');
@@ -1578,7 +1642,7 @@ function renderEndpointDetails(endpoint) {
                 if (inGroup.length > 0)
                     section.appendChild(renderParamGroup(title, inGroup));
             });
-            container.appendChild(section);
+            left.appendChild(section);
         }
         const reqBody = data.requestBody;
         if (reqBody?.content) {
@@ -1586,12 +1650,10 @@ function renderEndpointDetails(endpoint) {
             section.className = 'endpoint-subsection';
             const contentType = Object.keys(reqBody.content)[0];
             section.innerHTML = `<div class="subsection-label">REQUEST BODY${reqBody.required ? ' <span style="color:#ef4444">required</span>' : ''}${contentType ? ` · ${esc(contentType)}` : ''}</div>`;
-            const content = reqBody.content[contentType];
-            if (content?.schema) {
-                renderSchemaTree(section, content.schema);
-                appendJsonExample(section, generateExampleFromSchema(content.schema));
-            }
-            container.appendChild(section);
+            const bodyContent = reqBody.content[contentType];
+            if (bodyContent?.schema)
+                renderSchemaTree(section, bodyContent.schema);
+            left.appendChild(section);
         }
         const responses = data.responses;
         if (responses && Object.keys(responses).length > 0) {
@@ -1611,14 +1673,25 @@ function renderEndpointDetails(endpoint) {
                 if (first)
                     first.classList.add('open');
             }
-            container.appendChild(section);
+            left.appendChild(section);
+        }
+        // Right column: request samples (cURL / JavaScript / Python / Rust).
+        const samplesSection = doc.createElement('div');
+        samplesSection.className = 'endpoint-right-section';
+        samplesSection.innerHTML = '<div class="endpoint-right-header">Request samples</div>';
+        samplesSection.appendChild(renderCodeExamples(endpoint, data));
+        right.appendChild(samplesSection);
+        // Right column: response samples (JSON examples per status code).
+        if (responses && Object.keys(responses).length > 0) {
+            const respSamples = doc.createElement('div');
+            respSamples.className = 'endpoint-right-section';
+            respSamples.innerHTML = '<div class="endpoint-right-header">Response samples</div>';
+            respSamples.appendChild(renderResponseSamples(responses));
+            right.appendChild(respSamples);
         }
-        // Request samples (cURL / JavaScript / Python / Rust)
-        const examplesSection = doc.createElement('div');
-        examplesSection.className = 'endpoint-subsection';
-        examplesSection.innerHTML = '<div class="subsection-label">REQUEST SAMPLES</div>';
-        examplesSection.appendChild(renderCodeExamples(endpoint, data));
-        container.appendChild(examplesSection);
+        content.appendChild(left);
+        content.appendChild(right);
+        container.appendChild(content);
     }
     if (activeProtocol === 'websocket') {
         appendInfoGrid(container, [['Channel Type', data.type], ['Path', endpoint.path]]);
@@ -1901,23 +1974,35 @@ function pageNavCard(entry, label, direction) {
     button.onclick = () => setDocsPage(entry.path);
     return button;
 }
+function setTocColumn(visible) {
+    const shell = doc.querySelector?.('.main-shell');
+    if (shell)
+        shell.classList.toggle('main-shell-no-toc', !visible);
+}
 function renderToc(root) {
     const toc = byId('pageToc');
     if (!toc)
         return;
     toc.textContent = '';
-    if (tocConfig.enabled === false)
+    if (tocConfig.enabled === false) {
+        setTocColumn(false);
         return;
-    if (root.querySelector?.('[data-markdown-ignore-all="true"]'))
+    }
+    if (root.querySelector?.('[data-markdown-ignore-all="true"]')) {
+        setTocColumn(false);
         return;
+    }
     const min = Number(tocConfig.minLevel ?? 2);
     const max = Number(tocConfig.maxLevel ?? 3);
     const headings = Array.from(root.querySelectorAll('h1,h2,h3,h4,h5,h6') ?? []).filter((heading) => {
         const level = Number(heading.tagName.slice(1));
         return heading.id && level >= min && level <= max && heading.dataset?.markdownIgnore !== 'true';
     });
-    if (headings.length === 0)
+    if (headings.length === 0) {
+        setTocColumn(false);
         return;
+    }
+    setTocColumn(true);
     const title = doc.createElement('div');
     title.className = 'toc-title';
     title.textContent = 'On this page';