@keenmate/pure-css 1.1.1 → 1.2.0

package/package.json

@@ -1,83 +1,86 @@
-{
-  "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
-  }
-}
+{
+  "name": "@keenmate/pure-css",
+  "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": {
+    ".": "./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",
+    "components.json",
+    "COMPONENTS.md"
+  ],
+  "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 && npm run catalog",
+    "catalog": "node scripts/build-catalog.mjs"
+  },
+  "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

@@ -188,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/_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

package/src/scss/utilities.scss

@@ -709,16 +709,65 @@ $spacers: (
 .text-warning { color: var(--pc-warning-text) !important; }
 .text-info { color: var(--pc-info-text) !important; }
 
-// Text color utilities (theme custom colors 1-9)
-.text-color-1 { color: var(--pc-color-1) !important; }
-.text-color-2 { color: var(--pc-color-2) !important; }
-.text-color-3 { color: var(--pc-color-3) !important; }
-.text-color-4 { color: var(--pc-color-4) !important; }
-.text-color-5 { color: var(--pc-color-5) !important; }
-.text-color-6 { color: var(--pc-color-6) !important; }
-.text-color-7 { color: var(--pc-color-7) !important; }
-.text-color-8 { color: var(--pc-color-8) !important; }
-.text-color-9 { color: var(--pc-color-9) !important; }
+// Role SURFACE utilities — the role parallel of the numeric
+// .{bg,text-on,surface}-color-N family below. Fill = --pc-{role} (primary →
+// --pc-accent); on-fill contrast text = --base-text-on-{role} (the only on-role
+// contrast token — foreground .text-{role} above is a DIFFERENT colour). All
+// !important for cascade parity with the role text utilities.
+//
+//   .bg-{role}        role colour as background (no text change)
+//   .text-on-{role}   contrast text to sit on a role fill (pair with .bg-{role})
+//   .surface-{role}   role background + contrast text in one class
+@each $role, $fill in (primary: accent, success: success, warning: warning, danger: danger, info: info) {
+  .bg-#{$role} { background-color: var(--pc-#{$fill}) !important; }
+  .text-on-#{$role} { color: var(--base-text-on-#{$role}) !important; }
+  .surface-#{$role} {
+    background-color: var(--pc-#{$fill}) !important;
+    color: var(--base-text-on-#{$role}) !important;
+  }
+}
+
+// Text colour — neutral hierarchy. Maps to --pc-text-color-N (text HIERARCHY),
+// a DIFFERENT scale from the numbered .text-color-N palette below (--pc-color-N
+// data colours). `.text-secondary` is the flat muted/subdued text utility (the
+// muted token used to live only inside a component modifier); `.text-body` is the
+// explicit default body colour. !important so the colour wins when composed onto
+// a component that carries its own colour.
+.text-body      { color: var(--pc-text-color-1) !important; } // default body text (explicit)
+.text-secondary { color: var(--pc-text-color-2) !important; } // muted / subdued body text
+
+// Semantic text shorthands (compound).
+.text-caption {
+  font-size: $font-size-xs;
+  color: var(--pc-text-color-2);
+  margin-bottom: $spacing-sm;
+}
+.text-lead {
+  font-size: $font-size-base;
+  line-height: $line-height-relaxed;
+}
+
+// Theme palette colour utilities (theme custom colors 1-9).
+// Two token layers per slot: --pc-color-N (the slot) + --pc-color-N-text (its
+// guaranteed-contrasting text). Each form applies the slot to one property;
+// `.surface-color-N` is the composite (slot background + readable text). All
+// !important for cascade parity with the role colours above.
+//
+//   .text-color-N     slot as text colour
+//   .bg-color-N       slot as background
+//   .border-color-N   slot as border colour
+//   .text-on-color-N  contrast text only (pair with .bg-color-N yourself)
+//   .surface-color-N  slot background + contrast text in one class
+@for $i from 1 through 9 {
+  .text-color-#{$i} { color: var(--pc-color-#{$i}) !important; }
+  .bg-color-#{$i} { background-color: var(--pc-color-#{$i}) !important; }
+  .border-color-#{$i} { border-color: var(--pc-color-#{$i}) !important; }
+  .text-on-color-#{$i} { color: var(--pc-color-#{$i}-text) !important; }
+  .surface-color-#{$i} {
+    background-color: var(--pc-color-#{$i}) !important;
+    color: var(--pc-color-#{$i}-text) !important;
+  }
+}
 
 // Rounded utilities
 .rounded {

package/src/scss/variables/_base.scss

@@ -296,6 +296,14 @@ $base-border-radius-sm: 0.4 !default;  // 4px
 $base-border-radius-md: 0.6 !default;  // 6px
 $base-border-radius-lg: 0.8 !default;  // 8px
 
+// Checkbox BOX scale (web-component bridge: --base-checkbox-scale) — multiplies
+// the box's OWN width/height, NOT a CSS transform (a transform pixel-snaps the
+// fractionally-positioned mask glyph and shifts it off-centre). The box sizes as
+// `calc(<base-size> * var(--base-checkbox-scale))`, the glyph via
+// --base-icon-check-size. One knob every component with a checkbox reads, so a
+// theme resizes all of them in lockstep. 1 = the component's base size.
+$base-checkbox-scale: 1 !default;
+
 // Rem base for web components (bridge: --base-rem). They size themselves as
 // `calc(<unitless-multiplier> * var(--base-rem, 10px))`. pure-css pins
 // `html { font-size: 10px }` (reboot), so `1rem` tracks that base adaptively.