# WidgetCard

> El widget de iCloud Home armado de una —ícono, título, subtítulo, acción, filas y «…»—, translúcido sobre el wallpaper; y la card promocional de Ajustes.

```tsx
import { PromoCard, PromoCardLink, WidgetCard } from "sebs7n-ui/widget-card"
```

Sin `"use client"`: sirve en un Server Component.

## Ejemplos

### El widget

Todo de una: ícono de la app, título, subtítulo y la acción arriba; filas con separadores interiores y el «…» abajo. Son las partes de `Card`, ya armadas.

```tsx
import { CardRow } from "sebs7n-ui/card"
import { WidgetCard } from "sebs7n-ui/widget-card"

function Basico() {
  return (
    <WidgetCard action={Nueva} className="w-full max-w-sm" icon={IconoFacturas} more={Mas} subtitle="Septiembre · 3 por cobrar" title="Facturas">
      <CardRow description="Factura 0012" title="Acme S.A." trailing="30/09" />
      <CardRow description="Factura 0013" title="Nube Digital" trailing="28/09" />
      <CardRow description="Factura 0014" title="Estudio Ruiz" trailing="21/09" />
    </WidgetCard>
  )
}
```

### Sobre el wallpaper

Adentro de `AppShell ambient` (acá, una caja con `bg-ambient` y `data-ambient`) el cuerpo pasa a translúcido con blur y la franja a una capa encima, sin blur propio: el widget de Home de iCloud. Grande, con dos columnas. La caja lleva `[contain:paint]` para que el wallpaper, que es fijo a la ventana, quede adentro de ella.

```tsx
import { CardRow } from "sebs7n-ui/card"
import { WidgetCard } from "sebs7n-ui/widget-card"

function SobreElWallpaper() {
  return (
    <div className="w-full rounded-surface bg-ambient p-6 [contain:paint] sm:p-8" data-ambient="">
      <WidgetCard action={Nueva} className="w-full" columns={2} icon={IconoFacturas} more={Mas} subtitle="Últimos 7 días" title="Cobranzas">
        <CardRow description="Transferencia" title="Acme S.A." trailing="$ 128.400" />
        <CardRow description="Tarjeta" title="Nube Digital" trailing="$ 96.000" />
        <CardRow description="Transferencia" title="Estudio Ruiz" trailing="$ 41.200" />
        <CardRow description="Efectivo" title="Taller Sur" trailing="$ 12.800" />
      </WidgetCard>
    </div>
  )
}
```

### La card promocional

La de Ajustes de iCloud: degradado de marca, título grande, links con chevron y el chip translúcido. El texto es el color de contraste de la marca, así que anda con cualquier brand.

```tsx
import { PromoCard, PromoCardLink } from "sebs7n-ui/widget-card"

function Promocional() {
  return (
    <PromoCard chip="12 usuarios" className="w-full max-w-md" title="Plan Pro">
      <PromoCardLink href="#plan">Plan</PromoCardLink>
      <PromoCardLink href="#facturacion">Facturación</PromoCardLink>
      <PromoCardLink href="#beneficios">Beneficios</PromoCardLink>
    </PromoCard>
  )
}
```

## Props

### PromoCard

Hereda las props de `<div>`.

| Prop | Tipo | Por defecto | Descripción |
|---|---|---|---|
| `title` * | `React.ReactNode` | — | El título grande (48/700). Es el nombre de la región. |
| `chip` | `React.ReactNode` | — | El chip translúcido de abajo a la derecha: el plan, el espacio. |
| `className` | `string` | — | Se fusiona con las clases del componente vía `cn()` (tailwind-merge): lo que pongas gana. |

`*` obligatoria.

### PromoCardLink

Hereda las props de `<a>`.

| Prop | Tipo | Por defecto | Descripción |
|---|---|---|---|
| `render` | `RenderElement` | — | El elemento del link (el `Link` de Next). Recibe el contenido y las clases. |
| `className` | `string` | — | Se fusiona con las clases del componente vía `cn()` (tailwind-merge): lo que pongas gana. |

### WidgetCard

Hereda las props de `<div>`.

| Prop | Tipo | Por defecto | Descripción |
|---|---|---|---|
| `title` * | `React.ReactNode` | — | El título (21/600). Es el nombre de la región. |
| `action` | `React.ReactNode` | — | La acción de arriba a la derecha: un botón de ícono. |
| `columns` | `1 \| 2` | — | `2` reparte las filas en dos columnas con una regla vertical. |
| `filter` | `React.ReactNode` | — | Abajo a la derecha: un filtro. |
| `icon` | `React.ReactNode` | — | El ícono de la app, en una caja de 40. Decorativo. |
| `more` | `React.ReactNode` | — | El «…» de abajo a la izquierda: un botón de ícono o el disparador de un menú. |
| `subtitle` | `React.ReactNode` | — | Debajo del título, en 14 gris. |
| `className` | `string` | — | Se fusiona con las clases del componente vía `cn()` (tailwind-merge): lo que pongas gana. |

`*` obligatoria.

## Teclado

| Tecla | Qué hace |
|---|---|
| Tab | Recorre la acción de arriba, lo interactivo de las filas y el «…». La card no es una parada. |

## Accesibilidad

- `WidgetCard` y `PromoCard` son **regiones nombradas por su título** (`role="region"` + `aria-labelledby`): el lector las lista entre las regiones de la página.
- El ícono de la app es decorativo: el título ya nombra el widget.
- La acción y el «…» son botones de ícono: **necesitan `aria-label`** («Nueva factura», «Ver todas las facturas»).
- `PromoCard` escribe en el color de contraste de la marca (el par del botón `accent`) sobre el acento y un tono un cuarto más oscuro: el 17/600 de los links pasa 4,5:1 con cualquier brand. El chevron es decorativo.
- Con menos transparencia o más contraste pedidos, el widget es opaco (lo resuelve `material-translucent-body`).

## Reglas de uso

- **`WidgetCard` para un resumen que lleva a una app**: las últimas facturas, lo cobrado en la semana. Si necesitás otra forma, armala con las partes de `Card`.
- **Sobre el wallpaper** (`AppShell ambient`) la franja y el cuerpo pasan solos a translúcidos; en cualquier otro lado son opacos. No lo fuerces con clases.
- Filas con `CardRow` (`title`, `description`, `trailing`, las mismas props que `ListRow`); `columns={2}` para el widget grande.
- La acción de arriba es **una**: la principal («redactar», «nueva»). El resto va en el menú del «…».
- **`PromoCard` para una sola cosa por pantalla**: el plan de la cuenta, una función nueva. Dos promocionales juntas se pelean.
- `PromoCardLink` con `render` para el `Link` de la app.

## Relacionados

[card](/docs/components/card.md) · [list-row](/docs/components/list-row.md) · [app-shell](/docs/components/app-shell.md)