@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/financial/ReturnCalendar.js

@@ -0,0 +1,196 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { ChartFamily, DataShape, Dimension, Orientation } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { CalendarCell, CalendarGrain, CalendarMeasure, CalendarTotals } from "./financeEnums.js";
+import { Quotes } from "./Quotes.js";
+import { color, mean, quantile, scaleBand, utcFormat } from "d3";
+// src/charts/financial/ReturnCalendar.ts
+var MONTHS = Array.from({ length: 12 }, (_, month) => utcFormat("%b")(new Date(Date.UTC(2024, month, 1))));
+var QUARTERS = [
+	"Q1",
+	"Q2",
+	"Q3",
+	"Q4"
+];
+var TOTAL = "Year";
+var AVERAGE = "Mean";
+/** Period returns laid out by year: use it to report performance and to spot seasonal patterns. */
+var ReturnCalendar = class extends Chart2D {
+	static meta = {
+		id: "return-calendar",
+		name: "Return calendar",
+		family: ChartFamily.Financial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Arranges monthly or quarterly returns in a year-by-period table, with polarity colour for gains and losses.",
+		tags: [
+			"monthly returns",
+			"seasonality",
+			"heatmap",
+			"tearsheet"
+		],
+		sample: (seed) => SampleData.ohlc(seed, 1095),
+		variants: {
+			measure: [CalendarMeasure.Return, CalendarMeasure.Excess],
+			grain: [CalendarGrain.Month, CalendarGrain.Quarter],
+			totals: [
+				CalendarTotals.Year,
+				CalendarTotals.None,
+				CalendarTotals.Both
+			],
+			cell: [CalendarCell.Tile, CalendarCell.Bubble],
+			orientation: [Orientation.Horizontal, Orientation.Vertical]
+		},
+		valid: (values) => values.measure === CalendarMeasure.Return || values.cell === CalendarCell.Bubble
+	};
+	defaults() {
+		return {
+			date: "date",
+			close: "close",
+			measure: CalendarMeasure.Return,
+			grain: CalendarGrain.Month,
+			totals: CalendarTotals.Year,
+			cell: CalendarCell.Tile,
+			orientation: Orientation.Horizontal
+		};
+	}
+	cells() {
+		const { data, date, close, measure, grain, totals } = this.options;
+		const quarterly = grain === CalendarGrain.Quarter;
+		const periods = quarterly ? QUARTERS : MONTHS;
+		const closes = /* @__PURE__ */ new Map();
+		for (const row of data ?? []) {
+			const when = Quotes.date(row[date]), price = Quotes.number(row[close]);
+			if (!when || !Number.isFinite(price)) continue;
+			const year = when.getUTCFullYear(), slot = quarterly ? Math.floor(when.getUTCMonth() / 3) : when.getUTCMonth();
+			const key = `${year}/${slot}`, hit = closes.get(key);
+			if (!hit) closes.set(key, {
+				year,
+				slot,
+				time: +when,
+				first: price,
+				last: price
+			});
+			else if (+when >= hit.time) {
+				hit.time = +when;
+				hit.last = price;
+			}
+		}
+		const ordered = [...closes.values()].sort((a, b) => a.year - b.year || a.slot - b.slot);
+		const raw = ordered.flatMap((period, i) => {
+			const base = ordered[i - 1]?.last ?? period.first;
+			return base ? [{
+				year: period.year,
+				slot: period.slot,
+				value: (period.last - base) / Math.abs(base) * 100
+			}] : [];
+		});
+		const years = [...new Set(raw.map((item) => item.year))];
+		const cells = [];
+		for (const year of years) {
+			const items = raw.filter((item) => item.year === year);
+			const average = measure === CalendarMeasure.Excess ? mean(items, (item) => item.value) ?? 0 : 0;
+			items.forEach((item) => cells.push({
+				row: String(year),
+				column: periods[item.slot],
+				value: item.value - average,
+				total: false
+			}));
+			if (totals !== CalendarTotals.None) {
+				const compound = (items.reduce((growth, item) => growth * (1 + item.value / 100), 1) - 1) * 100;
+				cells.push({
+					row: String(year),
+					column: TOTAL,
+					value: measure === CalendarMeasure.Excess ? compound - average * items.length : compound,
+					total: true
+				});
+			}
+		}
+		const rows = years.map(String);
+		if (totals === CalendarTotals.Both) {
+			for (const column of periods) {
+				const hits = cells.filter((cell) => cell.column === column);
+				if (hits.length) cells.push({
+					row: AVERAGE,
+					column,
+					value: mean(hits, (cell) => cell.value),
+					total: true
+				});
+			}
+			rows.push(AVERAGE);
+		}
+		return {
+			cells,
+			rows,
+			columns: totals === CalendarTotals.None ? periods : [...periods, TOTAL]
+		};
+	}
+	plotMargin() {
+		return {
+			top: 20,
+			right: 12,
+			bottom: 8,
+			left: 44
+		};
+	}
+	legendItems() {
+		return [];
+	}
+	draw(ctx) {
+		const { cells, rows, columns } = this.cells();
+		const { width, height } = ctx.plot;
+		const flipped = this.options.orientation === Orientation.Vertical;
+		const across = flipped ? rows : columns, down = flipped ? columns : rows;
+		const x = scaleBand(across, [0, width]).paddingInner(.06), y = scaleBand(down, [0, height]).paddingInner(.08);
+		const wide = x.bandwidth(), deep = y.bandwidth();
+		const left = (cell) => x(flipped ? cell.row : cell.column);
+		const top = (cell) => y(flipped ? cell.column : cell.row);
+		const reach = Math.max(quantile(cells.filter((cell) => !cell.total).map((cell) => Math.abs(cell.value)), .9) ?? 0, .01);
+		const paint = (cell) => ctx.palette.diverging(Math.max(-1, Math.min(1, -cell.value / reach)));
+		const key = (cell) => `${cell.row}/${cell.column}`;
+		const tile = this.options.cell === CalendarCell.Tile;
+		const tips = (cell) => ({
+			title: `${cell.column} ${cell.row}`,
+			color: paint(cell),
+			rows: [[this.options.measure === CalendarMeasure.Excess ? "Excess" : "Return", `${Quotes.signed(cell.value)}%`]]
+		});
+		const rects = ctx.marks("tiles", "rect", tile ? cells : [], key).attr("fill", paint).attr("rx", 3);
+		ctx.set(rects, {
+			x: left,
+			y: top,
+			width: wide,
+			height: deep
+		}, {
+			x: left,
+			y: top,
+			width: wide,
+			height: 0
+		}, 3);
+		ctx.hover(rects, tips);
+		const room = Math.min(wide, deep) / 2 - 1;
+		const radius = (cell) => Math.max(1.5, room * Math.sqrt(Math.min(1, Math.abs(cell.value) / reach)));
+		const dots = ctx.marks("bubbles", "circle", tile ? [] : cells, key).attr("fill", paint);
+		const cx = (cell) => left(cell) + wide / 2, cy = (cell) => top(cell) + deep / 2;
+		ctx.set(dots, {
+			cx,
+			cy,
+			r: radius
+		}, {
+			cx,
+			cy,
+			r: 0
+		}, 3);
+		ctx.hover(dots, tips);
+		const fits = tile && wide >= 22 && deep >= 13;
+		const labels = ctx.text(ctx.marks("values", "text", fits ? cells : [], key), wide >= 34 ? 10 : 9).attr("text-anchor", "middle").attr("dy", "0.34em").attr("pointer-events", "none").attr("fill", (cell) => ctx.palette.inkOn(color(paint(cell))?.formatHex() ?? ctx.theme.surface)).attr("font-weight", (cell) => cell.total ? 600 : 400).text((cell) => cell.value.toFixed(wide >= 34 ? 1 : 0).replace(/^-(0(\.0)?)$/, "$1"));
+		ctx.set(labels, {
+			x: cx,
+			y: cy
+		});
+		const header = across.filter((_, i) => wide >= 20 || i % 2 === 0);
+		ctx.text(ctx.marks("column-names", "text", header)).attr("text-anchor", "middle").attr("x", (name) => x(name) + wide / 2).attr("y", -7).text((name) => name);
+		const side = down.filter((_, i) => deep >= 12 || i % 2 === 0);
+		ctx.text(ctx.marks("row-names", "text", side)).attr("text-anchor", "end").attr("x", -7).attr("y", (name) => y(name) + deep / 2).attr("dy", "0.34em").text((name) => name);
+	}
+};
+export { ReturnCalendar };

package/dist/charts/financial/SessionChart.js

@@ -0,0 +1,194 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { FinanceInk } from "./FinanceInk.js";
+import { Quotes } from "./Quotes.js";
+import { pointer, scaleLinear, scaleUtc, utcFormat } from "d3";
+// src/charts/financial/SessionChart.ts
+var shortDay = utcFormat("%b %-d");
+var monthYear = utcFormat("%b %Y");
+var GAP = 18;
+/**
+* Session-indexed time axis: every bar gets equal width, so weekends and holidays leave no holes.
+* Owns pane layout, polarity colours, the crosshair and the per-session hit columns.
+*/
+var SessionChart = class extends CartesianChart {
+	timeScale = null;
+	percentAxis = null;
+	polarity = false;
+	mainHeight = 300;
+	defaults() {
+		return {
+			date: "date",
+			open: "open",
+			high: "high",
+			low: "low",
+			close: "close",
+			volume: "volume"
+		};
+	}
+	valueScale() {
+		return scaleLinear();
+	}
+	/** Bars plotted on the axis, after any rebasing. */
+	bars() {
+		return Quotes.read(this.options.data, this.options);
+	}
+	/** Empty sessions kept after the last bar, for indicators projected forward. */
+	futureSessions() {
+		return 0;
+	}
+	/** Fraction of the plot given to the secondary pane; 0 for none. */
+	subShare() {
+		return 0;
+	}
+	/** Secondary pane sits below the main one unless this returns true. */
+	subOnTop() {
+		return false;
+	}
+	/** False when the marks are a single-colour line, so the legend says Close rather than Up and Down. */
+	twoTone() {
+		return true;
+	}
+	/** Axis values end in %. */
+	percentValues() {
+		return false;
+	}
+	yTicks() {
+		return Math.max(2, Math.min(6, Math.floor(this.mainHeight / 34)));
+	}
+	scales(ctx) {
+		const bars = this.bars();
+		const { width, height } = ctx.plot;
+		const share = this.subShare();
+		const subHeight = (share ? Math.max(0, height - GAP) : height) * share;
+		const sub = !share ? null : this.subOnTop() ? {
+			top: 0,
+			bottom: subHeight
+		} : {
+			top: height - subHeight,
+			bottom: height
+		};
+		const main = !share ? {
+			top: 0,
+			bottom: height
+		} : this.subOnTop() ? {
+			top: subHeight + GAP,
+			bottom: height
+		} : {
+			top: 0,
+			bottom: height - subHeight - GAP
+		};
+		this.mainHeight = main.bottom - main.top;
+		const count = bars.length + this.futureSessions();
+		const x = scaleLinear(count ? [-.6, count - .4] : [0, 1], [0, width]);
+		const y = this.valueScale().domain(bars.length ? this.valueDomain(bars) : [0, 1]).range([main.bottom, main.top]);
+		if (!("base" in y)) y.nice(this.yTicks());
+		this.timeScale = x;
+		this.percentAxis = this.percentValues() ? y : null;
+		this.fitTicks(x, bars, this.futureSessions(), width);
+		const step = x(1) - x(0);
+		return {
+			x,
+			y,
+			bars,
+			step,
+			body: Math.max(1, step > 4 ? step - 2 : step * .7),
+			main,
+			sub
+		};
+	}
+	/** Ticks land on calendar boundaries, snapped to the first session on or after each one. */
+	fitTicks(x, bars, future, width) {
+		const dated = bars.filter((bar) => bar.date);
+		this.tickDates = bars.map((bar) => bar.date);
+		if (dated.length < 2) return;
+		const first = dated[0].date, last = dated.at(-1).date;
+		const pace = (last.getTime() - first.getTime()) / (dated.length - 1);
+		if (pace <= 0) return;
+		for (let i = 1; i <= future; i++) this.tickDates.push(new Date(last.getTime() + pace * i));
+		const end = this.tickDates.at(-1);
+		const seen = /* @__PURE__ */ new Set();
+		for (const tick of scaleUtc().domain([first, end]).ticks(Math.max(2, Math.floor(width / 84)))) {
+			const index = this.tickDates.findIndex((date) => date && date >= tick);
+			if (index >= 0) seen.add(index);
+		}
+		const spaced = [];
+		for (const index of [...seen].sort((a, b) => a - b)) {
+			const previous = spaced.at(-1);
+			if (previous === void 0 || x(index) - x(previous) >= 64) spaced.push(index);
+		}
+		x.ticks = () => spaced;
+		this.dateFormat = end.getTime() - first.getTime() > 2592e7 ? monthYear : shortDay;
+	}
+	dateFormat = shortDay;
+	tickDates = [];
+	tickFormat(scale) {
+		if (scale === this.timeScale) return (value) => {
+			const date = this.tickDates[+value];
+			return date ? this.dateFormat(date) : "";
+		};
+		const base = super.tickFormat(scale);
+		return base && scale === this.percentAxis ? (value) => `${base(value)}%` : base;
+	}
+	/** Claims the first categorical slot, which is the up pole, so overlays never share its colour. */
+	tones(ctx) {
+		this.polarity = true;
+		ctx.palette.color("Up");
+		return {
+			up: ctx.palette.diverging(-1),
+			down: ctx.palette.diverging(1)
+		};
+	}
+	legendItems() {
+		const items = this.palette.items();
+		if (!this.polarity) return items;
+		return items.flatMap((item) => {
+			if (item.key !== "Up") return [item];
+			return this.twoTone() ? [item, {
+				key: "Down",
+				color: this.palette.diverging(1)
+			}] : [{
+				...item,
+				key: "Close"
+			}];
+		});
+	}
+	barTip(bar) {
+		const { open, high, low, close } = bar.source;
+		return {
+			title: bar.label,
+			color: this.palette.diverging(close >= open ? -1 : 1),
+			rows: [
+				["Open", Quotes.money(open)],
+				["High", Quotes.money(high)],
+				["Low", Quotes.money(low)],
+				["Close", Quotes.money(close)],
+				["Volume", Quotes.compact(bar.volume)]
+			]
+		};
+	}
+	/** Full-height hover columns with a crosshair; the columns are the hit targets for every mark in a session. */
+	sessions(ctx, view, tip = (bar) => this.barTip(bar)) {
+		const { x, bars, step, main } = view;
+		const { width, height } = ctx.plot;
+		const line = ctx.marks("crosshair", "line", [0, 1]).attr("stroke", ctx.theme.inkMuted).attr("stroke-width", 1).attr("stroke-dasharray", "2 3").attr("opacity", 0).attr("pointer-events", "none");
+		const hits = ctx.marks("hits", "rect", bars, (bar) => bar.index).attr("fill", "transparent").attr("pointer-events", "all").attr("x", (bar) => Math.max(0, x(bar.index) - step / 2)).attr("width", Math.max(1, step)).attr("y", 0).attr("height", height);
+		ctx.hover(hits, tip);
+		const root = ctx.root.node();
+		hits.on("pointermove.crosshair", (event, bar) => {
+			const [, py] = pointer(event, root);
+			const level = Math.max(main.top, Math.min(main.bottom, py));
+			line.attr("opacity", 1);
+			line.filter((_, i) => i === 0).attr("x1", x(bar.index)).attr("x2", x(bar.index)).attr("y1", 0).attr("y2", height);
+			line.filter((_, i) => i === 1).attr("x1", 0).attr("x2", width).attr("y1", level).attr("y2", level);
+		}).on("pointerleave.crosshair", () => line.attr("opacity", 0));
+	}
+	/** Thin pane label, top-left, halo so bars can run underneath. */
+	paneTitle(ctx, name, title, pane) {
+		FinanceInk.note(ctx, name, title && pane ? [title] : [], (text) => ({
+			x: 4,
+			y: pane.top + 10,
+			text
+		}), 10, "muted");
+	}
+};
+export { SessionChart };

package/dist/charts/financial/StochasticChart.js

@@ -0,0 +1,77 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { StochasticForm } from "./financeEnums.js";
+import { FinanceMath } from "./FinanceMath.js";
+import { OscillatorChart } from "./OscillatorChart.js";
+import { PriceMarks } from "./PriceMarks.js";
+// src/charts/financial/StochasticChart.ts
+/** Where the close sits in its recent range: use it for turning points inside a sideways market. */
+var StochasticChart = class extends OscillatorChart {
+	static meta = {
+		id: "stochastic-oscillator",
+		name: "Stochastic oscillator",
+		family: ChartFamily.Financial,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Places each close within its recent high-low range, with %K and %D crossings signalling reversals.",
+		tags: [
+			"momentum",
+			"oscillator",
+			"kd",
+			"overbought"
+		],
+		sample: (seed) => SampleData.ohlc(seed, 110),
+		variants: {
+			period: [
+				14,
+				5,
+				21
+			],
+			form: [
+				StochasticForm.Slow,
+				StochasticForm.Fast,
+				StochasticForm.Full
+			],
+			upper: [80, 70],
+			shade: [true, false],
+			pricePane: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			period: 14,
+			form: StochasticForm.Slow,
+			upper: 80,
+			shade: true
+		};
+	}
+	lines(bars) {
+		const { period, form } = this.options;
+		const raw = FinanceMath.stochastic(bars.map((bar) => bar.close), bars.map((bar) => bar.high), bars.map((bar) => bar.low), period);
+		const k = form === StochasticForm.Fast ? raw : FinanceMath.sma(raw, form === StochasticForm.Full ? 5 : 3);
+		return {
+			k,
+			d: FinanceMath.sma(k, form === StochasticForm.Full ? 5 : 3)
+		};
+	}
+	valueDomain() {
+		return [0, 100];
+	}
+	oscillator(ctx, view, tones) {
+		const { k, d } = this.lines(view.bars);
+		const { upper, shade } = this.options;
+		this.zones(ctx, view, tones, k, upper, 100 - upper, shade);
+		PriceMarks.line(ctx, view, "stoch-k", k, ctx.palette.color("%K"));
+		PriceMarks.line(ctx, view, "stoch-d", d, ctx.palette.color("%D"), 1.5, "4 3");
+	}
+	tooltip(bar) {
+		const { k, d } = this.lines(this.bars());
+		const show = (value) => value == null ? "–" : value.toFixed(1);
+		return {
+			title: bar.label,
+			rows: [["%K", show(k[bar.index])], ["%D", show(d[bar.index])]]
+		};
+	}
+};
+export { StochasticChart };

package/dist/charts/financial/TpoProfile.js

@@ -0,0 +1,172 @@
+import { max, min, utcFormat, utcMonday } from "d3";
+// src/charts/financial/TpoProfile.ts
+var TpoForm = /* @__PURE__ */ function(TpoForm) {
+	TpoForm["Letters"] = "letters";
+	TpoForm["Blocks"] = "blocks";
+	return TpoForm;
+}({});
+/** `Collapsed` pushes each row's prints to the left, the classic profile; `Split` keeps every bracket in its own column. */
+var TpoStacking = /* @__PURE__ */ function(TpoStacking) {
+	TpoStacking["Collapsed"] = "collapsed";
+	TpoStacking["Split"] = "split-brackets";
+	return TpoStacking;
+}({});
+var TpoGrouping = /* @__PURE__ */ function(TpoGrouping) {
+	TpoGrouping["Session"] = "session";
+	TpoGrouping["Week"] = "week";
+	TpoGrouping["Composite"] = "composite";
+	return TpoGrouping;
+}({});
+var TpoBracket = /* @__PURE__ */ function(TpoBracket) {
+	TpoBracket["ThirtyMinutes"] = "30m";
+	TpoBracket["Hour"] = "60m";
+	return TpoBracket;
+}({});
+var LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+var STEPS = [
+	1,
+	2,
+	2.5,
+	5,
+	10
+];
+var shortDay = utcFormat("%b %-d");
+var isoDay = (date) => date.toISOString().slice(0, 10);
+/** Market Profile arithmetic: time brackets, TPO rows, point of control and the CBOT value area. */
+var TpoProfile = class {
+	static letter(bracket) {
+		return LETTERS[bracket % 52];
+	}
+	/** Smallest 1-2-2.5-5 price increment that fits the range in `rows` rows. */
+	static tick(range, rows, reference = 1) {
+		const wanted = (range || Math.abs(reference) * .01 || 1) / Math.max(1, rows);
+		const scale = 10 ** Math.floor(Math.log10(wanted));
+		return (STEPS.find((step) => step * scale >= wanted * (1 - 1e-9)) ?? 10) * scale;
+	}
+	/**
+	* Buckets bars into profiles and time brackets. Bars with no intraday timing cannot form brackets, so
+	* each becomes its own bracket inside a weekly profile. `tags` optionally names each bar's session.
+	*/
+	static groups(bars, tags, grouping, minutes) {
+		const days = bars.map((bar, i) => tags[i] ?? (bar.date ? isoDay(bar.date) : "undated"));
+		const order = [...new Set(days)];
+		const intraday = order.length < days.length;
+		const opened = /* @__PURE__ */ new Map();
+		bars.forEach((bar, i) => {
+			if (bar.date) opened.set(days[i], Math.min(opened.get(days[i]) ?? Infinity, bar.date.getTime()));
+		});
+		const groups = /* @__PURE__ */ new Map();
+		const seen = /* @__PURE__ */ new Map();
+		bars.forEach((bar, i) => {
+			const day = days[i], ordinal = seen.get(day) ?? 0;
+			seen.set(day, ordinal + 1);
+			const weekly = grouping === "week" || !intraday;
+			const key = grouping === "composite" ? "composite" : weekly ? bar.date ? isoDay(utcMonday(bar.date)) : "undated" : day;
+			if (!groups.has(key)) groups.set(key, {
+				key,
+				label: this.label(bar, tags[i] ?? null, grouping, weekly),
+				periods: /* @__PURE__ */ new Map()
+			});
+			const group = groups.get(key);
+			const bracket = !intraday ? group.periods.size : bar.date ? Math.floor((bar.date.getTime() - opened.get(day)) / (minutes * 6e4)) : ordinal;
+			const id = `${day}/${bracket}`;
+			const period = group.periods.get(id);
+			if (!period) group.periods.set(id, {
+				order: order.indexOf(day),
+				bracket,
+				start: bar.date,
+				open: bar.open,
+				high: bar.high,
+				low: bar.low,
+				close: bar.close
+			});
+			else {
+				period.high = Math.max(period.high, bar.high);
+				period.low = Math.min(period.low, bar.low);
+				period.close = bar.close;
+			}
+		});
+		return [...groups.values()].map(({ key, label, periods }) => ({
+			key,
+			label,
+			periods: [...periods.values()].sort((a, b) => a.order - b.order || a.bracket - b.bracket)
+		}));
+	}
+	static label(bar, tag, grouping, weekly) {
+		if (grouping === "composite") return "Composite";
+		if (weekly) return bar.date ? `Wk of ${shortDay(utcMonday(bar.date))}` : "Undated";
+		return tag ?? (bar.date ? shortDay(bar.date) : "Undated");
+	}
+	/** One TPO per row per period, stacked left to right in time order. `openingBrackets` span the first hour. */
+	static session({ key, label, periods }, tick, share, openingBrackets) {
+		const place = (price) => Math.round(price / tick);
+		const stacks = /* @__PURE__ */ new Map();
+		const first = periods[0], last = periods.at(-1);
+		for (const period of periods) for (let row = place(period.low); row <= place(period.high); row++) {
+			const stack = stacks.get(row) ?? [];
+			stacks.set(row, stack);
+			stack.push({
+				row,
+				price: this.price(row, tick),
+				bracket: period.bracket,
+				letter: this.letter(period.bracket),
+				stack: stack.length,
+				mark: null
+			});
+		}
+		this.flag(stacks, first, place(first.open), "open");
+		this.flag(stacks, last, place(last.close), "close");
+		const rows = [...stacks.entries()].sort((a, b) => a[0] - b[0]).map(([row, cells]) => ({
+			row,
+			price: this.price(row, tick),
+			count: cells.length,
+			letters: cells.map((cell) => cell.letter).join("")
+		}));
+		const poc = this.pointOfControl(rows);
+		const [low, high] = this.valueArea(rows, rows.indexOf(poc), share);
+		const opening = periods.filter((period) => period.order === first.order && period.bracket < openingBrackets);
+		return {
+			key,
+			label,
+			rows,
+			poc,
+			cells: [...stacks.values()].flat(),
+			brackets: max(periods, (period) => period.bracket) + 1,
+			valueLow: rows[low].price,
+			valueHigh: rows[high].price,
+			balance: [min(opening, (period) => period.low), max(opening, (period) => period.high)]
+		};
+	}
+	static price(row, tick) {
+		return +(row * tick).toFixed(10);
+	}
+	static flag(stacks, period, row, mark) {
+		const cell = stacks.get(row)?.findLast((candidate) => candidate.bracket === period.bracket);
+		if (cell) cell.mark = mark;
+	}
+	/** Most TPOs wins; a tie goes to the row nearest the middle of the range. */
+	static pointOfControl(rows) {
+		const middle = (rows[0].price + rows.at(-1).price) / 2;
+		const distance = (row) => Math.abs(row.price - middle);
+		return rows.reduce((best, row) => row.count > best.count || row.count === best.count && distance(row) < distance(best) ? row : best);
+	}
+	/** CBOT method: from the POC, compare the next two rows on each side and take the heavier pair until `share` of TPOs is held. A tied pair takes both. */
+	static valueArea(rows, poc, share) {
+		const pair = (index, step) => (rows[index + step]?.count ?? 0) + (rows[index + step * 2]?.count ?? 0);
+		const target = rows.reduce((sum, row) => sum + row.count, 0) * share;
+		let low = poc, high = poc, held = rows[poc].count;
+		while (held < target && (low > 0 || high < rows.length - 1)) {
+			const below = pair(low, -1), above = pair(high, 1);
+			if (above >= below) {
+				held += above;
+				high = Math.min(rows.length - 1, high + 2);
+			}
+			if (below >= above) {
+				held += below;
+				low = Math.max(0, low - 2);
+			}
+		}
+		return [low, high];
+	}
+};
+export { TpoBracket, TpoForm, TpoGrouping, TpoProfile, TpoStacking };