@cfasim-ui/docs 0.4.4 → 0.4.6

package/charts/BarChart/BarChart.md

@@ -160,37 +160,149 @@ Use `value-tick-format` to format the value-axis labels. `tooltip-value-format`
   </template>
 </ComponentDemo>
 
+### Annotations
+
+Pin callouts to specific bars with `annotations`. `x` is the category
+index (fractional values land between categories — e.g. `x: 1.5` sits at
+the boundary between categories 1 and 2). `y` is on the value axis. See
+[`LineChart` → Annotations](./line-chart#annotations) for the full
+`ChartAnnotation` shape.
+
+<ComponentDemo>
+  <BarChart
+    :data="[12, 19, 7, 24, 16]"
+    :categories="['Mon', 'Tue', 'Wed', 'Thu', 'Fri']"
+    :annotations="[
+      { x: 3, y: 24, offset: { x: 18, y: -22 }, text: 'Peak day' },
+    ]"
+    :chart-padding="{ top: 32, right: 32 }"
+    :height="240"
+    x-label="Day"
+    y-label="Cases"
+  />
+
+<template #code>
+
+```vue
+<BarChart
+  :data="[12, 19, 7, 24, 16]"
+  :categories="['Mon', 'Tue', 'Wed', 'Thu', 'Fri']"
+  :annotations="[{ x: 3, y: 24, offset: { x: 18, y: -22 }, text: 'Peak day' }]"
+  :chart-padding="{ top: 32, right: 32 }"
+  :height="240"
+  x-label="Day"
+  y-label="Cases"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+`chart-padding` reserves extra space outside the plot so the annotation
+label and pointer don't get clipped by the data area. Pass a number for
+uniform padding or an object with `top` / `right` / `bottom` / `left`.
+
+Set `pointer` to a rule value (`"ruleX"`, `"ruleY"`, `"ruleUp"`,
+`"ruleDown"`, `"ruleFromLeft"`, `"ruleFromRight"`) to draw a line
+through the anchor instead of the default curved connector. The first
+two span the full plot; the latter four extend from one edge to the
+anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
+
+<ComponentDemo>
+  <BarChart
+    :data="[12, 19, 7, 24, 16]"
+    :categories="['Mon', 'Tue', 'Wed', 'Thu', 'Fri']"
+    :annotations="[
+      {
+        x: 0,
+        y: 15.6,
+        offset: { x: 6, y: -6 },
+        text: 'Avg 15.6',
+        pointer: 'ruleY',
+        lineDash: '4 3',
+      },
+      {
+        x: 3,
+        y: 20,
+        offset: { x: 8, y: 4 },
+        text: 'Target hit',
+        pointer: 'ruleFromLeft',
+        lineColor: '#0a7',
+      },
+    ]"
+    :chart-padding="{ top: 24, right: 24 }"
+    :height="240"
+    x-label="Day"
+    y-label="Cases"
+  />
+
+<template #code>
+
+```vue
+<BarChart
+  :data="[12, 19, 7, 24, 16]"
+  :categories="['Mon', 'Tue', 'Wed', 'Thu', 'Fri']"
+  :annotations="[
+    {
+      x: 0,
+      y: 15.6,
+      offset: { x: 6, y: -6 },
+      text: 'Avg 15.6',
+      pointer: 'ruleY',
+      lineDash: '4 3',
+    },
+    {
+      x: 3,
+      y: 20,
+      offset: { x: 8, y: 4 },
+      text: 'Target hit',
+      pointer: 'ruleFromLeft',
+      lineColor: '#0a7',
+    },
+  ]"
+  :chart-padding="{ top: 24, right: 24 }"
+  :height="240"
+  x-label="Day"
+  y-label="Cases"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ## API
 
 ## Props
 
 | Prop | Type | Required | Default |
 |------|------|----------|---------|
-| `data` | `BarChartData` | No | — |
-| `y` | `BarChartData` | No | — |
-| `series` | `BarSeries[]` | No | — |
-| `categories` | `readonly string[]` | No | — |
-| `orientation` | `"vertical" \| "horizontal"` | No | `"vertical"` |
-| `layout` | `"grouped" \| "stacked"` | No | `"grouped"` |
 | `width` | `number` | No | — |
 | `height` | `number` | No | — |
 | `title` | `string` | No | — |
 | `xLabel` | `string` | No | — |
 | `yLabel` | `string` | No | — |
-| `valueMin` | `number` | No | `0` |
-| `valueTicks` | `number \| number[]` | No | — |
-| `valueTickFormat` | `(value: number) =&gt; string` | No | — |
-| `tooltipValueFormat` | `(value: number) =&gt; string` | No | — |
-| `categoryFormat` | `(label: string, index: number) =&gt; string` | No | — |
-| `barPadding` | `number` | No | `0.2` |
-| `groupGap` | `number` | No | `1` |
 | `debounce` | `number` | No | — |
 | `menu` | `boolean \| string` | No | `true` |
-| `valueGrid` | `boolean` | No | `true` |
 | `tooltipData` | `ArrayLike&lt;unknown&gt;` | No | — |
 | `tooltipTrigger` | `"hover" \| "click"` | No | — |
 | `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
+| `tooltipValueFormat` | `(value: number) =&gt; string` | No | — |
 | `csv` | `string \| (() =&gt; string)` | No | — |
 | `filename` | `string` | No | — |
 | `downloadLink` | `boolean \| string` | No | — |
+| `annotations` | `readonly ChartAnnotation[]` | No | — |
+| `chartPadding` | `ChartPadding` | No | — |
+| `data` | `BarChartData` | No | — |
+| `y` | `BarChartData` | No | — |
+| `series` | `BarSeries[]` | No | — |
+| `categories` | `readonly string[]` | No | — |
+| `orientation` | `"vertical" \| "horizontal"` | No | `"vertical"` |
+| `layout` | `"grouped" \| "stacked"` | No | `"grouped"` |
+| `valueMin` | `number` | No | `0` |
+| `valueTicks` | `number \| number[]` | No | — |
+| `valueTickFormat` | `(value: number) =&gt; string` | No | — |
+| `categoryFormat` | `(label: string, index: number) =&gt; string` | No | — |
+| `barPadding` | `number` | No | `0.2` |
+| `groupGap` | `number` | No | `1` |
+| `valueGrid` | `boolean` | No | `true` |
 

package/charts/BarChart/BarChart.vue

@@ -6,12 +6,13 @@ import {
   formatTick,
   computeTickValues,
   categoricalToCsv,
-  useChartSize,
-  useChartTooltip,
-  useChartMenu,
-  useChartPadding,
-  INLINE_LEGEND_HEIGHT,
+  useChartFoundation,
+  makeTooltipValueFormatter,
+  ChartAnnotations,
   type ChartData,
+  type ChartCommonProps,
+  type ChartHoverPayload,
+  type ChartTooltipBaseProps,
 } from "../_shared/index.js";
 
 export type BarChartData = ChartData;
@@ -26,117 +27,67 @@ export interface BarSeries {
   legend?: string;
 }
 
-const props = withDefaults(
-  defineProps<{
-    /** Single-series values. Equivalent to `y`. */
-    data?: BarChartData;
-    /** Single-series values (alias for `data`). */
-    y?: BarChartData;
-    /** Multi-series mode. Each series has its own values. */
-    series?: BarSeries[];
-    /**
-     * Category labels for the categorical axis. Length should match the
-     * longest series. When omitted, indices (0, 1, 2, ...) are used.
-     */
-    categories?: readonly string[];
-    /** "vertical" (default, aka column) draws upright bars; "horizontal" draws sideways. */
-    orientation?: "vertical" | "horizontal";
-    /** "grouped" (default) places series side-by-side; "stacked" stacks them. */
-    layout?: "grouped" | "stacked";
-    width?: number;
-    height?: number;
-    title?: string;
-    xLabel?: string;
-    yLabel?: string;
-    /** Force the value axis to start at this value or lower (default 0). */
-    valueMin?: number;
-    /**
-     * Tick placement on the value axis (numeric). Number = interval,
-     * array = explicit values. When omitted, ticks are chosen automatically.
-     */
-    valueTicks?: number | number[];
-    /** Formatter for value-axis tick labels. */
-    valueTickFormat?: (value: number) => string;
-    /**
-     * Formatter for numeric values shown in the default tooltip. Receives
-     * the raw value. Defaults to the same tick formatter used for axes.
-     */
-    tooltipValueFormat?: (value: number) => string;
-    /** Formatter for category-axis labels. Receives the resolved category string. */
-    categoryFormat?: (label: string, index: number) => string;
-    /**
-     * Fraction of each category slot reserved as gap between groups (0..1).
-     * Default 0.2 — i.e. bars/groups fill 80% of their slot.
-     */
-    barPadding?: number;
-    /**
-     * Pixel gap between bars within a single category group in `grouped` layout.
-     * Default 1.
-     */
-    groupGap?: number;
-    debounce?: number;
-    menu?: boolean | string;
-    valueGrid?: boolean;
-    /**
-     * Custom per-index data passed to the tooltip slot. Accepts a plain
-     * array or any `ArrayLike` (e.g. a typed array column from a
-     * `ModelOutput`).
-     */
-    tooltipData?: ArrayLike<unknown>;
-    /** Tooltip activation mode. */
-    tooltipTrigger?: "hover" | "click";
-    /** Boundary for tooltip flip/clamp. Default "chart". */
-    tooltipClamp?: "none" | "chart" | "window";
-    /** Custom CSV content (string or function). When omitted, generated from the bars. */
-    csv?: string | (() => string);
-    /** Filename (without extension) for downloaded SVG, PNG, CSV. */
-    filename?: string;
-    /** Show a plain text link below the chart to download the CSV. */
-    downloadLink?: boolean | string;
-  }>(),
-  {
-    orientation: "vertical",
-    layout: "grouped",
-    valueMin: 0,
-    barPadding: 0.2,
-    groupGap: 1,
-    menu: true,
-    tooltipClamp: "chart",
-    valueGrid: true,
-  },
-);
+interface BarChartProps extends ChartCommonProps {
+  /** Single-series values. Equivalent to `y`. */
+  data?: BarChartData;
+  /** Single-series values (alias for `data`). */
+  y?: BarChartData;
+  /** Multi-series mode. Each series has its own values. */
+  series?: BarSeries[];
+  /**
+   * Category labels for the categorical axis. Length should match the
+   * longest series. When omitted, indices (0, 1, 2, ...) are used.
+   */
+  categories?: readonly string[];
+  /** "vertical" (default, aka column) draws upright bars; "horizontal" draws sideways. */
+  orientation?: "vertical" | "horizontal";
+  /** "grouped" (default) places series side-by-side; "stacked" stacks them. */
+  layout?: "grouped" | "stacked";
+  /** Force the value axis to start at this value or lower (default 0). */
+  valueMin?: number;
+  /**
+   * Tick placement on the value axis (numeric). Number = interval,
+   * array = explicit values. When omitted, ticks are chosen automatically.
+   */
+  valueTicks?: number | number[];
+  /** Formatter for value-axis tick labels. */
+  valueTickFormat?: (value: number) => string;
+  /** Formatter for category-axis labels. Receives the resolved category string. */
+  categoryFormat?: (label: string, index: number) => string;
+  /**
+   * Fraction of each category slot reserved as gap between groups (0..1).
+   * Default 0.2 — i.e. bars/groups fill 80% of their slot.
+   */
+  barPadding?: number;
+  /**
+   * Pixel gap between bars within a single category group in `grouped` layout.
+   * Default 1.
+   */
+  groupGap?: number;
+  valueGrid?: boolean;
+}
+
+const props = withDefaults(defineProps<BarChartProps>(), {
+  orientation: "vertical",
+  layout: "grouped",
+  valueMin: 0,
+  barPadding: 0.2,
+  groupGap: 1,
+  menu: true,
+  tooltipClamp: "chart",
+  valueGrid: true,
+});
 
 const emit = defineEmits<{
-  (e: "hover", payload: { index: number } | null): void;
+  (e: "hover", payload: ChartHoverPayload): void;
 }>();
 
 defineSlots<{
-  tooltip?(props: {
-    index: number;
-    category: string;
-    values: { value: number; color: string; seriesIndex: number }[];
-    data: unknown;
-  }): unknown;
+  tooltip?(props: ChartTooltipBaseProps & { category: string }): unknown;
 }>();
 
-const { containerRef, measuredWidth } = useChartSize({
-  debounce: () => props.debounce,
-});
-
-const width = computed(() => props.width ?? (measuredWidth.value || 400));
-const height = computed(() => props.height ?? 200);
-
 const hasInlineLegend = computed(() => allSeries.value.some((s) => s.legend));
 
-const { padding, innerW, innerH } = useChartPadding({
-  title: () => props.title,
-  xLabel: () => props.xLabel,
-  yLabel: () => props.yLabel,
-  hasInlineLegend: () => hasInlineLegend.value,
-  width: () => width.value,
-  height: () => height.value,
-});
-
 const EMPTY_DATA: readonly number[] = [];
 
 type ResolvedSeries = {
@@ -408,11 +359,10 @@ function defaultColor(i: number): string {
   return DEFAULT_COLORS[i % DEFAULT_COLORS.length];
 }
 
-function formatTooltipValue(v: number): string {
-  if (props.tooltipValueFormat) return props.tooltipValueFormat(v);
-  if (props.valueTickFormat) return props.valueTickFormat(v);
-  return formatTick(v);
-}
+const formatTooltipValue = makeTooltipValueFormatter(
+  () => props.tooltipValueFormat,
+  () => props.valueTickFormat,
+);
 
 const valueTickItems = computed(() => {
   const { min, max } = valueExtent.value;
@@ -489,6 +439,20 @@ const hasTooltipSlot = computed(
   () => !!props.tooltipData || !!props.tooltipTrigger,
 );
 
+function projectAnnotation(
+  x: number,
+  y: number,
+): { x: number; y: number } | null {
+  if (!isFinite(x) || !isFinite(y)) return null;
+  if (slotSize.value === 0) return null;
+  const base = isVertical.value ? padding.value.left : padding.value.top;
+  const categoricalPx = base + (x + 0.5) * slotSize.value;
+  const valuePx = valuePixel(y);
+  return isVertical.value
+    ? { x: categoricalPx, y: valuePx }
+    : { x: valuePx, y: categoricalPx };
+}
+
 function pointerToIndex(clientX: number, clientY: number): number | null {
   const rect = containerRef.value?.getBoundingClientRect();
   if (!rect) return null;
@@ -501,30 +465,41 @@ function pointerToIndex(clientX: number, clientY: number): number | null {
 }
 
 const {
+  containerRef,
+  svgRef,
+  width,
+  height,
+  padding,
+  legendY,
+  innerW,
+  innerH,
+  bounds,
   hoverIndex,
   tooltipRef,
   tooltipPos,
-  handlers: tooltipHandlers,
-} = useChartTooltip({
-  enabled: () => hasTooltipSlot.value,
-  trigger: () => props.tooltipTrigger,
-  clamp: () => props.tooltipClamp,
-  pointerToIndex,
-  containerRef,
-  onHover: (payload) => emit("hover", payload),
-});
-
-const {
-  svgRef,
-  items: menuItems,
+  tooltipHandlers,
+  menuItems,
   downloadLinkText,
   csvHref,
-  resolvedFilename: menuFilename,
-} = useChartMenu({
+  menuFilename,
+} = useChartFoundation({
+  width: () => props.width,
+  height: () => props.height,
+  title: () => props.title,
+  xLabel: () => props.xLabel,
+  yLabel: () => props.yLabel,
+  debounce: () => props.debounce,
+  menu: () => props.menu,
+  tooltipTrigger: () => props.tooltipTrigger,
+  tooltipClamp: () => props.tooltipClamp,
   filename: () => props.filename,
-  legacyMenuLabel: () => props.menu,
-  getCsv: toCsv,
   downloadLink: () => props.downloadLink,
+  chartPadding: () => props.chartPadding,
+  hasInlineLegend: () => hasInlineLegend.value,
+  hasTooltipSlot: () => hasTooltipSlot.value,
+  getCsv: toCsv,
+  pointerToIndex,
+  onHover: (payload) => emit("hover", payload),
 });
 
 const hoveredCategoryLabel = computed(() => {
@@ -591,14 +566,14 @@ const hoverBand = computed(() => {
         <template v-for="(item, i) in inlineLegendItems" :key="'ileg' + i">
           <rect
             :x="padding.left + i * 120"
-            :y="padding.top - INLINE_LEGEND_HEIGHT / 2 - 5"
+            :y="legendY - 5"
             width="12"
             height="10"
             :fill="item.color"
           />
           <text
             :x="padding.left + i * 120 + 18"
-            :y="padding.top - INLINE_LEGEND_HEIGHT / 2 + 4"
+            :y="legendY + 4"
             font-size="11"
             fill="currentColor"
           >
@@ -759,6 +734,13 @@ const hoverBand = computed(() => {
         style="cursor: crosshair; touch-action: none"
         v-on="tooltipHandlers"
       />
+      <!-- annotations (top layer) -->
+      <ChartAnnotations
+        v-if="annotations && annotations.length > 0"
+        :annotations="annotations"
+        :project="projectAnnotation"
+        :bounds="bounds"
+      />
     </svg>
     <!-- Tooltip floating content -->
     <div

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -1,6 +1,7 @@
 <script setup>
 import { computed, ref } from "vue";
 import countiesTopoForPerf from "us-atlas/counties-10m.json";
+import { fipsToHsa } from "@cfasim-ui/charts";
 
 // Build one row per county (~3,143) with a deterministic-ish value so the
 // perf example can render every region with a custom tooltip.
@@ -16,6 +17,19 @@ const denseCountyData = computed(() => {
 // handles click-to-toggle and emits null when the focused feature is
 // re-clicked.
 const focused = ref(null);
+
+// "Outline a focused feature's parent" demo: focus is a county id;
+// we derive the parent HSA and add it to the focus array as a dashed
+// overlay so clicking a county also outlines its HSA.
+const focusedCounty = ref(null);
+const parentFocus = computed(() => {
+  const fips = focusedCounty.value;
+  if (!fips) return null;
+  const hsa = fipsToHsa[fips];
+  return hsa
+    ? [fips, { id: hsa, geoType: "hsas", style: "dashed", stroke: "#666" }]
+    : fips;
+});
 </script>
 
 # ChoroplethMap
@@ -407,6 +421,124 @@ const focused = ref(null);
   </template>
 </ComponentDemo>
 
+### Color by HSA, interact by county (`dataGeoType`)
+
+Set `dataGeoType` when your data is keyed by a coarser geography than
+the one you want to render. Each county fills with its parent HSA's
+value (via the built-in FIPS → HSA mapping); hover, click, and `focus`
+still operate on the county geometry, and you can layer an HSA outline
+on top with a `FocusItem`.
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="counties"
+    data-geo-type="hsas"
+    :pan="true"
+    :zoom="true"
+    :data="[
+      { id: '060737', value: 80 },
+      { id: '060723', value: 60 },
+      { id: '060757', value: 45 },
+      { id: '060807', value: 35 },
+      { id: '060768', value: 25 },
+      { id: '060774', value: 50 },
+    ]"
+    :focus="[
+      { id: '06043' },
+      { id: '060737', geoType: 'hsas', style: 'dashed' },
+    ]"
+    :focus-zoom-level="6"
+    title="HSA-keyed data on a county map"
+    :legend-title="'Cases'"
+    :height="400"
+  />
+
+<template #code>
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  data-geo-type="hsas"
+  :data="hsaData"
+  :focus="[{ id: '06043' }, { id: '060737', geoType: 'hsas', style: 'dashed' }]"
+  title="HSA-keyed data on a county map"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+### Outline a focused feature's parent
+
+Use `v-model:focus` together with a computed that derives a parent
+feature (e.g. an HSA from a county via `fipsToHsa`). Pass both as a
+`FocusItem` array — the focused county lights up as usual and the
+parent HSA renders on top as a dashed overlay (`stroke: "#666"` here —
+default is white).
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="counties"
+    data-geo-type="hsas"
+    :pan="true"
+    :zoom="true"
+    :focus="parentFocus"
+    @update:focus="focusedCounty = typeof $event === 'string' ? $event : null"
+    :data="[
+      { id: '060737', value: 80 },
+      { id: '060723', value: 60 },
+      { id: '060757', value: 45 },
+      { id: '060807', value: 35 },
+      { id: '060768', value: 25 },
+      { id: '060774', value: 50 },
+    ]"
+    :focus-zoom-level="6"
+    title="Click a county to outline its HSA"
+    :legend-title="'Cases'"
+    :height="400"
+  >
+    <template #tooltip="{ name, value }">
+      <div style="font-weight: 600">{{ name }}</div>
+      <div v-if="value != null">Cases: {{ value }}</div>
+      <div v-else style="opacity: 0.6">No data</div>
+    </template>
+  </ChoroplethMap>
+
+<template #code>
+
+```vue
+<script setup>
+import { ref, computed } from "vue";
+import { fipsToHsa } from "@cfasim-ui/charts";
+
+const focusedCounty = ref(null);
+const focus = computed(() => {
+  const fips = focusedCounty.value;
+  if (!fips) return null;
+  const hsa = fipsToHsa[fips];
+  return hsa
+    ? [fips, { id: hsa, geoType: "hsas", style: "dashed", stroke: "#666" }]
+    : fips;
+});
+</script>
+
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  data-geo-type="hsas"
+  :data="hsaData"
+  :focus="focus"
+  @update:focus="focusedCounty = typeof $event === 'string' ? $event : null"
+  title="Click a county to outline its HSA"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Custom tooltip number format
 
 Pass `tooltip-value-format` to format numeric values shown in the tooltip
@@ -554,6 +686,7 @@ set `tooltip-trigger`.
 | `topology` | `Topology` | Yes | — |
 | `data` | `StateData[]` | No | — |
 | `geoType` | `GeoType` | No | `"states"` |
+| `dataGeoType` | `GeoType` | No | — |
 | `width` | `number` | No | — |
 | `height` | `number` | No | — |
 | `colorScale` | `ChoroplethColorScale \| ThresholdStop[] \| CategoricalStop[]` | No | — |
@@ -573,7 +706,7 @@ set `tooltip-trigger`.
 | `value` | `number \| string` | No | — |
 | `tooltipValueFormat` | `(value: number) =&gt; string` | No | — |
 | `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
-| `focus` | `string \| string[] \| null` | No | — |
+| `focus` | `FocusValue` | No | — |
 | `focusZoomLevel` | `number` | No | `4` |
 
 
@@ -624,3 +757,22 @@ interface CategoricalStop {
   color: string;
 }
 ```
+
+### FocusItem
+
+The `focus` prop accepts a bare id, a `FocusItem`, or an array of either. Use objects when you want to pin features from a different `geoType` than the base map, or pick a non-default outline style.
+
+```ts
+interface FocusItem {
+  /** Feature id (FIPS code, HSA code) or name. */
+  id: string;
+  /** Defaults to the map's geoType. Cross-geoType items render as
+   * non-interactive outlines on top of the base map. */
+  geoType?: "states" | "counties" | "hsas";
+  /** Outline style. "solid" (default) matches the hover highlight;
+   * "dashed" uses long dashes; "dotted" uses small round dots. */
+  style?: "solid" | "dashed" | "dotted";
+  /** Stroke color for cross-geoType overlay paths. Default: "#fff". */
+  stroke?: string;
+}
+```