rip-lang 3.16.0 → 3.16.1

package/src/components.js

@@ -17,7 +17,7 @@ import { HTML_TAGS, SVG_TAGS, TEMPLATE_TAGS } from './generated/dom-tags.js';
 const BIND_PREFIX = '__bind_';
 const BIND_SUFFIX = '__';
 
-const LIFECYCLE_HOOKS = new Set(['beforeMount', 'mounted', 'updated', 'beforeUnmount', 'unmounted', 'onError']);
+const LIFECYCLE_HOOKS = new Set(['beforeMount', 'mounted', 'beforeUnmount', 'unmounted', 'onError']);
 const BOOLEAN_ATTRS = new Set([
   'disabled', 'hidden', 'readonly', 'required', 'checked', 'selected',
   'autofocus', 'autoplay', 'controls', 'loop', 'muted', 'multiple',
@@ -79,6 +79,17 @@ function getMemberType(target) {
   return null;
 }
 
+/**
+ * Extract `?` optionality flag from s-expression target node.
+ * Set by the lexer as `.optional` on the prop-name String wrapper when
+ * the source wrote `@label?:: T` or similar.
+ */
+function getMemberOptional(target) {
+  if (target instanceof String && target.optional) return true;
+  if (Array.isArray(target) && target[2] instanceof String && target[2].optional) return true;
+  return false;
+}
+
 // ============================================================================
 // Prototype Installation
 // ============================================================================
@@ -575,9 +586,52 @@ export function installComponentSupport(CodeEmitter, Lexer) {
   const _transferMeta = (from, to) => {
     if (!(from instanceof String)) return to;
     const s = new String(to);
-    if (from.predicate) s.predicate = true;
-    if (from.await) s.await = true;
-    return (s.predicate || s.await) ? s : to;
+    if (from.optional) s.optional = true;
+    if (from.bang) s.bang = true;
+    return (s.optional || s.bang) ? s : to;
+  };
+
+  // Inject `// @rip-src:N` markers onto each statement line of a method body
+  // emitted into a component stub.  The emitter doesn't carry source-map data
+  // for stub method bodies, so without explicit markers, typecheck.js falls
+  // back to linear gap-fill interpolation which silently misaligns when stub
+  // sizes change.  Walks the body s-expression to recover statement source
+  // lines and pairs them with the rendered body's non-trivial lines.
+  proto.addBodyRipSrcMarkers = function(bodyCode, bodySexpr) {
+    if (typeof bodyCode !== 'string' || !bodyCode) return bodyCode;
+    const stmts = Array.isArray(bodySexpr) && bodySexpr[0] === 'block'
+      ? bodySexpr.slice(1)
+      : (Array.isArray(bodySexpr) ? [bodySexpr] : []);
+    if (stmts.length === 0) return bodyCode;
+    const getLoc = (s) => {
+      if (s == null) return null;
+      if (!Array.isArray(s)) return s?.loc?.r ?? null;
+      if (s.loc?.r) return s.loc.r;
+      if (s[0]?.loc?.r) return s[0].loc.r;
+      for (const child of s) {
+        if (child?.loc?.r) return child.loc.r;
+        if (Array.isArray(child)) {
+          const l = getLoc(child);
+          if (l != null) return l;
+        }
+      }
+      return null;
+    };
+    const srcLines = stmts.map(getLoc);
+    if (srcLines.every(l => l == null)) return bodyCode;
+    const lines = bodyCode.split('\n');
+    let si = 0;
+    for (let i = 0; i < lines.length && si < srcLines.length; i++) {
+      const trimmed = lines[i].trim();
+      if (!trimmed) continue;
+      if (trimmed === '{' || trimmed === '}' || trimmed.startsWith('//')) continue;
+      if (lines[i].includes('@rip-src:')) { si++; continue; }
+      if (srcLines[si] != null) {
+        lines[i] = `${lines[i]} // @rip-src:${srcLines[si]}`;
+      }
+      si++;
+    }
+    return lines.join('\n');
   };
 
   proto.transformComponentMembers = function(sexpr, localScope = new Set()) {
@@ -707,31 +761,35 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           reactiveMembers.add(varName);
         }
       } else if (op === '.' && stmt[1] === 'this' && getMemberName(stmt)) {
-        // Required prop: (. this name) — no default value
+        // Bare prop form: `(. this name)` — no default value.
+        // `@name`     → required (caller must pass)
+        // `@name?`    → optional (caller may omit; value will be undefined)
+        // `@name?:: T`→ optional, typed
         const varName = (typeof stmt[2] === 'string' || stmt[2] instanceof String) ? stmt[2].valueOf() : null;
         if (varName) {
-          stateVars.push({ name: varName, value: undefined, isPublic: true, type: stmt[2]?.type || null, required: true });
+          const optional = getMemberOptional(stmt);
+          stateVars.push({ name: varName, value: undefined, isPublic: true, type: stmt[2]?.type || null, required: !optional, optional, srcLine: stmt.loc?.r });
           memberNames.add(varName);
           reactiveMembers.add(varName);
         }
       } else if (op === 'state') {
         const varName = getMemberName(stmt[1]);
         if (varName) {
-          stateVars.push({ name: varName, value: stmt[2], isPublic: isPublicProp(stmt[1]), type: getMemberType(stmt[1]) });
+          stateVars.push({ name: varName, value: stmt[2], isPublic: isPublicProp(stmt[1]), type: getMemberType(stmt[1]), optional: getMemberOptional(stmt[1]), srcLine: stmt.loc?.r });
           memberNames.add(varName);
           reactiveMembers.add(varName);
         }
       } else if (op === 'computed') {
         const varName = getMemberName(stmt[1]);
         if (varName) {
-          derivedVars.push({ name: varName, expr: stmt[2], type: getMemberType(stmt[1]) });
+          derivedVars.push({ name: varName, expr: stmt[2], type: getMemberType(stmt[1]), srcLine: stmt.loc?.r });
           memberNames.add(varName);
           reactiveMembers.add(varName);
         }
       } else if (op === 'readonly') {
         const varName = getMemberName(stmt[1]);
         if (varName) {
-          readonlyVars.push({ name: varName, value: stmt[2], isPublic: isPublicProp(stmt[1]), type: getMemberType(stmt[1]) });
+          readonlyVars.push({ name: varName, value: stmt[2], isPublic: isPublicProp(stmt[1]), type: getMemberType(stmt[1]), optional: getMemberOptional(stmt[1]), srcLine: stmt.loc?.r });
           memberNames.add(varName);
         }
       } else if (op === '=') {
@@ -745,7 +803,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
               methods.push({ name: varName, func: val });
               memberNames.add(varName);
             } else {
-              stateVars.push({ name: varName, value: val, isPublic: isPublicProp(stmt[1]) });
+              stateVars.push({ name: varName, value: val, isPublic: isPublicProp(stmt[1]), srcLine: stmt.loc?.r });
               memberNames.add(varName);
               reactiveMembers.add(varName);
             }
@@ -804,28 +862,44 @@ export function installComponentSupport(CodeEmitter, Lexer) {
 
     // --- Type-check stub: typed member declarations + body expressions, no DOM ---
     if (this.options.stubComponents) {
-      // Inline type suffix expansion (mirrors types.js expandSuffixes)
-      const expandType = (t) => t ? t.replace(/::/g, ':')
-        .replace(/(\w+(?:<[^>]+>)?)\?\?/g, '$1 | null | undefined')
-        .replace(/(\w+(?:<[^>]+>)?)\?(?![.:])/g, '$1 | undefined')
-        .replace(/(\w+(?:<[^>]+>)?)\!/g, 'NonNullable<$1>') : null;
+      // Strip Rip's `::` annotation sigil to TypeScript's `:` separator.
+      const expandType = (t) => t ? t.replace(/::/g, ':') : null;
 
       const sl = [];
       const componentTypeParams = this._componentTypeParams || '';
       sl.push(`class ${componentTypeParams}{`);
-      // `declare app: any` is rewritten to a typed shape by typecheck.js when
-      // the project has a typed `<root>/app/stash.rip`. The compiler stays
-      // context-free; the rewrite happens in the same pass that splices
-      // function-overload signatures into the stub.
-      sl.push('  declare _root: Element | null; declare app: any;');
+      // Injected `this` shape for every component. The compiler stays
+      // context-free; `declare app: any` and `declare router: any` are
+      // rewritten by typecheck.js to typed shapes when the project anchor /
+      // stash file is discoverable. `params`, `query`, `children`, and the
+      // lifecycle hooks are stable across all projects, so they're typed
+      // here directly. User-defined hooks are emitted later as real methods;
+      // skip the optional-signature declaration for those names to avoid
+      // overload-optionality mismatches.
+      // Combine all injected declarations onto a single line to preserve the
+      // stub's prior line count.  Source-map gap-fill interpolates linearly
+      // between marker lines (e.g. between @rip-src markers from `@count`
+      // and a downstream method), so adding stub header lines pushes the
+      // method bodies past where interpolation expects them — breaking
+      // @ts-expect-error injection.  Keeping a single header line preserves
+      // the relative offsets.
+      sl.push('  declare _root: Element | null; declare app: any; declare router: any; declare params: Record<string, string>; declare query: URLSearchParams; declare children: any;');
+      const userHookNames = new Set(lifecycleHooks.map(h => h.name));
+      const hookDecls = [];
+      if (!userHookNames.has('beforeMount'))   hookDecls.push('beforeMount?(): void;');
+      if (!userHookNames.has('mounted'))       hookDecls.push('mounted?(): void;');
+      if (!userHookNames.has('beforeUnmount')) hookDecls.push('beforeUnmount?(): void;');
+      if (!userHookNames.has('unmounted'))     hookDecls.push('unmounted?(): void;');
+      if (!userHookNames.has('onError'))       hookDecls.push('onError?(err: { status?: number; message?: string; error?: Error; path?: string }): void;');
+      if (hookDecls.length) sl.push('  ' + hookDecls.join(' '));
       sl.push('  emit(_name: string, _detail?: any): void {}');
 
       // Constructor — typed props for public state/readonly (matches DTS)
       const propEntries = [];
-      for (const { name, type, isPublic, required } of stateVars) {
+      for (const { name, type, isPublic, required, optional } of stateVars) {
         if (!isPublic) continue;
         const ts = expandType(type);
-        const opt = required ? '' : '?';
+        const opt = (optional ?? !required) ? '?' : '';
         propEntries.push(`${name}${opt}: ${ts || 'any'}`);
         // Two-way binding: allow parent to pass Signal<T> for this prop
         propEntries.push(`__bind_${name}__?: Signal<${ts || 'any'}>`);
@@ -836,7 +910,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
         propEntries.push(`${name}?: ${ts || 'any'}`);
       }
       {
-        const hasRequired = propEntries.length > 0 && stateVars.some(v => v.isPublic && v.required);
+        const hasRequired = propEntries.length > 0 && stateVars.some(v => v.isPublic && v.required && !v.optional);
         const propsOpt = hasRequired ? '' : '?';
         let propsType = propEntries.length > 0 ? `{${propEntries.join('; ')}}` : '{}';
         if (inheritsTag) propsType += ` & __RipProps<'${inheritsTag}'>`;
@@ -854,9 +928,15 @@ export function installComponentSupport(CodeEmitter, Lexer) {
       };
 
       // Property declarations (declare avoids definite-assignment errors)
-      for (const { name, type, value } of stateVars) {
+      for (const { name, type, value, optional, srcLine } of stateVars) {
         const ts = expandType(type) || inferLiteralType(value);
-        sl.push(ts ? `  declare ${name}: Signal<${ts}>;` : `  declare ${name}: Signal<any>;`);
+        // Optional prop with no default: field can be undefined at runtime
+        // (we don't synthesize a `?? null` fallback below), so the Signal's
+        // payload type must include undefined.
+        const optNoDefault = optional && value === undefined;
+        const wrapped = ts ? (optNoDefault ? `${ts} | undefined` : ts) : null;
+        const marker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
+        sl.push((wrapped ? `  declare ${name}: Signal<${wrapped}>;` : `  declare ${name}: Signal<any>;`) + marker);
       }
       if (inheritsTag) {
         sl.push(`  declare rest: Signal<__RipProps<'${inheritsTag}'>>;`);
@@ -880,19 +960,21 @@ export function installComponentSupport(CodeEmitter, Lexer) {
 
       // _init body — readonly, state, computed assignments (skip accepted/offered)
       sl.push('  _init(props) {');
-      for (const { name, value, isPublic } of readonlyVars) {
+      for (const { name, value, isPublic, srcLine } of readonlyVars) {
         const val = this.emitInComponent(value, 'value');
-        sl.push(isPublic ? `    this.${name} = props.${name} ?? ${val};` : `    this.${name} = ${val};`);
+        const marker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
+        sl.push((isPublic ? `    this.${name} = props.${name} ?? ${val};` : `    this.${name} = ${val};`) + marker);
       }
-      for (const { name, value, isPublic, required, type } of stateVars) {
-        if (isPublic && required) {
-          sl.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name});`);
+      for (const { name, value, isPublic, required, type, srcLine } of stateVars) {
+        const marker = srcLine != null ? ` // @rip-src:${srcLine}` : '';
+        if (isPublic && (required || value === undefined)) {
+          sl.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name});` + marker);
         } else if (isPublic) {
           const val = this.emitInComponent(value, 'value');
-          sl.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name} ?? ${val});`);
+          sl.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name} ?? ${val});` + marker);
         } else {
           const val = this.emitInComponent(value, 'value');
-          sl.push(`    this.${name} = __state(${val});`);
+          sl.push(`    this.${name} = __state(${val});` + marker);
         }
       }
 
@@ -976,7 +1058,12 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           }
           const transformed = this.reactiveMembers ? this.transformComponentMembers(methodBody) : methodBody;
           const isAsync = this.containsAwait(methodBody);
-          const bodyCode = this.emitFunctionBody(transformed, params || []);
+          let bodyCode = this.emitFunctionBody(transformed, params || []);
+          // Inject @rip-src markers on each body statement line so that
+          // @ts-expect-error injection and hover/diagnostics resolve to the
+          // user's actual source line, instead of relying on linear gap-fill
+          // interpolation across the stub (which is brittle to stub size).
+          bodyCode = this.addBodyRipSrcMarkers(bodyCode, methodBody);
           sl.push(`  ${isAsync ? 'async ' : ''}${name}(${paramStr}) ${bodyCode}`);
         }
       }
@@ -988,7 +1075,8 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           const paramStr = Array.isArray(params) ? params.map(p => this.formatParam(p)).join(', ') : '';
           const transformed = this.reactiveMembers ? this.transformComponentMembers(hookBody) : hookBody;
           const isAsync = this.containsAwait(hookBody);
-          const bodyCode = this.emitFunctionBody(transformed, params || []);
+          let bodyCode = this.emitFunctionBody(transformed, params || []);
+          bodyCode = this.addBodyRipSrcMarkers(bodyCode, hookBody);
           sl.push(`  ${isAsync ? 'async ' : ''}${name}(${paramStr}) ${bodyCode}`);
         }
       }
@@ -1051,8 +1139,22 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           props.sideExprs = sideExprs;
           return props;
         };
-        const extractIntrinsicProps = (args) => {
+        const extractIntrinsicProps = (args, tagName) => {
           const props = [];
+          // For <a href: ...>, wrap interpolated route literals (templates
+          // starting with `/...`) in __ripRoute so TS checks the dynamic
+          // template against __RipRoutes. Static literals fall through to
+          // the existing __ripEl Option-C conditional, which still gives
+          // the "Did you mean ..." hint. Variables and external URLs are
+          // left untouched.
+          const wrapHrefVal = (val) => {
+            if (tagName !== 'a') return val;
+            if (typeof val !== 'string') return val;
+            if (val.length < 2) return val;
+            if (val[0] !== '`') return val;
+            if (val[1] !== '/') return val;
+            return `__ripRoute(${val})`;
+          };
           for (const arg of args) {
             let obj = null;
             if (this.is(arg, 'object')) {
@@ -1089,7 +1191,8 @@ export function installComponentSupport(CodeEmitter, Lexer) {
                     props.push({ code: `${propName}: ${val}`, srcLine });
                   } else {
                     const val = this.emitInComponent(value, 'value');
-                    props.push({ code: `${key}: ${val}`, srcLine });
+                    const finalVal = key === 'href' ? wrapHrefVal(val) : val;
+                    props.push({ code: `${key}: ${finalVal}`, srcLine });
                   }
                 }
               }
@@ -1373,7 +1476,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
           } else if (typeof head === 'string' && !CodeEmitter.GENERATORS[head] && (TEMPLATE_TAGS.has(head.split(/[.#]/)[0]) ||
                      (/^[a-z][\w-]*$/.test(head) && node.length > 1))) {
             const tagName = head.split(/[.#]/)[0];
-            const iProps = extractIntrinsicProps(node.slice(1));
+            const iProps = extractIntrinsicProps(node.slice(1), tagName);
             const tagLine = node.loc?.r;
             const srcMarker = tagLine != null ? ` // @rip-src:${tagLine}` : '';
             if (iProps.length === 0) {
@@ -1441,7 +1544,7 @@ export function installComponentSupport(CodeEmitter, Lexer) {
 
     // State variables (__state handles signal passthrough)
     for (const { name, value, isPublic, required } of stateVars) {
-      if (isPublic && required) {
+      if (isPublic && (required || value === undefined)) {
         lines.push(`    this.${name} = __state(props.__bind_${name}__ ?? props.${name});`);
       } else if (isPublic) {
         const val = this.emitInComponent(value, 'value');
@@ -2727,7 +2830,13 @@ export function installComponentSupport(CodeEmitter, Lexer) {
     const outerParams = this._loopVarStack.map(v => `${v.itemVar}, ${v.indexVar}`).join(', ');
     const outerExtra = outerParams ? `, ${outerParams}` : '';
 
-    this._loopVarStack.push({ itemVar, indexVar });
+    // If the iterated collection is reactive, treat direct member access
+    // on the iter var (`item.qty`, `item[0]`, `item.a.b`) as reactive
+    // inside the loop body. hasReactiveDeps consults this flag, so the
+    // existing emit paths wrap those reads in __effect and the per-row
+    // patch function gets populated.
+    const reactiveSource = this.hasReactiveDeps(collection);
+    this._loopVarStack.push({ itemVar, indexVar, reactiveSource });
     const itemNode = this.emitTemplateBlock(body);
     this._loopVarStack.pop();
     const itemCreateLines = this._createLines;
@@ -3037,6 +3146,16 @@ export function installComponentSupport(CodeEmitter, Lexer) {
       return true;
     }
 
+    // Property chain rooted at a `for`-loop iter var whose source is
+    // reactive (e.g. `for item in cart.items` → `item.qty`, `item[0]`,
+    // `item.foo.bar`). Same rationale as the this-rooted case: the source
+    // proxy is reactive at runtime, so any member read may track. Limited
+    // to direct member access on the iter var — aliases and destructuring
+    // are explicitly out of scope.
+    if ((sexpr[0] === '.' || sexpr[0] === '[]') && this._rootsAtReactiveLoopVar(sexpr)) {
+      return true;
+    }
+
     // Method call on component: [['.', 'this', method], ...args]
     // Methods may read reactive state internally — treat as reactive so the
     // call gets wrapped in __effect and re-runs when dependencies change.
@@ -3118,6 +3237,26 @@ export function installComponentSupport(CodeEmitter, Lexer) {
     return this._rootsAtThis(sexpr[1]);
   };
 
+  // _rootsAtReactiveLoopVar — true when a `.` / `[]` access chain bottoms
+  // out at a string identifier that matches the itemVar of some frame on
+  // _loopVarStack whose `reactiveSource` is true. See emitTemplateLoop.
+  proto._rootsAtReactiveLoopVar = function(sexpr) {
+    if (typeof sexpr === 'string') {
+      if (!this._loopVarStack || this._loopVarStack.length === 0) return false;
+      // Iterate innermost-first so a shadowed name resolves to its nearest
+      // binding: `for item in reactive` containing `for item in [1,2,3]`
+      // must treat inner reads of `item` as non-reactive.
+      for (let i = this._loopVarStack.length - 1; i >= 0; i--) {
+        const v = this._loopVarStack[i];
+        if (v.itemVar === sexpr) return !!v.reactiveSource;
+      }
+      return false;
+    }
+    if (!Array.isArray(sexpr)) return false;
+    if (sexpr[0] === '.' || sexpr[0] === '[]') return this._rootsAtReactiveLoopVar(sexpr[1]);
+    return false;
+  };
+
   // ==========================================================================
   // Component Runtime
   // ==========================================================================