be-observant

be-observant is a key member of the may-it-be family of web components. It allows one DOM element to observe another element, where that element typically comes "before it". It is much like how Javascript closures can access variables defined outside the closure, as long as it came before.

be-observant is also a trend-setting member of the family -- many of the other may-it-be components piggy-back both on the code as well as the syntax for adding "environment-aware" bindings to their configuration properties.

be-observant also provides an experimental declarative trans-render plugin, so the binding can be done while instantiating a template, rather than after the DOM has been added to the live DOM tree.

Sample syntax

<ways-of-science>
    <largest-scale>
        <woman-with-carrot-attached-to-nose></woman-with-carrot-attached-to-nose>
    </largest-scale>
    <largest-scale>
        <a-duck></a-duck>
    </largest-scale>
    <if-diff iff not-equals set-attr=hidden be-observant='{
        "lhs": {"observe": "largest-scale:has(> woman-with-carrot-attached-to-nose", "on":"value-changed", "valueFromTarget": "value"}, 
        "rhs": {"observe": "largest-scale:has(> a-duck)", "on":"value-changed", "valueFromTarget": "value"} 
    }'>
        <template>
            <div hidden>A witch!</div>
        </template>
    </if-diff>
</ways-of-science>

Now hold on just a minute...

Use Cases

Web Components as a Democratic Organism

be-observant works well with web components that are designed like an organism - with an internal non visual "component as a service" acting as the "brain", and *be-observant" aids in transmitting the "thoughts" from this "brain" to peripheral elements (both built-in and custom).

Progressively Enhancing Server Rendered/Generated content

Because this.

Alternatives

be-observant shares similar syntax / concepts to be-noticed and to pass-down and pass-up.

However, there are some subtle differences in spirit between what these three components are trying to achieve. In many cases, more than one of these components can solve the same problem, so it becomes a matter of "taste" which one solves it better.

What all these components share in common is they do not assume that there is a host component managing state.

For example, the preceding example does not yet assume King Arthur has fully established his kingdom -- it works regardless of a containing component managing state.

The overlap between these four components, functionally, is considerable.

The general guidelines for choosing between these four elements:

Assumptions, shortcuts

Another subtle difference in emphasis between pass-down and be-observant:

Whereas the pass-down component may be more fitting for a 30,000 ft above the ground environment outside any web component (rather, as part of a "web composition" of Native DOM and custom DOM elements), be-observant is more tailored for markup within a web component.

In particular, with be-observant, the shortcuts we provide are based on the assumption that there is such a component container managing (some amount of) state.

So, for example:

 <xtal-editor be-observant='{
    "open": "expandAll",
    "expandAll": "expandAll",
    "readOnly": "readOnly"
}'></xtal-editor>

is interpreted to mean: "any time the host's expandAll property changes (communicated via expand-all-changed event), set this instance's "open" property to the same value. Likewise with the other two lhs/rhs pairs.

The host is obtained by calling the native function el.getRootNode(). If that is a miss, it searches for the closest parent containing a dash.

To specify a different source to observe other than the host, there are numerous other options, which are catalogued below.

Notes

Note: Editing large JSON attributes like this is quite error-prone, if you are like me. The json-in-html VSCode extension can help with this issue. That extension is compatible with pressing "." on the github page and with the web version of vs-code. An even better editing experience can be had by using .mts/.mjs files to define the html, with the help of a transpiler such as the may-it-be transpiler.

Note: The attribute name "be-observant" is configurable. "data-be-observant" also works, with the default configuration. The only limitation as far as naming is the attribute must start with be-* (which also guarantees data-be-* as well).

Note: The syntax, and the core code behind be-observant, is also used by a fair number of other web components in the may-it-be family of web components, so it is worthwhile expounding on / understanding exactly what that syntax means, if we wish to be fluent in be-speak.

Note: The be-observant attribute can also be an array, allowing for grouping of observers, and observing duplicate events or properties.

Note: If a property key (lhs) starts with ^, then the previous key that didn't start with a ^ is substituted. This provides for a more compact way to avoid use of arrays.

Syntax in depth

What

First we need to choose what to observe. This is done via a number of alternative keys:

Homing in [Untested]

Having selected a DOM element to observe, we may optionally want to observe a sub object as our "container" to observe from. These sub objects might extend EventTarget, meaning they have events we can subscribe to. The assumption here is that unlike other typical properties of the DOM element, which might be transient, properties we would want to home in on are "stable, permanent" properties that may, for example, point to a store (MobX, for example).

This is done via parameter homeInOn, which specifies a "dot" delimited path from the element to observe found above.

When to act

Once we find the element (or Event Target) to observe, next we need to specify what property or event to listen to on that element / Event Target.

What to pass

Next we specify what to pass to the adorned element from the element we are observing and possibly from the event.

Adjusting the value

There are some frequent requirements when it comes to adjusting the value obtained from the target / event, prior to passing the value. The options to do this are listed below:

Alternative End Point

By default, the lhs of each be-observant setting specifies the name of the property to set.

But we can instead opt to set an attribute.

Possible values are shown below

export interface AlternateEndPoint {
    /** Set attribute rather than property. */
    as?: 'str-attr' | 'bool-attr' | 'obj-attr' | 'class' | 'part',
}

Side Effects

We can apply some "side effects":

NB

Big time short cuts.

When working with be-observant, we will likely encounter the following patterns rather frequently:

<my-element be-observant='{
    "typicalProp1": {"vft": "myHostProp1"},
    "typicalProp2": {"onSet": "myHostProp2", "vft": "myHostProp2"}
}'>

These are already shortcuts for a number of configurable atomic operations, but even these shortcuts get to feeling rather repetitive in many circumstances.

The shortcut for these two scenarios is shown below:

<my-element be-observant='{
    "typicalProp1": "myHostProp1",
    "typicalProp2": ".myHostProp2"
}'>

Being host-ish

Sometimes there are scenarios where we would like to benefit from the shortcuts above, but don't want to use Shadow DOM on a containing component just for the benefit of the shortcut.

An element can declare itself to be a host for these purposes by adding global attribute "itemscope". Be-observant searches for such an element before doing the getRootNode() call.

Under the hood, this scenario will use another option: observeClosestOrHost (ocoho for short), which tries using the native "closest" query first, and if that fails, does getRootNode()

Configuration Parameters

Performed during template instantiation

be-observant also provides a declarative trans-rendering plugin, trPlugin.js.

During instantiation of the template, if the trPlugin library is loaded in memory, it can bind the initial values prior to the HTML landing in the live DOM tree. If not, no problemo.

Just have the be-observant library described above, and it will, using almost completely shared code, achieve the same result.

Sample Markup.

Add filter [TODO]

If the property we are observing resolves to an array, allow filtering the array based on some conditions (like mongodb query).

where:{ ifAllOf:[], ifNoneOf:[], ifEquals:[], }

Viewing Locally

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

5. npm install

6. npm run serve

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

Importing in ES Modules:

import 'be-observant/be-observant.js';

const {importFromScriptRef} = await import('be-observant/importFromScriptRef.js');

Using from CDN:

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