@grrr/hansel - npm Package Compare versions

Comparing version 2.0.4 to 2.1.0

package.json

 {
   "name": "@grrr/hansel",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "Runner of handlers/enhancers.",
@@ -5,0 +5,0 @@ "main": "index.mjs",

README.md

@@ -5,3 +5,3 @@ # Hansel
 
-### Runner of handlers and enhancers
+### Runner of JavaScript handlers and enhancers
 
@@ -13,5 +13,5 @@ - Lightweight (less than 1kb minified and gzipped)
 Based on the article ["Progressive enhancement with handlers and enhancers" by Hidde de Vries](https://hiddedevries.nl/en/blog/2015-04-03-progressive-enhancement-with-handlers-and-enhancers).
-We've been using this model for many years with great pleasure, fine-tuning here and there.
+We've been using this model for many years with great pleasure, fine-tuning here and there. Read the article for a deeper explanation.
 
-Read the article for a deeper explanation.
+Built with ❤️ by [GRRR](https://grrr.tech).
 
@@ -21,10 +21,9 @@
 
-Using npm:
-
+```sh
+$ npm install @grrr/hansel
 ```
-npm install @grrr/hansel
-```
 
-Note: depending on your setup additional configuration might be needed ([see below](#usage-with-build-tools)).
+Note: depending on your setup [additional configuration might be needed](https://github.com/grrr-amsterdam/hansel/wiki/Usage-with-build-tools), since this package is published with untranspiled JavaScript.
 
+
 ## Usage
@@ -38,23 +37,39 @@
 enhance(document.documentElement, {
-    enhancer1(elm) {
-    },
-    enhancer2(elm) {
-    },
-    enhancerN(elm) {
-    }
+  enhancer1(elm) {
+    // Enhance elements with this enhancer.
+  },
+  enhancer2(elm) { /* */ },
+  enhancerN(elm) { /* */ },
 });
 
 handle(document.documentElement, {
-    handler1(elm, event) {
-    },
-    handler2(elm, event) {
-    },
-    handlerN(elm) {
-    }
+  handler1(elm, event) {
+    // Handle clicks on elements with this handler.
+  },
+  handler2(elm, event) { /* */ },
+  handlerN(elm, event) { /* */ },
 });
 ```
 
+In a more modular setup, this would look like:
+
+```js
+import { enhance, handle } from '@grrr/hansel';
+import { enhancer as fooEnhancer, handler as fooHandler } from './foo';
+import { enhancer as barEnhancer, handler as barHandler } from './bar';
+
+enhance(document.documentElement, {
+  fooEnhancer,
+  barEnhancer,
+});
+
+handle(document.documentElement, {
+  fooHandler,
+  barHandler,
+});
+```
+
 ## Enhancers
 
-`enhance` will look for DOM nodes containing the `data-enhancer` attribute.
+The `enhance` function will look for DOM nodes containing the `data-enhancer` attribute.
 The second argument is a lookup table for enhancer functions. The value of the `data-enhancer` attribute will be matched with the table and if found, executed, given the element as first argument:
@@ -67,3 +82,3 @@
   foo(elm) {
-    console.log(elm.getAttribute('data-message')); // "Hello!"
+    console.log(elm.getAttribute('data-message')); //=> "Hello!"
   }
@@ -81,3 +96,3 @@ });
 
-Handlers are called on click, using a global event listener on the `document`. Meta-clicks are caught and *not* passed on to the handler.
+Handlers are called on click, using a global event listener on the `document`. 
 
@@ -89,3 +104,3 @@ ```js
   shout(elm, e) {
-    alert(elm.getAttribute('data-message')); // "Hello!"
+    alert(elm.getAttribute('data-message')); //=> "Hello!"
     e.preventDefault();
@@ -102,48 +117,44 @@ }
 
-## Furthermore
+### Options
 
-Thanks to the global click listener, handlers do not have to be re-initialized to dynamically added content. The presence of a `data-handler` attribute is enough.
+It's possible to register a handler with options. To do so, register the handler via an object with an `fn` and `options` key:
 
-Enhancers are run immediately however, so you might want to run them again, for instance when loading new DOM nodes in response to an AJAX call. The first argument to `enhance` is the container element within which nodes are searched. Therefore, you can pass the parent to the newly created nodes as reference to enhance all its children:
-
 ```js
-const myContainer = document.querySelector('foo');
-myContainer.innerHTML = htmlContainingEnhancedElements;
-
-enhance(myContainer, myEnhancers);
+handle(document.documentElement, {
+  foo(elm, e) { /* */ },
+  bar(elm, e) { /* */ },
+  baz: {
+    fn: baz(el, e) {
+      // The handler function.
+    },
+    options: {
+      // The handler options.
+    },
+  },
+});
 ```
 
-## Usage with build tools
+The following options are available:
 
-This package is published with untranspiled JavaScript. All files are in the form of ECMAScript Modules (ESM), with `.mjs` as file extension. This means that you'll need to transpile the package yourself.
+#### allowModifierKeys
 
-Not every build tool or bundler will recognize `.mjs` files correctly, and not every setup will transpile these files when they're in the `node_modules` folder. Here's a list with commonly used tools and usage instructions:
+By default, modifier-clicks ([metaKey](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/metaKey), [ctrlKey](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/ctrlKey), [altKey](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/altKey) and [shiftKey](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/shiftKey)) on anchors (`<a>`) are caught, and are *not* passed on to the handler. To disable this behaviour, register the handler with the `allowModifierKeys` option:
 
-#### Webpack
-
-The latest version of Webpack should transpile `.mjs` files properly when used with the default Babel loader ([babel-loader](https://github.com/babel/babel-loader)).
-
-#### Rollup
-
-The latest version of Rollup should transpile `.mjs` files properly when used with the default Babel plugin ([rollup-plugin-babel](https://github.com/rollup/rollup-plugin-babel)).
-
-#### Browserify
-
-Use the following [babelify](https://github.com/babel/babelify#why-arent-files-in-node_modules-being-transformed) settings to transform `.mjs` files in the `node_modules`:
-
 ```js
-global: true,
-ignore: /\/node_modules\/(?!.*.*\/.*.mjs)/,
+options: {
+  allowModifierKeys: true,
+},
 ```
 
-The [esmify](https://github.com/mattdesl/esmify) plugin might also prove to be usefull.
+## Furthermore
 
-#### Babel
+Thanks to the global click listener, handlers do not have to be re-initialized to dynamically added content. The presence of a `data-handler` attribute is enough.
 
-If you're transpiling with Babel in any other setup, use the following ignore pattern to properly ignore the `node_modules` and allow `.mjs` files to be transpiled:
+Enhancers are run immediately however, so you might want to run them again, for instance when loading new DOM nodes in response to an AJAX call. The first argument to `enhance` is the container element within which nodes are searched. Therefore, you can pass the parent to the newly created nodes as reference to enhance all its children:
 
 ```js
-ignore: [/\/node_modules\/(?!.*.*\/.*.mjs)/],
+const myContainer = document.querySelector('foo');
+myContainer.innerHTML = htmlContainingEnhancedElements;
+
+enhance(myContainer, myEnhancers);
 ```
-
-This can be added in your `babel.config.js`, `.babelrc` or `package.json`; quotes will be necessary for JSON-based configurations.

No alert changes

Improved metrics

Total package byte prevSize

10880

increased by11.17%

Lines of code

131

increased by45.56%

Number of lines in readme file

153

increased by7.75%

No dependency changes