@cfasim-ui/docs 0.4.14 → 0.4.16

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>
@@ -290,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
@@ -424,14 +593,16 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
 | `csv` | `string \| (() =&gt; string)` | No | — |
 | `filename` | `string` | No | — |
 | `downloadLink` | `boolean \| string` | No | — |
+| `downloadButton` | `boolean \| string` | No | — |
 | `annotations` | `readonly ChartAnnotation[]` | No | — |
 | `chartPadding` | `ChartPadding` | No | — |
 | `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)",
@@ -580,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;
 });
@@ -652,6 +879,8 @@ const {
   menuItems,
   downloadLinkText,
   csvHref,
+  downloadButtonText,
+  triggerCsvDownload,
   menuFilename,
   isFullscreen,
 } = useChartFoundation({
@@ -667,6 +896,7 @@ const {
   tooltipClamp: () => props.tooltipClamp,
   filename: () => props.filename,
   downloadLink: () => props.downloadLink,
+  downloadButton: () => props.downloadButton,
   chartPadding: () => props.chartPadding,
   inlineLegendLabels: () => inlineLegendLabels.value,
   hasTooltipSlot: () => hasTooltipSlot.value,
@@ -824,12 +1054,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"
@@ -988,7 +1229,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"
@@ -1051,6 +1323,14 @@ const positionedLegendItems = computed(() => {
     >
       {{ downloadLinkText }}
     </a>
+    <button
+      v-if="downloadButtonText"
+      type="button"
+      class="bar-chart-download-button"
+      @click="triggerCsvDownload"
+    >
+      {{ downloadButtonText }}
+    </button>
   </div>
 </template>
 
@@ -1086,3 +1366,27 @@ const positionedLegendItems = computed(() => {
   flex-shrink: 0;
 }
 </style>
+
+<style>
+.bar-chart-download-button {
+  display: inline-flex;
+  align-items: center;
+  margin-top: 0.5em;
+  padding: 0.5em 1em;
+  border: 1px solid var(--color-border);
+  border-radius: 0.25em;
+  background: var(--color-bg-0, #fff);
+  color: var(--color-text);
+  font-size: var(--font-size-sm);
+  cursor: pointer;
+}
+
+.bar-chart-download-button:hover {
+  background: var(--color-bg-1, rgba(0, 0, 0, 0.05));
+}
+
+.bar-chart-download-button:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+</style>

package/charts/DataTable/DataTable.md

@@ -157,9 +157,8 @@ the available space equally.
 
 A `⋯` menu appears in the top-right corner of every table with a
 **Download** item that exports the data as CSV. Use `download-menu-link`
-to customize the menu item label, `filename` to control the downloaded
-filename, and `csv` to supply custom CSV content. Pass `:menu="false"`
-to hide the menu entirely.
+to customize the menu item label and `filename` to control the
+downloaded filename. Pass `:menu="false"` to hide the menu entirely.
 
 <ComponentDemo>
   <DataTable
@@ -184,6 +183,115 @@ to hide the menu entirely.
   </template>
 </ComponentDemo>
 
+### Custom CSV download
+
+By default, the Download menu item exports the displayed table as CSV.
+Use the `csv` prop to supply your own content — for example, to include
+ISO dates, extra columns that aren't in the table, or values formatted
+differently from the on-screen rendering. Accepts a raw string or a
+function returning one (called lazily on click).
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], cases: [1, 21, 56, 101, 141] }"
+    filename="sir-cases"
+    :csv="'date,day,cases\n2024-01-01,0,1\n2024-01-02,1,21\n2024-01-03,2,56\n2024-01-04,3,101\n2024-01-05,4,141'"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    cases: [1, 21, 56, 101, 141],
+  }"
+  filename="sir-cases"
+  :csv="`date,day,cases
+2024-01-01,0,1
+2024-01-02,1,21
+2024-01-03,2,56
+2024-01-04,3,101
+2024-01-05,4,141`"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Download button
+
+Pass `download-button` to render a visible, labeled button beneath the
+table instead of exposing the download only via the top-right menu. The
+button uses `download-menu-link` as its label, and the menu's Download
+item is suppressed so the action isn't duplicated. The button has the
+class `data-table-download-button` and its styles are unscoped, so it
+can be targeted directly from custom CSS without specificity battles.
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], cases: [1, 21, 56, 101, 141] }"
+    filename="sir-cases"
+    download-menu-link="Download CSV"
+    download-button
+    :csv="'date,day,cases\n2024-01-01,0,1\n2024-01-02,1,21\n2024-01-03,2,56\n2024-01-04,3,101\n2024-01-05,4,141'"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    cases: [1, 21, 56, 101, 141],
+  }"
+  filename="sir-cases"
+  download-menu-link="Download CSV"
+  download-button
+  :csv="`date,day,cases
+2024-01-01,0,1
+2024-01-02,1,21
+2024-01-03,2,56
+2024-01-04,3,101
+2024-01-05,4,141`"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Download link
+
+Pass `download-link` to render a plain text link beneath the table
+instead of (or alongside) the menu. It's a real `<a href download>` —
+right-click → Save As works. Pass `true` for the default "Download data
+(CSV)" label, or a string to customize. The menu's Download item is
+suppressed when this is set. If both `download-link` and
+`download-button` are set, the button wins.
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], cases: [1, 21, 56, 101, 141] }"
+    filename="sir-cases"
+    download-link
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    cases: [1, 21, 56, 101, 141],
+  }"
+  filename="sir-cases"
+  download-link
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ## Props
 
 | Prop | Type | Required | Default |
@@ -195,6 +303,8 @@ to hide the menu entirely.
 | `csv` | `string \| (() =&gt; string)` | No | — |
 | `filename` | `string` | No | — |
 | `downloadMenuLink` | `string` | No | `"Download"` |
+| `downloadButton` | `boolean` | No | `false` |
+| `downloadLink` | `boolean \| string` | No | — |
 | `fullWidth` | `boolean` | No | `false` |
 
 

package/charts/DataTable/DataTable.vue

@@ -54,14 +54,34 @@ const props = withDefaults(
     /** Filename (without extension) for downloaded CSV files. */
     filename?: string;
     /**
-     * Label for the Download item in the table's top-right menu.
-     * Defaults to "Download".
+     * Label for the Download item in the table's top-right menu, and for
+     * the button rendered when `downloadButton` is true. Defaults to
+     * "Download".
      */
     downloadMenuLink?: string;
+    /**
+     * Render a visible "Download" button beneath the table instead of
+     * exposing the action only via the top-right menu. When enabled, the
+     * menu's Download item is suppressed to avoid duplicate controls.
+     */
+    downloadButton?: boolean;
+    /**
+     * Render a plain text link beneath the table for downloading CSV.
+     * Pass `true` for the default "Download data (CSV)" label, or a
+     * string to customize. When set, the menu's Download item is
+     * suppressed. Mutually exclusive with `downloadButton`; if both are
+     * set, `downloadButton` wins.
+     */
+    downloadLink?: boolean | string;
     /** Stretch the table to fill its container's width. */
     fullWidth?: boolean;
   }>(),
-  { menu: true, fullWidth: false, downloadMenuLink: "Download" },
+  {
+    menu: true,
+    fullWidth: false,
+    downloadMenuLink: "Download",
+    downloadButton: false,
+  },
 );
 
 function columnLabel(name: string): string {
@@ -165,14 +185,30 @@ function toCsv(): string {
   return lines.join("\n");
 }
 
-const menuItems = computed<ChartMenuItem[]>(() => [
-  {
-    label: props.downloadMenuLink,
-    action: () => downloadCsv(toCsv(), menuFilename()),
-  },
-]);
+function triggerDownload() {
+  downloadCsv(toCsv(), menuFilename());
+}
+
+const menuItems = computed<ChartMenuItem[]>(() => {
+  if (props.downloadButton || props.downloadLink) return [];
+  return [{ label: props.downloadMenuLink, action: triggerDownload }];
+});
+
+const downloadLinkText = computed<string | null>(() => {
+  if (props.downloadButton) return null;
+  const v = props.downloadLink;
+  if (!v) return null;
+  return typeof v === "string" ? v : "Download data (CSV)";
+});
+
+const csvHref = computed<string | null>(() => {
+  if (!downloadLinkText.value) return null;
+  return `data:text/csv;charset=utf-8,${encodeURIComponent(toCsv())}`;
+});
 
-const showMenu = computed(() => Boolean(props.menu));
+const showMenu = computed(
+  () => Boolean(props.menu) && menuItems.value.length > 0,
+);
 </script>
 
 <template>
@@ -215,6 +251,22 @@ const showMenu = computed(() => Boolean(props.menu));
         </tbody>
       </table>
     </div>
+    <button
+      v-if="downloadButton"
+      type="button"
+      class="data-table-download-button"
+      @click="triggerDownload"
+    >
+      {{ downloadMenuLink }}
+    </button>
+    <a
+      v-else-if="downloadLinkText"
+      class="data-table-download-link"
+      :href="csvHref!"
+      :download="`${menuFilename()}.csv`"
+    >
+      {{ downloadLinkText }}
+    </a>
   </div>
 </template>
 
@@ -288,3 +340,34 @@ const showMenu = computed(() => Boolean(props.menu));
   padding-right: 2.5em;
 }
 </style>
+
+<style>
+.data-table-download-button {
+  display: inline-flex;
+  align-items: center;
+  margin-top: 0.75em;
+  padding: 0.5em 1em;
+  border: 1px solid var(--color-border);
+  border-radius: 0.25em;
+  background: var(--color-bg-0, #fff);
+  color: var(--color-text);
+  font-size: var(--font-size-sm);
+  cursor: pointer;
+}
+
+.data-table-download-button:hover {
+  background: var(--color-bg-1, rgba(0, 0, 0, 0.05));
+}
+
+.data-table-download-button:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+
+.data-table-download-link {
+  display: block;
+  text-align: right;
+  font-size: var(--font-size-sm);
+  margin-top: 0.25em;
+}
+</style>

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>
@@ -881,7 +941,10 @@ dates, categorical labels, or extra columns that aren't plotted). Use
 `filename` to control the download filename (shared by SVG, PNG and CSV).
 
 Pass `download-link` to also render a plain text link below the chart — set
-it to `true` for the default label, or pass a string to customize it.
+it to `true` for the default label, or pass a string to customize it. Use
+`download-button` instead to render a styled `<button>` (with the class
+`line-chart-download-button`, available for custom CSS) in place of the
+link.
 
 <ComponentDemo>
   <LineChart
@@ -944,6 +1007,7 @@ until the user clicks Download:
 | `csv` | `string \| (() =&gt; string)` | No | — |
 | `filename` | `string` | No | — |
 | `downloadLink` | `boolean \| string` | No | — |
+| `downloadButton` | `boolean \| string` | No | — |
 | `annotations` | `readonly ChartAnnotation[]` | No | — |
 | `chartPadding` | `ChartPadding` | No | — |
 | `y` | `LineChartData` | No | — |

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.
@@ -931,6 +929,8 @@ const {
   menuItems,
   downloadLinkText,
   csvHref,
+  downloadButtonText,
+  triggerCsvDownload,
   menuFilename,
   isFullscreen,
 } = useChartFoundation({
@@ -946,6 +946,7 @@ const {
   tooltipClamp: () => props.tooltipClamp,
   filename: () => props.filename,
   downloadLink: () => props.downloadLink,
+  downloadButton: () => props.downloadButton,
   chartPadding: () => props.chartPadding,
   inlineLegendLabels: () => inlineLegendLabels.value,
   hasTooltipSlot: () => hasTooltipSlot.value,
@@ -1208,6 +1209,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 +1221,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>
@@ -1403,6 +1406,14 @@ const positionedLegendItems = computed(() => {
     >
       {{ downloadLinkText }}
     </a>
+    <button
+      v-if="downloadButtonText"
+      type="button"
+      class="line-chart-download-button"
+      @click="triggerCsvDownload"
+    >
+      {{ downloadButtonText }}
+    </button>
   </div>
 </template>
 
@@ -1438,3 +1449,27 @@ const positionedLegendItems = computed(() => {
   flex-shrink: 0;
 }
 </style>
+
+<style>
+.line-chart-download-button {
+  display: inline-flex;
+  align-items: center;
+  margin-top: 0.5em;
+  padding: 0.5em 1em;
+  border: 1px solid var(--color-border);
+  border-radius: 0.25em;
+  background: var(--color-bg-0, #fff);
+  color: var(--color-text);
+  font-size: var(--font-size-sm);
+  cursor: pointer;
+}
+
+.line-chart-download-button:hover {
+  background: var(--color-bg-1, rgba(0, 0, 0, 0.05));
+}
+
+.line-chart-download-button:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+</style>

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
@@ -88,6 +141,13 @@ export interface ChartCommonProps {
    * for the default label or a string to customize.
    */
   downloadLink?: boolean | string;
+  /**
+   * Show a `<button>` below the chart to download CSV. Pass `true` for
+   * the default label or a string to customize. When set, the CSV menu
+   * item is suppressed. Mutually exclusive with `downloadLink`; if both
+   * are set, `downloadButton` wins.
+   */
+  downloadButton?: boolean | string;
   /** Annotations rendered as the top layer of the chart. */
   annotations?: readonly ChartAnnotation[];
   /**

package/charts/_shared/index.ts

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

package/charts/_shared/useChartFoundation.ts

@@ -25,6 +25,7 @@ export interface ChartFoundationOptions {
   tooltipClamp: () => TooltipClamp | undefined;
   filename: () => string | undefined;
   downloadLink: () => boolean | string | undefined;
+  downloadButton: () => boolean | string | undefined;
   chartPadding: () => ChartPadding | undefined;
   // Chart-specific hooks that the composable can't infer.
   /**
@@ -61,6 +62,8 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     items: menuItems,
     downloadLinkText,
     csvHref,
+    downloadButtonText,
+    triggerCsvDownload,
     resolvedFilename: menuFilename,
     isFullscreen,
   } = useChartMenu({
@@ -68,6 +71,7 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     legacyMenuLabel: opts.menu,
     getCsv: opts.getCsv,
     downloadLink: opts.downloadLink,
+    downloadButton: opts.downloadButton,
     fullscreen: true,
   });
 
@@ -130,6 +134,8 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
     menuItems,
     downloadLinkText,
     csvHref,
+    downloadButtonText,
+    triggerCsvDownload,
     menuFilename,
     isFullscreen,
     measuredHeight,

package/charts/_shared/useChartMenu.ts

@@ -11,6 +11,8 @@ export interface ChartMenuOptions {
   getCsv: () => string;
   /** Whether a separate download link is rendered (and the CSV menu item should be hidden). */
   downloadLink: () => boolean | string | undefined;
+  /** Whether a separate download button is rendered (and the CSV menu item should be hidden). */
+  downloadButton?: () => boolean | string | undefined;
   /**
    * When true, prepends an Expand/Collapse menu item that toggles the
    * chart into a full-window view. The consumer is responsible for
@@ -56,7 +58,8 @@ export function useChartMenu(opts: ChartMenuOptions) {
         },
       },
     );
-    if (!opts.downloadLink()) {
+    const buttonOn = opts.downloadButton?.();
+    if (!opts.downloadLink() && !buttonOn) {
       out.push({
         label: "Download CSV",
         action: () => downloadCsv(opts.getCsv(), fname),
@@ -66,21 +69,35 @@ export function useChartMenu(opts: ChartMenuOptions) {
   });
 
   const downloadLinkText = computed<string | null>(() => {
+    if (opts.downloadButton?.()) return null;
     const v = opts.downloadLink();
     if (!v) return null;
     return typeof v === "string" ? v : "Download data (CSV)";
   });
 
   const csvHref = computed<string | null>(() => {
+    if (opts.downloadButton?.()) return null;
     if (!opts.downloadLink()) return null;
     return `data:text/csv;charset=utf-8,${encodeURIComponent(opts.getCsv())}`;
   });
 
+  const downloadButtonText = computed<string | null>(() => {
+    const v = opts.downloadButton?.();
+    if (!v) return null;
+    return typeof v === "string" ? v : "Download data (CSV)";
+  });
+
+  function triggerCsvDownload() {
+    downloadCsv(opts.getCsv(), resolvedFilename());
+  }
+
   return {
     svgRef: svgRef as Ref<SVGSVGElement | null>,
     items,
     downloadLinkText,
     csvHref,
+    downloadButtonText,
+    triggerCsvDownload,
     resolvedFilename,
     isFullscreen: fullscreen?.isFullscreen ?? ref(false),
   };

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.14",
+  "version": "0.4.16",
   "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.14",
+  "version": "0.4.16",
   "description": "LLM-friendly component and chart documentation for cfasim-ui",
   "license": "Apache-2.0",
   "repository": {