docusaurus-plugin-generate-schema-docs 1.3.0 → 1.5.0

package/components/PropertyRow.js

@@ -3,25 +3,15 @@ import clsx from 'clsx';
 import CodeBlock from '@theme/CodeBlock';
 
 /**
- * Formats an example value into a string for display in a CodeBlock.
- * - Objects are stringified with indentation.
- * - Arrays are joined by newlines.
- * @param {any} example The example to format.
- * @returns {string}
+ * Formats a single example value into a string for display in a CodeBlock.
+ * @param {any} singleEx The example to format.
+ * @returns {string|null}
  */
-const formatExample = (example) => {
-  if (typeof example === 'undefined' || example === null) return '';
-  if (Array.isArray(example)) {
-    return example
-      .map((ex) =>
-        typeof ex === 'object' ? JSON.stringify(ex, null, 2) : String(ex),
-      )
-      .join('\n');
-  }
-  if (typeof example === 'object') {
-    return JSON.stringify(example, null, 2);
-  }
-  return String(example);
+const formatExample = (singleEx) => {
+  if (typeof singleEx === 'undefined' || singleEx === null) return null;
+  if (typeof singleEx === 'object') return JSON.stringify(singleEx, null, 2);
+  if (typeof singleEx === 'string') return JSON.stringify(singleEx);
+  return String(singleEx);
 };
 
 /**
@@ -47,7 +37,7 @@ export default function PropertyRow({ row, isLastInGroup }) {
     required,
     propertyType,
     description,
-    example,
+    examples,
     constraints,
     hasChildren,
     containerType,
@@ -65,7 +55,6 @@ export default function PropertyRow({ row, isLastInGroup }) {
   const [firstConstraint, ...remainingConstraints] = hasConstraints
     ? constraints
     : [null];
-  const formattedExample = formatExample(example);
 
   // Generate background gradients for:
   // 1. Parent-to-child line (from 50% down) - for elements with children
@@ -154,11 +143,21 @@ export default function PropertyRow({ row, isLastInGroup }) {
         </td>
 
         <td rowSpan={rowSpan}>
-          {formattedExample && (
-            <CodeBlock language="json" className="schema-examples">
-              {formattedExample}
-            </CodeBlock>
-          )}
+          {examples &&
+            examples.map((ex, i) => {
+              const formatted = formatExample(ex);
+              return (
+                formatted && (
+                  <CodeBlock
+                    key={i}
+                    language="json"
+                    className="schema-examples"
+                  >
+                    {formatted}
+                  </CodeBlock>
+                )
+              );
+            })}
         </td>
         <td rowSpan={rowSpan}>{description || ''}</td>
       </tr>

package/components/SchemaRows.css

@@ -248,3 +248,9 @@ td.level-6::after {
 .schema-examples button {
   display: none;
 }
+
+/* Force long unbreakable words to wrap in examples */
+.schema-examples pre {
+  white-space: pre-wrap;
+  overflow-wrap: break-word;
+}

package/components/SchemaViewer.js

@@ -3,7 +3,7 @@ import Heading from '@theme/Heading';
 import ExampleDataLayer from './ExampleDataLayer';
 import PropertiesTable from './PropertiesTable';
 
-export default function SchemaViewer({ schema }) {
+export default function SchemaViewer({ schema, dataLayerName }) {
   const hasOneOfAnyOf =
     schema.oneOf ||
     schema.anyOf ||
@@ -18,7 +18,7 @@ export default function SchemaViewer({ schema }) {
   return (
     <div>
       <Heading as="h2">{exampleTitle}</Heading>
-      <ExampleDataLayer schema={schema} />
+      <ExampleDataLayer schema={schema} dataLayerName={dataLayerName} />
 
       <Heading as="h2">Event Properties</Heading>
       <PropertiesTable schema={schema} />

package/components/WordWrapButton.js

@@ -0,0 +1,31 @@
+import React from 'react';
+import clsx from 'clsx';
+import styles from './wordWrapButton.module.css';
+
+export default function WordWrapButton({ className, onClick, isEnabled }) {
+  const title = 'Toggle word wrap';
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={clsx(
+        'clean-btn',
+        className,
+        isEnabled && styles.wordWrapButtonEnabled,
+      )}
+      aria-label={title}
+      title={title}
+    >
+      <svg
+        className={styles.wordWrapButtonIcon}
+        viewBox="0 0 24 24"
+        aria-hidden="true"
+      >
+        <path
+          fill="currentColor"
+          d="M4 19h6v-2H4v2zM20 5H4v2h16V5zm-3 6H4v2h13.25c1.1 0 2 .9 2 2s-.9 2-2 2H15v-2l-3 3l3 3v-2h2c2.21 0 4-1.79 4-4s-1.79-4-4-4z"
+        />
+      </svg>
+    </button>
+  );
+}

package/components/wordWrapButton.module.css

@@ -0,0 +1,8 @@
+.wordWrapButtonIcon {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+.wordWrapButtonEnabled {
+  color: var(--ifm-color-primary);
+}

package/generateEventDocs.js

@@ -15,7 +15,7 @@ async function generateAndWriteDoc(
   options,
   alreadyMergedSchema = null,
 ) {
-  const { organizationName, projectName, siteDir } = options;
+  const { organizationName, projectName, siteDir, dataLayerName } = options;
   const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
   const PARTIALS_DIR = path.join(siteDir, 'docs/partials');
 
@@ -53,6 +53,7 @@ async function generateAndWriteDoc(
     bottomPartialImport,
     topPartialComponent,
     bottomPartialComponent,
+    dataLayerName,
   });
 
   const outputFilename = path.basename(filePath).replace('.json', '.mdx');

package/helpers/buildExampleFromSchema.js

@@ -1,69 +1,66 @@
-/**
- * Recursively builds a single, default example object from a JSON schema.
- * It prefers explicit examples, consts, or defaults. For choices (`oneOf`/`anyOf`),
- * it defaults to the first option.
- *
- * @param {object} schema The schema to build an example from.
- * @returns {object|undefined} The generated example.
- */
-const buildExampleFromSchema = (schema) => {
-  if (!schema) return undefined;
+import { getSingleExampleValue } from './example-helper';
+import mergeJsonSchema from 'json-schema-merge-allof';
 
-  // For choices, default to the first option.
-  if (schema.oneOf?.length > 0) {
-    return buildExampleFromSchema(schema.oneOf[0]);
+const getPrimitivePlaceholder = (type) => {
+  switch (type) {
+    case 'string':
+      return '';
+    case 'integer':
+    case 'number':
+      return 0;
+    case 'boolean':
+      return false;
+    default:
+      return undefined;
   }
-  if (schema.anyOf?.length > 0) {
-    return buildExampleFromSchema(schema.anyOf[0]);
+};
+
+const buildExampleFromSchema = (schema) => {
+  if (!schema) {
+    return undefined;
   }
 
-  // Prefer const, explicit examples, or default values.
-  if (typeof schema.const !== 'undefined') return schema.const;
-  if (schema.examples?.length > 0) return schema.examples[0];
-  if (typeof schema.default !== 'undefined') return schema.default;
+  // For choices, default to the first option and recurse.
+  const choiceType = schema.oneOf ? 'oneOf' : schema.anyOf ? 'anyOf' : null;
+  if (choiceType && schema[choiceType]?.length > 0) {
+    const newSchema = { ...schema };
+    const choice = newSchema[choiceType][0];
+    delete newSchema[choiceType];
+    const merged = mergeJsonSchema({ allOf: [newSchema, choice] });
+    return buildExampleFromSchema(merged);
+  }
 
-  let type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
-  if (!type && schema.properties) {
-    type = 'object';
+  // If there's an explicit example, use it.
+  const exampleValue = getSingleExampleValue(schema);
+  if (typeof exampleValue !== 'undefined') {
+    return exampleValue;
   }
 
-  if (type === 'object') {
-    if (schema.properties) {
-      const obj = {};
-      Object.entries(schema.properties).forEach(([key, propSchema]) => {
+  // Determine the type, defaulting to 'object' if properties are present.
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  const inferredType = !type && schema.properties ? 'object' : type;
+
+  // Build examples based on type.
+  if (inferredType === 'object' && schema.properties) {
+    const obj = Object.entries(schema.properties).reduce(
+      (acc, [key, propSchema]) => {
         const value = buildExampleFromSchema(propSchema);
         if (typeof value !== 'undefined') {
-          obj[key] = value;
+          acc[key] = value;
         }
-      });
-      // Return undefined for objects that end up empty.
-      return Object.keys(obj).length > 0 ? obj : undefined;
-    }
-    // No properties defined, treat as an empty object (which we filter out).
-    return undefined;
+        return acc;
+      },
+      {},
+    );
+    return Object.keys(obj).length > 0 ? obj : undefined;
   }
 
-  if (type === 'array') {
-    if (schema.items) {
-      const itemValue = buildExampleFromSchema(schema.items);
-      // Only return an array if the item schema generates a value.
-      return typeof itemValue !== 'undefined' ? [itemValue] : undefined;
-    }
-    return undefined; // No items defined.
+  if (inferredType === 'array' && schema.items) {
+    const itemValue = buildExampleFromSchema(schema.items);
+    return typeof itemValue !== 'undefined' ? [itemValue] : undefined;
   }
 
-  // Return placeholder values for primitive types if no other value is found.
-  switch (type) {
-    case 'string':
-      return '';
-    case 'integer':
-    case 'number':
-      return 0;
-    case 'boolean':
-      return false;
-    default:
-      return undefined;
-  }
+  return getPrimitivePlaceholder(inferredType);
 };
 
 export default buildExampleFromSchema;

package/helpers/example-helper.js

@@ -0,0 +1,41 @@
+export function getSingleExampleValue(propSchema) {
+  if (Object.prototype.hasOwnProperty.call(propSchema, 'const')) {
+    return propSchema.const;
+  }
+  if (propSchema.examples?.length > 0) {
+    return propSchema.examples[0];
+  }
+  if (propSchema.example) {
+    return propSchema.example;
+  }
+  if (Object.prototype.hasOwnProperty.call(propSchema, 'default')) {
+    return propSchema.default;
+  }
+  return undefined;
+}
+
+export function getExamples(propSchema) {
+  if (Object.prototype.hasOwnProperty.call(propSchema, 'const')) {
+    return [propSchema.const];
+  }
+
+  const examples = [];
+
+  if (propSchema.examples) {
+    examples.push(...propSchema.examples);
+  }
+
+  if (propSchema.example) {
+    if (!examples.includes(propSchema.example)) {
+      examples.push(propSchema.example);
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(propSchema, 'default')) {
+    if (!examples.includes(propSchema.default)) {
+      examples.push(propSchema.default);
+    }
+  }
+
+  return examples.length > 0 ? examples : undefined;
+}

package/helpers/file-system.js

@@ -1,6 +1,5 @@
 import fs from 'fs';
 import path from 'path';
-import loadSchema from './loadSchema';
 
 export function createDir(directory) {
   if (!fs.existsSync(directory)) {
@@ -15,7 +14,7 @@ export function readSchemas(directory) {
 
   return files.map((file) => {
     const filePath = path.join(directory, file);
-    const schema = loadSchema(filePath);
+    const schema = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
     return {
       fileName: file,
       filePath,

package/helpers/getConstraints.js

@@ -15,6 +15,7 @@ const constraintHandlers = {
   format: (val) => `format: ${val}`,
   minContains: (val) => `minContains: ${val}`,
   maxContains: (val) => `maxContains: ${val}`,
+  default: (val) => `default: ${JSON.stringify(val)}`,
 
   // Special-cased constraints
   pattern: (val) => `pattern: /${val}/`,

package/helpers/schema-doc-template.js

@@ -28,7 +28,14 @@ ${schema.description}
 
 ${topPartialComponent}
 
-<SchemaViewer schema={${JSON.stringify(mergedSchema)}} />
+<SchemaViewer
+  schema={${JSON.stringify(mergedSchema)}}
+  ${
+    data.dataLayerName && data.dataLayerName !== 'undefined'
+      ? ` dataLayerName={'${data.dataLayerName}'}`
+      : ''
+  }
+/>
 <SchemaJsonViewer schema={${JSON.stringify(schema)}} />
 
 ${bottomPartialComponent}

package/helpers/schema-processing.js

@@ -15,21 +15,6 @@ export function slugify(text) {
     .replace(/-+$/, ''); // Trim - from end of text
 }
 
-export function fixRefs(obj, basePath) {
-  for (const key in obj) {
-    if (
-      key === '$ref' &&
-      typeof obj[key] === 'string' &&
-      !obj[key].startsWith('#') &&
-      !obj[key].startsWith('http')
-    ) {
-      obj[key] = path.resolve(basePath, obj[key]);
-    } else if (typeof obj[key] === 'object' && obj[key] !== null) {
-      fixRefs(obj[key], basePath);
-    }
-  }
-}
-
 export async function processOneOfSchema(schema, filePath) {
   const processedSchemas = [];
   const choiceType = schema.oneOf ? 'oneOf' : null;
@@ -56,6 +41,8 @@ export async function processOneOfSchema(schema, filePath) {
       const hadId = resolvedOption.$id && resolvedOption.$id.endsWith('.json');
       if (hadId) {
         slug = path.basename(resolvedOption.$id, '.json');
+      } else if (resolvedOption.$anchor) {
+        slug = resolvedOption.$anchor;
       } else {
         slug = slugify(newSchema.title);
       }

package/helpers/schemaToExamples.js

@@ -1,99 +1,71 @@
 import buildExampleFromSchema from './buildExampleFromSchema';
+import mergeJsonSchema from 'json-schema-merge-allof';
 
-/**
- * This is the main helper that generates a list of complete example objects,
- * grouped by the property that contains the choice.
- *
- * @param {object} rootSchema The complete schema for the event.
- * @returns {object[]} An array of group objects.
- */
-export function schemaToExamples(rootSchema) {
-  const choicePoints = [];
+const findChoicePoints = (subSchema, path = []) => {
+  if (!subSchema) {
+    return [];
+  }
 
-  // 1. Find all choice points in the schema recursively
-  function findChoices(subSchema, path = []) {
-    if (!subSchema) return;
+  const choiceType = subSchema.oneOf
+    ? 'oneOf'
+    : subSchema.anyOf
+      ? 'anyOf'
+      : null;
+  const currentChoice = choiceType ? [{ path, schema: subSchema }] : [];
 
-    // First, check for choices at the current schema level
-    const choiceType = subSchema.oneOf
-      ? 'oneOf'
-      : subSchema.anyOf
-        ? 'anyOf'
-        : null;
-    if (choiceType) {
-      choicePoints.push({ path, schema: subSchema });
-    }
+  const nestedChoices = subSchema.properties
+    ? Object.entries(subSchema.properties).flatMap(([key, propSchema]) =>
+        findChoicePoints(propSchema, [...path, 'properties', key]),
+      )
+    : [];
+
+  return [...currentChoice, ...nestedChoices];
+};
+
+const generateExampleForChoice = (rootSchema, path, option) => {
+  const schemaVariant = JSON.parse(JSON.stringify(rootSchema));
 
-    // Then, recurse into any nested properties
-    if (subSchema.properties) {
-      for (const [key, propSchema] of Object.entries(subSchema.properties)) {
-        findChoices(propSchema, [...path, 'properties', key]);
-      }
+  if (path.length === 0) {
+    delete schemaVariant.oneOf;
+    delete schemaVariant.anyOf;
+    const newSchemaVariant = mergeJsonSchema({
+      allOf: [schemaVariant, option],
+    });
+    return buildExampleFromSchema(newSchemaVariant);
+  } else {
+    let parentOfChoice = schemaVariant;
+    for (let i = 0; i < path.length; i++) {
+      parentOfChoice = parentOfChoice[path[i]];
     }
+    delete parentOfChoice.oneOf;
+    delete parentOfChoice.anyOf;
+    Object.assign(parentOfChoice, option);
+    return buildExampleFromSchema(schemaVariant);
   }
+};
 
-  findChoices(rootSchema);
+export function schemaToExamples(rootSchema) {
+  const choicePoints = findChoicePoints(rootSchema);
 
-  // 2. If no choices are found, generate a single default example
   if (choicePoints.length === 0) {
     const example = buildExampleFromSchema(rootSchema);
     if (example && Object.keys(example).length > 0) {
-      // Return in the same group structure for consistency
       return [
-        {
-          property: 'default',
-          options: [{ title: 'Example', example }],
-        },
+        { property: 'default', options: [{ title: 'Example', example }] },
       ];
     }
     return [];
   }
 
-  // 3. Map each found choice point to a "group" of examples
   return choicePoints.map(({ path, schema }) => {
     const choiceType = schema.oneOf ? 'oneOf' : 'anyOf';
-    const choices = schema[choiceType];
     const propertyName = path.length > 0 ? path[path.length - 1] : 'root';
 
-    // For each option within the choice, generate a complete example
-    const options = choices.map((option) => {
-      // Create a deep copy of the root schema to modify for this specific example
-      const schemaVariant = JSON.parse(JSON.stringify(rootSchema));
-
-      // If path is empty, the choice is at the root of the schema.
-      if (path.length === 0) {
-        // Merge the chosen option's properties into the root properties
-        schemaVariant.properties = {
-          ...schemaVariant.properties,
-          ...option.properties,
-        };
-        // Remove the choice block from the root
-        delete schemaVariant.oneOf;
-        delete schemaVariant.anyOf;
-      } else {
-        // The choice is nested. Find the parent of the choice block in the copied schema.
-        let parentOfChoice = schemaVariant;
-        for (let i = 0; i < path.length; i++) {
-          parentOfChoice = parentOfChoice[path[i]];
-        }
-
-        // Delete the choice keywords and merge the selected option.
-        // This preserves other properties on the parent (like `type` and `description`).
-        delete parentOfChoice.oneOf;
-        delete parentOfChoice.anyOf;
-        Object.assign(parentOfChoice, option);
-      }
-
-      const example = buildExampleFromSchema(schemaVariant);
-      return {
-        title: option.title || 'Option',
-        example,
-      };
-    });
+    const options = schema[choiceType].map((option) => ({
+      title: option.title || 'Option',
+      example: generateExampleForChoice(rootSchema, path, option),
+    }));
 
-    return {
-      property: propertyName,
-      options,
-    };
+    return { property: propertyName, options };
   });
 }

package/helpers/schemaToTableData.js

@@ -1,4 +1,5 @@
 import { getConstraints } from './getConstraints';
+import { getExamples } from './example-helper';
 
 function processOptions(
   choices,
@@ -36,7 +37,7 @@ function processOptions(
         required: isRequired,
         propertyType: optionSchema.type,
         description: optionSchema.description,
-        example: optionSchema.examples || optionSchema.example,
+        examples: getExamples(optionSchema),
         constraints: constraints,
         isLastInGroup: isLastOption, // Updated: Uses the calculated flag instead of always true
         hasChildren: false,
@@ -201,7 +202,7 @@ export function schemaToTableData(
             propertyType:
               propSchema.type || (propSchema.enum ? 'enum' : 'object'),
             description: propSchema.description,
-            example: propSchema.examples || propSchema.example,
+            examples: getExamples(propSchema),
             constraints,
             isLastInGroup: isLast,
             hasChildren,
@@ -296,7 +297,7 @@ export function schemaToTableData(
         required: false,
         propertyType: subSchema.type,
         description: subSchema.description,
-        example: subSchema.examples || subSchema.example,
+        examples: getExamples(subSchema),
         constraints: getConstraints(subSchema),
         isLastInGroup: true,
         hasChildren: false,