histropediajs 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # HistropediaJS
 
-An embeddable, high-performance, canvas-based timeline engine for rendering events (known as "articles" in the library)over timescales from days to billions of years. Offers smooth pan/zoom, stacking, card layouts, time bands, image loading, and a flexible API.
+An embeddable, high-performance, canvas-based timeline engine for rendering events (known as "articles" in the library) over timescales from days to billions of years. Offers smooth pan/zoom, stacking, card layouts, time bands, image loading, and a flexible API.
 
 - **Canvas-based**: fast rendering and smooth animations
 - **Huge ranges**: day -> billion-year scales, BCE support
@@ -25,10 +25,12 @@ For comprehensive guides, options reference, and API docs, see the hosted docume
 
 ```js
 import Histropedia from 'histropediajs';
-// or named exports if you tree-shake
-import { Timeline, Article, Dmy, Logger } from 'histropediajs';
+// or named exports when you only need part of the public API
+import { Timeline, Article, Chart, Dmy, Logger } from 'histropediajs';
 ```
 
+The package entry point is a bundled ESM file, so named imports are mainly for clarity and smaller application bundles when your bundler can remove unused exports. They do not expose separate per-module entry points.
+
 - UMD (script tag) via CDN or self-host:
   - CDN (jsDelivr):
 
@@ -89,8 +91,8 @@ Each article (event) uses the following minimal shape. Short property aliases ar
   title: string,
   subtitle?: string,
   lane?: string|number,
-  from: { year: number, month?: number, day?: number, precision?: number },
-  to?:  { year: number, month?: number, day?: number, precision?: number },
+  from: { year: number, month?: number, day?: number, precision?: string },
+  to?:  { year: number, month?: number, day?: number, precision?: string },
   isToPresent?: boolean,
   rank?: number,
   starred?: boolean,
@@ -107,7 +109,9 @@ Each article (event) uses the following minimal shape. Short property aliases ar
 Notes:
 
 - BCE years are supported with negative year values; internally year 0 represents 1 BCE. Set `shiftBceDates: true` to shift year input by 1 so that -1 is 1BCE.
-- If `to` is omitted and `isToPresent` is false, the article is treated as an instant event (uses `from`), but the `from.precision` will be used to determined the span of the periodLine.
+- Precision accepts `day`, `month`, `year`, `decade`, `century`, `millennium`, `million-years`, and `billion-years`. The exported `Histropedia.PRECISION_*` constants resolve to these strings. Legacy numeric precision values remain supported but are deprecated.
+- If `to` is omitted and `isToPresent` is false, the article is treated as an instant event (uses `from`), but the `from.precision` determines the span of the period line.
+- Full precision boundary rules and examples: [docs/date-precision.md](docs/date-precision.md)
 
 ## Lanes
 
@@ -162,7 +166,7 @@ timeline.loadLaneArticles('projects', [
 
 ```js
 import Histropedia from 'histropediajs';
-// Histropedia = { Timeline, Article, Lane, Dmy, Logger, ...constants, ...sorters, setDebug, isDebugEnabled, enableDebug, disableDebug }
+// Histropedia = { Timeline, Article, Chart, Lane, TimeBand, Dmy, Logger, ...constants, ...sorters, setDebug, isDebugEnabled, enableDebug, disableDebug }
 ```
 
 ### Classes and utilities
@@ -187,8 +191,10 @@ If `container` is an element, the timeline creates and appends its own `<canvas>
 - `loadLanes(lanes: LaneData[])`: add or update lane definitions.
 - `loadLaneArticles(laneId, articles)`: stamp a lane id onto a batch and forward to `load(...)`.
 - `loadTimeBands(...)`: add timeline-wide background bands.
-- `setStartDate(dmyOrISO: Dmy | string, pixelOffset?: number)`: set left edge date.
-- `setCentreDate(dmyOrISO: Dmy | string, pixelOffset?: number)`: center given date.
+- `loadCharts(...)`: add time-series charts; duplicate ids are skipped with a warning.
+- `loadLaneCharts(laneId, charts)`: stamp a lane id onto a batch and forward to `loadCharts(...)`.
+- `setStartDate(date, options?)`: set the left edge date. `date` accepts a `Dmy`-compatible object or date string; use `options.padding` to place that date away from the left edge, and `options.animation` for animated movement.
+- `setCentreDate(date, pixelOffset?)`: center the given date.
 - `setSize(width: number, height: number)`: resize canvas and reflow.
 - `setZoom(level: number, pivotPixel?: number, offsetX?: number)`: programmatic zoom.
 - `on(event: string, handler)` / `off(event, handler)` / `trigger(event, ...args)`: event system.
@@ -223,6 +229,18 @@ timeline.trigger('my-custom-event', { any: 'payload' });
 
 HistropediaJS uses a centralized `Logger` service to control console output. Logging is **disabled by default** so it will not spam your console unless you explicitly turn it on.
 
+`Histropedia.setDebug()` and the other global debug helpers control logging only. They do not enable visual canvas diagnostics. Visual debug overlays are configured per timeline and are disabled by default:
+
+```js
+const timeline = new Histropedia.Timeline(container, {
+  debugOverlays: {
+    densityRegions: true,
+  },
+});
+```
+
+`debugOverlays.densityRegions` draws non-interactive vertical guides over the timeline at the current article-density region boundaries. It does not change density filtering, stacking, interaction, selection, or saved timeline data.
+
 - **Enable / disable debug logging (default export helpers)**:
 
 ```js
@@ -300,7 +318,8 @@ TimelineOptions tunes layout, interaction, article rendering, and image loading.
 - **Layout**: adjust `width`, `height`, and `verticalOffset` to size and position the canvas.
 - **Navigation**: set `initialDate`, `zoom.initial`, and `enableUserControl` to define how people explore the timeline.
 - **Articles**: control stacking and presentation with `article.autoStacking`, adaptive `defaultCardLayout`, `cardLayoutBreakpoints`, `distanceToBaseline`, and density settings.
-- **Lanes**: use `lanes.defaultStyle`, `lanes.data`, and per-lane `article` overrides for shared-axis multi-lane layouts.
+- **Lanes**: use `lane.defaultStyle`, `lane.data`, and per-lane `article` overrides for shared-axis multi-lane layouts.
+- **Charts**: use `chart.data` or `loadCharts(...)` for read-only line charts, with optional `lane` placement.
 - **Images**: use `image.sanitizer.allowedOrigins`, caching limits, or a custom `image.customSanitizer` to match your content policies.
 - **Events**: register callbacks via the `on` map or helpers such as `onArticleClick`.