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

package/src/MetricHighlight/MetricHighlight.tsx

@@ -0,0 +1,116 @@
+import * as React from "react";
+import { cn } from "../_internal/cn";
+import type {
+  TypeMetricHighlightProps,
+  TypeMetricHighlightTrend,
+} from "./MetricHighlightTypes";
+
+/** 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 chart supplied via
+ * the `sparkline` slot (e.g. a `<SparklineChart />` from
+ * `@sproutsocial/seeds-react-data-viz/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,
+      sparkline,
+      appearance = "horizontal",
+      size = "default",
+      container = true,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    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>
+        {sparkline != null && (
+          // Layout-only slot (bounded dimensions per horizontal/vertical/small)
+          // for a consumer-supplied chart. It controls its own look; the slot
+          // only sizes and centers it.
+          <div className="seeds-metric-highlight-chart">{sparkline}</div>
+        )}
+      </div>
+    );
+  }
+);
+
+MetricHighlight.displayName = "MetricHighlight";
+
+export default MetricHighlight;

package/src/MetricHighlight/MetricHighlightTypes.ts

@@ -0,0 +1,58 @@
+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;
+  /**
+   * Chart slot. When provided, this node renders in the chart area beside/below
+   * the metric — e.g. a `<SparklineChart />` from
+   * `@sproutsocial/seeds-react-data-viz/sparkline`. Omit it to render the metric
+   * on its own. The injected node controls its own look; the slot only sizes and
+   * centers it (pass `className="h-full w-full"` to fill).
+   */
+  sparkline?: React.ReactNode;
+  /**
+   * 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,116 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import MetricHighlight from "../MetricHighlight";
+
+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("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 slot node in the chart area", () => {
+    const { container } = render(
+      <MetricHighlight
+        label="Engagement"
+        value="123"
+        sparkline={<div data-testid="custom-spark">chart</div>}
+      />
+    );
+
+    expect(screen.getByTestId("custom-spark")).toBeInTheDocument();
+    expect(
+      container.querySelector(".seeds-metric-highlight-chart")
+    ).toBeInTheDocument();
+  });
+
+  it("omits the chart area when no sparkline slot is provided", () => {
+    const { container } = render(
+      <MetricHighlight label="Engagement" value="123" />
+    );
+
+    expect(
+      container.querySelector(".seeds-metric-highlight-chart")
+    ).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/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.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,45 @@
+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, size = "default", className, ...props },
+    ref
+  ) => {
+    const Heading = `h${headingLevel}` as const;
+
+    return (
+      <Heading
+        ref={ref}
+        className={cn(
+          "seeds-narrative-headline",
+          { "seeds-narrative-headline-small": size === "small" },
+          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;