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

package/components/ExampleDataLayer.js

@@ -1,40 +1,71 @@
 import React from 'react';
 import CodeBlock from '@theme/CodeBlock';
-import buildExampleFromSchema from '../helpers/buildExampleFromSchema';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Heading from '@theme/Heading';
+import { schemaToExamples } from '../helpers/schemaToExamples';
 
-export default function ExampleDataLayer({ schema }) {
-    // 1. Identify properties that need to be reset (cleared) first
-    const clearableProperties = findClearableProperties(schema || {});
+const generateCodeSnippet = (example, schema) => {
+  const clearableProperties = findClearableProperties(schema || {});
+  let codeSnippet = '';
+  const propertiesToClear = clearableProperties.filter(
+    (prop) => prop in example,
+  );
 
-    // 2. Build the main example data
-    const example = buildExampleFromSchema(schema || {});
+  if (propertiesToClear.length > 0) {
+    const resetObject = {};
+    propertiesToClear.forEach((prop) => {
+      resetObject[prop] = null;
+    });
+    codeSnippet += `window.dataLayer.push(${JSON.stringify(resetObject, null, 2)});\n`;
+  }
 
-    // 3. Construct the code snippet
-    let codeSnippet = '';
+  codeSnippet += `window.dataLayer.push(${JSON.stringify(example, null, 2)});`;
+  return codeSnippet;
+};
 
-    // Filter properties to reset to only those present in the example
-    const propertiesToClear = clearableProperties.filter(prop => prop in example);
+export default function ExampleDataLayer({ schema }) {
+  const exampleGroups = schemaToExamples(schema);
 
-    // If there are properties to reset, push them as null first
-    if (propertiesToClear.length > 0)
-    {
-        const resetObject = {};
-        propertiesToClear.forEach(prop => {
-            resetObject[prop] = null;
-        });
-        codeSnippet += `window.dataLayer.push(${JSON.stringify(resetObject, null, 2)});\n`;
-    }
+  if (!exampleGroups || exampleGroups.length === 0) {
+    return null;
+  }
 
-    // Append the main data payload
-    codeSnippet += `window.dataLayer.push(${JSON.stringify(example, null, 2)});`;
+  // Handle the simple case of a single default example with no choices
+  if (exampleGroups.length === 1 && exampleGroups[0].property === 'default') {
+    const codeSnippet = generateCodeSnippet(
+      exampleGroups[0].options[0].example,
+      schema,
+    );
+    return <CodeBlock language="javascript">{codeSnippet}</CodeBlock>;
+  }
 
-    return <CodeBlock language="javascript">{codeSnippet}</CodeBlock>
-};
+  return (
+    <>
+      {exampleGroups.map((group) => (
+        <div key={group.property} style={{ marginTop: '20px' }}>
+          <Heading as="h4">
+            <code>{group.property}</code> options:
+          </Heading>
+          <Tabs>
+            {group.options.map(({ title, example }, index) => (
+              <TabItem value={index} label={title} key={index}>
+                <CodeBlock language="javascript">
+                  {generateCodeSnippet(example, schema)}
+                </CodeBlock>
+              </TabItem>
+            ))}
+          </Tabs>
+        </div>
+      ))}
+    </>
+  );
+}
 
 export const findClearableProperties = (schema) => {
-    if (!schema || !schema.properties) return [];
+  if (!schema || !schema.properties) return [];
 
-    return Object.entries(schema.properties)
-        .filter(([key, definition]) => definition["x-gtm-clear"] === true)
-        .map(([key]) => key);
-}
+  return Object.entries(schema.properties)
+    .filter(([, definition]) => definition['x-gtm-clear'] === true)
+    .map(([key]) => key);
+};

package/components/FoldableRows.js

@@ -0,0 +1,164 @@
+import React, { useState } from 'react';
+import SchemaRows from './SchemaRows';
+import Heading from '@theme/Heading';
+import clsx from 'clsx';
+
+/**
+ * Generates inline styles for continuing hierarchical lines through a row.
+ * @param {number[]} continuingLevels - Array of ancestor levels that need lines
+ * @param {number} level - Current level of the choice
+ * @returns {object} Style object with background gradients
+ */
+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 choice rows to their parent property
+  if (level > 0) {
+    const parentPos = getLevelPosition(level - 1);
+    // Check if this position is not already in continuing levels
+    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',
+  };
+};
+
+// A clickable row that acts as a header/summary for a foldable choice
+const ChoiceRow = ({
+  title,
+  description,
+  onToggle,
+  isActive,
+  isRadio,
+  name,
+  continuingLinesStyle,
+}) => (
+  <tr className="choice-row">
+    <td colSpan={5} style={continuingLinesStyle}>
+      <label className="choice-row-header">
+        <input
+          type={isRadio ? 'radio' : 'checkbox'}
+          name={name}
+          checked={isActive}
+          onChange={onToggle}
+        />
+        <span
+          className={clsx('choice-row-toggle', isRadio ? 'radio' : 'checkbox')}
+        />
+        <strong>{title}</strong>
+      </label>
+      {description && <p className="choice-row-description">{description}</p>}
+    </td>
+  </tr>
+);
+
+/**
+ * Renders 'oneOf' and 'anyOf' choices as a set of foldable `<tr>` elements
+ * that integrate directly into the main table body.
+ */
+export default function FoldableRows({ row }) {
+  const {
+    choiceType,
+    options,
+    description,
+    name,
+    required,
+    level = 0,
+    continuingLevels = [],
+  } = row;
+  const [openOneOf, setOpenOneOf] = useState(0); // For oneOf, track the single open index
+  const [openAnyOf, setOpenAnyOf] = useState({}); // For anyOf, track each option's state
+
+  const handleAnyOfToggle = (index) => {
+    setOpenAnyOf((prev) => ({ ...prev, [index]: !prev[index] }));
+  };
+
+  const selectTitle = `Select ${
+    choiceType === 'oneOf' ? 'one' : 'any'
+  } of the following options:`;
+  const header = name ? (
+    <>
+      <strong>{name}</strong>
+      {required && <span className="required-badge">required</span>}
+      {' - '}
+      {selectTitle}
+    </>
+  ) : (
+    selectTitle
+  );
+
+  // Calculate continuing lines style for choice rows
+  const continuingLinesStyle = getContinuingLinesStyle(continuingLevels, level);
+
+  return (
+    <>
+      {/* A header row for the entire choice block */}
+      <tr>
+        <td colSpan={5} style={continuingLinesStyle}>
+          <Heading as="h4" className="choice-row-header-headline">
+            {header}
+          </Heading>
+          <p className="choice-row-header-description">{description}</p>
+        </td>
+      </tr>
+
+      {/* Render the options */}
+      {options.map((option, index) => {
+        const isActive =
+          choiceType === 'oneOf' ? openOneOf === index : !!openAnyOf[index];
+        return (
+          <React.Fragment key={option.title}>
+            <ChoiceRow
+              title={option.title}
+              description={option.description}
+              onToggle={() =>
+                choiceType === 'oneOf'
+                  ? setOpenOneOf(index)
+                  : handleAnyOfToggle(index)
+              }
+              isActive={isActive}
+              isRadio={choiceType === 'oneOf'}
+              name={choiceType === 'oneOf' ? row.title : option.title}
+              continuingLinesStyle={continuingLinesStyle}
+            />
+            {/* If the option is active, render its rows directly into the table body */}
+            {isActive && <SchemaRows tableData={option.rows} />}
+          </React.Fragment>
+        );
+      })}
+    </>
+  );
+}

package/components/PropertiesTable.js

@@ -1,14 +1,17 @@
 import React from 'react';
 import SchemaRows from './SchemaRows';
 import TableHeader from './TableHeader';
-import { getConstraints } from '../helpers/getConstraints';
+import { schemaToTableData } from '../helpers/schemaToTableData';
 
 export default function PropertiesTable({ schema }) {
+  const tableData = schemaToTableData(schema);
 
-    return <table>
-        <TableHeader />
-        <tbody>
-            <SchemaRows properties={schema.properties} requiredList={schema.required} getConstraints={getConstraints} />
-        </tbody>
+  return (
+    <table>
+      <TableHeader />
+      <tbody>
+        <SchemaRows tableData={tableData} />
+      </tbody>
     </table>
-}
+  );
+}

package/components/PropertyRow.js

@@ -1,74 +1,183 @@
 import React from 'react';
 import clsx from 'clsx';
+import CodeBlock from '@theme/CodeBlock';
 
-// Helper to format the property type
-const getPropertyType = (type) => {
-    return Array.isArray(type) ? type.join(' | ') : type;
+/**
+ * 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}
+ */
+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);
 };
 
-// Helper to format examples
-const formatExamples = (examples) => {
-    if (!examples)
-    {
-        return '';
-    }
-    return examples
-        .map((example) =>
-            typeof example === 'object' ? JSON.stringify(example) : example
-        )
-        .join(', ');
+/**
+ * Returns the container symbol for a property based on its container type.
+ * @param {string|null} containerType - 'object', 'array', or null
+ * @returns {string} The symbol to display
+ */
+const getContainerSymbol = (containerType) => {
+  if (containerType === 'object') return '{}';
+  if (containerType === 'array') return '[]';
+  return '';
 };
 
-const PropertyRow = ({ propertyKey, prop, requiredList, getConstraints }) => {
-    const isReq = requiredList.includes(propertyKey);
-    const constraints = getConstraints(prop, isReq);
+/**
+ * Renders a single property row in the schema table.
+ * 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 }) {
+  const {
+    name,
+    level,
+    required,
+    propertyType,
+    description,
+    example,
+    constraints,
+    hasChildren,
+    containerType,
+    continuingLevels = [],
+  } = row;
 
-    const childProperties = prop.properties || (prop.items && prop.items.properties);
-    const hasChildren = childProperties && Object.keys(childProperties).length > 0;
+  const indentStyle = {
+    paddingLeft: `${level * 1.25 + 0.5}rem`,
+  };
 
-    const isObject = prop.type === 'object';
-    const isArrayOfObjects = prop.type === 'array' && prop.items && prop.items.type === 'object';
+  const hasConstraints = constraints && constraints.length > 0;
+  // Set rowspan to 1 if there are no constraints.
+  const rowSpan = hasConstraints ? constraints.length : 1;
+  // Gracefully handle case with no constraints
+  const [firstConstraint, ...remainingConstraints] = hasConstraints
+    ? constraints
+    : [null];
+  const formattedExample = formatExample(example);
 
-    if ((isObject || isArrayOfObjects) && !hasChildren)
-    {
-        return null;
-    }
+  // Generate background gradients for:
+  // 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
+  //
+  // Position mapping: level N's line is at position (N * 1.25 + 0.5)rem
+  // This matches the CSS: level-1 at 0.5rem, level-2 at 1.75rem, etc.
+  const getLevelPosition = (lvl) => lvl * 1.25 + 0.5;
 
-    const numRows = Math.max(1, constraints.length);
-    const [firstConstraint, ...remainingConstraints] = constraints;
+  const allGradients = [];
+  const allSizes = [];
+  const allPositions = [];
 
-    return (
-        <React.Fragment>
-            <tr className={clsx(isReq && 'required-row')}>
-                <td rowSpan={numRows}>
-                    <strong>{propertyKey}</strong>
-                    {hasChildren && <span style={{ fontSize: '0.8em', marginLeft: '5px' }}>⤵</span>}
-                </td>
-                <td rowSpan={numRows}><code>{getPropertyType(prop.type)}</code></td>
-                <td>
-                    {firstConstraint && (
-                        <code className={clsx('constraint-code', firstConstraint === 'required' && 'required')}>
-                            {firstConstraint}
-                        </code>
-                    )}
-                </td>
-                <td rowSpan={numRows}>
-                    {formatExamples(prop.examples)}
-                </td>
-                <td rowSpan={numRows}>{prop.description || ''}</td>
-            </tr>
-
-            {remainingConstraints.map((constraint, index) => (
-                <tr className={clsx(isReq && 'required-row')} key={`${propertyKey}-constraint-${index}`}>
-                    <td>
-                        <code className={clsx('constraint-code', constraint === 'required' && 'required')}>
-                            {constraint}
-                        </code>
-                    </td>
-                </tr>
-            ))}
-        </React.Fragment>
+  // 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(
+      'linear-gradient(to bottom, transparent calc(50% + 1em), var(--ifm-table-border-color) calc(50% + 1em))',
     );
-};
+    allSizes.push('1px 100%');
+    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
+  continuingLevels
+    .filter((lvl) => lvl < level - 1)
+    .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`);
+    });
+
+  const continuingLinesStyle =
+    allGradients.length > 0
+      ? {
+          backgroundImage: allGradients.join(', '),
+          backgroundSize: allSizes.join(', '),
+          backgroundPosition: allPositions.join(', '),
+          backgroundRepeat: 'no-repeat',
+        }
+      : {};
+
+  const containerSymbol = getContainerSymbol(containerType);
+
+  return (
+    <>
+      <tr className={clsx(required && 'required-row')}>
+        <td
+          rowSpan={rowSpan}
+          style={{ ...indentStyle, ...continuingLinesStyle }}
+          className={clsx(
+            level > 0 && `level-${level}`,
+            isLastInGroup && 'is-last',
+            hasChildren && 'has-children',
+            containerType && `container-${containerType}`,
+          )}
+        >
+          <span className="property-name">
+            {containerSymbol && (
+              <span className="container-symbol">{containerSymbol}</span>
+            )}
+            <strong>{name}</strong>
+          </span>
+        </td>
+        <td rowSpan={rowSpan}>
+          <code>{propertyType}</code>
+        </td>
+
+        {/* The first constraint cell */}
+        <td>
+          {firstConstraint && (
+            <code
+              className={clsx(
+                'constraint-code',
+                firstConstraint === 'required' && 'required',
+              )}
+            >
+              {firstConstraint}
+            </code>
+          )}
+        </td>
+
+        <td rowSpan={rowSpan}>
+          {formattedExample && (
+            <CodeBlock language="json" className="schema-examples">
+              {formattedExample}
+            </CodeBlock>
+          )}
+        </td>
+        <td rowSpan={rowSpan}>{description || ''}</td>
+      </tr>
 
-export default PropertyRow;
+      {/* Render subsequent constraints in their own rows */}
+      {remainingConstraints.map((constraint) => (
+        <tr className={clsx(required && 'required-row')} key={constraint}>
+          <td>
+            <code
+              className={clsx(
+                'constraint-code',
+                constraint === 'required' && 'required',
+              )}
+            >
+              {constraint}
+            </code>
+          </td>
+        </tr>
+      ))}
+    </>
+  );
+}

package/components/SchemaJsonViewer.js

@@ -2,10 +2,10 @@ import React from 'react';
 import CodeBlock from '@theme/CodeBlock';
 
 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>
-        </details>);
+  return (
+    <details className="schema-json-viewer">
+      <summary>View Raw JSON Schema</summary>
+      <CodeBlock language="json">{JSON.stringify(schema, null, 2)}</CodeBlock>
+    </details>
+  );
 }