@corrbo/comp-with-methods/README.md

Create React components with imperative methods and multi-instance support

# `compWithMethods` Library Documentation

## Introduction

`compWithMethods` is a powerful React component wrapper that enables:

- Creating components with external methods
- Managing multiple component instances
- Maintaining clean code and TypeScript type safety

## Installation

```bash
npm install @corrbo/comp-with-methods
# or
yarn add @corrbo/comp-with-methods
```

## Basic Usage

### 1. Creating a Component

```tsx
import {compWithMethods} from '@corrbo/comp-with-methods';

const MyComponent = compWithMethods({
  adapter: useMyAdapter,
  UI: ({adapter}) => <View>{adapter.variables.text}</View>
});
```

### 2. Using the Component

```tsx
<MyComponent/>
```

### 3. Calling Methods

```tsx
MyComponent.someMethod(params);
```

## Advanced Usage

### Working with Multiple Instances

```tsx
// Creating named instances
<MyComponent instanceKey="first"/>
<MyComponent instanceKey="second"/>

// Calling methods for specific instances
MyComponent['first'].someMethod(params);
MyComponent['second'].someMethod(params);

// Calling method for last created unnamed instance
MyComponent.someMethod(params);
```

## Complete Example

```tsx
import React from 'react';
import {View, Text, Button} from 'react-native';
import {compWithMethods} from '@corrbo/comp-with-methods';

// 1. Create adapter
const usePopupAdapter = () => {
  const [isVisible, setIsVisible] = React.useState(false);
  const [message, setMessage] = React.useState('');
  
  return {
    handlers: {
      show: (msg: string) => {
        setMessage(msg);
        setIsVisible(true);
      },
      hide: () => setIsVisible(false),
    },
    variables: {
      isVisible,
      message,
    },
  };
};

// 2. Define method types
interface IPopupMethods {
  show(message: string): void;
  
  hide(): void;
}

// 3. Create component
const Popup = compWithMethods<ReturnType<typeof usePopupAdapter>, IPopupMethods>({
  adapter: usePopupAdapter,
  UI: ({adapter}) => (
    adapter.variables.isVisible && (
      <View style={styles.popup}>
        <Text>{adapter.variables.message}</Text>
      </View>
    )
  ),
});

// 4. Use component
const App = () => {
  return (
    <View>
      <Popup instanceKey="topPopup"/>
      <Popup instanceKey="bottomPopup"/>
      <Popup/>
      
      <Button
        title="Show Top Popup"
        onPress={() => Popup['topPopup'].show('Hello from top!')}
      />
      
      <Button
        title="Show Bottom Popup"
        onPress={() => Popup['bottomPopup'].show('Hello from bottom!')}
      />
      
      <Button
        title="Show Default Popup"
        onPress={() => Popup.show('Hello from default!')}
      />
    </View>
  );
};
```

## API Reference

### `compWithMethods<AdapterRes, ComponentRef, UIProps>(config)`

#### Parameters

- `config` (object):
    - `adapter: () => AdapterRes` - function returning object with:
        - `handlers`: component methods
        - `variables`: component state
    - `UI: (props: UIProps & { adapter: AdapterRes }) => ReactNode` - render function

#### Return Value

React component with added methods from the adapter.

## Best Practices

1. **Typing**: Always define an interface for component methods
2. **Naming**: Use meaningful keys for instanceKey
3. **Cleanup**: Component automatically cleans up refs on unmount
4. **State**: Each instance maintains independent state

## Limitations

1. Component methods aren't available before mounting
2. Multiple instances require instanceKey specification

## Use Cases

### Modals

```tsx
// Creation
<Modal instanceKey="loginModal"/>
<Modal instanceKey="registerModal"/>

// Usage
Modal['loginModal'].open();
Modal['registerModal'].open();
```

### Notifications

```tsx
// Creation
<Notification instanceKey="topNotification"/>
<Notification instanceKey="bottomNotification"/>

// Usage
Notification['topNotification'].show('New message!');
```

### Forms

```tsx
// Creation
<Form instanceKey="userForm"/>

// Usage
Form['userForm'].submit();
Form['userForm'].reset();
```

## Conclusion

`compWithMethods` provides a powerful and type-safe way to create components with methods, especially useful for:

- Modals
- Notifications
- Forms
- Any components that need external control