Diseño y componentes

El tipo changelog escribe páginas Markdown corrientes cuyos cuerpos son dos componentes MDC, renderizados dentro de un diseño propio. Los tres están documentados porque son parte de la superficie pública — un consumidor puede sustituir cualquiera de ellos — no porque haya que escribir una página a mano.

#El diseño changelog

Ligado solo a la granularidad split; un registro plano es una página de documentación corriente y renderiza en el marco de la documentación.

Se diferencia de docs en dos cosas, y ambas se siguen de lo que son las páginas. La barra lateral es la lista de versiones en vez de un árbol de prosa — la misma navegación, la misma colección, porque una sección generada es una colección corriente y sus páginas son las versiones. Y la columna de lectura está limitada a una medida: una nota de versión es prosa, y la prosa compuesta a lo ancho de toda la ventana es ilegible. La columna de contenidos se queda, listando los grupos.

Sustitúyelo por un fichero propio en la misma ruta:

app/layouts/changelog.vue

#ChangelogReleases

La línea de tiempo de la vista general: cada versión, la más reciente primero, filtrable por lo que cambió. Escrito en la página índice de la sección.

El historial abre con cuatro cifras — versiones, cambios, tipos de cambio y el día en que salió la última — cada una un número con una línea pequeña y su etiqueta debajo, como en la página de inicio — pero dispuestas como una rejilla de cuatro columnas a todo el ancho y no como una fila que se envuelve, para que se lean como la cabecera de la lista y no como un pie con un hueco al lado. Los tipos se cuentan sobre los nombres que usó el fichero, así que se cuenta su propio vocabulario; la fecha es la única que no es un recuento, y se omite en vez de dibujar un guion cuando el fichero no fecha nada. Responde lo que una lista de filas no puede: cuánto hay. Las cifras cuentan lo que se muestra, así que en una página filtrada hablan de la página filtrada, con el total junto a la primera.

La etiqueta lleva el acento, no la cifra: --primary es el único color que un sitio consumidor cambia para hacer suyo el tema, y dos líneas cortas con etiqueta son donde eso no cuesta nada.

Debajo, cada versión es una línea en columnas — número, insignia, lo que trajo y la fecha — de modo que los números quedan uno bajo otro y los resúmenes empiezan a la misma altura. Por debajo de sm el resumen baja a una segunda línea; nada se desplaza en horizontal. La versión actual lo dice con una insignia junto al número — una insignia habla del número, así que va con él — en una pista fija que existe la llene o no una fila, de modo que las versiones sin ella empiezan su resumen justo donde lo empieza la que sí la tiene. La fecha va al extremo, junto a la flecha: es el campo que se recorre hacia abajo en vez de leerse a lo ancho.

El filtrado se anima por ambos lados — las fichas que aparecen sobre la lista y las filas que se mueven debajo, con los mismos tiempos, para que ambas se lean como un solo gesto. Las filas aparecen y se asientan en 200 ms, una fila que se va sale del flujo para que las de abajo cierren el hueco mientras se desvanece, y el propio FLIP del navegador mueve a las que quedan. Es un TransitionGroup, no una biblioteca de animación — un fundido y un empujón no valen una dependencia en tiempo de ejecución para cada sitio que extiende la capa — y todo ello se apaga con prefers-reduced-motion. Una fila nombra los tres grupos mayores y cuenta el resto: «Features 2 · Bug Fixes 2 · Documentation 1 · y 9 más». Tres, por número y no por el orden en que los escribió el fichero, porque el orden de secciones de release-please es fijo y no significa nada. Nada se pierde en silencio, y una fila filtrada nombra primero aquello por lo que se filtró.

El tono no está en el historial. Se queda donde distingue en vez de decorar: el menú de filtro, y la etiqueta con la que una página de versión encabeza cada grupo.

Una marca delante de un nombre se omite al dibujarlo allá donde se muestre un nombre — el ⚠ con el que release-please encabeza su bloque de cambios incompatibles, un emoji con el que un registro hecho a mano abre una sección. Solo al principio, así que C++ Support sobrevive. El nombre almacenado queda entero: el filtro compara con él, el ancla se genera a partir de él y las props lo llevan, y por eso la marca se omite al dibujar y no al analizar. Véase changelogLabel.

Los groups de una versión llevan solo un name y un count — las entradas no están aquí, porque cada versión tiene una página propia y repetir sus puntos metería el historial entero dos veces en el índice de búsqueda, en llms-full.txt y en el feed.

Las fichas de filtro se construyen con los nombres que usó el propio fichero. Sin nada seleccionado la página muestra todo, que es también lo que renderiza el servidor: un filtro es una elección del lector, así que la página tiene que estar completa antes de que nadie la haga — si no, al rastreador y al lector cuya hidratación aún no ha llegado se les muestra un registro filtrado que nadie pidió.

#ChangelogGroup

Un grupo de una versión — «Features», «Bug Fixes», lo que dijera el fichero.

Las entradas llegan en el slot, como el Markdown en el que se escribieron — así la búsqueda las indexa, llms-full.txt las lleva y el control de copia entrega a un modelo prosa en vez de una llamada a un componente. Solo el nombre y el número, que la insignia y los filtros necesitan como datos, viajan como props.

El nombre es una etiqueta, no un titular: compuesto pequeño, en versales y en el tono del propio grupo, sobre una lista que se cierra debajo. Como encabezado de 20 píxeles reclamaba el peso de un capítulo para una palabra que nombra cuatro puntos, y seis de ellos se leían como seis secciones en vez de como una versión. Sigue siendo un <h2> — el esquema, la columna de contenidos y el ancla no cambian, y solo su composición dice lo que vale.

El color es una pista y nunca un significado: un nombre que la lista de pistas no conoce recibe igualmente un color propio y estable, que es lo que hace el mismo tipo de cambio recorrible de un vistazo por una página de cuarenta versiones en cualquier idioma. La etiqueta toma el par text del tono y no el relleno dot, porque unas palabras y un punto de seis píxeles no superan el contraste con la misma claridad.

Los marcadores de las entradas siguen siendo grises. El color ya está dicho en la etiqueta que está justo encima; repetido en cada línea deja de ser una señal. Se componen desde duxt.css, no desde este componente, porque llegan como Markdown por el slot.

#Sustituir uno

Igual que con cualquier otro componente que trae la capa: gana un fichero en la misma ruta dentro del sitio consumidor.

app/components/content/ChangelogGroup.vue

Las props de arriba son el contrato, y el nombre del diseño también. Un cambio de nombre aquí es un cambio incompatible de la capa.

#Qué muestra una página de versión aparte de sus grupos

Nada en el cuerpo. El día en que se cortó una versión y el diff del que se cortó viajan como date y compare en el frontmatter de la página, y se dibujan donde el sitio ya responde de dónde vino una página: el bloque de procedencia bajo la columna de contenidos, encima de «Editar esta página».

La fecha de la versión sustituye a la línea del último commit en vez de sumarse a ella — todas las versiones de un registro viven en un fichero, así que su último commit las fecha a todas el mismo día, que en el mejor caso es el de la más reciente.

Así una página de versión se lee como cualquier otra página Markdown del sitio, que es de lo que se trata: una nota de versión es prosa, no un panel.

#Sin encabezado propio

Ninguno de los dos componentes abre con un <h1>. El marco de la documentación dibuja la cabecera — miga de pan, título, el control de copia al lado — para toda página generada cuyo cuerpo no abre con encabezado, y una página de versión quiere exactamente eso: un título y un rastro como cualquier página escrita.