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

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

@@ -1,26 +1,33 @@
-import type { HTMLAttributes } from "react";
-interface Props extends HTMLAttributes<HTMLDivElement> {
+import { type FC, type HTMLAttributes } from "react";
+import { CardHeader } from "./CardHeader";
+import { CardTitle } from "./CardTitle";
+import { CardSubtitle } from "./CardSubtitle";
+import { CardActions } from "./CardActions";
+import { CardBody } from "./CardBody";
+export interface CardProps extends HTMLAttributes<HTMLDivElement> {
     variant?: "default" | "hover" | "selected";
     padding?: "none" | "small" | "medium" | "large";
     onClick?: () => void;
     "aria-label"?: string;
     "aria-labelledby"?: string;
+    /**
+     * Render the root as a semantic `<section>` instead of `<div>`.
+     * When `true`, the Card becomes a landmark — a screen-reader-visible
+     * region in the document outline — so it MUST carry an accessible
+     * name (either `aria-labelledby` pointing to a `Card.Title` `id` or
+     * `aria-label`). A dev-only warning is emitted when this contract
+     * isn't met; an anonymous landmark hurts navigation by announcing
+     * "region" without a name.
+     * @default false
+     */
+    asSection?: boolean;
 }
-/**
- * Card Component
- *
- * A versatile card component for displaying content in containers.
- * Follows Atomic Design principles as a Molecule component.
- * Can be used to replace BoxWrapper in many cases with more flexibility.
- * Optimized with React.memo to prevent unnecessary re-renders.
- *
- * @example
- * ```tsx
- * <Card variant="hover" padding="large">
- *   <h3>Card Title</h3>
- *   <p>Card content</p>
- * </Card>
- * ```
- */
-declare const Card: import("react").MemoExoticComponent<({ variant, padding, className, onClick, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, children, ...props }: Props) => import("react").JSX.Element>;
+type CardCompound = FC<CardProps> & {
+    Header: typeof CardHeader;
+    Title: typeof CardTitle;
+    Subtitle: typeof CardSubtitle;
+    Actions: typeof CardActions;
+    Body: typeof CardBody;
+};
+declare const Card: CardCompound;
 export default Card;

package/dist/ui/components/Card/CardActions.d.ts

@@ -0,0 +1,21 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export interface CardActionsProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+}
+/**
+ * CardActions — wrapper that hosts consumer-supplied action buttons
+ * within a `Card.Header`.
+ *
+ * The `data-card-actions` attribute is the structural marker `CardHeader`
+ * uses (via Tailwind v4 `:has()` selectors) to switch its grid layout
+ * from a single column to `[1fr auto]` when actions are present, so
+ * Title/Subtitle stack in column 1 and the action row spans both rows
+ * in column 2. Consumers should not override this attribute.
+ *
+ * This component is presentational: it emits no handlers on the DOM
+ * itself. The action elements (typically `<Button>`) are consumer-supplied
+ * and React's RSC boundary keeps them as client references — the
+ * wrapper stays server-safe.
+ */
+export declare function CardActions({ children, className, ...props }: CardActionsProps): import("react").JSX.Element;
+export default CardActions;

package/dist/ui/components/Card/CardBody.d.ts

@@ -0,0 +1,6 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export interface CardBodyProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+}
+export declare function CardBody({ children, className, ...props }: CardBodyProps): import("react").JSX.Element;
+export default CardBody;

package/dist/ui/components/Card/CardHeader.d.ts

@@ -0,0 +1,6 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export interface CardHeaderProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+}
+export declare function CardHeader({ children, className, ...props }: CardHeaderProps): import("react").JSX.Element;
+export default CardHeader;

package/dist/ui/components/Card/CardSubtitle.d.ts

@@ -0,0 +1,6 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export interface CardSubtitleProps extends HTMLAttributes<HTMLParagraphElement> {
+    children: ReactNode;
+}
+export declare function CardSubtitle({ children, className, ...props }: CardSubtitleProps): import("react").JSX.Element;
+export default CardSubtitle;

package/dist/ui/components/Card/CardTitle.d.ts

@@ -0,0 +1,22 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export type CardTitleAs = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+export interface CardTitleProps extends HTMLAttributes<HTMLHeadingElement> {
+    children: ReactNode;
+    /**
+     * Optional icon rendered before the title text.
+     */
+    icon?: ReactNode;
+    /**
+     * Optional badge rendered after the title text.
+     */
+    badge?: ReactNode;
+    /**
+     * Heading level. Default `h2` — the typical depth for a card title
+     * inside a page that already has an `h1`. Use `h3` (or deeper) when
+     * the card sits inside a nested section.
+     * @default 'h2'
+     */
+    as?: CardTitleAs;
+}
+export declare function CardTitle({ children, icon, badge, as: As, className, ...props }: CardTitleProps): import("react").JSX.Element;
+export default CardTitle;

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

@@ -1 +1,13 @@
 export { default } from "./Card";
+export { default as Card } from "./Card";
+export type { CardProps } from "./Card";
+export { CardHeader } from "./CardHeader";
+export type { CardHeaderProps } from "./CardHeader";
+export { CardTitle } from "./CardTitle";
+export type { CardTitleProps, CardTitleAs } from "./CardTitle";
+export { CardSubtitle } from "./CardSubtitle";
+export type { CardSubtitleProps } from "./CardSubtitle";
+export { CardActions } from "./CardActions";
+export type { CardActionsProps } from "./CardActions";
+export { CardBody } from "./CardBody";
+export type { CardBodyProps } from "./CardBody";

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

@@ -24,6 +24,17 @@ 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 Card } from "./components/Card/Card";
+export type { CardProps } from "./components/Card/Card";
+export { CardHeader } from "./components/Card/CardHeader";
+export type { CardHeaderProps } from "./components/Card/CardHeader";
+export { CardTitle } from "./components/Card/CardTitle";
+export type { CardTitleProps, CardTitleAs } from "./components/Card/CardTitle";
+export { CardSubtitle } from "./components/Card/CardSubtitle";
+export type { CardSubtitleProps } from "./components/Card/CardSubtitle";
+export { CardActions } from "./components/Card/CardActions";
+export type { CardActionsProps } from "./components/Card/CardActions";
+export { CardBody } from "./components/Card/CardBody";
+export type { CardBodyProps } from "./components/Card/CardBody";
 export { DialogHeader } from "./components/Dialog/DialogHeader";
 export type { DialogHeaderProps } from "./components/Dialog/DialogHeader";
 export { DialogFooter } from "./components/Dialog/DialogFooter";

package/package.json

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