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

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,49 @@
   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;
+}
+
+.schema-json-viewer__ref-link {
+  text-decoration: underline;
+  text-decoration-thickness: 1.5px;
+  text-underline-offset: 0.14em;
+}
+
+.schema-json-viewer__ref-link:hover {
+  color: var(--ifm-link-hover-color) !important;
+  text-decoration-thickness: 2px;
+}
+
+.schema-json-viewer__keyword {
+  font-weight: 600;
+}
+
+.schema-json-viewer__keyword--meta {
+  color: var(--ifm-color-info-light);
+}
+
+.schema-json-viewer__keyword--structural {
+  color: var(--ifm-color-success-light);
+}
+
 /* --- Property Name and Container Symbol Styles --- */
 
 .property-name {
@@ -34,6 +77,78 @@
   gap: 4px;
 }
 
+.property-name--keyword {
+  align-items: center;
+}
+
+.property-keyword-wrapper {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+}
+
+.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-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.1rem 0.4rem;
+  border-radius: 999px;
+  border: 1px solid var(--ifm-table-border-color);
+  background-color: var(--ifm-color-emphasis-100);
+  color: var(--ifm-color-emphasis-800);
+  font-size: 0.68rem;
+  font-weight: 700;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
+.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 +182,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 +204,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 +239,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 +263,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 +307,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/components/SchemaViewer.js

@@ -3,7 +3,16 @@ import Heading from '@theme/Heading';
 import ExampleDataLayer from './ExampleDataLayer';
 import PropertiesTable from './PropertiesTable';
 
-export default function SchemaViewer({ schema, dataLayerName }) {
+export default function SchemaViewer({
+  schema,
+  sourceSchema,
+  sourcePath,
+  schemaSources,
+  dataLayerName,
+}) {
+  const resolvedSourceSchema =
+    (sourcePath && schemaSources?.[sourcePath]) || sourceSchema || schema;
+
   const hasOneOfAnyOf =
     schema.oneOf ||
     schema.anyOf ||
@@ -21,7 +30,7 @@ export default function SchemaViewer({ schema, dataLayerName }) {
       <ExampleDataLayer schema={schema} dataLayerName={dataLayerName} />
 
       <Heading as="h2">Event Properties</Heading>
-      <PropertiesTable schema={schema} />
+      <PropertiesTable schema={schema} sourceSchema={resolvedSourceSchema} />
     </div>
   );
 }

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/example-helper.js

@@ -5,7 +5,7 @@ export function getSingleExampleValue(propSchema) {
   if (propSchema.examples?.length > 0) {
     return propSchema.examples[0];
   }
-  if (propSchema.example) {
+  if (Object.prototype.hasOwnProperty.call(propSchema, 'example')) {
     return propSchema.example;
   }
   if (Object.prototype.hasOwnProperty.call(propSchema, 'default')) {
@@ -25,7 +25,7 @@ export function getExamples(propSchema) {
     examples.push(...propSchema.examples);
   }
 
-  if (propSchema.example) {
+  if (Object.prototype.hasOwnProperty.call(propSchema, 'example')) {
     if (!examples.includes(propSchema.example)) {
       examples.push(propSchema.example);
     }

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/getConstraints.js

@@ -1,4 +1,23 @@
 // A list of JSON Schema keywords that have simple key-value constraints.
+function formatInlineConstraintValue(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => formatInlineConstraintValue(item)).join(', ')}]`;
+  }
+
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).map(
+      ([key, nested]) => `${key}: ${formatInlineConstraintValue(nested)}`,
+    );
+    return `{ ${entries.join(', ')} }`;
+  }
+
+  return JSON.stringify(value);
+}
+
+function formatNotConstraint(val) {
+  return `not: ${formatInlineConstraintValue(val)}`;
+}
+
 const constraintHandlers = {
   // Simple key-value constraints
   minLength: (val) => `minLength: ${val}`,
@@ -32,6 +51,7 @@ const constraintHandlers = {
   contains: (val) => `contains: ${JSON.stringify(val)}`,
   enum: (val) => `enum: [${val.join(', ')}]`,
   const: (val) => `const: ${JSON.stringify(val)}`,
+  not: (val) => formatNotConstraint(val),
 };
 
 export const getConstraints = (prop, isReq) => {

package/helpers/processSchema.js

@@ -3,6 +3,37 @@ import fs from 'fs';
 import { resolveConstraintSchemaPath } from './constraintSchemaPaths.js';
 import { mergeSchema } from './mergeSchema.js';
 
+function unwrapRedundantNotAnyOf(node) {
+  if (!node || typeof node !== 'object') {
+    return node;
+  }
+
+  if (Array.isArray(node)) {
+    return node.map(unwrapRedundantNotAnyOf);
+  }
+
+  const normalized = {};
+  for (const [key, value] of Object.entries(node)) {
+    normalized[key] = unwrapRedundantNotAnyOf(value);
+  }
+
+  if (normalized.not && typeof normalized.not === 'object') {
+    let candidate = normalized.not;
+    while (
+      candidate &&
+      typeof candidate === 'object' &&
+      !Array.isArray(candidate) &&
+      Array.isArray(candidate.anyOf) &&
+      candidate.anyOf.length === 1
+    ) {
+      candidate = candidate.anyOf[0];
+    }
+    normalized.not = candidate;
+  }
+
+  return normalized;
+}
+
 /**
  * Processes a JSON schema file by bundling external references,
  * dereferencing internal references, and merging allOf properties.
@@ -41,5 +72,5 @@ export default async function processSchema(filePath) {
   // Then merge allOf properties
   const mergedSchema = mergeSchema(dereferencedSchema);
 
-  return mergedSchema;
+  return unwrapRedundantNotAnyOf(mergedSchema);
 }

package/helpers/schema-doc-template.js

@@ -9,7 +9,10 @@ export default function MdxTemplate(data) {
     topPartialComponent,
     bottomPartialComponent,
     dataLayerName,
+    sourcePath,
+    schemaSources,
   } = data;
+  const sourceSchema = schemaSources?.[sourcePath] || schema;
 
   return `---
 title: ${schema.title}
@@ -31,9 +34,16 @@ ${topPartialComponent}
 
 <SchemaViewer
   schema={${JSON.stringify(mergedSchema)}}
+  sourceSchema={${JSON.stringify(sourceSchema)}}
+  sourcePath={${JSON.stringify(sourcePath)}}
+  schemaSources={${JSON.stringify(schemaSources)}}
   ${dataLayerName ? ` dataLayerName={'${dataLayerName}'}` : ''}
 />
-<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
+<SchemaJsonViewer
+  schema={${JSON.stringify(schema)}}
+  sourcePath={${JSON.stringify(sourcePath)}}
+  schemaSources={${JSON.stringify(schemaSources)}}
+/>
 
 ${bottomPartialComponent}
 `;

package/helpers/schemaToExamples.js

@@ -1,44 +1,31 @@
 import buildExampleFromSchema from './buildExampleFromSchema';
 import { mergeSchema } from './mergeSchema.js';
+import traversalHelpers from './schemaTraversal.cjs';
 
-const findChoicePoints = (subSchema, path = []) => {
-  if (!subSchema) {
-    return [];
-  }
+const { visitSchemaNodes } = traversalHelpers;
 
-  const choiceType = subSchema.oneOf
-    ? 'oneOf'
-    : subSchema.anyOf
-      ? 'anyOf'
-      : null;
-  const currentChoice = choiceType ? [{ path, schema: subSchema }] : [];
+const findChoicePoints = (schema) => {
+  const choicePoints = [];
 
-  const nestedChoices = subSchema.properties
-    ? Object.entries(subSchema.properties).flatMap(([key, propSchema]) =>
-        findChoicePoints(propSchema, [...path, 'properties', key]),
-      )
-    : [];
+  visitSchemaNodes(schema, (subSchema, context) => {
+    if (subSchema.oneOf || subSchema.anyOf) {
+      choicePoints.push({ path: context.path, schema: subSchema });
+    }
+  });
 
-  return [...currentChoice, ...nestedChoices];
+  return choicePoints;
 };
 
-const findConditionalPoints = (subSchema, path = []) => {
-  if (!subSchema) {
-    return [];
-  }
-
-  const currentConditional =
-    subSchema.if && (subSchema.then || subSchema.else)
-      ? [{ path, schema: subSchema }]
-      : [];
+const findConditionalPoints = (schema) => {
+  const conditionalPoints = [];
 
-  const nestedConditionals = subSchema.properties
-    ? Object.entries(subSchema.properties).flatMap(([key, propSchema]) =>
-        findConditionalPoints(propSchema, [...path, 'properties', key]),
-      )
-    : [];
+  visitSchemaNodes(schema, (subSchema, context) => {
+    if (subSchema.if && (subSchema.then || subSchema.else)) {
+      conditionalPoints.push({ path: context.path, schema: subSchema });
+    }
+  });
 
-  return [...currentConditional, ...nestedConditionals];
+  return conditionalPoints;
 };
 
 const generateExampleForChoice = (rootSchema, path, option) => {
@@ -151,10 +138,17 @@ export function schemaToExamples(rootSchema) {
 
   if (choicePoints.length === 0 && conditionalPoints.length === 0) {
     const example = buildExampleFromSchema(rootSchema);
-    if (example && Object.keys(example).length > 0) {
-      return [
-        { property: 'default', options: [{ title: 'Example', example }] },
-      ];
+    if (typeof example !== 'undefined') {
+      const shouldIncludeObjectExample =
+        typeof example !== 'object' ||
+        example === null ||
+        Object.keys(example).length > 0;
+
+      if (shouldIncludeObjectExample) {
+        return [
+          { property: 'default', options: [{ title: 'Example', example }] },
+        ];
+      }
     }
     return [];
   }