Remove webpack includePath dependency (#43)

The controls library previously depended on a global colors import, which would be resolved to an actual file through a webpack IncludePath declaration. This pattern meant we could not use the library with create-react-app unless we ejected, which is not optimal.

To avoid this, this PR changes the convention to depend on a ./src/styles/_colors.scss file existing at the project root instead. This file is created as a postinstall step when the controls library is installed.

.npmignore

@@ -1,5 +1,6 @@
 dist/
 docs/
+test/
 method-design/
 .sass-lint.yml
 karma.conf.js

CHANGELOG.md

@@ -1,5 +1,14 @@
 # CHANGELOG
 
+## v5.0.0
+### Changed
+- Dependency on a `_colors.scss` existing at the global scope (resolved via webpack `includePath`).
+
+  The controls library now requires the file to exist at `<project root>/src/styles/_colors.scss`. This convention allows the library to be used with an out-of-the-box [create-react-app](https://github.com/facebook/create-react-app) install without ejecting. See the [Azure IoT UX Baseline](https://github.com/Azure/iot-ux-baseline) for an example.
+
+  For ease of use, this file will be automatically created on postinstall if it doesn't already exist.
+
+
 ## v4.0.9
 ### Fixed
 - Calendar component would choose current time first time you are selecting a date. Now defaults to 12:00 AM local

README.md

@@ -1,4 +1,40 @@
-# Azure IoT React Controls
+# Azure IoT UX Fluent Controls
+
+This project contains common React controls (Form Inputs, DateTime etc.) that match the Azure IoT Fluent design.
+
+# Get started
+```
+npm install --save @microsoft/azure-iot-ux-fluent-controls
+```
+
+This project is built on top of [Azure IoT UX Fluent CSS](https://github.com/Azure/iot-ux-fluent-css) and expects it -- along a few other common packages like React -- to be present in your app as peer dependencies. Run the following command to install these:
+```
+npm install --save @microsoft/azure-iot-ux-fluent-css react react-dom classnames prop-types
+```
+
+On install, this project will create a `_colors.scss` file at your `<app root>/src/styles/`. This allows you to override or extend the default colors specified in the CSS library and have it apply to the controls seamlessly. For more details, see the comments and examples in `_colors.scss`.
+
+
+# Quick overview
+The full documentation and sample code for the controls is available at https://aka.ms/iotfluentcontrols, but in general, the pattern is:
+
+```tsx
+import { DateField } from '@microsoft/azure-iot-ux-fluent-controls';
+const initialState = {value: 'Sep 20, 2010 07:00:00 GMT'};
+
+<div>
+    <div style={{marginBottom: '20px'}}>
+        Current Value: {state.value}
+    </div>
+    <DateField
+        name='date-picker'
+        label='Default Example (Local)'
+        onChange={(newValue) => setState({value: newValue}) }
+        initialValue={state.value}
+    />
+</div>
+```
+![Image of DateField control](https://i.imgur.com/KAT2EBf.jpg)
 
 ## Contributing
 
@@ -16,7 +52,7 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 
 
 ## Build
-1. git clone https://github.com/Azure/iot-react-controls.git
+1. git clone https://github.com/Azure/iot-ux-fluent-controls.git
 2. npm install
 3. npm run build
 
@@ -24,11 +60,9 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 1. npm run docs:build
 2. npm run docs
 3. You can now view style guide in the browser:
-
-    - `On Local:`         http://localhost:6060/
-
-    - `On your network:`  http://{machine ip address}:6060/
+    - On local:         http://localhost:6060/
+    - On your network:  http://{machine ip address}:6060/
 
 ## Bug/ Issue
 
-https://github.com/Azure/iot-react-controls/issues
+https://github.com/Azure/iot-ux-fluent-controls/issues

lib/common/_color.controls.scss

@@ -1,15 +1,7 @@
-// The 'colors' file is injected by webpack during build time. The following snippet inside
-// the webpack.config specifies the location of the file:
-//
-//   {
-//      loader: 'sass-loader',
-//      options: {
-//          includePaths: path.resolve(`./template/src/styles`)
-//      }
-//   }
-//
-// This will import './template/src/styles/colors' to be available as 'colors'. This allows 
-// the app to specify one color override file for both the controls and the app. Please
-// see https://github.com/webpack-contrib/sass-loader for further documentation.
-
-@import 'colors';
+// Import the colors specified at <project root>/src/styles/_colors.scss.
+// This allows each project to override or extend the colors specified in
+// @microsoft/azure-iot-ux-fluent-css and have it apply to the controls seamlessly.
+// If we take a direct dependency on the css library here, the per-project
+// customization won't be reflected in the controls.
+// To access the project root, start from '~' (the node_modules folder) and move up:
+@import '~/../src/styles/colors';

lib/components/Shell/Shell.scss

@@ -1,6 +1,6 @@
 @import "~@microsoft/azure-iot-ux-fluent-css/src/normalize";
 @import "~@microsoft/azure-iot-ux-fluent-css/src/icons";
-@import "colors";
+@import '../../common/color.controls';
 
 // provide some common styling that everyone requires:
 :global {

lib/scripts/postinstall.ts

@@ -0,0 +1,42 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as process from 'process';
+import * as util from 'util';
+
+declare const __dirname: string;
+
+const access = util.promisify(fs.access);
+const copyFile = util.promisify(fs.copyFile);
+const mkdir = util.promisify(fs.mkdir);
+
+async function notExists(p: string) {
+    try {
+        await access(p);
+        return false;
+    } catch (err) {
+        return true;
+    }
+}
+
+async function main() {
+    const projectRoot = process.env.INIT_CWD;
+    const srcFolder = path.resolve(projectRoot, 'src');
+    if (await notExists(srcFolder)) {
+        await mkdir(srcFolder);
+    }
+
+    const srcStylesFolder = path.resolve(srcFolder, 'styles');
+    if (await notExists(srcStylesFolder)) {
+        await mkdir(srcStylesFolder);
+    }
+
+    const srcStylesColorsFile = path.resolve(srcStylesFolder, '_colors.scss');
+    if (await notExists(srcStylesColorsFile)) {
+        await copyFile(path.resolve(__dirname, '../../src/styles/_colors.scss'), srcStylesColorsFile);
+    }
+}
+
+main().catch(err => {
+    console.error(err);
+    process.exit(-1);
+});

package.json

@@ -1,7 +1,7 @@
 {
     "name": "@microsoft/azure-iot-ux-fluent-controls",
-    "version": "4.0.9",
-    "description": "Azure IoT Fluent React Controls",
+    "version": "5.0.0",
+    "description": "Azure IoT UX Fluent Controls",
     "main": "./lib/index.js",
     "types": "./lib/index.d.ts",
     "scripts": {
@@ -12,13 +12,16 @@
         "sasslint": "sass-lint -c .sass-lint.yml 'lib/**/*.scss' -v -q",
         "docs": "styleguidist server",
         "docs:build": "styleguidist build",
-        "prepublish": "npm run tslint && npm run test && npm run build"
+        "postinstall": "node ./lib/scripts/postinstall.js",
+        "prepublishOnly": "npm run tslint && npm run test && npm run build"
     },
     "repository": {
         "type": "git",
-        "url": "https://github.com/Azure/iot-ux-fluent-controls/issues"
+        "url": "https://github.com/Azure/iot-ux-fluent-controls.git"
     },
-    "author": "",
+    "homepage": "https://github.com/Azure/iot-ux-fluent-controls#readme",
+    "bugs": "https://github.com/Azure/iot-ux-fluent-controls/issues",
+    "author": "Azure IoT",
     "license": "MIT",
     "engines": {
         "node": ">=8"

src/styles/_colors.scss

@@ -0,0 +1,22 @@
+// WARNING: DO NOT MOVE THIS FILE!
+// The @microsoft/azure-iot-ux-fluent-controls library requires a _colors.scss to
+// exist at the <project root>/src/styles/. This allows each project to override or
+// extend the colors specified in @microsoft/azure-iot-ux-fluent-css and have them
+// apply to the controls seamlessly. The following code demonstrates this pattern:
+
+    // // first import the color palette:
+    // @import "~@microsoft/azure-iot-ux-fluent-css/src/color.palette";
+    // // specify overrides/extensions for the themes:
+    // $theme-dark: (
+    //     color-bg-header: $color-grey-1200,
+    //     color-bg-content: #3d4147,
+    //     color-text-header: $color-white,
+    // );
+
+    // $theme-light: (
+    //     color-bg-header: $color-grey-800,
+    //     color-text-header: $color-white,
+    // );
+
+// as a final step, import the default colors (this will preserve any overrides specified above):
+@import "~@microsoft/azure-iot-ux-fluent-css/src/colors";

webpack.styleguide.js

@@ -45,14 +45,6 @@ module.exports = {
           },
           {
             loader: 'sass-loader',
-            options: {
-              includePaths: [
-                path.resolve(
-                  __dirname,
-                  'node_modules/@microsoft/azure-iot-ux-fluent-css/src/'
-                ),
-              ],
-            },
           },
         ],
       },