Show open API nodes as nested boxes instead of guide lines

[akira28]

Open nodes in an API schema now sit in nested outlined boxes, so the open path through a deep schema reads from the outlines.

Affects: API reference

Prompt summary: Work on elastic/docs-eng-team#1072. In deeply nested oneOf/anyOf and object schemas, it is hard to tell which nodes are open and where you are. Prototype boxes with outlines only, in the greys the other panels use, and put the result on a draft PR for the preview.

Why

An open node draws a thin guide line that ends at its last child. With five or six levels open, the lines run together and nothing marks which node you are inside.

What

Boxes replace guide lines

An open object row or union variant is outlined in --color-grey-20, and its "hide properties" toggle is the header of that box. The guide lines and L-connectors are hidden. Each level indents by 0.25rem plus its border and padding, less than the old 1.25rem per level.

Innermost open box

The deepest open box in a chain gets a darker --color-grey-60 outline. It marks where the reader is.

Verify

npm ci && npm run build   # in src/Elastic.Documentation.Site
dotnet run --project src/tooling/docs-builder -- serve
# open an operation, open a section, then open nested properties

Check on the preview

• Elasticsearch: Run a search — open the request body, then inner_hits and docvalue_fields: each open node is a box, the innermost has the darker outline.
• Kibana: Create a case — union variants behind chips fold into boxes the same way.

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4493/

[lcawl]

This kind of reminds me of what we used to do in the manually-maintained API docs (e.g. https://www.elastic.co/guide/en/elasticsearch/reference/8.15/ml-put-job.html). Which I think we eventually had a problem with where something becomes so deeply nested that you can't represent it any more (i.e. you run out of room for the boxes). So as long as there's some way of automating / controlling when you point to objects in the "Types" section instead, this is seems fine to me.

[akira28]

This kind of reminds me of what we used to do in the manually-maintained API docs (e.g. https://www.elastic.co/guide/en/elasticsearch/reference/8.15/ml-put-job.html). Which I think we eventually had a problem with where something becomes so deeply nested that you can't represent it any more (i.e. you run out of room for the boxes). So as long as there's some way of automating / controlling when you point to objects in the "Types" section instead, this is seems fine to me.

do you have some extreme nesting example?