Data-rich applications built using Preswald often require a visual highlight of KPIs like total revenue, conversion rate, or average score. Currently, Preswald lacks a dedicated UI component to display such single-value summaries prominently and attractively.

There is a clear need for a reusable, visually prominent “big number” metric card.

Feature Overview

Introduce a new big_number() UI component for the Preswald SDK, enabling developers to render high-impact numeric KPIs in a card format, optionally with a label, subtext, icon, or trend indicator.

Example Usage in Python

from preswald import big_number

big_number(
    value=15602,
    label="Total Users",
    delta="+5.4%",
    delta_color="green",
    icon="user",
    description="Since last week"
)

🎯 Functional Requirements

• Primary Value (Required):

  • Accepts int, float, or str values.
  • Automatically formats large numbers (e.g., 1200000 → 1.2M).

• Label:

  • String displayed above or below the big number (e.g., “Total Users”).

• Delta Indicator:

  • Value + color-coded change indicator (e.g., "+5.2%", with green arrow).
  • Accept delta_color: str to customize appearance (green, red, gray).

• Icon:

  • Icon name to be rendered (integrated with an icon library like lucide-react).
  • Positioned to the left or right of the number.

UI/UX Mock

• Bold central number
• Smaller label above or below
• Optional arrow/delta to right
• Optional icon to left
• Light background card with padding and subtle shadow
• Option to stack horizontally with other metric cards

🛠️ Engineering Tasks

1. Frontend Implementation:

   • Create a new BigNumberWidget.jsx in frontend/src/components/widgets/.
   • Use Card, Typography, and Tailwind utility classes for layout.
   • Support props: value, label, delta, deltaColor, icon, description.

2. SDK Integration:

   • Add big_number() to preswald/interfaces/components.py.
   • Register as a new component type in the layout engine and render pipeline.

3. Testing:

   • Snapshot tests for various display configurations.

4. Docs & Demo:

   • Add new SDK docs in docs/sdk/big_number.mdx.
   • Include an example in examples/iris/hello.py or a new metrics_demo example.
   • Document in preswald/docs/usage/examples.mdx.