chore: angular 17 pagination models explained

Author: Jaume Segarra

docs/develop/paginated/angular17.md

@@ -72,6 +72,17 @@ Por defecto, el esquema de datos de Spring para la paginación es como el siguie
 
 Así que necesitamos poder enviar y recuperar esa información desde Angular, nos hace falta crear esos objetos. Los objetos de paginación, al ser comunes a toda la aplicación, vamos a crearlos en `core/model/page`.
 
+!!! info "¿Por qué en `core/model/page` y no dentro del componente `author`?"
+    `SortPage`, `Pageable` y `PaginatedData` **no pertenecen al dominio de negocio de `Author`**; son contratos técnicos que describen cómo se comunica el frontend con el backend cuando los datos vienen paginados.
+
+    Cualquier otro listado de la aplicación —categorías, préstamos, juegos…— necesitará exactamente estos mismos objetos. Si los metiéramos dentro de `author/`, el día que quisiéramos paginar otro listado tendríamos dos opciones igual de malas: duplicar el código o importar clases de un módulo que no tiene nada que ver con tu entidad.
+
+    Colocarlos en `core/` sigue el principio de **reutilización y responsabilidad única**:
+
+    - Un único lugar donde mantener el contrato de paginación.
+    - Si el backend cambia el esquema (p. ej. renombra `pageNumber` a `page`), sólo hay que tocar un fichero.
+    - Cualquier desarrollador que llegue al proyecto sabrá dónde buscarlos sin tener que adivinar en qué módulo de negocio están escondidos.
+
 === "SortPage.ts"
     ``` TypeScript
     export class SortPage {
@@ -100,6 +111,19 @@ Así que necesitamos poder enviar y recuperar esa información desde Angular, no
     }
     ```
 
+!!! info "¿Qué es `<TData>`?"
+    `<TData>` es un **genérico de TypeScript** (el equivalente a los *generics* de Java `<T>` o de C# `<T>`).
+
+    Permite que `PaginatedData` sea una clase **reutilizable con cualquier tipo de contenido**, sin necesidad de crear una clase distinta para cada entidad:
+
+    ```typescript
+    PaginatedData<Author>    // content será Author[]
+    PaginatedData<Category>  // content será Category[]
+    PaginatedData<Loan>      // content será Loan[]
+    ```
+
+    TypeScript verifica el tipo en tiempo de compilación, por lo que si intentas acceder a una propiedad que no existe en `Author` dentro de un `PaginatedData<Author>`, el compilador te avisará de inmediato. Obtienes reutilización **y** seguridad de tipos al mismo tiempo.
+
 Con estos objetos creados ya podemos implementar el servicio y sus datos mockeados.
 
 === "mock-authors.ts"

site/develop/paginated/angular17/index.html

@@ -2301,6 +2301,17 @@ <h2 id="implementar-servicio">Implementar servicio</h2>
 </div>
 </div>
 <p>Así que necesitamos poder enviar y recuperar esa información desde Angular, nos hace falta crear esos objetos. Los objetos de paginación, al ser comunes a toda la aplicación, vamos a crearlos en <code>core/model/page</code>.</p>
+<div class="admonition info">
+<p class="admonition-title">¿Por qué en <code>core/model/page</code> y no dentro del componente <code>author</code>?</p>
+<p><code>SortPage</code>, <code>Pageable</code> y <code>PaginatedData</code> <strong>no pertenecen al dominio de negocio de <code>Author</code></strong>; son contratos técnicos que describen cómo se comunica el frontend con el backend cuando los datos vienen paginados.</p>
+<p>Cualquier otro listado de la aplicación —categorías, préstamos, juegos…— necesitará exactamente estos mismos objetos. Si los metiéramos dentro de <code>author/</code>, el día que quisiéramos paginar otro listado tendríamos dos opciones igual de malas: duplicar el código o importar clases de un módulo que no tiene nada que ver con tu entidad.</p>
+<p>Colocarlos en <code>core/</code> sigue el principio de <strong>reutilización y responsabilidad única</strong>:</p>
+<ul>
+<li>Un único lugar donde mantener el contrato de paginación.</li>
+<li>Si el backend cambia el esquema (p. ej. renombra <code>pageNumber</code> a <code>page</code>), sólo hay que tocar un fichero.</li>
+<li>Cualquier desarrollador que llegue al proyecto sabrá dónde buscarlos sin tener que adivinar en qué módulo de negocio están escondidos.</li>
+</ul>
+</div>
 <div class="tabbed-set tabbed-alternate" data-tabs="4:3"><input checked="checked" id="__tabbed_4_1" name="__tabbed_4" type="radio" /><input id="__tabbed_4_2" name="__tabbed_4" type="radio" /><input id="__tabbed_4_3" name="__tabbed_4" type="radio" /><div class="tabbed-labels"><label for="__tabbed_4_1">SortPage.ts</label><label for="__tabbed_4_2">Pageable.ts</label><label for="__tabbed_4_3">PaginatedData.ts</label></div>
 <div class="tabbed-content">
 <div class="tabbed-block">
@@ -2332,6 +2343,16 @@ <h2 id="implementar-servicio">Implementar servicio</h2>
 </div>
 </div>
 </div>
+<div class="admonition info">
+<p class="admonition-title">¿Qué es <code>&lt;TData&gt;</code>?</p>
+<p><code>&lt;TData&gt;</code> es un <strong>genérico de TypeScript</strong> (el equivalente a los <em>generics</em> de Java <code>&lt;T&gt;</code> o de C# <code>&lt;T&gt;</code>).</p>
+<p>Permite que <code>PaginatedData</code> sea una clase <strong>reutilizable con cualquier tipo de contenido</strong>, sin necesidad de crear una clase distinta para cada entidad:</p>
+<div class="highlight"><pre><span></span><code><span class="nx">PaginatedData</span><span class="o">&lt;</span><span class="nx">Author</span><span class="o">&gt;</span><span class="w">    </span><span class="c1">// content será Author[]</span>
+<span class="nx">PaginatedData</span><span class="o">&lt;</span><span class="nx">Category</span><span class="o">&gt;</span><span class="w">  </span><span class="c1">// content será Category[]</span>
+<span class="nx">PaginatedData</span><span class="o">&lt;</span><span class="nx">Loan</span><span class="o">&gt;</span><span class="w">      </span><span class="c1">// content será Loan[]</span>
+</code></pre></div>
+<p>TypeScript verifica el tipo en tiempo de compilación, por lo que si intentas acceder a una propiedad que no existe en <code>Author</code> dentro de un <code>PaginatedData&lt;Author&gt;</code>, el compilador te avisará de inmediato. Obtienes reutilización <strong>y</strong> seguridad de tipos al mismo tiempo.</p>
+</div>
 <p>Con estos objetos creados ya podemos implementar el servicio y sus datos mockeados.</p>
 <div class="tabbed-set tabbed-alternate" data-tabs="5:2"><input checked="checked" id="__tabbed_5_1" name="__tabbed_5" type="radio" /><input id="__tabbed_5_2" name="__tabbed_5" type="radio" /><div class="tabbed-labels"><label for="__tabbed_5_1">mock-authors.ts</label><label for="__tabbed_5_2">author.service.ts</label></div>
 <div class="tabbed-content">