histropediajs 1.6.1 → 1.7.0

package/index.d.ts

@@ -19,8 +19,29 @@ export type DeepPartial<T> = T extends (...args: any) => any
       ? { [K in keyof T]?: DeepPartial<T[K]> }
       : T;
 
+/** Remove an override and resolve its default/inherited value. */
+export const UNSET: unique symbol;
+
+/** Sparse setter patch; arrays remain replace-whole values. */
+export type OptionPatch<T> = T extends (...args: any) => any
+  ? T
+  : T extends readonly any[]
+    ? T
+    : T extends object
+      ? { [K in keyof T]?: OptionPatch<T[K]> | typeof UNSET }
+      : T;
+
 /** Built-in card layouts stay in autocomplete while custom registered names still type-check. */
-export type CardLayoutName = 'portrait' | 'landscape' | (string & {});
+export type CardLayoutName =
+  | 'portrait'
+  | 'landscape'
+  | 'title-only'
+  | 'title-subtitle'
+  | 'label'
+  | 'image-text'
+  | 'image-only'
+  | 'pill'
+  | (string & {});
 
 /** Runtime visibility state used by lanes and time bands. */
 export type VisibilityState = 'visible' | 'hidden';
@@ -212,6 +233,9 @@ export interface DmyConstructor {
   new (value: Dmy): DmyInstance;
   readonly prototype: DmyInstance;
   getByDayOfYear(year: number, dayOfYear: number): DmyInstance;
+  /** Period helpers take internal astronomical years (0 = 1 BCE), after any input shift.
+   * Decades group historical tens digits; boundary buckets are 9 through 1 BCE and 1 through 9 CE.
+   */
   CreateAsStartOfPeriod(date: Dmy, precision?: Precision): DmyInstance;
   CreateAsEndOfPeriod(date: Dmy, precision?: Precision): DmyInstance;
   CreateAsExclusiveEndOfPeriod(date: Dmy, precision?: Precision): DmyInstance;
@@ -355,18 +379,32 @@ export interface ArticleStyleText {
   baseline?: 'top' | 'hanging' | 'middle' | 'alphabetic' | 'bottom';
   margin?: number;
   lineHeight?: number;
+  /** Maximum rendered lines: header defaults to 2, subheader to 1. Zero disables text. */
   numberOfLines?: number;
   offsetY?: number;
 }
 
+/** Block padding in non-negative CSS pixels. Each side defaults to zero. */
+export interface ArticleStylePadding {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+
+/** Image margins in non-negative CSS pixels. Unspecified sides resolve to zero. */
+export type ArticleStyleMargin = ArticleStylePadding;
+
 export interface ArticleStyle {
-  /** @defaultValue 150 */
-  width?: number;
-  /** Landscape card layout only. @defaultValue 70 */
-  height?: number;
+  /** Fixed width in CSS pixels, or content/layout width capped by maxWidth. Image-only uses the image aspect ratio with fixed height, or its default width when both dimensions are auto. @defaultValue 150 */
+  width?: number | 'auto';
+  /** Optional finite, non-negative cap in CSS pixels. Only applies when width is 'auto'. */
+  maxWidth?: number;
+  /** Fixed card height or content height. Portrait defaults to 'auto'; landscape to 70. */
+  height?: number | 'auto';
   /** Card background fill color. @defaultValue '#e5e5e5' */
   color?: string;
-  /** Inner card background. @defaultValue '#fff' */
+  /** Inner card background, also used for image-only placeholders while images are loading, missing or failed. @defaultValue '#fff' */
   backgroundColor?: string;
   /** Portrait card layout only. @defaultValue 3 */
   topRadius?: number;
@@ -380,25 +418,33 @@ export interface ArticleStyle {
    */
   maxImageHeight?: number;
   image?: {
+    /** Include the image and its spacing in card sizing and rendering. @defaultValue true */
+    visible?: boolean;
     /** @defaultValue 'natural' */
     shape?: 'natural' | 'square' | 'circle';
-    /** @defaultValue 0 */
-    margin?: number;
-    /** @defaultValue 200 */
+    /** Spacing around the image, including its right edge beside landscape text blocks. A number applies to all sides. Portrait defaults to 0; landscape to 4. */
+    margin?: number | ArticleStyleMargin;
+    /** Maximum rendered image height for all shapes in both built-in layouts, with automatic or numeric card heights. Does not change an explicit card height. @defaultValue 200 */
     maxHeight?: number;
     /** @defaultValue 0 */
     borderRadius?: number;
   };
   header?: {
-    /** Portrait card layout only. @defaultValue 50 */
-    height?: number;
+    /** Explicit allocation, zero to disable, or rendered-line height. Portrait defaults to 50; landscape to 'auto'. */
+    height?: number | 'auto';
+    /** Block fill. Falls back to color in portrait; transparent by default in landscape. */
+    color?: string;
+    /** Included in block height; insets text in addition to text.margin. A number applies to all sides. */
+    padding?: number | ArticleStylePadding;
     text?: ArticleStyleText;
   };
   subheader?: {
-    /** Portrait card layout only. @defaultValue 30 */
-    height?: number;
-    /** Portrait card layout only. @defaultValue '#555' */
+    /** Explicit allocation, zero to disable, or rendered-line height. Portrait defaults to 30; landscape to 'auto'. */
+    height?: number | 'auto';
+    /** Block fill. Defaults to '#555' in portrait and transparent in landscape. */
     color?: string;
+    /** Included in block height; insets text in addition to text.margin. A number applies to all sides. */
+    padding?: number | ArticleStylePadding;
     text?: ArticleStyleText;
   };
   shadow?: {
@@ -412,11 +458,22 @@ export interface ArticleStyle {
     /** @defaultValue 1 */ width?: number;
   };
   connectorLine?: {
-    /** @defaultValue true */ visible?: boolean;
+    /** Show both the connector stroke and arrow. @defaultValue true */ visible?: boolean;
+    /** CSS colour or 'article' for the current state's article colour. @defaultValue 'article' */
+    color?: string;
+    /** Canvas dash lengths in CSS pixels; [] is solid. Applies only to the line stroke. @defaultValue [] */
+    dash?: number[];
+    /** Shape of the line stroke's ends. @defaultValue 'butt' */
+    lineCap?: 'butt' | 'round' | 'square';
     /** @defaultValue 18 */ offsetX?: number;
     /** @defaultValue -20 */ offsetY?: number;
-    /** @defaultValue 1 */ thickness?: number;
+    /** Stroke width in CSS pixels; 0 hides only the stroke. Active default: 2. @defaultValue 1 */
+    thickness?: number;
     arrow?: {
+      /** Show the arrow without changing the line's attachment point. @defaultValue true */
+      visible?: boolean;
+      /** CSS colour, 'article' for the current article colour, or 'inherit' for the resolved line colour. @defaultValue 'inherit' */
+      color?: string;
       /** @defaultValue 16 */ width?: number;
       /** @defaultValue 45 */ height?: number;
     };
@@ -532,7 +589,9 @@ export interface TimelineStyleOptions {
       /** Enable and reserve space for the parent-context row at every scale. @defaultValue false */
       visible?: boolean;
       /** Current major-label levels at which to render parent text. @defaultValue 'all' */
-      levels?: 'all' | Array<
+      levels?:
+        | 'all'
+        | Array<
             | 'millisecond'
             | 'second'
             | 'minute'
@@ -890,6 +949,8 @@ export interface TimelineZoomOptions {
   allowCtrlWheel?: boolean;
   /** 'auto' picks smooth vs discrete from device; 'discrete' forces stepped. @defaultValue 'auto' */
   wheelMode?: 'auto' | 'discrete';
+  /** Touchscreen pinch zoom momentum; wheel/trackpad events retain their existing behaviour. */
+  pinchMomentum?: PinchMomentumOptions;
   /** Animate discrete/notched wheel zoom steps. */
   discreteWheelAnimation?: {
     /** Enable animated wheel zoom. @defaultValue true */
@@ -915,8 +976,23 @@ export interface TimelineZoomOptions {
   };
 }
 
+export interface PinchMomentumOptions {
+  /** Continue zooming after releasing a touchscreen pinch. @defaultValue true */
+  active?: boolean;
+  /** Recent input window in ms used to estimate first-lift velocity, retaining a sparse baseline. @defaultValue 50 */
+  sampleWindow?: number;
+  /** Minimum release velocity in zoom levels/ms. @defaultValue 0.001 */
+  minVelocity?: number;
+  /** Velocity in zoom levels/ms at which momentum stops. @defaultValue 0.0001 */
+  stopVelocity?: number;
+  /** Exponential friction coefficient per ms. Lower values travel farther. @defaultValue 0.005 */
+  friction?: number;
+  /** Maximum zoom momentum duration in ms. @defaultValue 1200 */
+  maxDuration?: number;
+}
+
 export interface PanMomentumOptions {
-  /** Continue timeline panning after a drag release. @defaultValue true */
+  /** Continue timeline panning after a drag or pinch release. @defaultValue true */
   active?: boolean;
   /** Pointer movement sample window in ms used to estimate release velocity. @defaultValue 100 */
   sampleWindow?: number;
@@ -1380,9 +1456,11 @@ export type CardLayoutArticleContext = Article;
 export interface RegisteredCardLayout {
   name: string;
   draw(this: Article, ctx: CanvasRenderingContext2D): void;
+  /** Return a numeric width; with width: 'auto', measure content and layout slots, not image resolution. The size cache applies maxWidth. */
   getWidth?(this: Article): number;
   getHeight?(this: Article): number;
   getIconBox?(this: Article): CardLayoutIconBox | false;
+  getConnectorEnd?(this: Article): CanvasPosition;
   defaultStyle?: ArticleStyle;
   defaultHoverStyle?: ArticleStyle;
   defaultActiveStyle?: ArticleStyle;
@@ -1392,10 +1470,27 @@ export interface RegisteredCardLayout {
 export interface CardLayoutAliasDefinition {
   name: string;
   aliasOf: CardLayoutName;
+  extends?: never;
+}
+
+/** Registration-time snapshot of an existing layout, with optional hook and style overrides. */
+export interface CardLayoutExtensionDefinition
+  extends Partial<
+    Omit<RegisteredCardLayout, 'name' | 'defaultStyle' | 'defaultHoverStyle' | 'defaultActiveStyle'>
+  > {
+  name: string;
+  extends: CardLayoutName;
+  aliasOf?: never;
+  defaultStyle?: OptionPatch<ArticleStyle> | typeof UNSET;
+  defaultHoverStyle?: OptionPatch<ArticleStyle> | typeof UNSET;
+  defaultActiveStyle?: OptionPatch<ArticleStyle> | typeof UNSET;
 }
 
 /** Definition accepted by `Timeline.registerCardLayout(...)`. */
-export type CardLayoutDefinition = RegisteredCardLayout | CardLayoutAliasDefinition;
+export type CardLayoutDefinition =
+  | (RegisteredCardLayout & { aliasOf?: never; extends?: never })
+  | CardLayoutAliasDefinition
+  | CardLayoutExtensionDefinition;
 
 // ------------------------------------------------------------------------------------
 // Classes
@@ -1404,13 +1499,16 @@ export type CardLayoutDefinition = RegisteredCardLayout | CardLayoutAliasDefinit
 export interface AnimOptions {
   /** Duration in ms. @defaultValue 2000 */ duration?: number;
   /** Easing name. @defaultValue 'swing' */ easing?: EasingName;
-  /** Callback when animation completes. */ complete?: () => void;
+  /** Asynchronous completion after the final viewport draw. Takes precedence over complete. */ onComplete?: () => void;
+  /** Legacy alias for onComplete. */ complete?: () => void;
   /** Additional horizontal shift, used by pinch. */ offsetX?: number;
 }
 
 export type FitDateRangePadding = number | { left?: number; right?: number };
 
 export interface FitDateRangeAnimationOptions {
+  /** Legacy completion alias; top-level onComplete takes precedence. */
+  complete?: () => void;
   /** Enable simultaneous animated zooming and panning. @defaultValue false */
   active?: boolean;
   /** Duration in ms. Inherits the viewport animation default when omitted. */
@@ -1420,6 +1518,8 @@ export interface FitDateRangeAnimationOptions {
 }
 
 export interface FitDateRangeOptions {
+  /** Runs asynchronously after the final viewport draw, including immediate/no-op requests. Cancelled requests do not complete. */
+  onComplete?: () => void;
   /** Edge padding in px, or per-side padding for asymmetric fits. @defaultValue 0 */
   padding?: FitDateRangePadding;
   /** Optional animation settings for the fit. */
@@ -1427,6 +1527,8 @@ export interface FitDateRangeOptions {
 }
 
 export interface SetStartDateOptions {
+  /** Runs asynchronously after the final viewport draw, including immediate/no-op requests. Cancelled requests do not complete. */
+  onComplete?: () => void;
   /** 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 })`. */
@@ -1434,6 +1536,8 @@ export interface SetStartDateOptions {
 }
 
 export interface FitArticleRangeOptions {
+  /** Runs asynchronously after the final viewport draw, including immediate/no-op requests. Cancelled requests do not complete. */
+  onComplete?: () => void;
   /** Edge padding in px, or per-side padding for asymmetric fits. @defaultValue 0 */
   padding?: FitDateRangePadding;
   /** Optional animation settings for the fit. */
@@ -1441,6 +1545,8 @@ export interface FitArticleRangeOptions {
 }
 
 export interface FitArticlesOptions {
+  /** Runs asynchronously after the final viewport draw, including immediate/no-op requests. Cancelled requests do not complete. */
+  onComplete?: () => void;
   /** Space in px between the outermost fitted article cards and the viewport edge. @defaultValue 40 */
   padding?: FitDateRangePadding;
   /** Optional article predicate. Defaults to fitting articles that are not `hiddenByFilter`. */
@@ -1546,7 +1652,9 @@ export class Timeline {
   fitArticleRange(article: Article, options?: FitArticleRangeOptions): boolean;
   /** Fit currently unfiltered article cards into the viewport using each article's start date, card width, and connector offset. */
   fitArticles(options?: FitArticlesOptions): boolean;
-  /** Animate to an absolute zoom value using the built-in tween. */
+  /** Settle an existing date-bound overflow; false means no correction or callback. */
+  settleDateBounds(options?: { animate?: boolean; onComplete?: () => void }): boolean;
+  /** Animate to an absolute zoom value. Completion is asynchronous after the final draw. */
   zoomToAnim(newZoom: number, complete?: () => void): void;
 
   // Drawing
@@ -1582,7 +1690,7 @@ export class Timeline {
   // Options
   /** Get or set options via dot-path or partial object. */
   setOption(path: string, value: unknown): void;
-  setOption<T extends DeepPartial<TimelineOptions>>(patch: T): void;
+  setOption<T extends OptionPatch<TimelineOptions>>(patch: T): void;
   setOption(path: string): unknown;
   /** Resize the canvas. */
   setSize(width: number, height: number): void;
@@ -1642,22 +1750,22 @@ export class Article {
 
   /** Update article data at runtime (dot-path or object). */
   setOption(path: string, value: unknown): void;
-  setOption(patch: Partial<ArticleData>): void;
+  setOption(patch: OptionPatch<ArticleData>): void;
   setOption(path: string): unknown;
 
   /** Update normal style (dot-path or object). */
   setStyle(path: string, value: unknown): void;
-  setStyle(style: Partial<ArticleStyle>): void;
+  setStyle(style: OptionPatch<ArticleStyle>): void;
   setStyle(path: string): unknown;
 
   /** Update hover style (dot-path or object). */
   setHoverStyle(path: string, value: unknown): void;
-  setHoverStyle(style: Partial<ArticleStyle>): void;
+  setHoverStyle(style: OptionPatch<ArticleStyle>): void;
   setHoverStyle(path: string): unknown;
 
   /** Update active style (dot-path or object). */
   setActiveStyle(path: string, value: unknown): void;
-  setActiveStyle(style: Partial<ArticleStyle>): void;
+  setActiveStyle(style: OptionPatch<ArticleStyle>): void;
   setActiveStyle(path: string): unknown;
 
   /** Move instantly to absolute canvas position. */
@@ -1693,12 +1801,12 @@ export class TimeBand {
 
   /** Update band data at runtime (dot-path or object). */
   setOption(path: string, value: unknown): void;
-  setOption(patch: Partial<TimeBandData>): void;
+  setOption(patch: OptionPatch<TimeBandData>): void;
   setOption(path: string): unknown;
 
   /** Update band style (dot-path or object). */
   setStyle(path: string, value: unknown): void;
-  setStyle(style: Partial<TimeBandStyle>): void;
+  setStyle(style: OptionPatch<TimeBandStyle>): void;
   setStyle(path: string): unknown;
 }
 
@@ -1739,12 +1847,12 @@ export class Chart {
 
   /** Update chart data at runtime (dot-path or object). */
   setOption(path: string, value: unknown): void;
-  setOption(patch: Partial<Omit<ChartData, 'id'>>): void;
+  setOption(patch: OptionPatch<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(style: OptionPatch<ChartStyle>): void;
   setStyle(path: string): unknown;
 
   /** Resolve the active y-domain for the chart. */
@@ -1764,7 +1872,7 @@ export class Lane {
 
   /** Update lane data at runtime (dot-path or object). */
   setOption(path: string, value: unknown): void;
-  setOption(patch: Partial<LaneData>): void;
+  setOption(patch: OptionPatch<LaneData>): void;
   setOption(path: string): unknown;
 
   /** Hide the lane by setting visibility to "hidden". */
@@ -1790,7 +1898,7 @@ export class Lane {
 
   /** Update lane style (dot-path or object). */
   setStyle(path: string, value: unknown): void;
-  setStyle(style: Partial<LaneStyle>): void;
+  setStyle(style: OptionPatch<LaneStyle>): void;
   setStyle(path: string): unknown;
 }
 
@@ -1805,6 +1913,7 @@ export const ARTICLE_TO_SORTER: ArticleSorter;
 export const ARTICLE_TOP_SORTER: ArticleSorter;
 export const ARTICLE_ROW_SORTER: ArticleSorter;
 export const ARTICLE_RANK_SORTER: ArticleSorter;
+/** Selected first, then starred, then normal; descending rank within each tier. */
 export const ARTICLE_EFFECTIVE_RANK_SORTER: ArticleSorter;
 export const ARTICLE_POSITION_SORTER: ArticleSorter;
 
@@ -1813,6 +1922,7 @@ export const ARTICLE_POSITION_SORTER: ArticleSorter;
 // ------------------------------------------------------------------------------------
 
 export interface HistropediaApi {
+  readonly UNSET: typeof UNSET;
   Timeline: typeof Timeline;
   Article: typeof Article;
   Chart: typeof Chart;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "histropediajs",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "JavaScript library for rendering interactive zoomable timelines in HTML5 canvas.",
   "main": "./dist/histropedia.esm.js",
   "module": "./dist/histropedia.esm.js",
@@ -30,6 +30,9 @@
   },
   "scripts": {
     "dev": "vite serve ./demo --host",
+    "benchmark:build": "node scripts/benchmark-build.mjs",
+    "benchmark:last": "node scripts/benchmark-build.mjs --last",
+    "benchmark:clean": "node scripts/benchmark-build.mjs --clean",
     "build:es": "vite build --config vite.config.js",
     "build:umd": "vite build --config vite.legacy.config.js",
     "build:umd:min": "vite build --config vite.legacy.config.js --mode minified",
@@ -76,18 +79,18 @@
   "license": "SEE LICENSE IN LICENSE",
   "devDependencies": {
     "@eslint/js": "^9.34.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.1.12",
     "eslint": "^9.34.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "globals": "^14.0.0",
     "husky": "^9.1.7",
     "jsdom": "^25.0.1",
-    "lint-staged": "^15.5.2",
+    "lint-staged": "^16.4.0",
     "prettier": "^3.6.2",
     "typescript": "6.0.3",
     "vite": "^7.0.4",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.12"
   },
   "lint-staged": {
     "**/*.{js,mjs,cjs}": [