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

package/docs/api.md

@@ -4,7 +4,7 @@ This document provides exhaustive technical specifications for the Jattac Overfl
 
 ### Table of Contents
 1. [OverflowMenu Component](#overflowmenu-component)
-2. [IOverflowMenuItem Interface](#ioverflowmenuitem-interface)
+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)
 
@@ -21,19 +21,26 @@ The primary component for rendering the overflow menu.
 | `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
+### IOverflowMenuItem Type
 
-The interface defining the structure of each item in the `items` array.
+`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 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.
+| `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.
 
 ---
 

package/docs/breaking-changes.md

@@ -3,13 +3,50 @@
 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)
+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.30 (Upcoming)
+### 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.
 

package/docs/development.md

@@ -21,12 +21,17 @@ To get started with local development, ensure you have Node.js and npm installed
 
 ### 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.
+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
 

package/docs/examples.md

@@ -7,7 +7,9 @@ The Jattac Overflow Menu is designed to be highly flexible. This cookbook provid
 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)
+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)
 
@@ -114,6 +116,70 @@ const MyComponent = () => (
 );
 ```
 
+### 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.

package/docs/features.md

@@ -5,9 +5,11 @@ The Jattac Overflow Menu offers a powerful set of features designed to simplify
 ### 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)
+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)
 
@@ -28,10 +30,23 @@ Organize complex sets of actions with ease using recursive submenus. The library
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jattac.libs.web.overflow-menu",
-  "version": "0.0.32",
+  "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",