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

package/dist/narrative-headline.css

@@ -0,0 +1,132 @@
+/**
+ * Seeds NarrativeHeadline 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:
+ *   <h2 class="seeds-narrative-headline">
+ *     Headline with a
+ *     <span class="seeds-narrative-headline-highlight">highlighted</span>
+ *     word
+ *   </h2>
+ */
+
+@layer components {
+
+/* Headline text. Rendered as an h1–h6, so reset the UA heading margins. */
+.seeds-narrative-headline {
+  box-sizing: border-box;
+  margin: 0;
+  font-family: var(--font-family);
+  font-size: var(--font-size-700);
+  line-height: var(--line-height-700);
+  font-weight: var(--font-weight-bold);
+  letter-spacing: -0.02em;
+  color: var(--color-text-headline);
+}
+
+/* Compact size for denser layouts (e.g. NarrativeSummary). Weight, letter
+   spacing, and color are inherited from the base class. */
+.seeds-narrative-headline-small {
+  font-size: var(--font-size-600); /* 24px */
+  line-height: var(--line-height-600); /* 32px */
+}
+
+/* Static gradient accent for a span of headline text ("highlighted word").
+   Paints the AI brand gradient onto the glyphs via background-clip. */
+.seeds-narrative-headline-highlight {
+  background: var(--color-gradient-ai);
+  -webkit-background-clip: text;
+          background-clip: text;
+  color: transparent;
+}
+
+/* -------------------------------------------------------------------------
+   "Roll" variant — vertical word roll. The active word slides into view
+   while the previous one rolls out.
+   ------------------------------------------------------------------------- */
+.seeds-narrative-headline-roll {
+  display: inline-block;
+  position: relative;
+  /* clip-path rather than overflow:hidden: overflow:hidden on an inline-block
+     snaps its baseline to the bottom margin edge, dropping the rolling word
+     below the surrounding text. clip-path keeps the natural baseline. */
+  clip-path: inset(0);
+}
+
+/* Invisible word that holds the box width to the active word. */
+.seeds-narrative-headline-roll-sizer {
+  display: inline-block;
+  visibility: hidden;
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+.seeds-narrative-headline-roll-word {
+  display: inline-block;
+  position: absolute;
+  top: 0;
+  left: 0;
+  white-space: nowrap;
+  transform: translateY(100%);
+  opacity: 0;
+  transition:
+    transform var(--seeds-narrative-headline-roll-ms, 500ms) ease,
+    opacity var(--seeds-narrative-headline-roll-ms, 500ms) ease;
+}
+
+.seeds-narrative-headline-roll-word-active {
+  transform: translateY(0);
+  opacity: 1;
+}
+
+.seeds-narrative-headline-roll-word-past {
+  transform: translateY(-100%);
+  opacity: 0;
+}
+
+/* Reverse the roll direction. */
+.seeds-narrative-headline-roll-down .seeds-narrative-headline-roll-word {
+  transform: translateY(-100%);
+}
+.seeds-narrative-headline-roll-down .seeds-narrative-headline-roll-word-active {
+  transform: translateY(0);
+}
+.seeds-narrative-headline-roll-down .seeds-narrative-headline-roll-word-past {
+  transform: translateY(100%);
+}
+
+/* Gradient-painted rolling words with a slow shimmer. */
+.seeds-narrative-headline-roll-gradient .seeds-narrative-headline-roll-word {
+  background: var(--color-gradient-ai);
+  background-size: 200% 200%;
+  -webkit-background-clip: text;
+          background-clip: text;
+  color: transparent;
+  animation: seeds-narrative-headline-grad-shift 8s ease infinite;
+}
+
+@keyframes seeds-narrative-headline-grad-shift {
+  0%,
+  100% {
+    background-position: 0% 50%;
+  }
+  50% {
+    background-position: 100% 50%;
+  }
+}
+
+/* The JS cycle is already disabled under reduced-motion (the first word holds);
+   also flatten the transition and shimmer so any in-flight motion settles. */
+@media (prefers-reduced-motion: reduce) {
+  .seeds-narrative-headline-roll-word {
+    transition: none;
+  }
+  .seeds-narrative-headline-roll-gradient .seeds-narrative-headline-roll-word {
+    animation: none;
+  }
+}
+
+}

package/dist/narrative-summary.css

@@ -0,0 +1,126 @@
+/**
+ * Seeds NarrativeSummary 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. Also relies on
+ * narrative-headline.css (headline) and eyebrow-token.css (eyebrow).
+ *
+ * The layout is a CSS grid driven by a container query on the root, so the
+ * columns collapse based on the width the component is given, not the viewport.
+ *
+ * Usage:
+ *   <div class="seeds-narrative-summary">
+ *     <div class="seeds-narrative-summary-grid">…</div>
+ *   </div>
+ */
+
+@layer components {
+
+/* Establishes the query container. The grid inside reacts to this element's
+   inline size. */
+.seeds-narrative-summary {
+  container-type: inline-size;
+  box-sizing: border-box;
+  font-family: var(--font-family);
+}
+
+/* Stacked single column by default (narrow). The container query below expands
+   it once there is room. */
+.seeds-narrative-summary-grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--space-450); /* 24px */
+}
+
+/* The lead column: eyebrow, headline, optional action. align-items:flex-start
+   keeps the eyebrow pill and the action sized to their content — without it the
+   column's default stretch would blow the eyebrow out to full width. The
+   headline still fills and wraps because its text is wider than the track. */
+.seeds-narrative-summary-lead {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--space-300); /* 8px */
+  min-width: 0;
+}
+
+/* The headline area grows so the action anchors toward the bottom of the lead
+   column when the neighboring columns are taller. align-self:stretch fills the
+   track width (the lead column pins other items to flex-start) so the headline
+   wraps at the column edge regardless of its length. */
+.seeds-narrative-summary-headline {
+  flex: 1 1 auto;
+  align-self: stretch;
+}
+
+/* In three-column mode the content wrapper is transparent to the grid, so its
+   two sections become grid items in their own columns. In two-column mode the
+   container query below turns it into a real, stacking grid item. */
+.seeds-narrative-summary-content {
+  display: contents;
+}
+
+.seeds-narrative-summary-section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-300); /* 8px */
+  min-width: 0;
+}
+
+/* Section label. 14px / 24px has no exact type token (the scale skips from
+   13px to 16px), so the design value is kept verbatim — same rationale as
+   eyebrow-token.css. All other values use tokens. */
+.seeds-narrative-summary-label {
+  margin: 0;
+  font-size: 14px;
+  line-height: 24px;
+  font-weight: var(--font-weight-bold);
+  color: var(--color-text-headline);
+}
+
+.seeds-narrative-summary-text {
+  margin: 0;
+  font-size: 14px; /* off-scale, see label above */
+  line-height: 24px;
+  font-weight: var(--font-weight-normal);
+  color: var(--color-text-body);
+}
+
+.seeds-narrative-summary-list {
+  margin: 0;
+  padding-inline-start: 21px;
+  list-style: disc;
+  font-size: 14px; /* off-scale, see label above */
+  line-height: 24px;
+  font-weight: var(--font-weight-normal);
+  color: var(--color-text-body);
+}
+
+.seeds-narrative-summary-list li {
+  margin: 0;
+}
+
+/* Expand to the multi-column layout 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. */
+@container (min-width: 640px) {
+  .seeds-narrative-summary-grid {
+    grid-template-columns: repeat(3, 1fr);
+  }
+
+  /* 1/3 lead + 2/3 content. */
+  .seeds-narrative-summary-two-column {
+    grid-template-columns: 1fr 2fr;
+  }
+
+  /* The content wrapper becomes a real grid item that stacks its two sections. */
+  .seeds-narrative-summary-two-column .seeds-narrative-summary-content {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-450); /* 24px */
+    min-width: 0;
+  }
+}
+
+}

package/dist/pull-quote.css

@@ -0,0 +1,89 @@
+/**
+ * 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.
+ *
+ * Usage:
+ *   <figure class="seeds-pull-quote">…</figure>            // subtle (default)
+ *   <figure class="seeds-pull-quote 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;
+  align-items: flex-start;
+  margin: 0; /* reset the browser default <figure> margin */
+  /* 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. */
+.seeds-pull-quote-bar {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--space-450); /* 24px */
+  width: 100%;
+  padding-left: var(--space-450); /* 24px */
+  /* 4px is off the border-width scale (max token is 3px); the bar is a
+     decorative accent, mirroring NarrativeContainer's hardcoded 4px ring. The
+     subtle accent uses the AI gradient mid stop (#9747ff — no exact token). */
+  border-left: 4px solid #9747ff;
+}
+
+.seeds-pull-quote-vivid .seeds-pull-quote-bar {
+  border-left-color: #fff;
+}
+
+.seeds-pull-quote-text {
+  margin: 0; /* reset the browser default <blockquote> margin */
+  font-size: var(--font-size-600);
+  line-height: var(--line-height-600);
+  font-style: italic;
+  font-weight: var(--font-weight-normal);
+  color: inherit;
+  overflow-wrap: break-word;
+}
+
+/* Attribution row — a flex container for author name, avatar, network, etc.
+   Direct text inherits a bold, small treatment to match the display-name style;
+   richer content (e.g. an Avatar) composes freely. */
+.seeds-pull-quote-attribution {
+  display: flex;
+  align-items: center;
+  gap: var(--space-300); /* 8px */
+  font-size: var(--font-size-200);
+  line-height: var(--line-height-200);
+  font-weight: var(--font-weight-bold);
+  color: inherit;
+}
+
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutsocial/seeds-react-narrative-kit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Seeds React Narrative Kit — composable narrative primitives for executive-brief style pages",
   "author": "Sprout Social, Inc.",
   "license": "MIT",
@@ -13,10 +13,16 @@
       "import": "./dist/esm/index.js",
       "require": "./dist/index.js"
     },
-    "./dist/narrative-container.css": "./dist/narrative-container.css"
+    "./dist/narrative-container.css": "./dist/narrative-container.css",
+    "./dist/narrative-headline.css": "./dist/narrative-headline.css",
+    "./dist/pull-quote.css": "./dist/pull-quote.css",
+    "./dist/metric-highlight.css": "./dist/metric-highlight.css",
+    "./dist/eyebrow-token.css": "./dist/eyebrow-token.css",
+    "./dist/narrative-summary.css": "./dist/narrative-summary.css",
+    "./dist/narrative-divider.css": "./dist/narrative-divider.css"
   },
   "scripts": {
-    "build": "tsup --dts && cp src/narrative-container.css dist/narrative-container.css",
+    "build": "tsup --dts && cp src/narrative-container.css dist/narrative-container.css && cp src/narrative-headline.css dist/narrative-headline.css && cp src/pull-quote.css dist/pull-quote.css && cp src/metric-highlight.css dist/metric-highlight.css && cp src/eyebrow-token.css dist/eyebrow-token.css && cp src/narrative-summary.css dist/narrative-summary.css && cp src/narrative-divider.css dist/narrative-divider.css",
     "build:debug": "tsup --dts --metafile",
     "dev": "tsup --watch --dts",
     "clean": "rm -rf .turbo dist",
@@ -30,6 +36,10 @@
   },
   "devDependencies": {
     "@sproutsocial/eslint-config-seeds": "*",
+    "@sproutsocial/seeds-react-button": "*",
+    "@sproutsocial/seeds-react-data-viz": "*",
+    "@sproutsocial/seeds-react-grid": "^0.2.5",
+    "@sproutsocial/seeds-react-text": "*",
     "@sproutsocial/seeds-react-testing-library": "*",
     "@sproutsocial/seeds-testing": "*",
     "@sproutsocial/seeds-tsconfig": "*",

package/src/EyebrowToken/EyebrowToken.stories.tsx

@@ -0,0 +1,25 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import EyebrowToken from "./EyebrowToken";
+import "../eyebrow-token.css";
+
+const meta = {
+  title: "Narrative Kit/EyebrowToken",
+  component: EyebrowToken,
+  args: {
+    children: "May 31, 2026",
+  },
+} satisfies Meta<typeof EyebrowToken>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A small gray pill carrying a date — the typical eyebrow above a headline. */
+export const Default: Story = {};
+
+/** A category kicker instead of a date. */
+export const Category: Story = {
+  args: {
+    children: "Quarterly review",
+  },
+};

package/src/EyebrowToken/EyebrowToken.tsx

@@ -0,0 +1,25 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypeEyebrowTokenProps } from "./EyebrowTokenTypes";
+
+/**
+ * EyebrowToken — a small gray pill that sits above a headline to carry a short
+ * bit of context: a date (e.g. "May 31, 2026"), category, or kicker.
+ *
+ * A faithful match of the Figma "Token / Non Clickable / Default" design — a
+ * solid `#dee1e1` fill with a matching border, 6px radius, and small body text.
+ * Styled via `eyebrow-token.css` (Seeds CSS custom properties); consumers import
+ * the classes through `@sproutsocial/racine/css/components`. Overrides come via
+ * standard `className` / `style`.
+ */
+const EyebrowToken = React.forwardRef<HTMLSpanElement, TypeEyebrowTokenProps>(
+  ({ children, className, ...props }, ref) => (
+    <span ref={ref} className={cn("seeds-eyebrow-token", className)} {...props}>
+      {children}
+    </span>
+  )
+);
+
+EyebrowToken.displayName = "EyebrowToken";
+
+export default EyebrowToken;

package/src/EyebrowToken/EyebrowTokenTypes.ts

@@ -0,0 +1,7 @@
+import type * as React from "react";
+
+export interface TypeEyebrowTokenProps
+  extends React.HTMLAttributes<HTMLSpanElement> {
+  /** The eyebrow text — a date, category, or short kicker. */
+  children: React.ReactNode;
+}

package/src/EyebrowToken/__tests__/EyebrowToken.test.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import EyebrowToken from "../EyebrowToken";
+
+describe("EyebrowToken", () => {
+  it("renders its children", () => {
+    render(<EyebrowToken>May 31, 2026</EyebrowToken>);
+
+    expect(screen.getByText("May 31, 2026")).toBeInTheDocument();
+  });
+
+  it("merges a consumer className with the base class", () => {
+    const { container } = render(
+      <EyebrowToken className="custom">May 31, 2026</EyebrowToken>
+    );
+
+    const root = container.querySelector(".seeds-eyebrow-token");
+    expect(root).toBeInTheDocument();
+    expect(root).toHaveClass("custom");
+  });
+
+  it("forwards extra props to the underlying element", () => {
+    render(<EyebrowToken data-testid="eyebrow">May 31, 2026</EyebrowToken>);
+
+    expect(screen.getByTestId("eyebrow")).toBeInTheDocument();
+  });
+
+  it("forwards its ref to the underlying span element", () => {
+    const ref = React.createRef<HTMLSpanElement>();
+    render(<EyebrowToken ref={ref}>May 31, 2026</EyebrowToken>);
+
+    expect(ref.current).toBeInstanceOf(HTMLSpanElement);
+    expect(ref.current?.tagName).toBe("SPAN");
+  });
+});

package/src/EyebrowToken/index.ts

@@ -0,0 +1,2 @@
+export { default as EyebrowToken } from "./EyebrowToken";
+export type { TypeEyebrowTokenProps } from "./EyebrowTokenTypes";

package/src/MetricHighlight/MetricHighlight.stories.tsx

@@ -0,0 +1,110 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { SparklineChart } from "@sproutsocial/seeds-react-data-viz/sparkline";
+import MetricHighlight from "./MetricHighlight";
+import "../metric-highlight.css";
+import "@sproutsocial/seeds-react-data-viz/sparkline.css";
+
+/**
+ * MetricHighlight has no built-in chart — the `sparkline` slot accepts any node.
+ * These stories inject the real `SparklineChart` from
+ * `@sproutsocial/seeds-react-data-viz`; narrative-kit takes no runtime
+ * dependency on data-viz (only these stories do, via a devDependency). The
+ * injected chart fills the slot with `className="h-full w-full"`.
+ */
+const RISING = [4, 6, 5, 8, 7, 10];
+const FALLING = [18, 16, 17, 13, 14, 10];
+
+const spark = (
+  data: number[],
+  variant: "line" | "bar" = "line"
+): React.ReactNode => (
+  <SparklineChart
+    variant={variant}
+    description="Weekly trend"
+    data={data}
+    className="h-full w-full"
+  />
+);
+
+const meta = {
+  title: "Narrative Kit/MetricHighlight",
+  component: MetricHighlight,
+  args: {
+    label: "Insight metric",
+    value: "123",
+    trend: { direction: "up", value: "240%", "aria-label": "up 240%" },
+    sparkline: spark(RISING),
+  },
+} satisfies Meta<typeof MetricHighlight>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Horizontal, default size, padded surface, numeric trend badge, and a sparkline. */
+export const Default: Story = {
+  args: {
+    className: "w-80",
+  },
+};
+
+/** Condensed: label and value share a single row. */
+export const Small: Story = {
+  args: {
+    className: "w-80",
+    size: "small",
+  },
+};
+
+/** Stacked: metric block above a full-width sparkline. */
+export const Vertical: Story = {
+  args: {
+    className: "w-80",
+    appearance: "vertical",
+  },
+};
+
+/** No surface — composes inside another container. */
+export const WithoutContainer: Story = {
+  args: {
+    className: "w-80",
+    container: false,
+  },
+};
+
+/** Metric on its own — omit the `sparkline` slot to drop the chart. */
+export const WithoutChart: Story = {
+  args: {
+    className: "w-80",
+    sparkline: undefined,
+  },
+};
+
+/**
+ * Negative trend — the badge swaps to the red treatment and the sparkline (which
+ * auto-colors from its data) slopes downward in red.
+ */
+export const TrendDown: Story = {
+  args: {
+    className: "w-80",
+    value: "87",
+    trend: { direction: "down", value: "12%", "aria-label": "down 12%" },
+    sparkline: spark(FALLING),
+  },
+};
+
+/** Icon-only trend badge (no number). */
+export const TrendIconOnly: Story = {
+  args: {
+    className: "w-80",
+    trend: { direction: "up", "aria-label": "trending up" },
+  },
+};
+
+/** The slot accepts the bar variant of the sparkline just as well. */
+export const BarSparkline: Story = {
+  args: {
+    className: "w-80",
+    sparkline: spark(RISING, "bar"),
+  },
+};