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

package/dist/index.d.mts

@@ -21,6 +21,210 @@ interface TypeNarrativeContainerProps extends React.HTMLAttributes<HTMLDivElemen
  */
 declare const NarrativeContainer: React.ForwardRefExoticComponent<TypeNarrativeContainerProps & React.RefAttributes<HTMLDivElement>>;
 
+/** Heading level the headline text renders as. */
+type TypeNarrativeHeadlineLevel = 1 | 2 | 3 | 4 | 5 | 6;
+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;
+}
+interface TypeNarrativeHeadlineHighlightProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Text painted with the AI gradient. */
+    children?: React.ReactNode;
+}
+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;
+}
+
+/**
+ * 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`.
+ */
+declare const NarrativeHeadline: React.ForwardRefExoticComponent<TypeNarrativeHeadlineProps & React.RefAttributes<HTMLHeadingElement>>;
+
+/**
+ * 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>
+ */
+declare const NarrativeHeadlineHighlight: React.ForwardRefExoticComponent<TypeNarrativeHeadlineHighlightProps & React.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * 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.
+ */
+declare const NarrativeHeadlineRoll: React.ForwardRefExoticComponent<TypeNarrativeHeadlineRollProps & React.RefAttributes<HTMLSpanElement>>;
+
+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";
+}
+
+/**
+ * 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`.
+ */
+declare const PullQuote: React.ForwardRefExoticComponent<TypePullQuoteProps & React.RefAttributes<HTMLElement>>;
+
+interface TypeEyebrowTokenProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** The eyebrow text — a date, category, or short kicker. */
+    children: React.ReactNode;
+}
+
+/**
+ * EyebrowToken — a small gray pill that sits above a headline to carry a short
+ * bit of context: a date (e.g. "May 31, 2026"), category, or kicker.
+ *
+ * A faithful match of the Figma "Token / Non Clickable / Default" design — a
+ * solid `#dee1e1` fill with a matching border, 6px radius, and small body text.
+ * Styled via `eyebrow-token.css` (Seeds CSS custom properties); consumers import
+ * the classes through `@sproutsocial/racine/css/components`. Overrides come via
+ * standard `className` / `style`.
+ */
+declare const EyebrowToken: React.ForwardRefExoticComponent<TypeEyebrowTokenProps & React.RefAttributes<HTMLSpanElement>>;
+
+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;
+}
+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;
+}
+
+/**
+ * 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 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`.
+ */
+declare const MetricHighlight: React.ForwardRefExoticComponent<TypeMetricHighlightProps & React.RefAttributes<HTMLDivElement>>;
+
 /**
  * Shared types for narrative primitives.
  *
@@ -33,4 +237,4 @@ declare const NarrativeContainer: React.ForwardRefExoticComponent<TypeNarrativeC
  */
 type TypeNarrativeTone = "neutral" | "positive" | "negative" | "opportunity";
 
-export { NarrativeContainer, type TypeNarrativeContainerProps, type TypeNarrativeTone };
+export { EyebrowToken, MetricHighlight, NarrativeContainer, NarrativeHeadline, NarrativeHeadlineHighlight, NarrativeHeadlineRoll, PullQuote, type TypeEyebrowTokenProps, type TypeMetricHighlightProps, type TypeMetricHighlightTrend, type TypeNarrativeContainerProps, type TypeNarrativeHeadlineHighlightProps, type TypeNarrativeHeadlineLevel, type TypeNarrativeHeadlineProps, type TypeNarrativeHeadlineRollProps, type TypeNarrativeTone, type TypePullQuoteProps };

package/dist/index.d.ts

@@ -21,6 +21,210 @@ interface TypeNarrativeContainerProps extends React.HTMLAttributes<HTMLDivElemen
  */
 declare const NarrativeContainer: React.ForwardRefExoticComponent<TypeNarrativeContainerProps & React.RefAttributes<HTMLDivElement>>;
 
+/** Heading level the headline text renders as. */
+type TypeNarrativeHeadlineLevel = 1 | 2 | 3 | 4 | 5 | 6;
+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;
+}
+interface TypeNarrativeHeadlineHighlightProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Text painted with the AI gradient. */
+    children?: React.ReactNode;
+}
+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;
+}
+
+/**
+ * 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`.
+ */
+declare const NarrativeHeadline: React.ForwardRefExoticComponent<TypeNarrativeHeadlineProps & React.RefAttributes<HTMLHeadingElement>>;
+
+/**
+ * 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>
+ */
+declare const NarrativeHeadlineHighlight: React.ForwardRefExoticComponent<TypeNarrativeHeadlineHighlightProps & React.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * 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.
+ */
+declare const NarrativeHeadlineRoll: React.ForwardRefExoticComponent<TypeNarrativeHeadlineRollProps & React.RefAttributes<HTMLSpanElement>>;
+
+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";
+}
+
+/**
+ * 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`.
+ */
+declare const PullQuote: React.ForwardRefExoticComponent<TypePullQuoteProps & React.RefAttributes<HTMLElement>>;
+
+interface TypeEyebrowTokenProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** The eyebrow text — a date, category, or short kicker. */
+    children: React.ReactNode;
+}
+
+/**
+ * EyebrowToken — a small gray pill that sits above a headline to carry a short
+ * bit of context: a date (e.g. "May 31, 2026"), category, or kicker.
+ *
+ * A faithful match of the Figma "Token / Non Clickable / Default" design — a
+ * solid `#dee1e1` fill with a matching border, 6px radius, and small body text.
+ * Styled via `eyebrow-token.css` (Seeds CSS custom properties); consumers import
+ * the classes through `@sproutsocial/racine/css/components`. Overrides come via
+ * standard `className` / `style`.
+ */
+declare const EyebrowToken: React.ForwardRefExoticComponent<TypeEyebrowTokenProps & React.RefAttributes<HTMLSpanElement>>;
+
+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;
+}
+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;
+}
+
+/**
+ * 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 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`.
+ */
+declare const MetricHighlight: React.ForwardRefExoticComponent<TypeMetricHighlightProps & React.RefAttributes<HTMLDivElement>>;
+
 /**
  * Shared types for narrative primitives.
  *
@@ -33,4 +237,4 @@ declare const NarrativeContainer: React.ForwardRefExoticComponent<TypeNarrativeC
  */
 type TypeNarrativeTone = "neutral" | "positive" | "negative" | "opportunity";
 
-export { NarrativeContainer, type TypeNarrativeContainerProps, type TypeNarrativeTone };
+export { EyebrowToken, MetricHighlight, NarrativeContainer, NarrativeHeadline, NarrativeHeadlineHighlight, NarrativeHeadlineRoll, PullQuote, type TypeEyebrowTokenProps, type TypeMetricHighlightProps, type TypeMetricHighlightTrend, type TypeNarrativeContainerProps, type TypeNarrativeHeadlineHighlightProps, type TypeNarrativeHeadlineLevel, type TypeNarrativeHeadlineProps, type TypeNarrativeHeadlineRollProps, type TypeNarrativeTone, type TypePullQuoteProps };