jattac.libs.web.overflow-menu 0.0.30 → 0.0.33

package/docs/api.md

@@ -0,0 +1,47 @@
+# API Reference: Technical Blueprint
+
+This document provides exhaustive technical specifications for the Jattac Overflow Menu component and its associated types.
+
+### Table of Contents
+1. [OverflowMenu Component](#overflowmenu-component)
+2. [IOverflowMenuItem Type](#ioverflowmenuitem-type)
+
+[Previous: Features](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/features.md) | [Next: Configuration](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/configuration.md)
+
+---
+
+### OverflowMenu Component
+
+The primary component for rendering the overflow menu.
+
+| Prop | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `items` | `IOverflowMenuItem[]` | Yes | - | An array of objects defining the menu items and their behavior. |
+| `icon` | `React.ReactNode` | No | `<DefaultIcon />` | A custom React node to be used as the menu trigger. |
+| `className` | `string` | No | `''` | A custom CSS class to apply to the trigger button for styling. |
+| `portal` | `HTMLElement` | No | `null` | A reference to a DOM element to render the menu content into using a React Portal. |
+
+### IOverflowMenuItem Type
+
+`IOverflowMenuItem` is a discriminated union that enforces correct property usage for different menu item roles.
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `content` | `React.ReactNode` | Yes | - | The visual content for the menu item. |
+| `onClick` | `() => void` | **See Note** | - | Callback executed when the item is selected. |
+| `children` | `IOverflowMenuItem[]` | **See Note** | - | Optional child items to create a nested submenu. |
+| `visible` | `boolean \| (() => boolean) \| (() => Promise<boolean>)` | No | `true` | Controls the visibility of the item. Supports booleans, sync, and async functions. |
+| `enabled` | `boolean \| (() => boolean) \| (() => Promise<boolean>)` | No | `true` | Controls whether the item is interactive. Supports booleans, sync, and async functions. |
+
+#### Notes on Union Variants
+- **`ActionItem`:** Required `onClick`. Does not accept `children`.
+- **`SubmenuItem`:** Required `children` (minimum 1 item). `onClick` is optional and usually omitted.
+
+#### Notes on Visibility and Enabled State
+- If `visible` resolves to `false`, the item will not be rendered at all.
+- If `enabled` resolves to `false`, the item is rendered as disabled and `onClick` will not be triggered.
+- Async functions are evaluated once when the item is mounted or when their reference changes.
+
+---
+
+[Previous: Features](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/features.md) | [Next: Configuration](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/configuration.md)

package/docs/breaking-changes.md

@@ -0,0 +1,76 @@
+# Upgrade Path: Breaking Changes
+
+This document provides information about major version changes and breaking changes to the Jattac Overflow Menu.
+
+### Table of Contents
+1. [Version 0.0.32](#version-0-0-32)
+2. [Version 0.0.30](#version-0-0-30)
+
+[Previous: Development](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/development.md) | [Next: README](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/README.md)
+
+---
+
+### Version 0.0.32
+
+Version 0.0.32 introduces significant API and architectural enhancements to improve type safety and maintainability.
+
+**Breaking Change: IOverflowMenuItem Union**
+`IOverflowMenuItem` is now a discriminated union. This change enforces that `onClick` is required for action items (items without `children`).
+
+**Before:**
+```tsx
+const items: IOverflowMenuItem[] = [
+  { content: 'Delete' }, // Invalid if children are absent
+];
+```
+
+**After:**
+```tsx
+const items: IOverflowMenuItem[] = [
+  { content: 'Delete', onClick: () => {} }, // Now correctly required
+];
+```
+
+**Feature: Conditional Visibility & Enabled State**
+Added `visible` and `enabled` properties supporting boolean, synchronous, and asynchronous values.
+
+```tsx
+const items: IOverflowMenuItem[] = [
+  {
+    content: 'Export',
+    enabled: async () => await checkExportStatus(),
+    onClick: () => {},
+  },
+];
+```
+
+---
+
+### Version 0.0.30
+
+Version 0.0.30 introduces significant enhancements to the component's internal architecture, including support for multi-level submenus. While the primary API remains consistent, some internal types and styles have changed.
+
+**Before: Flat Items Only**
+```tsx
+const items: IOverflowMenuItem[] = [
+  { content: 'Item 1', onClick: () => {} },
+];
+```
+
+**After: Multi-Level Support**
+```tsx
+const items: IOverflowMenuItem[] = [
+  {
+    content: 'Item 1',
+    children: [
+      { content: 'Child Item', onClick: () => {} },
+    ],
+  },
+];
+```
+
+For detailed implementation information, refer to the [Multi-Level Child Menus recipe](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/examples.md#multi-level-child-menus) in the Cookbook.
+
+---
+
+[Previous: Development](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/development.md) | [Next: README](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/README.md)

package/docs/configuration.md

@@ -0,0 +1,48 @@
+# Configuration: The Control Panel
+
+The Jattac Overflow Menu is designed to be easily customized. This document outlines the available configuration and styling options.
+
+### Table of Contents
+1. [Styling and Customization](#styling-and-customization)
+2. [Advanced Styling with Data Attributes](#advanced-styling-with-data-attributes)
+3. [Portal Usage and Z-Index](#portal-usage-and-z-index)
+
+[Previous: API Reference](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/api.md) | [Next: Development](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/development.md)
+
+---
+
+### Styling and Customization
+
+The component uses CSS Modules internally, but its styles can be overridden using standard CSS selectors. The primary classes used are:
+- `.jattac-overflow-menu-content`: The container for the menu items.
+- `.jattac-overflow-menu-item`: Individual menu items.
+- `.jattac-overflow-menu-trigger`: The trigger button for the menu.
+
+### Advanced Styling with Data Attributes
+
+The underlying Radix UI components expose data attributes that can be used to target specific states of the menu:
+- `[data-state="open"]`: Applied to the trigger when the menu is visible.
+- `[data-state="closed"]`: Applied to the trigger when the menu is hidden.
+- `[data-highlighted]`: Applied to a menu item when it is being hovered or navigated via keyboard.
+
+**Example: Customizing a Highlighted Item**
+```css
+/* In your application's global CSS file */
+.jattac-overflow-menu-item[data-highlighted] {
+  background-color: #f0f0f0;
+  color: #333;
+}
+```
+
+### Portal Usage and Z-Index
+
+The `portal` prop is used to render the menu content into a specific DOM element. This is essential for layouts where:
+- A parent container has `overflow: hidden` or `overflow: scroll`.
+- The menu is nested within a complex stacking context (e.g., a modal inside a table).
+- You need to explicitly manage the z-index of the menu content relative to other components in your application.
+
+For implementation details, refer to the [Using a Portal recipe](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/examples.md#using-a-portal-for-complex-layouts).
+
+---
+
+[Previous: API Reference](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/api.md) | [Next: Development](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/development.md)

package/docs/development.md

@@ -0,0 +1,52 @@
+# Development Guide: Contributing to Jattac Overflow Menu
+
+Thank you for your interest in contributing to the Jattac Overflow Menu. This document provides instructions for setting up your local environment and understanding the project's internal structure.
+
+### Table of Contents
+1. [Local Setup](#local-setup)
+2. [Internal Architecture](#internal-architecture)
+3. [Available Scripts](#available-scripts)
+4. [Testing and Quality Assurance](#testing-and-quality-assurance)
+
+[Previous: Configuration](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/configuration.md) | [Next: Breaking Changes](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/breaking-changes.md)
+
+---
+
+### Local Setup
+
+To get started with local development, ensure you have Node.js and npm installed.
+1. Clone the repository.
+2. Install dependencies by running `npm install`.
+3. To start the development build in watch mode, run `npm run watch`.
+
+### Internal Architecture
+
+The project is structured to maintain a clean separation of concerns:
+- `src/Data`: Contains core types, including the `IOverflowMenuItem` discriminated union.
+- `src/Styles`: Contains CSS Modules for encapsulated styling.
+- `src/Utils`: Includes helper utilities, such as `Evaluate.ts` for handling sync/async properties.
+- `src/UI`: Contains modular components:
+  - `Animations.ts`: Centralized Framer Motion variants.
+  - `DefaultIcon.tsx`: The default animated trigger icon.
+  - `MenuRow.tsx`: Logic for individual menu rows and submenus.
+  - `OverflowMenu.tsx`: The root component and coordinator.
+- `test-app/`: A standard React environment for manual testing.
+- `test-app2/`: A Next.js (App Router) environment for cross-framework verification.
+
+### Available Scripts
+
+- `npm run build`: Compiles the library using Rollup into ESM and CommonJS formats.
+- `npm run watch`: Compiles the library in watch mode for a faster development cycle.
+- `npm run lint`: Executes ESLint to ensure code quality and style consistency.
+- `npm run size`: Analyzes the bundle size to maintain a lightweight footprint.
+
+### Testing and Quality Assurance
+
+Before submitting a pull request, please ensure that:
+- The project builds without errors (`npm run build`).
+- No linting issues are present (`npm run lint`).
+- The component is manually verified in both `test-app` and `test-app2` to ensure cross-framework compatibility.
+
+---
+
+[Previous: Configuration](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/configuration.md) | [Next: Breaking Changes](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/breaking-changes.md)

package/docs/examples.md

@@ -0,0 +1,213 @@
+# Cookbook: Practical Examples
+
+The Jattac Overflow Menu is designed to be highly flexible. This cookbook provides practical, copy-paste recipes for common scenarios, ranging from simple action lists to complex nested menus.
+
+### Table of Contents
+1. [Simple Action Menu](#simple-action-menu)
+2. [Custom Trigger Icon](#custom-trigger-icon)
+3. [Rich Content Items](#rich-content-items)
+4. [Multi-Level Child Menus](#multi-level-child-menus)
+5. [Conditional Visibility](#conditional-visibility)
+6. [Enabled Toggling](#enabled-toggling)
+7. [Using a Portal for Complex Layouts](#using-a-portal-for-complex-layouts)
+
+[Previous: README](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/README.md) | [Next: Features](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/features.md)
+
+---
+
+### Simple Action Menu
+
+The most common use case is a flat list of actions. This recipe shows the minimum configuration required to implement a standard overflow menu.
+
+```tsx
+import React from 'react';
+import OverflowMenu, { IOverflowMenuItem } from 'jattac.libs.web.overflow-menu';
+
+const items: IOverflowMenuItem[] = [
+  { content: 'Edit', onClick: () => console.log('Edit clicked') },
+  { content: 'Delete', onClick: () => console.log('Delete clicked') },
+];
+
+const MyComponent = () => (
+  <OverflowMenu items={items} />
+);
+```
+
+### Custom Trigger Icon
+
+You can override the default animated "three dots" icon with any React node. This is useful for integrating with icon libraries like `react-icons` or `lucide-react`.
+
+```tsx
+import React from 'react';
+import { FiSettings } from 'react-icons/fi';
+import OverflowMenu, { IOverflowMenuItem } from 'jattac.libs.web.overflow-menu';
+
+const items: IOverflowMenuItem[] = [
+  { content: 'Profile', onClick: () => {} },
+  { content: 'Security', onClick: () => {} },
+];
+
+const MyComponent = () => (
+  <OverflowMenu items={items} icon={<FiSettings size={20} />} />
+);
+```
+
+### Rich Content Items
+
+The `content` property of each menu item can be a complex React node. This allows for items with icons, badges, or specialized typography.
+
+```tsx
+import React from 'react';
+import { FiEdit2, FiTrash2 } from 'react-icons/fi';
+import OverflowMenu, { IOverflowMenuItem } from 'jattac.libs.web.overflow-menu';
+
+const items: IOverflowMenuItem[] = [
+  {
+    content: (
+      <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+        <FiEdit2 /> <span>Edit Entry</span>
+      </div>
+    ),
+    onClick: () => {},
+  },
+  {
+    content: (
+      <div style={{ display: 'flex', alignItems: 'center', gap: '8px', color: 'red' }}>
+        <FiTrash2 /> <span>Delete Entry</span>
+      </div>
+    ),
+    onClick: () => {},
+  },
+];
+
+const MyComponent = () => (
+  <OverflowMenu items={items} />
+);
+```
+
+### Multi-Level Child Menus
+
+Support for nested menus is built-in. Simply add a `children` array to any item. The component will recursively render submenus with consistent styling and animations.
+
+```tsx
+import React from 'react';
+import OverflowMenu, { IOverflowMenuItem } from 'jattac.libs.web.overflow-menu';
+
+const items: IOverflowMenuItem[] = [
+  {
+    content: 'Share',
+    children: [
+      { content: 'Email', onClick: () => {} },
+      { content: 'Message', onClick: () => {} },
+      {
+        content: 'Social Media',
+        children: [
+          { content: 'Twitter', onClick: () => {} },
+          { content: 'Facebook', onClick: () => {} },
+        ],
+      },
+    ],
+  },
+  { content: 'Download', onClick: () => {} },
+];
+
+const MyComponent = () => (
+  <OverflowMenu items={items} />
+);
+```
+
+### Conditional Visibility
+
+Control the visibility of menu items using booleans, synchronous functions, or asynchronous functions. This is ideal for role-based access control or state-dependent actions.
+
+```tsx
+import React from 'react';
+import OverflowMenu, { IOverflowMenuItem } from 'jattac.libs.web.overflow-menu';
+
+const items: IOverflowMenuItem[] = [
+  {
+    content: 'Admin Panel',
+    visible: false, // Statically hidden
+    onClick: () => {},
+  },
+  {
+    content: 'User Settings',
+    visible: () => localStorage.getItem('user') !== null, // Synchronous check
+    onClick: () => {},
+  },
+  {
+    content: 'Delete Project',
+    visible: async () => {
+      const response = await fetch('/api/check-permissions');
+      return response.ok; // Asynchronous check
+    },
+    onClick: () => {},
+  },
+];
+
+const MyComponent = () => <OverflowMenu items={items} />;
+```
+
+### Enabled Toggling
+
+Similar to visibility, you can disable items while keeping them visible. Disabled items are non-interactive and styled appropriately to indicate their state.
+
+```tsx
+import React from 'react';
+import OverflowMenu, { IOverflowMenuItem } from 'jattac.libs.web.overflow-menu';
+
+const items: IOverflowMenuItem[] = [
+  {
+    content: 'Quick Save',
+    enabled: true,
+    onClick: () => {},
+  },
+  {
+    content: 'Export Data',
+    enabled: () => isDataDirty, // Synchronous check
+    onClick: () => {},
+  },
+  {
+    content: 'Finalize Deployment',
+    enabled: async () => {
+      const status = await getBuildStatus();
+      return status === 'ready'; // Asynchronous check
+    },
+    onClick: () => {},
+  },
+];
+
+const MyComponent = () => <OverflowMenu items={items} />;
+```
+
+### Using a Portal for Complex Layouts
+
+When a menu is rendered inside a container with `overflow: hidden` or restricted z-indexing (e.g., a table cell or a modal), use the `portal` prop to render the menu outside the parent's stacking context.
+
+```tsx
+import React, { useRef } from 'react';
+import OverflowMenu, { IOverflowMenuItem } from 'jattac.libs.web.overflow-menu';
+
+const App = () => {
+  const portalRef = useRef<HTMLDivElement>(null);
+  
+  const items: IOverflowMenuItem[] = [
+    { content: 'Action 1', onClick: () => {} },
+  ];
+
+  return (
+    <div style={{ position: 'relative' }}>
+      <div style={{ overflow: 'hidden', height: '100px' }}>
+        <OverflowMenu items={items} portal={portalRef.current} />
+      </div>
+      
+      {/* The menu will be rendered here, outside the hidden container */}
+      <div ref={portalRef} id="menu-portal" />
+    </div>
+  );
+};
+```
+
+---
+
+[Previous: README](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/README.md) | [Next: Features](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/features.md)

package/docs/features.md

@@ -0,0 +1,62 @@
+# Showcase: Feature Overview
+
+The Jattac Overflow Menu offers a powerful set of features designed to simplify the management of secondary actions while providing a premium user experience.
+
+### Table of Contents
+1. [Full Accessibility](#full-accessibility)
+2. [Multi-Level Submenus](#multi-level-submenus)
+3. [Conditional Visibility and Enabled Toggling](#conditional-visibility-and-enabled-toggling)
+4. [Advanced Animations](#advanced-animations)
+5. [Atomic & Maintainable Architecture](#atomic-maintainable-architecture)
+6. [Modern Frosted-Glass Aesthetic](#modern-frosted-glass-aesthetic)
+7. [Flexible Trigger Icons](#flexible-trigger-icons)
+
+[Previous: Cookbook](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/examples.md) | [Next: API Reference](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/api.md)
+
+---
+
+### Full Accessibility
+
+The component is built on top of Radix UI primitives, ensuring that it is fully accessible to all users. It adheres to the WAI-ARIA Menu Button pattern, providing:
+- Full keyboard navigation (arrow keys, Enter, Space, Escape, Tab).
+- Focus management to ensure proper tab order.
+- ARIA attributes that automatically communicate the state of the menu to assistive technologies.
+
+For implementation details, refer to the [Simple Action Menu recipe](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/examples.md#simple-action-menu).
+
+### Multi-Level Submenus
+
+Organize complex sets of actions with ease using recursive submenus. The library handles the logic for positioning, timing, and keyboard navigation for nested menus, ensuring a smooth experience regardless of depth.
+
+For implementation details, refer to the [Multi-Level Child Menus recipe](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/examples.md#multi-level-child-menus).
+
+### Conditional Visibility and Enabled Toggling
+
+Dynamically control whether actions are visible or interactive. These properties support boolean values, synchronous functions, and asynchronous functions (Promises). This allows for complex logic, such as checking permissions from an API or verifying state before enabling an action.
+
+For implementation details, refer to the [Conditional Visibility recipe](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/examples.md#conditional-visibility).
+
+### Advanced Animations
+
+Powered by Framer Motion, every interaction feels deliberate and responsive. The trigger features spring-based hover effects, and the menu items use staggered entry animations to guide the user's eye.
+
+### Atomic & Maintainable Architecture
+
+The library is designed for enterprise-grade maintainability. The core component has been refactored into atomic, single-responsibility modules, including:
+- **`Evaluate` Utility:** Centralized logic for boolean/sync/async property evaluation.
+- **Animation Hub:** Consolidated Framer Motion variants for consistency.
+- **Isolated UI Components:** Modularized `DefaultIcon` and `MenuRow` for easier testing and extension.
+
+### Modern Frosted-Glass Aesthetic
+
+Out of the box, the component features a "glassmorphism" design, including backdrop blur and a subtle translucent background. This allows it to blend seamlessly into modern, high-quality user interfaces without extensive customization.
+
+### Flexible Trigger Icons
+
+The default "three dots" icon is animated and interactive. However, the component supports any React node as a custom trigger, making it easy to adapt to your application's specific iconography.
+
+For implementation details, refer to the [Custom Trigger Icon recipe](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/examples.md#custom-trigger-icon).
+
+---
+
+[Previous: Cookbook](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/examples.md) | [Next: API Reference](https://github.com/nyingimaina/jattac.libs.web.overflow-menu/blob/develop/docs/api.md)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jattac.libs.web.overflow-menu",
-  "version": "0.0.30",
-  "description": "A customizable and lightweight React overflow menu component with a modern design.",
+  "version": "0.0.33",
+  "description": "Enterprise-grade, accessible, and highly customizable React overflow menu component. Built on Radix UI and Framer Motion for premium UX and full WAI-ARIA compliance.",
   "main": "dist/index.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",
@@ -16,29 +16,57 @@
       "require": "./dist/index.css"
     }
   },
+  "sideEffects": [
+    "*.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nyingimaina/jattac.libs.web.overflow-menu.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nyingimaina/jattac.libs.web.overflow-menu/issues"
+  },
+  "homepage": "https://github.com/nyingimaina/jattac.libs.web.overflow-menu#readme",
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=8.0.0"
+  },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "scripts": {
     "build": "rollup -c",
     "watch": "rollup -c -w",
     "lint": "eslint \"./{src,app}/**/*.{ts,tsx}\"",
+    "lint:fix": "eslint \"./{src,app}/**/*.{ts,tsx}\" --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,css,md}\"",
+    "type-check": "tsc --noEmit",
     "size": "size-limit",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run lint && npm run type-check && npm run build"
   },
   "keywords": [
     "react",
     "typescript",
     "menu",
     "overflow-menu",
-    "component"
+    "dropdown",
+    "context-menu",
+    "accessible",
+    "radix-ui",
+    "framer-motion",
+    "ui-component",
+    "enterprise",
+    "nested-menu",
+    "submenu"
   ],
   "author": "Nyingi Maina",
   "license": "MIT",
   "peerDependencies": {
+    "framer-motion": ">=11.0.0",
     "react": ">=18.2.0",
-    "react-dom": ">=18.2.0",
-    "framer-motion": ">=11.0.0"
+    "react-dom": ">=18.2.0"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.7",