@bemedev/mind-flow 0.3.2 → 1.1.0

package/src/ui/globals/directives/mouseOut.test.ts

@@ -0,0 +1,115 @@
+import { createRoot } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { mouseOut } from './mouseOut';
+
+describe('Directive => mouseOut', () => {
+  let el: HTMLDivElement;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    el = document.createElement('div');
+    document.body.appendChild(el);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    el.remove();
+  });
+
+  it('#01 => should trigger callback immediately when no delay is provided', () => {
+    const callback = vi.fn();
+
+    createRoot(dispose => {
+      mouseOut(el, () => callback);
+
+      el.dispatchEvent(new MouseEvent('mouseleave'));
+      expect(callback).toHaveBeenCalledTimes(1);
+
+      dispose();
+    });
+  });
+
+  it('#02 => should wait for the specified delay before executing the callback', () => {
+    const callback = vi.fn();
+
+    createRoot(dispose => {
+      mouseOut(el, () => [callback, 300]);
+
+      el.dispatchEvent(new MouseEvent('mouseleave'));
+      expect(callback).not.toHaveBeenCalled();
+
+      vi.advanceTimersByTime(200);
+      expect(callback).not.toHaveBeenCalled();
+
+      vi.advanceTimersByTime(100);
+      expect(callback).toHaveBeenCalledTimes(1);
+
+      dispose();
+    });
+  });
+
+  it('#03 => should reset/cancel the timer when user re-enters before delay finishes', () => {
+    const callback = vi.fn();
+
+    createRoot(dispose => {
+      mouseOut(el, () => ({ callback, delay: 500 }));
+
+      el.dispatchEvent(new MouseEvent('mouseleave'));
+      expect(callback).not.toHaveBeenCalled();
+
+      vi.advanceTimersByTime(300);
+      expect(callback).not.toHaveBeenCalled();
+
+      // User re-enters
+      el.dispatchEvent(new MouseEvent('mouseenter'));
+
+      // Time passes past the original 500ms
+      vi.advanceTimersByTime(500);
+      expect(callback).not.toHaveBeenCalled();
+
+      dispose();
+    });
+  });
+
+  it('#04 => should re-arm timer when mouse leaves again after re-entering', () => {
+    const callback = vi.fn();
+
+    createRoot(dispose => {
+      mouseOut(el, () => ({ onMouseOut: callback, delay: 400 }));
+
+      el.dispatchEvent(new MouseEvent('mouseleave'));
+      vi.advanceTimersByTime(200);
+      el.dispatchEvent(new MouseEvent('mouseenter'));
+      vi.advanceTimersByTime(300);
+      expect(callback).not.toHaveBeenCalled();
+
+      // Leave again
+      el.dispatchEvent(new MouseEvent('mouseleave'));
+      vi.advanceTimersByTime(400);
+      expect(callback).toHaveBeenCalledTimes(1);
+
+      dispose();
+    });
+  });
+
+  it('#05 => should cancel pending timer and remove event listeners on cleanup', () => {
+    const callback = vi.fn();
+
+    let disposeRoot!: () => void;
+    createRoot(dispose => {
+      disposeRoot = dispose;
+      mouseOut(el, () => [callback, 300]);
+    });
+
+    el.dispatchEvent(new MouseEvent('mouseleave'));
+    disposeRoot();
+
+    vi.advanceTimersByTime(400);
+    expect(callback).not.toHaveBeenCalled();
+
+    // Ensure listeners are removed
+    el.dispatchEvent(new MouseEvent('mouseleave'));
+    expect(callback).not.toHaveBeenCalled();
+  });
+});

package/src/ui/globals/directives/mouseOut.ts

@@ -0,0 +1,98 @@
+import { onCleanup } from 'solid-js';
+
+/**
+ * Callback function type invoked when the mouse leaves the bound element.
+ *
+ * @param event - Optional mouse event that triggered the leave.
+ */
+export type MouseOutCallback = (event?: MouseEvent) => void;
+
+/** Configuration options for the {@linkcode mouseOut} directive. */
+export type MouseOutOptions = {
+  /** Callback function to trigger after the timer elapses. */
+  callback?: MouseOutCallback;
+
+  /** Alternative callback property name for triggering after the timer elapses. */
+  onMouseOut?: MouseOutCallback;
+
+  /**
+   * Delay in milliseconds before triggering the callback after the mouse leaves. If
+   * the cursor re-enters the element before this duration, the timer is reset.
+   *
+   * @defaultValue 0
+   */
+  delay?: number;
+};
+
+/** Accepted parameter shapes for the {@linkcode mouseOut} directive. */
+export type MouseOutParam =
+  | MouseOutCallback
+  | [callback: MouseOutCallback, delay?: number]
+  | MouseOutOptions;
+
+/**
+ * Solid custom directive that triggers a callback when the mouse leaves the bound
+ * element after a specified timer duration. If the user re-enters the component
+ * before the timer expires, the timer is reset/cancelled.
+ *
+ * @param el - The bound DOM element.
+ * @param accessor - Accessor returning a callback, tuple `[callback, delay]`, or
+ *   type {@linkcode MouseOutOptions}.
+ */
+export const mouseOut = (
+  el: HTMLElement | Element,
+  accessor: () => MouseOutParam,
+) => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const clear = () => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  const onMouseEnter = () => {
+    clear();
+  };
+
+  const onMouseLeave = (event: MouseEvent) => {
+    clear();
+
+    const param = accessor();
+    if (!param) return;
+
+    let callback: MouseOutCallback | undefined;
+    let delay = 0;
+
+    if (typeof param === 'function') {
+      callback = param;
+    } else if (Array.isArray(param)) {
+      callback = param[0];
+      delay = param[1] ?? 0;
+    } else if (typeof param === 'object') {
+      callback = param.callback ?? param.onMouseOut;
+      delay = param.delay ?? 0;
+    }
+
+    if (!callback) return;
+
+    if (delay > 0) {
+      timer = setTimeout(() => {
+        callback?.(event);
+        timer = undefined;
+      }, delay);
+    } else {
+      callback(event);
+    }
+  };
+
+  el.addEventListener('mouseleave', onMouseLeave as EventListener);
+  el.addEventListener('mouseenter', onMouseEnter as EventListener);
+
+  onCleanup(() => {
+    clear();
+    el.removeEventListener('mouseleave', onMouseLeave as EventListener);
+    el.removeEventListener('mouseenter', onMouseEnter as EventListener);
+  });
+};

package/src/ui/globals/directives/resize.ts

@@ -0,0 +1,33 @@
+import { useFlow } from '../../components/FlowChart.context';
+
+/**
+ * Creates a ResizeObserver hook attached to the node content container element,
+ * dispatching RESIZE events to update node dimensions and edge positioning in
+ * real-time.
+ *
+ * @param id - Unique identifier of the flowchart node.
+ *
+ * @returns Ref callback attaching and cleaning up the observer on unmount.
+ */
+export const resize = (id: string) => (el: HTMLDivElement) => {
+  const service = useFlow();
+
+  const resize = new ResizeObserver(entries => {
+    const entry = entries[0].target;
+    if (!entry) return;
+
+    const width = entry.clientWidth;
+    const height = entry.clientHeight;
+
+    if (width > 0 && height > 0) {
+      service.send({ type: 'RESIZE', payload: { id, size: { width, height } } });
+    }
+  });
+
+  resize.observe(el);
+
+  return () => {
+    resize.unobserve(el);
+    resize.disconnect();
+  };
+};

package/src/ui/globals/helpers/espace.ts

@@ -0,0 +1,26 @@
+import { NON_BREAKABLE_SPACE, VISIBLE_ESPACE } from '../constants';
+
+/**
+ * Returns a zero-width space if string is empty, preserving layout flow.
+ *
+ * @param newText - The input text string.
+ *
+ * @returns The input text or zero-width visible space placeholder.
+ */
+export const espace = (newText: string) => {
+  if (newText === '') {
+    return VISIBLE_ESPACE;
+  }
+  return newText;
+};
+
+/**
+ * Generates a repeated sequence of non-breakable space characters.
+ *
+ * @param count - The number of non-breakable spaces to repeat. Defaults to 1.
+ *
+ * @returns The non-breakable space string sequence.
+ */
+export const repeatSpace = (count = 1) => {
+  return NON_BREAKABLE_SPACE.repeat(count);
+};

package/src/ui/globals/signals/createTyping.ts

@@ -0,0 +1,82 @@
+import { createSignal, onCleanup } from 'solid-js';
+
+import { VISIBLE_ESPACE } from '../constants';
+import { espace } from '../helpers/espace';
+
+/** Typing animation options. */
+type Props = {
+  /** The text content to type out. */
+  content: string;
+  /** Minimum delay interval between keystrokes in milliseconds. */
+  min: number;
+  /** Whether the typing effect rewinds after completion. */
+  rewind?: boolean;
+  /** Delay in milliseconds before rewinding or restarting. */
+  rewindDelay?: number;
+};
+
+/**
+ * Creates a reactive typewriter effect signal with oscillatory typing delay and
+ * optional rewind.
+ *
+ * @param props - Configuration properties of type {@linkcode Props}.
+ *
+ * @returns An object containing the current text signal, type trigger, and text
+ *   setter.
+ */
+export const createTyping = ({ content, min, ...props }: Props) => {
+  const rewind = props.rewind ?? false;
+  const rewindDelay = (props as any).rewindDelay ?? 500;
+
+  const OSCILLATION = Math.min(min / 10 + content.length / 10, 10);
+
+  const [text, setText] = createSignal(VISIBLE_ESPACE);
+  let timeoutId: number | NodeJS.Timeout;
+  let index = 0;
+  let isTyping = true;
+  const max = min + OSCILLATION;
+  let interval = min;
+  let intervalDirection = 1; // 1 for incrementing, -1 for decrementing
+
+  const type = () => {
+    if (isTyping) {
+      if (index < content.length) {
+        setText(prev => prev + content[index]);
+        index++;
+        timeoutId = setTimeout(type, interval);
+      } else if (rewind) {
+        isTyping = false;
+        // interval = min;
+        intervalDirection = 1;
+        timeoutId = setTimeout(type, rewindDelay);
+      }
+    } else {
+      // Rewind mode
+      if (index > 0) {
+        index--;
+        setText(espace(content.substring(0, index)));
+        timeoutId = setTimeout(type, interval);
+      } else {
+        isTyping = true;
+        // interval = min;
+        intervalDirection = 1;
+        timeoutId = setTimeout(type, rewindDelay);
+      }
+    }
+
+    // Update interval with oscillation
+    interval += intervalDirection;
+
+    if (interval >= max) {
+      intervalDirection = -1;
+    } else if (interval <= min) {
+      intervalDirection = 1;
+    }
+  };
+
+  onCleanup(() => {
+    if (timeoutId !== undefined) clearTimeout(timeoutId);
+  });
+
+  return { text, type, setText };
+};

package/src/ui/globals/types.ts

@@ -0,0 +1,83 @@
+import type { Component, ComponentProps, JSX, ValidComponent } from 'solid-js';
+
+/**
+ * Extracts a subset of component props from a valid component.
+ *
+ * @template | {@linkcode ValidComponent} `T` - Target component type.
+ * @template | `keyof ComponentProps<T>` `K` - Prop keys to pick.
+ */
+export type PropsOf<
+  T extends ValidComponent,
+  K extends keyof ComponentProps<T> = never,
+> = Pick<ComponentProps<T>, K>;
+
+/**
+ * Omits a subset of component props from a valid component.
+ *
+ * @template | {@linkcode ValidComponent} `T` - Target component type.
+ * @template | `keyof ComponentProps<T>` `K` - Prop keys to omit.
+ */
+export type OmitPropsOf<
+  T extends ValidComponent,
+  K extends keyof ComponentProps<T> = never,
+> = Omit<ComponentProps<T>, K>;
+
+/**
+ * Creates a component type where specified props are optional.
+ *
+ * @template | {@linkcode ValidComponent} `T` - Target component type.
+ * @template | `keyof ComponentProps<T>` `K` - Prop keys to make optional.
+ */
+export type ReduceComponent<
+  T extends ValidComponent,
+  K extends keyof ComponentProps<T> = never,
+> = Component<OmitPropsOf<T, K> & Partial<PropsOf<T, K>>>;
+
+/**
+ * Short alias for type {@linkcode ReduceComponent}.
+ *
+ * @template | {@linkcode ValidComponent} `T` - Target component type.
+ * @template | `keyof ComponentProps<T>` `K` - Prop keys to make optional.
+ */
+export type RC<
+  T extends ValidComponent,
+  K extends keyof ComponentProps<T> = never,
+> = ReduceComponent<T, K>;
+
+/**
+ * Creates a component type requiring only a picked subset of props.
+ *
+ * @template | {@linkcode ValidComponent} `T` - Target component type.
+ * @template | `keyof ComponentProps<T>` `K` - Picked prop keys.
+ */
+export type PickComponent<
+  T extends ValidComponent,
+  K extends keyof ComponentProps<T> = never,
+> = Component<PropsOf<T, K>>;
+
+/**
+ * Short alias for type {@linkcode PickComponent}.
+ *
+ * @template | {@linkcode ValidComponent} `T` - Target component type.
+ * @template | `keyof ComponentProps<T>` `K` - Picked prop keys.
+ */
+export type PiC<
+  T extends ValidComponent,
+  K extends keyof ComponentProps<T> = never,
+> = PickComponent<T, K>;
+
+/** Type representing an HTML `<link>` tag properties. */
+export type RootLink = JSX.HTMLElementTags['link'];
+
+/**
+ * Type representing an HTML element ref or ref callback.
+ *
+ * @template | {@linkcode HTMLElement} `T` - Target HTML element type.
+ */
+export type Ref<T extends HTMLElement> =
+  | T
+  | ((el: T | undefined) => void)
+  | undefined;
+
+/** Class map dictionary for conditional styling in Solid.js components. */
+export type ClassList = Record<string, boolean | undefined>;

package/src/ui/utils.ts

@@ -0,0 +1,14 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Merges conditional CSS class names using `clsx` and resolves Tailwind CSS class
+ * conflicts with `twMerge`.
+ *
+ * @param inputs - Variable list of class values, objects, or arrays.
+ *
+ * @returns The resolved single class name string.
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}