ripple 0.2.188 → 0.2.190

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.2.188",
+  "version": "0.2.190",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -38,6 +38,12 @@
       "require": "./src/compiler/index.js",
       "default": "./src/compiler/index.js"
     },
+    "./compiler/internal/import": {
+      "types": "./src/compiler/types/import.d.ts"
+    },
+    "./compiler/internal/identifier/utils": {
+      "default": "./src/compiler/identifier-utils.js"
+    },
     "./validator": {
       "types": "./types/index.d.ts",
       "require": "./validator/index.js",
@@ -86,6 +92,6 @@
     "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "ripple": "0.2.188"
+    "ripple": "0.2.190"
   }
 }

package/src/compiler/identifier-utils.js

@@ -0,0 +1,75 @@
+export const IDENTIFIER_OBFUSCATION_PREFIX = '_$_';
+export const STYLE_IDENTIFIER = IDENTIFIER_OBFUSCATION_PREFIX + encode_utf16_char('#') + 'style';
+export const SERVER_IDENTIFIER = IDENTIFIER_OBFUSCATION_PREFIX + encode_utf16_char('#') + 'server';
+export const CSS_HASH_IDENTIFIER = IDENTIFIER_OBFUSCATION_PREFIX + 'hash';
+
+const DECODE_UTF16_REGEX = /_u([0-9a-fA-F]{4})_/g;
+
+/**
+ * @param {string} char
+ * @returns {string}
+ */
+function encode_utf16_char(char) {
+	return `_u${('0000' + char.charCodeAt(0).toString(16)).slice(-4)}_`;
+}
+
+/**
+ * @param {string} encoded
+ * @returns {string}
+ */
+function decoded_utf16_string(encoded) {
+	return encoded.replace(DECODE_UTF16_REGEX, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export function obfuscate_identifier(name) {
+	let start = 0;
+	if (name[0] === name[0].toUpperCase()) {
+		start = 1;
+	}
+	const index = find_next_uppercase(name, start);
+
+	const first_part = name.slice(0, index);
+	const second_part = name.slice(index);
+
+	return (
+		IDENTIFIER_OBFUSCATION_PREFIX +
+		(second_part ? second_part + '__' + first_part : first_part + '__')
+	);
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function is_identifier_obfuscated(name) {
+	return name.startsWith(IDENTIFIER_OBFUSCATION_PREFIX);
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export function deobfuscate_identifier(name) {
+	name = name.replaceAll(IDENTIFIER_OBFUSCATION_PREFIX, '');
+	const parts = name.split('__');
+	return decoded_utf16_string((parts[1] ? parts[1] : '') + parts[0]);
+}
+
+/**
+ * Finds the next uppercase character or returns name.length
+ * @param {string} name
+ * @param {number} start
+ * @returns {number}
+ */
+function find_next_uppercase(name, start) {
+	for (let i = start; i < name.length; i++) {
+		if (name[i] === name[i].toUpperCase()) {
+			return i;
+		}
+	}
+	return name.length;
+}

package/src/compiler/index.d.ts

@@ -1,4 +1,4 @@
-import type { Program } from 'estree';
+import type * as AST from 'estree';
 import type {
 	CodeInformation as VolarCodeInformation,
 	Mapping as VolarMapping,
@@ -14,7 +14,7 @@ import type { SourceMapMappings } from '@jridgewell/sourcemap-codec';
  */
 export interface CompileResult {
 	/** The transformed AST */
-	ast: Program;
+	ast: AST.Program;
 	/** The generated JavaScript code with source map */
 	js: {
 		code: string;
@@ -49,6 +49,14 @@ export interface PluginActionOverrides {
 				description?: string; // just for reference
 				// Generic location for embedded content (CSS, etc.)
 				location?: DefinitionLocation;
+				// Replace the type name in hover/definition with a different name
+				// And provide the path to import the type definitions from
+				// the `ripple` package directory, e.g. `types/index.d.ts`
+				// Currently only supported by the definition plugin
+				typeReplace?: {
+					name: string;
+					path: string;
+				};
 		  }
 		| false;
 }
@@ -94,7 +102,7 @@ export interface AnalyzeOptions extends ParseOptions, Pick<CompileOptions, 'mode
 
 export interface VolarCompileOptions extends ParseOptions, SharedCompileOptions {}
 
-export function parse(source: string, options?: ParseOptions): Program;
+export function parse(source: string, options?: ParseOptions): AST.Program;
 
 export function compile(source: string, filename: string, options?: CompileOptions): CompileResult;
 

package/src/compiler/index.js

@@ -1,4 +1,4 @@
-/** @import { Program } from 'estree' */
+/** @import * as AST from 'estree' */
 
 import { parse as parse_module } from './phases/1-parse/index.js';
 import { analyze } from './phases/2-analyze/index.js';
@@ -9,7 +9,7 @@ import { convert_source_map_to_mappings } from './phases/3-transform/segments.js
 /**
  * Parse Ripple source code to ESTree AST
  * @param {string} source
- * @returns {Program}
+ * @returns {AST.Program}
  */
 export function parse(source) {
 	return parse_module(source, undefined);

package/src/compiler/phases/1-parse/index.js

@@ -342,8 +342,12 @@ function RipplePlugin(config) {
 						if (this.input.slice(this.pos, this.pos + 4) === '#Map') {
 							const charAfter =
 								this.pos + 4 < this.input.length ? this.input.charCodeAt(this.pos + 4) : -1;
-							if (charAfter === 40) {
-								// ( character
+							if (charAfter === 40 || charAfter === 60) {
+								// ( or < character (for generics like #Map<string, number>)
+								this.pos += 4; // consume '#Map'
+								return this.finishToken(tt.name, '#Map');
+							} else if (this.#loose) {
+								// In loose mode, produce token even without parens (incomplete syntax)
 								this.pos += 4; // consume '#Map'
 								return this.finishToken(tt.name, '#Map');
 							}
@@ -351,8 +355,12 @@ function RipplePlugin(config) {
 						if (this.input.slice(this.pos, this.pos + 4) === '#Set') {
 							const charAfter =
 								this.pos + 4 < this.input.length ? this.input.charCodeAt(this.pos + 4) : -1;
-							if (charAfter === 40) {
-								// ( character
+							if (charAfter === 40 || charAfter === 60) {
+								// ( or < character (for generics like #Set<number>)
+								this.pos += 4; // consume '#Set'
+								return this.finishToken(tt.name, '#Set');
+							} else if (this.#loose) {
+								// In loose mode, produce token even without parens (incomplete syntax)
 								this.pos += 4; // consume '#Set'
 								return this.finishToken(tt.name, '#Set');
 							}
@@ -378,9 +386,29 @@ function RipplePlugin(config) {
 							}
 						}
 
+						if (this.input.slice(this.pos, this.pos + 6) === '#style') {
+							// Check that next char after 'style' is . (dot), [, whitespace, or EOF
+							const charAfter =
+								this.pos + 6 < this.input.length ? this.input.charCodeAt(this.pos + 6) : -1;
+							if (
+								charAfter === 46 || // . (dot)
+								charAfter === 91 || // [
+								charAfter === 32 || // space
+								charAfter === 9 || // tab
+								charAfter === 10 || // newline
+								charAfter === 13 || // carriage return
+								charAfter === -1 // EOF
+							) {
+								// { or . or whitespace or EOF
+								this.pos += 6; // consume '#style'
+								return this.finishToken(tt.name, '#style');
+							}
+						}
+
 						// Check if this is an invalid #Identifier pattern
-						// Valid patterns: #[, #{, #Map(, #Set(, #server
+						// Valid patterns: #[, #{, #Map(, #Map<, #Set(, #Set<, #server, #style
 						// If we see # followed by an uppercase letter that isn't Map or Set, it's an error
+						// In loose mode, allow incomplete identifiers like #M, #Ma, #S, #Se for autocomplete
 						if (nextChar >= 65 && nextChar <= 90) {
 							// A-Z
 							// Extract the identifier name
@@ -401,12 +429,34 @@ function RipplePlugin(config) {
 							}
 							const identName = this.input.slice(this.pos + 1, identEnd);
 							if (identName !== 'Map' && identName !== 'Set') {
-								this.raise(
-									this.pos,
-									`Invalid tracked syntax '#${identName}'. Only #Map and #Set are currently supported using shorthand tracked syntax.`,
-								);
+								// In loose mode, allow incomplete identifiers (prefixes of Map/Set)
+								// This supports autocomplete scenarios where user is still typing
+								const isIncompleteMap = 'Map'.startsWith(identName);
+								const isIncompleteSet = 'Set'.startsWith(identName);
+
+								if (!this.#loose || (!isIncompleteMap && !isIncompleteSet)) {
+									this.raise(
+										this.pos,
+										`Invalid tracked syntax '#${identName}'. Only #Map and #Set are currently supported using shorthand tracked syntax.`,
+									);
+								} else {
+									// In loose mode with valid prefix, consume the token and return it
+									// This allows the parser to handle incomplete syntax gracefully
+									this.pos = identEnd; // consume '#' + identifier
+									return this.finishToken(tt.name, '#' + identName);
+								}
 							}
 						}
+
+						// In loose mode, handle bare # or # followed by unrecognized characters
+						if (this.#loose) {
+							this.pos++; // consume '#'
+							return this.finishToken(tt.name, '#');
+						}
+					} else if (this.#loose) {
+						// In loose mode, handle bare # at EOF
+						this.pos++; // consume '#'
+						return this.finishToken(tt.name, '#');
 					}
 				}
 				if (code === 64) {
@@ -435,20 +485,43 @@ function RipplePlugin(config) {
 							// In JSX expressions, inside parentheses, assignments, etc.
 							// we want to treat @ as an identifier prefix rather than decorator
 							const currentType = this.type;
-							const inExpression =
-								this.exprAllowed ||
-								currentType === tt.braceL || // Inside { }
-								currentType === tt.parenL || // Inside ( )
-								currentType === tt.eq || // After =
-								currentType === tt.comma || // After ,
-								currentType === tt.colon || // After :
-								currentType === tt.question || // After ?
-								currentType === tt.logicalOR || // After ||
-								currentType === tt.logicalAND || // After &&
-								currentType === tt.dot || // After . (for member expressions like obj.@prop)
-								currentType === tt.questionDot; // After ?. (for optional chaining like obj?.@prop)
-
-							if (inExpression) {
+							/**
+							 * @param {Parse.TokenType} type
+							 * @param {Parse.Parser} parser
+							 * @param {Parse.TokTypes} tt
+							 * @returns {boolean}
+							 */
+							function inExpression(type, parser, tt) {
+								return (
+									parser.exprAllowed ||
+									type === tt.braceL || // Inside { }
+									type === tt.parenL || // Inside ( )
+									type === tt.eq || // After =
+									type === tt.comma || // After ,
+									type === tt.colon || // After :
+									type === tt.question || // After ?
+									type === tt.logicalOR || // After ||
+									type === tt.logicalAND || // After &&
+									type === tt.dot || // After . (for member expressions like obj.@prop)
+									type === tt.questionDot // After ?. (for optional chaining like obj?.@prop)
+								);
+							}
+
+							/**
+							 * @param {Parse.Parser} parser
+							 * @param {Parse.TokTypes} tt
+							 * @returns {boolean}
+							 */
+							function inAwait(parser, tt) {
+								return currentType === tt.name &&
+									parser.value === 'await' &&
+									parser.canAwait &&
+									parser.preToken
+									? inExpression(parser.preToken, parser, tt)
+									: false;
+							}
+
+							if (inExpression(currentType, this, tt) || inAwait(this, tt)) {
 								return this.readAtIdentifier();
 							}
 						}
@@ -604,12 +677,32 @@ function RipplePlugin(config) {
 					return /** @type {AST.ServerIdentifier} */ (this.finishNode(node, 'ServerIdentifier'));
 				}
 
+				if (this.type === tt.name && this.value === '#style') {
+					const node = this.startNode();
+					this.next();
+					return /** @type {AST.StyleIdentifier} */ (this.finishNode(node, 'StyleIdentifier'));
+				}
+
 				// Check if this is #Map( or #Set(
 				if (this.type === tt.name && (this.value === '#Map' || this.value === '#Set')) {
 					const type = this.value === '#Map' ? 'TrackedMapExpression' : 'TrackedSetExpression';
 					return this.parseTrackedCollectionExpression(type);
 				}
 
+				// In loose mode, handle incomplete #Map/#Set prefixes (e.g., #M, #Ma, #S, #Se)
+				if (
+					this.#loose &&
+					this.type === tt.name &&
+					typeof this.value === 'string' &&
+					this.value.startsWith('#')
+				) {
+					// Return an Identifier node for incomplete tracked syntax
+					const node = /** @type {AST.Identifier} */ (this.startNode());
+					node.name = this.value;
+					this.next();
+					return this.finishNode(node, 'Identifier');
+				}
+
 				// Check if this is a tuple literal starting with #[
 				if (this.type === tt.bracketL && this.value === '#[') {
 					return this.parseTrackedArrayExpression();
@@ -676,7 +769,7 @@ function RipplePlugin(config) {
 				const node = /** @type {AST.ServerBlock} */ (this.startNode());
 				this.next();
 
-				const body = /** @type {AST.BlockStatement} */ (this.startNode());
+				const body = /** @type {AST.ServerBlockStatement} */ (this.startNode());
 				node.body = body;
 				body.body = [];
 
@@ -728,8 +821,10 @@ function RipplePlugin(config) {
 					);
 				}
 
-				if (this.type === tt.parenL) {
-					// Don't consume parens - they belong to NewExpression
+				// Don't consume parens or generics - they belong to NewExpression
+				// When used as "new #Map(...)" the next token is '('
+				// When used as "new #Map<K,V>(...)" the next token is '<' (relational)
+				if (this.type === tt.parenL || (this.type === tt.relational && this.value === '<')) {
 					node.arguments = [];
 					return this.finishNode(node, type);
 				}

package/src/compiler/phases/2-analyze/index.js

@@ -6,6 +6,8 @@
 	AnalysisContext,
 	ScopeInterface,
 	Visitors,
+	TopScopedClasses,
+	StyleClasses,
 } from '#compiler';
  */
 /** @import * as AST from 'estree' */
@@ -200,6 +202,51 @@ const visitors = {
 			context.state.metadata.tracking = true;
 		}
 
+		// Track #style.className or #style['className'] references
+		if (node.object.type === 'StyleIdentifier') {
+			const component = is_inside_component(context, true);
+
+			if (!component) {
+				return error(
+					'`#style` can only be used within a component',
+					context.state.analysis.module.filename,
+					node,
+				);
+			} else {
+				component.metadata.styleIdentifierPresent = true;
+			}
+
+			/** @type {string | null} */
+			let className = null;
+
+			if (!node.computed && node.property.type === 'Identifier') {
+				// #style.test
+				className = node.property.name;
+			} else if (
+				node.computed &&
+				node.property.type === 'Literal' &&
+				typeof node.property.value === 'string'
+			) {
+				// #style['test']
+				className = node.property.value;
+			} else {
+				// #style[expression] - dynamic, not allowed
+				error(
+					'`#style` property access must use a dot property or static string for css class name, not a dynamic expression',
+					context.state.analysis.module.filename,
+					node.property,
+				);
+			}
+
+			if (className !== null) {
+				context.state.metadata.styleClasses?.set(className, node.property);
+			}
+
+			return context.next();
+		} else if (node.object.type === 'ServerIdentifier') {
+			context.state.analysis.metadata.serverIdentifierPresent = true;
+		}
+
 		if (node.object.type === 'Identifier' && !node.object.tracked) {
 			const binding = context.state.scope.get(node.object.name);
 
@@ -372,7 +419,13 @@ const visitors = {
 		const elements = [];
 
 		// Track metadata for this component
-		const metadata = { await: false };
+		const metadata = {
+			await: false,
+			styleClasses: /** @type {StyleClasses} */ (new Map()),
+		};
+
+		/** @type {TopScopedClasses} */
+		const topScopedClasses = new Map();
 
 		context.next({
 			...context.state,
@@ -388,7 +441,27 @@ const visitors = {
 			analyze_css(css);
 
 			for (const node of elements) {
-				prune_css(css, node);
+				prune_css(css, node, metadata.styleClasses, topScopedClasses);
+			}
+
+			if (topScopedClasses.size > 0) {
+				node.metadata.topScopedClasses = topScopedClasses;
+			}
+
+			if (metadata.styleClasses.size > 0) {
+				node.metadata.styleClasses = metadata.styleClasses;
+
+				if (!context.state.loose) {
+					for (const [className, property] of metadata.styleClasses) {
+						if (!topScopedClasses?.has(className)) {
+							return error(
+								`CSS class ".${className}" does not exist in ${node.id?.name ? node.id.name : "this component's"} <style> block`,
+								context.state.analysis.module.filename,
+								property,
+							);
+						}
+					}
+				}
 			}
 		}
 
@@ -677,13 +750,13 @@ const visitors = {
 
 		// Store capitalized name for dynamic components/elements
 		if (node.id.tracked) {
-			const original_name = node.id.name;
-			const capitalized_name = original_name.charAt(0).toUpperCase() + original_name.slice(1);
+			const source_name = node.id.name;
+			const capitalized_name = source_name.charAt(0).toUpperCase() + source_name.slice(1);
 			node.metadata.ts_name = capitalized_name;
-			node.metadata.original_name = original_name;
+			node.metadata.source_name = source_name;
 
 			// Mark the binding as a dynamic component so we can capitalize it everywhere
-			const binding = context.state.scope.get(original_name);
+			const binding = context.state.scope.get(source_name);
 			if (binding) {
 				if (!binding.metadata) {
 					binding.metadata = {};
@@ -889,13 +962,16 @@ export function analyze(ast, filename, options = {}) {
 
 	const { scope, scopes } = create_scopes(ast, scope_root, null);
 
-	const analysis = {
+	const analysis = /** @type {AnalysisResult} */ ({
 		module: { ast, scope, scopes, filename },
 		ast,
 		scope,
 		scopes,
 		component_metadata: [],
-	};
+		metadata: {
+			serverIdentifierPresent: false,
+		},
+	});
 
 	walk(
 		ast,

package/src/compiler/phases/2-analyze/prune.js

@@ -1,5 +1,5 @@
 /** @import * as AST from 'estree' */
-/** @import { Visitors } from '#compiler' */
+/** @import { Visitors, TopScopedClasses, StyleClasses } from '#compiler' */
 /** @typedef {0 | 1} Direction */
 
 import { walk } from 'zimmerframe';
@@ -15,6 +15,10 @@ const BACKWARD = 1;
 // since the code is synchronous, this is safe
 /** @type {string} */
 let css_hash;
+/** @type {StyleClasses} */
+let style_identifier_classes;
+/** @type {TopScopedClasses} */
+let top_scoped_classes;
 
 // CSS selector constants
 /**
@@ -27,6 +31,15 @@ function create_descendant_combinator(start, end) {
 }
 
 /**
+ * @param {AST.CSS.RelativeSelector} relative_selector
+ * @param {AST.CSS.ClassSelector} selector
+ * @returns {boolean}
+ */
+function is_standalone_class_selector(relative_selector, selector) {
+	return relative_selector.selectors.length === 1 && relative_selector.selectors[0] === selector;
+}
+
+/**`
  * @param {number} start
  * @param {number} end
  * @returns {AST.CSS.RelativeSelector}
@@ -211,7 +224,6 @@ function apply_selector(relative_selectors, rule, element, direction) {
 						if (!element.metadata.css) {
 							element.metadata.css = {
 								scopedClasses: new Map(),
-								topScopedClasses: new Map(),
 								hash: css_hash,
 							};
 						}
@@ -225,14 +237,12 @@ function apply_selector(relative_selectors, rule, element, direction) {
 							});
 						}
 
-						// Also store in topScopedClasses if standalone
-						// Standalone = only this ClassSelector in the RelativeSelector, no pseudo-classes/elements
-						const isStandalone =
-							relative_selector.selectors.length === 1 &&
-							relative_selector.selectors[0] === selector;
-
-						if (isStandalone && !element.metadata.css.topScopedClasses.has(name)) {
-							element.metadata.css.topScopedClasses.set(name, {
+						// Also store in top_scoped_classes if standalone selector
+						if (
+							is_standalone_class_selector(relative_selector, selector) &&
+							!top_scoped_classes.has(name)
+						) {
+							top_scoped_classes.set(name, {
 								start: selector.start,
 								end: selector.end,
 								selector: selector,
@@ -939,7 +949,11 @@ function relative_selector_might_apply_to_node(relative_selector, rule, element,
 			}
 
 			case 'ClassSelector': {
-				if (!attribute_matches(element, 'class', name, '~=', false)) {
+				if (
+					!attribute_matches(element, 'class', name, '~=', false) &&
+					(!style_identifier_classes.has(name) ||
+						!is_standalone_class_selector(relative_selector, selector))
+				) {
 					return false;
 				}
 
@@ -1047,10 +1061,14 @@ function rule_has_animation(rule) {
 /**
  * @param {AST.CSS.StyleSheet} css
  * @param {AST.Element} element
+ * @param {StyleClasses} styleClasses
+ * @param {TopScopedClasses} topScopedClasses
  * @return {void}
  */
-export function prune_css(css, element) {
+export function prune_css(css, element, styleClasses, topScopedClasses) {
 	css_hash = css.hash;
+	style_identifier_classes = styleClasses;
+	top_scoped_classes = topScopedClasses;
 
 	/** @type {Visitors<AST.CSS.Node, null>} */
 	const visitors = {

package/src/compiler/phases/2-analyze/validation.js

@@ -151,6 +151,10 @@ export function validate_nesting(element, context) {
 						context.state.analysis.module.filename,
 						element,
 					);
+				} else {
+					// if my parent has a set of invalid children
+					// and i'm not in it, then i'm valid
+					return;
 				}
 			}
 		}