@wordpress/components
Version:
UI components for WordPress.
228 lines • 8.65 kB
TypeScript
import type { ReactNode } from 'react';
import type { HeadingSize } from '../heading/types';
import type { DropdownMenu } from '../dropdown-menu';
export type ResetAllFilter = (attributes?: any) => any;
type ResetAll = (filters?: ResetAllFilter[]) => void;
export type ToolsPanelProps = {
/**
* The child elements.
*/
children: ReactNode;
/**
* The dropdown menu props to configure the panel's `DropdownMenu`.
*/
dropdownMenuProps?: Omit<React.ComponentProps<typeof DropdownMenu>, 'label'>;
/**
* Flags that the items in this ToolsPanel will be contained within an inner
* wrapper element allowing the panel to lay them out accordingly.
*
* @default false
*/
hasInnerWrapper?: boolean;
/**
* The heading level of the panel's header.
*
* @default 2
*/
headingLevel?: HeadingSize;
/**
* Text to be displayed within the panel's header and as the `aria-label`
* for the panel's dropdown menu.
*/
label: string;
/**
* If a `panelId` is set, it is passed through the `ToolsPanelContext` and
* used to restrict panel items. When a `panelId` is set, items can only
* register themselves if the `panelId` is explicitly `null` or the item's
* `panelId` matches exactly.
*/
panelId?: string | null;
/**
* A function to call when the `Reset all` menu option is selected. As an
* argument, it receives an array containing the `resetAllFilter` callbacks
* of all the valid registered `ToolsPanelItems`.
*/
resetAll: ResetAll;
/**
* Advises the `ToolsPanel` that its child `ToolsPanelItem`s should render
* placeholder content instead of null when they are toggled off and hidden.
* Note that placeholder items won't apply the `className` that would be
* normally applied to a visible `ToolsPanelItem` via the `className` prop.
*
* @default false
*/
shouldRenderPlaceholderItems?: boolean;
/**
* Experimental prop allowing for a custom CSS class to be applied to the
* first visible `ToolsPanelItem` within the `ToolsPanel`.
*/
__experimentalFirstVisibleItemClass?: string;
/**
* Experimental prop allowing for a custom CSS class to be applied to the
* last visible `ToolsPanelItem` within the `ToolsPanel`.
*/
__experimentalLastVisibleItemClass?: string;
};
export type ToolsPanelHeaderProps = {
/**
* The dropdown menu props to configure the panel's `DropdownMenu`.
*/
dropdownMenuProps?: Omit<React.ComponentProps<typeof DropdownMenu>, 'label'>;
/**
* The heading level of the panel's header.
*
* @default 2
*/
headingLevel?: HeadingSize;
/**
* Text to be displayed within the panel header. It is also passed along as
* the `label` for the panel header's `DropdownMenu`.
*/
label: string;
/**
* The `resetAll` prop provides the callback to execute when the "Reset all"
* menu item is selected. Its purpose is to facilitate resetting any control
* values for items contained within this header's panel.
*/
resetAll: ResetAll;
/**
* This is executed when an individual control's menu item is toggled. It
* will update the panel's menu item state and call the panel item's
* `onSelect` or `onDeselect` callbacks as appropriate.
*/
toggleItem: (label: string) => void;
};
export type ToolsPanelItem = {
/**
* For optional items only, this determines whether the item is shown on
* first render even when `hasValue()` returns `false`.
*
* An item is always shown while it has a value, so this only controls the
* initial state of items without one.
*
* @default false
*/
defaultShown?: boolean;
/**
* This is called when building the `ToolsPanel` menu to determine the
* item's initial checked state.
*/
hasValue: () => boolean;
/**
* This prop identifies the current item as being displayed by default. This
* means it will show regardless of whether it has a value set or is toggled
* on in the panel's menu.
*
* @default false
*/
isShownByDefault?: boolean;
/**
* The supplied label is dual purpose. It is used as:
* 1. the human-readable label for the panel's dropdown menu
* 2. a key to locate the corresponding item in the panel's menu context to
* determine if the panel item should be displayed.
* A panel item's `label` should be unique among all items within a single
* panel.
*/
label: string;
/**
* A callback executed when the user shows or hides the item via the
* `ToolsPanel` menu, passed `true` when it was shown and `false` when it
* was hidden.
*
* Unlike `onDeselect`, this fires whether or not the item has a value, and
* only in response to an explicit menu action. Visibility changes with
* another cause do not trigger it, such as an item becoming visible
* because it received a value or because `defaultShown` was set, or
* hiding because `Reset all` ran.
*
* Items flagged with `isShownByDefault` are always visible and stay so when
* toggled off, so this is never called for them.
*
* A single menu action may also call `onSelect` or `onDeselect`, which are
* unchanged. Showing an item without a value calls this with `true` and
* `onSelect`; hiding an item that has a value calls this with `false` and
* `onDeselect`. Use this callback to track visibility and `onDeselect` to
* reset a value, rather than treating them as interchangeable.
*/
onShownChange?: (isShown: boolean) => void;
/**
* Panel items will ensure they are only registering with their intended panel
* by comparing the `panelId` props set on both the item and the panel itself,
* or if the `panelId` is explicitly `null`. This allows items to be injected
* from a shared source.
*/
panelId?: string | null;
};
export type ToolsPanelItemProps = ToolsPanelItem & {
/**
* The child elements.
*/
children?: ReactNode;
/**
* Called when this item is deselected in the `ToolsPanel` menu. This is
* normally used to reset the panel item control's value.
*/
onDeselect?: () => void;
/**
* A callback to take action when this item is selected in the `ToolsPanel`
* menu.
*/
onSelect?: () => void;
/**
* A `ToolsPanel` will collect each item's `resetAllFilter` and pass an
* array of these functions through to the panel's `resetAll` callback. They
* can then be iterated over to perform additional tasks.
*
* @default noop
*/
resetAllFilter?: ResetAllFilter;
};
/**
* The shape of an item as it is held in `ToolsPanel` state. It extends
* `ToolsPanelItem` with the data the panel needs but that isn't part of the
* item's own API surface.
*/
export type RegisteredToolsPanelItem = ToolsPanelItem & {
/**
* The item's `resetAllFilter`, collected at registration time so the panel
* doesn't need a second round of effects to gather them.
*/
resetAllFilter?: ResetAllFilter;
};
export type ToolsPanelMenuItemKey = 'default' | 'optional';
export type ToolsPanelMenuItems = {
[menuItemKey in ToolsPanelMenuItemKey]: {
[key: string]: boolean;
};
};
export type ToolsPanelContext = {
panelId?: string | null;
menuItems: ToolsPanelMenuItems;
hasMenuItems: boolean;
registerPanelItem: (item: RegisteredToolsPanelItem) => void;
deregisterPanelItem: (label: string, item?: RegisteredToolsPanelItem) => void;
registerResetAllFilter: (filter: ResetAllFilter) => void;
deregisterResetAllFilter: (filter: ResetAllFilter) => void;
flagItemCustomization: (value: boolean, label: string,
/**
* Ignored, and kept only so that existing three argument callers
* still typecheck. The group a value lands in now follows from the
* registered item's `isShownByDefault` rather than from the caller.
*/
group?: ToolsPanelMenuItemKey) => void;
isResetting: boolean;
shouldRenderPlaceholderItems: boolean;
areAllOptionalControlsHidden: boolean;
firstDisplayedItem?: string;
lastDisplayedItem?: string;
__experimentalFirstVisibleItemClass?: string;
__experimentalLastVisibleItemClass?: string;
};
export type ToolsPanelControlsGroupProps = {
itemClassName?: string;
items: [string, boolean][];
toggleItem: (label: string) => void;
};
export {};
//# sourceMappingURL=types.d.ts.map