@rokkit/actions 1.0.0-next.99 → 1.0.1

package/src/navigator.svelte.js

@@ -0,0 +1,235 @@
+import { on } from 'svelte/events'
+import { omit } from 'ramda'
+import { getKeyboardAction, defaultNavigationOptions } from './kbd'
+import { getClickAction, getPathFromEvent } from './utils'
+
+/**
+ * Scrolls the focused element into view if it exists
+ * @param {HTMLElement} container - The container element with the navigator action
+ * @param {*} wrapper - The controller/wrapper with focusedKey
+ */
+function scrollFocusedIntoView(container, wrapper) {
+	let focusedElement = null
+
+	// Use focusedKey if available (most reliable)
+	if (wrapper.focusedKey) {
+		focusedElement = container.querySelector(`[data-path="${wrapper.focusedKey}"]`)
+	}
+
+	// Fallback: find by aria-current
+	if (!focusedElement) {
+		focusedElement = container.querySelector('[aria-current="true"]')
+	}
+
+	// Scroll into view if element found and method exists (may not exist in test env)
+	if (focusedElement?.scrollIntoView) {
+		focusedElement.scrollIntoView({
+			behavior: 'smooth',
+			block: 'nearest',
+			inline: 'nearest'
+		})
+	}
+}
+
+const EVENT_MAP = {
+	first: ['move'],
+	last: ['move'],
+	previous: ['move'],
+	next: ['move'],
+	select: ['move', 'select'],
+	extend: ['move', 'select'],
+	range: ['move', 'select'],
+	collapse: ['toggle'],
+	expand: ['toggle'],
+	toggle: ['toggle']
+}
+
+/**
+ * The last only indicates that if there is an array only the last event is fired.
+ * This is crucial because a click event needs to fire both move and select,
+ * however the keyboard should only fire the select event because we are already
+ * on the current item
+ *
+ * @param {HTMLElement} root
+ * @param {*} controller
+ * @param {*} name
+ */
+export function emitAction(root, controller, name, lastOnly = false) {
+	const events = lastOnly ? EVENT_MAP[name].slice(-1) : EVENT_MAP[name]
+
+	events.forEach((event) => {
+		root.dispatchEvent(
+			new CustomEvent('action', {
+				detail: {
+					name: event,
+					data: { value: controller.focused, selected: controller.selected }
+				}
+			})
+		)
+	})
+}
+
+/*
+ * Generic action handler for keyboard events.
+ *
+ * @param {Record<string, () => void>} actions
+ * @param {KeyboardEvent} event
+ */
+export function handleAction(event, handler, path) {
+	if (handler) {
+		event.preventDefault()
+		event.stopPropagation()
+
+		return handler(path)
+	}
+	return false
+}
+
+function getHandlers(wrapper) {
+	return {
+		first: () => wrapper.moveFirst(),
+		last: () => wrapper.moveLast(),
+		previous: () => wrapper.movePrev(),
+		next: () => wrapper.moveNext(),
+		collapse: () => wrapper.collapse(),
+		expand: () => wrapper.expand(),
+		select: (path) => wrapper.select(path),
+		extend: (path) => wrapper.extendSelection(path),
+		range: (path) => wrapper.selectRange(path),
+		toggle: (path) => wrapper.toggleExpansion(path)
+	}
+}
+
+function isTypeaheadEvent(event) {
+	if (event.ctrlKey) return false
+	if (event.metaKey) return false
+	if (event.altKey) return false
+	if (event.key.length !== 1) return false
+	return event.key !== ' '
+}
+
+function dispatchFocusMoveEvent(node, wrapper) {
+	node.dispatchEvent(
+		new CustomEvent('action', {
+			detail: {
+				name: 'move',
+				data: { value: wrapper.focused, selected: wrapper.selected }
+			}
+		})
+	)
+}
+
+const SCROLL_ACTIONS = new Set(['first', 'last', 'previous', 'next', 'expand', 'collapse'])
+
+function isNativeLink(action, target) {
+	return action === 'select' && Boolean(target.closest('a[href]'))
+}
+
+function notifyFocusMove(node, wrapper, action, prevKey) {
+	if (action !== 'expand' && action !== 'collapse') return false
+	if (wrapper.focusedKey === prevKey) return false
+	dispatchFocusMoveEvent(node, wrapper)
+	return true
+}
+
+function runTypeahead(config, wrapper, ta, event) {
+	if (!config.typeahead) return
+	if (!wrapper.findByText) return
+	ta.handle(event)
+}
+
+function makeKeydownHandler(ctx, config, handlers, ta) {
+	const { node, wrapper } = ctx
+	return (event) => {
+		const action = getKeyboardAction(event, config)
+		if (isNativeLink(action, event.target)) return
+
+		const prevKey = wrapper.focusedKey
+		const handled = handleAction(event, handlers[action])
+		if (!handled) {
+			runTypeahead(config, wrapper, ta, event)
+			return
+		}
+
+		ta.reset()
+		emitAction(node, wrapper, action, true)
+		notifyFocusMove(node, wrapper, action, prevKey)
+		if (SCROLL_ACTIONS.has(action)) setTimeout(() => scrollFocusedIntoView(node, wrapper), 0)
+	}
+}
+
+function getTypeaheadStart(buffer, wrapper) {
+	if (buffer.length === 0) return wrapper.focusedKey
+	return null
+}
+
+function makeTypeahead(node, wrapper) {
+	let buffer = ''
+	let timer = null
+
+	function reset() {
+		buffer = ''
+		if (timer) {
+			clearTimeout(timer)
+			timer = null
+		}
+	}
+
+	function handle(event) {
+		if (!isTypeaheadEvent(event)) return false
+
+		const startAfter = getTypeaheadStart(buffer, wrapper)
+		buffer += event.key
+		if (timer) clearTimeout(timer)
+		timer = setTimeout(reset, 500)
+
+		const matchKey = wrapper.findByText(buffer, startAfter)
+		if (matchKey === null) return false
+		if (!wrapper.moveTo(matchKey)) return false
+
+		event.preventDefault()
+		event.stopPropagation()
+		emitAction(node, wrapper, 'first', true)
+		setTimeout(() => scrollFocusedIntoView(node, wrapper), 0)
+		return true
+	}
+
+	return { reset, handle }
+}
+
+/**
+ * A svelte action function that captures keyboard evvents and emits event for corresponding movements.
+ *
+ * @param {HTMLElement} node
+ * @param {import('./types').NavigableOptions} options
+ * @returns {import('./types').SvelteActionReturn}
+ */
+export function navigator(node, options) {
+	const { wrapper } = options
+	const config = { ...defaultNavigationOptions, ...omit(['wrapper'], options) }
+	const handlers = getHandlers(wrapper)
+	const ta = makeTypeahead(node, wrapper)
+	const handleKeydown = makeKeydownHandler({ node, wrapper }, config, handlers, ta)
+
+	const handleClick = (event) => {
+		const action = getClickAction(event)
+		const path = getPathFromEvent(event)
+
+		if (event.target.closest('a[href]')) {
+			const handler = handlers[action]
+			if (handler?.(path)) emitAction(node, options.wrapper, action)
+			return
+		}
+
+		const handled = handleAction(event, handlers[action], path)
+		if (handled) emitAction(node, options.wrapper, action)
+	}
+
+	$effect(() => {
+		const cleanup = [on(node, 'keydown', handleKeydown), on(node, 'click', handleClick)]
+		return () => {
+			ta.reset()
+			cleanup.forEach((fn) => fn())
+		}
+	})
+}

package/src/{pannable.js → pannable.svelte.js}

@@ -1,25 +1,38 @@
 import { omit } from 'ramda'
 import { removeListeners, setupListeners } from './lib'
+
+/**
+ * Handles the panning event.
+ *
+ * @param {HTMLElement}              node   - The node where the event is dispatched.
+ * @param {Event}                    event  - The event object.
+ * @param {string}                   name   - The name of the event.
+ * @param {import('./types').Coords} coords - The previous coordinates of the event.
+ */
+function handleEvent(node, event, name, coords) {
+	const x = event.clientX ?? event.touches[0].clientX
+	const y = event.clientY ?? event.touches[0].clientY
+	const detail = { x, y }
+
+	if (name === 'panmove') {
+		detail.dx = x - coords.x
+		detail.dy = y - coords.y
+	}
+
+	event.stopPropagation()
+	event.preventDefault()
+	node.dispatchEvent(new CustomEvent(name, { detail }))
+	return omit(['dx', 'dy'], detail)
+}
+
 /**
  * Makes an element pannable with mouse or touch events.
  *
  * @param {HTMLElement} node The DOM element to apply the panning action.
- * @returns {import('./types').SvelteActionReturn}
  */
 export function pannable(node) {
 	let coords = { x: 0, y: 0 }
-	const listeners = {
-		primary: {
-			mousedown: start,
-			touchstart: start
-		},
-		secondary: {
-			mousemove: move,
-			mouseup: stop,
-			touchmove: move,
-			touchend: stop
-		}
-	}
+	const listeners = { primary: {}, secondary: {} }
 
 	function start(event) {
 		coords = handleEvent(node, event, 'panstart', coords)
@@ -35,33 +48,19 @@ export function pannable(node) {
 		removeListeners(window, listeners.secondary)
 	}
 
-	setupListeners(node, listeners.primary)
-
-	return {
-		destroy: () => removeListeners(node, listeners.primary)
+	listeners.primary = {
+		mousedown: start,
+		touchstart: start
 	}
-}
-
-/**
- * Handles the panning event.
- *
- * @param {HTMLElement}              node   - The node where the event is dispatched.
- * @param {Event}                    event  - The event object.
- * @param {string}                   name   - The name of the event.
- * @param {import('./types').Coords} coords - The previous coordinates of the event.
- */
-function handleEvent(node, event, name, coords) {
-	const x = event.clientX || event.touches[0].clientX
-	const y = event.clientY || event.touches[0].clientY
-	const detail = { x, y }
-
-	if (name === 'panmove') {
-		detail.dx = x - coords.x
-		detail.dy = y - coords.y
+	listeners.secondary = {
+		mousemove: move,
+		mouseup: stop,
+		touchmove: move,
+		touchend: stop
 	}
 
-	event.stopPropagation()
-	event.preventDefault()
-	node.dispatchEvent(new CustomEvent(name, { detail }))
-	return omit(['dx', 'dy'], detail)
+	$effect(() => {
+		setupListeners(node, listeners.primary)
+		return () => removeListeners(node, listeners.primary)
+	})
 }

package/src/reveal.svelte.js

@@ -0,0 +1,147 @@
+/**
+ * Scroll-triggered reveal action using IntersectionObserver.
+ * Applies CSS transitions (opacity + translate) when element enters viewport.
+ * When stagger > 0, applies reveal to each child element independently.
+ *
+ * @param {HTMLElement} node
+ * @param {RevealOptions} [options]
+ *
+ * @typedef {Object} RevealOptions
+ * @property {'up' | 'down' | 'left' | 'right' | 'none'} [direction='up'] Slide direction
+ * @property {string} [distance='1.5rem'] Slide distance (CSS unit)
+ * @property {number} [duration=600] Animation duration (ms)
+ * @property {number} [delay=0] Delay before animation starts (ms)
+ * @property {number} [stagger=0] Delay increment per child in ms (0 = disabled)
+ * @property {boolean} [once=true] Only animate once
+ * @property {number} [threshold=0.1] IntersectionObserver threshold (0–1)
+ * @property {string} [easing='cubic-bezier(0.4, 0, 0.2, 1)'] CSS easing function
+ */
+
+function resolveRevealOpts(options) {
+	return {
+		direction: 'up',
+		distance: '1.5rem',
+		duration: 600,
+		delay: 0,
+		stagger: 0,
+		once: true,
+		threshold: 0.1,
+		easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+		...options
+	}
+}
+
+function applyReveal(el, opts) {
+	el.style.setProperty('--reveal-duration', `${opts.duration}ms`)
+	el.style.setProperty('--reveal-distance', opts.distance)
+	el.style.setProperty('--reveal-easing', opts.easing)
+	el.setAttribute('data-reveal', opts.direction)
+}
+
+function cleanReveal(el) {
+	el.removeAttribute('data-reveal')
+	el.removeAttribute('data-reveal-visible')
+	el.style.removeProperty('--reveal-duration')
+	el.style.removeProperty('--reveal-distance')
+	el.style.removeProperty('--reveal-easing')
+	el.style.removeProperty('transition-delay')
+}
+
+function initRevealElements(node, opts, isStagger) {
+	if (isStagger) {
+		Array.from(node.children).forEach((child) => applyReveal(child, opts))
+	} else {
+		applyReveal(node, opts)
+		if (opts.delay > 0) node.style.transitionDelay = `${opts.delay}ms`
+	}
+}
+
+function handleReducedMotion(node, isStagger) {
+	if (isStagger) {
+		Array.from(node.children).forEach((child) => child.setAttribute('data-reveal-visible', ''))
+	} else {
+		node.setAttribute('data-reveal-visible', '')
+	}
+	node.dispatchEvent(new CustomEvent('reveal', { detail: { visible: true } }))
+	return () => {
+		if (isStagger) {
+			Array.from(node.children).forEach((child) => cleanReveal(child))
+		} else {
+			cleanReveal(node)
+		}
+	}
+}
+
+function handleIntersectEnter(node, opts, isStagger, timers) {
+	if (isStagger) {
+		timers.forEach((t) => clearTimeout(t))
+		const kids = Array.from(node.children)
+		const newTimers = kids.map((child, i) => {
+			if (!child.hasAttribute('data-reveal')) applyReveal(child, opts)
+			return setTimeout(
+				() => child.setAttribute('data-reveal-visible', ''),
+				opts.delay + i * opts.stagger
+			)
+		})
+		return newTimers
+	}
+	node.setAttribute('data-reveal-visible', '')
+	return timers
+}
+
+function handleIntersectLeave(node, isStagger, timers) {
+	if (isStagger) {
+		timers.forEach((t) => clearTimeout(t))
+		Array.from(node.children).forEach((child) => child.removeAttribute('data-reveal-visible'))
+		return []
+	}
+	node.removeAttribute('data-reveal-visible')
+	return timers
+}
+
+function buildObserver(node, opts, isStagger) {
+	let timers = []
+
+	const observer = new IntersectionObserver(
+		(entries) => {
+			for (const entry of entries) {
+				if (entry.isIntersecting) {
+					timers = handleIntersectEnter(node, opts, isStagger, timers)
+					node.dispatchEvent(new CustomEvent('reveal', { detail: { visible: true } }))
+					if (opts.once) observer.unobserve(node)
+				} else if (!opts.once) {
+					timers = handleIntersectLeave(node, isStagger, timers)
+					node.dispatchEvent(new CustomEvent('reveal', { detail: { visible: false } }))
+				}
+			}
+		},
+		{ threshold: opts.threshold }
+	)
+
+	observer.observe(node)
+
+	return () => {
+		timers.forEach((t) => clearTimeout(t))
+		observer.disconnect()
+		if (isStagger) {
+			Array.from(node.children).forEach((child) => cleanReveal(child))
+		} else {
+			cleanReveal(node)
+		}
+	}
+}
+
+export function reveal(node, options = {}) {
+	$effect(() => {
+		const opts = resolveRevealOpts(options)
+		const reducedMotion =
+			typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
+		const isStagger = opts.stagger > 0
+
+		initRevealElements(node, opts, isStagger)
+
+		if (reducedMotion) return handleReducedMotion(node, isStagger)
+
+		return buildObserver(node, opts, isStagger)
+	})
+}

package/src/ripple.svelte.js

@@ -0,0 +1,92 @@
+/**
+ * Ripple action — material-design inspired click ripple effect.
+ * Appends a circular expanding span at click coordinates that scales and fades out.
+ *
+ * @param {HTMLElement} node
+ * @param {RippleOptions} [options]
+ *
+ * @typedef {Object} RippleOptions
+ * @property {string} [color='currentColor'] Ripple color
+ * @property {number} [opacity=0.15] Ripple opacity
+ * @property {number} [duration=500] Ripple animation duration (ms)
+ */
+
+function resolveRippleOpts(options) {
+	return { color: 'currentColor', opacity: 0.15, duration: 500, ...options }
+}
+
+function isReducedMotion() {
+	return (
+		typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches
+	)
+}
+
+function injectRippleKeyframes() {
+	if (document.querySelector('#rokkit-ripple-keyframes')) return
+	const style = document.createElement('style')
+	style.id = 'rokkit-ripple-keyframes'
+	style.textContent = `
+		@keyframes rokkit-ripple {
+			to {
+				transform: scale(1);
+				opacity: 0;
+			}
+		}
+	`
+	document.head.appendChild(style)
+}
+
+function createRippleSpan(e, node, opts) {
+	const rect = node.getBoundingClientRect()
+	const size = Math.max(rect.width, rect.height) * 2
+	const x = e.clientX - rect.left - size / 2
+	const y = e.clientY - rect.top - size / 2
+
+	const span = document.createElement('span')
+	span.style.position = 'absolute'
+	span.style.left = `${x}px`
+	span.style.top = `${y}px`
+	span.style.width = `${size}px`
+	span.style.height = `${size}px`
+	span.style.borderRadius = '50%'
+	span.style.background = opts.color
+	span.style.opacity = String(opts.opacity)
+	span.style.transform = 'scale(0)'
+	span.style.pointerEvents = 'none'
+	span.style.animation = `rokkit-ripple ${opts.duration}ms ease-out forwards`
+	return span
+}
+
+function applyRipple(node, opts) {
+	const originalOverflow = node.style.overflow
+	const originalPosition = node.style.position
+	const computed = getComputedStyle(node).position
+	if (!computed || computed === 'static') node.style.position = 'relative'
+	node.style.overflow = 'hidden'
+
+	function onClick(e) {
+		const span = createRippleSpan(e, node, opts)
+		node.appendChild(span)
+		span.addEventListener('animationend', () => span.remove(), { once: true })
+		setTimeout(() => {
+			if (span.parentNode) span.remove()
+		}, opts.duration + 100)
+	}
+
+	injectRippleKeyframes()
+	node.addEventListener('click', onClick)
+
+	return () => {
+		node.removeEventListener('click', onClick)
+		node.style.overflow = originalOverflow
+		node.style.position = originalPosition
+	}
+}
+
+export function ripple(node, options = {}) {
+	$effect(() => {
+		const opts = resolveRippleOpts(options)
+		if (isReducedMotion()) return
+		return applyRipple(node, opts)
+	})
+}

package/src/skinnable.svelte.js

@@ -0,0 +1,12 @@
+/**
+ * Applies theme variables to an element
+ * @param {HTMLElement} node - Element to apply variables to
+ * @param {Object.<string, string>} variables - CSS variables and their values
+ */
+export function skinnable(node, variables) {
+	$effect(() => {
+		Object.entries(variables).forEach(([key, value]) => {
+			node.style.setProperty(key, value)
+		})
+	})
+}