docusaurus-plugin-generate-schema-docs 1.8.1 → 1.8.3

package/__tests__/components/SchemaJsonViewer.test.js

@@ -1,17 +1,21 @@
+/* eslint-disable @docusaurus/no-html-links */
 import '@testing-library/jest-dom';
 import React from 'react';
-import { render } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import SchemaJsonViewer from '../../components/SchemaJsonViewer';
 
-// Mock CodeBlock as it's an external theme component
-jest.mock('@theme/CodeBlock', () => {
-  return function DummyCodeBlock({ children, language }) {
-    return <pre data-language={language}>{children}</pre>;
-  };
-});
+jest.mock(
+  '@docusaurus/Link',
+  () => {
+    return function DocusaurusLink({ children, ...props }) {
+      return <a {...props}>{children}</a>;
+    };
+  },
+  { virtual: true },
+);
 
 describe('SchemaJsonViewer', () => {
-  it('renders the schema in a CodeBlock', () => {
+  it('renders the schema in a syntax-highlighted pre block', () => {
     const schema = {
       type: 'object',
       properties: {
@@ -29,8 +33,70 @@ describe('SchemaJsonViewer', () => {
     const codeBlockElement = container.querySelector('pre');
     expect(codeBlockElement).toBeInTheDocument();
     expect(codeBlockElement).toHaveAttribute('data-language', 'json');
-    expect(codeBlockElement.textContent).toEqual(
-      JSON.stringify(schema, null, 2),
+    expect(codeBlockElement.textContent.replace(/\s+/g, '')).toEqual(
+      JSON.stringify(schema, null, 2).replace(/\s+/g, ''),
+    );
+  });
+
+  it('navigates local $ref values inside the viewer and resets to root', () => {
+    const rootSchema = {
+      type: 'object',
+      properties: {
+        component: { $ref: './components/referenced.json' },
+      },
+    };
+    const referencedSchema = {
+      title: 'Referenced Component',
+      type: 'object',
+      properties: {
+        prop: { type: 'string' },
+      },
+    };
+
+    render(
+      <SchemaJsonViewer
+        schema={rootSchema}
+        sourcePath="main-schema.json"
+        schemaSources={{
+          'main-schema.json': rootSchema,
+          'components/referenced.json': referencedSchema,
+        }}
+      />,
     );
+
+    fireEvent.click(screen.getByText('View Raw JSON Schema'));
+    fireEvent.click(
+      screen.getByRole('button', { name: '"./components/referenced.json"' }),
+    );
+
+    expect(screen.getAllByText(/Referenced Component/).length).toBeGreaterThan(
+      0,
+    );
+    expect(
+      screen.getByRole('button', { name: 'Back to root' }),
+    ).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole('button', { name: 'Back to root' }));
+
+    expect(
+      screen.getByText('"./components/referenced.json"'),
+    ).toBeInTheDocument();
+  });
+
+  it('renders external $ref values as new-tab links', () => {
+    const schema = {
+      $ref: 'https://example.com/schema.json',
+    };
+
+    render(<SchemaJsonViewer schema={schema} sourcePath="root.json" />);
+
+    fireEvent.click(screen.getByText('View Raw JSON Schema'));
+    const refLink = screen.getByRole('link', {
+      name: '"https://example.com/schema.json"',
+    });
+
+    expect(refLink).toHaveAttribute('href', 'https://example.com/schema.json');
+    expect(refLink).toHaveAttribute('target', '_blank');
+    expect(refLink).toHaveAttribute('rel', 'noreferrer');
   });
 });

package/__tests__/components/SchemaRows.test.js

@@ -7,7 +7,9 @@ import SchemaRows from '../../components/SchemaRows';
 jest.mock('../../components/PropertyRow', () => {
   const MockPropertyRow = (props) => (
     <tr>
-      <td>Mocked PropertyRow: {props.row.name}</td>
+      <td>
+        Mocked PropertyRow: {props.row.name} ({props.stripeIndex})
+      </td>
     </tr>
   );
   MockPropertyRow.displayName = 'MockPropertyRow';
@@ -17,7 +19,10 @@ jest.mock('../../components/PropertyRow', () => {
 jest.mock('../../components/FoldableRows', () => {
   const MockFoldableRows = (props) => (
     <tr>
-      <td>Mocked FoldableRows: {props.row.choiceType}</td>
+      <td>
+        Mocked FoldableRows: {props.row.choiceType} ({props.stripeIndex},{' '}
+        {String(!!props.stripeState)})
+      </td>
     </tr>
   );
   MockFoldableRows.displayName = 'MockFoldableRows';
@@ -27,7 +32,10 @@ jest.mock('../../components/FoldableRows', () => {
 jest.mock('../../components/ConditionalRows', () => {
   const MockConditionalRows = (props) => (
     <tr>
-      <td>Mocked ConditionalRows: {props.row.condition.title}</td>
+      <td>
+        Mocked ConditionalRows: {props.row.condition.title} ({props.stripeIndex}
+        , {String(!!props.stripeState)})
+      </td>
     </tr>
   );
   MockConditionalRows.displayName = 'MockConditionalRows';
@@ -49,8 +57,8 @@ describe('SchemaRows', () => {
       </table>,
     );
 
-    expect(getByText('Mocked PropertyRow: name')).toBeInTheDocument();
-    expect(getByText('Mocked PropertyRow: age')).toBeInTheDocument();
+    expect(getByText('Mocked PropertyRow: name (0)')).toBeInTheDocument();
+    expect(getByText('Mocked PropertyRow: age (1)')).toBeInTheDocument();
   });
 
   it('renders nested properties from a flat list', () => {
@@ -68,8 +76,8 @@ describe('SchemaRows', () => {
     );
 
     // It should render both the parent and child property from the flat list
-    expect(getByText('Mocked PropertyRow: user')).toBeInTheDocument();
-    expect(getByText('Mocked PropertyRow: id')).toBeInTheDocument();
+    expect(getByText('Mocked PropertyRow: user (0)')).toBeInTheDocument();
+    expect(getByText('Mocked PropertyRow: id (1)')).toBeInTheDocument();
   });
 
   it('renders a FoldableRows for choice type items in tableData', () => {
@@ -90,7 +98,9 @@ describe('SchemaRows', () => {
       </table>,
     );
 
-    expect(getByText('Mocked FoldableRows: oneOf')).toBeInTheDocument();
+    expect(
+      getByText('Mocked FoldableRows: oneOf (0, true)'),
+    ).toBeInTheDocument();
   });
 
   it('renders a mix of properties and choices', () => {
@@ -113,9 +123,11 @@ describe('SchemaRows', () => {
       </table>,
     );
 
-    expect(getByText('Mocked PropertyRow: prop1')).toBeInTheDocument();
-    expect(getByText('Mocked FoldableRows: anyOf')).toBeInTheDocument();
-    expect(getByText('Mocked PropertyRow: prop2')).toBeInTheDocument();
+    expect(getByText('Mocked PropertyRow: prop1 (0)')).toBeInTheDocument();
+    expect(
+      getByText('Mocked FoldableRows: anyOf (1, true)'),
+    ).toBeInTheDocument();
+    expect(getByText('Mocked PropertyRow: prop2 (2)')).toBeInTheDocument();
   });
 
   it('renders a ConditionalRows for conditional type items in tableData', () => {
@@ -136,6 +148,44 @@ describe('SchemaRows', () => {
       </table>,
     );
 
-    expect(getByText('Mocked ConditionalRows: If')).toBeInTheDocument();
+    expect(
+      getByText('Mocked ConditionalRows: If (0, true)'),
+    ).toBeInTheDocument();
+  });
+
+  it('increments stripe indices across logical rows', () => {
+    const tableData = [
+      { type: 'property', name: 'prop1', path: ['prop1'] },
+      {
+        type: 'choice',
+        choiceType: 'anyOf',
+        path: ['choice'],
+        options: [],
+      },
+      {
+        type: 'conditional',
+        path: ['if/then/else'],
+        condition: { title: 'If', rows: [] },
+        branches: [],
+      },
+      { type: 'property', name: 'prop2', path: ['prop2'] },
+    ];
+
+    const { getByText } = render(
+      <table>
+        <tbody>
+          <SchemaRows tableData={tableData} />
+        </tbody>
+      </table>,
+    );
+
+    expect(getByText('Mocked PropertyRow: prop1 (0)')).toBeInTheDocument();
+    expect(
+      getByText('Mocked FoldableRows: anyOf (1, true)'),
+    ).toBeInTheDocument();
+    expect(
+      getByText('Mocked ConditionalRows: If (2, true)'),
+    ).toBeInTheDocument();
+    expect(getByText('Mocked PropertyRow: prop2 (3)')).toBeInTheDocument();
   });
 });

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

@@ -1,7 +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="property-cell level-1"><span class="property-name"><strong>cvv</strong></span></td>"`;
+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="property-cell property-cell--tree 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="property-cell level-1"><span class="property-name"><strong>user_id</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="property-cell property-cell--tree 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="property-cell level-1"><span class="property-name"><strong>wallet_provider</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="property-cell property-cell--required property-cell--tree level-1"><span class="property-name"><strong>wallet_provider</strong></span></td>"`;

package/__tests__/generateEventDocs.partials.test.js

@@ -45,6 +45,48 @@ describe('generateEventDocs (partials)', () => {
     readDirRecursive(fixturesDir);
   });
 
+  function writeDuplicateNameOneOfSchemas() {
+    const schemaA = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $id: 'https://example.com/schemas/duplicate-a.json',
+      title: 'Duplicate A',
+      oneOf: [
+        {
+          title: 'Shared Option',
+          type: 'object',
+          properties: {
+            event: { type: 'string', const: 'dup_a' },
+          },
+          required: ['event'],
+        },
+      ],
+    };
+    const schemaB = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $id: 'https://example.com/schemas/duplicate-b.json',
+      title: 'Duplicate B',
+      oneOf: [
+        {
+          title: 'Shared Option',
+          type: 'object',
+          properties: {
+            event: { type: 'string', const: 'dup_b' },
+          },
+          required: ['event'],
+        },
+      ],
+    };
+
+    fs.vol.writeFileSync(
+      path.join(fixturesDir, 'static', 'schemas', 'duplicate-a.json'),
+      JSON.stringify(schemaA, null, 2),
+    );
+    fs.vol.writeFileSync(
+      path.join(fixturesDir, 'static', 'schemas', 'duplicate-b.json'),
+      JSON.stringify(schemaB, null, 2),
+    );
+  }
+
   it('injects top partial when _<eventName>.mdx exists in partials dir', async () => {
     console.log = jest.fn();
     fs.vol.mkdirSync(partialsDir, { recursive: true });
@@ -131,4 +173,57 @@ describe('generateEventDocs (partials)', () => {
     expect(output).not.toContain('TopPartial');
     expect(output).not.toContain('BottomPartial');
   });
+
+  it('skips basename fallback partials when event names are ambiguous', async () => {
+    console.log = jest.fn();
+    writeDuplicateNameOneOfSchemas();
+    fs.vol.mkdirSync(partialsDir, { recursive: true });
+    fs.vol.writeFileSync(
+      path.join(partialsDir, '_shared-option.mdx'),
+      'Shared',
+    );
+
+    await generateEventDocs(options);
+
+    const outputA = fs.readFileSync(
+      path.join(outputDir, 'duplicate-a', '01-shared-option.mdx'),
+      'utf-8',
+    );
+    const outputB = fs.readFileSync(
+      path.join(outputDir, 'duplicate-b', '01-shared-option.mdx'),
+      'utf-8',
+    );
+
+    expect(outputA).not.toContain('TopPartial');
+    expect(outputB).not.toContain('TopPartial');
+  });
+
+  it('uses scoped partials for ambiguous event names', async () => {
+    console.log = jest.fn();
+    writeDuplicateNameOneOfSchemas();
+    fs.vol.mkdirSync(path.join(partialsDir, 'duplicate-a'), {
+      recursive: true,
+    });
+    fs.vol.writeFileSync(
+      path.join(partialsDir, 'duplicate-a', '_shared-option.mdx'),
+      'Scoped shared',
+    );
+
+    await generateEventDocs(options);
+
+    const outputA = fs.readFileSync(
+      path.join(outputDir, 'duplicate-a', '01-shared-option.mdx'),
+      'utf-8',
+    );
+    const outputB = fs.readFileSync(
+      path.join(outputDir, 'duplicate-b', '01-shared-option.mdx'),
+      'utf-8',
+    );
+
+    expect(outputA).toContain(
+      "import TopPartial from '@site/docs/partials/duplicate-a/_shared-option.mdx'",
+    );
+    expect(outputA).toContain('<TopPartial />');
+    expect(outputB).not.toContain('TopPartial');
+  });
 });

package/__tests__/generateEventDocs.test.js

@@ -56,6 +56,9 @@ describe('generateEventDocs (non-versioned)', () => {
       'utf-8',
     );
     expect(addToCart).toMatchSnapshot();
+    expect(addToCart).toContain('sourcePath={"add-to-cart-event.json"}');
+    expect(addToCart).toContain(JSON.stringify('components/product.json'));
+    expect(addToCart).toContain('"$ref":"./components/product.json"');
 
     const choiceEvent = fs.readFileSync(
       path.join(outputDir, 'choice-event.mdx'),

package/__tests__/helpers/processSchema.test.js

@@ -53,4 +53,33 @@ describe('processSchema', () => {
     expect(mergedSchema.properties.b.title).toBe('Schema B');
     expect(mergedSchema.properties.b.properties.a.$ref).toBe('#');
   });
+
+  it('resolves published /constraints refs when bundling and merging allOf', async () => {
+    const filePath = path.join(
+      __dirname,
+      '..',
+      '__fixtures__',
+      'validateSchemas',
+      'main-schema-with-constraints-ref.json',
+    );
+    const mergedSchema = await processSchema(filePath);
+
+    expect(mergedSchema.title).toBe('Main Schema with Constraints Ref');
+    expect(mergedSchema.additionalProperties).toEqual(
+      expect.objectContaining({
+        type: expect.arrayContaining([
+          'string',
+          'number',
+          'integer',
+          'boolean',
+          'null',
+        ]),
+      }),
+    );
+    expect(mergedSchema.properties.items).toEqual(
+      expect.objectContaining({
+        type: 'array',
+      }),
+    );
+  });
 });

package/__tests__/helpers/schemaToTableData.test.js

@@ -217,6 +217,118 @@ describe('schemaToTableData', () => {
     expect(tableData[0].examples).toEqual(['default-value']);
   });
 
+  it('renders schema-valued additionalProperties as a synthetic row', () => {
+    const schema = {
+      properties: {
+        metadata: {
+          type: 'object',
+          description: 'Free-form metadata.',
+          additionalProperties: {
+            type: 'string',
+            description: 'Metadata value.',
+            pattern: '^[a-z]+$',
+          },
+        },
+      },
+    };
+
+    const tableData = schemaToTableData(schema);
+
+    const metadataRow = tableData.find((row) => row.name === 'metadata');
+    expect(metadataRow).toBeDefined();
+    expect(metadataRow.containerType).toBe('object');
+
+    const additionalPropertiesRow = tableData.find(
+      (row) =>
+        row.type === 'property' &&
+        row.name === 'additionalProperties' &&
+        row.level === 1,
+    );
+
+    expect(additionalPropertiesRow).toBeDefined();
+    expect(additionalPropertiesRow.propertyType).toBe('string');
+    expect(additionalPropertiesRow.description).toBe('Metadata value.');
+    expect(additionalPropertiesRow.constraints).toContain(
+      'pattern: /^[a-z]+$/',
+    );
+    expect(additionalPropertiesRow.isSchemaKeywordRow).toBe(true);
+    expect(additionalPropertiesRow.keepConnectorOpen).toBe(false);
+    expect(additionalPropertiesRow.isLastInGroup).toBe(true);
+  });
+
+  it('treats additionalProperties as the last sibling after declared properties', () => {
+    const schema = {
+      properties: {
+        user_properties: {
+          type: 'object',
+          properties: {
+            allow_ad_personalization_signals: {
+              type: ['string', 'null'],
+            },
+          },
+          additionalProperties: {
+            type: ['string', 'null'],
+          },
+        },
+      },
+    };
+
+    const tableData = schemaToTableData(schema);
+
+    const explicitPropertyRow = tableData.find(
+      (row) =>
+        row.name === 'allow_ad_personalization_signals' && row.level === 1,
+    );
+    const additionalPropertiesRow = tableData.find(
+      (row) => row.name === 'additionalProperties' && row.level === 1,
+    );
+
+    expect(explicitPropertyRow).toBeDefined();
+    expect(additionalPropertiesRow).toBeDefined();
+    expect(explicitPropertyRow.isLastInGroup).toBe(false);
+    expect(additionalPropertiesRow.isLastInGroup).toBe(true);
+  });
+
+  it('renders schema-valued patternProperties as synthetic keyword rows', () => {
+    const schema = {
+      properties: {
+        attributes: {
+          type: 'object',
+          properties: {
+            segment: { type: 'string' },
+          },
+          patternProperties: {
+            '^custom_': {
+              type: 'number',
+              description: 'Numeric custom attribute values.',
+              minimum: 0,
+            },
+          },
+        },
+      },
+    };
+
+    const tableData = schemaToTableData(schema);
+
+    const explicitPropertyRow = tableData.find(
+      (row) => row.name === 'segment' && row.level === 1,
+    );
+    const patternPropertyRow = tableData.find(
+      (row) => row.name === 'patternProperties /^custom_/' && row.level === 1,
+    );
+
+    expect(explicitPropertyRow).toBeDefined();
+    expect(patternPropertyRow).toBeDefined();
+    expect(explicitPropertyRow.isLastInGroup).toBe(false);
+    expect(patternPropertyRow.isLastInGroup).toBe(true);
+    expect(patternPropertyRow.propertyType).toBe('number');
+    expect(patternPropertyRow.description).toBe(
+      'Numeric custom attribute values.',
+    );
+    expect(patternPropertyRow.constraints).toContain('minimum: 0');
+    expect(patternPropertyRow.isSchemaKeywordRow).toBe(true);
+  });
+
   describe('if/then/else conditional support', () => {
     it('creates a conditional row for schema with if/then/else at root level', () => {
       const tableData = schemaToTableData(conditionalEventSchema);

package/__tests__/helpers/validator.test.js

@@ -1,4 +1,5 @@
 import { createValidator } from '../../helpers/validator';
+import path from 'path';
 
 describe('createValidator', () => {
   it('creates a validator that returns true for valid data with no schema version (draft-07)', async () => {
@@ -112,4 +113,35 @@ describe('createValidator', () => {
     expect(result.valid).toBe(true);
     expect(result.errors).toEqual([]);
   });
+
+  it('resolves published /constraints refs to local constraint schemas', async () => {
+    const schema = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      allOf: [
+        {
+          $ref: 'https://tracking-docs-demo.buchert.digital/constraints/schemas/firebase/v1/flat-event-params.json',
+        },
+      ],
+    };
+
+    const schemaPath = path.resolve(
+      __dirname,
+      '../../../../demo/static/schemas/next',
+    );
+    const validator = await createValidator([], schema, schemaPath);
+
+    const valid = validator({
+      event: 'screen_view',
+      screen_name: 'Checkout',
+      attempt: 1,
+    });
+    expect(valid.valid).toBe(true);
+
+    const invalid = validator({
+      event: 'screen_view',
+      nested: { disallowed: true },
+    });
+    expect(invalid.valid).toBe(false);
+  });
 });

package/components/ConditionalRows.js

@@ -17,6 +17,8 @@ import {
  */
 export default function ConditionalRows({
   row,
+  stripeIndex = 0,
+  stripeState,
   bracketEnds: parentBracketEnds,
 }) {
   const {
@@ -91,7 +93,7 @@ export default function ConditionalRows({
   return (
     <>
       {/* Condition (if) section - always visible */}
-      <tr className="conditional-condition-header">
+      <tr className="conditional-condition-header schema-row--control">
         <td colSpan={5} style={headerStyle}>
           <span className="conditional-condition-label">
             <span className="conditional-info-icon-wrapper">
@@ -111,7 +113,7 @@ export default function ConditionalRows({
           )}
         </td>
       </tr>
-      <SchemaRows tableData={condition.rows} />
+      <SchemaRows tableData={condition.rows} stripeState={stripeState} />
 
       {/* Branch toggles (then / else) */}
       {branches.map((branch, index) => {
@@ -121,7 +123,7 @@ export default function ConditionalRows({
           isLastBranch && !isActive ? lastToggleStyle : middleStyle;
         return (
           <React.Fragment key={branch.title}>
-            <tr className="choice-row">
+            <tr className="choice-row schema-row--control">
               <td colSpan={5} style={toggleStyle}>
                 <label className="choice-row-header">
                   <input
@@ -141,6 +143,7 @@ export default function ConditionalRows({
             {isActive && (
               <SchemaRows
                 tableData={branch.rows}
+                stripeState={stripeState}
                 bracketEnds={
                   isLastBranch
                     ? [ownBracket, ...(parentBracketEnds || [])]

package/components/FoldableRows.js

@@ -18,7 +18,7 @@ const ChoiceRow = ({
   name,
   continuingLinesStyle,
 }) => (
-  <tr className="choice-row">
+  <tr className="choice-row schema-row--control">
     <td colSpan={5} style={continuingLinesStyle}>
       <label className="choice-row-header">
         <input
@@ -41,7 +41,12 @@ 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, bracketEnds: parentBracketEnds }) {
+export default function FoldableRows({
+  row,
+  stripeIndex = 0,
+  stripeState,
+  bracketEnds: parentBracketEnds,
+}) {
   const {
     choiceType,
     options,
@@ -136,7 +141,7 @@ export default function FoldableRows({ row, bracketEnds: parentBracketEnds }) {
   return (
     <>
       {/* A header row for the entire choice block */}
-      <tr>
+      <tr className="schema-row--control">
         <td colSpan={5} style={headerStyle}>
           <Heading as="h4" className="choice-row-header-headline">
             {header}
@@ -176,6 +181,7 @@ export default function FoldableRows({ row, bracketEnds: parentBracketEnds }) {
             {isActive && (
               <SchemaRows
                 tableData={option.rows}
+                stripeState={stripeState}
                 bracketEnds={
                   isLastOption
                     ? [ownBracket, ...(parentBracketEnds || [])]

package/components/PropertiesTable.js

@@ -8,6 +8,7 @@ import styles from './PropertiesTable.module.css';
 export default function PropertiesTable({ schema }) {
   const [isWordWrapOn, setIsWordWrapOn] = useState(true);
   const tableData = schemaToTableData(schema);
+  const stripeState = { current: 0 };
 
   return (
     <div
@@ -24,7 +25,7 @@ export default function PropertiesTable({ schema }) {
       <table className="schema-table">
         <TableHeader />
         <tbody>
-          <SchemaRows tableData={tableData} />
+          <SchemaRows tableData={tableData} stripeState={stripeState} />
         </tbody>
       </table>
     </div>