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

Components

MantineBetterMenu

Enhanced context menus with better positioning and visibility control

Gridler

Powerful data grid component with sorting, filtering, and pagination

Former

Form component with React Hook Form integration and validation

FormerControllers

Pre-built form input controls for use with Former

Boxer

Advanced combobox/select with virtualization and server-side data support

ErrorBoundary

React error boundary components for graceful error handling

GlobalStateStore

Zustand-based global state management with automatic persistence

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

Usage

MantineBetterMenu

import { MantineBetterMenusProvider, useMantineBetterMenus } from '@warkypublic/oranguru';

// Wrap app with provider
<MantineBetterMenusProvider>
  <App />
</MantineBetterMenusProvider>

// Use in components
const { show, hide } = useMantineBetterMenus();
show('menu-id', {
  x: e.clientX,
  y: e.clientY,
  items: [
    { label: 'Edit', onClick: () => {} },
    { isDivider: true },
    { label: 'Async', onClickAsync: async () => {} }
  ]
});

Gridler

import { Gridler } from '@warkypublic/oranguru';

// Local data
<Gridler columns={columns} uniqueid="my-grid">
  <Gridler.LocalDataAdaptor data={data} />
</Gridler>

// API data
<Gridler columns={columns} uniqueid="my-grid">
  <Gridler.APIAdaptorForGoLangv2 apiURL="/api/data" />
</Gridler>

// With inline editing form
<Gridler columns={columns} uniqueid="editable-grid" ref={gridRef}>
  <Gridler.APIAdaptorForGoLangv2 url="/api/data" />
  <Gridler.FormAdaptor
    changeOnActiveClick={true}
    descriptionField="name"
    onRequestForm={(request, data) => {
      setFormProps({ opened: true, request, values: data });
    }}
  />
</Gridler>

<FormerDialog
  former={{ request: formProps.request, values: formProps.values }}
  opened={formProps.opened}
  onClose={() => setFormProps({ opened: false })}
>
  <TextInputCtrl label="Name" name="name" />
  <NativeSelectCtrl label="Type" name="type" data={["A", "B"]} />
</FormerDialog>

// Columns definition
const columns = [
  { id: 'name', title: 'Name', width: 200 },
  { id: 'email', title: 'Email', width: 250 }
];

Former

import { Former, FormerDialog } from '@warkypublic/oranguru';

const formRef = useRef<FormerRef>(null);

<Former
  ref={formRef}
  onSave={async (data) => { /* save logic */ }}
  primeData={{ name: '', email: '' }}
  wrapper={FormerDialog}
>
  {/* Form content */}
</Former>

// Methods: formRef.current.show(), .save(), .reset()

FormerControllers

import {
  TextInputCtrl,
  PasswordInputCtrl,
  NativeSelectCtrl,
  TextAreaCtrl,
  SwitchCtrl,
  ButtonCtrl
} from '@warkypublic/oranguru';

<Former>
  <TextInputCtrl name="username" label="Username" />
  <PasswordInputCtrl name="password" label="Password" />
  <NativeSelectCtrl name="role" data={['Admin', 'User']} />
  <SwitchCtrl name="active" label="Active" />
  <ButtonCtrl type="submit">Save</ButtonCtrl>
</Former>

Boxer

import { Boxer } from '@warkypublic/oranguru';

// Local data
<Boxer
  data={[{ label: 'Apple', value: 'apple' }]}
  dataSource="local"
  value={value}
  onChange={setValue}
  searchable
  clearable
/>

// Server-side data
<Boxer
  dataSource="server"
  onAPICall={async ({ page, pageSize, search }) => ({
    data: [...],
    total: 100
  })}
  value={value}
  onChange={setValue}
/>

// Multi-select
<Boxer multiSelect value={values} onChange={setValues} />

ErrorBoundary

import { ReactErrorBoundary, ReactBasicErrorBoundary } from '@warkypublic/oranguru';

// Full-featured error boundary
<ReactErrorBoundary
  namespace="my-component"
  reportAPI="/api/errors"
  onResetClick={() => {}}
>
  <App />
</ReactErrorBoundary>

// Basic error boundary
<ReactBasicErrorBoundary>
  <App />
</ReactBasicErrorBoundary>

GlobalStateStore

import {
  GlobalStateStoreProvider,
  useGlobalStateStore,
  GlobalStateStore
} from '@warkypublic/oranguru';

// Wrap app
<GlobalStateStoreProvider
  apiURL="https://api.example.com"
  fetchOnMount={true}
  throttleMs={5000}
>
  <App />
</GlobalStateStoreProvider>

// Use in components
const { program, session, user, layout } = useGlobalStateStore();
const { refetch } = useGlobalStateStoreContext();

// Outside React
GlobalStateStore.getState().setAuthToken('token');
const apiURL = GlobalStateStore.getState().session.apiURL;

API Reference

MantineBetterMenu

• Provider: MantineBetterMenusProvider
• Hook: useMantineBetterMenus() returns { show, hide, menus, setInstanceState }
• Key Props: items[], x, y, visible, menuProps, renderer

Gridler

• Main Component: Gridler
• Adaptors: LocalDataAdaptor, APIAdaptorForGoLangv2, FormAdaptor
• Store Hook: useGridlerStore()
• Key Props: uniqueid, columns[], data

Former

• Main Component: Former
• Wrappers: FormerDialog, FormerModel, FormerPopover
• Ref Methods: show(), close(), save(), reset(), validate()
• Key Props: primeData, onSave, wrapper

FormerControllers

• Controls: TextInputCtrl, PasswordInputCtrl, TextAreaCtrl, NativeSelectCtrl, SwitchCtrl, ButtonCtrl, IconButtonCtrl
• Common Props: name (required), label, disabled

Boxer

• Provider: BoxerProvider
• Store Hook: useBoxerStore()
• Data Sources: local, server
• Key Props: data, dataSource, onAPICall, multiSelect, searchable, clearable

ErrorBoundary

• Components: ReactErrorBoundary, ReactBasicErrorBoundary
• Key Props: namespace, reportAPI, onResetClick, onRetryClick

GlobalStateStore

• Provider: GlobalStateStoreProvider
• Hook: useGlobalStateStore() returns { program, session, owner, user, layout, navigation, app }
• Store Methods: setAuthToken(), setApiURL(), fetchData(), login(), logout()
• Key Props: apiURL, autoFetch, fetchOnMount, throttleMs

MCP Server

Oranguru includes a Model Context Protocol (MCP) server for AI-assisted development.

Configuration:

Add to ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "oranguru-docs": {
      "command": "npx",
      "args": ["-y", "@warkypublic/oranguru", "mcp"]
    }
  }
}

Tools:

• list_components - List all components
• get_component_docs - Get component documentation
• get_component_example - Get code examples

Resources:

• oranguru://docs/readme - Full documentation
• oranguru://docs/components - Component list

See mcp/README.md for details.

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
• pnpm mcp: Run MCP server

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