Convert the Snackbar component to TypeScript

packages/components/CHANGELOG.md

@@ -56,6 +56,7 @@
 -   `Autocomplete`: use Popover's new `placement` prop instead of legacy `position` prop ([#44396](https://github.com/WordPress/gutenberg/pull/44396/)).
 -   `SelectControl`: Add `onChange`, `onBlur` and `onFocus` to storybook actions ([#45432](https://github.com/WordPress/gutenberg/pull/45432/)).
 -   `FontSizePicker`: Add more comprehensive tests ([#45298](https://github.com/WordPress/gutenberg/pull/45298)).
+-   `Snackbar`: Convert to TypeScript ([#45472](https://github.com/WordPress/gutenberg/pull/45472)).
 
 ## 21.3.0 (2022-10-19)
 

packages/components/src/snackbar/README.md

@@ -36,17 +36,54 @@ const MySnackbarNotice = () => (
 );
 ```
 
-#### Props
+### Props
 
 The following props are used to control the display of the component.
 
--   `children`: (string) The displayed message of a notice. Also used as the spoken message for assistive technology, unless `spokenMessage` is provided as an alternative message.
--   `spokenMessage`: (string) Used to provide a custom spoken message in place of the `children` default.
--   `politeness`: (string) A politeness level for the notice's spoken message. Should be provided as one of the valid options for [an `aria-live` attribute value](https://www.w3.org/TR/wai-aria-1.1/#aria-live). Defaults to `"polite"`. Note that this value should be considered a suggestion; assistive technologies may override it based on internal heuristics.
-    -   A value of `'assertive'` is to be used for important, and usually time-sensitive, information. It will interrupt anything else the screen reader is announcing in that moment.
-    -   A value of `'polite'` is to be used for advisory information. It should not interrupt what the screen reader is announcing in that moment (the "speech queue") or interrupt the current task.
--   `onRemove`: function called when dismissing the notice.
--   `actions`: (array) an array of action objects. Each member object should contain a `label` and either a `url` link string or `onClick` callback function.
+#### `children`: `ReactNode`
+The displayed message of a notice. Also used as the spoken message for assistive technology, unless `spokenMessage` is provided as an alternative message.
+-   Required: Yes
+
+#### `spokenMessage`: `ReactNode`
+Used to provide a custom spoken message in place of the `children` default.
+-   Required: No
+-   Default: `children`
+
+#### `politeness`: `'polite' | 'assertive'`
+A politeness level for the notice's spoken message. Should be provided as one of the valid options for [an `aria-live` attribute value](https://www.w3.org/TR/wai-aria-1.1/#aria-live). Defaults to `"polite"`. Note that this value should be considered a suggestion; assistive technologies may override it based on internal heuristics.
+-   A value of `'assertive'` is to be used for important, and usually time-sensitive, information. It will interrupt anything else the screen reader is announcing in that moment.
+-   A value of `'polite'` is to be used for advisory information. It should not interrupt what the screen reader is announcing in that moment (the "speech queue") or interrupt the current task.
+-   Required: No
+-   Default: `'polite'`
+
+#### `actions`: `Action[]`
+An array of action objects. Each member object should contain a `label` and either a `url` link string or `onClick` callback function.
+-   Required: No
+-   Default: `[]`
+
+#### `onRemove`: `Function`
+Function called when dismissing the notice.
+-   Required: No
+-   Default: `() => void`
+
+#### `icon`: `WPElement | null`
+The icon to render in the snackbar.
+-   Required: No
+-   Default: `null`
+
+#### `explicitDismiss`: `boolean`
+Whether to require user action to dismiss the snackbar. By default, this is dismissed on a timeout, without user interaction.
+-   Required: No
+-   Default: `false`
+
+#### `onDismiss`: `Function`
+A callback executed when the snackbar is dismissed. It is distinct from onRemove, which _looks_ like a callback but is actually the function to call to remove the snackbar from the UI.
+-   Required: No
+-   Default: `() => void`
+
+#### `listRef`: `MutableRefObject< HTMLDivElement >`
+A ref to the list that contains the snackbar.
+-   Required: No
 
 ## Related components
 

packages/components/src/snackbar/index.js → packages/components/src/snackbar/index.tsx

@@ -1,6 +1,7 @@
 /**
  * External dependencies
  */
+import type { ForwardedRef, KeyboardEvent, MouseEvent, ReactNode } from 'react';
 import classnames from 'classnames';
 
 /**
@@ -14,21 +15,21 @@ import warning from '@wordpress/warning';
 /**
  * Internal dependencies
  */
-import { Button } from '../';
+import Button from '../button';
+import type { Action, ButtonEvent, SnackbarProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
 const noop = () => {};
 const NOTICE_TIMEOUT = 10000;
 
-/** @typedef {import('@wordpress/element').WPElement} WPElement */
-
 /**
  * Custom hook which announces the message with the given politeness, if a
  * valid message is provided.
- *
- * @param {string|WPElement}     [message]  Message to announce.
- * @param {'polite'|'assertive'} politeness Politeness to announce.
  */
-function useSpokenMessage( message, politeness ) {
+function useSpokenMessage(
+	message: ReactNode,
+	politeness: 'polite' | 'assertive'
+) {
 	const spokenMessage =
 		typeof message === 'string' ? message : renderToString( message );
 
@@ -39,7 +40,7 @@ function useSpokenMessage( message, politeness ) {
 	}, [ spokenMessage, politeness ] );
 }
 
-function Snackbar(
+function UnforwardedSnackbar(
 	{
 		className,
 		children,
@@ -54,24 +55,28 @@ function Snackbar(
 		// actually the function to call to remove the snackbar from the UI.
 		onDismiss = noop,
 		listRef,
-	},
-	ref
+	}: WordPressComponentProps< SnackbarProps, 'div' >,
+	ref: ForwardedRef< any >
 ) {
 	onDismiss = onDismiss || noop;
 
-	function dismissMe( event ) {
+	function dismissMe(
+		event:
+			| KeyboardEvent< HTMLDivElement | HTMLSpanElement >
+			| MouseEvent< HTMLDivElement | HTMLSpanElement >
+	) {
 		if ( event && event.preventDefault ) {
 			event.preventDefault();
 		}
 
 		// Prevent focus loss by moving it to the list element.
-		listRef.current.focus();
+		listRef?.current.focus();
 
 		onDismiss();
 		onRemove();
 	}
 
-	function onActionClick( event, onClick ) {
+	function onActionClick( event: ButtonEvent, onClick: Action[ 'onClick' ] ) {
 		event.stopPropagation();
 
 		onRemove();
@@ -119,7 +124,7 @@ function Snackbar(
 			ref={ ref }
 			className={ classes }
 			onClick={ ! explicitDismiss ? dismissMe : noop }
-			tabIndex="0"
+			tabIndex={ 0 }
 			role={ ! explicitDismiss ? 'button' : '' }
 			onKeyPress={ ! explicitDismiss ? dismissMe : noop }
 			aria-label={ ! explicitDismiss ? __( 'Dismiss this notice' ) : '' }
@@ -135,7 +140,7 @@ function Snackbar(
 							key={ index }
 							href={ url }
 							variant="tertiary"
-							onClick={ ( event ) =>
+							onClick={ ( event: ButtonEvent ) =>
 								onActionClick( event, onClick )
 							}
 							className="components-snackbar__action"
@@ -148,7 +153,7 @@ function Snackbar(
 					<span
 						role="button"
 						aria-label="Dismiss this notice"
-						tabIndex="0"
+						tabIndex={ 0 }
 						className="components-snackbar__dismiss-button"
 						onClick={ dismissMe }
 						onKeyPress={ dismissMe }
@@ -161,4 +166,18 @@ function Snackbar(
 	);
 }
 
-export default forwardRef( Snackbar );
+/**
+ * A Snackbar displays a succinct message that is cleared out after a small delay.
+ *
+ * It can also offer the user options, like viewing a published post.
+ * But these options should also be available elsewhere in the UI.
+ *
+ * ```jsx
+ * const MySnackbarNotice = () => (
+ *   <Snackbar>Post published successfully.</Snackbar>
+ * );
+ * ```
+ */
+export const Snackbar = forwardRef( UnforwardedSnackbar );
+
+export default Snackbar;

packages/components/src/snackbar/list.js → packages/components/src/snackbar/list.tsx

@@ -1,6 +1,7 @@
 /**
  * External dependencies
  */
+import type { MutableRefObject } from 'react';
 import classnames from 'classnames';
 
 /**
@@ -12,11 +13,13 @@ import { useRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Snackbar from './';
+import Snackbar from '.';
 import {
 	__unstableMotion as motion,
 	__unstableAnimatePresence as AnimatePresence,
 } from '../animation';
+import type { Notice, SnackbarListProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
 const noop = () => {};
 const SNACKBAR_VARIANTS = {
@@ -40,27 +43,33 @@ const SNACKBAR_VARIANTS = {
 };
 
 const SNACKBAR_REDUCE_MOTION_VARIANTS = {
-	init: false,
-	open: false,
-	exit: false,
+	init: {},
+	open: {},
+	exit: {},
 };
 
 /**
  * Renders a list of notices.
  *
- * @param {Object}   $0           Props passed to the component.
- * @param {Array}    $0.notices   Array of notices to render.
- * @param {Function} $0.onRemove  Function called when a notice should be removed / dismissed.
- * @param {Object}   $0.className Name of the class used by the component.
- * @param {Object}   $0.children  Array of children to be rendered inside the notice list.
- *
- * @return {Object} The rendered notices list.
+ * ```jsx
+ * const MySnackbarListNotice = () => (
+ *   <SnackbarList
+ *     notices={ notices }
+ *     onRemove={ removeNotice }
+ *   />
+ * );
+ * ```
  */
-function SnackbarList( { notices, className, children, onRemove = noop } ) {
-	const listRef = useRef();
+export function SnackbarList( {
+	notices,
+	className,
+	children,
+	onRemove = noop,
+}: WordPressComponentProps< SnackbarListProps, 'div' > ) {
+	const listRef = useRef() as MutableRefObject< HTMLDivElement >;
 	const isReducedMotion = useReducedMotion();
 	className = classnames( 'components-snackbar-list', className );
-	const removeNotice = ( notice ) => () => onRemove( notice.id );
+	const removeNotice = ( notice: Notice ) => () => onRemove( notice.id );
 	return (
 		<div className={ className } tabIndex={ -1 } ref={ listRef }>
 			{ children }