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

package/docs/guidelines/ai-knowledge.md

@@ -0,0 +1,154 @@
+# AI Knowledge Graph
+
+Purpose:
+
+Maintain a continuously evolving architectural memory of this repository.
+
+This document is not documentation for humans.
+
+It is persistent memory for future AI agents.
+
+---
+
+# Instructions
+
+Every completed task MUST update this file if new knowledge is discovered.
+
+This MUST happen BEFORE implementation and AGAIN after implementation.
+
+---
+
+# Format
+
+Every component entry MUST follow this format:
+
+```
+## [ComponentName]
+
+### Purpose
+[One sentence]
+
+### Location
+[File path]
+
+### Callers
+[List of callers]
+
+### Callees
+[List of callees]
+
+### Dependencies
+[List of dependencies]
+
+### Publishes
+[List of events]
+
+### Consumes
+[List of events]
+
+### Configuration
+[Configuration sources]
+
+### Database
+[Tables, queries]
+
+### Known Invariants
+[Business rules that MUST NOT change]
+
+### Known Pitfall
+[Things easy to break]
+
+### Thread Safety
+[Concurrency considerations]
+
+### Transaction Boundaries
+[Transaction scope]
+
+### Security Assumption
+[Auth assumptions]
+
+### Performance Characteristics
+[Known traits]
+
+### Test Coverage
+[What is tested, what is not]
+```
+
+---
+
+# Entries
+
+<!-- Add component entries below this line -->
+
+## ZestButton dropdown options (split button)
+
+### Purpose
+`zest.dropdownOptions` renders `ZestButton` as a split button: the existing button segment keeps firing its default `onClick` directly, plus a chevron segment that opens a menu of independent secondary actions.
+
+### Location
+`UI/ZestButton.tsx` (additive types + 3 small mandatory edits — see Known Pitfalls), `UI/ZestDropdownMenu.tsx`, `UI/ZestDropdownMenuItem.tsx`, `Styles/ZestButton.module.css` (new rules appended).
+
+### Callers
+Any consumer passing `zest={{ dropdownOptions: [...] }}` to `ZestButton`.
+
+### Callees
+`@radix-ui/react-dropdown-menu` (positioning, dismiss, a11y, keyboard nav — `modal={false}` explicitly, see Known Invariants). Reuses `useBusyState`/`useConfirmation` (one hook instance per menu item, via `ZestDropdownMenuItem`) and `useZestConfig`/`useThemeDetection` (main button, unchanged).
+
+### Dependencies
+`@radix-ui/react-dropdown-menu` (new peer+dev dependency, externalized in `rollup.config.mjs` exactly like `react-icons`).
+
+### Configuration
+`zest.dropdownAriaLabel` (default `"More options"`) — the chevron's accessible name, since it has no visible text.
+
+### Known Invariants
+- `DropdownMenu.Root` **must** stay `modal={false}`. Radix's default (`modal: true`) `aria-hide`s everything outside the menu *including the trigger button itself* while open — wrong for a split button, whose trigger must stay reachable. Discovered via a failing `getByRole` test, not assumed; see decision-log 2026-07-28.
+- The `force-light`/`force-dark` theme class must be applied to **both** the trigger and `DropdownMenu.Content` separately — Radix portals `Content` outside the trigger's DOM subtree, so a theme class scoped only to the trigger never reaches the portaled menu.
+- `ZestButton.tsx`'s render, when `dropdownOptions` is absent/empty, must stay byte-identical to pre-dropdown behavior — enforced by extracting the existing `<button>` JSX into a `buttonElement` const reused in both render branches, and covered by two explicit regression tests in `__tests__/ZestButton.test.tsx`.
+
+### Known Pitfall
+Three lines of *existing* `ZestButton.tsx` logic were deliberately edited (not just added to) for this feature, each BRS-mandated:
+1. `isDisabled` extended with `anyDropdownItemBusy` (whole control disables while any menu item is busy)
+2. The `isDefault` Enter-key `useEffect`'s guard/deps gained `dropdownOpen` (Enter must not re-trigger the main action while the menu is open)
+3. The return statement was restructured (button JSX extracted to a variable) to avoid duplicating markup across the two render paths
+
+All three are no-ops when `dropdownOptions` is absent (the new state variables never leave their default `false`), but any future editor touching `isDisabled` or the `isDefault` effect should know these three lines exist and why.
+
+### Test Coverage
+`__tests__/ZestDropdownMenuItem.test.tsx`, `__tests__/ZestDropdownMenu.test.tsx`, and a `describe("dropdownOptions (split button)")` block in `__tests__/ZestButton.test.tsx`. 81 tests total in the suite (up from 52), 97.21% line coverage (up from 95.38%).
+
+### jsdom/Radix testing gotchas (apply to any future test that opens a ZestButton dropdown)
+- jsdom has **no `PointerEvent` constructor at all**. Radix's `DropdownMenu.Trigger` opens on `pointerdown`, not `click` — a plain `.click()` never opens it. `jest.setup.js` polyfills `window.PointerEvent` plus `Element.prototype.{has,set,release}PointerCapture`/`scrollIntoView`. Tests must dispatch `fireEvent.pointerDown` (+`pointerUp`) on the trigger to open it, not `.click()`.
+- jsdom has no `ResizeObserver` either — also polyfilled in `jest.setup.js` (Radix's Popper-based content measurement needs it).
+- `ZestDropdownMenu`'s `open` prop is fully controlled. A `jest.fn()` passed as `onOpenChange` that doesn't feed back into a real `open` state will never actually open the menu, regardless of whether Radix's internal toggle logic fired correctly — tests asserting the open *result* (not just that the callback fired) need a real state-backed wrapper component.
+
+## Jest test infrastructure
+
+### Purpose
+Test tooling for this repo (a React component library: `UI/`, `Styles/`, built via Rollup) — was entirely absent before 2026-07-28 (`package.json`'s `test` script was a no-op stub, no Jest deps/config existed).
+
+### Location
+`jest.config.js`, `jest.setup.js`, `tsconfig.jest.json` (all repo root). Tests live in `__tests__/`, mirroring `UI/`'s structure (e.g. `__tests__/ZestButton.test.tsx` tests `UI/ZestButton.tsx`; `__tests__/hooks/*.test.ts` test `UI/hooks/*.ts`).
+
+### Callers
+`npm test` (`package.json`), `scripts/verify-post.ps1` (runs `npx jest --coverage --coverageReporters=json-summary` directly, not via the npm script), CI (if/when added — none exists yet).
+
+### Callees
+`ts-jest` (via `tsconfig.jest.json`), `jest-environment-jsdom`, `@testing-library/react`, `@testing-library/jest-dom`, `identity-obj-proxy` (CSS Modules stub).
+
+### Dependencies
+All added as devDependencies only: `jest`, `@types/jest`, `ts-jest`, `jest-environment-jsdom`, `@testing-library/react`, `@testing-library/jest-dom`, `identity-obj-proxy`.
+
+### Configuration
+`coverageReporters: ['json-summary', 'text', 'lcov']` — the `json-summary` entry is load-bearing; `scripts/verify-post.ps1` reads `coverage/coverage-summary.json` directly and fails silently (0% coverage) without it. `coverage/` is gitignored; `test-reports/coverage-baseline.json` is not (intentionally committed, per `AI_TEST_CONFIGURATION.md`).
+
+### Known Invariants
+- Test files MUST NOT live inside `UI/`. `tsconfig.json`'s `include` is `UI/**/*.ts(x)`, and `@rollup/plugin-typescript` (used by `rollup.config.mjs` for the production build) type-checks everything matching that glob — not just files reachable from the `UI/index.ts` entry point. A `*.test.tsx` file co-located inside `UI/` will fail type-check against the production `tsconfig.json` (which has no jest/testing-library ambient types) and pollute `npm run build`'s output with TS diagnostics, even though it's never actually bundled into `dist/`. This was hit and fixed during initial setup (see decision-log 2026-07-28).
+- `tsconfig.jest.json` (not `tsconfig.json`) supplies the `types` compiler option (`jest`, `node`, `@testing-library/jest-dom`) needed for jest-dom's ambient matcher types (`toBeInTheDocument`, etc.) to resolve. A triple-slash `/// <reference types="@testing-library/jest-dom" />` in `global.d.ts` was tried first and did NOT reliably work with this project's Jest 30 / `@types/jest` 30 combination — don't reintroduce that approach without re-verifying it actually resolves.
+- `jest.setup.js` stubs `window.matchMedia` globally (jsdom doesn't implement it) because `UI/hooks/useThemeDetection.ts` calls it unconditionally on every render — any test that renders `ZestButton` (directly or indirectly) will throw `TypeError: window.matchMedia is not a function` without this stub. Individual tests (e.g. `__tests__/hooks/useThemeDetection.test.ts`) may still override `window.matchMedia` locally per-test; that's expected and doesn't conflict (each Jest test *file* gets a fresh jsdom global environment).
+
+### Known Pitfall
+`scripts/verify-pre.ps1` / `scripts/verify-post.ps1` hardcode `$projectRoot` — originally pointed at a `lattice-web-light` subfolder that doesn't exist in this repo (copied from a different project's version of these scripts); fixed 2026-07-28 to `$projectRoot = $repoRoot`. If these scripts are ever copied into yet another repo, check this first.
+
+### Test Coverage
+As of 2026-07-28: 52 tests across 9 suites, covering every file currently in `UI/`'s public surface (`ZestButton.tsx` incl. busy/confirm/keyboard flows, all 4 hooks, `ZestButtonConfigContext.ts`, `ZestButtonConfigProvider.tsx`, `SpinnerIcon.tsx`, `semanticTypeButtonConfigDefaults.tsx`). 95.38% lines / 94.76% statements / 97.36% functions / 85.23% branches. Baseline recorded in `test-reports/coverage-baseline.json`. Superseded by the dropdown-options feature's test additions above (81 tests, 97.21% lines as of the same date).
+

package/docs/guidelines/decision-log.md

@@ -0,0 +1,149 @@
+# Decision Log
+
+Purpose:
+
+Record architectural and implementation decisions for future reference.
+
+This document is not documentation for humans.
+
+It is persistent memory for future AI agents.
+
+---
+
+# Instructions
+
+Every task that involves a decision MUST add an entry.
+
+Entries MUST be added BEFORE implementation begins.
+
+---
+
+# Format
+
+```
+## [YYYY-MM-DD] Decision Title
+
+### Requested
+
+[What the user asked for]
+
+### Options Considered
+
+1. [Option A] — [pros/cons]
+2. [Option B] — [pros/cons]
+3. [Option C] — [pros/cons]
+
+### Chosen
+
+[Which option was chosen]
+
+### Rationale
+
+[Why this option was chosen]
+
+### Trade-offs
+
+[What was sacrificed, what was gained]
+
+### Reversible
+
+[Yes/No — and what it would take to reverse]
+```
+
+---
+
+# Decisions
+
+<!-- Add decision entries below this line -->
+
+## [2026-07-28] Wire up Jest test infrastructure (no prior tests existed)
+
+### Requested
+
+"get jest wired up, no half measures" — this component library had zero test tooling (`package.json`'s `test` script was a no-op stub). Preceded by a session establishing/fixing this repo's BRS-gated AI workflow (fixed `scripts/verify-pre.ps1`/`verify-post.ps1`'s hardcoded `lattice-web-light` project path, confirmed throughout that `git remote.origin.url` was never at risk from any of it). Full scope: `BRS.md` (repo root).
+
+### Options Considered
+
+1. `ts-jest` vs `babel-jest` for TS transform — chosen `ts-jest`: this project is TypeScript-first with no Babel config anywhere (Rollup build uses `@rollup/plugin-typescript` directly), so `ts-jest` matches the existing toolchain rather than introducing a second transform pipeline.
+2. Test file location: co-located next to source (as originally drafted in the BRS) vs. a separate `__tests__/` tree — co-location was tried first and reverted. `tsconfig.json`'s `include: ["UI/**/*.ts", "UI/**/*.tsx", ...]` is read by `@rollup/plugin-typescript` for type-check diagnostics on `npm run build`, not just for what actually gets bundled from the `UI/index.ts` entry graph — a co-located `*.test.tsx` file failed type-check against the production tsconfig (no jest/testing-library types there) and polluted the build output with TS diagnostics. Moved all test files to `__tests__/`, mirroring `UI/`'s structure, rather than modifying `tsconfig.json` (explicitly out of scope per the BRS).
+3. jest-dom matcher types: triple-slash `/// <reference types="@testing-library/jest-dom" />` in `global.d.ts` vs. a dedicated `tsconfig.jest.json` with an explicit `types` compiler option — the triple-slash approach didn't work reliably against this project's Jest 30 / `@types/jest` 30 combination (TS resolved `expect()`'s return type without ever merging in jest-dom's `Matchers` interface augmentation). Chose the dedicated `tsconfig.jest.json` (extends `tsconfig.json`, adds `types: ["jest","node","@testing-library/jest-dom"]`), used only via `jest.config.js`'s `transform` option — production `tsconfig.json` stays untouched.
+4. Scope of tests written: minimal smoke tests vs. full behavioral coverage of the current public surface — chosen full coverage (all 4 hooks, config context/provider, `SpinnerIcon`, `semanticTypeButtonConfigDefaults`, and the complete `ZestButton` component including busy/confirm/keyboard-Enter flows), per the user's explicit "no half measures" and the global TDD rule to freeze existing behaviour with real tests, not placeholders.
+
+### Chosen
+
+Options 1, 2 (the `__tests__/` variant), 3 (the `tsconfig.jest.json` variant), and 4 (full coverage) — all as amended in `BRS.md`'s "Amendments during implementation" section.
+
+### Rationale
+
+Each deviation from the original BRS draft was discovered empirically (by actually running `npm run build` and the test suite, not assumed) and fixed with the smallest change that didn't touch files explicitly marked out-of-scope (`tsconfig.json`).
+
+### Trade-offs
+
+`tsconfig.jest.json` is a second TypeScript config file to keep in sync conceptually with `tsconfig.json` (it `extends` it, so most drift risk is limited to the `types` array and `include` list). Test files living in `__tests__/` rather than beside their source is a minor discoverability cost, offset by avoiding any change to the production build's type-checking surface.
+
+### Reversible
+
+Yes — every changed/added file is listed in `test-reports/CHANGE_MANIFEST_jest-wiring.md`. No file under `UI/`/`Styles/` (production source) was touched. Revert by removing the new devDependencies, `jest.config.js`, `jest.setup.js`, `tsconfig.jest.json`, `__tests__/`, `BRS.md`, and the `coverage/` line in `.gitignore`, and restoring `package.json`'s `test` script.
+
+## [2026-07-28] ZestButton dropdown options (split button), via @radix-ui/react-dropdown-menu
+
+### Requested
+
+"make the button support dropdown options so that in instances where a button may be used for a default action and optional others, then we show in ui that this is possible and provide a hit area to bring up option." Clicking the main segment always fires the default action directly; each dropdown item independent but DRY as possible; mobile-first, desktop-aware; full a11y; leverage a headless menu library if one fits, to avoid hand-rolling popup positioning. Full scope: `docs/features/zest-button-dropdown-options/BRS.md`.
+
+### Options Considered
+
+1. Reuse the sibling repo `jattac.Libs.Web.OverflowMenu` (`D:\work\nyingi\code\systems\jattac-web-libs\jattac.Libs.Web.OverflowMenu`) directly — rejected. Its trigger is a fixed 48×48 circular "kebab" icon-button with hover styling hardcoded via Framer Motion **inline styles** (`whileHover={{ color: '#016a80', ... }}`), which cannot be overridden by external CSS — no way to theme it into ZestButton's variant/dark-mode system without forking. It's also architecturally a standalone floating "more actions" button, not a chevron segment meant to fuse onto another button, and its `src/index.tsx` doesn't export the internals (`MenuRow`, the Radix wiring) separately, so there's no seam to reuse just the mechanics.
+2. `@floating-ui/react` (generic positioning + a-la-carte interaction hooks) — viable, but a lower-level primitive than needed; would mean hand-assembling menu semantics (roles, type-ahead, keyboard nav) that a menu-specific library already provides.
+3. `@radix-ui/react-dropdown-menu`, used directly (not via `OverflowMenu`'s wrapper) — chosen. Same package `OverflowMenu` already depends on in production (proven in this org already), but consumed via its `asChild` composition model so ZestButton drives its own trigger element and full styling, inheriting only positioning/dismiss/a11y/keyboard-nav mechanics. No Framer Motion needed — CSS-only transitions match this repo's existing animation approach.
+
+### Chosen
+
+Option 3.
+
+### Rationale
+
+`asChild` composition is the deciding factor: it gets the exact same battle-tested Radix positioning/a11y engine `OverflowMenu` already uses in this org, without inheriting that component's fixed skin, Framer Motion dependency, or lack of theme/variant props.
+
+### Trade-offs (each found empirically while implementing, not guessed — see `test-reports/CHANGE_MANIFEST_dropdown-options.md` and `docs/guidelines/ai-knowledge.md`'s "ZestButton dropdown options" entry for detail)
+
+- Radix's `DropdownMenu.Root` defaults to `modal: true`, which `aria-hide`s the trigger itself while its own menu is open — wrong for a split button; explicitly set `modal={false}`.
+- Radix portals `DropdownMenu.Content` outside the trigger's DOM subtree, so a theme-override class scoped only to the trigger doesn't reach it — applied the theme class to both.
+- jsdom has no `PointerEvent` constructor at all, and Radix's trigger opens on `pointerdown` not `click` — required three jsdom polyfills in `jest.setup.js` (`PointerEvent`, pointer-capture methods, `scrollIntoView`).
+- First full test run showed a real aggregate coverage regression (95.38% → 95.12%) even though all new code was well-tested — a large, decently-but-not-perfectly-covered addition dilutes a weighted-average baseline. Fixed by adding 8 more targeted tests (3 of them for **pre-existing, untouched** `ZestButton.tsx` branches that happened to be uncovered already) rather than treating the dip as acceptable noise, since `AI_TESTING.md` has zero tolerance for any regression.
+
+### Reversible
+
+Yes — no file under `UI/`/`Styles/` had an *existing* line rewritten, only 3 small, explicitly BRS-mandated additions to existing conditions (see `ai-knowledge.md`'s "Known Pitfall" entry for exactly which 3 lines and why). Full file list in `test-reports/CHANGE_MANIFEST_dropdown-options.md`.
+
+## [2026-07-28] Fix verify-post.ps1 silently skipping BRS compliance; align verify-pre.ps1's approval regex
+
+### Requested
+
+User noticed `verify-post.ps1`'s report looked "ok with there not being a BRS" and asked why that wasn't flagged as an issue.
+
+### Options Considered
+
+1. Leave it — the caller is expected to always pass `-BRSPath` — rejected, since nothing enforces that, and the whole point of this phase is to catch exactly this kind of omission.
+2. Auto-discover the most-recently-modified `BRS.md` when `-BRSPath` isn't passed (mirroring `verify-pre.ps1`'s existing Phase 1 logic exactly), and make "no BRS found" or "found but not approved" a `FAIL`, never a silent `SKIPPED` — chosen.
+
+### Chosen
+
+Option 2, applied to `verify-post.ps1`'s Phase 3.
+
+### Rationale
+
+A script whose entire purpose is enforcing this repo's BRS-gated policy must never be able to report `RESULT: COMPLETE` while staying silent about BRS compliance just because an optional parameter was omitted. `verify-pre.ps1` already had the correct auto-discovery pattern; `verify-post.ps1` just never reused it.
+
+### Also found and fixed while testing this change
+
+Both scripts' approval-detection regex only recognized `Status: Approved` (or the equivalent markdown-table row), not `Status: Complete` — even though `AI_BRS.md`'s own template defines `Complete` as a later, valid lifecycle stage that can only be reached *after* approval. Running the fixed `verify-post.ps1` against this session's own (by-then-`Complete`) BRS immediately exposed this as a false negative. Fixed both scripts' regexes to accept either value.
+
+### Trade-offs
+
+None identified — this only makes both scripts stricter/more accurate, never looser.
+
+### Reversible
+
+Yes — confined to `scripts/verify-pre.ps1`'s Phase 1 and `scripts/verify-post.ps1`'s Phase 3 regex/discovery logic.
+

package/package.json

@@ -1,69 +1,78 @@
-{
-  "name": "jattac.libs.web.zest-button",
-  "version": "1.2.9",
-  "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": {
-    "type": "git",
-    "url": "git+https://github.com/nyingimaina/jattac.libs.web.zest-button.git"
-  },
-  "bugs": {
-    "url": "https://github.com/nyingimaina/jattac.libs.web.zest-button/issues"
-  },
-  "main": "dist/index.cjs.js",
-  "module": "dist/index.esm.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md",
-    "docs"
-  ],
-  "scripts": {
-    "build": "rollup -c rollup.config.mjs",
-    "dev": "rollup -c rollup.config.mjs -w",
-    "test": "echo \"No tests specified. See WORKPLAN.md for future plans.\" && exit 0"
-  },
-  "keywords": [
-    "react",
-    "button",
-    "ui",
-    "component",
-    "interactive",
-    "react-button",
-    "form",
-    "web",
-    "async",
-    "loading",
-    "confirmation",
-    "feedback",
-    "animation",
-    "transitions",
-    "ux",
-    "zest",
-    "jattac"
-  ],
-  "author": "Jattac",
-  "license": "MIT",
-  "peerDependencies": {
-    "react": ">=16.8.0",
-    "react-dom": ">=16.8.0",
-    "react-icons": "^5.0.1"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-typescript": "^11.1.6",
-    "@types/node": "^25.1.0",
-    "@types/react": "^18.2.67",
-    "@types/react-dom": "^18.2.22",
-    "postcss": "^8.4.38",
-    "postcss-modules": "6.0.1",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "rollup": "^4.13.0",
-    "rollup-plugin-dts": "^6.1.0",
-    "rollup-plugin-postcss": "^4.0.2",
-    "tslib": "^2.6.2",
-    "typescript": "^5.4.2"
-  }
-}
+{
+  "name": "jattac.libs.web.zest-button",
+  "version": "1.4.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/nyingimaina/jattac.libs.web.zest-button.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nyingimaina/jattac.libs.web.zest-button/issues"
+  },
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "rollup -c rollup.config.mjs",
+    "dev": "rollup -c rollup.config.mjs -w",
+    "test": "jest --coverage"
+  },
+  "keywords": [
+    "react",
+    "button",
+    "ui",
+    "component",
+    "interactive",
+    "react-button",
+    "form",
+    "web",
+    "async",
+    "loading",
+    "confirmation",
+    "feedback",
+    "animation",
+    "transitions",
+    "ux",
+    "zest",
+    "jattac"
+  ],
+  "author": "Jattac",
+  "license": "MIT",
+  "peerDependencies": {
+    "@radix-ui/react-dropdown-menu": "^2.1.24",
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0",
+    "react-icons": "^5.0.1"
+  },
+  "devDependencies": {
+    "@radix-ui/react-dropdown-menu": "^2.1.24",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.1.0",
+    "@types/react": "^18.2.67",
+    "@types/react-dom": "^18.2.22",
+    "identity-obj-proxy": "^3.0.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
+    "postcss": "^8.4.38",
+    "postcss-modules": "6.0.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rollup": "^4.13.0",
+    "rollup-plugin-dts": "^6.1.0",
+    "rollup-plugin-postcss": "^4.0.2",
+    "ts-jest": "^29.4.12",
+    "tslib": "^2.6.2",
+    "typescript": "^5.4.2"
+  }
+}

package/dist/ZestContext.d.ts

@@ -1,9 +0,0 @@
-import React from 'react';
-import { ZestCustomProps } from './ZestButton';
-export interface ZestGlobalConfig {
-    defaultProps?: ZestCustomProps;
-    semanticTypeDefaults?: Partial<Record<string, Partial<ZestCustomProps>>>;
-}
-declare const ZestContext: React.Context<ZestGlobalConfig | undefined>;
-export declare const useZest: () => ZestGlobalConfig | undefined;
-export default ZestContext;

package/dist/ZestProvider.d.ts

@@ -1,8 +0,0 @@
-import React from 'react';
-import { ZestGlobalConfig } from './ZestContext';
-interface ZestProviderProps {
-    config: ZestGlobalConfig;
-    children: React.ReactNode;
-}
-declare const ZestProvider: React.FC<ZestProviderProps>;
-export default ZestProvider;

package/dist/semanticTypeDefaults.d.ts

@@ -1,4 +0,0 @@
-import { ZestCustomProps } from './ZestButton';
-type SemanticTypeDefaultsMap = Partial<Record<string, Partial<ZestCustomProps>>>;
-export declare const semanticTypeDefaults: SemanticTypeDefaultsMap;
-export {};

package/docs/api.md

@@ -1,140 +0,0 @@
----
-[⬅️ 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`.
-
-| 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 `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.
-
----
-
-[⬅️ Previous: Features Showcase](./features.md) | [Next: Configuration Guide ➡️](./configuration.md)