@cfasim-ui/docs 0.6.1 → 0.6.3

package/charts/BarChart/BarChart.md

@@ -699,6 +699,30 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
   </template>
 </ComponentDemo>
 
+## Accessibility
+
+The chart's individual bars aren't exposed to assistive tech, so the chart
+announces itself with a single accessible name. When the chart has a `title`,
+its root element gets `role="figure"` and an `aria-label` set to the title, so
+screen readers announce it as a labeled figure while the menu and download
+controls stay reachable.
+
+Set `ariaLabel` to give screen readers a fuller summary than the visible title
+(it overrides `title` for the accessible name only):
+
+```vue
+<BarChart
+  :data="cases"
+  :categories="regions"
+  title="Cases by region"
+  aria-label="Cases by region: North 120, South 80, West 45"
+/>
+```
+
+Pass `role` to override the default, e.g. `role="img"` to expose the chart as a
+single image (note this hides the inner menu/download controls from assistive
+tech).
+
 ## API
 
 ## Props
@@ -709,6 +733,8 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
 | `height` | `number` | No | — |
 | `title` | `string` | No | — |
 | `titleStyle` | `TitleStyle` | No | — |
+| `role` | `string` | No | — |
+| `ariaLabel` | `string` | No | — |
 | `axisLabelStyle` | `LabelStyle` | No | — |
 | `tickLabelStyle` | `LabelStyle` | No | — |
 | `legendStyle` | `LabelStyle` | No | — |

package/charts/BarChart/BarChart.vue

@@ -286,6 +286,14 @@ const props = withDefaults(defineProps<BarChartProps>(), {
   valueAxis: true,
 });
 
+// Accessible name for the whole chart; falls back to the visible title.
+const chartAriaLabel = computed(() => props.ariaLabel ?? props.title);
+// Label the chart as a figure when it has a name (keeps inner controls
+// reachable, unlike role="img"). An explicit `role` prop always wins.
+const chartRole = computed(
+  () => props.role ?? (chartAriaLabel.value ? "figure" : undefined),
+);
+
 // The template root is a <Teleport>, so fallthrough attrs (class, style,
 // data-*, id…) can't auto-inherit — forward them onto the wrapper manually.
 defineOptions({ inheritAttrs: false });
@@ -1475,6 +1483,8 @@ const columnHeaders = computed<ColumnHeader[]>(() => {
       class="bar-chart-wrapper"
       :class="{ 'is-fullscreen': isFullscreen }"
       :style="fullscreenStyle"
+      :role="chartRole || undefined"
+      :aria-label="chartAriaLabel || undefined"
     >
       <ChartMenu
         v-if="menu"

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -258,6 +258,8 @@ Use an array of `CategoricalStop` objects to map string values to colors. Each s
 
 Set `geoType="counties"` to render county-level data using 5-digit FIPS codes. State borders are drawn on top for context. Use `pan` and `zoom` props to enable interactive navigation — useful for dense county data.
 
+On touch devices, add `two-finger-pan` so a single finger scrolls the page (the map sets `touch-action: pan-y`) and two fingers pan/pinch-zoom the map — tap-to-select still works with one finger.
+
 <ComponentDemo>
   <ChoroplethMap
     :topology="countiesTopo"
@@ -356,6 +358,58 @@ Set `geoType="hsas"` to render Health Service Area boundaries. HSAs are dissolve
   </template>
 </ComponentDemo>
 
+### Single-state map (`state`)
+
+Set the `state` prop to render just one state's outline with its `counties` or
+`hsas` inside it — no surrounding states — and the projection zooms to fit it.
+Accepts a state **name** (`"California"`) or a 2-digit **FIPS code** (`"06"`).
+This needs a counties topology (the same `us-atlas/counties-10m.json`). `data`
+can stay national; only features inside the selected state are drawn and
+colored.
+
+<ComponentDemo>
+  <ChoroplethMap
+    :topology="countiesTopo"
+    geo-type="counties"
+    state="California"
+    :data="[
+      { id: '06037', value: 100 },
+      { id: '06073', value: 80 },
+      { id: '06059', value: 65 },
+      { id: '06065', value: 55 },
+      { id: '06001', value: 45 },
+      { id: '06085', value: 40 },
+    ]"
+    title="California cases by county"
+    :legend-title="'Cases'"
+    :height="400"
+  />
+
+<template #code>
+
+```vue
+<ChoroplethMap
+  :topology="countiesTopo"
+  geo-type="counties"
+  state="California"
+  :data="[
+    { id: '06037', value: 100 }, // Los Angeles
+    { id: '06073', value: 80 }, // San Diego
+    { id: '06059', value: 65 }, // Orange
+  ]"
+  title="California cases by county"
+  :legend-title="'Cases'"
+  :height="400"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Switch `geo-type="hsas"` to fill the same state with Health Service Areas
+instead. An unrecognized `state` value logs a warning and falls back to the
+full national map.
+
 ### Click to focus (`v-model:focus`)
 
 Bind the `focus` prop to pan and zoom to a specific feature. Pass a feature
@@ -365,6 +419,10 @@ the focused feature toggles back off. If a tooltip is configured, focusing
 shows that feature's tooltip. Users can pan/zoom freely around the focused
 area; the built-in **Reset** button clears focus and snaps back.
 
+Set `:focus-zoom="false"` to highlight (and draw cross-geoType overlays)
+**without** panning or zooming — useful for a click-to-select interaction
+where the map should stay put while a side panel shows the details.
+
 Selection works on touch too: a single-finger **tap** on a feature emits
 `stateClick` and toggles focus, while drags (pan) and pinches (zoom) are left
 to the map. Hover tooltips stay off on touch for performance.
@@ -687,6 +745,30 @@ set `tooltip-trigger`.
   </template>
 </ComponentDemo>
 
+## Accessibility
+
+The map's individual regions aren't exposed to assistive tech, so the map
+announces itself with a single accessible name. When it has a `title`, the root
+element gets `role="figure"` and an `aria-label` set to the title, so screen
+readers announce it as a labeled figure while the menu and reset controls stay
+reachable.
+
+Set `ariaLabel` to give screen readers a fuller summary than the visible title
+(it overrides `title` for the accessible name only):
+
+```vue
+<ChoroplethMap
+  :topology="usStates"
+  :data="cases"
+  title="Cases by state"
+  aria-label="US map shaded by case count per state, highest in the Southeast"
+/>
+```
+
+Pass `role` to override the default, e.g. `role="img"` to expose the map as a
+single image (note this hides the inner menu/reset controls from assistive
+tech).
+
 ## Props
 
 | Prop | Type | Required | Default |
@@ -695,11 +777,14 @@ set `tooltip-trigger`.
 | `data` | `StateData[]` | No | — |
 | `geoType` | `GeoType` | No | `"states"` |
 | `dataGeoType` | `GeoType` | No | — |
+| `state` | `string` | No | — |
 | `width` | `number` | No | — |
 | `height` | `number` | No | — |
 | `colorScale` | `ChoroplethColorScale \| ThresholdStop[] \| CategoricalStop[]` | No | — |
 | `title` | `string` | No | — |
 | `titleStyle` | `TitleStyle` | No | — |
+| `role` | `string` | No | — |
+| `ariaLabel` | `string` | No | — |
 | `legendStyle` | `LabelStyle` | No | — |
 | `noDataColor` | `string` | No | `"#ddd"` |
 | `strokeColor` | `string` | No | `"#fff"` |
@@ -709,6 +794,7 @@ set `tooltip-trigger`.
 | `legendTitle` | `string` | No | — |
 | `zoom` | `boolean` | No | `false` |
 | `pan` | `boolean` | No | `false` |
+| `twoFingerPan` | `boolean` | No | `false` |
 | `tooltipTrigger` | `"hover" \| "click"` | No | — |
 | `tooltipFormat` | `(data: {
       id: string` | No | — |
@@ -718,6 +804,7 @@ set `tooltip-trigger`.
 | `tooltipClamp` | `"none" \| "chart" \| "window"` | No | `"chart"` |
 | `focus` | `FocusValue` | No | — |
 | `focusZoomLevel` | `number` | No | `4` |
+| `focusZoom` | `boolean` | No | `true` |
 | `fullscreenTarget` | `string \| HTMLElement` | No | — |
 
 

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -8,7 +8,7 @@ import {
   toRaw,
   useSlots,
 } from "vue";
-import { geoPath, geoAlbersUsa } from "d3-geo";
+import { geoPath, geoAlbersUsa, geoMercator } from "d3-geo";
 import { zoom as d3Zoom, zoomIdentity } from "d3-zoom";
 import { select } from "d3-selection";
 // Side-effect import: enables `selection.transition()` on d3 selections so
@@ -107,6 +107,15 @@ const props = withDefaults(
      * When unset, data ids must match the base `geoType`.
      */
     dataGeoType?: GeoType;
+    /**
+     * Scope the map to a single state: render only that state's outline with
+     * its `counties` or `hsas` inside it (no surrounding states), and refit
+     * the projection to zoom to it. Accepts a state name ("California") or a
+     * 2-digit FIPS code ("06"). Requires a counties topology when `geoType`
+     * is `"counties"` or `"hsas"`. If the value matches no state, the full
+     * national map is rendered and a warning is logged.
+     */
+    state?: string;
     width?: number;
     height?: number;
     colorScale?: ChoroplethColorScale | ThresholdStop[] | CategoricalStop[];
@@ -117,6 +126,21 @@ const props = withDefaults(
     title?: string;
     /** Styling for the map title. See `TitleStyle`. */
     titleStyle?: TitleStyle;
+    /**
+     * ARIA role for the map's root element. Defaults to `"figure"` when an
+     * accessible name is present (from `ariaLabel` or `title`), so screen
+     * readers announce the map as a labeled figure while its controls (menu,
+     * reset) stay reachable. Pass `"img"` to expose it as a single image
+     * (which hides the inner controls from assistive tech), or your own role.
+     */
+    role?: string;
+    /**
+     * Accessible name for the map, announced by screen readers via the root
+     * element's `aria-label`. Defaults to the `title` prop. The individual
+     * regions aren't exposed to assistive tech, so set this to a short summary
+     * of what the map shows.
+     */
+    ariaLabel?: string;
     /** Styling for the legend (title, swatch labels, and continuous-scale ticks). */
     legendStyle?: LabelStyle;
     noDataColor?: string;
@@ -131,6 +155,14 @@ const props = withDefaults(
     zoom?: boolean;
     /** Enable click-and-drag panning. Default: false */
     pan?: boolean;
+    /**
+     * Require two fingers to pan/zoom on touch devices. Default `false`.
+     * When `true`, a single finger scrolls the page (the map sets
+     * `touch-action: pan-y` and ignores one-finger drags) while two fingers
+     * pan and pinch-zoom the map. Single-finger tap-to-select still works.
+     * Has no effect with a mouse.
+     */
+    twoFingerPan?: boolean;
     /** Tooltip activation mode */
     tooltipTrigger?: "hover" | "click";
     /**
@@ -174,6 +206,14 @@ const props = withDefaults(
     focus?: FocusValue;
     /** Scale factor applied when `focus` is set. Default: 4 */
     focusZoomLevel?: number;
+    /**
+     * Whether setting `focus` pans/zooms to fit the focused feature.
+     * Default `true`. Set `false` to highlight (and draw cross-geoType
+     * overlays) without changing the current pan/zoom — useful for a
+     * click-to-select interaction where the map should stay put. The
+     * built-in Reset button is unaffected.
+     */
+    focusZoom?: boolean;
     /**
      * Where to teleport the map while expanded (the Expand menu item). A
      * CSS selector or element; defaults to `body`. Moving it to the
@@ -193,11 +233,21 @@ const props = withDefaults(
     legend: true,
     zoom: false,
     pan: false,
+    twoFingerPan: false,
     tooltipClamp: "chart",
     focusZoomLevel: 4,
+    focusZoom: true,
   },
 );
 
+// Accessible name for the whole map; falls back to the visible title.
+const chartAriaLabel = computed(() => props.ariaLabel ?? props.title);
+// Label the map as a figure when it has a name (keeps inner controls
+// reachable, unlike role="img"). An explicit `role` prop always wins.
+const chartRole = computed(
+  () => props.role ?? (chartAriaLabel.value ? "figure" : undefined),
+);
+
 // The template root is a <Teleport>, so fallthrough attrs (class, style,
 // data-*, id…) can't auto-inherit — forward them onto the wrapper manually.
 defineOptions({ inheritAttrs: false });
@@ -425,16 +475,28 @@ function setupZoom() {
   // Dynamic filter: re-evaluated per event, so toggling `focus`,
   // `zoom`, or `pan` doesn't require tearing down the zoom behavior.
   // When focus is active we always allow drag + wheel so users can
-  // explore away from the focused area regardless of `zoom`/`pan`.
+  // explore away from the focused area regardless of `zoom`/`pan` — but
+  // not in highlight-only mode (`focusZoom=false`), where focus is purely
+  // visual and shouldn't grant interaction the props didn't ask for.
   // Programmatic `.transform()` calls bypass this filter entirely.
   zoomBehavior.filter((event) => {
-    const focused = normalizedFocus.value.length > 0;
+    const focused =
+      normalizedFocus.value.length > 0 && props.focusZoom !== false;
     const allowZoom = !!props.zoom || focused;
     const allowPan = !!props.pan || focused;
     if (event.type === "wheel" || event.type === "dblclick") {
       if (!allowZoom) return false;
     } else if (event.type === "mousedown" || event.type === "touchstart") {
       if (!allowPan) return false;
+      // Two-finger-only mode: ignore single-finger touches so the page can
+      // scroll; a second finger drives the map (pan + pinch-zoom).
+      if (
+        props.twoFingerPan &&
+        event.type === "touchstart" &&
+        (event as TouchEvent).touches.length < 2
+      ) {
+        return false;
+      }
     } else if (!allowZoom && !allowPan) {
       return false;
     }
@@ -541,6 +603,13 @@ function applyFocus() {
     return;
   }
 
+  // Highlight-only mode: the strokes + overlays above are applied; skip the
+  // pan/zoom transform so the current view stays put (click-to-select).
+  if (props.focusZoom === false) {
+    focusApplied = true;
+    return;
+  }
+
   const svg = select(svgRef.value);
   // Always cancel any in-flight transition first — d3-transition queues
   // same-named transitions rather than replacing them, so rapid focus
@@ -667,6 +736,19 @@ watch(
   },
 );
 
+// Switching the scoped `state` refits the projection to a different region,
+// so any leftover pan/zoom transform would leave the new map off-center.
+// Reset it instantly (no animation) when the region changes.
+watch(
+  () => props.state,
+  () => {
+    if (!svgRef.value || !zoomBehavior) return;
+    const svg = select(svgRef.value);
+    svg.interrupt();
+    zoomBehavior.transform(svg, zoomIdentity);
+  },
+);
+
 // Canonical internal coordinate system. All layout (projection, legend,
 // title) is computed at this size; the SVG's viewBox makes the browser
 // scale the entire canvas to whatever the container provides, so there's no
@@ -692,6 +774,58 @@ type CountiesTopo = Topology<{
   states: NamedGeometry;
 }>;
 
+type StateFeature = GeoJSON.Feature<GeoJSON.Geometry | null, { name?: string }>;
+
+// ─── Single-state scoping (`state` prop) ─────────────────────────────────
+//
+// Resolved directly from the topology's `states` object (not from
+// featuresByGeoType) so it stays free of the featuresGeo → featuresById →
+// featuresByGeoType chain — that chain reads `stateFips`, so depending on it
+// here would form a reactive cycle.
+const statesFeatures = computed<StateFeature[]>(() => {
+  const topo = toRaw(props.topology) as unknown as {
+    objects?: { states?: NamedGeometry };
+  };
+  const statesObj = topo?.objects?.states;
+  if (!statesObj) return [];
+  const fc = feature(topo as unknown as Topology, statesObj) as
+    | GeoJSON.FeatureCollection<GeoJSON.Geometry | null, { name?: string }>
+    | StateFeature;
+  return fc.type === "FeatureCollection" ? fc.features : [fc];
+});
+
+// 2-digit FIPS for the active `state` prop, or null when unset/unresolved.
+const stateFips = computed<string | null>(() => {
+  const s = props.state?.trim();
+  if (!s) return null;
+  if (/^\d{1,2}$/.test(s)) return s.padStart(2, "0");
+  const match = statesFeatures.value.find((f) => f.properties?.name === s);
+  return match?.id != null ? String(match.id).padStart(2, "0") : null;
+});
+
+// The single state's GeoJSON feature — drives the outline path and the
+// projection fit in single-state mode.
+const stateOutlineFeature = computed<StateFeature | null>(() => {
+  const fips = stateFips.value;
+  if (!fips) return null;
+  return (
+    statesFeatures.value.find((f) => String(f.id).padStart(2, "0") === fips) ??
+    null
+  );
+});
+
+watch(
+  () => [props.state, stateFips.value] as const,
+  ([state, fips]) => {
+    if (state && state.trim() && !fips) {
+      console.warn(
+        `[ChoroplethMap] state="${state}" matched no state name or FIPS code; rendering the full map.`,
+      );
+    }
+  },
+  { immediate: true },
+);
+
 // 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.
@@ -727,10 +861,14 @@ const hsaFeaturesGeo = computed(() => {
   const { fipsToHsa, hsaNames } = mod;
   const topo = toRaw(props.topology) as unknown as CountiesTopo;
   const countyGeometries = topo.objects.counties.geometries;
+  const scopeFips = stateFips.value;
   const groups = new Map<string, typeof countyGeometries>();
 
   for (const geom of countyGeometries) {
     const fips = String(geom.id).padStart(5, "0");
+    // Single-state mode: drop counties outside the state before grouping, so
+    // the resulting HSAs only cover the selected state.
+    if (scopeFips && fips.slice(0, 2) !== scopeFips) continue;
     const hsaCode = fipsToHsa[fips];
     if (!hsaCode) continue;
     if (!groups.has(hsaCode)) groups.set(hsaCode, []);
@@ -751,30 +889,71 @@ const hsaFeaturesGeo = computed(() => {
 });
 
 const featuresGeo = computed(() => {
+  // hsaFeaturesGeo already honors `state` (it scopes the source counties).
   if (props.geoType === "hsas") return hsaFeaturesGeo.value;
+  const scopeFips = stateFips.value;
   if (props.geoType === "counties") {
     const topo = toRaw(props.topology) as unknown as CountiesTopo;
-    return feature(topo, topo.objects.counties);
+    const fc = feature(topo, topo.objects.counties);
+    if (!scopeFips) return fc;
+    return {
+      type: "FeatureCollection" as const,
+      features: fc.features.filter(
+        (f) => String(f.id).padStart(5, "0").slice(0, 2) === scopeFips,
+      ),
+    };
   }
   const topo = toRaw(props.topology) as unknown as StatesTopo;
-  return feature(topo, topo.objects.states);
+  const fc = feature(topo, topo.objects.states);
+  if (!scopeFips) return fc;
+  return {
+    type: "FeatureCollection" as const,
+    features: fc.features.filter(
+      (f) => String(f.id).padStart(2, "0") === scopeFips,
+    ),
+  };
 });
 
 const stateBordersPath = computed(() => {
   if (props.geoType !== "counties" && props.geoType !== "hsas") return null;
+  // Single-state mode: trace just the selected state's outline instead of
+  // the full national state-border mesh.
+  if (stateFips.value) return stateOutlineFeature.value;
   const topo = toRaw(props.topology) as unknown as CountiesTopo;
   return mesh(topo, topo.objects.states, (a, b) => a !== b);
 });
 
-const projection = computed(() =>
-  geoAlbersUsa().fitExtent(
+// Breathing room (canonical px) around a single state so its outline isn't
+// flush against the SVG edge. Only applied in single-state mode.
+const STATE_FIT_INSET = 12;
+
+const projection = computed(() => {
+  const outline = stateOutlineFeature.value;
+  if (stateFips.value && outline) {
+    const extent: [[number, number], [number, number]] = [
+      [STATE_FIT_INSET, STATE_FIT_INSET],
+      [width.value - STATE_FIT_INSET, height.value - STATE_FIT_INSET],
+    ];
+    const albers = geoAlbersUsa().fitExtent(extent, outline);
+    // geoAlbersUsa only covers the 50 states + DC (it handles Alaska and
+    // Hawaii via insets). The island territories — Puerto Rico, Guam, the
+    // US Virgin Islands, American Samoa, the N. Mariana Islands — fall
+    // outside it and project to null, so fitExtent yields a NaN transform
+    // and every path renders as "MNaN,NaN…". Detect that by projecting the
+    // outline's centroid and fall back to a plain Mercator that can render
+    // any region.
+    const c = geoPath(albers).centroid(outline);
+    if (Number.isFinite(c[0]) && Number.isFinite(c[1])) return albers;
+    return geoMercator().fitExtent(extent, outline);
+  }
+  return geoAlbersUsa().fitExtent(
     [
       [0, 0],
       [width.value, height.value],
     ],
     featuresGeo.value,
-  ),
-);
+  );
+});
 
 const pathGenerator = computed(() => geoPath(projection.value));
 
@@ -1481,9 +1660,12 @@ const menuItems = computed<ChartMenuItem[]>(() => {
 // Registered last so the eagerly-evaluated source getters can read every
 // computed defined above without hitting a TDZ.
 
-// Geometry / projection / tooltip-mode → full rebuild.
+// Geometry / projection / tooltip-mode → full rebuild. `featuresGeo` is
+// watched explicitly because in single-state mode the projection is pinned
+// to the static state outline, so an async change to the feature set (e.g.
+// the lazy HSA module resolving) wouldn't otherwise change `pathGenerator`.
 watch(
-  () => [pathGenerator.value, hasInteractiveTooltip.value],
+  () => [featuresGeo.value, pathGenerator.value, hasInteractiveTooltip.value],
   () => rebuildPaths(),
 );
 
@@ -1535,6 +1717,8 @@ watch(
         { pannable: pan, 'is-fullscreen': fullscreen.isFullscreen.value },
       ]"
       :style="fullscreen.fullscreenStyle.value"
+      :role="chartRole || undefined"
+      :aria-label="chartAriaLabel || undefined"
     >
       <ChartMenu
         v-if="menu"
@@ -1596,6 +1780,7 @@ watch(
         ref="svgRef"
         :viewBox="`0 0 ${width} ${height}`"
         preserveAspectRatio="xMidYMid meet"
+        :style="twoFingerPan ? { touchAction: 'pan-y' } : undefined"
       >
         <!--
         Path elements are created imperatively in `rebuildPaths()`; Vue never

package/charts/LineChart/LineChart.md

@@ -888,6 +888,56 @@ Markers compose (`**_bold italic_**`).
   </template>
 </ComponentDemo>
 
+Multi-line callouts attach to whichever edge of the text faces the anchor:
+text **above** the point connects to its bottom edge, text **below**
+connects to its top, and text to the side connects to its near vertical
+edge — so the pointer never cuts through the lines. The demo below anchors
+the same two-line label at one point and fans it out in every direction.
+
+<ComponentDemo>
+  <LineChart
+    :data="[2, 10, 7, 6, 8, 4, 9]"
+    :annotations="[
+      { x: 3, y: 6, offset: { x: 0, y: -86 }, text: 'Cluster\ndetected' },
+      { x: 3, y: 6, offset: { x: 62, y: -62 }, text: 'Cluster\ndetected' },
+      { x: 3, y: 6, offset: { x: 96, y: 0 }, text: 'Cluster\ndetected' },
+      { x: 3, y: 6, offset: { x: 62, y: 62 }, text: 'Cluster\ndetected' },
+      { x: 3, y: 6, offset: { x: 0, y: 86 }, text: 'Cluster\ndetected' },
+      { x: 3, y: 6, offset: { x: -62, y: 62 }, text: 'Cluster\ndetected' },
+      { x: 3, y: 6, offset: { x: -96, y: 0 }, text: 'Cluster\ndetected' },
+      { x: 3, y: 6, offset: { x: -62, y: -62 }, text: 'Cluster\ndetected' },
+    ]"
+    :chart-padding="{ top: 70, right: 120, bottom: 50, left: 120 }"
+    :height="340"
+    x-label="Days"
+    y-label="Cases"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :data="[2, 10, 7, 6, 8, 4, 9]"
+  :annotations="[
+    { x: 3, y: 6, offset: { x: 0, y: -86 }, text: 'Cluster\ndetected' },
+    { x: 3, y: 6, offset: { x: 62, y: -62 }, text: 'Cluster\ndetected' },
+    { x: 3, y: 6, offset: { x: 96, y: 0 }, text: 'Cluster\ndetected' },
+    { x: 3, y: 6, offset: { x: 62, y: 62 }, text: 'Cluster\ndetected' },
+    { x: 3, y: 6, offset: { x: 0, y: 86 }, text: 'Cluster\ndetected' },
+    { x: 3, y: 6, offset: { x: -62, y: 62 }, text: 'Cluster\ndetected' },
+    { x: 3, y: 6, offset: { x: -96, y: 0 }, text: 'Cluster\ndetected' },
+    { x: 3, y: 6, offset: { x: -62, y: -62 }, text: 'Cluster\ndetected' },
+  ]"
+  :chart-padding="{ top: 70, right: 120, bottom: 50, left: 120 }"
+  :height="340"
+  x-label="Days"
+  y-label="Cases"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ```ts
 interface ChartAnnotation {
   x: number; // anchor in data coords (x-axis)
@@ -1063,6 +1113,29 @@ until the user clicks Download:
 <LineChart :data="cases" :csv="() => buildCsv(cases, dates)" />
 ```
 
+## Accessibility
+
+The chart's individual marks aren't exposed to assistive tech, so the chart
+announces itself with a single accessible name. When the chart has a `title`,
+its root element gets `role="figure"` and an `aria-label` set to the title, so
+screen readers announce it as a labeled figure while the menu and download
+controls stay reachable.
+
+Set `ariaLabel` to give screen readers a fuller summary than the visible title
+(it overrides `title` for the accessible name only):
+
+```vue
+<LineChart
+  :data="cases"
+  title="Daily ED visits"
+  aria-label="Daily ED visits over 11 days, rising from 12 to a peak of 48"
+/>
+```
+
+Pass `role` to override the default, e.g. `role="img"` to expose the chart as a
+single image (note this hides the inner menu/download controls from assistive
+tech).
+
 ## Props
 
 | Prop | Type | Required | Default |
@@ -1071,6 +1144,8 @@ until the user clicks Download:
 | `height` | `number` | No | — |
 | `title` | `string` | No | — |
 | `titleStyle` | `TitleStyle` | No | — |
+| `role` | `string` | No | — |
+| `ariaLabel` | `string` | No | — |
 | `axisLabelStyle` | `LabelStyle` | No | — |
 | `tickLabelStyle` | `LabelStyle` | No | — |
 | `legendStyle` | `LabelStyle` | No | — |

package/charts/LineChart/LineChart.vue

@@ -240,6 +240,14 @@ const props = withDefaults(defineProps<LineChartProps>(), {
   yScaleType: "linear",
 });
 
+// Accessible name for the whole chart; falls back to the visible title.
+const chartAriaLabel = computed(() => props.ariaLabel ?? props.title);
+// Label the chart as a figure when it has a name (keeps inner controls
+// reachable, unlike role="img"). An explicit `role` prop always wins.
+const chartRole = computed(
+  () => props.role ?? (chartAriaLabel.value ? "figure" : undefined),
+);
+
 // The template root is a <Teleport>, so fallthrough attrs (class, style,
 // data-*, id…) can't auto-inherit — forward them onto the wrapper manually.
 defineOptions({ inheritAttrs: false });
@@ -1048,6 +1056,8 @@ const positionedLegendItems = computed(() => {
       class="line-chart-wrapper"
       :class="{ 'is-fullscreen': isFullscreen }"
       :style="fullscreenStyle"
+      :role="chartRole || undefined"
+      :aria-label="chartAriaLabel || undefined"
     >
       <ChartMenu
         v-if="menu"

package/charts/_shared/ChartAnnotations.vue

@@ -36,9 +36,9 @@ const ANCHOR_GAP_PX = 4;
 const LABEL_GAP_PX = 6;
 const LINE_HEIGHT_RATIO = 1.2;
 // Ratio of font-size that puts the pointer endpoint at the visual center
-// of the first text line (between baseline and cap-height). Lands on the
-// x-height middle for most fonts.
-const FIRST_LINE_CENTER_RATIO = 0.35;
+// of a text line (between baseline and cap-height). Lands on the x-height
+// middle for most fonts.
+const LINE_CENTER_RATIO = 0.35;
 
 interface TextRun {
   text: string;
@@ -139,6 +139,8 @@ const items = computed<RenderedAnnotation[]>(() => {
       a.align ?? (offsetX > 0 ? "left" : offsetX < 0 ? "right" : "center");
     const textAnchor = alignMap[align];
 
+    const lines = a.text.split("\n").map(parseInline);
+
     let rule: RenderedAnnotation["rule"];
     let pointerPath = "";
     let arrowTip: RenderedAnnotation["arrowTip"];
@@ -152,6 +154,7 @@ const items = computed<RenderedAnnotation[]>(() => {
         labelX,
         labelY,
         fontSize,
+        lines.length,
         pointer as "curved" | "straight" | "none",
       );
       pointerPath = built.path;
@@ -159,7 +162,7 @@ const items = computed<RenderedAnnotation[]>(() => {
     }
 
     out.push({
-      lines: a.text.split("\n").map(parseInline),
+      lines,
       textX: labelX,
       textY: labelY,
       textAnchor,
@@ -220,12 +223,17 @@ function computeRule(
  * - When the label has offset in only one dimension, the line is
  *   straight (vertical or horizontal) ending at the label's baseline.
  * - When both dimensions have offset, the line is a quarter-arc:
- *   a quadratic Bezier with the control point at `(anchorX, firstLineY)`
- *   where `firstLineY` is the visual center of the first line of text
- *   (slightly above the baseline). The curve emerges from the anchor
- *   vertically toward the label's row, then bends horizontally into the
- *   label so the endpoint reads as pointing at the first line — not at
- *   the bottom of a multi-line block.
+ *   a quadratic Bezier with the control point at `(anchorX, targetY)`
+ *   where `targetY` is the visual center of the text line nearest the
+ *   anchor (slightly above its baseline). The curve emerges from the
+ *   anchor vertically toward the label's row, then bends horizontally
+ *   into the label.
+ *
+ * `targetY` tracks the *near* edge of the text block: the first line
+ * when the label sits below the anchor (connector points up at the top
+ * line), the last line when the label sits above the anchor (connector
+ * points up at the bottom line) — so multi-line text above the point
+ * connects to its bottom edge instead of having the line cut through it.
  */
 interface PointerGeom {
   path: string;
@@ -242,23 +250,30 @@ function buildPointerPath(
   lx: number,
   ly: number,
   fontSize: number,
+  lineCount: number,
   pointer: "curved" | "straight" | "none",
 ): PointerGeom {
   if (pointer === "none") return { path: "" };
   const dx = lx - ax;
   const dy = ly - ay;
 
-  // Target the visual center of the first line so multi-line text
-  // doesn't have the pointer dive below the whole block.
-  const targetY = ly - fontSize * FIRST_LINE_CENTER_RATIO;
+  // Aim at the visual center of the text line nearest the anchor: the
+  // first (top) line when the label is below the anchor, the last
+  // (bottom) line when the label is above it. That keeps the connector
+  // attached to the block's near edge instead of cutting through the
+  // lower lines of text that sits above the point.
+  const lineHeight = fontSize * LINE_HEIGHT_RATIO;
+  const nearestBaseline = dy < 0 ? ly + (lineCount - 1) * lineHeight : ly;
+  const targetY = nearestBaseline - fontSize * LINE_CENTER_RATIO;
 
   // Pure horizontal or vertical → straight line at baseline, no curve.
   // Force straight when explicitly requested.
   if (dx === 0 || dy === 0 || pointer === "straight") {
-    // For straight pointers, aim at first-line-center (so multi-line text
-    // still points at the first line) — but only when the anchor isn't
-    // already at exactly the same Y (pure horizontal offset). The pure
-    // horizontal case stays on the baseline so it's a real horizontal line.
+    // For straight pointers, aim at the near-line center (so multi-line
+    // text above the point connects to its bottom edge) — but only when
+    // the anchor isn't already at exactly the same Y (pure horizontal
+    // offset). The pure horizontal case stays on the baseline so it's a
+    // real horizontal line.
     const ey = dy === 0 ? ly : targetY;
     const segDx = lx - ax;
     const segDy = ey - ay;

package/charts/_shared/chartProps.ts

@@ -103,6 +103,21 @@ export interface ChartCommonProps {
   title?: string;
   /** Styling for the chart title. See `TitleStyle`. */
   titleStyle?: TitleStyle;
+  /**
+   * ARIA role for the chart's root element. Defaults to `"figure"` when an
+   * accessible name is present (from `ariaLabel` or `title`), so screen
+   * readers announce the chart as a labeled figure while its controls (menu,
+   * download) stay reachable. Pass `"img"` to expose it as a single image
+   * (which hides the inner controls from assistive tech), or your own role.
+   */
+  role?: string;
+  /**
+   * Accessible name for the chart, announced by screen readers via the root
+   * element's `aria-label`. Defaults to the `title` prop. The individual
+   * marks aren't exposed to assistive tech, so set this to a short summary of
+   * what the chart shows.
+   */
+  ariaLabel?: string;
   /** Styling for axis labels (the `xLabel` / `yLabel` text). */
   axisLabelStyle?: LabelStyle;
   /** Styling for axis tick labels (the numbers/categories on each axis). */

package/components/SidebarLayout/SidebarLayout.md

@@ -2,6 +2,8 @@
 
 A responsive two-panel layout with a collapsible sidebar and main content area. On mobile, the sidebar becomes an overlay.
 
+When the sidebar is collapsed it is marked [`inert`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inert), so its contents (including the collapse button) are removed from the tab order and the accessibility tree while visually hidden. The expand button is likewise `inert` while the sidebar is open. This keeps keyboard and screen-reader focus on whichever control is actually visible.
+
 ## Demo
 
 <a href="/cfa-simulator/docs/demos/sidebar-layout/index.html" target="_blank">Open in full window ↗</a>

package/components/SidebarLayout/SidebarLayout.vue

@@ -86,7 +86,7 @@ if (globals) {
 <template>
   <div class="SidebarLayout" :data-collapsed="collapsed">
     <div class="SidebarRail">
-      <aside class="Sidebar">
+      <aside class="Sidebar" :inert="collapsed">
         <div class="SidebarScroll">
           <div class="SidebarHeader">
             <button
@@ -105,6 +105,7 @@ if (globals) {
       <button
         type="button"
         class="Toggle Toggle--expand"
+        :inert="!collapsed"
         aria-label="Expand sidebar"
         title="Expand sidebar"
         @click="toggle"

package/index.json

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

package/package.json

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