@wordpress/components 28.5.0 → 28.6.0

package/src/dimension-control/stories/index.story.tsx

@@ -44,6 +44,7 @@ const Template: StoryFn< typeof DimensionControl > = ( args ) => (
 export const Default = Template.bind( {} );
 
 Default.args = {
+	__nextHasNoMarginBottom: true,
 	label: 'Please select a size',
 	sizes,
 };

package/src/dimension-control/test/__snapshots__/index.test.js.snap

@@ -13,10 +13,6 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
   box-sizing: inherit;
 }
 
-.emotion-2 {
-  margin-bottom: calc(4px * 2);
-}
-
 .components-panel__row .emotion-2 {
   margin-bottom: inherit;
 }
@@ -299,10 +295,6 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
   box-sizing: inherit;
 }
 
-.emotion-2 {
-  margin-bottom: calc(4px * 2);
-}
-
 .components-panel__row .emotion-2 {
   margin-bottom: inherit;
 }
@@ -595,10 +587,6 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
   box-sizing: inherit;
 }
 
-.emotion-2 {
-  margin-bottom: calc(4px * 2);
-}
-
 .components-panel__row .emotion-2 {
   margin-bottom: inherit;
 }
@@ -903,10 +891,6 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
   box-sizing: inherit;
 }
 
-.emotion-2 {
-  margin-bottom: calc(4px * 2);
-}
-
 .components-panel__row .emotion-2 {
   margin-bottom: inherit;
 }

package/src/dimension-control/test/index.test.js

@@ -12,7 +12,11 @@ import { plus } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
-import { DimensionControl } from '../';
+import { DimensionControl as _DimensionControl } from '../';
+
+const DimensionControl = ( props ) => {
+	return <_DimensionControl { ...props } __nextHasNoMarginBottom />;
+};
 
 describe( 'DimensionControl', () => {
 	const onChangeHandler = jest.fn();

package/src/dimension-control/types.ts

@@ -2,6 +2,7 @@
  * Internal dependencies
  */
 import type { IconType } from '../icon';
+import type { SelectControlProps } from '../select-control/types';
 
 export type Size = {
 	/**
@@ -14,7 +15,10 @@ export type Size = {
 	slug: string;
 };
 
-export type DimensionControlProps = {
+export type DimensionControlProps = Pick<
+	SelectControlProps,
+	'__next40pxDefaultSize' | '__nextHasNoMarginBottom'
+> & {
 	/**
 	 * Label for the control.
 	 */
@@ -45,10 +49,4 @@ export type DimensionControlProps = {
 	 * @default ''
 	 */
 	className?: string;
-	/**
-	 * Start opting into the larger default height that will become the default size in a future version.
-	 *
-	 * @default false
-	 */
-	__next40pxDefaultSize?: boolean;
 };

package/src/drop-zone/style.scss

@@ -7,7 +7,7 @@
 	z-index: z-index(".components-drop-zone");
 	visibility: hidden;
 	opacity: 0;
-	border-radius: $radius-block-ui;
+	border-radius: $radius-small;
 
 	&.is-active {
 		opacity: 1;

package/src/dropdown-menu-v2/index.tsx

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import * as Ariakit from '@ariakit/react';
+import { useStoreState } from '@ariakit/react';
 
 /**
  * WordPress dependencies
@@ -248,9 +249,10 @@ const UnconnectedDropdownMenu = (
 	);
 
 	// Extract the side from the applied placement — useful for animations.
-	const appliedPlacementSide = dropdownMenuStore
-		.useState( 'placement' )
-		.split( '-' )[ 0 ];
+	const appliedPlacementSide = useStoreState(
+		dropdownMenuStore,
+		'placement'
+	).split( '-' )[ 0 ];
 
 	if (
 		dropdownMenuStore.parent &&

package/src/dropdown-menu-v2/styles.ts

@@ -25,13 +25,15 @@ const ITEM_PADDING_BLOCK = space( 2 );
 const ITEM_PADDING_INLINE = space( 3 );
 
 // TODO:
-// - those values are different from saved variables?
-// - should bring this into the config, and make themeable
-// - border color and divider color are different?
-const DEFAULT_BORDER_COLOR = COLORS.gray[ 300 ];
-const DIVIDER_COLOR = COLORS.gray[ 200 ];
-const TOOLBAR_VARIANT_BORDER_COLOR = COLORS.gray[ '900' ];
-const DEFAULT_BOX_SHADOW = `0 0 0 ${ CONFIG.borderWidth } ${ DEFAULT_BORDER_COLOR }, ${ CONFIG.popoverShadow }`;
+// - border color and divider color are different from COLORS.theme variables
+// - lighter text color is not defined in COLORS.theme, should it be?
+// - lighter background color is not defined in COLORS.theme, should it be?
+const DEFAULT_BORDER_COLOR = COLORS.theme.gray[ 300 ];
+const DIVIDER_COLOR = COLORS.theme.gray[ 200 ];
+const LIGHTER_TEXT_COLOR = COLORS.theme.gray[ 700 ];
+const LIGHT_BACKGROUND_COLOR = COLORS.theme.gray[ 100 ];
+const TOOLBAR_VARIANT_BORDER_COLOR = COLORS.theme.foreground;
+const DEFAULT_BOX_SHADOW = `0 0 0 ${ CONFIG.borderWidth } ${ DEFAULT_BORDER_COLOR }, ${ CONFIG.elevationXSmall }`;
 const TOOLBAR_VARIANT_BOX_SHADOW = `0 0 0 ${ CONFIG.borderWidth } ${ TOOLBAR_VARIANT_BORDER_COLOR }`;
 
 const GRID_TEMPLATE_COLS = 'minmax( 0, max-content ) 1fr';
@@ -87,7 +89,7 @@ export const DropdownMenu = styled( Ariakit.Menu )<
 	padding: ${ CONTENT_WRAPPER_PADDING };
 
 	background-color: ${ COLORS.ui.background };
-	border-radius: 4px;
+	border-radius: ${ CONFIG.radiusMedium };
 	${ ( props ) => css`
 		box-shadow: ${ props.variant === 'toolbar'
 			? TOOLBAR_VARIANT_BOX_SHADOW
@@ -149,8 +151,8 @@ const baseItem = css`
 	font-weight: normal;
 	line-height: 20px;
 
-	color: ${ COLORS.gray[ 900 ] };
-	border-radius: ${ CONFIG.radiusBlockUi };
+	color: ${ COLORS.theme.foreground };
+	border-radius: ${ CONFIG.radiusSmall };
 
 	padding-block: ${ ITEM_PADDING_BLOCK };
 	padding-inline: ${ ITEM_PADDING_INLINE };
@@ -193,8 +195,8 @@ const baseItem = css`
 
 	/* When the item is the trigger of an open submenu */
 	${ DropdownMenu }:not(:focus) &:not(:focus)[aria-expanded="true"] {
-		background-color: ${ COLORS.gray[ 100 ] };
-		color: ${ COLORS.gray[ 900 ] };
+		background-color: ${ LIGHT_BACKGROUND_COLOR };
+		color: ${ COLORS.theme.foreground };
 	}
 
 	svg {
@@ -238,7 +240,7 @@ export const ItemPrefixWrapper = styled.span`
 	align-items: center;
 	justify-content: center;
 
-	color: ${ COLORS.gray[ '700' ] };
+	color: ${ LIGHTER_TEXT_COLOR };
 
 	/*
 	* When the parent menu item is active, except when it's a non-focused/hovered
@@ -284,7 +286,7 @@ export const ItemSuffixWrapper = styled.span`
 	justify-content: center;
 	gap: ${ space( 3 ) };
 
-	color: ${ COLORS.gray[ '700' ] };
+	color: ${ LIGHTER_TEXT_COLOR };
 
 	/*
 	 * When the parent menu item is active, except when it's a non-focused/hovered
@@ -343,7 +345,7 @@ export const DropdownMenuItemLabel = styled( Truncate )`
 export const DropdownMenuItemHelpText = styled( Truncate )`
 	font-size: ${ font( 'helpText.fontSize' ) };
 	line-height: 16px;
-	color: ${ COLORS.gray[ '700' ] };
+	color: ${ LIGHTER_TEXT_COLOR };
 	word-break: break-all;
 
 	[data-active-item]:not( [data-focus-visible] ) *:not( ${ DropdownMenu } ) &,

package/src/focal-point-picker/README.md

@@ -100,10 +100,18 @@ Callback which is called at the start of drag operations.
 
 Function which is called before internal updates to the value state. It receives the upcoming value and may return a modified one.
 
-#### __nextHasNoMarginBottom
+### `__next40pxDefaultSize`
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`
 
 Start opting into the new margin-free styles that will become the default 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.

package/src/focal-point-picker/controls.tsx

@@ -23,7 +23,6 @@ const noop = () => {};
 
 export default function FocalPointPickerControls( {
 	__nextHasNoMarginBottom,
-	__next40pxDefaultSize,
 	hasHelpText,
 	onChange = noop,
 	point = {
@@ -57,7 +56,6 @@ export default function FocalPointPickerControls( {
 			gap={ 4 }
 		>
 			<FocalPointUnitControl
-				__next40pxDefaultSize={ __next40pxDefaultSize }
 				label={ __( 'Left' ) }
 				aria-label={ __( 'Focal point left position' ) }
 				value={ [ valueX, '%' ].join( '' ) }
@@ -71,7 +69,6 @@ export default function FocalPointPickerControls( {
 				dragDirection="e"
 			/>
 			<FocalPointUnitControl
-				__next40pxDefaultSize={ __next40pxDefaultSize }
 				label={ __( 'Top' ) }
 				aria-label={ __( 'Focal point top position' ) }
 				value={ [ valueY, '%' ].join( '' ) }
@@ -91,6 +88,7 @@ export default function FocalPointPickerControls( {
 function FocalPointUnitControl( props: UnitControlProps ) {
 	return (
 		<StyledUnitControl
+			__next40pxDefaultSize
 			className="focal-point-picker__controls-position-unit-control"
 			labelPosition="top"
 			max={ TEXTCONTROL_MAX }

package/src/focal-point-picker/index.tsx

@@ -85,7 +85,6 @@ const GRID_OVERLAY_TIMEOUT = 600;
  */
 export function FocalPointPicker( {
 	__nextHasNoMarginBottom,
-	__next40pxDefaultSize = false,
 	autoPlay = true,
 	className,
 	help,
@@ -251,6 +250,7 @@ export function FocalPointPicker( {
 		<BaseControl
 			{ ...restProps }
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			__associatedWPComponentName="FocalPointPicker"
 			label={ label }
 			id={ id }
 			help={ help }
@@ -285,7 +285,6 @@ export function FocalPointPicker( {
 			</MediaWrapper>
 			<Controls
 				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
-				__next40pxDefaultSize={ __next40pxDefaultSize }
 				hasHelpText={ !! help }
 				point={ { x, y } }
 				onChange={ ( value ) => {

package/src/focal-point-picker/stories/index.story.tsx

@@ -49,6 +49,9 @@ const Template: StoryFn< typeof FocalPointPicker > = ( {
 };
 
 export const Default = Template.bind( {} );
+Default.args = {
+	__nextHasNoMarginBottom: true,
+};
 
 export const Image = Template.bind( {} );
 Image.args = {

package/src/focal-point-picker/styles/focal-point-picker-style.ts

@@ -22,7 +22,7 @@ export const MediaWrapper = styled.div`
 
 export const MediaContainer = styled.div`
 	align-items: center;
-	border-radius: ${ CONFIG.radiusBlockUi };
+	border-radius: ${ CONFIG.radiusSmall };
 	cursor: pointer;
 	display: inline-flex;
 	justify-content: center;

package/src/focal-point-picker/test/index.tsx

@@ -7,12 +7,16 @@ import userEvent from '@testing-library/user-event';
 /**
  * Internal dependencies
  */
-import Picker from '..';
+import _Picker from '..';
 import type { FocalPointPickerProps } from '../types';
 
 type Log = { name: string; args: unknown[] };
 type EventLogger = ( name: string, args: unknown[] ) => void;
 
+const Picker = ( props: React.ComponentProps< typeof _Picker > ) => {
+	return <_Picker { ...props } __nextHasNoMarginBottom />;
+};
+
 const props: FocalPointPickerProps = {
 	onChange: jest.fn(),
 	url: 'test-url',

package/src/focal-point-picker/types.ts

@@ -29,7 +29,8 @@ export type FocalPointPickerProps = Pick<
 	/**
 	 * Start opting into the larger default height that will become the default size in a future version.
 	 *
-	 * @default false
+	 * @deprecated Default behavior since WP 6.7. Prop can be safely removed.
+	 * @ignore
 	 */
 	__next40pxDefaultSize?: boolean;
 	/**
@@ -68,7 +69,6 @@ export type FocalPointPickerProps = Pick<
 
 export type FocalPointPickerControlsProps = {
 	__nextHasNoMarginBottom?: boolean;
-	__next40pxDefaultSize?: boolean;
 	/**
 	 * A bit of extra bottom margin will be added if a `help` text
 	 * needs to be rendered under it.

package/src/font-size-picker/README.md

@@ -113,3 +113,10 @@ If `true`, a slider will be displayed alongside the input field when a custom fo
 
 -   Required: no
 -   Default: `false`
+
+### `__next40pxDefaultSize`: `boolean`
+
+Start opting into the larger default height that will become the default size in a future version.
+
+- Required: No
+- Default: `false`

package/src/form-file-upload/README.md

@@ -85,3 +85,11 @@ Optional callback function used to render the UI. If passed, the component does
 
 -   Type: `Function`
 -   Required: No
+
+### __next40pxDefaultSize
+
+Start opting into the larger default height that will become the default size in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`

package/src/form-file-upload/types.ts

@@ -10,6 +10,12 @@ import type Icon from '../icon';
 
 // TODO: Replace `children` and `icon` types with props from Button once Button is typed.
 export type FormFileUploadProps = {
+	/**
+	 * Start opting into the larger default height that will become the default size in a future version.
+	 *
+	 * @default false
+	 */
+	__next40pxDefaultSize?: boolean;
 	/**
 	 * A string passed to `input` element that tells the browser which file types can be
 	 * upload to the upload by the user use. e.g: `image/*,video/*`.

package/src/form-token-field/README.md

@@ -61,6 +61,7 @@ The `value` property is handled in a manner similar to controlled form component
 -   `__experimentalShowHowTo` - If false, the text on how to use the select (ie: _Separate with commas or the Enter key._) will be hidden.
 -   `__experimentalValidateInput` - If passed, all introduced values will be validated before being added as tokens.
 -   `__experimentalAutoSelectFirstMatch` - If true, the select the first matching suggestion when the user presses the Enter key (or space when tokenizeOnSpace is true).
+-   `__next40pxDefaultSize` - Start opting into the larger default height that will become the default size in a future version.
 -   `__nextHasNoMarginBottom` - Start opting into the new margin-free styles that will become the default in a future version, currently scheduled to be WordPress 7.0. (The prop can be safely removed once this happens.)
 -   `tokenizeOnBlur` - If true, add any incompleteTokenValue as a new token when the field loses focus.
 

package/src/guide/style.scss

@@ -9,7 +9,6 @@
 	.components-modal__content {
 		padding: 0;
 		margin-top: 0;
-		border-radius: $radius-block-ui;
 
 		&::before {
 			content: none;

package/src/index.ts

@@ -61,7 +61,7 @@ export {
 	CompositeGroup as __unstableCompositeGroup,
 	CompositeItem as __unstableCompositeItem,
 	useCompositeState as __unstableUseCompositeState,
-} from './composite';
+} from './composite/legacy';
 export { ConfirmDialog as __experimentalConfirmDialog } from './confirm-dialog';
 export { default as CustomSelectControl } from './custom-select-control';
 export { default as Dashicon } from './dashicon';

package/src/input-control/README.md

@@ -107,3 +107,11 @@ The current value of the input.
 
 -   Type: `String`
 -   Required: No
+
+### __next40pxDefaultSize
+
+Start opting into the larger default height that will become the default size in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`

package/src/item-group/styles.ts

@@ -70,7 +70,7 @@ export const separated = css`
 	}
 `;
 
-const borderRadius = CONFIG.controlBorderRadius;
+const borderRadius = CONFIG.radiusSmall;
 
 export const spacedAround = css`
 	border-radius: ${ borderRadius };

package/src/mobile/utils/alignments.native.js

@@ -13,6 +13,7 @@ export const WIDE_ALIGNMENTS = {
 		'core/image',
 		'core/separator',
 		'core/media-text',
+		'core/quote',
 		'core/pullquote',
 	],
 };

package/src/modal/style.scss

@@ -20,8 +20,8 @@
 	margin: $grid-unit-50 0 0 0;
 	width: 100%;
 	background: $white;
-	box-shadow: $shadow-modal;
-	border-radius: $grid-unit-05 $grid-unit-05 0 0;
+	box-shadow: $elevation-large;
+	border-radius: $radius-large $radius-large 0 0;
 	overflow: hidden;
 	// Have the content element fill the vertical space yet not overflow.
 	display: flex;
@@ -32,7 +32,7 @@
 
 	// Show a centered modal on bigger screens.
 	@include break-small() {
-		border-radius: $grid-unit-05;
+		border-radius: $radius-large;
 		margin: auto;
 		width: auto;
 		min-width: $modal-min-width;

package/src/navigator/navigator-back-button/component.tsx

@@ -48,7 +48,7 @@ function UnconnectedNavigatorBackButton(
  *     <NavigatorScreen path="/child">
  *       <p>This is the child screen.</p>
  *       <NavigatorBackButton>
- *         Go back
+ *         Go back (to parent)
  *       </NavigatorBackButton>
  *     </NavigatorScreen>
  *   </NavigatorProvider>

package/src/navigator/navigator-back-button/hook.ts

@@ -10,31 +10,27 @@ import type { WordPressComponentProps } from '../../context';
 import { useContextSystem } from '../../context';
 import Button from '../../button';
 import useNavigator from '../use-navigator';
-import type { NavigatorBackButtonHookProps } from '../types';
+import type { NavigatorBackButtonProps } from '../types';
 
 export function useNavigatorBackButton(
-	props: WordPressComponentProps< NavigatorBackButtonHookProps, 'button' >
+	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >
 ) {
 	const {
 		onClick,
 		as = Button,
-		goToParent: goToParentProp = false,
+
 		...otherProps
 	} = useContextSystem( props, 'NavigatorBackButton' );
 
-	const { goBack, goToParent } = useNavigator();
+	const { goBack } = useNavigator();
 	const handleClick: React.MouseEventHandler< HTMLButtonElement > =
 		useCallback(
 			( e ) => {
 				e.preventDefault();
-				if ( goToParentProp ) {
-					goToParent();
-				} else {
-					goBack();
-				}
+				goBack();
 				onClick?.( e );
 			},
-			[ goToParentProp, goToParent, goBack, onClick ]
+			[ goBack, onClick ]
 		);
 
 	return {

package/src/navigator/navigator-provider/README.md

@@ -10,38 +10,42 @@ The `NavigatorProvider` component allows rendering nested views/panels/menus (vi
 
 ```jsx
 import {
-  __experimentalNavigatorProvider as NavigatorProvider,
-  __experimentalNavigatorScreen as NavigatorScreen,
-  __experimentalNavigatorButton as NavigatorButton,
-  __experimentalNavigatorToParentButton as NavigatorToParentButton,
+	__experimentalNavigatorProvider as NavigatorProvider,
+	__experimentalNavigatorScreen as NavigatorScreen,
+	__experimentalNavigatorButton as NavigatorButton,
+	__experimentalNavigatorBackButton as NavigatorBackButton,
 } from '@wordpress/components';
 
 const MyNavigation = () => (
-  <NavigatorProvider initialPath="/">
-    <NavigatorScreen path="/">
-      <p>This is the home screen.</p>
-       <NavigatorButton path="/child">
-         Navigate to child screen.
-      </NavigatorButton>
-    </NavigatorScreen>
-
-    <NavigatorScreen path="/child">
-      <p>This is the child screen.</p>
-      <NavigatorToParentButton>
-        Go back
-      </NavigatorToParentButton>
-    </NavigatorScreen>
-  </NavigatorProvider>
+	<NavigatorProvider initialPath="/">
+		<NavigatorScreen path="/">
+			<p>This is the home screen.</p>
+			<NavigatorButton path="/child">
+				Navigate to child screen.
+			</NavigatorButton>
+		</NavigatorScreen>
+
+		<NavigatorScreen path="/child">
+			<p>This is the child screen.</p>
+			<NavigatorBackButton>Go back</NavigatorBackButton>
+		</NavigatorScreen>
+	</NavigatorProvider>
 );
 ```
+
 **Important note**
 
-Parent/child navigation only works if the path you define are hierarchical, following a URL-like scheme where each path segment is separated by the `/` character.
+`Navigator` assumes that screens are organized hierarchically according to their `path`, which should follow a URL-like scheme where each path segment starts with and is separated by the `/` character.
+
+`Navigator` will treat "back" navigations as going to the parent screen — it is therefore responsibility of the consumer of the component to create the correct screen hierarchy.
+
 For example:
-- `/` is the root of all paths. There should always be a screen with `path="/"`.
-- `/parent/child` is a child of `/parent`.
-- `/parent/child/grand-child` is a child of `/parent/child`.
-- `/parent/:param` is a child of `/parent` as well.
+
+-   `/` is the root of all paths. There should always be a screen with `path="/"`.
+-   `/parent/child` is a child of `/parent`.
+-   `/parent/child/grand-child` is a child of `/parent/child`.
+-   `/parent/:param` is a child of `/parent` as well.
+-   if the current screen has a `path` with value `/parent/child/grand-child`, when going "back" `Navigator` will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) is found.
 
 ## Props
 
@@ -65,28 +69,26 @@ The `goTo` function allows navigating to a given path. The second argument can a
 
 The available options are:
 
-- `focusTargetSelector`: `string`. An optional property used to specify the CSS selector used to restore focus on the matching element when navigating back.
-- `isBack`: `boolean`. An optional property used to specify whether the navigation should be considered as backwards (thus enabling focus restoration when possible, and causing the animation to be backwards too)
-
-### `goToParent`: `() => void;`
+-   `focusTargetSelector`: `string`. An optional property used to specify the CSS selector used to restore focus on the matching element when navigating back;
+-   `isBack`: `boolean`. An optional property used to specify whether the navigation should be considered as backwards (thus enabling focus restoration when possible, and causing the animation to be backwards too);
+-   `skipFocus`: `boolean`. An optional property used to opt out of `Navigator`'s focus management, useful when the consumer of the component wants to manage focus themselves;
+-   `replace`: `boolean`. An optional property used to cause the new location to replace the current location in the stack.
 
-The `goToParent` function allows navigating to the parent screen.
+### `goBack`: `( path: string, options: NavigateOptions ) => void`
 
-Parent/child navigation only works if the path you define are hierarchical (see note above).
+The `goBack` function allows navigating to the parent screen. Parent/child navigation only works if the paths you define are hierarchical (see note above).
 
 When a match is not found, the function will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) are found.
 
-### `goBack`: `() => void`
-
-The `goBack` function allows navigating to the previous path.
+The available options are the same as for the `goTo` method, except for the `isBack` property, which is not available for the `goBack` method.
 
 ### `location`: `NavigatorLocation`
 
 The `location` object represent the current location, and has a few properties:
 
-- `path`: `string`. The path associated to the location.
-- `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards in the location stack.
-- `isInitial`: `boolean`. A flag that is `true` only for the first (root) location in the location stack.
+-   `path`: `string`. The path associated to the location.
+-   `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards in the location history.
+-   `isInitial`: `boolean`. A flag that is `true` only for the first (root) location in the location history.
 
 ### `params`: `Record< string, string | string[] >`