@rokkit/actions 1.0.2 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jerry Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/delegate.svelte.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Svelte action function for forwarding keyboard events from a parent element to a child.
+ * The child is selected using a CSS selector passed in the options object.
+ * Optionally, you can specify which keyboard events you want to forward: "keydown", "keyup", and/or "keypress".
+ * By default, all three events are forwarded.
+ *
+ * @param {HTMLElement} element - The parent element from which keyboard events will be forwarded.
+ * @param {import('./types').PushDownOptions} options - The options object.
+ * @returns {{destroy: Function}}
+ */
+export function delegateKeyboardEvents(element: HTMLElement, { selector, events }: import("./types").PushDownOptions): {
+    destroy: Function;
+};

package/dist/dismissable.svelte.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A svelte action function that captures clicks outside the element or escape keypress
+ * emits a `dismiss` event. This is useful for closing a modal or dropdown.
+ *
+ * @param {HTMLElement} node
+ */
+export function dismissable(node: HTMLElement): void;

package/dist/fillable.svelte.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Action for filling a <del>?</del> element in html block.
+ *
+ * @param {HTMLElement} node
+ * @param {import('./types').FillOptions} options
+ * @returns
+ */
+export function fillable(node: HTMLElement, data: any): void;

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

@@ -0,0 +1,19 @@
+export function hoverLift(node: any, options?: {}): 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

@@ -0,0 +1,19 @@
+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";
+export { navigator } from "./navigator.svelte.js";
+export { themable } from "./themable.svelte.js";
+export { skinnable } from "./skinnable.svelte.js";
+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 { tooltip } from "./tooltip.svelte.js";
+export { buildKeymap, resolveAction, ACTIONS } from "./keymap.js";

package/dist/kbd.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Gets keyboard action handlers based on orientation and direction
+ * @param {Object} options - Configuration options
+ * @param {Object} handlers - Event handler functions
+ * @returns {Object} Object mapping key presses to handler functions
+ */
+export function getKeyboardActions(options: Object, handlers: Object): Object;
+/**
+ * Creates a keyboard action mapping based on navigation options
+ *
+ * @param {Object} options - Navigation options
+ * @param {string} options.orientation - Whether navigation is horizontal or vertical
+ * @param {string} options.dir - Text direction ('ltr' or 'rtl')
+ * @param {boolean} options.nested - Whether navigation is nested
+ * @returns {Object} Mapping of keys to actions
+ */
+export function createKeyboardActionMap(options: {
+    orientation: string;
+    dir: string;
+    nested: boolean;
+}): Object;
+/**
+ * Creates a keyboard action mapping for modifier keys based on navigation options
+ *
+ * @param {Object} options - Navigation options
+ * @param {string} options.orientation - Whether navigation is horizontal or vertical
+ * @returns {Object} Mapping of keys to actions
+ */
+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
+ * @param {Object} options - Configuration options
+ * @returns {string|null} The action to perform, or null if no action is defined
+ */
+export function getKeyboardAction(event: KeyboardEvent, options?: Object): string | null;
+export namespace defaultNavigationOptions {
+    let orientation: string;
+    let dir: string;
+    let nested: boolean;
+    let enabled: boolean;
+    let typeahead: boolean;
+}

package/dist/keyboard.svelte.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Handle keyboard events
+ *
+ * @param {HTMLElement} root
+ * @param {import('./types.js').KeyboardConfig} options - Custom key mappings
+ */
+export function keyboard(root: HTMLElement, options?: import("./types.js").KeyboardConfig): void;

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/lib/event-manager.d.ts

@@ -0,0 +1,8 @@
+/**
+ * EventManager class to manage event listeners on an element.
+ *
+ * @param {HTMLElement} element  - The element to listen for events on.
+ * @param {Object}      handlers - An object with event names as keys and event handlers as values.
+ * @returns {Object} - An object with methods to activate, reset, and update the event listeners.
+ */
+export function EventManager(element: HTMLElement, handlers?: Object, enabled?: boolean): Object;

package/dist/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./internal";
+export { EventManager } from "./event-manager";

package/dist/lib/internal.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Sets up event handlers based on the given options.
+ * Returns whether or not the event handlers are listening.
+ *
+ * @param {HTMLElement} element
+ * @param {import('../types').EventHandlers} listeners
+ * @param {import('../types').TraversableOptions} options
+ * @returns {void}
+ */
+export function setupListeners(element: HTMLElement, listeners: import("../types").EventHandlers, options: import("../types").TraversableOptions): void;
+/**
+ * Removes event handlers based on the given options.
+ * Returns whether or not the event handlers are listening.
+ *
+ * @param {HTMLElement} element
+ * @param {import('../types').EventHandlers} listeners
+ * @returns {void}
+ */
+export function removeListeners(element: HTMLElement, listeners: import("../types").EventHandlers): void;

package/dist/magnetic.svelte.d.ts

@@ -0,0 +1,15 @@
+export function magnetic(node: any, options?: {}): 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/navigable.svelte.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 navigable(node: HTMLElement, options: import("./types").NavigableOptions): import("./types").SvelteActionReturn;

package/dist/navigator.d.ts

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

package/dist/navigator.svelte.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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: HTMLElement, controller: any, name: any, lastOnly?: boolean): void;
+export function handleAction(event: any, handler: any, path: any): any;
+/**
+ * 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: HTMLElement, options: import("./types").NavigableOptions): import("./types").SvelteActionReturn;

package/dist/pannable.svelte.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Makes an element pannable with mouse or touch events.
+ *
+ * @param {HTMLElement} node The DOM element to apply the panning action.
+ */
+export function pannable(node: HTMLElement): void;

package/dist/reveal.svelte.d.ts

@@ -0,0 +1,40 @@
+export function reveal(node: any, options?: {}): void;
+/**
+ * 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.
+ */
+export type RevealOptions = {
+    /**
+     * Slide direction
+     */
+    direction?: "none" | "left" | "right" | "up" | "down" | undefined;
+    /**
+     * Slide distance (CSS unit)
+     */
+    distance?: string | undefined;
+    /**
+     * Animation duration (ms)
+     */
+    duration?: number | undefined;
+    /**
+     * Delay before animation starts (ms)
+     */
+    delay?: number | undefined;
+    /**
+     * Delay increment per child in ms (0 = disabled)
+     */
+    stagger?: 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,19 @@
+export function ripple(node: any, options?: {}): 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/skinnable.svelte.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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: HTMLElement, variables: {
+    [x: string]: string;
+}): void;

package/dist/swipeable.svelte.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A svelte action function that captures swipe actions and emits event for corresponding movements.
+ *
+ * @param {HTMLElement} node
+ * @param {import(./types).SwipeableOptions} options
+ * @returns {import('./types').SvelteActionReturn}
+ */
+export function swipeable(node: HTMLElement, options?: {
+    horizontal: boolean;
+    vertical: boolean;
+    threshold: number;
+    enabled: boolean;
+    minSpeed: number;
+}): import("./types").SvelteActionReturn;

package/dist/themable.svelte.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Update the theme attributes when the state changes.
+ *
+ * @param {HTMLElement} root
+ * @param {import('./types.js').ThemableConfig} options - Custom key mappings
+ */
+export function themable(root: HTMLElement, options: import("./types.js").ThemableConfig): void;

package/dist/tooltip.svelte.d.ts

@@ -0,0 +1 @@
+export function tooltip(node: any, options?: {}): void;

package/dist/trigger.d.ts

@@ -0,0 +1,18 @@
+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/dist/types.d.ts

@@ -0,0 +1,72 @@
+export type EventMapping = {
+    /**
+     * - The event name
+     */
+    event: string;
+    /**
+     * - The keys that trigger the event
+     */
+    keys?: string[] | undefined;
+    /**
+     * - The pattern that triggers the event
+     */
+    pattern?: RegExp | undefined;
+};
+export type KeyboardConfig = {
+    [x: string]: RegExp | string[];
+};
+export type Direction = "vertical" | "horizontal";
+export type NavigatorOptions = {
+    /**
+     * - Whether the navigator is enabled
+     */
+    enabled: boolean;
+    /**
+     * - Whether the navigator is vertical or horizontal
+     */
+    direction: Direction;
+    /**
+     * - Whether the navigator supports multiple selections
+     */
+    multiselect: boolean;
+};
+export type DataWrapper = {
+    moveNext: Function;
+    movePrev: Function;
+    moveFirst: Function;
+    moveLast: Function;
+    expand: Function;
+    collapse: Function;
+    select: Function;
+    toggleExpansion: Function;
+};
+export type NavigatorActions = {
+    next: Function;
+    prev: Function;
+    first: Function;
+    last: Function;
+    expand: Function;
+    collapse: Function;
+    select: Function;
+};
+export type NavigatorConfig = {
+    /**
+     * - Whether the navigator is enabled
+     */
+    wrapper: Navigator;
+    /**
+     * - Whether the navigator is vertical or horizontal
+     */
+    options: NavigatorOptions;
+};
+export type Controller = {
+    moveNext: Function;
+    movePrev: Function;
+    moveFirst: Function;
+    moveLast: Function;
+    expand?: Function | undefined;
+    collapse?: Function | undefined;
+    select: Function;
+    extendSelection: Function;
+    toggleExpansion?: Function | undefined;
+};

package/dist/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Finds the closest ancestor of the given element that has the given attribute.
+ *
+ * @param {HTMLElement} element
+ * @param {string} attribute
+ * @returns {HTMLElement|null}
+ */
+export function getClosestAncestorWithAttribute(element: HTMLElement, attribute: string): HTMLElement | null;
+export function handleAction(actions: any, event: any): void;
+/**
+ * Finds and returns an index path based on data-path attribute
+ *
+ * @param {MouseEvent} event
+ * @returns {number[]|null} null or index path array
+ */
+export function getPathFromEvent(event: MouseEvent): number[] | null;
+export function getEventForKey(keyMapping: import("./types.js").KeyboardConfig, key: string): string | null;
+export function getClickAction(event: MouseEvent): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Contains generic actions that can be used in various components.",
   "repository": {
     "type": "git",