mates-raw

Standalone mount-once class components on lit-html 3.2.1.

This is the fast path behind mates xRaw / renderRaw. Use it on its own when you want a tiny class → DOM library — vanilla, React islands, or any other host that owns a DOM node. Use it from mates when you already have the full framework ($, atoms, x(), router): mates re-exports the same API and skips setup() during SSR.

Not in this package: $(), atoms, x(), the render scheduler, or component hooks. Patch the DOM yourself in setup().

Install

npm install mates-raw

Runtime dependency: [email protected] (same pin as mates).

Published builds emit dist/ via npm run build. In this repo the package exports TypeScript source so Vite apps that alias mates to lib/ resolve mates-raw without a pre-build.

Vanilla

import { html, ref, setRef, xRaw, render } from "mates-raw";

class Counter {
  declare props: { label?: string };
  button = ref<HTMLButtonElement>();
  n = 0;

  html = html`
    <button ${setRef(this.button)}>
      ${this.props.label ?? "count"} is 0
    </button>
  `;

  setup() {
    this.button.value!.onclick = () => {
      this.n++;
      this.button.value!.textContent =
        `${this.props.label ?? "count"} is ${this.n}`;
    };
  }

  destroy() {
    if (this.button.value) this.button.value.onclick = null;
  }
}

render(html`${xRaw(Counter, { label: "count" })}`, document.getElementById("app")!);

Root mount without a parent template:

import { renderRaw, unmountRaw } from "mates-raw";

renderRaw(Counter, document.getElementById("app")!, { label: "count" });
unmountRaw(document.getElementById("app")!);

With mates

If you already use mates, import from mates — same classes, plus $ / atoms / renderApp:

import { html, ref, setRef, $, xRaw, renderApp } from "mates";

Mates wraps this package and passes { skipSetup: true } during an SSR render pass.

React (optional)

React is a peer, not a hard dependency. Mount a Raw island into a node React owns. Later React prop changes do not remount the island (same mount-once contract as xRaw).

import { useRaw } from "mates-raw/react";

function Widget() {
  const host = useRaw(Counter, { label: "count" });
  return <div ref={host} />;
}

Or <RawView as={Counter} label="count" />.

Contract

| Rule | Detail | |------|--------| | One-shot html | Committed once. Parent re-renders with new props are ignored. | | setup() | Microtask after DOM commit — refs are ready. | | destroy() | Disconnect only. No auto-off of listeners. | | declare props: P | Type-only field, before html. Native props; / props!: fields hide the mount snapshot. | | Refs | Declare ref() fields above html so setRef(this.*) sees them. | | Lists | Do not put an xRaw island on every row of a 100k table — clone DOM instead. |

API

xRaw(Class, props?, options?: { skipSetup?: boolean })
renderRaw(Class, el, props?, options?)
unmountRaw(el)
ref() / setRef(ref)
html / render / nothing / noChange   // re-exported from lit-html