https://github.com/bahrus/be-inclusive
Enable merging templates together.
https://github.com/bahrus/be-inclusive
custom-element custom-elements web-component web-components
Last synced: 2 months ago
JSON representation
Enable merging templates together.
- Host: GitHub
- URL: https://github.com/bahrus/be-inclusive
- Owner: bahrus
- License: mit
- Created: 2021-10-11T14:12:51.000Z (over 3 years ago)
- Default Branch: baseline
- Last Pushed: 2024-02-25T14:48:36.000Z (over 1 year ago)
- Last Synced: 2024-04-25T01:42:27.017Z (about 1 year ago)
- Topics: custom-element, custom-elements, web-component, web-components
- Language: TypeScript
- Homepage:
- Size: 631 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# be-inclusive (đ„°) [WIP]
*be-inclusive* enables weaving templates together.
[](https://github.com/bahrus/be-inclusive/actions/workflows/CI.yml)
[](https://www.webcomponents.org/element/be-inclusive)
Like other [be-enhanced](https://github.com/bahrus/be-enhanced) based [custom enhancements](https://github.com/WICG/webcomponents/issues/1000), be-inclusive can use attributes to enhance the functionality of the element it adorns.
However, the core functionality be-inclusive addresses seems [so fundamental and important](https://github.com/bahrus/mount-observer?tab=readme-ov-file#birtual-inclusions), that its functionality is already built into the underlying infrastructure supporting custom enhancements and binding from a distance (like [trans-rendering](https://github.com/bahrus/trans-render) supports).
Namely, without any help from this particular package, we can already do:
```html
It's I'm in love
I don't care if 's blue
's gray and too
I don't care about you
Friday
```
... and the last element (*template*) will be replaced with the template content.
This syntax allows IDE's like VS Code to be able to jump to the source without the need for extensions being installed.
The syntax could also be used to good effect during a build process (SSG) or while server-side rendering, or in a service worker, [w3c willing](https://github.com/whatwg/dom/issues/1217#issuecomment-1694483432). If used with server-side rendering, the resulting HTML could be significantly heavier (even after factoring in gzip), so it could often be a net loss to do so on the server, rather than on the client. This package contains no such support currently for server-side rendering.
## Example 1 - Simplest example with no value added from this package, no slots
Song lyrics can be "deconstructed" and repetitive sections (like the chorus) shared, without a single line of JavaScript (once the MountObserver API is loaded).
Please expand below to see the "code".
Applying DRY to punk lyrics
```html
Something's gone wrong again
Something's gone wrong again
Something goes wrong again
And again
And again, and again, again and something's gone wrong again
And again, and again, again and something goes wrong again
Nothing ever happens to people like us
'Cept we miss the bus, something goes wrong again
Need a smoke, use my last fifty P.
But the machine is broke, something's gone wrong again
Tried to find my sock
No good, it's lost
Need a shave
Cut myself, need a new blade
Tried to fry an egg
Broke the yolk, no joke
Look at my watch, just to tell the time but the hand's come off mine
I turned up early in time for our date
But then you turn up late, something goes wrong again
Need a drink, go to the pub
But the bugger's shut, something goes wrong again
Ah, something goes wrong again
```
## Value-add of be-inclusive
The built-in inclusiveness that the mount-observer api supports has a fundamental limitation that Shadow DOM slots don't have -- with these "birtual inclusions", all traces of "slots" vanish so as not to conflict in any way with the ShadowDOM support that slots provide.
And more significantly, the mechanism for updating the slots and having them be projected into the ShadowDOM is completely non existent with this solution. That is the primary value-add of this library -- to provide some ability to emulate that feature (if you squint your eyes enough). Basically, we turn the information contained in the slots into a "model", which we can then update via JavaScript (or declarative binding).
## be-inclusive in a nutshell
```html
It's I'm in love
I don't care if 's blue
's gray and too
I don't care about you
you can fall apart
break my heart
Oh, doesn't even start
...
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday
Wi not trei a holiday in Sweeden this yer
function updateModel(){
const model = {
day1: 'mÄndag', day2: 'tisdag', day3: 'onsdag', day4: 'torsdag', day5: 'fredag',
day6: 'lördag', day7: 'söndag',
};
Object.assign(song.beEnhanced.beInclusive.model, model);
//target.setAttribute('be-inclusive', JSON.stringify({model}));
}
```
What this does:
1. Updates the initModel via the slots: querySelectorAll('[slot][init-val-from]').forEach(el => model[el.slot] = getVal(el, el.getAttribute('init-val-from')))
2. Adds event listener of adorned element for event "load", which MountObserver dispatches after it is done template weaving.
3. Sets the adorned element's href attribute to "of" parameter, and also sets the slotmap attribute, which the MountObserver api knows what to do with.
4. The MountObserver replaces all the slot attributes with the "micro syntax"
3. Applies the xform via [trans-render's binding syntax](https://github.com/bahrus/trans-render?tab=readme-ov-file#example-2a-shortcut-with-pass-through-derivation).
## Example 2 in detail
To see the full example described above in detail, please expand below
TrĂ€nslĂ„tyng pĂžst pĂŒnk lyriks tĂž Sweedisλ
```html
Friday I'm in Love
Wi not trei a holiday in Sweeden this yer
function updateModel(){
const model = {
day1: 'mÄndag', day2: 'tisdag', day3: 'onsdag', day4: 'torsdag', day5: 'fredag',
day6: 'lördag', day7: 'söndag',
};
Object.assign(song.beEnhanced.beInclusive.model, model);
}
It's I'm in love
I don't care if 's blue
's gray and too
I don't care about you
you can fall apart
break my heart
Oh, doesn't even start
wait
And always comes too late
But never hesitate
I don't care if 's black
, heart attack
never looking back
you can hold your head
, stay in bed
Or watch the walls instead
wait
And always comes too late
But never hesitate
Dressed up to the eyes
It's a wonderful surprise
To see your shoes and your spirits rise
Throwing out your frown
And just smiling at the sound
And as sleek as a shriek
Spinning round and round
Always take a big bite
It's such a gorgeous sight
To see you in the middle of the night
You can never get enough
Enough of this stuff
It's
I'm in love
you can fall apart
, break my heart
doesn't even start
.stanza{
padding-top: 20px;
}
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday
```
If you need to pull the value from an element buried deep within the element, specify the path starting with a dot.
For example:
```html
My Input:
```
The vertical pipe represents an open parenthesis that automatically closes at the end of the expression, or before the next period (".").
The init-val-from attribute is actually optional, and we use as much inference as possible to derive the initial value from the element -- if the element is a microdata element (as is the case here) it applies the same rules -- it assumes the value from the textContent. If the element is an input element, it gets the value based on the type (checkbox, number, etc).
So this works just the same:
```html
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday
```
## Example 3 - Adventures with the Shadow DOM
In the example below, this package again provides nothing beyond what is supported in the underlying library on which *be-inclusive* (and other [be-enhanced](https://github.com/bahrus/be-enhanced) [enhancements](https://github.com/WICG/webcomponents/issues/1000)) rests -- the [MountObserver](https://github.com/WICG/webcomponents/issues/896). Here we use slots / Shadow DOM in all its glory, using the platform's ability to update slots as needed, combined with the MountObserver's support for template importing (with ShadowDOM open/closed mode).
Sample Markup
```html
div {
background-color: cornsilk;
}
Beautiful
Christina Aguilera
Don't look at me
Everyday is so wonderful
Then suddenly
It's hard to breathe
Now and then I get insecure
From all the pain
I'm so ashamed
beautiful
So don't you bring me down today
No matter what they say
Words
bring
down
Oh no
In every single way
Yes words
bring
down
Oh no
can't
can't
me
me
I am
I am
To all your friends you're delirious
So consumed
In all your doom, ooh
Trying hard to fill the emptiness
The pieces gone
Left the puzzle undone
Ain't that the way it is
can't
can't
you
you
You are
You are
No matter what we (no matter what we )
do
do
say
say
We're the song inside the tune (yeah, oh yeah)
Full of beautiful mistakes
And everywhere we go (and everywhere we go)
The sun will always shine (the sun will always, always, shine)
And tomorrow we might awake
On the other side
won't
can't
us
us
We are
We are
Oh, oh
Don't you bring me down today
Don't you bring me down, ooh
Today
```
## Example 4 - Applying DRY to the song of the material universe [TODO]
The [Periodic Table Codepen](https://codepen.io/mikegolus/pen/OwrPgB) has lots of repetitive, periodic DOM in it. Performance can actually be improved over server-rendering all ths HTML by utilizing templates for the purpose of reducing repeating HTML (yes, it even improves over HTML with gzip in place).
In order to support this, some features have been added to *be-inclusive* -- specifying arrays of includes, and prepending when needed.
The markup can be found [here](https://github.com/bahrus/be-inclusive/blob/baseline/demo/periodic_table.html).
[TODO] beatify
[WIP] share templates
## Viewing Demos 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:8000/demo/dev in a modern browser.