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

package/__tests__/syncGtm.test.js

@@ -0,0 +1,346 @@
+/* eslint-env jest */
+/**
+ * @jest-environment node
+ */
+const fs = require('fs');
+const path = require('path');
+const gtmScript = require('../scripts/sync-gtm');
+const { execSync } = require('child_process');
+const RefParser = require('@apidevtools/json-schema-ref-parser');
+
+jest.mock('fs');
+jest.mock('child_process');
+jest.mock('@apidevtools/json-schema-ref-parser');
+
+describe('parseArgs', () => {
+  it('should parse --quiet, --json, and --skip-array-sub-properties flags', () => {
+    const argv = [
+      'node',
+      'script.js',
+      '--quiet',
+      '--json',
+      '--skip-array-sub-properties',
+    ];
+    const { isQuiet, isJson, skipArraySubProperties } =
+      gtmScript.parseArgs(argv);
+    expect(isQuiet).toBe(true);
+    expect(isJson).toBe(true);
+    expect(skipArraySubProperties).toBe(true);
+  });
+
+  it('should parse --path argument', () => {
+    const argv = ['node', 'script.js', '--path=./my-demo'];
+    const { siteDir } = gtmScript.parseArgs(argv);
+    expect(siteDir).toBe('./my-demo');
+  });
+
+  it('should default siteDir to .', () => {
+    const argv = ['node', 'script.js'];
+    const { siteDir } = gtmScript.parseArgs(argv);
+    expect(siteDir).toBe('.');
+  });
+});
+
+describe('getLatestSchemaPath', () => {
+  const SITE_DIR = '/fake/site';
+  const SCHEMAS_BASE_PATH = path.join(SITE_DIR, 'static', 'schemas');
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should return path to latest version when versions.json exists', () => {
+    fs.existsSync.mockImplementation(
+      (p) => p === path.join(SITE_DIR, 'versions.json'),
+    );
+    fs.readFileSync.mockReturnValue('["1.2.0", "1.1.1"]');
+    const result = gtmScript.getLatestSchemaPath(SITE_DIR);
+    expect(result).toBe(path.join(SCHEMAS_BASE_PATH, '1.2.0'));
+  });
+
+  it('should return path to "next" when versions.json does not exist', () => {
+    const nextPath = path.join(SCHEMAS_BASE_PATH, 'next');
+    fs.existsSync.mockImplementation((p) => p === nextPath);
+    const result = gtmScript.getLatestSchemaPath(SITE_DIR);
+    expect(result).toBe(nextPath);
+  });
+
+  it('should return base schemas path as fallback', () => {
+    fs.existsSync.mockReturnValue(false);
+    const result = gtmScript.getLatestSchemaPath(SITE_DIR);
+    expect(result).toBe(SCHEMAS_BASE_PATH);
+  });
+});
+
+describe('getVariablesFromSchemas', () => {
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  const SCHEMA_PATH = '/fake/schemas';
+  const mockFiles = {
+    [SCHEMA_PATH]: ['complex-event.json', 'components'],
+    [path.join(SCHEMA_PATH, 'components')]: ['address.json'],
+  };
+  const addressSchema = {
+    title: 'Address',
+    type: 'object',
+    properties: {
+      street: { type: 'string', description: 'Street name.' },
+      city: { type: 'string', description: 'City name.' },
+    },
+  };
+  const complexEventSchema = {
+    title: 'Complex Event',
+    type: 'object',
+    properties: {
+      $schema: { type: 'string', description: 'Should now be included.' },
+      event: { type: 'string', const: 'user_update' },
+      user_data: {
+        type: 'object',
+        properties: {
+          user_id: { type: 'string', description: 'The user ID.' },
+          addresses: {
+            type: 'array',
+            description: 'List of addresses.',
+            items: { $ref: './components/address.json' },
+          },
+        },
+      },
+      timestamp: { type: 'number', description: 'Event timestamp.' },
+    },
+  };
+  const mockFileContents = {
+    [path.join(SCHEMA_PATH, 'complex-event.json')]:
+      JSON.stringify(complexEventSchema),
+    [path.join(SCHEMA_PATH, 'components', 'address.json')]:
+      JSON.stringify(addressSchema),
+  };
+
+  beforeEach(() => {
+    fs.readdirSync.mockImplementation((p) => mockFiles[p] || []);
+    fs.statSync.mockImplementation((p) => ({
+      isDirectory: () => !!mockFiles[p],
+    }));
+    fs.readFileSync.mockImplementation((p) => mockFileContents[p] || '');
+    fs.existsSync.mockImplementation(
+      (p) => !!mockFiles[p] || !!mockFileContents[p],
+    );
+    RefParser.bundle.mockClear();
+  });
+
+  it('should find all top-level variables, including $schema', async () => {
+    const bundledSchema = JSON.parse(JSON.stringify(complexEventSchema));
+    bundledSchema.properties.user_data.properties.addresses.items =
+      addressSchema;
+    RefParser.bundle.mockResolvedValue(bundledSchema);
+
+    const result = await gtmScript.getVariablesFromSchemas(SCHEMA_PATH, {});
+
+    const expected = expect.arrayContaining([
+      expect.objectContaining({ name: '$schema' }),
+      expect.objectContaining({ name: 'event' }),
+      expect.objectContaining({ name: 'user_data' }),
+      expect.objectContaining({ name: 'user_data.user_id' }),
+      expect.objectContaining({ name: 'user_data.addresses' }),
+      expect.objectContaining({ name: 'user_data.addresses.0.street' }),
+      expect.objectContaining({ name: 'user_data.addresses.0.city' }),
+      expect.objectContaining({ name: 'timestamp' }),
+    ]);
+
+    expect(result.length).toBe(8);
+    expect(result).toEqual(expected);
+  });
+
+  it('should skip array sub-properties when skipArraySubProperties is true', async () => {
+    const bundledSchema = JSON.parse(JSON.stringify(complexEventSchema));
+    bundledSchema.properties.user_data.properties.addresses.items =
+      addressSchema;
+    RefParser.bundle.mockResolvedValue(bundledSchema);
+
+    const result = await gtmScript.getVariablesFromSchemas(SCHEMA_PATH, {
+      skipArraySubProperties: true,
+    });
+
+    const expected = [
+      '$schema',
+      'event',
+      'user_data',
+      'user_data.user_id',
+      'user_data.addresses',
+      'timestamp',
+    ];
+
+    expect(result.map((r) => r.name)).toEqual(expect.arrayContaining(expected));
+    expect(result.length).toBe(expected.length);
+  });
+});
+
+describe('GTM Synchronization Logic', () => {
+  const schemaVariables = [
+    { name: '$schema', description: 'The schema version.' },
+    { name: 'event', description: 'The event name.' },
+    { name: 'user_id', description: 'The user ID.' },
+  ];
+  const gtmVariables = [
+    {
+      name: 'DLV - event',
+      variableId: '1',
+      type: 'v',
+      parameter: [{ key: 'name', value: 'event' }],
+    },
+    {
+      name: 'DLV - old_variable',
+      variableId: '123',
+      type: 'v',
+      parameter: [{ key: 'name', value: 'old_variable' }],
+    },
+  ];
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('getVariablesToCreate', () => {
+    it('should return variables that are in schema but not in GTM', () => {
+      const toCreate = gtmScript.getVariablesToCreate(
+        schemaVariables,
+        gtmVariables,
+      );
+      expect(toCreate).toEqual([
+        { name: '$schema', description: 'The schema version.' },
+        { name: 'user_id', description: 'The user ID.' },
+      ]);
+    });
+  });
+
+  describe('getVariablesToDelete', () => {
+    it('should return variables that are in GTM but not in schema', () => {
+      const toDelete = gtmScript.getVariablesToDelete(
+        schemaVariables,
+        gtmVariables,
+      );
+      expect(toDelete).toEqual([
+        {
+          name: 'DLV - old_variable',
+          variableId: '123',
+          type: 'v',
+          parameter: [{ key: 'name', value: 'old_variable' }],
+        },
+      ]);
+    });
+  });
+
+  describe('createGtmVariables', () => {
+    it('should call execSync to create variables and return their names', () => {
+      const toCreate = gtmScript.getVariablesToCreate(
+        schemaVariables,
+        gtmVariables,
+      );
+      const created = gtmScript.createGtmVariables(toCreate);
+      expect(execSync).toHaveBeenCalledTimes(2);
+
+      const schemaVarConfig = JSON.stringify({
+        notes: "References the '$schema' property. The schema version.",
+        parameter: [
+          { type: 'INTEGER', key: 'dataLayerVersion', value: '2' },
+          { type: 'BOOLEAN', key: 'setDefaultValue', value: 'false' },
+          { type: 'TEMPLATE', key: 'name', value: '$schema' },
+        ],
+      });
+      expect(execSync).toHaveBeenCalledWith(
+        `gtm variables create --name "DLV - \\$schema" --type v --config '${schemaVarConfig}' --quiet`,
+        { stdio: 'inherit' },
+      );
+
+      const userIdVarConfig = JSON.stringify({
+        notes: 'The user ID.',
+        parameter: [
+          { type: 'INTEGER', key: 'dataLayerVersion', value: '2' },
+          { type: 'BOOLEAN', key: 'setDefaultValue', value: 'false' },
+          { type: 'TEMPLATE', key: 'name', value: 'user_id' },
+        ],
+      });
+      expect(execSync).toHaveBeenCalledWith(
+        `gtm variables create --name "DLV - user_id" --type v --config '${userIdVarConfig}' --quiet`,
+        { stdio: 'inherit' },
+      );
+      expect(created).toEqual(['$schema', 'user_id']);
+    });
+  });
+
+  describe('deleteGtmVariables', () => {
+    it('should call execSync to delete variables and return their names', () => {
+      const toDelete = gtmScript.getVariablesToDelete(
+        schemaVariables,
+        gtmVariables,
+      );
+      const deleted = gtmScript.deleteGtmVariables(toDelete);
+      expect(execSync).toHaveBeenCalledTimes(1);
+      expect(execSync).toHaveBeenCalledWith(
+        'gtm variables delete --variable-id 123 --force --quiet',
+        { stdio: 'inherit' },
+      );
+      expect(deleted).toEqual(['old_variable']);
+    });
+  });
+});
+
+describe('main function', () => {
+  let mockDeps;
+  let logSpy;
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+    fs.existsSync.mockReturnValue(true);
+    mockDeps = {
+      setupGtmWorkspace: jest.fn().mockResolvedValue({
+        workspaceName: 'test-workspace',
+        workspaceId: '123',
+      }),
+      syncGtmVariables: jest.fn().mockResolvedValue({
+        created: ['var1'],
+        deleted: ['var2'],
+        inSync: ['var3'],
+      }),
+      getVariablesFromSchemas: jest
+        .fn()
+        .mockResolvedValue([{ name: 'event', description: 'Event name' }]),
+      getLatestSchemaPath: jest.fn().mockReturnValue('/fake/schemas'),
+      assertGtmCliAvailable: jest.fn(),
+      logger: gtmScript.logger,
+      parseArgs: gtmScript.parseArgs,
+      process: {
+        exit: jest.fn(),
+      },
+    };
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('should run quietly when --quiet is passed', async () => {
+    const argv = ['node', 'script.js', '--quiet'];
+    await gtmScript.main(argv, mockDeps);
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
+  it('should output JSON when --json is passed', async () => {
+    const argv = ['node', 'script.js', '--json'];
+    await gtmScript.main(argv, mockDeps);
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(logSpy.mock.calls[0][0])).toEqual({
+      workspace: { workspaceName: 'test-workspace', workspaceId: '123' },
+      created: ['var1'],
+      deleted: ['var2'],
+      inSync: ['var3'],
+    });
+  });
+
+  it('should use the path from --path argument', async () => {
+    const argv = ['node', 'script.js', '--path=./my-demo'];
+    await gtmScript.main(argv, mockDeps);
+    expect(mockDeps.getLatestSchemaPath).toHaveBeenCalledWith('./my-demo');
+  });
+});

package/__tests__/validateSchemas.test.js

@@ -10,13 +10,16 @@ import validateSchemas from '../validateSchemas';
 describe('validateSchemas', () => {
   let tmpDir;
   let consoleErrorSpy;
-  let consoleLogSpy;
+  let consoleWarnSpy;
 
   beforeEach(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'schema-test-'));
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
   });
 
   afterEach(() => {
+    jest.restoreAllMocks();
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
@@ -50,4 +53,53 @@ describe('validateSchemas', () => {
     const result = await validateSchemas(schemaDir);
     expect(result).toBe(false);
   });
+
+  it('should warn and fallback to default target when x-tracking-targets is missing', async () => {
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(schemaDir, 'event.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: {
+          event: {
+            type: 'string',
+            const: 'test_event',
+          },
+        },
+        required: ['event'],
+      }),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(true);
+    expect(consoleWarnSpy).toHaveBeenCalled();
+    expect(consoleWarnSpy.mock.calls[0][0]).toContain('web-datalayer-js');
+  });
+
+  it('should fail when x-tracking-targets has an unsupported target', async () => {
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(schemaDir, 'event.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        'x-tracking-targets': ['web-not-supported-js'],
+        properties: {
+          event: {
+            type: 'string',
+            const: 'test_event',
+          },
+        },
+        required: ['event'],
+      }),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(false);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    expect(consoleErrorSpy.mock.calls[0][0]).toContain('x-tracking-targets');
+  });
 });

package/components/ExampleDataLayer.js

@@ -1,80 +1,215 @@
-import React from 'react';
+import React, { useEffect, useMemo } from 'react';
 import CodeBlock from '@theme/CodeBlock';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import Heading from '@theme/Heading';
-import { schemaToExamples } from '../helpers/schemaToExamples';
+import {
+  buildExampleModel,
+  findClearableProperties,
+} from '../helpers/exampleModel';
 
-const generateCodeSnippet = (example, schema, dataLayerName = 'dataLayer') => {
-  const clearableProperties = findClearableProperties(schema || {});
-  let codeSnippet = '';
-  const propertiesToClear = clearableProperties.filter(
-    (prop) => prop in example,
-  );
+const TARGET_HASH_KEY = 'target';
+const TARGET_HASH_PREFIX = `${TARGET_HASH_KEY}-`;
+const TARGET_STORAGE_KEY = 'tracking-docs-selected-target';
 
-  if (propertiesToClear.length > 0) {
-    const resetObject = {};
-    propertiesToClear.forEach((prop) => {
-      resetObject[prop] = null;
-    });
-    codeSnippet += `window.${dataLayerName}.push(${JSON.stringify(
-      resetObject,
-      null,
-      2,
-    )});\n`;
+function parseHashTarget(rawHash = '') {
+  const raw = rawHash.startsWith('#') ? rawHash.substring(1) : rawHash;
+  if (!raw) return null;
+  if (raw.startsWith(TARGET_HASH_PREFIX)) {
+    return raw.substring(TARGET_HASH_PREFIX.length) || null;
   }
+  return null;
+}
+
+function readHashTarget() {
+  if (typeof window === 'undefined') return null;
+  return parseHashTarget(window.location.hash || '');
+}
+
+function readSearchTarget(search = '') {
+  const query = search.startsWith('?') ? search.substring(1) : search;
+  if (!query) return null;
+  const params = new URLSearchParams(query);
+  return params.get(TARGET_HASH_KEY);
+}
 
-  codeSnippet += `window.${dataLayerName}.push(${JSON.stringify(
-    example,
+function persistTarget(targetId) {
+  if (typeof window === 'undefined') return;
+  window.localStorage.setItem(TARGET_STORAGE_KEY, targetId);
+  window.history.replaceState(
     null,
-    2,
-  )});`;
-  return codeSnippet;
-};
+    '',
+    `${window.location.pathname}${window.location.search}#${TARGET_HASH_PREFIX}${targetId}`,
+  );
+}
+
+function resolveInitialTargetId(targets) {
+  const safeTargets = Array.isArray(targets)
+    ? targets.filter((t) => t && typeof t.id === 'string' && t.id.length > 0)
+    : [];
+  if (safeTargets.length === 0) return null;
+  const validTargetIds = new Set(safeTargets.map((t) => t.id));
+
+  const fromHash = readHashTarget();
+  if (fromHash && validTargetIds.has(fromHash)) {
+    return fromHash;
+  }
+
+  if (typeof window !== 'undefined') {
+    const fromStorage = window.localStorage.getItem(TARGET_STORAGE_KEY);
+    if (fromStorage && validTargetIds.has(fromStorage)) {
+      return fromStorage;
+    }
+  }
+
+  return safeTargets[0].id;
+}
 
 export default function ExampleDataLayer({ schema, dataLayerName }) {
-  const exampleGroups = schemaToExamples(schema);
+  const model = useMemo(
+    () => buildExampleModel(schema, { dataLayerName }),
+    [schema, dataLayerName],
+  );
+  const safeTargets = useMemo(
+    () =>
+      (Array.isArray(model.targets) ? model.targets : []).filter(
+        (target) =>
+          target && typeof target.id === 'string' && target.id.length > 0,
+      ),
+    [model.targets],
+  );
+  const exampleGroups = model.variantGroups;
+  const targetId = resolveInitialTargetId(safeTargets);
+  const showTargetTabs = safeTargets.length > 1;
+  const validTargetIds = useMemo(
+    () => new Set(safeTargets.map((target) => target.id)),
+    [safeTargets],
+  );
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined;
+    let isSyncing = false;
+    const originalReplaceState = window.history.replaceState;
+
+    const syncFromSearch = () => {
+      if (isSyncing) return;
+      const targetFromSearch = readSearchTarget(window.location.search);
+      if (!targetFromSearch || !validTargetIds.has(targetFromSearch)) return;
+
+      isSyncing = true;
+      try {
+        window.localStorage.setItem(TARGET_STORAGE_KEY, targetFromSearch);
+
+        const searchParams = new URLSearchParams(window.location.search);
+        searchParams.delete(TARGET_HASH_KEY);
+        const remainingSearch = searchParams.toString();
+        const searchPart = remainingSearch ? `?${remainingSearch}` : '';
+
+        originalReplaceState.call(
+          window.history,
+          null,
+          '',
+          `${window.location.pathname}${searchPart}#${TARGET_HASH_PREFIX}${targetFromSearch}`,
+        );
+      } finally {
+        isSyncing = false;
+      }
+    };
+
+    syncFromSearch();
+    window.history.replaceState = function patchedReplaceState(...args) {
+      const result = originalReplaceState.apply(window.history, args);
+      syncFromSearch();
+      return result;
+    };
+
+    return () => {
+      window.history.replaceState = originalReplaceState;
+    };
+  }, [validTargetIds]);
 
   if (!exampleGroups || exampleGroups.length === 0) {
     return null;
   }
 
-  // Handle the simple case of a single default example with no choices
-  if (exampleGroups.length === 1 && exampleGroups[0].property === 'default') {
-    const codeSnippet = generateCodeSnippet(
-      exampleGroups[0].options[0].example,
-      schema,
-      dataLayerName,
+  const getLanguageForTarget = (targetIdForSnippet) =>
+    safeTargets.find((target) => target.id === targetIdForSnippet)?.language ||
+    'javascript';
+
+  const renderVariantGroups = (currentTargetId) => (
+    <>
+      {exampleGroups.map((group) => {
+        const showVariantTabs = group.options.length > 1;
+
+        if (!showVariantTabs) {
+          return (
+            <div key={group.property} style={{ marginTop: '20px' }}>
+              {!model.isSimpleDefault && (
+                <Heading as="h4">
+                  <code>{group.property}</code> options:
+                </Heading>
+              )}
+              <CodeBlock language={getLanguageForTarget(currentTargetId)}>
+                {group.options[0].snippets[currentTargetId]}
+              </CodeBlock>
+            </div>
+          );
+        }
+
+        return (
+          <div key={group.property} style={{ marginTop: '20px' }}>
+            <Heading as="h4">
+              <code>{group.property}</code> options:
+            </Heading>
+            <Tabs>
+              {group.options.map(({ id, title, snippets }) => (
+                <TabItem value={id} label={title} key={id}>
+                  <CodeBlock language={getLanguageForTarget(currentTargetId)}>
+                    {snippets[currentTargetId]}
+                  </CodeBlock>
+                </TabItem>
+              ))}
+            </Tabs>
+          </div>
+        );
+      })}
+    </>
+  );
+
+  // Single target + single default variant => keep old layout
+  if (!showTargetTabs && model.isSimpleDefault) {
+    const snippets = exampleGroups[0].options[0].snippets || {};
+    const codeSnippet =
+      (targetId && snippets[targetId]) || Object.values(snippets)[0] || '';
+    return (
+      <CodeBlock language={getLanguageForTarget(targetId)}>
+        {codeSnippet}
+      </CodeBlock>
     );
-    return <CodeBlock language="javascript">{codeSnippet}</CodeBlock>;
+  }
+
+  if (!showTargetTabs) {
+    return renderVariantGroups(targetId);
   }
 
   return (
-    <>
-      {exampleGroups.map((group) => (
-        <div key={group.property} style={{ marginTop: '20px' }}>
-          <Heading as="h4">
-            <code>{group.property}</code> options:
-          </Heading>
-          <Tabs>
-            {group.options.map(({ title, example }, index) => (
-              <TabItem value={index} label={title} key={index}>
-                <CodeBlock language="javascript">
-                  {generateCodeSnippet(example, schema, dataLayerName)}
-                </CodeBlock>
-              </TabItem>
-            ))}
-          </Tabs>
-        </div>
-      ))}
-    </>
+    <div data-testid="target-tabs">
+      <Tabs defaultValue={targetId} queryString={TARGET_HASH_KEY}>
+        {safeTargets.map((target) => (
+          <TabItem value={target.id} label={target.label} key={target.id}>
+            <span id={`${TARGET_HASH_PREFIX}${target.id}`} />
+            {renderVariantGroups(target.id)}
+          </TabItem>
+        ))}
+      </Tabs>
+    </div>
   );
 }
 
-export const findClearableProperties = (schema) => {
-  if (!schema || !schema.properties) return [];
-
-  return Object.entries(schema.properties)
-    .filter(([, definition]) => definition['x-gtm-clear'] === true)
-    .map(([key]) => key);
+export {
+  findClearableProperties,
+  resolveInitialTargetId,
+  readHashTarget,
+  readSearchTarget,
+  TARGET_STORAGE_KEY,
 };