jq79 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jq79",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Mini reactive component library: single-file components, Svelte-style setup scripts, fine-grained proxy reactivity. Single-file build, zero dependencies.",
   "keywords": [
     "reactive",

package/src/jq79.ts

@@ -94,12 +94,95 @@ const compileExpr = (expr: string, params: string[]): Function | null => {
   return fn
 }
 
+// a template expression is re-evaluated constantly - once per effect run, once
+// per interpolation, once per :each item - so a value that is briefly undefined
+// mid-render has to fail quietly, and the catch below stays. A ReferenceError
+// is the one failure worth a word: `with` resolves a name against the store and
+// then globalThis, so a name that resolves nowhere is declared nowhere - a
+// typo, a dropped prop, or the trap this was written for, a top-level
+// `function` declaration, which transformSetupScript leaves as an ordinary
+// lexical binding instead of a store property
+//
+// It is reported late rather than where it throws, because "declared nowhere"
+// is not yet decidable at that moment: a factory script assigns its bindings to
+// the store when it returns, so an async factory renders its whole template
+// before any of its names exist. Reporting waits until no script is still
+// running (pendingScripts), and then asks whether the name resolves *now*.
+//
+// The re-check is `name in scope` rather than a re-evaluation, because
+// re-evaluating is not pure: `@click="count++ + missing"` increments before it
+// throws, and running it again to see if it still throws would increment twice
+// and notify. `in` walks the same scope chain (:each scopes are
+// Object.create(scope), :with is a proxy over it) and evaluates nothing
+const MISSING_NAME_RE = /^(?:([\w$]+) is not defined|Can't find variable: ([\w$]+))/
+
+// the queue holds live scopes, so it is capped: a script that never settles
+// would otherwise let it grow for the life of the page
+const MAX_PENDING_REPORTS = 100
+
+type PendingReport = { name: string; expr: string; scope: Record<string, any> }
+
+const pendingReports = new Map<string, PendingReport>()
+const reportedExprErrors = new Set<string>()
+let pendingScripts = 0
+let flushScheduled = false
+
+const flushExprReports = () => {
+  flushScheduled = false
+  if (pendingScripts > 0) return // a script started meanwhile; its release re-schedules
+  pendingReports.forEach(({ name, expr, scope }, key) => {
+    if (name in scope) return // it arrived late - a factory's bindings, a prop
+    reportedExprErrors.add(key)
+    console.warn(
+      `jq79: ${name} is not defined - evaluating "${expr}". Template expressions ` +
+      `resolve against the component store: a top-level let/var/const in a :setup ` +
+      `script, a declared prop, or a global. Note a "function name() {}" declaration ` +
+      `is not on the store - write "const name = () => {}".`
+    )
+  })
+  pendingReports.clear()
+}
+
+const scheduleExprReportFlush = () => {
+  if (flushScheduled || pendingScripts > 0 || !pendingReports.size) return
+  flushScheduled = true
+  queueMicrotask(flushExprReports)
+}
+
+// scripts run before the template renders, so the counter is already up when
+// the first evaluation fails. Both script modes settle through a promise;
+// the factory's has to cover the merge, not just the module body
+const trackScript = (settled: Promise<unknown>) => {
+  pendingScripts++
+  const release = () => {
+    pendingScripts--
+    scheduleExprReportFlush()
+  }
+  settled.then(release, release)
+}
+
+const reportExprError = (expr: string, scope: Record<string, any>, error: unknown) => {
+  if (!(error instanceof ReferenceError)) return
+  const match = MISSING_NAME_RE.exec(error.message)
+  const name = match?.[1] ?? match?.[2]
+  if (!name) return // an engine whose wording we don't know: stay quiet, as before
+  // keyed on name and expression, not on the expression alone, so two missing
+  // names in one expression stay distinguishable - and so a :each of 1000 items
+  // enqueues one entry rather than 1000
+  const key = `${name}|${expr}`
+  if (reportedExprErrors.has(key) || pendingReports.has(key)) return
+  if (pendingReports.size >= MAX_PENDING_REPORTS) return
+  pendingReports.set(key, { name, expr, scope })
+  scheduleExprReportFlush()
+}
+
 const evalExpr = (expr: string, scope: Record<string, any>, extras?: Record<string, any>): any => {
   const fn = compileExpr(expr, extras ? Object.keys(extras) : [])
   if (!fn) return undefined
   try {
     return fn(scope, ...(extras ? Object.values(extras) : []))
-  } catch {
+  } catch (error) {
+    reportExprError(expr, scope, error)
     return undefined
   }
 }
@@ -689,6 +772,7 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     // or an undeclared name would be filtered on the first render and reappear
     // on the next update
     const declared = declaredPropSet(instance.scripts)
+    warnUndeclared(node, key, Object.keys(props), declared)
     const seed = pickDeclared(untracked(resolveProps), declared)
     // mounting into a fragment attaches no shadow root of its own: a
     // shadow-rendered child keeps its <style> elements inline, next to the DOM
@@ -819,6 +903,41 @@ const normalizeAllowUrl = (policy: any): AllowUrl => {
   return () => false
 }
 
+// HTML's boolean attributes, verbatim from the spec's list. Presence is the
+// whole message for these: `disabled="false"` and `disabled="0"` both disable,
+// so the value they carry is noise. This is a table of a fact, not of a jq79
+// convention - nobody in this repo decides what belongs in it, which is what
+// earns it a place in a codebase that otherwise has no name tables
+const BOOLEAN_ATTRS = new Set([
+  "allowfullscreen", "async", "autofocus", "autoplay", "checked", "controls",
+  "default", "defer", "disabled", "formnovalidate", "inert", "ismap",
+  "itemscope", "loop", "multiple", "muted", "nomodule", "novalidate", "open",
+  "playsinline", "readonly", "required", "reversed", "selected",
+])
+
+// the one value rule, shared by `:attr="expr"` and `:attrs` so the two forms
+// can never disagree:
+//
+// - a boolean attribute is removed by ANY falsy value and set to "" when
+//   truthy, so `:disabled="items.length"` enables the button on an empty list
+//   (with `value !== false` as the only test, 0 set the attribute and disabled
+//   it - the trap renderComponent.test.ts used to pin);
+// - every other attribute is removed only by null/undefined, so `false`, `0`
+//   and `""` are written. `aria-expanded="false"` and a `data-` flag mean
+//   something that absent cannot say.
+//
+// Asking the DOM which family a name belongs to (`typeof el[name] ===
+// "boolean"`) is deliberately not what this does: jsdom and Chrome disagree on
+// `autofocus` and every `aria-*`, so the tests would pin a semantics the
+// browser doesn't have - and `readonly`/`novalidate`/`ismap` reflect under
+// camelCase property names no kebab->camel pass can produce, failing toward
+// `readonly="false"`, which is read-only
+const applyAttr = (el: Element, name: string, value: any) => {
+  const boolean = BOOLEAN_ATTRS.has(name)
+  if (boolean ? !value : value == null) el.removeAttribute(name)
+  else el.setAttribute(name, boolean ? "" : String(value))
+}
+
 // renders a single element node: static attrs, @event listeners, a reactive
 // :attrs object, and its content - :text/:html override the element's own
 // children with a reactive textContent/innerHTML, otherwise children render
@@ -848,7 +967,11 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
   // imported component after `await`). Watch for the key: the effect tracks
   // no deps, so it only re-runs on the store's new-key sweep, and swaps the
   // placeholder element for the component exactly once
-  if (el instanceof HTMLUnknownElement || node.tag.includes("-")) {
+  // dashes included, because findComponentKey matches them case-insensitively
+  // with dashes stripped: <drop-area> resolves DropArea, so a dashed tag is a
+  // possible component too, not only a custom element
+  const mayUpgrade = el instanceof HTMLUnknownElement || node.tag.includes("-")
+  if (mayUpgrade) {
     let upgraded = false
     fx.effect(() => {
       if (upgraded) return
@@ -871,10 +994,30 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
       // the native-element form is parked there). Warn on a real element, but
       // not on a tag that may still upgrade into a component - the upgrade
       // re-renders through renderNestedComponent, models and all
-      if (!(el instanceof HTMLUnknownElement || node.tag.includes("-"))) {
+      if (!mayUpgrade) {
         console.warn(`jq79: ${key} on <${node.tag}> does nothing - :model binds component tags only (for now)`)
       }
-    } else if (!isControlAttr(key)) el.setAttribute(key, value)
+    } else if (isControlAttr(key)) {
+      // a directive of its own, bound further down (or by renderNodes)
+    } else if (key.startsWith(":")) {
+      // :name="expr" binds that one attribute, reactively - the single-key
+      // case :attrs="{ name: expr }" was carrying. `:name` alone is shorthand
+      // for `:name="name"`, like props and :model.<name>, and the shorthand
+      // reads the camelCase variable while the attribute keeps its written
+      // (kebab) name: `:aria-expanded` binds `ariaExpanded`, because
+      // `aria-expanded` as an expression is a subtraction.
+      //
+      // On a tag that may still upgrade this is a *parameter*, not an
+      // attribute: leave it written verbatim, as before, so the upgrade's
+      // renderNestedComponent still finds it. A component tag has no single
+      // root for an attribute to land on anyway (TODOS/2026-07-15.class-directive.md)
+      if (mayUpgrade) el.setAttribute(key, value)
+      else {
+        const name = key.slice(1)
+        const expr = value || kebabToCamel(name)
+        fx.effect(() => applyAttr(el, name, evalExpr(expr, scope)))
+      }
+    } else el.setAttribute(key, value)
   })
 
   const bindExpr = node.attrs[":attrs"]
@@ -885,10 +1028,7 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
       boundKeys.forEach(key => el.removeAttribute(key))
       const bound = evalExpr(bindExpr, scope)
       boundKeys = bound && typeof bound === "object" ? Object.keys(bound) : []
-      boundKeys.forEach(key => {
-        const value = bound[key]
-        if (value != null && value !== false) el.setAttribute(key, String(value))
-      })
+      boundKeys.forEach(key => applyAttr(el, key, bound[key]))
     })
   }
 
@@ -1625,6 +1765,7 @@ const runSetupScript = (code: string, scope: Record<string, any>, effect: (run:
     `return (async () => { with ($scope) { ${code} } })()${sourceUrlComment(at.filename, at.index ?? 0)}`
   )(scriptScope, effect, importer, ...Object.values(helpers))
   result.catch(error => console.error("jq79: error in :setup script", error))
+  trackScript(result)
 }
 
 // puts a component's declared props on the store, before any script runs and
@@ -1646,6 +1787,22 @@ const declareProps = (store: Record<string, any>, props: PropDecl[] | null) => {
   })
 }
 
+// a setup script's signature. A bare `<script :setup>` is a CLOSED signature -
+// the same as `<script :setup="{}">`, declaring zero props and taking none -
+// because the difference between "takes nothing" and "takes anything" should
+// not be a pair of braces somebody didn't type. Permissive is still reachable,
+// it just has to be asked for: `<script :setup="_">`, the same `_` convention
+// factory scripts already use, which parsePropsPattern reads as no signature.
+//
+// Only the empty *value* is closed. An absent attribute (a factory <script>
+// with no :setup at all) stays `null`, so its signature is still read from the
+// factory's first parameter
+const setupSignature = (script: TagBlock): PropDecl[] | null => {
+  const pattern = script.attrs[":setup"]
+  if (pattern === undefined) return null
+  return pattern.trim() === "" ? [] : parsePropsPattern(pattern)
+}
+
 // every prop name a component's scripts declare, across both script modes.
 // Read before the store exists, because what a component declares decides
 // which of its file's sibling components it can still see: declaring a name
@@ -1654,7 +1811,7 @@ const declareProps = (store: Record<string, any>, props: PropDecl[] | null) => {
 const declaredPropNames = (scripts: TagBlock[]): Set<string> => {
   const names = new Set<string>()
   scripts.forEach(script => {
-    const declarations = parseFactoryProps(script.content) ?? parsePropsPattern(script.attrs[":setup"])
+    const declarations = parseFactoryProps(script.content) ?? setupSignature(script)
     declarations?.forEach(({ name }) => names.add(name))
   })
   return names
@@ -1662,13 +1819,13 @@ const declaredPropNames = (scripts: TagBlock[]): Set<string> => {
 
 // the same names, but null when NO script declared a signature at all - the
 // distinction declareProps already keeps, and the only one that can decide
-// whether to filter what a parent passes: `<script :setup>` declares nothing
-// and stays permissive, `<script :setup="{}">` is a closed signature that
-// declares zero props and takes none
+// whether to filter what a parent passes. `<script :setup>` and
+// `<script :setup="{}">` are both closed signatures that take nothing (see
+// setupSignature); `<script :setup="_">` is the permissive one
 const declaredPropSet = (scripts: TagBlock[]): Set<string> | null => {
   let names: Set<string> | null = null
   scripts.forEach(script => {
-    const declarations = parseFactoryProps(script.content) ?? parsePropsPattern(script.attrs[":setup"])
+    const declarations = parseFactoryProps(script.content) ?? setupSignature(script)
     if (!declarations) return
     const into = (names ??= new Set())
     declarations.forEach(({ name }) => into.add(name))
@@ -1690,6 +1847,30 @@ const pickDeclared = (props: Record<string, any>, declared: Set<string> | null):
   return out
 }
 
+// names already reported by warnUndeclared, keyed by the template node - which
+// is the usage site itself, built once and shared by every instance it ever
+// renders. So a :each over 200 rows says it once, not once per row, and a
+// definition swap doesn't repeat what the last one already said
+const undeclaredWarned = new WeakMap<TemplateNode, Set<string>>()
+
+// a parameter the child's signature doesn't declare is dropped by pickDeclared
+// and never reaches its store - `{{ bar }}` renders empty at the other end of
+// the file. Written parameters only: this is handed the named ones (`:bar`,
+// and the prop each :model binds), never a `:props` spread's keys, because a
+// spread of an object wider than the component is the documented, intended use
+// and taking only the declared few is its point - see pickDeclared. A
+// component with no signature at all declares nothing to compare against
+const warnUndeclared = (node: TemplateNode, name: string, written: string[], declared: Set<string> | null) => {
+  if (declared === null) return
+  const said = undeclaredWarned.get(node) ?? new Set<string>()
+  undeclaredWarned.set(node, said)
+  written.forEach(prop => {
+    if (declared.has(prop) || said.has(prop)) return
+    said.add(prop)
+    console.warn(`jq79: :${prop} is not declared by <${name}> - add it to the :setup signature, or drop it`)
+  })
+}
+
 // the sibling components this one resolves by name, or null when there are
 // none left to resolve. They go on the store's *prototype* rather than in it:
 // the component-key scan walks the chain, so <Row> resolves; they stay out of
@@ -1741,11 +1922,16 @@ const runFactoryScript = (code: string, scope: Record<string, any>, effect: (run
 
   const logError = (error: any) => console.error("jq79: error in factory script", error)
   let invoked = false
-  const invoke = () => {
-    if (invoked) return
+  // what invoke() is still waiting on, memoized: it is called from both paths
+  // below and does its work once, but the *second* caller is the one whose
+  // promise is tracked - without this it would see `undefined` and count the
+  // script as settled while an async factory's bindings are still on the way
+  let merging: Promise<void> | undefined
+  const invoke = (): Promise<void> | undefined => {
+    if (invoked) return merging
     invoked = true
     const factory = $__exports.default
-    if (typeof factory !== "function") return
+    if (typeof factory !== "function") return undefined
     const merge = (bindings: any) => {
       if (bindings && typeof bindings === "object") Object.assign(scope, bindings)
     }
@@ -1756,14 +1942,18 @@ const runFactoryScript = (code: string, scope: Record<string, any>, effect: (run
       // the props it declared (copying, as destructuring does - $props is the
       // live view for a primitive the parent reassigns later)
       const returned = factory(scope, { $data: scope, $props: scope, $effect: effect, ...instanceHelpers })
-      if (returned instanceof Promise) returned.then(merge).catch(logError)
+      if (returned instanceof Promise) merging = returned.then(merge).catch(logError)
       else merge(returned)
     } catch (error) {
       logError(error)
     }
+    return merging
   }
 
-  result.then(invoke, logError)
+  // tracked through the merge, not just the module body: a factory's names
+  // reach the store in `merge`, and a template expression that reads one before
+  // then is not an authoring mistake (see reportExprError)
+  trackScript(result.then(invoke, logError))
   if ($__exports.done) invoke() // fully-sync body: factory runs before first render
 }
 
@@ -1982,6 +2172,13 @@ export class Component79 {
   // while its markers sit where its DOM actually is
   hotReplace(src: string | ComponentParts): boolean {
     const parts = typeof src === "string" ? parseComponentString(src) : src
+    // the source just changed, so what was already said about it no longer
+    // applies: without this the author fixes the typo, saves, and the next typo
+    // in the same expression is deduped away against the old one. `compiled`
+    // needs no such reset - it is keyed by expression text, so edited source is
+    // a different key
+    reportedExprErrors.clear()
+    pendingReports.clear()
     const marker = this.startMarker
     const rendered = !!(marker && this.content)
 
@@ -2217,7 +2414,7 @@ export class Component79 {
         return
       }
       const { vars, code } = transformSetupScript(script.content)
-      declareProps(store, parsePropsPattern(script.attrs[":setup"]))
+      declareProps(store, setupSignature(script))
       // 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 })