@wordpress/components 28.9.0 → 28.11.0

package/build-types/utils/hooks/use-animated-offset-rect.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal dependencies
+ */
+import type { ElementOffsetRect } from '../element-rect';
+/**
+ * A utility used to animate something in a container component based on the "offset
+ * rect" (position relative to the container and size) of a subelement. For example,
+ * this is useful to render an indicator for the selected option of a component, and
+ * to animate it when the selected option changes.
+ *
+ * Takes in a container element and the up-to-date "offset rect" of the target
+ * subelement, obtained with `useTrackElementOffsetRect`. Then it does the following:
+ *
+ * - Adds CSS variables with rect information to the container, so that the indicator
+ *   can be rendered and animated with them. These are kept up-to-date, enabling CSS
+ *   transitions on change.
+ * - Sets an attribute (`data-subelement-animated` by default) when the tracked
+ *   element changes, so that the target (e.g. the indicator) can be animated to its
+ *   new size and position.
+ * - Removes the attribute when the animation is done.
+ *
+ * The need for the attribute is due to the fact that the rect might update in
+ * situations other than when the tracked element changes, e.g. the tracked element
+ * might be resized. In such cases, there is no need to animate the indicator, and
+ * the change in size or position of the indicator needs to be reflected immediately.
+ */
+export declare function useAnimatedOffsetRect(
+/**
+ * The container element.
+ */
+container: HTMLElement | undefined, 
+/**
+ * The rect of the tracked element.
+ */
+rect: ElementOffsetRect, { prefix, dataAttribute, transitionEndFilter, roundRect, }?: {
+    /**
+     * The prefix used for the CSS variables, e.g. if `prefix` is `selected`, the
+     * CSS variables will be `--selected-top`, `--selected-left`, etc.
+     * @default 'subelement'
+     */
+    prefix?: string;
+    /**
+     * The name of the data attribute used to indicate that the animation is in
+     * progress. The `data-` prefix is added automatically.
+     *
+     * For example, if `dataAttribute` is `indicator-animated`, the attribute will
+     * be `data-indicator-animated`.
+     * @default `${ prefix }-animated`
+     */
+    dataAttribute?: string;
+    /**
+     * A function that is called with the transition event and returns a boolean
+     * indicating whether the animation should be stopped. The default is a function
+     * that always returns `true`.
+     *
+     * For example, if the animated element is the `::before` pseudo-element, the
+     * function can be written as `( event ) => event.pseudoElement === '::before'`.
+     * @default () => true
+     */
+    transitionEndFilter?: (event: TransitionEvent) => boolean;
+    /**
+     * Whether the `rect` measurements should be rounded down when applied
+     * to the CSS variables. This can be useful to avoid blurry animations or
+     * to avoid subpixel rendering issues.
+     * @default false
+     */
+    roundRect?: boolean;
+}): void;
+//# sourceMappingURL=use-animated-offset-rect.d.ts.map

package/build-types/utils/hooks/use-animated-offset-rect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-animated-offset-rect.d.ts","sourceRoot":"","sources":["../../../src/utils/hooks/use-animated-offset-rect.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB;AACpC;;GAEG;AACH,SAAS,EAAE,WAAW,GAAG,SAAS;AAClC;;GAEG;AACH,IAAI,EAAE,iBAAiB,EACvB,EACC,MAAqB,EACrB,aAAsC,EACtC,mBAAgC,EAChC,SAAiB,GACjB,GAAE;IACF;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,CAAE,KAAK,EAAE,eAAe,KAAM,OAAO,CAAC;IAC5D;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACf,QAmCN"}

package/build-types/utils/hooks/use-update-effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-update-effect.d.ts","sourceRoot":"","sources":["../../../src/utils/hooks/use-update-effect.js"],"names":[],"mappings":";AAKA;;;;;;;GAOG;AACH,yCAHW,OAAO,OAAO,EAAE,cAAc,QAC9B,OAAO,OAAO,EAAE,cAAc,QAuBxC"}
+{"version":3,"file":"use-update-effect.d.ts","sourceRoot":"","sources":["../../../src/utils/hooks/use-update-effect.js"],"names":[],"mappings":";AAKA;;;;;;;GAOG;AACH,yCAHW,OAAO,OAAO,EAAE,cAAc,QAC9B,OAAO,OAAO,EAAE,cAAc,QAqBxC"}

package/build-types/visually-hidden/stories/index.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/visually-hidden/stories/index.story.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;GAEG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AAEpC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,cAAc,CAatC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,OAAO,CAAE,OAAO,cAAc,CAanD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAE,OAAO,cAAc,CAW9D,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,OAAO,CAAE,OAAO,cAAc,CAWpE,CAAC"}
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/visually-hidden/stories/index.story.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;GAEG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AAEpC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,cAAc,CActC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,OAAO,CAAE,OAAO,cAAc,CAanD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,OAAO,CAAE,OAAO,cAAc,CAW9D,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,OAAO,CAAE,OAAO,cAAc,CAWpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "28.9.0",
+	"version": "28.11.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -32,7 +32,7 @@
 	"types": "build-types",
 	"dependencies": {
 		"@ariakit/react": "^0.4.10",
-		"@babel/runtime": "^7.16.0",
+		"@babel/runtime": "7.25.7",
 		"@emotion/cache": "^11.7.1",
 		"@emotion/css": "^11.7.1",
 		"@emotion/react": "^11.7.1",
@@ -43,23 +43,23 @@
 		"@types/gradient-parser": "0.1.3",
 		"@types/highlight-words-core": "1.2.1",
 		"@use-gesture/react": "^10.3.1",
-		"@wordpress/a11y": "^4.9.0",
-		"@wordpress/compose": "^7.9.0",
-		"@wordpress/date": "^5.9.0",
-		"@wordpress/deprecated": "^4.9.0",
-		"@wordpress/dom": "^4.9.0",
-		"@wordpress/element": "^6.9.0",
-		"@wordpress/escape-html": "^3.9.0",
-		"@wordpress/hooks": "^4.9.0",
-		"@wordpress/html-entities": "^4.9.0",
-		"@wordpress/i18n": "^5.9.0",
-		"@wordpress/icons": "^10.9.0",
-		"@wordpress/is-shallow-equal": "^5.9.0",
-		"@wordpress/keycodes": "^4.9.0",
-		"@wordpress/primitives": "^4.9.0",
-		"@wordpress/private-apis": "^1.9.0",
-		"@wordpress/rich-text": "^7.9.0",
-		"@wordpress/warning": "^3.9.0",
+		"@wordpress/a11y": "*",
+		"@wordpress/compose": "*",
+		"@wordpress/date": "*",
+		"@wordpress/deprecated": "*",
+		"@wordpress/dom": "*",
+		"@wordpress/element": "*",
+		"@wordpress/escape-html": "*",
+		"@wordpress/hooks": "*",
+		"@wordpress/html-entities": "*",
+		"@wordpress/i18n": "*",
+		"@wordpress/icons": "*",
+		"@wordpress/is-shallow-equal": "*",
+		"@wordpress/keycodes": "*",
+		"@wordpress/primitives": "*",
+		"@wordpress/private-apis": "*",
+		"@wordpress/rich-text": "*",
+		"@wordpress/warning": "*",
 		"change-case": "^4.1.2",
 		"clsx": "^2.1.1",
 		"colord": "^2.7.0",
@@ -84,5 +84,6 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "2e5495c635910cb34bfaca3c6258d2e989f66214"
+	"wpScript": true,
+	"gitHead": "dcf4613b33b0eda14e203ac30f700ed0db70347f"
 }

package/schemas/docs-manifest.json

@@ -0,0 +1,38 @@
+{
+	"title": "JSON schema for @wordpress/components README manifests",
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"type": "object",
+	"properties": {
+		"displayName": {
+			"type": "string",
+			"description": "The `displayName` of the component, as determined in code. Used to identify the component in the specified source file."
+		},
+		"filePath": {
+			"type": "string",
+			"description": "The file path where the component is located."
+		},
+		"subcomponents": {
+			"type": "array",
+			"description": "List of subcomponents related to the component.",
+			"items": {
+				"type": "object",
+				"properties": {
+					"displayName": {
+						"type": "string",
+						"description": "The `displayName` of the subcomponent, as determined in code. Used to identify the component in the specified source file."
+					},
+					"preferredDisplayName": {
+						"type": "string",
+						"description": "The display name to use in the README, if it is different from the `displayName` as determined in code."
+					},
+					"filePath": {
+						"type": "string",
+						"description": "The file path where the subcomponent is located."
+					}
+				},
+				"required": [ "displayName", "filePath" ]
+			}
+		}
+	},
+	"required": [ "displayName", "filePath" ]
+}

package/src/alignment-matrix-control/README.md

@@ -1,12 +1,14 @@
 # AlignmentMatrixControl
 
-AlignmentMatrixControl components enable adjustments to horizontal and vertical alignments for UI.
+<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->
+
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-alignmentmatrixcontrol--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
 
-## Usage
+AlignmentMatrixControl components enable adjustments to horizontal and vertical alignments for UI.
 
 ```jsx
-import { useState } from 'react';
 import { AlignmentMatrixControl } from '@wordpress/components';
+import { useState } from '@wordpress/element';
 
 const Example = () => {
 	const [ alignment, setAlignment ] = useState( 'center center' );
@@ -14,63 +16,70 @@ const Example = () => {
 	return (
 		<AlignmentMatrixControl
 			value={ alignment }
-			onChange={ ( newAlignment ) => setAlignment( newAlignment ) }
+			onChange={ setAlignment }
 		/>
 	);
 };
 ```
-
 ## Props
 
-The component accepts the following props:
+### `defaultValue`
 
-### className
+If provided, sets the default alignment value.
 
-The class that will be added to the classes of the underlying `grid` widget.
--   Type: `string`
--   Required: No
+ - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
+ - Required: No
+ - Default: `'center center'`
 
-### id
+### `label`
 
-Unique ID for the component.
+Accessible label. If provided, sets the `aria-label` attribute of the
+underlying `grid` widget.
 
--  Type: `string`
--  Required: No
+ - Type: `string`
+ - Required: No
+ - Default: `'Alignment Matrix Control'`
 
-### label
+### `onChange`
 
-Accessible label. If provided, sets the `aria-label` attribute of the underlying `grid` widget.
+A function that receives the updated alignment value.
 
--   Type: `string`
--   Required: No
--   Default: `Alignment Matrix Control`
+ - Type: `(newValue: AlignmentMatrixControlValue) => void`
+ - Required: No
 
-### defaultValue
+### `value`
 
-If provided, sets the default alignment value.
+The current alignment value.
 
-- Type: `AlignmentMatrixControlValue`
-- Required: No
-- Default: `center center`
+ - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
+ - Required: No
 
-### value
+### `width`
 
-The current alignment value.
+If provided, sets the width of the control.
 
-- Type: `AlignmentMatrixControlValue`
-- Required: No
+ - Type: `number`
+ - Required: No
+ - Default: `92`
 
-### onChange
+## Subcomponents
 
-A function that receives the updated alignment value.
+### AlignmentMatrixControl.Icon
 
--   Type: `( newValue: AlignmentMatrixControlValue ) => void`
--   Required: No
+#### Props
 
-### width
+##### `disablePointerEvents`
 
-If provided, sets the width of the control.
+If `true`, disables pointer events on the icon.
 
- - Type: `number`
+ - Type: `boolean`
  - Required: No
- - Default: `92`
+ - Default: `true`
+
+##### `value`
+
+The current alignment value.
+
+ - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
+ - Required: No
+ - Default: `center`

package/src/alignment-matrix-control/docs-manifest.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "../../schemas/docs-manifest.json",
+	"displayName": "AlignmentMatrixControl",
+	"filePath": "./index.tsx",
+	"subcomponents": [
+		{
+			"displayName": "AlignmentMatrixControlIcon",
+			"preferredDisplayName": "AlignmentMatrixControl.Icon",
+			"filePath": "./icon.tsx"
+		}
+	]
+}

package/src/alignment-matrix-control/types.ts

@@ -54,6 +54,8 @@ export type AlignmentMatrixControlIconProps = Pick<
 	 * component instead_
 	 *
 	 * The size of the icon.
+	 *
+	 * @deprecated
 	 * @ignore
 	 * @default 24
 	 */

package/src/angle-picker-control/README.md

@@ -1,44 +1,56 @@
 # AnglePickerControl
 
-`AnglePickerControl` is a React component to render a UI that allows users to pick an angle.
-Users can choose an angle in a visual UI with the mouse by dragging an angle indicator inside a circle or by directly inserting the desired angle in a text field.
+<!-- 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-anglepickercontrol--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
+
+`AnglePickerControl` is a React component to render a UI that allows users to
+pick an angle. Users can choose an angle in a visual UI with the mouse by
+dragging an angle indicator inside a circle or by directly inserting the
+desired angle in a text field.
 
 ```jsx
-import { useState } from 'react';
+import { useState } from '@wordpress/element';
 import { AnglePickerControl } from '@wordpress/components';
 
 function Example() {
-	const [ angle, setAngle ] = useState( 0 );
-	return (
-		<AnglePickerControl
-			value={ angle }
-			onChange={ setAngle }
-		/>
-	);
-};
+  const [ angle, setAngle ] = useState( 0 );
+  return (
+    <AnglePickerControl
+      value={ angle }
+      onChange={ setAngle }
+    </>
+  );
+}
 ```
-
 ## Props
 
-The component accepts the following props.
+### `as`
+
+The HTML element or React component to render the component as.
 
-### `label`: `string`
+ - Type: `"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | ...`
+ - Required: No
+
+### `label`
 
 Label to use for the angle picker.
 
--   Required: No
--   Default: `__( 'Angle' )`
+ - Type: `string`
+ - Required: No
+ - Default: `__( 'Angle' )`
 
-### `value`: `number | string`
+### `onChange`
 
-The current value of the input. The value represents an angle in degrees and should be a value between 0 and 360.
+A function that receives the new value of the input.
 
--   Required: Yes
+ - Type: `(value: number) => void`
+ - Required: Yes
 
-### `onChange`: `( value: number ) => void`
+### `value`
 
-A function that receives the new value of the input.
+The current value of the input. The value represents an angle in degrees
+and should be a value between 0 and 360.
 
--   Required: Yes
+ - Type: `string | number`
+ - Required: Yes

package/src/angle-picker-control/docs-manifest.json

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

package/src/animate/stories/index.story.tsx

@@ -10,7 +10,8 @@ import { Animate } from '..';
 import Notice from '../../notice';
 
 const meta: Meta< typeof Animate > = {
-	title: 'Components/Animate',
+	title: 'Components/Utilities/Animate',
+	id: 'components-animate',
 	component: Animate,
 	parameters: {
 		controls: { expanded: true },

package/src/autocomplete/autocompleter-ui.native.js

@@ -69,9 +69,8 @@ export function getAutoCompleterUI( autocompleter ) {
 			} else if ( isVisible && text.length === 0 ) {
 				startAnimation( false );
 			}
-			// Temporarily disabling exhaustive-deps to avoid introducing unexpected side effecst.
+			// We want to avoid introducing unexpected side effects.
 			// See https://github.com/WordPress/gutenberg/pull/41820
-			// eslint-disable-next-line react-hooks/exhaustive-deps
 		}, [ items, isVisible, text ] );
 
 		const activeItemStyles = usePreferredColorSchemeStyle(
@@ -112,9 +111,8 @@ export function getAutoCompleterUI( autocompleter ) {
 					}
 				} );
 			},
-			// Temporarily disabling exhaustive-deps to avoid introducing unexpected side effecst.
+			// We want to avoid introducing unexpected side effects.
 			// See https://github.com/WordPress/gutenberg/pull/41820
-			// eslint-disable-next-line react-hooks/exhaustive-deps
 			[ isVisible ]
 		);
 

package/src/autocomplete/autocompleter-ui.tsx

@@ -165,9 +165,8 @@ export function getAutoCompleterUI( autocompleter: WPCompleter ) {
 		useLayoutEffect( () => {
 			onChangeOptions( items );
 			announce( items );
-			// Temporarily disabling exhaustive-deps to avoid introducing unexpected side effecst.
+			// We want to avoid introducing unexpected side effects.
 			// See https://github.com/WordPress/gutenberg/pull/41820
-			// eslint-disable-next-line react-hooks/exhaustive-deps
 		}, [ items ] );
 
 		if ( items.length === 0 ) {
@@ -235,8 +234,5 @@ function useOnClickOutside(
 			document.removeEventListener( 'mousedown', listener );
 			document.removeEventListener( 'touchstart', listener );
 		};
-		// Disable reason: `ref` is a ref object and should not be included in a
-		// hook's dependency list.
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [ handler ] );
+	}, [ handler, ref ] );
 }

package/src/autocomplete/index.tsx

@@ -97,7 +97,7 @@ export function useAutocomplete( {
 		( ( props: AutocompleterUIProps ) => JSX.Element | null ) | null
 	>( null );
 
-	const backspacing = useRef( false );
+	const backspacingRef = useRef( false );
 
 	function insertCompletion( replacement: React.ReactNode ) {
 		if ( autocompleter === null ) {
@@ -177,7 +177,7 @@ export function useAutocomplete( {
 	}
 
 	function handleKeyDown( event: KeyboardEvent ) {
-		backspacing.current = event.key === 'Backspace';
+		backspacingRef.current = event.key === 'Backspace';
 
 		if ( ! autocompleter ) {
 			return;
@@ -323,7 +323,7 @@ export function useAutocomplete( {
 		// Ex: "Some text @marcelo sekkkk" <--- "kkkk" caused a mismatch, but
 		// if the user presses backspace here, it will show the completion popup again.
 		const matchingWhileBackspacing =
-			backspacing.current && wordsFromTrigger.length <= 3;
+			backspacingRef.current && wordsFromTrigger.length <= 3;
 
 		if ( mismatch && ! ( matchingWhileBackspacing || hasOneTriggerWord ) ) {
 			if ( autocompleter ) {
@@ -380,9 +380,8 @@ export function useAutocomplete( {
 				: AutocompleterUI
 		);
 		setFilterValue( query === null ? '' : query );
-		// Temporarily disabling exhaustive-deps to avoid introducing unexpected side effecst.
+		// We want to avoid introducing unexpected side effects.
 		// See https://github.com/WordPress/gutenberg/pull/41820
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ textContent ] );
 
 	const { key: selectedKey = '' } = filteredOptions[ selectedIndex ] || {};