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

package/README.md

@@ -73,6 +73,45 @@ npm run update-schema-ids
 
 This command will update the `$id` of all schemas in the versioned directories.
 
+### Sync GTM Variables (Optional)
+
+If you use Google Tag Manager, you can sync Data Layer Variables from your schemas:
+
+```bash
+npm install --save-optional @owntag/gtm-cli
+npm run sync:gtm
+```
+
+The Docusaurus CLI command is:
+
+```bash
+docusaurus sync-gtm
+```
+
+By default, it resolves schemas from the project root. Use `--path=<siteDir>` to target a different site directory.
+
+### Firebase Snippet Targets
+
+`ExampleDataLayer` supports Firebase snippet targets for:
+
+- `android-firebase-kotlin-sdk`
+- `android-firebase-java-sdk`
+- `ios-firebase-swift-sdk`
+- `ios-firebase-objc-sdk`
+
+Mapping rules for generated parameters:
+
+- `string` -> string parameter
+- `integer`/`boolean` -> integer/long parameter (`true` = `1`, `false` = `0`)
+- `number` -> double parameter
+- `items` -> non-empty array of flat item objects
+- unsupported nested values cause a generation error (no automatic flattening or JSON-string fallback)
+
+Reference docs used for syntax and kept as source of truth:
+
+- https://firebase.google.com/docs/analytics/android/events
+- https://firebase.google.com/docs/analytics/ios/events
+
 ## 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.

package/__tests__/ExampleDataLayer.test.js

@@ -3,6 +3,10 @@ import { render, screen } from '@testing-library/react';
 import '@testing-library/jest-dom';
 import ExampleDataLayer, {
   findClearableProperties,
+  readHashTarget,
+  readSearchTarget,
+  resolveInitialTargetId,
+  TARGET_STORAGE_KEY,
 } from '../components/ExampleDataLayer';
 import choiceEventSchema from './__fixtures__/static/schemas/choice-event.json';
 
@@ -14,8 +18,20 @@ jest.mock('@theme/CodeBlock', () => {
 });
 
 jest.mock('@theme/Tabs', () => {
-  return function Tabs({ children }) {
-    return <div data-testid="tabs">{children}</div>;
+  return function Tabs({ children, queryString, defaultValue }) {
+    const attrs = {};
+    if (queryString !== undefined) {
+      attrs['data-query-string'] = queryString;
+    }
+    if (defaultValue !== undefined) {
+      attrs['data-default-value'] = defaultValue;
+    }
+
+    return (
+      <div data-testid="tabs" {...attrs}>
+        {children}
+      </div>
+    );
   };
 });
 
@@ -30,6 +46,11 @@ jest.mock('@theme/TabItem', () => {
 });
 
 describe('ExampleDataLayer', () => {
+  afterEach(() => {
+    window.location.hash = '';
+    window.localStorage.clear();
+  });
+
   it('should render a single example for a simple schema', () => {
     const schema = {
       type: 'object',
@@ -81,6 +102,59 @@ describe('ExampleDataLayer', () => {
     );
     expect(getByText(/window.customDataLayer.push/)).toBeInTheDocument();
   });
+
+  it('should render target tabs when multiple targets are configured', () => {
+    const schema = {
+      type: 'object',
+      'x-tracking-targets': ['web-datalayer-js', 'android-firebase-kotlin-sdk'],
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+      },
+    };
+
+    const { getByTestId, getAllByTestId } = render(
+      <ExampleDataLayer schema={schema} />,
+    );
+    expect(getByTestId('target-tabs')).toBeInTheDocument();
+    const tabLabels = getAllByTestId('tab-item').map((item) =>
+      item.getAttribute('data-label'),
+    );
+    expect(tabLabels).toEqual(
+      expect.arrayContaining([
+        'Web Data Layer (JS)',
+        'Android Firebase (Kotlin)',
+      ]),
+    );
+    expect(getByTestId('tabs')).toHaveAttribute('data-query-string', 'target');
+  });
+
+  it('uses per-target syntax highlighting language', () => {
+    const schema = {
+      type: 'object',
+      'x-tracking-targets': ['android-firebase-kotlin-sdk'],
+      properties: {
+        event: { type: 'string', examples: ['purchase'] },
+        value: { type: 'number', examples: [14.98] },
+      },
+    };
+
+    const { container } = render(<ExampleDataLayer schema={schema} />);
+    const codeBlocks = container.querySelectorAll('pre[data-language]');
+    expect(codeBlocks.length).toBeGreaterThan(0);
+    expect(codeBlocks[0]).toHaveAttribute('data-language', 'kotlin');
+  });
+
+  it('should not render target tabs for single-target schemas', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+      },
+    };
+
+    const { queryByTestId } = render(<ExampleDataLayer schema={schema} />);
+    expect(queryByTestId('target-tabs')).toBeNull();
+  });
 });
 
 describe('findClearableProperties', () => {
@@ -103,3 +177,76 @@ describe('findClearableProperties', () => {
     expect(findClearableProperties(schema)).toEqual(['prop2', 'prop4']);
   });
 });
+
+describe('target selection helpers', () => {
+  afterEach(() => {
+    window.location.hash = '';
+    window.localStorage.clear();
+  });
+
+  it('reads target from hash', () => {
+    window.location.hash = '#target-android-firebase-java-sdk';
+    expect(readHashTarget()).toBe('android-firebase-java-sdk');
+  });
+
+  it('reads target from search', () => {
+    expect(readSearchTarget('?target=android-firebase-java-sdk')).toBe(
+      'android-firebase-java-sdk',
+    );
+  });
+
+  it('persistTarget writes hash without duplicate query target', () => {
+    const originalReplaceState = window.history.replaceState;
+    const replaceSpy = jest.fn();
+    window.history.replaceState = replaceSpy;
+    window.history.pushState(
+      {},
+      '',
+      '/next/event-reference/purchase-event?target=android-firebase-kotlin-sdk',
+    );
+
+    const schema = {
+      type: 'object',
+      'x-tracking-targets': ['web-datalayer-js', 'android-firebase-kotlin-sdk'],
+      properties: {
+        event: { type: 'string', examples: ['purchase'] },
+      },
+    };
+
+    render(<ExampleDataLayer schema={schema} />);
+    expect(replaceSpy).toHaveBeenCalled();
+    const lastCallUrl =
+      replaceSpy.mock.calls[replaceSpy.mock.calls.length - 1][2];
+    expect(lastCallUrl).toContain('#target-android-firebase-kotlin-sdk');
+    expect(lastCallUrl).not.toContain('?target=android-firebase-kotlin-sdk');
+
+    window.history.replaceState = originalReplaceState;
+  });
+
+  it('prefers hash over localStorage for initial target resolution', () => {
+    const targets = [
+      { id: 'web-datalayer-js' },
+      { id: 'android-firebase-java-sdk' },
+    ];
+    window.localStorage.setItem(TARGET_STORAGE_KEY, 'web-datalayer-js');
+    window.location.hash = '#target-android-firebase-java-sdk';
+
+    expect(resolveInitialTargetId(targets)).toBe('android-firebase-java-sdk');
+  });
+
+  it('falls back to first target when hash is unknown', () => {
+    const targets = [
+      { id: 'web-datalayer-js' },
+      { id: 'android-firebase-java-sdk' },
+    ];
+    window.location.hash = '#target-unknown';
+
+    expect(resolveInitialTargetId(targets)).toBe('web-datalayer-js');
+  });
+
+  it('ignores malformed targets and still resolves a valid initial target', () => {
+    const targets = [undefined, {}, { id: 'android-firebase-kotlin-sdk' }];
+    window.location.hash = '#target-android-firebase-kotlin-sdk';
+    expect(resolveInitialTargetId(targets)).toBe('android-firebase-kotlin-sdk');
+  });
+});

package/__tests__/__fixtures__/schema-processing/components/dataLayer.json

@@ -0,0 +1,9 @@
+{
+  "type": "object",
+  "properties": {
+    "ecommerce": {
+      "type": "object",
+      "x-gtm-clear": true
+    }
+  }
+}

package/__tests__/__fixtures__/schema-processing/event-reference.json

@@ -0,0 +1,14 @@
+{
+  "title": "Event Reference",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "./components/dataLayer.json"
+    }
+  ],
+  "oneOf": [
+    {
+      "$ref": "./purchase-event.json"
+    }
+  ]
+}

package/__tests__/__fixtures__/schema-processing/purchase-event.json

@@ -0,0 +1,14 @@
+{
+  "title": "Purchase",
+  "type": "object",
+  "properties": {
+    "ecommerce": {
+      "type": "object",
+      "properties": {
+        "transaction_id": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/__tests__/components/PropertyRow.test.js

@@ -79,6 +79,36 @@ describe('PropertyRow', () => {
     expect(getByText('maxLength: 10')).toBeInTheDocument();
   });
 
+  it('marks only the property column cell with property-cell class', () => {
+    const row = {
+      name: 'name',
+      level: 0,
+      required: true,
+      propertyType: 'string',
+      description: '',
+      example: '',
+      constraints: ['required', 'minLength: 1'],
+      path: ['name'],
+    };
+
+    const { container } = render(
+      <table>
+        <tbody>
+          <PropertyRow row={row} />
+        </tbody>
+      </table>,
+    );
+
+    const propertyCell = container.querySelector('td.property-cell');
+    expect(propertyCell).toBeInTheDocument();
+
+    const subsequentConstraintRows = container.querySelectorAll('tbody tr');
+    expect(subsequentConstraintRows.length).toBeGreaterThan(1);
+    expect(
+      subsequentConstraintRows[1].querySelector('td.property-cell'),
+    ).not.toBeInTheDocument();
+  });
+
   it('renders an example', () => {
     const row = {
       name: 'name',

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="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 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 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 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>"`;
+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>"`;

package/__tests__/helpers/exampleModel.test.js

@@ -0,0 +1,88 @@
+import {
+  buildExampleModel,
+  resolveExampleTargets,
+} from '../../helpers/exampleModel';
+import { DEFAULT_SNIPPET_TARGET_ID } from '../../helpers/snippetTargets';
+import choiceEventSchema from '../__fixtures__/static/schemas/choice-event.json';
+import conditionalEventSchema from '../__fixtures__/static/schemas/conditional-event.json';
+
+describe('buildExampleModel', () => {
+  it('builds a default model for simple schema', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+      },
+    };
+
+    const model = buildExampleModel(schema);
+    expect(model.targets.map((t) => t.id)).toEqual([DEFAULT_SNIPPET_TARGET_ID]);
+    expect(model.isSimpleDefault).toBe(true);
+    expect(model.variantGroups).toHaveLength(1);
+    expect(model.variantGroups[0].property).toBe('default');
+    expect(
+      model.variantGroups[0].options[0].snippets[DEFAULT_SNIPPET_TARGET_ID],
+    ).toContain('window.dataLayer.push');
+  });
+
+  it('builds grouped variants for choice schemas', () => {
+    const model = buildExampleModel(choiceEventSchema);
+    const groupProperties = model.variantGroups.map((group) => group.property);
+
+    expect(model.isSimpleDefault).toBe(false);
+    expect(groupProperties).toEqual(
+      expect.arrayContaining(['user_id', 'payment_method']),
+    );
+    expect(
+      model.variantGroups[0].options[0].snippets[DEFAULT_SNIPPET_TARGET_ID],
+    ).toContain('window.dataLayer.push');
+  });
+
+  it('builds conditional variants for if-then-else schemas', () => {
+    const model = buildExampleModel(conditionalEventSchema);
+    const conditionalGroup = model.variantGroups.find(
+      (group) => group.property === 'conditional',
+    );
+
+    expect(conditionalGroup).toBeDefined();
+    expect(conditionalGroup.options).toHaveLength(2);
+    expect(conditionalGroup.options.map((o) => o.title)).toEqual(
+      expect.arrayContaining([
+        'When condition is met',
+        'When condition is not met',
+      ]),
+    );
+  });
+
+  it('uses configured dataLayerName in snippets', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+      },
+    };
+
+    const model = buildExampleModel(schema, {
+      dataLayerName: 'customDataLayer',
+    });
+    expect(
+      model.variantGroups[0].options[0].snippets[DEFAULT_SNIPPET_TARGET_ID],
+    ).toContain('window.customDataLayer.push');
+  });
+
+  it('resolves multiple targets when x-tracking-targets is provided', () => {
+    const schema = {
+      'x-tracking-targets': ['web-datalayer-js', 'android-firebase-kotlin-sdk'],
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+      },
+    };
+
+    const targets = resolveExampleTargets(schema);
+    expect(targets.map((target) => target.id)).toEqual([
+      'web-datalayer-js',
+      'android-firebase-kotlin-sdk',
+    ]);
+  });
+});

package/__tests__/helpers/schema-processing.test.js

@@ -1,5 +1,10 @@
+/**
+ * @jest-environment node
+ */
+
 import { processOneOfSchema } from '../../helpers/schema-processing';
 import path from 'path';
+import fs from 'fs';
 
 describe('schema-processing', () => {
   describe('processOneOfSchema', () => {
@@ -78,5 +83,56 @@ describe('schema-processing', () => {
       const result = await processOneOfSchema(rootSchema, filePath);
       expect(result[0].schema.$id).toBe('root.json#option-1');
     });
+
+    it('preserves parent property metadata when an option refines the same property', async () => {
+      const rootSchema = {
+        $id: 'root.json',
+        title: 'Root',
+        oneOf: [
+          {
+            title: 'Purchase',
+            properties: {
+              ecommerce: {
+                type: 'object',
+                properties: {
+                  transaction_id: { type: 'string' },
+                },
+              },
+            },
+          },
+        ],
+        properties: {
+          ecommerce: {
+            type: 'object',
+            'x-gtm-clear': true,
+          },
+        },
+      };
+
+      const result = await processOneOfSchema(
+        rootSchema,
+        '/path/to/schema.json',
+      );
+      const mergedEcommerce = result[0].schema.properties.ecommerce;
+
+      expect(mergedEcommerce['x-gtm-clear']).toBe(true);
+      expect(mergedEcommerce.properties.transaction_id.type).toBe('string');
+    });
+
+    it('preserves parent allOf metadata when root oneOf options are file refs', async () => {
+      const rootFile = path.join(
+        __dirname,
+        '..',
+        '__fixtures__',
+        'schema-processing',
+        'event-reference.json',
+      );
+      const rootSchema = JSON.parse(fs.readFileSync(rootFile, 'utf8'));
+      const result = await processOneOfSchema(rootSchema, rootFile);
+      const mergedEcommerce = result[0].schema.properties.ecommerce;
+
+      expect(mergedEcommerce['x-gtm-clear']).toBe(true);
+      expect(mergedEcommerce.properties.transaction_id.type).toBe('string');
+    });
   });
 });