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

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

@@ -5,6 +5,12 @@ export interface AccordionItem {
     title: string;
     content: ReactNode;
     disabled?: boolean;
+    /** Extra classes for the item wrapper (the bordered card). Merged after the defaults, so conflicting Tailwind classes win. */
+    className?: string;
+    /** Extra classes for the header button — overrides the default `label` typography (e.g. `font-semibold text-base`). */
+    triggerClassName?: string;
+    /** Extra classes for the content padding wrapper inside the panel. */
+    contentClassName?: string;
 }
 export interface AccordionProps {
     items: AccordionItem[];
@@ -18,7 +24,9 @@ export interface AccordionProps {
  *
  * A collapsible content component that can display multiple items.
  * Supports single and multiple selection modes.
- * Follows Atomic Design principles as an Atom component.
+ *
+ * Open panels animate via `grid-template-rows: 0fr → 1fr`, so content of
+ * any height expands fully — there is no max-height clamp (issue #202).
  *
  * @example
  * ```tsx

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-entry.d.ts

@@ -0,0 +1,2 @@
+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/dist/ui/utils/tailwind-safelist.d.ts

@@ -32,7 +32,9 @@ export declare const TAILWIND_SAFELIST: readonly [RegExp, RegExp, RegExp, RegExp
  * Documentation for Tailwind v4 configuration
  *
  * In Tailwind v4, safelist is configured via CSS using @theme or @source directives.
- * Since we're using @tailwindcss/postcss, we can add safelist in the CSS file.
+ * Since we're using the @tailwindcss/vite plugin (see vite.config.ts and
+ * .claude/rules/tokens.md — the PostCSS pipeline is banned), we can add
+ * safelist in the CSS file.
  *
  * For dynamic classes, we should ensure they're:
  * 1. Used in component code (so Tailwind detects them)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fabio.caffarello/react-design-system",
   "private": false,
-  "version": "3.6.0",
+  "version": "3.8.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -19,6 +19,11 @@
       "import": "./dist/server/index.js",
       "require": "./dist/server/index.cjs"
     },
+    "./hooks": {
+      "types": "./dist/ui/hooks-entry.d.ts",
+      "import": "./dist/hooks/index.js",
+      "require": "./dist/hooks/index.cjs"
+    },
     "./styles": "./dist/react-design-system.css",
     "./styles.css": "./dist/react-design-system.css"
   },
@@ -31,7 +36,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "npx tsc --project tsconfig.app.json --declaration --emitDeclarationOnly --outDir dist && vite build && vite build --config vite.config.server.ts && npm run build:validate",
+    "build": "npx tsc --project tsconfig.app.json --declaration --emitDeclarationOnly --outDir dist && vite build && vite build --config vite.config.server.ts && vite build --config vite.config.hooks.ts && npm run build:validate",
     "build:validate": "tsx scripts/validate-build-exports.ts && node scripts/validate-use-client-in-dist.mjs && node scripts/validate-server-entry.mjs",
     "lint": "eslint .",
     "typecheck": "tsc --build --force tsconfig.json",
@@ -50,7 +55,7 @@
     "lucide-react": "^0.552.0 || ^1.0.0",
     "react": ">=19",
     "react-dom": ">=19",
-    "react-hook-form": "^7.77.0"
+    "react-hook-form": "^7.78.0"
   },
   "overrides": {
     "handlebars": "^4.7.9",
@@ -77,8 +82,7 @@
     }
   },
   "dependencies": {
-    "@radix-ui/react-slot": "^1.2.4",
-    "@tailwindcss/postcss": "^4.1.16",
+    "@radix-ui/react-slot": "^1.2.5",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "react": ">=19",
@@ -86,8 +90,8 @@
     "tailwind-merge": "^3.6.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.3.1",
-    "@commitlint/config-conventional": "^20.3.1",
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.60.0",
     "@storybook/addon-a11y": "^10.4.2",
@@ -99,19 +103,19 @@
     "@storybook/addon-vitest": "^10.4.2",
     "@storybook/react-vite": "^10.4.2",
     "@storybook/test": "^8.6.15",
-    "@tailwindcss/vite": "^4.1.16",
+    "@tailwindcss/vite": "^4.3.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/bun": "^1.3.7",
-    "@types/node": "^24.6.0",
-    "@types/react": "^19.2.16",
+    "@types/node": "^25.9.2",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.0.4",
     "@vitest/browser-playwright": "^4.1.8",
     "@vitest/coverage-v8": "^4.1.8",
-    "autoprefixer": "^10.4.21",
-    "baseline-browser-mapping": "^2.10.32",
+    "autoprefixer": "^10.5.0",
+    "baseline-browser-mapping": "^2.10.34",
     "culori": "^4.0.2",
     "dependency-cruiser": "^17.3.6",
     "eslint": "^10.4.1",
@@ -127,7 +131,7 @@
     "plop": "^4.0.4",
     "postcss": "^8.5.6",
     "prettier": "^3.8.3",
-    "react-hook-form": "^7.77.0",
+    "react-hook-form": "^7.78.0",
     "remark-gfm": "^4.0.1",
     "storybook": "^10.4.2",
     "storybook-addon-performance": "^0.17.3",