feat(project): add feature-flags package (#6401)

* feat(project): add feature-flags package

* chore: check-in work

* chore(feature-flags): finalize work

* chore(project): sync offline mirror

* chore(feature-flags): format files

* chore(feature-flags): fix eslint violations

Co-authored-by: TJ Egan <[email protected]>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

.prettierignore

@@ -48,3 +48,6 @@ packages/components/docs/js
 
 # Yarn
 **/.yarn/**
+
+# Generated files
+**/generated/**

packages/feature-flags/.gitignore

@@ -0,0 +1 @@
+**/generated/**

packages/feature-flags/.npmignore

@@ -0,0 +1,4 @@
+**/__mocks__/**
+**/__tests__/**
+**/examples/**
+**/tasks/**

packages/feature-flags/README.md

@@ -0,0 +1,114 @@
+# @carbon/feature-flags
+
+> Build with feature flags in Carbon
+
+## Getting started
+
+To install `@carbon/feature-flags` in your project, you will need to run the
+following command using [npm](https://www.npmjs.com/):
+
+```bash
+npm install -S @carbon/feature-flags
+```
+
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
+instead:
+
+```bash
+yarn add @carbon/feature-flags
+```
+
+## Usage
+
+The `@carbon/feature-flags` provides a runtime-based feature flag system that
+you can use to enable or disable experimental features from Carbon or in your
+own code.
+
+To enable a feature flag, you will need to enable it in each of the environments
+that you're using it in. Often times, this will mean JavaScript, Sass, or both.
+
+To enable a flag in JavaScript, you would use `enableFeatureFlag`:
+
+```js
+import { enableFeatureFlag } from '@carbon/feature-flags';
+
+enableFeatureFlag('feature-flag-name');
+```
+
+To enable a flag in Sass, you would set the `$feature-flags` variable:
+
+```scss
+@import '@carbon/feature-flags/scss/feature-flags';
+
+$feature-flags: map-merge(
+  $feature-flags,
+  (
+    'feature-flag-name': true,
+  )
+);
+```
+
+### Managing and using feature flags
+
+You can use the `@carbon/feature-flags` package to build on top of existing
+feature flags, or to add your own.
+
+You can add and toggle flags in JavaScript and Sass. In JavaScript, this would
+look like:
+
+```js
+import {
+  addFeatureFlag,
+  enableFeatureFlag,
+  disableFeatureFlag,
+  featureFlagEnabled,
+} from '@carbon/feature-flags';
+
+// Specify a default value for the flag
+addFeatureFlag('feature-flag-name', false);
+
+// You can use `featureFlagEnabled` to conditionally run
+// branches of your code
+if (featureFlagEnabled('feature-flag-name')) {
+  // Run code if the flag is enabled
+}
+
+// You can also modify the value of the flag
+disableFeatureFlag('feature-flag-name');
+enableFeatureFlag('feature-flag-name');
+```
+
+In Sass, you would write the following:
+
+```scss
+@import '@carbon/feature-flags/scss/feature-flags';
+
+$feature-flags: map-merge(
+  $feature-flags,
+  (
+    'feature-flag-name': true,
+  )
+);
+
+@if feature-flag-enabled('feature-flag-name') {
+  // ...
+}
+
+// You can also run this as a mixin to conditionally include
+// code
+.my-selector {
+  @include feature-flag-enabled('feature-flag-name') {
+    // ...
+  }
+}
+```
+
+## 🙌 Contributing
+
+We're always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you're interested, definitely
+check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀
+
+## 📝 License
+
+Licensed under the [Apache 2.0 License](/LICENSE).

packages/feature-flags/__tests__/feature-flags-test.js

@@ -0,0 +1,40 @@
+/**
+ * Copyright IBM Corp. 2015, 2020
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {
+  addFeatureFlag,
+  enableFeatureFlag,
+  disableFeatureFlag,
+  featureFlagEnabled,
+} from '../src';
+
+describe('@carbon/feature-flags', () => {
+  it('should let the user check if a feature flag is enabled', () => {
+    addFeatureFlag('test', false);
+    expect(featureFlagEnabled('test')).toBe(false);
+
+    enableFeatureFlag('test');
+    expect(featureFlagEnabled('test')).toBe(true);
+
+    disableFeatureFlag('test');
+    expect(featureFlagEnabled('test')).toBe(false);
+  });
+
+  it('should throw an error if a flag does not exist', () => {
+    expect(() => {
+      enableFeatureFlag('does-not-exist');
+    }).toThrow();
+
+    expect(() => {
+      disableFeatureFlag('does-not-exist');
+    }).toThrow();
+
+    expect(() => {
+      featureFlagEnabled('does-not-exist');
+    }).toThrow();
+  });
+});

packages/feature-flags/__tests__/scss-test.js

@@ -0,0 +1,57 @@
+/**
+ * Copyright IBM Corp. 2015, 2020
+ *
+ * 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 { convert, createSassRenderer } = require('@carbon/test-utils/scss');
+
+const render = createSassRenderer(__dirname);
+
+describe('feature-flags.scss', () => {
+  it('should support default feature flags before the import', async () => {
+    const { calls } = await render(`
+      $feature-flags: ('test': true);
+
+      @import '../scss/feature-flags';
+
+      @if feature-flag-enabled('test') {
+        $t: test(true);
+      }
+    `);
+
+    expect(calls.length).toBe(1);
+    expect(convert(calls[0][0])).toBe(true);
+  });
+
+  it('should support modifying flags', async () => {
+    const { calls } = await render(`
+      @import '../scss/feature-flags';
+
+      $feature-flags: map-merge($feature-flags, (
+        'test': true,
+      ));
+
+      @if feature-flag-enabled('test') {
+        $t: test('feature-flag-enabled');
+      }
+
+      $feature-flags: map-merge($feature-flags, (
+        'test': false,
+      ));
+
+      @if not feature-flag-enabled('test') {
+        $t: test('feature-flag-disabled');
+      }
+    `);
+
+    expect(calls.length).toBe(2);
+    expect(convert(calls[0][0])).toBe('feature-flag-enabled');
+    expect(convert(calls[1][0])).toBe('feature-flag-disabled');
+  });
+});

packages/feature-flags/feature-flags.yml

@@ -0,0 +1,11 @@
+#
+# Copyright IBM Corp. 2015, 2020
+#
+# This source code is licensed under the Apache-2.0 license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+feature-flags:
+  - name: enable-css-custom-properties
+    description: Describe what the flag does
+    enabled: false

packages/feature-flags/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@carbon/feature-flags",
+  "private": true,
+  "description": "Build with feature flags in Carbon",
+  "version": "0.0.0",
+  "license": "Apache-2.0",
+  "main": "lib/index.js",
+  "module": "es/index.js",
+  "repository": "https://github.com/carbon-design-system/carbon/tree/master/packages/feature-flags",
+  "bugs": "https://github.com/carbon-design-system/carbon/issues",
+  "keywords": [
+    "ibm",
+    "carbon",
+    "carbon-design-system",
+    "components",
+    "react"
+  ],
+  "scripts": {
+    "build": "yarn clean && node tasks/build.js && rollup -c",
+    "clean": "rimraf es lib scss/generated src/generated",
+    "watch": "yarn clean && node tasks/build.js && rollup -c -w"
+  },
+  "devDependencies": {
+    "@babel/generator": "^7.10.2",
+    "@babel/types": "^7.10.2",
+    "@carbon/scss-generator": "^10.8.0",
+    "fs-extra": "^9.0.1",
+    "js-yaml": "^3.14.0",
+    "rimraf": "^3.0.2",
+    "rollup": "^2.17.0",
+    "rollup-plugin-strip-banner": "^2.0.0"
+  }
+}

packages/feature-flags/rollup.config.js

@@ -0,0 +1,48 @@
+/**
+ * Copyright IBM Corp. 2015, 2020
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import path from 'path';
+import stripBanner from 'rollup-plugin-strip-banner';
+
+const BANNER = `/**
+ * Copyright IBM Corp. 2015, 2020
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+`;
+
+const baseConfig = {
+  external: [],
+  plugins: [
+    stripBanner(),
+    {
+      renderChunk(code) {
+        return `${BANNER}\n${code}`;
+      },
+    },
+  ],
+};
+
+export default [
+  {
+    ...baseConfig,
+    input: path.join(__dirname, './src/index.js'),
+    output: {
+      file: 'es/index.js',
+      format: 'esm',
+    },
+  },
+  {
+    ...baseConfig,
+    input: path.join(__dirname, './src/index.js'),
+    output: {
+      file: 'lib/index.js',
+      format: 'commonjs',
+    },
+  },
+];

packages/feature-flags/scss/feature-flags.scss

@@ -0,0 +1,30 @@
+//
+// Copyright IBM Corp. 2015, 2020
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@import 'generated/feature-flags';
+
+$feature-flags: () !default;
+$feature-flags: map-merge($generated-feature-flags, $feature-flags);
+
+/// Check if a feature flag is enabled
+/// @param {String} $name
+/// @returns {Boolean}
+@function feature-flag-enabled($name) {
+  @if (map-has-key($feature-flags, $name)) {
+    @return map-get($feature-flags, $name);
+  }
+  @error 'Unable to find feature flag named #{$name}';
+}
+
+/// Emit the content of the mixin if the feature flag is enabled
+/// @param {String} $name
+/// @content
+@mixin feature-flag-enabled($name) {
+  @if feature-flag-enabled($name) {
+    @content;
+  }
+}