@sola-air-ui/compiler 1.1.0 → 1.2.0

package/package.json

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

package/src/index.js

@@ -32,18 +32,81 @@ function hashString(str) {
   return 'sola-' + Math.abs(hash).toString(36);
 }
 
+// Split on `sep` characters that are not inside (), [] or a string, so
+// `:is(a, b)` and `:global(.x, .y)` are not torn apart at their commas.
+function splitTopLevel(text, isSep) {
+  const parts = [];
+  let depth = 0, quote = null, start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) { if (c === '\\') i++; else if (c === quote) quote = null; continue; }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === '(' || c === '[') depth++;
+    else if (c === ')' || c === ']') depth--;
+    else if (depth === 0 && isSep(c)) { parts.push(text.slice(start, i)); start = i + 1; }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+// Put the scope class on one compound selector, before any pseudo-class or
+// pseudo-element (button:hover → button.hash:hover).
+function addScopeToCompound(compound, scopeHash) {
+  const pseudoIdx = compound.search(/::?[\w-]/);
+  if (pseudoIdx > 0) {
+    return `${compound.slice(0, pseudoIdx)}.${scopeHash}${compound.slice(pseudoIdx)}`;
+  }
+  return `${compound}.${scopeHash}`;
+}
+
+// `:global(sel)` opts a piece of a selector out of scoping, so a scoped
+// component can style markup it did not create (e.g. the output of {@html}):
+//   .msg :global(table)  →  .msg.hash table
+//   :global(body)        →  body
+// The scope class always goes on the last compound that is not global.
+function scopeSelector(selector, scopeHash) {
+  const tokens = [];       // alternating compounds and combinators
+  let depth = 0, cur = '', comb = '';
+  const flushCompound = () => { if (cur) { tokens.push({ compound: cur }); cur = ''; } };
+  for (let i = 0; i < selector.length; i++) {
+    const c = selector[i];
+    if (c === '(' || c === '[') depth++;
+    else if (c === ')' || c === ']') depth--;
+    if (depth === 0 && /[\s>+~]/.test(c)) {
+      flushCompound();
+      comb += c;
+      continue;
+    }
+    if (comb) { tokens.push({ comb }); comb = ''; }
+    cur += c;
+  }
+  flushCompound();
+  if (comb) tokens.push({ comb });
+
+  let last = -1;
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.compound === undefined) continue;
+    const m = t.compound.match(/^:global\(([\s\S]*)\)$/);
+    // A comma list must stay grouped, or `.a :global(.x, .y)` would turn into
+    // two selectors and leave `.y` outside `.a`.
+    const group = (inner) => (splitTopLevel(inner, c => c === ',').length > 1 ? `:is(${inner})` : inner);
+    if (m) { t.compound = group(m[1]); t.global = true; }
+    else if (t.compound.includes(':global(')) {
+      t.compound = t.compound.replace(/:global\(([\s\S]*?)\)/g, (_, inner) => group(inner));
+      t.global = true;
+    } else { last = i; }
+  }
+  if (last >= 0) tokens[last].compound = addScopeToCompound(tokens[last].compound, scopeHash);
+  return tokens.map(t => t.compound ?? t.comb).join('');
+}
+
 function scopeSelectorList(selector, scopeHash) {
-  return selector
-    .split(',')
+  return splitTopLevel(selector, c => c === ',')
     .map(part => {
       const trimmed = part.trim();
       if (!trimmed) return part;
-      // Insert scope hash before pseudo-class/element (e.g. button:hover → button.hash:hover)
-      const pseudoIdx = trimmed.search(/::?[\w-]/);
-      if (pseudoIdx > 0) {
-        return `${trimmed.slice(0, pseudoIdx)}.${scopeHash}${trimmed.slice(pseudoIdx)}`;
-      }
-      return `${trimmed}.${scopeHash}`;
+      return scopeSelector(trimmed, scopeHash);
     })
     .join(', ');
 }
@@ -540,7 +603,7 @@ function collectReactiveVars(ast) {
             decl.init.callee.type === 'Identifier' && decl.id.type === 'Identifier') {
           const macro = decl.init.callee.name;
           if (macro === '$state' || macro === '$persist') vars.state.add(decl.id.name);
-          else if (macro === '$derived') vars.derived.add(decl.id.name);
+          else if (macro === '$derived' || macro === '$lastEvent') vars.derived.add(decl.id.name);
           else if (macro === '$intent') vars.intent.add(decl.id.name);
           else if (macro === '$data') vars.data.add(decl.id.name);
         }
@@ -638,7 +701,7 @@ function emitReactiveEdits(rootNode, src, vars, edits, initialShadows) {
         const isMemberProp = p.type === 'MemberExpression' && p.property === node && !p.computed;
         const isCallee = (p.type === 'CallExpression' || p.type === 'NewExpression') && p.callee === node;
         const isAssignTarget = (p.type === 'AssignmentExpression' && p.left === node) || p.type === 'UpdateExpression';
-        const isPropertyKey = p.type === 'Property' && p.key === node && !p.computed && !p.shorthand;
+        const isPropertyKey = p.type === 'Property' && p.key === node && !p.computed;
         const isShorthand = p.type === 'Property' && p.shorthand && p.value === node;
         const isMemberObject = p.type === 'MemberExpression' && p.object === node;
 
@@ -874,6 +937,16 @@ export function compile(source, options = {}) {
           removedRanges.push([node.start, node.end]);
         }
 
+        // $on('type', handler): subscribe to a bus event for the life of the
+        // component. Compiles to onDestroy(__solaBus.on(type, handler)). The handler
+        // stays in place so signals read inside it are rewritten like any other.
+        if (node.type === 'ExpressionStatement' && node.expression.type === 'CallExpression' &&
+            node.expression.callee.type === 'Identifier' && node.expression.callee.name === '$on') {
+          const call = node.expression;
+          edits.push({ start: call.callee.start, end: call.callee.end, replacement: 'onDestroy(__solaBus.on' });
+          edits.push({ start: call.end, end: call.end, replacement: ')' });
+        }
+
         // $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.
@@ -907,6 +980,16 @@ export function compile(source, options = {}) {
               } else {
                 edits.push({ start: node.start, end: node.end, replacement: `const ${varName} = createDerived(() => undefined);` });
               }
+            } else if (macro === '$lastEvent') {
+              // let ctx = $lastEvent('type'): the latest payload of a bus event as a
+              // reactive accessor, released when the component is destroyed.
+              const varName = decl.id.name;
+              if (arg) {
+                edits.push({ start: node.start, end: arg.start, replacement: `const ${varName} = __solaBus.signal(` });
+                edits.push({ start: lastArg.end, end: node.end, replacement: `); onDestroy(${varName}.dispose);` });
+              } else {
+                edits.push({ start: node.start, end: node.end, replacement: `const ${varName} = () => undefined;` });
+              }
             } else if (macro === '$effect') {
               if (arg) {
                 edits.push({ start: node.start, end: arg.start, replacement: `createEffect(` });
@@ -1274,20 +1357,24 @@ export function compile(source, options = {}) {
 
   // Assemble final output module
   const CORE_EXPORTS = 'createSignal, createDerived, createEffect, createIntent, createData, createPersistentSignal, onMount, onDestroy, pushContext, popContext, __flush_mounts, __flush_destroys';
+  // 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';
+  const IIFE_CORE_PULL = CORE_EXPORTS + ', bus: __solaBus';
   let output = '';
   output += `// Compiled by @sola-air-ui/compiler v${COMPILER_VERSION}\n`;
 
   if (target === 'iife') {
     // ServiceNow / no-bundler mode: pull from window.SolaCore global
     output += `(function() {\n`;
-    output += `const { ${CORE_EXPORTS} } = window.SolaCore;\n`;
+    output += `const { ${IIFE_CORE_PULL} } = window.SolaCore;\n`;
     for (const imp of componentImports) {
       output += `// Note: sub-component ${imp.localName} must be pre-loaded before this script\n`;
     }
     output += `\n`;
     output += `window['${options.exportName || 'SolaComponent'}'] = function mount(__target, props = {}) {\n`;
   } else {
-    output += `import { ${CORE_EXPORTS} } from '@sola-air-ui/core';\n`;
+    output += `import { ${ESM_CORE_IMPORTS} } from '@sola-air-ui/core';\n`;
     for (const imp of componentImports) {
       output += `import ${imp.localName} from '${imp.path}';\n`;
     }
@@ -1336,6 +1423,13 @@ export function compile(source, options = {}) {
   output += `};\n`;
   if (target === 'iife') {
     output += `})();\n`;
+  } else if (options.exportStyles) {
+    // Opt-in: the stylesheet and its scope class as module exports, for hosts
+    // that mount into a Shadow Root and adopt the CSS themselves (e.g. via
+    // adoptedStyleSheets). Off by default so existing build scripts that append
+    // their own `css` / `scopeHash` exports, or strip exports, keep working.
+    output += `\nexport const scopeHash = ${JSON.stringify(scopeHash)};\n`;
+    output += `export const css = \`${escapeTemplateLiteral(scopedCss || '')}\`;\n`;
   }
 
   // The reactive rewrite can add or remove characters within a line but never
@@ -1355,6 +1449,38 @@ export function compile(source, options = {}) {
     code: output,
     scopeHash,
     css: scopedCss,
-    map
+    map,
+    dts: buildDeclarations(exportedProps, !!options.exportStyles)
   };
 }
+
+// Best-effort TypeScript type for a prop, from the literal its default is
+// declared with. Anything it cannot read confidently is `unknown`, which stays
+// safe for callers rather than claiming a precision it does not have.
+function inferPropType(defaultSrc) {
+  const d = String(defaultSrc ?? '').trim();
+  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';
+  if (d.startsWith('[')) return 'unknown[]';
+  if (d.startsWith('{')) return 'Record<string, unknown>';
+  if (/^(\(.*\)|\w+)\s*=>|^function\b/.test(d)) return '(...args: any[]) => any';
+  return 'unknown';
+}
+
+// A `.d.ts` for a compiled component, so a TypeScript host can import the
+// compiled module with its props checked. Every prop is optional because each
+// has a default.
+function buildDeclarations(props, exportStyles) {
+  const fields = props
+    .map(p => `  ${/^[A-Za-z_$][\w$]*$/.test(p.name) ? p.name : JSON.stringify(p.name)}?: ${inferPropType(p.default)};`)
+    .join('\n');
+  return [
+    `export interface Props {${fields ? '\n' + fields + '\n' : ''}}`,
+    `/** Mounts the component into \`target\` and returns a teardown function. */`,
+    `declare function mount(target: Element | ShadowRoot, props?: Props): () => void;`,
+    `export default mount;`,
+    ...(exportStyles ? [`export declare const scopeHash: string;`, `export declare const css: string;`] : []),
+    ``
+  ].join('\n');
+}