@mim/histui 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # Histui
 
-Histui is a reusable, framework-agnostic interactive history timeline package. It can render PastStruct datasets or already-normalized records into a zoomable, pannable, responsive timeline with LOD, clustering, a zoom navigator, hover-linked connectors, axis placement controls, themes, Persian/English UI strings, and explode mode.
+Histui is a reusable, framework-agnostic interactive history timeline package. It can render PastStruct datasets or already-normalized records into a zoomable, pannable, responsive timeline with LOD, clustering, a zoom navigator, hover-linked connectors, blueprint-style measurement indicators, axis placement controls, themes, Persian/English UI strings, and explode mode.
 
 ## Files
 
@@ -13,29 +13,34 @@ Histui is a reusable, framework-agnostic interactive history timeline package. I
 
 ## Basic Usage
 
-```html
-<link rel="stylesheet" href="/path/to/histui/src/styles.css">
-<div id="timeline" style="height: 720px"></div>
-<script type="module">
-  import { createHistuiTimeline } from "/path/to/histui/src/index.js";
-
-  const histui = createHistuiTimeline({
-    container: "#timeline",
-    data: pastStructDataset,
-    language: "en",
-    themeId: "obsidian-lab",
-    explodeEnabled: false,
-    onSelect(record) {
-      console.log("selected", record.id);
-    },
-    onViewportChange(viewport) {
-      console.log(viewport);
-    }
-  });
+Install the package from npm:
+
+```bash
+npm install @mim/histui
+```
+
+Import the JavaScript API and required stylesheet:
 
-  histui.setExplodeEnabled(true);
-  histui.setFilters({ minSignificance: 7 });
-</script>
+```js
+import { createHistuiTimeline } from "@mim/histui";
+import "@mim/histui/styles.css";
+
+const histui = createHistuiTimeline({
+  container: "#timeline",
+  data: pastStructDataset,
+  language: "en",
+  themeId: "obsidian-lab",
+  explodeEnabled: false,
+  onSelect(record) {
+    console.log("selected", record.id);
+  },
+  onViewportChange(viewport) {
+    console.log(viewport);
+  }
+});
+
+histui.setExplodeEnabled(true);
+histui.setFilters({ minSignificance: 7 });
 ```
 
 ## Local Development
@@ -56,7 +61,7 @@ Use a custom port when needed:
 PORT=5180 npm run dev
 ```
 
-Keep this server running while editing package files. For testing the package inside `histui-app-2`, keep the app pointed at the local file dependency (`"histui": "file:../histui"`), run the app dev server in that repo, and reinstall there only after changing package metadata or dependency wiring.
+Keep this server running while editing package files. For testing the package inside `histui-app-2`, run `npm run histui:local` in the app repo to point `@mim/histui` at `../histui`, then run `npm run histui:published` when you want to switch the app back to the published package.
 
 ## Public API
 
@@ -69,7 +74,7 @@ import {
   createDefaultFilters,
   filterRecords,
   DEFAULT_HISTUI_CONFIG
-} from "histui";
+} from "@mim/histui";
 ```
 
 ### `createHistuiTimeline(options)`
@@ -92,6 +97,7 @@ Common options:
 - `axisPlacement`: `{ horizontal, vertical }`, each `"center"`, `"side-start"`, or `"side-end"`.
 - `lodEnabled`: boolean.
 - `explodeEnabled`: boolean.
+- `measurement`: optional override for `config.timeline.measurement`.
 - `analytics.measurementId`: optional Google Analytics measurement id.
 - `onSelect(record, instance)`: event callback.
 - `onViewportChange(viewport, instance)`: event callback.
@@ -112,6 +118,8 @@ Common options:
 - `setAxisPlacement(orientation, placement)`
 - `setLodEnabled(enabled)`
 - `setExplodeEnabled(enabled)`
+- `setMeasurementOptions(options)`
+- `setMeasurementEnabled(enabled)`
 - `setLanguage(language, direction)`
 - `setTheme(themeOrId)`
 - `getState()`
@@ -146,6 +154,11 @@ createHistuiTimeline({
   data,
   config: {
     timeline: {
+      measurement: {
+        enabled: true,
+        transient: true,
+        fadeOutMs: 1200
+      },
       explode: {
         maxVisible: 42,
         layers: 8,
@@ -156,6 +169,8 @@ createHistuiTimeline({
 });
 ```
 
+`timeline.measurement.enabled` draws a dimension-style line across the currently visible timeline span and labels it with the visible year count. Set `timeline.measurement.transient` to `true` to show it only after the viewport changes; it fades out after `fadeOutMs` milliseconds, defaulting to `1200`.
+
 ## Check
 
 ```bash

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Reusable Histui interactive timeline package for PastStruct and normalized historical records.",
   "type": "module",
   "main": "./src/index.js",

package/src/default-config.js

@@ -29,6 +29,11 @@ export const DEFAULT_HISTUI_CONFIG = {
       trackInsetPx: 18,
       minSelectionPixels: 10
     },
+    measurement: {
+      enabled: false,
+      transient: false,
+      fadeOutMs: 1200
+    },
     lod: {
       enabled: true,
       thresholds: [
@@ -117,4 +122,3 @@ export const DEFAULT_HISTUI_CONFIG = {
     }
   ]
 };
-

package/src/index.d.ts

@@ -7,6 +7,24 @@ export interface HistuiTheme {
   colors: Record<string, string>;
 }
 
+export interface HistuiMeasurementConfig {
+  enabled?: boolean;
+  transient?: boolean;
+  showOnChangeOnly?: boolean;
+  visibleOnChangeOnly?: boolean;
+  fadeOutMs?: number;
+  hideAfterMs?: number;
+  offsetPx?: number;
+}
+
+export interface HistuiTimelineConfig {
+  minZoomSpanYears?: number;
+  maxZoomMultiplier?: number;
+  defaultPaddingRatio?: number;
+  measurement?: HistuiMeasurementConfig;
+  [key: string]: unknown;
+}
+
 export interface HistuiConfig {
   app?: {
     name?: string;
@@ -22,7 +40,7 @@ export interface HistuiConfig {
   analytics?: {
     googleAnalyticsMeasurementId?: string;
   };
-  timeline?: Record<string, unknown>;
+  timeline?: HistuiTimelineConfig;
   themes?: HistuiTheme[];
 }
 
@@ -77,6 +95,7 @@ export interface HistuiTimelineOptions<RecordType = any> {
   };
   lodEnabled?: boolean;
   explodeEnabled?: boolean;
+  measurement?: HistuiMeasurementConfig;
   analytics?: {
     measurementId?: string;
   };
@@ -104,6 +123,7 @@ export interface HistuiState<RecordType = any> {
   };
   lodEnabled: boolean;
   explodeEnabled: boolean;
+  measurement: HistuiMeasurementConfig;
 }
 
 export class HistuiTimeline<RecordType = any> {
@@ -120,6 +140,8 @@ export class HistuiTimeline<RecordType = any> {
   setAxisPlacement(orientation: "horizontal" | "vertical", placement: HistuiAxisPlacement): this;
   setLodEnabled(enabled: boolean): this;
   setExplodeEnabled(enabled: boolean): this;
+  setMeasurementOptions(options: HistuiMeasurementConfig): this;
+  setMeasurementEnabled(enabled: boolean): this;
   setLanguage(language: string, direction?: "ltr" | "rtl"): this;
   setTheme(themeOrId: string | HistuiTheme): this;
   applyTheme(theme: HistuiTheme): void;
@@ -134,4 +156,3 @@ export function createDefaultFilters(records: any[], facets?: unknown): HistuiFi
 export function filterRecords<RecordType = any>(records: RecordType[], filters: HistuiFilters): RecordType[];
 export function normalizeFilters(filters?: HistuiFilters, baseFilters?: HistuiFilters): HistuiFilters;
 export const DEFAULT_HISTUI_CONFIG: HistuiConfig;
-

package/src/index.js

@@ -35,6 +35,10 @@ export class HistuiTimeline {
       ...options
     };
     this.config = mergeConfig(DEFAULT_HISTUI_CONFIG, options.config || {});
+    if (options.measurement) {
+      this.config.timeline = this.config.timeline || {};
+      this.config.timeline.measurement = mergeConfig(this.config.timeline.measurement || {}, options.measurement);
+    }
     this.language = options.language || this.config.app.defaultLanguage || "en";
     this.direction = options.direction || dirForLanguage(this.language);
     this.t = options.translator || makeTranslator(this.language);
@@ -232,6 +236,18 @@ export class HistuiTimeline {
     return this;
   }
 
+  setMeasurementOptions(options = {}) {
+    this.config.timeline = this.config.timeline || {};
+    this.config.timeline.measurement = mergeConfig(this.config.timeline.measurement || {}, options);
+    this.timeline.setMeasurementOptions(this.config.timeline.measurement);
+    this.track("timeline_setting_change", { setting: "measurement", value: { ...this.config.timeline.measurement } });
+    return this;
+  }
+
+  setMeasurementEnabled(enabled) {
+    return this.setMeasurementOptions({ enabled: Boolean(enabled) });
+  }
+
   setLanguage(language, direction = dirForLanguage(language)) {
     this.language = language;
     this.direction = direction;
@@ -272,7 +288,8 @@ export class HistuiTimeline {
       orientation: this.orientation,
       axisPlacement: { ...this.axisPlacement },
       lodEnabled: this.lodEnabled,
-      explodeEnabled: this.explodeEnabled
+      explodeEnabled: this.explodeEnabled,
+      measurement: { ...(this.config.timeline?.measurement || {}) }
     };
   }
 

package/src/styles.css

@@ -167,6 +167,160 @@
   pointer-events: none;
 }
 
+.histui-measurement-line {
+  position: absolute;
+  z-index: 240;
+  opacity: 0;
+  pointer-events: none;
+  transform: translateY(-4px);
+  transition:
+    opacity 240ms ease,
+    transform 260ms cubic-bezier(0.16, 0.84, 0.28, 1);
+}
+
+.histui-measurement-line[hidden] {
+  display: none;
+}
+
+.histui-measurement-line.is-visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+.histui-measurement-line[data-orientation="vertical"] {
+  transform: translateX(-4px);
+}
+
+.histui-measurement-line[data-orientation="vertical"].is-visible {
+  transform: translateX(0);
+}
+
+.histui-measurement-rule {
+  position: absolute;
+  inset: 0;
+  color: var(--accent2);
+}
+
+.histui-measurement-rule::before,
+.histui-measurement-rule::after {
+  position: absolute;
+  background: color-mix(in srgb, var(--accent2) 72%, var(--line));
+  content: "";
+}
+
+.histui-measurement-line[data-orientation="horizontal"] .histui-measurement-rule {
+  top: 50%;
+  right: 0;
+  left: 0;
+  height: 0;
+  border-top: 1px dashed color-mix(in srgb, var(--accent2) 72%, var(--line));
+  box-shadow: 0 0 18px color-mix(in srgb, var(--accent2) 12%, transparent);
+}
+
+.histui-measurement-line[data-orientation="horizontal"] .histui-measurement-rule::before,
+.histui-measurement-line[data-orientation="horizontal"] .histui-measurement-rule::after {
+  top: -7px;
+  width: 1px;
+  height: 14px;
+}
+
+.histui-measurement-line[data-orientation="horizontal"] .histui-measurement-rule::before {
+  left: 0;
+}
+
+.histui-measurement-line[data-orientation="horizontal"] .histui-measurement-rule::after {
+  right: 0;
+}
+
+.histui-measurement-line[data-orientation="vertical"] .histui-measurement-rule {
+  top: 0;
+  bottom: 0;
+  left: 50%;
+  width: 0;
+  border-left: 1px dashed color-mix(in srgb, var(--accent2) 72%, var(--line));
+  box-shadow: 0 0 18px color-mix(in srgb, var(--accent2) 12%, transparent);
+}
+
+.histui-measurement-line[data-orientation="vertical"] .histui-measurement-rule::before,
+.histui-measurement-line[data-orientation="vertical"] .histui-measurement-rule::after {
+  left: -7px;
+  width: 14px;
+  height: 1px;
+}
+
+.histui-measurement-line[data-orientation="vertical"] .histui-measurement-rule::before {
+  top: 0;
+}
+
+.histui-measurement-line[data-orientation="vertical"] .histui-measurement-rule::after {
+  bottom: 0;
+}
+
+.histui-measurement-arrow {
+  position: absolute;
+  width: 0;
+  height: 0;
+  filter: drop-shadow(0 0 8px color-mix(in srgb, var(--accent2) 22%, transparent));
+}
+
+.histui-measurement-line[data-orientation="horizontal"] .histui-measurement-arrow {
+  top: 50%;
+  border-top: 5px solid transparent;
+  border-bottom: 5px solid transparent;
+  transform: translateY(-50%);
+}
+
+.histui-measurement-line[data-orientation="horizontal"] .histui-measurement-arrow-start {
+  left: 0;
+  border-left: 9px solid color-mix(in srgb, var(--accent2) 88%, var(--text));
+}
+
+.histui-measurement-line[data-orientation="horizontal"] .histui-measurement-arrow-end {
+  right: 0;
+  border-right: 9px solid color-mix(in srgb, var(--accent2) 88%, var(--text));
+}
+
+.histui-measurement-line[data-orientation="vertical"] .histui-measurement-arrow {
+  left: 50%;
+  border-right: 5px solid transparent;
+  border-left: 5px solid transparent;
+  transform: translateX(-50%);
+}
+
+.histui-measurement-line[data-orientation="vertical"] .histui-measurement-arrow-start {
+  top: 0;
+  border-top: 9px solid color-mix(in srgb, var(--accent2) 88%, var(--text));
+}
+
+.histui-measurement-line[data-orientation="vertical"] .histui-measurement-arrow-end {
+  bottom: 0;
+  border-bottom: 9px solid color-mix(in srgb, var(--accent2) 88%, var(--text));
+}
+
+.histui-measurement-label {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  max-width: min(220px, calc(100vw - 72px));
+  padding: 5px 9px;
+  overflow: hidden;
+  border: 1px solid color-mix(in srgb, var(--accent2) 62%, var(--line));
+  border-radius: 999px;
+  background:
+    linear-gradient(180deg, color-mix(in srgb, var(--surface-raised) 92%, var(--accent2) 8%), color-mix(in srgb, var(--panel) 92%, transparent));
+  box-shadow:
+    0 10px 22px color-mix(in srgb, var(--shadow) 62%, transparent),
+    inset 0 0 0 1px color-mix(in srgb, var(--text) 8%, transparent);
+  color: var(--accent2);
+  font-family: var(--mono-font);
+  font-size: 11px;
+  line-height: 1;
+  text-align: center;
+  text-overflow: ellipsis;
+  transform: translate(-50%, -50%);
+  white-space: nowrap;
+}
+
 .event-card {
   position: absolute;
   left: var(--x);

package/src/timeline-view.js

@@ -64,6 +64,9 @@ export class TimelineView {
     this.viewportAnimation = null;
     this.motionTimer = 0;
     this.explodeAnimationTimer = 0;
+    this.measurementFadeTimer = 0;
+    this.lastMeasurementKey = "";
+    this.suppressMeasurementChange = false;
     this.lastFrame = 0;
     this.lastMetrics = null;
     this.lastItems = { all: [], display: [], hidden: [] };
@@ -73,6 +76,7 @@ export class TimelineView {
     this.clusterTooltip.className = "cluster-tooltip";
     this.clusterTooltip.hidden = true;
     this.stage.append(this.clusterTooltip);
+    this.setupMeasurementLine();
     this.stage.classList.toggle("is-explode-mode", this.explodeEnabled);
     this.setupZoomBar();
 
@@ -177,6 +181,22 @@ export class TimelineView {
     this.zoomBar.addEventListener("keydown", (event) => this.handleZoomKeydown(event));
   }
 
+  setupMeasurementLine() {
+    this.measurementLine = document.createElement("div");
+    this.measurementLine.className = "histui-measurement-line";
+    this.measurementLine.hidden = true;
+    this.measurementLine.setAttribute("aria-hidden", "true");
+    this.measurementLine.innerHTML = `
+      <span class="histui-measurement-rule" aria-hidden="true">
+        <span class="histui-measurement-arrow histui-measurement-arrow-start"></span>
+        <span class="histui-measurement-arrow histui-measurement-arrow-end"></span>
+      </span>
+      <span class="histui-measurement-label"></span>
+    `;
+    this.measurementLabel = this.measurementLine.querySelector(".histui-measurement-label");
+    this.stage.append(this.measurementLine);
+  }
+
   setTranslator(t) {
     this.t = t;
     if (this.zoomBar) {
@@ -231,7 +251,19 @@ export class TimelineView {
     this.render();
   }
 
+  setMeasurementOptions(options = {}) {
+    this.config.timeline = this.config.timeline || {};
+    this.config.timeline.measurement = {
+      ...(this.config.timeline.measurement || {}),
+      ...options
+    };
+    this.lastMeasurementKey = "";
+    if (!this.getMeasurementConfig().enabled) this.hideMeasurementLine({ immediate: true });
+    this.render();
+  }
+
   setRecords(records, { resetView = false } = {}) {
+    this.suppressMeasurementChange = true;
     this.records = records;
     this.idMap = new Map(records.map((record) => [record.id, record]));
     this.hoveredClusterId = null;
@@ -860,6 +892,7 @@ export class TimelineView {
     this.drawClusters(metrics, colors, items.hidden);
     this.renderClusterTooltip(metrics);
     this.renderZoomBar(colors);
+    this.renderMeasurementLine(metrics);
     if (renderCards) this.renderCards(metrics, items.display);
     else this.updateCardHighlightClasses();
     this.renderHint(metrics, items);
@@ -1486,6 +1519,112 @@ export class TimelineView {
     this.clusterTooltip.hidden = false;
   }
 
+  renderMeasurementLine(metrics) {
+    if (!this.measurementLine || !this.measurementLabel) return;
+    const measurement = this.getMeasurementConfig();
+    this.stage.classList.toggle("has-measurement-line", measurement.enabled);
+
+    if (!measurement.enabled || metrics.axisLength < 80) {
+      this.hideMeasurementLine({ immediate: true });
+      return;
+    }
+
+    const span = Math.max(1, Math.round(this.view.end - this.view.start));
+    this.measurementLabel.textContent = this.t("zoomLevel", { span });
+    this.measurementLine.dataset.orientation = metrics.orientation;
+    this.measurementLine.hidden = false;
+
+    if (metrics.orientation === "horizontal") {
+      const y = this.measurementCoordinate(metrics, measurement);
+      this.measurementLine.style.left = `${metrics.axisStart}px`;
+      this.measurementLine.style.top = `${y - 16}px`;
+      this.measurementLine.style.width = `${metrics.axisLength}px`;
+      this.measurementLine.style.height = "32px";
+    } else {
+      const x = this.measurementCoordinate(metrics, measurement);
+      this.measurementLine.style.left = `${x - 16}px`;
+      this.measurementLine.style.top = `${metrics.axisStart}px`;
+      this.measurementLine.style.width = "32px";
+      this.measurementLine.style.height = `${metrics.axisLength}px`;
+    }
+
+    if (!measurement.transient) {
+      this.showMeasurementLine({ persistent: true });
+      return;
+    }
+
+    const key = [
+      metrics.orientation,
+      Math.round(this.view.start * 1000) / 1000,
+      Math.round(this.view.end * 1000) / 1000,
+      metrics.axisLength
+    ].join(":");
+
+    if (!this.lastMeasurementKey || this.suppressMeasurementChange) {
+      this.lastMeasurementKey = key;
+      this.suppressMeasurementChange = false;
+      this.hideMeasurementLine();
+      return;
+    }
+
+    if (key !== this.lastMeasurementKey) {
+      this.lastMeasurementKey = key;
+      this.showMeasurementLine({ fadeOutMs: measurement.fadeOutMs });
+    }
+  }
+
+  getMeasurementConfig() {
+    const measurement = this.config.timeline?.measurement || {};
+    const fadeOutMs = Number(measurement.fadeOutMs ?? measurement.hideAfterMs ?? 1200);
+    return {
+      enabled: measurement.enabled === true,
+      transient: measurement.transient === true ||
+        measurement.showOnChangeOnly === true ||
+        measurement.visibleOnChangeOnly === true,
+      fadeOutMs: Number.isFinite(fadeOutMs) ? Math.max(0, fadeOutMs) : 1200,
+      offsetPx: Number.isFinite(Number(measurement.offsetPx)) ? Number(measurement.offsetPx) : null
+    };
+  }
+
+  measurementCoordinate(metrics, measurement) {
+    const offset = clamp(measurement.offsetPx ?? 32, 20, 110);
+    if (metrics.orientation === "horizontal") {
+      if (metrics.placement === "side-start") return clamp(metrics.axisCoordinate + offset, 18, metrics.height - 18);
+      if (metrics.placement === "side-end") return clamp(metrics.axisCoordinate - offset, 18, metrics.height - 18);
+      return clamp(offset, 18, metrics.height - 18);
+    }
+
+    if (metrics.placement === "center") {
+      return clamp(this.direction === "rtl" ? metrics.width - offset : offset, 18, metrics.width - 18);
+    }
+
+    const side = metrics.axisCoordinate < metrics.width / 2 ? 1 : -1;
+    return clamp(metrics.axisCoordinate + side * offset, 18, metrics.width - 18);
+  }
+
+  showMeasurementLine({ persistent = false, fadeOutMs = 1200 } = {}) {
+    if (!this.measurementLine) return;
+    const wasHidden = this.measurementLine.hidden;
+    this.measurementLine.hidden = false;
+    if (wasHidden) void this.measurementLine.offsetWidth;
+    this.measurementLine.classList.add("is-visible");
+    if (this.measurementFadeTimer) window.clearTimeout(this.measurementFadeTimer);
+    this.measurementFadeTimer = 0;
+    if (persistent) return;
+    this.measurementFadeTimer = window.setTimeout(() => {
+      this.measurementFadeTimer = 0;
+      this.hideMeasurementLine();
+    }, fadeOutMs);
+  }
+
+  hideMeasurementLine({ immediate = false } = {}) {
+    if (!this.measurementLine) return;
+    if (this.measurementFadeTimer) window.clearTimeout(this.measurementFadeTimer);
+    this.measurementFadeTimer = 0;
+    this.measurementLine.classList.remove("is-visible");
+    if (immediate) this.measurementLine.hidden = true;
+  }
+
   renderCards(metrics, displayItems) {
     const axis = metrics.axisCoordinate;
     const mode = this.getLod(this.view.end - this.view.start).labelMode;
@@ -1835,11 +1974,14 @@ export class TimelineView {
     if (this.viewportAnimationFrame) cancelAnimationFrame(this.viewportAnimationFrame);
     if (this.motionTimer) window.clearTimeout(this.motionTimer);
     if (this.explodeAnimationTimer) window.clearTimeout(this.explodeAnimationTimer);
+    if (this.measurementFadeTimer) window.clearTimeout(this.measurementFadeTimer);
     this.clusterTooltip?.remove();
+    this.measurementLine?.remove();
     this.animationFrame = 0;
     this.viewportAnimationFrame = 0;
     this.motionTimer = 0;
     this.explodeAnimationTimer = 0;
+    this.measurementFadeTimer = 0;
   }
 }