docusaurus-theme-openapi-docs 5.0.2 → 5.1.1

package/lib/theme/Schema/normalize.js

@@ -0,0 +1,210 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCircularMarker = isCircularMarker;
+exports.mergeAllOf = mergeAllOf;
+exports.foldSiblingsIntoBranches = foldSiblingsIntoBranches;
+exports.getDiscriminator = getDiscriminator;
+exports.findPropertyDeep = findPropertyDeep;
+exports.normalizeSchema = normalizeSchema;
+// eslint-disable-next-line import/no-extraneous-dependencies
+const allof_merge_1 = require("allof-merge");
+function isCircularMarker(value) {
+  return typeof value === "string" && value.startsWith("circular(");
+}
+/**
+ * Strip `additionalProperties: false` from sibling allOf members so
+ * allof-merge doesn't collapse to an unsatisfiable empty schema. See #1119.
+ *
+ * NOT cached: DiscriminatorNode mutates raw subschemas (deletes the
+ * discriminator property from each branch to avoid duplicate rendering).
+ * A WeakMap cache would return the pre-mutation deep clone on subsequent
+ * mergeAllOf calls, causing deleted properties to reappear inside tab
+ * content. Matches prod's per-call behavior.
+ */
+function stripConflictingAdditionalProps(node) {
+  if (Array.isArray(node)) return node.map(stripConflictingAdditionalProps);
+  if (!node || typeof node !== "object") return node;
+  let working = node;
+  if (Array.isArray(node.allOf) && node.allOf.length > 1) {
+    const hasStrictMember = node.allOf.some(
+      (m) => m && m.additionalProperties === false
+    );
+    if (hasStrictMember) {
+      working = {
+        ...node,
+        allOf: node.allOf.map((m) => {
+          if (m && m.additionalProperties === false) {
+            const { additionalProperties: _drop, ...rest } = m;
+            return rest;
+          }
+          return m;
+        }),
+      };
+    }
+  }
+  const result = {};
+  for (const [k, v] of Object.entries(working)) {
+    result[k] = stripConflictingAdditionalProps(v);
+  }
+  return result;
+}
+function mergeAllOf(schema) {
+  const onMergeError = (msg) => console.warn(msg);
+  const merged = (0, allof_merge_1.merge)(
+    stripConflictingAdditionalProps(schema),
+    {
+      onMergeError,
+    }
+  );
+  return merged ?? {};
+}
+// Keys that are parent-level metadata and should NOT be folded into branches.
+const METADATA_KEYS = new Set([
+  "title",
+  "description",
+  "discriminator",
+  "deprecated",
+  "externalDocs",
+  "example",
+  "examples",
+  "xml",
+  "nullable",
+  "readOnly",
+  "writeOnly",
+  "default",
+]);
+/**
+ * Fold sibling fields into each oneOf/anyOf branch via allOf-merge so each
+ * branch is self-contained. See #1218.
+ *
+ * Skipped when a discriminator is present: DiscriminatorNode already renders
+ * sibling properties at the top level, and folding would duplicate the
+ * discriminator metadata into each branch (causing nested DiscriminatorNode
+ * renders inside tabs — see #1525 follow-up).
+ *
+ * Called by normalizeSchema after allOf resolution. Uses mergeAllOf internally
+ * to compose `{ allOf: [siblings, branch] }` per branch — the WeakMap caches
+ * in stripConflictingAdditionalProps prevent redundant work on shared subtrees.
+ */
+function foldSiblingsIntoBranches(schema) {
+  const branchKey = schema?.oneOf
+    ? "oneOf"
+    : schema?.anyOf
+      ? "anyOf"
+      : undefined;
+  if (!branchKey) return schema;
+  const branches = schema[branchKey];
+  if (!Array.isArray(branches) || branches.length === 0) return schema;
+  // Discriminator schemas rely on top-level properties being intact so
+  // DiscriminatorNode can locate the discriminator property and render
+  // shared siblings at the top level. Leave them alone.
+  if (schema.discriminator) return schema;
+  // Build siblings from non-metadata keys only. Metadata (title, description,
+  // examples, etc.) belongs at the top level and must not be folded.
+  const siblings = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key !== branchKey && !METADATA_KEYS.has(key) && !key.startsWith("x-")) {
+      siblings[key] = value;
+    }
+  }
+  if (Object.keys(siblings).length === 0) return schema;
+  const folded = branches.map((branch) =>
+    mergeAllOf({ allOf: [siblings, branch] })
+  );
+  const result = { [branchKey]: folded };
+  for (const key of Object.keys(schema)) {
+    if (key !== branchKey && (METADATA_KEYS.has(key) || key.startsWith("x-"))) {
+      result[key] = schema[key];
+    }
+  }
+  return result;
+}
+// WeakMap caches keyed by object identity — shared-reference subtrees from
+// $RefParser.dereference are looked up once, and cycles short-circuit.
+const discriminatorCache = new WeakMap();
+const findPropertyCache = new WeakMap();
+/**
+ * Cached recursive discriminator lookup. Returns O(1) on repeated calls
+ * with the same object reference (common after normalizeSchema).
+ */
+const BRANCH_KEYS = ["oneOf", "anyOf", "allOf"];
+function getDiscriminator(schema) {
+  if (!schema || typeof schema !== "object") return undefined;
+  if (discriminatorCache.has(schema)) {
+    const cached = discriminatorCache.get(schema);
+    return cached === null ? undefined : cached;
+  }
+  discriminatorCache.set(schema, null);
+  let result = schema.discriminator;
+  if (!result) {
+    for (const key of BRANCH_KEYS) {
+      const branches = schema[key];
+      if (!Array.isArray(branches)) continue;
+      for (const branch of branches) {
+        result = getDiscriminator(branch);
+        if (result) break;
+      }
+      if (result) break;
+    }
+  }
+  discriminatorCache.set(schema, result ?? null);
+  return result;
+}
+/**
+ * Cached recursive property lookup. Searches schema.properties first, then
+ * into oneOf/anyOf/allOf branches. Returns O(1) on repeated calls with the
+ * same (schema, propertyName) pair — replaces the O(subtree) findProperty
+ * walk that caused #1525's O(N^2) render cost.
+ */
+function findPropertyDeep(schema, propertyName) {
+  if (!schema || typeof schema !== "object") return undefined;
+  let cache = findPropertyCache.get(schema);
+  if (cache && cache.has(propertyName)) {
+    const cached = cache.get(propertyName);
+    return cached === null ? undefined : cached;
+  }
+  if (!cache) {
+    cache = new Map();
+    findPropertyCache.set(schema, cache);
+  }
+  cache.set(propertyName, null);
+  let result = schema.properties?.[propertyName];
+  if (!result) {
+    for (const key of BRANCH_KEYS) {
+      const branches = schema[key];
+      if (!Array.isArray(branches)) continue;
+      for (const branch of branches) {
+        result = findPropertyDeep(branch, propertyName);
+        if (result) break;
+      }
+      if (result) break;
+    }
+  }
+  cache.set(propertyName, result ?? null);
+  return result;
+}
+/**
+ * Identity-stable schema pass-through. Returns the input as-is so SchemaNode
+ * useMemo dependencies stay stable across renders.
+ *
+ * Earlier iterations of this function eagerly merged allOf and folded
+ * siblings into oneOf/anyOf branches, but those operations need to stay
+ * conditional inside SchemaNode and DiscriminatorNode — eager versions
+ * caused cartesian product expansion (allOf with multiple oneOfs) and
+ * double-folding regressions. The render-time helpers below
+ * (mergeAllOf, foldSiblingsIntoBranches) are still cached via the WeakMap
+ * inside stripConflictingAdditionalProps, so per-render cost stays bounded.
+ *
+ * The perf win for #1525 comes from getDiscriminator's WeakMap cache
+ * replacing the O(subtree) findDiscriminator walk, not from eager
+ * normalization here.
+ */
+function normalizeSchema(schema) {
+  return schema;
+}

package/lib/theme/Schema/normalize.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/theme/Schema/normalize.test.js

@@ -0,0 +1,271 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+const normalize_1 = require("./normalize");
+describe("normalizeSchema", () => {
+  it("returns the input as-is (identity-stable pass-through)", () => {
+    const schema = { type: "object", properties: { a: { type: "string" } } };
+    expect((0, normalize_1.normalizeSchema)(schema)).toBe(schema);
+  });
+  it("handles null, undefined, and primitives", () => {
+    expect((0, normalize_1.normalizeSchema)(null)).toBeNull();
+    expect((0, normalize_1.normalizeSchema)(undefined)).toBeUndefined();
+    expect((0, normalize_1.normalizeSchema)("string")).toBe("string");
+    expect((0, normalize_1.normalizeSchema)(42)).toBe(42);
+  });
+});
+describe("mergeAllOf", () => {
+  it("merges allOf members into a flat schema", () => {
+    const schema = {
+      allOf: [
+        { type: "object", properties: { a: { type: "string" } } },
+        { type: "object", properties: { b: { type: "number" } } },
+      ],
+    };
+    const result = (0, normalize_1.mergeAllOf)(schema);
+    expect(result.allOf).toBeUndefined();
+    expect(result.properties.a).toEqual({ type: "string" });
+    expect(result.properties.b).toEqual({ type: "number" });
+  });
+  it("strips conflicting additionalProperties: false from allOf members", () => {
+    const schema = {
+      allOf: [
+        {
+          type: "object",
+          properties: { a: { type: "string" } },
+          additionalProperties: false,
+        },
+        {
+          type: "object",
+          properties: { b: { type: "number" } },
+          additionalProperties: false,
+        },
+      ],
+    };
+    const result = (0, normalize_1.mergeAllOf)(schema);
+    expect(result.properties.a).toBeDefined();
+    expect(result.properties.b).toBeDefined();
+  });
+  it("preserves both properties and oneOf when merging incompatible-shape members", () => {
+    const result = (0, normalize_1.mergeAllOf)({
+      allOf: [
+        { type: "object", properties: { id: { type: "string" } } },
+        { oneOf: [{ title: "a" }, { title: "b" }] },
+      ],
+    });
+    expect(result.properties.id).toBeDefined();
+    expect(result.oneOf).toHaveLength(2);
+  });
+});
+describe("foldSiblingsIntoBranches", () => {
+  it("returns schema unchanged when no oneOf/anyOf is present", () => {
+    const schema = { type: "object", properties: { a: { type: "string" } } };
+    expect((0, normalize_1.foldSiblingsIntoBranches)(schema)).toBe(schema);
+  });
+  it("returns schema unchanged when branches have no siblings", () => {
+    const schema = {
+      oneOf: [{ properties: { a: { type: "string" } } }],
+    };
+    expect((0, normalize_1.foldSiblingsIntoBranches)(schema)).toBe(schema);
+  });
+  it("returns schema unchanged when a discriminator is present", () => {
+    const schema = {
+      discriminator: { propertyName: "type" },
+      properties: { shared: { type: "string" } },
+      oneOf: [{ properties: { a: { type: "number" } } }],
+    };
+    expect((0, normalize_1.foldSiblingsIntoBranches)(schema)).toBe(schema);
+  });
+  it("folds sibling properties into oneOf branches", () => {
+    const schema = {
+      properties: { shared: { type: "string" } },
+      oneOf: [
+        { properties: { a: { type: "number" } } },
+        { properties: { b: { type: "boolean" } } },
+      ],
+    };
+    const result = (0, normalize_1.foldSiblingsIntoBranches)(schema);
+    expect(result.properties).toBeUndefined();
+    expect(result.oneOf).toHaveLength(2);
+    expect(result.oneOf[0].properties.shared).toBeDefined();
+    expect(result.oneOf[0].properties.a).toBeDefined();
+  });
+  it("folds sibling properties into anyOf branches", () => {
+    const schema = {
+      properties: { shared: { type: "string" } },
+      anyOf: [
+        { properties: { a: { type: "number" } } },
+        { properties: { b: { type: "boolean" } } },
+      ],
+    };
+    const result = (0, normalize_1.foldSiblingsIntoBranches)(schema);
+    expect(result.properties).toBeUndefined();
+    expect(result.anyOf).toHaveLength(2);
+    expect(result.anyOf[1].properties.shared).toBeDefined();
+    expect(result.anyOf[1].properties.b).toBeDefined();
+  });
+  it("preserves metadata and x-extension keys when folding", () => {
+    const schema = {
+      title: "Test",
+      description: "desc",
+      deprecated: true,
+      "x-vendor": true,
+      properties: { shared: { type: "string" } },
+      anyOf: [{ properties: { a: { type: "number" } } }],
+    };
+    const result = (0, normalize_1.foldSiblingsIntoBranches)(schema);
+    expect(result.title).toBe("Test");
+    expect(result.description).toBe("desc");
+    expect(result.deprecated).toBe(true);
+    expect(result["x-vendor"]).toBe(true);
+    expect(result.properties).toBeUndefined();
+  });
+  it("strips non-metadata keys from result", () => {
+    const schema = {
+      type: "object",
+      required: ["shared"],
+      properties: { shared: { type: "string" } },
+      items: { type: "string" },
+      oneOf: [{ properties: { a: { type: "number" } } }],
+    };
+    const result = (0, normalize_1.foldSiblingsIntoBranches)(schema);
+    expect(result.type).toBeUndefined();
+    expect(result.required).toBeUndefined();
+    expect(result.properties).toBeUndefined();
+    expect(result.items).toBeUndefined();
+    expect(result.oneOf).toHaveLength(1);
+  });
+});
+describe("getDiscriminator", () => {
+  it("returns direct discriminator", () => {
+    const schema = { discriminator: { propertyName: "type" } };
+    expect((0, normalize_1.getDiscriminator)(schema)).toEqual({
+      propertyName: "type",
+    });
+  });
+  it("finds discriminator in oneOf branches", () => {
+    const schema = {
+      oneOf: [{ discriminator: { propertyName: "kind" } }, { type: "string" }],
+    };
+    expect((0, normalize_1.getDiscriminator)(schema)).toEqual({
+      propertyName: "kind",
+    });
+  });
+  it("finds discriminator in anyOf branches", () => {
+    const schema = {
+      anyOf: [
+        { type: "string" },
+        { discriminator: { propertyName: "variant" } },
+      ],
+    };
+    expect((0, normalize_1.getDiscriminator)(schema)).toEqual({
+      propertyName: "variant",
+    });
+  });
+  it("finds discriminator in allOf branches", () => {
+    const schema = {
+      allOf: [
+        { properties: { id: { type: "string" } } },
+        { discriminator: { propertyName: "type" } },
+      ],
+    };
+    expect((0, normalize_1.getDiscriminator)(schema)).toEqual({
+      propertyName: "type",
+    });
+  });
+  it("returns undefined when no discriminator exists", () => {
+    const schema = {
+      type: "object",
+      properties: { name: { type: "string" } },
+    };
+    expect((0, normalize_1.getDiscriminator)(schema)).toBeUndefined();
+  });
+  it("returns undefined for null/primitive input", () => {
+    expect((0, normalize_1.getDiscriminator)(null)).toBeUndefined();
+    expect((0, normalize_1.getDiscriminator)("string")).toBeUndefined();
+  });
+  it("caches results for same object reference", () => {
+    const inner = { discriminator: { propertyName: "type" } };
+    const schema = { oneOf: [inner] };
+    const first = (0, normalize_1.getDiscriminator)(schema);
+    const second = (0, normalize_1.getDiscriminator)(schema);
+    expect(first).toBe(second);
+  });
+  it("handles cycles without infinite recursion", () => {
+    const a = { properties: {} };
+    const b = { properties: { a } };
+    a.properties.b = b;
+    expect(() => (0, normalize_1.getDiscriminator)(a)).not.toThrow();
+    expect((0, normalize_1.getDiscriminator)(a)).toBeUndefined();
+  });
+});
+describe("findPropertyDeep", () => {
+  it("returns property at top level", () => {
+    const schema = { properties: { foo: { type: "string" } } };
+    expect((0, normalize_1.findPropertyDeep)(schema, "foo")).toEqual({
+      type: "string",
+    });
+  });
+  it("finds property in oneOf branches", () => {
+    const schema = {
+      oneOf: [
+        { properties: { a: { type: "string" } } },
+        { properties: { b: { type: "number" } } },
+      ],
+    };
+    expect((0, normalize_1.findPropertyDeep)(schema, "a")).toEqual({
+      type: "string",
+    });
+    expect((0, normalize_1.findPropertyDeep)(schema, "b")).toEqual({
+      type: "number",
+    });
+  });
+  it("finds property in anyOf branches", () => {
+    const schema = {
+      anyOf: [{ properties: { x: { type: "integer" } } }],
+    };
+    expect((0, normalize_1.findPropertyDeep)(schema, "x")).toEqual({
+      type: "integer",
+    });
+  });
+  it("finds property in allOf branches", () => {
+    const schema = {
+      allOf: [{ properties: { y: { type: "boolean" } } }],
+    };
+    expect((0, normalize_1.findPropertyDeep)(schema, "y")).toEqual({
+      type: "boolean",
+    });
+  });
+  it("returns undefined when property not found", () => {
+    const schema = { properties: { foo: { type: "string" } } };
+    expect((0, normalize_1.findPropertyDeep)(schema, "bar")).toBeUndefined();
+  });
+  it("returns undefined for null/primitive input", () => {
+    expect((0, normalize_1.findPropertyDeep)(null, "foo")).toBeUndefined();
+    expect((0, normalize_1.findPropertyDeep)("string", "foo")).toBeUndefined();
+  });
+  it("handles cycles without infinite recursion", () => {
+    const a = { properties: {} };
+    a.oneOf = [a];
+    expect(() => (0, normalize_1.findPropertyDeep)(a, "foo")).not.toThrow();
+    expect((0, normalize_1.findPropertyDeep)(a, "foo")).toBeUndefined();
+  });
+});
+describe("isCircularMarker", () => {
+  it("returns true for circular marker strings", () => {
+    expect((0, normalize_1.isCircularMarker)("circular(Title)")).toBe(true);
+    expect((0, normalize_1.isCircularMarker)("circular()")).toBe(true);
+  });
+  it("returns false for other values", () => {
+    expect((0, normalize_1.isCircularMarker)("normal string")).toBe(false);
+    expect((0, normalize_1.isCircularMarker)(null)).toBe(false);
+    expect((0, normalize_1.isCircularMarker)(undefined)).toBe(false);
+    expect((0, normalize_1.isCircularMarker)({})).toBe(false);
+    expect((0, normalize_1.isCircularMarker)(42)).toBe(false);
+  });
+});

package/lib/theme/SchemaExpansion/_SchemaExpansion.scss

@@ -0,0 +1,113 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+.openapi-schema-expansion {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  margin-left: auto;
+}
+
+.openapi-schema-expansion__trigger {
+  appearance: none;
+  background: transparent;
+  border: none;
+  border-radius: var(--ifm-global-radius);
+  padding: 0;
+  width: 22px;
+  height: 22px;
+  flex: 0 0 22px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--ifm-color-emphasis-600);
+  line-height: 0;
+  opacity: 0.7;
+  transition:
+    opacity 0.12s ease,
+    background-color 0.12s ease,
+    color 0.12s ease;
+
+  &:hover {
+    opacity: 1;
+    background-color: var(--ifm-color-emphasis-200);
+    color: var(--ifm-color-emphasis-900);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--ifm-color-primary);
+    outline-offset: 2px;
+    opacity: 1;
+  }
+
+  &[aria-expanded="true"] {
+    opacity: 1;
+    background-color: var(--ifm-color-emphasis-200);
+    color: var(--ifm-color-emphasis-900);
+  }
+}
+
+.openapi-schema-expansion__popover {
+  position: fixed;
+  z-index: 1000;
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  padding: 3px;
+  background-color: var(--ifm-background-surface-color);
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  box-shadow: var(--ifm-global-shadow-md);
+  white-space: nowrap;
+}
+
+.openapi-schema-expansion__option {
+  appearance: none;
+  background: transparent;
+  border: none;
+  border-radius: calc(var(--ifm-global-radius) - 2px);
+  padding: 2px 8px;
+  font-size: 0.8rem;
+  line-height: 1.4;
+  color: var(--ifm-color-emphasis-800);
+  transition:
+    background-color 0.12s ease,
+    color 0.12s ease;
+
+  &:hover {
+    background-color: var(--ifm-color-emphasis-200);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--ifm-color-primary);
+    outline-offset: 1px;
+  }
+}
+
+.openapi-schema-expansion__option--active {
+  background-color: var(--ifm-color-primary);
+  color: var(--ifm-color-white);
+
+  &:hover {
+    background-color: var(--ifm-color-primary-dark);
+  }
+}
+
+.openapi-markdown__details-summary--with-control {
+  display: flex !important;
+  align-items: center;
+  gap: 0.5rem;
+
+  > h3,
+  > strong {
+    margin-bottom: 0;
+    display: inline-flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+  }
+}

package/lib/theme/SchemaExpansion/context.d.ts

@@ -0,0 +1,24 @@
+import React from "react";
+export declare const SCHEMA_EXPANSION_STORAGE_KEY = "docusaurus-openapi-schema-expansion-level";
+export interface SchemaExpansionConfig {
+    enabled: boolean;
+    defaultLevel: number;
+    max: number;
+    persist: boolean;
+}
+interface SchemaExpansionContextValue {
+    config: SchemaExpansionConfig;
+    level: number;
+    setLevel: (next: number) => void;
+}
+export declare function normalizeLevel(value: number | "all" | undefined): number;
+export declare const SchemaExpansionProvider: React.FC<{
+    children: React.ReactNode;
+}>;
+export declare const SchemaDepthProvider: React.FC<{
+    depth: number;
+    children: React.ReactNode;
+}>;
+export declare function useSchemaExpansion(): SchemaExpansionContextValue;
+export declare function useSchemaDepth(): number;
+export {};