docusaurus-plugin-generate-schema-docs 1.8.2 → 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.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/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/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>

package/components/PropertyRow.js

@@ -26,12 +26,36 @@ const getContainerSymbol = (containerType) => {
   return '';
 };
 
+const KEYWORD_HELP_TEXT = {
+  additionalProperties:
+    'Controls properties not listed in properties and not matched by patternProperties.',
+  patternProperties:
+    'Applies the subschema to property names that match the given regular expression.',
+};
+
+function splitKeywordLabel(name) {
+  const match = /^patternProperties (\/.+\/)$/.exec(name);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    keyword: 'patternProperties',
+    pattern: match[1],
+  };
+}
+
 /**
  * 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, bracketEnds }) {
+export default function PropertyRow({
+  row,
+  stripeIndex,
+  isLastInGroup,
+  bracketEnds,
+}) {
   const {
     name,
     level,
@@ -44,6 +68,8 @@ export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
     containerType,
     continuingLevels = [],
     groupBrackets = [],
+    isSchemaKeywordRow = false,
+    keepConnectorOpen = false,
   } = row;
 
   const indentStyle = {
@@ -112,11 +138,27 @@ export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
   const bracketStyle = getBracketLinesStyle(groupBrackets, bracketCaps);
 
   const containerSymbol = getContainerSymbol(containerType);
+  const shouldCloseConnector = isLastInGroup && !keepConnectorOpen;
+  const splitKeyword = splitKeywordLabel(name);
+  const keywordHelpKey = name.startsWith('patternProperties ')
+    ? 'patternProperties'
+    : name;
+  const keywordHelpText = KEYWORD_HELP_TEXT[keywordHelpKey];
+  const keywordHelpId = keywordHelpText
+    ? `schema-keyword-help-${name}`
+    : undefined;
+  const zebraClassName =
+    stripeIndex === undefined
+      ? undefined
+      : stripeIndex % 2 === 0
+        ? 'schema-row--zebra-even'
+        : 'schema-row--zebra-odd';
 
   return (
     <>
       <tr
         className={clsx(
+          zebraClassName,
           required && 'required-row',
           row.isCondition && 'conditional-condition-row',
         )}
@@ -126,17 +168,57 @@ export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
           style={{ ...indentStyle, ...continuingLinesStyle }}
           className={clsx(
             'property-cell',
+            isSchemaKeywordRow && 'property-cell--keyword',
+            required && 'property-cell--required',
+            level > 0 && 'property-cell--tree',
             level > 0 && `level-${level}`,
-            isLastInGroup && 'is-last',
+            shouldCloseConnector && 'is-last',
             hasChildren && 'has-children',
             containerType && `container-${containerType}`,
           )}
         >
-          <span className="property-name">
+          <span
+            className={clsx(
+              'property-name',
+              isSchemaKeywordRow && 'property-name--keyword',
+            )}
+          >
             {containerSymbol && (
               <span className="container-symbol">{containerSymbol}</span>
             )}
-            <strong>{name}</strong>
+            {isSchemaKeywordRow ? (
+              <span className="property-keyword-wrapper">
+                {splitKeyword ? (
+                  <span className="property-keyword-stack">
+                    <code
+                      className="property-keyword"
+                      aria-describedby={keywordHelpId}
+                    >
+                      {splitKeyword.keyword}
+                    </code>
+                    <code className="property-keyword-pattern">
+                      {splitKeyword.pattern}
+                    </code>
+                  </span>
+                ) : (
+                  <code
+                    className="property-keyword"
+                    aria-describedby={keywordHelpId}
+                  >
+                    {name}
+                  </code>
+                )}
+                <span
+                  id={keywordHelpId}
+                  className="property-keyword-tooltip"
+                  role="tooltip"
+                >
+                  {keywordHelpText}
+                </span>
+              </span>
+            ) : (
+              <strong>{name}</strong>
+            )}
           </span>
         </td>
         <td rowSpan={rowSpan}>
@@ -181,7 +263,10 @@ export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
 
       {/* Render subsequent constraints in their own rows */}
       {remainingConstraints.map((constraint) => (
-        <tr className={clsx(required && 'required-row')} key={constraint}>
+        <tr
+          className={clsx(zebraClassName, required && 'required-row')}
+          key={constraint}
+        >
           <td className="constraint-cell">
             <code
               className={clsx(