@cleen/ui 0.1.0

package/src/components/pillBadge/PillBadge.tsx

@@ -0,0 +1,130 @@
+import { IconX } from '@/components/cleenIcon';
+import { cn, ColorHelpers, type HintedString } from '@cleen/ui-core';
+import {
+  useMemo,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { getColor } from './helper';
+import { dotVariants, roundVariants, variants, type Color } from './variants';
+
+export type PillBadgeProps = Omit<ComponentProps<'span'>, 'color'> & {
+  color?: HintedString<Color>;
+  colorByIndex?: number;
+  variant?: keyof typeof roundVariants;
+  label?: ReactNode;
+  showDot?: boolean;
+  icon?: ReactNode;
+  removeable?: boolean;
+  withBorder?: boolean;
+  classNames?: { container?: string; dot?: string; removable?: string };
+  styles?: {
+    container?: CSSProperties;
+    dot?: CSSProperties;
+    removable?: CSSProperties;
+  };
+  onRemoveClicked?: () => void;
+};
+
+/**
+ * Compact badge/chip used to display labels, statuses, tags, and counts.
+ *
+ * - Pick from preset `color` values or pass any CSS color string for custom tinting.
+ * - Use `colorByIndex` to deterministically cycle through the color palette by a numeric index.
+ * - Set `variant` to control roundness (`rounded`, `square`, `pill`).
+ * - Enable `showDot` for a colored status dot, `removeable` for an \`×\` remove button.
+ * - Accepts `classNames` and `styles` for keys: `container`, `dot`, `removable`.
+ */
+export const PillBadge = ({
+  className,
+  classNames,
+  style,
+  styles,
+  label,
+  color = 'primary',
+  variant = 'rounded',
+  showDot = false,
+  icon,
+  removeable = false,
+  withBorder = true,
+  onRemoveClicked,
+  onClick,
+  colorByIndex,
+  children,
+  ...props
+}: PillBadgeProps) => {
+  const { variantClass, dotVariantClass, dotVariantStyle, variantStyle } =
+    useMemo(() => {
+      const styles: {
+        variantClass?: string;
+        variantStyle?: CSSProperties;
+        dotVariantClass?: string;
+        dotVariantStyle?: CSSProperties;
+      } = {};
+
+      if (color in variants) {
+        styles.variantClass = variants[getColor(color as Color, colorByIndex)];
+        styles.dotVariantClass =
+          dotVariants[getColor(color as Color, colorByIndex)];
+      } else {
+        styles.variantStyle = {
+          borderColor: ColorHelpers.trasparentize(color, 0.8),
+          backgroundColor: ColorHelpers.trasparentize(color, 0.95),
+          color,
+        };
+        styles.dotVariantStyle = {
+          backgroundColor: ColorHelpers.trasparentize(color, 0.5),
+        };
+      }
+
+      return styles;
+    }, [color, colorByIndex]);
+
+  return (
+    <div className={cn('cleen', className)} style={style}>
+      <span
+        className={cn(
+          'cleen-flex cleen-justify-center cleen-items-center cleen-gap-1 cleen-text-xs cleen-font-medium cleen-py-0.5 cleen-px-2 cleen-w-fit cleen-min-w-max cleen-transition-all cleen-duration-200',
+          variantClass,
+          roundVariants[variant],
+          { 'cleen-border': withBorder },
+          {
+            'hover:cleen-opacity-80 cleen-cursor-pointer':
+              onClick || removeable,
+          },
+          classNames?.container
+        )}
+        style={{
+          ...variantStyle,
+          ...styles?.container,
+        }}
+        onClick={onClick}
+        {...props}
+      >
+        {showDot && (
+          <span
+            className={cn(
+              'cleen-size-2 cleen-rounded-[50%]',
+              dotVariantClass,
+              classNames?.dot
+            )}
+            style={{ ...dotVariantStyle, ...styles?.dot }}
+          />
+        )}
+        {icon}
+        {label ?? children}
+        {removeable && (
+          <IconX
+            className={cn(
+              'cleen-cursor-pointer cleen-flex cleen-flex-col cleen-justify-center cleen-items-center cleen-transition-transform cleen-duration-200 hover:cleen-scale-125',
+              classNames?.removable
+            )}
+            style={styles?.removable}
+            onClick={onRemoveClicked}
+          />
+        )}
+      </span>
+    </div>
+  );
+};

package/src/components/pillBadge/helper.ts

@@ -0,0 +1,11 @@
+import { colorList, type Color } from './variants';
+
+export const getColor = (color?: Color, colorByIndex?: number): Color => {
+  if (!color && !colorByIndex) {
+    return 'primary';
+  }
+
+  return colorByIndex
+    ? colorList[colorByIndex % colorList.length]
+    : (color as Color);
+};

package/src/components/pillBadge/index.ts

@@ -0,0 +1 @@
+export { PillBadge, type PillBadgeProps } from './PillBadge';

package/src/components/pillBadge/variants.ts

@@ -0,0 +1,47 @@
+export const colorList = [
+  'blue',
+  'lighter-blue',
+  'primary',
+  'indigo',
+  'green',
+  'red',
+  'purple',
+  'pink',
+  'orange',
+  'gray',
+] as const;
+
+export type Color = (typeof colorList)[number];
+
+export const variants: Record<Color, string> = {
+  blue: 'cleen-border-primary/30 cleen-bg-primary/10 cleen-text-primary',
+  'lighter-blue':
+    'cleen-border-primary/20 cleen-bg-primary/5 cleen-text-primary',
+  primary: 'cleen-border-brand cleen-bg-brand cleen-text-white',
+  indigo: 'cleen-border-indigo/50 cleen-bg-indigo/5 cleen-text-indigo/80',
+  green: 'cleen-border-success/20 cleen-bg-success/5 cleen-text-success',
+  red: 'cleen-border-error/20 cleen-bg-error/5 cleen-text-error',
+  purple: 'cleen-border-purple/20 cleen-bg-purple/5 cleen-text-purple/80',
+  pink: 'cleen-border-pink/50 cleen-bg-pink/5 cleen-text-pink/80',
+  orange: 'cleen-border-warning/20 cleen-bg-warning/5 cleen-text-warning',
+  gray: 'cleen-border-gray/10 cleen-bg-gray/5 cleen-text-gray/80',
+};
+
+export const dotVariants: Partial<Record<Color, string>> = {
+  blue: 'cleen-bg-primary/50',
+  primary: 'cleen-bg-primary/50',
+  indigo: 'cleen-bg-indigo/50',
+  green: 'cleen-bg-success/50',
+  red: 'cleen-bg-error/50',
+  purple: 'cleen-bg-purple/50',
+  pink: 'cleen-bg-pink/50',
+  orange: 'cleen-bg-warning/50',
+  gray: 'cleen-bg-gray/50',
+};
+
+export const roundVariants = {
+  full: 'cleen-rounded-full',
+  rounded: 'cleen-rounded-2xl',
+  semiRounded: 'cleen-rounded-lg',
+  sleek: 'cleen-rounded',
+};

package/src/components/popover/Popover.tsx

@@ -0,0 +1,108 @@
+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 { PopoverProps } from './types/popover';
+
+/**
+ * A Popover component that displays a floating menu when the trigger element is clicked. The menu is positioned relative to the trigger based on the specified `position` prop. The component handles click outside to close the menu and calculates optimal positioning to ensure it stays within the viewport.
+ */
+export const Popover = forwardRef<HTMLDivElement, PopoverProps>(
+  function Popover(
+    {
+      isOpen: isOpenProp,
+      onOpenChange,
+      content,
+      position = 'bottom-left',
+      children,
+      className,
+      classNames,
+      style,
+      styles,
+      ...props
+    },
+    ref
+  ) {
+    const { isOpen, toggle, close } = useDisclosure({
+      value: isOpenProp,
+      setValue: onOpenChange,
+    });
+
+    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?.popover
+                )}
+                style={{
+                  top: `${positionStyles.top}px`,
+                  left: `${positionStyles.left}px`,
+                  ...styles?.popover,
+                }}
+                onClick={e => e.stopPropagation()}
+              >
+                {content}
+              </div>
+            </div>,
+            document.body
+          )}
+      </div>
+    );
+  }
+);

package/src/components/popover/index.ts

@@ -0,0 +1,2 @@
+export { Popover } from './Popover';
+export type { PopoverProps } from './types/popover';

package/src/components/popover/types/popover.ts

@@ -0,0 +1,21 @@
+import type { Position } from '@cleen/ui-core';
+import type { ComponentProps, CSSProperties, ReactNode } from 'react';
+
+export type PopoverProps = Omit<ComponentProps<'div'>, 'content'> & {
+  isOpen?: boolean;
+  onOpenChange?: (isOpen: boolean) => void;
+  content?: ReactNode;
+  position?: Position;
+  classNames?: {
+    container?: string;
+    trigger?: string;
+    triggerOpen?: string;
+    popover?: string;
+  };
+  styles?: {
+    container?: CSSProperties;
+    trigger?: CSSProperties;
+    triggerOpen?: CSSProperties;
+    popover?: CSSProperties;
+  };
+};

package/src/components/progressBar/ProgressBar.tsx

@@ -0,0 +1,179 @@
+import { cn, useAnimateNumber } from '@cleen/ui-core';
+import type { ComponentProps, CSSProperties, ForwardedRef } from 'react';
+import { forwardRef, useEffect, useMemo, useRef, useState } from 'react';
+
+export interface ProgressBarProps extends ComponentProps<'div'> {
+  percentage: number;
+  title?: string;
+  barColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  invertProgressColors?: boolean;
+  showPercentage?: boolean;
+  renderAnimated?: boolean;
+  renderAnimatedDuration?: number;
+  classNames?: {
+    container?: string;
+    wrapper?: string;
+    track?: string;
+    fill?: string;
+    progress?: string;
+    title?: string;
+    text?: string;
+  };
+  styles?: {
+    container?: CSSProperties;
+    wrapper?: CSSProperties;
+    track?: CSSProperties;
+    fill?: CSSProperties;
+    progress?: CSSProperties;
+    title?: CSSProperties;
+    text?: CSSProperties;
+  };
+}
+
+/**
+ * Horizontal progress bar with optional title, percentage label, color overrides, and entrance animation.
+ *
+ * - Pass `percentage` (0–100) to set fill level; values are clamped automatically.
+ * - Set `renderAnimated` to animate the fill from 0 to the target on mount; control speed with `renderAnimatedDuration`.
+ * - Use `invertProgressColors` to swap the success/error color logic (useful for "budget remaining" scenarios).
+ * - Accepts `classNames` and `styles` for keys: `container`, `wrapper`, `track`, `fill`, `progress`, `title`, `text`.
+ */
+export const ProgressBar = forwardRef<HTMLDivElement, ProgressBarProps>(
+  (
+    {
+      percentage,
+      title,
+      barColor,
+      backgroundColor = 'rgb(var(--cleen-gray), 0.1)',
+      textColor = 'rgb(var(--cleen-gray))',
+      invertProgressColors = false,
+      showPercentage = false,
+      renderAnimated = false,
+      renderAnimatedDuration = 1000,
+      className,
+      classNames,
+      style,
+      styles,
+      ...props
+    },
+    ref: ForwardedRef<HTMLDivElement>
+  ) => {
+    const clampPercentage = Math.max(0, Math.min(percentage, 100));
+
+    const lastPercentageRef = useRef(clampPercentage);
+
+    const [renderedPercentage, setRenderedPercentage] = useState(
+      renderAnimated ? 0 : clampPercentage
+    );
+    const animatedPercentage = useAnimateNumber({
+      targetNumber: renderedPercentage,
+      duration: renderAnimatedDuration,
+      disabled: !renderAnimated,
+    });
+
+    useEffect(() => {
+      if (renderAnimated) {
+        setTimeout(() => setRenderedPercentage(clampPercentage), 0);
+        return;
+      }
+
+      if (lastPercentageRef.current !== clampPercentage) {
+        setRenderedPercentage(clampPercentage);
+        lastPercentageRef.current = clampPercentage;
+      }
+    }, [clampPercentage, renderAnimated]);
+
+    const progressColor = useMemo(() => {
+      if (barColor) return barColor;
+
+      const _color =
+        clampPercentage <= 30
+          ? 'red'
+          : clampPercentage < 70
+            ? 'orange'
+            : 'green';
+
+      switch (_color) {
+        case 'red':
+          return invertProgressColors
+            ? 'rgb(var(--cleen-success))'
+            : 'rgb(var(--cleen-error))';
+        case 'orange':
+          return 'rgb(var(--cleen-warning))';
+        case 'green':
+          return invertProgressColors
+            ? 'rgb(var(--cleen-error))'
+            : 'rgb(var(--cleen-success))';
+        default:
+          return 'rgb(var(--cleen-success))';
+      }
+    }, [clampPercentage, invertProgressColors, barColor]);
+
+    return (
+      <div ref={ref} className={cn('cleen', className)} style={style}>
+        <div
+          className={cn('cleen-w-full', classNames?.container)}
+          style={styles?.container}
+          {...props}
+        >
+          {title && (
+            <div
+              className={cn(
+                'cleen-mb-1 cleen-font-semibold cleen-text-xs',
+                classNames?.title
+              )}
+              style={styles?.title}
+            >
+              {title}
+            </div>
+          )}
+          <div
+            className={cn(
+              'cleen-flex cleen-items-center cleen-gap-2 cleen-w-full cleen-h-4',
+              classNames?.wrapper || classNames?.progress
+            )}
+            style={styles?.wrapper ?? styles?.progress}
+          >
+            <div
+              className={cn(
+                'cleen-overflow-hidden cleen-flex-1 cleen-h-2 cleen-rounded-full',
+                classNames?.track
+              )}
+              style={{ backgroundColor, ...styles?.track }}
+            >
+              <div
+                className={cn(
+                  'cleen-h-full cleen-transition-all cleen-duration-300 ease-out',
+                  classNames?.fill
+                )}
+                style={{
+                  width: `${renderedPercentage}%`,
+                  backgroundColor: progressColor,
+                  ...(renderAnimated && {
+                    transitionDuration: `${renderAnimatedDuration}ms`,
+                  }),
+                  ...styles?.fill,
+                }}
+              />
+            </div>
+            {showPercentage && (
+              <span
+                className={cn(
+                  'cleen-font-medium cleen-text-sm cleen-whitespace-nowrap cleen-w-10',
+                  classNames?.text
+                )}
+                style={{ color: textColor, ...styles?.text }}
+              >
+                {Math.round(animatedPercentage)}%
+              </span>
+            )}
+          </div>
+        </div>
+      </div>
+    );
+  }
+);
+
+ProgressBar.displayName = 'ProgressBar';

package/src/components/progressBar/index.ts

@@ -0,0 +1 @@
+export { ProgressBar, type ProgressBarProps } from './ProgressBar';

package/src/components/progressCircle/ProgressCircle.tsx

@@ -0,0 +1,142 @@
+import { cn } from '@cleen/ui-core';
+import type { ComponentProps, CSSProperties, ForwardedRef } from 'react';
+import { forwardRef, useEffect, useState } from 'react';
+
+const sizes = { xs: 40, sm: 60, md: 80, lg: 100, xl: 120, xxl: 140, xxxl: 160 };
+
+export interface ProgressCircleProps extends ComponentProps<'div'> {
+  isFullscreen?: boolean;
+  percentage: number;
+  duration?: number;
+  radius?: number;
+  stroke?: number;
+  size?: keyof typeof sizes;
+  color?: string;
+  emptyColor?: string;
+  textColor?: string;
+  fontSize?: string | number;
+  classNames?: { container?: string };
+  styles?: { container?: CSSProperties };
+}
+
+/**
+ * Animated SVG circular progress indicator.
+ *
+ * - Animates from 0% to `percentage` on mount over `duration` milliseconds.
+ * - Choose from preset `size` values (`xs`–`xxxl`) or supply a custom `radius` in pixels.
+ * - Override track and fill colors with `emptyColor` and `color`; label color with `textColor`.
+ * - Pass `isFullscreen` to center the circle in a full-viewport overlay.
+ * - Accepts `classNames` and `styles` for key: `container`.
+ */
+export const ProgressCircle = forwardRef<HTMLDivElement, ProgressCircleProps>(
+  (
+    {
+      isFullscreen,
+      percentage,
+      duration = 1000,
+      radius,
+      stroke = 16,
+      size = 'md',
+      color = 'rgb(var(--cleen-primary))',
+      emptyColor = 'rgb(var(--cleen-gray), 0.1)',
+      textColor = 'rgb(var(--cleen-gray))',
+      fontSize,
+      className,
+      classNames,
+      style,
+      styles,
+      ...props
+    },
+    ref: ForwardedRef<HTMLDivElement>
+  ) => {
+    const circleRadius = radius ?? sizes[size] / 2;
+    const normalizedRadius = circleRadius - stroke / 2;
+    const circumference = normalizedRadius * 2 * Math.PI;
+
+    const [progress, setProgress] = useState(0);
+
+    useEffect(() => {
+      let start: number | null = null;
+
+      const animate = (timestamp: number) => {
+        if (!start) start = timestamp;
+        const progressTime = timestamp - start;
+        const progressPercent = Math.min(
+          (progressTime / duration) * percentage,
+          percentage
+        );
+        setProgress(progressPercent);
+        if (progressPercent < percentage) {
+          requestAnimationFrame(animate);
+        }
+      };
+
+      requestAnimationFrame(animate);
+    }, [percentage, duration]);
+
+    const strokeDashoffset = circumference - (progress / 100) * circumference;
+
+    return (
+      <div
+        ref={ref}
+        className={cn('cleen', className)}
+        style={style}
+        {...props}
+      >
+        <div
+          className={cn(
+            'cleen-flex cleen-justify-center cleen-items-center cleen-w-full cleen-h-full',
+            {
+              'cleen-h-screen cleen-w-screen cleen-bg-background': isFullscreen,
+            },
+            classNames?.container
+          )}
+          style={styles?.container}
+        >
+          <svg
+            height={circleRadius * 2}
+            width={circleRadius * 2}
+            style={{ transform: 'rotate(-90deg)' }}
+          >
+            {/* Background circle */}
+            <circle
+              stroke={emptyColor}
+              fill="transparent"
+              strokeWidth={stroke}
+              r={normalizedRadius}
+              cx={circleRadius}
+              cy={circleRadius}
+            />
+            {/* Progress circle */}
+            <circle
+              stroke={color}
+              fill="transparent"
+              strokeWidth={stroke}
+              strokeLinecap="round"
+              strokeDasharray={circumference}
+              strokeDashoffset={strokeDashoffset}
+              r={normalizedRadius}
+              cx={circleRadius}
+              cy={circleRadius}
+            />
+            {/* Text */}
+            <text
+              x="50%"
+              y="50%"
+              dy=".3em"
+              textAnchor="middle"
+              fontWeight={600}
+              fontSize={fontSize ?? circleRadius / 2.5}
+              fill={textColor}
+              transform={`rotate(90, ${circleRadius}, ${circleRadius})`}
+            >
+              {Math.round(progress)}%
+            </text>
+          </svg>
+        </div>
+      </div>
+    );
+  }
+);
+
+ProgressCircle.displayName = 'ProgressCircle';

package/src/components/progressCircle/index.ts

@@ -0,0 +1 @@
+export { ProgressCircle, type ProgressCircleProps } from './ProgressCircle';