feat(styles): add support for layer sets

packages/styles/package.json

@@ -27,6 +27,7 @@
     "@carbon/type": "^10.31.0"
   },
   "devDependencies": {
-    "@carbon/test-utils": "^10.16.0"
+    "@carbon/test-utils": "^10.16.0",
+    "css": "^3.0.0"
   }
 }

packages/styles/scss/utilities/__tests__/custom-property-test.js

@@ -0,0 +1,50 @@
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const { SassRenderer } = require('@carbon/test-utils/scss');
+const css = require('css');
+
+const { render } = SassRenderer.create(__dirname);
+
+describe('scss/utilities/custom-property', () => {
+  it('should support getting the property name from a value', async () => {
+    const { unwrap } = await render(`
+      @use '../../config' with (
+        $prefix: 'cds',
+      );
+      @use '../custom-property';
+
+      $_: get('name', custom-property.get-name('test'));
+    `);
+    expect(unwrap('name')).toBe('--cds-test');
+  });
+
+  it('should support emitting a declaration for a CSS Custom Property', async () => {
+    const { result } = await render(`
+      @use '../../config' with (
+        $prefix: 'cds',
+      );
+      @use '../custom-property';
+
+      .test {
+        @include custom-property.declaration(test, #000000);
+      }
+    `);
+    const { stylesheet } = css.parse(result.css.toString());
+    const selector = stylesheet.rules.find((rule) => {
+      return rule.selectors.includes('.test');
+    });
+    const [declaration] = selector.declarations;
+
+    expect(declaration.property).toBe('--cds-test');
+    expect(declaration.value).toBe('#000000');
+  });
+});

packages/styles/scss/utilities/__tests__/layer-set-test.js

@@ -0,0 +1,78 @@
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const { SassRenderer } = require('@carbon/test-utils/scss');
+const css = require('css');
+
+const { render } = SassRenderer.create(__dirname);
+
+describe('scss/utilities/layer-set', () => {
+  it('should map layer set values to scoped $prefix--layer selectors', async () => {
+    const { result } = await render(`
+      @use '../../config' with (
+        $prefix: 'cds',
+      );
+      @use '../layer-set' with (
+        $layer-sets: (
+          field: (
+            rgba(0, 0, 0, 0.3),
+            rgba(0, 0, 0, 0.2),
+            rgba(0, 0, 0, 0.1),
+          ),
+          background: (
+            rgba(0, 0, 0, 0.8),
+            rgba(0, 0, 0, 0.7),
+            rgba(0, 0, 0, 0.6),
+          ),
+        )
+      );
+    `);
+    const { stylesheet } = css.parse(result.css.toString());
+
+    function findSelector(stylesheet, matcher) {
+      return stylesheet.rules.find((rule) => {
+        return rule.selectors.some((selector) => {
+          return selector.includes(matcher);
+        });
+      });
+    }
+
+    function findDeclaration(rule, property) {
+      return rule.declarations.find((declaration) => {
+        return declaration.property.includes(property);
+      });
+    }
+
+    const layer1 = findSelector(stylesheet, ':root');
+    const layer2 = findSelector(stylesheet, '.cds--layer');
+    const layer3 = findSelector(stylesheet, '.cds--layer .cds--layer');
+
+    expect(findDeclaration(layer1, '--cds-field').value).toBe(
+      'rgba(0, 0, 0, 0.3)'
+    );
+    expect(findDeclaration(layer2, '--cds-field').value).toBe(
+      'rgba(0, 0, 0, 0.2)'
+    );
+    expect(findDeclaration(layer3, '--cds-field').value).toBe(
+      'rgba(0, 0, 0, 0.1)'
+    );
+
+    expect(findDeclaration(layer1, '--cds-background').value).toBe(
+      'rgba(0, 0, 0, 0.8)'
+    );
+    expect(findDeclaration(layer2, '--cds-background').value).toBe(
+      'rgba(0, 0, 0, 0.7)'
+    );
+    expect(findDeclaration(layer3, '--cds-background').value).toBe(
+      'rgba(0, 0, 0, 0.6)'
+    );
+  });
+});

packages/styles/scss/utilities/_custom-property.scss

@@ -0,0 +1,45 @@
+//
+// Copyright IBM Corp. 2018, 2018
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@use '../config';
+
+// Some CSS Custom Property terminology
+// @see https://www.w3.org/TR/css-variables-1/
+//
+// <custom-property-name>:
+//   Any valid identifer that starts with two dashes (--)
+//
+// A declaration:
+//   CSS Custom Properties can be used as declarations in a CSS selector. They
+//   take on the form of:
+//
+//   <custom-property-name>: <declaration-value>;
+//
+// The var() notation:
+//   You can use a CSS Custom Property as a substitute for a value of another
+//   property using the var() function. This function has the following syntax:
+//
+//   var( <custom-property-name> [, <declarative-value> ]? )
+//
+//   This function takes in an optional fallback value if the CSS Custom
+//   Property has not been previously defined
+
+/// Get the <custom-property-name> for a given string
+/// @param {String} $name
+/// @returns {String}
+@function get-name($name) {
+  @return --#{config.$prefix}-#{$name};
+}
+
+/// Emit a declaration which sets the value of a CSS Custom Property using the
+/// $name as the <custom-property-name> and the $value as the
+/// <declaration-value>
+/// @param {String} $name
+/// @param {any} $value
+@mixin declaration($name, $value) {
+  #{get-name($name)}: #{$value};
+}

packages/styles/scss/utilities/_layer-set.scss

@@ -0,0 +1,38 @@
+//
+// Copyright IBM Corp. 2021
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@use 'sass:list';
+@use 'sass:meta';
+@use '../config' as *;
+@use './custom-property';
+
+/// Define a map of layer sets, each set should have values for each layer in
+/// the application. The key of this map is used for the CSS Custom Property
+/// name whose value is updated as more layers are added.
+/// @type {Map}
+$layer-sets: () !default;
+
+/// Emit the layer tokens defined in $layer-sets for the given $level
+/// @param {Number} $level
+@mixin -emit-layer-tokens($level) {
+  @each $key, $layer-set in $layer-sets {
+    $value: list.nth($layer-set, $level);
+    @include custom-property.declaration($key, $value);
+  }
+}
+
+:root {
+  @include -emit-layer-tokens(1);
+}
+
+.#{$prefix}--layer {
+  @include -emit-layer-tokens(2);
+
+  .#{$prefix}--layer {
+    @include -emit-layer-tokens(3);
+  }
+}

yarn.lock

@@ -2055,6 +2055,7 @@ __metadata:
     "@carbon/test-utils": ^10.16.0
     "@carbon/themes": ^10.38.0
     "@carbon/type": ^10.31.0
+    css: ^3.0.0
   languageName: unknown
   linkType: soft