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

package/dist/index.d.ts

@@ -23,6 +23,8 @@ declare const NarrativeContainer: React.ForwardRefExoticComponent<TypeNarrativeC
 
 /** Heading level the headline text renders as. */
 type TypeNarrativeHeadlineLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** Visual size of the headline. Independent of the semantic heading level. */
+type TypeNarrativeHeadlineSize = "default" | "small";
 interface TypeNarrativeHeadlineProps extends React.HTMLAttributes<HTMLHeadingElement> {
     /**
      * The headline text. Wrap part of it in `<NarrativeHeadlineHighlight>` for a
@@ -36,6 +38,12 @@ interface TypeNarrativeHeadlineProps extends React.HTMLAttributes<HTMLHeadingEle
      * @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;
 }
 interface TypeNarrativeHeadlineHighlightProps extends React.HTMLAttributes<HTMLSpanElement> {
     /** Text painted with the AI gradient. */
@@ -132,9 +140,10 @@ interface TypePullQuoteProps extends React.HTMLAttributes<HTMLElement> {
  * 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`.
+ * Styled via `pull-quote.css` and `ai-container.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>>;
 
@@ -155,6 +164,23 @@ interface TypeEyebrowTokenProps extends React.HTMLAttributes<HTMLSpanElement> {
  */
 declare const EyebrowToken: React.ForwardRefExoticComponent<TypeEyebrowTokenProps & React.RefAttributes<HTMLSpanElement>>;
 
+/** NarrativeDivider takes no extra props — just standard <hr> attributes. */
+type TypeNarrativeDividerProps = React.HTMLAttributes<HTMLHRElement>;
+
+/**
+ * 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.
+ */
+declare const NarrativeDivider: React.ForwardRefExoticComponent<TypeNarrativeDividerProps & React.RefAttributes<HTMLHRElement>>;
+
 interface TypeMetricHighlightTrend {
     /**
      * Direction of movement. Selects the arrow glyph and the sentiment color of
@@ -181,16 +207,13 @@ interface TypeMetricHighlightProps extends React.HTMLAttributes<HTMLDivElement>
     /** 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 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).
      */
-    chart?: boolean;
+    sparkline?: React.ReactNode;
     /**
      * Layout direction.
      * - `horizontal` — metric block beside the sparkline.
@@ -216,7 +239,9 @@ interface TypeMetricHighlightProps extends React.HTMLAttributes<HTMLDivElement>
 /**
  * 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.
+ * 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
@@ -225,6 +250,199 @@ interface TypeMetricHighlightProps extends React.HTMLAttributes<HTMLDivElement>
  */
 declare const MetricHighlight: React.ForwardRefExoticComponent<TypeMetricHighlightProps & React.RefAttributes<HTMLDivElement>>;
 
+/**
+ * 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.
+ */
+type TypeNarrativeSummaryLayout = "three-column" | "two-column";
+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;
+}
+
+/**
+ * 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`.
+ */
+declare const NarrativeSummary: React.ForwardRefExoticComponent<TypeNarrativeSummaryProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Item arrangement.
+ * - `"vertical"`: items stacked full-width, one per row (the default).
+ * - `"horizontal"`: items laid out as a row of equal columns that collapses
+ *   back to a stack when the container is narrow (container query).
+ */
+type TypeNarrativeOrderedListOrientation = "vertical" | "horizontal";
+interface TypeNarrativeOrderedListItem {
+    /** Bold action title for the item. A plain string or any React node. */
+    title: React.ReactNode;
+    /**
+     * Descriptive text below the title. A plain string or any React node. The
+     * paragraph is omitted when this is empty.
+     */
+    description?: React.ReactNode;
+    /**
+     * Optional call-to-action rendered below the description, only when provided.
+     * Typically a Seeds `<Button>` in an AI appearance (e.g.
+     * `appearance="ai-secondary"`). Pass it without system props so it renders the
+     * Tailwind path — same as NarrativeSummary's `action` slot.
+     */
+    action?: React.ReactNode;
+}
+interface TypeNarrativeOrderedListProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The ordered items. Numbered automatically (01, 02, …) in order. */
+    items: TypeNarrativeOrderedListItem[];
+    /**
+     * Item arrangement. `"horizontal"` lays items in a row of equal columns that
+     * collapses to a stack when the container is narrow; `"vertical"` is always
+     * stacked.
+     * @default "vertical"
+     */
+    orientation?: TypeNarrativeOrderedListOrientation;
+}
+
+/**
+ * NarrativeOrderedList — a numbered list of action items. Each item pairs a
+ * large ordinal (01, 02, …) with a title, an optional description, and an
+ * optional call-to-action slot.
+ *
+ * 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 driven by container queries, so it responds to the width the
+ * component is actually given, not the viewport:
+ * - `"vertical"` (default) → items stacked full-width, one per row.
+ * - `"horizontal"` → items laid out as a row of equal columns once there is
+ *   room, collapsing back to a stack when the container is narrow.
+ *
+ * Styled via `narrative-ordered-list.css` (Seeds CSS custom properties);
+ * consumers import the classes through `@sproutsocial/racine/css/components`.
+ * Overrides come via standard `className` / `style`.
+ */
+declare const NarrativeOrderedList: React.ForwardRefExoticComponent<TypeNarrativeOrderedListProps & React.RefAttributes<HTMLDivElement>>;
+
+interface TypeNarrativeDataCalloutProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Data-viz component rendered in the left slot (occupies ~1/3 of the width).
+     * The kit ships no chart of its own — drop in any data-viz node, e.g. a v2
+     * `DonutChart` from `@sproutsocial/seeds-react-data-viz`.
+     */
+    visual: React.ReactNode;
+    /** Body copy / description occupying the right two-thirds. */
+    children: React.ReactNode;
+    /**
+     * Accessible label for the visual slot region. Omit when the injected visual
+     * already carries its own description/label.
+     */
+    visualLabel?: string;
+}
+
+/**
+ * NarrativeDataCallout — a horizontally oriented callout that pairs an injected
+ * data-viz visual (left, ~1/3 width) with a block of body copy (right, ~2/3).
+ *
+ * The kit ships no chart of its own; the `visual` slot accepts any node — the
+ * stories drop in a v2 `DonutChart` from `@sproutsocial/seeds-react-data-viz`.
+ * narrative-kit takes no runtime dependency on data-viz (mirrors MetricHighlight's
+ * `sparkline` slot).
+ *
+ * Renders inner content only — it carries no surface, shadow, or accent of its
+ * own. Drop it into a `NarrativeContainer` (see the stories) to reproduce the
+ * card look.
+ *
+ * Layout is a flex row driven by a container query, so it collapses to a stacked
+ * column (visual on top, text below) based on the width the component is actually
+ * given, not the viewport.
+ *
+ * Styled via `narrative-data-callout.css` (Seeds CSS custom properties); consumers
+ * import the classes through `@sproutsocial/racine/css/components`. Overrides come
+ * via standard `className` / `style`.
+ */
+declare const NarrativeDataCallout: React.ForwardRefExoticComponent<TypeNarrativeDataCalloutProps & React.RefAttributes<HTMLDivElement>>;
+
+interface TypeAIContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Content rendered inside the container. */
+    children?: 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 (always white).
+     * @default "subtle"
+     */
+    appearance?: "subtle" | "vivid";
+}
+
+/**
+ * AIContainer — a rounded surface primitive with the AI gradient background.
+ * Provides the outer shell (border-radius, shadow, overflow, gradient) without
+ * any padding. Used by PullQuote and available as a standalone container.
+ *
+ * - `subtle` — a light 20% gradient tint over the base surface with adaptive text color.
+ * - `vivid` — the full-saturation AI gradient with white text (always white).
+ *
+ * Styled via `ai-container.css` (Seeds CSS custom properties).
+ */
+declare const AIContainer: React.ForwardRefExoticComponent<TypeAIContainerProps & React.RefAttributes<HTMLDivElement>>;
+
 /**
  * Shared types for narrative primitives.
  *
@@ -237,4 +455,4 @@ declare const MetricHighlight: React.ForwardRefExoticComponent<TypeMetricHighlig
  */
 type TypeNarrativeTone = "neutral" | "positive" | "negative" | "opportunity";
 
-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 };
+export { AIContainer, EyebrowToken, MetricHighlight, NarrativeContainer, NarrativeDataCallout, NarrativeDivider, NarrativeHeadline, NarrativeHeadlineHighlight, NarrativeHeadlineRoll, NarrativeOrderedList, NarrativeSummary, PullQuote, type TypeAIContainerProps, type TypeEyebrowTokenProps, type TypeMetricHighlightProps, type TypeMetricHighlightTrend, type TypeNarrativeContainerProps, type TypeNarrativeDataCalloutProps, type TypeNarrativeDividerProps, type TypeNarrativeHeadlineHighlightProps, type TypeNarrativeHeadlineLevel, type TypeNarrativeHeadlineProps, type TypeNarrativeHeadlineRollProps, type TypeNarrativeOrderedListItem, type TypeNarrativeOrderedListOrientation, type TypeNarrativeOrderedListProps, type TypeNarrativeSummaryLayout, type TypeNarrativeSummaryProps, type TypeNarrativeTone, type TypePullQuoteProps };