From 3d17c61018b2e5d37755f690e35e7a0e6eadf5ff Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Fri, 13 Dec 2024 23:05:33 +0900
Subject: [PATCH] TreeSelect: Deprecate 36px default size (#67855)

* TreeSelect: Deprecate 36px default size

* Fix types

* Auto-generate readme

* Add changelog

* Fixup readme

Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
---
 packages/components/CHANGELOG.md              |   1 +
 .../components/src/input-control/types.ts     |   6 +-
 packages/components/src/tree-select/README.md | 171 +++++++++++++++---
 .../src/tree-select/docs-manifest.json        |   5 +
 packages/components/src/tree-select/index.tsx |  12 +-
 .../src/tree-select/stories/index.story.tsx   |   1 +
 packages/components/src/tree-select/types.ts  |   9 +-
 7 files changed, 172 insertions(+), 33 deletions(-)
 create mode 100644 packages/components/src/tree-select/docs-manifest.json

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index 49cc196b1f7e69..af71c4104b4d97 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -8,6 +8,7 @@
 
 ### Deprecations
 
+-   `TreeSelect`: Deprecate 36px default size ([#67855](https://github.com/WordPress/gutenberg/pull/67855)).
 -   `SelectControl`: Deprecate 36px default size ([#66898](https://github.com/WordPress/gutenberg/pull/66898)).
 -   `InputControl`: Deprecate 36px default size ([#66897](https://github.com/WordPress/gutenberg/pull/66897)).
 
diff --git a/packages/components/src/input-control/types.ts b/packages/components/src/input-control/types.ts
index 99c5b1aea92c37..edb69def619057 100644
--- a/packages/components/src/input-control/types.ts
+++ b/packages/components/src/input-control/types.ts
@@ -136,7 +136,7 @@ export interface InputBaseProps extends BaseProps, FlexProps {
 	 * If you want to apply standard padding in accordance with the size variant, wrap the element in
 	 * the provided `<InputControlPrefixWrapper>` component.
 	 *
-	 * @example
+	 * ```jsx
 	 * import {
 	 *   __experimentalInputControl as InputControl,
 	 *   __experimentalInputControlPrefixWrapper as InputControlPrefixWrapper,
@@ -145,6 +145,7 @@ export interface InputBaseProps extends BaseProps, FlexProps {
 	 * <InputControl
 	 *   prefix={<InputControlPrefixWrapper>@</InputControlPrefixWrapper>}
 	 * />
+	 * ```
 	 */
 	prefix?: ReactNode;
 	/**
@@ -154,7 +155,7 @@ export interface InputBaseProps extends BaseProps, FlexProps {
 	 * If you want to apply standard padding in accordance with the size variant, wrap the element in
 	 * the provided `<InputControlSuffixWrapper>` component.
 	 *
-	 * @example
+	 * ```jsx
 	 * import {
 	 *   __experimentalInputControl as InputControl,
 	 *   __experimentalInputControlSuffixWrapper as InputControlSuffixWrapper,
@@ -163,6 +164,7 @@ export interface InputBaseProps extends BaseProps, FlexProps {
 	 * <InputControl
 	 *   suffix={<InputControlSuffixWrapper>%</InputControlSuffixWrapper>}
 	 * />
+	 * ```
 	 */
 	suffix?: ReactNode;
 	/**
diff --git a/packages/components/src/tree-select/README.md b/packages/components/src/tree-select/README.md
index 3d26488478bd0c..493c83bf993b0c 100644
--- a/packages/components/src/tree-select/README.md
+++ b/packages/components/src/tree-select/README.md
@@ -1,10 +1,10 @@
 # TreeSelect
 
-TreeSelect component is used to generate select input fields.
+<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->
 
-## Usage
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-treeselect--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
 
-Render a user interface to select the parent page in a hierarchy of pages:
+Generates a hierarchical select input.
 
 ```jsx
 import { useState } from 'react';
@@ -15,7 +15,8 @@ const MyTreeSelect = () => {
 
 	return (
 		<TreeSelect
-		  __nextHasNoMarginBottom
+			__nextHasNoMarginBottom
+			__next40pxDefaultSize
 			label="Parent page"
 			noOptionLabel="No parent page"
 			onChange={ ( newPage ) => setPage( newPage ) }
@@ -50,51 +51,165 @@ const MyTreeSelect = () => {
 	);
 }
 ```
-
 ## Props
 
-The set of props accepted by the component will be specified below.
-Props not included in this set will be applied to the SelectControl component being used.
+### `__next40pxDefaultSize`
+
+Start opting into the larger default height that will become the default size in a future version.
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+### `__nextHasNoMarginBottom`
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+### `children`
+
+As an alternative to the `options` prop, `optgroup`s and `options` can be
+passed in as `children` for more customizability.
+
+ - Type: `ReactNode`
+ - Required: No
+
+### `disabled`
 
-### label
+If true, the `input` will be disabled.
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+### `hideLabelFromVision`
+
+If true, the label will only be visible to screen readers.
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+### `help`
+
+Additional description for the control.
+
+Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an `aria-describedby` attribute.
+
+ - Type: `ReactNode`
+ - Required: No
+
+### `label`
 
 If this property is added, a label will be generated using label property as the content.
 
--   Type: `String`
--   Required: No
+ - Type: `ReactNode`
+ - Required: No
+
+### `labelPosition`
+
+The position of the label.
 
-### noOptionLabel
+ - Type: `"top" | "bottom" | "side" | "edge"`
+ - Required: No
+ - Default: `'top'`
+
+### `noOptionLabel`
 
 If this property is added, an option will be added with this label to represent empty selection.
 
--   Type: `String`
--   Required: No
+ - Type: `string`
+ - Required: No
+
+### `onChange`
+
+A function that receives the value of the new option that is being selected as input.
+
+ - Type: `(value: string, extra?: { event?: ChangeEvent<HTMLSelectElement>; }) => void`
+ - Required: No
+
+### `options`
+
+An array of option property objects to be rendered,
+each with a `label` and `value` property, as well as any other
+`<option>` attributes.
 
-### onChange
+ - Type: `readonly ({ label: string; value: string; } & Omit<OptionHTMLAttributes<HTMLOptionElement>, "label" | "value">)[]`
+ - Required: No
 
-A function that receives the id of the new node element that is being selected.
+### `prefix`
+
+Renders an element on the left side of the input.
+
+By default, the prefix is aligned with the edge of the input border, with no padding.
+If you want to apply standard padding in accordance with the size variant, wrap the element in
+the provided `<InputControlPrefixWrapper>` component.
+
+```jsx
+import {
+  __experimentalInputControl as InputControl,
+  __experimentalInputControlPrefixWrapper as InputControlPrefixWrapper,
+} from '@wordpress/components';
+
+<InputControl
+  prefix={<InputControlPrefixWrapper>@</InputControlPrefixWrapper>}
+/>
+```
 
--   Type: `function`
--   Required: Yes
+ - Type: `ReactNode`
+ - Required: No
 
-### selectedId
+### `selectedId`
 
 The id of the currently selected node.
 
--   Type: `string` | `string[]`
--   Required: No
+ - Type: `string`
+ - Required: No
 
-### tree
+### `size`
+
+Adjusts the size of the input.
+
+ - Type: `"default" | "small" | "compact" | "__unstable-large"`
+ - Required: No
+ - Default: `'default'`
+
+### `suffix`
+
+Renders an element on the right side of the input.
+
+By default, the suffix is aligned with the edge of the input border, with no padding.
+If you want to apply standard padding in accordance with the size variant, wrap the element in
+the provided `<InputControlSuffixWrapper>` component.
+
+```jsx
+import {
+  __experimentalInputControl as InputControl,
+  __experimentalInputControlSuffixWrapper as InputControlSuffixWrapper,
+} from '@wordpress/components';
+
+<InputControl
+  suffix={<InputControlSuffixWrapper>%</InputControlSuffixWrapper>}
+/>
+```
+
+ - Type: `ReactNode`
+ - Required: No
+
+### `tree`
 
 An array containing the tree objects with the possible nodes the user can select.
 
--   Type: `Object[]`
--   Required: No
+ - Type: `Tree[]`
+ - Required: No
 
-#### __nextHasNoMarginBottom
+### `variant`
 
-Start opting into the new margin-free styles that will become the default in a future version.
+The style variant of the control.
 
--   Type: `Boolean`
--   Required: No
--   Default: `false`
+ - Type: `"default" | "minimal"`
+ - Required: No
+ - Default: `'default'`
diff --git a/packages/components/src/tree-select/docs-manifest.json b/packages/components/src/tree-select/docs-manifest.json
new file mode 100644
index 00000000000000..0e74d71d309e10
--- /dev/null
+++ b/packages/components/src/tree-select/docs-manifest.json
@@ -0,0 +1,5 @@
+{
+	"$schema": "../../schemas/docs-manifest.json",
+	"displayName": "TreeSelect",
+	"filePath": "./index.tsx"
+}
diff --git a/packages/components/src/tree-select/index.tsx b/packages/components/src/tree-select/index.tsx
index 075ae1268e3c72..66116576361623 100644
--- a/packages/components/src/tree-select/index.tsx
+++ b/packages/components/src/tree-select/index.tsx
@@ -11,6 +11,7 @@ import { SelectControl } from '../select-control';
 import type { TreeSelectProps, Tree, Truthy } from './types';
 import { useDeprecated36pxDefaultSizeProp } from '../utils/use-deprecated-props';
 import { ContextSystemProvider } from '../context';
+import { maybeWarnDeprecated36pxSize } from '../utils/deprecated-36px-size';
 
 const CONTEXT_VALUE = {
 	BaseControl: {
@@ -35,11 +36,11 @@ function getSelectOptions(
 }
 
 /**
- * TreeSelect component is used to generate select input fields.
+ * Generates a hierarchical select input.
  *
  * ```jsx
+ * import { useState } from 'react';
  * import { TreeSelect } from '@wordpress/components';
- * import { useState } from '@wordpress/element';
  *
  * const MyTreeSelect = () => {
  * 	const [ page, setPage ] = useState( 'p21' );
@@ -47,6 +48,7 @@ function getSelectOptions(
  * 	return (
  * 		<TreeSelect
  * 			__nextHasNoMarginBottom
+ * 			__next40pxDefaultSize
  * 			label="Parent page"
  * 			noOptionLabel="No parent page"
  * 			onChange={ ( newPage ) => setPage( newPage ) }
@@ -99,6 +101,12 @@ export function TreeSelect( props: TreeSelectProps ) {
 		].filter( < T, >( option: T ): option is Truthy< T > => !! option );
 	}, [ noOptionLabel, tree ] );
 
+	maybeWarnDeprecated36pxSize( {
+		componentName: 'TreeSelect',
+		size: restProps.size,
+		__next40pxDefaultSize: restProps.__next40pxDefaultSize,
+	} );
+
 	return (
 		<ContextSystemProvider value={ CONTEXT_VALUE }>
 			<SelectControl
diff --git a/packages/components/src/tree-select/stories/index.story.tsx b/packages/components/src/tree-select/stories/index.story.tsx
index b43245e5e16213..0ef8f44b790db0 100644
--- a/packages/components/src/tree-select/stories/index.story.tsx
+++ b/packages/components/src/tree-select/stories/index.story.tsx
@@ -50,6 +50,7 @@ const TreeSelectWithState: StoryFn< typeof TreeSelect > = ( props ) => {
 export const Default = TreeSelectWithState.bind( {} );
 Default.args = {
 	__nextHasNoMarginBottom: true,
+	__next40pxDefaultSize: true,
 	label: 'Label Text',
 	noOptionLabel: 'No parent page',
 	help: 'Help text to explain the select control.',
diff --git a/packages/components/src/tree-select/types.ts b/packages/components/src/tree-select/types.ts
index da90ece3a658e8..59e8e173fab02f 100644
--- a/packages/components/src/tree-select/types.ts
+++ b/packages/components/src/tree-select/types.ts
@@ -16,11 +16,18 @@ export interface Tree {
 // `TreeSelect` inherits props from `SelectControl`, but only
 // in single selection mode (ie. when the `multiple` prop is not defined).
 export interface TreeSelectProps
-	extends Omit< SelectControlSingleSelectionProps, 'value' | 'multiple' > {
+	extends Omit<
+		SelectControlSingleSelectionProps,
+		'value' | 'multiple' | 'onChange'
+	> {
 	/**
 	 * If this property is added, an option will be added with this label to represent empty selection.
 	 */
 	noOptionLabel?: string;
+	/**
+	 * A function that receives the value of the new option that is being selected as input.
+	 */
+	onChange?: SelectControlSingleSelectionProps[ 'onChange' ];
 	/**
 	 * An array containing the tree objects with the possible nodes the user can select.
 	 */