@basiclines/rampa 1.2.0 → 1.3.0

package/README.md

@@ -140,6 +140,35 @@ Available types:
 | `--output` | `-O` | Output format: text, json, css | text |
 | `--preview` | | Show colored squares | true |
 
+### Accessibility
+
+| Flag | Alias | Description | Default |
+|------|-------|-------------|---------|
+| `--accessibility` | `-A` | APCA contrast report | off |
+
+The `-A` flag generates an accessibility report using the [APCA](https://github.com/Myndex/APCA) (Accessible Perceptual Contrast Algorithm) methodology. It analyzes all color pairs across all generated ramps and groups passing pairs by contrast level.
+
+**Filter options:**
+
+| Syntax | Example | Description |
+|--------|---------|-------------|
+| `-A` | `-A` | Show all passing pairs |
+| `-A=<Lc>` | `-A=60` | Minimum Lc threshold |
+| `-A=<label>` | `-A=body` | Filter by named level |
+| `-A=<min>:<max>` | `-A=15:30` | Lc range filter |
+| `-A=<label>:<label>` | `-A=nontext:bold` | Range using level names |
+
+**Level labels:**
+
+| Label | Lc Threshold | Use Case |
+|-------|-------------|----------|
+| `preferred` | 90 | Preferred body text |
+| `body` | 75 | Body text |
+| `large` | 60 | Large text |
+| `bold` | 45 | Large/bold text |
+| `minimum` | 30 | Minimum text |
+| `nontext` | 15 | Non-text elements |
+
 ### Other
 
 | Flag | Alias | Description |
@@ -251,6 +280,28 @@ Output:
 rampa -C "#3b82f6" --no-preview | head -5
 ```
 
+### Accessibility Report
+
+```bash
+# Full APCA contrast report
+rampa -C "#3b82f6" --add=complementary -A
+
+# Filter by minimum Lc threshold
+rampa -C "#3b82f6" --add=complementary -A=body
+
+# Filter by Lc range
+rampa -C "#3b82f6" --add=complementary -A=15:30
+
+# Filter using level labels
+rampa -C "#3b82f6" --add=complementary -A=nontext:bold
+
+# Accessibility report in JSON
+rampa -C "#3b82f6" --add=complementary -A -O json
+
+# Accessibility report in CSS (appended as comment)
+rampa -C "#3b82f6" --add=complementary -A -O css
+```
+
 ## Contextual Help
 
 Run any flag without a value to see detailed help:

package/dist/index.js

@@ -9943,6 +9943,291 @@ ${dim}For accurate color previews, use a terminal with COLORTERM=truecolor.${res
   return null;
 }
 
+// node_modules/apca-w3/src/apca-w3.js
+var SA98G = {
+  mainTRC: 2.4,
+  get mainTRCencode() {
+    return 1 / this.mainTRC;
+  },
+  sRco: 0.2126729,
+  sGco: 0.7151522,
+  sBco: 0.072175,
+  normBG: 0.56,
+  normTXT: 0.57,
+  revTXT: 0.62,
+  revBG: 0.65,
+  blkThrs: 0.022,
+  blkClmp: 1.414,
+  scaleBoW: 1.14,
+  scaleWoB: 1.14,
+  loBoWoffset: 0.027,
+  loWoBoffset: 0.027,
+  deltaYmin: 0.0005,
+  loClip: 0.1,
+  mFactor: 1.9468554433171,
+  get mFactInv() {
+    return 1 / this.mFactor;
+  },
+  mOffsetIn: 0.0387393816571401,
+  mExpAdj: 0.283343396420869,
+  get mExp() {
+    return this.mExpAdj / this.blkClmp;
+  },
+  mOffsetOut: 0.312865795870758
+};
+function APCAcontrast(txtY, bgY, places = -1) {
+  const icp = [0, 1.1];
+  if (isNaN(txtY) || isNaN(bgY) || Math.min(txtY, bgY) < icp[0] || Math.max(txtY, bgY) > icp[1]) {
+    return 0;
+  }
+  let SAPC = 0;
+  let outputContrast = 0;
+  let polCat = "BoW";
+  txtY = txtY > SA98G.blkThrs ? txtY : txtY + Math.pow(SA98G.blkThrs - txtY, SA98G.blkClmp);
+  bgY = bgY > SA98G.blkThrs ? bgY : bgY + Math.pow(SA98G.blkThrs - bgY, SA98G.blkClmp);
+  if (Math.abs(bgY - txtY) < SA98G.deltaYmin) {
+    return 0;
+  }
+  if (bgY > txtY) {
+    SAPC = (Math.pow(bgY, SA98G.normBG) - Math.pow(txtY, SA98G.normTXT)) * SA98G.scaleBoW;
+    outputContrast = SAPC < SA98G.loClip ? 0 : SAPC - SA98G.loBoWoffset;
+  } else {
+    polCat = "WoB";
+    SAPC = (Math.pow(bgY, SA98G.revBG) - Math.pow(txtY, SA98G.revTXT)) * SA98G.scaleWoB;
+    outputContrast = SAPC > -SA98G.loClip ? 0 : SAPC + SA98G.loWoBoffset;
+  }
+  if (places < 0) {
+    return outputContrast * 100;
+  } else if (places == 0) {
+    return Math.round(Math.abs(outputContrast) * 100) + "<sub>" + polCat + "</sub>";
+  } else if (Number.isInteger(places)) {
+    return (outputContrast * 100).toFixed(places);
+  } else {
+    return 0;
+  }
+}
+function sRGBtoY(rgb10 = [0, 0, 0]) {
+  function simpleExp(chan) {
+    return Math.pow(chan / 255, SA98G.mainTRC);
+  }
+  return SA98G.sRco * simpleExp(rgb10[0]) + SA98G.sGco * simpleExp(rgb10[1]) + SA98G.sBco * simpleExp(rgb10[2]);
+}
+
+// src/accessibility/apca.ts
+var APCA_LEVELS = [
+  { id: "preferred-body", name: "Preferred body text", minLc: 90 },
+  { id: "body", name: "Body text", minLc: 75 },
+  { id: "large", name: "Large text", minLc: 60 },
+  { id: "large-bold", name: "Large/bold text", minLc: 45 },
+  { id: "min-text", name: "Minimum text", minLc: 30 },
+  { id: "non-text", name: "Non-text", minLc: 15 }
+];
+var LEVEL_ALIASES = {
+  preferred: 90,
+  body: 75,
+  large: 60,
+  bold: 45,
+  minimum: 30,
+  nontext: 15
+};
+function resolveValue2(val) {
+  const num9 = parseFloat(val);
+  if (!isNaN(num9) && num9 >= 0)
+    return num9;
+  const label = val.toLowerCase().trim();
+  if (label in LEVEL_ALIASES)
+    return LEVEL_ALIASES[label];
+  return null;
+}
+function parseAccessibilityFilter(value) {
+  const raw = value ?? "";
+  if (!value || value === "" || value === "true")
+    return { min: 0, max: Infinity, raw };
+  if (value.includes(":")) {
+    const [startStr, endStr] = value.split(":");
+    const start = resolveValue2(startStr);
+    const end = resolveValue2(endStr);
+    if (start === null || end === null) {
+      const validLabels2 = Object.keys(LEVEL_ALIASES).join(", ");
+      console.error(`Error: Invalid accessibility range "${value}". Use Lc numbers or labels: ${validLabels2}`);
+      process.exit(1);
+    }
+    const lo = Math.min(start, end);
+    const hi = Math.max(start, end);
+    return { min: lo, max: hi, raw: value };
+  }
+  const resolved = resolveValue2(value);
+  if (resolved !== null)
+    return { min: resolved, max: Infinity, raw: value };
+  const validLabels = Object.keys(LEVEL_ALIASES).join(", ");
+  console.error(`Error: Invalid accessibility filter "${value}". Use a Lc number, label, or range (e.g. 15:30). Labels: ${validLabels}`);
+  process.exit(1);
+}
+function computeApca(fgHex, bgHex) {
+  const [fgR, fgG, fgB] = chroma_js_default(fgHex).rgb();
+  const [bgR, bgG, bgB] = chroma_js_default(bgHex).rgb();
+  return APCAcontrast(sRGBtoY([fgR, fgG, fgB]), sRGBtoY([bgR, bgG, bgB]));
+}
+function getPassingLevels(lc) {
+  const absLc = Math.abs(lc);
+  return APCA_LEVELS.filter((level) => absLc >= level.minLc);
+}
+
+// src/accessibility/report.ts
+function collectColors(ramps) {
+  const refs = [];
+  for (const ramp of ramps) {
+    for (let i2 = 0;i2 < ramp.colors.length; i2++) {
+      refs.push({ ramp: ramp.name, index: i2, color: ramp.colors[i2] });
+    }
+  }
+  return refs;
+}
+function deduplicateColors(colors2) {
+  if (colors2.length <= 2)
+    return colors2;
+  const keep = new Set;
+  keep.add(0);
+  keep.add(colors2.length - 1);
+  for (let i2 = 1;i2 < colors2.length; i2++) {
+    const prev = colors2[i2 - 1];
+    const curr = colors2[i2];
+    if (curr.ramp !== prev.ramp) {
+      keep.add(i2);
+      keep.add(i2 - 1);
+      continue;
+    }
+    const de = chroma_js_default.deltaE(curr.color, prev.color);
+    if (de >= 3) {
+      keep.add(i2);
+    }
+  }
+  return colors2.filter((_3, i2) => keep.has(i2));
+}
+var DEFAULT_FILTER = { min: 0, max: Infinity, raw: "" };
+function generateAccessibilityReport(ramps, filter = DEFAULT_FILTER) {
+  const allColors = collectColors(ramps);
+  const colors2 = deduplicateColors(allColors);
+  const totalPairs = colors2.length * (colors2.length - 1) / 2;
+  const levelMap = new Map;
+  for (const level of APCA_LEVELS) {
+    levelMap.set(level.id, []);
+  }
+  let passingPairs = 0;
+  for (let i2 = 0;i2 < colors2.length; i2++) {
+    for (let j = i2 + 1;j < colors2.length; j++) {
+      const a2 = colors2[i2];
+      const b2 = colors2[j];
+      const lcAB = computeApca(a2.color, b2.color);
+      const lcBA = computeApca(b2.color, a2.color);
+      const bestAbsLc = Math.max(Math.abs(lcAB), Math.abs(lcBA));
+      const passing = getPassingLevels(bestAbsLc);
+      if (passing.length > 0) {
+        passingPairs++;
+        const pair = {
+          colorA: a2,
+          colorB: b2,
+          lcAB: Math.round(lcAB * 100) / 100,
+          lcBA: Math.round(lcBA * 100) / 100
+        };
+        const highest = passing[0];
+        levelMap.get(highest.id).push(pair);
+      }
+    }
+  }
+  const levels = APCA_LEVELS.filter((level) => level.minLc >= filter.min && level.minLc <= filter.max).map((level) => {
+    const pairs = filter.max < Infinity ? levelMap.get(level.id).filter((p) => {
+      const bestAbsLc = Math.max(Math.abs(p.lcAB), Math.abs(p.lcBA));
+      return bestAbsLc >= filter.min && bestAbsLc <= filter.max;
+    }) : levelMap.get(level.id);
+    return { id: level.id, name: level.name, minLc: level.minLc, pairs };
+  });
+  return {
+    totalPairs,
+    passingPairs,
+    levels,
+    filter
+  };
+}
+
+// src/formatters/accessibility-json.ts
+function formatAccessibilityJson(report) {
+  return {
+    totalPairs: report.totalPairs,
+    passingPairs: report.passingPairs,
+    filter: report.filter.raw ? { value: report.filter.raw, min: report.filter.min, max: report.filter.max === Infinity ? null : report.filter.max } : null,
+    levels: report.levels.map((level) => ({
+      id: level.id,
+      name: level.name,
+      minLc: level.minLc,
+      count: level.pairs.length,
+      pairs: level.pairs.map((pair) => ({
+        colorA: { ramp: pair.colorA.ramp, index: pair.colorA.index, color: pair.colorA.color },
+        colorB: { ramp: pair.colorB.ramp, index: pair.colorB.index, color: pair.colorB.color },
+        lcAB: pair.lcAB,
+        lcBA: pair.lcBA
+      }))
+    }))
+  };
+}
+
+// src/formatters/accessibility-text.ts
+function formatLc(lc) {
+  const str = lc.toString();
+  return lc >= 0 ? ` ${str}` : str;
+}
+function pairSquares(pair) {
+  const [rA, gA, bA] = chroma_js_default(pair.colorA.color).rgb();
+  const [rB, gB, bB] = chroma_js_default(pair.colorB.color).rgb();
+  return `${coloredSquare(rA, gA, bA)}${coloredSquare(rB, gB, bB)}`;
+}
+function formatAccessibilityText(report, options = {}) {
+  const lines = [];
+  const showPreview = options.preview ?? false;
+  lines.push("");
+  lines.push("# Accessibility Report (APCA)");
+  lines.push(`${report.passingPairs} of ${report.totalPairs} pairs pass at least one level`);
+  lines.push("");
+  const filteredPairCount = report.levels.reduce((sum, l2) => sum + l2.pairs.length, 0);
+  if (filteredPairCount === 0) {
+    const filterDesc = report.filter.raw ? `filter: ${report.filter.raw}` : "current filter";
+    lines.push(`No pairs match the ${filterDesc}`);
+    lines.push("");
+    return lines.join(`
+`);
+  }
+  for (const level of report.levels) {
+    if (level.pairs.length === 0)
+      continue;
+    lines.push(`## ${level.name} (Lc ≥ ${level.minLc}) — ${level.pairs.length} pairs`);
+    const maxColorA = Math.max(...level.pairs.map((p) => p.colorA.color.length));
+    const maxColorB = Math.max(...level.pairs.map((p) => p.colorB.color.length));
+    const maxLcAB = Math.max(...level.pairs.map((p) => formatLc(p.lcAB).length));
+    const maxLcBA = Math.max(...level.pairs.map((p) => formatLc(p.lcBA).length));
+    const maxRefA = Math.max(...level.pairs.map((p) => `${p.colorA.ramp}[${p.colorA.index}]`.length));
+    const maxRefB = Math.max(...level.pairs.map((p) => `${p.colorB.ramp}[${p.colorB.index}]`.length));
+    for (const pair of level.pairs) {
+      const colA = pair.colorA.color.padEnd(maxColorA);
+      const colB = pair.colorB.color.padEnd(maxColorB);
+      const lcA = formatLc(pair.lcAB).padStart(maxLcAB);
+      const lcB = formatLc(pair.lcBA).padStart(maxLcBA);
+      const refA = `${pair.colorA.ramp}[${pair.colorA.index}]`.padEnd(maxRefA);
+      const refB = `${pair.colorB.ramp}[${pair.colorB.index}]`.padEnd(maxRefB);
+      const preview = showPreview ? `${pairSquares(pair)} ` : "";
+      lines.push(`  ${preview}${colA} ↔ ${colB}  Lc ${lcA} / ${lcB}  ${refA} ↔ ${refB}`);
+    }
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+function formatAccessibilityCss(report) {
+  return `
+/*
+` + formatAccessibilityText(report) + `*/
+`;
+}
+
 // src/index.ts
 if (process.argv.includes("--help") || process.argv.includes("-h")) {
   showHelp();
@@ -9995,6 +10280,10 @@ HARMONIES
 OUTPUT
   ${cyan}-O, --output <format>${reset}          ${dim}Output format (default: text)${reset}
   ${cyan}--preview / --no-preview${reset}       ${dim}Show colored squares (default: true)${reset}
+  ${cyan}-A, --accessibility [filter]${reset}    ${dim}Show APCA contrast report${reset}
+
+                                  ${dim}Filters: preferred, body, large, bold, minimum, nontext${reset}
+                                  ${dim}or a custom Lc value (e.g. 60)${reset}
 
                                   ${dim}Formats: text, json, css${reset}
 
@@ -10009,6 +10298,8 @@ EXAMPLES
   ${cyan}rampa -C "#3b82f6" --add=shift:45 --add=shift:90${reset}
   ${cyan}rampa -C "#3b82f6" -O css${reset}
   ${cyan}rampa -C "#3b82f6" --tint-color="#FF0000" --tint-opacity=15${reset}
+  ${cyan}rampa -C "#3b82f6" -A${reset}
+  ${cyan}rampa -C "#3b82f6" --add=complementary -O json -A${reset}
 `;
   console.log(help.trim());
   process.exit(0);
@@ -10148,6 +10439,25 @@ Examples:
   rampa -C "#3b82f6" --output=json
   rampa -C "#3b82f6" --output=css
   rampa -C "#3b82f6" -O json --add=complementary
+`,
+  accessibility: `
+-A, --accessibility [filter]  Show APCA contrast report
+
+Filters (optional):
+  preferred   Lc ≥ 90  Preferred body text
+  body        Lc ≥ 75  Body text
+  large       Lc ≥ 60  Large text
+  bold        Lc ≥ 45  Large/bold text
+  minimum     Lc ≥ 30  Minimum text
+  nontext     Lc ≥ 15  Non-text
+  <number>    Custom Lc threshold (e.g. 60)
+
+Examples:
+  rampa -C "#3b82f6" -A
+  rampa -C "#3b82f6" -A body
+  rampa -C "#3b82f6" -A=large
+  rampa -C "#3b82f6" --accessibility=75
+  rampa -C "#3b82f6" -O json -A preferred
 `
 };
 function showFlagHelp(flag) {
@@ -10190,7 +10500,7 @@ var validFormats = ["hex", "hsl", "rgb", "oklch"];
 var main = defineCommand({
   meta: {
     name: "rampa",
-    version: "1.2.0",
+    version: "1.3.0",
     description: "Generate mathematically accurate color palettes from a base color"
   },
   args: {
@@ -10271,6 +10581,11 @@ var main = defineCommand({
       alias: ["O", "o"],
       description: "Output format: text, json, css (default: text)",
       default: "text"
+    },
+    accessibility: {
+      type: "string",
+      alias: ["A", "a"],
+      description: "Show APCA contrast report. Optional: filter by level name or Lc value"
     }
   },
   run({ args }) {
@@ -10510,10 +10825,23 @@ var main = defineCommand({
         colors: formattedShiftedColors
       });
     }
+    const accessibilityEnabled = args.accessibility !== undefined;
+    const accessibilityFilter = accessibilityEnabled ? parseAccessibilityFilter(args.accessibility) : undefined;
     if (outputType === "json") {
-      console.log(formatJson(ramps));
+      if (accessibilityEnabled) {
+        const report = generateAccessibilityReport(ramps, accessibilityFilter);
+        const output = { ramps: JSON.parse(formatJson(ramps)).ramps, accessibility: formatAccessibilityJson(report) };
+        console.log(JSON.stringify(output, null, 2));
+      } else {
+        console.log(formatJson(ramps));
+      }
     } else if (outputType === "css") {
-      console.log(formatCss2(ramps));
+      let output = formatCss2(ramps);
+      if (accessibilityEnabled) {
+        const report = generateAccessibilityReport(ramps, accessibilityFilter);
+        output += formatAccessibilityCss(report);
+      }
+      console.log(output);
     } else {
       const canShowPreview = args.preview && supportsTruecolor();
       if (args.preview && !canShowPreview) {
@@ -10540,6 +10868,10 @@ var main = defineCommand({
           }
         });
       });
+      if (accessibilityEnabled) {
+        const report = generateAccessibilityReport(ramps, accessibilityFilter);
+        console.log(formatAccessibilityText(report, { preview: canShowPreview }));
+      }
     }
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basiclines/rampa",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Generate mathematically accurate color palettes from a base color",
   "type": "module",
   "bin": {
@@ -40,8 +40,9 @@
   "author": "ismael.fyi",
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "citty": "^0.1.6",
+    "apca-w3": "^0.1.9",
     "chroma-js": "^3.1.2",
+    "citty": "^0.1.6",
     "culori": "^4.0.1"
   },
   "devDependencies": {