@cfasim-ui/docs 0.4.11 → 0.4.13

package/charts/_shared/ChartAnnotations.vue

@@ -29,8 +29,8 @@ const props = withDefaults(
 const DEFAULT_FONT_SIZE = 13;
 const DEFAULT_FONT_WEIGHT = "normal";
 const BOLD_FONT_WEIGHT = 700;
-const DEFAULT_HALO_COLOR = "var(--color-bg-0, #fff)";
-const DEFAULT_HALO_WIDTH = 3;
+const DEFAULT_OUTLINE_COLOR = "var(--color-bg-0, #fff)";
+const DEFAULT_OUTLINE_WIDTH = 3;
 const DEFAULT_LINE_WIDTH = 1;
 const ANCHOR_GAP_PX = 4;
 const LABEL_GAP_PX = 6;
@@ -55,8 +55,8 @@ interface RenderedAnnotation {
   fontSize: number;
   fontWeight: string | number;
   color: string;
-  haloColor: string;
-  haloWidth: number;
+  outlineColor: string;
+  outlineWidth: number;
   pointerPath: string;
   lineColor: string;
   lineWidth: number;
@@ -66,6 +66,7 @@ interface RenderedAnnotation {
   // renders correctly in Safari (which doesn't support `context-stroke` on
   // SVG markers). Present only when an arrow should be drawn.
   arrowTip?: { x: number; y: number; angle: number };
+  arrowTransform: string;
   rule?: { x1: number; y1: number; x2: number; y2: number };
 }
 
@@ -128,13 +129,15 @@ const items = computed<RenderedAnnotation[]>(() => {
     const color = a.color ?? "currentColor";
     const fontSize = a.fontSize ?? DEFAULT_FONT_SIZE;
     const fontWeight = a.fontWeight ?? DEFAULT_FONT_WEIGHT;
-    const haloColor = a.haloColor ?? DEFAULT_HALO_COLOR;
-    const haloWidth = a.haloWidth ?? DEFAULT_HALO_WIDTH;
+    const outlineColor = a.outlineColor ?? DEFAULT_OUTLINE_COLOR;
+    const outlineWidth = a.outlineWidth ?? DEFAULT_OUTLINE_WIDTH;
     const lineColor = a.lineColor ?? color;
     const lineWidth = a.lineWidth ?? DEFAULT_LINE_WIDTH;
     const lineDash = resolveDash(a.lineDash);
-    const textAnchor =
-      a.textAnchor ?? (offsetX > 0 ? "start" : offsetX < 0 ? "end" : "middle");
+    const alignMap = { left: "start", center: "middle", right: "end" } as const;
+    const align =
+      a.align ?? (offsetX > 0 ? "left" : offsetX < 0 ? "right" : "center");
+    const textAnchor = alignMap[align];
 
     let rule: RenderedAnnotation["rule"];
     let pointerPath = "";
@@ -164,14 +167,17 @@ const items = computed<RenderedAnnotation[]>(() => {
       fontSize,
       fontWeight,
       color,
-      haloColor,
-      haloWidth,
+      outlineColor,
+      outlineWidth,
       pointerPath,
       lineColor,
       lineWidth,
       lineDash,
       arrow: wantArrow,
       arrowTip,
+      arrowTransform: arrowTip
+        ? `translate(${arrowTip.x} ${arrowTip.y}) rotate(${arrowTip.angle})`
+        : "",
       rule,
     });
   }
@@ -302,12 +308,45 @@ function buildPointerPath(
 <template>
   <g class="chart-annotations" pointer-events="none">
     <template v-for="(item, i) in items" :key="i">
+      <!--
+        Outline pass. Each shape is rendered first in `outlineColor` at a
+        wider stroke so the rule line, pointer, and arrow tip stay legible
+        over busy series. Outline elements carry `class="annotation-outline"`
+        so consumers (and tests) can target the "real" shape directly.
+        Outlines deliberately drop `stroke-dasharray` — a dashed outline
+        would expose gaps where legibility matters most.
+      -->
+      <line
+        v-if="item.rule && item.outlineWidth > 0"
+        v-bind="item.rule"
+        class="annotation-outline"
+        :stroke="item.outlineColor"
+        :stroke-width="item.lineWidth + item.outlineWidth"
+        stroke-linecap="round"
+      />
+      <path
+        v-if="item.pointerPath && item.outlineWidth > 0"
+        :d="item.pointerPath"
+        class="annotation-outline"
+        fill="none"
+        :stroke="item.outlineColor"
+        :stroke-width="item.lineWidth + item.outlineWidth"
+        stroke-linecap="round"
+      />
+      <polygon
+        v-if="item.arrowTip && item.outlineWidth > 0"
+        points="0,0 -6,-3 -6,3"
+        class="annotation-outline"
+        :fill="item.outlineColor"
+        :stroke="item.outlineColor"
+        :stroke-width="item.outlineWidth"
+        stroke-linejoin="round"
+        :transform="item.arrowTransform"
+      />
+      <!-- Actual shapes. -->
       <line
         v-if="item.rule"
-        :x1="item.rule.x1"
-        :y1="item.rule.y1"
-        :x2="item.rule.x2"
-        :y2="item.rule.y2"
+        v-bind="item.rule"
         :stroke="item.lineColor"
         :stroke-width="item.lineWidth"
         :stroke-dasharray="item.lineDash"
@@ -332,7 +371,7 @@ function buildPointerPath(
         v-if="item.arrowTip"
         points="0,0 -6,-3 -6,3"
         :fill="item.lineColor"
-        :transform="`translate(${item.arrowTip.x} ${item.arrowTip.y}) rotate(${item.arrowTip.angle})`"
+        :transform="item.arrowTransform"
       />
       <text
         :x="item.textX"
@@ -341,8 +380,8 @@ function buildPointerPath(
         :font-size="item.fontSize"
         :font-weight="item.fontWeight"
         :fill="item.color"
-        :stroke="item.haloColor"
-        :stroke-width="item.haloWidth"
+        :stroke="item.outlineColor"
+        :stroke-width="item.outlineWidth"
         stroke-linejoin="round"
         paint-order="stroke fill"
       >

package/charts/_shared/annotations.ts

@@ -37,18 +37,23 @@ export interface ChartAnnotation {
    */
   fontWeight?: string | number;
   /**
-   * Halo (stroke) color drawn behind the text so the label stays legible
-   * against busy chart elements. Defaults to `var(--color-bg-0, #fff)` so
-   * it matches the page background out of the box.
+   * Color of the legibility outline drawn behind the text, pointer/rule
+   * line, and arrow tip. Defaults to `var(--color-bg-0, #fff)` so it
+   * matches the page background out of the box.
    */
-  haloColor?: string;
-  /** Halo stroke width in pixels. Default: 3. */
-  haloWidth?: number;
+  outlineColor?: string;
   /**
-   * SVG text-anchor for the label. When omitted, derived from the sign of
-   * `offset.x`: positive → `start`, negative → `end`, zero → `middle`.
+   * Outline stroke width in pixels. Applied to the text (via paint-order
+   * stroke), and added to `lineWidth` for the pointer/rule line and
+   * arrow tip outline pass. Set to `0` to disable the outline. Default: 3.
    */
-  textAnchor?: "start" | "middle" | "end";
+  outlineWidth?: number;
+  /**
+   * Horizontal alignment of the label relative to its anchor position.
+   * When omitted, derived from the sign of `offset.x`: positive →
+   * `"left"`, negative → `"right"`, zero → `"center"`.
+   */
+  align?: "left" | "center" | "right";
   /** Pointer- or rule-line color override. Defaults to `color`. */
   lineColor?: string;
   /** Pointer- or rule-line width in pixels. Default: 1. */

package/charts/_shared/chartProps.ts

@@ -8,6 +8,33 @@ import type { NumberFormat } from "@cfasim-ui/shared";
 import type { ChartAnnotation } from "./annotations.js";
 import type { ChartPadding } from "./useChartPadding.js";
 
+/**
+ * Visual styling for the chart title. All fields optional; unspecified
+ * fields fall back to the chart's defaults (font-size 14, line-height 18,
+ * font-weight 600, currentColor, align "left"). `lineHeight` is in pixels
+ * and controls spacing between lines when the title contains `\n`.
+ */
+export interface TitleStyle {
+  fontSize?: number;
+  lineHeight?: number;
+  color?: string;
+  fontWeight?: number | string;
+  /** Horizontal alignment of the title. Default: `"left"`. */
+  align?: "left" | "center" | "right";
+}
+
+/**
+ * Visual styling for axis labels, tick labels, and legend text. Each
+ * field is optional; unspecified fields fall back to that element's
+ * default. When `color` is set, the default fill-opacity (used by tick
+ * labels) is dropped so the exact color is rendered.
+ */
+export interface LabelStyle {
+  fontSize?: number;
+  color?: string;
+  fontWeight?: number | string;
+}
+
 /**
  * Props common to every cartesian chart component. Anything specific to
  * the chart type (series shape, layout, value-axis details) lives on the
@@ -16,7 +43,19 @@ import type { ChartPadding } from "./useChartPadding.js";
 export interface ChartCommonProps {
   width?: number;
   height?: number;
+  /**
+   * Chart title. `\n` in the string creates additional lines, each
+   * adding `titleStyle.lineHeight` (default 18px) of vertical space.
+   */
   title?: string;
+  /** Styling for the chart title. See `TitleStyle`. */
+  titleStyle?: TitleStyle;
+  /** Styling for axis labels (the `xLabel` / `yLabel` text). */
+  axisLabelStyle?: LabelStyle;
+  /** Styling for axis tick labels (the numbers/categories on each axis). */
+  tickLabelStyle?: LabelStyle;
+  /** Styling for the inline legend item labels. */
+  legendStyle?: LabelStyle;
   xLabel?: string;
   yLabel?: string;
   debounce?: number;