jq79 0.4.17 → 0.5.0

package/package.json

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

@@ -182,6 +182,12 @@ const wireTagEvent = (instance: Component79, attr: string, expr: string, scope:
 
 const kebabToCamel = (name: string) => name.replace(/-(\w)/g, (_, c: string) => c.toUpperCase())
 
+// the inverse, used only by the pre-parse name rewrite (see expandNameCase):
+// uppercase ASCII letters only, never digits - `:props.0` is a generated
+// attribute name and splitting on digits would mangle it. Round-trips through
+// kebabToCamel, acronyms included: userID -> user-i-d -> userID
+const camelToKebab = (name: string) => name.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)
+
 // the stable boundaries of a rendered chunk. An element is its own handle, but
 // a fragment (a nested component: two anchors with the instance's DOM between
 // them) empties itself into the parent on insertion - after that its identity
@@ -289,10 +295,11 @@ type SlotMap = Record<string, SlotRenderer>
 // nested component is handed
 const SLOTS = Symbol("jq79.slots")
 
-// <slot>, <slot.header-bar>: the hole and its name. Names are kebab-case where
-// written (the HTML parser lowercases tag names and attribute modifiers alike)
-// and camelCase where read - <slot.header-bar> is :slot.header-bar is
-// $slots.headerBar
+// <slot>, <slot.header-bar>: the hole and its name. Names arrive kebab-case
+// whichever way they were authored (the HTML parser lowercases tag names and
+// attribute modifiers alike, so expandNameCase normalizes camelCase to kebab
+// before parsing) and are camelCase where read - <slot.header-bar> and
+// <slot.headerBar> are :slot.header-bar is $slots.headerBar
 const isSlotTag = (tag: string): boolean => tag === "slot" || tag.startsWith("slot.")
 
 const slotName = (suffix: string): string => (suffix ? kebabToCamel(suffix) : "default")
@@ -515,8 +522,8 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     } else if (attr === ":model" || attr.startsWith(":model.")) {
       // :model[.name]="expr" - two-way: a prop down plus a writeback listener
       // (wired below, once the instance exists). The modifier arrives
-      // lowercased from the HTML parser, so names are declared kebab-case;
-      // the bare :model binds the name "default"
+      // kebab-case whichever way it was authored (expandNameCase rewrote any
+      // camelCase before parsing); the bare :model binds the name "default"
       const name = attr === ":model" ? "default" : kebabToCamel(attr.slice(":model.".length))
       models[name] = value || (attr === ":model" ? "model" : name)
     } else if (attr.startsWith(":")) {
@@ -543,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) {
@@ -552,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`)
     }
   })
@@ -633,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
@@ -673,7 +684,12 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     // explicit re-emit)
     events.forEach(([attr, expr]) => wireTagEvent(instance, attr, expr, scope))
 
-    const seed = untracked(resolveProps)
+    // what this component actually takes, decided by its signature. Applied to
+    // every path that writes a prop - the seed here and both sync paths below -
+    // or an undeclared name would be filtered on the first render and reappear
+    // on the next update
+    const declared = declaredPropSet(instance.scripts)
+    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
     // they style, and the parent's shadow root is what scopes both
@@ -709,7 +725,7 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     if (hasSpread) {
       let written: string[] = []
       syncFx.effect(() => {
-        const next = resolveProps()
+        const next = pickDeclared(resolveProps(), declared)
         const nextKeys = Object.keys(next)
         written.forEach(key => { if (!(key in next)) (instance.data as Record<string, any>)[key] = undefined })
         nextKeys.forEach(key => { (instance.data as Record<string, any>)[key] = next[key] })
@@ -717,6 +733,7 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
       })
     } else {
       Object.entries(props).forEach(([name, expr]) => {
+        if (declared !== null && !declared.has(name)) return
         syncFx.effect(() => { (instance.data as Record<string, any>)[name] = evalExpr(expr, scope) })
       })
     }
@@ -1277,6 +1294,53 @@ const expandPropsSpread = (src: string): string =>
     )
     .join("")
 
+// a `:`-prefixed attribute name in name position, and a </slot.name> closing
+// tag. Both quote-aware for the same reason ATTR_SPREAD_RE is: a colon inside
+// a value (@click="a ? b : c", style="color: red") is not an attribute name
+const ATTR_NAME_RE = /"[^"]*"|'[^']*'|(^|\s)(:[\w.$-]+)/g
+const CLOSE_SLOT_RE = /<\/slot\.([\w.$-]+)(\s*)>/gi
+const SLOT_TAG_RE = /^slot\./i
+
+// camelCase -> kebab-case for every name the HTML parser would lowercase,
+// BEFORE it gets the chance: `:firstName` would arrive as `:firstname` and
+// kebabToCamel (which is what reads these names back out) would have nothing
+// to un-kebab, so the prop, model or slot would silently land under the wrong
+// key. Rewriting to `:first-name` here means both spellings converge on the
+// same camelCase name downstream - the author picks, the runtime doesn't care.
+//
+// Runs FIRST among the pre-parse passes, which is what keeps it simple: it
+// never sees the `:props.<n>` that expandPropsSpread generates, and a
+// <slot.firstName /> is still one occurrence rather than the open+close pair
+// expandSelfClosingTags turns it into. Same defenses as the passes after it -
+// <script>/<style> bodies split out, only start-tag interiors scanned, quoted
+// values consumed whole.
+//
+// Two name positions, not one: attribute names (`:model.firstName`) and the
+// dotted tag names (`<slot.firstName>`), whose closing halves are rewritten
+// too or the parser sees a mismatched pair. Component tags are deliberately
+// left alone - findComponentKey already matches them case-insensitively with
+// dashes stripped, so <UserCard> needs no help and rewriting it would only
+// obscure what the author wrote
+const kebabTagName = (tag: string): string =>
+  SLOT_TAG_RE.test(tag) ? `slot.${camelToKebab(tag.slice("slot.".length))}` : tag
+
+const expandNameCase = (src: string): string =>
+  src
+    .split(RAW_BLOCK_RE)
+    .map((chunk, i) =>
+      i % 2 === 1
+        ? chunk
+        : chunk
+            .replace(OPEN_TAG_RE, (_match, tag: string, attrs: string) => {
+              const rewritten = attrs.replace(ATTR_NAME_RE, (whole, space: string | undefined, name: string | undefined) =>
+                name === undefined ? whole : `${space}${camelToKebab(name)}`
+              )
+              return `<${kebabTagName(tag)}${rewritten}>`
+            })
+            .replace(CLOSE_SLOT_RE, (_match, suffix: string, space: string) => `</slot.${camelToKebab(suffix)}${space}>`)
+    )
+    .join("")
+
 // <style scoped> support. Every element of the component's own template is
 // stamped with data-jq79="<hash>" and the style's selectors are rewritten to
 // require that attribute, so its rules can't reach anything the component
@@ -1367,10 +1431,13 @@ const parseComponentString = (component: string): ComponentParts => {
   // </style>
 
   // parsed as the content of a <template> so leading <script>/<style> tags
-  // aren't reparented into <head> by the HTML parser. Both pre-DOM string
-  // rewrites run here: `...expr` -> :props.<n>="expr" first (it reads the raw
-  // camelCase before the parser can lowercase names), then self-closing tags
-  const prepared = expandSelfClosingTags(expandPropsSpread(component))
+  // aren't reparented into <head> by the HTML parser. All three pre-DOM string
+  // rewrites run here, and the order is load-bearing: camelCase names ->
+  // kebab-case first (before `:props.<n>` exists to be mangled and while a
+  // self-closing tag is still one occurrence), then `...expr` -> :props.<n>
+  // (which reads the raw camelCase before the parser can lowercase names),
+  // then self-closing tags
+  const prepared = expandSelfClosingTags(expandPropsSpread(expandNameCase(component)))
   const parsedDOM = new DOMParser().parseFromString(`<template>${prepared}</template>`, "text/html")
   const root = parsedDOM.querySelector("template") as HTMLTemplateElement
 
@@ -1593,6 +1660,36 @@ const declaredPropNames = (scripts: TagBlock[]): Set<string> => {
   return names
 }
 
+// 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
+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"])
+    if (!declarations) return
+    const into = (names ??= new Set())
+    declarations.forEach(({ name }) => into.add(name))
+  })
+  return names
+}
+
+// drops the props a component didn't declare, so an undeclared name is simply
+// absent from its store rather than quietly present: `{{ label }}` renders
+// empty and `{{ user.name }}` throws on the member access, both at the usage
+// site that got the name wrong. A null signature keeps everything - see
+// declaredPropSet. Silent by design: the main source of extra keys is a
+// `:props` spread of an object wider than the component (`...sdk`), where
+// taking only the declared few is the point, not a mistake to report
+const pickDeclared = (props: Record<string, any>, declared: Set<string> | null): Record<string, any> => {
+  if (declared === null) return props
+  const out: Record<string, any> = {}
+  Object.keys(props).forEach(key => { if (declared.has(key)) out[key] = props[key] })
+  return out
+}
+
 // 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
@@ -1809,6 +1906,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
 
@@ -2001,7 +2105,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))
@@ -2048,17 +2161,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])),
     })