Capa modal

Descripción general

link

Web

tanrei-modal-layer

clock_loader_40

SwiftUI

tanreiModalLayer

radio_button_unchecked

Jetpack Compose

TanreiModalLayer

radio_button_unchecked

Flutter

TanreiModalLayer

radio_button_unchecked

React Native

ModalLayer

radio_button_unchecked

Generado a partir de docs/status/status.json, specs/modal-layer.spec.json

Una capa modal alrededor de una tarjeta propia: ábrela con el botón

Exportar fotos

Hay 24 fotos listas para exportar.

Listo

Toda superficie modal tiene debajo la misma capa. Atenúa la ventana detrás de la superficie, de modo que la página se lee como apartada. Vuelve inerte todo lo que hay ahí: nada de lo que queda detrás puede pulsarse, recibir el foco ni ser leído por un lector de pantalla, y la página no se desplaza. Lleva el foco al interior de la superficie, lo mantiene ahí mientras está abierta y lo devuelve cuando se cierra. Y pide cerrarse cuando la persona pulsa Escape, usa la acción de retroceso de la plataforma o pulsa el velo.

La capa modal es esa capa, convertida en un componente propio. El diálogo, la hoja lateral y la hoja inferior cuando son modales, el panel de navegación modal, la vista previa de imágenes, el selector de fecha y hora modal y las vistas modales de la búsqueda se construyen todos con ella. Cada uno sigue sus reglas en lugar de tener unas propias.

Es un componente avanzado. Te lo encuentras de dos maneras:

• Para cambiar el estilo de todas las superficies modales a la vez. Los tokens de la capa, comp.modal-layer.*, son a los que apuntan los tokens de velo y de movimiento de cada uno de esos componentes. Defínelos en la capa de tu producto y todas las superficies modales cambian juntas: el color y la opacidad del velo, un desenfoque de lo que queda detrás y cuánto tarda la capa en aparecer y en irse.
• Para construir una superficie modal que Tanrei no tiene: una paleta de comandos, una vista que ocupa toda la ventana, un visor propio. Pon tu superficie dentro de la capa y se comportará como cualquier otra superficie modal de tu producto.

Para una decisión, usa el diálogo. Para un panel, usa la hoja lateral o la hoja inferior modales. Ya se dan un nombre, colocan sus acciones y ofrecen una salida.

En la web es <tanrei-modal-layer>. Las demás plataformas todavía no lo han implementado.

Uso

link

La capa es un componente controlado. Define open para mostrarla. Cuando la persona pide cerrarla, emite close con el motivo (escape, back o scrim) y sigue abierta: eres tú quien vuelve a poner open en false. Dale una label, que es el nombre que anuncia un lector de pantalla.

La capa no dibuja nada propio salvo el velo. Tu contenido conserva su propio color, su forma y su margen interior, y la capa lo centra en la ventana con su propio tamaño. Colócalo en otro sitio con los medios propios de la plataforma (en la web, ::part(container)).

<tanrei-button id="open-palette" variant="text">Comandos</tanrei-button>

<tanrei-modal-layer label="Comandos">
  <div class="palette">
    <!-- autofocus marca el foco inicial. Sin él, el foco va al contenedor de la capa. -->
    <input autofocus aria-label="Buscar comandos">
    <ul>…</ul>
  </div>
</tanrei-modal-layer>

<style>
  /* Coloca tú el contenedor: aquí, cerca de la parte superior de la ventana. */
  tanrei-modal-layer::part(container) { margin-block-start: 15vh; }
</style>

<script type="module">
  import '@tanrei/web/components/modal-layer';
  const layer = document.querySelector('tanrei-modal-layer');
  document.querySelector('#open-palette').addEventListener('click', () => (layer.open = true));
  // Escape, retroceso o una pulsación en el velo. La capa nunca se cierra sola.
  layer.addEventListener('close', (event) => {
    console.log(event.detail.reason); // 'escape', 'back' o 'scrim'
    layer.open = false;
  });
</script>

// Un componente avanzado —una pieza de la que se construyen otros— se importa desde la entrada advanced.
import { ModalLayer } from '@tanrei/react/advanced';

<ModalLayer open={open} label="Comandos" onClose={() => setOpen(false)}>
  <CommandPalette />
</ModalLayer>

Todavía no está implementado. La forma prevista es un modificador de vista: .tanreiModalLayer(isPresented:, accessibilityLabel:, onClose:) { … }.

Todavía no está implementado. La forma prevista es TanreiModalLayer(visible, onCloseRequest, contentDescription) { … }.

Todavía no está implementado. La forma prevista es TanreiModalLayer(open:, onClose:, semanticLabel:, child: …).

Todavía no está implementado. La forma prevista es <ModalLayer visible onClose accessibilityLabel>…</ModalLayer>.

Cambiar el estilo de todas las superficies modales

link

Un producto define los tokens de la capa en su archivo de capa, y todas las superficies modales lo siguen:

{
  "tokens": {
    "tanrei.comp.modal-layer.scrim.color": { "$value": "{tanrei.sys.color.scrim}" },
    "tanrei.comp.modal-layer.scrim.blur": { "$value": { "value": 8, "unit": "px" }, "reason": "Nuestras superficies modales esmerilan lo que queda detrás de ellas." }
  }
}

La opacidad del velo es el alfa de su color: cambia el color, o el rol scrim del sistema, para hacerlo más claro o más oscuro. Para diferenciar una sola superficie, define en su lugar el token propio de esa superficie (comp.dialog.scrim.color, comp.dialog.motion.enter-duration). Apunta al de la capa hasta que lo hagas.

Especificaciones

link

Anatomía

Parte	Descripción
1 scrim · opcional	The dim over the whole window behind the container, to every edge and under every system inset. It blocks presses and, while the layer is dismissible, a press on it asks the layer to close. Not drawn while scrim is false.
2 container	The box the content is in, placed in the window's safe area. It draws nothing of its own — no color, edge, shadow, shape or padding — takes focus when nothing in the content is marked for it, and is the modal dialog assistive technology reads.

Propiedades

Propiedad	Tipo	Valor predeterminado	Descripción
open	boolean	false	Whether the layer is presented. The product opens it, and closes it in answer to close (or from its content's own controls); on SwiftUI, where it is a binding, the layer writes false itself.
dismissible	boolean	true	Whether Escape, the platform's back and a press on the scrim ask the layer to close (MDL-6). Set it to false only when the person must finish with one of the content's own controls, and give the content one.
scrim	boolean	true	Whether the layer dims what lies behind its container. False for content that covers the whole window with a fill of its own (a full-window preview): the layer then draws nothing behind it and still blocks everything there (MDL-2).
label	string	""	Names the container for assistive technology ("Export photos"): the modal dialog's name. Never drawn. Required.

Slots

Slot	Descripción
default	The content: the surface the product presents modally (a panel, a card, a view over the whole window). The layer places its container (MDL-11) and draws, styles and sizes nothing of the content. A fixture's content string is plain text.

Eventos

Evento	Descripción
close	The layer asks to be closed: Escape, the platform's back or a press on the scrim. Carries which of these it was, named escape, back or scrim (in the platform's casing). Emitted only while dismissible is true.

Estados

Comportamiento

Requisitos en formato EARS. Cada implementación de plataforma se prueba contra estos identificadores. El texto de los requisitos se muestra tal como está en la especificación, en inglés.

ID	Requisito
MDL-1	WHEN open becomes true THE modal layer SHALL present its container above everything in its window — every region, every overlay not opened from inside it (MDL-9) and every modal layer opened before it (MDL-8) — and, WHILE scrim is true, SHALL draw its scrim over the whole window behind the container, to every edge and under every system inset, filled with comp.modal-layer.scrim.color (its alpha is the dim) and, WHILE comp.modal-layer.scrim.blur is above 0, with what lies behind it blurred by a Gaussian blur of that radius (the radius of CSS's blur()); WHERE the platform cannot blur what lies behind a window it SHALL draw the color alone. WHILE scrim is false it SHALL draw nothing behind the container and SHALL still block what is behind as MDL-2 says. A component built from the modal layer draws the scrim from its own scrim tokens, which alias these two (comp.dialog.scrim.color and comp.dialog.scrim.blur, and so on).
MDL-2	WHILE open is true THE modal layer SHALL make everything outside its container inert — not focusable, not pressable, hidden from assistive technology — and SHALL keep the content behind it from scrolling without moving it (where a scroll bar takes room, that room stays while the scroll is held), so that a press, a scroll or a key anywhere outside the container reaches nothing behind it; WHEN it closes THE modal layer SHALL restore what is behind to what it was before: its scroll position, and what was focusable, pressable and exposed.
MDL-3	WHEN open changes from false to true, and WHEN the layer is mounted with open true, THE modal layer SHALL move focus to the element in its content that the product marked for initial focus (the platform's own mark, named in the platform notes) or, without one, to the element the component built from it names (the navigation drawer's selected destination, NVD-19) or else to its container, so that assistive technology reads its name first and the next Tab reaches the first focusable element. Focus SHALL move when the layer opens, not when its motion ends.
MDL-4	WHILE open is true THE modal layer SHALL keep focus inside its container: Tab from the last focusable element in it SHALL move to the first, Shift+Tab from the first (or from the container itself) SHALL move to the last, the container SHALL keep focus WHILE nothing in it is focusable, and screen-reader navigation SHALL NOT leave it.
MDL-5	WHEN the layer closes THE modal layer SHALL return focus to the element that had it when the layer opened or, where that element no longer exists, cannot take focus or is inert, to the platform's default for a closed overlay; focus SHALL move when the layer closes, not when its motion ends.
MDL-6	WHILE dismissible is true and open is true, WHEN the user presses Escape, uses the platform's back (Android's back gesture or button, the iOS accessibility escape gesture) or presses the scrim — a press that starts and ends outside the container — THE modal layer SHALL emit close exactly once with the reason escape, back or scrim, and SHALL stay open until open becomes false: the product sets it from close (through the binding where open is one, SwiftUI), unless the component built from the modal layer closes itself as its own spec says (DLG-5, NVD-20). Escape SHALL reach the layer only after everything inside its container has heard it: a key an element inside takes (a field clearing its text, a menu closing) SHALL NOT also ask the layer to close. WHILE dismissible is false THE modal layer SHALL ignore these inputs and emit nothing, and a press on the scrim SHALL still reach nothing behind it.
MDL-7	WHEN the layer opens THE modal layer SHALL fade its scrim and its container in from transparent over comp.modal-layer.motion.enter-duration with comp.modal-layer.motion.enter-easing, and WHEN it closes SHALL fade both out over comp.modal-layer.motion.exit-duration with comp.modal-layer.motion.exit-easing, keeping them drawn until the fade ends. A component built from the modal layer SHALL fade the scrim in step with its own surface, over its own enter and exit motion, and moves its surface as its own spec says (a dialog grows, a sheet slides). The enter and exit tokens of a surface that takes the modal role (a dialog, a modal picker, an image preview) alias these four, so that one value sets the tempo of every such surface of a product; a sheet (a bottom sheet, a side sheet, a modal navigation drawer) takes the sheet role (tanrei.sys.motion.role.appear.sheet.enter and .exit) instead, so that one value sets the tempo of every sheet. WHERE motion is reduced THE modal layer SHALL fade without moving or growing anything, or SHALL appear and disappear at once WHERE the component built from it says so or on a platform whose reduced-motion setting removes every animation (Android's).
MDL-8	WHEN a modal layer opens while another is open THE modal layer SHALL stack above it with its own scrim, make the first one inert with the rest of the window, and WHEN it closes return focus to the element inside the first one that had it; Escape, the platform's back and a press on the scrim SHALL reach only the topmost layer.
MDL-9	WHEN an overlay that is not modal opens from an element inside the container — a menu, a tooltip, a popover, a select's list, a docked picker — THE modal layer SHALL let it be presented above the layer and operated while the rest of the window is inert, and SHALL NOT count a press inside it as a press on the scrim: the overlay belongs to the layer as POP-25 says.
MDL-10	THE modal layer SHALL expose its container as a modal dialog named by label, everything outside it being hidden (MDL-2); a component built from it names the dialog by its own headline or label and may expose it as an alert dialog (DLG-14). WHILE label is empty THE modal layer SHALL still open, and in debug builds SHALL report that it has no accessible name.
MDL-11	THE modal layer SHALL draw nothing of its own but the scrim: its container has no color, edge, shadow, shape or padding and hands its content no color or text style, so that plain text given as content takes what the window around it gives. It SHALL lay the container out at the size of its content, centred in the window's safe area and above the on-screen keyboard while one is shown, and never larger than that area, the content scrolling inside it where it is larger; the product places or sizes the container otherwise in the platform's own way (named in the platform notes). A component built from the modal layer places and draws its own surface (DLG-7, SSH-7, BSH-6, IMP-1).
MDL-12	THE modal layer SHALL take its layout direction from where it is used and SHALL have no direction setting of its own; it SHALL mirror nothing itself, and its content follows the direction.
MDL-13	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE modal layer SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on its dialog (MDL-10) — an id reference by the elements it names in the host's tree or a tree around it, a description after its own. WHILE label is not empty it is the dialog's name, over a name given so; WHILE label is empty, a name given so is the dialog's name and SHALL NOT be reported as having none in debug builds. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE modal layer SHALL take it off that element.

Correspondencia de nombres por plataforma

Paridad no significa API idénticas. Cada plataforma expresa el mismo contrato con su propio estilo.

Especificación	Web	SwiftUI	Jetpack Compose	Flutter	React Native
Componente	tanrei-modal-layer	tanreiModalLayer	TanreiModalLayer	TanreiModalLayer	ModalLayer
open · Propiedad	open	isPresented	visible	open	visible
dismissible · Propiedad	closedby	dismissible	dismissible	dismissible	dismissible
scrim · Propiedad	scrim	scrim	scrim	scrim	scrim
label · Propiedad	label	accessibilityLabel	contentDescription	semanticLabel	accessibilityLabel
close · Evento	close	onClose	onCloseRequest	onClose	onClose
Notas	dismissible is HTML's own closedby attribute, as on <tanrei-dialog> and <tanrei-bottom-sheet>: any (the default) or none. scrim is a boolean property that defaults to true; its attribute is the inverse no-scrim (an HTML boolean attribute cannot default to true). close is a CustomEvent whose detail.reason is escape, scrim or back (back when the native cancel arrives without an Escape key, as Android's back gesture sends it); the product sets open to false from it. The content is the default slot. The container is a native <dialog> in the shadow root opened with showModal(), in the top layer over ::backdrop, the scrim (backdrop-filter blurs what is behind it); it is the container part, which a product places or sizes with ::part(container) (MDL-11). The fade out (MDL-7) keeps the closed <dialog> in the top layer in every browser, as it does every Tanrei modal overlay: closing closes the modal <dialog> at once (focus goes back, nothing is inert any more) and shows it as a manual popover, inert and taking no pointer, marked data-tanrei-leaving, until its fade and its scrim's have finished. The autofocus attribute on a slotted element marks initial focus. Debug builds (import.meta.env.DEV or the package's dev export) report an empty label (MDL-10). Snapshot harness: a 640 × 640 viewport with a surface page, the layer opened by open; the screenshot is the viewport.	Planned: a view modifier, as .sheet is: .tanreiModalLayer(isPresented: Binding<Bool>, dismissible:, scrim:, accessibilityLabel:, onClose:, content:), presented as tanreiDialog is (on iOS .fullScreenCover with a clear presentation background and the system transition off; Tanrei draws the scrim and the fade; on macOS an overlay of the modified view with the modal trait). Closing writes false to isPresented and then calls onClose with the reason. Initial focus is .defaultFocus; Escape is .onKeyPress(.escape) and the escape gesture .accessibilityAction(.escape). The blur is a material behind the scrim where the radius is above 0. The container is placed with the content's own frame and alignment.	Planned: TanreiModalLayer(visible, onCloseRequest: (TanreiModalLayerCloseReason) -> Unit, dismissible, scrim, contentDescription, content), drawn in a Dialog window of its own (as TanreiDialog and the modal sheets are) with the window's own dim off and usePlatformDefaultWidth = false; the window traps focus, answers back and hides what is behind from TalkBack. The blur is the window's blur-behind radius on Android 12 and later, and none before (MDL-1). The caller sets visible to false from onCloseRequest. The container is placed with a Modifier on the content.	Planned: TanreiModalLayer(open:, onClose:, dismissible:, scrim:, semanticLabel:, child:), a controlled overlay in the Overlay over the page with a ModalBarrier drawn in the layer's color and a BackdropFilter for the blur, a FocusScope that traps focus, BlockSemantics behind it and a PopScope for back. The container is placed with the child's own Align.	Planned: <ModalLayer visible onClose dismissible scrim accessibilityLabel>{content}</ModalLayer>, presented in a transparent Modal with animationType="none", statusBarTranslucent and navigationBarTranslucent; onRequestClose (Android's back, and Escape on a hardware keyboard) is close with the reason back or escape. React Native cannot blur what is behind a window without a native module of its own, so the scrim is the color alone (MDL-1). The container is placed with the content's own style.

Tokens

Token	Alias de	Valor resuelto (claro)
--tanrei-comp-modal-layer-motion-enter-duration	sys.motion.role.appear.modal.enter	350ms
--tanrei-comp-modal-layer-motion-enter-easing	sys.motion.easing.enter	cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-modal-layer-motion-exit-duration	sys.motion.role.appear.modal.exit	300ms
--tanrei-comp-modal-layer-motion-exit-easing	sys.motion.easing.exit	cubic-bezier(0.3, 0, 1, 1)
--tanrei-comp-modal-layer-scrim-blur	—	0px
--tanrei-comp-modal-layer-scrim-color	sys.color.scrim	#000000 · 40%

Fixtures

Representaciones canónicas. Todas las plataformas capturan cada fixture con el mismo identificador para poder comparar los resultados.

open

open: true label: Export photos Dibujado por separado en una ventana de 640 × 640

no-scrim

open: true scrim: false label: Export photos Dibujado por separado en una ventana de 640 × 640

Generado a partir de specs/modal-layer.spec.json, tokens/comp/modal-layer.tokens.json, design/tokens/

Pautas

link

Qué hace la capa y qué te deja a ti

link

La capa	Tu contenido
Atenúa la ventana que hay detrás (o no dibuja nada, con scrim desactivado), hasta todos los bordes.	Su propio color, forma, sombra y margen interior. La capa no añade ninguno.
Vuelve inerte todo lo que hay detrás e impide que la página se desplace.	Su propio desplazamiento, cuando es más alto que la ventana.
Lleva el foco al interior, lo mantiene ahí y lo devuelve al cerrarse.	Marca el elemento que debe recibir el foco primero, si lo hay.
Pide cerrarse con Escape, con la acción de retroceso de la plataforma y con una pulsación en el velo.	Una salida propia: un botón Cerrar, Cancelar o Listo.
Centra el contenedor en la ventana con el tamaño de su contenido.	Dónde va en su lugar, si no es en el centro.

Sin el velo

link

Desactiva scrim para un contenido que cubre toda la ventana con un relleno propio, como un visor sobre un fondo oscuro. No queda nada que atenuar. La capa sigue bloqueando todo lo que hay detrás, y una pulsación fuera de tu contenido sigue pidiendo que se cierre.

Recomendado

link

• Da nombre a la capa con label. Un lector de pantalla lo anuncia cuando el foco entra.
• Pon una salida visible en el contenido. No todo el mundo conoce Escape, y la acción de retroceso no existe en todos los dispositivos.
• Cambia las superficies modales de un producto mediante comp.modal-layer.*, para que sigan siendo parecidas.

Evita

link

• No construyas un diálogo ni una hoja con la capa sin nada más. Usa el diálogo o la hoja, que ya ofrecen un titular, acciones y su lugar.
• No desactives dismissible sin una salida en el contenido. La persona no tendría forma de salir.
• No la uses para algo que no deba bloquear la página. Un popover, un menú o un snackbar dejan la página utilizable.

Accesibilidad

link

Rol

dialog

Etiquetado

The container is a modal dialog named by label; everything outside it is hidden from assistive technology while the layer is open. The scrim is not exposed. A component built from the modal layer names the dialog by its own headline or label, and the dialog may be an alert dialog.

Objetivo mínimo

El área de pulsación cumple el tamaño mínimo de objetivo aunque el tamaño visual sea menor. minimum 32px · pointer 44px · spacing 8px · touch 48px

Teclado

Teclas	Acción
Tab / Shift+Tab	Move focus through the focusable elements in the container, wrapping from the last to the first and back; focus never leaves the layer.
Escape	Asks the layer to close (close, reason escape) while dismissible is true; with stacked layers, only the topmost. A key an element inside takes first goes no further.

Notas

• The modal layer is what every modal surface of Tanrei has in common: the dialog, the modal side sheet, the modal bottom sheet, the modal navigation drawer, the image preview, the modal date-time picker and the search's modal views are each built from it and cite its rules. Restyle their scrim and their tempo once, through comp.modal-layer.*.
• Use it alone for a modal surface Tanrei does not have — a command palette, a takeover over the whole window, a viewer of your own. For a decision use the Dialog; for a panel, the modal side sheet or bottom sheet: they already hold focus, name themselves and place their actions.
• Give the content a way out of its own (a Close, Cancel or Done button). Escape, back and the scrim are not found by everyone, and with dismissible false they do nothing.
• The layer has no target of its own; what the product puts in it meets the minimum target itself.
• Inert, focus moved in, kept and given back: the WAI-ARIA Authoring Practices' modal dialog pattern and HTML's modal dialog. The web presents the container with a modal <dialog> element (showModal gives the top layer and inertness); the other platforms present it in a window or a route of its own with the system's dim switched off, so that every platform draws the layer's own scrim.

Generado a partir de specs/modal-layer.spec.json, tokens/sys/measure.tokens.json

De qué se encarga el componente

link

• El contenedor es un diálogo modal, con label como nombre. Mientras está abierto, todo lo que queda fuera está oculto para la tecnología de apoyo.
• El foco entra en la capa cuando se abre, incluso cuando se escribe ya abierta. Va al elemento que marcaste o, si no, al contenedor, de modo que el nombre se lee primero.
• Tab y Mayús+Tab dan la vuelta dentro de la capa. El foco nunca llega a la página que queda detrás.
• Al cerrarse, el foco vuelve adonde estaba. Si ese elemento ya no existe, el foco va adonde lo pone la plataforma.
• Escape solo pide cerrar cuando todo lo que hay dentro ya lo ha recibido. Un campo que borra su texto con Escape, o un menú que se cierra, mantiene abierta la capa.
• Una capa abierta desde dentro de otra se apila encima de ella. Solo la que está más arriba responde a Escape, a la acción de retroceso y a su velo.

Qué debes hacer tú

link

• Da una label que diga para qué sirve la superficie.
• Marca el primer elemento que debe recibir el foco cuando un formulario o un campo de búsqueda sea el motivo de la superficie.
• Da al contenido un control visible que lo cierre, y deja dismissible activado salvo que ese control exista.