docusaurus-plugin-generate-schema-docs 1.5.4 → 1.7.0

package/helpers/schemaToTableData.js

@@ -1,6 +1,16 @@
 import { getConstraints } from './getConstraints';
 import { getExamples } from './example-helper';
 
+/**
+ * Computes the bracket descriptor for a new group being opened at `level`.
+ * `bracketIndex` is the total number of existing parent brackets, so each
+ * nested group gets a unique visual position on the right side.
+ */
+function computeOwnBracket(level, parentGroupBrackets) {
+  const bracketIndex = parentGroupBrackets.length;
+  return { level, bracketIndex };
+}
+
 function processOptions(
   choices,
   level,
@@ -8,6 +18,8 @@ function processOptions(
   isNestedInProperty,
   requiredArray = [],
   continuingLevels = [],
+  groupBrackets = [],
+  choiceIsLastInGroup = true,
 ) {
   return choices.map((optionSchema, index) => {
     const optionTitle = optionSchema.title || 'Option';
@@ -39,10 +51,12 @@ function processOptions(
         description: optionSchema.description,
         examples: getExamples(optionSchema),
         constraints: constraints,
-        isLastInGroup: isLastOption, // Updated: Uses the calculated flag instead of always true
+        // Keep connector lines open when the enclosing choice block isn't truly last.
+        isLastInGroup: isLastOption && choiceIsLastInGroup,
         hasChildren: false,
         containerType: null,
         continuingLevels: [...continuingLevels],
+        groupBrackets: [...groupBrackets],
       });
     } else {
       // This is a complex object within a choice
@@ -53,7 +67,8 @@ function processOptions(
         level,
         isNestedInProperty ? [] : path,
         continuingLevels,
-        isLastOption,
+        isLastOption && choiceIsLastInGroup,
+        groupBrackets,
       );
     }
 
@@ -71,6 +86,7 @@ export function schemaToTableData(
   path = [],
   parentContinuingLevels = [],
   isLastOption = true,
+  parentGroupBrackets = [],
 ) {
   const flatRows = [];
 
@@ -81,7 +97,7 @@ export function schemaToTableData(
     ) {
       return false;
     }
-    if (schemaNode.oneOf || schemaNode.anyOf) {
+    if (schemaNode.oneOf || schemaNode.anyOf || schemaNode.if) {
       return false;
     }
     if (
@@ -93,18 +109,113 @@ export function schemaToTableData(
     return Object.values(schemaNode.properties).every(isEffectivelyEmpty);
   }
 
+  function buildConditionalRow(
+    subSchema,
+    currentLevel,
+    currentPath,
+    continuingLevels,
+    currentGroupBrackets = [],
+    ownContinuingLevels,
+    conditionalIsLastInGroup = true,
+  ) {
+    // Inner rows (condition, branches) inherit the parent's continuingLevels.
+    // The immediate parent connector (currentLevel - 1) is handled by the
+    // ConditionalRows component via its ancestorLevels.push(level - 1).
+    const innerContinuingLevels = [...continuingLevels];
+
+    // Compute the bracket for this if/then/else group
+    const ownBracket = computeOwnBracket(currentLevel, currentGroupBrackets);
+    const innerGroupBrackets = [...currentGroupBrackets, ownBracket];
+
+    const conditionRows = schemaToTableData(
+      subSchema.if,
+      currentLevel,
+      currentPath,
+      innerContinuingLevels,
+      false, // branches always follow condition rows, so they are never "last"
+      innerGroupBrackets,
+    ).map((row) => ({ ...row, isCondition: true }));
+
+    const hasThen = !!subSchema.then;
+    const hasElse = !!subSchema.else;
+
+    const branches = [];
+    if (hasThen) {
+      // Then is NOT the last branch if Else exists — use innerContinuingLevels
+      // to keep the parent line flowing. If Then IS the last branch, use original.
+      const thenLevels = hasElse ? innerContinuingLevels : continuingLevels;
+      branches.push({
+        title: 'Then',
+        description: subSchema.then.description,
+        rows: schemaToTableData(
+          subSchema.then,
+          currentLevel,
+          currentPath,
+          thenLevels,
+          // Keep branch connectors open if this conditional block isn't truly last.
+          !hasElse && conditionalIsLastInGroup,
+          innerGroupBrackets,
+        ),
+      });
+    }
+    if (hasElse) {
+      // Else is always the last branch — use original continuingLevels
+      branches.push({
+        title: 'Else',
+        description: subSchema.else.description,
+        rows: schemaToTableData(
+          subSchema.else,
+          currentLevel,
+          currentPath,
+          continuingLevels,
+          conditionalIsLastInGroup,
+          innerGroupBrackets,
+        ),
+      });
+    }
+
+    // ownContinuingLevels (when provided) includes currentLevel for the row's
+    // header/toggle rendering, since sibling properties' tree lines must continue.
+    // Merge with innerContinuingLevels to also include the parent level.
+    const rowContinuingLevels = ownContinuingLevels
+      ? [...new Set([...innerContinuingLevels, ...ownContinuingLevels])]
+      : innerContinuingLevels;
+
+    flatRows.push({
+      type: 'conditional',
+      path: [...currentPath, 'if/then/else'],
+      level: currentLevel,
+      isLastInGroup: conditionalIsLastInGroup,
+      hasChildren: false,
+      containerType: null,
+      continuingLevels: [...rowContinuingLevels],
+      groupBrackets: [...currentGroupBrackets],
+      condition: {
+        title: 'If',
+        description: subSchema.if.description,
+        rows: conditionRows,
+      },
+      branches,
+    });
+  }
+
   function buildRows(
     subSchema,
     currentLevel,
     currentPath,
     requiredFromParent = [],
     continuingLevels = [],
+    currentGroupBrackets = [],
   ) {
     if (!subSchema) return;
 
     if (subSchema.properties) {
       const propKeys = Object.keys(subSchema.properties);
-      const hasSiblingChoices = !!(subSchema.oneOf || subSchema.anyOf);
+      const hasSiblingChoices = !!(
+        subSchema.oneOf ||
+        subSchema.anyOf ||
+        subSchema.if
+      );
 
       // Filter out properties that should be skipped to get accurate count
       const visiblePropKeys = propKeys.filter((name) => {
@@ -127,20 +238,35 @@ export function schemaToTableData(
         const isLast = isLastProp && (currentLevel !== level || isLastOption);
 
         const isChoiceWrapper = !!(propSchema.oneOf || propSchema.anyOf);
+        const isConditionalWrapper = !!(
+          propSchema.if &&
+          (propSchema.then || propSchema.else)
+        );
 
         // Determine if this property has children and what type
         const hasNestedProperties = !!propSchema.properties;
         const hasArrayItems =
-          propSchema.type === 'array' && !!propSchema.items?.properties;
+          propSchema.type === 'array' &&
+          !!(propSchema.items?.properties || propSchema.items?.if);
         const hasNestedChoice = isChoiceWrapper;
+        const hasNestedConditional = isConditionalWrapper;
         const hasChildren =
-          hasNestedProperties || hasArrayItems || hasNestedChoice;
+          hasNestedProperties ||
+          hasArrayItems ||
+          hasNestedChoice ||
+          hasNestedConditional;
 
         // Determine container type for the symbol
         let containerType = null;
+        const choiceOptions = propSchema.oneOf || propSchema.anyOf || [];
+        const choiceOptionsAreObjects =
+          isChoiceWrapper &&
+          choiceOptions.some((opt) => opt.type === 'object' || opt.properties);
         if (
           hasNestedProperties ||
-          (isChoiceWrapper && propSchema.type === 'object')
+          (isChoiceWrapper && propSchema.type === 'object') ||
+          (isConditionalWrapper && propSchema.type === 'object') ||
+          choiceOptionsAreObjects
         ) {
           containerType = 'object';
         } else if (hasArrayItems) {
@@ -149,24 +275,36 @@ export function schemaToTableData(
 
         // Calculate continuing levels for children
         // If this is not the last item, add current level to continuing levels for children
-        // If this IS the last item, remove the immediate parent level (currentLevel - 1) because
-        // that line stops at this item and should not continue through its children
+        // If this IS the last item, don't add currentLevel (no more siblings at this level).
+        // We keep all existing continuingLevels intact — they represent ancestor lines
+        // that must continue through all descendants regardless of last-child status.
         const childContinuingLevels = isLast
-          ? continuingLevels.filter((lvl) => lvl !== currentLevel - 1)
+          ? [...continuingLevels]
           : [...continuingLevels, currentLevel];
 
-        // This is a "simple" choice property like user_id.
-        // It gets unwrapped into a choice row directly.
-        if (
+        // A "simple" choice property like user_id: { oneOf: [{ type: "string" }, { type: "integer" }] }
+        // where the options are scalar types (no nested properties). These get unwrapped
+        // into a choice row directly without their own property row.
+        // In contrast, choice wrappers whose options are objects with properties
+        // (like contact_method) need their own property row to start a nesting level.
+        const isSimpleChoice =
           isChoiceWrapper &&
           !propSchema.properties &&
-          propSchema.type !== 'object'
-        ) {
+          propSchema.type !== 'object' &&
+          !(propSchema.oneOf || propSchema.anyOf).some((opt) => opt.properties);
+
+        if (isSimpleChoice) {
           const choiceType = propSchema.oneOf ? 'oneOf' : 'anyOf';
           const choices = propSchema[choiceType];
+          const ownBracket = computeOwnBracket(
+            currentLevel,
+            currentGroupBrackets,
+          );
+          const innerGroupBrackets = [...currentGroupBrackets, ownBracket];
           flatRows.push({
             type: 'choice',
             choiceType,
+            name,
             path: newPath,
             level: currentLevel,
             title: propSchema.title,
@@ -175,6 +313,7 @@ export function schemaToTableData(
             hasChildren: false,
             containerType: null,
             continuingLevels: [...continuingLevels],
+            groupBrackets: [...currentGroupBrackets],
             options: processOptions(
               choices,
               currentLevel,
@@ -182,6 +321,8 @@ export function schemaToTableData(
               false,
               subSchema.required || requiredFromParent,
               childContinuingLevels,
+              innerGroupBrackets,
+              isLast,
             ),
           });
         } else {
@@ -208,6 +349,7 @@ export function schemaToTableData(
             hasChildren,
             containerType,
             continuingLevels: [...continuingLevels],
+            groupBrackets: [...currentGroupBrackets],
           });
 
           if (propSchema.properties) {
@@ -217,23 +359,50 @@ export function schemaToTableData(
               newPath,
               propSchema.required,
               childContinuingLevels,
+              currentGroupBrackets,
             );
           } else if (
             propSchema.type === 'array' &&
-            propSchema.items?.properties
+            (propSchema.items?.properties || propSchema.items?.if)
           ) {
-            buildRows(
-              propSchema.items,
-              currentLevel + 1,
-              [...newPath, '[n]'],
-              propSchema.items.required,
-              childContinuingLevels,
-            );
+            if (propSchema.items.properties) {
+              buildRows(
+                propSchema.items,
+                currentLevel + 1,
+                [...newPath, '[n]'],
+                propSchema.items.required,
+                childContinuingLevels,
+                currentGroupBrackets,
+              );
+            }
+            // Handle if/then/else inside array items
+            if (
+              propSchema.items.if &&
+              (propSchema.items.then || propSchema.items.else)
+            ) {
+              buildConditionalRow(
+                propSchema.items,
+                currentLevel + 1,
+                [...newPath, '[n]'],
+                childContinuingLevels,
+                currentGroupBrackets,
+                undefined,
+                isLast,
+              );
+            }
           } else if (isChoiceWrapper) {
             // This handles the "complex" choice property like payment_method.
             // A property row has already been created above, now we add the choice row.
             const choiceType = propSchema.oneOf ? 'oneOf' : 'anyOf';
             const choices = propSchema[choiceType];
+            const complexOwnBracket = computeOwnBracket(
+              currentLevel + 1,
+              currentGroupBrackets,
+            );
+            const complexInnerBrackets = [
+              ...currentGroupBrackets,
+              complexOwnBracket,
+            ];
             flatRows.push({
               type: 'choice',
               choiceType,
@@ -245,6 +414,7 @@ export function schemaToTableData(
               hasChildren: false,
               containerType: null,
               continuingLevels: childContinuingLevels,
+              groupBrackets: [...currentGroupBrackets],
               options: processOptions(
                 choices,
                 currentLevel + 1,
@@ -252,13 +422,39 @@ export function schemaToTableData(
                 true,
                 propSchema.required,
                 childContinuingLevels,
+                complexInnerBrackets,
               ),
             });
           }
+
+          // Handle if/then/else nested inside a property without its own properties.
+          // When propSchema HAS properties, the recursive buildRows call above
+          // already handles if/then/else via the root-level check at the end of buildRows.
+          if (isConditionalWrapper && !propSchema.properties) {
+            buildConditionalRow(
+              propSchema,
+              currentLevel + 1,
+              newPath,
+              childContinuingLevels,
+              currentGroupBrackets,
+              undefined,
+              isLast,
+            );
+          }
         }
       });
     }
 
+    // When properties coexist with root-level choices or conditionals,
+    // the header/toggle rows need the tree line at currentLevel to continue.
+    // Only used for the row's own continuingLevels — NOT propagated to inner rows.
+    const hasProperties =
+      subSchema.properties && Object.keys(subSchema.properties).length > 0;
+    const ownContinuingLevels =
+      hasProperties && !continuingLevels.includes(currentLevel)
+        ? [...continuingLevels, currentLevel]
+        : [...continuingLevels];
+
     // This handles choices at the root of a schema
     const choiceType = subSchema.oneOf
       ? 'oneOf'
@@ -267,6 +463,10 @@ export function schemaToTableData(
         : null;
     if (choiceType) {
       const choices = subSchema[choiceType];
+      const ownBracket = computeOwnBracket(currentLevel, currentGroupBrackets);
+      const innerGroupBrackets = [...currentGroupBrackets, ownBracket];
+      const choiceIsLastInGroup =
+        isLastOption && !(subSchema.if && (subSchema.then || subSchema.else));
       flatRows.push({
         type: 'choice',
         choiceType,
@@ -274,10 +474,11 @@ export function schemaToTableData(
         level: currentLevel,
         title: subSchema.title,
         description: subSchema.description,
-        isLastInGroup: true,
+        isLastInGroup: choiceIsLastInGroup,
         hasChildren: false,
         containerType: null,
-        continuingLevels: [...continuingLevels],
+        continuingLevels: [...ownContinuingLevels],
+        groupBrackets: [...currentGroupBrackets],
         options: processOptions(
           choices,
           currentLevel,
@@ -285,6 +486,8 @@ export function schemaToTableData(
           false,
           subSchema.required || requiredFromParent,
           continuingLevels,
+          innerGroupBrackets,
+          choiceIsLastInGroup,
         ),
       });
     } else if (!subSchema.properties && subSchema.type) {
@@ -303,10 +506,33 @@ export function schemaToTableData(
         hasChildren: false,
         containerType: null,
         continuingLevels: [...continuingLevels],
+        groupBrackets: [...currentGroupBrackets],
       });
     }
+
+    // Handle if/then/else at the schema root (or sub-schema root)
+    if (subSchema.if && (subSchema.then || subSchema.else)) {
+      // ownContinuingLevels includes currentLevel for the row's header/toggle rendering.
+      // Inner rows (condition, branches) use the original continuingLevels.
+      buildConditionalRow(
+        subSchema,
+        currentLevel,
+        currentPath,
+        continuingLevels,
+        currentGroupBrackets,
+        hasProperties ? [...ownContinuingLevels] : undefined,
+        isLastOption,
+      );
+    }
   }
 
-  buildRows(schema, level, path, schema.required, parentContinuingLevels);
+  buildRows(
+    schema,
+    level,
+    path,
+    schema.required,
+    parentContinuingLevels,
+    parentGroupBrackets,
+  );
   return flatRows;
 }

package/helpers/update-schema-ids.js

@@ -28,8 +28,8 @@ export default function updateSchemaIds(siteDir, url, version = null) {
     ? [version]
     : JSON.parse(fs.readFileSync(versionsJsonPath, 'utf8'));
 
-  for (const version of versions) {
-    const schemaDir = path.join(siteDir, 'static/schemas', version);
+  for (const v of versions) {
+    const schemaDir = path.join(siteDir, 'static/schemas', v);
     if (!fs.existsSync(schemaDir)) {
       continue;
     }
@@ -41,7 +41,7 @@ export default function updateSchemaIds(siteDir, url, version = null) {
       const relativePath = path.relative(path.join(siteDir, 'static'), file);
       schema.$id = `${baseUrl}/${relativePath.replace(/\\/g, '/')}`;
       fs.writeFileSync(file, JSON.stringify(schema, null, 2));
-      console.log(`Updated $id for ${file} in version ${version}`);
+      console.log(`Updated $id for ${file} in version ${v}`);
     }
   }
 }

package/helpers/validator.js

@@ -26,31 +26,23 @@ function createAjvInstance(schemas, mainSchema, schemaPath) {
     return JSON.parse(schemaContent);
   };
 
-  const options = { allErrors: true, schemas: schemas };
+  const options = {
+    allErrors: true,
+    schemas: schemas,
+    strict: false,
+    loadSchema,
+  };
 
   let ajv;
   if (schemaVersion?.includes('2020-12')) {
-    options.strict = false;
-    options.loadSchema = loadSchema;
     ajv = new Ajv2020(options);
   } else if (schemaVersion?.includes('2019-09')) {
-    options.strict = false;
-    options.loadSchema = loadSchema;
     ajv = new Ajv2019(options);
-  } else if (schemaVersion?.includes('draft-07')) {
-    options.strict = false;
-    options.loadSchema = loadSchema;
-    ajv = new Ajv(options);
-  } else if (schemaVersion?.includes('draft-06')) {
-    options.strict = false;
-    options.loadSchema = loadSchema;
-    ajv = new Ajv(options);
   } else if (schemaVersion?.includes('draft-04')) {
     ajv = new AjvDraft4();
     schemas.forEach((s) => ajv.addSchema(s));
   } else {
-    options.strict = false;
-    options.loadSchema = loadSchema;
+    // covers draft-07, draft-06, and unknown versions
     ajv = new Ajv(options);
   }
 
@@ -71,10 +63,6 @@ function createAjvInstance(schemas, mainSchema, schemaPath) {
  * @returns {function(object): {valid: boolean, errors: object[]}} A function that takes data and returns a validation result.
  */
 export async function createValidator(schemas, mainSchema, schemaPath) {
-  if (!mainSchema) {
-    mainSchema = schemas;
-    schemas = [mainSchema];
-  }
   const ajv = createAjvInstance(schemas, mainSchema, schemaPath);
 
   let validate;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-generate-schema-docs",
-  "version": "1.5.4",
+  "version": "1.7.0",
   "description": "Docusaurus plugin to generate documentation from JSON schemas.",
   "main": "index.js",
   "license": "MIT",
@@ -12,7 +12,8 @@
     "@apidevtools/json-schema-ref-parser": "^15.1.3",
     "json-schema-merge-allof": "^0.8.1",
     "ajv": "^8.17.1",
-    "ajv-draft-04": "^1.0.0"
+    "ajv-draft-04": "^1.0.0",
+    "ajv-keywords": "^5.1.0"
   },
   "publishConfig": {
     "access": "public",