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

package/docs/api.md

@@ -0,0 +1,40 @@
+# 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 Interface](#ioverflowmenuitem-interface)
+
+[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 Interface
+
+The interface defining the structure of each item in the `items` array.
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `content` | `React.ReactNode` | Yes | - | The visual content to be displayed for the menu item. |
+| `onClick` | `() => void` | No | - | A callback function to execute when the menu item is selected. |
+| `children` | `IOverflowMenuItem[]` | No | - | An optional array of child items to create a nested submenu. |
+
+#### Notes on Type Behavior
+- If `children` is provided and contains at least one item, the menu item will render as a `SubmenuTrigger` rather than a standard `MenuItem`.
+- When an item has `children`, its `onClick` handler is ignored in favor of opening the submenu.
+
+---
+
+[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,39 @@
+# 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.30 (Upcoming)](#version-0-0-30-upcoming)
+
+[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.30 (Upcoming)
+
+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,47 @@
+# 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 between data, styles, and UI components:
+- `src/Data`: Contains TypeScript interfaces and types, such as `IOverflowMenuItem`.
+- `src/Styles`: Contains CSS Modules for component styling.
+- `src/UI`: Contains the core React components, including `OverflowMenu.tsx`.
+- `test-app/`: A standalone React environment for manual testing and component verification.
+- `test-app2/`: A Next.js (App Router) environment for verifying compatibility with modern frameworks.
+
+### 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,147 @@
+# 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. [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} />
+);
+```
+
+### 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,47 @@
+# 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. [Advanced Animations](#advanced-animations)
+4. [Modern Frosted-Glass Aesthetic](#modern-frosted-glass-aesthetic)
+5. [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).
+
+### 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.
+
+### 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.32",
+  "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",