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

@@ -13,10 +13,25 @@ import {
   useChartFoundation,
   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,
+  type ChartTooltipValue,
 } from "../_shared/index.js";
 
 export type BarChartData = ChartData;
@@ -29,6 +44,16 @@ export interface BarSeries {
   opacity?: number;
   /** Label shown in the inline legend. */
   legend?: string;
+  /**
+   * Whether this series appears in the inline legend. Defaults to true.
+   * Has no effect when `legend` is unset (no legend entry to begin with).
+   */
+  showInLegend?: boolean;
+  /**
+   * Whether this series contributes a value to the tooltip. Defaults to
+   * true. The bars are still drawn.
+   */
+  showInTooltip?: boolean;
 }
 
 interface BarChartProps extends ChartCommonProps {
@@ -41,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. */
@@ -71,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.
@@ -104,8 +142,6 @@ defineSlots<{
   tooltip?(props: ChartTooltipBaseProps & { category: string }): unknown;
 }>();
 
-const hasInlineLegend = computed(() => allSeries.value.some((s) => s.legend));
-
 const EMPTY_DATA: readonly number[] = [];
 
 type ResolvedSeries = {
@@ -113,6 +149,8 @@ type ResolvedSeries = {
   color?: string;
   opacity?: number;
   legend?: string;
+  showInLegend?: boolean;
+  showInTooltip?: boolean;
 };
 
 function resolveSeries(s: BarSeries): ResolvedSeries {
@@ -121,6 +159,8 @@ function resolveSeries(s: BarSeries): ResolvedSeries {
     color: s.color,
     opacity: s.opacity,
     legend: s.legend,
+    showInLegend: s.showInLegend,
+    showInTooltip: s.showInTooltip,
   };
 }
 
@@ -144,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). */
@@ -439,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++) {
@@ -462,12 +566,16 @@ interface InlineLegendItem {
 const inlineLegendItems = computed<InlineLegendItem[]>(() => {
   const items: InlineLegendItem[] = [];
   allSeries.value.forEach((s, i) => {
-    if (!s.legend) return;
+    if (!s.legend || s.showInLegend === false) return;
     items.push({ label: s.legend, color: s.color ?? defaultColor(i) });
   });
   return items;
 });
 
+const inlineLegendLabels = computed(() =>
+  inlineLegendItems.value.map((item) => item.label),
+);
+
 function toCsv(): string {
   if (typeof props.csv === "function") return props.csv();
   if (typeof props.csv === "string") return props.csv;
@@ -514,6 +622,7 @@ const {
   height,
   padding,
   legendY,
+  inlineLegendLayout,
   innerW,
   innerH,
   bounds,
@@ -525,10 +634,12 @@ const {
   downloadLinkText,
   csvHref,
   menuFilename,
+  isFullscreen,
 } = useChartFoundation({
   width: () => props.width,
   height: () => props.height,
   title: () => props.title,
+  titleStyle: () => props.titleStyle,
   xLabel: () => props.xLabel,
   yLabel: () => props.yLabel,
   debounce: () => props.debounce,
@@ -538,30 +649,84 @@ const {
   filename: () => props.filename,
   downloadLink: () => props.downloadLink,
   chartPadding: () => props.chartPadding,
-  hasInlineLegend: () => hasInlineLegend.value,
+  inlineLegendLabels: () => inlineLegendLabels.value,
   hasTooltipSlot: () => hasTooltipSlot.value,
   getCsv: toCsv,
   pointerToIndex,
   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];
 });
 
 const hoverSlotProps = computed(() => {
   const idx = hoverIndex.value;
   if (idx === null) return null;
-  return {
-    index: idx,
-    category: categoryLabels.value[idx] ?? String(idx),
-    values: allSeries.value.map((s, i) => ({
+  const series = allSeries.value;
+  const values: ChartTooltipValue[] = [];
+  for (let i = 0; i < series.length; i++) {
+    const s = series[i];
+    if (s.showInTooltip === false) continue;
+    values.push({
       value: Number(s.data[idx] ?? NaN),
       color: s.color ?? defaultColor(i),
       seriesIndex: i,
-    })),
+    });
+  }
+  return {
+    index: idx,
+    category: categoryLabels.value[idx] ?? String(idx),
+    values,
     data: props.tooltipData?.[idx] ?? null,
   };
 });
@@ -586,39 +751,72 @@ const hoverBand = computed(() => {
     h: slotSize.value,
   };
 });
+
+/**
+ * Legend items joined with their wrapped pixel positions. `x` is the
+ * left edge of the indicator; `y` is the center of the row.
+ */
+const positionedLegendItems = computed(() => {
+  const positions = inlineLegendLayout.value.positions;
+  const pad = padding.value.left;
+  const baseY = legendY.value;
+  return inlineLegendItems.value.map((item, i) => {
+    const pos = positions[i];
+    return {
+      ...item,
+      x: pad + pos.x,
+      y: baseY + pos.row * INLINE_LEGEND_ROW_HEIGHT,
+    };
+  });
+});
 </script>
 
 <template>
-  <div ref="containerRef" class="bar-chart-wrapper">
+  <div
+    ref="containerRef"
+    class="bar-chart-wrapper"
+    :class="{ 'is-fullscreen': isFullscreen }"
+  >
     <ChartMenu v-if="menu" :items="menuItems" />
+    <div class="chart-sr-only" aria-live="polite">
+      {{ isFullscreen ? "Chart expanded to fill window" : "" }}
+    </div>
     <svg ref="svgRef" :width="width" :height="height">
       <!-- 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="inlineLegendItems.length > 0">
-        <template v-for="(item, i) in inlineLegendItems" :key="'ileg' + i">
+      <g v-if="positionedLegendItems.length > 0">
+        <template v-for="(item, i) in positionedLegendItems" :key="'ileg' + i">
           <rect
-            :x="padding.left + i * 120"
-            :y="legendY - 5"
+            :x="item.x"
+            :y="item.y - 5"
             width="12"
             height="10"
             :fill="item.color"
           />
           <text
-            :x="padding.left + i * 120 + 18"
-            :y="legendY + 4"
-            font-size="11"
-            fill="currentColor"
+            :x="item.x + 18"
+            :y="item.y + 4"
+            :font-size="legendResolved.fontSize"
+            :fill="legendResolved.fill"
+            :font-weight="legendResolved.fontWeight"
           >
             {{ item.label }}
           </text>
@@ -675,9 +873,10 @@ const hoverBand = 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>
@@ -690,9 +889,10 @@ const hoverBand = 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>
@@ -704,8 +904,9 @@ const hoverBand = 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>
@@ -718,9 +919,10 @@ const hoverBand = 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>
@@ -734,9 +936,10 @@ const hoverBand = 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>
@@ -747,8 +950,9 @@ const hoverBand = 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>
@@ -837,10 +1041,6 @@ const hoverBand = computed(() => {
   width: 100%;
 }
 
-.bar-chart-wrapper:hover :deep(.chart-menu-button) {
-  opacity: 1;
-}
-
 .bar-chart-tooltip-label {
   font-weight: 600;
   margin-bottom: 0.25em;

package/charts/ChartMenu/ChartMenu.vue

@@ -10,6 +10,8 @@ import {
 export interface ChartMenuItem {
   label: string;
   action: () => void;
+  /** Sets aria-pressed on the menu item — use for toggle-style items. */
+  ariaPressed?: boolean;
 }
 
 const props = withDefaults(
@@ -72,6 +74,7 @@ const useDropdown = () => props.forceDropdown || props.items.length > 1;
             v-for="item in items"
             :key="item.label"
             class="chart-menu-item"
+            :aria-pressed="item.ariaPressed"
             @select="item.action"
           >
             {{ item.label }}

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