Configuración: recuadros de aviso

#Estilos de aviso

La propiedad calloutStyles declara los estilos de caja con nombre que el documento aplica mediante un contenedor :::callout{type="…"} — notas, consejos, advertencias, objetivos de aprendizaje, cualquier contenido separado del texto corrido en una caja tintada o con borde. Por defecto se incluye un estilo neutro, note (fondo gris claro, sin borde, sin franja, sin icono, sin título), de modo que :::callout funciona sin configuración alguna; declarar calloutStyles sustituye esa lista por defecto.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Nota' },
    {
      id: 'objectives',
      name: 'Objetivos de aprendizaje',
      title: 'Objetivos',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Advertencia',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describir las partes de la linterna.
- Recortar la mecha al anochecer.
:::
 
:::callout{type="warning" title="No toques la lente"}
El cristal sigue caliente una hora después de apagar la llama.
:::

#El contenedor :::callout

Una línea :::callout{type="<id>"} abre la caja y una línea ::: a solas la cierra. La valla admite cinco atributos — type (el id del estilo), title (sobrescribe el título del estilo), span, placement y columns (sobrescriben los valores del estilo) — y el contenido intermedio se compone dentro de la caja: un título opcional y después los párrafos, listas, citas, fórmulas o recursos incrustados, cada uno con la tipografía body / lists del estilo (los encabezados conservan sus estilos habituales). Los márgenes entre hijos se funden como en el texto corrido; el interior abandona la rejilla base y el flujo vuelve a ella tras la caja garantizando al menos marginBottom por debajo (la rejilla manda; el margen es un mínimo — la misma convención que siguen los recursos). Un estilo con snapToGrid: false conserva en cambio el marginBottom exacto, y el texto tras la caja queda fuera de la rejilla hasta el siguiente encabezado o final de lista. Un encabezado inmediatamente anterior a un aviso se mantiene unido a él.

Límites de esta versión:

• Un aviso se mantiene entero salvo que su estilo indique keepTogether: false. Cuando no cabe en el espacio restante de la columna pasa entero a la columna o página siguiente — también desde una columna vacía que las bandas de flotantes o un tope de banda han acortado, siempre que una columna completa lo alojara. Una caja más alta que una columna completa se parte en su lugar, como una divisible; solo la que ningún corte puede partir (una figura o tabla más alta que la columna, o un splitMinLines que ningún corte cumple) se coloca de todos modos y desborda; la maquetación registra entonces un aviso calloutOverflow (VDTDocument.warnings), que el sandbox lista. Un grupo :::columns se corta como la caja que lo rodea, entre sus subcolumnas (desde postext 1.25); solo se mantiene entero, y puede desbordar de la misma manera, con layout.flowColumns: false o dentro de una caja anidada. Una caja divisible deja atrás la parte que cabe — hijos enteros, o las líneas de un párrafo hasta splitMinLines a cada lado (basta una figura, tabla o fórmula en bloque en un lado) — y continúa en una caja sin icono en la columna o página siguiente, sin título salvo que el estilo lo repita y, si se quiere, con un indicador bajo la parte que deja (ver Marcas de un recuadro partido).
• Los flotantes ceden ante una caja indivisible. Cuando el bloque que sigue a la referencia de una figura es un aviso keepTogether, no se toma un hueco que dejaría a la caja sin ninguna columna de la banda actual donde caer (la columna de la referencia o una vacía posterior, que antes del flotante la alojaba): la figura pasa a su siguiente hueco, normalmente la página siguiente, y la caja sigue en el flujo — como la compondría un cajista, en lugar de expulsar la caja de la página y dejar la columna con la figura sola.
• span: 'page' en una disposición multicolumna convierte la caja en un bloque a ancho de página: se compone al ancho completo del área de contenido y divide la página en bandas de columnas — las columnas de texto que hay encima se cierran en la línea de corte, la caja ocupa su propia columna a todo el ancho y debajo se abre una banda nueva de columnas de texto, de modo que el flujo continúa bajo la caja en todas las columnas. Donde las columnas están niveladas — al inicio de una página, justo debajo de un encabezado de apertura con span: 'page', justo debajo de otro bloque a ancho de página o justo debajo de una banda de flotantes superior — la caja simplemente corta ahí. Si llega a mitad de página, con las columnas desiguales, se compone como lo haría un cajista: el texto que hay encima se corta nivelado en todas las columnas (el motor repite la colocación con las columnas de la banda acortadas al mismo número de líneas de rejilla, de modo que el texto desborda de columna en columna de forma natural y siguen aplicándose todas las reglas de huérfanas, viudas y encabezados unidos a su texto), la caja ocupa el ancho de la página y las columnas continúan debajo. El corte cuesta un par de pasadas de colocación adicionales; cuando la línea de corte no dejaría sitio para la caja más el mínimo de líneas viudas de cuerpo por debajo, o ninguna disposición encaja tras unos pocos intentos, la caja pasa al inicio de la página siguiente. El texto de encima respeta el corte: un párrafo que no puede empezar en las pocas líneas que le quedan a una columna bajo una figura pasa a la columna siguiente (la figura queda sola en su columna), y cuando un bloque aún pasaría del corte, el corte se baja una línea en lugar de quedarse donde termina ese bloque. Una caja partida que abre la banda también se corta ahí, de modo que su resto nunca pasa del corte. Con headings.balancing.beforeSpan (el valor por defecto) la banda que deja se corta nivelada tras ella — como la banda de cierre de un capítulo — y, cuando el estilo permite partirla (keepTogether: false), la parte de la caja que cabe bajo las columnas niveladas cierra la página y el resto abre la siguiente; con beforeSpan: false la página que deja simplemente se equilibra como siempre, sin forzar un salto de página. Un encabezado justo antes de un bloque a ancho de página no viaja con él. En disposiciones de una columna span: 'page' es simplemente en línea.
• placement: 'fixed' saca la caja del flujo: se compone (width: 'auto' se ajusta al título; 'fill' toma el ancho de la columna de texto bajo el punto de anclaje) y se fija a la página en la que aparece en el flujo, en la posición que describen fixed.anchor / fixed.offset — por defecto la esquina inferior izquierda del área de contenido. Las columnas de texto que cubre ceden esa zona (recortada por abajo, o por arriba cuando la columna aún está vacía), exactamente como una banda de flotantes; cuando la zona ya contiene texto, un flotante o un bloque a ancho de página, la caja pasa a la página siguiente. Una caja fija que cierra el capítulo (el bloque siguiente es una apertura de capítulo, un :::part, una caja barrera de flotantes o el final del documento) nivela primero las columnas que quedan encima (headings.balancing.trailing), de modo que una página de cierre corta termina nivelada con el distintivo debajo. La caja y sus hijos viven en page.floats y se pintan fuera del recorte de columna en todos los backends.
• placement: 'top' | 'bottom' hace flotar la caja como un recurso: sale del flujo donde aparece y toma la primera banda libre a partir de ese punto — el pie de la página actual ('bottom'), o la cabeza / el pie de la siguiente página que abre el flujo — al ancho de la columna (span: 'column') o al ancho completo del área de contenido (span: 'page'); el texto que la sigue rellena la página que dejó. Su marco y sus hijos van a page.floats, como los de una caja fija. Una caja flotante que encabeza una página nueva se coloca antes que las figuras que esperan esa página, y una figura citada en una página anterior que entonces cabe bajo ella toma el resto de esa página aunque quedaran menos de tres líneas de texto (una página galería: caja más figura, sin texto entre ambas). Una caja span: 'side' nunca flota: se apila junto al texto sea cual sea su placement. Con columns mayor que 1 (en el estilo o como atributo de la valla, desde postext 1.18), una caja span: 'column' ocupa ese número de columnas contiguas: la cabeza de una serie de columnas vacías que empiezan a la misma altura, o el pie de la columna en curso y de las vacías que la siguen, como en :::callout{placement="top" columns="2"}.
• width: 'auto' se ajusta solo al título; los hijos se ignoran.
• Un :::callout anidado dentro de otro aviso es una caja propia: se compone con su propio estilo (fondo, borde, radio, relleno, franja, título, icono, marcador, pestaña, tipografía) al ancho interior completo de su caja madre y se apila como un hijo más, con su marginTop / marginBottom colapsando con los vecinos. Su span y su placement (de la valla o del estilo) se ignoran —una caja anidada siempre fluye dentro de su madre—, igual que floatBarrier y snapToGrid. Las cajas se anidan a cualquier profundidad y pueden ir dentro de un grupo :::columns (cada una entera, en una columna). Cuando la caja madre se parte, el corte cae antes o después de una caja anidada, o dentro de ella si su estilo permite partirla; cada fragmento vuelve a dibujar los marcos que atraviesa el corte, y una caja anidada que continúa del fragmento anterior pierde su título y su icono, como una continuación de primer nivel.
• Un grupo :::columns{count=N} … ::: entre los hijos compone esos hijos en N columnas de igual ancho, separadas por columnGap, dentro de la caja: la secuencia se corta por los límites de bloque o de línea que mejor nivelan las columnas (un párrafo o elemento de lista cortado a medias sigue en la cabeza de la columna siguiente sin su viñeta), cada columna empieza en la parte superior del grupo y el grupo mide lo que la columna más alta; los hijos posteriores recuperan el ancho completo. Una caja que se parte (keepTogether: false, o más alta que una columna) también corta dentro de un grupo, entre sus columnas: un grupo en serpentina llena sus columnas por turno y sigue en el fragmento siguiente, y uno paralelo (breaks) sigue corriente a corriente (desde postext 1.25; ver Formato del documento › :::columns). Un gap en la valla sustituye a columnGap para ese grupo, y rule traza un filete a lo largo de cada medianil. Sirve para un resumen de puntos clave a dos columnas o para las tablas de un recuadro ancho puestas lado a lado.
• El sexto atributo de la valla, label, se imprime en la pestaña label del estilo (véase arriba): :::callout{type="recuadro" label="RECUADRO 1-1" title="La regla del octeto"}; sin estilo de pestaña el atributo se ignora.

En el VDT la caja es un bloque marco de type: 'callout' cuya decoración (fondo, franja, icono, título) vive en designOverlay, seguido de sus bloques hijos en la misma columna; el marco y cada hijo llevan el containerId de la valla. Una caja anidada es un marco type: 'callout' propio entre los hijos, seguido de sus bloques; conservan el containerId de la valla de primer nivel (la colocación y el equilibrado siguen viendo una sola unidad) y añaden calloutPath, los identificadores de contenedor de las vallas anidadas que los rodean, de la más externa a la más interna (el de un marco anidado es la última entrada). El PDF etiquetado da a cada caja anidada un Div dentro del de su madre. Las imágenes de icono se resuelven como las de los recursos: el registro de imágenes del canvas, la opción resourceImageUrl del HTML y el proveedor resourceBytes del PDF.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => cada campo heredado se rellena desde las secciones resueltas; el locale
//    opcional elige el idioma de las cadenas de continuación
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined para el `note` por defecto; se eliminan los valores estáticos por defecto

#Enunciados numerados y demostraciones

Un estilo con numbering cuenta sus cajas, como el paquete amsthm de LaTeX cuenta los entornos de teorema (desde postext 1.19). Cada caja imprime su rótulo y su número —«Teorema 2.» al principio de su primer párrafo—, y el title de la valla sigue al número entre paréntesis: :::callout{type="theorem" title="Bradley–Terry"} empieza con «Teorema 2 (Bradley–Terry).». Una caja abierta con un identificador ({#thm:main}) es destino de referencias cruzadas, que imprimen «Teorema 2» (:ref{id="thm:main"}), y \ref{thm:main} o style=number imprimen 2.

Una demostración es un estilo con un rótulo sin número y una marca final:

calloutStyles: [
  { id: 'theorem', numbering: { label: 'Teorema' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lema', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definición' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Demostración', counter: false, bold: false, italic: true } },
]

En un libro compuesto capítulo a capítulo, los contadores siguen desde el capítulo anterior (LayoutContinuation.statementCounters, que rellena continuationAfter), y el esquema del libro da al ancla de cada caja numerada su rótulo (OutlineEntry.numberLabel), de modo que una referencia desde otro capítulo lo imprime.

#Tipografía dentro de un recuadro

Una caja de aviso —un recuadro, como la llaman el panel Estilos de recuadro del sandbox y el formato del documento— compone su contenido con la tipografía body y lists de su estilo; todo lo demás conserva los estilos del documento:

• Los párrafos toman el body de la caja: fuente, cuerpo, interlineado, color, colores de énfasis, pesos, italic, smallCaps, alineación, separación silábica, sangría y espaciado entre párrafos. Un campo sin definir hereda de bodyText. Un color de énfasis heredado conserva su vínculo con la paleta, así que las negritas, las cursivas y las etiquetas de :ref de una caja cambian con colorPalette igual que fuera de ella. (Hasta postext 1.4 la negrita de una caja se quedaba en #295AA3 fuera cual fuera el color principal).
• Las listas de viñetas toman el lists de la caja (carácter de viñeta, color, tamaño y peso del glifo, sangría, separación, espaciado entre elementos) sobre unorderedLists, y su texto es el del cuerpo de la caja. Un lists.bulletChar o un lists.color distinto del del documento (unorderedLists) sustituye la viñeta o el color de todos los niveles; uno que lo repite, o que no se define, deja a cada nivel los suyos (unorderedLists.levels), de modo que las rayas de los niveles anidados se conservan en la caja.
• Las listas ordenadas toman lists.indent, gap e itemSpacing, y lists.color siempre que el estilo lo define, también cuando coincide con el color de viñeta del documento; un estilo que no lo define deja los números en orderedLists.color. (Hasta postext 1.4 el color solo llegaba a los números si era distinto de unorderedLists.color, así que darle justo ese color no tenía efecto). El número —su fuente, su cuerpo y su separador— viene de los orderedLists globales, porque lists solo tiene campos de viñeta: es ahí donde se da estilo a los números de una caja.
• Los :::paragraphs dentro de una caja usan su estilo de párrafo, también en cajas anidadas. Los campos que el estilo no define heredan del bodyText del documento, no del body de la caja (ni de su cursiva ni de sus versalitas).
• Los grupos :::columns no tienen estilo propio: todas las columnas comparten la tipografía de cuerpo y de listas de la caja, y columnGap fija la separación entre ellas.
• Las citas toman la fuente, el cuerpo y los pesos del texto de la caja (en cursiva y en gris, como en el texto corrido) y sus versalitas. Los encabezados conservan sus estilos; las fórmulas en bloque, los ajustes de matemáticas.
• Las figuras y las tablas conservan los estilos de pie y de tabla del documento, al ancho interior de la caja; sus pesos normal y negrita siguen los pesos del body de la caja.
• Los chips conservan su estilo de chip; un tamaño en em se mide sobre el cuerpo del texto de la caja.
• :::space se mide en líneas del texto de la caja (ver :::space para saber dónde se descarta).
• Una caja anidada toma su propio estilo completo; su span, su placement, su floatBarrier y su snapToGrid se ignoran.

#Marcas de un recuadro partido

Cuando una caja se parte entre columnas o páginas (keepTogether: false, o una caja más alta que una columna), cada parte posterior a la primera empieza sin el título ni el icono y, por defecto, nada avisa al lector de que la caja continúa. Dos opciones añaden las marcas que usan un libro o un guion:

• repeatTitle: true repite el título al principio de cada continuación, seguido de continuedSuffix — «Puntos clave (cont.)» por defecto. La repetición toma el estilo del título, así que con textTransform: 'uppercase' da el «HAMLET (CONT.)» de un guion. El icono y la pestaña de etiqueta se quedan en la primera parte.
• continuesMarkerEnabled: true pone continuesMarker — «Continúa» en un documento en español, «Continued» en inglés — bajo la última línea de cada parte que continúa, dentro de la caja, en la fuente y el cuerpo del texto de la caja: en cursiva salvo que continuesMarkerItalic sea false, y alineado a la derecha salvo que continuesMarkerAlign diga 'left' o 'center'. El indicador ocupa sitio en la parte que cierra, y el corte se elige para que quepa.

calloutStyles: [{
  id: 'parlamento',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: '(CONT.)',
  continuesMarkerEnabled: true,
  continuesMarker: '(SIGUE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="parlamento" title="Hamlet"}
Un parlamento lo bastante largo para pasar del pie de la página…
:::

La parte que cierra la página termina con «(SIGUE)» y la página siguiente empieza con «HAMLET (CONT.)». Las dos son elementos de paginación: en un PDF accesible son artefactos y en el HTML se ocultan a las tecnologías de apoyo, de modo que el título se lee una sola vez. En el VDT son bloques de texto de designOverlay marcados con artifact: true.