Ripple

https://www.ripple-ts.com/docs
Admin
Ripple is an elegant, compiler-driven TypeScript UI framework with fine-grain reactivity,...
Tokens:23,842
Snippets:248
Trust Score:5.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Language Server

Source: https://www.ripple-ts.com/docs/quick-start

Install the global language server package for editor integration.

```sh
npm install -g '@ripple-ts/language-server'
```

--------------------------------

### Example: Using `handleEvent`

Source: https://www.ripple-ts.com/docs/guide/events

Demonstrates passing an object with `handleEvent` to an onClick attribute.

```APIDOC
## Example: Using `handleEvent`

### Description
This example shows how to use an object with the `handleEvent` property for an `onClick` event.

### Code
```jsx
<button onClick={{
	handleEvent: (e) => console.log('clicked!'),
}}>
	{"Click me"}
</button>
```
```

--------------------------------

### Example: Using `passive`

Source: https://www.ripple-ts.com/docs/guide/events

Illustrates the `passive` option, which prevents `preventDefault()` and optimizes performance.

```APIDOC
## Example: Using `passive`

### Description
This example shows the `passive` option, which is useful for scroll and touch events to improve performance by indicating that `preventDefault()` will not be called.

### Code
```jsx
<div onWheel={{
	handleEvent: (e) => {
		// This preventDefault() will be ignored in passive mode
		e.preventDefault();
		console.log('scrolling');
	},
	passive: true,
}}>
	{"Scroll over me"}
</div>
```

### Warning
Calling `preventDefault()` in a passive listener has no effect and may trigger a console warning.
```

--------------------------------

### Example: Using `capture`

Source: https://www.ripple-ts.com/docs/guide/events

Illustrates using the `capture` option to handle events during the capture phase.

```APIDOC
## Example: Using `capture`

### Description
This example demonstrates how to use the `capture` option to handle an event during the capture phase.

### Code
```jsx
import { RippleArray } from 'ripple';

export component EventExample() {
	let order = new RippleArray();

	<div onClick={{
		handleEvent: () => order.push('outer-capture'),
		capture: true,
	}}>
		<button onClick={() => order.push('inner-bubble')}>
			{"Click"}
		</button>
		<p>{order.join(' → ')}</p>
	</div>
}
// Clicking button outputs: outer-capture → inner-bubble
```
```

--------------------------------

### Example: Using `once`

Source: https://www.ripple-ts.com/docs/guide/events

Shows how to use the `once` option to ensure an event listener fires only one time.

```APIDOC
## Example: Using `once`

### Description
This example demonstrates using the `once` option to create an event listener that executes only a single time.

### Code
```jsx
import { track } from 'ripple';

export component EventExample() {
	let &[count] = track(0);

	<button onClick={{
		handleEvent: () => count++,
		once: true,
	}}>
		{"Click me (only works once)"}
	</button>
	<p>{`Clicks: ${count}`}</p>
}
// Button only responds to the first click
```
```

--------------------------------

### Usage Example of RippleMap - Ripple TS

Source: https://www.ripple-ts.com/docs/guide/reactivity

Demonstrates using `RippleMap` with direct method calls and assigning reactive properties (like `has`) to reactive variables using `track`.

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

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

  // 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>
}
```

--------------------------------

### Example: Using `delegated: false`

Source: https://www.ripple-ts.com/docs/guide/events

Demonstrates disabling event delegation for a specific event listener.

```APIDOC
## Example: Using `delegated: false`

### Description
This example shows how to disable Ripple's event delegation for a specific event listener by setting `delegated` to `false`.

### Code
```jsx
export component EventExample() {
	<button onClick={{
		handleEvent: () => console.log('clicked'),
		delegated: false, // Attach listener directly to this button
	}}>
		{"Click me"}
	</button>
}
```
```

--------------------------------

### Usage Example of RippleArray - Ripple TS

Source: https://www.ripple-ts.com/docs/guide/reactivity

Illustrates how to use `RippleArray` in a component, demonstrating reactive length updates and adding new elements via `push`.

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

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

  <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>
}
```

--------------------------------

### Usage Example of RippleSet - Ripple TS

Source: https://www.ripple-ts.com/docs/guide/reactivity

Illustrates using `RippleSet` directly and assigning its reactive properties (like `has`) to reactive variables using `track`.

```typescript
import { RippleSet, track } from 'ripple';

export component App() {
  const set = new RippleSet([1, 2, 3]);

  // direct usage
  <p>{"Direct usage: set contains 2: "}{set.has(2)}</p>

  // reactive assignment
  let &[has] = track(() => set.has(2));
  <p>{"Assigned usage: set contains 2: "}{has}</p>

  <button onClick={() => set.delete(2)}>{'Delete 2'}</button>
  <button onClick={() => set.add(2)}>{'Add 2'}</button>
}
```

--------------------------------

### Usage Example of RippleObject - Ripple TS

Source: https://www.ripple-ts.com/docs/guide/reactivity

Shows how to use `RippleObject` in a component, updating properties and accessing potentially non-existent ones which become reactive upon assignment.

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

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

  obj.a = 0;

  <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>
}
```

--------------------------------

### Custom Tracked Value Get/Set Functions

Source: https://www.ripple-ts.com/docs/guide/reactivity

Customize how tracked values are read and written using optional `get` and `set` functions passed to `track`. The `get` function transforms the stored value before it's exposed, and the `set` function transforms the incoming value before it's stored. This is useful for logging, validation, or value transformation.

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

export component 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;
    }
  );
}
```

--------------------------------

### Initialize Ripple Project

Source: https://www.ripple-ts.com/docs/quick-start

Use the experimental CLI to create a new project.

```sh
npm create ripple
```

--------------------------------

### Get DOM Element Reference with bindNode

Source: https://www.ripple-ts.com/docs/guide/bindings

Use bindNode to get a direct reference to a DOM element. This is useful for imperative DOM manipulation, such as focusing the element or modifying its styles.

```typescript
import { bindNode, track } from 'ripple';

export component App() {
  let &[divElement, divElementTracked] = track();

  const handleFocus = () => {
    if (divElement) {
      divElement.focus();
      divElement.style.backgroundColor = 'lightblue';
    }
  };

  <div>
    <div
      {ref bindNode(divElementTracked)}
      tabIndex={0}
      style={{
        border: '2px solid navy',
        padding: '20px',
        outline: 'none'
      }}
    >
      {'Click the button to focus this div'}
    </div>
    <button onClick={handleFocus}>{'Focus Div'}</button>
  </div>
}
```

--------------------------------

### Configure Sublime Text LSP

Source: https://www.ripple-ts.com/docs/quick-start

Add the Ripple client configuration to the LSP package settings.

```json
{
	"clients": {
		"Ripple": {
			"enabled": true,
			"command": ["'@ripple-ts/language-server'", "--stdio"],
			"selector": "source.ripple"
		}
	}
}
```

--------------------------------

### Clone Basic Template

Source: https://www.ripple-ts.com/docs/quick-start

Scaffold a project using the Vite-based basic template.

```sh
npx degit Ripple-TS/ripple/templates/basic ripple-app

cd ripple-app
npm i
npm run dev
```

--------------------------------

### Use prop shorthands and object spread

Source: https://www.ripple-ts.com/docs/guide/components

Syntax for spreading objects into props and using shorthand notation when variable names match prop names.

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

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

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

--------------------------------

### Binding Attributes and Plain HTML

Source: https://www.ripple-ts.com/docs/guide/syntax

Shows how to bind JavaScript expressions to attributes using braces and how to use standard HTML attributes.

```ripple
<span data-my-attr={attr_val}>{'Hi there!'}</span>
```

```ripple
<input type="text" />
```

--------------------------------

### Create RippleMap Instance - Ripple TS

Source: https://www.ripple-ts.com/docs/guide/reactivity

Shows how to instantiate a `RippleMap`, which extends the standard JS `Map` class and offers reactive methods and properties.

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

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

--------------------------------

### Manage reactive state with Context

Source: https://www.ripple-ts.com/docs/guide/state-management

Demonstrates creating contexts and using the track function to share reactive values within components.

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

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

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

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

  <button onClick={() => { count++; count2++ }}>
    {'Click Me'}
  </button>

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

--------------------------------

### Manage Head Content in Ripple Component

Source: https://www.ripple-ts.com/docs/guide/head-management

Use the <head> tag directly within a Ripple component to manage static or reactive data in the document's head. This example shows how to dynamically update the page title based on component state.

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

export component App() {
	let &[curr_step] = track(0);

	<head>
		<title>{`Step ${curr_step}`}</title>
	</head>

	<button onClick={() => { curr_step++ }}>{'Next Step'}</button>
}
```

--------------------------------

### List iteration with for statements

Source: https://www.ripple-ts.com/docs/guide/control-flow

Render collections using for...of loops, with optional support for indices and keys.

```ripple
component ListView({ title, items }) {
  <h2>{title}</h2>
  <ul>
    for (const item of items) {
      <li>{item.text}</li>
    }
  </ul>
}

// usage
export default component App() {
	<ListView
		title="My List"
		items={[
			{ text: "Item 1" },
			{ text: "Item 2" },
			{ text: "Item 3" },
		]}
	/>
}
```

```ripple
  for (const item of items; index i) {
    <div>{item.label}{' at index '}{i}</div>
  }
```

```ripple
  for (const item of items; index i; key item.id) {
    <div>{item.label}{' at index '}{i}</div>
  }
```

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

export component Numbers() {
  const array = new RippleArray(1, 2, 3);

  for (const item of array; index i) {
    <div>{item}{' at index '}{i}</div>
  }

  <button onClick={() => array.push(array.length + 1)}>{"Add Item"}</button>
}
```

--------------------------------

### Programmatic Ref Assignment with createRefKey

Source: https://www.ripple-ts.com/docs/guide/dom-refs

Use `createRefKey()` to generate a unique object key for programmatic ref assignment. This allows refs to be applied via props spreading, offering flexibility beyond template syntax.

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

export component App() {
  let &[value] = track('');

  const props = {
    id: "example",
    value,
    [createRefKey()]: (node) => {
      const removeListener = node.addEventListener('input', (e) => {
        value = e.target.value;
        console.log(value);
      });

      return () => {
        removeListener();
      }
    }
  };

  // applied to an element
  <input type="text" {...props} />

  // with composite component
  <Input {...props} />
}

component Input({ id, value, ...rest }) {
  <input type="text" {id} {value} {...rest} />
}
```

--------------------------------

### Initialize RippleDate

Source: https://www.ripple-ts.com/docs/guide/reactivity

Instantiate a new RippleDate object using standard Date constructor arguments.

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

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

--------------------------------

### Create RippleObject Instance - Ripple TS

Source: https://www.ripple-ts.com/docs/guide/reactivity

Demonstrates how to create a `RippleObject`, which extends the standard JS `Object` and provides shallow reactivity for its root-level properties.

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

const obj = new RippleObject({a: 1, b: 2, c: 3});
```

--------------------------------

### ResizeObserver Bindings

Source: https://www.ripple-ts.com/docs/guide/bindings

Bindings that leverage the ResizeObserver API to track element dimensions.

```APIDOC
## bindContentRect

### Description
Tracks the element's content rectangle from the ResizeObserver API.

### Method
Not applicable.

### Endpoint
Not applicable.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { bindContentRect, track } from 'ripple';

export component App() {
  let &[rect, rectTracked] = track({ width: 0, height: 0, top: 0, left: 0 });

  <div>
    <div
      {ref bindContentRect(rectTracked)}
      style={{
        resize: 'both',
        overflow: 'auto',
        border: '2px solid purple',
        padding: '20px',
        minWidth: '200px',
        minHeight: '100px'
      }}
    >
      {'Resize me!'}
    </div>
    <pre>{JSON.stringify(rect, null, 2)}</pre>
  </div>
}
```

### Response
#### Success Response (200)
Not applicable.

#### Response Example
Not applicable.
```

```APIDOC
## bindContentBoxSize

### Description
Tracks the content box size (without padding or borders).

### Method
Not applicable.

### Endpoint
Not applicable.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { bindContentBoxSize, track } from 'ripple';

export component App() {
  let &[size, sizeTracked] = track([]);

  <div>
    <div
      {ref bindContentBoxSize(sizeTracked)}
      style={{
        border: '5px solid orange',
        padding: '15px',
        width: '250px',
        height: '100px'
      }}
    >
      {'Content box size'}
    </div>
    <pre>
      {'Block size: '}{size[0]?.blockSize || 0}{'px\n'}
      {'Inline size: '}{size[0]?.inlineSize || 0}{'px'}
    </pre>
  </div>
}
```

### Response
#### Success Response (200)
Not applicable.

#### Response Example
Not applicable.
```

```APIDOC
## bindBorderBoxSize

### Description
Tracks the border box size (including padding and borders).

### Method
Not applicable.

### Endpoint
Not applicable.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { bindBorderBoxSize, track } from 'ripple';

export component App() {
  let &[size, sizeTracked] = track([]);

  <div>
    <div
      {ref bindBorderBoxSize(sizeTracked)}
      style={{
        border: '5px solid teal',
        padding: '15px',
        width: '250px',
        height: '100px'
      }}
    >
      {'Border box size'}
    </div>
    <pre>
      {'Block size: '}{size[0]?.blockSize || 0}{'px\n'}
      {'Inline size: '}{size[0]?.inlineSize || 0}{'px'}
    </pre>
  </div>
}
```

### Response
#### Success Response (200)
Not applicable.

#### Response Example
Not applicable.
```

```APIDOC
## bindDevicePixelContentBoxSize

### Description
Tracks the content box size in device pixels (useful for high-DPI displays).

### Method
Not applicable.

### Endpoint
Not applicable.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { bindDevicePixelContentBoxSize, track } from 'ripple';

export component App() {
  let &[size, sizeTracked] = track([]);

  <div>
    <div
      {ref bindDevicePixelContentBoxSize(sizeTracked)}
      style={{
        border: '3px solid crimson',
        padding: '10px',
        width: '200px',
        height: '80px'
      }}
    >
      {'Device pixel content box'}
    </div>
    <pre>
      {'Block size: '}{size[0]?.blockSize || 0}{'px\n'}
      {'Inline size: '}{size[0]?.inlineSize || 0}{'px'}
    </pre>
  </div>
}
```

### Response
#### Success Response (200)
Not applicable.

#### Response Example
Not applicable.
```

--------------------------------

### Basic Event Binding

Source: https://www.ripple-ts.com/docs/guide/events

Demonstrates binding click and input events using camelCase props in a Ripple component.

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

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

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

--------------------------------

### Mount Ripple App to DOM

Source: https://www.ripple-ts.com/docs/guide/application

Use the `mount` function to attach a Ripple application to a target DOM element for client-side rendering. Ensure the target element exists in the DOM.

```javascript
import { mount } from 'ripple';
// @ts-expect-error: known issue, we're working on it
import { App } from './App.ripple';

mount(App, {
	target: document.getElementById('app')!,
});
```

--------------------------------

### Create a card component with slots

Source: https://www.ripple-ts.com/docs/guide/components

Uses component composition to create a flexible card layout with optional header and footer slots.

```ripple
component Card({ children, Header, Footer }) {
	<fieldset>
		<Header />
		<hr />
		{children}
		<hr />
		<Footer />
	</fieldset>
}

component CustomHeader() {
	<h1>{'Card Title'}</h1>
}

export component App() {
	<Card Header={CustomHeader}> // <- Header passed in as a prop
		<p>{'Card content here'}</p>
		component Footer() {     // <- Footer passed in as a inline component
			<button>{'Cancel'}</button>
			<button>{'OK'}</button>
		}
	</Card>
}
```

--------------------------------

### Error handling with try statements

Source: https://www.ripple-ts.com/docs/guide/control-flow

Use try/catch blocks to implement error boundaries and render fallback content.

```ripple
import { reportError } from 'some-library';

export component ErrorBoundary() {
  <div>
    try {
      <ComponentThatFails />
    } catch (e) {
      reportError(e);

      <div>{'An error occurred! ' + e.message}</div>
    }
  </div>
}
```

--------------------------------

### Define and use children in components

Source: https://www.ripple-ts.com/docs/guide/components

Demonstrates passing elements as children and rendering them via the children prop.

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

component Card(props: { children: Children }) {
	<div class="card">
		{props.children}
	</div>
}

export component App() {
	// Use implicitly...
	<Card>
		<p>{"Card content here"}</p>
	</Card>

	// or pass children explicitly as a prop.
	component children() {
		<p>{"Card content here"}</p>
	}

	<Card {children} />
}
```

--------------------------------

### Create RippleSet Instance - Ripple TS

Source: https://www.ripple-ts.com/docs/guide/reactivity

Demonstrates the creation of a `RippleSet`, which extends the standard JS `Set` class and provides reactive methods and properties.

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

const set = new RippleSet([1, 2, 3]);
```

--------------------------------

### Dynamic Components

Source: https://www.ripple-ts.com/docs/guide/reactivity

Use the <@Component /> tag to render components stored in Tracked state, allowing runtime component swapping.

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

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

  <Child swapMe={swapMeTracked} />

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

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

component Child1(props) {
  <pre>{'I am child 1'}</pre>
}

component Child2(props) {
  <pre>{'I am child 2'}</pre>
}
```

--------------------------------

### Track Content Box Size

Source: https://www.ripple-ts.com/docs/guide/bindings

Use bindContentBoxSize to track the content box size, excluding padding and borders.

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

export component App() {
  let &[size, sizeTracked] = track([]);

  <div>
    <div
      {ref bindContentBoxSize(sizeTracked)}
      style={{
        border: '5px solid orange',
        padding: '15px',
        width: '250px',
        height: '100px'
      }}
    >
      {'Content box size'}
    </div>
    <pre>
      {'Block size: '}{size[0]?.blockSize || 0}{'px\n'}
      {'Inline size: '}{size[0]?.inlineSize || 0}{'px'}
    </pre>
  </div>
}
```

--------------------------------

### Dynamic Component Styling

Source: https://www.ripple-ts.com/docs/guide/styling

Use #style when rendering components dynamically via the <@Component /> syntax.

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

component Child({ cls }: { cls: string }) {
  <span class={cls}>{'text'}</span>
}

component Parent() {
  let &[Dynamic] = track(() => Child);
  <@Dynamic cls={#style.text} />

  <style>
    .text {
      color: red;
    }
  </style>
}
```

--------------------------------

### Bind File Input to Tracked Variable

Source: https://www.ripple-ts.com/docs/guide/bindings

Use `bindFiles` to create a two-way binding between a tracked variable and a file input's selected files. This allows reading and programmatically updating the file input. `FileList` objects are read-only; use `DataTransfer` to set files.

```ripple
import { bindFiles, bindNode, track } from 'ripple';

export component App() {
	let &[files, filesTracked] = track();
	let &[version] = track(0);
	let &[input, inputTracked] = track();

	const clearFiles = () => {
		files = new DataTransfer().files; // null or undefined does not work
		input.value = null; // reset the input selected message
	};

	const createSampleFile = () => {
		version++;
		const dt = new DataTransfer();
		const file = new File([`Hello, World version: ${version}!`], `sample_${version}.txt`, {
			type: 'text/plain',
		});
		dt.items.add(file);
		for (const file of files ?? []) {
			dt.items.add(file);
		}
		files = dt.files;
	};

	<div>
		<input type="file" {ref bindFiles(filesTracked)} {ref bindNode(inputTracked)} multiple />

		<div>
			if (files && files.length > 0) {
				<p>{'Selected files:'}</p>
				<ul>
					for (const file of Array.from(files)) {
						<li>
							{file.name}
							{' ('}
							{file.size}
							{' bytes)'}
						</li>
					}
				</ul>
			} else {
				<p>{'No files selected'}</p>
			}
		</div>

		<button onClick={clearFiles}>{'Clear files'}</button>
		<button onClick={createSampleFile}>{'Add sample file'}</button>
	</div>
}
```

--------------------------------

### Programmatically Set Files using DataTransfer

Source: https://www.ripple-ts.com/docs/guide/bindings

To programmatically set files for a file input bound with `bindFiles`, create a new `DataTransfer` object, add files to it, and assign its `files` property to the tracked variable. This is necessary because `FileList` objects are read-only.

```javascript
const dt = new DataTransfer()
dt.items.add(new File(['content'], 'filename.txt'))
files = dt.files
```

--------------------------------

### Use Reactive RippleDate in Components

Source: https://www.ripple-ts.com/docs/guide/reactivity

Demonstrates direct usage of reactive date methods and tracking specific date properties within a component.

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

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

  // 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(2026)}>{"Change to 2026"}</button>
  <button onClick={() => date.setMonth(11)}>{"Change to December"}</button>
}
```

--------------------------------

### Bind input values with bindValue

Source: https://www.ripple-ts.com/docs/guide/bindings

Synchronize input and select elements with tracked variables. Requires a Tracked object as an argument.

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

export component App() {
  let &[name, nameTracked] = track('');

  <div>
    <input type="text" {ref bindValue(nameTracked)} placeholder="Enter your name" />
    <p>{'Hello, '}{name || 'stranger'}{'!'}</p>
    <button onClick={() => name = ''}>{'Clear'}</button>
  </div>
}
```

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

export component App() {
  let &[age, ageTracked] = track(0);

  <div>
    <input type="number" {ref bindValue(ageTracked)} min="0" max="120" />
    <p>{'Age: '}{age}{' years old'}</p>
    <button onClick={() => age = age + 1}>{'Increment'}</button>
  </div>
}
```

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

export component App() {
  let &[selectedFruit, selectedFruitTracked] = track('apple');

  <div>
    <select {ref bindValue(selectedFruitTracked)}>
      <option value="apple">{'Apple'}</option>
      <option value="banana">{'Banana'}</option>
      <option value="cherry">{'Cherry'}</option>
      <option value="durian">{'Durian'}</option>
    </select>
    <p>{'You selected: '}{selectedFruit}</p>
  </div>
}
```

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

export component App() {
  let &[selectedColors, selectedColorsTracked] = track(['red', 'blue']);

  <div>
    <select multiple {ref bindValue(selectedColorsTracked)} style="height: 100px">
      <option value="red">{'Red'}</option>
      <option value="green">{'Green'}</option>
      <option value="blue">{'Blue'}</option>
      <option value="yellow">{'Yellow'}</option>
    </select>
    <p>{'Selected colors: '}{selectedColors.join(', ')}</p>
  </div>
}
```

--------------------------------

### Element Dimension Bindings

Source: https://www.ripple-ts.com/docs/guide/bindings

Bindings for tracking the dimensions of DOM elements.

```APIDOC
## bindClientWidth / bindClientHeight

### Description
These bindings track the inner dimensions of an element (excluding borders and scrollbars).

### Method
Not applicable (these are bindings, not API endpoints).

### Endpoint
Not applicable.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { bindClientWidth, bindClientHeight, track } from 'ripple';

export component App() {
  let &[width, widthTracked] = track(0);
  let &[height, heightTracked] = track(0);

  <div>
    <div
      {ref bindClientWidth(widthTracked)}
      {ref bindClientHeight(heightTracked)}
      style={{
        resize: 'both',
        overflow: 'auto',
        border: '2px solid blue',
        padding: '20px',
        minWidth: '200px',
        minHeight: '100px'
      }}
    >
      {'Resize me! (drag bottom-right corner)'}
      <p>{'Client Width: '}{width}{'px'}</p>
      <p>{'Client Height: '}{height}{'px'}</p>
    </div>
  </div>
}
```

### Response
#### Success Response (200)
Not applicable.

#### Response Example
Not applicable.
```

```APIDOC
## bindOffsetWidth / bindOffsetHeight

### Description
These bindings track the full outer dimensions of an element (including borders).

### Method
Not applicable.

### Endpoint
Not applicable.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { bindOffsetWidth, bindOffsetHeight, track } from 'ripple';

export component App() {
  let &[width, widthTracked] = track(0);
  let &[height, heightTracked] = track(0);

  <div>
    <div
      {ref bindOffsetWidth(widthTracked)}
      {ref bindOffsetHeight(heightTracked)}
      style={{
        border: '10px solid green',
        padding: '20px',
        width: '300px',
        height: '150px'
      }}
    >
      {'Box with borders'}
    </div>
    <p>{'Offset Width: '}{width}{'px (includes borders)'}</p>
    <p>{'Offset Height: '}{height}{'px (includes borders)'}</p>
  </div>
}
```

### Response
#### Success Response (200)
Not applicable.

#### Response Example
Not applicable.
```

--------------------------------

### Server-Side Rendering with Ripple

Source: https://www.ripple-ts.com/docs/guide/application

On the server, use the `render` function to generate HTML for your Ripple application. This HTML can then be sent to the client.

```javascript
// server.js
import { render } from 'ripple/server'
import { App } from './App.ripple'

const html = render(App, {
	props: { title: 'Hello world!' },
})

// Send html to the client
res.send(`
  <!DOCTYPE html>
  <html>
    <body>
      <div id="app">${html}</div>
      <script type="module" src="/client.js"></script>
    </body>
  </html>
`)
```

--------------------------------

### Pass data between components using Context

Source: https://www.ripple-ts.com/docs/guide/state-management

Shows how to define a context and share data from a parent component to a child component.

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

const MyContext = new Context(null);

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

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

export component 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!");

  <Child />
}
```

--------------------------------

### Create RippleArray Instances - Ripple TS

Source: https://www.ripple-ts.com/docs/guide/reactivity

Shows different ways to instantiate a `RippleArray`, which extends the standard JS `Array` and provides full reactivity for all elements and operations.

```typescript
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 of method
const arr = RippleArray.of(1, 2, 3);
```

--------------------------------

### Early return guard clauses

Source: https://www.ripple-ts.com/docs/guide/control-flow

Short-circuit component rendering by using return; inside an if block.

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

export component AuthGate() {
  let &[is_logged_in] = track(false);

  if (!is_logged_in) {
    <p>{'Please sign in.'}</p>
    return;
  }

  <h1>{'Dashboard'}</h1>
  <p>{'Private content'}</p>
}
```

--------------------------------

### Track Border Box Size

Source: https://www.ripple-ts.com/docs/guide/bindings

Use bindBorderBoxSize to track the border box size, including padding and borders.

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

export component App() {
  let &[size, sizeTracked] = track([]);

  <div>
    <div
      {ref bindBorderBoxSize(sizeTracked)}
      style={{
        border: '5px solid teal',
        padding: '15px',
        width: '250px',
        height: '100px'
      }}
    >
      {'Border box size'}
    </div>
    <pre>
      {'Block size: '}{size[0]?.blockSize || 0}{'px\n'}
      {'Inline size: '}{size[0]?.inlineSize || 0}{'px'}
    </pre>
  </div>
}
```

--------------------------------

### Track Client Dimensions

Source: https://www.ripple-ts.com/docs/guide/bindings

Use bindClientWidth and bindClientHeight to track the inner dimensions of an element, excluding borders and scrollbars.

```ripple
import { bindClientWidth, bindClientHeight, track } from 'ripple';

export component App() {
  let &[width, widthTracked] = track(0);
  let &[height, heightTracked] = track(0);

  <div>
    <div
      {ref bindClientWidth(widthTracked)}
      {ref bindClientHeight(heightTracked)}
      style={{
        resize: 'both',
        overflow: 'auto',
        border: '2px solid blue',
        padding: '20px',
        minWidth: '200px',
        minHeight: '100px'
      }}
    >
      {'Resize me! (drag bottom-right corner)'}
      <p>{'Client Width: '}{width}{'px'}</p>
      <p>{'Client Height: '}{height}{'px'}</p>
    </div>
  </div>
}
```

--------------------------------

### Rendering Raw HTML

Source: https://www.ripple-ts.com/docs/guide/syntax

Uses the {html} directive to render trusted strings as HTML, noting that malformed HTML fragments are not supported.

```ripple
export component App() {
	let source = `
<h1>My Blog Post</h1>
<p>Hi! I like JS and Ripple.</p>
`

	<article>
		{html source}
	</article>
}
```

```ripple
{html '<div>'}content{html '</div>'}
```

--------------------------------

### Capture DOM Element Reference

Source: https://www.ripple-ts.com/docs/guide/dom-refs

Use the `{ref fn}` syntax to capture the DOM element. The provided function `fn` receives the DOM node on mount and can return a cleanup function for unmount.

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

export default component App() {
  let &[div] = track();

  const divRef = (node) => {
    div = node;
    console.log("mounted", node);

    return () => {
      div = undefined;
      console.log("unmounted", node);
    };
  };

  <div {ref divRef}>{"Hello world"}</div>
}
```

--------------------------------

### Defining Lexical Scopes in Templates

Source: https://www.ripple-ts.com/docs/guide/syntax

Demonstrates declaring variables, executing logic, and using nested scopes directly within a component template.

```ripple
component TemplateScope() {
	<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>
}
```

--------------------------------

### Render content with Portal

Source: https://www.ripple-ts.com/docs/guide/components

Teleport component content to a specific DOM target, such as document.body, bypassing the standard hierarchy.

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

export component App() {
	<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>
}
```

--------------------------------

### Handling Suspense with try/pending/catch

Source: https://www.ripple-ts.com/docs/guide/control-flow

Wrap components that use `await` in a `try/pending/catch` block to manage suspended states and errors. The `{pending}` clause displays while suspended, and the `{catch}` clause handles sync throws and async rejections. Both clauses are optional.

```ripple
export component App() {
  try {
    <UserProfile id={1} />
  } pending {
    <p>{'Loading...'}</p>
  } catch (e) {
    <p>{'Error: '}{e.message}</p>
  }
}
```

--------------------------------

### Use Reactive Collections

Source: https://www.ripple-ts.com/docs/best-practices

Employ `RippleArray` and `RippleSet` for reactive collections instead of standard JavaScript arrays and sets to enable reactivity.

```typescript
const list = new RippleArray([1, 2, 3]);
const set = new RippleSet(new Set([4, 5, 6]));
```

--------------------------------

### Track Offset Dimensions

Source: https://www.ripple-ts.com/docs/guide/bindings

Use bindOffsetWidth and bindOffsetHeight to track the full outer dimensions of an element, including borders.

```ripple
import { bindOffsetWidth, bindOffsetHeight, track } from 'ripple';

export component App() {
  let &[width, widthTracked] = track(0);
  let &[height, heightTracked] = track(0);

  <div>
    <div
      {ref bindOffsetWidth(widthTracked)}
      {ref bindOffsetHeight(heightTracked)}
      style={{
        border: '10px solid green',
        padding: '20px',
        width: '300px',
        height: '150px'
      }}
    >
      {'Box with borders'}
    </div>
    <p>{'Offset Width: '}{width}{'px (includes borders)'}</p>
    <p>{'Offset Height: '}{height}{'px (includes borders)'}</p>
  </div>
}
```

--------------------------------

### Client-Side Hydration with SSR Props

Source: https://www.ripple-ts.com/docs/guide/application

When hydrating server-rendered HTML on the client, pass the same props used during server rendering to the `hydrate` function to ensure consistency.

```javascript
// client.js
import { hydrate } from 'ripple';
import { App } from './App.ripple';

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

--------------------------------

### Dynamic element rendering

Source: https://www.ripple-ts.com/docs/guide/control-flow

Render dynamic HTML elements by using the <@tagName> syntax with a tracked variable.

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

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

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

--------------------------------

### Direct Async Rendering in Ripple Components

Source: https://www.ripple-ts.com/docs/guide/control-flow

Use `await` directly in component bodies for asynchronous operations. Content before the first `await` renders immediately, while content after suspends until the promise resolves. No `async` keyword is needed.

```ripple
component UserProfile({ id }: { id: number }) {
  // Renders immediately
  <h1>{'Loading profile...'}</h1>

  // Suspends here until resolved
  const user = await fetchUser(id);

  // Renders after resolution
  <h1>{user.name}</h1>
  <p>{user.email}</p>
}
```

--------------------------------

### Reactive Async with await track()

Source: https://www.ripple-ts.com/docs/guide/control-flow

Use `await track(fn)` for asynchronous operations that need to re-run when reactive dependencies change. Dependencies are tracked within the function passed to `track`. The component re-suspends to the nearest `try/pending` boundary when dependencies change.

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

export component CitySearch() {
  let &[query] = track('');

  // Renders immediately, never suspended
  <input type="text" value={query} onInput={e => query = e.target.value} />

  // Re-runs and re-suspends whenever query changes
  const city = await track(() => fetchCity(query));

  // Only renders once city has resolved for the current query
  <p>{'Showing: '}{query}</p>
  <CityCard city={city} />
}
```

--------------------------------

### Content Editable Bindings

Source: https://www.ripple-ts.com/docs/guide/bindings

Bindings for managing content editable elements.

```APIDOC
## bindInnerHTML

### Description
Binds to an element's innerHTML property, useful for rich text editors.

### Method
Not applicable.

### Endpoint
Not applicable.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { bindInnerHTML, track } from 'ripple';

export component App() {
  let &[content, contentTracked] = track('<strong>Bold text</strong>');

  <div>
    <div
      contentEditable={true}
      {ref bindInnerHTML(contentTracked)}
      style={{
        border: '1px solid gray',
        padding: '10px',
        minHeight: '50px'
      }}
    />
    <p>{'Raw HTML:'}</p>
    <pre>{content}</pre>
  </div>
}
```

### Response
#### Success Response (200)
Not applicable.

#### Response Example
Not applicable.
```

--------------------------------

### on() Function

Source: https://www.ripple-ts.com/docs/guide/events

The on() function attaches an event handler to an element and returns a cleanup function. It provides optimized event delegation and guarantees execution order compared to standard addEventListener.

```APIDOC
## on()

### Description
Attaches an event handler to an element and returns a function to remove it. It is optimized with event delegation for supported events and ensures proper execution order with attribute-based handlers.

### Parameters
- **target** (Element) - Required - The DOM element to attach the listener to.
- **eventName** (string) - Required - The name of the event to listen for.
- **handler** (Function) - Required - The callback function to execute when the event triggers.

### Request Example
const removeListener = on(window, 'resize', () => {
  console.log('Window resized!');
});
```

--------------------------------

### Implement named children composition

Source: https://www.ripple-ts.com/docs/guide/components

Pass multiple components as props or define them inline to act as named slots.

```ripple
component Composite({ PropComp, InlineComp }) {
	<PropComp />
	<InlineComp />
}

component Separate() {
	<p>{`I'm a separate component.`}</p>
}

export component App() {
	<Composite PropComp={Separate}>
		component InlineComp() {
			<p>{`I'm an inline component.`}</p>
		}
	</Composite>
}
```

--------------------------------

### Component Template Placement Rules

Source: https://www.ripple-ts.com/docs/guide/syntax

Templates must be defined within the body of a component. Helper functions should return data, not templates, to ensure clear separation of concerns.

```ripple
// ❌ Wrong - Templates outside the component
const element = <div>{"Hello"}</div>;  // Compilation error

function regularFunction() {
	return <span>{"Not allowed"}</span>;  // Compilation error
}

const myTemplate = (
	<div>{"Cannot assign JSX"}</div>  // Compilation error
);

// ✅ Correct - Templates only inside components
component MyComponent() {
	// Template syntax is valid here
	<div>{"Hello World"}</div>

	// You can have JavaScript code mixed with templates
	const message = "Dynamic content";
	console.log("This JavaScript works");

	<p>{message}</p>
}

// ✅ Correct - Helper functions return data, not templates
function getMessage() {
	return "Hello from function";  // Return data, not JSX
}

component App() {
	<div>{getMessage()}</div>  // Use function result in template
}
```
Tokens:
Raw