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

package/documentation/api.md

@@ -0,0 +1,165 @@
+---
+[⬅️ 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)
+  - [ZestDropdownOption](#zestdropdownoption)
+
+---
+
+### `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. |
+| `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. |
+
+---
+
+#### `ZestGlobalConfig`
+
+This is the configuration object passed to the `config` prop of the `ZestButtonConfigProvider`.
+
+| 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. |
+| `stretch` | `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.
+
+---
+
+#### `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/documentation/breaking-changes.md

@@ -0,0 +1,143 @@
+---
+[⬅️ 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/documentation/configuration.md

@@ -0,0 +1,214 @@
+---
+[⬅️ 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/documentation/development.md

@@ -0,0 +1,93 @@
+---
+[⬅️ 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)