oranguru/README.md

# @warkypublic/oranguru

A React component library providing enhanced Mantine-based components with advanced features and state management capabilities.

## Overview

Oranguru is a comprehensive component library that extends Mantine's component ecosystem. Named after the wise Orangutan Pokémon known for its intelligence and strategic thinking, this library provides enhanced components with advanced positioning, custom rendering, and sophisticated state management capabilities.

Currently featuring advanced menu components, Oranguru is designed to grow into a full suite of enhanced Mantine components that offer more flexibility and power than their standard counterparts.

## Features

### Current Components
- **Enhanced Context Menus**: Better menu positioning and visibility control
- **Custom Rendering**: Support for custom menu item renderers and complete menu rendering
- **Async Actions**: Built-in support for async menu item actions with loading states

### Core Features
- **State Management**: Zustand-based store for component state management
- **TypeScript Support**: Full TypeScript definitions included
- **Portal-based Rendering**: Proper z-index handling through React portals
- **Extensible Architecture**: Designed to support additional Mantine component enhancements

## Installation

```bash
npm install @warkypublic/oranguru
```

### Peer Dependencies

This package requires the following peer dependencies:

```bash
npm install react@">= 19.0.0" zustand@">= 5.0.0" @mantine/core@"^8.3.1" @mantine/hooks@"^8.3.1" @warkypublic/artemis-kit@"^1.0.10" @warkypublic/zustandsyncstore@"^0.0.4" use-sync-external-store@">= 1.4.0"
```

## Usage

### Basic Setup

```tsx
import { MantineBetterMenusProvider } from '@warkypublic/oranguru';
import { MantineProvider } from '@mantine/core';

function App() {
  return (
    <MantineProvider>
      <MantineBetterMenusProvider>
        {/* Your app content */}
      </MantineBetterMenusProvider>
    </MantineProvider>
  );
}
```

### Using the Menu Hook

```tsx
import { useMantineBetterMenus } from '@warkypublic/oranguru';

function MyComponent() {
  const { show, hide } = useMantineBetterMenus();
  
  const handleContextMenu = (e: React.MouseEvent) => {
    e.preventDefault();
    show('my-menu', {
      x: e.clientX,
      y: e.clientY,
      items: [
        {
          label: 'Edit',
          onClick: () => console.log('Edit clicked')
        },
        {
          label: 'Delete',
          onClick: () => console.log('Delete clicked')
        },
        {
          isDivider: true
        },
        {
          label: 'Async Action',
          onClickAsync: async () => {
            await new Promise(resolve => setTimeout(resolve, 2000));
            console.log('Async action completed');
          }
        }
      ]
    });
  };

  return (
    <div onContextMenu={handleContextMenu}>
      Right-click me for a context menu
    </div>
  );
}
```

### Custom Menu Items

```tsx
const customMenuItem = {
  renderer: ({ loading }: any) => (
    <div style={{ padding: '8px 12px' }}>
      {loading ? 'Loading...' : 'Custom Item'}
    </div>
  )
};

show('custom-menu', {
  x: e.clientX,
  y: e.clientY,
  items: [customMenuItem]
});
```

## API Reference

### MantineBetterMenusProvider

The main provider component that wraps your application.

**Props:**
- `providerID?`: Optional unique identifier for the provider instance

### useMantineBetterMenus

Hook to access menu functionality.

**Returns:**
- `show(id: string, options?: Partial<MantineBetterMenuInstance>)`: Show a menu
- `hide(id: string)`: Hide a menu
- `menus`: Array of current menu instances
- `setInstanceState`: Update specific menu instance properties

### MantineBetterMenuInstance

Interface for menu instances:

```typescript
interface MantineBetterMenuInstance {
  id: string;
  items?: Array<MantineBetterMenuInstanceItem>;
  menuProps?: MenuProps;
  renderer?: ReactNode;
  visible: boolean;
  x: number;
  y: number;
}
```

### MantineBetterMenuInstanceItem

Interface for menu items:

```typescript
interface MantineBetterMenuInstanceItem extends Partial<MenuItemProps> {
  isDivider?: boolean;
  label?: string;
  onClick?: (e?: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
  onClickAsync?: () => Promise<void>;
  renderer?: ((props: MantineBetterMenuInstanceItem & Record<string, unknown>) => ReactNode) | ReactNode;
}
```

## Development

### Scripts

- `pnpm dev`: Start development server
- `pnpm build`: Build the library
- `pnpm lint`: Run ESLint
- `pnpm typecheck`: Run TypeScript type checking
- `pnpm clean`: Clean node_modules and dist folders

### Building

The library is built using Vite and outputs both ESM and CommonJS formats:

- ESM: `dist/lib.es.js`
- CommonJS: `dist/lib.cjs.js`
- Types: `dist/lib.d.ts`

## License

See [LICENSE](LICENSE) file for details.

## About the Name

Oranguru is named after the Orangutan Pokémon (オランガ Oranga), a Normal/Psychic-type Pokémon introduced in Generation VII. Known as the "Sage Pokémon," Oranguru is characterized by its wisdom, intelligence, and ability to use tools strategically. 

In the Pokémon world, Oranguru is known for:
- Its exceptional intelligence and strategic thinking
- Living deep in forests and rarely showing itself to humans
- Using its psychic powers to control other Pokémon with its fan
- Being highly territorial but also caring for other Pokémon in its domain

Just as Oranguru the Pokémon enhances and controls its environment with wisdom and strategic tools, this library aims to enhance and extend Mantine components with intelligent, well-designed solutions.

## Author

**Warky Devs**