Component System: Add Elevation Component

packages/components/src/ui/elevation/README.md

@@ -0,0 +1,70 @@
+# Elevation
+
+`Elevation` is a core component that renders shadow, using the component system's shadow system.
+
+## Usage
+
+The shadow effect is generated using the `value` prop.
+
+```jsx live
+import {
+	__experimentalElevation as Elevation,
+	__experimetnalSurface as Surface,
+	__experimetnalText as Text,
+	__experimetnalView as View,
+} from '@wp-g2/components';
+
+function Example() {
+	return (
+		<Surface>
+			<Text>Elevation</Text>
+			<Elevation value={ 5 } />
+		</Surface>
+	);
+}
+```
+
+## Props
+
+##### active
+
+**Type**: `boolean`
+
+Renders the active (interaction) shadow value.
+
+##### borderRadius
+
+**Type**: `string`,`number`
+
+Renders the border-radius of the shadow.
+
+##### focus
+
+**Type**: `boolean`
+
+Renders the focus (interaction) shadow value.
+
+##### hover
+
+**Type**: `boolean`
+
+Renders the hover (interaction) shadow value.
+
+##### isInteractive
+
+**Type**: `boolean`
+
+Determines if hover, active, and focus shadow values should be automatically calculated and rendered.
+
+##### offset
+
+**Type**: `number`
+
+Dimensional offsets (margin) for the shadow.
+
+##### value
+
+**Type**: `number`
+
+Size of the shadow, based on the Style system's elevation system. The `value` determines the strength of the shadow, which sense of depth.
+In the example below, `isInteractive` is activated to give a better sense of depth.

packages/components/src/ui/elevation/elevation-styles.js

@@ -0,0 +1,13 @@
+/**
+ * External dependencies
+ */
+import { css } from '@wp-g2/styles';
+
+export const Elevation = css`
+	background: transparent;
+	display: block;
+	margin: 0 !important;
+	pointer-events: none;
+	position: absolute;
+	will-change: box-shadow;
+`;

packages/components/src/ui/elevation/elevation.js

@@ -0,0 +1,44 @@
+/**
+ * External dependencies
+ */
+import { contextConnect } from '@wp-g2/context';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../view';
+import { useElevation } from './use-elevation';
+
+/**
+ *
+ * @param {import('@wp-g2/create-styles').ViewOwnProps<import('./types').Props, 'div'>} props
+ * @param {import('react').Ref<any>} forwardedRef
+ */
+function Elevation( props, forwardedRef ) {
+	const otherProps = useElevation( props );
+
+	return <View aria-hidden { ...otherProps } ref={ forwardedRef } />;
+}
+
+/**
+ * `Elevation` is a core component that renders shadow, using the library's shadow system.
+ *
+ * The shadow effect is generated using the `value` prop.
+ *
+ * @example
+ * ```jsx
+ * function Example() {
+ *   return (
+ *     <View css={ [ ui.padding( 5 ) ] }>
+ *       <Surface css={ [ ui.padding( 5 ) ] }>
+ *         <Text>Into The Unknown</Text>
+ *         <Elevation value={ 5 } />
+ *       </Surface>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+const ConnectedElevation = contextConnect( Elevation, 'Elevation' );
+
+export default ConnectedElevation;

packages/components/src/ui/elevation/index.js

@@ -0,0 +1,2 @@
+export { default as Elevation } from './elevation';
+export * from './use-elevation';

packages/components/src/ui/elevation/stories/index.js

@@ -0,0 +1,40 @@
+/**
+ * External dependencies
+ */
+import { number } from '@storybook/addon-knobs';
+/**
+ * Internal dependencies
+ */
+import { Elevation } from '../index';
+import { View } from '../../view';
+
+export default {
+	component: Elevation,
+	title: 'G2 Components (Experimental)/Elevation',
+};
+
+export const _default = () => {
+	const value = number( 'value', 5 );
+	const hover = number( 'hover', undefined );
+	const focus = number( 'focus', undefined );
+	const active = number( 'active', undefined );
+
+	return (
+		<View
+			css={ {
+				padding: '20vh',
+				position: 'relative',
+				margin: '20vh auto 10vw',
+				maxWidth: 400,
+			} }
+		>
+			<Elevation
+				isInteractive
+				value={ value }
+				hover={ hover }
+				focus={ focus }
+				active={ active }
+			/>
+		</View>
+	);
+};