@fabio.caffarello/react-design-system 3.5.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/hooks/useScrollSpy.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Options for `useScrollSpy`.
+ */
+export interface UseScrollSpyOptions {
+    /**
+     * `IntersectionObserver` `rootMargin`. Shrinks the effective viewport
+     * the observer reports on. The default `"0px 0px -50% 0px"` shrinks
+     * the bottom edge by half — a section is considered "in view" only
+     * when part of it sits in the upper half of the viewport, which is
+     * the canonical "table-of-contents follows the scroll" behaviour. To
+     * compensate for a sticky header, prefix the top with a negative
+     * pixel value, e.g. `"-56px 0px -50% 0px"`.
+     *
+     * @default "0px 0px -50% 0px"
+     */
+    rootMargin?: string;
+    /**
+     * `IntersectionObserver` `threshold`. With the default `0`, the
+     * observer fires when any part of the target enters the (margin-
+     * shrunken) viewport.
+     *
+     * @default 0
+     */
+    threshold?: number | number[];
+}
+/**
+ * Track which section of a long scroll surface is currently in view,
+ * suitable for a table-of-contents nav that highlights the active section
+ * (the classic "scroll spy" pattern).
+ *
+ * The hook resolves each `id` to a DOM element via
+ * `document.getElementById`, observes those elements with a single
+ * `IntersectionObserver`, and returns the **id of the topmost visible
+ * section**. Returns `null` when nothing has reported as visible yet —
+ * including on the server, during the first render before the effect
+ * runs, and any frame where no observed section intersects the
+ * (margin-shrunken) viewport.
+ *
+ * ### Behavioural contract
+ *
+ * - **Return value.** `string | null`. `null` until at least one section
+ *   has been reported intersecting; never falls back to a "first id"
+ *   heuristic. Consumers that want a default highlight should fall back
+ *   themselves: `active ?? ids[0]`.
+ * - **Tie-breaking.** When multiple sections intersect simultaneously,
+ *   the hook picks the one **closest to the top of the viewport**
+ *   (smallest `boundingClientRect.top`). This matches the user's
+ *   expectation that scrolling DOWN advances the highlight forward, not
+ *   backward.
+ * - **Missing ids.** An id that resolves to no element is skipped
+ *   silently. The observer is created only when at least one element
+ *   resolves; an empty `ids` array (or one with all-missing ids) leaves
+ *   `activeId` as `null` and creates no observer.
+ * - **Cleanup.** The observer is disconnected on unmount and when the
+ *   `ids` set changes, before a new observer is created. No leaks.
+ * - **Re-observation on `ids` change.** The hook detects changes via a
+ *   string sentinel `ids.join("|")`. Pass `ids` as a stable reference
+ *   (constant module-scope array, or `useMemo`) to avoid recreating the
+ *   observer on every render. The hook does not memoise `ids` for you
+ *   because the consumer typically already knows whether the array is
+ *   stable.
+ * - **SSR safety.** `IntersectionObserver` and `document` are accessed
+ *   only inside `useEffect`, which never runs on the server. The hook
+ *   returns `null` during server rendering and the first client render
+ *   pre-commit. A `typeof window` guard inside the effect protects
+ *   older runtimes that evaluate `useEffect` outside a browser.
+ * - **`useState` initial value.** Always `null`. Returning the first id
+ *   would highlight a section that the user has not yet seen and
+ *   contradict the SSR/hydration contract.
+ *
+ * ### Why this lives in the design system as a hook, not as a component
+ *
+ * The visual surface (a sticky nav with highlighted active item) is
+ * already covered by `Navigation` + `NavLink` with the `active` prop. A
+ * `<ScrollSpy>` component would fuse behaviour and visual, restrict
+ * layout choice, and couple to a sibling component (`SectionCard`) via
+ * an opaque id-string convention. As a hook the consumer keeps the
+ * `ids` constant in one place and composes the nav however they want:
+ * vertical, horizontal, sticky, in a drawer, etc.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useScrollSpy, Navigation, NavLink } from "@fabio.caffarello/react-design-system";
+ *
+ * const SECTIONS = ["intro", "votos", "gastos"];
+ *
+ * function ProfileToc() {
+ *   const active = useScrollSpy(SECTIONS, { rootMargin: "-56px 0px -50% 0px" });
+ *   return (
+ *     <nav className="sticky top-14">
+ *       <Navigation orientation="vertical">
+ *         {SECTIONS.map((id) => (
+ *           <NavLink
+ *             key={id}
+ *             href={`#${id}`}
+ *             active={id === active}
+ *             aria-current={id === active ? "location" : undefined}
+ *           >
+ *             {id}
+ *           </NavLink>
+ *         ))}
+ *       </Navigation>
+ *     </nav>
+ *   );
+ * }
+ * ```
+ *
+ * @param ids - Element ids to observe, in document order. Stable
+ *   reference recommended (constant or `useMemo`).
+ * @param options - Optional `IntersectionObserver` overrides — see
+ *   {@link UseScrollSpyOptions}.
+ * @returns The id of the topmost visible section, or `null` when
+ *   nothing is reported visible yet.
+ */
+export declare function useScrollSpy(ids: string[], options?: UseScrollSpyOptions): string | null;

package/dist/ui/index.d.ts

@@ -15,3 +15,5 @@ export { ThemeProvider, ConfigProvider, ToastProvider, DialogProvider, useTheme,
 export { AppProvider, useApp, type AppProviderProps, type AppProviderConfig, } from "./providers/AppProvider";
 export * from "./primitives";
 export * from "./components";
+export { useScrollSpy } from "./hooks/useScrollSpy";
+export type { UseScrollSpyOptions } from "./hooks/useScrollSpy";

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.5.0",
+  "version": "3.7.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",