@windstream/react-shared-components 0.1.18 → 0.1.20

package/src/types/global.d.ts

@@ -1,9 +1,9 @@
-declare module "*.module.css" {
-  const classes: { [key: string]: string };
-  export default classes;
-}
-
-declare module "*.css" {
-  const content: string;
-  export default content;
-}
+declare module "*.module.css" {
+  const classes: { [key: string]: string };
+  export default classes;
+}
+
+declare module "*.css" {
+  const content: string;
+  export default content;
+}

package/src/types/micro-components.ts

@@ -1,99 +1,99 @@
-import { ButtonProps } from "@shared/contentful";
-
-export interface Asset {
-  url?: string | null;
-  title?: string | null;
-  description?: string | null;
-  contentType?: string | null;
-  width?: number | null;
-  height?: number | null;
-}
-export interface Button {
-  anchorId?: string | null;
-  showButtonAs?: "solid" | "text" | null;
-  buttonLabel: string; // required in your model
-  buttonPrefix?: string | null;
-  href?: string | null;
-  target?: "_blank" | "_self" | null;
-  badge?: string | null;
-  preserveQueryParameters: boolean; // non-null in your model
-  badgeIcon?: Asset | null;
-  buttonVariant?: "primary_brand" | "primary_inverse" | "secondary" | null;
-  buttonIcon?: Asset | null;
-  buttonIconPosition?: boolean | null; // matches EntryFieldTypes.Boolean in your model
-  clickToOpen?: "accordion" | "modal" | "tab" | null;
-  tabmodalNameToOpen?: string | null;
-  preDefinedFunctionExecution?: "check availability" | null;
-}
-
-export interface ButtonGroup {
-  __typename: "ComponentButtonGroup";
-  anchorId?: string | null;
-  title?: string | null;
-  itemsCollection?: {
-    items: Button[];
-  };
-}
-export interface Card {
-  anchorId?: string;
-  title?: string;
-  body?: {
-    json: any; // Contentful Rich Text
-  };
-  image?: Asset;
-  imageLink?: string;
-  imageAlignment?: "Left" | "Right" | "Center" | string;
-  imageView?: "Full" | "Inset" | string;
-  cta?: Button;
-  ctaAlignment?: "Left" | "Right" | "Center" | string;
-  textColor?: string;
-  backgroundColor?: string;
-  showBackgroundImage?: boolean;
-  pinwheelColor?: "blue" | "green" | "navy" | "purple" | "white" | "yellow";
-  iconToRichTextAlignment?: string;
-  phoneNumber?: string;
-  workingHours?: string;
-  titleLocation?: "Top" | "Bottom" | string;
-  ctaBottom?: Button;
-  ctaAlignmentBottom?: "Left" | "Right" | "Center" | string;
-  imageFloatingType?: boolean;
-}
-
-export interface VideoLink {
-  image?: Asset;
-  videoPopup?: boolean;
-  link?: string;
-}
-
-export interface Checklist {
-  list?: {
-    items: {
-      checkListTitle?: { json: any };
-      icon?: Asset;
-      anchorId?: string;
-    }[];
-  };
-}
-
-export interface RichTextItem {
-  title?: string;
-  isTargetBlank?: boolean;
-  richText?: { json: any };
-}
-
-export type CheckPlansProps = {
-  className?: string;
-  title?: string;
-  ctaAlignment?: "new-row" | "same-row";
-  ctaText?: string;
-  buttonVariant?: "primary_brand" | "secondary" | "primary_inverse";
-  showButtonAs?: "solid" | "unstyled" | "text" | undefined;
-  cta?: ButtonProps;
-  speedCardConfig?: {
-    isModalOpen?: boolean;
-    setModalOpen?: () => void;
-    speed?: string;
-    techType?: string;
-    isMax?: boolean;
-  };
-};
+import { ButtonProps } from "@shared/contentful";
+
+export interface Asset {
+  url?: string | null;
+  title?: string | null;
+  description?: string | null;
+  contentType?: string | null;
+  width?: number | null;
+  height?: number | null;
+}
+export interface Button {
+  anchorId?: string | null;
+  showButtonAs?: "solid" | "text" | null;
+  buttonLabel: string; // required in your model
+  buttonPrefix?: string | null;
+  href?: string | null;
+  target?: "_blank" | "_self" | null;
+  badge?: string | null;
+  preserveQueryParameters: boolean; // non-null in your model
+  badgeIcon?: Asset | null;
+  buttonVariant?: "primary_brand" | "primary_inverse" | "secondary" | null;
+  buttonIcon?: Asset | null;
+  buttonIconPosition?: boolean | null; // matches EntryFieldTypes.Boolean in your model
+  clickToOpen?: "accordion" | "modal" | "tab" | null;
+  tabmodalNameToOpen?: string | null;
+  preDefinedFunctionExecution?: "check availability" | null;
+}
+
+export interface ButtonGroup {
+  __typename: "ComponentButtonGroup";
+  anchorId?: string | null;
+  title?: string | null;
+  itemsCollection?: {
+    items: Button[];
+  };
+}
+export interface Card {
+  anchorId?: string;
+  title?: string;
+  body?: {
+    json: any; // Contentful Rich Text
+  };
+  image?: Asset;
+  imageLink?: string;
+  imageAlignment?: "Left" | "Right" | "Center" | string;
+  imageView?: "Full" | "Inset" | string;
+  cta?: Button;
+  ctaAlignment?: "Left" | "Right" | "Center" | string;
+  textColor?: string;
+  backgroundColor?: string;
+  showBackgroundImage?: boolean;
+  pinwheelColor?: "blue" | "green" | "navy" | "purple" | "white" | "yellow";
+  iconToRichTextAlignment?: string;
+  phoneNumber?: string;
+  workingHours?: string;
+  titleLocation?: "Top" | "Bottom" | string;
+  ctaBottom?: Button;
+  ctaAlignmentBottom?: "Left" | "Right" | "Center" | string;
+  imageFloatingType?: boolean;
+}
+
+export interface VideoLink {
+  image?: Asset;
+  videoPopup?: boolean;
+  link?: string;
+}
+
+export interface Checklist {
+  list?: {
+    items: {
+      checkListTitle?: { json: any };
+      icon?: Asset;
+      anchorId?: string;
+    }[];
+  };
+}
+
+export interface RichTextItem {
+  title?: string;
+  isTargetBlank?: boolean;
+  richText?: { json: any };
+}
+
+export type CheckPlansProps = {
+  className?: string;
+  title?: string;
+  ctaAlignment?: "new-row" | "same-row";
+  ctaText?: string;
+  buttonVariant?: "primary_brand" | "secondary" | "primary_inverse";
+  showButtonAs?: "solid" | "unstyled" | "text" | undefined;
+  cta?: ButtonProps;
+  speedCardConfig?: {
+    isModalOpen?: boolean;
+    setModalOpen?: () => void;
+    speed?: string;
+    techType?: string;
+    isMax?: boolean;
+  };
+};

package/src/types/utm.ts

@@ -0,0 +1,49 @@
+/**
+ * UTM Parameter Types
+ *
+ * Type definitions for UTM tracking parameters used across Kinetic applications.
+ */
+
+/** All tracked UTM and click-ID parameter names */
+export type UTMProperty =
+  | "utm_content"
+  | "utm_medium"
+  | "utm_campaign"
+  | "utm_source"
+  | "utm_term"
+  | "utm_campaign_id"
+  | "utm_adgroup_id"
+  | "fbclid"
+  | "gclid"
+  | "msclkid";
+
+/** Partial record of UTM parameter values */
+export type UTMProperties = Partial<Record<UTMProperty, string>>;
+
+/** Segment campaign context schema */
+export interface CampaignProperties {
+  name?: string;
+  source?: string;
+  medium?: string;
+  term?: string;
+  content?: string;
+  campaign_id?: string;
+  adgroup_id?: string;
+  gclid?: string;
+  fbclid?: string;
+  msclkid?: string;
+}
+
+/** List of all UTM parameter names for filtering */
+export const UTM_PARAM_NAMES: UTMProperty[] = [
+  "utm_content",
+  "utm_medium",
+  "utm_campaign",
+  "utm_source",
+  "utm_term",
+  "utm_campaign_id",
+  "utm_adgroup_id",
+  "fbclid",
+  "gclid",
+  "msclkid",
+];

package/src/utils/cookie.ts

@@ -0,0 +1,58 @@
+/**
+ * Cookie Helpers for UTM Parameter Storage
+ *
+ * Provides Base64-encoded JSON cookie storage for UTM parameters.
+ */
+import type { UTMProperties } from "../types/utm";
+import { Base64 } from "js-base64";
+import Cookies from "js-cookie";
+
+const UTM_COOKIE_KEY = "utm_parameters";
+const DEFAULT_DOMAIN = ".windstream.com";
+
+/**
+ * Reads UTM parameters from the Base64-encoded cookie.
+ * @returns Parsed UTMProperties or null if cookie doesn't exist / is invalid.
+ */
+export function getUTMs(): UTMProperties | null {
+  if (typeof window === "undefined") return null;
+
+  const raw = Cookies.get(UTM_COOKIE_KEY);
+  if (!raw) return null;
+
+  try {
+    const decoded = Base64.decode(raw);
+    return JSON.parse(decoded) as UTMProperties;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stores UTM parameters as a Base64-encoded JSON cookie.
+ * @param utms - The UTM properties to store.
+ * @param domain - Cookie domain (defaults to `.windstream.com`).
+ */
+export function setUTMs(
+  utms: UTMProperties,
+  domain: string = DEFAULT_DOMAIN
+): void {
+  if (typeof window === "undefined") return;
+
+  const json = JSON.stringify(utms);
+  const encoded = Base64.encode(json);
+
+  Cookies.set(UTM_COOKIE_KEY, encoded, {
+    domain,
+    path: "/",
+    sameSite: "Lax",
+  });
+}
+
+/**
+ * Removes the UTM cookie.
+ * @param domain - Cookie domain (defaults to `.windstream.com`).
+ */
+export function removeUTMs(domain: string = DEFAULT_DOMAIN): void {
+  Cookies.remove(UTM_COOKIE_KEY, { domain, path: "/" });
+}

package/src/utils/index.ts

@@ -1,49 +1,65 @@
-import { clsx, type ClassValue } from "clsx";
-import { extendTailwindMerge } from "tailwind-merge";
-
-const twMerge = extendTailwindMerge({
-  // Define class groups so twMerge knows which classes override each other
-  extend: {
-    classGroups: {
-      ["font-variants" as any]: [
-        "heading1",
-        "heading2",
-        "heading3",
-        "heading4",
-        "heading5",
-        "heading6",
-        "subheading1",
-        "subheading2",
-        "subheading3",
-        "subheading4",
-        "subheading5",
-        "subheading6",
-        "body1",
-        "body2",
-        "body3",
-        "footnote",
-        "micro",
-        "label1",
-        "label2",
-        "label3",
-        "label4",
-      ],
-      ["button-sizes" as any]: [
-        "btn-small",
-        "btn-medium",
-        "btn-large",
-        "btn-x-large",
-      ],
-    },
-  },
-});
-
-/**
- * Utility function to combine class names using clsx
- * @param inputs - Class values to combine
- * @returns Combined class string
- */
-export const cx = (...val: ClassValue[]) => twMerge(clsx(...val));
-
-export { clsx };
-export type { ClassValue };
+import { clsx, type ClassValue } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+const twMerge = extendTailwindMerge({
+  // Define class groups so twMerge knows which classes override each other
+  extend: {
+    classGroups: {
+      ["font-variants" as any]: [
+        "heading1",
+        "heading2",
+        "heading3",
+        "heading4",
+        "heading5",
+        "heading6",
+        "subheading1",
+        "subheading2",
+        "subheading3",
+        "subheading4",
+        "subheading5",
+        "subheading6",
+        "body1",
+        "body2",
+        "body3",
+        "footnote",
+        "micro",
+        "label1",
+        "label2",
+        "label3",
+        "label4",
+      ],
+      ["button-sizes" as any]: [
+        "btn-small",
+        "btn-medium",
+        "btn-large",
+        "btn-x-large",
+      ],
+    },
+  },
+});
+
+/**
+ * Utility function to combine class names using clsx
+ * @param inputs - Class values to combine
+ * @returns Combined class string
+ */
+export const cx = (...val: ClassValue[]) => twMerge(clsx(...val));
+
+export { clsx };
+export type { ClassValue };
+
+// UTM & Cookie utilities
+export { getUTMs, setUTMs, removeUTMs } from "./cookie";
+export {
+  getUtmParametersFromURL,
+  combineExistingAndNewUTMs,
+  getOrganicTrafficUtmParameters,
+  getCampaignProperties,
+  buildPreservedQueryHref,
+} from "./utm";
+export type {
+  UTMProperty,
+  UTMProperties,
+  CampaignProperties,
+} from "../types/utm";
+export { UTM_PARAM_NAMES } from "../types/utm";

package/src/utils/utm.ts

@@ -0,0 +1,221 @@
+/**
+ * UTM Parameter Helpers
+ *
+ * Functions for extracting, combining, and mapping UTM parameters
+ * for marketing campaign attribution.
+ */
+import {
+  UTM_PARAM_NAMES,
+  type CampaignProperties,
+  type UTMProperties,
+  type UTMProperty,
+} from "../types/utm";
+
+/**
+ * Extracts UTM parameters from the current page URL.
+ * Parses window.location.search for the 10 tracked UTM/click-ID params.
+ * @returns UTMProperties with any found values, or null if none found.
+ */
+export function getUtmParametersFromURL(): UTMProperties | null {
+  if (typeof window === "undefined") return null;
+
+  const searchParams = new URLSearchParams(window.location.search);
+  const utms: UTMProperties = {};
+  let found = false;
+
+  for (const param of UTM_PARAM_NAMES) {
+    const value = searchParams.get(param);
+    if (value) {
+      utms[param] = value;
+      found = true;
+    }
+  }
+
+  return found ? utms : null;
+}
+
+/**
+ * Smart-merges existing (cookie) UTMs with newly arrived (URL) UTMs.
+ *
+ * Logic:
+ * - If the same campaign (campaign, medium, source, campaign_id, adgroup_id,
+ *   fbclid, gclid, msclkid all match): preserve existing utm_content and
+ *   utm_term (first-touch attribution for ad content/keyword).
+ * - If only campaign-level UTMs changed (no new content/term provided):
+ *   carry forward existing content/term from cookie.
+ * - If completely different campaign: new UTMs fully overwrite.
+ *
+ * @param existing - UTM values currently stored in cookie.
+ * @param incoming - UTM values extracted from the current URL.
+ * @returns Merged UTMProperties.
+ */
+export function combineExistingAndNewUTMs(
+  existing: UTMProperties | null,
+  incoming: UTMProperties | null
+): UTMProperties {
+  if (!incoming) return existing || {};
+  if (!existing) return incoming;
+
+  // Campaign-level keys used to determine if it's the "same campaign"
+  const campaignKeys: UTMProperty[] = [
+    "utm_campaign",
+    "utm_medium",
+    "utm_source",
+    "utm_campaign_id",
+    "utm_adgroup_id",
+    "fbclid",
+    "gclid",
+    "msclkid",
+  ];
+
+  const isSameCampaign = campaignKeys.every(
+    key => (existing[key] || "") === (incoming[key] || "")
+  );
+
+  if (isSameCampaign) {
+    // Same campaign — preserve existing content/term (first-touch)
+    return {
+      ...incoming,
+      utm_content: existing.utm_content || incoming.utm_content,
+      utm_term: existing.utm_term || incoming.utm_term,
+    };
+  }
+
+  // Different campaign — check if incoming has content/term
+  const hasNewContent = !!incoming.utm_content;
+  const hasNewTerm = !!incoming.utm_term;
+
+  return {
+    ...incoming,
+    // Carry forward existing content/term only if incoming doesn't provide them
+    ...(!hasNewContent &&
+      existing.utm_content && { utm_content: existing.utm_content }),
+    ...(!hasNewTerm && existing.utm_term && { utm_term: existing.utm_term }),
+  };
+}
+
+/**
+ * Generates synthetic UTM parameters for organic/direct traffic
+ * based on document.referrer.
+ *
+ * - No referrer → direct / direct
+ * - Google/Bing → organic / google or bing
+ * - Other external site (not windstream.com) → referral / <domain>
+ * - Internal (windstream.com) → null (no cookie set)
+ *
+ * @returns UTMProperties for organic traffic, or null for internal nav.
+ */
+export function getOrganicTrafficUtmParameters(): UTMProperties | null {
+  if (typeof document === "undefined") return null;
+
+  const referrer = document.referrer;
+
+  if (!referrer) {
+    return { utm_medium: "direct", utm_source: "direct" };
+  }
+
+  let referrerHost: string;
+  try {
+    referrerHost = new URL(referrer).hostname.toLowerCase();
+  } catch {
+    return { utm_medium: "direct", utm_source: "direct" };
+  }
+
+  // Internal navigation — don't set organic UTMs
+  if (
+    referrerHost.includes("windstream.com") ||
+    referrerHost.includes("gokinetic.com")
+  ) {
+    return null;
+  }
+
+  // Search engines → organic
+  if (referrerHost.includes("google.")) {
+    return { utm_medium: "organic", utm_source: "google" };
+  }
+  if (referrerHost.includes("bing.")) {
+    return { utm_medium: "organic", utm_source: "bing" };
+  }
+
+  // External referral
+  return { utm_medium: "referral", utm_source: referrerHost };
+}
+
+/**
+ * Maps UTMProperties to Segment's campaign context schema.
+ * @param utms - The UTM properties (typically from cookie).
+ * @returns CampaignProperties for Segment context.
+ */
+export function getCampaignProperties(
+  utms: UTMProperties | null
+): CampaignProperties | null {
+  if (!utms) return null;
+
+  const campaign: CampaignProperties = {};
+
+  if (utms.utm_campaign) campaign.name = utms.utm_campaign;
+  if (utms.utm_source) campaign.source = utms.utm_source;
+  if (utms.utm_medium) campaign.medium = utms.utm_medium;
+  if (utms.utm_term) campaign.term = utms.utm_term;
+  if (utms.utm_content) campaign.content = utms.utm_content;
+  if (utms.utm_campaign_id) campaign.campaign_id = utms.utm_campaign_id;
+  if (utms.utm_adgroup_id) campaign.adgroup_id = utms.utm_adgroup_id;
+  if (utms.gclid) campaign.gclid = utms.gclid;
+  if (utms.fbclid) campaign.fbclid = utms.fbclid;
+  if (utms.msclkid) campaign.msclkid = utms.msclkid;
+
+  return Object.keys(campaign).length > 0 ? campaign : null;
+}
+
+/**
+ * Builds a URL with non-UTM query params preserved and UTM params stripped.
+ * Used by the Link/Button component when preserveQueryParameters is true.
+ *
+ * @param href - The target URL/path.
+ * @param currentSearch - The current page's search string (e.g. "?foo=bar&utm_source=google").
+ * @returns The href with non-UTM params merged and UTM params removed.
+ */
+export function buildPreservedQueryHref(
+  href: string,
+  currentSearch: string
+): string {
+  if (!currentSearch) return href;
+
+  const currentParams = new URLSearchParams(currentSearch);
+  const utmSet = new Set<string>(UTM_PARAM_NAMES);
+
+  // Also strip common non-UTM params that shouldn't carry forward
+  const stripParams = new Set([...utmSet, "searchtext", "page"]);
+
+  // Parse the target href to separate path and existing query
+  let basePath: string;
+  let targetParams: URLSearchParams;
+
+  try {
+    // Handle both absolute URLs and relative paths
+    if (href.startsWith("http://") || href.startsWith("https://")) {
+      const url = new URL(href);
+      basePath = url.origin + url.pathname;
+      targetParams = url.searchParams;
+    } else {
+      const [path, query] = href.split("?");
+      basePath = path;
+      targetParams = new URLSearchParams(query || "");
+    }
+  } catch {
+    return href;
+  }
+
+  // Start with target's existing params
+  const merged = new URLSearchParams(targetParams);
+
+  // Add current page params that aren't UTM and aren't already in target
+  currentParams.forEach((value, key) => {
+    if (!stripParams.has(key.toLowerCase()) && !merged.has(key)) {
+      merged.set(key, value);
+    }
+  });
+
+  const queryString = merged.toString();
+  return queryString ? `${basePath}?${queryString}` : basePath;
+}