jq79 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jq79",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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/dom.ts

@@ -65,12 +65,77 @@ export function isSafeUrl(value: string): boolean {
   }
 }
 
+// la política de destinos: decide si un href/src ya seguro por protocolo
+// puede apuntar a donde apunta. Restringe *sobre* el chequeo de protocolo,
+// nunca en su lugar
+export type AllowUrl = (url: URL, tag: string, attr: string) => boolean;
+
+export type SanitizeOptions = { allowUrl?: AllowUrl };
+
+const DEFAULT_PORTS: Record<string, string> = { 'https:': '443', 'http:': '80' };
+
+type HostPattern = { host: RegExp; port: string | null };
+
+// "host[:puerto]": `*` casa exactamente UNA etiqueta dns - la regla de los
+// certificados TLS, no la de CSP: *.germade.dev casa a.germade.dev, pero ni
+// germade.dev (escribe los dos para incluir el apex) ni a.b.germade.dev.
+// Sin puerto casa cualquiera; un patrón inválido devuelve null y no casa
+// nada - una política rota cierra, no abre
+function compileHostPattern(pattern: string): HostPattern | null {
+  const match = pattern.trim().toLowerCase().match(/^([a-z\d*][a-z\d.*-]*?)(?::(\d{1,5}|\*))?$/);
+  if (!match) return null;
+  const [, host, port] = match;
+  const labels = host.split('.');
+  if (labels.some(label => label !== '*' && !/^[a-z\d-]+$/.test(label))) return null;
+  // las etiquetas validadas no llevan metacaracteres de regex, así que no
+  // hay nada que escapar; los puntos los pone el join
+  const re = new RegExp(`^${labels.map(label => (label === '*' ? '[^.]+' : label)).join('\\.')}$`);
+  return { host: re, port: !port || port === '*' ? null : port };
+}
+
+// compila una lista de patrones (string separado por comas, o array) en un
+// predicado AllowUrl. El puerto comparado es el *efectivo* de la URL (el
+// explícito, o el del esquema), así "germade.dev:443" casa https://germade.dev.
+// Una URL sin host (mailto:) no casa ningún patrón: los patrones hablan de
+// hosts - la forma función de la política puede admitirla si quiere
+export const allowedHosts = (patterns: string | string[]): AllowUrl => {
+  const compiled = (Array.isArray(patterns) ? patterns : patterns.split(','))
+    .map(compileHostPattern)
+    .filter((p): p is HostPattern => p !== null);
+  return url => {
+    const host = url.hostname.toLowerCase();
+    const port = url.port || DEFAULT_PORTS[url.protocol] || '';
+    return compiled.some(p => p.host.test(host) && (p.port === null || p.port === port));
+  };
+};
+
+// consulta la política con la URL resuelta contra la página, para que una
+// URL relativa se juzgue como el destino same-origin que realmente es. Un
+// predicado que lanza, o una URL que no parsea, es un no
+function consultAllowUrl(allowUrl: AllowUrl, value: string, tag: string, attr: string): boolean {
+  try {
+    return !!allowUrl(new URL(value, document.baseURI), tag, attr);
+  } catch {
+    return false;
+  }
+}
+
+// el saneado es recursivo, así que la profundidad del input es profundidad
+// de pila. 512 es lo que toleran los parsers de los navegadores antes de
+// aplanar el anidamiento, con lo que ningún documento legítimo pierde nada -
+// y superar el límite lanza un RangeError con nombre, en vez de reventar la
+// pila en algún punto indeterminado más arriba
+const MAX_SANITIZE_DEPTH = 512;
+
 // copia los hijos de `source` en `target`, saneando los elementos y clonando
 // el texto; cualquier otra cosa (comentarios, etc.) se descarta
-function appendSanitizedChildren(source: ParentNode, target: HTMLElement): void {
+function appendSanitizedChildren(source: ParentNode, target: HTMLElement, depth: number, allowUrl?: AllowUrl): void {
+  if (depth > MAX_SANITIZE_DEPTH) {
+    throw new RangeError(`jq79: sanitizeHTML input nests deeper than ${MAX_SANITIZE_DEPTH} elements`);
+  }
   for (const child of Array.from(source.childNodes)) {
     if (child.nodeType === Node.ELEMENT_NODE) {
-      const sanitizedChild = sanitizeNode(child as HTMLElement);
+      const sanitizedChild = sanitizeNode(child as HTMLElement, depth, allowUrl);
       if (sanitizedChild) target.appendChild(sanitizedChild);
     } else if (child.nodeType === Node.TEXT_NODE) {
       target.appendChild(child.cloneNode());
@@ -79,7 +144,7 @@ function appendSanitizedChildren(source: ParentNode, target: HTMLElement): void
 }
 
 // sanea un elemento (los llamadores solo pasan nodos ELEMENT_NODE)
-function sanitizeNode(node: HTMLElement): HTMLElement | null {
+function sanitizeNode(node: HTMLElement, depth: number, allowUrl?: AllowUrl): HTMLElement | null {
   const tag = node.tagName.toLowerCase();
   if (!ALLOWED_TAGS.has(tag)) return null; // tag no permitido → se descarta el nodo entero
 
@@ -91,7 +156,10 @@ function sanitizeNode(node: HTMLElement): HTMLElement | null {
     const allowedGlobal = ALLOWED_ATTR['*']?.has(name);
     if (!allowedForTag && !allowedGlobal) continue;
 
-    if ((name === 'href' || name === 'src') && !isSafeUrl(attr.value)) continue;
+    if (name === 'href' || name === 'src') {
+      if (!isSafeUrl(attr.value)) continue;
+      if (allowUrl && !consultAllowUrl(allowUrl, attr.value, tag, name)) continue;
+    }
 
     clean.setAttribute(name, attr.value);
   }
@@ -99,16 +167,16 @@ function sanitizeNode(node: HTMLElement): HTMLElement | null {
   // fuerza rel seguro en enlaces (target nunca se copia: no está permitido)
   if (tag === 'a') clean.setAttribute('rel', 'noopener noreferrer');
 
-  appendSanitizedChildren(node, clean);
+  appendSanitizedChildren(node, clean, depth + 1, allowUrl);
 
   return clean;
 }
 
-export function sanitizeHTML(html: string): string {
+export function sanitizeHTML(html: string, options?: SanitizeOptions): string {
   const doc = new DOMParser().parseFromString(html, 'text/html');
   const container = document.createElement('div');
 
-  appendSanitizedChildren(doc.body, container);
+  appendSanitizedChildren(doc.body, container, 0, options?.allowUrl);
 
   return container.innerHTML;
 }

package/src/jq79.ts

@@ -1,5 +1,6 @@
 
-import { $, $$, $create, sanitizeHTML } from "./dom"
+import { $, $$, $create, sanitizeHTML, allowedHosts } from "./dom"
+import type { AllowUrl } from "./dom"
 import { $reactive, untracked, createEffectScope } from "./reactive"
 import type { ReactiveDeepData, EffectScope } from "./reactive"
 import { transformSetupScript, transformFactoryScript, parsePropsPattern, parseFactoryProps, type PropDecl } from "./transform"
@@ -66,7 +67,11 @@ const compileExpr = (expr: string, params: string[]): Function | null => {
   let fn = compiled.get(key)
   if (fn === undefined) {
     try {
-      fn = new Function("$scope", ...params, `with ($scope) { return (${expr}); }`)
+      // the newline before `)` ends a trailing line comment in the
+      // expression ({{ msg // greeting }}); ASI doesn't apply inside parens,
+      // so everything else is untouched. Without it the comment eats the
+      // rest of this single-line body and the expression never compiles
+      fn = new Function("$scope", ...params, `with ($scope) { return (${expr}\n); }`)
     } catch {
       fn = null // a syntax error: it will never compile, so don't try again
     }
@@ -91,7 +96,7 @@ const interpolate = (template: string, scope: Record<string, any>): string =>
   template.replace(/{{\s*([\s\S]+?)\s*}}/g, (_, expr) => evalExpr(expr, scope) ?? "")
 
 
-const CONTROL_ATTRS = new Set([":attrs", ":class", ":if", ":elseif", ":else", ":each", ":key", ":with", ":text", ":html"])
+const CONTROL_ATTRS = new Set([":attrs", ":class", ":value", ":checked", ":selected", ":if", ":elseif", ":else", ":each", ":key", ":with", ":text", ":html", ":html.allowed"])
 // `item in items`, `item, i in items`, `(value, key) in props` - the second
 // binding is the array index or the object key, parens optional (Vue-style).
 // The list expression can span lines, so it matches [\s\S] rather than `.`
@@ -120,6 +125,39 @@ const bindEvent = (el: Element, attr: string, expr: string, scope: Record<string
   }, { once: mods.has("once"), capture: mods.has("capture") })
 }
 
+// @event on a component tag: the tag renders as comment anchors, so there is
+// no element to listen on - the attribute subscribes to the child instance's
+// $emit channel (instance.on) instead, which survives the child's re-renders
+// and works detached. Native DOM events from the child's inner DOM never
+// arrive here: they bubble past the anchors to shared ancestors (a listener
+// on a wrapping element hears those); a child that wants its native event
+// heard on its tag re-emits it. .prevent flips the child's $emit() return to
+// false, .stop keeps the emit off the DOM dispatch, .once unsubscribes after
+// one call; .self and .capture have no meaning on this channel and are ignored
+const wireTagEvent = (instance: Component79, attr: string, expr: string, scope: Record<string, any>) => {
+  const [name, ...modifiers] = attr.slice(1).split(".")
+  const mods = new Set(modifiers)
+
+  const listener = (event: CustomEvent) => {
+    if (mods.has("prevent")) event.preventDefault()
+    if (mods.has("stop")) event.stopPropagation()
+    if (mods.has("once")) instance.off(name, listener)
+
+    // untracked, so a tag handler behaves like an element handler no matter
+    // when the emit fires: an element handler never runs inside an effect,
+    // but $emit can (a $: that emits, a setup-script emit inside the parent's
+    // creation effect), and the handler's reads would land in that effect's
+    // deps. Today that is contained - cross-store deps are never notified,
+    // and the creation effect's definition guard no-ops a spurious wake - but
+    // "what a handler reads is nobody's dependency" shouldn't hinge on either
+    untracked(() => {
+      const handler = evalExpr(expr, scope, { $event: event })
+      if (typeof handler === "function") handler(event)
+    })
+  }
+  instance.on(name, listener)
+}
+
 const kebabToCamel = (name: string) => name.replace(/-(\w)/g, (_, c: string) => c.toUpperCase())
 
 // the stable boundaries of a rendered chunk. An element is its own handle, but
@@ -195,11 +233,22 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
   wrapper.append(anchor, endAnchor)
 
   const props: Record<string, string> = {} // prop name -> expression in parent scope
+  const models: Record<string, string> = {} // model name -> assignable expression in parent scope
+  const events: Array<[string, string]> = [] // @attr (modifiers included) -> handler expression
   Object.entries(node.attrs).forEach(([attr, value]) => {
     // the parent's scope stamp is stamped on every template element, this tag
     // included - it's not a prop, and the child renders under its own scope
-    if (attr === SCOPE_ATTR || CONTROL_ATTRS.has(attr) || attr.startsWith("@")) return
-    if (attr.startsWith(":")) {
+    if (attr === SCOPE_ATTR || CONTROL_ATTRS.has(attr)) return
+    if (attr.startsWith("@")) {
+      events.push([attr, value])
+    } 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"
+      const name = attr === ":model" ? "default" : kebabToCamel(attr.slice(":model.".length))
+      models[name] = value || (attr === ":model" ? "model" : name)
+    } else if (attr.startsWith(":")) {
       const name = kebabToCamel(attr.slice(1))
       props[name] = value || name
     } else {
@@ -207,6 +256,31 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     }
   })
 
+  // each model is also a prop down: the child reads the value under the
+  // model's name - `model` for the default, because a prop named `default`
+  // could never be read from a child expression (reserved word). Without the
+  // prop this isn't two-way, it's upward collection: a parent reset or an
+  // initial value would never reach the child
+  const modelAttr = (name: string) => (name === "default" ? ":model" : `:model.${name}`)
+  const modelProp = (name: string) => (name === "default" ? "model" : name)
+  // the newline keeps `= $value` out of a trailing line comment in the
+  // expression (:model="uname // the username") - glued on the same line,
+  // 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`
+  Object.entries(models).forEach(([name, expr]) => {
+    const prop = modelProp(name)
+    if (props[prop] !== undefined) {
+      console.warn(`jq79: <${node.tag}> binds prop "${prop}" through both :${prop} and ${modelAttr(name)} - ${modelAttr(name)} wins`)
+    }
+    props[prop] = expr
+    // 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) {
+      console.warn(`jq79: ${modelAttr(name)}="${expr}" is not assignable - updates from <${node.tag}> will be dropped`)
+    }
+  })
+
   let current: Component79 | null = null
   let currentDef: Component79 | null = null
   let childFx: EffectScope | null = null
@@ -232,6 +306,46 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
       modules: nextDef.modules,
       filename: nextDef.filename,
     })
+    // 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
+    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
+      // 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))
+        const expr = models[name]
+        if (expr === undefined) {
+          warnOnce(name, `jq79: <${node.tag}> has no ${modelAttr(name)} - bound: ${Object.keys(models).map(modelAttr).join(", ")}`)
+          return
+        }
+        // untracked, like the tag handlers: a child emitting 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 }))
+      })
+    }
+
+    // @event on the tag listens to this instance's $emit channel (and only
+    // this instance's - a grandchild's emit arrives here solely as an
+    // explicit re-emit)
+    events.forEach(([attr, expr]) => wireTagEvent(instance, attr, expr, scope))
+
     const seed = untracked(() =>
       Object.fromEntries(Object.entries(props).map(([name, expr]) => [name, evalExpr(expr, scope)]))
     )
@@ -308,6 +422,26 @@ const classNames = (value: any): string[] => {
   return []
 }
 
+// what :html.allowed accepts, normalized to an AllowUrl predicate: host
+// patterns (a comma-separated string or an array - see allowedHosts in
+// ./dom) or a function (url: URL, tag, attr) => boolean. Anything else -
+// including a policy expression that evaluates to undefined - denies every
+// destination: the attribute declares the intent to restrict, so a broken
+// policy fails closed, and so does a predicate that throws
+const normalizeAllowUrl = (policy: any): AllowUrl => {
+  if (typeof policy === "function") {
+    return (url, tag, attr) => {
+      try {
+        return !!policy(url, tag, attr)
+      } catch {
+        return false
+      }
+    }
+  }
+  if (typeof policy === "string" || Array.isArray(policy)) return allowedHosts(policy)
+  return () => false
+}
+
 // 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
@@ -349,7 +483,15 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
 
   Object.entries(node.attrs).forEach(([key, value]) => {
     if (key.startsWith("@")) bindEvent(el, key, value, scope)
-    else if (!CONTROL_ATTRS.has(key)) el.setAttribute(key, value)
+    else if (key === ":model" || key.startsWith(":model.")) {
+      // :model binds component tags only (see TODOS/2026-07-15.model-directive.md;
+      // 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("-"))) {
+        console.warn(`jq79: ${key} on <${node.tag}> does nothing - :model binds component tags only (for now)`)
+      }
+    } else if (!CONTROL_ATTRS.has(key)) el.setAttribute(key, value)
   })
 
   const bindExpr = node.attrs[":attrs"]
@@ -389,17 +531,49 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
   // :text="expr" sets textContent reactively, replacing any children.
   // :html="expr" sets innerHTML reactively, sanitizing the value first so
   // untrusted content can't inject scripts/attributes (see sanitizeHTML in
-  // ./dom). Both skip rendering the element's own children/interpolation
+  // ./dom). Both skip rendering the element's own children/interpolation.
+  // :html.allowed="expr" adds a destination policy for the content's
+  // href/src URLs - evaluated in the same effect, so a policy held in the
+  // store is as reactive as the content itself
   const textExpr = node.attrs[":text"]
   const htmlExpr = node.attrs[":html"]
+  const allowedExpr = node.attrs[":html.allowed"]
+  if (allowedExpr !== undefined && htmlExpr === undefined) {
+    console.warn("jq79: :html.allowed without :html on the same element does nothing")
+  }
   if (textExpr !== undefined) {
     fx.effect(() => { el.textContent = String(evalExpr(textExpr, scope) ?? "") })
   } else if (htmlExpr !== undefined) {
-    fx.effect(() => { el.innerHTML = sanitizeHTML(String(evalExpr(htmlExpr, scope) ?? "")) })
+    fx.effect(() => {
+      const options = allowedExpr !== undefined ? { allowUrl: normalizeAllowUrl(evalExpr(allowedExpr, scope)) } : undefined
+      el.innerHTML = sanitizeHTML(String(evalExpr(htmlExpr, scope) ?? ""), options)
+    })
   } else {
     el.appendChild(renderNodes(node.children, scope, fx, shadow))
   }
 
+  // :value / :checked / :selected write the DOM *property*, not the
+  // attribute - the attribute is only a form control's default, and detaches
+  // the moment the user interacts (which is why :attrs="{ value }" stops
+  // driving a typed-in input). One-way, store -> DOM: the way back stays an
+  // explicit @input/@change. :value skips the write when the property
+  // already holds the string, so an unrelated re-run can't move the caret of
+  // the input the user is typing into. Registered after the children render:
+  // :value on a <select> can only pick an <option> that already exists
+  const valueExpr = node.attrs[":value"]
+  if (valueExpr !== undefined) {
+    fx.effect(() => {
+      const value = String(evalExpr(valueExpr, scope) ?? "")
+      if ((el as HTMLInputElement).value !== value) (el as HTMLInputElement).value = value
+    })
+  }
+  ;([":checked", ":selected"] as const).forEach(attr => {
+    const expr = node.attrs[attr]
+    if (expr === undefined) return
+    const prop = attr.slice(1) as "checked" | "selected"
+    fx.effect(() => { (el as any)[prop] = !!evalExpr(expr, scope) })
+  })
+
   return el
 }
 
@@ -1197,15 +1371,22 @@ export class Component79 {
     // 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
+    // generations from reaching the instance's on() listeners.
+    // The on() channel runs *first* (it's where @event on a component tag is
+    // wired - see wireTagEvent) so its listeners can shape the DOM dispatch:
+    // stopPropagation() there keeps the event off the DOM entirely, and the
+    // event is cancelable so preventDefault() - from either channel - flips
+    // the return to false, telling the emitting child "the parent vetoed"
     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)
+      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))
       }
-      return result
+      // cancelBubble is the spec's legacy name, but it's the only *readable*
+      // accessor for the stop-propagation flag - hence the deprecation hint
+      if (!event.cancelBubble) marker.dispatchEvent(event)
+      return !event.defaultPrevented
     }
 
     // `await $mounted()` suspends a setup script until mount() attaches the
@@ -1271,7 +1452,18 @@ export class Component79 {
     })
 
     const content = document.createDocumentFragment()
-    content.append(this.startMarker, renderNodes(this.template, store, fx, shadow), this.endMarker)
+    // the template renders under a scope that also answers $emit (unless the
+    // store shadows the name), so an inline handler can emit without routing
+    // through a setup function: @input="$emit('update', $event.target.value)".
+    // has/get only - never an own key - so Object.keys, snapshot spreads and
+    // the component-key scan don't see it, and every read still forwards
+    // through the reactive store, keeping dependency tracking intact
+    const templateScope = new Proxy(store as Record<string, any>, {
+      has: (target, key) => key === "$emit" || Reflect.has(target, key),
+      get: (target, key, receiver) =>
+        key === "$emit" && !Reflect.has(target, key) ? $emit : Reflect.get(target, key, receiver),
+    })
+    content.append(this.startMarker, renderNodes(this.template, templateScope, fx, shadow), this.endMarker)
     this.content = content
 
     if (shadow) {