@cfasim-ui/docs 0.4.6 → 0.4.8

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/ChartAnnotations.vue

@@ -39,10 +39,6 @@ const LINE_HEIGHT_RATIO = 1.2;
 // of the first text line (between baseline and cap-height). Lands on the
 // x-height middle for most fonts.
 const FIRST_LINE_CENTER_RATIO = 0.35;
-// Nudge the start of the curve a few pixels in the offset direction so
-// it doesn't sit directly on top of axis lines or gridlines at the
-// anchor.
-const START_NUDGE_PX = 3;
 
 interface TextRun {
   text: string;
@@ -66,6 +62,10 @@ interface RenderedAnnotation {
   lineWidth: number;
   lineDash?: string;
   arrow: boolean;
+  // Inline arrow geometry. Rendered as a triangle with explicit fill so it
+  // renders correctly in Safari (which doesn't support `context-stroke` on
+  // SVG markers). Present only when an arrow should be drawn.
+  arrowTip?: { x: number; y: number; angle: number };
   rule?: { x1: number; y1: number; x2: number; y2: number };
 }
 
@@ -138,10 +138,12 @@ const items = computed<RenderedAnnotation[]>(() => {
 
     let rule: RenderedAnnotation["rule"];
     let pointerPath = "";
+    let arrowTip: RenderedAnnotation["arrowTip"];
+    const wantArrow = !isRule && (a.arrow ?? true);
     if (isRule && props.bounds) {
       rule = computeRule(pointer, projected.x, projected.y, props.bounds);
     } else {
-      pointerPath = buildPointerPath(
+      const built = buildPointerPath(
         projected.x,
         projected.y,
         labelX,
@@ -149,6 +151,8 @@ const items = computed<RenderedAnnotation[]>(() => {
         fontSize,
         pointer as "curved" | "straight" | "none",
       );
+      pointerPath = built.path;
+      if (wantArrow && built.arrow) arrowTip = built.arrow;
     }
 
     out.push({
@@ -166,7 +170,8 @@ const items = computed<RenderedAnnotation[]>(() => {
       lineColor,
       lineWidth,
       lineDash,
-      arrow: !isRule && (a.arrow ?? true),
+      arrow: wantArrow,
+      arrowTip,
       rule,
     });
   }
@@ -216,6 +221,15 @@ function computeRule(
  *   label so the endpoint reads as pointing at the first line — not at
  *   the bottom of a multi-line block.
  */
+interface PointerGeom {
+  path: string;
+  // Tip position and rotation (degrees) for the inline arrow head. The
+  // arrow points opposite the path's start tangent — matching the look of
+  // `marker-start` with `orient="auto-start-reverse"`, but rendered as a
+  // plain triangle so the color works in Safari.
+  arrow?: { x: number; y: number; angle: number };
+}
+
 function buildPointerPath(
   ax: number,
   ay: number,
@@ -223,8 +237,8 @@ function buildPointerPath(
   ly: number,
   fontSize: number,
   pointer: "curved" | "straight" | "none",
-): string {
-  if (pointer === "none") return "";
+): PointerGeom {
+  if (pointer === "none") return { path: "" };
   const dx = lx - ax;
   const dy = ly - ay;
 
@@ -243,53 +257,49 @@ function buildPointerPath(
     const segDx = lx - ax;
     const segDy = ey - ay;
     const len = Math.hypot(segDx, segDy);
-    if (len <= ANCHOR_GAP_PX + LABEL_GAP_PX) return "";
+    if (len <= ANCHOR_GAP_PX + LABEL_GAP_PX) return { path: "" };
     const ux = segDx / len;
     const uy = segDy / len;
     const sx = ax + ux * ANCHOR_GAP_PX;
     const sy = ay + uy * ANCHOR_GAP_PX;
     const ex = lx - ux * LABEL_GAP_PX;
     const eyClamped = ey - uy * LABEL_GAP_PX;
-    return `M${sx},${sy} L${ex},${eyClamped}`;
+    // Arrow points back toward the anchor (opposite of (ux, uy)).
+    const angle = (Math.atan2(-uy, -ux) * 180) / Math.PI;
+    return {
+      path: `M${sx},${sy} L${ex},${eyClamped}`,
+      arrow: { x: sx, y: sy, angle },
+    };
   }
 
   const adjDy = targetY - ay;
 
   // Skip the curve if one dimension is too small to clear its gap.
   if (Math.abs(adjDy) <= ANCHOR_GAP_PX || Math.abs(dx) <= LABEL_GAP_PX) {
-    return "";
+    return { path: "" };
   }
 
   const xDir = Math.sign(dx);
   const yDir = Math.sign(adjDy);
-  // Nudge the start horizontally toward the label so the line doesn't
-  // sit on top of axis/grid lines passing through the anchor.
-  const sx = ax + xDir * START_NUDGE_PX;
+  // Start the curve directly above/below the anchor so the arrow head
+  // lines up with the data point rather than sitting off to one side.
+  const sx = ax;
   const sy = ay + yDir * ANCHOR_GAP_PX;
   const ex = lx - xDir * LABEL_GAP_PX;
   const ey = targetY;
-  // Control sits at (sx, targetY) so the curve emerges from the nudged
-  // start tangent vertically and lands on the label horizontally —
-  // a clean quarter-arc shape.
-  return `M${sx},${sy} Q${sx},${targetY} ${ex},${ey}`;
+  // Control sits at (sx, targetY) so the curve emerges from the start
+  // tangent vertically and lands on the label horizontally —
+  // a clean quarter-arc shape. The start tangent is (0, yDir), so the
+  // arrow points (0, -yDir) — straight up when yDir=1, down when yDir=-1.
+  const angle = yDir > 0 ? -90 : 90;
+  return {
+    path: `M${sx},${sy} Q${sx},${targetY} ${ex},${ey}`,
+    arrow: { x: sx, y: sy, angle },
+  };
 }
 </script>
 
 <template>
-  <defs>
-    <marker
-      id="chart-annotation-arrow"
-      viewBox="0 0 8 8"
-      refX="7"
-      refY="4"
-      markerWidth="6"
-      markerHeight="6"
-      orient="auto-start-reverse"
-      markerUnits="userSpaceOnUse"
-    >
-      <path d="M0,0 L8,4 L0,8 Z" fill="context-stroke" />
-    </marker>
-  </defs>
   <g class="chart-annotations" pointer-events="none">
     <template v-for="(item, i) in items" :key="i">
       <line
@@ -308,11 +318,21 @@ function buildPointerPath(
         :d="item.pointerPath"
         fill="none"
         :stroke="item.lineColor"
-        :style="{ color: item.lineColor }"
         :stroke-width="item.lineWidth"
         :stroke-dasharray="item.lineDash"
         stroke-linecap="round"
-        :marker-start="item.arrow ? 'url(#chart-annotation-arrow)' : undefined"
+      />
+      <!--
+        Inline arrow head. Drawn as an explicit triangle (not via
+        `<marker>`) because Safari does not implement `context-stroke` on
+        marker fills, so a shared marker rendered as black instead of the
+        line color.
+      -->
+      <polygon
+        v-if="item.arrowTip"
+        points="0,0 -6,-3 -6,3"
+        :fill="item.lineColor"
+        :transform="`translate(${item.arrowTip.x} ${item.arrowTip.y}) rotate(${item.arrowTip.angle})`"
       />
       <text
         :x="item.textX"

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 | — |