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

package/components/SchemaRows.js

@@ -1,75 +1,30 @@
 import React from 'react';
+import './SchemaRows.css';
+import PropertyRow from './PropertyRow';
+import FoldableRows from './FoldableRows';
 
-const SchemaRows = ({ properties, requiredList = [], level = 0 }) => {
-    return (
-        <>
-            {Object.entries(properties).map(([key, prop]) => {
-                const isReq = requiredList.includes(key);
+/**
+ * Renders the rows of the schema table from a flat `tableData` array.
+ * It maps over the array and renders the appropriate component for each row.
+ */
+export default function SchemaRows({ tableData }) {
+  if (!tableData) {
+    return null;
+  }
 
-                // 1. Calculate if it has children (Same as before)
-                const hasChildren =
-                    (prop.type === 'object' &&
-                        prop.properties &&
-                        Object.keys(prop.properties).length > 0) ||
-                    (prop.type === 'array' &&
-                        prop.items &&
-                        prop.items.properties &&
-                        Object.keys(prop.items.properties).length > 0);
+  return tableData.map((row) => {
+    const key = row.path.join('.');
 
-                const isObject = prop.type === 'object';
-                const isArrayOfObjects = prop.type === 'array' && prop.items && prop.items.type === 'object';
+    if (row.type === 'choice') {
+      return <FoldableRows key={key} row={row} />;
+    }
 
-                if ((isObject || isArrayOfObjects) && !hasChildren)
-                {
-                    return null;
-                }
+    if (row.type === 'property') {
+      return (
+        <PropertyRow key={key} row={row} isLastInGroup={row.isLastInGroup} />
+      );
+    }
 
-                return (
-                    <React.Fragment key={key}>
-                        {/* Main property row */}
-                        <tr style={{ backgroundColor: isReq ? 'rgba(255,0,0,0.05)' : 'transparent' }}>
-                            <td>
-                                <strong>{key}</strong>
-                                {hasChildren && <span style={{ fontSize: '0.8em', marginLeft: '5px' }}>⤵</span>}
-                            </td>
-                            <td><code>{Array.isArray(prop.type) ? prop.type.join('|') : prop.type}</code></td>
-                            <td style={{ textAlign: 'center' }}>{isReq ? '✅' : ''}</td>
-                            <td>{prop.examples ? prop.examples.join(', ') : ''}</td>
-                            <td>{prop.description || ''}</td>
-                        </tr>
-
-                        {/* Nested children rendered immediately after parent */}
-                        {hasChildren && (
-                            <tr>
-                                <td colSpan="5" style={{ paddingLeft: '20px', borderLeft: '4px solid #eee' }}>
-                                    <strong>{prop.type === 'array' ? `${key} [ ]` : `${key} { }`}</strong>
-                                    <table style={{ width: '100%', marginTop: '5px' }}>
-                                        <thead>
-                                            <tr>
-                                                <th width="20%">Property</th>
-                                                <th width="15%">Type</th>
-                                                <th width="10%">Req</th>
-                                                <th width="15%">Examples</th>
-                                                <th>Description</th>
-                                            </tr>
-                                        </thead>
-                                        <tbody>
-                                            <SchemaRows
-                                                properties={prop.type === 'object' ? prop.properties : prop.items.properties}
-                                                requiredList={prop.type === 'object' ? prop.required || [] : prop.items.required || []}
-                                                level={level + 1}
-                                            />
-                                        </tbody>
-                                    </table>
-                                </td>
-                            </tr>
-                        )
-                        }
-                    </React.Fragment >
-                );
-            })}
-        </>
-    );
-};
-
-export default SchemaRows;
+    return null;
+  });
+}

package/components/SchemaViewer.js

@@ -1,19 +1,27 @@
+import React from 'react';
+import Heading from '@theme/Heading';
 import ExampleDataLayer from './ExampleDataLayer';
 import PropertiesTable from './PropertiesTable';
 
-// --- Main Exported Component ---
-// Helper: Build an example payload from per-property `examples` or other hints
-
-
 export default function SchemaViewer({ schema }) {
+  const hasOneOfAnyOf =
+    schema.oneOf ||
+    schema.anyOf ||
+    (schema.properties &&
+      Object.values(schema.properties).some(
+        (prop) => prop.oneOf || prop.anyOf,
+      ));
+  const exampleTitle = hasOneOfAnyOf
+    ? 'DataLayer Examples'
+    : 'DataLayer Example';
 
-    return (
-        <div>
-            <h2>DataLayer Example</h2>
-            <ExampleDataLayer schema={schema} />
+  return (
+    <div>
+      <Heading as="h2">{exampleTitle}</Heading>
+      <ExampleDataLayer schema={schema} />
 
-            <h2>Event Properties</h2>
-            <PropertiesTable schema={schema} />
-        </div>
-    );
-}
+      <Heading as="h2">Event Properties</Heading>
+      <PropertiesTable schema={schema} />
+    </div>
+  );
+}

package/components/TableHeader.js

@@ -0,0 +1,15 @@
+import React from 'react';
+
+export default function TableHeader() {
+  return (
+    <thead>
+      <tr>
+        <th>Property</th>
+        <th>Type</th>
+        <th>Constraints</th>
+        <th>Examples</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+  );
+}

package/generateEventDocs.js

@@ -1,68 +1,149 @@
-import $RefParser from "@apidevtools/json-schema-ref-parser";
-import mergeJsonSchema from "json-schema-merge-allof";
-import fs from 'fs';
 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 { processOneOfSchema, slugify } from './helpers/schema-processing.js';
+import SchemaDocTemplate from './helpers/schema-doc-template.js';
+import ChoiceIndexTemplate from './helpers/choice-index-template.js';
+import processSchema from './helpers/processSchema.js';
+
+async function generateAndWriteDoc(
+  filePath,
+  schema,
+  eventName,
+  outputDir,
+  options,
+  alreadyMergedSchema = null,
+) {
+  const { organizationName, projectName, siteDir } = options;
+  const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
+  const PARTIALS_DIR = path.join(siteDir, 'docs/partials');
+
+  const mergedSchema = alreadyMergedSchema || (await processSchema(filePath));
+
+  // Check for partials
+  const topPartialPath = path.join(PARTIALS_DIR, `${eventName}.mdx`);
+  const bottomPartialPath = path.join(PARTIALS_DIR, `${eventName}_bottom.mdx`);
+
+  let topPartialImport = '';
+  let topPartialComponent = '';
+  if (fs.existsSync(topPartialPath)) {
+    topPartialImport = `import TopPartial from '@site/docs/partials/${eventName}.mdx';`;
+    topPartialComponent = '<TopPartial />';
+  }
+
+  let bottomPartialImport = '';
+  let bottomPartialComponent = '';
+  if (fs.existsSync(bottomPartialPath)) {
+    bottomPartialImport = `import BottomPartial from '@site/docs/partials/${eventName}_bottom.mdx';`;
+    bottomPartialComponent = '<BottomPartial />';
+  }
+
+  const editUrl = `${baseEditUrl}/${path.relative(
+    path.join(siteDir, '..'),
+    filePath,
+  )}`;
+
+  const mdxContent = SchemaDocTemplate({
+    schema,
+    mergedSchema,
+    editUrl,
+    file: path.basename(filePath),
+    topPartialImport,
+    bottomPartialImport,
+    topPartialComponent,
+    bottomPartialComponent,
+  });
+
+  const outputFilename = path.basename(filePath).replace('.json', '.mdx');
+  writeDoc(outputDir, outputFilename, mdxContent);
+}
+
+async function generateOneOfDocs(
+  eventName,
+  schema,
+  filePath,
+  outputDir,
+  options,
+) {
+  const eventOutputDir = path.join(outputDir, eventName);
+  createDir(eventOutputDir);
+
+  const processed = await processOneOfSchema(schema, filePath);
+
+  const indexPageContent = ChoiceIndexTemplate({
+    schema,
+    processedOptions: processed,
+  });
+  writeDoc(eventOutputDir, 'index.mdx', indexPageContent);
+
+  for (const [
+    index,
+    { slug, schema: processedSchema },
+  ] of processed.entries()) {
+    const subChoiceType = processedSchema.oneOf ? 'oneOf' : null;
+    const prefixedSlug = `${(index + 1).toString().padStart(2, '0')}-${slug}`;
+
+    if (subChoiceType) {
+      const tempFilePath = path.join(eventOutputDir, `${slug}.json`);
+      fs.writeFileSync(tempFilePath, JSON.stringify(processedSchema, null, 2));
+      await generateOneOfDocs(
+        prefixedSlug,
+        processedSchema,
+        tempFilePath,
+        eventOutputDir,
+        options,
+      );
+      fs.unlinkSync(tempFilePath);
+    } else {
+      const tempFilePath = path.join(eventOutputDir, `${prefixedSlug}.json`);
+      fs.writeFileSync(tempFilePath, JSON.stringify(processedSchema, null, 2));
+      await generateAndWriteDoc(
+        tempFilePath,
+        processedSchema,
+        slug,
+        eventOutputDir,
+        options,
+        processedSchema,
+      );
+      fs.unlinkSync(tempFilePath);
+    }
+  }
+}
+
+export default async function generateEventDocs(options) {
+  const { siteDir, version, url } = options || {};
+  const { schemaDir, outputDir } = getPathsForVersion(version, siteDir);
+
+  createDir(outputDir);
+  const schemas = readSchemas(schemaDir);
+
+  console.log(`🚀 Generating documentation for ${schemas.length} schemas...`);
 
-export default async function generateEventDocs() {
-    // CONFIGURATION
-    const SCHEMA_DIR = 'schemas'; // Where your JSON files are
-    const OUTPUT_DIR = 'docs/events'; // Where MDX goes
+  for (const { fileName, filePath, schema } of schemas) {
+    const eventName = fileName.replace('.json', '');
 
-    // Ensure output dir exists
-    if (!fs.existsSync(OUTPUT_DIR))
-    {
-        fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+    if (version) {
+      const baseUrl = url.endsWith('/') ? url.slice(0, -1) : url;
+      if (version !== 'current') {
+        schema.$id = `${baseUrl}/schemas/${version}/${fileName}`;
+      } else {
+        schema.$id = `${baseUrl}/schemas/next/${fileName}`;
+      }
     }
 
-    // Read all JSON files
-    const files = fs.readdirSync(SCHEMA_DIR).filter(file => file.endsWith('.json'));
-
-    console.log(`🚀 Generating documentation for ${files.length} schemas...`);
-
-    for (const file of files)
-    {
-        const filePath = path.join(SCHEMA_DIR, file);
-        const rawContent = fs.readFileSync(filePath, 'utf-8');
-        const schema = JSON.parse(rawContent);
-
-        // First, dereference all $ref properties
-        const clonedSchema = await $RefParser.dereference(filePath, {
-            mutateInputSchema: false, dereference: {
-                circular: 'ignore'
-            }
-        });
-
-        // Then merge allOf properties
-        const mergedSchema = mergeJsonSchema(clonedSchema, {
-            resolvers: {
-                defaultResolver: mergeJsonSchema.options.resolvers.title
-            }
-        });
-
-        // Define the MDX Content
-        // We embed the JSON directly into the file to avoid Webpack import issues
-        const mdxContent = `---
-title: ${schema.title}
-description: ${schema.description}
-sidebar_label: ${schema.title}
----
-
-import SchemaViewer from '@theme/SchemaViewer';
-import SchemaJsonViewer from '@theme/SchemaJsonViewer';
-
-# ${schema.title}
-
-${schema.description}
-
-<SchemaViewer schema={${JSON.stringify(mergedSchema)}} />
-<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
-`;
-
-        // Write the .mdx file
-        const outputFilename = file.replace('.json', '.mdx');
-        fs.writeFileSync(path.join(OUTPUT_DIR, outputFilename), mdxContent);
-        console.log(`✅ Generated docs/events/${outputFilename}`);
+    if (schema.oneOf) {
+      await generateOneOfDocs(eventName, schema, filePath, outputDir, options);
+    } else {
+      await generateAndWriteDoc(
+        filePath,
+        schema,
+        eventName,
+        outputDir,
+        options,
+      );
     }
+  }
 
-    console.log('🎉 Documentation generation complete!');
+  console.log('🎉 Documentation generation complete!');
 }

package/helpers/buildExampleFromSchema.js

@@ -1,83 +1,69 @@
+/**
+ * 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) => {
-    const buildValue = (prop) => {
-        if (!prop) return undefined;
+  if (!schema) return undefined;
 
-        // 1. Prefer explicit examples or constants if available
-        if (prop.examples && prop.examples.length) return prop.examples[0];
-        if (prop.const !== undefined) return prop.const;
-        if (prop.default !== undefined) return prop.default;
+  // For choices, default to the first option.
+  if (schema.oneOf?.length > 0) {
+    return buildExampleFromSchema(schema.oneOf[0]);
+  }
+  if (schema.anyOf?.length > 0) {
+    return buildExampleFromSchema(schema.anyOf[0]);
+  }
 
-        const type = Array.isArray(prop.type) ? prop.type[0] : prop.type;
+  // 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;
 
-        if (type === 'object')
-        {
-            if (prop.properties)
-            {
-                const obj = {};
-                Object.entries(prop.properties).forEach(([k, v]) => {
-                    const val = buildValue(v);
-                    // Only add the property if it has a valid value (not undefined)
-                    if (val !== undefined)
-                    {
-                        obj[k] = val;
-                    }
-                });
+  let type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  if (!type && schema.properties) {
+    type = 'object';
+  }
 
-                // If the object ends up having no keys, consider it "empty" and return undefined
-                if (Object.keys(obj).length === 0) return undefined;
-                return obj;
-            }
-            // Object with no properties defined
-            return {};
+  if (type === 'object') {
+    if (schema.properties) {
+      const obj = {};
+      Object.entries(schema.properties).forEach(([key, propSchema]) => {
+        const value = buildExampleFromSchema(propSchema);
+        if (typeof value !== 'undefined') {
+          obj[key] = value;
         }
-
-        if (type === 'array')
-        {
-            if (prop.items)
-            {
-                const itemVal = buildValue(prop.items);
-                // If the inner item is valid, return it as an array
-                if (itemVal !== undefined)
-                {
-                    return [itemVal];
-                }
-            }
-            // Empty array or array of undefined items
-            return [];
-        }
-
-        switch (type)
-        {
-            case 'string': return '';
-            case 'integer':
-            case 'number': return 0;
-            case 'boolean': return false;
-            default: return undefined;
-        }
-    };
-
-    // If the schema provides a top-level examples array with an object, prefer it
-    if (schema && schema.examples && schema.examples.length)
-    {
-        const first = schema.examples[0];
-        if (typeof first === 'object' && first !== null) return first;
+      });
+      // 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;
+  }
 
-    // Otherwise, build from properties
-    if (schema && schema.properties)
-    {
-        const out = {};
-        Object.entries(schema.properties).forEach(([k, p]) => {
-            const val = buildValue(p);
-            // Only add top-level keys if they are not undefined
-            if (val !== undefined)
-            {
-                out[k] = val;
-            }
-        });
-        return out;
+  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.
+  }
+
+  // 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 {};
-}
-export default buildExampleFromSchema;
+export default buildExampleFromSchema;

package/helpers/choice-index-template.js

@@ -0,0 +1,22 @@
+export default function ChoiceIndexTemplate(data) {
+  const { schema, processedOptions } = data;
+
+  return `---
+title: ${schema.title}
+description: "${schema.description}"
+---
+import SchemaJsonViewer from '@theme/SchemaJsonViewer';
+
+# ${schema.title}
+
+${schema.description}
+
+Please select one of the following options:
+
+${processedOptions
+  .map((option) => `- [${option.schema.title}](./${option.slug})`)
+  .join('\n')}
+
+<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
+`;
+}

package/helpers/file-system.js

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import path from 'path';
+import loadSchema from './loadSchema';
+
+export function createDir(directory) {
+  if (!fs.existsSync(directory)) {
+    fs.mkdirSync(directory, { recursive: true });
+  }
+}
+
+export function readSchemas(directory) {
+  const files = fs
+    .readdirSync(directory)
+    .filter((file) => file.endsWith('.json'));
+
+  return files.map((file) => {
+    const filePath = path.join(directory, file);
+    const schema = loadSchema(filePath);
+    return {
+      fileName: file,
+      filePath,
+      schema,
+    };
+  });
+}
+
+export function writeDoc(outputDir, fileName, content) {
+  fs.writeFileSync(path.join(outputDir, fileName), content);
+  console.log(
+    `✅ Generated ${path.relative(process.cwd(), path.join(outputDir, fileName))}`,
+  );
+}

package/helpers/getConstraints.js

@@ -0,0 +1,52 @@
+// A list of JSON Schema keywords that have simple key-value constraints.
+const constraintHandlers = {
+  // Simple key-value constraints
+  minLength: (val) => `minLength: ${val}`,
+  maxLength: (val) => `maxLength: ${val}`,
+  minimum: (val) => `minimum: ${val}`,
+  maximum: (val) => `maximum: ${val}`,
+  exclusiveMinimum: (val) => `exclusiveMinimum: ${val}`,
+  exclusiveMaximum: (val) => `exclusiveMaximum: ${val}`,
+  minItems: (val) => `minItems: ${val}`,
+  maxItems: (val) => `maxItems: ${val}`,
+  minProperties: (val) => `minProperties: ${val}`,
+  maxProperties: (val) => `maxProperties: ${val}`,
+  multipleOf: (val) => `multipleOf: ${val}`,
+  format: (val) => `format: ${val}`,
+  minContains: (val) => `minContains: ${val}`,
+  maxContains: (val) => `maxContains: ${val}`,
+
+  // Special-cased constraints
+  pattern: (val) => `pattern: /${val}/`,
+  uniqueItems: (val) => (val ? 'uniqueItems: true' : null),
+  additionalProperties: (val) =>
+    val === false ? 'additionalProperties: false' : null,
+  propertyNames: (val) => `propertyNames: ${JSON.stringify(val)}`,
+  dependentRequired: (val) => {
+    const deps = Object.entries(val)
+      .map(([key, depVal]) => `${key} -> [${depVal.join(', ')}]`)
+      .join('; ');
+    return `dependentRequired: ${deps}`;
+  },
+  contains: (val) => `contains: ${JSON.stringify(val)}`,
+  enum: (val) => `enum: [${val.join(', ')}]`,
+  const: (val) => `const: ${JSON.stringify(val)}`,
+};
+
+export const getConstraints = (prop, isReq) => {
+  const constraints = [];
+  if (isReq) {
+    constraints.push('required');
+  }
+
+  for (const keyword in constraintHandlers) {
+    if (prop[keyword] !== undefined) {
+      const handler = constraintHandlers[keyword];
+      const result = handler(prop[keyword]);
+      if (result) {
+        constraints.push(result);
+      }
+    }
+  }
+  return constraints;
+};

package/helpers/loadSchema.js

@@ -0,0 +1,11 @@
+import fs from 'fs';
+
+/**
+ * Loads a JSON schema file and returns its content as a JSON object.
+ * @param {string} filePath Path to the JSON schema file.
+ * @returns {object} The parsed JSON schema.
+ */
+export default function loadSchema(filePath) {
+  const rawContent = fs.readFileSync(filePath, 'utf-8');
+  return JSON.parse(rawContent);
+}

package/helpers/path-helpers.js

@@ -0,0 +1,22 @@
+import path from 'path';
+
+export function getPathsForVersion(version, siteDir) {
+  let schemaDir;
+  let outputDir;
+
+  if (version) {
+    if (version !== 'current') {
+      schemaDir = path.join(siteDir, 'static/schemas', version);
+      outputDir = path.join(siteDir, 'versioned_docs', `version-${version}`);
+    } else {
+      schemaDir = path.join(siteDir, 'static/schemas', 'next');
+      outputDir = path.join(siteDir, 'docs');
+    }
+  } else {
+    // Non-versioned
+    schemaDir = path.join(siteDir, 'static/schemas');
+    outputDir = path.join(siteDir, 'docs');
+  }
+
+  return { schemaDir, outputDir };
+}