From ff49133775aef00bf3498ad79f2bba9acc97c5e0 Mon Sep 17 00:00:00 2001 From: Karn Date: Thu, 8 Oct 2026 01:34:20 +0530 Subject: [PATCH] feat: let a timeline marker show rich content on hover A marker can now carry a preview (any React content). When the hovered marker has one, the hover card shows it in place of the time and label. The card is then full size, left-aligned and up to 300px wide, and it still stays inside the track and above icon markers. The label stays the marker button's accessible name. Markers without a preview look and behave as before. Co-Authored-By: Claude Opus 5.5 --- .changeset/marker-preview.md | 5 ++++ README.md | 2 ++ src/core/types.ts | 7 ++++++ src/styles/kino.css | 18 +++++++++++++++ src/ui/scrubber.test.tsx | 44 ++++++++++++++++++++++++++++++++++++ src/ui/scrubber.tsx | 39 ++++++++++++++++++++++---------- 6 files changed, 103 insertions(+), 12 deletions(-) create mode 100644 .changeset/marker-preview.md diff --git a/.changeset/marker-preview.md b/.changeset/marker-preview.md new file mode 100644 index 0000000..6f8fd30 --- /dev/null +++ b/.changeset/marker-preview.md @@ -0,0 +1,5 @@ +--- +"@karnstack/kino": minor +--- + +Markers can carry a `preview` (any React content) shown in the hover preview instead of the time and `label`. The preview card is then full size, left-aligned and up to 300px wide, and still stays inside the track. `label` stays the marker's accessible name. Omit `preview` and markers look as before. diff --git a/README.md b/README.md index e4eadb2..92e82b5 100644 --- a/README.md +++ b/README.md @@ -308,6 +308,8 @@ Pass `markers` to draw dots on the timeline, for example comments or notes at a Give a marker an `icon` (short text, usually one emoji) to draw it in place of the dot, for example reactions: `{ id: "r1", time: 79, icon: "🔥", label: "🔥 3 at 1:19" }`. The hover label wraps up to three lines. Keep labels short. +For a richer hover card, give a marker a `preview` (any React content). It is shown in place of the time and `label`, left-aligned, up to 300px wide, and stays inside the track. Keep `label` too: it is still the button's accessible name. + `Player` takes the same two props. Theme the ring around dot markers with `--kino-marker-ring` (icons have no ring). Omit `markers` and nothing changes. ## Theming diff --git a/src/core/types.ts b/src/core/types.ts index fcd99df..cb524ce 100644 --- a/src/core/types.ts +++ b/src/core/types.ts @@ -1,3 +1,5 @@ +import type { ReactNode } from "react" + export type QualityLevel = { id: string // rendition id from the engine height: number // e.g. 1080 @@ -94,4 +96,9 @@ export type Marker = { label?: string /** Short text drawn in place of the dot, usually one emoji. */ icon?: string + /** + * Rich content shown in the hover preview instead of the time and `label`. + * `label` stays the marker button's accessible name, so set both. + */ + preview?: ReactNode } diff --git a/src/styles/kino.css b/src/styles/kino.css index f01b094..a436fae 100644 --- a/src/styles/kino.css +++ b/src/styles/kino.css @@ -356,6 +356,24 @@ .kino .kino-preview.kino-preview-above-icon { bottom: calc(100% + 11px); } +/* A marker's own preview content: full size, left-aligned, wraps at 300px + (or the scrubber width, if that is smaller). */ +.kino .kino-preview.kino-preview-rich { + transform: translateX(-50%); + align-items: stretch; + width: max-content; + max-width: min(300px, 100% - 8px); + padding: 10px 12px; + text-align: left; + font-size: 13px; + line-height: 1.4; + color: var(--kino-text); + white-space: normal; + overflow-wrap: anywhere; +} +.kino .kino-preview-content { + min-width: 0; +} .kino .kino-preview-img { border-radius: 6px; background-repeat: no-repeat; diff --git a/src/ui/scrubber.test.tsx b/src/ui/scrubber.test.tsx index f9a9971..d78f93a 100644 --- a/src/ui/scrubber.test.tsx +++ b/src/ui/scrubber.test.tsx @@ -227,3 +227,47 @@ test("hovering a marker shows the marker's own time", () => { .getAttribute("aria-label"), ).toBe("0:50") }) + +test("hovering a marker with a preview shows the preview instead of time and label", () => { + withMarkers([ + { + id: "a", + time: 50, + label: "Lee: gzip", + preview:

Lee says gzip

, + }, + ]) + stubRect(screen.getByTestId("kino-track")) + hoverMarker(screen.getByTestId("kino-marker")) + const preview = document.querySelector(".kino-preview")! + expect(preview.classList.contains("kino-preview-rich")).toBe(true) + expect(screen.getByTestId("rich").textContent).toBe("Lee says gzip") + expect(preview.querySelector(".kino-preview-time")).toBeNull() + expect(preview.querySelector(".kino-preview-label")).toBeNull() +}) + +test("a marker without a preview keeps the time and label preview", () => { + withMarkers([{ id: "a", time: 50, label: "Lee: gzip" }]) + stubRect(screen.getByTestId("kino-track")) + hoverMarker(screen.getByTestId("kino-marker")) + const preview = document.querySelector(".kino-preview")! + expect(preview.classList.contains("kino-preview-rich")).toBe(false) + expect(preview.querySelector(".kino-preview-time")).toBeTruthy() + expect(preview.querySelector(".kino-preview-label")!.textContent).toBe( + "Lee: gzip", + ) +}) + +test("a marker with a preview still takes its accessible name from label", () => { + withMarkers([{ id: "a", time: 50, label: "Lee: gzip", preview: rich }]) + expect(screen.getByRole("button", { name: "Lee: gzip" })).toBeTruthy() +}) + +test("a rich preview above an icon marker still rises above the icon", () => { + withMarkers([{ id: "r", time: 50, icon: "🔥", preview: rich }]) + stubRect(screen.getByTestId("kino-track")) + hoverMarker(screen.getByTestId("kino-marker")) + const cls = document.querySelector(".kino-preview")!.classList + expect(cls.contains("kino-preview-rich")).toBe(true) + expect(cls.contains("kino-preview-above-icon")).toBe(true) +}) diff --git a/src/ui/scrubber.tsx b/src/ui/scrubber.tsx index 94b295f..f96859f 100644 --- a/src/ui/scrubber.tsx +++ b/src/ui/scrubber.tsx @@ -88,15 +88,28 @@ export function Scrubber() { const pw = previewRef.current?.getBoundingClientRect().width ?? 0 const tw = trackRef.current?.getBoundingClientRect().width ?? 0 setDims({ pw, tw }) - }, [hover, tile?.url]) + }, [hover, tile?.url, hoverMarker]) // Center the preview on the cursor, but clamp so it never crosses an edge. + // A preview wider than the track is centered on the track. let previewLeft = hover?.x ?? 0 if (hover && dims.pw > 0 && dims.tw > 0) { const half = dims.pw / 2 + 4 - previewLeft = Math.min(Math.max(hover.x, half), dims.tw - half) + previewLeft = + half * 2 >= dims.tw + ? dims.tw / 2 + : Math.min(Math.max(hover.x, half), dims.tw - half) } + const rich = hoverMarker?.preview != null ? hoverMarker.preview : null + const previewClass = [ + "kino-preview kino-glass", + rich != null && "kino-preview-rich", + hoverMarker?.icon && "kino-preview-above-icon", + ] + .filter(Boolean) + .join(" ") + return (
{tile && ( @@ -128,11 +137,17 @@ export function Scrubber() { }} /> )} - - - - {hoverMarker?.label && ( - {hoverMarker.label} + {rich != null ? ( +
{rich}
+ ) : ( + <> + + + + {hoverMarker?.label && ( + {hoverMarker.label} + )} + )}
)}