Changelog

[1.6.1] - 2026-09-05

Fixed

• Infer time precision from date parts. Fixed date-parts objects containing time components defaulting to day precision. When precision is omitted, precision is inferred from the smallest supplied time component; date-only values still default to day precision. An explicitly supplied precision always takes precedence.

• Automatic height fitting after option changes. Updating reserved vertical space with timeline.setOption(...), including parent date-label visibility or height, now refits stacked articles before redrawing when auto-fit is enabled. No manual fitToHeight() call is needed.

[1.6.0] - 2026-09-04

Added

• Opt-in sub-day zoom. Extends the timeline scale through hours, minutes, seconds, and milliseconds using the new ZOOM_HOUR, ZOOM_MINUTE, ZOOM_SECOND, and ZOOM_MILLISECOND levels. Existing timelines retain day-level minimum zoom by default; set zoom.minimum below 0 to opt in. Adaptive major and clock-style minor labels remain readable through scale transitions, ranked density filtering uses time-anchored binary regions, split day/millisecond coordinates preserve precision even at billion-year dates, and chart geometry remains stable with extremely distant offscreen points.
• Millisecond date precision. Extends Dmy, articles, time bands, chart points, viewport bounds, and saved timeline state with optional hour, minute, second, and millisecond fields. Adds matching precision constants and legacy numeric values, precision-aware exclusive range boundaries, time arithmetic and formatting helpers, and compact data keys for sub-day values while preserving date-only serialization.
• Canonical date-time navigation strings. initialDate, date bounds, setStartDate(...), setCentreDate(...), goToDateAnim(...), and fitDateRange(...) now accept timezone-free strings in the form year[-month[-day]][T| ]hour[:minute[:second[.SSS]]], including BCE and deep-year values. Timezone suffixes and fractions finer than milliseconds remain unsupported.
• Sticky major date labels. Adds style.dateLabel.major.sticky with configurable activation and left-edge offset. The default "auto" mode enables sticking only at the month and finer scales where persistent context is useful. When sticking is enabled, the current major label remains visible at the left edge and is pushed out as the next major interval arrives.
• Parent context date labels. Adds an optional, default-off style.dateLabel.parent row for persistent higher-level calendar context without changing existing major or minor labels. The row supports scale-level selection, reserved height, font and colour styling, BCE and deep-time labels, and sticky interval transitions.
• Configurable main-line fills. Adds style.mainLine.color, accepting either a CSS colour string or a top-to-bottom gradient object, with a safe fallback for malformed gradient values.
• State-aware date indicators. Adds style.mainLine.dateIndicators for rectangle or circle indicators with configurable size, colour, and opacity. Base, density-hidden, and active states can be styled independently, including resolving colours from the corresponding article state.
• Configurable chart series palette. Adds chart.seriesColors for replacing the colours assigned cyclically to chart series without an explicit or shared series colour, including runtime updates through timeline.setOption(...).
• Current article style helper. Adds Article#getCurrentStyle() so custom card layouts can retrieve the fully merged style for the current normal, hover, active, or active-hover state without relying on internal methods or duplicating state-selection logic.

Changed

• Article style inheritance. Registered card-layout styles now act as defaults instead of overriding explicitly configured timeline or lane styles. Article styles resolve from base defaults through layout defaults, timeline, lane, and article overrides, with layout-specific values applied after generic values within each scope. This may change rendering where the same property was previously defined by both a registered layout and timeline or lane configuration.
• Default timeline palette. Replaces the previous main-line gradient with a neutral solid fill and refines the default main-line, article-card, and density-hidden indicator colours for clearer visual hierarchy. The previous gradient remains available through style.mainLine.color.
• Chart grid-line defaults. Moves the canonical timeline-wide chart grid-line configuration to chart.defaultStyle.gridLine, alongside the other chart visual defaults. Chart-level style.gridLine continues to override the timeline default.

Deprecated

• Top-level chart grid-line option. chart.gridLine is deprecated in favour of chart.defaultStyle.gridLine. Constructor options and runtime setOption(...) updates continue to accept the old location, emit a deprecation warning, and migrate it to the canonical style path; canonical values win when both forms are supplied.

Removed

• Previously undocumented date-indicator toggle. Removes style.mainLine.showDateIndicators, which was included in the public TypeScript definitions but not documented in the guides. Use style.mainLine.dateIndicators.visible and the new indicator style options instead.

Fixed

• Offscreen chart geometry. Pre-clips line segments and area polygons to chart plot bounds before Canvas rasterization, preventing rendering loss from extremely distant coordinates at sub-day zoom while preserving viewport-edge interpolation and null gaps.
• Dmy precision retention. Object-form construction and date arithmetic retain a supplied precision property without changing existing enumeration or JSON output.
• Mutable Dmy calculations. Dmy#getDayOfYear() now recalculates from the instance’s writable calendar fields instead of returning a stale cached value after mutation.
• Pixel-snapped article connectors. Aligns vertical connector strokes and arrowheads to the same device-pixel, CSS-pixel, or unsnapped mode used by their article cards, including correct alignment for different line widths.
• Card-layout star interaction boxes. Defines getIconBox() around the rectangular star hover/click area only. Built-in layouts now return left, top, width, and height, while their renderers derive pixel-snapped centre and radius values locally; previously released drawing fields remain optional deprecated type properties for compatibility.
• Chart grid-line defaults. Uses a one-pixel default thickness for both major and minor grid lines, and synchronizes the documented minor-line visibility and spacing defaults with the runtime. Runtime updates made through the deprecated chart.gridLine alias now also re-resolve existing charts through its canonical path.

Documentation & Internal

• Sub-day and date-label guidance. Expands the README and date-precision guide with sub-day fields, precision boundaries, navigation strings, zoom configuration, adaptive markers, density behaviour, main-line styling, and state-aware date indicators; adds a dedicated parent-context label guide and runnable sub-day demo.
• Custom card-layout reference. Adds a complete guide to Timeline.registerCardLayout(...), including registry timing, rendering and measurement hooks, selection precedence, aliases, caching, JavaScript, TypeScript, and UMD usage.
• Public typings. Extends TypeScript coverage for date/time values, sub-day constants and precision, main-line fills, date indicators, sticky and parent labels, adaptive marker spacing, navigation inputs, date bounds, and the existing article pixel-snapping modes.
• Demo and regression tooling. Adds v1.4.0, v1.5.0, and v1.5.1 comparison bundles, sub-day scenarios, and a line/area chart selector for the performance demo, with expanded rendering, viewport, density, date-label, chart, and type regression coverage.

[1.5.1] - 2026-07-28

Fixed

• Elastic date-bound dragging. Prevents the viewport from jumping when a pinch gesture returns to a single-pointer drag while elastic date bounds are active.
• Responsive demos. Keeps demo timelines fitted to mobile viewport sizes, including embedded and type-check examples.

Documentation & Internal

• Date-bounds demo coverage. Adds and registers an elastic date-bounds scenario with regression coverage for the scenario runner.
• Development dependency maintenance. Refreshes compatible transitive tooling dependencies, including the patched PostCSS release.

[1.5.0] - 2026-07-14

Added

• Timeline charts. Adds a visual line-chart layer that shares the timeline date scale, with initial chart data via options.chart.data, runtime loading and removal APIs (loadCharts(...), loadLaneCharts(...), removeChart(...), clearCharts()), configurable chart areas, y-scale options, styling, multiple series, data gaps, and lane-scoped charts that render inside lane bodies.
• Date bounds. Adds options.bounds with optional minDate, maxDate, and overflow settings so the visible viewport can be constrained by date range. Programmatic viewport changes, panning, momentum, wheel zoom, and pinch zoom now respect configured bounds.
• Per-timeline debug overlays. Adds options.debugOverlays.densityRegions, disabled by default, to draw non-interactive vertical guides at the current article-density region boundaries. Visual overlays are independent from the global logging-only Histropedia.setDebug() mode.

Changed

• String option selectors. Date precision, article density, and auto-stacking range constants now resolve to descriptive strings such as "month", "all", and "screen". Engine and article defaults now use these string values directly.
• Start-date navigation options. timeline.setStartDate(date, options) now accepts an options object with left-only padding and an animation object matching timeline.fitDateRange(...). The legacy numeric pixelOffset argument still works with a deprecation warning.
• Timeline state-change timing. Emits timeline-state-change only after meaningful timeline interactions settle, such as completed viewport drags, zoom gestures, animations, and article drags, so expensive save handlers are not called on every movement frame.

Deprecated

• Numeric option selectors. Legacy numeric values for date precision, article density, and auto-stacking range remain supported for backwards compatibility but are deprecated in favour of their descriptive string equivalents.
• Legacy date animation API. timeline.goToDateAnim(...) is deprecated in favour of timeline.setStartDate(date, { padding, animation: { active: true, ... } }).

Fixed

• Article removal state changes. timeline.removeArticleById(...) now emits timeline-state-change when an article is removed.
• Date input normalization. Methods that normalize dates through getDmyFromInput(...), including timeline.setStartDate(...), now accept plain { year, month?, day? } objects, default missing month and day values to 1, and apply BCE shifting without mutating the caller’s date object.
• Animated day-range fitting. Keeps timeline.fitDateRange(...) zoom animation smooth for short day-level ranges by preserving fractional day spans during intermediate zoom calculations.
• Browser-zoomed notched wheel input. Detects browser zoom-scaled mouse-wheel deltas so smooth discrete wheel zoom animation still runs when the page is zoomed.
• Discrete wheel zoom restacking. Restacks articles when a smooth discrete wheel zoom animation settles, preventing overlaps after a single notched wheel action.

[1.4.0] - 2026-05-08

Added

• Multi-lane timelines. Adds options.lane, ArticleData.lane, timeline.loadLanes(...), timeline.loadLaneArticles(...), and a new Lane runtime API, enabling events to be organised into separate horizontal lanes while sharing a single bottom timeline axis. Maintains timeline.articles as a flat array for backwards compatibility.
• Lane rendering and layout. Introduces DOM-based lane backgrounds and titles with CSS-first styling (inline styles only when explicitly set). Supports per-lane article option overrides (e.g. default styles), and handles density grouping, row stacking, and baseline scaling independently within each lane.
• Lane layout controls. Adds options for lane header visibility, top gap, height weighting, and period-line baseline/anchor spacing.
• Lane visibility and reordering APIs. Adds lane hide/show helpers and convenience methods on both timeline and Lane for reordering by index, relative position, or adjacent step.
• Timeline pan momentum. Adds configurable momentum after viewport drag release via options.pan.momentum, with controls for enabling, velocity sampling, friction, stop velocity, and maximum duration.
• Discrete wheel zoom animation. Adds options.zoom.discreteWheelAnimation, enabled by default for notched mouse-wheel input, providing smooth animated zoom transitions that preserve the cursor anchor while repeated wheel input continues the zoom fluidly.
• Date range fitting API. Adds timeline.fitDateRange(start, end, options) to zoom and position the timeline so a supplied date range fits the viewport. Accepts either Dmy instances or plain { year, month?, day? } inputs, treats year-only and month-only dates as full periods for fit calculations, supports symmetric or per-side horizontal padding, and can optionally animate zoom and pan together.
• Article range fitting APIs. Adds timeline.fitArticleRange(article, options) to fit a single article’s full period, and timeline.fitArticles(options) to fit all currently unfiltered article cards into the viewport.
• Responsive baseline distance. Adds responsive baseline settings under article.distanceToBaseline, with value as the static fallback and responsive.byCardLayout providing per-card-layout ratios and bounds. Responsive distances are chosen from the resolved default card layout; unmatched layouts use value.
• Article card layout breakpoints. Adds ordered article.cardLayoutBreakpoints for height-based layout overrides, including defaults that switch low-height timelines to landscape when portrait cards would be unusable.
• Article pixel snapping control. Adds article.rendering.pixelSnap with device, css, and none modes so article rendering can trade crisp device-pixel alignment for smoother subpixel motion when needed.
• Public TimeBand exports. Exposes the TimeBand constructor as both Histropedia.TimeBand on the default export and a direct named ESM export. This brings it in line with other main classes such as Timeline and Article, and enables advanced prototype-based extensions.

Changed

• Package distribution metadata and typings. Aligns package entry points and named exports, declares supported Node.js versions, limits published package contents to runtime essentials, and fills missing index typings for package consumers.
• Default wheel zoom responsiveness. Increases the default options.zoom.wheelStep from 0.1 to 0.2 so wheel zooming feels more responsive out of the box.

Deprecated

• Legacy baseline option. article.distanceToMainLine is deprecated in favour of article.distanceToBaseline.value. The old option name still maps through as an explicit numeric override for backwards compatibility, including lane.article.distanceToMainLine.

Fixed

• False double-click detection. Tightens click tracking so article-dblclick and timeline-dblclick only fire after two completed clicks on the same target, clears pending click state when touch input turns into a pinch, and suppresses legacy synthetic mouse events that could make a single tap register twice.
• Compatibility wrapper for article.activated(). Maintains functionality of article method removed in v1.3.0 by triggering article-click event.
• Occluded article hover states. Prevents articles from entering hover styles when the pointer is over another DOM element stacked above the timeline, while preserving window-level drag tracking beyond the canvas edge.
• Timeline item ID matching. Compares article and lane IDs without implicit type coercion so values such as 1 and "1" are treated as distinct IDs.
• Boolean article opacity values. Normalizes boolean opacity values to numeric values, which occurred
• Article pixel jitter during slow pans. Stabilizes article rendering by using a shared snapped origin for card internals, aligning connector endpoints to the rendered card position, and snapping portrait and landscape card geometry to the active device-pixel grid by default.

Documentation & Internal

• Lane docs and demo coverage. Adds lane examples to the README, demo scenarios, public type fixtures, and unit tests, and updates the type-check script so the verification pipeline passes consistently.

[1.3.3] - 2026-02-04

Fixed

• Time Band opacity bleed. Resets the canvas globalAlpha at the start of each Time Band draw so the overlay does not inherit the last rendered article’s fade opacity when it has no image.

[1.3.2] - 2026-01-25

Fixed

• Legacy event handler this context. Preserves the timeline instance as this inside legacy event handlers (onSave, onArticleClick, onArticleDoubleClick, onRedraw) to maintain backward compatibility with code that relies on this referring to the timeline.

[1.3.1] - 2025-12-18

Fixed

• HiDPI shadows. Aligns shadow dimensions with the canvas DPR to keep shadows constant size and offset according to CSS pixels for high-density displays.
• Card border toggles. Prevents landscape cards from drawing borders when the border width is set to 0. This was defaulting to 1px if not set, or keeping previously set value if individual articles differed.
• Card height refresh. Recalculates card height when border width changes to fix misalignment of the bottom of the article card.

[1.3.0] - 2025-12-04

Added

• Time Bands overlay API. Introduces a schema and styling model that mirrors article layouts, configured through options.timeBand and adjustable post-init with setOption/setStyle so bands share the same visibility, alignment, and reserved-space controls as articles.
• Pluggable article card layouts. A new feature to draw articles using different layouts, which can then be adjusted as before using the style options. Launches with two built-in options: portrait (the layout used before this release) and the new landscape layout. Layouts can have style options specific to the layout, which override normal style options. Choose layout using options.article.defaultCardLayout, or for individual articles call article.setCardLayout. Developers can register their own custom layouts, giving them full control over the rendering and click area.
• EventManager. Debuts a dedicated event surface that registers via options.on or the timeline .on helper, spanning 18 events such as timeline-render-start, timeline-render-end, timeline-click, timeline-state-change, article-activated, pointer enter/leave/move, zoom, wheel, pinch, and viewport drag notifications, plus .off for unsubscribing.
• Rendering and UX options. Provides options.canvas for DPR-aware high definition canvases, cursor configuration, toggles for date indicators and article connectors, marker extension controls, and new article style options such as image shape.
• Logger and debug toggles. Ships a centralized Histropedia.Logger plus Histropedia.enableDebug/setDebug helpers so developers can turn on deprecation warnings and internal diagnostics during development.
• Article data defaults. options.article.defaultData provides a way to set defaults for any fields when loading article data.
• TypeScript definitions. Coverage now spans image options, dragging vicinities, article data (Dmy helpers and function properties), PointerEvent payloads, deprecated handler types, easing options, and more so the full API stays consumable in TypeScript projects.

Changed

• Image loading pipeline. Uses a byte-aware cache, safe eviction ordering, dynamic queue prioritization, fetchPriority hints, visible-only enqueueing, aborts for out-of-range requests, and adds createImageBitmap support so decoded bitmaps can flow directly into canvas draws.
• Pointer and tween engine. Runs entirely on vanilla pointer/tween utilities (no jQuery), bringing smooth trackpad zoom, unified pointer/touch handling, and new animation helpers for article moves, fades, pans, and zoom transitions.
• Event naming and payloads. Aligns with the new EventManager by standardizing PointerEvent payloads, routing background clicks through timeline-click, renaming article-double-click to article-dblclick, and mapping every legacy hook onto the modern event names for backwards compatibility.
• Text and layout calculations. Hardens via memoized helpers, a binary-search ellipsize routine, and a new font watcher that forces text measurement cache invalidation on load to eliminate fixing on placeholder font sizes.

Deprecated

All scheduled for removal in v2.0.0

• Legacy timeline event handlers. onRedraw now maps to timeline-render-end/timeline-render-start, while onSave maps to timeline-state-change.
• Legacy Article event handlers. onArticleClick and onArticleDoubleClick are replaced by article-select/article-click and article-dblclick events from the EventManager. These options will be removed in 2.0.0.
• Deprecated style option. maxImageHeight article style option is superceded by image.maxHeight to work alongside other new image style options.
• Deprecated article default option. periodLine.defaultHide article option is superceded by the new generic defaults setting using defaultData.hidePeriodLine.

Removed

• jQuery dependencies. Removes every jQuery dependency (DOM size helpers, mousewheel, animation shims, dummy nodes) for a completely dependency free bundle.
• Legacy handlers and pub/sub. Removes legacy click, double-click, and background click handlers plus the old pub/sub implementation after migrating to the EventManager.
• Unused modules. Removes unused storage modules and legacy helper functions.

Fixed

• Drag release handling. Keeps dragging state from sticking when users release the mouse or touch outside the browser window or an embedded iframe so interactions always complete cleanly.
• Font loading. Prevents squashed text when custom fonts were still loading during timeline init by waiting for the new font watcher to confirm real fonts before caching text measurements.
• Article sorting with string IDs. Fixed stable sort order for articles with string id values when their ranks are equal by properly handling string comparison in the fallback sorting logic.

Security

• Adds URL sanitization and configurable image sanitizer options so external article imagery cannot inject unsafe URLs.
• Hardens the deep merge helper against prototype pollution, ensures branding links open with noopener/noreferrer, and documents the threat model in SECURITY.md.
• Patches npm audit findings and refreshes all dev dependencies to eliminate known vulnerabilities.

Documentation & Internal

• Event documentation. Documents the expanded event surface in a new guide, simplifies the README, and adds explicit license information so the API reference stays accurate.
• Demo tooling. Adds a version selector, previous release support, restored legacy widths, and performance scenarios so regressions are easy to compare between releases.
• Distribution pipeline. Introduces ES Module and UMD bundles, overhauls the bundler/dev asset pipeline, and adds a build test HTML file to verify outputs.
• Source restructuring. Moves code into service-specific folders, splits helpers, simplifies the font watcher, and reorganizes article defaults and engines for maintainability.
• Tooling and automation. Adds ESLint with auto-fix hooks, Husky/pre-commit automation, new testing scripts, updated Vitest packages, and commit automation for consistent CI runs.
• Debugging and performance infrastructure. Adds logger toggles, a scenario runner, a performance demo with small or large image modes, non-fullscreen test scenarios, and versioned demos to aid regression testing.

Note: All notable changes to this project are documented here, starting from v1.3.0 onward.