@domandigital/craft 0.18.0 → 0.18.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @domandigital/craft
 
+## 0.18.1
+
+### Patch Changes
+
+- 72c3463: `gradientContrast` no longer blends across a hard stop. A gradient such as `linear-gradient(90deg, #000 50%, #fff 50%)` is painted as a jump from black to white, but 0.18.0 sampled the greys between them and could fail text that clears every colour the browser actually paints. Stop positions are now read, and a stop placed at or before an earlier position starts a hard edge that is not sampled, as in CSS. A painted blend is still sampled between its stops. Found by Codex review on Doman-Digital/dd-drift-guards#8, where the same fix landed.
+
 ## 0.18.0
 
 ### Minor Changes

package/README.md

@@ -213,7 +213,8 @@ restraint rule) and art direction (`craft direction`, `craft estate`).
   against the worst point. The worst point is sampled along every segment, not
   only at the stops: mid-grey text on a black-to-white gradient clears 4.5:1
   against both ends and is about 1:1 in the middle, which the drift-guards
-  version passed. WCAG defines no method for gradients, so this is craft's
+  version passed. A hard stop (`#000 50%, #fff 50%`) is a jump the browser
+  paints without a blend, so it is not sampled across. WCAG defines no method for gradients, so this is craft's
   rule, not a conformance claim.
 - **`checkPhotoReview(text, { minScore, required })`**: gates a build on the
   report `halide review --json` wrote. It takes the report's text (null when

package/dist/index.cjs

@@ -726,6 +726,9 @@ function composite(top, under) {
   };
 }
 function gradientStops(gradient) {
+  return parseStops(gradient).map((s) => s.colour);
+}
+function parseStops(gradient) {
   const inner = /gradient\(([\s\S]*)\)\s*$/.exec(gradient.trim());
   if (!inner) throw new Error(`not a CSS gradient: ${gradient}`);
   const parts2 = [];
@@ -744,27 +747,57 @@ function gradientStops(gradient) {
   if (current.trim()) parts2.push(current.trim());
   const stops = [];
   for (const part of parts2) {
-    const colour = part.replace(/(\s+-?[\d.]+(%|px|r?em|deg|turn|vw|vh))+\s*$/i, "").trim();
-    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(colour)) continue;
+    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(part)) continue;
+    const positions = [];
+    let colour = part;
+    for (let i = 0; i < 2; i++) {
+      const m = /\s+(-?[\d.]+)(%|px|r?em|vw|vh|deg|turn|rad|grad)\s*$/i.exec(colour);
+      if (!m) break;
+      positions.unshift({ value: parseFloat(m[1]), unit: m[2].toLowerCase() });
+      colour = colour.slice(0, m.index);
+    }
+    colour = colour.trim();
     if (!toRgba(colour)) throw new Error(`unreadable gradient stop "${colour}" in ${gradient}`);
-    stops.push(colour);
+    stops.push({ colour, positions });
   }
   if (stops.length === 0) throw new Error(`no colour stops in ${gradient}`);
   return stops;
 }
+function blendedSegments(stops) {
+  const entries = [];
+  for (const s of stops) {
+    const rgba = toRgba(s.colour);
+    if (s.positions.length === 0) entries.push({ rgba, pos: null });
+    for (const pos of s.positions) entries.push({ rgba, pos });
+  }
+  const furthest = {};
+  const pairs = [];
+  for (let i = 0; i + 1 < entries.length; i++) {
+    const pos = entries[i].pos;
+    if (pos) furthest[pos.unit] = Math.max(furthest[pos.unit] ?? -Infinity, pos.value);
+    const next = entries[i + 1].pos;
+    const hard = next !== null && furthest[next.unit] !== void 0 && next.value <= furthest[next.unit];
+    if (!hard) pairs.push([entries[i].rgba, entries[i + 1].rgba]);
+  }
+  return pairs;
+}
 function gradientContrast(text, gradient, beneath = "#ffffff") {
   const under = toRgba(beneath);
   if (!under || under.a < 1) throw new Error(`beneath must be an opaque colour, got ${beneath}`);
   const fg = toRgba(text);
   if (!fg || fg.a < 1) throw new Error(`text must be an opaque colour, got ${text}`);
   const textHex = formatHex(fg);
-  const raw = gradientStops(gradient).map((s) => toRgba(s));
-  const stops = raw.map((s) => formatHex(composite(s, under)));
+  const parsed = parseStops(gradient);
+  const stops = parsed.map((s) => formatHex(composite(toRgba(s.colour), under)));
   let worst = stops[0];
   let worstRatio = wcagContrast(textHex, worst);
-  for (let i = 0; i + 1 < raw.length; i++) {
-    for (let k = 1; k <= SAMPLES_PER_SEGMENT; k++) {
-      const point = formatHex(composite(mix(raw[i], raw[i + 1], k / SAMPLES_PER_SEGMENT), under));
+  for (const s of stops) {
+    const ratio = wcagContrast(textHex, s);
+    if (ratio < worstRatio) [worst, worstRatio] = [s, ratio];
+  }
+  for (const [a, b] of blendedSegments(parsed)) {
+    for (let k = 1; k < SAMPLES_PER_SEGMENT; k++) {
+      const point = formatHex(composite(mix(a, b, k / SAMPLES_PER_SEGMENT), under));
       const ratio = wcagContrast(textHex, point);
       if (ratio < worstRatio) [worst, worstRatio] = [point, ratio];
     }

package/dist/index.d.cts

@@ -178,7 +178,8 @@ declare function checkPair(text: string, background: string): ContrastCheck;
  * the backdrop's luminance comes closest to the text's: mid-grey text on a
  * black-to-white gradient clears 4.5:1 against both ends and about 1:1 in the
  * middle. So each segment is sampled, interpolated as browsers paint legacy
- * colours (sRGB, premultiplied alpha). Pure.
+ * colours (sRGB, premultiplied alpha), except across a hard stop
+ * (`#000 50%, #fff 50%`), where the browser paints a jump and no blend. Pure.
  */
 /** Samples per segment between two stops: under 1/255 of a channel apart for any pair. */
 declare const SAMPLES_PER_SEGMENT = 256;

package/dist/index.d.ts

@@ -178,7 +178,8 @@ declare function checkPair(text: string, background: string): ContrastCheck;
  * the backdrop's luminance comes closest to the text's: mid-grey text on a
  * black-to-white gradient clears 4.5:1 against both ends and about 1:1 in the
  * middle. So each segment is sampled, interpolated as browsers paint legacy
- * colours (sRGB, premultiplied alpha). Pure.
+ * colours (sRGB, premultiplied alpha), except across a hard stop
+ * (`#000 50%, #fff 50%`), where the browser paints a jump and no blend. Pure.
  */
 /** Samples per segment between two stops: under 1/255 of a channel apart for any pair. */
 declare const SAMPLES_PER_SEGMENT = 256;

package/dist/index.js

@@ -436,6 +436,9 @@ function composite(top, under) {
   };
 }
 function gradientStops(gradient) {
+  return parseStops(gradient).map((s) => s.colour);
+}
+function parseStops(gradient) {
   const inner = /gradient\(([\s\S]*)\)\s*$/.exec(gradient.trim());
   if (!inner) throw new Error(`not a CSS gradient: ${gradient}`);
   const parts2 = [];
@@ -454,27 +457,57 @@ function gradientStops(gradient) {
   if (current.trim()) parts2.push(current.trim());
   const stops = [];
   for (const part of parts2) {
-    const colour = part.replace(/(\s+-?[\d.]+(%|px|r?em|deg|turn|vw|vh))+\s*$/i, "").trim();
-    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(colour)) continue;
+    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(part)) continue;
+    const positions = [];
+    let colour = part;
+    for (let i = 0; i < 2; i++) {
+      const m = /\s+(-?[\d.]+)(%|px|r?em|vw|vh|deg|turn|rad|grad)\s*$/i.exec(colour);
+      if (!m) break;
+      positions.unshift({ value: parseFloat(m[1]), unit: m[2].toLowerCase() });
+      colour = colour.slice(0, m.index);
+    }
+    colour = colour.trim();
     if (!toRgba(colour)) throw new Error(`unreadable gradient stop "${colour}" in ${gradient}`);
-    stops.push(colour);
+    stops.push({ colour, positions });
   }
   if (stops.length === 0) throw new Error(`no colour stops in ${gradient}`);
   return stops;
 }
+function blendedSegments(stops) {
+  const entries = [];
+  for (const s of stops) {
+    const rgba = toRgba(s.colour);
+    if (s.positions.length === 0) entries.push({ rgba, pos: null });
+    for (const pos of s.positions) entries.push({ rgba, pos });
+  }
+  const furthest = {};
+  const pairs = [];
+  for (let i = 0; i + 1 < entries.length; i++) {
+    const pos = entries[i].pos;
+    if (pos) furthest[pos.unit] = Math.max(furthest[pos.unit] ?? -Infinity, pos.value);
+    const next = entries[i + 1].pos;
+    const hard = next !== null && furthest[next.unit] !== void 0 && next.value <= furthest[next.unit];
+    if (!hard) pairs.push([entries[i].rgba, entries[i + 1].rgba]);
+  }
+  return pairs;
+}
 function gradientContrast(text, gradient, beneath = "#ffffff") {
   const under = toRgba(beneath);
   if (!under || under.a < 1) throw new Error(`beneath must be an opaque colour, got ${beneath}`);
   const fg = toRgba(text);
   if (!fg || fg.a < 1) throw new Error(`text must be an opaque colour, got ${text}`);
   const textHex = formatHex(fg);
-  const raw = gradientStops(gradient).map((s) => toRgba(s));
-  const stops = raw.map((s) => formatHex(composite(s, under)));
+  const parsed = parseStops(gradient);
+  const stops = parsed.map((s) => formatHex(composite(toRgba(s.colour), under)));
   let worst = stops[0];
   let worstRatio = wcagContrast(textHex, worst);
-  for (let i = 0; i + 1 < raw.length; i++) {
-    for (let k = 1; k <= SAMPLES_PER_SEGMENT; k++) {
-      const point = formatHex(composite(mix(raw[i], raw[i + 1], k / SAMPLES_PER_SEGMENT), under));
+  for (const s of stops) {
+    const ratio = wcagContrast(textHex, s);
+    if (ratio < worstRatio) [worst, worstRatio] = [s, ratio];
+  }
+  for (const [a, b] of blendedSegments(parsed)) {
+    for (let k = 1; k < SAMPLES_PER_SEGMENT; k++) {
+      const point = formatHex(composite(mix(a, b, k / SAMPLES_PER_SEGMENT), under));
       const ratio = wcagContrast(textHex, point);
       if (ratio < worstRatio) [worst, worstRatio] = [point, ratio];
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/craft",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "private": false,
   "description": "The Doman Digital house craft standard as numbers: OKLCh colour ramps that snap to existing anchors, derived semantic tokens with measured WCAG and APCA contrast, one shared motion vocabulary for CSS and JS, and a base stylesheet. Zero dependencies.",
   "license": "Apache-2.0",