@windstream/react-shared-components 0.1.93 → 0.1.94

package/src/components/image/Image.stories.tsx

@@ -1,113 +1,113 @@
-import { forwardRef } from "react";
-import { Image } from "./index";
-import type { ImageComponentProps } from "./types";
-
-import { DocsPage } from "@shared/stories/DocsTemplate";
-import type { Meta, StoryObj } from "@storybook/react";
-
-const meta: Meta<typeof Image> = {
-  title: "Components/Image",
-  component: Image,
-  tags: ["autodocs"],
-  parameters: {
-    layout: "centered",
-    docs: {
-      page: DocsPage,
-      description: {
-        component:
-          "A reusable image component that renders a native img by default. Pass the `as` prop with a custom component (e.g. next/image) to use Next.js Image or another image component.",
-      },
-    },
-  },
-  argTypes: {
-    src: {
-      control: { type: "text" },
-      description: "Image source URL",
-    },
-    alt: {
-      control: { type: "text" },
-      description:
-        "Alt text (required for accessibility; use empty string for decorative images)",
-    },
-    width: {
-      control: { type: "number" },
-      description: "Image width",
-    },
-    height: {
-      control: { type: "number" },
-      description: "Image height",
-    },
-    className: {
-      control: { type: "text" },
-      description: "Custom CSS classes",
-    },
-    loading: {
-      control: { type: "select" },
-      options: ["lazy", "eager"],
-      description: "Loading behavior",
-    },
-    as: {
-      description:
-        "Custom component to render (e.g. next/image). In a Next.js app: import Image from 'next/image' then use <Image as={Image} src={...} alt={...} width={...} height={...} />",
-      control: false,
-    },
-  },
-  args: {
-    src: "https://placehold.co/400x300",
-    alt: "Placeholder image",
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {
-  args: {},
-};
-
-export const WithDimensions: Story = {
-  args: {
-    src: "https://placehold.co/300x200",
-    alt: "Image with explicit dimensions",
-    width: 300,
-    height: 200,
-  },
-};
-
-export const WithClassName: Story = {
-  args: {
-    src: "https://placehold.co/400x300",
-    alt: "Styled image",
-    className: "rounded-lg object-cover shadow-md",
-    width: 400,
-    height: 300,
-  },
-};
-
-/** Mock component to demonstrate the `as` prop. In a Next.js app, pass next/image: <Image as={NextImage} ... /> */
-const MockImageComponent = forwardRef<HTMLImageElement, ImageComponentProps>(
-  (props, ref) => <img ref={ref} {...props} />
-);
-MockImageComponent.displayName = "MockImageComponent";
-
-export const WithCustomComponent: Story = {
-  render: args => (
-    <Image
-      {...args}
-      as={MockImageComponent}
-      src="https://placehold.co/350x150"
-      alt="Rendered via custom component (as prop)"
-      width={350}
-      height={150}
-      className="rounded border-2 border-dashed border-gray-300"
-    />
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Use the `as` prop to render with a custom component. In Next.js, pass the Image component from next/image for optimized images.",
-      },
-    },
-  },
-};
+import { forwardRef } from "react";
+import { Image } from "./index";
+import type { ImageComponentProps } from "./types";
+
+import { DocsPage } from "@shared/stories/DocsTemplate";
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: Meta<typeof Image> = {
+  title: "Components/Image",
+  component: Image,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+    docs: {
+      page: DocsPage,
+      description: {
+        component:
+          "A reusable image component that renders a native img by default. Pass the `as` prop with a custom component (e.g. next/image) to use Next.js Image or another image component.",
+      },
+    },
+  },
+  argTypes: {
+    src: {
+      control: { type: "text" },
+      description: "Image source URL",
+    },
+    alt: {
+      control: { type: "text" },
+      description:
+        "Alt text (required for accessibility; use empty string for decorative images)",
+    },
+    width: {
+      control: { type: "number" },
+      description: "Image width",
+    },
+    height: {
+      control: { type: "number" },
+      description: "Image height",
+    },
+    className: {
+      control: { type: "text" },
+      description: "Custom CSS classes",
+    },
+    loading: {
+      control: { type: "select" },
+      options: ["lazy", "eager"],
+      description: "Loading behavior",
+    },
+    as: {
+      description:
+        "Custom component to render (e.g. next/image). In a Next.js app: import Image from 'next/image' then use <Image as={Image} src={...} alt={...} width={...} height={...} />",
+      control: false,
+    },
+  },
+  args: {
+    src: "https://placehold.co/400x300",
+    alt: "Placeholder image",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {},
+};
+
+export const WithDimensions: Story = {
+  args: {
+    src: "https://placehold.co/300x200",
+    alt: "Image with explicit dimensions",
+    width: 300,
+    height: 200,
+  },
+};
+
+export const WithClassName: Story = {
+  args: {
+    src: "https://placehold.co/400x300",
+    alt: "Styled image",
+    className: "rounded-lg object-cover shadow-md",
+    width: 400,
+    height: 300,
+  },
+};
+
+/** Mock component to demonstrate the `as` prop. In a Next.js app, pass next/image: <Image as={NextImage} ... /> */
+const MockImageComponent = forwardRef<HTMLImageElement, ImageComponentProps>(
+  (props, ref) => <img ref={ref} {...props} />
+);
+MockImageComponent.displayName = "MockImageComponent";
+
+export const WithCustomComponent: Story = {
+  render: args => (
+    <Image
+      {...args}
+      as={MockImageComponent}
+      src="https://placehold.co/350x150"
+      alt="Rendered via custom component (as prop)"
+      width={350}
+      height={150}
+      className="rounded border-2 border-dashed border-gray-300"
+    />
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Use the `as` prop to render with a custom component. In Next.js, pass the Image component from next/image for optimized images.",
+      },
+    },
+  },
+};

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

@@ -0,0 +1,174 @@
+import "@testing-library/jest-dom";
+
+import React, { createRef, forwardRef } from "react";
+import { Image } from "./index";
+import { ImageComponentProps } from "./types";
+
+import { render, screen } from "@testing-library/react";
+
+// Mock cx
+jest.mock("@shared/utils", () => ({
+  cx: (...args: any[]) => args.filter(Boolean).join(" "),
+}));
+
+describe("Image", () => {
+  it("has displayName set to Image", () => {
+    expect(Image.displayName).toBe("Image");
+  });
+
+  describe("native img rendering", () => {
+    it("renders a native img element by default", () => {
+      render(<Image src="/test.png" alt="Test image" />);
+      const img = screen.getByAltText("Test image");
+      expect(img.tagName).toBe("IMG");
+    });
+
+    it("passes src prop to img", () => {
+      render(<Image src="/photo.jpg" alt="Photo" />);
+      const img = screen.getByAltText("Photo");
+      expect(img).toHaveAttribute("src", "/photo.jpg");
+    });
+
+    it("passes alt prop to img", () => {
+      render(<Image src="/img.png" alt="My image" />);
+      const img = screen.getByAltText("My image");
+      expect(img).toBeInTheDocument();
+    });
+
+    it("passes className to img", () => {
+      render(<Image src="/img.png" alt="Img" className="h-auto w-full" />);
+      const img = screen.getByAltText("Img");
+      expect(img).toHaveClass("w-full");
+      expect(img).toHaveClass("h-auto");
+    });
+
+    it("uses empty string className by default", () => {
+      render(<Image src="/img.png" alt="Img" />);
+      const img = screen.getByAltText("Img");
+      expect(img).toBeInTheDocument();
+    });
+
+    it("passes additional HTML img attributes", () => {
+      render(
+        <Image
+          src="/img.png"
+          alt="Img"
+          width={200}
+          height={100}
+          loading="lazy"
+        />
+      );
+      const img = screen.getByAltText("Img");
+      expect(img).toHaveAttribute("width", "200");
+      expect(img).toHaveAttribute("height", "100");
+      expect(img).toHaveAttribute("loading", "lazy");
+    });
+  });
+
+  describe("ref forwarding", () => {
+    it("forwards ref to native img element", () => {
+      const ref = createRef<HTMLImageElement>();
+      render(<Image ref={ref} src="/img.png" alt="Ref test" />);
+      expect(ref.current).toBeInstanceOf(HTMLImageElement);
+      expect(ref.current?.tagName).toBe("IMG");
+    });
+
+    it("forwards ref to custom component", () => {
+      const ref = createRef<HTMLImageElement>();
+      const CustomImage = forwardRef<HTMLImageElement, ImageComponentProps>(
+        function CustomImage(props, fwdRef) {
+          return <img ref={fwdRef} data-testid="custom-img" {...props} />;
+        }
+      );
+      render(
+        <Image ref={ref} as={CustomImage} src="/img.png" alt="Custom ref" />
+      );
+      expect(ref.current).toBeInstanceOf(HTMLImageElement);
+    });
+  });
+
+  describe("polymorphic rendering with 'as' prop", () => {
+    it("renders custom component when 'as' is provided", () => {
+      const CustomImage = (props: any) => (
+        <div data-testid="custom-image" data-src={props.src}>
+          {props.alt}
+        </div>
+      );
+      render(<Image as={CustomImage} src="/custom.png" alt="Custom" />);
+      expect(screen.getByTestId("custom-image")).toBeInTheDocument();
+      expect(screen.getByTestId("custom-image")).toHaveAttribute(
+        "data-src",
+        "/custom.png"
+      );
+    });
+
+    it("passes className to custom component", () => {
+      const CustomImage = ({ className, ...props }: any) => (
+        <img data-testid="custom-img" className={className} {...props} />
+      );
+      render(
+        <Image as={CustomImage} src="/img.png" alt="Cls" className="rounded" />
+      );
+      const img = screen.getByTestId("custom-img");
+      expect(img).toHaveClass("rounded");
+    });
+
+    it("passes all props to custom component", () => {
+      const CustomImage = (props: any) => (
+        <img
+          data-testid="custom-img"
+          data-fill={props.fill?.toString()}
+          data-priority={props.priority?.toString()}
+          src={props.src}
+          alt={props.alt}
+        />
+      );
+      render(
+        <Image
+          as={CustomImage}
+          src="/img.png"
+          alt="Props test"
+          fill={true}
+          priority={true}
+        />
+      );
+      const img = screen.getByTestId("custom-img");
+      expect(img).toHaveAttribute("data-fill", "true");
+      expect(img).toHaveAttribute("data-priority", "true");
+    });
+
+    it("does not render native img when as prop is provided", () => {
+      const CustomImage = (props: any) => (
+        <div data-testid="custom-wrapper">{props.alt}</div>
+      );
+      render(<Image as={CustomImage} src="/img.png" alt="No native" />);
+      expect(screen.queryByRole("img")).not.toBeInTheDocument();
+    });
+
+    it("renders forwardRef component via as prop", () => {
+      const ForwardRefImage = forwardRef<HTMLImageElement, ImageComponentProps>(
+        function ForwardRefImage(props, fwdRef) {
+          return <img ref={fwdRef} data-testid="fwdref-img" {...props} />;
+        }
+      );
+      render(
+        <Image as={ForwardRefImage} src="/img.png" alt="ForwardRef test" />
+      );
+      expect(screen.getByTestId("fwdref-img")).toBeInTheDocument();
+    });
+  });
+
+  describe("edge cases", () => {
+    it("renders with empty alt for decorative images", () => {
+      const { container } = render(<Image src="/decorative.png" alt="" />);
+      const img = container.querySelector("img");
+      expect(img).toHaveAttribute("alt", "");
+    });
+
+    it("renders with no className (defaults to empty string)", () => {
+      const { container } = render(<Image src="/img.png" alt="No class" />);
+      const img = container.querySelector("img");
+      expect(img).toBeInTheDocument();
+    });
+  });
+});

package/src/components/image/index.tsx

@@ -1,25 +1,25 @@
-"use client";
-
-import { forwardRef } from "react";
-
-import type { ImageProps } from "@shared/components/image/types";
-import { cx } from "@shared/utils";
-
-export const Image = forwardRef<HTMLImageElement, ImageProps>(
-  ({ as: ImageComponent, className = "", ...rest }, ref) => {
-    const combinedClassName = cx(className);
-
-    if (ImageComponent) {
-      // Cast to any to allow ref forwarding for custom components
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const Component = ImageComponent as any;
-      return <Component ref={ref} className={combinedClassName} {...rest} />;
-    }
-
-    return <img ref={ref} className={combinedClassName} {...rest} />;
-  }
-);
-
-Image.displayName = "Image";
-
-export type { ImageProps, ImageComponentProps } from "./types";
+"use client";
+
+import { forwardRef } from "react";
+
+import type { ImageProps } from "@shared/components/image/types";
+import { cx } from "@shared/utils";
+
+export const Image = forwardRef<HTMLImageElement, ImageProps>(
+  ({ as: ImageComponent, className = "", ...rest }, ref) => {
+    const combinedClassName = cx(className);
+
+    if (ImageComponent) {
+      // Cast to any to allow ref forwarding for custom components
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const Component = ImageComponent as any;
+      return <Component ref={ref} className={combinedClassName} {...rest} />;
+    }
+
+    return <img ref={ref} className={combinedClassName} {...rest} />;
+  }
+);
+
+Image.displayName = "Image";
+
+export type { ImageProps, ImageComponentProps } from "./types";

package/src/components/image/types.ts

@@ -1,40 +1,40 @@
-import type {
-  ComponentType,
-  ForwardRefExoticComponent,
-  ImgHTMLAttributes,
-  RefAttributes,
-} from "react";
-
-/**
- * Props passed to the custom image component when using the `as` prop.
- * Covers native img attributes plus optional Next.js Image props (fill, sizes, priority, etc.).
- */
-export interface ImageComponentProps
-  extends Omit<ImgHTMLAttributes<HTMLImageElement>, "alt"> {
-  /** Image source URL */
-  src: string;
-  /** Alt text (required for accessibility; use "" for decorative images) */
-  alt: string;
-  /** Optional; used by Next.js Image when using fill layout */
-  fill?: boolean;
-  /** Optional; used by Next.js Image for responsive sizes */
-  sizes?: string;
-  /** Optional; used by Next.js Image for priority loading */
-  priority?: boolean;
-  /** Optional; used by Next.js Image for blur placeholder */
-  placeholder?: "blur" | "empty";
-  /** Optional; used by Next.js Image for quality (1–100) */
-  quality?: number;
-}
-
-/** Type for custom image component that supports ref forwarding */
-type ImageComponent =
-  | ComponentType<ImageComponentProps>
-  | ForwardRefExoticComponent<
-      ImageComponentProps & RefAttributes<HTMLImageElement>
-    >;
-
-export interface ImageProps extends ImageComponentProps {
-  /** Custom component to render instead of native img (e.g. next/image) */
-  as?: ImageComponent;
-}
+import type {
+  ComponentType,
+  ForwardRefExoticComponent,
+  ImgHTMLAttributes,
+  RefAttributes,
+} from "react";
+
+/**
+ * Props passed to the custom image component when using the `as` prop.
+ * Covers native img attributes plus optional Next.js Image props (fill, sizes, priority, etc.).
+ */
+export interface ImageComponentProps
+  extends Omit<ImgHTMLAttributes<HTMLImageElement>, "alt"> {
+  /** Image source URL */
+  src: string;
+  /** Alt text (required for accessibility; use "" for decorative images) */
+  alt: string;
+  /** Optional; used by Next.js Image when using fill layout */
+  fill?: boolean;
+  /** Optional; used by Next.js Image for responsive sizes */
+  sizes?: string;
+  /** Optional; used by Next.js Image for priority loading */
+  priority?: boolean;
+  /** Optional; used by Next.js Image for blur placeholder */
+  placeholder?: "blur" | "empty";
+  /** Optional; used by Next.js Image for quality (1–100) */
+  quality?: number;
+}
+
+/** Type for custom image component that supports ref forwarding */
+type ImageComponent =
+  | ComponentType<ImageComponentProps>
+  | ForwardRefExoticComponent<
+      ImageComponentProps & RefAttributes<HTMLImageElement>
+    >;
+
+export interface ImageProps extends ImageComponentProps {
+  /** Custom component to render instead of native img (e.g. next/image) */
+  as?: ImageComponent;
+}