Support custom prop aliases API

cypress/integration/custom-configuration/custom-prop-aliases.test.js

@@ -0,0 +1,16 @@
+describe('Supports custom prop aliases', () => {
+  cy.loadStory(['core'], ['configuration', 'custom-prop-aliases'])
+
+  it('Prop alias with transform', () => {
+    cy.get('#box-one').should('have.css', 'text-align', 'center')
+  })
+
+  it('Prop alias with "transformNumeric"', () => {
+    cy.get('#box-two').should('have.css', 'font-size', '32px')
+    cy.get('#box-three').should('have.css', 'font-size', '20px')
+  })
+
+  it('Prop alias with custom value transformer', () => {
+    //
+  })
+})

examples/Core/Configuration/CustomPropAliases.jsx

@@ -0,0 +1,36 @@
+import React from 'react'
+import Layout, { Box } from 'atomic-layout'
+
+export default class CustomUnit extends React.Component {
+  componentDidMount() {
+    Layout.configure({
+      propAliases: {
+        textAlign: {
+          output: ['text-align'],
+        },
+        fontSize: {
+          output: ['font-size'],
+          transformValue: (value, Layout) => {
+            return Layout.transformNumeric(value)
+          },
+        },
+      },
+    })
+  }
+
+  render() {
+    return (
+      <>
+        <Box id="box-one" textAlign="center">
+          Content
+        </Box>
+        <Box id="box-two" fontSize={2}>
+          Content
+        </Box>
+        <Box id="box-three" fontSize="20px">
+          Content
+        </Box>
+      </>
+    )
+  }
+}

examples/Core/Configuration/CustomUnit.jsx

@@ -3,7 +3,7 @@ import Layout from 'atomic-layout'
 import Notch from '../Rendering/Notch'
 
 export default class CustomUnit extends React.Component {
-  componentWillMount() {
+  componentDidMount() {
     Layout.configure({
       defaultUnit: 'rem',
     })

examples/index.js

@@ -33,10 +33,12 @@ storiesOf('Core|Responsive props', module)
  */
 import ConfigCustomUnit from './Core/Configuration/CustomUnit'
 import ConfigCustomBreakpoints from './Core/Configuration/CustomBreakpoints'
+import ConfigCustomPropAliases from './Core/Configuration/CustomPropAliases'
 
 storiesOf('Core|Configuration', module)
   .add('Custom unit', () => <ConfigCustomUnit />)
   .add('Custom breakpoints', () => <ConfigCustomBreakpoints />)
+  .add('Custom prop aliases', () => <ConfigCustomPropAliases />)
 
 /**
  * Composition

src/Layout.spec.ts

@@ -114,4 +114,34 @@ describe('Layout', () => {
       })
     })
   })
+
+  describe('transformNumeric', () => {
+    describe('suffixes numeric value with measurement unit', () => {
+      it('with default measurement unit', () => {
+        expect(Layout.transformNumeric(5)).toBe('5px')
+      })
+
+      it('with custom measurement unit', () => {
+        Layout.configure({
+          defaultUnit: 'rem',
+        })
+
+        expect(Layout.transformNumeric(3)).toBe('3rem')
+      })
+    })
+
+    it('bypasses string value', () => {
+      expect(Layout.transformNumeric('2vh')).toBe('2vh')
+    })
+
+    it('handles explicit zero as a value and no suffix is attached', () => {
+      expect(Layout.transformNumeric('0')).toBe('0')
+      expect(Layout.transformNumeric(0)).toBe('0')
+    })
+
+    it('returns empty string when no value provided', () => {
+      expect(Layout.transformNumeric()).toBe('')
+      expect(Layout.transformNumeric('')).toBe('')
+    })
+  })
 })

src/Layout.ts

@@ -4,11 +4,14 @@ import defaultOptions, {
   Breakpoints,
   MeasurementUnit,
   BreakpointBehavior,
+  Numeric,
 } from './const/defaultOptions'
+import { PropAliases } from './const/propAliases'
 import invariant from './utils/invariant'
 import warn from './utils/functions/warn'
 
 class Layout {
+  public propAliases: PropAliases = defaultOptions.propAliases
   public defaultUnit: MeasurementUnit = defaultOptions.defaultUnit
   public defaultBehavior: BreakpointBehavior = defaultOptions.defaultBehavior
   public breakpoints: Breakpoints = defaultOptions.breakpoints
@@ -47,14 +50,14 @@ class Layout {
     invariant(
       this.breakpoints.hasOwnProperty(this.defaultBreakpointName),
       `Failed to configure Layout: cannot use "${
-        this.defaultBreakpointName
+      this.defaultBreakpointName
       }" as the default breakpoint (breakpoint not found).`,
     )
 
     invariant(
       this.defaultBreakpointName,
       `Failed to configure Layout: expected "defaultBreakpointName" property set, but got: ${
-        this.defaultBreakpointName
+      this.defaultBreakpointName
       }.`,
     )
 

src/components/MediaQuery.tsx

@@ -1,8 +1,9 @@
 import * as React from 'react'
+import Layout from '@src/Layout'
 import { MediaQuery as MediaQueryParams } from '@const/defaultOptions'
 import { joinQueryList } from '@utils/styles/createMediaQuery'
 import normalizeQuery from '@src/utils/styles/normalizeQuery'
-import transformNumeric from '@utils/math/transformNumeric'
+// import transformNumeric from '@utils/math/transformNumeric'
 import compose from '@src/utils/functions/compose'
 
 interface Props extends MediaQueryParams {
@@ -22,7 +23,7 @@ const createMediaQuery = (queryParams: MediaQueryParams): string => {
        * (min-width: 750) ==> (min-width: 750px)
        */
       const resolvedParamValue = /^\d/.test(String(paramValue))
-        ? transformNumeric(paramValue)
+        ? Layout.transformNumeric(paramValue)
         : paramValue
       return `(${paramName}:${resolvedParamValue})`
     }),
@@ -32,7 +33,9 @@ const createMediaQuery = (queryParams: MediaQueryParams): string => {
 
 const MediaQuery = (props: Props): JSX.Element => {
   const { children, ...queryParams } = props
-  const query = React.useMemo(() => createMediaQuery(queryParams), [queryParams])
+  const query = React.useMemo(() => createMediaQuery(queryParams), [
+    queryParams,
+  ])
   const [matches, setMatches] = React.useState(false)
 
   const handleMediaQueryChange = (

src/const/defaultOptions.ts

@@ -1,3 +1,5 @@
+import propAliases, { PropAliases } from './propAliases'
+
 type AbsoluteUnits = 'cm' | 'mm' | 'in' | 'px' | 'pt' | 'pc'
 type RelativeUnits =
   | '%'
@@ -16,13 +18,15 @@ export type BreakpointBehavior = 'up' | 'down' | 'only'
 export interface Breakpoints {
   [breakpointName: string]: Breakpoint
 }
+
 export interface LayoutOptions {
+  propAliases: PropAliases
   /**
    * Measurement unit that suffixes numeric prop values.
    * @default "px"
    * @example
    * <Box padding={10} />
-   * // "padding: 10px"
+   * @returns "padding: 10px"
    */
   defaultUnit: MeasurementUnit
   /**
@@ -54,11 +58,12 @@ export interface MediaQuery {
 }
 
 export interface Breakpoint extends MediaQuery {
-  /* Index signature for dynamic breakpoint composition */
+  // Index signature for dynamic breakpoint composition
   [propName: string]: any
 }
 
 const defaultOptions: LayoutOptions = {
+  propAliases,
   defaultUnit: 'px',
   defaultBehavior: 'up',
   defaultBreakpointName: 'xs',

src/const/propAliases.spec.tsx

@@ -1,4 +1,6 @@
+import 'jest-dom/extend-expect'
 import React from 'react'
+import Layout from '@src/Layout'
 import propAliases from './propAliases'
 import { Composition } from '..'
 import { render, cleanup, getByTestId } from '@testing-library/react'
@@ -55,12 +57,12 @@ describe('Prop aliases', () => {
       const element = getByTestId(container, 'composition')
 
       /* Assertion */
-      const { props: cssProps, transformValue } = propAliases[propAliasName]
+      const { output, transformValue } = propAliases[propAliasName]
       const expectedValue = transformValue
-        ? transformValue(propValue)
+        ? transformValue(propValue, Layout)
         : propValue
 
-      cssProps.forEach((cssPropName) => {
+      output.forEach((cssPropName) => {
         expect(element).toHaveStyle(`${cssPropName}:${expectedValue}`)
       })
     })