postcss-tidy-columns v0.4.0

PostCSS Tidy Columns

PostCSS plugin to manage column alignment.

PostCSS Tidy Columns sets an element's width based on a user-defined grid of columns and gaps using calculations based on vw units, which allows for easy vertical alignment of elements.

PostCSS Tidy Columns does not set layout. Positioning elements is your job.

Install

npm install postcss-tidy-columns

Example

require('postcss-tidy-columns')({
	columns: 12,
	gap: '1.25rem',
	edge: '2rem',
	siteMax: '90rem',
});

/* Input example, using the above plugins options */
div {
	tidy-span: 3;
	tidy-offset-left: 2;
}

/* Output example */
div {
	width: calc((((100vw - 2rem * 2) / 12 - 1.1458rem) * 3) + 1.25rem * 2);
	max-width: calc((((90rem - 2rem * 2) / 12 - 1.1458rem) * 3) + 1.25rem * 2);
	margin-left: calc((((100vw - 2rem * 2) / 12 - 1.1458rem) * 2) + 1.25rem * 2);
}

@media (min-width: 90rem) {
	div {
		margin-left: calc((((90rem - 2rem * 2) / 12 - 1.1458rem) * 2) + 1.25rem * 2);
	}
}

Usage

postcss([ require('postcss-tidy-columns') ]);

See PostCSS docs for examples for your environment.

Contents

• Tidy Properties
• Tidy Functions
• Options
• Options Cascade
• Using CSS Custom Properties in setting values

See the Wiki for additional documentation and tips.

Tidy Properties

Span

The tidy-span property specifies the number of columns and adjacent column gaps the element should span. Supports positive and decimal values.

Syntax

tidy-span: <number>;

Offsets

The tidy-offset-left and tidy-offset-right properties specify the number of columns and adjacent column gaps the element's margin should span. Supports positive, negative, and decimal values

Offsets use a siteMax breakpoint, since there's no max-margin CSS property.

Syntax

tidy-offset-left: <number>;
tidy-offset-right: <number>;

Column Shorthand

tidy-column is a shorthand property for setting tidy-offset-left, tidy-span, and tidy-offset-right in one declaration.

Use none to bypass a required value.

Syntax

/* [ <number> | none ] / span && <number> [ / <number> ]? */

tidy-column: 3 / span 2 / 4;
tidy-column: none / span 4 / 1;
tidy-column: 1 / span 4;

Offset Shorthand

tidy-offset is a shorthand property for setting tidy-offset-left and tidy-offset-right in one declaration.

Use none to bypass a required value.

Syntax

/* [ <number> | none ] [ / <number> ]? */

tidy-offset: 3 / 4;
tidy-offset: none / 1;
tidy-offset: 1; /* 1 / none */

Tidy Functions

These functions are provided for incorporating the tidy- properties' output without using the properties. These can be used on their own or nested inside a calc() function, and allow for more control over the declarations added by the plugin.

When using these functions, the siteMax-based static value will not be output. Use the tidy-span-full() and tidy-offset-full() functions to set the static span and offset widths, respectively.

Span Function

tidy-span() and tidy-span-full() functions return the span property's calc() declaration for use in assigning widths.

Syntax

/* property: tidy-span(number) */
/* property: calc(tidy-span(number) expression) */

div {
	width: calc(tidy-span(3) + 4rem);
}

@media (min-width: 75rem) {
	div {
		width: calc(tidy-span-full(3) + 4rem);
	}
}

Offset Function

tidy-offset() and tidy-offset-full() functions return the offset property's calc() declaration for use in positioning.

Syntax

/* property: tidy-offset(number) */
/* property: calc(tidy-offset(number) expression) */

div {
	left: calc(tidy-offset(1) + 2rem);
}

@media (min-width: 75rem) {
	div {
		left: calc(tidy-offset-full(1) + 2rem);
	}
}

Options

As an alternative to the PostCSS JavaScript API, options may also be passed via stylesheet @tidy at-rules.

columns

Declares the number of columns in your design. Supports any positive integer.

CSS Syntax

@tidy columns <number>;

gap

Declares the width of the gap between each column. Supports any positive integer of unit px|em|rem.

CSS Syntax

@tidy gap <length> [ / <boolean> ]?;

See addGap for more about the CSS syntax.

siteMax

Declares the max-width of the site, at which point the site transitions from fluid width to static width. Setting a siteMax value ensures the column and margin widths are correct once the site width is static.

Supports any positive integer of unit px|em|rem.

CSS Syntax

@tidy site-max <length>;

/* Alternatively use the camelCased JavaScript property */
@tidy siteMax <length>;

edge

Set edge to the non-cumulative value of the space between the content and the edge of the page.

Supports any positive integer of unit px|em|rem.

CSS Syntax

@tidy edge <length>;

addGap

Declares whether or not to add a gap-wide margin-right to the columns.

When this is set to true, a :last-of-type rule will be added to reset the margin-right to 0 for the last item.

CSS Syntax

/**
 * Declared as a boolean value after the `gap` value.
 * Must be preceeded by a slash.
 */
@tidy gap <length> / <boolean>;

breakpoints

Use the breakpoints array to configure a grid spec that changes for certain breakpoints.

1. Define the small-screen grid in the root object.
2. Define breakpoints at which the grid spec changes, and any configuration options that will change.

Each breakpoint configuration object must contain a breakpoint (singular) property defining the min-width breakpoint at which the configuration becomes active. There is no CSS syntax for this config option.

The root configuration will cascade through the breakpoints, with each breakpoint's config overriding any changed options. Each breakpoint config will also cascade through to the next larger breakpoint config.

Which means, given the following options...

{
	columns: 9,
	edge: '1rem',
	gap: '0.625rem',
	addGap: true,
	breakpoints: [
		{
			breakpoint: '48rem',
			columns: 12,
			gap: '1rem'
		},
		{
			breakpoint: '64rem',
			edge: '1.25rem',
			addGap: false,
			siteMax: '90rem'
		}
	]
};

... each breakpoint object will essentially end up like this:

{
	breakpoints: [
		{ // small screens
			columns: 9,
			edge: '1rem',
			gap: '0.625rem',
			addGap: true,
		},
		{ // min-width: 48rem
			breakpoint: '48rem',
			columns: 12,
			gap: '1rem'
			edge: '1rem',
			addGap: true,
		},
		{ // min-width: 64rem
			breakpoint: '64rem',
			edge: '1.25rem',
			addGap: false,
			siteMax: '90rem'
			columns: 12,
			gap: '1rem'
		}
	]
};

Caveats

• The breakpoint value must be based on a min-width media query.
• breakpoint values must be in the same units as the media query it's responding to or it will be ignored and use the root config.
• All breakpoints must also be in the same units or it will be ignored and use the root config.
• A media query spanning more than one breakpoint config will be ignored and use the root config. - In the above configuration example, a media query with (min-width: 48rem) and (max-width: 90rem) would match two breakpoint configs and thus use the root config as a fallback.

Options Cascade

Plugin options

Options passed directly to the plugin via the PostCSS JavaScript API.

Global at-rules

Global options are defined via @tidy at-rules outside of any selector blocks. Values declared here take precedence over those passed via the plugin options.

Local at-rules

Local options are defined via @tidy at-rules inside a selector block and are scoped to that rule block. Values declared here take precedence over the global at-rules.

Using CSS Custom Properties in setting values

CSS Custom Proprties are supported in @tidy rules, with the following caveats:

1. Due to the nature of CSS Custom Properties, particularly the inability to use them in media query parmeters, a CSS Custom Property used as the @tidy site-max value will throw an error.
2. The @tidy gap custom property value must only contain its length, and not its boolean addGap portion of the gap shorthand.

See the Tips and Tricks Wiki page for more.