blume 2.0.3 → 2.1.1

package/src/components/openapi/code-samples.ts

@@ -0,0 +1,97 @@
+import { sampleLanguageInfo } from "./snippets.ts";
+import type { SampleLanguageInfo } from "./snippets.ts";
+
+/**
+ * Hand-written code samples from a spec: the `x-codeSamples` extension on an
+ * operation (Redocly's, which Mintlify, Speakeasy, and Stainless write too),
+ * or its older spelling `x-code-samples`. Each entry names a `lang`, holds
+ * the `source`, and may carry a `label`. They render as their own tabs ahead
+ * of the generated samples and, being fixed text, the playground leaves them
+ * as written.
+ */
+
+/** One hand-written sample, ready to render as a tab. */
+export interface CustomCodeSample {
+  /** A stable, unique tab key. */
+  key: string;
+  /** The tab label: the entry's own, else the language's name. */
+  label: string;
+  /** The Shiki language to highlight `source` with. */
+  lang: string;
+  source: string;
+}
+
+/** The two places an operation keeps them. */
+export interface CodeSamplesCarrier {
+  "x-code-samples"?: unknown;
+  "x-codeSamples"?: unknown;
+}
+
+interface RawSample {
+  label?: string;
+  lang: string;
+  source: string;
+}
+
+const isRawSample = (value: unknown): value is RawSample =>
+  typeof value === "object" &&
+  value !== null &&
+  "lang" in value &&
+  typeof value.lang === "string" &&
+  "source" in value &&
+  typeof value.source === "string" &&
+  (!("label" in value) || typeof value.label === "string");
+
+// Shell tools in an `x-codeSamples` entry are usually an SDK's CLI, not curl,
+// so they're named for the shell rather than "cURL".
+const SHELL_LANGS = new Set(["bash", "sh", "shell", "zsh"]);
+
+/** The display name and highlighter for a sample's `lang`. */
+const describe = (lang: string): SampleLanguageInfo => {
+  const lower = lang.toLowerCase();
+  if (SHELL_LANGS.has(lower)) {
+    return { label: "Shell", lang: "bash" };
+  }
+  // A language Blume doesn't generate keeps its own name, and Shiki tries
+  // it as written (it knows most languages by their common names).
+  return sampleLanguageInfo(lower) ?? { label: lang, lang: lower };
+};
+
+/**
+ * The operation's hand-written samples, with a unique tab label each. A label
+ * two samples share gains its language (`List plants · JavaScript`), and one
+ * that still repeats gains a number. Malformed entries are skipped.
+ */
+export const customCodeSamples = (
+  operation: CodeSamplesCarrier
+): CustomCodeSample[] => {
+  const raw = operation["x-codeSamples"] ?? operation["x-code-samples"];
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const entries = raw.filter(isRawSample).map((entry) => {
+    const language = describe(entry.lang);
+    return {
+      base: entry.label?.trim() || language.label,
+      language,
+      source: entry.source.replace(/\n$/u, ""),
+    };
+  });
+  const counts = new Map<string, number>();
+  for (const { base } of entries) {
+    counts.set(base, (counts.get(base) ?? 0) + 1);
+  }
+  const used = new Set<string>();
+  return entries.map(({ base, language, source }, index) => {
+    const first =
+      (counts.get(base) ?? 0) > 1 && base !== language.label
+        ? `${base} · ${language.label}`
+        : base;
+    let label = first;
+    for (let n = 2; used.has(label); n += 1) {
+      label = `${first} (${n})`;
+    }
+    used.add(label);
+    return { key: `x-${index}`, label, lang: language.lang, source };
+  });
+};

package/src/components/openapi/graphql-helpers.ts

@@ -10,8 +10,11 @@ import {
   isGraphqlOperationKind,
 } from "../../openapi/graphql.ts";
 import type { ApiSpecData } from "../../openapi/model.ts";
+import { endpointSecurity } from "../content/api-page.ts";
 import type { SpecValue } from "./helpers.ts";
+import { playgroundAuth } from "./operation-model.ts";
 import type { PlaygroundModel } from "./request.ts";
+import type { OperationSecurity } from "./security.ts";
 
 /**
  * Build-time logic behind the GraphQL reference pages: the generated example
@@ -67,9 +70,10 @@ const isComposite = (document: GraphqlDocument, name: string): boolean => {
 
 /**
  * A valid selection set for a composite type, or undefined for leaves: every
- * scalar/enum field, plus nested composites while `depth` allows. A composite
- * with nothing selectable at this depth falls back to `__typename`, which is
- * legal on any composite — the set must never come out empty.
+ * scalar/enum field, plus nested composites while `depth` allows, deprecated
+ * fields left out so the example doesn't teach them. A composite with nothing
+ * selectable at this depth falls back to `__typename`, which is legal on any
+ * composite — the set must never come out empty.
  */
 export const selectionSet = (
   document: GraphqlDocument,
@@ -85,10 +89,12 @@ export const selectionSet = (
   }
   const selections: GraphqlSelection[] = [];
   for (const field of type.fields ?? []) {
-    // A field with an argument that must be supplied — non-null and no
-    // default — can't ride an example selection; there is nothing valid to
-    // fill it with inline. A defaulted non-null argument is omittable.
+    // A deprecated field stays out of the example. So does a field with an
+    // argument that must be supplied — non-null and no default: there is
+    // nothing valid to fill it with inline. A defaulted non-null argument is
+    // omittable.
     if (
+      field.deprecationReason !== undefined ||
       field.args.some(
         (arg) => arg.type.display.endsWith("!") && arg.default === undefined
       )
@@ -189,10 +195,14 @@ const sampleForRef = (
   if (type?.kind === "enum") {
     named = type.enumValues?.[0]?.name ?? null;
   } else if (type?.kind === "input" && depth > 0) {
+    // A field with a default starts at it, the value a client leaving it
+    // out gets.
     named = Object.fromEntries(
       (type.inputFields ?? []).map((field) => [
         field.name,
-        sampleForRef(document, field.type, depth - 1),
+        field.defaultValue === undefined
+          ? sampleForRef(document, field.type, depth - 1)
+          : field.defaultValue,
       ])
     );
   } else if (type?.kind === "input") {
@@ -203,7 +213,10 @@ const sampleForRef = (
   return wrapLists(ref.display, named);
 };
 
-/** Example `variables` for a root field's arguments; undefined when it has none. */
+/**
+ * Example `variables` for a root field's arguments, each starting at its
+ * declared default when it has one; undefined when it has none.
+ */
 export const exampleVariables = (
   document: GraphqlDocument,
   field: GraphqlField
@@ -212,7 +225,9 @@ export const exampleVariables = (
     ? Object.fromEntries(
         field.args.map((arg) => [
           arg.name,
-          sampleForRef(document, arg.type, VARIABLE_DEPTH),
+          arg.defaultValue === undefined
+            ? sampleForRef(document, arg.type, VARIABLE_DEPTH)
+            : arg.defaultValue,
         ])
       )
     : undefined;
@@ -271,19 +286,27 @@ export const exampleResponse = (
   return { data };
 };
 
+/**
+ * The security every operation of a GraphQL reference enforces: its `auth`
+ * option, read the way a hand-written endpoint reads the site's `api.auth`.
+ */
+export const graphqlSecurity = (spec: ApiSpecData): OperationSecurity =>
+  endpointSecurity(undefined, spec.auth);
+
 /**
  * The playground/request model for one GraphQL operation: a plain POST whose
  * JSON body carries the query and variables. Reusing `PlaygroundModel` means
  * the OpenAPI playground UI, its client module, and `buildRequest` all work
- * unchanged — the samples show byte-for-byte what the Send button transmits.
+ * unchanged — the samples show byte-for-byte what the Send button transmits,
+ * the configured `auth` credential included.
  */
 export const graphqlPlaygroundModel = (
   spec: ApiSpecData,
   query: string,
   variables?: GraphqlSampleObject
 ): PlaygroundModel => ({
-  auth: [],
-  authOptional: true,
+  auth: playgroundAuth(graphqlSecurity(spec)),
+  authOptional: false,
   body: {
     contentType: "application/json",
     example: JSON.stringify(

package/src/components/openapi/helpers.ts

@@ -135,7 +135,23 @@ export const mergeParameters = (
 export const refName = (ref: string): string =>
   REF_PATTERN.exec(ref)?.groups?.name ?? ref.split("/").at(-1) ?? ref;
 
-/** Resolve one level of `$ref` against the document's component schemas. */
+/**
+ * The one member of an `allOf` that only wraps it: `allOf: [{ $ref }]` beside
+ * a `description`, `readOnly`, or `default`, which is how drf-spectacular and
+ * other generators attach keywords a 3.0 `$ref` can't carry. `undefined` for
+ * a real composition: several members, or properties or branches of its own.
+ */
+export const soleAllOfMember = (schema: SchemaLike): SchemaLike | undefined =>
+  schema.allOf?.length === 1 &&
+  !(schema.properties || schema.oneOf || schema.anyOf)
+    ? schema.allOf[0]
+    : undefined;
+
+/**
+ * Resolve one level of `$ref` against the document's component schemas. A
+ * single-member `allOf` wrapper resolves like its member, with the wrapper's
+ * own keywords on top: its `description` is about this field.
+ */
 export const resolveSchema = (
   schemas: Record<string, SchemaLike>,
   schema?: SchemaLike
@@ -143,6 +159,11 @@ export const resolveSchema = (
   if (!schema) {
     return {};
   }
+  const member = soleAllOfMember(schema);
+  if (member) {
+    const { allOf: _wrapped, ...own } = schema;
+    return { ...resolveSchema(schemas, member), ...own };
+  }
   if (isString(schema.$ref)) {
     const name = REF_PATTERN.exec(schema.$ref)?.groups?.name;
     if (name && schemas[name]) {
@@ -152,6 +173,16 @@ export const resolveSchema = (
   return schema;
 };
 
+/**
+ * A parameter's description: its own, else its schema's (resolved one `$ref`
+ * level), which is where generators like Elysia and oRPC write it.
+ */
+export const parameterDescription = (
+  param: { description?: string; schema?: SchemaLike },
+  schemas: Record<string, SchemaLike>
+): string | undefined =>
+  param.description ?? resolveSchema(schemas, param.schema).description;
+
 const declaredTypeList = (type: string | string[] | undefined): string[] => {
   if (!type) {
     return [];
@@ -177,6 +208,8 @@ const isNullType = (schema: SchemaLike): boolean => {
  * (`Pet`, `Pet[]`) without resolving — which also means circular refs through
  * array items can't recurse forever. A `null` member stays out of a union's
  * label: rows mark it with {@link isNullable}, as they do `type: [T, "null"]`.
+ * A single-member `allOf` wrapper labels as its member; a real composition is
+ * an `object`.
  */
 export const typeLabel = (schema: SchemaLike): string => {
   if (isString(schema.$ref)) {
@@ -192,7 +225,8 @@ export const typeLabel = (schema: SchemaLike): string => {
     return [...new Set(labels)].join(" | ") || "any";
   }
   if (schema.allOf) {
-    return "object";
+    const member = soleAllOfMember(schema);
+    return member ? typeLabel(member) : "object";
   }
   const types = nonNullTypes(schema.type);
   const arrayLabel = (): string => `${typeLabel(schema.items ?? {})}[]`;

package/src/components/openapi/message-model.ts

@@ -1,10 +1,15 @@
 import type {
   AsyncApiAction,
+  AsyncApiDocument,
   AsyncApiServerObject,
 } from "../../openapi/asyncapi.ts";
 import { withServerDefaults } from "../../openapi/model.ts";
 import type { AsyncApiMessageLike, NamedMessage } from "./async.ts";
-import { payloadSchema } from "./async.ts";
+import {
+  kafkaKeySchema,
+  payloadSchema,
+  resolvedServerSecurity,
+} from "./async.ts";
 import { exampleValue, toJson } from "./helpers.ts";
 import type { ParameterLike, SchemaLike } from "./helpers.ts";
 import type {
@@ -76,14 +81,34 @@ const messagePayload = (
   };
 };
 
+/**
+ * The first message's Kafka key as the kcat sample writes it: sampled from
+ * its binding's `key` schema the way a payload is (a declared example wins),
+ * a non-string value as JSON. None when the message declares no key.
+ */
+const messageKey = (
+  message: AsyncApiMessageLike | undefined,
+  schemas: Record<string, SchemaLike>,
+  components: AsyncApiDocument["components"]
+): string | undefined => {
+  const schema = kafkaKeySchema(message, components);
+  const key = inputValue(schema ? exampleValue(schema, schemas) : null);
+  return key === "" ? undefined : key;
+};
+
 /**
  * A server's base URL for the picker. Falls back to the bare host when the
  * spec omits `protocol` — a label is a label, and the snippet builders read
  * the server object itself rather than this string. Server variables in the
  * host and pathname (`{env}.events.example.com`) resolve to their declared
  * defaults, in the label and in the object the samples and connect URL read.
+ * Security refs resolve here too, so the kcat sample can name the server's
+ * SASL mechanism.
  */
-const serverOption = (spec: AsyncApiServerObject): MessageServerOption => {
+const serverOption = (
+  spec: AsyncApiServerObject,
+  components: AsyncApiDocument["components"]
+): MessageServerOption => {
   const server = { ...spec };
   if (spec.host !== undefined) {
     server.host = withServerDefaults(spec.host, spec.variables);
@@ -91,6 +116,9 @@ const serverOption = (spec: AsyncApiServerObject): MessageServerOption => {
   if (spec.pathname !== undefined) {
     server.pathname = withServerDefaults(spec.pathname, spec.variables);
   }
+  if (spec.security !== undefined) {
+    server.security = resolvedServerSecurity(spec, components);
+  }
   const host = `${server.host ?? ""}${server.pathname ?? ""}`;
   return {
     label: server.protocol ? `${server.protocol}://${host}` : host,
@@ -102,17 +130,32 @@ const serverOption = (spec: AsyncApiServerObject): MessageServerOption => {
 export const messageModel = (args: {
   action: AsyncApiAction;
   address: string;
+  /** The document's `components`, which bindings and security refs resolve against. */
+  components?: AsyncApiDocument["components"];
   messages: NamedMessage[];
   parameters: ParameterLike[];
   protocol?: string;
   schemas: Record<string, SchemaLike>;
   servers: AsyncApiServerObject[];
-}): MessageModel => ({
-  action: args.action,
-  address: args.address,
-  connectable: Object.hasOwn(LIVE_PROTOCOLS, args.protocol ?? ""),
-  params: messageParams(args.parameters),
-  payload: messagePayload(args.messages[0]?.message, args.schemas),
-  protocol: args.protocol,
-  servers: args.servers.map(serverOption),
-});
+}): MessageModel => {
+  const model: MessageModel = {
+    action: args.action,
+    address: args.address,
+    connectable: Object.hasOwn(LIVE_PROTOCOLS, args.protocol ?? ""),
+    params: messageParams(args.parameters),
+    payload: messagePayload(args.messages[0]?.message, args.schemas),
+    protocol: args.protocol,
+    servers: args.servers.map((server) =>
+      serverOption(server, args.components)
+    ),
+  };
+  const key = messageKey(
+    args.messages[0]?.message,
+    args.schemas,
+    args.components
+  );
+  if (key !== undefined) {
+    model.key = key;
+  }
+  return model;
+};

package/src/components/openapi/message.ts

@@ -41,15 +41,19 @@ export interface MessageServerOption {
   /** `protocol://host+pathname` — what the reader picks between. */
   label: string;
   /**
-   * The spec server with its host/pathname variables at their defaults; the
-   * snippet builders read host/pathname/protocol.
+   * The spec server with its host/pathname variables at their defaults and
+   * its `security` refs resolved; the snippet builders read
+   * host/pathname/protocol/security.
    */
   server: AsyncApiServerObject;
 }
 
 export interface MessageModel {
   action: AsyncApiAction;
-  /** Channel address with `{param}` templates intact, e.g. `user/{id}/signedup`. */
+  /**
+   * Channel address with `{param}` templates intact, e.g. `user/{id}/signedup`
+   * — or the Kafka binding's `topic` when the channel names one.
+   */
   address: string;
   /**
    * Whether the panel offers a live connection. Only WebSocket bindings can be
@@ -57,6 +61,8 @@ export interface MessageModel {
    * CLI samples rather than faked connectivity.
    */
   connectable: boolean;
+  /** Example Kafka message key, sampled from the first message's binding. */
+  key?: string;
   params: MessageParam[];
   payload: MessagePayload;
   /** Normalized binding key (`ws`, `kafka`, `mqtt`, …) when the spec implies one. */
@@ -149,7 +155,7 @@ export const buildMessage = (
   } catch {
     payload = undefined;
   }
-  return {
+  const sample: MessageSample = {
     action: model.action,
     address: model.address.replaceAll(PARAM_TEMPLATE, (template, name) => {
       const value = values.params[String(name)] ?? "";
@@ -158,6 +164,10 @@ export const buildMessage = (
     payload,
     server: custom === "" ? picked?.server : customServer(custom),
   };
+  if (model.key !== undefined) {
+    sample.key = model.key;
+  }
+  return sample;
 };
 
 /**

package/src/components/openapi/operation-model.ts

@@ -3,6 +3,7 @@ import {
   declaredExample,
   exampleValue,
   objectProperties,
+  parameterDescription,
   resolveSchema,
   toJson,
 } from "./helpers.ts";
@@ -142,7 +143,7 @@ const modelParams = (
     const required = where === "path" ? true : param.required === true;
     const schema = resolveSchema(schemas, param.schema);
     params.push({
-      description: param.description,
+      description: parameterDescription(param, schemas),
       enum: schema.enum?.map(String),
       in: where,
       name: param.name,
@@ -330,6 +331,19 @@ const authInput = (
   }
 };
 
+/**
+ * The playground's credential inputs for an operation's security: the first
+ * alternative only — the spec's preferred way to authorize, matching what the
+ * static samples always showed.
+ */
+export const playgroundAuth = (
+  security: OperationSecurity
+): PlaygroundAuthInput[] =>
+  (security.alternatives[0] ?? []).flatMap((resolved) => {
+    const input = authInput(resolved);
+    return input ? [input] : [];
+  });
+
 /** Derive the playground request model for one operation, at build time. */
 export const operationModel = (args: {
   method: string;
@@ -344,12 +358,7 @@ export const operationModel = (args: {
   components?: ComponentsLike;
   security: OperationSecurity;
 }): PlaygroundModel => ({
-  // First alternative only — the spec's preferred way to authorize, matching
-  // what the static samples always showed.
-  auth: (args.security.alternatives[0] ?? []).flatMap((resolved) => {
-    const input = authInput(resolved);
-    return input ? [input] : [];
-  }),
+  auth: playgroundAuth(args.security),
   authOptional: args.security.optional,
   body: modelBody(args.requestBody, args.schemas, args.components),
   method: args.method.toUpperCase(),

package/src/components/openapi/playground-client.ts

@@ -26,16 +26,34 @@ import { fetchRefusesMethod, sampleLanguages } from "./snippets.ts";
 import type { RequestSample } from "./snippets.ts";
 import { validateJson } from "./validate-json.ts";
 
+const OPENAPI_PROXY_SETTING =
+  "`playground: { proxy: true }` on the `openapi()` reference";
+
+/**
+ * The Blume config setting that turns on the proxy for a panel, keyed by the
+ * `data-proxy-config` the rendering surface stamps on it: an `openapi()` or
+ * `graphql()` reference's `playground` option, or `api.playground` for
+ * hand-written API pages.
+ */
+const PROXY_SETTINGS = new Map([
+  ["api", "`api: { playground: { proxy: true } }`"],
+  ["graphql", "`playground: { proxy: true }` on the `graphql()` reference"],
+  ["openapi", OPENAPI_PROXY_SETTING],
+]);
+
 /**
  * A failed fetch surfaces as a TypeError with no status — almost always the
  * browser's CORS wall, not the API being down — so the message explains the
- * one fix docs authors control instead of parroting "failed to fetch".
+ * one fix docs authors control instead of parroting "failed to fetch", naming
+ * the setting for the surface this panel is on and the server output the
+ * built-in proxy needs.
  */
-const CORS_MESSAGE =
+const corsMessage = (config: string): string =>
   "The browser blocked this request before it reached the API — the API " +
   "likely does not allow cross-origin requests from this docs site. Set " +
-  "`playground: { proxy: true }` on the `openapi()` reference in the Blume " +
-  "config to route playground requests through the docs server instead.";
+  `${PROXY_SETTINGS.get(config) ?? OPENAPI_PROXY_SETTING} in the Blume ` +
+  "config to route playground requests through the docs server instead. " +
+  "The proxy needs server output: a host adapter in `deployment`.";
 
 /**
  * `Cookie` is a forbidden header name: a page cannot set it, so a credential
@@ -294,6 +312,7 @@ export const initPlayground = (root: HTMLElement): void => {
   const response = root.querySelector<HTMLElement>("[data-response]");
   const storageKey = root.dataset.storageKey ?? "";
   const proxy = root.dataset.proxy ?? "";
+  const proxyConfig = root.dataset.proxyConfig ?? "";
 
   /** True while a send is outstanding, so a second click can't race it. */
   let sending = false;
@@ -607,7 +626,7 @@ export const initPlayground = (root: HTMLElement): void => {
         const crossOrigin = !proxy && !sample.url.startsWith("/");
         message =
           crossOrigin && (await reachable(sample.url))
-            ? CORS_MESSAGE
+            ? corsMessage(proxyConfig)
             : UNREACHABLE_MESSAGE;
       }
       response.textContent = "";

package/src/components/openapi/playground-schema.ts

@@ -62,7 +62,7 @@ const isReadOnly = (
  * Prune a spec schema into the tiny subset `validate-json.ts` understands:
  * `$ref`s resolved inline, cycles cut (the visited set is copied per branch so
  * a ref reused by siblings still prunes fully), depth capped. Structure beyond
- * the cut simply goes unvalidated — advisory checks, not a gate.
+ * the cut simply goes unvalidated, so it can never block a send.
  */
 const pruneSchema = (
   schema: SchemaLike | undefined,

package/src/components/openapi/schema-tree.ts

@@ -2,6 +2,7 @@ import {
   objectProperties,
   refName,
   resolveSchema,
+  soleAllOfMember,
   typeLabel,
 } from "./helpers.ts";
 import type { SchemaLike, SpecValue } from "./helpers.ts";
@@ -67,6 +68,15 @@ export type SchemaNode =
 const isString = (value: SpecValue): value is string =>
   typeof value === "string";
 
+/**
+ * The `$ref` a schema stands for: its own, or its member's when it is a
+ * single-member `allOf` wrapper, which plans (and stops at a circle) the same.
+ */
+const refOf = (schema: SchemaLike): string | undefined => {
+  const ref = schema.$ref ?? soleAllOfMember(schema)?.$ref;
+  return isString(ref) ? ref : undefined;
+};
+
 const typesOf = (schema: SchemaLike): (string | undefined)[] =>
   Array.isArray(schema.type) ? schema.type : [schema.type];
 
@@ -88,13 +98,32 @@ interface PendingRef {
   slot: SchemaSlot;
 }
 
-/** Plan the table tree for one schema (a request body, a response, a payload). */
+/**
+ * Which way a schema's data travels, when its table has one: a request body
+ * leaves out the `readOnly` fields the server generates, and a response the
+ * `writeOnly` ones it never returns, as the examples beside them do.
+ */
+export type SchemaDirection = "request" | "response";
+
+/**
+ * Plan the table tree for one schema (a request body, a response, a payload).
+ * With a `direction`, every table in the tree leaves out the fields that
+ * don't travel that way.
+ */
 export const schemaTree = (
   root: SchemaLike,
-  schemas: Record<string, SchemaLike>
+  schemas: Record<string, SchemaLike>,
+  direction?: SchemaDirection
 ): SchemaNode => {
   const queue: PendingRef[] = [];
   const expanded = new Set<string>();
+  const omitted = direction === "request" ? "readOnly" : "writeOnly";
+
+  /** Whether a property stays out of this tree's tables. */
+  const hidden = (property: SchemaLike): boolean =>
+    direction !== undefined &&
+    (property[omitted] === true ||
+      resolveSchema(schemas, property)[omitted] === true);
 
   /**
    * A table for `schema`, where `ancestors` are the named schemas already
@@ -107,8 +136,9 @@ export const schemaTree = (
     ancestors: string[],
     resolved = false
   ): SchemaSlot => {
-    if (!resolved && isString(schema.$ref)) {
-      const name = refName(schema.$ref);
+    const ref = resolved ? undefined : refOf(schema);
+    if (ref) {
+      const name = refName(ref);
       if (ancestors.includes(name)) {
         return { node: { kind: "circular", name } };
       }
@@ -132,10 +162,8 @@ export const schemaTree = (
     }
     // A row discloses nested structure — never a model inside itself.
     const rowChildren = (property: SchemaLike): SchemaSlot | undefined => {
-      if (
-        isString(property.$ref) &&
-        ancestors.includes(refName(property.$ref))
-      ) {
+      const propertyRef = refOf(property);
+      if (propertyRef && ancestors.includes(refName(propertyRef))) {
         return undefined;
       }
       const target = resolveSchema(schemas, property);
@@ -147,12 +175,14 @@ export const schemaTree = (
         : undefined;
     };
     const { properties, required } = objectProperties(schema, schemas);
-    const rows: SchemaRow[] = properties.map(([name, property]) => ({
-      children: rowChildren(property),
-      name,
-      required: required.has(name),
-      schema: property,
-    }));
+    const rows: SchemaRow[] = properties
+      .filter(([, property]) => !hidden(property))
+      .map(([name, property]) => ({
+        children: rowChildren(property),
+        name,
+        required: required.has(name),
+        schema: property,
+      }));
     // Shared properties beside a `oneOf`/`anyOf` (`amount` and `currency`
     // next to `Card | BankAccount`) render above the variants, planned first
     // as they read first.