docusaurus-plugin-generate-schema-docs 1.8.3 → 1.8.4

package/components/PropertyRow.js

@@ -26,6 +26,19 @@ const getContainerSymbol = (containerType) => {
   return '';
 };
 
+const formatPropertyType = (value) => {
+  if (Array.isArray(value)) {
+    return value.join(', ');
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (value === undefined || value === null) {
+    return '';
+  }
+  return JSON.stringify(value);
+};
+
 const KEYWORD_HELP_TEXT = {
   additionalProperties:
     'Controls properties not listed in properties and not matched by patternProperties.',
@@ -33,6 +46,8 @@ const KEYWORD_HELP_TEXT = {
     'Applies the subschema to property names that match the given regular expression.',
 };
 
+const SCHEMA_KEYWORD_BADGE_TEXT = 'Schema constraint';
+
 function splitKeywordLabel(name) {
   const match = /^patternProperties (\/.+\/)$/.exec(name);
   if (!match) {
@@ -45,6 +60,15 @@ function splitKeywordLabel(name) {
   };
 }
 
+function buildKeywordHelpId(name, rowPath) {
+  if (!rowPath || rowPath.length === 0) {
+    return `schema-keyword-help-${name}`;
+  }
+
+  const normalizedPath = rowPath.join('-').replace(/[^a-zA-Z0-9_-]/g, '_');
+  return `schema-keyword-help-${normalizedPath}`;
+}
+
 /**
  * Renders a single property row in the schema table.
  * All data is passed in via the `row` prop, which comes from `tableData`.
@@ -145,7 +169,7 @@ export default function PropertyRow({
     : name;
   const keywordHelpText = KEYWORD_HELP_TEXT[keywordHelpKey];
   const keywordHelpId = keywordHelpText
-    ? `schema-keyword-help-${name}`
+    ? buildKeywordHelpId(name, row.path)
     : undefined;
   const zebraClassName =
     stripeIndex === undefined
@@ -208,6 +232,9 @@ export default function PropertyRow({
                     {name}
                   </code>
                 )}
+                <span className="property-keyword-badge">
+                  {SCHEMA_KEYWORD_BADGE_TEXT}
+                </span>
                 <span
                   id={keywordHelpId}
                   className="property-keyword-tooltip"
@@ -222,7 +249,7 @@ export default function PropertyRow({
           </span>
         </td>
         <td rowSpan={rowSpan}>
-          <code>{propertyType}</code>
+          <code>{formatPropertyType(propertyType)}</code>
         </td>
 
         {/* The first constraint cell */}

package/components/SchemaJsonViewer.js

@@ -1,14 +1,43 @@
-import React, { Fragment, useState } from 'react';
+import React, { useState } from 'react';
 import Link from '@docusaurus/Link';
+import { usePrismTheme } from '@docusaurus/theme-common';
+import { Highlight } from 'prism-react-renderer';
 
-function isPlainObject(value) {
-  return (
-    value !== null &&
-    typeof value === 'object' &&
-    !Array.isArray(value) &&
-    Object.getPrototypeOf(value) === Object.prototype
-  );
-}
+const SCHEMA_META_KEYS = [
+  '$schema',
+  '$id',
+  '$anchor',
+  '$dynamicAnchor',
+  '$comment',
+  '$vocabulary',
+];
+
+const SCHEMA_STRUCTURAL_KEYS = new Set([
+  '$ref',
+  '$defs',
+  'properties',
+  'required',
+  'allOf',
+  'anyOf',
+  'oneOf',
+  'if',
+  'then',
+  'else',
+  'not',
+  'items',
+  'prefixItems',
+  'contains',
+  'dependentSchemas',
+  'patternProperties',
+  'additionalProperties',
+]);
+
+const SCHEMA_NAME_MAP_KEYS = new Set([
+  'properties',
+  'patternProperties',
+  '$defs',
+  'dependentSchemas',
+]);
 
 function isExternalRef(value) {
   return typeof value === 'string' && /^https?:\/\//.test(value);
@@ -51,137 +80,189 @@ function resolveLocalRef(currentPath, refValue) {
   return normalizePathSegments(`${dirname(currentPath)}/${refValue}`);
 }
 
-function JsonIndent({ depth }) {
-  return <span>{'  '.repeat(depth)}</span>;
+function getSchemaKeywordClassName(key, parentKey) {
+  if (parentKey && SCHEMA_NAME_MAP_KEYS.has(parentKey)) {
+    return '';
+  }
+
+  if (SCHEMA_META_KEYS.includes(key)) {
+    return 'schema-json-viewer__keyword schema-json-viewer__keyword--meta';
+  }
+
+  if (SCHEMA_STRUCTURAL_KEYS.has(key)) {
+    return 'schema-json-viewer__keyword schema-json-viewer__keyword--structural';
+  }
+
+  return '';
 }
 
-function JsonPrimitive({
-  value,
-  propertyKey,
-  currentPath,
-  schemaSources,
-  onNavigate,
-}) {
-  const interactiveRefClassName = 'schema-json-viewer__link';
-  const quotedValue = `${JSON.stringify(value)}`;
-
-  if (typeof value === 'string') {
-    if (propertyKey === '$ref') {
-      if (isExternalRef(value)) {
-        return (
-          <Link
-            className={interactiveRefClassName}
-            href={value}
-            target="_blank"
-            rel="noreferrer"
-          >
-            {quotedValue}
-          </Link>
-        );
-      }
-
-      const resolvedRef = resolveLocalRef(currentPath, value);
-      if (resolvedRef && schemaSources?.[resolvedRef]) {
-        return (
-          <button
-            type="button"
-            className={interactiveRefClassName}
-            onClick={() => onNavigate(resolvedRef)}
-          >
-            {quotedValue}
-          </button>
-        );
-      }
+function joinClassNames(...classNames) {
+  return classNames.filter(Boolean).join(' ');
+}
+
+function createParserState() {
+  return {
+    stack: [],
+  };
+}
+
+function beginNestedValue(state, tokenContent) {
+  const currentContext = state.stack[state.stack.length - 1];
+  let parentKey = null;
+
+  if (currentContext?.type === 'object' && currentContext.afterColon) {
+    parentKey = currentContext.currentKey;
+    currentContext.currentKey = null;
+    currentContext.afterColon = false;
+  }
+
+  state.stack.push({
+    type: tokenContent === '{' ? 'object' : 'array',
+    parentKey,
+    currentKey: null,
+    afterColon: false,
+  });
+}
+
+function classifyRenderedToken(state, token) {
+  const currentContext = state.stack[state.stack.length - 1];
+  const tokenTypes = new Set(token.types);
+  const content = token.content;
+  const semantic = {};
+
+  if (!content) {
+    return semantic;
+  }
+
+  if (tokenTypes.has('property')) {
+    const key = JSON.parse(content);
+    semantic.propertyKey = key;
+    semantic.parentKey = currentContext?.parentKey ?? null;
+
+    if (currentContext?.type === 'object') {
+      currentContext.currentKey = key;
+      currentContext.afterColon = false;
     }
 
-    return <span className="token string">{quotedValue}</span>;
+    return semantic;
+  }
+
+  if (content === ':') {
+    if (
+      currentContext?.type === 'object' &&
+      currentContext.currentKey !== null
+    ) {
+      currentContext.afterColon = true;
+    }
+    return semantic;
   }
 
-  if (typeof value === 'number') {
-    return <span className="token number">{value}</span>;
+  if (content === '{' || content === '[') {
+    beginNestedValue(state, content);
+    return semantic;
   }
 
-  if (typeof value === 'boolean') {
-    return <span className="token boolean">{String(value)}</span>;
+  if (content === '}' || content === ']') {
+    state.stack.pop();
+    return semantic;
   }
 
-  return <span className="token null keyword">null</span>;
+  if (content === ',') {
+    if (currentContext?.type === 'object') {
+      currentContext.currentKey = null;
+      currentContext.afterColon = false;
+    }
+    return semantic;
+  }
+
+  if (currentContext?.type === 'object' && currentContext.afterColon) {
+    if (tokenTypes.has('string') && content.trim().startsWith('"')) {
+      semantic.valueKey = currentContext.currentKey;
+      semantic.stringValue = JSON.parse(content);
+      currentContext.currentKey = null;
+      currentContext.afterColon = false;
+      return semantic;
+    }
+
+    if (
+      tokenTypes.has('number') ||
+      tokenTypes.has('boolean') ||
+      (tokenTypes.has('keyword') && content === 'null')
+    ) {
+      currentContext.currentKey = null;
+      currentContext.afterColon = false;
+    }
+  }
+
+  return semantic;
 }
 
-function JsonNode({
-  value,
-  depth,
+function renderToken({
+  token,
+  tokenIndex,
+  getTokenProps,
+  semantic,
   currentPath,
   schemaSources,
   onNavigate,
-  propertyKey = null,
 }) {
-  if (Array.isArray(value)) {
-    return (
-      <>
-        <span className="token punctuation">[</span>
-        {value.length > 0 && <br />}
-        {value.map((item, index) => (
-          <Fragment key={`${depth}-${index}`}>
-            <JsonIndent depth={depth + 1} />
-            <JsonNode
-              value={item}
-              depth={depth + 1}
-              currentPath={currentPath}
-              schemaSources={schemaSources}
-              onNavigate={onNavigate}
-            />
-            {index < value.length - 1 && (
-              <span className="token punctuation">,</span>
-            )}
-            <br />
-          </Fragment>
-        ))}
-        {value.length > 0 && <JsonIndent depth={depth} />}
-        <span className="token punctuation">]</span>
-      </>
-    );
-  }
+  const tokenProps = getTokenProps({ token, key: tokenIndex });
+  const propertyKeyClassName = semantic.propertyKey
+    ? getSchemaKeywordClassName(semantic.propertyKey, semantic.parentKey)
+    : '';
+  const className = joinClassNames(tokenProps.className, propertyKeyClassName);
+
+  if (
+    semantic.valueKey === '$ref' &&
+    typeof semantic.stringValue === 'string'
+  ) {
+    if (isExternalRef(semantic.stringValue)) {
+      return (
+        <Link
+          key={tokenIndex}
+          className={joinClassNames(
+            className,
+            'schema-json-viewer__link',
+            'schema-json-viewer__ref-link',
+          )}
+          style={tokenProps.style}
+          href={semantic.stringValue}
+          target="_blank"
+          rel="noreferrer"
+        >
+          {token.content}
+        </Link>
+      );
+    }
 
-  if (isPlainObject(value)) {
-    const entries = Object.entries(value);
-    return (
-      <>
-        <span className="token punctuation">{'{'}</span>
-        {entries.length > 0 && <br />}
-        {entries.map(([key, child], index) => (
-          <Fragment key={`${depth}-${key}`}>
-            <JsonIndent depth={depth + 1} />
-            <span className="token property">{JSON.stringify(key)}</span>
-            <span className="token punctuation">: </span>
-            <JsonNode
-              value={child}
-              depth={depth + 1}
-              currentPath={currentPath}
-              schemaSources={schemaSources}
-              onNavigate={onNavigate}
-              propertyKey={key}
-            />
-            {index < entries.length - 1 && (
-              <span className="token punctuation">,</span>
-            )}
-            <br />
-          </Fragment>
-        ))}
-        {entries.length > 0 && <JsonIndent depth={depth} />}
-        <span className="token punctuation">{'}'}</span>
-      </>
-    );
+    const resolvedRef = resolveLocalRef(currentPath, semantic.stringValue);
+    if (resolvedRef && schemaSources?.[resolvedRef]) {
+      return (
+        <button
+          key={tokenIndex}
+          type="button"
+          className={joinClassNames(
+            className,
+            'schema-json-viewer__link',
+            'schema-json-viewer__ref-link',
+          )}
+          style={tokenProps.style}
+          onClick={() => onNavigate(resolvedRef)}
+        >
+          {token.content}
+        </button>
+      );
+    }
   }
 
   return (
-    <JsonPrimitive
-      value={value}
-      propertyKey={propertyKey}
-      currentPath={currentPath}
-      schemaSources={schemaSources}
-      onNavigate={onNavigate}
-    />
+    <span
+      key={tokenIndex}
+      className={className || tokenProps.className}
+      style={tokenProps.style}
+    >
+      {token.content}
+    </span>
   );
 }
 
@@ -190,6 +271,7 @@ export default function SchemaJsonViewer({
   sourcePath = null,
   schemaSources = null,
 }) {
+  const prismTheme = usePrismTheme();
   const resolvedSchemaSources =
     schemaSources || (sourcePath ? { [sourcePath]: schema } : {});
   const rootPath = sourcePath;
@@ -197,6 +279,7 @@ export default function SchemaJsonViewer({
 
   const currentSchema =
     (currentPath && resolvedSchemaSources?.[currentPath]) || schema;
+  const formattedSchema = JSON.stringify(currentSchema, null, 2);
 
   return (
     <details className="schema-json-viewer">
@@ -212,17 +295,37 @@ export default function SchemaJsonViewer({
           </button>
         </div>
       ) : null}
-      <pre data-language="json">
-        <code className="language-json">
-          <JsonNode
-            value={currentSchema}
-            depth={0}
-            currentPath={currentPath}
-            schemaSources={resolvedSchemaSources}
-            onNavigate={setCurrentPath}
-          />
-        </code>
-      </pre>
+      <Highlight code={formattedSchema} language="json" theme={prismTheme}>
+        {({ className, style, tokens, getLineProps, getTokenProps }) => {
+          const parserState = createParserState();
+
+          return (
+            <pre className={className} style={style} data-language="json">
+              <code className="language-json">
+                {tokens.map((line, lineIndex) => (
+                  <span
+                    key={lineIndex}
+                    {...getLineProps({ line, key: lineIndex })}
+                  >
+                    {line.map((token, tokenIndex) =>
+                      renderToken({
+                        token,
+                        tokenIndex,
+                        getTokenProps,
+                        semantic: classifyRenderedToken(parserState, token),
+                        currentPath,
+                        schemaSources: resolvedSchemaSources,
+                        onNavigate: setCurrentPath,
+                      }),
+                    )}
+                    {'\n'}
+                  </span>
+                ))}
+              </code>
+            </pre>
+          );
+        }}
+      </Highlight>
     </details>
   );
 }

package/components/SchemaRows.css

@@ -46,6 +46,29 @@
   text-decoration: underline;
 }
 
+.schema-json-viewer__ref-link {
+  text-decoration: underline;
+  text-decoration-thickness: 1.5px;
+  text-underline-offset: 0.14em;
+}
+
+.schema-json-viewer__ref-link:hover {
+  color: var(--ifm-link-hover-color) !important;
+  text-decoration-thickness: 2px;
+}
+
+.schema-json-viewer__keyword {
+  font-weight: 600;
+}
+
+.schema-json-viewer__keyword--meta {
+  color: var(--ifm-color-info-light);
+}
+
+.schema-json-viewer__keyword--structural {
+  color: var(--ifm-color-success-light);
+}
+
 /* --- Property Name and Container Symbol Styles --- */
 
 .property-name {
@@ -62,6 +85,8 @@
   position: relative;
   display: inline-flex;
   align-items: center;
+  flex-wrap: wrap;
+  gap: 0.35rem;
 }
 
 .property-keyword-stack {
@@ -76,6 +101,21 @@
   font-weight: 600;
 }
 
+.property-keyword-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.1rem 0.4rem;
+  border-radius: 999px;
+  border: 1px solid var(--ifm-table-border-color);
+  background-color: var(--ifm-color-emphasis-100);
+  color: var(--ifm-color-emphasis-800);
+  font-size: 0.68rem;
+  font-weight: 700;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
 .property-keyword-pattern {
   font-size: 0.85em;
   color: var(--ifm-color-emphasis-700);

package/components/SchemaViewer.js

@@ -3,7 +3,16 @@ import Heading from '@theme/Heading';
 import ExampleDataLayer from './ExampleDataLayer';
 import PropertiesTable from './PropertiesTable';
 
-export default function SchemaViewer({ schema, dataLayerName }) {
+export default function SchemaViewer({
+  schema,
+  sourceSchema,
+  sourcePath,
+  schemaSources,
+  dataLayerName,
+}) {
+  const resolvedSourceSchema =
+    (sourcePath && schemaSources?.[sourcePath]) || sourceSchema || schema;
+
   const hasOneOfAnyOf =
     schema.oneOf ||
     schema.anyOf ||
@@ -21,7 +30,7 @@ export default function SchemaViewer({ schema, dataLayerName }) {
       <ExampleDataLayer schema={schema} dataLayerName={dataLayerName} />
 
       <Heading as="h2">Event Properties</Heading>
-      <PropertiesTable schema={schema} />
+      <PropertiesTable schema={schema} sourceSchema={resolvedSourceSchema} />
     </div>
   );
 }

package/helpers/example-helper.js

@@ -5,7 +5,7 @@ export function getSingleExampleValue(propSchema) {
   if (propSchema.examples?.length > 0) {
     return propSchema.examples[0];
   }
-  if (propSchema.example) {
+  if (Object.prototype.hasOwnProperty.call(propSchema, 'example')) {
     return propSchema.example;
   }
   if (Object.prototype.hasOwnProperty.call(propSchema, 'default')) {
@@ -25,7 +25,7 @@ export function getExamples(propSchema) {
     examples.push(...propSchema.examples);
   }
 
-  if (propSchema.example) {
+  if (Object.prototype.hasOwnProperty.call(propSchema, 'example')) {
     if (!examples.includes(propSchema.example)) {
       examples.push(propSchema.example);
     }

package/helpers/getConstraints.js

@@ -1,4 +1,23 @@
 // A list of JSON Schema keywords that have simple key-value constraints.
+function formatInlineConstraintValue(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => formatInlineConstraintValue(item)).join(', ')}]`;
+  }
+
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).map(
+      ([key, nested]) => `${key}: ${formatInlineConstraintValue(nested)}`,
+    );
+    return `{ ${entries.join(', ')} }`;
+  }
+
+  return JSON.stringify(value);
+}
+
+function formatNotConstraint(val) {
+  return `not: ${formatInlineConstraintValue(val)}`;
+}
+
 const constraintHandlers = {
   // Simple key-value constraints
   minLength: (val) => `minLength: ${val}`,
@@ -32,6 +51,7 @@ const constraintHandlers = {
   contains: (val) => `contains: ${JSON.stringify(val)}`,
   enum: (val) => `enum: [${val.join(', ')}]`,
   const: (val) => `const: ${JSON.stringify(val)}`,
+  not: (val) => formatNotConstraint(val),
 };
 
 export const getConstraints = (prop, isReq) => {

package/helpers/processSchema.js

@@ -3,6 +3,37 @@ import fs from 'fs';
 import { resolveConstraintSchemaPath } from './constraintSchemaPaths.js';
 import { mergeSchema } from './mergeSchema.js';
 
+function unwrapRedundantNotAnyOf(node) {
+  if (!node || typeof node !== 'object') {
+    return node;
+  }
+
+  if (Array.isArray(node)) {
+    return node.map(unwrapRedundantNotAnyOf);
+  }
+
+  const normalized = {};
+  for (const [key, value] of Object.entries(node)) {
+    normalized[key] = unwrapRedundantNotAnyOf(value);
+  }
+
+  if (normalized.not && typeof normalized.not === 'object') {
+    let candidate = normalized.not;
+    while (
+      candidate &&
+      typeof candidate === 'object' &&
+      !Array.isArray(candidate) &&
+      Array.isArray(candidate.anyOf) &&
+      candidate.anyOf.length === 1
+    ) {
+      candidate = candidate.anyOf[0];
+    }
+    normalized.not = candidate;
+  }
+
+  return normalized;
+}
+
 /**
  * Processes a JSON schema file by bundling external references,
  * dereferencing internal references, and merging allOf properties.
@@ -41,5 +72,5 @@ export default async function processSchema(filePath) {
   // Then merge allOf properties
   const mergedSchema = mergeSchema(dereferencedSchema);
 
-  return mergedSchema;
+  return unwrapRedundantNotAnyOf(mergedSchema);
 }