be-invoking (🕹️)

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.

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

<script type=module>
    import {Mount} from 'xtal-element/index.js';
    import '/🕹️.js';
    class MoodStoneBase extends Mount{
        howAmIFeelingAboutToday(targetElement, event){
            console.log({targetElement, event});
        }
    }
    customElements.define('mood-stone-base', MoodStoneBase);
</script>
...
<mood-stone itemscope>
    <button 🕹️=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 "input" events.
3. Invokes host-element's howAmIFeelingToday method only when the input element dispatches "input" event. If adorning a button element, it will invoke the method on clicking.

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, "be-invoking" 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 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{
        engageInSoulSearching(targetElement, event){
            console.log({targetElement, event});
        }
    }
    customElements.define('soul-searching-base', SoulSearchingBase);
</script>
...

<mood-stone itemscope>
    <soul-searching itemscope -engage-in-soul-searching>
        <xtal-element
            inherits=soul-searching-base
        ></xtal-element>
    </soul-searching>
    <button 🕹️=-engage-in-soul-searching>What have I done?</button>
    <xtal-element></xtal-element>
</mood-stone>

Example 1d Specifying a Peer Element, Part II

This also works:

<mood-stone itemscope>
    <soul-searching itemscope>
        <xtal-element
            inherits=soul-searching-base
        ></xtal-element>
    </soul-searching>
    <button 🕹️=~soulSearching?.engageInSoulSearching>What have I done?</button>
    <xtal-element></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 'be-invoking/be-invoking.js';

Using from CDN:

<script type=module crossorigin=anonymous>
    import 'https://esm.run/be-invoking';
</script>

or

<script type="importmap">
{
"imports": {
    "be-invoking": "https://ga.jspm.io/npm:[email protected]/be-invoking.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>