Merge pull request #37 from alleyinteractive/feature/component-provider

v3 Feature: Component provider

Author: goodguyry

.babelrc.json

@@ -1,4 +1,7 @@
 {
+  "presets": [
+    "@babel/preset-env",
+  ],
   "env": {
     "es": {
       "plugins": ["@babel/plugin-transform-runtime"],
@@ -13,11 +16,6 @@
     },
     "cjs": {
       "plugins": ["@babel/plugin-transform-runtime"],
-      "presets": [
-        [
-          "@babel/preset-env"
-        ]
-      ]
     }
   }
 }

.eslintrc.json

@@ -2,7 +2,8 @@
   "env": {
     "browser": true,
     "es2021": true,
-    "node": true
+    "node": true,
+    "jest": true
   },
   "extends": ["airbnb"],
   "parser": "@babel/eslint-parser",

.github/workflows/node-tests.yml

@@ -0,0 +1,15 @@
+name: Node Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  node-tests:
+    uses: alleyinteractive/.github/.github/workflows/node-tests.yml@main
+    with:
+      run-build: false

.npmignore

@@ -1,2 +1 @@
 /src/
-/examples/

CHANGELOG.md

@@ -0,0 +1,120 @@
+# Change Log
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## 3.0.0
+
+**Added**
+
+* Adds `componentProvider` for initializing and loading components
+* Adds `componentLoader` for optionally loading the function returned from `componentProvider`
+
+**Changed**
+
+* Simplifies component creation by allowing components to be a class or a function
+* No longer writes to `window[manifest]`
+* Replaces `ComponentManager` with `initComponents` for initializing legacy components using the `/v2` export
+* Moves `Component` to the `/v2` export
+
+**Fixed**
+
+* Moves `@babel/runtime` to devDependencies
+
+**Removed**
+
+* Removes the rate limiter
+* Removes Aria plugins; consider using [aria-components](https://www.npmjs.com/package/aria-components) instead.
+* Removes the `/core` export due to code restructuring
+
+## 2.1.0
+
+Adds an ES Module export to reduce bundle sizes
+
+## 2.0.0
+
+**Changed**
+
+* Reduce the size of the framework by adding a core/ directory which does not include the Aria plugins
+* Updates babel configs and plugins
+* Updates ESLint config and include Airbnb standards
+
+**Removed**
+
+* Polyfills and support for IE
+
+## 1.2.6
+
+Automated security updates
+
+## 1.2.5
+
+**Changed**
+
+* Moved rate limiter to standalone function.
+
+**Removed**
+
+* Bottleneck library
+
+## 1.2.4
+
+Automated security updates
+
+## 1.2.2
+
+**Fixed**
+
+* Bottleneck updates caused missing polyfills and non-transpiled code
+
+**Changed**
+
+* Updates Bottleneck package to latest
+
+**Added**
+
+* Babel polyfills and plugins relative to bottleneck package update
+* Browserlist settings to package.json
+
+## 1.2.1
+
+**Fixed**
+
+Bugs related to the hasTransition option for AriaPlugin
+
+## 1.2.0
+
+Updates to Aria classes.
+
+**Fixed**
+
+* Prevents arrow keys from activating out-of-bounds tabs
+
+**Added**
+
+* hasTransition option to delay focus, etc. until after transition
+* Target and controller now have a reference to the parent popup
+* loadOpen config option
+
+**Changed**
+
+* Normalizes Aria event names
+* Refactors AriaTablist setup to verify markup
+
+**Removed**
+
+* Removes breakpoint option and related code
+* Event listeners on ariaDestroy
+* First item focus for popups
+
+## 1.0.3
+
+**Added**
+
+Aria plugins.
+
+## 1.0.1
+
+Documentation updates.
+
+## 1.0.0
+
+Initial release.

README.md

@@ -1,118 +1,147 @@
-# Component Framework
+JS Component Framework
+======================
 
-A framework for attaching an ES6 class to a DOM element or collection of DOM elements, making it easier to organize the DOM interactions on your website.
+A zero-dependency framework for configuring a JavaScript component and attaching it to a DOM element or collection of DOM elements, simplifying organization of DOM interactions on your website.
 
-## How it works
+Components can be ES6 classes or simple functions, and their child nodes are collected automatically based on the component configuration and passed to the component, which reduces or removes the need to write DOM queries for each component.
 
-A high-level overview on how it works. You ...
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Mqxx/GitHub-Markdown/main/blockquotes/badge/light-theme/warning.svg">
+  <img alt="Warning" src="https://raw.githubusercontent.com/Mqxx/GitHub-Markdown/main/blockquotes/badge/dark-theme/warning.svg">
+</picture><br>
 
-* provide a configuration and an ES6 class (which extends the base Component class).
-* create a ComponentManager and call its `instanceComponents` method, passing it one or more component configurations created in the previous step.
+Version 3.0.0 contains breaking changes. See [v2 documentation](src/v2/) for backward compatibility.
 
-The library will ...
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Mqxx/GitHub-Markdown/main/blockquotes/badge/light-theme/info.svg">
+  <img alt="Info" src="https://raw.githubusercontent.com/Mqxx/GitHub-Markdown/main/blockquotes/badge/dark-theme/info.svg">
+</picture><br>
 
-* loop through every element match it finds for `data-component={componentName}` in your configuration and start an instance of the component class.
-* add each instance of the component to a global manifest on the `window` object, using a property provided when you instanced the manager.
-
-This results in distinct (and encapsulated) functionality for each DOM element.
+**Coming from a previous version?** Find full upgrade documentation in [the Wiki](https://github.com/alleyinteractive/js-component-framework/wiki/Updating-to-v3).
 
 ## Getting Started
 
-Install the js-component-framework and all the plugins:
+Install js-component-framework from [NPM](https://www.npmjs.com/package/js-component-framework).
+
 ```bash
 npm install js-component-framework
 ```
-Below is a basic set up for using the component framework without the included Aria plugins:
+
+## Creating a Component
+
+Component elements are denoted by a `data-component` attribute, the value of which is used to match the component to its element(s).
+
+```
+<header data-component="site-header">...</header>
+```
+
+### The Configuration Object
+
+**name**: _(Required)_ - The component name. This must match the component root element's `data-component` attribute value.
+
+**component**: _(Required)_ - A component can be created as an ES6 class or a function. This property accepts the exported class or function to be initialized for the component.
+
+**querySelector**: _(Optional)_ - An object mapping of `name: selector` pairs matching a single child element of the component. Each selector is passed to `querySelector()` and the result is passed to as component's `children` property. For example, if you provide `{ title: '.site-title' }`, the element will be accessible in your component as `children.title`.
+
+**querySelectorAll**: _(Optional)_ - Same as `querySelector`, but each selector is passed to `querySelectorAll()` and returned as an array of elements for each selector.
+
+**options**: _(Optional)_ - An arbitrary value, typically an object, used by the component. This could be a configuration for another JS library, values used for calculating styles, etc. This is passed to the wrapped function as the `options` property.
+
+**load**: _(Optional)_ - Accepts `false`, array, or a callback. _Default is a `domContentLoaded` callback_.
+
+* `false` will disable loading and instruct `componentProvider` to return the provider function
+* An array, in the format of `[HTMLElement, event]`, will listen on `HTMLElement` for `event` (e.g., `[window, 'load']`)
+* A callback that accepts a function and contains the logic to call the function
+
+### Component Properties
+
+Components receive an object of component properties as their only argument. These are based on the config and are included automatically by the framework.
+
+**element**: the `data-component` element to which the component is attached
+
+**children**: the component’s child elements as described in `config.querySelector` and `config.querySelectorAll`
+
+**options**: the `config.options` value, if any
+
+#### Functional Components
+
+Functional components receive the object of component properties as their only parameter.
 
 ```javascript
-// Import the ES modules to be consumed by a bundler such as webpack append the '/es' to the end of the import statement.
-import { Component } from 'js-component-framework/es';
-
-/**
- * Custom component which extends the base component class.
- */
-class MyComponent extends Component {
-
-  /**
-   * Start the component
-   */
-  constructor(config) {
-    super(config);
-  }
-}
+function myComponent({ element, children, options }) { ... }
 ```
 
-If you also want to use the entire framework using the CommonJS bundled scripts with Aria plugins use the default import:
-```js
-import { Component, plugins } from 'js-component-framework';
+#### Classical Components
+
+For classical components, the object of component properties is passed as the constructor's only parameter.
+
+```javascript
+class MyComponent {
+  constructor({ element, children, options }) { ... }
+}
 ```
 
-## Best practices for creating components
+## Loading Components
 
-### Create one directory per component
+Due to the nature of the component framework, components must be prepared for loading prior to initialization. By default, the function that performs this preparation will also load the component.
 
-It will contain the configuration file and the class.
+### componentProvider
 
-### The configuration file
+`componentProvider` creates a provider function that contains all the properties and DOM querying logic necessary for all instances of the component to be initialized.
 
-Use the convention `index.js`, as this will be the default export for the component. The configuration requires several properties:
+The component will automatically be initialized according to the `config.load` value. If `config.load` is `false`, the provider function is returned.
 
-* `name` - *required* - **THIS _MUST_ BE UNIQUE**. An arbitrary name for the component. This is used to find component elements via data attribute `data-component="componentName"`. `name` is also used to store instances of the component in the global manifest.
-* `class` - *required* - The imported ES6 class for the component.
-* `querySelector` - *optional* - An object containing child selectors you'll need for the component logic. Each of these selectors should correspond to an element of which there is only one within the component (and will be queried using the `querySelector` JS method). The base Component class will automatically query these selectors and add them as properties to the class (using the provided object keys). For example, if you provide `title: '.site-title'`, this will be accessible in your component class as `this.children.title`.
-* `querySelectorAll` - *optional* - Same as `querySelector`, but will provide an array of each element it finds matching the selector.
-* `options` - *optional* - An object containing arbitrary additional options for the component. This could be a configuration for another JS library, values used for calculating styles, etc.
+**Parameters**
 
-[See the Header example](./examples/Header/index.js) for context.
+**config** _(Required)_ A component config object.
 
-### The component class
+```javascript
+import { componentProvider } from 'js-component-framework';
+
+function productDetails({ element, children, options }) { ... }
 
-To create a component, do the following at the top of the file:
+const productDetailsConfig = {
+  name: 'product-details',
+  component: productDetails,
+  // load: false | array | function
+  querySelectorAll: {
+    toggles: '.product-details__toggle',
+  },
+};
 
-```js
-import { Component } from 'js-component-framework';
+componentProvider(productDetailsConfig);
 ```
 
-If you are compiling your code with a bundler like webpack, only import what you need for a smaller footprint:
-```js
-import { Component } from 'js-component-framework/es';
+When using a bundler like webpack, import the ES module for a smaller footprint:
+
+```javascript
+import { componentProvider } from 'js-component-framework/es';
 ```
 
-When writing a component class, are some rules you need to follow and some guidelines:
+### componentLoader
 
-* You _must_ provide a constructor. At minimum, the constructor should look like the following:
-	```js
-	constructor(config) {
-		super(config);
-	}
-	```
-	This constructor will be called when ComponentManager instances your component, your configuration passed in, then passed to the parent Component class using the `super()` function.
-* Don't perform much logic within the class constructor. Instead, separate logic into distinct methods, each for a specific purpose. Use the constructor to call these methods and initialize any runtime component logic, event listeners, calculations, etc.
-* Any method you might call from another component or use as a callback for an event listener should be bound to the component class using `this.myMethod = this.myMethod.bind(this)`. Methods can be called from other components using the component manager via `manager.callComponentMethod`. See the ComponentManager class for documentation.
+`componentLoader` is used by `componentProvider` to load components. It is exported individually for cases where one doesn't want `componentProvider` to load the provider function automatically.
 
-[See the Header example](./examples/Header/Header.js) for context.
+**Parameters**
 
-## How to instantiate components
+**providerFunction**: _(Required)_ A function returned from `componentProvider`.
 
-Import the component config in one of your entry point files, and pass that config to the ComponentManager's instanceComponents method.
+**load**: _(Optional)_ A valid `config.load` value. _Default is a `domContentLoaded` callback_.
 
-Generally speaking, you'll want to instantiate your component in the footer or on `DOMContentLoaded`.
+```javascript
+// my-component/my-component.js
 
-```js
+const wrappedComponent = componentProvider(config); // config.load === false
+export default wrappedComponent;
+```
 
-import { ComponentManager } from `js-component-framework/es`;
-import headerConfig from `./Components/Header`;
+```javascript
+// my-component/index.js
 
-// Instantiate manager
-// "namespace" can be any string to namespace this instance of the manager
-const manager = new ComponentManager('namespace');
+import { componentLoader } from 'js-component-framework';
+import wrappedComponent from './my-component';
 
-// Create component instances
-document.addEventListener('DOMContentLoaded', () => {
-  manager.initComponents([
-    headerConfig
-  ]);
-});
+// This is a contrived example; in a real-world component this same outcome can 
+// be accomplished simply by setting the config load value to `[window, 'load']`
+componentLoader(wrappedComponent, [window, 'load']);
 ```
-
-Be sure you've added the appropriate data attribute containing your configured `name` to the element(s) on which you want this component to be attached. For example, add `data-component="siteHeader"` to instance [the Header component](./examples/Header/Header.js), assuming you configured the Header component `name` to be `siteHeader`.