@keenmate/pure-css 1.0.6 → 1.1.1

package/CHANGELOG.md

@@ -3,6 +3,61 @@
 All notable changes to `@keenmate/pure-css` are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.1.1] — 2026-09-26 [PUBLISHED]
+
+### Fixed
+
+- **Themes could not override `$base-*` — `_base-css-variables.scss` now `@import`s
+  the variable vocabulary instead of `@use`ing it.** The file pulled its
+  `$`-vocabulary in with `@use 'variables/index' as *`, but Sass refuses to expose
+  a member whose name already exists in the importing global scope — so any consumer
+  that set a `$base-*` value **before** importing (exactly what a theme does, relying
+  on the `!default` flags) failed with *"This module and the new module both define a
+  variable named $base-accent-color"*. The workflow documented at the top of that
+  file therefore worked only for a theme that overrode nothing, and the first real
+  downstream theme (`keen-docs-themes/cobalt2`) could not build. Switched to
+  `@import 'variables/index'`, which shares the one global scope the `!default`
+  mechanism needs (the same reason `variables/_index.scss` uses `@import`). pure-css's
+  own `@use 'base-css-variables' as bcv` entry points are unaffected. Behaviour-
+  preserving for the prebuilt CSS: all 7 artifacts rebuilt, every emitted `--base-*`
+  token name and value identical. Committed as `40b5b88`; it reached `prod` just after
+  the 1.1.0 tarball was cut, so 1.1.1 is its first published release.
+
+## [1.1.0] — 2026-09-26 [PUBLISHED]
+
+### Changed
+
+- **Sidebar link / submenu-toggle hover is now instant (removed `transition: all`).**
+  `.pc-sidebar__link`, the submenu toggle, and the sidebar search trigger animated
+  their hover with `transition: all $transition-fast`, which swept in `color` /
+  `background-color` — so the hover tint *faded in* and felt sluggish. Their hover
+  only changes colours (no motion), so the transition was pure colour animation,
+  against the "colours snap; transitions are motion-only" rule. Removed it; hover
+  colours now snap. The genuine motion transitions are kept — the submenu chevron
+  rotation (`transform`) and the icon-collapse label fade (`opacity` / `width`).
+
+### Added
+
+- **Icon hover affordance (foundation) — `_icon-hover.scss`.** Inside an enabled
+  interactive control on `:hover`, icons react with no JS and no SVG computation,
+  driven by convention + marker classes a wrapper stamps:
+  - masked `.pa-icon` glyphs that declared `--pa-icon-src-hover` swap to the
+    filled source (automatic; no-op for outline-only sets like Lucide);
+  - Font Awesome `<i>` marked `.pc-icon-hover-fill` flips regular → solid via the
+    `font-weight` axis (needs the `far` face, i.e. FA Pro);
+  - outline icons marked `.pc-icon-hover-highlight` recolour to
+    `--pc-icon-hover-color` (default: `--pc-accent`) — the hover cue for sets with
+    no solid form.
+
+  Applied to the shell contexts the foundation owns (`.pc-sidebar__link:hover` and
+  the submenu `.pc-sidebar__toggle:hover`, so submenu parents match plain/child
+  items) and a generic opt-in wrapper `.pc-icon-hover` for any enabled control. The behaviour
+  is exposed as the `pc-icon-hover-effects` mixin so component layers (pure-admin
+  core on `.pa-btn` / `.pa-tabs__item`, etc.) can apply the same effects to their
+  own selectors without redefining them. Additive; no change to existing output.
+  (Two-asset outline↔solid toggle for Heroicons / Fluent is a follow-up, wired
+  when a wrapper renders both layers.) See `pure-admin/docs/icon-hover-fill-design.md`.
+
 ## [1.0.6] — 2026-09-20 [PUBLISHED]
 
 ### Added

package/README.md

@@ -12,13 +12,14 @@ It's the shared layer the whole Keenmate stack agrees on:
 top of it, and every Keenmate web/Svelte component reads its colours from the same `--base-*`
 variables.
 
-## What's New in 1.0.6
+## What's New in 1.1.1
 
-- **Icons — `--base-icon-check-size` turns the selection glyph's scale into a theme knob** — the check mark (`--base-icon-check`) and the indeterminate dash (`--base-icon-indeterminate`) share one mask box, but the size that box was painted at used to be hard-coded downstream. This adds a single `--base-icon-check-size` token (`68%` default, authored as `$base-icon-check-size` in `variables/_base.scss` and emitted from `output-base-css-variables`) that both pure-admin and every Keenmate web component read, so overriding the check glyph **and** its scale now re-sizes the mark in lockstep across the whole stack — drop in an edge-to-edge glyph such as a star and shrink it from this one knob. `68%` leaves breathing room inside the box, and because indeterminate shares the mask box it re-sizes too. Both `base.css` and the `pure-css.css` bundle emit it, and it mirrors the canonical `@keenmate/base-css-variables` contract (parity guard green).
+- **Theming — downstream themes can finally override `$base-*` at compile time** — `_base-css-variables.scss` loaded its `$`-vocabulary with `@use 'variables/index' as *`, but Sass won't re-expose a member that already exists in the importing global scope, so any theme that set `$base-*` values *before* importing (the whole point of the `!default` contract) crashed with *"both define a variable named $base-accent-color"* — the workflow documented in that file compiled only when the theme overrode nothing, and the first real theme (`keen-docs-themes/cobalt2`) couldn't build. Switching to `@import 'variables/index'` shares the single global scope the `!default` mechanism relies on (the same reason `variables/_index.scss` uses `@import`), so `$base-*` overrides now land. It's behaviour-preserving for the prebuilt CSS — all seven artifacts rebuilt with every emitted `--base-*` name and value identical — and pure-css's own `@use … as bcv` entry points are unchanged. This landed just after the 1.1.0 tarball was cut, so 1.1.1 is the first release to actually ship it.
 
-## What's New in 1.0.5
+## What's New in 1.1.0
 
-- **Reboot — ordered lists (`<ol>`) render numbers again** — a 1.0.4 regression applied the new `--pc-list-bullet-type` knob to the shared `ul, ol` rule with a `disc` default, so every ordered list showed filled bullets instead of `decimal` numbers. The marker knob is an unordered concern, so it now sits on a `ul`-only rule; `<ol>` keeps the browser-default `decimal` (roman/alpha ordered variants stay a per-component override). The shared list margin/padding is unchanged, and `--pc-list-bullet-type` / `--base-list-bullet-type` continue to drive `ul` markers exactly as before.
+- **Icons — hover affordance for interactive controls, no JS (`_icon-hover.scss`)** — icons inside an enabled control now react on `:hover` through pure CSS, driven by convention plus marker classes a wrapper stamps: masked `.pa-icon` glyphs that declared `--pa-icon-src-hover` swap to their filled source (automatic; a no-op for outline-only sets like Lucide), Font Awesome `<i>` marked `.pc-icon-hover-fill` flips regular → solid on the `font-weight` axis (needs the FA Pro `far` face), and outline icons marked `.pc-icon-hover-highlight` recolour to `--pc-icon-hover-color` (default `--pc-accent`) for sets with no solid form. The foundation applies it to the shell context it owns (`.pc-sidebar__link:hover`) and ships a generic opt-in wrapper `.pc-icon-hover` for any enabled control. Crucially the behaviour is exposed as the `pc-icon-hover-effects` SCSS mixin, so component layers (pure-admin core on `.pa-btn` / `.pa-tabs__item`, etc.) apply the exact same effects to their own selectors from one shared definition rather than redefining them. Additive — no change to existing output.
+- **Sidebar — hover colours snap instead of fading** — `.pc-sidebar__link`, the submenu toggle, and the sidebar search trigger animated their hover with `transition: all $transition-fast`, which swept `color` / `background-color` so the hover tint faded in and felt sluggish. Their hover changes colours only (no motion), so per the "colours snap; transitions are motion-only" rule the transition was pure colour animation and has been removed — hover colours now snap. The genuine motion transitions are untouched: the submenu chevron rotation (`transform`) and the icon-collapse label fade (`opacity` / `width`).
 
 ## Why
 

package/dist/css/pure-css.css

@@ -2413,9 +2413,6 @@ body.pc-layout--sticky .pc-layout__sidebar {
   font-weight: 500;
   border-inline-end: 3px solid transparent;
 }
-body.loaded .pc-sidebar__link {
-  transition: all 0.1s ease-out;
-}
 .pc-sidebar__link:hover {
   color: var(--pc-sidebar-text, var(--base-text-color-1));
   background-color: var(--pc-accent-light);
@@ -2445,9 +2442,6 @@ body.loaded .pc-sidebar__link {
 .pc-sidebar__search[hidden] {
   display: none;
 }
-body.loaded .pc-sidebar__search {
-  transition: all 0.1s ease-out;
-}
 .pc-sidebar__search:hover {
   border-color: #0ea5e9;
   color: var(--base-input-color);
@@ -2513,9 +2507,6 @@ body.loaded .pc-sidebar__search {
   font-weight: 500;
   cursor: pointer;
 }
-body.loaded .pc-sidebar__toggle {
-  transition: all 0.1s ease-out;
-}
 .pc-sidebar__toggle:hover {
   color: var(--pc-sidebar-text, var(--base-text-color-1));
   background-color: var(--pc-accent-light);
@@ -3133,6 +3124,31 @@ body.pc-layout--sticky .pc-layout__inner {
   border-top: 1px solid var(--pc-border-color);
 }
 
+.pc-sidebar__link:not([aria-disabled=true]):not(.is-disabled):hover .pa-icon,
+.pc-sidebar__toggle:not([aria-disabled=true]):not(.is-disabled):hover .pa-icon {
+  -webkit-mask-image: var(--pa-icon-src-hover, var(--pa-icon-src));
+  mask-image: var(--pa-icon-src-hover, var(--pa-icon-src));
+}
+.pc-sidebar__link:not([aria-disabled=true]):not(.is-disabled):hover .pc-icon-hover-fill,
+.pc-sidebar__toggle:not([aria-disabled=true]):not(.is-disabled):hover .pc-icon-hover-fill {
+  font-weight: 900;
+}
+.pc-sidebar__link:not([aria-disabled=true]):not(.is-disabled):hover .pc-icon-hover-highlight,
+.pc-sidebar__toggle:not([aria-disabled=true]):not(.is-disabled):hover .pc-icon-hover-highlight {
+  color: var(--pc-icon-hover-color, var(--pc-accent));
+}
+
+.pc-icon-hover:not([disabled]):not([aria-disabled=true]):not(.is-disabled):hover .pa-icon {
+  -webkit-mask-image: var(--pa-icon-src-hover, var(--pa-icon-src));
+  mask-image: var(--pa-icon-src-hover, var(--pa-icon-src));
+}
+.pc-icon-hover:not([disabled]):not([aria-disabled=true]):not(.is-disabled):hover .pc-icon-hover-fill {
+  font-weight: 900;
+}
+.pc-icon-hover:not([disabled]):not([aria-disabled=true]):not(.is-disabled):hover .pc-icon-hover-highlight {
+  color: var(--pc-icon-hover-color, var(--pc-accent));
+}
+
 .font-family-system {
   font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
 }

package/package.json

@@ -1,83 +1,83 @@
-{
-  "name": "@keenmate/pure-css",
-  "version": "1.0.6",
-  "description": "The Keenmate CSS foundation — --base-* theming contract, PureCSS grid and utility classes. Extracted from pure-admin-core so docs sites, standalone pages and every web/svelte component share one theming layer.",
-  "style": "dist/css/pure-css.css",
-  "exports": {
-    ".": "./dist/css/pure-css.css",
-    "./css": "./dist/css/pure-css.css",
-    "./css/*": "./dist/css/*",
-    "./base": "./dist/css/base.css",
-    "./reboot": "./dist/css/reboot.css",
-    "./component-reset": "./dist/css/component-reset.css",
-    "./scrollbars": "./dist/css/scrollbars.css",
-    "./grid": "./dist/css/grid.css",
-    "./utilities": "./dist/css/utilities.css",
-    "./scss": "./src/scss/pure-css.scss",
-    "./scss/*": "./src/scss/*",
-    "./js": "./src/js/pure-css.js",
-    "./js/*": "./src/js/*"
-  },
-  "files": [
-    "dist/",
-    "src/scss/",
-    "src/js/",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build:bundle": "sass src/scss/pure-css.scss dist/css/pure-css.css --no-source-map --silence-deprecation=import",
-    "build:base": "sass src/scss/base.scss dist/css/base.css --no-source-map --silence-deprecation=import",
-    "build:reboot": "sass src/scss/reboot.scss dist/css/reboot.css --no-source-map --silence-deprecation=import",
-    "build:component-reset": "sass src/scss/component-reset.scss dist/css/component-reset.css --no-source-map --silence-deprecation=import",
-    "build:scrollbars": "sass src/scss/scrollbars.scss dist/css/scrollbars.css --no-source-map --silence-deprecation=import",
-    "build:grid": "sass src/scss/grid.scss dist/css/grid.css --no-source-map --silence-deprecation=import",
-    "build:utilities": "sass src/scss/utilities.scss dist/css/utilities.css --no-source-map --silence-deprecation=import",
-    "build": "npm run build:bundle && npm run build:base && npm run build:reboot && npm run build:component-reset && npm run build:scrollbars && npm run build:grid && npm run build:utilities",
-    "watch": "sass --watch src/scss/pure-css.scss:dist/css/pure-css.css --silence-deprecation=import",
-    "dev": "vite --port 12500",
-    "test": "npm run test:e2e",
-    "test:e2e": "playwright test",
-    "test:e2e:ui": "playwright test --ui",
-    "test:e2e:headed": "playwright test --headed",
-    "test:e2e:install": "playwright install chromium",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "css",
-    "scss",
-    "purecss",
-    "grid",
-    "utilities",
-    "css-variables",
-    "theming",
-    "keenmate",
-    "pure-admin"
-  ],
-  "author": "Keenmate",
-  "license": "MIT",
-  "peerDependencies": {
-    "sass": "^1.0.0"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.60.0",
-    "sass": "^1.70.0",
-    "vite": "^5.4.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Keenmate/pure-css.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Keenmate/pure-css/issues"
-  },
-  "homepage": "https://github.com/Keenmate/pure-css#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "allowScripts": {
-    "esbuild@0.21.5": true,
-    "@parcel/watcher@2.6.0": true
-  }
-}
+{
+  "name": "@keenmate/pure-css",
+  "version": "1.1.1",
+  "description": "The Keenmate CSS foundation — --base-* theming contract, PureCSS grid and utility classes. Extracted from pure-admin-core so docs sites, standalone pages and every web/svelte component share one theming layer.",
+  "style": "dist/css/pure-css.css",
+  "exports": {
+    ".": "./dist/css/pure-css.css",
+    "./css": "./dist/css/pure-css.css",
+    "./css/*": "./dist/css/*",
+    "./base": "./dist/css/base.css",
+    "./reboot": "./dist/css/reboot.css",
+    "./component-reset": "./dist/css/component-reset.css",
+    "./scrollbars": "./dist/css/scrollbars.css",
+    "./grid": "./dist/css/grid.css",
+    "./utilities": "./dist/css/utilities.css",
+    "./scss": "./src/scss/pure-css.scss",
+    "./scss/*": "./src/scss/*",
+    "./js": "./src/js/pure-css.js",
+    "./js/*": "./src/js/*"
+  },
+  "files": [
+    "dist/",
+    "src/scss/",
+    "src/js/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:bundle": "sass src/scss/pure-css.scss dist/css/pure-css.css --no-source-map --silence-deprecation=import",
+    "build:base": "sass src/scss/base.scss dist/css/base.css --no-source-map --silence-deprecation=import",
+    "build:reboot": "sass src/scss/reboot.scss dist/css/reboot.css --no-source-map --silence-deprecation=import",
+    "build:component-reset": "sass src/scss/component-reset.scss dist/css/component-reset.css --no-source-map --silence-deprecation=import",
+    "build:scrollbars": "sass src/scss/scrollbars.scss dist/css/scrollbars.css --no-source-map --silence-deprecation=import",
+    "build:grid": "sass src/scss/grid.scss dist/css/grid.css --no-source-map --silence-deprecation=import",
+    "build:utilities": "sass src/scss/utilities.scss dist/css/utilities.css --no-source-map --silence-deprecation=import",
+    "build": "npm run build:bundle && npm run build:base && npm run build:reboot && npm run build:component-reset && npm run build:scrollbars && npm run build:grid && npm run build:utilities",
+    "watch": "sass --watch src/scss/pure-css.scss:dist/css/pure-css.css --silence-deprecation=import",
+    "dev": "vite --port 12500",
+    "test": "npm run test:e2e",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:install": "playwright install chromium",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "css",
+    "scss",
+    "purecss",
+    "grid",
+    "utilities",
+    "css-variables",
+    "theming",
+    "keenmate",
+    "pure-admin"
+  ],
+  "author": "Keenmate",
+  "license": "MIT",
+  "peerDependencies": {
+    "sass": "^1.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "sass": "^1.70.0",
+    "vite": "^5.4.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Keenmate/pure-css.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Keenmate/pure-css/issues"
+  },
+  "homepage": "https://github.com/Keenmate/pure-css#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "allowScripts": {
+    "esbuild@0.21.5": true,
+    "@parcel/watcher@2.6.0": true
+  }
+}

package/src/scss/_base-css-variables.scss

@@ -14,11 +14,18 @@
 //   --ms-accent-color: var(--base-accent-color, #3b82f6);
 // ============================================================================
 
-// Make variables resolvable when this file is loaded as a @use module
-// (e.g. from main.scss). Legacy @import callers (themes) are unaffected —
-// Sass places @use'd members into the importing file's global scope, where
-// theme-set overrides already live.
-@use 'variables/index' as *;
+// Make the $-vocabulary resolvable here.
+//
+// MUST be @import, not `@use 'variables/index' as *`. A theme's whole job is to set
+// $base-* BEFORE pulling this file in (the !default flags then keep those values) --
+// but `@use ... as *` REFUSES to expose a member whose name already exists in the
+// importing global scope, so every theme died on
+//   "This module and the new module both define a variable named $base-accent-color".
+// That made the usage documented at the top of this file impossible: it worked only
+// for a theme that overrode nothing. @import shares one global scope and is what the
+// !default mechanism needs. pure-css's own `@use 'base-css-variables' as bcv` entries
+// are unaffected -- a module that @imports still exports its members normally.
+@import 'variables/index';
 
 @mixin output-base-css-variables {
   // === Accent Colors ===

package/src/scss/_icon-hover.scss

@@ -0,0 +1,64 @@
+// ── Icon hover affordance (foundation) ────────────────────────────────────────
+// See pure-admin/docs/icon-hover-fill-design.md.
+//
+// Inside an ENABLED interactive control on :hover, icons react — no JS, no SVG
+// computation, driven by convention + marker classes the wrapper stamps:
+//
+//   • Masked `.pa-icon` glyphs that declared a filled source on
+//     `--pa-icon-src-hover` swap their mask to it. NO-OP for outline-only glyphs
+//     (e.g. Lucide ships no solid), and no marker needed — it's automatic.
+//   • Font Awesome `<i>` marked `.pc-icon-hover-fill` flips regular → solid via the
+//     font-weight axis (same codepoint). Needs the `far` regular face present
+//     (largely FA Pro), else there's nothing lighter to flip from.
+//   • Outline icons marked `.pc-icon-hover-highlight` recolour to
+//     `--pc-icon-hover-color` (default: the accent). This is the answer for sets
+//     with no solid form (Lucide): a real hover cue without a fill.
+//
+// The behaviour lives here (foundation) so every consumer — pure-admin core,
+// keen, svelte, the web components — shares ONE definition. Wrappers only stamp
+// the marker classes. `pc-icon-hover-effects` is a mixin so component layers can
+// apply the same effects to their own enabled-control selectors (e.g. core on
+// `.pa-btn` / `.pa-tabs__item`) without redefining them.
+//
+// Deliberately NOT here yet: the two-asset outline↔solid toggle for Heroicons /
+// Fluent (render both layers, swap visibility) — that needs a wrapper markup
+// contract, so it's wired when a wrapper renders both layers.
+
+@mixin pc-icon-hover-effects {
+  // Masked icons: swap to the filled mask source if one was declared. Set the
+  // longhand directly (not --pa-icon-src) so the var(--pa-icon-src) fallback
+  // stays non-cyclic — reassigning --pa-icon-src to reference itself would
+  // compute to invalid and wipe the mask to a solid box.
+  .pa-icon {
+    -webkit-mask-image: var(--pa-icon-src-hover, var(--pa-icon-src));
+            mask-image: var(--pa-icon-src-hover, var(--pa-icon-src));
+  }
+
+  // Font Awesome regular → solid (weight axis). No transition — a font-weight
+  // swap is instant, matching the mask swap.
+  .pc-icon-hover-fill {
+    font-weight: 900;
+  }
+
+  // Outline-only sets (Lucide): recolour the stroke instead of filling. Works
+  // because Lucide SVGs are stroke="currentColor".
+  .pc-icon-hover-highlight {
+    color: var(--pc-icon-hover-color, var(--pc-accent));
+  }
+}
+
+// Shell contexts owned by the foundation: sidebar nav links AND submenu toggles,
+// so a submenu parent's icon reacts identically to a plain/child link (not just
+// to the toggle's own hover colour).
+.pc-sidebar__link:not([aria-disabled='true']):not(.is-disabled):hover,
+.pc-sidebar__toggle:not([aria-disabled='true']):not(.is-disabled):hover {
+  @include pc-icon-hover-effects;
+}
+
+// Generic opt-in: put `.pc-icon-hover` on any enabled control/element to get the
+// behaviour without depending on a component class (a bare link, a custom
+// button, a list row, …). Disabled opt-outs are excluded so only actionable
+// controls react.
+.pc-icon-hover:not([disabled]):not([aria-disabled='true']):not(.is-disabled):hover {
+  @include pc-icon-hover-effects;
+}