@cfasim-ui/docs 0.4.6 → 0.4.8

package/charts/BarChart/BarChart.md

@@ -160,6 +160,40 @@ Use `value-tick-format` to format the value-axis labels. `tooltip-value-format`
   </template>
 </ComponentDemo>
 
+### Logarithmic value axis
+
+Set `value-scale-type="log"` to switch the value axis to base-10 log
+scaling. Non-positive values collapse to the axis floor, and
+`valueMin <= 0` is ignored. With `layout="stacked"`, individual segment
+sizes are no longer proportional to their raw values, but the cumulative
+top still represents the sum.
+
+<ComponentDemo>
+  <BarChart
+    :data="[3, 24, 180, 1450, 9800]"
+    :categories="['Wk1', 'Wk2', 'Wk3', 'Wk4', 'Wk5']"
+    value-scale-type="log"
+    :height="220"
+    x-label="Week"
+    y-label="Cases"
+  />
+
+<template #code>
+
+```vue
+<BarChart
+  :data="[3, 24, 180, 1450, 9800]"
+  :categories="['Wk1', 'Wk2', 'Wk3', 'Wk4', 'Wk5']"
+  value-scale-type="log"
+  :height="220"
+  x-label="Week"
+  y-label="Cases"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Annotations
 
 Pin callouts to specific bars with `annotations`. `x` is the category
@@ -286,7 +320,7 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
 | `tooltipData` | `ArrayLike&lt;unknown&gt;` | No | — |
 | `tooltipTrigger` | `"hover" \| "click"` | No | — |
 | `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
-| `tooltipValueFormat` | `(value: number) =&gt; string` | No | — |
+| `tooltipValueFormat` | `NumberFormat` | No | — |
 | `csv` | `string \| (() =&gt; string)` | No | — |
 | `filename` | `string` | No | — |
 | `downloadLink` | `boolean \| string` | No | — |
@@ -299,8 +333,9 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
 | `orientation` | `"vertical" \| "horizontal"` | No | `"vertical"` |
 | `layout` | `"grouped" \| "stacked"` | No | `"grouped"` |
 | `valueMin` | `number` | No | `0` |
+| `valueScaleType` | `"linear" \| "log"` | No | `"linear"` |
 | `valueTicks` | `number \| number[]` | No | — |
-| `valueTickFormat` | `(value: number) =&gt; string` | No | — |
+| `valueTickFormat` | `NumberFormat` | No | — |
 | `categoryFormat` | `(label: string, index: number) =&gt; string` | No | — |
 | `barPadding` | `number` | No | `0.2` |
 | `groupGap` | `number` | No | `1` |

package/charts/BarChart/BarChart.vue

@@ -1,10 +1,14 @@
 <script setup lang="ts">
 import { computed } from "vue";
+import { formatNumber, type NumberFormat } from "@cfasim-ui/shared";
 import ChartMenu from "../ChartMenu/ChartMenu.vue";
 import {
   snap,
   formatTick,
   computeTickValues,
+  computeLogTickValues,
+  scaleFraction,
+  clampExtentForScale,
   categoricalToCsv,
   useChartFoundation,
   makeTooltipValueFormatter,
@@ -45,13 +49,26 @@ interface BarChartProps extends ChartCommonProps {
   layout?: "grouped" | "stacked";
   /** Force the value axis to start at this value or lower (default 0). */
   valueMin?: number;
+  /**
+   * Scale type for the value axis. `"linear"` (default) maps values
+   * directly to pixels; `"log"` uses a base-10 log mapping. On a log
+   * axis, non-positive values collapse to the visible minimum, and
+   * `valueMin <= 0` is ignored. Stacked layout + log produces a
+   * cumulative axis but individual segment sizes are no longer
+   * proportional to their values.
+   */
+  valueScaleType?: "linear" | "log";
   /**
    * Tick placement on the value axis (numeric). Number = interval,
    * array = explicit values. When omitted, ticks are chosen automatically.
    */
   valueTicks?: number | number[];
-  /** Formatter for value-axis tick labels. */
-  valueTickFormat?: (value: number) => string;
+  /**
+   * Formatter for value-axis tick labels. Accepts a preset name, a
+   * printf-style format string, or a function. See `formatNumber` in
+   * `@cfasim-ui/shared`.
+   */
+  valueTickFormat?: NumberFormat;
   /** Formatter for category-axis labels. Receives the resolved category string. */
   categoryFormat?: (label: string, index: number) => string;
   /**
@@ -76,6 +93,7 @@ const props = withDefaults(defineProps<BarChartProps>(), {
   menu: true,
   tooltipClamp: "chart",
   valueGrid: true,
+  valueScaleType: "linear",
 });
 
 const emit = defineEmits<{
@@ -137,6 +155,10 @@ const isVertical = computed(() => props.orientation === "vertical");
 const valueExtent = computed(() => {
   let min = Infinity;
   let max = -Infinity;
+  let smallestPositive = Infinity;
+  const visitPositive = (v: number) => {
+    if (v > 0 && v < smallestPositive) smallestPositive = v;
+  };
   if (props.layout === "stacked") {
     const n = categoryCount.value;
     for (let i = 0; i < n; i++) {
@@ -146,6 +168,7 @@ const valueExtent = computed(() => {
         if (i >= s.data.length) continue;
         const v = Number(s.data[i]);
         if (!isFinite(v)) continue;
+        visitPositive(v);
         if (v >= 0) pos += v;
         else neg += v;
       }
@@ -157,6 +180,7 @@ const valueExtent = computed(() => {
       for (const v of s.data) {
         const n = Number(v);
         if (!isFinite(n)) continue;
+        visitPositive(n);
         if (n < min) min = n;
         if (n > max) max = n;
       }
@@ -165,11 +189,25 @@ const valueExtent = computed(() => {
   if (!isFinite(min)) min = 0;
   if (!isFinite(max)) max = 0;
   // Extend the value axis down to valueMin (default 0) when data sits
-  // above it, so bars share a common baseline.
+  // above it, so bars share a common baseline. On log scales, only
+  // positive valueMin values are honored.
   const floor = props.valueMin ?? 0;
-  if (floor < min) min = floor;
-  const range = max - min || 1;
-  return { min, max, range };
+  if (props.valueScaleType === "log") {
+    if (floor > 0 && floor < min) min = floor;
+  } else if (floor < min) {
+    min = floor;
+  }
+  const clamped = clampExtentForScale(
+    min,
+    max,
+    props.valueScaleType,
+    smallestPositive,
+  );
+  return {
+    min: clamped.min,
+    max: clamped.max,
+    range: clamped.max - clamped.min || 1,
+  };
 });
 
 /** Size (in pixels) of the categorical axis. */
@@ -218,12 +256,12 @@ const groupedBaselinePixel = computed(() => {
 
 /** Convert a data value to its pixel position along the value axis. */
 function valuePixel(v: number): number {
-  const { min, range } = valueExtent.value;
-  const scale = valueSize.value / range;
+  const { min, max } = valueExtent.value;
+  const frac = scaleFraction(v, min, max, props.valueScaleType);
   if (isVertical.value) {
-    return padding.value.top + innerH.value - (v - min) * scale;
+    return padding.value.top + innerH.value - frac * innerH.value;
   }
-  return padding.value.left + (v - min) * scale;
+  return padding.value.left + frac * innerW.value;
 }
 
 interface BarRect {
@@ -367,7 +405,9 @@ const formatTooltipValue = makeTooltipValueFormatter(
 const valueTickItems = computed(() => {
   const { min, max } = valueExtent.value;
   const fmt = (v: number) =>
-    props.valueTickFormat ? props.valueTickFormat(v) : formatTick(v);
+    props.valueTickFormat !== undefined
+      ? formatNumber(v, props.valueTickFormat)
+      : formatTick(v);
   if (min === max) {
     return [
       {
@@ -377,12 +417,15 @@ const valueTickItems = computed(() => {
     ];
   }
   const targetTickPixels = isVertical.value ? 50 : 80;
-  const values = computeTickValues({
-    min,
-    max,
-    ticks: props.valueTicks,
-    targetTickCount: valueSize.value / targetTickPixels,
-  });
+  const values =
+    props.valueScaleType === "log"
+      ? computeLogTickValues({ min, max, ticks: props.valueTicks })
+      : computeTickValues({
+          min,
+          max,
+          ticks: props.valueTicks,
+          targetTickCount: valueSize.value / targetTickPixels,
+        });
   return values.map((v) => ({
     value: fmt(v),
     pos: snap(valuePixel(v)),

package/charts/ChartMenu/download.ts

@@ -7,16 +7,81 @@ export function downloadBlob(blob: Blob, name: string) {
   URL.revokeObjectURL(url);
 }
 
-export function saveSvg(svg: SVGSVGElement, filename: string) {
+/** Inherited CSS properties propagated onto the cloned SVG root so text and
+ *  `currentColor` strokes render with the same color/typography as the
+ *  live chart when the SVG is opened standalone or rasterized to PNG. */
+const ROOT_INHERITED_PROPS = [
+  "color",
+  "font-family",
+  "font-size",
+  "font-weight",
+] as const;
+
+/** Presentation attributes that may contain `var(--…)` references. The
+ *  fallback inside `var(--name, #fff)` is the only thing that renders when
+ *  the custom property is undefined outside the page context — so we
+ *  resolve them against the document's CSS custom properties before
+ *  serializing. */
+const VAR_RESOLVABLE_ATTRS = ["fill", "stroke"] as const;
+
+/** Resolve a single `var(--name)` or `var(--name, fallback)` expression.
+ *  Looks the name up on `document.documentElement` (where theme tokens are
+ *  declared); falls back to the in-expression fallback, then the original
+ *  expression if neither resolves. */
+function resolveVarExpression(expr: string): string {
+  const match = expr.match(
+    /^\s*var\(\s*(--[\w-]+)\s*(?:,\s*([^)]*?)\s*)?\)\s*$/,
+  );
+  if (!match) return expr;
+  const [, name, fallback] = match;
+  const value = window
+    .getComputedStyle(document.documentElement)
+    .getPropertyValue(name)
+    .trim();
+  if (value) return value;
+  if (fallback) return fallback.trim();
+  return expr;
+}
+
+/** Clone `svg` and inline the styles that don't survive a standalone render:
+ *  inherited `color`/`font-*` on the root (so `currentColor` and unset
+ *  font-family resolve), and any `var(--…)` references in fill/stroke
+ *  attributes resolved against the document. */
+export function prepareSvgForExport(svg: SVGSVGElement): SVGSVGElement {
   const clone = svg.cloneNode(true) as SVGSVGElement;
   clone.setAttribute("xmlns", "http://www.w3.org/2000/svg");
+
+  const rootComputed = window.getComputedStyle(svg);
+  const rootStyleParts: string[] = [];
+  for (const prop of ROOT_INHERITED_PROPS) {
+    const value = rootComputed.getPropertyValue(prop);
+    if (value) rootStyleParts.push(`${prop}: ${value}`);
+  }
+  const existingRootStyle = clone.getAttribute("style") ?? "";
+  clone.setAttribute(
+    "style",
+    [existingRootStyle, ...rootStyleParts].filter(Boolean).join("; "),
+  );
+
+  for (const target of clone.querySelectorAll<SVGElement>("*")) {
+    for (const attr of VAR_RESOLVABLE_ATTRS) {
+      const raw = target.getAttribute(attr);
+      if (!raw || !raw.includes("var(")) continue;
+      target.setAttribute(attr, resolveVarExpression(raw));
+    }
+  }
+
+  return clone;
+}
+
+export function saveSvg(svg: SVGSVGElement, filename: string) {
+  const clone = prepareSvgForExport(svg);
   const xml = new XMLSerializer().serializeToString(clone);
   downloadBlob(new Blob([xml], { type: "image/svg+xml" }), `${filename}.svg`);
 }
 
 export function savePng(svg: SVGSVGElement, filename: string) {
-  const clone = svg.cloneNode(true) as SVGSVGElement;
-  clone.setAttribute("xmlns", "http://www.w3.org/2000/svg");
+  const clone = prepareSvgForExport(svg);
   const xml = new XMLSerializer().serializeToString(clone);
   const svgBlob = new Blob([xml], { type: "image/svg+xml;charset=utf-8" });
   const url = URL.createObjectURL(svgBlob);

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -704,7 +704,7 @@ set `tooltip-trigger`.
       id: string` | No | — |
 | `name` | `string` | Yes | — |
 | `value` | `number \| string` | No | — |
-| `tooltipValueFormat` | `(value: number) => string` | No | — |
+| `tooltipValueFormat` | `NumberFormat` | No | — |
 | `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
 | `focus` | `FocusValue` | No | — |
 | `focusZoomLevel` | `number` | No | `4` |

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -16,6 +16,7 @@ import { select } from "d3-selection";
 import "d3-transition";
 import { feature, mesh, merge } from "topojson-client";
 import type { Topology, GeometryCollection } from "topojson-specification";
+import { formatNumber, type NumberFormat } from "@cfasim-ui/shared";
 import { fipsToHsa, hsaNames } from "./hsaMapping.js";
 import ChartMenu from "../ChartMenu/ChartMenu.vue";
 import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
@@ -129,11 +130,12 @@ const props = withDefaults(
       value?: number | string;
     }) => string;
     /**
-     * Formatter for numeric values shown in the default tooltip. Receives
-     * the raw value. Ignored when `tooltipFormat` is provided (the caller
-     * controls the entire tooltip in that case).
+     * Formatter for numeric values shown in the default tooltip. Accepts a
+     * preset name, a printf-style format string, or a function. Ignored when
+     * `tooltipFormat` is provided (the caller controls the entire tooltip in
+     * that case). See `formatNumber` in `@cfasim-ui/shared`.
      */
-    tooltipValueFormat?: (value: number) => string;
+    tooltipValueFormat?: NumberFormat;
     /**
      * Boundary for tooltip flip/clamp. `"none"` always places to the right of
      * the pointer with no clamping. `"chart"` (default) uses the map
@@ -889,8 +891,8 @@ const featureName = (
 
 function formatTooltipValue(value: number | string | undefined): string {
   if (value == null) return "";
-  if (typeof value === "number" && props.tooltipValueFormat) {
-    return props.tooltipValueFormat(value);
+  if (typeof value === "number" && props.tooltipValueFormat !== undefined) {
+    return formatNumber(value, props.tooltipValueFormat);
   }
   return String(value);
 }

package/charts/DataTable/DataTable.md

@@ -56,6 +56,43 @@ A table for displaying columnar data. Accepts a plain record of arrays or a `Mod
   </template>
 </ComponentDemo>
 
+### Formatting cell values
+
+Use `format` on a column to override the default rendering. Accepts a
+{@link NumberFormat} value — a preset name (optionally with `:N` digits,
+e.g. `"percent:1"`), a printf-style format string, or a function
+`(value, row) => string`. Formatted values are also used in CSV exports.
+
+<ComponentDemo>
+  <DataTable
+    :data="{ day: [0, 1, 2, 3, 4], rate: [0.012, 0.234, 0.467, 0.512, 0.601], cases: [1, 21, 56, 101, 141] }"
+    :column-config="{
+      day: { label: 'Day', width: 'small' },
+      rate: { label: 'Attack rate', format: 'percent:1' },
+      cases: { label: 'Cases', format: '%05d' },
+    }"
+  />
+
+<template #code>
+
+```vue
+<DataTable
+  :data="{
+    day: [0, 1, 2, 3, 4],
+    rate: [0.012, 0.234, 0.467, 0.512, 0.601],
+    cases: [1, 21, 56, 101, 141],
+  }"
+  :column-config="{
+    day: { label: 'Day', width: 'small' },
+    rate: { label: 'Attack rate', format: 'percent:1' },
+    cases: { label: 'Cases', format: '%05d' },
+  }"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Cell class and max rows
 
 <ComponentDemo>
@@ -169,5 +206,16 @@ interface ColumnConfig {
   width?: "small" | "medium" | "large" | number;
   align?: "left" | "center" | "right";
   cellClass?: string;
+  format?: NumberFormat | ((value: CellValue, row: number) => string);
 }
+
+type CellValue = number | string | boolean;
+
+type NumberFormat =
+  | NumberFormatPreset // "plain" | "localized" | "percent" | "compact" | "scientific" | "engineering" (optionally with ":N" digits, e.g. "percent:1")
+  | string // printf-style format, e.g. "%.2f", "%05d"
+  | ((value: number) => string);
 ```
+
+See `formatNumber` in `@cfasim-ui/shared` for the underlying utility — you
+can also call it directly in your own code.

package/charts/DataTable/DataTable.vue

@@ -1,7 +1,11 @@
 <script setup lang="ts">
 import { computed } from "vue";
 import type { CSSProperties } from "vue";
-import type { ModelOutput } from "@cfasim-ui/shared";
+import {
+  formatNumber,
+  type ModelOutput,
+  type NumberFormat,
+} from "@cfasim-ui/shared";
 import ChartMenu from "../ChartMenu/ChartMenu.vue";
 import type { ChartMenuItem } from "../ChartMenu/ChartMenu.vue";
 import { downloadCsv } from "../ChartMenu/download.js";
@@ -10,12 +14,23 @@ export type TableRecord = Record<string, ArrayLike<number | string | boolean>>;
 export type TableData = TableRecord | ModelOutput;
 export type ColumnWidth = "small" | "medium" | "large";
 export type ColumnAlign = "left" | "center" | "right";
+export type CellValue = number | string | boolean;
+export type ColumnFormatter = (value: CellValue, row: number) => string;
 
 export interface ColumnConfig {
   label?: string;
   width?: ColumnWidth | number;
   align?: ColumnAlign;
   cellClass?: string;
+  /**
+   * Custom formatter for cell values in this column. Accepts a
+   * {@link NumberFormat} (preset name, printf-style string, or
+   * `(value) => string` function — see `formatNumber` in
+   * `@cfasim-ui/shared`) or a `(value, row) => string` function for full
+   * control. Number presets/sprintf only apply to numeric cells; other
+   * types fall back to default rendering. Used in CSV exports.
+   */
+  format?: NumberFormat | ColumnFormatter;
 }
 
 const COLUMN_WIDTHS: Record<ColumnWidth, string> = {
@@ -102,6 +117,18 @@ const rowCount = computed(() => {
 function cellValue(col: Column, row: number): string {
   const v = col.values[row];
   if (v === undefined || v === null) return "";
+  const format = props.columnConfig?.[col.name]?.format;
+  if (format !== undefined) {
+    // Function variant — either `(value: number) => string` (NumberFormat
+    // function) or `(value, row) => string` (ColumnFormatter). Both call
+    // sites are compatible; the narrower variant ignores `row`.
+    if (typeof format === "function") {
+      return (format as ColumnFormatter)(v, row);
+    }
+    // String preset/sprintf — only applies to numeric cells; other types
+    // fall through to default rendering.
+    if (typeof v === "number") return formatNumber(v, format);
+  }
   if (col.enumLabels && typeof v === "number")
     return col.enumLabels[v] ?? String(v);
   if (typeof v === "number") {

package/charts/LineChart/LineChart.md

@@ -180,6 +180,39 @@ Control tick placement with `x-ticks` and `y-ticks`. Pass a **number** for a fix
   </template>
 </ComponentDemo>
 
+### Logarithmic y-axis
+
+Set `y-scale-type="log"` to switch the y axis to base-10 log scaling. Useful
+when data spans several orders of magnitude (e.g. epidemic case counts in
+early exponential growth). Non-positive values collapse to the axis
+floor, and `yMin <= 0` is ignored.
+
+<ComponentDemo>
+  <LineChart
+    :data="[1, 3, 8, 22, 60, 165, 450, 1230, 3350]"
+    y-scale-type="log"
+    :height="220"
+    x-label="Day"
+    y-label="Cases"
+    y-grid
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :data="[1, 3, 8, 22, 60, 165, 450, 1230, 3350]"
+  y-scale-type="log"
+  :height="220"
+  x-label="Day"
+  y-label="Cases"
+  y-grid
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Dashed baseline
 
 <ComponentDemo>
@@ -647,7 +680,7 @@ until the user clicks Download:
 | `tooltipData` | `ArrayLike&lt;unknown&gt;` | No | — |
 | `tooltipTrigger` | `"hover" \| "click"` | No | — |
 | `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
-| `tooltipValueFormat` | `(value: number) =&gt; string` | No | — |
+| `tooltipValueFormat` | `NumberFormat` | No | — |
 | `csv` | `string \| (() =&gt; string)` | No | — |
 | `filename` | `string` | No | — |
 | `downloadLink` | `boolean \| string` | No | — |
@@ -661,11 +694,12 @@ until the user clicks Download:
 | `areaSections` | `AreaSection[]` | No | — |
 | `lineOpacity` | `number` | No | `1` |
 | `yMin` | `number` | No | — |
+| `yScaleType` | `"linear" \| "log"` | No | `"linear"` |
 | `xMin` | `number` | No | — |
 | `xTicks` | `number \| number[]` | No | — |
 | `yTicks` | `number \| number[]` | No | — |
-| `xTickFormat` | `(value: number, index: number) =&gt; string` | No | — |
-| `yTickFormat` | `(value: number) =&gt; string` | No | — |
+| `xTickFormat` | `NumberFormat \| ((value: number, index: number) =&gt; string)` | No | — |
+| `yTickFormat` | `NumberFormat` | No | — |
 | `xLabels` | `string[]` | No | — |
 | `xGrid` | `boolean` | No | — |
 | `yGrid` | `boolean` | No | — |