@cfasim-ui/docs 0.6.2 → 0.6.4

package/charts/BarChart/BarChart.md

@@ -699,6 +699,29 @@ anchor. `lineColor`, `lineWidth`, and `lineDash` style the line.
   </template>
 </ComponentDemo>
 
+## Accessibility
+
+The chart's `<svg>` is exposed as a single labeled image so screen readers
+announce one accessible name instead of wandering through the individual bars.
+When the chart has a `title`, the `<svg>` gets `role="img"` and an `aria-label`
+set to the title. The menu and download controls live outside the `<svg>`, so
+they stay reachable regardless.
+
+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 `"img"` (e.g. `role="figure"`, or a role of
+your own).
+
 ## API
 
 ## Props
@@ -709,6 +732,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,16 @@ const props = withDefaults(defineProps<BarChartProps>(), {
   valueAxis: true,
 });
 
+// Accessible name for the chart; falls back to the visible title.
+const chartAriaLabel = computed(() => props.ariaLabel ?? props.title);
+// Expose the <svg> as a single labeled image so screen readers announce the
+// name instead of wandering through the individual bars. The menu/download
+// controls live outside the <svg>, so they stay reachable. An explicit `role`
+// prop always wins.
+const chartRole = computed(
+  () => props.role ?? (chartAriaLabel.value ? "img" : 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 });
@@ -1485,7 +1495,13 @@ const columnHeaders = computed<ColumnHeader[]>(() => {
       <div class="chart-sr-only" aria-live="polite">
         {{ isFullscreen ? "Chart expanded to fill window" : "" }}
       </div>
-      <svg ref="svgRef" :width="width" :height="height">
+      <svg
+        ref="svgRef"
+        :width="width"
+        :height="height"
+        :role="chartRole || undefined"
+        :aria-label="chartAriaLabel || undefined"
+      >
         <!-- title -->
         <text
           v-if="title"

package/charts/ChoroplethMap/ChoroplethMap.md

@@ -745,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 |
@@ -759,6 +783,8 @@ set `tooltip-trigger`.
 | `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"` |

package/charts/ChoroplethMap/ChoroplethMap.vue

@@ -126,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;
@@ -225,6 +240,14 @@ const props = withDefaults(
   },
 );
 
+// 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 });
@@ -1694,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"

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,28 @@ until the user clicks Download:
 <LineChart :data="cases" :csv="() => buildCsv(cases, dates)" />
 ```
 
+## Accessibility
+
+The chart's `<svg>` is exposed as a single labeled image so screen readers
+announce one accessible name instead of wandering through the individual marks.
+When the chart has a `title`, the `<svg>` gets `role="img"` and an `aria-label`
+set to the title. The menu and download controls live outside the `<svg>`, so
+they stay reachable regardless.
+
+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 `"img"` (e.g. `role="figure"`, or a role of
+your own).
+
 ## Props
 
 | Prop | Type | Required | Default |
@@ -1071,6 +1143,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,16 @@ const props = withDefaults(defineProps<LineChartProps>(), {
   yScaleType: "linear",
 });
 
+// Accessible name for the chart; falls back to the visible title.
+const chartAriaLabel = computed(() => props.ariaLabel ?? props.title);
+// Expose the <svg> as a single labeled image so screen readers announce the
+// name instead of wandering through the individual marks. The menu/download
+// controls live outside the <svg>, so they stay reachable. An explicit `role`
+// prop always wins.
+const chartRole = computed(
+  () => props.role ?? (chartAriaLabel.value ? "img" : 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 });
@@ -1058,7 +1068,13 @@ const positionedLegendItems = computed(() => {
       <div class="chart-sr-only" aria-live="polite">
         {{ isFullscreen ? "Chart expanded to fill window" : "" }}
       </div>
-      <svg ref="svgRef" :width="width" :height="totalHeight">
+      <svg
+        ref="svgRef"
+        :width="width"
+        :height="totalHeight"
+        :role="chartRole || undefined"
+        :aria-label="chartAriaLabel || undefined"
+      >
         <!-- title -->
         <text
           v-if="title"

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 `<svg>`. Defaults to `"img"` when an accessible
+   * name is present (from `ariaLabel` or `title`), so screen readers announce
+   * the chart as a single labeled image instead of exposing the individual
+   * marks. The menu and download controls sit outside the `<svg>`, so they
+   * stay reachable regardless. Pass your own role to override.
+   */
+  role?: string;
+  /**
+   * Accessible name for the chart, announced by screen readers via the
+   * `<svg>`'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.2",
+  "version": "0.6.4",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [

package/package.json

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