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

package/src/AIContainer/AIContainer.stories.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import AIContainer from "./AIContainer";
+import "../ai-container.css";
+
+const meta = {
+  title: "Narrative Kit/AIContainer",
+  component: AIContainer,
+  args: {
+    className: "w-80",
+    style: { padding: "24px" },
+  },
+} satisfies Meta<typeof AIContainer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const ShortContent = () => (
+  <p>
+    Engagement is up 24% this month, driven by a strong week on LinkedIn and a
+    viral reply thread.
+  </p>
+);
+
+const RichContent = () => (
+  <div className="grid gap-300">
+    <strong>AI-generated summary</strong>
+    <p>
+      Audience growth held steady while impressions climbed. Your top-performing
+      post reached 3x the usual engagement rate.
+    </p>
+  </div>
+);
+
+export const Subtle: Story = {
+  args: {
+    appearance: "subtle",
+    children: <ShortContent />,
+  },
+};
+
+export const Vivid: Story = {
+  args: {
+    appearance: "vivid",
+    children: <ShortContent />,
+  },
+};
+
+export const WithChildren: Story = {
+  args: {
+    appearance: "subtle",
+    children: <RichContent />,
+  },
+};

package/src/AIContainer/AIContainer.tsx

@@ -0,0 +1,35 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypeAIContainerProps } from "./AIContainerTypes";
+
+/**
+ * AIContainer — a rounded surface primitive with the AI gradient background.
+ * Provides the outer shell (border-radius, shadow, overflow, gradient) without
+ * any padding. Used by PullQuote and available as a standalone container.
+ *
+ * - `subtle` — a light 20% gradient tint over the base surface with adaptive text color.
+ * - `vivid` — the full-saturation AI gradient with white text (always white).
+ *
+ * Styled via `ai-container.css` (Seeds CSS custom properties).
+ */
+const AIContainer = React.forwardRef<HTMLDivElement, TypeAIContainerProps>(
+  ({ children, appearance = "subtle", className, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "seeds-ai-container",
+          { "seeds-ai-container-vivid": appearance === "vivid" },
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+  }
+);
+
+AIContainer.displayName = "AIContainer";
+
+export default AIContainer;

package/src/AIContainer/AIContainerTypes.ts

@@ -0,0 +1,14 @@
+import type * as React from "react";
+
+export interface TypeAIContainerProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** Content rendered inside the container. */
+  children?: React.ReactNode;
+  /**
+   * Visual treatment of the AI gradient surface.
+   * - `subtle` — a light 20% gradient tint over the base surface with dark text.
+   * - `vivid` — the full-saturation AI gradient with white text (always white).
+   * @default "subtle"
+   */
+  appearance?: "subtle" | "vivid";
+}

package/src/AIContainer/__tests__/AIContainer.test.tsx

@@ -0,0 +1,61 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import AIContainer from "../AIContainer";
+
+describe("AIContainer", () => {
+  it("renders its children", () => {
+    render(<AIContainer>Summary text</AIContainer>);
+
+    expect(screen.getByText("Summary text")).toBeInTheDocument();
+  });
+
+  it("renders as a div", () => {
+    const { container } = render(<AIContainer>content</AIContainer>);
+
+    expect(container.firstChild?.nodeName).toBe("DIV");
+  });
+
+  it("applies the base class", () => {
+    const { container } = render(<AIContainer>content</AIContainer>);
+
+    expect(container.querySelector(".seeds-ai-container")).toBeInTheDocument();
+  });
+
+  it("does not apply the vivid modifier by default", () => {
+    const { container } = render(<AIContainer>content</AIContainer>);
+
+    expect(
+      container.querySelector(".seeds-ai-container-vivid")
+    ).not.toBeInTheDocument();
+  });
+
+  it("applies the vivid modifier only for the vivid appearance", () => {
+    const { container, rerender } = render(<AIContainer>content</AIContainer>);
+    expect(
+      container.querySelector(".seeds-ai-container-vivid")
+    ).not.toBeInTheDocument();
+
+    rerender(<AIContainer appearance="vivid">content</AIContainer>);
+    expect(
+      container.querySelector(".seeds-ai-container-vivid")
+    ).toBeInTheDocument();
+  });
+
+  it("merges a consumer className with the base class", () => {
+    const { container } = render(
+      <AIContainer className="custom">content</AIContainer>
+    );
+
+    const root = container.querySelector(".seeds-ai-container");
+    expect(root).toBeInTheDocument();
+    expect(root).toHaveClass("custom");
+  });
+
+  it("forwards its ref to the underlying div element", () => {
+    const ref = React.createRef<HTMLDivElement>();
+    render(<AIContainer ref={ref}>content</AIContainer>);
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.tagName).toBe("DIV");
+  });
+});

package/src/AIContainer/index.ts

@@ -0,0 +1,2 @@
+export { default as AIContainer } from "./AIContainer";
+export type { TypeAIContainerProps } from "./AIContainerTypes";

package/src/NarrativeAttribution/NarrativeAttribution.stories.tsx

@@ -0,0 +1,78 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import NarrativeAttribution from "./NarrativeAttribution";
+import { PartnerLogo } from "@sproutsocial/seeds-react-partner-logo";
+import "../narrative-attribution.css";
+
+const meta = {
+  title: "Narrative Kit/NarrativeAttribution",
+  component: NarrativeAttribution,
+  args: {
+    avatarUrl: "https://api.dicebear.com/7.x/avataaars/svg?seed=Felix",
+    userName: "Sprout Social",
+  },
+} satisfies Meta<typeof NarrativeAttribution>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Twitter/X attribution with partner logo. */
+export const Twitter: Story = {
+  args: {
+    socialIcon: <PartnerLogo partnerName="twitter" size="small" />,
+  },
+};
+
+/** Instagram attribution with partner logo. */
+export const Instagram: Story = {
+  args: {
+    avatarUrl: "https://api.dicebear.com/7.x/avataaars/svg?seed=Aneka",
+    userName: "design.studio",
+    socialIcon: <PartnerLogo partnerName="instagram" size="small" />,
+  },
+};
+
+/** LinkedIn attribution with partner logo. */
+export const LinkedIn: Story = {
+  args: {
+    avatarUrl: "https://api.dicebear.com/7.x/avataaars/svg?seed=Bailey",
+    userName: "Tech Company",
+    socialIcon: <PartnerLogo partnerName="linkedin" size="small" />,
+  },
+};
+
+/** Facebook attribution with partner logo. */
+export const Facebook: Story = {
+  args: {
+    avatarUrl: "https://api.dicebear.com/7.x/avataaars/svg?seed=Charlie",
+    userName: "Community Page",
+    socialIcon: <PartnerLogo partnerName="facebook" size="small" />,
+  },
+};
+
+/** YouTube attribution with partner logo. */
+export const YouTube: Story = {
+  args: {
+    avatarUrl: "https://api.dicebear.com/7.x/avataaars/svg?seed=Dakota",
+    userName: "Creator Channel",
+    socialIcon: <PartnerLogo partnerName="youtube" size="small" />,
+  },
+};
+
+/** TikTok attribution with partner logo. */
+export const TikTok: Story = {
+  args: {
+    avatarUrl: "https://api.dicebear.com/7.x/avataaars/svg?seed=Ellis",
+    userName: "viral.content",
+    socialIcon: <PartnerLogo partnerName="tiktok" size="small" />,
+  },
+};
+
+/** Threads attribution with partner logo icon. */
+export const Threads: Story = {
+  args: {
+    avatarUrl: "https://api.dicebear.com/7.x/avataaars/svg?seed=Jordan",
+    userName: "threads.user",
+    socialIcon: <PartnerLogo partnerName="threads" size="small" />,
+  },
+};

package/src/NarrativeAttribution/NarrativeAttribution.tsx

@@ -0,0 +1,54 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypeNarrativeAttributionProps } from "./NarrativeAttributionTypes";
+
+/**
+ * NarrativeAttribution — a narrative primitive that displays attribution
+ * information for social media content, including an avatar, social network
+ * icon, and user name.
+ *
+ * Styled via narrative-attribution.css (Seeds CSS custom properties);
+ * consumers import the classes through @sproutsocial/racine/css/components.
+ * Layout is horizontal with avatar, social icon, and user name arranged
+ * side by side. Surface overrides are done with standard className / style.
+ */
+const NarrativeAttribution = React.forwardRef<
+  HTMLDivElement,
+  TypeNarrativeAttributionProps
+>(
+  (
+    {
+      avatarUrl,
+      avatarAlt = "Profile avatar",
+      userName,
+      socialIcon,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    return (
+      <div
+        ref={ref}
+        className={cn("seeds-narrative-attribution", className)}
+        {...props}
+      >
+        <img
+          src={avatarUrl}
+          alt={avatarAlt}
+          className="seeds-narrative-attribution-avatar"
+        />
+        <div className="seeds-narrative-attribution-social-icon">
+          {socialIcon}
+        </div>
+        <span className="seeds-narrative-attribution-user-name">
+          {userName}
+        </span>
+      </div>
+    );
+  }
+);
+
+NarrativeAttribution.displayName = "NarrativeAttribution";
+
+export default NarrativeAttribution;

package/src/NarrativeAttribution/NarrativeAttributionTypes.ts

@@ -0,0 +1,13 @@
+import type * as React from "react";
+
+export interface TypeNarrativeAttributionProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  /** Avatar image URL for the social media profile. */
+  avatarUrl: string;
+  /** Alt text for the avatar image. */
+  avatarAlt?: string;
+  /** User name or display name for the social media profile. */
+  userName: string;
+  /** Social media network icon (e.g., Twitter, Instagram, LinkedIn). */
+  socialIcon: React.ReactNode;
+}

package/src/NarrativeAttribution/index.ts

@@ -0,0 +1,2 @@
+export { default as NarrativeAttribution } from "./NarrativeAttribution";
+export type { TypeNarrativeAttributionProps } from "./NarrativeAttributionTypes";

package/src/NarrativeDataCallout/NarrativeDataCallout.stories.tsx

@@ -0,0 +1,71 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { DonutChart } from "@sproutsocial/seeds-react-data-viz/donut";
+import NarrativeDataCallout from "./NarrativeDataCallout";
+import NarrativeContainer from "../NarrativeContainer/NarrativeContainer";
+import "../narrative-data-callout.css";
+import "../narrative-container.css";
+
+/**
+ * NarrativeDataCallout has no built-in chart — the `visual` slot accepts any
+ * node. These stories inject the real v2 `DonutChart` from
+ * `@sproutsocial/seeds-react-data-viz/donut`; narrative-kit takes no runtime
+ * dependency on data-viz (only these stories do, via a devDependency). The
+ * injected chart fills the left third; the copy fills the right two-thirds.
+ */
+const donut = (): React.ReactNode => (
+  <DonutChart
+    description="Completion rate: 80% complete"
+    data={[
+      { name: "Complete", value: 80 },
+      { name: "Remaining", value: 20 },
+    ]}
+  />
+);
+
+const BODY =
+  "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec odio leo, " +
+  "gravida vitae sodales vitae, tempor eget ligula. Vestibulum nec enim eget " +
+  "mi placerat finibus. Donec tempor tincidunt elit.";
+
+const meta = {
+  title: "Narrative Kit/NarrativeDataCallout",
+  component: NarrativeDataCallout,
+  args: {
+    visual: donut(),
+    children: BODY,
+  },
+} satisfies Meta<typeof NarrativeDataCallout>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Bare inner content — the visual on the left third, copy on the right. */
+export const Default: Story = {
+  args: {
+    className: "w-full max-w-240",
+  },
+};
+
+/**
+ * Dropped into a `NarrativeContainer` to reproduce the gradient-accented card
+ * from the design. This is the intended composition — the callout itself carries
+ * no surface.
+ */
+export const InContainer: Story = {
+  render: (args) => (
+    <NarrativeContainer className="w-full max-w-240">
+      <NarrativeDataCallout {...args} />
+    </NarrativeContainer>
+  ),
+};
+
+/**
+ * Narrow width — the container query collapses the row to a stacked column
+ * (visual on top, copy below). Resize the canvas to watch it reflow.
+ */
+export const Stacked: Story = {
+  args: {
+    className: "w-80",
+  },
+};

package/src/NarrativeDataCallout/NarrativeDataCallout.tsx

@@ -0,0 +1,50 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypeNarrativeDataCalloutProps } from "./NarrativeDataCalloutTypes";
+
+/**
+ * NarrativeDataCallout — a horizontally oriented callout that pairs an injected
+ * data-viz visual (left, ~1/3 width) with a block of body copy (right, ~2/3).
+ *
+ * The kit ships no chart of its own; the `visual` slot accepts any node — the
+ * stories drop in a v2 `DonutChart` from `@sproutsocial/seeds-react-data-viz`.
+ * narrative-kit takes no runtime dependency on data-viz (mirrors MetricHighlight's
+ * `sparkline` slot).
+ *
+ * Renders inner content only — it carries no surface, shadow, or accent of its
+ * own. Drop it into a `NarrativeContainer` (see the stories) to reproduce the
+ * card look.
+ *
+ * Layout is a flex row driven by a container query, so it collapses to a stacked
+ * column (visual on top, text below) based on the width the component is actually
+ * given, not the viewport.
+ *
+ * Styled via `narrative-data-callout.css` (Seeds CSS custom properties); consumers
+ * import the classes through `@sproutsocial/racine/css/components`. Overrides come
+ * via standard `className` / `style`.
+ */
+const NarrativeDataCallout = React.forwardRef<
+  HTMLDivElement,
+  TypeNarrativeDataCalloutProps
+>(({ visual, children, visualLabel, className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("seeds-narrative-data-callout", className)}
+    {...props}
+  >
+    <div className="seeds-narrative-data-callout-row">
+      <div
+        className="seeds-narrative-data-callout-visual"
+        role={visualLabel != null ? "img" : undefined}
+        aria-label={visualLabel}
+      >
+        {visual}
+      </div>
+      <div className="seeds-narrative-data-callout-body">{children}</div>
+    </div>
+  </div>
+));
+
+NarrativeDataCallout.displayName = "NarrativeDataCallout";
+
+export default NarrativeDataCallout;

package/src/NarrativeDataCallout/NarrativeDataCalloutTypes.ts

@@ -0,0 +1,18 @@
+import type * as React from "react";
+
+export interface TypeNarrativeDataCalloutProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Data-viz component rendered in the left slot (occupies ~1/3 of the width).
+   * The kit ships no chart of its own — drop in any data-viz node, e.g. a v2
+   * `DonutChart` from `@sproutsocial/seeds-react-data-viz`.
+   */
+  visual: React.ReactNode;
+  /** Body copy / description occupying the right two-thirds. */
+  children: React.ReactNode;
+  /**
+   * Accessible label for the visual slot region. Omit when the injected visual
+   * already carries its own description/label.
+   */
+  visualLabel?: string;
+}

package/src/NarrativeDataCallout/__tests__/NarrativeDataCallout.test.tsx

@@ -0,0 +1,69 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import NarrativeDataCallout from "../NarrativeDataCallout";
+
+describe("NarrativeDataCallout", () => {
+  it("renders the body copy", () => {
+    render(
+      <NarrativeDataCallout visual={<div>chart</div>}>
+        Engagement climbed this month.
+      </NarrativeDataCallout>
+    );
+
+    expect(
+      screen.getByText("Engagement climbed this month.")
+    ).toBeInTheDocument();
+  });
+
+  it("renders the injected visual node in the visual slot", () => {
+    const { container } = render(
+      <NarrativeDataCallout visual={<div data-testid="custom-viz">chart</div>}>
+        Body
+      </NarrativeDataCallout>
+    );
+
+    expect(screen.getByTestId("custom-viz")).toBeInTheDocument();
+    expect(
+      container.querySelector(".seeds-narrative-data-callout-visual")
+    ).toBeInTheDocument();
+  });
+
+  it("applies the root class and merges a custom className", () => {
+    const { container } = render(
+      <NarrativeDataCallout visual={<div>chart</div>} className="custom">
+        Body
+      </NarrativeDataCallout>
+    );
+
+    const root = container.querySelector(".seeds-narrative-data-callout");
+    expect(root).toBeInTheDocument();
+    expect(root).toHaveClass("custom");
+  });
+
+  it("labels the visual region when visualLabel is provided", () => {
+    render(
+      <NarrativeDataCallout
+        visual={<div>chart</div>}
+        visualLabel="Completion rate"
+      >
+        Body
+      </NarrativeDataCallout>
+    );
+
+    expect(
+      screen.getByRole("img", { name: "Completion rate" })
+    ).toBeInTheDocument();
+  });
+
+  it("forwards its ref to the underlying div element", () => {
+    const ref = React.createRef<HTMLDivElement>();
+    render(
+      <NarrativeDataCallout ref={ref} visual={<div>chart</div>}>
+        Body
+      </NarrativeDataCallout>
+    );
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.tagName).toBe("DIV");
+  });
+});

package/src/NarrativeDataCallout/index.ts

@@ -0,0 +1,2 @@
+export { default as NarrativeDataCallout } from "./NarrativeDataCallout";
+export type { TypeNarrativeDataCalloutProps } from "./NarrativeDataCalloutTypes";

package/src/NarrativeOrderedList/NarrativeOrderedList.stories.tsx

@@ -0,0 +1,69 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Button from "@sproutsocial/seeds-react-button";
+import NarrativeOrderedList from "./NarrativeOrderedList";
+import "../narrative-ordered-list.css";
+import "@sproutsocial/seeds-react-button/dist/button.css";
+
+/**
+ * NarrativeOrderedList renders a numbered list of action items. Each item pairs
+ * a large ordinal (01, 02, …) with a title, an optional description, and an
+ * optional call-to-action slot. It renders inner content only, meant to be
+ * dropped into a `NarrativeContainer` in production (see the Playground story
+ * for that composition).
+ *
+ * Layout is container-query-driven, so it responds to the width it is given
+ * rather than the viewport. The `"horizontal"` variant collapses back to a
+ * stack when the container is narrow.
+ */
+const description =
+  "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec odio leo, gravida vitae sodales vitae.";
+
+// No system props → the Button renders its Tailwind path.
+const suggestedAction = (
+  <Button appearance="ai-secondary">Suggested Action</Button>
+);
+
+const meta = {
+  title: "Narrative Kit/NarrativeOrderedList",
+  component: NarrativeOrderedList,
+  args: {
+    items: [
+      { title: "Action title", description, action: suggestedAction },
+      { title: "Action title", description, action: suggestedAction },
+      { title: "Action title", description, action: suggestedAction },
+    ],
+  },
+  // Constrain the width so the layout has a realistic amount of room.
+  decorators: [
+    (Story) => (
+      <div className="max-w-256">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof NarrativeOrderedList>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Items stacked full-width, one per row (the default). */
+export const Vertical: Story = {};
+
+/** Items laid out as a row of equal columns. */
+export const Horizontal: Story = {
+  args: {
+    orientation: "horizontal",
+  },
+};
+
+/** The action is optional — omit it and each item drops the button. */
+export const WithoutAction: Story = {
+  args: {
+    items: [
+      { title: "Action title", description },
+      { title: "Action title", description },
+      { title: "Action title", description },
+    ],
+  },
+};

package/src/NarrativeOrderedList/NarrativeOrderedList.tsx

@@ -0,0 +1,74 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypeNarrativeOrderedListProps } from "./NarrativeOrderedListTypes";
+
+/**
+ * NarrativeOrderedList — a numbered list of action items. Each item pairs a
+ * large ordinal (01, 02, …) with a title, an optional description, and an
+ * optional call-to-action slot.
+ *
+ * Renders inner content only — it carries no surface, shadow, or accent of its
+ * own. Drop it into a `NarrativeContainer` (see the stories / playground).
+ *
+ * Layout is driven by container queries, so it responds to the width the
+ * component is actually given, not the viewport:
+ * - `"vertical"` (default) → items stacked full-width, one per row.
+ * - `"horizontal"` → items laid out as a row of equal columns once there is
+ *   room, collapsing back to a stack when the container is narrow.
+ *
+ * Styled via `narrative-ordered-list.css` (Seeds CSS custom properties);
+ * consumers import the classes through `@sproutsocial/racine/css/components`.
+ * Overrides come via standard `className` / `style`.
+ */
+const NarrativeOrderedList = React.forwardRef<
+  HTMLDivElement,
+  TypeNarrativeOrderedListProps
+>(({ items, orientation = "vertical", className, ...props }, ref) => {
+  return (
+    // The outer element establishes the query container. The ol inside switches
+    // direction based on this element's width — a container query can only style
+    // descendants of the container, never the container element itself.
+    <div
+      ref={ref}
+      className={cn("seeds-narrative-ordered-list", className)}
+      {...props}
+    >
+      <ol
+        className={cn("seeds-narrative-ordered-list-track", {
+          "seeds-narrative-ordered-list-horizontal":
+            orientation === "horizontal",
+        })}
+      >
+        {items.map((item, i) => (
+          <li key={i} className="seeds-narrative-ordered-list-item">
+            {/* Decorative — the ol/li already convey order to assistive tech, so
+                hide the visible ordinal from it to avoid double-announcing. */}
+            <span
+              className="seeds-narrative-ordered-list-number"
+              aria-hidden="true"
+            >
+              {String(i + 1).padStart(2, "0")}
+            </span>
+            <div className="seeds-narrative-ordered-list-body">
+              <p className="seeds-narrative-ordered-list-title">{item.title}</p>
+              {item.description != null && (
+                <p className="seeds-narrative-ordered-list-description">
+                  {item.description}
+                </p>
+              )}
+              {item.action != null && (
+                <div className="seeds-narrative-ordered-list-action">
+                  {item.action}
+                </div>
+              )}
+            </div>
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+});
+
+NarrativeOrderedList.displayName = "NarrativeOrderedList";
+
+export default NarrativeOrderedList;