@zentauri-ui/zentauri-components 2.3.0 → 2.3.2

package/src/ui/speech-recognition/speech-recognition.test.tsx

@@ -0,0 +1,74 @@
+import { createRef } from "react";
+import { render } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { SpeechRecognition } from "./speech-recognition";
+
+describe("SpeechRecognition", () => {
+  it("should set displayName", () => {
+    expect(SpeechRecognition.displayName).toBe("SpeechRecognition");
+  });
+
+  it("should stamp data-slot on the root container", () => {
+    const { container } = render(<SpeechRecognition />);
+    const root = container.querySelector('[data-slot="speech-recognition"]');
+    expect(root).toBeTruthy();
+  });
+
+  it("should render a mic button", () => {
+    const { container } = render(<SpeechRecognition />);
+    const btn = container.querySelector('[data-slot="speech-recognition-btn"]');
+    expect(btn).toBeTruthy();
+  });
+
+  it("should render a status label", () => {
+    const { container } = render(<SpeechRecognition />);
+    const status = container.querySelector(
+      '[data-slot="speech-recognition-status"]',
+    );
+    expect(status).toBeTruthy();
+    expect(status?.textContent).toContain("start listening");
+  });
+
+  it("should render children when provided", () => {
+    const { container } = render(
+      <SpeechRecognition>
+        <div data-testid="child" />
+      </SpeechRecognition>,
+    );
+    expect(container.querySelector('[data-testid="child"]')).toBeTruthy();
+  });
+
+  it("should expose an imperative handle with start, stop, abort methods", () => {
+    const ref = createRef<{
+      start: () => void;
+      stop: () => void;
+      abort: () => void;
+      state: string;
+    }>();
+    render(<SpeechRecognition ref={ref as any} />);
+    expect(ref.current).toBeTruthy();
+    expect(typeof ref.current?.start).toBe("function");
+    expect(typeof ref.current?.stop).toBe("function");
+    expect(typeof ref.current?.abort).toBe("function");
+  });
+
+  it("should set default state to idle", () => {
+    const ref = createRef<{
+      start: () => void;
+      stop: () => void;
+      abort: () => void;
+      state: string;
+    }>();
+    render(<SpeechRecognition ref={ref as any} />);
+    expect(ref.current?.state).toBe("idle");
+  });
+
+  it("should apply custom className", () => {
+    const { container } = render(
+      <SpeechRecognition className="custom-class" />,
+    );
+    const root = container.querySelector('[data-slot="speech-recognition"]');
+    expect(root?.className).toMatch(/custom-class/);
+  });
+});

package/src/ui/speech-recognition/speech-recognition.tsx

@@ -0,0 +1 @@
+export { SpeechRecognitionBase as SpeechRecognition } from "./speech-recognition-base";

package/src/ui/speech-recognition/types.ts

@@ -0,0 +1,50 @@
+import type { VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef, Ref } from "react";
+
+import type {
+  speechRecognitionBtnVariants,
+  speechRecognitionVariants,
+} from "./variants";
+
+export type SpeechRecognitionVariantProps = VariantProps<
+  typeof speechRecognitionBtnVariants
+>;
+
+export type SpeechRecognitionState =
+  | "idle"
+  | "listening"
+  | "processing"
+  | "error";
+
+export interface SpeechRecognitionResult {
+  transcript: string;
+  isFinal: boolean;
+}
+
+export type SpeechRecognitionBaseProps = VariantProps<
+  typeof speechRecognitionVariants
+> &
+  VariantProps<typeof speechRecognitionBtnVariants> &
+  ComponentPropsWithRef<"div"> & {
+    lang?: string;
+    continuous?: boolean;
+    interimResults?: boolean;
+    autoStart?: boolean;
+    onResult?: (result: SpeechRecognitionResult) => void;
+    onError?: (error: string) => void;
+    onStateChange?: (state: SpeechRecognitionState) => void;
+    renderMic?: (props: {
+      isListening: boolean;
+      state: SpeechRecognitionState;
+    }) => React.ReactNode;
+    children?: React.ReactNode;
+  };
+
+export type SpeechRecognitionProps = SpeechRecognitionBaseProps;
+
+export type SpeechRecognitionRef = {
+  start: () => void;
+  stop: () => void;
+  abort: () => void;
+  state: SpeechRecognitionState;
+};

package/src/ui/speech-recognition/variants.ts

@@ -0,0 +1,47 @@
+import { cva } from "class-variance-authority";
+
+import {
+  zuiSpeechRecognitionAppearances,
+  zuiSpeechRecognitionBase,
+  zuiSpeechRecognitionBtnActive,
+  zuiSpeechRecognitionBtnBase,
+  zuiSpeechRecognitionBtnSizes,
+  zuiSpeechRecognitionSizes,
+  zuiSpeechRecognitionStatusBase,
+  zuiSpeechRecognitionTranscriptBase,
+} from "../../design-system/speech-recognition";
+
+export const speechRecognitionVariants = cva(
+  zuiSpeechRecognitionBase.join(" "),
+  {
+    variants: {
+      size: zuiSpeechRecognitionSizes,
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  },
+);
+
+export const speechRecognitionBtnVariants = cva(
+  zuiSpeechRecognitionBtnBase.join(" "),
+  {
+    variants: {
+      appearance: zuiSpeechRecognitionAppearances,
+      size: zuiSpeechRecognitionBtnSizes,
+    },
+    defaultVariants: {
+      appearance: "default",
+      size: "md",
+    },
+  },
+);
+
+export const speechRecognitionStatusClasses =
+  zuiSpeechRecognitionStatusBase.join(" ");
+
+export const speechRecognitionTranscriptClasses =
+  zuiSpeechRecognitionTranscriptBase.join(" ");
+
+export const speechRecognitionBtnActiveClasses =
+  zuiSpeechRecognitionBtnActive.join(" ");

package/src/ui/speech-synthesizer/animated/animations.ts

@@ -0,0 +1,62 @@
+import type { Transition, Variants } from "framer-motion";
+
+export type SpeechSynthesizerAnimation = "none" | "pulse" | "wave" | "glow";
+
+export type SpeechSynthesizerAnimationPresets = Record<
+  SpeechSynthesizerAnimation,
+  {
+    transition: Transition;
+    variants: Variants;
+  }
+>;
+
+export const speechSynthesizerAnimationPresets: SpeechSynthesizerAnimationPresets =
+  {
+    none: {
+      transition: { duration: 0 },
+      variants: {
+        initial: { scale: 1 },
+        animate: { scale: 1 },
+      },
+    },
+    pulse: {
+      transition: {
+        duration: 1,
+        repeat: Infinity,
+        repeatType: "reverse",
+        ease: "easeInOut",
+      },
+      variants: {
+        initial: { scale: 1, opacity: 0.7 },
+        animate: { scale: 1.15, opacity: 1 },
+      },
+    },
+    wave: {
+      transition: {
+        duration: 0.8,
+        repeat: Infinity,
+        repeatType: "reverse",
+        ease: "easeInOut",
+      },
+      variants: {
+        initial: { scale: 1, rotate: 0 },
+        animate: { scale: 1.1, rotate: -5 },
+      },
+    },
+    glow: {
+      transition: {
+        duration: 1.5,
+        repeat: Infinity,
+        repeatType: "reverse",
+        ease: "easeInOut",
+      },
+      variants: {
+        initial: {
+          boxShadow: "0 0 0px rgba(59,130,246,0)",
+        },
+        animate: {
+          boxShadow: "0 0 20px rgba(59,130,246,0.5)",
+        },
+      },
+    },
+  };

package/src/ui/speech-synthesizer/animated/index.ts

@@ -0,0 +1,8 @@
+"use client";
+
+export { SpeechSynthesizerAnimated } from "./speech-synthesizer-animated";
+export type {
+  SpeechSynthesizerAnimation,
+  SpeechSynthesizerAnimatedProps,
+} from "./types";
+export { speechSynthesizerAnimationPresets } from "./animations";

package/src/ui/speech-synthesizer/animated/speech-synthesizer-animated.tsx

@@ -0,0 +1,260 @@
+"use client";
+
+import { motion } from "framer-motion";
+import {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from "react";
+
+import { cn } from "../../../lib/utils";
+
+import type { SpeechSynthesizerRef, SpeechSynthesizerState } from "../types";
+import {
+  speechSynthesizerBtnActiveClasses,
+  speechSynthesizerBtnVariants,
+  speechSynthesizerControlsClasses,
+  speechSynthesizerProgressBarClasses,
+  speechSynthesizerProgressClasses,
+  speechSynthesizerTextClasses,
+  speechSynthesizerVariants,
+} from "../variants";
+
+import { speechSynthesizerAnimationPresets } from "./animations";
+import type { SpeechSynthesizerAnimatedProps } from "./types";
+
+function DefaultPlayIcon() {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" className="size-5">
+      <path d="M8 5v14l11-7z" />
+    </svg>
+  );
+}
+
+function DefaultPauseIcon() {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" className="size-5">
+      <rect x="6" y="4" width="4" height="16" />
+      <rect x="14" y="4" width="4" height="16" />
+    </svg>
+  );
+}
+
+function DefaultStopIcon() {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" className="size-5">
+      <rect x="6" y="6" width="12" height="12" />
+    </svg>
+  );
+}
+
+export function SpeechSynthesizerAnimated({
+  appearance,
+  size,
+  text,
+  lang,
+  rate = 1,
+  pitch = 1,
+  volume = 1,
+  autoSpeak = false,
+  onStart,
+  onEnd,
+  onError,
+  onStateChange,
+  renderPlay,
+  renderPause,
+  renderStop,
+  showProgress = false,
+  animation = "pulse",
+  className,
+  children,
+  ...rest
+}: SpeechSynthesizerAnimatedProps) {
+  const [state, setState] = useState<SpeechSynthesizerState>("idle");
+  const utteranceRef = useRef<SpeechSynthesisUtterance | null>(null);
+  const stateRef = useRef<SpeechSynthesizerState>("idle");
+  const preset = speechSynthesizerAnimationPresets[animation];
+
+  const setStateSafe = useCallback(
+    (newState: SpeechSynthesizerState) => {
+      stateRef.current = newState;
+      setState(newState);
+      onStateChange?.(newState);
+    },
+    [onStateChange],
+  );
+
+  const speak = useCallback(() => {
+    if (!text || typeof window === "undefined") return;
+    window.speechSynthesis.cancel();
+
+    const utterance = new SpeechSynthesisUtterance(text);
+    if (lang) utterance.lang = lang;
+    utterance.rate = rate;
+    utterance.pitch = pitch;
+    utterance.volume = volume;
+
+    utterance.onstart = () => {
+      setStateSafe("speaking");
+      onStart?.();
+    };
+    utterance.onend = () => {
+      setStateSafe("idle");
+      onEnd?.();
+    };
+    utterance.onerror = (event) => {
+      setStateSafe("idle");
+      onError?.(event.error);
+    };
+    utterance.onpause = () => setStateSafe("paused");
+    utterance.onresume = () => setStateSafe("speaking");
+
+    utteranceRef.current = utterance;
+    window.speechSynthesis.speak(utterance);
+  }, [text, lang, rate, pitch, volume, onStart, onEnd, onError, setStateSafe]);
+
+  const pauseFn = useCallback(() => {
+    if (typeof window !== "undefined") window.speechSynthesis.pause();
+  }, []);
+
+  const resumeFn = useCallback(() => {
+    if (typeof window !== "undefined") window.speechSynthesis.resume();
+  }, []);
+
+  const stop = useCallback(() => {
+    if (typeof window !== "undefined") window.speechSynthesis.cancel();
+    setStateSafe("idle");
+  }, [setStateSafe]);
+
+  const imperativeHandle: SpeechSynthesizerRef = {
+    speak,
+    pause: pauseFn,
+    resume: resumeFn,
+    stop,
+    get state() {
+      return stateRef.current;
+    },
+  };
+
+  useImperativeHandle((rest as any).ref, () => imperativeHandle, [
+    speak,
+    pauseFn,
+    resumeFn,
+    stop,
+  ]);
+
+  useEffect(() => {
+    if (autoSpeak && text) speak();
+    return () => {
+      if (typeof window !== "undefined") window.speechSynthesis.cancel();
+    };
+  }, []);
+
+  const isSpeaking = state === "speaking";
+  const isPaused = state === "paused";
+  const showPlay = state === "idle" || state === "paused";
+  const showPause = state === "speaking";
+
+  return (
+    <motion.div
+      data-slot="speech-synthesizer"
+      className={cn(speechSynthesizerVariants({ size }), className)}
+      {...(rest as any)}
+    >
+      {text && (
+        <motion.p
+          data-slot="speech-synthesizer-text"
+          className={speechSynthesizerTextClasses}
+          initial="initial"
+          animate={isSpeaking ? "animate" : "initial"}
+          variants={preset.variants}
+          transition={preset.transition}
+        >
+          {text}
+        </motion.p>
+      )}
+      {showProgress && isSpeaking && (
+        <motion.div
+          data-slot="speech-synthesizer-progress"
+          className={speechSynthesizerProgressClasses}
+          initial={{ scaleX: 0 }}
+          animate={{ scaleX: 1 }}
+          transition={{ duration: 0.3 }}
+          style={{ originX: 0 }}
+        >
+          <div
+            data-slot="speech-synthesizer-progress-bar"
+            className={cn(
+              speechSynthesizerProgressBarClasses,
+              "w-full animate-pulse",
+            )}
+          />
+        </motion.div>
+      )}
+      <motion.div
+        data-slot="speech-synthesizer-controls"
+        className={speechSynthesizerControlsClasses}
+      >
+        {showPlay && (
+          <motion.button
+            type="button"
+            data-slot="speech-synthesizer-play-btn"
+            className={cn(
+              speechSynthesizerBtnVariants({ appearance, size }),
+              isPaused && speechSynthesizerBtnActiveClasses,
+            )}
+            onClick={isPaused ? resumeFn : speak}
+            aria-label={isPaused ? "Resume" : "Play"}
+            whileHover={{ scale: 1.1 }}
+            whileTap={{ scale: 0.9 }}
+          >
+            {renderPlay ? (
+              renderPlay({ isSpeaking, isPaused, state })
+            ) : (
+              <DefaultPlayIcon />
+            )}
+          </motion.button>
+        )}
+        {showPause && (
+          <motion.button
+            type="button"
+            data-slot="speech-synthesizer-pause-btn"
+            className={speechSynthesizerBtnVariants({ appearance, size })}
+            onClick={pauseFn}
+            aria-label="Pause"
+            whileHover={{ scale: 1.1 }}
+            whileTap={{ scale: 0.9 }}
+          >
+            {renderPause ? (
+              renderPause({ isSpeaking, isPaused, state })
+            ) : (
+              <DefaultPauseIcon />
+            )}
+          </motion.button>
+        )}
+        {(isSpeaking || isPaused) && (
+          <motion.button
+            type="button"
+            data-slot="speech-synthesizer-stop-btn"
+            className={speechSynthesizerBtnVariants({ appearance, size })}
+            onClick={stop}
+            aria-label="Stop"
+            whileHover={{ scale: 1.1 }}
+            whileTap={{ scale: 0.9 }}
+          >
+            {renderStop ? (
+              renderStop({ isSpeaking, isPaused, state })
+            ) : (
+              <DefaultStopIcon />
+            )}
+          </motion.button>
+        )}
+      </motion.div>
+      {children}
+    </motion.div>
+  );
+}
+
+SpeechSynthesizerAnimated.displayName = "SpeechSynthesizerAnimated";

package/src/ui/speech-synthesizer/animated/types.ts

@@ -0,0 +1,11 @@
+import type { Ref } from "react";
+
+import type { SpeechSynthesizerBaseProps } from "../types";
+import type { SpeechSynthesizerAnimation } from "./animations";
+
+export type { SpeechSynthesizerAnimation };
+
+export type SpeechSynthesizerAnimatedProps = SpeechSynthesizerBaseProps & {
+  animation?: SpeechSynthesizerAnimation;
+  ref?: Ref<HTMLDivElement>;
+};

package/src/ui/speech-synthesizer/index.ts

@@ -0,0 +1,14 @@
+"use client";
+
+export { SpeechSynthesizer } from "./speech-synthesizer";
+export type {
+  SpeechSynthesizerBaseProps,
+  SpeechSynthesizerProps,
+  SpeechSynthesizerRef,
+  SpeechSynthesizerState,
+  SpeechSynthesizerVariantProps,
+} from "./types";
+export {
+  speechSynthesizerBtnVariants,
+  speechSynthesizerVariants,
+} from "./variants";