jq79 0.4.18 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jq79",
-  "version": "0.4.18",
+  "version": "0.5.1",
   "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

@@ -550,6 +550,11 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
   // the assignment would vanish into the comment and compile as a bare read,
   // dropping every update without a word
   const assignment = (expr: string) => `${expr}\n= $value`
+  // the models whose expression will never take an update, decided here rather
+  // than at update time: an assignment that landed and one that was dropped
+  // both evaluate to the value assigned, so the result can't tell them apart -
+  // which is what $updateModel's return has to report
+  const unassignable = new Set<string>()
   Object.entries(models).forEach(([name, expr]) => {
     const prop = modelProp(name)
     if (props[prop] !== undefined) {
@@ -559,6 +564,7 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     // an expression that can't be an assignment target is a wiring mistake -
     // say so now, not on the first update that silently goes nowhere
     if (compileExpr(assignment(expr), ["$value"]) === null) {
+      unassignable.add(name)
       console.warn(`jq79: ${modelAttr(name)}="${expr}" is not assignable - updates from <${node.tag}> will be dropped`)
     }
   })
@@ -640,39 +646,37 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     // the content this site wrote inside the tag, before the first render: a
     // <slot> is resolved while rendering, so the map has to be there by then
     if (slots) instance.slots = slots
-    // the writeback half of :model - one event, one contract. The name is
-    // normalized like the attribute was (kebab->camel; absent means default),
-    // and everything off-contract warns and does nothing: an event protocol's
-    // failure mode has to be loud, or a typo'd name is an input that types
-    // into the void
+    // the writeback half of :model - the function the child's $updateModel
+    // calls, handed over before the first render. Not an event: nothing about
+    // a parent-child assignment wants a CustomEvent bubbling through the page
+    // on every keystroke, and a direct call has no payload shape to get wrong.
+    // The name is normalized like the attribute was (kebab->camel; absent
+    // means the default model), and a name nothing binds warns: a typo must
+    // not be an input that types into the void
     if (Object.keys(models).length) {
       // each mistake is warned once per instance, not once per keystroke: an
-      // input emitting a typo'd name would otherwise flood the console on
+      // input updating a typo'd name would otherwise flood the console on
       // every character typed into it
       const warned = new Set<string>()
-      const warnOnce = (key: string, message: string) => {
-        if (warned.has(key)) return
-        warned.add(key)
-        console.warn(message)
-      }
-      instance.on("model:update", (_event, payload) => {
-        if (payload === null || typeof payload !== "object") {
-          warnOnce("payload", `jq79: model:update expects a { name?, value } payload, got ${payload === null ? "null" : typeof payload}`)
-          return
-        }
-        const name = payload.name == null ? "default" : kebabToCamel(String(payload.name))
+      instance.modelWriteback = (rawName, value) => {
+        const name = rawName == null ? "default" : kebabToCamel(String(rawName))
         const expr = models[name]
         if (expr === undefined) {
-          warnOnce(name, `jq79: <${node.tag}> has no ${modelAttr(name)} - bound: ${Object.keys(models).map(modelAttr).join(", ")}`)
-          return
+          if (!warned.has(name)) {
+            warned.add(name)
+            console.warn(`jq79: <${node.tag}> has no ${modelAttr(name)} - bound: ${Object.keys(models).map(modelAttr).join(", ")}`)
+          }
+          return false
         }
-        // untracked, like the tag handlers: a child emitting from its setup
+        if (unassignable.has(name)) return false // already warned, at wiring time
+        // untracked, like the tag handlers: a child updating from its setup
         // script runs inside the parent's *creation* effect, and the reads a
         // path assignment makes (`user` in `user.name = $value`) would land
         // in its deps - donating that effect one wasted (guard-stopped) wake
         // per later write. An imperative writeback is nobody's dependency
-        untracked(() => evalExpr(assignment(expr), scope, { $value: payload.value }))
-      })
+        untracked(() => evalExpr(assignment(expr), scope, { $value: value }))
+        return true
+      }
     }
 
     // @event on the tag listens to this instance's $emit channel (and only
@@ -685,6 +689,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
@@ -815,6 +820,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
@@ -844,7 +884,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
@@ -867,10 +911,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"]
@@ -881,10 +945,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]))
     })
   }
 
@@ -1642,6 +1703,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
@@ -1650,7 +1727,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
@@ -1658,13 +1735,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))
@@ -1686,6 +1763,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
@@ -1902,6 +2003,13 @@ export class Component79 {
   // and every render reads it from here: a hot reload re-renders from a data
   // snapshot, which a symbol on the store would not survive
   slots?: SlotMap
+  // the writeback half of :model, same story: the function that assigns into
+  // the parent, set by renderNestedComponent before the first render and
+  // called by this instance's $updateModel. Kept outside the render generation
+  // so it survives re-render and hot reload. Absent means no :model on the tag
+  // (or no tag at all - a root mount), which makes every $updateModel a no-op.
+  // Internal: set by the usage site, not part of the public API
+  modelWriteback?: (name: string | undefined, value: any) => boolean
 
   data: ReactiveDeepData<Record<string, any>> | null = null
 
@@ -2094,7 +2202,16 @@ export class Component79 {
     // event is cancelable so preventDefault() - from either channel - flips
     // the return to false, telling the emitting child "the parent vetoed"
     const marker = this.startMarker
+    // model:update used to be the writeback's event name; it is a direct call
+    // now ($updateModel), so an emit under that name reaches nothing. Said
+    // once per generation rather than per keystroke, and said at all because
+    // the alternative is a child whose edits silently stop arriving
+    let warnedModelUpdate = false
     const $emit = (eventName: string, payload?: any): boolean => {
+      if (eventName === "model:update" && !warnedModelUpdate) {
+        warnedModelUpdate = true
+        console.warn("jq79: $emit('model:update', …) no longer feeds :model - call $updateModel(value) or $updateModel(name, value) instead")
+      }
       const event = new CustomEvent(eventName, { detail: payload, bubbles: true, composed: true, cancelable: true })
       if (marker === this.startMarker) {
         this.emitListeners.get(eventName)?.forEach(listener => listener(event, payload))
@@ -2141,17 +2258,35 @@ export class Component79 {
     const $import = (url: string): Promise<any> =>
       modules && url in modules ? Promise.resolve(modules[url]) : importResource(url)
 
+    // the writeback half of :model, from the child's side: one argument is the
+    // value for the default model (the bare :model), two are a name and a
+    // value. Arity is what tells them apart, so the value is never inspected -
+    // an object with `name`/`value` keys is just a value, which is exactly
+    // what a payload-shaped contract could not promise. Returns whether a
+    // bound model took it; no :model at the usage site is a silent no-op,
+    // since a child may be designed to work bound or unbound
+    const $updateModel = (...args: [value?: any] | [name: string, value: any]): boolean => {
+      const [name, value] = args.length > 1 ? args as [string, any] : [undefined, args[0]]
+      // the same stale-generation guard $emit has: destroy() nulls the marker,
+      // so a closure the old child leaked (a timer, a registered callback)
+      // cannot keep writing a parent that replaced it
+      if (marker !== this.startMarker) return false
+      return this.modelWriteback?.(name, value) ?? false
+    }
+
     // the names a component answers on top of its store: $emit, so an inline
     // handler can emit without routing through a setup function
-    // (@input="$emit('update', $event.target.value)"), and $slots, the static
-    // map of the names the usage site filled, so a wrapper can be dropped when
-    // nothing filled it (<footer :if="$slots.footer">). Both reach the
+    // (@input="$emit('update', $event.target.value)"), $updateModel, the
+    // writeback a :model binding listens for, and $slots, the static map of
+    // the names the usage site filled, so a wrapper can be dropped when
+    // nothing filled it (<footer :if="$slots.footer">). All reach the
     // template (through templateScope, below) and both script modes (as
-    // instance helpers), and a same-named store key shadows either.
+    // instance helpers), and a same-named store key shadows any of them.
     // Null-prototype, for the same reason storeApi is: `key in injected` must
     // not start answering true for toString, constructor and the rest
     const injected: Record<string, any> = Object.assign(Object.create(null), {
       $emit,
+      $updateModel,
       $slots: Object.fromEntries(Object.keys(this.slots ?? {}).map(name => [name, true])),
     })
 
@@ -2179,7 +2314,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 })