@arkyn/components 3.0.1-beta.12 → 3.0.1-beta.13

package/package.json

@@ -1,42 +1,44 @@
 {
   "name": "@arkyn/components",
-  "version": "3.0.1-beta.12",
+  "version": "3.0.1-beta.13",
   "main": "./dist/bundle.js",
   "types": "./dist/index.d.ts",
-  "author": "Lucas Gonçalves",
   "type": "module",
   "private": false,
+  "license": "Apache-2.0",
+  "author": "Arkyn | Lucas Gonçalves",
+  "description": "Arkyn's component library for Remix applications.",
   "scripts": {
+    "dev": "bunx vite --config documentation/vite.config.ts",
     "build": "bunx vite build && tsc",
     "typecheck": "bunx tsc --project tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@react-google-maps/api": ">=2.20.6",
-    "@react-input/mask": ">=1.2.15",
-    "@vitejs/plugin-react": ">=4.4.1",
-    "framer-motion": ">=11.18.2",
-    "html-react-parser": ">=5.2.2",
-    "is-hotkey": ">=0.2.0",
-    "lucide-react": ">=0.424.0",
-    "react-hot-toast": ">=2.5.2",
-    "react-scroll": ">=1.9.3",
-    "slate": ">=0.103.0",
-    "slate-history": ">=0.109.0",
-    "slate-react": ">=0.110.3"
+    "@react-google-maps/api": "^2.20.7",
+    "@react-input/mask": "^1.2.15",
+    "framer-motion": "^11.18.2",
+    "html-react-parser": "^5.2.6",
+    "is-hotkey": "^0.2.0",
+    "react-hot-toast": "^2.6.0",
+    "react-scroll": "^1.9.3",
+    "slate": "^0.103.0",
+    "slate-history": "^0.109.0",
+    "slate-react": "^0.110.3"
   },
   "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0",
-    "react-router": ">=7.6.0"
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router": "^7.6.2",
+    "lucide-react": "^0.424.0"
   },
   "devDependencies": {
-    "@arkyn/types": "^2.2.3",
     "@types/is-hotkey": "^0.1.10",
-    "@types/react": "^18.3.20",
-    "@types/react-dom": "^18.3.5",
-    "@types/react-scroll": "^1.8.10",
+    "@types/react": "^18.3.23",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^4.7.0",
     "bun-types": "latest",
-    "typescript": "^5.8.2",
-    "vite": "^5.4.15"
+    "globals": "^15.15.0",
+    "typescript": "^5.9.2",
+    "vite": "^5.4.19"
   }
 }

package/src/components/alert/alertContainer/index.tsx

@@ -0,0 +1,87 @@
+import { createContext, HTMLAttributes, ReactNode, useContext } from "react";
+import { AlertTitle } from "../alertTitle";
+import "./styles.css";
+
+type AlertContainerProps = {
+  schema: "success" | "danger" | "warning" | "info";
+} & HTMLAttributes<HTMLDivElement>;
+
+const AlertContainerContext = createContext({} as AlertContainerProps);
+
+function useAlertContainer() {
+  return useContext(AlertContainerContext);
+}
+
+/**
+ * AlertContainer component - used to display alert messages with different schemas
+ *
+ * @param props - AlertContainer component properties
+ * @param props.schema - Alert color scheme and semantic meaning: "success" | "danger" | "warning" | "info"
+ *
+ * **...Other valid HTML properties for div**
+ *
+ * @returns AlertContainer JSX element with context provider
+ *
+ * @example
+ * ```tsx
+ * // Basic alert
+ * <AlertContainer schema="info">
+ *   Alert message content
+ * </AlertContainer>
+ *
+ * // Success alert
+ * <AlertContainer schema="success">
+ *   Operation completed successfully!
+ * </AlertContainer>
+ *
+ * // Alert with title
+ * <AlertContainer schema="warning">
+ *   <AlertTitle>Warning</AlertTitle>
+ *   Please check your input data.
+ * </AlertContainer>
+ *
+ * // Danger alert
+ * <AlertContainer schema="danger">
+ *   <AlertTitle>Error</AlertTitle>
+ *   Something went wrong. Please try again.
+ * </AlertContainer>
+ * ```
+ */
+
+function AlertContainer(props: AlertContainerProps) {
+  const { schema, children, className: baseClassName, ...rest } = props;
+
+  const hasAlertTitle = (children: ReactNode): boolean => {
+    let found = false;
+    const searchForAlertTitle = (nodes: ReactNode) => {
+      if (Array.isArray(nodes)) {
+        nodes.forEach(searchForAlertTitle);
+      } else if (nodes && typeof nodes === "object" && "type" in nodes) {
+        if (nodes.type === AlertTitle) {
+          found = true;
+        } else if (nodes.props && nodes.props.children) {
+          searchForAlertTitle(nodes.props.children);
+        }
+      }
+    };
+    searchForAlertTitle(children);
+    return found;
+  };
+
+  const shouldAlignCenter = !hasAlertTitle(children);
+  const finalClassName = shouldAlignCenter
+    ? "nonExistsAlertTitle"
+    : "existsAlertTitle";
+
+  const className = `arkynAlertContainer ${schema} ${finalClassName} ${baseClassName}`;
+
+  return (
+    <AlertContainerContext.Provider value={props}>
+      <div className={className.trim()} {...rest}>
+        {children}
+      </div>
+    </AlertContainerContext.Provider>
+  );
+}
+
+export { AlertContainer, useAlertContainer };

package/src/components/alert/alertContainer/styles.css

@@ -0,0 +1,33 @@
+.arkynAlertContainer {
+  display: flex;
+  align-items: start;
+  gap: 16px;
+  padding: 16px;
+
+  border: 1px solid transparent;
+  border-radius: 6px;
+}
+
+.arkynAlertContainer.nonExistsAlertTitle {
+  align-items: center;
+}
+
+.arkynAlertContainer.danger {
+  background: rgba(var(--spotlight-danger), 0.1);
+  border-color: rgba(var(--spotlight-danger), 0.4);
+}
+
+.arkynAlertContainer.success {
+  background: rgba(var(--spotlight-success), 0.1);
+  border-color: rgba(var(--spotlight-success), 0.4);
+}
+
+.arkynAlertContainer.info {
+  background: rgba(var(--spotlight-info), 0.1);
+  border-color: rgba(var(--spotlight-info), 0.4);
+}
+
+.arkynAlertContainer.warning {
+  background: rgba(var(--spotlight-warning), 0.1);
+  border-color: rgba(var(--spotlight-warning), 0.4);
+}

package/src/components/alert/alertContent/index.tsx

@@ -0,0 +1,53 @@
+import { HTMLAttributes } from "react";
+import "./styles.css";
+
+type AlertContentProps = HTMLAttributes<HTMLDivElement>;
+
+/**
+ * AlertContent component - used to wrap and style the main content area of alerts
+ *
+ * @param props - AlertContent component properties
+ *
+ * **...Other valid HTML properties for div**
+ *
+ * @returns AlertContent JSX element
+ *
+ * @example
+ * ```tsx
+ * // Basic alert content
+ * <AlertContainer schema="info">
+ *   <AlertContent>
+ *     This is the main alert message content.
+ *   </AlertContent>
+ * </AlertContainer>
+ *
+ * // Alert with title and content
+ * <AlertContainer schema="success">
+ *   <AlertContent>
+ *     <AlertTitle>Success</AlertTitle>
+ *     Your operation has been completed successfully.
+ *   </AlertContent>
+ * </AlertContainer>
+ *
+ * // Multiple content sections
+ * <AlertContainer schema="warning">
+ *   <AlertContent>
+ *     <AlertTitle>Warning</AlertTitle>
+ *     <p>Please review the following items:</p>
+ *     <ul>
+ *       <li>Check your input data</li>
+ *       <li>Verify permissions</li>
+ *     </ul>
+ *   </AlertContent>
+ * </AlertContainer>
+ * ```
+ */
+
+function AlertContent(props: AlertContentProps) {
+  const { className: baseClassName, ...rest } = props;
+  const className = `arkynAlertContent ${baseClassName}`;
+
+  return <div className={className.trim()} {...rest} />;
+}
+
+export { AlertContent };

package/src/components/alert/alertDescription/index.tsx

@@ -0,0 +1,57 @@
+import { HTMLAttributes } from "react";
+import "./styles.css";
+
+type AlertDescriptionProps = HTMLAttributes<HTMLDivElement>;
+
+/**
+ * AlertDescription component - used to display additional descriptive text in alerts
+ *
+ * @param props - AlertDescription component properties
+ *
+ * **...Other valid HTML properties for div**
+ *
+ * @returns AlertDescription JSX element
+ *
+ * @example
+ * ```tsx
+ * // Basic alert with description
+ * <AlertContainer schema="info">
+ *   <AlertContent>
+ *     <AlertTitle>Information</AlertTitle>
+ *     <AlertDescription>
+ *       This is additional information to help you understand the context.
+ *     </AlertDescription>
+ *   </AlertContent>
+ * </AlertContainer>
+ *
+ * // Success alert with description
+ * <AlertContainer schema="success">
+ *   <AlertContent>
+ *     <AlertTitle>Upload Complete</AlertTitle>
+ *     <AlertDescription>
+ *       Your file has been successfully uploaded and processed.
+ *     </AlertDescription>
+ *   </AlertContent>
+ * </AlertContainer>
+ *
+ * // Warning with detailed description
+ * <AlertContainer schema="warning">
+ *   <AlertContent>
+ *     <AlertTitle>Storage Limit</AlertTitle>
+ *     <AlertDescription>
+ *       You have used 90% of your storage quota. Consider upgrading your plan
+ *       or removing unused files.
+ *     </AlertDescription>
+ *   </AlertContent>
+ * </AlertContainer>
+ * ```
+ */
+
+function AlertDescription(props: AlertDescriptionProps) {
+  const { className: baseClassName, ...rest } = props;
+  const className = `arkynAlertDescription ${baseClassName}`;
+
+  return <div className={className.trim()} {...rest} />;
+}
+
+export { AlertDescription };

package/src/components/alert/alertIcon/index.tsx

@@ -0,0 +1,79 @@
+import {
+  AlertTriangle,
+  CheckCircle2,
+  Info,
+  LucideProps,
+  XCircle,
+} from "lucide-react";
+
+import { useAlertContainer } from "../alertContainer";
+import "./styles.css";
+
+type AlertIconProps = LucideProps;
+
+/**
+ * AlertIcon component - automatically displays the appropriate icon based on the alert schema
+ *
+ * @param props - AlertIcon component properties
+ *
+ * **...Other valid Lucide icon properties**
+ *
+ * @returns AlertIcon JSX element with schema-specific icon
+ *
+ * @description
+ * This component automatically selects and renders the appropriate icon based on the
+ * AlertContainer's schema context:
+ * - success: CheckCircle2 icon
+ * - danger: XCircle icon
+ * - warning: AlertTriangle icon
+ * - info: Info icon
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - icon automatically matches container schema
+ * <AlertContainer schema="success">
+ *   <AlertIcon />
+ *   <AlertContent>
+ *     <AlertTitle>Success</AlertTitle>
+ *     <AlertDescription>Operation completed successfully.</AlertDescription>
+ *   </AlertContent>
+ * </AlertContainer>
+ *
+ * // Warning alert with icon
+ * <AlertContainer schema="warning">
+ *   <AlertIcon />
+ *   <AlertContent>
+ *     Please review your input before proceeding.
+ *   </AlertContent>
+ * </AlertContainer>
+ *
+ * // Custom icon size
+ * <AlertContainer schema="danger">
+ *   <AlertIcon size={24} />
+ *   <AlertContent>
+ *     <AlertTitle>Error</AlertTitle>
+ *     <AlertDescription>Something went wrong.</AlertDescription>
+ *   </AlertContent>
+ * </AlertContainer>
+ * ```
+ */
+
+function AlertIcon(props: AlertIconProps) {
+  const { className: baseClassName, ...rest } = props;
+  const { schema } = useAlertContainer();
+
+  const className = `arkynAlertIcon ${schema} ${baseClassName}`;
+
+  switch (schema) {
+    case "success":
+      return <CheckCircle2 className={className} {...rest} />;
+    case "danger":
+      return <XCircle className={className} {...rest} />;
+    case "warning":
+      return <AlertTriangle className={className} {...rest} />;
+    case "info":
+      return <Info className={className} {...rest} />;
+  }
+}
+
+export { AlertIcon };

package/src/components/alert/alertTitle/index.tsx

@@ -0,0 +1,54 @@
+import { HTMLAttributes } from "react";
+import "./styles.css";
+
+type AlertTitleProps = HTMLAttributes<HTMLDivElement>;
+
+/**
+ * AlertTitle component - used to display the main title/heading of alerts
+ *
+ * @param props - AlertTitle component properties
+ *
+ * **...Other valid HTML properties for div**
+ *
+ * @returns AlertTitle JSX element
+ *
+ * @description
+ * This component affects the layout of the AlertContainer. When present, the container
+ * content will be aligned differently compared to alerts without a title.
+ *
+ * @example
+ * ```tsx
+ * // Basic alert with title
+ * <AlertContainer schema="info">
+ *   <AlertTitle>Information</AlertTitle>
+ *   <AlertDescription>This is important information.</AlertDescription>
+ * </AlertContainer>
+ *
+ * // Success alert with title and icon
+ * <AlertContainer schema="success">
+ *   <AlertIcon />
+ *   <AlertTitle>Success!</AlertTitle>
+ *   <AlertDescription>Your operation was completed.</AlertDescription>
+ * </AlertContainer>
+ *
+ * // Error alert with custom styling
+ * <AlertContainer schema="danger">
+ *   <AlertIcon />
+ *   <AlertTitle className="custom-title">
+ *     Critical Error
+ *   </AlertTitle>
+ *   <AlertDescription>
+ *     Please contact support immediately.
+ *   </AlertDescription>
+ * </AlertContainer>
+ * ```
+ */
+
+function AlertTitle(props: AlertTitleProps) {
+  const { className: baseClassName, ...rest } = props;
+  const className = `arkynAlertTitle ${baseClassName}`;
+
+  return <div className={className.trim()} {...rest} />;
+}
+
+export { AlertTitle };

package/src/components/audioPlayer/index.tsx

@@ -0,0 +1,187 @@
+import { Pause, Play } from "lucide-react";
+import { AudioHTMLAttributes, useEffect, useRef, useState } from "react";
+
+import { useSlider } from "../../hooks/useSlider";
+import { Slider } from "../slider";
+import "./styles.css";
+
+type AudioInformationProps = {
+  currentTime: number;
+  totalTime: number;
+  formattedCurrentTime: string;
+  formattedTotalTime: string;
+};
+
+type AudioPlayerProps = Omit<
+  AudioHTMLAttributes<HTMLAudioElement>,
+  "onEnded" | "src"
+> & {
+  src: string;
+  disabled?: boolean;
+  onPlayAudio?: (props: AudioInformationProps) => void;
+  onPauseAudio?: (props: AudioInformationProps) => void;
+};
+
+/**
+ * AudioPlayer component - used to play audio files with playback controls
+ *
+ * @param props - AudioPlayer component properties
+ * @param props.src - Audio source URL (required)
+ * @param props.disabled - Whether the audio player is disabled. Default: false
+ * @param props.onPlayAudio - Callback function called when audio starts playing
+ * @param props.onPauseAudio - Callback function called when audio is paused
+ *
+ * **...Other valid HTML audio properties**
+ *
+ * @returns AudioPlayer JSX element
+ *
+ * @example
+ * ```tsx
+ * // Basic audio player
+ * <AudioPlayer src="/audio/sample.mp3" />
+ *
+ * // Audio player with callbacks
+ * <AudioPlayer
+ *   src="/audio/sample.mp3"
+ *   onPlayAudio={(info) => console.log('Playing:', info)}
+ *   onPauseAudio={(info) => console.log('Paused:', info)}
+ * />
+ *
+ * // Disabled audio player
+ * <AudioPlayer
+ *   src="/audio/sample.mp3"
+ *   disabled
+ * />
+ *
+ * // Audio player with additional HTML audio attributes
+ * <AudioPlayer
+ *   src="/audio/sample.mp3"
+ *   loop
+ *   preload="metadata"
+ *   onPlayAudio={(info) => {
+ *     console.log(`Current: ${info.formattedCurrentTime}`);
+ *     console.log(`Total: ${info.formattedTotalTime}`);
+ *   }}
+ * />
+ * ```
+ */
+
+function AudioPlayer(props: AudioPlayerProps) {
+  const { onPlayAudio, onPauseAudio, disabled, ...rest } = props;
+
+  const [sliderValue, setSliderValue] = useSlider(0);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [isDragging, setIsDragging] = useState(false);
+
+  const audioReference = useRef<HTMLAudioElement>(null);
+
+  const currentTime = audioReference.current?.currentTime;
+  const totalTime = audioReference.current?.duration;
+
+  const formattedCurrentTime = formatTime(currentTime);
+  const formattedTotalTime = formatTime(totalTime);
+
+  const audioInformation: AudioInformationProps = {
+    totalTime,
+    currentTime,
+    formattedCurrentTime,
+    formattedTotalTime,
+  };
+
+  function formatTime(time?: number) {
+    if (!time) return "00:00";
+
+    const minutes = Math.floor(time / 60);
+    const seconds = Math.floor(time % 60);
+
+    const formattedMinutes = String(minutes).padStart(2, "0");
+    const formattedSeconds = String(seconds).padStart(2, "0");
+
+    return `${formattedMinutes}:${formattedSeconds}`;
+  }
+
+  function handlePlayAudio() {
+    const audioElement = audioReference.current;
+    if (!audioElement) return;
+    if (props.onPlayAudio) props.onPlayAudio(audioInformation);
+    audioElement.play();
+    setIsPlaying(true);
+  }
+
+  function handlePauseAudio() {
+    const audioElement = audioReference.current;
+    if (!audioElement) return;
+    if (props.onPauseAudio) props.onPauseAudio(audioInformation);
+    audioElement.pause();
+    setIsPlaying(false);
+  }
+
+  function handleToggleAudio() {
+    if (isPlaying) handlePauseAudio();
+    else handlePlayAudio();
+  }
+
+  function handleSliderChange(value: number) {
+    const audioElement = audioReference.current;
+    if (!audioElement) return;
+
+    const totalTime = audioElement.duration;
+    const currentTime = (value / 100) * totalTime;
+
+    audioElement.currentTime = currentTime;
+  }
+
+  if (isDragging || !isPlaying) {
+    audioReference.current?.pause();
+  } else if (isPlaying) {
+    audioReference.current?.play();
+  }
+
+  useEffect(() => {
+    const audioElement = audioReference.current;
+    if (!audioElement) return;
+
+    const handleTimeUpdate = () => {
+      const totalTime = audioElement.duration;
+      const currentTime = audioElement.currentTime;
+
+      const value = (currentTime / totalTime) * 100;
+      setSliderValue(value);
+    };
+
+    audioElement.addEventListener("timeupdate", handleTimeUpdate);
+
+    return () => {
+      audioElement.removeEventListener("timeupdate", handleTimeUpdate);
+    };
+  }, []);
+
+  return (
+    <div className="arkynAudioPlayer">
+      <audio
+        {...rest}
+        ref={audioReference}
+        src={props.src}
+        onEnded={handlePauseAudio}
+      />
+
+      <button type="button" disabled={disabled} onClick={handleToggleAudio}>
+        {isPlaying && <Pause />}
+        {!isPlaying && <Play />}
+      </button>
+
+      <p>{formattedCurrentTime}</p>
+
+      <Slider
+        value={sliderValue}
+        onChange={handleSliderChange}
+        onDragging={setIsDragging}
+        disabled={disabled}
+      />
+
+      <p>{formattedTotalTime}</p>
+    </div>
+  );
+}
+
+export { AudioPlayer };

package/src/components/audioPlayer/styles.css

@@ -0,0 +1,50 @@
+.arkynAudioPlayer {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.arkynAudioPlayer button {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  border: none;
+  border-radius: 50%;
+
+  min-height: 40px;
+  min-width: 40px;
+  max-height: 40px;
+  max-width: 40px;
+
+  background-color: rgba(var(--spotlight-primary), 1);
+}
+
+.arkynAudioPlayer button:hover:not(:disabled) {
+  cursor: pointer;
+  background-color: rgba(var(--spotlight-primary), 0.8);
+}
+
+.arkynAudioPlayer button:disabled {
+  cursor: not-allowed;
+  opacity: 0.2;
+}
+
+.arkynAudioPlayer button svg {
+  fill: #fff;
+  stroke: #fff;
+
+  min-height: 20px;
+  min-width: 20px;
+  max-height: 20px;
+  max-width: 20px;
+}
+
+.arkynAudioPlayer p {
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 12px;
+  text-align: left;
+  color: var(--text-body);
+  user-select: none;
+}