jq79 0.3.30 → 0.3.32

package/dist/transform.d.ts

@@ -3,5 +3,11 @@ type SetupTransform = {
     code: string;
 };
 export declare const transformSetupScript: (src: string) => SetupTransform;
+export type PropDecl = {
+    name: string;
+    default?: string;
+};
+export declare const parsePropsPattern: (pattern: string | undefined) => PropDecl[] | null;
+export declare const parseFactoryProps: (src: string) => PropDecl[] | null;
 export declare const transformFactoryScript: (src: string) => string | null;
 export {};

package/package.json

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

@@ -2,7 +2,7 @@
 import { $, $$, $create, sanitizeHTML } from "./dom"
 import { $reactive, untracked, createEffectScope } from "./reactive"
 import type { ReactiveDeepData, EffectScope } from "./reactive"
-import { transformSetupScript, transformFactoryScript } from "./transform"
+import { transformSetupScript, transformFactoryScript, parsePropsPattern, parseFactoryProps, type PropDecl } from "./transform"
 
 export { $, $$, $create } from "./dom"
 export { $reactive } from "./reactive"
@@ -763,6 +763,25 @@ const runSetupScript = (code: string, scope: Record<string, any>, effect: (run:
   result.catch(error => console.error("jq79: error in :setup script", error))
 }
 
+// puts a component's declared props on the store, before any script runs and
+// before the first render: the names, so the template can bind to them even
+// when the parent passes nothing, and the defaults, so it binds to something.
+//
+// A prop the parent *did* pass is already on the store (render() seeds it), so
+// a default only fills an `undefined` - which is also what JS destructuring
+// does with the same pattern, so both modes agree. It happens once, at setup:
+// re-applying a default later would need an effect that reads and writes the
+// same key, and that effect would wake itself forever.
+//
+// `null` props means the component declared no signature at all, which is not
+// the same as declaring an empty one: it keeps today's permissive behavior
+const declareProps = (store: Record<string, any>, props: PropDecl[] | null) => {
+  props?.forEach(({ name, default: expr }) => {
+    if (store[name] !== undefined) return
+    store[name] = expr === undefined ? undefined : evalExpr(expr, store)
+  })
+}
+
 // default-import interop for factory scripts: real modules expose .default,
 // while importing an .html component resolves to the Component79 itself
 const interopDefault = (mod: any) => (mod && mod.default !== undefined ? mod.default : mod)
@@ -776,7 +795,7 @@ const interopDefault = (mod: any) => (mod && mod.default !== undefined ? mod.def
 // resolve later and the template updates reactively
 const runFactoryScript = (code: string, scope: Record<string, any>, effect: (run: () => void) => void, instanceHelpers: Record<string, any> = {}, importer: (url: string) => Promise<any> = importResource, at: ScriptLocation = {}) => {
   const helpers = { ...SETUP_HELPERS, ...instanceHelpers }
-  const $__exports: { default?: (ctx: Record<string, any>) => any; done?: boolean } = {}
+  const $__exports: { default?: (props: Record<string, any>, ctx: Record<string, any>) => any; done?: boolean } = {}
   const result: Promise<void> = new Function(
     "$__exports", "$__default", "$__import", ...Object.keys(helpers),
     `return (async () => { "use strict";\n${code}\n;$__exports.done = true })()${sourceUrlComment(at.filename, at.index ?? 0)}`
@@ -795,7 +814,10 @@ const runFactoryScript = (code: string, scope: Record<string, any>, effect: (run
     // the sync path is invoked straight from render(), so a throwing factory
     // must be caught here too - not just by the `result` rejection handler
     try {
-      const returned = factory({ $data: scope, $effect: effect, ...instanceHelpers })
+      // props first, ctx second. Both are the store: the pattern destructures
+      // 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)
       else merge(returned)
     } catch (error) {
@@ -1100,11 +1122,13 @@ export class Component79 {
       const at: ScriptLocation = { filename: this.filename, index }
       const factoryCode = transformFactoryScript(script.content)
       if (factoryCode !== null) {
+        declareProps(store, parseFactoryProps(script.content))
         const body = ":mounted" in script.attrs ? defer(factoryCode) : factoryCode
         runFactoryScript(body, store, fx.effect, instanceHelpers, $import, at)
         return
       }
       const { vars, code } = transformSetupScript(script.content)
+      declareProps(store, parsePropsPattern(script.attrs[":setup"]))
       // 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 })

package/src/transform.ts

@@ -235,6 +235,193 @@ const staticImportToAwait = (clause: string | undefined, spec: string, n: number
   return `const ${bindings.join(", ")}`
 }
 
+// ---------------------------------------------------------------------------
+// the component's prop signature
+//
+// A component declares the props it takes as a destructuring pattern, in the
+// place each script mode already puts its inputs: the `:setup` attribute's
+// value, or the factory's *first* parameter (the ctx moved to the second).
+// Position is fixed, so the signature is read straight from the source string -
+// no parser, no execution - and the runtime can seed the defaults on the store
+// before the first render, which is what makes them reach the template even in
+// factory mode (where JS would only apply them inside the function body).
+//
+//   <script :setup="{ label = 'Total', step = 1 }">
+//   export default ({ label = "Total" }, { $data }) => {}
+//
+// An object pattern *is* the declaration; anything else (`_`, a plain
+// identifier, no attribute at all) declares nothing and stays permissive.
+// ---------------------------------------------------------------------------
+
+export type PropDecl = { name: string; default?: string }
+
+const IDENTIFIER_RE = /^[A-Za-z_$][\w$]*$/
+
+// index of the first `ch` at bracket depth 0, skipping strings and comments
+const indexOfTopLevel = (src: string, ch: string): number => {
+  let depth = 0
+  let i = 0
+  while (i < src.length) {
+    const c = src[i]
+    if (c === "'" || c === '"' || c === "`") { i = skipString(src, i); continue }
+    if (c === "/" && src[i + 1] === "/") { i = skipLineComment(src, i); continue }
+    if (c === "/" && src[i + 1] === "*") { i = skipBlockComment(src, i); continue }
+    if ("([{".includes(c)) depth++
+    else if (")]}".includes(c)) depth--
+    else if (depth === 0 && c === ch) return i
+    i++
+  }
+  return -1
+}
+
+const splitTopLevel = (src: string): string[] => {
+  const parts: string[] = []
+  let depth = 0
+  let start = 0
+  let i = 0
+  while (i <= src.length) {
+    const ch = src[i]
+    if (ch === "'" || ch === '"' || ch === "`") { i = skipString(src, i); continue }
+    if (ch === "/" && src[i + 1] === "/") { i = skipLineComment(src, i); continue }
+    if (ch === "/" && src[i + 1] === "*") { i = skipBlockComment(src, i); continue }
+    if (ch !== undefined && "([{".includes(ch)) depth++
+    else if (ch !== undefined && ")]}".includes(ch)) depth--
+    else if (i === src.length || (ch === "," && depth === 0)) {
+      const part = src.slice(start, i).trim()
+      if (part) parts.push(part)
+      start = i + 1
+    }
+    i++
+  }
+  return parts
+}
+
+// the `=` that opens a default value: the first one at depth 0 that isn't part
+// of `==`/`===` or an arrow's `=>` (so `{ format = a => a }` keeps its default)
+const defaultAssignIndex = (src: string): number => {
+  let from = 0
+  while (from < src.length) {
+    const at = indexOfTopLevel(src.slice(from), "=")
+    if (at === -1) return -1
+    const i = from + at
+    if (src[i + 1] !== "=" && src[i + 1] !== ">" && src[i - 1] !== "=" && src[i - 1] !== "!") return i
+    from = i + 1
+  }
+  return -1
+}
+
+// a destructuring pattern -> the props it declares. null means "no signature":
+// the pattern isn't an object one (`_`, `props`, nothing at all), so the
+// component declares nothing and keeps the permissive, undeclared behavior.
+// `{}` parses to [] - a closed signature that declares zero props
+export const parsePropsPattern = (pattern: string | undefined): PropDecl[] | null => {
+  const src = (pattern ?? "").trim()
+  if (!src.startsWith("{")) return null
+
+  // to the `}` that closes the pattern, so a parameter's own default value
+  // (`({ label } = {})`) is left out of it
+  let depth = 0
+  let close = 0
+  while (close < src.length) {
+    const ch = src[close]
+    if (ch === "'" || ch === '"' || ch === "`") { close = skipString(src, close); continue }
+    if ("([{".includes(ch)) depth++
+    else if (")]}".includes(ch) && --depth === 0) break
+    close++
+  }
+  if (close >= src.length) return null // unbalanced: not a pattern we can read
+
+  const props: PropDecl[] = []
+  for (const part of splitTopLevel(src.slice(1, close))) {
+    if (part.startsWith("...")) continue // a rest element names no prop
+    const assign = defaultAssignIndex(part)
+    const named = assign === -1 ? part : part.slice(0, assign)
+    const fallback = assign === -1 ? undefined : part.slice(assign + 1).trim()
+    // `{ user: { id } }` and `{ user: renamed }` both declare `user`: what the
+    // store holds is the key, whatever the pattern binds it to
+    const colon = indexOfTopLevel(named, ":")
+    const name = (colon === -1 ? named : named.slice(0, colon)).trim()
+    if (!IDENTIFIER_RE.test(name)) continue
+    props.push(fallback === undefined ? { name } : { name, default: fallback })
+  }
+  return props
+}
+
+// index just past a top-level `export default`, or -1
+const findExportDefault = (src: string): number => {
+  let i = 0
+  let depth = 0
+  let atStatementStart = true
+  while (i < src.length) {
+    const ch = src[i]
+    if (ch === "'" || ch === '"' || ch === "`") { i = skipString(src, i); atStatementStart = false; continue }
+    if (ch === "/" && src[i + 1] === "/") { i = skipLineComment(src, i); continue }
+    if (ch === "/" && src[i + 1] === "*") { i = skipBlockComment(src, i); continue }
+
+    if (ch === "e" && depth === 0 && atStatementStart && (i === 0 || !/[\w$.]/.test(src[i - 1]))) {
+      EXPORT_DEFAULT_RE.lastIndex = i
+      const found = EXPORT_DEFAULT_RE.exec(src)
+      if (found) return i + found[0].length
+    }
+
+    if ("([{".includes(ch)) depth++
+    else if (")]}".includes(ch)) depth = Math.max(0, depth - 1)
+    if (ch === "\n" || ch === ";" || ch === "}") atStatementStart = true
+    else if (!/\s/.test(ch)) atStatementStart = false
+    i++
+  }
+  return -1
+}
+
+const ASYNC_RE = /^async(?![\w$])/
+const FUNCTION_RE = /^function(?![\w$])\s*\*?\s*[A-Za-z_$][\w$]*|^function(?![\w$])\s*\*?/
+
+// source text of the exported function's first parameter, or null when there
+// is no parameter list to read (`export default Factory`, `export default
+// props => ...`, an exported object) - all of which declare nothing
+const firstParameterSource = (src: string): string | null => {
+  const start = findExportDefault(src)
+  if (start === -1) return null
+
+  let i = skipToToken(src, start)
+  const rest = src.slice(i)
+  if (ASYNC_RE.test(rest)) i = skipToToken(src, i + "async".length)
+  const fn = FUNCTION_RE.exec(src.slice(i))
+  if (fn) i = skipToToken(src, i + fn[0].length)
+  if (src[i] !== "(") return null
+
+  // the parameter list runs to the `)` that closes this `(`
+  let depth = 0
+  let end = i
+  while (end < src.length) {
+    const ch = src[end]
+    if (ch === "'" || ch === '"' || ch === "`") { end = skipString(src, end); continue }
+    if ("([{".includes(ch)) depth++
+    else if (")]}".includes(ch) && --depth === 0) break
+    end++
+  }
+  return splitTopLevel(src.slice(i + 1, end))[0] ?? ""
+}
+
+// the props declared by a factory script's first parameter. Throws the
+// migration error when it finds the pre-0.4 signature there - the ctx used to
+// be the first parameter, and the change is silent otherwise ($data would just
+// come back undefined). `$` is what tells them apart: what carries one comes
+// from the library, what doesn't comes from the parent, everywhere in jq79
+export const parseFactoryProps = (src: string): PropDecl[] | null => {
+  const first = firstParameterSource(src)
+  if (first === null) return null
+  const props = parsePropsPattern(first)
+  const ctxName = props?.find(prop => prop.name.startsWith("$"))?.name
+  if (ctxName) {
+    throw new Error(
+      `jq79: the factory signature is (props, ctx), so \`${ctxName}\` can't be destructured from the first parameter. ` +
+      `Write \`export default (props, { ${ctxName} }) => …\`, or \`_\` in place of props if the component takes none.`
+    )
+  }
+  return props
+}
+
 // rewrites a factory script into a Function body, or returns null when the
 // script has no top-level `export default` (i.e. it's a regular setup script)
 export const transformFactoryScript = (src: string): string | null => {