@wordpress/components 29.0.1-next.a9f418477.0 → 29.1.0

package/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 ) }
@@ -53,48 +54,163 @@ 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`
 
-### label
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+Start opting into the larger default height that will become the default size in a future version.
+
+### `__nextHasNoMarginBottom`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+### `children`
+
+ - Type: `ReactNode`
+ - Required: No
+
+As an alternative to the `options` prop, `optgroup`s and `options` can be
+passed in as `children` for more customizability.
+
+### `disabled`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+If true, the `input` will be disabled.
+
+### `hideLabelFromVision`
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+If true, the label will only be visible to screen readers.
+
+### `help`
+
+ - Type: `ReactNode`
+ - Required: No
+
+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.
+
+### `label`
+
+ - Type: `ReactNode`
+ - Required: No
 
 If this property is added, a label will be generated using label property as the content.
 
--   Type: `String`
--   Required: No
+### `labelPosition`
+
+ - Type: `"top" | "bottom" | "side" | "edge"`
+ - Required: No
+ - Default: `'top'`
+
+The position of the label.
+
+### `noOptionLabel`
 
-### noOptionLabel
+ - Type: `string`
+ - Required: No
 
 If this property is added, an option will be added with this label to represent empty selection.
 
--   Type: `String`
--   Required: No
+### `onChange`
 
-### onChange
+ - Type: `(value: string, extra?: { event?: ChangeEvent<HTMLSelectElement>; }) => void`
+ - Required: No
 
-A function that receives the id of the new node element that is being selected.
+A function that receives the value of the new option that is being selected as input.
 
--   Type: `function`
--   Required: Yes
+### `options`
 
-### selectedId
+ - Type: `readonly ({ label: string; value: string; } & Omit<OptionHTMLAttributes<HTMLOptionElement>, "label" | "value">)[]`
+ - Required: No
+
+An array of option property objects to be rendered,
+each with a `label` and `value` property, as well as any other
+`<option>` attributes.
+
+### `prefix`
+
+ - Type: `ReactNode`
+ - Required: No
+
+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>}
+/>
+```
+
+### `selectedId`
+
+ - Type: `string`
+ - Required: No
 
 The id of the currently selected node.
 
--   Type: `string` | `string[]`
--   Required: No
+### `size`
 
-### tree
+ - Type: `"default" | "small" | "compact" | "__unstable-large"`
+ - Required: No
+ - Default: `'default'`
 
-An array containing the tree objects with the possible nodes the user can select.
+Adjusts the size of the input.
 
--   Type: `Object[]`
--   Required: No
+### `suffix`
 
-#### __nextHasNoMarginBottom
+ - Type: `ReactNode`
+ - Required: No
 
-Start opting into the new margin-free styles that will become the default in a future version.
+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>}
+/>
+```
+
+### `tree`
+
+ - Type: `Tree[]`
+ - Required: No
+
+An array containing the tree objects with the possible nodes the user can select.
+
+### `variant`
+
+ - Type: `"default" | "minimal"`
+ - Required: No
+ - Default: `'default'`
 
--   Type: `Boolean`
--   Required: No
--   Default: `false`
+The style variant of the control.

package/src/tree-select/docs-manifest.json

@@ -0,0 +1,5 @@
+{
+	"$schema": "../../schemas/docs-manifest.json",
+	"displayName": "TreeSelect",
+	"filePath": "./index.tsx"
+}

package/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,9 +101,16 @@ 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
+				__shouldNotWarnDeprecated36pxSize
 				{ ...{ label, options, onChange } }
 				value={ selectedId }
 				{ ...restProps }

package/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.',

package/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.
 	 */

package/src/utils/colors-values.js

@@ -75,6 +75,9 @@ export const COLORS = Object.freeze( {
 	 * @deprecated Use semantic aliases in `COLORS.ui` or theme-ready variables in `COLORS.theme.gray`.
 	 */
 	gray: GRAY, // TODO: Stop exporting this when everything is migrated to `theme` or `ui`
+	/**
+	 * @deprecated Prefer theme-ready variables in `COLORS.theme`.
+	 */
 	white,
 	alert: ALERT,
 	/**

package/src/utils/config-values.js

@@ -12,7 +12,6 @@ const CONTROL_PROPS = {
 	controlPaddingXSmall: 8,
 	controlPaddingXLarge: 12 * 1.3334, // TODO: Deprecate
 
-	controlBackgroundColor: COLORS.white,
 	controlBoxShadowFocus: `0 0 0 0.5px ${ COLORS.theme.accent }`,
 	controlHeight: CONTROL_HEIGHT,
 	controlHeightXSmall: `calc( ${ CONTROL_HEIGHT } * 0.6 )`,

package/tsconfig.json

@@ -2,8 +2,6 @@
 	"$schema": "https://json.schemastore.org/tsconfig.json",
 	"extends": "../../tsconfig.base.json",
 	"compilerOptions": {
-		"rootDir": "src",
-		"declarationDir": "build-types",
 		"types": [
 			"gutenberg-env",
 			"gutenberg-test-env",
@@ -31,7 +29,6 @@
 		{ "path": "../rich-text" },
 		{ "path": "../warning" }
 	],
-	"include": [ "src/**/*" ],
 	"exclude": [
 		"src/**/*.android.js",
 		"src/**/*.ios.js",