fix(theme): apply default expansion depth even when control is hidden

`themeConfig.api.schemaExpansion.default` now reliably auto-expands to
the configured depth on every page load when `enabled` is false — the
provider previously kept reading from localStorage in that case, so a
stale value from a prior session where the control was enabled could
shadow the new default. Persistence is now implicitly off whenever the
control is hidden.

Also clarify the docstrings so it's discoverable that you can set just
`{ default: 1 }` to get auto-expansion without rendering the UI.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: sserrata

packages/docusaurus-theme-openapi-docs/src/theme/SchemaExpansion/context.tsx

@@ -61,11 +61,16 @@ function readConfig(
 ): SchemaExpansionConfig {
   const raw = themeConfig?.api?.schemaExpansion;
   if (!raw) return DEFAULT_CONFIG;
+  const enabled = raw.enabled ?? false;
   return {
-    enabled: raw.enabled ?? false,
+    enabled,
     defaultLevel: normalizeLevel(raw.default),
     max: typeof raw.max === "number" && raw.max > 0 ? Math.floor(raw.max) : 4,
-    persist: raw.persist ?? true,
+    // Persistence only matters when the reader can change the level via the
+    // UI control. When the control is hidden, fall back to the configured
+    // default on every visit so it isn't shadowed by a stale localStorage
+    // value from a session where the control used to be enabled.
+    persist: enabled ? (raw.persist ?? true) : false,
   };
 }
 

packages/docusaurus-theme-openapi-docs/src/types.d.ts

@@ -37,15 +37,19 @@ export interface ThemeConfig {
     /**
      * Controls automatic expansion of nested schema trees in request/response
      * documentation. Inspired by Redoc's `schemaExpansionLevel`.
+     *
+     * `default` applies whether or not `enabled` is `true` — set
+     * `{ default: 1 }` alone to auto-expand the first level on every page
+     * without rendering the depth control.
      */
     schemaExpansion?: {
-      /** Show an interactive control on the page so readers can change depth at view time. Defaults to `false`. */
+      /** Render an interactive depth control next to each schema header so readers can change the depth at view time. Defaults to `false`. */
       enabled?: boolean;
-      /** Initial expansion depth. Use `"all"` to expand everything. Defaults to `0` (all collapsed). */
+      /** Initial expansion depth applied on every page load. Use `"all"` to expand everything. Defaults to `0` (all collapsed). */
       default?: number | "all";
-      /** Maximum depth value offered by the UI control's pill buttons. Defaults to `4`. */
+      /** Highest numeric depth offered by the UI control. Ignored when `enabled` is `false`. Defaults to `4`. */
       max?: number;
-      /** Persist the reader's selected depth in `localStorage`. Defaults to `true` when `enabled` is `true`. */
+      /** Persist the reader's selected depth in `localStorage`. Only meaningful when `enabled` is `true`; defaults to `true` in that case. */
       persist?: boolean;
     };
   };