@k2b/editor 0.6.5 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/editor",
-  "version": "0.6.5",
+  "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.49.0",
+    "@k2b/ui": "0.51.0",
     "@lezer/common": "1.5.3",
     "@lezer/highlight": "1.2.4",
     "@lezer/markdown": "1.7.2",

package/src/chart-locale.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+/** BCP 47 locale strings must be accepted by every Intl formatter used during rendering. */
+export const chartLocaleSchema = () =>
+  z
+    .string()
+    .min(1)
+    .refine((value) => {
+      try {
+        return Intl.getCanonicalLocales(value).length === 1;
+      } catch {
+        return false;
+      }
+    }, "Use a valid BCP 47 locale, such as de-DE.");
+
+/** The portable renderers which honour an explicit locale. Keep one policy for single charts and groups. */
+const localeKinds = new Set(["sankey", "treemap", "pareto", "bubble", "radar"]);
+export const chartAcceptsLocale = (chart: { kind?: string; layout?: string }): boolean =>
+  chart.kind === "heatmap" ? chart.layout === "calendar" : localeKinds.has(chart.kind ?? "");

package/src/chart-schema.ts

@@ -1,7 +1,10 @@
+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()`.
@@ -25,12 +28,25 @@ 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(["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)]);
@@ -60,7 +76,13 @@ export const chartParts = (limits?: ChartLimits) => {
   });
   // As many lines as series a reader can tell apart.
   const ChartReferences = list(
-    z.object({ value: z.union([z.number(), ChartDate]), axis: z.enum(["x", "y"]).optional(), label: ChartLabel.optional() }),
+    z.object({
+      value: z.union([z.number(), ChartDate]),
+      axis: z.enum(["x", "y"]).optional(),
+      label: ChartLabel.optional(),
+      style: z.enum(["solid", "dashed", "dotted"]).optional(),
+      tone: z.enum(["neutral", "info", "success", "warning", "danger"]).optional(),
+    }),
     0,
     limits?.maxSeries,
     `Use at most ${limits?.maxSeries} references.`,
@@ -142,17 +164,107 @@ export const chartKinds = (limits?: ChartLimits) => {
   const ChartKindCommon = { ...ChartCommon, tooltip: ChartTooltip.optional() };
   const numberFormat = chartNumberFormatSchema();
   return z.discriminatedUnion("kind", [
-    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("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"),
+        ...ChartKindCommon,
+        layout: z.literal("stacked"),
+        normalize: z.boolean().optional(),
+        x: list(z.union([z.number(), ChartLabel]), 1, limits?.maxValues),
+        series: list(z.object({ label: ChartLabel, data: list(z.number().min(0).nullable(), 0, limits?.maxValues) }), 1, limits?.maxSeries),
+        legend: z.boolean().optional(),
+        format: numberFormat.optional(),
+      })
+      .superRefine((spec, ctx) => {
+        spec.series.forEach((s, i) => {
+          if (s.data.length !== spec.x.length)
+            ctx.addIssue({ code: "custom", path: ["series", i, "data"], message: "Area series must match x length." });
+        });
+        spec.x.forEach((_, i) => {
+          const sum = spec.series.reduce((sum, s) => sum + (s.data[i] ?? 0), 0);
+          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, 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,
@@ -220,15 +332,51 @@ export const chartKinds = (limits?: ChartLimits) => {
       yAxis: ChartAxis.optional(),
       references: ChartReferences.optional(),
     }),
-    z.object({
-      kind: z.literal("heatmap"),
-      ...ChartKindCommon,
-      data: list(ChartCell, 1, limits?.maxMarks),
-      format: numberFormat.optional(),
-      showValues: z.boolean().optional(),
-      min: z.number().optional(),
-      max: z.number().optional(),
-    }),
+    z.discriminatedUnion("layout", [
+      z
+        .object({
+          kind: z.literal("heatmap"),
+          ...ChartKindCommon,
+          layout: z.literal("calendar"),
+          data: list(
+            z.tuple([
+              z.string().refine((day) => {
+                try {
+                  calendarDay(day);
+                  return true;
+                } catch {
+                  return false;
+                }
+              }, "Invalid ISO calendar day."),
+              ChartNumber.nullable(),
+            ]),
+            1,
+            limits?.maxMarks,
+          ),
+          scale: z.enum(["sequential", "diverging"]),
+          label: ChartLabel.optional(),
+          format: numberFormat.optional(),
+          locale: chartLocaleSchema().optional(),
+        })
+        .superRefine((spec, ctx) => {
+          if (ctx.issues.length) return;
+          const times = spec.data.map(([day]) => calendarDay(day));
+          if (times.length && (Math.max(...times) - Math.min(...times)) / 86400000 >= CALENDAR_MAX_DAYS)
+            ctx.addIssue({ code: "custom", message: "Calendar span must not exceed three years." });
+          if (new Set(spec.data.map(([day]) => day)).size !== spec.data.length)
+            ctx.addIssue({ code: "custom", message: "Calendar dates must be unique." });
+        }),
+      z.object({
+        kind: z.literal("heatmap"),
+        ...ChartKindCommon,
+        layout: z.undefined().optional(),
+        data: list(ChartCell, 1, limits?.maxMarks),
+        format: numberFormat.optional(),
+        showValues: z.boolean().optional(),
+        min: z.number().optional(),
+        max: z.number().optional(),
+      }),
+    ]),
     z.object({
       kind: z.literal("barGauge"),
       ...ChartKindCommon,
@@ -270,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

@@ -1,35 +1,56 @@
 // Named renderers, not the `charts` namespace, so bundles leave out the map and state timeline renderers.
+import { i18n } from "@k2b/stdlib";
 import {
+  type AreaOptions,
   autoBin,
+  type BarChartOptions,
+  barChartLayout,
   barGauge,
   boxplot,
   type ChartDatum,
+  calendarWords,
   type charts,
   computeDomain,
   donut,
   extendDomainToNice,
   gauge,
-  heatmap,
+  type HeatmapChartOptions,
+  type HorizontalBarOptions,
+  hbarLayout,
   histogram,
-  i18n,
   line,
   niceLogTicks,
   niceStep,
   pie,
+  renderAreaSvg,
+  renderBarChartSvg,
+  renderHbarSvg,
+  renderHeatmapSvg,
+  renderWaterfallSvg,
   scatter,
   sparkline,
   stat,
-} from "@k2b/stdlib";
-import { type BarChartOptions, barChartLayout, renderBarChartSvg } from "@k2b/ui/charts";
+  type WaterfallOptions,
+} from "@k2b/ui/charts/core";
 import { z } from "zod";
 import { type ChartFormat, type ChartInput, type ChartNumberFormat, chartDateTime, chartKinds } from "./chart-schema";
 
 export * from "./chart-schema";
 
 type RenderOptions = {
-  [K in ChartInput["kind"]]: { kind: K } & (K extends "bar"
-    ? BarChartOptions
-    : Omit<Parameters<(typeof charts)[K]>[0], "width" | "height" | "inspect">);
+  [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"]];
 
 /**
@@ -45,8 +66,15 @@ 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",
       to: "To",
       count: "Count",
@@ -62,8 +90,15 @@ 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",
       to: "Bis",
       count: "Anzahl",
@@ -123,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" }];
@@ -232,15 +279,29 @@ 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":
-    case "heatmap":
       return input.data.map((item) => item.value);
+    case "heatmap":
+      return input.layout === "calendar"
+        ? input.data.flatMap((item) => (item[1] === null ? [] : [item[1]]))
+        : input.data.map((item) => item.value);
     case "barGauge":
       return [...input.data.flatMap((item) => [item.value, item.min, item.max]), input.min, input.max].filter(
         (value) => value !== undefined,
@@ -304,8 +365,11 @@ 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 }));
   if (input.kind !== "line" && input.kind !== "scatter") return [];
   if (!(input.legend ?? input.series.length > 1)) return [];
   const t = labels.resolve([locale]).t;
@@ -334,6 +398,7 @@ export function chartRenderOptions(
     formats?: { x?: (v: number) => string; y?: (v: number) => string; value?: (v: number) => string };
   } = {},
 ): RenderOptions {
+  if (input.kind === "heatmap" && input.layout === "calendar") locale = input.locale ?? locale;
   const defaults = formats(input, locale);
   // Function formats must be measured with the same text the renderer will print.
   const format = {
@@ -346,6 +411,37 @@ 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",
+        layout: input.layout,
+        normalize: input.normalize,
+        x: input.x,
+        series: input.series,
+        displayWidth: options.width,
+        locale,
+        format: format.value,
+        legend: options.legend === "outside" ? false : input.legend,
+      };
     case "bar":
     case "boxplot": {
       const yAxis = referencedAxis(input, "y");
@@ -353,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 }),
         };
@@ -458,6 +560,17 @@ export function chartRenderOptions(
         thresholds: input.thresholds,
       };
     case "heatmap":
+      if (input.layout === "calendar")
+        return {
+          kind: "heatmap",
+          layout: "calendar",
+          data: input.data,
+          scale: input.scale,
+          label: input.label,
+          locale: input.locale ?? locale,
+          format: format.value,
+          displayWidth: options.width,
+        };
       return {
         kind: "heatmap",
         data: input.data,
@@ -501,6 +614,12 @@ 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":
       return renderBarChartSvg({ ...options, ...common, height: barChartLayout(options).height });
     case "line":
@@ -522,7 +641,7 @@ export const drawChart = (options: RenderOptions): string => {
     case "stat":
       return stat({ ...options, ...common });
     case "heatmap":
-      return heatmap({ ...options, ...common });
+      return renderHeatmapSvg({ ...options, ...common });
     case "sparkline":
       return sparkline({ ...options, ...common });
   }
@@ -548,11 +667,26 @@ 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. */
-export function chartTooltip(columns: ChartColumn[], row: ChartRow): { title?: string; rows: { label: string; value: string }[] } {
+export function chartTooltip(
+  columns: ChartColumn[],
+  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,
+      rows: [{ label: row.cells.series ?? "", value: `${row.cells.percent ? `${row.cells.percent} · ` : ""}${row.cells.value ?? "—"}` }],
+    };
   const [first, ...rest] = columns;
   const named = first && !first.numeric;
   return {
@@ -572,6 +706,7 @@ export function chartRows(
   locale: string,
   options: { formats?: { x?: (v: number) => string; y?: (v: number) => string; value?: (v: number) => string } } = {},
 ) {
+  if (input.kind === "heatmap" && input.layout === "calendar") locale = input.locale ?? locale;
   const t = labels.resolve([locale]).t;
   const format = formats(input, locale);
   const valueFormat = input.tooltip?.format
@@ -580,12 +715,27 @@ export function chartRows(
   const xFormat = options.formats?.x ?? format.x.value;
   const series = chartSeries(input);
   const countFormat = (input.kind === "histogram" ? options.formats?.y : undefined) ?? chartNumberFormatters(undefined, locale).value;
-  const percent = new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 });
+  const percent = new Intl.NumberFormat(locale, {
+    style: "percent",
+    minimumFractionDigits: input.kind === "area" ? 1 : 0,
+    maximumFractionDigits: 1,
+  });
   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) => {
@@ -593,33 +743,83 @@ export function chartRows(
       cells[id] = text;
       values[id] = value;
     };
+    if (input.kind === "area") cell("series", t.series, datum.label ?? "", datum.label ?? "");
     if (input.kind === "line" || input.kind === "scatter") {
       if (named || series.length > 1) {
         const name = series[datum.seriesIndex ?? 0]?.label ?? `${t.series} ${(datum.seriesIndex ?? 0) + 1}`;
         cell("series", t.series, name, name);
       }
-    } else {
+    } else if (input.kind !== "area") {
       // 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", t.category, label, label);
+      if (label)
+        cell("label", input.kind === "heatmap" && input.layout === "calendar" ? calendarWords(locale).day : t.category, label, label);
     }
     for (const field of datum.values) {
       const value = field.value;
+      if (typeof value === "string" && input.kind === "area" && field.key === "x") {
+        cell("x", t.position, value, field.formatted ?? value);
+        continue;
+      }
       if (typeof value === "string" && input.kind === "heatmap" && (field.key === "x" || field.key === "y")) {
         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") {
-        const header = (input.kind === "line" || input.kind === "scatter" ? input.xAxis?.label : undefined) ?? "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");
         cell(
           "x",
           input.kind === "sparkline" || input.kind === "stat" ? "#" : header,
           value,
-          input.kind === "sparkline" || input.kind === "stat" ? String(value + 1) : xFormat(value),
+          input.kind === "sparkline" || input.kind === "stat"
+            ? String(value + 1)
+            : input.kind === "area"
+              ? (field.formatted ?? String(value))
+              : xFormat(value),
         );
       } else if (field.key === "y") {
         const header =
@@ -630,9 +830,17 @@ export function chartRows(
       } else if (field.key === "value")
         cell(
           "value",
-          input.tooltip?.label ?? (input.kind === "bar" ? input.yAxis?.label : undefined) ?? t.value,
+          input.tooltip?.label ??
+            (input.kind === "bar"
+              ? input.yAxis?.label
+              : input.kind === "heatmap" && input.layout === "calendar"
+                ? input.label
+                : undefined) ??
+            t.value,
           value,
-          `${valueFormat(value)}${unit}`,
+          input.kind === "heatmap" && input.layout === "calendar"
+            ? (field.formatted ?? valueFormat(value))
+            : `${valueFormat(value)}${unit}`,
         );
       else if (field.key === "delta") cell("delta", t.delta, value, `${value > 0 ? "+" : ""}${valueFormat(value)}`);
       else if (field.key === "q1" || field.key === "q2" || field.key === "q3" || field.key === "whiskerLow" || field.key === "whiskerHigh")
@@ -648,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;
   };
@@ -665,9 +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,6 +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 === "waterfall" || options.kind === "area") return 280;
   if (options.kind !== "bar") return undefined;
   const layout = barChartLayout(options);
   return layout.layout === "rows" ? layout.height : undefined;
@@ -487,17 +490,31 @@ export const renderNotebookChartFigure = (input: ChartInput, locale: string, opt
       key: ({ datum }) => chartMarkKey(datum),
       tooltip: ({ datum }) => {
         const row = rows.add(datum);
-        return chartTooltip(rows.columns(), row);
+        return chartTooltip(rows.columns(), row, input.kind);
       },
       reference: ({ datum }) => chartReferenceMark(input, datum),
     });
     if (!snapshot.marks.length) return null;
     const legend = chartLegend(input, locale);
     const t = chartBlockMessages.resolve([locale]).t;
+    const valueField = input.kind === "area" ? (input.normalize ? "percent" : "value") : "y";
+    let lastX = -Infinity;
+    for (const mark of snapshot.marks) lastX = Math.max(lastX, mark.datum.anchor[0]);
+    const legendValue = (index: number) => {
+      const field = snapshot.marks
+        .find((mark) => mark.datum.seriesIndex === index && mark.datum.anchor[0] === lastX)
+        ?.datum.values.find((field) => field.key === valueField);
+      return field
+        ? (field.formatted ??
+            (typeof field.value === "number"
+              ? new Intl.NumberFormat(locale, { maximumFractionDigits: 6 }).format(field.value)
+              : field.value))
+        : "—";
+    };
     const legendHtml = legend.length
-      ? `<ul class="k2b-chart-legend" aria-label="${escape(t.chartLegend)}">${legend.map((entry) => `<li><span class="k2b-chart-legend__swatch"${entry.style && entry.style !== "solid" ? ` data-style="${entry.style}"` : ""}${entry.reference ? ' data-reference="true"' : ""} style="--k2b-chart-legend-color:var(--stdlib-chart-c${(entry.color % 8) + 1})" aria-hidden="true"></span>${escape(entry.label)}</li>`).join("")}</ul>`
+      ? `<ul class="k2b-chart-legend" aria-label="${escape(t.chartLegend)}">${legend.map((entry, index) => `<li><span class="k2b-chart-legend__swatch"${entry.style && entry.style !== "solid" ? ` data-style="${entry.style}"` : ""}${entry.reference ? ' data-reference="true"' : ""} style="--k2b-chart-legend-color:var(--stdlib-chart-c${(entry.color % 8) + 1})" aria-hidden="true"></span>${escape(entry.label)}${input.kind === "area" ? `<b data-chart-legend-value data-series-index="${index}" data-field="${valueField}" data-default="${escape(legendValue(index))}">${escape(legendValue(index))}</b>` : ""}</li>`).join("")}</ul>`
       : "";
-    const viewport = `<div class="k2b-chart" data-chart-kind="${snapshot.kind}"><div class="k2b-chart__svg"${snapshot.stretch ? ' data-stretch="true"' : ""} style="--k2b-chart-width:${snapshot.width}px;--k2b-chart-height:${snapshot.height}px">${snapshot.svg}</div></div>${legendHtml}`;
+    const viewport = `<div class="k2b-chart" data-chart-kind="${snapshot.kind}"><div class="k2b-chart__svg"${snapshot.stretch ? ' data-stretch="true"' : ""} style="${snapshot.minWidth ? "min-width:0;" : ""}--k2b-chart-width:${snapshot.width}px;--k2b-chart-height:${snapshot.height}px">${snapshot.svg}</div></div>${legendHtml}`;
     const height = notebookChartHeight(input, locale);
     const figure = notebookChartFrameHtml(height ? { ...input, height } : input, viewport, {
       legend: legend.length > 0,

package/src/markdown/notebook-charts.tsx

@@ -1,6 +1,7 @@
 import { i18n } from "@k2b/stdlib";
 import { CopyButton, IconButton, LocaleProvider, prepareChartSnapshot, toast } from "@k2b/ui";
 import { type ChartTooltip, inspectChart } from "@k2b/ui/chart-inspection";
+import { calendarInspectionNavigation, mountCalendarScroll } from "@k2b/ui/charts";
 import { createSignal, onCleanup, Show } from "solid-js";
 import { render } from "solid-js/web";
 import { type ChartInput, type ChartTable, chartMarkKey, chartReferenceMark, chartRenderOptions, chartRows, chartTooltip } from "../charts";
@@ -43,7 +44,7 @@ const draw = (input: ChartInput, locale: string): Drawn => {
     key: ({ datum }) => chartMarkKey(datum),
     tooltip: ({ datum }) => {
       const row = rows.add(datum);
-      return chartTooltip(rows.columns(), row);
+      return chartTooltip(rows.columns(), row, input.kind);
     },
     reference: ({ datum }) => chartReferenceMark(input, datum),
   });
@@ -121,8 +122,12 @@ export function enhanceNotebookCharts(root: HTMLElement, locale: string, options
     chart.setAttribute("aria-label", figure.querySelector(".notebook-book-chart__title")?.textContent ?? "");
     chart.setAttribute("aria-description", t.interactiveChart);
     chart.dataset.interactive = "true";
+    if (input.kind === "heatmap" && input.layout === "calendar") cleanups.push(mountCalendarScroll(chart));
     const inspection = inspectChart(chart, {
       kind: input.kind,
+      nav: input.kind === "heatmap" && input.layout === "calendar" ? calendarInspectionNavigation : undefined,
+      locale,
+      legend: figure,
       format: ({ datum }) => lazy().tooltips.get(chartMarkKey(datum)) ?? { rows: [] },
     });
     const dispose = render(