# Ripple TS Framework - AI/LLM Documentation

## Overview

Ripple is a TypeScript UI framework that combines the best parts of React, Solid, and Svelte into one elegant package. Created by Dominic Gannaway ([@trueadm](https://github.com/trueadm)), Ripple is designed to be JS/TS-first with `.tsrx` as its default component file extension while preserving `.tsrx` compatibility.

**Key Characteristics:**
- **Performance**: Fine-grain rendering, with industry-leading performance, bundle-size and memory usage
- **TypeScript-first**: Full TypeScript integration with type checking
- **JSX-like syntax**: Familiar templating with TSRX-specific enhancements
- **Reactive state**: Built-in reactivity with `track` and `&[]` lazy destructuring syntax
- **Component-based**: Clean, reusable components with props and children

## Installation & Setup

```bash
# Create new project from template
npx degit Ripple-TS/ripple/templates/basic my-app
cd my-app
pnpm install && pnpm dev

# Or install in existing project
pnpm add ripple
pnpm add -D '@ripple-ts/vite-plugin'  # For Vite integration
```

## Core Syntax & Concepts

### Component Definition

Components are ordinary TypeScript functions that return TSRX. Use a capitalized
function name, accept props as the first parameter, and return either a single
TSRX element or a fragment.

Direct calls keep ordinary helper semantics. A PascalCase helper such as
`StatusCode()` or `FormatName()` is left as a normal function when called
directly; component compilation applies to functions used as components or render
entries, and to functions that return native TSRX without being directly called.

```ripple
function Button(props: { text: string; onClick: () => void }) {
  return <button onClick={props.onClick}>{props.text}</button>;
}

export function App() {
  return <Button text="Click me" onClick={() => console.log('Clicked!')} />;
}
```

Use a fragment when the body needs statements, control flow, locals, or scoped
styles. Opening a TSRX expression is expression-based; inside it, TSRX uses a
template statement list.

```ripple
export function Panel({ title, children }: { title: string; children: any }) {
  return <>
    const heading = title.trim();

    <section class="panel">
      <h2>{heading}</h2>
      <div>{children}</div>
    </section>

    <style>
      .panel { padding: 1rem; }
    </style>
  </>;
}
```

**LLM DO:**
- Use `function Name(props: Props) { return ... }` for UI building blocks.
- Use `export function` for public components.
- Return `<div />` directly for compact UI.
- Return `<>...</>` when the template includes multiple statements.
- Keep inline `<style>` blocks inside the TSRX fragment/expression they style.
- Use module-scope `<style>` expressions for reusable class maps.
- Treat `<style>` contents as static CSS, and use CSS custom properties for
  runtime style values.

**LLM DON'T:**
- Do not invent a custom declaration form for components.
- Do not claim TSRX templates are restricted to special declarations or bodies.
- Do not put JavaScript statements, control flow, or `{expr}` interpolation
  inside `<style>` blocks.
- Use native TSRX elements or fragments directly when storing, passing, or
  returning UI.

### TSRX Expressions

TSRX is the default JSX-like expression form in `.tsrx` files. UI can be
returned from functions, assigned to variables, or passed as props anywhere a
TypeScript expression is allowed. The interior remains TSRX, so direct
quote-delimited text children and statement control flow still work.

```ripple
function createBadge(label: string) {
  return <span class="badge">{label}</span>;
}

function App() {
  const title = <span class="title">"Settings"</span>;

  return <>
    <header>{title}</header>
    {createBadge('New')}
  </>;
}
```

### ⚠️ Critical: Text Content Must Be Explicit

**IMPORTANT**: Unlike HTML or JSX, Ripple elements cannot contain raw unquoted
text content. Static text may be written as a direct double-quoted text child.
Variables, single-quoted strings, template literals, and other JavaScript
expressions must be wrapped in curly braces `{}`.

```ripple
// ❌ WRONG - Raw unquoted text not allowed
<div>Hello World</div>
<p>This will cause a compilation error</p>

// ✅ CORRECT - Static text as direct double-quoted children
<div>"Hello World"</div>
<p>"This works correctly"</p>
<p>"Use &quot; for a quote and &amp; for an ampersand"</p>

// ✅ CORRECT - JavaScript strings in expressions
<div>{'Hello World'}</div>
<p>{"This works correctly"}</p>

// ✅ CORRECT - Variables and expressions
<div>{greeting}</div>
<p>{`Dynamic content: ${value}`}</p>
```

This is because Ripple needs to distinguish between JavaScript code and literal
strings within the template syntax. The parser cannot determine if `Hello` is
meant to be a string literal or a JavaScript identifier unless static text is
explicitly double-quoted or dynamic content is wrapped in `{}`.

Direct double-quoted text children use the same character-reference behavior as
quoted JSX attribute values. Use entities such as `&quot;` and `&amp;` for literal
characters that need escaping; backslashes are literal text and do not escape the
closing quote.

### Guard Returns

Functions are just functions. A Ripple component can return `null`, a TSRX
element, or any value accepted by the runtime before the returned TSRX expression
opens. `return` statements are not valid inside TSRX element or fragment bodies.

```ripple
function AuthGate({ is_logged_in }) {
  if (!is_logged_in) {
    return null;
  }

  return <h1>"Dashboard"</h1>
}
```

**LLM DO:**
- Use `return null;` for empty/fallback component output.
- Use ordinary function returns when a helper creates UI.
- Keep statement-rich UI inside a TSRX fragment.

**LLM DON'T:**
- Do not describe `return;` as the only legal guard form.
- Do not translate new Ripple examples away from ordinary function returns.
- Do not put `return` statements inside TSRX element or fragment bodies.

### Template Lexical Scoping

**Unique Feature**: Ripple templates act as lexical scopes, allowing you to declare variables, call functions, and execute JavaScript statements directly within JSX elements - similar to block statements in regular JavaScript.

```ripple
function TemplateScope() {
  return <div>
    // Variable declarations inside templates
    const message = "Hello from template scope";
    let count = 42;

    // Function calls and expressions
    console.log("This runs during render");

    // Conditional logic
    const isEven = count % 2 === 0;

    <h1>{message}</h1>
    <p>"Count is: "{count}</p>

    if (isEven) {
      <span>"Count is even"</span>
    }

    // Nested scopes work too
    <section>
      const sectionData = "Nested scope variable";
      <p>{sectionData}</p>
    </section>

    // You can even put debugger statements
    debugger;
  </div>;
}
```

**Key Benefits:**
- **Inline Logic**: Execute JavaScript directly where you need it in the template
- **Local Variables**: Declare variables scoped to specific parts of your template
- **Debugging**: Place `console.log()` or `debugger` statements anywhere in templates
- **Dynamic Computation**: Calculate values inline without helper functions

**Scope Rules:**
- Variables declared in templates are scoped to that template block
- Nested elements create nested scopes
- Variables from outer scopes are accessible in inner scopes
- Template variables don't leak to the function scope

### Reactive Variables

You use `track` to create a single tracked value. The `track` function creates a `Tracked<V>` object. Use lazy destructuring with `&[...]` to unwrap the tracked value into a reactive variable:

```ripple
import { track } from 'ripple';

export function Counter() {
  let &[count] = track(0);
  let &[double] = track(() => count * 2);  // Derived reactive value

  return <div>
    <p>"Count: "{count}</p>
    <p>"Double: "{double}</p>
    <button onClick={() => count++}>"Increment"</button>
  </div>;
}
```

**IMPORTANT:** You must use `track()` with lazy destructuring `&[...]` to create reactive variables:

```ripple
import { track } from 'ripple';

// CORRECT:
let &[count] = track(0);   // Create with track() and &[] destructuring
count++;                    // Read/write directly

// Access the tracked ref as the second element:
let &[count, countTracked] = track(0);
```

#### Accessing Tracked Values with `.value`

As an alternative to lazy destructuring, you can read and write a tracked value directly using the `.value` property on the `Tracked<V>` object:

```ripple
import { track } from 'ripple';

const count = track(0);

// Read the current value
console.log(count.value);  // 0

// Write a new value
count.value++;
console.log(count.value);  // 1
```

Using `&[...]` lazy destructuring is typically preferred in most cases because it produces cleaner, more readable code. However, `.value` is useful when you need top performance, especially in hots paths, or to keep the `Tracked<V>` object around — for example, when storing tracked values in data structures, passing them as props typed as `Tracked<T>`, or when you need both the tracked object and its value in different contexts:

```ripple
import { track } from 'ripple';

// Storing tracked values in an array — use .value to read/write
const items = [track(1), track(2), track(3)];
items[0].value++;  // reactively updates

// Passing tracked objects as props — the child receives the Tracked<T> object
function Child(props: { count: Tracked<number> }) {
  return <div>{props.count.value}</div>
}

// Using &[value, trackedValue] gives you both:
let &[count, countTracked] = track(0);
count++;                    // convenient direct access via lazy destructuring
console.log(countTracked.value);  // equivalent: read via .value on the tracked object
```

Objects can also contain tracked values — use lazy destructuring to access them:
```ripple
import { track } from 'ripple';

let counter = { current: track(0) };
let &[current] = counter.current;
current++;  // Triggers reactivity
```

Tracked derived values are also `Tracked<V>` objects, except you pass a function to `track` rather than a value:

```ripple
import { track } from 'ripple';

let &[count] = track(0);
let &[double] = track(() => count * 2);
let &[quadruple] = track(() => double * 2);

console.log(quadruple);
```

If you want to use a tracked value inside a reactive context, such as an effect but you don't want that value to be a tracked dependency, you can use `untrack`:

```ripple
import { track, effect, untrack } from 'ripple';

let &[count] = track(0);
let &[double] = track(() => count * 2);
let &[quadruple] = track(() => double * 2);

effect(() => {
  // This effect will never fire again, as we've untracked the only dependency it has
  console.log(untrack(() => quadruple));
})
```

> Note: you cannot create `Tracked` objects in module/global scope, they have to be created on access from an active component context.

#### track with get / set

The optional get and set parameters of the `track` function let you customize how a tracked value is read or written, similar to property accessors but expressed as pure functions. The get function receives the current stored value and its return value is exposed when the tracked value is read via `&[]` destructuring. The set function should return the value that will actually be stored and receives two parameters: the first is the one being assigned and the second with the previous value.  The get and set functions may be useful for tasks such as logging, validating, or transforming values before they are exposed or stored.

```ripple
import { track } from 'ripple';

export function App() {
  let &[count] = track(0,
    (current) => {
      console.log(current);
      return current;
    },
    (next, prev) => {
      console.log(prev);
      if (typeof next === 'string') {
        next = Number(next);
      }

      return next;
    }
  );

  return <button onClick={()=>count++}>{count}</button>;
}
```

> Note: If no value is returned from either `get` or `set`, `undefined` is either exposed (for get) or stored (for set). Also, if only supplying the `set`, the `get` parameter must be set to `undefined`.

#### Lazy Destructuring (`&{...}` / `&[...]`)

Lazy destructuring uses the `&` prefix directly before `{` or `[` in a destructuring pattern. Instead of eagerly pulling values out of the source object, lazy destructuring compiles each variable access to a deferred property/index lookup on the source. This preserves reactivity for reactive props and other tracked objects.

```ripple
// Lazy object destructuring
const &{ a, b } = props;
// Compiles to: a → props.a, b → props.b (accessed lazily)

// Lazy array destructuring
const &[first, second] = items;
// Compiles to: first → items[0], second → items[1]

// With default values
const &{ x = 10 } = props;
// Compiles to: x → _$_.fallback(props.x, 10)

// With rest patterns
const &{ a, ...rest } = props;
// Compiles to: a → props.a, rest → { ...props, a: undefined } (lazily)
```

**Component props** — use `&{...}` to lazily destructure props, preserving reactivity:

```ripple
function Child(&{ count, className, children }: Props) {
  return <>
		// count, className, children are lazily read from __props
		<button class={className}>{children}</button>
		<pre>"Count is: "{count}</pre>
  </>;
}
```

**Function parameters** — works in regular functions too:

```ripple
function process(&{ x, y }: Point) {
  return x + y; // lazily reads from the parameter object
}
```

**Variable declarations** — lazy destructuring works with `const`, `let`, and `var`:

```ripple
const &{ a, b } = someObject;     // read-only lazy access
let &{ x, y } = mutableObject;    // supports assignment: x = 5 writes back to mutableObject.x
```

> **When to use lazy destructuring**: Use `&{...}` whenever you destructure reactive props or tracked objects and need the variables to remain reactive. Regular destructuring (`{ a, b } = obj`) eagerly copies values and loses reactivity.

### Transporting Reactivity

**Critical Concept**: Ripple doesn't constrain reactivity to components only. `Tracked<V>` objects can simply be passed by reference between boundaries to improve expressivity and co-location.

#### Basic Transport Pattern
```ripple
import { track, effect } from 'ripple';

function createDouble(&[count]) {
  const &[double] = track(() => count * 2);

  effect(() => {
    console.log('Count:', count)
  });

  return double;
}

export function App() {
  let &[count, countTracked] = track(0);

  const &[double] = createDouble(countTracked);

  return <>
  	<div>"Double: "{double}</div>
  	<button onClick={() => { count++; }}>"Increment"</button>
  </>;
}
```

#### Dynamic Component Transport Pattern

Ripple has built-in support for dynamic components, a way to render different components based on reactive state. Instead of hardcoding which function to show, you can store a function in a `Tracked` via `track()`, and update it at runtime. When the tracked value changes, Ripple automatically unmounts the previous function and mounts the new one. Dynamic components are written with the `<@Component />` tag, where `@` is a special marker that tells the compiler the function or element is dynamic — it does not dereference or unwrap the value. The expression after `@` (e.g., `swapMe` in `<@swapMe />`) is treated as a `Tracked` value, and the runtime handles unwrapping it internally. This makes it straightforward to pass components as props or swap them directly within a component, enabling flexible, state-driven UIs with minimal boilerplate.

```ripple
import { track } from 'ripple';

export function App() {
  let &[swapMe, swapMeTracked] = track(() => Child1);

  return <>
  	<Child swapMe={swapMeTracked} />

  	<button onClick={() => swapMe = swapMe === Child1 ? Child2 : Child1}>"Swap Component"</button>
  </>;
}

function Child(&{ swapMe }: {swapMe: Tracked<Component>}) {
  return <@swapMe />
}

function Child1(props) {
  return <pre>"I am child 1"</pre>
}

function Child2(props) {
  return <pre>"I am child 2"</pre>
}
```

**Transport Rules:**
- Reactive state must be connected to a component
- Cannot be global or created at module/global scope
- Use arrays `[ trackedVar ]` or objects `{ trackedVar }` to transport reactivity
- Functions can accept and return reactive state using these patterns
- This enables composable reactive logic outside of component boundaries

### Control Flow

#### If Statements
```ripple
function Conditional({ isVisible }) {
  return <div>
		if (isVisible) {
			<span>"Visible content"</span>
		} else {
			<span>"Hidden state"</span>
		}
	</div>;
}
```

#### Switch Statements
Switch statements in Ripple provide a powerful way to conditionally render content based on the value of an expression. They are fully reactive and integrate seamlessly with Ripple's templating syntax.

**Key Features:**
- **Reactivity:** Works with both static and reactive (`Tracked`) values.
- **Control Flow:** Full support of standard JS with `break` statements and fall-through's.
- **Template Integration:** `case` blocks can contain any valid Ripple template content, including other components, elements, and logic.

**Basic Usage:**
The `switch` statement evaluates an expression and matches its value against a series of `case` clauses.

```ripple
function StatusIndicator({ status }) {
  return <>
		// The switch statement evaluates the 'status' prop
		switch (status) {
			case: 'init':
				// fall-through to the next
			case 'loading':
				<p>"Loading..."</p>
				break; // break is mandatory
			case 'success':
				<p>"Success!"</p>
				break;
			case 'error':
				<p>"Error!"</p>
				break;
			default:
				<p>"Unknown status"</p>
				// No break needed for default
		}
  </>;
}
```

`switch` statements can also react to changes in `Tracked` variables. When the tracked variable changes, the `switch` statement will re-evaluate and render the appropriate `case`.

```ripple
import { track } from 'ripple';

function InteractiveStatus() {
  let &[status] = track('loading'); // Reactive state

  <button onClick={() => status = 'success'}>"Set to Success"</button>
  <button onClick={() => status = 'error'}>"Set to Error"</button>

  return <>
		// This switch block will update automatically when 'status' changes
		switch (status) {
			case 'init':
				<p>"Status: Init"</p>
				// fall-through to the next
			case 'loading':
				<p>"Status: Loading..."</p>
				break;
			case 'success':
				<p>"Status: Success!"</p>
				break;
			case 'error':
				<p>"Status: Error!"</p>
				break;
			default:
				<p>"Status: Unknown"</p>
		}
  </>;
}
```

#### For Loops
```ripple
function List({ items }) {
  return <ul>
			for (const item of items) {
				<li>{item.text}</li>
			}
		</ul>
}
```

#### For Loops with index
```ripple
function ListView({ title, items }) {
  return <>
		<h2>{title}</h2>
		<ul>
			for (const item of items; index i) {
				<li>{item.text}" at index "{i}</li>
			}
		</ul>
  </>;
}
```

#### For Loops with key
```ripple
function ListView({ title, items }) {
  return <>
		<h2>{title}</h2>
		<ul>
			for (const item of items; index i; key item.id) {
				<li>{item.text}" at index "{i}</li>
			}
		</ul>
  </>;
}
```

**Key Usage Guidelines:**
- **Arrays with `RippleObject` instances**: Keys are usually unnecessary - object identity and reactivity handle updates automatically. Identity-based loops are more efficient with less bookkeeping.
- **Arrays with plain objects**: Keys are needed when object reference isn't sufficient for identification. Use stable identifiers: `key item.id`.

#### Dynamic Elements
```ripple
import { track } from 'ripple';

export function App() {
  let &[tag] = track('div');

  return <>
		<@tag class="dynamic">"Hello World"</@tag>
		<button onClick={() => tag = tag === 'div' ? 'span' : 'div'}>"Toggle Element"</button>
  </>;
}
```

#### Try-Catch (Error Boundaries)
```ripple
function ErrorBoundary() {
  return <div>
		try {
			<ComponentThatMightFail />
		} catch (e) {
			<div>"Error: "{e.message}</div>
		}
	</div>;
}
```

The `catch` block receives a `reset` function as its second argument. Calling
`reset()` clears the error state and re-renders the children:

```ripple
function RetryBoundary() {
  return <div>
		try {
			<ComponentThatMightFail />
		} catch (e, reset) {
			<div>
				<p>"Error: "{e.message}</p>
				<button onClick={() => reset()}>"Try again"</button>
			</div>
		}
	</div>
}
```

### Children Components

Use the `children` prop for component composition. Use the `Children` type to accept one or more children. If you need to pass additional child components such as `Header`, `Footer`, or `InlineComp`, define them in scope and pass them as explicit props on the component element. Do not declare `function Foo() {
  return <>
  </>;}` directly inside another component's child content.

```ripple
import type { Children, Component } from 'ripple';

function Card(props: { children: Children; Footer?: Component }) {
  return <div class="card">
			{props.children}
			if (props.Footer) {
				<props.Footer />
			}
		</div>
}

function Footer() {
  return <button>"OK"</button>
}

// Usage
<Card Footer={Footer}>
  <p>"Card content here"</p>
</Card>
```

### Events

#### Attribute Event Handling

Events follow React-style naming (`onClick`, `onPointerMove`, etc.):

```ripple
import { track } from 'ripple';

function EventExample() {
  let &[message] = track("");

  return <div>
		<button onClick={() => message = "Clicked!"}>"Click me"</button>
		<input onInput={(e) => message = e.target.value} />
		<p>{message}</p>
	</div>;
  );
}
```

For capture phase events, add `Capture` suffix:
- `onClickCapture`
- `onPointerDownCapture`

#### Direct Event Handling

Use function `on` to attach events to window, document or any other element instead of addEventListener.
This method guarantees the proper execution order with respect to attribute-based handlers such as `onClick`, and similarly optimized through event delegation for those events that support it.

```ripple
import { on, effect } from 'ripple';

export function App() {
  effect(() => {
    // on component mount
    const removeListener = on(window, 'resize', () => {
      console.log('Window resized!');
    });

    // return the removeListener when the component unmounts
    return removeListener;
  });

  return <></>;
}
```

### Styling

Components support scoped CSS with `<style>` elements:

`<style>` blocks contain static CSS. TSRX template rules for JavaScript
statements and expressions do not apply inside them, so do not put `{expr}`,
`if`, `for`, or declarations in a style block. Use CSS custom properties for
runtime values: set them on an element with `style={{ '--name': value }}` and
read them from static CSS with `var(--name)`.

```ripple
function StyledComponent() {
  return <>
		<div class="container">
			<h1>"Styled Content"</h1>
		</div>

		<style>
			.container {
				background: blue;
				padding: 1rem;
			}
			h1 {
				color: white;
				font-size: 2rem;
			}
		</style>
  </>;
}
```

#### Style Scoping

Styles defined in a `<style>` block are **automatically scoped** to the returned TSRX template where they are defined. Ripple achieves this by adding a unique hash-based class (e.g., `ripple-abc123`) to all elements in that template and rewriting the CSS selectors to include that hash.

**Important**: Scoped styles of a parent component do NOT apply to child components. Each component's styles are isolated. This means:

```ripple
function Parent() {
  return <>
		<div class="wrapper">
			<Child />  // .wrapper styles will NOT affect elements inside Child
		</div>

		<style>
			.wrapper { padding: 20px; }      // Only applies to THIS component's .wrapper
			.child-class {
				color: red;
			}     // Will NOT work - can't reach into Child
		</style>
  </>;
}

function Child() {
  return <div class="child-class">"I won't be red"</div>;
}
```

#### Style Composition via Style Expressions

Because scoped classes don't cross component boundaries, assigning a `<style>`
expression to a variable exposes a class map. Each standalone class maps to a
string containing both the scope hash and the class name. Pass those values to
children through normal props.

```ripple
function Badge({ class: className }: { class?: string }) {
  return <>
		<span class={`badge ${className ?? ''}`}>"New"</span>
		<style>
			.badge { padding: 0.25rem 0.5rem; }
		</style>
  </>;
}

function App() {
  const styles = <style>
    .highlight { background: #e8f5e9; color: #2e7d32; }
  </style>;

  return <Badge class={styles.highlight} />;
}
```

Style expressions can also live at module scope. Use this for StyleX-like or
CSS-in-JS-like reusable class maps when the styles should be declared before the
components that reference them. The CSS inside the style expression is still
static CSS; dynamic values should still flow through CSS custom properties:

```ripple
const articleStyles = <style>
  .card { padding: 1rem; }
  .title { font-weight: 700; }
</style>;

export function ArticleCard({ title }: { title: string }) {
  // Ripple host elements:
  return <article class={articleStyles.card}>
    <h2 class={articleStyles.title}>{title}</h2>
  </article>;
}
```

Inline `<style>` blocks inside a returned TSRX template are scoped to that
returned template. Module-scope style expressions are reusable class maps and
are not tied to one returned fragment.

Style expression maps expose standalone selectors from their `<style>` value.
Classes that only appear as part of compound/descendant selectors are not
exported on the map.

#### Global Styles with `:global()`

To escape scoping and apply styles globally (or to reach into child components), use the `:global()` modifier:

```ripple
function Parent() {
  return <>
		<div class="wrapper">
			<Child />
		</div>

		<style>
			.wrapper { padding: 20px; }              // Scoped to this component

			:global(.child-class) { color: red; }   // Applies globally - will reach Child

			.wrapper :global(.nested) {             // Scoped .wrapper, global .nested
				font-weight: bold;
			}
		</style>
  </>;
}
```

The `:global()` modifier can wrap:
- A single selector: `:global(.class-name)`
- Multiple selectors: `:global(.foo, .bar)`
- Part of a selector chain: `.scoped :global(.unscoped) .also-scoped`
```

#### Dynamic Classes

In Ripple, the `class` attribute can accept more than just a string — it also supports objects and arrays. Truthy values are included as class names, while falsy values are omitted. This behavior is powered by the `clsx` library.

Examples:

```ripple
import { track } from 'ripple';

let &[includeBaz] = track(true);
<div class={{ foo: true, bar: false, baz: includeBaz }}></div>
// becomes: class="foo baz"

<div class={['foo', {baz: false}, 0 && 'bar', [true && 'bat'] ]}></div>
// becomes: class="foo bat"

let &[count] = track(3);
<div class={['foo', {bar: count > 2}, count > 3 && 'bat']}></div>
// becomes: class="foo bar"
```

#### Dynamic CSS Values

Styles in `<style>` blocks are static CSS. When a value needs to change at runtime, put that value in a CSS custom property on the element and read it with `var(...)` from your static CSS:

```ripple
import { track } from 'ripple';

function App() {
  let &[color] = track('red');

  return <>
		<div class="notice" style={{ '--notice-color': color }}>
			"Styled text"
		</div>
		<button onClick={() => (color = color === 'red' ? 'blue' : 'red')}>
			"Toggle Color"
		</button>

		<style>
			.notice {
				color: var(--notice-color);
				font-weight: bold;
				background-color: gray;
			}
		</style>
  </>;
}
```

### DOM References (Refs)

Ripple supports DOM refs with the normal JSX `ref` attribute shape:

- `ref={expr}` — one ref for the current element or component.
- `ref={[a, b]}` — multiple refs for the same element.

Refs accept callbacks, `Tracked` values for reactive assignments, and mutable
identifiers/member expressions. Mutable refs are assigned when the element
mounts and cleared when it unmounts.

```ripple
import { track } from 'ripple';

export function App() {
  let div: HTMLDivElement | null | undefined;
  const input = track<HTMLInputElement | null>(null);
  const state: { button?: HTMLButtonElement } = {};

  return <>
		<div ref={div}>"Hello world"</div>
		<input ref={input} type="text" />
		<button ref={[state.button, (node) => console.log("mounted", node)]}>"Log"</button>
  </>;
}
```

Components receive `ref={...}` as a prop. Forward it explicitly or include it in
a spread onto the host element that should be exposed. Named props such as
`inputRef` are ordinary component API props; pass them into `ref={...}` inside
the receiving component when you want to forward them.

```ripple
function Field({ inputRef, ...rest }) {
  return <label>
			"Search"
			<input ref={inputRef} type="search" {...rest} />
		</label>
}

export function App() {
  let input: HTMLInputElement | null | undefined;
  return <Field inputRef={input} placeholder="Search docs" />;
}
```

Use `createRefKey()` when refs need to be assembled programmatically and applied
through object spread.

## Built-in APIs

### Core Functions
```typescript
import {
  mount,           // Mount component to DOM
  flushSync,       // Synchronous state updates
} from 'ripple';
```

### Mount API

Use `mount()` to render a component to the DOM for client-side only applications:

```typescript
import { mount } from 'ripple';
import { App } from './App.tsrx';

const cleanup = mount(App, {
  target: document.getElementById('root')!,
  props: { title: 'Hello world!' }
});

// To unmount later:
cleanup();
```

### Hydrate API

Use `hydrate()` when your HTML was server-rendered and you need to make it interactive:

```typescript
import { hydrate } from 'ripple';
import { App } from './App.tsrx';

const cleanup = hydrate(App, {
  target: document.getElementById('root')!,
  props: { title: 'Hello world!' }
});
```

**When to use each:**
- `mount()`: Client-side only (SPA). Clears target and renders fresh DOM.
- `hydrate()`: SSR apps. Adopts existing server-rendered HTML without re-creating elements.

### Server-Side Rendering

On the server, use `render()` from `ripple/server`:

```typescript
import { render } from 'ripple/server';
import { App } from './App.tsrx';

// Render to string
const html = render(App, {
  props: { title: 'Hello world!' }
});
```

### Effects
```ripple
import { track, effect } from 'ripple';

export function App() {
	let &[count] = track(0);

  effect(() => {
    console.log("Count changed:", count);
  });

  return <button onClick={() => count++}>"Increment"</button>;
}
```

### After Update tick()

The `tick()` function returns a Promise that resolves after all pending reactive updates have been applied to the DOM. This is useful when you need to ensure that DOM changes are complete before executing subsequent code, similar to Vue's `nextTick()` or Svelte's `tick()`.

```ripple
import { tick, track, effect } from 'ripple';

export function App() {
  let &[count] = track(0);

  effect(() => {
    count;

    if (count === 0) {
      console.log('initial run, skipping');
      return;
    }

    tick().then(() => {
      console.log('after the update');
    });
  });

  return <button onClick={() => count++}>"Increment"</button>;
}
```

### Context

Ripple has the concept of `context` where a value or reactive object can be shared through the component tree –
like in other frameworks. This all happens from the `Context` class that is imported from `ripple`.

Creating contexts may take place anywhere. Contexts can contain anything including tracked values or objects. However, context cannot be read via `get` or written to via `set` inside an event handler or at the module level as it must happen within the context of a component. A good strategy is to assign the contents of a context to a variable via the `.get()` method during the component initialization and use this variable for reading and writing.

When Child components overwrite a context's value via `.set()`, this new value will only be seen by its descendants. Components higher up in the tree will continue to see the original value.

Example with tracked / reactive contents:

```ripple
import { Context, track } from 'ripple';

// create context with an empty object
const context  = new Context({});
const context2 = new Context();

export function App() {
  // get reference to the object
  const obj = context.get();
  // set your reactive value
  let &[objCount, objCountTracked] = track(0);
  obj.count = objCountTracked;

  // create another tracked variable
  let &[count2, count2Tracked] = track(0);
  // context2 now contains a tracked variable
  context2.set(count2Tracked);

	return <>
		<button onClick={() => { objCount++; count2++ }}>
			"Click Me"
		</button>

		// context's reactive property count gets updated
		<pre>"Context: "{objCount}</pre>
		<pre>"Context2: "{count2}</pre>
  </>;
}
```

Passing data between components:

```ripple
import { Context } from 'ripple';

const MyContext = new Context(null);

function Child() {
  // Context is read in the Child component
  const value = MyContext.get();

  // value is "Hello from context!"
  console.log(value);

  return <p>"Value in Child: "{value}</p>;
}

function Parent() {
  const value = MyContext.get();

  // Context is read in the Parent component, but hasn't yet
  // been set, so we fallback to the initial context value.
  // So the value is `null`
  console.log(value);

  // Context is set in the Parent component
  MyContext.set("Hello from context!");

  return <Child />
}
```

### Reactive Collections

#### Simple Reactive Array

Just like objects, you can use the `Tracked<V>` objects in any standard JavaScript object, like arrays:

```ripple
import { track } from 'ripple';

let &[first, firstTracked] = track(0);
let &[second, secondTracked] = track(0);
const arr = [firstTracked, secondTracked];

const &[total] = track(() => arr.reduce((a, b) => a + b, 0));

console.log(total);
```

Like shown in the above example, you can compose normal arrays with reactivity and pass them through props or boundaries.

However, if you need the entire array to be fully reactive, including when new elements get added, you should use the reactive array that Ripple provides.

#### Fully Reactive Array

`RippleArray` class from Ripple extends the standard JS `Array` class, and supports all of its methods and properties. Import `RippleArray` from `'ripple'` to use it. All elements existing or new of the `RippleArray` are reactive and respond to the various array operations such as push, pop, shift, unshift, etc. Even if you reference a non-existent element, once it added, the original reference will react to the change.

```ripple
import { RippleArray } from 'ripple';

// using the constructor
const arr = new RippleArray(1, 2, 3);

// using static from method
const arr = RippleArray.from([1, 2, 3]);

// using static fromAsync method
const arr = RippleArray.fromAsync([1, 2, 3]);

// using static of method
const arr = RippleArray.of(1, 2, 3);
```

Usage Example:

```ripple
import { RippleArray } from 'ripple';

export function App() {
  const items = new RippleArray(1, 2, 3);

  return <div>
    <p>"Length: "{items.length}</p>  // Reactive length
    for (const item of items) {
      <div>{item}</div>
    }
    <button onClick={() => items.push(items.length + 1)}>"Add"</button>
  </div>;
}
```

#### Reactive Object

`RippleObject` class extends the standard JS `Object` class, and supports all of its methods and properties. Import `RippleObject` from `'ripple'` to use it. `RippleObject` fully supports shallow reactivity and any property on the root level is reactive.  You can even reference non-existent properties and once added the original reference reacts to the change.

```ripple
import { RippleObject } from 'ripple';

// using the constructor
const arr = new RippleObject({a: 1, b: 2, c: 3});
```

Usage Example:

```ripple
import { RippleObject } from 'ripple';

export function App() {
  const obj = new RippleObject({a: 0})

  obj.a = 0;

	return <>
		<pre>"obj.a is: "{obj.a}</pre>
		<pre>"obj.b is: "{obj.b}</pre>
		<button onClick={() => { obj.a++; obj.b = obj.b ?? 5; obj.b++; }}>"Increment"</button>
  </>;
}
```

#### Reactive Set

```ripple
import { RippleSet } from 'ripple';

function SetExample() {
  const mySet = new RippleSet([1, 2, 3]);

  return <div>
    <p>"Size: "{mySet.size}</p>  // Reactive size
    <p>"Has 2: "{mySet.has(2)}</p>
    <button onClick={() => mySet.add(4)}>"Add 4"</button>
  </div>;
}
```

#### Reactive Map

The `RippleMap` extends the standard JS `Map` class, and supports all of its methods and properties.

```ripple
import { RippleMap } from 'ripple';

const map = new RippleMap([[1,1], [2,2], [3,3], [4,4]]);
```

RippleMap's reactive methods or properties can be used directly or assigned to reactive variables.

```ripple
import { RippleMap, track } from 'ripple';

export function App() {
  const map = new RippleMap([[1,1], [2,2], [3,3], [4,4]]);

	return <>
		// direct usage
		<p>"Direct usage: map has an item with key 2: "{map.has(2)}</p>

		// reactive assignment
		let &[has] = track(() => map.has(2));
		<p>"Assigned usage: map has an item with key 2: "{has}</p>

		<button onClick={() => map.delete(2)}>"Delete item with key 2"</button>
		<button onClick={() => map.set(2, 2)}>"Add key 2 with value 2"</button>
  </>;
}
```

#### Reactive Date

The `RippleDate` extends the standard JS `Date` class, and supports all of its methods and properties.

```ripple
import { RippleDate } from 'ripple';

const date = new RippleDate(2026, 0, 1); // January 1, 2026
```

RippleDate's reactive methods or properties can be used directly or assigned to reactive variables. All getter methods (`getFullYear()`, `getMonth()`, `getDate()`, etc.) and formatting methods (`toISOString()`, `toDateString()`, etc.) are reactive and will update when the date is modified.

```ripple
import { RippleDate, track } from 'ripple';

export function App() {
  const date = new RippleDate(2025, 0, 1, 12, 0, 0);

	return <>
		// direct usage
		<p>"Direct usage: Current year is "{date.getFullYear()}</p>
		<p>"ISO String: "{date.toISOString()}</p>

		// reactive assignment
		let &[year] = track(() => date.getFullYear());
		let &[month] = track(() => date.getMonth());
		<p>"Assigned usage: Year "{year}", Month "{month}</p>

		<button onClick={() => date.setFullYear(2027)}>"Change to 2027"</button>
		<button onClick={() => date.setMonth(11)}>"Change to December"</button>
  </>;
}
```

## Advanced Features

### Portal Component

The `Portal` component allows you to render (teleport) content anywhere in the DOM tree, breaking out of the normal component hierarchy. This is particularly useful for modals, tooltips, and notifications.

```ripple
import { Portal } from 'ripple';

export function App() {
  return <div class="app">
			<h1>"My App"</h1>
			{/* This will render inside document.body, not inside the .app div */}
			<Portal target={document.body}>
				<div class="modal">
					<h2>"I am rendered in document.body!"</h2>
					<p>"This content escapes the normal component tree."</p>
				</div>
			</Portal>
		</div>;
}
```

### Untracking Reactivity
```ripple
import { track, effect, untrack } from 'ripple';

let &[count] = track(0);
let &[double] = track(() => count * 2);
let &[quadruple] = track(() => double * 2);

effect(() => {
  // This effect will never fire again, as we've untracked the only dependency it has
  console.log(untrack(() => quadruple));
})
```

### Prop Shortcuts
```ripple
// Object spread
<div {...properties}>"Content"</div>

// Shorthand props (when variable name matches prop name)
<div {onClick} {id}>"Content"</div>

// Equivalent to:
<div onClick={onClick} id={id}>"Content"</div>
```

### Raw HTML

All text nodes are escaped by default in Ripple. To render trusted raw HTML
strings, use the native `innerHTML` prop:
`<article innerHTML={source} />`.

When raw markup must sit beside normal children, import `Fragment` from
`ripple` and render `<Fragment innerHTML={source} />`.

```tsrx
function Article({ markup }: { markup: string }) {
  return <article innerHTML={markup} />;
}
```

### Text Expressions

Direct double-quoted children are static escaped text. Dynamic text is just a
normal `{expression}`. When you need explicit string coercion, write it in
JavaScript with `String(value)`, `value + ''`, or a typed string value.

```ripple
export function Frame({ children }) {
  return <div class="frame">
			"before"
			{children}
			"after"
		</div>;
}
```

Regular text expressions are HTML-escaped by the target renderer. The content is
never parsed as HTML unless you use the framework's raw HTML prop.

```ripple
export function App() {
	const markup = '<span>Not HTML</span>';

	// Renders the literal string "<span>Not HTML</span>" as text
  return <div>{markup}</div>;
}
```

## TypeScript Integration

### Component Types
```typescript
import type { Component } from 'ripple';

interface Props {
  value: string;
  label: string;
  children?: Component;
}

function MyComponent(props: Props) {
  return <>
  // Component implementation

  </>;
}
```

### Context Types
```typescript
import { Context } from 'ripple';

type Theme = 'light' | 'dark';
const ThemeContext = new Context<Theme>('light');
```

## File Structure

```
src/
  App.tsrx            # Main app component
  components/
    Button.tsrx       # Reusable components
    Card.tsrx
  index.ts           # Entry point with mount()
```

## Development Tools

### VSCode Extension
- **Name**: "Ripple for VS Code"
- **ID**: `Ripple-TS.ripple-ts-vscode-plugin`
- **Features**: Syntax highlighting, diagnostics, TypeScript integration, IntelliSense

### Vite Plugin
```typescript
// vite.config.js
import { defineConfig } from 'vite';
import ripple from '@ripple-ts/vite-plugin';

export default defineConfig({
  plugins: [ripple()]
});
```

### Prettier Plugin
```javascript
// .prettierrc
{
  "plugins": ["@tsrx/prettier-plugin"]
}
```

### TSRX MCP Server

Use `@tsrx/mcp` when an AI coding tool supports Model Context Protocol (MCP) and
needs target-aware TSRX help. The server exposes current TSRX documentation,
target detection, project inspection, formatting, compilation, diagnostic
analysis, and read-only file validation.

Hosted endpoint:

For hosted MCP apps and connectors, use:

```text
https://mcp.tsrx.dev/mcp
```

This is the best starting point for ChatGPT web and other clients that connect to
an HTTP MCP server instead of launching a local command.

ChatGPT setup:

Add `https://mcp.tsrx.dev/mcp` when creating a custom app or connector from
ChatGPT developer mode, then select that app from the tools menu in a chat.

Self-hosting:

To self-host the endpoint, deploy the monorepo's `website-mcp` app anywhere that
can run a Node HTTP server and connect remote MCP clients to its `/mcp` route.

Local MCP server:

For local repository work in Codex, Cursor, Gemini CLI, or Claude Code, install
`@tsrx/mcp` as a stdio MCP server so the tool can inspect your project.

Generic local MCP client config:

```json
{
  "mcpServers": {
    "tsrx": {
      "command": "npx",
      "args": ["-y", "@tsrx/mcp"]
    }
  }
}
```

Codex setup:

```toml
# ~/.codex/config.toml
[mcp_servers.tsrx]
command = "npx"
args = ["-y", "@tsrx/mcp"]
```

Gemini CLI setup:

Put the generic `mcpServers` JSON in `.gemini/settings.json` for a project, or
`~/.gemini/settings.json` globally.

Cursor setup:

Put the generic `mcpServers` JSON in `.cursor/mcp.json` for a project, or
`~/.cursor/mcp.json` globally. Cursor Agent and `cursor-agent` discover the
configured tools automatically.

Claude Code setup:

```bash
claude mcp add tsrx -- npx -y @tsrx/mcp
```

Recommended agent workflow:

- Start with `inspect-project` to identify the active runtime target, installed
  TSRX packages, formatting/typecheck scripts, and likely project commands.
- Use `detect-target` when only the runtime target is needed.
- For generated source, run `format-tsrx`, then `compile-tsrx`. If compilation
  fails, run `analyze-tsrx`, apply the advice, format again, and compile again.
- For existing `.tsrx` files, prefer `validate-tsrx-file`; it reads the file and
  runs formatting, compilation, and diagnostic advice in one read-only pass.
- Fetch `tsrx://docs/{slug}.md` resources for target-neutral syntax details and
  `tsrx://targets/{target}.md` for runtime-specific handoff guidance.

The MCP server is target-neutral. Runtime-specific imports, bundler setup, and
framework semantics should come from the detected target package and its docs.

## Key Differences from Other Frameworks

### vs React
- No wrapper components for control flow - returned templates support inline `if`, `for`, and `switch`
- Built-in reactivity with `track` and `&[]` lazy destructuring syntax instead of useState/useEffect
- Scoped CSS without CSS-in-JS libraries
- No virtual DOM - fine-grained reactivity

### vs Svelte
- TypeScript-first approach
- JSX-like syntax instead of HTML templates
- Default `.tsrx` extension instead of `.svelte`
- Similar reactivity concepts but different syntax

### vs Solid
- Components are ordinary functions that return TSRX
- Built-in collections (RippleArray, RippleSet)
- Returned templates support statement-style control flow

## Best Practices

1. **Reactivity**: Use `track()` (imported from `'ripple'`) with `&[]` lazy destructuring to create reactive variables
2. **Strings**: Use direct double-quoted children for static text, and `{...}` for JavaScript expressions
3. **Effects**: Use `effect()` (imported from `'ripple'`) for side effects, not direct reactive variable access
4. **Components**: Keep components focused and use TypeScript interfaces for props
5. **Styling**: Use scoped static `<style>` elements for component-specific styles and CSS custom properties for runtime style values
6. **Collections**: Use `new RippleArray()`/`new RippleSet()`/`new RippleMap()` (imported from `'ripple'`) for reactive collections instead of regular arrays/sets/maps

## Current Limitations

- **Ecosystem**: Early stage - limited third-party library ecosystem
- **Production Ready**: Currently in development but has been used in production already

## Resources

- **Website**: https://ripple-ts.com
- **GitHub**: https://github.com/Ripple-TS/ripple
- **VSCode Extension**: https://marketplace.visualstudio.com/items?itemName=Ripple-TS.ripple-ts-vscode-plugin

---

This documentation is optimized for AI/LLM understanding of the Ripple framework. For the most up-to-date information, visit https://ripple-ts.com or the GitHub repository.