micra.js 2.2.1 → 2.3.1

package/src/dom/scan.ts

@@ -5,12 +5,13 @@
  * traversal that classifies every directive attribute in a single visit.
  *
  * Boundaries:
- *   - REJECT (skip subtree) on nested [data-component] — same semantics as
- *     the old `filterOwn` helper, but applied during the walk so we don't
- *     even *visit* those nodes.
+ *   - REJECT (skip subtree) on nested [data-component] — a parent component
+ *     never processes directives owned by a nested child. Applied during the
+ *     walk so we don't even *visit* those nodes.
  *   - <template> contents are not visited (browser TreeWalker default).
  *     `<template data-each>` itself IS visited and classified into scan.each;
- *     its children are processed by each.ts on every render via scanFragment.
+ *     its children are processed by each.ts on every render — fresh rows
+ *     are wrapped in a per-row element and scanned via scanComponent.
  *
  * Hot-path notes:
  *   - We read `el.attributes` once and switch by suffix. No allocations per
@@ -166,24 +167,3 @@ export function scanComponent(root: Element): ScanIndex {
   return scan;
 }
 
-/**
- * Scan a DocumentFragment (no-key each clone). Not cached — these fragments
- * are temporary and re-cloned every render.
- */
-export function scanFragment(frag: DocumentFragment): ScanIndex {
-  const scan = emptyScan();
-
-  const walker = document.createTreeWalker(
-    frag,
-    NodeFilter.SHOW_ELEMENT,
-    NESTED_COMPONENT_FILTER,
-  );
-
-  let node: Element | null = walker.nextNode() as Element | null;
-  while (node) {
-    classify(node, scan);
-    node = walker.nextNode() as Element | null;
-  }
-
-  return scan;
-}

package/src/index.ts

@@ -27,6 +27,9 @@ export type {
   StateRecord,
   UnsubFn,
   EventHandler,
+  EventPayload,
+  EmitArgs,
+  MicraEvents,
   FetchOptions,
   ComponentMethods,
   ComponentBuiltins,

package/src/types.ts

@@ -22,6 +22,53 @@ export type UnsubFn = () => void
 /** Event bus handler. Generic `T` types the payload. */
 export type EventHandler<T = unknown> = (payload: T) => void
 
+/**
+ * Type-safe event bus registry. Empty by default — augment it via
+ * declaration merging to type your application's events.
+ *
+ * @example
+ * declare module 'micra.js' {
+ *   interface MicraEvents {
+ *     'cart:updated': { count: number }
+ *     'user:login':   { id: number; name: string }
+ *     'modal:close':  void
+ *   }
+ * }
+ *
+ * Micra.emit('cart:updated', { count: 3 })       // ✓ typed
+ * Micra.emit('cart:updated', { count: '3' })     // ✗ type error
+ * Micra.on('user:login', user => user.id)        // user: { id, name }
+ *
+ * Events not present in the interface fall back to `unknown` payload —
+ * fully backward-compatible with untyped usage.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface MicraEvents {}
+
+/**
+ * Resolves the payload type for an event key. For keys registered in
+ * `MicraEvents` returns the declared payload; for any other string key
+ * returns `unknown` (preserving backward compatibility).
+ */
+export type EventPayload<K extends string> = K extends keyof MicraEvents
+  ? MicraEvents[K]
+  : unknown
+
+/**
+ * Tuple of arguments passed to `emit` after the event name. When the
+ * payload type for a known event includes `undefined` (or the payload is
+ * declared as `void`), the argument is optional. For known events with a
+ * required payload, the argument is required. Unknown events accept any
+ * optional payload (backward compat).
+ */
+export type EmitArgs<K extends string> = K extends keyof MicraEvents
+  ? [MicraEvents[K]] extends [void]
+    ? [payload?: undefined]
+    : undefined extends MicraEvents[K]
+      ? [payload?: MicraEvents[K]]
+      : [payload: MicraEvents[K]]
+  : [payload?: unknown]
+
 /** Options for `this.fetch()`. For GET/HEAD extra keys become query params. */
 export interface FetchOptions {
   method?: string
@@ -71,10 +118,16 @@ export interface ComponentBuiltins<S extends StateRecord = StateRecord> {
   prop<T>(name: string, defaultVal: T): T
   /** Fetch helper: CSRF header, JSON body, query params, typed errors. */
   fetch(url: string, options?: FetchOptions): Promise<unknown>
-  /** Publish an event on the global bus. */
-  emit(event: string, payload?: unknown): void
-  /** Subscribe to the global bus. Subscription is auto-removed on destroy(). */
-  on<T = unknown>(event: string, handler: EventHandler<T>): UnsubFn
+  /**
+   * Publish an event on the global bus.
+   * Payload is typed via the `MicraEvents` interface (augmentable).
+   */
+  emit<K extends string>(event: K, ...args: EmitArgs<K>): void
+  /**
+   * Subscribe to the global bus. Subscription is auto-removed on destroy().
+   * Handler payload is typed via the `MicraEvents` interface (augmentable).
+   */
+  on<K extends string>(event: K, handler: (payload: EventPayload<K>) => void): UnsubFn
 }
 
 /**
@@ -146,8 +199,6 @@ export interface MicraElement extends HTMLElement {
   __micraModel?: true       // data-model listener bound
   __micraEvents?: true      // data-on listeners bound
   __micraAtBound?: true     // @event shorthand bound (per-element)
-  __micraKey?: unknown      // keyed-diff key
-  __micraEach?: true        // belongs to a no-key each list
   __micraScan?: ScanIndex   // single-pass scan result (cached after 1st render)
   __micraItem?: StateRecord  // keyed row: last-rendered item ref (for skip check)
   __micraIndex?: number      // keyed row: last-rendered index (for skip check)

package/src/dom/query.ts

@@ -1,50 +0,0 @@
-/**
- * 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 function queryAll(root: ParentNode, sel: string): Element[] {
-  return Array.from(root.querySelectorAll(sel))
-}
-
-/**
- * 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 function queryOwn(root: Element, attr: string): Element[] {
-  return filterOwn(root, queryAll(root, `[${attr}]`))
-}
-
-/**
- * Like queryOwn but accepts an arbitrary CSS selector. Used by bindAtEvents
- * which scans `*` for `@`-prefixed attribute names (no attribute selector exists
- * for those).
- */
-export function queryOwnAll(root: Element, sel: string): Element[] {
-  return filterOwn(root, queryAll(root, sel))
-}
-
-/** @internal Shared subtree-ownership filter. */
-function filterOwn(root: Element, els: Element[]): Element[] {
-  return els.filter(el => {
-    let node: Element | null = el.parentElement
-    while (node && node !== root) {
-      if (node.hasAttribute('data-component')) return false
-      node = node.parentElement
-    }
-    return true
-  })
-}