jq79 0.1.5 → 0.2.0

package/src/jq79.ts

@@ -238,7 +238,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
   return reactive
 }
 
-const CONTROL_ATTRS = new Set([":bind", ":if", ":elseif", ":else", ":each", ":key"])
+const CONTROL_ATTRS = new Set([":bind", ":if", ":elseif", ":else", ":each", ":key", ":with"])
 const EACH_PATTERN = /^\s*(\w+)\s+in\s+(.+)$/
 
 type ConditionalBranch = { expr?: string; node: TemplateNode }
@@ -337,7 +337,7 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
 
     childFx?.dispose()
     childFx = null
-    current?.destroy() // unmounts its marker range, removing the child's DOM
+    current?.destroy() // detaches its marker range, removing the child's DOM
     current = null
     currentDef = nextDef
     if (!nextDef) return
@@ -369,12 +369,53 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
   return wrapper
 }
 
+// :with="expr" narrows the scope for an element and its subtree: names
+// resolve against the expression's value first, then fall back to the outer
+// scope. The value is re-evaluated lazily on every name lookup (never
+// snapshotted), so an effect reading through this proxy tracks both the
+// expression's own dependencies and the property it reads - replacing the
+// object or mutating one of its properties re-renders exactly the dependents,
+// without rebuilding the subtree. Assignments to names the object owns write
+// through to it (reactively, if it came from a store); everything else
+// behaves as if the :with weren't there
+const createWithScope = (expr: string, scope: Record<string, any>): Record<string, any> => {
+  const source = (): Record<string, any> | null => {
+    const value = evalExpr(expr, scope)
+    return value !== null && typeof value === "object" ? value : null
+  }
+  return new Proxy(scope, {
+    has(target, key) {
+      const obj = source()
+      return (obj !== null && Reflect.has(obj, key)) || Reflect.has(target, key)
+    },
+    get(target, key) {
+      const obj = source()
+      if (obj !== null && Reflect.has(obj, key)) return obj[key as string]
+      return Reflect.get(target, key)
+    },
+    set(target, key, value) {
+      const obj = source()
+      if (obj !== null && Reflect.has(obj, key)) {
+        obj[key as string] = value
+        return true
+      }
+      return Reflect.set(target, key, value)
+    },
+  })
+}
+
 // renders a single element node: static attrs, @event listeners, a reactive
 // :bind object, and its (reactive) children. :if/:elseif/:else/:each are
 // handled by renderNodes, which decides *whether*/*how many times* a node is
 // rendered before calling this. Tags matching a PascalCase scope variable
 // render as nested components instead
-const renderNode = (node: TemplateNode, scope: Record<string, any>, fx: EffectScope): Node => {
+const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: EffectScope): Node => {
+  // :with applies to the element's own bindings (@events, :bind) and its
+  // whole subtree. On a :each element the item scope is already in place, so
+  // :with="item" works
+  const withExpr = node.attrs[":with"]
+  const scope = withExpr !== undefined ? createWithScope(withExpr, outerScope) : outerScope
+
   const componentKey = findComponentKey(scope, node.tag)
   if (componentKey) return renderNestedComponent(componentKey, node, scope, fx)
 
@@ -831,26 +872,31 @@ const SETUP_HELPERS: Record<string, any> = { $, $$, $create, $reactive }
 // The body is wrapped in an async IIFE so top-level `await` works: everything
 // up to the first await runs synchronously (before the template renders), and
 // later assignments update the DOM reactively when they happen
-const runSetupScript = (code: string, scope: Record<string, any>, effect: (run: () => void) => void) => {
+const runSetupScript = (code: string, scope: Record<string, any>, effect: (run: () => void) => void, instanceHelpers: Record<string, any> = {}) => {
+  // instanceHelpers are per-component-instance additions (e.g. $emit, which
+  // is bound to this instance's DOM position)
+  const helpers = { ...SETUP_HELPERS, ...instanceHelpers }
   const scriptScope = new Proxy(scope, {
     has: (target, key) =>
       key !== "$__effect" && key !== "$__import" &&
-      (Reflect.has(target, key) || !(key in globalThis) && !(key in SETUP_HELPERS)),
+      (Reflect.has(target, key) || !(key in globalThis) && !(key in helpers)),
   })
   const result: Promise<void> = new Function(
-    "$scope", "$__effect", "$__import", ...Object.keys(SETUP_HELPERS),
+    "$scope", "$__effect", "$__import", ...Object.keys(helpers),
     `return (async () => { with ($scope) { ${code} } })()`
-  )(scriptScope, effect, importResource, ...Object.values(SETUP_HELPERS))
+  )(scriptScope, effect, importResource, ...Object.values(helpers))
   result.catch(error => console.error("jq79: error in :setup script", error))
 }
 
+type EmitListener = (event: CustomEvent, payload: any) => void
+
 // a parsed single-file component. Typical lifecycle:
 //
 //   const jq79 = new Component79(src)   // or await Component79.fetch(url)
-//   jq79.render({ user })               // build reactive DOM, run scripts, inject styles
-//      .mount("#app")                  // attach (renderShadow mounts into a shadow root)
-//   ...
-//   jq79.unmount()                      // detach, keeping state - mount() re-attaches
+//   jq79.on("submit", (e, payload) => {}) // hear this instance's $emit events
+//   jq79.mount("#app", { user })        // render (reactive DOM, scripts, styles) + attach
+//   ...                                 // (mountShadow mounts into a shadow root)
+//   jq79.detach()                       // detach, keeping state - mount() re-attaches
 //      .destroy()                      // dispose effects and remove styles
 export class Component79 {
   template: TemplateNode[]
@@ -860,11 +906,11 @@ export class Component79 {
   data: ReactiveDeepData<Record<string, any>> | null = null
 
   private fx: EffectScope | null = null
-  // holds the rendered nodes while unmounted; anchors keep this fragment as
+  // holds the rendered nodes while detached; anchors keep this fragment as
   // their parentNode, so effects keep the (detached) DOM up to date and a
   // later mount() shows current state
   private content: DocumentFragment | null = null
-  // markers bracketing the component's output so unmount() can collect nodes
+  // markers bracketing the component's output so detach() can collect nodes
   // that :if/:each inserted next to the anchors after mounting
   private startMarker: Comment | null = null
   private endMarker: Comment | null = null
@@ -874,6 +920,11 @@ export class Component79 {
   private ownsSharedStyles = false
   private useShadow = false
   private mountRoot: Element | ShadowRoot | DocumentFragment | null = null
+  // settles the $mounted() promise handed to this render generation's scripts
+  private resolveMounted: (() => void) | null = null
+  // instance-level listeners for $emit events, registered with on(). Kept
+  // outside the render generation so they survive re-render and destroy()
+  private emitListeners = new Map<string, Set<EmitListener>>()
 
   constructor(src: string | ComponentParts) {
     const { template, scripts, styles } = typeof src === "string" ? parseComponentString(src) : src
@@ -888,6 +939,21 @@ export class Component79 {
     return new Component79(await response.text())
   }
 
+  // subscribes to this instance's $emit events, on top of the DOM CustomEvent
+  // dispatch - so it hears emits even while the component is detached (where
+  // the event has no ancestors to bubble to). Chainable; can be called before
+  // render()
+  on(eventName: string, listener: EmitListener): this {
+    if (!this.emitListeners.has(eventName)) this.emitListeners.set(eventName, new Set())
+    this.emitListeners.get(eventName)!.add(listener)
+    return this
+  }
+
+  off(eventName: string, listener: EmitListener): this {
+    this.emitListeners.get(eventName)?.delete(listener)
+    return this
+  }
+
   render(data: Record<string, any> = {}): this {
     return this.renderWith(data, false)
   }
@@ -907,17 +973,65 @@ export class Component79 {
     this.fx = fx
     this.useShadow = shadow
 
-    // scripts run before the template renders so `$:` values are initialized
+    this.startMarker = document.createComment("jq79")
+    this.endMarker = document.createComment("/jq79")
+
+    // $emit dispatches a bubbling CustomEvent from this instance's start
+    // marker, so once mounted it travels up the real DOM and parents can
+    // listen on any ancestor (or with @event-name on a wrapping element).
+    // Captures the marker rather than `this` so a later re-render's scripts
+    // can't dispatch from the wrong generation - the same guard keeps stale
+    // generations from reaching the instance's on() listeners
+    const marker = this.startMarker
+    const $emit = (eventName: string, payload?: any): boolean => {
+      const event = new CustomEvent(eventName, { detail: payload, bubbles: true, composed: true })
+      const result = marker.dispatchEvent(event)
+      if (marker === this.startMarker) {
+        this.emitListeners.get(eventName)?.forEach(listener => listener(event, payload))
+      }
+      return result
+    }
+
+    // `await $mounted()` suspends a setup script until mount() attaches the
+    // component, so code below it can querySelector its own DOM. Resumption
+    // is a microtask, so in the usual synchronous render().mount() flow the
+    // whole tree (nested components included) is in the document before the
+    // script continues. If this instance is never mounted, the promise stays
+    // pending and the script's tail never runs
+    let resolveMounted!: () => void
+    const mounted = new Promise<void>(resolve => { resolveMounted = resolve })
+    this.resolveMounted = resolveMounted
+    const $mounted = () => mounted
+
+    // $self / $$self mirror $ / $$ but only search this instance's own
+    // output: the sibling nodes between its markers. They work detached too
+    // (the holding fragment keeps markers and rendered nodes as siblings),
+    // though the template renders after the scripts run, so they only find
+    // something from post-await code or callbacks
+    const endMarker = this.endMarker
+    const $$self = (selector: string): Element[] => {
+      const found: Element[] = []
+      for (let node: Node | null = marker.nextSibling; node && node !== endMarker; node = node.nextSibling) {
+        if (node instanceof Element) {
+          if (node.matches(selector)) found.push(node)
+          found.push(...Array.from(node.querySelectorAll(selector)))
+        }
+      }
+      return found
+    }
+    const $self = (selector: string): Element | null => $$self(selector)[0] ?? null
+
+    // scripts run before the template renders so `$:` values are initialized;
+    // a `:mounted` script defers entirely until mount() instead
     this.scripts.forEach(script => {
       const { vars, code } = transformSetupScript(script.content)
       // pre-declare script vars on the store so `with` resolves assignments
       // to them (and reads of them) through the reactive proxy
       vars.forEach(name => { if (!(name in store)) (store as any)[name] = undefined })
-      runSetupScript(code, store, fx.effect)
+      const body = ":mounted" in script.attrs ? `await $mounted();\n${code}` : code
+      runSetupScript(body, store, fx.effect, { $emit, $mounted, $self, $$self })
     })
 
-    this.startMarker = document.createComment("jq79")
-    this.endMarker = document.createComment("/jq79")
     const content = document.createDocumentFragment()
     content.append(this.startMarker, renderNodes(this.template, store, fx), this.endMarker)
     this.content = content
@@ -936,22 +1050,44 @@ export class Component79 {
     return this
   }
 
-  mount(parent: Element | ShadowRoot | DocumentFragment | string): this {
+  // renders (when needed) and attaches in one call: the component is rendered
+  // on the first mount, and re-rendered fresh whenever `data` is passed.
+  // mount(el) on an already-rendered component just re-attaches, keeping its
+  // state - the detach()/mount() round trip. Rendering here keeps whichever
+  // style mode was last used (document.head unless renderShadow/mountShadow
+  // chose a shadow root)
+  mount(parent: Element | ShadowRoot | DocumentFragment | string, data?: Record<string, any>): this {
+    const target = typeof parent === "string" ? $(parent) : parent
+    if (!target) throw new Error(`mount target not found: ${parent}`)
+    if (!this.content || data !== undefined) this.renderWith(data ?? {}, this.useShadow)
+    return this.attach(target)
+  }
+
+  // like mount(), but renders with styles scoped to a shadow root on the
+  // target instead of document.head
+  mountShadow(parent: Element | ShadowRoot | DocumentFragment | string, data?: Record<string, any>): this {
     const target = typeof parent === "string" ? $(parent) : parent
     if (!target) throw new Error(`mount target not found: ${parent}`)
-    if (!this.content) throw new Error("render() must be called before mount()")
-    if (this.mountRoot) this.unmount()
+    if (!this.content || data !== undefined || !this.useShadow) this.renderWith(data ?? {}, true)
+    return this.attach(target)
+  }
+
+  private attach(target: Element | ShadowRoot | DocumentFragment): this {
+    if (this.mountRoot) this.detach()
 
     const root = this.useShadow && target instanceof Element
       ? target.shadowRoot ?? target.attachShadow({ mode: "open" })
       : target
     if (this.useShadow) this.styleEls.forEach(el => root.appendChild(el))
-    root.appendChild(this.content)
+    root.appendChild(this.content!)
     this.mountRoot = root
+    this.resolveMounted?.()
     return this
   }
 
-  unmount(): this {
+  // detaches from the DOM while keeping all state; a later mount() re-attaches
+  // with any updates that happened while detached already applied
+  detach(): this {
     if (!this.mountRoot || !this.content || !this.startMarker || !this.endMarker) return this
 
     // move everything between the markers (inclusive) back into the holding
@@ -969,7 +1105,7 @@ export class Component79 {
   }
 
   destroy(): this {
-    this.unmount()
+    this.detach()
     this.fx?.dispose()
     this.fx = null
     this.styleEls.forEach(el => el.parentNode?.removeChild(el))
@@ -982,6 +1118,7 @@ export class Component79 {
     this.startMarker = null
     this.endMarker = null
     this.data = null
+    this.resolveMounted = null
     return this
   }
 }