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

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/Playground/Playground.stories.tsx

@@ -10,9 +10,12 @@ 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 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 "../narrative-container.css";
 import "../narrative-headline.css";
 import "../pull-quote.css";
@@ -20,12 +23,14 @@ 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 "@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 +91,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 +133,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 +182,52 @@ 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>
         </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/index.ts

@@ -36,4 +36,18 @@ 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 type { TypeNarrativeTone } from "./_internal/types";

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/pull-quote.css

@@ -2,20 +2,17 @@
  * Seeds PullQuote 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.
+ * Requires @sproutsocial/seeds-react-theme/dist/theme-all.css and
+ * ai-container.css imported for CSS variable definitions and surface styles.
  *
  * Usage:
- *   <figure class="seeds-pull-quote">…</figure>            // subtle (default)
- *   <figure class="seeds-pull-quote seeds-pull-quote-vivid">…</figure>
+ *   <figure class="seeds-pull-quote seeds-ai-container">…</figure>            // subtle (default)
+ *   <figure class="seeds-pull-quote seeds-ai-container seeds-ai-container-vivid seeds-pull-quote-vivid">…</figure>
  */
 
 @layer components {
 
 .seeds-pull-quote {
-  position: relative;
-  overflow: hidden;
-  box-sizing: border-box;
   width: 100%;
   display: flex;
   flex-direction: column;
@@ -24,24 +21,6 @@
   /* 40px block / 48px inline — 48px is off the space scale, so derive it from
      two tokens (40 + 8) rather than hardcoding an off-scale value. */
   padding: var(--space-600) calc(var(--space-600) + var(--space-300));
-  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-pull-quote-vivid {
-  background-color: transparent;
-  background-image: var(--color-gradient-ai);
-  color: #fff;
 }
 
 /* The accented bar holding the quote and attribution. */