@cleen/ui 0.1.0

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

@@ -0,0 +1,69 @@
+import type { TooltipProps } from '@/components/tooltip/Tooltip';
+import type { ComponentProps, CSSProperties, ReactNode } from 'react';
+
+export interface Bar {
+  // Type indicating serie as a bar
+  type: 'bar';
+
+  // Range start (0-100). If omitted for a range, defaults to 0.
+  start?: number;
+  // Range end (0-100). If omitted for a range, defaults to 100.
+  end?: number;
+}
+
+export interface Clamp {
+  // Type indicating serie as a clamp
+  type: 'clamp';
+
+  // Position for clamp markers (0-100). Optional if `start` is provided.
+  value?: number;
+}
+
+export type Serie = (Bar | Clamp) & {
+  // Color for the serie. Any valid CSS color.
+  color?: string;
+
+  // Height of the series in px
+  height?: number;
+
+  // Optional label underneath the serie
+  label?: ReactNode;
+
+  // Optional tooltip upon hovering over the serie
+  tooltip?: TooltipProps;
+};
+
+export interface AdvancedProgressBarProps extends ComponentProps<'div'> {
+  // Array of series to render on the track.
+  series?: Serie[];
+  // Optional CSS class overrides
+  classNames?: {
+    container?: string;
+    track?: string;
+    bar?: string; // for range bars
+    clamp?: string; // for clamp markers
+    labels?: string;
+    label?: string;
+  };
+  // Optional inline style overrides
+  styles?: {
+    container?: CSSProperties;
+    track?: CSSProperties;
+    bar?: CSSProperties;
+    clamp?: CSSProperties;
+    label?: CSSProperties;
+    labels?: CSSProperties;
+  };
+  track?: {
+    // Track background color
+    color?: string;
+    // Height of the track in px (visual), defaults to 8
+    height?: number;
+  };
+  // Minimum value for the scale (defaults to 0)
+  minValue?: number;
+  // Maximum value for the scale (defaults to 100)
+  maxValue?: number;
+  renderAnimated?: boolean;
+  renderAnimatedDuration?: number;
+}

package/src/components/advancedProgressBar/utils.ts

@@ -0,0 +1,17 @@
+export const clamp = (v: number) =>
+  Math.max(0, Math.min(100, Number.isFinite(v) ? v : 0));
+
+export const valueToPercent = (
+  value: number,
+  minValue: number,
+  maxValue: number
+) => {
+  const min = Number.isFinite(minValue) ? minValue : 0;
+  const max = Number.isFinite(maxValue) ? maxValue : 100;
+
+  if (max === min) {
+    return 0;
+  }
+
+  return ((value - min) / (max - min)) * 100;
+};

package/src/components/audioPlayback/AudioPlayback.tsx

@@ -0,0 +1,141 @@
+import { Button } from '@/components/button';
+import type { ButtonProps } from '@/components/button/Button';
+import {
+  cn,
+  ColorHelpers,
+  formatAudioTime,
+  type ComponentClassnames,
+  type ComponentStyles,
+} from '@cleen/ui-core';
+import { useWavesurfer } from '@wavesurfer/react';
+import {
+  forwardRef,
+  useCallback,
+  useRef,
+  type CSSProperties,
+  type ComponentProps,
+} from 'react';
+import { FaPause, FaPlay } from 'react-icons/fa';
+import type { WaveSurferOptions } from 'wavesurfer.js';
+
+type WaveSurferHookOptions = Omit<WaveSurferOptions, 'container' | 'url'>;
+
+const DEFAULT_OPTIONS: WaveSurferHookOptions = {
+  waveColor: ColorHelpers.getComputedColor('var(--cleen-light-gray)'),
+  progressColor: ColorHelpers.getComputedColor('var(--cleen-primary)'),
+  cursorColor: 'rgb(var(--cleen-primary))',
+  height: 56,
+  barWidth: 2,
+  barGap: 2,
+  barRadius: 2,
+  interact: true,
+  normalize: true,
+};
+
+export interface AudioPlaybackProps extends Omit<
+  ComponentProps<'div'>,
+  'children'
+> {
+  /** URL of the audio file to play */
+  url: string;
+  options?: WaveSurferHookOptions;
+  classNames?: {
+    container?: string;
+    controls?: string;
+    playButton?: ComponentClassnames<ButtonProps>;
+    waveform?: string;
+    timestamp?: string;
+  };
+  styles?: {
+    container?: CSSProperties;
+    controls?: CSSProperties;
+    playButton?: ComponentStyles<ButtonProps>;
+    waveform?: CSSProperties;
+    timestamp?: CSSProperties;
+  };
+}
+
+/**
+ * The `AudioPlayback` component renders an interactive audio player with a waveform
+ * visualization, a play/pause control, and a current/total time display.
+ *
+ * - Provide a `url` pointing to the audio file.
+ * - Use `waveColor` / `progressColor` to theme the waveform.
+ * - Accepts `classNames` and `styles` to customize: `container`, `controls`, `playButton`, `waveform`, `timestamp`.
+ */
+export const AudioPlayback = forwardRef<HTMLDivElement, AudioPlaybackProps>(
+  function AudioPlayback(
+    { url, options, className, classNames, style, styles, ...props },
+    ref
+  ) {
+    const waveformRef = useRef<HTMLDivElement>(null);
+
+    const { wavesurfer, isPlaying, isReady, currentTime } = useWavesurfer({
+      ...DEFAULT_OPTIONS,
+      ...options,
+      container: waveformRef,
+      url,
+    });
+
+    const totalDuration = isReady ? (wavesurfer?.getDuration() ?? 0) : 0;
+
+    const handlePlayPause = useCallback(() => {
+      wavesurfer?.playPause();
+    }, [wavesurfer]);
+
+    return (
+      <div
+        ref={ref}
+        className={cn('cleen', className)}
+        style={style}
+        {...props}
+      >
+        <div
+          className={cn(
+            'cleen-flex cleen-items-center cleen-gap-3 cleen-px-4 cleen-py-3 cleen-rounded-xl cleen-bg-white cleen-border cleen-border-gray/10',
+            classNames?.container
+          )}
+          style={styles?.container}
+        >
+          {/* play/pause controls */}
+          <Button
+            type="button"
+            onClick={handlePlayPause}
+            disabled={!isReady}
+            aria-label={isPlaying ? 'Pause' : 'Play'}
+            className={classNames?.playButton?.className}
+            classNames={{
+              ...classNames?.playButton?.classNames,
+              container: cn(
+                'cleen-p-0 !cleen-size-9 cleen-rounded-full',
+                classNames?.playButton?.classNames?.container
+              ),
+            }}
+            {...styles?.playButton}
+          >
+            {isPlaying ? <FaPause /> : <FaPlay />}
+          </Button>
+
+          {/* waveform */}
+          <div
+            ref={waveformRef}
+            className={cn('cleen-flex-1 cleen-min-w-0', classNames?.waveform)}
+            style={styles?.waveform}
+          />
+
+          {/* timestamp: current / total */}
+          <span
+            className={cn(
+              'cleen-shrink-0 cleen-text-xs cleen-text-gray/60 cleen-tabular-nums',
+              classNames?.timestamp
+            )}
+            style={styles?.timestamp}
+          >
+            {formatAudioTime(currentTime)}&nbsp;/&nbsp;
+            {formatAudioTime(totalDuration)}
+          </span>
+        </div>
+      </div>
+    );
+  }
+);

package/src/components/audioPlayback/index.ts

@@ -0,0 +1,2 @@
+export { AudioPlayback } from './AudioPlayback';
+export type { AudioPlaybackProps } from './AudioPlayback';

package/src/components/audioRecorder/AudioRecorder.tsx

@@ -0,0 +1,391 @@
+import {
+  DEFAULT_AUDIO_RECORDER_OPTIONS,
+  DEFAULT_REGION_COLOR,
+} from '@/components/audioRecorder/constant/default';
+import { DEFAULT_AUDIO_RECORDER_LABELS } from '@/components/audioRecorder/constant/labels';
+import type { AudioRecorderProps } from '@/components/audioRecorder/types/props';
+import { Button } from '@/components/button';
+import { IconCheck } from '@/components/cleenIcon';
+import { cn, formatAudioTime, trimBlob } from '@cleen/ui-core';
+import { useWavesurfer } from '@wavesurfer/react';
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { BiMicrophone } from 'react-icons/bi';
+import { BsStop } from 'react-icons/bs';
+import { FaPause, FaPlay, FaScissors, FaTrash } from 'react-icons/fa6';
+import RecordPlugin from 'wavesurfer.js/dist/plugins/record.js';
+import RegionsPlugin, {
+  type Region,
+} from 'wavesurfer.js/dist/plugins/regions.js';
+
+type RecorderStatus = 'idle' | 'recording' | 'recorded';
+
+/**
+ * `AudioRecorder` captures audio from the microphone with a live waveform preview.
+ * After stopping, a resizable trim region appears — drag its handles to select the
+ * desired clip, then hit the scissors button to apply. The trash button discards
+ * the whole recording.
+ *
+ * - `onFinalize(blob, url)` fires when the user confirms the final recording.
+ * - `recordOptions` are forwarded directly to the WaveSurfer `RecordPlugin`.
+ * - `options` controls the WaveSurfer instance (waveColor, height, regionColor, etc.).
+ * - `labels` allows overriding UI strings (e.g. `startRecording`).
+ * - Accepts `classNames` / `styles` for: `container`, `startButton`, `startLabel`,
+ *   `stopButton`, `waveform`, `recordedContainer`, `timestamp`, `trimmedTimestamp`,
+ *   `playPauseButton`, `discardButton`, `trimButton`, `finalizeButton`.
+ */
+export const AudioRecorder = forwardRef<HTMLDivElement, AudioRecorderProps>(
+  function AudioRecorder(
+    {
+      onFinalize,
+      recordOptions,
+      options,
+      labels = DEFAULT_AUDIO_RECORDER_LABELS,
+      className,
+      classNames,
+      style,
+      styles,
+      ...props
+    },
+    ref
+  ) {
+    const waveformRef = useRef<HTMLDivElement>(null);
+
+    const [status, setStatus] = useState<RecorderStatus>('idle');
+    const [recordedBlob, setRecordedBlob] = useState<Blob | null>(null);
+    const [trimRegion, setTrimRegion] = useState<{
+      start: number;
+      end: number;
+    } | null>(null);
+    const [isTrimming, setIsTrimming] = useState(false);
+
+    // Lets wavesurfer callbacks read the latest status without going stale in a closure
+    const statusRef = useRef<RecorderStatus>('idle');
+    statusRef.current = status;
+
+    // Stable plugin instances – reinitialising mid-lifecycle would nuke wavesurfer (¬_¬)
+    const plugins = useMemo(
+      () =>
+        [
+          RecordPlugin.create({
+            renderRecordedAudio: true,
+            scrollingWaveform: false,
+            continuousWaveform: false,
+            ...recordOptions,
+          }),
+          RegionsPlugin.create(),
+        ] as [RecordPlugin, RegionsPlugin],
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      []
+    );
+
+    const [recordPlugin, regionPlugin] = plugins;
+
+    const { wavesurfer, isPlaying, isReady, currentTime } = useWavesurfer({
+      ...DEFAULT_AUDIO_RECORDER_OPTIONS,
+      ...options,
+      container: waveformRef,
+      plugins,
+    });
+
+    const totalDuration = isReady ? (wavesurfer?.getDuration() ?? 0) : 0;
+
+    useEffect(() => {
+      const unsubs = [
+        recordPlugin.on('record-start', () => setStatus('recording')),
+        recordPlugin.on('record-end', (blob: Blob) => {
+          setStatus('recorded');
+          setRecordedBlob(blob);
+        }),
+        regionPlugin.on('region-clicked', (region, e) => {
+          e.stopPropagation(); // prevent triggering a click on the waveform
+          region.play(true);
+        }),
+      ];
+
+      return () => unsubs.forEach(fn => fn?.());
+    }, [regionPlugin, recordPlugin]);
+
+    // ── Add a full-span resizable region whenever a (new) audio finishes loading ──
+    //
+    // renderRecordedAudio causes wavesurfer to call load() internally after record-end,
+    // so 'ready' fires once the waveform is drawn. Same thing happens after a trim reload.
+
+    useEffect(() => {
+      if (!wavesurfer) return;
+
+      const unsub = wavesurfer.on('ready', () => {
+        if (statusRef.current !== 'recorded') return;
+
+        const duration = wavesurfer.getDuration();
+        regionPlugin.clearRegions();
+
+        const region: Region = regionPlugin.addRegion({
+          start: 0,
+          end: duration,
+          color: options?.regionColor ?? DEFAULT_REGION_COLOR,
+          drag: false,
+          resize: true,
+        });
+
+        setTrimRegion({ start: region.start, end: region.end });
+      });
+
+      return unsub;
+    }, [wavesurfer, regionPlugin, options]);
+
+    // Keep trim state in sync as the user drags the region handles
+
+    useEffect(() => {
+      const unsub = regionPlugin.on('region-updated', (region: Region) => {
+        setTrimRegion({ start: region.start, end: region.end });
+      });
+
+      return unsub;
+    }, [regionPlugin]);
+
+    const handleStartRecording = useCallback(async () => {
+      await recordPlugin.startRecording();
+    }, [recordPlugin]);
+
+    const handleStopRecording = useCallback(() => {
+      recordPlugin.stopRecording();
+    }, [recordPlugin]);
+
+    const handlePlayPause = useCallback(() => {
+      wavesurfer?.playPause();
+    }, [wavesurfer]);
+
+    const handleTrim = useCallback(async () => {
+      if (!recordedBlob || !trimRegion || !wavesurfer) return;
+
+      setIsTrimming(true);
+      try {
+        const trimmed = await trimBlob(
+          recordedBlob,
+          trimRegion.start,
+          trimRegion.end
+        );
+        const url = URL.createObjectURL(trimmed);
+
+        setRecordedBlob(trimmed);
+
+        // Reload waveform – 'ready' will fire again and re-add a fresh full-span region
+        wavesurfer.load(url);
+      } finally {
+        setIsTrimming(false);
+      }
+    }, [recordedBlob, trimRegion, wavesurfer]);
+
+    const handleDiscard = useCallback(() => {
+      regionPlugin.clearRegions();
+      wavesurfer?.empty();
+      setRecordedBlob(null);
+      setTrimRegion(null);
+      setStatus('idle');
+    }, [wavesurfer, regionPlugin]);
+
+    const handleFinalize = useCallback(() => {
+      if (recordedBlob) {
+        const url = URL.createObjectURL(recordedBlob);
+        onFinalize?.(recordedBlob, url);
+      }
+    }, [onFinalize, recordedBlob]);
+
+    // Scissors button is disabled when the region already spans the whole clip
+    const isFullSpan =
+      !trimRegion || (trimRegion.start <= 0 && trimRegion.end >= totalDuration);
+
+    return (
+      <div
+        ref={ref}
+        className={cn('cleen wavesurfer-handle', className)}
+        style={style}
+        {...props}
+      >
+        <div
+          className={cn(
+            'cleen-flex cleen-flex-col cleen-items-center cleen-gap-3',
+            classNames?.container
+          )}
+          style={styles?.container}
+        >
+          {/* ── idle ── */}
+          {status === 'idle' && (
+            <>
+              <button
+                type="button"
+                onClick={handleStartRecording}
+                aria-label="Start recording"
+                className={cn(
+                  'cleen-p-8 cleen-border-2 cleen-border-primary/20 hover:cleen-border-primary cleen-rounded-full cleen-transition-colors',
+                  classNames?.startButton
+                )}
+                style={styles?.startButton}
+              >
+                <BiMicrophone className="cleen-size-8 cleen-text-primary" />
+              </button>
+
+              <p
+                className={cn(
+                  'cleen-text-gray/50 cleen-text-sm cleen-select-none',
+                  classNames?.startLabel
+                )}
+                style={styles?.startLabel}
+              >
+                {labels.startRecording}
+              </p>
+            </>
+          )}
+
+          {/* ── recording ── */}
+          {status === 'recording' && (
+            <button
+              type="button"
+              onClick={handleStopRecording}
+              aria-label="Stop recording"
+              className={cn(
+                'cleen-p-8 cleen-border-2 cleen-border-primary/20 hover:cleen-border-primary cleen-rounded-full cleen-transition-colors',
+                classNames?.stopButton
+              )}
+              style={styles?.stopButton}
+            >
+              <BsStop className="cleen-size-8 cleen-text-primary" />
+            </button>
+          )}
+
+          {/* ── waveform (always mounted – wavesurfer needs a stable DOM container) ── */}
+          <div
+            ref={waveformRef}
+            className={cn(
+              'cleen-w-full cleen-min-w-0 cleen-waveform',
+              status === 'idle' && 'cleen-hidden',
+              classNames?.waveform
+            )}
+            style={styles?.waveform}
+          />
+
+          {/* ── recorded: inline playback + trim toolbar ── */}
+          {status === 'recorded' && (
+            <div
+              className={cn(
+                'cleen-flex cleen-items-center cleen-gap-2 cleen-w-full',
+                classNames?.recordedContainer
+              )}
+              style={styles?.recordedContainer}
+            >
+              {/* Play / Pause */}
+              <Button
+                type="button"
+                onClick={handlePlayPause}
+                disabled={!isReady}
+                aria-label={isPlaying ? 'Pause' : 'Play'}
+                className={classNames?.playPauseButton?.className}
+                classNames={{
+                  ...classNames?.playPauseButton?.classNames,
+                  container: cn(
+                    'cleen-p-0 !cleen-size-9 cleen-rounded-full cleen-shrink-0',
+                    classNames?.playPauseButton?.classNames?.container
+                  ),
+                }}
+                {...styles?.playPauseButton}
+              >
+                {isPlaying ? <FaPause /> : <FaPlay />}
+              </Button>
+
+              {/* Current / total duration */}
+              <span
+                className={cn(
+                  'cleen-tabular-nums cleen-text-gray/60 cleen-text-xs cleen-shrink-0',
+                  classNames?.timestamp
+                )}
+                style={styles?.timestamp}
+              >
+                {formatAudioTime(currentTime)}&nbsp;/&nbsp;
+                {formatAudioTime(totalDuration)}
+              </span>
+
+              <span className="cleen-flex-1" />
+
+              {/* Selected trim range hint – visible only when region ≠ full span */}
+              {!isFullSpan && trimRegion && (
+                <span
+                  className={cn(
+                    'cleen-tabular-nums cleen-text-gray/50 cleen-text-xs cleen-shrink-0',
+                    classNames?.trimmedTimestamp
+                  )}
+                  style={styles?.trimmedTimestamp}
+                >
+                  {formatAudioTime(trimRegion.start)}–
+                  {formatAudioTime(trimRegion.end)}
+                </span>
+              )}
+
+              {/* Discard */}
+              <Button
+                type="button"
+                onClick={handleDiscard}
+                variant="secondary"
+                aria-label="Discard recording"
+                className={classNames?.discardButton?.className}
+                classNames={{
+                  ...classNames?.discardButton?.classNames,
+                  container: cn(
+                    'cleen-p-0 !cleen-size-9 cleen-rounded-full cleen-shrink-0',
+                    classNames?.discardButton?.classNames?.container
+                  ),
+                }}
+                {...styles?.discardButton}
+              >
+                <FaTrash className="cleen-text-error" />
+              </Button>
+
+              {/* Apply trim */}
+              <Button
+                type="button"
+                onClick={handleTrim}
+                disabled={isFullSpan || isTrimming || !isReady}
+                aria-label="Apply trim"
+                variant="secondary"
+                className={classNames?.trimButton?.className}
+                classNames={{
+                  ...classNames?.trimButton?.classNames,
+                  container: cn(
+                    'cleen-p-0 !cleen-size-9 cleen-rounded-full cleen-shrink-0',
+                    classNames?.trimButton?.classNames?.container
+                  ),
+                }}
+                {...styles?.trimButton}
+              >
+                <FaScissors />
+              </Button>
+
+              <Button
+                type="button"
+                onClick={handleFinalize}
+                aria-label="Finalize recording"
+                className={classNames?.finalizeButton?.className}
+                classNames={{
+                  ...classNames?.finalizeButton?.classNames,
+                  container: cn(
+                    'cleen-p-0 !cleen-size-9 cleen-rounded-full cleen-shrink-0',
+                    classNames?.finalizeButton?.classNames?.container
+                  ),
+                }}
+                {...styles?.finalizeButton}
+              >
+                <IconCheck />
+              </Button>
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+);

package/src/components/audioRecorder/constant/default.ts

@@ -0,0 +1,19 @@
+import type { WaveSurferHookOptions } from '@/components/audioRecorder/types/props';
+import { ColorHelpers } from '@cleen/ui-core';
+
+export const DEFAULT_WAVE_COLOR = ColorHelpers.getComputedColor(
+  'var(--cleen-primary)'
+);
+export const DEFAULT_REGION_COLOR = 'rgba(var(--cleen-primary), 0.15)';
+
+export const DEFAULT_AUDIO_RECORDER_OPTIONS: WaveSurferHookOptions = {
+  waveColor: DEFAULT_WAVE_COLOR,
+  progressColor: DEFAULT_WAVE_COLOR,
+  cursorColor: 'rgb(var(--cleen-primary))',
+  height: 56,
+  barWidth: 2,
+  barGap: 2,
+  barRadius: 2,
+  minPxPerSec: 0.5,
+  sampleRate: 8000,
+};

package/src/components/audioRecorder/constant/labels.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+
+export interface AudioRecorderLabels {
+  startRecording: ReactNode;
+}
+
+export const DEFAULT_AUDIO_RECORDER_LABELS: AudioRecorderLabels = {
+  startRecording: 'Click to start recording',
+};

package/src/components/audioRecorder/index.ts

@@ -0,0 +1,2 @@
+export { AudioRecorder } from './AudioRecorder';
+export type { AudioRecorderProps } from './types/props';