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

package/src/Playground/Playground.stories.tsx

@@ -0,0 +1,163 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Grid from "@sproutsocial/seeds-react-grid";
+import NarrativeContainer from "../NarrativeContainer/NarrativeContainer";
+import NarrativeHeadline from "../NarrativeHeadline/NarrativeHeadline";
+import NarrativeHeadlineHighlight from "../NarrativeHeadline/NarrativeHeadlineHighlight";
+import NarrativeHeadlineRoll from "../NarrativeHeadline/NarrativeHeadlineRoll";
+import PullQuote from "../PullQuote/PullQuote";
+import MetricHighlight from "../MetricHighlight/MetricHighlight";
+import EyebrowToken from "../EyebrowToken/EyebrowToken";
+import NarrativeDivider from "../NarrativeDivider/NarrativeDivider";
+import NarrativeSummary from "../NarrativeSummary/NarrativeSummary";
+import Button from "@sproutsocial/seeds-react-button";
+import Text from "@sproutsocial/seeds-react-text";
+import { SparklineChart } from "@sproutsocial/seeds-react-data-viz/sparkline";
+import "../narrative-container.css";
+import "../narrative-headline.css";
+import "../pull-quote.css";
+import "../metric-highlight.css";
+import "../eyebrow-token.css";
+import "../narrative-divider.css";
+import "../narrative-summary.css";
+import "@sproutsocial/seeds-react-button/dist/button.css";
+import "@sproutsocial/seeds-react-data-viz/sparkline.css";
+
+const spark = (data: number[]) => (
+  <SparklineChart
+    variant="line"
+    description="Trend"
+    data={data}
+    className="h-full w-full"
+  />
+);
+
+/**
+ * Narrative Kit — Playground (showcase story)
+ * ============================================
+ * A living showcase that composes the narrative primitives exactly as an agent
+ * would assemble them in production. It only ever uses primitives that have
+ * actually shipped in the kit — as new ones land, drop them in here and the
+ * showcase grows with the ecosystem.
+ *
+ * Today's shipped primitives: NarrativeContainer, NarrativeHeadline
+ * (+ Highlight / + Roll), PullQuote, and MetricHighlight. Layout uses
+ * `@sproutsocial/seeds-react-grid` to arrange the containers.
+ */
+
+const Attribution = ({ name }: { name: string }) => (
+  <>
+    <span aria-hidden className="text-400">
+      🧵
+    </span>
+    <span>{name}</span>
+  </>
+);
+
+const Brief = () => (
+  <div className="box-border min-h-screen p-600 bg-app-bg-base">
+    <div className="max-w-280 mx-auto grid gap-500">
+      <span>
+        <EyebrowToken className="mb-300 inline-flex">May 31, 2026</EyebrowToken>
+        <NarrativeHeadline headingLevel={1}>
+          The social suite built for{" "}
+          <NarrativeHeadlineRoll
+            words={["marketers", "agencies", "enterprise teams", "founders"]}
+          />
+        </NarrativeHeadline>
+        <Text.BodyCopy mt={400} display="block" width="50ch">
+          Empowering cross-functional stakeholders to drive engagement at scale
+          and accelerate time-to-value through data-driven content strategies
+          aligned with your brand's north-star KPIs.
+        </Text.BodyCopy>
+      </span>
+
+      {/* Pull quotes ------------------------------------------------------- */}
+      <NarrativeContainer className="w-full">
+        <Grid columns={{ sm: 1, md: 1 }} gap={500}>
+          {/* Metric highlights — a row of 3 -------------------------------- */}
+          <Grid columns={{ sm: 1, md: 2, lg: 3 }} gap={400}>
+            <MetricHighlight
+              label="Impressions"
+              value="1.2M"
+              trend={{ direction: "up", value: "18%", "aria-label": "up 18%" }}
+              sparkline={spark([8, 12, 9, 15, 13, 19])}
+            />
+            <MetricHighlight
+              label="Engagement rate"
+              value="6.4%"
+              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])}
+            />
+          </Grid>
+
+          {/* Divider — separates the metric row from the narrative below --- */}
+          <NarrativeDivider />
+
+          {/* Narrative summary (2-column) — between the pull quotes -------- */}
+          <NarrativeSummary
+            layout="two-column"
+            eyebrow="June 10th"
+            headline="Engagement climbed across every owned channel this month"
+            summary="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."
+            keyThemes={[
+              "Reply threads outperformed paid pushes for the week.",
+              "Average response time dropped nearly in half.",
+              "Enterprise segment drove the largest share of new engagement.",
+            ]}
+          />
+
+          <PullQuote
+            quote="The reply thread on the 18th outperformed our entire paid push for the week."
+            attribution={<Attribution name="Jordan Lee" />}
+          />
+
+          <NarrativeDivider />
+
+          {/* Narrative summary (3-column) — below the pull quotes --------- */}
+          <NarrativeSummary
+            eyebrow="Quarterly review"
+            headline="Three themes defined the quarter for the brand"
+            action={<Button appearance="primary">View report</Button>}
+            summary="Praesent pretium libero vitae arcu blandit pellentesque. Aenean fermentum, nisi eu blandit placerat, ligula ligula euismod ante, id semper nibh diam ac ipsum."
+            keyThemes={[
+              "Owned channels outpaced paid across every region.",
+              "Response time held under two hours through peak weeks.",
+              "Sentiment trended positive after the product launch.",
+            ]}
+          />
+
+          <PullQuote
+            appearance="vivid"
+            quote="This rollout cut our average response time nearly in half."
+            attribution={<Attribution name="Priya Nair" />}
+          />
+        </Grid>
+      </NarrativeContainer>
+    </div>
+  </div>
+);
+
+const meta: Meta = {
+  title: "Narrative Kit/Playground",
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * The showcase brief. Resize the canvas to watch the Grid reflow from 2 → 1
+ * column. Toggle dark mode (Storybook toolbar) to verify token-driven theming.
+ */
+export const ExecutiveBrief: Story = {
+  render: () => <Brief />,
+};

package/src/PullQuote/PullQuote.stories.tsx

@@ -0,0 +1,45 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import PullQuote from "./PullQuote";
+import "../pull-quote.css";
+
+const meta = {
+  title: "Narrative Kit/PullQuote",
+  component: PullQuote,
+  args: {
+    quote: "This rollout cut our average response time nearly in half.",
+  },
+} satisfies Meta<typeof PullQuote>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const Attribution = () => (
+  <>
+    <span aria-hidden className="text-400">
+      🧵
+    </span>
+    <span>Display Name</span>
+  </>
+);
+
+export const Subtle: Story = {
+  args: {
+    className: "w-80",
+    attribution: <Attribution />,
+  },
+};
+
+export const Vivid: Story = {
+  args: {
+    className: "w-80",
+    appearance: "vivid",
+    attribution: <Attribution />,
+  },
+};
+
+export const WithoutAttribution: Story = {
+  args: {
+    className: "w-80",
+  },
+};

package/src/PullQuote/PullQuote.tsx

@@ -0,0 +1,42 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypePullQuoteProps } from "./PullQuoteTypes";
+
+/**
+ * PullQuote — a narrative primitive that spotlights a quotation on an AI
+ * gradient surface. The quote sits behind an accented vertical bar with an
+ * 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`.
+ */
+const PullQuote = React.forwardRef<HTMLElement, TypePullQuoteProps>(
+  ({ quote, attribution, appearance = "subtle", className, ...props }, ref) => {
+    return (
+      <figure
+        ref={ref}
+        className={cn(
+          "seeds-pull-quote",
+          { "seeds-pull-quote-vivid": appearance === "vivid" },
+          className
+        )}
+        {...props}
+      >
+        <div className="seeds-pull-quote-bar">
+          <blockquote className="seeds-pull-quote-text">{quote}</blockquote>
+          {attribution != null && (
+            <figcaption className="seeds-pull-quote-attribution">
+              {attribution}
+            </figcaption>
+          )}
+        </div>
+      </figure>
+    );
+  }
+);
+
+PullQuote.displayName = "PullQuote";
+
+export default PullQuote;

package/src/PullQuote/PullQuoteTypes.ts

@@ -0,0 +1,18 @@
+import type * as React from "react";
+
+export interface TypePullQuoteProps extends React.HTMLAttributes<HTMLElement> {
+  /** The quotation text, rendered emphasized inside the accented bar. */
+  quote: React.ReactNode;
+  /**
+   * Optional attribution slot rendered beneath the quote (e.g. an author name,
+   * avatar, and network). Composed by the consumer; omitted entirely when absent.
+   */
+  attribution?: 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.
+   * @default "subtle"
+   */
+  appearance?: "subtle" | "vivid";
+}

package/src/PullQuote/__tests__/PullQuote.test.tsx

@@ -0,0 +1,48 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import PullQuote from "../PullQuote";
+
+describe("PullQuote", () => {
+  it("renders the quote text in a blockquote", () => {
+    render(<PullQuote quote="A memorable line" />);
+
+    const quote = screen.getByText("A memorable line");
+    expect(quote).toBeInTheDocument();
+    expect(quote.tagName).toBe("BLOCKQUOTE");
+  });
+
+  it("renders the attribution in a figcaption when provided", () => {
+    const { container } = render(
+      <PullQuote quote="A line" attribution={<span>Jane Doe</span>} />
+    );
+
+    expect(screen.getByText("Jane Doe")).toBeInTheDocument();
+    expect(container.querySelector("figcaption")).toBeInTheDocument();
+  });
+
+  it("omits the figcaption when no attribution is provided", () => {
+    const { container } = render(<PullQuote quote="A line" />);
+
+    expect(container.querySelector("figcaption")).not.toBeInTheDocument();
+  });
+
+  it("applies the vivid modifier only for the vivid appearance", () => {
+    const { container, rerender } = render(<PullQuote quote="A line" />);
+    expect(
+      container.querySelector(".seeds-pull-quote-vivid")
+    ).not.toBeInTheDocument();
+
+    rerender(<PullQuote quote="A line" appearance="vivid" />);
+    expect(
+      container.querySelector(".seeds-pull-quote-vivid")
+    ).toBeInTheDocument();
+  });
+
+  it("forwards its ref to the underlying figure element", () => {
+    const ref = React.createRef<HTMLElement>();
+    render(<PullQuote ref={ref} quote="A line" />);
+
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+    expect(ref.current?.tagName).toBe("FIGURE");
+  });
+});

package/src/PullQuote/index.ts

@@ -0,0 +1,2 @@
+export { default as PullQuote } from "./PullQuote";
+export type { TypePullQuoteProps } from "./PullQuoteTypes";

package/src/_internal/cn.ts

@@ -0,0 +1,22 @@
+/** Merge class names, supporting `{ "class": boolean }` toggles. */
+export function cn(
+  ...inputs: (string | undefined | null | false | Record<string, boolean>)[]
+): string {
+  const classes: string[] = [];
+
+  for (const input of inputs) {
+    if (!input) continue;
+
+    if (typeof input === "string") {
+      classes.push(input);
+    } else if (typeof input === "object") {
+      for (const [key, value] of Object.entries(input)) {
+        if (value) {
+          classes.push(key);
+        }
+      }
+    }
+  }
+
+  return classes.join(" ");
+}

package/src/eyebrow-token.css

@@ -0,0 +1,37 @@
+/**
+ * Seeds EyebrowToken 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:
+ *   <span class="seeds-eyebrow-token">May 31, 2026</span>
+ */
+
+@layer components {
+
+/* A solid gray pill matching the design: background and border are both the
+   #dee1e1 container-border-base token, which also tracks dark mode. The two
+   pixel literals below have no exact theme token — the --space scale skips 6px
+   (4px→8px) and the --font-size scale skips 12px (11px→13px) — so the design's
+   values are kept verbatim. All colors use tokens. */
+.seeds-eyebrow-token {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-100); /* 2px */
+  padding: var(--space-100) var(--space-300); /* 2px / 8px */
+  border: 1px solid var(--color-container-border-base); /* #dee1e1 */
+  border-radius: var(--radius-500); /* 6px */
+  background-color: var(--color-container-border-base); /* #dee1e1 */
+  font-family: var(--font-family);
+  font-size: 12px; /* text-sm */
+  line-height: 20px;
+  font-weight: var(--font-weight-normal);
+  color: var(--color-text-body);
+  white-space: nowrap;
+}
+
+}

package/src/index.ts

@@ -5,4 +5,35 @@ export {
   type TypeNarrativeContainerProps,
 } from "./NarrativeContainer";
 
+export {
+  NarrativeHeadline,
+  NarrativeHeadlineHighlight,
+  NarrativeHeadlineRoll,
+  type TypeNarrativeHeadlineProps,
+  type TypeNarrativeHeadlineLevel,
+  type TypeNarrativeHeadlineHighlightProps,
+  type TypeNarrativeHeadlineRollProps,
+} from "./NarrativeHeadline";
+
+export { PullQuote, type TypePullQuoteProps } from "./PullQuote";
+
+export { EyebrowToken, type TypeEyebrowTokenProps } from "./EyebrowToken";
+
+export {
+  NarrativeDivider,
+  type TypeNarrativeDividerProps,
+} from "./NarrativeDivider";
+
+export {
+  MetricHighlight,
+  type TypeMetricHighlightProps,
+  type TypeMetricHighlightTrend,
+} from "./MetricHighlight";
+
+export {
+  NarrativeSummary,
+  type TypeNarrativeSummaryProps,
+  type TypeNarrativeSummaryLayout,
+} from "./NarrativeSummary";
+
 export type { TypeNarrativeTone } from "./_internal/types";

package/src/metric-highlight.css

@@ -0,0 +1,168 @@
+/**
+ * Seeds MetricHighlight 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-metric-highlight">…</div>                       // horizontal, default
+ *   <div class="seeds-metric-highlight seeds-metric-highlight-vertical">…</div>
+ *   <div class="seeds-metric-highlight seeds-metric-highlight-small">…</div>
+ *   <div class="seeds-metric-highlight seeds-metric-highlight-bare">…</div>   // no surface
+ */
+
+@layer components {
+
+.seeds-metric-highlight {
+  box-sizing: border-box;
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-350); /* 12px */
+  border-radius: var(--radius-800); /* 12px */
+  font-family: var(--font-family);
+  /* Container (default): a padded gray app surface (matches the design's
+     #f3f4f4 box). `-bare` strips it. */
+  padding: var(--space-400) var(--space-450); /* 16px / 24px */
+  background-color: var(--color-app-bg-base);
+}
+
+.seeds-metric-highlight-bare {
+  padding: 0;
+  background-color: transparent;
+}
+
+.seeds-metric-highlight-vertical {
+  flex-direction: column;
+}
+
+/* The metric block: label + value/trend. Grows to fill the row in horizontal. */
+.seeds-metric-highlight-metric {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--space-200); /* 4px */
+  flex: 1 0 0;
+  min-width: 0;
+}
+
+.seeds-metric-highlight-vertical .seeds-metric-highlight-metric {
+  width: 100%;
+  flex: 0 0 auto;
+}
+
+/* Small: label and value collapse onto a single centered row. */
+.seeds-metric-highlight-small .seeds-metric-highlight-metric {
+  flex-direction: row;
+  align-items: center;
+  gap: var(--space-300); /* 8px */
+}
+
+.seeds-metric-highlight-label {
+  margin: 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;
+}
+
+/* In small, the label takes the slack so the value/trend align to the end. */
+.seeds-metric-highlight-small .seeds-metric-highlight-label {
+  flex: 1 0 0;
+  min-width: 0;
+}
+
+.seeds-metric-highlight-value-row {
+  display: flex;
+  align-items: center;
+  gap: var(--space-300); /* 8px */
+}
+
+.seeds-metric-highlight-small .seeds-metric-highlight-value-row {
+  justify-content: flex-end;
+}
+
+.seeds-metric-highlight-value {
+  margin: 0;
+  /* No mono token exists yet; fall back to a system monospace stack. Mirrors the
+     font/font-mono treatment in the design. */
+  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);
+  white-space: nowrap;
+}
+
+.seeds-metric-highlight-small .seeds-metric-highlight-value {
+  font-size: var(--font-size-600); /* 24px */
+  line-height: var(--line-height-600); /* 32px */
+}
+
+/* Trend badge — a rounded pill. Up is the positive (green) treatment; down
+   swaps to the negative (red) treatment. Color flows to the arrow + value via
+   currentColor. */
+.seeds-metric-highlight-trend {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-200); /* 4px */
+  padding: var(--space-100) var(--space-300); /* 2px / 8px */
+  border-radius: 999px;
+  font-size: var(--font-size-200); /* 13px */
+  line-height: var(--line-height-200);
+  font-weight: var(--font-weight-bold);
+  white-space: nowrap;
+  background-color: var(--color-container-bg-decorative-green);
+  color: var(--color-text-decorative-green);
+}
+
+.seeds-metric-highlight-trend-down {
+  background-color: var(--color-container-bg-decorative-red);
+  color: var(--color-text-decorative-red);
+}
+
+.seeds-metric-highlight-trend-arrow {
+  flex: 0 0 auto;
+  width: 1em;
+  height: 1em;
+  stroke: currentColor;
+  stroke-width: 1.5;
+}
+
+/* Slot for an injected chart (e.g. a data-viz SparklineChart). Layout only — no
+   stroke/background styling, so the injected chart controls its own look. Heights
+   are explicit (never percentage/stretch) so a Highcharts chart always measures a
+   concrete container instead of falling back to its 400px default. */
+.seeds-metric-highlight-chart {
+  box-sizing: border-box;
+  flex: 0 0 auto;
+  align-self: center;
+  /* Center the injected chart as a flex item — an inline/inline-block child
+     (e.g. the data-viz SparklineChart) otherwise sits on the text baseline with
+     descender space below it, reading as vertically off-center in the slot. */
+  display: flex;
+  align-items: center;
+}
+
+.seeds-metric-highlight:not(.seeds-metric-highlight-vertical) .seeds-metric-highlight-chart {
+  width: 104px;
+  height: 48px;
+}
+
+.seeds-metric-highlight-small:not(.seeds-metric-highlight-vertical) .seeds-metric-highlight-chart {
+  width: 88px;
+  height: 40px;
+}
+
+.seeds-metric-highlight-vertical .seeds-metric-highlight-chart {
+  width: 100%;
+  height: 96px;
+}
+
+.seeds-metric-highlight-vertical.seeds-metric-highlight-small .seeds-metric-highlight-chart {
+  height: 56px;
+}
+
+}

package/src/narrative-container.css

@@ -17,7 +17,7 @@
   box-sizing: border-box;
   display: flex;
   flex-direction: column;
-  align-items: flex-start;
+  align-items: stretch;
   padding: var(--space-500);
   border-radius: var(--radius-800);
   box-shadow: var(--shadow-low);

package/src/narrative-divider.css

@@ -0,0 +1,27 @@
+/**
+ * Seeds NarrativeDivider 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:
+ *   <hr class="seeds-narrative-divider" />
+ */
+
+@layer components {
+
+/* A full-width, 1px horizontal rule. The <hr> ships with user-agent margins
+   and a beveled border, so reset those and draw the line with a single
+   border-top using the container-border-base token (#dee1e1), which also
+   tracks dark mode. */
+.seeds-narrative-divider {
+  box-sizing: border-box;
+  width: 100%;
+  height: 0;
+  margin: 0;
+  border: 0;
+  border-top: 1px solid var(--color-container-border-base); /* #dee1e1 */
+}
+
+}