@cfasim-ui/charts 0.7.8 → 0.8.1

package/src/_shared/axes.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure helpers shared by chart components for axis tick math and value
+ * formatting. No Vue reactivity here; see `useAxisTicks` for the
+ * reactive wrapper.
+ */
+
+/** Round to nearest half-pixel so 1px SVG strokes stay sharp. */
+export function snap(v: number): number {
+  return Math.round(v) + 0.5;
+}
+
+export function niceStep(range: number, targetTicks: number): number {
+  const rough = range / targetTicks;
+  const mag = Math.pow(10, Math.floor(Math.log10(rough)));
+  const norm = rough / mag;
+  let step: number;
+  if (norm <= 1.5) step = 1;
+  else if (norm <= 3) step = 2;
+  else if (norm <= 7) step = 5;
+  else step = 10;
+  return step * mag;
+}
+
+/** Generate interval-spaced values in [min, max], inclusive. */
+export function intervalValues(
+  min: number,
+  max: number,
+  step: number,
+): number[] {
+  if (!(step > 0) || !isFinite(step)) return [];
+  const out: number[] = [];
+  const start = Math.ceil(min / step) * step;
+  // Cap iteration to avoid runaway loops from pathological inputs.
+  const maxIterations = 1000;
+  for (
+    let i = 0, v = start;
+    v <= max + 1e-9 && i < maxIterations;
+    i++, v = start + i * step
+  ) {
+    out.push(v);
+  }
+  return out;
+}
+
+const numFmt = new Intl.NumberFormat();
+
+export function formatTick(v: number): string {
+  if (Math.abs(v) >= 1000) return numFmt.format(v);
+  if (Number.isInteger(v)) return v.toString();
+  return v.toFixed(1);
+}
+
+/**
+ * Numeric input accepted by chart components. `number[]` and any standard
+ * numeric typed array are supported, so the output of
+ * `ModelOutput.column('x')` (e.g. a `Float64Array`) can be passed
+ * directly without copying.
+ */
+export type ChartData =
+  | readonly number[]
+  | Float64Array
+  | Float32Array
+  | Int32Array
+  | Uint32Array
+  | Int16Array
+  | Uint16Array
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray;

package/src/_shared/chartProps.ts

@@ -0,0 +1,201 @@
+/**
+ * Prop / slot / emit types shared by LineChart and BarChart. Component
+ * authors compose these with chart-specific props via TypeScript
+ * 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";
+
+/**
+ * Visual styling for the chart title. All fields optional; unspecified
+ * fields fall back to the chart's defaults (font-size 14, line-height 18,
+ * font-weight 600, currentColor, align "left"). `lineHeight` is in pixels
+ * and controls spacing between lines when the title contains `\n`.
+ */
+export interface TitleStyle {
+  fontSize?: number;
+  lineHeight?: number;
+  color?: string;
+  fontWeight?: number | string;
+  /** Horizontal alignment of the title. Default: `"left"`. */
+  align?: "left" | "center" | "right";
+}
+
+/**
+ * Visual styling for axis labels, tick labels, and legend text. Each
+ * field is optional; unspecified fields fall back to that element's
+ * default. When `color` is set, the default fill-opacity (used by tick
+ * labels) is dropped so the exact color is rendered.
+ */
+export interface LabelStyle {
+  fontSize?: number;
+  color?: string;
+  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
+ * component itself.
+ */
+export interface ChartCommonProps {
+  width?: number;
+  height?: number;
+  /**
+   * Chart title. `\n` in the string creates additional lines, each
+   * adding `titleStyle.lineHeight` (default 18px) of vertical space.
+   */
+  title?: string;
+  /** Styling for the chart title. See `TitleStyle`. */
+  titleStyle?: TitleStyle;
+  /**
+   * ARIA role for the chart's `<svg>`. Defaults to `"img"` when an accessible
+   * name is present (from `ariaLabel` or `title`), so screen readers announce
+   * the chart as a single labeled image instead of exposing the individual
+   * marks. The menu and download controls sit outside the `<svg>`, so they
+   * stay reachable regardless. Pass your own role to override.
+   */
+  role?: string;
+  /**
+   * Accessible name for the chart, announced by screen readers via the
+   * `<svg>`'s `aria-label`. Defaults to the `title` prop. The individual
+   * marks aren't exposed to assistive tech, so set this to a short summary of
+   * what the chart shows.
+   */
+  ariaLabel?: string;
+  /** Styling for axis labels (the `xLabel` / `yLabel` text). */
+  axisLabelStyle?: LabelStyle;
+  /** Styling for axis tick labels (the numbers/categories on each axis). */
+  tickLabelStyle?: LabelStyle;
+  /** Styling for the inline legend item labels. */
+  legendStyle?: LabelStyle;
+  xLabel?: string;
+  yLabel?: string;
+  debounce?: number;
+  menu?: boolean | string;
+  /**
+   * Custom per-index data forwarded to the `tooltip` slot. Accepts a
+   * plain array or any `ArrayLike` (e.g. a typed-array column).
+   */
+  tooltipData?: ArrayLike<unknown>;
+  /** Tooltip activation mode. */
+  tooltipTrigger?: "hover" | "click";
+  /** Boundary for tooltip flip/clamp. Default: `"window"`. */
+  tooltipClamp?: "none" | "chart" | "window";
+  /**
+   * 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?: NumberFormat;
+  /**
+   * Custom CSV content (string or function) for the Download CSV menu
+   * item. When omitted, CSV is generated from the chart's series.
+   */
+  csv?: string | (() => string);
+  /** Filename (without extension) for SVG, PNG, and CSV downloads. */
+  filename?: string;
+  /**
+   * Show a plain text link below the chart to download CSV. Pass `true`
+   * 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;
+  /**
+   * Where to teleport the chart while expanded (the Expand menu item). A
+   * CSS selector or element; defaults to `body`. The expanded chart is
+   * moved here so its `position: fixed` resolves against the viewport
+   * instead of being trapped by an ancestor's `transform`/`filter`/
+   * `contain`/`perspective` (which would otherwise become its containing
+   * block) or stacking context. Set this when your app doesn't mount at
+   * the document root (e.g. inside a shadow root or a dedicated overlay).
+   */
+  fullscreenTarget?: string | HTMLElement;
+  /** Annotations rendered as the top layer of the chart. */
+  annotations?: readonly ChartAnnotation[];
+  /**
+   * Extra padding (pixels) added around the plot. Number = same on all
+   * sides; object = per-side. Useful for giving annotations or other
+   * overlays room to extend past the data area without clipping.
+   */
+  chartPadding?: ChartPadding;
+}
+
+/** Payload emitted on `hover` from a cartesian chart. */
+export type ChartHoverPayload = { index: number } | null;
+
+/** One per-series value passed to the tooltip slot. */
+export interface ChartTooltipValue {
+  value: number;
+  color: string;
+  seriesIndex: number;
+}
+
+/** Properties common to every chart's tooltip slot. */
+export interface ChartTooltipBaseProps {
+  index: number;
+  values: ChartTooltipValue[];
+  data: unknown;
+}

package/src/_shared/computeTicks.ts

@@ -0,0 +1,42 @@
+import { intervalValues, niceStep } from "./axes.js";
+
+export interface TickValueOptions {
+  /** Data-space extent. */
+  min: number;
+  max: number;
+  /** Tick spec: number = interval, array = explicit values, undefined = auto. */
+  ticks?: number | number[];
+  /** Target tick count when auto-spacing (typically innerSize / 50 for y, /80 for x). */
+  targetTickCount?: number;
+  /**
+   * Display-space offset added to user-supplied explicit/interval values
+   * before they are interpreted. Used by LineChart's `xMin` semantics so
+   * users supply tick values in display coordinates.
+   */
+  displayOffset?: number;
+}
+
+/**
+ * Returns tick values in data-space ([min, max]) according to the spec.
+ * Display-space conversions (for labels) happen at the call site so
+ * each chart can layer its own formatting / fallback behavior.
+ */
+export function computeTickValues(opts: TickValueOptions): number[] {
+  const { min, max, ticks } = opts;
+  if (min === max) return [];
+  const offset = opts.displayOffset ?? 0;
+
+  if (Array.isArray(ticks)) {
+    return ticks.map((v) => v - offset).filter((v) => v >= min && v <= max);
+  }
+  if (typeof ticks === "number") {
+    return intervalValues(min + offset, max + offset, ticks).map(
+      (v) => v - offset,
+    );
+  }
+  const target = Math.max(3, Math.floor(opts.targetTickCount ?? 3));
+  const step = niceStep(max - min, target);
+  return intervalValues(min + offset, max + offset, step).map(
+    (v) => v - offset,
+  );
+}

package/src/_shared/contrast.ts

@@ -0,0 +1,100 @@
+/**
+ * Color helpers for picking a readable text color against a bar fill.
+ * The luminance math is pure and unit-testable; resolving CSS values
+ * that aren't plain hex/rgb (named colors, `var(--x)`) needs the DOM and
+ * is handled separately by {@link resolveColorToRgb}.
+ */
+
+export type Rgb = [number, number, number];
+
+/**
+ * Parse a hex (`#rgb`, `#rrggbb`, `#rrggbbaa`) or `rgb()/rgba()` string to
+ * `[r, g, b]` in 0..255. Returns null for anything else (named colors,
+ * `var(...)`, `hsl(...)`) — resolve those via {@link resolveColorToRgb}.
+ */
+export function parseRgb(color: string): Rgb | null {
+  const c = color.trim();
+  if (c.startsWith("#")) {
+    let hex = c.slice(1);
+    if (hex.length === 3 || hex.length === 4) {
+      hex = hex
+        .slice(0, 3)
+        .split("")
+        .map((ch) => ch + ch)
+        .join("");
+    } else if (hex.length === 6 || hex.length === 8) {
+      hex = hex.slice(0, 6);
+    } else {
+      return null;
+    }
+    const n = Number.parseInt(hex, 16);
+    if (Number.isNaN(n)) return null;
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+  }
+  const m = c.match(/^rgba?\(([^)]+)\)$/i);
+  if (m) {
+    const parts = m[1].split(/[,/\s]+/).filter(Boolean);
+    if (parts.length < 3) return null;
+    const rgb = parts.slice(0, 3).map((p) => {
+      if (p.endsWith("%")) return Math.round((parseFloat(p) / 100) * 255);
+      return Math.round(parseFloat(p));
+    });
+    if (rgb.some((v) => Number.isNaN(v))) return null;
+    return [rgb[0], rgb[1], rgb[2]];
+  }
+  return null;
+}
+
+/** WCAG relative luminance (0 = black, 1 = white) for an RGB triple. */
+export function relativeLuminance([r, g, b]: Rgb): number {
+  const channel = (v: number) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+let probe: HTMLSpanElement | null = null;
+const resolveCache = new Map<string, Rgb | null>();
+
+/**
+ * Resolve any CSS color string (including named colors and `var(--x)`) to
+ * an RGB triple by letting the browser compute it on a hidden probe
+ * element. Cached per input. Returns null in non-DOM environments or when
+ * the value can't be resolved. Plain hex/rgb shortcut through
+ * {@link parseRgb} without touching the DOM.
+ */
+export function resolveColorToRgb(color: string): Rgb | null {
+  const direct = parseRgb(color);
+  if (direct) return direct;
+  if (resolveCache.has(color)) return resolveCache.get(color) ?? null;
+  if (typeof document === "undefined") return null;
+  if (!probe) {
+    probe = document.createElement("span");
+    probe.style.cssText =
+      "position:absolute;width:0;height:0;visibility:hidden;pointer-events:none";
+    document.body.appendChild(probe);
+  }
+  probe.style.color = "";
+  probe.style.color = color;
+  const computed = getComputedStyle(probe).color;
+  const rgb = parseRgb(computed);
+  resolveCache.set(color, rgb);
+  return rgb;
+}
+
+/**
+ * Pick the more readable of `light`/`dark` text colors for a given fill.
+ * Uses the WCAG luminance threshold (0.179) that maximizes contrast
+ * against black-or-white text. When the fill can't be resolved (e.g. an
+ * unresolvable CSS var in a non-DOM context), falls back to `light`.
+ */
+export function pickContrastColor(
+  fill: string,
+  light = "#ffffff",
+  dark = "#1a1a1a",
+): string {
+  const rgb = resolveColorToRgb(fill);
+  if (!rgb) return light;
+  return relativeLuminance(rgb) > 0.179 ? dark : light;
+}