do-invoke (🕹️)

Invoke method on upstream peer element or the host.

Note

This element enhancement took some inspiration from the original form that the invoker commands proposal adopted as well as countless frameworks. Once that becomes built into the platform (hopefully), definitely consider adopting that built-in technique before using this as a last resort.

Other alternatives

This enhancement allows us to only specify the name of a method to invoke from the host or peer element, optionally based on some explicitly defined event. After it invokes the method, this enhancement simply punts. I.e. all the logic for actually doing anything must be fully defined within the method.

Another enhancement, be-modding, takes a more active role in managing what happens.

Example 1a Invoking a host method on most common event (depending on context)

<script type=module>
    import {Mount} from 'xtal-element/index.js';
    class MoodStoneBase extends Mount{
        howAmIFeelingAboutToday(targetElement, event){
            console.log({targetElement, event});
        }
    }
    customElements.define('mood-stone-base', MoodStoneBase);
</script>
...
<mood-stone itemscope>
    <button disabled 🕹️=howAmIFeelingAboutToday>Feeling great</button>
    <xtal-element inherits=mood-stone-base></xtal-element>
</mood-stone>

What this does:

1. Removes the disabled attribute after hydrating.
2. Listens by default for "click" events in this case.
3. Invokes host-element's howAmIFeelingToday method only when the button dispatches "click" event.

It passes in two arguments:

1. The instance of whatever element is being invoked, just in case that is helpful.
2. The event that triggered the action.

Note that the name of this package, "do-invoke" is the canonical name of this element enhancement. It is a bit long, but benefits from making the markup somewhat self-explanatory. It is easy to choose your own name, as demonstrated by this file.

Example 1a with inference

We can infer the name of the method to invoke from the name attribute of the element do-invoke adorns:

<script type=module>
    import {Mount} from 'xtal-element/index.js';
    class MoodStoneBase extends Mount{
        howAmIFeelingAboutToday(targetElement, event){
            console.log({targetElement, event});
        }
    }
    customElements.define('mood-stone-base', MoodStoneBase);
</script>
...
<mood-stone itemscope>
    <button disabled name=howAmIFeelingAboutToday 🕹️>Feeling great</button>
    <xtal-element inherits=mood-stone-base></xtal-element>
</mood-stone>

Example 1b Specifying the event

To specify a different event to act on:

<mood-stone itemscope>
    <button 🕹️="howAmIFeelingAboutToday on mouseover">Feeling great</button>
    <xtal-element inherits=mood-stone-base></xtal-element>
</mood-stone>

Example 1c Specifying a peer element

<script type=module>
    import {Mount} from 'xtal-element/index.js';
    import '/🕹️.js';
    class SoulSearchingBase extends Mount{
        engage(targetElement, event){
            console.log({targetElement, event});
        }
    }
    customElements.define('soul-searching-base', SoulSearchingBase);
</script>
...

<mood-stone itemscope>
    <soul-searching #>
        <xtal-element
            inherits=soul-searching-base
        ></xtal-element>
    </soul-searching>
    <button 🕹️="#{{soul-searching}}?.engage">What have I done?</button>
    <xtal-element -id></xtal-element>
</mood-stone>

Viewing Demos Locally

Any web server that can serve static files will do, but...

1. Install git.
2. Fork/clone this repo.
3. Install node.js.
4. Open command window to folder where you cloned this repo.

5. npm install

6. npm run serve

7. Open http://localhost:8000/demo/ in a modern browser.

Running Tests

> npm run test

Using from ESM Module:

import 'do-invoke/do-invoke.js';

Using from CDN:

<script type=module crossorigin=anonymous>
    import 'https://esm.sh/do-invoke';
</script>

or

<script type="importmap">
{
"imports": {
    "do-invoke": "https://ga.jspm.io/npm:[email protected]/do-invoke.js"
},
"scopes": {
    "https://ga.jspm.io/": {
    "be-enhanced/": "https://ga.jspm.io/npm:[email protected]/",
    "trans-render/": "https://ga.jspm.io/npm:[email protected]/"
    }
}
}
</script>