@bemedev/app-solid/README.md

Middleware between @bemedev/app-ts and solidjs

# @bemedev/app-solid

<br/>

A TypeScript middleware for integrating `@bemedev/app-ts` finite state
machines with SolidJS.

<br/>

## Description

This library serves as a bridge between `@bemedev/app-ts` (finite state
machine library) and SolidJS, enabling the use of reactive state machines
in SolidJS applications.

<br/>

## Key Features

- 🔗 **SolidJS Integration**: Connects `@bemedev/app-ts` state machines
  with SolidJS signals
- ⚡ **Reactivity**: Automatic synchronization between machine state and
  SolidJS components
- 🎯 **TypeScript Types**: Preserves type safety between both libraries
- 🔄 **Transparent Middleware**: Simple interface for using state machines
  in SolidJS

<br/>

## Installation

### npm

```bash
npm install @bemedev/app-solid @bemedev/app-ts solid-js
```

### pnpm

```bash
pnpm install @bemedev/app-solid @bemedev/app-ts solid-js
```

<br/>

## Usage

### Basic Example

```typescript
import { createInterpreter } from '@bemedev/app-solid';
import { createMachine } from '@bemedev/app-ts';

// Define your state machine
const toggleMachine = createMachine({
  initial: 'inactive',
  states: {
    inactive: {
      on: { TOGGLE: '/active' }
    },
    active: {
      on: { TOGGLE: '/inactive' }
    }
  }
});

// Create an interpreter
const interpreter = createInterpreter({
  machine: toggleMachine,
  options: {
    context: {},
    pContext: {}
  }
});

// Start the interpreter
interpreter.start();

// In your SolidJS component
function MyComponent() {
  const value = interpreter.value();
  const currentState = value();

  return (
    <div>
      <p>Current state: {currentState}</p>
      <button onClick={() => interpreter.send('TOGGLE')}>
        Toggle
      </button>
    </div>
  );
}
```

### Runtime Options Override

You can override machine options at runtime using `provideOptions`:

```typescript
const interpreter = createInterpreter({
  machine: myMachine,
  options: {
    context: { count: 0 },
    pContext: {},
  },
}).provideOptions(({ assign }) => ({
  actions: {
    increment: assign(
      'context.count',
      ({ context: { count } }) => count + 2,
    ),
  },
}));
```

### State Matching & Tags

```typescript
// Check if current state matches
const isActive = interpreter.matches('active');

// Check if state contains a value
const hasWorking = interpreter.contains('working');

// Check for tags
const hasTags = interpreter.hasTags('loading', 'visible');
```

### UI Thread (External State Management)

You can add UI state that exists outside the machine's internal state using
`uiThread`. This is useful for managing UI-specific state (like form
inputs, loading indicators, etc.) that needs to be reactive but shouldn't
be part of the machine's state logic. Generally, it's a problem of speed.

```typescript
import { createSignal } from 'solid-js';

// Define UI signals outside the machine
const [username, setUsername] = createSignal('');
const [email, setEmail] = createSignal('');

const interpreter = createInterpreter({
  machine: myMachine,
  options: {
    context: {},
    pContext: {}
  },
  uiThread: {
    username: [username, setUsername],
    email: [email, setEmail]
  }
});

// Access UI state in components
function MyComponent() {
  const ui = interpreter.ui();
  const currentUsername = ui()?.username;

  return (
    <div>
      <input
        value={currentUsername || ''}
        onInput={(e) => interpreter.sendUI({
          type: 'username',
          payload: e.currentTarget.value
        })}
      />
    </div>
  );
}
```

**Key points:**

- UI thread state is **separate** from the machine's internal context
- Perfect for form inputs, UI toggles, and temporary UI state
- Very fast for efficent UI updates, avoiding unnecessary machine state
  transitions
- Reactive through SolidJS signals
- Accessible via `interpreter.ui()` and `interpreter.sendUI()`

<br/>

## Licence

MIT

## CHANGE_LOG

<details>

<summary>
...
</summary>

[CHANGELOG](https://github.com/chlbri/app-solid/blob/main/CHANGE_LOG.md)

</details>

<br/>

## Auteur

chlbri (bri_lvi@icloud.com)

[My github](https://github.com/chlbri?tab=repositories)

[<svg width="98" height="96" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#24292f"/></svg>](https://github.com/chlbri?tab=repositories)

<br/>

## Liens

- [Documentation](https://github.com/chlbri/new-package)