@phcdevworks/spectre-ui 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -6,6 +6,36 @@ reflects package releases published to npm.
 
 ## [Unreleased]
 
+## [2.6.0] - 2026-06-28
+
+Release Title: Semantic Primitives and Form-Field Recipes
+
+Contract change type: additive
+
+### Added
+
+- **Link utility**: Added a token-backed `.sp-link` class
+  (`--sp-link-default` `--sp-link-hover` `--sp-link-active`
+  `--sp-link-visited`) for inline text links. Plain CSS, no recipe wrapper —
+  there is no variant or size axis to validate.
+- **Interactive surface state utilities**: Added `.sp-surface--hover`,
+  `.sp-surface--selected`, and `.sp-surface--active` modifier classes backed
+  by `--sp-surface-hover`, `--sp-surface-selected`, and `--sp-surface-active`
+  for clickable list items, menu items, table rows, and selectable surfaces.
+- **Divider utility**: Added a token-backed `.sp-divider` class
+  (`--sp-surface-divider`) for `<hr>`, section separators, and table borders.
+- **Form-field recipes**: Added `getCheckboxClasses` (`.sp-checkbox-indicator`,
+  `--sp-checkbox-*`), `getRadioClasses` (`.sp-radio-indicator`,
+  `--sp-radio-*`), `getSelectClasses` (`.sp-select`, `--sp-select-*`),
+  `getTextareaClasses` (`.sp-textarea`, `--sp-textarea-*`),
+  `getFieldsetClasses`/`getFieldsetLegendClasses` (`.sp-fieldset`,
+  `.sp-fieldset__legend`, `--sp-fieldset-*`), and `getLabelClasses`
+  (`.sp-form-label`, `--sp-label-*`). These back the previously
+  recipe-less `sp-checkbox`, `sp-radio`, `sp-select`, `sp-textarea`,
+  `sp-fieldset`, and `sp-label` Lit components in `spectre-components`. New
+  class names are distinct from the pre-existing `.sp-label` (input-scoped,
+  via `getInputLabelClasses`) to avoid colliding with that existing contract.
+
 ## [2.5.0] - 2026-06-25
 
 Release Title: Sidebar Navigation Hardening

package/README.md

@@ -7,7 +7,7 @@
 | Project team | `project-design` |
 | Repository role | Spectre L2 CSS, Tailwind, and recipe contract |
 | Package/artifact | `@phcdevworks/spectre-ui` |
-| Current version/status | 2.5.0 |
+| Current version/status | 2.6.0 |
 
 ## Standard Workflow
 
@@ -280,10 +280,31 @@ All options are optional and fall back to sensible defaults.
 | Grid        | `getGridClasses`        | columns: `1` `2` `3` `4` `6` `12`                                                                              | gap: `sm` `md` `lg` | —                                                                       |
 | Sidebar     | `getSidebarClasses`     | —                                                                                                              | —                   | `bordered`                                                              |
 | Footer      | `getFooterClasses`      | —                                                                                                              | —                   | `bordered` `fullWidth`                                                  |
+| Checkbox    | `getCheckboxClasses`    | —                                                                                                              | —                   | `checked` `disabled`                                                    |
+| Radio       | `getRadioClasses`       | —                                                                                                              | —                   | `checked` `disabled`                                                    |
+| Select      | `getSelectClasses`      | —                                                                                                              | —                   | `disabled` `focused`                                                    |
+| Textarea    | `getTextareaClasses`    | —                                                                                                              | —                   | `disabled` `focused`                                                    |
+| Fieldset    | `getFieldsetClasses`    | —                                                                                                              | —                   | `disabled`                                                              |
+| Label       | `getLabelClasses`       | —                                                                                                              | —                   | `disabled` `required`                                                   |
 
 Each recipe family also exports sub-element helpers for its structural parts
 (labels, wrappers, sub-containers, text elements). See the full list below.
 
+### Semantic utility classes (no recipe wrapper)
+
+These primitives are intentionally plain CSS classes in
+`src/styles/utilities.css` with no recipe function — there is no variant or
+size axis to validate, so a recipe wrapper would add indirection without a
+type-safety benefit. Apply the class name directly.
+
+| Class                   | Tokens                                                                       | Usage                                                   |
+| ----------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `.sp-link`              | `--sp-link-default` `--sp-link-hover` `--sp-link-active` `--sp-link-visited` | Inline text links (`<a>`).                              |
+| `.sp-surface--hover`    | `--sp-surface-hover`                                                         | Clickable list items, menu items, table rows on hover.  |
+| `.sp-surface--selected` | `--sp-surface-selected`                                                     | Selected list items, menu items, table rows.            |
+| `.sp-surface--active`   | `--sp-surface-active`                                                       | Pressed/active state for clickable surfaces.            |
+| `.sp-divider`           | `--sp-surface-divider`                                                      | `<hr>`, section separators, table borders.               |
+
 ### Root package
 
 The root package exports CSS path constants plus the recipe functions
@@ -304,22 +325,28 @@ Root recipe functions:
 - `getBadgeClasses`
 - `getButtonClasses`
 - `getCardClasses`
+- `getCheckboxClasses`
 - `getContainerClasses`
 - `getDropdownClasses`
+- `getFieldsetClasses`
 - `getFooterClasses`
 - `getGridClasses`
 - `getIconBoxClasses`
 - `getInputClasses`
+- `getLabelClasses`
 - `getModalClasses`
 - `getNavClasses`
 - `getPricingCardClasses`
+- `getRadioClasses`
 - `getRatingClasses`
 - `getSectionClasses`
+- `getSelectClasses`
 - `getSidebarClasses`
 - `getSpinnerClasses`
 - `getStackClasses`
 - `getTagClasses`
 - `getTestimonialClasses`
+- `getTextareaClasses`
 - `getToastClasses`
 - `getTooltipClasses`
 
@@ -327,6 +354,7 @@ Root recipe helper functions:
 
 - `getDropdownItemClasses`
 - `getDropdownMenuClasses`
+- `getFieldsetLegendClasses`
 - `getInputErrorMessageClasses`
 - `getInputHelperTextClasses`
 - `getInputLabelClasses`

package/dist/base.css

@@ -76,6 +76,39 @@
   --sp-dropdown-item-hover: #eef1f6;
   --sp-dropdown-item-active: #f0f9ff;
   --sp-dropdown-item-text: #141b24;
+  --sp-checkbox-bg: #ffffff;
+  --sp-checkbox-border: #b7c1d4;
+  --sp-checkbox-checked-bg: #0369a1;
+  --sp-checkbox-checked-border: #0369a1;
+  --sp-checkbox-text: #ffffff;
+  --sp-checkbox-disabled-bg: #f7f8fb;
+  --sp-checkbox-disabled-border: #d9dfeb;
+  --sp-radio-bg: #ffffff;
+  --sp-radio-border: #b7c1d4;
+  --sp-radio-checked-bg: #0369a1;
+  --sp-radio-checked-border: #0369a1;
+  --sp-radio-text: #ffffff;
+  --sp-radio-disabled-bg: #f7f8fb;
+  --sp-radio-disabled-border: #d9dfeb;
+  --sp-select-bg: #ffffff;
+  --sp-select-border: #b7c1d4;
+  --sp-select-text: #141b24;
+  --sp-select-placeholder-text: #657287;
+  --sp-select-disabled-bg: #f7f8fb;
+  --sp-select-disabled-border: #d9dfeb;
+  --sp-select-focus-border: #0ea5e9;
+  --sp-textarea-bg: #ffffff;
+  --sp-textarea-border: #b7c1d4;
+  --sp-textarea-text: #141b24;
+  --sp-textarea-placeholder: #657287;
+  --sp-textarea-disabled-bg: #f7f8fb;
+  --sp-textarea-disabled-border: #d9dfeb;
+  --sp-textarea-focus-border: #0ea5e9;
+  --sp-fieldset-border: #d9dfeb;
+  --sp-fieldset-legend-text: #141b24;
+  --sp-label-text: #141b24;
+  --sp-label-disabled-text: #8a96ad;
+  --sp-label-required-indicator-text: #dc2626;
   --sp-link-default: #1f57db;
   --sp-link-hover: #1946b4;
   --sp-link-active: #173b8f;
@@ -505,6 +538,39 @@
   --sp-dropdown-item-hover: #374253;
   --sp-dropdown-item-active: #082f49;
   --sp-dropdown-item-text: #eef1f6;
+  --sp-checkbox-bg: #222b38;
+  --sp-checkbox-border: #4b576a;
+  --sp-checkbox-checked-bg: #0369a1;
+  --sp-checkbox-checked-border: #0369a1;
+  --sp-checkbox-text: #ffffff;
+  --sp-checkbox-disabled-bg: #141b24;
+  --sp-checkbox-disabled-border: #374253;
+  --sp-radio-bg: #222b38;
+  --sp-radio-border: #4b576a;
+  --sp-radio-checked-bg: #0369a1;
+  --sp-radio-checked-border: #0369a1;
+  --sp-radio-text: #ffffff;
+  --sp-radio-disabled-bg: #141b24;
+  --sp-radio-disabled-border: #374253;
+  --sp-select-bg: #222b38;
+  --sp-select-border: #4b576a;
+  --sp-select-text: #f7f8fb;
+  --sp-select-placeholder-text: #8a96ad;
+  --sp-select-disabled-bg: #141b24;
+  --sp-select-disabled-border: #374253;
+  --sp-select-focus-border: #38bdf8;
+  --sp-textarea-bg: #222b38;
+  --sp-textarea-border: #4b576a;
+  --sp-textarea-text: #f7f8fb;
+  --sp-textarea-placeholder: #8a96ad;
+  --sp-textarea-disabled-bg: #141b24;
+  --sp-textarea-disabled-border: #374253;
+  --sp-textarea-focus-border: #38bdf8;
+  --sp-fieldset-border: #374253;
+  --sp-fieldset-legend-text: #f7f8fb;
+  --sp-label-text: #f7f8fb;
+  --sp-label-disabled-text: #4b576a;
+  --sp-label-required-indicator-text: #f87171;
   --sp-link-default: #1f57db;
   --sp-link-hover: #1946b4;
   --sp-link-active: #173b8f;

package/dist/components.css

@@ -76,6 +76,39 @@
   --sp-dropdown-item-hover: #eef1f6;
   --sp-dropdown-item-active: #f0f9ff;
   --sp-dropdown-item-text: #141b24;
+  --sp-checkbox-bg: #ffffff;
+  --sp-checkbox-border: #b7c1d4;
+  --sp-checkbox-checked-bg: #0369a1;
+  --sp-checkbox-checked-border: #0369a1;
+  --sp-checkbox-text: #ffffff;
+  --sp-checkbox-disabled-bg: #f7f8fb;
+  --sp-checkbox-disabled-border: #d9dfeb;
+  --sp-radio-bg: #ffffff;
+  --sp-radio-border: #b7c1d4;
+  --sp-radio-checked-bg: #0369a1;
+  --sp-radio-checked-border: #0369a1;
+  --sp-radio-text: #ffffff;
+  --sp-radio-disabled-bg: #f7f8fb;
+  --sp-radio-disabled-border: #d9dfeb;
+  --sp-select-bg: #ffffff;
+  --sp-select-border: #b7c1d4;
+  --sp-select-text: #141b24;
+  --sp-select-placeholder-text: #657287;
+  --sp-select-disabled-bg: #f7f8fb;
+  --sp-select-disabled-border: #d9dfeb;
+  --sp-select-focus-border: #0ea5e9;
+  --sp-textarea-bg: #ffffff;
+  --sp-textarea-border: #b7c1d4;
+  --sp-textarea-text: #141b24;
+  --sp-textarea-placeholder: #657287;
+  --sp-textarea-disabled-bg: #f7f8fb;
+  --sp-textarea-disabled-border: #d9dfeb;
+  --sp-textarea-focus-border: #0ea5e9;
+  --sp-fieldset-border: #d9dfeb;
+  --sp-fieldset-legend-text: #141b24;
+  --sp-label-text: #141b24;
+  --sp-label-disabled-text: #8a96ad;
+  --sp-label-required-indicator-text: #dc2626;
   --sp-link-default: #1f57db;
   --sp-link-hover: #1946b4;
   --sp-link-active: #173b8f;
@@ -505,6 +538,39 @@
   --sp-dropdown-item-hover: #374253;
   --sp-dropdown-item-active: #082f49;
   --sp-dropdown-item-text: #eef1f6;
+  --sp-checkbox-bg: #222b38;
+  --sp-checkbox-border: #4b576a;
+  --sp-checkbox-checked-bg: #0369a1;
+  --sp-checkbox-checked-border: #0369a1;
+  --sp-checkbox-text: #ffffff;
+  --sp-checkbox-disabled-bg: #141b24;
+  --sp-checkbox-disabled-border: #374253;
+  --sp-radio-bg: #222b38;
+  --sp-radio-border: #4b576a;
+  --sp-radio-checked-bg: #0369a1;
+  --sp-radio-checked-border: #0369a1;
+  --sp-radio-text: #ffffff;
+  --sp-radio-disabled-bg: #141b24;
+  --sp-radio-disabled-border: #374253;
+  --sp-select-bg: #222b38;
+  --sp-select-border: #4b576a;
+  --sp-select-text: #f7f8fb;
+  --sp-select-placeholder-text: #8a96ad;
+  --sp-select-disabled-bg: #141b24;
+  --sp-select-disabled-border: #374253;
+  --sp-select-focus-border: #38bdf8;
+  --sp-textarea-bg: #222b38;
+  --sp-textarea-border: #4b576a;
+  --sp-textarea-text: #f7f8fb;
+  --sp-textarea-placeholder: #8a96ad;
+  --sp-textarea-disabled-bg: #141b24;
+  --sp-textarea-disabled-border: #374253;
+  --sp-textarea-focus-border: #38bdf8;
+  --sp-fieldset-border: #374253;
+  --sp-fieldset-legend-text: #f7f8fb;
+  --sp-label-text: #f7f8fb;
+  --sp-label-disabled-text: #4b576a;
+  --sp-label-required-indicator-text: #f87171;
   --sp-link-default: #1f57db;
   --sp-link-hover: #1946b4;
   --sp-link-active: #173b8f;
@@ -3151,4 +3217,143 @@
   .sp-modal--full {
     width: 100%;
   }
+
+  .sp-checkbox-indicator {
+    display: inline-block;
+    width: var(--sp-space-16);
+    height: var(--sp-space-16);
+    border-radius: var(--sp-radius-sm);
+    border: var(--sp-component-border-width) solid var(--sp-checkbox-border);
+    background-color: var(--sp-checkbox-bg);
+    transition:
+      background-color var(--sp-duration-fast) var(--sp-easing-out),
+      border-color var(--sp-duration-fast) var(--sp-easing-out);
+  }
+
+  .sp-checkbox-indicator--checked {
+    background-color: var(--sp-checkbox-checked-bg);
+    border-color: var(--sp-checkbox-checked-border);
+  }
+
+  .sp-checkbox-indicator--disabled {
+    background-color: var(--sp-checkbox-disabled-bg);
+    border-color: var(--sp-checkbox-disabled-border);
+  }
+
+  .sp-radio-indicator {
+    display: inline-block;
+    width: var(--sp-space-16);
+    height: var(--sp-space-16);
+    border-radius: var(--sp-radius-pill);
+    border: var(--sp-component-border-width) solid var(--sp-radio-border);
+    background-color: var(--sp-radio-bg);
+    transition:
+      background-color var(--sp-duration-fast) var(--sp-easing-out),
+      border-color var(--sp-duration-fast) var(--sp-easing-out);
+  }
+
+  .sp-radio-indicator--checked {
+    background-color: var(--sp-radio-checked-bg);
+    border-color: var(--sp-radio-checked-border);
+  }
+
+  .sp-radio-indicator--disabled {
+    background-color: var(--sp-radio-disabled-bg);
+    border-color: var(--sp-radio-disabled-border);
+  }
+
+  .sp-select {
+    width: 100%;
+    display: block;
+    appearance: none;
+    padding: var(--sp-space-4) var(--sp-space-16);
+    border-radius: var(--sp-radius-md);
+    border: var(--sp-component-border-width) solid var(--sp-select-border);
+    background-color: var(--sp-select-bg);
+    color: var(--sp-select-text);
+    font-family: var(--sp-font-family-sans);
+    font-size: var(--sp-font-md-size);
+    line-height: var(--sp-font-md-line-height);
+    transition:
+      border-color var(--sp-duration-fast) var(--sp-easing-out),
+      background-color var(--sp-duration-fast) var(--sp-easing-out);
+  }
+
+  .sp-select::placeholder {
+    color: var(--sp-select-placeholder-text);
+  }
+
+  .sp-select:focus,
+  .sp-select--focus,
+  .sp-select.is-focus {
+    border-color: var(--sp-select-focus-border);
+  }
+
+  .sp-select--disabled,
+  .sp-select:disabled {
+    background-color: var(--sp-select-disabled-bg);
+    border-color: var(--sp-select-disabled-border);
+  }
+
+  .sp-textarea {
+    width: 100%;
+    display: block;
+    appearance: none;
+    padding: var(--sp-space-4) var(--sp-space-16);
+    border-radius: var(--sp-radius-md);
+    border: var(--sp-component-border-width) solid var(--sp-textarea-border);
+    background-color: var(--sp-textarea-bg);
+    color: var(--sp-textarea-text);
+    font-family: var(--sp-font-family-sans);
+    font-size: var(--sp-font-md-size);
+    line-height: var(--sp-font-md-line-height);
+    transition:
+      border-color var(--sp-duration-fast) var(--sp-easing-out),
+      background-color var(--sp-duration-fast) var(--sp-easing-out);
+  }
+
+  .sp-textarea::placeholder {
+    color: var(--sp-textarea-placeholder);
+  }
+
+  .sp-textarea:focus,
+  .sp-textarea--focus,
+  .sp-textarea.is-focus {
+    border-color: var(--sp-textarea-focus-border);
+  }
+
+  .sp-textarea--disabled,
+  .sp-textarea:disabled {
+    background-color: var(--sp-textarea-disabled-bg);
+    border-color: var(--sp-textarea-disabled-border);
+  }
+
+  .sp-fieldset {
+    border: var(--sp-component-border-width) solid var(--sp-fieldset-border);
+    border-radius: var(--sp-radius-md);
+    padding: var(--sp-space-16);
+  }
+
+  .sp-fieldset__legend {
+    color: var(--sp-fieldset-legend-text);
+    font-size: var(--sp-font-sm-size);
+    font-weight: var(--sp-font-sm-weight);
+    line-height: var(--sp-font-sm-line-height);
+  }
+
+  .sp-form-label {
+    color: var(--sp-label-text);
+    font-size: var(--sp-font-sm-size);
+    font-weight: var(--sp-font-sm-weight);
+    line-height: var(--sp-font-sm-line-height);
+  }
+
+  .sp-form-label--disabled {
+    color: var(--sp-label-disabled-text);
+  }
+
+  .sp-form-label--required::after {
+    content: "*";
+    color: var(--sp-label-required-indicator-text);
+  }
 }

package/dist/index.cjs

@@ -1038,15 +1038,77 @@ function getGridClasses(opts = {}) {
   return cx("sp-grid", `sp-grid--gap-${gap}`, `sp-grid-cols-${columns}`);
 }
 
+// src/recipes/checkbox.ts
+function getCheckboxClasses(opts = {}) {
+  const { checked = false, disabled = false } = opts;
+  return cx(
+    "sp-checkbox-indicator",
+    checked && "sp-checkbox-indicator--checked",
+    disabled && "sp-checkbox-indicator--disabled"
+  );
+}
+
+// src/recipes/radio.ts
+function getRadioClasses(opts = {}) {
+  const { checked = false, disabled = false } = opts;
+  return cx(
+    "sp-radio-indicator",
+    checked && "sp-radio-indicator--checked",
+    disabled && "sp-radio-indicator--disabled"
+  );
+}
+
+// src/recipes/select.ts
+function getSelectClasses(opts = {}) {
+  const { disabled = false, focused = false } = opts;
+  return cx(
+    "sp-select",
+    disabled && "sp-select--disabled",
+    focused && "sp-select--focus is-focus"
+  );
+}
+
+// src/recipes/textarea.ts
+function getTextareaClasses(opts = {}) {
+  const { disabled = false, focused = false } = opts;
+  return cx(
+    "sp-textarea",
+    disabled && "sp-textarea--disabled",
+    focused && "sp-textarea--focus is-focus"
+  );
+}
+
+// src/recipes/fieldset.ts
+function getFieldsetClasses(opts = {}) {
+  const { disabled = false } = opts;
+  return cx("sp-fieldset", disabled && "sp-fieldset--disabled");
+}
+function getFieldsetLegendClasses() {
+  return cx("sp-fieldset__legend");
+}
+
+// src/recipes/label.ts
+function getLabelClasses(opts = {}) {
+  const { disabled = false, required = false } = opts;
+  return cx(
+    "sp-form-label",
+    disabled && "sp-form-label--disabled",
+    required && "sp-form-label--required"
+  );
+}
+
 exports.getAlertClasses = getAlertClasses;
 exports.getAvatarClasses = getAvatarClasses;
 exports.getBadgeClasses = getBadgeClasses;
 exports.getButtonClasses = getButtonClasses;
 exports.getCardClasses = getCardClasses;
+exports.getCheckboxClasses = getCheckboxClasses;
 exports.getContainerClasses = getContainerClasses;
 exports.getDropdownClasses = getDropdownClasses;
 exports.getDropdownItemClasses = getDropdownItemClasses;
 exports.getDropdownMenuClasses = getDropdownMenuClasses;
+exports.getFieldsetClasses = getFieldsetClasses;
+exports.getFieldsetLegendClasses = getFieldsetLegendClasses;
 exports.getFooterClasses = getFooterClasses;
 exports.getGridClasses = getGridClasses;
 exports.getIconBoxClasses = getIconBoxClasses;
@@ -1055,6 +1117,7 @@ exports.getInputErrorMessageClasses = getInputErrorMessageClasses;
 exports.getInputHelperTextClasses = getInputHelperTextClasses;
 exports.getInputLabelClasses = getInputLabelClasses;
 exports.getInputWrapperClasses = getInputWrapperClasses;
+exports.getLabelClasses = getLabelClasses;
 exports.getModalClasses = getModalClasses;
 exports.getModalOverlayClasses = getModalOverlayClasses;
 exports.getNavClasses = getNavClasses;
@@ -1065,11 +1128,13 @@ exports.getPricingCardClasses = getPricingCardClasses;
 exports.getPricingCardDescriptionClasses = getPricingCardDescriptionClasses;
 exports.getPricingCardPriceClasses = getPricingCardPriceClasses;
 exports.getPricingCardPriceContainerClasses = getPricingCardPriceContainerClasses;
+exports.getRadioClasses = getRadioClasses;
 exports.getRatingClasses = getRatingClasses;
 exports.getRatingStarClasses = getRatingStarClasses;
 exports.getRatingStarsClasses = getRatingStarsClasses;
 exports.getRatingTextClasses = getRatingTextClasses;
 exports.getSectionClasses = getSectionClasses;
+exports.getSelectClasses = getSelectClasses;
 exports.getSidebarBackdropClasses = getSidebarBackdropClasses;
 exports.getSidebarClasses = getSidebarClasses;
 exports.getSidebarHeaderClasses = getSidebarHeaderClasses;
@@ -1084,6 +1149,7 @@ exports.getTestimonialAuthorNameClasses = getTestimonialAuthorNameClasses;
 exports.getTestimonialAuthorTitleClasses = getTestimonialAuthorTitleClasses;
 exports.getTestimonialClasses = getTestimonialClasses;
 exports.getTestimonialQuoteClasses = getTestimonialQuoteClasses;
+exports.getTextareaClasses = getTextareaClasses;
 exports.getToastClasses = getToastClasses;
 exports.getToastIconClasses = getToastIconClasses;
 exports.getTooltipClasses = getTooltipClasses;