@mstone6969/graph 0.1.0 → 0.2.0

package/dist/charts/frameworks/NpsGauge.js

@@ -0,0 +1,279 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { NpsBand, NpsSurvey } from "./NpsSurvey.js";
+import { arc, scaleBand, scaleLinear } from "d3";
+// src/charts/frameworks/NpsGauge.ts
+var NpsSweep = /* @__PURE__ */ function(NpsSweep) {
+	NpsSweep["Semi"] = "semi";
+	NpsSweep["ThreeQuarter"] = "three-quarter";
+	return NpsSweep;
+}({});
+var NpsIndicator = /* @__PURE__ */ function(NpsIndicator) {
+	NpsIndicator["Needle"] = "needle";
+	NpsIndicator["Fill"] = "fill";
+	return NpsIndicator;
+}({});
+var STRIP = 22;
+var GAP = 8;
+var CHAR = 6.2;
+var BANDS = [
+	NpsBand.Detractors,
+	NpsBand.Passives,
+	NpsBand.Promoters
+];
+var CELLS = Array.from({ length: 20 }, (_, i) => -100 + i * 10);
+var percent = (value) => `${value.toFixed(1)}%`;
+/** A bar with its own radius per corner, clockwise from top left. */
+var bar = (x, y, w, h, [tl, tr, br, bl]) => `M${x + tl},${y}H${x + w - tr}Q${x + w},${y} ${x + w},${y + tr}V${y + h - br}Q${x + w},${y + h} ${x + w - br},${y + h}H${x + bl}Q${x},${y + h} ${x},${y + h - bl}V${y + tl}Q${x},${y} ${x + tl},${y}Z`;
+/** Synthetic answers, invented for the sample: a left-skewed 0 to 10 spread like typical recommendation surveys. */
+var syntheticResponses = (seed) => SampleData.distribution(seed, 400, 1).map((row) => {
+	const z = (row.value - 40) / 8;
+	return { score: Math.max(0, Math.min(10, Math.round(8.1 + 1.9 * z - .3 * z * z))) };
+});
+/**
+* Net Promoter Score gauge: the score on a -100 to 100 dial with zero at the top, above a stacked breakdown
+* of detractors, passives and promoters whose outer two parts are what the score subtracts. See `NpsSurvey`.
+*/
+var NpsGauge = class extends Chart2D {
+	static meta = {
+		id: "nps-gauge",
+		name: "Net Promoter Score gauge",
+		family: ChartFamily.Indicator,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Shows Net Promoter Score from 0 to 10 answers on a -100 to 100 dial with its promoter, passive and detractor breakdown.",
+		tags: [
+			"nps",
+			"net promoter",
+			"customer loyalty",
+			"survey"
+		],
+		sample: syntheticResponses,
+		variants: {
+			sweep: ["semi", "three-quarter"],
+			indicator: ["needle", "fill"],
+			scores: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			score: "score",
+			sweep: "semi",
+			indicator: "needle",
+			scores: false
+		};
+	}
+	get survey() {
+		return new NpsSurvey(this.options.data, this.options.score, this.options.count);
+	}
+	/** Promoters take the good pole. Passives are a neutral, since the diverging midpoint nearly vanishes into the surface. */
+	#color(band) {
+		if (band === NpsBand.Passives) return this.theme.axis;
+		return this.palette.diverging(band === NpsBand.Promoters ? -1 : 1);
+	}
+	/** Blue above zero and red below, never so faint that a cell near zero disappears. */
+	#polarity(score) {
+		return this.palette.diverging(-Math.sign(score) * (.2 + .8 * Math.abs(score) / 100));
+	}
+	legendItems() {
+		return BANDS.map((key) => ({
+			key,
+			color: this.#color(key)
+		}));
+	}
+	draw(ctx) {
+		const { width, height } = ctx.plot;
+		const { survey } = this;
+		const panel = this.options.scores ? Math.round(width * .45) : width;
+		const room = height - STRIP - GAP;
+		this.#gauge(ctx, survey, this.#dial(panel, room));
+		this.#distribution(ctx, survey, panel, room);
+		this.#strip(ctx, survey, height - STRIP, width);
+	}
+	#dial(width, height) {
+		const needle = this.options.indicator === "needle", semi = this.options.sweep === "semi";
+		const top = 16;
+		const under = semi && needle ? 60 : 18;
+		const radius = Math.max(18, Math.min(width / 2 - 8, (height - top - under) / (semi ? 1 : 1 + Math.SQRT1_2)));
+		const cy = top + radius;
+		const size = Math.max(20, Math.min(40, radius * .5));
+		const number = needle ? semi ? cy + 12 + size * .75 : cy + radius * .56 : cy - (semi ? 14 : 0);
+		return {
+			cx: width / 2,
+			cy,
+			radius,
+			size,
+			number,
+			caption: number + 16,
+			room: radius * 1.5
+		};
+	}
+	#gauge(ctx, survey, dial) {
+		const { theme } = ctx;
+		const { cx, cy, radius } = dial;
+		const half = this.options.sweep === "semi" ? Math.PI / 2 : Math.PI * .75;
+		const needle = this.options.indicator === "needle";
+		const angle = scaleLinear().domain([-100, 100]).range([-half, half]);
+		const inner = radius * .82;
+		const ring = arc().innerRadius(inner).outerRadius(radius).startAngle((d) => angle(d.from)).endAngle((d) => angle(d.to));
+		const cell = arc().innerRadius(inner).outerRadius(radius).startAngle((d) => angle(d.from)).endAngle((d) => angle(d.to)).padAngle(2 / radius).padRadius(radius);
+		const stage = ctx.nest(`translate(${cx},${cy})`, "dial");
+		const { score } = survey;
+		const parts = needle ? CELLS.map((from) => ({
+			from,
+			to: from + 10
+		})) : [{
+			from: -100,
+			to: 100
+		}];
+		stage.marks("track", "path", parts, (d) => d.from).attr("d", (d) => (needle ? cell : ring)(d)).attr("fill", (d) => needle ? this.#polarity(d.from + 5) : theme.grid);
+		const value = !needle && score !== null ? [score] : [];
+		const fill = stage.marks("fill", "path", value).attr("fill", (d) => this.#polarity(d));
+		stage.set(fill, { d: (d) => ring(d < 0 ? {
+			from: d,
+			to: 0
+		} : {
+			from: 0,
+			to: d
+		}) }, { d: () => ring({
+			from: 0,
+			to: 0
+		}) });
+		stage.hover(fill, (d) => this.#tip(survey, d));
+		const zero = stage.marks("zero", "line", needle ? [] : [0]).attr("stroke", theme.ink).attr("stroke-width", 2);
+		stage.set(zero, {
+			x1: 0,
+			x2: 0,
+			y1: -radius,
+			y2: -inner
+		});
+		const length = needle ? inner - 4 : 0;
+		const pointer = stage.marks("needle", "path", needle && score !== null ? [score] : []).attr("fill", theme.ink);
+		stage.set(pointer, {
+			d: `M-3,0L0,${-length}L3,0Z`,
+			transform: (d) => `rotate(${angle(d) * 180 / Math.PI})`
+		}, { transform: "rotate(0)" });
+		stage.hover(pointer, (d) => this.#tip(survey, d));
+		const hub = stage.marks("hub", "circle", needle && score !== null ? [score] : []).attr("fill", theme.ink).attr("stroke", theme.surface).attr("stroke-width", 2);
+		stage.set(hub, { r: 6 });
+		stage.hover(hub, (d) => this.#tip(survey, d));
+		const reach = (radius + inner) / 2;
+		const ends = [
+			{
+				text: "−100",
+				x: Math.sin(-half) * reach,
+				y: -Math.cos(-half) * reach + 14
+			},
+			{
+				text: "0",
+				x: 0,
+				y: -radius - 5
+			},
+			{
+				text: "+100",
+				x: Math.sin(half) * reach,
+				y: -Math.cos(half) * reach + 14
+			}
+		];
+		stage.text(stage.marks("ends", "text", ends, (d) => d.text).attr("text-anchor", "middle").attr("x", (d) => d.x).attr("y", (d) => d.y).text((d) => d.text), 11, "muted");
+		ctx.text(ctx.marks("score", "text", [score === null ? "–" : NpsSurvey.format(score)]).attr("text-anchor", "middle").attr("x", cx).attr("y", dial.number).attr("font-weight", 700).text((d) => d), dial.size, "ink");
+		ctx.text(ctx.marks("caption", "text", [this.#caption(survey, dial.room)]).attr("text-anchor", "middle").attr("x", cx).attr("y", dial.caption).text((d) => d), 11, "secondary");
+	}
+	#caption(survey, room) {
+		if (!survey.total) return "No valid responses";
+		const base = `n = ${survey.total.toLocaleString("en")}`;
+		const full = `${base} · ${survey.excluded.toLocaleString("en")} excluded`;
+		return survey.excluded && full.length * CHAR <= room ? full : base;
+	}
+	#tip(survey, score) {
+		const rows = BANDS.map((band) => [band, percent(survey.share(band))]);
+		return {
+			title: `NPS ${NpsSurvey.format(score)}`,
+			rows: [
+				["Unrounded", score.toFixed(1)],
+				...rows,
+				["Responses", survey.total]
+			]
+		};
+	}
+	/** The 0 to 10 answers themselves, so a score's shape shows: bars start at zero and share one scale. */
+	#distribution(ctx, survey, left, height) {
+		const bottom = height - 16;
+		const shown = this.options.scores && survey.total ? survey.counts.map((count, score) => ({
+			score,
+			count
+		})) : [];
+		const x = scaleBand().domain(shown.map((d) => d.score)).range([left + 12, ctx.plot.width]).paddingInner(0);
+		const peak = Math.max(1, ...survey.counts);
+		const y = scaleLinear().domain([0, peak]).range([bottom, 4]);
+		const shape = (d, to) => {
+			const w = Math.max(1, x.bandwidth() - 2), r = Math.min(4, w / 2, bottom - to);
+			return bar(x(d.score) + 1, to, w, bottom - to, [
+				r,
+				r,
+				0,
+				0
+			]);
+		};
+		const bars = ctx.marks("scores", "path", shown.filter((d) => d.count), (d) => d.score).attr("fill", (d) => this.#color(NpsSurvey.band(d.score)));
+		ctx.set(bars, { d: (d) => shape(d, y(d.count)) }, { d: (d) => shape(d, bottom) }, 20);
+		ctx.hover(bars, (d) => ({
+			title: `Score ${d.score}`,
+			color: this.#color(NpsSurvey.band(d.score)),
+			rows: [
+				["Band", NpsSurvey.band(d.score)],
+				["Responses", d.count],
+				["Share", percent(d.count / survey.total * 100)]
+			]
+		}));
+		const step = x.bandwidth() >= 13 ? 1 : 2;
+		const ticks = ctx.marks("score-ticks", "text", shown.filter((d) => d.score % step === 0), (d) => d.score).attr("text-anchor", "middle").attr("x", (d) => x(d.score) + x.bandwidth() / 2).attr("y", height - 3).text((d) => d.score);
+		ctx.text(ticks, 11, "secondary");
+	}
+	/** Whole shares can round away from the score, as 41.25 - 22.5 reads 41 - 23 beside +19, so such a strip prints tenths. */
+	#tenths(survey) {
+		const whole = (band) => Math.round(survey.share(band));
+		return survey.score !== null && whole(NpsBand.Promoters) - whole(NpsBand.Detractors) !== NpsSurvey.rounded(survey.score);
+	}
+	/** Part-to-whole across 100% of valid responses, with a 2px gap taken out of the length, not added to it. */
+	#strip(ctx, survey, top, width) {
+		const present = BANDS.filter((band) => survey.count(band));
+		const room = width - 2 * Math.max(0, present.length - 1);
+		let at = 0;
+		const parts = present.map((band, i) => {
+			const w = survey.share(band) / 100 * room, x = at;
+			at += w + 2;
+			return {
+				band,
+				x,
+				w,
+				first: !i,
+				last: i === present.length - 1
+			};
+		});
+		const shape = (d, w) => {
+			const r = Math.min(4, w / 2);
+			return bar(d.x, top, w, STRIP, [
+				d.first ? r : 0,
+				d.last ? r : 0,
+				d.last ? r : 0,
+				d.first ? r : 0
+			]);
+		};
+		const segments = ctx.marks("strip", "path", parts, (d) => d.band).attr("fill", (d) => this.#color(d.band));
+		ctx.set(segments, { d: (d) => shape(d, d.w) }, { d: (d) => shape(d, 0) }, 40);
+		ctx.hover(segments, (d) => ({
+			title: d.band,
+			color: this.#color(d.band),
+			rows: [["Responses", survey.count(d.band)], ["Share", percent(survey.share(d.band))]]
+		}));
+		const tenths = this.#tenths(survey);
+		const label = (d) => {
+			const share = `${tenths ? survey.share(d.band).toFixed(1) : Math.round(survey.share(d.band))}%`, long = `${d.band} ${share}`;
+			return long.length * CHAR + 12 <= d.w ? long : share.length * CHAR + 8 <= d.w ? share : "";
+		};
+		ctx.marks("strip-labels", "text", parts, (d) => d.band).attr("text-anchor", "middle").attr("x", (d) => d.x + d.w / 2).attr("y", top + STRIP / 2 + 4).attr("font-size", 11).attr("font-family", ctx.theme.fontFamily).attr("fill", (d) => ctx.palette.inkOn(this.#color(d.band))).text(label).style("pointer-events", "none");
+	}
+};
+export { NpsGauge, NpsIndicator, NpsSweep };

package/dist/charts/frameworks/NpsSurvey.js

@@ -0,0 +1,58 @@
+// src/charts/frameworks/NpsSurvey.ts
+var NpsBand = /* @__PURE__ */ function(NpsBand) {
+	NpsBand["Detractors"] = "Detractors";
+	NpsBand["Passives"] = "Passives";
+	NpsBand["Promoters"] = "Promoters";
+	return NpsBand;
+}({});
+var SCORES = 11;
+var number = (cell) => typeof cell === "number" ? cell : typeof cell === "string" && cell.trim() ? Number(cell) : NaN;
+/**
+* Net Promoter Score from 0 to 10 likelihood-to-recommend answers (Reichheld, "The One Number You Need to
+* Grow", Harvard Business Review, 2003): 9 and 10 promote, 7 and 8 are passive, 0 to 6 detract, and the score
+* is the percentage of promoters minus the percentage of detractors. Anything but a whole 0 to 10 is left out.
+*/
+var NpsSurvey = class NpsSurvey {
+	/** Responses per score, 0 to 10. */
+	counts = Array.from({ length: SCORES }, () => 0);
+	excluded = 0;
+	/** `count` names a column of response counts, for data already tallied by score. */
+	constructor(rows, score, count) {
+		let excluded = 0;
+		for (const row of Array.isArray(rows) ? rows : []) {
+			const value = row !== null && typeof row === "object" ? number(row[score]) : NaN;
+			const weight = count === void 0 ? 1 : row !== null && typeof row === "object" ? number(row[count]) : NaN;
+			if (!Number.isFinite(weight) || weight < 0) excluded++;
+			else if (Number.isInteger(value) && value >= 0 && value < SCORES) this.counts[value] += weight;
+			else excluded += weight;
+		}
+		this.excluded = excluded;
+	}
+	static band(score) {
+		return score >= 9 ? "Promoters" : score >= 7 ? "Passives" : "Detractors";
+	}
+	/** Whole-number report form, rounding halves away from zero so the sign cannot bias it. */
+	static rounded(score) {
+		return Math.sign(score) * Math.round(Math.abs(score)) || 0;
+	}
+	/** Signed report form: `+42`, `−12`, `0`. */
+	static format(score) {
+		const whole = NpsSurvey.rounded(score);
+		return whole > 0 ? `+${whole}` : whole < 0 ? `−${-whole}` : "0";
+	}
+	get total() {
+		return this.counts.reduce((sum, count) => sum + count, 0);
+	}
+	count(band) {
+		return this.counts.reduce((sum, count, score) => NpsSurvey.band(score) === band ? sum + count : sum, 0);
+	}
+	/** Percentage of valid responses in `band`, 0 with none. */
+	share(band) {
+		return this.total ? this.count(band) / this.total * 100 : 0;
+	}
+	/** Unrounded, from -100 to 100, or `null` with no valid responses. */
+	get score() {
+		return this.total ? this.share("Promoters") - this.share("Detractors") : null;
+	}
+};
+export { NpsBand, NpsSurvey };