@tmbr/component 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# Component
+
+A base class for enhancing DOM elements with reactive state, similar to [Alpine.js](https://alpinejs.dev/) and [petite-vue](https://github.com/vuejs/petite-vue), but without loops and conditionals.
+
+```bash
+npm install @tmbr/component
+```
+
+## Simple
+
+Define state inline with a `data-state` attribute.
+
+```html
+<div data-state="{count: 0}">
+  <button type="button" @click="count--">Remove</button>
+  <span :text="count"></span>
+  <button type="button" @click="count++">Add</button>
+</div>
+```
+```js
+document.querySelectorAll('[data-state]').forEach(el => {
+  new Component(el);
+});
+```
+
+## Extended
+
+Subclass `Component` to define reusable components with DOM refs, methods, and lifecycle hooks.
+
+```html
+<div id="counter">
+  <button type="button" @click="dec" :disabled="count <= 0">Remove</button>
+  <span :text="count"></span>
+  <button type="button" @click="inc">Add</button>
+  <span :show="count >= 10">Count is dangerously high</span>
+</div>
+```
+```js
+class Counter extends Component {
+
+  static state = {
+    count: 0
+  };
+
+  init() {
+    console.log('mounted', this.el);
+  }
+
+  inc() {
+    this.state.count++;
+  }
+
+  dec() {
+    this.state.count--;
+  }
+
+  update(state) {
+    console.log('updated', state.count);
+  }
+}
+
+new Counter('#counter');
+```
+
+## Directives
+
+Directives are expressions evaluated with the current state.
+
+| Directive                    | Effect                                                        |
+| -----------------------------| --------------------------------------------------------------|
+| `:text`                      | sets `textContent`                                            |
+| `:html`                      | sets `innerHTML`                                              |
+| `:show`                      | toggles `display: none`                                       |
+| `:value`                     | sets `.value` on inputs (one-way)                             |
+| `:model`                     | two-way binding for form elements                             |
+| `:class`                     | merges classes from a string, array, or `{name: bool}` object |
+| `:disabled`, `:hidden`, etc. | boolean attributes — set when truthy, removed when falsy      |
+| `:attribute`                 | `setAttribute` fallback for any other attribute               |
+
+## Events
+
+Events are attached with `@event.modifier="handler"` where handler is an expression or component method.
+
+| Modifier    | Effect                                                |
+| ----------- | ----------------------------------------------------- |
+| `.prevent`  | calls `preventDefault()`                              |
+| `.stop`     | calls `stopPropagation()`                             |
+| `.self`     | only fires when `event.target` is the current element |
+| `.once`     | auto-removes after first invocation                   |
+| `.passive`  | passive event listener                                |
+| `.capture`  | capture phase listener                                |
+| `.outside`  | fires on events outside the element                   |
+| `.window`   | listens to `window`                                   |
+| `.document` | listens to `document`                                 |
+
+## Refs
+
+Elements with a `ref` attribute are collected into `this.dom`. Multiple elements with the same name are grouped into an array. Use bracket syntax `ref="[items]"` to force an array even with a single element.
+
+```html
+<div>
+  <input ref="input" />
+  <ul>
+    <li ref="[items]">one</li>
+    <li ref="[items]">two</li>
+  </ul>
+</div>
+```
+
+## Computed
+
+Getters on the subclass expose derived values that are accessible in template expressions and the `update()` hook.
+
+```js
+class Example extends Component {
+
+  static state = {
+    name: 'Jane Doe'
+  };
+
+  get firstName() {
+    return this.state.name.split(' ')[0];
+  }
+}
+```
+
+```html
+<input type="text" :model="name" />
+First name is <span :text="firstName"></span>
+```
+
+```js
+this.dom.input // input
+this.dom.items // [li, li]
+```
+
+## Instance API
+
+| Property or Method                 | Description                                         |
+| ---------------------------------- | --------------------------------------------------- |
+| `.el`                              | root element                                        |
+| `.dom`                             | child elements collected from `ref` attributes      |
+| `.props`                           | parsed from `data-props` attribute                  |
+| `.state`                           | reactive proxy where changes trigger a rerender     |
+| `.findOne(selector)`               | scoped `querySelector`                              |
+| `.findAll(selector)`               | scoped `querySelectorAll`                           |
+| `.init()`                          | called after constructor — override in subclass     |
+| `.update(state)`                   | called after each render — override in subclass     |
+| `.on(event, target, fn)`           | delegate event listener, cleaned up on `.destroy()` |
+| `.dispatch(type, detail, options)` | dispatches a `CustomEvent` from `.el`               |
+| `.destroy()`                       | removes all listeners and directives                |

package/bind.js

@@ -0,0 +1,125 @@
+import { cx, isFunction } from '@tmbr/utils';
+
+const BOOLEANS = new Set([
+  'allowfullscreen',
+  'async',
+  'autofocus',
+  'autoplay',
+  'checked',
+  'controls',
+  'default',
+  'defer',
+  'disabled',
+  'formnovalidate',
+  'hidden',
+  'ismap',
+  'itemscope',
+  'loop',
+  'multiple',
+  'muted',
+  'nomodule',
+  'novalidate',
+  'open',
+  'playsinline',
+  'readonly',
+  'required',
+  'reversed',
+  'selected'
+]);
+
+export function bindDirective(component, node, attr, expression) {
+
+  const fn = new Function('state', `
+    try {
+      var result;
+      with (state) { result = ${expression} };
+      return result;
+    } catch(e) {
+      console.warn('[Component]', e);
+    }`);
+
+  let apply;
+
+  if (attr === 'model') {
+
+    const isCheckbox = node.type === 'checkbox';
+    const isRadio = node.type === 'radio';
+    const isNumber = node.type === 'number' || node.type === 'range';
+    const isSelect = node.nodeName === 'SELECT';
+
+    if (isCheckbox) {
+      apply = value => node.checked = !!value;
+    } else if (isRadio) {
+      apply = value => node.checked = node.value === value;
+    } else {
+      apply = value => node.value = value ?? '';
+    }
+
+    component.controller ??= new AbortController();
+    const type = (isCheckbox || isRadio || isSelect) ? 'change' : 'input';
+
+    node.addEventListener(type, event => {
+      const value = isCheckbox ? event.target.checked : event.target.value;
+      component.state[expression] = isNumber ? Number(value) : value;
+    }, {signal: component.controller.signal});
+
+  } else if (attr === 'text') {
+    apply = value => node.textContent = value;
+  } else if (attr === 'html') {
+    apply = value => node.innerHTML = value;
+  } else if (attr === 'value') {
+    apply = value => node.value = value;
+  } else if (attr === 'show') {
+    const display = node.style.display || '';
+    apply = value => node.style.display = value ? display : 'none';
+  } else if (attr === 'class') {
+    const initial = node.className;
+    apply = value => { node.className = initial; cx(node, value); };
+  } else if (BOOLEANS.has(attr)) {
+    apply = value => value ? node.setAttribute(attr, '') : node.removeAttribute(attr);
+  } else {
+    apply = value => node.setAttribute(attr, value);
+  }
+
+  component.directives.push(state => apply(fn(state)));
+}
+
+export function bindEvent(component, node, attr, value) {
+
+  const [name, ...modifiers] = attr.split('.');
+
+  let target = node;
+
+  if (modifiers.includes('window')) {
+    target = window;
+  } else if (modifiers.includes('document') || modifiers.includes('outside')) {
+    target = document;
+  }
+
+  const callback = isFunction(component[value])
+    ? component[value]
+    : new Function('event', 'state', `
+      try {
+        with (state) { ${value} };
+      } catch (e) {
+        console.warn('[Component]', e);
+      }`);
+
+  component.controller ??= new AbortController();
+  const signal = component.controller.signal;
+
+  const options = {signal};
+  if (modifiers.includes('once')) options.once = true;
+  if (modifiers.includes('capture')) options.capture = true;
+  if (modifiers.includes('passive')) options.passive = true;
+
+  function listener(event) {
+    if (modifiers.includes('outside') && node.contains(event.target)) return;
+    if (modifiers.includes('self') && node !== event.target) return;
+    if (modifiers.includes('stop')) event.stopPropagation();
+    if (modifiers.includes('prevent')) event.preventDefault();
+    callback.call(component, event, component.state);
+  }
+
+  target.addEventListener(name, listener, options);
+}

package/index.js

@@ -0,0 +1,135 @@
+import { on, findOne, findAll, isDefined, isString, toJSON, traverse } from '@tmbr/utils';
+import { bindDirective, bindEvent } from './bind.js';
+
+let queue;
+let scheduled = false;
+
+function enqueue(component) {
+  queue ??= new Set();
+  queue.add(component);
+
+  if (scheduled) return;
+  queueMicrotask(flush);
+  scheduled = true;
+}
+
+function flush() {
+  for (const component of queue) render(component);
+  queue.clear();
+  scheduled = false;
+}
+
+function render(component) {
+  const state = component.state;
+  const proto = Object.getPrototypeOf(component);
+
+  const context = proto === Component.prototype ? state : new Proxy(state, {
+    has(target, key) {
+      return Object.getOwnPropertyDescriptor(proto, key)?.get ? true : key in target;
+    },
+    get(target, key, receiver) {
+      const d = Object.getOwnPropertyDescriptor(proto, key);
+      return d?.get ? d.get.call(component) : Reflect.get(target, key, receiver);
+    }
+  });
+
+  for (const apply of component.directives) apply(context);
+  component.update?.(context);
+}
+
+export default class Component {
+
+  static state = {};
+
+  constructor(el) {
+    this.el = isString(el) ? findOne(el) : el;
+
+    if (!this.el) {
+      console.warn(`[Component] ${el} element not found`);
+      return;
+    }
+
+    this.dom = this.findAll('[ref]').reduce((result, child) => {
+
+      let key = child.getAttribute('ref');
+      child.removeAttribute('ref');
+
+      const hasBrackets = key.includes('[');
+      hasBrackets && (key = key.replace(/[\[\]]/g, ''));
+
+      const asArray = hasBrackets || isDefined(result[key]);
+
+      result[key] = asArray ? [].concat(result[key] ?? [], child) : child;
+      return result;
+
+    }, {});
+
+    this.controller = null;
+    this.directives = [];
+
+    const hasProps = this.el.hasAttribute('data-props');
+    this.props = hasProps ? toJSON(this.el.dataset.props) : {};
+
+    const hasState = this.el.hasAttribute('data-state') || this.constructor.state;
+    this.state = hasState ? this.#state() : {};
+
+    this.el.removeAttribute('data-props');
+    this.el.removeAttribute('data-state');
+    this.init?.();
+  }
+
+  #state() {
+
+    traverse(this.el, child => {
+      for (const {name, value} of [...child.attributes]) {
+        if (name.startsWith(':')) {
+          bindDirective(this, child, name.slice(1), value);
+          child.removeAttribute(name);
+        } else if (name.startsWith('@')) {
+          bindEvent(this, child, name.slice(1), value);
+          child.removeAttribute(name);
+        }
+      }
+    });
+
+    const state = this.el.dataset.state
+      ? toJSON(this.el.dataset.state)
+      : structuredClone(this.constructor.state);
+
+    const set = (target, key, value) => {
+      target[key] = value;
+      enqueue(this);
+      return true;
+    };
+
+    enqueue(this);
+    return new Proxy(state, {set});
+  }
+
+  findOne(s) {
+    return findOne(s, this.el);
+  }
+
+  findAll(s) {
+    return findAll(s, this.el);
+  }
+
+  on(event, target, fn) {
+    const off = on(event, target, fn, this.el);
+    this.on.destroy ??= [];
+    this.on.destroy.push(off);
+    return off;
+  }
+
+  dispatch(type, detail, options = {}) {
+    const e = new CustomEvent(type, {detail, ...options});
+    return this.el.dispatchEvent(e);
+  }
+
+  destroy() {
+    this.on.destroy?.forEach(off => off());
+    this.controller?.abort();
+    this.directives.length = 0;
+    queue.delete(this);
+  }
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@tmbr/component",
+  "version": "1.0.0",
+  "repository": "github:nikrowell/tmbr-toolkit",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "bind.js",
+    "index.js"
+  ],
+  "scripts": {
+    "start": "npx esbuild index.js --outdir=. --servedir=. --format=esm --bundle --watch"
+  },
+  "dependencies": {
+    "@tmbr/utils": "^2.13.1"
+  }
+}