@penskemediacorp/larva-css 1.5.4-alpha.0 → 1.6.1

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,35 +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).
 
-## Concepts
+## Overview of Functionality
 
-### "Atomic" or "Functional" CSS
+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.
 
-### Removing the Burden of Naming
+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).
 
-Unless you are authoring a CSS algorithm, you should not have to name a new class.
+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/).
 
-### Cascading and Specificity
+Contribution to this repository is relatively infrequent, and will genereally be for the purposes of increasing the capability of the library.
 
-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.
+## Development Setup
 
-## Terminology
+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`
 
-*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.
+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.
 
-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):
+## Using larva-css in Projects
 
-* pmc-u-display-block
-* pmc-u-color-brand-primary
-* pmc-u-margin-tb-1@tablet
+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.
 
-\* 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.
+First, install the package:
 
-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:
+```
+npm install @penskemediacorp/larva-css --save
+```
 
-* 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.
+Then, using the below details, determine how to load larva-css in your project.
 
-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.
+### 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';
+
+@import '@penskemediacorp/larva-css/src/01-generic/*.inline.scss';
+@import '01-generic/*.common.inline.scss';
+
+@import '@penskemediacorp/larva-css/src/02-algorithms/**/*.inline.scss';
+@import '02-algorithms/*.common.inline.scss';
+
+@import '@penskemediacorp/larva-css/src/03-utilities/*.inline.scss';
+@import '03-utilities/*.common.inline.scss';
+
+@import '@penskemediacorp/larva-css/src/04-js/*.inline.scss';
+@import '04-js/*.common.inline.scss';
+```
+
+Next, create a file for project-level tokens in in assets/src/scss/00-tools/tokens.scss that contains the following:
+
+```
+@import '@penskemediacorp/larva-tokens/build/default.map.scss';
+
+$local-tokens: (
+	'font-size-12': pmc-rem(12),
+	'opacity-075': 0.75,
+);
+
+$TOKENS-MAP: map-merge( $default-map, $local-tokens );
+```
+
+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.
+
+If a property is **not** generated from larva-css, you can iterate over the local tokens map with the following Sass:
+
+```
+// Example: u-opacity.common.inline.scss
+@import 'setup';
+
+@each $token, $value in $TOKENS-MAP {
+	$token-str: quote( $token );
+
+	@if str-index( $token-str, 'opacity' ) {
+		.u-#{$token} {
+			opacity: $value;
+		}
+
+		// 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;
+			}
+		}
+	}
+
+}
+
+```
+
+Refer to the larva-css source files in larva-css/src and in the local Larva server, navigate to /css to see available classes.
+
+## Things to Know
+
+### The .lrv namespace
+
+CSS originating from larva-css .scss files contain a .lrv- namespace. Local project CSS should only contain an `a-`, `u-`, or `js-` namespace.
+
+### Utility Naming
+
+Utilities that are generated from larva-tokens, are named as follows:
+
+`.lrv-u-{$token-name}`
+
+For `spacing-XX` tokens, they are named:
+
+`.lrv-u-margin-{l|r|t|b|lr|tb|a}-{$size}`
+
+Where, if the token was `spacing-1`, the utility would be `lrv-u-margin-l-1`.
+
+### Algorithms
+
+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`.
+
+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.
+
+#### `.lrv-a-font` Generation
+
+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.
+
+### JS-related CSS
+
+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)}}
+.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}
+@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-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}}