histropediajs 1.4.0 → 1.5.0

package/index.d.ts

@@ -67,19 +67,22 @@ export interface CardLayoutIconBox extends CanvasPosition {
 // Date and precision
 // ------------------------------------------------------------------------------------
 
-/** Numeric precision constants (public). */
-export const PRECISION_DAY: 11;
-export const PRECISION_MONTH: 10;
-export const PRECISION_YEAR: 9;
-export const PRECISION_DECADE: 8;
-export const PRECISION_CENTURY: 7;
-export const PRECISION_MILLENNIUM: 6;
-export const PRECISION_MILLION_YEARS: 3;
-export const PRECISION_BILLION_YEARS: 1;
+/** Date precision constants (public). */
+export const PRECISION_DAY: 'day';
+export const PRECISION_MONTH: 'month';
+export const PRECISION_YEAR: 'year';
+export const PRECISION_DECADE: 'decade';
+export const PRECISION_CENTURY: 'century';
+export const PRECISION_MILLENNIUM: 'millennium';
+export const PRECISION_MILLION_YEARS: 'million-years';
+export const PRECISION_BILLION_YEARS: 'billion-years';
+
+/** @deprecated Use the equivalent string precision instead. */
+export type LegacyPrecision = 11 | 10 | 9 | 8 | 7 | 6 | 3 | 1;
 
 /**
  * Date precision used by Article/TimeBand ranges.
- * Matches the numeric constants exported above.
+ * Legacy numeric precision values remain supported for backwards compatibility.
  */
 export type Precision =
   | typeof PRECISION_DAY
@@ -89,7 +92,8 @@ export type Precision =
   | typeof PRECISION_CENTURY
   | typeof PRECISION_MILLENNIUM
   | typeof PRECISION_MILLION_YEARS
-  | typeof PRECISION_BILLION_YEARS;
+  | typeof PRECISION_BILLION_YEARS
+  | LegacyPrecision;
 
 /** Plain YMD date parts (no precision). */
 export type DateParts = {
@@ -161,19 +165,24 @@ export const Dmy: DmyConstructor;
 // Public constants (used in options)
 // ------------------------------------------------------------------------------------
 
-export const DENSITY_ALL: 0;
-export const DENSITY_LOW: 1;
-export const DENSITY_MEDIUM: 2;
-export const DENSITY_HIGH: 3;
+export const DENSITY_ALL: 'all';
+export const DENSITY_LOW: 'low';
+export const DENSITY_MEDIUM: 'medium';
+export const DENSITY_HIGH: 'high';
+/** @deprecated Use the equivalent string density instead. */
+export type LegacyDensity = 0 | 1 | 2 | 3;
 export type Density =
   | typeof DENSITY_ALL
   | typeof DENSITY_LOW
   | typeof DENSITY_MEDIUM
-  | typeof DENSITY_HIGH;
+  | typeof DENSITY_HIGH
+  | LegacyDensity;
 
-export const RANGE_ALL: 0;
-export const RANGE_SCREEN: 1;
-export type AutoStackRange = typeof RANGE_ALL | typeof RANGE_SCREEN;
+export const RANGE_ALL: 'all';
+export const RANGE_SCREEN: 'screen';
+/** @deprecated Use the equivalent string auto-stacking range instead. */
+export type LegacyAutoStackRange = 0 | 1;
+export type AutoStackRange = typeof RANGE_ALL | typeof RANGE_SCREEN | LegacyAutoStackRange;
 
 export const MINOR_MARKER: 0;
 export const MAJOR_MARKER: 1;
@@ -471,6 +480,139 @@ export interface TimeBandData {
   style?: TimeBandStyle;
 }
 
+export type ChartType = 'line' | 'area';
+export type ChartScaleSource = 'data' | 'viewport';
+export type ChartScaleTickMode = 'round' | 'exact';
+export type ChartAreaStackingInterpolation = 'linear' | 'step' | 'none';
+
+export interface ChartPointData {
+  date: DateInput;
+  value: number | null;
+}
+
+export interface ChartSeriesStyle {
+  color?: string;
+  lineWidth?: number;
+  lineDash?: number[];
+  area?: {
+    fillColor?: string | null;
+    opacity?: number;
+  };
+  point?: {
+    visible?: boolean;
+    radius?: number;
+    fillColor?: string | null;
+    strokeColor?: string | null;
+    lineWidth?: number;
+  };
+}
+
+export interface ChartGridLineStyle {
+  visible?: boolean;
+  color?: string;
+  /** Stroke thickness in canvas pixels. */
+  thickness?: number;
+}
+
+export interface ChartMinorGridLineStyle extends ChartGridLineStyle {
+  /** Hide minor grid lines while the timeline minor unit size is below this many pixels. @defaultValue 40 */
+  minimumSpacing?: number;
+}
+
+export interface ChartGridLineOptions {
+  x?: {
+    major?: ChartGridLineStyle;
+    minor?: ChartMinorGridLineStyle;
+  };
+  y?: {
+    major?: ChartGridLineStyle;
+  };
+}
+
+export interface ChartStyle {
+  padding?: {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+  };
+  backgroundColor?: string;
+  gridLine?: ChartGridLineOptions;
+  axis?: {
+    visible?: boolean;
+    color?: string;
+    lineWidth?: number;
+  };
+  yAxis?: {
+    visible?: boolean;
+    font?: string;
+    color?: string;
+    margin?: number;
+    /** Thousands separator for numeric y-axis labels. Set to null or an empty string to disable. @defaultValue ',' */
+    thousandsSeparator?: string | null;
+    formatter?: ((value: number) => string) | null;
+  };
+  legend?: {
+    visible?: boolean | 'auto';
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    font?: string;
+    color?: string;
+    markerSize?: number;
+    markerGap?: number;
+    itemGap?: number;
+    inset?: { x?: number; y?: number };
+  };
+  series?: ChartSeriesStyle;
+}
+
+export interface ChartScaleOptions {
+  /** Use all loaded values or only values inside the current viewport. @defaultValue 'data' */
+  source?: ChartScaleSource;
+  /** Include 0 in the computed domain before padding/fixed bounds. @defaultValue false */
+  includeZero?: boolean;
+  /** Fractional padding applied to auto domains. @defaultValue 0.05 */
+  padding?: number;
+  /** Fixed minimum y value. */
+  min?: number;
+  /** Fixed maximum y value. */
+  max?: number;
+  /** Controls how y-axis tick values are generated. @defaultValue 'round' */
+  tickMode?: ChartScaleTickMode;
+  /** Preferred number of y-axis ticks. Rounded ticks may vary slightly. @defaultValue 5 */
+  tickTarget?: number;
+}
+
+export interface ChartTypeOptions {
+  area?: {
+    stacking?: {
+      /** Enable stacked area rendering. When false, area series fill independently from zero. @defaultValue true */
+      active?: boolean;
+      /** How missing series values are resolved across the shared area x-domain. @defaultValue 'linear' */
+      interpolation?: ChartAreaStackingInterpolation;
+    };
+  };
+}
+
+export interface ChartSeriesData {
+  id?: string | number;
+  title?: string;
+  points?: ChartPointData[];
+  style?: ChartSeriesStyle;
+}
+
+export interface ChartData {
+  id: string | number;
+  type?: ChartType;
+  title?: string;
+  lane?: string | number;
+  visibility?: VisibilityState | ((chart: Chart) => VisibilityState);
+  series?: ChartSeriesData[];
+  scale?: ChartScaleOptions;
+  typeOptions?: ChartTypeOptions;
+  area?: { up?: AreaValue; down?: AreaValue };
+  style?: ChartStyle;
+}
+
 export interface LaneLayout {
   height?: number;
   /**
@@ -652,6 +794,11 @@ export interface TimelinePanOptions {
   momentum?: PanMomentumOptions;
 }
 
+export interface TimelineDebugOverlayOptions {
+  /** Draw vertical guides at article-density region boundaries. @defaultValue false */
+  densityRegions?: boolean;
+}
+
 export interface ArticleOptions {
   /** Density filter for visible articles. @defaultValue DENSITY_ALL */
   density?: Density;
@@ -748,6 +895,21 @@ export interface TimeBandOptions {
   data?: TimeBandData[];
 }
 
+export interface ChartOptions {
+  /** Enable drawing of loaded charts. @defaultValue true */
+  visible?: boolean;
+  /** Main-view chart area relative to the shared axis. Lane-scoped charts use lane body geometry. */
+  area?: { up?: AreaValue; down?: AreaValue };
+  /** Global chart grid-line defaults merged into each chart style. */
+  gridLine?: ChartGridLineOptions;
+  /** Default data merged into every loaded chart. */
+  defaultData?: Partial<ChartData>;
+  /** Global default chart style merged into each chart. */
+  defaultStyle?: ChartStyle;
+  /** Charts to load initially. */
+  data?: ChartData[];
+}
+
 export interface LaneOptions {
   /**
    * Enable lane DOM chrome. Article layout still remains lane-aware when lane data is present.
@@ -846,6 +1008,20 @@ export interface ImageOptions {
   decodeMode?: ImageDecodeMode;
 }
 
+export interface TimelineDateBoundsOptions {
+  /** Earliest allowed visible viewport edge. @defaultValue null */
+  minDate?: DateParts | null;
+  /** Latest allowed visible viewport edge. @defaultValue null */
+  maxDate?: DateParts | null;
+  /**
+   * Boundary behaviour during active user interaction.
+   * - 'elastic': allow resisted temporary overflow and settle back when interaction ends.
+   * - 'clamp': prevent overflow immediately.
+   * @defaultValue 'elastic'
+   */
+  overflow?: 'elastic' | 'clamp';
+}
+
 export interface TimelineOptions {
   /** Canvas width in px. @defaultValue 1000 */
   width?: number;
@@ -865,6 +1041,8 @@ export interface TimelineOptions {
     dprMode?: 'stable' | 'native';
     /** Maximum DPR to apply for performance. @defaultValue 3 */ maxDpr?: number;
   };
+  /** Per-timeline visual diagnostics. Independent from global debug logging. */
+  debugOverlays?: TimelineDebugOverlayOptions;
   /** Vertical offset of the main line in px. @defaultValue 40 */
   verticalOffset?: number;
   /** Enable user interactions (wheel/drag/pinch). @defaultValue true */
@@ -875,6 +1053,11 @@ export interface TimelineOptions {
   zoom?: TimelineZoomOptions;
   /** Initial date (top-left when position not offset). @defaultValue {year:1990,month:1,day:1} */
   initialDate?: DateParts;
+  /**
+   * Optional visible viewport date bounds. Bounds constrain viewport edges, not only the centre date.
+   * With both dates set, the settled viewport stays within `[minDate, maxDate]`.
+   */
+  bounds?: TimelineDateBoundsOptions;
   /** Shift BCE input dates by +1 so 1BCE = year 0 internally. @defaultValue false */
   shiftBceDates?: boolean;
   /** Hide the built-in Histropedia branding/footer links. Defaults to false when omitted. */
@@ -897,6 +1080,8 @@ export interface TimelineOptions {
   style?: TimelineStyleOptions;
   /** Time band configuration. */
   timeBand?: TimeBandOptions;
+  /** Chart layer configuration. */
+  chart?: ChartOptions;
   /** Lane configuration. */
   lane?: LaneOptions;
   /** Article configuration. */
@@ -1082,6 +1267,13 @@ export interface FitDateRangeOptions {
   animation?: FitDateRangeAnimationOptions;
 }
 
+export interface SetStartDateOptions {
+  /** Left padding in px for the supplied start date. This only affects the left side. @defaultValue 0 */
+  padding?: number;
+  /** Optional animation settings matching `fitDateRange(..., { animation })`. */
+  animation?: FitDateRangeAnimationOptions;
+}
+
 export interface FitArticleRangeOptions {
   /** Edge padding in px, or per-side padding for asymmetric fits. @defaultValue 0 */
   padding?: FitDateRangePadding;
@@ -1119,6 +1311,7 @@ export class Timeline {
   readonly articles: Article[];
   readonly lanes: Lane[];
   readonly timeBands: TimeBand[];
+  readonly charts: Chart[];
 
   /** Register a reusable card layout globally for all timelines. */
   static registerCardLayout(definition: CardLayoutDefinition): void;
@@ -1132,6 +1325,14 @@ export class Timeline {
   loadLanes(lanes: LaneData[]): void;
   /** Load time bands and redraw. */
   loadTimeBands(bands: TimeBandData[]): void;
+  /** Load new charts and redraw; duplicate ids are skipped with a warning. */
+  loadCharts(charts: ChartData[]): void;
+  /** Remove a chart by id and redraw when found. */
+  removeChart(id: string | number): boolean;
+  /** Remove all loaded charts and redraw. */
+  clearCharts(): void;
+  /** Stamp a lane id onto a batch of charts, load them, and redraw. */
+  loadLaneCharts(laneId: string | number, charts: ChartData[]): void;
   /** Stamp a lane id onto a batch of articles, load them, and redraw. */
   loadLaneArticles(laneId: string | number, articles: ArticleData[]): void;
 
@@ -1139,6 +1340,7 @@ export class Timeline {
   getArticleById(id: string | number): Article | undefined;
   getActiveArticle(): Article | null;
   getLaneById(id: string | number): Lane | undefined;
+  getChartById(id: string | number): Chart | undefined;
   hasArticle(id: string | number): boolean;
 
   // Selection and ordering
@@ -1161,7 +1363,9 @@ export class Timeline {
   setTitle(title: string): void;
 
   // Navigation & view
-  /** Set start date (left edge). String input accepted in "-YYYY-MM-DD" style. */
+  /** Set start date (left edge). Accepts Dmy-compatible objects or strings in "-YYYY-MM-DD" style. */
+  setStartDate(date: Dmy | string, options?: SetStartDateOptions): void;
+  /** @deprecated Use `setStartDate(date, { padding })` instead. */
   setStartDate(date: Dmy | string, pixelOffset?: number): void;
   /** Set centre date using startDate + offset computation. */
   setCentreDate(date: Dmy | string, pixelOffset?: number): void;
@@ -1171,7 +1375,7 @@ export class Timeline {
   setZoom(zoom: number, pivotPixel?: number, offsetX?: number): void;
   /** Smooth pan by pixels (negative = right). */
   goToPixelAnim(pixels: number, options?: AnimOptions): void;
-  /** Smoothly scroll so that the given date is centred/positioned. */
+  /** @deprecated Use `setStartDate(dmy, { padding, animation: { active: true, ... } })` instead. */
   goToDateAnim(dmy: Dmy, options?: AnimOptions): void;
   /** Fit a date range into the viewport with optional edge padding. Dates may be passed in either order; year-only and month-only inputs are treated as full periods. */
   fitDateRange(
@@ -1336,6 +1540,55 @@ export class TimeBand {
   setStyle(path: string): unknown;
 }
 
+export class Chart {
+  id: string | number;
+  owner: Timeline;
+  data: ChartData;
+  type: ChartType;
+  title: string;
+  laneId: string | number | null;
+  area: { up?: AreaValue; down?: AreaValue } | null;
+  scale: ChartScaleOptions;
+  typeOptions: ChartTypeOptions;
+  style: ChartStyle;
+  series: Array<{
+    id: string | number;
+    title: string;
+    style: ChartSeriesStyle;
+    points: Array<{ date: DmyInstance; value: number | null }>;
+  }>;
+  visibility: VisibilityState;
+
+  /** Add one series to this chart and redraw. */
+  addSeries(series: ChartSeriesData): void;
+
+  /** Remove one series by id and redraw when found. */
+  removeSeriesById(id: string | number): boolean;
+
+  /** Return the normalized runtime series with this id. */
+  getSeriesById(id: string | number):
+    | {
+        id: string | number;
+        title: string;
+        style: ChartSeriesStyle;
+        points: Array<{ date: DmyInstance; value: number | null }>;
+      }
+    | undefined;
+
+  /** Update chart data at runtime (dot-path or object). */
+  setOption(path: string, value: unknown): void;
+  setOption(patch: Partial<Omit<ChartData, 'id'>>): void;
+  setOption(path: string): unknown;
+
+  /** Update chart style (dot-path or object). */
+  setStyle(path: string, value: unknown): void;
+  setStyle(style: Partial<ChartStyle>): void;
+  setStyle(path: string): unknown;
+
+  /** Resolve the active y-domain for the chart. */
+  getScaleDomain(drawCycleContext?: RedrawCycleContext): { min: number; max: number };
+}
+
 export class Lane {
   id: string | number;
   owner: Timeline;
@@ -1400,6 +1653,7 @@ export const ARTICLE_POSITION_SORTER: ArticleSorter;
 export interface HistropediaApi {
   Timeline: typeof Timeline;
   Article: typeof Article;
+  Chart: typeof Chart;
   Lane: typeof Lane;
   TimeBand: typeof TimeBand;
   Dmy: DmyConstructor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "histropediajs",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "JavaScript library for rendering interactive zoomable timelines in HTML5 canvas.",
   "main": "./dist/histropedia.esm.js",
   "module": "./dist/histropedia.esm.js",