@cfasim-ui/docs 0.4.13 → 0.4.15

package/charts/BarChart/BarChart.md

@@ -1,8 +1,8 @@
 # BarChart
 
-A responsive SVG bar chart supporting single, grouped, and stacked series in
-either vertical (column) or horizontal orientation. Shares axis, tooltip,
-menu, and CSV export wiring with [`LineChart`](./line-chart).
+A responsive SVG bar chart supporting single, grouped, stacked, and overlay
+series in either vertical (column) or horizontal orientation. Shares axis,
+tooltip, menu, and CSV export wiring with [`LineChart`](./line-chart).
 
 ## Examples
 
@@ -100,6 +100,101 @@ menu, and CSV export wiring with [`LineChart`](./line-chart).
   </template>
 </ComponentDemo>
 
+### Overlay series
+
+`layout="overlay"` draws each series at full group width from the shared
+baseline, painting later series on top of earlier ones. Use it to compare
+a backdrop value (e.g. target, capacity, prior period) against a shorter
+foreground value sharing the same axis.
+
+Series render in the order they appear in `series`, so put the taller
+backdrop first and the shorter foreground after. Use `opacity`, a
+distinct color, or a per-series `blendMode` (see below) if bars might
+overlap fully.
+
+<ComponentDemo>
+  <BarChart
+    :series="[
+      { data: [40, 40, 40, 40], legend: 'Target', color: '#d4d4d8' },
+      { data: [22, 35, 28, 38], legend: 'Actual', color: '#0057b7' },
+    ]"
+    :categories="['Q1', 'Q2', 'Q3', 'Q4']"
+    layout="overlay"
+    :height="220"
+    y-label="Doses (thousands)"
+    tooltip-trigger="hover"
+  />
+
+<template #code>
+
+```vue
+<BarChart
+  :series="[
+    { data: [40, 40, 40, 40], legend: 'Target', color: '#d4d4d8' },
+    { data: [22, 35, 28, 38], legend: 'Actual', color: '#0057b7' },
+  ]"
+  :categories="['Q1', 'Q2', 'Q3', 'Q4']"
+  layout="overlay"
+  :height="220"
+  y-label="Doses (thousands)"
+  tooltip-trigger="hover"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Blend mode
+
+Set `blendMode` on a series to apply a CSS `mix-blend-mode` to every
+bar in that series. Useful with `layout="overlay"` (or just two
+overlapping grouped bars) to combine colors instead of one obscuring
+the other. Common picks: `"multiply"` (darkens light fills where bars
+overlap), `"screen"` (lightens dark fills), `"difference"` (high
+contrast).
+
+<ComponentDemo>
+  <BarChart
+    :series="[
+      { data: [22, 35, 28, 38], legend: 'Treatment A', color: '#ef4444', blendMode: 'multiply' },
+      { data: [30, 24, 36, 32], legend: 'Treatment B', color: '#3b82f6', blendMode: 'multiply' },
+    ]"
+    :categories="['Q1', 'Q2', 'Q3', 'Q4']"
+    layout="overlay"
+    :height="220"
+    y-label="Cases avoided"
+    tooltip-trigger="hover"
+  />
+
+<template #code>
+
+```vue
+<BarChart
+  :series="[
+    {
+      data: [22, 35, 28, 38],
+      legend: 'Treatment A',
+      color: '#ef4444',
+      blendMode: 'multiply',
+    },
+    {
+      data: [30, 24, 36, 32],
+      legend: 'Treatment B',
+      color: '#3b82f6',
+      blendMode: 'multiply',
+    },
+  ]"
+  :categories="['Q1', 'Q2', 'Q3', 'Q4']"
+  layout="overlay"
+  :height="220"
+  y-label="Cases avoided"
+  tooltip-trigger="hover"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Horizontal orientation
 
 <ComponentDemo>
@@ -208,6 +303,54 @@ LineChart's `x-tick-format` (e.g. `"iso"`, `"month-year"`, an
 `Intl.DateTimeFormatOptions` object, or a `(ms, unit?) => string`
 function).
 
+### Crowded categorical labels
+
+Non-date categorical labels are also thinned when they don't all fit:
+the chart estimates label width from character count and font size,
+then strides through the categories so adjacent labels never overlap.
+Every bar still renders — only the tick labels are skipped.
+
+<ComponentDemo>
+  <BarChart
+    data-testid="thinned-bar-chart"
+    :data="[3, 5, 8, 12, 18, 24, 31, 27, 22, 16, 11, 7, 4, 2]"
+    :categories="['2.11', '2.33', '2.56', '2.78', '3.00', '3.22', '3.44', '3.67', '3.89', '4.11', '4.33', '4.56', '4.78', '5.00']"
+    :width="380"
+    :height="220"
+    x-label="R₀"
+    y-label="Frequency"
+  />
+
+<template #code>
+
+```vue
+<BarChart
+  :data="[3, 5, 8, 12, 18, 24, 31, 27, 22, 16, 11, 7, 4, 2]"
+  :categories="[
+    '2.11',
+    '2.33',
+    '2.56',
+    '2.78',
+    '3.00',
+    '3.22',
+    '3.44',
+    '3.67',
+    '3.89',
+    '4.11',
+    '4.33',
+    '4.56',
+    '4.78',
+    '5.00',
+  ]"
+  :height="220"
+  x-label="R₀"
+  y-label="Frequency"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Logarithmic value axis
 
 Set `value-scale-type="log"` to switch the value axis to base-10 log
@@ -242,6 +385,80 @@ top still represents the sum.
   </template>
 </ComponentDemo>
 
+### Summary line overlay
+
+Layer a curve (KDE, rolling mean, target) on top of the bars with
+`summary-lines`. Each line scales to **its own value extent** —
+independent of the bar axis — so a probability-density curve in
+`[0, 0.02]` and a histogram in `[0, 500]` can share the same chart.
+
+<ComponentDemo>
+  <BarChart
+    :data="[3, 5, 8, 12, 18, 24, 31, 27, 22, 16, 11, 7, 4, 2]"
+    :categories="['2.11', '2.33', '2.56', '2.78', '3.00', '3.22', '3.44', '3.67', '3.89', '4.11', '4.33', '4.56', '4.78', '5.00']"
+    :summary-lines="[
+      {
+        data: [0.05, 0.10, 0.20, 0.40, 0.75, 1.10, 1.32, 1.20, 0.92, 0.60, 0.32, 0.16, 0.07, 0.03],
+        color: '#ef4444',
+        strokeWidth: 2,
+        legend: 'KDE',
+      },
+    ]"
+    :width="380"
+    :height="240"
+    x-label="R₀"
+    y-label="Frequency"
+  />
+
+<template #code>
+
+```vue
+<BarChart
+  :data="[3, 5, 8, 12, 18, 24, 31, 27, 22, 16, 11, 7, 4, 2]"
+  :categories="[
+    '2.11',
+    '2.33',
+    '2.56',
+    '2.78',
+    '3.00',
+    '3.22',
+    '3.44',
+    '3.67',
+    '3.89',
+    '4.11',
+    '4.33',
+    '4.56',
+    '4.78',
+    '5.00',
+  ]"
+  :summary-lines="[
+    {
+      data: [
+        0.05, 0.1, 0.2, 0.4, 0.75, 1.1, 1.32, 1.2, 0.92, 0.6, 0.32, 0.16, 0.07,
+        0.03,
+      ],
+      color: '#ef4444',
+      strokeWidth: 2,
+      legend: 'KDE',
+    },
+  ]"
+  :height="240"
+  x-label="R₀"
+  y-label="Frequency"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Each line accepts `color`, `strokeWidth`, `dashed`, `opacity`,
+`blendMode`, `dots`, and `dotRadius` for styling — same vocabulary as
+`LineChart` series (both extend `LineMarkStyle`). Override the line's
+extent with `valueMin` / `valueMax`. Pass `x: number[]` (in
+category-index space — `0` is the first category center, fractional
+values land between) to plot at custom positions; useful when the
+summary samples are denser or sparser than the histogram bins.
+
 ### Annotations
 
 Pin callouts to specific bars with `annotations`. `x` is the category
@@ -381,9 +598,10 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
 | `data` | `BarChartData` | No | — |
 | `y` | `BarChartData` | No | — |
 | `series` | `BarSeries[]` | No | — |
+| `summaryLines` | `BarSummaryLine[]` | No | — |
 | `categories` | `readonly (string \| Date)[]` | No | — |
 | `orientation` | `"vertical" \| "horizontal"` | No | `"vertical"` |
-| `layout` | `"grouped" \| "stacked"` | No | `"grouped"` |
+| `layout` | `"grouped" \| "stacked" \| "overlay"` | No | `"grouped"` |
 | `valueMin` | `number` | No | `0` |
 | `valueScaleType` | `"linear" \| "log"` | No | `"linear"` |
 | `valueTicks` | `number \| number[]` | No | — |

package/charts/BarChart/BarChart.vue

@@ -32,6 +32,8 @@ import {
   type ChartHoverPayload,
   type ChartTooltipBaseProps,
   type ChartTooltipValue,
+  type BlendMode,
+  type LineMarkStyle,
 } from "../_shared/index.js";
 
 export type BarChartData = ChartData;
@@ -42,6 +44,12 @@ export interface BarSeries {
   data?: BarChartData;
   color?: string;
   opacity?: number;
+  /**
+   * CSS `mix-blend-mode` applied to each bar in this series. Lets
+   * overlapping bars (e.g. `layout="overlay"`) combine their colors
+   * instead of one obscuring the other.
+   */
+  blendMode?: BlendMode;
   /** Label shown in the inline legend. */
   legend?: string;
   /**
@@ -56,6 +64,38 @@ export interface BarSeries {
   showInTooltip?: boolean;
 }
 
+/**
+ * A line overlay drawn on top of the bars — e.g. a KDE over a histogram,
+ * a rolling mean, or any other summary curve. Each line scales to its
+ * own value extent (independent of the bars), so a probability-density
+ * curve in `[0, 0.02]` and a count histogram in `[0, 500]` can coexist.
+ *
+ * Sample the curve densely on the input side — `summaryLines` connects
+ * points with straight segments (matching matplotlib / seaborn `kde=True`).
+ *
+ * Shares visual styling (`color`, `strokeWidth`, `dashed`, `opacity`,
+ * `blendMode`, `dots`, `dotRadius`, `legend`, `showInLegend`) with
+ * `LineChart`'s `Series` via `LineMarkStyle`.
+ */
+export interface BarSummaryLine extends LineMarkStyle {
+  /** Y values along the line. */
+  data: BarChartData;
+  /**
+   * X positions in category-index space (0 = first category center,
+   * `categories.length - 1` = last). Fractional values land between
+   * category centers. When omitted, points plot at successive category
+   * centers — one point per `data` entry.
+   */
+  x?: BarChartData;
+  /**
+   * Override the line's value-axis floor. When unset, defaults to the
+   * line's own min (clamped to 0 when all data is non-negative).
+   */
+  valueMin?: number;
+  /** Override the line's value-axis ceiling. Defaults to the line's own max. */
+  valueMax?: number;
+}
+
 interface BarChartProps extends ChartCommonProps {
   /** Single-series values. Equivalent to `y`. */
   data?: BarChartData;
@@ -63,6 +103,12 @@ interface BarChartProps extends ChartCommonProps {
   y?: BarChartData;
   /** Multi-series mode. Each series has its own values. */
   series?: BarSeries[];
+  /**
+   * Line overlays drawn on top of the bars (e.g. a KDE, a rolling mean,
+   * or any summary curve). Each line scales to its own value extent —
+   * unrelated to the bar value axis. See `BarSummaryLine`.
+   */
+  summaryLines?: BarSummaryLine[];
   /**
    * Category labels for the categorical axis. Length should match the
    * longest series. When omitted, indices (0, 1, 2, ...) are used.
@@ -73,8 +119,14 @@ interface BarChartProps extends ChartCommonProps {
   categories?: readonly (string | Date)[];
   /** "vertical" (default, aka column) draws upright bars; "horizontal" draws sideways. */
   orientation?: "vertical" | "horizontal";
-  /** "grouped" (default) places series side-by-side; "stacked" stacks them. */
-  layout?: "grouped" | "stacked";
+  /**
+   * "grouped" (default) places series side-by-side; "stacked" stacks
+   * them; "overlay" draws each series at full group width from the
+   * shared baseline, painting later series on top of earlier ones.
+   * In overlay mode set `opacity` per series, or order series so the
+   * tallest renders first, so bars behind remain visible.
+   */
+  layout?: "grouped" | "stacked" | "overlay";
   /** Force the value axis to start at this value or lower (default 0). */
   valueMin?: number;
   /**
@@ -148,6 +200,7 @@ type ResolvedSeries = {
   data: BarChartData;
   color?: string;
   opacity?: number;
+  blendMode?: BlendMode;
   legend?: string;
   showInLegend?: boolean;
   showInTooltip?: boolean;
@@ -158,6 +211,7 @@ function resolveSeries(s: BarSeries): ResolvedSeries {
     data: s.y ?? s.data ?? EMPTY_DATA,
     color: s.color,
     opacity: s.opacity,
+    blendMode: s.blendMode,
     legend: s.legend,
     showInLegend: s.showInLegend,
     showInTooltip: s.showInTooltip,
@@ -334,6 +388,7 @@ interface BarRect {
   h: number;
   color: string;
   opacity: number;
+  blendMode?: BlendMode;
   value: number;
   categoryIndex: number;
   seriesIndex: number;
@@ -351,6 +406,7 @@ function makeBar(
   span: number,
   color: string,
   opacity: number,
+  blendMode: BlendMode | undefined,
   value: number,
   categoryIndex: number,
   seriesIndex: number,
@@ -365,6 +421,7 @@ function makeBar(
       h: size,
       color,
       opacity,
+      blendMode,
       value,
       categoryIndex,
       seriesIndex,
@@ -377,6 +434,7 @@ function makeBar(
     h: span,
     color,
     opacity,
+    blendMode,
     value,
     categoryIndex,
     seriesIndex,
@@ -414,6 +472,7 @@ const bars = computed<BarRect[]>(() => {
             group,
             series.color ?? defaultColor(s),
             series.opacity ?? 1,
+            series.blendMode,
             raw,
             i,
             s,
@@ -422,6 +481,26 @@ const bars = computed<BarRect[]>(() => {
         if (raw >= 0) posCursor = top;
         else negCursor = top;
       }
+    } else if (props.layout === "overlay") {
+      for (let s = 0; s < k; s++) {
+        const series = seriesList[s];
+        const raw = Number(series.data[i] ?? NaN);
+        if (!isFinite(raw)) continue;
+        out.push(
+          makeBar(
+            baseline,
+            valuePixel(raw),
+            groupStart,
+            group,
+            series.color ?? defaultColor(s),
+            series.opacity ?? 1,
+            series.blendMode,
+            raw,
+            i,
+            s,
+          ),
+        );
+      }
     } else {
       for (let s = 0; s < k; s++) {
         const series = seriesList[s];
@@ -436,6 +515,7 @@ const bars = computed<BarRect[]>(() => {
             bw,
             series.color ?? defaultColor(s),
             series.opacity ?? 1,
+            series.blendMode,
             raw,
             i,
             s,
@@ -447,6 +527,138 @@ const bars = computed<BarRect[]>(() => {
   return out;
 });
 
+/**
+ * Per-line styling, resolved with defaults but without pixel work. Kept
+ * separate from `ResolvedSummaryLine` so the inline legend can depend on
+ * it without pulling in the chart's pixel layout (which depends on the
+ * legend row count — a circular reference otherwise).
+ */
+type StyledSummaryLine = {
+  data: BarChartData;
+  x?: BarChartData;
+  color: string;
+  strokeWidth: number;
+  dashed: boolean;
+  opacity: number;
+  blendMode?: BlendMode;
+  dots: boolean;
+  dotRadius: number;
+  extent: { min: number; max: number };
+  legend?: string;
+  showInLegend: boolean;
+};
+
+type ResolvedSummaryLine = StyledSummaryLine & {
+  pathD: string;
+  points: { x: number; y: number }[];
+};
+
+/** Compute the line's own value extent. */
+function computeLineExtent(line: BarSummaryLine): { min: number; max: number } {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const v of line.data) {
+    const n = Number(v);
+    if (!isFinite(n)) continue;
+    if (n < min) min = n;
+    if (n > max) max = n;
+  }
+  if (!isFinite(min)) {
+    min = 0;
+    max = 1;
+  }
+  if (line.valueMin !== undefined) {
+    min = line.valueMin;
+  } else if (min > 0) {
+    // Default to a 0 floor for all-positive data so the line shape
+    // reads as "rises from zero" rather than filling the full plot.
+    min = 0;
+  }
+  if (line.valueMax !== undefined) max = line.valueMax;
+  if (min === max) max = min + 1;
+  return { min, max };
+}
+
+/**
+ * Project a single line point (x in category-index space, y in the
+ * line's own value space) to pixels. Orientation flips which axis is
+ * categorical vs value.
+ */
+function projectLinePoint(
+  x: number,
+  y: number,
+  extent: { min: number; max: number },
+): { x: number; y: number } {
+  const base = isVertical.value ? padding.value.left : padding.value.top;
+  const categoricalPx = base + (x + 0.5) * slotSize.value;
+  const span = extent.max - extent.min || 1;
+  const frac = (y - extent.min) / span;
+  if (isVertical.value) {
+    return {
+      x: categoricalPx,
+      y: padding.value.top + innerH.value - frac * innerH.value,
+    };
+  }
+  return {
+    x: padding.value.left + frac * innerW.value,
+    y: categoricalPx,
+  };
+}
+
+const summaryLinesStyled = computed<StyledSummaryLine[]>(() => {
+  const lines = props.summaryLines;
+  if (!lines || lines.length === 0) return [];
+  return lines.map((line, i): StyledSummaryLine => {
+    return {
+      data: line.data ?? EMPTY_DATA,
+      x: line.x,
+      color: line.color ?? defaultLineColor(i),
+      strokeWidth: line.strokeWidth ?? 2,
+      dashed: line.dashed ?? false,
+      opacity: line.opacity ?? 1,
+      blendMode: line.blendMode,
+      dots: line.dots ?? false,
+      dotRadius: line.dotRadius ?? (line.strokeWidth ?? 2) + 1,
+      extent: computeLineExtent(line),
+      legend: line.legend,
+      showInLegend: line.showInLegend !== false,
+    };
+  });
+});
+
+const summaryLinesResolved = computed<ResolvedSummaryLine[]>(() => {
+  if (slotSize.value === 0) return [];
+  return summaryLinesStyled.value.map((line): ResolvedSummaryLine => {
+    const points: { x: number; y: number }[] = [];
+    let d = "";
+    let inSeg = false;
+    for (let j = 0; j < line.data.length; j++) {
+      const yv = Number(line.data[j]);
+      const xv = line.x ? Number(line.x[j]) : j;
+      if (!isFinite(yv) || !isFinite(xv)) {
+        inSeg = false;
+        continue;
+      }
+      const p = projectLinePoint(xv, yv, line.extent);
+      points.push(p);
+      d += inSeg ? `L${p.x},${p.y}` : `M${p.x},${p.y}`;
+      inSeg = true;
+    }
+    return { ...line, pathD: d, points };
+  });
+});
+
+const DEFAULT_LINE_COLORS = [
+  "var(--color-fg-1, #111)",
+  "var(--color-danger, #ef4444)",
+  "var(--color-success, #10b981)",
+  "var(--color-info, #6366f1)",
+];
+
+function defaultLineColor(i: number): string {
+  return DEFAULT_LINE_COLORS[i % DEFAULT_LINE_COLORS.length];
+}
+
 const DEFAULT_COLORS = [
   "var(--color-primary, #3b82f6)",
   "var(--color-accent, #f59e0b)",
@@ -547,10 +759,29 @@ const categoryTickItems = computed<CategoryTickItem[]>(() => {
   const out: CategoryTickItem[] = [];
   const fmt = (label: string, i: number) =>
     props.categoryFormat ? props.categoryFormat(label, i) : label;
+  const formatted = new Array<string>(n);
+  let maxLen = 0;
   for (let i = 0; i < n; i++) {
+    formatted[i] = fmt(categoryLabels.value[i], i);
+    if (formatted[i].length > maxLen) maxLen = formatted[i].length;
+  }
+  // Skip labels when slots are too narrow (or short) to fit them
+  // without overlap. Vertical orientation measures horizontal label
+  // width (≈ chars × fontSize × 0.6); horizontal orientation just
+  // measures stacked line height (≈ fontSize × 1.2).
+  const fontSize = props.tickLabelStyle?.fontSize ?? TICK_LABEL_FONT_SIZE;
+  const minGap = 8;
+  const needPerLabel = isVertical.value
+    ? maxLen * fontSize * 0.6 + minGap
+    : fontSize * 1.2 + minGap;
+  const stride =
+    slotSize.value > 0
+      ? Math.max(1, Math.ceil(needPerLabel / slotSize.value))
+      : 1;
+  for (let i = 0; i < n; i += stride) {
     const center = slotStart(i) + slotSize.value / 2;
     out.push({
-      label: fmt(categoryLabels.value[i], i),
+      label: formatted[i],
       pos: center,
       anchor: "middle",
     });
@@ -561,13 +792,28 @@ const categoryTickItems = computed<CategoryTickItem[]>(() => {
 interface InlineLegendItem {
   label: string;
   color: string;
+  kind: "bar" | "line";
+  dashed?: boolean;
 }
 
 const inlineLegendItems = computed<InlineLegendItem[]>(() => {
   const items: InlineLegendItem[] = [];
   allSeries.value.forEach((s, i) => {
     if (!s.legend || s.showInLegend === false) return;
-    items.push({ label: s.legend, color: s.color ?? defaultColor(i) });
+    items.push({
+      label: s.legend,
+      color: s.color ?? defaultColor(i),
+      kind: "bar",
+    });
+  });
+  summaryLinesStyled.value.forEach((line) => {
+    if (!line.legend || !line.showInLegend) return;
+    items.push({
+      label: line.legend,
+      color: line.color,
+      kind: "line",
+      dashed: line.dashed,
+    });
   });
   return items;
 });
@@ -805,12 +1051,23 @@ const positionedLegendItems = computed(() => {
       <g v-if="positionedLegendItems.length > 0">
         <template v-for="(item, i) in positionedLegendItems" :key="'ileg' + i">
           <rect
+            v-if="item.kind === 'bar'"
             :x="item.x"
             :y="item.y - 5"
             width="12"
             height="10"
             :fill="item.color"
           />
+          <line
+            v-else
+            :x1="item.x"
+            :y1="item.y"
+            :x2="item.x + 12"
+            :y2="item.y"
+            :stroke="item.color"
+            stroke-width="2"
+            :stroke-dasharray="item.dashed ? '4 2' : undefined"
+          />
           <text
             :x="item.x + 18"
             :y="item.y + 4"
@@ -969,7 +1226,38 @@ const positionedLegendItems = computed(() => {
         :height="bar.h"
         :fill="bar.color"
         :fill-opacity="bar.opacity"
+        :style="bar.blendMode ? { mixBlendMode: bar.blendMode } : undefined"
       />
+      <!-- summary lines (drawn above bars, below annotations) -->
+      <template v-for="(line, i) in summaryLinesResolved" :key="'sl' + i">
+        <path
+          v-if="line.pathD"
+          data-testid="summary-line"
+          :d="line.pathD"
+          fill="none"
+          :stroke="line.color"
+          :stroke-width="line.strokeWidth"
+          :stroke-opacity="line.opacity"
+          :stroke-dasharray="line.dashed ? '6 3' : undefined"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          :style="line.blendMode ? { mixBlendMode: line.blendMode } : undefined"
+        />
+        <template v-if="line.dots">
+          <circle
+            v-for="(pt, j) in line.points"
+            :key="'sld' + i + '-' + j"
+            :cx="pt.x"
+            :cy="pt.y"
+            :r="line.dotRadius"
+            :fill="line.color"
+            :fill-opacity="line.opacity"
+            :style="
+              line.blendMode ? { mixBlendMode: line.blendMode } : undefined
+            "
+          />
+        </template>
+      </template>
       <!-- Tooltip: interaction overlay -->
       <rect
         v-if="hasTooltipSlot"

package/charts/LineChart/LineChart.md

@@ -478,6 +478,66 @@ busy background — the outline keeps each series visually distinct.
   </template>
 </ComponentDemo>
 
+### Blend mode
+
+Set `blendMode` on a `Series` to apply a CSS `mix-blend-mode` to that
+series' line (and dots, if enabled). Useful when two thick or
+high-contrast lines overlap — `"multiply"` darkens the crossing point
+on light backgrounds, `"screen"` lightens on dark, `"difference"`
+inverts. The white `outline`, if any, is unaffected.
+
+<ComponentDemo>
+  <LineChart
+    :series="[
+      {
+        data: Array.from({ length: 30 }, (_, t) => 20 + 15 * Math.sin(t / 4)),
+        color: '#ef4444',
+        strokeWidth: 3,
+        blendMode: 'multiply',
+        legend: 'Strain A',
+      },
+      {
+        data: Array.from({ length: 30 }, (_, t) => 20 + 15 * Math.cos(t / 4)),
+        color: '#3b82f6',
+        strokeWidth: 3,
+        blendMode: 'multiply',
+        legend: 'Strain B',
+      },
+    ]"
+    :height="240"
+    x-label="Day"
+    y-label="Incidence"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :series="[
+    {
+      data: strainA,
+      color: '#ef4444',
+      strokeWidth: 3,
+      blendMode: 'multiply',
+      legend: 'Strain A',
+    },
+    {
+      data: strainB,
+      color: '#3b82f6',
+      strokeWidth: 3,
+      blendMode: 'multiply',
+      legend: 'Strain B',
+    },
+  ]"
+  :height="240"
+  x-label="Day"
+  y-label="Incidence"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Grid lines
 
 <ComponentDemo>

package/charts/LineChart/LineChart.vue

@@ -35,6 +35,8 @@ import {
   type ChartHoverPayload,
   type ChartTooltipBaseProps,
   type ChartTooltipValue,
+  type BlendMode,
+  type LineMarkStyle,
 } from "../_shared/index.js";
 
 /**
@@ -52,7 +54,13 @@ export type LineChartData = ChartData;
  */
 export type LineChartXInput = LineChartData | readonly (string | Date)[];
 
-export interface Series {
+/**
+ * A single line/dot series. Inherits visual styling
+ * (`color`, `strokeWidth`, `dashed`, `opacity`, `blendMode`, `dots`,
+ * `dotRadius`, `legend`, `showInLegend`) from `LineMarkStyle`, shared
+ * with `BarChart`'s `BarSummaryLine`.
+ */
+export interface Series extends LineMarkStyle {
   /**
    * Y-values. One of `y` or `data` must be supplied; `y` wins if both
    * are set.
@@ -67,12 +75,11 @@ export interface Series {
    * date strings or `Date` objects to enable date-axis mode.
    */
   x?: LineChartXInput;
-  color?: string;
-  dashed?: boolean;
-  strokeWidth?: number;
-  opacity?: number;
+  /** Overrides `opacity` for the line stroke only. */
   lineOpacity?: number;
+  /** Overrides `opacity` for the dots only. */
   dotOpacity?: number;
+  /** Draw the line. Default true. */
   line?: boolean;
   /**
    * Draw a page-colored stroke behind the line so it stays visually
@@ -80,17 +87,8 @@ export interface Series {
    * effect when `line` is `false`.
    */
   outline?: boolean;
-  dots?: boolean;
-  dotRadius?: number;
   dotFill?: string;
   dotStroke?: string;
-  /** Label shown in the inline legend */
-  legend?: string;
-  /**
-   * Whether this series appears in the inline legend. Defaults to true.
-   * Has no effect when `legend` is unset (no legend entry to begin with).
-   */
-  showInLegend?: boolean;
   /**
    * Whether this series contributes a value to the tooltip and shows a
    * hover dot. Defaults to true. The series line/dots are still drawn.
@@ -1208,6 +1206,7 @@ const positionedLegendItems = computed(() => {
           :stroke-width="s.strokeWidth ?? 1.5"
           :stroke-opacity="s.lineOpacity ?? s.opacity ?? lineOpacity"
           :stroke-dasharray="s.dashed ? '6 3' : undefined"
+          :style="s.blendMode ? { mixBlendMode: s.blendMode } : undefined"
         />
         <template v-if="s.dots">
           <circle
@@ -1219,6 +1218,7 @@ const positionedLegendItems = computed(() => {
             :fill="s.dotFill ?? s.color ?? 'currentColor'"
             :fill-opacity="s.dotOpacity ?? s.opacity ?? lineOpacity"
             :stroke="s.dotStroke ?? 'none'"
+            :style="s.blendMode ? { mixBlendMode: s.blendMode } : undefined"
           />
         </template>
       </template>

package/charts/_shared/chartProps.ts

@@ -35,6 +35,59 @@ export interface LabelStyle {
   fontWeight?: number | string;
 }
 
+/**
+ * CSS `mix-blend-mode` values usable on chart series. Drives how a
+ * series' pixels combine with what's painted behind them. Useful for
+ * overlapping series (e.g. `"multiply"` darkens light fills where bars
+ * overlap; `"screen"` lightens dark fills).
+ */
+export type BlendMode =
+  | "normal"
+  | "multiply"
+  | "screen"
+  | "overlay"
+  | "darken"
+  | "lighten"
+  | "color-dodge"
+  | "color-burn"
+  | "hard-light"
+  | "soft-light"
+  | "difference"
+  | "exclusion"
+  | "hue"
+  | "saturation"
+  | "color"
+  | "luminosity";
+
+/**
+ * Visual styling shared by anything drawn as "a stroked line with
+ * optional dots" — used by `LineChart`'s `Series` and `BarChart`'s
+ * `BarSummaryLine`. Chart-specific data (y/x arrays, scaling overrides,
+ * tooltip/outline behavior) lives on the extending type.
+ */
+export interface LineMarkStyle {
+  color?: string;
+  strokeWidth?: number;
+  dashed?: boolean;
+  opacity?: number;
+  /**
+   * CSS `mix-blend-mode` applied to the line and dots. Lets overlapping
+   * marks combine their colors instead of one obscuring the other.
+   */
+  blendMode?: BlendMode;
+  /** Draw a dot at each sample point. Default false. */
+  dots?: boolean;
+  /** Radius of each dot in pixels. */
+  dotRadius?: number;
+  /** Label shown in the inline legend. */
+  legend?: string;
+  /**
+   * Whether this mark appears in the inline legend. Defaults to true.
+   * Has no effect when `legend` is unset.
+   */
+  showInLegend?: boolean;
+}
+
 /**
  * Props common to every cartesian chart component. Anything specific to
  * the chart type (series shape, layout, value-axis details) lives on the

package/charts/_shared/index.ts

@@ -51,6 +51,8 @@ export type {
   ChartTooltipBaseProps,
   TitleStyle,
   LabelStyle,
+  BlendMode,
+  LineMarkStyle,
 } from "./chartProps.js";
 export {
   parseDate,

package/charts/index.ts

@@ -11,6 +11,7 @@ export {
   default as BarChart,
   type BarChartData,
   type BarSeries,
+  type BarSummaryLine,
 } from "./BarChart/BarChart.vue";
 export {
   default as ChoroplethMap,
@@ -33,3 +34,4 @@ export {
   type ColumnWidth,
 } from "./DataTable/DataTable.vue";
 export type { ChartAnnotation } from "./_shared/annotations.js";
+export type { BlendMode, LineMarkStyle } from "./_shared/chartProps.js";

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.13",
+  "version": "0.4.15",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [
@@ -149,6 +149,7 @@
           "categorical",
           "grouped",
           "stacked",
+          "overlay",
           "vertical",
           "horizontal",
           "svg"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/docs",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "LLM-friendly component and chart documentation for cfasim-ui",
   "license": "Apache-2.0",
   "repository": {