jattac.libs.web.zest-button 1.3.0 → 1.5.0

package/{docs → documentation}/api.md

@@ -18,6 +18,7 @@ This document provides an exhaustive reference for all `ZestButton` props and ty
   - [SuccessOptions](#successoptions)
   - [ConfirmOptions](#confirmoptions)
   - [SemanticType](#semantictype)
+  - [ZestDropdownOption](#zestdropdownoption)
 
 ---
 
@@ -50,6 +51,10 @@ This is the main configuration object passed to the `zest` prop.
 | `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Overrides the automatic theme detection. |
 | `buttonStyle` | `'solid' \| 'outline' \| 'text' \| 'dashed'`| `'solid'` | Defines the visual style of the button. |
 | `semanticType` | `SemanticType` | `undefined` | Defines the semantic type of the button, providing default visuals and behaviors. Extensible via module augmentation. |
+| `dropdownOptions` | `ZestDropdownOption[]` | `undefined` | If provided (non-empty), renders the button as a split button: the main action on the left, and a chevron on the right that opens a menu of these options. See [`ZestDropdownOption`](#zestdropdownoption). |
+| `dropdownAriaLabel` | `string` | `'More options'` | Accessible name for the chevron trigger button (it has no visible text). |
+| `dropdownTheme` | `'light' \| 'dark' \| 'system'` | `'light'` | Theme for the dropdown menu panel, independent of the button's own `theme`. Menus default to light regardless of the button's theme; set this to theme the menu to match. |
+| `dropdownWidth` | `number \| string` | `undefined` | Minimum width for the dropdown menu panel — a number is treated as pixels, a string is used as a raw CSS length (e.g. `'18rem'`). When unset, the menu's minimum width tracks the rendered width of the whole split button control. |
 
 ---
 
@@ -137,4 +142,24 @@ After augmentation, `'archive'` and `'publish'` would be valid `SemanticType` va
 
 ---
 
+#### `ZestDropdownOption`
+
+Describes a single secondary action in a split button's dropdown menu (see [`dropdownOptions`](#zestcustomprops)). Each option runs through the same busy/confirm machinery as the main button, independently per item.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `key` | `string` | index | Stable React key. Defaults to the option's index in the array if omitted. |
+| `label` | `React.ReactNode` | **(Required)** | The menu item's visible content. |
+| `icon` | `React.ReactNode` | `undefined` | An icon to display to the left of the label. |
+| `disabled` | `boolean` | `false` | If true, the item cannot be selected. |
+| `semanticType` | `SemanticType` | `undefined` | Same as the main button's `semanticType` — provides default icon/behavior for this item. |
+| `onClick` | `(e: Event) => void \| Promise<void>` | `undefined` | Handler invoked when the item is selected. |
+| `busyOptions` | `BusyOptions` | `{}` | Same shape as the main button's `busyOptions`, scoped to this item. |
+| `successOptions` | `SuccessOptions` | `{}` | Same shape as the main button's `successOptions`, scoped to this item. |
+| `confirmOptions` | `ConfirmOptions` | `undefined` | Same shape as the main button's `confirmOptions`, scoped to this item. |
+
+*See the [Split Button with Overflow Actions recipe](./examples.md#recipe-5-a-split-button-with-overflow-actions) for a full example.*
+
+---
+
 [⬅️ Previous: Features Showcase](./features.md) | [Next: Configuration Guide ➡️](./configuration.md)

package/{docs → documentation}/examples.md

@@ -10,6 +10,7 @@ Welcome to the ZestButton Cookbook! This is the core learning path for mastering
 - [Recipe 2: The Safe "Delete" Button](#recipe-2-the-safe-delete-button)
 - [Recipe 3: Standardizing Your Buttons with a Global Config](#recipe-3-standardizing-your-buttons-with-a-global-config)
 - [Recipe 4: Creating a Custom "Archive" Button](#recipe-4-creating-a-custom-archive-button)
+- [Recipe 5: A Split Button with Overflow Actions](#recipe-5-a-split-button-with-overflow-actions)
 
 ---
 
@@ -224,4 +225,65 @@ This powerful pattern allows you to build a complete, consistent design system f
 
 ---
 
+### Recipe 5: A Split Button with Overflow Actions
+
+**Goal:** Create a button with one obvious default action ("Export as CSV") plus a few situational alternatives ("Export as PDF", "Export as JSON"), without cluttering the UI with three separate buttons.
+
+**Problem:** You have a primary action and a handful of related, less-common actions. Placing them all as top-level buttons crowds the UI; hiding all of them behind a menu makes the primary action less discoverable and adds an extra click for the common case.
+
+**Solution:** Pass `dropdownOptions` in `zest`. `ZestButton` renders as two visually-fused segments: the main action (left) fires immediately on click, exactly like a normal `ZestButton`, while the chevron (right) opens a menu of the extra options. Each option is independent — it can have its own icon, `busyOptions`, `successOptions`, or `confirmOptions`, running through the same machinery as the main button.
+
+```tsx
+import React from 'react';
+import ZestButton from 'jattac.libs.web.zest-button';
+import { FaFileCsv, FaFilePdf, FaFileCode, FaTrash } from 'react-icons/fa6';
+
+const ExportButton = () => {
+  const exportAs = (format: string) => async () => {
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    alert(`Exported as ${format}!`);
+  };
+
+  return (
+    <ZestButton
+      onClick={exportAs('CSV')}
+      zest={{
+        visualOptions: { iconLeft: <FaFileCsv /> },
+        dropdownOptions: [
+          { label: 'Export as PDF', icon: <FaFilePdf />, onClick: exportAs('PDF') },
+          { label: 'Export as JSON', icon: <FaFileCode />, onClick: exportAs('JSON') },
+          {
+            label: 'Delete export history',
+            icon: <FaTrash />,
+            onClick: async () => alert('History cleared.'),
+            confirmOptions: { displayLabel: 'Confirm Delete', timeoutSecs: 5 },
+          },
+        ],
+      }}
+    >
+      Export as CSV
+    </ZestButton>
+  );
+};
+```
+
+**Theming and sizing the menu independently:** the dropdown menu panel defaults to a light theme and a minimum width matching the whole split button, regardless of the main button's own `theme`. Both are configurable, either per-button or app-wide via `ZestButtonConfigProvider`'s `defaultProps`:
+
+```tsx
+<ZestButton
+  zest={{
+    theme: 'dark',
+    dropdownTheme: 'dark',   // theme the menu to match, instead of the light default
+    dropdownWidth: '16rem',  // force a specific minimum width instead of matching the button
+    dropdownOptions: [{ label: 'Export as PDF', onClick: exportAs('PDF') }],
+  }}
+>
+  Export as CSV
+</ZestButton>
+```
+
+*For the full prop reference, see [`dropdownOptions`](./api.md#zestcustomprops) and [`ZestDropdownOption`](./api.md#zestdropdownoption) in our API reference.*
+
+---
+
 [⬅️ Previous: README](../README.md) | [Next: Features Showcase ➡️](./features.md)

package/{docs → documentation}/features.md

@@ -11,6 +11,7 @@ This document provides a high-level showcase of what's possible with `ZestButton
 - [Semantic Types](#semantic-types)
 - [Global Configuration](#global-configuration)
 - [Rich Styling](#rich-styling)
+- [Split Buttons & Overflow Menus](#split-buttons--overflow-menus)
 
 ---
 
@@ -123,4 +124,27 @@ const MyComponent = () => (
 
 ---
 
+### Split Buttons & Overflow Menus
+
+**What it does:** Attaches a set of secondary actions to a button that already has one obvious default action, via a chevron segment that opens a menu — a discoverable place for "there's more here" without cluttering the UI with extra buttons. Each menu item gets its own independent busy/success/fail/confirm feedback, and the menu can be themed and sized independently of the main button.
+
+```tsx
+const MyComponent = () => (
+  <ZestButton
+    onClick={() => alert('Exported as CSV!')}
+    zest={{
+      dropdownOptions: [
+        { label: 'Export as PDF', onClick: () => alert('Exported as PDF!') },
+        { label: 'Export as JSON', onClick: () => alert('Exported as JSON!') },
+      ],
+    }}
+  >
+    Export as CSV
+  </ZestButton>
+);
+```
+*__Learn more in the [Split Button with Overflow Actions recipe](./examples.md#recipe-5-a-split-button-with-overflow-actions).__*
+
+---
+
 [⬅️ Previous: The Cookbook (Examples)](./examples.md) | [Next: API Reference ➡️](./api.md)

package/package.json

@@ -1,69 +1,79 @@
-{
-  "name": "jattac.libs.web.zest-button",
-  "version": "1.3.0",
-  "description": "A highly customizable and production-ready React button component featuring robust asynchronous handling, rich visual feedback, and built-in confirmation flows for enhanced user experience",
-  "homepage": "https://github.com/nyingimaina/jattac.libs.web.zest-button#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nyingimaina/jattac.libs.web.zest-button.git"
-  },
-  "bugs": {
-    "url": "https://github.com/nyingimaina/jattac.libs.web.zest-button/issues"
-  },
-  "main": "dist/index.cjs.js",
-  "module": "dist/index.esm.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md",
-    "docs"
-  ],
-  "scripts": {
-    "build": "rollup -c rollup.config.mjs",
-    "dev": "rollup -c rollup.config.mjs -w",
-    "test": "echo \"No tests specified. See WORKPLAN.md for future plans.\" && exit 0"
-  },
-  "keywords": [
-    "react",
-    "button",
-    "ui",
-    "component",
-    "interactive",
-    "react-button",
-    "form",
-    "web",
-    "async",
-    "loading",
-    "confirmation",
-    "feedback",
-    "animation",
-    "transitions",
-    "ux",
-    "zest",
-    "jattac"
-  ],
-  "author": "Jattac",
-  "license": "MIT",
-  "peerDependencies": {
-    "react": ">=16.8.0",
-    "react-dom": ">=16.8.0",
-    "react-icons": "^5.0.1"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-typescript": "^11.1.6",
-    "@types/node": "^25.1.0",
-    "@types/react": "^18.2.67",
-    "@types/react-dom": "^18.2.22",
-    "postcss": "^8.4.38",
-    "postcss-modules": "6.0.1",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "rollup": "^4.13.0",
-    "rollup-plugin-dts": "^6.1.0",
-    "rollup-plugin-postcss": "^4.0.2",
-    "tslib": "^2.6.2",
-    "typescript": "^5.4.2"
-  }
-}
+{
+  "name": "jattac.libs.web.zest-button",
+  "version": "1.5.0",
+  "description": "A highly customizable and production-ready React button component featuring robust asynchronous handling, rich visual feedback, and built-in confirmation flows for enhanced user experience",
+  "homepage": "https://github.com/nyingimaina/jattac.libs.web.zest-button#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nyingimaina/jattac.libs.web.zest-button.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nyingimaina/jattac.libs.web.zest-button/issues"
+  },
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "documentation"
+  ],
+  "scripts": {
+    "build": "rollup -c rollup.config.mjs",
+    "dev": "rollup -c rollup.config.mjs -w",
+    "test": "jest --coverage"
+  },
+  "keywords": [
+    "react",
+    "button",
+    "ui",
+    "component",
+    "interactive",
+    "react-button",
+    "form",
+    "web",
+    "async",
+    "loading",
+    "confirmation",
+    "feedback",
+    "animation",
+    "transitions",
+    "ux",
+    "zest",
+    "jattac"
+  ],
+  "author": "Jattac",
+  "license": "MIT",
+  "peerDependencies": {
+    "@radix-ui/react-dropdown-menu": "^2.1.24",
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0",
+    "react-icons": "^5.0.1"
+  },
+  "devDependencies": {
+    "@radix-ui/react-dropdown-menu": "^2.1.24",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.1.0",
+    "@types/react": "^18.2.67",
+    "@types/react-dom": "^18.2.22",
+    "identity-obj-proxy": "^3.0.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
+    "postcss": "^8.4.38",
+    "postcss-modules": "6.0.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rollup": "^4.13.0",
+    "rollup-plugin-dts": "^6.1.0",
+    "rollup-plugin-postcss": "^4.0.2",
+    "ts-jest": "^29.4.12",
+    "tslib": "^2.6.2",
+    "typescript": "^5.4.2"
+  }
+}

package/dist/ZestContext.d.ts

@@ -1,9 +0,0 @@
-import React from 'react';
-import { ZestCustomProps } from './ZestButton';
-export interface ZestGlobalConfig {
-    defaultProps?: ZestCustomProps;
-    semanticTypeDefaults?: Partial<Record<string, Partial<ZestCustomProps>>>;
-}
-declare const ZestContext: React.Context<ZestGlobalConfig | undefined>;
-export declare const useZest: () => ZestGlobalConfig | undefined;
-export default ZestContext;

package/dist/ZestProvider.d.ts

@@ -1,8 +0,0 @@
-import React from 'react';
-import { ZestGlobalConfig } from './ZestContext';
-interface ZestProviderProps {
-    config: ZestGlobalConfig;
-    children: React.ReactNode;
-}
-declare const ZestProvider: React.FC<ZestProviderProps>;
-export default ZestProvider;

package/dist/semanticTypeDefaults.d.ts

@@ -1,4 +0,0 @@
-import { ZestCustomProps } from './ZestButton';
-type SemanticTypeDefaultsMap = Partial<Record<string, Partial<ZestCustomProps>>>;
-export declare const semanticTypeDefaults: SemanticTypeDefaultsMap;
-export {};