@fabio.caffarello/react-design-system 4.6.0 → 4.8.0

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

@@ -1,7 +1,29 @@
 import type { HTMLAttributes, ReactNode } from "react";
 export interface EmptyStateProps extends HTMLAttributes<HTMLDivElement> {
     title: string;
-    message: string;
+    /**
+     * Descriptive message below the title.
+     * Optional — several empty states have only a title (e.g. a section
+     * that speaks for itself). When absent, the `aria-label` is just the
+     * title; the `<p>` element is not rendered.
+     */
+    message?: string;
+    /**
+     * Action slot — accepts any ReactNode (link, button, custom CTA).
+     * Takes priority over `actionLabel` + `onAction`.
+     *
+     * Use this prop when the action is a server-rendered `<a>` or
+     * `next/link` (zero-JS route); the component renders it without
+     * wrapping it in a client Button. When you need a callback-driven
+     * button, use `actionLabel` + `onAction` instead (or pass
+     * `<Button onClick={…}>…</Button>` here).
+     *
+     * @example
+     * // Server-rendered link (zero-JS)
+     * <EmptyState title="Sem resultados" action={<a href="/lista">Limpar filtros</a>} />
+     */
+    action?: ReactNode;
+    /** @deprecated Prefer the `action` slot for new code. Still supported for backwards compat. */
     actionLabel?: string;
     onAction?: () => void;
     illustration?: ReactNode;
@@ -22,4 +44,4 @@ export interface EmptyStateProps extends HTMLAttributes<HTMLDivElement> {
  * />
  * ```
  */
-export default function EmptyState({ title, message, actionLabel, onAction, illustration, variant, className, ...props }: EmptyStateProps): import("react").JSX.Element;
+export default function EmptyState({ title, message, action, actionLabel, onAction, illustration, variant, className, ...props }: EmptyStateProps): import("react").JSX.Element;

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

@@ -1,5 +1,6 @@
 import { type HTMLAttributes, type ReactNode } from "react";
-export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+import type { AvatarSize } from "./AvatarBase";
+export type { AvatarSize } from "./AvatarBase";
 export interface AvatarProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
     src?: string;
     alt?: string;
@@ -7,13 +8,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 +53,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/dist/ui/primitives/Avatar/AvatarBase.d.ts

@@ -0,0 +1,63 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+export interface AvatarBaseProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    src?: string;
+    alt?: string;
+    fallback?: string | ReactNode;
+    size?: AvatarSize;
+    variant?: "circle" | "square" | "rounded";
+    /**
+     * 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.
+     *
+     * Has no effect when `src` is absent (no `<img>` is rendered).
+     *
+     * @default 'eager'
+     */
+    loading?: "lazy" | "eager";
+    "aria-label"?: string;
+}
+/**
+ * AvatarBase — the **server-safe presentational core** of `Avatar` (issue #250).
+ *
+ * It holds no React client state (`useState` / `useEffect` / hooks of any
+ * kind), so it is importable from
+ * `@fabio.caffarello/react-design-system/server` and renders inside React
+ * Server Components and zero-JS routes.
+ *
+ * ### Trade-off vs `Avatar`
+ *
+ * | Scenario                  | AvatarBase behaviour                              |
+ * |---------------------------|---------------------------------------------------|
+ * | `src` absent / null       | Renders initials fallback — fully server-rendered |
+ * | `src` present, loads OK   | Renders `<img>` — same as `Avatar`                |
+ * | `src` present, 404s       | Browser broken-image; no graceful JS fallback     |
+ *
+ * Use `Avatar` (main entry) when you need the graceful `onError` swap to
+ * initials (requires `useState` — client island). Use `AvatarBase` in
+ * Server Components and listings that are deliberately zero-JS, where `src`
+ * is null for entries without a photo and a graceful 404 fallback is
+ * acceptable to forgo.
+ *
+ * @example
+ * ```tsx
+ * // Server Component list — zero-JS, initials rendered on server when src is null
+ * import { AvatarBase } from "@fabio.caffarello/react-design-system/server";
+ *
+ * export default function ParlamentarCard({ parlamentar }) {
+ *   return (
+ *     <AvatarBase
+ *       src={parlamentar.fotoUrl ?? undefined}
+ *       fallback={parlamentar.nome}
+ *       alt={parlamentar.nome}
+ *       size="md"
+ *       loading="lazy"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare const AvatarBase: import("react").ForwardRefExoticComponent<AvatarBaseProps & import("react").RefAttributes<HTMLDivElement>>;
+export default AvatarBase;

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

@@ -5,5 +5,7 @@
  */
 export { default as Avatar } from "./Avatar";
 export type { AvatarProps, AvatarSize } from "./Avatar";
+export { default as AvatarBase } from "./AvatarBase";
+export type { AvatarBaseProps } from "./AvatarBase";
 export { AvatarGroup } from "./AvatarGroup";
 export type { AvatarGroupProps } from "./AvatarGroup";

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

@@ -1,9 +1,18 @@
 import type { HTMLAttributes, ReactNode } from "react";
-export interface TooltipProps extends HTMLAttributes<HTMLDivElement> {
-    content: string;
+export interface TooltipProps extends Omit<HTMLAttributes<HTMLDivElement>, "content"> {
+    content: ReactNode;
     children: ReactNode;
     position?: "top" | "bottom" | "left" | "right";
     delay?: number;
+    /**
+     * When true, the tooltip panel stays open while the pointer hovers over it
+     * (150 ms grace-period bridge), and keyboard focus may move into focusable
+     * elements inside the panel (e.g. links). Use for educational / rich
+     * tooltips that contain interactive content.
+     *
+     * @default false
+     */
+    interactive?: boolean;
     "aria-label"?: string;
     /**
      * When true, the tooltip wrapper won't interfere with absolute positioning of children.
@@ -16,11 +25,31 @@ export interface TooltipProps extends HTMLAttributes<HTMLDivElement> {
  *
  * A tooltip component for displaying additional information on hover.
  *
+ * Pass `content` as a plain string for simple labels, or as a `ReactNode`
+ * for rich / educational content. Set `interactive` when the panel contains
+ * clickable elements (links, buttons) — the tooltip then stays open while
+ * the pointer is over the panel and while keyboard focus is inside it.
+ *
  * @example
  * ```tsx
+ * // Simple string
  * <Tooltip content="This is a tooltip">
  *   <Button>Hover me</Button>
  * </Tooltip>
+ *
+ * // Rich interactive content
+ * <Tooltip
+ *   interactive
+ *   content={
+ *     <>
+ *       <strong>Pirâmide de Confiança L2</strong>
+ *       <p>Dados verificados por fonte oficial.</p>
+ *       <a href="/ajuda/piramide">Saiba mais</a>
+ *     </>
+ *   }
+ * >
+ *   <Badge>L2</Badge>
+ * </Tooltip>
  * ```
  */
 declare const Tooltip: import("react").ForwardRefExoticComponent<TooltipProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/ui/server.d.ts

@@ -1,3 +1,5 @@
+export { default as AvatarBase } from "./primitives/Avatar/AvatarBase";
+export type { AvatarBaseProps, AvatarSize, } from "./primitives/Avatar/AvatarBase";
 export { default as Badge } from "./primitives/Badge/Badge";
 export type { BadgeProps, BadgeSize, BadgeStyle, BadgeVariant, } from "./primitives/Badge/Badge";
 export { default as Button } from "./primitives/Button/Button";

package/package.json

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