@cleen/ui 0.1.0

package/src/components/menu/Menu.tsx

@@ -0,0 +1,103 @@
+import { MenuContent } from '@/components/menu/blocks/MenuContent';
+import {
+  cn,
+  useDisclosure,
+  useOutsideClick,
+  usePositionClose,
+} from '@cleen/ui-core';
+import { forwardRef, useRef, type MouseEvent as ReactMouseEvent } from 'react';
+import { createPortal } from 'react-dom';
+import type { MenuProps } from './types/menu';
+
+/**
+ * The `Menu` component displays a list of selectable items, typically used for navigation or actions. It appears when triggered and can be positioned relative to its trigger element, automatically adjusting to fit within the viewport.
+ */
+export const Menu = forwardRef<HTMLDivElement, MenuProps>(function Menu(
+  {
+    items = [],
+    position = 'bottom-left',
+    keepOpenOnClick = true,
+    children,
+    className,
+    classNames,
+    style,
+    styles,
+    ...props
+  },
+  ref
+) {
+  const { isOpen, toggle, close } = useDisclosure();
+
+  const triggerRef = useRef<HTMLDivElement>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  // Calculate optimal position and handle click-outside =w=
+  const { positionStyles, isMounted } = usePositionClose({
+    triggerRef,
+    targetRef: menuRef,
+    position,
+    isOpen,
+  });
+
+  useOutsideClick({
+    refs: [triggerRef, menuRef],
+    handler: close,
+    enabled: isOpen,
+  });
+
+  const handleTriggerClick = (e: ReactMouseEvent) => {
+    e.stopPropagation();
+    toggle();
+  };
+
+  return (
+    <div className={cn('cleen', className)} style={style} ref={ref} {...props}>
+      <div
+        ref={triggerRef}
+        onClick={handleTriggerClick}
+        className={cn(
+          'cleen-size-fit',
+          classNames?.trigger,
+          isOpen && classNames?.triggerOpen
+        )}
+        style={{
+          ...styles?.trigger,
+          ...(isOpen ? styles?.triggerOpen : {}),
+        }}
+      >
+        {children}
+      </div>
+
+      {isOpen &&
+        createPortal(
+          <div className="cleen">
+            <div
+              ref={menuRef}
+              className={cn(
+                'cleen-bg-background cleen-shadow-lg cleen-border cleen-border-gray/20 cleen-rounded-lg cleen-w-52',
+                'cleen-absolute cleen-z-50',
+                {
+                  'cleen-opacity-0': !isMounted,
+                },
+                classNames?.menu
+              )}
+              style={{
+                top: `${positionStyles.top}px`,
+                left: `${positionStyles.left}px`,
+                ...styles?.menu,
+              }}
+            >
+              <MenuContent
+                items={items}
+                keepOpenOnClick={keepOpenOnClick}
+                hideMenu={close}
+                classNames={classNames}
+                styles={styles}
+              />
+            </div>
+          </div>,
+          document.body
+        )}
+    </div>
+  );
+});

package/src/components/menu/blocks/MenuContent.tsx

@@ -0,0 +1,105 @@
+import { IconChevronLeft } from '@/components/cleenIcon';
+import { MenuItem } from '@/components/menu/blocks/MenuItem';
+import type { MenuProps, MenuStack } from '@/components/menu/types/menu';
+import type {
+  IMenuItem,
+  MenuItemButton,
+} from '@/components/menu/types/menuItem';
+import { cn } from '@cleen/ui-core';
+import { useEffect, useState } from 'react';
+
+interface MenuContentProps {
+  items: IMenuItem[];
+  keepOpenOnClick?: boolean;
+  hideMenu: () => void;
+  classNames: MenuProps['classNames'];
+  styles: MenuProps['styles'];
+}
+
+export const MenuContent = ({
+  items,
+  keepOpenOnClick,
+  hideMenu,
+  classNames,
+  styles,
+}: MenuContentProps) => {
+  const [menuStack, setMenuStack] = useState<MenuStack[]>([]);
+  const [activeItems, setActiveItems] = useState<IMenuItem[]>(items);
+
+  const enterSubmenu = (submenu: IMenuItem[], title?: React.ReactNode) => {
+    setMenuStack(stack => [...stack, { items: activeItems, title }]);
+    setActiveItems(submenu);
+  };
+
+  const goBack = () => {
+    const previous = menuStack[menuStack?.length - 1];
+    if (!previous) return;
+
+    setActiveItems(previous?.items);
+    setMenuStack(stack => stack?.slice(0, -1));
+  };
+
+  useEffect(() => {
+    setActiveItems(items);
+    setMenuStack([]);
+  }, [items]);
+
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape') return;
+
+      if (menuStack.length > 0) {
+        const previous = menuStack?.[menuStack?.length - 1];
+
+        setActiveItems(previous?.items);
+        setMenuStack(stack => stack?.slice(0, -1));
+      } else {
+        hideMenu();
+      }
+    };
+
+    document.addEventListener('keydown', handleEscape);
+
+    return () => {
+      document.removeEventListener('keydown', handleEscape);
+    };
+  }, [hideMenu, menuStack]);
+
+  const handleItemClick = (item: MenuItemButton) => {
+    item?.onClick?.();
+
+    if (!keepOpenOnClick) {
+      hideMenu();
+    }
+  };
+
+  return (
+    <>
+      {menuStack?.length > 0 && (
+        <button
+          onClick={goBack}
+          className={cn(
+            'cleen-flex cleen-items-center cleen-gap-3 cleen-px-4 cleen-py-2 cleen-w-full cleen-text-sm cleen-text-gray hover:cleen-bg-gray/5',
+            classNames?.submenuButton
+          )}
+          style={styles?.submenuButton}
+        >
+          <IconChevronLeft className="cleen-size-4 cleen-text-gray/30" />
+          {menuStack?.[menuStack?.length - 1]?.title}
+        </button>
+      )}
+
+      {activeItems?.map((item, idx, arr) => (
+        <MenuItem
+          key={item?.id || idx}
+          item={item}
+          isLast={idx === arr?.length - 1}
+          handleClick={handleItemClick}
+          onEnterSubmenu={enterSubmenu}
+          classNames={classNames?.item}
+          styles={styles?.item}
+        />
+      ))}
+    </>
+  );
+};

package/src/components/menu/blocks/MenuItem.tsx

@@ -0,0 +1,120 @@
+import { IconChevronRight } from '@/components/cleenIcon';
+import { cn } from '@cleen/ui-core';
+import { Link } from 'react-router-dom';
+import type {
+  MenuItemButton,
+  MenuItemLink,
+  MenuItemProps,
+} from '../types/menuItem';
+
+const getWrapperProps = ({
+  item,
+  classNames,
+  styles,
+}: {
+  item: MenuItemButton | MenuItemLink;
+  handleClick?: MenuItemProps['handleClick'];
+  classNames?: MenuItemProps['classNames'];
+  styles?: MenuItemProps['styles'];
+}) => ({
+  disabled: item?.disabled,
+  className: cn(
+    'cleen-flex cleen-items-center cleen-gap-3 cleen-px-4 cleen-py-2 cleen-w-full cleen-text-gray cleen-text-sm cleen-text-left cleen-transition-colors',
+    item?.disabled
+      ? 'cleen-opacity-50 cleen-select-none cleen-cursor-not-allowed'
+      : 'hover:cleen-bg-gray/5 cleen-cursor-pointer',
+    {
+      'cleen-text-error hover:cleen-bg-error/10': item?.danger,
+    },
+    classNames?.container
+  ),
+  style: styles?.container,
+  children: (
+    <>
+      {item?.icon}
+
+      <span
+        className={cn('cleen-flex-1', classNames?.label)}
+        style={styles?.label}
+      >
+        {item?.label}
+      </span>
+    </>
+  ),
+  ...(item?.type === 'button' ? { type: 'button' as const } : { to: item?.to }),
+});
+
+export const MenuItem = ({
+  item,
+  isLast,
+  handleClick,
+  onEnterSubmenu,
+  classNames,
+  styles,
+}: MenuItemProps) => {
+  switch (item?.type) {
+    case 'group':
+      return (
+        <>
+          {item?.label && (
+            <p
+              className={cn(
+                'cleen-px-4 cleen-py-2 cleen-font-bold cleen-text-gray/60 cleen-text-xs',
+                classNames?.groupLabel
+              )}
+              style={styles?.groupDivider}
+            >
+              {item?.label}
+            </p>
+          )}
+
+          {item?.items?.map((i, idx, arr) => (
+            <MenuItem
+              key={i?.id || idx}
+              item={i}
+              handleClick={handleClick}
+              onEnterSubmenu={onEnterSubmenu}
+              isLast={idx === arr.length - 1}
+            />
+          ))}
+
+          {!isLast && (
+            <hr
+              className={cn('cleen-text-gray/20', classNames?.groupDivider)}
+              style={styles?.groupDivider}
+            />
+          )}
+        </>
+      );
+
+    case 'button': {
+      const hasSubmenu = item?.submenu && item?.submenu?.length > 0;
+
+      return (
+        <button
+          type="button"
+          onClick={() => {
+            if (hasSubmenu) {
+              onEnterSubmenu?.(item.submenu!, item?.label);
+            } else {
+              handleClick?.(item);
+            }
+          }}
+          {...getWrapperProps({ item, classNames, styles })}
+        >
+          {item?.icon}
+          <span className="cleen-flex-1">{item?.label}</span>
+          {hasSubmenu && (
+            <IconChevronRight className="cleen-size-4 cleen-text-gray/50" />
+          )}
+        </button>
+      );
+    }
+
+    case 'link':
+      return <Link to="" {...getWrapperProps({ item, classNames, styles })} />;
+
+    default:
+      return null;
+  }
+};

package/src/components/menu/index.ts

@@ -0,0 +1,2 @@
+export { Menu } from './Menu';
+export type { MenuProps } from './types/menu';

package/src/components/menu/types/menu.ts

@@ -0,0 +1,30 @@
+import type { Position } from '@cleen/ui-core';
+import type { ComponentProps, CSSProperties } from 'react';
+import type { IMenuItem, MenuItemProps } from './menuItem';
+
+export type MenuProps = ComponentProps<'div'> & {
+  items?: IMenuItem[];
+  position?: Position;
+  keepOpenOnClick?: boolean;
+  classNames?: {
+    container?: string;
+    trigger?: string;
+    triggerOpen?: string;
+    menu?: string;
+    item?: MenuItemProps['classNames'];
+    submenuButton?: string;
+  };
+  styles?: {
+    container?: CSSProperties;
+    trigger?: CSSProperties;
+    triggerOpen?: CSSProperties;
+    menu?: CSSProperties;
+    item?: MenuItemProps['styles'];
+    submenuButton?: CSSProperties;
+  };
+};
+
+export interface MenuStack {
+  items: IMenuItem[];
+  title?: React.ReactNode;
+}

package/src/components/menu/types/menuItem.ts

@@ -0,0 +1,48 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+export interface MenuItemProps {
+  item: IMenuItem;
+  isLast?: boolean;
+  handleClick?: (item: MenuItemButton) => void;
+  onEnterSubmenu?: (items: IMenuItem[], title?: React.ReactNode) => void;
+  classNames?: {
+    container?: string;
+    label?: string;
+    groupLabel?: string;
+    groupDivider?: string;
+  };
+  styles?: {
+    container?: CSSProperties;
+    label?: CSSProperties;
+    groupLabel?: CSSProperties;
+    groupDivider?: CSSProperties;
+  };
+}
+
+export type IMenuItem = MenuItemButton | MenuItemLink | MenuItemGroup;
+
+interface MenuItemSharedProps {
+  id?: string;
+  disabled?: boolean;
+  danger?: boolean;
+  icon?: ReactNode;
+  label?: ReactNode;
+}
+
+export interface MenuItemButton extends MenuItemSharedProps {
+  type: 'button';
+  onClick?: () => void;
+  submenu?: IMenuItem[];
+}
+
+export interface MenuItemLink extends MenuItemSharedProps {
+  type: 'link';
+  to: string;
+}
+
+export interface MenuItemGroup {
+  id?: string;
+  type: 'group';
+  label?: ReactNode;
+  items: IMenuItem[];
+}

package/src/components/modal/Modal.tsx

@@ -0,0 +1,191 @@
+import { Button } from '@/components/button';
+import { Card } from '@/components/card';
+import type { CardProps } from '@/components/card/Card';
+import { IconX } from '@/components/cleenIcon';
+import {
+  cn,
+  type ComponentClassnames,
+  type ComponentStyles,
+} from '@cleen/ui-core';
+import {
+  forwardRef,
+  useEffect,
+  useRef,
+  useState,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+const SIZES = {
+  xs: 320,
+  sm: 384,
+  md: 448,
+  lg: 512,
+  xl: 576,
+  '2xl': 728,
+};
+
+const TRANSITION_DURATION = 300;
+
+export type ModalProps = ComponentProps<'div'> & {
+  isOpen?: boolean;
+  onClose?: () => void;
+  closeOnOverlayClick?: boolean;
+  closeButtonIcon?: ReactNode | null;
+  zIndex?: number;
+  size?: keyof typeof SIZES | number;
+  header?: CardProps['header'];
+  footer?: CardProps['header'];
+  color?: string;
+  p?: number;
+  gap?: number;
+  classNames?: {
+    overlay?: string;
+    container?: string;
+    modal?: ComponentClassnames<CardProps>;
+  };
+  styles?: {
+    overlay?: CSSProperties;
+    container?: CSSProperties;
+    modal?: ComponentStyles<CardProps>;
+  };
+};
+
+/**
+ * Modal component that displays content in a centered modal dialog.
+ *
+ * - Controlled via `isOpen` (boolean) and `onClose` (callback).
+ * - Renders a clickable overlay/backdrop that closes the modal when clicked.
+ * - Modal content is centered on the screen with smooth fade-in/fade-out animations.
+ * - Accepts `classNames` and `styles` objects to customize classes and inline styles for:
+ *   `overlay` and `container`.
+ */
+export const Modal = forwardRef<HTMLDivElement, ModalProps>(function Modal(
+  {
+    isOpen = false,
+    onClose,
+    closeOnOverlayClick = true,
+    closeButtonIcon = <IconX className="cleen-size-5" />,
+    header,
+    footer,
+    zIndex = 50,
+    size = 'md',
+    color,
+    p,
+    gap,
+    className,
+    classNames,
+    style,
+    styles,
+    children,
+    ...props
+  },
+  ref
+) {
+  const [isVisible, setIsVisible] = useState(isOpen);
+  const [shouldRender, setShouldRender] = useState(isOpen);
+  const internalRef = useRef<HTMLDivElement>(null);
+
+  const closeModal = () => {
+    setIsVisible(false);
+    setTimeout(() => onClose?.(), TRANSITION_DURATION);
+  };
+
+  useEffect(() => {
+    if (isOpen) {
+      setShouldRender(true);
+      const timer = setTimeout(() => setIsVisible(true), 1);
+      return () => clearTimeout(timer);
+    } else {
+      setIsVisible(false);
+      const timer = setTimeout(
+        () => setShouldRender(false),
+        TRANSITION_DURATION
+      );
+      return () => clearTimeout(timer);
+    }
+  }, [isOpen]);
+
+  if (!shouldRender) {
+    return null;
+  }
+
+  return createPortal(
+    <div className={cn('cleen', className)} style={style} ref={ref} {...props}>
+      {/* Overlay */}
+      <div
+        className={cn(
+          'cleen-fixed cleen-inset-0 cleen-bg-black/50 dark:cleen-bg-white/50 cleen-transition-opacity cleen-duration-300 cleen-ease-in-out',
+          isVisible ? 'cleen-opacity-100' : 'cleen-opacity-0',
+          classNames?.overlay
+        )}
+        style={{
+          zIndex,
+          ...styles?.overlay,
+        }}
+        onClick={() => {
+          if (closeOnOverlayClick) {
+            closeModal();
+          }
+        }}
+        aria-hidden="true"
+      />
+
+      {/* Modal Container */}
+      <div
+        className={cn(
+          'cleen-fixed cleen-inset-0 cleen-flex cleen-justify-center cleen-items-center cleen-p-4 cleen-overflow-auto',
+          'cleen-transition-all cleen-duration-300 cleen-ease-in-out',
+          'cleen-pointer-events-none',
+          isVisible
+            ? 'cleen-opacity-100 cleen-scale-100'
+            : 'cleen-opacity-0 cleen-scale-95',
+          classNames?.container
+        )}
+        style={{ zIndex, ...styles?.container }}
+        aria-modal="true"
+        role="dialog"
+      >
+        <Card
+          header={header}
+          footer={footer}
+          color={color}
+          p={p}
+          gap={gap}
+          className={cn(
+            'cleen-relative cleen-shadow-xl cleen-w-full cleen-max-w-lg cleen-max-h-[90vh] cleen-rounded-lg',
+            'cleen-pointer-events-auto',
+            classNames?.modal?.className
+          )}
+          style={{
+            maxWidth: typeof size === 'number' ? size : SIZES[size],
+            ...styles?.modal?.style,
+          }}
+          classNames={classNames?.modal?.classNames}
+          styles={styles?.modal?.styles}
+          ref={internalRef}
+        >
+          {children}
+
+          {closeButtonIcon && (
+            <div className={cn('cleen-top-3 cleen-right-3 cleen-absolute')}>
+              <Button
+                variant="borderless"
+                onClick={closeModal}
+                aria-label="Close modal"
+                classNames={{
+                  container: 'cleen-p-1.5 cleen-rounded-full',
+                }}
+              >
+                {closeButtonIcon}
+              </Button>
+            </div>
+          )}
+        </Card>
+      </div>
+    </div>,
+    document.body
+  );
+});

package/src/components/modal/index.ts

@@ -0,0 +1 @@
+export { Modal, type ModalProps } from './Modal';

package/src/components/notification/Notification.tsx

@@ -0,0 +1,79 @@
+import { NOTIFICATION_VARIANT_CONFIG } from '@/components/notification/constant/notification';
+import { cn } from '@cleen/ui-core';
+import type { ReactNode } from 'react';
+import {
+  Bounce,
+  Flip,
+  toast as notification,
+  Slide,
+  Zoom,
+  type ToastOptions as NotificationOptions,
+} from 'react-toastify';
+
+export type NotificationVariant =
+  | 'success'
+  | 'error'
+  | 'info'
+  | 'warning'
+  | 'default';
+
+export interface NotificationProps extends Omit<
+  NotificationOptions,
+  'type' | 'transition'
+> {
+  message: ReactNode;
+  variant?: NotificationVariant;
+  animationType?: 'bounce' | 'zoom' | 'slide' | 'flip';
+}
+
+/**
+ * The `Notification` component provides a way to display brief notifications to users.
+ * It uses react-toastify library for toast notifications.
+ */
+export const showNotification = ({
+  message,
+  variant = 'default',
+  animationType = 'slide',
+  className,
+  ...options
+}: NotificationProps) => {
+  const getAnimationType = () => {
+    switch (animationType) {
+      case 'bounce':
+        return Bounce;
+
+      case 'flip':
+        return Flip;
+
+      case 'zoom':
+        return Zoom;
+
+      case 'slide':
+      default:
+        return Slide;
+    }
+  };
+
+  const notificationOptions: NotificationOptions = {
+    ...NOTIFICATION_VARIANT_CONFIG.default,
+    ...(variant !== 'default' && NOTIFICATION_VARIANT_CONFIG[variant]),
+    transition: getAnimationType(),
+    className: cn('cleen-text-sm', className),
+    ...options,
+  };
+
+  switch (variant) {
+    case 'success':
+      return notification.success(message, notificationOptions);
+    case 'error':
+      return notification.error(message, notificationOptions);
+    case 'info':
+      return notification.info(message, notificationOptions);
+    case 'warning':
+      return notification.warning(message, notificationOptions);
+
+    case 'default':
+    default:
+      return notification(message, notificationOptions);
+  }
+};