docusaurus-plugin-generate-schema-docs 1.6.0 → 1.7.1

package/components/PropertiesTable.js

@@ -21,7 +21,7 @@ export default function PropertiesTable({ schema }) {
           isEnabled={isWordWrapOn}
         />
       </div>
-      <table>
+      <table className="schema-table">
         <TableHeader />
         <tbody>
           <SchemaRows tableData={tableData} />

package/components/PropertyRow.js

@@ -1,6 +1,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import CodeBlock from '@theme/CodeBlock';
+import { getBracketLinesStyle } from '../helpers/continuingLinesStyle';
 
 /**
  * Formats a single example value into a string for display in a CodeBlock.
@@ -30,7 +31,7 @@ const getContainerSymbol = (containerType) => {
  * All data is passed in via the `row` prop, which comes from `tableData`.
  * This component handles multi-row constraints using `rowSpan`.
  */
-export default function PropertyRow({ row, isLastInGroup }) {
+export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
   const {
     name,
     level,
@@ -42,6 +43,7 @@ export default function PropertyRow({ row, isLastInGroup }) {
     hasChildren,
     containerType,
     continuingLevels = [],
+    groupBrackets = [],
   } = row;
 
   const indentStyle = {
@@ -56,7 +58,7 @@ export default function PropertyRow({ row, isLastInGroup }) {
     ? constraints
     : [null];
 
-  // Generate background gradients for:
+  // Generate background gradients for tree connector lines (left side):
   // 1. Parent-to-child line (from 50% down) - for elements with children
   // 2. Continuing ancestor lines (full height) - for ancestors that have more siblings below
   //
@@ -69,7 +71,6 @@ export default function PropertyRow({ row, isLastInGroup }) {
   const allPositions = [];
 
   // Parent-to-child line: draws from 50% (below symbol) to bottom of cell
-  // Position is at the child's level, which is (level * 20 + 8)px
   if (hasChildren) {
     const childLevelPos = level * 1.25 + 0.5;
     allGradients.push(
@@ -79,10 +80,14 @@ export default function PropertyRow({ row, isLastInGroup }) {
     allPositions.push(`${childLevelPos}rem top`);
   }
 
-  // Continuing ancestor lines: full-height vertical lines for ancestors with more siblings
-  // Filter to only include levels less than (level - 1) since ::before handles immediate parent
+  // Continuing ancestor lines: full-height vertical lines for ancestors with more siblings.
+  // Only levels strictly below the immediate parent (< level - 1) are drawn here.
+  // The ::before pseudo-element handles the immediate parent connector at level - 1.
+  // We also require lvl+1 to be in continuingLevels: if the next level up is not continuing
+  // (i.e. the parent was the last sibling), drawing lvl's line would create a stray line at
+  // the same x-position as that parent's elbow.
   continuingLevels
-    .filter((lvl) => lvl < level - 1)
+    .filter((lvl) => lvl < level - 1 && continuingLevels.includes(lvl + 1))
     .forEach((lvl) => {
       const pos = getLevelPosition(lvl);
       allGradients.push(
@@ -102,11 +107,20 @@ export default function PropertyRow({ row, isLastInGroup }) {
         }
       : {};
 
+  // Bracket lines on the right side (description column)
+  const bracketCaps = bracketEnds ? { ending: bracketEnds } : undefined;
+  const bracketStyle = getBracketLinesStyle(groupBrackets, bracketCaps);
+
   const containerSymbol = getContainerSymbol(containerType);
 
   return (
     <>
-      <tr className={clsx(required && 'required-row')}>
+      <tr
+        className={clsx(
+          required && 'required-row',
+          row.isCondition && 'conditional-condition-row',
+        )}
+      >
         <td
           rowSpan={rowSpan}
           style={{ ...indentStyle, ...continuingLinesStyle }}
@@ -159,7 +173,9 @@ export default function PropertyRow({ row, isLastInGroup }) {
               );
             })}
         </td>
-        <td rowSpan={rowSpan}>{description || ''}</td>
+        <td rowSpan={rowSpan} style={bracketStyle}>
+          {description || ''}
+        </td>
       </tr>
 
       {/* Render subsequent constraints in their own rows */}

package/components/SchemaRows.css

@@ -42,6 +42,40 @@
   margin-left: -0.55em;
 }
 
+/* --- Schema Table Border Model --- */
+
+/*
+ * Use border-collapse: separate with 0 spacing so that backgrounds are
+ * painted directly adjacent between rows — no collapsed border line is
+ * rendered on top of the background gradients. Horizontal separators are
+ * recreated via box-shadow so they don't interrupt vertical lines.
+ */
+.schema-table {
+  border-collapse: separate;
+  border-spacing: 0;
+  border: 1px solid var(--ifm-table-border-color);
+}
+
+.schema-table th,
+.schema-table td {
+  border: none;
+  border-left: 1px solid var(--ifm-table-border-color);
+}
+
+.schema-table th:first-child,
+.schema-table td:first-child {
+  border-left: none;
+}
+
+.schema-table thead th {
+  border-bottom: 2px solid var(--ifm-table-border-color);
+}
+
+/* Row separators via box-shadow (doesn't mask background gradients) */
+.schema-table tbody tr + tr td {
+  box-shadow: inset 0 1px 0 var(--ifm-table-border-color);
+}
+
 /* --- Organigram Connector Line Styles --- */
 
 /*
@@ -225,6 +259,87 @@ td.level-6::after {
   transform: rotate(45deg);
 }
 
+/* --- Conditional Row Styles --- */
+
+.conditional-condition-header {
+  background-color: rgba(var(--ifm-color-info-rgb), 0.08);
+}
+
+.conditional-condition-header:hover {
+  background-color: rgba(var(--ifm-color-info-rgb), 0.12);
+}
+
+.conditional-condition-label {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.conditional-info-icon-wrapper {
+  position: relative;
+  display: inline-flex;
+  cursor: help;
+}
+
+.conditional-info-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.25rem;
+  height: 1.25rem;
+  border-radius: 50%;
+  background-color: var(--ifm-color-info);
+  color: white;
+  font-size: 0.75rem;
+  font-weight: bold;
+  font-style: italic;
+  flex-shrink: 0;
+}
+
+.conditional-info-tooltip {
+  display: none;
+  position: absolute;
+  bottom: calc(100% + 0.5rem);
+  left: 0;
+  background-color: var(--ifm-color-emphasis-800);
+  color: var(--ifm-color-emphasis-0);
+  padding: 0.5rem 0.75rem;
+  border-radius: 0.375rem;
+  font-size: 0.8rem;
+  font-style: normal;
+  font-weight: normal;
+  line-height: 1.4;
+  white-space: normal;
+  width: max-content;
+  max-width: 280px;
+  z-index: 10;
+  pointer-events: none;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+}
+
+.conditional-info-tooltip::after {
+  content: '';
+  position: absolute;
+  top: 100%;
+  left: 0.625rem;
+  border: 0.375rem solid transparent;
+  border-top-color: var(--ifm-color-emphasis-800);
+}
+
+.conditional-info-icon-wrapper:hover .conditional-info-tooltip {
+  display: block;
+}
+
+.conditional-condition-description {
+  margin-left: 1.75rem;
+  font-size: 0.9em;
+  color: var(--ifm-color-secondary-darkest);
+}
+
+.conditional-condition-row {
+  background-color: rgba(var(--ifm-color-info-rgb), 0.04);
+}
+
 /* --- Example CodeBlock Styles --- */
 
 .schema-examples {

package/components/SchemaRows.js

@@ -2,26 +2,53 @@ import React from 'react';
 import './SchemaRows.css';
 import PropertyRow from './PropertyRow';
 import FoldableRows from './FoldableRows';
+import ConditionalRows from './ConditionalRows';
 
 /**
  * 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.
+ *
+ * @param {object} props
+ * @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 }) {
+export default function SchemaRows({ tableData, bracketEnds }) {
   if (!tableData) {
     return null;
   }
 
-  return tableData.map((row) => {
+  return tableData.map((row, index) => {
     const key = row.path.join('.');
+    const isLast = index === tableData.length - 1;
 
     if (row.type === 'choice') {
-      return <FoldableRows key={key} row={row} />;
+      return (
+        <FoldableRows
+          key={key}
+          row={row}
+          bracketEnds={isLast ? bracketEnds : undefined}
+        />
+      );
+    }
+
+    if (row.type === 'conditional') {
+      return (
+        <ConditionalRows
+          key={key}
+          row={row}
+          bracketEnds={isLast ? bracketEnds : undefined}
+        />
+      );
     }
 
     if (row.type === 'property') {
       return (
-        <PropertyRow key={key} row={row} isLastInGroup={row.isLastInGroup} />
+        <PropertyRow
+          key={key}
+          row={row}
+          isLastInGroup={row.isLastInGroup}
+          bracketEnds={isLast ? bracketEnds : undefined}
+        />
       );
     }
 

package/generateEventDocs.js

@@ -7,6 +7,20 @@ import SchemaDocTemplate from './helpers/schema-doc-template.js';
 import ChoiceIndexTemplate from './helpers/choice-index-template.js';
 import processSchema from './helpers/processSchema.js';
 
+function buildEditUrl(organizationName, projectName, siteDir, filePath) {
+  const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
+  return `${baseEditUrl}/${path.relative(path.join(siteDir, '..'), filePath)}`;
+}
+
+function resolvePartial(partialPath, relativePartialsDir, componentPrefix) {
+  if (!fs.existsSync(partialPath)) return { import: '', component: '' };
+  const fileName = path.basename(partialPath);
+  return {
+    import: `import ${componentPrefix} from '@site/${relativePartialsDir}/${fileName}';`,
+    component: `<${componentPrefix} />`,
+  };
+}
+
 async function generateAndWriteDoc(
   filePath,
   schema,
@@ -18,7 +32,6 @@ async function generateAndWriteDoc(
 ) {
   const { organizationName, projectName, siteDir, dataLayerName, version } =
     options;
-  const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
 
   const { outputDir: versionOutputDir } = getPathsForVersion(version, siteDir);
   const PARTIALS_DIR = path.join(versionOutputDir, 'partials');
@@ -27,37 +40,33 @@ async function generateAndWriteDoc(
   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/${relativePartialsDir}/_${eventName}.mdx';`;
-    topPartialComponent = '<TopPartial />';
-  }
-
-  let bottomPartialImport = '';
-  let bottomPartialComponent = '';
-  if (fs.existsSync(bottomPartialPath)) {
-    bottomPartialImport = `import BottomPartial from '@site/${relativePartialsDir}/_${eventName}_bottom.mdx';`;
-    bottomPartialComponent = '<BottomPartial />';
-  }
-
-  const editUrl = `${baseEditUrl}/${path.relative(
-    path.join(siteDir, '..'),
+  const top = resolvePartial(
+    path.join(PARTIALS_DIR, `_${eventName}.mdx`),
+    relativePartialsDir,
+    'TopPartial',
+  );
+  const bottom = resolvePartial(
+    path.join(PARTIALS_DIR, `_${eventName}_bottom.mdx`),
+    relativePartialsDir,
+    'BottomPartial',
+  );
+
+  const editUrl = buildEditUrl(
+    organizationName,
+    projectName,
+    siteDir,
     editFilePath || filePath,
-  )}`;
+  );
 
   const mdxContent = SchemaDocTemplate({
     schema,
     mergedSchema,
     editUrl,
     file: path.basename(filePath),
-    topPartialImport,
-    bottomPartialImport,
-    topPartialComponent,
-    bottomPartialComponent,
+    topPartialImport: top.import,
+    bottomPartialImport: bottom.import,
+    topPartialComponent: top.component,
+    bottomPartialComponent: bottom.component,
     dataLayerName,
   });
 
@@ -73,8 +82,12 @@ async function generateOneOfDocs(
   options,
 ) {
   const { organizationName, projectName, siteDir } = options;
-  const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
-  const editUrl = `${baseEditUrl}/${path.relative(path.join(siteDir, '..'), filePath)}`;
+  const editUrl = buildEditUrl(
+    organizationName,
+    projectName,
+    siteDir,
+    filePath,
+  );
 
   const eventOutputDir = path.join(outputDir, eventName);
   createDir(eventOutputDir);
@@ -96,8 +109,6 @@ async function generateOneOfDocs(
     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,
@@ -105,12 +116,9 @@ async function generateOneOfDocs(
         eventOutputDir,
         options,
       );
-      fs.unlinkSync(tempFilePath);
     } else {
-      const tempFilePath = path.join(eventOutputDir, `${prefixedSlug}.json`);
-      fs.writeFileSync(tempFilePath, JSON.stringify(processedSchema, null, 2));
       await generateAndWriteDoc(
-        tempFilePath,
+        `${prefixedSlug}.json`,
         processedSchema,
         slug,
         eventOutputDir,
@@ -118,7 +126,6 @@ async function generateOneOfDocs(
         processedSchema,
         sourceFilePath || filePath,
       );
-      fs.unlinkSync(tempFilePath);
     }
   }
 }

package/helpers/buildExampleFromSchema.js

@@ -30,6 +30,17 @@ const buildExampleFromSchema = (schema) => {
     return buildExampleFromSchema(merged);
   }
 
+  // For conditionals, default to the 'then' branch and recurse.
+  if (schema.if && schema.then) {
+    const newSchema = { ...schema };
+    const thenBranch = newSchema.then;
+    delete newSchema.if;
+    delete newSchema.then;
+    delete newSchema.else;
+    const merged = mergeJsonSchema({ allOf: [newSchema, thenBranch] });
+    return buildExampleFromSchema(merged);
+  }
+
   // If there's an explicit example, use it.
   const exampleValue = getSingleExampleValue(schema);
   if (typeof exampleValue !== 'undefined') {

package/helpers/continuingLinesStyle.js

@@ -0,0 +1,169 @@
+/**
+ * Colors for group bracket lines, indexed by bracketIndex.
+ * Uses Docusaurus CSS custom properties so they adapt to light/dark themes.
+ */
+const BRACKET_COLORS = [
+  'var(--ifm-color-info)',
+  'var(--ifm-color-warning)',
+  'var(--ifm-color-success)',
+];
+
+/**
+ * Returns the right-offset (in rem) for a bracket line.
+ * Brackets are positioned from the right edge of the cell so they appear
+ * on the right side of the table, away from the tree connector lines.
+ *
+ *   B=0 → 0.50 rem from right
+ *   B=1 → 0.75 rem from right
+ *   B=2 → 1.00 rem from right
+ */
+export const getBracketPosition = (bracketIndex) => 0.5 + bracketIndex * 0.25;
+
+export const getBracketColor = (bracketIndex) =>
+  BRACKET_COLORS[bracketIndex % BRACKET_COLORS.length];
+
+/** Width of horizontal cap lines in pixels */
+const CAP_WIDTH = 10;
+
+/** Inset from cell edge for cap lines (so they aren't hidden by table borders) */
+const CAP_INSET = 6;
+
+/** Helper to create a bracket key for Set lookups */
+const bracketKey = (b) => `${b.level}:${b.bracketIndex}`;
+
+/**
+ * Generates inline styles for bracket lines positioned on the right side.
+ * Supports optional horizontal "cap" lines at the top and/or bottom of
+ * brackets to visually delineate where a bracket group starts and ends.
+ *
+ * @param {Array<{level: number, bracketIndex: number}>} groupBrackets - Active bracket groups
+ * @param {object} [caps] - Optional cap configuration
+ * @param {Array<{level: number, bracketIndex: number}>} [caps.starting] - Brackets needing a top cap
+ * @param {Array<{level: number, bracketIndex: number}>} [caps.ending] - Brackets needing a bottom cap
+ * @returns {object} Style object with background gradients
+ */
+export const getBracketLinesStyle = (groupBrackets = [], caps = {}) => {
+  if (groupBrackets.length === 0) return {};
+
+  const startingKeys = new Set((caps.starting || []).map(bracketKey));
+  const endingKeys = new Set((caps.ending || []).map(bracketKey));
+
+  const gradients = [];
+  const sizes = [];
+  const positions = [];
+
+  groupBrackets.forEach((bracket) => {
+    const { bracketIndex } = bracket;
+    const pos = getBracketPosition(bracketIndex);
+    const color = getBracketColor(bracketIndex);
+    const key = bracketKey(bracket);
+    const isStarting = startingKeys.has(key);
+    const isEnding = endingKeys.has(key);
+
+    // Vertical line — shortened when caps are present so it doesn't bleed past them
+    const topInset = isStarting ? CAP_INSET : 0;
+    const bottomInset = isEnding ? CAP_INSET : 0;
+    gradients.push(`linear-gradient(${color}, ${color})`);
+    sizes.push(`1px calc(100% - ${topInset + bottomInset}px)`);
+    positions.push(`right ${pos}rem top ${topInset}px`);
+
+    // Horizontal cap at the top (bracket start) — inset from cell edge
+    if (isStarting) {
+      const capOffset = (CAP_WIDTH - 1) / 2; // center cap on the vertical line
+      gradients.push(`linear-gradient(${color}, ${color})`);
+      sizes.push(`${CAP_WIDTH}px 1px`);
+      positions.push(
+        `right calc(${pos}rem - ${capOffset}px) top ${CAP_INSET}px`,
+      );
+    }
+
+    // Horizontal cap at the bottom (bracket end) — inset from cell edge
+    if (isEnding) {
+      const capOffset = (CAP_WIDTH - 1) / 2;
+      gradients.push(`linear-gradient(${color}, ${color})`);
+      sizes.push(`${CAP_WIDTH}px 1px`);
+      positions.push(
+        `right calc(${pos}rem - ${capOffset}px) bottom ${CAP_INSET}px`,
+      );
+    }
+  });
+
+  return {
+    backgroundImage: gradients.join(', '),
+    backgroundSize: sizes.join(', '),
+    backgroundPosition: positions.join(', '),
+    backgroundRepeat: 'no-repeat',
+  };
+};
+
+/**
+ * Merges two background-gradient style objects into one.
+ * @param {object} style1 - First style object
+ * @param {object} style2 - Second style object
+ * @returns {object} Merged style object
+ */
+export const mergeBackgroundStyles = (style1, style2) => {
+  if (!style2.backgroundImage) return style1;
+  if (!style1.backgroundImage) return { ...style1, ...style2 };
+
+  return {
+    ...style1,
+    backgroundImage: `${style1.backgroundImage}, ${style2.backgroundImage}`,
+    backgroundSize: `${style1.backgroundSize}, ${style2.backgroundSize}`,
+    backgroundPosition: `${style1.backgroundPosition}, ${style2.backgroundPosition}`,
+    backgroundRepeat: 'no-repeat',
+  };
+};
+
+/**
+ * Generates inline styles for continuing hierarchical lines through a row.
+ * Only handles tree connector lines (left side). Bracket lines are separate.
+ * @param {number[]} continuingLevels - Array of ancestor levels that need lines
+ * @param {number} level - Current level of the row
+ * @returns {object} Style object with background gradients
+ */
+export const getContinuingLinesStyle = (continuingLevels = [], level = 0) => {
+  const getLevelPosition = (lvl) => lvl * 1.25 + 0.5;
+
+  const allGradients = [];
+  const allSizes = [];
+  const allPositions = [];
+
+  // Draw continuing lines for all ancestor levels
+  continuingLevels.forEach((lvl) => {
+    const pos = getLevelPosition(lvl);
+    allGradients.push(
+      'linear-gradient(var(--ifm-table-border-color), var(--ifm-table-border-color))',
+    );
+    allSizes.push('1px 100%');
+    allPositions.push(`${pos}rem top`);
+  });
+
+  // Also draw the line for the immediate parent level (level - 1) if level > 0
+  // This connects the rows to their parent property
+  if (level > 0) {
+    const parentPos = getLevelPosition(level - 1);
+    if (!continuingLevels.includes(level - 1)) {
+      allGradients.push(
+        'linear-gradient(var(--ifm-table-border-color), var(--ifm-table-border-color))',
+      );
+      allSizes.push('1px 100%');
+      allPositions.push(`${parentPos}rem top`);
+    }
+  }
+
+  // Calculate indentation based on level
+  const paddingLeft = `${level * 1.25 + 0.5}rem`;
+
+  if (allGradients.length === 0) {
+    return { paddingLeft };
+  }
+
+  return {
+    paddingLeft,
+    backgroundImage: allGradients.join(', '),
+    backgroundSize: allSizes.join(', '),
+    backgroundPosition: allPositions.join(', '),
+    backgroundRepeat: 'no-repeat',
+  };
+};

package/helpers/schema-doc-template.js

@@ -8,6 +8,7 @@ export default function MdxTemplate(data) {
     bottomPartialImport,
     topPartialComponent,
     bottomPartialComponent,
+    dataLayerName,
   } = data;
 
   return `---
@@ -30,11 +31,7 @@ ${topPartialComponent}
 
 <SchemaViewer
   schema={${JSON.stringify(mergedSchema)}}
-  ${
-    data.dataLayerName && data.dataLayerName !== 'undefined'
-      ? ` dataLayerName={'${data.dataLayerName}'}`
-      : ''
-  }
+  ${dataLayerName ? ` dataLayerName={'${dataLayerName}'}` : ''}
 />
 <SchemaJsonViewer schema={${JSON.stringify(schema)}} />