@automattic/jetpack-components 0.39.0

package/components/layout/container/index.tsx

@@ -0,0 +1,42 @@
+import classNames from 'classnames';
+import { useMemo } from 'react';
+import { ContainerProps } from '../types';
+import styles from './style.module.scss';
+import type React from 'react';
+
+/**
+ * JP Container
+ *
+ * @param {ContainerProps} props - Component properties.
+ * @returns {React.ReactElement}   Container component.
+ */
+const Container: React.FC< ContainerProps > = ( {
+	children,
+	fluid = false,
+	className,
+	horizontalGap = 1,
+	horizontalSpacing = 1,
+} ) => {
+	const containerStyle = useMemo( () => {
+		const padding = `calc( var(--horizontal-spacing) * ${ horizontalSpacing } )`;
+		const rowGap = `calc( var(--horizontal-spacing) * ${ horizontalGap } )`;
+
+		return {
+			paddingTop: padding,
+			paddingBottom: padding,
+			rowGap,
+		};
+	}, [ horizontalGap, horizontalSpacing ] );
+
+	const containerClassName = classNames( className, styles.container, {
+		[ styles.fluid ]: fluid,
+	} );
+
+	return (
+		<div className={ containerClassName } style={ containerStyle }>
+			{ children }
+		</div>
+	);
+};
+
+export default Container;

package/components/layout/container/style.module.scss

@@ -0,0 +1,35 @@
+@use "sass:map";
+@import "../breakpoints.module.scss";
+
+@mixin container($size) {
+	$paddings: ("sm": "16px", "md": "18px", "lg": "24px");
+	$padding: map.get($paddings, #{$size});
+
+	@include media(#{$size}) using ($columns) {
+		padding: 0 #{$padding};
+		grid-template-columns: repeat( #{$columns}, minmax(0, 1fr) );
+	}
+}
+
+.container {
+	--max-container-width: 1128px;
+	// vertical spacing
+	--vertical-gutter: 24px;
+	// horizontal spacing
+	--horizontal-spacing: 8px;
+
+	display: grid;
+	column-gap: var(--vertical-gutter);
+	max-width: var(--max-container-width);
+	margin: 0 auto;
+	width: 100%;
+
+	@include container( "sm" );
+	@include container( "md" );
+	@include container( "lg" );
+
+	&.fluid {
+		max-width: none;
+		padding: unset;
+	}
+}

package/components/layout/stories/index.stories.tsx

@@ -0,0 +1,145 @@
+import Text from '../../text';
+import Col from '../col';
+import Container from '../container';
+import useBreakpointMatch from '../use-breakpoint-match';
+import styles from './styles.module.scss';
+
+const Layout = ( { items, fluid, horizontalGap, horizontalSpacing } ) => {
+	return (
+		<Container
+			className={ styles.container }
+			horizontalSpacing={ horizontalSpacing }
+			fluid={ fluid }
+			horizontalGap={ horizontalGap }
+		>
+			{ items.map( ( { sm, lg, md }, idx ) => {
+				const smText = Number.isInteger( sm?.start ) ? JSON.stringify( sm ) : sm;
+				const mdText = Number.isInteger( md?.start ) ? JSON.stringify( md ) : md;
+				const lgText = Number.isInteger( lg?.start ) ? JSON.stringify( lg ) : lg;
+
+				return (
+					<Col
+						sm={ sm }
+						md={ md }
+						lg={ lg }
+						className={ styles.col }
+						key={ `${ smText }${ mdText }${ lgText }${ idx }` }
+					>
+						{ sm ? `sm=${ smText } ` : '' }
+						{ md ? `md=${ mdText } ` : '' }
+						{ lg ? `lg=${ lgText } ` : '' }
+					</Col>
+				);
+			} ) }
+			<Col>
+				<Container fluid horizontalSpacing={ 0 } horizontalGap={ 1 }>
+					<Col className={ styles.col }>Composition Example</Col>
+					<Col className={ styles.col }>Composition Example</Col>
+				</Container>
+			</Col>
+		</Container>
+	);
+};
+
+export default {
+	title: 'JS Packages/Components/Layout',
+	component: Layout,
+};
+
+const Template = args => <Layout { ...args } />;
+export const Default = Template.bind( {} );
+Default.args = {
+	fluid: false,
+	horizontalSpacing: 10,
+	horizontalGap: 5,
+	items: [
+		{
+			sm: 2,
+			md: 5,
+			lg: 4,
+		},
+		{
+			sm: 2,
+			md: 3,
+			lg: { start: 6, end: 12 },
+		},
+		{
+			sm: 2,
+			md: 3,
+			lg: 6,
+		},
+		{
+			sm: 2,
+			md: 5,
+			lg: { start: 9, end: 12 },
+		},
+		{
+			sm: 2,
+			md: 5,
+			lg: 4,
+		},
+		{
+			sm: 2,
+			md: 3,
+			lg: 8,
+		},
+	],
+};
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export const BreakpointMatch = args => {
+	const [ isSm, isGtSm, isMd, isLtOrMd, isLtMd, isGtOrMd, isGtMd, isLessThanLg, isLg ] =
+		useBreakpointMatch(
+			[ 'sm', 'sm', 'md', 'md', 'md', 'md', 'md', 'lg', 'lg' ],
+			[ null, '>', null, '<=', '<', '>=', '>', '<', null ]
+		);
+
+	return (
+		<Container>
+			{ /* SMALL */ }
+			<Text variant="headline-small">Small</Text>
+			<Col>
+				<Text variant="title-small">Is Small</Text>
+				<Text className={ isSm ? styles.yes : styles.no }>{ isSm ? 'Yes' : 'False' }</Text>
+			</Col>
+			<Col>
+				<Text variant="title-small">Is greater than Small</Text>
+				<Text className={ isGtSm ? styles.yes : styles.no }>{ isGtSm ? 'Yes' : 'False' }</Text>
+			</Col>
+			{ /* MEDIUM */ }
+			<Text variant="headline-small">Medium</Text>
+			<Col>
+				<Text variant="title-small">Is Medium</Text>
+				<Text className={ isMd ? styles.yes : styles.no }>{ isMd ? 'Yes' : 'False' }</Text>
+			</Col>
+			<Col>
+				<Text variant="title-small">Is less then Medium</Text>
+				<Text className={ isLtMd ? styles.yes : styles.no }>{ isLtMd ? 'Yes' : 'False' }</Text>
+			</Col>
+			<Col>
+				<Text variant="title-small">Is less then OR Medium</Text>
+				<Text className={ isLtOrMd ? styles.yes : styles.no }>{ isLtOrMd ? 'Yes' : 'False' }</Text>
+			</Col>
+			<Col>
+				<Text variant="title-small">Is greater then Medium</Text>
+				<Text className={ isGtMd ? styles.yes : styles.no }>{ isGtMd ? 'Yes' : 'False' }</Text>
+			</Col>
+			<Col>
+				<Text variant="title-small">Is greater then OR Medium</Text>
+				<Text className={ isGtOrMd ? styles.yes : styles.no }>{ isGtOrMd ? 'Yes' : 'False' }</Text>
+			</Col>
+			{ /* LARGE */ }
+			<Text variant="headline-small">Large</Text>
+			<Col>
+				<Text variant="title-small">Is Large</Text>
+				<Text className={ isLg ? styles.yes : styles.no }>{ isLg ? 'Yes' : 'False' }</Text>
+			</Col>
+			<Col>
+				<Text variant="title-small">Is less than Large</Text>
+				<Text className={ isLessThanLg ? styles.yes : styles.no }>
+					{ isLessThanLg ? 'Yes' : 'False' }
+				</Text>
+			</Col>
+		</Container>
+	);
+};

package/components/layout/stories/styles.module.scss

@@ -0,0 +1,22 @@
+.container {
+	background: var(--jp-gray-50);
+}
+
+.col {
+	padding: 20px;
+	background: var(--jp-gray-80);
+	font-size: 1rem;
+	color: var(--jp-white-off);
+}
+
+.yes {
+	padding: var(--spacing-base);
+	background-color: var(--jp-green-0);
+	border: 1px solid var(--jp-green-50);
+}
+
+.no {
+	padding: var(--spacing-base);
+	background-color: var(--jp-red-0);
+	border: 1px solid var(--jp-red-50);
+}

package/components/layout/types.ts

@@ -0,0 +1,55 @@
+type ColSpan = number | { start: number; end: number };
+
+export type ColProps = {
+	/**
+	 * Custom className to be inserted.
+	 */
+	className?: string;
+
+	/**
+	 * Colspan for small viewport. Needs to be an integer.
+	 */
+	sm?: ColSpan;
+
+	/**
+	 * Colstart for medium viewport. Needs to be an integer.
+	 */
+	md?: ColSpan;
+
+	/**
+	 * Colstart for large viewport. Needs to be an integer.
+	 */
+	lg?: ColSpan;
+
+	/**
+	 * Children to be inserted.
+	 */
+	children?: React.ReactNode;
+};
+
+export type ContainerProps = {
+	/**
+	 * Make container not having a max width.
+	 */
+	fluid?: boolean;
+
+	/**
+	 * Custom className to be inserted.
+	 */
+	className?: string;
+
+	/**
+	 * Number of spacing (top / bottom), it gets mutiplied by 8px. Needs to be an integer
+	 */
+	horizontalSpacing?: number;
+
+	/**
+	 * Number of gap betwen rows, it gets multipled by 8px. Needs to be an integer
+	 */
+	horizontalGap?: number;
+
+	/**
+	 * Children to be inserted.
+	 */
+	children?: React.ReactNode;
+};

package/components/layout/use-breakpoint-match/README.md

@@ -0,0 +1,43 @@
+# useBreakpointMatch
+
+Utility to match against breakpoints.
+
+[ Storybook Reference ](https://automattic.github.io/jetpack-storybook/?path=/story/js-packages-components-layout--breakpoint-match)
+
+## Usage
+
+```jsx
+import { useBreakpointMatch } from '@automattic/jetpack-components';
+const [ isLg ] = useBreakpointMatch('lg')
+return isLg && <Component />
+```
+
+## Parameters
+
+### breakpointToMatch
+
+Single or Array of breakpoints to match against.
+
+- Type: `String`|`Array<String>`
+- Required: `true`
+
+```javascript
+useBreakpointMatch('lg');
+useBreakpointMatch([ 'lg', 'sm' ]);
+```
+
+### operator
+
+A Single or Array of operators to match less, equal, or greater than the breakpoint.
+
+In Array, it matches against the same index from breakpoint.
+
+- Type: `String`|`Array<String>`
+- Required: `false`
+
+#### Example
+
+```javascript
+useBreakpointMatch('md', '<=');
+useBreakpointMatch([ 'lg', 'sm' ], ['<', '>']);
+```

package/components/layout/use-breakpoint-match/declaration.d.ts

@@ -0,0 +1,9 @@
+declare module '*.module.css' {
+	const classes: { [ key: string ]: string };
+	export default classes;
+}
+
+declare module '*.module.scss' {
+	const classes: { [ key: string ]: string };
+	export default classes;
+}

package/components/layout/use-breakpoint-match/index.ts

@@ -0,0 +1,79 @@
+import { useMediaQuery } from '@wordpress/compose';
+import breakpointsValues from '../breakpoints.module.scss';
+
+const BREAKPOINTS = [ 'sm', 'md', 'lg' ] as const;
+
+type Breakpoints = ( typeof BREAKPOINTS )[ number ];
+
+type Operators = '<' | '<=' | '>' | '>=';
+
+type Matches = { sm: boolean; md: boolean; lg: boolean };
+
+const getMediaByOperator = (
+	breakpoint: Breakpoints,
+	operator: Operators,
+	matches: Matches
+): boolean => {
+	const breakpointIndex = BREAKPOINTS.indexOf( breakpoint );
+	const breakpointIndexPlusOne = breakpointIndex + 1;
+	const isEqual = operator.includes( '=' );
+
+	let allNeededBreakpoints = [];
+
+	if ( operator.startsWith( '<' ) ) {
+		allNeededBreakpoints = BREAKPOINTS.slice(
+			0,
+			isEqual ? breakpointIndexPlusOne : breakpointIndex
+		);
+	}
+
+	if ( operator.startsWith( '>' ) ) {
+		allNeededBreakpoints = BREAKPOINTS.slice( isEqual ? breakpointIndex : breakpointIndexPlusOne );
+	}
+
+	return allNeededBreakpoints?.length
+		? allNeededBreakpoints.some( brk => matches[ brk ] )
+		: matches[ breakpoint ];
+};
+
+/**
+ * Hook to match if current viewport is equal, greater or less than expected breakpoint
+ *
+ * @param {(Breakpoints | Array< Breakpoints >)} breakpointToMatch	  - An single breakpoint or list of breakpoints to match.
+ * @param {(Operators | Array< Operators >)} operatorToMatch				  - An single operator or list of them. It should follow the same sequence than breakpoints.
+ * @returns {Array<boolean>}																					- List of matches, following breakpoints sequence.
+ * @example
+ *
+ * ```es6
+ * useBreakpointMatch('sm')
+ * useBreakpointMatch('lg', '<')
+ * useBreakpointMatch([ 'lg', 'sm' ], [ '<', null ])
+ * ```
+ */
+const useBreakpointMatch = (
+	breakpointToMatch: Breakpoints | Array< Breakpoints >,
+	operatorToMatch?: Operators | Array< Operators >
+) => {
+	const breakpoints: Array< Breakpoints > = Array.isArray( breakpointToMatch )
+		? breakpointToMatch
+		: [ breakpointToMatch ];
+
+	const operators: Array< Operators > = Array.isArray( operatorToMatch )
+		? operatorToMatch
+		: [ operatorToMatch ];
+
+	const [ smKey, mdKey, lgKey ] = BREAKPOINTS;
+
+	const sm = useMediaQuery( breakpointsValues[ smKey ] );
+	const md = useMediaQuery( breakpointsValues[ mdKey ] );
+	const lg = useMediaQuery( breakpointsValues[ lgKey ] );
+
+	const matches: Matches = { sm, md, lg };
+
+	return breakpoints.map( ( breakpoint, idx ) => {
+		const operator = operators[ idx ];
+		return operator ? getMediaByOperator( breakpoint, operator, matches ) : matches[ breakpoint ];
+	} );
+};
+
+export default useBreakpointMatch;

package/components/loading-placeholder/README.md

@@ -0,0 +1,22 @@
+LoadingPlaceholder
+=========
+
+This component is used in case we want to create a skeleton loader.
+
+## General Usage:
+
+```js
+import { LoadingPlaceholder } from '@automattic/jetpack-components';
+render() {
+	return (
+		<Placeholder width="60%" height={ 30 } />
+	);
+}
+```
+
+## Props
+
+- `width`: an optional placeholder width
+- `height`: an optional placeholder height.
+- `children`: an optional react child
+- `className`: an optional class name.

package/components/loading-placeholder/index.tsx

@@ -0,0 +1,23 @@
+import classNames from 'classnames';
+import React from 'react';
+import styles from './style.module.scss';
+
+const LoadingPlaceholder = ( {
+	children = null,
+	width = null,
+	height = null,
+	className = '',
+}: {
+	children?: React.ReactNode;
+	width?: number | string;
+	height?: number;
+	className?: string;
+} ) => {
+	return (
+		<div className={ classNames( styles.placeholder, className ) } style={ { width, height } }>
+			{ children }
+		</div>
+	);
+};
+
+export default LoadingPlaceholder;

package/components/loading-placeholder/stories/index.stories.tsx

@@ -0,0 +1,78 @@
+/**
+ * Internal dependencies
+ */
+import LoadingPlaceholder from '..';
+/**
+ * Types
+ */
+import type { ComponentStory, ComponentMeta } from '@storybook/react';
+
+export default {
+	title: 'JS Packages/Components/Loading Placeholder',
+	component: LoadingPlaceholder,
+	parameters: {
+		layout: 'centered',
+	},
+} as ComponentMeta< typeof LoadingPlaceholder >;
+
+const Template: ComponentStory< typeof LoadingPlaceholder > = args => (
+	<LoadingPlaceholder { ...args } />
+);
+
+export const Fluid = Template.bind( {} );
+Fluid.decorators = [
+	Story => (
+		<div
+			style={ {
+				width: '200px',
+				height: '300px',
+			} }
+		>
+			<Story />
+		</div>
+	),
+];
+
+Fluid.argTypes = {
+	width: {
+		table: {
+			disable: true,
+		},
+	},
+	height: {
+		table: {
+			disable: true,
+		},
+	},
+};
+
+Fluid.args = {
+	width: null,
+	height: null,
+};
+
+export const Fixed = Template.bind( {} );
+
+Fixed.args = {
+	width: 200,
+	height: 300,
+};
+
+Fixed.argTypes = {
+	width: {
+		control: {
+			type: 'range',
+			min: 0,
+			max: 500,
+			step: 1,
+		},
+	},
+	height: {
+		control: {
+			type: 'range',
+			min: 0,
+			max: 500,
+			step: 1,
+		},
+	},
+};

package/components/loading-placeholder/style.module.scss

@@ -0,0 +1,18 @@
+@keyframes pulse {
+  0% {
+    opacity: .6;
+  }
+  50% {
+    opacity: 1;
+  }
+  100% {
+    opacity: .6;
+  }
+}
+
+.placeholder {
+  background-color: var( --jp-gray );
+  animation: pulse 1.5s infinite;
+  height: 100%;
+  width: 100%;
+}

package/components/notice/index.tsx

@@ -0,0 +1,98 @@
+import { Icon, warning, info, check, close } from '@wordpress/icons';
+import classNames from 'classnames';
+import React from 'react';
+import styles from './style.module.scss';
+
+type NoticeProps = {
+	/** The severity of the alert. */
+	level: 'error' | 'warning' | 'info' | 'success';
+
+	/** The title of the notice */
+	title: string;
+
+	/** A list of action elements to show across the bottom */
+	actions?: React.ReactNode[];
+
+	/** Hide close button */
+	hideCloseButton?: boolean;
+
+	/** Method to call when the close button is clicked */
+	onClose?: () => void;
+
+	/** Children to be rendered inside the alert. */
+	children: React.ReactNode;
+};
+
+const getIconByLevel = ( level: NoticeProps[ 'level' ] ) => {
+	switch ( level ) {
+		case 'error':
+			return warning;
+		case 'warning':
+			return warning;
+		case 'info':
+			return info;
+		case 'success':
+			return check;
+		default:
+			return warning;
+	}
+};
+
+/**
+ * Notice component
+ *
+ * @param {object} props                    - The component properties.
+ * @param {string} props.level              - The notice level: error, warning, info, success.
+ * @param {boolean} props.hideCloseButton   - Whether to hide the close button.
+ * @param {Function} props.onClose          - The function to call when the close button is clicked.
+ * @param {string} props.title              - The title of the notice.
+ * @param {React.ReactNode[]} props.actions - Actions to show across the bottom of the bar.
+ * @param {React.Component} props.children  - The notice content.
+ * @returns {React.ReactElement}              The `Notice` component.
+ */
+const Notice: React.FC< NoticeProps > = ( {
+	level,
+	title,
+	children,
+	actions,
+	hideCloseButton,
+	onClose,
+} ) => {
+	const classes = classNames( styles.container, styles[ `is-${ level }` ] );
+
+	return (
+		<div className={ classes }>
+			<div className={ styles[ 'icon-wrapper' ] }>
+				<Icon icon={ getIconByLevel( level ) } className={ styles.icon } />
+			</div>
+
+			<div className={ styles[ 'main-content' ] }>
+				<div className={ styles.title }>{ title }</div>
+				{ children }
+
+				{ actions && actions.length > 0 && (
+					<div className={ styles[ 'action-bar' ] }>
+						{ actions.map( ( action, index ) => (
+							<div key={ index } className={ styles.action }>
+								{ action }
+							</div>
+						) ) }
+					</div>
+				) }
+			</div>
+
+			{ ! hideCloseButton && (
+				<button aria-label="close" className={ styles[ 'close-button' ] } onClick={ onClose }>
+					<Icon icon={ close } />
+				</button>
+			) }
+		</div>
+	);
+};
+
+Notice.defaultProps = {
+	level: 'info',
+	hideCloseButton: false,
+};
+
+export default Notice;