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

package/src/NarrativeDivider/NarrativeDivider.stories.tsx

@@ -0,0 +1,33 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import NarrativeDivider from "./NarrativeDivider";
+import "../narrative-divider.css";
+
+const meta = {
+  title: "Narrative Kit/NarrativeDivider",
+  component: NarrativeDivider,
+  decorators: [
+    (Story) => (
+      <div style={{ width: 480 }}>
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof NarrativeDivider>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A full-width 1px rule spanning its container. */
+export const Default: Story = {};
+
+/** Sitting between two blocks of content, as it would in a brief. */
+export const BetweenSections: Story = {
+  render: () => (
+    <div style={{ width: 480 }}>
+      <p>Insight metrics</p>
+      <NarrativeDivider />
+      <p>Headline and summary</p>
+    </div>
+  ),
+};

package/src/NarrativeDivider/NarrativeDivider.tsx

@@ -0,0 +1,30 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypeNarrativeDividerProps } from "./NarrativeDividerTypes";
+
+/**
+ * NarrativeDivider — a full-width, 1px horizontal rule that separates sections
+ * within a narrative brief (e.g. a row of metrics from the headline/summary
+ * block below it).
+ *
+ * Renders a semantic <hr> stripped of its user-agent margins and borders, then
+ * draws a single 1px line with the container-border-base token (#dee1e1, which
+ * also tracks dark mode). Styled via narrative-divider.css (Seeds CSS custom
+ * properties); consumers import the classes through
+ * @sproutsocial/racine/css/components. Overrides come via standard className /
+ * style.
+ */
+const NarrativeDivider = React.forwardRef<
+  HTMLHRElement,
+  TypeNarrativeDividerProps
+>(({ className, ...props }, ref) => (
+  <hr
+    ref={ref}
+    className={cn("seeds-narrative-divider", className)}
+    {...props}
+  />
+));
+
+NarrativeDivider.displayName = "NarrativeDivider";
+
+export default NarrativeDivider;

package/src/NarrativeDivider/NarrativeDividerTypes.ts

@@ -0,0 +1,4 @@
+import type * as React from "react";
+
+/** NarrativeDivider takes no extra props — just standard <hr> attributes. */
+export type TypeNarrativeDividerProps = React.HTMLAttributes<HTMLHRElement>;

package/src/NarrativeDivider/__tests__/NarrativeDivider.test.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import NarrativeDivider from "../NarrativeDivider";
+
+describe("NarrativeDivider", () => {
+  it("renders a horizontal rule with the base class", () => {
+    const { container } = render(<NarrativeDivider />);
+
+    const root = container.querySelector(".seeds-narrative-divider");
+    expect(root).toBeInTheDocument();
+    expect(root?.tagName).toBe("HR");
+  });
+
+  it("merges a consumer className with the base class", () => {
+    const { container } = render(<NarrativeDivider className="custom" />);
+
+    const root = container.querySelector(".seeds-narrative-divider");
+    expect(root).toBeInTheDocument();
+    expect(root).toHaveClass("custom");
+  });
+
+  it("forwards extra props to the underlying element", () => {
+    render(<NarrativeDivider data-testid="divider" />);
+
+    expect(screen.getByTestId("divider")).toBeInTheDocument();
+  });
+
+  it("forwards its ref to the underlying hr element", () => {
+    const ref = React.createRef<HTMLHRElement>();
+    render(<NarrativeDivider ref={ref} />);
+
+    expect(ref.current).toBeInstanceOf(HTMLHRElement);
+    expect(ref.current?.tagName).toBe("HR");
+  });
+});

package/src/NarrativeDivider/index.ts

@@ -0,0 +1,2 @@
+export { default as NarrativeDivider } from "./NarrativeDivider";
+export type { TypeNarrativeDividerProps } from "./NarrativeDividerTypes";

package/src/NarrativeHeadline/NarrativeHeadline.tsx

@@ -17,19 +17,28 @@ import type { TypeNarrativeHeadlineProps } from "./NarrativeHeadlineTypes";
 const NarrativeHeadline = React.forwardRef<
   HTMLHeadingElement,
   TypeNarrativeHeadlineProps
->(({ children, headingLevel = 2, className, ...props }, ref) => {
-  const Heading = `h${headingLevel}` as const;
+>(
+  (
+    { children, headingLevel = 2, size = "default", className, ...props },
+    ref
+  ) => {
+    const Heading = `h${headingLevel}` as const;
 
-  return (
-    <Heading
-      ref={ref}
-      className={cn("seeds-narrative-headline", className)}
-      {...props}
-    >
-      {children}
-    </Heading>
-  );
-});
+    return (
+      <Heading
+        ref={ref}
+        className={cn(
+          "seeds-narrative-headline",
+          { "seeds-narrative-headline-small": size === "small" },
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </Heading>
+    );
+  }
+);
 
 NarrativeHeadline.displayName = "NarrativeHeadline";
 

package/src/NarrativeHeadline/NarrativeHeadlineRoll.tsx

@@ -74,7 +74,10 @@ const NarrativeHeadlineRoll = React.forwardRef<
       >
         {/* 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">
+        <span
+          className="seeds-narrative-headline-roll-sizer"
+          aria-hidden="true"
+        >
           {words[i]}
         </span>
         {words.map((w, idx) => (

package/src/NarrativeHeadline/NarrativeHeadlineTypes.ts

@@ -3,6 +3,9 @@ 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> {
   /**
@@ -17,6 +20,12 @@ export interface TypeNarrativeHeadlineProps
    * @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

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

@@ -12,9 +12,7 @@ describe("NarrativeHeadline", () => {
   });
 
   it("renders the headline as an h2 by default and honors headingLevel", () => {
-    const { rerender } = render(
-      <NarrativeHeadline>Title</NarrativeHeadline>
-    );
+    const { rerender } = render(<NarrativeHeadline>Title</NarrativeHeadline>);
     expect(screen.getByRole("heading", { level: 2 })).toHaveTextContent(
       "Title"
     );
@@ -101,10 +99,7 @@ describe("NarrativeHeadlineRoll", () => {
     jest.useFakeTimers();
     try {
       const { container } = render(
-        <NarrativeHeadlineRoll
-          words={["first", "second"]}
-          intervalMs={1000}
-        />
+        <NarrativeHeadlineRoll words={["first", "second"]} intervalMs={1000} />
       );
 
       const wordsBefore = container.querySelectorAll(

package/src/NarrativeHeadline/index.ts

@@ -4,6 +4,7 @@ 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";