@sproutsocial/seeds-react-narrative-kit 0.4.0 → 0.5.1

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";

package/src/Playground/Playground.stories.tsx

@@ -12,10 +12,13 @@ import NarrativeDivider from "../NarrativeDivider/NarrativeDivider";
 import NarrativeSummary from "../NarrativeSummary/NarrativeSummary";
 import NarrativeOrderedList from "../NarrativeOrderedList/NarrativeOrderedList";
 import NarrativeDataCallout from "../NarrativeDataCallout/NarrativeDataCallout";
+import NarrativeSocialMediaCard from "../NarrativeSocialMediaCard/NarrativeSocialMediaCard";
 import Button from "@sproutsocial/seeds-react-button";
 import Text from "@sproutsocial/seeds-react-text";
 import { SparklineChart } from "@sproutsocial/seeds-react-data-viz/sparkline";
 import { DonutChart } from "@sproutsocial/seeds-react-data-viz/donut";
+import { PartnerLogo } from "@sproutsocial/seeds-react-partner-logo";
+import Icon from "@sproutsocial/seeds-react-icon";
 import "../narrative-container.css";
 import "../narrative-headline.css";
 import "../pull-quote.css";
@@ -25,6 +28,7 @@ import "../narrative-divider.css";
 import "../narrative-summary.css";
 import "../narrative-ordered-list.css";
 import "../narrative-data-callout.css";
+import "../narrative-social-media-card.css";
 import "@sproutsocial/seeds-react-button/dist/button.css";
 import "@sproutsocial/seeds-react-data-viz/sparkline.css";
 
@@ -204,8 +208,87 @@ const Brief = () => (
             move the needle and sunsetting the low-leverage noise to land this
             initiative ahead of the curve.
           </NarrativeDataCallout>
+
+          <NarrativeDivider />
+
+          {/* Social media cards — a row of 3 sample posts -------------------- */}
+          <Grid columns={{ sm: 1, md: 2, lg: 3 }} gap={400}>
+            <NarrativeSocialMediaCard
+              avatar="https://api.dicebear.com/7.x/avataaars/svg?seed=Felix"
+              avatarAlt="Sprout Social avatar"
+              displayName="Sprout Social"
+              socialIcon={<PartnerLogo partnerName="twitter" size="small" />}
+              text="Just launched our new product! Check it out and let us know what you think."
+              meta={[
+                {
+                  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",
+                },
+              ]}
+            />
+            <NarrativeSocialMediaCard
+              avatar="https://api.dicebear.com/7.x/avataaars/svg?seed=Jordan"
+              avatarAlt="Marketing Team avatar"
+              displayName="Marketing Team"
+              socialIcon={<PartnerLogo partnerName="linkedin" size="small" />}
+              text="Our most viral post ever! Thanks for all the engagement. The community response has been incredible and we're excited to keep the momentum going."
+              meta={[
+                {
+                  icon: <Icon name="reply-outline" />,
+                  value: 45,
+                  label: "Comments",
+                },
+                {
+                  icon: <Icon name="heart-outline" />,
+                  value: 892,
+                  label: "Likes",
+                },
+                {
+                  icon: <Icon name="repost-outline" />,
+                  value: 156,
+                  label: "Shares",
+                },
+              ]}
+            />
+            <NarrativeSocialMediaCard
+              avatar="https://api.dicebear.com/7.x/avataaars/svg?seed=Alex"
+              avatarAlt="Brand Studio avatar"
+              displayName="Brand Studio"
+              socialIcon={<PartnerLogo partnerName="instagram" size="small" />}
+              text="Behind the scenes of today's campaign launch. Swipe to see the creative process!"
+              meta={[
+                {
+                  icon: <Icon name="reply-outline" />,
+                  value: 89,
+                  label: "Comments",
+                },
+                {
+                  icon: <Icon name="heart-outline" />,
+                  value: 1240,
+                  label: "Likes",
+                },
+                {
+                  icon: <Icon name="repost-outline" />,
+                  value: 203,
+                  label: "Shares",
+                },
+              ]}
+            />
+          </Grid>
         </Grid>
       </NarrativeContainer>
+
       <NarrativeContainer>
         <NarrativeOrderedList
           orientation="horizontal"

package/src/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/src/index.ts

@@ -50,4 +50,15 @@ export {
 
 export { AIContainer, type TypeAIContainerProps } from "./AIContainer";
 
+export {
+  NarrativeSocialMediaCard,
+  type TypeNarrativeSocialMediaCardProps,
+  type TypeNarrativeSocialMediaCardMeta,
+} from "./NarrativeSocialMediaCard";
+
+export {
+  NarrativeAttribution,
+  type TypeNarrativeAttributionProps,
+} from "./NarrativeAttribution";
+
 export type { TypeNarrativeTone } from "./_internal/types";

package/src/narrative-attribution.css

@@ -0,0 +1,56 @@
+/**
+ * Seeds NarrativeAttribution component classes.
+ * Use these instead of writing out individual Tailwind utility classes.
+ *
+ * Requires @sproutsocial/seeds-react-theme/dist/theme-all.css imported for
+ * CSS variable definitions and dark mode support.
+ *
+ * Usage:
+ *   <div class="seeds-narrative-attribution">
+ *     <img class="seeds-narrative-attribution-avatar" />
+ *     <div class="seeds-narrative-attribution-social-icon">...</div>
+ *     <span class="seeds-narrative-attribution-user-name">...</span>
+ *   </div>
+ */
+
+@layer components {
+
+/* Main container — horizontal layout with avatar, social icon, and user name. */
+.seeds-narrative-attribution {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: var(--space-300); /* 8px */;
+  font-family: var(--font-family);
+}
+
+/* Circular avatar image — fixed size with rounded corners. */
+.seeds-narrative-attribution-avatar {
+  width: var(--space-450); /* 24px */
+  height: var(--space-450); /* 24px */
+  border-radius: var(--radius-circular); /* 50% */
+  object-fit: cover;
+  flex-shrink: 0;
+}
+
+/* Social network icon container — flexible sizing for partner logos. */
+.seeds-narrative-attribution-social-icon {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* User name text — bold headline text with ellipsis overflow. */
+.seeds-narrative-attribution-user-name {
+  overflow: hidden;
+  color: var(--color-text-headline);
+  text-overflow: ellipsis;
+  font-family: var(--font-family);
+  font-size: var(--text-base-font-size, 14px);
+  font-style: normal;
+  font-weight: var(--font-weight-bold, 700);
+  line-height: var(--text-base-line-height, 24px);
+}
+
+}

package/src/narrative-social-media-card.css

@@ -0,0 +1,79 @@
+/**
+ * Seeds NarrativeSocialMediaCard component classes.
+ * Use these instead of writing out individual Tailwind utility classes.
+ *
+ * Requires @sproutsocial/seeds-react-theme/dist/theme-all.css imported for
+ * CSS variable definitions and dark mode support.
+ *
+ * Usage:
+ *   <div class="seeds-narrative-social-media-card">
+ *     <div class="seeds-narrative-social-media-card-header">...</div>
+ *     <div class="seeds-narrative-social-media-card-content">...</div>
+ *     <div class="seeds-narrative-social-media-card-footer">...</div>
+ *   </div>
+ */
+
+@layer components {
+
+/* Main card container — gray background with rounded corners and padding.
+   Uses Seeds tokens for spacing, colors, and radius to match the design system. */
+.seeds-narrative-social-media-card {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  max-width: 320px;
+  padding: var(--space-450); /* 24px */
+  border-radius: var(--radius-500); /* 6px */
+  background-color: var(--color-app-bg-base);
+  font-family: var(--font-family);
+  color: var(--color-text-body);
+}
+
+/* No background — transparent background for cards that blend seamlessly with the page. */
+.seeds-narrative-social-media-card--no-background {
+  background-color: transparent;
+}
+
+/* Main content area — standard body text styling. */
+.seeds-narrative-social-media-card-content {
+  flex: 1;
+  margin-top: var(--space-400); /* 16px */
+  font-family: var(--font-family);
+  font-size: 14px;
+  font-style: normal;
+  font-weight: 400;
+  line-height: 24px;
+  color: var(--color-text-body);
+}
+
+/* Footer section — horizontal layout for stats with equal spacing. */
+.seeds-narrative-social-media-card-footer {
+  display: flex;
+  align-items: center;
+  gap: var(--space-400); /* 16px */
+  margin-top: var(--space-400); /* 16px */;
+}
+
+/* Hide footer when empty (no metadata items). */
+.seeds-narrative-social-media-card-footer:empty {
+  display: none;
+}
+
+/* Individual stat container — icon + value in horizontal layout. */
+.seeds-narrative-social-media-card-stat {
+  display: flex;
+  align-items: center;
+  gap: var(--space-200); /* 4px */
+}
+
+/* Stat value text — monospace font for numeric values. */
+.seeds-narrative-social-media-card-stat-value {
+  font-family: var(--font-family-mono, ui-monospace, "SF Mono", SFMono-Regular, Menlo, monospace);  font-size: 14px;
+  font-style: normal;
+  font-weight: 400;
+  line-height: 24px;
+  color: var(--color-text-body);
+}
+
+}