Mini Widgets
Button
Button en React
Dispara una acción y muestra un estado de carga durante un proceso asíncrono.
Referencia para @arcrider/arcwidgets-react@0.1.0-alpha.5. <a href="/docs/react/intro/setup-react">Instalación</a> · <a href="/docs/react/intro/react-components">Todos los componentes</a>.
Ejemplo completo
Solo se define title; todo lo demás es el valor por defecto: fondo negro, texto blanco en negrita, esquinas redondeadas y un hover más claro.
import { ArcWidgetButton, ArcWidgetLayout } from '@arcrider/arcwidgets-react';
export default function Example() { // Only required fields are set on the button; everything else is the widget default. // The Layout fills its surroundings and centers the button. return ( <ArcWidgetLayout data={{ direction: 'vertical', alignX: 'center', alignY: 'center', width: '100%', height: '100%', backgroundColor: '#F8FAFC', border: { radius: '12px' }, blocks: [ { width: 'auto', value: <ArcWidgetButton data={{ title: 'Save' }} /> }, ], }} /> ); }</code></pre>
Props del componente
id
ID de DOM opcional. No es necesario en el uso normal; se genera automáticamente si se omite.
data
Configuración de tipo ArcWidgetButtonData. Pasa los cambios como objetos nuevos; gestiona los datos de negocio y la selección en el estado de React.
onAction
Fallback opcional (type: string, ...args: unknown[]) => unknown. El callback concreto tiene prioridad. Detalles: <a href="/docs/react/patterns/react-state-events">Estado y eventos</a>.
onClick
Se dispara al hacer clic. Devuelve una promesa para que loading siga visible hasta que se resuelva.
onClick?: () => void | Promise<void>;
Configuración
Los siguientes campos pertenecen a data. Los tamaños se indican como strings, los números y valores de tiempo según su tipo respectivo.
title
Etiqueta en negrita; como slot también es posible con JSX. Usa '' para botones solo con icono.
Tipo: ArcWidgetSlot.
subtitle
Segunda etiqueta más pequeña junto al título.
Tipo: ArcWidgetSlot.
icon
Icono junto al título, p. ej. un ArcWidgetIcon.
Tipo: ArcWidgetSlot.
prefix
Contenido fijado al borde inicial, antes del icono y el título.
Tipo: ArcWidgetSlot.
suffix
Contenido fijado al borde final; necesita un width mayor que el contenido.
Tipo: ArcWidgetSlot.
alignX
Alineación horizontal del icono y el título. Con prefix o suffix se aplica al espacio entre ambos. Valor por defecto: center.
Tipo: 'left' | 'center' | 'right'.
alignY
Alineación vertical del contenido cuando height es mayor que el contenido. Valor por defecto: center.
Tipo: 'top' | 'center' | 'bottom'.
iconPosition
Posición del icono en relación con el título. Valor por defecto: left.
Tipo: 'left' | 'right' | 'top' | 'bottom'.
gap
Espacio entre prefix, icono, título, badge y suffix. Valor por defecto: 0 entre slots, 5px entre icono y título.
Tipo: string.
paddingX
Espaciado interno a izquierda y derecha. Valor por defecto: 0.8em.
Tipo: string.
paddingY
Espaciado interno arriba y abajo. Valor por defecto: 0.5em.
Tipo: string.
width
Ancho del botón. Valor por defecto: fit-content.
Tipo: string.
height
Alto del botón; 'auto' mantiene la altura del contenido. Valor por defecto: auto.
Tipo: string.
borderRadius
Redondeo de las esquinas. Valor por defecto: 0.6em.
Tipo: string.
borderColor
Color del borde de 1px. Valor por defecto: transparente, así el borde toma el color de fondo.
Tipo: string.
backgroundColor
Color de fondo. Valor por defecto: #18181B. Con un color claro, define también fontColor.
Tipo: string.
fontColor
Color del texto; el indicador de carga lo sigue. Valor por defecto: #ffffff.
Tipo: string.
fontSize
Tamaño de fuente como valor CSS; el subtítulo usa el 80 % de este valor. Valor por defecto: 13px.
Tipo: string.
hoverActions
Colores mientras el puntero está sobre el botón (fontColor, iconColor, backgroundColor, borderColor), más la duración de la transición (animation, p. ej. "0.2s"). Sin ellos, solo el aspecto por defecto se aclara en hover; un backgroundColor propio mantiene su color.
Tipo: ArcWidgetButtonHoverActions.
showBadge
Muestra el badge. Valor por defecto: false.
Tipo: boolean.
badgeTitle
Contenido del badge, p. ej. un contador.
Tipo: ArcWidgetSlot.
badgeColor
Color del texto del badge. Valor por defecto: #ffffff.
Tipo: string.
badgeBackground
Fondo del badge. Valor por defecto: #e9595d.
Tipo: string.
badgeBorderColor
Color del borde del badge. Valor por defecto: #ffffff.
Tipo: string.
badgePosition
inside coloca el badge después del título; outside lo fija en la esquina superior derecha. Valor por defecto: inside.
Tipo: 'inside' | 'outside'.
badgeGap
Espacio antes de un badge interior. Valor por defecto: 6px si gap no está establecido; si no, gap.
Tipo: string.
loading
Estado de carga mientras la promesa de onClick está pendiente, activado con show: true. Muestra un indicador en el botón o, con overlay, una tarjeta centrada. Oculta contenidos concretos con hide (icon también admite 'auto'). El indicador toma el color del texto y crece con el tamaño de fuente.
Tipo: ArcWidgetButtonLoading.
Navigation: AI Defaults
Para la navegación y las acciones con etiqueta, usa alignX: 'left', iconPosition: 'left' y gap: '8px'. Los valores por defecto existentes del runtime no cambian. alignY controla la alineación vertical; paddingX/paddingY, el espaciado interno.
Usa ArcWidgetIcon con iconSet: 'phosphor' en el slot del icono. Envuelve los iconos decorativos con aria-hidden y pointerEvents: 'none' para que no intercepten los clics del botón. La plantilla React muestra el patrón completo.
Comportamiento y límites
onClick puede devolver una promesa. Con loading.show: true, el estado de carga permanece activo hasta el final de este proceso.
- Captura los errores de guardado en tu callback y muéstralos en tu propio estado. Un indicador de carga no sustituye un mensaje de éxito o error.
Los campos ArcWidgetSlot admitidos permiten elementos JSX individuales, texto o descriptores de widget. Pasa texto externo como texto JSX; los strings HTML se interpretan como HTML. <a href="/docs/react/patterns/nested-widget-descriptors">Combinar contenidos</a>.
Tipos de datos
Estos tipos relacionados con el widget se exportan desde el paquete. También están disponibles tipos comunes como ArcWidgetSlot, ArcWidgetStyles y ArcReactWidgetProps. Los objetos de configuración son cerrados, por lo que una clave mal escrita o no admitida se notifica como error de tipo.
export interface ArcWidgetButtonHoverActions {
fontColor?: string;
iconColor?: string;
backgroundColor?: string;
borderColor?: string;
animation?: string;
}
export interface ArcWidgetButtonLoadingIndicator { type?: 'dots' | 'spinner' | 'pulse'; color?: string; width?: string; height?: string; }
export interface ArcWidgetButtonLoadingHide { icon?: boolean | 'auto'; title?: boolean; subtitle?: boolean; badge?: boolean; prefix?: boolean; suffix?: boolean; }
export interface ArcWidgetButtonLoadingStyles { fontColor?: string; iconColor?: string; backgroundColor?: string; borderColor?: string; }
export interface ArcWidgetButtonOverlayText { value: string; styles?: string; }
export interface ArcWidgetButtonOverlaySequence { after?: number; when?: boolean; priority?: number; title?: string | ArcWidgetButtonOverlayText; message?: string | ArcWidgetButtonOverlayText; indicator?: ArcWidgetButtonLoadingIndicator; }
export interface ArcWidgetButtonOverlay { title?: string | ArcWidgetButtonOverlayText; message?: string | ArcWidgetButtonOverlayText; sequences?: ArcWidgetButtonOverlaySequence[]; indicator?: ArcWidgetButtonLoadingIndicator; width?: string; height?: string; backgroundColor?: string; }
export interface ArcWidgetButtonLoading { show?: boolean; indicator?: ArcWidgetButtonLoadingIndicator; hideOnFinish?: boolean; minDuration?: number; position?: 'left' | 'right' | 'prefix' | 'suffix'; hideTitle?: boolean; hide?: ArcWidgetButtonLoadingHide; styles?: 'hover' | 'default' | ArcWidgetButtonLoadingStyles; overlay?: true | ArcWidgetButtonOverlay; }
export interface ArcWidgetButtonData { title?: ArcWidgetSlot; subtitle?: ArcWidgetSlot; icon?: ArcWidgetSlot; prefix?: ArcWidgetSlot; suffix?: ArcWidgetSlot; alignX?: 'left' | 'center' | 'right'; alignY?: 'top' | 'center' | 'bottom'; iconPosition?: 'left' | 'right' | 'top' | 'bottom'; gap?: string; paddingX?: string; paddingY?: string; width?: string; height?: string; borderRadius?: string; borderColor?: string; backgroundColor?: string; fontColor?: string; fontSize?: string; hoverActions?: ArcWidgetButtonHoverActions; showBadge?: boolean; badgeTitle?: ArcWidgetSlot; badgeColor?: string; badgeBackground?: string; badgeBorderColor?: string; badgePosition?: 'inside' | 'outside'; badgeGap?: string; loading?: ArcWidgetButtonLoading; }
export interface ArcWidgetButtonProps extends ArcReactWidgetProps<ArcWidgetButtonData> { onClick?: () => void | Promise<void>; }</code></pre>