kettanaito / atomic-layout

Build declarative, responsive layouts in React using CSS Grid.

Atomic Layout is a spatial distribution library for React. It uses CSS Grid to define layout areas and render them as React components. This pattern encourages separation of elements and spacing, preventing contextual implementations and boosting maintenance of layouts.

import React from 'react'
import { Composition } from 'atomic-layout'

// Define layout areas: visual representation
// of what composes a layout, detached from
// what components are actually rendered.
const areasMobile = `
  thumbnail
  header
  footer
`

// Declare responsive changes of your areas.
// Operate in two dimensions, remove areas
// or introduce new ones.
const areasTablet = `
  thumbnail header
  thumbnail footer
`

const Card = ({ title, imageUrl, actions }) => (
  <Composition areas={areasMobile} areasMd={areasTablet} gap={20}>
    {/* Get React components based on provided areas */}
    {({ Thumbnail, Header, Footer }) => (
      <React.Fragment>
        <Thumbnail>
          {/* Render anything, including another Composition */}
          <img src={imageUrl} alt={title} />
        </Thumbnail>
        {/* Preserve semantics with polymorphic prop */}
        <Header as="h3">{title}</Header>
        {/* Responsive props: just suffix with a breakpoint name */}
        <Footer padding={10} paddingMd={20}>
          {actions}
        </Footer>
      </React.Fragment>
    )}
  </Composition>
)

export default Card

Atomic Layout is responsive-first. It uses Bootstrap 4 breakpoints by default, which you can always customize for your needs.

Motivation

Modern layout development is about modularity and composition. Following the best practices of Atomic design, we strive toward independent UI units that gradually compose into more meaningful pieces. While the attention paid to units implementation is thorough, we often overlook how to achieve layout composition that scales. It's as if we forget that spacing defines composition.

When it comes to distributing the spacing things get more difficult. First of all, true contextless spacing is hard. To make things worse, all present solutions couple spacing with UI elements, inevitably making small reusable pieces contextful and, thus, hard to maintain.

Atomic Layout helps you to compose your elements by introducing a dedicated spacing layer called Composition. It encourages you to separate concerns between UI elements' visual appearance and spacing between them. With the first-class responsive support at your disposal you can build gorgeous responsive permutations of your elements without leaving the dedicated spacing layer, keeping UI elements contextless and predictable. Embrace the era of a true layout composition!

Implementations

Atomic Layout has multiple implementations depending on the styling solution:

Package name	Latest version	Styling library
atomic-layout		styled-components
@atomic-layout/emotion		@emotion/styled

Documentation

See the Official documentation.

Here are some shortcuts for quick access:

• Motivation
• Getting started
• Responsive props
• Recipes

Examples

Although the examples below use atomic-layout package, they are fully compatible with other styling implementations of the library (i.e. @atomic-layout/emotion).

Basics

Basic composition Combine two UI elements into a single one using Composition.

Responsive props Change a prop's value depending on a breakpoint.

Nested composition Any element can be a composition and a composite at the same time.

Intermediate

Conditional rendering Render or display elements conditionally based on breakpoints.

Custom configuration Configure a default measurement unit, custom breakpoints, and responsive behaviors.

Shorthand media query Use a shorthand query function to declare inline media queries in CSS.

Materials

	Creating layouts that last (React Finland, 2019) Find out the main aspects of a layout's maintainability and why spacing plays a crucial role in it. Learn how to wield layout composition as an actual React component–a missing glue for your elements and design systems. Live demo
	Layout composition as a React component (SurviveJS) Read through the extensive interview about how Atomic layout came to be, how it's different from other solutions, and which practices it encourages.
	The future of layouts (React Vienna, 2018) Watch Artem discussing the biggest obstacle to achieve maintainable layouts, and showcases a way to combine existing technologies to build clean UI implementations using Atomic layout. Live demo Slides

Community

Reach out to us to share an awesome project you're building, or ask a question:

• Reactiflux

Browser support

Atomic Layout's browser support is made by the browser support of underlying technologies the library uses. Pay attention if your project can support CSS Grid to be sure you can use Atomic Layout.

See the Support table for CSS Grid. For Internet Explorer support please read this issue.

Contributing

By contributing to Atomic Layout you shape the way developers create reusable UI.

Please refer to the Contribution guidelines before committing to this project. We are thankful for any kind of contribution you may bring: discussion, issue report, or a pull request.

atomic-layout's Issues

React Native support

What

Suggest to consider React Native support.

Why

Because creating layouts in RN is a hell.

How

• Read if RN supports CSS Grid (it doesn't at the moment)
• Render native components instead of browser tags
• Test on a RN project

Consider memoization for "parseTemplates" calls

What

I suggest to introduce a memoization logic for parseTemplates function call.

Why

• This is the heaviest function in the library, its performance must be ensured
• To ease to components computation process
• To potentially allow updates of template-* prop values due to computation process is memoized

How

1. Research memoization.
2. Add a simple memoize function, or similar.
3. Write unit test for memoize function.

Use "cross-env" for environmental flags

Allow long breakpoint names

What

I suggest to allow long (2+ words) breakpoint names.

Why

At the moment only one word breakpoint names are expected in the prop name parsing algorithm. Having custom breakpoint names is essential for DX.

How

• Adjust prop name parsing algorithm (maybe to use RegExp?)
• Write tests

Write generic "getAreaParams" logic

What

Need to base the logic of utils/getAreaParams function to handle any scenarios of breakpoints (using min/maxHeight, min/maxWidth, resolution, orientation, etc.).

Why

To have a single source of truth for area component media query props composition.

How

1. Setup some graph, analyze what similarities may be highlighted in different breakpoints.
2. Figure out how to handle sibling breakpoints which have different params (one uses minWidth, the next one uses minResolutions). Write a specification on how those are handled.
3. Reduce the complexity level of getAreaParams function.
4. Write tests, if applicable.

---

Branch: https://github.com/kettanaito/atomic-layout/tree/28-generic-breakpoint-concatenation

Improve error handling

What

Error handling must be refined and improved where necessary.

Why

Having meaningful and helpful error messages is a must.

How

• Warn on multiple calls of Layout.configure()
• Referencing non-existing area must not throw, but print a warning

Cleanly handle components not included in grid templates

What

Gracefully handle components that are not included in the current grid template(s)

Why

For example, when using atomic-layout as a top level routing component, not all components will be included in the template, which means that each has to be checked to see if it's defined before it can be used.

<Composition template={router.gridTemplate || `notFound`}>
{({ Page1, Page2, NotFound }) => (
  <>
    {Page1 && (
      <Page1>
        <Page1Component />
      </Page1>
    )}
    {Page2 && (
      <Page2>
        <Page2Component />
      </Page2>
    )}
    {NotFound && (
      <NotFound>
        <NotFoundComponent />
      </NotFound>
    )}
  </>
)}
</Composition>

How

This could more cleanly be describe with a hash of components (indexed by template area)

<Composition template={router.gridTemplate || `notFound`} components={{
  'page1': Page1Component,
  'page2': Page2Component,
  'notFound': NotFoundComponent,
}} />

or by using a more generic Area wrapper

<Composition template={router.gridTemplate || `notFound`}>
  <Area name='page1'>
    <Page1Component />
  </Area>
  <Area name='page2'>
    <Page2Component />
   </Area>
  <Area name='notFound'>
    <NotFoundComponent />
  </Area>
</Composition>

Report bundle check status immediately after library build

What

Suggest to move the order of bundle-size reporting in the CircleCI pipeline.

Why

To receive the build size status faster, without waiting for all the tests to run.

How

• By editing .circleci/config.yml

Handle string values in breakpoint's minWidth/maxWidth

What

Need to parse string values of minWidth and maxWidth of a breakpoint.

Why

It's allowed to use string values (i.e. 25vw), which needs to be handled properly during the breakpoint boundaries subtraction.

How

1. parseFloat()?

Error when running the Getting Started example

What

1. Syntax Error: Unexpected character '​' (7:0)
2. Layout is not defined
3. Element type is invalid: expected a string

Why

1. Invisible characters in the docs example code
2. Layout -> Composition
3. React.Fragment -> Array of children (gatsby gave me react 16.3.2)

Environment

• node vesrion: 8.9.4
• npm version: 6.1.0
• atomic-layout version: 0.3.4
• mac: 10.13.5
• react: 16.3.2

Steps to reproduce

Steps to reproduce the behavior:

1. I used gatsby for boilerplate
2. Copy code snippet from get started page in the docs
3. Mock card components
4. See errors

Expected behavior

See the card example

I also tried https://styled-css-grid.js.org/ I like their api better (the cell approach), but it does not seem to support break points.
Other than that your project looks great! 👍 Good step at making css grid more developer friendly.

Support "min/maxHeight" and "min/maxWidth" prop aliases

Prop aliases to handle unknown aliases

What

I suggest to find some sensible way of handling unknown prop aliases.

Why

I would like to reduce the size of propAliases by excluding the aliases which output properties are identical to the alias itself (i.e. margin, padding, height, width). This would decrease the library size even more.

Create a pull request template

What

Should create a template for pull request.

Why

To improve developer experience and make the contribution process smooth.

How

• Use GitHub pull request template markdown file.

Default "up" behavior is broken

What

Current "up" behavior is broken. Consider this composition:

const templateXs = `A B C`
const templateMd = `A B`

<Composition template={templateXs} templateMd={templateMd} />

The composition for sm breakpoint will render empty component, which is not correct.

Why

This is most likely related to the changed parsing API.

Environment

• atomic-layout version: 0.3.0

Expected behavior

Default "up" behavior is working properly. That implies that the most left provided value is persistent through the breakpoints, unless met more specific right value overwriting it.

Support "component" prop for grid areas

What

Need to add the support for component prop to grid area components.

Why

At the moment all grid areas will render <div> elements. That may not be the desired layout in some cases. For example, sometimes passing a presentational component as the component prop may simplify the layout declaration:

import React from 'react'
import ArticleHeader from './ArticleHeader'

const template = `
  'header'
`

const Article = () => (
<Layout template={template}>
  {({ Header }) => (
    <React.Fragment>
      <Header component={ArticleHeader} />
    </React.Fragment>
  )}
</Layout>
)

export default Article

Bell areas are not wrapped in Placeholder (MediaQuery)

What

Currently, a bell areas are not wrapped in MediaQuery properly, as their shouldAlwaysRender flag returns true.

Why

This is most likely an issue with reduceAreas function.

Glossary

Bell area is an area that is present on the very left breakpoint, then is not present in the middle breakpoint, and present again on the very right breakpoint. This is an example:

const templateMobile = `
  'header actions'
`

const templateMobile = `
  'header'
`

const templateDesktop = `
  'header actions'
`

In the example above, <Actions/> is a bell area.

How

1. Write a proper test that covers this.
2. Investigate and adjust reduceAreas functionality to properly compose bell areas.

Roadmap

• Adjust reduceAreas functionality to cover bell areas
• Write test to ensure the functionality

Parsing of a prop name without breakpoint but with behavior is wrong

What

parsePropName('templateDown') doesn't return proper parsed prop object.

Why

Because of the current RegExp.

Expected behavior

Returns prop name template and down as a behavior.

Lack of indentation in template breaks the Composition component

What

Lack of indentation in template breaks the Composition component

Not working

const template = `
top
bottom
`

Working

const template = `
  top
  bottom
`

Why

Hard coded white space removal

Environment

• All environments

Expected behavior

You dont need to append whitespace to template string

Enhance integration tests to check for "grid-area" and area position

What

Need to enhance integration tests assertion to also test for grid-area property value and area component position on the screen.

Why

When grid-area assignment is broken, grid areas will still be visible, but positioned in the unexpected part of the layout. That is a falsy positive test result, which must be avoided.

How

1. Enhance the assertion function.

Make "template" prop optional

What

I suggest to make template and its derived props optional for Composition component.

Why

As I continue on the marvelous road of learning CSS Grid, I find a lot of scenarios when using templateCols and/or templateRows is sufficient to create a layout. I wouldn't limit the functionality of CSS Grid by artificially forcing template-areas prop.

Specification

1. Composition component can render without template-* props being provided.
2. Composition component can still render with template-* props being provided.
3. Other grid-specific properties affect the composition as they do with the template-based composition.
4. When template-* props are not provided, the children of Composition are usual React components.
5. When template-* props are provided, the children of Composition is a function that accepts generated area components and renders React component.

How

• Make template and its derived props optional.
• When template props are provided, expose function as a children of Composition component
• When `template props are not provided, render children as-is, since there is no benefit of a children function in this case

Support "Only" responsive component

Specification:

• <Only/> is a React component that renders its children responsively, depending on the breakpoint props specified to it.
• The component accepts breakpoint names defined in the Layout options (via Layout.configure()).
• The component can also accept an explicit breakpoint Object, to render on a breakpoint other than the ones specified in the Layout options, when needed.
• The component can be rendered on its own anywhere, and doesn't have to be a child of either of Atomic layout components.

Example:

atomic-layout/examples/only/OnlyExample.jsx

Lines 9 to 32 in 4c7ca5d

	{/* Explicit */}
	<Only for="sm">
	<Square id="first">First</Square>
	</Only>
	{/* High-pass */}
	<Only to="md">
	<Square id="second">Second</Square>
	</Only>
	{/* Low-pass */}
	<Only from="lg">
	<Square id="third">Third</Square>
	</Only>
	{/* Bell */}
	<Only from="sm" to="lg">
	<Square id="fourth">Fourth</Square>
	</Only>
	{/* Notch */}
	<Only except from="md" to="lg">
	<Square id="fifth">Fifth</Square>
	</Only>

Roadmap

• Define the name
• API of inclusive/bell behavior

Handle conditional grid areas

What

Need to handle conditional grid areas.

Why

Consider:

const templateMobile = `
  'text'
`

const templateTablet = `
  'text subtext'
`

<Layout
  template={templateMobile}
  templateSm={templateTablet}>
  {({ Text, Subtext }) => (...)}
</Layout>

Using this example the Layout will throw when trying to render Subtext on mobile (subtext area is not preset in the template, therefore, its component is not created).

How

1. Maybe creating an "empty" placeholder component for the areas which are not defined:

const Placeholder = () => null

2. Maybe analyze each template to know the fullest list of areas, and create them all, no matter the screen size.

Roadmap

• Implement conditional grid areas
• Break down parseTemplateString composite function into smaller pure functions
• Write unit tests

Allow to set default measurement unit

What

Need to provide an interface which will allow a developer to set a default measurement unit of his preference.

Why

At the moment the default measurement unit is rem. While that bears the most sense when building layouts to me, others can share different opinions and have different project requirements. It's not a good idea to force any behavior in general.

How

1. Integrate a defaultUnit property to the options Object passed to the library.
2. Grab the value of that option property and reuse it within the measurement computation.

Setup CI

Straightforward. CI is a must.

Improve contributor experience

What

Need to focus on improving contributor experience.

Why

To create a clear process of contributing to Atomic layout, in order to get more contributors and make the contribution process as pleasing as it gets <3

How

• Add and configure eslint
• Integrate eslint check on pre-commit hook
• Integrate unit tests execution on pre-push hook
• Consider test coverage monitoring. Integrate automatic test coverage report into pull request hook in GitHub
• Consider bundle size monitoring. Integrate automatic report on bundle size change in the pull request hooks via GitHub
• Write contribution guidelines, include them in the official documentation
• Consider separate pull request templates for bugfixes and features (I don't think this is necessary at the moment)
• Refine GitHub labels
• Refine GitHub milestones

Make area components behave as flexbox

What

I suggest to make generated area components to have display: flex by default.

Why

This will allow to control their children behavior using the flexbox prop aliases without explicitly setting its display, or having to nest composition/box just for alignment matter.

How

1. Set display: flex on the generated area component.
2. Conduct testing of its behavior.

Specification

1. Each generated area components behave as flexbox by default.
2. Area components can be displayed in two variants:
   • default, flex
   • inline: true, inline-flex
3. Area components support all prop aliases supported by flexbox (align, justifyItems, place, etc.).

ElementQuery

What

Need to consider Element Queries non-standard feature.

Why

That is a brand new look at the components and their responsive behavior. I believe that in the conjuncture with the traditional media queries this could allow to create immersive responsive experiences.

How

1. CSS Element Queries
2. Alternative

---

Specification

See the Element Query API proposal.

Make flexbox an explicit behavior on Box

Why

Enforcing all area components behave like flex results into broken layouts by default.

Environment

• atomic-layout version: 0.3.8

Expected behavior

Flex behavior doesn't interfere with the existing layouts.

How

1. Turn off flexbox display by default, make it parametric with the explicit prop (i.e. flex).
2. Set flex-direction: column by default. However, this, most likely, will not eliminate the issue.

Add lint-staged

What

Suggest to add lint-staged package.

Why

To have hooks on the files added to the commit only.

Check "behavior:down" in the area breakpoint algorithm

What

Conduct a check and add tests to ensure behavior:down areas are working properly.

Roadmap

• Investigate
• (Optional) Fix
• Add tests

Set default breakpoints's measurement unit to use explicit "px" strings

What

I suggest to list default breakpoints' values as explicit unit strings.

Why

Right now it will take the defaultUnit. So if you set default unit to rem, numeric values in default breakpoint definitions use rem as their suffix.

Reuse Box (common model) for Composition render

What

Box and Composition components (as well as generated React components) behave very simiarly, they can use a generic component in their render.

Why

Reusing functionality is good.

How

• Try to reuse Box
• If not, create a generic model and use it for common components (Box, Composition, generated area components)

Allow custom breakpoints

What

Need to allow custom breakpoints to be used with the Atomic layout.

Why

Having custom breakpoints grants additional flexibility and customization when using Atomi layout.

For example, at the moment Bootstrap's grid breakpoints are used as default breakpoints. This influences the way responsive props are written:

<Layout gutterMd={2} gutterLg={3} />

With custom breakpoints, developers can strive toward explicit semantics dictated by their projects:

<Layout gutterTablet={2} gutterDesktop={3} />

How

• Design the interface to accepts custom breakpoints just once.
• Propagate custom breakpoints to the usage points.
• Write tests.

Support behavior for breakpoint-less template declarations

What

I suggest to consider behavior support for template declarations that do not have a preceding breakpoint name (i.e. templateDown or templateOnly).

Why

Current RegExp won't match the template prop names enlisted above. There must be a way to use explicit behaviors even for breakpoint-less template declarations, especially since there is a defaultBreakpointName param, which excludes the necessity of specifying breakpoint name every time.

How

• Adjust the regular expression
• Add unit tests

[RFC] Pluggable styling API

What

I propose to establishing a support for different CSS-in-JS libraries to help developers take benefits of Atomic Layout using their favorite styling solution.

Why

• The library operates on CSS properties Object, which can be computed into string (when needed), and be compliant with about any modern CiJ solution

Implementation

To enable such support it has been decided to convert the library to a monorepo that consist of the following parts:

• core library (@atomic-layout/core, responsible for media queries calculation, areas parsing, parametric components generation without attachment to any specific styling/rendering solution)
• rendering libraries (i.e. @atomic-layout/emotion)

All rendering libraries would list @atomic-layout/core as a dependency and utilize functions and types the core library exports.

Usage

To use Atomic Layout with another styling solution (implying that such solution is supported) import the respective @atomic-layout/X package and use it with the same API described in the documentation:

import React from 'react'
import { Composition } from '@atomic-layout/emotion'

const MyComponent = () => (
  <Composition templateCols="250px 1fr">
    <span>Emotion support</span>
    <span>Example</span>
  </Composition>
)

Don't minimise the npm published content

What

Deploy lib to npm without minification

Why

Because errors are not reported correctly and we cannot easily make use of internal functions.

How

Remove minification build step for npm publish

Allow string values for spacial properties

What

Allow string values to be passed for spacial props (i.e.height, width).

Why

To allow to set vw and px in case of necessity for that properties. By default, numbers passed to spacial properties represent rem units.

Consider "react-responsive" optimization

What

Maybe it's worth looking into optimizing "react-responsive" package built-in into the library.

Why

react-responsive takes almost a half of the library's bundle size. It's always good to ship a smaller package, that evaluates and runs faster.

How

If react-responsive allows es/src imports, those can be included and processed via library's webpack. This can improve the bundle size via tree shaking, for example, as Atomic layout doesn't utilize all features of react-responsive.

Alternatively, can do a PoC to include a custom responsive utility, covering only the required aspects.

Increase test coverage

What

Need to increase code coverage up to 100%.

Why

To have our code covered with tests, of course. And also because 99% coverage is simply unacceptable.

How

• See Coveralls coverage report to know the uncovered modules

Support custom options

Relates to #6 and #4.

What

Need to implement a custom options support.

Why

In order to customize things like measurement units, breakpoints, and other.

How

• Think of an API
• Give it some PoC
• Polish and refine
• Write some tests
• Release

Integration tests

What

Need to setup and write integration tests.

Why

Atomic layout contributes to the end layout (UI) of the application. Its contribution needs to be tested to ensure it works as expected.

How

1. Pick the technology (strongly suggest Cypress)
2. Configure the technology.
3. Write integration tests.

Tests roadmap

• Ensures "up" default behavior (x x x)
• Ensures inclusive behavior (0 x 0)
• Ensures bell behavior (x 0 x)
• Ensures responsive props (incl. all behaviors of props) (#23)
• Ensures composition (nested <Composition/>)
• Ensure custom breakpoint names
• Ensure custom measurement unit

Provide developer-friendly error messages

What

Need to provide proper error handling and error messages.

Why

Right now any error results into broken client build. That is unacceptable.

How

• Forbid calling Layout.configure() without options
• Forbid configuring Layout without breakpoints set
• Forbid setting defaultBreakpointName to the name of non-existing breakpoint
• Handle undefined Composition.props.template
• Handle invalid value of Composition.props.template (not wrapped in quotes)
• Handle . as the grid area name (#5)
• Handle trying to render area which is not included in the template definition

Extend breakpoint params

What

I suggest to extend a breakpoint params to include more properties rather than just from and to.

Why

This will allow to craft completely custom breakpoints, i.e. the ones dependant on the screen resolution or device orientation.

How

• Remap from to minWidth and to to maxWidth.
• Implement universal print function which will handle a breakpoint's props.
• Adjust the existing logic to correspond to the API changes.

No default breakpoint for custom breakpoints

What

Layout is broken when using custom breakpoints.

Why

When provided custom breakpoints via Layout.configure(), there is no logic which sets a breakpoint as the default one.

Currently xs is a fallback value for the cases when no breakpoint is specified. However, when such breakpoint name doesn't exist, breakpoint becomes undefined, causing a hell of errors.

Environment

• atomic-layout version: 0.3.1

Steps to reproduce

Steps to reproduce the behavior:

1. Setup custom breakpoints via Layout.configure()
2. Declare any layout composition.
3. See it broken.

Expected behavior

There must be a logic to define and use the default breakpoint.

Style props given an undefined value are output as 'undefined' in css

What

<Composition templateCols={undefined} />

will output

grid-template-columns: undefined;

Why

not checking for undefined values

Expected behavior

css attributes for props with undefined or null values should not be output

Handle "." (dot) as the grid area name

What

Need to handle . character which is supported by CSS Grid spec.

Why

In order to cover feature which is in spec, in case it needs to be handled from React side.

How

1. Refine what dot stands for in grid-template-areas. There is a fair chance that we need not to handle it in any way. If that is a placeholder to achieve different gutter (gap) between different grid areas, this can be done via explicit spacing props (margin/padding) assigned directly to area components as props.
2. If it's a placeholder, it can be handled by rendering a <Placeholder/> component at its place.

"postinstall" hook attempts webpack installation

What

After introducing a postinstallhook, installing of a library attempts to build it immediately afterward. Since the end consumer may not have a proper tools to build, this attempt is rather ridiculous.

Steps to reproduce

1. Install the library from NPM: npm install atomic-layout

Expected behavior

Library is built only after it is being cloned. Alternatively, remove this logic completely, and provide a comment in the contribution guidelines that a developer must first build the library.

Tests for SSR

What

Add integration tests for SSR of the components rendered using Atomic layout.

Why

SSR support is a crucial part of any implementation. Since we use react-responsive for conditional areas rendering, I believe that SSR should be supported out of the box. The tests are needed regardless.

How

ReactDOMServer.renderToString(<Component/>)

Assert the output, or use a snapshot to assert it.

Add tests for prop aliases

What

Need to add test cases for prop aliases functionality.

Why

To ensure all prop aliases are assigned properly in the generated CSS properties.

Export GitBook docs to repository

Self-descriptive.