Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kgscialdone/facet

Web components made simple and declarative
https://github.com/kgscialdone/facet

custom-elements facet html javascript vanilla-js web-components

Last synced: 3 months ago
JSON representation

Web components made simple and declarative

Host: GitHub
URL: https://github.com/kgscialdone/facet
Owner: kgscialdone
License: unlicense
Created: 2023-11-28T04:14:03.000Z (11 months ago)
Default Branch: master
Last Pushed: 2024-01-06T20:44:44.000Z (10 months ago)
Last Synced: 2024-06-11T07:34:05.764Z (5 months ago)
Topics: custom-elements, facet, html, javascript, vanilla-js, web-components
Language: JavaScript
Homepage: https://discord.gg/fmqVtPABQh
Size: 64.5 KB
Stars: 133
Watchers: 6
Forks: 4
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

awesome-github-repos - kgscialdone/facet - Web components made simple and declarative (JavaScript)

README

Facet

Facet is a single-file web library that allows for the easy, declarative definition of [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). By making use of `` elements with special attributes, Facet makes it possible to define useful and effective web components with no Javascript boilerplate, so you can focus entirely on the structure and behavior of your component.

> _Like what you see? [Consider buying me a coffee](https://ko-fi.com/kgscialdone)_ 💜

## Installation
You can download `facet.min.js` from this repository and reference it locally, or retrieve it directly from a CDN like JSDelivr. Facet will automatically detect component definitions in your page's HTML and convert them into web components.
```html

```

## Defining Components
Facet components are defined with `` elements, which will be automatically detected when the page loads. Facet uses the browser's [custom elements API](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) internally, so Facet components are treated just like normal HTML elements.
```html

Hello, world!

Facet
```

By default, Facet components use the [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) in `closed` mode. You can adjust this with the `shadow` attribute, which accepts `open`, `closed`, or `none`.
```html

Hello, world!

```

You can also define a list of attributes to be observed by the component; any attributes defined here will trigger the component's `attributeChanged` event when changed, allowing your code to respond to the update. (See [Attaching Behavior](#attaching-behavior) for details on ``.)
```html
<template component="observed-attrs" observe="name title">
<script on="attributeChanged">console.log(event.detail.name)

```

## Inherited Attributes
In many cases, it's beneficial to be able to define attributes where a component is used, and have those attributes change the behavior of elements inside the component. Facet achieves this through inherited attributes, which make copying attributes deeper into your components quick and easy.
```html

Input

Email
```

When inheriting attributes, you can use them as-is, rename them, filter them through a Javascript function, or both:
```html

Lorem ipsum dolor sit amet...

function uppercase(string) { return string.toUpperCase() }

return value.toUpperCase()

```

In addition, attributes that are both observed and inherited will automatically update whenever the component's attribute is changed:
```html

```

## Attaching Behavior
Since Facet components are defined entirely in HTML, you don't have the opportunity to edit the component class directly to add your behavior. Instead, Facet searches for `` elements inside of component definitions, and attaches their contents to their parent elements as event handlers.
```html
<template component="immediate-alert">
<script on="connect">alert("You've been alerted immediately!")

```

Event handler scripts don't have to be at the top level of the component; they'll be attached to whatever their parent element is, allowing you to easily define complex behaviors for any part of your component.
```html

Alert me!
alert("I've been clicked!")

```

Facet exposes components' lifecycle hooks as custom events, which works hand in hand with event handler scripts to allow flexible, easy definition of custom behavior.

| Component Class Function | Facet Event | `event.detail` |
| :------------------------- | :----------------- | :---------------------------------------- |
| `connectedCallback` | `connect` | `{ component }` |
| `disconnectedCallback` | `disconnect` | `{ component }` |
| `adoptedCallback` | `adopt` | `{ component }` |
| `attributeChangedCallback` | `attributeChanged` | `{ component, name, newValue, oldValue }` |

In addition, event handler scripts have access to a small handful of magic variables, in a similar way to the `onclick` event handler attribute family.

You can also adjust how event handler scripts act with the `once`, `capture`, and `passive` attributes, which correspond to their respective equivalents in [`addEventListener`'s `options` parameter](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). If the attribute is present, the corresponding option will be set to `true`, otherwise it will follow the browser defaults.

## Mixins
Facet also provides a mixin system in order to facilitate code reuse between similar components. Like components, mixins are defined with `` elements, and their contents are appended to the shadow DOM of any component they're mixed into.
```html

alert("Connected!")

Hello, world!

Goodbye, world...

```

Mixins with the `global` attribute will be automatically applied to all components on a page.
```html

alert("Connected!")

```

Mixins with the `prepend` attribute will prepend their contents instead of appending them.
```html
Lorem ipsum dolor sit amet...

is a pretty weird choice of filler text, if you think about it.

```

## Advanced Features
You can define [customized built-in elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#customized_built-in_elements) with the `extends` attribute.
```html

Lorem ipsum dolor sit amet...

is a pretty weird choice of filler text, if you think about it.

```

You can define [form-associated custom elements](https://web.dev/articles/more-capable-form-controls) with the `forminput` attribute.
```html

host.innerText = host.value
+ host.innerText = ++host.value

- host.innerText = --host.value

```

## Configuration Options
While Facet's defaults are designed to serve the majority of use cases out of the box, it does have a small handful of configuration options, which can be adjusted via attributes on the `` tag that imports the Facet library.

### Namespacing
Requires a prefix on the `component` and `mixin` attributes to help avoid conflicts. The prefix defaults to `facet-` if no value is supplied to the attribute.
```html

<script src="facet.min.js" namespace>

Hello, world!

console.log(this)

Hello, world!

console.log(this)

```

### Disable Automatic Discovery
Prevents the automatic discovery of component and mixin definitions, requiring you to manually call `facet.discoverDeclarativeComponents` yourself.
```html

facet.discoverDeclarativeComponents(document)
```

### Default Shadow Mode
Changes the default shadow root mode for new components. Equivalent to the `shadow` attribute on individual components.
```html

```

## Javascript API
While Facet strives to never require you to write Javascript for any of its core behavior, it does expose its internal workings as a basic Javascript API. Facet's API is intentionally not perfectly ergonomic, since the declarative ``-based interface described above is always the intended use case, but there are some things that can only be realistically achieved with Javascript, such as single-file importable components.

Facet's source code is also lovingly commented with [JSDoc](https://jsdoc.app/), which keeps it lightweight and build-step free while still enabling Typescript users to rest easy about type safety when interacting with Facet's API.

## Reviews
> ⭐⭐⭐⭐⭐ "Anyone exploring web components really would do themselves a major favor giving this a solid look."
>
> ⭐⭐⭐⭐⭐ "Facet is the first time I've looked at WebComponents and thought 'oh, I get this, I get what it's for'."
>
> ⭐⭐⭐⭐⭐ "This is exactly what I thought web components should be."
>
> ⭐⭐⭐⭐⭐ "Holy f\*\*\*, this is awesome!"
>
> ⭐⭐⭐⭐⭐ "I never thought much of web components but this really changes my view."

_{* All reviews are real quotes from users, but are used here in jest and with permission.}

## Sponsors
Thank you so much to these $5/mo+ sponsors for your support!

- [Morgan Murrah](https://github.com/airbr) ($5/mo)