🎨 Mejora la página de bienvenida y el tema básico #6

Merged
manuelcillero merged 37 commits from advanced-welcome-page into main 2025-09-20 12:37:55 +02:00
25 changed files with 66 additions and 67 deletions
Showing only changes of commit d7fcd6ccc4 - Show all commits

View file

@ -1,8 +1,7 @@
# 🔃 Dependencias
`PageTop` está basado en [Rust](https://www.rust-lang.org/) y crece a hombros de gigantes
aprovechando algunas de las librerías más robustas y populares del [ecosistema Rust](https://lib.rs)
como son:
PageTop está basado en [Rust](https://www.rust-lang.org/) y crece a hombros de gigantes aprovechando
algunas de las librerías más robustas y populares del [ecosistema Rust](https://lib.rs) como son:
* [Actix Web](https://actix.rs/) para los servicios web.
* [Config](https://docs.rs/config) para cargar y procesar las opciones de configuración.
@ -11,14 +10,14 @@ como son:
* [Fluent templates](https://github.com/XAMPPRocky/fluent-templates), que integra
[Fluent](https://projectfluent.org/) para internacionalizar las aplicaciones.
* Además de otros *crates* adicionales que se pueden explorar en los archivos `Cargo.toml` de
`PageTop` y sus extensiones.
PageTop y sus extensiones.
# 🗚 FIGfonts
`PageTop` usa el *crate* [figlet-rs](https://crates.io/crates/figlet-rs) desarrollado por
*yuanbohan* para mostrar un banner de presentación en el terminal con el nombre de la aplicación en
caracteres [FIGlet](http://www.figlet.org). Las fuentes incluidas en `pagetop/src/app` son:
PageTop usa el *crate* [figlet-rs](https://crates.io/crates/figlet-rs) desarrollado por *yuanbohan*
para mostrar un banner de presentación en el terminal con el nombre de la aplicación en caracteres
[FIGlet](http://www.figlet.org). Las fuentes incluidas en `pagetop/src/app` son:
* [slant.flf](http://www.figlet.org/fontdb_example.cgi?font=slant.flf) de *Glenn Chappell*
* [small.flf](http://www.figlet.org/fontdb_example.cgi?font=small.flf) de *Glenn Chappell*

View file

@ -14,8 +14,8 @@
<br>
</div>
`PageTop` reivindica la esencia de la web clásica usando [Rust](https://www.rust-lang.org/es) para
la creación de soluciones web SSR (*renderizadas en el servidor*) basadas en HTML, CSS y JavaScript.
PageTop reivindica la esencia de la web clásica usando [Rust](https://www.rust-lang.org/es) para la
creación de soluciones web SSR (*renderizadas en el servidor*) basadas en HTML, CSS y JavaScript.
Ofrece un conjunto de herramientas que los desarrolladores pueden implementar, extender o adaptar
según las necesidades de cada proyecto, incluyendo:
@ -24,14 +24,14 @@ según las necesidades de cada proyecto, incluyendo:
* **Componentes** (*components*): encapsulan HTML, CSS y JavaScript en unidades funcionales,
configurables y reutilizables.
* **Extensiones** (*extensions*): añaden, extienden o personalizan funcionalidades usando las APIs
de `PageTop` o de terceros.
de PageTop o de terceros.
* **Temas** (*themes*): son extensiones que permiten modificar la apariencia de páginas y
componentes sin comprometer su funcionalidad.
# ⚡️ Guía rápida
La aplicación más sencilla de `PageTop` se ve así:
La aplicación más sencilla de PageTop se ve así:
```rust,no_run
use pagetop::prelude::*;
@ -42,10 +42,10 @@ async fn main() -> std::io::Result<()> {
}
```
Este código arranca el servidor de `PageTop`. Con la configuración por defecto, muestra una página
de bienvenida accesible desde un navegador local en la dirección `http://localhost:8080`.
Este código arranca el servidor de PageTop. Con la configuración por defecto, muestra una página de
bienvenida accesible desde un navegador local en la dirección `http://localhost:8080`.
Para personalizar el servicio, se puede crear una extensión de `PageTop` de la siguiente manera:
Para personalizar el servicio, se puede crear una extensión de PageTop de la siguiente manera:
```rust,no_run
use pagetop::prelude::*;
@ -86,15 +86,15 @@ El código se organiza en un *workspace* donde actualmente se incluyen los sigui
* **[pagetop-statics](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/helpers/pagetop-statics)**,
es la librería que permite incluir archivos estáticos en el ejecutable de las aplicaciones
`PageTop` para servirlos de forma eficiente, con detección de cambios que optimizan el tiempo
de compilación.
PageTop para servirlos de forma eficiente, con detección de cambios que optimizan el tiempo de
compilación.
* **[pagetop-build](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/helpers/pagetop-build)**,
prepara los archivos estáticos o archivos SCSS compilados para incluirlos en el binario de las
aplicaciones `PageTop` durante la compilación de los ejecutables.
aplicaciones PageTop durante la compilación de los ejecutables.
* **[pagetop-macros](https://git.cillero.es/manuelcillero/pagetop/src/branch/main/helpers/pagetop-macros)**,
proporciona una colección de macros que mejoran la experiencia de desarrollo con `PageTop`.
proporciona una colección de macros que mejoran la experiencia de desarrollo con PageTop.
# 🧪 Pruebas
@ -116,7 +116,7 @@ Para simplificar el flujo de trabajo, el repositorio incluye varios **alias de C
# 🚧 Advertencia
`PageTop` es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
**PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos
hasta que se libere la versión **1.0.0**.

View file

@ -113,7 +113,7 @@ impl Extension for MyExtension {
# 🚧 Advertencia
`PageTop` es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
**PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos
hasta que se libere la versión **1.0.0**.

View file

@ -26,12 +26,12 @@ Esta librería incluye entre sus macros una adaptación de
[SmartDefault](https://crates.io/crates/smart_default) (0.7.1) de
[Jane Doe](https://crates.io/users/jane-doe), llamada `AutoDefault`. Estas macros eliminan la
necesidad de referenciar `maud` o `smart_default` en las dependencias del archivo `Cargo.toml` de
cada proyecto `PageTop`.
cada proyecto PageTop.
# 🚧 Advertencia
`PageTop` es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
**PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos
hasta que se libere la versión **1.0.0**.

View file

@ -27,7 +27,7 @@ Esta librería incluye entre sus macros una adaptación de
[SmartDefault](https://crates.io/crates/smart_default) (0.7.1) de
[Jane Doe](https://crates.io/users/jane-doe), llamada `AutoDefault`. Estas macros eliminan la
necesidad de referenciar `maud` o `smart_default` en las dependencias del archivo `Cargo.toml` de
cada proyecto `PageTop`.
cada proyecto PageTop.
*/
#![doc(
@ -219,7 +219,7 @@ pub fn builder_fn(_: TokenStream, item: TokenStream) -> TokenStream {
expanded.into()
}
/// Define una función `main` asíncrona como punto de entrada de `PageTop`.
/// Define una función `main` asíncrona como punto de entrada de PageTop.
///
/// # Ejemplo
///
@ -240,7 +240,7 @@ pub fn main(_: TokenStream, item: TokenStream) -> TokenStream {
output
}
/// Define funciones de prueba asíncronas para usar con `PageTop`.
/// Define funciones de prueba asíncronas para usar con PageTop.
///
/// # Ejemplo
///

View file

@ -16,7 +16,7 @@ configurables, basadas en HTML, CSS y JavaScript.
## Descripción general
Esta librería permite incluir archivos estáticos en el ejecutable de las aplicaciones `PageTop` para
Esta librería permite incluir archivos estáticos en el ejecutable de las aplicaciones PageTop para
servirlos de forma eficiente vía web, con detección de cambios que optimizan el tiempo de
compilación.
@ -28,13 +28,13 @@ Para ello, adapta el código de los *crates* [static-files](https://crates.io/cr
[4.0.1](https://github.com/kilork/actix-web-static-files/tree/v4.0.1)), desarrollados ambos por
[Alexander Korolev](https://crates.io/users/kilork).
Estas implementaciones se integran en `PageTop` para evitar que cada proyecto tenga que declarar
Estas implementaciones se integran en PageTop para evitar que cada proyecto tenga que declarar
`static-files` manualmente como dependencia en su `Cargo.toml`.
# 🚧 Advertencia
`PageTop` es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
**PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos
hasta que se libere la versión **1.0.0**.

View file

@ -17,7 +17,7 @@ configurables, basadas en HTML, CSS y JavaScript.
## Descripción general
Esta librería permite incluir archivos estáticos en el ejecutable de las aplicaciones `PageTop` para
Esta librería permite incluir archivos estáticos en el ejecutable de las aplicaciones PageTop para
servirlos de forma eficiente vía web, con detección de cambios que optimizan el tiempo de
compilación.
@ -29,7 +29,7 @@ Para ello, adapta el código de los *crates* [static-files](https://crates.io/cr
[4.0.1](https://github.com/kilork/actix-web-static-files/tree/v4.0.1)), desarrollados ambos por
[Alexander Korolev](https://crates.io/users/kilork).
Estas implementaciones se integran en `PageTop` para evitar que cada proyecto tenga que declarar
Estas implementaciones se integran en PageTop para evitar que cada proyecto tenga que declarar
`static-files` manualmente como dependencia en su `Cargo.toml`.
*/

View file

@ -1,4 +1,4 @@
//! Prepara y ejecuta una aplicación creada con `Pagetop`.
//! Prepara y ejecuta una aplicación creada con PageTop.
mod figfont;
@ -17,7 +17,7 @@ use substring::Substring;
use std::io::Error;
use std::sync::LazyLock;
/// Punto de entrada de una aplicación `PageTop`.
/// Punto de entrada de una aplicación PageTop.
///
/// No almacena datos, **encapsula** el inicio completo de configuración y puesta en marcha. Para
/// instanciarla se puede usar [`new()`](Application::new) o [`prepare()`](Application::prepare).

View file

@ -1,4 +1,4 @@
//! Acciones predefinidas para alterar el funcionamiento interno de `PageTop`.
//! Acciones predefinidas para alterar el funcionamiento interno de PageTop.
use crate::prelude::*;

View file

@ -1,4 +1,4 @@
//! Componentes nativos proporcionados por `PageTop`.
//! Componentes nativos proporcionados por PageTop.
mod html;
pub use html::Html;

View file

@ -1,4 +1,4 @@
//! Extensiones para funcionalidades avanzadas de `PageTop`.
//! Extensiones para funcionalidades avanzadas de PageTop.
mod welcome;
pub use welcome::Welcome;

View file

@ -1,6 +1,6 @@
use crate::prelude::*;
/// Página de bienvenida predeterminada de `PageTop`.
/// Página de bienvenida predeterminada de PageTop.
///
/// Esta extensión se instala por defecto y muestra una página en la ruta raíz (`/`) cuando no se ha
/// configurado ninguna página de inicio personalizada. Permite confirmar que el servidor está

View file

@ -1,4 +1,4 @@
//! Temas básicos soportados por `PageTop`.
//! Temas básicos soportados por PageTop.
mod basic;
pub use basic::Basic;

View file

@ -1,4 +1,4 @@
//! Es el tema básico que incluye `PageTop` por defecto.
//! Es el tema básico que incluye PageTop por defecto.
use crate::prelude::*;

View file

@ -3,7 +3,7 @@
//! Estos ajustes se obtienen de archivos [TOML](https://toml.io) como pares `clave = valor` que se
//! mapean a estructuras **fuertemente tipadas** y valores predefinidos.
//!
//! Siguiendo la metodología [Twelve-Factor App](https://12factor.net/config), `PageTop` separa el
//! Siguiendo la metodología [Twelve-Factor App](https://12factor.net/config), PageTop separa el
//! **código** de la **configuración**, lo que permite tener configuraciones diferentes para cada
//! despliegue, como *dev*, *staging* o *production*, sin modificar el código fuente.
//!
@ -13,14 +13,14 @@
//! Si tu aplicación necesita archivos de configuración, crea un directorio `config` en la raíz del
//! proyecto, al mismo nivel que el archivo *Cargo.toml* o que el binario de la aplicación.
//!
//! `PageTop` carga en este orden, y siempre de forma opcional, los siguientes archivos TOML:
//! PageTop carga en este orden, y siempre de forma opcional, los siguientes archivos TOML:
//!
//! 1. **config/common.toml**, para ajustes comunes a todos los entornos. Este enfoque simplifica el
//! mantenimiento al centralizar los valores de configuración comunes.
//!
//! 2. **config/{rm}.toml**, donde `{rm}` es el valor de la variable de entorno `PAGETOP_RUN_MODE`:
//!
//! * Si `PAGETOP_RUN_MODE` no está definida, se asume el valor `default`, y `PageTop` intentará
//! * Si `PAGETOP_RUN_MODE` no está definida, se asume el valor `default`, y PageTop intentará
//! cargar *config/default.toml* si el archivo existe.
//!
//! * Útil para definir configuraciones específicas por entorno, garantizando que cada uno (p.ej.

View file

@ -117,7 +117,7 @@ impl TypeInfo {
///
/// Este *trait* se implementa automáticamente para **todos** los tipos que implementen [`Any`], de
/// modo que basta con traer [`AnyInfo`] al ámbito (`use crate::AnyInfo;`) para disponer de estos
/// métodos adicionales, o usar el [`prelude`](crate::prelude) de `PageTop`.
/// métodos adicionales, o usar el [`prelude`](crate::prelude) de PageTop.
///
/// # Ejemplo
///

View file

@ -11,7 +11,7 @@ pub trait ComponentRender {
fn render(&mut self, cx: &mut Context) -> Markup;
}
/// Interfaz común que debe implementar un componente renderizable en `PageTop`.
/// Interfaz común que debe implementar un componente renderizable en PageTop.
///
/// Se recomienda que los componentes deriven [`AutoDefault`](crate::AutoDefault). También deben
/// implementar explícitamente el método [`new()`](Self::new) y pueden sobrescribir los otros

View file

@ -1,6 +1,6 @@
//! API para añadir nuevas funcionalidades usando extensiones.
//!
//! Cada funcionalidad adicional que quiera incorporarse a una aplicación `PageTop` se debe modelar
//! Cada funcionalidad adicional que quiera incorporarse a una aplicación PageTop se debe modelar
//! como una **extensión**. Todas comparten la misma interfaz declarada en [`Extension`].
mod definition;

View file

@ -10,7 +10,7 @@ use crate::{actions_boxed, service};
/// cualquier hilo de la ejecución sin necesidad de sincronización adicional.
pub type ExtensionRef = &'static dyn Extension;
/// Interfaz común que debe implementar cualquier extensión de `PageTop`.
/// Interfaz común que debe implementar cualquier extensión de PageTop.
///
/// Este *trait* es fácil de implementar, basta con declarar una estructura de tamaño cero para la
/// extensión y sobreescribir los métodos que sea necesario.
@ -63,7 +63,7 @@ pub trait Extension: AnyInfo + Send + Sync {
/// Otras extensiones que deben habilitarse **antes** de esta.
///
/// `PageTop` las resolverá automáticamente respetando el orden durante el arranque de la
/// PageTop las resolverá automáticamente respetando el orden durante el arranque de la
/// aplicación.
fn dependencies(&self) -> Vec<ExtensionRef> {
vec![]

View file

@ -1,6 +1,6 @@
//! API para añadir y gestionar nuevos temas.
//!
//! En `PageTop` un tema es la *piel* de la aplicación, decide cómo se muestra cada documento HTML,
//! En PageTop un tema es la *piel* de la aplicación, decide cómo se muestra cada documento HTML,
//! especialmente las páginas de contenido ([`Page`](crate::response::page::Page)), sin alterar la
//! lógica interna de sus componentes.
//!

View file

@ -68,7 +68,7 @@ pub struct App {
#[derive(Debug, Deserialize)]
/// Sección `[Dev]` de la configuración. Forma parte de [`Settings`].
pub struct Dev {
/// Directorio desde el que servir los archivos estáticos de `PageTop`.
/// Directorio desde el que servir los archivos estáticos de PageTop.
///
/// Por defecto, los archivos se integran en el binario de la aplicación. Si aquí se indica una
/// ruta válida, ya sea absoluta o relativa al directorio del proyecto o del binario en

View file

@ -15,8 +15,8 @@
<br>
</div>
`PageTop` reivindica la esencia de la web clásica usando [Rust](https://www.rust-lang.org/es) para
la creación de soluciones web SSR (*renderizadas en el servidor*) basadas en HTML, CSS y JavaScript.
PageTop reivindica la esencia de la web clásica usando [Rust](https://www.rust-lang.org/es) para la
creación de soluciones web SSR (*renderizadas en el servidor*) basadas en HTML, CSS y JavaScript.
Ofrece un conjunto de herramientas que los desarrolladores pueden implementar, extender o adaptar
según las necesidades de cada proyecto, incluyendo:
@ -25,14 +25,14 @@ según las necesidades de cada proyecto, incluyendo:
* **Componentes** (*components*): encapsulan HTML, CSS y JavaScript en unidades funcionales,
configurables y reutilizables.
* **Extensiones** (*extensions*): añaden, extienden o personalizan funcionalidades usando las APIs
de `PageTop` o de terceros.
de PageTop o de terceros.
* **Temas** (*themes*): son extensiones que permiten modificar la apariencia de páginas y
componentes sin comprometer su funcionalidad.
# Guía rápida
La aplicación más sencilla de `PageTop` se ve así:
La aplicación más sencilla de PageTop se ve así:
```rust,no_run
use pagetop::prelude::*;
@ -43,10 +43,10 @@ async fn main() -> std::io::Result<()> {
}
```
Este código arranca el servidor de `PageTop`. Con la configuración por defecto, muestra una página
de bienvenida accesible desde un navegador local en la dirección `http://localhost:8080`.
Este código arranca el servidor de PageTop. Con la configuración por defecto, muestra una página de
bienvenida accesible desde un navegador local en la dirección `http://localhost:8080`.
Para personalizar el servicio, se puede crear una extensión de `PageTop` de la siguiente manera:
Para personalizar el servicio, se puede crear una extensión de PageTop de la siguiente manera:
```rust,no_run
use pagetop::prelude::*;
@ -77,11 +77,11 @@ Este programa implementa una extensión llamada `HelloWorld` que sirve una pági
# 🧩 Gestión de Dependencias
Los proyectos que utilizan `PageTop` gestionan las dependencias con `cargo`, como cualquier otro
Los proyectos que utilizan PageTop gestionan las dependencias con `cargo`, como cualquier otro
proyecto en Rust.
Sin embargo, es fundamental que cada extensión declare explícitamente sus
[dependencias](core::extension::Extension::dependencies), si las tiene, para que `PageTop` pueda
[dependencias](core::extension::Extension::dependencies), si las tiene, para que PageTop pueda
estructurar e inicializar la aplicación de forma modular.
*/

View file

@ -1,6 +1,6 @@
//! Localización (L10n).
//!
//! `PageTop` utiliza las especificaciones de [Fluent](https://www.projectfluent.org/) para la
//! PageTop utiliza las especificaciones de [Fluent](https://www.projectfluent.org/) para la
//! localización de aplicaciones, y aprovecha [fluent-templates](https://docs.rs/fluent-templates/)
//! para integrar los recursos de traducción directamente en el binario de la aplicación.
//!
@ -87,7 +87,7 @@
//! include_locales!(LOCALES_SAMPLE from "ruta/a/las/traducciones");
//! ```
//!
//! Y *voilà*, sólo queda operar con los idiomas soportados por `PageTop` usando [`LangMatch`] y
//! Y *voilà*, sólo queda operar con los idiomas soportados por PageTop usando [`LangMatch`] y
//! traducir textos con [`L10n`].
use crate::html::{Markup, PreEscaped};
@ -141,10 +141,10 @@ pub trait LangId {
fn langid(&self) -> &'static LanguageIdentifier;
}
/// Operaciones con los idiomas soportados por `PageTop`.
/// Operaciones con los idiomas soportados por PageTop.
///
/// Utiliza [`LangMatch`] para transformar un identificador de idioma en un [`LanguageIdentifier`]
/// soportado por `PageTop`.
/// soportado por PageTop.
///
/// # Ejemplos
///
@ -183,11 +183,11 @@ pub trait LangId {
pub enum LangMatch {
/// Cuando el identificador de idioma es una cadena vacía.
Unspecified,
/// Si encuentra un [`LanguageIdentifier`] en la lista de idiomas soportados por `PageTop` que
/// Si encuentra un [`LanguageIdentifier`] en la lista de idiomas soportados por PageTop que
/// coincide exactamente con el identificador de idioma (p.ej. "es-ES"), o con el identificador
/// del idioma base (p.ej. "es").
Found(&'static LanguageIdentifier),
/// Si el identificador de idioma no está entre los soportados por `PageTop`.
/// Si el identificador de idioma no está entre los soportados por PageTop.
Unsupported(String),
}
@ -319,7 +319,7 @@ enum L10nOp {
/// Cada instancia puede representar:
///
/// - Un texto puro (`n()`) que no requiere traducción.
/// - Una clave para traducir un texto de las traducciones predefinidas de `PageTop` (`l()`).
/// - Una clave para traducir un texto de las traducciones predefinidas de PageTop (`l()`).
/// - Una clave para traducir de un conjunto concreto de traducciones (`t()`).
///
/// # Ejemplo

View file

@ -1,4 +1,4 @@
//! *Prelude* de `PageTop`.
//! *Prelude* de PageTop.
// RE-EXPORTED.

View file

@ -1,13 +1,13 @@
//! Gestión de trazas y registro de eventos de la aplicación.
//!
//! `PageTop` recopila información de diagnóstico de la aplicación de forma estructurada y basada en
//! PageTop recopila información de diagnóstico de la aplicación de forma estructurada y basada en
//! eventos.
//!
//! En los sistemas asíncronos, interpretar los mensajes de log tradicionales suele volverse
//! complicado. Las tareas individuales se multiplexan en el mismo hilo y los eventos y registros
//! asociados se entremezclan, lo que dificulta seguir la secuencia lógica.
//!
//! `PageTop` usa [`tracing`](https://docs.rs/tracing) para registrar eventos estructurados y con
//! PageTop usa [`tracing`](https://docs.rs/tracing) para registrar eventos estructurados y con
//! información adicional sobre la *temporalidad* y la *causalidad*. A diferencia de un mensaje de
//! log, un *span* (intervalo) tiene un momento de inicio y de fin, puede entrar y salir del flujo
//! de ejecución y puede existir dentro de un árbol anidado de *spans* similares. Además, estos