@scalar/schemas 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @scalar/schemas
 
+## 0.10.0
+
+### Minor Changes
+
+- [#10074](https://github.com/scalar/scalar/pull/10074): feat(api-reference)!: the tree layout is the schema renderer
+
+  The tree layout is the schema renderer, so every visual baseline that renders a schema changes with this release and is regenerated per suite.
+
+- [#10074](https://github.com/scalar/scalar/pull/10074): feat(api-reference): the tree schema layout
+
+  The tree layout replaces the bordered card per nesting level and the "Show Child Attributes" pill with the visual grammar of a tree: a continuous rail per depth that hangs from the parent property's text column, and a discrete disclosure control in each expandable property's own gutter. The control is a real button whose accessible name is the property name alone and whose child count rides `aria-describedby`; property descriptions stay visible instead of being swallowed into a button label. Types render as token runs — `array of Planet` instead of `array Planet[]`, with a `$ref` link as the type itself — collapsed objects show a preview of what they hold, short enums render inline in the type position or wrap as chips instead of a row per value, and a `$ref` cycle says `recursive` in its own signature line instead of offering a toggle that descends forever. Rails fade with depth, capped so the deepest ones never wash out into the page. In a narrow container — the same `max-width: 900px` query the sections already use — the indent tightens and the controls shrink, so a deep tree still fits and the outermost control clears the page edge instead of being clipped by it. Collapsed subtrees that were opened once stay reachable with find-in-page via `hidden="until-found"` where the engine supports it, against a budget shared by every tree in the reference, with Safari falling back to unmounting exactly as before.
+
+  Printing temporarily expands the whole tree and restores the reader's expansion state afterwards.
+
+- [#10074](https://github.com/scalar/scalar/pull/10074): feat(api-reference): one disclosure grammar across every surface in the tree layout
+
+  The tree layout now reaches the surfaces the schema renderer never covered. Response headers fold into the tree as a child group named Headers, keyed into the expansion store so expand-all and deep links finally reach them — and the headers card's long-standing CSS syntax error is fixed along the way. Callbacks trade their native `details`/`summary` for the gutter control, and gain breadcrumbs, so a property inside a callback body is addressable for the first time. AsyncAPI message headers and payloads gain breadcrumbs the same way. Parameter rows keep rendering their type, required marker and description inline: a disclosure may hide child elements, never child information, and the classic layout starts passing `collapsableItems` — previously omitted, which silently made `expandAllResponses` a no-op there. Model properties in the classic layout gain anchors.
+
+  Group titles — Body, Responses, Query Parameters, Callbacks — become real headings through the document outline (`operationSection`, level 4), never hardcoded tags.
+
+  One flagged feature ships with this: `schemaKeyboardNav` (default off) adds APG-tree arrow-key navigation over the gutter toggles.
+
+- [#10102](https://github.com/scalar/scalar/pull/10102): Allow response hooks to return a replacement Response before the client processes its body, status, and headers. Add the onResponseReceived configuration callback for API References. Existing hooks can still read responses and return nothing.
+
+### Patch Changes
+
+- [#10126](https://github.com/scalar/scalar/pull/10126): refactor(api-reference): remove the legacy schema layout and the `schemaLayout` option
+
+  The legacy schema layout — a bordered card per nesting level behind a "Show Child Attributes" pill — is deleted, together with the `schemaLayout` configuration option that selected it. The tree layout is the only schema renderer.
+
+  The `schemaLayout` option never shipped in a release, so there is no `schemaLayout` value to remove from your configuration. Five translation keys the deleted markup owned are removed from `ApiReferenceTranslations`, and therefore from the `ApiReferenceTranslationKey` union: `schema.childAttributes`, `schema.hideChildAttributes`, `schema.showChildAttributes`, `operation.hideHeaders` and `operation.showHeaders`. They labelled the "Show Child Attributes" pill and the headers disclosure toggle, neither of which renders any more. If you override any of them in `localization.translations`, delete those entries — TypeScript will otherwise report an unknown-property error on the object literal.
+
+  The class names the tree already carried (`.schema-card`, `.property`, `.property--level-N` and their family) are unchanged, so `customCss` keeps working.
+
 ## 0.9.0
 
 ### Minor Changes

package/dist/api-reference/api-reference-configuration.d.ts

@@ -124,6 +124,10 @@ export declare const apiReferenceConfigurationSchema: import("@scalar/validation
         requestBuilder: unknown;
         envVariables: Record<string, string>;
     }) => Promise<void> | void>>;
+    onResponseReceived: import("@scalar/validation").OptionalSchema<import("@scalar/validation").FunctionSchema<(input: {
+        response: Response;
+        request: Request;
+    }) => Response | void | Promise<Response | void>>>;
     onShowMore: import("@scalar/validation").OptionalSchema<import("@scalar/validation").FunctionSchema<(tagId: string) => Promise<void> | void>>;
     onSidebarClick: import("@scalar/validation").OptionalSchema<import("@scalar/validation").FunctionSchema<(href: string) => Promise<void> | void>>;
     pathRouting: import("@scalar/validation").OptionalSchema<import("@scalar/validation").ObjectSchema<{
@@ -170,6 +174,7 @@ export declare const apiReferenceConfigurationSchema: import("@scalar/validation
     tagsSorter: import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnionSchema<readonly [LiteralSchema<"alpha">, import("@scalar/validation").FunctionSchema<(a: any, b: any) => number>]>>;
     operationsSorter: import("@scalar/validation").OptionalSchema<import("@scalar/validation").UnionSchema<readonly [LiteralSchema<"alpha">, LiteralSchema<"method">, import("@scalar/validation").FunctionSchema<(a: any, b: any) => number>]>>;
     orderSchemaPropertiesBy: import("@scalar/validation").UnionSchema<readonly [LiteralSchema<"alpha">, LiteralSchema<"preserve">]>;
+    schemaKeyboardNav: import("@scalar/validation").BooleanSchema;
     orderRequiredPropertiesFirst: import("@scalar/validation").BooleanSchema;
 }>]>;
 export declare const apiReferenceConfigurationWithSourceSchema: (rawInput: unknown) => {
@@ -230,6 +235,7 @@ export declare const apiReferenceConfigurationWithSourceSchema: (rawInput: unkno
     expandAllResponses: boolean;
     expandAllSchemaProperties: boolean;
     orderSchemaPropertiesBy: "alpha" | "preserve";
+    schemaKeyboardNav: boolean;
     orderRequiredPropertiesFirst: boolean;
 } & {
     proxy?: string | undefined;
@@ -307,6 +313,10 @@ export declare const apiReferenceConfigurationWithSourceSchema: (rawInput: unkno
         requestBuilder: unknown;
         envVariables: Record<string, string>;
     }) => Promise<void> | void) | undefined;
+    onResponseReceived?: ((input: {
+        response: Response;
+        request: Request;
+    }) => Response | void | Promise<Response | void>) | undefined;
     onShowMore?: ((tagId: string) => Promise<void> | void) | undefined;
     onSidebarClick?: ((href: string) => Promise<void> | void) | undefined;
     pathRouting?: {

package/dist/api-reference/api-reference-configuration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-reference-configuration.d.ts","sourceRoot":"","sources":["../../src/api-reference/api-reference-configuration.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-reference-configuration.d.ts","sourceRoot":"","sources":["../../src/api-reference/api-reference-configuration.ts"],"names":[],"mappings":"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"}

package/dist/api-reference/api-reference-configuration.js

@@ -122,6 +122,9 @@ export const apiReferenceConfigurationSchema = intersection([
         onRequestBuilt: optional(fn(), {
             typeComment: 'Fired right before the outbound request is sent; callback receives the exact fetch Request that goes over the wire. Experimental API.',
         }),
+        onResponseReceived: optional(fn(), {
+            typeComment: 'Fired before response processing. Return a Response to replace it, or nothing to keep it.',
+        }),
         onShowMore: optional(fn(), {
             typeComment: 'onShowMore is fired when the user clicks the "Show more" button on the references',
         }),
@@ -189,7 +192,7 @@ export const apiReferenceConfigurationSchema = intersection([
         }),
         expandAllSchemaProperties: boolean({
             default: false,
-            typeComment: 'Whether to expand all nested schema properties by default. The Show/Hide Child Attributes toggle remains available so nested sections can still be collapsed manually. Warning: this can cause performance issues on big documents',
+            typeComment: 'Whether to expand all nested schema properties by default. Each row keeps its own disclosure control, so nested sections can still be collapsed manually. Warning: this can cause performance issues on big documents',
         }),
         tagsSorter: optional(union([literal('alpha'), fn()]), {
             typeComment: 'Function to sort tags',
@@ -200,6 +203,10 @@ export const apiReferenceConfigurationSchema = intersection([
         orderSchemaPropertiesBy: union([literal('alpha'), literal('preserve')], {
             typeComment: 'Order the schema properties by',
         }),
+        schemaKeyboardNav: boolean({
+            default: false,
+            typeComment: 'Arrow-key navigation over the schema disclosure toggles (APG tree bindings). Off until screen-reader interaction questions are settled',
+        }),
         orderRequiredPropertiesFirst: boolean({
             default: true,
             typeComment: 'Sort the schema properties by required ones first',

package/package.json

@@ -14,7 +14,7 @@
     "schemas",
     "scalar"
   ],
-  "version": "0.9.0",
+  "version": "0.10.0",
   "engines": {
     "node": ">=22"
   },
@@ -41,12 +41,12 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@scalar/helpers": "0.11.3",
+    "@scalar/helpers": "0.12.0",
     "@scalar/validation": "0.6.3"
   },
   "devDependencies": {
     "vitest": "4.1.10",
-    "@scalar/types": "0.19.0"
+    "@scalar/types": "0.20.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",