Mini Widgets
Custom Layout
Layout en React
Organiza widgets y páginas completas horizontal o verticalmente. Empieza las apps nuevas con Arc Layout; HTML puede seguir siendo el host y un límite semántico. Un host solo define la altura del viewport, sin tener que recrear el layout de la página con CSS Grid o Flexbox.
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>.
Widget-First-App-Shell: AI Defaults
Para una barra lateral, una cabecera y el contenido, usa la plantilla React completa, incluida también en el paquete como examples/blueprints/blueprint-app-shell.tsx.
- Host: una altura definida, como
100dvh; layouts de shell anidados:height: '100%'. - Bloques verticales: cabecera
height: 'auto', contenido restanteheight: 'fraction'. - Scroll: coloca un Layout con
height: '100%'yscrollSettings: { scrollY: true }en el bloque restante. - Bloques horizontales: ancho de barra lateral fijo/automático, región principal
width: 'fraction'. - Usa
min-width:0;min-height:0;en los bloques limitados; cambia la dirección responsiva y los tamaños a la vez. - Usa
fractionpara la altura del bloque, no para la altura del Layout interior. La región padre debe tener una altura definida.
Ejemplo completo
import {
ArcWidgetBadge,
ArcWidgetInput,
ArcWidgetLayout,
} from '@arcrider/arcwidgets-react';
const row = (number: string, title: string) => ({ value: ( <ArcWidgetLayout data={{ direction: 'horizontal', gap: '12px', height: '48px', blocks: [ { width: '52px', value: ( <ArcWidgetBadge data={{ value: number, singleColor: '#3f3f46', borderRadius: '6px', paddingX: '8px', paddingY: '4px', }} /> ), }, { width: 'fraction', value: ( <ArcWidgetInput data={{ type: 'number', labelSettings: { title }, numpad: { suffix: '€' }, }} /> ), }, ], }} /> ), });
export default function Example() { return ( <ArcWidgetLayout data={{ direction: 'vertical', gap: '8px', width: '420px', blocks: [row('1.1', 'Inspection'), row('1.2', 'Travel')], }} /> ); }</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 ArcWidgetLayoutData. 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 en un layout clickable fuera de sus bloques. Los clics en los bloques nunca llegan a él.
onClick?: () => void;
onBlockClick
Se dispara al hacer clic en un bloque clickable. blockIndex es el índice de base cero en data.blocks.
onBlockClick?: (blockIndex: number) => 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.
direction
Dirección en la que se apilan los bloques. Establécela siempre de forma explícita. Valor por defecto: vertical.
Tipo: 'horizontal' | 'vertical'.
alignX
Colocación horizontal de los bloques. between solo funciona con direction: 'horizontal', stretch solo con 'vertical'. Valor por defecto: center.
Tipo: 'left' | 'center' | 'right' | 'between' | 'stretch'.
alignY
Colocación vertical de los bloques. between solo funciona con direction: 'vertical', stretch solo con 'horizontal'. Valor por defecto: center.
Tipo: 'top' | 'center' | 'bottom' | 'between' | 'stretch'.
width
Ancho del layout. 'fraction' ocupa el ancho restante del bloque circundante; cualquier otro valor es CSS. Valor por defecto: 100%.
Tipo: 'fraction' | (string & {}).
height
Altura del layout como CSS, p. ej. "320px". Usa un valor definido para shells con scroll y 'auto' para layouts que se ajustan al contenido. Los valores porcentuales necesitan un contenedor padre con altura fija. Valor por defecto: 100%.
Tipo: string.
gap
Espacio entre bloques. Valor por defecto: 2px. Un valor negativo, por ejemplo '-8px', superpone los bloques en esa medida. Los bloques con width: 'fraction' (o height: 'fraction' en una columna) se estiran sobre la superposición, por eso los bloques superpuestos necesitan un tamaño propio.
Tipo: string.
overlapOrder
Qué bloque queda encima cuando gap es negativo: 'end' el último bloque, 'start' el primero (izquierda en una fila, arriba en una columna). El bloque bajo el puntero siempre pasa al frente. Valor por defecto: end.
Tipo: 'start' | 'end'.
backgroundColor
Color de fondo.
Tipo: string.
minWidth
Ancho mínimo del layout como CSS, p. ej. "320px". El layout nunca se hace más estrecho; el área circundante se desplaza o recorta. Los bloques también aceptan minWidth.
Tipo: string.
maxWidth
Ancho máximo del layout como CSS, p. ej. "1000px". Un layout con maxWidth se centra horizontalmente en su contenedor, así obtienes una columna de página sin CSS adicional. Los bloques también aceptan maxWidth (p. ej. "100%" para mantener un hijo ancho dentro del bloque); un bloque se posiciona con el alignX de su layout.
Tipo: string.
border
Borde y radio de esquina del contenedor del layout: color, width, style, radius y sides. La línea se dibuja en cuanto se define color, width, style o sides; radius por sí solo solo redondea las esquinas. El radio no recorta a los hijos, así que da el mismo radio a un bloque interior con color. Los bloques aceptan el mismo objeto border.
Tipo: ArcWidgetLayoutBorder.
paddingX
Espaciado interno a izquierda y derecha.
Tipo: string.
paddingY
Espaciado interno arriba y abajo.
Tipo: string.
lineHeight
Altura de línea que heredan los bloques.
Tipo: string.
scrollSettings
Scroll del contenedor del layout (scrollX, scrollY). Las barras de desplazamiento permanecen ocultas; scrollY necesita una height definida.
Tipo: ArcWidgetLayoutScrollSettings.
styles
Declaraciones CSS en bruto que se aplican al final al contenedor del layout, p. ej. 'padding: 8px; color: #333'.
Tipo: string.
clickable
true muestra un cursor de puntero y dispara onClick para clics fuera de los bloques. Valor por defecto: false.
Tipo: boolean.
blocks
Filas (vertical) o columnas (horizontal) del layout. Cada bloque tiene su propio tamaño, alineación (alignX, alignY), colores, styles y contenido en value; consulta ArcWidgetLayoutBlock.
Tipo: ArcWidgetLayoutBlock[].
Comportamiento y límites
- Establece
direction de forma explícita. fraction distribuye el espacio restante en el eje correspondiente; una altura de 100% necesita un contenedor padre con límite definido.
- Cada bloque es un contenedor flex horizontal. Posiciona su contenido con
blocks[].alignX (left, center, right; por defecto left) y blocks[].alignY (top, center, bottom, stretch; por defecto center). text-align en blocks[].styles no puede centrar el contenido.
blocks[].value admite JSX. Vincula los eventos de componentes anidados directamente a sus props de callback.
- Para clics en el layout o en un bloque debe establecerse
clickable: true en el objeto correspondiente. onBlockClick recibe el índice en blocks.
- Para layouts de página completa, da al elemento de la app circundante una altura definida, como
100dvh.
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 ArcWidgetLayoutBorder {
color?: string;
width?: string;
style?: 'solid' | 'dashed' | 'dotted' | 'double';
radius?: string;
sides?: Array<'top' | 'right' | 'bottom' | 'left'>;
}
export interface ArcWidgetLayoutBlock { value?: ArcWidgetSlot; width?: 'fraction' | (string & {}); minWidth?: string; maxWidth?: string; height?: 'fraction' | (string & {}); alignX?: 'left' | 'center' | 'right'; alignY?: 'top' | 'center' | 'bottom' | 'stretch'; paddingX?: string; paddingY?: string; backgroundColor?: string; border?: ArcWidgetLayoutBorder; color?: string; backgroundImage?: string; backgroundSize?: string; backgroundPosition?: string; lineHeight?: string; styles?: string; clickable?: boolean; blockId?: string; }
export interface ArcWidgetLayoutScrollSettings { scrollX?: boolean; scrollY?: boolean; }
export interface ArcWidgetLayoutData { direction?: 'horizontal' | 'vertical'; alignX?: 'left' | 'center' | 'right' | 'between' | 'stretch'; alignY?: 'top' | 'center' | 'bottom' | 'between' | 'stretch'; width?: 'fraction' | (string & {}); minWidth?: string; maxWidth?: string; height?: string; gap?: string; overlapOrder?: 'start' | 'end'; paddingX?: string; paddingY?: string; backgroundColor?: string; border?: ArcWidgetLayoutBorder; lineHeight?: string; scrollSettings?: ArcWidgetLayoutScrollSettings; styles?: string; clickable?: boolean; blocks?: ArcWidgetLayoutBlock[]; }
export interface ArcWidgetLayoutProps extends ArcReactWidgetProps<ArcWidgetLayoutData> { onClick?: () => void; onBlockClick?: (blockIndex: number) => void; }</code></pre>