@mim/histui 0.1.0

package/README.md

@@ -0,0 +1,167 @@
+# 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.
+
+## Files
+
+- `src/index.js` - public package API
+- `src/index.d.ts` - public TypeScript declarations
+- `src/styles.css` - required component styles
+- `src/timeline-view.js` - low-level timeline renderer
+- `src/paststruct.js` - PastStruct normalization helpers
+- `examples/basic.html` - no-build browser example
+
+## 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);
+    }
+  });
+
+  histui.setExplodeEnabled(true);
+  histui.setFilters({ minSignificance: 7 });
+</script>
+```
+
+## Local Development
+
+Run the package directly from this repository when you want to develop `histui` itself and see source changes immediately in the browser:
+
+```bash
+npm run dev
+```
+
+Open [http://127.0.0.1:5175](http://127.0.0.1:5175). The dev server serves `examples/basic.html`, which imports `../src/index.js` and `../src/styles.css`, so it always uses the local package source instead of a published build.
+
+Changes in `src/`, `examples/`, `README.md`, `PUBLISHING.md`, or `package.json` trigger an automatic browser reload. The server disables caching so style and JavaScript edits show up on the next reload without extra build steps.
+
+Use a custom port when needed:
+
+```bash
+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.
+
+## Public API
+
+```js
+import {
+  HistuiTimeline,
+  createHistuiTimeline,
+  normalizeTimelineData,
+  normalizePastStruct,
+  createDefaultFilters,
+  filterRecords,
+  DEFAULT_HISTUI_CONFIG
+} from "histui";
+```
+
+### `createHistuiTimeline(options)`
+
+Creates and mounts a timeline instance.
+
+Common options:
+
+- `container`: CSS selector or element. Required.
+- `data`: PastStruct dataset document, single PastStruct record, or array of records.
+- `records`: normalized records or raw PastStruct record array.
+- `config`: partial config merged with `DEFAULT_HISTUI_CONFIG`.
+- `language`: default `"en"`.
+- `direction`: optional text direction override.
+- `themeId` or `theme`: built-in theme id or custom theme object.
+- `controls`: render built-in timeline controls. Default `true`.
+- `replace`: clear the container before mounting. Default `true`.
+- `filters`: initial filter object.
+- `orientation`: `"auto"`, `"horizontal"`, or `"vertical"`.
+- `axisPlacement`: `{ horizontal, vertical }`, each `"center"`, `"side-start"`, or `"side-end"`.
+- `lodEnabled`: boolean.
+- `explodeEnabled`: boolean.
+- `analytics.measurementId`: optional Google Analytics measurement id.
+- `onSelect(record, instance)`: event callback.
+- `onViewportChange(viewport, instance)`: event callback.
+- `onRecordsChange(records, instance)`: event callback.
+- `onTrack(name, payload, instance)`: analytics/telemetry callback.
+
+### Instance Methods
+
+- `setData(data, options)`
+- `setRecords(records, options)`
+- `setFilters(filters, options)`
+- `resetFilters(options)`
+- `select(recordId, options)`
+- `fit(options)`
+- `zoomBy(factor)`
+- `setViewRange(start, end, options)`
+- `setOrientation(orientation)`
+- `setAxisPlacement(orientation, placement)`
+- `setLodEnabled(enabled)`
+- `setExplodeEnabled(enabled)`
+- `setLanguage(language, direction)`
+- `setTheme(themeOrId)`
+- `getState()`
+- `destroy()`
+
+## Filters
+
+`setFilters()` accepts the same filter shape used internally:
+
+```js
+histui.setFilters({
+  search: "revolution",
+  recordTypes: ["event", "period"],
+  types: ["political"],
+  minSignificance: 6,
+  mediaOnly: false,
+  uncertainOnly: false,
+  fromYear: 1800,
+  toYear: 2026
+});
+```
+
+Set-like fields can be arrays or `Set` instances.
+
+## Config
+
+The package exposes `DEFAULT_HISTUI_CONFIG`. You can override only the keys you need:
+
+```js
+createHistuiTimeline({
+  container,
+  data,
+  config: {
+    timeline: {
+      explode: {
+        maxVisible: 42,
+        layers: 8,
+        animationMs: 700
+      }
+    }
+  }
+});
+```
+
+## Check
+
+```bash
+npm run check
+```
+
+## Publishing
+
+See [PUBLISHING.md](./PUBLISHING.md) for the npm publishing checklist.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mim/histui",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.1.0",
+  "description": "Reusable Histui interactive timeline package for PastStruct and normalized historical records.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "style": "./src/styles.css",
+  "exports": {
+    ".": "./src/index.js",
+    "./styles.css": "./src/styles.css"
+  },
+  "sideEffects": [
+    "./src/styles.css"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "node scripts/dev-server.mjs",
+    "check": "node scripts/check.mjs"
+  },
+  "keywords": [
+    "history",
+    "timeline",
+    "paststruct",
+    "visualization"
+  ],
+  "license": "UNLICENSED"
+}

package/src/analytics.js

@@ -0,0 +1,25 @@
+let analyticsReady = false;
+
+export function initializeAnalytics({ measurementId, appName = "Histui" } = {}) {
+  const id = String(measurementId || "").trim();
+  if (!id || analyticsReady || typeof window === "undefined") return;
+
+  window.dataLayer = window.dataLayer || [];
+  window.gtag = function gtag() {
+    window.dataLayer.push(arguments);
+  };
+  window.gtag("js", new Date());
+  window.gtag("config", id, { app_name: appName });
+
+  const script = document.createElement("script");
+  script.async = true;
+  script.src = `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(id)}`;
+  document.head.append(script);
+  analyticsReady = true;
+}
+
+export function trackAnalyticsEvent(name, params = {}) {
+  if (typeof window === "undefined" || typeof window.gtag !== "function") return;
+  window.gtag("event", name, params);
+}
+

package/src/default-config.js

@@ -0,0 +1,120 @@
+export const DEFAULT_HISTUI_CONFIG = {
+  app: {
+    name: "Histui",
+    defaultLanguage: "en",
+    languages: ["en", "fa"],
+    defaultTheme: "obsidian-lab",
+    orientation: "auto",
+    axisPlacement: {
+      horizontal: "center",
+      vertical: "side-start"
+    }
+  },
+  analytics: {
+    googleAnalyticsMeasurementId: ""
+  },
+  timeline: {
+    minZoomSpanYears: 2,
+    maxZoomMultiplier: 2.5,
+    defaultPaddingRatio: 0.08,
+    inertia: {
+      enabled: true,
+      friction: 0.92,
+      wheelFriction: 0.86,
+      minVelocity: 0.02
+    },
+    navigator: {
+      enabled: true,
+      animationMs: 420,
+      trackInsetPx: 18,
+      minSelectionPixels: 10
+    },
+    lod: {
+      enabled: true,
+      thresholds: [
+        { spanYears: 2600, minSignificance: 9, labelMode: "icon" },
+        { spanYears: 1100, minSignificance: 8, labelMode: "short" },
+        { spanYears: 450, minSignificance: 7, labelMode: "short" },
+        { spanYears: 170, minSignificance: 5, labelMode: "standard" },
+        { spanYears: 0, minSignificance: 1, labelMode: "full" }
+      ]
+    },
+    explode: {
+      enabled: false,
+      maxVisible: 34,
+      minVisible: 10,
+      layers: 6,
+      densityPixels: 8800,
+      animationMs: 620
+    }
+  },
+  themes: [
+    {
+      id: "obsidian-lab",
+      label: {
+        en: "Obsidian Lab",
+        fa: "آزمایشگاه آبسیدین"
+      },
+      colors: {
+        background: "#0f1412",
+        surface: "#151b18",
+        surfaceRaised: "#202821",
+        panel: "#111714",
+        text: "#edf2ea",
+        muted: "#9ba89d",
+        line: "#35433b",
+        grid: "#26322c",
+        accent: "#4fb7a5",
+        accent2: "#d4b45f",
+        accent3: "#f0705a",
+        accent4: "#81c7d4",
+        shadow: "rgba(0, 0, 0, 0.42)"
+      }
+    },
+    {
+      id: "museum-glass",
+      label: {
+        en: "Museum Glass",
+        fa: "شیشه موزه"
+      },
+      colors: {
+        background: "#f4f2ec",
+        surface: "#fffdf8",
+        surfaceRaised: "#ffffff",
+        panel: "#ebe7dd",
+        text: "#242820",
+        muted: "#697163",
+        line: "#cec7b8",
+        grid: "#ded8cb",
+        accent: "#257c78",
+        accent2: "#a66b2c",
+        accent3: "#b84740",
+        accent4: "#4a7c9f",
+        shadow: "rgba(67, 54, 32, 0.16)"
+      }
+    },
+    {
+      id: "graphite-citrus",
+      label: {
+        en: "Graphite Citrus",
+        fa: "گرافیت مرکباتی"
+      },
+      colors: {
+        background: "#191a18",
+        surface: "#22231f",
+        surfaceRaised: "#2d3029",
+        panel: "#141512",
+        text: "#f5f7ed",
+        muted: "#a9b09d",
+        line: "#474b3f",
+        grid: "#33382e",
+        accent: "#b5d342",
+        accent2: "#42b6a3",
+        accent3: "#e86f4f",
+        accent4: "#f0bd52",
+        shadow: "rgba(0, 0, 0, 0.38)"
+      }
+    }
+  ]
+};
+

package/src/filters.js

@@ -0,0 +1,61 @@
+export function getDatasetBounds(records) {
+  if (!records.length) {
+    const year = new Date().getUTCFullYear();
+    return { start: year - 10, end: year + 10 };
+  }
+  const starts = records.map((record) => record.__meta.start).filter(Number.isFinite);
+  const ends = records.map((record) => record.__meta.end).filter(Number.isFinite);
+  return {
+    start: Math.min(...starts, ...ends),
+    end: Math.max(...starts, ...ends)
+  };
+}
+
+export function createDefaultFilters(records, facets = {}) {
+  const bounds = getDatasetBounds(records);
+  return {
+    search: "",
+    recordTypes: new Set((facets.recordTypes || []).map((item) => item.key)),
+    types: new Set((facets.types || []).map((item) => item.key)),
+    factuality: new Set((facets.factuality || []).map((item) => item.key)),
+    confidence: new Set((facets.confidence || []).map((item) => item.key)),
+    scopes: new Set((facets.scopes || []).map((item) => item.key)),
+    categories: new Set((facets.categories || []).map((item) => item.key)),
+    countries: new Set((facets.countries || []).map((item) => item.key)),
+    minSignificance: 1,
+    mediaOnly: false,
+    uncertainOnly: false,
+    fromYear: Math.floor(bounds.start),
+    toYear: Math.ceil(bounds.end)
+  };
+}
+
+export function normalizeFilters(filters = {}, baseFilters = {}) {
+  const merged = { ...baseFilters, ...filters };
+  for (const key of ["recordTypes", "types", "factuality", "confidence", "scopes", "categories", "countries"]) {
+    if (Array.isArray(merged[key])) merged[key] = new Set(merged[key]);
+    else if (!(merged[key] instanceof Set)) merged[key] = new Set(merged[key] ? [merged[key]] : []);
+  }
+  return merged;
+}
+
+export function filterRecords(records, filters) {
+  if (!filters) return records;
+  const query = String(filters.search || "").trim().toLocaleLowerCase();
+  return records.filter((record) => {
+    if (query && !record.__meta.searchText.includes(query)) return false;
+    if (filters.recordTypes instanceof Set && !filters.recordTypes.has(record.recordType)) return false;
+    if (record.type && filters.types instanceof Set && !filters.types.has(record.type)) return false;
+    if (filters.factuality instanceof Set && !filters.factuality.has(record.factuality || "unknown")) return false;
+    if (filters.confidence instanceof Set && !filters.confidence.has(record.__meta.confidence || "unknown")) return false;
+    if (filters.scopes instanceof Set && !filters.scopes.has(record.__meta.scope || "local")) return false;
+    if (record.__meta.categories.length && filters.categories instanceof Set && !record.__meta.categories.some((category) => filters.categories.has(category))) return false;
+    if (record.__meta.countries.length && filters.countries instanceof Set && !record.__meta.countries.some((country) => filters.countries.has(country))) return false;
+    if (record.__meta.importance < Number(filters.minSignificance || 1)) return false;
+    if (filters.mediaOnly && !record.__meta.hasMedia) return false;
+    if (filters.uncertainOnly && !record.__meta.temporalUncertainty) return false;
+    if (Number.isFinite(filters.fromYear) && record.__meta.end < filters.fromYear) return false;
+    if (Number.isFinite(filters.toYear) && record.__meta.start > filters.toYear) return false;
+    return true;
+  });
+}

package/src/i18n.js

@@ -0,0 +1,184 @@
+export const UI_STRINGS = {
+  en: {
+    dataset: "Dataset",
+    language: "Language",
+    theme: "Theme",
+    orientation: "Orientation",
+    auto: "Auto",
+    horizontal: "Horizontal",
+    vertical: "Vertical",
+    axis: "Axis",
+    middle: "Middle",
+    sideStart: "Side start",
+    sideEnd: "Side end",
+    filters: "Filters",
+    search: "Search",
+    searchPlaceholder: "Search records",
+    recordTypes: "Record types",
+    specificTypes: "Specific types",
+    factuality: "Factuality",
+    confidence: "Confidence",
+    scope: "Scope",
+    categories: "Categories",
+    countries: "Countries",
+    dateRange: "Date range",
+    from: "From",
+    to: "To",
+    significance: "Significance",
+    mediaOnly: "Media only",
+    uncertainOnly: "Uncertain dates",
+    lod: "Adaptive detail",
+    explode: "Explode",
+    resetFilters: "Reset",
+    zoomIn: "Zoom in",
+    zoomOut: "Zoom out",
+    fit: "Fit",
+    resetView: "Reset view",
+    selected: "Selected",
+    noSelection: "Select a record",
+    records: "records",
+    visible: "visible",
+    hidden: "reduced",
+    span: "span",
+    details: "Details",
+    overview: "Overview",
+    dates: "Dates",
+    entities: "Entities",
+    places: "Places",
+    relationships: "Relationships",
+    interpretations: "Interpretations",
+    sources: "Sources",
+    funFacts: "Fun facts",
+    media: "Media",
+    extensions: "Extensions",
+    notes: "Notes",
+    type: "Type",
+    category: "Category",
+    rank: "Rank",
+    method: "Method",
+    basis: "Basis",
+    reliability: "Reliability",
+    noRecords: "No records match the filters.",
+    loading: "Loading",
+    all: "All",
+    clear: "Clear",
+    apply: "Apply",
+    ongoing: "present",
+    circa: "c.",
+    bce: "BCE",
+    ce: "CE",
+    lessDetail: "compact",
+    fullDetail: "full",
+    mediaOpen: "Open media",
+    sourceOpen: "Open source",
+    hiddenEvents: "hidden events",
+    clusterHint: "Click to expand temporarily",
+    clusterExpanded: "{count} hidden events expanded",
+    timelineOverview: "Timeline overview",
+    zoomWindow: "Current viewing window",
+    zoomSelection: "Selected zoom range",
+    currentView: "{count} of {total} records",
+    zoomLevel: "{span} years",
+    attestation: "Attestation",
+    originalDate: "Original",
+    statusReady: "{visible} visible, {hidden} reduced by detail level"
+  },
+  fa: {
+    dataset: "مجموعه",
+    language: "زبان",
+    theme: "پوسته",
+    orientation: "جهت",
+    auto: "خودکار",
+    horizontal: "افقی",
+    vertical: "عمودی",
+    axis: "محور",
+    middle: "میانه",
+    sideStart: "کنار آغاز",
+    sideEnd: "کنار پایان",
+    filters: "فیلترها",
+    search: "جستجو",
+    searchPlaceholder: "جستجوی رخدادها",
+    recordTypes: "گونه رکورد",
+    specificTypes: "نوع های دقیق",
+    factuality: "اعتبار تاریخی",
+    confidence: "اطمینان",
+    scope: "گستره",
+    categories: "دسته ها",
+    countries: "کشورها",
+    dateRange: "بازه زمانی",
+    from: "از",
+    to: "تا",
+    significance: "اهمیت",
+    mediaOnly: "فقط رسانه",
+    uncertainOnly: "تاریخ نامطمئن",
+    lod: "جزئیات تطبیقی",
+    explode: "نمای انفجاری",
+    resetFilters: "بازنشانی",
+    zoomIn: "بزرگ نمایی",
+    zoomOut: "کوچک نمایی",
+    fit: "نمای کامل",
+    resetView: "بازنشانی نما",
+    selected: "انتخاب شده",
+    noSelection: "یک رکورد را انتخاب کنید",
+    records: "رکورد",
+    visible: "نمایان",
+    hidden: "کاهش یافته",
+    span: "بازه",
+    details: "جزئیات",
+    overview: "نمای کلی",
+    dates: "تاریخ ها",
+    entities: "کنشگران",
+    places: "مکان ها",
+    relationships: "روابط",
+    interpretations: "تفسیرها",
+    sources: "منابع",
+    funFacts: "نکته ها",
+    media: "رسانه",
+    extensions: "افزونه ها",
+    notes: "یادداشت",
+    type: "نوع",
+    category: "دسته",
+    rank: "رتبه",
+    method: "روش",
+    basis: "پشتوانه",
+    reliability: "اعتبار",
+    noRecords: "هیچ رکوردی با فیلترها سازگار نیست.",
+    loading: "در حال بارگذاری",
+    all: "همه",
+    clear: "پاک کردن",
+    apply: "اعمال",
+    ongoing: "اکنون",
+    circa: "حدود",
+    bce: "پیش از میلاد",
+    ce: "میلادی",
+    lessDetail: "فشرده",
+    fullDetail: "کامل",
+    mediaOpen: "باز کردن رسانه",
+    sourceOpen: "باز کردن منبع",
+    hiddenEvents: "رخداد پنهان",
+    clusterHint: "برای باز شدن موقت کلیک کنید",
+    clusterExpanded: "{count} رخداد پنهان باز شده",
+    timelineOverview: "نمای کلی زمان",
+    zoomWindow: "پنجره نمای کنونی",
+    zoomSelection: "بازه بزرگ نمایی انتخاب شده",
+    currentView: "{count} از {total} رکورد",
+    zoomLevel: "{span} سال",
+    attestation: "گواهی تاریخی",
+    originalDate: "اصل تاریخ",
+    statusReady: "{visible} نمایان، {hidden} با سطح جزئیات کاهش یافته"
+  }
+};
+
+export function dirForLanguage(language) {
+  return /^(fa|ar|he|ur)(-|$)/i.test(language) ? "rtl" : "ltr";
+}
+
+export function makeTranslator(language) {
+  const strings = UI_STRINGS[language] || UI_STRINGS.en;
+  return function translate(key, values = {}) {
+    const template = strings[key] || UI_STRINGS.en[key] || key;
+    return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, name) => {
+      return Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : "";
+    });
+  };
+}