@phcdevworks/spectre-ui 1.8.0 → 2.0.0

package/CHANGELOG.md

@@ -6,6 +6,98 @@ reflects package releases published to npm.
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-06-17
+
+Release Title: Token 3 Alignment
+
+Contract change type: breaking
+
+### Changed
+
+- **Token Alignment**: Updated `@phcdevworks/spectre-tokens` dependency to
+  `^3.0.0` and refreshed lockfile metadata against the latest published token
+  package. This is a major release because the upstream token package moved to
+  a breaking `3.0.0` contract.
+- **Avatar Surface Role**: Updated Avatar background role mappings from the
+  removed upstream `--sp-surface-alternate` token to
+  `--sp-surface-subtle`, preserving the existing Avatar class and recipe
+  contract while matching the v3 token surface.
+- **Release Readiness**: Updated package manager and development dependency
+  metadata, including the `esbuild` override and allowed script entry required
+  by the refreshed build stack.
+- **Roadmap Accuracy**: Corrected the token-gap notes in `TODO.md` after
+  verifying the published `@phcdevworks/spectre-tokens@3.0.0` package: link,
+  interactive surface state, and divider tokens remain blocked.
+
+## [1.9.0] - 2026-06-10
+
+Release Title: Component Recipe Expansion
+
+Contract change type: additive
+
+### Added
+
+- **Nav Recipe**: Added `getNavClasses`, `getNavLinksClasses`, and
+  `getNavLinkClasses` recipes plus `.sp-nav`, `.sp-nav__links`, and
+  `.sp-nav__link` CSS in `src/styles/components.css`. Consumes the new
+  `component.nav` tokens (`nav.bg`, `nav.text`, `nav.link`, `nav.linkHover`,
+  `nav.linkActive`, `nav.border`) published in
+  `@phcdevworks/spectre-tokens@2.9.0`. `getNavClasses` supports `bordered`,
+  `sticky`, and `fullWidth`; `getNavLinkClasses` supports `active`, `disabled`,
+  `hovered`, and `focused`. This is the first of the five Phase 4 component
+  recipes in `TODO.md`. Raised the `components.css` size budget in
+  `tests/css-entrypoints.test.ts` from 92000 to 96000 bytes.
+
+- **Toast Recipe**: Added `getToastClasses` and `getToastIconClasses` recipes
+  plus `.sp-toast` and `.sp-toast__icon` CSS in `src/styles/components.css`.
+  Consumes the new `component.toast` tokens (`toast.{success,warning,danger,info}.{bg,text,border,icon}`)
+  published in `@phcdevworks/spectre-tokens@2.9.0`. `getToastClasses` supports
+  `info`, `success`, `warning`, and `danger` variants plus `dismissed` and
+  `fullWidth`; `getToastIconClasses` mirrors the same variants for icon color.
+  This is the second of the five Phase 4 component recipes in `TODO.md`.
+  Raised the `components.css` size budget in `tests/css-entrypoints.test.ts`
+  from 96000 to 100000 bytes.
+
+- **Tooltip Recipe**: Added `getTooltipClasses` recipe plus `.sp-tooltip` CSS
+  in `src/styles/components.css`. Consumes the new `component.tooltip` tokens
+  (`tooltip.bg`, `tooltip.text`, `tooltip.border`) along with the existing
+  `--sp-opacity-tooltip` and `--sp-z-index-tooltip` primitives published in
+  `@phcdevworks/spectre-tokens@2.9.0`. `getTooltipClasses` supports `top`,
+  `bottom`, `left`, and `right` placements plus a `visible` flag. This is the
+  third of the five Phase 4 component recipes in `TODO.md`.
+
+- **Dropdown Recipe**: Added `getDropdownClasses`, `getDropdownMenuClasses`,
+  and `getDropdownItemClasses` recipes plus `.sp-dropdown`,
+  `.sp-dropdown__menu`, and `.sp-dropdown__item` CSS in
+  `src/styles/components.css`. Consumes the new `component.dropdown` tokens
+  (`dropdown.bg`, `dropdown.border`, `dropdown.item.default`,
+  `dropdown.item.hover`, `dropdown.item.active`, `dropdown.item.text`)
+  published in `@phcdevworks/spectre-tokens@2.9.0`. `getDropdownClasses`
+  supports `fullWidth`; `getDropdownMenuClasses` supports `bottom-start`,
+  `bottom-end`, `top-start`, and `top-end` placements plus an `open` flag;
+  `getDropdownItemClasses` supports `active`, `disabled`, `hovered`, and
+  `focused`. This is the fourth of the five Phase 4 component recipes in
+  `TODO.md`. Raised the `components.css` size budget in
+  `tests/css-entrypoints.test.ts` from 100000 to 105000 bytes.
+
+- **Modal Recipe**: Added `getModalClasses` and `getModalOverlayClasses`
+  recipes plus `.sp-modal` and `.sp-modal-overlay` CSS in
+  `src/styles/components.css`. Consumes the new `component.modal` tokens
+  (`modal.bg`, `modal.shadow`, `modal.border`, `modal.overlay`) along with the
+  existing `--sp-z-index-modal` primitive published in
+  `@phcdevworks/spectre-tokens@2.9.0`. `getModalClasses` supports `open` and
+  `fullWidth`; `getModalOverlayClasses` supports `open`. This is the fifth and
+  final of the five Phase 4 component recipes in `TODO.md`.
+
+### Changed
+
+- **Token Alignment**: Updated `@phcdevworks/spectre-tokens` dependency to
+  `^2.9.0`. The published bundle now carries the five Phase 4 `component.*`
+  token groups (`nav`, `toast`, `tooltip`, `dropdown`, `modal`) for light and
+  dark modes, unblocking the matching recipe work in `TODO.md`. Raised the
+  `components.css` size budget in `tests/css-entrypoints.test.ts` from 88000 to
+  92000 bytes to account for the additional bundled token variables.
+
 ## [1.8.0] - 2026-06-07
 
 Release Title: Spinner Contract and Token Focus Alignment

package/README.md

@@ -1,5 +1,37 @@
 # @phcdevworks/spectre-ui
 
+## Repository Snapshot
+
+| Field | Value |
+|-------|-------|
+| Project team | `project-design` |
+| Repository role | Spectre L2 CSS, Tailwind, and recipe contract |
+| Package/artifact | `@phcdevworks/spectre-ui` |
+| Current version/status | 2.0.0 |
+
+## Standard Workflow
+
+1. Read [AGENTS.md](AGENTS.md), then the agent-specific guide for the task.
+2. Check [TODO.md](TODO.md) and [ROADMAP.md](ROADMAP.md) for current scope.
+3. Make the smallest repo-local change that satisfies the task.
+4. Run `npm run check` when validation is required or practical.
+5. Update docs and [CHANGELOG.md](CHANGELOG.md) only when behavior, public
+   contracts, or release-relevant metadata changed.
+
+## Documentation Map
+
+| Guide | Path |
+|-------|------|
+| Agent rules | [AGENTS.md](AGENTS.md) |
+| Claude Code | [CLAUDE.md](CLAUDE.md) |
+| Codex | [CODEX.md](CODEX.md) |
+| Copilot | [COPILOT.md](COPILOT.md) |
+| Jules | [JULES.md](JULES.md) |
+| Roadmap | [ROADMAP.md](ROADMAP.md) |
+| Todo | [TODO.md](TODO.md) |
+| Changelog | [CHANGELOG.md](CHANGELOG.md) |
+| Security | [SECURITY.md](SECURITY.md) |
+
 [![npm version](https://img.shields.io/npm/v/@phcdevworks/spectre-ui)](https://www.npmjs.com/package/@phcdevworks/spectre-ui)
 [![CI](https://github.com/phcdevworks/spectre-ui/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/phcdevworks/spectre-ui/actions/workflows/ci.yml)
 [![License](https://img.shields.io/npm/l/@phcdevworks/spectre-ui)](LICENSE)
@@ -237,6 +269,11 @@ All options are optional and fall back to sensible defaults.
 | Avatar      | `getAvatarClasses`      | —                                                                                                              | `sm` `md` `lg` `xl` | shape: `circle` `square`                                                |
 | Tag         | `getTagClasses`         | `default` `primary` `secondary` `success` `warning` `danger` `info` `neutral` `accent` `cta` `outline` `ghost` | `sm` `md` `lg`      | `dismissible` `selected` `disabled` `loading` `interactive` `fullWidth` |
 | Spinner     | `getSpinnerClasses`     | —                                                                                                              | `sm` `md` `lg`      | —                                                                       |
+| Nav         | `getNavClasses`         | —                                                                                                              | —                   | `bordered` `sticky` `fullWidth`                                         |
+| Toast       | `getToastClasses`       | `info` `success` `warning` `danger`                                                                            | —                   | `dismissed` `fullWidth`                                                 |
+| Tooltip     | `getTooltipClasses`     | placement: `top` `bottom` `left` `right`                                                                       | —                   | `visible`                                                               |
+| Dropdown    | `getDropdownClasses`    | menu placement: `bottom-start` `bottom-end` `top-start` `top-end`                                              | —                   | `fullWidth`, item: `active` `disabled`                                  |
+| Modal       | `getModalClasses`       | —                                                                                                              | —                   | `open` `fullWidth`                                                      |
 
 Each recipe family also exports sub-element helpers for its structural parts
 (labels, wrappers, sub-containers, text elements). See the full list below.
@@ -261,20 +298,30 @@ Root recipe functions:
 - `getBadgeClasses`
 - `getButtonClasses`
 - `getCardClasses`
+- `getDropdownClasses`
 - `getIconBoxClasses`
 - `getInputClasses`
+- `getModalClasses`
+- `getNavClasses`
 - `getPricingCardClasses`
 - `getRatingClasses`
 - `getSpinnerClasses`
 - `getTagClasses`
 - `getTestimonialClasses`
+- `getToastClasses`
+- `getTooltipClasses`
 
 Root recipe helper functions:
 
+- `getDropdownItemClasses`
+- `getDropdownMenuClasses`
 - `getInputErrorMessageClasses`
 - `getInputHelperTextClasses`
 - `getInputLabelClasses`
 - `getInputWrapperClasses`
+- `getModalOverlayClasses`
+- `getNavLinkClasses`
+- `getNavLinksClasses`
 - `getPricingCardBadgeClasses`
 - `getPricingCardDescriptionClasses`
 - `getPricingCardPriceClasses`
@@ -287,6 +334,7 @@ Root recipe helper functions:
 - `getTestimonialAuthorNameClasses`
 - `getTestimonialAuthorTitleClasses`
 - `getTestimonialQuoteClasses`
+- `getToastIconClasses`
 
 The root package also re-exports the related recipe option, variant, size, and
 state TypeScript types defined by those recipes.

package/dist/base.css

@@ -3,7 +3,7 @@
   --sp-surface-card: #ffffff;
   --sp-surface-input: #ffffff;
   --sp-surface-overlay: rgba(0, 0, 0, 0.6);
-  --sp-surface-alternate: #eef1f6;
+  --sp-surface-subtle: #eef1f6;
   --sp-surface-hero: linear-gradient(135deg, #5b6ee1 0%, #6f3fd7 100%);
   --sp-text-on-page-default: #141b24;
   --sp-text-on-page-muted: #4b576a;
@@ -37,6 +37,41 @@
   --sp-icon-box-icon-success: #16a34a;
   --sp-icon-box-icon-warning: #d48806;
   --sp-icon-box-icon-danger: #dc2626;
+  --sp-nav-bg: #ffffff;
+  --sp-nav-text: #141b24;
+  --sp-nav-link: #374253;
+  --sp-nav-link-hover: #1f57db;
+  --sp-nav-link-active: #1946b4;
+  --sp-nav-border: #d9dfeb;
+  --sp-modal-bg: #ffffff;
+  --sp-modal-shadow: 0 20px 48px -12px rgba(0, 0, 0, 0.20);
+  --sp-modal-border: #d9dfeb;
+  --sp-modal-overlay: rgba(0, 0, 0, 0.6);
+  --sp-toast-success-bg: #f0fdf4;
+  --sp-toast-success-text: #166534;
+  --sp-toast-success-border: #bbf7d0;
+  --sp-toast-success-icon: #16a34a;
+  --sp-toast-warning-bg: #fffbea;
+  --sp-toast-warning-text: #8f5200;
+  --sp-toast-warning-border: #ffe08a;
+  --sp-toast-warning-icon: #d48806;
+  --sp-toast-danger-bg: #fef2f2;
+  --sp-toast-danger-text: #991b1b;
+  --sp-toast-danger-border: #fecaca;
+  --sp-toast-danger-icon: #dc2626;
+  --sp-toast-info-bg: #f0f9ff;
+  --sp-toast-info-text: #0c4a6e;
+  --sp-toast-info-border: #bae6fd;
+  --sp-toast-info-icon: #0369a1;
+  --sp-tooltip-bg: #141b24;
+  --sp-tooltip-text: #ffffff;
+  --sp-tooltip-border: #374253;
+  --sp-dropdown-bg: #ffffff;
+  --sp-dropdown-border: #d9dfeb;
+  --sp-dropdown-item-default: transparent;
+  --sp-dropdown-item-hover: #eef1f6;
+  --sp-dropdown-item-active: #f0f9ff;
+  --sp-dropdown-item-text: #141b24;
   --sp-color-brand-50: #eef4ff;
   --sp-color-brand-100: #d9e7ff;
   --sp-color-brand-200: #b9d2ff;
@@ -228,6 +263,7 @@
   --sp-z-index-popover: 1500;
   --sp-z-index-tooltip: 1600;
   --sp-z-index-toast: 1700;
+  --sp-duration-reduced: 0.01ms;
   --sp-duration-instant: 75ms;
   --sp-duration-fast: 150ms;
   --sp-duration-base: 200ms;
@@ -255,6 +291,7 @@
   --sp-focus-ring-style: solid;
   --sp-min-touch-target: 44px;
   --sp-min-text-size: 16px;
+  --sp-reduced-motion: 0.01ms;
   --sp-button-primary-bg: #0369a1;
   --sp-button-primary-bghover: #075985;
   --sp-button-primary-bgactive: #0c4a6e;
@@ -355,13 +392,37 @@
   --sp-animation-pulse-duration: 1200ms;
   --sp-animation-pulse-easing: cubic-bezier(0.4, 0, 0.2, 1);
   --sp-animation-pulse-keyframes: pulse;
+  --sp-animation-reduced-motion-fadein-duration: 0.01ms;
+  --sp-animation-reduced-motion-fadein-easing: linear;
+  --sp-animation-reduced-motion-fadein-keyframes: fade-in;
+  --sp-animation-reduced-motion-fadeout-duration: 0.01ms;
+  --sp-animation-reduced-motion-fadeout-easing: linear;
+  --sp-animation-reduced-motion-fadeout-keyframes: fade-out;
+  --sp-animation-reduced-motion-slideup-duration: 0.01ms;
+  --sp-animation-reduced-motion-slideup-easing: linear;
+  --sp-animation-reduced-motion-slideup-keyframes: slide-up;
+  --sp-animation-reduced-motion-slidedown-duration: 0.01ms;
+  --sp-animation-reduced-motion-slidedown-easing: linear;
+  --sp-animation-reduced-motion-slidedown-keyframes: slide-down;
+  --sp-animation-reduced-motion-scalein-duration: 0.01ms;
+  --sp-animation-reduced-motion-scalein-easing: linear;
+  --sp-animation-reduced-motion-scalein-keyframes: scale-in;
+  --sp-animation-reduced-motion-bounce-duration: 0.01ms;
+  --sp-animation-reduced-motion-bounce-easing: linear;
+  --sp-animation-reduced-motion-bounce-keyframes: bounce;
+  --sp-animation-reduced-motion-shake-duration: 0.01ms;
+  --sp-animation-reduced-motion-shake-easing: linear;
+  --sp-animation-reduced-motion-shake-keyframes: shake;
+  --sp-animation-reduced-motion-pulse-duration: 0.01ms;
+  --sp-animation-reduced-motion-pulse-easing: linear;
+  --sp-animation-reduced-motion-pulse-keyframes: pulse;
 }
 :root[data-spectre-theme="dark"] {
   --sp-surface-page: #141b24;
   --sp-surface-card: #222b38;
   --sp-surface-input: #374253;
   --sp-surface-overlay: rgba(0, 0, 0, 0.6);
-  --sp-surface-alternate: #222b38;
+  --sp-surface-subtle: #222b38;
   --sp-surface-hero: linear-gradient(135deg, #5d28b8 0%, #401f75 100%);
   --sp-text-on-page-default: #f7f8fb;
   --sp-text-on-page-muted: #b7c1d4;
@@ -395,6 +456,41 @@
   --sp-icon-box-icon-success: #4ade80;
   --sp-icon-box-icon-warning: #ffc21a;
   --sp-icon-box-icon-danger: #f87171;
+  --sp-nav-bg: #141b24;
+  --sp-nav-text: #f7f8fb;
+  --sp-nav-link: #b7c1d4;
+  --sp-nav-link-hover: #5a92ff;
+  --sp-nav-link-active: #8ab6ff;
+  --sp-nav-border: #374253;
+  --sp-modal-bg: #222b38;
+  --sp-modal-shadow: 0 20px 48px -12px rgba(0, 0, 0, 0.20);
+  --sp-modal-border: #374253;
+  --sp-modal-overlay: rgba(0, 0, 0, 0.6);
+  --sp-toast-success-bg: #14532d;
+  --sp-toast-success-text: #dcfce7;
+  --sp-toast-success-border: #15803d;
+  --sp-toast-success-icon: #4ade80;
+  --sp-toast-warning-bg: #734000;
+  --sp-toast-warning-text: #fff1c2;
+  --sp-toast-warning-border: #ad6800;
+  --sp-toast-warning-icon: #ffc21a;
+  --sp-toast-danger-bg: #7f1d1d;
+  --sp-toast-danger-text: #fee2e2;
+  --sp-toast-danger-border: #b91c1c;
+  --sp-toast-danger-icon: #f87171;
+  --sp-toast-info-bg: #082f49;
+  --sp-toast-info-text: #e0f2fe;
+  --sp-toast-info-border: #075985;
+  --sp-toast-info-icon: #38bdf8;
+  --sp-tooltip-bg: #f7f8fb;
+  --sp-tooltip-text: #141b24;
+  --sp-tooltip-border: #b7c1d4;
+  --sp-dropdown-bg: #222b38;
+  --sp-dropdown-border: #374253;
+  --sp-dropdown-item-default: transparent;
+  --sp-dropdown-item-hover: #374253;
+  --sp-dropdown-item-active: #082f49;
+  --sp-dropdown-item-text: #eef1f6;
 }
 @layer base {