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

package/components/ConditionalRows.js

@@ -0,0 +1,156 @@
+import React, { useState, useId } from 'react';
+import SchemaRows from './SchemaRows';
+import clsx from 'clsx';
+import {
+  getContinuingLinesStyle,
+  getBracketLinesStyle,
+  mergeBackgroundStyles,
+} from '../helpers/continuingLinesStyle';
+
+/**
+ * Renders 'if/then/else' conditionals as a set of `<tr>` elements
+ * that integrate directly into the main table body.
+ *
+ * Structure:
+ * 1. Condition (if) rows: always visible, info-styled
+ * 2. Branch toggles (then/else): radio-style, foldable
+ */
+export default function ConditionalRows({
+  row,
+  bracketEnds: parentBracketEnds,
+}) {
+  const {
+    condition,
+    branches,
+    level = 0,
+    continuingLevels = [],
+    groupBrackets = [],
+  } = row;
+  const [activeBranch, setActiveBranch] = useState(0);
+  const radioGroupId = useId();
+
+  // Compute this group's own bracket and combine with any parent brackets.
+  // bracketIndex = total number of existing brackets, so each group gets a unique position.
+  const ownBracket = {
+    level,
+    bracketIndex: groupBrackets.length,
+  };
+  const allBrackets = [...groupBrackets, ownBracket];
+
+  // colSpan=5 rows need continuing ancestor lines to pass through (for visual
+  // continuity). They don't have ::before/::after connectors, so we draw all
+  // ancestor lines via background gradients. We always include the immediate
+  // parent level (level-1) so the parent-to-child connector passes through.
+  // Only draw ancestor lines where the next level up is also continuing;
+  // this matches PropertyRow's filter to avoid stray lines at a parent's
+  // corner connector when that parent is the last in its group.
+  const ancestorLevels = continuingLevels.filter(
+    (lvl) => lvl < level && continuingLevels.includes(lvl + 1),
+  );
+  // Always include the immediate parent level so the parent-to-child
+  // connector passes through these full-width rows.
+  if (level > 0 && !ancestorLevels.includes(level - 1)) {
+    ancestorLevels.push(level - 1);
+  }
+  const treePassthrough = getContinuingLinesStyle(ancestorLevels, 0);
+  const indent = { paddingLeft: `${level * 1.25 + 0.5}rem` };
+
+  // If header: top cap on ownBracket
+  const headerBracketStyle = getBracketLinesStyle(allBrackets, {
+    starting: [ownBracket],
+  });
+  const headerMerged = mergeBackgroundStyles(
+    treePassthrough,
+    headerBracketStyle,
+  );
+  const headerStyle = { ...headerMerged, ...indent, paddingTop: '0.5rem' };
+
+  // Middle rows (branch toggles): no caps
+  const middleBracketStyle = getBracketLinesStyle(allBrackets);
+  const middleMerged = mergeBackgroundStyles(
+    treePassthrough,
+    middleBracketStyle,
+  );
+  const middleStyle = { ...middleMerged, ...indent };
+
+  // Last branch toggle when content is NOT shown: bottom cap (+ parent ends)
+  const allEndings = [ownBracket, ...(parentBracketEnds || [])];
+  const lastToggleBracketStyle = getBracketLinesStyle(allBrackets, {
+    ending: allEndings,
+  });
+  const lastToggleMerged = mergeBackgroundStyles(
+    treePassthrough,
+    lastToggleBracketStyle,
+  );
+  const lastToggleStyle = {
+    ...lastToggleMerged,
+    ...indent,
+    paddingBottom: '0.5rem',
+  };
+
+  return (
+    <>
+      {/* Condition (if) section - always visible */}
+      <tr className="conditional-condition-header">
+        <td colSpan={5} style={headerStyle}>
+          <span className="conditional-condition-label">
+            <span className="conditional-info-icon-wrapper">
+              <span className="conditional-info-icon">i</span>
+              <span className="conditional-info-tooltip">
+                The properties below define the condition. When the condition is
+                met, the &ldquo;Then&rdquo; branch applies. Otherwise, the
+                &ldquo;Else&rdquo; branch applies.
+              </span>
+            </span>
+            <strong>If</strong>
+          </span>
+          {condition.description && (
+            <p className="conditional-condition-description">
+              {condition.description}
+            </p>
+          )}
+        </td>
+      </tr>
+      <SchemaRows tableData={condition.rows} />
+
+      {/* Branch toggles (then / else) */}
+      {branches.map((branch, index) => {
+        const isActive = activeBranch === index;
+        const isLastBranch = index === branches.length - 1;
+        const toggleStyle =
+          isLastBranch && !isActive ? lastToggleStyle : middleStyle;
+        return (
+          <React.Fragment key={branch.title}>
+            <tr className="choice-row">
+              <td colSpan={5} style={toggleStyle}>
+                <label className="choice-row-header">
+                  <input
+                    type="radio"
+                    name={`conditional-${radioGroupId}`}
+                    checked={isActive}
+                    onChange={() => setActiveBranch(index)}
+                  />
+                  <span className={clsx('choice-row-toggle', 'radio')} />
+                  <strong>{branch.title}</strong>
+                </label>
+                {branch.description && (
+                  <p className="choice-row-description">{branch.description}</p>
+                )}
+              </td>
+            </tr>
+            {isActive && (
+              <SchemaRows
+                tableData={branch.rows}
+                bracketEnds={
+                  isLastBranch
+                    ? [ownBracket, ...(parentBracketEnds || [])]
+                    : undefined
+                }
+              />
+            )}
+          </React.Fragment>
+        );
+      })}
+    </>
+  );
+}

package/components/FoldableRows.js

@@ -1,60 +1,12 @@
-import React, { useState } from 'react';
+import React, { useState, useId } 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',
-  };
-};
+import {
+  getContinuingLinesStyle,
+  getBracketLinesStyle,
+  mergeBackgroundStyles,
+} from '../helpers/continuingLinesStyle';
 
 // A clickable row that acts as a header/summary for a foldable choice
 const ChoiceRow = ({
@@ -89,7 +41,7 @@ const ChoiceRow = ({
  * 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 }) {
+export default function FoldableRows({ row, bracketEnds: parentBracketEnds }) {
   const {
     choiceType,
     options,
@@ -98,7 +50,9 @@ export default function FoldableRows({ row }) {
     required,
     level = 0,
     continuingLevels = [],
+    groupBrackets = [],
   } = row;
+  const radioGroupId = useId();
   const [openOneOf, setOpenOneOf] = useState(0); // For oneOf, track the single open index
   const [openAnyOf, setOpenAnyOf] = useState({}); // For anyOf, track each option's state
 
@@ -120,14 +74,70 @@ export default function FoldableRows({ row }) {
     selectTitle
   );
 
-  // Calculate continuing lines style for choice rows
-  const continuingLinesStyle = getContinuingLinesStyle(continuingLevels, level);
+  // Compute this group's own bracket and combine with any parent brackets.
+  // bracketIndex = total number of existing brackets, so each group gets a unique position.
+  const ownBracket = {
+    level,
+    bracketIndex: groupBrackets.length,
+  };
+  const allBrackets = [...groupBrackets, ownBracket];
+
+  // colSpan=5 rows need continuing ancestor lines to pass through (for visual
+  // continuity). They don't have ::before/::after connectors, so we draw all
+  // ancestor lines via background gradients. We always include the immediate
+  // parent level (level-1) so the parent-to-child connector passes through.
+  // Only draw ancestor lines where the next level up is also continuing;
+  // this matches PropertyRow's filter to avoid stray lines at a parent's
+  // corner connector when that parent is the last in its group.
+  const ancestorLevels = continuingLevels.filter(
+    (lvl) => lvl < level && continuingLevels.includes(lvl + 1),
+  );
+  // Always include the immediate parent level so the parent-to-child
+  // connector passes through these full-width rows.
+  if (level > 0 && !ancestorLevels.includes(level - 1)) {
+    ancestorLevels.push(level - 1);
+  }
+  const treePassthrough = getContinuingLinesStyle(ancestorLevels, 0);
+  const indent = { paddingLeft: `${level * 1.25 + 0.5}rem` };
+
+  // Header row: top cap on the ownBracket
+  const headerBracketStyle = getBracketLinesStyle(allBrackets, {
+    starting: [ownBracket],
+  });
+  const headerMerged = mergeBackgroundStyles(
+    treePassthrough,
+    headerBracketStyle,
+  );
+  const headerStyle = { ...headerMerged, ...indent, paddingTop: '0.5rem' };
+
+  // Middle rows (option toggles): no caps
+  const middleBracketStyle = getBracketLinesStyle(allBrackets);
+  const middleMerged = mergeBackgroundStyles(
+    treePassthrough,
+    middleBracketStyle,
+  );
+  const middleStyle = { ...middleMerged, ...indent };
+
+  // Last toggle when its content is NOT shown: bottom cap on ownBracket (+ parent ends)
+  const allEndings = [ownBracket, ...(parentBracketEnds || [])];
+  const lastToggleBracketStyle = getBracketLinesStyle(allBrackets, {
+    ending: allEndings,
+  });
+  const lastToggleMerged = mergeBackgroundStyles(
+    treePassthrough,
+    lastToggleBracketStyle,
+  );
+  const lastToggleStyle = {
+    ...lastToggleMerged,
+    ...indent,
+    paddingBottom: '0.5rem',
+  };
 
   return (
     <>
       {/* A header row for the entire choice block */}
       <tr>
-        <td colSpan={5} style={continuingLinesStyle}>
+        <td colSpan={5} style={headerStyle}>
           <Heading as="h4" className="choice-row-header-headline">
             {header}
           </Heading>
@@ -139,6 +149,10 @@ export default function FoldableRows({ row }) {
       {options.map((option, index) => {
         const isActive =
           choiceType === 'oneOf' ? openOneOf === index : !!openAnyOf[index];
+        const isLastOption = index === options.length - 1;
+        // Last toggle needs bottom cap when its content is hidden
+        const toggleStyle =
+          isLastOption && !isActive ? lastToggleStyle : middleStyle;
         return (
           <React.Fragment key={option.title}>
             <ChoiceRow
@@ -151,11 +165,24 @@ export default function FoldableRows({ row }) {
               }
               isActive={isActive}
               isRadio={choiceType === 'oneOf'}
-              name={choiceType === 'oneOf' ? row.title : option.title}
-              continuingLinesStyle={continuingLinesStyle}
+              name={
+                choiceType === 'oneOf'
+                  ? `oneOf-${radioGroupId}`
+                  : `anyOf-${option.title}-${radioGroupId}`
+              }
+              continuingLinesStyle={toggleStyle}
             />
             {/* If the option is active, render its rows directly into the table body */}
-            {isActive && <SchemaRows tableData={option.rows} />}
+            {isActive && (
+              <SchemaRows
+                tableData={option.rows}
+                bracketEnds={
+                  isLastOption
+                    ? [ownBracket, ...(parentBracketEnds || [])]
+                    : undefined
+                }
+              />
+            )}
           </React.Fragment>
         );
       })}

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}
+        />
       );
     }