From 8a18eeae2e33bddc900e0edd69bfde4b913901f0 Mon Sep 17 00:00:00 2001 From: Marco Ciampini Date: Wed, 10 Jul 2024 23:14:56 +0200 Subject: [PATCH] CustomSelectControl V2 legacy adapter: stabilize experimental props (#63248) * CustomSelectControl V2: add showSelectedHint prop, deprecate __experimentalShowSelectedHint * Update showSelectedHint unit tests * CustomSelectControl V2: add hint option prop, deprecate __experimentalHint * Rename __experimentalHint to hint * Refactor to smarter approach * Continue using `__experimentalHint` in the V1 storybook example * CHANGELOG * Add hint to options only if necessary * __experimentalShowSelectedHint => showSelectedHint * Move changelog entry to unreleased section * Give priority to `showSelectedHint` over `__experimentalShowSelectedHint` * Move `__experimentalHint` => `hint` code to run at runtime This avoids breakages for any consumer relying on object identity * Fix wrong link in inline comment --- Co-authored-by: ciampo Co-authored-by: mirka <0mirka00@git.wordpress.org> Co-authored-by: tyxla --- .../components/date-format-picker/index.js | 2 +- packages/block-editor/src/hooks/position.js | 6 +- packages/components/CHANGELOG.md | 4 ++ .../legacy-component/index.tsx | 65 +++++++++++++------ .../legacy-component/test/index.tsx | 12 ++-- .../src/custom-select-control-v2/types.ts | 16 ++++- .../font-size-picker-select.tsx | 4 +- .../components/src/font-size-picker/types.ts | 2 +- 8 files changed, 74 insertions(+), 37 deletions(-) diff --git a/packages/block-editor/src/components/date-format-picker/index.js b/packages/block-editor/src/components/date-format-picker/index.js index 72e6d4831efa93..cf9af5eb33f122 100644 --- a/packages/block-editor/src/components/date-format-picker/index.js +++ b/packages/block-editor/src/components/date-format-picker/index.js @@ -126,7 +126,7 @@ function NonDefaultControls( { format, onChange } ) { name: __( 'Custom' ), className: 'block-editor-date-format-picker__custom-format-select-control__custom-option', - __experimentalHint: __( 'Enter your own date format' ), + hint: __( 'Enter your own date format' ), }; const [ isCustom, setIsCustom ] = useState( diff --git a/packages/block-editor/src/hooks/position.js b/packages/block-editor/src/hooks/position.js index 11fddf72896925..a5fae3d8d3a7c2 100644 --- a/packages/block-editor/src/hooks/position.js +++ b/packages/block-editor/src/hooks/position.js @@ -42,7 +42,7 @@ const STICKY_OPTION = { key: 'sticky', value: 'sticky', name: _x( 'Sticky', 'Name for the value of the CSS position property' ), - __experimentalHint: __( + hint: __( 'The block will stick to the top of the window instead of scrolling.' ), }; @@ -51,9 +51,7 @@ const FIXED_OPTION = { key: 'fixed', value: 'fixed', name: _x( 'Fixed', 'Name for the value of the CSS position property' ), - __experimentalHint: __( - 'The block will not move when the page is scrolled.' - ), + hint: __( 'The block will not move when the page is scrolled.' ), }; const POSITION_SIDES = [ 'top', 'right', 'bottom', 'left' ]; diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md index 401d92d06afe19..3699162feb5109 100644 --- a/packages/components/CHANGELOG.md +++ b/packages/components/CHANGELOG.md @@ -6,6 +6,10 @@ - `CustomSelectControlV2`: animate select popover appearance. ([#63343](https://github.com/WordPress/gutenberg/pull/63343)) +### Enhancements + +- `CustomSelectControl`: Stabilize `__experimentalShowSelectedHint` and `options[]. __experimentalHint` props ([#63248](https://github.com/WordPress/gutenberg/pull/63248)). + ## 28.3.0 (2024-07-10) ### Enhancements diff --git a/packages/components/src/custom-select-control-v2/legacy-component/index.tsx b/packages/components/src/custom-select-control-v2/legacy-component/index.tsx index a4c437be97e405..7dcdec9b7bdc60 100644 --- a/packages/components/src/custom-select-control-v2/legacy-component/index.tsx +++ b/packages/components/src/custom-select-control-v2/legacy-component/index.tsx @@ -12,9 +12,31 @@ import CustomSelectItem from '../item'; import type { LegacyCustomSelectProps } from '../types'; import * as Styled from '../styles'; +function useDeprecatedProps( { + __experimentalShowSelectedHint, + ...otherProps +}: LegacyCustomSelectProps ) { + return { + showSelectedHint: __experimentalShowSelectedHint, + ...otherProps, + }; +} + +// The removal of `__experimentalHint` in favour of `hint` doesn't happen in +// the `useDeprecatedProps` hook in order not to break consumers that rely +// on object identity (see https://github.com/WordPress/gutenberg/pull/63248#discussion_r1672213131) +function applyOptionDeprecations( { + __experimentalHint, + ...rest +}: LegacyCustomSelectProps[ 'options' ][ number ] ) { + return { + hint: __experimentalHint, + ...rest, + }; +} + function CustomSelectControl( props: LegacyCustomSelectProps ) { const { - __experimentalShowSelectedHint = false, __next40pxDefaultSize = false, describedBy, options, @@ -22,8 +44,9 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) { size = 'default', value, className: classNameProp, + showSelectedHint = false, ...restProps - } = props; + } = useDeprecatedProps( props ); // Forward props + store from v2 implementation const store = Ariakit.useSelectStore( { @@ -60,8 +83,9 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) { defaultValue: options[ 0 ]?.name, } ); - const children = options.map( - ( { name, key, __experimentalHint, style, className } ) => { + const children = options + .map( applyOptionDeprecations ) + .map( ( { name, key, hint, style, className } ) => { const withHint = ( { name } @@ -69,7 +93,7 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) { // TODO: Legacy classname. Add V1 styles are removed from the codebase // className="components-custom-select-control__item-hint" > - { __experimentalHint } + { hint } ); @@ -78,7 +102,7 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) { ); - } - ); + } ); const renderSelectedValueHint = () => { const { value: currentValue } = store.getState(); - const currentHint = options?.find( - ( { name } ) => currentValue === name - ); + const selectedOptionHint = options + ?.map( applyOptionDeprecations ) + ?.find( ( { name } ) => currentValue === name )?.hint; return ( { currentValue } - - { currentHint?.__experimentalHint } - + { selectedOptionHint && ( + + { selectedOptionHint } + + ) } ); }; @@ -131,9 +156,7 @@ function CustomSelectControl( props: LegacyCustomSelectProps ) { <_CustomSelect aria-describedby={ describedBy } renderSelectedValue={ - __experimentalShowSelectedHint - ? renderSelectedValueHint - : undefined + showSelectedHint ? renderSelectedValueHint : undefined } size={ translatedSize } store={ store } diff --git a/packages/components/src/custom-select-control-v2/legacy-component/test/index.tsx b/packages/components/src/custom-select-control-v2/legacy-component/test/index.tsx index 1e361236aafd9a..496b42572d82f6 100644 --- a/packages/components/src/custom-select-control-v2/legacy-component/test/index.tsx +++ b/packages/components/src/custom-select-control-v2/legacy-component/test/index.tsx @@ -297,7 +297,7 @@ describe.each( [ { key: 'one', name: 'One', - __experimentalHint: 'Hint', + hint: 'Hint', }, ] } /> @@ -309,7 +309,7 @@ describe.each( [ ); } ); - it( 'shows selected hint when __experimentalShowSelectedHint is set', async () => { + it( 'shows selected hint when showSelectedHint is set', async () => { render( ); @@ -334,7 +334,7 @@ describe.each( [ ); } ); - it( 'shows selected hint in list of options when added, regardless of __experimentalShowSelectedHint prop', async () => { + it( 'shows selected hint in list of options when added, regardless of showSelectedHint prop', async () => { render( diff --git a/packages/components/src/custom-select-control-v2/types.ts b/packages/components/src/custom-select-control-v2/types.ts index b663f1892ceebc..95a78c501839d6 100644 --- a/packages/components/src/custom-select-control-v2/types.ts +++ b/packages/components/src/custom-select-control-v2/types.ts @@ -90,6 +90,12 @@ type LegacyOption = { name: string; style?: React.CSSProperties; className?: string; + hint?: string; + /** + * Use the `hint` property instead + * @deprecated + * @ignore + */ __experimentalHint?: string; [ key: string ]: any; }; @@ -169,11 +175,17 @@ export type LegacyCustomSelectProps = { */ value?: LegacyOption; /** - * Legacy way to add additional text to the right of each option. + * Use the `showSelectedHint` property instead. + * @deprecated + * @ignore + */ + __experimentalShowSelectedHint?: boolean; + /** + * Show the hint of the selected item in the trigger button. * * @default false */ - __experimentalShowSelectedHint?: boolean; + showSelectedHint?: boolean; /** * Opt-in prop for an unconstrained width style which became the default in * WordPress 6.5. The prop is no longer needed and can be safely removed. diff --git a/packages/components/src/font-size-picker/font-size-picker-select.tsx b/packages/components/src/font-size-picker/font-size-picker-select.tsx index 3f0b7a0e54074a..4dd80b45b0ac70 100644 --- a/packages/components/src/font-size-picker/font-size-picker-select.tsx +++ b/packages/components/src/font-size-picker/font-size-picker-select.tsx @@ -56,7 +56,7 @@ const FontSizePickerSelect = ( props: FontSizePickerSelectProps ) => { key: fontSize.slug, name: fontSize.name || fontSize.slug, value: fontSize.size, - __experimentalHint: hint, + hint, }; } ), ...( disableCustomFontSizes ? [] : [ CUSTOM_OPTION ] ), @@ -79,7 +79,7 @@ const FontSizePickerSelect = ( props: FontSizePickerSelectProps ) => { ) } options={ options } value={ selectedOption } - __experimentalShowSelectedHint + showSelectedHint onChange={ ( { selectedItem, }: { diff --git a/packages/components/src/font-size-picker/types.ts b/packages/components/src/font-size-picker/types.ts index 6b4ed4b7ee75a5..0072c47df6f052 100644 --- a/packages/components/src/font-size-picker/types.ts +++ b/packages/components/src/font-size-picker/types.ts @@ -110,7 +110,7 @@ export type FontSizePickerSelectOption = { key: string; name: string; value?: FontSize[ 'size' ]; - __experimentalHint?: string; + hint?: string; }; export type FontSizePickerToggleGroupProps = Pick<