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

package/src/02-algorithms/README.md

@@ -0,0 +1,65 @@
+
+# CSS Algorithms
+
+## Anatomy
+
+Each algorithm should contain the following files:
+
+```
+|-- a-name
+	|-- a-name.{chunkName}.{async|inline}.{scss|css}
+	|-- a-name.html
+	|-- a-name.browser-test.js
+	|-- README.md
+```
+
+The HTML file should contain the minimum HTML required to reflect the functionality. 
+
+### CSS-only wherever possible!
+
+If you algorithm does not use any Sass, there is no need to pre-process it through Sass, so you can work directly in a CSS file. Although this might be unusual since we need to use tokens for a lot of styling, we should try to use CSS-only wherever possible! When developing relative layouts with CSS Grid, this is certainly a possibility.
+
+### Naming the Algorithm
+
+The name of the algorithm should be presentational in nature, and indicative of the CSS programming, _not_ oriented around the name of a UI element. Algorithms follow the development practice of small, well-named functions. 
+
+For example, `a-card-title` is a very poor algorithm name because it does not tell a fellow developer _what_ the CSS algorithm is doing. Essentially, any CSS could be in something called `a-card-title`. Some better names might be:
+
+* `a-minmax-font-size` for an algorithm that controls the min and max in the font-size property.
+* `a-vertically-centered-border-behind` for an algorithm that adds a vertically centered border behind an element.
+* `a-fade-in-on-hover-before` for an algorithm that fades in the `::before` pseudo-element when its hover state is triggered.
+
+### Naming the (S)CSS File
+
+The algorithm's CSS file should be named according to the chunk it will be included in when used in an actual product. Example, full file names (note that these may have originated as SCSS files):
+
+* `a-minmax-font-size.common.inline.css`
+* `a-offset-dots-behind.single.async.css`
+* `a-gradient-after.common.async.css`
+* `a-archive-grid.archive.inline.css`
+
+Note that the algorihtm name should be the _base_ name of the algorithm. These files may contain classes with responsive suffixes, elements, and modifiers, but it only necessary to include the base name in the file. Read on for further description of these naming parameters.
+
+#### `chunkName`
+
+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.
+
+#### `async` or `inline`
+
+These terms refer to whether or not the algorithm should be included in inlined, or "critical CSS", or in a file loaded asynchronously. 
+
+`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. 
+
+`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.
+
+## Usage
+
+Refer to the README for each algorithm for usage instructions.
+
+## Development
+
+Algorithms should be developed and build within a single SCSS file that outputs CSS to a file in the same directory with the same name. There is a watch command registered using the node-sass CLI that can be run from the packages/css-algorithms with the command `npm run sass`.
+
+## Testing
+
+CSS algorithms should have tests where possible. These tests are written in client side JavaScript and can be included in both the example HTML file in each pattern for unit testing, or included in any environment using the algorithm for integration tests.

package/src/02-algorithms/a-buy-now/a-buy-now.common.inline.scss

@@ -0,0 +1,112 @@
+@import 'setup';
+
+.lrv-a-buy-now {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	position: relative;
+
+	@include pmc-breakpoint( tablet ) {
+		display: block;
+	}
+}
+
+.lrv-a-buy-now__image {
+	position: relative;
+	z-index: 1;
+	width: 100%;
+	background-color: $color-white;
+	max-width: pmc-rem(300);
+
+	@include pmc-breakpoint( tablet ) {
+		width: pmc-rem(190); // 160 + 30
+		left: 0;
+		padding: 0 pmc-rem(30) 0 0;
+	}
+
+	@include pmc-breakpoint( desktop ) {
+		width: pmc-rem(245); // 185 + 30 + 30
+		left: pmc-rem(94);
+		padding: 0 pmc-rem(30);
+	}
+}
+
+.lrv-a-buy-now__button {
+	margin-top: pmc-rem(16);
+
+	@include pmc-breakpoint( tablet ) {
+		margin-top: 0;
+		position: absolute;
+		top: 50%;
+		left: pmc-rem(190);
+		transform: translateY(-50%);
+	}
+
+	@include pmc-breakpoint( desktop ) {
+		left: pmc-rem(339);
+	}
+}
+
+.lrv-a-buy-now__hr {
+	display: none;
+	margin: 0;
+	padding: 0;
+	border-top: pmc-rem(0.5) solid #000;
+	position: relative;
+
+	@include pmc-breakpoint( tablet ) {
+		display: block;
+	}
+}
+
+.lrv-a-buy-now__hr--top {
+	top: 0;
+
+	@include pmc-breakpoint( tablet ) {
+		top: pmc-rem(37);
+	}
+
+	@include pmc-breakpoint( desktop ) {
+		top: pmc-rem(50);
+	}
+}
+
+.lrv-a-buy-now__hr--bottom {
+	bottom: 0;
+
+	@include pmc-breakpoint( tablet ) {
+		bottom: pmc-rem(37);
+	}
+
+	@include pmc-breakpoint( desktop ) {
+		bottom: pmc-rem(50);
+	}
+}
+
+// Optional span.
+.lrv-a-buy-now__span {
+	display: none;
+	position: absolute;
+	right: 0;
+
+	@include pmc-breakpoint( tablet ) {
+		display: block;
+		bottom: pmc-rem(16);
+	}
+
+	@include pmc-breakpoint( desktop ) {
+		bottom: pmc-rem(29);
+	}
+}
+
+// Used when image is not present.
+.lrv-a-buy-now__p {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+}
+
+.lrv-a-buy-now__p .lrv-a-buy-now__button {
+	position: inherit;
+	transform: none;
+}

package/src/02-algorithms/a-carousel-grid/a-carousel-grid.common.inline.scss

@@ -0,0 +1,66 @@
+@import 'setup';
+
+.lrv-a-carousel-grid {
+    --grid-overlay: initial;
+
+    display: grid;
+    grid-template-columns: 1fr;
+
+    @include pmc-breakpoint( tablet ) {
+        grid-gap: var(--spacing-050);
+        grid-template-columns: 2fr 1fr;
+    }
+}
+
+.lrv-a-carousel-grid__overlay {
+    --grid-overlay: grid;
+
+    @include pmc-breakpoint( tablet ) {
+        grid-template-columns: 1fr;
+    }
+}
+
+.lrv-a-carousel-grid__overlay--primary {
+
+    @include pmc-breakpoint( desktop ) {
+        display: var(--grid-overlay);
+        grid-template-columns: 1fr 1.5rem 2fr;
+        align-items: center;
+        grid-auto-flow: column;
+        height: 100%;
+    }
+}
+
+.lrv-a-carousel-grid__overlay--primary-img {
+
+    @include pmc-breakpoint( desktop ) {
+        grid-column: 2/4;
+        grid-row: 1;
+    }
+}
+
+.lrv-a-carousel-grid__overlay--primary-content {
+
+    @include pmc-breakpoint( desktop ) {
+        grid-column: 1/3;
+        grid-row: 1;
+        padding: 1.875rem;
+        z-index: 1;
+        background-color: #fff;
+    }
+}
+
+.lrv-a-carousel-grid__overlay--secondary {
+
+    @include pmc-breakpoint( desktop ) {
+        display: var(--grid-overlay);
+        grid-template-columns: repeat(3,1fr);
+        grid-gap: var(--spacing-125);
+    }
+}
+
+.lrv-a-carousel-grid__overlay--secondary-card {
+    display: var(--grid-overlay);
+    grid-template-columns: 6.25rem 1fr;
+    grid-gap: var(--spacing-1);
+}

package/src/02-algorithms/a-children-border/a-children-border.common.inline.scss

@@ -0,0 +1,43 @@
+@import 'setup';
+
+:root {
+	--a-children-border-color: #{ map-get( $TOKENS-MAP, color-black ) };
+}
+
+.lrv-a-children-border--grey {
+	--a-children-border-color: #{ map-get( $TOKENS-MAP, border-color-grey ) };
+}
+
+.lrv-a-children-border--grey-light {
+	--a-children-border-color: #{ map-get( $TOKENS-MAP, border-color-grey-light ) };
+}
+
+// stylelint-disable selector-max-compound-selectors
+.lrv-a-children-border-vertical {
+	& > * + * {
+		border-top: var(--a-children-border-width, 1px) solid var(--a-children-border-color, '');
+	}
+}
+
+.lrv-a-children-border-vertical\@mobile-max {
+	@include pmc-breakpoint(mobile-max) {
+		& > * + * {
+			border-top: var(--a-children-border-width, 1px) solid var(--a-children-border-color, '');
+		}
+	}
+}
+
+.lrv-a-children-border-horizontal {
+	& > * + * {
+		border-left: var(--a-children-border-width, 1px) solid var(--a-children-border-color, '');
+	}
+}
+
+.lrv-a-children-border-horizontal\@desktop {
+	@include pmc-breakpoint(desktop) {
+		& > * + * {
+			border-left: var(--a-children-border-width, 1px) solid var(--a-children-border-color, '');
+		}
+	}
+}
+// stylelint-enable selector-max-compound-selectors

package/src/02-algorithms/a-children-link-color/a-children-link-color.common.inline.scss

@@ -0,0 +1,15 @@
+@import 'setup';
+
+.lrv-a-children-link-color-black {
+	& > a {
+		color: map-get( $TOKENS-MAP, color-black );
+		color: var( --color-black );
+	}
+}
+
+.lrv-a-children-link-color-brand-primary\:hover {
+	& > a:hover {
+		color: map-get( $TOKENS-MAP, color-brand-primary );
+		color: var( --color-brand-primary );
+	}
+}

package/src/02-algorithms/a-children-link-decoration/a-children-link-decoration.common.inline.scss

@@ -0,0 +1,13 @@
+@import 'setup';
+
+.lrv-a-children-link-decoration-underline {
+	& > a {
+		text-decoration: underline;
+	}
+}
+
+.lrv-a-children-link-decoration-underline\:hover {
+	& > a:hover {
+		text-decoration: underline;
+	}
+}

package/src/02-algorithms/a-counter/a-counter.common.inline.scss

@@ -0,0 +1,26 @@
+.lrv-a-counter {
+	counter-reset: a-counter;
+}
+
+.lrv-a-counter-increment {
+	counter-increment: a-counter;
+}
+
+.lrv-a-counter-before::before {
+	content: counter( a-counter );
+	display: var( --a-counter__display, inline-block);
+	padding: var( --a-counter__padding, initial );
+	background-color: var( --a-counter__background-color, initial );
+	color: var( --a-counter__color, inherit );
+	border-top-right-radius: var( --a-counter__border-top-right-radius, inherit );
+	font-family: var( --a-counter__font-family, inherit );
+	font-size: var( --a-counter__font-size, inherit ); // stylelint-disable-line property-blacklist
+	line-height: var( --a-counter__line-height, 0.7 );
+	font-weight: var( --a-counter__font-weight, inherit ); // stylelint-disable-line property-blacklist
+	z-index: 1;
+	position: var( --a-counter__position, initial );
+	left: var( --a-counter__left, auto );
+	top: var( --a-counter__top, auto );
+	right: var( --a-counter__right, auto );
+	bottom: var( --a-counter__bottom, auto );
+}

package/src/02-algorithms/a-crop/README.md

@@ -1,31 +1,35 @@
-# Crop
+# a-crop
 
 The cropping algorithm applies an aspect ratio to a element containing an image, and will crop the contained image to the aspect ratio. It uses background-size: cover, padding, and absolute positioning to do this. 
 
-The classes output by the generator are `.pmc-a-crop-WIDTHxHEIGHT`, so a 16x9 cropped image would use the class `.pmc-a-crop-16x9`.
+The classes output by the generator are `.a-crop-WIDTHxHEIGHT`, so a 16x9 cropped image would use the class `.a-crop-16x9`.
 
-The available aspect ratios output from this package are:
+## Available Classes
 
-```
-.pmc-a-crop-1x1
-.pmc-a-crop-2x1
-.pmc-a-crop-2x3
-.pmc-a-crop-4x3
-.pmc-a-crop-16x9
-.pmc-a-crop-3x4
-```
+Reference the Sass list in a-crop.common.inline.scss to see a list of a-crop classes provided by Larva CSS.
+
+## Algorithm Source
 
 The source for the cropping algorithm is:
+
 ```
-.pmc-a-crop-16x9 {
+.lrv-a-crop-16x9 {
 	position: relative;
 	padding-bottom: calc( ( 9 / 16 ) * 100%); 
 }
 
-.pmc-a-crop-16x9 img {
+.lrv-a-crop-16x9 img {
 	position: absolute;
 	width: 100%;
 	height: 100%;
 	object-fit: cover; 
 }
 ```
+
+## Extendable?
+
+**Do no extend `a-crop`**. Create a separate algorithm, or use utilities for properties like the following:
+
+* object-fit - change the scaling behavior of the image e.g. `u-object-fit-contain`.
+* object-position - change the alignment of a cropped image, e.g. align it to the top rather than center.
+* background-color – update the background color that may appear while an image is loading.

package/src/02-algorithms/a-crop/a-crop.common.inline.scss

@@ -1,12 +1,97 @@
-@import '@penskemediacorp/larva-scss/dist/generators';
-
-@include pmc-a-crop(
-	(
-		'1x1': (1, 1),
-		'2x1': (2, 2),
-		'2x3': (3, 2),
-		'4x3': (4, 3),
-		'16x9': (16, 9),
-		'3x4': (3, 4)
-	)
-);
+@import 'setup';
+
+$aspect-ratios: (
+	'1x1': (1, 1),
+	'2x1': (2, 1),
+	'2x3': (2, 3),
+	'3x2': (3, 2),
+	'4x3': (4, 3),
+	'16x9': (16, 9),
+	'5x1': (5, 1),
+	'5x2': (5, 2),
+	'3x4': (3, 4)
+);
+
+@include a-crop( $aspect-ratios, $NAMESPACE: 'lrv-' );
+
+.lrv-a-crop-contain img { // Required for a-crop
+	object-fit: contain;
+}
+
+.lrv-a-crop-1x1\@mobile-max {
+	@include pmc-breakpoint( mobile-max ) {
+	 
+		position: relative;
+		padding-bottom: 100%;
+
+		img {
+			position: absolute;
+			width: 100%;
+			height: 100%;
+			object-fit: cover;
+		}
+		 
+	}
+}
+
+.lrv-a-crop-1x1\@tablet {
+	@include pmc-breakpoint( tablet ) {
+	 
+		position: relative;
+		padding-bottom: 100%;
+
+		img {
+			position: absolute;
+			width: 100%;
+			height: 100%;
+			object-fit: cover;
+		}
+		 
+	}
+}
+
+.lrv-a-crop-1x1\@desktop-xl-max {
+	@include pmc-breakpoint( desktop-xl-max ) {
+	 
+		position: relative;
+		padding-bottom: 100%;
+
+		img {
+			position: absolute;
+			width: 100%;
+			height: 100%;
+			object-fit: cover;
+		} 
+	}
+}
+
+.lrv-a-crop-3x2\@desktop-xl {
+	@include pmc-breakpoint( desktop-xl ) {
+	 
+		position: relative;
+		padding-bottom: calc( ( 2 / 3 ) * 100% );
+
+		img {
+			position: absolute;
+			width: 100%;
+			height: 100%;
+			object-fit: cover;
+		} 
+	}
+}
+
+
+.lrv-a-crop-3x2\@mobile-max {
+	@include pmc-breakpoint( mobile-max ) {
+	 
+		position: relative;
+		padding-bottom: calc( ( 2 / 3 ) * 100% );
+
+		img {
+			position: absolute;
+			width: 100%;
+			height: 100%;
+			object-fit: cover;
+		} 
+	}
+}

package/src/02-algorithms/a-crop/a-crop.html

@@ -9,11 +9,11 @@
 </head>
 <body>
 
-	<div class="pmc-a-crop-16x9" style="width: 600px;">
+	<div class="lrv-a-crop-16x9" style="width: 600px;">
 		<img src="https://pmcdeadline2.files.wordpress.com/2019/07/jonathan-majors.jpg" alt="">
 	</div>
 	<hr>
-	<div class="pmc-a-crop-3x4" style="width: 400px;">
+	<div class="lrv-a-crop-3x4" style="width: 400px;">
 		<img src="https://pmcdeadline2.files.wordpress.com/2019/07/jonathan-majors.jpg" alt="">
 	</div>
 

package/src/02-algorithms/a-floated/a-floated.common.inline.scss

@@ -0,0 +1,32 @@
+@import '@penskemediacorp/larva-scss/dist/tools';
+
+.lrv-a-floated-parent::before,
+.lrv-a-floated-parent::after {
+	content: '';
+	display: table;
+}
+
+.lrv-a-floated-parent::after {
+	clear: both;
+}
+
+.lrv-a-floated-parent {
+	zoom: 1;
+}
+
+.lrv-a-floated-left {
+	float: left;
+}
+
+.lrv-a-floated-left\@tablet {
+
+	@include pmc-breakpoint( tablet ) {
+		float: left;
+	}
+}
+
+.lrv-a-floated-right\@tablet {
+	@include pmc-breakpoint(tablet) {
+		float: right;
+	}
+}

package/src/02-algorithms/a-font/a-font.common.inline.scss

@@ -0,0 +1,3 @@
+@import 'setup';
+
+@import '../../_generated/a-font';

package/src/02-algorithms/a-glue/a-glue.common.inline.scss

@@ -10,11 +10,11 @@
 	left: var( --a-glue-left, initial );
 }
 
-.pmc-a-glue-parent {
+.lrv-a-glue-parent {
 	position: relative;
 }
 
-.pmc-a-glue {
+.lrv-a-glue {
 	// Fallback is top left for everything.
 	top: 0;
 	left: 0;
@@ -22,18 +22,75 @@
 	@include _a-glue-base;
 }
 
-.pmc-a-glue--l-0 {
+@include pmc-breakpoint( mobile-max ) {
+	.lrv-a-glue\@mobile-max {
+		top: 0;
+		left: 0;
+
+		@include _a-glue-base;
+	}
+}
+
+.lrv-a-glue\@tablet {
+	@include pmc-breakpoint( tablet ) {
+		// TODO: incorporate these fallback values into mixin
+		top: 0;
+		left: 0;
+
+		@include _a-glue-base;
+	}
+}
+
+.lrv-a-glue--l-0 {
 	--a-glue-left: 0;
 }
 
-.pmc-a-glue--r-0 {
+.lrv-a-glue--r-0 {
 	--a-glue-right: 0;
 }
 
-.pmc-a-glue--t-0 {
+.lrv-a-glue--t-0 {
 	--a-glue-top: 0;
 }
 
-.pmc-a-glue--b-0 {
+.lrv-a-glue--b-0 {
 	--a-glue-bottom: 0;
 }
+
+.lrv-a-glue--t-50p {
+	--a-glue-top: 50%;
+}
+
+.lrv-a-glue--t-100p {
+	--a-glue-top: 100%;
+}
+
+.lrv-a-glue--l-50p {
+	--a-glue-left: 50%;
+}
+
+.lrv-a-glue--r-50p {
+	--a-glue-right: 50%;
+}
+
+.lrv-a-glue--b-n1 {
+	--a-glue-bottom: -1rem;
+}
+
+.lrv-a-glue-parent\@mobile-max {
+	@include pmc-breakpoint( mobile-max ) {
+		position: relative;
+	}
+}
+
+.lrv-a-glue-parent\@tablet {
+	@include pmc-breakpoint( tablet ) {
+		position: relative;
+	}
+}
+
+.lrv-a-glue--b-unset\@mobile-max {
+	@include pmc-breakpoint( mobile-max ) {
+		bottom: unset;
+	}
+}

package/src/02-algorithms/a-glue/a-glue.html

@@ -5,12 +5,12 @@
 	<meta name="viewport" content="width=device-width, initial-scale=1.0">
 	<meta http-equiv="X-UA-Compatible" content="ie=edge">
 	<title>Document</title>
-	<link rel="stylesheet" href="./a-glue.common.inline.css">
+	<link rel="stylesheet" href="../../../build/css/algorithms.common.inline.css">
 </head>
 <body>
-	<div class="a-glue-parent" style="display: inline-block;">
+	<div class="lrv-a-glue-parent" style="display: inline-block;">
 		<img src="http://placehold.it/300x300" alt="">
-		<p class="a-glue a-glue--t-0 a-glue--r-0">Glued Element</p>
+		<p class="lrv-a-glue lrv-a-glue--t-0 lrv-a-glue--r-0">Glued Element</p>
 	</div>
 </body>
 </html>