Components: Add props for Toolspanel (isShownOnFirstRender and onVisibilityChange)

[im3dabasia]

What?

Focuses on: #41544 (comment), Conclusion comment for the discussion of the issue #41544 (comment)

Closes #41544

Adds two new props to the ToolsPanel component:

• isShownOnFirstRender on ToolsPanelItem: allows optional items to be visible on first render without requiring a value
• onVisibilityChange on ToolsPanel: a callback that notifies consumers which panel items are currently shown or hidden

Why?

Currently, optional ToolsPanelItem components are only rendered when they have a value or are toggled on by the user. There was no way to pre-show an optional item, or for consumers to know the current visibility state of items without reaching into internals.

How?

• Added isShownOnFirstRender?: boolean to ToolsPanelItem props; used in generateMenuItems to set the initial menu state for optional items
• Added onVisibilityChange?: ( { shown, hidden }: ToolsPanelVisibility ) => void to ToolsPanelProps; fires via a useEffect in useToolsPanel whenever menu state changes
• Added unit tests for both behaviors including DOM assertions

Testing Instructions

1. Render a ToolsPanel with an optional ToolsPanelItem and pass isShownOnFirstRender — the item should be visible on first paint
2. Pass an onVisibilityChange callback — it should fire with { shown, hidden } arrays reflecting current panel state, and update when items are toggled via the dropdown menu

Have added unit tests for both the above props.

Use of AI Tools

GitHub Copilot

[aaronrobertshaw]

Thanks for putting the PR together 👍

I don’t think onVisibilityChange is the right direction here.

This adds a broad panel-level API for something that should remain item-level state. ToolsPanelItem already has onSelect and onDeselect, and those are the natural extension points for tracking whether a specific item has been shown or hidden.

The main issue is that the current callbacks are value-gated. That means an optional item can be shown, receive no value, and then be hidden without onDeselect firing. That should be extended or tweaked directly rather than adding a second panel-level visibility lifecycle.

My specific concerns with onVisibilityChange are:

• It exposes aggregate internal ToolsPanel menu state as public API.
• It reports visibility by label, which is not a stable identifier. Labels are user-facing, translatable, and subject to copy changes.
• It forces consumers to map parent-level label arrays back to individual controls.
• It is awkward for SlotFill injected items, where the panel owner and item owner may not be the same code.
• It can fire from registration changes, conditional rendering, value changes, and reset behaviour, not just an explicit user show/hide action.
• It does not replace onDeselect, because consumers still need item-level reset behaviour.
• The PR does not demonstrate a real consumer that proves this panel-level abstraction is necessary.

I think the better fix is to make onSelect and onDeselect fire on actual item menu selection transitions:

• item selected/shown from the menu → onSelect
• item deselected/hidden from the menu → onDeselect

That gives consumers the control needed to track/persist visibility at the item level, lets them use their own stable IDs, and avoids exposing the panel’s internal visibility bookkeeping as a new public API.

So I’d prefer we do not add onVisibilityChange and instead expand the existing ToolsPanelItem callbacks.

[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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @apeatling.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

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

Unlinked contributors: apeatling.

Co-authored-by: im3dabasia <im3dabasia1@git.wordpress.org>
Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org>
Co-authored-by: mtias <matveb@git.wordpress.org>
Co-authored-by: annezazu <annezazu@git.wordpress.org>
Co-authored-by: markhowellsmead <markhowellsmead@git.wordpress.org>
Co-authored-by: bacoords <bacoords@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org>

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