@cfasim-ui/docs 0.4.11 → 0.4.12

package/charts/LineChart/LineChart.md

@@ -59,6 +59,127 @@ charts, set `x` and `y` (or `data`) on each `Series`.
 
 When `x` is omitted, `y`/`data` values are plotted at indices 0, 1, 2, etc.
 
+### Dates
+
+Pass ISO date strings (`YYYY-MM-DD`) or `Date` objects as `x` and the
+chart auto-detects a date axis: ticks anchor to year / month / week /
+day / hour boundaries depending on the visible range, and labels
+format themselves accordingly. Numeric `x` arrays keep their existing
+behavior — auto-detection is content-driven and never promotes plain
+numbers.
+
+<ComponentDemo>
+  <LineChart
+    :x="['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02', '2026-02-09', '2026-02-16', '2026-02-23', '2026-03-02', '2026-03-09']"
+    :y="[4, 9, 18, 32, 41, 38, 27, 18, 11, 6]"
+    :height="220"
+    y-label="% ED visits"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :x="[
+    '2026-01-05',
+    '2026-01-12',
+    '2026-01-19',
+    '2026-01-26',
+    '2026-02-02',
+    '2026-02-09',
+    '2026-02-16',
+    '2026-02-23',
+    '2026-03-02',
+    '2026-03-09',
+  ]"
+  :y="[4, 9, 18, 32, 41, 38, 27, 18, 11, 6]"
+  :height="220"
+  y-label="% ED visits"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+Override the format via `x-tick-format`. Presets: `"iso"`,
+`"iso-datetime"`, `"year"`, `"month-year"`, `"month-day"`, `"day"`,
+`"time"`, `"datetime"`, `"medium"`. You can also pass an
+`Intl.DateTimeFormatOptions` literal, or a function `(ms, unit?) =>
+string` for full control.
+
+<ComponentDemo>
+  <LineChart
+    :x="['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']"
+    :y="[4, 9, 18, 32, 41]"
+    x-tick-format="iso"
+    :height="220"
+    y-label="% ED visits"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :x="['2026-01-05', '2026-01-12', '2026-01-19', '2026-01-26', '2026-02-02']"
+  :y="[4, 9, 18, 32, 41]"
+  x-tick-format="iso"
+  :height="220"
+  y-label="% ED visits"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
+By default the chart parses bare `YYYY-MM-DD` (and offset-less
+`YYYY-MM-DDTHH:mm:ss`) as UTC and renders tick labels in UTC. Set
+`timezone="local"` to interpret offset-less strings in the browser's
+timezone instead. Strings that include an explicit offset (`Z` or
+`+05:00`) are always parsed exactly as written.
+
+> **Annotations on a date axis.** `ChartAnnotation.x` is always in the
+> chart's resolved coordinate space — that's **epoch-ms** when the axis
+> is in date mode. Pass `Date.UTC(2026, 0, 15)`, `new Date("2026-01-15").getTime()`,
+> or `Date.parse("2026-01-15T00:00:00Z")`. Passing a small integer like
+> `0` will place the annotation at 1970-01-01 (off-screen).
+>
+> **`xLabels` on a date axis.** When both `x: [...date strings]` and
+> `xLabels` are supplied, the date axis wins — `xLabels` is ignored.
+> Date strings carry their own labeling.
+
+### Title
+
+The `title` prop accepts `\n` to break across lines. Use `titleStyle`
+to override `fontSize`, `lineHeight`, `color`, `fontWeight`, and
+`align` (`"left" | "center" | "right"`, default `"left"`). Top padding
+grows automatically for additional lines.
+
+<ComponentDemo>
+  <LineChart
+    :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+    :height="220"
+    :title="'Daily ED visits\nInfluenza-like illness, last 11 days'"
+    :title-style="{ fontSize: 16, lineHeight: 20, color: '#0057b7' }"
+    x-label="Days"
+    y-label="Cases"
+  />
+
+<template #code>
+
+```vue
+<LineChart
+  :data="[0, 4, 8, 15, 22, 30, 28, 20, 12, 5, 2]"
+  :height="220"
+  :title="'Daily ED visits\nInfluenza-like illness, last 11 days'"
+  :title-style="{ fontSize: 16, lineHeight: 20, color: '#0057b7' }"
+  x-label="Days"
+  y-label="Cases"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ### Multiple series
 
 <ComponentDemo>
@@ -558,8 +679,9 @@ Pin callouts to data points with `annotations`. Each annotation anchors at
 respects `xMin` and explicit `x` values), with a pixel
 `offset: { x, y }` for the label position. Text supports `\n` for line
 breaks. A curved
-pointer line connects the anchor to the label, and the label gets a halo
-stroke matching the background so it stays legible over series lines.
+pointer line connects the anchor to the label, and the label gets an
+outline stroke matching the background so it stays legible over series
+lines.
 
 <ComponentDemo>
   <LineChart
@@ -644,9 +766,9 @@ interface ChartAnnotation {
   color?: string; // text / pointer color (default: currentColor)
   fontSize?: number; // default: 13 (matches axis labels)
   fontWeight?: string | number; // default: "normal"
-  haloColor?: string; // background-matched halo (default: var(--color-bg-0, #fff))
-  haloWidth?: number; // default: 3
-  textAnchor?: "start" | "middle" | "end"; // default: derived from offset[0] sign
+  outlineColor?: string; // background-matched outline (default: var(--color-bg-0, #fff))
+  outlineWidth?: number; // default: 3
+  align?: "left" | "center" | "right"; // default: derived from offset[0] sign
   lineColor?: string; // connector-line color override (default: color)
   lineWidth?: number; // default: 1
   lineDash?: string | number | readonly number[]; // SVG stroke-dasharray
@@ -699,7 +821,7 @@ positioned from the anchor as usual via `offset`.
         y: 30,
         offset: { x: -8, y: -6 },
         text: 'Max',
-        textAnchor: 'end',
+        align: 'right',
         pointer: 'ruleFromLeft',
         lineDash: '4 3',
       },
@@ -729,7 +851,7 @@ positioned from the anchor as usual via `offset`.
       y: 30,
       offset: { x: -8, y: -6 },
       text: 'Max',
-      textAnchor: 'end',
+      align: 'right',
       pointer: 'ruleFromLeft',
       lineDash: '4 3',
     },
@@ -807,6 +929,10 @@ until the user clicks Download:
 | `width` | `number` | No | — |
 | `height` | `number` | No | — |
 | `title` | `string` | No | — |
+| `titleStyle` | `TitleStyle` | No | — |
+| `axisLabelStyle` | `LabelStyle` | No | — |
+| `tickLabelStyle` | `LabelStyle` | No | — |
+| `legendStyle` | `LabelStyle` | No | — |
 | `xLabel` | `string` | No | — |
 | `yLabel` | `string` | No | — |
 | `debounce` | `number` | No | — |
@@ -822,7 +948,7 @@ until the user clicks Download:
 | `chartPadding` | `ChartPadding` | No | — |
 | `y` | `LineChartData` | No | — |
 | `data` | `LineChartData` | No | — |
-| `x` | `LineChartData` | No | — |
+| `x` | `LineChartXInput` | No | — |
 | `series` | `Series[]` | No | — |
 | `areas` | `Area[]` | No | — |
 | `areaSections` | `AreaSection[]` | No | — |
@@ -832,7 +958,10 @@ until the user clicks Download:
 | `xMin` | `number` | No | — |
 | `xTicks` | `number \| number[]` | No | — |
 | `yTicks` | `number \| number[]` | No | — |
-| `xTickFormat` | `NumberFormat \| ((value: number, index: number) =&gt; string)` | No | — |
+| `xTickFormat` | `\| NumberFormat
+    \| ((value: number, index: number) =&gt; string)
+    \| DateFormat` | No | — |
+| `timezone` | `DateTimezone` | No | — |
 | `yTickFormat` | `NumberFormat` | No | — |
 | `xLabels` | `string[]` | No | — |
 | `xGrid` | `boolean` | No | — |