ripple 0.2.2 → 0.2.4

package/README.md

@@ -0,0 +1,387 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/ripple-dark.png">
+  <img src="assets/ripple-light.png" alt="Ripple - the elegant UI framework for the web" />
+</picture>
+
+# What is Ripple?
+
+> Currently, this project is still in early development, and should not be used in production.
+
+Ripple is a TypeScript UI framework for the web.
+
+I wrote Ripple as a love letter for frontend web – and this is largely a project that I built in less than a week, so it's very raw.
+
+Personally, I ([@trueadm](https://github.com/trueadm)) have been involved in some truly amazing frontend frameworks along their journeys – from [Inferno](https://github.com/infernojs/inferno), where it all began, to [React](https://github.com/facebook/react) and the journey of React Hooks, to creating [Lexical](https://github.com/facebook/lexical), to [Svelte 5](https://github.com/sveltejs/svelte) and its new compiler and signal-based reactivity runtime. Along that journey, I collected ideas, and intriguing thoughts that may or may not pay off. Given my time between roles, I decided it was the best opportunity to try them out, and for open source to see what I was cooking.
+
+Ripple was designed to be a JS/TS-first framework, rather than HTML-first. Ripple modules have their own `.ripple` extension and these modules
+fully support TypeScript. By introducing a new extension, it affords Ripple to invent its own superset language, that plays really nicely with
+TypeScript and JSX, but with a few interesting touches. In my experience, this has led to better DX not only for humans, but also for LLMs.
+
+Right now, there will be plenty of bugs, things just won't work either and you'll find TODOs everywhere. At this stage, Ripple is more of an early alpha version of something that _might_ be, rather than something you should try and adopt. If anything, maybe some of the ideas can be shared and incubated back into other frameworks. There's also a lot of similarities with Svelte 5, and that's not by accident, that's because of my recent time working on Svelte 5.
+
+If you'd like to know more, join the [Ripple Discord](https://discord.gg/JBF2ySrh2W).
+
+## Features
+
+- **Reactive State Management**: Built-in reactivity with `$` prefixed variables
+- **Component-Based Architecture**: Clean, reusable components with props and children
+- **JSX-like Syntax**: Familiar templating with Ripple-specific enhancements
+- **TypeScript Support**: Full TypeScript integration with type checking
+- **VSCode Integration**: Rich editor support with diagnostics, syntax highlighting, and IntelliSense
+
+## Missing Features
+
+- **SSR**: Ripple is currently an SPA only, this is because I haven't gotten around to it
+- **Testing & Types**: The codebase is very raw with limited types (I've opted for JavaScript only to avoid build problems). There aren't any tests either – I've been using the `playground` directory to manually test things as I go
+
+## Quick Start
+
+### Try Ripple
+
+> We're working hard on getting an online playgroud available. Watch this space!
+
+You can try Ripple now by using our basic Vite template by running these commands in your terminal:
+
+```bash
+npx degit trueadm/ripple/templates/basic my-app
+cd my-app
+npm i # or yarn or pnpm
+npm run dev # or yarn or pnpm
+```
+
+### Mounting your app
+
+You can use the `mount` API from the `ripple` package to render your Ripple component, using the `target`
+option to specify what DOM element you want to render the component.
+
+```ts
+// index.ts
+import { mount } from 'ripple';
+import { App } from '/App.ripple';
+
+mount(App, {
+  props: {
+    title: 'Hello world!'
+  },
+  target: document.getElementById('root')
+});
+```
+
+## Key Concepts
+
+### Components
+
+Define reusable components with the `component` keyword. These are similar to functions in that they have `props`, but crucially,
+they allow for a JSX-like syntax to be defined alongside standard TypeScript. That means you do not _return JSX_ like in other frameworks,
+but you instead use it like a JavaScript statement, as shown:
+
+```ripple
+component Button(props: { text: string, onClick: () => void }) {
+  <button onClick={props.onClick}>
+    {props.text}
+  </button>
+}
+
+// Usage
+component App() {
+  <Button text="Click me" onClick={() => console.log("Clicked!")} />
+}
+```
+
+![iamge for the sourcecode above](assets/readme-1.png)
+
+Ripple's templating language also supports shorthands and object spreads too:
+
+```svelte
+// you can do a normal prop
+<div onClick={onClick}>{text}</div>
+
+// or using the shorthand prop
+<div {onClick}>{text}</div>
+
+// and you can spread props
+<div {...properties}>{text}</div>
+```
+
+### Reactive Variables
+
+Variables prefixed with `$` are automatically reactive:
+
+```ts
+let $name = "World";
+let $count = 0;
+
+// Updates automatically trigger re-renders
+$count++;
+```
+
+Object properties prefixed with `$` are also automatically reactive:
+
+```ts
+let counter = { $current: 0 };
+
+// Updates automatically trigger re-renders
+counter.$current++;
+```
+
+Derived values are simply `$` variables that combined different parts of state:
+
+```ts
+let $count = 0;
+let $double = $count * 2;
+let $quadruple = $double * 2;
+```
+
+That means `$count` itself might be derived if it were to reference another reactive property. For example:
+
+```ripple
+component Counter({ $startingCount }) {
+  let $count = $startingCount;
+  let $double = $count * 2;
+  let $quadruple = $double * 2;
+}
+```
+
+Now given `$startingCount` is reactive, it would mean that `$count` might reset each time an incoming change to `$startingCount` occurs. That might not be desirable, so Ripple provides a way to `untrack` reactivity in those cases:
+
+```ripple
+import { untrack } from 'ripple';
+
+component Counter({ $startingCount }) {
+  let $count = untrack(() => $startingCount);
+  let $double = $count * 2;
+  let $quadruple = $double * 2;
+}
+```
+
+Now `$count` will only reactively create its value on initialization.
+
+> Note: you cannot define reactive variables in module/global scope, they have to be created on access from an active component
+
+### Effects
+
+When dealing with reactive state, you might want to be able to create side-effects based upon changes that happen upon updates.
+To do this, you can use `effect`:
+
+```ripple
+import { effect } from 'ripple';
+
+component App() {
+  let $count = 0;
+
+  effect(() => {
+    console.log($count);
+  });
+
+  <button onClick={() => $count++}>Increment</button>
+}
+```
+
+### Control flow
+
+The JSX-like syntax might take some time to get used to if you're coming from another framework. For one, templating in Ripple
+can only occur _inside_ a `component` body – you can't create JSX inside functions, or assign it to variables as an expression.
+
+```ripple
+<div>
+  // you can create variables inside the template!
+  const str = "hello world";
+
+  console.log(str); // and function calls too!
+
+  debugger; // you can put breakpoints anywhere to help debugging!
+
+  {str}
+</div>
+```
+
+![iamge for the sourcecode above](assets/readme-5.png)
+
+Note that strings inside the template need to be inside `{"string"}`, you can't do `<div>hello</div>` as Ripple
+has no idea if `hello` is a string or maybe some JavaScript code that needs evaluating, so just ensure you wrap them
+in curly braces. This shouldn't be an issue in the real-world anyway, as you'll likely use an i18n library that means
+using JavaScript expressions regardless.
+
+### If statements
+
+If blocks work seemlessly with Ripple's templating language, you can put them inside the JSX-like
+statements, making control-flow far easier to read and reason with.
+
+```ripple
+component Truthy({ x }) {
+  <div>
+    if (x) {
+      <span>
+        {"x is truthy"}
+      </span>
+    } else {
+      <span>
+        {"x is falsy"}
+      </span>
+    }
+  </div>
+}
+```
+
+![iamge for the sourcecode above](assets/readme-2.png)
+
+### For statements
+
+You can render collections using a `for...of` block, and you don't need to specify a `key` prop like
+other frameworks.
+
+```ripple
+component ListView({ title, items }) {
+  <h2>{title}</h2>
+  <ul>
+    for (const item of items) {
+      <li>{item.text}</li>
+    }
+  </ul>
+}
+```
+
+![iamge for the sourcecode above](assets/readme-3.png)
+
+### Try statements
+
+Try blocks work to building the foundation for **error boundaries**, when the runtime encounters
+an error in the `try` block, you can easily render a fallback in the `catch` block.
+
+```ripple
+import { reportError } from 'some-library';
+
+component ErrorBoundary() {
+  <div>
+    try {
+      <ComponentThatFails />
+    } catch (e) {
+      reportError(e);
+
+      <div>{"An error occured! " + e.message}</div>
+    }
+  </div>
+}
+```
+
+![iamge for the sourcecode above](assets/readme-4.png)
+
+### Props
+
+If you want a prop to be reactive, you should also give it a `$` prefix.
+
+```ripple
+component Button(props: { $text: string, onClick: () => void }) {
+  <button onClick={props.onClick}>
+    {props.$text}
+  </button>
+}
+
+// Usage
+<Button $text={some_text} onClick={() => console.log("Clicked!")} />
+```
+
+### Children
+
+Use `$children` prop and then use it in the form of `<$children />` for component composition.
+
+When you pass in children to a component, it gets implicitly passed as the `$children` prop, in the form of a component.
+
+```ripple
+import type { Component } from 'ripple';
+
+component Card(props: { $children: Component }) {
+  <div class="card">
+    <$children />
+  </div>
+}
+
+// Usage
+<Card>
+  <p>{"Card content here"}</p>
+</Card>
+```
+
+You could also explicitly write the same code as shown:
+
+```ripple
+import type { Component } from 'ripple';
+
+component Card(props: { $children: Component }) {
+  <div class="card">
+    <$children />
+  </div>
+}
+
+// Usage with explicit component
+<Card>
+  component $children() {
+    <p>{"Card content here"}</p>
+  }
+</Card>
+```
+
+### Events
+
+Like React, events are props that start with `on` and then continue with an uppercase character, such as:
+
+- `onClick`
+- `onPointerMove`
+- `onPointerDown`
+- `onKeyDown`
+
+For `capture` phase events, just add `Capture` to the end of the prop name:
+
+- `onClickCapture`
+- `onPointerMoveCapture`
+- `onPointerDownCapture`
+- `onKeyDownCapture`
+
+> Note: Some events are automatically delegated where possible by Ripple to improve runtime performance.
+
+### Styling
+
+Ripple supports native CSS styling that is localized to the given component using the `<style>` element.
+
+```ripple
+component MyComponent() {
+  <div class="container">
+    <h1>{"Hello World"}</h1>
+  </div>
+  
+  <style>
+    .container {
+      background: blue;
+      padding: 1rem;
+    }
+    
+    h1 {
+      color: white;
+      font-size: 2rem;
+    }
+  </style>
+}
+```
+
+> Note: the `<style>` element must be top-level within a `component`.
+
+## VSCode Extension
+
+The [Ripple VSCode extension](https://marketplace.visualstudio.com/items?itemName=ripplejs.ripple-vscode-plugin) provides:
+
+- **Syntax Highlighting** for `.ripple` files
+- **Real-time Diagnostics** for compilation errors
+- **TypeScript Integration** for type checking
+- **IntelliSense** for autocompletion
+
+You can find the extension on the VS Code Marketplace as [`Ripple for VS Code`](https://marketplace.visualstudio.com/items?itemName=ripplejs.ripple-vscode-plugin).
+
+## Playground
+
+Feel free to play around with how Ripple works. If you clone the repo, you can then:
+
+```bash
+pnpm i && cd playground && pnpm dev
+```
+
+The playground uses Ripple's Vite plugin, where you can play around with things inside the `playground/src` directory.

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is a TypeScript UI framework for the web",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "module": "src/runtime/index.js",
   "main": "src/runtime/index.js",

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

@@ -9,8 +9,8 @@ function convert_from_jsx(node) {
 		node.type = 'Identifier';
 	} else if (node.type === 'JSXMemberExpression') {
 		node.type = 'MemberExpression';
-		node.object = convert_from_jsx(node.object)
-		node.property = convert_from_jsx(node.property)
+		node.object = convert_from_jsx(node.object);
+		node.property = convert_from_jsx(node.property);
 	}
 	return node;
 }
@@ -24,6 +24,38 @@ function RipplePlugin(config) {
 		class RippleParser extends Parser {
 			#path = [];
 
+			parseExportDefaultDeclaration() {
+				// Check if this is "export default component"
+				if (this.value === 'component') {
+					const node = this.startNode();
+					node.type = 'Component';
+					node.css = null;
+					node.default = true;
+					this.next();
+					this.enterScope(0);
+					
+					node.id = this.type.label === 'name' ? this.parseIdent() : null;
+					
+					this.parseFunctionParams(node);
+					this.eat(tt.braceL);
+					node.body = [];
+					this.#path.push(node);
+
+					this.parseTemplateBody(node.body);
+
+					this.#path.pop();
+					this.exitScope();
+
+					this.next();
+					this.finishNode(node, 'Component');
+					this.awaitPos = 0;
+
+					return node;
+				}
+				
+				return super.parseExportDefaultDeclaration();
+			}
+
 			shouldParseExportStatement() {
 				if (super.shouldParseExportStatement()) {
 					return true;
@@ -253,10 +285,7 @@ function RipplePlugin(config) {
 						case 62: // '>'
 						case 125: {
 							// '}'
-							if (
-								ch === 125 &&
-								(this.#path.at(-1).type === 'Component')
-							) {
+							if (ch === 125 && this.#path.at(-1).type === 'Component') {
 								return original.readToken.call(this, ch);
 							}
 							this.raise(
@@ -318,7 +347,7 @@ function RipplePlugin(config) {
 				if (open.name.type === 'JSXIdentifier') {
 					open.name.type = 'Identifier';
 				}
-				
+
 				element.id = convert_from_jsx(open.name);
 				element.attributes = open.attributes;
 				element.selfClosing = open.selfClosing;
@@ -364,6 +393,37 @@ function RipplePlugin(config) {
 				return element;
 			}
 
+			parseSubscript(base, startPos, startLoc, noCalls, maybeAsyncArrow, optionalChained, forInit) {
+				if (this.value === '<' && this.#path.findLast((n) => n.type === 'Component')) {
+					// Check if this looks like JSX by looking ahead
+					const ahead = this.lookahead();
+					if (ahead.type.label === 'name' || ahead.value === '/' || ahead.value === '>') {
+						// This is JSX, rewind to the end of the object expression
+						// and let ASI handle the semicolon insertion naturally
+						this.pos = base.end;
+						this.type = tt.braceR;
+						this.value = '}';
+						this.start = base.end - 1;
+						this.end = base.end;
+						const position = this.curPosition();
+						this.startLoc = position;
+						this.endLoc = position;
+						this.next();
+
+						return base;
+					}
+				}
+				return super.parseSubscript(
+					base,
+					startPos,
+					startLoc,
+					noCalls,
+					maybeAsyncArrow,
+					optionalChained,
+					forInit
+				);
+			}
+
 			parseTemplateBody(body) {
 				var inside_func =
 					this.context.some((n) => n.token === 'function') || this.scopeStack.length > 1;
@@ -456,10 +516,7 @@ function RipplePlugin(config) {
 			parseBlock(createNewLexicalScope, node, exitStrict) {
 				const parent = this.#path.at(-1);
 
-				if (
-					parent?.type === 'Component' ||
-					parent?.type === 'Element'
-				) {
+				if (parent?.type === 'Component' || parent?.type === 'Element') {
 					if (createNewLexicalScope === void 0) createNewLexicalScope = true;
 					if (node === void 0) node = this.startNode();
 

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

@@ -439,20 +439,6 @@ const visitors = {
 						attribute
 					);
 				}
-			} else if (name === 'ref') {
-				if (is_dom_element) {
-					error(
-						'Cannot have a `ref` prop on an element, did you mean `$ref`?',
-						state.analysis.module.filename,
-						attribute
-					);
-				} else {
-					error(
-						'Cannot have a `ref` prop on a component, did you mean `$ref`?',
-						state.analysis.module.filename,
-						attribute
-					);
-				}
 			}
 
 			if (is_tracked_name(name)) {

package/src/compiler/phases/3-transform/index.js

@@ -44,7 +44,7 @@ function visit_function(node, context) {
 
 	let body = context.visit(node.body, state);
 
-	if (metadata.tracked === true) {
+	if (metadata?.tracked === true) {
 		return /** @type {FunctionExpression} */ ({
 			...node,
 			params: node.params.map((param) => context.visit(param, state)),
@@ -66,7 +66,7 @@ function build_getter(node, context) {
 
 		// don't transform the declaration itself
 		if (node !== binding?.node && binding?.transform) {
-			return binding.transform.read(node);
+			return binding.transform.read(node, context.state?.metadata?.spread);
 		}
 	}
 
@@ -345,11 +345,9 @@ const visitors = {
 			);
 
 			if (is_spreading) {
-				if (spread_attributes.length === 0) {
-					state.template.push(attr_value);
-				} else {
-					spread_attributes.push(b.prop('init', b.literal(name), attr_value));
-				}
+				spread_attributes.push(b.prop('init', b.literal(name), attr_value));
+			} else {
+				state.template.push(attr_value);
 			}
 		};
 
@@ -411,18 +409,12 @@ const visitors = {
 							continue;
 						}
 
-						if (name === '$ref') {
-							const id = state.flush_node();
-							const value = attr.value;
-
-							state.init.push(b.stmt(b.call('$.set_ref', id, visit(value, state))));
-							continue;
-						}
-
 						if (is_event_attribute(name)) {
-							const event_name = name.slice(2).toLowerCase();
+							let capture = name.endsWith('Capture');
+							let event_name = capture
+								? name.slice(2, -7).toLowerCase()
+								: name.slice(2).toLowerCase();
 							let handler = visit(attr.value, state);
-							let capture = false; // TODO
 
 							if (attr.metadata?.delegated) {
 								let delegated_assignment;
@@ -554,8 +546,9 @@ const visitors = {
 
 			state.template.push('<!>');
 
+			const is_spreading = node.attributes.some((attr) => attr.type === 'SpreadAttribute');
 			const tracked = [];
-			let props = [];
+			const props = [];
 			let children_prop = null;
 
 			for (const attr of node.attributes) {
@@ -579,6 +572,15 @@ const visitors = {
 					} else {
 						props.push(b.prop('init', attr.name, visit(attr.value, state)));
 					}
+				} else if (attr.type === 'SpreadAttribute') {
+					props.push(
+						b.spread(
+							b.call(
+								'$.spread_object',
+								visit(attr.argument, { ...state, metadata: { ...state.metadata, spread: true } })
+							)
+						)
+					);
 				} else {
 					throw new Error('TODO');
 				}
@@ -602,7 +604,18 @@ const visitors = {
 				}
 			}
 
-			if (tracked.length > 0) {
+			if (is_spreading) {
+				state.init.push(
+					b.stmt(
+						b.call(
+							node.id,
+							id,
+							b.call('$.tracked_spread_object', b.thunk(b.object(props))),
+							b.id('$.active_block')
+						)
+					)
+				);
+			} else if (tracked.length > 0) {
 				state.init.push(
 					b.stmt(
 						b.call(

package/src/runtime/internal/client/constants.js

@@ -20,4 +20,5 @@ export var LOGIC_BLOCK = FOR_BLOCK | IF_BLOCK | TRY_BLOCK;
 
 export var UNINITIALIZED = Symbol();
 export var TRACKED_OBJECT = Symbol();
+export var SPREAD_OBJECT = Symbol();
 export var COMPUTED_PROPERTY = Symbol();

package/src/runtime/internal/client/index.js

@@ -7,7 +7,6 @@ export {
 	set_value,
 	set_checked,
 	set_selected,
-	set_ref
 } from './render.js';
 
 export { render, render_spread, async } from './blocks.js';
@@ -25,6 +24,7 @@ export {
 	async_computed,
 	tracked,
 	tracked_object,
+	tracked_spread_object,
 	computed_property,
 	get_property,
 	set_property,

package/src/runtime/internal/client/render.js

@@ -157,16 +157,6 @@ export function set_selected(element, selected) {
 	}
 }
 
-export function set_ref(dom, fn) {
-	effect(() => {
-		fn(dom);
-
-		return () => {
-			fn(null);
-		};
-	});
-}
-
 export function apply_element_spread(element, fn) {
 	return () => {
 		set_attributes(element, fn());

package/src/runtime/internal/client/runtime.js

@@ -18,6 +18,7 @@ import {
 	EFFECT_BLOCK,
 	PAUSED,
 	ROOT_BLOCK,
+	SPREAD_OBJECT,
 	TRACKED,
 	TRACKED_OBJECT,
 	TRY_BLOCK,
@@ -217,9 +218,9 @@ export function tracked(v, b) {
 	};
 }
 
-export function computed(fn, b) {
+export function computed(fn, block) {
 	return {
-		b,
+		b: block,
 		blocks: null,
 		c: 0,
 		d: null,
@@ -644,7 +645,7 @@ export function flush_sync(fn) {
 	var previous_queued_root_blocks = queued_root_blocks;
 
 	try {
-		const root_blocks = [];
+		var root_blocks = [];
 
 		scheduler_mode = FLUSH_SYNC;
 		queued_root_blocks = root_blocks;
@@ -667,6 +668,17 @@ export function flush_sync(fn) {
 	}
 }
 
+export function tracked_spread_object(fn) {
+	var obj = fn();
+
+	define_property(obj, SPREAD_OBJECT, {
+		value: fn,
+		enumerable: false
+	});
+
+	return obj;
+}
+
 export function tracked_object(obj, properties, block) {
 	var tracked_properties = obj[TRACKED_OBJECT];
 
@@ -719,6 +731,10 @@ export function get_property(obj, property, chain = false) {
 
 	if (tracked_property !== undefined) {
 		value = obj[property] = get(tracked_property);
+	} else if (SPREAD_OBJECT in obj) {
+		var spread_fn = obj[SPREAD_OBJECT];
+		var properties = spread_fn();
+		return get_property(properties, property, chain);
 	}
 
 	return value;
@@ -851,11 +867,11 @@ export function spread_object(obj) {
 		return { ...obj };
 	}
 	var keys = original_object_keys(obj);
-	const values = {};
+	var values = {};
 
 	for (var i = 0; i < keys.length; i++) {
 		var key = keys[i];
-		values[key] = get_property_computed(obj, key);
+		values[key] = get_property(obj, key);
 	}
 
 	return values;

package/src/runtime/internal/client/try.js

@@ -109,13 +109,13 @@ export function capture() {
 	var previous_tracking = tracking;
 	var previous_block = active_block;
 	var previous_reaction = active_reaction;
-    var previous_component = active_component;
+	var previous_component = active_component;
 
 	return () => {
 		set_tracking(previous_tracking);
 		set_active_block(previous_block);
 		set_active_reaction(previous_reaction);
-        set_active_component(previous_component);
+		set_active_component(previous_component);
 
 		queue_microtask(exit);
 	};

package/types/index.d.ts

@@ -1,4 +1,4 @@
-export type Component<T> = (props: T) => void;
+export type Component<T = Record<string, any>> = (props: T) => void;
 
 export declare function mount(
 	component: () => void,