Build your own frontend framework

import {
  define,
  attr,
  string,
  number,
  connected,
  reactive,
} from "@sirpepe/ornament";

// Register the element with the specified tag name
@define("my-greeter")
class MyGreeter extends HTMLElement {
  // No built-in rendering functionality. Shadow DOM or light DOM? Template
  // strings, JSX, or something else entirely? You decide!
  #shadow = this.attachShadow({ mode: "open" });

  // Define content attributes alongside corresponding getter/setter pairs
  // for a JS api and attribute change handling and type checking. If you use
  // TypeScript, the type checks will work at compile time *and* at run time
  @attr(string()) accessor name = "Anonymous";
  @attr(number({ min: 0 })) accessor age = 0;

  // Mark the method as reactive to have it run every time one of the attributes
  // change, and also run it when the component first connects to the DOM.
  @reactive()
  @connected()
  greet() {
    this.#shadow.innerHTML = `Hello! My name is ${this.name}, my age is ${this.age}`;
  }
}

123456789101112131415161718192021222324252627282930

import {
  define,
  attr,
  string,
  number,
  connected,
  reactive,
} from "@sirpepe/ornament";

// Register the element with the specified tag name
@define("my-greeter")
class MyGreeter extends HTMLElement {
  // No built-in rendering functionality. Shadow DOM or light DOM? Template
  // strings, JSX, or something else entirely? You decide!
  #shadow = this.attachShadow({ mode: "open" });

  // Define content attributes alongside corresponding getter/setter pairs
  // for a JS api and attribute change handling and type checking. If you use
  // TypeScript, the type checks will work at compile time *and* at run time
  @attr(string()) accessor name = "Anonymous";
  @attr(number({ min: 0 })) accessor age = 0;

  // Mark the method as reactive to have it run every time one of the attributes
  // change, and also run it when the component first connects to the DOM.
  @reactive()
  @connected()
  greet() {
    this.#shadow.innerHTML = `Hello! My name is ${this.name}, my age is ${this.age}`;
  }
}

// Regular web component class
class ClickCounter extends HTMLElement {
}

// Regular web component class
class ClickCounter extends HTMLElement {
  // Public accessor for the initial value
  accessor value = 0;

  // Internal state for the current click count
  accessor #count = this.value;
}

import { define } from "@sirpepe/ornament";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public accessor for the initial value
  accessor value = 0;

  // Internal state for the current click count
  accessor #count = this.value;
}

import { define, attr, prop, number } from "@sirpepe/ornament";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public content attribute for the initial value
  @attr(number({ min: 0 })) accessor value = 0;

  // Internal attribute for the current click count
  @prop(number({ min: 0 })) accessor #count = this.value;
}

import { define, attr, prop, number } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public content attribute for the initial value
  @attr(number({ min: 0 })) accessor value = 0;

  // Internal attribute for the current click count
  @prop(number({ min: 0 })) accessor #count = this.value;
}

import { define, attr, prop, number } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public content attribute for the initial value
  @attr(number({ min: 0 })) accessor value = 0;

  // Internal attribute for the current click count
  @prop(number({ min: 0 })) accessor #count = this.value;

  // Component's render logic, boilt with preact
  #render() {}
}

import { define, attr, prop, number } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public content attribute for the initial value
  @attr(number({ min: 0 })) accessor value = 0;

  // Internal attribute for the current click count
  @prop(number({ min: 0 })) accessor #count = this.value;

  // Component's render logic, boilt with preact
  #render() {
    render(<></>, this);
  }
}

import { define, attr, prop, number } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public content attribute for the initial value
  @attr(number({ min: 0 })) accessor value = 0;

  // Internal attribute for the current click count
  @prop(number({ min: 0 })) accessor #count = this.value;

  // Component's render logic, boilt with preact
  #render() {
    render(
      <>
        <button onClick={() => this.#count++}>+1</button>
      </>,
      this,
    );
  }
}

import { define, attr, prop, number } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public content attribute for the initial value
  @attr(number({ min: 0 })) accessor value = 0;

  // Internal attribute for the current click count
  @prop(number({ min: 0 })) accessor #count = this.value;

  // Component's render logic, boilt with preact
  #render() {
    render(
      <>
        <button onClick={() => this.#count++}>+1</button>
        Total: <b>{this.#count}</b>
      </>,
      this,
    );
  }
}

import { define, attr, prop, number, connected } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public content attribute for the initial value
  @attr(number({ min: 0 })) accessor value = 0;

  // Internal attribute for the current click count
  @prop(number({ min: 0 })) accessor #count = this.value;

  // Component's render logic, boilt with preact
  @connected() // run method when the component connects
  #render() {
    render(
      <>
        <button onClick={() => this.#count++}>+1</button>
        Total: <b>{this.#count}</b>
      </>,
      this,
    );
  }
}

import { define, attr, prop, number, reactive, connected } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public content attribute for the initial value
  @attr(number({ min: 0 })) accessor value = 0;

  // Internal attribute for the current click count
  @prop(number({ min: 0 })) accessor #count = this.value;

  // Component's render logic, boilt with preact
  @connected() // run method when the component connects
  @reactive() // run method when attributes change
  #render() {
    render(
      <>
        <button onClick={() => this.#count++}>+1</button>
        Total: <b>{this.#count}</b>
      </>,
      this,
    );
  }
}

import { define, attr, prop, number, reactive, connected } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

// Register the class a a custom HTML tag
@define("click-counter")
class ClickCounter extends HTMLElement {
  // Public content attribute for the initial value
  @attr(number({ min: 0 })) accessor value = 0;

  // Internal attribute for the current click count
  @prop(number({ min: 0 })) accessor #count = this.value;

  // Component's render logic, boilt with preact
  @connected() // run method when the component connects
  @reactive({ keys: ["#count"] }) // run method when this.#count changes
  #render() {
    render(
      <>
        <button onClick={() => this.#count++}>+1</button>
        Total: <b>{this.#count}</b>
      </>,
      this,
    );
  }
}

1. Start with a regular, vanilla web component class.
2. Model the component's state using class accessors. Alternatively, you could store state in signals or on objects that implement EventTarget.
3. Import the decorator @define() to register your custom element class.
4. Use decorators @attr() and @prop() to define content and IDL attributes respectively. The number()-transformer plugs type-checking into the attributes.
5. Import Preact's functionality. Note that miuch of this can be abstracted away if you choose to write your own base class or micro-framework.
6. Write a method to handle rendering. Can be public, can be private, it's up to you.
7. Time to write some JSX. Don't like JSX? Then just use something else for rendering!
8. Listen for events. You could alternatively leverage event delegation in the component class, if that's more up your alley.
9. Show the current click count. Note that this could just as well be rendered into Shadow DOM if you need more encapsulation.
10. Use the decorator @connected() to run the render method when the component connects to the DOM.
11. Use the decorator @reactive() to run the render method when any attributes change. But since we only really care about #count …
12. … we make sure to only render-when something relevant to the method changes. @reactive() has multiple filtering options.

import { define } from "@sirpepe/ornament";

@define("my-test")
class MyTest extends HTMLElement {}

console.log(document.createElement("my-test")); // instance of MyTest

123456

import { define } from "@sirpepe/ornament";

@define("my-test")
class MyTest extends HTMLElement {}

console.log(document.createElement("my-test")); // instance of MyTest

import { enhance } from "@sirpepe/ornament";

@enhance()
class MyTest extends HTMLElement {}

// MyTest can only be instantiated when it has been registered as a custom
// element. Because we use @enhance() instead of @define() in this example, we
// have to take care of this manually.
window.customElements.define("my-test", MyTest);

console.log(document.createElement("my-test")); // instance of MyTest

1234567891011

import { enhance } from "@sirpepe/ornament";

@enhance()
class MyTest extends HTMLElement {}

// MyTest can only be instantiated when it has been registered as a custom
// element. Because we use @enhance() instead of @define() in this example, we
// have to take care of this manually.
window.customElements.define("my-test", MyTest);

console.log(document.createElement("my-test")); // instance of MyTest

import { enhance } from "@sirpepe/ornament";

// Not useful, but also not a problem
@enhance()
@enhance()
@enhance()
class MyTest0 extends HTMLElement {}

// Works
@enhance()
class Base1 extends HTMLElement {}
class MyTest1 extends Base1 {}

// Works
class Base2 extends HTMLElement {}
@enhance()
class MyTest2 extends Base2 {}

// Works
@enhance()
class Base3 extends HTMLElement {}
@enhance()
class MyTest3 extends Base3 {}

1234567891011121314151617181920212223

import { enhance } from "@sirpepe/ornament";

// Not useful, but also not a problem
@enhance()
@enhance()
@enhance()
class MyTest0 extends HTMLElement {}

// Works
@enhance()
class Base1 extends HTMLElement {}
class MyTest1 extends Base1 {}

// Works
class Base2 extends HTMLElement {}
@enhance()
class MyTest2 extends Base2 {}

// Works
@enhance()
class Base3 extends HTMLElement {}
@enhance()
class MyTest3 extends Base3 {}

import { define, prop, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Applies the number transformer to ensure that foo is always a number
  @prop(number()) accessor foo = 23;

  // Automatically runs when "foo" (or any accessor decorated with @prop() or
  // @attr()) changes
  @reactive()
  log() {
    console.log(`Foo changed to ${this.foo}`);
  }
}

let testEl = document.createElement("my-test");
console.log(testEl.foo); // logs 23
testEl.foo = 42; // logs "Foo changed to 42"
console.log(testEl.foo); // logs 42
testEl.foo = "asdf"; // throw exception (thanks to the number transformer)

1234567891011121314151617181920

import { define, prop, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Applies the number transformer to ensure that foo is always a number
  @prop(number()) accessor foo = 23;

  // Automatically runs when "foo" (or any accessor decorated with @prop() or
  // @attr()) changes
  @reactive()
  log() {
    console.log(`Foo changed to ${this.foo}`);
  }
}

let testEl = document.createElement("my-test");
console.log(testEl.foo); // logs 23
testEl.foo = 42; // logs "Foo changed to 42"
console.log(testEl.foo); // logs 42
testEl.foo = "asdf"; // throw exception (thanks to the number transformer)

import { define, attr, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Applies the number transformer to ensure that content attribute values get
  // parsed into numbers and that new non-number values passed to the property
  // setter get rejected
  @attr(number()) accessor foo = 23; // 23 = fallback value

  // Automatically runs when "foo", or any accessor decorated with @prop() or
  // @attr(), changes (plus once on element initialization)
  @reactive() log() {
    console.log(`Foo changed to ${this.foo}`);
  }
}

document.body.innerHTML = `<my-test foo="42"></my-test>`;
let testEl = document.querySelector("my-test");
console.log(testEl.foo); // logs 42 (initialized from the attribute)
testEl.foo = 1337; // logs "Foo changed to 1337"
console.log(testEl.foo); // logs 1337
console.log(testEl.getAttribute("foo")); // logs "1337"
testEl.foo = "asdf"; // throw exception (thanks to the number transformer)
testEl.setAttribute("foo", "asdf"); // works, content attributes can be any string
console.log(testEl.foo); // logs 23 (fallback value)

12345678910111213141516171819202122232425

import { define, attr, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Applies the number transformer to ensure that content attribute values get
  // parsed into numbers and that new non-number values passed to the property
  // setter get rejected
  @attr(number()) accessor foo = 23; // 23 = fallback value

  // Automatically runs when "foo", or any accessor decorated with @prop() or
  // @attr(), changes (plus once on element initialization)
  @reactive() log() {
    console.log(`Foo changed to ${this.foo}`);
  }
}

document.body.innerHTML = `<my-test foo="42"></my-test>`;
let testEl = document.querySelector("my-test");
console.log(testEl.foo); // logs 42 (initialized from the attribute)
testEl.foo = 1337; // logs "Foo changed to 1337"
console.log(testEl.foo); // logs 1337
console.log(testEl.getAttribute("foo")); // logs "1337"
testEl.foo = "asdf"; // throw exception (thanks to the number transformer)
testEl.setAttribute("foo", "asdf"); // works, content attributes can be any string
console.log(testEl.foo); // logs 23 (fallback value)

import { define, state } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @state()
  accessor foo = 0;
  // Default: tracks the state "foo" by transforming the value with Boolean()

  @state({ name: "isOdd", toBoolean: (value) => value % 2 !== 0 })
  accessor bar = 0;
  // Custom: tracks "bar" as "isOff" by transforming the value with toBoolean()
}

let testEl = document.createElement("my-test");

// Custom state "foo" is not set, since Boolean(0) === false
console.log(testEl.matches(":state(foo)")); // > false

// Custom state "isOdd" is not set, since (value % 2 !== 0) === false
console.log(testEl.matches(":state(isOdd)")); // > false

testEl.foo = 1;
testEl.bar = 1;

// Custom state "foo" is set, since Boolean(1) === true
console.log(testEl.matches(":state(foo)")); // > true

// Custom state "isOdd" is set, since (value % 2 !== 0) === true
console.log(testEl.matches(":state(isOdd)")); // > true

1234567891011121314151617181920212223242526272829

import { define, state } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @state()
  accessor foo = 0;
  // Default: tracks the state "foo" by transforming the value with Boolean()

  @state({ name: "isOdd", toBoolean: (value) => value % 2 !== 0 })
  accessor bar = 0;
  // Custom: tracks "bar" as "isOff" by transforming the value with toBoolean()
}

let testEl = document.createElement("my-test");

// Custom state "foo" is not set, since Boolean(0) === false
console.log(testEl.matches(":state(foo)")); // > false

// Custom state "isOdd" is not set, since (value % 2 !== 0) === false
console.log(testEl.matches(":state(isOdd)")); // > false

testEl.foo = 1;
testEl.bar = 1;

// Custom state "foo" is set, since Boolean(1) === true
console.log(testEl.matches(":state(foo)")); // > true

// Custom state "isOdd" is set, since (value % 2 !== 0) === true
console.log(testEl.matches(":state(isOdd)")); // > true

import { define, state, prop, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @prop(number({ min: 0 })) // <- @prop() comes first
  @state({ toBoolean: (x) => x % 2 === 0 }) // <- @state() comes last
  accessor foo = 0;
}

const testEl = new Test();
// state "foo" is true

testEl.foo = 1;
// state "foo" is false

try {
  testEl.foo = -2; // <- this fails
} catch {
  // state "foo" on el still false; @prop intercepted the set operation
}

1234567891011121314151617181920

import { define, state, prop, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @prop(number({ min: 0 })) // <- @prop() comes first
  @state({ toBoolean: (x) => x % 2 === 0 }) // <- @state() comes last
  accessor foo = 0;
}

const testEl = new Test();
// state "foo" is true

testEl.foo = 1;
// state "foo" is false

try {
  testEl.foo = -2; // <- this fails
} catch {
  // state "foo" on el still false; @prop intercepted the set operation
}

import { define, reactive, prop, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @prop(number()) accessor foo = 0;
  @prop(number()) accessor bar = 0;

  @reactive()
  log() {
    console.log(`foo is now ${this.foo}, bar is now ${this.bar}`);
  }
}

let testEl = document.createElement("my-test");
testEl.foo = 1;
testEl.bar = 2;

// first logs "foo is now 1, bar is now 0"
// then logs "foo is now 1, bar is now 2"

12345678910111213141516171819

import { define, reactive, prop, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @prop(number()) accessor foo = 0;
  @prop(number()) accessor bar = 0;

  @reactive()
  log() {
    console.log(`foo is now ${this.foo}, bar is now ${this.bar}`);
  }
}

let testEl = document.createElement("my-test");
testEl.foo = 1;
testEl.bar = 2;

// first logs "foo is now 1, bar is now 0"
// then logs "foo is now 1, bar is now 2"

import { define, init } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  constructor() {
    super();
    console.log(23);
  }

  @init()
  log() {
    console.log(42);
  }
}

let testEl = document.createElement("my-test");
// first logs 23, then logs 42

1234567891011121314151617

import { define, init } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  constructor() {
    super();
    console.log(23);
  }

  @init()
  log() {
    console.log(42);
  }
}

let testEl = document.createElement("my-test");
// first logs 23, then logs 42

import { define, connected } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @connected()
  log() {
    console.log("Connected!");
  }
}

let testEl = document.createElement("my-test");
document.body.append(testEl);
// testEl.log logs "Connected!"

12345678910111213

import { define, connected } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @connected()
  log() {
    console.log("Connected!");
  }
}

let testEl = document.createElement("my-test");
document.body.append(testEl);
// testEl.log logs "Connected!"

import { define, disconnected } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @disconnected()
  log() {
    console.log("Disconnected!");
  }
}

let testEl = document.createElement("my-test");
document.body.append(testEl);
testEl.remove();
// testEl.log logs "Disconnected!"

1234567891011121314

import { define, disconnected } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @disconnected()
  log() {
    console.log("Disconnected!");
  }
}

let testEl = document.createElement("my-test");
document.body.append(testEl);
testEl.remove();
// testEl.log logs "Disconnected!"

import { define, connectedMove } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @connectedMove()
  log() {
    console.log("Moved!");
  }
}

let testEl = document.createElement("my-test");
document.body.append(document.createElement("div"), testEl);
document.body.moveBefore(testEl, document.body.firstChild);
// testEl.log logs "Moved!"

1234567891011121314

import { define, connectedMove } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @connectedMove()
  log() {
    console.log("Moved!");
  }
}

let testEl = document.createElement("my-test");
document.body.append(document.createElement("div"), testEl);
document.body.moveBefore(testEl, document.body.firstChild);
// testEl.log logs "Moved!"

import { define, adopted } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @adopted() log() {
    console.log("Adopted!");
  }
}

let testEl = document.createElement("my-test");
const newDocument = new Document();
newDocument.adoptNode(testEl);
// testEl.log logs "Adopted!"

12345678910111213

import { define, adopted } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @adopted() log() {
    console.log("Adopted!");
  }
}

let testEl = document.createElement("my-test");
const newDocument = new Document();
newDocument.adoptNode(testEl);
// testEl.log logs "Adopted!"

import { define, formAssociated } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  static formAssociated = true;
  @formAssociated() log(newOwner) {
    console.log(newOwner); // null or HTMLFormElement
  }
}

let testEl = document.createElement("my-test");
let form = document.createElement("form");
form.append(testEl);
// testEl.log logs "form"

1234567891011121314

import { define, formAssociated } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  static formAssociated = true;
  @formAssociated() log(newOwner) {
    console.log(newOwner); // null or HTMLFormElement
  }
}

let testEl = document.createElement("my-test");
let form = document.createElement("form");
form.append(testEl);
// testEl.log logs "form"

import { define, formReset } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  static formAssociated = true;
  @formReset() log() {
    console.log("Reset!");
  }
}

let testEl = document.createElement("my-test");
let form = document.createElement("form");
form.append(testEl);
form.reset();
// ... some time passes...
// testEl.log logs "Reset!"

12345678910111213141516

import { define, formReset } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  static formAssociated = true;
  @formReset() log() {
    console.log("Reset!");
  }
}

let testEl = document.createElement("my-test");
let form = document.createElement("form");
form.append(testEl);
form.reset();
// ... some time passes...
// testEl.log logs "Reset!"

import { define, formDisabled } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  static formAssociated = true;
  @formDisabled() log(state) {
    console.log("Disabled via fieldset:", state); // true or false
  }
}

let testEl = document.createElement("my-test");
let fieldset = document.createElement("fieldset");
let form = document.createElement("form");
form.append(fieldset);
fieldset.append(testEl);
fieldset.disabled = true;
// testEl.log logs "Disabled via fieldset: true"

1234567891011121314151617

import { define, formDisabled } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  static formAssociated = true;
  @formDisabled() log(state) {
    console.log("Disabled via fieldset:", state); // true or false
  }
}

let testEl = document.createElement("my-test");
let fieldset = document.createElement("fieldset");
let form = document.createElement("form");
form.append(fieldset);
fieldset.append(testEl);
fieldset.disabled = true;
// testEl.log logs "Disabled via fieldset: true"

import { define, subscribe } from "@sirpepe/ornament";

const myTarget = new EventTarget();

@define("my-test")
class Test extends HTMLElement {
  @subscribe(myTarget, "foo")
  log(evt) {
    // evt = Event({ name: "foo", target: myTarget })
    // this = Test instance
    console.log(`'${evt.type}' event fired!`);
  }
}

let testEl = document.createElement("my-test");

myTarget.dispatchEvent(new Event("foo"));

// testEl.log logs "'foo' event fired!"

12345678910111213141516171819

import { define, subscribe } from "@sirpepe/ornament";

const myTarget = new EventTarget();

@define("my-test")
class Test extends HTMLElement {
  @subscribe(myTarget, "foo")
  log(evt) {
    // evt = Event({ name: "foo", target: myTarget })
    // this = Test instance
    console.log(`'${evt.type}' event fired!`);
  }
}

let testEl = document.createElement("my-test");

myTarget.dispatchEvent(new Event("foo"));

// testEl.log logs "'foo' event fired!"

import { define, subscribe } from "@sirpepe/ornament";

const myTarget = new EventTarget();

@define("my-test")
class Test extends HTMLElement {
  @subscribe(myTarget, "foo bar") #a() {} // subscribed to both "foo" and "bar"
}

12345678

import { define, subscribe } from "@sirpepe/ornament";

const myTarget = new EventTarget();

@define("my-test")
class Test extends HTMLElement {
  @subscribe(myTarget, "foo bar") #a() {} // subscribed to both "foo" and "bar"
}

import { define, subscribe } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // "window" is a perfectly valid event target
  @subscribe(window, "update") #a() {} // same effect as below
  @subscribe(() => window, "update") #b() {} // same effect as above
  @subscribe(Promise.resolve(window), "update") #c() {} // same effect as above
}

123456789

import { define, subscribe } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // "window" is a perfectly valid event target
  @subscribe(window, "update") #a() {} // same effect as below
  @subscribe(() => window, "update") #b() {} // same effect as above
  @subscribe(Promise.resolve(window), "update") #c() {} // same effect as above
}

import { define, subscribe } from "@sirpepe/ornament";
import { signal } from "@preact/signals-core";

const counter = signal(0);
@define("my-test")
class Test extends HTMLElement {
  @subscribe(counter)
  test() {
    console.log(counter.value);
  }
}
const instance = new Test();
counter.value = 1;
counter.value = 2;
counter.value = 3;
// logs 0, 1, 2, 3

12345678910111213141516

import { define, subscribe } from "@sirpepe/ornament";
import { signal } from "@preact/signals-core";

const counter = signal(0);
@define("my-test")
class Test extends HTMLElement {
  @subscribe(counter)
  test() {
    console.log(counter.value);
  }
}
const instance = new Test();
counter.value = 1;
counter.value = 2;
counter.value = 3;
// logs 0, 1, 2, 3

type Signal<T> = {
  // Takes an update callback and returns an unsubscribe function
  subscribe(callback: () => void): () => void;
  // Represents the current value
  value: T;
};

123456

type Signal<T> = {
  // Takes an update callback and returns an unsubscribe function
  subscribe(callback: () => void): () => void;
  // Represents the current value
  value: T;
};

import { define, debounce } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Debounce a class method
  @debounce()
  test1(x) {
    console.log(x);
  }
  // Debounce a class field function
  @debounce() test2 = (x) => console.log(x);
}

const el = new Test();

el.test1(1);
el.test1(2);
el.test1(3);
// only logs "3"

el.test2("a");
el.test2("b");
el.test2("c");
// only logs "c"

123456789101112131415161718192021222324

import { define, debounce } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Debounce a class method
  @debounce()
  test1(x) {
    console.log(x);
  }
  // Debounce a class field function
  @debounce() test2 = (x) => console.log(x);
}

const el = new Test();

el.test1(1);
el.test1(2);
el.test1(3);
// only logs "3"

el.test2("a");
el.test2("b");
el.test2("c");
// only logs "c"

import { define, observe } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Pass the observer constructor and relevant options
  @observe(MutationObserver, { childList: true })
  reactToChanges(mutations, observer) {
    // "mutations" = array of MutationRecord objects
    // "observer" = the observer instance
    console.log(mutations);
  }
}

const el = new Test();
el.innerText = "Test"; // cause mutation

// Test.reactToChanges() gets called asynchronously by the observer

1234567891011121314151617

import { define, observe } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Pass the observer constructor and relevant options
  @observe(MutationObserver, { childList: true })
  reactToChanges(mutations, observer) {
    // "mutations" = array of MutationRecord objects
    // "observer" = the observer instance
    console.log(mutations);
  }
}

const el = new Test();
el.innerText = "Test"; // cause mutation

// Test.reactToChanges() gets called asynchronously by the observer

export type Transformer<
    extends HTMLElement,
  Value,
  IntermediateValue = Value,
> = {
  // Validates and/or transforms a value before it is used to initialize the
  // accessor. Can also be used to run a side effect when the accessor
  // initializes. Defaults to the identity function.
  init: (
    this: T,
    value: Value,
    context: ClassAccessorDecoratorContext<T, Value>,
    isContentAttribute: boolean,
  ) => Value;
  // Turns content attribute values into DOM property values. Must never throw
  // exceptions, and instead always just deal with its input. Must not cause any
  // observable side effects. May return NO_VALUE in case the content attribute
  // can't be parsed, in which case the @attr() decorator must not change the
  // property value
  parse: (this: T, value: string | null) => Value | typeof NO_VALUE;
  // Decides if setter inputs, which may be of absolutely any type, should be
  // accepted or rejected. Should throw for invalid values, just like setters on
  // built-in elements may. Must not cause any observable side effects.
  validate: (
    this: T,
    value: unknown,
    isContentAttribute: boolean,
  ) => asserts value is IntermediateValue;
  // Transforms values that were accepted by validate() into the proper type by
  // eg. clamping numbers, normalizing strings etc.
  transform: (this: T, value: IntermediateValue) => Value;
  // Turns DOM property values into content attribute values (strings), thereby
  // controlling the attribute representation of an accessor together with
  // updateContentAttr(). Must never throw, defaults to the String() function
  stringify: (this: T, value: Value) => string;
  // Determines whether a new attribute value is equal to the old value. If this
  // method returns true, reactive callbacks will not be triggered. Defaults to
  // simple strict equality (===).
  eql: (this: T, a: Value, b: Value) => boolean;
  // Optionally run a side effect immediately before the accessor's setter is
  // invoked. Required by the event transformer.
  beforeSet: (
    this: T,
    value: Value,
    context: ClassAccessorDecoratorContext<T, Value>,
    attributeRemoved: boolean,
  ) => void;
  // Optionally transform the getter's response. Required by the href
  // transformer.
  transformGet: (this: T, value: Value) => Value;
  // Decides if, based on a new value, an attribute gets updated to match the
  // new value (true/false) or removed (null). Only gets called when the
  // transformer's eql() method returns false. Defaults to a function that
  // always returns true.
  updateContentAttr: (
    oldValue: Value | null,
    newValue: Value | null,
  ) => boolean | null;
};

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859

export type Transformer<
    extends HTMLElement,
  Value,
  IntermediateValue = Value,
> = {
  // Validates and/or transforms a value before it is used to initialize the
  // accessor. Can also be used to run a side effect when the accessor
  // initializes. Defaults to the identity function.
  init: (
    this: T,
    value: Value,
    context: ClassAccessorDecoratorContext<T, Value>,
    isContentAttribute: boolean,
  ) => Value;
  // Turns content attribute values into DOM property values. Must never throw
  // exceptions, and instead always just deal with its input. Must not cause any
  // observable side effects. May return NO_VALUE in case the content attribute
  // can't be parsed, in which case the @attr() decorator must not change the
  // property value
  parse: (this: T, value: string | null) => Value | typeof NO_VALUE;
  // Decides if setter inputs, which may be of absolutely any type, should be
  // accepted or rejected. Should throw for invalid values, just like setters on
  // built-in elements may. Must not cause any observable side effects.
  validate: (
    this: T,
    value: unknown,
    isContentAttribute: boolean,
  ) => asserts value is IntermediateValue;
  // Transforms values that were accepted by validate() into the proper type by
  // eg. clamping numbers, normalizing strings etc.
  transform: (this: T, value: IntermediateValue) => Value;
  // Turns DOM property values into content attribute values (strings), thereby
  // controlling the attribute representation of an accessor together with
  // updateContentAttr(). Must never throw, defaults to the String() function
  stringify: (this: T, value: Value) => string;
  // Determines whether a new attribute value is equal to the old value. If this
  // method returns true, reactive callbacks will not be triggered. Defaults to
  // simple strict equality (===).
  eql: (this: T, a: Value, b: Value) => boolean;
  // Optionally run a side effect immediately before the accessor's setter is
  // invoked. Required by the event transformer.
  beforeSet: (
    this: T,
    value: Value,
    context: ClassAccessorDecoratorContext<T, Value>,
    attributeRemoved: boolean,
  ) => void;
  // Optionally transform the getter's response. Required by the href
  // transformer.
  transformGet: (this: T, value: Value) => Value;
  // Decides if, based on a new value, an attribute gets updated to match the
  // new value (true/false) or removed (null). Only gets called when the
  // transformer's eql() method returns false. Defaults to a function that
  // always returns true.
  updateContentAttr: (
    oldValue: Value | null,
    newValue: Value | null,
  ) => boolean | null;
};

import { define, attr, string } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(string()) accessor foo = "default value";
  @attr(string()) accessor bar = "default value";
  @attr(string()) accessor baz;
}

document.body.innerHTML += `<my-test foo="other value"></my-test>`;

12345678910

import { define, attr, string } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(string()) accessor foo = "default value";
  @attr(string()) accessor bar = "default value";
  @attr(string()) accessor baz;
}

document.body.innerHTML += `<my-test foo="other value"></my-test>`;

import { define, attr, string } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(string()) accessor foo = "default value";
}

123456

import { define, attr, string } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(string()) accessor foo = "default value";
}

import { define, attr, href } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(href()) accessor foo = "";
}

let testEl = new Test();

// Assuming that the page is served from localhost:
console.log(testEl.foo); // > ""
testEl.foo = "asdf";
console.log(testEl.foo); // > "http://localhost/asdf"
testEl.foo = "https://example.com/foo/bar/";
console.log(testEl.foo); // > "https://example.com/foo/bar/"

123456789101112131415

import { define, attr, href } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(href()) accessor foo = "";
}

let testEl = new Test();

// Assuming that the page is served from localhost:
console.log(testEl.foo); // > ""
testEl.foo = "asdf";
console.log(testEl.foo); // > "http://localhost/asdf"
testEl.foo = "https://example.com/foo/bar/";
console.log(testEl.foo); // > "https://example.com/foo/bar/"

import { define, attr, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // With default options (see below)
  @attr(number()) accessor foo = 0;

  // With all options set
  @attr(number({ min: 0, max: 10 })) accessor bar = 0;
}

12345678910

import { define, attr, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // With default options (see below)
  @attr(number()) accessor foo = 0;

  // With all options set
  @attr(number({ min: 0, max: 10 })) accessor bar = 0;
}

import { define, attr, int } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // With default options (see below)
  @attr(int()) accessor foo = 0n;

  // With all options set
  @attr(int({ min: 0n, max: 10n, nullable: false })) accessor bar = 0n;
}

12345678910

import { define, attr, int } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // With default options (see below)
  @attr(int()) accessor foo = 0n;

  // With all options set
  @attr(int({ min: 0n, max: 10n, nullable: false })) accessor bar = 0n;
}

import { define, attr, bool } from "@sirpepe/ornament";

class DemoElement extends HTMLElement {
  @attr(bool()) accessor foo = false;
}

12345

import { define, attr, bool } from "@sirpepe/ornament";

class DemoElement extends HTMLElement {
  @attr(bool()) accessor foo = false;
}

import { define, attr, list, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(list({ transform: number(), separator: "," })) accessor numbers = [0];
}

123456

import { define, attr, list, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(list({ transform: number(), separator: "," })) accessor numbers = [0];
}

import { define, attr, list, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(list({ transform: number() })) accessor foo = [0];
}
const el = new Test();
el.setAttribute("foo", "   1, , ,,2   ,3     ");
console.log(el.foo); // > [1, 2, 3]

123456789

import { define, attr, list, number } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(list({ transform: number() })) accessor foo = [0];
}
const el = new Test();
el.setAttribute("foo", "   1, , ,,2   ,3     ");
console.log(el.foo); // > [1, 2, 3]

import { define, attr, literal, string } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(literal({ values: ["A", "B"], transform: string() })) accessor foo =
    "A";
}

1234567

import { define, attr, literal, string } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(literal({ values: ["A", "B"], transform: string() })) accessor foo =
    "A";
}

import { define, attr, prop, json } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Must be valid JSON when used with @attr()
  @attr(json()) accessor foo = { user: "", email: "" };
  // When used with prop, any value can be used
  @prop(json()) accessor foo = { value: 42n };
}

123456789

import { define, attr, prop, json } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Must be valid JSON when used with @attr()
  @attr(json()) accessor foo = { user: "", email: "" };
  // When used with prop, any value can be used
  @prop(json()) accessor foo = { value: 42n };
}

import { define, prop, any } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @prop(any()) accessor whatever: any = 42;
}

123456

import { define, prop, any } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @prop(any()) accessor whatever: any = 42;
}

import { define, attr, eventHandler } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(event()) accessor onfoo: ((evt: Event) => void) | null = null;
}

123456

import { define, attr, eventHandler } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(event()) accessor onfoo: ((evt: Event) => void) | null = null;
}

<my-test onfoo="console.log('Foo event:', event)"></my-test>
<script>
  document.querySelector("my-test").dispatchEvent(new Event("foo"));
  // Logs "'Foo event:', Event{type: "foo"}"
</script>

12345

<my-test onfoo="console.log('Foo event:', event)"></my-test>
<script>
  document.querySelector("my-test").dispatchEvent(new Event("foo"));
  // Logs "'Foo event:', Event{type: "foo"}"
</script>

const testEl = document.createElement("my-test");
testEl.onfoo = (event) => console.log("Foo event:", event);
testEl.dispatchEvent(new Event("foo"));
// Logs "'Foo event:', Event{type: "foo"}"

1234

const testEl = document.createElement("my-test");
testEl.onfoo = (event) => console.log("Foo event:", event);
testEl.dispatchEvent(new Event("foo"));
// Logs "'Foo event:', Event{type: "foo"}"

import { define, getTagName } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {}

console.log(getTagName(Test));
// > "my-test"

console.log(getTagName(new Test()));
// > "my-test"

12345678910

import { define, getTagName } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {}

console.log(getTagName(Test));
// > "my-test"

console.log(getTagName(new Test()));
// > "my-test"

import { define, attr, string, listAttributes } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(string()) accessor foo = "";
  @attr(string(), { as: "asdf" }) accessor bar = "";
}

console.log(listAttributes(Test));
// > ["foo", "asdf"]

console.log(listAttributes(new Test()));
// > ["foo", "asdf"]

12345678910111213

import { define, attr, string, listAttributes } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @attr(string()) accessor foo = "";
  @attr(string(), { as: "asdf" }) accessor bar = "";
}

console.log(listAttributes(Test));
// > ["foo", "asdf"]

console.log(listAttributes(new Test()));
// > ["foo", "asdf"]

import { define, attr, number, getAttribute } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Requires non-negative values
  @attr(number({ min: 0 }), { as: "asdf" }) accessor bar = 0;
}

const { prop, transformer } = getAttribute(Test, "asdf");

console.log(prop);
// > "bar" - the backend accessor for the content attribute "asdf"

transformer.parse("-1");
// > 0; input clamped to valid value

transformer.validate(-1, true);
// Throws an error; the transformer only accepts nonnegative numbers

123456789101112131415161718

import { define, attr, number, getAttribute } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Requires non-negative values
  @attr(number({ min: 0 }), { as: "asdf" }) accessor bar = 0;
}

const { prop, transformer } = getAttribute(Test, "asdf");

console.log(prop);
// > "bar" - the backend accessor for the content attribute "asdf"

transformer.parse("-1");
// > 0; input clamped to valid value

transformer.validate(-1, true);
// Throws an error; the transformer only accepts nonnegative numbers

import { trigger } from "@sirpepe/ornament";

// Dispatches an "connected" event. This will run all methods on "someElement"
// that were decorated with @connect().
trigger(someElement, "connected"); // note no args

// Dispatches an "prop" event. This will run all methods on "someElement"
// that were decorated with @reactive(), provided the "foo" key is not excluded
// in the setup of the @reactive decorator
trigger(someElement, "prop", "foo", 42); // note args for prop name and value

12345678910

import { trigger } from "@sirpepe/ornament";

// Dispatches an "connected" event. This will run all methods on "someElement"
// that were decorated with @connect().
trigger(someElement, "connected"); // note no args

// Dispatches an "prop" event. This will run all methods on "someElement"
// that were decorated with @reactive(), provided the "foo" key is not excluded
// in the setup of the @reactive decorator
trigger(someElement, "prop", "foo", 42); // note args for prop name and value

import { listen } from "@sirpepe/ornament";

// Listen for "prop" event on the event bus for "someElement"
listen(someElement, "prop", (evt) => {
  const [name, value] = event.args;
  window.alert(`Attribute ${name} was changed to ${value}!`);
});

1234567

import { listen } from "@sirpepe/ornament";

// Listen for "prop" event on the event bus for "someElement"
listen(someElement, "prop", (evt) => {
  const [name, value] = event.args;
  window.alert(`Attribute ${name} was changed to ${value}!`);
});

import { define, getInternals } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {}
const testEl = new Test();

const internals1 = getInternals(testEl);
const internals2 = testEl.attachInternals();
console.log(internals1 === internals2); // > true

getInternals(testEl); // works a second time
getInternals(testEl); // works a third time
testEl.attachInternals()) to.throw(); // > Exception on second use

12345678910111213

import { define, getInternals } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {}
const testEl = new Test();

const internals1 = getInternals(testEl);
const internals2 = testEl.attachInternals();
console.log(internals1 === internals2); // > true

getInternals(testEl); // works a second time
getInternals(testEl); // works a third time
testEl.attachInternals()) to.throw(); // > Exception on second use

import { define, init } from "@sirpepe/ornament";

function otherDecorator(target) {
  return class OtherMixin extends target {
    #secret = 42;
    get foo() {
      return this.#secret; // <- Fails because @init() runs too early
    }
  };
}

@otherDecorator
@define("foo-bar") // If this was before @otherDecorator it would work
class Test extends HTMLElement {
  @init() // Runs after the constructor of Test has run, does not wait for the mixin class
  method() {
    console.log(this.foo);
  }
}

new Test();

123456789101112131415161718192021

import { define, init } from "@sirpepe/ornament";

function otherDecorator(target) {
  return class OtherMixin extends target {
    #secret = 42;
    get foo() {
      return this.#secret; // <- Fails because @init() runs too early
    }
  };
}

@otherDecorator
@define("foo-bar") // If this was before @otherDecorator it would work
class Test extends HTMLElement {
  @init() // Runs after the constructor of Test has run, does not wait for the mixin class
  method() {
    console.log(this.foo);
  }
}

new Test();

OtherMixinConstructor(
  DefineMixinConstructor(
    TestConstructor(
      HTMLElementConstructor()
    )
    // <---- init event happens here, after TestConstructor has run
  )
  // <---- finishes only after the init event has happened
)

123456789

OtherMixinConstructor(
  DefineMixinConstructor(
    TestConstructor(
      HTMLElementConstructor()
    )
    // <---- init event happens here, after TestConstructor has run
  )
  // <---- finishes only after the init event has happened
)

function decorator(target) {
  return class DecoratorMixin extends target {
    #secret = 42;
    get feature() {
      return this.#secret;
    }
  };
}

@decorator
class A {
  constructor() {
    console.log(this.feature);
  }
}

new A();

1234567891011121314151617

function decorator(target) {
  return class DecoratorMixin extends target {
    #secret = 42;
    get feature() {
      return this.#secret;
    }
  };
}

@decorator
class A {
  constructor() {
    console.log(this.feature);
  }
}

new A();

import { define, prop, reactive,          int } from "@sirpepe/ornament";

@define("my-test")
export class TestElement extends HTMLElement {
  @prop(int()) accessor value = 0;

  @reactive()
  @debounce()
  #log() {
    console.log("Value is now", this.value);
  }
}

let el = new TestElement();
el.value = 1;
el.value = 2;
el.value = 2;

// Only logs "Value is now 3"

12345678910111213141516171819

import { define, prop, reactive,          int } from "@sirpepe/ornament";

@define("my-test")
export class TestElement extends HTMLElement {
  @prop(int()) accessor value = 0;

  @reactive()
  @debounce()
  #log() {
    console.log("Value is now", this.value);
  }
}

let el = new TestElement();
el.value = 1;
el.value = 2;
el.value = 2;

// Only logs "Value is now 3"

import { render, html } from "uhtml";
import { define, prop, reactive,          int } from "@sirpepe/ornament";

@define("counter-element")
export class CounterElement extends HTMLElement {
  @prop(int()) accessor value = 0;

  @reactive()
  @debounce()
  #render() {
    render(
      this.shadowRoot ?? this.attachShadow({ mode: "open" }),
      html`
        Current value: ${this.value}
        <button .click={() => ++this.value}>Add 1</button>
      `
    );
  }
}

12345678910111213141516171819

import { render, html } from "uhtml";
import { define, prop, reactive,          int } from "@sirpepe/ornament";

@define("counter-element")
export class CounterElement extends HTMLElement {
  @prop(int()) accessor value = 0;

  @reactive()
  @debounce()
  #render() {
    render(
      this.shadowRoot ?? this.attachShadow({ mode: "open" }),
      html`
        Current value: ${this.value}
        <button .click={() => ++this.value}>Add 1</button>
      `
    );
  }
}

import { define, attr, number, reactive, connected } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

@define("click-counter")
class ClickCounter extends HTMLElement {
  #shadow = this.attachShadow({ mode: "closed" });

  @attr(number({ min: 0 }), { reflective: false }) accessor up = 0;
  @attr(number({ min: 0 }), { reflective: false }) accessor down = 0;

  @connected()
  @reactive()
  render() {
    render(
      <>
        <button onClick={() => this.up++}>+1</button>
        Total: <b>{this.up + this.down}</b>
        <button onClick={() => this.down--}>-1</button>
      </>,
      this.#shadow,
    );
  }
}

1234567891011121314151617181920212223

import { define, attr, number, reactive, connected } from "@sirpepe/ornament";
import { Fragment, h, render } from "preact";

@define("click-counter")
class ClickCounter extends HTMLElement {
  #shadow = this.attachShadow({ mode: "closed" });

  @attr(number({ min: 0 }), { reflective: false }) accessor up = 0;
  @attr(number({ min: 0 }), { reflective: false }) accessor down = 0;

  @connected()
  @reactive()
  render() {
    render(
      <>
        <button onClick={() => this.up++}>+1</button>
        Total: <b>{this.up + this.down}</b>
        <button onClick={() => this.down--}>-1</button>
      </>,
      this.#shadow,
    );
  }
}

import { define, attr, reactive, string } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Writable, but private
  @prop(string()) accessor #foo = "Starting value";

  // Provides public readonly access to #foo
  get foo() {
    return this.#foo;
  }

  change() {
    this.#foo++;
  }

  // Reacts to changes to #foo, which can only be caused by calling the method
  // `change()`
  @reactive()
  log() {
    console.log(this.#foo);
  }
}

1234567891011121314151617181920212223

import { define, attr, reactive, string } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  // Writable, but private
  @prop(string()) accessor #foo = "Starting value";

  // Provides public readonly access to #foo
  get foo() {
    return this.#foo;
  }

  change() {
    this.#foo++;
  }

  // Reacts to changes to #foo, which can only be caused by calling the method
  // `change()`
  @reactive()
  log() {
    console.log(this.#foo);
  }
}

@define("my-test")
class Test extends HTMLElement {
  // Implements a content attribute "foo" with getters and setters at #secret
  @attr(string(), { as: "foo" }) accessor #secret = "A";

  // To provide public a public DOM API, we just write a getter/setter pair with
  // names matching the content attribute
  get foo() {
    console.log("Custom getter logic!");
    return this.#secret; // accesses the getter decorated with @attr()
  }

  set foo(value) {
    console.log("Custom seter logic!");
    this.#secret = value; // accesses the setter decorated with @attr()
  }
}

1234567891011121314151617

@define("my-test")
class Test extends HTMLElement {
  // Implements a content attribute "foo" with getters and setters at #secret
  @attr(string(), { as: "foo" }) accessor #secret = "A";

  // To provide public a public DOM API, we just write a getter/setter pair with
  // names matching the content attribute
  get foo() {
    console.log("Custom getter logic!");
    return this.#secret; // accesses the getter decorated with @attr()
  }

  set foo(value) {
    console.log("Custom seter logic!");
    this.#secret = value; // accesses the setter decorated with @attr()
  }
}

import { define, subscribe } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @subscribe(document.documentElement, "input", {
    predicate: (evt) => evt.target.matches("input[type-number]"),
  })
  log(evt) {
    console.log(evt); // "input" events
  }
}

1234567891011

import { define, subscribe } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  @subscribe(document.documentElement, "input", {
    predicate: (evt) => evt.target.matches("input[type-number]"),
  })
  log(evt) {
    console.log(evt); // "input" events
  }
}

import { define, subscribe } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  root = this.attachShadow({ mode: "open" });
  @subscribe((instance) => this.root, "input", {
    predicate: (evt) => evt.target.matches("input[type-number]"),
  })
  log(evt) {
    console.log(evt); // "input" events
  }
}

123456789101112

import { define, subscribe } from "@sirpepe/ornament";

@define("my-test")
class Test extends HTMLElement {
  root = this.attachShadow({ mode: "open" });
  @subscribe((instance) => this.root, "input", {
    predicate: (evt) => evt.target.matches("input[type-number]"),
  })
  log(evt) {
    console.log(evt); // "input" events
  }
}

import { define, subscribe } from "@sirpepe/ornament";

const handle = (eventName, selector) =>
  subscribe((instance) => this.root, eventName, {
    predicate: (evt) => evt.target.matches(selector),
  });

@define("my-test")
class Test extends HTMLElement {
  root = this.attachShadow({ mode: "open" });

  @handle("input", "input[type-number]") // Much better!
  log(evt) {
    console.log(evt); // "input" events
  }
}

12345678910111213141516

import { define, subscribe } from "@sirpepe/ornament";

const handle = (eventName, selector) =>
  subscribe((instance) => this.root, eventName, {
    predicate: (evt) => evt.target.matches(selector),
  });

@define("my-test")
class Test extends HTMLElement {
  root = this.attachShadow({ mode: "open" });

  @handle("input", "input[type-number]") // Much better!
  log(evt) {
    console.log(evt); // "input" events
  }
}

import { define, subscribe } from "@sirpepe/ornament";

// This can now handle all events from the shadow root
const capture = (eventName, selector) =>
  subscribe((instance) => this.root, eventName, {
    predicate: (evt) => evt.target.matches(selector),
    capture: true,
  });

12345678

import { define, subscribe } from "@sirpepe/ornament";

// This can now handle all events from the shadow root
const capture = (eventName, selector) =>
  subscribe((instance) => this.root, eventName, {
    predicate: (evt) => evt.target.matches(selector),
    capture: true,
  });

import {
  define,
  attr,
  reactive as baseReactive,
  string,
} from "@sirpepe/ornament";

// @reactive with "keys" always set to ["foo"]
const reactive = (options) => baseReactive({ ...options, keys: ["foo"] });

@define("my-test")
class Test extends HTMLElement {
  @prop(string()) accessor foo = "A"; // included in options.keys
  @prop(string()) accessor bar = "A"; // excluded from options.keys

  @reactive()
  log() {
    console.log("Hello");
  }
}

let test = new Test();
test.foo = "B"; //  logs "Hello"
test.bar = "B"; //  does not log anything

123456789101112131415161718192021222324

import {
  define,
  attr,
  reactive as baseReactive,
  string,
} from "@sirpepe/ornament";

// @reactive with "keys" always set to ["foo"]
const reactive = (options) => baseReactive({ ...options, keys: ["foo"] });

@define("my-test")
class Test extends HTMLElement {
  @prop(string()) accessor foo = "A"; // included in options.keys
  @prop(string()) accessor bar = "A"; // excluded from options.keys

  @reactive()
  log() {
    console.log("Hello");
  }
}

let test = new Test();
test.foo = "B"; //  logs "Hello"
test.bar = "B"; //  does not log anything

import { define, subscribe } from "@sirpepe/ornament";

// A more convenient decorator for event delegation
function listen(event, selector = "*") {
  return subscribe(document.documentElement, "input", (evt) =>
    evt.target.matches(selector),
  );
}

@define("my-test")
class Test extends HTMLElement {
  @listen("input", "input[type-number]")
  log(evt) {
    console.log(evt);
  }
}

12345678910111213141516

import { define, subscribe } from "@sirpepe/ornament";

// A more convenient decorator for event delegation
function listen(event, selector = "*") {
  return subscribe(document.documentElement, "input", (evt) =>
    evt.target.matches(selector),
  );
}

@define("my-test")
class Test extends HTMLElement {
  @listen("input", "input[type-number]")
  log(evt) {
    console.log(evt);
  }
}

import { define, attr, number } from "@sirpepe/ornament";

function nonnegativeNumber(otherOptions) {
  return number({ ...otherOptions, min: 0 });
}

@define("my-test")
class Test extends HTMLElement {
  @attr(nonnegativeNumber({ max: 1337 }))
  accessor foo = 42;
}

1234567891011

import { define, attr, number } from "@sirpepe/ornament";

function nonnegativeNumber(otherOptions) {
  return number({ ...otherOptions, min: 0 });
}

@define("my-test")
class Test extends HTMLElement {
  @attr(nonnegativeNumber({ max: 1337 }))
  accessor foo = 42;
}

import { reactive as baseReactive, connected } from "@sirpepe/ornament";

// Combines @reactive() and @connected() into one handy decorator that runs
// methods when components connect AND when their attributes change
function reactive() {
  return function (target, context) {
    return baseReactive()(connected()(target, context), context);
  };
}

123456789

import { reactive as baseReactive, connected } from "@sirpepe/ornament";

// Combines @reactive() and @connected() into one handy decorator that runs
// methods when components connect AND when their attributes change
function reactive() {
  return function (target, context) {
    return baseReactive()(connected()(target, context), context);
  };
}

import {
  reactive as baseReactive,
  connected,
  debounce,
} from "@sirpepe/ornament";

// Combines @reactive(), @connected() and @debounce():
// - reacts to attribute updates (only while the component is connected)
// - and runs its target method at most once per frame
// - and also when the component connects
const reactive = () => (target, context) =>
  baseReactive({ predicate: ({ isConnected }) => isConnected })(
    connected()(debounce({ fn: debounce.raf() })(target, context), context),
    context,
  );

123456789101112131415

import {
  reactive as baseReactive,
  connected,
  debounce,
} from "@sirpepe/ornament";

// Combines @reactive(), @connected() and @debounce():
// - reacts to attribute updates (only while the component is connected)
// - and runs its target method at most once per frame
// - and also when the component connects
const reactive = () => (target, context) =>
  baseReactive({ predicate: ({ isConnected }) => isConnected })(
    connected()(debounce({ fn: debounce.raf() })(target, context), context),
    context,
  );

import { define, attr, string } from "@sirpepe/ornament";

// The built-in string transformer always represents strings, but we want to
// allow `null` in this case
let nullableString = {
  ...string(),
  validate(value) {
    if (value === null || typeof value === "undefined") {
      return value;
    }
    return String(value);
  },
};

@define("my-test")
class Test extends HTMLElement {
  @attr(nullableString())
  accessor foo = "Hello";
}