@cfasim-ui/docs 0.4.11 → 0.4.13

package/charts/_shared/dateAxis.ts

@@ -0,0 +1,507 @@
+/**
+ * Date axis support: parsing, auto-detection, tick selection, and
+ * formatting for chart x-axes that carry temporal data. All functions
+ * are pure (no Vue reactivity, no DOM); chart components call into this
+ * module from their computed setup.
+ *
+ * Design notes:
+ * - Parsing is regex-based, not `Date.parse`. The ES spec parses bare
+ *   `YYYY-MM-DD` as UTC but offset-less `YYYY-MM-DDTHH:mm:ss` as local,
+ *   which makes a `timezone` prop incoherent. Manual parsing keeps the
+ *   timezone interpretation consistent.
+ * - `isDateLike` deliberately rejects plain numbers so existing numeric
+ *   demos (generation indices, day counters) aren't misclassified.
+ * - Tick stepping for month/year (and day/week in local mode) goes
+ *   through `Date` field math so DST and month-length irregularities
+ *   don't drift the tick boundaries.
+ */
+
+export type DateTickUnit =
+  | "year"
+  | "month"
+  | "week"
+  | "day"
+  | "hour"
+  | "minute"
+  | "second";
+
+export type DateTimezone = "utc" | "local";
+
+export type DateFormatPreset =
+  | "iso"
+  | "iso-datetime"
+  | "year"
+  | "month-year"
+  | "month-day"
+  | "day"
+  | "time"
+  | "datetime"
+  | "medium";
+
+/**
+ * How to render a tick label on a date axis. Accepts:
+ * - A preset name (`"iso"`, `"month-year"`, ...).
+ * - An `Intl.DateTimeFormatOptions` literal for full control.
+ * - A function receiving the tick's epoch-ms and the tick unit the
+ *   chart picked. Useful for unit-aware custom formatting.
+ */
+export type DateFormat =
+  | DateFormatPreset
+  | Intl.DateTimeFormatOptions
+  | ((ms: number, unit?: DateTickUnit) => string);
+
+const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_DATETIME_RE =
+  /^(\d{4})-(\d{2})-(\d{2})[Tt ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:?\d{2})?$/;
+
+const MS_PER_SECOND = 1000;
+const MS_PER_MINUTE = 60 * MS_PER_SECOND;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+const MS_PER_WEEK = 7 * MS_PER_DAY;
+const MS_PER_MONTH_APPROX = 30 * MS_PER_DAY;
+const MS_PER_YEAR_APPROX = 365 * MS_PER_DAY;
+
+/**
+ * Candidate tick intervals sorted by ascending duration. `pickInterval`
+ * walks this list in order and returns the smallest entry whose `ms`
+ * is at least the rough per-tick duration the caller is targeting,
+ * giving at most ~`targetCount` ticks. Year step set is locked to
+ * `{1,2,5,10,25,50,100}` (no "3-year" step).
+ */
+interface TickInterval {
+  unit: DateTickUnit;
+  step: number;
+  ms: number;
+}
+const TICK_INTERVALS: readonly TickInterval[] = [
+  { unit: "second", step: 1, ms: 1 * MS_PER_SECOND },
+  { unit: "second", step: 5, ms: 5 * MS_PER_SECOND },
+  { unit: "second", step: 15, ms: 15 * MS_PER_SECOND },
+  { unit: "second", step: 30, ms: 30 * MS_PER_SECOND },
+  { unit: "minute", step: 1, ms: 1 * MS_PER_MINUTE },
+  { unit: "minute", step: 5, ms: 5 * MS_PER_MINUTE },
+  { unit: "minute", step: 15, ms: 15 * MS_PER_MINUTE },
+  { unit: "minute", step: 30, ms: 30 * MS_PER_MINUTE },
+  { unit: "hour", step: 1, ms: 1 * MS_PER_HOUR },
+  { unit: "hour", step: 3, ms: 3 * MS_PER_HOUR },
+  { unit: "hour", step: 6, ms: 6 * MS_PER_HOUR },
+  { unit: "hour", step: 12, ms: 12 * MS_PER_HOUR },
+  { unit: "day", step: 1, ms: 1 * MS_PER_DAY },
+  { unit: "day", step: 2, ms: 2 * MS_PER_DAY },
+  { unit: "week", step: 1, ms: 1 * MS_PER_WEEK },
+  { unit: "month", step: 1, ms: 1 * MS_PER_MONTH_APPROX },
+  { unit: "month", step: 3, ms: 3 * MS_PER_MONTH_APPROX },
+  { unit: "month", step: 6, ms: 6 * MS_PER_MONTH_APPROX },
+  { unit: "year", step: 1, ms: 1 * MS_PER_YEAR_APPROX },
+  { unit: "year", step: 2, ms: 2 * MS_PER_YEAR_APPROX },
+  { unit: "year", step: 5, ms: 5 * MS_PER_YEAR_APPROX },
+  { unit: "year", step: 10, ms: 10 * MS_PER_YEAR_APPROX },
+  { unit: "year", step: 25, ms: 25 * MS_PER_YEAR_APPROX },
+  { unit: "year", step: 50, ms: 50 * MS_PER_YEAR_APPROX },
+  { unit: "year", step: 100, ms: 100 * MS_PER_YEAR_APPROX },
+];
+
+const MAX_TICK_ITER = 1000;
+
+/**
+ * Parse `v` into an epoch-ms timestamp under the given timezone.
+ * Accepts `Date` instances and ISO-shaped strings; returns `null` for
+ * anything else (including plain `number`s — see `isDateLike`).
+ */
+export function parseDate(v: unknown, tz: DateTimezone): number | null {
+  if (v instanceof Date) {
+    const t = v.getTime();
+    return Number.isFinite(t) ? t : null;
+  }
+  if (typeof v !== "string") return null;
+
+  const dm = ISO_DATE_RE.exec(v);
+  if (dm) {
+    const y = +dm[1];
+    const mo = +dm[2] - 1;
+    const d = +dm[3];
+    if (tz === "utc") return Date.UTC(y, mo, d);
+    return new Date(y, mo, d).getTime();
+  }
+
+  const tm = ISO_DATETIME_RE.exec(v);
+  if (tm) {
+    const y = +tm[1];
+    const mo = +tm[2] - 1;
+    const d = +tm[3];
+    const h = +tm[4];
+    const mi = +tm[5];
+    const se = tm[6] ? +tm[6] : 0;
+    // Regex caps the fractional-second group at 3 digits, so this is
+    // always 0..999.
+    const ms = tm[7] ? Number("0." + tm[7]) * 1000 : 0;
+    const offset = tm[8];
+    if (offset) {
+      // Explicit offset overrides the prop's tz interpretation.
+      if (offset === "Z" || offset === "z") {
+        return Date.UTC(y, mo, d, h, mi, se, ms);
+      }
+      const sign = offset[0] === "+" ? 1 : -1;
+      const offHour = +offset.slice(1, 3);
+      const offMin = +offset.slice(-2);
+      const offsetMs = sign * (offHour * 60 + offMin) * MS_PER_MINUTE;
+      return Date.UTC(y, mo, d, h, mi, se, ms) - offsetMs;
+    }
+    if (tz === "utc") return Date.UTC(y, mo, d, h, mi, se, ms);
+    return new Date(y, mo, d, h, mi, se, ms).getTime();
+  }
+
+  return null;
+}
+
+/**
+ * Whether `v` looks like a date value to the auto-detector. Strict:
+ * `Date` instances or ISO-shaped strings only. Plain numbers are *not*
+ * considered date-like so numeric demos can't be silently promoted to
+ * a date axis.
+ */
+export function isDateLike(v: unknown): boolean {
+  if (v instanceof Date) return Number.isFinite(v.getTime());
+  if (typeof v !== "string") return false;
+  return ISO_DATE_RE.test(v) || ISO_DATETIME_RE.test(v);
+}
+
+/**
+ * Whether every entry of `values` is date-like and parses cleanly. An
+ * empty array is *not* considered all-dates (auto-detection should
+ * stay opt-in by content).
+ */
+export function isAllDates(
+  values: ArrayLike<unknown>,
+  tz: DateTimezone,
+): boolean {
+  if (values.length === 0) return false;
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i];
+    if (!isDateLike(v)) return false;
+    if (parseDate(v, tz) === null) return false;
+  }
+  return true;
+}
+
+/**
+ * Pick the smallest tick interval whose duration is at least the rough
+ * per-tick budget (`span / targetCount`). Guarantees at most
+ * ~`targetCount` ticks.
+ */
+function chooseInterval(spanMs: number, targetCount: number): TickInterval {
+  const rough = spanMs / Math.max(1, targetCount);
+  for (const candidate of TICK_INTERVALS) {
+    if (rough <= candidate.ms) return candidate;
+  }
+  return TICK_INTERVALS[TICK_INTERVALS.length - 1];
+}
+
+function snapToUnit(ms: number, unit: DateTickUnit, tz: DateTimezone): number {
+  const d = new Date(ms);
+  if (tz === "utc") {
+    switch (unit) {
+      case "second":
+        return Math.floor(ms / MS_PER_SECOND) * MS_PER_SECOND;
+      case "minute":
+        return Math.floor(ms / MS_PER_MINUTE) * MS_PER_MINUTE;
+      case "hour":
+        return Math.floor(ms / MS_PER_HOUR) * MS_PER_HOUR;
+      case "day":
+        return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+      case "week": {
+        // ISO 8601 week starts Monday. JS day: Sun=0..Sat=6.
+        const dayIndex = d.getUTCDay();
+        const daysSinceMonday = (dayIndex + 6) % 7;
+        return Date.UTC(
+          d.getUTCFullYear(),
+          d.getUTCMonth(),
+          d.getUTCDate() - daysSinceMonday,
+        );
+      }
+      case "month":
+        return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
+      case "year":
+        return Date.UTC(d.getUTCFullYear(), 0, 1);
+    }
+  }
+  switch (unit) {
+    case "second":
+      return Math.floor(ms / MS_PER_SECOND) * MS_PER_SECOND;
+    case "minute":
+      return Math.floor(ms / MS_PER_MINUTE) * MS_PER_MINUTE;
+    case "hour":
+      return new Date(
+        d.getFullYear(),
+        d.getMonth(),
+        d.getDate(),
+        d.getHours(),
+      ).getTime();
+    case "day":
+      return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+    case "week": {
+      const dayIndex = d.getDay();
+      const daysSinceMonday = (dayIndex + 6) % 7;
+      return new Date(
+        d.getFullYear(),
+        d.getMonth(),
+        d.getDate() - daysSinceMonday,
+      ).getTime();
+    }
+    case "month":
+      return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+    case "year":
+      return new Date(d.getFullYear(), 0, 1).getTime();
+  }
+}
+
+function addUnit(
+  ms: number,
+  unit: DateTickUnit,
+  step: number,
+  tz: DateTimezone,
+): number {
+  if (unit === "second") return ms + step * MS_PER_SECOND;
+  if (unit === "minute") return ms + step * MS_PER_MINUTE;
+  if (unit === "hour" && tz === "utc") return ms + step * MS_PER_HOUR;
+  if (unit === "week" && tz === "utc") return ms + step * MS_PER_WEEK;
+
+  const d = new Date(ms);
+  if (tz === "utc") {
+    switch (unit) {
+      case "day":
+        return Date.UTC(
+          d.getUTCFullYear(),
+          d.getUTCMonth(),
+          d.getUTCDate() + step,
+          d.getUTCHours(),
+          d.getUTCMinutes(),
+          d.getUTCSeconds(),
+          d.getUTCMilliseconds(),
+        );
+      case "month":
+        return Date.UTC(
+          d.getUTCFullYear(),
+          d.getUTCMonth() + step,
+          d.getUTCDate(),
+          d.getUTCHours(),
+          d.getUTCMinutes(),
+          d.getUTCSeconds(),
+          d.getUTCMilliseconds(),
+        );
+      case "year":
+        return Date.UTC(
+          d.getUTCFullYear() + step,
+          d.getUTCMonth(),
+          d.getUTCDate(),
+          d.getUTCHours(),
+          d.getUTCMinutes(),
+          d.getUTCSeconds(),
+          d.getUTCMilliseconds(),
+        );
+    }
+  }
+  // Local mode: Date field math handles DST and month length.
+  switch (unit) {
+    case "hour":
+      return new Date(
+        d.getFullYear(),
+        d.getMonth(),
+        d.getDate(),
+        d.getHours() + step,
+        d.getMinutes(),
+        d.getSeconds(),
+        d.getMilliseconds(),
+      ).getTime();
+    case "day":
+      return new Date(
+        d.getFullYear(),
+        d.getMonth(),
+        d.getDate() + step,
+        d.getHours(),
+        d.getMinutes(),
+        d.getSeconds(),
+        d.getMilliseconds(),
+      ).getTime();
+    case "week":
+      return new Date(
+        d.getFullYear(),
+        d.getMonth(),
+        d.getDate() + step * 7,
+        d.getHours(),
+        d.getMinutes(),
+        d.getSeconds(),
+        d.getMilliseconds(),
+      ).getTime();
+    case "month":
+      return new Date(
+        d.getFullYear(),
+        d.getMonth() + step,
+        d.getDate(),
+        d.getHours(),
+        d.getMinutes(),
+        d.getSeconds(),
+        d.getMilliseconds(),
+      ).getTime();
+    case "year":
+      return new Date(
+        d.getFullYear() + step,
+        d.getMonth(),
+        d.getDate(),
+        d.getHours(),
+        d.getMinutes(),
+        d.getSeconds(),
+        d.getMilliseconds(),
+      ).getTime();
+  }
+  // Unreachable — the early returns above cover second/minute/hour-utc/week-utc.
+  return ms;
+}
+
+/**
+ * Choose tick values for a date axis spanning `[minMs, maxMs]`. The
+ * returned `unit` lets the default formatter pick a unit-appropriate
+ * preset (year ticks → "year", month → "month-year", day → "month-day",
+ * etc.) — same trick Vega-Lite uses.
+ */
+export function pickDateTicks(
+  minMs: number,
+  maxMs: number,
+  targetCount: number,
+  tz: DateTimezone,
+): { values: number[]; unit: DateTickUnit } {
+  if (
+    !Number.isFinite(minMs) ||
+    !Number.isFinite(maxMs) ||
+    minMs >= maxMs ||
+    targetCount < 1
+  ) {
+    return { values: [], unit: "day" };
+  }
+  const span = maxMs - minMs;
+  const { unit, step } = chooseInterval(span, targetCount);
+
+  let v = snapToUnit(minMs, unit, tz);
+  let safety = 0;
+  while (v < minMs && safety < MAX_TICK_ITER) {
+    v = addUnit(v, unit, step, tz);
+    safety++;
+  }
+
+  const values: number[] = [];
+  for (let i = 0; i < MAX_TICK_ITER && v <= maxMs; i++) {
+    values.push(v);
+    v = addUnit(v, unit, step, tz);
+  }
+  return { values, unit };
+}
+
+const PRESET_OPTIONS: Record<DateFormatPreset, Intl.DateTimeFormatOptions> = {
+  // "iso" and "iso-datetime" route through manual formatters below so
+  // the output stays exactly YYYY-MM-DD regardless of locale.
+  iso: { year: "numeric", month: "2-digit", day: "2-digit" },
+  "iso-datetime": {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hourCycle: "h23",
+  },
+  year: { year: "numeric" },
+  "month-year": { month: "short", year: "numeric" },
+  "month-day": { month: "short", day: "numeric" },
+  day: { day: "numeric" },
+  time: { hour: "2-digit", minute: "2-digit", hourCycle: "h23" },
+  datetime: {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+  },
+  medium: { dateStyle: "medium" } as Intl.DateTimeFormatOptions,
+};
+
+const UNIT_DEFAULT_PRESET: Record<DateTickUnit, DateFormatPreset> = {
+  year: "year",
+  month: "month-year",
+  week: "month-day",
+  day: "month-day",
+  hour: "time",
+  minute: "time",
+  second: "time",
+};
+
+/** All valid preset names. Exported for the disjointness invariant test. */
+export const DATE_FORMAT_PRESETS = Object.keys(
+  PRESET_OPTIONS,
+) as readonly DateFormatPreset[];
+
+function pad2(n: number): string {
+  return n < 10 ? "0" + n : String(n);
+}
+
+function formatIso(ms: number, tz: DateTimezone): string {
+  const d = new Date(ms);
+  if (tz === "utc") {
+    return `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+  }
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+function formatIsoDateTime(ms: number, tz: DateTimezone): string {
+  const d = new Date(ms);
+  if (tz === "utc") {
+    return (
+      `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}` +
+      `T${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}:${pad2(d.getUTCSeconds())}Z`
+    );
+  }
+  return (
+    `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}` +
+    `T${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`
+  );
+}
+
+function isPreset(name: string): name is DateFormatPreset {
+  return name in PRESET_OPTIONS;
+}
+
+/**
+ * Format an epoch-ms timestamp into a tick label. When `format` is
+ * undefined, picks a preset based on the tick `unit` (Vega-Lite style:
+ * year ticks read as "2024", month ticks as "Jan 2024", etc.).
+ */
+export function formatDate(
+  ms: number,
+  format: DateFormat | undefined,
+  tz: DateTimezone,
+  unit?: DateTickUnit,
+): string {
+  if (typeof format === "function") return format(ms, unit);
+
+  let presetName: DateFormatPreset | null = null;
+  let options: Intl.DateTimeFormatOptions;
+  if (format === undefined) {
+    presetName = unit ? UNIT_DEFAULT_PRESET[unit] : "iso";
+    options = PRESET_OPTIONS[presetName];
+  } else if (typeof format === "string") {
+    if (!isPreset(format)) {
+      throw new Error(`Unknown date format preset: "${format}"`);
+    }
+    presetName = format;
+    options = PRESET_OPTIONS[presetName];
+  } else {
+    options = format;
+  }
+
+  if (presetName === "iso") return formatIso(ms, tz);
+  if (presetName === "iso-datetime") return formatIsoDateTime(ms, tz);
+
+  const finalOpts: Intl.DateTimeFormatOptions =
+    tz === "utc" ? { ...options, timeZone: "UTC" } : options;
+  return new Intl.DateTimeFormat(undefined, finalOpts).format(ms);
+}

package/charts/_shared/index.ts

@@ -16,7 +16,15 @@ export {
 export { useChartSize, type ChartSizeOptions } from "./useChartSize.js";
 export {
   useChartPadding,
+  resolveLabelStyle,
   INLINE_LEGEND_ROW_HEIGHT,
+  TITLE_LINE_HEIGHT,
+  TITLE_FONT_SIZE,
+  TITLE_FONT_WEIGHT,
+  AXIS_LABEL_FONT_SIZE,
+  TICK_LABEL_FONT_SIZE,
+  TICK_LABEL_OPACITY,
+  LEGEND_FONT_SIZE,
   type ChartPaddingOptions,
   type ChartPadding,
   type ChartBounds,
@@ -41,4 +49,18 @@ export type {
   ChartHoverPayload,
   ChartTooltipValue,
   ChartTooltipBaseProps,
+  TitleStyle,
+  LabelStyle,
 } from "./chartProps.js";
+export {
+  parseDate,
+  isDateLike,
+  isAllDates,
+  pickDateTicks,
+  formatDate,
+  DATE_FORMAT_PRESETS,
+  type DateFormat,
+  type DateFormatPreset,
+  type DateTickUnit,
+  type DateTimezone,
+} from "./dateAxis.js";

package/charts/_shared/useChartFoundation.ts

@@ -6,6 +6,7 @@ import { useChartPadding, type ChartPadding } from "./useChartPadding.js";
 import { useChartTooltip } from "./useChartTooltip.js";
 import type { TooltipClamp } from "../tooltip-position.js";
 import { useChartMenu } from "./useChartMenu.js";
+import type { TitleStyle } from "./chartProps.js";
 
 const DEFAULT_WIDTH_FALLBACK = 400;
 const DEFAULT_HEIGHT = 200;
@@ -15,6 +16,7 @@ export interface ChartFoundationOptions {
   width: () => number | undefined;
   height: () => number | undefined;
   title: () => string | undefined;
+  titleStyle: () => TitleStyle | undefined;
   xLabel: () => string | undefined;
   yLabel: () => string | undefined;
   debounce: () => number | undefined;
@@ -87,6 +89,7 @@ export function useChartFoundation(opts: ChartFoundationOptions) {
   const { padding, legendY, inlineLegendLayout, innerW, innerH, bounds } =
     useChartPadding({
       title: opts.title,
+      titleStyle: opts.titleStyle,
       xLabel: opts.xLabel,
       yLabel: opts.yLabel,
       inlineLegendLabels: opts.inlineLegendLabels,

package/charts/_shared/useChartPadding.ts

@@ -1,7 +1,46 @@
 import { computed } from "vue";
+import type { LabelStyle, TitleStyle } from "./chartProps.js";
 
 /** Vertical space reserved per row of the inline legend strip. */
 export const INLINE_LEGEND_ROW_HEIGHT = 20;
+/** Default line height (px) for the chart title; overridable per chart. */
+export const TITLE_LINE_HEIGHT = 18;
+/** Default font size (px) for the chart title; overridable per chart. */
+export const TITLE_FONT_SIZE = 14;
+/** Default font weight for the chart title; overridable per chart. */
+export const TITLE_FONT_WEIGHT: number | string = 600;
+/** Default font size (px) for axis labels (`xLabel` / `yLabel`). */
+export const AXIS_LABEL_FONT_SIZE = 13;
+/** Default font size (px) for axis tick labels (the numbers on each axis). */
+export const TICK_LABEL_FONT_SIZE = 10;
+/** Default fill-opacity for tick labels when no custom color is set. */
+export const TICK_LABEL_OPACITY = 0.6;
+/** Default font size (px) for inline legend item labels. */
+export const LEGEND_FONT_SIZE = 11;
+/** Vertical space below the title's last baseline before the next element. */
+const TITLE_BOTTOM_GAP = 8;
+
+/**
+ * Resolve a `LabelStyle` against per-element defaults. Returns the
+ * fields the chart's `<text>` element needs. When `style.color` is set,
+ * the default fill-opacity is dropped so the exact color renders.
+ */
+export function resolveLabelStyle(
+  style: LabelStyle | undefined,
+  defaults: { fontSize: number; fillOpacity?: number },
+): {
+  fontSize: number;
+  fill: string;
+  fontWeight: number | string | undefined;
+  fillOpacity: number | undefined;
+} {
+  return {
+    fontSize: style?.fontSize ?? defaults.fontSize,
+    fill: style?.color ?? "currentColor",
+    fontWeight: style?.fontWeight,
+    fillOpacity: style?.color != null ? undefined : defaults.fillOpacity,
+  };
+}
 /**
  * Estimated character width at font-size 11 used by inline-legend
  * measurement. Matches the value used by LineChart's area-section labels
@@ -30,6 +69,7 @@ export type ChartPadding =
 
 export interface ChartPaddingOptions {
   title: () => string | undefined;
+  titleStyle?: () => TitleStyle | undefined;
   xLabel: () => string | undefined;
   yLabel: () => string | undefined;
   /**
@@ -128,14 +168,22 @@ export function useChartPadding(opts: ChartPaddingOptions) {
     return { positions, rowCount: row + 1 };
   });
 
+  // Title height in px. `\n` in the title creates additional lines, each
+  // adding `titleStyle.lineHeight` (default 18). When there is no title,
+  // reserve a small top margin so the plot doesn't hug the top edge.
+  const titleHeight = computed(() => {
+    const t = opts.title();
+    if (!t) return 10;
+    const lineHeight = opts.titleStyle?.()?.lineHeight ?? TITLE_LINE_HEIGHT;
+    const lineCount = t.split("\n").length;
+    return lineCount * lineHeight + TITLE_BOTTOM_GAP;
+  });
+
   const padding = computed(() => {
     const extra = resolvePadding(opts.extraPadding?.());
     const rowCount = inlineLegendLayout.value.rowCount;
     return {
-      top:
-        (opts.title() ? 26 : 10) +
-        rowCount * INLINE_LEGEND_ROW_HEIGHT +
-        extra.top,
+      top: titleHeight.value + rowCount * INLINE_LEGEND_ROW_HEIGHT + extra.top,
       bottom: (opts.xLabel() ? 38 : 30) + extra.bottom,
       left: horizontalPadding.value.left,
       right: horizontalPadding.value.right,
@@ -147,7 +195,7 @@ export function useChartPadding(opts: ChartPaddingOptions) {
   // `extraPadding.top` becomes empty room between the legend and the
   // plot. Subsequent rows are offset by `INLINE_LEGEND_ROW_HEIGHT`.
   const legendY = computed(
-    () => (opts.title() ? 26 : 10) + INLINE_LEGEND_ROW_HEIGHT / 2,
+    () => titleHeight.value + INLINE_LEGEND_ROW_HEIGHT / 2,
   );
 
   const innerH = computed(

package/charts/hsa-mapping.ts

@@ -0,0 +1 @@
+export { fipsToHsa, hsaNames } from "./ChoroplethMap/hsaMapping.js";

package/charts/index.ts

@@ -23,7 +23,6 @@ export {
   type FocusValue,
   type FocusStyle,
 } from "./ChoroplethMap/ChoroplethMap.vue";
-export { fipsToHsa, hsaNames } from "./ChoroplethMap/hsaMapping.js";
 export { default as ChartTooltip } from "./ChartTooltip/ChartTooltip.vue";
 export {
   default as DataTable,

package/index.json

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

package/package.json

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

package/shared/index.ts

@@ -22,5 +22,10 @@ export {
   deserialize,
   paramsToQuery,
   queryToParams,
+  jsonCodec,
+} from "./useUrlParams.js";
+export type {
+  UrlParamsOptions,
+  ParamCodec,
+  ParamCodecs,
 } from "./useUrlParams.js";
-export type { UrlParamsOptions } from "./useUrlParams.js";