jattac.libs.web.zest-button 1.2.1 → 1.2.3

package/docs/api.md

@@ -0,0 +1,119 @@
+# API Reference: The Technical Blueprint
+
+This document provides an exhaustive reference for all `ZestButton` props and type definitions.
+
+---
+
+### `ZestButtonProps`
+
+The `ZestButton` component accepts all standard HTML `<button>` attributes (e.g., `disabled`, `type`, `name`, `className`) in addition to its own custom configuration prop, `zest`.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `zest` | `ZestCustomProps` | `{}` | An object containing all custom configuration for the button's behavior and appearance. See `ZestCustomProps` below for details. |
+| `...rest`| `React.ButtonHTMLAttributes` | | All other standard button props are passed directly to the underlying `<button>` element. |
+
+---
+
+### Type Definitions
+
+The `zest` prop is a configuration object that follows the `ZestCustomProps` interface. Its properties are detailed below.
+
+#### `ZestCustomProps`
+
+This is the main configuration object passed to the `zest` prop.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `visualOptions` | `VisualOptions` | `{}` | Controls the button's appearance, including variant, size, and icons. |
+| `busyOptions` | `BusyOptions` | `{}` | Configures behavior for asynchronous operations. |
+| `successOptions` | `SuccessOptions` | `{}` | Configures feedback after a successful or failed operation. |
+| `confirmOptions` | `ConfirmOptions` | `undefined` | If provided, enables the "click-to-confirm" workflow. |
+| `isDefault` | `boolean` | `false` | If true, the button can be triggered by the `Enter` key. |
+| `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. |
+
+---
+
+#### `ZestGlobalConfig`
+
+This is the configuration object passed to the `config` prop of the `ZestProvider`.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `defaultProps` | `ZestCustomProps` | `{}` | A set of `ZestCustomProps` that will be applied to all `ZestButton` instances within the provider's scope. |
+| `semanticTypeDefaults` | `Partial<Record<string, Partial<ZestCustomProps>>>` | `{}` | A map of semantic types to `ZestCustomProps`. This allows you to define defaults for custom semantic types or override the library's built-in defaults. |
+
+---
+
+#### `VisualOptions`
+
+Controls the button's appearance.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `variant` | `'standard' \| 'success' \| 'danger'` | `'standard'`| The color scheme of the button. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the button, affecting padding and font size. |
+| `fullWidth` | `boolean` | `false` | If true, the button expands to the full width of its parent. |
+| `iconLeft` | `React.ReactNode` | `undefined` | A React node (e.g., an icon component) to display on the left. |
+| `iconRight` | `React.ReactNode` | `undefined` | A React node to display on the right. |
+
+---
+
+#### `BusyOptions`
+
+Configures behavior during asynchronous `onClick` operations.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `handleInternally` | `boolean` | `true` | If true, automatically manages busy state when `onClick` returns a Promise. |
+| `preventRageClick` | `boolean` | `true` | If true, disables the button while it is in a busy, success, or fail state. |
+| `minBusyDurationMs`| `number` | `500` | Ensures the spinner is shown for at least this long (in ms) to prevent visual flickering on fast network requests. |
+
+---
+
+#### `SuccessOptions`
+
+Configures the visual feedback after an operation completes.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `showCheckmark` | `boolean` | `true` | If true, displays an animated checkmark when the `onClick` Promise resolves successfully. |
+| `showFailIcon` | `boolean` | `true` | If true, displays an animated 'X' when the `onClick` Promise rejects or the confirmation timer expires. |
+| `autoResetAfterMs`| `number` | `2000` | The duration (in ms) to show the success/fail icon before the button resets to its normal state. |
+
+---
+
+#### `ConfirmOptions`
+
+If this object is provided, the button will require two clicks to fire the `onClick` event.
+
+| Prop Name | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `displayLabel` | `string` | **(Required)**| The text to show during the confirmation phase (e.g., "Confirm?"). The countdown timer is appended automatically. |
+| `timeoutSecs` | `number` | **(Required)**| The number of seconds the user has to click the button a second time to confirm the action. |
+
+---
+
+#### `SemanticType`
+
+The `SemanticType` defines common button actions, allowing `ZestButton` to automatically apply default visuals (e.g., icons, variants) and behaviors (e.g., confirmation prompts). This type is extensible through TypeScript module augmentation.
+
+**Built-in Semantic Types:**
+`'add'`, `'save'`, `'submit'`, `'edit'`, `'update'`, `'delete'`, `'remove'`, `'cancel'`, `'close'`, `'view'`, `'details'`, `'download'`, `'upload'`, `'refresh'`, `'reload'`, `'print'`, `'share'`, `'confirm'`.
+
+**Extensibility:** Developers can extend this list to include custom semantic types by augmenting the `CustomZestSemanticTypes` interface in their project. For example:
+
+```typescript
+// your-project/src/typings/zest-button.d.ts
+import 'jattac.libs.web.zest-button';
+
+declare module 'jattac.libs.web.zest-button' {
+  export interface CustomZestSemanticTypes {
+    archive: 'archive';
+    publish: 'publish';
+  }
+}
+```
+After augmentation, `'archive'` and `'publish'` would be valid `SemanticType` values, available for autocompletion and type-checking.

package/docs/breaking-changes.md

@@ -0,0 +1,52 @@
+# Breaking Changes: The Upgrade Path
+
+This document lists significant changes between versions that might require modifications to your existing codebase.
+
+---
+
+## Version 1.2.0
+
+### Encapsulated Custom Props under `zest` Object
+
+To improve maintainability, reduce prop-drilling, and provide a clearer API surface, all custom `ZestButton` properties have been consolidated under a single `zest` prop. Previously, these properties were passed directly to the `ZestButton` component.
+
+This change allows for better organization of configuration options (e.g., `visualOptions`, `busyOptions`, `confirmOptions`) and prepares the component for future global configuration contexts.
+
+**Before:**
+
+```tsx
+<ZestButton
+  variant="success"
+  size="lg"
+  fullWidth={true}
+  minBusyDurationMs={1000}
+  preventRageClick={false}
+  confirmOptions={{ displayLabel: "Delete?", timeoutSecs: 5 }}
+>
+  My Button
+</ZestButton>
+```
+
+**After:**
+
+```tsx
+<ZestButton
+  zest={{
+    visualOptions: {
+      variant: "success",
+      size: "lg",
+      fullWidth: true,
+    },
+    busyOptions: {
+      minBusyDurationMs: 1000,
+      preventRageClick: false,
+    },
+    confirmOptions: {
+      displayLabel: "Delete?",
+      timeoutSecs: 5,
+    },
+  }}
+>
+  My Button
+</ZestButton>
+```

package/docs/configuration.md

@@ -0,0 +1,192 @@
+# Configuration: The Control Panel
+
+This document explains how to configure `ZestButton` on a component and global level.
+
+---
+
+### Overview
+
+Currently, `ZestButton` is primarily configured on a per-component basis via the `zest` prop. This provides the most explicit and direct control over each button's behavior and appearance.
+
+However, there are ways to manage themes and a clear path for future global configuration.
+
+---
+
+### Theme Configuration
+
+One of the most powerful configuration options is theme control. `ZestButton` can automatically adapt to the user's operating system preferences, or you can lock it to a specific theme.
+
+The `theme` prop within the `zest` object accepts one of three values:
+
+-   `'system'` (Default): The button listens for the system's color scheme (`prefers-color-scheme`) and applies the `light` or `dark` theme automatically.
+-   `'light'`: Forces the button to use the light theme, regardless of system settings.
+-   `'dark'`: Forces the button to use the dark theme, regardless of system settings.
+
+#### Order of Precedence
+
+The `zest.theme` prop has the highest precedence.
+
+1.  **`zest.theme` Prop (`light` or `dark`)**: If set, this value is always used.
+2.  **`zest.theme` Prop (`system`)**: If set to `system` (or if undefined), the button will defer to the user's OS-level preference.
+
+#### Example: Forcing a Theme
+
+This is useful for sections of your UI that have a fixed background color, where you need the button's theme to match its immediate parent rather than the overall page theme.
+
+```tsx
+import ZestButton from 'jattac.libs.web.zest-button';
+
+const PinnedFooter = () => (
+  <div style={{ background: '#333', padding: '1rem' }}>
+    {/* This button's text will be light, matching the dark background */}
+    <ZestButton zest={{ theme: 'dark' }}>
+      Action in Dark Footer
+    </ZestButton>
+  </div>
+);
+```
+
+---
+
+### Global Configuration with `ZestProvider`
+
+The `ZestProvider` component is now implemented, allowing you to streamline `ZestButton` configuration across your entire application. You can define a set of default `zest` properties that all `ZestButton` instances within its scope will inherit.
+
+#### Usage
+
+Wrap your application (or specific sections) with the `ZestProvider` and pass a configuration object to its `config` prop. The `config` prop expects an object of type `ZestGlobalConfig`, which contains a `defaultProps` field of type `ZestCustomProps`.
+
+```tsx
+// In your main App.tsx file
+
+import { ZestProvider } from 'jattac.libs.web.zest-button';
+import MyRoutes from './MyRoutes';
+
+const appZestConfig = {
+  defaultProps: {
+    visualOptions: {
+      size: 'sm', // Make all buttons small by default
+    },
+    busyOptions: {
+      minBusyDurationMs: 300, // Shorten the busy duration app-wide
+    },
+  },
+};
+
+const App = () => (
+  <ZestProvider config={appZestConfig}>
+    <MyRoutes />
+  </ZestProvider>
+);
+```
+
+#### Precedence with the `ZestProvider`
+
+Property configurations are merged in a "deep merge" fashion with the following order of precedence (where the last one wins):
+
+1.  **Global `defaultProps`**: Props defined in the `ZestProvider`'s `config.defaultProps` object. This is the base layer of styling.
+2.  **Built-in Semantic Defaults**: The library's own defaults for a given `semanticType` (e.g., the `success` variant for `save`).
+3.  **Custom Semantic Defaults**: **(New!)** Defaults for a `semanticType` that you provide in the `ZestProvider`'s `config.semanticTypeDefaults` object. This allows you to override the library's defaults or create new ones.
+4.  **Local `zest` Props**: The props passed directly to a specific `<ZestButton>` instance. This gives you the ultimate granular control.
+
+---
+
+### Advanced: Customizing Semantic Defaults
+
+This is one of the most powerful features of the `ZestProvider`. You can define application-wide styles and behaviors for any `semanticType`. This is perfect for creating a consistent design system.
+
+The `ZestProvider`'s `config` prop accepts a `semanticTypeDefaults` object. You can use this to **override** built-in defaults or **define** defaults for your own custom types.
+
+#### Example: Defining a Custom 'archive' Type
+
+First, let's imagine you've used module augmentation to create a new `semanticType` called `'archive'`, as explained in the [Development Guide](./development.md). Now, you want all `'archive'` buttons to have a specific look and feel across your app.
+
+```tsx
+// your-project/src/typings/zest-button-extensions.d.ts
+import 'jattac.libs.web.zest-button';
+
+declare module 'jattac.libs.web.zest-button' {
+  export interface CustomZestSemanticTypes {
+    archive: 'archive';
+  }
+}
+```
+
+Now, configure the defaults in your `ZestProvider`:
+
+```tsx
+// In your main App.tsx file
+import { ZestProvider } from 'jattac.libs.web.zest-button';
+import { FaArchive } from 'react-icons/fa';
+import MyRoutes from './MyRoutes';
+
+const appZestConfig = {
+  // Define defaults for our new custom semantic type
+  semanticTypeDefaults: {
+    archive: {
+      buttonStyle: 'outline',
+      visualOptions: {
+        iconLeft: <FaArchive />,
+        variant: 'standard',
+      },
+      confirmOptions: {
+        displayLabel: 'Confirm Archive?',
+        timeoutSecs: 10,
+      }
+    }
+  }
+};
+
+const App = () => (
+  <ZestProvider config={appZestConfig}>
+    <MyRoutes />
+  </ZestProvider>
+);
+
+// --- Later, in some other component ---
+
+// This button will automatically get the icon, style, and confirmation behavior!
+<ZestButton zest={{ semanticType: 'archive' }} onClick={handleArchiveAction}>
+  Archive Record
+</ZestButton>
+```
+
+#### Example: Overriding a Built-in 'delete' Default
+
+Let's say you like the built-in `delete` type, but for your application, you want the button style to be `outline` instead of `solid`, and you want a shorter confirmation time.
+
+```tsx
+// In your main App.tsx file
+import { ZestProvider } from 'jattac.libs.web.zest-button';
+import MyRoutes from './MyRoutes';
+
+const appZestConfig = {
+  // Override specific props for a built-in semantic type
+  semanticTypeDefaults: {
+    delete: {
+      // We only specify what we want to change.
+      // The icon and 'danger' variant will still be inherited from the built-in default.
+      buttonStyle: 'outline',
+      confirmOptions: {
+        // We must provide the full object to override, not just one property.
+        displayLabel: 'Confirm Deletion',
+        timeoutSecs: 3, // Shorter timeout
+      }
+    }
+  }
+};
+
+const App = () => (
+  <ZestProvider config={appZestConfig}>
+    <MyRoutes />
+  </ZestProvider>
+);
+
+// --- Later, in some other component ---
+
+// This button will now be an 'outline' button with a 3-second confirmation.
+<ZestButton zest={{ semanticType: 'delete' }} onClick={handleDeleteAction}>
+  Delete Record
+</ZestButton>
+```
+

package/docs/development.md

@@ -0,0 +1,77 @@
+# Development: The Contributor's Guide
+
+This guide provides an overview of the project's internal structure and instructions for setting up your development environment.
+
+---
+
+### Internal Architecture
+
+The `jattac.libs.web.zest-button` project is structured to be a self-contained React component library.
+
+-   **`UI/ZestButton.tsx`**: This is the heart of the component. It contains the main React functional component, state management logic, event handlers, and renders the button's UI based on its props and internal state. Auxiliary components like `AnimatedCheckmark` and `AnimatedX` are also defined here.
+-   **`UI/SpinnerIcon.tsx`**: A small, dedicated component for rendering the loading spinner, utilizing `react-icons`.
+-   **`Styles/ZestButton.module.css`**: All the CSS for the component is defined in this file. It leverages CSS Modules to ensure styles are scoped and prevent conflicts. It also includes global CSS variables for theming and animations.
+-   **`dist/`**: This directory is the output of the build process. It contains the compiled JavaScript files (CommonJS and ES Modules), the TypeScript declaration file (`index.d.ts`), and potentially source maps. This is the content that gets published to npm.
+-   **`rollup.config.mjs`**: The configuration file for Rollup, the module bundler used for this project. It defines how the TypeScript and CSS are transpiled, bundled, and how the declaration files are generated.
+-   **`tsconfig.json`**: The TypeScript compiler configuration. It specifies compiler options, such as target JavaScript version, module resolution strategy, JSX factory, and files to include/exclude from compilation.
+
+---
+
+### Setup Instructions
+
+To get the development environment running on your local machine, follow these steps:
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/jattac/jattac.libs.web.zest-button.git
+    cd jattac.libs.web.zest-button
+    ```
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+    This command will install all the necessary `devDependencies` listed in `package.json`.
+
+---
+
+### Scripts
+
+The `package.json` includes several scripts to help with development and building the package:
+
+-   **`npm run build`**:
+    *   **Purpose**: Compiles the TypeScript code, processes CSS Modules, and bundles the component into production-ready CommonJS and ES Module formats. It also generates the TypeScript declaration file (`index.d.ts`).
+    *   **Output**: Creates the `dist/` directory with all the necessary files for publishing.
+    *   **Command**: `rollup -c rollup.config.mjs`
+
+-   **`npm run dev`**:
+    *   **Purpose**: Starts Rollup in watch mode. This command is ideal for development as it automatically recompiles the component whenever source files are changed, allowing for rapid iteration.
+    *   **Output**: Similar to `build`, but also keeps the process running to watch for changes.
+    *   **Command**: `rollup -c rollup.config.mjs -w`
+
+---
+
+### Extending Semantic Types
+
+The `ZestButton` provides a mechanism for developers to extend the built-in `SemanticType` union with their own custom semantic types. This is achieved through TypeScript's [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) feature.
+
+To add your own custom semantic types:
+
+1.  Create a TypeScript declaration file in your project (e.g., `your-project/src/typings/zest-button-extensions.d.ts`).
+2.  Augment the `jattac.libs.web.zest-button` module and define your custom semantic types within the `CustomZestSemanticTypes` interface. The keys of this interface will become available as new `SemanticType` values.
+
+```typescript
+// your-project/src/typings/zest-button-extensions.d.ts
+import 'jattac.libs.web.zest-button'; // Important: Extend the module
+
+declare module 'jattac.libs.web.zest-button' {
+  export interface CustomZestSemanticTypes {
+    archive: 'archive';
+    publish: 'publish';
+    // Add any other custom semantic types here
+  }
+}
+```
+
+Once augmented, these new semantic types (`'archive'`, `'publish'`) will be available for autocompletion and type-checking when using the `semanticType` prop on your `ZestButton` instances.
+
+*(Note: Currently, there are no dedicated test scripts defined in `package.json`. Testing is typically done manually in a consuming project during development, or through dedicated test runners that would be added in the future.)*

package/docs/examples.md

@@ -0,0 +1,215 @@
+# 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.
+
+---
+
+### 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 />, fullWidth: 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 { ZestProvider, 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 = () => (
+  <ZestProvider 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>
+  </ZestProvider>
+);
+```
+*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 **`ZestProvider`**.
+
+**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 `ZestProvider` to define the default props for your new `'archive'` type.
+
+```tsx
+// In your main App.tsx
+import React from 'react';
+import { ZestProvider, 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 = () => (
+  <ZestProvider 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>
+  </ZestProvider>
+);
+```
+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).
+