@sola-air-ui/compiler 1.2.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sola-air-ui/compiler",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Compiler for Sola single-file components (.sola) \u2014 transforms template + script + style to ES modules",
   "type": "module",
   "main": "./src/index.js",

package/src/cli.js

@@ -18,7 +18,7 @@ if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
     --target <esm|iife>       Output format (default: esm)
                                 esm  — ES module with import/export (default, for bundlers)
                                 iife — Self-contained IIFE for no-bundler environments
-                                       (ServiceNow Service Portal, plain <script> tags)
+                                       (enterprise portal widgets, plain <script> tags)
     --export-name <Name>      Global name for IIFE target (default: SolaComponent)
                               The compiled component mounts as window['Name'](el, props)
     -v, --version             Print compiler version

package/src/index.js

@@ -6,6 +6,14 @@ const { version: COMPILER_VERSION } = JSON.parse(
   readFileSync(new URL('../package.json', import.meta.url), 'utf8')
 );
 
+// Names every compiled component imports from core under their own name. A
+// script that imports one of these again is not given a second binding.
+const CORE_PROVIDED = new Set([
+  'createSignal', 'createDerived', 'createEffect', 'createIntent', 'createData',
+  'createPersistentSignal', 'onMount', 'onDestroy', 'pushContext', 'popContext',
+  '__flush_mounts', '__flush_destroys', '__untrack'
+]);
+
 const VOID_ELEMENTS = new Set([
   'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
   'link', 'meta', 'param', 'source', 'track', 'wbr'
@@ -325,7 +333,7 @@ function preprocessTemplate(template, dynAttrs, handlers) {
           } else if (hasDyn) {
             // Build a string-concatenation expression instead of a runtime backtick
             // template literal. Confirmed by driving a real browser against a live
-            // ServiceNow Service Portal instance: its widget-script delivery pipeline
+            // enterprise portal instance: its widget-script delivery pipeline
             // silently mangles `${expr}` interpolation inside a template literal down
             // to bare, unevaluated expression text (e.g. `background: ${x}` becomes
             // the literal string "background: x" — the function reference itself,
@@ -889,6 +897,12 @@ export function compile(source, options = {}) {
   const stateVars = new Set();
   const exportedProps = [];
   const componentImports = [];
+  // Every other import in the script. They used to be deleted, so a package
+  // import (`import DataCard from '@sola-air-ui/ui/data-card'`, or anything from
+  // '@sola-air-ui/core' that the compiler does not already provide) was gone from
+  // the output and left an undefined name behind.
+  const otherImports = [];
+  const coreImportExtras = [];
 
   let reactiveVars = NO_REACTIVE_VARS;
   if (strippedScript.trim()) {
@@ -914,6 +928,21 @@ export function compile(source, options = {}) {
             node.specifiers.forEach(spec => {
               componentImports.push({ localName: spec.local.name, path: src });
             });
+          } else if (src === '@sola-air-ui/core' || src === '@sola/core') {
+            // The compiler already imports these names under their own names.
+            // Importing one again would be a duplicate binding, so keep only the
+            // rest: names it does not provide, and aliased ones.
+            node.specifiers.forEach(spec => {
+              if (spec.type !== 'ImportSpecifier') return;
+              const imported = spec.imported.name ?? spec.imported.value;
+              if (spec.local.name === imported && CORE_PROVIDED.has(imported)) return;
+              coreImportExtras.push({ imported, local: spec.local.name });
+            });
+          } else {
+            otherImports.push({
+              code: strippedScript.slice(node.start, node.end).trim().replace(/;?$/, ';'),
+              locals: node.specifiers.map(spec => spec.local.name)
+            });
           }
           edits.push({
             start: node.start,
@@ -947,6 +976,14 @@ export function compile(source, options = {}) {
           edits.push({ start: call.end, end: call.end, replacement: ')' });
         }
 
+        // $effect(fn) as a bare statement: the form the docs show. It compiles to
+        // createEffect(fn); the declaration form (const stop = $effect(fn)) is below.
+        if (node.type === 'ExpressionStatement' && node.expression.type === 'CallExpression' &&
+            node.expression.callee.type === 'Identifier' && node.expression.callee.name === '$effect') {
+          const callee = node.expression.callee;
+          edits.push({ start: callee.start, end: callee.end, replacement: 'createEffect' });
+        }
+
         // $state()/$derived()/$effect()/$intent()/$data() macro declarations.
         // Bracket edits (head + tail) leave the argument expression in place so
         // the reactive rewrite pass below can still auto-call signals inside it.
@@ -1050,6 +1087,11 @@ export function compile(source, options = {}) {
   let uid = 0;
   let domCode = '';
   const importedComponentSet = new Set(componentImports.map(i => i.localName));
+  // A capitalised tag that matches a name imported from a package is a component
+  // too (`import DataCard from '@sola-air-ui/ui/data-card'`), not only a `.sola` path.
+  for (const imp of otherImports) {
+    for (const name of imp.locals) if (/^[A-Z]/.test(name)) importedComponentSet.add(name);
+  }
 
   const sourceFile = options.filename || '<component>';
 
@@ -1130,25 +1172,43 @@ export function compile(source, options = {}) {
       domCode += `  ${parentVar}.appendChild(${cid}_target);\n`;
 
       // Dynamically-bound props (rows={items}) arrive here as __soladyn_N__ placeholders —
-      // resolve them back to the real expression from dynAttrs and pass it as a raw
-      // (unquoted) property so the child receives live data, not the placeholder text.
+      // resolve them back to the real expression from dynAttrs.
       //
       // `onXxx`-named props (e.g. onChange={handler}) arrive as a
       // __solahandler_N__ marker, because preprocessTemplate cannot tell a
       // component apart from a native element and lifts both the same way.
       // Either way the expression is passed through as a live function.
+      //
+      // Three kinds of dynamic prop:
+      //  - a bare name (rows={items}) is passed as-is. For a $state that is the
+      //    signal accessor, which is how a child receives live data (the shipped
+      //    components accept either an accessor or a plain value);
+      //  - an expression that reads a signal (title={ctx.title}) is evaluated
+      //    with the signal reads rewritten, and the child is re-mounted when
+      //    the value changes;
+      //  - an expression that reads no signal (text={msg.text} in an {#each})
+      //    is evaluated once, when the child is mounted.
       const propEntries = [];
+      let reactiveProps = false;
       for (const [key, val] of Object.entries(node.attribs || {})) {
         const dynMatch = /^__soladyn_(\d+)__$/.exec(val);
         const handlerMatch = /^__solahandler_(\d+)__$/.exec(val);
-        // Dynamic (non-event) component props are deliberately NOT auto-called:
-        // passing the getter is how a child receives live data today, and
-        // README-syntax components rely on it.
-        const propValue = dynMatch
-          ? `(${dynAttrs[parseInt(dynMatch[1], 10)]})`
-          : handlerMatch
-            ? `(${rewrite(handlers[parseInt(handlerMatch[1], 10)])})`
-            : JSON.stringify(val);
+        let propValue;
+        if (dynMatch) {
+          const raw = dynAttrs[parseInt(dynMatch[1], 10)];
+          if (/^\s*[A-Za-z_$][\w$]*\s*$/.test(raw)) {
+            propValue = `(${raw})`;
+          } else {
+            checkExpression(raw, 'component prop');
+            const rewritten = rewrite(raw);
+            if (rewritten !== raw) reactiveProps = true;
+            propValue = `(${rewritten})`;
+          }
+        } else if (handlerMatch) {
+          propValue = `(${rewrite(handlers[parseInt(handlerMatch[1], 10)])})`;
+        } else {
+          propValue = JSON.stringify(val);
+        }
         propEntries.push(`${JSON.stringify(key)}: ${propValue}`);
       }
 
@@ -1162,7 +1222,21 @@ export function compile(source, options = {}) {
         propEntries.push(`children: ${slotVar}`);
       }
 
-      domCode += `  ${node.name}(${cid}_target, { ${propEntries.join(', ')} });\n`;
+      // The child mounts untracked, so nothing it reads while building itself
+      // can re-run the parent's effect. Its teardown is kept and registered with
+      // whatever scope is being built, so it runs when that scope is destroyed.
+      domCode += `  let ${cid}_unmount = null;\n`;
+      domCode += `  onDestroy(() => { if (typeof ${cid}_unmount === 'function') ${cid}_unmount(); ${cid}_unmount = null; });\n`;
+      if (reactiveProps) {
+        domCode += `  createEffect(() => {\n`;
+        domCode += `    const ${cid}_props = { ${propEntries.join(', ')} };\n`;
+        domCode += `    if (typeof ${cid}_unmount === 'function') __untrack(${cid}_unmount);\n`;
+        domCode += `    ${cid}_target.textContent = '';\n`;
+        domCode += `    ${cid}_unmount = __untrack(() => ${node.name}(${cid}_target, ${cid}_props));\n`;
+        domCode += `  });\n`;
+      } else {
+        domCode += `  ${cid}_unmount = __untrack(() => ${node.name}(${cid}_target, { ${propEntries.join(', ')} }));\n`;
+      }
       return;
     }
 
@@ -1173,37 +1247,50 @@ export function compile(source, options = {}) {
     }
 
     // {#if ...} {:else} ... {/if}
+    //
+    // Each time a branch is built it gets its own scope (pushContext). Effects,
+    // onDestroy callbacks and child components created inside register with that
+    // scope, and switching or removing the branch destroys it, so nothing built
+    // for a branch that is no longer on the page keeps running.
     if (node.name === 'sola-if') {
       const cid = `c${uid++}`;
       domCode += `  const ${cid}_a = document.createComment('if');\n`;
       domCode += `  ${parentVar}.appendChild(${cid}_a);\n`;
       domCode += `  let ${cid}_els = [];\n`;
-      
+      domCode += `  let ${cid}_ctx = null;\n`;
+      domCode += `  onDestroy(() => { if (${cid}_ctx) { __flush_destroys(${cid}_ctx); ${cid}_ctx = null; } });\n`;
+
       const thenChild = node.children.find(c => c.name === 'sola-then');
       const elseChild = node.children.find(c => c.name === 'sola-else');
 
-      domCode += `  createEffect(() => {\n`;
-      domCode += `    ${cid}_els.forEach(e => e.remove()); ${cid}_els = [];\n`;
-      domCode += `    if (${rewrite(node.attribs.condition)}) {\n`;
-      if (thenChild) {
+      const emitBranch = (branch) => {
+        if (!branch) return;
+        domCode += `      ${cid}_ctx = pushContext();\n`;
+        domCode += `      try {\n`;
         domCode += `      const f = document.createDocumentFragment();\n`;
-        thenChild.children.forEach(child => emitNode(child, 'f', locals));
+        branch.children.forEach(child => emitNode(child, 'f', locals));
         domCode += `      Array.from(f.childNodes).forEach(n => ${cid}_els.push(n));\n`;
         domCode += `      ${cid}_a.parentNode.insertBefore(f, ${cid}_a.nextSibling);\n`;
-      }
+        domCode += `      } finally { popContext(${cid}_ctx); }\n`;
+      };
+
+      domCode += `  createEffect(() => {\n`;
+      domCode += `    if (${cid}_ctx) { __flush_destroys(${cid}_ctx); ${cid}_ctx = null; }\n`;
+      domCode += `    ${cid}_els.forEach(e => e.remove()); ${cid}_els = [];\n`;
+      domCode += `    if (${rewrite(node.attribs.condition)}) {\n`;
+      emitBranch(thenChild);
       domCode += `    } else {\n`;
-      if (elseChild) {
-        domCode += `      const f = document.createDocumentFragment();\n`;
-        elseChild.children.forEach(child => emitNode(child, 'f', locals));
-        domCode += `      Array.from(f.childNodes).forEach(n => ${cid}_els.push(n));\n`;
-        domCode += `      ${cid}_a.parentNode.insertBefore(f, ${cid}_a.nextSibling);\n`;
-      }
+      emitBranch(elseChild);
       domCode += `    }\n`;
       domCode += `  });\n`;
       return;
     }
 
     // {#each} with optional keyed diffing: {#each items as item (item.id)}
+    //
+    // Like {#if}, what is built for the list gets its own scope so it can be
+    // destroyed: the whole list for an unkeyed each, one scope per key for a
+    // keyed one (so removing an item stops that item's effects and children).
     if (node.name === 'sola-each') {
       const eid = `e${uid++}`;
       // Item/index names shadow signals inside the loop body and key expression
@@ -1217,70 +1304,53 @@ export function compile(source, options = {}) {
       domCode += `  const ${eid}_a = document.createComment('each');\n`;
       domCode += `  ${parentVar}.appendChild(${eid}_a);\n`;
       if (keyExpr) {
-        // Keyed: maintain a Map<key, Node[]> and reconcile on each run
+        // Keyed: maintain a Map<key, { nodes, ctx }> and reconcile on each run
         // Reconcile by walking the new order and moving each key's nodes into
         // place against a cursor. The previous version only ever inserted, and
         // against an anchor it never advanced — so reordering a keyed list (a
         // sort, a drag, a reverse) left the DOM in its original order, silently.
-        domCode += `  let ${eid}_keyMap = new Map();
-`;
-        domCode += `  createEffect(() => {
-`;
-        domCode += `    const _items = ${arrayExpr} || [];
-`;
-        domCode += `    const _parent = ${eid}_a.parentNode;
-`;
-        domCode += `    const _seen = new Set();
-`;
-        domCode += `    let _cursor = ${eid}_a.nextSibling;
-`;
-        domCode += `    for (let _i = 0; _i < _items.length; _i++) {
-`;
-        domCode += `      const ${node.attribs.item} = _items[_i];
-`;
-        if (node.attribs.index) domCode += `      const ${node.attribs.index} = _i;
-`;
-        domCode += `      const _key = String(${keyExpr});
-`;
-        domCode += `      _seen.add(_key);
-`;
-        domCode += `      let _nodes = ${eid}_keyMap.get(_key);
-`;
-        domCode += `      if (!_nodes) {
-`;
-        domCode += `        const f = document.createDocumentFragment();
-`;
+        domCode += `  let ${eid}_keyMap = new Map();\n`;
+        domCode += `  onDestroy(() => { for (const _e of ${eid}_keyMap.values()) __flush_destroys(_e.ctx); ${eid}_keyMap.clear(); });\n`;
+        domCode += `  createEffect(() => {\n`;
+        domCode += `    const _items = ${arrayExpr} || [];\n`;
+        domCode += `    const _parent = ${eid}_a.parentNode;\n`;
+        domCode += `    const _seen = new Set();\n`;
+        domCode += `    let _cursor = ${eid}_a.nextSibling;\n`;
+        domCode += `    for (let _i = 0; _i < _items.length; _i++) {\n`;
+        domCode += `      const ${node.attribs.item} = _items[_i];\n`;
+        if (node.attribs.index) domCode += `      const ${node.attribs.index} = _i;\n`;
+        domCode += `      const _key = String(${keyExpr});\n`;
+        domCode += `      _seen.add(_key);\n`;
+        domCode += `      let _entry = ${eid}_keyMap.get(_key);\n`;
+        domCode += `      if (!_entry) {\n`;
+        domCode += `        const _kctx = pushContext();\n`;
+        domCode += `        try {\n`;
+        domCode += `        const f = document.createDocumentFragment();\n`;
         node.children.forEach(child => emitNode(child, 'f', eachLocals));
-        domCode += `        _nodes = Array.from(f.childNodes);
-`;
-        domCode += `        ${eid}_keyMap.set(_key, _nodes);
-`;
-        domCode += `      }
-`;
-        domCode += `      for (const _n of _nodes) {
-`;
-        domCode += `        if (_n === _cursor) { _cursor = _cursor.nextSibling; }
-`;
-        domCode += `        else { _parent.insertBefore(_n, _cursor); }
-`;
-        domCode += `      }
-`;
-        domCode += `    }
-`;
-        domCode += `    for (const [_k, _stale] of ${eid}_keyMap) {
-`;
-        domCode += `      if (!_seen.has(_k)) { _stale.forEach(n => n.remove()); ${eid}_keyMap.delete(_k); }
-`;
-        domCode += `    }
-`;
-        domCode += `  });
-`;
+        domCode += `        _entry = { nodes: Array.from(f.childNodes), ctx: _kctx };\n`;
+        domCode += `        } finally { popContext(_kctx); }\n`;
+        domCode += `        ${eid}_keyMap.set(_key, _entry);\n`;
+        domCode += `      }\n`;
+        domCode += `      for (const _n of _entry.nodes) {\n`;
+        domCode += `        if (_n === _cursor) { _cursor = _cursor.nextSibling; }\n`;
+        domCode += `        else { _parent.insertBefore(_n, _cursor); }\n`;
+        domCode += `      }\n`;
+        domCode += `    }\n`;
+        domCode += `    for (const [_k, _stale] of ${eid}_keyMap) {\n`;
+        domCode += `      if (!_seen.has(_k)) { __flush_destroys(_stale.ctx); _stale.nodes.forEach(n => n.remove()); ${eid}_keyMap.delete(_k); }\n`;
+        domCode += `    }\n`;
+        domCode += `  });\n`;
       } else {
         // Unkeyed: full teardown + rebuild
         domCode += `  let ${eid}_els = [];\n`;
+        domCode += `  let ${eid}_ctx = null;\n`;
+        domCode += `  onDestroy(() => { if (${eid}_ctx) { __flush_destroys(${eid}_ctx); ${eid}_ctx = null; } });\n`;
         domCode += `  createEffect(() => {\n`;
+        domCode += `    if (${eid}_ctx) { __flush_destroys(${eid}_ctx); ${eid}_ctx = null; }\n`;
         domCode += `    ${eid}_els.forEach(e => e.remove()); ${eid}_els = [];\n`;
         domCode += `    const _items = ${arrayExpr} || [];\n`;
+        domCode += `    ${eid}_ctx = pushContext();\n`;
+        domCode += `    try {\n`;
         domCode += `    const f = document.createDocumentFragment();\n`;
         domCode += `    for (let _i = 0; _i < _items.length; _i++) {\n`;
         domCode += `      const ${node.attribs.item} = _items[_i];\n`;
@@ -1289,6 +1359,7 @@ export function compile(source, options = {}) {
         domCode += `    }\n`;
         domCode += `    Array.from(f.childNodes).forEach(n => ${eid}_els.push(n));\n`;
         domCode += `    ${eid}_a.parentNode.insertBefore(f, ${eid}_a.nextSibling);\n`;
+        domCode += `    } finally { popContext(${eid}_ctx); }\n`;
         domCode += `  });\n`;
       }
       return;
@@ -1356,7 +1427,7 @@ export function compile(source, options = {}) {
   root.children.forEach(child => emitNode(child, '__target'));
 
   // Assemble final output module
-  const CORE_EXPORTS = 'createSignal, createDerived, createEffect, createIntent, createData, createPersistentSignal, onMount, onDestroy, pushContext, popContext, __flush_mounts, __flush_destroys';
+  const CORE_EXPORTS = [...CORE_PROVIDED].join(', ');
   // The default bus is imported under an alias so a user variable named `bus`
   // cannot shadow what $on / $lastEvent compile to.
   const ESM_CORE_IMPORTS = CORE_EXPORTS + ', bus as __solaBus';
@@ -1365,19 +1436,30 @@ export function compile(source, options = {}) {
   output += `// Compiled by @sola-air-ui/compiler v${COMPILER_VERSION}\n`;
 
   if (target === 'iife') {
-    // ServiceNow / no-bundler mode: pull from window.SolaCore global
+    // No-bundler mode: pull from window.SolaCore global
     output += `(function() {\n`;
-    output += `const { ${IIFE_CORE_PULL} } = window.SolaCore;\n`;
+    const iifeExtras = coreImportExtras.map(e => (e.local === e.imported ? e.imported : `${e.imported}: ${e.local}`));
+    output += `const { ${[IIFE_CORE_PULL, ...iifeExtras].join(', ')} } = window.SolaCore;\n`;
     for (const imp of componentImports) {
       output += `// Note: sub-component ${imp.localName} must be pre-loaded before this script\n`;
     }
+    for (const imp of otherImports) {
+      output += `// Note: ${imp.locals.join(', ')} must be loaded before this script (no-bundler output cannot import)\n`;
+    }
     output += `\n`;
     output += `window['${options.exportName || 'SolaComponent'}'] = function mount(__target, props = {}) {\n`;
   } else {
     output += `import { ${ESM_CORE_IMPORTS} } from '@sola-air-ui/core';\n`;
+    if (coreImportExtras.length) {
+      const names = coreImportExtras.map(e => (e.local === e.imported ? e.imported : `${e.imported} as ${e.local}`));
+      output += `import { ${names.join(', ')} } from '@sola-air-ui/core';\n`;
+    }
     for (const imp of componentImports) {
       output += `import ${imp.localName} from '${imp.path}';\n`;
     }
+    for (const imp of otherImports) {
+      output += `${imp.code}\n`;
+    }
     output += `\n`;
     output += `export default function mount(__target, props = {}) {\n`;
   }
@@ -1462,6 +1544,9 @@ function inferPropType(defaultSrc) {
   if (/^(['"`])[\s\S]*\1$/.test(d)) return 'string';
   if (/^-?\d[\d_]*(\.\d+)?([eE][+-]?\d+)?$/.test(d)) return 'number';
   if (d === 'true' || d === 'false') return 'boolean';
+  // A null or undefined default says nothing about the type. `unknown` would stop a
+  // TypeScript host from reading or calling the prop; `any` lets it.
+  if (d === 'null' || d === 'undefined') return 'any';
   if (d.startsWith('[')) return 'unknown[]';
   if (d.startsWith('{')) return 'Record<string, unknown>';
   if (/^(\(.*\)|\w+)\s*=>|^function\b/.test(d)) return '(...args: any[]) => any';

package/types/index.d.ts

@@ -4,7 +4,7 @@ export interface CompileOptions {
   /**
    * 'esm' (default) emits a module importing from @sola-air-ui/core.
    * 'iife' emits a self-contained bundle reading from window.SolaCore, for
-   * ServiceNow and other no-bundler hosts.
+   * enterprise portals and other no-bundler hosts.
    */
   target?: 'esm' | 'iife';
   /** Global name the IIFE build registers itself under. Default 'SolaComponent'. */