### Install React Call

Source: https://github.com/desko27/react-call/blob/main/README.md

Install the react-call package using npm.

```sh
npm install react-call
```

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

### Example Structure

Source: https://github.com/desko27/react-call/blob/main/sites/web/README.md

The directory structure for a single gallery example, including the necessary files for the Callable, caller, composition, metadata, and optional notes.

```text
src/examples/<slug>/
├── callable.tsx   # the Callable: createCallable(…) + call.end(…)
├── caller.tsx     # the trigger UI: await Confirm.call(…)
├── index.tsx      # composition for the live demo (default export)
├── meta.ts        # typed metadata: title, category, behaviors, files…
└── notes.mdx      # optional prose — see "Writing notes.mdx" below
```

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

### Reactive Providers for Multi-Preview Hosts

Source: https://github.com/desko27/react-call/blob/main/README.md

Use reactive providers for dynamic setup in multi-preview hosts, allowing for more flexible configurations.

```javascript
import { Root } from "react-call";
import { useState } from "react";

export const decorators = [
  (Story) => {
    const [config, setConfig] = useState({});
    return (
      <Root {...config}>
        <Story />
      </Root>
    );
  },
];

```

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

### Static Providers for Multi-Preview Hosts

Source: https://github.com/desko27/react-call/blob/main/README.md

Configure static providers for environments like Storybook or Ladle to ensure react-call functions correctly in multi-preview setups.

```javascript
import { Root } from "react-call";

export const decorators = [
  (Story) => (
    <Root>
      <Story />
    </Root>
  ),
];

```

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

### Migration Example: Namespace to Flat Export

Source: https://github.com/desko27/react-call/blob/main/docs/adr/0015-flat-type-exports-over-namespace.md

Illustrates the change in import statements and type usage when migrating from the `ReactCall` namespace to flat named exports.

```typescript
// Before
import { createCallable, type ReactCall } from 'react-call'
type Props = ReactCall.Props<MyProps, MyResponse>

// After
import { createCallable, type PropsWithCall } from 'react-call'
type Props = PropsWithCall<MyProps, MyResponse>
```

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

### Setup Root Component

Source: https://github.com/desko27/react-call/blob/main/README.md

Include the callable component in your root component (e.g., `App.tsx`) to render active calls. This component acts as the mounting point for all active calls.

```diff
+ <Confirm />
//  ^-- it will render active calls
```

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

### Required MutationFn Example

Source: https://github.com/desko27/react-call/blob/main/skills/react-call/references/mutation-flow.md

Demonstrates a `useMutationFlow` setup where the `mutationFn` is required. The handler explicitly calls `call.end()` to close the Call. If the `mutationFn` throws, the Call remains open.

```tsx
import { createCallable } from 'react-call'
import { useMutationFlow, type MutationFn } from 'react-call/mutation-flow'

type Props = { mutationFn: MutationFn<boolean> }

export const Confirm = createCallable<Props, boolean>(({ call, mutationFn }) => {
  const submit = useMutationFlow(call, mutationFn)
  return (
    <div role="dialog">
      <button disabled={submit.pending} onClick={() => submit()}>Yes</button>
      <button onClick={() => call.end(false)}>No</button>
    </div>
  )
})

await Confirm.call({
  mutationFn: async (call) => {
    await api.delete(id)
    call.end(true) // the handler decides when to close
  },
})
```

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

### Add React Call Skill

Source: https://github.com/desko27/react-call/blob/main/docs/adr/0021-publish-consumer-usage-skill.md

Use this command to add the React Call skill to your project. The `--skill` flag is mandatory for proper installation.

```bash
npx skills add desko27/react-call --skill react-call
```

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

### SSR with Next.js / RSC

Source: https://github.com/desko27/react-call/blob/main/README.md

Example of setting up react-call for Server-Side Rendering (SSR) specifically within a Next.js environment using React Server Components (RSC).

```javascript
import { Root } from "react-call/server";

export default function Layout({ children }) {
  return <Root>{children}</Root>;
}

```

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

### Exit Animations

Source: https://github.com/desko27/react-call/blob/main/README.md

Configure exit animations for callable components. This example shows a simple fade-out effect.

```javascript
import { Root } from "react-call";

function App() {
  return (
    <Root exitAnimation={(node) => {
      node.style.opacity = 0;
      node.style.transition = "opacity 0.5s ease-out";
    }}>
      {/* Your app content */}
    </Root>
  );
}

```

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

### Example Component and Caller in Separate Blocks

Source: https://github.com/desko27/react-call/blob/main/docs/adr/0018-examples-gallery-islands-with-on-demand-sandpack.md

Code is presented in two distinct blocks: 'The Callable' for the component definition and 'The caller' for its usage. This separation mirrors the library's design and is crucial for the mental model.

```tsx
import { Button } from "@mui/material";

export default function Counter() {
  const [count, setCount] = React.useState(0);
  return (
    <Button variant="contained" onClick={() => setCount(count + 1)}>
      Clicked {count} times
    </Button>
  );
}

```

```tsx
import Counter from "./index.tsx?island";

export default function Page() {
  return <Counter />;
}

```

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

### Ending All Open Approvals

Source: https://github.com/desko27/react-call/blob/main/sites/web/src/examples/caller-resolve/notes.mdx

This example demonstrates how to end all currently open approval calls simultaneously with a single response value. This is useful for global actions like route changes or logouts.

```tsx
Approval.end(false) // decline all open approvals
```

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

### Development Commands

Source: https://github.com/desko27/react-call/blob/main/sites/web/README.md

Commands to run the development server, build the static output, and preview the production build locally for the web package.

```sh
pnpm --filter web dev      # http://localhost:4321
pnpm --filter web build    # static output → dist/
pnpm --filter web preview  # serve the production build locally
pnpm --filter web check:types
```

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

### Options for Multi-Preview Hosts

Source: https://github.com/desko27/react-call/blob/main/README.md

Configure various options for react-call within multi-preview host environments.

```javascript
import { Root } from "react-call";

export const decorators = [
  (Story) => (
    <Root
      exitAnimation={false}
      initialAnimation={false}
      animationDuration={0}
    >
      <Story />
    </Root>
  ),
];

```

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

### Set up the Root Component

Source: https://github.com/desko27/react-call/blob/main/README.md

Wrap your application with the `Root` component provided by react-call. This component manages the state and rendering of callable components.

```javascript
import { Root } from "react-call";

function App() {
  return (
    <Root>
      {/* Your app content */}
    </Root>
  );
}

```

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

### Mounting Confirm in Storybook Preview

Source: https://github.com/desko27/react-call/blob/main/skills/react-call/references/host.md

Use `mount` from `react-call/host` in your Storybook preview file to set up a shared root for Callables. This should be done once.

```tsx
// .storybook/preview.tsx
import { mount } from 'react-call/host'
import { Confirm } from '../src/Confirm'

mount(<Confirm />)

const preview = { /* normal Storybook config */ }
export default preview
```

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

### Mounting with Static Providers

Source: https://github.com/desko27/react-call/blob/main/README.md

When using static providers, pass them via the 'wrapper' option to the mount helper. This ensures the Confirm component receives necessary context like themes or locales.

```tsx
import { mount } from 'react-call/host'
import { ThemeProvider } from '@mui/material/styles'
import { lightTheme } from '../src/themes'
import { Confirm } from '../src/Confirm'

mount(<Confirm />, {
  wrapper: ({ children }) => (
    <ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
  ),
})
```

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

### Providing Context with a Reactive Wrapper

Source: https://github.com/desko27/react-call/blob/main/skills/react-call/references/host.md

For providers that depend on Storybook globals (e.g., toolbar toggles), define a component that subscribes to `useGlobals` and pass it as the `wrapper` to `mount`.

```tsx
import { useGlobals } from '@storybook/preview-api'

function ReactiveTheme({ children }: { children: ReactNode }) {
  const [{ theme = 'light' }] = useGlobals()
  return <ThemeProvider theme={theme === 'dark' ? darkTheme : lightTheme}>{children}</ThemeProvider>
}

mount(<Confirm />, { wrapper: ReactiveTheme })
```

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

### MutationFn with Payload Example

Source: https://github.com/desko27/react-call/blob/main/skills/react-call/references/mutation-flow.md

Illustrates passing a payload to the `mutationFn` using `MutationFn<Response, Payload>`. The payload is typed end-to-end, allowing different Triggers to forward distinct payloads.

```tsx
type Props = { mutationFn: MutationFn<boolean, { name: string }> }

export const Create = createCallable<Props, boolean>(({ call, mutationFn }) => {
  const [name, setName] = useState('')
  const submit = useMutationFlow(call, mutationFn)
  return <button onClick={() => submit({ name })}>Create</button>
})

await Create.call({
  mutationFn: async (call, payload) => { // payload: { name: string }
    await api.create(payload.name)
    call.end(true)
  },
})
```

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

### Vite Plugin for Automatic DisplayName Injection

Source: https://github.com/desko27/react-call/blob/main/README.md

The bundled Vite plugin automatically injects the displayName line during development, simplifying the HMR setup. No manual source changes are required.

```typescript
// vite.config.ts
import react from '@vitejs/plugin-react'
import reactCall from 'react-call/vite'

export default {
  plugins: [react(), reactCall()],
}
```

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

### Single-Context Repository Structure

Source: https://github.com/desko27/react-call/blob/main/docs/agents/domain.md

Illustrates the file structure for a single-context repository, highlighting the location of context files and ADRs.

```plaintext
/
├── CONTEXT.md
├── docs/adr/
│   ├── 0001-event-sourced-orders.md
│   └── 0002-postgres-for-write-model.md
└── src/

```

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

### Providing Context with a Static Wrapper

Source: https://github.com/desko27/react-call/blob/main/skills/react-call/references/host.md

Pass a `wrapper` component to `mount` to provide context like themes or routers to the shared root. This wrapper is rendered once.

```tsx
mount(<Confirm />, {
  wrapper: ({ children }) => <ThemeProvider theme={lightTheme}>{children}</ThemeProvider>,
})
```

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

### Mounting with Reactive Providers

Source: https://github.com/desko27/react-call/blob/main/README.md

For providers that depend on Storybook globals, use 'useGlobals' within a custom wrapper component passed to the mount helper. This allows dynamic theme switching based on Storybook toolbar toggles.

```tsx
import type { ReactNode } from 'react'
import { mount } from 'react-call/host'
import { useGlobals } from '@storybook/preview-api'
import { ThemeProvider } from '@mui/material/styles'
import { lightTheme, darkTheme } from '../src/themes'
import { Confirm } from '../src/Confirm'

function ReactiveTheme({ children }: { children: ReactNode }) {
  const [{ theme = 'light' }] = useGlobals()
  return (
    <ThemeProvider theme={theme === 'dark' ? darkTheme : lightTheme}>
      {children}
    </ThemeProvider>
  )
}

mount(<Confirm />, { wrapper: ReactiveTheme })
```

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

### Multi-Context Repository Structure

Source: https://github.com/desko27/react-call/blob/main/docs/agents/domain.md

Shows the file structure for a multi-context repository, differentiating between system-wide and context-specific ADRs.

```plaintext
/
├── CONTEXT-MAP.md
├── docs/adr/                          ← system-wide decisions
└── src/
    ├── ordering/
    │   ├── CONTEXT.md
    │   └── docs/adr/                  ← context-specific decisions
    └── billing/
        ├── CONTEXT.md
        └── docs/adr/

```

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

### Passing Root Props

Source: https://github.com/desko27/react-call/blob/main/README.md

Demonstrates how to pass props down to the `Root` component, which can then be accessed by callable components.

```javascript
import { Root } from "react-call";

function App() {
  return (
    <Root data-testid="root-component">
      {/* Your app content */}
    </Root>
  );
}

```

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

### Mount Options for react-call/host

Source: https://github.com/desko27/react-call/blob/main/skills/react-call/references/host.md

The `mount` function accepts an optional options object to configure the wrapper component and the DOM container for the shared root.

```tsx
mount(element, {
  wrapper?: ComponentType<{ children: ReactNode }>,
  container?: HTMLElement, // default: <div data-react-call-host> in document.body
})
```

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

### Create a GitHub Issue

Source: https://github.com/desko27/react-call/blob/main/docs/agents/issue-tracker.md

Use this command to create a new GitHub issue. A heredoc can be used for multi-line issue bodies.

```bash
gh issue create --title "..." --body "..."
```

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

### Optional MutationFn with .orEnd()

Source: https://github.com/desko27/react-call/blob/main/skills/react-call/references/mutation-flow.md

Shows how to use `useMutationFlow` with an optional `mutationFn`. The `.orEnd(value)` chain provides a fallback response when no `mutationFn` is supplied, otherwise it's a no-op.

```tsx
type Props = { mutationFn?: MutationFn<boolean> }

export const Confirm = createCallable<Props, boolean>(({ call, mutationFn }) => {
  const submit = useMutationFlow(call, mutationFn)
  //                  closes with `true` (Fallback response) if no mutationFn ↓
  return <button disabled={submit.pending} onClick={() => submit().orEnd(true)}>Yes</button>
})
```

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

### Marking Client Component in Next.js

Source: https://github.com/desko27/react-call/blob/main/skills/react-call/references/ssr-and-lazy.md

Mark the file where you run `createCallable(...)` as a Client Component using the 'use client' directive. This is necessary because the library uses `useSyncExternalStore`.

```tsx
'use client'

import { createCallable } from 'react-call'

export const Confirm = createCallable(/* ... */)
```

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

### React-Call Host Mount Options

Source: https://github.com/desko27/react-call/blob/main/README.md

The mount helper accepts an options object to customize the container and wrapper for the React-Call root. The default container is a div with the attribute 'data-react-call-host' in the document body.

```tsx
mount(element, {
  wrapper?: ComponentType<{ children: ReactNode }>
  container?: HTMLElement, // default: <div data-react-call-host> in document.body
})
```

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

### Call and Await a Component

Source: https://github.com/desko27/react-call/blob/main/README.md

Invoke a callable component and await its resolution. The component will be rendered, and its resolution value will be returned.

```javascript
async function handleClick() {
  const result = await MyCallableComponent({ name: "World" });
  console.log(result);
}

```

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

### Defining and Creating a Callable Component

Source: https://github.com/desko27/react-call/blob/main/skills/react-call/references/types.md

This snippet shows how to define the props and response types for a component, declare the component using the UserComponent type, and then create a callable version of it using createCallable. This pattern is useful for encapsulating component logic and making it available for calls.

```tsx
import { createCallable, type UserComponent } from 'react-call'

interface Props { message: string }
type Response = boolean

const ConfirmView: UserComponent<Props, Response> = ({ call, message }) => (
  <div role="dialog">{/* … */}</div>
)

export const Confirm = createCallable(ConfirmView)
```

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

### Dynamic Progress Notification with Upsert

Source: https://github.com/desko27/react-call/blob/main/README.md

Demonstrates using `upsert()` to create a dynamic progress notification that updates itself. The `Toast.end()` call is used to dismiss the notification after completion.

```tsx
// Example: progress notification that updates itself
const showProgress = async () => {
  Toast.upsert({ message: 'Starting download...' })

  for (let i = 0; i <= 100; i += 10) {
    await new Promise(resolve => setTimeout(resolve, 100))
    Toast.upsert({ message: `Progress: ${i}%` })
  }

  Toast.end()
}
```

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

### List Open GitHub Issues with JSON Output

Source: https://github.com/desko27/react-call/blob/main/docs/agents/issue-tracker.md

Lists open GitHub issues and formats the output as JSON, including specific fields like number, title, body, labels, and comments. This allows for programmatic processing of issue data.

```bash
gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'
```