@mim/histui 0.2.1 → 0.3.3

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, blueprint-style measurement indicators, 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, broadcast display mode, Persian/English UI strings, and explode mode.
 
 ## Files
 
@@ -30,6 +30,7 @@ const histui = createHistuiTimeline({
   data: pastStructDataset,
   language: "en",
   themeId: "obsidian-lab",
+  displayMode: "standard",
   explodeEnabled: false,
   onSelect(record) {
     console.log("selected", record.id);
@@ -90,6 +91,7 @@ Common options:
 - `language`: default `"en"`.
 - `direction`: optional text direction override.
 - `themeId` or `theme`: built-in theme id or custom theme object.
+- `displayMode`: `"standard"` or `"broadcast"`. Broadcast mode increases legibility and uses overlay-friendly timeline styling.
 - `controls`: render built-in timeline controls. Default `true`.
 - `replace`: clear the container before mounting. Default `true`.
 - `filters`: initial filter object.
@@ -120,6 +122,8 @@ Common options:
 - `setExplodeEnabled(enabled)`
 - `setMeasurementOptions(options)`
 - `setMeasurementEnabled(enabled)`
+- `setDisplayMode("standard" | "broadcast")`
+- `setBroadcastMode(enabled)`
 - `setLanguage(language, direction)`
 - `setTheme(themeOrId)`
 - `getState()`

package/package.json

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

package/src/default-config.js

@@ -4,6 +4,7 @@ export const DEFAULT_HISTUI_CONFIG = {
     defaultLanguage: "en",
     languages: ["en", "fa"],
     defaultTheme: "obsidian-lab",
+    displayMode: "standard",
     orientation: "auto",
     axisPlacement: {
       horizontal: "center",

package/src/i18n.js

@@ -29,6 +29,18 @@ export const UI_STRINGS = {
     uncertainOnly: "Uncertain dates",
     lod: "Adaptive detail",
     explode: "Explode",
+    broadcast: "Broadcast",
+    broadcastMode: "Broadcast Mode",
+    broadcastSettings: "Broadcast settings",
+    exitBroadcast: "Exit broadcast",
+    preset: "Preset",
+    background: "Background",
+    showDetails: "Show selected details",
+    restoreOnLoad: "Restore on load",
+    copyUrl: "Copy viewer URL",
+    copied: "Copied",
+    settings: "Settings",
+    close: "Close",
     resetFilters: "Reset",
     zoomIn: "Zoom in",
     zoomOut: "Zoom out",
@@ -113,6 +125,18 @@ export const UI_STRINGS = {
     uncertainOnly: "تاریخ نامطمئن",
     lod: "جزئیات تطبیقی",
     explode: "نمای انفجاری",
+    broadcast: "پخش",
+    broadcastMode: "حالت پخش",
+    broadcastSettings: "تنظیمات پخش",
+    exitBroadcast: "خروج از پخش",
+    preset: "پیش تنظیم",
+    background: "پس زمینه",
+    showDetails: "نمایش جزئیات انتخاب",
+    restoreOnLoad: "بازیابی هنگام بارگذاری",
+    copyUrl: "کپی نشانی نما",
+    copied: "کپی شد",
+    settings: "تنظیمات",
+    close: "بستن",
     resetFilters: "بازنشانی",
     zoomIn: "بزرگ نمایی",
     zoomOut: "کوچک نمایی",

package/src/index.d.ts

@@ -1,5 +1,6 @@
 export type HistuiOrientation = "auto" | "horizontal" | "vertical";
 export type HistuiAxisPlacement = "center" | "side-start" | "side-end";
+export type HistuiDisplayMode = "standard" | "broadcast";
 
 export interface HistuiTheme {
   id: string;
@@ -31,6 +32,7 @@ export interface HistuiConfig {
     defaultLanguage?: string;
     languages?: string[];
     defaultTheme?: string;
+    displayMode?: HistuiDisplayMode;
     orientation?: HistuiOrientation;
     axisPlacement?: {
       horizontal?: HistuiAxisPlacement;
@@ -83,6 +85,7 @@ export interface HistuiTimelineOptions<RecordType = any> {
   theme?: HistuiTheme;
   title?: string;
   description?: string;
+  displayMode?: HistuiDisplayMode;
   controls?: boolean;
   replace?: boolean;
   selectInitial?: boolean;
@@ -116,6 +119,7 @@ export interface HistuiState<RecordType = any> {
   language: string;
   direction: string;
   themeId: string;
+  displayMode: HistuiDisplayMode;
   orientation: HistuiOrientation;
   axisPlacement: {
     horizontal: HistuiAxisPlacement;
@@ -142,6 +146,8 @@ export class HistuiTimeline<RecordType = any> {
   setExplodeEnabled(enabled: boolean): this;
   setMeasurementOptions(options: HistuiMeasurementConfig): this;
   setMeasurementEnabled(enabled: boolean): this;
+  setDisplayMode(displayMode: HistuiDisplayMode): this;
+  setBroadcastMode(enabled: boolean): this;
   setLanguage(language: string, direction?: "ltr" | "rtl"): this;
   setTheme(themeOrId: string | HistuiTheme): this;
   applyTheme(theme: HistuiTheme): void;

package/src/index.js

@@ -43,6 +43,7 @@ export class HistuiTimeline {
     this.direction = options.direction || dirForLanguage(this.language);
     this.t = options.translator || makeTranslator(this.language);
     this.themeId = options.themeId || this.config.app.defaultTheme;
+    this.displayMode = normalizeDisplayMode(options.displayMode || this.config.app.displayMode);
     this.orientation = options.orientation || this.config.app.orientation || "auto";
     this.axisPlacement = {
       horizontal: options.axisPlacement?.horizontal || this.config.app.axisPlacement?.horizontal || "center",
@@ -77,6 +78,7 @@ export class HistuiTimeline {
     this.root.className = "histui-timeline";
     this.root.lang = this.language;
     this.root.dir = this.direction;
+    this.applyDisplayMode(this.displayMode);
     this.root.innerHTML = `
       <section class="histui-timeline-workbench">
         <header class="histui-timeline-head" data-histui-head></header>
@@ -269,6 +271,27 @@ export class HistuiTimeline {
     return this;
   }
 
+  setDisplayMode(displayMode) {
+    const nextMode = normalizeDisplayMode(displayMode);
+    if (nextMode === this.displayMode) return this;
+    this.displayMode = nextMode;
+    this.applyDisplayMode(nextMode);
+    this.timeline.render();
+    this.track("timeline_setting_change", { setting: "display-mode", value: nextMode });
+    return this;
+  }
+
+  setBroadcastMode(enabled) {
+    return this.setDisplayMode(enabled ? "broadcast" : "standard");
+  }
+
+  applyDisplayMode(displayMode) {
+    if (!this.root) return;
+    const mode = normalizeDisplayMode(displayMode);
+    this.root.dataset.displayMode = mode;
+    this.root.classList.toggle("is-broadcast-mode", mode === "broadcast");
+  }
+
   applyTheme(theme) {
     applyTheme(theme, this.root);
   }
@@ -285,6 +308,7 @@ export class HistuiTimeline {
       language: this.language,
       direction: this.direction,
       themeId: this.themeId,
+      displayMode: this.displayMode,
       orientation: this.orientation,
       axisPlacement: { ...this.axisPlacement },
       lodEnabled: this.lodEnabled,
@@ -459,6 +483,10 @@ function resolveContainer(container) {
   return element;
 }
 
+function normalizeDisplayMode(displayMode) {
+  return displayMode === "broadcast" ? "broadcast" : "standard";
+}
+
 function mergeConfig(base, override) {
   if (Array.isArray(base) || Array.isArray(override)) return override ?? base;
   if (!isPlainObject(base) || !isPlainObject(override)) return override ?? base;

package/src/styles.css

@@ -66,6 +66,22 @@
   grid-template-rows: minmax(0, 1fr) auto;
 }
 
+.histui-timeline.is-broadcast-mode {
+  background: transparent;
+}
+
+.histui-timeline.is-broadcast-mode .histui-timeline-workbench {
+  background:
+    linear-gradient(90deg, color-mix(in srgb, var(--grid) 18%, transparent) 1px, transparent 1px),
+    linear-gradient(0deg, color-mix(in srgb, var(--grid) 14%, transparent) 1px, transparent 1px),
+    color-mix(in srgb, var(--background) 58%, transparent);
+  background-size: 52px 52px;
+}
+
+.histui-timeline.is-broadcast-mode.has-hidden-controls .histui-timeline-workbench {
+  grid-template-rows: minmax(0, 1fr) auto;
+}
+
 .histui-timeline-head {
   display: flex;
   align-items: center;
@@ -451,6 +467,35 @@
   padding: 1px 5px;
 }
 
+.histui-timeline.is-broadcast-mode .event-card {
+  width: 320px;
+  max-width: min(320px, calc(100vw - 42px));
+  max-height: 214px;
+  border-color: color-mix(in srgb, var(--record-color) 68%, var(--text));
+  background:
+    linear-gradient(180deg, color-mix(in srgb, var(--surface-raised) 88%, var(--record-color) 12%), color-mix(in srgb, var(--surface) 92%, transparent));
+  box-shadow:
+    0 22px 52px color-mix(in srgb, var(--shadow) 92%, transparent),
+    0 0 0 1px color-mix(in srgb, var(--record-color) 24%, transparent);
+}
+
+.histui-timeline.is-broadcast-mode .event-card.mode-short {
+  width: 246px;
+  max-height: 146px;
+}
+
+.histui-timeline.is-broadcast-mode .event-card.mode-icon {
+  width: 188px;
+}
+
+.histui-timeline.is-broadcast-mode .card-title {
+  font-size: 15px;
+}
+
+.histui-timeline.is-broadcast-mode .event-card p {
+  font-size: 13px;
+}
+
 .card-date {
   display: block;
   margin-bottom: 6px;

package/src/timeline-view.js

@@ -1595,7 +1595,8 @@ export class TimelineView {
     }
 
     if (metrics.placement === "center") {
-      return clamp(this.direction === "rtl" ? metrics.width - offset : offset, 18, metrics.width - 18);
+      const side = this.direction === "rtl" ? -1 : 1;
+      return clamp(metrics.axisCoordinate + side * offset, 18, metrics.width - 18);
     }
 
     const side = metrics.axisCoordinate < metrics.width / 2 ? 1 : -1;