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

package/docs/breaking-changes.md

@@ -1,143 +0,0 @@
----
-[⬅️ Previous: Development Guide](./development.md)
-
-# Breaking Changes: The Upgrade Path
-
-This document lists significant changes between versions that might require modifications to your existing codebase.
-
----
-
-## Table of Contents
-
-- [Version 1.2.7](#version-127)
-- [Version 1.2.6](#version-126)
-- [Version 1.2.0](#version-120)
-
----
-
-## Version 1.2.7
-
-### Renamed `ZestProvider` to `ZestButtonConfigProvider`
-
-To provide more explicit naming and better context within the API, the `ZestProvider` component has been renamed to `ZestButtonConfigProvider`. Additionally, its associated context is now `ZestButtonConfigContext`, and the consumption hook is `useZestButtonConfig`.
-
-This is a breaking change that requires updating all imports and usages of the provider, context, and hook in your application.
-
-**Before:**
-
-```tsx
-import { ZestProvider, useZest } from 'jattac.libs.web.zest-button';
-
-const App = () => (
-  <ZestProvider config={myConfig}>...</ZestProvider>
-);
-
-const MyComponent = () => {
-  const config = useZest();
-  // ...
-}
-```
-
-**After:**
-
-```tsx
-import { ZestButtonConfigProvider, useZestButtonConfig } from 'jattac.libs.web.zest-button';
-
-const App = () => (
-  <ZestButtonConfigProvider config={myConfig}>...</ZestButtonConfigProvider>
-);
-
-const MyComponent = () => {
-  const config = useZestButtonConfig();
-  // ...
-}
-```
-
----
-
-## Version 1.2.6
-
-### Renamed `fullWidth` prop to `stretch`
-
-To better reflect its behavior and avoid potential confusion with other layout properties, the `fullWidth` prop within `visualOptions` has been renamed to `stretch`. This means any usage of `fullWidth` in your `ZestButton` configurations must be updated.
-
-**Before:**
-
-```tsx
-<ZestButton
-  zest={{
-    visualOptions: {
-      fullWidth: true,
-    },
-  }}
->
-  Stretched Button
-</ZestButton>
-```
-
-**After:**
-
-```tsx
-<ZestButton
-  zest={{
-    visualOptions: {
-      stretch: true,
-    },
-  }}
->
-  Stretched Button
-</ZestButton>
-```
-
----
-
-## 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>
-```
-
----
-
-[⬅️ Previous: Development Guide](./development.md) | [Next: README ➡️](../README.md)

package/docs/configuration.md

@@ -1,214 +0,0 @@
----
-[⬅️ Previous: API Reference](./api.md)
-
-# Configuration: The Control Panel
-
-This document explains how to configure `ZestButton` on a component and global level.
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Theme Configuration](#theme-configuration)
-  - [Order of Precedence](#order-of-precedence)
-  - [Example: Forcing a Theme](#example-forcing-a-theme)
-- [Global Configuration with ZestButtonConfigProvider](#global-configuration-with-zestbuttonconfigprovider)
-  - [Usage](#usage)
-  - [Precedence with the ZestButtonConfigProvider](#precedence-with-the-zestbuttonconfigprovider)
-- [Advanced: Customizing Semantic Defaults](#advanced-customizing-semantic-defaults)
-  - [Example: Defining a Custom 'archive' Type](#example-defining-a-custom-archive-type)
-  - [Example: Overriding a Built-in 'delete' Default](#example-overriding-a-built-in-delete-default)
-
----
-
-### 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 `ZestButtonConfigProvider`
-
-The `ZestButtonConfigProvider` 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 `ZestButtonConfigProvider` 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 { ZestButtonConfigProvider } 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 = () => (
-  <ZestButtonConfigProvider config={appZestConfig}>
-    <MyRoutes />
-  </ZestButtonConfigProvider>
-);
-```
-
-#### Precedence with the `ZestButtonConfigProvider`
-
-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 `ZestButtonConfigProvider`'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 `ZestButtonConfigProvider`'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 `ZestButtonConfigProvider`. You can define application-wide styles and behaviors for any `semanticType`. This is perfect for creating a consistent design system.
-
-The `ZestButtonConfigProvider`'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 `ZestButtonConfigProvider`:
-
-```tsx
-// In your main App.tsx file
-import { ZestButtonConfigProvider } 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 = () => (
-  <ZestButtonConfigProvider config={appZestConfig}>
-    <MyRoutes />
-  </ZestButtonConfigProvider>
-);
-
-// --- 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 { ZestButtonConfigProvider } 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 = () => (
-  <ZestButtonConfigProvider config={appZestConfig}>
-    <MyRoutes />
-  </ZestButtonConfigProvider>
-);
-
-// --- 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>
-```
-
----
-
-[⬅️ Previous: API Reference](./api.md) | [Next: Development Guide ➡️](./development.md)
-

package/docs/development.md

@@ -1,93 +0,0 @@
----
-[⬅️ Previous: Configuration Guide](./configuration.md)
-
-# Development: The Contributor's Guide
-
-This guide provides an overview of the project's internal structure and instructions for setting up your development environment.
-
----
-
-## Table of Contents
-
-- [Internal Architecture](#internal-architecture)
-- [Setup Instructions](#setup-instructions)
-- [Scripts](#scripts)
-- [Extending Semantic Types](#extending-semantic-types)
-
----
-
-### 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.)*
-
----
-
-[⬅️ Previous: Configuration Guide](./configuration.md) | [Next: Breaking Changes ➡️](./breaking-changes.md)

package/docs/examples.md

@@ -1,227 +0,0 @@
-# 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 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).*
-
----
-
-[⬅️ Previous: README](../README.md) | [Next: Features Showcase ➡️](./features.md)