@cleen/ui 0.1.0

package/src/components/audioRecorder/types/props.ts

@@ -0,0 +1,56 @@
+import type { AudioRecorderLabels } from '@/components/audioRecorder/constant/labels';
+import type { ButtonProps } from '@/components/button/Button';
+import type { ComponentClassnames, ComponentStyles } from '@cleen/ui-core';
+import type { ComponentProps, CSSProperties } from 'react';
+import type { RecordPluginOptions } from 'wavesurfer.js/dist/plugins/record.js';
+import type { WaveSurferOptions } from 'wavesurfer.js/dist/types.js';
+
+export type WaveSurferHookOptions = Omit<
+  WaveSurferOptions,
+  'container' | 'plugins' | 'splitChannels'
+> & {
+  regionColor?: string;
+};
+
+export interface AudioRecorderProps extends Omit<
+  ComponentProps<'div'>,
+  'children'
+> {
+  /** Fired when a recording is finalized; receives the raw Blob and a transient blob-URL */
+  onFinalize?: (blob: Blob, url: string) => void;
+  /** Options forwarded to the WaveSurfer RecordPlugin */
+  recordOptions?: RecordPluginOptions;
+  /** Options forwarded to the WaveSurfer hook */
+  options?: WaveSurferHookOptions;
+  labels?: Partial<AudioRecorderLabels>;
+  classNames?: {
+    container?: string;
+    startButton?: string;
+    startLabel?: string;
+    stopButton?: string;
+    waveform?: string;
+
+    recordedContainer?: string;
+    timestamp?: string;
+    trimmedTimestamp?: string;
+    playPauseButton?: ComponentClassnames<ButtonProps>;
+    discardButton?: ComponentClassnames<ButtonProps>;
+    trimButton?: ComponentClassnames<ButtonProps>;
+    finalizeButton?: ComponentClassnames<ButtonProps>;
+  };
+  styles?: {
+    container?: CSSProperties;
+    startButton?: CSSProperties;
+    startLabel?: CSSProperties;
+    stopButton?: CSSProperties;
+    waveform?: CSSProperties;
+
+    recordedContainer?: CSSProperties;
+    timestamp?: CSSProperties;
+    trimmedTimestamp?: CSSProperties;
+    playPauseButton?: ComponentStyles<ButtonProps>;
+    discardButton?: ComponentStyles<ButtonProps>;
+    trimButton?: ComponentStyles<ButtonProps>;
+    finalizeButton?: ComponentStyles<ButtonProps>;
+  };
+}

package/src/components/avatar/Avatar.tsx

@@ -0,0 +1,132 @@
+import { IconUser } from '@/components/cleenIcon';
+import { cn } from '@cleen/ui-core';
+import {
+  forwardRef,
+  useMemo,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { sizeVariants, type AvatarSize } from './variants';
+
+export type AvatarProps = Omit<ComponentProps<'div'>, 'children'> & {
+  name?: string;
+  src?: string;
+  alt?: string;
+  size?: AvatarSize | number;
+  initialsLength?: 1 | 2;
+  isSelected?: boolean;
+  showBorder?: boolean;
+  fallback?: ReactNode;
+  classNames?: {
+    container?: string;
+    avatar?: string;
+    avatarSelected?: string;
+    image?: string;
+    fallback?: string;
+  };
+  styles?: {
+    container?: CSSProperties;
+    avatar?: CSSProperties;
+    avatarSelected?: CSSProperties;
+    image?: CSSProperties;
+    fallback?: CSSProperties;
+  };
+};
+
+/**
+ * Avatar component displays a user's profile picture or initials.
+ *
+ * - Supports image source via `src` prop or displays first letter of `name` as fallback.
+ * - Configurable `size` variants: xs, sm, md, lg, xl.
+ * - Optional `isSelected` state changes border color to primary.
+ * - Accepts `classNames` and `styles` objects to customize:
+ *   `container`, `avatar`, `image`, and `fallback`.
+ * - Forwards remaining div props and ref to the root element.
+ */
+export const Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
+  {
+    title,
+    name,
+    src,
+    alt,
+    size = 'md',
+    initialsLength = 2,
+    isSelected = false,
+    showBorder = false,
+    fallback = <IconUser />,
+    className,
+    classNames,
+    style,
+    styles,
+    onClick,
+    ...props
+  },
+  ref
+) {
+  const initials = useMemo(
+    () =>
+      (initialsLength === 2
+        ? name
+            ?.split(' ')
+            .map(n => n.charAt(0).toUpperCase())
+            .join('')
+            .slice(0, initialsLength)
+        : name?.charAt(0).toUpperCase()) || fallback,
+    [name, initialsLength, fallback]
+  );
+
+  return (
+    <div className={cn('cleen', className)} style={style} ref={ref} {...props}>
+      <div
+        onClick={onClick}
+        className={cn(
+          'cleen-flex cleen-justify-center cleen-items-center cleen-bg-gray/20 cleen-rounded-full cleen-font-medium cleen-transition-all',
+          typeof size === 'string' && sizeVariants[size],
+          {
+            'cleen-border-2 cleen-border-white': showBorder,
+            'cleen-cursor-pointer': !!onClick,
+          },
+          classNames?.avatar,
+          {
+            [`cleen-border-primary ${classNames?.avatarSelected}`]:
+              showBorder && isSelected,
+          }
+        )}
+        style={{
+          ...(typeof size === 'number' && {
+            width: size,
+            height: size,
+            fontSize: size * 0.4,
+            lineHeight: `${size}px`,
+          }),
+          ...styles?.avatar,
+          ...(showBorder && isSelected && styles?.avatarSelected),
+        }}
+        title={title || name}
+      >
+        {src ? (
+          <img
+            src={src}
+            alt={alt || name}
+            className={cn(
+              'cleen-rounded-full cleen-w-full cleen-h-full cleen-object-cover',
+              classNames?.image
+            )}
+            style={styles?.image}
+          />
+        ) : (
+          <span
+            className={cn(
+              'cleen-select-none cleen-text-gray/70',
+              classNames?.fallback
+            )}
+            style={styles?.fallback}
+          >
+            {initials}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+});

package/src/components/avatar/index.ts

@@ -0,0 +1 @@
+export { Avatar, type AvatarProps } from './Avatar';

package/src/components/avatar/variants.ts

@@ -0,0 +1,9 @@
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export const sizeVariants: Record<AvatarSize, string> = {
+  xs: 'cleen-size-6 cleen-text-[10px]',
+  sm: 'cleen-size-7 cleen-text-xs',
+  md: 'cleen-size-9 cleen-text-sm',
+  lg: 'cleen-size-11 cleen-text-base',
+  xl: 'cleen-size-14 cleen-text-lg',
+};

package/src/components/avatarRow/AvatarRow.tsx

@@ -0,0 +1,127 @@
+import { Avatar, type AvatarProps } from '@/components/avatar';
+import { type AvatarSize } from '@/components/avatar/variants';
+import {
+  cn,
+  type ComponentClassnames,
+  type ComponentStyles,
+} from '@cleen/ui-core';
+import {
+  forwardRef,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+
+export type AvatarRowProps = Omit<ComponentProps<'div'>, 'children'> & {
+  avatars?: AvatarProps[];
+  size?: AvatarSize;
+  selectedAvatars?: string[];
+  onAvatarToggle?: (id: string) => void;
+  gap?: number;
+  maxVisible?: number;
+  maxExtra?: number;
+  showBorder?: boolean;
+  initialsLength?: 1 | 2;
+  fallback?: ReactNode;
+  classNames?: {
+    container?: string;
+    row?: string;
+    avatar?: ComponentClassnames<AvatarProps>;
+    extra?: ComponentClassnames<AvatarProps>;
+  };
+  styles?: {
+    container?: CSSProperties;
+    row?: CSSProperties;
+    avatar?: ComponentStyles<AvatarProps>;
+    extra?: ComponentStyles<AvatarProps>;
+  };
+};
+
+/**
+ * AvatarRow displays multiple user avatars in a horizontal row.
+ *
+ * - Renders a list of `avatars` with Avatar components.
+ * - Supports `selectedAvatars` array to highlight selected avatars using their `id`.
+ * - Optional `onAvatarToggle` callback fired when an avatar is clicked.
+ * - Configurable `size`, `gap`, `maxVisible` (shows +N for overflow), and `showBorder`.
+ * - Accepts `classNames` and `styles` objects to customize:
+ *   `container`, `row`, `avatar`, and `extra`.
+ * - Forwards remaining div props and ref to the root element.
+ * - By default each avatar has a zIndex based on its position from the left to create a stacking effect.
+ */
+export const AvatarRow = forwardRef<HTMLDivElement, AvatarRowProps>(
+  function AvatarRow(
+    {
+      avatars,
+      size = 'md',
+      selectedAvatars = [],
+      onAvatarToggle,
+      gap = 4,
+      maxVisible,
+      maxExtra = 99,
+      showBorder = true,
+      initialsLength,
+      fallback,
+      className,
+      classNames,
+      style,
+      styles,
+      ...props
+    },
+    ref
+  ) {
+    const visibleAvatars = maxVisible ? avatars?.slice(0, maxVisible) : avatars;
+    const extraCount =
+      maxVisible && avatars && avatars.length > maxVisible
+        ? Math.min(avatars.length - maxVisible, maxExtra)
+        : 0;
+
+    return (
+      <div
+        className={cn('cleen', className)}
+        style={style}
+        ref={ref}
+        {...props}
+      >
+        <div
+          className={cn('cleen-flex cleen-items-center', classNames?.row)}
+          style={{ gap, ...styles?.row }}
+        >
+          {visibleAvatars?.map((avatar, index) => {
+            const isSelected = selectedAvatars.includes(avatar?.id ?? '');
+
+            return (
+              <Avatar
+                key={avatar.id || index}
+                name={avatar.name}
+                src={avatar.src}
+                size={size}
+                isSelected={isSelected}
+                showBorder={showBorder}
+                initialsLength={initialsLength}
+                fallback={fallback}
+                onClick={() => onAvatarToggle?.(avatar.id ?? '')}
+                {...classNames?.avatar}
+                style={{
+                  zIndex: visibleAvatars.length - index,
+                  ...styles?.avatar?.style,
+                }}
+                styles={styles?.avatar?.styles}
+                {...avatar}
+              />
+            );
+          })}
+
+          {extraCount > 0 && (
+            <Avatar
+              size={size}
+              fallback={`+${extraCount}`}
+              {...classNames?.extra}
+              {...styles?.extra}
+            />
+          )}
+        </div>
+      </div>
+    );
+  }
+);

package/src/components/avatarRow/index.ts

@@ -0,0 +1 @@
+export { AvatarRow, type AvatarRowProps } from './AvatarRow';

package/src/components/breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,158 @@
+import { IconChevronRight, IconHouseLine } from '@/components/cleenIcon';
+import { cn } from '@cleen/ui-core';
+import {
+  forwardRef,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { Link } from 'react-router-dom';
+
+export interface BreadcrumbSegment {
+  path: string;
+  icon?: ReactNode;
+  label?: ReactNode;
+  id?: string;
+}
+
+export type BreadcrumbProps = ComponentProps<'div'> & {
+  root?: BreadcrumbSegment | null;
+  segments?: BreadcrumbSegment[];
+  classNames?: {
+    container?: string;
+    list?: string;
+    item?: string;
+    link?: string;
+    chevron?: string;
+    rootItem?: string;
+    rootLink?: string;
+  };
+  styles?: {
+    container?: CSSProperties;
+    list?: CSSProperties;
+    item?: CSSProperties;
+    link?: CSSProperties;
+    chevron?: CSSProperties;
+    rootItem?: CSSProperties;
+    rootLink?: CSSProperties;
+  };
+};
+
+/**
+ * The `Breadcrumb` component displays the navigation path to the current page, helping users understand their location within the application's hierarchy. It supports custom segments, icons, and styling for flexible integration.
+ */
+export const Breadcrumb = forwardRef<HTMLDivElement, BreadcrumbProps>(
+  function Breadcrumb(
+    {
+      root = {
+        path: '/',
+        icon: (
+          <IconHouseLine aria-hidden="true" className="cleen-h-5 cleen-w-5" />
+        ),
+      },
+      segments,
+      className,
+      classNames,
+      style,
+      styles,
+      ...props
+    },
+    ref
+  ) {
+    // If no segments are being passed, render nothing
+    if (!segments || segments.length === 0) {
+      return null;
+    }
+
+    return (
+      <div
+        className={cn('cleen', className)}
+        style={style}
+        ref={ref}
+        {...props}
+      >
+        <nav
+          className={cn('cleen-hidden sm:cleen-flex', classNames?.container)}
+          style={styles?.container}
+          aria-label="Breadcrumb"
+        >
+          <ol
+            role="list"
+            className={cn(
+              'cleen-flex cleen-items-center cleen-gap-4',
+              classNames?.list
+            )}
+            style={styles?.list}
+          >
+            {root && (
+              <li
+                className={cn(
+                  'cleen-flex cleen-items-center',
+                  classNames?.rootItem
+                )}
+                style={styles?.rootItem}
+              >
+                <Link
+                  to={root?.path}
+                  className={cn(
+                    'cleen-text-sm cleen-text-gray/60 cleen-flex cleen-items-center cleen-gap-2 cleen-transition-colors cleen-duration-200 hover:cleen-text-gray/80',
+                    classNames?.rootLink
+                  )}
+                  style={styles?.rootLink}
+                  aria-current="page"
+                >
+                  {root?.icon}
+                  {root?.label}
+                </Link>
+              </li>
+            )}
+
+            {segments.map(({ path, icon, label, id }, index) => {
+              const isLast = index === segments.length - 1;
+              const displayName =
+                label || path.charAt(0).toUpperCase() + path.slice(1);
+
+              return (
+                <li
+                  key={id || path}
+                  className={cn(
+                    'cleen-flex cleen-items-center cleen-gap-4',
+                    classNames?.item
+                  )}
+                  style={styles?.item}
+                >
+                  {(root || (!root && index !== 0)) && (
+                    <IconChevronRight
+                      className={cn(
+                        'cleen-h-5 cleen-w-5 cleen-text-gray/50',
+                        classNames?.chevron
+                      )}
+                      style={styles?.chevron}
+                      aria-hidden="true"
+                    />
+                  )}
+
+                  <Link
+                    to={path}
+                    className={cn(
+                      'cleen-transition-colors cleen-duration-200 hover:cleen-text-primary cleen-text-sm cleen-flex cleen-items-center cleen-gap-2',
+                      isLast
+                        ? 'cleen-rounded-md cleen-bg-gray/5 cleen-py-1 cleen-px-2 cleen-text-gray/80 cleen-font-semibold'
+                        : 'cleen-text-gray/80 cleen-font-medium',
+                      classNames?.link
+                    )}
+                    style={styles?.link}
+                    aria-current={isLast ? 'page' : undefined}
+                  >
+                    {icon}
+                    {displayName}
+                  </Link>
+                </li>
+              );
+            })}
+          </ol>
+        </nav>
+      </div>
+    );
+  }
+);

package/src/components/breadcrumb/index.ts

@@ -0,0 +1 @@
+export { Breadcrumb, type BreadcrumbProps } from './Breadcrumb';

package/src/components/button/Button.tsx

@@ -0,0 +1,114 @@
+import { Loader } from '@/components/loader';
+import { cn, useWidthDynamicResize } from '@cleen/ui-core';
+import {
+  forwardRef,
+  useImperativeHandle,
+  useRef,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { loaderColorVariants, variants, type ButtonVariant } from './variants';
+
+export type ButtonProps = ComponentProps<'button'> & {
+  variant?: ButtonVariant;
+  label?: ReactNode;
+  fullWidth?: boolean;
+  isLoading?: boolean;
+  leftIcon?: ReactNode;
+  rightIcon?: ReactNode;
+  loaderColor?: string;
+  dataModalTarget?: string;
+  'data-testid'?: string;
+  classNames?: {
+    container?: string;
+    loaderContainer?: string;
+    loader?: string;
+  };
+  styles?: {
+    container?: CSSProperties;
+    loaderContainer?: CSSProperties;
+    loader?: CSSProperties;
+  };
+};
+
+/**
+ * The `Button` component is used to trigger an action or event, such as submitting a form, opening a dialog, or performing a specific task. It is a fundamental UI element that users interact with to initiate various operations within an application.
+ */
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  function Button(
+    {
+      type = 'button',
+      label,
+      onClick,
+      className,
+      classNames,
+      style,
+      styles,
+      disabled = false,
+      leftIcon,
+      rightIcon,
+      loaderColor,
+      isLoading = false,
+      variant = 'primary',
+      fullWidth = false,
+      dataModalTarget,
+      'data-testid': testId,
+      children,
+      ...props
+    },
+    ref
+  ) {
+    const internalRef = useRef<HTMLButtonElement>(null);
+
+    useImperativeHandle(ref, () => internalRef.current!);
+    useWidthDynamicResize({ ref: internalRef, skip: fullWidth }, [
+      isLoading,
+      leftIcon,
+      rightIcon,
+      fullWidth,
+    ]);
+
+    return (
+      <div className={cn('cleen', className)} style={style}>
+        <button
+          type={type}
+          ref={internalRef}
+          className={cn(
+            'cleen-flex cleen-justify-center cleen-items-center cleen-gap-1 cleen-text-sm cleen-text-nowrap cleen-transition-[width] cleen-duration-150 cleen-ease-in-out cleen-cursor-pointer',
+            variants[variant],
+            {
+              'cleen-w-full cleen-flex-1': fullWidth,
+              'cleen-opacity-50 cleen-cursor-not-allowed cleen-pointer-events-none':
+                disabled || isLoading,
+            },
+            classNames?.container
+          )}
+          style={styles?.container}
+          disabled={isLoading || disabled}
+          onClick={onClick}
+          data-testid={testId}
+          data-modal-target={dataModalTarget}
+          {...props}
+        >
+          {isLoading && (
+            <Loader
+              size="xs"
+              color={loaderColor || loaderColorVariants[variant]}
+              className={cn(
+                'cleen-mr-1.5 cleen-w-fit',
+                classNames?.loaderContainer
+              )}
+              style={styles?.loaderContainer}
+              classNames={{ loader: classNames?.loader }}
+              styles={{ loader: styles?.loader }}
+            />
+          )}
+          {leftIcon || null}
+          {label || children}
+          {rightIcon || null}
+        </button>
+      </div>
+    );
+  }
+);

package/src/components/button/index.ts

@@ -0,0 +1,2 @@
+export { Button, type ButtonProps } from './Button';
+export type { ButtonVariant } from './variants';

package/src/components/button/variants.ts

@@ -0,0 +1,41 @@
+export type ButtonVariant =
+  | 'borderless'
+  | 'borderless-blue'
+  | 'borderless-success'
+  | 'group'
+  | 'secondary'
+  | 'secondary-blue'
+  | 'primary'
+  | 'disable'
+  | 'error'
+  | 'warning';
+
+export const variants: Record<ButtonVariant, string> = {
+  borderless:
+    'cleen-flex cleen-py-2 cleen-px-5 cleen-gap-1 cleen-rounded-lg cleen-font-semibold cleen-items-center cleen-text-gray/90 cleen-transition-colors cleen-duration-200 hover:cleen-bg-gray/10',
+  'borderless-blue':
+    'cleen-flex cleen-py-2 cleen-px-5 cleen-gap-1 cleen-rounded-lg cleen-font-semibold cleen-items-center cleen-text-primary/70 cleen-transition-colors cleen-duration-200 hover:cleen-bg-primary/10',
+  'borderless-success':
+    'cleen-flex cleen-py-2 cleen-px-5 cleen-gap-1 cleen-rounded-lg cleen-font-semibold cleen-items-center cleen-text-success cleen-transition-colors cleen-duration-200 hover:cleen-bg-success/10',
+  group:
+    'cleen-flex cleen-border cleen-border-gray/30 cleen-py-2 cleen-px-4 cleen-gap-1 cleen-font-semibold cleen-items-center cleen-text-black cleen-transition-colors cleen-duration-200 focus:cleen-bg-gray/5 focus-visible:cleen-outline-none hover:cleen-bg-gray/10',
+  secondary:
+    'cleen-flex cleen-border cleen-border-gray/20 cleen-text-gray/90 cleen-bg-white cleen-py-2 cleen-px-4 cleen-gap-1 cleen-rounded-lg cleen-font-semibold cleen-items-center cleen-transition-colors cleen-duration-200 hover:cleen-bg-gray/5 focus-visible:cleen-outline-none',
+  'secondary-blue':
+    'cleen-flex cleen-border cleen-border-primary/60 cleen-text-primary cleen-bg-white cleen-py-2 cleen-px-4 cleen-gap-1 cleen-rounded-lg cleen-font-semibold cleen-items-center cleen-transition-colors cleen-duration-200 focus-visible:cleen-outline-none hover:cleen-bg-primary/10',
+  primary:
+    'cleen-flex cleen-justify-center cleen-rounded-md cleen-py-2 cleen-px-4 cleen-font-semibold cleen-leading-6 cleen-text-white cleen-shadow-sm cleen-bg-primary/80 cleen-transition-colors cleen-duration-200 hover:cleen-bg-primary focus-visible:cleen-outline focus-visible:cleen-outline-2 focus-visible:cleen-outline-offset-2 focus-visible:cleen-outline-indigo/60',
+  disable:
+    'cleen-flex cleen-justify-center cleen-rounded-md cleen-bg-gray/10 cleen-py-2 cleen-px-4 cleen-font-semibold cleen-leading-6 cleen-border cleen-border-gray/30 cleen-text-gray/40 cleen-shadow-sm cleen-cursor-default',
+  error:
+    'cleen-flex cleen-justify-center cleen-rounded-md cleen-py-2 cleen-px-4 cleen-font-semibold cleen-leading-6 cleen-text-white cleen-shadow-sm cleen-bg-error/80 cleen-transition-colors cleen-duration-200 hover:cleen-bg-error focus-visible:cleen-outline focus-visible:cleen-outline-2 focus-visible:cleen-outline-offset-2 focus-visible:cleen-outline-indigo/60',
+  warning:
+    'cleen-flex cleen-justify-center cleen-rounded-md cleen-py-2 cleen-px-4 cleen-font-semibold cleen-leading-6 cleen-text-white cleen-shadow-sm cleen-bg-warning/80 cleen-transition-colors cleen-duration-200 hover:cleen-bg-warning focus-visible:cleen-outline focus-visible:cleen-outline-2 focus-visible:cleen-outline-offset-2 focus-visible:cleen-outline-indigo/60',
+};
+
+export const loaderColorVariants: Partial<Record<ButtonVariant, string>> = {
+  primary: 'rgb(var(--cleen-white))',
+  'borderless-success': 'rgb(var(--cleen-success))',
+  error: 'rgb(var(--cleen-white))',
+  warning: 'rgb(var(--cleen-white))',
+};