@katlux/block-charts 0.1.0-beta.0

package/src/runtime/composables/useChartAnimation.ts

@@ -0,0 +1,45 @@
+import { ref, type Ref } from 'vue'
+
+export interface IChartAnimationContext {
+	progress: Ref<number>
+	animate: () => void
+	stop: () => void
+}
+
+export function useChartAnimation(duration = 600): IChartAnimationContext {
+	const progress = ref(0)
+	let rafId: number | null = null
+	let startTime: number | null = null
+
+	const animate = () => {
+		stop()
+		progress.value = 0
+		startTime = null
+
+		const tick = (now: number) => {
+			if (startTime === null) startTime = now
+			const elapsed = now - startTime
+			progress.value = Math.min(elapsed / duration, 1)
+			if (progress.value < 1) {
+				rafId = requestAnimationFrame(tick)
+			} else {
+				rafId = null
+			}
+		}
+		rafId = requestAnimationFrame(tick)
+	}
+
+	const stop = () => {
+		if (rafId !== null) {
+			cancelAnimationFrame(rafId)
+			rafId = null
+		}
+	}
+
+	return { progress, animate, stop }
+}
+
+/** Easing function: ease-out cubic */
+export function easeOut(t: number): number {
+	return 1 - Math.pow(1 - t, 3)
+}

package/src/runtime/composables/useChartAxes.ts

@@ -0,0 +1,105 @@
+import { computed, type Ref, type ComputedRef } from 'vue'
+
+export type TScaleMode = 'linear' | 'logarithmic' | 'time'
+
+export interface IChartAxesOptions {
+	items: Ref<any[]>
+	xField: Ref<string>
+	yField: Ref<string>
+	width: Ref<number>
+	height: Ref<number>
+	scale: Ref<number>
+	panOffset: Ref<{ x: number; y: number }>
+	padding?: { top: number; right: number; bottom: number; left: number }
+	scaleMode?: TScaleMode
+}
+
+export interface IChartAxesContext {
+	xMin: ComputedRef<number>
+	xMax: ComputedRef<number>
+	yMin: ComputedRef<number>
+	yMax: ComputedRef<number>
+	plotLeft: number
+	plotTop: number
+	plotWidth: ComputedRef<number>
+	plotHeight: ComputedRef<number>
+	toX: (value: number) => number
+	toY: (value: number) => number
+	fromX: (px: number) => number
+}
+
+/**
+ * Robustly parses a value into a number.
+ * Handles: numbers, numeric strings, and ISO date strings.
+ */
+export function parseValue(val: any): number {
+	if (val === null || val === undefined) return 0
+	const n = Number(val)
+	if (!isNaN(n)) return n
+	if (typeof val === 'string') {
+		const d = Date.parse(val)
+		if (!isNaN(d)) return d
+	}
+	return 0
+}
+
+export function useChartAxes(opts: IChartAxesOptions): IChartAxesContext {
+	const pad = opts.padding ?? { top: 20, right: 20, bottom: 40, left: 55 }
+
+	const plotLeft = pad.left
+	const plotTop = pad.top
+
+	const plotWidth = computed(() => Math.max(0, opts.width.value - pad.left - pad.right))
+	const plotHeight = computed(() => Math.max(0, opts.height.value - pad.top - pad.bottom))
+
+	// Domain extents from data
+	const rawXMin = computed(() => {
+		const vals = opts.items.value.map(r => parseValue(r[opts.xField.value]))
+		return vals.length ? Math.min(...vals) : 0
+	})
+	const rawXMax = computed(() => {
+		const vals = opts.items.value.map(r => parseValue(r[opts.xField.value]))
+		return vals.length ? Math.max(...vals) : 1
+	})
+	const yMin = computed(() => {
+		const vals = opts.items.value.map(r => parseValue(r[opts.yField.value]))
+		return vals.length ? Math.min(...vals) : 0
+	})
+	const yMax = computed(() => {
+		const vals = opts.items.value.map(r => parseValue(r[opts.yField.value]))
+		return vals.length ? Math.max(...vals) : 1
+	})
+
+	// Apply zoom + pan to X domain
+	// panOffset.x is in pixel-space; convert back to domain
+	const xRange = computed(() => rawXMax.value - rawXMin.value)
+	const visibleXRange = computed(() => xRange.value / opts.scale.value)
+
+	const panOffsetDomain = computed(() => {
+		const pxRange = plotWidth.value
+		if (pxRange === 0) return 0
+		return (opts.panOffset.value.x / pxRange) * xRange.value
+	})
+
+	const xMin = computed(() => rawXMin.value + panOffsetDomain.value)
+	const xMax = computed(() => xMin.value + visibleXRange.value)
+
+	const toX = (value: number): number => {
+		const range = xMax.value - xMin.value
+		if (range === 0) return plotLeft
+		return plotLeft + ((value - xMin.value) / range) * plotWidth.value
+	}
+
+	const toY = (value: number): number => {
+		const range = yMax.value - yMin.value
+		if (range === 0) return plotTop + plotHeight.value
+		return plotTop + plotHeight.value - ((value - yMin.value) / range) * plotHeight.value
+	}
+
+	const fromX = (px: number): number => {
+		const range = xMax.value - xMin.value
+		return xMin.value + ((px - plotLeft) / plotWidth.value) * range
+	}
+
+	return { xMin, xMax, yMin, yMax, plotLeft, plotTop, plotWidth, plotHeight, toX, toY, fromX }
+}

package/src/runtime/composables/useChartCanvas.ts

@@ -0,0 +1,67 @@
+import { ref, onMounted, onUnmounted, type Ref } from 'vue'
+
+export interface IChartCanvasContext {
+	canvas: Ref<HTMLCanvasElement | null>
+	ctx: Ref<CanvasRenderingContext2D | null>
+	width: Ref<number>
+	height: Ref<number>
+	dpr: Ref<number>
+	clear: (color?: string) => void
+	setupCanvas: (el: HTMLCanvasElement) => void
+}
+
+export function useChartCanvas(): IChartCanvasContext {
+	const canvas = ref<HTMLCanvasElement | null>(null)
+	const ctx = ref<CanvasRenderingContext2D | null>(null)
+	const width = ref(0)
+	const height = ref(0)
+	const dpr = ref(window?.devicePixelRatio ?? 1)
+
+	let resizeObserver: ResizeObserver | null = null
+
+	const applySize = (el: HTMLCanvasElement, w: number, h: number) => {
+		const ratio = window.devicePixelRatio ?? 1
+		dpr.value = ratio
+		el.width = w * ratio
+		el.height = h * ratio
+		ctx.value?.scale(ratio, ratio)
+		width.value = w
+		height.value = h
+	}
+
+	const setupCanvas = (el: HTMLCanvasElement) => {
+		canvas.value = el
+		ctx.value = el.getContext('2d')
+
+		const rect = el.getBoundingClientRect()
+		applySize(el, rect.width, rect.height)
+
+		resizeObserver = new ResizeObserver((entries) => {
+			for (const entry of entries) {
+				const { width: w, height: h } = entry.contentRect
+				if (canvas.value && ctx.value) {
+					// Re-get context after resize to reset transform
+					ctx.value = canvas.value.getContext('2d')
+					applySize(canvas.value, w, h)
+				}
+			}
+		})
+		resizeObserver.observe(el)
+	}
+
+	const clear = (color?: string) => {
+		if (ctx.value && canvas.value) {
+			ctx.value.clearRect(0, 0, width.value, height.value)
+			if (color && color !== 'transparent') {
+				ctx.value.fillStyle = color
+				ctx.value.fillRect(0, 0, width.value, height.value)
+			}
+		}
+	}
+
+	onUnmounted(() => {
+		resizeObserver?.disconnect()
+	})
+
+	return { canvas, ctx, width, height, dpr, clear, setupCanvas }
+}

package/src/runtime/composables/useChartData.ts

@@ -0,0 +1,79 @@
+import { ref, watch, onMounted, isRef, type Ref } from 'vue'
+
+export interface IChartDataContext<T = any> {
+	items: Ref<T[]>
+	loading: Ref<boolean>
+	error: Ref<string | null>
+	reload: () => Promise<void>
+}
+
+/**
+ * Robust data fetcher for charts. Supports:
+ * 1. Plain arrays
+ * 2. Katlux DataProviders (with .pageData ref)
+ * 3. Legacy fetchable providers (with .fetch() method)
+ */
+export function useChartData<T = any>(
+	providerOrData: Ref<any>
+): IChartDataContext<T> {
+	const items = ref<T[]>([]) as Ref<T[]>
+	const loading = ref(false)
+	const error = ref<string | null>(null)
+
+	const load = async () => {
+		const source = providerOrData.value
+		if (!source) {
+			items.value = []
+			return
+		}
+
+		loading.value = true
+		error.value = null
+
+		try {
+			// 1. Plain array
+			if (Array.isArray(source)) {
+				items.value = source as T[]
+				return
+			}
+
+			// 2. Katlux DataProvider (has pageData ref)
+			if (source.pageData) {
+				items.value = (isRef(source.pageData) ? source.pageData.value : source.pageData) as T[]
+				return
+			}
+
+			// 3. Legacy fetchable provider
+			if (typeof source.fetch === 'function') {
+				const result = await source.fetch()
+				items.value = (result?.rows ?? result ?? []) as T[]
+				return
+			}
+
+			// 4. Object with rows
+			if (source.rows) {
+				items.value = source.rows as T[]
+				return
+			}
+		} catch (e: any) {
+			error.value = e?.message ?? 'Failed to load chart data'
+		} finally {
+			loading.value = false
+		}
+	}
+
+	const reload = load
+
+	onMounted(load)
+
+	// Watch the provider instance itself
+	watch(providerOrData, load)
+
+	// High priority: watch the pageData of the current provider (if it exists)
+	// This ensures that when a provider finishes an async load, the chart re-renders.
+	watch(() => providerOrData.value?.pageData?.value, (newRows) => {
+		if (newRows) items.value = newRows as T[]
+	}, { deep: true })
+
+	return { items, loading, error, reload }
+}

package/src/runtime/composables/useChartExport.ts

@@ -0,0 +1,40 @@
+export interface IChartExportContext {
+	exportPng: (canvas: HTMLCanvasElement, filename?: string) => void
+	exportSvg: (svgEl: SVGSVGElement, filename?: string) => void
+}
+
+export function useChartExport(): IChartExportContext {
+	const download = (href: string, filename: string) => {
+		const a = document.createElement('a')
+		a.href = href
+		a.download = filename
+		a.style.display = 'none'
+		document.body.appendChild(a)
+		a.click()
+		document.body.removeChild(a)
+	}
+
+	const exportPng = (canvas: HTMLCanvasElement, filename = 'chart.png') => {
+		try {
+			const dataUrl = canvas.toDataURL('image/png')
+			download(dataUrl, filename)
+		} catch (e) {
+			console.error('[KChart] PNG export failed:', e)
+		}
+	}
+
+	const exportSvg = (svgEl: SVGSVGElement, filename = 'chart.svg') => {
+		try {
+			const serializer = new XMLSerializer()
+			const svgStr = serializer.serializeToString(svgEl)
+			const blob = new Blob([svgStr], { type: 'image/svg+xml;charset=utf-8' })
+			const url = URL.createObjectURL(blob)
+			download(url, filename)
+			URL.revokeObjectURL(url)
+		} catch (e) {
+			console.error('[KChart] SVG export failed:', e)
+		}
+	}
+
+	return { exportPng, exportSvg }
+}

package/src/runtime/composables/useChartHitTest.ts

@@ -0,0 +1,71 @@
+import { type Ref } from 'vue'
+import { parseValue, type IChartAxesContext } from './useChartAxes'
+
+export function useChartHitTest() {
+	/**
+	 * Finds the nearest item based on X-coordinate.
+	 * Optimized for Line and Area charts where points are usually ordered by X.
+	 */
+	const findNearestX = (items: any[], mouseX: number, xField: string, axes: IChartAxesContext): { item: any; index: number } | null => {
+		if (!items.length) return null
+
+		// Convert pixel mouseX to data-space
+		const dataX = axes.fromX(mouseX)
+
+		let nearestIdx = 0
+		let minDiff = Math.abs(parseValue(items[0][xField]) - dataX)
+
+		// Basic linear search (could be binary search if we guarantee sorting, 
+		// but simple enough for a few thousands)
+		for (let i = 1; i < items.length; i++) {
+			const val = parseValue(items[i][xField])
+			const diff = Math.abs(val - dataX)
+			if (diff < minDiff) {
+				minDiff = diff
+				nearestIdx = i
+			}
+		}
+
+		return { item: items[nearestIdx], index: nearestIdx }
+	}
+
+	/**
+	 * Finds the nearest item based on Euclidean distance.
+	 * Used for Scatter and Bubble charts.
+	 */
+	const findNearestEuclidean = (
+		items: any[],
+		mouseX: number,
+		mouseY: number,
+		axes: IChartAxesContext,
+		xField: string,
+		yField: string,
+		threshold: number = 20
+	): { item: any; index: number } | null => {
+		if (!items.length) return null
+
+		let nearestIdx = -1
+		let minDistanceSq = threshold * threshold
+
+		items.forEach((item, i) => {
+			const px = axes.toX(parseValue(item[xField]))
+			const py = axes.toY(parseValue(item[yField]))
+
+			const dx = mouseX - px
+			const dy = mouseY - py
+			const distSq = dx * dx + dy * dy
+
+			if (distSq < minDistanceSq) {
+				minDistanceSq = distSq
+				nearestIdx = i
+			}
+		})
+
+		return nearestIdx !== -1 ? { item: items[nearestIdx], index: nearestIdx } : null
+	}
+
+	return {
+		findNearestX,
+		findNearestEuclidean
+	}
+}

package/src/runtime/composables/useChartSvg.ts

@@ -0,0 +1,45 @@
+import { ref, computed, type Ref } from 'vue'
+
+export interface ITooltipState {
+	visible: boolean
+	x: number
+	y: number
+	content: string
+	item: any
+	index: number
+}
+
+export interface IChartSvgContext {
+	hoveredIndex: Ref<number>
+	tooltipState: Ref<ITooltipState>
+	showTooltip: (x: number, y: number, content: string, item: any, index: number) => void
+	hideTooltip: () => void
+	setHovered: (index: number) => void
+}
+
+export function useChartSvg(): IChartSvgContext {
+	const hoveredIndex = ref<number>(-1)
+
+	const tooltipState = ref<ITooltipState>({
+		visible: false,
+		x: 0,
+		y: 0,
+		content: '',
+		item: null,
+		index: -1
+	})
+
+	const showTooltip = (x: number, y: number, content: string, item: any, index: number) => {
+		tooltipState.value = { visible: true, x, y, content, item, index }
+	}
+
+	const hideTooltip = () => {
+		tooltipState.value.visible = false
+	}
+
+	const setHovered = (index: number) => {
+		hoveredIndex.value = index
+	}
+
+	return { hoveredIndex, tooltipState, showTooltip, hideTooltip, setHovered }
+}

package/src/runtime/composables/useChartViewport.ts

@@ -0,0 +1,140 @@
+import { ref, watch, type Ref } from 'vue'
+
+export interface IViewportState {
+	scale: Ref<number>
+	panOffset: Ref<{ x: number; y: number }>
+	isDragging: Ref<boolean>
+	canPan: Ref<boolean>
+}
+
+export interface IChartViewportContext extends IViewportState {
+	zoomIn: () => void
+	zoomOut: () => void
+	resetZoom: () => void
+	onWheel: (e: WheelEvent) => void
+	onMouseDown: (e: MouseEvent) => void
+	onMouseMove: (e: MouseEvent) => void
+	onMouseUp: (e: MouseEvent) => void
+	onMouseLeave: (e: MouseEvent) => void
+}
+
+const ZOOM_STEP = 0.25
+const MIN_SCALE = 1
+const PAN_CLAMP_THRESHOLD = 0.01
+
+export function useChartViewport(
+	options: {
+		maxZoom?: Ref<number>
+		plotWidth: Ref<number>
+		plotLeft?: Ref<number>
+	}
+): IChartViewportContext {
+	const maxZoom = options.maxZoom ?? ref(10)
+	const scale = ref(1)
+	const panOffset = ref({ x: 0, y: 0 })
+	const isDragging = ref(false)
+	const canPan = ref(false)
+	let dragStart = { x: 0, y: 0 }
+	let panStart = { x: 0, y: 0 }
+
+	// Clamp panOffset so the viewport doesn't go out of data bounds
+	const clampPan = () => {
+		const maxPanX = plotWidth() * (1 - 1 / scale.value)
+		panOffset.value.x = Math.max(0, Math.min(panOffset.value.x, maxPanX))
+		panOffset.value.y = 0 // Only horizontal pan for now
+	}
+
+	const plotWidth = () => options.plotWidth.value
+
+	const updateCanPan = () => {
+		canPan.value = scale.value > MIN_SCALE + PAN_CLAMP_THRESHOLD
+	}
+
+	const resetPan = () => {
+		panOffset.value = { x: 0, y: 0 }
+	}
+
+	const zoomTo = (newScale: number, anchorX?: number) => {
+		const prev = scale.value
+		const clamped = Math.min(Math.max(newScale, MIN_SCALE), maxZoom.value)
+
+		if (anchorX !== undefined && prev !== clamped) {
+			// Keep the data point under cursor fixed
+			// anchorX is relative to chart plot area
+			panOffset.value.x += anchorX * (1 / prev - 1 / clamped)
+		}
+
+		scale.value = clamped
+		if (scale.value <= MIN_SCALE) resetPan()
+		else clampPan()
+		updateCanPan()
+	}
+
+	const zoomIn = () => zoomTo(scale.value + ZOOM_STEP)
+	const zoomOut = () => zoomTo(scale.value - ZOOM_STEP)
+	const resetZoom = () => {
+		scale.value = MIN_SCALE
+		resetPan()
+		updateCanPan()
+	}
+
+	// Ctrl + scroll to zoom, Shift + scroll to pan
+	const onWheel = (e: WheelEvent) => {
+		if (e.ctrlKey) {
+			e.preventDefault()
+
+			const rect = (e.currentTarget as HTMLElement).getBoundingClientRect()
+			const plotLeft = options.plotLeft?.value ?? 0
+			const anchorX = e.clientX - rect.left - plotLeft
+
+			const delta = e.deltaY < 0 ? ZOOM_STEP : -ZOOM_STEP
+			zoomTo(scale.value + delta, anchorX)
+		} else if (e.shiftKey) {
+			e.preventDefault()
+			if (!canPan.value) return
+
+			const delta = e.deltaX !== 0 ? e.deltaX : e.deltaY
+			const dx = delta / scale.value
+			panOffset.value.x += dx
+			clampPan()
+		}
+	}
+
+	// Mouse drag for pan
+	const onMouseDown = (e: MouseEvent) => {
+		if (e.button !== 0 || !canPan.value) return
+		isDragging.value = true
+		dragStart = { x: e.clientX, y: e.clientY }
+		panStart = { x: panOffset.value.x, y: panOffset.value.y }
+	}
+
+	const onMouseMove = (e: MouseEvent) => {
+		if (!isDragging.value || !canPan.value) return
+		const dx = -(e.clientX - dragStart.x) / scale.value
+		panOffset.value.x = panStart.x + dx
+		clampPan()
+	}
+
+	const onMouseUp = (_e: MouseEvent) => {
+		isDragging.value = false
+	}
+
+	const onMouseLeave = (_e: MouseEvent) => {
+		isDragging.value = false
+	}
+
+	return {
+		scale,
+		panOffset,
+		isDragging,
+		canPan,
+		zoomIn,
+		zoomOut,
+		resetZoom,
+		onWheel,
+		onMouseDown,
+		onMouseMove,
+		onMouseUp,
+		onMouseLeave
+	}
+}