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

package/src/MetricHighlight/MetricHighlightTypes.ts

@@ -0,0 +1,61 @@
+import type * as React from "react";
+
+export interface TypeMetricHighlightTrend {
+  /**
+   * Direction of movement. Selects the arrow glyph and the sentiment color of
+   * the badge (green for `up`, red for `down`).
+   * @default "up"
+   */
+  direction?: "up" | "down";
+  /**
+   * Optional value rendered next to the arrow (e.g. `"240%"`, `12`). When
+   * omitted the badge is icon-only.
+   */
+  value?: React.ReactNode;
+  /**
+   * Accessible label describing the trend (e.g. `"up 240%"`). The arrow glyph is
+   * decorative, so provide this whenever the trend conveys meaning on its own.
+   */
+  "aria-label"?: string;
+}
+
+export interface TypeMetricHighlightProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** Short metric label rendered above/beside the value (e.g. `"Insight metric"`). */
+  label: React.ReactNode;
+  /** The metric value, rendered as the emphasized monospace figure (e.g. `"123"`, `"1.2M"`). */
+  value: React.ReactNode;
+  /** Optional trend badge — a directional arrow plus an optional value. */
+  trend?: TypeMetricHighlightTrend;
+  /**
+   * Sparkline data points. When omitted, a sensible default series is used
+   * (sloped to match `trend`). Pass an explicit array to override, or an empty
+   * array to opt out of the chart.
+   */
+  data?: number[];
+  /**
+   * Render the sparkline.
+   * @default true
+   */
+  chart?: boolean;
+  /**
+   * Layout direction.
+   * - `horizontal` — metric block beside the sparkline.
+   * - `vertical` — metric block stacked above a full-width sparkline.
+   * @default "horizontal"
+   */
+  appearance?: "horizontal" | "vertical";
+  /**
+   * Size of the value and overall density.
+   * - `default` — large value, label stacked above it.
+   * - `small` — condensed value, label and value on a single row.
+   * @default "default"
+   */
+  size?: "default" | "small";
+  /**
+   * Render the padded surface background. Set `false` to drop the surface and
+   * compose the metric inside another container.
+   * @default true
+   */
+  container?: boolean;
+}

package/src/MetricHighlight/__tests__/MetricHighlight.test.tsx

@@ -0,0 +1,151 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import MetricHighlight from "../MetricHighlight";
+
+const DATA = [1, 4, 2, 6, 3];
+
+describe("MetricHighlight", () => {
+  it("renders the label and value", () => {
+    render(<MetricHighlight label="Engagement" value="123" />);
+
+    expect(screen.getByText("Engagement")).toBeInTheDocument();
+    expect(screen.getByText("123")).toBeInTheDocument();
+  });
+
+  it("renders the trend value when provided", () => {
+    render(
+      <MetricHighlight
+        label="Engagement"
+        value="123"
+        trend={{ direction: "up", value: "240%" }}
+      />
+    );
+
+    expect(screen.getByText("240%")).toBeInTheDocument();
+  });
+
+  it("renders an icon-only trend badge with no value text", () => {
+    const { container } = render(
+      <MetricHighlight
+        label="Engagement"
+        value="123"
+        trend={{ direction: "up", "aria-label": "trending up" }}
+      />
+    );
+
+    expect(container.querySelector(".seeds-metric-highlight-trend")).toBeInTheDocument();
+    expect(
+      container.querySelector(".seeds-metric-highlight-trend-value")
+    ).not.toBeInTheDocument();
+    expect(screen.getByLabelText("trending up")).toBeInTheDocument();
+  });
+
+  it("applies the down modifier for a downward trend", () => {
+    const { container } = render(
+      <MetricHighlight
+        label="Engagement"
+        value="123"
+        trend={{ direction: "down", value: "12%" }}
+      />
+    );
+
+    expect(
+      container.querySelector(".seeds-metric-highlight-trend-down")
+    ).toBeInTheDocument();
+  });
+
+  it("marks the sparkline negative for a downward trend", () => {
+    const { container, rerender } = render(
+      <MetricHighlight
+        label="Engagement"
+        value="123"
+        data={DATA}
+        trend={{ direction: "down", value: "12%" }}
+      />
+    );
+    expect(
+      container.querySelector(".seeds-metric-highlight-spark-negative")
+    ).toBeInTheDocument();
+
+    rerender(
+      <MetricHighlight
+        label="Engagement"
+        value="123"
+        data={DATA}
+        trend={{ direction: "up", value: "12%" }}
+      />
+    );
+    expect(
+      container.querySelector(".seeds-metric-highlight-spark-negative")
+    ).not.toBeInTheDocument();
+  });
+
+  it("omits the trend badge when no trend is provided", () => {
+    const { container } = render(
+      <MetricHighlight label="Engagement" value="123" />
+    );
+
+    expect(
+      container.querySelector(".seeds-metric-highlight-trend")
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the sparkline when data is provided", () => {
+    const { container } = render(
+      <MetricHighlight label="Engagement" value="123" data={DATA} />
+    );
+
+    expect(
+      container.querySelector(".seeds-metric-highlight-spark")
+    ).toBeInTheDocument();
+  });
+
+  it("renders a default sparkline when no data is provided", () => {
+    const { container } = render(
+      <MetricHighlight label="Engagement" value="123" />
+    );
+
+    expect(
+      container.querySelector(".seeds-metric-highlight-spark")
+    ).toBeInTheDocument();
+  });
+
+  it("omits the sparkline when chart is false or data is empty", () => {
+    const { container, rerender } = render(
+      <MetricHighlight label="Engagement" value="123" data={DATA} chart={false} />
+    );
+    expect(
+      container.querySelector(".seeds-metric-highlight-spark")
+    ).not.toBeInTheDocument();
+
+    rerender(<MetricHighlight label="Engagement" value="123" data={[]} />);
+    expect(
+      container.querySelector(".seeds-metric-highlight-spark")
+    ).not.toBeInTheDocument();
+  });
+
+  it("applies the vertical, small, and bare modifiers per props", () => {
+    const { container } = render(
+      <MetricHighlight
+        label="Engagement"
+        value="123"
+        appearance="vertical"
+        size="small"
+        container={false}
+      />
+    );
+
+    const root = container.querySelector(".seeds-metric-highlight");
+    expect(root).toHaveClass("seeds-metric-highlight-vertical");
+    expect(root).toHaveClass("seeds-metric-highlight-small");
+    expect(root).toHaveClass("seeds-metric-highlight-bare");
+  });
+
+  it("forwards its ref to the underlying div element", () => {
+    const ref = React.createRef<HTMLDivElement>();
+    render(<MetricHighlight ref={ref} label="Engagement" value="123" />);
+
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current?.tagName).toBe("DIV");
+  });
+});

package/src/MetricHighlight/index.ts

@@ -0,0 +1,5 @@
+export { default as MetricHighlight } from "./MetricHighlight";
+export type {
+  TypeMetricHighlightProps,
+  TypeMetricHighlightTrend,
+} from "./MetricHighlightTypes";

package/src/NarrativeContainer/NarrativeContainer.stories.tsx

@@ -12,7 +12,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 const SlotContent = () => (
-  <div style={{ display: "grid", gap: 8 }}>
+  <div className="grid gap-300">
     <strong>Engagement is up 24% this month</strong>
     <span>
       Driven by a strong week on LinkedIn and a viral reply thread. Audience
@@ -23,14 +23,14 @@ const SlotContent = () => (
 
 export const Default: Story = {
   args: {
-    style: { width: 384 },
+    className: "w-96",
     children: <SlotContent />,
   },
 };
 
 export const WithoutAccent: Story = {
   args: {
-    style: { width: 384 },
+    className: "w-96",
     accent: false,
     children: <SlotContent />,
   },

package/src/NarrativeContainer/NarrativeContainer.tsx

@@ -1,29 +1,7 @@
 import * as React from "react";
+import { cn } from "../_internal/cn";
 import type { TypeNarrativeContainerProps } from "./NarrativeContainerTypes";
 
-/** Merge class names, supporting `{ "class": boolean }` toggles. */
-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(" ");
-}
-
 /**
  * NarrativeContainer — the foundational surface that narrative primitives are
  * composed inside. A padded, rounded, elevated card with a content slot and an

package/src/NarrativeHeadline/NarrativeHeadline.stories.tsx

@@ -0,0 +1,68 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import NarrativeHeadline from "./NarrativeHeadline";
+import NarrativeHeadlineHighlight from "./NarrativeHeadlineHighlight";
+import NarrativeHeadlineRoll from "./NarrativeHeadlineRoll";
+import "../narrative-headline.css";
+
+const meta = {
+  title: "Narrative Kit/NarrativeHeadline",
+  component: NarrativeHeadline,
+} satisfies Meta<typeof NarrativeHeadline>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    className: "w-150",
+    children: "Engagement is up 24% this month",
+  },
+};
+
+export const Highlight: Story = {
+  name: "With highlight",
+  args: {
+    className: "w-150",
+    children: (
+      <>
+        Headline with a{" "}
+        <NarrativeHeadlineHighlight>highlighted</NarrativeHeadlineHighlight>{" "}
+        word
+      </>
+    ),
+  },
+};
+
+export const Roll: Story = {
+  name: "Roll variant",
+  args: {
+    className: "w-150",
+    children: (
+      <>
+        The social suite for{" "}
+        <NarrativeHeadlineRoll
+          words={["marketers", "agencies", "enterprise teams", "founders"]}
+        />
+      </>
+    ),
+  },
+};
+
+export const RollDownNoGradient: Story = {
+  name: "Roll variant — downward, no gradient",
+  args: {
+    className: "w-150",
+    children: (
+      <>
+        Now tracking{" "}
+        <NarrativeHeadlineRoll
+          words={["mentions", "reach", "sentiment"]}
+          direction="down"
+          gradient={false}
+          intervalMs={1600}
+        />
+      </>
+    ),
+  },
+};

package/src/NarrativeHeadline/NarrativeHeadline.tsx

@@ -0,0 +1,36 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypeNarrativeHeadlineProps } from "./NarrativeHeadlineTypes";
+
+/**
+ * NarrativeHeadline — the titling primitive for a narrative block. A single
+ * heading element, nothing more: supporting copy and tags/tokens belong to
+ * sibling primitives that compose alongside it, not baked into the title.
+ *
+ * Wrap part of the headline in `<NarrativeHeadlineHighlight>` for a static
+ * gradient accent, or `<NarrativeHeadlineRoll>` for the rolling "roll" variant.
+ *
+ * Styled via `narrative-headline.css` (Seeds CSS custom properties). Consumers
+ * import the classes through `@sproutsocial/racine/css/components`. Overrides
+ * are done with standard `className` / `style`.
+ */
+const NarrativeHeadline = React.forwardRef<
+  HTMLHeadingElement,
+  TypeNarrativeHeadlineProps
+>(({ children, headingLevel = 2, className, ...props }, ref) => {
+  const Heading = `h${headingLevel}` as const;
+
+  return (
+    <Heading
+      ref={ref}
+      className={cn("seeds-narrative-headline", className)}
+      {...props}
+    >
+      {children}
+    </Heading>
+  );
+});
+
+NarrativeHeadline.displayName = "NarrativeHeadline";
+
+export default NarrativeHeadline;

package/src/NarrativeHeadline/NarrativeHeadlineHighlight.tsx

@@ -0,0 +1,31 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type { TypeNarrativeHeadlineHighlightProps } from "./NarrativeHeadlineTypes";
+
+/**
+ * NarrativeHeadlineHighlight — paints a span of headline text with the AI
+ * brand gradient (the "highlighted word" treatment). Drop it inline inside a
+ * `<NarrativeHeadline>`:
+ *
+ *     <NarrativeHeadline>
+ *       Headline with a <NarrativeHeadlineHighlight>highlighted</NarrativeHeadlineHighlight> word
+ *     </NarrativeHeadline>
+ */
+const NarrativeHeadlineHighlight = React.forwardRef<
+  HTMLSpanElement,
+  TypeNarrativeHeadlineHighlightProps
+>(({ children, className, ...props }, ref) => {
+  return (
+    <span
+      ref={ref}
+      className={cn("seeds-narrative-headline-highlight", className)}
+      {...props}
+    >
+      {children}
+    </span>
+  );
+});
+
+NarrativeHeadlineHighlight.displayName = "NarrativeHeadlineHighlight";
+
+export default NarrativeHeadlineHighlight;

package/src/NarrativeHeadline/NarrativeHeadlineRoll.tsx

@@ -0,0 +1,100 @@
+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,54 @@
+import type * as React from "react";
+
+/** Heading level the headline text renders as. */
+export type TypeNarrativeHeadlineLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+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;
+}
+
+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;
+}