element! For example,
-// you can call regular DOM APIs like setAttribute on it.
+// The result stored in the `el` variable is a `
` element! For example,
+// we can call regular DOM APIs like `setAttribute` on it.
el.setAttribute('foo', 'bar')
-// Append the element to the body of the page, and now you'll see a
-// continually-updating message on your screen.
+// Append the element to the body of the page, and now we'll see a
+// continually-updating message on the screen.
document.body.append(el)
```
[Example on CodePen](https://codepen.io/trusktr/pen/bGPXmEJ) (with Solid's `html` template tag instead of JSX)
-### Create functional components
+## Create functional components
Continuing with the same `count` variable from the previous example, here's how
-to compose DOM trees using "functional components". This is also just plain
-Solid.js, but can be useful in a custom element's `template`.
+to compose DOM trees using "functional components". This is plain Solid.js, and
+functional components (Solid.js components) can be used in a custom element's
+`template`.
A functional component is a function that simply returns one or more DOM
elements. JSX expressions and the `html` template string tag both return the top
@@ -493,350 +532,83 @@ level elements defined in the markup.
// This Label functional component uses the empty <> tag to contain more than
// one root-level child, and the return value will be an array of DOM nodes.
const Label = props => (
- <>
-
{props.greeting}
- {props.children}
-
+ <>
+
{props.greeting}
+ {props.children}
+
)
// This Greeting functional component nests the content of the Label component
// in its template, and the
inside the
gets distributed to the
// part of the Label component where we see `{props.children}`.
const Greeting = () => (
-
+
)
-// You only need to call this once, and you get a reference to an element or
-// multiple elements. You do NOT need to call it over and over to re-render like
-// you do in some other libraries. That's what makes all of this simple and
-// clean. The reactivity inside the component templates takes care of updating
-// content of the created DOM tree.
-// Here elem is a reference to an actual `` element.
+// The `Greeting` function only needs to be called once, and it will return a
+// reference to an element or multiple elements. The `Greeting` function does
+// NOT need to be called over and over to re-render like in some other libraries
+// (for example React). That's what makes all of this simple and clean. The
+// reactivity inside the component templates takes care of updating content of
+// the created DOM tree.
+// Here `elem` will be a reference to an actual `` element that the
+// `Greeting` function returned.
const elem = Greeting()
// It's just DOM! Use regular DOM APIs to append the element to the body.
document.body.append(elem)
```
-[Example on CodePen](https://codepen.io/trusktr/pen/eYwqPzz)
-
-Writing function components can sometimes be simpler, but functional components do not have features that
-custom elements have like style scoping (requires an additional a Solid.js
-library or compiler plugin).
-
-In contrast to custom elements, functional components only work within the
-context of other functional components made with Solid.js or custom elements
-made with `@lume/element`. Functional components will no longer be compatible
-with React, Vue, Angular, Svelte, or all the other web libraries and frameworks.
-For portability across applications and frameworks, this is where custom
-elements accel.
-
-Custom elements are also debuggable in a browser's element inspector _out of the
-box_, while functional components are not (functional components require
-devtools plugins for each browser, if they even exist). See Lume's [Debugging
-guide](https://docs.lume.io/guide/debugging) for an example.
+[Example on CodePen](https://codepen.io/trusktr/pen/eYwqPzz) (with Solid's `html` template tag instead of JSX)
-### Use functional components inside custom elements
+## Using functional components inside custom elements
Continuing from above, here's a custom element that re-uses the `Greeting`
component. This shows that any regular Solid.js component can be
used in the `template` of a custom element made with `@lume/element`:
```jsx
-@element('cool-element')
+@element // The 'cool-element' name is implied from the constructor name (dash-cased)
class CoolElement extends Element {
- template = () => (
- <>
- Here's a greeting:
- Here's a greeting:
+
-
The count is: {count()}
- ,
-)
-
-el.setAttribute('foo', 'bar')
-
-document.body.appendChild(el)
-```
-
-The main differences from plain JS are
-
-- Use of the `@jsxImportSource` comment to place JSX types into scope. This is
- required, or TypeScript will not know what the types of elements in JSX
- markup are. Alternative to comments, configure it in tsconfig.json's
- `compilerOptions`.
-- The `div()` helper function explicitly returns the type `HTMLDivElement` so
- that the `el` variable will be typed as `HTMLDivElement` instead of
- `JSX.Element`. Under the hood, the `div()` function is an identity function
- at runtime, it simply returns whatever you pass into it, and serves only as a
- convenient type cast helper.
-
-> [!Warning]
-> Keep in mind to use the correct type helper depending on what the root element
-> of the JSX expression is. For for example, if the root of a JSX expression is a
-> `` element then we need to use the `menu()` helper like follows.
-
-```tsx
-/* @jsxImportSource solid-js */
-import {createSignal} from 'solid-js'
-import {menu} from '@lume/element/dist/type-helpers.js'
-
-// ...
-
-// The type of `el` will be `HTMLMenuElement`.
-const el = menu(
-
- The count is: {count()}
- ,
-)
-```
-
-If the wrong helper is used, then it will effectively cast the expression to
-the wrong type. For example, in the next snippet the `el` variable will be of
-type `HTMLDivElement` despite the fact that at runtime we will be have an
-`HTMLMenuElement` instance.
-
-```tsx
-/* @jsxImportSource solid-js */
-import {div, button} from '@lume/element/dist/type-helpers.js'
-
-// GOOD.
-const el = button(... )
-
-// BAD! Don't do this! Remember to double check, because the helpers are not
-// type safe, you will not get an error here, and el2 will incorrectly be type
-// HTMLDivElement.
-const el2 = div(... )
-```
-
-Without the type helpers, we would need to write more verbose code like the
-following to have the proper types, but note that the following is also not type
-safe:
-
-```tsx
-/* @jsxImportSource solid-js */
-
-// GOOD.
-const el = (... ) as any as HTMLMenuElement
-
-// BAD! Don't do this! Remember to double check, because the helpers are not
-// type safe, you will not get an error here.
-const el2 = (... ) as any as HTMLDivElement
-```
-
-#### Type definitions for custom elements
-
-To give your Custom Elements type checking for use with DOM APIs, and type
-checking in JSX, use the following template.
-
-```tsx
-/* @jsxImportSource solid-js */
-
-// We already use @jsxImportSource above, but if you need to reference JSX
-// anywhere in non-JSX parts of the code, you also need to import it from
-// solid-js:
-import {Element, element, stringAttribute, numberAttribute, /*...,*/ JSX} from 'solid-js'
-// ^ We imported JSX so that...
-
-// Define the attributes that your element accepts
-export interface CoolElementAttributes extends JSX.HTMLAttributes {
- // ^ ...we can use it in this non-JSX code.
- 'cool-type'?: 'beans' | 'hair'
- 'cool-factor'?: number
- // ^ NOTE: These should be dash-case versions of your class's attribute properties.
-}
-
-@element('cool-element')
-class CoolElement extends Element {
- @stringAttribute coolType: 'beans' | 'hair' = 'beans'
- @numberAttribute coolFactor = 100
- // ^ NOTE: These are the camelCase equivalents of the attributes defined above.
-
- // ... Define your class as described above. ...
-}
-
-export {CoolElement}
-
-// Add your element to the list of known HTML elements. This makes it possible
-// for browser APIs to have the expected return type. For example, the return
-// type of `document.createElement('cool-element')` will be `CoolElement`.
-declare global {
- interface HTMLElementTagNameMap {
- 'cool-element': CoolElement
- }
-}
-
-// Also register the element name in the JSX types for TypeScript to recognize
-// the element as a valid JSX tag.
-declare module 'solid-js' {
- namespace JSX {
- interface IntrinsicElements {
- 'cool-element': CoolElementAttributes
- }
- }
-}
-```
-
-> :bulb:**TIP:**
->
-> To make code less redundant, use the `ElementAttributes` helper to
-> pluck the types of properties directly from your custom element class for the
-> attribute types:
-
-```ts
-import type {ElementAttributes} from '@lume/element'
-
-// This definition is now shorter than before, automatically maps the property
-// names to dash-case, and automatically picks up the property types from the
-// class.
-export type CoolElementAttributes = ElementAttributes
-
-// The same as before:
-declare module 'solid-js' {
- namespace JSX {
- interface IntrinsicElements {
- 'cool-element': CoolElementAttributes
- }
- }
-}
-```
-
-Now when you use `` in Solid JSX, it will be type checked:
-
-```jsx
-return (
- {
- 'cool-type'?: 'beans' | 'hair'
- 'cool-factor'?: number
- // ^ NOTE: These should be dash-case versions of your class's attribute properties.
-}
-
-// Add your element to the list of known HTML elements, like before.
-declare global {
- interface HTMLElementTagNameMap {
- 'cool-element': CoolElement
- }
-}
-
-// Also register the element name in the React JSX types, which are global in
-// the case of React.
-declare global {
- namespace JSX {
- interface IntrinsicElements {
- 'cool-element': CoolElementAttributes
- }
- }
-}
-```
+Writing function components can sometimes be simpler, but functional components
+do not have features that custom elements have such as native style scoping
+(style scoping with function components requires an additional Solid.js library
+or compiler plugin), etc.
-> :bulb:**TIP:**
->
-> To make code less redundant, use the `ReactElementAttributes` helper to
-> pluck the types of properties directly from your custom element class for the
-> attribute types:
-
-```ts
-import type {ReactElementAttributes} from '@lume/element/src/react'
-
-// This definition is now shorter than before, and automatically maps the property names to dash-case.
-export type CoolElementAttributes = ReactElementAttributes
-
-// The same as before:
-declare global {
- namespace JSX {
- interface IntrinsicElements {
- 'cool-element': CoolElementAttributes
- }
- }
-}
-```
+In contrast to custom elements, functional components only work within the
+context of other functional components made with Solid.js or custom elements
+made with `@lume/element`. Functional components are not compatible with HTML,
+React, Vue, Angular, Svelte, or all the other web libraries and frameworks. For
+portability across applications and frameworks, this is where custom elements
+shine.
-> [!Note]
-> You may want to define React JSX types for your elements in separate files, and
-> have only React users import those files if they need the types, and similar if you make
-> JSX types for Vue, Svelte, etc (we don't have helpers for those other fameworks
-> yet, but you can manually augment JSX as in the examples above on a
-> per-framework basis, contributions welcome!).
+Custom elements are also debuggable in a browser's element inspector _out of the
+box_, while functional components are not (functional components require
+devtools plugins for each browser, if they even exist). See Lume's [Debugging
+guide](https://docs.lume.io/guide/debugging) for an example.
-## API
+# API
-### `Element`
+## `Element`
A base class for custom elements made with `@lume/element`.
@@ -849,7 +621,7 @@ A base class for custom elements made with `@lume/element`.
The `Element` class provides:
-#### `template`
+### `template`
A subclass can define a `.template` that returns a DOM node, and this DOM node
will be appened into the element's `ShadowRoot` by default, or to the element
@@ -864,14 +636,14 @@ import {Element} from '@lume/element'
import {createSignalFunction} from 'classy-solid' // a small wrapper around Solid's createSignal that allows reading and writing from the same function.
class CoolElement extends Element {
- count = createSignalFunction(100)
-
- template = () => (
-
- The count is: {this.count()}!
-
- )
- // ...
+ count = createSignalFunction(100)
+
+ template = () => (
+
+ The count is: {this.count()}!
+
+ )
+ // ...
}
customElements.define('cool-element', CoolElement)
@@ -885,9 +657,9 @@ decorators yet):
```js
// ...
template = () => html`
-
- The count is: ${this.count}!
-
+
+ The count is: ${this.count}!
+
`
// ...
```
@@ -899,7 +671,7 @@ template = () => html`
We can also manually create DOM any other way, for example here we make and
return a DOM tree using DOM APIs, and using a Solid effect to update the element
-when `count` changes (but you could have used React or jQuery, or anything
+when `count` changes (but we could have used React or jQuery, or anything
else!):
```js
@@ -911,17 +683,17 @@ import {createEffect} from 'solid-js'
// Replace the previous `template` with this one:
template = () => {
- const div = document.createElement('div')
- const span = document.createElement('span')
- div.append(span)
+ const div = document.createElement('div')
+ const span = document.createElement('span')
+ div.append(span)
- createEffect(() => {
- // Automatically set the textContent whenever `count` changes (this is a
- // conceptually-simplified example of what Solid JSX compiles to).
- span.textContent = `The count is: ${this.count()}!`
- })
+ createEffect(() => {
+ // Automatically set the textContent whenever `count` changes (this is a
+ // conceptually-simplified example of what Solid JSX compiles to).
+ span.textContent = `The count is: ${this.count()}!`
+ })
- return div
+ return div
}
// ...same...
@@ -929,21 +701,21 @@ template = () => {
[Example on CodePen](https://codepen.io/trusktr/pen/ExBqdMQ)
-#### `static css`
+### `static css`
Use the _static_ `css` field to define a CSS string for styling all instances of
the given class. A static property allows `@lume/element` to optimize by sharing
a single `CSSStyleSheet` across all instances of the element, which could be
-beneficial for performance if you have _many thousands_ of instances.
+beneficial for performance if there are _many thousands_ of instances.
```js
import {Element} from '@lume/element'
class CoolElement extends Element {
- template = () => This is some DOM!
+ template = () => This is some DOM!
- // Style is scoped to our element, this will only style the inside our element.
- static css = `
+ // Style is scoped to our element, this will only style the inside our element.
+ static css = `
span { color: violet; }
`
}
@@ -959,15 +731,15 @@ The `static css` property can also be a function:
// ...
class CoolElement extends Element {
- // ...
- static css = () => {
- const color = 'limegreen'
+ // ...
+ static css = () => {
+ const color = 'limegreen'
- return `
+ return `
span { color: ${color}; }
`
- }
- // ...
+ }
+ // ...
}
```
@@ -982,17 +754,17 @@ import {css} from '@lume/element'
// ...
class CoolElement extends Element {
- // ...
- static css = css`
- span {
- color: cornflowerblue;
- }
- `
- // ...
+ // ...
+ static css = css`
+ span {
+ color: cornflowerblue;
+ }
+ `
+ // ...
}
```
-#### `css`
+### `css`
Use the _non-static_ `css` property to define styles that are applied _per
instance_ of the given element. This is useful for style that should differ
@@ -1004,23 +776,23 @@ difference will not matter for most use cases.
import {Element, css} from '@lume/element'
class CoolElement extends Element {
- template = () => This is some DOM!
+ template = () => This is some DOM!
- // A random color per instance.
- #color = `hsl(calc(${Math.random()} * 360) 50% 50%)`
+ // A random color per instance.
+ #color = `hsl(calc(${Math.random()} * 360) 50% 50%)`
- // Style is scoped to our element, this will only style the inside our element.
- css = css`
- span {
- color: ${this.#color};
- }
- `
+ // Style is scoped to our element, this will only style the inside our element.
+ css = css`
+ span {
+ color: ${this.#color};
+ }
+ `
}
```
[Example on CodePen](https://codepen.io/trusktr/pen/NWZQEJa) (with `html` template tag instead of JSX)
-#### `connectedCallback`
+### `connectedCallback`
Nothing new here, this is simply a part of the browser's [native Custom Elements
`connectedCallback` API](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
@@ -1031,17 +803,17 @@ create things.
import {Element} from '@lume/element'
class CoolElement extends Element {
- connectedCallback() {
- // Don't forget to call the super method from the Element class!
- super.connectedCallback()
+ connectedCallback() {
+ // Don't forget to call the super method from the Element class!
+ super.connectedCallback()
- // ...Create things...
- }
- // ...
+ // ...Create things...
+ }
+ // ...
}
```
-#### `disconnectedCallback`
+### `disconnectedCallback`
Nothing new here, this is simply a part of the browser's [native Custom Elements
`disconnectedCallback` API](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
@@ -1052,17 +824,17 @@ clean things up.
import {Element} from '@lume/element'
class CoolElement extends Element {
- disconnectedCallback() {
- // Don't forget to call the super method from the Element class!
- super.disconnectedCallback()
+ disconnectedCallback() {
+ // Don't forget to call the super method from the Element class!
+ super.disconnectedCallback()
- // ...Clean things up...
- }
- // ...
+ // ...Clean things up...
+ }
+ // ...
}
```
-#### `adoptedCallback`
+### `adoptedCallback`
Nothing new here, this is simply a part of the browser's [native Custom Elements
`adoptedCallback` API](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
@@ -1072,17 +844,17 @@ It is triggered when the element is adopted into a new document (f.e. in an ifra
import {Element} from '@lume/element'
class CoolElement extends Element {
- adoptedCallback() {
- // Don't forget to call the super method from the Element class!
- super.adoptedCallback()
+ adoptedCallback() {
+ // Don't forget to call the super method from the Element class!
+ super.adoptedCallback()
- // ...Do something when the element was transferred into another window's or iframe's document...
- }
- // ...
+ // ...Do something when the element was transferred into another window's or iframe's document...
+ }
+ // ...
}
```
-#### `attributeChangedCallback`
+### `attributeChangedCallback`
Nothing new here, this is simply a part of the browser's [native Custom Elements
`attributeChangedCallback` API](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
@@ -1093,18 +865,18 @@ or removed.
import {Element} from '@lume/element'
class CoolElement extends Element {
- static observedAttributes = ['foo', 'bar']
-
- attributeChangedCallback(attributeName, oldValue, newValue) {
- // Don't forget to call the super method from the Element class!
- super.attributeChangedCallback(attributeName, oldValue, newValue)
-
- // Attribute name is the name of the attribute change changed.
- // If `oldValue` is `null` and `newValue` is a string, it means the attribute was added.
- // If `oldValue` and `newValue` are both strings, it means the value changed.
- // If `oldValue` is a string and `newValue` is `null`, it means the attribute was removed.
- }
- // ...
+ static observedAttributes = ['foo', 'bar']
+
+ attributeChangedCallback(attributeName, oldValue, newValue) {
+ // Don't forget to call the super method from the Element class!
+ super.attributeChangedCallback(attributeName, oldValue, newValue)
+
+ // Attribute name is the name of the attribute change changed.
+ // If `oldValue` is `null` and `newValue` is a string, it means the attribute was added.
+ // If `oldValue` and `newValue` are both strings, it means the value changed.
+ // If `oldValue` is a string and `newValue` is `null`, it means the attribute was removed.
+ }
+ // ...
}
```
@@ -1113,7 +885,7 @@ class CoolElement extends Element {
> attributes will trigger `attributeChangedCallback`. `attributeChangedCallback`
> will not be triggered for any attributes that are not listed in `static observedAttributes`!
-#### `static observedAttributes`
+### `static observedAttributes`
Nothing new here, this is simply a part of the browser's [native Custom Elements
`static observedAttributes` API](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes).
@@ -1121,21 +893,32 @@ It defines which attributes will be observed. From the previous example:
```js
class CoolElement extends Element {
- static observedAttributes = ['foo', 'bar']
- // ...
+ static observedAttributes = ['foo', 'bar']
+ // ...
}
```
-#### `static observedAttributeHandlers`
+Note! Although `static observedAttributes` works, it is recommended to use the
+`static observedAttributeHandlers` property instead:
+
+### `static observedAttributeHandlers`
+
+This is an alternative to attribute decorators (recommended, see the
+[Decorators](#decorators) docs below), and will be removed after decorators
+are supported natively in JS engines.
As an alternative to `static observedAttributes`, and mainly for non-decorator
-users (because not all JS engines support them yet at time of writing this), observed
-attributes can be defined with `static observedAttributeHandlers`, a map of
-attribute names to attribute handlers. This requires using the `@element`
+users (because not all JS engines support them yet at time of writing this),
+observed attributes can be defined with `static observedAttributeHandlers`, a
+map of attribute names to attribute handlers. This requires using the `@element`
decorator (calling it as a plain function for non-decorator usage). This will
map attributes to JS properties and make the JS properties reactive.
-Each value in the `observedAttributeHandlers` object has the following shape:
+`static observedAttributeHandlers` is an object where each key is a property
+name to be associated with an attribute, and each value is an object with the
+following shape:
+
+ = {
- // TODO `to` handler currently does nothing. If it is present, then prop
- // changes should reflect back to the attribute. This will add a performance
- // hit.
- to?: (propValue: T) => string | null
-
- /**
- * Define how to deserialize an attribute string value on its way to the
- * respective JS property.
- *
- * If not defined, the attribute string value is passed to the JS property
- * untouched.
- */
- from?: (AttributeValue: string) => T
-
- /**
- * The default value that the respective JS property should have when the
- * attribute is removed.
- *
- * If not initially defined, this will be defined to whatever the initial JS
- * property value is.
- *
- * When explicitly defined, an attribute's respective JS property will be set to this
- * value when the attribute is removed, even if that is different than the JS property's initial value.
- *
- * If this is not explicitly defined, and the JS property has no initial
- * value, then the JS property will receive `undefined` when the attribute is
- * removed which matches the initial value of the JS property (this is not
- * ideal, especially in TypeScript, you should provide initial JS property
- * values so that shapes of your elements are well defined), just like
- * `attributeChangedCallback` does.
- */
- default?: T
+ // TODO The `to` handler currently does nothing. In the future, if there is demand
+ // for it, this will be for property-to-attribute reflection.
+ to?: (propValue: T) => string | null
+
+ /**
+ * Define how to deserialize an attribute string value on its way to the
+ * respective JS property.
+ *
+ * If not defined, the attribute string value is passed to the JS property
+ * untouched.
+ *
+ * **Default when omitted:** `value => value`
+ */
+ from?: (AttributeValue: string) => T
+
+ /**
+ * A side effect to run when the value is set on the JS property. It also
+ * runs on with the initial value. Avoid this if you can, and instead use
+ * effects. One use case of this is to call addEventListener with event
+ * listener values, just like with native `.on*` properties.
+ *
+ * **Default when omitted:** `() => {}` (no sideeffect)
+ */
+ sideEffect?: (instance: Element, prop: string, propValue: T) => void
+
+ /**
+ * @deprecated - Define a field with the initial value instead of providing
+ * the initial value here. When decorators land in browsers, this will be
+ * removed.
+ *
+ * The default value that the respective JS property should have when the
+ * attribute is removed.
+ *
+ * If this is not specified, and the respective class field is defined, it
+ * will default to the initial value of the class field. If this is
+ * specified, it will take precedence over the respective field's initial
+ * value. This should generally be avoided, and the class field initial
+ * value should be relied on as the source of the default value.
+ *
+ * When defined, an attribute's respective JS property will be set to this
+ * value when the attribute is removed. If not defined, then the JS property
+ * will always receive the initial value of the respective JS class field or
+ * `undefined` if the field was not defined (that's the "initial value" of
+ * the field), when the attribute is removed.
+ *
+ * **Default when omitted:** the value of the respective class field, or
+ * `undefined` if the field was not defined.
+ */
+ default?: T
+
+ /**
+ * Whether to convert the property name to dash-case for the attribute name.
+ * This option is ignore if the `name` option is set.
+ *
+ * The default is `true`, where the attribute name will be the same as the
+ * property name but dash-cased (and all lower case). For example, `fooBar`
+ * becomes `foo-bar` and `foo-bar` stays `foo-bar`.
+ *
+ * If this is set to `false`, the attribute name will be the same as the
+ * property name, but all lowercased (attributes are case insensitive). For
+ * example `fooBar` becomes `foobar` and `foo-bar` stays `foo-bar`.
+ *
+ * Note! Using this option to make a non-standard prop-attribute mapping
+ * will result in template type definitions (f.e. in JSX) missing the
+ * customized attribute names and will require custom type definition
+ * management.
+ *
+ * **Default when omitted:** `true`
+ */
+ dashcase?: boolean
+
+ /**
+ * The name of the attribute to use. Use of this options bad practice to be
+ * avoided, but it may be useful in rare cases.
+ *
+ * If this is not specified, see `dashcase` for how the attribute name is
+ * derived from the property name.
+ *
+ * Note! Using this option to make a non-standard prop-attribute mapping
+ * will result in template type definitions (f.e. in JSX) missing the
+ * customized attribute names and will require custom type definition
+ * management.
+ *
+ * **Default when omitted:** the attribute name derived from the property
+ * name, converted to dash-case based on the `dashcase` option.
+ */
+ name?: string
+
+ /**
+ * Whether to suppress warnings about the attribute attribute name clashes
+ * when not using default `dashcase` and `name` settings. This is
+ * discouraged, and should only be used when you know what you're doing,
+ * such as overriding a property that has `dashcase` set to `false` or
+ * `name` set to the same name as the attribue of another property.
+ *
+ * **Default when omitted:** `false`
+ */
+ noWarn?: boolean
}
```
@@ -1184,291 +1033,259 @@ HTML attributes mapped to same-name JS properties:
```js
import {Element, element} from '@lume/element'
-element('cool-element')(
- class CoolElement extends Element {
- static observedAttributeHandlers = {
- foo: {from: Number},
- bar: {from: Boolean},
- }
+element(
+ class CoolElement extends Element {
+ static elementName = 'cool-element'
- // Due to the `observedAttributeHandlers` definition, any time the `"foo"` attribute
- // on the element changes, the attribute string value will be converted into a
- // `Number` and assigned to the JS `.foo` property.
- // Not only does `.foo` have an initial value of `123`, but when the element's
- // `"foo"` attribute is removed, `.foo` will be set back to the initial value
- // of `123`.
- foo = 123
-
- // Due to the `observedAttributeHandlers` definition, any time the `"bar"` attribute
- // on the element changes, the attribute string value will be converted into a
- // `Boolean` and assigned to the JS `.bar` property.
- // Not only does `.bar` have an initial value of `123`, but when the element's
- // `"bar"` attribute is removed, `.bar` will be set back to the initial value
- // of `false`.
- bar = false
-
- // ...
- },
+ static observedAttributeHandlers = {
+ foo: {from: Number},
+ bar: {from: Boolean},
+ }
+
+ // Due to the `observedAttributeHandlers` definition, any time the `"foo"` attribute
+ // on the element changes, the attribute string value will be converted into a
+ // `Number` and assigned to the JS `.foo` property.
+ // Not only does `.foo` have an initial value of `123`, but when the element's
+ // `"foo"` attribute is removed, `.foo` will be set back to the initial value
+ // of `123`.
+ foo = 123
+
+ // Due to the `observedAttributeHandlers` definition, any time the `"bar"` attribute
+ // on the element changes, the attribute string value will be converted into a
+ // `Boolean` and assigned to the JS `.bar` property.
+ // Not only does `.bar` have an initial value of `123`, but when the element's
+ // `"bar"` attribute is removed, `.bar` will be set back to the initial value
+ // of `false`.
+ bar = false
+
+ // ...
+ },
)
```
[Example on CodePen](https://codepen.io/trusktr/pen/rNEXoOb?editors=1111)
`@lume/element` comes with a set of basic handlers available out of the box, each of
-which are alternatives to a respective set of included decorators:
+which are alternatives to a respective set of included [decorators](#decorators):
```js
import {Element, element, attribute} from '@lume/element'
-element('cool-element')(
- class CoolElement extends Element {
- static observedAttributeHandlers = {
- lorem: {}, // Effectively the same as attribute.string()
- foo: attribute.string(), // Effectively the same as the @stringAttribute decorator. Values get passed to the JS property as strings.
- bar: attribute.number(), // Effectively the same as the @numberAttribute decorator. Values get passed to the JS property as numbers.
- baz: attribute.boolean(), // Effectively the same as the @booleanAttribute decorator. Values get passed to the JS property as booleans.
+element(
+ class CoolElement extends Element {
+ static elementName = 'cool-element'
- // Here we define an attribute with custom handling of the string value, in this case making it accept a JSON string that maps it to a parsed object on the JS property.
- bespoke: {from: value => JSON.parse(value)}, // f.e. besoke='{"b": true}' results in the JS property having the value `{b: true}`
- }
+ static observedAttributeHandlers = {
+ lorem: {}, // Effectively the same as attribute.string
+ foo: attribute.string, // Effectively the same as the @stringAttribute decorator. Values get passed to the JS property as strings.
+ bar: attribute.number, // Effectively the same as the @numberAttribute decorator. Values get passed to the JS property as numbers.
+ baz: attribute.boolean, // Effectively the same as the @booleanAttribute decorator. Values get passed to the JS property as booleans.
- // The initial values of the JS properties define the values that the JS properties get reset back to when the corresponding attributes are removed.
- lorem = 'hello'
- foo = 'world'
- bar = 123
- baz = false
- bespoke = {n: 123}
+ // Here we define an attribute with custom handling of the string value, in this case making it accept a JSON string that maps it to a parsed object on the JS property.
+ bespoke: {from: value => JSON.parse(value)}, // f.e. besoke='{"b": true}' results in the JS property having the value `{b: true}`
+ }
- // ...
- },
+ // The initial values of the JS properties define the values that the JS properties get reset back to when the corresponding attributes are removed.
+ lorem = 'hello'
+ foo = 'world'
+ bar = 123
+ baz = false
+ bespoke = {n: 123}
+
+ // ...
+ },
)
```
[Example on CodePen](https://codepen.io/trusktr/pen/rNEXbOR?editors=1011)
-If you have decorator support (either with a build, or natively in near-future
-JS engines), defining attributes with decorators is simpler and more concise:
+If decorator support is present (either with a build, or natively in near-future
+JS engines), defining attributes with [decorators](#decorators) is simpler and more concise:
```js
import {Element, element, numberAttribute, booleanAttribute} from '@lume/element'
-@element('cool-element')
+@element
class CoolElement extends Element {
- // Due to the `@numberAttribute` decorator, any time the `"foo"` attribute
- // on the element changes, the attribute string value will be converted into a
- // `Number` and assigned to the JS `.foo` property.
- // Not only does `.foo` have an initial value of `123`, but when the element's
- // `"foo"` attribute is removed, `.foo` will be set back to the initial value
- // of `123`.
- @numberAttribute foo = 123
-
- // Due to the `@booleanAttribute` decorator, any time the `"bar"` attribute
- // on the element changes, the attribute string value will be converted into a
- // `Boolean` and assigned to the JS `.bar` property.
- // Not only does `.bar` have an initial value of `true`, but when the element's
- // `"bar"` attribute is removed, `.bar` will be set back to the initial value
- // of `true`.
- @booleanAttribute bar = true
-
- // ...
+ static elementName = 'cool-element'
+
+ // Due to the `@numberAttribute` decorator, any time the `"foo"` attribute
+ // on the element changes, the attribute string value will be converted into a
+ // `Number` and assigned to the JS `.foo` property.
+ // Not only does `.foo` have an initial value of `123`, but when the element's
+ // `"foo"` attribute is removed, `.foo` will be set back to the initial value
+ // of `123`.
+ @numberAttribute foo = 123
+
+ // Due to the `@booleanAttribute` decorator, any time the `"bar"` attribute
+ // on the element changes, the attribute string value will be converted into a
+ // `Boolean` and assigned to the JS `.bar` property.
+ // Not only does `.bar` have an initial value of `true`, but when the element's
+ // `"bar"` attribute is removed, `.bar` will be set back to the initial value
+ // of `true`.
+ @booleanAttribute bar = true
+
+ // ...
}
```
> [!Note]
> Not only do decorators make the definition more concise, but they avoid surface
> area for human error: the non-decorator form requires defining the same-name
-> property in both the `observedAttributeHandlers` object and in the class fields, and if
-> you miss one or the other then things might not work as expected.
+> property in both the `static observedAttributeHandlers` object and in the class fields, and if
+> we miss one or the other then things might not work as expected.
-Each of the available decorators are detailed further below.
+Each of the available decorators are detailed further [below](#decorators).
-Decorators, and the `observedAttributeHandlers` object format, both work with
+Decorators, and the `static observedAttributeHandlers` object format, both work with
getter/setter properties as well:
```js
import {Element, element, numberAttribute, booleanAttribute} from '@lume/element'
-@element('cool-element')
+@element // The 'cool-element' name is implied from the constructor name (dash-cased)
class CoolElement extends Element {
- #foo = 123
-
- // Like with class fields, the initial value is 123, so when the "foo"
- // attribute is removed the setter will receive 123.
- @numberAttribute
- get foo() {
- return this.#foo
- }
- set foo(v) {
- this.#foo = v
- }
- // ...
+ #foo = 123
+
+ // Like with class fields, the initial value is 123, so when the "foo"
+ // attribute is removed the setter will receive 123.
+ @numberAttribute
+ get foo() {
+ return this.#foo
+ }
+ set foo(v) {
+ this.#foo = v
+ }
+ // ...
}
```
-Auto accessors are not supported yet. If there is enough demand for them, we'll add support and they will look like so:
+They also work with "auto accessors", which creates a _prototype_ getter/setter:
```js
-@element('cool-element')
+@element
class CoolElement extends Element {
- // The same rules with initial values and attribute removal will apply.
- @numberAttribute accessor foo = 123
- @booleanAttribute accessor bar = false
+ // The same rules with initial values and attribute removal apply.
+ @numberAttribute accessor foo = 123
+ @booleanAttribute accessor bar = false
- // ...
+ // ...
}
```
-#### `createEffect`
+It may be redundant to write `accessor` repeatedly for each property when the
+alternative non-accessor format works too. The `accessor` format can be a
+fallback in very rare cases where a performance boost is needed (for example
+thousands of objects with many non-accessor properties being instantiated all at
+once). Most likely there will be _other_ performance issues at the point in
+which we have thousands of elements being instantiated at once causing an any
+issues.
-The `createEffect` method is a wrapper around Solid's `createEffect` with some differences for convenience:
+#### events with `static observedAttributeHandlers`
-- `createRoot` is not required in order to dispose of effects created with `this.createEffect()`
-- Effects created with `this.createEffect()` will automatically be cleaned up when the element is disconnected.
-- Besides being useful for re-running logic on signals changes,
- `this.createEffect()` is useful as an alternative to `disconnectedCallback` when
- paired with Solid's `onCleanup`.
+This is an alternative for the `@eventAttribute` decorator (recommended, see the
+[`@eventAttribute`](#eventattribute) docs below), and will be removed after
+native support for decorators lands in JS engines.
```js
-import {Element} from '@lume/element'
-import {createSignal, onCleanup} from 'solid-js'
+import {Element, element, attribute} from '@lume/element'
-const [count, setCount] = createSignal(0)
+const SomeEl = element('some-el')(
+ class extends Element {
+ static observedAttributeHandlers = {
+ onjump: attribute.event,
+ }
-setInterval(() => setCount(n => ++n), 1000)
+ // Also define the property explicitly (here with an optional type definition).
+ /** @type {EventListener | null} */
+ onjump = null
-class CoolElement extends Element {
- connectedCallback() {
- super.connectedCallback()
+ connectedCallback() {
+ super.connectedCallback()
- // Log `count()` any time it changes.
- this.createEffect(() => console.log(count()))
+ // This element dispatches a "jump" event every second:
+ setInterval(() => this.dispatchEvent(new Event('jump')), 1000)
+ }
+ },
+)
- this.createEffect(() => {
- const interval1 = setInterval(() => console.log('interval 1'), 1000)
- onCleanup(() => clearInterval(interval1))
+const el = new SomeEl()
- const interval2 = setInterval(() => console.log('interval 2'), 1000)
- onCleanup(() => clearInterval(interval2))
- })
- }
-}
+el.onjump = () => console.log('jump!')
+// or, as with "onclick" and other built-in attributes:
+el.setAttribute('onjump', "console.log('jump!')")
-customElements.define('cool-element', CoolElement)
+document.body.append(el)
-// After removing the element, onCleanup fires and cleans up the intervals created in connectedCallback (not the count interval outside the element)
-setTimeout(() => {
- const el = document.querySelector('cool-element')
- el.remove()
-}, 2000)
+// "jump!" will be logged every second.
```
-[Example on CodePen](https://codepen.io/trusktr/pen/MWNgaGQ?editors=1011)
-
-Compare that to using `disconnectedCallback`:
-
-```js
-import {Element} from '@lume/element'
-import {createSignal, onCleanup} from 'solid-js'
+Note that for TypeScript JSX types (TSX), we want to also define event
+properties on the class, for example `onjump` in the last example. Any
+properties that start with `on` will be mapped to `on`-prefixed JSX props for
+type checking. See the [TypeScript](#typescript) section for more info.
-const [count, setCount] = createSignal(0)
+### `static elementName`
-setInterval(() => setCount(n => ++n), 1000)
+The default tag name of the elements this class instantiates. When using the
+`@element` decorator, this name value will be used if a name value is not
+supplied to the decorator.
-class CoolElement extends Element {
- #interval1 = 0
- #interval2 = 0
+```js
+@element
+class SomeEl extends LumeElement {
+ static elementName = 'some-el'
+}
- connectedCallback() {
- super.connectedCallback()
+console.log(document.createElement('some-el') instanceof SomeEl) // true
+```
- // Log `count()` any time it changes.
- this.createEffect(() => console.log(count()))
+[Example on CodePen](https://codepen.io/trusktr/pen/ZEdgMZY)
- this.#interval1 = setInterval(() => console.log('interval 1'), 1000)
- this.#interval2 = setInterval(() => console.log('interval 2'), 1000)
- }
+### `static autoDefine`
- disconnectedCallback() {
- super.disconnectedCallback()
+Set this to `false` to tell the `@element` decorator (or `element()` when called
+as a function) to not automatically define the element in the global
+`customElements` registry. When un-specified, it defaults to `true`.
- clearInterval(this.#interval1)
- clearInterval(this.#interval2)
- }
+```js
+@element
+class SomeEl extends LumeElement {
+ static elementName = 'some-el'
+ static autoDefine = false
}
-customElements.define('cool-element', CoolElement)
+const el = document.createElement('some-el')
+console.log(el instanceof SomeEl) // false
+customElements.define(SomeEl.elementName, SomeEl)
+console.log(el instanceof SomeEl) // true
```
-> :bulb:**Tip:**
->
-> Prefer `onCleanup` instead of `disconnectedCallback` because composition of
-> logic will be easier while also keeping it co-located and easier to read. That
-> example is simple, but when logic grows, having to clean things up in
-> `disconnectedCallback` can get more complicated, especially when each piece of
-> creation logic and cleanup logic is multiple lines long and interleaving
-> them would be harder to read. Plus, putting them in effects makes them
-> creatable+cleanable if signals in the effects change, not just if the element is
-> connected or disconnected. For example, the following element cleans up the
-> interval any time the signal changes, not only on disconnect:
+Preventing automatic definition can be useful for use with non-global
+CustomElementRegistry instances for scoping element definitions to ShadowRoots,
```js
-import {Element} from '@lume/element'
-import {createSignal, onCleanup} from 'solid-js'
-
-const [count, setCount] = createSignal(0)
-
-setInterval(() => setCount(n => ++n), 1000)
-
-class CoolElement extends Element {
- connectedCallback() {
- super.connectedCallback()
-
- // Log `count()` any time it changes.
- this.createEffect(() => console.log(count()))
-
- this.createEffect(() => {
- // Run the interval only during moments that count() is an even number.
- // Whenever count() is odd, the running interval will be cleaned up and a new interval will not be created.
- // Also, when the element is disconnected (while count() is even), the interval will be cleaned up.
- if (count() % 2 !== 0) return
- const interval = setInterval(() => console.log('interval'), 100)
- onCleanup(() => clearInterval(interval))
- })
- }
+// Use a non-global element registry instead of the default global element registry:
+const myRegistry = new CustomElementRegistry()
+SomeEl.defineElement(myRegistry)
+
+// Use the non-global registry for scoped element definitions inside a custom element's ShadowRoot:
+class SomeElementWithScopedRegistry extends HTMLElement {
+ constructor() {
+ super()
+ const root = this.attachShadow({mode: 'open', customElementRegistry: myRegistry})
+ root.innerHTML = ` with the SomeEl class
+SomeEl.defineElement('some-el-renamed')
```
-[Example on CodePen](https://codepen.io/trusktr/pen/ZEdgMZY)
-
-#### `static defineElement`
+### `static defineElement`
Define this class for the given element `name`, or using its default name
(`TheClass.elementName`) if no was `name` given and the element was not already
@@ -1477,19 +1294,41 @@ defined using the `@element` decorator. Defaults to using the global
ShadowRoot-scoped registry) as a second argument.
```js
-@element('some-el') // defines with the decorated class
+// Defines with the decorated class, using the passed-in name.
+@element('some-el')
class SomeEl extends LumeElement {}
-const OtherEl = SomeEl.defineElement('other-el') // defines with an empty subclass of SomeEl
+// Defines with an empty subclass of SomeEl using the name passed
+// into .defineElement().
+const OtherEl = SomeEl.defineElement('other-el')
console.log(OtherEl === SomeEl) // false
-@element // without a name, the decorator does not perform the element definition
-class AnotherEl extends LumeElement {}
+@element
+class AnotherEl extends LumeElement {
+ static autoDefine = false
+}
+// The first call to .defineElement() will not make a subclass if the class has
+// not been used in a definition yet.
const El = AnotherEl.defineElement('another-el') // defines
console.log(El === AnotherEl) // true
+
+// The second call to .defineElement() will make a new subclass.
const El2 = AnotherEl.defineElement('yet-another-el') // defines
console.log(El2 === AnotherEl) // false
+
+// Use a non-global element registry instead of the default global element registry:
+const myRegistry = new CustomElementRegistry()
+AnotherEl.defineElement('one-more-el', myRegistry)
+
+// Use the non-global registry for scoped element definitions inside a custom element's ShadowRoot:
+class SomeElementWithScopedRegistry extends HTMLElement {
+ constructor() {
+ super()
+ const root = this.attachShadow({mode: 'open', customElementRegistry: myRegistry})
+ root.innerHTML = `hello
`
+ template = () => html`hello
`
}
```
@@ -1525,9 +1364,9 @@ The `template` content will be appended to the SomeEl instance directly, with no
```html
` no longer works because it must be
> inside a ShadowRoot, therefore going without a ShadowRoot is useful moreso for
-> elements that are leafs at the end of your DOM tree branches and elements that
-> will not slot accept any children and will only have `template` content as their
+> elements that are leafs at the end of DOM tree branches and elements that
+> will not accept any slotted children and will only have `template` content as their
> children.
-#### `root`
-
-Deprecated, renamed to `templateRoot`.
-
-#### `templateRoot`
+### `templateRoot`
Subclasses can override the `templateRoot` property to provide an alternate Node for
`template` content to be placed into (f.e. a subclass can set it to `this` to have
@@ -1555,18 +1390,18 @@ A primary use case for this is customizing the ShadowRoot:
```js
@element('some-el')
class SomeEl extends Element {
- // Create the element's ShadowRoot with custom options for example:
- templateRoot = this.attachShadow({
- mode: 'closed',
- })
+ // Create the element's ShadowRoot with custom options for example:
+ templateRoot = this.attachShadow({
+ mode: 'closed',
+ })
- template = () => html`hello
`
+ template = () => html`hello
`
}
```
[Example on CodePen](https://codepen.io/trusktr/pen/MWMNpbR)
-#### `shadowOptions`
+### `shadowOptions`
Define a `shadowOptions` property to specify any options for the element's
ShadowRoot. These options are passed to `attachShadow()`. This is a simpler
@@ -1575,13 +1410,13 @@ alternative to overriding `templateRoot` in the previous example.
```js
@element('some-el')
class SomeEl extends Element {
- shadowOptions = {mode: 'closed'}
+ shadowOptions = {mode: 'closed'}
- template = () => html`hello
`
+ template = () => html`hello
`
}
```
-#### `styleRoot`
+### `styleRoot`
Similar to the previous `templateRoot`, this defines which `Node` to append style
sheets to when `hasShadow` is `true`. This is ignored if `hasShadow` is
@@ -1589,20 +1424,21 @@ sheets to when `hasShadow` is `true`. This is ignored if `hasShadow` is
`ShadowRoot`.
When `hasShadow` is `true`, an alternate `styleRoot` is sometimes desired so
-that styles will be appended elsewhere than the `templateRoot`. To customize this, override it in your class:
+that styles will be appended elsewhere than the `templateRoot`. To customize
+this, override it:
```js
@element('some-el')
class SomeEl extends Element {
- styleRoot = document.createElement('div')
+ styleRoot = document.createElement('div')
- template = () => html`
-
-
${this.styleRoot}
+ template = () => html`
+
+
${this.styleRoot}
-
hello
-
- `
+
hello
+
will be defined
class CoolElement extends Element {
- // ...
+ // ...
}
```
@@ -1650,27 +1626,21 @@ class CoolElement extends Element {
> Make sure you extend from the `Element` base class from `@lume/element` when
> using the `@element` decorator.
-When not passed a string, the element will not be defined (while reactivity
-features will still be applied), and `customElements.define` should be used
-manually, which can be useful for upcoming scoped registries:
+When not passed a name string, the name is derived from the dash-cased name of
+the class:
```js
import {Element, element} from '@lume/element'
-@element
+@element // The 'cool-element' name is implied
class CoolElement extends Element {
- // ...
+ // ...
}
-
-customElements.define('cool-element', CoolElement)
-// or
-const myRegistry = new CustomElementRegistry()
-myRegistry.define('cool-element', CoolElement)
```
-Finally, even if passed a string for the element name, a second boolean option
-can disable automatic definition, and in this case the constructor's `.defineElement()`
-method can be used to trigger the definition using the given name:
+A second boolean argument can disable automatic definition in the global
+`customElements` registry. The constructor's `.defineElement()` method can then
+be used to manually trigger the definition using the given name:
```js
import {Element, element} from '@lume/element'
@@ -1679,10 +1649,22 @@ const autoDefine = false
@element('cool-element', autoDefine)
class CoolElement extends Element {
- // ...
+ // ...
}
-CoolElement.defineElement() // defines
+CoolElement.defineElement() // uses the global customElements to define
+// or
+const myRegistry = new CustomElementRegistry()
+CoolElement.defineElement(myRegistry) // uses a non-global registry to define
+
+// Use a non-global registry for scoped element definitions inside a custom element's ShadowRoot:
+class SomeElementWithScopedRegistry extends HTMLElement {
+ constructor() {
+ super()
+ const root = this.attachShadow({mode: 'open', customElementRegistry: myRegistry})
+ root.innerHTML = ` (even if `` is already defined)
```
-#### `@attribute`
+`@element` also accepts options as an object:
+
+```js
+const autoDefine = false
+
+@element({elementName: 'cool-element', autoDefine})
+class CoolElement extends Element {
+ // ...
+}
+```
+
+```js
+const autoDefine = false
+
+@element({autoDefine}) // The "cool-element" name is implied.
+class CoolElement extends Element {
+ // ...
+}
+```
+
+Without passing arguments to `@element`, options can be specified using
+static class fields:
+
+```js
+const autoDefine = false
+
+@element
+class CoolElement extends Element {
+ static elementName = 'cool-element'
+ static autoDefine = autoDefine
+ // ...
+}
+```
+
+The last format is nice and clean if you like all the aspects of your class
+defined _within_ the class, or your minifier is mangling your class name. It is
+also useful in TypeScript to avoid repeating the class name multiple times:
+
+```ts
+const autoDefine = false
+
+@element
+class CoolElement extends Element {
+ static readonly elementName = 'cool-element'
+ static readonly autoDefine = autoDefine
+ // ...
+}
+
+declare global {
+ interface HTMLElementTagNameMap {
+ // This avoids error-prone repitition of 'cool-element' in multiple locations.
+ [CoolElement.elementName]: CoolElement
+ }
+}
+```
+
+See more on [TypeScript](#typescript) below.
+
+### `@attribute`
A decorator for defining a generic element attribute. The name of the property
is mapped from camelCase to dash-case.
@@ -1701,15 +1741,17 @@ The `@attribute` decorator is effectively the same as the `@stringAttribute` dec
```ts
import {Element, element, attribute} from '@lume/element'
-@element('cool-element')
+@element
class CoolElement extends Element {
- @attribute firstName = null // the attribute name is first-name
- // ...
+ @attribute firstName = null // the attribute name is first-name
+ // ...
}
```
When an attribute is removed, the JS property will receive the default value
-determined by the initial value of the JS property.
+determined by the initial value of the JS property, ensuring consistency: when
+all attributes of an element are removed, the values the JS properties will have
+is known based on the class definition.
Sample usage of the attribute from the outside:
@@ -1741,48 +1783,49 @@ el.removeAttribute('first-name')
console.log(el.firstName) // logs "Batman"
```
-This is great because the intial values that you see in the class definition are
-always the expected values when the element has no attributes or when all
-attributes are removed, making the outcome predictable and consistent.
+The outcome is _predictable and consistent_.
-For TypeScript, you'll want the property type to be at least `string | null` if
-the initial value is `null`, as removing the attribute will set the JS property
-back to `null`.
+For TypeScript, if the initial value is a string and we're using `@attribute` (or
+`@stringAttribute`), then no type annotation is needed because it will always
+receive a string (f.e. even when the attribute is removed) and the type will be
+inferred from the initial value:
```ts
-import {Element, element, attribute} from '@lume/element'
-
-@element('cool-element')
+@element
class CoolElement extends Element {
- @attribute firstName: string | null = null
- // ...
+ @attribute firstName = 'Batman' // always a `string`
+ // ...
}
```
-For TypeScript, if the initial value is a string, then no type annotation is
-needed because it will always receive a string (f.e. even when the attribute is
-removed) and the type will be inferred from the initial value:
+You could of course make the string type more specific,
```ts
-import {Element, element, attribute} from '@lume/element'
-
-@element('cool-element')
+@element
class CoolElement extends Element {
- @attribute firstName = 'Batman' // always a `string`
- // ...
+ @attribute firstName: 'Batman' | 'Robin' = 'Batman'
+ // ...
}
```
+but note that this does not prevent any string value being set via the
+attribute.
+
You can of course make a broader type that accepts a string from the element
-attribute, but also other types via the JS property directly:
+attribute, but also other types via the JS property directly, but you'd
+generally want to avoid this, unless you're using a getter/setter to coerce
+setter values into a single consistent type that the getter always returns (like
+how the builtin `el.style=` can accept a string but the return value of
+`el.style` is always an object), or the user's input is always unchanged and
+mapped separately to internal structures:
```ts
import {Element, element, attribute} from '@lume/element'
-@element('cool-element')
+@element
class CoolElement extends Element {
- @attribute firstName: string | number = 'Batman'
- // ...
+ @attribute firstName: string | number = 'Batman'
+ // ...
}
```
@@ -1792,60 +1835,124 @@ const el = document.querySelector('cool-element')
el.firstName = 123 // ok
```
-> [!Note]
-> Assigning any other value will work because `@attribute` does not do any
-> coercion, it just accepts values as-is. But properties with specific attribute type decorators, f.e.
-> `@numberAttribute` below, will coerce values, and their type should be defined accordingly.
-
-#### `@stringAttribute`
-
-The `@stringAttribute` decorator is effectively the same as the `@attribute` decorator.
+#### Custom attribute handlers
-#### `@numberAttribute`
+The `@attribute` decorator is also useful for defining custom handling of
+attributes. For example, the following shows how we can define an attribute that
+can accept JSON string values by providing an
+[`AttributeHandler`](#attributehandler) definition, using the `from` option to
+define how string values _from_ the attribute are coerced when they are assigned
+to the JS property:
-A decorator that defines an attribute that accepts a number. Any value the
-attribute receives will be passed to the JS property. The JS property will
-convert a `null` value (attribute removed) to the default value defined by the
-initial property value, and will convert any string into a number (it will be
-`NaN` if the string is invalid).
+```js
+// Here, `attribute` is not called as a decorator. When `attribute` is given an
+// argument that defines how to handle an attribute, it will return a new
+// decorator function.
+const jsonAttribute = attribute({from: str => JSON.parse(str)})
+```
-```ts
-import {Element, element, numberAttribute} from '@lume/element'
+Now we can use the new `jsonAttribute` decorator in an element class:
-@element('cool-element')
+```js
+@element
class CoolElement extends Element {
- @numberAttribute age = 10
- // ...
+ @jsonAttribute someValue = {foo: 123}
+ // ...
}
```
-```js
-const el = document.querySelector('cool-element')
-
-el.setAttribute('age', '20')
-console.log(el.age) // logs 20
-console.log(typeof el.age) // logs "number"
+Now in HTML/DOM the attribute can accept JSON strings:
-el.removeAttribute('age')
+```html
+
+
The count is: {count()}
+ ,
+)
+
+el.setAttribute('foo', 'bar')
+
+document.body.appendChild(el)
+```
+
+The main differences from plain JS are
+
+- Use of the `@jsxImportSource` comment to place JSX types into scope. This is
+ required, or TypeScript will not know what the types of elements in JSX
+ markup are. Alternative to comments, configure it in tsconfig.json's
+ `compilerOptions`.
+- The `div()` helper function explicitly returns the type `HTMLDivElement` so
+ that the `el` variable will be typed as `HTMLDivElement` instead of
+ `JSX.Element`. Under the hood, the `div()` function is an identity function
+ at runtime, it simply returns whatever you pass into it, and serves only as a
+ convenient type cast helper.
+
+> [!Warning]
+> Keep in mind to use the correct type helper depending on what the root element
+> of the JSX expression is. For for example, if the root of a JSX expression is a
+> `` element then we need to use the `menu()` helper like follows.
+
+```tsx
+import {createSignal} from 'solid-js'
+import {menu} from '@lume/element/dist/type-helpers.js'
+
+// ...
+
+// The type of `el` will be `HTMLMenuElement`.
+const el = menu(
+
+ The count is: {count()}
+ ,
+)
+```
+
+If the wrong helper is used, then it will effectively cast the expression to
+the wrong type. For example, in the next snippet the `el` variable will be of
+type `HTMLDivElement` despite the fact that at runtime we will be have an
+`HTMLMenuElement` instance.
+
+```tsx
+import {div, button} from '@lume/element/dist/type-helpers.js'
+
+// GOOD.
+const el = button(... )
+
+// BAD! Don't do this! Remember to double check, because the helpers are not
+// type safe, you will not get an error here, and el2 will incorrectly be type
+// HTMLDivElement.
+const el2 = div(... )
+```
+
+Without the type helpers, we would need to write more verbose code like the
+following to have the proper types, but note that the following is also not type
+safe:
+
+```tsx
+// GOOD.
+const el = (... ) as any as HTMLMenuElement
+
+// BAD! Don't do this! Remember to double check, because the helpers are not
+// type safe, you will not get an error here.
+const el2 = (... ) as any as HTMLDivElement
+```
+
+## Type definitions for custom elements in frameworks
+
+(For type definitions for function components, see [Solid.js](https://solidjs.com) docs).
+
+### In Solid JSX (in Lume Elements)
+
+Example: ['kitchen-sink-tsx'](./examples/kitchen-sink-tsx/)
+
+First set up `jsxImportSource` as mentioned above.
+
+To give our Custom Elements type checking for use with DOM APIs, and type
+checking in Solid JSX, we can add the element type definition to
+`HTMLElementTagNameMap` and `JSX.IntrinsicElements`. Use the `ElementAttributes`
+helper to specify which attributes/properties should be exposed in the JSX type
+(we do not want to expose methods for example, or we may want to skip exposing
+some properties that are implementation details such as those prefixed with
+underscores to represent that they are internal, etc):
+
+```tsx
+import type {ElementAttributes} from '@lume/element'
+import {Element, element, stringAttribute, numberAttribute, eventAttribute} from '@lume/element'
+
+// List the properties that should be picked from the class type for JSX props.
+// Note! Make sure that the properties listed are either decorated with
+// attribute decorators, or that they are on* event properties.
+export type CoolElementAttributes = 'coolType' | 'coolFactor' | 'oncoolness'
+
+@element
+export class CoolElement extends Element {
+ static readonly elementName = 'cool-element'
+
+ @stringAttribute coolType: 'beans' | 'hair' = 'beans'
+ @numberAttribute coolFactor = 100
+ // ^ NOTE: These are the camelCase equivalents of the attributes defined above.
+
+ // For any given event our element will dispatch, define an event prop with
+ // the event name prefixed with 'on', and that accepts an event listener
+ // function or null.
+ @eventAttribute oncoolness: ((event: CoolnessEvent) => void) | null = null
+
+ // This property will not appear in the JSX types because it is not listed in
+ // the `CoolElementAttributes` that are passed to `ElementAttributes` below.
+ notJsxProp = 123
+
+ // ... Define the class as described above. ...
+}
+
+/** This an event that our element dispatches, for example. */
+class CoolnessEvent extends Event {
+ constructor() {
+ super('coolness', {...})
+ }
+}
+
+// Add our element to the list of known HTML elements. This makes it possible
+// for browser APIs to have the expected return types. For example, the return
+// type of `document.createElement('cool-element')` will be `CoolElement`.
+declare global {
+ interface HTMLElementTagNameMap {
+ [CoolElement.elementName]: CoolElement
+ }
+}
+
+// Hook up the type for use in Solid JSX templates
+declare module 'solid-js' {
+ namespace JSX {
+ interface IntrinsicElements {
+ [CoolElement.elementName]: ElementAttributes
+ }
+ }
+}
+```
+
+Now when we use `` in Solid JSX, it will be type checked:
+
+```jsx
+return (
+
+ }
+ }
+}
+```
+
+Now when we use `` in React JSX, it will be type checked:
+
+```jsx
+return (
+
+ }
+}
+```
+
+### In Svelte
+
+Example: ['kitchen-sink-svelte'](./examples/kitchen-sink-svelte/)
+
+Register the element type for Svelte like so:
+
+```ts
+import type {SvelteElementAttributes} from '@lume/element/dist/framework-types/vue.js'
+
+// ... the same CoolElement class and HTMLElementTagNameMap definitions as above ...
+
+// Hook up the type for use in Svelte templates
+declare module 'svelte/elements' {
+ interface SvelteHTMLElements {
+ [CoolElement.elementName]: SvelteElementAttributes
+ }
+}
+```
+
+### In Stencil.js JSX
+
+Example: ['kitchen-sink-stencil'](./examples/kitchen-sink-stencil/)
+
+Register the element type for Stencil.js like so:
+
+```ts
+import type {StencilElementAttributes} from '@lume/element/dist/framework-types/stencil.js'
+
+// ... the same CoolElement class and HTMLElementTagNameMap definitions as above ...
+
+// Hook up the type for use in Svelte templates
+declare module '@stencil/core' {
+ export namespace JSX {
+ interface IntrinsicElements {
+ [CoolElement.elementName]: StencilElementAttributes
+ }
+ }
+}
+```
+
+## Setter types in framework templates
+
+Given a custom element definition like so,
+
+```ts
+@element
+class MyEl extends Element {
+ static readonly elementName = 'my-el'
+
+ #position = new Vec3()
+
+ get position(): Vec3 {
+ return this.#position
+ }
+
+ set position(value: Vec3 | `${number} ${number} ${number}` | [number, number, number]) {
+ const {x, y, z} = parseValue(value)
+ this.#position.set(x, y, z)
+ }
+}
+```
+
+using it in JSX or other framework templates will show type errors for a use
+cases like this one,
+
+```jsx
+function MyComponent() {
+ return (
+ <>
+ ` using `@lume/element`
+- Real-time chat functionality with Meteor backend
+- User authentication integration
+- Simple, clean UI for messaging
+
+## Features
+
+- **Real-time messaging**: Messages appear instantly for all connected users
+- **User authentication**: Login required to send messages
+- **Simple UI**: Clean, minimal interface focused on the chat experience
+- **Custom element**: Reusable `` component that can be used anywhere
+
+## Usage
+
+Simply add the custom element to any HTML page:
+
+```html
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
From 06c3cb505dbbc7fe5a9b5819618d3fe51382562d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 19 Aug 2025 20:49:35 +0000
Subject: [PATCH 4/4] Refactor: Extract JavaScript code into separate modules
- Moved ChatWidget class to separate chat-widget.js file
- Extracted 3D background animation logic to background-animation.js
- Updated HTML to import modules using script type="module" tags
- Improved code organization and modularity as requested
Co-authored-by: trusktr <297678+trusktr@users.noreply.github.com>
---
examples/chat-widget/background-animation.js | 28 ++
examples/chat-widget/chat-widget.js | 386 +++++++++++++++++
examples/chat-widget/example.html | 418 +------------------
3 files changed, 419 insertions(+), 413 deletions(-)
create mode 100644 examples/chat-widget/background-animation.js
create mode 100644 examples/chat-widget/chat-widget.js
diff --git a/examples/chat-widget/background-animation.js b/examples/chat-widget/background-animation.js
new file mode 100644
index 0000000..1367a45
--- /dev/null
+++ b/examples/chat-widget/background-animation.js
@@ -0,0 +1,28 @@
+import {Motor} from 'lume'
+
+// Simple animation for background spheres
+export function initBackgroundAnimation() {
+ Motor.addRenderTask(time => {
+ const sphere1 = document.getElementById('sphere1')
+ const sphere2 = document.getElementById('sphere2')
+ const sphere3 = document.getElementById('sphere3')
+
+ if (sphere1) {
+ sphere1.rotation.x = time * 0.0005
+ sphere1.rotation.y = time * 0.0003
+ sphere1.position.z = -200 + Math.sin(time * 0.001) * 30
+ }
+
+ if (sphere2) {
+ sphere2.rotation.x = time * 0.0008
+ sphere2.rotation.z = time * 0.0004
+ sphere2.position.z = -150 + Math.cos(time * 0.0012) * 25
+ }
+
+ if (sphere3) {
+ sphere3.rotation.y = time * 0.0006
+ sphere3.rotation.z = time * 0.0005
+ sphere3.position.z = -100 + Math.sin(time * 0.0008) * 20
+ }
+ })
+}
\ No newline at end of file
diff --git a/examples/chat-widget/chat-widget.js b/examples/chat-widget/chat-widget.js
new file mode 100644
index 0000000..67c1cfd
--- /dev/null
+++ b/examples/chat-widget/chat-widget.js
@@ -0,0 +1,386 @@
+import {Element, element, css} from '@lume/element'
+import {createSignal, createEffect, For, Show} from 'solid-js'
+import html from 'solid-js/html'
+
+// Mock data for demonstration (in real app, this would use Meteor)
+let mockMessages = [
+ {id: 1, text: "Welcome to the chat! π", username: "System", createdAt: new Date(Date.now() - 300000)},
+ {id: 2, text: "This is a demo of the chat widget built with @lume/element!", username: "Demo User", createdAt: new Date(Date.now() - 200000)},
+ {id: 3, text: "Feel free to join and test it out!", username: "Demo User", createdAt: new Date(Date.now() - 100000)}
+]
+
+// Define the chat-widget custom element (without decorators for compatibility)
+export class ChatWidget extends Element {
+ static elementName = 'chat-widget'
+
+ constructor() {
+ super()
+ }
+
+ // Template function using Solid.js html template
+ template = () => {
+ const [messages, setMessages] = createSignal(mockMessages)
+ const [currentUser, setCurrentUser] = createSignal(null)
+ const [username, setUsername] = createSignal('')
+ const [message, setMessage] = createSignal('')
+
+ // Login handler
+ const handleLogin = (e) => {
+ e.preventDefault()
+ const user = username().trim()
+ if (!user) return
+
+ // Simple demo authentication
+ setCurrentUser({username: user, id: Date.now()})
+
+ // Add welcome message
+ const welcomeMsg = {
+ id: Date.now(),
+ text: `${user} joined the chat! π`,
+ username: "System",
+ createdAt: new Date()
+ }
+ setMessages([...messages(), welcomeMsg])
+ this.scrollToBottom()
+ }
+
+ // Send message handler
+ const handleSendMessage = (e) => {
+ e.preventDefault()
+ const msg = message().trim()
+ if (!msg || !currentUser()) return
+
+ const newMessage = {
+ id: Date.now(),
+ text: msg,
+ username: currentUser().username,
+ createdAt: new Date()
+ }
+
+ setMessages([...messages(), newMessage])
+ setMessage('')
+ this.scrollToBottom()
+ }
+
+ // Logout handler
+ const handleLogout = () => {
+ const user = currentUser()
+ setCurrentUser(null)
+ setUsername('')
+
+ // Add goodbye message
+ const goodbyeMsg = {
+ id: Date.now(),
+ text: `${user.username} left the chat. π`,
+ username: "System",
+ createdAt: new Date()
+ }
+ setMessages([...messages(), goodbyeMsg])
+ this.scrollToBottom()
+ }
+
+ return html`
+
+ `
+ }
+
+ // Helper method to scroll to bottom
+ scrollToBottom() {
+ setTimeout(() => {
+ const container = this.shadowRoot?.querySelector('.messages-container')
+ if (container) {
+ container.scrollTop = container.scrollHeight
+ }
+ }, 100)
+ }
+
+ // Styling for the chat widget
+ static css = css`
+ :host {
+ display: block;
+ max-width: 600px;
+ margin: 0 auto;
+ }
+
+ .chat-widget {
+ background: rgba(255, 255, 255, 0.95);
+ border-radius: 15px;
+ box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3);
+ overflow: hidden;
+ backdrop-filter: blur(10px);
+ }
+
+ .chat-container {
+ display: flex;
+ flex-direction: column;
+ height: 500px;
+ }
+
+ .chat-header {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ padding: 20px;
+ background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+ color: white;
+ }
+
+ .chat-header h3 {
+ margin: 0;
+ font-size: 1.3rem;
+ }
+
+ .user-info {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ font-size: 0.9rem;
+ }
+
+ .logout-btn {
+ background: rgba(255, 255, 255, 0.2);
+ border: 1px solid rgba(255, 255, 255, 0.3);
+ color: white;
+ padding: 5px 12px;
+ border-radius: 6px;
+ cursor: pointer;
+ font-size: 12px;
+ transition: all 0.2s;
+ }
+
+ .logout-btn:hover {
+ background: rgba(255, 255, 255, 0.3);
+ }
+
+ .messages-container {
+ flex: 1;
+ overflow-y: auto;
+ padding: 20px;
+ display: flex;
+ flex-direction: column;
+ gap: 15px;
+ scroll-behavior: smooth;
+ }
+
+ .message {
+ max-width: 80%;
+ padding: 12px 16px;
+ border-radius: 12px;
+ background: #f1f3f5;
+ align-self: flex-start;
+ }
+
+ .message.own-message {
+ background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+ color: white;
+ align-self: flex-end;
+ }
+
+ .message.system-message {
+ background: #e8f5e8;
+ color: #2d5a2d;
+ align-self: center;
+ max-width: 90%;
+ text-align: center;
+ border-left: 3px solid #4caf50;
+ }
+
+ .message-header {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+ margin-bottom: 5px;
+ gap: 10px;
+ }
+
+ .username {
+ font-size: 0.9rem;
+ opacity: 0.8;
+ font-weight: 600;
+ }
+
+ .timestamp {
+ font-size: 0.75rem;
+ opacity: 0.6;
+ }
+
+ .message-text {
+ word-wrap: break-word;
+ line-height: 1.4;
+ }
+
+ .message-form {
+ display: flex;
+ padding: 20px;
+ border-top: 1px solid #e9ecef;
+ gap: 10px;
+ }
+
+ .message-input {
+ flex: 1;
+ padding: 12px 16px;
+ border: 2px solid #e9ecef;
+ border-radius: 25px;
+ font-size: 14px;
+ outline: none;
+ transition: border-color 0.2s;
+ }
+
+ .message-input:focus {
+ border-color: #667eea;
+ }
+
+ .send-btn {
+ background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+ color: white;
+ border: none;
+ padding: 12px 20px;
+ border-radius: 25px;
+ cursor: pointer;
+ font-weight: 600;
+ min-width: 70px;
+ transition: all 0.2s;
+ }
+
+ .send-btn:disabled {
+ opacity: 0.5;
+ cursor: not-allowed;
+ }
+
+ .send-btn:not(:disabled):hover {
+ transform: translateY(-1px);
+ box-shadow: 0 5px 15px rgba(0, 0, 0, 0.2);
+ }
+
+ .login-container {
+ text-align: center;
+ padding: 40px;
+ }
+
+ .login-container h3 {
+ margin: 0 0 10px 0;
+ color: #333;
+ font-size: 1.5rem;
+ }
+
+ .login-container p {
+ margin: 0 0 30px 0;
+ color: #666;
+ }
+
+ .login-form {
+ display: flex;
+ flex-direction: column;
+ gap: 20px;
+ max-width: 300px;
+ margin: 0 auto;
+ }
+
+ .username-input {
+ padding: 15px 20px;
+ border: 2px solid #e9ecef;
+ border-radius: 25px;
+ font-size: 16px;
+ text-align: center;
+ outline: none;
+ transition: border-color 0.2s;
+ }
+
+ .username-input:focus {
+ border-color: #667eea;
+ }
+
+ .login-btn {
+ background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+ color: white;
+ border: none;
+ padding: 15px 30px;
+ border-radius: 25px;
+ cursor: pointer;
+ font-weight: 600;
+ font-size: 16px;
+ transition: all 0.2s;
+ }
+
+ .login-btn:hover {
+ transform: translateY(-1px);
+ box-shadow: 0 5px 15px rgba(0, 0, 0, 0.2);
+ }
+
+ .demo-note {
+ margin-top: 30px;
+ padding: 15px;
+ background: rgba(255, 255, 255, 0.1);
+ border-radius: 10px;
+ font-size: 0.9rem;
+ }
+
+ .demo-note p {
+ margin: 0;
+ opacity: 0.8;
+ }
+ `
+}
+
+// Register the custom element
+customElements.define('chat-widget', ChatWidget)
\ No newline at end of file
diff --git a/examples/chat-widget/example.html b/examples/chat-widget/example.html
index 064af50..57adfef 100644
--- a/examples/chat-widget/example.html
+++ b/examples/chat-widget/example.html
@@ -95,418 +95,10 @@ π¬ Chat Widget Demo
+
+
\ No newline at end of file