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

package/components/FoldableRows.js

@@ -18,7 +18,7 @@ const ChoiceRow = ({
   name,
   continuingLinesStyle,
 }) => (
-  <tr className="choice-row">
+  <tr className="choice-row schema-row--control">
     <td colSpan={5} style={continuingLinesStyle}>
       <label className="choice-row-header">
         <input
@@ -41,7 +41,12 @@ const ChoiceRow = ({
  * Renders 'oneOf' and 'anyOf' choices as a set of foldable `<tr>` elements
  * that integrate directly into the main table body.
  */
-export default function FoldableRows({ row, bracketEnds: parentBracketEnds }) {
+export default function FoldableRows({
+  row,
+  stripeIndex = 0,
+  stripeState,
+  bracketEnds: parentBracketEnds,
+}) {
   const {
     choiceType,
     options,
@@ -136,7 +141,7 @@ export default function FoldableRows({ row, bracketEnds: parentBracketEnds }) {
   return (
     <>
       {/* A header row for the entire choice block */}
-      <tr>
+      <tr className="schema-row--control">
         <td colSpan={5} style={headerStyle}>
           <Heading as="h4" className="choice-row-header-headline">
             {header}
@@ -176,6 +181,7 @@ export default function FoldableRows({ row, bracketEnds: parentBracketEnds }) {
             {isActive && (
               <SchemaRows
                 tableData={option.rows}
+                stripeState={stripeState}
                 bracketEnds={
                   isLastOption
                     ? [ownBracket, ...(parentBracketEnds || [])]

package/components/PropertiesTable.js

@@ -5,9 +5,40 @@ import WordWrapButton from './WordWrapButton';
 import { schemaToTableData } from '../helpers/schemaToTableData';
 import styles from './PropertiesTable.module.css';
 
-export default function PropertiesTable({ schema }) {
+function filterInheritedTopLevelProperties(schema, sourceSchema) {
+  if (!schema?.properties || !sourceSchema?.properties) {
+    return schema;
+  }
+
+  const sourceKeys = new Set(Object.keys(sourceSchema.properties));
+  const filteredEntries = Object.entries(schema.properties).filter(
+    ([key, propSchema]) => {
+      if (sourceKeys.has(key)) {
+        return true;
+      }
+
+      const hasDescription =
+        typeof propSchema?.description === 'string' &&
+        propSchema.description.trim().length > 0;
+      const hasExamples =
+        Array.isArray(propSchema?.examples) && propSchema.examples.length > 0;
+      const hasExample = propSchema?.example !== undefined;
+
+      return hasDescription || hasExamples || hasExample;
+    },
+  );
+
+  return {
+    ...schema,
+    properties: Object.fromEntries(filteredEntries),
+  };
+}
+
+export default function PropertiesTable({ schema, sourceSchema }) {
   const [isWordWrapOn, setIsWordWrapOn] = useState(true);
-  const tableData = schemaToTableData(schema);
+  const tableSchema = filterInheritedTopLevelProperties(schema, sourceSchema);
+  const tableData = schemaToTableData(tableSchema);
+  const stripeState = { current: 0 };
 
   return (
     <div
@@ -24,7 +55,7 @@ export default function PropertiesTable({ schema }) {
       <table className="schema-table">
         <TableHeader />
         <tbody>
-          <SchemaRows tableData={tableData} />
+          <SchemaRows tableData={tableData} stripeState={stripeState} />
         </tbody>
       </table>
     </div>

package/components/PropertyRow.js

@@ -26,12 +26,60 @@ 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.',
+  patternProperties:
+    '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) {
+    return null;
+  }
+
+  return {
+    keyword: 'patternProperties',
+    pattern: match[1],
+  };
+}
+
+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`.
  * This component handles multi-row constraints using `rowSpan`.
  */
-export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
+export default function PropertyRow({
+  row,
+  stripeIndex,
+  isLastInGroup,
+  bracketEnds,
+}) {
   const {
     name,
     level,
@@ -44,6 +92,8 @@ export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
     containerType,
     continuingLevels = [],
     groupBrackets = [],
+    isSchemaKeywordRow = false,
+    keepConnectorOpen = false,
   } = row;
 
   const indentStyle = {
@@ -112,11 +162,27 @@ export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
   const bracketStyle = getBracketLinesStyle(groupBrackets, bracketCaps);
 
   const containerSymbol = getContainerSymbol(containerType);
+  const shouldCloseConnector = isLastInGroup && !keepConnectorOpen;
+  const splitKeyword = splitKeywordLabel(name);
+  const keywordHelpKey = name.startsWith('patternProperties ')
+    ? 'patternProperties'
+    : name;
+  const keywordHelpText = KEYWORD_HELP_TEXT[keywordHelpKey];
+  const keywordHelpId = keywordHelpText
+    ? buildKeywordHelpId(name, row.path)
+    : undefined;
+  const zebraClassName =
+    stripeIndex === undefined
+      ? undefined
+      : stripeIndex % 2 === 0
+        ? 'schema-row--zebra-even'
+        : 'schema-row--zebra-odd';
 
   return (
     <>
       <tr
         className={clsx(
+          zebraClassName,
           required && 'required-row',
           row.isCondition && 'conditional-condition-row',
         )}
@@ -126,21 +192,64 @@ export default function PropertyRow({ row, isLastInGroup, bracketEnds }) {
           style={{ ...indentStyle, ...continuingLinesStyle }}
           className={clsx(
             'property-cell',
+            isSchemaKeywordRow && 'property-cell--keyword',
+            required && 'property-cell--required',
+            level > 0 && 'property-cell--tree',
             level > 0 && `level-${level}`,
-            isLastInGroup && 'is-last',
+            shouldCloseConnector && 'is-last',
             hasChildren && 'has-children',
             containerType && `container-${containerType}`,
           )}
         >
-          <span className="property-name">
+          <span
+            className={clsx(
+              'property-name',
+              isSchemaKeywordRow && 'property-name--keyword',
+            )}
+          >
             {containerSymbol && (
               <span className="container-symbol">{containerSymbol}</span>
             )}
-            <strong>{name}</strong>
+            {isSchemaKeywordRow ? (
+              <span className="property-keyword-wrapper">
+                {splitKeyword ? (
+                  <span className="property-keyword-stack">
+                    <code
+                      className="property-keyword"
+                      aria-describedby={keywordHelpId}
+                    >
+                      {splitKeyword.keyword}
+                    </code>
+                    <code className="property-keyword-pattern">
+                      {splitKeyword.pattern}
+                    </code>
+                  </span>
+                ) : (
+                  <code
+                    className="property-keyword"
+                    aria-describedby={keywordHelpId}
+                  >
+                    {name}
+                  </code>
+                )}
+                <span className="property-keyword-badge">
+                  {SCHEMA_KEYWORD_BADGE_TEXT}
+                </span>
+                <span
+                  id={keywordHelpId}
+                  className="property-keyword-tooltip"
+                  role="tooltip"
+                >
+                  {keywordHelpText}
+                </span>
+              </span>
+            ) : (
+              <strong>{name}</strong>
+            )}
           </span>
         </td>
         <td rowSpan={rowSpan}>
-          <code>{propertyType}</code>
+          <code>{formatPropertyType(propertyType)}</code>
         </td>
 
         {/* The first constraint cell */}
@@ -181,7 +290,10 @@ 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}>
+        <tr
+          className={clsx(zebraClassName, required && 'required-row')}
+          key={constraint}
+        >
           <td className="constraint-cell">
             <code
               className={clsx(

package/components/SchemaJsonViewer.js

@@ -1,11 +1,331 @@
-import React from 'react';
-import CodeBlock from '@theme/CodeBlock';
+import React, { useState } from 'react';
+import Link from '@docusaurus/Link';
+import { usePrismTheme } from '@docusaurus/theme-common';
+import { Highlight } from 'prism-react-renderer';
+
+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);
+}
+
+function normalizePathSegments(pathValue) {
+  const normalized = pathValue.replace(/\\/g, '/');
+  const isAbsolute = normalized.startsWith('/');
+  const segments = normalized.split('/');
+  const resolvedSegments = [];
+
+  segments.forEach((segment) => {
+    if (!segment || segment === '.') return;
+    if (segment === '..') {
+      resolvedSegments.pop();
+      return;
+    }
+    resolvedSegments.push(segment);
+  });
+
+  return `${isAbsolute ? '/' : ''}${resolvedSegments.join('/')}`;
+}
+
+function dirname(pathValue) {
+  const normalized = normalizePathSegments(pathValue);
+  const segments = normalized.split('/');
+
+  if (segments.length <= 1) {
+    return normalized.startsWith('/') ? '/' : '.';
+  }
+
+  segments.pop();
+  const joined = segments.join('/');
+  return joined || '/';
+}
+
+function resolveLocalRef(currentPath, refValue) {
+  if (!currentPath || typeof refValue !== 'string') return null;
+  if (refValue.startsWith('#')) return null;
+  return normalizePathSegments(`${dirname(currentPath)}/${refValue}`);
+}
+
+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 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 semantic;
+  }
+
+  if (content === ':') {
+    if (
+      currentContext?.type === 'object' &&
+      currentContext.currentKey !== null
+    ) {
+      currentContext.afterColon = true;
+    }
+    return semantic;
+  }
+
+  if (content === '{' || content === '[') {
+    beginNestedValue(state, content);
+    return semantic;
+  }
+
+  if (content === '}' || content === ']') {
+    state.stack.pop();
+    return semantic;
+  }
+
+  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 renderToken({
+  token,
+  tokenIndex,
+  getTokenProps,
+  semantic,
+  currentPath,
+  schemaSources,
+  onNavigate,
+}) {
+  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>
+      );
+    }
+
+    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 (
+    <span
+      key={tokenIndex}
+      className={className || tokenProps.className}
+      style={tokenProps.style}
+    >
+      {token.content}
+    </span>
+  );
+}
+
+export default function SchemaJsonViewer({
+  schema,
+  sourcePath = null,
+  schemaSources = null,
+}) {
+  const prismTheme = usePrismTheme();
+  const resolvedSchemaSources =
+    schemaSources || (sourcePath ? { [sourcePath]: schema } : {});
+  const rootPath = sourcePath;
+  const [currentPath, setCurrentPath] = useState(rootPath);
+
+  const currentSchema =
+    (currentPath && resolvedSchemaSources?.[currentPath]) || schema;
+  const formattedSchema = JSON.stringify(currentSchema, null, 2);
 
-export default function SchemaJsonViewer({ schema }) {
   return (
     <details className="schema-json-viewer">
       <summary>View Raw JSON Schema</summary>
-      <CodeBlock language="json">{JSON.stringify(schema, null, 2)}</CodeBlock>
+      {rootPath && currentPath !== rootPath ? (
+        <div className="schema-json-viewer__controls">
+          <button
+            type="button"
+            className="schema-json-viewer__link"
+            onClick={() => setCurrentPath(rootPath)}
+          >
+            Back to root
+          </button>
+        </div>
+      ) : null}
+      <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>
   );
 }