@rolemodel/optics 2.5.1 → 2.6.1

package/dist/tools/contrast/stylesheet.cjs

@@ -0,0 +1,174 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const CheckError = require('./check-error.cjs')
+const { findClosingParen } = require('./css-syntax.cjs')
+
+// All custom properties, not just --op-*, so theme vars like var(--brand-hue) resolve.
+const DECLARATION = /(--[\w-]+)\s*:\s*([^;}]*)/g
+const IMPORTANT = /\s*!\s*important$/i
+// Blocks that change whether or how much a declaration applies, which the cascade here doesn't follow.
+const SCOPED_RULE = /^@(media|supports|container|layer)\b/i
+// Optics itself is already loaded, and a remote URL (https:, data:, or //host) is usually a font, not a theme.
+const SKIPPED_IMPORT = /^(?:[a-z][a-z0-9+.-]*:|\/\/)|(^|\/)@rolemodel\/optics(\/|@|$)/i
+
+// The text of one or more CSS files, with their imports and without comments. Selectors are ignored.
+class Stylesheet {
+  #css
+
+  // Reads the files in order, as if they were one file.
+  static read(paths) {
+    const missing = paths.find((file) => !fs.existsSync(file))
+    if (missing) throw new CheckError(`File not found: ${missing}`)
+    return new Stylesheet(paths.map((file) => readWithImports(file, [path.resolve(file)])).join('\n'))
+  }
+
+  // Comments are stripped first, so commented-out tokens can't sway build detection or the cascade.
+  constructor(css) {
+    this.#css = stripComments(css)
+  }
+
+  get isEmpty() {
+    return this.#css === ''
+  }
+
+  mentions(pattern) {
+    return pattern.test(this.#css)
+  }
+
+  // Every custom property declaration, in source order, with duplicates. `rule` is the innermost
+  // @media, @supports, @container or @layer rule around it, if any.
+  *declarations() {
+    const scopedBlocks = this.#scopedBlocks()
+    for (const match of this.#css.matchAll(DECLARATION)) {
+      const [, name, rawValue] = match
+      const block = scopedBlocks.find(({ start, end }) => match.index > start && match.index < end)
+      const value = rawValue.trim()
+      yield { name, value: value.replace(IMPORTANT, ''), important: IMPORTANT.test(value), rule: block?.rule }
+    }
+  }
+
+  // The start and end of each scoped block, innermost first, with its rule, like "@media (prefers-color-scheme: dark)".
+  #scopedBlocks() {
+    const blocks = []
+    const open = []
+    let ruleStart = 0
+    for (let index = 0; index < this.#css.length; index++) {
+      const char = this.#css[index]
+      if (char === '{') {
+        const rule = this.#css.slice(ruleStart, index).trim()
+        open.push(SCOPED_RULE.test(rule) ? { rule, start: index } : undefined)
+      } else if (char === '}') {
+        const block = open.pop()
+        if (block) blocks.push({ ...block, end: index })
+      }
+      if (char === '{' || char === '}' || char === ';') ruleStart = index + 1
+    }
+    // A block left open runs to the end of the file, as in CSS.
+    for (const block of open) if (block) blocks.push({ ...block, end: this.#css.length })
+    return blocks
+  }
+}
+
+// Replaces each @import with the imported file, found relative to the importing file, as CSS does.
+// An import that can't be read or found stops the check, because the theme would be checked without its tokens.
+function readWithImports(file, chain) {
+  const css = stripComments(fs.readFileSync(file, 'utf8'))
+  const where = path.relative('.', file)
+  let output = ''
+  let index = 0
+  for (const { index: start } of css.matchAll(/@import\b/gi)) {
+    if (start < index) continue
+    const statement = parseImport(css, start)
+    if (!statement) throw new CheckError(`Can't read an @import in ${where}. Pass your compiled CSS instead.`)
+    output += css.slice(index, start) + importedCss(statement, file, where, chain)
+    index = statement.end
+  }
+  return output + css.slice(index)
+}
+
+function importedCss({ url, conditions }, file, where, chain) {
+  if (SKIPPED_IMPORT.test(url)) return ''
+
+  const imported = [url, `${url}.css`]
+    .map((candidate) => path.resolve(path.dirname(file), candidate))
+    .find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile())
+  if (!imported)
+    throw new CheckError(`Can't find @import '${url}' in ${where}. Fix the path, or pass your compiled CSS instead.`)
+  // CSS skips an import that would loop back to a file already being read.
+  if (chain.includes(imported)) return ''
+  return withConditions(readWithImports(imported, [...chain, imported]), conditions)
+}
+
+// Reads `@import "url" conditions;`, `@import 'url' ...;` or `@import url(...) ...;` starting at `start`.
+// Quoted URLs can hold spaces and semicolons. Returns undefined when the statement can't be read.
+function parseImport(css, start) {
+  let index = start + '@import'.length
+  const skipSpaces = () => {
+    while (/\s/.test(css[index] ?? '')) index++
+  }
+
+  skipSpaces()
+  const isUrlFunction = css.slice(index, index + 4).toLowerCase() === 'url('
+  if (isUrlFunction) {
+    index += 4
+    skipSpaces()
+  }
+
+  let url
+  const quote = css[index]
+  if (quote === '"' || quote === "'") {
+    const close = css.indexOf(quote, index + 1)
+    if (close === -1) return undefined
+    url = css.slice(index + 1, close)
+    index = close + 1
+  } else if (isUrlFunction) {
+    const close = css.indexOf(')', index)
+    if (close === -1) return undefined
+    url = css.slice(index, close).trim()
+    index = close
+  } else {
+    return undefined
+  }
+
+  if (isUrlFunction) {
+    skipSpaces()
+    if (css[index] !== ')') return undefined
+    index++
+  }
+
+  // The last statement in a file may end without a semicolon.
+  const semicolon = css.indexOf(';', index)
+  const end = semicolon === -1 ? css.length : semicolon
+  return { url, conditions: css.slice(index, end).trim(), end: end + 1 }
+}
+
+// Wraps imported CSS in the import's media, supports() and layer() parts, so its tokens count as scoped.
+function withConditions(css, conditions) {
+  let rest = conditions
+  let layer
+  const layerMatch = rest.match(/^layer(?:\(([^)]*)\))?\s*/i)
+  if (layerMatch) {
+    layer = layerMatch[1]?.trim() ?? ''
+    rest = rest.slice(layerMatch[0].length)
+  }
+
+  let supports
+  if (/^supports\(/i.test(rest)) {
+    const end = findClosingParen(rest, 'supports'.length)
+    if (end !== -1) {
+      supports = rest.slice('supports('.length, end)
+      rest = rest.slice(end + 1).trim()
+    }
+  }
+
+  let wrapped = css
+  if (layer !== undefined) wrapped = `@layer ${layer} {\n${wrapped}\n}`
+  if (supports !== undefined) wrapped = `@supports (${supports}) {\n${wrapped}\n}`
+  return rest ? `@media ${rest} {\n${wrapped}\n}` : wrapped
+}
+
+function stripComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, '')
+}
+
+module.exports = Stylesheet

package/dist/tools/contrast/theme.cjs

@@ -0,0 +1,84 @@
+const CalcExpression = require('./calc-expression.cjs')
+const CheckError = require('./check-error.cjs')
+const { findClosingParen, splitAtFirstComma } = require('./css-syntax.cjs')
+
+const VAR_NAME = /^--[\w-]+$/
+
+// The user's theme on top of the Optics tokens: one final value per custom property, like getComputedStyle(:root).
+class Theme {
+  #values = new Map()
+  // The @media, @supports, @container or @layer rule a property's final value was set inside, if any.
+  #rules = new Map()
+
+  // Applies the stylesheets in order. The last value wins, except a normal value can't replace an !important one, as in CSS.
+  static cascade(...stylesheets) {
+    const theme = new Theme()
+    const important = new Set()
+    for (const stylesheet of stylesheets) {
+      for (const { name, value, important: isImportant, rule } of stylesheet.declarations()) {
+        if (important.has(name) && !isImportant) continue
+        if (isImportant) important.add(name)
+        theme.#values.set(name, value)
+        if (rule) theme.#rules.set(name, rule)
+        else theme.#rules.delete(name)
+      }
+    }
+    return theme
+  }
+
+  names() {
+    return [...this.#values.keys()]
+  }
+
+  has(name) {
+    return this.#values.has(name)
+  }
+
+  // The token's value with every var() substituted and every plain-number calc() worked out.
+  resolve(name) {
+    this.#assertUnscoped(name, name)
+    return CalcExpression.resolveAll(this.#substituteVars(this.#values.get(name), [], name))
+  }
+
+  // Walks each var() with balanced parentheses, so fallbacks can hold their own var(),
+  // and a fallback is only resolved when its variable is not defined.
+  #substituteVars(value, seen, token) {
+    let output = ''
+    let index = 0
+    for (let start; (start = value.indexOf('var(', index)) !== -1;) {
+      const end = findClosingParen(value, start + 'var'.length)
+      if (end === -1) throw new CheckError(`Can't resolve: ${value}`)
+
+      const [name, fallback] = splitAtFirstComma(value.slice(start + 'var('.length, end)).map((part) => part.trim())
+      output += value.slice(index, start) + this.#substituteVar(name, fallback, seen, value, token)
+      index = end + 1
+    }
+    return output + value.slice(index)
+  }
+
+  #substituteVar(name, fallback, seen, value, token) {
+    if (!VAR_NAME.test(name)) throw new CheckError(`Can't resolve: ${value}`)
+    if (seen.includes(name)) throw new CheckError(`Circular reference: ${[...seen, name].join(' -> ')}`)
+    if (this.#values.has(name)) {
+      this.#assertUnscoped(token, name)
+      return this.#substituteVars(this.#values.get(name), [...seen, name], token)
+    }
+    if (fallback !== undefined) return this.#substituteVars(fallback, seen, token)
+    throw new CheckError(`${name} is not defined`)
+  }
+
+  // A value set inside @media, @supports or @container applies only under that condition, and one inside @layer
+  // loses to any unlayered value. The cascade here follows neither, so a color that depends on one could pass a
+  // theme that fails.
+  #assertUnscoped(token, name) {
+    const rule = this.#rules.get(name)
+    if (!rule) return
+    const reason = name === token ? 'it is set' : `it uses ${name}, which is set`
+    const advice = /^@layer/i.test(rule)
+      ? 'Layers change which value wins, so move color tokens out of @layer.'
+      : 'Set mode colors with light-dark(), or check that theme in its own file.'
+    throw new CheckError(`Can't check ${token}: ${reason} inside ${rule}. ${advice}`)
+  }
+}
+
+module.exports = Theme

package/dist/tools/contrast/tool-options.cjs

@@ -0,0 +1,50 @@
+const CheckError = require('./check-error.cjs')
+const ThemedColor = require('./colors/themed-color.cjs')
+
+const DEFAULT_MIN = 4.5
+const FLAG = /^--([a-z-]+)(?:=(.*))?$/
+
+// The command-line arguments: optics-check-contrast [files...] [--hsl | --oklch] [--mode=light | --mode=dark] [--min=4.5] [--alt-min=4.5] [--report]
+class ToolOptions {
+  static parse(args) {
+    const flags = {}
+    const files = []
+    for (const arg of args) {
+      const flag = arg.match(FLAG)
+      if (flag) flags[flag[1]] = flag[2] ?? true
+      else files.push(arg)
+    }
+    return new ToolOptions(files, flags)
+  }
+
+  constructor(files, flags) {
+    this.files = files
+    this.buildName = forcedBuildName(flags)
+    this.mode = mode(flags.mode)
+    this.min = threshold(flags.min)
+    this.altMin = threshold(flags['alt-min'])
+    this.report = Boolean(flags.report)
+  }
+}
+
+function forcedBuildName(flags) {
+  if (flags.hsl) return 'hsl'
+  if (flags.oklch) return 'oklch'
+  return undefined
+}
+
+function mode(value) {
+  if (value === undefined || ThemedColor.MODES.includes(value)) return value
+  throw new CheckError('--mode must be light or dark')
+}
+
+function threshold(value) {
+  if (value === undefined) return DEFAULT_MIN
+  // A bare --min (true) or empty --min= ('') would become 1 or 0 with Number(), so require a numeric string.
+  const number = typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN
+  // A NaN threshold would make every ratio < min check false, so every pair would pass.
+  if (!Number.isFinite(number)) throw new CheckError('--min and --alt-min must be numbers, like 4.5')
+  return number
+}
+
+module.exports = ToolOptions

package/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",