@carbon/themes 10.37.0 → 10.39.0

package/README.md

@@ -93,11 +93,18 @@ import {
 } from '@carbon/themes';
 ```
 
+## 📖 API Documentation
+
+If you're looking for `@carbon/themes` API documentation, check out:
+
+- [Sass](./docs/sass.md)
+
 ## 📚 Examples
 
 If you're looking for more examples on how to use `@carbon/themes`, we have some
 examples that you can check out:
 
+- [preview-v11](./examples/preview-v11)
 - [sass-modules](./examples/sass-modules)
 
 ## 🙌 Contributing

package/docs/sass.md

@@ -0,0 +1,96 @@
+# `@carbon/themes`
+
+_Note: this documentation is used with the next version of `@carbon/themes`
+which uses Sass Modules. It will not work in the current stable version of this
+package_
+
+<!-- prettier-ignore-start -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Usage](#usage)
+- [FAQ](#faq)
+  - [Why are the themes not exported in `@carbon/themes`?](#why-are-the-themes-not-exported-in-carbonthemes)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- prettier-ignore-end -->
+
+## Usage
+
+There are several entrypoints that you can use with `@carbon/themes`, including:
+
+| Filename                                     | Description                                            |
+| -------------------------------------------- | ------------------------------------------------------ |
+| `@use '@carbon/themes';`                     | Package entrypoint                                     |
+| `@use '@carbon/themes/scss/modules/config';` | Specify config options for the package                 |
+| `@use '@carbon/themes/scss/modules/themes';` | Theme definitions for white, g10, g90, and g100        |
+| `@use '@carbon/themes/scss/modules/theme';`  | Set the current theme, get token values from the theme |
+| `@use '@carbon/themes/scss/modules/tokens';` | Access theme tokens                                    |
+
+_Note: the white, g10, g90, and g100 themes are only available in the
+`scss/modules/themes` file and are not re-exported in `@carbon/themes`. To learn
+more, checkout our [FAQ](#why-are-the-themes-not-exported-in-carbonthemes)._
+
+You can bring in `@carbon/themes` by using `@use`:
+
+```scss
+@use '@carbon/themes';
+
+.my-component {
+  // Use tokens from the theme, this will map to a CSS Custom Property
+  color: themes.$token-01;
+}
+
+:root {
+  // Emit CSS Custom Properties for the current theme
+  @include themes.theme();
+}
+
+// Get the value of a specific token
+$custom-variable: rgba(themes.get('token-01'), 0.25);
+```
+
+You can configure the current theme with the `$theme` option:
+
+```scss
+@use '@carbon/themes/scss/modules/themes';
+@use '@carbon/themes' with (
+  $theme: themes.$g100,
+);
+```
+
+You can also extend the theme with your own custom tokens:
+
+```scss
+@use '@carbon/themes/scss/modules/themes';
+@use '@carbon/themes' with (
+  $fallback: themes.$g100,
+  $theme: (
+    token-01: #000000,
+  ),
+);
+```
+
+## Tokens
+
+TODO
+
+## FAQ
+
+### Why are the themes not exported in `@carbon/themes`?
+
+In order to support `@use '@carbon/themes' with` in Sass Modules, unfortunately
+we cannot re-export the themes available in `scss/modules/themes`. If we
+implemented the entrypoint at `@carbon/themes` to re-export that module, then
+Sass would not compile when doing the following:
+
+```scss
+@use '@carbon/themes/scss/modules/themes';
+@use '@carbon/themes' with (
+  $theme: themes.$g100,
+);
+```
+
+This is because the `scss/modules/themes` file will have been initialized twice
+which is not allowed in the Sass Module system.

package/index.scss

@@ -5,6 +5,6 @@
 // LICENSE file in the root directory of this source tree.
 //
 
-@forward 'scss/modules/themes';
+@forward 'scss/modules/config';
 @forward 'scss/modules/theme';
 @forward 'scss/modules/tokens';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carbon/themes",
   "description": "Themes for applying color in the Carbon Design System",
-  "version": "10.37.0",
+  "version": "10.39.0",
   "license": "Apache-2.0",
   "main": "lib/index.js",
   "module": "es/index.js",
@@ -26,16 +26,18 @@
   "scripts": {
     "ci-check": "carbon-cli check \"scss/**/*.scss\" -i \"**/generated/**\"",
     "clean": "rimraf es lib umd scss/generated",
-    "build": "yarn clean && carbon-cli bundle src/index.js --name CarbonThemes && node tasks/build.js && carbon-cli check \"scss/*.scss\""
+    "build": "yarn clean && carbon-cli bundle src/index.js --name CarbonThemes && babel-node --presets '@babel/preset-env' tasks/build.js && carbon-cli check \"scss/*.scss\""
   },
   "dependencies": {
-    "@carbon/colors": "^10.27.0",
-    "@carbon/layout": "^10.26.0",
-    "@carbon/type": "^10.30.0",
+    "@carbon/colors": "^10.29.0",
+    "@carbon/layout": "^10.28.0",
+    "@carbon/type": "^10.32.0",
     "color": "^3.1.2"
   },
   "devDependencies": {
-    "@carbon/cli": "^10.25.0",
+    "@babel/node": "^7.14.2",
+    "@babel/preset-env": "^7.14.2",
+    "@carbon/cli": "^10.26.0",
     "@carbon/cli-reporter": "^10.5.0",
     "@carbon/scss-generator": "^10.13.0",
     "@carbon/test-utils": "^10.16.0",
@@ -46,5 +48,6 @@
     "node-sass": "^4.13.1",
     "rimraf": "^3.0.0"
   },
-  "gitHead": "74da5c7df7a93263ed79ed9b3dd6dc2b52d80024"
+  "sideEffects": false,
+  "gitHead": "388008d11f2996c262303445a2e26453cbda9261"
 }

package/scss/modules/_config.scss

@@ -0,0 +1,8 @@
+//
+// 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.
+//
+
+$prefix: 'cds' !default;

package/scss/modules/_theme.scss

@@ -7,18 +7,23 @@
 
 @use 'sass:map';
 @use 'sass:meta';
+@use 'config';
 @use 'themes';
 
-$theme: themes.$white !default;
-$-custom-property-prefix: 'cds';
+/// Specify the fallback theme, used as a catch-all for tokens that you may not
+/// have defined in your custom theme
+$fallback: themes.$white !default;
 
-/// @access public
-/// @group @carbon/themes
-@mixin theme($active-theme: $theme, $component-tokens...) {
-  $parent-theme: $theme;
-  $theme: $active-theme !global;
+/// Specify the current theme. This can override existing tokens, or add new
+/// tokens. If you are adding new tokens, it's recommended that you set the
+/// fallback for your current theme
+$theme: () !default;
+$theme: map.merge($fallback, $theme);
 
-  @each $token, $value in $theme {
+/// Include the CSS Custom Properties for the active theme or a given theme on
+/// a selector
+@mixin theme($active-theme: $theme, $component-tokens...) {
+  @each $token, $value in $active-theme {
     @include -custom-property($token, $value);
   }
 
@@ -27,21 +32,20 @@ $-custom-property-prefix: 'cds';
       @include -custom-property($token, $value);
     }
   }
-
-  @content;
-
-  $theme: $parent-theme !global;
 }
 
-/// @access public
-/// @group @carbon/themes
-@mixin set-theme($active-theme) {
-  $theme: $active-theme !global;
+/// Retrieve the value for the given $token from the current $theme
+/// @param {String} $token
+@function get($token) {
+  @if map.has-key($theme, $token) {
+    @return map.get($theme, $token);
+  }
+  @error "Unable to find token: #{$token} in current $theme";
 }
 
 /// @access private
 /// @group @carbon/themes
-@mixin -custom-property($name, $value, $prefix: $-custom-property-prefix) {
+@mixin -custom-property($name, $value) {
   @if meta.type-of($value) == map {
     @each $property, $property-value in $value {
       // Only support one-level of depth for values that are maps. This is to
@@ -51,6 +55,6 @@ $-custom-property-prefix: 'cds';
       }
     }
   } @else {
-    --#{$prefix}-#{$name}: #{$value};
+    --#{config.$prefix}-#{$name}: #{$value};
   }
 }

package/scss/modules/_themes.scss

@@ -6,3 +6,4 @@
 //
 
 @forward 'generated/themes';
+@use 'generated/themes';