@keenmate/pure-css 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/pure-css",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "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": {
@@ -24,7 +24,9 @@
     "src/js/",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "components.json",
+    "COMPONENTS.md"
   ],
   "scripts": {
     "build:bundle": "sass src/scss/pure-css.scss dist/css/pure-css.css --no-source-map --silence-deprecation=import",
@@ -42,7 +44,8 @@
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:headed": "playwright test --headed",
     "test:e2e:install": "playwright install chromium",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm run catalog",
+    "catalog": "node scripts/build-catalog.mjs"
   },
   "keywords": [
     "css",

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 ===
@@ -181,6 +188,10 @@
   --base-border-radius-sm: #{$base-border-radius-sm};
   --base-border-radius-md: #{$base-border-radius-md};
   --base-border-radius-lg: #{$base-border-radius-lg};
+  // Checkbox BOX scale — multiplies the box's own size (NOT a transform, which
+  // would pixel-snap the mask glyph off-centre). One knob every component with a
+  // checkbox reads; pairs with --base-icon-check-size.
+  --base-checkbox-scale: #{$base-checkbox-scale};
 
   // === Rem base for web components ===
   --base-rem: #{$base-rem};

package/src/scss/_icon-hover.scss

@@ -1,64 +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;
-}
+// ── 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;
+}

package/src/scss/_layout-responsive.scss

@@ -21,110 +21,130 @@
   --pc-easing-snappy: #{$easing-snappy};
 }
 
-// Responsive Design - Mobile and Tablet
-@media (max-width: $mobile-breakpoint) {
-  // Mobile: the sidebar is an off-canvas drawer that SLIDES in/out, in sync with
-  // the profile panel (same $transition-medium / $easing-snappy). It's always
-  // position:fixed at the drawer size and translated off-canvas at the
-  // inline-start edge; `.sidebar-visible` slides it to translateX(0). This
-  // replaces the old snap between width:0 and a fixed overlay, which popped in
-  // with no animation. Content takes full width in both states because the
-  // drawer is out of flow (fixed).
-  .pc-layout__sidebar,
-  .pc-layout__sidebar--icon-collapse {
-    position: fixed;
-    top: $navbar-height;
-    inset-inline-start: 0; // RTL: flips to right
-    bottom: 0;
-    width: $mobile-sidebar-width;
-    z-index: 1050;
-    background-color: var(--pc-sidebar-bg, var(--base-page-bg));
-    opacity: 1;
-    overflow-y: auto;
-    overscroll-behavior: contain; // drawer's own scroll doesn't chain to the page
-    border-inline-end: none; // RTL: flips to left
-    transform: translateX(-100%); // off-canvas (slid out past the inline-start edge)
-    visibility: hidden; // inert + unfocusable while closed; flips visible on open
-
-    // Gate the transition on body.loaded like the sidebar links, so the drawer
-    // doesn't animate from off-canvas on first paint.
-    body.loaded & {
-      transition: transform $transition-medium $easing-snappy,
-                  visibility $transition-medium $easing-snappy;
+// Off-canvas drawer overlay — the sidebar SLIDES in/out as a fixed sheet in sync
+// with the profile panel (same $transition-medium / $easing-snappy), translated
+// off-canvas at the inline-start edge; `.sidebar-visible` slides it to
+// translateX(0). Content takes full width in both states because the drawer is
+// out of flow (fixed), so the flex sibling `.pc-layout__content {flex:1}` grows.
+//
+// Shared by two callers via $bodyQualifier:
+//   • ''                 → every sidebar below $mobile-breakpoint (media query).
+//   • '.sidebar-overlay' → the opt-in desktop "overlay" sidebar behaviour, at any
+//                          width (burger opens a temporary floating drawer).
+// The qualifier composes onto `body` so the body.loaded transition gate and the
+// .sidebar-visible open state resolve as SAME-ELEMENT compounds (body.loaded,
+// body.sidebar-visible) — not broken descendant selectors.
+//
+// $drawerWidth differs per caller: mobile uses a near-full-width 90vw sheet;
+// desktop overlay uses the normal $sidebar-width (288px) so the content stays
+// usable behind it and the dismiss zone isn't a sliver.
+@mixin sidebar-drawer-overlay($bodyQualifier: '', $drawerWidth: $mobile-sidebar-width) {
+  body#{$bodyQualifier} {
+    .pc-layout__sidebar,
+    .pc-layout__sidebar--icon-collapse {
+      position: fixed;
+      top: $navbar-height;
+      inset-inline-start: 0; // RTL: flips to right
+      bottom: 0;
+      width: $drawerWidth;
+      z-index: 1050;
+      background-color: var(--pc-sidebar-bg, var(--base-page-bg));
+      opacity: 1;
+      overflow-y: auto;
+      overscroll-behavior: contain; // drawer's own scroll doesn't chain to the page
+      border-inline-end: none; // RTL: flips to left
+      transform: translateX(-100%); // off-canvas (slid out past the inline-start edge)
+      visibility: hidden; // inert + unfocusable while closed; flips visible on open
     }
-  }
 
-  // RTL: the drawer sits at the inline-start (right) edge, so it slides off to
-  // the right when closed.
-  [dir="rtl"] .pc-layout__sidebar,
-  [dir="rtl"] .pc-layout__sidebar--icon-collapse {
-    transform: translateX(100%);
-  }
+    // RTL: the drawer sits at the inline-start (right) edge, so it slides off to
+    // the right when closed.
+    [dir="rtl"] & {
+      .pc-layout__sidebar,
+      .pc-layout__sidebar--icon-collapse {
+        transform: translateX(100%);
+      }
+    }
 
-  // icon-collapse mode is a full overlay drawer on mobile — force labels visible.
-  .pc-layout__sidebar--icon-collapse .pc-sidebar__label {
-    opacity: 1 !important;
-    width: auto !important;
-    overflow: visible !important;
-    position: static !important;
-  }
+    // icon-collapse mode is a full labelled drawer here — force labels visible.
+    .pc-layout__sidebar--icon-collapse .pc-sidebar__label {
+      opacity: 1 !important;
+      width: auto !important;
+      overflow: visible !important;
+      position: static !important;
+    }
 
-  // Backdrop scrim: an always-present fixed pseudo that FADES its opacity, so it
-  // eases in/out with the drawer (a pseudo that only existed while open couldn't
-  // fade out). Inert + invisible when closed. On body::before so it's positioned
-  // against the viewport (not a transformed ancestor) — the toggle class lives
-  // on body too.
-  body::before {
-    content: "";
-    position: fixed;
-    top: $navbar-height;
-    inset-inline: 0; // RTL: covers full width
-    bottom: 0;
-    background-color: $mobile-backdrop-bg;
-    z-index: 1040;
-    opacity: 0;
-    visibility: hidden;
-    pointer-events: none;
-
-    body.loaded & {
-      transition: opacity $transition-medium $easing-snappy,
-                  visibility $transition-medium $easing-snappy;
+    // Backdrop scrim: an always-present fixed pseudo that FADES its opacity, so it
+    // eases in/out with the drawer (a pseudo that only existed while open couldn't
+    // fade out). Inert + invisible when closed. On the body pseudo so it's
+    // positioned against the viewport — the toggle class lives on body too.
+    &::before {
+      content: "";
+      position: fixed;
+      top: $navbar-height;
+      inset-inline: 0; // RTL: covers full width
+      bottom: 0;
+      background-color: $mobile-backdrop-bg;
+      z-index: 1040;
+      opacity: 0;
+      visibility: hidden;
+      pointer-events: none;
     }
-  }
 
-  // Mobile: drawer open — slide it in, reveal the scrim, lock background scroll.
-  .sidebar-visible {
-    // Standard modal-drawer scroll-lock: while the drawer + scrim are open the
-    // page behind must not scroll (otherwise dragging the scrim strip scrolls
-    // the content under the fixed drawer, exposing that the drawer is only
-    // viewport-high). This covers desktop browsers + Android; iOS Safari ignores
-    // body{overflow:hidden} for touch scroll, so the mobile toggle also applies
-    // a position:fixed body lock in JS (demo layout.mustache). See
-    // docs/mobile-sidebar-overlay.md.
-    overflow: hidden;
+    // Gate the drawer + scrim transitions on body.loaded so neither animates from
+    // its closed position on first paint.
+    &.loaded {
+      .pc-layout__sidebar,
+      .pc-layout__sidebar--icon-collapse {
+        transition: transform $transition-medium $easing-snappy,
+                    visibility $transition-medium $easing-snappy;
+      }
+
+      &::before {
+        transition: opacity $transition-medium $easing-snappy,
+                    visibility $transition-medium $easing-snappy;
+      }
+    }
 
-    .pc-layout__sidebar,
-    .pc-layout__sidebar--icon-collapse {
-      transform: translateX(0); // slide in (source order beats the RTL closed rule)
-      visibility: visible;
+    // Open — slide the drawer in, reveal the scrim, lock background scroll.
+    // Listed LAST so translateX(0) beats both the default and the RTL closed
+    // transform at equal specificity (source order wins).
+    &.sidebar-visible {
+      // Standard modal-drawer scroll-lock: while the drawer + scrim are open the
+      // page behind must not scroll (otherwise dragging the scrim strip scrolls
+      // the content under the fixed drawer, exposing that the drawer is only
+      // viewport-high). This covers desktop browsers + Android; iOS Safari ignores
+      // body{overflow:hidden} for touch scroll, so the toggle also applies a
+      // position:fixed body lock in JS (demo layout.mustache). See
+      // docs/mobile-sidebar-overlay.md.
+      overflow: hidden;
+
+      .pc-layout__sidebar,
+      .pc-layout__sidebar--icon-collapse {
+        transform: translateX(0);
+        visibility: visible;
+      }
+
+      &::before {
+        opacity: 1;
+        visibility: visible;
+        pointer-events: auto; // tap the scrim to dismiss
+      }
     }
 
-    &::before {
-      opacity: 1;
-      visibility: visible;
-      pointer-events: auto; // tap the scrim to dismiss
+    // Resize handle is meaningless on a fixed overlay drawer (and would ride the
+    // overlay edge straddling the backdrop-dismiss tap zone). Touch resize still
+    // works in the tablet band above $mobile-breakpoint.
+    .pc-sidebar-resize {
+      display: none;
     }
   }
+}
 
-  // Mobile overlay: the sidebar is a fixed 90vw sheet and resize is disabled in
-  // JS at this width (sidebar-resize.js MOBILE_MAX = $mobile-breakpoint). Hide
-  // the handle so the coarse-pointer grip pill / edge line don't render as a
-  // dead affordance riding the overlay's edge (where it also straddles the
-  // backdrop-dismiss tap zone). Touch resize still works in the tablet band
-  // above this breakpoint, where the coarse-pointer affordance is kept.
-  .pc-sidebar-resize {
-    display: none;
-  }
+// Responsive Design - Mobile and Tablet
+@media (max-width: $mobile-breakpoint) {
+  // Below the mobile breakpoint EVERY sidebar is an off-canvas drawer.
+  @include sidebar-drawer-overlay;
 
   // Adjust navbar for mobile
   .pc-navbar__inner {
@@ -146,6 +166,17 @@
   }
 }
 
+// Desktop opt-in: `body.sidebar-overlay` turns the sidebar into a temporary
+// floating drawer — the "overlay" sidebar behaviour. The burger toggles
+// `.sidebar-visible`; a tap on the scrim/outside closes it (demo JS). Gated
+// ABOVE the mobile breakpoint: at/below it the media query already renders the
+// sidebar as a 90vw drawer, so the desktop rules would only fight it (and widen
+// a phone drawer to 288px). Uses the normal $sidebar-width so the drawer floats
+// over content rather than swallowing the viewport.
+@media (min-width: ($mobile-breakpoint + 1)) {
+  @include sidebar-drawer-overlay('.sidebar-overlay', $sidebar-width);
+}
+
 @media (max-width: $tablet-breakpoint) and (min-width: $tablet-breakpoint-min) {
   // Tablet: reduce the sidebar by default, but honour an explicit resize.
   // The default (un-resized) width caps at $sidebar-width-tablet via min() so