jattac.libs.web.overflow-menu 0.0.28 → 0.0.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +209 -147
  2. package/package.json +76 -76
package/README.md CHANGED
@@ -1,147 +1,209 @@
1
- # React Overflow Menu
2
-
3
- [![npm version](https://badge.fury.io/js/jattac.libs.web.overflow-menu.svg)](https://badge.fury.io/js/jattac.libs.web.overflow-menu)
4
-
5
- A customizable, animated, and lightweight React overflow menu component built with TypeScript and Framer Motion.
6
-
7
- This component provides a clean, modern, and accessible overflow menu suitable for any React application, with a focus on great user experience through satisfying micro-interactions.
8
-
9
- ## Features
10
-
11
- - **Smooth Animations**: Built with Framer Motion for fluid, physics-based animations, including a subtle wave animation and color change for the default icon.
12
- - **Staggered Item Display**: Menu items animate in with a subtle "waterfall" effect.
13
- - **Highly Customizable**: Easily change the trigger icon, menu item content, and functionality.
14
- - **Responsive Positioning**: Mobile-first design with desktop awareness, ensuring the menu positions correctly on various screen sizes and avoids cut-offs.
15
- - **Enhanced Hover Effects**: Menu items feature modern background and foreground color changes on hover for clear visual feedback.
16
- - **Item Separators**: Muted borders visually separate menu items, improving clarity and user experience.
17
- - **Portal Support**: Optionally render the menu in a React Portal to avoid CSS stacking context issues.
18
- - **Lightweight**: Simple and focused on providing a great overflow menu experience without unnecessary bloat.
19
-
20
- ## Installation
21
-
22
- Install the package and its peer dependencies using npm:
23
-
24
- ```bash
25
- npm install jattac.libs.web.overflow-menu react react-dom framer-motion
26
- ```
27
-
28
- ## Getting Started
29
-
30
- Here's a basic example to get you up and running quickly.
31
-
32
- ```jsx
33
- import React from 'react';
34
- import OverflowMenu, { IOverflowMenuItem } from 'jattac.libs.web.overflow-menu';
35
-
36
- const App = () => {
37
- const menuItems: IOverflowMenuItem[] = [
38
- {
39
- content: 'Edit Profile',
40
- onClick: () => alert('Editing Profile!'),
41
- },
42
- {
43
- content: 'View Settings',
44
- onClick: () => alert('Viewing Settings!'),
45
- },
46
- {
47
- content: 'Log Out',
48
- onClick: () => alert('Logging Out!'),
49
- },
50
- ];
51
-
52
- return (
53
- <div style={{ position: 'relative', display: 'flex', justifyContent: 'flex-end', padding: '2rem' }}>
54
- <OverflowMenu items={menuItems} />
55
- </div>
56
- );
57
- };
58
-
59
- export default App;
60
- ```
61
-
62
- ## API and Props
63
-
64
- The `OverflowMenu` component accepts the following props:
65
-
66
- | Prop | Type | Required | Default | Description |
67
- |-------------|-----------------------|----------|---------|------------------------------------------------------------------------------------------------------------|
68
- | `items` | `IOverflowMenuItem[]` | Yes | - | An array of objects that define the menu items. |
69
- | `icon` | `ReactNode` | No | `'⋮'` | A custom trigger icon to open the menu. |
70
- | `className` | `string` | No | `''` | A CSS class to apply to the trigger button for custom styling. |
71
- | `portal` | `HTMLElement` | No | `null` | A DOM element to render the menu into. Use this to prevent z-index issues with parent containers. |
72
-
73
- ### The `IOverflowMenuItem` Interface
74
-
75
- Each item in the `items` array must conform to this interface:
76
-
77
- ```typescript
78
- interface IOverflowMenuItem {
79
- content: React.ReactNode; // The content to display for the item.
80
- onClick?: () => void; // Function to call when the item is clicked.
81
- }
82
- ```
83
-
84
- ---
85
-
86
- ## Advanced Usage
87
-
88
- ### Custom Trigger Icon
89
-
90
- You can provide any `ReactNode` as the trigger icon. This is great for using a custom SVG or an icon from a library like `react-icons`.
91
-
92
- ```jsx
93
- import { BsThreeDotsVertical } from 'react-icons/bs';
94
-
95
- // ...
96
- <OverflowMenu items={menuItems} icon={<BsThreeDotsVertical size={24} />} />
97
- ```
98
-
99
- ### Complex Item Content
100
-
101
- The `content` property of a menu item can be any valid `ReactNode`. This allows you to create rich menu items with icons, styled text, and more.
102
-
103
- ```jsx
104
- import { FiEdit, FiLogOut } from 'react-icons/fi';
105
-
106
- const richMenuItems: IOverflowMenuItem[] = [
107
- {
108
- content: (
109
- <span style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
110
- <FiEdit /> Edit Profile
111
- </span>
112
- ),
113
- onClick: () => alert('Editing Profile!'),
114
- },
115
- {
116
- content: (
117
- <span style={{ display: 'flex', alignItems: 'center', gap: '8px', color: 'red' }}>
118
- <FiLogOut /> Log Out
119
- </span>
120
- ),
121
- onClick: () => alert('Logging Out!'),
122
- },
123
- ];
124
-
125
- // ...
126
- <OverflowMenu items={richMenuItems} />
127
- ```
128
-
129
- ---
130
-
131
- ## Styling and Customization
132
-
133
- The component's styling is primarily controlled via its internal CSS module (`OverflowMenu.module.css`). While direct customization through CSS variables is no longer supported, you can override the component's default styles by targeting its CSS classes in your own stylesheets.
134
-
135
- For example, to change the background of the menu:
136
-
137
- ```css
138
- /* In your application's CSS file */
139
- .your-custom-wrapper-class .OverflowMenu-module_menu__n8uKD { /* Use the hashed class name from your build output */
140
- background: #f0f0f0; /* Your desired background */
141
- }
142
- ```
143
- *Note: The exact hashed class names (e.g., `OverflowMenu-module_menu__n8uKD`) will depend on your build process. You may need to inspect the rendered HTML to find them.*
144
-
145
- ## License
146
-
147
- This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
1
+ # Jattac Overflow Menu
2
+
3
+ [![npm version](https://badge.fury.io/js/jattac.libs.web.overflow-menu.svg)](https://badge.fury.io/js/jattac.libs.web.overflow-menu)
4
+
5
+ A customizable, accessible, and animated overflow menu for React, designed for a delightful developer experience.
6
+
7
+ This component provides a powerful and flexible overflow menu that is easy to style and customize. It's built on top of [Radix UI's](https://www.radix-ui.com/) Dropdown Menu primitive and animated with [Framer Motion](https://www.framer.com/motion/), giving you a robust foundation with a beautiful user experience out of the box.
8
+
9
+ ---
10
+
11
+ ## Table of Contents
12
+
13
+ - [Why Jattac Overflow Menu?](#why-jattac-overflow-menu)
14
+ - [Installation](#installation)
15
+ - [Getting Started](#getting-started)
16
+ - [API and Props](#api-and-props)
17
+ - [`OverflowMenu` Component](#overflowmenu-component)
18
+ - [`IOverflowMenuItem` Interface](#ioverflowmenuitem-interface)
19
+ - [Recipes: From Zero to Expert](#recipes-from-zero-to-expert)
20
+ - [Custom Trigger Icon](#custom-trigger-icon)
21
+ - [Rich Item Content](#rich-item-content)
22
+ - [Using a Portal](#using-a-portal)
23
+ - [Styling and Customization](#styling-and-customization)
24
+ - [Accessibility](#accessibility)
25
+ - [License](#license)
26
+
27
+ ---
28
+
29
+ ## Why Jattac Overflow Menu?
30
+
31
+ This component is designed to be the last overflow menu you'll ever need. Here's the philosophy:
32
+
33
+ - **Headless at the Core:** We leverage the power of Radix UI to handle all the complex logic for state management, positioning, and accessibility. This means you get a battle-tested foundation that just works.
34
+ - **You Own the UI:** While we provide a default modern look and feel, you have 100% control over the rendering. Use our styles, or override them completely. It's your choice.
35
+ - **Animations Included:** We use Framer Motion to provide smooth, delightful animations out of the box.
36
+ - **Developer Experience First:** Our goal is to provide a component that is easy to learn, a joy to use, and powerful enough for advanced use cases.
37
+
38
+ ## Installation
39
+
40
+ Install the package and its peer dependencies using npm:
41
+
42
+ ```bash
43
+ npm install jattac.libs.web.overflow-menu react react-dom framer-motion @radix-ui/react-dropdown-menu
44
+ ```
45
+
46
+ > **Note on Peer Dependencies:** This component requires `react`, `react-dom`, `framer-motion`, and `@radix-ui/react-dropdown-menu` to be installed in your project.
47
+
48
+ ## Getting Started
49
+
50
+ Here's a basic example to get you up and running in seconds.
51
+
52
+ ```jsx
53
+ import React from 'react';
54
+ import OverflowMenu, { IOverflowMenuItem } from 'jattac.libs.web.overflow-menu';
55
+ import 'jattac.libs.web.overflow-menu/dist/index.css'; // Don't forget to import the styles!
56
+
57
+ const App = () => {
58
+ const menuItems: IOverflowMenuItem[] = [
59
+ {
60
+ content: 'Edit Profile',
61
+ onClick: () => alert('Editing Profile!'),
62
+ },
63
+ {
64
+ content: 'View Settings',
65
+ onClick: () => alert('Viewing Settings!'),
66
+ },
67
+ {
68
+ content: 'Log Out',
69
+ onClick: () => alert('Logging Out!'),
70
+ },
71
+ ];
72
+
73
+ return (
74
+ <div style={{ display: 'flex', justifyContent: 'flex-end', padding: '2rem' }}>
75
+ <OverflowMenu items={menuItems} />
76
+ </div>
77
+ );
78
+ };
79
+
80
+ export default App;
81
+ ```
82
+
83
+ ## API and Props
84
+
85
+ ### `OverflowMenu` Component
86
+
87
+ The `OverflowMenu` component accepts the following props:
88
+
89
+ | Prop | Type | Required | Default | Description |
90
+ |-------------|-----------------------|----------|-------------|------------------------------------------------------------------------------------------------------------|
91
+ | `items` | `IOverflowMenuItem[]` | Yes | - | An array of objects that define the menu items. |
92
+ | `icon` | `ReactNode` | No | `DefaultIcon` | A custom trigger icon to open the menu. |
93
+ | `className` | `string` | No | `''` | A CSS class to apply to the trigger button for custom styling. |
94
+ | `portal` | `HTMLElement` | No | `null` | A DOM element to render the menu into. Use this to prevent z-index issues with parent containers. |
95
+
96
+ ### `IOverflowMenuItem` Interface
97
+
98
+ Each item in the `items` array must conform to this interface:
99
+
100
+ ```typescript
101
+ interface IOverflowMenuItem {
102
+ content: React.ReactNode; // The content to display for the item.
103
+ onClick?: () => void; // Function to call when the item is clicked.
104
+ }
105
+ ```
106
+
107
+ ---
108
+
109
+ ## Recipes: From Zero to Expert
110
+
111
+ Here are some common use cases to help you get the most out of the component.
112
+
113
+ ### Custom Trigger Icon
114
+
115
+ You can provide any `ReactNode` as the trigger icon. This is great for using a custom SVG or an icon from a library like `react-icons`.
116
+
117
+ ```jsx
118
+ import { BsThreeDotsVertical } from 'react-icons/bs';
119
+ // ...
120
+ <OverflowMenu items={menuItems} icon={<BsThreeDotsVertical size={24} />} />
121
+ ```
122
+
123
+ ### Rich Item Content
124
+
125
+ The `content` property of a menu item can be any valid `ReactNode`. This allows you to create rich menu items with icons, styled text, and more.
126
+
127
+ ```jsx
128
+ import { FiEdit, FiLogOut } from 'react-icons/fi';
129
+
130
+ const richMenuItems: IOverflowMenuItem[] = [
131
+ {
132
+ content: (
133
+ <span style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
134
+ <FiEdit /> Edit Profile
135
+ </span>
136
+ ),
137
+ onClick: () => alert('Editing Profile!'),
138
+ },
139
+ {
140
+ content: (
141
+ <span style={{ display: 'flex', alignItems: 'center', gap: '8px', color: 'red' }}>
142
+ <FiLogOut /> Log Out
143
+ </span>
144
+ ),
145
+ onClick: () => alert('Logging Out!'),
146
+ },
147
+ ];
148
+
149
+ // ...
150
+ <OverflowMenu items={richMenuItems} />
151
+ ```
152
+
153
+ ### Using a Portal
154
+
155
+ To avoid z-index issues with parent containers, you can render the menu in a React Portal.
156
+
157
+ ```jsx
158
+ const App = () => {
159
+ const portalContainer = document.getElementById('portal-container');
160
+ // ...
161
+ return (
162
+ <div>
163
+ <OverflowMenu items={menuItems} portal={portalContainer} />
164
+ {/* ... other content ... */}
165
+ <div id="portal-container" />
166
+ </div>
167
+ );
168
+ }
169
+ ```
170
+
171
+ > **Best Practice:** Using a portal is highly recommended for menus that might be rendered inside complex layouts, such as tables, modals, or other components with their own stacking context.
172
+
173
+ ---
174
+
175
+ ## Styling and Customization
176
+
177
+ The component is styled using CSS Modules, but it's designed to be easily customized. The underlying Radix UI components expose `data-` attributes that you can use to target specific states and parts of the menu.
178
+
179
+ Here are some of the most common selectors:
180
+
181
+ | Selector | Description |
182
+ |----------------------------------------|-------------------------------------------|
183
+ | `[data-state="open"]` | Applied to the trigger when the menu is open. |
184
+ | `[data-state="closed"]` | Applied to the trigger when the menu is closed. |
185
+ | `.jattac-overflow-menu-content` | The menu content container. |
186
+ | `.jattac-overflow-menu-item` | An individual menu item. |
187
+ | `[data-highlighted]` | Applied to a menu item when it is highlighted (e.g., on hover or with keyboard navigation). |
188
+
189
+ **Example: Overriding the background color of a highlighted item**
190
+
191
+ ```css
192
+ /* In your application's global CSS file */
193
+ .jattac-overflow-menu-item[data-highlighted] {
194
+ background-color: #f0f0f0;
195
+ color: #333;
196
+ }
197
+ ```
198
+
199
+ ## Accessibility
200
+
201
+ This component is built on top of Radix UI's Dropdown Menu, which is fully accessible and follows the [WAI-ARIA Menu Button design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/).
202
+
203
+ - **Keyboard Navigation:** Full keyboard support for opening, closing, and navigating the menu.
204
+ - **Focus Management:** Focus is automatically managed, moving to the menu when it opens and returning to the trigger when it closes.
205
+ - **ARIA Attributes:** All necessary ARIA attributes are automatically applied.
206
+
207
+ ## License
208
+
209
+ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
package/package.json CHANGED
@@ -1,76 +1,76 @@
1
- {
2
- "name": "jattac.libs.web.overflow-menu",
3
- "version": "0.0.28",
4
- "description": "A customizable and lightweight React overflow menu component with a modern design.",
5
- "main": "dist/index.js",
6
- "module": "dist/index.es.js",
7
- "types": "dist/index.d.ts",
8
- "exports": {
9
- ".": {
10
- "import": "./dist/index.es.js",
11
- "require": "./dist/index.js",
12
- "types": "./dist/index.d.ts"
13
- },
14
- "./dist/index.css": {
15
- "import": "./dist/index.css",
16
- "require": "./dist/index.css"
17
- }
18
- },
19
- "files": [
20
- "dist"
21
- ],
22
- "scripts": {
23
- "build": "rollup -c",
24
- "watch": "rollup -c -w",
25
- "lint": "eslint \"./{src,app}/**/*.{ts,tsx}\"",
26
- "size": "size-limit",
27
- "prepare": "npm run build"
28
- },
29
- "keywords": [
30
- "react",
31
- "typescript",
32
- "menu",
33
- "overflow-menu",
34
- "component"
35
- ],
36
- "author": "Nyingi Maina",
37
- "license": "MIT",
38
- "peerDependencies": {
39
- "react": ">=18.2.0",
40
- "react-dom": ">=18.2.0",
41
- "framer-motion": ">=11.0.0"
42
- },
43
- "devDependencies": {
44
- "@rollup/plugin-commonjs": "^25.0.7",
45
- "@rollup/plugin-node-resolve": "^15.2.3",
46
- "@rollup/plugin-terser": "^0.4.4",
47
- "@rollup/plugin-typescript": "^11.1.5",
48
- "@size-limit/preset-small-lib": "^10.0.1",
49
- "@types/react": "^18.2.33",
50
- "@types/react-dom": "^18.2.14",
51
- "@typescript-eslint/eslint-plugin": "^6.9.1",
52
- "@typescript-eslint/parser": "^6.9.1",
53
- "eslint": "^8.52.0",
54
- "eslint-config-prettier": "^9.0.0",
55
- "eslint-plugin-prettier": "^5.0.1",
56
- "eslint-plugin-react": "^7.33.2",
57
- "framer-motion": "^12.23.16",
58
- "postcss": "^8.4.31",
59
- "prettier": "^3.0.3",
60
- "react": "^18.2.0",
61
- "react-dom": "^18.2.0",
62
- "rollup": "^4.2.0",
63
- "rollup-plugin-copy": "^3.5.0",
64
- "rollup-plugin-delete": "^2.0.0",
65
- "rollup-plugin-generate-package-json": "^3.2.0",
66
- "rollup-plugin-peer-deps-external": "^2.2.4",
67
- "rollup-plugin-postcss": "^4.0.2",
68
- "size-limit": "^10.0.1",
69
- "typescript": "^5.2.2"
70
- },
71
- "dependencies": {
72
- "@radix-ui/react-dropdown-menu": "^2.0.6",
73
- "@radix-ui/react-popover": "^1.0.7",
74
- "tslib": "^2.6.2"
75
- }
76
- }
1
+ {
2
+ "name": "jattac.libs.web.overflow-menu",
3
+ "version": "0.0.29",
4
+ "description": "A customizable and lightweight React overflow menu component with a modern design.",
5
+ "main": "dist/index.js",
6
+ "module": "dist/index.es.js",
7
+ "types": "dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "import": "./dist/index.es.js",
11
+ "require": "./dist/index.js",
12
+ "types": "./dist/index.d.ts"
13
+ },
14
+ "./dist/index.css": {
15
+ "import": "./dist/index.css",
16
+ "require": "./dist/index.css"
17
+ }
18
+ },
19
+ "files": [
20
+ "dist"
21
+ ],
22
+ "scripts": {
23
+ "build": "rollup -c",
24
+ "watch": "rollup -c -w",
25
+ "lint": "eslint \"./{src,app}/**/*.{ts,tsx}\"",
26
+ "size": "size-limit",
27
+ "prepare": "npm run build"
28
+ },
29
+ "keywords": [
30
+ "react",
31
+ "typescript",
32
+ "menu",
33
+ "overflow-menu",
34
+ "component"
35
+ ],
36
+ "author": "Nyingi Maina",
37
+ "license": "MIT",
38
+ "peerDependencies": {
39
+ "react": ">=18.2.0",
40
+ "react-dom": ">=18.2.0",
41
+ "framer-motion": ">=11.0.0"
42
+ },
43
+ "devDependencies": {
44
+ "@rollup/plugin-commonjs": "^25.0.7",
45
+ "@rollup/plugin-node-resolve": "^15.2.3",
46
+ "@rollup/plugin-terser": "^0.4.4",
47
+ "@rollup/plugin-typescript": "^11.1.5",
48
+ "@size-limit/preset-small-lib": "^10.0.1",
49
+ "@types/react": "^18.2.33",
50
+ "@types/react-dom": "^18.2.14",
51
+ "@typescript-eslint/eslint-plugin": "^6.9.1",
52
+ "@typescript-eslint/parser": "^6.9.1",
53
+ "eslint": "^8.52.0",
54
+ "eslint-config-prettier": "^9.0.0",
55
+ "eslint-plugin-prettier": "^5.0.1",
56
+ "eslint-plugin-react": "^7.33.2",
57
+ "framer-motion": "^12.23.16",
58
+ "postcss": "^8.4.31",
59
+ "prettier": "^3.0.3",
60
+ "react": "^18.2.0",
61
+ "react-dom": "^18.2.0",
62
+ "rollup": "^4.2.0",
63
+ "rollup-plugin-copy": "^3.5.0",
64
+ "rollup-plugin-delete": "^2.0.0",
65
+ "rollup-plugin-generate-package-json": "^3.2.0",
66
+ "rollup-plugin-peer-deps-external": "^2.2.4",
67
+ "rollup-plugin-postcss": "^4.0.2",
68
+ "size-limit": "^10.0.1",
69
+ "typescript": "^5.2.2"
70
+ },
71
+ "dependencies": {
72
+ "@radix-ui/react-dropdown-menu": "^2.0.6",
73
+ "@radix-ui/react-popover": "^1.0.7",
74
+ "tslib": "^2.6.2"
75
+ }
76
+ }