@fabio.caffarello/react-design-system 3.6.0 → 3.7.0

package/dist/ui/components/Stat/Stat.d.ts

@@ -0,0 +1,105 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export type StatTone = "neutral" | "success" | "warning" | "error";
+export type StatAlign = "start" | "center";
+export interface StatProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * The metric value to display. Strings are rendered verbatim — formatting
+     * (number locale, currency, units, relative time, etc.) is the consumer's
+     * responsibility, not the design system's. Pass `null` or `undefined` to
+     * render the empty-state placeholder (see "Empty state" below).
+     */
+    value: ReactNode;
+    /**
+     * Short metric label (e.g. "Votos", "Alinhamento"). Required for screen
+     * reader context — the label describes what the value means.
+     */
+    label: string;
+    /**
+     * Optional third line of context below the value (e.g. "no banco",
+     * "últimos 12 m", "+3% no mês"). The `tone` prop styles THIS line — see
+     * `tone` for the contract.
+     */
+    hint?: ReactNode;
+    /**
+     * Optional icon rendered above the value (home-style stats use icons;
+     * detail-page stats typically don't).
+     */
+    icon?: ReactNode;
+    /**
+     * Block alignment. `start` left-aligns label/value/hint (detail-page
+     * style); `center` centers them (home-hero style).
+     * @default 'start'
+     */
+    align?: StatAlign;
+    /**
+     * Semantic tone for the metric — `neutral` for plain stats, the others
+     * for classified states (good/warning/bad).
+     *
+     * **Scope (contract).** Tone affects ONLY the `hint`, not the `value`,
+     * `label`, or `icon`. The `value` always renders in `text-fg-primary`
+     * regardless of tone; the `label` in `text-fg-secondary`; the `icon` in
+     * `text-icon-default`. This is deliberate — a colored value would
+     * compete with the label for attention and bias the reader's
+     * interpretation of the metric. If a future requirement needs the
+     * `value` (or icon) to inherit tone, that becomes a new prop or a
+     * semver-bound default change, not a surprise expansion of `tone`.
+     *
+     * Tone maps directly to the semantic foreground tokens (no new
+     * vocabulary): `neutral` → `text-fg-tertiary`, `success` →
+     * `text-fg-success`, `warning` → `text-fg-warning`, `error` →
+     * `text-fg-error`. See `.claude/rules/colors.md`.
+     *
+     * @default 'neutral'
+     */
+    tone?: StatTone;
+}
+/**
+ * `Stat` — a single statistic block (icon? + value + label + hint?).
+ *
+ * Composes with `StatGroup` (1-px-divider strip or grid) but is also
+ * valid standalone — a single `Stat` outside a group is a legitimate use
+ * case for a hero metric.
+ *
+ * ### Empty state contract
+ *
+ * When `value` is `null` OR `undefined`, the component renders the
+ * em-dash placeholder `—` (U+2014) with `aria-label="No data"` on its
+ * wrapper. The label is intentionally hard-coded in English in this
+ * version; a screen reader announcing "No data" in an otherwise
+ * Portuguese app is a known inconsistency accepted for now — if i18n
+ * becomes a requirement, an `emptyLabel?: string` prop will be added in
+ * a follow-up PR (semver-safe addition).
+ *
+ * Other falsy values — `0`, `""`, `false`, an empty fragment — are
+ * **legitimate values** and render as-is. The empty trigger is only
+ * `null`/`undefined`, because `0` (count = zero) is meaningful data that
+ * the consumer would not want masked.
+ *
+ * ### Server-safe
+ *
+ * Pure presentation — no hooks, no event handlers on the DOM. Ships in
+ * the `./server` entry alongside `StatGroup`. Consumer-supplied `icon`
+ * may itself be a client component; React's RSC boundary handles that
+ * normally.
+ *
+ * @example
+ * ```tsx
+ * // Home-style (centered, with icon)
+ * <Stat
+ *   icon={<Users size={20} aria-hidden="true" />}
+ *   value="9,4 mil"
+ *   label="Parlamentares"
+ *   align="center"
+ * />
+ *
+ * // Detail-page-style (start-aligned, with hint)
+ * <Stat
+ *   value="87%"
+ *   label="Alinhamento"
+ *   hint="últimos 12 meses"
+ *   tone="success"
+ * />
+ * ```
+ */
+export declare function Stat({ value, label, hint, icon, align, tone, className, ...props }: StatProps): import("react").JSX.Element;
+export default Stat;

package/dist/ui/components/Stat/StatGroup.d.ts

@@ -0,0 +1,69 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export type StatGroupLayout = "strip" | "grid";
+export type StatGroupCols = 2 | 3 | 4;
+export interface StatGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * `strip` — single horizontal row, no wrap. Each `Stat` shares the row
+     * width via `flex-1`. Use when you guarantee the horizontal space
+     * (hero areas, wide dashboards). On narrow viewports the row does NOT
+     * reflow — choose `grid` if you need responsive collapse.
+     *
+     * `grid` — multi-column grid that reflows. Always 2-up on mobile,
+     * expands to `cols` columns at the `md` breakpoint (768 px) and up.
+     * Five or more children spill to a second row with the divider lines
+     * preserved.
+     *
+     * @default 'grid'
+     */
+    layout?: StatGroupLayout;
+    /**
+     * Desktop column count (≥ 768 px). Only effective in `layout="grid"`;
+     * ignored in `layout="strip"`. Mobile is always 2 columns regardless.
+     *
+     * @default 4
+     */
+    cols?: StatGroupCols;
+    children: ReactNode;
+}
+/**
+ * `StatGroup` — container for one or more `Stat` blocks with 1-px
+ * dividers between them.
+ *
+ * ### Divider technique
+ *
+ * The container has `bg-line-default` and `gap-px` (1 px); each child
+ * `Stat` carries its own `bg-surface-base`. The 1 px of gap exposes the
+ * container's background as the divider line, while each cell masks its
+ * own area with `bg-surface-base`. Works identically for the strip
+ * layout (vertical dividers) and the grid layout (vertical AND
+ * horizontal dividers, automatically, as the grid reflows). No separate
+ * `Divider` component, no per-cell border logic.
+ *
+ * The outer ring is `border border-line-default` matching the gap color,
+ * with `rounded-lg` and `overflow-hidden` clipping the inner cells to
+ * the radius.
+ *
+ * ### Server-safe
+ *
+ * Pure presentation — no hooks, no event handlers on the DOM. Ships in
+ * `./server` alongside `Stat`.
+ *
+ * @example
+ * ```tsx
+ * <StatGroup layout="strip">
+ *   <Stat icon={<Users />} value="9,4 mil" label="Parlamentares" align="center" />
+ *   <Stat icon={<FileText />} value="3,2 mil" label="Proposições" align="center" />
+ *   <Stat icon={<Vote />} value="1,1 mil" label="Votações" align="center" />
+ *   <Stat icon={<Clock />} value="há 18 dias" label="Última atualização" align="center" />
+ * </StatGroup>
+ *
+ * <StatGroup layout="grid" cols={4}>
+ *   <Stat value="87%" label="Alinhamento" hint="últimos 12 m" tone="success" />
+ *   <Stat value={null} label="Sem orientação" hint="no período" />
+ *   <Stat value="R$ 187.472,95" label="Gastos" hint="no mandato" />
+ *   <Stat value="42" label="Votações" hint="no banco" />
+ * </StatGroup>
+ * ```
+ */
+export declare function StatGroup({ layout, cols, className, children, ...props }: StatGroupProps): import("react").JSX.Element;
+export default StatGroup;

package/dist/ui/components/Stat/index.d.ts

@@ -0,0 +1,4 @@
+export { Stat, default } from "./Stat";
+export type { StatProps, StatTone, StatAlign } from "./Stat";
+export { StatGroup } from "./StatGroup";
+export type { StatGroupProps, StatGroupLayout, StatGroupCols, } from "./StatGroup";

package/dist/ui/components/index.d.ts

@@ -1,4 +1,6 @@
 export { default as Card } from "./Card";
+export { Stat, StatGroup } from "./Stat";
+export type { StatProps, StatTone, StatAlign, StatGroupProps, StatGroupLayout, StatGroupCols, } from "./Stat";
 export * from "./Form";
 export { default as Breadcrumb } from "./Breadcrumb";
 export type { BreadcrumbItem } from "./Breadcrumb";

package/dist/ui/server.d.ts

@@ -53,6 +53,10 @@ export { default as NavbarSeparator } from "./components/SideNavbar/components/N
 export type { NavbarSeparatorProps } from "./components/SideNavbar/types";
 export { default as PageHeader } from "./components/PageHeader/PageHeader";
 export type { PageHeaderProps, PageHeaderVariant, } from "./components/PageHeader/types";
+export { default as Stat } from "./components/Stat/Stat";
+export type { StatProps, StatTone, StatAlign } from "./components/Stat/Stat";
+export { StatGroup } from "./components/Stat/StatGroup";
+export type { StatGroupProps, StatGroupLayout, StatGroupCols, } from "./components/Stat/StatGroup";
 export { default as TableCell } from "./components/Table/TableCell";
 export type { TableCellProps } from "./components/Table/TableCell";
 export { default as Timeline } from "./components/Timeline/Timeline";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fabio.caffarello/react-design-system",
   "private": false,
-  "version": "3.6.0",
+  "version": "3.7.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",