@redocly/realm-plugin-asciidoc 0.1.0

package/src/template.tsx

@@ -0,0 +1,628 @@
+import React, { useCallback, useMemo, useState } from 'react';
+import styled from 'styled-components';
+import { Admonition, CodeBlock, Markdown, useThemeHooks } from '@redocly/theme';
+
+import type {
+  AsciidocFrontmatter,
+  AsciidocSection,
+  CodeBlockNode,
+  ContentNode,
+  InlineIcon,
+  ListItemNode,
+  DescriptionListItemNode,
+  TableCellNode,
+} from './types.js';
+
+import { DocumentationLayout } from '@redocly/theme/layouts/DocumentationLayout';
+import { TableOfContent } from '@redocly/theme/components/TableOfContent/TableOfContent';
+import { Heading } from '@redocly/theme/markdoc/components/Heading/Heading';
+import { CDNIcon } from '@redocly/theme/icons/CDNIcon/CDNIcon';
+
+type PageProps = {
+  title: string;
+  contentNodes: ContentNode[];
+  sections: AsciidocSection[];
+  links: Array<{ href: string; text: string; type: string }>;
+  frontmatter: AsciidocFrontmatter;
+};
+
+type AsciidocDocsProps = {
+  pageProps: PageProps;
+};
+
+function buildTocHeadings(
+  sections: AsciidocSection[],
+): Array<{ id: string; value: string; depth: number }> {
+  const items: Array<{ id: string; value: string; depth: number }> = [];
+  for (const section of sections) {
+    items.push({ id: section.id, value: section.title, depth: section.level });
+    if (section.children.length > 0) {
+      items.push(...buildTocHeadings(section.children));
+    }
+  }
+  return items;
+}
+
+/**
+ * Renders an HTML string that may contain `<!--icon:N-->` placeholders,
+ * splitting the HTML and interleaving CDNIcon React components.
+ */
+function renderHtmlWithIcons(
+  html: string,
+  icons: InlineIcon[],
+  keyPrefix: string,
+): React.ReactNode {
+  if (!icons.length || !html.includes('<!--icon:')) {
+    return <span key={keyPrefix} dangerouslySetInnerHTML={{ __html: html }} />;
+  }
+
+  const parts = html.split(/(<!--icon:\d+-->)/);
+  const nodes: React.ReactNode[] = [];
+
+  for (let j = 0; j < parts.length; j++) {
+    const fragment = parts[j];
+    const iconMatch = fragment.match(/<!--icon:(\d+)-->/);
+    if (iconMatch) {
+      const idx = parseInt(iconMatch[1], 10);
+      const icon = icons[idx];
+      if (icon) {
+        nodes.push(
+          <CDNIcon
+            key={`${keyPrefix}-icon-${idx}`}
+            name={icon.name}
+            type={icon.style}
+            size={icon.size}
+          />,
+        );
+      }
+    } else if (fragment) {
+      nodes.push(
+        <span key={`${keyPrefix}-f-${j}`} dangerouslySetInnerHTML={{ __html: fragment }} />,
+      );
+    }
+  }
+
+  return <>{nodes}</>;
+}
+
+function injectCalloutBadges(html: string, callouts: { line: number; number: number }[]): string {
+  if (!callouts.length) return html;
+
+  const calloutByLine = new Map(callouts.map((c) => [c.line, c.number]));
+  let lineNumber = 0;
+
+  return html.replace(/<span class="line">(.*?)<\/span>/g, (match, inner) => {
+    lineNumber++;
+    const calloutNumber = calloutByLine.get(lineNumber);
+    if (calloutNumber != null) {
+      return `<span class="line">${inner}<span class="code-callout-badge" data-callout="${calloutNumber}">${calloutNumber}</span></span>`;
+    }
+    return match;
+  });
+}
+
+function AsciidocCodeBlock({ node }: { node: CodeBlockNode }): React.ReactElement {
+  const { useCodeHighlight } = useThemeHooks();
+  const { highlight } = useCodeHighlight() || {};
+
+  const highlightLines = node.callouts?.map((c) => String(c.line)).join(',');
+
+  const highlightedHtml = useMemo(() => {
+    if (!highlight) return undefined;
+
+    let html = highlight(node.source, node.lang, {
+      highlight: highlightLines,
+    });
+
+    if (html && node.callouts?.length) {
+      html = injectCalloutBadges(html, node.callouts);
+    }
+
+    return html || undefined;
+  }, [highlight, node.source, node.lang, highlightLines, node.callouts]);
+
+  return (
+    <CodeBlock
+      lang={node.lang}
+      source={node.source}
+      highlightedHtml={highlightedHtml}
+      header={
+        node.title || node.lang
+          ? {
+              title: node.title || node.lang,
+              controls: { copy: {} },
+            }
+          : { controls: { copy: {} } }
+      }
+    />
+  );
+}
+
+// Counter to track heading index for PageActions (Copy button shown on first heading)
+let headingCounter = 0;
+
+function RenderNode({
+  node,
+  index,
+}: {
+  node: ContentNode;
+  index: number;
+}): React.ReactElement | null {
+  const key = `node-${index}`;
+
+  switch (node.type) {
+    case 'section': {
+      const __idx = headingCounter++;
+      return (
+        <React.Fragment key={key}>
+          <Heading level={node.level} id={node.id} __idx={__idx}>
+            {renderHtmlWithIcons(node.titleHtml, node.titleIcons, `${key}-title`)}
+          </Heading>
+          <RenderNodes nodes={node.children} keyPrefix={key} />
+        </React.Fragment>
+      );
+    }
+
+    case 'heading': {
+      const __idx = headingCounter++;
+      return (
+        <Heading key={key} level={node.level} id={node.id} __idx={__idx}>
+          <span dangerouslySetInnerHTML={{ __html: node.contentHtml }} />
+        </Heading>
+      );
+    }
+
+    case 'paragraph': {
+      const Tag = node.role ? 'div' : 'p';
+      const className = node.role || undefined;
+      return (
+        <Tag key={key} className={className}>
+          {renderHtmlWithIcons(node.contentHtml, node.icons, key)}
+        </Tag>
+      );
+    }
+
+    case 'codeBlock': {
+      return (
+        <React.Fragment key={key}>
+          <AsciidocCodeBlock node={node} />
+          {node.calloutDescriptions && node.calloutDescriptions.length > 0 && (
+            <ol className="callout-list">
+              {node.calloutDescriptions.map((desc, i) => (
+                <li key={`${key}-co-${i}`}>
+                  <span className="callout-badge">{i + 1}</span>
+                  <span dangerouslySetInnerHTML={{ __html: desc }} />
+                </li>
+              ))}
+            </ol>
+          )}
+        </React.Fragment>
+      );
+    }
+
+    case 'admonition':
+      return (
+        <Admonition key={key} type={node.admonitionType} name={node.name}>
+          <RenderNodes nodes={node.children} keyPrefix={key} />
+        </Admonition>
+      );
+
+    case 'list': {
+      const ListTag = node.ordered ? 'ol' : 'ul';
+      return (
+        <ListTag key={key} className="md">
+          {node.items.map((item, i) => (
+            <RenderListItem key={`${key}-li-${i}`} item={item} keyPrefix={`${key}-li-${i}`} />
+          ))}
+        </ListTag>
+      );
+    }
+
+    case 'descriptionList':
+      return (
+        <dl key={key} className="dlist">
+          {node.items.map((item, i) => (
+            <RenderDlistItem key={`${key}-dl-${i}`} item={item} keyPrefix={`${key}-dl-${i}`} />
+          ))}
+        </dl>
+      );
+
+    case 'table':
+      return (
+        <div key={key} className="md-table-wrapper">
+          <table className="md">
+            {node.title && <caption>{node.title}</caption>}
+            {node.head.length > 0 && (
+              <thead>
+                {node.head.map((row, ri) => (
+                  <tr key={`${key}-th-${ri}`}>
+                    {row.map((cell, ci) => (
+                      <RenderTableCell key={`${key}-th-${ri}-${ci}`} cell={cell} tag="th" />
+                    ))}
+                  </tr>
+                ))}
+              </thead>
+            )}
+            <tbody>
+              {node.body.map((row, ri) => (
+                <tr key={`${key}-tb-${ri}`}>
+                  {row.map((cell, ci) => (
+                    <RenderTableCell key={`${key}-tb-${ri}-${ci}`} cell={cell} tag="td" />
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+            {node.foot.length > 0 && (
+              <tfoot>
+                {node.foot.map((row, ri) => (
+                  <tr key={`${key}-tf-${ri}`}>
+                    {row.map((cell, ci) => (
+                      <RenderTableCell key={`${key}-tf-${ri}-${ci}`} cell={cell} tag="td" />
+                    ))}
+                  </tr>
+                ))}
+              </tfoot>
+            )}
+          </table>
+        </div>
+      );
+
+    case 'image':
+      return (
+        <div key={key} className="imageblock">
+          <img
+            src={node.src}
+            alt={node.alt}
+            {...(node.width ? { width: node.width } : {})}
+            {...(node.height ? { height: node.height } : {})}
+          />
+          {node.title && <div className="title">{node.title}</div>}
+        </div>
+      );
+
+    case 'quote':
+      return (
+        <div key={key} className="quoteblock">
+          <blockquote>
+            <RenderNodes nodes={node.children} keyPrefix={key} />
+          </blockquote>
+          {node.attribution && (
+            <div className="attribution">
+              — {node.attribution}
+              {node.citeTitle && (
+                <>
+                  , <cite>{node.citeTitle}</cite>
+                </>
+              )}
+            </div>
+          )}
+        </div>
+      );
+
+    case 'sidebar':
+      return (
+        <div key={key} className="sidebarblock">
+          <div className="content">
+            {node.title && <div className="title">{node.title}</div>}
+            <RenderNodes nodes={node.children} keyPrefix={key} />
+          </div>
+        </div>
+      );
+
+    case 'example':
+      return (
+        <div key={key} className="exampleblock">
+          <div className="content">
+            {node.title && <div className="title">{node.title}</div>}
+            <RenderNodes nodes={node.children} keyPrefix={key} />
+          </div>
+        </div>
+      );
+
+    case 'collapsible':
+      return (
+        <details key={key}>
+          {node.title && <summary>{node.title}</summary>}
+          <RenderNodes nodes={node.children} keyPrefix={key} />
+        </details>
+      );
+
+    case 'thematicBreak':
+      return <hr key={key} />;
+
+    case 'htmlPassthrough':
+      return <div key={key} dangerouslySetInnerHTML={{ __html: node.html }} />;
+
+    default:
+      return null;
+  }
+}
+
+function RenderNodes({
+  nodes,
+  keyPrefix,
+}: {
+  nodes: ContentNode[];
+  keyPrefix: string;
+}): React.ReactElement {
+  return (
+    <>
+      {nodes.map((node, i) => (
+        <RenderNode key={`${keyPrefix}-${i}`} node={node} index={i} />
+      ))}
+    </>
+  );
+}
+
+function RenderListItem({
+  item,
+  keyPrefix,
+}: {
+  item: ListItemNode;
+  keyPrefix: string;
+}): React.ReactElement {
+  return (
+    <li>
+      {renderHtmlWithIcons(item.contentHtml, item.icons, keyPrefix)}
+      {item.children.length > 0 && <RenderNodes nodes={item.children} keyPrefix={keyPrefix} />}
+    </li>
+  );
+}
+
+function RenderDlistItem({
+  item,
+  keyPrefix,
+}: {
+  item: DescriptionListItemNode;
+  keyPrefix: string;
+}): React.ReactElement {
+  return (
+    <>
+      {item.termsHtml.map((termHtml, ti) => (
+        <dt key={`${keyPrefix}-dt-${ti}`} dangerouslySetInnerHTML={{ __html: termHtml }} />
+      ))}
+      <dd>
+        {renderHtmlWithIcons(item.descriptionHtml, item.descriptionIcons, `${keyPrefix}-dd`)}
+        {item.children.length > 0 && (
+          <RenderNodes nodes={item.children} keyPrefix={`${keyPrefix}-dd`} />
+        )}
+      </dd>
+    </>
+  );
+}
+
+function RenderTableCell({
+  cell,
+  tag: Tag,
+}: {
+  cell: TableCellNode;
+  tag: 'th' | 'td';
+}): React.ReactElement {
+  return (
+    <Tag
+      {...(cell.colSpan ? { colSpan: cell.colSpan } : {})}
+      {...(cell.rowSpan ? { rowSpan: cell.rowSpan } : {})}
+      dangerouslySetInnerHTML={{ __html: cell.contentHtml }}
+    />
+  );
+}
+
+const Template: React.FC<AsciidocDocsProps> = ({ pageProps }) => {
+  const { useSidebarSiblingsData } = useThemeHooks();
+  const { nextPage, prevPage } = useSidebarSiblingsData() || {};
+  const [wrapperElement, setWrapperElement] = useState<HTMLDivElement | null>(null);
+
+  const wrapperRefCb = useCallback((node: HTMLDivElement) => {
+    if (!node) return;
+    setWrapperElement(node);
+  }, []);
+
+  const tocHeadings = useMemo(() => {
+    const items = buildTocHeadings(pageProps.sections);
+    return items.filter((item) => Boolean(item.id) && Boolean(item.value));
+  }, [pageProps.sections]);
+
+  const tableOfContent = <TableOfContent headings={tocHeadings} contentWrapper={wrapperElement} />;
+
+  // Reset heading counter for each page render (used for __idx tracking)
+  headingCounter = 0;
+
+  return (
+    <DocumentationLayout
+      tableOfContent={tableOfContent}
+      feedback={undefined}
+      nextPage={nextPage}
+      prevPage={prevPage}
+    >
+      <AsciidocWrapper ref={wrapperRefCb} as="div" className="asciidoc-content">
+        <RenderNodes nodes={pageProps.contentNodes} keyPrefix="root" />
+      </AsciidocWrapper>
+    </DocumentationLayout>
+  );
+};
+
+export default Template;
+
+const AsciidocWrapper = styled(Markdown)`
+  /* === Fix list item <p> margins === */
+  li > p:only-child {
+    margin: 0;
+  }
+
+  li > .paragraph:first-child > p:first-child {
+    margin-top: 0;
+  }
+
+  li > .paragraph:last-child > p:last-child {
+    margin-bottom: 0;
+  }
+
+  li > p:first-child {
+    margin-top: 0;
+  }
+
+  li > p:last-child {
+    margin-bottom: 0;
+  }
+
+  /* === AsciiDoc description lists === */
+  .dlist dt,
+  dl.dlist dt {
+    font-weight: var(--font-weight-semibold, 600);
+    margin-top: var(--spacing-xs, 0.5em);
+  }
+
+  .dlist dd,
+  dl.dlist dd {
+    margin-left: var(--md-list-left-padding, 1.25rem);
+    margin-bottom: calc(var(--spacing-xxs, 0.25em) / 2);
+  }
+
+  /* === AsciiDoc images === */
+  .imageblock {
+    margin: var(--spacing-base, 1em) 0;
+    text-align: center;
+  }
+
+  .imageblock img {
+    max-width: 100%;
+    height: auto;
+  }
+
+  .imageblock .title {
+    font-style: italic;
+    margin-top: var(--spacing-xxs, 0.25em);
+    color: var(--text-color-secondary, #666);
+    font-size: var(--font-size-sm, 0.875em);
+  }
+
+  /* === AsciiDoc quote blocks === */
+  .quoteblock {
+    margin: var(--md-blockquote-margin-vertical, 1em) var(--md-blockquote-margin-horizontal, 0);
+    padding: var(--md-blockquote-padding-vertical, 0.5em) var(--md-blockquote-padding-horizontal, 1em);
+    border-left: var(--md-blockquote-border-left, 3px solid var(--border-color-secondary, #ddd));
+    background-color: var(--md-blockquote-bg-color, transparent);
+    color: var(--md-blockquote-text-color, var(--text-color-secondary, #666));
+  }
+
+  .quoteblock blockquote {
+    margin: 0;
+    padding: 0;
+    border: none;
+    background: transparent;
+  }
+
+  .quoteblock .attribution {
+    margin-top: var(--spacing-xs, 0.5em);
+    font-style: italic;
+  }
+
+  /* === AsciiDoc sidebar blocks === */
+  .sidebarblock {
+    margin: var(--spacing-base, 1em) 0;
+    padding: var(--spacing-sm, 0.75em) var(--spacing-base, 1em);
+    background-color: var(--layer-color, #f8f8f8);
+    border-radius: var(--border-radius-lg, 6px);
+    border: 1px solid var(--border-color-secondary, #e0e0e0);
+  }
+
+  .sidebarblock > .content > .title {
+    font-weight: var(--font-weight-semibold, 600);
+    margin-bottom: var(--spacing-xs, 0.5em);
+  }
+
+  /* === AsciiDoc example blocks === */
+  .exampleblock > .content {
+    padding: var(--spacing-sm, 0.75em) var(--spacing-base, 1em);
+    border: 1px solid var(--border-color-secondary, #e0e0e0);
+    border-radius: var(--border-radius-lg, 6px);
+    margin: var(--spacing-xs, 0.5em) 0;
+  }
+
+  /* === Callout badges in code blocks === */
+  .code-callout-badge {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 1.25em;
+    height: 1.25em;
+    border-radius: 50%;
+    background-color: var(--callout-badge-bg, #333);
+    color: var(--callout-badge-color, #fff);
+    font-size: 0.75em;
+    font-weight: 600;
+    margin-left: 0.5em;
+    vertical-align: middle;
+    user-select: none;
+  }
+
+  /* === Callout lists === */
+  .callout-list {
+    margin-top: var(--spacing-xs, 0.5em);
+    margin-bottom: var(--spacing-base, 1em);
+    padding-left: 0;
+    list-style: none;
+  }
+
+  .callout-list li {
+    display: flex;
+    align-items: baseline;
+    gap: 0.5em;
+    margin-bottom: 0.25em;
+  }
+
+  .callout-badge {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: 1.25em;
+    height: 1.25em;
+    border-radius: 50%;
+    background-color: var(--callout-badge-bg, #333);
+    color: var(--callout-badge-color, #fff);
+    font-size: 0.75em;
+    font-weight: var(--font-weight-semibold, 600);
+    flex-shrink: 0;
+  }
+
+  /* === AsciiDoc roles (custom CSS classes) === */
+  .underline {
+    text-decoration: underline;
+  }
+
+  .line-through {
+    text-decoration: line-through;
+  }
+
+  .text-center {
+    text-align: center;
+  }
+
+  .text-right {
+    text-align: right;
+  }
+
+  /* === AsciiDoc footer rows === */
+  table tfoot {
+    font-weight: var(--font-weight-semibold, 600);
+    background-color: var(--layer-color, #f8f8f8);
+  }
+
+  /* === Collapsible blocks === */
+  details {
+    margin: var(--spacing-base, 1em) 0;
+    border: 1px solid var(--border-color-secondary, #e0e0e0);
+    border-radius: var(--border-radius-lg, 6px);
+    padding: var(--spacing-sm, 0.75em) var(--spacing-base, 1em);
+  }
+
+  details summary {
+    cursor: pointer;
+    font-weight: var(--font-weight-semibold, 600);
+    margin-bottom: var(--spacing-xs, 0.5em);
+  }
+
+  details[open] summary {
+    margin-bottom: var(--spacing-sm, 0.75em);
+  }
+`;