micra.js 1.0.0

package/README.md

@@ -0,0 +1,166 @@
+# Micra.js
+
+Micra.js is a lightweight reactive TypeScript framework for small sites and SaaS apps. It gives you reactive state, DOM directives, keyed list rendering, an event bus, SSR-friendly props, and auto-mounting in about 3.7 KB gzip.
+
+## What is Micra.js?
+
+Micra.js is designed for server-rendered apps and small frontends that need a little reactivity without a large framework.
+
+Use it when you want:
+
+- JS expressions in directives like `data-if="count > 0"`
+- keyed list diffing with `data-each` + `data-key`
+- auto-mounting with `data-component`, `Micra.define()`, and `Micra.start()`
+- SSR props from `data-*` attributes via `this.prop()`
+- a built-in `this.fetch()` helper
+- a small global event bus with `Micra.on()` and `Micra.emit()`
+- DOM refs via `data-ref`
+- additive class toggling with `data-class`
+- simple lifecycle hooks: `onCreate`, `onDestroy`
+
+## Quick Start
+
+```html
+<div data-component="counter">
+  <button @click="decrement">-</button>
+  <strong data-text="count"></strong>
+  <button @click="increment">+</button>
+</div>
+
+<script src="https://unpkg.com/micra.js/dist/micra.min.js"></script>
+<script>
+  Micra.define('counter', {
+    state: { count: 0 },
+    increment() { this.state.count++ },
+    decrement() { this.state.count-- },
+  })
+
+  Micra.start()
+</script>
+```
+
+## Installation
+
+### CDN
+
+```html
+<script src="https://unpkg.com/micra.js/dist/micra.min.js"></script>
+```
+
+### npm
+
+```bash
+npm install micra.js
+```
+
+```ts
+import * as Micra from 'micra'
+```
+
+## Basic usage
+
+A counter mounted automatically from `data-component`:
+
+```html
+<div data-component="counter">
+  <p>Count: <span data-text="count"></span></p>
+  <button @click="decrement">-</button>
+  <button @click="increment">+</button>
+  <button @click="reset">Reset</button>
+</div>
+```
+
+```ts
+import * as Micra from 'micra'
+
+Micra.define('counter', {
+  state: { count: 0 },
+
+  increment() {
+    this.state.count++
+  },
+
+  decrement() {
+    this.state.count--
+  },
+
+  reset() {
+    this.state.count = 0
+  },
+})
+
+Micra.start()
+```
+
+## Directives
+
+| Directive | Example | Description |
+|---|---|---|
+| `data-text` | `data-text="name"` | Set `textContent` |
+| `data-html` | `data-html="content"` | Set `innerHTML` |
+| `data-if` | `data-if="count > 0"` | Toggle display |
+| `data-show` | `data-show="loaded"` | Alias of `data-if` |
+| `data-bind` | `data-bind="href:url, disabled:loading"` | Bind attributes |
+| `data-model` | `data-model="search"` | Two-way input binding |
+| `data-each` | `data-each="items" data-key="id"` | List rendering |
+| `data-ref` | `data-ref="chart"` | DOM ref in `this.refs` |
+| `data-class` | `data-class="active:isActive"` | Toggle classes additively |
+| `data-on` | `data-on="click:save"` | Bind DOM events |
+| `@event` | `@click="increment"` | Shorthand event binding |
+
+## API reference summary
+
+### Register
+
+```ts
+Micra.define(name: string, definition: ComponentDefinition): void
+Micra.defineComponent(definition): ComponentDefinition
+```
+
+### Mount
+
+```ts
+Micra.mount(selector: string | HTMLElement, definition): ComponentInstance | null
+Micra.start(root?: Document | HTMLElement): void
+```
+
+### Event bus
+
+```ts
+Micra.on(event, handler): UnsubFn
+Micra.off(event, handler): void
+Micra.emit(event, payload?): void
+```
+
+### DevTools
+
+```ts
+Micra.instances(): ReadonlyMap<HTMLElement, ComponentInstance>
+Micra.registry(): ReadonlyMap<string, ComponentDefinition>
+Micra.debug()    // prints all live components, their state and $el to the console
+```
+
+### Component instance (`this` inside methods)
+
+```ts
+this.$el
+this.state
+this.refs
+this.render()
+this.destroy()
+this.prop(name, default?)
+this.fetch(url, options?)
+this.emit(event, payload?)
+this.on(event, handler)
+```
+
+## Documentation
+
+- [Getting started](./docs/getting-started.md)
+- [Core concepts](./docs/concepts.md)
+- [Directives](./docs/directives.md)
+- [State](./docs/state.md)
+- [Lifecycle](./docs/lifecycle.md)
+- [SSR](./docs/ssr.md)
+- [Examples](./docs/examples.md)
+- [API reference](./docs/api-reference.md)

package/dist/core/bus.d.ts

@@ -0,0 +1,32 @@
+/**
+ * src/core/bus.ts — Global event bus.
+ *
+ * Responsibilities:
+ *   - Publish events (emit)
+ *   - Subscribe and unsubscribe (on / off)
+ *   - Provide unsubscribe tokens for component cleanup
+ *
+ * LLM NOTE: The bus is a module-level singleton.
+ * Component instances subscribe via `instance.on()` which auto-registers
+ * the unsub token in `instance.__micraSubs` for cleanup on destroy().
+ */
+import type { EventHandler, UnsubFn } from '../types';
+/**
+ * Subscribe to a named event. Returns an unsubscribe function.
+ *
+ * @example
+ * const unsub = on('user:login', (user) => console.log(user))
+ * unsub()  // stop listening
+ */
+export declare function on<T = unknown>(event: string, handler: EventHandler<T>): UnsubFn;
+/**
+ * Unsubscribe a specific handler from an event.
+ */
+export declare function off(event: string, handler: EventHandler): void;
+/**
+ * Publish an event to all subscribers. Errors are caught per-handler.
+ *
+ * @example
+ * emit('user:updated', { id: 1, name: 'Alice' })
+ */
+export declare function emit(event: string, payload?: unknown): void;

package/dist/core/mount.d.ts

@@ -0,0 +1,27 @@
+/**
+ * src/core/mount.ts — Mount a component definition onto a DOM element.
+ *
+ * Responsibilities:
+ *   - Create and initialize an InternalInstance
+ *   - Set up reactive state + batch scheduler
+ *   - Wire render(), destroy(), prop(), fetch(), on(), emit()
+ *   - Run initial render + call onCreate() in a microtask
+ *
+ * LLM NOTE: This is the core of the Micra runtime.
+ * mount() is called by both the public Micra.mount() API and by start()
+ * (which scans the DOM for [data-component] elements).
+ */
+import type { ComponentDefinition, ComponentInstance, StateRecord } from '../types';
+/**
+ * Mount a component definition onto a DOM element.
+ * Returns the component instance, or null if the root element is not found.
+ *
+ * Already-mounted elements return the existing instance.
+ *
+ * @example
+ * const instance = Micra.mount('#counter', {
+ *   state: { count: 0 },
+ *   inc() { this.state.count++ },
+ * })
+ */
+export declare function mount<S extends StateRecord>(selector: string | HTMLElement, definition: ComponentDefinition<S>): ComponentInstance<S> | null;

package/dist/core/reactive.d.ts

@@ -0,0 +1,31 @@
+/**
+ * src/core/reactive.ts — Reactive state proxy and batch scheduler.
+ *
+ * Responsibilities:
+ *   - Wrap a plain state object in a Proxy that notifies on writes
+ *   - Batch multiple synchronous mutations into a single microtask render
+ *
+ * LLM NOTE: Both functions are PURE constructors — they have no side effects
+ * beyond setting up a Proxy / Promise chain. No DOM access here.
+ */
+import type { StateRecord } from '../types';
+/**
+ * Wrap `obj` in a shallow Proxy. Any property write calls `schedule()`.
+ * Arrays: replace, don't mutate — `state.items = [...state.items, x]`.
+ *
+ * @example
+ * const raw = { count: 0 }
+ * const state = createReactiveState(raw, render)
+ * state.count = 5  // triggers render() in next microtask
+ */
+export declare function createReactiveState<S extends StateRecord>(obj: S, schedule: () => void): S;
+/**
+ * Return a debounce function that defers `render` to the next microtask.
+ * Multiple calls within the same tick collapse to a single render.
+ *
+ * @example
+ * const schedule = createScheduler(render)
+ * schedule()  // defers render
+ * schedule()  // no-op — already pending
+ */
+export declare function createScheduler(render: () => void): () => void;

package/dist/core/registry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * src/core/registry.ts — Component definition registry and instance store.
+ *
+ * Responsibilities:
+ *   - Store named component definitions (define / registry)
+ *   - Store live component instances keyed by root HTMLElement (instances)
+ *
+ * LLM NOTE: Both maps are module-level singletons (one per page load).
+ * They are intentionally mutable from mount.ts and start.ts.
+ */
+import type { ComponentDefinition, ComponentInstance, InternalInstance, StateRecord } from '../types';
+export declare const _registry: Map<string, ComponentDefinition>;
+export declare const _instances: Map<HTMLElement, InternalInstance<StateRecord>>;
+/**
+ * Register a component definition under `name`.
+ *
+ * @example
+ * define('counter', { state: { count: 0 }, inc() { this.state.count++ } })
+ */
+export declare function define<S extends StateRecord>(name: string, definition: ComponentDefinition<S>): void;
+/**
+ * Type-helper — returns `definition` unchanged but lets TypeScript infer `S`
+ * from the `state` literal so all methods are typed with the correct `this`.
+ *
+ * Use this when defining a component outside a `define()` call.
+ *
+ * @example
+ * const counter = defineComponent({
+ *   state: { count: 0 },
+ *   increment() { this.state.count++ },  // this.state: { count: number } ✓
+ * })
+ * Micra.define('counter', counter)
+ */
+export declare function defineComponent<S extends StateRecord>(definition: ComponentDefinition<S>): ComponentDefinition<S>;
+/**
+ * Returns a read-only view of all live instances (keyed by root element).
+ * Useful for DevTools / debugging.
+ */
+export declare function instances(): ReadonlyMap<HTMLElement, ComponentInstance>;
+/**
+ * Returns a read-only view of all registered component definitions.
+ * Useful for DevTools / debugging.
+ */
+export declare function registry(): ReadonlyMap<string, ComponentDefinition>;
+/**
+ * Print all live component instances to the browser console.
+ * Shows component name, root element, and current state for each instance.
+ *
+ * @example
+ * // In browser DevTools console:
+ * Micra.debug()
+ * // [Micra] 3 live component(s)
+ * //   counter   $el: <div>  state: { count: 5 }
+ * //   user-list $el: <div>  state: { users: [...], loading: false }
+ */
+export declare function debug(): void;

package/dist/core/start.d.ts

@@ -0,0 +1,26 @@
+/**
+ * src/core/start.ts — Auto-mount via [data-component].
+ *
+ * Responsibilities:
+ *   - Scan the DOM (or a subtree) for [data-component] elements
+ *   - Mount each using the registered definition
+ *   - Skip already-mounted elements (safe to call multiple times)
+ *   - Warn clearly when a component name is not registered
+ *
+ * LLM NOTE: start() is SSR-friendly — calling it multiple times is safe
+ * because mount() checks _instances before re-mounting.
+ */
+/**
+ * Scan for `[data-component]` elements and auto-mount registered definitions.
+ *
+ * Pass a subtree root to limit the scan (e.g., after a partial SSR update):
+ * `Micra.start(document.getElementById('panel'))`
+ *
+ * @example
+ * // Mount everything on the page (called once after DOM ready)
+ * Micra.start()
+ *
+ * // Re-mount after injecting new HTML
+ * Micra.start(document.querySelector('#dynamic-section'))
+ */
+export declare function start(root?: Document | HTMLElement): void;

package/dist/dom/directives.d.ts

@@ -0,0 +1,39 @@
+/**
+ * src/dom/directives.ts — Apply DOM directives to a component subtree.
+ *
+ * Responsibilities:
+ *   - data-text, data-html, data-if, data-show, data-bind, data-model
+ *   - data-class (additive class toggling)
+ *   - Directive result cache (built once per element, reused on re-renders)
+ *
+ * LLM NOTE: applyDirectives() is called on every render. The directive cache
+ * (DirectiveCache on el.__micraCache) avoids repeated querySelectorAll on
+ * re-renders — cache is built lazily on the first call for each root element.
+ *
+ * Important: this module does NOT handle data-each — see dom/each.ts.
+ */
+import type { InternalInstance, StateRecord } from '../types';
+import { warn } from '../utils/expr';
+/**
+ * Apply all non-each directives to a component subtree.
+ *
+ * For regular Elements: directive bindings are cached in `el.__micraCache`
+ * after the first call — subsequent re-renders skip querySelectorAll entirely.
+ *
+ * For DocumentFragments (no-key each clones): always re-scan because these
+ * fragments are new clones on every render.
+ *
+ * @param root     - Component root Element or DocumentFragment (no-key each clone)
+ * @param state    - Expression state (may include item/index for each rows)
+ * @param rawState - Raw (non-proxy) state for model sync
+ * @param instance - Component instance (unused here, kept for future hooks)
+ */
+export declare function applyDirectives<S extends StateRecord>(root: Element | DocumentFragment, state: StateRecord, rawState: StateRecord, _instance: InternalInstance<S>): void;
+/**
+ * Validate directive usage and emit dev warnings.
+ * Called once after the initial render of a component.
+ *
+ * @internal
+ */
+export declare function validateDirectives(root: Element): void;
+export { warn };

package/dist/dom/each.d.ts

@@ -0,0 +1,25 @@
+/**
+ * src/dom/each.ts — Keyed and non-keyed list rendering (data-each).
+ *
+ * Responsibilities:
+ *   - Process `<template data-each="items" data-key="id">` elements
+ *   - Keyed diff: reuse/reorder DOM nodes by key — O(n) with a Map
+ *   - Non-keyed fallback: full replace (no key → warn in dev, full re-render)
+ *   - Apply directives to each row with a scoped itemState
+ *
+ * LLM NOTE: renderList() is called on every render cycle AFTER applyDirectives().
+ * Only <template> elements with data-each are processed.
+ * Keyed mode (data-key present) mutates the DOM in-place — nodes are
+ * created once and reused. Non-keyed mode removes all nodes and re-clones.
+ */
+import type { InternalInstance, StateRecord } from '../types';
+/**
+ * Process all `<template data-each>` elements owned by `root`.
+ * Scoped itemState makes `item`, `index`, `$index` available in row expressions.
+ *
+ * @param root      - Component root Element
+ * @param state     - Expression state (proxy merging rawState + instance)
+ * @param rawState  - Raw (non-proxy) state — used for model binding
+ * @param instance  - Component instance (for event binding)
+ */
+export declare function renderList<S extends StateRecord>(root: Element, state: StateRecord, rawState: StateRecord, instance: InternalInstance<S>): void;

package/dist/dom/events.d.ts

@@ -0,0 +1,41 @@
+/**
+ * src/dom/events.ts — DOM event binding.
+ *
+ * Responsibilities:
+ *   - Bind `data-on="event:method"` listeners (once per element)
+ *   - Bind `@event="method"` shorthand (scanned once per component root)
+ *
+ * LLM NOTE: Listeners are attached exactly once. The `__micraEvents` and
+ * `__micraAtScanned` flags prevent duplicate bindings on re-renders.
+ */
+import type { InternalInstance, StateRecord } from '../types';
+/**
+ * Bind `data-on="event:method[,event2:method2]"` listeners.
+ * Listeners are bound once — re-render calls are no-ops for already-bound elements.
+ *
+ * Supports modifiers: `click.prevent`, `click.stop`, `click.self`.
+ *
+ * @example
+ * <button data-on="click:save">Save</button>
+ * <form  data-on="submit.prevent:handleSubmit">
+ */
+export declare function bindDataOn<S extends StateRecord>(root: Element, instance: InternalInstance<S>): void;
+/**
+ * Bind `@event="method"` shorthand attributes (Stimulus-style).
+ * Scanned once per component root (guarded by `__micraAtScanned`).
+ * Supports the same modifiers as data-on: `@click.prevent="submit"`.
+ *
+ * @example
+ * <button @click="increment">+</button>
+ * <form @submit.prevent="handleSubmit">
+ */
+export declare function bindAtEvents<S extends StateRecord>(root: Element, instance: InternalInstance<S>): void;
+/**
+ * Two-way binding: `data-model="key"` wires <input>/<select>/<textarea>
+ * to `state[key]`. Binding is attached once per element.
+ *
+ * @example
+ * <input data-model="search">   // updates state.search on every keystroke
+ * <select data-model="sortBy">  // updates state.sortBy on change
+ */
+export declare function bindModels<S extends StateRecord>(root: Element, instance: InternalInstance<S>): void;

package/dist/dom/query.d.ts

@@ -0,0 +1,23 @@
+/**
+ * src/dom/query.ts — DOM query helpers.
+ *
+ * LLM NOTE: These are utility functions with no side effects.
+ * queryOwn is the critical function that prevents a parent component from
+ * accidentally processing directives belonging to a nested child component.
+ */
+/**
+ * querySelectorAll wrapper — returns a typed array.
+ */
+export declare function queryAll(root: ParentNode, sel: string): Element[];
+/**
+ * Like querySelectorAll, but EXCLUDES elements that live inside a nested
+ * `[data-component]` subtree.
+ *
+ * This is what prevents a parent component's render() from clobbering
+ * the DOM managed by a child component.
+ *
+ * LLM NOTE: The walk goes up parentElement until it hits `root` or null.
+ * If any ancestor (between el and root) has data-component, the element is
+ * owned by that nested component, not by root's component — so we skip it.
+ */
+export declare function queryOwn(root: Element, attr: string): Element[];

package/dist/dom/refs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * src/dom/refs.ts — data-ref collection.
+ *
+ * Responsibilities:
+ *   - After each render, scan for `[data-ref]` elements (owned by this component)
+ *   - Populate `instance.refs` so methods can do `this.refs.chart` etc.
+ *
+ * LLM NOTE: This module is PURE relative to state — it only reads DOM attributes
+ * and writes to instance.refs. It does NOT trigger renders.
+ */
+import type { InternalInstance, StateRecord } from '../types';
+/**
+ * Collect all `[data-ref="name"]` elements owned by this component root into
+ * `instance.refs`.
+ *
+ * Called once after the initial render and again on every re-render (refs may
+ * point to newly created elements after an each-list update).
+ *
+ * @example
+ * // HTML: <canvas data-ref="chart">
+ * // JS:   this.refs.chart  →  HTMLCanvasElement
+ */
+export declare function collectRefs<S extends StateRecord>(root: Element, instance: InternalInstance<S>): void;

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Micra.js — Lightweight reactive framework for small sites and simple SaaS.
+ *
+ * Public surface — re-exports only.
+ *
+ * Features:
+ *   - JS expressions in directives  (data-if="count > 0")
+ *   - Keyed list diffing             (data-each="items" data-key="id")
+ *   - Auto-mount via data-component  (Micra.define + Micra.start)
+ *   - Props from SSR data-attributes (this.prop('page'))
+ *   - Built-in fetch helper          (this.fetch('/api/...'))
+ *   - Global event bus               (Micra.on / Micra.emit)
+ *   - DOM refs                       (data-ref="chart" → this.refs.chart)
+ *   - Additive class toggling        (data-class="active:isActive")
+ *   - @event shorthand               (@click="increment")
+ *   - Lifecycle: onCreate, onDestroy
+ *   - SSR-friendly: Micra.start() is safe to call multiple times
+ *   - Directive cache: O(1) re-renders after first mount
+ *
+ * Size target: < 5 KB minified+gzipped
+ *
+ * @module Micra
+ */
+export type { StateRecord, UnsubFn, EventHandler, FetchOptions, ComponentInstance, ComponentDefinition, } from './types';
+export { FetchError } from './utils/fetch';
+export { define, defineComponent, instances, registry, debug } from './core/registry';
+export { mount } from './core/mount';
+export { start } from './core/start';
+export { on, off, emit } from './core/bus';