@rokkit/actions 1.0.0-next.125 → 1.0.0-next.128

package/dist/hover-lift.svelte.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Hover lift action — adds translateY + elevated shadow on hover.
+ * Sets transition on mount, applies transform + box-shadow on mouseenter, resets on mouseleave.
+ *
+ * @param {HTMLElement} node
+ * @param {HoverLiftOptions} [options]
+ *
+ * @typedef {Object} HoverLiftOptions
+ * @property {string} [distance='-0.25rem'] Translate distance on hover (negative = up)
+ * @property {string} [shadow='0 10px 25px -5px rgba(0,0,0,0.1)'] Box shadow on hover
+ * @property {number} [duration=200] Transition duration (ms)
+ */
+export function hoverLift(node: HTMLElement, options?: HoverLiftOptions): void;
+/**
+ * Hover lift action — adds translateY + elevated shadow on hover.
+ * Sets transition on mount, applies transform + box-shadow on mouseenter, resets on mouseleave.
+ */
+export type HoverLiftOptions = {
+    /**
+     * Translate distance on hover (negative = up)
+     */
+    distance?: string | undefined;
+    /**
+     * Box shadow on hover
+     */
+    shadow?: string | undefined;
+    /**
+     * Transition duration (ms)
+     */
+    duration?: number | undefined;
+};

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./types.js";
+export { Navigator } from "./navigator.js";
+export { Trigger } from "./trigger.js";
 export { keyboard } from "./keyboard.svelte.js";
 export { pannable } from "./pannable.svelte.js";
 export { swipeable } from "./swipeable.svelte.js";
@@ -9,3 +11,8 @@ export { dismissable } from "./dismissable.svelte.js";
 export { navigable } from "./navigable.svelte.js";
 export { fillable } from "./fillable.svelte.js";
 export { delegateKeyboardEvents } from "./delegate.svelte.js";
+export { reveal } from "./reveal.svelte.js";
+export { hoverLift } from "./hover-lift.svelte.js";
+export { magnetic } from "./magnetic.svelte.js";
+export { ripple } from "./ripple.svelte.js";
+export { buildKeymap, resolveAction, ACTIONS } from "./keymap.js";

package/dist/kbd.d.ts

@@ -29,6 +29,12 @@ export function createKeyboardActionMap(options: {
 export function createModifierKeyboardActionMap(options: {
     orientation: string;
 }): Object;
+/**
+ * Creates a keyboard action mapping for shift key combinations
+ *
+ * @returns {Object} Mapping of keys to actions
+ */
+export function createShiftKeyboardActionMap(): Object;
 /**
  * Gets the keyboard action for a key event
  * @param {KeyboardEvent} event - The keyboard event
@@ -41,4 +47,5 @@ export namespace defaultNavigationOptions {
     let dir: string;
     let nested: boolean;
     let enabled: boolean;
+    let typeahead: boolean;
 }

package/dist/keymap.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Build a complete keymap for the given options.
+ *
+ * Returns three layers — plain, shift, ctrl — each mapping key name → action name.
+ * Call resolveAction(event, keymap) to look up the action for a keyboard event.
+ *
+ * @param {Object} [options]
+ * @param {'vertical'|'horizontal'} [options.orientation='vertical']
+ * @param {'ltr'|'rtl'} [options.dir='ltr']
+ * @param {boolean} [options.collapsible=false]
+ * @returns {{ plain: Record<string, string>, shift: Record<string, string>, ctrl: Record<string, string> }}
+ */
+export function buildKeymap({ orientation, dir, collapsible }?: {
+    orientation?: "vertical" | "horizontal" | undefined;
+    dir?: "ltr" | "rtl" | undefined;
+    collapsible?: boolean | undefined;
+}): {
+    plain: Record<string, string>;
+    shift: Record<string, string>;
+    ctrl: Record<string, string>;
+};
+/**
+ * Resolve the action for a keyboard event given a pre-built keymap.
+ * Returns null if the key has no binding.
+ *
+ * @param {KeyboardEvent} event
+ * @param {{ plain: Record<string, string>, shift: Record<string, string>, ctrl: Record<string, string> }} keymap
+ * @returns {string|null}
+ */
+export function resolveAction(event: KeyboardEvent, keymap: {
+    plain: Record<string, string>;
+    shift: Record<string, string>;
+    ctrl: Record<string, string>;
+}): string | null;
+export { ACTIONS } from "./nav-constants.js";

package/dist/magnetic.svelte.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Magnetic action — element shifts subtly toward the cursor on hover.
+ * Calculates cursor offset from element center and translates proportionally.
+ *
+ * @param {HTMLElement} node
+ * @param {MagneticOptions} [options]
+ *
+ * @typedef {Object} MagneticOptions
+ * @property {number} [strength=0.3] Maximum displacement as fraction of element size (0–1)
+ * @property {number} [duration=300] Transition duration for return to center (ms)
+ */
+export function magnetic(node: HTMLElement, options?: MagneticOptions): void;
+/**
+ * Magnetic action — element shifts subtly toward the cursor on hover.
+ * Calculates cursor offset from element center and translates proportionally.
+ */
+export type MagneticOptions = {
+    /**
+     * Maximum displacement as fraction of element size (0–1)
+     */
+    strength?: number | undefined;
+    /**
+     * Transition duration for return to center (ms)
+     */
+    duration?: number | undefined;
+};

package/dist/nav-constants.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Navigator constants — keyboard actions, key bindings, and typeahead config.
+ * These are used by the Navigator class and keymap builder.
+ */
+export const ACTIONS: Readonly<{
+    next: "next";
+    prev: "prev";
+    first: "first";
+    last: "last";
+    expand: "expand";
+    collapse: "collapse";
+    select: "select";
+    extend: "extend";
+    range: "range";
+    cancel: "cancel";
+}>;
+export const PLAIN_FIXED: {
+    Enter: "select";
+    ' ': "select";
+    Home: "first";
+    End: "last";
+    Escape: "cancel";
+};
+export const CTRL_FIXED: {
+    ' ': "extend";
+    Home: "first";
+    End: "last";
+};
+export const SHIFT_FIXED: {
+    ' ': "range";
+};
+export const ARROWS: {
+    'vertical-ltr': {
+        move: {
+            ArrowUp: "prev";
+            ArrowDown: "next";
+        };
+        nested: {
+            ArrowLeft: "collapse";
+            ArrowRight: "expand";
+        };
+    };
+    'vertical-rtl': {
+        move: {
+            ArrowUp: "prev";
+            ArrowDown: "next";
+        };
+        nested: {
+            ArrowRight: "collapse";
+            ArrowLeft: "expand";
+        };
+    };
+    horizontal: {
+        move: {
+            ArrowLeft: "prev";
+            ArrowRight: "next";
+        };
+        nested: {
+            ArrowUp: "collapse";
+            ArrowDown: "expand";
+        };
+    };
+};
+/** Milliseconds of inactivity before the typeahead buffer resets. */
+export const TYPEAHEAD_RESET_MS: 500;

package/dist/navigator.d.ts

@@ -0,0 +1,14 @@
+export class Navigator {
+    /**
+     * @param {HTMLElement} root
+     * @param {import('@rokkit/states').Wrapper} wrapper
+     * @param {{ orientation?: string, dir?: string, collapsible?: boolean }} [options]
+     */
+    constructor(root: HTMLElement, wrapper: import("@rokkit/states").Wrapper, options?: {
+        orientation?: string;
+        dir?: string;
+        collapsible?: boolean;
+    });
+    destroy(): void;
+    #private;
+}

package/dist/reveal.svelte.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Scroll-triggered reveal action using IntersectionObserver.
+ * Applies CSS transitions (opacity + translate) when element enters viewport.
+ *
+ * @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 {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
+ */
+export function reveal(node: HTMLElement, options?: RevealOptions): void;
+/**
+ * Scroll-triggered reveal action using IntersectionObserver.
+ * Applies CSS transitions (opacity + translate) when element enters viewport.
+ */
+export type RevealOptions = {
+    /**
+     * Slide direction
+     */
+    direction?: "up" | "down" | "left" | "right" | "none" | undefined;
+    /**
+     * Slide distance (CSS unit)
+     */
+    distance?: string | undefined;
+    /**
+     * Animation duration (ms)
+     */
+    duration?: number | undefined;
+    /**
+     * Delay before animation starts (ms)
+     */
+    delay?: number | undefined;
+    /**
+     * Only animate once
+     */
+    once?: boolean | undefined;
+    /**
+     * IntersectionObserver threshold (0–1)
+     */
+    threshold?: number | undefined;
+    /**
+     * CSS easing function
+     */
+    easing?: string | undefined;
+};

package/dist/ripple.svelte.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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)
+ */
+export function ripple(node: HTMLElement, options?: RippleOptions): void;
+/**
+ * Ripple action — material-design inspired click ripple effect.
+ * Appends a circular expanding span at click coordinates that scales and fades out.
+ */
+export type RippleOptions = {
+    /**
+     * Ripple color
+     */
+    color?: string | undefined;
+    /**
+     * Ripple opacity
+     */
+    opacity?: number | undefined;
+    /**
+     * Ripple animation duration (ms)
+     */
+    duration?: number | undefined;
+};

package/dist/trigger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Trigger
+ *
+ * Manages dropdown open/close from a trigger button.
+ * Pairs with Navigator (on the dropdown) to form a complete dropdown component.
+ *
+ * Responsibilities:
+ *   - click on trigger     → toggle open/close
+ *   - Enter / Space        → toggle open/close
+ *   - ArrowDown            → open (callback can focus first item)
+ *   - ArrowUp              → open (callback can focus last item)
+ *   - Escape (document)    → close + return focus to trigger
+ *   - Click outside (doc)  → close
+ *
+ * Usage:
+ *   const trigger = new Trigger(triggerEl, containerEl, {
+ *     onopen: () => { isOpen = true },
+ *     onclose: () => { isOpen = false },
+ *     onlast: () => { wrapper.last(null) }  // optional: ArrowUp opens at end
+ *   })
+ *   // …
+ *   trigger.destroy()
+ */
+export class Trigger {
+    /**
+     * @param {HTMLElement} trigger    — the trigger button element
+     * @param {HTMLElement} container  — the menu root (for click-outside detection)
+     * @param {{ onopen: () => void, onclose: () => void, onlast?: () => void, isOpen: () => boolean }} callbacks
+     */
+    constructor(trigger: HTMLElement, container: HTMLElement, { onopen, onclose, onlast, isOpen }: {
+        onopen: () => void;
+        onclose: () => void;
+        onlast?: () => void;
+        isOpen: () => boolean;
+    });
+    get isOpen(): boolean;
+    open(): void;
+    close(): void;
+    destroy(): void;
+    #private;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.0-next.125",
+  "version": "1.0.0-next.128",
   "description": "Contains generic actions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",
@@ -29,7 +29,7 @@
     }
   },
   "dependencies": {
-    "ramda": "^0.31.3",
+    "ramda": "^0.32.0",
     "@rokkit/core": "latest"
   },
   "devDependencies": {

package/src/hover-lift.svelte.js

@@ -0,0 +1,56 @@
+/**
+ * Hover lift action — adds translateY + elevated shadow on hover.
+ * Sets transition on mount, applies transform + box-shadow on mouseenter, resets on mouseleave.
+ *
+ * @param {HTMLElement} node
+ * @param {HoverLiftOptions} [options]
+ *
+ * @typedef {Object} HoverLiftOptions
+ * @property {string} [distance='-0.25rem'] Translate distance on hover (negative = up)
+ * @property {string} [shadow='0 10px 25px -5px rgba(0,0,0,0.1)'] Box shadow on hover
+ * @property {number} [duration=200] Transition duration (ms)
+ */
+export function hoverLift(node, options = {}) {
+	$effect(() => {
+		const opts = {
+			distance: '-0.25rem',
+			shadow: '0 10px 25px -5px rgba(0,0,0,0.1)',
+			duration: 200,
+			...options
+		}
+
+		const reducedMotion =
+			typeof window !== 'undefined' &&
+			window.matchMedia('(prefers-reduced-motion: reduce)').matches
+
+		if (reducedMotion) return
+
+		// Store original values
+		const originalTransform = node.style.transform
+		const originalBoxShadow = node.style.boxShadow
+		const originalTransition = node.style.transition
+
+		node.style.transition = `transform ${opts.duration}ms ease, box-shadow ${opts.duration}ms ease`
+
+		function onEnter() {
+			node.style.transform = `translateY(${opts.distance})`
+			node.style.boxShadow = opts.shadow
+		}
+
+		function onLeave() {
+			node.style.transform = originalTransform
+			node.style.boxShadow = originalBoxShadow
+		}
+
+		node.addEventListener('mouseenter', onEnter)
+		node.addEventListener('mouseleave', onLeave)
+
+		return () => {
+			node.removeEventListener('mouseenter', onEnter)
+			node.removeEventListener('mouseleave', onLeave)
+			node.style.transform = originalTransform
+			node.style.boxShadow = originalBoxShadow
+			node.style.transition = originalTransition
+		}
+	})
+}

package/src/index.js

@@ -1,5 +1,8 @@
 // skipcq: JS-E1004 - Needed for exposing all types
 export * from './types.js'
+export { Navigator } from './navigator.js'
+export { Trigger } from './trigger.js'
+export { buildKeymap, resolveAction, ACTIONS } from './keymap.js'
 export { keyboard } from './keyboard.svelte.js'
 export { pannable } from './pannable.svelte.js'
 export { swipeable } from './swipeable.svelte.js'
@@ -10,3 +13,7 @@ export { dismissable } from './dismissable.svelte.js'
 export { navigable } from './navigable.svelte.js'
 export { fillable } from './fillable.svelte.js'
 export { delegateKeyboardEvents } from './delegate.svelte.js'
+export { reveal } from './reveal.svelte.js'
+export { hoverLift } from './hover-lift.svelte.js'
+export { magnetic } from './magnetic.svelte.js'
+export { ripple } from './ripple.svelte.js'

package/src/kbd.js

@@ -57,7 +57,8 @@ export const defaultNavigationOptions = {
 	orientation: 'vertical',
 	dir: 'ltr',
 	nested: false,
-	enabled: true
+	enabled: true,
+	typeahead: false
 }
 
 /**
@@ -161,6 +162,15 @@ export function createModifierKeyboardActionMap(options) {
 	return { ...common, ...directional }
 }
 
+/**
+ * Creates a keyboard action mapping for shift key combinations
+ *
+ * @returns {Object} Mapping of keys to actions
+ */
+export function createShiftKeyboardActionMap() {
+	return { ' ': 'range' }
+}
+
 /**
  * Gets the keyboard action for a key event
  * @param {KeyboardEvent} event - The keyboard event
@@ -168,12 +178,18 @@ export function createModifierKeyboardActionMap(options) {
  * @returns {string|null} The action to perform, or null if no action is defined
  */
 export function getKeyboardAction(event, options = {}) {
-	const { key, ctrlKey, metaKey } = event
+	const { key, ctrlKey, metaKey, shiftKey } = event
 
 	// Use updated options with defaults
 	const mergedOptions = { ...defaultNavigationOptions, ...options }
 
-	// Check for modifier keys first (highest priority)
+	// Check for shift key (range selection)
+	if (shiftKey && !ctrlKey && !metaKey) {
+		const shiftMap = createShiftKeyboardActionMap()
+		return shiftMap[key] || null
+	}
+
+	// Check for modifier keys (ctrl/cmd)
 	if (ctrlKey || metaKey) {
 		const modifierMap = createModifierKeyboardActionMap(mergedOptions)
 		return modifierMap[key] || null

package/src/keymap.js

@@ -0,0 +1,81 @@
+/**
+ * List Keymap
+ *
+ * Maps keyboard inputs to semantic actions.
+ *
+ * Design principle: orientation is just a rotation of arrow key assignments.
+ *
+ *   vertical ltr  up/down  = prev/next    left/right = collapse/expand  (when collapsible)
+ *   vertical rtl  up/down  = prev/next    right/left = collapse/expand  (expand/collapse reversed)
+ *   horizontal    left/right = prev/next  up/down    = collapse/expand  (dir ignored — use CSS flex-reverse for RTL)
+ *
+ * ─── Actions ────────────────────────────────────────────────────────────────
+ *
+ *   next       focus next visible item, skip disabled
+ *   prev       focus previous visible item, skip disabled
+ *   first      jump to first visible item
+ *   last       jump to last visible item
+ *   expand     when collapsible: expand collapsed group
+ *              if already expanded: move focus to first child
+ *              on leaf: no-op
+ *   collapse   when collapsible: collapse expanded group
+ *              if already collapsed or leaf: move focus to parent
+ *              at root level: no-op
+ *   select     activate the focused item
+ *   extend     toggle individual selection (multiselect ctrl/cmd + space)
+ *   range      select contiguous range (multiselect shift + space)
+ */
+
+import { PLAIN_FIXED, CTRL_FIXED, SHIFT_FIXED, ARROWS } from './nav-constants.js'
+export { ACTIONS } from './nav-constants.js'
+
+function getArrows(orientation, dir) {
+	if (orientation === 'horizontal') return ARROWS.horizontal
+	return ARROWS[`vertical-${dir}`]
+}
+
+// ─── buildKeymap ──────────────────────────────────────────────────────────────
+
+/**
+ * Build a complete keymap for the given options.
+ *
+ * Returns three layers — plain, shift, ctrl — each mapping key name → action name.
+ * Call resolveAction(event, keymap) to look up the action for a keyboard event.
+ *
+ * @param {Object} [options]
+ * @param {'vertical'|'horizontal'} [options.orientation='vertical']
+ * @param {'ltr'|'rtl'} [options.dir='ltr']
+ * @param {boolean} [options.collapsible=false]
+ * @returns {{ plain: Record<string, string>, shift: Record<string, string>, ctrl: Record<string, string> }}
+ */
+export function buildKeymap({ orientation = 'vertical', dir = 'ltr', collapsible = false } = {}) {
+	const arrows = getArrows(orientation, dir)
+
+	return {
+		plain: {
+			...PLAIN_FIXED,
+			...arrows.move,
+			...(collapsible ? arrows.nested : {})
+		},
+		shift: { ...SHIFT_FIXED },
+		ctrl: { ...CTRL_FIXED }
+	}
+}
+
+// ─── resolveAction ────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the action for a keyboard event given a pre-built keymap.
+ * Returns null if the key has no binding.
+ *
+ * @param {KeyboardEvent} event
+ * @param {{ plain: Record<string, string>, shift: Record<string, string>, ctrl: Record<string, string> }} keymap
+ * @returns {string|null}
+ */
+export function resolveAction(event, keymap) {
+	const { key, ctrlKey, metaKey, shiftKey } = event
+
+	if (shiftKey && !ctrlKey && !metaKey) return keymap.shift[key] ?? null
+	if (ctrlKey || metaKey) return keymap.ctrl[key] ?? null
+	return keymap.plain[key] ?? null
+}

package/src/magnetic.svelte.js

@@ -0,0 +1,58 @@
+/**
+ * Magnetic action — element shifts subtly toward the cursor on hover.
+ * Calculates cursor offset from element center and translates proportionally.
+ *
+ * @param {HTMLElement} node
+ * @param {MagneticOptions} [options]
+ *
+ * @typedef {Object} MagneticOptions
+ * @property {number} [strength=0.3] Maximum displacement as fraction of element size (0–1)
+ * @property {number} [duration=300] Transition duration for return to center (ms)
+ */
+export function magnetic(node, options = {}) {
+	$effect(() => {
+		const opts = {
+			strength: 0.3,
+			duration: 300,
+			...options
+		}
+
+		const reducedMotion =
+			typeof window !== 'undefined' &&
+			window.matchMedia('(prefers-reduced-motion: reduce)').matches
+
+		if (reducedMotion) return
+
+		const originalTransform = node.style.transform
+		const originalTransition = node.style.transition
+
+		node.style.transition = `transform ${opts.duration}ms ease`
+
+		function onMove(e) {
+			const rect = node.getBoundingClientRect()
+			const centerX = rect.left + rect.width / 2
+			const centerY = rect.top + rect.height / 2
+
+			const offsetX = (e.clientX - centerX) * opts.strength
+			const offsetY = (e.clientY - centerY) * opts.strength
+
+			node.style.transition = 'none'
+			node.style.transform = `translate(${offsetX}px, ${offsetY}px)`
+		}
+
+		function onLeave() {
+			node.style.transition = `transform ${opts.duration}ms ease`
+			node.style.transform = originalTransform
+		}
+
+		node.addEventListener('mousemove', onMove)
+		node.addEventListener('mouseleave', onLeave)
+
+		return () => {
+			node.removeEventListener('mousemove', onMove)
+			node.removeEventListener('mouseleave', onLeave)
+			node.style.transform = originalTransform
+			node.style.transition = originalTransition
+		}
+	})
+}

package/src/nav-constants.js

@@ -0,0 +1,61 @@
+/**
+ * Navigator constants — keyboard actions, key bindings, and typeahead config.
+ * These are used by the Navigator class and keymap builder.
+ */
+
+// ─── Navigator actions ────────────────────────────────────────────────────────
+
+export const ACTIONS = Object.freeze({
+	next: 'next',
+	prev: 'prev',
+	first: 'first',
+	last: 'last',
+	expand: 'expand',
+	collapse: 'collapse',
+	select: 'select',
+	extend: 'extend',
+	range: 'range',
+	cancel: 'cancel' // Escape — close dropdown, deselect, or dismiss
+})
+
+// ─── Keymap: fixed key bindings (orientation-independent) ────────────────────
+
+export const PLAIN_FIXED = {
+	Enter: ACTIONS.select,
+	' ': ACTIONS.select,
+	Home: ACTIONS.first,
+	End: ACTIONS.last,
+	Escape: ACTIONS.cancel
+}
+
+export const CTRL_FIXED = {
+	' ': ACTIONS.extend,
+	Home: ACTIONS.first,
+	End: ACTIONS.last
+}
+
+export const SHIFT_FIXED = {
+	' ': ACTIONS.range
+}
+
+// ─── Keymap: arrow key assignments per orientation/direction ──────────────────
+
+export const ARROWS = {
+	'vertical-ltr': {
+		move: { ArrowUp: ACTIONS.prev, ArrowDown: ACTIONS.next },
+		nested: { ArrowLeft: ACTIONS.collapse, ArrowRight: ACTIONS.expand }
+	},
+	'vertical-rtl': {
+		move: { ArrowUp: ACTIONS.prev, ArrowDown: ACTIONS.next },
+		nested: { ArrowRight: ACTIONS.collapse, ArrowLeft: ACTIONS.expand }
+	},
+	horizontal: {
+		move: { ArrowLeft: ACTIONS.prev, ArrowRight: ACTIONS.next },
+		nested: { ArrowUp: ACTIONS.collapse, ArrowDown: ACTIONS.expand }
+	}
+}
+
+// ─── Typeahead ────────────────────────────────────────────────────────────────
+
+/** Milliseconds of inactivity before the typeahead buffer resets. */
+export const TYPEAHEAD_RESET_MS = 500