woby/readme.md

A high-performance framework with fine-grained observable/signal-based reactivity for building rich applications.

<p align="center">
  <a href="https://github.com/wobyjs/woby">
    <img src="./resources/banner/png/banner-light-rounded.png" alt="Woby's Banner" width="640px" height="320px">
  </a>
</p>

# Woby

A high-performance framework with fine-grained observable-based reactivity for building rich applications. Woby is built upon the [Soby](https://github.com/wobyjs/soby) reactive core, providing an enhanced API for component-based development.

## Features

This works similarly to [Solid](https://www.solidjs.com), but without a custom Babel transform and with a different API.

- **No VDOM**: there's no VDOM overhead, the framework deals with raw DOM nodes directly.
- **No stale closures**: functions are always executed afresh, no need to worry about previous potential executions of the current function, ever.
- **No rules of hooks**: hooks are regular functions that can be nested indefinitely, called conditionally, and used outside components, providing maximum flexibility for developers.
- **No dependencies arrays**: the framework is able to detect what depends on what else automatically, no need to specify dependencies manually.
- **No props diffing**: updates are fine grained, there's no props diffing, whenever an attribute/property/class/handler/etc. should be updated it's updated directly and immediately.
- **No key prop**: developers can map over arrays directly or use the `For` component with an array of unique values, eliminating the need to specify keys explicitly.
- **No Babel**: this framework works with plain JavaScript (plus JSX support), eliminating the need for Babel transforms. As a result, there are zero transform function bugs since no code transformation is required.
- **No magic**: Woby follows a transparent approach where your code behaves exactly as written, with no hidden transformations or unexpected behavior.
- **Client-focused**: this framework is currently focused on client-side rich applications. Server-related features such as hydration, server components, SSR, and streaming are not implemented at this time.
- **Observable-based**: observables are at the core of the reactivity system. While the approach differs significantly from React-like systems and may require an initial learning investment, it provides substantial benefits in terms of performance and developer experience.
- **Minimal dependencies**: Woby is designed with a focus on minimal third-party dependencies, providing a streamlined API for developers who prefer a lightweight solution. The framework draws inspiration from [Solid](https://www.solidjs.com) while offering its own unique approach to reactive programming.
- **Built-in Class Management**: Woby includes powerful built-in class management that supports complex class expressions similar to `classnames` and `clsx` libraries, with full reactive observable support.
- **Web Components Support**: First-class support for creating and using custom elements with reactive properties.
- **Advanced Context API**: Powerful context system that works seamlessly with both JSX components and custom elements.
- **Advanced Nested Property Support**: Unique feature allowing deeply nested properties to be set directly through HTML attributes using both `$` and `.` notation - a capability not available in React or SolidJS.

## 📚 Documentation

**[📖 Complete Documentation Wiki](./docs/README.md)** - Comprehensive guides, tutorials, and API reference

### Quick Links
- **[Installation Guide](./docs/Installation.md)** - Get started with Woby
- **[Quick Start Tutorial](./docs/Quick-Start.md)** - Build your first app
- **[API Reference](./docs/Core-Methods.md)** - Complete API documentation
- **[Reactive Utilities](./docs/Reactive-Utilities.md)** - Working with observables and the `$$` function
- **[Reactivity System](./docs/Reactivity-System.md)** - Understanding Woby's reactivity model
- **[Examples Gallery](./docs/Examples.md)** - Practical examples and patterns
- **[Class Management](./docs/Class-Management.md)** - Advanced class handling with reactive support
- **[Best Practices](./docs/Best-Practices.md)** - Recommended patterns and practices
- **[Woby vs React](./docs/Woby-vs-React.md)** - API differences and migration guide
- **[FAQ](./docs/FAQ.md)** - Common questions and answers
- **[Type Synchronization](./docs/Type-Synchronization.md)** - How HTML attributes sync with component props
- **[Simple Type Synchronization](./docs/Type-Sync-Simple.md)** - Straightforward approach to type sync

### Specialized Documentation
- **[Context API](./docs/CONTEXT_API.md)** - Advanced context management for components and custom elements
- **[Custom Elements](./docs/CUSTOM_ELEMENTS.md)** - Creating and using Web Components with Woby

## Key Features

### Context API

Woby provides a powerful Context API that works seamlessly with both JSX components and custom elements:

```tsx
// Create a context
const ThemeContext = createContext('light')

// Use in JSX components
const ThemedButton = () => {
  const theme = useContext(ThemeContext)
  return <button className={theme}>Themed Button</button>
}

// Use in custom elements
const ThemedElement = defaults(() => ({}), () => {
  const [theme, mount] = useMountedContext(ThemeContext)
  return <div>{mount}Theme: {theme}</div>
})

customElement('themed-element', ThemedElement)
```

[Learn more about the Context API](./docs/CONTEXT_API.md)

### Custom Elements

Woby provides first-class support for creating custom HTML elements with reactive properties:

```tsx
// Define a component with default props
const Counter = defaults(() => ({
  value: $(0, { type: 'number' } as const),
  title: $('Counter')
}), ({ value, title }) => (
  <div>
    <h1>{title}</h1>
    <p>Count: {value}</p>
    <button onClick={() => value(prev => prev + 1)}>+</button>
  </div>
))

// Register as a custom element
customElement('counter-element', Counter)

// Use in JSX or HTML
// JSX: <counter-element value={5} title="My Counter" />
// HTML: <counter-element value="5" title="My Counter"></counter-element>
```

### Advanced Nested Property Support

One of Woby's unique features is its advanced nested property support, allowing you to set deeply nested properties directly through HTML attributes:

```html
<!-- Set nested properties using $ notation (works in both HTML and JSX) -->
<user-card 
  user$name="John Doe"
  user$details$age="30"
  style$font-size="1.2em"
  style$color="blue">
</user-card>

<!-- Set nested properties using . notation (HTML only) -->
<user-card 
  user.name="John Doe"
  user.details.age="30"
  style.font-size="1.2em"
  style.color="blue">
</user-card>
```

This feature is not available in React or SolidJS, making Woby a more powerful choice for creating highly configurable custom elements that can be used directly in HTML.

[Learn more about Custom Elements](./docs/CUSTOM_ELEMENTS.md)

## Demos

You can find some demos and benchmarks below, more demos are contained inside the repository.

- Playground: https://codesandbox.io/s/playground-7w2pxg
- Benchmark: https://krausest.github.io/js-framework-benchmark/current.html
- Counter: https://codesandbox.io/s/demo-counter-23fv5
- Clock: https://codesandbox.io/s/demo-clock-w1e7yb
- Emoji Counter: https://codesandbox.io/s/demo-emoji-counter-j91iz2
- HyperScript: https://codesandbox.io/s/demo-hyperscript-h4rf38
- HTML Template Literal: https://codesandbox.io/s/demo-html-lvfeyo
- Single-file HTML: https://codesandbox.io/s/demo-html-dueygt?file=/public/index.html
- Spiral: https://codesandbox.io/s/demo-spiral-ux33p6
- Store Counter: https://codesandbox.io/s/demo-store-counter-kvoqrw
- Triangle: https://codesandbox.io/s/demo-triangle-l837v0
- Boxes: https://codesandbox.io/s/demo-boxes-wx6rqb

## AI Assistant Instructions

### For AI Coding Assistants

When using AI coding assistants to help with Woby development, please provide these explicit instructions to ensure proper understanding of Woby patterns:

1.  **Framework Specific Instructions**: "Use Woby patterns, NOT React patterns. Woby uses observables with `$()` and `$()` functions, not React hooks like useState, useEffect with dependency arrays, or useCallback."

2.  **Observable-Based Reactivity**: "In Woby, declare reactive variables with `$()`, and access their values with `$()` in reactive contexts. Woby automatically tracks dependencies when you use `$()`."

3.  **No Dependency Arrays**: "Woby hooks like `useEffect` and `useMemo` do not require dependency arrays. Dependencies are automatically tracked when accessed with `$()`."

4.  **Reactive Patterns**: "Direct observable passing (`{userName}`) is preferred for simple reactive content. For complex expressions, use function expressions (`{() => $(userName)}`) which are automatically tracked."

### Common Anti-Patterns to Avoid

``tsx
// ❌ Anti-pattern: React-style useState
const [count, setCount] = useState(0)

// ✅ Woby pattern
const count = $(0)

// ❌ Anti-pattern: React useEffect with dependency array
useEffect(() => {
  console.log(count)
}, [count])

// ✅ Woby pattern
useEffect(() => {
  console.log($(count))
})

// ❌ Anti-pattern: Non-reactive content
<div>Hello {$(userName)}</div>

// ✅ Woby pattern
<div>Hello {userName}</div>

// ❌ Anti-pattern: React-style array mapping
{todos.map(todo => <div>{todo.text}</div>)}

// ✅ Woby pattern
<For values={todos}>{(todo) => <div>{todo.text}</div>}</For>
```

## Contributing

Contributions are welcome! Please read our [contributing guidelines](./docs/Contributing.md) before submitting pull requests.

## Thanks

- **[S](https://github.com/adamhaile/S)**: for pioneering reactive programming approaches that inspired this framework.
- **[sinuous/observable](https://github.com/luwes/sinuous/tree/master/packages/sinuous/observable)**: for providing an excellent Observable implementation that served as the foundation for this library.
- **[solid](https://www.solidjs.com)**: for serving as a reference implementation, popularizing signal-based reactivity, and building a strong community.
- **[solid](https://www.solidjs.com)**: for serving as a reference implementation, popularizing signal-based reactivity, and building a strong community.
- **[trkl](https://github.com/jbreckmckye/trkl)**: for demonstrating the power of minimal, focused implementations.

## License

MIT
    }
    return currentTodos
  })

  const activeCount = useMemo(() => {
    return $(todos).filter(todo => !todo.completed).length
  })

  return (
    <div class="todo-app max-w-md mx-auto p-4">
      <h1 class="text-2xl font-bold mb-4 text-center">My Todo App</h1>
      
      {/* Add new todo */}
      <div class="flex gap-2 mb-4">
        <input
          type="text"
          value={input}
          onInput={(e) => input(e.target.value)}
          placeholder="Add a new todo..."
          onKeyPress={(e) => e.key === 'Enter' && addTodo()}
          class="flex-1 p-2 border border-gray-300 rounded"
        />
        <button 
          onClick={addTodo}
          class="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
        >
          Add
        </button>
      </div>

      {/* Filter buttons */}
      <div class="flex justify-center gap-2 mb-4">
        {['all', 'active', 'completed'].map((filterName) => (
          <button
            key={filterName}
            onClick={() => setFilter(filterName)}
            class={[
              'px-3 py-1 rounded',
              () => $(filter) === filterName 
                ? 'bg-blue-500 text-white' 
                : 'bg-gray-200 hover:bg-gray-300'
            ]}
          >
            {filterName.charAt(0).toUpperCase() + filterName.slice(1)}
          </button>
        ))}
      </div>

      {/* Todo list */}
      <ul class="list-none p-0">
        <For values={filteredTodos}>
          {(todo) => (
            <li class={[
              'flex items-center p-2 border-b border-gray-200 gap-2',
              { 
                'line-through text-gray-500': todo.completed,
                'bg-yellow-50': () => todo.id % 2 === 0  // Alternate row styling
              }
            ]}>
              <input
                type="checkbox"
                checked={todo.completed}
                onChange={() => toggleTodo(todo.id)}
                class="w-4 h-4"
              />
              <span class="flex-1">{todo.text}</span>
              <button 
                class="w-6 h-6 flex items-center justify-center bg-red-500 text-white rounded-full hover:bg-red-600 text-xs"
                onClick={() => removeTodo(todo.id)}
              >
                ✕
              </button>
            </li>
          )}
        </For>
      </ul>

      {/* Stats */}
      <div class="mt-4 p-2 bg-gray-100 rounded text-sm">
        Total: {() => $(todos).length} | 
        Active: {activeCount} |
        Completed: {() => $(todos).filter(t => t.completed).length}
      </div>
    </div>
  )
}

// Render the application
render(<TodoApp />, document.getElementById('app')!)
```

## React Compatibility Guide

### useState → Observable

```tsx
// React
const [count, setCount] = useState(0)

// Woby
const count = $(0)
// To update: count(1) or count(prev => prev + 1)
```

### useEffect → useEffect (but different)

```tsx
// React
useEffect(() => {
  console.log(count)
}, [count])

// Woby
useEffect(() => {
  console.log($(count))
})
// No dependency array needed!
```

### useMemo → useMemo (but different)

```tsx
// React
const doubled = useMemo(() => count * 2, [count])

// Woby
const doubled = useMemo(() => $(count) * 2)
// No dependency array needed!
```

### Conditional Rendering

```tsx
// React
{isLoggedIn && <div>Welcome!</div>}

// Woby
<If when={isLoggedIn}>
  <div>Welcome!</div>
</If>
```

### List Rendering

```tsx
// React
{todos.map(todo => <div key={todo.id}>{todo.text}</div>)}

// Woby
<For values={todos}>
  {(todo) => <div>{todo.text}</div>}
</For>
```

### React to Woby Type Conversions

| React Type | Woby Equivalent | Description |
|------------|-----------------|-------------|
| `React.ReactNode` | `JSX.Child` | Represents any renderable content |
| `React.FC<Props>` | `JSX.ComponentFunction<Props>` | Function component type |
| `React.ComponentType<Props>` | `JSX.Component<Props>` | Union of function components and intrinsic elements |
| `React.PropsWithChildren<Props>` | `Props & { children?: JSX.Child }` | Props interface with children |
| `React.Ref<T>` | `JSX.Ref<T>` | Ref type definition |
| `React.MutableRefObject<T>` | Direct DOM access or observable refs | Ref object equivalent |
| `React.Context<T>` | `Woby.Context<T>` | Context object (see createContext) |
| `React.Dispatch<React.SetStateAction<T>>` | Observable setter pattern | State update function |
| `React.HTMLProps<T>` | `JSX.HTMLAttributes<T>` | HTML element props |
| `React.CSSProperties` | `JSX.CSSProperties` | CSS properties object |

For a comprehensive guide on React to Woby type conversions, see our [React to Woby Type Conversion Guide](./docs/React-to-Woby-Type-Conversion.md).

## HTML Utility Types

Woby provides a set of HTML utility types that make it easier to work with common HTML attribute patterns in custom elements. These utilities implement the `ObservableOptions` interface and provide consistent conversion between JavaScript values and HTML attributes.

### Available HTML Utilities

| Woby Utility | Description |
|--------------|-------------|
| `HtmlBoolean` | Handles boolean values with automatic conversion |
| `HtmlNumber` | Handles numeric values with automatic conversion |
| `HtmlDate` | Handles Date values with ISO string serialization |
| `HtmlBigInt` | Handles BigInt values with automatic conversion |
| `HtmlObject` | Handles Object values with JSON serialization |
| `HtmlLength` | Handles CSS length values (px, em, rem, %, etc.) |
| `HtmlBox` | Handles CSS box values (margin, padding, border, etc.) |
| `HtmlColor` | Handles CSS color values (hex, rgb, etc.) |
| `HtmlStyle` | Handles CSS style values (objects and strings) |

### Usage Example

``tsx
import { $, defaults, customElement, HtmlBoolean, HtmlNumber, HtmlColor, HtmlStyle } from 'woby'

interface CounterProps {
  count?: number
  enabled?: boolean
  color?: string
  styles?: Record<string, string | number>
}

const def = () => ({
  count: $(0, HtmlNumber),
  enabled: $(true, HtmlBoolean),
  color: $('#000000', HtmlColor),
  styles: $({} as Record<string, string | number>, HtmlStyle)
})

const Counter = defaults(def, (props: CounterProps) => {
  const { count, enabled, color, styles } = props
  return (
    <div style={() => ({ color: $(color), ...$$(styles) })}>
      <span>Count: {count}</span>
      <span>Status: {enabled ? 'Enabled' : 'Disabled'}</span>
    </div>
  )
})

// Register as custom element
customElement('styled-counter', Counter)
```

### Benefits of HTML Utility Types

1. **Type Safety**: Each utility provides proper type conversion between HTML attributes and JavaScript values
2. **Consistency**: All utilities follow the same pattern and behavior
3. **Automatic Serialization**: Complex values are automatically serialized to/from HTML attributes
4. **Error Handling**: Utilities handle edge cases and invalid values gracefully
5. **Empty String Handling**: All utilities treat empty strings as `undefined` for consistent behavior
6. **Equality Checking**: Each utility implements proper equality checking for value comparison

## Performance Tips

1.  **Use Direct Observable Passing**: For simple reactive content, pass observables directly rather than using `$()` in functions
2.  **Group Related Effects**: Separate unrelated concerns into individual effects for better performance
3.  **Use Early Returns**: Skip unnecessary work in effects when dependencies haven't changed meaningfully
4.  **Choose the Right List Component**: Use `For` for objects, `ForValue` for primitives, `ForIndex` for fixed-size lists
5.  **Avoid Unnecessary useMemo**: Simple expressions with `() =>` are automatically tracked and often don't need `useMemo`

## APIs

| Core Methods                        | Components                | Hooks                             | Types & Utilities                  | Miscellaneous            |
|------------------------------------|---------------------------|-----------------------------------|------------------------------------|--------------------------|
| [`](#methods)                    | [`Dynamic`](#dynamic)     | [`useAbortController`](#useabortcontroller) | [`Context`](#context)             | [`Contributing`](#contributing) |
| [`batch`](#batch)                  | [`ErrorBoundary`](#errorboundary) | [`useAbortSignal`](#useabortsignal) | [`Directive`](#directive)         | [`Globals`](#globals)   |
| [`createContext`](#createcontext) | [`For`](#for)             | [`useAnimationFrame`](#useanimationframe) | [`DirectiveOptions`](#directiveoptions) | [`JSX`](#jsx)           |
| [`createDirective`](#createdirective) | [`ForIndex`](#forindex) | [`useAnimationLoop`](#useanimationloop) | [`FunctionMaybe`](#functionmaybe) | [`Tree Shaking`](#tree-shaking) |
| [`customElement`](#customelement) | [`ForValue`](#forvalue)   | [`useBoolean`](#useboolean)       | [`Observable`](#observable)       | [`TypeScript`](#typescript) |
| [`createElement`](#createelement) | [`Fragment`](#fragment)   | [`useCleanup`](#usecleanup)       | [`ObservableReadonly`](#observablereadonly) |                          |
| [`h`](#h)                          | [`If`](#if)               | [`useContext`](#usecontext)       | [`ObservableMaybe`](#observablemaybe) |                          |
| [`html`](#html)                    | [`Portal`](#portal)       | [`useDisposed`](#usedisposed)     | [`ObservableOptions`](#observableoptions) |                          |
| [`isBatching`](#isbatching)       | [`Suspense`](#suspense)   | [`useEffect`](#useeffect)         | [`Resource`](#resource)           |                          |
| [`isObservable`](#isobservable)   | [`Switch`](#switch)       | [`useError`](#useerror)           | [`StoreOptions`](#storeoptions)   |                          |
| [`isServer`](#isserver)           | [`Tary`](#ternary)     | [`useEventListener`](#useeventlistener) |                                |                          |
| [`isStore`](#isstore)             |                           | [`useFetch`](#usefetch)           |                                    |                          |
| [`lazy`](#lazy)                   |                           | [`useIdleCallback`](#useidlecallback) |                                |                          |
| [`render`](#render)               |                           | [`useIdleLoop`](#useidleloop)     |                                    |                          |
| [`renderToString`](#rendertostring) |                         | [`useInterval`](#useinterval)     |                                    |                          |
| [`resolve`](#resolve)             |                           | [`useMemo`](#usememo)             |                                    |                          |
| [`store`](#store)                 |                           | [`useMicrotask`](#usemicrotask)   |                                    |                          |
| [`template`](#template)           |                           | [`usePromise`](#usepromise)       |                                    |                          |
| [`untrack`](#untrack)             |                           | [`useReaction`](#usereaction)     |                                    |                          |
                                    |                           | [`useReadonly`](#usereadonly)     |                                    |                          |
                                    |                           | [`useResolved`](#useresolved)     |                                    |                          |
                                    |                           | [`useResource`](#useresource)     |                                    |                          |
                                    |                           | [`useRoot`](#useroot)             |                                    |                          |
                                    |                           | [`useSelector`](#useselector)     |                                    |                          |
                                    |                           | [`useTimeout`](#usetimeout)       |                                    |                          |
## Usage

Woby serves as a view layer built on top of the Observable library [`soby`](https://github.com/wobyjs/soby). Understanding how soby works is essential for effectively using Woby.

Woby re-exports all soby functionality with interfaces adjusted for component and hook usage, along with additional framework-specific functions.

### Counter Example

Here's a complete counter example that demonstrates Woby's reactive capabilities:

**Source:** [@woby/demo](https://github.com/wobyjs/demo) ⭐

```tsx
import { $, $, useMemo, render, Observable, customElement, ElementAttributes } from 'woby'

const Counter = ({ increment, decrement, value, ...props }: { 
  increment: () => number, 
  decrement: () => number, 
  value: Observable<number> 
}): JSX.Element => {
  const v = $('abc')
  const m = useMemo(() => {
    return $(value) + $(v)
  })
  return <div {...props}>
    <h1>Counter</h1>
    <p>{value}</p>
    <p>{m}</p>
    <button onClick={increment}>+</button>
    <button onClick={decrement}>-</button>
  </div>
}

// Register as custom element
customElement('counter-element', Counter, 'value', 'class', 'style-*')

declare module 'woby' {
    namespace JSX {
        interface IntrinsicElements {
            'counter-element': ElementAttributes<typeof Counter>
        }
    }
}


const App = () => {
  const value = $(0)
  const increment = () => value(prev => prev + 1)
  const decrement = () => value(prev => prev - 1)

  return <counter-element 
    value={value} 
    increment={increment} 
    decrement={decrement} 
    class="border-2 border-black border-solid bg-amber-400" 
  />
}

render(<App />, document.getElementById('app'))
```

**Output:**
```
<counter-element value="0" class="border-2 border-black border-solid bg-amber-400">
  <div class="border-2 border-black border-solid bg-amber-400">
    <h1>Counter</h1>
    <p>0</p>
    <p>0abc</p>
    <button>+</button>
    <button>-</button>
  </div>
</counter-element>
```

Modifying the value attribute on <counter-element value="0"> triggers an immediate update to its associated observable.

### Advanced Class Management

Woby provides powerful built-in class management that supports complex class expressions with full reactive observable support, similar to popular libraries like `classnames` and `clsx`.

#### Class Array Support

Woby supports complex class expressions including arrays, objects, and functions:

```tsx
// Array of classes
<div class={['red', 'bold']}>Text</div>

// Nested arrays
<div class={['red', ['bold', ['italic']]]}>Text</div>

// Mixed types
<div class={[
  "red",
  () => ($(value) % 2 === 0 ? "bold" : ""),
  { hidden: true, italic: false },
  ['hello', ['world']]
]}>Complex classes</div>
```

#### Reactive Classes

All class expressions support reactive observables that automatically update when values change:

```tsx
const isActive = $(false)
const theme = $('dark')

// Reactive boolean
<div class={{ active: isActive }}>Toggle me</div>

// Reactive string
<div class={() => `btn btn-${theme()}`}>Themed button</div>

// Complex reactive expression
<div class={[
  'base-class',
  () => isActive() ? 'active' : 'inactive',
  { 'loading': loadingState() }
]}>Dynamic element</div>
```

#### Class Object Syntax

Woby supports object syntax for conditional classes where keys are class names and values are boolean conditions:

```tsx
const error = $(false)
const warning = $(false)

<div class={{
  'base': true,           // Always applied
  'error': error,         // Applied when error is truthy
  'warning': warning,     // Applied when warning is truthy
  'success': !error && !warning  // Applied when neither error nor warning
}}>Status element</div>
```

#### Function-based Classes

Classes can be computed using functions that return class strings or other class expressions:

```tsx
const count = $(0)

<div class={() => count() > 5 ? 'high-count' : 'low-count'}>
  Count: {count}
</div>

// Function returning complex expression
<div class={() => [
  'base',
  count() > 10 ? 'large' : 'small',
  { 'even': count() % 2 === 0 }
]}>
  Dynamic element
</div>
```

### Built-in Classnames/CLSX/Tailwind-Merge Support

Woby's class system provides built-in functionality equivalent to popular libraries:

- **Classnames/CLSX-like syntax**: Supports all the same patterns as the popular `classnames` and `clsx` libraries
- **Tailwind CSS ready**: Works seamlessly with Tailwind CSS class patterns
- **No external dependencies**: Built-in implementation eliminates the need for external libraries
- **Reactive by default**: All class expressions automatically update when observables change
- **Performance optimized**: Efficient implementation that minimizes DOM updates

#### Migration from CLSX

If you're familiar with `clsx`, Woby's class system works similarly:

```tsx
// Instead of: clsx('foo', true && 'bar', 'baz')
<div class={['foo', true && 'bar', 'baz']}>Content</div>

// Instead of: clsx({ foo:true, bar:false, baz:isTrue() })
<div class={{ foo:true, bar:false, baz:isTrue() }}>Content</div>

// Instead of: clsx(['foo', 0, false, 'bar'])
<div class={['foo', 0, false, 'bar']}>Content</div>
```

#### Integration with Tailwind Merge

For advanced Tailwind CSS class merging, you can wrap your expressions with a custom merge function:

```tsx
import { twMerge } from 'tailwind-merge'

const mergedClass = useMemo(() => twMerge(
  'px-4 py-2 bg-blue-500',
  isActive() ? 'bg-blue-700' : 'bg-blue-500'
))

<div class={mergedClass}>Merged classes</div>
```

All reactive elements in class expressions should be wrapped in `useMemo` or arrow functions `() =>` to ensure proper reactivity:

```tsx
// Correct - wrapped in useMemo
const dynamicClass = useMemo(() => ({
  'active': isActive(),
  'disabled': isDisabled()
}))

<div class={dynamicClass}>Content</div>

// Correct - wrapped in arrow function
<div class={() => isActive() ? 'active' : 'inactive'}>Content</div>

// Correct - observables automatically handled
<div class={{ 'active': isActive }}>Content</div>
```

### Methods

The following top-level functions are provided.

#### `

This function is just the default export of `soby`, it can be used to wrap a value in an observable.

No additional methods are attached to this function. Everything that `soby` attaches to it is instead exported as components and hooks.

[Read upstream documentation](https://github.com/wobyjs/soby#core).

Interface:

```ts
function $ <T> (): Observable<T | undefined>;
function $ <T> ( value: undefined, options?: ObservableOptions<T | undefined> ): Observable<T | undefined>;
function $ <T> ( value: T, options?: ObservableOptions<T> ): Observable<T>;
```

Usage:

```tsx
import {$} from 'woby';

// Create an observable without an initial value

$<number> ();

// Create an observable with an initial value

$(1);

// Create an observable with an initial value and a custom equality function

const equals = ( value, valuePrev ) => Object.is ( value, valuePrev );

const o = $( 1, { equals } );

// Create an observable with an initial value and a special "false" equality function, which is a shorthand for `() => false`, which causes the observable to always emit when its setter is called

const oFalse = $( 1, { equals: false } );

// Getter

o (); // => 1

// Setter

o ( 2 ); // => 2

// Setter via a function, which gets called with the current value

o ( value => value + 1 ); // => 3

// Setter that sets a function, it has to be wrapped in another function because the above form exists

const noop = () => {};

o ( () => noop );
```

#### `

This function unwraps a potentially observable value.

[Read upstream documentation](https://github.com/wobyjs/soby#get).

Interface:

```ts
function $ <T> ( value: T ): (T extends ObservableReadonly<infer U> ? U : T);
```

Usage:

```tsx
import {$} from 'woby';

// Getting the value out of an observable

const o = $(123);

$ ( o ); // => 123

// Getting the value out of a function

$ ( () => 123 ); // => 123

// Getting the value out of an observable but not out of a function

$ ( o, false ); // => 123
$ ( () => 123, false ); // => () => 123

// Getting the value out of a non-observable and non-function

$ ( 123 ); // => 123
```

#### `$$`

This function unwraps a potentially observable value. Recent enhancements to Soby (which Woby uses as its reactive core) have added automatic `valueOf()` and `toString()` methods to observable functions, making them behave more naturally in JavaScript contexts where primitives are expected.

[Read upstream documentation](https://github.com/wobyjs/soby#get).

Interface:

```ts
function $$ <T> ( value: T ): (T extends ObservableReadonly<infer U> ? U : T);
```

Usage:

```tsx
import {$$} from 'woby';

// Getting the value out of an observable

const o = $(123);

$$ ( o ); // => 123

// Getting the value out of a function

$$ ( () => 123 ); // => 123

// Getting the value out of an observable but not out of a function

$$ ( o, false ); // => 123
$$ ( () => 123, false ); // => () => 123

// Getting the value out of a non-observable and non-function

$$ ( 123 ); // => 123
```

##### Enhanced Observable Functions

Recent enhancements to Soby have added automatic `valueOf()` and `toString()` methods to observable functions. These methods use `deepResolve()` to automatically resolve observables to their current values in various contexts.

###### Technical Implementation

The enhancement was implemented in Soby's `src/objects/callable.ts` by adding the following lines to both `readable` and `writable` observable function generators:

```typescript
fn.valueOf = () => deepResolve(fn)
fn.toString = () => fn.valueOf().toString()
```

This change affects the creation of observable functions, making them behave more naturally in JavaScript contexts where primitives are expected.

###### Automatic String Conversion

Observables now automatically resolve to their values in string contexts:

```typescript
import {$} from 'woby'

// In template literals
const name = $('John')
console.log(`Hello, ${name}!`) // Outputs: "Hello, John!"

// In JSX expressions
const App = () => {
  const count = $(5)
  return <div>Count: {count}</div> // Renders: "Count: 5"
}
```

###### Mathematical Operations

Observables automatically resolve in mathematical operations:

```typescript
import {$} from 'woby'

const count = $(5)
const result = count + 10 // Results in 15 automatically

const price = $(19.99)
const tax = $(0.08)
const total = price * (1 + tax) // Automatically calculates with current values
```

###### DOM Attribute Binding

When binding observables to DOM attributes, they automatically convert to appropriate string representations:

```typescript
import {$} from 'woby'

const isVisible = $(true)
const opacity = $(0.5)

// These will automatically convert to appropriate string values
const element = <div hidden={isVisible} style={{ opacity }}>Content</div>
```

###### Performance Considerations

The `deepResolve` function recursively resolves observables, which means for deeply nested structures there could be performance implications in hot paths. The resolution happens every time `valueOf()` or `toString()` is called.

For performance-critical applications with deeply nested structures, explicit unwrapping with `$$()` may be preferred:

```typescript
// This maintains reactivity by directly passing the observable
const reactive = <div>{deeplyNestedObject}</div>

// This unwraps the observable to get its static value, losing reactivity
const staticValue = <div>{$$(deeplyNestedObject)}</div>

// With the valueOf enhancement, mathematical operations are simplified
const price = $(19.99);
const quantity = $(3);
const total = <div>Total: {() => price * quantity}</div>; // Automatically computes 59.97
```

###### Backward Compatibility

This enhancement improves rather than breaks existing functionality:

1. All existing code continues to work as before
2. Explicit unwrapping with `$$()` still works and may be preferred in performance-critical situations
3. The enhancement provides additional convenience without removing any capabilities

#### `batch`

This function holds onto updates within its scope and flushes them out once it exits.

[Read upstream documentation](https://github.com/wobyjs/soby#batch).

Interface:

```ts
function batch <T> ( fn: () => T ): T;
function batch <T> ( value: T ): T;
```

Usage:

```tsx
import {batch} from 'woby';

batch // => Same as require ( 'soby' ).batch
```

#### `createContext`

This function creates a context object, optionally with a default value, which can later be used to provide a new value for the context or to read the current value.

A context's `Provider` will register the context with its children, which is always what you want, but it can lead to messy code due to nesting.

A context's `register` function will register the context with the current parent observer, which is usually only safe to do at the root level, but it will lead to very readable code.

Interface:

```ts
type ContextProvider<T> = ( props: { value: T, children: JSX.Element } ) => JSX.Element;
type ContextRegister<T> = ( value: T ) => void;
type Context<T> = { Provider: ContextProvider<T>, register: ContextRegister<T> };

function createContext <T> ( defaultValue?: T ): Context<T>;
```

Usage:

```tsx
import {createContext, useContext} from 'woby';

const App = () => {
  const Context = createContext ( 123 );
  return (
    <>
      {() => {
        const value = useContext ( Context );
        return <p>{value}</p>;
      }}
      <Context.Provider value={312}>
        {() => {
          const value = useContext ( Context );
          return <p>{value}</p>;
        }}
      </Context.Provider>
    </>
  );
};
```

#### `createDirective`

This function creates a directive provider, which can be used to register a directive with its children.

A directive is a function that always receives an `Element` as its first argument, which is basically a ref to the target element, and arbitrary user-provided arguments after that.

Each directive has a unique name and it can be called by simply writing `use:directivename={[arg1, arg2, ...argN]]}` in the JSX.

Directives internally are registered using context providers, so you can also override directives for a particular scope just by registering another directive with the same name closer to where you are reading it.

A directive's `Provider` will register the directive with its children, which is always what you want, but it can lead to messy code due to nesting.

A directive's `register` function will register the directive with the current parent observer, which is usually only safe to do at the root level, but it will lead to very readable code.

Interface:

```ts
type DirectiveFunction = <T extends unknown[]> ( ref: Element, ...args: T ) => void;
type DirectiveProvider = ( props: { children: JSX.Element } ) => JSX.Element;
type DirectiveRef<T extends unknown[]> = ( ...args: T ) => (( ref: Element ) => void);
type DirectiveRegister = () => void;
type Directive = { Provider: DirectiveProvider, ref: DirectiveRef, register: DirectiveRegister };

function createDirective <T extends unknown[] = []> ( name: string, fn: DirectiveFunction<T>, options?: DirectiveOptions ): Directive;
```

Usage:

```tsx
import {createDirective, useEffect} from 'woby';

// First of all if you are using TypeScript you should extend the "JSX.Directives" interface, so that TypeScript will know about your new directive

namespace JSX {
  interface Directives {
    tooltip: [title: string] // Mapping the name of the directive to the array of arguments it accepts
  }
}

// Then you should create a directive provider

const TooltipDirective = createDirective ( 'tooltip', ( ref, title: string ) => {

  useEffect ( () => {

    if ( !ref () ) return; // The element may not be available yet, or it might have been unmounted

    // Code that implements a tooltip for the given element here...

  });

});

// Then you can use the new "tooltip" directive anywhere inside the "TooltipDirective.Provider"

const App = () => {
  return (
    <TooltipDirective.Provider>
      <input value="Placeholder..." use:tooltip={['This is a tooltip!']} />
    </TooltipDirective.Provider>
  );
};

// You can also use directives directly by padding them along as refs

const App = () => {
  return <input ref={TooltipDirective.ref ( 'This is a tooltip!' )} value="Placeholder..." />;
};
```

#### `createElement`

This is the internal function that will make DOM nodes and call/instantiate components, it will be called for you automatically via JSX.

Interface:

```ts
function createElement <P = {}> ( component: JSX.Component<P>, props: P | null, ...children: JSX.Element[] ): () => JSX.Element);
```

Usage:

```tsx
import {createElement} from 'woby';

const element = createElement ( 'div', { class: 'foo' }, 'child' ); // => () => HTMLDivElement
```

#### `h`

This function is just an alias for the `createElement` function, it's more convenient to use if you want to use Woby in hyperscript mode just because it has a much shorter name.

Interface:

```ts
function h <P = {}> ( component: JSX.Component<P>, props: P | null, ...children: JSX.Element[] ): () => JSX.Element);
```

Usage:

```tsx
import {h} from 'woby';

const element = h ( 'div', { class: 'foo' }, 'child' ); // => () => HTMLDivElement
```

#### `html`

This function provides an alternative way to use the framework, without writing JSX or using the `h` function manually, it instead allows you to write your markup as tagged template literals.

[`htm`](https://github.com/developit/htm) is used under the hood, read its documentation.

Interface:

```ts
function html ( strings: TemplateStringsArray, ...values: any[] ): JSX.Element;```

Usage:

```tsx
import {html, If} from 'woby';

const Counter = (): JSX.Element => {
  const value = $(0);
  const increment = () => value ( prev => prev + 1 );
  const decrement = () => value ( prev => prev - 1 );
  return html`
    <h1>Counter</h1>
    <p>${value}</p>
    <button onClick=${increment}>+</button>
    <button onClick=${decrement}>-</button>
  `;
};

// Using a custom component without registering it

const NoRegistration = (): JSX.Element => {
  return html`
    <${If} when=${true}>
      <p>content</p>
    </${If}>
  `;
};

// Using a custom component after registering it, so you won't need to interpolate it anymore

html.register ({ If });

const NoRegistration = (): JSX.Element => {
  return html`
    <If when=${true}>
      <p>content</p>
    </If>
  `;
};
```

#### `isBatching`

This function tells you if batching is currently active or not.

Interface:

```ts
function isBatching (): boolean;
```

Usage:

```tsx
import {batch, isBatching} from 'woby';

// Checking if currently batching

isBatching (); // => false

batch ( () => {

  isBatching (); // => true

});

isBatching (); // => false
```

#### `isObservable`

This function tells you if a variable is an observable or not.

Interface:

```ts
function isObservable <T = unknown> ( value: unknown ): value is Observable<T> | ObservableReadonly<T>;
```

Usage:

```tsx
import {$, isObservable} from 'woby';

isObservable ( 123 ); // => false
isObservable ( $(123) ); // => true
```

#### `isServer`

This function tells you if your code is executing in a browser environment or not.

Interface:

```ts
function isServer (): boolean;
```

Usage:

```tsx
import {isServer} from 'woby';

isServer (); // => true or false
```

#### `isStore`

This function tells you if a variable is a store or not.

Interface:

```ts
function isStore ( value: unknown ): boolean;
```

Usage:

```tsx
import {store, isStore} from 'woby';

isStore ( {} ); // => false
isStore ( store ( {} ) ); // => true
```

#### `lazy`

This function creates a lazy component, which is loaded via the provided function only when/if needed.

This function uses `useResource` internally, so it's significant for `Suspense` too.

Interface:

```ts
type LazyComponent<P = {}> = ( props: P ) => ObservableReadonly<Child>;
type LazyFetcher<P = {}> = () => Promise<{ default: JSX.Component<P> } | JSX.Component<P>>;
type LazyResult<P = {}> = LazyComponent<P> & ({ preload: () => Promise<void> });

function lazy <P = {}> ( fetcher: LazyFetcher<P> ): LazyResult<P>;
```

Usage:

```ts
import {lazy} from 'woby';

const LazyComponent = lazy ( () => import ( './component' ) );
```

#### `render`

This function mounts a component inside a provided DOM element and returns a disposer function for unmounting it and stopping all reactivity inside it.

Interface:

```ts
function render ( child: JSX.Element, parent?: HTMLElement | null ): Disposer;
```

Usage:

```tsx
import {render} from 'woby';

const App = () => <p>Hello, World!</p>;

const dispose = render ( <App />, document.body );

dispose (); // Unmounted and all reactivity inside it stopped
```

#### `renderToString`

This function operates similarly to `render`, but returns a Promise that resolves to the HTML representation of the rendered component.

The current implementation works within browser-like environments. For server-side usage, [JSDOM](https://github.com/jsdom/jsdom) or similar solutions are required.

This function automatically waits for all `Suspense` boundaries to resolve before returning the HTML.

Interface:

```ts
function renderToString ( child: JSX.Element ): Promise<string>;
```

Usage:

```tsx
import {renderToString} from 'woby';

const App = () => <p>Hello, World!</p>;

const html = await renderToString ( <App /> );
```

#### `resolve`

This function resolves all reactivity within the provided argument, replacing each function with a memo that captures the function's value.

While developers may not need to use this function directly, it is internally necessary to ensure proper tracking of child values by their parent computations.

[Read upstream documentation](https://github.com/wobyjs/soby#resolve).

Interface:

```ts
type ResolvablePrimitive = null | undefined | boolean | number | bigint | string | symbol;
type ResolvableArray = Resolvable[];
type ResolvableObject = { [Key in string | number | symbol]?: Resolvable };
type ResolvableFunction = () => Resolvable;
type Resolvable = ResolvablePrimitive | ResolvableObject | ResolvableArray | ResolvableFunction;

function resolve <T> ( value: T ): T extends Resolvable ? T : never;
```

Usage:

```tsx
import {resolve} from 'woby';

resolve // => Same as require ( 'soby' ).resolve
```

#### `store`

This function returns a deeply reactive version of the passed object, where property accesses and writes are automatically interpreted as Observables reads and writes for you.

[Read upstream documentation](https://github.com/wobyjs/soby#store).

Interface:

```ts
function store <T> ( value: T, options?: StoreOptions ): T;
```

Usage:

```tsx
import {store} from 'woby';

store // => Same as require ( 'soby' ).store
```

#### `template`

This function enables constructing elements with [Solid](https://www.solidjs.com)-level performance without using the Babel transform, but also without the convenience of that.

This function works similarly to [sinuous](https://github.com/luwes/sinuous/tree/master)'s template function but provides a cleaner API, as props are accessed identically inside and outside the template.

This function can be used to wrap components that do not directly create observables or call hooks, significantly improving performance during component instantiation.

Interface:

```ts
function template <P = {}> ( fn: (( props: P ) => JSX.Element) ): (( props: P ) => () => Element);
```

Usage:

```tsx
import {template} from 'woby';

const Row = template ( ({ id, cls, label, onSelect, onRemove }) => { // Now Row is super fast to instantiate
  return (
    <tr class={cls}>
      <td class="col-md-1">{id}</td>
      <td class="col-md-4">
        <a onClick={onSelect}>{label}</a>
      </td>
      <td class="col-md-1">
        <a onClick={onRemove}>
          <span class="glyphicon glyphicon-remove" ariaHidden={true}></span>
        </a>
      </td>
      <td class="col-md-6"></td>
    </tr>
  );
});

const Table = () => {
  const rows = [ /* props for all your rows here */ ];
  return rows.map ( row => <Row {...row}> );
};
```

#### `untrack`

This function executes the provided function without creating dependencies on observables retrieved inside it.

[Read upstream documentation](https://github.com/wobyjs/soby#untrack).

Interface:

```ts
function untrack <T> ( fn: () => T ): T;
function untrack <T> ( value: T ): T;
```

Usage:

```tsx
import {untrack} from 'woby';

untrack // => Same as require ( 'soby' ).untrack
```

### Components

The following components are provided.

Crucially some components are provided for control flow, since regular JavaScript control flow primitives are not reactive, and we need to have reactive alternatives to them to have great performance.

#### `Dynamic`

This component is just an alternative to `createElement` that can be used in JSX, it's useful to create a new element dynamically.

Interface:

```ts
function Dynamic <P = {}> ( props: { component: ObservableMaybe<JSX.Component<P>, props?: FunctionMaybe<P | null>, children?: JSX.Element }): JSX. Element;
```

Usage:

```tsx
import {Dynamic} from 'woby';

const App = () => {
  const heading = 'h2';
  return (
    <Dynamic component={heading}>
      Some content
    </Dynamic>
  );
};
```

#### `ErrorBoundary`

The error boundary catches errors thrown inside it, and renders a fallback component when that happens.

Interface:

```ts
function ErrorBoundary ( props: { fallback: JSX.Element | (( props: { error: Error, reset: Callback } ) => JSX.Element), children: JSX.Element }): ObservableReadonly<JSX.Element>;
```

Usage:

```tsx
import {ErrorBoundary} from 'woby';

const Fallback = ({ reset, error }: { reset: () => void, error: Error }) => {
  return (
    <>
      <p>Error: {error.message}</p>
      <button onClick={reset}>Recover</button>
    </>
  );
};

const Som