@penskemediacorp/larva-css 1.10.0-alpha.0 → 1.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Penske Media Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,84 +1,222 @@
 # Larva CSS
 
-This package contains Larva's base CSS, CSS algorithms, utlities, and CSS for JS patterns from larva-js.
+This package contains Larva's base CSS, CSS algorithms, utlities, and CSS for JS patterns from larva-js. Design-related utilities e.g. typography, spacing, and color, are generated according to configuration in [larva-tokens](https://github.com/penske-media-corp/pmc-larva/tree/master/packages/larva-tokens).
 
-## Usage
+## Overview of Functionality
+
+This package provides the source files for the larva.css stylesheet. They are built together and available as larva.css from the @penskemediacorp/larva package, but are available in chunks from this repository in order to support project-level additions to the library.
+
+CSS rulesets are provided in a variety of ways. Many utilities, for example, are generated by iterating over design tokens provided in the SCSS map from larva-tokens, while other rules, such as flex-related utilities or generic styling resets, are added statically since their values are not controlled by tokens. Still others, specifically CSS algorithms, or rulesets that are more complicated than single declarations, are generated by SCSS mixins available in larva-scss (`a-grid`, `a-crop`), or are generated from a Node script (`a-font` - see below for details).
+
+The CSS is ordered intentionally, following the ideology of low specificity and adherence to the cascade via layering similar to [ITCSS](https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/).
+
+Contribution to this repository is relatively infrequent, and will genereally be for the purposes of increasing the capability of the library.
+
+## Development Setup
+
+1. Clone this repository and follow the root README setup instructions.
+2. Make changes to this package, paying careful attention to where you are adding CSS, and ensuring it aligns with existing conventions.
+3. From the root of this repo, run `npm run prod:scss`
+
+Note: For more immediate feedback during development, it is possible to run `npm run dev` in this package, and `npm run dev:scss` from the root.
+
+## Using larva-css in Projects
+
+The easiest way to access the contents of larva-css is by using the built larva.css that is available in the package @penskemediacorp/larva. However, it is possible to use larva-css on its own.
+
+First, install the package:
 
 ```
 npm install @penskemediacorp/larva-css --save
 ```
 
-Then include the CSS from @penskemediacorp/larva-css/build/css in your asset pipeline. Make sure that the CSS files containing `inline` and `async` are loaded accordingly.
+Then, using the below details, determine how to load larva-css in your project.
+
+### Loading larva-css into your project's build
+
+larva-css files can be accessed as CSS directly by linking the stylesheets available in the build directory, but the current recommended approach is to load them into a local project build and output a single file.
+
+#### Option 1: Without project-level utility generation (simple)
+
+In your local build, inlcude these files into your main stylesheet:
+
+```language:scss
+// larva.scss => larva.css
+@import '@penskemediacorp/larva-css/build/css/generic.common.inline';
+@import '@penskemediacorp/larva-css/build/css/algorithms.common.inline';
+@import '@penskemediacorp/larva-css/build/css/algorithms.common.async';
+@import '@penskemediacorp/larva-css/build/css/utilities.common.inline';
+@import '@penskemediacorp/larva-css/build/css/utilities.common.async';
+@import '@penskemediacorp/larva-css/build/css/js.common.inline';
+
+```
+
+If you are splitting inline CSS, you can load inline CSS separately by including the following in a file that will be inlined:
+
+```language:scss
+// larva-inline.scss => larva-inline.css
+@import '@penskemediacorp/larva-css/build/css/generic.inline';
+@import '@penskemediacorp/larva-css/build/css/algorithms.inline';
+@import '@penskemediacorp/larva-css/build/css/utilities.inline';
+@import '@penskemediacorp/larva-css/build/css/js.inline';
+```
+
+Note that at present, there are no js or generic files for async CSS from larva-css.
+#### Option 2: With project-level utilities (complex, not recommended)
+
+This approach is not recommended because accrues technical debt, but it also indicates the areas where the design system is not supporting designs requirements (and vice versa). Generally speaking, this approach allows a project to build the larva.css stylesheet locally and provides areas to plug in additional functionality while maintaining the same, strict architecture.
+
+Prerequisites to this approach:
+
+1. Your project is using the `larva` binary for its build step.
+2. Your project includes a CSS architecture and directory structure that matches that of [pmc-spark/assets](https://bitbucket.org/penskemediacorp/pmc-spark/src/master/assets/).
+
+Include the source .scss files from this repository in your top-level common stylesheet in assets/entries/:
+
+In all of the following, replace `default` with the brand name containing tokens.
+
+```language:scss
+// common.async.scss
+@import '@penskemediacorp/larva-tokens/build/default.custom-properties';
+
+@import '@penskemediacorp/larva-css/src/01-generic/*.scss';
+@import '01-generic/*.common.*.scss';
+
+@import '@penskemediacorp/larva-css/src/02-algorithms/**/*.scss';
+@import '02-algorithms/*.common.*.scss';
+
+@import '@penskemediacorp/larva-css/src/03-utilities/*.scss';
+@import '03-utilities/*.common.*.scss';
+
+@import '@penskemediacorp/larva-css/src/04-js/*.scss';
+@import '04-js/*.common.*.scss';
+```
+
+In a corresponding stylesheet for inline CSS, include only the .inline.scss extensions.
+
+```language:scss
+// common.inline.scss
+@import '@penskemediacorp/larva-tokens/build/default.custom-properties';
 
-## Concepts
+@import '@penskemediacorp/larva-css/src/01-generic/*.inline.scss';
+@import '01-generic/*.common.inline.scss';
 
-### "Atomic" or "Functional" CSS
+@import '@penskemediacorp/larva-css/src/02-algorithms/**/*.inline.scss';
+@import '02-algorithms/*.common.inline.scss';
 
-Coming soon!
+@import '@penskemediacorp/larva-css/src/03-utilities/*.inline.scss';
+@import '03-utilities/*.common.inline.scss';
 
-### Removing the Burden of Naming
+@import '@penskemediacorp/larva-css/src/04-js/*.inline.scss';
+@import '04-js/*.common.inline.scss';
+```
 
-Unless you are authoring a CSS algorithm, you should not have to name a new class.
+Next, create a file for project-level tokens in in assets/src/scss/00-tools/tokens.scss that contains the following:
 
-### Cascading and Specificity
+```
+@import '@penskemediacorp/larva-tokens/build/default.map.scss';
 
-Directories are ordered according to the cascading of styles, inspired by ITCSS. Generic CSS will almost always be overridden, so it is first. Unless selector specificty says otherwise (e.g. `a-space-children` or the image in `a-crop`), CSS algorithms should be overridden by utilities. The CSS related to JS interactivity comes last because it should be the most important in the cascade.
+$local-tokens: (
+	'font-size-12': pmc-rem(12),
+	'opacity-075': 0.75,
+);
 
-## Terminology
+$TOKENS-MAP: map-merge( $default-map, $local-tokens );
+```
 
-*Generic* styles are any basic reset styles, usually applied to general elements. Larva does not use a formal reset like Normalize, rather, any initial property values are overridden in this directory as needed. For example, removing margins from headings and adding box-sizing: border-box to all elements.
+And in assets/src/scss/setup.scss, import the tokens:
+```
+@import '00-tools/tokens.scss';
+```
+
+Be sure to `@import 'setup'` at the top of all of your local utility files. Font size is already generated from the larva-css repo, but opacity is not.
 
-A *utility* is a single* declaration ruleset that is named according to the declaration and prefixed with a `u-*`. These sometimes come from SCSS generators, but many are authored by hand. A few examples (namespaced with pmc-* to indicate they come from this repository):
+If a property is **not** generated from larva-css, you can iterate over the local tokens map with the following Sass:
 
-* pmc-u-display-block
-* pmc-u-color-brand-primary
-* pmc-u-margin-tb-1@tablet
+```
+// Example: u-opacity.common.inline.scss
+@import 'setup';
 
-\* The only time a utility would have more than one declaration is for margin and padding where top/bottom and right/left values can be in the same ruleset.
+@each $token, $value in $TOKENS-MAP {
+	$token-str: quote( $token );
 
-An *algorithm* is a more involved ruleset or set of rulesets that accomplished a specific styling goal that is not reasonable to accomplish with utilties, and generally makes use of browser algorithms or familiar CSS programming patterns. A few examples:
+	@if str-index( $token-str, 'opacity' ) {
+		.u-#{$token} {
+			opacity: $value;
+		}
 
-* pmc-a-space-children - utilized the owl selector pattern to apply space between child elements.
-* pmc-a-glue - an algorithm for "glueing" one element onto another with absolute positioning.
-* pmc-a-unstyle-list – a straightforward set of declarations that remove basic list styling.
+		// If you would like to generate a hover selector,
+		// that could happen here, but media queries need
+		// to be in an additional loops to maintain the cascade
+
+	}
+}
+
+//
+// Media Queries
+//
+
+
+@include pmc-breakpoint( desktop ) {
+
+	@each $token, $value in $TOKENS-MAP {
+		$token-str: quote( $token );
+
+		@if str-index( $token-str, 'opacity' ) {
+			.u-#{$token}\@desktop {
+				opacity: $value;
+			}
+		}
+	}
+
+}
+
+@include pmc-breakpoint( desktop-xl ) {
+
+	@each $token, $value in $TOKENS-MAP {
+		$token-str: quote( $token );
+
+		@if str-index( $token-str, 'opacity' ) {
+			.u-#{$token}\@desktop-xl {
+				opacity: $value;
+			}
+		}
+	}
+
+}
+
+```
 
-The *js* directory contains CSS corresponding to interactivity from larva-js. These styles could be kept alongside the JS, but in order to minimize build tool dependencies, there are kept here, in the larva-css package.
+Refer to the larva-css source files in larva-css/src and in the local Larva server, navigate to /css to see available classes.
 
-## Naming SCSS Files
+## Things to Know
 
-The SCSS file should be named according to the chunk it will be included in when used in an actual product, and whether it should be loaded asynchronously or inline. The formular for naming a file:
+### The .lrv namespace
 
-`{a|u|js}-{baseName}.{chunkName}.{inline|async}.scss`
+CSS originating from larva-css .scss files contain a .lrv- namespace. Local project CSS should only contain an `a-`, `u-`, or `js-` namespace.
 
-Example, full file names:
+### Utility Naming
 
-* u-background.common.async.scss
-* u-font-size.single.async.scss
-* a-gradient-after.common.async.scss
-* a-archive-grid.archive.inline.scss
-* js-MobileHeightToggle.common.async.scss
+Utilities that are generated from larva-tokens, are named as follows:
 
-### Namespace {a|u|js}
+`.lrv-u-{$token-name}`
 
-- a, for algorithm
-- u, for utility
-- js, styling paired with a JS pattern
-- No namespace for generic or reset styles
+For `spacing-XX` tokens, they are named:
 
-### baseName
+`.lrv-u-margin-{l|r|t|b|lr|tb|a}-{$size}`
 
-The baseName of a pattern is the consistent name that is included before all responsive suffixes and BEM elements or modifiers.
+Where, if the token was `spacing-1`, the utility would be `lrv-u-margin-l-1`.
 
-For example, `a-article-grid` could contain `a-article-grid__sidebar` or `a-article-grid--3col`, but the name of the file only contains a-article-grid.
+### Algorithms
 
-### chunkName
+Algorithms are presentationally named CSS patterns that provide functionality difficult or impossible to accomplish with utilities, or where abstractions are useful. Examples are aspect ratio cropping, CSS grid with flex box fallbacks, and SVG icons with `::before` and `::after`.
 
-The name of the chunk where this algorithm should be included. Most algorithms will be common, but there will certainly be cases when algorithms are written for specifc projects that may have their own chunk naming convention. When naming chunks in a WordPress theme, they should map directly 1 to 1 with the queried template where the CSS is equeued or inlined.
+Many of the variations for algorithms are generated with mixins from `larva-scss`, but this is slated to be deprecated in favor of Node scripts in this repository.
 
-### Async or Inline
+#### `.lrv-a-font` Generation
 
-These terms refer to whether or not the algorithm should be included in inlined, or "critical CSS", or in a file loaded asynchronously.
+The `.lrv-a-font` algorithm handles the styling for typography styles that are included in a style guide. Each property value and selector is generated according to data from `larva-tokens`. The SCSS itself is generated from a Node script in this package that is incoporated into the `larva-css` build.
 
-inline should be used for CSS that is applied to elements that are both "above the fold" and contain properties that come into play at the layout phase in rendering. In other words, they are crucial for the first paint of the page. Examples are any properties part of the box model, positioning, layout APIs like Grid and Flexbox, font sizing, and more.
+### JS-related CSS
 
-async should be used for CSS that is not critical to the first paint i.e. to making the page content readable, and that apply during the paint and composite phases of rendering. These are properties like color, background, transition, and box-shadow.
+The SCSS files inside 04-js should be imported directly into a local project build, other than js-MobileHeightToggle which is added to the js.common.inline chunk here.

package/__tests__/fixtures/expected.js

@@ -0,0 +1,29 @@
+module.exports = {
+	ruleset: `
+.lrv-a-font-primary-xxl {
+	// Define this token locally; it can be defined via larva-tokens, if needed in the future.
+	--font-family: var( --font-family-primary );
+
+	font-family: var( --font-family );
+	font-size: var( --primary-xxl-font-size-mobile );
+	line-height: var( --primary-xxl-line-height-mobile );
+	letter-spacing: var( --primary-xxl-letter-spacing-mobile );
+	font-weight: var( --primary-xxl-font-weight-mobile );
+	font-style: var( --primary-xxl-font-style-mobile );
+
+	@media (min-width: $screen-desktop) {
+		font-size: var( --primary-xxl-font-size-desktop );
+		line-height: var( --primary-xxl-line-height-desktop );
+		letter-spacing: var( --primary-xxl-letter-spacing-desktop );
+		font-weight: var( --primary-xxl-font-weight-desktop );
+		font-style: var( --primary-xxl-font-style-desktop );
+	}
+	@media (min-width: $screen-desktop-xl) {
+		font-size: var( --primary-xxl-font-size-desktop-xl );
+		line-height: var( --primary-xxl-line-height-desktop-xl );
+		letter-spacing: var( --primary-xxl-letter-spacing-desktop-xl );
+		font-weight: var( --primary-xxl-font-weight-desktop-xl );
+		font-style: var( --primary-xxl-font-style-desktop-xl );
+	}
+}\n`,
+};

package/__tests__/lib/generators.test.js

@@ -0,0 +1,11 @@
+const { generate } = require( '../../lib/generators' );
+
+const expected = require( '../fixtures/expected' );
+
+describe( 'A-Font Generator', () => {
+	it( 'should output a CSS ruleset containing a-font CSS', () => {
+		const output = generate( [ 'lrv-a-font-primary-xxl' ] );
+
+		expect( output ).toEqual( expected.ruleset );
+	} );
+} );

package/build/css/algorithms.common.async.css

@@ -1,36 +1,4 @@
-@media (min-width: 48rem) {
-  .pmc-a-hover-dropup\@tablet {
-    position: relative;
-    min-width: 14rem; }
-  .pmc-a-hover-dropup-trigger\@tablet {
-    cursor: pointer; }
-  .pmc-a-hover-dropup-target\@tablet {
-    width: 100%;
-    visibility: hidden;
-    opacity: 0;
-    position: absolute;
-    width: 100%;
-    z-index: 2;
-    bottom: 100%;
-    left: 0;
-    overflow-y: scroll;
-    max-height: 8.438rem; }
-  .pmc-a-hover-dropup\@tablet:hover .pmc-a-hover-dropup-target\@tablet,
-  .pmc-a-hover-dropup\@tablet:focus .pmc-a-hover-dropup-target\@tablet {
-    visibility: visible;
-    opacity: 1; }
-  .pmc-a-hover-dropup\@tablet:hover .a-icon-arrow-down::after,
-  .pmc-a-hover-dropup\@tablet:focus .a-icon-arrow-down {
-    --a-icon-transform: rotate(180deg); } }
-
-@media (min-width: 48rem) {
-  .a-icon-after-remove\@tablet::after {
-    display: none; } }
-
-.a-icon-invert {
-  --a-icon-filter: invert(1); }
-
-.pmc-a-unstyle-link,
-.pmc-a-unstyle-link:hover {
-  color: currentColor;
-  text-decoration: none; }
+@media(min-width: 48rem){.lrv-a-hover-dropup\@tablet{position:relative;min-width:14rem}.lrv-a-hover-dropup-trigger\@tablet{cursor:pointer}.lrv-a-hover-dropup-target\@tablet{width:100%;visibility:hidden;opacity:0;position:absolute;width:100%;z-index:2;bottom:100%;left:0;overflow-y:scroll;max-height:8.438rem}.lrv-a-hover-dropup\@tablet:hover .lrv-a-hover-dropup-target\@tablet,.lrv-a-hover-dropup\@tablet:focus .lrv-a-hover-dropup-target\@tablet{visibility:visible;opacity:1}.lrv-a-hover-dropup\@tablet:hover .lrv-a-icon-arrow-down::after,.lrv-a-hover-dropup\@tablet:focus .lrv-a-icon-arrow-down{--a-icon-transform: rotate(180deg)}}
+@media(min-width: 48rem){.lrv-a-icon-after-remove\@tablet::after{display:none}}.lrv-a-icon-invert{--a-icon-filter: invert(1)}.lrv-a-icon-arrow-left,.lrv-a-icon-arrow-right,.lrv-a-icon-arrow-down,.lrv-a-icon-arrow-up{--a-icon-url: url( "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 14 8'%3E%3Cpath d='M13.7 1.7l-6 6c-.2.2-.4.3-.7.3-.3 0-.5-.1-.7-.3l-6-6C-.1 1.3-.1.7.3.3s1-.4 1.4 0L7 5.6 12.3.3c.4-.4 1-.4 1.4 0s.4 1 0 1.4z'/%3E%3C/svg%3E" );--a-icon-height: 0.75rem}.lrv-a-icon-arrow-right{--a-icon-transform: rotate(-90deg)}.lrv-a-icon-arrow-left{--a-icon-transform: rotate(90deg)}.lrv-a-icon-envelope{--a-icon-url: url( "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='9'%3E%3Cpath d='M.77.945C.636.875.406.752.356.605.269.357.362.258.731.258h12.723c.37 0 .462.096.376.349-.05.143-.28.27-.416.34-.366.192-5.45 2.964-5.64 3.064-.19.1-.382.146-.681.146-.3 0-.493-.047-.683-.146C6.22 3.91 1.137 1.138.77.945zm12.934.15c.296-.15.276.023.276.163v6.82c0 .307-.39.696-.716.696H.921c-.326 0-.782-.386-.782-.695V1.258c0-.136.016-.313.31-.163.272.14 2.747 1.883 4.368 2.931L2.085 7.104c-.066.066-.096.15-.056.186.04.04.13.02.196-.046l3.28-2.769c.496.32.842.54.905.573.257.13.436.146.683.146.246 0 .425-.017.682-.146.06-.034.409-.253.905-.573l3.28 2.769c.07.063.156.083.196.046.037-.04.007-.12-.06-.186L9.363 4.026c1.62-1.048 4.069-2.791 4.342-2.931z'/%3E%3C/svg%3E" );--a-icon-height: 0.625rem}.lrv-a-icon-search{--a-icon-url: url( "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='18' height='18'%3E%3Cpath d='M5.228 11.335h.79l.28-.27a6.471 6.471 0 01-1.57-4.23 6.5 6.5 0 116.5 6.5c-1.61 0-3.09-.59-4.23-1.57l-.27.28v.79l-5 4.99-1.49-1.49 4.99-5zm6 0c2.49 0 4.5-2.01 4.5-4.5s-2.01-4.5-4.5-4.5-4.5 2.01-4.5 4.5 2.01 4.5 4.5 4.5z' fill-rule='evenodd'/%3E%3C/svg%3E" )}
+.lrv-a-hover-effect{transition:var(--a-hover-effect-property, 300ms cubic-bezier(0.19, 1, 0.22, 1))}.lrv-a-hover-effect--fade{transform:translate3d(0px, 0px, 0px)}.lrv-a-hover-effect--fade:hover{--a-hover-effect-property: opacity;opacity:.5}.lrv-a-hover-effect--underline{transform:translate3d(0px, 0px, 0px)}.lrv-a-hover-effect--underline:hover{--a-hover-effect-property: border-bottom;border-bottom:1px solid currentColor}
+.lrv-a-truncate-ellipsis{white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.lrv-a-truncate-ellipsis-1line{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:1;-webkit-box-orient:vertical}.lrv-a-truncate-ellipsis-2line{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical}.lrv-a-truncate-ellipsis-3line{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical}.lrv-a-truncate-ellipsis-5line{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:5;-webkit-box-orient:vertical}.lrv-a-truncate-ellipsis-6line{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:6;-webkit-box-orient:vertical}@media(min-width: 78.75rem){.lrv-a-truncate-ellipsis-3line\@desktop-xl{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical}}@media(max-width: 78.7499rem){.lrv-a-truncate-ellipsis-4line\@mobile-max{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:4;-webkit-box-orient:vertical}}@media only screen and (max-width: 78.75rem)and (min-width: 48rem){.lrv-a-truncate-ellipsis-5line\@tablet-desktop-only{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:5;-webkit-box-orient:vertical}}@media(max-width: 78.7499rem){.lrv-a-truncate-ellipsis-5line\@desktop-xl-max{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:5;-webkit-box-orient:vertical}}@media only screen and (max-width: 78.75rem)and (min-width: 48rem){.lrv-a-truncate-ellipsis-1line\@tablet-desktop-only{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:1;-webkit-box-orient:vertical}}@media(max-width: 47.999rem){.lrv-a-truncate-ellipsis-2line\@mobile-max{overflow:hidden;text-overflow:ellipsis;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical}}