@bicharts/chart-host 0.5.31 → 0.5.32

package/dist/index.mjs

@@ -569,6 +569,170 @@ function qualifyGroupHeadingFor(row, state) {
   return null;
 }
 
+// src/selectionCard.ts
+var SYNTHETIC_PREFIX = "__";
+var NUMERIC_DATATYPE = /int|double|decimal|single|float|number|currency|money/i;
+function normaliseAggregation(raw) {
+  const s = String(raw ?? "").trim().toLowerCase();
+  if (!s) return "sum";
+  if (/^(avg|average|mean)$/.test(s)) return "average";
+  if (/^(min|minimum)$/.test(s)) return "min";
+  if (/^(max|maximum)$/.test(s)) return "max";
+  if (/^(count|countrows)$/.test(s)) return "count";
+  if (/^(median|med)$/.test(s)) return "median";
+  if (/^(distinctcount|dcount|countdistinct|uniques?)$/.test(s)) return "distinctcount";
+  return "sum";
+}
+function isAdditive(agg) {
+  return agg === "sum" || agg === "count";
+}
+function aggLabel(agg) {
+  switch (agg) {
+    case "average":
+      return "Average";
+    case "min":
+      return "Min";
+    case "max":
+      return "Max";
+    case "count":
+      return "Count";
+    case "median":
+      return "Median";
+    case "distinctcount":
+      return "Distinct";
+    default:
+      return "Sum";
+  }
+}
+function isSynthetic(name) {
+  return String(name ?? "").startsWith(SYNTHETIC_PREFIX);
+}
+function isMeasureColumn(col) {
+  if (!col || isSynthetic(col.name)) return false;
+  if (col.isMeasure === true) return true;
+  return NUMERIC_DATATYPE.test(String(col.dataType ?? ""));
+}
+function toNumber(v) {
+  if (v == null || v === "") return null;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+function reduce(values, agg, distinctRaw) {
+  if (agg === "count") return values.length;
+  if (agg === "distinctcount") return new Set(distinctRaw.map((v) => v == null ? "\0" : String(v))).size;
+  if (!values.length) return null;
+  switch (agg) {
+    case "average":
+      return values.reduce((a, b) => a + b, 0) / values.length;
+    case "min":
+      return Math.min(...values);
+    case "max":
+      return Math.max(...values);
+    case "median": {
+      const s = [...values].sort((a, b) => a - b);
+      const m = s.length >> 1;
+      return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+    }
+    default:
+      return values.reduce((a, b) => a + b, 0);
+  }
+}
+function fmtNumber(v, culture) {
+  try {
+    const abs = Math.abs(v);
+    const opts = abs >= 1e6 ? { notation: "compact", maximumFractionDigits: 1 } : { maximumFractionDigits: abs < 10 ? 2 : 0 };
+    return new Intl.NumberFormat(culture || void 0, opts).format(v);
+  } catch {
+    return String(Math.round(v * 100) / 100);
+  }
+}
+function computeSelectionCard(payload, selectedRowIdxs, opts = {}) {
+  const columns = payload?.columns ?? [];
+  const rows = payload?.rows ?? [];
+  if (!columns.length || !rows.length) return null;
+  const wanted = Array.from(new Set((selectedRowIdxs ?? []).filter((n) => Number.isInteger(n))));
+  if (!wanted.length) return null;
+  const rowIdxCol = columns.findIndex((c) => c?.name === "__rowIdx__");
+  let byIdx = null;
+  if (rowIdxCol >= 0) {
+    byIdx = /* @__PURE__ */ new Map();
+    for (let r = 0; r < rows.length; r++) {
+      const v = toNumber(rows[r]?.[rowIdxCol]);
+      if (v != null) byIdx.set(v, r);
+    }
+  }
+  const positions = [];
+  for (const idx of wanted) {
+    const pos = byIdx ? byIdx.get(idx) : idx;
+    if (pos != null && pos >= 0 && pos < rows.length) positions.push(pos);
+  }
+  if (!positions.length) return null;
+  const agg = normaliseAggregation(opts.aggregation);
+  const maxMeasures = opts.maxMeasures ?? 4;
+  const maxHeaderValues = opts.maxHeaderValues ?? 3;
+  const dimIdx = columns.findIndex((c) => c && !isSynthetic(c.name) && !isMeasureColumn(c));
+  let header;
+  if (dimIdx >= 0) {
+    const seen = [];
+    const set = /* @__PURE__ */ new Set();
+    for (const p of positions) {
+      const raw = rows[p]?.[dimIdx];
+      const s = raw == null || raw === "" ? "(blank)" : String(raw);
+      if (!set.has(s)) {
+        set.add(s);
+        seen.push(s);
+      }
+      if (seen.length > maxHeaderValues) break;
+    }
+    header = seen.length > maxHeaderValues ? `${positions.length} marks` : seen.join(", ");
+  } else {
+    header = `${positions.length} mark${positions.length === 1 ? "" : "s"}`;
+  }
+  const measureCols = [];
+  for (let c = 0; c < columns.length; c++) if (isMeasureColumn(columns[c])) measureCols.push(c);
+  const shown = measureCols.slice(0, maxMeasures);
+  const lines = [];
+  for (const c of shown) {
+    const selVals = [];
+    const selRaw = [];
+    for (const p of positions) {
+      const n = toNumber(rows[p]?.[c]);
+      selRaw.push(rows[p]?.[c]);
+      if (n != null) selVals.push(n);
+    }
+    const value = reduce(selVals, agg, selRaw);
+    let sharePct = null;
+    if (isAdditive(agg) && value != null) {
+      const allVals = [];
+      const allRaw = [];
+      for (let r = 0; r < rows.length; r++) {
+        const n = toNumber(rows[r]?.[c]);
+        allRaw.push(rows[r]?.[c]);
+        if (n != null) allVals.push(n);
+      }
+      const total = reduce(allVals, agg, allRaw);
+      if (total != null && total > 0) sharePct = value / total * 100;
+    }
+    lines.push({
+      column: String(columns[c]?.name ?? ""),
+      label: `${aggLabel(agg)} of ${columns[c]?.name ?? ""}`,
+      value,
+      valueText: value == null ? "\u2014" : fmtNumber(value, opts.cultureCode),
+      sharePct,
+      shareText: sharePct == null ? "" : `${sharePct < 0.1 ? "<0.1" : sharePct.toFixed(1)}% of total`
+    });
+  }
+  return {
+    header,
+    lines,
+    rowsText: `${positions.length} of ${rows.length} rows`,
+    selectedRows: positions.length,
+    totalRows: rows.length,
+    hiddenMeasures: Math.max(0, measureCols.length - shown.length),
+    aggregation: agg
+  };
+}
+
 // src/index.ts
 function registerCityTable(packed) {
   L3(packed);
@@ -610,6 +774,7 @@ export {
   clearGeoCache,
   compileRenderFn,
   compileTrivialSource,
+  computeSelectionCard,
   createChartHost,
   createMarkResolver,
   explainRenderFailure,
@@ -617,6 +782,7 @@ export {
   geoFromCache,
   loadGeo,
   newQualifyGroupState,
+  normaliseAggregation,
   planTrivialChart,
   qualifyGroupHeadingFor,
   rasterizeSvgToPngDataUrl,

package/dist/types/index.d.ts

@@ -12,3 +12,4 @@ export { captureSvgSnapshot, svgToDataUrl, svgNaturalSize, rasterizeSvgToPngData
 export { shouldReview, buildReviewWire, bareBase64, actionFor, type ReviewGate, type ReviewWire, type ReviewVerdict, type ReviewAction } from "./review";
 export { askApplyImprovements, type ReviewDialogOptions, type ReviewDialogText } from "./reviewDialog";
 export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, type QualifyGroupState, type QualifyGroupHeading, } from "./qualifyGroups";
+export { computeSelectionCard, normaliseAggregation, type SelectionCardModel, type SelectionCardLine, type SelectionCardOptions, } from "./selectionCard";

package/dist/types/selectionCard.d.ts

@@ -0,0 +1,53 @@
+import type { RenderPayload } from "./payload";
+export interface SelectionCardOptions {
+    /** The chart's own aggregation, so the card AGREES with the picture it sits on. A card
+     *  reading "Sum" beside a chart drawn from averages is two answers to one question. */
+    aggregation?: string;
+    cultureCode?: string;
+    /** Cards are capped at roughly a third of the tile, so the measure list is capped too.
+     *  `hiddenMeasures` reports what was dropped rather than truncating silently. */
+    maxMeasures?: number;
+    /** Past this many distinct dimension values the header becomes "N marks" — naming twelve
+     *  cities in a header is not a header. */
+    maxHeaderValues?: number;
+}
+export interface SelectionCardLine {
+    column: string;
+    /** "Sum of Revenue" — the aggregation is named because it is not always sum. */
+    label: string;
+    value: number | null;
+    valueText: string;
+    /** Share of the same aggregate over ALL rows. Null whenever a share would be a lie — see
+     *  isAdditive: the average of a subset is not a percentage of the average of the whole. */
+    sharePct: number | null;
+    shareText: string;
+}
+export interface SelectionCardModel {
+    header: string;
+    lines: SelectionCardLine[];
+    /** "6 of 24 rows" — the one line that is true regardless of what the columns contain. */
+    rowsText: string;
+    selectedRows: number;
+    totalRows: number;
+    /** Measures the cap left out, so a host can say "+2 more" instead of implying there were none. */
+    hiddenMeasures: number;
+    aggregation: string;
+}
+type Agg = "sum" | "average" | "min" | "max" | "count" | "median" | "distinctcount";
+/** Normalise the many spellings the hosts use into the set this file reduces over. Unknown
+ *  spellings fall back to sum rather than throwing: a card is a courtesy, and refusing to draw
+ *  one because a host wrote "Total" is a worse outcome than summing. */
+export declare function normaliseAggregation(raw: string | undefined | null): Agg;
+/**
+ * The card for a selection, or NULL when there is nothing to say.
+ *
+ * `selectedRowIdxs` are the values a mark carries in `data-row-idx` — which ARE row positions,
+ * because `buildRenderPayload` writes `__rowIdx__` as the row's own index. The mapping is
+ * resolved through that column when it is present rather than assumed, so a payload that ever
+ * reorders rows keeps working.
+ *
+ * Null (rather than an empty model) when the selection is empty, because "no selection" and "a
+ * selection that sums to nothing" are different states and only the first should dismiss the card.
+ */
+export declare function computeSelectionCard(payload: RenderPayload | null | undefined, selectedRowIdxs: number[] | null | undefined, opts?: SelectionCardOptions): SelectionCardModel | null;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.5.31",
+  "version": "0.5.32",
   "description": "Run a BIC-generated D3 chart in any web host: compiles the generated render() function, applies the shared option defaults, resolves mark clicks (through tooltip overlays), owns the selection affordance, and translates row indices between cross-filtered charts. The same contract the BIC Power BI visual implements, minus Power BI. React bindings at @bicharts/chart-host/react.",
   "license": "Apache-2.0",
   "type": "module",