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

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,
 };

package/components/PropertyRow.js

@@ -125,6 +125,7 @@ export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
           rowSpan={rowSpan}
           style={{ ...indentStyle, ...continuingLinesStyle }}
           className={clsx(
+            'property-cell',
             level > 0 && `level-${level}`,
             isLastInGroup && 'is-last',
             hasChildren && 'has-children',
@@ -143,7 +144,7 @@ export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
         </td>
 
         {/* The first constraint cell */}
-        <td>
+        <td className="constraint-cell">
           {firstConstraint && (
             <code
               className={clsx(
@@ -181,7 +182,7 @@ 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}>
-          <td>
+          <td className="constraint-cell">
             <code
               className={clsx(
                 'constraint-code',

package/components/SchemaRows.css

@@ -63,10 +63,19 @@
 }
 
 .schema-table th:first-child,
-.schema-table td:first-child {
+.schema-table td.property-cell {
   border-left: none;
 }
 
+/*
+ * Constraint-only continuation rows render a single cell; in those rows that
+ * cell is also :first-child, but it still needs the separator before the
+ * "Constraints" column.
+ */
+.schema-table td.constraint-cell {
+  border-left: 1px solid var(--ifm-table-border-color);
+}
+
 .schema-table thead th {
   border-bottom: 2px solid var(--ifm-table-border-color);
 }

package/helpers/exampleModel.js

@@ -0,0 +1,70 @@
+import { schemaToExamples } from './schemaToExamples';
+import {
+  DEFAULT_SNIPPET_TARGET_ID,
+  findClearableProperties,
+  generateSnippetForTarget,
+  getSnippetTarget,
+} from './snippetTargets';
+
+export function resolveExampleTargets(schema) {
+  const configured = schema?.['x-tracking-targets'];
+  const targetIds =
+    Array.isArray(configured) && configured.length > 0
+      ? configured
+      : [DEFAULT_SNIPPET_TARGET_ID];
+
+  const targets = targetIds
+    .map((id) => {
+      try {
+        return getSnippetTarget(id);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  if (targets.length > 0) return targets;
+  return [getSnippetTarget(DEFAULT_SNIPPET_TARGET_ID)];
+}
+
+export function buildExampleModel(schema, { dataLayerName } = {}) {
+  const exampleGroups = schemaToExamples(schema);
+  const targets = resolveExampleTargets(schema);
+
+  if (!exampleGroups || exampleGroups.length === 0) {
+    return {
+      targets,
+      variantGroups: [],
+      isSimpleDefault: false,
+    };
+  }
+
+  const variantGroups = exampleGroups.map((group) => ({
+    property: group.property,
+    options: group.options.map((option, index) => ({
+      id: `${group.property}-${index}`,
+      title: option.title,
+      example: option.example,
+      snippets: Object.fromEntries(
+        targets.map((target) => [
+          target.id,
+          generateSnippetForTarget({
+            targetId: target.id,
+            example: option.example,
+            schema,
+            dataLayerName,
+          }),
+        ]),
+      ),
+    })),
+  }));
+
+  return {
+    targets,
+    variantGroups,
+    isSimpleDefault:
+      variantGroups.length === 1 && variantGroups[0].property === 'default',
+  };
+}
+
+export { findClearableProperties };

package/helpers/schema-processing.js

@@ -1,5 +1,33 @@
 import path from 'path';
+import fs from 'fs';
 import processSchema from './processSchema.js';
+import mergeJsonSchema from 'json-schema-merge-allof';
+
+function mergePropertySchemas(baseProperties = {}, optionProperties = {}) {
+  const mergedProperties = {
+    ...baseProperties,
+    ...optionProperties,
+  };
+
+  for (const key of Object.keys(baseProperties)) {
+    if (!Object.prototype.hasOwnProperty.call(optionProperties, key)) {
+      continue;
+    }
+
+    mergedProperties[key] = mergeJsonSchema(
+      {
+        allOf: [baseProperties[key], optionProperties[key]],
+      },
+      {
+        resolvers: {
+          defaultResolver: mergeJsonSchema.options.resolvers.title,
+        },
+      },
+    );
+  }
+
+  return mergedProperties;
+}
 
 export function slugify(text) {
   if (!text) {
@@ -20,7 +48,15 @@ export async function processOneOfSchema(schema, filePath) {
   const choiceType = schema.oneOf ? 'oneOf' : null;
 
   if (choiceType) {
-    const parentWithoutChoice = { ...schema };
+    let parentSchema = schema;
+
+    // When the root schema is loaded from disk, use its processed form so
+    // parent-level allOf refs (e.g. shared dataLayer metadata) are preserved.
+    if (filePath && fs.existsSync(filePath)) {
+      parentSchema = await processSchema(filePath);
+    }
+
+    const parentWithoutChoice = { ...parentSchema };
     delete parentWithoutChoice[choiceType];
 
     for (const option of schema[choiceType]) {
@@ -34,10 +70,10 @@ export async function processOneOfSchema(schema, filePath) {
 
       // Merge the parent schema with the resolved option schema
       const newSchema = { ...parentWithoutChoice, ...resolvedOption };
-      newSchema.properties = {
-        ...parentWithoutChoice.properties,
-        ...resolvedOption.properties,
-      };
+      newSchema.properties = mergePropertySchemas(
+        parentWithoutChoice.properties,
+        resolvedOption.properties,
+      );
 
       let slug;
       const hadId = resolvedOption.$id && resolvedOption.$id.endsWith('.json');

package/helpers/schemaToExamples.js

@@ -63,18 +63,61 @@ const generateExampleForChoice = (rootSchema, path, option) => {
   }
 };
 
+const pruneSiblingConditionalProperties = (
+  mergedSchema,
+  activeBranchSchema,
+  inactiveBranchSchema,
+  baseRequired = [],
+) => {
+  const branchesOnlyAdjustRequired =
+    !activeBranchSchema?.properties && !inactiveBranchSchema?.properties;
+
+  if (
+    !mergedSchema?.properties ||
+    !branchesOnlyAdjustRequired ||
+    !Array.isArray(inactiveBranchSchema?.required)
+  ) {
+    return mergedSchema;
+  }
+
+  const activeRequired = new Set(activeBranchSchema?.required || []);
+  const protectedRequired = new Set(baseRequired);
+
+  inactiveBranchSchema.required.forEach((name) => {
+    if (activeRequired.has(name) || protectedRequired.has(name)) {
+      return;
+    }
+
+    delete mergedSchema.properties[name];
+    if (Array.isArray(mergedSchema.required)) {
+      mergedSchema.required = mergedSchema.required.filter(
+        (requiredName) => requiredName !== name,
+      );
+    }
+  });
+
+  return mergedSchema;
+};
+
 const generateConditionalExample = (rootSchema, path, branch) => {
   const schemaVariant = JSON.parse(JSON.stringify(rootSchema));
+  const siblingBranch = branch === 'then' ? 'else' : 'then';
 
   if (path.length === 0) {
     const branchSchema = schemaVariant[branch];
+    const siblingBranchSchema = schemaVariant[siblingBranch];
+    const baseRequired = schemaVariant.required || [];
     delete schemaVariant.if;
     delete schemaVariant.then;
     delete schemaVariant.else;
     if (branchSchema) {
-      return buildExampleFromSchema(
+      const merged = pruneSiblingConditionalProperties(
         mergeJsonSchema({ allOf: [schemaVariant, branchSchema] }),
+        branchSchema,
+        siblingBranchSchema,
+        baseRequired,
       );
+      return buildExampleFromSchema(merged);
     }
     return buildExampleFromSchema(schemaVariant);
   }
@@ -84,11 +127,18 @@ const generateConditionalExample = (rootSchema, path, branch) => {
     target = target[segment];
   }
   const branchSchema = target[branch];
+  const siblingBranchSchema = target[siblingBranch];
+  const baseRequired = target.required || [];
   delete target.if;
   delete target.then;
   delete target.else;
   if (branchSchema) {
-    const merged = mergeJsonSchema({ allOf: [target, branchSchema] });
+    const merged = pruneSiblingConditionalProperties(
+      mergeJsonSchema({ allOf: [target, branchSchema] }),
+      branchSchema,
+      siblingBranchSchema,
+      baseRequired,
+    );
     Object.keys(target).forEach((k) => delete target[k]);
     Object.assign(target, merged);
   }

package/helpers/schemaToTableData.js

@@ -11,6 +11,36 @@ function computeOwnBracket(level, parentGroupBrackets) {
   return { level, bracketIndex };
 }
 
+function materializeConditionalBranchSchema(branchSchema, parentSchema) {
+  if (
+    !branchSchema ||
+    branchSchema.properties ||
+    branchSchema.oneOf ||
+    branchSchema.anyOf ||
+    branchSchema.if ||
+    !Array.isArray(branchSchema.required) ||
+    !parentSchema?.properties
+  ) {
+    return branchSchema;
+  }
+
+  const branchProperties = Object.fromEntries(
+    branchSchema.required
+      .filter((name) => parentSchema.properties[name])
+      .map((name) => [name, parentSchema.properties[name]]),
+  );
+
+  if (Object.keys(branchProperties).length === 0) {
+    return branchSchema;
+  }
+
+  return {
+    ...branchSchema,
+    type: 'object',
+    properties: branchProperties,
+  };
+}
+
 function processOptions(
   choices,
   level,
@@ -144,11 +174,15 @@ export function schemaToTableData(
       // Then is NOT the last branch if Else exists — use innerContinuingLevels
       // to keep the parent line flowing. If Then IS the last branch, use original.
       const thenLevels = hasElse ? innerContinuingLevels : continuingLevels;
+      const thenSchema = materializeConditionalBranchSchema(
+        subSchema.then,
+        subSchema,
+      );
       branches.push({
         title: 'Then',
         description: subSchema.then.description,
         rows: schemaToTableData(
-          subSchema.then,
+          thenSchema,
           currentLevel,
           currentPath,
           thenLevels,
@@ -160,11 +194,15 @@ export function schemaToTableData(
     }
     if (hasElse) {
       // Else is always the last branch — use original continuingLevels
+      const elseSchema = materializeConditionalBranchSchema(
+        subSchema.else,
+        subSchema,
+      );
       branches.push({
         title: 'Else',
         description: subSchema.else.description,
         rows: schemaToTableData(
-          subSchema.else,
+          elseSchema,
           currentLevel,
           currentPath,
           continuingLevels,