@cfasim-ui/docs 0.4.10 → 0.4.12

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -17,10 +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,
+  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";
 
@@ -103,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;
@@ -230,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>();
@@ -611,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>();
@@ -695,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);
@@ -1298,9 +1372,12 @@ const gradientCss = computed(() => {
   return `linear-gradient(to right, ${stops})`;
 });
 
+const fullscreen = useChartFullscreen();
+
 const menuItems = computed<ChartMenuItem[]>(() => {
   const fname = menuFilename();
   return [
+    fullscreen.menuItem.value,
     {
       label: "Save as SVG",
       action: () => {
@@ -1351,25 +1428,42 @@ 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" },
 );
 </script>
 
 <template>
-  <div ref="containerRef" :class="['choropleth-wrapper', { pannable: pan }]">
+  <div
+    ref="containerRef"
+    :class="[
+      'choropleth-wrapper',
+      { pannable: pan, 'is-fullscreen': fullscreen.isFullscreen.value },
+    ]"
+  >
     <ChartMenu v-if="menu" :items="menuItems" />
+    <div class="chart-sr-only" aria-live="polite">
+      {{ fullscreen.isFullscreen.value ? "Map expanded to fill window" : "" }}
+    </div>
     <!--
       Title + legend live as an HTML overlay on top of the SVG so they keep
       their intrinsic px sizes regardless of how the browser scales the
       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>
@@ -1476,10 +1570,6 @@ watch(
   cursor: grabbing;
 }
 
-.choropleth-wrapper:hover :deep(.chart-menu-button) {
-  opacity: 1;
-}
-
 .state-path {
   cursor: pointer;
 }
@@ -1530,6 +1620,7 @@ watch(
   font-size: 14px;
   font-weight: 600;
   line-height: 1.2;
+  white-space: pre-line;
 }
 
 .choropleth-legend {

package/charts/LineChart/LineChart.md

@@ -59,6 +59,127 @@ charts, set `x` and `y` (or `data`) on each `Series`.
 
 When `x` is omitted, `y`/`data` values are plotted at indices 0, 1, 2, etc.
 
+### Dates
+
+Pass ISO date strings (`YYYY-MM-DD`) or `Date` objects as `x` and the
+chart auto-detects a date axis: ticks anchor to year / month / week /
+day / hour boundaries depending on the visible range, and labels
+format themselves accordingly. Numeric `x` arrays keep their existing
+behavior — auto-detection is content-driven and never promotes plain
+numbers.
+
+<ComponentDemo>
+  <LineChart
+    :x="['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']"
+    :y="[4, 9, 18, 32, 41, 38, 27, 18, 11, 6]"
+    :height="220"
+    y-label="% ED visits"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :x="[
+    '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',
+  ]"
+  :y="[4, 9, 18, 32, 41, 38, 27, 18, 11, 6]"
+  :height="220"
+  y-label="% ED visits"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Override the format via `x-tick-format`. Presets: `"iso"`,
+`"iso-datetime"`, `"year"`, `"month-year"`, `"month-day"`, `"day"`,
+`"time"`, `"datetime"`, `"medium"`. You can also pass an
+`Intl.DateTimeFormatOptions` literal, or a function `(ms, unit?) =>
+string` for full control.
+
+<ComponentDemo>
+  <LineChart
+    :x="['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']"
+    :y="[4, 9, 18, 32, 41]"
+    x-tick-format="iso"
+    :height="220"
+    y-label="% ED visits"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :x="['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']"
+  :y="[4, 9, 18, 32, 41]"
+  x-tick-format="iso"
+  :height="220"
+  y-label="% ED visits"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+By default the chart parses bare `YYYY-MM-DD` (and offset-less
+`YYYY-MM-DDTHH:mm:ss`) as UTC and renders tick labels in UTC. Set
+`timezone="local"` to interpret offset-less strings in the browser's
+timezone instead. Strings that include an explicit offset (`Z` or
+`+05:00`) are always parsed exactly as written.
+
+> **Annotations on a date axis.** `ChartAnnotation.x` is always in the
+> chart's resolved coordinate space — that's **epoch-ms** when the axis
+> is in date mode. Pass `Date.UTC(2026, 0, 15)`, `new Date("2026-01-15").getTime()`,
+> or `Date.parse("2026-01-15T00:00:00Z")`. Passing a small integer like
+> `0` will place the annotation at 1970-01-01 (off-screen).
+>
+> **`xLabels` on a date axis.** When both `x: [...date strings]` and
+> `xLabels` are supplied, the date axis wins — `xLabels` is ignored.
+> Date strings carry their own labeling.
+
+### Title
+
+The `title` prop accepts `\n` to break across lines. Use `titleStyle`
+to override `fontSize`, `lineHeight`, `color`, `fontWeight`, and
+`align` (`"left" | "center" | "right"`, default `"left"`). Top padding
+grows automatically for additional lines.
+
+<ComponentDemo>
+  <LineChart
+    :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+    :height="220"
+    :title="'Daily ED visits\nInfluenza-like illness, last 11 days'"
+    :title-style="{ fontSize: 16, lineHeight: 20, color: '#0057b7' }"
+    x-label="Days"
+    y-label="Cases"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+  :height="220"
+  :title="'Daily ED visits\nInfluenza-like illness, last 11 days'"
+  :title-style="{ fontSize: 16, lineHeight: 20, color: '#0057b7' }"
+  x-label="Days"
+  y-label="Cases"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Multiple series
 
 <ComponentDemo>
@@ -98,6 +219,46 @@ When `x` is omitted, `y`/`data` values are plotted at indices 0, 1, 2, etc.
   </template>
 </ComponentDemo>
 
+### Legend
+
+Set `legend` on a series to add an entry to the inline legend strip above the plot. When the items don't all fit on one row at the chart's current width, the legend wraps to additional rows and the plot area shrinks to keep the legend clear of the data. Use `showInLegend: false` to keep a series off the legend (e.g. when its `legend` string is reused as a CSV column header) and `showInTooltip: false` to omit it from the hover tooltip.
+
+<ComponentDemo>
+  <LineChart
+    :series="[
+      { data: [0, 12, 28, 45, 60, 55, 40, 25, 12], color: '#0057b7', legend: 'No interventions' },
+      { data: [0, 10, 22, 38, 50, 45, 32, 18, 8], color: '#fb7e38', legend: 'School closures' },
+      { data: [0, 8, 18, 30, 40, 35, 25, 14, 6], color: '#ef4444', legend: 'Masking + distancing' },
+      { data: [0, 6, 14, 24, 32, 28, 20, 10, 4], color: '#10b981', legend: 'Vaccination only' },
+      { data: [0, 4, 10, 16, 22, 19, 13, 7, 3], color: '#6366f1', legend: 'Vaccination + masking' },
+      { data: [0, 3, 7, 11, 15, 13, 9, 5, 2], color: '#a855f7', legend: 'All interventions combined' },
+    ]"
+    :height="240"
+    x-label="Weeks"
+    y-label="Incidence"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :series="[
+    { data: scenarioA, color: '#0057b7', legend: 'No interventions' },
+    { data: scenarioB, color: '#fb7e38', legend: 'School closures' },
+    { data: scenarioC, color: '#ef4444', legend: 'Masking + distancing' },
+    { data: scenarioD, color: '#10b981', legend: 'Vaccination only' },
+    { data: scenarioE, color: '#6366f1', legend: 'Vaccination + masking' },
+    { data: scenarioF, color: '#a855f7', legend: 'All interventions combined' },
+  ]"
+  :height="240"
+  x-label="Weeks"
+  y-label="Incidence"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Tooltip
 
 Hover over the chart to see a tooltip with values at each data point. Set `tooltip-trigger="hover"` to enable the built-in tooltip with crosshair and highlight dots. Use the `#tooltip` slot for custom content. Pass `tooltip-value-format` to control how numeric values render (e.g. percentages, currency); it falls back to `y-tick-format` when omitted.
@@ -248,6 +409,46 @@ floor, and `yMin <= 0` is ignored.
   </template>
 </ComponentDemo>
 
+### Outline
+
+Set `outline: true` on a series to draw a page-colored stroke behind the
+line. This is useful when lines overlap, cross dense areas, or sit on a
+busy background — the outline keeps each series visually distinct.
+
+<ComponentDemo>
+  <LineChart
+    :series="[
+      { data: [0, 10, 25, 45, 60, 55, 40, 20, 8], color: '#fb7e38', strokeWidth: 3, outline: true },
+      { data: [0, 12, 22, 40, 58, 58, 42, 22, 10], color: '#0057b7', strokeWidth: 3, outline: true },
+    ]"
+    :height="200"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :series="[
+    {
+      data: [0, 10, 25, 45, 60, 55, 40, 20, 8],
+      color: '#fb7e38',
+      strokeWidth: 3,
+      outline: true,
+    },
+    {
+      data: [0, 12, 22, 40, 58, 58, 42, 22, 10],
+      color: '#0057b7',
+      strokeWidth: 3,
+      outline: true,
+    },
+  ]"
+  :height="200"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Many trajectories with low opacity
 
 <ComponentDemo>
@@ -478,8 +679,9 @@ Pin callouts to data points with `annotations`. Each annotation anchors at
 respects `xMin` and explicit `x` values), with a pixel
 `offset: { x, y }` for the label position. Text supports `\n` for line
 breaks. A curved
-pointer line connects the anchor to the label, and the label gets a halo
-stroke matching the background so it stays legible over series lines.
+pointer line connects the anchor to the label, and the label gets an
+outline stroke matching the background so it stays legible over series
+lines.
 
 <ComponentDemo>
   <LineChart
@@ -564,9 +766,9 @@ interface ChartAnnotation {
   color?: string; // text / pointer color (default: currentColor)
   fontSize?: number; // default: 13 (matches axis labels)
   fontWeight?: string | number; // default: "normal"
-  haloColor?: string; // background-matched halo (default: var(--color-bg-0, #fff))
-  haloWidth?: number; // default: 3
-  textAnchor?: "start" | "middle" | "end"; // default: derived from offset[0] sign
+  outlineColor?: string; // background-matched outline (default: var(--color-bg-0, #fff))
+  outlineWidth?: number; // default: 3
+  align?: "left" | "center" | "right"; // default: derived from offset[0] sign
   lineColor?: string; // connector-line color override (default: color)
   lineWidth?: number; // default: 1
   lineDash?: string | number | readonly number[]; // SVG stroke-dasharray
@@ -619,7 +821,7 @@ positioned from the anchor as usual via `offset`.
         y: 30,
         offset: { x: -8, y: -6 },
         text: 'Max',
-        textAnchor: 'end',
+        align: 'right',
         pointer: 'ruleFromLeft',
         lineDash: '4 3',
       },
@@ -649,7 +851,7 @@ positioned from the anchor as usual via `offset`.
       y: 30,
       offset: { x: -8, y: -6 },
       text: 'Max',
-      textAnchor: 'end',
+      align: 'right',
       pointer: 'ruleFromLeft',
       lineDash: '4 3',
     },
@@ -664,6 +866,13 @@ positioned from the anchor as usual via `offset`.
   </template>
 </ComponentDemo>
 
+### Chart menu
+
+The chart menu (top-right) leads with Expand / Collapse and then Save as SVG,
+Save as PNG, and Download CSV. Expand grows the chart to fill the browser
+window so the plot has more room; press <kbd>Esc</kbd> or pick "Collapse" to
+return to the inline size. Set `menu="false"` to hide the trigger entirely.
+
 ### Custom CSV download
 
 By default, the Download CSV menu item exports the chart series as CSV. Use
@@ -720,6 +929,10 @@ until the user clicks Download:
 | `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 | — |
@@ -735,7 +948,7 @@ until the user clicks Download:
 | `chartPadding` | `ChartPadding` | No | — |
 | `y` | `LineChartData` | No | — |
 | `data` | `LineChartData` | No | — |
-| `x` | `LineChartData` | No | — |
+| `x` | `LineChartXInput` | No | — |
 | `series` | `Series[]` | No | — |
 | `areas` | `Area[]` | No | — |
 | `areaSections` | `AreaSection[]` | No | — |
@@ -745,7 +958,10 @@ until the user clicks Download:
 | `xMin` | `number` | No | — |
 | `xTicks` | `number \| number[]` | No | — |
 | `yTicks` | `number \| number[]` | No | — |
-| `xTickFormat` | `NumberFormat \| ((value: number, index: number) =&gt; string)` | No | — |
+| `xTickFormat` | `\| NumberFormat
+    \| ((value: number, index: number) =&gt; string)
+    \| DateFormat` | No | — |
+| `timezone` | `DateTimezone` | No | — |
 | `yTickFormat` | `NumberFormat` | No | — |
 | `xLabels` | `string[]` | No | — |
 | `xGrid` | `boolean` | No | — |
@@ -789,6 +1005,7 @@ interface Series {
   strokeWidth?: number;
   opacity?: number;
   line?: boolean;
+  outline?: boolean; // page-colored stroke drawn behind the line
   dots?: boolean;
   dotRadius?: number;
   dotFill?: string;