@industream/timeline 1.0.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@industream/timeline",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "type": "module",
   "description": "The @industream timeline as a framework-agnostic Web Component (<industream-timeline>). Self-contained bundle (React + styles inside a Shadow DOM). Works in Angular, Vue, vanilla — no React or Tailwind setup required.",
   "license": "ISC",
@@ -19,14 +19,20 @@
   "sideEffects": true,
   "main": "./dist/industream-timeline.js",
   "module": "./dist/industream-timeline.js",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./dist/industream-timeline.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./dist/industream-timeline.js"
+    }
   },
   "files": [
-    "dist"
+    "dist",
+    "types"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
     "@base-ui/react": "^1.3.0",
@@ -38,6 +44,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",
+    "jsdom": "^29.1.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "shadcn": "^4.2.0",
@@ -46,10 +53,12 @@
     "tw-animate-css": "^1.4.0",
     "typescript": "~5.9.3",
     "vite": "^8.0.1",
+    "vitest": "^4.1.10",
     "@industream/timeline-react": "0.1.0"
   },
   "scripts": {
     "build": "vite build",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }

package/types/index.d.ts

@@ -0,0 +1,82 @@
+// Type declarations of @industream/timeline. Written by hand, as the bundle's sources depend on an unpublished
+// package; the typecheck verifies them against the element (src/type-declarations.test.ts).
+
+export type TimelineLanguage = "en" | "fr" | "de";
+export type TimelineTheme = "light" | "dark";
+export type TimelineMode = "historic" | "live" | "timelapse";
+
+/**
+ * The element's attributes, for typing a framework's templates (e.g. a JSX `IntrinsicElements` entry). Boolean
+ * attributes (`instant`, `window`, `step-loading`) are on when present: give them `""`.
+ */
+export interface IndustreamTimelineAttributes {
+    language?: TimelineLanguage;
+    /** Show the snapshot instant T. */
+    instant?: string;
+    /** Show the `[from, to]` window. */
+    window?: string;
+    /** Space-separated animated modes on top of Historic: `"live"`, `"timelapse"`; `""` for Historic only. */
+    modes?: string;
+    theme?: TimelineTheme;
+    "step-loading"?: string;
+    /** Window start: epoch ms or ISO 8601. Goes with `to`. */
+    from?: string | number;
+    /** Window end: epoch ms or ISO 8601. Goes with `from`. */
+    to?: string | number;
+    /** The window as the last duration: `30m`, `1h`, `2d`, `1w`, `3M`, `1y`. */
+    timespan?: string;
+    /** How much time the band spans, same syntax as `timespan`. */
+    extent?: string;
+    /** The mode to start in. */
+    mode?: "historic" | "live";
+}
+
+/** An overlay series drawn faintly across the band. */
+export type BandPreview = {
+    points: readonly { time: number; value: number }[];
+    min: number;
+    max: number;
+    color?: string;
+};
+
+/** Times are epoch milliseconds. */
+export type TimelineSnapshotChangeDetail = { snapshot: number };
+export type TimelineWindowChangeDetail = { from: number; to: number };
+export type TimelineExtentChangeDetail = { from: number; to: number };
+export type TimelineModeChangeDetail = { mode: TimelineMode };
+
+export interface IndustreamTimelineEventMap {
+    snapshotchange: CustomEvent<TimelineSnapshotChangeDetail>;
+    windowchange: CustomEvent<TimelineWindowChangeDetail>;
+    extentchange: CustomEvent<TimelineExtentChangeDetail>;
+    modechange: CustomEvent<TimelineModeChangeDetail>;
+}
+
+type TimelineListener<K extends keyof IndustreamTimelineEventMap> =
+    (this: IndustreamTimelineElement, event: IndustreamTimelineEventMap[K]) => unknown;
+type ElementListener<K extends keyof HTMLElementEventMap> =
+    (this: IndustreamTimelineElement, event: HTMLElementEventMap[K]) => unknown;
+
+/** `<industream-timeline>`. */
+export declare class IndustreamTimelineElement extends HTMLElement {
+    static readonly observedAttributes: readonly string[];
+    /** Optional band overlay — an object, so set as a property, not an attribute. */
+    get preview(): BandPreview | null;
+    set preview(value: BandPreview | null);
+
+    addEventListener<K extends keyof IndustreamTimelineEventMap>(type: K, listener: TimelineListener<K>, options?: boolean | AddEventListenerOptions): void;
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: ElementListener<K>, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof IndustreamTimelineEventMap>(type: K, listener: TimelineListener<K>, options?: boolean | EventListenerOptions): void;
+    removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: ElementListener<K>, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
+
+/** Registers `<industream-timeline>`, or the element under another tag name. Importing the package already does it. */
+export declare function defineTimelineElement(tagName?: string): void;
+
+declare global {
+    interface HTMLElementTagNameMap {
+        "industream-timeline": IndustreamTimelineElement;
+    }
+}