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

package/src/NarrativeHeadline/NarrativeHeadlineRoll.tsx

@@ -0,0 +1,103 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypeNarrativeHeadlineRollProps } from "./NarrativeHeadlineTypes";
+
+/**
+ * NarrativeHeadlineRoll — the "roll" variant: a vertical word roll for the
+ * highlighted slot of a headline. The active word slides into view while the
+ * previous one rolls out (no typing). Inspired by the performative-ui WordRoll.
+ *
+ *     <NarrativeHeadline>
+ *       Built for{" "}
+ *       <NarrativeHeadlineRoll words={["marketers", "agencies", "teams"]} />
+ *     </NarrativeHeadline>
+ *
+ * The container width follows the active word so it sits naturally inline.
+ * Gradient-painted by default; honors `prefers-reduced-motion` by holding the
+ * first word static.
+ */
+const NarrativeHeadlineRoll = React.forwardRef<
+  HTMLSpanElement,
+  TypeNarrativeHeadlineRollProps
+>(
+  (
+    {
+      words,
+      intervalMs = 2200,
+      transitionMs = 500,
+      direction = "up",
+      gradient = true,
+      className,
+      style,
+      ...rest
+    },
+    ref
+  ) => {
+    const [i, setI] = React.useState(0);
+
+    React.useEffect(() => {
+      if (words.length <= 1) return;
+
+      // Respect reduced-motion: hold the first word, skip the cycle entirely.
+      const reduced =
+        typeof window !== "undefined" &&
+        typeof window.matchMedia === "function" &&
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+      if (reduced) return;
+
+      const t = setInterval(
+        () => setI((j) => (j + 1) % words.length),
+        intervalMs
+      );
+      return () => clearInterval(t);
+    }, [intervalMs, words.length]);
+
+    const merged: React.CSSProperties = {
+      ...style,
+      // Consumed by the transition timing in narrative-headline.css.
+      ["--seeds-narrative-headline-roll-ms" as string]: `${transitionMs}ms`,
+    };
+
+    const prev = words.length ? (i - 1 + words.length) % words.length : 0;
+
+    return (
+      <span
+        ref={ref}
+        className={cn(
+          "seeds-narrative-headline-roll",
+          { "seeds-narrative-headline-roll-down": direction === "down" },
+          { "seeds-narrative-headline-roll-gradient": gradient },
+          className
+        )}
+        style={merged}
+        {...rest}
+      >
+        {/* Sizer keeps the container width matched to the active word — without
+            it the absolutely-positioned words would collapse the box. */}
+        <span
+          className="seeds-narrative-headline-roll-sizer"
+          aria-hidden="true"
+        >
+          {words[i]}
+        </span>
+        {words.map((w, idx) => (
+          <span
+            key={idx}
+            className={cn("seeds-narrative-headline-roll-word", {
+              "seeds-narrative-headline-roll-word-active": idx === i,
+              "seeds-narrative-headline-roll-word-past":
+                idx === prev && i !== prev,
+            })}
+            aria-hidden={idx === i ? undefined : "true"}
+          >
+            {w}
+          </span>
+        ))}
+      </span>
+    );
+  }
+);
+
+NarrativeHeadlineRoll.displayName = "NarrativeHeadlineRoll";
+
+export default NarrativeHeadlineRoll;

package/src/NarrativeHeadline/NarrativeHeadlineTypes.ts

@@ -0,0 +1,63 @@
+import type * as React from "react";
+
+/** Heading level the headline text renders as. */
+export type TypeNarrativeHeadlineLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+/** Visual size of the headline. Independent of the semantic heading level. */
+export type TypeNarrativeHeadlineSize = "default" | "small";
+
+export interface TypeNarrativeHeadlineProps
+  extends React.HTMLAttributes<HTMLHeadingElement> {
+  /**
+   * The headline text. Wrap part of it in `<NarrativeHeadlineHighlight>` for a
+   * static gradient accent, or `<NarrativeHeadlineRoll>` for the rolling "roll"
+   * variant.
+   */
+  children?: React.ReactNode;
+  /**
+   * Heading element the headline text renders as, for document outline /
+   * accessibility. Visual size is unaffected.
+   * @default 2
+   */
+  headingLevel?: TypeNarrativeHeadlineLevel;
+  /**
+   * Visual size. `"default"` is the display size (32px / 40px); `"small"` is the
+   * compact size (24px / 32px) used inside denser layouts like NarrativeSummary.
+   * @default "default"
+   */
+  size?: TypeNarrativeHeadlineSize;
+}
+
+export interface TypeNarrativeHeadlineHighlightProps
+  extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Text painted with the AI gradient. */
+  children?: React.ReactNode;
+}
+
+export interface TypeNarrativeHeadlineRollProps
+  extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Words to cycle through. The first word is shown initially. */
+  words: string[];
+  /**
+   * Milliseconds each word holds before rolling out.
+   * @default 2200
+   */
+  intervalMs?: number;
+  /**
+   * Milliseconds of the slide animation.
+   * @default 500
+   */
+  transitionMs?: number;
+  /**
+   * Direction the active word rolls in from.
+   * @default "up"
+   */
+  direction?: "up" | "down";
+  /**
+   * Paint each word with the AI gradient. Apply it here rather than nesting
+   * inside `<NarrativeHeadlineHighlight>` — `background-clip: text` does not
+   * apply across the absolutely-positioned rolling words.
+   * @default true
+   */
+  gradient?: boolean;
+}

package/src/NarrativeHeadline/__tests__/NarrativeHeadline.test.tsx

@@ -0,0 +1,133 @@
+import React from "react";
+import { act, render, screen } from "@sproutsocial/seeds-react-testing-library";
+import NarrativeHeadline from "../NarrativeHeadline";
+import NarrativeHeadlineHighlight from "../NarrativeHeadlineHighlight";
+import NarrativeHeadlineRoll from "../NarrativeHeadlineRoll";
+
+describe("NarrativeHeadline", () => {
+  it("renders its headline content", () => {
+    render(<NarrativeHeadline>Engagement is up</NarrativeHeadline>);
+
+    expect(screen.getByText("Engagement is up")).toBeInTheDocument();
+  });
+
+  it("renders the headline as an h2 by default and honors headingLevel", () => {
+    const { rerender } = render(<NarrativeHeadline>Title</NarrativeHeadline>);
+    expect(screen.getByRole("heading", { level: 2 })).toHaveTextContent(
+      "Title"
+    );
+
+    rerender(<NarrativeHeadline headingLevel={1}>Title</NarrativeHeadline>);
+    expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent(
+      "Title"
+    );
+  });
+
+  it("forwards its ref to the underlying heading element", () => {
+    const ref = React.createRef<HTMLHeadingElement>();
+    render(<NarrativeHeadline ref={ref}>Content</NarrativeHeadline>);
+
+    expect(ref.current).toBeInstanceOf(HTMLHeadingElement);
+  });
+});
+
+describe("NarrativeHeadlineHighlight", () => {
+  it("paints its children with the gradient accent class", () => {
+    const { container } = render(
+      <NarrativeHeadlineHighlight>boosted</NarrativeHeadlineHighlight>
+    );
+
+    expect(screen.getByText("boosted")).toBeInTheDocument();
+    expect(
+      container.querySelector(".seeds-narrative-headline-highlight")
+    ).toBeInTheDocument();
+  });
+});
+
+describe("NarrativeHeadlineRoll", () => {
+  it("renders every word and marks the first one active", () => {
+    const { container } = render(
+      <NarrativeHeadlineRoll words={["marketers", "agencies", "teams"]} />
+    );
+
+    const words = container.querySelectorAll(
+      ".seeds-narrative-headline-roll-word"
+    );
+    expect(words).toHaveLength(3);
+    expect(words[0]).toHaveClass("seeds-narrative-headline-roll-word-active");
+    expect(words[1]).not.toHaveClass(
+      "seeds-narrative-headline-roll-word-active"
+    );
+  });
+
+  it("renders a sizer matched to the active word", () => {
+    const { container } = render(
+      <NarrativeHeadlineRoll words={["alpha", "beta"]} />
+    );
+
+    const sizer = container.querySelector(
+      ".seeds-narrative-headline-roll-sizer"
+    );
+    expect(sizer).toHaveTextContent("alpha");
+    expect(sizer).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("applies the gradient modifier by default and omits it when disabled", () => {
+    const { container, rerender } = render(
+      <NarrativeHeadlineRoll words={["a", "b"]} />
+    );
+    expect(
+      container.querySelector(".seeds-narrative-headline-roll-gradient")
+    ).toBeInTheDocument();
+
+    rerender(<NarrativeHeadlineRoll words={["a", "b"]} gradient={false} />);
+    expect(
+      container.querySelector(".seeds-narrative-headline-roll-gradient")
+    ).not.toBeInTheDocument();
+  });
+
+  it("applies the direction modifier when rolling down", () => {
+    const { container } = render(
+      <NarrativeHeadlineRoll words={["a", "b"]} direction="down" />
+    );
+    expect(
+      container.querySelector(".seeds-narrative-headline-roll-down")
+    ).toBeInTheDocument();
+  });
+
+  it("advances to the next word after the interval elapses", () => {
+    jest.useFakeTimers();
+    try {
+      const { container } = render(
+        <NarrativeHeadlineRoll words={["first", "second"]} intervalMs={1000} />
+      );
+
+      const wordsBefore = container.querySelectorAll(
+        ".seeds-narrative-headline-roll-word"
+      );
+      expect(wordsBefore[0]).toHaveClass(
+        "seeds-narrative-headline-roll-word-active"
+      );
+
+      act(() => {
+        jest.advanceTimersByTime(1000);
+      });
+
+      const wordsAfter = container.querySelectorAll(
+        ".seeds-narrative-headline-roll-word"
+      );
+      expect(wordsAfter[1]).toHaveClass(
+        "seeds-narrative-headline-roll-word-active"
+      );
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it("forwards its ref to the underlying element", () => {
+    const ref = React.createRef<HTMLSpanElement>();
+    render(<NarrativeHeadlineRoll ref={ref} words={["x"]} />);
+
+    expect(ref.current).toBeInstanceOf(HTMLSpanElement);
+  });
+});

package/src/NarrativeHeadline/index.ts

@@ -0,0 +1,10 @@
+export { default as NarrativeHeadline } from "./NarrativeHeadline";
+export { default as NarrativeHeadlineHighlight } from "./NarrativeHeadlineHighlight";
+export { default as NarrativeHeadlineRoll } from "./NarrativeHeadlineRoll";
+export type {
+  TypeNarrativeHeadlineProps,
+  TypeNarrativeHeadlineLevel,
+  TypeNarrativeHeadlineSize,
+  TypeNarrativeHeadlineHighlightProps,
+  TypeNarrativeHeadlineRollProps,
+} from "./NarrativeHeadlineTypes";

package/src/NarrativeSummary/NarrativeSummary.stories.tsx

@@ -0,0 +1,79 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import Button from "@sproutsocial/seeds-react-button";
+import NarrativeSummary from "./NarrativeSummary";
+import "../narrative-summary.css";
+import "../narrative-headline.css";
+import "../eyebrow-token.css";
+import "@sproutsocial/seeds-react-button/dist/button.css";
+
+/**
+ * NarrativeSummary pairs a lead column (eyebrow + headline + optional action)
+ * with a Summary section and a Key themes list. It renders inner content only,
+ * meant to be dropped into a `NarrativeContainer` in production (see the
+ * Playground story for that composition).
+ *
+ * The layout is a container-query-driven CSS grid, so it responds to the width
+ * it is given rather than the viewport.
+ */
+const meta = {
+  title: "Narrative Kit/NarrativeSummary",
+  component: NarrativeSummary,
+  args: {
+    eyebrow: "June 10th",
+    headline: "Headline goes here and wraps to second line",
+    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. Praesent pretium libero vitae arcu blandit pellentesque. Aenean fermentum, nisi eu blandit placerat, ligula ligula euismod ante, id semper nibh diam ac ipsum.",
+    keyThemes: [
+      "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. Praesent pretium libero vitae arcu blandit pellentesque.",
+    ],
+    // No system props → the Button renders its Tailwind path.
+    action: <Button appearance="primary">Action</Button>,
+  },
+  // Constrain the width so the grid has a realistic amount of room to lay out.
+  decorators: [
+    (Story) => (
+      <div className="max-w-256">
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof NarrativeSummary>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Lead | Summary | Key themes — three side-by-side columns. */
+export const ThreeColumn: Story = {};
+
+/** A 1/3 | 2/3 split: the lead column beside a stacked Summary + Key themes. */
+export const TwoColumn: Story = {
+  args: {
+    layout: "two-column",
+  },
+};
+
+/** The action is optional — omit it and the lead column drops the button. */
+export const WithoutAction: Story = {
+  args: {
+    action: undefined,
+  },
+};
+
+/**
+ * Responsiveness is container-driven. In this narrow container the grid
+ * collapses to a single stacked column; widen the container (or view the
+ * ThreeColumn story) to see it expand. Resize the canvas to watch it reflow.
+ */
+export const Responsive: Story = {
+  decorators: [
+    (Story) => (
+      <div className="max-w-96">
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/NarrativeSummary/NarrativeSummary.tsx

@@ -0,0 +1,98 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import EyebrowToken from "../EyebrowToken/EyebrowToken";
+import NarrativeHeadline from "../NarrativeHeadline/NarrativeHeadline";
+import type { TypeNarrativeSummaryProps } from "./NarrativeSummaryTypes";
+
+/**
+ * NarrativeSummary — a composed narrative block that pairs a lead column
+ * (eyebrow + headline + optional action) with a Summary section and a Key
+ * themes list.
+ *
+ * Renders inner content only — it carries no surface, shadow, or accent of its
+ * own. Drop it into a `NarrativeContainer` (see the stories / playground).
+ *
+ * Layout is CSS Grid driven by container queries, so the columns collapse based
+ * on the width the component is actually given, not the viewport:
+ * - `"three-column"` → lead | Summary | Key themes.
+ * - `"two-column"` → a 1/3 | 2/3 split with Summary and Key themes stacked in
+ *   the wider column.
+ *
+ * Styled via `narrative-summary.css` (Seeds CSS custom properties); consumers
+ * import the classes through `@sproutsocial/racine/css/components`. Overrides
+ * come via standard `className` / `style`.
+ */
+const NarrativeSummary = React.forwardRef<
+  HTMLDivElement,
+  TypeNarrativeSummaryProps
+>(
+  (
+    {
+      eyebrow,
+      headline,
+      headingLevel = 2,
+      action,
+      summary,
+      summaryLabel = "Summary",
+      keyThemes,
+      keyThemesLabel = "Key themes",
+      layout = "three-column",
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    const hasKeyThemes = keyThemes != null && keyThemes.length > 0;
+
+    return (
+      <div
+        ref={ref}
+        className={cn("seeds-narrative-summary", className)}
+        {...props}
+      >
+        <div
+          className={cn("seeds-narrative-summary-grid", {
+            "seeds-narrative-summary-two-column": layout === "two-column",
+          })}
+        >
+          <div className="seeds-narrative-summary-lead">
+            {eyebrow != null && <EyebrowToken>{eyebrow}</EyebrowToken>}
+            <div className="seeds-narrative-summary-headline">
+              <NarrativeHeadline size="small" headingLevel={headingLevel}>
+                {headline}
+              </NarrativeHeadline>
+            </div>
+            {action != null && (
+              <div className="seeds-narrative-summary-action">{action}</div>
+            )}
+          </div>
+
+          <div className="seeds-narrative-summary-content">
+            {summary != null && (
+              <section className="seeds-narrative-summary-section">
+                <p className="seeds-narrative-summary-label">{summaryLabel}</p>
+                <p className="seeds-narrative-summary-text">{summary}</p>
+              </section>
+            )}
+            {hasKeyThemes && (
+              <section className="seeds-narrative-summary-section">
+                <p className="seeds-narrative-summary-label">
+                  {keyThemesLabel}
+                </p>
+                <ul className="seeds-narrative-summary-list">
+                  {keyThemes.map((theme, i) => (
+                    <li key={i}>{theme}</li>
+                  ))}
+                </ul>
+              </section>
+            )}
+          </div>
+        </div>
+      </div>
+    );
+  }
+);
+
+NarrativeSummary.displayName = "NarrativeSummary";
+
+export default NarrativeSummary;

package/src/NarrativeSummary/NarrativeSummaryTypes.ts

@@ -0,0 +1,59 @@
+import type * as React from "react";
+import type { TypeNarrativeHeadlineLevel } from "../NarrativeHeadline/NarrativeHeadlineTypes";
+
+/**
+ * Column arrangement.
+ * - `"three-column"`: lead | Summary | Key themes, three side-by-side columns.
+ * - `"two-column"`: a 1/3 | 2/3 split — lead on the left, with Summary and Key
+ *   themes stacked together in the wider right column.
+ */
+export type TypeNarrativeSummaryLayout = "three-column" | "two-column";
+
+export interface TypeNarrativeSummaryProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Kicker shown in an `EyebrowToken` above the headline (e.g. a date). Omit to
+   * hide the eyebrow entirely.
+   */
+  eyebrow?: React.ReactNode;
+  /** Headline text — rendered via `NarrativeHeadline` at `size="small"`. */
+  headline: React.ReactNode;
+  /**
+   * Heading element the headline renders as, for document outline /
+   * accessibility.
+   * @default 2
+   */
+  headingLevel?: TypeNarrativeHeadlineLevel;
+  /**
+   * Optional action, typically a `<Button>`. Rendered below the headline only
+   * when provided. Pass a Button without system props so it renders the Tailwind
+   * path (e.g. `<Button appearance="primary">Action</Button>`).
+   *
+   * Note: in the MVP this will most often be left unset (null) — the AC is
+   * poorly defined at this time and needs more definition before the data model
+   * will properly support it.
+   */
+  action?: React.ReactNode;
+  /** Summary body content. The section is omitted when this is empty. */
+  summary?: React.ReactNode;
+  /**
+   * Label above the summary.
+   * @default "Summary"
+   */
+  summaryLabel?: React.ReactNode;
+  /**
+   * Key themes, rendered as a bulleted list. The section is omitted when this
+   * is empty.
+   */
+  keyThemes?: string[];
+  /**
+   * Label above the key themes.
+   * @default "Key themes"
+   */
+  keyThemesLabel?: React.ReactNode;
+  /**
+   * Column arrangement. `"two-column"` is a 1/3 | 2/3 split.
+   * @default "three-column"
+   */
+  layout?: TypeNarrativeSummaryLayout;
+}

package/src/NarrativeSummary/__tests__/NarrativeSummary.test.tsx

@@ -0,0 +1,99 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import NarrativeSummary from "../NarrativeSummary";
+
+const baseProps = {
+  headline: "Headline goes here",
+  summary: "A short summary.",
+  keyThemes: ["Theme one", "Theme two"],
+};
+
+describe("NarrativeSummary", () => {
+  it("renders the headline, eyebrow, summary, and key themes", () => {
+    render(<NarrativeSummary {...baseProps} eyebrow="June 10th" />);
+
+    expect(screen.getByText("June 10th")).toBeInTheDocument();
+    expect(
+      screen.getByRole("heading", { name: "Headline goes here" })
+    ).toBeInTheDocument();
+    expect(screen.getByText("A short summary.")).toBeInTheDocument();
+    expect(screen.getByText("Theme one")).toBeInTheDocument();
+    expect(screen.getByText("Theme two")).toBeInTheDocument();
+  });
+
+  it("renders the headline at the small size", () => {
+    const { container } = render(<NarrativeSummary {...baseProps} />);
+
+    expect(
+      container.querySelector(".seeds-narrative-headline-small")
+    ).toBeInTheDocument();
+  });
+
+  it("uses the default section labels and allows overrides", () => {
+    const { rerender } = render(<NarrativeSummary {...baseProps} />);
+    expect(screen.getByText("Summary")).toBeInTheDocument();
+    expect(screen.getByText("Key themes")).toBeInTheDocument();
+
+    rerender(
+      <NarrativeSummary
+        {...baseProps}
+        summaryLabel="Overview"
+        keyThemesLabel="Highlights"
+      />
+    );
+    expect(screen.getByText("Overview")).toBeInTheDocument();
+    expect(screen.getByText("Highlights")).toBeInTheDocument();
+  });
+
+  it("renders the key themes as list items", () => {
+    render(<NarrativeSummary {...baseProps} />);
+
+    expect(screen.getAllByRole("listitem")).toHaveLength(2);
+  });
+
+  it("renders the action only when provided", () => {
+    const { rerender } = render(<NarrativeSummary {...baseProps} />);
+    expect(
+      screen.queryByRole("button", { name: "Action" })
+    ).not.toBeInTheDocument();
+
+    rerender(
+      <NarrativeSummary {...baseProps} action={<button>Action</button>} />
+    );
+    expect(screen.getByRole("button", { name: "Action" })).toBeInTheDocument();
+  });
+
+  it("omits a section when its content is empty", () => {
+    render(<NarrativeSummary headline="Only summary" summary="Just this." />);
+
+    expect(screen.getByText("Summary")).toBeInTheDocument();
+    expect(screen.queryByText("Key themes")).not.toBeInTheDocument();
+  });
+
+  it("applies the two-column modifier class", () => {
+    const { container } = render(
+      <NarrativeSummary {...baseProps} layout="two-column" />
+    );
+
+    expect(
+      container.querySelector(".seeds-narrative-summary-two-column")
+    ).toBeInTheDocument();
+  });
+
+  it("merges a consumer className with the base class", () => {
+    const { container } = render(
+      <NarrativeSummary {...baseProps} className="custom" />
+    );
+
+    const root = container.querySelector(".seeds-narrative-summary");
+    expect(root).toBeInTheDocument();
+    expect(root).toHaveClass("custom");
+  });
+
+  it("forwards its ref to the underlying div element", () => {
+    const ref = React.createRef<HTMLDivElement>();
+    render(<NarrativeSummary {...baseProps} ref={ref} />);
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+});

package/src/NarrativeSummary/index.ts

@@ -0,0 +1,5 @@
+export { default as NarrativeSummary } from "./NarrativeSummary";
+export type {
+  TypeNarrativeSummaryProps,
+  TypeNarrativeSummaryLayout,
+} from "./NarrativeSummaryTypes";