Configuração: boxes

#Estilos de boxe

A propriedade calloutStyles declara os estilos de boxe nomeados que um documento aplica com um contêiner :::callout{type="…"}: notas, dicas, avisos, objetivos de aprendizagem, qualquer conteúdo separado do texto corrido em um boxe com fundo ou contorno. Um estilo neutro, note, vem por padrão (fundo cinza-claro, sem contorno, sem faixa, sem ícone, sem título), de modo que :::callout funciona sem nenhuma configuração; declarar calloutStyles substitui essa lista padrão.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      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"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
 
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::

#O contêiner :::callout

Uma linha :::callout{type="<id>"} abre o boxe e uma linha ::: sozinha o fecha. O delimitador aceita cinco atributos, type (o id do estilo), title (substitui o título do estilo), span, placement e columns (substituem os valores do estilo), e o conteúdo entre as duas linhas é composto dentro do boxe: um título opcional e depois os parágrafos, listas, citações, fórmulas ou recursos incorporados, cada um com a tipografia body / lists do estilo (os títulos mantêm os seus estilos habituais). As margens entre os filhos se fundem como no texto corrido; o interior sai da grade de linhas de base, e o fluxo volta a ela depois do boxe com pelo menos marginBottom abaixo (a grade prevalece; a margem é um mínimo, a mesma convenção que os recursos seguem). Um estilo com snapToGrid: false mantém, em vez disso, o marginBottom exato, e o texto depois do boxe fica fora da grade até o próximo título ou fim de lista. Um título imediatamente antes de um boxe fica junto dele.

Limites desta versão:

• Um boxe é mantido inteiro, a menos que o seu estilo defina keepTogether: false. Quando não cabe no espaço restante da coluna, passa inteiro para a coluna ou página seguinte, inclusive saindo de uma coluna vazia que as faixas de flutuantes ou um limite de faixa encurtaram, desde que uma coluna completa o comportasse. Um boxe mais alto que uma coluna completa se divide em vez disso, como um divisível; só aquele que nenhum corte consegue dividir (uma figura ou tabela mais alta que a coluna, ou um splitMinLines que nenhum corte satisfaz) é colocado mesmo assim e transborda; o layout registra então um aviso calloutOverflow (VDTDocument.warnings), que o Sandbox lista. Um grupo :::columns é cortado como o boxe que o envolve, entre as suas subcolunas (desde o postext 1.25); ele só fica inteiro, e pode transbordar do mesmo modo, com layout.flowColumns: false ou dentro de um boxe aninhado. Um boxe divisível deixa para trás a parte que cabe (filhos inteiros, ou as linhas de um parágrafo até splitMinLines de cada lado; uma figura, tabela ou fórmula em destaque sozinha basta para um lado) e continua em um boxe sem ícone na coluna ou página seguinte, sem o título a menos que o estilo o repita e, opcionalmente, com uma marca sob a parte que deixa (veja Marcas em um boxe dividido).
• Os flutuantes cedem a um boxe indivisível. Quando o bloco logo depois da referência a uma figura é um boxe keepTogether, um espaço que deixaria o boxe sem nenhuma coluna da faixa atual onde cair (a coluna da referência ou uma vazia depois dela, que o comportava antes do flutuante) não é tomado: a figura passa para o seu próximo espaço, normalmente a página seguinte, e o boxe continua no fluxo, como um compositor o comporia, em vez de empurrar o boxe para fora da página e deixar a coluna só com a figura.
• span: 'page' em um layout de várias colunas faz do boxe um bloco de largura de página: ele é composto na largura total do conteúdo e divide a página em faixas de colunas. As colunas de texto acima dele são fechadas na linha de corte, o boxe ocupa uma coluna própria de largura total e uma nova faixa de colunas de texto se abre abaixo dele, de modo que o fluxo continua sob o boxe em todas as colunas. Onde as colunas estão niveladas (no alto de uma página, logo abaixo de um título de abertura span: 'page', logo abaixo de outro bloco de largura de página ou logo abaixo de uma faixa de flutuantes superior), o boxe simplesmente corta ali. Chegando no meio da página, com as colunas desiguais, ele é composto como um compositor faria: o texto acima é cortado nivelado em todas as colunas (o motor refaz a colocação com as colunas da faixa encurtadas para o mesmo número de linhas da grade, de modo que o texto passa de coluna em coluna naturalmente e todas as regras de órfãs, viúvas e manter com o seguinte continuam valendo), o boxe ocupa a largura da página e as colunas continuam abaixo dele. O corte custa algumas passadas extras de colocação; quando a linha de corte não deixaria espaço para o boxe mais o mínimo de linhas do corpo para viúvas abaixo dele, ou nenhuma disposição cabe depois de algumas tentativas, o boxe passa para o alto da página seguinte. O texto acima respeita o corte: um parágrafo que não consegue começar nas poucas linhas que uma coluna mantém acima, sob uma figura, passa para a coluna seguinte (a figura fica então sozinha na sua coluna), e quando um bloco ainda ultrapassaria o corte, o corte é feito uma linha abaixo em vez de onde esse bloco termina. Um boxe dividido que abre a faixa também é cortado ali, de modo que o resto dele nunca ultrapassa o corte. Com headings.balancing.beforeSpan (o padrão), a faixa que ele deixa é cortada nivelada atrás dele, como a faixa de fechamento de um capítulo, e, quando o estilo permite a divisão (keepTogether: false), a parte do boxe que cabe sob as colunas niveladas fecha a página e o resto abre a seguinte; com beforeSpan: false, a página que ele deixa é simplesmente equilibrada como de costume, sem forçar uma quebra de página. Um título logo antes de um bloco de largura de página não o acompanha. Em layouts de uma coluna, span: 'page' é simplesmente em linha.
• placement: 'fixed' tira o boxe do fluxo: ele é composto (width: 'auto' se ajusta ao título; 'fill' toma a largura da coluna de texto sob o ponto de ancoragem) e fixado na página em que aparece no fluxo, na posição descrita por fixed.anchor / fixed.offset (por padrão, o canto inferior esquerdo da área de conteúdo). As colunas de texto que ele cobre cedem essa zona (cortada por baixo, ou por cima quando a coluna ainda está vazia), exatamente como uma faixa de flutuantes; quando a zona já contém texto, um flutuante ou um bloco de largura de página, o boxe passa para a página seguinte. Um boxe fixo que fecha o capítulo (o bloco seguinte é uma abertura de capítulo, um :::part, um boxe barreira de flutuantes ou o fim do documento) primeiro nivela as colunas acima dele (headings.balancing.trailing), de modo que uma página final curta termina nivelada, com o selo embaixo. O quadro e os filhos ficam em page.floats e são renderizados fora do recorte das colunas em todos os renderizadores.
• placement: 'top' | 'bottom' faz o boxe flutuar como um recurso: ele sai do fluxo onde aparece e toma a primeira faixa livre depois desse ponto, isto é, o pé da página atual ('bottom') ou o alto / o pé da próxima página que o fluxo abrir, na largura da coluna (span: 'column') ou na largura total do conteúdo (span: 'page'); o texto que vem depois preenche a página que ele deixou. O seu quadro e os seus filhos vão para page.floats, como os de um boxe fixo. Um boxe flutuante no alto de uma página nova é colocado antes das figuras que esperam por essa página, e uma figura citada em uma página anterior que então caiba sob ele fica com o resto da página, mesmo que restem menos de três linhas de texto (uma página de galeria: boxe mais figura, sem texto entre eles). Um boxe span: 'side' nunca flutua: ele se empilha ao lado do texto, qualquer que seja a sua posição. Com columns acima de 1 (no estilo ou como atributo do delimitador, desde o postext 1.18), um boxe span: 'column' ocupa esse número de colunas adjacentes: o alto de uma sequência de colunas vazias que começam niveladas, ou o pé da coluna atual e das vazias depois dela, como em :::callout{placement="top" columns="2"}.
• width: 'auto' se ajusta só ao título; os filhos são ignorados.
• Um :::callout aninhado dentro de outro boxe é um boxe próprio: é composto com o seu próprio estilo (fundo, contorno, raio, margem interna, faixa, título, ícone, marcador, aba, tipografia) na largura interna total do pai e se empilha como um filho dele, com o seu marginTop / marginBottom se fundindo com os vizinhos. O seu span e o seu placement (do delimitador ou do estilo) são ignorados (um boxe aninhado sempre flui dentro do pai), assim como floatBarrier e snapToGrid. Os boxes se aninham em qualquer profundidade e podem ficar dentro de um grupo :::columns (cada um inteiro, em uma coluna). Quando o pai se divide, o corte cai antes ou depois de um boxe aninhado, ou dentro dele quando o estilo aninhado permite a divisão; cada fragmento redesenha os quadros que atravessa, e um boxe aninhado que continua do fragmento anterior perde o título e o ícone, como uma continuação de primeiro nível.
• Um grupo :::columns{count=N} … ::: entre os filhos compõe esses filhos em N colunas de mesma largura, separadas por columnGap, dentro do boxe: a sequência é cortada nos limites de bloco ou de linha que melhor nivelam as colunas (um parágrafo ou item de lista cortado no meio continua no alto da coluna seguinte sem o marcador), cada coluna começa no alto do grupo e o grupo tem a altura da coluna mais alta; os filhos depois dele voltam à largura total. Um boxe que se divide (keepTogether: false, ou mais alto que uma coluna) também corta dentro de um grupo, entre as suas colunas: um grupo em serpentina (snake) preenche as colunas uma após a outra e continua no fragmento seguinte, e um paralelo (breaks) continua fluxo por fluxo (desde o postext 1.25; veja Formato do documento › :::columns). Um gap no delimitador substitui columnGap para esse grupo, e rule traça um fio ao longo de cada medianiz. Use-o para um resumo de pontos-chave em duas colunas, ou para as tabelas de um boxe largo postas lado a lado.
• O sexto atributo do delimitador, label, é impresso na aba de rótulo do estilo (veja label acima): :::callout{type="box" label="BOX 1-1" title="The octet rule"}; sem um estilo label, o atributo é ignorado.

No VDT, o boxe é um bloco de quadro type: 'callout' cuja decoração (fundo, faixa, ícone, título) fica em designOverlay, seguido dos seus blocos filhos na mesma coluna; o quadro e cada filho levam o containerId do delimitador. Um boxe aninhado é um quadro type: 'callout' próprio entre os filhos, seguido dos seus blocos; eles mantêm o containerId do delimitador de primeiro nível (a colocação e o equilíbrio continuam vendo uma só unidade) e acrescentam calloutPath, os ids de contêiner dos delimitadores aninhados em volta deles, do mais externo para o mais interno (o id do próprio quadro aninhado é a última entrada). O PDF com tags dá a cada boxe aninhado um Div dentro daquele do pai. As imagens de ícone são resolvidas como as imagens de recursos: o registro de imagens do canvas, a opção resourceImageUrl do HTML e o provedor resourceBytes do PDF.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => todo campo herdado é preenchido a partir das seções resolvidas; o locale
//    opcional escolhe o idioma das strings de continuação
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined para o padrão `note` embutido; os padrões estáticos são removidos

#Enunciados numerados e demonstrações

Um estilo com numbering conta os seus boxes, como o amsthm do LaTeX conta os ambientes de teorema (desde o postext 1.19). Cada boxe imprime o seu rótulo e número (“Theorem 2.” abrindo o primeiro parágrafo), e o title do delimitador vem depois do número, entre parênteses: :::callout{type="theorem" title="Bradley–Terry"} começa com “Theorem 2 (Bradley–Terry).”. Um boxe aberto com um identificador ({#thm:main}) é alvo de referências cruzadas, que imprimem “Theorem 2” (:ref{id="thm:main"}), e \ref{thm:main} ou style=number imprime 2.

Uma demonstração é um estilo com um rótulo sem número e uma marca final:

calloutStyles: [
  { id: 'theorem', numbering: { label: 'Theorem' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lemma', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definition' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Proof', counter: false, bold: false, italic: true } },
]

Em um livro diagramado capítulo por capítulo, os contadores continuam a partir do capítulo anterior (LayoutContinuation.statementCounters, que continuationAfter preenche), e o esboço do livro dá à âncora de cada boxe numerado o seu rótulo (OutlineEntry.numberLabel), para que uma referência vinda de outro capítulo o imprima.

#Tipografia dentro de um boxe

Um boxe compõe o seu conteúdo com a sua própria tipografia body e lists; todo o resto mantém os estilos do documento:

• Parágrafos recebem o body do boxe: fonte, tamanho, entrelinha, cor, cores de ênfase, pesos, italic, smallCaps, alinhamento, hifenização, recuo e espaçamento entre parágrafos. Um campo não definido herda bodyText. Uma cor de ênfase herdada mantém o vínculo com a paleta, de modo que o negrito, o itálico e os rótulos de :ref em um boxe mudam com colorPalette como mudam fora dele. (Até o postext 1.4, o negrito em um boxe ficava #295AA3 qualquer que fosse a cor principal.)
• Listas com marcadores recebem o lists do boxe (caractere do marcador, cor, tamanho e peso do glifo, recuo, espaço, espaçamento entre itens) por cima de unorderedLists, e o texto delas é o texto do corpo do boxe. Um lists.bulletChar ou lists.color diferente do documento (unorderedLists) substitui o marcador ou a cor de todos os níveis; um que o repita, ou que fique sem definir, deixa a cada nível o seu (unorderedLists.levels), de modo que os travessões aninhados se mantêm no boxe.
• Listas numeradas recebem lists.indent, gap e itemSpacing, e lists.color sempre que o estilo a define, inclusive quando é a cor dos marcadores do documento; um estilo que a deixa sem definir mantém os números em orderedLists.color. (Até o postext 1.4, a cor só chegava aos números quando era diferente de unorderedLists.color, de modo que defini-la com essa mesma cor não fazia nada.) O número em si (a sua fonte, tamanho e separador) vem do orderedLists global, já que lists só tem campos de marcador: estilize ali os números de um boxe.
• :::paragraphs dentro de um boxe usam o seu estilo de parágrafo, também em boxes aninhados. Os campos que o estilo deixa sem definir herdam o bodyText do documento, não o body do boxe (nem o seu itálico ou versaletes).
• Grupos :::columns não têm estilo próprio: todas as colunas compartilham a tipografia de corpo e de listas do boxe, e columnGap define o espaço entre elas.
• Citações recebem a fonte, o tamanho e os pesos do corpo do boxe (em itálico e cinza, como no texto corrido), e os seus versaletes. Títulos mantêm os estilos de título; fórmulas em destaque, as configurações de matemática.
• Figuras e tabelas mantêm os estilos de legenda e de tabela do documento, na largura interna do boxe; os seus pesos regular e negrito seguem os pesos do body do boxe.
• Chips mantêm o seu estilo de chip; um tamanho em em é medido sobre o tamanho do corpo do boxe.
• :::space é medido em linhas do corpo do boxe (veja :::space para saber onde ele é descartado).
• Um boxe aninhado recebe o seu próprio estilo por inteiro; o seu span, placement, floatBarrier e snapToGrid são ignorados.

#Marcas em um boxe dividido

Quando um boxe se divide entre colunas ou páginas (keepTogether: false, ou um boxe mais alto que uma coluna), cada parte depois da primeira começa sem o título e sem o ícone e, por padrão, nada avisa o leitor de que o boxe continua. Duas opções acrescentam as marcas que um livro ou um roteiro usa:

• repeatTitle: true repete o título no alto de cada continuação, seguido de continuedSuffix (“Pontos-chave (cont.)” por padrão). A repetição usa o estilo do título, de modo que, com textTransform: 'uppercase', ela dá o “HAMLET (CONT'D)” de um roteiro. O ícone e a aba de rótulo ficam na primeira parte.
• continuesMarkerEnabled: true põe continuesMarker (“Continued”, ou “Continúa” em um documento em espanhol) sob a última linha de cada parte que continua, dentro do boxe, na fonte e no tamanho do corpo do boxe: em itálico a menos que continuesMarkerItalic seja false, alinhado à direita a menos que continuesMarkerAlign diga 'left' ou 'center'. A marca ocupa espaço na parte que fecha, e o corte é escolhido de modo que ela caiba.

calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::

A parte que fecha a página termina com “(MORE)”, e a página seguinte começa com “HAMLET (CONT'D)”. As duas são elementos de paginação: em um PDF acessível são artefatos e no HTML ficam ocultas para as tecnologias assistivas, de modo que o título é lido uma só vez. No VDT são blocos de texto de designOverlay marcados com artifact: true.