diff --git a/docs/manifest.json b/docs/manifest.json index 9d0954b6b4b44..4b4f6fbb73b9e 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -713,6 +713,12 @@ "markdown_source": "../packages/components/src/checkbox-control/README.md", "parent": "components" }, + { + "title": "CircularOptionPicker", + "slug": "circular-option-picker", + "markdown_source": "../packages/components/src/circular-option-picker/README.md", + "parent": "components" + }, { "title": "ClipboardButton", "slug": "clipboard-button", diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md index 450c381a83c52..267c23bc8fcdf 100644 --- a/packages/components/CHANGELOG.md +++ b/packages/components/CHANGELOG.md @@ -6,6 +6,10 @@ - `ToolsPanel`: Separate reset all filter registration from items registration and support global resets ([#48123](https://github.com/WordPress/gutenberg/pull/48123#pullrequestreview-1308386926)). +### Internal + +- `CircularOptionPicker`: Convert to TypeScript ([#47937](https://github.com/WordPress/gutenberg/pull/47937)). + ## 23.4.0 (2023-02-15) ### Bug Fix diff --git a/packages/components/src/circular-option-picker/README.md b/packages/components/src/circular-option-picker/README.md new file mode 100644 index 0000000000000..122eca4fa5632 --- /dev/null +++ b/packages/components/src/circular-option-picker/README.md @@ -0,0 +1,141 @@ +# `CircularOptionPicker` + +
+This component is not exported, and therefore can only be used internally to the `@wordpress/components` package. +
+ +`CircularOptionPicker` is a component that displays a set of options as circular buttons. + +## Usage + +```jsx +import { CircularOptionPicker } from '../circular-option-picker'; +import { useState } from '@wordpress/element'; + +const Example = () => { + const [ currentColor, setCurrentColor ] = useState(); + const colors = [ + { color: '#f00', name: 'Red' }, + { color: '#0f0', name: 'Green' }, + { color: '#00f', name: 'Blue' }, + ]; + const colorOptions = ( + <> + { colors.map( ( { color, name }, index ) => { + return ( + setCurrentColor( index ) } + aria-label={ name } + /> + ); + } ) } + + ); + return ( + setCurrentColor( undefined ) } + > + { 'Clear' } + + } + /> + ); +}; +``` + +## Props + +### `className`: `string` + +A CSS class to apply to the wrapper element. + +- Required: No + +### `actions`: `ReactNode` + +The action(s) to be rendered after the options, such as a 'clear' button as seen in `ColorPalette`. + +Usually a `CircularOptionPicker.ButtonAction` or `CircularOptionPicker.DropdownLinkAction` component. + +- Required: No + +### `options`: `ReactNode` + +The options to be rendered, such as color swatches. + +Usually a `CircularOptionPicker.Option` component. + +- Required: No + +### `children`: `ReactNode` + +The child elements. + +- Required: No + +## Subcomponents + +### `CircularOptionPicker.ButtonAction` + +A `ButtonAction` is an action that is rendered as a button alongside the options themselves. + +A common use case is a 'clear' button to deselect the currently selected option. + +#### Props + +##### `className`: `string` + +A CSS class to apply to the underlying `Button` component. + +- Required: No + +##### `children`: `ReactNode` + +The button's children. + +- Required: No + +##### Inherited props + +`CircularOptionPicker.ButtonAction` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`. + +### `CircularOptionPicker.DropdownLinkAction` + +`CircularOptionPicker.DropdownLinkAction` is an action that's hidden behind a dropdown toggle. The button is formatted as a link and rendered as an `anchor` element. + +#### Props + +##### `className`: `string` + +A CSS class to apply to the underlying `Dropdown` component. + +- Required: No + +##### `linkText`: `string` + +The text to be displayed on the button. + +- Required: Yes + +##### `dropdownProps`: `object` + +The props for the underlying `Dropdown` component. + +Inherits all of the [`Dropdown` props](/packages/components/src/dropdown/README.md#props), except for `className` and `renderToggle`. + +- Required: Yes + +##### `buttonProps`: `object` + +Props for the underlying `Button` component. + +Inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href`, `target`, and `children`. + +- Required: No diff --git a/packages/components/src/circular-option-picker/index.js b/packages/components/src/circular-option-picker/index.tsx similarity index 50% rename from packages/components/src/circular-option-picker/index.js rename to packages/components/src/circular-option-picker/index.tsx index f41813906fcab..1736d2227ee77 100644 --- a/packages/components/src/circular-option-picker/index.js +++ b/packages/components/src/circular-option-picker/index.tsx @@ -1,4 +1,3 @@ -// @ts-nocheck /** * External dependencies */ @@ -15,15 +14,21 @@ import { Icon, check } from '@wordpress/icons'; import Button from '../button'; import Dropdown from '../dropdown'; import Tooltip from '../tooltip'; +import type { + CircularOptionPickerProps, + DropdownLinkActionProps, + OptionProps, +} from './types'; +import type { WordPressComponentProps } from '../ui/context'; +import type { ButtonAsButtonProps } from '../button/types'; -function Option( props ) { - const { - className, - isSelected, - selectedIconProps, - tooltipText, - ...additionalProps - } = props; +export function Option( { + className, + isSelected, + selectedIconProps, + tooltipText, + ...additionalProps +}: OptionProps ) { const optionButton = (