Widget Dashboard: measure the header fit and document the chrome

[retrofox]

What?

Fix the tile header so the inline attribute controls collapse into a dropdown at the right point.

The fit is measured from the actual header row rather than fixed reserves, so a help note in the identity or the actions menu beside the controls no longer skews the budget. Fixes #80398.

Truncate the header title with an ellipsis instead of letting it wrap out of the single-line row.

Add Storybook docs for the dashboard: Introduction, Anatomy, and Widget Chrome.
The last one covers the header's sections and how the fit adapts.

Rename the attribute section for a vocabulary parallel to widget-actions (see the note on renaming below).

Why?

The previous fit reconstructed the header from constants: a fixed 128px identity reserve plus a partial toolbar measurement. Anything the math did not know skewed the result.

A help tooltip lives inside the identity but was not in the constant, so availableSize was overestimated, causing the controls to overflow instead of collapsing.

The "More" menu actions sit beside the controls, and their width was not reduced either. The help case reproduces on trunk; both reproduce on this branch. #80398.

The chrome also had no shared documentation. The header's section model and its fit behavior lived only in the code.

How?

The header measures its own identity cluster (width plus the gap before the toolbar) and publishes availableSize.
Trailing sections register their footprint through useReserveHeaderSpace, and the header subtracts them.
The collapsible controls compare their natural width against what remains. No composite constants: whatever sits in the row is measured, so a new section counts on its own.

The toolbar chip reports its own padding and border the same way, as the difference between the border box and the content box the resize entry already carries. Observing the border box is what makes a padding change notify, since it leaves the content box untouched. No length in the budget is written twice.

One reserve path. Identity is measured by the header; every other section, the actions menu, and the settings trigger report up. useInlineFit reduces to natural > availableSize.

The docs are .md + .mdx story pages with hand-drawn SVGs, matching the widget-primitives pattern.

Testing

The stories exercise the fit directly:

npm run storybook:dev

1. Open Widget Dashboard / Playground and shrink the canvas.
   The high-relevance controls stay in line while they fit, then fold into the dropdown, and the actions menu keeps its place.

Screen.Recording.2026-07-20.at.2.14.15.PM.mov

2. Open Widget Dashboard / Playground / Long Title and shrink the canvas.
   The title truncates with an ellipsis instead of wrapping out of the header row.

3. Open Widget Dashboard / Introduction · Anatomy · Widget Chrome to review the docs.

In a real dashboard:

1. Enable the gutenberg-dashboard-widgets experiment.
2. Add the Hello Dolly widget and resize its tile.
3. The header adapts the same way; with a help note present, it now collapses at the right point instead of overflowing.

Screen.Recording.2026-07-17.at.5.19.40.PM.mov

Documentation is a work in progress

These three pages are a first pass. We keep improving them: more of the chrome, the customize mode, and the remaining sections still deserve their own coverage.

A note on renaming

This PR carries a sizable rename pass, in favor of code quality and a coherent, parallel section vocabulary:

• widget-attribute-controls → widget-attributes (WidgetAttributes), with attributes-dropdown and use-inline-fit inside.
• widget-header-size.ts → widget-header-fit.ts, which holds the fit contexts.
• the value type WidgetAttributes → WidgetAttributeValues, freeing the name for the section.

All via git mv, so history is preserved, and none of it changes behavior. CSS class names and the reserved IDs were left as-is to limit churn; more naming cleanup may follow.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: retrofox <retrofox@git.wordpress.org>
Co-authored-by: chihsuan <chihsuan@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: 0 B

Total Size: 7.74 MB

_{compressed-size-action}

[chihsuan]

Thanks for working on this! One thing I’m unsure about is using the identity’s current width.

I also found a couple of small story/docs mismatches.

[chihsuan]

Was removing target intentional? The Help text, comments, story description, and example data still describe two fields, but only metric remains editable.

[retrofox]

It was intentional. I want to show a widget instance with a single inline Field. Updating the docs.

[chihsuan]

Small optional thought: Is it possible to measure the toolbar padding too? Keeping 8 in JS could drift from the CSS token later.

[retrofox]

You were right, as usual 👍, and the drift is reproducible.

Set the chip to padding: 16px, leave the constant at 8, and keep the inline fields inline past the point where they fit, so they overflow the tile.

The constant is gone 🧹. The chip reports its own horizontal frame as the difference between the two boxes the resize entry already carries:

const border = entry.borderBoxSize?.[ 0 ]?.inlineSize ?? 0;
const content = entry.contentBoxSize?.[ 0 ]?.inlineSize ?? 0;

registerReserved( id, Math.max( 0, border - content ) );

[chihsuan]

Tiny wording mismatch: only Attributes folds. Identity shrinks and Actions stays compact. Maybe we can update this sentence to match the SVG below?

[chihsuan]

I wonder if this should reserve the identity’s minimum width instead. Once the controls collapse, the identity grows into the free space, so the header may keep thinking there isn’t enough room to expand them again. That would also match the docs’ “identity floor” wording.

[retrofox]

Sorry, Chi, I don't follow you :-(

What do you mean? Did you notice any erratic behavior or something we should try to address?

[chihsuan]

Sorry, let me do more local tests first. 🙏

[retrofox]

I've slightly changed how the title behaves when the viewport width is stretched.

Now, it applies ellipsis, avoiding more than one line for the title. So maybe the issue you described was affected by this new behavior.

[chihsuan]

Thanks, just tested locally again. No issues found.

[chihsuan]

LGTM! nice work. 🚢

[github-actions]

Flaky tests detected in bf9099e.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29810935086
📝 Reported issues:

• [Flaky Test] should update the HTML only for the latest navigation #78835 in /test/e2e/specs/interactivity/router-navigate.spec.ts