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

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,19 +1,17 @@
+import React from 'react';
 import SchemaRows from './SchemaRows';
+import TableHeader from './TableHeader';
+import { schemaToTableData } from '../helpers/schemaToTableData';
 
 export default function PropertiesTable({ schema }) {
+  const tableData = schemaToTableData(schema);
 
-    return <table>
-        <thead>
-            <tr>
-                <th width="20%">Property</th>
-                <th width="15%">Type</th>
-                <th width="10%">Req</th>
-                <th with="15%">Examples</th>
-                <th>Description</th>
-            </tr>
-        </thead>
-        <tbody>
-            <SchemaRows properties={schema.properties} requiredList={schema.required} />
-        </tbody>
+  return (
+    <table>
+      <TableHeader />
+      <tbody>
+        <SchemaRows tableData={tableData} />
+      </tbody>
     </table>
-}
+  );
+}

package/components/PropertyRow.js

@@ -0,0 +1,183 @@
+import React from 'react';
+import clsx from 'clsx';
+import CodeBlock from '@theme/CodeBlock';
+
+/**
+ * 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);
+};
+
+/**
+ * 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 '';
+};
+
+/**
+ * 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 indentStyle = {
+    paddingLeft: `${level * 1.25 + 0.5}rem`,
+  };
+
+  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);
+
+  // 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 allGradients = [];
+  const allSizes = [];
+  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(
+      '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>
+
+      {/* 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

@@ -1,10 +1,11 @@
+import React from 'react';
 import CodeBlock from '@theme/CodeBlock';
 
 export default function SchemaJsonViewer({ schema }) {
-
-    return (
-        <details>
-            <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>
+  );
+}

package/components/SchemaRows.css

@@ -0,0 +1,250 @@
+.required-row {
+  background-color: rgba(var(--ifm-color-danger-rgb), 0.05);
+}
+
+.constraint-code {
+  white-space: pre-wrap;
+  margin-right: 4px;
+  display: inline-block;
+  margin-bottom: 4px;
+}
+
+.constraint-code.required {
+  font-weight: bold;
+  color: var(--ifm-color-danger-dark);
+  background-color: var(--ifm-color-danger-lightest);
+  padding: 2px 4px;
+  border-radius: 4px;
+}
+
+.nested-table-container {
+  padding-left: 1.25rem;
+  border-left: 0.25rem solid var(--ifm-table-border-color);
+}
+
+.schema-json-viewer {
+  margin-bottom: 1em;
+}
+
+/* --- Property Name and Container Symbol Styles --- */
+
+.property-name {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 4px;
+}
+
+.container-symbol {
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.9em;
+  color: var(--ifm-color-emphasis-600);
+  font-weight: bold;
+  margin-left: -0.55em;
+}
+
+/* --- Organigram Connector Line Styles --- */
+
+/*
+ * Strategy:
+ * - ::before = vertical line from parent (top to bottom, or top to 50% for last items)
+ * - ::after = horizontal connector (from vertical line to property name)
+ * - background-image = parent-to-child lines (from 50% down) + continuing ancestor lines
+ */
+
+/* Base positioning */
+td[class*='level-'],
+td.has-children {
+  position: relative;
+}
+
+/*
+ * VERTICAL LINE (::before)
+ * Connects this row to its parent and siblings.
+ * Runs from top to bottom (or to 50% for last items in group).
+ */
+td[class*='level-']::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 0;
+  border-left: 1px solid var(--ifm-table-border-color);
+}
+
+/* Last items: stop vertical line at middle */
+td.is-last[class*='level-']::before {
+  bottom: 50%;
+}
+
+/*
+ * HORIZONTAL CONNECTOR (::after)
+ * Connects vertical line to the property name.
+ */
+td[class*='level-']::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  height: 0;
+  width: 0.75rem;
+  border-bottom: 1px solid var(--ifm-table-border-color);
+}
+
+/* --- Level-based positioning --- */
+
+td.level-1::before,
+td.level-1::after {
+  left: 0.5rem;
+}
+
+td.level-2::before,
+td.level-2::after {
+  left: 1.75rem;
+}
+
+td.level-3::before,
+td.level-3::after {
+  left: 3rem;
+}
+
+td.level-4::before,
+td.level-4::after {
+  left: 4.25rem;
+}
+
+td.level-5::before,
+td.level-5::after {
+  left: 5.5rem;
+}
+
+td.level-6::before,
+td.level-6::after {
+  left: 6.75rem;
+}
+
+/*
+ * Note: Parent-to-child lines and continuing ancestor lines are now
+ * handled via inline styles in PropertyRow.js using background gradients.
+ * This allows dynamic combination of multiple line levels.
+ */
+
+/* --- Choice Row Styles --- */
+
+.choice-row {
+  background-color: var(--ifm-table-stripe-background);
+}
+
+.choice-row:hover {
+  background-color: var(--ifm-hover-overlay);
+}
+
+.choice-row-header {
+  position: relative;
+  display: flex;
+  align-items: center;
+  cursor: pointer;
+}
+
+.choice-row-header input {
+  position: absolute;
+  opacity: 0;
+  width: 100%;
+  height: 100%;
+  cursor: pointer;
+}
+
+.choice-row-description {
+  margin-left: 28px;
+  font-size: 0.9em;
+  color: var(--ifm-color-secondary-darkest);
+}
+.choice-row-header-description {
+  font-size: 0.9em;
+  color: var(--ifm-color-secondary-darkest);
+}
+
+.choice-row-header-headline {
+  margin-bottom: 0px;
+}
+
+.choice-row-toggle {
+  display: inline-block;
+  width: 1rem;
+  height: 1rem;
+  margin-right: 0.75rem;
+  border: 1px solid var(--ifm-color-emphasis-400);
+  flex-shrink: 0;
+  position: relative;
+}
+
+.choice-row-toggle.radio {
+  border-radius: 50%;
+}
+
+.choice-row-toggle.checkbox {
+  border-radius: 0.25rem;
+}
+
+.choice-row-toggle.checkbox::after {
+  content: '';
+  position: absolute;
+  display: none;
+}
+
+.choice-row-header input:checked + .choice-row-toggle.radio {
+  border-color: var(--ifm-color-primary-dark);
+}
+
+.choice-row-toggle.radio::after {
+  content: '';
+  position: absolute;
+  display: none;
+  border-radius: 50%;
+  background-color: var(--ifm-color-primary);
+  width: 0.5em;
+  height: 0.5em;
+  left: 22%;
+  top: 22%;
+}
+
+.choice-row-header input:checked + .choice-row-toggle.radio::after {
+  display: block;
+}
+
+.choice-row-header input:checked + .choice-row-toggle.checkbox {
+  border-color: var(--ifm-color-primary-dark);
+}
+
+.choice-row-header input:checked + .choice-row-toggle.checkbox::after {
+  display: block;
+  left: 0.29em;
+  top: 0.125rem;
+  width: 0.1875rem;
+  height: 0.4375rem;
+  border: solid var(--ifm-color-primary);
+  border-width: 0 0.125rem 0.125rem 0;
+  transform: rotate(45deg);
+}
+
+/* --- Example CodeBlock Styles --- */
+
+.schema-examples {
+  margin: 0;
+  font-size: 0.85em;
+  white-space: pre-wrap;
+  /* Override theme defaults to make it blend into the table cell */
+  background-color: transparent !important;
+  box-shadow: none !important;
+  border: none !important;
+}
+
+.schema-examples pre,
+.schema-examples code {
+  margin: 0 !important;
+  padding: 0 !important;
+  background-color: transparent !important;
+}
+
+/* Hide the copy button within the examples code block */
+.schema-examples button {
+  display: none;
+}