jattac.libs.web.zest-button 1.4.0 → 1.5.1

package/documentation/examples.md

@@ -0,0 +1,289 @@
+# The Cookbook: From First Button to Design System
+
+Welcome to the ZestButton Cookbook! This is the core learning path for mastering `ZestButton`. Each recipe solves a real-world problem and builds on the concepts from the previous one. Start here to go from zero to expert.
+
+---
+
+## Table of Contents
+
+- [Recipe 1: Your First Async Button](#recipe-1-your-first-async-button)
+- [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)
+
+---
+
+### Recipe 1: Your First Async Button
+
+**Goal:** Create a button that automatically shows a loading spinner during an operation and gives feedback when it's done.
+
+**Problem:** You have an API call that takes time. You need to prevent the user from clicking the button multiple times and clearly show when the action is complete.
+
+**Solution:** Simply have your `onClick` handler return a `Promise`. `ZestButton` handles the rest. This example also shows success and failure states.
+
+```tsx
+import React, { useState } from 'react';
+import ZestButton from 'jattac.libs.web.zest-button';
+import { FaSave } from 'react-icons/fa';
+
+const SaveButton = () => {
+  const [shouldSucceed, setShouldSucceed] = useState(true);
+
+  const handleSave = async () => {
+    console.log('Saving...');
+    // Simulate an API call
+    await new Promise((resolve, reject) => {
+      setTimeout(() => {
+        shouldSucceed ? resolve('Success!') : reject('Error!');
+      }, 1500);
+    });
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '300px' }}>
+      <label>
+        <input
+          type="checkbox"
+          checked={shouldSucceed}
+          onChange={() => setShouldSucceed(e => !e)}
+        />
+        Simulate Success
+      </label>
+      <ZestButton
+        onClick={handleSave}
+        zest={{
+          visualOptions: { iconLeft: <FaSave />, stretch: true },
+        }}
+      >
+        Save Settings
+      </ZestButton>
+    </div>
+  );
+};
+```
+*For more details on all available options, see the [`BusyOptions`](./api.md#busyoptions) and [`SuccessOptions`](./api.md#successoptions) in our API reference.*
+
+---
+
+### Recipe 2: The Safe "Delete" Button
+
+**Goal:** Create a button for a destructive action that requires a second click to confirm.
+
+**Problem:** Destructive actions like deleting data are dangerous. A user might click the button by accident.
+
+**Solution:** Use the `confirmOptions` prop. This forces the user to click once to start a countdown, and a second time to execute the action. Combining this with a `danger` variant provides a clear visual warning.
+
+```tsx
+import React from 'react';
+import ZestButton from 'jattac.libs.web.zest-button';
+import { FaTrash } from 'react-icons/fa';
+
+const DeleteButton = () => {
+  const handleDelete = () => {
+    alert('Item has been permanently deleted.');
+  };
+
+  return (
+    <ZestButton
+      onClick={handleDelete}
+      zest={{
+        visualOptions: {
+          variant: 'danger',
+          iconLeft: <FaTrash />,
+        },
+        confirmOptions: {
+          displayLabel: 'Confirm Deletion',
+          timeoutSecs: 5,
+        },
+      }}
+    >
+      Delete Account
+    </ZestButton>
+  );
+};
+```
+*For more details, see the [`ConfirmOptions`](./api.md#confirmoptions) in our API reference.*
+
+---
+
+### Recipe 3: Standardizing Your Buttons with a Global Config
+
+**Goal:** Define a consistent look and feel for all buttons in your application without repeating props.
+
+**Problem:** Your app has dozens of buttons. Specifying `size: 'sm'` or `buttonStyle: 'outline'` on every single one is tedious and error-prone.
+
+**Solution:** Wrap your application in the `ZestProvider` and pass a `config` object. Any props in `defaultProps` will be applied to every `ZestButton` within the provider. Local props on a button will always override the global default.
+
+```tsx
+// In your main App.tsx
+import React from 'react';
+import { ZestButtonConfigProvider, ZestButton } from 'jattac.libs.web.zest-button';
+
+const appZestConfig = {
+  defaultProps: {
+    visualOptions: {
+      size: 'sm', // Make all buttons small by default
+    },
+    buttonStyle: 'outline', // Make all buttons outline by default
+  },
+};
+
+const App = () => (
+  <ZestButtonConfigProvider config={appZestConfig}>
+    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
+      <ZestButton>I'm a small outline button</ZestButton>
+      <ZestButton>So am I</ZestButton>
+      <ZestButton zest={{ visualOptions: { size: 'lg' }, buttonStyle: 'solid' }}>
+        I'm a large solid button! (Local override)
+      </ZestButton>
+    </div>
+  </ZestButtonConfigProvider>
+);
+```
+*For a full list of provider settings, see the [`ZestGlobalConfig`](./api.md#zestglobalconfig) documentation. To understand the precedence rules, see the [Configuration Guide](./configuration.md).*
+
+---
+
+### Recipe 4: Creating a Custom "Archive" Button
+
+**Goal:** Create a new, reusable button "type" with its own specific icon, style, and behavior that can be used anywhere in the app.
+
+**Problem:** You have a common action in your app, like "Archive," that should always look and feel the same. You want to avoid configuring it manually each time and just be able to write `zest={{ semanticType: 'archive' }}`.
+
+**Solution:** This is a two-step process that combines **TypeScript Module Augmentation** with the **`ZestButtonConfigProvider`**.
+
+**Step 1: Define the new type**
+In your project's type declarations file (e.g., `src/zest.d.ts`), augment the `CustomZestSemanticTypes` interface.
+
+```typescript
+// src/zest.d.ts
+import 'jattac.libs.web.zest-button';
+import { FaArchive } from 'react-icons/fa';
+
+// 1. Tell ZestButton that 'archive' is a valid semantic type
+declare module 'jattac.libs.web.zest-button' {
+  export interface CustomZestSemanticTypes {
+    archive: 'archive';
+  }
+}
+```
+*(For more on this, see the [Contributor's Guide](./development.md#extending-semantic-types).)*
+
+**Step 2: Provide the default configuration**
+In your `App.tsx`, use the `semanticTypeDefaults` property in the `ZestButtonConfigProvider` to define the default props for your new `'archive'` type.
+
+```tsx
+// In your main App.tsx
+import React from 'react';
+import { ZestButtonConfigProvider, ZestButton } from 'jattac.libs.web.zest-button';
+import { FaArchive } from 'react-icons/fa';
+
+const appZestConfig = {
+  semanticTypeDefaults: {
+    // 2. Define the default props for the 'archive' type
+    archive: {
+      buttonStyle: 'outline',
+      visualOptions: {
+        iconLeft: <FaArchive />,
+        variant: 'standard',
+      },
+      confirmOptions: {
+        displayLabel: 'Confirm Archive?',
+        timeoutSecs: 10,
+      },
+    },
+    // You can also override built-in types here!
+    delete: {
+      buttonStyle: 'outline', // Make all delete buttons 'outline'
+    }
+  },
+};
+
+const App = () => (
+  <ZestButtonConfigProvider config={appZestConfig}>
+    <div style={{ display: 'flex', gap: '1rem' }}>
+        {/* 3. Now just use it! */}
+        <ZestButton 
+          zest={{ semanticType: 'archive' }} 
+          onClick={() => alert('Archived!')}
+        >
+          Archive
+        </ZestButton>
+
+        <ZestButton 
+          zest={{ semanticType: 'delete' }}
+          onClick={() => alert('Deleted!')}
+        >
+          Delete
+        </ZestButton>
+    </div>
+  </ZestButtonConfigProvider>
+);
+```
+This powerful pattern allows you to build a complete, consistent design system for all button actions in your application. For more details on configuration, see the [Configuration Guide](./configuration.md).*
+
+---
+
+### 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',   // pin the menu's theme, instead of following the OS/browser preference
+    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/documentation/features.md

@@ -0,0 +1,150 @@
+# Features: A Guided Tour
+
+This document provides a high-level showcase of what's possible with `ZestButton`. For detailed, practical implementation guides, please see our **[Cookbook](./examples.md)**.
+
+---
+
+## Table of Contents
+
+- [Asynchronous Operations & Feedback](#asynchronous-operations--feedback)
+- [Confirmation Flow](#confirmation-flow)
+- [Semantic Types](#semantic-types)
+- [Global Configuration](#global-configuration)
+- [Rich Styling](#rich-styling)
+- [Split Buttons & Overflow Menus](#split-buttons--overflow-menus)
+
+---
+
+### Asynchronous Operations & Feedback
+
+**What it does:** Automatically handles loading states and provides clear success/failure feedback for any action that returns a Promise.
+
+```tsx
+const MyComponent = () => {
+  const handleAsyncClick = async () => {
+    // Simulate an API call that takes 2 seconds
+    await new Promise(resolve => setTimeout(resolve, 2000));
+  };
+
+  return (
+    <ZestButton onClick={handleAsyncClick}>
+      Perform Async Action
+    </ZestButton>
+  );
+};
+```
+*__Learn more in the [Your First Async Button recipe](./examples.md#recipe-1-your-first-async-button).__*
+
+---
+
+### Confirmation Flow
+
+**What it does:** Protects users from accidentally performing critical actions by requiring a second click to confirm.
+
+```tsx
+const MyComponent = () => {
+  const handleDelete = () => alert('The item has been deleted!');
+
+  return (
+    <ZestButton
+      onClick={handleDelete}
+      zest={{
+        confirmOptions: { displayLabel: 'Confirm?', timeoutSecs: 5 },
+        visualOptions: { variant: 'danger' }
+      }}
+    >
+      Delete Item
+    </ZestButton>
+  );
+};
+```
+*__Learn more in the [Safe "Delete" Button recipe](./examples.md#recipe-2-the-safe-delete-button).__*
+
+---
+
+### Semantic Types
+
+**What it does:** Streamlines development by allowing you to declare button intent (e.g., `'save'`, `'delete'`). The button automatically gets appropriate icons, colors, and behaviors.
+
+```tsx
+const MyComponent = () => (
+    <div style={{ display: 'flex', gap: '1rem' }}>
+        <ZestButton zest={{ semanticType: 'save' }}>Save</ZestButton>
+        <ZestButton zest={{ semanticType: 'cancel' }}>Cancel</ZestButton>
+    </div>
+);
+```
+*__Learn how to create your own in the [Creating a Custom "Archive" Button recipe](./examples.md#recipe-4-creating-a-custom-archive-button).__*
+
+---
+
+### Global Configuration
+
+**What it does:** Allows you to define a consistent style (like size or button style) for all buttons across your entire application.
+
+```tsx
+// In your App.tsx
+const appZestConfig = {
+  defaultProps: {
+    visualOptions: { size: 'sm' },
+    buttonStyle: 'outline',
+  },
+};
+
+const App = () => (
+  <ZestButtonConfigProvider config={appZestConfig}>
+    {/* All buttons inside will be small and outline by default */}
+  </ZestButtonConfigProvider>
+);
+```
+*__Learn more in the [Standardizing Your Buttons recipe](./examples.md#recipe-3-standardizing-your-buttons-with-a-global-config).__*
+
+---
+
+### Rich Styling
+
+**What it does:** Provides multiple variants, sizes, and styles (`solid`, `outline`, `text`, `dashed`) to fit any UI context. It also automatically adapts to light and dark themes.
+
+```tsx
+const MyComponent = () => (
+  <div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
+    <ZestButton zest={{ visualOptions: { variant: 'success', size: 'sm' } }}>
+      Small Success
+    </ZestButton>
+    <ZestButton zest={{ buttonStyle: 'outline', size: 'md' }}>
+      Medium Outline
+    </ZestButton>
+    <ZestButton zest={{ visualOptions: { variant: 'danger', size: 'lg' } }}>
+      Large Danger
+    </ZestButton>
+  </div>
+);
+```
+*Explore all the recipes in the **[Cookbook](./examples.md)** to see these options in action.*
+
+---
+
+### 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,6 +1,6 @@
 {
   "name": "jattac.libs.web.zest-button",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "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": {
@@ -16,7 +16,8 @@
   "files": [
     "dist",
     "README.md",
-    "docs"
+    "LICENSE",
+    "documentation"
   ],
   "scripts": {
     "build": "rollup -c rollup.config.mjs",

package/docs/e2e/critical-paths.md

@@ -1,75 +0,0 @@
-# Critical Paths
-
-This document defines the critical business paths that MUST be covered by e2E tests.
-
----
-
-## How to Identify Critical Paths
-
-A path is critical if:
-
-• It handles money or payments
-
-• It manages user authentication or authorization
-
-• It writes to the database in ways that affect business data
-
-• It integrates with external systems
-
-• If broken, it causes immediate user-facing impact
-
----
-
-## Paths
-
-### Authentication
-
-- [ ] Login with valid credentials → 200 + token
-
-- [ ] Login with invalid credentials → 401
-
-- [ ] Token refresh → 200 + new token
-
-- [ ] Logout → 200 + token invalidated
-
-### Payment
-
-- [ ] Create payment → 201 + payment record
-
-- [ ] Confirm payment → 200 + status updated
-
-- [ ] Handle payment failure → 200 + status updated
-
-- [ ] Process refund → 200 + refund record
-
-### Order
-
-- [ ] Create order → 201 + order record
-
-- [ ] Pay order → 200 + order status updated
-
-- [ ] Ship order → 200 + order status updated
-
-- [ ] Complete order → 200 + order status updated
-
-- [ ] Cancel order → 200 + order status updated
-
-### Data
-
-- [ ] Import data → 200 + records created
-
-- [ ] Export data → 200 + file returned
-
----
-
-## Adding New Paths
-
-When adding a new critical path:
-
-1. Add the path description above
-
-2. List each scenario with expected outcome
-
-3. Write e2e tests covering each scenario
-
-4. Mark scenarios as tested: `- [x]`