@cosla/sensemaking-report-builder 0.1.2 → 0.2.0

package/README.md

@@ -76,7 +76,9 @@ npx @cosla/sensemaking-report-builder config-schema --schema-version 1
 Prints a [JSON Schema draft 2020-12](https://json-schema.org/draft/2020-12/schema) document for supported `config.json` keys (`schemas/config.v1.json`), including application field `config_schema_version`. Unknown `--schema-version` values fail with a clear error.
 
 ```bash
-npm run smoke   # validates config-schema output
+npm test        # smoke (config-schema) + unit tests
+npm run smoke   # config-schema only
+npm run unit    # node:test suite only
 ```
 
 Logo and translations are configured in `config.json` (not CLI flags). Place `logo.svg` / `logo.png` next to that config (under `--inputDir` when using dir mode).
@@ -87,7 +89,7 @@ Logo and translations are configured in `config.json` (not CLI flags). Place `lo
 
 Required columns: `topic`, `opinion`, `quote`, `participant_id`.
 
-Optional: `AVERAGE_OF_2_BRIDGING` or `AVERAGE_OF_3_BRIDGING` (used to sort quotes). Demographic columns: prefix with `demo:` (e.g. `demo:Age`).
+Optional: `AVERAGE_OF_2_BRIDGING` or `AVERAGE_OF_3_BRIDGING` (used to sort quotes; OF_2 preferred when both are present). When neither column is present, a warning is printed and quotes keep input order. Demographic columns: prefix with `demo:` (e.g. `demo:Age`). When no demographic columns have values, the participant overview and drawer demographics tab are omitted.
 
 ### Summary JSON
 
@@ -103,9 +105,9 @@ Same shape as Python `sensemaking-report-text` / `report_data.json`: `text`, `su
 | `number_of_top_opinions` | Opinions overview chart size |
 | `number_of_sample_quotes` | Quote previews per opinion |
 | `low_sample_warning_threshold` | Low-sample warning threshold |
-| `topic_colors` / `chart_colors` | Overview chart colours |
-| `demographic_colors` | Participant chart colours |
-| `excluded_topics` / `excluded_opinions` | Hide named topics/opinions (exact match to CSV columns) |
+| `chart_colors` | Overview chart colours (array of hex strings). Default: `#DA3D2E`, `#F2A50C`, `#80CD57`, `#00885F`, `#11C2CE`, `#1233A6`, `#8A2FE4`, `#F388D2`. Blank entries are ignored; an empty list falls back to the default. |
+| `demographic_colors` | Participant chart colours: a single hex string (a 6-step light-to-dark palette is generated) or an explicit array of colours. Default base: `#4886f7`. Generated ramps use CSS relative colour syntax (`oklch(from …)`; Chrome 119+, Firefox 128+, Safari 18+); use an explicit hex array for older browsers. |
+| `excluded_topics` / `excluded_opinions` | Hide named topics/opinions (exact match to CSV columns). CamelCase aliases `excludedTopics` / `excludedOpinions` are also accepted at runtime. |
 
 ### Predicted agreement (optional)
 

package/data.js

@@ -10,8 +10,35 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { resolveDemographicColors } from "./palette.js";
+
 const demographics_prefix = "demo:";
 
+/**
+ * Bridging average columns, in preference order. Matches columns written by
+ * get_bridging_scores.py (OF_3) and older pipeline outputs (OF_2).
+ * @type {string[]}
+ */
+export const BRIDGING_COLUMNS = [
+  "AVERAGE_OF_2_BRIDGING",
+  "AVERAGE_OF_3_BRIDGING",
+];
+
+/**
+ * Default topic / overview chart colours when config.chart_colors is absent.
+ * @type {string[]}
+ */
+export const DEFAULT_CHART_COLORS = [
+  "#DA3D2E",
+  "#F2A50C",
+  "#80CD57",
+  "#00885F",
+  "#11C2CE",
+  "#1233A6",
+  "#8A2FE4",
+  "#F388D2",
+];
+
 /**
  * @typedef {Object} RawOpinion
  * @property {string} topic - The high-level topic category.
@@ -22,6 +49,39 @@ const demographics_prefix = "demo:";
  * @property {string|number} [AVERAGE_OF_3_BRIDGING] - Alternate bridging column.
  */
 
+/**
+ * Returns whether any row has a known bridging-score column.
+ * @param {Object[]} rows
+ * @returns {boolean}
+ */
+export function hasBridgingColumn(rows) {
+  return rows.some((row) => BRIDGING_COLUMNS.some((col) => col in row));
+}
+
+/**
+ * Reads bridging score from AVERAGE_OF_2_BRIDGING or AVERAGE_OF_3_BRIDGING.
+ * Prefers OF_2 when both are present (legacy Cosla behaviour).
+ * @param {RawOpinion|Object} row
+ * @returns {number}
+ */
+export function getBridgingScore(row) {
+  const num = Number(row.AVERAGE_OF_2_BRIDGING ?? row.AVERAGE_OF_3_BRIDGING);
+  return Number.isFinite(num) ? num : 0;
+}
+
+/**
+ * Drops blank/non-string entries from a colour list. Non-arrays pass through.
+ * Empty or all-blank arrays become undefined so callers can fall back to
+ * defaults (guards against Consul string-list rows that submit `[""]`).
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function cleanColorList(value) {
+  if (!Array.isArray(value)) return value;
+  const cleaned = value.filter((c) => typeof c === "string" && c.trim() !== "");
+  return cleaned.length > 0 ? cleaned : undefined;
+}
+
 /**
  * @typedef {Object} BuildOptions
  * @property {"inline"|"static"|"config-schema"} command
@@ -315,16 +375,6 @@ function generateId(str, useFirstWords = false) {
   );
 }
 
-/**
- * Reads bridging score from AVERAGE_OF_2_BRIDGING or AVERAGE_OF_3_BRIDGING.
- * @param {RawOpinion} row
- * @returns {number}
- */
-function bridgingScore(row) {
-  const raw = row.AVERAGE_OF_2_BRIDGING ?? row.AVERAGE_OF_3_BRIDGING;
-  return raw ? +raw : 0;
-}
-
 /**
  * Resolves optional user i18n file under the staged input directory.
  * @param {Object} config
@@ -369,6 +419,13 @@ export function processReportData({
     index,
   }));
 
+  if (opinions.length > 0 && !hasBridgingColumn(opinions)) {
+    console.warn(
+      `Warning: no ${BRIDGING_COLUMNS.join(" or ")} column found in the ` +
+        "opinions data; quotes will not be ordered by bridging score.",
+    );
+  }
+
   const config = configPath
     ? JSON.parse(fs.readFileSync(configPath, "utf-8"))
     : {};
@@ -422,8 +479,12 @@ export function processReportData({
   }
 
   const overviewChart = config.overview_chart || "toggle";
-  const excludedTopics = new Set(config.excluded_topics || []);
-  const excludedOpinions = new Set(config.excluded_opinions || []);
+  const excludedTopics = new Set(
+    config.excluded_topics ?? config.excludedTopics ?? [],
+  );
+  const excludedOpinions = new Set(
+    config.excluded_opinions ?? config.excludedOpinions ?? [],
+  );
   const reportOptions = {
     logo: config.logo || "",
     overviewChart,
@@ -437,23 +498,11 @@ export function processReportData({
       Math.max(config.number_of_top_opinions || 10, 2),
       20,
     ),
-    topicColors: config.chart_colors || [
-      "#AFB42B",
-      "#F4511E",
-      "#3949AB",
-      "#E52592",
-      "#00897B",
-      "#EFB22F",
-      "#aaa",
-    ],
-    demographicColors: config.demographic_colors || [
-      "#4886f7",
-      "#4071d5",
-      "#385db3",
-      "#2f4a93",
-      "#273874",
-      "#1e2656",
-    ],
+    topicColors:
+      cleanColorList(config.chart_colors) ?? DEFAULT_CHART_COLORS,
+    demographicColors: resolveDemographicColors(
+      cleanColorList(config.demographic_colors),
+    ),
   };
 
   /**
@@ -472,7 +521,7 @@ export function processReportData({
           index: v.index,
           text: v.quote,
           participant_id: v.participant_id,
-          avg_bridging: bridgingScore(v),
+          avg_bridging: getBridgingScore(v),
           ...demos,
         };
       })
@@ -710,6 +759,7 @@ export function processReportData({
   });
 
   demographics.sort((a, b) => a.label.localeCompare(b.label, i18n.locale));
+  const hasDemographics = demographics.some((d) => d.values.length > 0);
 
   const executiveSummary = parseSummary(cleanMarkdown(summary.text || ""));
   const title = stripMarkdownHeader(summary.title);
@@ -740,6 +790,7 @@ export function processReportData({
     propositionsGenerated,
     topics,
     demographics,
+    hasDemographics,
     predicted,
     hasPredicted: predicted.topics.length > 0,
     i18n,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosla/sensemaking-report-builder",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Interactive HTML report builder for Cosla Python sensemaking pipeline outputs.",
   "type": "module",
   "main": "build.js",
@@ -11,6 +11,7 @@
     "bin/",
     "build.js",
     "data.js",
+    "palette.js",
     "src/**/*",
     "schemas/**/*",
     "README.md",
@@ -25,7 +26,8 @@
     "preview": "node build.js preview",
     "github": "node build.js github",
     "smoke": "node smoke.js",
-    "test": "npm run smoke"
+    "unit": "node --test",
+    "test": "npm run smoke && npm run unit"
   },
   "repository": {
     "type": "git",

package/palette.js

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Sequential color palette generation for the report UI.
+ *
+ * Builds a light-to-dark palette from a single base hex color using CSS
+ * Relative Color Syntax (`oklch(from <color> l c h)`), delegating color-space
+ * conversion and gamut mapping to the browser's CSS engine.
+ */
+
+/**
+ * Number of colors generated for the demographic chart. The chart shows at
+ * most five values plus "Other" (see data.js), so six colors are enough.
+ * @type {number}
+ */
+export const DEMOGRAPHIC_PALETTE_STEPS = 6;
+
+/**
+ * Base color for the default demographic palette.
+ * @type {string}
+ */
+export const DEFAULT_DEMOGRAPHIC_BASE_COLOR = "#4886f7";
+
+/**
+ * Lightest OKLCH lightness used in generated palettes.
+ *
+ * Palettes deliberately use a wide lightness range: lightness differences are
+ * what keep segments distinguishable for color-blind readers. The lightest
+ * segment is therefore a tint with less than 3:1 contrast against the chart
+ * background; segments are separated by gaps and labelled in the legend, so
+ * color is not the only way to tell values apart.
+ * @type {number}
+ */
+export const PALETTE_MAX_LIGHTNESS = 0.85;
+
+/**
+ * Darkest OKLCH lightness used in generated palettes. Dark enough for a strong
+ * end to the ramp while staying visibly tinted rather than black.
+ * @type {number}
+ */
+export const PALETTE_MIN_LIGHTNESS = 0.22;
+
+/**
+ * Fraction of the base color's chroma kept at PALETTE_MAX_LIGHTNESS. Steps
+ * lighter than the base taper towards this, so pale steps are soft tints
+ * rather than fluorescent.
+ * @type {number}
+ */
+export const LIGHTEST_CHROMA_FRACTION = 0.5;
+
+const HEX_COLOR_RE = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/**
+ * Returns whether `value` is a `#rgb` or `#rrggbb` hex color string.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isHexColor(value) {
+  return typeof value === "string" && HEX_COLOR_RE.test(value.trim());
+}
+
+/**
+ * Generates a light-to-dark palette of CSS `oklch(from ...)` strings from a
+ * single base hex color.
+ *
+ * Every step keeps the base hue (`h`), spaces lightness (`targetL`) evenly
+ * from PALETTE_MAX_LIGHTNESS down to PALETTE_MIN_LIGHTNESS, and scales the
+ * base chroma (`c`) in CSS:
+ * - Steps darker than the base scale chroma proportionally (`targetL / l`).
+ * - Steps lighter than the base taper chroma linearly toward
+ *   `LIGHTEST_CHROMA_FRACTION * c` at `PALETTE_MAX_LIGHTNESS`.
+ *
+ * @param {string} [baseHex=DEFAULT_DEMOGRAPHIC_BASE_COLOR] - `#rgb` or `#rrggbb`.
+ * @param {number} [steps=DEMOGRAPHIC_PALETTE_STEPS] - Number of steps (>= 2).
+ * @returns {string[]} CSS `oklch(from ...)` color strings, lightest to darkest.
+ * @throws {Error} If `baseHex` is not a valid hex color or `steps` < 2.
+ */
+export function generateSequentialPalette(
+  baseHex = DEFAULT_DEMOGRAPHIC_BASE_COLOR,
+  steps = DEMOGRAPHIC_PALETTE_STEPS,
+) {
+  if (!isHexColor(baseHex)) {
+    throw new Error(`Invalid hex color: ${baseHex}`);
+  }
+  if (!Number.isInteger(steps) || steps < 2) {
+    throw new Error(`steps must be an integer >= 2, got ${steps}`);
+  }
+
+  const base = baseHex.trim().toLowerCase();
+  const lightTaper = +(1 - LIGHTEST_CHROMA_FRACTION).toFixed(4);
+
+  return Array.from({ length: steps }, (_, i) => {
+    const t = i / (steps - 1);
+    const targetL = +(
+      PALETTE_MAX_LIGHTNESS -
+      t * (PALETTE_MAX_LIGHTNESS - PALETTE_MIN_LIGHTNESS)
+    ).toFixed(4);
+
+    const darkScale = `${targetL} / max(l, 0.001)`;
+    const lightProgress = `clamp(0, (${targetL} - l) / max(0.001, ${PALETTE_MAX_LIGHTNESS} - l), 1)`;
+    const lightScale = `1 - ${lightTaper} * ${lightProgress}`;
+
+    return `oklch(from ${base} ${targetL} calc(c * min(${darkScale}, ${lightScale})) h)`;
+  });
+}
+
+/**
+ * Resolves the `demographic_colors` config value into a palette.
+ *
+ * Accepts an explicit array of colors (used as-is), a single hex color (a
+ * palette is generated from it), or nothing (a palette is generated from
+ * DEFAULT_DEMOGRAPHIC_BASE_COLOR).
+ *
+ * @param {string|string[]|undefined} configValue
+ * @returns {string[]}
+ */
+export function resolveDemographicColors(configValue) {
+  if (Array.isArray(configValue)) return configValue;
+  if (isHexColor(configValue)) return generateSequentialPalette(configValue);
+  if (configValue != null && configValue !== "") {
+    console.warn(
+      `Warning: demographic_colors must be an array or a hex color such as ` +
+        `"${DEFAULT_DEMOGRAPHIC_BASE_COLOR}"; got ` +
+        `${JSON.stringify(configValue)}. Using default colors.`,
+    );
+  }
+  return generateSequentialPalette(DEFAULT_DEMOGRAPHIC_BASE_COLOR);
+}

package/schemas/config.v1.json

@@ -7,15 +7,15 @@
   "properties": {
     "title": {
       "type": "string",
-      "title": "Report Title Override"
+      "title": "Report title"
     },
     "logo": {
       "type": "string",
-      "title": "Logo Image Filename"
+      "title": "Logo image filename"
     },
     "excluded_topics": {
       "type": "array",
-      "title": "Excluded Topics",
+      "title": "Excluded topics",
       "description": "Topic names to omit (exact match)",
       "items": {
         "type": "string"
@@ -23,7 +23,7 @@
     },
     "excluded_opinions": {
       "type": "array",
-      "title": "Excluded Opinions",
+      "title": "Excluded opinions",
       "description": "Opinion names to omit (exact match)",
       "items": {
         "type": "string"

package/src/index.mustache

@@ -95,6 +95,7 @@
 							{{/executiveSummary}}
 						</section>
 					</article>
+					{{#hasDemographics}}
 					<article>
 						<section id="participant-overview">
 							<header>
@@ -105,6 +106,7 @@
 							<div id="participant-overview-chart" class="demographic-chart"></div>
 						</section>
 					</article>
+					{{/hasDemographics}}
 					<article>
 						<section id="conversation-overview">
 							<header>
@@ -245,9 +247,11 @@
 								<button class="is-active" data-target="drawer-quotes">
 									{{i18n.drawer.participantQuotesTitle}} (<span class="drawer-quote-count"></span>)
 								</button>
+								{{#hasDemographics}}
 								<button data-target="drawer-demographics">
 									{{i18n.drawer.participantDemographics}}
 								</button>
+								{{/hasDemographics}}
 							</div>
 						</div>
 						<div id="drawer-quotes" class="tab is-visible">
@@ -265,9 +269,11 @@
 							<ul class="drawer-quotes"></ul>
 						</div>
 
+						{{#hasDemographics}}
 						<div id="drawer-demographics" class="tab">
 							<div id="drawer-demographics-chart" class="demographic-chart"></div>
 						</div>
+						{{/hasDemographics}}
 						<button class="button-close"><img inline src="svg/x.svg" alt="{{i18n.meta.closeAlt}}"></button>
 					</div>
 				</div>

package/src/script.js

@@ -246,7 +246,7 @@ function createDemographicChart({ id, data }) {
           return `calc(${ratio * 100}% - ${shrinkPixels}px)`;
         })
         .attr("rx", borderRadius)
-        .attr(
+        .style(
           "fill",
           (d, i) => DEMOGRAPHIC_PALETTE[i % DEMOGRAPHIC_PALETTE.length],
         );
@@ -532,6 +532,8 @@ function createParticipantChart() {
   /** @type {Demographic[]} */
   const data = window.PAYLOAD.demographics;
   const id = "participant-overview-chart";
+  // The section is omitted from the template when there is no demographic data.
+  if (!document.getElementById(id)) return;
   createDemographicChart({ id, data });
 }
 
@@ -870,6 +872,8 @@ function updateQuotesDrawer() {
 
 function createQuotesDrawerParticipantChart() {
   const id = "drawer-demographics-chart";
+  // The tab is omitted from the template when there is no demographic data.
+  if (!document.getElementById(id)) return null;
   const unknownOpinionText = i18n.drawer?.unknownOpinion || "Unknown Opinion";
   const match = flatOpinions.find((o) => o.fullID === currentDrawerId);
   const text = match?.text || unknownOpinionText;