@cfasim-ui/charts 0.4.11 → 0.4.12

package/dist/BarChart/BarChart.d.ts

@@ -1,5 +1,5 @@
 import { NumberFormat } from '@cfasim-ui/shared';
-import { ChartData, ChartCommonProps, ChartHoverPayload, ChartTooltipBaseProps } from '../_shared/index.js';
+import { ChartData, DateFormat, ChartCommonProps, ChartHoverPayload, ChartTooltipBaseProps } from '../_shared/index.js';
 export type BarChartData = ChartData;
 export interface BarSeries {
     /** Bar values; one entry per category. `y` is accepted as an alias. */
@@ -30,8 +30,11 @@ interface BarChartProps extends ChartCommonProps {
     /**
      * Category labels for the categorical axis. Length should match the
      * longest series. When omitted, indices (0, 1, 2, ...) are used.
+     * Accepts date strings or `Date` objects: when every category parses
+     * as a date, label formatting switches to date mode (bar positions
+     * stay ordinal — they are not time-proportional).
      */
-    categories?: readonly string[];
+    categories?: readonly (string | Date)[];
     /** "vertical" (default, aka column) draws upright bars; "horizontal" draws sideways. */
     orientation?: "vertical" | "horizontal";
     /** "grouped" (default) places series side-by-side; "stacked" stacks them. */
@@ -60,6 +63,16 @@ interface BarChartProps extends ChartCommonProps {
     valueTickFormat?: NumberFormat;
     /** Formatter for category-axis labels. Receives the resolved category string. */
     categoryFormat?: (label: string, index: number) => string;
+    /**
+     * Date-tick formatter for date-mode category labels (auto-detected
+     * when every entry of `categories` parses as a date). Ignored unless
+     * the axis is in date mode. Accepts a `DateFormat` — preset name,
+     * `Intl.DateTimeFormatOptions`, or `(ms, unit?) => string`. When
+     * omitted, the formatter is picked from the chosen tick unit (e.g.
+     * monthly ticks → `"month-year"`). Has no effect when
+     * `categoryFormat` is also set.
+     */
+    dateFormat?: DateFormat;
     /**
      * Fraction of each category slot reserved as gap between groups (0..1).
      * Default 0.2 — i.e. bars/groups fill 80% of their slot.

package/dist/ChoroplethMap/ChoroplethMap.d.ts

@@ -1,5 +1,6 @@
 import { Topology } from 'topojson-specification';
 import { NumberFormat } from '@cfasim-ui/shared';
+import { TitleStyle, LabelStyle } from '../_shared/index.js';
 export type GeoType = "states" | "counties" | "hsas";
 export interface StateData {
     /** FIPS code (e.g. "06" for California, "04015" for a county) or name */
@@ -68,7 +69,15 @@ type __VLS_Props = {
     width?: number;
     height?: number;
     colorScale?: ChoroplethColorScale | ThresholdStop[] | CategoricalStop[];
+    /**
+     * Map title. `\n` in the string creates additional lines, each
+     * adding `titleStyle.lineHeight` (default 18px) of vertical space.
+     */
     title?: string;
+    /** Styling for the map title. See `TitleStyle`. */
+    titleStyle?: TitleStyle;
+    /** Styling for the legend (title, swatch labels, and continuous-scale ticks). */
+    legendStyle?: LabelStyle;
     noDataColor?: string;
     strokeColor?: string;
     strokeWidth?: number;

package/dist/LineChart/LineChart.d.ts

@@ -1,5 +1,5 @@
 import { NumberFormat } from '@cfasim-ui/shared';
-import { ChartData, ChartCommonProps, ChartHoverPayload, ChartTooltipBaseProps } from '../_shared/index.js';
+import { ChartData, LabelStyle, DateFormat, DateTimezone, ChartCommonProps, ChartHoverPayload, ChartTooltipBaseProps } from '../_shared/index.js';
 /**
  * Numeric input accepted by the chart. `number[]` and any standard numeric
  * typed array are supported, so the output of
@@ -7,6 +7,12 @@ import { ChartData, ChartCommonProps, ChartHoverPayload, ChartTooltipBaseProps }
  * without copying into a plain array.
  */
 export type LineChartData = ChartData;
+/**
+ * Accepted shapes for an `x` array. Numeric arrays (typed or plain) plot
+ * as numbers; string-or-`Date` arrays trigger date-axis mode when every
+ * element parses. See the `timezone` prop and `dateAxis` module.
+ */
+export type LineChartXInput = LineChartData | readonly (string | Date)[];
 export interface Series {
     /**
      * Y-values. One of `y` or `data` must be supplied; `y` wins if both
@@ -18,9 +24,10 @@ export interface Series {
     /**
      * Optional x-values, parallel to `y`/`data`. When set, the chart
      * plots points at the given x positions (irregular spacing supported).
-     * When omitted, points are plotted at indices 0, 1, 2, ...
+     * When omitted, points are plotted at indices 0, 1, 2, ... Accepts
+     * date strings or `Date` objects to enable date-axis mode.
      */
-    x?: LineChartData;
+    x?: LineChartXInput;
     color?: string;
     dashed?: boolean;
     strokeWidth?: number;
@@ -55,7 +62,7 @@ export interface Area {
     upper: LineChartData;
     lower: LineChartData;
     /** Optional x-values parallel to `upper`/`lower`. See `Series.x`. */
-    x?: LineChartData;
+    x?: LineChartXInput;
     color?: string;
     opacity?: number;
 }
@@ -80,6 +87,17 @@ export interface AreaSection {
     dashed?: boolean;
     /** Label placement: "below" (default) renders below chart, "inline" renders in legend row, false hides label */
     legend?: "inline" | "below" | false;
+    /**
+     * Style for the area section's primary label text. Defaults: font-size
+     * 11, font-weight 600, color taken from the section's `color`.
+     */
+    inlineLabelStyle?: LabelStyle;
+    /**
+     * Style for the area section's secondary description text. Defaults:
+     * font-size 11, currentColor at 0.6 opacity. Providing `color` drops
+     * the default opacity.
+     */
+    inlineDescriptionStyle?: LabelStyle;
 }
 interface LineChartProps extends ChartCommonProps {
     /** Y-values. Equivalent to `data`. If both are set, `y` wins. */
@@ -90,8 +108,9 @@ interface LineChartProps extends ChartCommonProps {
      * Optional x-values paired with `y`/`data`. When provided, points
      * are plotted at the given x positions instead of at their indices.
      * Ignored when `series` is used — set `x` on each `Series` instead.
+     * Accepts date strings or `Date` objects to enable date-axis mode.
      */
-    x?: LineChartData;
+    x?: LineChartXInput;
     series?: Series[];
     areas?: Area[];
     areaSections?: AreaSection[];
@@ -124,12 +143,21 @@ interface LineChartProps extends ChartCommonProps {
      */
     yTicks?: number | number[];
     /**
-     * Formatter for x-axis tick labels. Accepts a preset name, a printf-style
-     * format string, or a function. The two-arg function form `(value, index)`
-     * is also supported for index-based labels. See `formatNumber` in
-     * `@cfasim-ui/shared`.
+     * Formatter for x-axis tick labels. On a numeric axis, accepts a
+     * preset name, a printf-style format string, or a function (the
+     * two-arg `(value, index)` form is also supported for index-based
+     * labels — see `formatNumber` in `@cfasim-ui/shared`). On a date
+     * axis (auto-detected when every x value parses as a date), accepts
+     * a `DateFormat` instead — see the `dateAxis` module.
+     */
+    xTickFormat?: NumberFormat | ((value: number, index: number) => string) | DateFormat;
+    /**
+     * Timezone used when parsing offset-less ISO strings and rendering
+     * date-axis tick labels. `"utc"` (default) keeps visuals consistent
+     * across viewers; `"local"` uses the browser timezone. Ignored on a
+     * numeric axis.
      */
-    xTickFormat?: NumberFormat | ((value: number, index: number) => string);
+    timezone?: DateTimezone;
     /**
      * Formatter for y-axis tick labels. Accepts a preset name, a printf-style
      * format string, or a function. See `formatNumber` in `@cfasim-ui/shared`.

package/dist/_shared/annotations.d.ts

@@ -39,18 +39,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/dist/_shared/chartProps.d.ts

@@ -1,6 +1,31 @@
 import { NumberFormat } from '@cfasim-ui/shared';
 import { ChartAnnotation } from './annotations.js';
 import { 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
@@ -9,7 +34,19 @@ import { 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;

package/dist/_shared/dateAxis.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Date axis support: parsing, auto-detection, tick selection, and
+ * formatting for chart x-axes that carry temporal data. All functions
+ * are pure (no Vue reactivity, no DOM); chart components call into this
+ * module from their computed setup.
+ *
+ * Design notes:
+ * - Parsing is regex-based, not `Date.parse`. The ES spec parses bare
+ *   `YYYY-MM-DD` as UTC but offset-less `YYYY-MM-DDTHH:mm:ss` as local,
+ *   which makes a `timezone` prop incoherent. Manual parsing keeps the
+ *   timezone interpretation consistent.
+ * - `isDateLike` deliberately rejects plain numbers so existing numeric
+ *   demos (generation indices, day counters) aren't misclassified.
+ * - Tick stepping for month/year (and day/week in local mode) goes
+ *   through `Date` field math so DST and month-length irregularities
+ *   don't drift the tick boundaries.
+ */
+export type DateTickUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";
+export type DateTimezone = "utc" | "local";
+export type DateFormatPreset = "iso" | "iso-datetime" | "year" | "month-year" | "month-day" | "day" | "time" | "datetime" | "medium";
+/**
+ * How to render a tick label on a date axis. Accepts:
+ * - A preset name (`"iso"`, `"month-year"`, ...).
+ * - An `Intl.DateTimeFormatOptions` literal for full control.
+ * - A function receiving the tick's epoch-ms and the tick unit the
+ *   chart picked. Useful for unit-aware custom formatting.
+ */
+export type DateFormat = DateFormatPreset | Intl.DateTimeFormatOptions | ((ms: number, unit?: DateTickUnit) => string);
+/**
+ * Parse `v` into an epoch-ms timestamp under the given timezone.
+ * Accepts `Date` instances and ISO-shaped strings; returns `null` for
+ * anything else (including plain `number`s — see `isDateLike`).
+ */
+export declare function parseDate(v: unknown, tz: DateTimezone): number | null;
+/**
+ * Whether `v` looks like a date value to the auto-detector. Strict:
+ * `Date` instances or ISO-shaped strings only. Plain numbers are *not*
+ * considered date-like so numeric demos can't be silently promoted to
+ * a date axis.
+ */
+export declare function isDateLike(v: unknown): boolean;
+/**
+ * Whether every entry of `values` is date-like and parses cleanly. An
+ * empty array is *not* considered all-dates (auto-detection should
+ * stay opt-in by content).
+ */
+export declare function isAllDates(values: ArrayLike<unknown>, tz: DateTimezone): boolean;
+/**
+ * Choose tick values for a date axis spanning `[minMs, maxMs]`. The
+ * returned `unit` lets the default formatter pick a unit-appropriate
+ * preset (year ticks → "year", month → "month-year", day → "month-day",
+ * etc.) — same trick Vega-Lite uses.
+ */
+export declare function pickDateTicks(minMs: number, maxMs: number, targetCount: number, tz: DateTimezone): {
+    values: number[];
+    unit: DateTickUnit;
+};
+/** All valid preset names. Exported for the disjointness invariant test. */
+export declare const DATE_FORMAT_PRESETS: readonly DateFormatPreset[];
+/**
+ * Format an epoch-ms timestamp into a tick label. When `format` is
+ * undefined, picks a preset based on the tick `unit` (Vega-Lite style:
+ * year ticks read as "2024", month ticks as "Jan 2024", etc.).
+ */
+export declare function formatDate(ms: number, format: DateFormat | undefined, tz: DateTimezone, unit?: DateTickUnit): string;

package/dist/_shared/dateAxis.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/_shared/index.d.ts

@@ -2,7 +2,7 @@ export { snap, niceStep, intervalValues, formatTick, type ChartData, } from './a
 export { computeTickValues, type TickValueOptions } from './computeTicks.js';
 export { scaleFraction, clampExtentForScale, computeLogTickValues, LOG_FLOOR, type ScaleType, } from './scale.js';
 export { useChartSize, type ChartSizeOptions } from './useChartSize.js';
-export { useChartPadding, INLINE_LEGEND_ROW_HEIGHT, type ChartPaddingOptions, type ChartPadding, type ChartBounds, type PositionedLegendItem, } from './useChartPadding.js';
+export { useChartPadding, resolveLabelStyle, INLINE_LEGEND_ROW_HEIGHT, TITLE_LINE_HEIGHT, TITLE_FONT_SIZE, TITLE_FONT_WEIGHT, AXIS_LABEL_FONT_SIZE, TICK_LABEL_FONT_SIZE, TICK_LABEL_OPACITY, LEGEND_FONT_SIZE, type ChartPaddingOptions, type ChartPadding, type ChartBounds, type PositionedLegendItem, } from './useChartPadding.js';
 export { useChartTooltip, type ChartTooltipOptions, } from './useChartTooltip.js';
 export { useChartMenu, type ChartMenuOptions } from './useChartMenu.js';
 export { useChartFullscreen } from './useChartFullscreen.js';
@@ -10,4 +10,5 @@ export { seriesToCsv, categoricalToCsv, type CsvSeries } from './seriesCsv.js';
 export { default as ChartAnnotations } from './ChartAnnotations';
 export type { ChartAnnotation } from './annotations.js';
 export { useChartFoundation, makeTooltipValueFormatter, type ChartFoundationOptions, } from './useChartFoundation.js';
-export type { ChartCommonProps, ChartHoverPayload, ChartTooltipValue, ChartTooltipBaseProps, } from './chartProps.js';
+export type { ChartCommonProps, ChartHoverPayload, ChartTooltipValue, ChartTooltipBaseProps, TitleStyle, LabelStyle, } from './chartProps.js';
+export { parseDate, isDateLike, isAllDates, pickDateTicks, formatDate, DATE_FORMAT_PRESETS, type DateFormat, type DateFormatPreset, type DateTickUnit, type DateTimezone, } from './dateAxis.js';

package/dist/_shared/useChartFoundation.d.ts

@@ -1,10 +1,12 @@
 import { NumberFormat } from '@cfasim-ui/shared';
 import { ChartPadding } from './useChartPadding.js';
 import { TooltipClamp } from '../tooltip-position.js';
+import { TitleStyle } from './chartProps.js';
 export interface ChartFoundationOptions {
     width: () => number | undefined;
     height: () => number | undefined;
     title: () => string | undefined;
+    titleStyle: () => TitleStyle | undefined;
     xLabel: () => string | undefined;
     yLabel: () => string | undefined;
     debounce: () => number | undefined;

package/dist/_shared/useChartPadding.d.ts

@@ -1,5 +1,34 @@
+import { LabelStyle, TitleStyle } from './chartProps.js';
 /** Vertical space reserved per row of the inline legend strip. */
 export declare const INLINE_LEGEND_ROW_HEIGHT = 20;
+/** Default line height (px) for the chart title; overridable per chart. */
+export declare const TITLE_LINE_HEIGHT = 18;
+/** Default font size (px) for the chart title; overridable per chart. */
+export declare const TITLE_FONT_SIZE = 14;
+/** Default font weight for the chart title; overridable per chart. */
+export declare const TITLE_FONT_WEIGHT: number | string;
+/** Default font size (px) for axis labels (`xLabel` / `yLabel`). */
+export declare const AXIS_LABEL_FONT_SIZE = 13;
+/** Default font size (px) for axis tick labels (the numbers on each axis). */
+export declare const TICK_LABEL_FONT_SIZE = 10;
+/** Default fill-opacity for tick labels when no custom color is set. */
+export declare const TICK_LABEL_OPACITY = 0.6;
+/** Default font size (px) for inline legend item labels. */
+export declare const LEGEND_FONT_SIZE = 11;
+/**
+ * Resolve a `LabelStyle` against per-element defaults. Returns the
+ * fields the chart's `<text>` element needs. When `style.color` is set,
+ * the default fill-opacity is dropped so the exact color renders.
+ */
+export declare function resolveLabelStyle(style: LabelStyle | undefined, defaults: {
+    fontSize: number;
+    fillOpacity?: number;
+}): {
+    fontSize: number;
+    fill: string;
+    fontWeight: number | string | undefined;
+    fillOpacity: number | undefined;
+};
 /**
  * Extra space added around the chart's standard layout. A number applies
  * the same amount to all four sides; an object lets you pad sides
@@ -14,6 +43,7 @@ export type ChartPadding = number | {
 };
 export interface ChartPaddingOptions {
     title: () => string | undefined;
+    titleStyle?: () => TitleStyle | undefined;
     xLabel: () => string | undefined;
     yLabel: () => string | undefined;
     /**

package/dist/hsa-mapping.d.ts

@@ -0,0 +1 @@
+export { fipsToHsa, hsaNames } from './ChoroplethMap/hsaMapping.js';

package/dist/hsa-mapping.js

@@ -0,0 +1,2 @@
+import { r as e, t } from "./hsaMapping-Devrp7Rk.js";
+export { t as fipsToHsa, e as hsaNames };