@sproutsocial/seeds-react-narrative-kit 0.3.0 → 0.5.0

package/src/NarrativeOrderedList/NarrativeOrderedListTypes.ts

@@ -0,0 +1,39 @@
+import type * as React from "react";
+
+/**
+ * Item arrangement.
+ * - `"vertical"`: items stacked full-width, one per row (the default).
+ * - `"horizontal"`: items laid out as a row of equal columns that collapses
+ *   back to a stack when the container is narrow (container query).
+ */
+export type TypeNarrativeOrderedListOrientation = "vertical" | "horizontal";
+
+export interface TypeNarrativeOrderedListItem {
+  /** Bold action title for the item. A plain string or any React node. */
+  title: React.ReactNode;
+  /**
+   * Descriptive text below the title. A plain string or any React node. The
+   * paragraph is omitted when this is empty.
+   */
+  description?: React.ReactNode;
+  /**
+   * Optional call-to-action rendered below the description, only when provided.
+   * Typically a Seeds `<Button>` in an AI appearance (e.g.
+   * `appearance="ai-secondary"`). Pass it without system props so it renders the
+   * Tailwind path — same as NarrativeSummary's `action` slot.
+   */
+  action?: React.ReactNode;
+}
+
+export interface TypeNarrativeOrderedListProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** The ordered items. Numbered automatically (01, 02, …) in order. */
+  items: TypeNarrativeOrderedListItem[];
+  /**
+   * Item arrangement. `"horizontal"` lays items in a row of equal columns that
+   * collapses to a stack when the container is narrow; `"vertical"` is always
+   * stacked.
+   * @default "vertical"
+   */
+  orientation?: TypeNarrativeOrderedListOrientation;
+}

package/src/NarrativeOrderedList/__tests__/NarrativeOrderedList.test.tsx

@@ -0,0 +1,89 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import NarrativeOrderedList from "../NarrativeOrderedList";
+import type { TypeNarrativeOrderedListItem } from "../NarrativeOrderedListTypes";
+
+const items: TypeNarrativeOrderedListItem[] = [
+  { title: "First action", description: "Do the first thing." },
+  { title: "Second action", description: "Do the second thing." },
+  { title: "Third action", description: "Do the third thing." },
+];
+
+describe("NarrativeOrderedList", () => {
+  it("renders an ordered list with one item per entry", () => {
+    const { container } = render(<NarrativeOrderedList items={items} />);
+
+    expect(
+      container.querySelector("ol.seeds-narrative-ordered-list-track")
+    ).toBeInTheDocument();
+    expect(screen.getAllByRole("listitem")).toHaveLength(3);
+  });
+
+  it("renders each item's title and description", () => {
+    render(<NarrativeOrderedList items={items} />);
+
+    expect(screen.getByText("First action")).toBeInTheDocument();
+    expect(screen.getByText("Do the first thing.")).toBeInTheDocument();
+    expect(screen.getByText("Third action")).toBeInTheDocument();
+  });
+
+  it("auto-numbers items with zero-padded ordinals", () => {
+    render(<NarrativeOrderedList items={items} />);
+
+    expect(screen.getByText("01")).toBeInTheDocument();
+    expect(screen.getByText("02")).toBeInTheDocument();
+    expect(screen.getByText("03")).toBeInTheDocument();
+  });
+
+  it("omits the description when it is not provided", () => {
+    const { container } = render(
+      <NarrativeOrderedList items={[{ title: "No description" }]} />
+    );
+
+    expect(screen.getByText("No description")).toBeInTheDocument();
+    expect(
+      container.querySelector(".seeds-narrative-ordered-list-description")
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the action only when provided", () => {
+    const { rerender } = render(<NarrativeOrderedList items={items} />);
+    expect(
+      screen.queryByRole("button", { name: "Action" })
+    ).not.toBeInTheDocument();
+
+    rerender(
+      <NarrativeOrderedList
+        items={[{ title: "With action", action: <button>Action</button> }]}
+      />
+    );
+    expect(screen.getByRole("button", { name: "Action" })).toBeInTheDocument();
+  });
+
+  it("applies the horizontal modifier class", () => {
+    const { container } = render(
+      <NarrativeOrderedList items={items} orientation="horizontal" />
+    );
+
+    expect(
+      container.querySelector(".seeds-narrative-ordered-list-horizontal")
+    ).toBeInTheDocument();
+  });
+
+  it("merges a consumer className with the base class", () => {
+    const { container } = render(
+      <NarrativeOrderedList items={items} className="custom" />
+    );
+
+    const root = container.querySelector(".seeds-narrative-ordered-list");
+    expect(root).toBeInTheDocument();
+    expect(root).toHaveClass("custom");
+  });
+
+  it("forwards its ref to the underlying container element", () => {
+    const ref = React.createRef<HTMLDivElement>();
+    render(<NarrativeOrderedList items={items} ref={ref} />);
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+});

package/src/NarrativeOrderedList/index.ts

@@ -0,0 +1,6 @@
+export { default as NarrativeOrderedList } from "./NarrativeOrderedList";
+export type {
+  TypeNarrativeOrderedListProps,
+  TypeNarrativeOrderedListItem,
+  TypeNarrativeOrderedListOrientation,
+} from "./NarrativeOrderedListTypes";

package/src/NarrativeSocialMediaCard/NarrativeSocialMediaCard.stories.tsx

@@ -0,0 +1,111 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import NarrativeSocialMediaCard from "./NarrativeSocialMediaCard";
+import { PartnerLogo } from "@sproutsocial/seeds-react-partner-logo";
+import "../narrative-social-media-card.css";
+import Icon from "@sproutsocial/seeds-react-icon";
+
+const metaArray = [
+  { icon: <Icon name="reply-outline" />, value: 12, label: "Replies" },
+  { icon: <Icon name="heart-outline" />, value: 128, label: "Likes" },
+  { icon: <Icon name="repost-outline" />, value: 42, label: "Reposts" },
+];
+
+const meta = {
+  title: "Narrative Kit/NarrativeSocialMediaCard",
+  component: NarrativeSocialMediaCard,
+  args: {
+    avatar: "https://api.dicebear.com/7.x/avataaars/svg?seed=Felix",
+    avatarAlt: "Profile avatar",
+    displayName: "Sprout Social",
+    socialIcon: <PartnerLogo partnerName="twitter" size="small" />,
+    meta: metaArray,
+    text: "Just launched our new product! Check it out and let us know what you think.",
+  },
+  decorators: [
+    (Story) => (
+      <div
+        style={{
+          padding: "24px",
+          backgroundColor: "white",
+          minHeight: "400px",
+        }}
+      >
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof NarrativeSocialMediaCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A typical social media card with gray background. */
+export const Default: Story = {};
+
+/** A card with longer content to show text wrapping. */
+export const LongContent: Story = {
+  args: {
+    text: "We're thrilled to announce our biggest update yet! After months of hard work from the team, we're rolling out features that will transform how you connect with your audience. Stay tuned for more details coming soon.",
+  },
+};
+
+/** A card with a horizontal landscape image in the content area. */
+export const WithHorizontalImage: Story = {
+  args: {
+    displayName: "Travel Blogger",
+    meta: metaArray,
+    image: (
+      <img
+        src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600&h=400&fit=crop"
+        alt="Mountain sunset landscape"
+        style={{
+          width: "100%",
+          height: "auto",
+          borderRadius: "8px",
+          display: "block",
+          marginBottom: "12px",
+        }}
+      />
+    ),
+    text: "Just had an amazing sunset hike in the mountains! Nature never disappoints.",
+  },
+};
+
+/** A card with a tall vertical image in the content area. */
+export const WithVerticalImage: Story = {
+  args: {
+    displayName: "Fashion Magazine",
+    meta: metaArray,
+    image: (
+      <img
+        src="https://images.unsplash.com/photo-1515886657613-9f3515b0c78f?w=400&h=600&fit=crop"
+        alt="Fashion portrait"
+        style={{
+          width: "100%",
+          height: "auto",
+          borderRadius: "8px",
+          display: "block",
+          marginBottom: "12px",
+        }}
+      />
+    ),
+    text: "New collection dropping this Friday. Stay tuned for the full reveal!",
+  },
+};
+
+/** A card with no metadata. */
+export const WithoutMetaData: Story = {
+  args: {
+    displayName: "Brand New Account",
+    meta: [],
+    text: "First post! Looking forward to connecting with everyone here.",
+  },
+};
+
+/** A card with no background that blends with the page. */
+export const NoBackground: Story = {
+  args: {
+    appearance: "no-background",
+  },
+};

package/src/NarrativeSocialMediaCard/NarrativeSocialMediaCard.tsx

@@ -0,0 +1,80 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import NarrativeAttribution from "../NarrativeAttribution/NarrativeAttribution";
+import type { TypeNarrativeSocialMediaCardProps } from "./NarrativeSocialMediaCardTypes";
+
+/**
+ * NarrativeSocialMediaCard — a narrative primitive that displays a social media
+ * post card with a header (avatar + handle), content area, and footer with
+ * engagement metadata (replies, likes, reposts, etc.).
+ *
+ * Styled via narrative-social-media-card.css (Seeds CSS custom properties);
+ * consumers import the classes through @sproutsocial/racine/css/components.
+ * Layout is vertically stacked with clean typography and icon-based metadata in
+ * the footer. Default has a gray background; use appearance="no-background" to
+ * remove the background and blend seamlessly with the page.
+ */
+const NarrativeSocialMediaCard = React.forwardRef<
+  HTMLDivElement,
+  TypeNarrativeSocialMediaCardProps
+>(
+  (
+    {
+      avatar,
+      avatarAlt,
+      displayName,
+      socialIcon,
+      image,
+      text,
+      meta,
+      appearance,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "seeds-narrative-social-media-card",
+          appearance === "no-background" &&
+            "seeds-narrative-social-media-card--no-background",
+          className
+        )}
+        {...props}
+      >
+        <NarrativeAttribution
+          avatarUrl={avatar}
+          avatarAlt={avatarAlt}
+          userName={displayName}
+          socialIcon={socialIcon}
+        />
+
+        <div className="seeds-narrative-social-media-card-content">
+          {image}
+          {text}
+        </div>
+
+        <div className="seeds-narrative-social-media-card-footer">
+          {meta.map((item, index) => (
+            <div
+              key={index}
+              className="seeds-narrative-social-media-card-stat"
+              aria-label={item.label}
+            >
+              {item.icon}
+              <span className="seeds-narrative-social-media-card-stat-value">
+                {item.value}
+              </span>
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  }
+);
+
+NarrativeSocialMediaCard.displayName = "NarrativeSocialMediaCard";
+
+export default NarrativeSocialMediaCard;

package/src/NarrativeSocialMediaCard/NarrativeSocialMediaCardTypes.ts

@@ -0,0 +1,30 @@
+import type * as React from "react";
+
+export interface TypeNarrativeSocialMediaCardMeta {
+  /** Icon for the metadata (e.g., reply, heart, repost). */
+  icon: React.ReactNode;
+  /** Number or formatted string value for the metadata. */
+  value: number | string;
+  /** Optional accessible label for the metadata. */
+  label?: string;
+}
+
+export interface TypeNarrativeSocialMediaCardProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  /** Avatar image URL for the social media profile. */
+  avatar: string;
+  /** Alt text for the avatar image. */
+  avatarAlt: string;
+  /** Display name for the social media profile. */
+  displayName: string;
+  /** Social media network icon (e.g., Twitter, Instagram, LinkedIn). */
+  socialIcon: React.ReactNode;
+  /** Optional image to display above the text content. */
+  image?: React.ReactNode;
+  /** The text content of the social media post. */
+  text: React.ReactNode;
+  /** Array of metadata with icons and values (e.g., replies, likes, reposts). */
+  meta: TypeNarrativeSocialMediaCardMeta[];
+  /** Visual appearance of the card. Default has gray background, "no-background" removes the background. */
+  appearance?: "no-background";
+}

package/src/NarrativeSocialMediaCard/__tests__/NarrativeSocialMediaCard.test.tsx

@@ -0,0 +1,154 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import NarrativeSocialMediaCard from "../NarrativeSocialMediaCard";
+import { PartnerLogo } from "@sproutsocial/seeds-react-partner-logo";
+
+// Test meta icons
+const TestIcon1 = () => (
+  <svg viewBox="0 0 16 16" aria-hidden focusable={false}>
+    <path d="M2 8H14" stroke="currentColor" strokeWidth="1.5" />
+  </svg>
+);
+
+const TestIcon2 = () => (
+  <svg viewBox="0 0 16 16" aria-hidden focusable={false}>
+    <circle cx="8" cy="8" r="6" stroke="currentColor" strokeWidth="1.5" />
+  </svg>
+);
+
+const TestIcon3 = () => (
+  <svg viewBox="0 0 16 16" aria-hidden focusable={false}>
+    <rect
+      x="4"
+      y="4"
+      width="8"
+      height="8"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    />
+  </svg>
+);
+
+describe("NarrativeSocialMediaCard", () => {
+  const defaultProps = {
+    avatar: "https://example.com/avatar.jpg",
+    avatarAlt: "Profile avatar",
+    displayName: "Display Name",
+    socialIcon: <PartnerLogo partnerName="twitter" size="small" />,
+    text: "Test content",
+    meta: [
+      { icon: <TestIcon1 />, value: 42, label: "Action 1" },
+      { icon: <TestIcon2 />, value: 128, label: "Action 2" },
+      { icon: <TestIcon3 />, value: 17, label: "Action 3" },
+    ],
+  };
+
+  it("renders the avatar image", () => {
+    render(<NarrativeSocialMediaCard {...defaultProps} />);
+
+    const avatar = screen.getByRole("img");
+    expect(avatar).toBeInTheDocument();
+    expect(avatar).toHaveAttribute("src", "https://example.com/avatar.jpg");
+  });
+
+  it("renders the display name", () => {
+    render(<NarrativeSocialMediaCard {...defaultProps} />);
+
+    expect(screen.getByText("Display Name")).toBeInTheDocument();
+  });
+
+  it("renders the text content", () => {
+    render(
+      <NarrativeSocialMediaCard
+        {...defaultProps}
+        text="This is a test post with some content"
+      />
+    );
+
+    expect(
+      screen.getByText("This is a test post with some content")
+    ).toBeInTheDocument();
+  });
+
+  it("renders the meta values in the footer", () => {
+    render(<NarrativeSocialMediaCard {...defaultProps} />);
+
+    expect(screen.getByText("42")).toBeInTheDocument();
+    expect(screen.getByText("128")).toBeInTheDocument();
+    expect(screen.getByText("17")).toBeInTheDocument();
+  });
+
+  it("accepts string values for meta values", () => {
+    render(
+      <NarrativeSocialMediaCard
+        avatar="https://example.com/avatar.jpg"
+        avatarAlt="Profile avatar"
+        displayName="Display Name"
+        socialIcon={<PartnerLogo partnerName="twitter" size="small" />}
+        text="Test content"
+        meta={[
+          { icon: <TestIcon1 />, value: "1.2K", label: "Action 1" },
+          { icon: <TestIcon2 />, value: "5.3K", label: "Action 2" },
+          { icon: <TestIcon3 />, value: "842", label: "Action 3" },
+        ]}
+      />
+    );
+
+    expect(screen.getByText("1.2K")).toBeInTheDocument();
+    expect(screen.getByText("5.3K")).toBeInTheDocument();
+    expect(screen.getByText("842")).toBeInTheDocument();
+  });
+
+  it("renders the avatarAlt attribute", () => {
+    render(
+      <NarrativeSocialMediaCard
+        {...defaultProps}
+        avatarAlt="Custom avatar description"
+      />
+    );
+
+    const avatar = screen.getByRole("img");
+    expect(avatar).toHaveAttribute("alt", "Custom avatar description");
+  });
+
+  it("merges a consumer className with the base class", () => {
+    const { container } = render(
+      <NarrativeSocialMediaCard {...defaultProps} className="custom" />
+    );
+
+    const root = container.querySelector(".seeds-narrative-social-media-card");
+    expect(root).toBeInTheDocument();
+    expect(root).toHaveClass("custom");
+  });
+
+  it("forwards extra props to the underlying element", () => {
+    render(
+      <NarrativeSocialMediaCard {...defaultProps} data-testid="social-card" />
+    );
+
+    expect(screen.getByTestId("social-card")).toBeInTheDocument();
+  });
+
+  it("forwards its ref to the underlying div element", () => {
+    const ref = React.createRef<HTMLDivElement>();
+    render(<NarrativeSocialMediaCard {...defaultProps} ref={ref} />);
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.tagName).toBe("DIV");
+  });
+
+  it("renders image above text when image is provided", () => {
+    const { container } = render(
+      <NarrativeSocialMediaCard
+        {...defaultProps}
+        image={<img src="test.jpg" alt="test" />}
+        text="Text content"
+      />
+    );
+
+    const content = container.querySelector(
+      ".seeds-narrative-social-media-card-content"
+    );
+    expect(content?.firstChild).toHaveProperty("tagName", "IMG");
+  });
+});

package/src/NarrativeSocialMediaCard/index.ts

@@ -0,0 +1,5 @@
+export { default as NarrativeSocialMediaCard } from "./NarrativeSocialMediaCard";
+export type {
+  TypeNarrativeSocialMediaCardProps,
+  TypeNarrativeSocialMediaCardMeta,
+} from "./NarrativeSocialMediaCardTypes";