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

package/__tests__/__fixtures__/static/schemas/conditional-event.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracking-docs-demo.buchert.digital/schemas/events/conditional-event.json",
+  "title": "Conditional Event",
+  "description": "An event with conditional properties based on country.",
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "const": "form_submit"
+    },
+    "country": {
+      "type": "string",
+      "description": "The user's country.",
+      "enum": ["US", "CA"],
+      "examples": ["US"]
+    }
+  },
+  "required": ["event", "country"],
+  "if": {
+    "properties": {
+      "country": { "const": "US" }
+    },
+    "required": ["country"]
+  },
+  "then": {
+    "properties": {
+      "postal_code": {
+        "type": "string",
+        "description": "US ZIP code format.",
+        "pattern": "[0-9]{5}",
+        "examples": ["90210"]
+      },
+      "state": {
+        "type": "string",
+        "description": "US state abbreviation.",
+        "examples": ["CA"]
+      }
+    },
+    "required": ["postal_code"]
+  },
+  "else": {
+    "properties": {
+      "postal_code": {
+        "type": "string",
+        "description": "Canadian postal code format.",
+        "pattern": "[A-Z][0-9][A-Z] [0-9][A-Z][0-9]",
+        "examples": ["K1A 0B1"]
+      }
+    }
+  }
+}

package/__tests__/__fixtures__/static/schemas/nested-conditional-event.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracking-docs-demo.buchert.digital/schemas/events/nested-conditional-event.json",
+  "title": "Nested Conditional Event",
+  "description": "An event with conditional properties nested inside a property.",
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "const": "order_placed"
+    },
+    "shipping": {
+      "type": "object",
+      "description": "Shipping details.",
+      "properties": {
+        "method": {
+          "type": "string",
+          "description": "The shipping method.",
+          "examples": ["express"]
+        }
+      },
+      "required": ["method"],
+      "if": {
+        "properties": {
+          "method": { "const": "express" }
+        },
+        "required": ["method"]
+      },
+      "then": {
+        "properties": {
+          "priority_level": {
+            "type": "string",
+            "description": "Express priority level.",
+            "examples": ["high"]
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "estimated_days": {
+            "type": "integer",
+            "description": "Estimated delivery days.",
+            "examples": [5]
+          }
+        }
+      }
+    }
+  },
+  "required": ["event", "shipping"]
+}

package/__tests__/__snapshots__/generateEventDocs.anchor.test.js.snap

@@ -4,6 +4,7 @@ exports[`generateEventDocs (oneOf with $anchor) should generate documentation us
 "---
 title: Parent Event Anchor
 description: "This is a parent event with oneOf."
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json
 ---
 import SchemaJsonViewer from '@theme/SchemaJsonViewer';
 
@@ -25,7 +26,7 @@ exports[`generateEventDocs (oneOf with $anchor) should generate documentation us
 title: Child Event Anchor
 description: "This is a child event with an anchor."
 sidebar_label: Child Event Anchor
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/docs/parent-event-anchor/01-child-event-with-anchor.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';
@@ -54,7 +55,7 @@ exports[`generateEventDocs (oneOf with $anchor) should generate documentation us
 title: Child Event Title
 description: "This is a child event with only a title."
 sidebar_label: Child Event Title
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/docs/parent-event-anchor/02-child-event-title.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';

package/__tests__/__snapshots__/generateEventDocs.nested.test.js.snap

@@ -4,6 +4,7 @@ exports[`generateEventDocs (nested oneOf) should generate nested documentation c
 "---
 title: Parent Event
 description: "undefined"
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/parent-event.json
 ---
 import SchemaJsonViewer from '@theme/SchemaJsonViewer';
 
@@ -23,6 +24,7 @@ exports[`generateEventDocs (nested oneOf) should generate nested documentation c
 "---
 title: Child Event
 description: "undefined"
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json
 ---
 import SchemaJsonViewer from '@theme/SchemaJsonViewer';
 
@@ -44,7 +46,7 @@ exports[`generateEventDocs (nested oneOf) should generate nested documentation c
 title: Grandchild A
 description: undefined
 sidebar_label: Grandchild A
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/docs/parent-event/01-child-event/01-grandchild-a.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';
@@ -73,7 +75,7 @@ exports[`generateEventDocs (nested oneOf) should generate nested documentation c
 title: Grandchild B
 description: undefined
 sidebar_label: Grandchild B
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/docs/parent-event/01-child-event/02-grandchild-b.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';

package/__tests__/__snapshots__/generateEventDocs.test.js.snap

@@ -91,6 +91,7 @@ exports[`generateEventDocs (non-versioned) should generate documentation correct
 "---
 title: Root Choice Event
 description: "An example event that has oneOf at the root level."
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/static/schemas/root-choice-event.json
 ---
 import SchemaJsonViewer from '@theme/SchemaJsonViewer';
 
@@ -112,7 +113,7 @@ exports[`generateEventDocs (non-versioned) should generate documentation correct
 title: Option A
 description: "An example event that has oneOf at the root level."
 sidebar_label: Option A
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/docs/root-choice-event/01-option-a.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/static/schemas/root-choice-event.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';
@@ -141,7 +142,7 @@ exports[`generateEventDocs (non-versioned) should generate documentation correct
 title: Option B
 description: "An example event that has oneOf at the root level."
 sidebar_label: Option B
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/docs/root-choice-event/02-option-b.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/static/schemas/root-choice-event.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';

package/__tests__/components/ConditionalRows.test.js

@@ -0,0 +1,150 @@
+import '@testing-library/jest-dom';
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import ConditionalRows from '../../components/ConditionalRows';
+
+jest.mock('../../components/SchemaRows', () => {
+  const MockSchemaRows = (props) => (
+    <tr data-testid="schema-rows">
+      <td>{JSON.stringify(props.tableData)}</td>
+    </tr>
+  );
+  MockSchemaRows.displayName = 'MockSchemaRows';
+  return MockSchemaRows;
+});
+
+describe('ConditionalRows', () => {
+  const conditionalRow = {
+    type: 'conditional',
+    path: ['if/then/else'],
+    level: 0,
+    continuingLevels: [],
+    condition: {
+      title: 'If',
+      description: 'When country is US',
+      rows: [{ name: 'country', isCondition: true }],
+    },
+    branches: [
+      {
+        title: 'Then',
+        description: 'US-specific fields',
+        rows: [{ name: 'postal_code' }],
+      },
+      {
+        title: 'Else',
+        description: 'Non-US fields',
+        rows: [{ name: 'province' }],
+      },
+    ],
+  };
+
+  it('renders condition (if) rows always visible', () => {
+    render(
+      <table>
+        <tbody>
+          <ConditionalRows row={conditionalRow} />
+        </tbody>
+      </table>,
+    );
+
+    expect(screen.getByText('If')).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        JSON.stringify([{ name: 'country', isCondition: true }]),
+      ),
+    ).toBeInTheDocument();
+  });
+
+  it('shows Then branch by default', () => {
+    render(
+      <table>
+        <tbody>
+          <ConditionalRows row={conditionalRow} />
+        </tbody>
+      </table>,
+    );
+
+    expect(
+      screen.getByText(JSON.stringify([{ name: 'postal_code' }])),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(JSON.stringify([{ name: 'province' }])),
+    ).not.toBeInTheDocument();
+  });
+
+  it('switches to Else branch when clicked', () => {
+    render(
+      <table>
+        <tbody>
+          <ConditionalRows row={conditionalRow} />
+        </tbody>
+      </table>,
+    );
+
+    // Click the Else toggle
+    fireEvent.click(screen.getByText('Else'));
+
+    // Now Else should be visible and Then should be hidden
+    expect(
+      screen.queryByText(JSON.stringify([{ name: 'postal_code' }])),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByText(JSON.stringify([{ name: 'province' }])),
+    ).toBeInTheDocument();
+  });
+
+  it('renders condition description when present', () => {
+    render(
+      <table>
+        <tbody>
+          <ConditionalRows row={conditionalRow} />
+        </tbody>
+      </table>,
+    );
+
+    expect(screen.getByText('When country is US')).toBeInTheDocument();
+  });
+
+  it('applies correct indentation for nested levels', () => {
+    const nestedRow = {
+      ...conditionalRow,
+      level: 2,
+      continuingLevels: [0],
+    };
+
+    const { container } = render(
+      <table>
+        <tbody>
+          <ConditionalRows row={nestedRow} />
+        </tbody>
+      </table>,
+    );
+
+    const cells = container.querySelectorAll('td[colspan="5"]');
+    // level 2: 2 * 1.25 + 0.5 = 3rem
+    cells.forEach((cell) => {
+      expect(cell.style.paddingLeft).toBe('3rem');
+    });
+  });
+
+  it('handles conditional with only Then branch (no Else)', () => {
+    const rowWithoutElse = {
+      ...conditionalRow,
+      branches: [conditionalRow.branches[0]],
+    };
+
+    render(
+      <table>
+        <tbody>
+          <ConditionalRows row={rowWithoutElse} />
+        </tbody>
+      </table>,
+    );
+
+    expect(screen.getByText('Then')).toBeInTheDocument();
+    expect(screen.queryByText('Else')).not.toBeInTheDocument();
+    expect(
+      screen.getByText(JSON.stringify([{ name: 'postal_code' }])),
+    ).toBeInTheDocument();
+  });
+});

package/__tests__/components/ConnectorLines.visualRegression.test.js

@@ -0,0 +1,93 @@
+import '@testing-library/jest-dom';
+import React from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import FoldableRows from '../../components/FoldableRows';
+import ConditionalRows from '../../components/ConditionalRows';
+import { schemaToTableData } from '../../helpers/schemaToTableData';
+import battleTestSchema from '../__fixtures__/static/schemas/battle-test-event.json';
+
+const renderInTable = (ui) =>
+  render(
+    <table>
+      <tbody>{ui}</tbody>
+    </table>,
+  );
+
+const getPropertyCellByName = (container, name) => {
+  const strongEls = Array.from(
+    container.querySelectorAll('span.property-name > strong'),
+  );
+  const strong = strongEls.find((el) => el.textContent === name);
+  return strong?.closest('td');
+};
+
+describe('connector lines visual regressions', () => {
+  const rows = schemaToTableData(battleTestSchema);
+
+  it('keeps user_id option row open when user conditional follows', () => {
+    const userIdChoice = rows.find(
+      (row) => row.type === 'choice' && row.name === 'user_id',
+    );
+
+    const { container } = renderInTable(<FoldableRows row={userIdChoice} />);
+    fireEvent.click(screen.getByText('Integer ID'));
+
+    const userIdCell = getPropertyCellByName(container, 'user_id');
+    expect(userIdCell).toBeInTheDocument();
+    expect(userIdCell).not.toHaveClass('is-last');
+    expect(userIdCell.outerHTML).toMatchSnapshot();
+  });
+
+  it('keeps wallet_provider option row open when wallet_email follows', () => {
+    const paymentChoice = rows.find(
+      (row) =>
+        row.type === 'choice' &&
+        row.path[0] === 'payment' &&
+        row.choiceType === 'anyOf',
+    );
+    const digitalWallet = paymentChoice.options.find(
+      (option) => option.title === 'Digital Wallet',
+    );
+    const walletProviderChoice = digitalWallet.rows.find(
+      (row) => row.type === 'choice' && row.name === 'wallet_provider',
+    );
+
+    const { container } = renderInTable(
+      <FoldableRows row={walletProviderChoice} />,
+    );
+    fireEvent.click(screen.getByText('Custom Provider'));
+
+    const walletProviderCell = getPropertyCellByName(
+      container,
+      'wallet_provider',
+    );
+    expect(walletProviderCell).toBeInTheDocument();
+    expect(walletProviderCell).not.toHaveClass('is-last');
+    expect(walletProviderCell.outerHTML).toMatchSnapshot();
+  });
+
+  it('keeps cvv row open when payment choice has following options', () => {
+    const paymentChoice = rows.find(
+      (row) =>
+        row.type === 'choice' &&
+        row.path[0] === 'payment' &&
+        row.choiceType === 'anyOf',
+    );
+    const creditCard = paymentChoice.options.find(
+      (option) => option.title === 'Credit Card',
+    );
+    const cardConditional = creditCard.rows.find(
+      (row) => row.type === 'conditional',
+    );
+
+    const { container } = renderInTable(
+      <ConditionalRows row={cardConditional} />,
+    );
+    fireEvent.click(screen.getByText('Else'));
+
+    const cvvCell = getPropertyCellByName(container, 'cvv');
+    expect(cvvCell).toBeInTheDocument();
+    expect(cvvCell).not.toHaveClass('is-last');
+    expect(cvvCell.outerHTML).toMatchSnapshot();
+  });
+});

package/__tests__/components/FoldableRows.test.js

@@ -233,7 +233,7 @@ describe('FoldableRows', () => {
       });
     });
 
-    it('has no background-image for root level choices with no continuing levels', () => {
+    it('has a bracket gradient for root level choices with no continuing levels', () => {
       const rootLevelRow = {
         type: 'choice',
         choiceType: 'oneOf',
@@ -241,6 +241,7 @@ describe('FoldableRows', () => {
         level: 0,
         description: 'Root level choice',
         continuingLevels: [],
+        groupBrackets: [],
         options: [
           {
             title: 'Option A',
@@ -257,9 +258,10 @@ describe('FoldableRows', () => {
         </table>,
       );
 
+      // Root-level choice rows get a bracket gradient even without tree-line continuing levels
       const cells = container.querySelectorAll('td[colspan="5"]');
       cells.forEach((cell) => {
-        expect(cell.style.backgroundImage).toBe('');
+        expect(cell.style.backgroundImage).toContain('linear-gradient');
       });
     });
 
@@ -290,9 +292,10 @@ describe('FoldableRows', () => {
       const cells = container.querySelectorAll('td[colspan="5"]');
       cells.forEach((cell) => {
         const bgImage = cell.style.backgroundImage;
-        // Should have multiple gradients (one for each continuing level + parent)
+        // colSpan=5 rows only have bracket lines (right side), not tree lines (left side).
+        // Should have exactly 1 bracket gradient.
         const gradientCount = (bgImage.match(/linear-gradient/g) || []).length;
-        expect(gradientCount).toBeGreaterThanOrEqual(2);
+        expect(gradientCount).toBeGreaterThanOrEqual(1);
       });
     });
 

package/__tests__/components/SchemaRows.test.js

@@ -24,6 +24,16 @@ jest.mock('../../components/FoldableRows', () => {
   return MockFoldableRows;
 });
 
+jest.mock('../../components/ConditionalRows', () => {
+  const MockConditionalRows = (props) => (
+    <tr>
+      <td>Mocked ConditionalRows: {props.row.condition.title}</td>
+    </tr>
+  );
+  MockConditionalRows.displayName = 'MockConditionalRows';
+  return MockConditionalRows;
+});
+
 describe('SchemaRows', () => {
   it('renders a PropertyRow for each property type item in tableData', () => {
     const tableData = [
@@ -107,4 +117,25 @@ describe('SchemaRows', () => {
     expect(getByText('Mocked FoldableRows: anyOf')).toBeInTheDocument();
     expect(getByText('Mocked PropertyRow: prop2')).toBeInTheDocument();
   });
+
+  it('renders a ConditionalRows for conditional type items in tableData', () => {
+    const tableData = [
+      {
+        type: 'conditional',
+        path: ['if/then/else'],
+        condition: { title: 'If', rows: [] },
+        branches: [],
+      },
+    ];
+
+    const { getByText } = render(
+      <table>
+        <tbody>
+          <SchemaRows tableData={tableData} />
+        </tbody>
+      </table>,
+    );
+
+    expect(getByText('Mocked ConditionalRows: If')).toBeInTheDocument();
+  });
 });

package/__tests__/components/__snapshots__/ConnectorLines.visualRegression.test.js.snap

@@ -0,0 +1,7 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`connector lines visual regressions keeps cvv row open when payment choice has following options 1`] = `"<td rowspan="1" style="padding-left: 1.75rem;" class="level-1"><span class="property-name"><strong>cvv</strong></span></td>"`;
+
+exports[`connector lines visual regressions keeps user_id option row open when user conditional follows 1`] = `"<td rowspan="1" style="padding-left: 1.75rem;" class="level-1"><span class="property-name"><strong>user_id</strong></span></td>"`;
+
+exports[`connector lines visual regressions keeps wallet_provider option row open when wallet_email follows 1`] = `"<td rowspan="2" style="padding-left: 1.75rem;" class="level-1"><span class="property-name"><strong>wallet_provider</strong></span></td>"`;

package/__tests__/generateEventDocs.anchor.test.js

@@ -61,11 +61,18 @@ describe('generateEventDocs (oneOf with $anchor)', () => {
       'utf-8',
     );
     expect(childWithAnchor).toMatchSnapshot();
+    // Inline oneOf options (using $anchor for slug) must link to the parent schema file
+    expect(childWithAnchor).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json',
+    );
 
     const childWithTitle = fs.readFileSync(
       path.join(parentDir, '02-child-event-title.mdx'),
       'utf-8',
     );
     expect(childWithTitle).toMatchSnapshot();
+    expect(childWithTitle).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json',
+    );
   });
 });

package/__tests__/generateEventDocs.nested.test.js

@@ -70,11 +70,18 @@ describe('generateEventDocs (nested oneOf)', () => {
       'utf-8',
     );
     expect(grandchildA).toMatchSnapshot();
+    // Nested $ref-based oneOf options must link to the resolved source schema file
+    expect(grandchildA).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json',
+    );
 
     const grandchildB = fs.readFileSync(
       path.join(childDir, '02-grandchild-b.mdx'),
       'utf-8',
     );
     expect(grandchildB).toMatchSnapshot();
+    expect(grandchildB).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json',
+    );
   });
 });