@bemedev/mind-flow 0.3.1 → 1.0.0

package/src/ui/components/Panels.tsx

@@ -0,0 +1,40 @@
+import { Show, type Component } from 'solid-js';
+
+import type { FlowPanels } from './FlowChart.types';
+
+/**
+ * Overlay container rendering custom panel slots positioned around the flowchart
+ * canvas.
+ *
+ * @param props - Flow panels layout properties of type {@linkcode FlowPanels}.
+ *
+ * @returns Rendered overlay panels JSX elements.
+ */
+export const Panels: Component<FlowPanels> = props => {
+  return (
+    <>
+      <Show when={props.topLeft} keyed>
+        {Panel => {
+          const Component = typeof Panel === 'function' ? <Panel /> : Panel;
+          return <div class='absolute top-4 left-4 z-50'>{Component}</div>;
+        }}
+      </Show>
+
+      {/* Top-Right Panel */}
+      <Show when={props.topRight} keyed>
+        {Panel => {
+          const Component = typeof Panel === 'function' ? <Panel /> : Panel;
+          return <div class='absolute top-4 right-4 z-50'>{Component}</div>;
+        }}
+      </Show>
+
+      {/* Bottom-Left Panel */}
+      <Show when={props.bottomLeft} keyed>
+        {Panel => {
+          const Component = typeof Panel === 'function' ? <Panel /> : Panel;
+          return <div class='absolute bottom-4 left-4 z-50'>{Component}</div>;
+        }}
+      </Show>
+    </>
+  );
+};

package/src/ui/globals/components/atoms/TypingText.tsx

@@ -0,0 +1,63 @@
+import {
+  createEffect,
+  createMemo,
+  on,
+  type Accessor,
+  type Component,
+} from 'solid-js';
+
+import { VISIBLE_ESPACE } from '../../constants';
+import { createTyping } from '../../signals/createTyping';
+
+/** Base configuration properties for {@linkcode TypingText}. */
+type BaseProps = {
+  /** The text string to animate typing out. */
+  children: string;
+  /** Optional container CSS class name. */
+  class?: string;
+  /** Keystroke interval delay in milliseconds. Defaults to 62. */
+  interval?: number;
+  /** Optional boolean accessor to disable typing and display text immediately. */
+  disabled?: Accessor<boolean>;
+};
+
+/** Props for the {@linkcode TypingText} component with optional rewind configuration. */
+type Props = BaseProps &
+  ({ rewind: true; rewindDelay: number } | { rewind?: false });
+
+/**
+ * Renders animated text with a typewriter keystroke animation effect.
+ *
+ * @param props - Component configuration properties of type {@linkcode Props}.
+ *
+ * @returns Rendered animated typing text JSX container.
+ */
+export const TypingText: Component<Props> = props => {
+  // #region Default values
+  const min = props.interval ?? 62;
+  const rewind = props.rewind ?? false;
+  const rewindDelay = (props as any).rewindDelay ?? 500;
+  const content = props.children;
+  const disabled = createMemo(
+    () => (props.disabled ? props.disabled() : false),
+    false,
+  );
+  // #endregion
+
+  const { text, type, setText } = createTyping({
+    content,
+    min,
+    rewind,
+    rewindDelay,
+  });
+
+  createEffect(on(disabled, () => setText(VISIBLE_ESPACE)));
+
+  createEffect(() => {
+    // If disabled, show full text immediately
+    if (disabled()) setText(content);
+    else type();
+  });
+
+  return <div class={props.class}>{text()}</div>;
+};

package/src/ui/globals/components/molecules/FadingDots.tsx

@@ -0,0 +1,45 @@
+import { splitProps, type Component, JSX } from 'solid-js';
+
+import { cn } from '../../../utils';
+import type { OmitPropsOf } from '../../types';
+
+/**
+ * Loading animation component displaying animated pulsing dots.
+ *
+ * @param props - Fading dots configuration properties.
+ * @param props.count - The number of dots to display.
+ * @param props.duration - Animation duration in milliseconds. Defaults to 500.
+ * @param props.innerProps - Additional properties and CSS styles applied to dot
+ *   elements.
+ *
+ * @returns Rendered animated dots container JSX element.
+ */
+export const FadingDots: Component<{
+  count: number;
+  duration?: number;
+  innerProps?: OmitPropsOf<'span', 'children' | 'style'> & {
+    style?: JSX.CSSProperties;
+  };
+}> = ({ count: length, innerProps = {}, duration = 500 }) => {
+  const [local, rest] = splitProps(innerProps, ['class', 'style']);
+
+  return (
+    <div class='mt-4 flex items-center justify-center space-x-4'>
+      {Array.from({ length }, (_, i) => (
+        <span
+          class={cn(
+            'rounded-full animate-out direction-alternate repeat-infinite fade-out-5 size-4  bg-gray-600',
+            local.class,
+          )}
+          style={{
+            ...local.style,
+            'animation-duration': `${duration}ms`,
+            'animation-delay': `${duration / i}ms`,
+          }}
+          aria-hidden='true'
+          {...rest}
+        />
+      ))}
+    </div>
+  );
+};

package/src/ui/globals/components/organisms/LoadingFallback.tsx

@@ -0,0 +1,116 @@
+import type { Component } from 'solid-js';
+
+import { cn } from '../../../utils';
+import { TypingText } from '../atoms/TypingText';
+import { FadingDots } from '../molecules/FadingDots';
+
+/** Properties for the {@linkcode LoadingFallback} component. */
+interface LoadingFallbackProps {
+  /**
+   * Text message to display alongside the loading animation.
+   *
+   * @default 'Chargement en cours...'
+   */
+  message?: string;
+  /** Additional CSS class names. */
+  class?: string;
+  /**
+   * Spinner dimension sizing.
+   *
+   * @default 'lg'
+   */
+  size?: 'sm' | 'md' | 'lg' | 'xl';
+  /** Keystroke typing interval in milliseconds. Defaults to 80. */
+  interval?: number;
+  /** Whether the typing text animation rewinds upon completion. Defaults to true. */
+  rewind?: boolean;
+  /**
+   * Delay in milliseconds before rewinding or restarting typing animation. Defaults
+   * to 2000.
+   */
+  rewindDelay?: number;
+}
+
+/**
+ * Fallback loading screen component displaying an animated spinner and typewriter
+ * text.
+ *
+ * @example
+ *   ```tsx
+ *   <Show when={data()} fallback={<LoadingFallback />}>
+ *     <DataComponent data={data()!} />
+ *   </Show>;
+ *   ```;
+ *
+ * @param props - Loading fallback properties of type
+ *   {@linkcode LoadingFallbackProps}.
+ *
+ * @returns Rendered full-screen loading fallback JSX element.
+ */
+export const LoadingFallback: Component<LoadingFallbackProps> = props => {
+  const message = props.message ?? 'Chargement en cours...';
+
+  const spinnerSizes = {
+    sm: 'w-8 h-8',
+    md: 'w-12 h-12',
+    lg: 'w-16 h-16',
+    xl: 'w-24 h-24',
+  };
+
+  const size = props.size ?? 'lg';
+
+  return (
+    <div
+      class={cn(
+        'flex flex-col items-center justify-center gap-6',
+        'h-screen w-screen overflow-hidden p-4',
+        props.class,
+      )}
+      role='status'
+      aria-live='polite'
+      aria-label='Chargement en cours'
+    >
+      {/* Spinner animé */}
+      <div class='relative'>
+        {/* Cercle extérieur avec rotation */}
+        <div
+          class={cn(
+            spinnerSizes[size],
+            'rounded-full border-4 border-[#4B9CAD]/20',
+            'animate-spin',
+            'border-t-[#4B9CAD]',
+          )}
+          aria-hidden='true'
+        />
+
+        {/* Cercle intérieur pour effet de profondeur */}
+        <div
+          class={cn(
+            'absolute inset-2',
+            'rounded-full border-4 border-transparent',
+            'border-b-[#4B9CAD]/40',
+            'animate-spin',
+            'animation-duration-[1.5s]',
+            'direction-[reverse]',
+          )}
+          aria-hidden='true'
+        />
+      </div>
+
+      {/* Texte avec effet typing */}
+      <div class='text-center' aria-label={message}>
+        <TypingText
+          class='text-lg font-medium text-gray-700 md:text-xl dark:text-gray-300'
+          interval={props.interval ?? 80}
+          rewind={props.rewind ?? true}
+          rewindDelay={props.rewindDelay ?? 2000}
+        >
+          {message}
+        </TypingText>
+
+        {/* Points d'animation pour indiquer le chargement */}
+        <FadingDots count={5} innerProps={{ class: 'bg-[#3d8091]' }} />
+      </div>
+    </div>
+  );
+};

package/src/ui/globals/constants/index.ts

@@ -0,0 +1,2 @@
+export * from './strings';
+export * from './links';

package/src/ui/globals/constants/links.ts

@@ -0,0 +1,15 @@
+import type { RootLink } from '../types';
+
+/** Preconnect and stylesheet link descriptors for Google Fonts. */
+export const GOOGLE_FONTS_LINKS: RootLink[] = [
+  { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: 'anonymous' },
+  {
+    rel: 'preconnect',
+    href: 'https://fonts.googleapis.com',
+    crossorigin: 'anonymous',
+  },
+  {
+    rel: 'preconnect',
+    href: 'https://fonts.googleapis.com/css2?family=Montserrat:wght@300;400;500;600;700;800&family=Open+Sans:wght@300;400;500;600;700;800&family=Poppins:wght@300;400;500;600;700;800&family=Roboto:wght@300;400;500;700;900&family=Lora:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap',
+  },
+];

package/src/ui/globals/constants/strings.ts

@@ -0,0 +1,5 @@
+/** Zero-width space character used for layout preservation in typing animations. */
+export const VISIBLE_ESPACE = '\u200B';
+
+/** Non-breakable space character string. */
+export const NON_BREAKABLE_SPACE = '\xa0';

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

@@ -0,0 +1,18 @@
+import { onCleanup } from 'solid-js';
+
+/**
+ * Solid custom directive that triggers a callback when a click occurs outside the
+ * bound element.
+ *
+ * @param el - The bound DOM element.
+ * @param accessor - Accessor returning the callback function to execute.
+ */
+export const clickOutside = (el: any, accessor: any) => {
+  const onClick = (e: any) => {
+    if (!el.contains(e.target)) {
+      accessor()?.();
+    }
+  };
+  document.body.addEventListener('click', onClick);
+  onCleanup(() => document.body.removeEventListener('click', onClick));
+};

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

@@ -0,0 +1,16 @@
+import type { MouseOutParam } from './mouseOut';
+
+export * from './clickOutside';
+export * from './mouseOut';
+export * from './resize';
+
+declare module 'solid-js' {
+  // oxlint-disable-next-line typescript/no-namespace
+  namespace JSX {
+    interface Directives {
+      clickOutside: () => void;
+      mouseOut: MouseOutParam;
+      draggable: { skipTransform?: boolean };
+    }
+  }
+}

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 };
+};