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

package/dist/narrative-headline.css

@@ -0,0 +1,125 @@
+/**
+ * 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);
+}
+
+/* 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/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.2.0",
   "description": "Seeds React Narrative Kit — composable narrative primitives for executive-brief style pages",
   "author": "Sprout Social, Inc.",
   "license": "MIT",
@@ -13,10 +13,14 @@
       "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"
   },
   "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",
     "build:debug": "tsup --dts --metafile",
     "dev": "tsup --watch --dts",
     "clean": "rm -rf .turbo dist",
@@ -30,6 +34,8 @@
   },
   "devDependencies": {
     "@sproutsocial/eslint-config-seeds": "*",
+    "@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,29 @@
+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,87 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import MetricHighlight from "./MetricHighlight";
+import "../metric-highlight.css";
+
+const meta = {
+  title: "Narrative Kit/MetricHighlight",
+  component: MetricHighlight,
+  args: {
+    label: "Insight metric",
+    value: "123",
+    trend: { direction: "up", value: "240%", "aria-label": "up 240%" },
+  },
+} satisfies Meta<typeof MetricHighlight>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Horizontal, default size, padded surface, numeric trend badge, and the
+ * default sparkline (no `data` passed).
+ */
+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 without the sparkline. */
+export const WithoutChart: Story = {
+  args: {
+    className: "w-80",
+    chart: false,
+  },
+};
+
+/**
+ * Negative trend — the badge swaps to the red treatment and the default
+ * sparkline slopes downward in red.
+ */
+export const TrendDown: Story = {
+  args: {
+    className: "w-80",
+    value: "87",
+    trend: { direction: "down", value: "12%", "aria-label": "down 12%" },
+  },
+};
+
+/** Consumer-supplied data overrides the default series. */
+export const CustomData: Story = {
+  args: {
+    className: "w-80",
+    data: [4, 9, 6, 12, 8, 15, 11, 18, 14, 22],
+  },
+};
+
+/** Icon-only trend badge (no number). */
+export const TrendIconOnly: Story = {
+  args: {
+    className: "w-80",
+    trend: { direction: "up", "aria-label": "trending up" },
+  },
+};

package/src/MetricHighlight/MetricHighlight.tsx

@@ -0,0 +1,196 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type {
+  TypeMetricHighlightProps,
+  TypeMetricHighlightTrend,
+} from "./MetricHighlightTypes";
+
+/** Fixed viewBox the sparkline normalizes into; CSS stretches it to fit. */
+const SPARK_VIEWBOX_WIDTH = 100;
+const SPARK_VIEWBOX_HEIGHT = 32;
+/** Inset so the stroke at the min/max points isn't clipped by the viewBox edge. */
+const SPARK_PADDING = 2;
+
+/**
+ * Default sparkline series used when the consumer doesn't pass `data` — a gently
+ * rising wave. It's reversed for a downward trend so the line slopes to match.
+ */
+const DEFAULT_SPARK = [6, 10, 8, 13, 11, 16];
+
+/**
+ * Build a smooth SVG path through `points` using a Catmull-Rom spline converted
+ * to cubic béziers. Each segment's control points are derived from its
+ * neighbors, so the curve passes through every data point with soft, rounded
+ * transitions (matching the design) rather than sharp polyline corners.
+ */
+const smoothPath = (points: { x: number; y: number }[]) => {
+  if (points.length < 2) {
+    const p = points[0];
+    return p ? `M ${p.x},${p.y}` : "";
+  }
+
+  let d = `M ${points[0]!.x.toFixed(2)},${points[0]!.y.toFixed(2)}`;
+  for (let i = 0; i < points.length - 1; i++) {
+    // The loop bound guarantees p1 and p2; p0/p3 clamp to the endpoints.
+    const p1 = points[i]!;
+    const p2 = points[i + 1]!;
+    const p0 = points[i - 1] ?? p1;
+    const p3 = points[i + 2] ?? p2;
+    // Catmull-Rom → bézier control points (tension 1/6).
+    const cp1x = p1.x + (p2.x - p0.x) / 6;
+    const cp1y = p1.y + (p2.y - p0.y) / 6;
+    const cp2x = p2.x - (p3.x - p1.x) / 6;
+    const cp2y = p2.y - (p3.y - p1.y) / 6;
+    d += ` C ${cp1x.toFixed(2)},${cp1y.toFixed(2)} ${cp2x.toFixed(
+      2
+    )},${cp2y.toFixed(2)} ${p2.x.toFixed(2)},${p2.y.toFixed(2)}`;
+  }
+  return d;
+};
+
+/**
+ * Sparkline — an inline SVG path normalized from `data` into a fixed viewBox and
+ * smoothed into a soft curve. `preserveAspectRatio="none"` plus a non-scaling
+ * stroke (set in CSS) lets a single path stretch to any width/height while
+ * keeping a crisp line.
+ */
+const Sparkline = ({
+  data,
+  negative,
+}: {
+  data: number[];
+  negative?: boolean;
+}) => {
+  const min = Math.min(...data);
+  const max = Math.max(...data);
+  const range = max - min || 1;
+  const usableHeight = SPARK_VIEWBOX_HEIGHT - SPARK_PADDING * 2;
+
+  const points = data.map((value, i) => ({
+    x:
+      data.length === 1
+        ? SPARK_VIEWBOX_WIDTH / 2
+        : (i / (data.length - 1)) * SPARK_VIEWBOX_WIDTH,
+    // Invert y so larger values sit higher in the chart.
+    y: SPARK_PADDING + (1 - (value - min) / range) * usableHeight,
+  }));
+
+  return (
+    <svg
+      className={cn("seeds-metric-highlight-spark", {
+        "seeds-metric-highlight-spark-negative": Boolean(negative),
+      })}
+      viewBox={`0 0 ${SPARK_VIEWBOX_WIDTH} ${SPARK_VIEWBOX_HEIGHT}`}
+      preserveAspectRatio="none"
+      aria-hidden
+      focusable={false}
+    >
+      <path d={smoothPath(points)} fill="none" strokeLinecap="round" />
+    </svg>
+  );
+};
+
+/** Directional arrow glyph for the trend badge (decorative; `aria-hidden`). */
+const TrendArrow = ({ direction }: { direction: "up" | "down" }) => (
+  <svg
+    className="seeds-metric-highlight-trend-arrow"
+    viewBox="0 0 16 16"
+    aria-hidden
+    focusable={false}
+  >
+    {direction === "up" ? (
+      <path
+        d="M4.5 11.5 11.5 4.5M11.5 4.5H5.5M11.5 4.5V10.5"
+        fill="none"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    ) : (
+      <path
+        d="M4.5 4.5 11.5 11.5M11.5 11.5H5.5M11.5 11.5V5.5"
+        fill="none"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    )}
+  </svg>
+);
+
+const TrendBadge = ({ direction = "up", value, ...rest }: TypeMetricHighlightTrend) => (
+  <span
+    className={cn("seeds-metric-highlight-trend", {
+      "seeds-metric-highlight-trend-down": direction === "down",
+    })}
+    {...rest}
+  >
+    <TrendArrow direction={direction} />
+    {value != null && (
+      <span className="seeds-metric-highlight-trend-value">{value}</span>
+    )}
+  </span>
+);
+
+/**
+ * MetricHighlight — a narrative primitive that spotlights a single metric: a
+ * label, a large monospace value, an optional trend badge (a directional arrow
+ * plus an optional number such as "240%"), and an optional sparkline.
+ *
+ * Styled via `metric-highlight.css` (Seeds CSS custom properties); consumers
+ * import the classes through `@sproutsocial/racine/css/components`. Layout flexes
+ * across `appearance` (horizontal/vertical) and `size` (default/small); surface
+ * overrides are done with standard `className` / `style`.
+ */
+const MetricHighlight = React.forwardRef<HTMLDivElement, TypeMetricHighlightProps>(
+  (
+    {
+      label,
+      value,
+      trend,
+      data,
+      chart = true,
+      appearance = "horizontal",
+      size = "default",
+      container = true,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    const isDown = trend?.direction === "down";
+    // Fall back to a sensible default series, sloped to match the trend, so the
+    // chart renders without the consumer wiring up data. An explicit `data`
+    // (including an empty array to opt out) always wins.
+    const resolvedData =
+      data ?? (isDown ? [...DEFAULT_SPARK].reverse() : DEFAULT_SPARK);
+    const showChart = chart && resolvedData.length > 0;
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "seeds-metric-highlight",
+          {
+            "seeds-metric-highlight-vertical": appearance === "vertical",
+            "seeds-metric-highlight-small": size === "small",
+            "seeds-metric-highlight-bare": !container,
+          },
+          className
+        )}
+        {...props}
+      >
+        <div className="seeds-metric-highlight-metric">
+          <p className="seeds-metric-highlight-label">{label}</p>
+          <div className="seeds-metric-highlight-value-row">
+            <p className="seeds-metric-highlight-value">{value}</p>
+            {trend != null && <TrendBadge {...trend} />}
+          </div>
+        </div>
+        {showChart && <Sparkline data={resolvedData} negative={isDown} />}
+      </div>
+    );
+  }
+);
+
+MetricHighlight.displayName = "MetricHighlight";
+
+export default MetricHighlight;