@daffodil/design 0.42.2 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daffodil/design",
-  "version": "0.42.2",
+  "version": "0.43.0",
   "author": "Graycore LLC",
   "license": "MIT",
   "bugs": {

package/scss/accessibility/_errors.scss

@@ -0,0 +1,12 @@
+/* stylelint-disable */
+$wcag-aa-errors: (
+	'text-contrast': 'WCAG 2.0 level AA requires text and its background color to have a contrast ratio of at least 4.5:1',
+	'icon-contrast': 'WCAG 2.0 level AA requires the icon and its background color to have a contrast ratio of at least 3:1'
+);
+
+$wcag-aaa-errors: (
+	map-merge($wcag-aa-errors, (
+		'text-contrast': 'WCAG 2.0 level AA requires text and its background color to have a contrast ratio of at least 7:1',
+	))
+);
+/* stylelint-enable */

package/scss/accessibility/_index.scss

@@ -0,0 +1 @@
+@forward 'errors';

package/scss/core/_index.scss

@@ -0,0 +1,4 @@
+@forward 'string/split/string-split';
+
+@forward 'map/map-deep-check/map-deep-check';
+@forward 'map/map-deep-get/map-deep-get';

package/scss/core/map/map-deep-check/map-deep-check.scss

@@ -0,0 +1,26 @@
+@use 'sass:map';
+
+//
+// Checks whether or not a map has a nested key
+//
+// @param $map - the map being checked
+// @param $keys - an list of ordered keys to traverse down
+//
+// @returns boolean
+// @throws error
+//
+@function daff-map-deep-check($map, $keys) {
+	@if (type-of($map) != 'map') {
+		@error 'Expected first parameter to be of type `map`';
+	}
+
+	@each $key in $keys {
+		@if (not map.has-key($map, $key)) {
+			@return false;
+		}
+
+		$map: map.get($map, $key);
+	}
+
+	@return true;
+}

package/scss/core/map/map-deep-check/map-deep-check.spec.scss

@@ -0,0 +1,43 @@
+@use 'true' as *;
+@use './map-deep-check' as *;
+
+@include describe('map-deep-check') {
+	$map: (
+		'nested': (
+			'string': '1',
+			'number': 2,
+			'map': (
+				'string': '3',
+				'number': 4
+			)
+		)
+	);
+
+	@include it('returns `true` if the map contains the key') {
+		@include assert-equal(
+			daff-map-deep-check($map, ('nested', 'string')),
+			true
+		);
+		@include assert-equal(
+			daff-map-deep-check($map, ('nested', 'number')),
+			true
+		);
+		@include assert-equal(daff-map-deep-check($map, ('nested', 'map')), true);
+		@include assert-equal(
+			daff-map-deep-check($map, ('nested', 'map', 'string')),
+			true
+		);
+		@include assert-equal(
+			daff-map-deep-check($map, ('nested', 'map', 'number')),
+			true
+		);
+	}
+
+	@include it('should return false if the $key is not in the list') {
+		@include assert-equal(
+			daff-map-deep-check($map, ('UNREALKEY', 'TEST')),
+			false
+		);
+		@include assert-equal(daff-map-deep-check($map, ('SOMEOTHER')), false);
+	}
+}

package/scss/core/map/map-deep-get/map-deep-get.scss

@@ -0,0 +1,27 @@
+@use 'sass:map';
+@use '../../string/split/string-split';
+@use '../map-deep-check/map-deep-check';
+
+//
+// Return a the value of a nested key in a map if it exists.
+// If the key doesn't exist, it throw an error.
+//
+// Note: This function doesn't support the use
+// of the search character in your map key names.
+//
+// @usage daff-map-deep-get($map, "nested.map.key");
+// @returns any
+// @throws error
+@function daff-map-deep-get($map, $key, $search-character: '.') {
+	$keys: string-split.daff-string-split($key, $search-character);
+
+	@if not map-deep-check.daff-map-deep-check($map, $keys) {
+		@error 'The map doesn\'t contain the $key: `#{$key}`\'';
+	}
+
+	@each $key in $keys {
+		$map: map.get($map, $key);
+	}
+
+	@return $map;
+}

package/scss/core/map/map-deep-get/map-deep-get.spec.scss

@@ -0,0 +1,25 @@
+@use 'true' as *;
+@use './map-deep-get' as *;
+
+@include describe('map-deep-get') {
+	$nested-map: (
+		'string': '3',
+		'number': 4
+	);
+
+	$map: (
+		'nested': (
+			'string': '1',
+			'number': 2,
+			'map': $nested-map
+		)
+	);
+
+	@include it('returns the value of the nested key if it exists in the map') {
+		@include assert-equal(daff-map-deep-get($map, ('nested.string')), '1');
+		@include assert-equal(daff-map-deep-get($map, ('nested.number')), 2);
+		@include assert-equal(daff-map-deep-get($map, ('nested.map')), $nested-map);
+		@include assert-equal(daff-map-deep-get($map, ('nested.map.string')), '3');
+		@include assert-equal(daff-map-deep-get($map, ('nested.map.number')), 4);
+	}
+}

package/scss/core/string/split/string-split.scss

@@ -0,0 +1,33 @@
+//
+// @docs
+// @private
+// Splits a string into an array based on a separator
+// Remember, string arrays begin at 1 in SASS.
+//
+// @returns comma-list
+//
+@function daff-string-split($string, $separator) {
+	$list: ();
+	$index: str-index($string, $separator);
+
+	@if ($index == null) {
+		@return $list;
+	}
+
+	@while $index !=null {
+		$item: str-slice($string, 1, $index - 1);
+
+		@if ($item != '') {
+			$list: append($list, $item, 'comma');
+		}
+
+		$string: str-slice($string, $index + 1);
+		$index: str-index($string, $separator);
+	}
+
+	@if ($string != '') {
+		$list: append($list, $string, 'comma');
+	}
+
+	@return $list;
+}

package/scss/core/string/split/string-split.spec.scss

@@ -0,0 +1,35 @@
+@use 'true' as *;
+@use './string-split' as *;
+
+@include describe('daff-string-split') {
+	@include it(
+		'returns an empty map if the separator does not exist in the string'
+	) {
+		@include assert-equal(daff-string-split('a', '.'), ());
+	}
+
+	@include it(
+		'returns a single element if there is only one separator at the beginning'
+	) {
+		@include assert-equal(daff-string-split('.a', '.'), ('a',));
+	}
+
+	@include it(
+		'will treat duplicate separators as if there was only a single separator'
+	) {
+		@include assert-equal(daff-string-split('..a..', '.'), ('a',));
+	}
+
+	@include it(
+		'returns a single element if there is only one separator at the end'
+	) {
+		@include assert-equal(daff-string-split('a.', '.'), ('a',));
+	}
+
+	@include it('splits a string based on a separator') {
+		@include assert-equal(
+			daff-string-split('abc.xyz.csv', '.'),
+			('abc', 'xyz', 'csv')
+		);
+	}
+}

package/scss/daff-global.scss

@@ -0,0 +1,49 @@
+// @docs
+
+// `daff-global` holds boilerplate code for the project. It includes
+// standard styles such as resets and typographic rules, which are
+// commonly used throughout your project.
+//
+// @note This should only be imported once in your `styles.scss` file.
+//
+// @usage
+// ```scss
+// @use '@daffodil/design/scss/daff-global';
+// ```
+
+@use 'typography' as t;
+@use '~@angular/cdk/overlay-prebuilt';
+@use '~modern-normalize/modern-normalize';
+@forward './theming/theme-css-variables';
+
+body,
+html {
+	font-family: t.$body-font-family;
+	font-size: 16px;
+	font-weight: 400;
+	line-height: 1.5;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+html {
+	scroll-behavior: smooth;
+}
+
+a {
+	color: currentColor;
+
+	&:hover {
+		text-decoration: none;
+	}
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+	margin: 0;
+	padding: 0;
+}

package/scss/daff-typography.scss

@@ -0,0 +1,55 @@
+//
+// @docs
+//
+// @deprecated in v1.0.0
+// `daff-typography` will be deprecated in v1.0.0 in favor
+// of the typography module. Check out the [typography
+// documentation](libs/design/scss/typography/README.md)
+// for more information.
+//
+// `daff-typography` is a generic typography library that
+// sets common typography settings for the daffodil design
+// package. It IS NOT necessary, but can be used.
+//
+// @note You SHOULD NOT import this as often as you like,
+// as it only contains CSS
+// and will effect your final compiled stylesheet size.
+//
+// @usage
+// ```scss
+// @use '@daffodil/design/scss/daff-typography';
+// ```
+
+@use '~modern-normalize/modern-normalize';
+
+@use 'typography' as t;
+@forward 'typography';
+@forward 'typography/classes';
+
+body,
+html {
+	font-family: t.$body-font-family;
+	font-size: 16px;
+	font-weight: 400;
+	line-height: 1.5;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+a {
+	color: currentColor;
+
+	&:hover {
+		text-decoration: none;
+	}
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+	margin: 0;
+	padding: 0;
+}

package/scss/daff-util.scss

@@ -0,0 +1,21 @@
+// @docs
+//
+// `daff-util` is a utility library that contains common functions,
+// mixins and variables that make writing SCSS stylesheets a bit
+// easier.
+//
+//
+// @note You can import this as often as you like, as it only contains SCSS
+// variables, mixins, and functions; thus it won't effect your final
+// compiled stylesheet size.
+//
+// @usage
+// ```scss
+// @use '@daffodil/design/scss/daff-util';
+// ```
+
+@forward 'core';
+@forward 'typography';
+@forward 'layout';
+@forward 'interactions';
+@forward 'accessibility';

package/scss/interactions/_index.scss

@@ -0,0 +1 @@
+@forward 'mouse/clickable';

package/scss/interactions/mouse/_clickable.scss

@@ -0,0 +1,22 @@
+//
+// @docs
+//
+// The clickable() mixin sets mouse cursor to display when the mouse
+// pointer is over an element for all supported browsers
+//
+// Supported browsers: Chrome all/Safari all/Firefox all/IE 10+
+//
+// @usage
+// ```
+// @include clickable();
+// ```
+@mixin clickable() {
+	cursor: pointer;
+	-webkit-user-select: none;
+	/// Chrome all / Safari all ///
+	-moz-user-select: none;
+	/// Firefox all ///
+	-ms-user-select: none;
+	/// IE 10+ ///
+	user-select: none;
+}

package/scss/layout/_breakpoint.scss

@@ -0,0 +1,21 @@
+@use 'sass:map';
+@use 'variables' as v;
+
+//
+// Take a the list of breakpoints and retrieves the defined point.
+// If an invalid breakpoint is defined, it will display a warning.
+//
+// @usage
+// ```
+// @include layout.breakpoint(mobile) {}
+// ```
+//
+@mixin breakpoint($point) {
+	@if not map.has-key($map: v.$breakpoints, $key: $point) {
+		@warn 'breakpoint(): "#{$key}" is not defined in your $breakpoints setting.';
+	}
+
+	@media (min-width: map.get(v.$breakpoints, $point)) {
+		@content;
+	}
+}

package/scss/layout/_index.scss

@@ -0,0 +1,2 @@
+@forward 'variables';
+@forward 'breakpoint';

package/scss/layout/_variables.scss

@@ -0,0 +1,13 @@
+//
+// @docs
+//
+// Sensible breakpoints to be used for layouts and interfaces.
+// These breakpoints are based on common devices viewport widths.
+$breakpoints: (
+	desktop: 1920px,
+	laptop: 1440px,
+	small-laptop: 1200px,
+	big-tablet: 1024px,
+	tablet: 768px,
+	mobile: 480px
+);

package/scss/theme.scss

@@ -0,0 +1,77 @@
+// @docs
+
+// `theme` is a utility library for theming the daffodil
+// design library. It contains many useful mixins, functions,
+// and variables.
+
+// @note You can use this as often as you like, as it only contains SCSS
+// variables, mixins, and functions; thus it won't effect your final
+// compiled stylesheet size.
+
+// @usage
+// ```
+// @use '@daffodil/design/scss/theme';
+// ```
+
+@forward 'core';
+@forward 'accessibility';
+@forward 'theming';
+
+// @daffodil/design components
+@use './theming/theme-css-variables' as variables;
+@use '../src/atoms/button/button-theme' as button;
+@use '../src/atoms/form/error-message/error-message-theme' as error-message;
+@use '../src/atoms/form/form-field/form-field/form-field-theme' as form-field;
+@use '../src/atoms/form/input/input-theme' as input;
+@use '../src/atoms/form/select/select/select-theme' as select;
+@use '../src/atoms/loading-icon/loading-icon-theme' as loading-icon;
+@use '../src/atoms/progress-indicator/progress-indicator-theme' as progress-indicator;
+@use '../src/molecules/accordion/accordion-item/accordion-item-theme' as accordion-item;
+@use '../src/molecules/article/article/article-theme' as article;
+@use '../src/molecules/callout/callout-theme' as callout;
+@use '../src/molecules/card/card/card-theme' as card;
+@use '../src/molecules/hero/hero-theme' as hero;
+@use '../src/molecules/list/list/list-theme' as list;
+@use '../src/molecules/media-gallery/media-gallery-theme' as media-gallery;
+@use '../src/molecules/modal/modal-theme' as modal;
+@use '../src/molecules/navbar/navbar-theme' as navbar;
+@use '../src/molecules/paginator/paginator-theme' as paginator;
+@use '../src/molecules/sidebar/sidebar/sidebar-theme' as sidebar;
+@use '../src/molecules/sidebar/sidebar-viewport/sidebar-viewport-theme' as sidebar-viewport;
+
+//
+// Generates the styles of a @daffodil/design theme.
+//
+// Usage:
+// ```scss
+// @use '@daffodil/design/scss/theme';
+//
+// @include daff-theme($theme);
+// ```
+@mixin daff-theme($theme) {
+	// CSS variables
+	@include variables.daff-theme-css-variables($theme);
+
+	// Atoms
+	@include button.daff-button-theme($theme);
+	@include error-message.daff-error-message-theme($theme);
+	@include form-field.daff-form-field-theme($theme);
+	@include input.daff-input-theme($theme);
+	@include select.daff-select-theme($theme);
+	@include loading-icon.daff-loading-icon-theme($theme);
+	@include progress-indicator.daff-progress-indicator-theme($theme);
+
+	// Molecules
+	@include accordion-item.daff-accordion-item-theme($theme);
+	@include article.daff-article-theme($theme);
+	@include callout.daff-callout-theme($theme);
+	@include card.daff-card-theme($theme);
+	@include hero.daff-hero-theme($theme);
+	@include list.daff-list-theme($theme);
+	@include media-gallery.daff-media-gallery-theme($theme);
+	@include modal.daff-modal-theme($theme);
+	@include navbar.daff-navbar-theme($theme);
+	@include paginator.daff-paginator-theme($theme);
+	@include sidebar.daff-sidebar-theme($theme);
+	@include sidebar-viewport.daff-sidebar-viewport-theme($theme);
+}

package/scss/theming/README.md

@@ -0,0 +1,59 @@
+# Theming
+Daffodil's theming capabilities enables you to customize `@daffodil/design` components to reflect your brand. A theme consists of custom color configurations that will work in dark and light themes.
+
+## Custom Colors
+:stop: Before you begin, read the [accessibility guide on color in `@daffodil/design`](../../guides/color#accessibility.md).
+
+[validate palette function]
+
+## Themes
+Dark and light modes are supported in all `@daffodil/design` components. When a theme is not specified, Daffodil defaults to the `light` mode.
+
+### Setting up the theme file
+Configure your application to support light and dark modes by adding the following to the `theme.scss` file:
+
+```scss
+@use '@daffodil/design/scss/theme' as daff-theme;
+
+// These palettes describe the colors that make up the "theme" of the components.
+
+$primary: daff-theme.daff-configure-palette(daff-theme.$daff-blue, 60);
+$secondary: daff-theme.daff-configure-palette(daff-theme.$daff-purple, 60);
+$tertiary: daff-theme.daff-configure-palette(daff-theme.$daff-turquoise, 60);
+
+$theme: daff-theme.daff-configure-theme($primary, $secondary, $tertiary, 'light');
+
+$primary-dark: daff-theme.daff-configure-palette(daff-theme.$daff-blue, 50);
+$secondary-dark: daff-theme.daff-configure-palette(daff-theme.$daff-purple, 50);
+$tertiary-dark: daff-theme.daff-configure-palette(daff-theme.$daff-green, 50);
+
+$theme-dark: daff-theme.daff-configure-theme($primary-dark, $secondary-dark, $tertiary-dark, 'dark');
+
+$black: daff-theme.daff-map-deep-get($theme, 'core.black');
+$white: daff-theme.daff-map-deep-get($theme, 'core.white');
+$gray: daff-theme.daff-map-deep-get($theme, 'core.gray');
+```
+
+### Setting up the styles file
+Add `theme.scss` to the `styles.scss` file.
+
+```scss
+@use 'theme' as app-theme;
+```
+
+> These lines include theme variables and functions that will generate the theme CSS and style the components.
+
+Create classes in the `styles.scss` file to include the `daff-theme` mixin for `$theme` and `$theme-dark` variables. This will allow you to set a click event on a button to switch between modes. [View this setup in Stackblitz](https://stackblitz.com/edit/daffodil-design-theming-angular-10)
+
+```scss
+@use '@daffodil/design/scss/theme' as daff-theme;
+@use 'theme' as app-theme;
+
+.daff-theme-light {
+	@include daff-theme.daff-theme(app-theme.$theme);
+}
+
+.daff-theme-dark {
+	@include daff-theme.daff-theme(app-theme.$theme-dark);
+}
+```

package/scss/theming/_color-palettes.scss

@@ -0,0 +1,116 @@
+// Base colors
+$daff-white: #ffffff;
+$error: #dd0000;
+
+// 60 apart passes AAA level for any size text (except for 10/70)
+// 50 apart passes AA level for any size text (except for 10/60)
+
+$daff-blue: (
+	10: #ebf1ff,
+	20: #c4d8ff,
+	30: #9dbeff,
+	40: #79a7ff,
+	50: #548fff,
+	60: #1f66ff,
+	70: #093cf3,
+	80: #001bcb,
+	90: #00098a,
+	100: #000033
+);
+
+$daff-primary: $daff-blue;
+
+$daff-purple: (
+	10: #ebebff,
+	20: #d4d3ff,
+	30: #b7b4ff,
+	40: #a19bff,
+	50: #8b82ff,
+	60: #6a57ff,
+	70: #5631f3,
+	80: #3c13bd,
+	90: #2c068a,
+	100: #110033
+);
+
+$daff-accent: $daff-purple;
+
+$daff-turquoise: (
+	10: #d6fcea,
+	20: #9dfbd3,
+	30: #51e1ae,
+	40: #37c193,
+	50: #1fa67c,
+	60: #00835f,
+	70: #0f654a,
+	80: #104b37,
+	90: #0d3426,
+	100: #082218
+);
+
+$daff-yellow: (
+	10: #fffaeb,
+	20: #fff1c2,
+	30: #ffe799,
+	40: #ffde70,
+	50: #ffd447,
+	60: #ffc810,
+	70: #f5bc00,
+	80: #cc9c00,
+	90: #a37d00,
+	100: #7a5e00
+);
+
+$daff-red: (
+	10: #fcf1f1,
+	20: #fae0e0,
+	30: #f8babb,
+	40: #f88d8f,
+	50: #fb5d61,
+	60: #ec0019,
+	70: #b30e19,
+	80: #871016,
+	90: #5e0c10,
+	100: #3f0809,
+);
+
+$daff-bronze: (
+	10: #fcf2eb,
+	20: #f7dac6,
+	30: #f2c093,
+	40: #e49d40,
+	50: #d2801a,
+	60: #b36200,
+	70: #955400,
+	80: #704000,
+	90: #462900,
+	100: #1a0f00,
+);
+
+$daff-green: (
+	10: #c4ffcc,
+	20: #6aff86,
+	30: #00db57,
+	40: #13c049,
+	50: #00aa3c,
+	60: #00852e,
+	70: #006b23,
+	80: #004b17,
+	90: #0c3515,
+	100: #07230d,
+);
+
+$daff-gray: (
+	0: #ffffff,
+	10: #fafafa,
+	20: #e8e8e8,
+	30: #d3d3d3,
+	40: #b6b6b6,
+	50: #949494,
+	60: #767676,
+	70: #5e5e5e,
+	80: #474747,
+	90: #323232,
+	100: #1a1a1a,
+	110: #070707
+);