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 peripheral elements (both built-in and custom) in reading the "thoughts" from this "brain".

Progressively Enhancing Server Rendered/Generated content

Because this.

Assumptions, shortcuts

be-observant is an attribute based alternative to the pass-down web component. A lengthy discussion comparing them is found here.

As mentioned there, one 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 (SSR/SSG rendered) web component.

In particular, with be-observant, the shortcuts we provide are based on the assumption that more often than not, there is 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.

Note: As we will see, be-observant provides quite a bit of functionality. As much as possible, be-observant attempts to keep it scalable by only loading code on demand -- so if features aren't used, it won't add to the payload.

Syntax in depth

What

First we need to choose what to observe.

be-observant supports no less than two alternative schemes for deciding this: One that reuses common functionality used by many be-decorated elements, with a reduced set of options.

The other is more powerful, with more options and has lots of intricate cross-logic fallbacks from one option to another (should one fail to produce the desired element), which is both a blessing and a curse.

The beautiful thing about dynamic imports is if you choose to use one scheme across the board, there's no penalty from the fact that another supporting another scheme which you never use is present (i.e. it shouldn't show up as unused code by dev tools).

First option: of

First, the simpler common approach: [TODO]

Simple example of the syntax:

<my-custom-element be-observant='{
    "myProp": {"on": "click", "of": "parent"}
}>

The full list of options for the simple schema is shown below:

/**
 * Target selector in upward direction.
 */
export type Target = 
/**
* Use the parent element as the target
*/ 
'parent' | 
/**
* abbrev for parent
*/
'p' |
/**
 * Use the element itself as the target
 */ 
'self' | 
/**
 * abbrev for self
 */ 
's' |
/**
 * Use the native .closest() function to get the target
 */
['closest', string] |
/**
 * abbrev for closet
 */
['c', string] | 
/**
 * Find nearest previous sibling, parent, previous sibling of parent, etc that matches this string.
 */
['upSearch', string] |
/**
 * abbrev for upSearch
 */
['us', string] |
/**
 * If second element is true, then tries .closest('itemscope').  If string, tries .closest([string value])
 * If that comes out to null, do .getRootNode
 */
['closestOrHost', boolean | string] |
/**
 * abbrev for closestOrHost
 */
['coh', true | string] |
/**
 * get host
 */
'host' |
/**
 * abbrev for host
 */
'h'
;

Option 2: multi-key

This is done via a number of alternative keys:

Homing in

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":

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:

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 / API

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.

Sample Markup.

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';

Using from CDN:

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