@fabio.caffarello/react-design-system 4.5.0 → 4.7.0

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

@@ -23,6 +23,53 @@ export interface StatGroupProps extends HTMLAttributes<HTMLDivElement> {
      * @default 4
      */
     cols?: StatGroupCols;
+    /**
+     * Optional slot for a badge that floats centered over the top border of
+     * the container. Use when all metrics in the group share a common
+     * provenance mark (e.g. a trust badge, data-source seal, tier label).
+     *
+     * The slot is intentionally opaque — the consumer supplies any ReactNode
+     * and owns the badge's styling and a11y. `StatGroup` provides only the
+     * positioning, not the badge shape. This is the same convention as the
+     * `kicker` slot in `HeroSection` or the `badge` slot in `PageHeader`.
+     *
+     * ### Layout
+     *
+     * When `floatingBadge` is supplied the outer container gains
+     * `pt-4` (16 px) top padding, which creates a landing zone for the
+     * badge's bottom half while keeping the first stat row clear. The badge
+     * itself is absolutely centred at `top-4 left-1/2`, then shifted up by
+     * `−50%` of its own height so its centre sits on the inner container's
+     * top border. This calibration is accurate for badges up to ~32 px tall
+     * (a standard `Badge` or small `Chip`). If a taller badge is needed,
+     * pass a `className` that increases the top padding to match.
+     *
+     * ### Reading order
+     *
+     * The badge node appears in the DOM **before** the stat cells, so screen
+     * readers encounter it first — "Fonte oficial, followed by the metrics" —
+     * which is the correct contextual order.
+     *
+     * @example
+     * ```tsx
+     * import { CheckCircle2 } from "lucide-react";
+     * import { Badge } from "@fabio.caffarello/react-design-system";
+     *
+     * <StatGroup
+     *   layout="strip"
+     *   floatingBadge={
+     *     <Badge variant="success" size="sm">
+     *       <CheckCircle2 size={10} aria-hidden="true" />
+     *       Fonte oficial
+     *     </Badge>
+     *   }
+     * >
+     *   <Stat icon={<Users />} value="726" label="Parlam." align="center" />
+     *   <Stat icon={<FileText />} value="28,1 mil" label="Proposições" align="center" />
+     * </StatGroup>
+     * ```
+     */
+    floatingBadge?: ReactNode;
     children: ReactNode;
 }
 /**
@@ -31,17 +78,18 @@ export interface StatGroupProps extends HTMLAttributes<HTMLDivElement> {
  *
  * ### 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 inner 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.
+ * The inner ring is `border border-line-default` matching the gap color,
+ * with `rounded-lg` and `overflow-hidden` clipping the inner cells to the
+ * radius. The outer wrapper is `relative` so the optional `floatingBadge`
+ * can be absolutely positioned over the inner container's top border.
  *
  * ### Server-safe
  *
@@ -65,5 +113,5 @@ export interface StatGroupProps extends HTMLAttributes<HTMLDivElement> {
  * </StatGroup>
  * ```
  */
-export declare function StatGroup({ layout, cols, className, children, ...props }: StatGroupProps): import("react").JSX.Element;
+export declare function StatGroup({ layout, cols, floatingBadge, className, children, ...props }: StatGroupProps): import("react").JSX.Element;
 export default StatGroup;

package/dist/ui/primitives/Avatar/Avatar.d.ts

@@ -1,5 +1,5 @@
 import { type HTMLAttributes, type ReactNode } from "react";
-export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
 export interface AvatarProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
     src?: string;
     alt?: string;
@@ -7,13 +7,42 @@ export interface AvatarProps extends Omit<HTMLAttributes<HTMLDivElement>, "child
     size?: AvatarSize;
     variant?: "circle" | "square" | "rounded";
     "aria-label"?: string;
+    /**
+     * Controls the browser's native lazy-loading behaviour for the avatar
+     * `<img>`. Set to `"lazy"` to defer loading until the avatar is near the
+     * viewport — strongly recommended for listings with many off-screen
+     * profile images (e.g. a 24-card parliament listing).
+     *
+     * Maps directly to the native `<img loading>` attribute and has no effect
+     * when `src` is absent (no `<img>` is rendered).
+     *
+     * @default 'eager'
+     */
+    loading?: "lazy" | "eager";
 }
 /**
  * Avatar Component
  *
- * A versatile avatar component for displaying user profile images or initials.
- * Supports fallback display when image fails to load or is not provided.
- * Fully accessible with ARIA attributes.
+ * A versatile avatar component for displaying user profile images or
+ * initials. Supports fallback display when image fails to load or is not
+ * provided. Fully accessible with ARIA attributes.
+ *
+ * ### Size scale
+ *
+ * | size | px  | Use case                        |
+ * |------|-----|---------------------------------|
+ * | xs   | 24  | Tight inline / notification dot |
+ * | sm   | 32  | Comment thread, compact row     |
+ * | md   | 40  | Default — card header, form row |
+ * | lg   | 48  | Expanded card, sidebar profile  |
+ * | xl   | 64  | Detail-page section header      |
+ * | 2xl  | 96  | Hero profile (PerfilHeader)     |
+ * | 3xl  | 112 | Full-bleed hero cover           |
+ *
+ * ### Lazy loading
+ *
+ * Pass `loading="lazy"` on listings to defer off-screen image loads. The
+ * default is `"eager"` (matches browser default) for backward compatibility.
  *
  * @example
  * ```tsx
@@ -23,8 +52,11 @@ export interface AvatarProps extends Omit<HTMLAttributes<HTMLDivElement>, "child
  * // With fallback initials
  * <Avatar fallback="JD" alt="John Doe" />
  *
- * // Custom size
- * <Avatar src="/user.jpg" size="lg" />
+ * // Hero profile — larger size + lazy load
+ * <Avatar src="/perfil.jpg" alt="Dep. Silva" size="2xl" />
+ *
+ * // Listing — lazy-load all avatars below the fold
+ * <Avatar src="/user.jpg" alt="User Name" loading="lazy" />
  * ```
  */
 declare const Avatar: import("react").ForwardRefExoticComponent<AvatarProps & import("react").RefAttributes<HTMLDivElement>>;

package/package.json

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