@fabio.caffarello/react-design-system 4.7.0 → 4.9.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/components/EmptyState/EmptyStateBase.d.ts

@@ -0,0 +1,52 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export interface EmptyStateBaseProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    title: string;
+    /**
+     * Descriptive message below the title. Optional — several empty states
+     * have only a title. When absent, `aria-label` is just the title and no
+     * `<p>` element is rendered.
+     */
+    message?: string;
+    /**
+     * Optional decorative illustration (icon, SVG, image). Rendered
+     * `aria-hidden` above the title.
+     */
+    illustration?: ReactNode;
+    /**
+     * Action slot — any ReactNode (link, button, custom CTA). Rendered
+     * below the message (or title when message is absent).
+     *
+     * Use a plain `<a href>` or `next/link` here to keep the component
+     * zero-JS in Server Components; the slot is passed through with no
+     * wrapper or event handler added.
+     *
+     * @example
+     * // Zero-JS link — Server Component safe
+     * <EmptyStateBase
+     *   title="Sem resultados"
+     *   action={<a href="/">Limpar filtros</a>}
+     * />
+     */
+    action?: ReactNode;
+}
+/**
+ * EmptyStateBase — the **server-safe presentational core** of `EmptyState`
+ * (issue #252 follow-up).
+ *
+ * It holds no React client state (no hooks, no `"use client"` directive), so
+ * it can be imported from `@fabio.caffarello/react-design-system/server` and
+ * rendered inside React Server Components and zero-JS routes.
+ *
+ * ### Trade-off vs `EmptyState`
+ *
+ * | Feature                      | EmptyStateBase       | EmptyState                  |
+ * |------------------------------|----------------------|-----------------------------|
+ * | `action` ReactNode slot      | ✅                   | ✅                          |
+ * | `onAction` callback button   | ❌ (needs client JS) | ✅                          |
+ * | `./server` exportable        | ✅                   | ❌ (barrel pulls Input/useId)|
+ *
+ * Use `EmptyState` when you need a client-driven callback button (`onAction`).
+ * Use `EmptyStateBase` in Server Components where the CTA is a zero-JS link.
+ */
+declare const EmptyStateBase: import("react").ForwardRefExoticComponent<EmptyStateBaseProps & import("react").RefAttributes<HTMLDivElement>>;
+export default EmptyStateBase;

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

@@ -1,2 +1,4 @@
 export { default } from "./EmptyState";
 export type { EmptyStateProps } from "./EmptyState";
+export { default as EmptyStateBase } from "./EmptyStateBase";
+export type { EmptyStateBaseProps } from "./EmptyStateBase";

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" | "2xl" | "3xl";
+import type { AvatarSize } from "./AvatarBase";
+export type { AvatarSize } from "./AvatarBase";
 export interface AvatarProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
     src?: string;
     alt?: string;

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";
@@ -29,6 +31,8 @@ export { Stack } from "./layouts/Stack/Stack";
 export type { StackProps } from "./layouts/Stack/Stack";
 export { default as Breadcrumb } from "./components/Breadcrumb/Breadcrumb";
 export type { BreadcrumbItem } from "./components/Breadcrumb/Breadcrumb";
+export { default as EmptyStateBase } from "./components/EmptyState/EmptyStateBase";
+export type { EmptyStateBaseProps } from "./components/EmptyState/EmptyStateBase";
 export { default as Card } from "./components/Card/Card";
 export type { CardProps } from "./components/Card/Card";
 export { CardHeader } from "./components/Card/CardHeader";

package/package.json

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