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