docusaurus-plugin-generate-schema-docs 1.2.0 → 1.4.0

package/README.md

@@ -29,6 +29,7 @@ npm install --save docusaurus-plugin-generate-schema-docs
           'docusaurus-plugin-generate-schema-docs',
           {
             // Options if any
+            dataLayerName: 'customDataLayer',
           },
         ],
       ],
@@ -36,6 +37,8 @@ npm install --save docusaurus-plugin-generate-schema-docs
     };
     ```
 
+    The `dataLayerName` option allows you to customize the name of the data layer variable in the generated examples. If not provided, it defaults to `dataLayer`.
+
 2.  Place your JSON schemas in the `schemas` directory at the root of your project.
 
 ## CLI Commands
@@ -45,7 +48,7 @@ npm install --save docusaurus-plugin-generate-schema-docs
 To generate the documentation from your schemas, run the following command:
 
 ```bash
-npx docusaurus generate schema-docs
+npm run gen-docs
 ```
 
 This will generate MDX files in the `docs/events` directory.
@@ -55,17 +58,78 @@ This will generate MDX files in the `docs/events` directory.
 To validate your schemas, run the following command:
 
 ```bash
-npx docusaurus validate-schemas
+npm run validate-schemas
 ```
 
 This will validate the schemas in the `schemas` directory.
 
+### Update Schema IDs
+
+When using versioning, you can update the `$id` of your versioned schemas by running:
+
+```bash
+npm run update-schema-ids
+```
+
+This command will update the `$id` of all schemas in the versioned directories.
+
 ## How it Works
 
 The plugin reads your JSON schemas, dereferences any `$ref` properties, and merges `allOf` properties. It then generates an MDX file for each schema, which uses custom React components to render the schema details.
 
 The validation script builds an example from each schema and validates it against the schema itself, ensuring your examples are always in sync with your schemas.
 
+## Schema Composition (anyOf, oneOf)
+
+The plugin has special handling for `anyOf` and `oneOf` keywords in your JSON schemas.
+
+### `anyOf`
+
+When `anyOf` is used, the plugin will render a dropdown menu in the documentation that allows users to switch between the different sub-schemas. This is useful for representing properties that can have multiple different structures.
+
+### `oneOf`
+
+Similar to `anyOf`, `oneOf` will also render a dropdown menu.
+
+#### `oneOf` at the Root Level
+
+A special behavior is triggered when `oneOf` is used at the root level of a schema file. If a schema's top-level definition is a `oneOf` array, the plugin will generate a directory structure that reflects the choices.
+
+For example, given a schema `my-event.json` with a `oneOf` at the root, where each item in the `oneOf` array is a reference to another schema file (e.g., `option-a.json`, `option-b.json`), the plugin will generate the following structure:
+
+- `docs/events/my-event/`: A directory for the parent schema.
+- `docs/events/my-event/index.mdx`: An index page for `my-event`.
+- `docs/events/my-event/option-a.mdx`: A page for the first option.
+- `docs/events/my-event/option-b.mdx`: A page for the second option.
+
+This creates a nested navigation structure in Docusaurus, which is useful for grouping related events or entities under a single menu item.
+
+## Versioning
+
+This plugin supports documentation and schema versioning, integrated with Docusaurus's native versioning system.
+
+### Enabling Versioning
+
+To enable versioning, you need to:
+
+1.  **Enable Docusaurus Versioning**: Follow the [Docusaurus documentation](https://docusaurus.io/docs/versioning) to enable versioning for your site. This typically involves creating a `versions.json` file.
+
+2.  **Organize Your Schemas**: Create a versioned directory structure for your schemas. Instead of placing your schemas in `static/schemas`, you should have:
+    - `static/schemas/next`: For the "current" or "next" version of your schemas.
+    - `static/schemas/<version>`: For each version of your schemas (e.g., `static/schemas/1.1.1`).
+
+When versioning is enabled, the plugin will automatically detect the `versions.json` file and generate documentation for each version, as well as for the `current` version.
+
+### Non-Versioned Mode
+
+If you do not have a `versions.json` file in your `siteDir`, the plugin will run in non-versioned mode. It will read your schemas from `static/schemas` and generate documentation in `docs/events`.
+
+### Schema `$id` Versioning
+
+When using the versioning feature, the plugin will automatically update the `$id` of your schemas to include the version number. For example, if your site's `url` is `https://example.com` and you have a schema `my-event.json` in version `1.0.0`, the `$id` will be updated to `https://example.com/schemas/1.0.0/my-event.json`.
+
+This is done automatically by the plugin. However, if you need to update the `$id`s of your schemas manually, you can use the `update-schema-ids.js` script located in the plugin's `helpers` directory.
+
 ## Partials
 
 You can provide additional content to the generated documentation pages by creating partial files. Partials are Markdown files that can be automatically included in the generated pages.
@@ -74,8 +138,8 @@ You can provide additional content to the generated documentation pages by creat
 
 Partials must be named after the schema file they correspond to. For a schema named `my-event.json`, the partials would be:
 
-*   `my-event.mdx`: This partial is rendered directly after the schema's main description.
-*   `my-event_bottom.mdx`: This partial is rendered at the very bottom of the page.
+- `my-event.mdx`: This partial is rendered directly after the schema's main description.
+- `my-event_bottom.mdx`: This partial is rendered at the very bottom of the page.
 
 ### Location
 
@@ -85,8 +149,8 @@ Place your partial files in the `/docs/partials` directory at the root of your d
 
 If you have a schema `add-to-cart-event.json`, you can create the following files:
 
-*   `docs/partials/add-to-cart-event.mdx`: For content to appear after the description.
-*   `docs/partials/add-to-cart-event_bottom.mdx`: For content to appear at the bottom.
+- `docs/partials/add-to-cart-event.mdx`: For content to appear after the description.
+- `docs/partials/add-to-cart-event_bottom.mdx`: For content to appear at the bottom.
 
 ## Contributing
 

package/__tests__/ExampleDataLayer.test.js

@@ -1,169 +1,105 @@
 import React from 'react';
 import { render, screen } from '@testing-library/react';
 import '@testing-library/jest-dom';
-import ExampleDataLayer, { findClearableProperties } from '../components/ExampleDataLayer';
-import buildExampleFromSchema from '../helpers/buildExampleFromSchema';
-
-jest.mock('../helpers/buildExampleFromSchema', () => jest.fn());
+import ExampleDataLayer, {
+  findClearableProperties,
+} from '../components/ExampleDataLayer';
+import choiceEventSchema from './__fixtures__/static/schemas/choice-event.json';
 
+// Mock the CodeBlock to make assertions on its content easier
 jest.mock('@theme/CodeBlock', () => {
-    return function CodeBlock({ children }) {
-        return <pre>{children}</pre>;
-    };
+  return function CodeBlock({ children, language }) {
+    return <pre data-language={language}>{children}</pre>;
+  };
 });
 
-describe('ExampleDataLayer', () => {
-    afterEach(() => {
-        jest.clearAllMocks();
-    });
-
-    it('should render correctly with a simple schema', () => {
-        const schema = {
-            type: 'object',
-            properties: {
-                event: { type: 'string', examples: ['test_event'] },
-            },
-        };
-        const example = { event: 'test_event' };
-        buildExampleFromSchema.mockReturnValue(example);
-
-        const { container } = render(<ExampleDataLayer schema={schema} />);
-
-        expect(buildExampleFromSchema).toHaveBeenCalledWith(schema);
-        const codeElement = container.querySelector('pre');
-        expect(codeElement.textContent).toMatchInlineSnapshot(`
-"window.dataLayer.push({
-  "event": "test_event"
-});"
-`);
-    });
-
-    it('should render correctly with properties to reset', () => {
-        const schema = {
-            type: 'object',
-            properties: {
-                ecommerce: {
-                    'x-gtm-clear': true,
-                    type: 'object',
-                    properties: { items: { type: 'array' } },
-                },
-                user_id: { type: 'string' }
-            },
-        };
-        const example = {
-            ecommerce: { items: [{ item_name: 'donuts' }] },
-            user_id: '123'
-        };
-        buildExampleFromSchema.mockReturnValue(example);
-
-        const { container } = render(<ExampleDataLayer schema={schema} />);
-
-        expect(buildExampleFromSchema).toHaveBeenCalledWith(schema);
-
-        const codeElement = container.querySelector('pre');
-        expect(codeElement.textContent).toMatchInlineSnapshot(`
-"window.dataLayer.push({
-  "ecommerce": null
+jest.mock('@theme/Tabs', () => {
+  return function Tabs({ children }) {
+    return <div data-testid="tabs">{children}</div>;
+  };
 });
-window.dataLayer.push({
-  "ecommerce": {
-    "items": [
-      {
-        "item_name": "donuts"
-      }
-    ]
-  },
-  "user_id": "123"
-});"
-`);
-    });
-
-    it('should render correctly with an empty schema', () => {
-        const schema = {};
-        const example = {};
-        buildExampleFromSchema.mockReturnValue(example);
-
-        const { container } = render(<ExampleDataLayer schema={schema} />);
 
-        expect(buildExampleFromSchema).toHaveBeenCalledWith(schema);
-        const codeElement = container.querySelector('pre');
-        expect(codeElement.textContent).toMatchInlineSnapshot(`"window.dataLayer.push({});"`);
-    });
-
-    it('should not reset properties that are not in the final example', () => {
-        const schema = {
-            type: 'object',
-            properties: {
-                ecommerce: {
-                    'x-gtm-clear': true,
-                    type: 'object',
-                    properties: { items: { type: 'array' } },
-                },
-                user_data: {
-                    'x-gtm-clear': true,
-                    type: 'object'
-                },
-                event: { type: 'string' }
-            },
-        };
-        // buildExampleFromSchema will not include user_data because it's an empty object
-        const example = {
-            ecommerce: { items: [{ item_name: 'donuts' }] },
-            event: 'purchase'
-        };
-        buildExampleFromSchema.mockReturnValue(example);
-
-        const { container } = render(<ExampleDataLayer schema={schema} />);
-
-        expect(buildExampleFromSchema).toHaveBeenCalledWith(schema);
-
-        const codeElement = container.querySelector('pre');
-        expect(codeElement.textContent).toMatchInlineSnapshot(`
-"window.dataLayer.push({
-  "ecommerce": null
+jest.mock('@theme/TabItem', () => {
+  return function TabItem({ children, label }) {
+    return (
+      <div data-testid="tab-item" data-label={label}>
+        {children}
+      </div>
+    );
+  };
 });
-window.dataLayer.push({
-  "ecommerce": {
-    "items": [
-      {
-        "item_name": "donuts"
-      }
-    ]
-  },
-  "event": "purchase"
-});"
-`);
-    });
+
+describe('ExampleDataLayer', () => {
+  it('should render a single example for a simple schema', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+      },
+    };
+    const { container } = render(<ExampleDataLayer schema={schema} />);
+    expect(container).toMatchSnapshot();
+  });
+
+  it('should render nothing for an empty schema', () => {
+    const { container } = render(<ExampleDataLayer schema={{}} />);
+    // An empty schema produces no examples, so the component should render null
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('should render grouped tabs for a schema with choices', () => {
+    const { container, getAllByTestId } = render(
+      <ExampleDataLayer schema={choiceEventSchema} />,
+    );
+
+    // Check for the group headings
+    const headings = screen.getAllByRole('heading', { level: 4 });
+    expect(headings[0]).toHaveTextContent(/user_id options:/);
+    expect(headings[1]).toHaveTextContent(/payment_method options:/);
+
+    const tabItems = getAllByTestId('tab-item');
+    // 2 options for user_id + 2 options for payment_method = 4 tabs total
+    expect(tabItems).toHaveLength(4);
+
+    // Check the labels for one of the groups
+    expect(tabItems[0]).toHaveAttribute('data-label', 'User ID as String');
+    expect(tabItems[1]).toHaveAttribute('data-label', 'User ID as Integer');
+
+    // Let snapshot testing verify the complex content of each tab
+    expect(container).toMatchSnapshot();
+  });
+
+  it('should use the provided dataLayerName', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+      },
+    };
+    const { getByText } = render(
+      <ExampleDataLayer schema={schema} dataLayerName="customDataLayer" />,
+    );
+    expect(getByText(/window.customDataLayer.push/)).toBeInTheDocument();
+  });
 });
 
 describe('findClearableProperties', () => {
-    it('should return an empty array when schema is empty, null, or has no properties', () => {
-        expect(findClearableProperties({})).toEqual([]);
-        expect(findClearableProperties({ type: 'object' })).toEqual([]);
-        expect(findClearableProperties(null)).toEqual([]);
-        expect(findClearableProperties(undefined)).toEqual([]);
-    });
-
-    it('should return properties with "x-gtm-clear": true', () => {
-        const schema = {
-            properties: {
-                prop1: { type: 'string' },
-                prop2: { 'x-gtm-clear': true, type: 'object' },
-                prop3: { 'x-gtm-clear': false, type: 'object' },
-                prop4: { 'x-gtm-clear': true, type: 'array' },
-            }
-        };
-        expect(findClearableProperties(schema)).toEqual(['prop2', 'prop4']);
-    });
-
-    it('should return an empty array if no properties have "x-gtm-clear": true', () => {
-        const schema = {
-            properties: {
-                prop1: { type: 'string' },
-                prop2: { type: 'object' },
-                prop3: { 'x-gtm-clear': false, type: 'object' },
-            }
-        };
-        expect(findClearableProperties(schema)).toEqual([]);
-    });
+  it('should return an empty array when schema is empty, null, or has no properties', () => {
+    expect(findClearableProperties({})).toEqual([]);
+    expect(findClearableProperties({ type: 'object' })).toEqual([]);
+    expect(findClearableProperties(null)).toEqual([]);
+    expect(findClearableProperties(undefined)).toEqual([]);
+  });
+
+  it('should return properties with "x-gtm-clear": true', () => {
+    const schema = {
+      properties: {
+        prop1: { type: 'string' },
+        prop2: { 'x-gtm-clear': true, type: 'object' },
+        prop3: { 'x-gtm-clear': false, type: 'object' },
+        prop4: { 'x-gtm-clear': true, type: 'array' },
+      },
+    };
+    expect(findClearableProperties(schema)).toEqual(['prop2', 'prop4']);
+  });
 });

package/__tests__/__fixtures__/static/schemas/add-to-cart-event.json

@@ -22,20 +22,12 @@
         "value": {
           "type": "number",
           "description": "The monetary value of the event. Set value to the sum of (price * quantity) for all items in items.",
-          "examples": [
-            30.03,
-            99.99,
-            45.50
-          ]
+          "examples": [30.03, 99.99, 45.5]
         },
         "currency": {
           "type": "string",
           "description": "The currency of the items in ISO 4217 three-letter format. Required when value is set.",
-          "examples": [
-            "USD",
-            "EUR",
-            "GBP"
-          ]
+          "examples": ["USD", "EUR", "GBP"]
         },
         "items": {
           "type": "array",
@@ -46,10 +38,7 @@
           }
         }
       },
-      "required": [
-        "currency",
-        "items"
-      ]
+      "required": ["currency", "items"]
     }
   }
-}
+}

package/__tests__/__fixtures__/static/schemas/anchor/parent-event-anchor.json

@@ -0,0 +1,29 @@
+{
+  "$id": "https://example.com/parent-event-anchor.json",
+  "title": "Parent Event Anchor",
+  "description": "This is a parent event with oneOf.",
+  "type": "object",
+  "oneOf": [
+    {
+      "title": "Child Event Anchor",
+      "description": "This is a child event with an anchor.",
+      "$anchor": "child-event-with-anchor",
+      "type": "object",
+      "properties": {
+        "property_a": {
+          "type": "string"
+        }
+      }
+    },
+    {
+      "title": "Child Event Title",
+      "description": "This is a child event with only a title.",
+      "type": "object",
+      "properties": {
+        "property_b": {
+          "type": "string"
+        }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracking-docs-demo.buchert.digital/schemas/1.2.0/choice-event.json",
+  "title": "Choice Event",
+  "description": "An example event that uses oneOf and anyOf.",
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "const": "one_of_event"
+    },
+    "user_id": {
+      "description": "The user's ID.",
+      "oneOf": [
+        {
+          "type": "string",
+          "title": "User ID as String",
+          "description": "The user's ID as a string.",
+          "examples": ["user-123"]
+        },
+        {
+          "type": "integer",
+          "title": "User ID as Integer",
+          "description": "The user's ID as an integer.",
+          "examples": [123]
+        }
+      ]
+    },
+    "payment_method": {
+      "description": "The user's payment method.",
+      "type": "object",
+      "anyOf": [
+        {
+          "title": "Credit Card",
+          "properties": {
+            "payment_type": {
+              "type": "string",
+              "enum": ["credit_card", "debit_card"],
+              "examples": ["credit_card"]
+            },
+            "card_number": {
+              "type": "string",
+              "examples": ["1234-5678-9012-3456"]
+            },
+            "expiry_date": {
+              "type": "string",
+              "examples": ["12/26"]
+            }
+          },
+          "required": ["card_number", "expiry_date"]
+        },
+        {
+          "title": "PayPal",
+          "type": "object",
+          "properties": {
+            "payment_type": {
+              "type": "string",
+              "const": "paypal"
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "examples": ["test@example.com"]
+            }
+          },
+          "required": ["email"]
+        }
+      ]
+    }
+  },
+  "required": ["event", "user_id", "payment_method"]
+}

package/__tests__/__fixtures__/static/schemas/components/dataLayer.json

@@ -1,58 +1,56 @@
 {
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://tracking-docs-demo.buchert.digital/schemas/components/dataLayer.json",
-    "title": "dataLayer",
-    "description": "Schema for the object structure pushed to the dataLayer.",
-    "type": "object",
-    "allOf": [
-        {
-            "$ref": "#/$defs/strictObject"
-        }
-    ],
-    "properties": {
-        "event": {
-            "type": "string",
-            "description": "The name of the event."
-        },
-        "ecommerce": {
-            "type": "object",
-            "description": "Ecommerce related data.",
-            "x-gtm-clear": true
-        },
-        "user_data": {
-            "type": "object",
-            "description": "User related data.",
-            "x-gtm-clear": true
-        }
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tracking-docs-demo.buchert.digital/schemas/components/dataLayer.json",
+  "title": "dataLayer",
+  "description": "Schema for the object structure pushed to the dataLayer.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "#/$defs/strictObject"
+    }
+  ],
+  "properties": {
+    "event": {
+      "type": "string",
+      "description": "The name of the event."
+    },
+    "ecommerce": {
+      "type": "object",
+      "description": "Ecommerce related data.",
+      "x-gtm-clear": true
     },
-    "required": [
-        "event"
-    ],
-    "$defs": {
-        "strictObject": {
-            "type": "object",
-            "propertyNames": {
-                "maxLength": 40,
-                "pattern": "^[a-z0-9_]+$"
-            },
-            "additionalProperties": {
-                "anyOf": [
-                    {
-                        "$ref": "#/$defs/strictObject"
-                    },
-                    {
-                        "type": "array",
-                        "items": {
-                            "$ref": "#/$defs/strictObject"
-                        }
-                    },
-                    {
-                        "not": {
-                            "type": "object"
-                        }
-                    }
-                ]
+    "user_data": {
+      "type": "object",
+      "description": "User related data.",
+      "x-gtm-clear": true
+    }
+  },
+  "required": ["event"],
+  "$defs": {
+    "strictObject": {
+      "type": "object",
+      "propertyNames": {
+        "maxLength": 40,
+        "pattern": "^[a-z0-9_]+$"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/strictObject"
+          },
+          {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/strictObject"
+            }
+          },
+          {
+            "not": {
+              "type": "object"
             }
-        }
+          }
+        ]
+      }
     }
-}
+  }
+}