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

package/src/Playground/Playground.stories.tsx

@@ -10,9 +10,15 @@ import MetricHighlight from "../MetricHighlight/MetricHighlight";
 import EyebrowToken from "../EyebrowToken/EyebrowToken";
 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";
@@ -20,12 +26,15 @@ import "../metric-highlight.css";
 import "../eyebrow-token.css";
 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";
 
-const spark = (data: number[]) => (
+const spark = (data: number[], variant: "line" | "bar" = "line") => (
   <SparklineChart
-    variant="line"
+    variant={variant}
     description="Trend"
     data={data}
     className="h-full w-full"
@@ -86,14 +95,22 @@ const Brief = () => (
             <MetricHighlight
               label="Engagement rate"
               value="6.4%"
-              trend={{ direction: "up", value: "240%", "aria-label": "up 240%" }}
+              trend={{
+                direction: "up",
+                value: "240%",
+                "aria-label": "up 240%",
+              }}
               sparkline={spark([3, 5, 4, 7, 6, 9])}
             />
             <MetricHighlight
               label="Response time"
               value="2h"
-              trend={{ direction: "down", value: "12%", "aria-label": "down 12%" }}
-              sparkline={spark([18, 16, 17, 13, 14, 10])}
+              trend={{
+                direction: "down",
+                value: "12%",
+                "aria-label": "down 12%",
+              }}
+              sparkline={spark([18, 16, 17, 13, 14, 10], "bar")}
             />
           </Grid>
 
@@ -120,6 +137,37 @@ const Brief = () => (
 
           <NarrativeDivider />
 
+          <NarrativeOrderedList
+            items={[
+              {
+                title: "Double down on reply threads",
+                description:
+                  "Shift a slice of paid budget toward the organic reply threads that outperformed this week.",
+                action: (
+                  <Button appearance="ai-secondary">Suggested Action</Button>
+                ),
+              },
+              {
+                title: "Protect response time at peak",
+                description:
+                  "Add coverage during the two peak windows to hold response time under two hours.",
+                action: (
+                  <Button appearance="ai-secondary">Suggested Action</Button>
+                ),
+              },
+              {
+                title: "Lean into the enterprise segment",
+                description:
+                  "Build a follow-up sequence for the enterprise cohort that drove the most new engagement.",
+                action: (
+                  <Button appearance="ai-secondary">Suggested Action</Button>
+                ),
+              },
+            ]}
+          />
+
+          <NarrativeDivider />
+
           {/* Narrative summary (3-column) — below the pull quotes --------- */}
           <NarrativeSummary
             eyebrow="Quarterly review"
@@ -138,8 +186,131 @@ const Brief = () => (
             quote="This rollout cut our average response time nearly in half."
             attribution={<Attribution name="Priya Nair" />}
           />
+
+          <NarrativeDivider />
+
+          {/* Data callout — a data-viz visual paired with narrative copy ---- */}
+          <NarrativeDataCallout
+            visual={
+              <DonutChart
+                description="Goal completion: 80% complete"
+                data={[
+                  { name: "Complete", value: 80 },
+                  { name: "Remaining", value: 20 },
+                ]}
+              />
+            }
+          >
+            We're 80% of the way to closing out this quarter's goal — a clear
+            signal that the cross-functional alignment we drove upstream is now
+            compounding into measurable downstream velocity. With the remaining
+            20% squarely in view, we're doubling down on the workstreams that
+            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"
+          items={[
+            {
+              title: "Unlock audience momentum",
+              description:
+                "Reallocate engagement capacity toward the content clusters generating outsized share-of-voice gains across high-intent segments.",
+            },
+            {
+              title: "Operationalize your top performers",
+              description:
+                "Templatize the creative formats moving the needle this quarter and activate them across your highest-converting touchpoints.",
+            },
+            {
+              title: "Accelerate pipeline velocity",
+              description:
+                "Trigger a nurture sequence for the buyer personas showing the strongest conversion propensity signals right now.",
+            },
+          ]}
+        />
+      </NarrativeContainer>
     </div>
   </div>
 );

package/src/PullQuote/PullQuote.stories.tsx

@@ -2,6 +2,7 @@ import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import PullQuote from "./PullQuote";
 import "../pull-quote.css";
+import "../ai-container.css";
 
 const meta = {
   title: "Narrative Kit/PullQuote",

package/src/PullQuote/PullQuote.tsx

@@ -8,9 +8,10 @@ import type { TypePullQuoteProps } from "./PullQuoteTypes";
  * optional attribution row (author name, avatar, network).
  *
  * Rendered as semantic `<figure>` / `<blockquote>` / `<figcaption>` markup.
- * Styled via `pull-quote.css` (Seeds CSS custom properties); consumers import
- * the classes through `@sproutsocial/racine/css/components`. Surface overrides
- * are done with standard `className` / `style`.
+ * Styled via `pull-quote.css` and `ai-container.css` (Seeds CSS custom
+ * properties); consumers import the classes through
+ * `@sproutsocial/racine/css/components`. Surface overrides are done with
+ * standard `className` / `style`.
  */
 const PullQuote = React.forwardRef<HTMLElement, TypePullQuoteProps>(
   ({ quote, attribution, appearance = "subtle", className, ...props }, ref) => {
@@ -19,6 +20,8 @@ const PullQuote = React.forwardRef<HTMLElement, TypePullQuoteProps>(
         ref={ref}
         className={cn(
           "seeds-pull-quote",
+          "seeds-ai-container",
+          { "seeds-ai-container-vivid": appearance === "vivid" },
           { "seeds-pull-quote-vivid": appearance === "vivid" },
           className
         )}

package/src/ai-container.css

@@ -0,0 +1,39 @@
+/**
+ * Seeds AIContainer 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-ai-container">…</div>            // subtle (default)
+ *   <div class="seeds-ai-container seeds-ai-container-vivid">…</div>
+ */
+
+@layer components {
+
+.seeds-ai-container {
+  position: relative;
+  overflow: hidden;
+  box-sizing: border-box;
+  border-radius: var(--radius-800);
+  box-shadow: var(--shadow-low);
+  font-family: var(--font-family);
+  /* Subtle (default): the 20% AI gradient tint composited over the base
+     surface. --color-gradient-ai-subtle is already translucent, so layering it
+     over the opaque base color produces the soft wash. */
+  background-color: var(--color-container-bg-base);
+  background-image: var(--color-gradient-ai-subtle);
+  color: var(--color-text-headline);
+}
+
+/* Vivid: the full-saturation AI gradient with white content. White has no
+   semantic Seeds token; it is part of the AI gradient treatment (mirrors the
+   raw brand hex used in --color-gradient-ai). */
+.seeds-ai-container-vivid {
+  background-color: transparent;
+  background-image: var(--color-gradient-ai);
+  color: #fff;
+}
+
+}

package/src/css.d.ts

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

package/src/index.ts

@@ -36,4 +36,29 @@ export {
   type TypeNarrativeSummaryLayout,
 } from "./NarrativeSummary";
 
+export {
+  NarrativeOrderedList,
+  type TypeNarrativeOrderedListProps,
+  type TypeNarrativeOrderedListItem,
+  type TypeNarrativeOrderedListOrientation,
+} from "./NarrativeOrderedList";
+
+export {
+  NarrativeDataCallout,
+  type TypeNarrativeDataCalloutProps,
+} from "./NarrativeDataCallout";
+
+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-data-callout.css

@@ -0,0 +1,103 @@
+/**
+ * Seeds NarrativeDataCallout 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.
+ *
+ * The layout is a flex row driven by a container query on the root, so the
+ * visual/text columns stack based on the width the component is given, not the
+ * viewport.
+ *
+ * Usage:
+ *   <div class="seeds-narrative-data-callout">
+ *     <div class="seeds-narrative-data-callout-row">
+ *       <div class="seeds-narrative-data-callout-visual">…chart…</div>
+ *       <div class="seeds-narrative-data-callout-body">…copy…</div>
+ *     </div>
+ *   </div>
+ */
+
+@layer components {
+
+/* Establishes the query container. The row inside reacts to this element's
+   inline size. A container query only styles DESCENDANTS of the query container,
+   so the flex row lives on the inner element, not this one. */
+.seeds-narrative-data-callout {
+  container-type: inline-size;
+  box-sizing: border-box;
+  font-family: var(--font-family);
+}
+
+/* Stacked single column by default (narrow). The container query below turns it
+   into the horizontal 1/3 + 2/3 row once there is room. */
+.seeds-narrative-data-callout-row {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--space-450); /* 24px */
+}
+
+/* Visual slot — layout only, no stroke/background so the injected chart controls
+   its own look and its own size. No fixed height: charts like the data-viz
+   DonutChart carry their own intrinsic height (and a legend), so the slot sizes
+   to the chart rather than clipping it. Stacked full-width until the container
+   query expands the row. */
+.seeds-narrative-data-callout-visual {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  min-width: 0;
+}
+
+/* Stretch the injected visual to the slot's full width. A fluid-width chart like
+   the v2 DonutChart otherwise shrinks to content inside this centered flex slot,
+   so Highcharts fills that shrunk width and the ring gets width-capped below its
+   fixed 270px height — leaving an empty vertical band. Filling the width lets the
+   ring become height-capped and fill its box top-to-bottom, like the standalone
+   chart story. */
+.seeds-narrative-data-callout-visual > * {
+  width: 100%;
+}
+
+/* Body copy — fills the remaining space. */
+.seeds-narrative-data-callout-body {
+  box-sizing: border-box;
+  min-width: 0;
+  font-size: var(--font-size-300); /* 16px */
+  line-height: var(--line-height-400); /* ~28px */
+  font-weight: var(--font-weight-normal);
+  color: var(--color-text-body);
+  overflow-wrap: break-word;
+}
+
+/* Expand to the horizontal 1/3 + 2/3 split once the component is wide enough.
+   The threshold is on the component's own width (container query), so a narrow
+   callout on a wide screen still stacks. 480px keeps the donut + copy readable
+   side by side. */
+@container (min-width: 480px) {
+  .seeds-narrative-data-callout-row {
+    flex-direction: row;
+  }
+
+  .seeds-narrative-data-callout-visual {
+    /* Nominally one-third, but never narrower than the injected chart's fixed
+       height (the v2 DonutChart is 270px tall). Below that width a fluid-width,
+       fixed-height chart like the donut gets width-capped and leaves an empty
+       vertical band above/below the ring; the min-width keeps the visual square
+       enough that the ring fills its box top-to-bottom, matching the standalone
+       chart story. */
+    flex: 0 0 33.333%;
+    min-width: 270px;
+    width: auto;
+  }
+
+  .seeds-narrative-data-callout-body {
+    flex: 1 1 0;
+  }
+}
+
+}

package/src/narrative-ordered-list.css

@@ -0,0 +1,112 @@
+/**
+ * Seeds NarrativeOrderedList 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-ordered-list">
+ *     <ol class="seeds-narrative-ordered-list-track">
+ *       <li class="seeds-narrative-ordered-list-item">…</li>
+ *     </ol>
+ *   </div>
+ */
+
+@layer components {
+
+/* Establishes the query container. The track inside reacts to this element's
+   inline size — a container query can only style descendants of the container,
+   never the container element itself. */
+.seeds-narrative-ordered-list {
+  container-type: inline-size;
+  box-sizing: border-box;
+  font-family: var(--font-family);
+}
+
+/* The list itself, and the default (stacked) layout. The horizontal modifier
+   only expands to a row once the container query below has room, so horizontal
+   collapses back to this stack when narrow. */
+.seeds-narrative-ordered-list-track {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-400); /* 16px */
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* An item row: the ordinal beside the body, on its own rounded surface. */
+.seeds-narrative-ordered-list-item {
+  display: flex;
+  gap: var(--space-450); /* 24px */
+  align-items: flex-start;
+  box-sizing: border-box;
+  min-width: 0;
+  padding: var(--space-400) var(--space-450); /* 16px 24px */
+  border-radius: var(--radius-800); /* 12px */
+  background-color: var(--color-app-bg-base);
+}
+
+/* The ordinal (01, 02, …). No mono token exists yet, so fall back to a system
+   monospace stack — mirrors the value treatment in metric-highlight.css. */
+.seeds-narrative-ordered-list-number {
+  margin: 0;
+  flex-shrink: 0;
+  font-family: var(--font-family-mono, ui-monospace, "SF Mono", SFMono-Regular, Menlo, monospace);
+  font-size: var(--font-size-700); /* 32px */
+  line-height: var(--line-height-700); /* 40px */
+  font-weight: var(--font-weight-bold);
+  color: var(--color-text-headline);
+}
+
+/* Title + description + optional action, stacked. */
+.seeds-narrative-ordered-list-body {
+  flex: 1 1 auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-200); /* 4px */
+  min-width: 0;
+}
+
+/* Title. 16px / 28px — the 28px line-height has no exact type token (the scale
+   skips from 24px to 32px), so the design value is kept verbatim. Same
+   rationale as narrative-summary.css. */
+.seeds-narrative-ordered-list-title {
+  margin: 0;
+  font-size: var(--font-size-300); /* 16px */
+  line-height: 28px; /* off-scale, see comment above */
+  font-weight: var(--font-weight-bold);
+  color: var(--color-text-body);
+}
+
+/* Description. 14px / 24px has no exact type token, so it is kept verbatim —
+   same rationale as the title above. */
+.seeds-narrative-ordered-list-description {
+  margin: 0;
+  font-size: 14px; /* off-scale, see title above */
+  line-height: 24px;
+  font-weight: var(--font-weight-normal);
+  color: var(--color-text-body);
+}
+
+.seeds-narrative-ordered-list-action {
+  padding-top: var(--space-350); /* 12px */
+}
+
+/* Expand the horizontal variant to a row of equal columns once the component is
+   wide enough. The threshold is on the component's own width (container query),
+   so a narrow card on a wide screen still stacks. 640px = Tailwind/Seeds sm
+   breakpoint, matching narrative-summary.css. */
+@container (min-width: 640px) {
+  .seeds-narrative-ordered-list-horizontal {
+    flex-direction: row;
+  }
+
+  .seeds-narrative-ordered-list-horizontal > .seeds-narrative-ordered-list-item {
+    flex: 1 1 0;
+    min-width: 0;
+  }
+}
+
+}

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

@@ -0,0 +1,82 @@
+/**
+ * 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>
+ */
+
+/* Import dependent component styles */
+@import "./narrative-attribution.css";
+
+@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);
+}
+
+}