@cfasim-ui/docs 0.4.11 → 0.4.12

package/charts/BarChart/BarChart.md

@@ -160,6 +160,54 @@ Use `value-tick-format` to format the value-axis labels. `tooltip-value-format`
   </template>
 </ComponentDemo>
 
+### Date categories
+
+When every entry of `categories` parses as a date (`YYYY-MM-DD` string
+or `Date` instance), labels switch to date-aware formatting and the
+chart thins them to clean date boundaries (week / month / year
+depending on range). Bar positions stay ordinal — every category gets
+a bar — only the labels are thinned.
+
+<ComponentDemo>
+  <BarChart
+    :data="[12, 18, 24, 35, 41, 38, 29, 21, 14, 9, 7, 4]"
+    :categories="['2026-01-05','2026-01-12','2026-01-19','2026-01-26','2026-02-02','2026-02-09','2026-02-16','2026-02-23','2026-03-02','2026-03-09','2026-03-16','2026-03-23']"
+    :height="220"
+    y-label="% ED visits"
+  />
+
+<template #code>
+
+```vue
+<BarChart
+  :data="[12, 18, 24, 35, 41, 38, 29, 21, 14, 9, 7, 4]"
+  :categories="[
+    '2026-01-05',
+    '2026-01-12',
+    '2026-01-19',
+    '2026-01-26',
+    '2026-02-02',
+    '2026-02-09',
+    '2026-02-16',
+    '2026-02-23',
+    '2026-03-02',
+    '2026-03-09',
+    '2026-03-16',
+    '2026-03-23',
+  ]"
+  :height="220"
+  y-label="% ED visits"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Use `date-format` to override the auto-picked preset. Same values as
+LineChart's `x-tick-format` (e.g. `"iso"`, `"month-year"`, an
+`Intl.DateTimeFormatOptions` object, or a `(ms, unit?) => string`
+function).
+
 ### Logarithmic value axis
 
 Set `value-scale-type="log"` to switch the value axis to base-10 log
@@ -313,6 +361,10 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
 | `width` | `number` | No | — |
 | `height` | `number` | No | — |
 | `title` | `string` | No | — |
+| `titleStyle` | `TitleStyle` | No | — |
+| `axisLabelStyle` | `LabelStyle` | No | — |
+| `tickLabelStyle` | `LabelStyle` | No | — |
+| `legendStyle` | `LabelStyle` | No | — |
 | `xLabel` | `string` | No | — |
 | `yLabel` | `string` | No | — |
 | `debounce` | `number` | No | — |
@@ -329,7 +381,7 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
 | `data` | `BarChartData` | No | — |
 | `y` | `BarChartData` | No | — |
 | `series` | `BarSeries[]` | No | — |
-| `categories` | `readonly string[]` | No | — |
+| `categories` | `readonly (string \| Date)[]` | No | — |
 | `orientation` | `"vertical" \| "horizontal"` | No | `"vertical"` |
 | `layout` | `"grouped" \| "stacked"` | No | `"grouped"` |
 | `valueMin` | `number` | No | `0` |
@@ -337,6 +389,7 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
 | `valueTicks` | `number \| number[]` | No | — |
 | `valueTickFormat` | `NumberFormat` | No | — |
 | `categoryFormat` | `(label: string, index: number) =&gt; string` | No | — |
+| `dateFormat` | `DateFormat` | No | — |
 | `barPadding` | `number` | No | `0.2` |
 | `groupGap` | `number` | No | `1` |
 | `valueGrid` | `boolean` | No | `true` |

package/charts/BarChart/BarChart.vue

@@ -14,7 +14,20 @@ import {
   makeTooltipValueFormatter,
   ChartAnnotations,
   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,
+  resolveLabelStyle,
+  parseDate,
+  isAllDates,
+  pickDateTicks,
+  formatDate,
   type ChartData,
+  type DateFormat,
   type ChartCommonProps,
   type ChartHoverPayload,
   type ChartTooltipBaseProps,
@@ -53,8 +66,11 @@ interface BarChartProps extends ChartCommonProps {
   /**
    * Category labels for the categorical axis. Length should match the
    * longest series. When omitted, indices (0, 1, 2, ...) are used.
+   * Accepts date strings or `Date` objects: when every category parses
+   * as a date, label formatting switches to date mode (bar positions
+   * stay ordinal — they are not time-proportional).
    */
-  categories?: readonly string[];
+  categories?: readonly (string | Date)[];
   /** "vertical" (default, aka column) draws upright bars; "horizontal" draws sideways. */
   orientation?: "vertical" | "horizontal";
   /** "grouped" (default) places series side-by-side; "stacked" stacks them. */
@@ -83,6 +99,16 @@ interface BarChartProps extends ChartCommonProps {
   valueTickFormat?: NumberFormat;
   /** Formatter for category-axis labels. Receives the resolved category string. */
   categoryFormat?: (label: string, index: number) => string;
+  /**
+   * Date-tick formatter for date-mode category labels (auto-detected
+   * when every entry of `categories` parses as a date). Ignored unless
+   * the axis is in date mode. Accepts a `DateFormat` — preset name,
+   * `Intl.DateTimeFormatOptions`, or `(ms, unit?) => string`. When
+   * omitted, the formatter is picked from the chosen tick unit (e.g.
+   * monthly ticks → `"month-year"`). Has no effect when
+   * `categoryFormat` is also set.
+   */
+  dateFormat?: DateFormat;
   /**
    * Fraction of each category slot reserved as gap between groups (0..1).
    * Default 0.2 — i.e. bars/groups fill 80% of their slot.
@@ -158,11 +184,34 @@ const categoryLabels = computed<string[]>(() => {
   const n = categoryCount.value;
   const labels = new Array<string>(n);
   for (let i = 0; i < n; i++) {
-    labels[i] = props.categories?.[i] ?? String(i);
+    const c = props.categories?.[i];
+    if (c instanceof Date) {
+      // Stable string form for CSV / tooltip. Date axis formatting
+      // (visible labels) goes through `categoryTickItems` separately.
+      labels[i] = c.toISOString().slice(0, 10);
+    } else {
+      labels[i] = c ?? String(i);
+    }
   }
   return labels;
 });
 
+/**
+ * Parallel array of epoch-ms timestamps when every category parses as
+ * a date, otherwise `null`. Drives both date-aware tick thinning and
+ * the default tick label formatter.
+ */
+const categoryDatesMs = computed<number[] | null>(() => {
+  const cats = props.categories;
+  if (!cats || cats.length === 0) return null;
+  if (!isAllDates(cats, "utc")) return null;
+  const out = new Array<number>(cats.length);
+  for (let i = 0; i < cats.length; i++) {
+    out[i] = parseDate(cats[i], "utc") ?? NaN;
+  }
+  return out;
+});
+
 const isVertical = computed(() => props.orientation === "vertical");
 
 /** Extent of the value axis (across all series, accounting for stacking). */
@@ -453,8 +502,49 @@ interface CategoryTickItem {
 }
 
 const categoryTickItems = computed<CategoryTickItem[]>(() => {
-  const out: CategoryTickItem[] = [];
   const n = categoryCount.value;
+  const dateMs = categoryDatesMs.value;
+
+  // Date mode: thin labels to the closest category index for each
+  // tick boundary picked by `pickDateTicks`. Bar positions stay
+  // ordinal — only the labels become date-aware.
+  if (dateMs && dateMs.length > 0) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const m of dateMs) {
+      if (!Number.isFinite(m)) continue;
+      if (m < min) min = m;
+      if (m > max) max = m;
+    }
+    if (!Number.isFinite(min) || min === max) return [];
+    const span = isVertical.value ? innerW.value : innerH.value;
+    const target = Math.max(2, Math.floor(span / 80));
+    const picked = pickDateTicks(min, max, target, "utc");
+    const unit = picked.unit;
+    const items: CategoryTickItem[] = [];
+    const seen = new Set<number>();
+    for (const tickMs of picked.values) {
+      let nearest = -1;
+      let best = Infinity;
+      for (let i = 0; i < dateMs.length; i++) {
+        const d = Math.abs(dateMs[i] - tickMs);
+        if (d < best) {
+          best = d;
+          nearest = i;
+        }
+      }
+      if (nearest < 0 || seen.has(nearest)) continue;
+      seen.add(nearest);
+      const center = slotStart(nearest) + slotSize.value / 2;
+      const label = props.categoryFormat
+        ? props.categoryFormat(categoryLabels.value[nearest], nearest)
+        : formatDate(dateMs[nearest], props.dateFormat, "utc", unit);
+      items.push({ label, pos: center, anchor: "middle" });
+    }
+    return items;
+  }
+
+  const out: CategoryTickItem[] = [];
   const fmt = (label: string, i: number) =>
     props.categoryFormat ? props.categoryFormat(label, i) : label;
   for (let i = 0; i < n; i++) {
@@ -549,6 +639,7 @@ const {
   width: () => props.width,
   height: () => props.height,
   title: () => props.title,
+  titleStyle: () => props.titleStyle,
   xLabel: () => props.xLabel,
   yLabel: () => props.yLabel,
   debounce: () => props.debounce,
@@ -565,9 +656,56 @@ const {
   onHover: (payload) => emit("hover", payload),
 });
 
+/** Resolved style for the x/y axis labels. */
+const axisLabelResolved = computed(() =>
+  resolveLabelStyle(props.axisLabelStyle, { fontSize: AXIS_LABEL_FONT_SIZE }),
+);
+/** Resolved style for the axis tick labels. */
+const tickLabelResolved = computed(() =>
+  resolveLabelStyle(props.tickLabelStyle, {
+    fontSize: TICK_LABEL_FONT_SIZE,
+    fillOpacity: TICK_LABEL_OPACITY,
+  }),
+);
+/** Resolved style for inline legend item labels. */
+const legendResolved = computed(() =>
+  resolveLabelStyle(props.legendStyle, { fontSize: LEGEND_FONT_SIZE }),
+);
+
+/** Resolved title style with defaults applied. */
+const titleResolved = computed(() => {
+  const s = props.titleStyle;
+  const align = s?.align ?? "left";
+  const b = bounds.value;
+  const x =
+    align === "left"
+      ? b.left
+      : align === "right"
+        ? b.right
+        : b.left + b.width / 2;
+  const anchor =
+    align === "left" ? "start" : align === "right" ? "end" : "middle";
+  return {
+    lines: (props.title ?? "").split("\n"),
+    fontSize: s?.fontSize ?? TITLE_FONT_SIZE,
+    lineHeight: s?.lineHeight ?? TITLE_LINE_HEIGHT,
+    fontWeight: s?.fontWeight ?? TITLE_FONT_WEIGHT,
+    color: s?.color ?? "currentColor",
+    x,
+    anchor,
+  };
+});
+
 const hoveredCategoryLabel = computed(() => {
   const i = hoverIndex.value;
   if (i === null) return undefined;
+  // In date mode, format the tooltip label so it honors `dateFormat`
+  // (otherwise the user would see the raw ISO string while the ticks
+  // render with a nicer preset).
+  const dateMs = categoryDatesMs.value;
+  if (dateMs && Number.isFinite(dateMs[i])) {
+    return formatDate(dateMs[i], props.dateFormat, "utc");
+  }
   return categoryLabels.value[i];
 });
 
@@ -647,14 +785,21 @@ const positionedLegendItems = computed(() => {
       <!-- title -->
       <text
         v-if="title"
-        :x="width / 2"
-        :y="18"
-        text-anchor="middle"
-        font-size="14"
-        font-weight="600"
-        fill="currentColor"
+        :x="titleResolved.x"
+        :y="titleResolved.lineHeight"
+        :text-anchor="titleResolved.anchor"
+        :font-size="titleResolved.fontSize"
+        :font-weight="titleResolved.fontWeight"
+        :fill="titleResolved.color"
       >
-        {{ title }}
+        <tspan
+          v-for="(line, i) in titleResolved.lines"
+          :key="i"
+          :x="titleResolved.x"
+          :dy="i === 0 ? 0 : titleResolved.lineHeight"
+        >
+          {{ line }}
+        </tspan>
       </text>
       <!-- inline legend -->
       <g v-if="positionedLegendItems.length > 0">
@@ -669,8 +814,9 @@ const positionedLegendItems = computed(() => {
           <text
             :x="item.x + 18"
             :y="item.y + 4"
-            font-size="11"
-            fill="currentColor"
+            :font-size="legendResolved.fontSize"
+            :fill="legendResolved.fill"
+            :font-weight="legendResolved.fontWeight"
           >
             {{ item.label }}
           </text>
@@ -727,9 +873,10 @@ const positionedLegendItems = computed(() => {
           :y="tick.pos"
           text-anchor="end"
           dominant-baseline="middle"
-          font-size="10"
-          fill="currentColor"
-          fill-opacity="0.6"
+          :font-size="tickLabelResolved.fontSize"
+          :fill="tickLabelResolved.fill"
+          :font-weight="tickLabelResolved.fontWeight"
+          :fill-opacity="tickLabelResolved.fillOpacity"
         >
           {{ tick.value }}
         </text>
@@ -742,9 +889,10 @@ const positionedLegendItems = computed(() => {
           :x="tick.pos"
           :y="padding.top + innerH + 16"
           text-anchor="middle"
-          font-size="10"
-          fill="currentColor"
-          fill-opacity="0.6"
+          :font-size="tickLabelResolved.fontSize"
+          :fill="tickLabelResolved.fill"
+          :font-weight="tickLabelResolved.fontWeight"
+          :fill-opacity="tickLabelResolved.fillOpacity"
         >
           {{ tick.value }}
         </text>
@@ -756,8 +904,9 @@ const positionedLegendItems = computed(() => {
         :y="0"
         :transform="`translate(14, ${padding.top + innerH / 2}) rotate(-90)`"
         text-anchor="middle"
-        font-size="13"
-        fill="currentColor"
+        :font-size="axisLabelResolved.fontSize"
+        :fill="axisLabelResolved.fill"
+        :font-weight="axisLabelResolved.fontWeight"
       >
         {{ yLabel }}
       </text>
@@ -770,9 +919,10 @@ const positionedLegendItems = computed(() => {
           :x="tick.pos"
           :y="padding.top + innerH + 16"
           :text-anchor="tick.anchor"
-          font-size="10"
-          fill="currentColor"
-          fill-opacity="0.6"
+          :font-size="tickLabelResolved.fontSize"
+          :fill="tickLabelResolved.fill"
+          :font-weight="tickLabelResolved.fontWeight"
+          :fill-opacity="tickLabelResolved.fillOpacity"
         >
           {{ tick.label }}
         </text>
@@ -786,9 +936,10 @@ const positionedLegendItems = computed(() => {
           :y="tick.pos"
           text-anchor="end"
           dominant-baseline="middle"
-          font-size="10"
-          fill="currentColor"
-          fill-opacity="0.6"
+          :font-size="tickLabelResolved.fontSize"
+          :fill="tickLabelResolved.fill"
+          :font-weight="tickLabelResolved.fontWeight"
+          :fill-opacity="tickLabelResolved.fillOpacity"
         >
           {{ tick.label }}
         </text>
@@ -799,8 +950,9 @@ const positionedLegendItems = computed(() => {
         :x="padding.left + innerW / 2"
         :y="height - 4"
         text-anchor="middle"
-        font-size="13"
-        fill="currentColor"
+        :font-size="axisLabelResolved.fontSize"
+        :fill="axisLabelResolved.fill"
+        :font-weight="axisLabelResolved.fontWeight"
       >
         {{ xLabel }}
       </text>

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -1,7 +1,7 @@
 <script setup>
 import { computed, ref } from "vue";
 import countiesTopoForPerf from "us-atlas/counties-10m.json";
-import { fipsToHsa } from "@cfasim-ui/charts";
+import { fipsToHsa } from "@cfasim-ui/charts/hsa-mapping";
 
 // Build one row per county (~3,143) with a deterministic-ish value so the
 // perf example can render every region with a custom tooltip.
@@ -478,6 +478,10 @@ feature (e.g. an HSA from a county via `fipsToHsa`). Pass both as a
 parent HSA renders on top as a dashed overlay (`stroke: "#666"` here —
 default is white).
 
+`fipsToHsa` and `hsaNames` ship from the `@cfasim-ui/charts/hsa-mapping`
+subpath so consumers that don't need HSA lookups don't pay for the
+~25 KB of mapping data.
+
 <ComponentDemo>
   <ChoroplethMap
     :topology="countiesTopo"
@@ -512,7 +516,7 @@ default is white).
 ```vue
 <script setup>
 import { ref, computed } from "vue";
-import { fipsToHsa } from "@cfasim-ui/charts";
+import { fipsToHsa } from "@cfasim-ui/charts/hsa-mapping";
 
 const focusedCounty = ref(null);
 const focus = computed(() => {
@@ -691,6 +695,8 @@ set `tooltip-trigger`.
 | `height` | `number` | No | — |
 | `colorScale` | `ChoroplethColorScale \| ThresholdStop[] \| CategoricalStop[]` | No | — |
 | `title` | `string` | No | — |
+| `titleStyle` | `TitleStyle` | No | — |
+| `legendStyle` | `LabelStyle` | No | — |
 | `noDataColor` | `string` | No | `"#ddd"` |
 | `strokeColor` | `string` | No | `"#fff"` |
 | `strokeWidth` | `number` | No | `0.5` |

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -17,11 +17,17 @@ 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";
 import { saveSvg, savePng } from "../ChartMenu/download.js";
-import { useChartFullscreen } from "../_shared/index.js";
+import {
+  useChartFullscreen,
+  TITLE_FONT_SIZE,
+  TITLE_LINE_HEIGHT,
+  TITLE_FONT_WEIGHT,
+  type TitleStyle,
+  type LabelStyle,
+} from "../_shared/index.js";
 import { placeTooltip } from "../tooltip-position.js";
 import ChoroplethTooltip from "./ChoroplethTooltip.vue";
 
@@ -104,7 +110,15 @@ const props = withDefaults(
     width?: number;
     height?: number;
     colorScale?: ChoroplethColorScale | ThresholdStop[] | CategoricalStop[];
+    /**
+     * Map title. `\n` in the string creates additional lines, each
+     * adding `titleStyle.lineHeight` (default 18px) of vertical space.
+     */
     title?: string;
+    /** Styling for the map title. See `TitleStyle`. */
+    titleStyle?: TitleStyle;
+    /** Styling for the legend (title, swatch labels, and continuous-scale ticks). */
+    legendStyle?: LabelStyle;
     noDataColor?: string;
     strokeColor?: string;
     strokeWidth?: number;
@@ -231,6 +245,33 @@ const slots = useSlots();
 const hasInteractiveTooltip = computed(
   () => !!props.tooltipTrigger || !!props.tooltipFormat || !!slots.tooltip,
 );
+
+/**
+ * Inline style for the legend container. Font properties cascade to
+ * children (legend title, swatch labels, continuous-scale ticks).
+ */
+const legendInlineStyle = computed(() => {
+  const s = props.legendStyle;
+  const style: Record<string, string> = {};
+  if (s?.fontSize != null) style["font-size"] = `${s.fontSize}px`;
+  if (s?.fontWeight != null) style["font-weight"] = String(s.fontWeight);
+  if (s?.color != null) style.color = s.color;
+  return style;
+});
+
+/** Inline style for the title element, applying TitleStyle overrides. */
+const titleInlineStyle = computed(() => {
+  const s = props.titleStyle;
+  const style: Record<string, string> = {
+    "font-size": `${s?.fontSize ?? TITLE_FONT_SIZE}px`,
+    "line-height": `${s?.lineHeight ?? TITLE_LINE_HEIGHT}px`,
+    "font-weight": String(s?.fontWeight ?? TITLE_FONT_WEIGHT),
+    "text-align": s?.align ?? "left",
+    width: "100%",
+  };
+  if (s?.color) style.color = s.color;
+  return style;
+});
 // Imperative path bookkeeping. Plain Maps rather than refs — Vue never reads
 // these from a render scope, so mutating them does not trigger re-renders.
 const pathsByFeatureId = new Map<string, SVGPathElement>();
@@ -612,7 +653,39 @@ type CountiesTopo = Topology<{
   states: NamedGeometry;
 }>;
 
+// HSA mapping is loaded lazily — it's ~25KB gzipped and only needed when
+// geoType or dataGeoType is "hsas". Keeps the main bundle small for users
+// who only need states/counties maps.
+type HsaModule = typeof import("./hsaMapping.js");
+const hsaModule = ref<HsaModule | null>(null);
+let hsaModulePromise: Promise<HsaModule> | null = null;
+function loadHsaModule() {
+  if (!hsaModulePromise) {
+    hsaModulePromise = import("./hsaMapping.js").then((m) => {
+      hsaModule.value = m;
+      return m;
+    });
+  }
+  return hsaModulePromise;
+}
+watch(
+  () => {
+    if (props.geoType === "hsas" || props.dataGeoType === "hsas") return true;
+    const focus = props.focus;
+    if (!focus) return false;
+    const items = Array.isArray(focus) ? focus : [focus];
+    return items.some((f) => typeof f !== "string" && f.geoType === "hsas");
+  },
+  (needsHsa) => {
+    if (needsHsa) loadHsaModule();
+  },
+  { immediate: true },
+);
+
 const hsaFeaturesGeo = computed(() => {
+  const mod = hsaModule.value;
+  if (!mod) return { type: "FeatureCollection" as const, features: [] };
+  const { fipsToHsa, hsaNames } = mod;
   const topo = toRaw(props.topology) as unknown as CountiesTopo;
   const countyGeometries = topo.objects.counties.geometries;
   const groups = new Map<string, typeof countyGeometries>();
@@ -696,7 +769,7 @@ function baseToDataId(baseId: string): string | undefined {
   const dataGt = props.dataGeoType;
   if (!dataGt || dataGt === props.geoType) return baseId;
   if (props.geoType === "counties" && dataGt === "hsas") {
-    return fipsToHsa[baseId];
+    return hsaModule.value?.fipsToHsa[baseId];
   }
   if (props.geoType === "counties" && dataGt === "states") {
     return baseId.slice(0, 2);
@@ -1355,9 +1428,11 @@ watch(
 // `flush: "post"` so any pending path rebuild from the watcher above has
 // already run; we still use the GeoJSON pathGenerator directly so the SVG
 // path tree isn't actually required, but keeping the order avoids stacking
-// two zoom transforms in the same tick.
+// two zoom transforms in the same tick. `hsaModule` is included so a
+// cross-geoType focus on an hsa item re-applies once the lazy module
+// resolves (the base pathGenerator doesn't depend on hsa data).
 watch(
-  () => [normalizedFocus.value, pathGenerator.value],
+  () => [normalizedFocus.value, pathGenerator.value, hsaModule.value],
   () => applyFocus(),
   { flush: "post" },
 );
@@ -1381,8 +1456,14 @@ watch(
       viewBox to fit the container.
     -->
     <div v-if="title || showLegend" class="choropleth-header">
-      <div v-if="title" class="choropleth-title">{{ title }}</div>
-      <div v-if="showLegend" class="choropleth-legend">
+      <div v-if="title" class="choropleth-title" :style="titleInlineStyle">
+        {{ title }}
+      </div>
+      <div
+        v-if="showLegend"
+        class="choropleth-legend"
+        :style="legendInlineStyle"
+      >
         <span v-if="legendTitle" class="choropleth-legend-title">
           {{ legendTitle }}
         </span>
@@ -1539,6 +1620,7 @@ watch(
   font-size: 14px;
   font-weight: 600;
   line-height: 1.2;
+  white-space: pre-line;
 }
 
 .choropleth-legend {