@rolemodel/optics 2.5.1 → 2.6.1

package/dist/package.json

@@ -1,28 +1,32 @@
 {
   "name": "@rolemodel/optics",
-  "version": "2.5.1",
+  "version": "2.6.1",
   "packageManager": "yarn@4.8.1",
   "description": "Optics is a css package that provides base styles and components that can be integrated and customized in a variety of projects.",
   "main": "dist/css/optics.css",
+  "bin": {
+    "optics-check-contrast": "dist/tools/check-contrast.cjs"
+  },
   "scripts": {
-    "test": "exit 0",
+    "test": "node --test 'test/**/*.test.cjs'",
     "build": "yarn build:css && yarn build:css-min && yarn build:tokens && yarn build:files",
     "build:css": "postcss 'src/optics*.css' -d dist/css",
     "build:css-min": "postcss 'src/optics*.css' -d dist/css --ext .min.css --env=minify",
     "build:tokens": "node build_token_json --source=src/core/tokens --output=dist/tokens/tokens.json",
-    "build:files": "mkdir -p dist/css/addons; cp LICENSE README.md package.json dist/; cp -rL src/addons src/core src/components dist/css",
+    "build:files": "mkdir -p dist/css/addons; cp LICENSE README.md package.json dist/; cp -rL src/addons src/core src/components dist/css; cp -r src/tools dist",
     "build-docs": "yarn build-docs:llms && yarn build-docs:storybook",
     "build-docs:llms": "node --disable-warning=MODULE_TYPELESS_PACKAGE_JSON tools/build-llms-docs.mjs",
     "build-docs:storybook": "storybook build --docs",
-    "storybook": "storybook dev -p 6006 --docs",
+    "storybook": "yarn build-docs:llms && storybook dev -p 6006 --docs",
     "lint": "yarn lint:js && yarn lint:css",
     "lint-fix": "yarn lint:js --fix && yarn lint:css --fix",
     "lint:js": "eslint 'src/stories/**/*.js'",
     "lint:css": "stylelint 'src/**/*.css'",
     "prettier": "prettier -w .",
     "prettier-check": "prettier -c .",
-    "sanity-check": "yarn lint && yarn prettier && yarn build && yarn build-docs && rm -rf ./dist && rm -rf ./storybook-static && rm -rf ./llms-docs",
-    "generate": "node ./tools/generate.js"
+    "sanity-check": "yarn lint && yarn prettier && yarn test && yarn build && yarn check-contrast && yarn build-docs && rm -rf ./dist && rm -rf ./storybook-static && rm -rf ./llms-docs",
+    "generate": "node ./tools/generate.js",
+    "check-contrast": "node dist/tools/check-contrast.cjs"
   },
   "repository": {
     "type": "git",

package/dist/tokens/tokens.json

@@ -41,9 +41,23 @@
 					"original": "hsl(var(--op-color-alerts-notice-h) var(--op-color-alerts-notice-s) var(--op-color-alerts-notice-l))"
 				}
 			},
-			"border": "var(--op-color-neutral-plus-five)",
 			"background": "var(--op-color-neutral-plus-eight)",
-			"on-background": "var(--op-color-neutral-on-plus-eight)"
+			"on-background": "var(--op-color-neutral-on-plus-eight)",
+			"border": "var(--op-color-neutral-plus-five)"
+		},
+		"shadow": {
+			"x-small": "0 1px 3px hsl(0deg 0% 0% / 15%), 0 1px 2px hsl(0deg 0% 0% / 30%)",
+			"small": "0 2px 6px hsl(0deg 0% 0% / 15%), 0 1px 2px hsl(0deg 0% 0% / 30%)",
+			"medium": "0 4px 8px hsl(0deg 0% 0% / 15%), 0 1px 3px hsl(0deg 0% 0% / 30%)",
+			"large": "0 6px 10px hsl(0deg 0% 0% / 15%), 0 2px 3px hsl(0deg 0% 0% / 30%)",
+			"x-large": "0 8px 12px hsl(0deg 0% 0% / 15%), 0 4px 4px hsl(0deg 0% 0% / 30%)"
+		},
+		"encoded": {
+			"images": {
+				"dropdown": {
+					"arrow": "url('data"
+				}
+			}
 		},
 		"opacity": {
 			"none": "0",
@@ -134,13 +148,6 @@
 		"animation": {
 			"flash": "rm-slide-in-out-flash 5s normal forwards"
 		},
-		"encoded": {
-			"images": {
-				"dropdown": {
-					"arrow": "url('data"
-				}
-			}
-		},
 		"size": {
 			"unit": "0.4rem"
 		},
@@ -157,13 +164,6 @@
 			"3x-large": "calc(var(--op-space-scale-unit) * 4)",
 			"4x-large": "calc(var(--op-space-scale-unit) * 8)"
 		},
-		"shadow": {
-			"x-small": "0 1px 3px hsl(0deg 0% 0% / 15%), 0 1px 2px hsl(0deg 0% 0% / 30%)",
-			"small": "0 2px 6px hsl(0deg 0% 0% / 15%), 0 1px 2px hsl(0deg 0% 0% / 30%)",
-			"medium": "0 4px 8px hsl(0deg 0% 0% / 15%), 0 1px 3px hsl(0deg 0% 0% / 30%)",
-			"large": "0 6px 10px hsl(0deg 0% 0% / 15%), 0 2px 3px hsl(0deg 0% 0% / 30%)",
-			"x-large": "0 8px 12px hsl(0deg 0% 0% / 15%), 0 4px 4px hsl(0deg 0% 0% / 30%)"
-		},
 		"z-index": {
 			"header": "500",
 			"footer": "500",

package/dist/tools/check-contrast.cjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Checks WCAG 2.1 contrast between every Optics scale step and its `on` text
+ * colors, in light and dark mode (or just one, with --mode), for your theme:
+ *
+ *   --op-color-primary-plus-five  vs  --op-color-primary-on-plus-five      (needs --min)
+ *   --op-color-primary-plus-five  vs  --op-color-primary-on-plus-five-alt  (needs --alt-min)
+ *
+ * Usage:
+ *   optics-check-contrast [files...] [--hsl | --oklch] [--mode=light | --mode=dark] [--min=4.5] [--alt-min=4.5] [--report]
+ *
+ *   files      CSS with your --op-* overrides: theme files, or your compiled CSS bundle.
+ *              They are applied on top of the Optics tokens, the last value of each token wins.
+ *   --hsl      Check against the HSL tokens (optics.css). Detected from -s / hsl() in your files.
+ *   --oklch    Check against the OKLCH tokens (optics-oklch.css). Detected from -c / oklch().
+ *   --mode     Check only light or dark mode. Both are checked by default.
+ *   --report   List every pair, and don't fail.
+ *
+ * Tokens are read without their selectors, so overrides scoped to a class or
+ * attribute are treated as if they were on :root. Colors outside sRGB are
+ * clipped, as browsers do. Exits with 1 if any pair fails, and 2 if the theme can't be read
+ * or a color can't be measured (translucent colors, or calc() that isn't plain numbers).
+ */
+// CommonJS, because Yarn Plug'n'Play can't load an ES module bin from inside its zip cache.
+const Build = require('./contrast/builds/build.cjs')
+const CheckError = require('./contrast/check-error.cjs')
+const ContrastCheck = require('./contrast/contrast-check.cjs')
+const ContrastReporter = require('./contrast/contrast-reporter.cjs')
+const Stylesheet = require('./contrast/stylesheet.cjs')
+const Theme = require('./contrast/theme.cjs')
+const ToolOptions = require('./contrast/tool-options.cjs')
+
+try {
+  const options = ToolOptions.parse(process.argv.slice(2))
+  const userCss = Stylesheet.read(options.files)
+  const build = Build.for(options, userCss)
+  const theme = Theme.cascade(build.stylesheet(), userCss)
+  const check = new ContrastCheck(theme, options)
+  const reporter = new ContrastReporter(process.stdout, build, options)
+
+  for (const result of check.results()) reporter.record(result)
+  process.exitCode = reporter.finish()
+} catch (error) {
+  if (!(error instanceof CheckError)) throw error
+  console.error(`optics-check-contrast: ${error.message}`)
+  process.exit(2)
+}

package/dist/tools/contrast/builds/build.cjs

@@ -0,0 +1,44 @@
+const path = require('node:path')
+const CheckError = require('../check-error.cjs')
+const Stylesheet = require('../stylesheet.cjs')
+
+const TOKENS_DIR = path.join(__dirname, '../../../css/core/tokens')
+const AMBIGUOUS = 'Could not tell if your theme is HSL or OKLCH. Pass --hsl or --oklch.'
+
+// An Optics build (optics.css or optics-oklch.css). Each subclass names its color token folder
+// and the CSS that marks a theme as written for it.
+class Build {
+  // Optics channel vars (-c or -s) decide first; color functions only when neither is set,
+  // so an unrelated oklch() or hsl() elsewhere in the CSS can't pick the wrong build.
+  static for({ buildName }, stylesheet) {
+    const builds = all()
+    if (buildName) return builds.find((build) => build.name === buildName)
+
+    const byChannel = builds.filter((build) => stylesheet.mentions(build.channelVariable))
+    if (byChannel.length > 1) throw new CheckError(AMBIGUOUS)
+    if (byChannel.length === 1) return byChannel[0]
+
+    const byFunction = builds.find((build) => stylesheet.mentions(build.colorFunction))
+    if (byFunction) return byFunction
+    if (stylesheet.isEmpty) return builds[0]
+    throw new CheckError(AMBIGUOUS)
+  }
+
+  stylesheet() {
+    const colorDir = path.join(TOKENS_DIR, this.colorFolder)
+    return Stylesheet.read([
+      // Used by both builds, and defines aliases like --op-color-border.
+      path.join(TOKENS_DIR, 'shared_tokens.css'),
+      path.join(colorDir, 'base_color_tokens.css'),
+      path.join(colorDir, 'scale_color_tokens.css'),
+    ])
+  }
+}
+
+// OKLCH comes first: it is the default with no theme, and a theme that uses both oklch() and hsl() is checked as OKLCH.
+// Required on first use, not at the top, because each subclass requires this file to extend Build.
+function all() {
+  return [new (require('./oklch-build.cjs'))(), new (require('./hsl-build.cjs'))()]
+}
+
+module.exports = Build

package/dist/tools/contrast/builds/hsl-build.cjs

@@ -0,0 +1,11 @@
+const Build = require('./build.cjs')
+
+// optics.css. Its color tokens are in the top-level tokens folder.
+class HslBuild extends Build {
+  name = 'hsl'
+  colorFolder = ''
+  channelVariable = /--op-color-[a-z0-9-]+-s\s*:/
+  colorFunction = /hsla?\(/
+}
+
+module.exports = HslBuild

package/dist/tools/contrast/builds/oklch-build.cjs

@@ -0,0 +1,11 @@
+const Build = require('./build.cjs')
+
+// optics-oklch.css.
+class OklchBuild extends Build {
+  name = 'oklch'
+  colorFolder = 'oklch'
+  channelVariable = /--op-color-[a-z0-9-]+-c\s*:/
+  colorFunction = /oklch\(/
+}
+
+module.exports = OklchBuild

package/dist/tools/contrast/calc-expression.cjs

@@ -0,0 +1,68 @@
+const CheckError = require('./check-error.cjs')
+
+// calc() with only numbers and operators inside. No parentheses, so the innermost calc() matches first.
+const PLAIN_CALC = /calc\(([\d.\s*/+-]+)\)/g
+const TOKEN = /\d+\.?\d*|\.\d+|\S/g
+
+// One calc() of plain numbers. Evaluates + - * / with the usual precedence, and leading + or - signs.
+class CalcExpression {
+  #source
+  #tokens
+  #position = 0
+
+  // Replaces each calc() of plain numbers with its result, innermost first, until none are left.
+  static resolveAll(value) {
+    let resolved = value
+    let previous
+    do {
+      previous = resolved
+      resolved = resolved.replace(PLAIN_CALC, (source, math) => String(new CalcExpression(source, math).evaluate()))
+    } while (resolved !== previous)
+    return resolved
+  }
+
+  constructor(source, math) {
+    this.#source = source
+    this.#tokens = math.match(TOKEN) ?? []
+  }
+
+  evaluate() {
+    const result = this.#sum()
+    return this.#position === this.#tokens.length ? result : this.#fail()
+  }
+
+  #sum() {
+    let result = this.#product()
+    while (this.#next === '+' || this.#next === '-')
+      result = this.#take() === '+' ? result + this.#product() : result - this.#product()
+    return result
+  }
+
+  #product() {
+    let result = this.#signed()
+    while (this.#next === '*' || this.#next === '/')
+      result = this.#take() === '*' ? result * this.#signed() : result / this.#signed()
+    return result
+  }
+
+  #signed() {
+    const token = this.#take()
+    if (token === '+') return this.#signed()
+    if (token === '-') return -this.#signed()
+    return /\d/.test(token ?? '') ? Number(token) : this.#fail()
+  }
+
+  get #next() {
+    return this.#tokens[this.#position]
+  }
+
+  #take() {
+    return this.#tokens[this.#position++]
+  }
+
+  #fail() {
+    throw new CheckError(`Can't calculate: ${this.#source}`)
+  }
+}
+
+module.exports = CalcExpression

package/dist/tools/contrast/check-error.cjs

@@ -0,0 +1,4 @@
+// A theme that can't be read or measured. The CLI reports it and exits with 2.
+class CheckError extends Error {}
+
+module.exports = CheckError

package/dist/tools/contrast/color-pair.cjs

@@ -0,0 +1,35 @@
+// Only base and the plus/minus steps, so derived tokens like -on-base-alpha-40 aren't paired.
+const STEP = 'base|(?:plus|minus)-(?:one|two|three|four|five|six|seven|eight|max)'
+const ON_TOKEN = new RegExp(`^--op-color-([a-z0-9-]+?)-on-(${STEP})(-alt)?$`)
+
+// A scale step and a text color meant to sit on it:
+// --op-color-primary-plus-five with --op-color-primary-on-plus-five (or -on-plus-five-alt).
+class ColorPair {
+  #isAlt
+
+  // Every `on` and `on-alt` token in the theme whose scale step is also in the theme.
+  static findAll(theme) {
+    return theme.names().flatMap((text) => {
+      const match = text.match(ON_TOKEN)
+      if (!match) return []
+
+      const [, color, step, alt] = match
+      const background = `--op-color-${color}-${step}`
+      // has(), not the value's truthiness, so an empty override reaches color validation instead of dropping the pair.
+      return theme.has(background) ? [new ColorPair(background, text, Boolean(alt))] : []
+    })
+  }
+
+  constructor(background, text, isAlt) {
+    this.background = background
+    this.text = text
+    this.#isAlt = isAlt
+  }
+
+  // `on-alt` text has its own minimum, so a theme can allow AA large text there.
+  minimum({ min, altMin }) {
+    return this.#isAlt ? altMin : min
+  }
+}
+
+module.exports = ColorPair

package/dist/tools/contrast/colors/color.cjs

@@ -0,0 +1,41 @@
+const CheckError = require('../check-error.cjs')
+
+// A CSS color. Each subclass reads one format and gives its channels in linear sRGB.
+class Color {
+  // Picks the subclass whose `pattern` matches, and passes it the text inside the match.
+  static parse(text) {
+    const value = text.trim()
+    for (const Format of formats()) {
+      const match = value.match(Format.pattern)
+      if (match) return new Format(match[1], value)
+    }
+    throw new CheckError(`Can't check color: ${value || '(empty value)'}`)
+  }
+
+  // Converts a gamma-encoded sRGB channel (0 to 1) to linear light.
+  static linearize(channel) {
+    return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4
+  }
+
+  linearRgb() {
+    throw new Error(`${this.constructor.name} must implement linearRgb()`)
+  }
+
+  // WCAG relative luminance, from 0 to 1. Channels outside sRGB are clipped, as browsers do on most screens.
+  get luminance() {
+    const [r, g, b] = this.linearRgb().map((channel) => Math.min(1, Math.max(0, channel)))
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+  }
+
+  contrastWith(other) {
+    const [first, second] = [this.luminance, other.luminance]
+    return (Math.max(first, second) + 0.05) / (Math.min(first, second) + 0.05)
+  }
+}
+
+// Required on first use, not at the top, because each subclass requires this file to extend Color.
+function formats() {
+  return [require('./hex-color.cjs'), require('./oklch-color.cjs'), require('./hsl-color.cjs')]
+}
+
+module.exports = Color

package/dist/tools/contrast/colors/function-color.cjs

@@ -0,0 +1,46 @@
+const CheckError = require('../check-error.cjs')
+const Color = require('./color.cjs')
+
+// A color written as a CSS function, like oklch(l c h / alpha) or the legacy hsl(h, s, l, alpha).
+// Translucent colors are rejected, because translucent text depends on what is behind it.
+class FunctionColor extends Color {
+  #channels
+
+  constructor(args, value) {
+    super()
+    const [channelText, slashAlpha] = args.split('/')
+    this.#channels = channelText.trim().split(/[\s,]+/)
+
+    const alpha = slashAlpha?.trim() ?? (channelText.includes(',') ? this.#channels[3] : undefined)
+    if (alpha === undefined) return
+    const opacity = fraction(alpha, 1)
+    // NaN < 1 is false, so an unresolved alpha would otherwise count as opaque.
+    if (!Number.isFinite(opacity)) throw new CheckError(`Can't measure alpha: ${value}`)
+    if (opacity < 1) throw new CheckError(`Can't check translucent color: ${value}`)
+  }
+
+  number(index) {
+    return parseFloat(this.#channels[index])
+  }
+
+  // The channel as a number, or as a percentage of `whole`.
+  fraction(index, whole) {
+    return fraction(this.#channels[index], whole)
+  }
+
+  // The channel as a hue in degrees from 0 to 360, from any CSS angle unit (deg is the default).
+  hue(index) {
+    const angle = this.#channels[index] ?? ''
+    const value = parseFloat(angle)
+    const unit = angle.match(/[a-z]+$/i)?.[0].toLowerCase()
+    const degrees = { rad: (value * 180) / Math.PI, grad: value * 0.9, turn: value * 360 }[unit] ?? value
+    return ((degrees % 360) + 360) % 360
+  }
+}
+
+function fraction(channel, whole) {
+  const number = parseFloat(channel)
+  return channel?.endsWith('%') ? (number / 100) * whole : number
+}
+
+module.exports = FunctionColor

package/dist/tools/contrast/colors/hex-color.cjs

@@ -0,0 +1,19 @@
+const Color = require('./color.cjs')
+
+// #rgb or #rrggbb.
+class HexColor extends Color {
+  static pattern = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i
+
+  #digits
+
+  constructor(digits) {
+    super()
+    this.#digits = digits.length === 3 ? [...digits].map((digit) => digit + digit).join('') : digits
+  }
+
+  linearRgb() {
+    return this.#digits.match(/../g).map((pair) => Color.linearize(parseInt(pair, 16) / 255))
+  }
+}
+
+module.exports = HexColor

package/dist/tools/contrast/colors/hsl-color.cjs

@@ -0,0 +1,25 @@
+const Color = require('./color.cjs')
+const FunctionColor = require('./function-color.cjs')
+
+// hsl() or hsla(), in the modern or the legacy comma syntax.
+class HslColor extends FunctionColor {
+  static pattern = /^hsla?\((.*)\)$/s
+
+  // CSS clamps out-of-range channels (e.g. hsl(240 200% 75%) is drawn at 100% saturation).
+  linearRgb() {
+    const hue = this.hue(0)
+    const saturation = this.#percent(1)
+    const lightness = this.#percent(2)
+    const channel = (n) => {
+      const k = (n + hue / 30) % 12
+      return lightness - saturation * Math.min(lightness, 1 - lightness) * Math.max(-1, Math.min(k - 3, 9 - k, 1))
+    }
+    return [channel(0), channel(8), channel(4)].map(Color.linearize)
+  }
+
+  #percent(index) {
+    return Math.min(1, Math.max(0, this.number(index) / 100))
+  }
+}
+
+module.exports = HslColor

package/dist/tools/contrast/colors/oklch-color.cjs

@@ -0,0 +1,36 @@
+const FunctionColor = require('./function-color.cjs')
+
+// In CSS, 100% chroma is 0.4.
+const FULL_CHROMA = 0.4
+
+class OklchColor extends FunctionColor {
+  static pattern = /^oklch\((.*)\)$/s
+
+  // OKLCH -> OKLab -> LMS -> linear sRGB (https://bottosson.github.io/posts/oklab/)
+  // CSS clamps out-of-range lightness and chroma.
+  linearRgb() {
+    const lightness = Math.min(1, Math.max(0, this.fraction(0, 1)))
+    const chroma = Math.max(0, this.fraction(1, FULL_CHROMA))
+    const hue = (this.hue(2) * Math.PI) / 180
+
+    // CSS gamut mapping draws 0% lightness as black and 100% as white, whatever the chroma and hue.
+    // Only when they are numbers, so an unresolved channel still stops the check as unmeasurable.
+    if (Number.isFinite(chroma) && Number.isFinite(hue)) {
+      if (lightness === 0) return [0, 0, 0]
+      if (lightness === 1) return [1, 1, 1]
+    }
+
+    const a = chroma * Math.cos(hue)
+    const b = chroma * Math.sin(hue)
+    const l = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3
+    const m = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3
+    const s = (lightness - 0.0894841775 * a - 1.291485548 * b) ** 3
+    return [
+      4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+      -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+      -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+    ]
+  }
+}
+
+module.exports = OklchColor

package/dist/tools/contrast/colors/themed-color.cjs

@@ -0,0 +1,37 @@
+const CheckError = require('../check-error.cjs')
+const Color = require('./color.cjs')
+const { splitAtFirstComma } = require('../css-syntax.cjs')
+
+const LIGHT_DARK = /^light-dark\((.*)\)$/s
+
+// A token's color in light and dark mode.
+class ThemedColor {
+  static MODES = ['light', 'dark']
+
+  #light
+  #dark
+
+  // light-dark(a, b) gives a in light mode and b in dark mode. Any other color is the same in both.
+  static parse(value) {
+    const inner = value.match(LIGHT_DARK)?.[1]
+    if (inner === undefined) {
+      const color = Color.parse(value)
+      return new ThemedColor(color, color)
+    }
+
+    const colors = splitAtFirstComma(inner)
+    if (colors.length !== 2) throw new CheckError(`Can't check color: ${value}`)
+    return new ThemedColor(Color.parse(colors[0]), Color.parse(colors[1]))
+  }
+
+  constructor(light, dark) {
+    this.#light = light
+    this.#dark = dark
+  }
+
+  in(mode) {
+    return mode === 'light' ? this.#light : this.#dark
+  }
+}
+
+module.exports = ThemedColor

package/dist/tools/contrast/contrast-check.cjs

@@ -0,0 +1,37 @@
+const CheckError = require('./check-error.cjs')
+const ColorPair = require('./color-pair.cjs')
+const ContrastResult = require('./contrast-result.cjs')
+const ThemedColor = require('./colors/themed-color.cjs')
+
+// Measures every scale step against its `on` and `on-alt` text colors, in light and dark mode, or just --mode.
+class ContrastCheck {
+  #theme
+  #options
+
+  constructor(theme, options) {
+    this.#theme = theme
+    this.#options = options
+  }
+
+  // Yields one result per pair and mode, so a report can print each one as it is measured.
+  *results() {
+    const modes = this.#options.mode ? [this.#options.mode] : ThemedColor.MODES
+    for (const pair of ColorPair.findAll(this.#theme)) {
+      const background = this.#colorOf(pair.background)
+      const text = this.#colorOf(pair.text)
+      for (const mode of modes) {
+        const ratio = background.in(mode).contrastWith(text.in(mode))
+        // NaN < min is false, so an unmeasurable pair would otherwise pass.
+        if (!Number.isFinite(ratio))
+          throw new CheckError(`Can't measure ${pair.text} (${mode}) against ${pair.background}`)
+        yield new ContrastResult(pair, mode, ratio, pair.minimum(this.#options))
+      }
+    }
+  }
+
+  #colorOf(token) {
+    return ThemedColor.parse(this.#theme.resolve(token))
+  }
+}
+
+module.exports = ContrastCheck

package/dist/tools/contrast/contrast-reporter.cjs

@@ -0,0 +1,44 @@
+// Writes the results to an output stream, and decides the exit code: 1 if any pair fails, unless --report was passed.
+class ContrastReporter {
+  #output
+  #build
+  #options
+  #count = 0
+  #failures = []
+
+  constructor(output, build, options) {
+    this.#output = output
+    this.#build = build
+    this.#options = options
+  }
+
+  record(result) {
+    this.#count++
+    if (!result.passes) this.#failures.push(result)
+    if (this.#options.report) this.#print(pairLine(result))
+  }
+
+  finish() {
+    const { mode, min, altMin, report } = this.#options
+    const passed = this.#count - this.#failures.length
+    const checked = mode ? ` (${mode})` : ''
+    this.#print(
+      `Optics ${this.#build.name} contrast${checked}: ${passed}/${this.#count} pairs pass (on >= ${min}, on-alt >= ${altMin})`
+    )
+    if (report || !this.#failures.length) return 0
+
+    for (const { pair, mode, ratio, minimum } of this.#failures)
+      this.#print(`  ${pair.text} (${mode}): ${ratio.toFixed(2)} < ${minimum}`)
+    return 1
+  }
+
+  #print(line) {
+    this.#output.write(`${line}\n`)
+  }
+}
+
+function pairLine({ pair, mode, ratio, passes }) {
+  return `${passes ? 'pass' : 'FAIL'}  ${ratio.toFixed(2).padStart(5)}  ${mode.padEnd(5)}  ${pair.text}`
+}
+
+module.exports = ContrastReporter

package/dist/tools/contrast/contrast-result.cjs

@@ -0,0 +1,15 @@
+// One pair measured in one mode.
+class ContrastResult {
+  constructor(pair, mode, ratio, minimum) {
+    this.pair = pair
+    this.mode = mode
+    this.ratio = ratio
+    this.minimum = minimum
+  }
+
+  get passes() {
+    return this.ratio >= this.minimum
+  }
+}
+
+module.exports = ContrastResult

package/dist/tools/contrast/css-syntax.cjs

@@ -0,0 +1,23 @@
+// Returns the index of the ")" that closes the "(" at openIndex, or -1 if it is never closed.
+function findClosingParen(text, openIndex) {
+  let depth = 0
+  for (let index = openIndex; index < text.length; index++) {
+    if (text[index] === '(') depth++
+    else if (text[index] === ')' && --depth === 0) return index
+  }
+  return -1
+}
+
+// Splits at the first comma outside parentheses: "a, b(c, d), e" -> ["a", " b(c, d), e"].
+function splitAtFirstComma(text) {
+  let depth = 0
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index]
+    if (char === '(') depth++
+    else if (char === ')') depth--
+    else if (char === ',' && depth === 0) return [text.slice(0, index), text.slice(index + 1)]
+  }
+  return [text]
+}
+
+module.exports = { findClosingParen, splitAtFirstComma }