jattac.libs.web.zest-button 1.2.6 → 1.2.8

package/docs/api.md

@@ -1,9 +1,26 @@
+---
+[⬅️ Previous: Features Showcase](./features.md)
+
 # API Reference: The Technical Blueprint
 
 This document provides an exhaustive reference for all `ZestButton` props and type definitions.
 
 ---
 
+## Table of Contents
+
+- [ZestButtonProps](#zestbuttonprops)
+- [Type Definitions](#type-definitions)
+  - [ZestCustomProps](#zestcustomprops)
+  - [ZestGlobalConfig](#zestglobalconfig)
+  - [VisualOptions](#visualoptions)
+  - [BusyOptions](#busyoptions)
+  - [SuccessOptions](#successoptions)
+  - [ConfirmOptions](#confirmoptions)
+  - [SemanticType](#semantictype)
+
+---
+
 ### `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`.
@@ -38,7 +55,7 @@ This is the main configuration object passed to the `zest` prop.
 
 #### `ZestGlobalConfig`
 
-This is the configuration object passed to the `config` prop of the `ZestProvider`.
+This is the configuration object passed to the `config` prop of the `ZestButtonConfigProvider`.
 
 | Prop Name | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
@@ -117,3 +134,7 @@ declare module 'jattac.libs.web.zest-button' {
 }
 ```
 After augmentation, `'archive'` and `'publish'` would be valid `SemanticType` values, available for autocompletion and type-checking.
+
+---
+
+[⬅️ Previous: Features Showcase](./features.md) | [Next: Configuration Guide ➡️](./configuration.md)

package/docs/breaking-changes.md

@@ -1,9 +1,60 @@
+---
+[⬅️ 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`
@@ -86,3 +137,7 @@ This change allows for better organization of configuration options (e.g., `visu
   My Button
 </ZestButton>
 ```
+
+---
+
+[⬅️ Previous: Development Guide](./development.md) | [Next: README ➡️](../README.md)

package/docs/configuration.md

@@ -1,9 +1,27 @@
+---
+[⬅️ 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.
@@ -48,18 +66,18 @@ const PinnedFooter = () => (
 
 ---
 
-### Global Configuration with `ZestProvider`
+### Global Configuration with `ZestButtonConfigProvider`
 
-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.
+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 `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`.
+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 { ZestProvider } from 'jattac.libs.web.zest-button';
+import { ZestButtonConfigProvider } from 'jattac.libs.web.zest-button';
 import MyRoutes from './MyRoutes';
 
 const appZestConfig = {
@@ -74,28 +92,28 @@ const appZestConfig = {
 };
 
 const App = () => (
-  <ZestProvider config={appZestConfig}>
+  <ZestButtonConfigProvider config={appZestConfig}>
     <MyRoutes />
-  </ZestProvider>
+  </ZestButtonConfigProvider>
 );
 ```
 
-#### Precedence with the `ZestProvider`
+#### 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 `ZestProvider`'s `config.defaultProps` object. This is the base layer of styling.
+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 `ZestProvider`'s `config.semanticTypeDefaults` object. This allows you to override the library's defaults or create new ones.
+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 `ZestProvider`. You can define application-wide styles and behaviors for any `semanticType`. This is perfect for creating a consistent design system.
+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 `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.
+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
 
@@ -112,11 +130,11 @@ declare module 'jattac.libs.web.zest-button' {
 }
 ```
 
-Now, configure the defaults in your `ZestProvider`:
+Now, configure the defaults in your `ZestButtonConfigProvider`:
 
 ```tsx
 // In your main App.tsx file
-import { ZestProvider } from 'jattac.libs.web.zest-button';
+import { ZestButtonConfigProvider } from 'jattac.libs.web.zest-button';
 import { FaArchive } from 'react-icons/fa';
 import MyRoutes from './MyRoutes';
 
@@ -138,9 +156,9 @@ const appZestConfig = {
 };
 
 const App = () => (
-  <ZestProvider config={appZestConfig}>
+  <ZestButtonConfigProvider config={appZestConfig}>
     <MyRoutes />
-  </ZestProvider>
+  </ZestButtonConfigProvider>
 );
 
 // --- Later, in some other component ---
@@ -157,7 +175,7 @@ Let's say you like the built-in `delete` type, but for your application, you wan
 
 ```tsx
 // In your main App.tsx file
-import { ZestProvider } from 'jattac.libs.web.zest-button';
+import { ZestButtonConfigProvider } from 'jattac.libs.web.zest-button';
 import MyRoutes from './MyRoutes';
 
 const appZestConfig = {
@@ -177,9 +195,9 @@ const appZestConfig = {
 };
 
 const App = () => (
-  <ZestProvider config={appZestConfig}>
+  <ZestButtonConfigProvider config={appZestConfig}>
     <MyRoutes />
-  </ZestProvider>
+  </ZestButtonConfigProvider>
 );
 
 // --- Later, in some other component ---
@@ -190,3 +208,7 @@ const App = () => (
 </ZestButton>
 ```
 
+---
+
+[⬅️ Previous: API Reference](./api.md) | [Next: Development Guide ➡️](./development.md)
+

package/docs/development.md

@@ -1,9 +1,21 @@
+---
+[⬅️ 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.
@@ -75,3 +87,7 @@ declare module 'jattac.libs.web.zest-button' {
 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

@@ -4,6 +4,15 @@ Welcome to the ZestButton Cookbook! This is the core learning path for mastering
 
 ---
 
+## 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.
@@ -108,7 +117,7 @@ const DeleteButton = () => {
 ```tsx
 // In your main App.tsx
 import React from 'react';
-import { ZestProvider, ZestButton } from 'jattac.libs.web.zest-button';
+import { ZestButtonConfigProvider, ZestButton } from 'jattac.libs.web.zest-button';
 
 const appZestConfig = {
   defaultProps: {
@@ -120,7 +129,7 @@ const appZestConfig = {
 };
 
 const App = () => (
-  <ZestProvider config={appZestConfig}>
+  <ZestButtonConfigProvider config={appZestConfig}>
     <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
       <ZestButton>I'm a small outline button</ZestButton>
       <ZestButton>So am I</ZestButton>
@@ -128,7 +137,7 @@ const App = () => (
         I'm a large solid button! (Local override)
       </ZestButton>
     </div>
-  </ZestProvider>
+  </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).*
@@ -141,7 +150,7 @@ const 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`**.
+**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.
@@ -161,12 +170,12 @@ declare module 'jattac.libs.web.zest-button' {
 *(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.
+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 { ZestProvider, ZestButton } from 'jattac.libs.web.zest-button';
+import { ZestButtonConfigProvider, ZestButton } from 'jattac.libs.web.zest-button';
 import { FaArchive } from 'react-icons/fa';
 
 const appZestConfig = {
@@ -191,7 +200,7 @@ const appZestConfig = {
 };
 
 const App = () => (
-  <ZestProvider config={appZestConfig}>
+  <ZestButtonConfigProvider config={appZestConfig}>
     <div style={{ display: 'flex', gap: '1rem' }}>
         {/* 3. Now just use it! */}
         <ZestButton 
@@ -208,8 +217,11 @@ const App = () => (
           Delete
         </ZestButton>
     </div>
-  </ZestProvider>
+  </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).
+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)

package/docs/features.md

@@ -4,6 +4,16 @@ This document provides a high-level showcase of what's possible with `ZestButton
 
 ---
 
+## 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)
+
+---
+
 ### Asynchronous Operations & Feedback
 
 **What it does:** Automatically handles loading states and provides clear success/failure feedback for any action that returns a Promise.
@@ -81,9 +91,9 @@ const appZestConfig = {
 };
 
 const App = () => (
-  <ZestProvider config={appZestConfig}>
+  <ZestButtonConfigProvider config={appZestConfig}>
     {/* All buttons inside will be small and outline by default */}
-  </ZestProvider>
+  </ZestButtonConfigProvider>
 );
 ```
 *__Learn more in the [Standardizing Your Buttons recipe](./examples.md#recipe-3-standardizing-your-buttons-with-a-global-config).__*
@@ -100,7 +110,7 @@ const MyComponent = () => (
     <ZestButton zest={{ visualOptions: { variant: 'success', size: 'sm' } }}>
       Small Success
     </ZestButton>
-    <ZestButton zest={{ buttonStyle: 'outline', size: 'md' } }}>
+    <ZestButton zest={{ buttonStyle: 'outline', size: 'md' }}>
       Medium Outline
     </ZestButton>
     <ZestButton zest={{ visualOptions: { variant: 'danger', size: 'lg' } }}>
@@ -111,3 +121,6 @@ const MyComponent = () => (
 ```
 *Explore all the recipes in the **[Cookbook](./examples.md)** to see these options in action.*
 
+---
+
+[⬅️ 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.2.6",
+  "version": "1.2.8",
   "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": {