docusaurus-plugin-generate-schema-docs 1.8.2 → 1.8.3

package/components/SchemaJsonViewer.js

@@ -1,11 +1,228 @@
-import React from 'react';
-import CodeBlock from '@theme/CodeBlock';
+import React, { Fragment, useState } from 'react';
+import Link from '@docusaurus/Link';
+
+function isPlainObject(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+function isExternalRef(value) {
+  return typeof value === 'string' && /^https?:\/\//.test(value);
+}
+
+function normalizePathSegments(pathValue) {
+  const normalized = pathValue.replace(/\\/g, '/');
+  const isAbsolute = normalized.startsWith('/');
+  const segments = normalized.split('/');
+  const resolvedSegments = [];
+
+  segments.forEach((segment) => {
+    if (!segment || segment === '.') return;
+    if (segment === '..') {
+      resolvedSegments.pop();
+      return;
+    }
+    resolvedSegments.push(segment);
+  });
+
+  return `${isAbsolute ? '/' : ''}${resolvedSegments.join('/')}`;
+}
+
+function dirname(pathValue) {
+  const normalized = normalizePathSegments(pathValue);
+  const segments = normalized.split('/');
+
+  if (segments.length <= 1) {
+    return normalized.startsWith('/') ? '/' : '.';
+  }
+
+  segments.pop();
+  const joined = segments.join('/');
+  return joined || '/';
+}
+
+function resolveLocalRef(currentPath, refValue) {
+  if (!currentPath || typeof refValue !== 'string') return null;
+  if (refValue.startsWith('#')) return null;
+  return normalizePathSegments(`${dirname(currentPath)}/${refValue}`);
+}
+
+function JsonIndent({ depth }) {
+  return <span>{'  '.repeat(depth)}</span>;
+}
+
+function JsonPrimitive({
+  value,
+  propertyKey,
+  currentPath,
+  schemaSources,
+  onNavigate,
+}) {
+  const interactiveRefClassName = 'schema-json-viewer__link';
+  const quotedValue = `${JSON.stringify(value)}`;
+
+  if (typeof value === 'string') {
+    if (propertyKey === '$ref') {
+      if (isExternalRef(value)) {
+        return (
+          <Link
+            className={interactiveRefClassName}
+            href={value}
+            target="_blank"
+            rel="noreferrer"
+          >
+            {quotedValue}
+          </Link>
+        );
+      }
+
+      const resolvedRef = resolveLocalRef(currentPath, value);
+      if (resolvedRef && schemaSources?.[resolvedRef]) {
+        return (
+          <button
+            type="button"
+            className={interactiveRefClassName}
+            onClick={() => onNavigate(resolvedRef)}
+          >
+            {quotedValue}
+          </button>
+        );
+      }
+    }
+
+    return <span className="token string">{quotedValue}</span>;
+  }
+
+  if (typeof value === 'number') {
+    return <span className="token number">{value}</span>;
+  }
+
+  if (typeof value === 'boolean') {
+    return <span className="token boolean">{String(value)}</span>;
+  }
+
+  return <span className="token null keyword">null</span>;
+}
+
+function JsonNode({
+  value,
+  depth,
+  currentPath,
+  schemaSources,
+  onNavigate,
+  propertyKey = null,
+}) {
+  if (Array.isArray(value)) {
+    return (
+      <>
+        <span className="token punctuation">[</span>
+        {value.length > 0 && <br />}
+        {value.map((item, index) => (
+          <Fragment key={`${depth}-${index}`}>
+            <JsonIndent depth={depth + 1} />
+            <JsonNode
+              value={item}
+              depth={depth + 1}
+              currentPath={currentPath}
+              schemaSources={schemaSources}
+              onNavigate={onNavigate}
+            />
+            {index < value.length - 1 && (
+              <span className="token punctuation">,</span>
+            )}
+            <br />
+          </Fragment>
+        ))}
+        {value.length > 0 && <JsonIndent depth={depth} />}
+        <span className="token punctuation">]</span>
+      </>
+    );
+  }
+
+  if (isPlainObject(value)) {
+    const entries = Object.entries(value);
+    return (
+      <>
+        <span className="token punctuation">{'{'}</span>
+        {entries.length > 0 && <br />}
+        {entries.map(([key, child], index) => (
+          <Fragment key={`${depth}-${key}`}>
+            <JsonIndent depth={depth + 1} />
+            <span className="token property">{JSON.stringify(key)}</span>
+            <span className="token punctuation">: </span>
+            <JsonNode
+              value={child}
+              depth={depth + 1}
+              currentPath={currentPath}
+              schemaSources={schemaSources}
+              onNavigate={onNavigate}
+              propertyKey={key}
+            />
+            {index < entries.length - 1 && (
+              <span className="token punctuation">,</span>
+            )}
+            <br />
+          </Fragment>
+        ))}
+        {entries.length > 0 && <JsonIndent depth={depth} />}
+        <span className="token punctuation">{'}'}</span>
+      </>
+    );
+  }
+
+  return (
+    <JsonPrimitive
+      value={value}
+      propertyKey={propertyKey}
+      currentPath={currentPath}
+      schemaSources={schemaSources}
+      onNavigate={onNavigate}
+    />
+  );
+}
+
+export default function SchemaJsonViewer({
+  schema,
+  sourcePath = null,
+  schemaSources = null,
+}) {
+  const resolvedSchemaSources =
+    schemaSources || (sourcePath ? { [sourcePath]: schema } : {});
+  const rootPath = sourcePath;
+  const [currentPath, setCurrentPath] = useState(rootPath);
+
+  const currentSchema =
+    (currentPath && resolvedSchemaSources?.[currentPath]) || schema;
 
-export default function SchemaJsonViewer({ schema }) {
   return (
     <details className="schema-json-viewer">
       <summary>View Raw JSON Schema</summary>
-      <CodeBlock language="json">{JSON.stringify(schema, null, 2)}</CodeBlock>
+      {rootPath && currentPath !== rootPath ? (
+        <div className="schema-json-viewer__controls">
+          <button
+            type="button"
+            className="schema-json-viewer__link"
+            onClick={() => setCurrentPath(rootPath)}
+          >
+            Back to root
+          </button>
+        </div>
+      ) : null}
+      <pre data-language="json">
+        <code className="language-json">
+          <JsonNode
+            value={currentSchema}
+            depth={0}
+            currentPath={currentPath}
+            schemaSources={resolvedSchemaSources}
+            onNavigate={setCurrentPath}
+          />
+        </code>
+      </pre>
     </details>
   );
 }

package/components/SchemaRows.css

@@ -1,4 +1,4 @@
-.required-row {
+.property-cell--required {
   background-color: rgba(var(--ifm-color-danger-rgb), 0.05);
 }
 
@@ -26,6 +26,26 @@
   margin-bottom: 1em;
 }
 
+.schema-json-viewer__controls {
+  margin: 0.5rem 0;
+}
+
+.schema-json-viewer__link {
+  appearance: none;
+  background: none;
+  border: none;
+  color: var(--ifm-link-color);
+  cursor: pointer;
+  font: inherit;
+  padding: 0;
+  text-decoration: none;
+}
+
+.schema-json-viewer__link:hover {
+  color: var(--ifm-link-hover-color);
+  text-decoration: underline;
+}
+
 /* --- Property Name and Container Symbol Styles --- */
 
 .property-name {
@@ -34,6 +54,61 @@
   gap: 4px;
 }
 
+.property-name--keyword {
+  align-items: center;
+}
+
+.property-keyword-wrapper {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+}
+
+.property-keyword-stack {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.2rem;
+}
+
+.property-keyword {
+  font-size: 0.95em;
+  font-weight: 600;
+}
+
+.property-keyword-pattern {
+  font-size: 0.85em;
+  color: var(--ifm-color-emphasis-700);
+}
+
+.property-keyword-tooltip {
+  position: absolute;
+  left: 0;
+  bottom: calc(100% + 0.4rem);
+  z-index: 3;
+  min-width: 14rem;
+  max-width: 18rem;
+  padding: 0.5rem 0.625rem;
+  border-radius: 0.375rem;
+  background: var(--ifm-background-surface-color);
+  border: 1px solid var(--ifm-table-border-color);
+  box-shadow: var(--ifm-global-shadow-lw);
+  color: var(--ifm-font-color-base);
+  font-size: 0.8rem;
+  line-height: 1.35;
+  opacity: 0;
+  pointer-events: none;
+  transform: translateY(0.125rem);
+  transition:
+    opacity 120ms ease,
+    transform 120ms ease;
+}
+
+.property-keyword-wrapper:hover .property-keyword-tooltip {
+  opacity: 1;
+  transform: translateY(0);
+}
+
 .container-symbol {
   font-family: var(--ifm-font-family-monospace);
   font-size: 0.9em;
@@ -67,6 +142,10 @@
   border-left: none;
 }
 
+.schema-table td[colspan='5'] {
+  border-left: none;
+}
+
 /*
  * Constraint-only continuation rows render a single cell; in those rows that
  * cell is also :first-child, but it still needs the separator before the
@@ -85,6 +164,18 @@
   box-shadow: inset 0 1px 0 var(--ifm-table-border-color);
 }
 
+.schema-table tbody tr.schema-row--zebra-even {
+  background-color: var(--ifm-table-stripe-background);
+}
+
+.schema-table tbody tr.schema-row--zebra-odd {
+  background-color: transparent;
+}
+
+.schema-table tbody tr.schema-row--control {
+  background-color: transparent;
+}
+
 /* --- Organigram Connector Line Styles --- */
 
 /*
@@ -108,10 +199,12 @@ td.has-children {
 td[class*='level-']::before {
   content: '';
   position: absolute;
-  top: 0;
-  bottom: 0;
+  top: -1px;
+  bottom: -1px;
   width: 0;
   border-left: 1px solid var(--ifm-table-border-color);
+  z-index: 1;
+  pointer-events: none;
 }
 
 /* Last items: stop vertical line at middle */
@@ -130,6 +223,8 @@ td[class*='level-']::after {
   height: 0;
   width: 0.75rem;
   border-bottom: 1px solid var(--ifm-table-border-color);
+  z-index: 1;
+  pointer-events: none;
 }
 
 /* --- Level-based positioning --- */
@@ -172,10 +267,6 @@ td.level-6::after {
 
 /* --- Choice Row Styles --- */
 
-.choice-row {
-  background-color: var(--ifm-table-stripe-background);
-}
-
 .choice-row:hover {
   background-color: var(--ifm-hover-overlay);
 }

package/components/SchemaRows.js

@@ -12,7 +12,11 @@ import ConditionalRows from './ConditionalRows';
  * @param {Array} props.tableData - Flat array of row objects
  * @param {Array} [props.bracketEnds] - Bracket descriptors that end on the last row
  */
-export default function SchemaRows({ tableData, bracketEnds }) {
+export default function SchemaRows({
+  tableData,
+  bracketEnds,
+  stripeState = { current: 0 },
+}) {
   if (!tableData) {
     return null;
   }
@@ -20,12 +24,15 @@ export default function SchemaRows({ tableData, bracketEnds }) {
   return tableData.map((row, index) => {
     const key = row.path.join('.');
     const isLast = index === tableData.length - 1;
+    const stripeIndex = stripeState.current++;
 
     if (row.type === 'choice') {
       return (
         <FoldableRows
           key={key}
           row={row}
+          stripeIndex={stripeIndex}
+          stripeState={stripeState}
           bracketEnds={isLast ? bracketEnds : undefined}
         />
       );
@@ -36,6 +43,8 @@ export default function SchemaRows({ tableData, bracketEnds }) {
         <ConditionalRows
           key={key}
           row={row}
+          stripeIndex={stripeIndex}
+          stripeState={stripeState}
           bracketEnds={isLast ? bracketEnds : undefined}
         />
       );
@@ -46,6 +55,7 @@ export default function SchemaRows({ tableData, bracketEnds }) {
         <PropertyRow
           key={key}
           row={row}
+          stripeIndex={stripeIndex}
           isLastInGroup={row.isLastInGroup}
           bracketEnds={isLast ? bracketEnds : undefined}
         />

package/generateEventDocs.js

@@ -1,7 +1,12 @@
 import path from 'path';
 import fs from 'fs';
 import { getPathsForVersion } from './helpers/path-helpers.js';
-import { readSchemas, writeDoc, createDir } from './helpers/file-system.js';
+import {
+  readSchemas,
+  readSchemaSources,
+  writeDoc,
+  createDir,
+} from './helpers/file-system.js';
 import { processOneOfSchema, slugify } from './helpers/schema-processing.js';
 import SchemaDocTemplate from './helpers/schema-doc-template.js';
 import ChoiceIndexTemplate from './helpers/choice-index-template.js';
@@ -37,6 +42,64 @@ function resolvePartial({
   };
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function toSchemaSourceKey(schemaDir, filePath) {
+  return path.relative(schemaDir, filePath).split(path.sep).join('/');
+}
+
+function resolveLocalSchemaRef(currentPath, ref) {
+  if (!ref || ref.startsWith('#') || /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(ref)) {
+    return null;
+  }
+
+  const [fileRef] = ref.split('#');
+  return path
+    .normalize(path.join(path.dirname(currentPath), fileRef))
+    .split(path.sep)
+    .join('/');
+}
+
+function collectReachableSchemaSources(sourcePath, allSchemaSources) {
+  if (!sourcePath || !allSchemaSources[sourcePath]) return {};
+
+  const visited = new Set();
+  const reachableSources = {};
+
+  function walkSchema(currentPath) {
+    if (visited.has(currentPath) || !allSchemaSources[currentPath]) return;
+    visited.add(currentPath);
+
+    const schema = allSchemaSources[currentPath];
+    reachableSources[currentPath] = schema;
+
+    function walkNode(node) {
+      if (Array.isArray(node)) {
+        node.forEach(walkNode);
+        return;
+      }
+
+      if (!isPlainObject(node)) return;
+
+      if (typeof node.$ref === 'string') {
+        const resolvedRefPath = resolveLocalSchemaRef(currentPath, node.$ref);
+        if (resolvedRefPath) {
+          walkSchema(resolvedRefPath);
+        }
+      }
+
+      Object.values(node).forEach(walkNode);
+    }
+
+    walkNode(schema);
+  }
+
+  walkSchema(sourcePath);
+  return reachableSources;
+}
+
 async function collectLeafEventNames(schema, filePath, eventNames) {
   if (!schema.oneOf) {
     eventNames.push(path.basename(filePath, '.json'));
@@ -86,6 +149,8 @@ async function generateAndWriteDoc(
   alreadyMergedSchema = null,
   editFilePath = null,
   partialNameConflicts = new Set(),
+  schemaSources = {},
+  schemaDir,
 ) {
   const { organizationName, projectName, siteDir, dataLayerName, version } =
     options;
@@ -134,6 +199,11 @@ async function generateAndWriteDoc(
     topPartialComponent: top.component,
     bottomPartialComponent: bottom.component,
     dataLayerName,
+    sourcePath: toSchemaSourceKey(schemaDir, editFilePath || filePath),
+    schemaSources: collectReachableSchemaSources(
+      toSchemaSourceKey(schemaDir, editFilePath || filePath),
+      schemaSources,
+    ),
   });
 
   const outputFilename = path.basename(filePath).replace('.json', '.mdx');
@@ -147,6 +217,8 @@ async function generateOneOfDocs(
   outputDir,
   options,
   partialNameConflicts,
+  schemaSources,
+  schemaDir,
 ) {
   const { organizationName, projectName, siteDir } = options;
   const editUrl = buildEditUrl(
@@ -165,6 +237,11 @@ async function generateOneOfDocs(
     schema,
     processedOptions: processed,
     editUrl,
+    sourcePath: toSchemaSourceKey(schemaDir, filePath),
+    schemaSources: collectReachableSchemaSources(
+      toSchemaSourceKey(schemaDir, filePath),
+      schemaSources,
+    ),
   });
   writeDoc(eventOutputDir, 'index.mdx', indexPageContent);
 
@@ -183,6 +260,8 @@ async function generateOneOfDocs(
         eventOutputDir,
         options,
         partialNameConflicts,
+        schemaSources,
+        schemaDir,
       );
     } else {
       await generateAndWriteDoc(
@@ -194,6 +273,8 @@ async function generateOneOfDocs(
         processedSchema,
         sourceFilePath || filePath,
         partialNameConflicts,
+        schemaSources,
+        schemaDir,
       );
     }
   }
@@ -205,6 +286,7 @@ export default async function generateEventDocs(options) {
 
   createDir(outputDir);
   const schemas = readSchemas(schemaDir);
+  const schemaSources = readSchemaSources(schemaDir);
   const partialNameConflicts = await getPartialNameConflicts(schemas);
 
   console.log(`🚀 Generating documentation for ${schemas.length} schemas...`);
@@ -229,6 +311,8 @@ export default async function generateEventDocs(options) {
         outputDir,
         options,
         partialNameConflicts,
+        schemaSources,
+        schemaDir,
       );
     } else {
       await generateAndWriteDoc(
@@ -240,6 +324,8 @@ export default async function generateEventDocs(options) {
         null,
         null,
         partialNameConflicts,
+        schemaSources,
+        schemaDir,
       );
     }
   }

package/helpers/choice-index-template.js

@@ -1,5 +1,5 @@
 export default function ChoiceIndexTemplate(data) {
-  const { schema, processedOptions, editUrl } = data;
+  const { schema, processedOptions, editUrl, sourcePath, schemaSources } = data;
 
   return `---
 title: ${schema.title}
@@ -18,6 +18,10 @@ ${processedOptions
   .map((option) => `- [${option.schema.title}](./${option.slug})`)
   .join('\n')}
 
-<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
+<SchemaJsonViewer
+  schema={${JSON.stringify(schema)}}
+  sourcePath={${JSON.stringify(sourcePath)}}
+  schemaSources={${JSON.stringify(schemaSources)}}
+/>
 `;
 }

package/helpers/file-system.js

@@ -23,6 +23,34 @@ export function readSchemas(directory) {
   });
 }
 
+export function readSchemaSources(directory) {
+  const schemaSources = {};
+
+  function walk(currentDirectory) {
+    const entries = fs.readdirSync(currentDirectory, { withFileTypes: true });
+
+    entries.forEach((entry) => {
+      const entryPath = path.join(currentDirectory, entry.name);
+      if (entry.isDirectory()) {
+        walk(entryPath);
+        return;
+      }
+
+      if (!entry.name.endsWith('.json')) return;
+      const relativePath = path
+        .relative(directory, entryPath)
+        .split(path.sep)
+        .join('/');
+      schemaSources[relativePath] = JSON.parse(
+        fs.readFileSync(entryPath, 'utf-8'),
+      );
+    });
+  }
+
+  walk(directory);
+  return schemaSources;
+}
+
 export function writeDoc(outputDir, fileName, content) {
   fs.writeFileSync(path.join(outputDir, fileName), content);
   console.log(

package/helpers/schema-doc-template.js

@@ -9,6 +9,8 @@ export default function MdxTemplate(data) {
     topPartialComponent,
     bottomPartialComponent,
     dataLayerName,
+    sourcePath,
+    schemaSources,
   } = data;
 
   return `---
@@ -33,7 +35,11 @@ ${topPartialComponent}
   schema={${JSON.stringify(mergedSchema)}}
   ${dataLayerName ? ` dataLayerName={'${dataLayerName}'}` : ''}
 />
-<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
+<SchemaJsonViewer
+  schema={${JSON.stringify(schema)}}
+  sourcePath={${JSON.stringify(sourcePath)}}
+  schemaSources={${JSON.stringify(schemaSources)}}
+/>
 
 ${bottomPartialComponent}
 `;