feat: intelligent content auto-detection for SocialShareButton

package.json

@@ -8,14 +8,16 @@
     "src/social-share-button.css",
     "src/social-share-button-react.jsx",
     "src/social-share-analytics.js",
+    "src/utils/extractContent.js",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "lint": "eslint src/**/*.{js,jsx} --max-warnings=0",
     "lint:fix": "eslint src/**/*.{js,jsx} --fix",
     "format": "prettier --write \"**/*.{js,jsx,json,css,md,html}\"",
-    "format:check": "prettier --check \"**/*.{js,jsx,json,css,md,html}\""
+    "format:check": "prettier --check \"**/*.{js,jsx,json,css,md,html}\"",
+    "test": "node --test tests/**/*.test.js"
   },
   "repository": {
     "type": "git",
@@ -44,6 +46,7 @@
     "@eslint/js": "^9.39.4",
     "eslint": "^9.39.4",
     "globals": "^17.4.0",
+    "jsdom": "^28.1.0",
     "prettier": "^3.2.4"
   },
   "type": "module"

src/social-share-button-react.jsx

@@ -1,51 +1,54 @@
-import { useEffect, useRef } from "react";
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+// Import SocialShareButton directly for ESM bundles, fall back to window for CDN
+import SocialShareButtonCore from './social-share-button.js';
 
 export const SocialShareButton = ({
   url,
   title,
-  description = "",
+  description,
   hashtags = [],
-  via = "",
-  platforms = [
-    "whatsapp",
-    "facebook",
-    "twitter",
-    "linkedin",
-    "telegram",
-    "reddit",
-  ],
-  theme = "dark",
-  buttonText = "Share",
-  customClass = "",
+  via = '',
+  platforms = ['whatsapp', 'facebook', 'twitter', 'linkedin', 'telegram', 'reddit'],
+  theme = 'dark',
+  buttonText = 'Share',
+  customClass = '',
   onShare = null,
   onCopy = null,
-  buttonStyle = "default",
-  modalPosition = "center",
+  buttonStyle = 'default',
+  modalPosition = 'center',
+  // Content auto-detection — set to false when all props are always provided.
+  autoDetect = true,
   // Analytics props — the library itself never collects data.
   // Provide any combination to connect your own analytics tools.
-  analytics = true,        // set to false to disable all event emission
-  onAnalytics = null,      // (payload) => void — direct callback hook
-  analyticsPlugins = [],   // array of adapter instances (see social-share-analytics.js)
-  componentId = null,      // optional string identifier for this instance
-  debug = false,           // log events to console during development
+  analytics = true, // set to false to disable all event emission
+  onAnalytics = null, // (payload) => void — direct callback hook
+  analyticsPlugins = [], // array of adapter instances (see social-share-analytics.js)
+  componentId = null, // optional string identifier for this instance
+  debug = false, // log events to console during development
 }) => {
   const containerRef = useRef(null);
   const shareButtonRef = useRef(null);
 
-  // Auto-detect current URL and title if not provided
-  const currentUrl =
-    url || (typeof window !== "undefined" ? window.location.href : "");
-  const currentTitle =
-    title || (typeof document !== "undefined" ? document.title : "");
+  // Resolve URL — fall back to current page URL but leave title/description
+  // undefined when not provided so the core SocialShareButton auto-detection
+  // priority chain (og:title → twitter:title → h1 → document.title etc.) runs.
+  const currentUrl = url || (typeof window !== 'undefined' ? window.location.href : '');
 
   useEffect(() => {
     if (containerRef.current && !shareButtonRef.current) {
-      if (typeof window !== "undefined" && window.SocialShareButton) {
-        shareButtonRef.current = new window.SocialShareButton({
+      // Use imported class for ESM bundles, fall back to window for CDN script tags
+      const ShareButtonConstructor =
+        SocialShareButtonCore || (typeof window !== 'undefined' ? window.SocialShareButton : null);
+
+      if (ShareButtonConstructor) {
+        // Only include title/description in the options object when explicitly
+        // provided — omitting them lets the core detector's priority chain run.
+        const initOptions = {
           container: containerRef.current,
           url: currentUrl,
-          title: currentTitle,
-          description,
           hashtags,
           via,
           platforms,
@@ -56,12 +59,16 @@ export const SocialShareButton = ({
           onCopy,
           buttonStyle,
           modalPosition,
+          autoDetect,
           analytics,
           onAnalytics,
           analyticsPlugins,
           componentId,
           debug,
-        });
+        };
+        if (title !== undefined) initOptions.title = title;
+        if (description !== undefined) initOptions.description = description;
+        shareButtonRef.current = new ShareButtonConstructor(initOptions);
       }
     }
 
@@ -73,13 +80,29 @@ export const SocialShareButton = ({
     };
   }, []);
 
-  // Update options when props change (including URL from route changes)
+  // Update options when props change (including URL from route changes).
+  // Also bust the content-detection cache so the new page's metadata is used.
   useEffect(() => {
     if (shareButtonRef.current) {
-      shareButtonRef.current.updateOptions({
+      // Invalidate detection cache on every route/prop change so the new
+      // page content is picked up when autoDetect is enabled.
+      if (autoDetect) {
+        const ShareButtonConstructor =
+          SocialShareButtonCore ||
+          (typeof window !== 'undefined' ? window.SocialShareButton : null);
+
+        if (
+          ShareButtonConstructor &&
+          typeof ShareButtonConstructor.clearContentCache === 'function'
+        ) {
+          // Pass the current URL so only this page's cache entry is cleared,
+          // rather than wiping the entire global cache shared across instances.
+          ShareButtonConstructor.clearContentCache(currentUrl);
+        }
+      }
+
+      const updateOpts = {
         url: currentUrl,
-        title: currentTitle,
-        description,
         hashtags,
         via,
         platforms,
@@ -90,16 +113,20 @@ export const SocialShareButton = ({
         onCopy,
         buttonStyle,
         modalPosition,
+        autoDetect,
         analytics,
         onAnalytics,
         analyticsPlugins,
         componentId,
         debug,
-      });
+      };
+      if (title !== undefined) updateOpts.title = title;
+      if (description !== undefined) updateOpts.description = description;
+      shareButtonRef.current.updateOptions(updateOpts);
     }
   }, [
     currentUrl,
-    currentTitle,
+    title,
     description,
     hashtags,
     via,
@@ -111,6 +138,7 @@ export const SocialShareButton = ({
     onCopy,
     buttonStyle,
     modalPosition,
+    autoDetect,
     analytics,
     onAnalytics,
     analyticsPlugins,