@wordpress/components 40.0.0 → 40.1.1-next.v.202609031004.0

package/src/tools-panel/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,3 +1,4 @@
+import { useState } from '@wordpress/element';
 import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { ToolsPanel, ToolsPanelContext, ToolsPanelItem } from '../';
@@ -38,6 +39,7 @@ const controlProps = {
 		controlValue = undefined;
 	} ),
 	onSelect: jest.fn(),
+	onShownChange: jest.fn(),
 };
 
 // Default props without a value for an alternate control to be rendered within
@@ -50,6 +52,7 @@ const altControlProps = {
 	label: 'Alt',
 	onDeselect: jest.fn(),
 	onSelect: jest.fn(),
+	onShownChange: jest.fn(),
 };
 
 // Default props for wrapped or grouped panel items.
@@ -488,6 +491,156 @@ describe( 'ToolsPanel', () => {
 			expect( controlRerendered ).toBeInTheDocument();
 		} );
 
+		it( 'should not render optional item without a value by default', () => {
+			render(
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem { ...altControlProps }>
+						<div>Optional control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			expect(
+				screen.queryByText( 'Optional control' )
+			).not.toBeInTheDocument();
+		} );
+
+		it( 'should render optional item on first render when defaultShown is true', () => {
+			render(
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem { ...altControlProps } defaultShown>
+						<div>Optional control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			expect(
+				screen.getByText( 'Optional control' )
+			).toBeInTheDocument();
+		} );
+
+		it( 'should render optional item with a value even when defaultShown is false', () => {
+			altControlValue = true;
+
+			render(
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem
+						{ ...altControlProps }
+						defaultShown={ false }
+					>
+						<div>Optional control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			expect(
+				screen.getByText( 'Optional control' )
+			).toBeInTheDocument();
+		} );
+
+		// `defaultShown` only seeds the item's initial visibility. A change
+		// after mount must leave the item as it is, and must not be reported
+		// as though the user had used the menu.
+		describe( 'changing defaultShown after mount', () => {
+			const onDeselect = jest.fn();
+			const onSelect = jest.fn();
+			const onShownChange = jest.fn();
+
+			const ToolsPanelOptional = ( {
+				defaultShown,
+			}: {
+				defaultShown: boolean;
+			} ) => (
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem
+						defaultShown={ defaultShown }
+						hasValue={ () => false }
+						label="Alt"
+						onDeselect={ onDeselect }
+						onSelect={ onSelect }
+						onShownChange={ onShownChange }
+					>
+						<div>Optional control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			beforeEach( () => {
+				jest.clearAllMocks();
+			} );
+
+			it( 'should keep a hidden item hidden when it changes to true', () => {
+				const { rerender } = render(
+					<ToolsPanelOptional defaultShown={ false } />
+				);
+
+				rerender( <ToolsPanelOptional defaultShown /> );
+
+				expect(
+					screen.queryByText( 'Optional control' )
+				).not.toBeInTheDocument();
+				expect( onShownChange ).not.toHaveBeenCalled();
+				expect( onSelect ).not.toHaveBeenCalled();
+				expect( onDeselect ).not.toHaveBeenCalled();
+			} );
+
+			it( 'should keep a shown item visible when it changes to false', () => {
+				const { rerender } = render(
+					<ToolsPanelOptional defaultShown />
+				);
+
+				rerender( <ToolsPanelOptional defaultShown={ false } /> );
+
+				expect(
+					screen.getByText( 'Optional control' )
+				).toBeInTheDocument();
+				expect( onShownChange ).not.toHaveBeenCalled();
+				expect( onSelect ).not.toHaveBeenCalled();
+				expect( onDeselect ).not.toHaveBeenCalled();
+			} );
+		} );
+
+		it( 'should keep an item the user hid hidden when another item registers', async () => {
+			// Registering an item regenerates the panel's menu state. An item
+			// the user hid is stored as `false`, which must be preserved
+			// rather than treated as unregistered and reseeded from
+			// `defaultShown`.
+			const TestPanel = ( { showExtra }: { showExtra: boolean } ) => (
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem { ...altControlProps } defaultShown>
+						<div>Optional control</div>
+					</ToolsPanelItem>
+					{ showExtra && (
+						<ToolsPanelItem
+							hasValue={ () => false }
+							label="Extra"
+							onDeselect={ noop }
+							onSelect={ noop }
+						>
+							<div>Extra control</div>
+						</ToolsPanelItem>
+					) }
+				</ToolsPanel>
+			);
+
+			const { rerender } = render( <TestPanel showExtra={ false } /> );
+			expect(
+				screen.getByText( 'Optional control' )
+			).toBeInTheDocument();
+
+			await openDropdownMenu();
+			await selectMenuItem( altControlProps.label );
+			expect(
+				screen.queryByText( 'Optional control' )
+			).not.toBeInTheDocument();
+
+			rerender( <TestPanel showExtra /> );
+
+			expect(
+				screen.queryByText( 'Optional control' )
+			).not.toBeInTheDocument();
+		} );
+
 		it( 'should continue to render shown by default item after it is toggled off via menu item', async () => {
 			render(
 				<ToolsPanel { ...defaultProps }>
@@ -734,7 +887,8 @@ describe( 'ToolsPanel', () => {
 			expect( context.registerPanelItem ).toHaveBeenCalledTimes( 1 );
 			// deregisterPanelItem is called, given that we have switched panels.
 			expect( context.deregisterPanelItem ).toHaveBeenCalledWith(
-				altControlProps.label
+				altControlProps.label,
+				expect.objectContaining( { label: altControlProps.label } )
 			);
 
 			// Simulate switching back to the original panelId, e.g. by selecting
@@ -757,6 +911,72 @@ describe( 'ToolsPanel', () => {
 			expect( context.deregisterPanelItem ).toHaveBeenCalledTimes( 1 );
 		} );
 
+		it( 'should register with the latest defaultShown when panelId changes', () => {
+			// A consumer that persists the user's choice feeds it back in
+			// through `defaultShown`. A change to that prop must not
+			// re-register the item on its own, but a re-registration caused by
+			// something else has to seed from the saved preference rather than
+			// the value the item mounted with.
+			const context: ToolsPanelContextType = {
+				...panelContext,
+				registerPanelItem: jest.fn(),
+				deregisterPanelItem: jest.fn(),
+			};
+			const TestPanel = ( {
+				defaultShown,
+			}: {
+				defaultShown: boolean;
+			} ) => (
+				<ToolsPanelContext.Provider value={ context }>
+					<ToolsPanelItem
+						{ ...altControlProps }
+						defaultShown={ defaultShown }
+						panelId="1234"
+					>
+						<div>Item</div>
+					</ToolsPanelItem>
+				</ToolsPanelContext.Provider>
+			);
+
+			const { rerender } = render( <TestPanel defaultShown={ false } /> );
+
+			expect( context.registerPanelItem ).toHaveBeenCalledWith(
+				expect.objectContaining( { defaultShown: false } )
+			);
+
+			// Let registration settle, so that any further calls can only
+			// have been caused by the changes made below.
+			rerender( <TestPanel defaultShown={ false } /> );
+			const settledCalls = ( context.registerPanelItem as jest.Mock ).mock
+				.calls.length;
+
+			// The user shows the item and the consumer saves that preference.
+			// The updated prop alone must not re-register the item, which
+			// would discard the visibility the user chose.
+			rerender( <TestPanel defaultShown /> );
+
+			expect( context.registerPanelItem ).toHaveBeenCalledTimes(
+				settledCalls
+			);
+
+			// Simulate switching block selection away and back again, which
+			// deregisters and re-registers the item.
+			context.panelId = '4321';
+			rerender( <TestPanel defaultShown /> );
+			context.panelId = '1234';
+			rerender( <TestPanel defaultShown /> );
+
+			expect( context.deregisterPanelItem ).toHaveBeenCalledWith(
+				altControlProps.label,
+				expect.objectContaining( { label: altControlProps.label } )
+			);
+			// The item registers again with the saved preference rather than
+			// the value it mounted with.
+			expect( context.registerPanelItem ).toHaveBeenLastCalledWith(
+				expect.objectContaining( { defaultShown: true } )
+			);
+		} );
+
 		it( 'should register items when ToolsPanel panelId is null', () => {
 			// This test simulates when a panel spans multiple block selections.
 			// Multi-selection means a panel can't have a single id to match
@@ -802,23 +1022,24 @@ describe( 'ToolsPanel', () => {
 			expect( context.deregisterPanelItem ).not.toHaveBeenCalled();
 
 			// Simulate another multi-selection where the panelId is `null`.
-			// Item should re-register itself after it deregistered as the
-			// multi-selection occurred.
+			// Still matches the panel, so the registration stands rather than
+			// churning through a deregister/register pair.
 			context.panelId = null;
 			rerender( <TestPanel /> );
-			expect( context.registerPanelItem ).toHaveBeenCalledTimes( 2 );
-			expect( context.deregisterPanelItem ).toHaveBeenCalledTimes( 1 );
+			expect( context.registerPanelItem ).toHaveBeenCalledTimes( 1 );
+			expect( context.deregisterPanelItem ).not.toHaveBeenCalled();
 
 			// Simulate a change in panel e.g. back to a single block selection
 			// Where the item's panelId is not a match.
 			context.panelId = '4321';
 			rerender( <TestPanel /> );
 
-			// As the item no longer matches the panelId it should not have
-			// registered again but instead deregistered.
+			// No longer matches, so it has already deregistered. Unmounting
+			// must not deregister again.
+			expect( context.deregisterPanelItem ).toHaveBeenCalledTimes( 1 );
 			unmount();
-			expect( context.registerPanelItem ).toHaveBeenCalledTimes( 2 );
-			expect( context.deregisterPanelItem ).toHaveBeenCalledTimes( 2 );
+			expect( context.registerPanelItem ).toHaveBeenCalledTimes( 1 );
+			expect( context.deregisterPanelItem ).toHaveBeenCalledTimes( 1 );
 		} );
 	} );
 
@@ -878,6 +1099,126 @@ describe( 'ToolsPanel', () => {
 		} );
 	} );
 
+	describe( 'shown change callback', () => {
+		beforeEach( () => {
+			jest.clearAllMocks();
+		} );
+
+		it( 'should call onShownChange with true when an optional item is shown via the menu', async () => {
+			renderPanel();
+
+			await openDropdownMenu();
+			await selectMenuItem( altControlProps.label );
+
+			expect( altControlProps.onShownChange ).toHaveBeenCalledTimes( 1 );
+			expect( altControlProps.onShownChange ).toHaveBeenCalledWith(
+				true
+			);
+		} );
+
+		it( 'should call onShownChange with false when an optional item without a value is hidden via the menu', async () => {
+			renderPanel();
+
+			await openDropdownMenu();
+			await selectMenuItem( altControlProps.label );
+			await selectMenuItem( altControlProps.label );
+
+			expect( altControlProps.onShownChange ).toHaveBeenCalledTimes( 2 );
+			expect( altControlProps.onShownChange ).toHaveBeenLastCalledWith(
+				false
+			);
+			// The item never had a value, so there was nothing to reset.
+			expect( altControlProps.onDeselect ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should call both onShownChange and onDeselect when an optional item with a value is hidden via the menu', async () => {
+			renderPanel();
+
+			await openDropdownMenu();
+			await selectMenuItem( controlProps.label );
+
+			expect( controlProps.onShownChange ).toHaveBeenCalledTimes( 1 );
+			expect( controlProps.onShownChange ).toHaveBeenCalledWith( false );
+			expect( controlProps.onDeselect ).toHaveBeenCalledTimes( 1 );
+		} );
+
+		it( 'should not call onShownChange for default items', async () => {
+			render(
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem { ...controlProps } isShownByDefault>
+						<div>Example control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			await openDropdownMenu();
+			await selectMenuItem( controlProps.label );
+
+			// Default items stay visible when toggled off; the action resets
+			// them rather than hiding them.
+			expect( controlProps.onDeselect ).toHaveBeenCalledTimes( 1 );
+			expect( controlProps.onShownChange ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should not call onShownChange when items are hidden by Reset all', async () => {
+			renderPanel();
+
+			await openDropdownMenu();
+			await selectMenuItem( 'Reset all' );
+
+			expect( controlProps.onShownChange ).not.toHaveBeenCalled();
+			expect( altControlProps.onShownChange ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should not call onShownChange when the value changes programmatically', () => {
+			const onShownChange = jest.fn();
+			const ToolsPanelOptional = ( { value }: { value?: number } ) => (
+				<ToolsPanel { ...defaultProps } panelId="1234">
+					<ToolsPanelItem
+						hasValue={ () => !! value }
+						label="Alt"
+						onShownChange={ onShownChange }
+						panelId="1234"
+					>
+						<div>Optional control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			const { rerender } = render( <ToolsPanelOptional /> );
+			expect(
+				screen.queryByText( 'Optional control' )
+			).not.toBeInTheDocument();
+
+			// Gaining a value shows the item, but that is not a menu action.
+			rerender( <ToolsPanelOptional value={ 100 } /> );
+			expect(
+				screen.getByText( 'Optional control' )
+			).toBeInTheDocument();
+
+			// Losing it again is not a menu action either.
+			rerender( <ToolsPanelOptional /> );
+
+			expect( onShownChange ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should not call any callback when an item is mounted with defaultShown', () => {
+			render(
+				<ToolsPanel { ...defaultProps }>
+					<ToolsPanelItem { ...altControlProps } defaultShown>
+						<div>Alt control</div>
+					</ToolsPanelItem>
+				</ToolsPanel>
+			);
+
+			// Registering an item as shown is not a menu action, so none of
+			// the item's callbacks should fire.
+			expect( screen.getByText( 'Alt control' ) ).toBeInTheDocument();
+			expect( altControlProps.onShownChange ).not.toHaveBeenCalled();
+			expect( altControlProps.onSelect ).not.toHaveBeenCalled();
+		} );
+	} );
+
 	describe( 'grouped panel items within custom components', () => {
 		it( 'should render grouped items correctly', () => {
 			renderGroupedItemsInPanel();
@@ -1153,6 +1494,103 @@ describe( 'ToolsPanel', () => {
 			expect( altControlProps.onDeselect ).not.toHaveBeenCalled();
 		} );
 
+		it( 'should not contain menu items for an item belonging to another panel', async () => {
+			// A fill can mount after the panel it is rendered into has already
+			// settled. An item whose `panelId` doesn't match must stay out of
+			// that panel's menu entirely, including out of the value flagging
+			// that populates it.
+			const Panel = ( { withForeign }: { withForeign: boolean } ) => (
+				<ToolsPanel { ...defaultProps } panelId="1234">
+					<ToolsPanelItem
+						label="Mine"
+						panelId="1234"
+						isShownByDefault
+						hasValue={ () => false }
+					>
+						<div>My control</div>
+					</ToolsPanelItem>
+					{ withForeign && (
+						<ToolsPanelItem
+							label="Foreign"
+							panelId="9999"
+							hasValue={ () => true }
+						>
+							<div>Foreign control</div>
+						</ToolsPanelItem>
+					) }
+				</ToolsPanel>
+			);
+
+			// Let the panel settle with only its own item registered, then
+			// bring in an item that belongs to a different panel.
+			const { rerender } = render( <Panel withForeign={ false } /> );
+			rerender( <Panel withForeign /> );
+
+			await openDropdownMenu();
+
+			expect(
+				screen.queryByRole( 'menuitemcheckbox', { name: /Foreign/i } )
+			).not.toBeInTheDocument();
+		} );
+
+		it( "should not let a replacement item inherit the outgoing one's state", async () => {
+			// Two blocks can each contribute a control of the same name. When
+			// selection moves between them, the incoming item starts from its
+			// own value rather than the visibility the user chose for the one
+			// it replaced.
+			const SameLabelInTwoPanels = ( {
+				panelId,
+			}: Pick<
+				React.ComponentProps< typeof ToolsPanelItem >,
+				'panelId'
+			> ) => (
+				<SlotFillProvider>
+					<ToolsPanelItems>
+						<ToolsPanelItem
+							label="Shared"
+							panelId="1234"
+							hasValue={ () => false }
+						>
+							<div>Item 1</div>
+						</ToolsPanelItem>
+					</ToolsPanelItems>
+					<ToolsPanelItems>
+						<ToolsPanelItem
+							label="Shared"
+							panelId="9999"
+							hasValue={ () => false }
+						>
+							<div>Item 2</div>
+						</ToolsPanelItem>
+					</ToolsPanelItems>
+					<ToolsPanel { ...defaultProps } panelId={ panelId }>
+						<Slot />
+					</ToolsPanel>
+				</SlotFillProvider>
+			);
+
+			const { rerender } = render(
+				<SameLabelInTwoPanels panelId="1234" />
+			);
+
+			// Show the first block's control.
+			await openDropdownMenu();
+			await selectMenuItem( 'Shared' );
+			expect( screen.getByText( 'Item 1' ) ).toBeInTheDocument();
+
+			// Move to the other block. Its control has no value and was never
+			// shown, so it stays hidden.
+			// The menu stays open across the rerender.
+			rerender( <SameLabelInTwoPanels panelId="9999" /> );
+
+			expect(
+				await screen.findByRole( 'menuitemcheckbox', {
+					name: 'Show Shared',
+				} )
+			).toBeInTheDocument();
+			expect( screen.queryByText( 'Item 2' ) ).not.toBeInTheDocument();
+		} );
+
 		it( 'should not contain orphaned menu items when panelId changes', async () => {
 			// As fills and the panel can update independently this aims to
 			// test that no orphaned items appear registered in the panel menu.
@@ -1291,6 +1729,45 @@ describe( 'ToolsPanel', () => {
 			expect( optionsDisplayedIcon ).not.toHaveAccessibleDescription();
 		} );
 
+		it( 'should pass reset all filters that see the latest props', async () => {
+			let received: unknown[] = [];
+			const ChangingFilter = () => {
+				const [ count, setCount ] = useState( 1 );
+				return (
+					<ToolsPanel
+						label="Panel header"
+						resetAll={ ( filters ) => {
+							received = ( filters ?? [] ).map( ( filter ) =>
+								filter()
+							);
+						} }
+					>
+						<ToolsPanelItem
+							label="Filtered"
+							isShownByDefault
+							hasValue={ () => true }
+							resetAllFilter={ () => count }
+						>
+							<button onClick={ () => setCount( 2 ) }>
+								bump
+							</button>
+						</ToolsPanelItem>
+					</ToolsPanel>
+				);
+			};
+
+			const user = userEvent.setup();
+			render( <ChangingFilter /> );
+
+			// The panelId never changes, which is where a filter frozen at
+			// registration goes stale.
+			await user.click( screen.getByText( 'bump' ) );
+			await openDropdownMenu();
+			await selectMenuItem( 'Reset all' );
+
+			expect( received ).toEqual( [ 2 ] );
+		} );
+
 		it( 'should not call reset all for different panelIds', async () => {
 			const resetItem = jest.fn();
 			const resetItemB = jest.fn();
@@ -1383,6 +1860,48 @@ describe( 'ToolsPanel', () => {
 		} );
 	} );
 
+	describe( 'reset all with values the reset leaves in place', () => {
+		it( 'should keep a default control resettable when its value survives', async () => {
+			// The value arrives after mount, like block library controls whose
+			// `hasValue` closes over an attribute: false at mount, true once
+			// edited. A value read back from registration time misses it.
+			const GainsAValue = () => {
+				const [ hasVal, setHasVal ] = useState( false );
+				return (
+					<ToolsPanel label="Panel header" resetAll={ () => {} }>
+						<ToolsPanelItem
+							label="Survivor"
+							isShownByDefault
+							hasValue={ () => hasVal }
+						>
+							<button onClick={ () => setHasVal( true ) }>
+								set a value
+							</button>
+						</ToolsPanelItem>
+					</ToolsPanel>
+				);
+			};
+
+			const user = userEvent.setup();
+			render( <GainsAValue /> );
+
+			await user.click( screen.getByText( 'set a value' ) );
+			await openDropdownMenu();
+			await selectMenuItem( 'Reset all' );
+
+			// `resetAll` clears nothing here, so the value is still set and
+			// must stay resettable from both menu entries.
+			expect(
+				await screen.findByRole( 'menuitem', { name: 'Reset all' } )
+			).toHaveAttribute( 'aria-disabled', 'false' );
+			expect(
+				await screen.findByRole( 'menuitem', {
+					name: 'Reset Survivor',
+				} )
+			).toBeInTheDocument();
+		} );
+	} );
+
 	describe( 'first and last panel items', () => {
 		it( 'should apply first/last classes to appropriate items', () => {
 			render(