@cfasim-ui/docs 0.4.7 → 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/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 | — |

package/charts/LineChart/LineChart.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,
   seriesToCsv,
   useChartFoundation,
   makeTooltipValueFormatter,
@@ -100,6 +104,13 @@ interface LineChartProps extends ChartCommonProps {
   areaSections?: AreaSection[];
   lineOpacity?: number;
   yMin?: number;
+  /**
+   * Scale type for the y 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 `yMin <= 0`
+   * is ignored.
+   */
+  yScaleType?: "linear" | "log";
   /**
    * Offset applied to index-based x values (e.g. `xMin: 10` starts the
    * x axis at 10 instead of 0). Ignored when any series or area has
@@ -119,10 +130,18 @@ interface LineChartProps extends ChartCommonProps {
    * omitted, ticks are chosen automatically.
    */
   yTicks?: number | number[];
-  /** Formatter for x-axis tick labels. Receives the raw numeric value. */
-  xTickFormat?: (value: number, index: number) => string;
-  /** Formatter for y-axis tick labels. Receives the raw numeric value. */
-  yTickFormat?: (value: number) => string;
+  /**
+   * Formatter for x-axis tick labels. Accepts a preset name, a printf-style
+   * format string, or a function. The two-arg function form `(value, index)`
+   * is also supported for index-based labels. See `formatNumber` in
+   * `@cfasim-ui/shared`.
+   */
+  xTickFormat?: NumberFormat | ((value: number, index: number) => string);
+  /**
+   * Formatter for y-axis tick labels. Accepts a preset name, a printf-style
+   * format string, or a function. See `formatNumber` in `@cfasim-ui/shared`.
+   */
+  yTickFormat?: NumberFormat;
   /**
    * @deprecated Use `xTickFormat` (e.g. `(_, i) => labels[i]`) together
    * with `xTicks` for explicit control. Still honored for tooltip x-labels
@@ -137,6 +156,7 @@ const props = withDefaults(defineProps<LineChartProps>(), {
   lineOpacity: 1,
   menu: true,
   tooltipClamp: "chart",
+  yScaleType: "linear",
 });
 
 const emit = defineEmits<{
@@ -254,36 +274,42 @@ function xPixel(v: number): number {
 const extent = computed(() => {
   let min = Infinity;
   let max = -Infinity;
-  for (const s of allSeries.value) {
-    for (const v of s.data) {
-      if (!isFinite(v)) continue;
-      if (v < min) min = v;
-      if (v > max) max = v;
-    }
-  }
+  let smallestPositive = Infinity;
+  const visit = (v: number) => {
+    if (!isFinite(v)) return;
+    if (v < min) min = v;
+    if (v > max) max = v;
+    if (v > 0 && v < smallestPositive) smallestPositive = v;
+  };
+  for (const s of allSeries.value) for (const v of s.data) visit(v);
   for (const a of allAreas.value) {
-    for (const v of a.upper) {
-      if (!isFinite(v)) continue;
-      if (v < min) min = v;
-      if (v > max) max = v;
-    }
-    for (const v of a.lower) {
-      if (!isFinite(v)) continue;
-      if (v < min) min = v;
-      if (v > max) max = v;
-    }
+    for (const v of a.upper) visit(v);
+    for (const v of a.lower) visit(v);
   }
   if (!isFinite(min)) return { min: 0, max: 0, range: 1 };
   if (props.yMin != null && props.yMin < min) min = props.yMin;
-  return { min, max, range: max - min || 1 };
+  const clamped = clampExtentForScale(
+    min,
+    max,
+    props.yScaleType,
+    smallestPositive,
+  );
+  return {
+    min: clamped.min,
+    max: clamped.max,
+    range: clamped.max - clamped.min || 1,
+  };
 });
 
+function yPixel(v: number): number {
+  const { min, max } = extent.value;
+  const py = padding.value.top + innerH.value;
+  return py - scaleFraction(v, min, max, props.yScaleType) * innerH.value;
+}
+
 function toPath(s: ResolvedSeries): string {
   const data = s.data;
   if (data.length === 0) return "";
-  const { min, range } = extent.value;
-  const yScale = innerH.value / range;
-  const py = padding.value.top + innerH.value;
   let d = "";
   let inSegment = false;
   for (let i = 0; i < data.length; i++) {
@@ -293,7 +319,7 @@ function toPath(s: ResolvedSeries): string {
       continue;
     }
     const x = xPixel(xv);
-    const y = py - (data[i] - min) * yScale;
+    const y = yPixel(data[i]);
     d += inSegment ? `L${x},${y}` : `M${x},${y}`;
     inSegment = true;
   }
@@ -302,14 +328,11 @@ function toPath(s: ResolvedSeries): string {
 
 function toPoints(s: ResolvedSeries): { x: number; y: number }[] {
   const data = s.data;
-  const { min, range } = extent.value;
-  const yScale = innerH.value / range;
-  const py = padding.value.top + innerH.value;
   const pts: { x: number; y: number }[] = [];
   for (let i = 0; i < data.length; i++) {
     const xv = seriesXAt(s, i);
     if (!isFinite(data[i]) || !isFinite(xv)) continue;
-    pts.push({ x: xPixel(xv), y: py - (data[i] - min) * yScale });
+    pts.push({ x: xPixel(xv), y: yPixel(data[i]) });
   }
   return pts;
 }
@@ -317,10 +340,6 @@ function toPoints(s: ResolvedSeries): { x: number; y: number }[] {
 function toAreaPath(a: Area): string {
   const len = Math.min(a.upper.length, a.lower.length);
   if (len === 0) return "";
-  const { min, range } = extent.value;
-  const yScale = innerH.value / range;
-  const py = padding.value.top + innerH.value;
-  const y = (v: number) => py - (v - min) * yScale;
   // Collect contiguous segments where both upper/lower and x are finite
   const segments: number[][] = [];
   let seg: number[] = [];
@@ -339,11 +358,11 @@ function toAreaPath(a: Area): string {
   if (seg.length) segments.push(seg);
   let d = "";
   for (const s of segments) {
-    d += `M${xPixel(areaXAt(a, s[0]))},${y(a.upper[s[0]])}`;
+    d += `M${xPixel(areaXAt(a, s[0]))},${yPixel(a.upper[s[0]])}`;
     for (let j = 1; j < s.length; j++)
-      d += `L${xPixel(areaXAt(a, s[j]))},${y(a.upper[s[j]])}`;
+      d += `L${xPixel(areaXAt(a, s[j]))},${yPixel(a.upper[s[j]])}`;
     for (let j = s.length - 1; j >= 0; j--)
-      d += `L${xPixel(areaXAt(a, s[j]))},${y(a.lower[s[j]])}`;
+      d += `L${xPixel(areaXAt(a, s[j]))},${yPixel(a.lower[s[j]])}`;
     d += "Z";
   }
   return d;
@@ -376,18 +395,15 @@ function toSectionPath(section: AreaSection, closed = true): string {
 
   const s = allSeries.value[section.seriesIndex];
   if (!s) return "";
-  const { min, range } = extent.value;
-  const yScale = innerH.value / range;
-  const y = (v: number) => py - (v - min) * yScale;
 
   const start = Math.max(0, section.startIndex);
   const end = Math.min(s.data.length - 1, section.endIndex);
   if (start > end) return "";
 
-  let d = `M${xPixel(seriesXAt(s, start))},${y(s.data[start])}`;
+  let d = `M${xPixel(seriesXAt(s, start))},${yPixel(s.data[start])}`;
   for (let i = start + 1; i <= end; i++) {
     if (!isFinite(s.data[i])) continue;
-    d += `L${xPixel(seriesXAt(s, i))},${y(s.data[i])}`;
+    d += `L${xPixel(seriesXAt(s, i))},${yPixel(s.data[i])}`;
   }
   if (closed) {
     d += `L${xPixel(seriesXAt(s, end))},${py}`;
@@ -531,26 +547,25 @@ const sectionLabelBaseY = computed(
 
 const yTickItems = computed(() => {
   const { min, max } = extent.value;
-  const toY = (v: number) =>
-    snap(
-      padding.value.top +
-        innerH.value -
-        ((v - min) / extent.value.range) * innerH.value,
-    );
   const fmt = (v: number) =>
-    props.yTickFormat ? props.yTickFormat(v) : formatTick(v);
+    props.yTickFormat !== undefined
+      ? formatNumber(v, props.yTickFormat)
+      : formatTick(v);
 
   if (min === max) {
     return [{ value: fmt(min), y: snap(padding.value.top + innerH.value / 2) }];
   }
 
-  const values = computeTickValues({
-    min,
-    max,
-    ticks: props.yTicks,
-    targetTickCount: innerH.value / 50,
-  });
-  return values.map((v) => ({ value: fmt(v), y: toY(v) }));
+  const values =
+    props.yScaleType === "log"
+      ? computeLogTickValues({ min, max, ticks: props.yTicks })
+      : computeTickValues({
+          min,
+          max,
+          ticks: props.yTicks,
+          targetTickCount: innerH.value / 50,
+        });
+  return values.map((v) => ({ value: fmt(v), y: snap(yPixel(v)) }));
 });
 
 const xTickItems = computed(() => {
@@ -562,7 +577,12 @@ const xTickItems = computed(() => {
   // Tick values are in data-space; display labels add `xDisplayOffset`.
   const fmt = (v: number, i: number) => {
     const display = v + offset;
-    if (props.xTickFormat) return props.xTickFormat(display, i);
+    const xf = props.xTickFormat;
+    if (xf !== undefined) {
+      return typeof xf === "function"
+        ? xf(display, i)
+        : formatNumber(display, xf);
+    }
     if (
       !hasExplicitX.value &&
       props.xLabels &&
@@ -653,9 +673,6 @@ function nearestIndex(s: ResolvedSeries, targetX: number): number | null {
 const hoverDots = computed(() => {
   const targetX = hoverDataX.value;
   if (targetX === null) return [];
-  const { min, range } = extent.value;
-  const yScale = innerH.value / range;
-  const py = padding.value.top + innerH.value;
   const dots: { x: number; y: number; color: string }[] = [];
   for (const s of allSeries.value) {
     const nIdx = nearestIndex(s, targetX);
@@ -664,7 +681,7 @@ const hoverDots = computed(() => {
     if (!isFinite(yv)) continue;
     dots.push({
       x: xPixel(seriesXAt(s, nIdx)),
-      y: py - (yv - min) * yScale,
+      y: yPixel(yv),
       color: s.color ?? "currentColor",
     });
   }
@@ -678,8 +695,10 @@ const hoverSlotProps = computed(() => {
   const offset = xDisplayOffset.value;
   const displayX = targetX + offset;
   let xLabel: string | undefined;
-  if (props.xTickFormat) {
-    xLabel = props.xTickFormat(displayX, idx);
+  const xf = props.xTickFormat;
+  if (xf !== undefined) {
+    xLabel =
+      typeof xf === "function" ? xf(displayX, idx) : formatNumber(displayX, xf);
   } else if (!hasExplicitX.value) {
     xLabel = props.xLabels?.[idx];
   } else {
@@ -706,10 +725,7 @@ function projectAnnotation(
 ): { x: number; y: number } | null {
   if (!isFinite(x) || !isFinite(y)) return null;
   const internalX = x - xDisplayOffset.value;
-  const { min, range } = extent.value;
-  const py =
-    padding.value.top + innerH.value - (y - min) * (innerH.value / range);
-  return { x: xPixel(internalX), y: py };
+  return { x: xPixel(internalX), y: yPixel(y) };
 }
 
 function indexFromPointer(clientX: number): number | null {

package/charts/_shared/chartProps.ts

@@ -4,6 +4,7 @@
  * intersection (e.g. `defineProps<ChartCommonProps & MyExtraProps>()`).
  */
 
+import type { NumberFormat } from "@cfasim-ui/shared";
 import type { ChartAnnotation } from "./annotations.js";
 import type { ChartPadding } from "./useChartPadding.js";
 
@@ -30,11 +31,12 @@ export interface ChartCommonProps {
   /** Boundary for tooltip flip/clamp. Default: `"chart"`. */
   tooltipClamp?: "none" | "chart" | "window";
   /**
-   * Formatter for numeric values shown in the default tooltip. Receives
-   * the raw value. When omitted, the chart falls back to its value-axis
-   * tick formatter, then `formatTick`.
+   * Formatter for numeric values shown in the default tooltip. Accepts a
+   * preset name, a printf-style format string, or a function. When
+   * omitted, the chart falls back to its value-axis tick formatter, then
+   * `formatTick`. See `formatNumber` in `@cfasim-ui/shared`.
    */
-  tooltipValueFormat?: (value: number) => string;
+  tooltipValueFormat?: NumberFormat;
   /**
    * Custom CSV content (string or function) for the Download CSV menu
    * item. When omitted, CSV is generated from the chart's series.

package/charts/_shared/index.ts

@@ -6,6 +6,13 @@ export {
   type ChartData,
 } from "./axes.js";
 export { computeTickValues, type TickValueOptions } from "./computeTicks.js";
+export {
+  scaleFraction,
+  clampExtentForScale,
+  computeLogTickValues,
+  LOG_FLOOR,
+  type ScaleType,
+} from "./scale.js";
 export { useChartSize, type ChartSizeOptions } from "./useChartSize.js";
 export {
   useChartPadding,

package/charts/_shared/scale.ts

@@ -0,0 +1,86 @@
+/**
+ * Linear and log scale helpers shared by chart components. The chart
+ * computes a `[min, max]` data extent then maps values to pixels via
+ * `scaleFraction`; log mode clamps `min` to a positive floor so we
+ * never take `log10(0)` or `log10(-x)`.
+ */
+
+export type ScaleType = "linear" | "log";
+
+/** Default floor used when a log-scale extent contains no positive data. */
+export const LOG_FLOOR = 1;
+
+/**
+ * Project a value onto a [0, 1] fraction of the axis range. The caller
+ * multiplies by the pixel range and adds the axis origin. On log
+ * scales, non-positive values collapse to the visible minimum so they
+ * sit on the axis floor instead of producing -Infinity.
+ */
+export function scaleFraction(
+  v: number,
+  min: number,
+  max: number,
+  type: ScaleType,
+): number {
+  if (type === "log") {
+    const lmin = Math.log10(min);
+    const lmax = Math.log10(max);
+    const range = lmax - lmin || 1;
+    const safe = v > 0 ? v : min;
+    return (Math.log10(safe) - lmin) / range;
+  }
+  const range = max - min || 1;
+  return (v - min) / range;
+}
+
+/**
+ * Clamp the lower bound of a data extent so it's safe for log scale.
+ * For linear scales the inputs are returned unchanged. For log scales,
+ * `min` is raised to the smallest positive value in the data (or
+ * `LOG_FLOOR` when no positive values exist), and `max` is also
+ * floored to that value so a degenerate axis still renders.
+ */
+export function clampExtentForScale(
+  min: number,
+  max: number,
+  type: ScaleType,
+  smallestPositive: number,
+): { min: number; max: number } {
+  if (type !== "log") return { min, max };
+  const floor =
+    smallestPositive > 0 && isFinite(smallestPositive)
+      ? smallestPositive
+      : LOG_FLOOR;
+  const lo = min > 0 ? min : floor;
+  const hi = max > 0 ? Math.max(max, lo) : lo;
+  return { min: lo, max: hi };
+}
+
+/**
+ * Generate tick values for a log axis. By default returns powers of 10
+ * inside `[min, max]`. Pass `ticks` as an explicit array to override;
+ * numeric `ticks` (linear interval) is ignored on a log axis since it
+ * would produce a swarm of densely-packed labels — use an array for
+ * non-default tick placement.
+ */
+export function computeLogTickValues(opts: {
+  min: number;
+  max: number;
+  ticks?: number | number[];
+}): number[] {
+  const { min, max, ticks } = opts;
+  if (!(min > 0) || !(max > 0) || min === max) return [];
+
+  if (Array.isArray(ticks)) {
+    return ticks.filter((v) => v > 0 && v >= min && v <= max);
+  }
+
+  const lo = Math.floor(Math.log10(min));
+  const hi = Math.ceil(Math.log10(max));
+  const out: number[] = [];
+  for (let e = lo; e <= hi; e++) {
+    const v = Math.pow(10, e);
+    if (v >= min && v <= max) out.push(v);
+  }
+  return out;
+}

package/charts/_shared/useChartFoundation.ts

@@ -1,4 +1,5 @@
 import { computed } from "vue";
+import { formatNumber, type NumberFormat } from "@cfasim-ui/shared";
 import { formatTick } from "./axes.js";
 import { useChartSize } from "./useChartSize.js";
 import { useChartPadding, type ChartPadding } from "./useChartPadding.js";
@@ -111,14 +112,14 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
  * `formatTick`. Both chart components use the same precedence order.
  */
 export function makeTooltipValueFormatter(
-  tooltipFormat: () => ((v: number) => string) | undefined,
-  axisFormat: () => ((v: number) => string) | undefined,
+  tooltipFormat: () => NumberFormat | undefined,
+  axisFormat: () => NumberFormat | undefined,
 ): (v: number) => string {
   return (v: number) => {
     const tf = tooltipFormat();
-    if (tf) return tf(v);
+    if (tf !== undefined) return formatNumber(v, tf);
     const af = axisFormat();
-    if (af) return af(v);
+    if (af !== undefined) return formatNumber(v, af);
     return formatTick(v);
   };
 }

package/components/NumberInput/NumberInput.md

@@ -232,12 +232,24 @@ Range mode works with `percent` and `live` as well:
   </template>
 </ComponentDemo>
 
-### Custom slider display
+### Custom display format
 
-Pass `slider-display` (a `(value: number) => string` function) to format the
-thumb labels and the min/max labels however you like. The internal model is
-still a number — only the displayed text changes. This applies to single
-sliders and ranges; the regular text input is unaffected.
+Pass `format` to control how the value is displayed in the text input and
+in slider thumb/min/max labels. Accepts a
+[`NumberFormat`](../charts/data-table.md#columnconfig) — a preset name
+(optionally with a `:N` digits suffix, e.g. `"percent:1"`), a printf-style
+format string (`"%.2f"`), or a `(value: number) => string` function. The
+internal model stays a number — only the displayed text changes.
+
+When unset, the default formatting follows the `percent` and `decimals`
+props. When set, `format` overrides both. Formats that add suffixes or
+scale the value (e.g. `"percent:1"` → `"12.3%"`) may not round-trip
+through the text input — pair them with `percent: true` for value scaling
+and use `format` for display shaping.
+
+The older `slider-display` prop (a `(value: number) => string` function
+that only affected slider thumb/min/max labels) is **deprecated** but
+still honored when `format` is unset. Prefer `format` for new code.
 
 <ComponentDemo>
   <div style="width: 300px">
@@ -247,7 +259,7 @@ sliders and ranges; the regular text input is unaffected.
       :min="dateStart"
       :max="dateEnd"
       :step="dayMs"
-      :slider-display="formatDate"
+      :format="formatDate"
     />
   </div>
 
@@ -270,7 +282,7 @@ const formatDate = (ms) =>
   :min="dateStart"
   :max="dateEnd"
   :step="dayMs"
-  :slider-display="formatDate"
+  :format="formatDate"
 />
 ```
 
@@ -466,5 +478,8 @@ the input visually.
 | `numberType` | `"integer" \| "float"` | No | — |
 | `required` | `boolean` | No | — |
 | `decimals` | `number` | No | — |
+| `percent` | `1"`) may not round-trip through the text input — use
+  // `percent: true` for value scaling and `format` for display shaping.
+  format?: NumberFormat` | Yes | — |
 | `sliderDisplay` | `(value: number) =&gt; string` | No | — |
 

package/components/NumberInput/NumberInput.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { ref, watch, computed, onMounted, getCurrentInstance } from "vue";
 import { SliderRoot, SliderTrack, SliderRange, SliderThumb } from "reka-ui";
+import { formatNumber, type NumberFormat } from "@cfasim-ui/shared";
 import Hint from "../Hint/Hint.vue";
 
 export type NumberRange = [number, number];
@@ -29,9 +30,17 @@ const props = defineProps<{
   numberType?: "integer" | "float";
   required?: boolean;
   decimals?: number;
-  // Custom formatter for slider thumb labels and min/max labels. Overrides
-  // the default percent/decimal formatting when provided. Only consulted in
-  // slider/range mode — the text input keeps its own number-shaped formatting.
+  // Custom formatter for the displayed value. Accepts a NumberFormat
+  // (preset name, printf string, or function) — see `formatNumber` in
+  // `@cfasim-ui/shared`. When set, overrides the default percent/decimal
+  // formatting for both the text input value and slider thumb/min/max
+  // labels. The model stays a raw number; only the display changes. Note
+  // that formats which add suffixes or scale the value (e.g.
+  // `"percent:1"`) may not round-trip through the text input — use
+  // `percent: true` for value scaling and `format` for display shaping.
+  format?: NumberFormat;
+  /** @deprecated Use `format` instead. Still honored for slider labels
+   * when `format` is unset, but will be removed in a future release. */
   sliderDisplay?: (value: number) => string;
 }>();
 
@@ -113,7 +122,11 @@ function roundToDecimals(v: number, d: number): number {
 
 function formatSliderValue(v: number | undefined) {
   if (v == null) return "";
-  if (props.sliderDisplay) return props.sliderDisplay(v);
+  // sliderDisplay (deprecated) is a function — i.e. already a valid
+  // NumberFormat — so route it through formatNumber. `format` wins when
+  // both are set.
+  const fmt = props.format ?? props.sliderDisplay;
+  if (fmt !== undefined) return formatNumber(v, fmt);
   const d = displayDecimals.value;
   if (props.percent) return (v * 100).toFixed(d) + "%";
   return v.toLocaleString("en-US", {
@@ -149,6 +162,7 @@ function formatWithCommas(v: number | undefined): string {
 
 function formatForDisplay(v: number | undefined): string {
   if (v == null) return "";
+  if (props.format !== undefined) return formatNumber(v, props.format);
   const d = displayDecimals.value;
   if (d > 0) {
     return v.toLocaleString("en-US", {

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.7",
+  "version": "0.4.8",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [

package/package.json

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

package/shared/formatNumber.ts

@@ -0,0 +1,146 @@
+import { sprintf } from "sprintf-js";
+
+/**
+ * Named number-format presets, modelled on Streamlit's number column formats.
+ * - `plain` — `String(value)` (no grouping)
+ * - `localized` — `Intl.NumberFormat()` with the user's locale
+ * - `percent` — formats as a percent (value `0.5` → `"50%"`)
+ * - `compact` — short form (`1.2K`, `3.4M`)
+ * - `scientific` — scientific notation (`1.23E4`)
+ * - `engineering` — engineering notation (powers of 1000)
+ *
+ * Presets preserve the raw value's precision by default (no rounding).
+ * Append `:N` (a digit) to fix the number of fractional digits, e.g.
+ * `"percent:1"` → `"12.3%"`, `"localized:2"` → `"1,234.50"`.
+ */
+export type NumberFormatPreset =
+  | "plain"
+  | "localized"
+  | "percent"
+  | "compact"
+  | "scientific"
+  | "engineering";
+
+/**
+ * A number format specifier:
+ * - A {@link NumberFormatPreset} name, optionally with `:N` digits suffix
+ *   (e.g. `"percent:1"`, `"compact:2"`)
+ * - A printf-style format string (must contain a `%` placeholder, parsed
+ *   by sprintf-js — e.g. `"%.2f"`, `"%05d"`)
+ * - A function `(value) => string` for full control
+ *
+ * Strings that contain no `%` and don't match a preset throw at format
+ * time, so typos surface immediately instead of silently rendering wrong.
+ */
+export type NumberFormat =
+  | NumberFormatPreset
+  | string
+  | ((value: number) => string);
+
+const PRESET_NAMES = new Set<NumberFormatPreset>([
+  "plain",
+  "localized",
+  "percent",
+  "compact",
+  "scientific",
+  "engineering",
+]);
+
+function isPreset(s: string): s is NumberFormatPreset {
+  return PRESET_NAMES.has(s as NumberFormatPreset);
+}
+
+/**
+ * Parse `"preset"` or `"preset:N"` into a name and optional digit count.
+ * Returns null if the string isn't a recognized preset.
+ */
+function parsePreset(
+  s: string,
+): { preset: NumberFormatPreset; digits: number | undefined } | null {
+  const colon = s.indexOf(":");
+  if (colon === -1) {
+    return isPreset(s) ? { preset: s, digits: undefined } : null;
+  }
+  const name = s.slice(0, colon);
+  const rest = s.slice(colon + 1);
+  if (!isPreset(name)) return null;
+  // Digits must be a non-negative integer (matches Intl's 0..100 range).
+  if (!/^\d+$/.test(rest)) return null;
+  const digits = Number(rest);
+  if (digits > 100) return null;
+  return { preset: name, digits };
+}
+
+// Covers JS double-precision (≤17 significant digits). When the caller
+// hasn't asked for a specific digit count, we use this to preserve the
+// raw value rather than letting Intl round to its default precision.
+const RAW_PRECISION_DIGITS = 20;
+
+function formatPreset(
+  value: number,
+  preset: NumberFormatPreset,
+  digits: number | undefined,
+): string {
+  const fractionOpts: Intl.NumberFormatOptions =
+    digits !== undefined
+      ? { minimumFractionDigits: digits, maximumFractionDigits: digits }
+      : { maximumFractionDigits: RAW_PRECISION_DIGITS };
+  switch (preset) {
+    case "plain":
+      return digits !== undefined ? value.toFixed(digits) : String(value);
+    case "localized":
+      return new Intl.NumberFormat(undefined, fractionOpts).format(value);
+    case "percent":
+      return new Intl.NumberFormat(undefined, {
+        style: "percent",
+        ...fractionOpts,
+      }).format(value);
+    case "compact":
+      return new Intl.NumberFormat(undefined, {
+        notation: "compact",
+        ...fractionOpts,
+      }).format(value);
+    case "scientific":
+      return new Intl.NumberFormat(undefined, {
+        notation: "scientific",
+        ...fractionOpts,
+      }).format(value);
+    case "engineering":
+      return new Intl.NumberFormat(undefined, {
+        notation: "engineering",
+        ...fractionOpts,
+      }).format(value);
+  }
+}
+
+/**
+ * Format a number using a preset name, a printf-style format string, or a
+ * custom function. Non-finite values (NaN, ±Infinity) are returned as
+ * `String(value)`; if `format` is omitted, falls back to `String(value)`.
+ *
+ * Throws if `format` is a string that's neither a recognized preset (with
+ * an optional `:N` digit suffix) nor a printf string containing `%`.
+ */
+export function formatNumber(value: number, format?: NumberFormat): string {
+  if (!Number.isFinite(value)) return String(value);
+  if (format === undefined) return String(value);
+  if (typeof format === "function") return format(value);
+  // printf strings always contain a `%` placeholder; everything else must
+  // be a recognized preset (with an optional `:N` digits suffix).
+  if (format.includes("%")) return sprintf(format, value);
+  const parsed = parsePreset(format);
+  if (!parsed) {
+    const names = [...PRESET_NAMES].join(", ");
+    throw new Error(
+      `formatNumber: invalid format ${JSON.stringify(format)}. ` +
+        `Expected one of ${names} (optionally with ":N" digits), ` +
+        `a printf format string containing "%", or a function.`,
+    );
+  }
+  return formatPreset(value, parsed.preset, parsed.digits);
+}
+
+/** True if `f` is a recognized {@link NumberFormat} value. */
+export function isNumberFormat(f: unknown): f is NumberFormat {
+  return typeof f === "string" || typeof f === "function";
+}

package/shared/index.ts

@@ -14,6 +14,8 @@ export type {
   ModelOutputsWire,
 } from "./ModelOutput.js";
 export { modelOutputToCSV } from "./csv.js";
+export { formatNumber, isNumberFormat } from "./formatNumber.js";
+export type { NumberFormat, NumberFormatPreset } from "./formatNumber.js";
 export {
   useUrlParams,
   serialize,