@wordpress/components 19.6.1 → 19.8.0

package/build-types/utils/colors-values.d.ts

@@ -141,8 +141,11 @@ export namespace UI {
     import textLight = BASE.black;
     export { textLight };
 }
-export namespace COLORS {
-    const darkGray_1: {
+export const COLORS: {
+    black: string;
+    white: string;
+} & {
+    darkGray: {
         900: string;
         800: string;
         700: string;
@@ -158,14 +161,42 @@ export namespace COLORS {
         primary: string;
         heading: string;
     };
-    export { darkGray_1 as darkGray };
-    export { DARK_OPACITY as darkOpacity };
-    export { DARK_OPACITY_LIGHT as darkOpacityLight };
-    import mediumGray_1 = G2.mediumGray;
-    export { mediumGray_1 as mediumGray };
-    import gray_1 = G2.gray;
-    export { gray_1 as gray };
-    const lightGray_1: {
+    darkOpacity: {
+        900: string;
+        800: string;
+        700: string;
+        600: string;
+        500: string;
+        400: string;
+        300: string;
+        200: string;
+        100: string;
+        backgroundFill: string;
+    };
+    darkOpacityLight: {
+        900: string;
+        800: string;
+        700: string;
+        600: string;
+        500: string;
+        400: string;
+        300: string;
+        200: string;
+        100: string;
+    };
+    mediumGray: {
+        text: string;
+    };
+    gray: {
+        900: string;
+        700: string;
+        600: string;
+        400: string;
+        300: string;
+        200: string;
+        100: string;
+    };
+    lightGray: {
         900: string;
         800: string;
         700: string;
@@ -181,9 +212,19 @@ export namespace COLORS {
         secondary: string;
         tertiary: string;
     };
-    export { lightGray_1 as lightGray };
-    export { LIGHT_OPACITY_LIGHT as lightGrayLight };
-    const blue_1: {
+    lightGrayLight: {
+        900: string;
+        800: string;
+        700: string;
+        600: string;
+        500: string;
+        400: string;
+        300: string;
+        200: string;
+        100: string;
+        backgroundFill: string;
+    };
+    blue: {
         wordpress: {
             700: string;
         };
@@ -209,10 +250,29 @@ export namespace COLORS {
             focusDark: string;
         };
     };
-    export { blue_1 as blue };
-    export { ALERT as alert };
-    export { ADMIN as admin };
-    export { UI as ui };
-}
+    alert: {
+        yellow: string;
+        red: string;
+        green: string;
+    };
+    admin: {
+        theme: string;
+        themeDark10: string;
+    };
+    ui: {
+        theme: string;
+        background: string;
+        backgroundDisabled: string;
+        border: string;
+        borderHover: string;
+        borderFocus: string;
+        borderDisabled: string;
+        borderLight: string;
+        label: string;
+        textDisabled: string;
+        textDark: string;
+        textLight: string;
+    };
+};
 export default COLORS;
 //# sourceMappingURL=colors-values.d.ts.map

package/build-types/utils/colors-values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"colors-values.d.ts","sourceRoot":"","sources":["../../src/utils/colors-values.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA;;;;;;;;;;;;EAYE;AAEF;;;;;;;;;;;EAWE;AAEF;;;;;;;;;;EAUE;AAEF;;;;;;;;;;;EAWE;AAEF;;;;;;;;;;;EAWE"}
+{"version":3,"file":"colors-values.d.ts","sourceRoot":"","sources":["../../src/utils/colors-values.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA;;;;;;;;;;;;EAYE;AAEF;;;;;;;;;;;EAWE;AAEF;;;;;;;;;;EAUE;AAEF;;;;;;;;;;;EAWE;AAEF;;;;;;;;;;;EAWE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYI"}

package/build-types/utils/config-values.d.ts

@@ -1,73 +1,73 @@
-declare namespace _default {
-    export const colorDivider: string;
-    export const colorScrollbarThumb: string;
-    export const colorScrollbarThumbHover: string;
-    export const colorScrollbarTrack: string;
-    export const elevationIntensity: number;
-    export const radiusBlockUi: string;
-    export const borderWidth: string;
-    export const borderWidthFocus: string;
-    export const borderWidthTab: string;
-    export const spinnerSize: number;
-    export const fontSize: string;
-    export const fontSizeH1: string;
-    export const fontSizeH2: string;
-    export const fontSizeH3: string;
-    export const fontSizeH4: string;
-    export const fontSizeH5: string;
-    export const fontSizeH6: string;
-    export const fontSizeInputMobile: string;
-    export const fontSizeMobile: string;
-    export const fontSizeSmall: string;
-    export const fontSizeXSmall: string;
-    export const fontLineHeightBase: string;
-    export const fontWeight: string;
-    export const fontWeightHeading: string;
-    export const gridBase: string;
-    export const cardBorderRadius: string;
-    export const cardPaddingXSmall: string;
-    export const cardPaddingSmall: string;
-    export const cardPaddingMedium: string;
-    export const cardPaddingLarge: string;
-    export const surfaceBackgroundColor: string;
-    export const surfaceBackgroundSubtleColor: string;
-    export const surfaceBackgroundTintColor: string;
-    export const surfaceBorderColor: string;
-    export const surfaceBorderBoldColor: string;
-    export const surfaceBorderSubtleColor: string;
-    export const surfaceBackgroundTertiaryColor: string;
-    export const surfaceColor: string;
-    export const transitionDuration: string;
-    export const transitionDurationFast: string;
-    export const transitionDurationFaster: string;
-    export const transitionDurationFastest: string;
-    export const transitionTimingFunction: string;
-    export const transitionTimingFunctionControl: string;
-    import toggleGroupControlBackgroundColor = controlBackgroundColor;
-    export { toggleGroupControlBackgroundColor };
-    export const toggleGroupControlBorderColor: string;
-    import toggleGroupControlButtonColorActive = controlBackgroundColor;
-    export { toggleGroupControlButtonColorActive };
-    export const controlSurfaceColor: string;
-    export const controlTextActiveColor: string;
-    export { CONTROL_PADDING_X as controlPaddingX };
-    export const controlPaddingXLarge: string;
-    export const controlPaddingXSmall: string;
-    export const controlBackgroundColor: string;
-    export const controlBorderRadius: string;
-    export const controlBorderColor: string;
-    export const controlBoxShadow: string;
-    export const controlBorderColorHover: string;
-    export const controlBoxShadowFocus: string;
-    export const controlDestructiveBorderColor: string;
-    export { CONTROL_HEIGHT as controlHeight };
-    export const controlHeightXSmall: string;
-    export const controlHeightSmall: string;
-    export const controlHeightLarge: string;
-    export const controlHeightXLarge: string;
-}
+declare var _default: {
+    controlSurfaceColor: string;
+    controlTextActiveColor: string;
+    controlPaddingX: string;
+    controlPaddingXLarge: string;
+    controlPaddingXSmall: string;
+    controlBackgroundColor: string;
+    controlBorderRadius: string;
+    controlBorderColor: string;
+    controlBoxShadow: string;
+    controlBorderColorHover: string;
+    controlBoxShadowFocus: string;
+    controlDestructiveBorderColor: string;
+    controlHeight: string;
+    controlHeightXSmall: string;
+    controlHeightSmall: string;
+    controlHeightLarge: string;
+    controlHeightXLarge: string;
+} & {
+    toggleGroupControlBackgroundColor: string;
+    toggleGroupControlBorderColor: string;
+    toggleGroupControlBackdropBackgroundColor: string;
+    toggleGroupControlBackdropBorderColor: string;
+    toggleGroupControlBackdropBoxShadow: string;
+    toggleGroupControlButtonColorActive: string;
+} & {
+    colorDivider: string;
+    colorScrollbarThumb: string;
+    colorScrollbarThumbHover: string;
+    colorScrollbarTrack: string;
+    elevationIntensity: number;
+    radiusBlockUi: string;
+    borderWidth: string;
+    borderWidthFocus: string;
+    borderWidthTab: string;
+    spinnerSize: number;
+    fontSize: string;
+    fontSizeH1: string;
+    fontSizeH2: string;
+    fontSizeH3: string;
+    fontSizeH4: string;
+    fontSizeH5: string;
+    fontSizeH6: string;
+    fontSizeInputMobile: string;
+    fontSizeMobile: string;
+    fontSizeSmall: string;
+    fontSizeXSmall: string;
+    fontLineHeightBase: string;
+    fontWeight: string;
+    fontWeightHeading: string;
+    gridBase: string;
+    cardBorderRadius: string;
+    cardPaddingXSmall: string;
+    cardPaddingSmall: string;
+    cardPaddingMedium: string;
+    cardPaddingLarge: string;
+    surfaceBackgroundColor: string;
+    surfaceBackgroundSubtleColor: string;
+    surfaceBackgroundTintColor: string;
+    surfaceBorderColor: string;
+    surfaceBorderBoldColor: string;
+    surfaceBorderSubtleColor: string;
+    surfaceBackgroundTertiaryColor: string;
+    surfaceColor: string;
+    transitionDuration: string;
+    transitionDurationFast: string;
+    transitionDurationFaster: string;
+    transitionDurationFastest: string;
+    transitionTimingFunction: string;
+    transitionTimingFunctionControl: string;
+};
 export default _default;
-declare namespace CONTROL_PROPS { }
-declare const CONTROL_PADDING_X: "12px";
-declare const CONTROL_HEIGHT: "36px";
 //# sourceMappingURL=config-values.d.ts.map

package/build-types/utils/config-values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-values.d.ts","sourceRoot":"","sources":["../../src/utils/config-values.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOA,wCAAiC;AADjC,qCAA8B"}
+{"version":3,"file":"config-values.d.ts","sourceRoot":"","sources":["../../src/utils/config-values.js"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "19.6.1",
+	"version": "19.8.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -37,21 +37,21 @@
 		"@emotion/styled": "^11.6.0",
 		"@emotion/utils": "1.0.0",
 		"@use-gesture/react": "^10.2.6",
-		"@wordpress/a11y": "^3.4.1",
-		"@wordpress/compose": "^5.2.1",
-		"@wordpress/date": "^4.4.1",
-		"@wordpress/deprecated": "^3.4.1",
-		"@wordpress/dom": "^3.4.1",
-		"@wordpress/element": "^4.2.1",
-		"@wordpress/escape-html": "^2.4.1",
-		"@wordpress/hooks": "^3.4.1",
-		"@wordpress/i18n": "^4.4.1",
-		"@wordpress/icons": "^8.0.1",
-		"@wordpress/is-shallow-equal": "^4.4.1",
-		"@wordpress/keycodes": "^3.4.1",
-		"@wordpress/primitives": "^3.2.1",
-		"@wordpress/rich-text": "^5.2.1",
-		"@wordpress/warning": "^2.4.1",
+		"@wordpress/a11y": "^3.6.0",
+		"@wordpress/compose": "^5.4.0",
+		"@wordpress/date": "^4.6.0",
+		"@wordpress/deprecated": "^3.6.0",
+		"@wordpress/dom": "^3.6.0",
+		"@wordpress/element": "^4.4.0",
+		"@wordpress/escape-html": "^2.6.0",
+		"@wordpress/hooks": "^3.6.0",
+		"@wordpress/i18n": "^4.6.0",
+		"@wordpress/icons": "^8.2.0",
+		"@wordpress/is-shallow-equal": "^4.6.0",
+		"@wordpress/keycodes": "^3.6.0",
+		"@wordpress/primitives": "^3.4.0",
+		"@wordpress/rich-text": "^5.4.0",
+		"@wordpress/warning": "^2.6.0",
 		"classnames": "^2.3.1",
 		"colord": "^2.7.0",
 		"dom-scroll-into-view": "^1.2.1",
@@ -76,5 +76,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "3494eafea7cb345728166c902b3d1223c4a8db6f"
+	"gitHead": "11eb1241e63c9240018323551c6753f8a5fa96f9"
 }

package/src/animate/README.md

@@ -5,7 +5,7 @@ Simple interface to introduce animations to components.
 ## Usage
 
 ```jsx
-import { Animate } from '@wordpress/components';
+import { Animate, Notice } from '@wordpress/components';
 
 const MyAnimatedNotice = () => (
 	<Animate type="slide-in" options={ { origin: 'top' } }>

package/src/base-control/README.md

@@ -1,16 +1,17 @@
 # BaseControl
 
-BaseControl component is used to generate labels and help text for components handling user inputs.
+`BaseControl` is a component used to generate labels and help text for components handling user inputs.
 
 ## Usage
 
-Render a BaseControl for a textarea input:
+Render a `BaseControl` for a textarea input:
 
 ```jsx
 import { BaseControl } from '@wordpress/components';
 
+// The `id` prop is necessary to accessibly associate the label with the textarea
 const MyBaseControl = () => (
-	<BaseControl id="textarea-1" label="Text" help="Enter some text">
+	<BaseControl id="textarea-1" label="Text" help="Enter some text" __nextHasNoMarginBottom={ true }>
 		<textarea id="textarea-1" />
 	</BaseControl>
 );
@@ -22,10 +23,10 @@ The component accepts the following props:
 
 ### id
 
-The id of the element to which labels and help text are being generated. That element should be passed as a child.
+The HTML `id` of the element (passed in as a child to `BaseControl`) to which labels and help text are being generated. This is necessary to accessibly associate the label with that element.
 
 -   Type: `String`
--   Required: Yes
+-   Required: No
 
 ### label
 
@@ -50,8 +51,7 @@ If this property is added, a help text will be generated using help property as
 
 ### className
 
-The class that will be added with "components-base-control" to the classes of the wrapper div.
-If no className is passed only components-base-control is used.
+Any other classes to add to the wrapper div.
 
 -   Type: `String`
 -   Required: No
@@ -63,10 +63,19 @@ The content to be displayed within the BaseControl.
 -   Type: `Element`
 -   Required: Yes
 
+### __nextHasNoMarginBottom
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`
+
 ## BaseControl.VisualLabel
 
-`BaseControl.VisualLabel` component is used to render a purely visual label inside a `BaseControl` component.
-It should only be used in cases where the children being rendered inside BaseControl are already properly labeled, e.g., a button, but we want an additional visual label for that section equivalent to the labels BaseControl would otherwise use if the label prop was passed.
+`BaseControl.VisualLabel` is used to render a purely visual label inside a `BaseControl` component.
+
+It should only be used in cases where the children being rendered inside BaseControl are already accessibly labeled, e.g., a button, but we want an additional visual label for that section equivalent to the labels `BaseControl` would otherwise use if the `label` prop was passed.
 
 ## Usage
 
@@ -74,7 +83,7 @@ It should only be used in cases where the children being rendered inside BaseCon
 import { BaseControl } from '@wordpress/components';
 
 const MyBaseControl = () => (
-	<BaseControl help="Pressing the Select an author button will open a modal that allows an advanced mechanism for author selection">
+	<BaseControl help="This button is already accessibly labeled.">
 		<BaseControl.VisualLabel>Author</BaseControl.VisualLabel>
 		<Button>Select an author</Button>
 	</BaseControl>
@@ -85,8 +94,7 @@ const MyBaseControl = () => (
 
 #### className
 
-The class that will be added with `components-base-control__label` to the classes of the wrapper div.
-If no className is passed only `components-base-control__label` is used.
+Any other classes to add to the wrapper div.
 
 -   Type: `String`
 -   Required: No

package/src/base-control/index.tsx

@@ -0,0 +1,124 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+import type { FunctionComponent } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { VisuallyHidden } from '../visually-hidden';
+import type { BaseControlProps, BaseControlVisualLabelProps } from './types';
+import {
+	Wrapper,
+	StyledField,
+	StyledLabel,
+	StyledHelp,
+	StyledVisualLabel,
+} from './styles/base-control-styles';
+
+/**
+ * `BaseControl` is a component used to generate labels and help text for components handling user inputs.
+ *
+ * @example
+ * // Render a `BaseControl` for a textarea input
+ * import { BaseControl } from '@wordpress/components';
+ *
+ * // The `id` prop is necessary to accessibly associate the label with the textarea
+ * const MyBaseControl = () => (
+ *   <BaseControl id="textarea-1" label="Text" help="Enter some text" __nextHasNoMarginBottom={ true }>
+ *     <textarea id="textarea-1" />
+ *   </BaseControl>
+ * );
+ */
+export const BaseControl = ( {
+	__nextHasNoMarginBottom = false,
+	id,
+	label,
+	hideLabelFromVision = false,
+	help,
+	className,
+	children,
+}: BaseControlProps ) => {
+	return (
+		<Wrapper
+			className={ classnames( 'components-base-control', className ) }
+		>
+			<StyledField
+				className="components-base-control__field"
+				// TODO: Official deprecation for this should start after all internal usages have been migrated
+				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+			>
+				{ label &&
+					id &&
+					( hideLabelFromVision ? (
+						<VisuallyHidden as="label" htmlFor={ id }>
+							{ label }
+						</VisuallyHidden>
+					) : (
+						<StyledLabel
+							className="components-base-control__label"
+							htmlFor={ id }
+						>
+							{ label }
+						</StyledLabel>
+					) ) }
+				{ label &&
+					! id &&
+					( hideLabelFromVision ? (
+						<VisuallyHidden as="label">{ label }</VisuallyHidden>
+					) : (
+						<BaseControl.VisualLabel>
+							{ label }
+						</BaseControl.VisualLabel>
+					) ) }
+				{ children }
+			</StyledField>
+			{ !! help && (
+				<StyledHelp
+					id={ id ? id + '__help' : undefined }
+					className="components-base-control__help"
+					__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+				>
+					{ help }
+				</StyledHelp>
+			) }
+		</Wrapper>
+	);
+};
+
+/**
+ * `BaseControl.VisualLabel` is used to render a purely visual label inside a `BaseControl` component.
+ *
+ * It should only be used in cases where the children being rendered inside `BaseControl` are already accessibly labeled,
+ * e.g., a button, but we want an additional visual label for that section equivalent to the labels `BaseControl` would
+ * otherwise use if the `label` prop was passed.
+ *
+ * @example
+ * import { BaseControl } from '@wordpress/components';
+ *
+ * const MyBaseControl = () => (
+ * 	<BaseControl help="This button is already accessibly labeled.">
+ * 		<BaseControl.VisualLabel>Author</BaseControl.VisualLabel>
+ * 		<Button>Select an author</Button>
+ * 	</BaseControl>
+ * );
+ */
+export const VisualLabel: FunctionComponent< BaseControlVisualLabelProps > = ( {
+	className,
+	children,
+} ) => {
+	return (
+		<StyledVisualLabel
+			className={ classnames(
+				'components-base-control__label',
+				className
+			) }
+		>
+			{ children }
+		</StyledVisualLabel>
+	);
+};
+BaseControl.VisualLabel = VisualLabel;
+
+export default BaseControl;

package/src/base-control/stories/index.tsx

@@ -0,0 +1,80 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '..';
+import Button from '../../button';
+
+const meta: ComponentMeta< typeof BaseControl > = {
+	title: 'Components/BaseControl',
+	component: BaseControl,
+	argTypes: {
+		children: { control: { type: null } },
+		help: { control: { type: 'text' } },
+		label: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const BaseControlWithTextarea: ComponentStory< typeof BaseControl > = ( {
+	id,
+	...props
+} ) => {
+	return (
+		<BaseControl id={ id } { ...props }>
+			<textarea style={ { display: 'block' } } id={ id } />
+		</BaseControl>
+	);
+};
+
+export const Default: ComponentStory<
+	typeof BaseControl
+> = BaseControlWithTextarea.bind( {} );
+Default.args = {
+	__nextHasNoMarginBottom: true,
+	id: 'textarea-default-1',
+	label: 'Label text',
+};
+
+export const WithHelpText = BaseControlWithTextarea.bind( {} );
+WithHelpText.args = {
+	...Default.args,
+	id: 'textarea-with-help-text-1',
+	help: 'Help text adds more explanation.',
+};
+
+/**
+ * `BaseControl.VisualLabel` is used to render a purely visual label inside a `BaseControl` component.
+ *
+ * It should only be used in cases where the children being rendered inside `BaseControl` are already accessibly labeled,
+ * e.g., a button, but we want an additional visual label for that section equivalent to the labels `BaseControl` would
+ * otherwise use if the `label` prop was passed.
+ */
+export const WithVisualLabel: ComponentStory< typeof BaseControl > = (
+	props
+) => {
+	BaseControl.VisualLabel.displayName = 'BaseControl.VisualLabel';
+
+	return (
+		<BaseControl { ...props }>
+			<BaseControl.VisualLabel>Visual label</BaseControl.VisualLabel>
+			<div>
+				<Button variant="secondary">Select an author</Button>
+			</div>
+		</BaseControl>
+	);
+};
+WithVisualLabel.args = {
+	...Default.args,
+	help: 'This button is already accessibly labeled.',
+	id: undefined,
+	label: undefined,
+};

package/src/base-control/styles/{base-control-styles.js → base-control-styles.ts}

@@ -15,8 +15,17 @@ export const Wrapper = styled.div`
 	font-size: ${ font( 'default.fontSize' ) };
 `;
 
+const deprecatedMarginField = ( { __nextHasNoMarginBottom = false } ) => {
+	return (
+		! __nextHasNoMarginBottom &&
+		css`
+			margin-bottom: ${ space( 2 ) };
+		`
+	);
+};
+
 export const StyledField = styled.div`
-	margin-bottom: ${ space( 2 ) };
+	${ deprecatedMarginField }
 
 	.components-panel__row & {
 		margin-bottom: inherit;
@@ -32,10 +41,23 @@ export const StyledLabel = styled.label`
 	${ labelStyles }
 `;
 
+const deprecatedMarginHelp = ( { __nextHasNoMarginBottom = false } ) => {
+	return (
+		! __nextHasNoMarginBottom &&
+		css`
+			margin-bottom: revert;
+		`
+	);
+};
+
 export const StyledHelp = styled.p`
+	margin-top: ${ space( 2 ) };
+	margin-bottom: 0;
 	font-size: ${ font( 'helpText.fontSize' ) };
 	font-style: normal;
 	color: ${ COLORS.mediumGray.text };
+
+	${ deprecatedMarginHelp }
 `;
 
 export const StyledVisualLabel = styled.span`