docusaurus-plugin-generate-schema-docs 1.6.0 → 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__/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.partials.test.js

@@ -0,0 +1,134 @@
+/**
+ * @jest-environment node
+ *
+ * Tests that top and bottom partials are correctly injected into generated MDX
+ * when matching partial files exist in the partials directory, and that the
+ * generated import paths use the event name (not the component prefix).
+ */
+
+import generateEventDocs from '../generateEventDocs';
+import fs from 'fs';
+import path from 'path';
+
+jest.mock('fs', () => {
+  const memfs = require('memfs');
+  return memfs;
+});
+
+describe('generateEventDocs (partials)', () => {
+  const fixturesDir = path.resolve(__dirname, '__fixtures__');
+  const options = {
+    organizationName: 'test-org',
+    projectName: 'test-project',
+    siteDir: fixturesDir,
+    url: 'https://tracking-docs-demo.buchert.digital',
+  };
+  const outputDir = path.join(fixturesDir, 'docs');
+  const partialsDir = path.join(outputDir, 'partials');
+
+  beforeEach(() => {
+    fs.vol.reset();
+    const realFs = jest.requireActual('fs');
+
+    function readDirRecursive(dir) {
+      const files = realFs.readdirSync(dir, { withFileTypes: true });
+      for (const file of files) {
+        const filePath = path.join(dir, file.name);
+        if (file.isDirectory()) {
+          fs.vol.mkdirSync(filePath, { recursive: true });
+          readDirRecursive(filePath);
+        } else {
+          fs.vol.writeFileSync(filePath, realFs.readFileSync(filePath));
+        }
+      }
+    }
+    readDirRecursive(fixturesDir);
+  });
+
+  it('injects top partial when _<eventName>.mdx exists in partials dir', async () => {
+    console.log = jest.fn();
+    fs.vol.mkdirSync(partialsDir, { recursive: true });
+    fs.vol.writeFileSync(
+      path.join(partialsDir, '_add-to-cart-event.mdx'),
+      '## Top content',
+    );
+
+    await generateEventDocs(options);
+
+    const output = fs.readFileSync(
+      path.join(outputDir, 'add-to-cart-event.mdx'),
+      'utf-8',
+    );
+
+    expect(output).toContain(
+      "import TopPartial from '@site/docs/partials/_add-to-cart-event.mdx'",
+    );
+    expect(output).toContain('<TopPartial />');
+    expect(output).not.toContain('_Top.mdx');
+  });
+
+  it('injects bottom partial when _<eventName>_bottom.mdx exists in partials dir', async () => {
+    console.log = jest.fn();
+    fs.vol.mkdirSync(partialsDir, { recursive: true });
+    fs.vol.writeFileSync(
+      path.join(partialsDir, '_add-to-cart-event_bottom.mdx'),
+      '## Bottom content',
+    );
+
+    await generateEventDocs(options);
+
+    const output = fs.readFileSync(
+      path.join(outputDir, 'add-to-cart-event.mdx'),
+      'utf-8',
+    );
+
+    expect(output).toContain(
+      "import BottomPartial from '@site/docs/partials/_add-to-cart-event_bottom.mdx'",
+    );
+    expect(output).toContain('<BottomPartial />');
+    expect(output).not.toContain('_Bottom.mdx');
+  });
+
+  it('injects both top and bottom partials when both exist', async () => {
+    console.log = jest.fn();
+    fs.vol.mkdirSync(partialsDir, { recursive: true });
+    fs.vol.writeFileSync(
+      path.join(partialsDir, '_add-to-cart-event.mdx'),
+      '## Top content',
+    );
+    fs.vol.writeFileSync(
+      path.join(partialsDir, '_add-to-cart-event_bottom.mdx'),
+      '## Bottom content',
+    );
+
+    await generateEventDocs(options);
+
+    const output = fs.readFileSync(
+      path.join(outputDir, 'add-to-cart-event.mdx'),
+      'utf-8',
+    );
+
+    expect(output).toContain(
+      "import TopPartial from '@site/docs/partials/_add-to-cart-event.mdx'",
+    );
+    expect(output).toContain('<TopPartial />');
+    expect(output).toContain(
+      "import BottomPartial from '@site/docs/partials/_add-to-cart-event_bottom.mdx'",
+    );
+    expect(output).toContain('<BottomPartial />');
+  });
+
+  it('omits partial imports when no partial files exist', async () => {
+    console.log = jest.fn();
+
+    await generateEventDocs(options);
+
+    const output = fs.readFileSync(
+      path.join(outputDir, 'add-to-cart-event.mdx'),
+      'utf-8',
+    );
+
+    expect(output).not.toContain('TopPartial');
+    expect(output).not.toContain('BottomPartial');
+  });
+});

package/__tests__/helpers/buildExampleFromSchema.test.js

@@ -185,4 +185,53 @@ describe('buildExampleFromSchema', () => {
       },
     });
   });
+
+  it('should handle if/then/else by defaulting to then branch', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['form_submit'] },
+      },
+      if: { properties: { event: { const: 'form_submit' } } },
+      then: {
+        properties: {
+          form_name: { type: 'string', examples: ['contact'] },
+        },
+      },
+      else: {
+        properties: {
+          error_code: { type: 'integer', examples: [404] },
+        },
+      },
+    };
+
+    const example = buildExampleFromSchema(schema);
+    expect(example).toHaveProperty('event', 'form_submit');
+    expect(example).toHaveProperty('form_name', 'contact');
+    expect(example).not.toHaveProperty('error_code');
+  });
+
+  it('should handle nested if/then/else inside a property', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        shipping: {
+          type: 'object',
+          properties: {
+            method: { type: 'string', examples: ['express'] },
+          },
+          if: { properties: { method: { const: 'express' } } },
+          then: {
+            properties: {
+              priority: { type: 'string', examples: ['high'] },
+            },
+          },
+        },
+      },
+    };
+
+    const example = buildExampleFromSchema(schema);
+    expect(example.shipping).toHaveProperty('method', 'express');
+    expect(example.shipping).toHaveProperty('priority', 'high');
+  });
 });