@nimbus-ds/patterns 1.32.0 → 1.33.1

package/dist/index.d.ts

@@ -1477,6 +1477,129 @@ export interface ChatInputProperties {
 }
 export type ChatInputProps = ChatInputProperties & Omit<BoxProperties, "children" | "display"> & HTMLAttributes<HTMLElement>;
 export declare const ChatInput: React.FC<ChatInputProps> & ChatInputComponents;
+/** Trend direction for the indicator (up, down, or neutral). */
+export type TrendDirection = "up" | "down" | "neutral";
+/**
+ * Props for the SummaryStatsItem component.
+ *
+ * Defines the props used to render a single stat: a primary value, description,
+ * optional trend indicator, optional tooltip, and optional expandable content
+ * (children). Used by the SummaryStatsItem component to display one metric in
+ * a summary stats row.
+ *
+ * @see SummaryStatsItem - Component that consumes these props.
+ * @property children - Optional ReactNode rendered in the expandable area when this stat is active.
+ */
+export interface SummaryStatsItemProperties {
+	/**
+	 * The main value to display (e.g., "$0.00", "156").
+	 */
+	value: string;
+	/**
+	 * Brief text that identifies the metric.
+	 */
+	description: string;
+	/**
+	 * Trend indicator showing the change direction.
+	 */
+	trend?: TrendDirection;
+	/**
+	 * Text describing the trend or change (e.g., "+15%", "-5%", "0%").
+	 */
+	trendText?: string;
+	/**
+	 * Tooltip content for the info icon. If provided, displays an info icon.
+	 */
+	infoTooltip?: string;
+	/**
+	 * Content to display when this stat is active (for expandable variant).
+	 * This content will be rendered in the expandable area below the stats row.
+	 * @TJS-type React.ReactNode
+	 */
+	children?: ReactNode;
+}
+export type SummaryStatsItemProps = SummaryStatsItemProperties & Omit<HTMLAttributes<HTMLElement>, "color">;
+declare const SummaryStatsItem: React.FC<SummaryStatsItemProps>;
+/**
+ * Layout variant for the SummaryStats container.
+ * - "horizontal": single row (optionally with scroll/expand).
+ * - "grid": 2-column grid.
+ */
+export type SummaryStatsLayout = "horizontal" | "grid";
+/**
+ * Subcomponents exposed on SummaryStats (e.g. SummaryStats.Item).
+ * Use {@link SummaryStatsItem} for the Item subcomponent type and API.
+ */
+export interface SummaryStatsComponents {
+	Item: typeof SummaryStatsItem;
+}
+/**
+ * Props specific to SummaryStats. Children should be {@link SummaryStatsItem}
+ * nodes (SummaryStats.Item). Layout is "horizontal" (default) or "grid".
+ * Defaults: layout "horizontal", expandable false.
+ *
+ * Supports both controlled and uncontrolled modes for the active stat:
+ * - **Uncontrolled** (default): omit `activeStatId` and the component manages
+ *   active state internally.
+ * - **Controlled**: pass `activeStatId` and `onActiveStatIdChange` to manage
+ *   the active stat externally (e.g. for routing, analytics, or persistence).
+ */
+export interface SummaryStatsProperties {
+	/**
+	 * Content to be rendered inside the SummaryStats component.
+	 * Composed of SummaryStats.Item subcomponents.
+	 * @TJS-type React.ReactNode
+	 */
+	children: ReactNode;
+	/**
+	 * Layout variant for the stats container.
+	 * - "horizontal": Items in a single row (2-6 items recommended).
+	 * - "grid": Items in a 2-column grid layout (2 or 4 items recommended).
+	 * @default "horizontal"
+	 */
+	layout?: SummaryStatsLayout;
+	/**
+	 * Enables expandable mode where stats can be clicked to show additional content.
+	 * @default false
+	 */
+	expandable?: boolean;
+	/**
+	 * The id of the currently active stat (controlled mode).
+	 * When provided, the component becomes controlled and `onActiveStatIdChange`
+	 * should be used to handle state changes. Pass `null` for no active stat.
+	 */
+	activeStatId?: string | null;
+	/**
+	 * Callback fired when the active stat changes (controlled mode).
+	 * Receives the new active stat id, or `null` when the active stat is deselected.
+	 */
+	onActiveStatIdChange?: (activeStatId: string | null) => void;
+}
+/**
+ * Full props for SummaryStats: {@link SummaryStatsProperties} plus HTML element
+ * attributes (excluding color). Use for the root SummaryStats component.
+ */
+export type SummaryStatsProps = SummaryStatsProperties & Omit<HTMLAttributes<HTMLElement>, "color">;
+/**
+ * SummaryStats displays a set of stat blocks in a configurable layout. Use
+ * {@link SummaryStatsProps} for the full props type and {@link SummaryStatsComponents}
+ * for the compound component API (e.g. SummaryStats.Item).
+ *
+ * Layout can be horizontal (single row, optionally with scroll/expand) or grid
+ * (2-column). When layout is "horizontal" and expandable is true, clicking a
+ * stat toggles an expanded area below showing that stat's extra content.
+ *
+ * @param props - See SummaryStatsProps
+ * @param props.className - Optional CSS class for the root element
+ * @param props.style - Optional inline styles for the root element
+ * @param props.children - Stat items, typically SummaryStats.Item components
+ * @param props.layout - "horizontal" (default) or "grid"; controls row vs grid layout
+ * @param props.expandable - When true and layout is horizontal, stats are expandable
+ * @param props.activeStatId - Optional. Controlled active stat id. Pass `null` for none.
+ * @param props.onActiveStatIdChange - Optional. Callback when active stat changes.
+ * @param props.rest - Remaining HTML element attributes (spread to root Box)
+ */
+export declare const SummaryStats: React.FC<SummaryStatsProps> & SummaryStatsComponents;
 export interface MenuExpandContextValue {
 	/** True when the menu is expanded; false when collapsed. */
 	expanded: boolean;