@windstream/react-shared-components 0.2.48 → 0.2.50

package/src/components/precisely-address-autocomplete/index.test.tsx

@@ -0,0 +1,159 @@
+import "@testing-library/jest-dom";
+
+import { AddressAutocomplete } from "./index";
+
+import { fireEvent, render, screen } from "@testing-library/react";
+
+const suggestions = [
+  {
+    address: {
+      addressLine1: "123 Dale Springs",
+      addressLine2: "Apt B",
+      city: "Binsport",
+      state: "NC",
+      postalCode: "17032",
+      providerId: "candidate-1",
+    },
+    mainText: "123 Dale Springs",
+    placeId: "place-1",
+    provider: "precisely",
+  },
+];
+
+describe("AddressAutocomplete", () => {
+  it("requests suggestions and displays results at the minimum query length", () => {
+    const onChange = jest.fn();
+    render(
+      <AddressAutocomplete suggestions={suggestions} onChange={onChange} />
+    );
+
+    const input = screen.getByRole("combobox");
+    fireEvent.change(input, { target: { value: "12" } });
+    expect(
+      screen.queryByTestId("address-autocomplete-suggestions")
+    ).not.toBeInTheDocument();
+
+    fireEvent.change(input, { target: { value: "123" } });
+    expect(onChange).toHaveBeenLastCalledWith("123");
+    expect(
+      screen.getByTestId("address-autocomplete-suggestions")
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("address-autocomplete-suggestions")).toHaveClass(
+      "max-h-[220px]",
+      "overflow-y-auto",
+      "p-0",
+      "border",
+      "border-input-border",
+      "bg-bg-surface",
+      "shadow-dark-drop"
+    );
+    expect(
+      screen.getByRole("button", { name: /123 Dale Springs/i })
+    ).toHaveClass("px-4");
+    expect(screen.getByRole("combobox").parentElement).toHaveClass("pl-4");
+    expect(screen.getAllByText("location_on")[0]).toHaveClass(
+      "text-icon-brand"
+    );
+  });
+
+  it("uses the input pin color for each suggestion pin", () => {
+    render(
+      <AddressAutocomplete
+        defaultValue="123"
+        suggestions={suggestions}
+        prefixIconClassName="text-input-icon-placeholder"
+      />
+    );
+
+    fireEvent.focus(screen.getByRole("combobox"));
+    const pins = screen.getAllByText("location_on");
+    expect(pins).toHaveLength(2);
+    pins.forEach(pin => {
+      expect(pin).toHaveClass("text-input-icon-placeholder");
+      expect(pin).toHaveClass(
+        "inline-flex",
+        "items-center",
+        "justify-center",
+        "leading-none"
+      );
+    });
+  });
+
+  it("returns the selected provider address without requesting again", () => {
+    const onChange = jest.fn();
+    const onSelectAddress = jest.fn();
+    render(
+      <AddressAutocomplete
+        defaultValue="123"
+        suggestions={suggestions}
+        onChange={onChange}
+        onSelectAddress={onSelectAddress}
+      />
+    );
+
+    fireEvent.focus(screen.getByRole("combobox"));
+    fireEvent.click(screen.getByRole("button", { name: /123 Dale Springs/i }));
+
+    expect(onSelectAddress).toHaveBeenCalledWith({
+      address: "123 Dale Springs, Apt B, Binsport, NC, 17032",
+      unit: "Apt B",
+      addressToSend: suggestions[0].address,
+      placeId: "place-1",
+    });
+    expect(onChange).not.toHaveBeenCalled();
+    expect(screen.getByRole("combobox")).toHaveValue(
+      "123 Dale Springs, Apt B, Binsport, NC, 17032"
+    );
+  });
+
+  it("clears the selected address when the input is emptied", () => {
+    const onSelectAddress = jest.fn();
+    render(
+      <AddressAutocomplete
+        defaultValue="123"
+        onSelectAddress={onSelectAddress}
+      />
+    );
+
+    fireEvent.change(screen.getByRole("combobox"), {
+      target: { value: "" },
+    });
+    expect(onSelectAddress).toHaveBeenCalledWith();
+  });
+
+  it("focuses and reports load when its provider becomes ready", () => {
+    const onLoadProvider = jest.fn();
+    const { rerender } = render(
+      <AddressAutocomplete isReady={false} onLoadProvider={onLoadProvider} />
+    );
+    const input = screen.getByRole("combobox");
+
+    expect(input).toBeDisabled();
+    expect(onLoadProvider).not.toHaveBeenCalled();
+
+    rerender(
+      <AddressAutocomplete isReady={true} onLoadProvider={onLoadProvider} />
+    );
+    expect(input).toHaveFocus();
+    expect(onLoadProvider).toHaveBeenCalledTimes(1);
+  });
+
+  it("dismisses suggestions after an outside click", () => {
+    render(
+      <div>
+        <AddressAutocomplete defaultValue="123" suggestions={suggestions} />
+        <button type="button">Outside</button>
+      </div>
+    );
+
+    fireEvent.focus(screen.getByRole("combobox"));
+    expect(
+      screen.getByTestId("address-autocomplete-suggestions")
+    ).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Outside" }));
+    expect(
+      screen.queryByTestId("address-autocomplete-suggestions")
+    ).not.toBeInTheDocument();
+  });
+});

package/src/components/precisely-address-autocomplete/index.tsx

@@ -0,0 +1,219 @@
+"use client";
+
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import type {
+  AddressAutocompleteAddress,
+  AddressAutocompleteProps,
+  AddressAutocompleteSuggestion,
+} from "./types";
+
+import { Input } from "@shared/components/input";
+import { MaterialIcon } from "@shared/components/material-icon";
+import { useOutsideClick } from "@shared/hooks/use-outside-click";
+import { cx } from "@shared/utils";
+
+const formatSuggestion = <TAddress extends AddressAutocompleteAddress>(
+  suggestion: AddressAutocompleteSuggestion<TAddress>
+) => {
+  const { address, mainText, postalCode: suggestionPostalCode } = suggestion;
+  if (!address) {
+    return { primaryText: mainText, secondaryText: "", value: mainText };
+  }
+
+  const primaryText = [address.addressLine1, address.addressLine2]
+    .filter(Boolean)
+    .join(", ");
+  const secondaryText = [
+    address.city,
+    address.state,
+    address.postalCode || suggestionPostalCode,
+  ]
+    .filter(Boolean)
+    .join(", ");
+
+  return {
+    primaryText: primaryText || mainText,
+    secondaryText,
+    value: [primaryText, secondaryText].filter(Boolean).join(", ") || mainText,
+  };
+};
+
+export const AddressAutocomplete = <
+  TAddress extends AddressAutocompleteAddress = AddressAutocompleteAddress,
+>({
+  className,
+  containerClassName,
+  defaultValue = "",
+  errorText,
+  fixedPositionedSuggestions = false,
+  focusOnLoad = true,
+  hasError,
+  inputContainerClassName,
+  isIframe = false,
+  isLoading = false,
+  isReady = true,
+  mapPinIcon = true,
+  minQueryLength = 3,
+  onChange,
+  onFocus,
+  onLoadProvider,
+  onSelectAddress,
+  onSuggestionsChange,
+  optionsContainerClassName,
+  prefixIconClassName = "text-icon-brand",
+  suggestions = [],
+  value: controlledValue,
+  ...inputProps
+}: AddressAutocompleteProps<TAddress>) => {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const suggestionsId = useId();
+  const [value, setValue] = useState(controlledValue ?? defaultValue);
+  const [showSuggestions, setShowSuggestions] = useState(false);
+  const pinIconClassName = cx(
+    "inline-flex items-center justify-center leading-none",
+    prefixIconClassName
+  );
+
+  useEffect(() => {
+    if (controlledValue !== undefined) setValue(controlledValue);
+  }, [controlledValue]);
+
+  useEffect(() => {
+    if (isReady && focusOnLoad) inputRef.current?.focus();
+  }, [focusOnLoad, isReady]);
+
+  useEffect(() => {
+    if (isReady) onLoadProvider?.();
+  }, [isReady, onLoadProvider]);
+
+  useEffect(() => {
+    onSuggestionsChange?.(suggestions);
+  }, [onSuggestionsChange, suggestions]);
+
+  useOutsideClick(rootRef, () => setShowSuggestions(false));
+
+  const selectSuggestion = useCallback(
+    (suggestion: AddressAutocompleteSuggestion<TAddress>) => {
+      if (!suggestion.address) return;
+
+      const formatted = formatSuggestion(suggestion);
+      setValue(formatted.value);
+      setShowSuggestions(false);
+      onSelectAddress?.({
+        address: formatted.value,
+        unit: suggestion.address.addressLine2 || "",
+        addressToSend: suggestion.address,
+        placeId: suggestion.placeId || "",
+      });
+    },
+    [onSelectAddress]
+  );
+
+  const hasSuggestions =
+    showSuggestions &&
+    value.length >= minQueryLength &&
+    !isLoading &&
+    suggestions.length > 0;
+
+  return (
+    <div
+      ref={rootRef}
+      className={cx("relative min-w-[300px] text-text", containerClassName)}
+    >
+      <Input
+        {...inputProps}
+        ref={inputRef}
+        size="medium"
+        value={value}
+        className={cx(
+          "mx-auto w-full bg-transparent pl-2 placeholder:text-input-text-placeholder",
+          "body2",
+          className
+        )}
+        containerClassName={cx("pl-4", inputContainerClassName)}
+        loading={!isReady}
+        onChange={event => {
+          const nextValue = event.target.value;
+          setValue(nextValue);
+          setShowSuggestions(nextValue.length >= minQueryLength);
+          if (!nextValue) onSelectAddress?.();
+          onChange?.(nextValue);
+        }}
+        onFocus={event => {
+          setShowSuggestions(true);
+          onFocus?.(event);
+        }}
+        autoComplete="off"
+        role="combobox"
+        aria-autocomplete="list"
+        aria-controls={suggestionsId}
+        aria-expanded={hasSuggestions}
+        data-cy="address-autocomplete-input"
+        data-testid="address-autocomplete-input"
+        prefixIconName={mapPinIcon ? "location_on" : undefined}
+        prefixIconFill={true}
+        prefixIconClassName={pinIconClassName}
+        errorText={errorText}
+        state={errorText || hasError ? "error" : inputProps.state}
+        hasError={hasError}
+      />
+
+      {hasSuggestions && (
+        <ul
+          id={suggestionsId}
+          role="listbox"
+          data-cy="address-autocomplete-suggestions"
+          data-testid="address-autocomplete-suggestions"
+          className={cx(
+            "shadow-dark-drop absolute top-full z-20 m-0 mt-1 w-full list-none overflow-y-auto overscroll-contain rounded-lg border border-input-border bg-bg-surface p-0",
+            isIframe ? "max-h-[117px]" : "max-h-[220px]",
+            fixedPositionedSuggestions &&
+              (isIframe
+                ? "fixed z-50 max-h-[117px]"
+                : "fixed z-50 max-h-[220px]"),
+            optionsContainerClassName
+          )}
+        >
+          {suggestions.map((suggestion, index) => {
+            const { primaryText, secondaryText } = formatSuggestion(suggestion);
+            return (
+              <li
+                role="option"
+                aria-selected="false"
+                key={suggestion.placeId || `${suggestion.mainText}-${index}`}
+              >
+                <button
+                  type="button"
+                  className="flex w-full items-center px-4 py-4 text-left hover:bg-bg-surface-secondary"
+                  onClick={() => selectSuggestion(suggestion)}
+                >
+                  <MaterialIcon
+                    fill={1}
+                    name="location_on"
+                    size={24}
+                    weight="200"
+                    className={cx("mr-4 min-w-[24px]", pinIconClassName)}
+                  />
+                  <span>
+                    <span>{primaryText}</span>
+                    {secondaryText && (
+                      <small className="ml-1">{secondaryText}</small>
+                    )}
+                  </span>
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+};
+
+export type {
+  AddressAutocompleteAddress,
+  AddressAutocompleteProps,
+  AddressAutocompleteResult,
+  AddressAutocompleteSuggestion,
+} from "./types";

package/src/components/precisely-address-autocomplete/types.ts

@@ -0,0 +1,54 @@
+import type { InputFieldProps } from "@shared/components/input";
+
+export type AddressAutocompleteAddress = {
+  addressLine1?: string;
+  addressLine2?: string | null;
+  city?: string;
+  state?: string;
+  postalCode?: string;
+};
+
+export type AddressAutocompleteSuggestion<
+  TAddress extends AddressAutocompleteAddress = AddressAutocompleteAddress,
+> = {
+  address?: TAddress;
+  mainText: string;
+  placeId?: string;
+  postalCode?: string;
+  provider?: string;
+};
+
+export type AddressAutocompleteResult<
+  TAddress extends AddressAutocompleteAddress = AddressAutocompleteAddress,
+> = {
+  address: string;
+  unit: string;
+  addressToSend: TAddress;
+  placeId: string;
+};
+
+export type AddressAutocompleteProps<
+  TAddress extends AddressAutocompleteAddress = AddressAutocompleteAddress,
+> = Omit<
+  InputFieldProps,
+  "defaultValue" | "loading" | "onChange" | "size" | "value"
+> & {
+  value?: string;
+  defaultValue?: string;
+  suggestions?: AddressAutocompleteSuggestion<TAddress>[];
+  isLoading?: boolean;
+  isReady?: boolean;
+  focusOnLoad?: boolean;
+  minQueryLength?: number;
+  mapPinIcon?: boolean;
+  fixedPositionedSuggestions?: boolean;
+  isIframe?: boolean;
+  inputContainerClassName?: string;
+  optionsContainerClassName?: string;
+  onChange?: (value: string) => void;
+  onSelectAddress?: (result?: AddressAutocompleteResult<TAddress>) => void;
+  onSuggestionsChange?: (
+    suggestions: AddressAutocompleteSuggestion<TAddress>[]
+  ) => void;
+  onLoadProvider?: () => void;
+};

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

@@ -258,10 +258,10 @@ describe("Callout", () => {
       expect(gridHolder?.className).not.toContain("gap-6");
     });
 
-    it("has gap-6 by default", () => {
+    it("has gap-3 by default", () => {
       const { container } = render(<Callout {...defaultProps} />);
       const gridHolder = container.querySelector(".card-holder");
-      expect(gridHolder?.className).toContain("gap-6");
+      expect(gridHolder?.className).toContain("gap-3");
     });
 
     it("calculates 3 columns for 6 items (divisible by 3)", () => {

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

@@ -140,6 +140,7 @@ export const Callout: React.FC<CalloutProps> = ({
             date={blogItem.blogCreationDate}
             category={blogItem.category}
             image={blogItem.cover}
+            imageAltText={blogItem.imageAltText}
             asGrid={false}
             {...widthProps}
           />

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

@@ -18,10 +18,17 @@ export const BlogCard: React.FC<BlogCardProps> = ({
   date,
   category,
   image,
+  imageAltText,
   imageComponent: ImageComponent,
   asGrid = true,
   index,
 }: BlogCardProps) => {
+  const imageAlt =
+    imageAltText ??
+    image?.description ??
+    image?.alt ??
+    title ??
+    "blog-card-image";
   const parentClassName = asGrid
     ? "group relative flex h-full flex-col overflow-hidden rounded-card-lg bg-white shadow-drop transition-all duration-200 hover:-translate-y-0.5 hover:shadow-cardDrop"
     : `callout-card group relative w-full flex h-full flex-col overflow-hidden`;
@@ -40,7 +47,7 @@ export const BlogCard: React.FC<BlogCardProps> = ({
             ImageComponent ? (
               <ImageComponent
                 src={image.src}
-                alt={image.alt}
+                alt={imageAlt}
                 width={image.width}
                 height={image.height}
                 className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-[1.03]"
@@ -49,7 +56,7 @@ export const BlogCard: React.FC<BlogCardProps> = ({
             ) : (
               <img
                 src={image.src}
-                alt={image.alt}
+                alt={imageAlt}
                 width={image.width}
                 height={image.height}
                 loading="lazy"

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

@@ -21,9 +21,13 @@ export interface BlogCardProps {
   image?: {
     src: string;
     alt: string;
+    /** Contentful asset description — used as the alt-text fallback. */
+    description?: string;
     width: number;
     height: number;
   };
+  /** Explicit image alt text; falls back to the image description then alt. */
+  imageAltText?: string;
   /** Pass next/image's Image component here to enable image optimization */
   imageComponent?: React.ComponentType<BlogCardImageProps>;
   asGrid?: boolean;

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

@@ -7,10 +7,11 @@ import { NextImage } from "@shared/components/next-image";
 import { Text } from "@shared/components/text";
 import { cx } from "@shared/utils";
 
+// Block (full-width) on mobile so the button fills the card; flex alignment only on desktop.
 const alignmentClasses: Record<string, string> = {
-  left: "flex w-full justify-start",
-  right: "flex w-full justify-end",
-  center: "flex w-full justify-center",
+  left: "w-full lg:flex lg:justify-start",
+  right: "w-full lg:flex lg:justify-end",
+  center: "w-full lg:flex lg:justify-center",
 };
 
 export const FloatingImageCard: React.FC<FloatingImageCardProps> = ({
@@ -28,6 +29,7 @@ export const FloatingImageCard: React.FC<FloatingImageCardProps> = ({
     imageLink,
     imageClassName,
     className,
+    imageAltText,
     isPromoBarImg = false,
     shadow = false,
     disableAnimation,
@@ -50,7 +52,13 @@ export const FloatingImageCard: React.FC<FloatingImageCardProps> = ({
     return image?.href ? (
       <NextImage
         src={image.href}
-        alt={image.title ?? title ?? "promo-bar-image"}
+        alt={
+          imageAltText ??
+          image.description ??
+          image.title ??
+          title ??
+          "promo-bar-image"
+        }
         width={148}
         height={40}
         onClick={handleImageClick}
@@ -73,13 +81,15 @@ export const FloatingImageCard: React.FC<FloatingImageCardProps> = ({
       {image?.href ? (
         <div
           className={cx(
-            "relative h-[233px] w-full overflow-hidden sm:mb-1 md:h-[274px] md:flex-none lg:h-[330px] lg:mb-0",
+            "relative h-[233px] w-full overflow-hidden sm:mb-1 md:h-[274px] md:flex-none lg:mb-0 lg:h-[330px]",
             imageClassName
           )}
         >
           <NextImage
             src={image.href}
-            alt={image.title ?? title ?? "card-image"}
+            alt={
+              imageAltText ?? image.description ?? image.title ?? "card-image"
+            }
             width={image.width || 400}
             height={image.height || 330}
             onClick={handleImageClick}
@@ -98,7 +108,10 @@ export const FloatingImageCard: React.FC<FloatingImageCardProps> = ({
       ) : null}
 
       {body ? (
-        <Text as="div" className="body1 -mt-1 mb-0 flex-1 text-text md:-mt-2 lg:mt-2">
+        <Text
+          as="div"
+          className="body1 -mt-1 mb-0 flex-1 text-text md:-mt-2 lg:mt-2"
+        >
           {body}
         </Text>
       ) : null}
@@ -108,10 +121,12 @@ export const FloatingImageCard: React.FC<FloatingImageCardProps> = ({
           <Button
             {...cta}
             showButtonAs={
-              cta.showButtonAs || (cta.buttonIconName ? undefined : "text-with-icon")
+              cta.showButtonAs ||
+              (cta.buttonIconName ? undefined : "text-with-icon")
             }
             iconName={
-              cta.iconName || (cta.buttonIconName ? undefined : "expand_circle_right")
+              cta.iconName ||
+              (cta.buttonIconName ? undefined : "expand_circle_right")
             }
             iconFill={cta.iconFill ?? 1}
             // Button animates ONLY when BOTH are explicitly enabled:

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

@@ -4,6 +4,8 @@ import type { ButtonProps } from "../../button/types";
 export type FloatingImageAsset = {
   href: string;
   title?: string;
+  /** Contentful asset description — used as the alt-text fallback. */
+  description?: string;
   width?: number;
   height?: number;
 };
@@ -15,6 +17,8 @@ export type FloatingImageCardItem = {
   cta?: ButtonProps;
   ctaAlignment?: "left" | "right" | "center";
   image?: FloatingImageAsset;
+  /** Explicit image alt text; falls back to the image asset description. */
+  imageAltText?: string;
   imageLink?: string;
   imageClassName?: string;
   className?: string;

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

@@ -18,6 +18,7 @@ export const FullImageCard: React.FC<FullImageCardProps> = ({
     description,
     caption,
     image,
+    imageAltText,
     cta,
     link,
     className,
@@ -35,7 +36,7 @@ export const FullImageCard: React.FC<FullImageCardProps> = ({
     const img = (
       <NextImage
         src={image.href}
-        alt={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"

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

@@ -3,6 +3,8 @@ import type { ButtonProps } from "../../button/types";
 export type FullImageAsset = {
   href: string;
   title?: string;
+  /** Contentful asset description — used as the alt-text fallback. */
+  description?: string;
   width?: number;
   height?: number;
 };
@@ -15,6 +17,8 @@ export type FullImageCardItem = {
   cta?: ButtonProps;
   link?: ButtonProps;
   image?: FullImageAsset;
+  /** Explicit image alt text; falls back to the image asset description. */
+  imageAltText?: string;
   className?: string;
   contentClassName?: string;
   imageClassName?: string;

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

@@ -97,7 +97,7 @@ export const SimpleCard: React.FC<SimpleCardProps> = ({
       >
         <NextImage
           src={card.image}
-          alt={card.imageAlt ?? card.title ?? "card-image"}
+          alt={card.imageAltText ?? card.imageDescription ?? card.imageAlt ?? card.title ?? "card-image"}
           width={card.imageWidth || 400}
           height={card.imageHeight || 280}
           className={cx("w-full", !margin && "rounded-t-3xl")}
@@ -124,7 +124,7 @@ export const SimpleCard: React.FC<SimpleCardProps> = ({
       >
         <NextImage
           src={card.image}
-          alt={card.imageAlt ?? card.title ?? "card-icon"}
+          alt={card.imageAltText ?? card.imageDescription ?? card.imageAlt ?? card.title ?? "card-icon"}
           width={imgWidth}
           height={imgHeight}
           className={cx(
@@ -331,7 +331,8 @@ export const SimpleCard: React.FC<SimpleCardProps> = ({
               fullWidth={true}
               buttonClassName={cx(
                 card.cta.buttonClassName,
-                isCtaOnly && "w-[342px] max-w-full lg:w-[342px]"
+                // Narrower padding so long labels still fit the fixed width.
+                isCtaOnly && "w-[342px] max-w-full px-4 lg:w-[342px]"
               )}
             />
           </div>

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

@@ -17,6 +17,10 @@ export type Item = {
   title?: string;
   image?: string;
   imageAlt?: string;
+  /** Explicit image alt text; takes priority over the description fallback. */
+  imageAltText?: string;
+  /** Contentful asset description — used as the alt-text fallback. */
+  imageDescription?: string;
   imageWidth?: number;
   imageHeight?: number;
   imageAlignment?: "left" | "right" | "center";