@ecomconsult/consentkit 0.5.9 → 0.5.10

package/README.md

@@ -184,9 +184,10 @@ Pass any subset to `init()`. Nested objects merge with the defaults.
 | `theme.accent` | `string` | `"#2B50D8"` | Exposed as `--ck-accent` |
 | `theme.font` | `"inherit" \| "system"` | `"inherit"` | v0.5.0. `inherit` takes the host page's font family; `system` restores the pre-0.5.0 system stack. Font *sizes* are fixed either way |
 | `theme.radius` | `{ card, button }` | `{ card: 16, button: 8 }` | v0.5.0. px, clamped 0–32. A bare string or number is the pre-0.5.0 form and still sets the card radius |
-| `theme.buttons` | `{ accept, reject, settings }` | see below | v0.5.0. Per-button appearance. **Contrast is enforced automatically** — see [Button appearance](#button-appearance) |
+| `theme.buttons` | `{ accept, reject, settings }` | see below | v0.5.0. Per-button appearance. A colour you set is painted as set; contrast rules correct only derived colours (v0.5.10) — see [Button appearance](#button-appearance) |
 | `theme.mode` | `"auto" \| "light" \| "dark"` | `"auto"` | `auto` follows `prefers-color-scheme` |
 | `theme.dark` | `{ bg, ink, accent, onAccent }` | built-in | Overrides the dark palette |
+| `theme.light` | `{ onAccent }` | built-in | v0.5.10. The light mirror of `theme.dark`. An `onAccent` set here is the filled buttons' text colour for light mode, painted as given |
 | `texts.policyUrl` | `string` | — | v0.5.0. Cookie policy address. `http(s)` only; anything else is ignored |
 | `texts.detailsAction` | `"policy" \| "settings" \| "hide" \| "declaration"` | see notes | v0.5.0, `declaration` in v0.5.7. What «Learn more» does. Defaults to `policy` when `policyUrl` is set, `settings` when it is not. `policy` or `declaration` without a usable URL falls back to `settings` rather than rendering a dead link |
 | `texts.declarationUrl` | `string` | — | v0.5.7. Address of the cookie declaration page, used by `detailsAction: "declaration"`. `http(s)` only. Filled by the hosted service; the client only reads it |
@@ -274,18 +275,25 @@ accept is a dark pattern, and consent collected through one is not freely
 given, so the config simply cannot express it. `settings` is independent and
 may itself be filled.
 
-**Contrast is enforced automatically and cannot be switched off.** A colour
-combination that would be unreadable is corrected before it reaches the
-stylesheet:
-
-- button text keeps the colour you set only when it clears **4.5:1** against
-  the fill it sits on; otherwise it becomes white or `#161616`, whichever
-  contrasts more;
-- an `outline` border is darkened (light card) or lightened (dark card) in
-  small steps until it clears **3:1** against the card, so it stays
-  recognisably your colour rather than jumping to black or white;
-- that resolved border colour is then the outline button's text colour,
-  subject to the same 4.5:1 rule.
+**A colour you set is painted as you set it; contrast rules decide only the
+colours you left to us.** Since v0.5.10 the **4.5:1** text rule and the **3:1**
+border rule apply to *derived* values — the automatic text on a filled button,
+the border and text an `outline` button takes from `theme.accent`, the link
+colour read off the accent. A `fg`, `border` or `onAccent` you wrote yourself
+is never repainted, however low it measures: the debug panel reports the ratio
+and warns («контраст 4.32 — ниже рекомендуемых 4.5»), and the choice stays
+yours. Concretely:
+
+- a `fg` you set is painted as set and only measured against the fill behind
+  it; the *derived* text on a filled button still becomes white or `#161616`,
+  whichever contrasts more, when it would fall under 4.5:1;
+- a `border` you set on an `outline` button is painted as set; a border
+  *derived* from `theme.accent` is darkened (light card) or lightened (dark
+  card) in small steps until it clears 3:1 against the card, so a default theme
+  can never produce a button invisible against its own card;
+- an outline button's text, when you did not set one, is that resolved border
+  colour put through the same 4.5:1 rule — derived even when the border it came
+  from was yours.
 
 The card is `#ffffff` in light mode and `#1c1c1e` in dark. A colour the
 arithmetic cannot read — a CSS colour name, an `rgb()` string — is left exactly
@@ -298,7 +306,11 @@ The same arithmetic is exposed as pure functions on `ConsentKit._contrast`
 instead of reimplementing them. It is present whenever `src/ck-ui.js` is loaded,
 and it is safe to call in Node — nothing in it touches the DOM. The debug
 panel's **Appearance** section reads it directly and reports each button's
-resolved colours, its contrast ratio, and whether the value was adjusted.
+resolved colours, its contrast ratio, and either that a derived value was
+adjusted or that a value you set measures below the recommended floor. Each
+resolved record carries `ratio` and `adjusted`, plus `low` (painted text under
+4.5:1) and, for outline buttons, `borderRatio`, `borderAdjusted` and
+`borderLow` (border under 3:1).
 
 ### The «Learn more» link
 

package/npm/internal-stub.mjs

@@ -28,7 +28,7 @@ export function undecidedState() {
  */
 export function createStub() {
   const stub = {
-    version: '0.5.9',
+    version: '0.5.10',
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecomconsult/consentkit",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "GDPR cookie consent core with blocking engine, Shadow DOM UI and Google Consent Mode v2. Zero dependencies, no build step.",
   "repository": {
     "type": "git",

package/src/ck-core.js

@@ -1941,7 +1941,7 @@
   // Public API
   // ---------------------------------------------------------------------------
   var ConsentKit = {
-    version: '0.5.9',
+    version: '0.5.10',
     config: config,
 
     init: function (userConfig) {

package/src/ck-debug.js

@@ -322,6 +322,14 @@
       btnAdjusted: 'исправлено автоматически',
       btnOk: 'AA',
       btnFail: 'ниже AA',
+      // 0.5.10: a colour the owner set is painted as set, so a low ratio is a
+      // WARNING, not a correction. Split around the measured number because it
+      // is the whole point of the note — «ниже рекомендуемых» with no reading
+      // tells the owner nothing about how far below they are.
+      lowTextA: 'контраст ',
+      lowTextB: ' — ниже рекомендуемых 4.5, текст может читаться хуже',
+      lowBorderA: 'обводка ',
+      lowBorderB: ' — ниже 3, кнопка плохо видна',
       secActions: 'Действия',
       reset: 'Сбросить согласие',
       showPrefs: 'Показать настройки',
@@ -388,6 +396,10 @@
       btnAdjusted: 'adjusted automatically',
       btnOk: 'AA',
       btnFail: 'below AA',
+      lowTextA: 'contrast ',
+      lowTextB: ' — below the recommended 4.5, the text may be harder to read',
+      lowBorderA: 'border ',
+      lowBorderB: ' — below 3, the button is hard to see',
       secActions: 'Actions',
       reset: 'Reset consent',
       showPrefs: 'Show preferences',
@@ -459,6 +471,10 @@
       btnAdjusted: 'corectat automat',
       btnOk: 'AA',
       btnFail: 'sub AA',
+      lowTextA: 'contrast ',
+      lowTextB: ' — sub 4.5 recomandat, textul poate fi mai greu de citit',
+      lowBorderA: 'contur ',
+      lowBorderB: ' — sub 3, butonul se vede greu',
       secActions: 'Acțiuni',
       reset: 'Resetează consimțământul',
       showPrefs: 'Arată setările',
@@ -1035,7 +1051,8 @@
           lkTxt = lk.color + ' ' + T.btnOn + ' ' + lk.against +
             ' · ' + fmtRatio(lk.ratio) +
             ' ' + ((typeof lk.ratio === 'number' && lk.ratio >= 4.5) ? T.btnOk : T.btnFail) +
-            (lk.adjusted ? ' · ' + T.btnAdjusted : '');
+            (lk.adjusted ? ' · ' + T.btnAdjusted : '') +
+            (lk.low ? ' · ' + T.lowTextA + fmtRatio(lk.ratio) + T.lowTextB : '');
         }
 
         sT.appendChild(defs([
@@ -1062,9 +1079,21 @@
             (b.variant === 'outline'
               ? ' · ' + T.btnBorder + ' ' + b.border + ' (' + fmtRatio(b.borderRatio) + ')'
               : '')));
+          // «исправлено» only where something WAS in fact replaced. Since
+          // 0.5.10 a colour the owner set is painted as set, and its shortfall
+          // is reported as a plain warning with the measured number instead —
+          // the panel must never claim to have corrected what it left alone.
           if (b.adjusted) {
             li.appendChild(el('span', { class: 'mut' }, ' · ' + T.btnAdjusted));
           }
+          if (b.low) {
+            li.appendChild(el('span', { class: 'mut' },
+              ' · ' + T.lowTextA + fmtRatio(b.ratio) + T.lowTextB));
+          }
+          if (b.borderLow) {
+            li.appendChild(el('span', { class: 'mut' },
+              ' · ' + T.lowBorderA + fmtRatio(b.borderRatio) + T.lowBorderB));
+          }
           uT.appendChild(li);
         });
         sT.appendChild(uT);

package/src/ck-ui.js

@@ -842,10 +842,14 @@
   var WHITE = '#ffffff';
   var NEAR_BLACK = '#161616';   // SPEC §1: white or #161616, whichever contrasts more
 
-  /* SPEC §1, the TEXT rule: keep the author's fg when it clears `min` against
-     bg; otherwise swap to white or #161616 — whichever wins. Unreadable input
+  /* SPEC §1, the TEXT rule: keep `fg` when it clears `min` against bg;
+     otherwise swap to white or #161616 — whichever wins. Unreadable input
      (a colour name, rgb(), a missing value) is returned untouched with
-     adjusted:false: the author sees their own colour, not a silent rewrite. */
+     adjusted:false rather than guessed at.
+
+     Since 0.5.10 this is only ever handed a DERIVED colour — resolveButtonStyles
+     keeps an explicitly set one out of here entirely — so the swap can no longer
+     overwrite something the owner chose. */
   function ensureContrast(fg, bg, min) {
     var floor = typeof min === 'number' && min > 0 ? min : 4.5;
     var have = contrastRatio(fg, bg);
@@ -861,7 +865,10 @@
      against the CARD background, so the button is visible as a button at all.
      Stepwise rather than a jump to black/white: a brand colour that is only
      slightly too pale should stay recognisably the brand colour. Direction is
-     chosen by which way there is room to move — away from the card. */
+     chosen by which way there is room to move — away from the card.
+
+     Since 0.5.10 only a DERIVED border reaches this: a border the owner set is
+     painted as set and merely measured. */
   function stepToContrast(color, bg, min) {
     var floor = typeof min === 'number' && min > 0 ? min : 3;
     var have = contrastRatio(color, bg);
@@ -1221,7 +1228,14 @@
      числа": nothing recomputes these numbers a second time.
 
      `palette` is optional and lets buildThemeCss pass the ALREADY-RESOLVED
-     accent/card colours for the mode, so a theme.dark.accent is honoured. */
+     accent/card colours for the mode, so a theme.dark.accent is honoured.
+
+     OWNER'S RULE (0.5.10): a colour the owner EXPLICITLY SET is painted as set.
+     The >= 4.5 text rule and the >= 3 border rule may only decide colours the
+     owner did NOT choose — the automatic text on a filled button, the border
+     and text derived from the accent on an outline one. A typed colour that
+     falls short is reported (`low` / `borderLow`) so the debug panel and the
+     cabinet can WARN about it, never corrected behind the owner's back. */
   function resolveButtonStyles(theme, mode, palette) {
     var t = (theme && typeof theme === 'object') ? theme : {};
     var base = mode === 'dark' ? DARK : LIGHT;
@@ -1229,9 +1243,12 @@
 
     var cardBg = sanitizeCssValue('color', pal.bg, base.bg);
     var accent = sanitizeCssValue('color', pal.accent, base.accent);
-    // theme.dark.onAccent stays meaningful: it is the GIVEN fg for filled
-    // buttons in that mode. The >= 4.5 rule may still override it.
+    // theme.dark.onAccent / theme.light.onAccent is the GIVEN fg for filled
+    // buttons in that mode. When the owner set it, it counts as an explicit
+    // colour and is painted as set; the built-in default is derived and stays
+    // subject to the >= 4.5 rule.
     var onAccent = sanitizeCssValue('color', pal.onAccent, base.onAccent);
+    var onAccentExplicit = pal.onAccentExplicit === true;
 
     var cfg = (t.buttons && typeof t.buttons === 'object') ? t.buttons : {};
 
@@ -1258,7 +1275,12 @@
        button's icon all read the token this produces, so none of them can
        drift from what the debug panel and the cabinet quote. Note the
        measurement is against cardBg — an accent that is fine inside a filled
-       button can still be unreadable on the card behind it. */
+       button can still be unreadable on the card behind it.
+
+       Still corrected in 0.5.10, deliberately: the ACCENT is the owner's, but
+       the LINK colour is derived from it — nobody typed "links are this
+       colour". The accent itself is never repainted, so the owner still sees
+       the brand colour everywhere they actually chose it. */
     var linkRes = ensureContrast(accent, cardBg, 4.5);
 
     var out = {
@@ -1269,11 +1291,35 @@
         color: linkRes.color,
         ratio: linkRes.ratio,
         adjusted: linkRes.adjusted,
+        // A link is always derived, so this is normally false — the rule
+        // already lifted it. It can still be true on a mid-tone custom card
+        // where even the better of white and #161616 falls short of 4.5.
+        low: (typeof linkRes.ratio === 'number' && linkRes.ratio < 4.5),
         against: cardBg
       },
       buttons: {}
     };
 
+    /* "Did the owner explicitly set this colour?" — the gate on the whole
+       0.5.10 rule, and it cannot be a plain `str(c.fg)` test. sanitizeCssValue
+       silently returns the FALLBACK for a hostile or malformed value, so a
+       value that failed the grammar would otherwise be painted as "the owner's
+       choice" with no correction at all — the injected-colour case would lose
+       its contrast check as well as its value. Sanitising against a sentinel
+       tells the two apart: a value that survives is the owner's, anything else
+       falls through to the derived path exactly as before 0.5.10. */
+    var NOT_SET = '\x00';
+    function explicitColor(v) {
+      var got = sanitizeCssValue('color', v, NOT_SET);
+      return got === NOT_SET ? null : got;
+    }
+    // A measured ratio is `null` for a colour the arithmetic cannot read (a CSS
+    // name, an rgb() string). That is "no verdict", not "below the floor", so it
+    // must not raise the warning flag — the panel would print a note with no number.
+    function below(ratio, floor) {
+      return typeof ratio === 'number' && ratio < floor;
+    }
+
     for (var i = 0; i < BTN_ROLES.length; i++) {
       var role = BTN_ROLES[i];
       var c = (cfg[role] && typeof cfg[role] === 'object') ? cfg[role] : {};
@@ -1283,40 +1329,86 @@
       var rec;
 
       if (variant === 'filled') {
-        // bg: author's, else the accent. fg: author's, else onAccent for the
-        // default accent fill, then checked against the resolved bg.
+        // bg: author's, else the accent — always painted as given either way.
         var bg = sanitizeCssValue('color', c.bg, accent);
-        var wantFg = sanitizeCssValue('color', c.fg, onAccent);
-        var fgRes = ensureContrast(wantFg, bg, 4.5);
         var bd = sanitizeCssValue('color', c.border, bg);
+        // fg: an EXPLICIT colour (the button's own, or an owner-set onAccent
+        // for the mode) is painted as set and only measured. Only the derived
+        // default goes through the >= 4.5 rule.
+        var setFg = explicitColor(c.fg) || (onAccentExplicit ? onAccent : null);
+        var fgColor, fgRatio, fgAdjusted;
+        if (setFg) {
+          fgColor = setFg;
+          fgRatio = contrastRatio(setFg, bg);
+          fgAdjusted = false;
+        } else {
+          var fgRes = ensureContrast(onAccent, bg, 4.5);
+          fgColor = fgRes.color;
+          fgRatio = fgRes.ratio;
+          fgAdjusted = fgRes.adjusted;
+        }
         rec = {
           variant: 'filled',
           bg: bg,
-          fg: fgRes.color,
+          fg: fgColor,
           border: bd,
           borderWidth: bw,
-          ratio: fgRes.ratio,
-          adjusted: fgRes.adjusted,
+          ratio: fgRatio,
+          adjusted: fgAdjusted,
+          // Warn-only: true when the PAINTED text falls under 4.5:1 —
+          // usually a typed colour (the owner's own trade-off), but also a
+          // CORRECTED one on a mid-tone fill near #767676, where neither
+          // white nor #161616 reaches 4.5 and the better of the two still fails.
+          low: below(fgRatio, 4.5),
           against: bg
         };
       } else {
         // outline: transparent fill, so everything is measured against the CARD.
-        // border >= 3:1 with the card (stepped), text = the border colour with
-        // the >= 4.5 rule against the card.
-        var wantBd = sanitizeCssValue('color', c.border, accent);
-        var bdRes = stepToContrast(wantBd, cardBg, 3);
-        var wantTx = str(c.fg) ? sanitizeCssValue('color', c.fg, bdRes.color) : bdRes.color;
-        var txRes = ensureContrast(wantTx, cardBg, 4.5);
+        // A border the owner TYPED is painted as typed and only measured; one
+        // DERIVED from the accent is still stepped to >= 3:1 so a default-themed
+        // button cannot vanish into the card.
+        var setBd = explicitColor(c.border);
+        var bdColor, bdRatio, bdAdjusted;
+        if (setBd) {
+          bdColor = setBd;
+          bdRatio = contrastRatio(setBd, cardBg);
+          bdAdjusted = false;
+        } else {
+          var bdRes = stepToContrast(accent, cardBg, 3);
+          bdColor = bdRes.color;
+          bdRatio = bdRes.ratio;
+          bdAdjusted = bdRes.adjusted;
+        }
+        // Text: the owner's when set, otherwise the resolved border colour put
+        // through the >= 4.5 rule — that text is derived even when the border
+        // it came from was typed, so it is still corrected.
+        var setTx = explicitColor(c.fg);
+        var txColor, txRatio, txAdjusted;
+        if (setTx) {
+          txColor = setTx;
+          txRatio = contrastRatio(setTx, cardBg);
+          txAdjusted = false;
+        } else {
+          var txRes = ensureContrast(bdColor, cardBg, 4.5);
+          txColor = txRes.color;
+          txRatio = txRes.ratio;
+          txAdjusted = txRes.adjusted;
+        }
         rec = {
           variant: 'outline',
           bg: sanitizeCssValue('color', c.bg, 'transparent'),
-          fg: txRes.color,
-          border: bdRes.color,
+          fg: txColor,
+          border: bdColor,
           borderWidth: bw,
-          ratio: txRes.ratio,
-          adjusted: txRes.adjusted || bdRes.adjusted,
-          borderRatio: bdRes.ratio,
-          borderAdjusted: bdRes.adjusted,
+          ratio: txRatio,
+          // `adjusted` now tracks the TEXT alone. A typed border that was kept
+          // must not make the row say «исправлено» about a colour nobody
+          // touched; the border reports itself through borderAdjusted.
+          adjusted: txAdjusted,
+          low: below(txRatio, 4.5),
+          borderRatio: bdRatio,
+          borderAdjusted: bdAdjusted,
+          borderLow: below(bdRatio, 3),
           against: cardBg
         };
       }
@@ -1381,6 +1473,11 @@
   function buildThemeCss(cfg) {
     var theme = (cfg && cfg.theme) || {};
     var dk = (theme.dark && typeof theme.dark === 'object') ? theme.dark : {};
+    // theme.light is the mirror of theme.dark and exists for one value: an
+    // onAccent the owner set for the light mode. Without it a light-mode
+    // filled button had no way to state its text colour once for all three
+    // buttons, and theme.dark could do what theme.light could not.
+    var lt = (theme.light && typeof theme.light === 'object') ? theme.light : {};
 
     var radius = resolveRadius(theme);
     var font = resolveFont(theme);
@@ -1390,6 +1487,11 @@
       sanitizeCssValue('color', theme.bg, LIGHT.bg),
       sanitizeCssValue('color', theme.ink, LIGHT.ink));
     if (str(theme.accent)) light.accent = sanitizeCssValue('color', theme.accent, LIGHT.accent);
+    // An onAccent that SURVIVES the grammar is the owner's word on the filled
+    // buttons' text and is painted as given; one that fails it falls back to
+    // the built-in default, which is derived and still gets corrected.
+    var ltOn = sanitizeCssValue('color', lt.onAccent, null);
+    if (ltOn) { light.onAccent = ltOn; light.onAccentExplicit = true; }
 
     // Dark: theme.dark overrides on top of the built-in dark palette.
     // A light-only theme.accent deliberately does NOT carry into dark — the
@@ -1398,7 +1500,8 @@
       sanitizeCssValue('color', dk.bg, DARK.bg),
       sanitizeCssValue('color', dk.ink, DARK.ink));
     if (str(dk.accent)) dark.accent = sanitizeCssValue('color', dk.accent, DARK.accent);
-    if (str(dk.onAccent)) dark.onAccent = sanitizeCssValue('color', dk.onAccent, DARK.onAccent);
+    var dkOn = sanitizeCssValue('color', dk.onAccent, null);
+    if (dkOn) { dark.onAccent = dkOn; dark.onAccentExplicit = true; }
 
     // Buttons are resolved per mode against that mode's real card colour, so a
     // custom dark card changes the outline border the same way a custom light
@@ -1407,6 +1510,16 @@
     var darkBtn = resolveButtonStyles(theme, 'dark', dark);
     light.__buttons = lightBtn.buttons;
     dark.__buttons = darkBtn.buttons;
+
+    // `--ck-on-accent` paints the text of every filled surface that is NOT a
+    // banner button — the panel's «Сохранить выбор» and the floating button —
+    // straight from the palette. A derived onAccent therefore has to pass the
+    // same >= 4.5 rule against the accent, or a white accent gets white text
+    // (the owner saw exactly that). Done AFTER the buttons are resolved, so
+    // the accept button still records `adjusted:true` for the same correction.
+    // An onAccent the owner set is painted as set — the 0.5.10 rule.
+    if (!light.onAccentExplicit) light.onAccent = ensureContrast(light.onAccent, light.accent, 4.5).color;
+    if (!dark.onAccentExplicit) dark.onAccent = ensureContrast(dark.onAccent, dark.accent, 4.5).color;
     light.__link = lightBtn.link;
     dark.__link = darkBtn.link;