@automattic/jetpack-components 0.39.0

package/components/text/stories/index.mdx

@@ -0,0 +1,195 @@
+import { Meta, Source, Story } from '@storybook/addon-docs';
+import dedent from 'ts-dedent';
+import Text, { BOX_MODEL_VALUES, H2, H3, Title } from '../index';
+import * as Stories from './index.stories';
+
+<Meta of={Stories} />
+
+# Text
+Set of React jetpack-components intended to facilitate when dealing with rendering text content.
+
+## &lt;Text /&gt;
+
+`Text` is the primary component that renders text, supporting the following features:
+
+* **Typography**: provided by the ThemeProvider component.
+* **Spacing**: A simple range of shorthand classes to modify the text element's margin and padding.
+
+### Props
+
+#### variant
+
+**Type**: `headline-medium`, `headline-small`, `headline-small-regular`, `title-medium`,
+`title-medium-semi-bold`, `title-small`, `body`, `body-small`, `body-extra-small`,
+`body-extra-small-bold`, `label`.
+
+Define the text Typography variant among the options offered by the ThemeProvider component.
+
+<Source
+  language='jsx'
+  code={dedent`
+    import Text from '@automattic/jetpack-components';
+    
+    function Hello() {
+      return (
+        <Text variant="headline-medium">
+          Hello, Text component!
+        </Text>
+      );
+    }
+  `}
+/>
+
+#### Spacing properties
+
+**Type**: number, one of `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`.
+
+Use the following properties to define margin and padding of the text. The unit is defined by the `--spacing-base` value.
+You can see how it works playing with the [Box Model](./?path=/story/js-packages-components-text--box-model) story.
+
+Prop | Description
+---|---
+**m** | margin
+**mt** | margin-top
+**mr** | margin-right
+**mb** | margin-bottom
+**ml** | margin-left
+**mx** | margin left and right
+**my** | margin top and bottom
+**p** | padding
+**pt** | padding-top
+**pr** | padding-right
+**pb** | padding-bottom
+**pl** | padding-left
+**px** | padding left and right
+**py** | padding top and bottom
+
+<Source
+  language='jsx'
+  code={dedent`
+    import Text from '@automattic/jetpack-components';
+    
+    function HelloBoxModel() {
+      return (
+        <Text mt={ 2 } px={ 4 }>
+          Hello, Text component!
+        </Text>
+      );
+    }
+  `}
+/>
+
+#### component
+
+**Type**: `elementType`, `string`.
+
+Force an specific tag (`"span"`, `"div"`) or use a custom component that will receive className and children.
+
+The example below renders the component with a `<span />` element.
+
+<Source
+  language='jsx'
+  code={dedent`
+    import Text from '@automattic/jetpack-components';
+    function SpanTextComponent() {
+      return (
+        <Text component="span" variant="title-medium">
+          Never underestimate the span element
+        </Text>
+      );
+    }
+  `}
+/>
+
+The following example shows how to define the typography and the margin for a Custom component.
+The className is passed down to the custom component, while the properties that belong to the Text component (in this case, `component`, `variant` and `mb`) are not.
+
+<Source
+  language='jsx'
+  code={dedent`
+    import Text from '@automattic/jetpack-components';
+    
+    function CustomComponent( { children, className } ) {
+      // className, provided by Text, is "custom-classname"
+      return (
+        <div className={ className }>{ children }</div>
+      );
+    }
+    
+    // Use a custom component when rendering the <Text />,
+    // it passes down the className property to it.
+    function CustomTextComponent() {
+      return (
+        <Text
+          component={ CustomComponent }
+          className="custom-classname"
+          variant="title-medium"
+          mb={ 3 }
+        >
+          Hello, Custom Text component!
+        </Text>
+      );
+    }
+  `}
+/>
+
+[▶️ Custom Tag story](.?path=/story/js-packages-components-text--custom-tag) and [▶️ Custom Component story](.?path=/story/js-packages-components-text--custom-component)
+
+#### Children
+
+**Type**: `node`.
+
+The text itself that will be rendered.
+
+# Text based components
+
+## &lt;H2 /&gt;
+Text shorthand to render a `heading-medium` text, applying proper spacing.
+
+[▶️ Story](.?path=/story/js-packages-components-text-heading--headline-h-2)
+
+## &lt;H3 /&gt;
+Text shorthand to render a `heading-small` text, applying proper spacing.
+
+[▶️ Story](.?path=/story/js-packages-components-text-heading--headline-h-3)
+
+### Props
+
+#### Weight: `bold` (default) | `regular`
+
+<Source
+  language='jsx'
+  code={dedent`
+    import { H3 } from '@automattic/jetpack-components';
+    
+    function Subtitle() {
+      return (
+        <H3 weight="regular">Let's explaining what H3 is</H3>
+      );
+    }
+  `}
+/>
+
+## &lt;Title /&gt;
+Text shorthand to render a `body` text, applying proper spacing.
+
+### Props
+
+#### Size: `medium` (default) | `small`
+
+<Source
+  language='jsx'
+  code={dedent`
+    import { Title } from '@automattic/jetpack-components';
+    
+    function Subtitle() {
+      return (
+        <Title size="small">
+          To explain what a Title component does, we should before...
+        </Title>
+      );
+    }
+  `}
+/>
+
+[▶️ Story](.?path=/story/js-packages-components-text-title--default)

package/components/text/stories/index.stories.tsx

@@ -0,0 +1,69 @@
+import Text, { BOX_MODEL_VALUES, H2, H3, Title, VARIANTS_MAPPING } from '../index';
+import styles from './style.module.scss';
+import type { SpacingValue } from '../types';
+
+const SPACING_VALUES: Array< SpacingValue > = [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ];
+
+export default {
+	title: 'JS Packages/Components/Text',
+	component: Text,
+	argTypes: {
+		...BOX_MODEL_VALUES.reduce(
+			( obj, cur ) => ( {
+				...obj,
+				[ cur ]: {
+					control: { type: 'select' },
+					options: SPACING_VALUES,
+				},
+			} ),
+			{}
+		),
+		variant: {
+			control: {
+				type: 'select',
+			},
+			options: Object.keys( VARIANTS_MAPPING ),
+		},
+	},
+	subcomponents: { H2, H3, Title },
+};
+
+const Template = args => <Text { ...args }>{ args.variant ?? 'body' }</Text>;
+
+export const Default = Template.bind( {} );
+
+Default.args = {
+	variant: 'headline-medium',
+};
+
+export const CustomTag = Template.bind( {} );
+
+CustomTag.args = {
+	variant: 'title-small',
+	component: 'div',
+};
+
+const Custom = ( { className, children } ) => (
+	<span className={ className }>{ children } Composition</span>
+);
+
+export const CustomComponent = Template.bind( {} );
+
+CustomComponent.args = {
+	variant: 'headline-small',
+	component: Custom,
+};
+
+const BoxModelTemplate = args => (
+	<div className={ styles[ 'box-model-wrapper' ] }>
+		<div className={ styles[ 'box-model-side-left' ] } />
+		<div className={ styles[ 'box-model-side-center' ] }>
+			<Text { ...args }>
+				<div className={ styles[ 'box-model-inner' ] }>Box Model</div>
+			</Text>
+		</div>
+		<div className={ styles[ 'box-model-side-right' ] } />
+	</div>
+);
+
+export const BoxModel = BoxModelTemplate.bind( {} );

package/components/text/stories/style.module.scss

@@ -0,0 +1,64 @@
+.instance {
+	span {
+		color: var( --jp-gray-40 );
+		display: inline-block;
+		width: 100%;
+		background-color: var( --jp-white-off );
+	}
+}
+
+.box-model-wrapper {
+	height: 100%;
+	display: flex;
+	margin-top: 50px;
+}
+.box-model-side-left,
+.box-model-side-right {
+	flex-grow: 1;
+}
+.box-model-side-center {
+	background-color: #A68169;
+	position: relative;
+	&:after {
+		content:" ";
+		border: 1px dashed rgba( 0, 0, 0, 0.6 );
+		display: block;
+		position: absolute;
+		top: 0;
+		left: 0;
+		height: 100%;
+		width: 100%;
+	}
+	> p {
+		background-color: #B9C386;
+		position: relative;
+		&:after {
+			content:" ";
+			border: 1px dashed rgba( 0, 0, 0, 0.6 );
+			display: block;
+			position: absolute;
+			top: 0;
+			left: 0;
+			height: 100%;
+			width: 100%;
+		}
+		.box-model-inner {
+			min-width: 200px;
+			min-height: 50px;
+			line-height: 50px;
+			background-color: #8FAFBA;
+			text-align: center;
+			position: relative;
+			&:after {
+				content: " ";
+				border: 1px dashed rgba( 0, 0, 0, 0.4 );
+				display: block;
+				position: absolute;
+				top: 0;
+				left: 0;
+				height: 100%;
+				width: 100%;
+			}
+		}
+	}
+}

package/components/text/stories/title.index.stories.tsx

@@ -0,0 +1,34 @@
+import { Title } from '../index';
+import styles from './style.module.scss';
+import type { TitleProps } from '../types';
+
+const TIPOGRAPHY_SIZES: Array< TitleProps[ 'size' ] > = [ 'medium', 'small' ];
+
+export default {
+	title: 'JS Packages/Components/Text/Title',
+	component: Title,
+	argTypes: {
+		children: {
+			control: { type: 'text' },
+		},
+		size: {
+			control: { type: 'select' },
+			options: TIPOGRAPHY_SIZES,
+		},
+	},
+};
+
+const Template = args => (
+	<div className={ styles.instance }>
+		<span>Text above to the the component...</span>
+		<Title { ...args }>
+			{ args?.children || 'Title Medium - Secure, grow, and increase your site speed' }
+		</Title>
+		<span>Text below to the the component...</span>
+	</div>
+);
+
+export const Default = Template.bind( {} );
+Default.args = {
+	size: 'medium',
+} as TitleProps;

package/components/text/style.module.scss

@@ -0,0 +1,125 @@
+/* Reset all margin and padding for used components */
+.reset {
+	margin: 0;
+	padding: 0;
+}
+
+/* Emerald Typography/Headline Medium */
+.headline-medium {
+	font-size: var(--font-headline-medium);
+	font-weight: 700;
+	line-height: 52px;
+}
+
+/* Emerald Typography/Headline Small */
+.headline-small {
+	font-size: var(--font-headline-small);
+	font-weight: 700;
+	line-height: 40px;
+}
+
+/* Emerald Typography/Headline Small Regular */
+.headline-small-regular {
+	font-size: var(--font-headline-small);
+	font-weight: 400;
+	line-height: 40px;
+}
+
+/* Emerald Typography/Title Medium */
+.title-medium {
+	font-size: var(--font-title-medium);
+	font-weight: 500;
+	line-height: 32px;
+}
+
+/* Emerald Typography/Title Medium Semi Bold */
+.title-medium-semi-bold {
+	font-size: var(--font-title-medium);
+	font-weight: 600;
+	line-height: 32px;
+}
+
+/* Emerald Typography/Title Small */
+.title-small {
+	font-size: var(--font-title-small);
+	font-weight: 500;
+	line-height: 30px;
+}
+
+/* Emerald Typography/Body */
+.body {
+	font-size: var(--font-body);
+	font-weight: 400;
+	line-height: 24px;
+}
+
+/* Emerald Typography/Body Small */
+.body-small {
+	font-size: var(--font-body-small);
+	font-weight: 400;
+	line-height: 24px;
+}
+
+/* Emerald Typography/Body Extra Small */
+.body-extra-small {
+	font-size: var(--font-body-extra-small);
+	font-weight: 400;
+	line-height: 20px;
+}
+
+/* Emerald Typography/Body Extra Small Bold */
+.body-extra-small-bold {
+	font-size: var(--font-body-extra-small);
+	font-weight: 700;
+	line-height: 20px;
+}
+
+/* Emerald Typography/Body Extra Small Label */
+.label {
+	font-size: var(--font-body-extra-small);
+	font-weight: 600;
+	line-height: 16px;
+}
+
+/** Box-Model: Spacing (margin) */
+$props: (
+	"margin": "m",
+	"padding": "p",
+);
+
+$sides: (
+	"top": "t",
+	"right": "r",
+	"bottom": "b",
+	"left": "l",
+);
+
+@each $prop, $p in $props {
+	$sizes: ( 0, 1, 2, 3, 4, 5, 6, 7, 8 );
+
+	@each $size in $sizes {
+		/* m, p */
+		.#{$p}-#{$size} {
+			#{$prop}: calc( var( --spacing-base ) * #{$size} );
+		}
+
+		/* mx, px */
+		.#{$p}x-#{$size} {
+			#{$prop}-left: calc( var( --spacing-base ) * #{$size} );
+			#{$prop}-right: calc( var( --spacing-base ) * #{$size} );
+		}
+
+		.#{$p}y-#{$size} {
+			#{$prop}-top: calc( var( --spacing-base ) * #{$size} );
+			#{$prop}-bottom: calc( var( --spacing-base ) * #{$size} );
+		}
+
+		/* mt, mr, mb, ml */
+		/* pt, pr, pb, pl */
+		@each $side, $s in $sides {
+			.#{$p}#{$s}-#{$size} {
+				#{$prop}-#{$side}: calc( var( --spacing-base ) * #{$size} );
+			}
+		}
+	}
+}

package/components/text/types.ts

@@ -0,0 +1,53 @@
+import { VARIANTS_MAPPING } from './constants';
+import type React from 'react';
+
+export type SpacingValue = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+
+export type TextProps = {
+	variant?: keyof typeof VARIANTS_MAPPING;
+	/** margin */
+	m?: SpacingValue;
+	/** margin-top */
+	mt?: SpacingValue;
+	/** margin-right */
+	mr?: SpacingValue;
+	/** margin-bottom */
+	mb?: SpacingValue;
+	/** margin-left */
+	ml?: SpacingValue;
+	/** margin left and right */
+	mx?: SpacingValue;
+	/** margin top and bottom */
+	my?: SpacingValue;
+	/** padding */
+	p?: SpacingValue;
+	/** padding-top */
+	pt?: SpacingValue;
+	/** padding-right */
+	pr?: SpacingValue;
+	/** padding-bottom */
+	pb?: SpacingValue;
+	/** padding-left */
+	pl?: SpacingValue;
+	/** padding left and right */
+	px?: SpacingValue;
+	/** padding top and bottom */
+	py?: SpacingValue;
+	/** HTML Class */
+	className?: string;
+	/** The text itself that will be rendered. */
+	children: React.ReactNode;
+	/** Force an specific tag (span, div) or use a custom component that will receive className and children */
+	component?: React.FC< { [ prop: string ]: unknown } > | React.ElementType;
+	[ prop: string ]: unknown;
+};
+
+export type H3Props = TextProps & {
+	/** Font weight: 'bold' (default) | 'regular'. */
+	weight?: 'bold' | 'regular';
+};
+
+export type TitleProps = TextProps & {
+	/** Heading size: 'medium' (default) | 'small'. */
+	size?: 'medium' | 'small';
+};

package/components/theme-provider/Readme.md

@@ -0,0 +1,49 @@
+= ThemeProvider
+
+ThemeProvider is a React component that, at the moment, defines and sets CSS variables to a wrapper element to make them accessible by the children components.
+Usually, you'd like to provide the styles by wrappig your App component:
+
+```jsx
+import { ThemeProvider } from '@automattic/jetpack-components';
+
+function MyComponent() {
+	return (
+		<ThemeProvider>
+			<div style={ { color: var( --jp-green ) } }>Jetpack</div>
+		</ThemeProvider>
+	);
+}
+```
+
+Unlike other more complex implementations that use React context to share data, the CSS vars are defined in the DOM element, and consequently, propagated to child DOM elements.
+
+## API
+
+### Children
+
+ReactNode children to be wrapped by the ThemeProvider element.
+
+### targetDom
+
+Optional target DOM element to set the styles. By default, they are set in a new wrapper element created by the provider.
+But when targetDom is defined, the styles are set straight into the given target, thus, the wrapper is not created.
+
+When defining it, it's up to you the proper target to store the styles.
+
+The following example stores the styles at the top of the page, in the body.
+
+```jsx
+import { ThemeProvider } from '@automattic/jetpack-components';
+
+function MyComponent() {
+	return (
+		<ThemeProvider targetDom={ document.body }>
+			<div style={ { color: var( --jp-green ) } }>Jetpack</div>
+		</ThemeProvider>
+	);
+}
+```
+
+### id
+
+Pass an id to register the ThemeProvider instance to avoid redefining the styles every time that a ThemeProvider instance is created, avoiding unneeded redefinitions of the styles.

package/components/theme-provider/globals.module.scss

@@ -0,0 +1,6 @@
+/* DO NOT USE THIS TO OVERRIDE STYLES */
+.global {
+	& * {
+		box-sizing: border-box;
+	}
+}