histropediajs 1.6.2 → 1.7.0

package/README.md

@@ -108,7 +108,7 @@ Each article (event) uses the following minimal shape. Short property aliases ar
   hidePeriodLine?: boolean,
   hiddenByFilter?: boolean,
   imageUrl?: string,
-  cardLayout?: 'portrait' | 'landscape',
+  cardLayout?: 'portrait' | 'landscape' | 'title-only' | 'title-subtitle' | 'label' | 'image-text' | 'image-only' | 'pill' | string,
   style?: object,
   hoverStyle?: object,
   activeStyle?: object
@@ -167,6 +167,81 @@ the base indicator settings. Within `activeStyle`, `color: 'article'` uses the c
 colour; the same value in the base or hidden style uses its resolved normal colour. Indicator
 `opacity` accepts values from `0` to `1`.
 
+## Connector line styling
+
+Set `connectorLine` in an article style to control the line and its filled arrow independently.
+The normal defaults preserve the existing appearance:
+
+```js
+connectorLine: {
+  visible: true,
+  color: 'article',
+  dash: [],
+  lineCap: 'butt',
+  offsetX: 18,
+  offsetY: -20,
+  thickness: 1,
+  arrow: {
+    visible: true,
+    color: 'inherit',
+    width: 16,
+    height: 45,
+  },
+}
+```
+
+`connectorLine.color` accepts a CSS colour string or `'article'`, which follows the article's
+resolved colour in its current normal, hover, active, or active-hover state. `arrow.color` also
+accepts `'inherit'` to follow the resolved connector-line colour. Keywords are resolved during
+drawing and remain unchanged in the stored styles, including those returned by `getCurrentStyle()`.
+Explicit colours remain fixed across states unless another style layer overrides them.
+
+For a grey dashed line with an arrow that follows the current article colour:
+
+```js
+const timeline = new Timeline(container, {
+  article: {
+    defaultStyle: {
+      connectorLine: {
+        color: '#aaa',
+        dash: [4, 3],
+        lineCap: 'round',
+        arrow: { color: 'article' },
+      },
+    },
+    defaultHoverStyle: {
+      connectorLine: { dash: [] }, // Solid while hovered.
+    },
+  },
+});
+```
+
+| Option                 | Behaviour                                                                                                             |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `visible: false`       | Hides both the connector stroke and arrow.                                                                            |
+| `arrow.visible: false` | Hides only the arrow; the line still reaches its configured card attachment point, including `offsetX` and `offsetY`. |
+| `thickness: 0`         | Hides only the line stroke, allowing an arrow-only appearance.                                                        |
+| `dash`                 | Canvas dash/gap lengths in CSS pixels, applied only to the stroke; `[]` is solid and `[4, 3]` is dashed.              |
+| `lineCap`              | Stroke end shape: `'butt'` (default), `'round'`, or `'square'`.                                                       |
+
+All settings support sparse overrides through the existing style cascade: library defaults,
+registered card-layout defaults, timeline defaults, timeline layout overrides, lane defaults,
+lane layout overrides, then article styles. Hover and active overrides use the same cascade;
+when both states apply, active values win conflicts and hover-only values remain. Arrays such as
+`dash` are replaced by an override, so `[]` resets a dashed style to solid.
+
+The existing active style sets `thickness: 2`. For an arrow-only connector in every state, override
+both the normal and active thickness:
+
+```js
+article.setStyle({ connectorLine: { thickness: 0 } });
+article.setActiveStyle({ connectorLine: { thickness: 0 } });
+```
+
+Connector settings do not change the period bar or date indicators. The period bar continues to
+use the current article colour and its existing period-line options. Date indicators retain the
+normal/active colour rules described above, including ignoring hover colours.
+
 ## Parent context date labels
 
 Set `style.dateLabel.parent.visible` to `true` to add a persistent calendar-parent row beneath the
@@ -238,6 +313,19 @@ import Histropedia from 'histropediajs';
 - **Logger**: centralized console logger with `setEnabled(boolean)`
 - **Constants**: zoom levels, precisions, density controls, etc.
 
+### Removing configuration overrides
+
+Use `Histropedia.UNSET` (also a named export) to clear an override and return to its default or inherited style:
+
+```js
+timeline.setOption('zoom.wheelSpeed', Histropedia.UNSET);
+article.setStyle({ header: { color: Histropedia.UNSET, height: 'auto' } });
+article.setHoverStyle('border.width', Histropedia.UNSET);
+article.setActiveStyle('border.width', Histropedia.UNSET);
+```
+
+An explicit value stays an override; removing it lets the value follow the lower configuration layers. `null` and `undefined` retain their existing meanings. See [clearing configuration overrides](docs/unset.md) for lane/timeline styles, optional properties, and layout extensions.
+
 ### Timeline constructor
 
 ```ts
@@ -262,6 +350,8 @@ If `container` is an element, the timeline creates and appends its own `<canvas>
 - `on(event: string, handler)` / `off(event, handler)` / `trigger(event, ...args)`: event system.
 - `select(articleId)`: bring to the front and trigger the `article-select` event.
 
+See [viewport navigation completion](docs/navigation.md) for `options.onComplete`, asynchronous timing, cancellation, and legacy callback compatibility.
+
 ### Events
 
 Register handlers using `timeline.on(name, callback)` or pass `options.on = { [name]: handler }`.
@@ -387,6 +477,113 @@ TimelineOptions tunes layout, interaction, article rendering, and image loading.
 
 Find the full option reference, defaults, and advanced patterns in the hosted docs: https://js.histropedia.com/documentation.
 
+### Article auto width
+
+Set `width: 'auto'` to size article cards from their content, with an optional `maxWidth` cap:
+
+```js
+const timeline = new Timeline(container, {
+  article: {
+    defaultStyle: { width: 'auto', maxWidth: 320 },
+  },
+});
+
+// The same styles work on individual articles and in lane/layout style overrides.
+timeline.getArticleById('example')?.setStyle({ width: 'auto', maxWidth: 280 });
+```
+
+Cards use their content width up to the cap, then use the existing wrapping and layout rules.
+Numeric `width` values keep their existing behaviour and ignore `maxWidth`. Without a cap,
+auto width can grow to fit the content.
+Auto width is driven by text and layout spacing, not image resolution. Portrait images fit
+the measured card width; landscape cards reserve their existing image slot. Cached bitmaps
+are sized for that drawing area.
+
+The [`image-only` preset](docs/custom-card-layouts.md#image-only) uses a filled
+`backgroundColor` placeholder for missing, loading or failed images. Automatic
+dimensions assume a square until loading succeeds, then follow the image aspect
+ratio; fixed dimensions remain fixed.
+
+Custom layouts use the same size cache and cap. An omitted `getWidth` hook measures standard
+title/subtitle text, block padding, margins, and border; a custom hook can supply its own content width.
+Use `this.getWidth()` in drawing code for the resolved numeric width. See
+[custom card measurements](docs/custom-card-layouts.md#auto-width) for details.
+
+### Article heights, text blocks and images
+
+Both portrait and landscape support numeric or automatic card and text-block heights,
+multi-line subtitles, block background colours, uniform or per-side block `padding`, and `image.visible`. Padding
+defaults to zero, adds to automatic block height, and sits inside numeric block heights. Automatic blocks allocate
+complete lines; numeric blocks retain their text placement and may overflow. Numeric total card heights clip
+that overflow. `image.maxHeight` caps all image shapes in both layouts, with automatic
+or numeric card heights, without changing an explicitly set card height.
+Fixed portrait images keep their normal width and crop vertically at
+the smaller of `image.maxHeight` and the remaining card height. Automatic landscape height keeps a stable thumbnail
+while text grows. Both layouts accept numeric or per-side `image.margin`, such as
+`{ top: 4, right: 12, bottom: 4, left: 4 }`. Landscape margins surround the thumbnail, including the gap
+before header/subheader backgrounds; automatic width includes both horizontal margins.
+See [article sizing](docs/article-sizing.md) for defaults, overflow priority,
+style migration notes and examples, or open the **Article sizing** demo.
+
+### Pan and pinch momentum
+
+Touchscreen pinches continue both zooming and panning after release, using recent finger
+spacing and midpoint movement. Zoom stays anchored to the moving pinch midpoint. Configure
+zoom inertia under `zoom.pinchMomentum`; its pan component uses `pan.momentum`:
+
+```js
+const timeline = new Timeline(container, {
+  zoom: {
+    pinchMomentum: {
+      active: true,
+      sampleWindow: 50,
+      minVelocity: 0.001,
+      stopVelocity: 0.0001,
+      friction: 0.005,
+      maxDuration: 1200,
+    },
+  },
+  pan: {
+    momentum: {
+      active: true,
+      sampleWindow: 100,
+      minVelocity: 0.01,
+      stopVelocity: 0.005,
+      friction: 0.005,
+      maxDuration: 5600,
+    },
+  },
+});
+```
+
+These are the defaults. Each component can be disabled independently with `active: false`.
+`sampleWindow` and `maxDuration` are milliseconds. Zoom velocities are zoom levels per
+millisecond; pan velocities are pixels per millisecond. Lower `friction` means a longer glide.
+Numeric momentum settings must be positive finite numbers; other values use the defaults.
+
+Zoom velocity uses the last 50 ms of input by default, including a baseline for sparse
+gestures. Input timestamps determine speed; there is no launch-speed cap or multiplier.
+Friction and maximum duration control the glide after launch, independently of that speed.
+
+Momentum begins after both fingers lift. Release velocity is measured at the first lift;
+a staggered release under 100 ms preserves it. Holding still or continuing a one-finger
+drag discards the old pinch velocity. A single release-tail movement must exceed 16 CSS
+pixels to become a pan; sustained movement uses 8 pixels. The threshold is consumed
+without a jump, and pan inertia requires genuine movement history.
+
+During a repeated pinch, zoom can coast for up to 80 ms while the next fingers land.
+The first pinch movement takes over at the current scale without a jump or extra gain.
+A tap, hold, one-finger drag, wheel input, or `setZoom()` stops that coast. Pan momentum
+stops on contact. Zoom and date bounds remain enforced.
+
+For physical-device checks, the development demo includes **Record pinch** and
+**Save pinch data** controls. See [touchscreen testing](docs/pinch-momentum.md).
+
+Smooth touchpad zoom already follows the browser's continuous wheel events, including any
+device/OS momentum. No additional inertia is added to that stream. Trackpad pinch events
+reported as Ctrl+wheel continue to follow `zoom.allowCtrlWheel` (default `false`). Notched
+mouse wheels retain `zoom.discreteWheelAnimation` and have no release momentum.
+
 ### Sub-day zoom
 
 Sub-day zoom is opt-in, so existing timelines keep exactly the same minimum scale. The default
@@ -435,6 +632,7 @@ negative or longer than four digits, and fractional seconds contain one to three
 ```js
 timeline.setStartDate('2026-08-13T12:30:15.250', {
   animation: { active: true, duration: 500 },
+  onComplete: () => console.log('Viewport navigation finished'),
 });
 
 timeline.setCentreDate('-44-03-15 09:01');
@@ -448,7 +646,7 @@ period.
 
 ### Card layouts
 
-Two built-in layouts are registered: `portrait` and `landscape`. By default the timeline falls back to `article.defaultCardLayout: 'portrait'`, while ordered `article.cardLayoutBreakpoints` can override that fallback using the currently available vertical space for article cards.
+The two base layouts are `portrait` (vertical) and `landscape` (horizontal). Six built-in presets provide common content and shape options: `title-only`, `title-subtitle`, `label`, `image-text` and `image-only` extend portrait, while `pill` extends landscape with a circular thumbnail and rounded ends. See [preset descriptions and examples](docs/custom-card-layouts.md#built-in-presets), or try the **Built-in card presets** demo scenario. By default the timeline falls back to `article.defaultCardLayout: 'portrait'`, while ordered `article.cardLayoutBreakpoints` can override that fallback using the currently available vertical space for article cards.
 
 ```js
 const timeline = new Timeline(container, {
@@ -552,6 +750,11 @@ npm run dev
 
 Then open the served URL (Vite dev server). Switch scenarios via the toolbar.
 
+Choose **Card layout inheritance** (or add `?scenario=card-layout-inheritance&metrics=0`)
+to compare built-in cards with custom layouts created using `extends`. The scenario
+includes style-only presets, an extension of a custom layout, and a drawing-hook
+override. Hover, select and star the cards to check their inherited behaviour.
+
 ## Browser support / Build targets
 
 ### Build targets