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

npm install @warkypublic/oranguru

Peer Dependencies

This package requires the following peer dependencies:

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.2" use-sync-external-store@">= 1.4.0"

Usage

Basic Setup

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

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

Using the Menu Hook

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

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:

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

MantineBetterMenuInstanceItem

Interface for menu items:

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 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