components: Add useCx (#33172)

* components: Add useCx

* Add tests

* Add JSDoc

* Add story for useCx

packages/components/package.json

@@ -34,6 +34,7 @@
  "@emotion/css": "^11.1.3",
  "@emotion/react": "^11.1.5",
  "@emotion/styled": "^11.3.0",
+ "@emotion/utils": "1.0.0",
  "@wordpress/a11y": "file:../a11y",
  "@wordpress/compose": "file:../compose",
  "@wordpress/date": "file:../date",

packages/components/src/utils/hooks/index.js

@@ -2,3 +2,4 @@ export { default as useControlledState } from './use-controlled-state';
 export { default as useJumpStep } from './use-jump-step';
 export { default as useUpdateEffect } from './use-update-effect';
 export { useControlledValue } from './use-controlled-value';
+export { useCx } from './use-cx';

packages/components/src/utils/hooks/stories/use-cx.js

@@ -0,0 +1,79 @@
+/**
+ * Internal dependencies
+ */
+import { useCx } from '..';
+import StyleProvider from '../../../style-provider';
+
+/**
+ * WordPress dependencies
+ */
+import { useState, createPortal } from '@wordpress/element';
+/**
+ * External dependencies
+ */
+import { css } from '@emotion/react';
+
+export default {
+ title: 'Components (Experimental)/useCx',
+};
+
+const IFrame = ( { children } ) => {
+ const [ iframeDocument, setIframeDocument ] = useState();
+
+ const handleRef = ( node ) => {
+ if ( ! node ) {
+ return null;
+ }
+
+ function setIfReady() {
+ const { contentDocument } = node;
+ const { readyState } = contentDocument;
+
+ if ( readyState !== 'interactive' && readyState !== 'complete' ) {
+ return false;
+ }
+
+ setIframeDocument( contentDocument );
+ }
+
+ if ( setIfReady() ) {
+ return;
+ }
+
+ node.addEventListener( 'load', () => {
+ // iframe isn't immediately ready in Firefox
+ setIfReady();
+ } );
+ };
+
+ return (
+ <iframe ref={ handleRef } title="use-cx-test-frame">
+ { iframeDocument &&
+ createPortal(
+ <StyleProvider document={ iframeDocument }>
+ { children }
+ </StyleProvider>,
+ iframeDocument.body
+ ) }
+ </iframe>
+ );
+};
+
+const Example = ( { args, children } ) => {
+ const cx = useCx();
+ const classes = cx( ...args );
+ return <span className={ classes }>{ children }</span>;
+};
+
+export const _default = () => {
+ const redText = css`
+ color: red;
+ `;
+ return (
+ <IFrame>
+ <Example args={ [ redText ] }>
+ This text is inside an iframe and is red!
+ </Example>
+ </IFrame>
+ );
+};

packages/components/src/utils/hooks/test/use-cx.js

@@ -0,0 +1,64 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import { cx as innerCx } from '@emotion/css';
+import { insertStyles } from '@emotion/utils';
+import { render } from '@testing-library/react';
+import { css, CacheProvider } from '@emotion/react';
+import createCache from '@emotion/cache';
+
+/**
+ * Internal dependencies
+ */
+import { useCx } from '..';
+
+jest.mock( '@emotion/css', () => ( {
+ cx: jest.fn(),
+} ) );
+
+jest.mock( '@emotion/utils', () => ( {
+ insertStyles: jest.fn(),
+} ) );
+
+function Example( { args } ) {
+ const cx = useCx();
+
+ return <div className={ cx( ...args ) } />;
+}
+
+describe( 'useCx', () => {
+ it( 'should call cx with the built style name and pass serialized styles to insertStyles', () => {
+ const serializedStyle = css`
+ color: red;
+ `;
+ const className = 'component-example';
+ const object = {
+ 'component-example-focused': true,
+ };
+
+ const key = 'test-cache-key';
+
+ const container = document.createElement( 'head' );
+
+ const cache = createCache( { container, key } );
+
+ render(
+ <CacheProvider value={ cache }>
+ <Example args={ [ className, serializedStyle, object ] } />
+ </CacheProvider>
+ );
+
+ expect( innerCx ).toHaveBeenCalledWith(
+ className,
+ `${ key }-${ serializedStyle.name }`,
+ object
+ );
+
+ expect( insertStyles ).toHaveBeenCalledWith(
+ cache,
+ serializedStyle,
+ false
+ );
+ } );
+} );

packages/components/src/utils/hooks/use-cx.ts

@@ -0,0 +1,65 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { Context } from 'react';
+import { CacheProvider, EmotionCache } from '@emotion/react';
+import type { SerializedStyles } from '@emotion/serialize';
+import { insertStyles } from '@emotion/utils';
+// eslint-disable-next-line no-restricted-imports
+import { cx as innerCx, ClassNamesArg } from '@emotion/css';
+
+/**
+ * WordPress dependencies
+ */
+import { useContext, useCallback } from '@wordpress/element';
+
+// @ts-ignore Private property
+const EmotionCacheContext: Context< EmotionCache > = CacheProvider._context;
+
+const useEmotionCacheContext = () => useContext( EmotionCacheContext );
+
+const isSerializedStyles = ( o: any ): o is SerializedStyles =>
+ [ 'name', 'styles' ].every( ( p ) => typeof o[ p ] !== 'undefined' );
+
+/**
+ * Retrieve a `cx` function that knows how to handle `SerializedStyles`
+ * returned by the `@emotion/react` `css` function in addition to what
+ * `cx` normally knows how to handle. It also hooks into the Emotion
+ * Cache, allowing `css` calls to work inside iframes.
+ *
+ * @example
+ * import { css } from '@emotion/react';
+ *
+ * const styles = css`
+ * color: red
+ * `;
+ *
+ * function RedText( { className, ...props } ) {
+ * const cx = useCx();
+ *
+ * const classes = cx(styles, className);
+ *
+ * return <span className={classes} {...props} />;
+ * }
+ */
+export const useCx = () => {
+ const cache = useEmotionCacheContext();
+
+ const cx = useCallback(
+ ( ...classNames: ( ClassNamesArg | SerializedStyles )[] ) => {
+ return innerCx(
+ ...classNames.map( ( arg ) => {
+ if ( isSerializedStyles( arg ) ) {
+ insertStyles( cache, arg, false );
+ return `${ cache.key }-${ arg.name }`;
+ }
+ return arg;
+ } )
+ );
+ },
+ [ cache ]
+ );
+
+ return cx;
+};