Fix: improved UI and accessibility of social share button

.github/copilot/integrate-analytics.prompt.md

@@ -83,6 +83,23 @@ new SocialShareButton({
 
 Load the adapters file **in addition to** the main library script:
 
+### Optional analytics control APIs
+
+```js
+// Runtime option updates, inspector-safe history, and manual reset
+shareButton.setAnalyticsOptions({
+  sampleRate: 0.3,
+  dedupeWindow: 1500,
+  dedupeBy: ["eventName", "platform", "url"],
+  historyLimit: 200,
+  enrichContext: true,
+  includeUserAgent: false,
+});
+
+console.log(shareButton.getAnalyticsHistory());
+shareButton.clearAnalyticsHistory();
+```
+
 ```html
 <!-- After the main social-share-button.js script tag -->
 <!-- CDN (pick whichever tag version ships this file): -->
@@ -98,6 +115,12 @@ const { GoogleAnalyticsAdapter, MixpanelAdapter } = window.SocialShareAnalytics;
 new SocialShareButton({
   container: "#share-button",
   analyticsPlugins: [new GoogleAnalyticsAdapter(), new MixpanelAdapter()],
+  analyticsOptions: {
+    sampleRate: 0.5, // send 50% of events
+    dedupeWindow: 3000, // prevent duplicate events within 3 seconds
+    enrichContext: true,
+    includeUserAgent: false,
+  },
 });
 ```
 
@@ -183,6 +206,28 @@ new SocialShareButton({
 // Calls: posthog.capture(eventName, { platform, url, ... })
 ```
 
+### Google Tag Manager (dataLayer)
+
+```js
+const { GoogleTagManagerAdapter } = window.SocialShareAnalytics;
+new SocialShareButton({
+  container: "#share-button",
+  analyticsPlugins: [new GoogleTagManagerAdapter()],
+});
+// Calls: dataLayer.push({ event: eventName, ...payload })
+```
+
+### Console (debug adapter)
+
+```js
+const { ConsoleAdapter } = window.SocialShareAnalytics;
+new SocialShareButton({
+  container: "#share-button",
+  analyticsPlugins: [new ConsoleAdapter()],
+});
+// Calls: console.info("[SocialShareButton Analytics][ConsoleAdapter]", payload)
+```
+
 ### Custom / inline function
 
 Wrap any one-off function without subclassing:

.github/copilot/integrate-social-share-button.prompt.md

@@ -440,6 +440,7 @@ function App() {
 | `onShare`          | function       | `null`                 | `(platform, url) => void`                                  |
 | `onCopy`           | function       | `null`                 | `(url) => void`                                            |
 | `analytics`        | boolean        | `true`                 | Set `false` to disable all event emission                  |
+| `analyticsOptions` | object         | `{}`                   | Advanced analytics controls: `sampleRate`, `filter`, `dedupeWindow`, `dedupeBy`, `historyLimit`, `enrichContext`, `includeUserAgent` |
 | `onAnalytics`      | function       | `null`                 | `(payload) => void` — direct analytics hook                |
 | `analyticsPlugins` | array          | `[]`                   | Adapter instances from `social-share-analytics.js`         |
 | `componentId`      | string         | `null`                 | Label this instance for analytics tracking                 |

README.md

@@ -111,6 +111,39 @@ No matter which framework you use, integration always follows the same 3 steps:
 
 > 💡 Pick your framework below for the full copy-paste snippet:
 
+## Analytics events (built-in privacy-first observability)
+
+`SocialShareButton` emits a standard event payload for every animation step, click, copy, and error. Electrify your GSOC demo by showing how to connect this to your own analytics stack with zero data collection on the library side.
+
+- `analyticsOptions`: configure sampling, dedupe, enrichment, and history
+- `eventId`: unique ID for every analytics payload to support traceability
+- `getAnalyticsHistory()`: inspect the last `historyLimit` events
+- `clearAnalyticsHistory()`: reset internal debug buffer
+
+```js
+const shareButton = new SocialShareButton({
+  container: "#share-button",
+  analyticsOptions: {
+    sampleRate: 0.6,                // keep volume down in load tests
+    dedupeWindow: 3000,             // suppress duplicate clicks in short windows
+    dedupeBy: ["eventName", "platform","url"],
+    historyLimit: 150,
+    enrichContext: true,
+    includeUserAgent: false,
+  },
+  analyticsPlugins: [new ConsoleAdapter()],
+  onAnalytics: (payload) => {
+    // custom filtering + forwarding
+    if (payload.eventName !== "social_share_popup_open") {
+      sendTelemetry(payload);
+    }
+  },
+});
+
+console.log(shareButton.getAnalyticsHistory());
+shareButton.clearAnalyticsHistory();
+```
+
 <details>
 <summary><b>📦 Create React App</b></summary>
 

src/social-share-analytics.js

@@ -241,6 +241,42 @@ class PostHogAdapter extends SocialShareAnalyticsPlugin {
   }
 }
 
+// -----------------------------------------------------------------------------
+// Google Tag Manager (DataLayer)
+// Requires: window.dataLayer exists. Uses dataLayer.push({ event, ...props }).
+// Docs: https://developers.google.com/tag-manager/devguide
+// -----------------------------------------------------------------------------
+class GoogleTagManagerAdapter extends SocialShareAnalyticsPlugin {
+  track(payload) {
+    if (typeof window === "undefined" || !Array.isArray(window.dataLayer)) {
+      return;
+    }
+    window.dataLayer.push({
+      event: payload.eventName,
+      source: payload.source,
+      interactionType: payload.interactionType,
+      platform: payload.platform,
+      url: payload.url,
+      title: payload.title,
+      componentId: payload.componentId,
+      timestamp: payload.timestamp,
+      ...(payload.errorMessage ? { errorMessage: payload.errorMessage } : {}),
+      ...(payload.context ? { context: payload.context } : {}),
+    });
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Console Adapter
+// Lightweight adapter for development / quick debugging.
+// -----------------------------------------------------------------------------
+class ConsoleAdapter extends SocialShareAnalyticsPlugin {
+  track(payload) {
+    // eslint-disable-next-line no-console
+    console.info("[SocialShareButton Analytics][ConsoleAdapter]", payload);
+  }
+}
+
 // -----------------------------------------------------------------------------
 // Custom / Callback Adapter
 // Use this adapter to wrap any inline function without subclassing.
@@ -278,6 +314,8 @@ const adapters = {
   SegmentAdapter,
   PlausibleAdapter,
   PostHogAdapter,
+  GoogleTagManagerAdapter,
+  ConsoleAdapter,
   CustomAdapter,
 };
 

src/social-share-button.js

@@ -38,6 +38,7 @@ class SocialShareButton {
       // Analytics — the library emits events but never collects or sends data itself.
       // Website owners wire up their own analytics tools via these options.
       analytics: options.analytics !== false, // set to false to disable all event emission
+      analyticsOptions: options.analyticsOptions || {}, // advanced analytics controls: sampleRate, filter, dedupeWindow, enrichContext
       onAnalytics: options.onAnalytics || null, // callback: (payload) => void
       analyticsPlugins: options.analyticsPlugins || [], // array of { track(payload) } adapters
       componentId: options.componentId || null, // optional identifier for this instance
@@ -58,6 +59,8 @@ class SocialShareButton {
     this.ownsBodyLock = false; // Track if this instance owns the body overflow lock
     this.eventsAttached = false; // Guard against multiple attachEvents() calls
     this.isDestroyed = false; // Track if instance has been destroyed (prevents async callbacks)
+    this._lastAnalyticsEvent = null; // For optional analytics dedupe by eventKey/time window
+    this.analyticsHistory = []; // keep a local rolling history of emitted events
 
     if (this.options.container) {
       this.init();
@@ -689,6 +692,40 @@ class SocialShareButton {
       : this.options.container;
   }
 
+  /**
+   * Generates a short unique event ID for each emitted analytics event.
+   * @returns {string}
+   */
+  _generateEventId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+  }
+
+  /**
+   * Update analytics options at runtime (includes dedupe settings, sampling).
+   * @param {Object} opts
+   */
+  setAnalyticsOptions(opts = {}) {
+    this.options.analyticsOptions = {
+      ...this.options.analyticsOptions,
+      ...opts,
+    };
+  }
+
+  /**
+   * Returns a read-only copy of the event history buffer.
+   * @returns {Array<Object>}
+   */
+  getAnalyticsHistory() {
+    return [...this.analyticsHistory];
+  }
+
+  /**
+   * Clears tracked analytics event history.
+   */
+  clearAnalyticsHistory() {
+    this.analyticsHistory = [];
+  }
+
   /**
    * Logs analytics warnings only when debug mode is enabled.
    * @param {string} message - Description of the failed analytics path.
@@ -725,9 +762,12 @@ class SocialShareButton {
   _emit(eventName, interactionType, extra = {}) {
     if (this.options.analytics === false) return;
 
+    const analyticsOptions = this.options.analyticsOptions || {};
+
     const payload = {
       version: ANALYTICS_SCHEMA_VERSION,
       source: "social-share-button",
+      eventId: this._generateEventId(),
       eventName,
       interactionType,
       platform: extra.platform || null,
@@ -741,6 +781,67 @@ class SocialShareButton {
       payload.errorMessage = extra.errorMessage;
     }
 
+    // Analytics sample rate and filtering
+    const sampleRate = Number(analyticsOptions.sampleRate || 1);
+    if (sampleRate <= 0 || sampleRate > 0 && sampleRate < 1 && Math.random() > sampleRate) {
+      return;
+    }
+
+    if (typeof analyticsOptions.filter === "function" && !analyticsOptions.filter(payload)) {
+      return;
+    }
+
+    // Optional event dedupe within rolling window (milliseconds)
+    const dedupeWindow = Number(analyticsOptions.dedupeWindow || 0);
+    if (dedupeWindow > 0 && this._lastAnalyticsEvent) {
+      let sameEvent =
+        this._lastAnalyticsEvent.eventName === payload.eventName &&
+        this._lastAnalyticsEvent.platform === payload.platform &&
+        this._lastAnalyticsEvent.url === payload.url &&
+        this._lastAnalyticsEvent.interactionType === payload.interactionType;
+
+      if (typeof analyticsOptions.dedupeBy === "function") {
+        sameEvent = analyticsOptions.dedupeBy(this._lastAnalyticsEvent, payload);
+      } else if (Array.isArray(analyticsOptions.dedupeBy)) {
+        sameEvent = analyticsOptions.dedupeBy.every((key) =>
+          Object.prototype.hasOwnProperty.call(payload, key)
+            ? this._lastAnalyticsEvent[key] === payload[key]
+            : false
+        );
+      }
+
+      if (sameEvent && Date.now() - this._lastAnalyticsEvent.timestamp < dedupeWindow) {
+        return;
+      }
+    }
+
+    // Enrich context if enabled (default true)
+    if (analyticsOptions.enrichContext !== false) {
+      payload.context = {
+        referrer: typeof document !== "undefined" ? document.referrer || null : null,
+        locale:
+          typeof navigator !== "undefined" && navigator.language
+            ? navigator.language
+            : null,
+        viewport:
+          typeof window !== "undefined"
+            ? `${window.innerWidth}x${window.innerHeight}`
+            : null,
+      };
+      if (analyticsOptions.includeUserAgent && typeof navigator !== "undefined") {
+        payload.context.userAgent = navigator.userAgent;
+      }
+    }
+
+    this._lastAnalyticsEvent = payload;
+
+    // Keep rolling event history buffer for debugging/inspection
+    const historyLimit = Number(analyticsOptions.historyLimit || 100);
+    this.analyticsHistory.push(payload);
+    if (this.analyticsHistory.length > historyLimit) {
+      this.analyticsHistory.shift();
+    }
+
     // Optional console output for development / debugging
     if (this.options.debug) {
       // eslint-disable-next-line no-console