@k2b/editor 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/editor",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Configurable Markdown editor for SolidJS: editor, toolbar, bubble menu, and slash menu on one shared state.",
   "type": "module",
   "sideEffects": [
@@ -70,7 +70,7 @@
     "@codemirror/state": "6.7.1",
     "@codemirror/view": "6.43.7",
     "@k2b/stdlib": "0.30.0",
-    "@k2b/ui": "0.50.0",
+    "@k2b/ui": "0.51.0",
     "@lezer/common": "1.5.3",
     "@lezer/highlight": "1.2.4",
     "@lezer/markdown": "1.7.2",

package/src/chart-schema.ts

@@ -1,12 +1,10 @@
-import { chartLocaleSchema } from "./chart-locale";
-
-export { chartAcceptsLocale, chartLocaleSchema } from "./chart-locale";
-
+import type { ChartInput, ChartLimits } from "@k2b/ui/charts";
 import { CALENDAR_MAX_DAYS, calendarDay } from "@k2b/ui/charts/core";
 import { z } from "zod";
+import { chartLocaleSchema } from "./chart-locale";
 
-/** Optional caller policy. Rendering itself has no AI input budget. */
-export type ChartLimits = { maxSeries: number; maxValues: number; maxMarks: number };
+export type { ChartDateFormat, ChartDescription, ChartFormat, ChartInput, ChartLimits, ChartNumberFormat } from "@k2b/ui/charts";
+export { chartAcceptsLocale, chartLocaleSchema } from "./chart-locale";
 
 // Every chart schema is built by a function whose call is marked pure, so a bundle that imports neither chart contract
 // leaves them out. App frames include the app contract through `cloud.chart()`.
@@ -31,12 +29,24 @@ export const chartNumberFormatSchema = () =>
 const dateFormatSchema = () => z.strictObject({ date: z.enum(["day", "minute", "second"]) });
 export const chartFormatSchema = () => z.union([chartNumberFormatSchema(), dateFormatSchema()]);
 
-export type ChartNumberFormat = z.output<ReturnType<typeof chartNumberFormatSchema>>;
-export type ChartDateFormat = z.output<ReturnType<typeof dateFormatSchema>>;
-export type ChartFormat = ChartNumberFormat | ChartDateFormat;
-
 export const chartKindSchema = () =>
-  z.enum(["area", "bar", "line", "scatter", "pie", "donut", "histogram", "gauge", "sparkline", "boxplot", "heatmap", "barGauge", "stat"]);
+  z.enum([
+    "waterfall",
+    "area",
+    "bar",
+    "hbar",
+    "line",
+    "scatter",
+    "pie",
+    "donut",
+    "histogram",
+    "gauge",
+    "sparkline",
+    "boxplot",
+    "heatmap",
+    "barGauge",
+    "stat",
+  ]);
 
 export const chartParts = (limits?: ChartLimits) => {
   const ChartLabel = limits ? z.string().trim().min(1).max(80) : z.union([z.string(), z.number().transform(String)]);
@@ -154,6 +164,27 @@ export const chartKinds = (limits?: ChartLimits) => {
   const ChartKindCommon = { ...ChartCommon, tooltip: ChartTooltip.optional() };
   const numberFormat = chartNumberFormatSchema();
   return z.discriminatedUnion("kind", [
+    z
+      .object({
+        kind: z.literal("waterfall"),
+        ...ChartKindCommon,
+        start: z.object({ label: ChartLabel, value: z.number() }),
+        steps: list(z.object({ label: ChartLabel, value: z.number() }), 0, limits?.maxValues),
+        end: z.strictObject({ label: ChartLabel }),
+        format: numberFormat.optional(),
+      })
+      .superRefine((spec, ctx) => {
+        let balance = spec.start.value;
+        let lo = Math.min(0, balance),
+          hi = Math.max(0, balance);
+        for (const step of spec.steps) {
+          balance += step.value;
+          lo = Math.min(lo, balance);
+          hi = Math.max(hi, balance);
+        }
+        if (!Number.isFinite(balance) || !Number.isFinite(hi - lo))
+          ctx.addIssue({ code: "custom", message: "Waterfall balances must form a finite range." });
+      }),
     z
       .object({
         kind: z.literal("area"),
@@ -175,17 +206,65 @@ export const chartKinds = (limits?: ChartLimits) => {
           if (!Number.isFinite(sum)) ctx.addIssue({ code: "custom", path: ["x", i], message: "Area totals must be finite." });
         });
       }),
-    z.object({
-      kind: z.literal("bar"),
-      ...ChartKindCommon,
-      data: list(ChartCategory, 1, limits?.maxValues),
-      xAxis: ChartAxis.pick({ label: true }).strict().optional(),
-      yAxis: ChartAxis.optional(),
-      colorByBar: z.boolean().optional(),
-      showValues: z.boolean().optional(),
-      legend: z.boolean().optional(),
-      references: ChartReferences.optional(),
-    }),
+    z
+      .object({
+        kind: z.literal("bar"),
+        ...ChartKindCommon,
+        data: list(ChartCategory, 0, limits?.maxValues).default([]),
+        x: list(ChartLabel, 0, limits?.maxValues).optional(),
+        series: list(
+          z.object({ label: ChartLabel, data: list(ChartNumber.nullable(), 0, limits?.maxValues) }),
+          1,
+          limits?.maxSeries,
+        ).optional(),
+        layout: z.enum(["columns", "rows", "grouped", "stacked"]).optional(),
+        normalize: z.boolean().optional(),
+        compare: z.object({ label: ChartLabel, data: list(ChartNumber.nullable(), 0, limits?.maxValues) }).optional(),
+        xAxis: ChartAxis.pick({ label: true }).extend({ ordered: z.boolean().optional() }).strict().optional(),
+        yAxis: ChartAxis.optional(),
+        colorByBar: z.boolean().optional(),
+        showValues: z.boolean().optional(),
+        legend: z.boolean().optional(),
+        references: ChartReferences.optional(),
+      })
+      .superRefine((bar, ctx) => {
+        const issue = (message: string) => ctx.addIssue({ code: "custom", message });
+        if (limits && !bar.series && !bar.data.length)
+          ctx.addIssue({ code: "custom", path: ["data"], message: "A bar chart needs data or aligned series." });
+        if (bar.series) {
+          if (!bar.x || bar.series.some((s) => s.data.length !== bar.x?.length)) issue("Bar series must have the same length as x.");
+          if (bar.data.length) issue("Use data or aligned series, not both.");
+          if (bar.layout === "rows" || bar.layout === "columns") issue("Series bars use grouped or stacked layout.");
+        } else if (bar.x || bar.compare || bar.layout === "grouped" || bar.layout === "stacked")
+          issue("This layout needs aligned x and series.");
+        if (bar.layout === "stacked" && bar.yAxis?.scale === "log") issue("Stacked bars need a linear axis.");
+        if (bar.normalize && bar.layout !== "stacked") issue("Normalized bars must be stacked.");
+        if (bar.layout === "stacked" && bar.series?.some((s) => s.data.some((v) => v !== null && v < 0)))
+          issue("Stacked bars require nonnegative values.");
+        if (bar.compare && (bar.series?.length !== 1 || bar.compare.data.length !== bar.x?.length || bar.layout === "stacked"))
+          issue("Comparison needs one current series and aligned previous values.");
+      }),
+    z
+      .object({
+        kind: z.literal("hbar"),
+        ...ChartKindCommon,
+        series: list(ChartLabel, 1, limits?.maxSeries),
+        rows: list(
+          z.object({
+            group: ChartLabel.optional(),
+            label: ChartLabel,
+            values: list(z.number().nonnegative().nullable(), 0, limits?.maxSeries),
+          }),
+          1,
+          limits?.maxValues,
+        ),
+        legend: z.boolean().optional(),
+        format: numberFormat.optional(),
+      })
+      .superRefine((bar, ctx) => {
+        if (bar.rows.some((r) => r.values.length !== bar.series.length))
+          ctx.addIssue({ code: "custom", message: "Horizontal bar values must match series." });
+      }),
     z.object({
       kind: z.literal("line"),
       ...ChartKindCommon,
@@ -339,5 +418,10 @@ export const chartDateTime = (value: string): number | undefined => {
   return date.toISOString().startsWith(`${year}-${month}-${day}T${hour}:${minute}:${second}`) ? date.getTime() : undefined;
 };
 
-/** One chart as the shared renderers read it. */
-export type ChartInput = z.output<ReturnType<typeof chartKinds>>;
+// Both directions are checked: a validator change must update the ui-owned description too.
+type Assert<T extends true> = T;
+type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+type _ChartSchemaMatchesDescription = Assert<Same<z.output<ReturnType<typeof chartKinds>>, ChartInput>>;
+type _ChartNumberFormatSchemaMatchesDescription = Assert<
+  Same<z.output<ReturnType<typeof chartNumberFormatSchema>>, import("@k2b/ui/charts").ChartNumberFormat>
+>;

package/src/charts.ts

@@ -15,6 +15,8 @@ import {
   extendDomainToNice,
   gauge,
   type HeatmapChartOptions,
+  type HorizontalBarOptions,
+  hbarLayout,
   histogram,
   line,
   niceLogTicks,
@@ -22,10 +24,13 @@ import {
   pie,
   renderAreaSvg,
   renderBarChartSvg,
+  renderHbarSvg,
   renderHeatmapSvg,
+  renderWaterfallSvg,
   scatter,
   sparkline,
   stat,
+  type WaterfallOptions,
 } from "@k2b/ui/charts/core";
 import { z } from "zod";
 import { type ChartFormat, type ChartInput, type ChartNumberFormat, chartDateTime, chartKinds } from "./chart-schema";
@@ -33,15 +38,19 @@ import { type ChartFormat, type ChartInput, type ChartNumberFormat, chartDateTim
 export * from "./chart-schema";
 
 type RenderOptions = {
-  [K in ChartInput["kind"]]: { kind: K } & (K extends "area"
-    ? AreaOptions
-    : K extends "heatmap"
-      ? HeatmapChartOptions
-      : K extends "bar"
-        ? BarChartOptions
-        : K extends keyof typeof charts
-          ? Omit<Parameters<(typeof charts)[K]>[0], "width" | "height" | "inspect">
-          : never);
+  [K in ChartInput["kind"]]: { kind: K } & (K extends "hbar"
+    ? HorizontalBarOptions
+    : K extends "waterfall"
+      ? WaterfallOptions
+      : K extends "area"
+        ? AreaOptions
+        : K extends "heatmap"
+          ? HeatmapChartOptions
+          : K extends "bar"
+            ? BarChartOptions & { data: NonNullable<BarChartOptions["data"]> }
+            : K extends keyof typeof charts
+              ? Omit<Parameters<(typeof charts)[K]>[0], "width" | "height" | "inspect">
+              : never);
 }[ChartInput["kind"]];
 
 /**
@@ -57,7 +66,13 @@ const labels = /* @__PURE__ */ i18n.define({
     en: {
       category: "Category",
       series: "Series",
+      balance: "Balance",
+      before: "Balance before",
+      inflow: "In",
+      outflow: "Out",
+      after: "Balance after",
       value: "Value",
+      total: "Total",
       share: "Share",
       position: "Position",
       from: "From",
@@ -75,7 +90,13 @@ const labels = /* @__PURE__ */ i18n.define({
     de: {
       category: "Kategorie",
       series: "Datenreihe",
+      balance: "Stand",
+      before: "Stand davor",
+      inflow: "Rein",
+      outflow: "Raus",
+      after: "Stand danach",
       value: "Wert",
+      total: "Gesamt",
       share: "Anteil",
       position: "Position",
       from: "Von",
@@ -137,7 +158,19 @@ export const chartReferenceValues = (input: ChartInput, name: "x" | "y") =>
 
 /** The value axes of a chart with what they show: the data checks and the label room read them alike. */
 export const chartValueAxes = (input: ChartInput): { values: number[]; axis?: ChartAxisInput; zero?: boolean; name: "x" | "y" }[] => {
-  if (input.kind === "bar") return [{ values: input.data.map((item) => item.value), axis: input.yAxis, zero: true, name: "y" }];
+  if (input.kind === "bar")
+    return [
+      {
+        values: [
+          ...input.data.map((item) => item.value),
+          ...(input.series?.flatMap((s) => s.data.filter((v): v is number => v !== null)) ?? []),
+          ...(input.compare?.data.filter((v): v is number => v !== null) ?? []),
+        ],
+        axis: input.yAxis,
+        zero: true,
+        name: "y",
+      },
+    ];
   if (input.kind === "boxplot") return [{ values: input.data.flatMap((item) => item.values), axis: input.yAxis, name: "y" }];
   if (input.kind === "histogram") {
     if (!input.references?.length) return [{ values: input.data, name: "x" }];
@@ -246,13 +279,22 @@ const numberFormat = (format: ChartFormat | undefined) => (format && !("date" in
 /** The values a chart writes with its value format, for whole-number currency. */
 const formattedValues = (input: ChartInput): number[] => {
   switch (input.kind) {
+    case "waterfall":
+      return [input.start.value, ...input.steps.map((step) => step.value)];
     case "area":
       return input.series.flatMap((s) => s.data.filter((v): v is number => v !== null));
     case "line":
     case "scatter":
       return [...input.series.flatMap((series) => series.data.map((point) => point.y)), ...chartReferenceValues(input, "y")];
     case "bar":
-      return [...input.data.map((item) => item.value), ...chartReferenceValues(input, "y")];
+      return [
+        ...input.data.map((item) => item.value),
+        ...(input.series?.flatMap((s) => s.data.filter((v): v is number => v !== null)) ?? []),
+        ...(input.compare?.data.filter((v): v is number => v !== null) ?? []),
+        ...chartReferenceValues(input, "y"),
+      ];
+    case "hbar":
+      return input.rows.flatMap((r) => r.values.filter((v): v is number => v !== null));
     case "pie":
     case "donut":
       return input.data.map((item) => item.value);
@@ -323,6 +365,8 @@ export function chartLegend(
   input: ChartInput,
   locale: string,
 ): { label: string; color: number; style?: "solid" | "dashed" | "dotted"; reference?: boolean }[] {
+  // These category renderers own their live legends, including prepared snapshots.
+  if (input.kind === "hbar" || (input.kind === "bar" && input.series)) return [];
   if (input.kind === "bar")
     return input.colorByBar && input.legend ? input.data.map((entry, index) => ({ label: entry.label, color: index % 8 })) : [];
   if (input.kind === "area") return input.legend === false ? [] : input.series.map((s, i) => ({ label: s.label, color: i % 8 }));
@@ -367,6 +411,25 @@ export function chartRenderOptions(
   const width = options.width ?? WIDTH;
   const references = renderReferences(input);
   switch (input.kind) {
+    case "hbar":
+      return {
+        kind: "hbar",
+        locale,
+        series: input.series,
+        rows: input.rows,
+        legend: input.legend,
+        valueFormat: format.value,
+      };
+    case "waterfall":
+      return {
+        kind: "waterfall",
+        start: input.start,
+        steps: input.steps,
+        end: input.end,
+        displayWidth: options.width ?? 296,
+        locale,
+        format: format.value,
+      };
     case "area":
       return {
         kind: "area",
@@ -386,14 +449,20 @@ export function chartRenderOptions(
       if (input.kind === "bar")
         return {
           kind: "bar",
+          locale,
           data: input.data,
+          x: input.x,
+          series: input.series,
+          layout: input.layout,
+          normalize: input.normalize,
+          compare: input.compare,
           xAxis: input.xAxis,
           yAxis: axis(yAxis, options.formats?.y ?? format.tick),
           // A host's own function format writes printed values like its ticks and table cells.
           valueFormat: options.formats?.value ?? options.formats?.y ?? format.value,
           colorByBar: input.colorByBar,
           showValues: input.showValues,
-          legend: options.legend === "outside" ? false : input.legend,
+          legend: input.series ? input.legend : options.legend === "outside" ? false : input.legend,
           references,
           ...(options.width === undefined ? {} : { displayWidth: options.width }),
         };
@@ -545,6 +614,10 @@ const decode = (value: string) =>
 export const drawChart = (options: RenderOptions): string => {
   const common = { width: WIDTH, height: HEIGHT, inspect: true };
   switch (options.kind) {
+    case "hbar":
+      return renderHbarSvg({ ...options, ...common, height: hbarLayout(options).height });
+    case "waterfall":
+      return renderWaterfallSvg({ ...options, ...common });
     case "area":
       return renderAreaSvg({ ...options, ...common });
     case "bar":
@@ -594,7 +667,12 @@ export const chartMarkKey = (datum: Pick<ChartDatum, "index" | "seriesIndex"> &
   `${datum.role === "outlier" ? "outlier:" : datum.role === "value" ? "value:" : ""}${datum.seriesIndex ?? 0}:${datum.index}`;
 
 export type ChartColumn = { id: string; label: string; numeric: boolean };
-export type ChartRow = { key: string; cells: Record<string, string>; values: Record<string, string | number> };
+export type ChartRow = {
+  key: string;
+  cells: Record<string, string>;
+  values: Record<string, string | number>;
+  tooltip?: { title?: string; rows: { label: string; value: string }[] };
+};
 export type ChartTable = { columns: ChartColumn[]; rows: ChartRow[] };
 
 /** The first text column titles the tooltip; the other columns become rows, matching the table in every host. */
@@ -603,6 +681,7 @@ export function chartTooltip(
   row: ChartRow,
   kind?: ChartInput["kind"],
 ): { title?: string; rows: { label: string; value: string }[] } {
+  if (row.tooltip) return row.tooltip;
   if (kind === "area")
     return {
       title: row.cells.x,
@@ -644,8 +723,19 @@ export function chartRows(
   const unit = "unit" in input && input.unit ? ` ${input.unit}` : "";
   const columns = new Map<string, ChartColumn>();
   const rows: ChartRow[] = [];
+  if (input.kind === "waterfall") {
+    for (const [id, label, numeric] of [
+      ["label", t.category, false],
+      ["before", t.before, true],
+      ["inflow", t.inflow, true],
+      ["outflow", t.outflow, true],
+      ["after", t.after, true],
+    ] as const)
+      columns.set(id, { id, label, numeric });
+  }
   const named = series.some((entry) => entry.label);
   const add = (datum: ChartDatum): ChartRow => {
+    const tooltip = input.kind === "waterfall" ? { title: datum.label, rows: [] as { label: string; value: string }[] } : undefined;
     const cells: Record<string, string> = {};
     const values: Record<string, string | number> = {};
     const cell = (id: string, label: string, value: string | number, text: string) => {
@@ -663,7 +753,9 @@ export function chartRows(
       // Bars may hide some axis labels; the table names every category.
       const label =
         input.kind === "bar" || input.kind === "pie" || input.kind === "donut" || input.kind === "boxplot" || input.kind === "barGauge"
-          ? input.data[datum.role === "outlier" ? (datum.seriesIndex ?? 0) : datum.index]?.label
+          ? ((input.kind === "bar" && input.series
+              ? undefined
+              : input.data[datum.role === "outlier" ? (datum.seriesIndex ?? 0) : datum.index]?.label) ?? datum.label)
           : datum.label;
       if (label)
         cell("label", input.kind === "heatmap" && input.layout === "calendar" ? calendarWords(locale).day : t.category, label, label);
@@ -678,8 +770,44 @@ export function chartRows(
         cell(field.key, field.key.toUpperCase(), value, value);
         continue;
       }
+      if (input.kind === "hbar" || (input.kind === "bar" && input.series)) {
+        const seriesIndex = field.key.startsWith("series:") ? Number(field.key.slice(7)) : undefined;
+        const label =
+          seriesIndex === undefined
+            ? field.key === "previous" && input.kind === "bar"
+              ? (input.compare?.label ?? field.key)
+              : field.key === "total"
+                ? t.total
+                : field.key === "delta"
+                  ? t.delta
+                  : field.key
+            : input.kind === "hbar"
+              ? input.series[seriesIndex]!
+              : input.series![seriesIndex]!.label;
+        cell(field.key, label, value, field.formatted ?? String(value));
+        continue;
+      }
       if (typeof value !== "number" || field.key === "total") continue;
-      if (field.key === "x") {
+      if (input.kind === "waterfall" && ["balance", "before", "inflow", "outflow", "change", "after"].includes(field.key)) {
+        const label =
+          field.key === "balance"
+            ? t.balance
+            : field.key === "before"
+              ? t.before
+              : field.key === "inflow"
+                ? t.inflow
+                : field.key === "outflow"
+                  ? t.outflow
+                  : field.key === "after"
+                    ? t.after
+                    : t.delta;
+        const arrow = field.key === "inflow" ? "↙ " : field.key === "outflow" ? "↗ " : field.key === "change" ? "= " : "";
+        const text = `${arrow}${valueFormat(field.key === "inflow" || field.key === "outflow" ? Math.abs(value) : value)}`;
+        // Totals occupy the ending balance column; zero changes are neutral inflows.
+        const id = field.key === "balance" ? "after" : field.key === "change" ? "inflow" : field.key;
+        cell(id, label, value, text);
+        if (field.key !== "before") tooltip?.rows.push({ label, value: text });
+      } else if (field.key === "x") {
         const header =
           (input.kind === "line" || input.kind === "scatter" ? input.xAxis?.label : undefined) ??
           (input.kind === "area" ? t.position : "X");
@@ -728,7 +856,7 @@ export function chartRows(
         cell(field.key, t[field.key], value, `${fieldFormat(value)}${field.key === "min" || field.key === "max" ? unit : ""}`);
       }
     }
-    const row = { key: chartMarkKey(datum), cells, values };
+    const row = { key: chartMarkKey(datum), cells, values, ...(tooltip ? { tooltip } : {}) };
     rows.push(row);
     return row;
   };
@@ -745,11 +873,17 @@ export function chartTable(input: ChartInput, locale: string): ChartTable {
 /** Input values count against the budget, including observations summarized into boxes or bins. */
 export const chartMarks = (input: ChartInput): number => {
   switch (input.kind) {
+    case "waterfall":
+      return input.steps.length + 2;
     case "area":
       return input.series.reduce((sum, s) => sum + s.data.length, 0);
     case "line":
     case "scatter":
       return input.series.reduce((sum, series) => sum + series.data.length, 0);
+    case "bar":
+      return input.series ? (input.x?.length ?? 0) * (input.series.length + (input.compare ? 1 : 0)) : input.data.length;
+    case "hbar":
+      return input.rows.length * input.series.length;
     case "boxplot":
       return input.data.reduce((sum, box) => sum + box.values.length, 0);
     case "gauge":

package/src/markdown/lib/chart-blocks.ts

@@ -1,6 +1,6 @@
 import { highlight, text } from "@k2b/stdlib";
 import { prepareChartSnapshot } from "@k2b/ui";
-import { barChartLayout } from "@k2b/ui/charts";
+import { barChartLayout, hbarLayout } from "@k2b/ui/charts";
 import { Lexer, type Tokens } from "marked";
 import type { z } from "zod";
 import {
@@ -457,8 +457,9 @@ export const chartBlockFrame = (body: string[], options: Pick<MarkdownChartOptio
  */
 export const notebookChartHeight = (input: ChartInput, locale: string): number | undefined => {
   const options = chartRenderOptions(input, locale, { legend: "outside" });
+  if (options.kind === "hbar") return hbarLayout(options).height;
   if (options.kind === "heatmap" && options.layout === "calendar") return 280;
-  if (options.kind === "area") return 280;
+  if (options.kind === "waterfall" || options.kind === "area") return 280;
   if (options.kind !== "bar") return undefined;
   const layout = barChartLayout(options);
   return layout.layout === "rows" ? layout.height : undefined;