@capgo/capacitor-sheets

Bottom sheets, drawers, diálogos y overlays agnósticos al framework, optimizados para los WebViews de Capacitor.

Agnóstico al framework

Usa elementos personalizados basados en estándares directamente o utiliza helpers de configuración para React, Vue, Angular, Svelte y Solid.

Listo para Capacitor

Respeta las safe areas, el movimiento del teclado, los gestos nativos de los bordes y el ajuste del theme-color de la WebView desde la capa web.

Cada forma de sheet

Crea bottom sheets, drawers laterales, top sheets, diálogos centrados, toasts, sheets independientes, cards, páginas y lightboxes.

CSS moderno

Define detents con em, rem, unidades de viewport, calc(), y variables CSS mientras el tamaño por defecto se mantiene em basado.

Soporte de plataformas

Plataforma	Soporte	Notas
iOS	Capa web	Elementos personalizados dentro de WKWebView
Android	Capa web	Elementos personalizados dentro de Android WebView
Web	Sí	Mismos componentes para builds web de Capacitor

Cuándo usarlo

@capgo/capacitor-sheets es para apps Capacitor que necesitan overlays móviles de alta calidad sin adoptar un framework de UI concreto. Se distribuye como custom elements, así que el paquete core no tiene ninguna dependencia de runtime de React, Vue, Angular, Svelte o Solid.

Úsalo cuando necesites:

bottom sheets con uno o más detents
sidebars a izquierda o derecha y top sheets
diálogos centrados, lightboxes, cards y overlays tipo toast
sheets persistentes que mantienen interactiva la app de fondo
overlays de pantalla completa que entran desde un borde
efectos de stack, profundidad y parallax según el progreso del sheet
helpers de scroll que exponen valores de progreso y distancia
layout seguro para Capacitor ante notches, home indicators, cutouts de Android y teclados de software

Cobertura de casos de uso

Caso de uso	Patrón de Capgo Sheets
Sheet largo	`cap-sheet` con desplazamiento natural del contenido o `cap-scroll`
Sheet con Detent	`detents="18em 32em"` además de `stepTo()` o un disparador por pasos
Barra lateral	`content-placement="left"` o `content-placement="right"`
Bottom Sheet	default `content-placement="bottom"`
Sheet con teclado	`native-focus-scroll-prevention` y manejo de offset de viewport visual
Toast	`inert-outside="false"`, `focus-trap="false"`, y sin cierre por clic externo
Sheet despegada	`cap-sheet-special-wrapper` más márgenes y radio personalizados
Página desde abajo	contenido de bottom sheet a pantalla completa
Hoja superior	`content-placement="top"`
Sheet con apilamiento	`cap-sheet-stack` con variables de profundidad
Sheet con profundidad	`cap-sheet-outlet` y transformaciones basadas en el progreso
Página parallax	`cap-sheet-outlet` con `cap-scroll` progreso
Página	contenido de pantalla completa que entra desde un borde
Lightbox	`content-placement="center"` con backdrop y contenido multimedia
Sheet persistente con detent	`default-presented`, `swipe-dismissal="false"`, y `inert-outside="false"`
Card	contenido de hoja compacto y centrado

Núcleo de API

<cap-sheet> gestiona el estado de presentación, detents, ubicación, gestos, accesibilidad y eventos.
<cap-sheet-trigger> declara las acciones present, dismiss, toggle y detent-step.
<cap-sheet-view> posiciona la superposición y aplica los offsets de área segura y teclado.
<cap-sheet-backdrop> renderiza un fondo sincronizado con el progreso.
<cap-sheet-content> renderiza la superficie de la hoja.
<cap-sheet-handle> proporciona controles de detent por arrastre y teclado.
<cap-sheet-stack> coordina las hojas apiladas.
<cap-sheet-outlet> expone el progreso de la hoja para efectos de página, profundidad y parallax.
<cap-scroll> y <cap-scroll-content> expone helpers de progreso y distancia de scroll.
setupSheet(element, options?) configura una hoja desde efectos del framework o hooks de ciclo de vida.

Modelo de layout de Capacitor

El viewport de la sheet por defecto lee env(safe-area-inset-*) y estilo Capacitor --safe-area-inset-* y luego aplica los bordes seleccionados como padding alrededor del overlay. safe-area="auto" protege todos los bordes; usa safe-area="bottom left right" o safe-area="none" cuando un caso de uso requiere un comportamiento diferente.

El manejo del teclado está habilitado por defecto. La sheet escucha visualViewport eventos de redimensionado y desplazamiento, añade un desplazamiento de teclado a la viewport y enfoca los controles con preventScroll para que las entradas sigan visibles sobre el teclado de software.

El paquete se ejecuta en la capa web. No renderiza bottom sheets nativas de UIKit o Android, por lo que tu app mantiene el control total del estilo mientras respeta las restricciones de WebView que importan en Capacitor.

Demos y Playgrounds

Las demos animadas en WebP para cada caso de uso soportado están en el README del repositorio. Los ejemplos también están disponibles como playgrounds de StackBlitz:

Sheet largo	Detents

Sidebar	Lightbox

Continúa desde @capgo/capacitor-sheets

Si estás usando @capgo/capacitor-sheets para planificar el trabajo con plugins nativos, conéctalo con Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, Alternativas a plugins de Ionic Enterprise para el flujo de trabajo en Alternativas a plugins de Ionic Enterprise, y Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds.