@windstream/react-shared-components 0.2.86 → 0.2.88

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windstream/react-shared-components",
-  "version": "0.2.86",
+  "version": "0.2.88",
   "type": "module",
   "description": "Shared React components for Kinetic applications",
   "main": "dist/index.js",

package/src/components/checklist/index.test.tsx

@@ -19,11 +19,18 @@ jest.mock("@shared/components/list", () => ({
   ListItem: ({
     children,
     className,
+    ...rest
   }: {
     children: React.ReactNode;
     className?: string;
   }) => (
-    <li data-testid="list-item" className={className}>
+    <li
+      data-testid="list-item"
+      className={className}
+      {...Object.fromEntries(
+        Object.entries(rest).filter(([k]) => k.startsWith("data-"))
+      )}
+    >
       {children}
     </li>
   ),
@@ -109,6 +116,29 @@ describe("Checklist", () => {
     });
   });
 
+  describe("fieldProps", () => {
+    it("spreads each structured item's fieldProps onto its own row", () => {
+      render(
+        <Checklist
+          items={[
+            { title: "One", fieldProps: { "data-contentful-entry-id": "a" } },
+            { title: "Two", fieldProps: { "data-contentful-entry-id": "b" } },
+          ]}
+        />
+      );
+      const rows = screen.getAllByTestId("list-item");
+      expect(rows[0]).toHaveAttribute("data-contentful-entry-id", "a");
+      expect(rows[1]).toHaveAttribute("data-contentful-entry-id", "b");
+    });
+
+    it("renders no tagging attributes for plain or untagged items", () => {
+      render(<Checklist items={["Plain", { title: "Structured" }]} />);
+      screen.getAllByTestId("list-item").forEach(row => {
+        expect(row).not.toHaveAttribute("data-contentful-entry-id");
+      });
+    });
+  });
+
   describe("icons", () => {
     it("renders check icons by default", () => {
       render(<Checklist items={["Item 1"]} />);

package/src/components/checklist/index.tsx

@@ -74,6 +74,7 @@ export const Checklist: React.FC<ChecklistProps> = props => {
               `${showIcons ? "flex" : ""} ${iconPosition === "top" ? "items-start" : "items-center"} gap-2 text-text-secondary`,
               listItemClassName
             )}
+            {...(structured ? item.fieldProps : undefined)}
           >
             {showIcons && hasCustomIcon ? (
               <div className="flex shrink-0 leading-none">

package/src/components/checklist/types.ts

@@ -2,6 +2,8 @@ export type ChecklistItem = {
   title: React.ReactNode;
   iconUrl?: string;
   iconAlt?: string;
+  /** Extra DOM attribute props, spread onto this item's list row. */
+  fieldProps?: Record<string, unknown>;
 };
 
 export type ChecklistProps = {

package/src/contentful/blocks/accordion/index.test.tsx

@@ -10,6 +10,59 @@ const items: AccordionItem[] = [
 ];
 
 describe("Contentful Accordion", () => {
+  describe("fieldProps", () => {
+    const tag = (field: string) => ({
+      "data-contentful-field-id": field,
+    });
+
+    it("spreads block-level title fieldProps onto the heading", () => {
+      render(
+        <Accordion
+          items={items}
+          title="FAQ"
+          fieldProps={{ title: tag("title") }}
+        />
+      );
+      expect(screen.getByText("FAQ")).toHaveAttribute(
+        "data-contentful-field-id",
+        "title"
+      );
+    });
+
+    it("spreads per-item title and description fieldProps", () => {
+      render(
+        <Accordion
+          items={[
+            {
+              ...items[0],
+              fieldProps: {
+                title: tag("itemTitle"),
+                description: tag("itemDescription"),
+              },
+            },
+            items[1],
+          ]}
+          title="FAQ"
+        />
+      );
+      expect(document.getElementById("item-1")).toHaveAttribute(
+        "data-contentful-field-id",
+        "itemTitle"
+      );
+      expect(screen.getByText("Answer one")).toHaveAttribute(
+        "data-contentful-field-id",
+        "itemDescription"
+      );
+      expect(document.getElementById("item-2")).not.toHaveAttribute(
+        "data-contentful-field-id"
+      );
+    });
+
+    it("renders no tagging attributes when fieldProps is omitted", () => {
+      const { container } = render(<Accordion items={items} title="FAQ" />);
+      expect(container.querySelector("[data-contentful-field-id]")).toBeNull();
+    });
+  });
   beforeEach(() => {
     Object.defineProperty(window, "location", {
       writable: true,

package/src/contentful/blocks/accordion/index.tsx

@@ -18,6 +18,7 @@ export const Accordion: React.FC<AccordionProps> = ({
   hashAutoExpand = false,
   descriptionMaxWidth = "max-w-[980px]",
   itemContainerClassName,
+  fieldProps,
 }) => {
   const [expandedItems, setExpandedItems] = useState<string[]>(
     initialExpandedItemsProp
@@ -64,7 +65,8 @@ export const Accordion: React.FC<AccordionProps> = ({
         <Text
           as={enableHeading ? "h1" : "h2"}
           className="heading2 mb-10 pt-12 text-left text-text md:heading1 lg:text-center"
-        >
+                    {...fieldProps?.title}
+                  >
           {title}
         </Text>
         <div className={`pt-6 md:pt-10 ${itemContainerClassName ?? ""}`}>
@@ -79,6 +81,7 @@ export const Accordion: React.FC<AccordionProps> = ({
                 key={itemKey}
                 id={item.anchorId}
                 className="snap-start scroll-mt-48 lg:scroll-mt-60"
+                {...item.fieldProps?.title}
               >
                 <AccordionComponent
                   title={item.title}
@@ -96,7 +99,9 @@ export const Accordion: React.FC<AccordionProps> = ({
                   })}
                 >
                   <div className={descriptionMaxWidth}>
-                    <Text as="div">{item.description}</Text>
+                    <Text as="div" {...item.fieldProps?.description}>
+                      {item.description}
+                    </Text>
                   </div>
                 </AccordionComponent>
                 {index < items.length - 1 && (

package/src/contentful/blocks/accordion/types.ts

@@ -1,9 +1,12 @@
 import React from "react";
 
+import type { FieldProps } from "@shared/types/field-props";
+
 export type AccordionItem = {
   anchorId?: string;
   title: string;
   description: React.ReactNode;
+  fieldProps?: FieldProps<"title" | "description">;
 };
 
 export type AccordionProps = {
@@ -22,6 +25,7 @@ export type AccordionProps = {
   descriptionMaxWidth?: string;
   /** Custom class for the accordion list wrapper */
   itemContainerClassName?: string;
+  fieldProps?: FieldProps<"title">;
 };
 
 export type ThemeKey =

package/src/contentful/blocks/callout/{callout.stories.tsx → Callout.stories.tsx}

@@ -8,7 +8,7 @@ import {
   fourColumnItems,
   fullImageItems,
   withFloatingImageArgs,
-} from "./callout.stories.mocks";
+} from "./Callout.stories.mocks";
 
 import { DocsPage } from "@shared/stories/DocsTemplate";
 import type { Meta, StoryObj } from "@storybook/react";

package/src/contentful/blocks/callout/field-props.test.tsx

@@ -0,0 +1,184 @@
+import React from "react";
+import { Callout } from "./index";
+import type { CalloutItem } from "./types";
+
+import { fireEvent, render, screen } from "@testing-library/react";
+
+const tag = (entry: string, field: string) => ({
+  "data-contentful-entry-id": entry,
+  "data-contentful-field-id": field,
+  "data-contentful-locale": "en-US",
+});
+
+describe("Callout fieldProps", () => {
+  it("tags the block fields and retains CTA behavior", () => {
+    const onClick = jest.fn();
+    const { container } = render(
+      <Callout
+        items={[]}
+        title="Callout title"
+        subtitle="Callout subtitle"
+        description="Callout description"
+        finePrint="Callout fine print"
+        cta={{ buttonLabel: "Callout CTA", onClick }}
+        fieldProps={{
+          title: tag("callout", "title"),
+          subtitle: tag("callout", "subtitle"),
+          description: tag("callout", "description"),
+          finePrint: tag("callout", "finePrint"),
+          cta: tag("callout", "cta"),
+        }}
+      />
+    );
+    ["title", "subtitle", "description", "finePrint", "cta"].forEach(field => {
+      expect(
+        container.querySelector(`[data-contentful-field-id="${field}"]`)
+      ).toHaveAttribute("data-contentful-entry-id", "callout");
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Callout CTA" }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("preserves CTA entry tags when both the block and CTA supply attributes", () => {
+    render(
+      <Callout
+        items={[]}
+        cta={{
+          buttonLabel: "Nested CTA",
+          fieldProps: tag("button", "buttonLabel"),
+        }}
+        fieldProps={{ cta: tag("callout", "cta") }}
+      />
+    );
+    expect(screen.getByRole("button", { name: "Nested CTA" })).toHaveAttribute(
+      "data-contentful-entry-id",
+      "button"
+    );
+  });
+
+  it("tags custom CTA renderers without requiring them to forward attributes", () => {
+    const onClick = jest.fn();
+    render(
+      <Callout
+        items={[]}
+        cta={{
+          preDefinedFunctionExecution: "check availability",
+          renderCheckPlans: () => <button onClick={onClick}>Custom CTA</button>,
+        }}
+        fieldProps={{ cta: tag("callout", "cta") }}
+      />
+    );
+    const button = screen.getByRole("button", { name: "Custom CTA" });
+    expect(button.parentElement).toHaveAttribute(
+      "data-contentful-field-id",
+      "cta"
+    );
+    fireEvent.click(button);
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    { cardsWidth: true, disableAnimation: true },
+    { cardsWidth: true, disableAnimation: false },
+    { cardsWidth: false, disableAnimation: true },
+    { cardsWidth: false, disableAnimation: false },
+  ])("tags every card variant with layout/animation options %p", options => {
+    const items: CalloutItem[] = [
+      {
+        cardType: "simple",
+        title: "Simple title",
+        body: "Simple body",
+        richText: "Simple rich text",
+        cta: { buttonLabel: "Simple CTA" },
+        fieldProps: {
+          title: tag("simple", "title"),
+          body: tag("simple", "body"),
+          richText: tag("simple", "richText"),
+          cta: tag("simple", "cta"),
+        },
+      },
+      {
+        cardType: "blog",
+        title: "Blog title",
+        slug: "/blog",
+        shortDescription: "Blog excerpt",
+        fieldProps: {
+          title: tag("blog", "title"),
+          shortDescription: tag("blog", "shortDescription"),
+        },
+      },
+      {
+        cardType: "fullImage",
+        title: "Full image title",
+        description: "Full image description",
+        caption: "Full image caption",
+        cta: { buttonLabel: "Full image CTA" },
+        fieldProps: {
+          title: tag("full", "title"),
+          description: tag("full", "description"),
+          caption: tag("full", "caption"),
+          cta: tag("full", "cta"),
+        },
+      },
+      {
+        cardType: "floatingImage",
+        header: "Floating header",
+        body: "Floating body",
+        cta: { buttonLabel: "Floating CTA" },
+        fieldProps: {
+          header: tag("floating", "header"),
+          body: tag("floating", "body"),
+          cta: tag("floating", "cta"),
+        },
+      },
+      { title: "Untagged item" },
+    ];
+    const { container } = render(<Callout items={items} {...options} />);
+    items.forEach(item => {
+      Object.values(item.fieldProps ?? {}).forEach(attributes => {
+        const element = container.querySelector(
+          `[data-contentful-entry-id="${attributes["data-contentful-entry-id"]}"][data-contentful-field-id="${attributes["data-contentful-field-id"]}"]`
+        );
+        expect(element).toBeInTheDocument();
+        expect(element).toHaveAttribute("data-contentful-locale", "en-US");
+      });
+    });
+    expect(screen.getByText("Untagged item")).not.toHaveAttribute(
+      "data-contentful-field-id"
+    );
+    expect(screen.getByText("Blog title").closest("h2")).toHaveAttribute(
+      "data-contentful-entry-id",
+      "blog"
+    );
+    expect(screen.getByText("Simple body")).toHaveAttribute(
+      "data-contentful-field-id",
+      "body"
+    );
+  });
+
+  it("supports partial fieldProps without creating absent fields", () => {
+    const { container } = render(
+      <Callout
+        items={[]}
+        title="Only title"
+        fieldProps={{
+          title: tag("callout", "title"),
+          description: tag("callout", "description"),
+        }}
+      />
+    );
+    expect(
+      container.querySelectorAll("[data-contentful-field-id]")
+    ).toHaveLength(1);
+  });
+
+  it("does not add tagging attributes when fieldProps is omitted", () => {
+    const { container } = render(
+      <Callout
+        title="No tags"
+        items={[{ title: "Card", body: "Body", cta: { buttonLabel: "CTA" } }]}
+      />
+    );
+    expect(container.querySelector("[data-contentful-field-id]")).toBeNull();
+  });
+});

package/src/contentful/blocks/callout/index.tsx

@@ -82,6 +82,7 @@ export const Callout: React.FC<CalloutProps> = ({
   noGutter = false,
   disableAnimation,
   animationType = "lift",
+  fieldProps,
 }) => {
   const itemCount = items?.length ?? 0;
   const desktopCols = clampCol(
@@ -142,6 +143,12 @@ export const Callout: React.FC<CalloutProps> = ({
             image={blogItem.cover}
             imageAltText={blogItem.imageAltText}
             asGrid={false}
+            fieldProps={{
+              ...item.fieldProps,
+              description:
+                item.fieldProps?.shortDescription ??
+                item.fieldProps?.description,
+            }}
             {...widthProps}
           />
         );
@@ -197,7 +204,9 @@ export const Callout: React.FC<CalloutProps> = ({
     >
       <div
         className={cx(
-          noGutter ? "p-0" : "mx-5 mb-5 mt-12 md:mx-0 md:mb-0 md:mt-0 md:px-6 md:pb-8 md:pt-16 lg:px-0 lg:py-20",
+          noGutter
+            ? "p-0"
+            : "mx-5 mb-5 mt-12 md:mx-0 md:mb-0 md:mt-0 md:px-6 md:pb-8 md:pt-16 lg:px-0 lg:py-20",
           maxWidth && "max-w-120 xl:mx-auto",
           color === "dark" ? "text-text" : "text-white",
           innerClassName
@@ -209,6 +218,7 @@ export const Callout: React.FC<CalloutProps> = ({
               <Text
                 as={enableHeading ? "h1" : "h2"}
                 className="heading2 md:heading1 md:text-center"
+                {...fieldProps?.title}
               >
                 {title}
               </Text>
@@ -217,12 +227,17 @@ export const Callout: React.FC<CalloutProps> = ({
               <Text
                 as={enableHeading ? "h2" : "h3"}
                 className="subheading3 mt-2 md:subheading1 md:text-center lg:mt-3"
+                {...fieldProps?.subtitle}
               >
                 {subtitle}
               </Text>
             )}
             {description && (
-              <Text as="p" className="body1 mt-4 text-center md:mt-6">
+              <Text
+                as="p"
+                className="body1 mt-4 text-center md:mt-6"
+                {...fieldProps?.description}
+              >
                 {description}
               </Text>
             )}
@@ -253,7 +268,10 @@ export const Callout: React.FC<CalloutProps> = ({
             )}
           </div>
           {(cta || finePrint) && (
-            <div className="flex flex-col items-center gap-4">
+            <div
+              className="flex flex-col items-center gap-4"
+              {...(cta ? fieldProps?.cta : undefined)}
+            >
               {cta ? (
                 <Button
                   linkClassName="label1"
@@ -264,7 +282,11 @@ export const Callout: React.FC<CalloutProps> = ({
                 </Button>
               ) : null}
               {finePrint ? (
-                <Text as="div" className="footnote text-center text-text">
+                <Text
+                  as="div"
+                  className="footnote text-center text-text"
+                  {...fieldProps?.finePrint}
+                >
                   {finePrint}
                 </Text>
               ) : null}

package/src/contentful/blocks/callout/types.ts

@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 import type { ButtonProps } from "../button/types";
 
 import type { AnimationType } from "@shared/components/animation-wrapper";
+import type { FieldProps } from "@shared/types/field-props";
 
 export type CalloutCardType = "simple" | "blog" | "fullImage" | "floatingImage";
 
@@ -16,6 +17,17 @@ export type CalloutItem = {
    * Callout (e.g. one full-image + two simple cards).
    */
   cardType?: CalloutCardType;
+  /** Per-field DOM attributes for the selected card variant. */
+  fieldProps?: FieldProps<
+    | "title"
+    | "shortDescription"
+    | "description"
+    | "header"
+    | "body"
+    | "richText"
+    | "caption"
+    | "cta"
+  >;
   // Permissive shape — concrete card components validate their own subset.
   [key: string]: any;
 };
@@ -30,7 +42,7 @@ export type CalloutProps = {
   finePrint?: ReactNode;
   cta?: CalloutCtaProps;
   applyBoxShadow?: boolean;
-  cardStackingMobile?: boolean;  
+  cardStackingMobile?: boolean;
   color?: "dark" | "light";
   /**
    * When `true` (default) cards are laid out in a responsive Tailwind
@@ -74,4 +86,8 @@ export type CalloutProps = {
   disableAnimation?: boolean;
   /** Animation type(s) applied to each card. */
   animationType?: AnimationType | AnimationType[];
+  /** Consumer-supplied Inspector Mode attributes. `cta` tags the CTA/fine-print region; nested CTA fieldProps remain unchanged. */
+  fieldProps?: FieldProps<
+    "title" | "subtitle" | "description" | "finePrint" | "cta"
+  >;
 };

package/src/contentful/blocks/cards/blog-card/index.tsx

@@ -22,6 +22,7 @@ export const BlogCard: React.FC<BlogCardProps> = ({
   imageComponent: ImageComponent,
   asGrid = true,
   index,
+  fieldProps,
 }: BlogCardProps) => {
   const imageAlt =
     imageAltText ??
@@ -96,7 +97,7 @@ export const BlogCard: React.FC<BlogCardProps> = ({
 
         {/* Title */}
         {title && (
-          <Text as="h2" className="heading6">
+          <Text as="h2" className="heading6" {...fieldProps?.title}>
             <Link
               href={href}
               className="m-0 line-clamp-3 font-black transition-colors duration-150 after:absolute after:inset-0 after:z-10 after:content-[''] hover:text-text-brand group-hover:text-text-brand"
@@ -108,7 +109,10 @@ export const BlogCard: React.FC<BlogCardProps> = ({
 
         {/* Excerpt */}
         {description && (
-          <Text className="body1 m-0 line-clamp-3 flex-1 text-text">
+          <Text
+            className="body1 m-0 line-clamp-3 flex-1 text-text"
+            {...fieldProps?.description}
+          >
             {description}
           </Text>
         )}

package/src/contentful/blocks/cards/blog-card/types.ts

@@ -1,5 +1,7 @@
 import React from "react";
 
+import type { FieldProps } from "@shared/types/field-props";
+
 export interface BlogCardImageProps {
   src: string;
   alt: string;
@@ -32,4 +34,6 @@ export interface BlogCardProps {
   imageComponent?: React.ComponentType<BlogCardImageProps>;
   asGrid?: boolean;
   index?: number;
+  /** Per-field DOM attributes supplied by the consumer or parent Callout item. */
+  fieldProps?: FieldProps<"title" | "description">;
 }

package/src/contentful/blocks/cards/floating-image-card/index.tsx

@@ -33,6 +33,7 @@ export const FloatingImageCard: React.FC<FloatingImageCardProps> = ({
     isPromoBarImg = false,
     shadow = false,
     disableAnimation,
+    fieldProps,
   } = card;
 
   const ctaAlignmentClass = ctaAlignment
@@ -102,7 +103,7 @@ export const FloatingImageCard: React.FC<FloatingImageCardProps> = ({
       ) : null}
 
       {header ? (
-        <Text as="h4" className="heading6 text-text">
+        <Text as="h4" className="heading6 text-text" {...fieldProps?.header}>
           {header}
         </Text>
       ) : null}
@@ -111,12 +112,13 @@ export const FloatingImageCard: React.FC<FloatingImageCardProps> = ({
         <Text
           as="div"
           className="body1 -mt-1 mb-0 flex-1 text-text md:-mt-2 lg:mt-2"
+          {...fieldProps?.body}
         >
           {body}
         </Text>
       ) : null}
 
-      <div className={cx(ctaAlignmentClass, "mt-auto")}>
+      <div className={cx(ctaAlignmentClass, "mt-auto")} {...fieldProps?.cta}>
         {cta ? (
           <Button
             {...cta}

package/src/contentful/blocks/cards/floating-image-card/types.ts

@@ -1,6 +1,8 @@
 import type { ReactNode } from "react";
 import type { ButtonProps } from "../../button/types";
 
+import type { FieldProps } from "@shared/types/field-props";
+
 export type FloatingImageAsset = {
   href: string;
   title?: string;
@@ -27,6 +29,8 @@ export type FloatingImageCardItem = {
   shadow?: boolean;
   /** Disables the CTA hover/tap animation when true. */
   disableAnimation?: boolean;
+  /** Per-field DOM attributes supplied by the consumer or parent Callout item. */
+  fieldProps?: FieldProps<"header" | "body" | "cta">;
 };
 
 export type FloatingImageCardProps = {

package/src/contentful/blocks/cards/full-image-card/index.tsx

@@ -25,6 +25,7 @@ export const FullImageCard: React.FC<FullImageCardProps> = ({
     contentClassName,
     imageClassName,
     shadow = true,
+    fieldProps,
   } = card;
 
   const target = cta || link;
@@ -36,7 +37,13 @@ export const FullImageCard: React.FC<FullImageCardProps> = ({
     const img = (
       <NextImage
         src={image.href}
-        alt={imageAltText ?? image.description ?? image.title ?? title ?? "card-image"}
+        alt={
+          imageAltText ??
+          image.description ??
+          image.title ??
+          title ??
+          "card-image"
+        }
         width={image.width || 400}
         height={image.height || 280}
         className="w-full"
@@ -53,7 +60,11 @@ export const FullImageCard: React.FC<FullImageCardProps> = ({
   };
 
   const titleNode = title ? (
-    <Text as="h3" className="body1 text-text xl:heading6">
+    <Text
+      as="h3"
+      className="body1 text-text xl:heading6"
+      {...fieldProps?.title}
+    >
       {title}
     </Text>
   ) : null;
@@ -101,19 +112,27 @@ export const FullImageCard: React.FC<FullImageCardProps> = ({
               titleNode
             )}
             {description ? (
-              <Text as="p" className="body2 mt-4 text-text md:body1">
+              <Text
+                as="p"
+                className="body2 mt-4 text-text md:body1"
+                {...fieldProps?.description}
+              >
                 {description}
               </Text>
             ) : null}
           </div>
           {caption ? (
-            <Text as="p" className="footnote mt-5 text-text-secondary">
+            <Text
+              as="p"
+              className="footnote mt-5 text-text-secondary"
+              {...fieldProps?.caption}
+            >
               {caption}
             </Text>
           ) : null}
         </div>
         {cta ? (
-          <div className="mt-2 flex items-end">
+          <div className="mt-2 flex items-end" {...fieldProps?.cta}>
             <Button
               linkVariant="unstyled"
               linkClassName="label1 flex items-center gap-2 text-text"