fragment-headless-sdk 2.1.1 → 2.1.2

package/CHANGELOG.md

@@ -0,0 +1,436 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.2] - 2025-10-30
+
+### 📚 Documentation Updates
+
+- **Enhanced README** – Updated documentation to highlight new click tracking features
+- **Feature Highlights** – Added comprehensive documentation for the enhanced click tracking system
+- **Usage Examples** – Improved examples showing the separation of button destinations and tracking
+
+## [2.1.1] - 2025-10-30
+
+### 🎯 Enhanced Click Tracking System
+
+- **Improved Click Tracking Architecture** – Separated button destinations from click tracking for better user experience
+  - `buttonHref` now contains the actual destination URL (no redirect)
+  - `clickHref` contains the tracking URL for metrics collection
+  - Users go directly to intended destinations instead of through redirects
+- **New `fireClickMetric()` Function** – Advanced click tracking without relying on redirects
+  - Uses `fetch()` with `no-cors` mode and `keepalive` for reliable tracking
+  - Falls back to Image pixel tracking for maximum compatibility
+  - Handles server-side rendering gracefully
+- **Removed Automatic New Tab Behavior** – Links no longer force `target="_blank"`
+  - Provides more natural user experience
+  - Allows developers to control link behavior explicitly
+  - Maintains accessibility with proper ARIA labels
+
+### 🛠 Technical Improvements
+
+- **Enhanced Component Props** – Both Hero and Announcement components now accept separate tracking parameters
+  - `buttonHref` for the actual destination
+  - `clickHref` for tracking metrics
+- **Better Error Handling** – Click tracking fails gracefully without affecting user experience
+- **Performance Optimized** – Non-blocking click tracking that doesn't delay navigation
+- **Cross-Browser Compatible** – Works across all modern browsers with appropriate fallbacks
+
+### 📝 Usage Examples
+
+```typescript
+// The SDK automatically handles the separation of concerns
+const heroContent = {
+  title: "Shop Now",
+  buttonText: "Get Started",
+  buttonLink: "https://example.com/products", // Direct destination
+  clickUrlBase: "https://tracking.example.com/click", // Tracking base
+  // SDK automatically creates:
+  // - buttonHref: "https://example.com/products" (direct link)
+  // - clickHref: "https://tracking.example.com/click?u=..." (tracking)
+};
+
+<Hero content={heroContent} />;
+```
+
+### ⚡ Performance Benefits
+
+- **Faster Navigation** – Users go directly to destinations without redirect delays
+- **Reliable Tracking** – Click metrics are captured even if users navigate away quickly
+- **Better SEO** – Direct links improve search engine crawling and indexing
+- **Enhanced UX** – More predictable link behavior for better user experience
+
+### 🔄 Backward Compatibility
+
+- **No Breaking Changes** – All existing implementations continue to work
+- **Automatic Upgrade** – New tracking system activates automatically when `clickUrlBase` is present
+- **Legacy Support** – Existing tracking URLs continue to function as before
+
+## [2.1.0] - 2025-10-27
+
+### 🎨 Enhanced Hero Styling System
+
+- **New Hero Resolvers Utility** – Comprehensive utility system for advanced Hero component customization
+  - `resolveHeroColors()` – Intelligent color resolution with fallback handling
+  - `resolveHeroTypography()` – Typography settings with font family, size, and line height control
+  - `resolveContentWidthClass()` – Dynamic content width management
+  - `resolvePosition()` – Content positioning (left, center, right alignment)
+  - `resolveHeight()` – Flexible height configuration
+  - `renderText()` – Unified text rendering with typography and styling support
+
+### ✨ Advanced Typography Features
+
+- **Font Family Support** – Built-in support for popular font families:
+  - Roboto, Open Sans, Lato, Montserrat, Poppins, Inter, Nunito Sans, Source Sans Pro
+  - Custom font family support through `FontKey` type system
+- **Responsive Typography** – Granular control over font sizes and line heights
+  - Separate title and description typography settings
+  - Tailwind CSS class integration for responsive design
+- **Typography Tokens** – New styling tokens for enhanced typography control:
+  - `titleFontSize`, `titleLineHeight`, `titleFont`
+  - `descriptionFontSize`, `descriptionLineHeight`, `descriptionFont`
+
+### 🏗️ Layout & Positioning Enhancements
+
+- **Content Positioning** – New positioning system for Hero content alignment
+  - Left, center, and right alignment options
+  - Responsive positioning with proper text alignment
+- **Content Width Control** – Dynamic content width management
+  - Configurable content container widths
+  - Responsive design integration
+- **Height Management** – Flexible height configuration system
+  - Custom height classes support
+  - Default height fallbacks
+
+### 🎯 Developer Experience Improvements
+
+- **Type Safety** – Enhanced TypeScript interfaces for all new features
+  - `HeroResolvedColors` interface for color resolution
+  - `HeroTypographySettings` interface for typography configuration
+  - `FontKey` type for font family validation
+- **Utility Functions** – New helper functions for common operations
+  - `joinClassNames()` – Safe CSS class concatenation
+  - `fallbackColor()` – Color value validation with fallbacks
+- **Better Defaults** – Comprehensive default values for all styling options
+  - `DEFAULT_COLORS` for color fallbacks
+  - `DEFAULT_TYPOGRAPHY` for typography defaults
+  - `FONT_FAMILY_MAP` for font family mappings
+
+### 🔄 Backward Compatibility
+
+- **Seamless Migration** – All existing Hero components continue to work without changes
+- **Progressive Enhancement** – New features are opt-in and don't affect existing implementations
+- **Legacy Support** – Existing styling approaches remain fully supported
+
+### 📝 Usage Examples
+
+```typescript
+// Enhanced Hero with new typography and positioning
+const heroContent = {
+  title: "Welcome to Our Store",
+  description: "Discover amazing products",
+  buttonText: "Shop Now",
+  buttonLink: "/products",
+  imageUrl: "https://example.com/hero.jpg",
+
+  styling: {
+    tokens: {
+      colors: {
+        title: "#ffffff",
+        text: "#f0f0f0",
+        button: "#007bff",
+        buttonText: "#ffffff",
+        background: "#1a1a1a",
+      },
+      typography: {
+        titleFont: "montserrat",
+        titleFontSize: "text-6xl",
+        titleLineHeight: "leading-tight",
+        descriptionFont: "inter",
+        descriptionFontSize: "text-xl",
+        descriptionLineHeight: "leading-relaxed",
+      },
+      layout: {
+        contentWidth: "max-w-4xl",
+        position: "center",
+        height: "min-h-screen",
+      },
+    },
+  },
+};
+```
+
+### 🛠 Technical Improvements
+
+- **Performance Optimized** – Efficient color and typography resolution
+- **Memory Efficient** – Optimized utility functions with minimal overhead
+- **Tree Shakeable** – Individual utility functions can be imported separately
+- **CSS-in-JS Ready** – Full compatibility with styled-components and emotion
+
+## [1.0.6] - 2025-10-16
+
+### 🚀 Next.js Caching Fix
+
+- **Fixed Vercel/Next.js Caching Issues** – Resolved aggressive caching that prevented fresh data from appearing in production deployments
+  - Added `cache: 'no-store'` by default for all `fetchResource()` calls
+  - Added Next.js-specific `revalidate: 0` configuration
+  - Added cache-busting headers (`Cache-Control`, `Pragma`) to prevent CDN caching
+  - Smart environment detection for Next.js vs other frameworks
+
+### ✨ New Cache Management Features
+
+- **Cache Configuration Options** – Added optional `cacheOptions` parameter to `fetchResource()`
+  - `cache`: Control request cache mode (default: 'no-store' for fresh data)
+  - `revalidate`: Next.js revalidation time in seconds (default: 0)
+  - `tags`: Next.js cache tags for selective invalidation
+- **Cache Invalidation Utilities** – New helper functions for cache management
+  - `revalidateFragmentCache()` – Invalidate all or specific Fragment caches
+  - `revalidateResourceType()` – Invalidate cache for specific resource type
+  - `revalidateAllFragmentCaches()` – Clear all Fragment-related caches
+  - `createCacheTag()` / `createCacheTags()` – Generate cache tags
+
+### 🛠 Technical Improvements
+
+- **Environment Detection** – Automatic Next.js environment detection for optimal cache settings
+- **Backward Compatibility** – All existing code continues to work without changes
+- **TypeScript Support** – Full type definitions for new cache options
+
+### 📝 Usage Examples
+
+```typescript
+// Default behavior - always fresh data (recommended)
+const announcements = await fetchResource({
+  baseUrl: process.env.FRAGMENT_BASE_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.Announcements,
+});
+
+// Optional: Enable caching for performance
+const cachedHeroes = await fetchResource({
+  baseUrl: process.env.FRAGMENT_BASE_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.HeroBanners,
+  cacheOptions: {
+    cache: "default",
+    revalidate: 300, // 5 minutes
+  },
+});
+
+// Cache invalidation (server-side only)
+import { revalidateResourceType } from "fragment-headless-sdk";
+await revalidateResourceType(ResourceType.Announcements);
+```
+
+### ⚠️ Migration Notes
+
+- **No breaking changes** – Existing code works without modification
+- **Fresh data by default** – Your database updates will now appear immediately in production
+- **Opt-in caching** – Use `cacheOptions` if you want to enable caching for performance
+
+## [1.0.5] - 2025-09-28
+
+### ✨ New Features
+
+- **Metrics Tracking** – Added built-in view and click tracking for both **Hero** and **Announcement** sections.
+  - Each resource’s `content` object now includes two server-generated fields:
+    - `impressionUrl` – 1×1 pixel URL automatically fired when the component enters the viewport.
+    - `clickUrlBase` – base redirect URL used to record button clicks before sending the user to the final destination.
+  - The SDK’s `<Hero>` and `<Announcement>` components now automatically:
+    - trigger a view pixel when visible, and
+    - wrap their CTA buttons with a signed click-tracking redirect.
+
+### 🛠 Technical Notes
+
+- The `makeSignedMetricUrls` helper was refactored to attach `impressionUrl` and `clickUrlBase` **inside the `content` object** for each item returned by the API.
+- New client-side utilities exported from `utils`:
+  - `buildClickUrl()` – safely appends the final destination (`&u=...`) to a signed `clickUrlBase`.
+  - `fireImpressionWhenVisible()` – fires a pixel only once when an element is at least 30 % visible.
+
+### ⚠️ Migration Notes
+
+- **No breaking changes.**  
+  Existing components continue to work; the new tracking is automatic when you upgrade to v1.0.5.
+- If you build custom CTAs outside the provided components, use the new helpers to track clicks and views manually.
+
+## [1.0.4] - 2025-09-27
+
+- **Types:** `IHero` now includes `views_count: number` and `clicks_count: number`.
+
+### 📝 Notes
+
+- No breaking changes..
+
+## [1.0.3] - 2025-09-21
+
+### 🎨 UI/UX Improvements
+
+- **Announcement Type Rename** - Changed `AnnouncementType.Announcement` to `AnnouncementType.Static` for better clarity
+- **Countdown Timer Styling** - Removed white background from countdown timer for cleaner appearance
+- **Layout Optimization** - Improved announcement banner layout with:
+  - Removed top/bottom padding (`py-3`) for more compact design
+  - Added 50px minimum height for consistent banner sizing
+  - Enhanced vertical centering of all content elements
+- **Timer Digit Sizing** - Made countdown timer digits smaller and more compact:
+  - Reduced digit size from 24×28px to 20×24px
+  - Changed font size from `text-xl` to `text-base`
+
+### 🔧 Technical Changes
+
+- Updated `announcementTypes` array to reflect new "Static" label
+- Improved flexbox layout for better vertical alignment
+- Maintained responsive design across all screen sizes
+
+## [1.0.2] - 2025-09-20
+
+### 🔄 Breaking Changes
+
+- **Component Naming** - Renamed `Banner` component and all related types to `Announcement`
+
+  - `Banner` → `Announcement`
+  - `IBannerContent` → `IAnnouncementContent`
+  - `IBanner` → `IAnnouncement`
+  - `BannerType` → `AnnouncementType`
+  - `BannerStatus` → `AnnouncementStatus`
+  - `BannerButton` → `AnnouncementButton`
+  - `BannerStyles` → `AnnouncementStyles`
+  - `bannerHtml` property → `announcementHtml`
+
+- **Resource Type Updates** - Updated resource type enums for consistency
+  - `ResourceType.HeroSections` → `ResourceType.HeroBanners`
+  - `ResourceType.Banners` → `ResourceType.Announcements`
+
+### 🔗 API Endpoint Changes
+
+- Updated API endpoints to match new naming:
+  - `/api/v1/hero-sections` → `/api/v1/hero-banners`
+  - `/api/v1/banners` → `/api/v1/announcements`
+
+### 📚 Documentation
+
+- Updated all documentation to reflect new component and type names
+- Updated README.md examples with new ResourceType values
+- Updated code examples throughout
+
+### 🛠️ Migration Guide
+
+To update your existing code:
+
+```typescript
+// Before (v1.0.1)
+import {
+  Banner,
+  BannerType,
+  IBannerContent,
+  ResourceType,
+} from "fragment-headless-sdk";
+
+const banners = await fetchResource({
+  type: ResourceType.Banners,
+});
+
+<Banner content={bannerContent} type={BannerType.Standard} />;
+
+// After (v1.0.2)
+import {
+  Announcement,
+  AnnouncementType,
+  IAnnouncementContent,
+  ResourceType,
+} from "fragment-headless-sdk";
+
+const announcements = await fetchResource({
+  type: ResourceType.Announcements,
+});
+
+<Announcement
+  content={announcementContent}
+  type={AnnouncementType.Announcement}
+/>;
+```
+
+## [1.0.1] - 2025-09-07
+
+### 🎉 Initial Release
+
+The official SDK for integrating with fragment-shopify CMS. Production-ready with full API key authentication support.
+
+### Features
+
+- **Complete TypeScript Support** - Full type definitions for all components and API responses
+- **React Components** - Pre-built Hero and Announcement components with responsive design
+- **API Integration** - Built-in utilities for fetching sections from fragment-shopify app
+- **Production Ready** - Full API key authentication with v1 endpoints
+- **Tailwind CSS** - Styled components with customizable design system
+
+### Components
+
+- **Hero Component** - Responsive hero sections with desktop/mobile variants
+  - Support for images, videos, and call-to-action buttons
+  - Customizable content and styling
+- **Announcement Component** - Flexible announcement bars with multiple display types
+  - Standard, marquee, and countdown announcement variants
+  - `AnnouncementButton` and `CountdownTimer` sub-components
+
+### API Integration
+
+- **`fetchResource()` Function** - Simple API for fetching sections
+- **API Key Authentication** - Secure authentication using `keyId:secret` format
+- **v1 Endpoints** - Production endpoints (`/api/v1/announcements`, `/api/v1/hero-banners`)
+- **Error Handling** - Comprehensive error handling and logging
+- **Type Safety** - Full TypeScript support for all API responses
+
+### Usage
+
+```tsx
+import {
+  fetchResource,
+  ResourceType,
+  Hero,
+  Announcement,
+} from "fragment-headless-sdk";
+
+// Fetch data
+const heroes = await fetchResource({
+  baseUrl: process.env.EXTERNAL_API_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.HeroBanners,
+});
+
+// Render components
+<Hero content={heroes[0]?.content} />;
+```
+
+### Environment Variables
+
+```bash
+EXTERNAL_API_URL=https://your-fragment-app.vercel.app
+FRAGMENT_API_KEY=bh_a1b2c3d4e5f6:your-64-char-secret
+```
+
+---
+
+## Upcoming Changes
+
+### v1.1.0 (Planned)
+
+- Enhanced error handling with specific error types
+- Support for additional section types
+- Caching and performance optimizations
+
+### v1.2.0 (Planned)
+
+- Real-time updates via webhooks
+- Advanced filtering and sorting options
+- Batch operations support
+- TypeScript strict mode compatibility
+
+---
+
+## Support
+
+- **Documentation**: [README.md](./README.md)
+- **NPM Package**: https://www.npmjs.com/package/fragment-shopify-sdk
+- **Issues**: Please report issues in the GitHub repository

package/dist/components/Announcement/AnnouncementButton.d.ts

@@ -1,6 +1,7 @@
 import React from "react";
 import { IAnnouncementContent } from "../../types";
-export default function AnnouncementButton({ content, buttonHref, }: {
+export default function AnnouncementButton({ content, buttonHref, clickHref, }: {
     content: IAnnouncementContent;
     buttonHref?: string;
+    clickHref?: string;
 }): React.JSX.Element | null;

package/dist/components/Announcement/AnnouncementButton.js

@@ -1,17 +1,13 @@
 import React from "react";
 import { ButtonType } from "../../constants";
-import { mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveToken, resolveTokenByCategory, } from "../../utils";
-export default function AnnouncementButton({ content, buttonHref, }) {
+import { fireClickMetric, mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveToken, resolveTokenByCategory, } from "../../utils";
+export default function AnnouncementButton({ content, buttonHref, clickHref, }) {
     // Don’t render if no button or explicitly None
     if (!content?.buttonText || content.buttonType === ButtonType.None)
         return null;
     // If we weren’t given a usable href, don’t render a broken link
     if (!buttonHref)
         return null;
-    // Decide if link should open in a new tab.
-    // If you already have a boolean like `content.buttonLink` meaning "open in new tab",
-    // keep using it; otherwise you can add one later.
-    const openInNewTab = Boolean(content.buttonLink);
     const styling = content.styling;
     const baseTextColor = resolveTokenByCategory(styling, "colors", "text") ||
         resolveToken(styling, "textColor");
@@ -37,7 +33,10 @@ export default function AnnouncementButton({ content, buttonHref, }) {
     if (attributes && "aria-label" in attributes) {
         delete attributes["aria-label"];
     }
-    return (React.createElement("a", { href: buttonHref, className: className, style: style, ...(openInNewTab
-            ? { target: "_blank", rel: "noopener noreferrer" }
-            : {}), ...(attributes ?? {}), "aria-label": ariaLabel }, content.buttonText));
+    const handleClick = React.useCallback(() => {
+        if (!clickHref)
+            return;
+        fireClickMetric(clickHref);
+    }, [clickHref]);
+    return (React.createElement("a", { href: buttonHref, className: className, style: style, onClick: handleClick, ...(attributes ?? {}), "aria-label": ariaLabel }, content.buttonText));
 }

package/dist/components/Announcement/index.js

@@ -2,6 +2,7 @@ import React, { useEffect, useRef } from "react";
 import { AnnouncementType, ButtonType } from "../../constants";
 import { buildClickUrl, fireImpressionWhenVisible, getThemeClasses, mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveToken, resolveTokenByCategory, } from "../../utils";
 import AnnouncementButton from "./AnnouncementButton";
+import { AnnouncementStyles } from "./AnnouncementStyles";
 import CountdownTimer from "./CountdownTimer";
 export default function Announcement({ content, type, handleClose, }) {
     const ref = useRef(null);
@@ -10,7 +11,8 @@ export default function Announcement({ content, type, handleClose, }) {
             fireImpressionWhenVisible(ref.current, content.impressionUrl);
         }
     }, [content?.impressionUrl]);
-    const signedButtonHref = content?.buttonLink && content?.clickUrlBase
+    const buttonHref = content?.buttonLink || undefined;
+    const clickTrackingHref = content?.buttonLink && content?.clickUrlBase
         ? buildClickUrl(content.clickUrlBase, content.buttonLink)
         : undefined;
     if (!content)
@@ -54,6 +56,7 @@ export default function Announcement({ content, type, handleClose, }) {
     const closeButtonStyle = mergeSlotStyles({ color: closeButtonColor }, styling, "closeButton");
     const closeButtonAttributes = mergeSlotAttributes(styling, "closeButton");
     return (React.createElement("div", { ref: ref, className: rootClass, style: rootStyle, ...(rootAttributes ?? {}) },
+        React.createElement(AnnouncementStyles, null),
         React.createElement("div", { className: innerClass, style: innerStyle, ...(innerAttributes ?? {}) },
             type === AnnouncementType.Marquee ? (React.createElement("div", { className: marqueeContainerClass, style: marqueeContainerStyle, ...(marqueeContainerAttributes ?? {}) },
                 React.createElement("div", { className: marqueeTextWrapperClass, style: marqueeTextWrapperStyle, ...(marqueeTextWrapperAttributes ?? {}) },
@@ -61,12 +64,12 @@ export default function Announcement({ content, type, handleClose, }) {
                         React.createElement("div", { className: marqueeContentClass, style: marqueeContentStyle, ...(marqueeContentAttributes ?? {}), dangerouslySetInnerHTML: {
                                 __html: content.announcementHtml || "",
                             } }))),
-                content.buttonText && content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: signedButtonHref })))) : (React.createElement("div", { className: contentRowClass, style: contentRowStyle, ...(contentRowAttributes ?? {}) },
+                content.buttonText && content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref })))) : (React.createElement("div", { className: contentRowClass, style: contentRowStyle, ...(contentRowAttributes ?? {}) },
                 React.createElement("div", { className: announcementTextClass, style: announcementTextStyle, ...(announcementTextAttributes ?? {}) },
                     React.createElement("div", { dangerouslySetInnerHTML: {
                             __html: content.announcementHtml || "",
                         } })),
                 type === AnnouncementType.Countdown ? (React.createElement(CountdownTimer, { content: content })) : (content.buttonText &&
-                    content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: signedButtonHref || content.buttonLink || "#" }))))),
+                    content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref }))))),
             React.createElement("div", { onClick: handleClose, className: closeButtonClass, style: closeButtonStyle, ...(closeButtonAttributes ?? {}) }, "\u00D7"))));
 }

package/dist/components/Hero/DesktopHero.d.ts

@@ -3,6 +3,7 @@ import { IHeroContent } from "../../types";
 import { resolveHeroColors, resolveHeroTypography } from "../../utils/hero-resolvers";
 interface HeroViewProps {
     buttonHref?: string;
+    clickHref?: string;
     content: IHeroContent;
     colors: ReturnType<typeof resolveHeroColors>;
     contentWidthClass: string;
@@ -10,5 +11,5 @@ interface HeroViewProps {
     position: "left" | "center" | "right";
     height: string;
 }
-export default function DesktopHero({ buttonHref, content, colors, contentWidthClass, typography, position, height, }: HeroViewProps): React.JSX.Element;
+export default function DesktopHero({ buttonHref, clickHref, content, colors, contentWidthClass, typography, position, height, }: HeroViewProps): React.JSX.Element;
 export {};

package/dist/components/Hero/DesktopHero.js

@@ -1,6 +1,7 @@
 import React from "react";
+import { fireClickMetric } from "../../utils";
 import { DEFAULT_CONTENT_WIDTH_CLASS, joinClassNames, renderText, } from "../../utils/hero-resolvers";
-export default function DesktopHero({ buttonHref, content, colors, contentWidthClass, typography, position, height, }) {
+export default function DesktopHero({ buttonHref, clickHref, content, colors, contentWidthClass, typography, position, height, }) {
     const getPositionClasses = () => {
         switch (position) {
             case "center":
@@ -12,6 +13,11 @@ export default function DesktopHero({ buttonHref, content, colors, contentWidthC
                 return "items-start text-left";
         }
     };
+    const handleClick = React.useCallback(() => {
+        if (!clickHref)
+            return;
+        fireClickMetric(clickHref);
+    }, [clickHref]);
     return (React.createElement("div", { className: `relative ${height} gap-4 w-full`, style: { backgroundColor: colors.background } },
         content?.videoUrl ? (React.createElement("video", { src: content.videoUrl, autoPlay: true, muted: true, loop: true, playsInline: true, className: "absolute inset-0 z-0 object-cover w-full h-full" })) : (
         /* Image Background */
@@ -22,6 +28,7 @@ export default function DesktopHero({ buttonHref, content, colors, contentWidthC
                     fontSize: typography.title.fontSize,
                     lineHeight: typography.title.lineHeight,
                     text: content?.title,
+                    className: "mt-4",
                     color: colors.title,
                     font: typography.title.font,
                 }),
@@ -33,7 +40,7 @@ export default function DesktopHero({ buttonHref, content, colors, contentWidthC
                     color: colors.text,
                     font: typography.description.font,
                 }),
-                content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, target: "_blank", rel: "noopener noreferrer", className: "no-underline" },
+                content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, onClick: handleClick, className: "no-underline" },
                     React.createElement("div", { className: "mt-6 inline-block rounded-md px-8 py-2 text-2xl font-semibold drop-shadow-lg transition-all duration-200 hover:opacity-90", style: {
                             color: colors.buttonText,
                             backgroundColor: colors.buttonBackground,

package/dist/components/Hero/MobileHero.d.ts

@@ -3,9 +3,10 @@ import { IHeroContent } from "../../types";
 import { resolveHeroColors, resolveHeroTypography } from "../../utils/hero-resolvers";
 interface MobileHeroProps {
     buttonHref?: string;
+    clickHref?: string;
     content: IHeroContent;
     colors: ReturnType<typeof resolveHeroColors>;
     typography: ReturnType<typeof resolveHeroTypography>;
 }
-export default function MobileHero({ buttonHref, content, colors, typography, }: MobileHeroProps): React.JSX.Element;
+export default function MobileHero({ buttonHref, clickHref, content, colors, typography, }: MobileHeroProps): React.JSX.Element;
 export {};

package/dist/components/Hero/MobileHero.js

@@ -1,22 +1,19 @@
 import React from "react";
-import { ensureSafeColor } from "../../utils/color";
+import { fireClickMetric } from "../../utils";
 import { renderText, } from "../../utils/hero-resolvers";
-export default function MobileHero({ buttonHref, content, colors, typography, }) {
-    const safeTitleColor = ensureSafeColor(colors.title, "#ffffff");
-    const safeTextColor = ensureSafeColor(colors.text, "#ffffff");
-    const titleFontSize = typography.title.fontSize === "text-5xl"
-        ? "text-3xl"
-        : typography.title.fontSize;
-    const descriptionFontSize = typography.description.fontSize === "text-3xl"
-        ? "text-lg"
-        : typography.description.fontSize;
+export default function MobileHero({ buttonHref, clickHref, content, colors, typography, }) {
+    const handleClick = React.useCallback(() => {
+        if (!clickHref)
+            return;
+        fireClickMetric(clickHref);
+    }, [clickHref]);
     return (React.createElement("div", { className: "relative z-10 mx-auto gap-4 flex max-w-screen-md flex-col items-center justify-center py-6 text-center", style: { backgroundColor: colors.background } },
         renderText({
-            fontSize: titleFontSize,
+            fontSize: typography.title.fontSize,
             lineHeight: typography.title.lineHeight,
             text: content?.title,
-            className: "px-4 drop-shadow-xl text-center font-bold",
-            color: safeTitleColor,
+            className: "px-4 drop-shadow-xl text-center",
+            color: colors.title,
             font: typography.title.font,
         }),
         content?.videoUrl ? (React.createElement("div", { className: "w-full" },
@@ -24,14 +21,14 @@ export default function MobileHero({ buttonHref, content, colors, typography, })
             React.createElement("img", { src: content.mobileImageUrl, alt: content.title || "Hero", className: "h-full w-full object-cover" }))) : content?.imageUrl ? (React.createElement("div", { className: "w-full" },
             React.createElement("img", { src: content.imageUrl, alt: content.title || "Hero", className: "h-full w-full object-cover" }))) : null,
         renderText({
-            fontSize: descriptionFontSize,
+            fontSize: typography.description.fontSize,
             lineHeight: typography.description.lineHeight,
             text: content?.description,
             className: "px-4 drop-shadow-lg text-center mt-4",
-            color: safeTextColor,
+            color: colors.text,
             font: typography.description.font,
         }),
-        content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, target: "_blank", rel: "noopener noreferrer", className: "no-underline" },
+        content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, onClick: handleClick, className: "no-underline" },
             React.createElement("div", { className: "mb-2 rounded-md px-6 py-2 text-lg font-semibold drop-shadow-lg transition-all duration-200 hover:opacity-90", style: {
                     color: colors.buttonText,
                     backgroundColor: colors.buttonBackground,

package/dist/components/Hero/index.js

@@ -1,5 +1,5 @@
 import React, { useEffect, useRef } from "react";
-import { buildClickUrl, fireImpressionWhenVisible } from "../../utils";
+import { buildClickUrl, fireImpressionWhenVisible, } from "../../utils";
 import { resolveContentWidthClass, resolveHeight, resolveHeroColors, resolveHeroTypography, resolvePosition, } from "../../utils/hero-resolvers";
 import DesktopHero from "./DesktopHero";
 import MobileHero from "./MobileHero";
@@ -10,7 +10,8 @@ export default function Hero({ content }) {
             fireImpressionWhenVisible(ref.current, content.impressionUrl);
         }
     }, [content?.impressionUrl]);
-    const signedButtonHref = content?.buttonLink && content?.clickUrlBase
+    const buttonHref = content?.buttonLink || undefined;
+    const clickTrackingHref = content?.buttonLink && content?.clickUrlBase
         ? buildClickUrl(content.clickUrlBase, content.buttonLink)
         : undefined;
     if (!content)
@@ -22,7 +23,7 @@ export default function Hero({ content }) {
     const height = resolveHeight(content);
     return (React.createElement("div", { className: "bg-black", ref: ref, style: { backgroundColor: colors.background } },
         React.createElement("div", { className: "hidden lg:block" },
-            React.createElement(DesktopHero, { content: content, buttonHref: signedButtonHref, colors: colors, contentWidthClass: contentWidthClass, typography: typography, position: position, height: height })),
+            React.createElement(DesktopHero, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref, colors: colors, contentWidthClass: contentWidthClass, typography: typography, position: position, height: height })),
         React.createElement("div", { className: "block lg:hidden" },
-            React.createElement(MobileHero, { content: content, buttonHref: signedButtonHref, colors: colors, typography: typography }))));
+            React.createElement(MobileHero, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref, colors: colors, typography: typography }))));
 }

package/dist/utils/index.d.ts

@@ -1,5 +1,4 @@
 export * from "./cache";
-export * from "./color";
 export * from "./fetch-resource";
 export * from "./hero-resolvers";
 export * from "./metrics";

package/dist/utils/index.js

@@ -1,5 +1,4 @@
 export * from "./cache";
-export * from "./color";
 export * from "./fetch-resource";
 export * from "./hero-resolvers";
 export * from "./metrics";

package/dist/utils/metrics.d.ts

@@ -1,3 +1,4 @@
 export declare function toBase64Url(input: string): string;
 export declare function buildClickUrl(clickUrlBase: string, targetHref: string): string;
+export declare function fireClickMetric(clickUrl: string): void;
 export declare function fireImpressionWhenVisible(el: HTMLElement, pixelUrl: string): void;

package/dist/utils/metrics.js

@@ -9,11 +9,42 @@ function appendQuery(url, key, value) {
     const sep = url.includes("?") ? "&" : "?";
     return `${url}${sep}${key}=${value}`;
 }
-// Build the final redirect URL the CTA should use
+// Build the tracking URL that encodes the final destination for metrics
 export function buildClickUrl(clickUrlBase, targetHref) {
     const u = encodeURIComponent(toBase64Url(targetHref));
     return appendQuery(clickUrlBase, "u", u);
 }
+// Fire the click tracking URL without relying on a redirect
+// Default to GET so legacy tracking endpoints continue to accept the request
+export function fireClickMetric(clickUrl) {
+    if (typeof window === "undefined")
+        return;
+    if (!clickUrl)
+        return;
+    try {
+        if (typeof fetch === "function") {
+            fetch(clickUrl, {
+                method: "GET",
+                mode: "no-cors",
+                keepalive: true,
+            }).catch(() => {
+                /* no-op */
+            });
+            return;
+        }
+    }
+    catch {
+        // swallow and fall back to <img>
+    }
+    try {
+        const img = new Image();
+        img.referrerPolicy = "strict-origin-when-cross-origin";
+        img.src = clickUrl;
+    }
+    catch {
+        // nothing else we can do
+    }
+}
 // --- View tracking (once per element) ---
 const seenEls = typeof WeakSet !== "undefined" ? new WeakSet() : null;
 export function fireImpressionWhenVisible(el, pixelUrl) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fragment-headless-sdk",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/readme.md

@@ -2,7 +2,20 @@
 
 The official SDK for integrating with Fragment-Shopify CMS. Provides React components, TypeScript types, and utilities for rendering published sections in headless Shopify storefronts.
 
-## ✨ What's New in v2.1.0
+## ✨ What's New in v2.1.2
+
+📚 **Enhanced Documentation** - Comprehensive documentation updates highlighting new click tracking features  
+📖 **Better Examples** - Improved usage examples and feature descriptions  
+🎯 **Feature Highlights** - Clear documentation of the enhanced click tracking system
+
+### Previous Release (v2.1.1)
+
+🎯 **Enhanced Click Tracking System** - Improved click tracking architecture with better user experience  
+⚡ **Direct Navigation** - Users go directly to destinations without redirect delays  
+🔗 **Separated Tracking** - Button destinations and click tracking are now handled separately  
+🛠️ **Better Performance** - Non-blocking click tracking that doesn't delay navigation
+
+### Previous Release (v2.1.0)
 
 🎨 **Enhanced Hero Styling System** - New hero resolvers utility with advanced typography, positioning, and layout controls  
 🔤 **Advanced Typography** - Built-in font family support with granular control over sizes and line heights  
@@ -41,6 +54,7 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
 - ✅ **TypeScript Support**: Full type definitions for all components and data structures
 - ✅ **Multiple Announcement Types**: Standard, marquee, and countdown announcement variants
 - ✅ **Hero Sections**: Desktop/mobile responsive hero components with video support
+- ✅ **Advanced Click Tracking**: Separated tracking and navigation for optimal user experience
 
 ### Advanced Styling System (v2.0+)
 
@@ -62,6 +76,15 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
 - 📝 **Type Safety**: Enhanced TypeScript interfaces for all styling options
 - 🔄 **Backward Compatible**: Works seamlessly with existing Hero implementations
 
+### Enhanced Click Tracking System (v2.1.1+)
+
+- 🎯 **Separated Concerns**: Button destinations and click tracking handled independently
+- ⚡ **Direct Navigation**: Users go directly to destinations without redirect delays
+- 🔗 **Advanced Tracking**: `fireClickMetric()` function with fetch API and image fallback
+- 🛠️ **Non-Blocking**: Click tracking doesn't delay user navigation
+- 🌐 **Cross-Browser**: Works across all modern browsers with appropriate fallbacks
+- 🔄 **Graceful Degradation**: Tracking fails silently without affecting user experience
+
 ---
 
 ## 📦 Installation

package/dist/utils/color.d.ts

@@ -1,2 +0,0 @@
-export declare function isDarkColor(color: string | undefined | null): boolean;
-export declare function ensureSafeColor(color: string | undefined | null, fallback: string): string;

package/dist/utils/color.js

@@ -1,67 +0,0 @@
-const HEX_COLOR_REGEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
-const RGB_COLOR_REGEX = /^rgba?\s*\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})(?:\s*,\s*(\d*\.?\d+))?\s*\)$/i;
-function hexToRgb(color) {
-    if (!HEX_COLOR_REGEX.test(color)) {
-        return null;
-    }
-    let hex = color.slice(1);
-    if (hex.length === 3) {
-        hex = hex
-            .split("")
-            .map((char) => char + char)
-            .join("");
-    }
-    const bigint = parseInt(hex, 16);
-    return {
-        r: (bigint >> 16) & 255,
-        g: (bigint >> 8) & 255,
-        b: bigint & 255,
-    };
-}
-function rgbStringToRgb(color) {
-    const match = color.match(RGB_COLOR_REGEX);
-    if (!match) {
-        return null;
-    }
-    const [, r, g, b] = match;
-    const red = Number(r);
-    const green = Number(g);
-    const blue = Number(b);
-    if ([red, green, blue].some((value) => Number.isNaN(value))) {
-        return null;
-    }
-    return { r: red, g: green, b: blue };
-}
-function normalizeColor(color) {
-    if (!color) {
-        return null;
-    }
-    const trimmed = color.trim();
-    return hexToRgb(trimmed) ?? rgbStringToRgb(trimmed);
-}
-function getRelativeLuminance(rgb) {
-    const transform = (value) => {
-        const channel = value / 255;
-        if (channel <= 0.03928) {
-            return channel / 12.92;
-        }
-        return Math.pow((channel + 0.055) / 1.055, 2.4);
-    };
-    const r = transform(rgb.r);
-    const g = transform(rgb.g);
-    const b = transform(rgb.b);
-    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-export function isDarkColor(color) {
-    const rgb = normalizeColor(color);
-    if (!rgb) {
-        return false;
-    }
-    return getRelativeLuminance(rgb) < 0.5;
-}
-export function ensureSafeColor(color, fallback) {
-    if (!color) {
-        return fallback;
-    }
-    return isDarkColor(color) ? fallback : color;
-}