@keenmate/pure-admin-core 2.7.0 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/pure-admin-core",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Lightweight, data-focused HTML/CSS admin framework built with PureCSS foundation and comprehensive component system",
   "style": "dist/css/main.css",
   "exports": {

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

@@ -14,6 +14,12 @@
 //   --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 *;
+
 @mixin output-base-css-variables {
   // === Accent Colors ===
   --base-accent-color: #{$base-accent-color};

package/src/scss/_core.scss

@@ -117,5 +117,16 @@
 // Data Visualization (progress bars, rings, gauges, heatmaps, sparklines)
 @use 'core-components/data-viz' as *;
 
+// KPI showcase components — shared chrome + 7 distinct designs.
+// Base must come first; design files use the shared classes from base.
+@use 'core-components/kpi-base' as *;
+@use 'core-components/kpi-terminal' as *;
+@use 'core-components/kpi-sparkline-list' as *;
+@use 'core-components/kpi-comparison-gauges' as *;
+@use 'core-components/kpi-hero-supporting' as *;
+@use 'core-components/kpi-bento' as *;
+@use 'core-components/kpi-numeric-strip' as *;
+@use 'core-components/kpi-editorial-minimal' as *;
+
 // Utility classes and helpers
 @use 'core-components/utilities' as *;

package/src/scss/core-components/_kpi-base.scss

@@ -0,0 +1,169 @@
+/* ========================================
+   KPI · shared base
+   Cross-cutting building blocks used by every pa-kpi-* showcase.
+   Tokens (--pa-positive, --pa-detail-bg, --pa-chart-trendline-*) live in
+   _base-css-variables.scss; this file only defines the shared class
+   surface that consumes them.
+   ======================================== */
+@use '../variables' as *;
+
+/* ----- LIVE indicator (title-bar pulse) ---------------------------------
+   Used in every KPI card header — a small mono "LIVE" caption with a
+   pulsing green dot. Sits next to the card title. */
+.pa-kpi-live {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.6rem;
+  font-family: var(--base-font-family-mono);
+  font-size: 1.2rem;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  color: var(--pa-text-secondary);
+
+  &__dot {
+    width: 0.8rem;
+    height: 0.8rem;
+    border-radius: 50%;
+    background: var(--pa-positive);
+    box-shadow: 0 0 6px var(--pa-positive);
+    animation: pa-kpi-pulse 1.6s ease-in-out infinite;
+  }
+}
+
+@keyframes pa-kpi-pulse {
+  50% { opacity: 0.35; }
+}
+
+/* ----- Card header row --------------------------------------------------
+   Title (h2/h3 by author choice) on one side, controls + LIVE on the other.
+   Wraps onto multiple rows on narrow cards. Every showcase uses this shape. */
+.pa-kpi-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 1.6rem;
+  flex-wrap: wrap;
+}
+
+/* ----- Card footer caption ---------------------------------------------
+   Two-line mono caption row at the bottom of the card (left: data source,
+   right: timestamp). Strong text inside picks up the focal color so things
+   like a metric name or count stand out. */
+.pa-kpi-footer {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 1rem;
+  font-family: var(--base-font-family-mono);
+  font-size: 1.2rem;
+  color: var(--pa-text-secondary);
+
+  strong {
+    color: var(--pa-text-color-1);
+    font-weight: 700;
+  }
+}
+
+/* ----- Sparkline endpoint dot ------------------------------------------
+   The SVG circle that marks the end of a sparkline is converted to a CSS
+   span at init time — the SVG uses preserveAspectRatio="none" so an
+   embedded <circle> renders as an oval at non-square aspect ratios.
+   See kpi-showcases.js for the conversion; here we only style the result. */
+.pa-kpi-spark-dot {
+  position: absolute;
+  width: 6px;
+  height: 6px;
+  margin: -3px 0 0 -3px;     /* centre on the (left, top) anchor */
+  border-radius: 50%;
+  background: currentColor;  /* inherits sentiment color from chart wrapper */
+  pointer-events: none;
+}
+
+/* Wrapper inserted around an SVG sparkline at init time when its parent
+   isn't already a positioned anchor — so the .pa-kpi-spark-dot can be
+   absolutely positioned relative to the chart. */
+.pa-kpi-spark-wrap {
+  display: block;
+  position: relative;
+  width: 100%;
+}
+
+/* ----- Hover detail popover --------------------------------------------
+   Bloomberg-dark by default regardless of host theme (terminal/data-dashboard
+   aesthetic). Override the --pa-detail-* tokens at :root or .pa-kpi-detail
+   level for a light/theme-aware variant.
+
+   Positioned by Floating UI anchored to a virtual element at the cursor —
+   the JS appends each popover to <body> at init so ancestor overflow:hidden
+   doesn't clip it. position: fixed because cursor coords are viewport-
+   relative; pointer-events:none so the cursor passes through cleanly and
+   tile mouseleave fires reliably. */
+.pa-kpi-detail {
+  position: fixed;
+  top: 0;
+  left: 0;
+  visibility: hidden;
+  pointer-events: none;
+  z-index: 9000;
+  min-width: 26rem;
+  max-width: 32rem;
+  background: var(--pa-detail-bg);
+  color: var(--pa-detail-text);
+  padding: 1.2rem 1.5rem;
+  font-family: var(--base-font-family-mono);
+  font-size: 1.25rem;
+  line-height: 1.5;
+  border-radius: 0.4rem;
+  box-shadow: var(--pa-detail-shadow);
+
+  &[data-show] {
+    visibility: visible;
+  }
+
+  &__title {
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    font-size: 1.05rem;
+    font-weight: 700;
+    color: var(--pa-detail-title);
+    margin-bottom: 0.6rem;
+  }
+
+  dl {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 0.35rem 1.6rem;
+    margin: 0;
+  }
+
+  dt {
+    margin: 0;
+    color: var(--pa-detail-row-label);
+    font-weight: 400;
+  }
+
+  dd {
+    margin: 0;
+    text-align: end;
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+  }
+
+  /* Inline sentiment hints for dd content (e.g. <dd>+12% <span class="pos">…</span></dd>) */
+  .pos  { color: var(--pa-positive); }
+  .neg  { color: var(--pa-negative); }
+  .warn { color: var(--pa-warning); }
+}
+
+/* ----- Section heading strip used outside card chrome -------------------
+   The 7 showcases each render a "stress-test" section that places tiles
+   directly inside .pa-col-* page-grid cells (no card wrapper). The strip
+   above those layouts hosts a label or LIVE indicator at the row's end. */
+.pa-kpi-sectionhead {
+  display: flex;
+  justify-content: flex-end;
+  align-items: center;
+  gap: 1.6rem;
+  margin-bottom: 1.2rem;
+}

package/src/scss/core-components/_kpi-bento.scss

@@ -0,0 +1,217 @@
+/* ========================================
+   KPI · Bento layout
+   Magazine-style asymmetric tile sizing with sparklines as soft background
+   fills behind the values. Default 6-tile layout on a 6-col × 3-row grid
+   (hero left-half × 2 rows, two stacked right-half × 2 rows, three equal
+   tiles bottom row). Tile placement is by source order via :nth-child, so
+   markup stays identical across layout modifiers.
+
+   Layout modifiers (below) swap `grid-template-areas` to provide
+   alternative compositions:
+     · default (no modifier) — 6 tiles, hero on the left
+     · `--hero-right`         — 6 tiles, mirror of default (hero on right)
+     · `--5-tile`             — 5 tiles, hero + 4 supporting
+   Row height is a CSS variable (`--pa-kpi-bento-row-height`, default
+   `12rem`) so authors can dial tile height per instance.
+   ======================================== */
+@use '../variables' as *;
+
+.pa-kpi-bento {
+  container-type: inline-size;
+  --pa-kpi-bento-row-height: 12rem;
+}
+.pa-kpi-bento__body { padding: 1.6rem; }
+
+/* ----- Bento grid (default: 6 tiles, hero on left) ---------------------- */
+.pa-kpi-bento__grid {
+  display: grid;
+  grid-template-columns: repeat(6, 1fr);
+  grid-template-rows: repeat(3, var(--pa-kpi-bento-row-height));
+  grid-template-areas:
+    "hero hero hero a    a    a"
+    "hero hero hero b    b    b"
+    "c    c    d    d    e    e";
+  gap: 1rem;
+
+  > :nth-child(1) { grid-area: hero; }
+  > :nth-child(2) { grid-area: a; }
+  > :nth-child(3) { grid-area: b; }
+  > :nth-child(4) { grid-area: c; }
+  > :nth-child(5) { grid-area: d; }
+  > :nth-child(6) { grid-area: e; }
+}
+
+/* Modifier: --hero-right — mirror of default. Hero on the right half,
+   two stacked tiles on the left of rows 1-2, three equal tiles below.
+   Same 6-tile contract as default; only the template flips. Source
+   order stays unchanged (1st = hero, 2nd = a, …). */
+.pa-kpi-bento__grid--hero-right {
+  grid-template-areas:
+    "a    a    a    hero hero hero"
+    "b    b    b    hero hero hero"
+    "c    c    d    d    e    e";
+}
+
+/* Modifier: --5-tile — hero + 4 supporting. Hero spans the left half ×
+   2 rows, two stacked tiles on the right (rows 1-2), two equal halves on
+   the bottom row. Requires exactly 5 tiles — a 6th tile (if present)
+   would be auto-placed in a new row and break the layout. */
+.pa-kpi-bento__grid--5-tile {
+  grid-template-areas:
+    "hero hero hero a    a    a"
+    "hero hero hero b    b    b"
+    "c    c    c    d    d    d";
+}
+
+/* Narrow card → stack everything single column. Resets `grid-area: auto`
+   on every tile so the same markup works regardless of which layout
+   modifier the grid carries (the @container override sets
+   `grid-template-areas: none` and the `grid-area: auto` on nth-child
+   together neutralise any modifier's template). */
+@container (max-width: 700px) {
+  .pa-kpi-bento__grid {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto;
+    grid-template-areas: none;
+    gap: 0.8rem;
+
+    > :nth-child(n) { grid-area: auto; }
+  }
+  .pa-kpi-bento-tile        { min-height: 10rem; }
+  .pa-kpi-bento-tile--hero  { min-height: 14rem; }
+}
+
+/* ----- Tile (per-KPI bento cell) ---------------------------------------- */
+.pa-kpi-bento-tile {
+  /* Per-tile inline-size container so the value font-size scales with
+     *this* tile's width via cqi (not the outer card's width). The hero
+     and the smaller bottom tiles each scale to their own column. */
+  container-type: inline-size;
+  position: relative;
+  overflow: hidden;
+  padding: 1.3rem 1.5rem;
+  border: 1px solid var(--pa-border-color);
+  background: var(--pa-card-bg);
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  grid-template-rows: auto 1fr auto;
+  grid-template-areas:
+    "label delta"
+    ".     .    "
+    "value value";
+  gap: 0.4rem 1rem;
+
+  /* Sparkline + delta sentiment cascade via currentColor. */
+  --pa-kpi-accent: var(--pa-positive);
+
+  &--positive    { --pa-kpi-accent: var(--pa-positive); }
+  &--negative    { --pa-kpi-accent: var(--pa-negative); }
+  &--neutral     { --pa-kpi-accent: var(--pa-neutral); }
+  &--up-strong   { --pa-kpi-accent: var(--pa-very-positive); }
+  &--down-strong { --pa-kpi-accent: var(--pa-very-negative); }
+
+  &--hero {
+    padding: 1.6rem 1.8rem;
+
+    .pa-kpi-bento-tile__num   { font-size: clamp(3.6rem, 22cqi, 7rem); }
+    .pa-kpi-bento-tile__unit  { font-size: clamp(1.6rem, 9cqi, 2.6rem); }
+    .pa-kpi-bento-tile__label,
+    .pa-kpi-bento-tile__delta { font-size: 1.4rem; }
+    .pa-kpi-bento-tile__chart { height: 70%; }
+  }
+}
+
+/* ----- Top row: label + delta, both layered over the chart -------------- */
+.pa-kpi-bento-tile__label {
+  grid-area: label;
+  font-family: var(--base-font-family-mono);
+  font-size: 1.3rem;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: color-mix(in srgb, var(--pa-text-color-1) 60%, transparent);
+  z-index: 1;
+  line-height: 1.2;
+}
+.pa-kpi-bento-tile__delta {
+  grid-area: delta;
+  font-family: var(--base-font-family-mono);
+  font-size: 1.3rem;
+  font-weight: 700;
+  color: var(--pa-kpi-accent);
+  z-index: 1;
+  align-self: start;
+  line-height: 1.2;
+}
+
+/* ----- Value (bottom of grid, layered over chart) ----------------------- */
+.pa-kpi-bento-tile__value {
+  grid-area: value;
+  align-self: end;
+  position: relative;
+  z-index: 1;
+  font-family: var(--base-font-family-mono);
+  display: inline-flex;
+  align-items: baseline;
+  line-height: 1;
+  white-space: nowrap;
+}
+.pa-kpi-bento-tile__num {
+  font-size: clamp(2rem, 14cqi, 3.2rem);
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  color: var(--pa-text-color-1);
+}
+.pa-kpi-bento-tile__unit {
+  font-size: clamp(1.2rem, 7cqi, 1.6rem);
+  font-weight: 500;
+  color: color-mix(in srgb, var(--pa-text-color-1) 50%, transparent);
+  margin: 0 0.3rem;
+}
+
+/* ----- Sparkline background ---------------------------------------------
+   Absolutely positioned, fills the bottom 65% of the tile. The value sits
+   over it (z-index: 1 above). The line/area read through behind the
+   digits at lower opacity so the value remains the focal point. SVG is
+   nested in a fixed-height wrapper so taller tiles don't distort the line
+   shape (preserveAspectRatio="none" would otherwise stretch the Y axis). */
+.pa-kpi-bento-tile__chart {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 65%;
+  pointer-events: none;
+  color: var(--pa-kpi-accent);
+  z-index: 0;
+  display: flex;
+  align-items: flex-end;
+
+  svg {
+    display: block;
+    width: 100%;
+    height: 100%;
+    overflow: visible;
+  }
+
+  polyline {
+    fill: none;
+    stroke: currentColor;
+    stroke-opacity: 0.55;
+    stroke-width: var(--pa-chart-trendline-stroke);
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
+
+  polygon {
+    fill: currentColor;
+    fill-opacity: 0.10;
+    stroke: none;
+  }
+}
+.pa-kpi-bento-tile__chart-svg {
+  position: relative;
+  display: block;
+  width: 100%;
+  height: var(--pa-chart-trendline-height);
+}

package/src/scss/core-components/_kpi-comparison-gauges.scss

@@ -0,0 +1,169 @@
+/* ========================================
+   KPI · Comparison gauges
+   Goal-oriented progress bars. Each KPI shows label · value, a bar with a
+   target tick, and a 0 · tgt scale below. Bar fill = value/target * 100%,
+   capped visually so overshoots are signalled by colour, not overflow.
+
+   Layout is a cell-min-driven `auto-fit` grid — cells stay at least
+   `--pa-kpi-gauge-cell-min` wide, the grid fits as many columns as the
+   container allows, and the responsive cascade is intrinsic to the grid
+   template (no `@container` queries). `--max-N` cap modifiers cap the
+   column count at N while still collapsing below the cell-min × N
+   threshold. Same pattern as `_kpi-editorial-minimal.scss`.
+   ======================================== */
+@use '../variables' as *;
+
+.pa-kpi-gauge-list__body { padding: 0; }
+
+/* ----- Grid + hairline rules -------------------------------------------
+   Cell-min-driven responsive layout. Override `--pa-kpi-gauge-cell-min`
+   per instance to change density (smaller min → more columns at the same
+   container width).
+
+   `gap: 1px` over `background: var(--pa-border-color)` with each tile
+   painting `background: var(--pa-card-bg)` on top — only the gap shows
+   through, giving single-pixel hairlines on every interior boundary
+   regardless of column count. The card's outer border supplies the
+   perimeter. Replaces the previous per-tile `border-right` +
+   `border-bottom` + nth-child suppression machinery, which only worked
+   for the hardcoded 2-col layout. */
+.pa-kpi-gauge-list__grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(var(--pa-kpi-gauge-cell-min, 20rem), 1fr));
+  gap: 1px;
+  background: var(--pa-border-color);
+}
+
+/* Modifier: force exactly 2 columns regardless of cell-min or container
+   width. For placements wanting a deterministic 2×N layout. */
+.pa-kpi-gauge-list__grid--2col { grid-template-columns: repeat(2, 1fr); }
+
+/* Cap-at-N modifiers: combine auto-fit with a ceiling on the column
+   count. Cells stay at least --pa-kpi-gauge-cell-min wide, but the grid
+   never exceeds N columns even when the container is wide enough to fit
+   more. Below the cell-min × N threshold the grid still collapses
+   responsively — these modifiers cap the maximum, not the minimum.
+
+   How the calc reads: each track's effective min is
+     max(cell-min, (container − total-gap) / N)
+   On a wide container the calc wins (so tracks grow, you stay at N).
+   On a narrow container cell-min wins (so the grid collapses).
+
+   Pick the cap so your item count divides into clean rows. */
+.pa-kpi-gauge-list__grid--max-2 {
+  grid-template-columns:
+    repeat(auto-fit, minmax(max(var(--pa-kpi-gauge-cell-min, 20rem), calc((100% - 1px) / 2)), 1fr));
+}
+.pa-kpi-gauge-list__grid--max-3 {
+  grid-template-columns:
+    repeat(auto-fit, minmax(max(var(--pa-kpi-gauge-cell-min, 20rem), calc((100% - 1px * 2) / 3)), 1fr));
+}
+.pa-kpi-gauge-list__grid--max-4 {
+  grid-template-columns:
+    repeat(auto-fit, minmax(max(var(--pa-kpi-gauge-cell-min, 20rem), calc((100% - 1px * 3) / 4)), 1fr));
+}
+.pa-kpi-gauge-list__grid--max-5 {
+  grid-template-columns:
+    repeat(auto-fit, minmax(max(var(--pa-kpi-gauge-cell-min, 20rem), calc((100% - 1px * 4) / 5)), 1fr));
+}
+.pa-kpi-gauge-list__grid--max-6 {
+  grid-template-columns:
+    repeat(auto-fit, minmax(max(var(--pa-kpi-gauge-cell-min, 20rem), calc((100% - 1px * 5) / 6)), 1fr));
+}
+
+/* ----- Gauge tile (label/value head · bar · 0/tgt scale) ---------------- */
+.pa-kpi-gauge {
+  position: relative;
+  background: var(--pa-card-bg);
+  padding: 1.6rem 2rem;
+  min-width: 0;
+
+  /* Per-tile bar colour cascade — modifiers below set the var, the fill
+     reads it. Cleaner than per-modifier-per-element rules; host apps can
+     override at the tile level via inline style="--pa-kpi-bar-color: …". */
+  --pa-kpi-bar-color: var(--pa-positive);
+
+  &--positive { --pa-kpi-bar-color: var(--pa-positive); }
+  &--warning  { --pa-kpi-bar-color: var(--pa-warning); }
+  &--negative { --pa-kpi-bar-color: var(--pa-negative); }
+  &--neutral  { --pa-kpi-bar-color: color-mix(in srgb, var(--pa-text-color-1) 70%, transparent); }
+}
+
+/* ----- Head: label left, value right (baseline-aligned) ----------------- */
+.pa-kpi-gauge__head {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 1.2rem;
+  margin-bottom: 0.8rem;
+}
+.pa-kpi-gauge__label {
+  font-family: var(--base-font-family-mono);
+  font-size: 1.4rem;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: color-mix(in srgb, var(--pa-text-color-1) 60%, transparent);
+}
+.pa-kpi-gauge__value {
+  font-family: var(--base-font-family-mono);
+  line-height: 1;
+}
+.pa-kpi-gauge__num {
+  font-size: 2.6rem;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  color: var(--pa-text-color-1);
+}
+.pa-kpi-gauge__unit {
+  font-size: 1.3rem;
+  font-weight: 500;
+  color: var(--pa-text-secondary);
+  margin-left: 0.2rem;
+}
+
+/* ----- Bar (track + sentiment-coloured fill + target tick) -------------- */
+.pa-kpi-gauge__bar {
+  /* Author-controlled tick position (default 100% — the target sits at the
+     right edge of the bar's "0 → target" scale). Override per-tile via
+     style="--pa-kpi-gauge-tick-pos: 80%" if the bar represents a wider
+     scale where the target sits inside the bar. */
+  --pa-kpi-gauge-tick-pos: 100%;
+  --pa-kpi-gauge-tick-color: var(--pa-text-color-1);
+
+  position: relative;
+  height: 0.7rem;
+  background: var(--pa-surface-track);
+  margin-bottom: 0.5rem;
+  overflow: visible;     /* tick can sit just outside the track */
+
+  /* Target tick — small bar slightly taller than the track. Centred on
+     --pa-kpi-gauge-tick-pos via the negative margin-left (matches half
+     the tick width). Full opacity so it stays readable on dark themes
+     against bright orange/green fills. */
+  &::after {
+    content: '';
+    position: absolute;
+    left: var(--pa-kpi-gauge-tick-pos);
+    margin-left: -0.15rem;
+    top: -0.2rem;
+    bottom: -0.2rem;
+    width: 0.3rem;
+    background: var(--pa-kpi-gauge-tick-color);
+  }
+}
+.pa-kpi-gauge__fill {
+  height: 100%;
+  background: var(--pa-kpi-bar-color);
+  /* Width set inline per tile via style="width: X%". */
+  transition: width 0.3s ease;
+}
+
+/* ----- Scale row (0 left · tgt XYZ right) ------------------------------- */
+.pa-kpi-gauge__scale {
+  display: flex;
+  justify-content: space-between;
+  font-family: var(--base-font-family-mono);
+  font-size: 1.2rem;
+  color: var(--pa-text-tertiary);
+}