@tinya-code/gas-admin-ui 0.2.0-alpha.12 → 0.2.0-alpha.15

package/src/lib/core/utils/clipboard.ts

@@ -0,0 +1,90 @@
+/**
+ * Mensaje completo a copiar o compartir.
+ *
+ * `shareTextTemplate` es el MENSAJE FORMATEADO por el schema (el que trae
+ * saludo, ref, PIN o el enlace ya escrito dentro), mientras que `urlTemplate`
+ * es sólo el enlace. Los tres caminos —copiar, compartir nativo y WhatsApp—
+ * deben ofrecer el mismo texto: antes `copy()` y la acción del listado sólo
+ * escribían `url`, así que el operador se quedaba sin el mensaje.
+ *
+ * Tres casos, sin perder información y sin duplicar el enlace:
+ *  - sin `shareText`            → sólo la URL
+ *  - `shareText` con el sitio ya mencionado → el mensaje tal cual
+ *  - `shareText` sin el sitio   → mensaje + espacio + URL
+ *
+ * "Sitio" se decide por ORIGIN, no por la URL exacta: la plantilla puede
+ * referenciar sólo la base (`{public_base_url}` → `https://ejemplo.com`)
+ * o la URL completa con el path (`…/p/{ref}`); en ambos casos el mensaje
+ * YA apunta al sitio y no se le pega nada al final. Antes se comparaba
+ * contra la URL completa, así que un mensaje con la base recibía la URL
+ * con código duplicada al final.
+ *
+ * @param url        Enlace resuelto (`urlTemplate`).
+ * @param shareText  Mensaje formateado opcional (`shareTextTemplate`).
+ */
+export function buildShareMessage(url: string, shareText?: string): string {
+  const text = (shareText ?? '').trim();
+  if (!text) return url;
+  if (url && mentionsSite(text, url)) return text;
+  return url ? `${text} ${url}` : text;
+}
+
+/** ¿El mensaje ya apunta al sitio de `url` (origin o URL exacta)? */
+function mentionsSite(text: string, url: string): boolean {
+  if (text.includes(url)) return true;
+  try {
+    const { origin } = new URL(url);
+    return origin !== 'null' && text.includes(origin);
+  } catch {
+    // `url` relativa (`/p/123`): sin origin que comparar, sólo la URL exacta.
+    return false;
+  }
+}
+
+/**
+ * Escribe en el portapapeles sin reventar: primero la API moderna, después
+ * el `textarea` + `execCommand` (obsoleto, pero sigue siendo el fallback
+ * que existe en contextos no seguros).
+ *
+ * Único punto del admin que sabe cómo copiar: `copy-share`, las acciones de
+ * fila del listado y cualquier widget futuro comparten este camino, en vez
+ * de reimplementar cada uno sus propios fallbacks.
+ *
+ * @returns `true` si el texto quedó copiado por alguna de las vías.
+ */
+export async function writeClipboard(text: string): Promise<boolean> {
+  const clipboard = typeof navigator !== 'undefined' ? navigator.clipboard : undefined;
+  if (clipboard && typeof clipboard.writeText === 'function') {
+    try {
+      await clipboard.writeText(text);
+      return true;
+    } catch {
+      // Permiso denegado o contexto no seguro: sigue al fallback legado.
+    }
+  }
+  return legacyCopy(text);
+}
+
+function legacyCopy(text: string): boolean {
+  if (typeof document === 'undefined' || typeof document.execCommand !== 'function') {
+    return false;
+  }
+  const area = document.createElement('textarea');
+  area.value = text;
+  area.setAttribute('readonly', '');
+  area.style.position = 'fixed';
+  area.style.top = '0';
+  area.style.opacity = '0';
+  document.body.appendChild(area);
+  area.select();
+
+  let copied = false;
+  try {
+    copied = document.execCommand('copy');
+  } catch {
+    copied = false;
+  }
+
+  document.body.removeChild(area);
+  return copied;
+}

package/src/lib/core/utils/context-resolver.spec.ts

@@ -0,0 +1,95 @@
+import { resolveEndpointPath } from './context-resolver';
+
+/**
+ * Plan `doc/context-sources-plan.md` · Fase 2.
+ *
+ * TDD: éstos son los tests RED del resolver puro. Congelan las reglas del
+ * contrato: resolución anidada, escalares, codificación, pereza (sin
+ * marcadores no se llama a ninguna fuente) y TODOS los casos fail-loud.
+ */
+describe('context-resolver — marcadores en paths de endpoints', () => {
+  const fuentes = {
+    auth: () => ({ user: { id: 'u_9', name: 'Ana' }, token: 'tok' }),
+    config: () => ({ pais: 'AR' }),
+    tenant: () => 'acme',
+    numero: () => 7,
+    ruta: () => 'a b/c',
+    vacio: () => '',
+    nulo: () => null,
+    objeto: () => ({ a: 1 }),
+    rota: () => {
+      throw new Error('boom fuente');
+    },
+  };
+
+  // ── Casos felices ────────────────────────────────────────────────────────
+  it('resuelve una ruta anidada {auth.user.id}', () => {
+    expect(resolveEndpointPath('/businesses/{auth.user.id}/orders', fuentes)).toBe(
+      '/businesses/u_9/orders',
+    );
+  });
+
+  it('resuelve la fuente entera {tenant}', () => {
+    expect(resolveEndpointPath('/tenants/{tenant}/orders', fuentes)).toBe('/tenants/acme/orders');
+  });
+
+  it('convierte escalares a texto', () => {
+    expect(resolveEndpointPath('/page/{numero}', fuentes)).toBe('/page/7');
+  });
+
+  it('codifica cada valor como segmento de URL', () => {
+    expect(resolveEndpointPath('/x/{ruta}/y', fuentes)).toBe('/x/a%20b%2Fc/y');
+  });
+
+  it('resuelve varios marcadores en un mismo path', () => {
+    expect(
+      resolveEndpointPath('/tenants/{tenant}/businesses/{auth.user.id}/paises/{config.pais}', fuentes),
+    ).toBe('/tenants/acme/businesses/u_9/paises/AR');
+  });
+
+  it('sin marcadores devuelve el path tal cual y NO llama a ninguna fuente', () => {
+    const perezosa = {
+      auth: () => {
+        throw new Error('no debe evaluarse sin marcadores');
+      },
+    };
+    expect(resolveEndpointPath('/admin/products', perezosa)).toBe('/admin/products');
+  });
+
+  it('resuelve un marcador dentro de un path que ya lleva query string', () => {
+    expect(resolveEndpointPath('/orders?owner={auth.user.id}&limit=10', fuentes)).toBe(
+      '/orders?owner=u_9&limit=10',
+    );
+  });
+
+  // ── Fail loud ────────────────────────────────────────────────────────────
+  it('valor ausente ⇒ error que nombra el path y el marcador', () => {
+    const path = '/x/{auth.user.nope}/y';
+    expect(() => resolveEndpointPath(path, fuentes)).toThrow(path);
+    expect(() => resolveEndpointPath(path, fuentes)).toThrow('auth.user.nope');
+  });
+
+  it('valor vacío ⇒ error, nunca un segmento vacío en la URL', () => {
+    expect(() => resolveEndpointPath('/x/{vacio}/y', fuentes)).toThrow('/x/{vacio}/y');
+  });
+
+  it('valor nulo ⇒ error', () => {
+    expect(() => resolveEndpointPath('/x/{nulo}', fuentes)).toThrow('nulo');
+  });
+
+  it('fuente no registrada ⇒ error con el nombre de la fuente', () => {
+    expect(() => resolveEndpointPath('/x/{desconocida.id}', fuentes)).toThrow('desconocida');
+  });
+
+  it('getter que revienta ⇒ su error se propaga tal cual', () => {
+    expect(() => resolveEndpointPath('/x/{rota}', fuentes)).toThrow('boom fuente');
+  });
+
+  it('{key} sin resolver ⇒ error que aclara que sólo aplica a operaciones con clave', () => {
+    expect(() => resolveEndpointPath('/x/{key}', fuentes)).toThrow('key');
+  });
+
+  it('valor no escalar ⇒ error, nunca [object Object] en la URL', () => {
+    expect(() => resolveEndpointPath('/x/{objeto}', fuentes)).toThrow('objeto');
+  });
+});

package/src/lib/core/utils/context-resolver.ts

@@ -0,0 +1,101 @@
+/**
+ * Resolución de marcadores de contexto en paths de endpoints.
+ *
+ * Plan `doc/context-sources-plan.md` · Fase 2. Lógica PURA: ni HTTP ni DI —
+ * recibe un path y un mapa de getters de fuentes y devuelve el path ya
+ * resuelto, o revienta.
+ *
+ * Reglas del contrato (R1–R4 del plan):
+ *
+ * - `{<fuente>}` / `{<fuente>.<ruta.anidada>}` → valor de la fuente en el
+ *   momento de la llamada (los getters se evalúan SOLO si hay marcadores).
+ * - Cada valor se codifica como segmento de URL (`encodeURIComponent`).
+ * - **Fail loud**: fuente no registrada, valor ausente/vacío, valor no
+ *   escalar o `{key}` sin resolver ⇒ error que nombra el path y el marcador.
+ *   Jamás se devuelve un segmento vacío ni el texto literal del marcador.
+ * - Sin marcadores ⇒ el path vuelve intacto y ninguna fuente se evalúa.
+ *
+ * OJO con `interpolateTemplate` (R3): su semántica «ausente ⇒ cadena vacía»
+ * es correcta para acciones y fuentes de datos, pero acá sería un 404 mudo.
+ * Por eso la lectura y la validación viven en este fichero y ese helper no
+ * se toca.
+ */
+
+/** `{nombre}` o `{nombre.ruta.anidada}` — misma forma que usa el interpolador. */
+const MARKER = /\{([a-zA-Z0-9_.]+)\}/g;
+
+/**
+ * Resuelve los marcadores de `path` contra `sources`.
+ *
+ * @param path Path declarado en `ResourceEndpoints`, tal cual vino del schema.
+ * @param sources Getters por nombre de fuente (`auth`, `config`, `valueSources`…).
+ * @returns El path con cada marcador sustituido y codificado.
+ * @throws Error nombrando path y marcador ante cualquier valor irresoluble.
+ */
+export function resolveEndpointPath(
+  path: string,
+  sources: Readonly<Record<string, () => unknown>>,
+): string {
+  if (!path.includes('{')) return path;
+  return path.replace(MARKER, (marker, nombre: string) =>
+    sustituir(path, marker, nombre, sources),
+  );
+}
+
+/** Sustituye UN marcador. `path` completo sólo viaja para el mensaje de error. */
+function sustituir(
+  path: string,
+  marker: string,
+  nombre: string,
+  sources: Readonly<Record<string, () => unknown>>,
+): string {
+  if (nombre === 'key') {
+    throw new Error(
+      `[gas-admin-ui] path '${path}': ${marker} llegó sin resolver — ` +
+        `la clave sólo la sustituyen get/update/remove antes de resolver el contexto.`,
+    );
+  }
+
+  const punto = nombre.indexOf('.');
+  const fuente = punto === -1 ? nombre : nombre.slice(0, punto);
+  const getter = sources[fuente];
+  if (typeof getter !== 'function') {
+    throw new Error(
+      `[gas-admin-ui] path '${path}': no se pudo resolver ${marker} — ` +
+        `la fuente '${fuente}' no está registrada.`,
+    );
+  }
+
+  // El getter se evalúa acá y sólo acá: si revienta, su error se propaga.
+  const valor = punto === -1 ? getter() : leerRuta(getter(), nombre.slice(punto + 1));
+
+  if (valor === undefined || valor === null) {
+    throw new Error(
+      `[gas-admin-ui] path '${path}': no se pudo resolver ${marker} — sin valor para '${nombre}'.`,
+    );
+  }
+  if (typeof valor === 'object') {
+    throw new Error(
+      `[gas-admin-ui] path '${path}': no se pudo resolver ${marker} — ` +
+        `el valor de '${fuente}' no es un segmento de URL (no es escalar).`,
+    );
+  }
+
+  const texto = String(valor);
+  if (texto === '') {
+    throw new Error(
+      `[gas-admin-ui] path '${path}': no se pudo resolver ${marker} — valor vacío en '${fuente}'.`,
+    );
+  }
+  return encodeURIComponent(texto);
+}
+
+/** Lectura profunda `a.b.c` sobre el valor de la fuente; inexistente ⇒ `undefined`. */
+function leerRuta(valor: unknown, ruta: string): unknown {
+  let actual: unknown = valor;
+  for (const paso of ruta.split('.')) {
+    if (actual === null || typeof actual !== 'object') return undefined;
+    actual = (actual as Record<string, unknown>)[paso];
+  }
+  return actual;
+}

package/src/lib/core/utils/response-unwrapper.spec.ts

@@ -0,0 +1,70 @@
+import { extractPagination } from './response-unwrapper';
+
+// Extracción de metadata de paginación (plan doc/engine-refactor-plan.md · Fase 2.2)
+// Lo consume `listPage()` (Fase 3); acá se prueba la utilidad pura.
+describe('extractPagination', () => {
+  it('lee cursor/total/hasMore de meta cuando metaKey está declarado', () => {
+    const raw = { data: [{ slug: 'a' }], meta: { cursor: 'c1', count: 10, more: true } };
+    const result = extractPagination(raw, {
+      dataKey: 'data',
+      metaKey: 'meta',
+      pagination: { cursorKey: 'cursor', totalKey: 'count', hasMoreKey: 'more' },
+    });
+    expect(result).toEqual({ nextCursor: 'c1', total: 10, hasMore: true });
+  });
+
+  it('auto-detecta claves comunes (nextCursor, total, hasMore) en el body', () => {
+    const raw = { items: [{ slug: 'a' }], nextCursor: 'tok', total: 42, hasMore: true };
+    expect(extractPagination(raw, { dataKey: 'items' })).toEqual({
+      nextCursor: 'tok',
+      total: 42,
+      hasMore: true,
+    });
+  });
+
+  it('sin cursor ni claves de paginación ⇒ nextCursor null, total 0, hasMore false', () => {
+    const raw = { items: [{ slug: 'a' }] };
+    expect(extractPagination(raw, undefined)).toEqual({
+      nextCursor: null,
+      total: 0,
+      hasMore: false,
+    });
+  });
+
+  it('con cursor presente y sin flag hasMore explícito ⇒ hasMore true (derivado)', () => {
+    const raw = { items: [], nextCursor: 'c2' };
+    expect(extractPagination(raw, undefined)).toEqual({
+      nextCursor: 'c2',
+      total: 0,
+      hasMore: true,
+    });
+  });
+
+  it('metaKey declarado pero ausente en el body ⇒ cae al body', () => {
+    const raw = { items: [], nextCursor: 'c3', total: 7 };
+    const result = extractPagination(raw, { dataKey: 'items', metaKey: 'meta' });
+    expect(result).toEqual({ nextCursor: 'c3', total: 7, hasMore: true });
+  });
+
+  it('cursor vacío string se trata como ausente (nextCursor null, hasMore false)', () => {
+    const raw = { items: [], nextCursor: '' };
+    expect(extractPagination(raw, undefined)).toEqual({
+      nextCursor: null,
+      total: 0,
+      hasMore: false,
+    });
+  });
+
+  it('cuerpo no-objeto ⇒ sin paginación (no lanza)', () => {
+    expect(extractPagination(null, undefined)).toEqual({
+      nextCursor: null,
+      total: 0,
+      hasMore: false,
+    });
+  });
+
+  it('hasMoreKey explícito tiene prioridad sobre el derivado del cursor', () => {
+    const raw = { items: [], nextCursor: 'c9', hasMore: false };
+    expect(extractPagination(raw, undefined).hasMore).toBe(false);
+  });
+});

package/src/lib/core/utils/response-unwrapper.ts

@@ -0,0 +1,103 @@
+/**
+ * Desempaquetado opt-in de respuestas HTTP anidadas (`{ data, meta }`,
+ * `{ items, total }`, o claves arbitrarias).
+ *
+ * El motor NO asume un sobre: sólo desempaqueta cuando la declaración
+ * `ResponseUnwrap` está presente. Sin ella, el comportamiento actual se
+ * conserva (arreglo plano, `{ items }`, u objeto crudo).
+ *
+ * Mantener esta lógica aquí (y no en `ApiService`) deja el servicio enfocado
+ * en el despacho y facilita la prueba de las reglas de unwrap.
+ */
+
+import type { ResponseUnwrap } from '../models/schema.model';
+
+export type UnwrapOperation = 'list' | 'get' | 'create' | 'update' | 'remove';
+
+/**
+ * Devuelve `true` si la declaración `unwrap` aplica a la operación dada.
+ * Si `apply` falta, se asume `'all'` (decisión fija del plan).
+ */
+export function appliesTo(unwrap: ResponseUnwrap, operation: UnwrapOperation): boolean {
+  const apply = unwrap.apply ?? 'all';
+  return apply === 'all' || apply === operation;
+}
+
+/**
+ * Extrae el payload declarado por `unwrap.dataKey` del cuerpo `raw`.
+ *
+ * - Si `unwrap` no aplica a `operation`, devuelve `raw` tal cual.
+ * - Si aplica y `raw` tiene la clave, devuelve su valor.
+ * - Si aplica y la clave falta, lanza un `Error` descriptivo (no silencia).
+ */
+export function unwrapResponse(raw: unknown, unwrap: ResponseUnwrap | undefined, operation: UnwrapOperation): unknown {
+  if (!unwrap || !appliesTo(unwrap, operation)) {
+    return raw;
+  }
+  if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) {
+    const record = raw as Record<string, unknown>;
+    if (Object.prototype.hasOwnProperty.call(record, unwrap.dataKey)) {
+      return record[unwrap.dataKey];
+    }
+  }
+  throw new Error(
+    `Response unwrap declared dataKey '${unwrap.dataKey}' but it is missing in the response for operation '${operation}'`,
+  );
+}
+
+/** Metadata de paginación extraída del sobre; la consume `ApiService.listPage()`. */
+export interface PaginationMeta {
+  nextCursor: string | null;
+  total: number;
+  hasMore: boolean;
+}
+
+const NO_PAGINATION: PaginationMeta = { nextCursor: null, total: 0, hasMore: false };
+
+/**
+ * Extrae la metadata de paginación del cuerpo `raw` según la declaración
+ * `unwrap.pagination` (cursorKey/totalKey/hasMoreKey).
+ *
+ * - Con `metaKey` declarado Y presente en el body, las claves se leen de ese
+ *   sub-objeto; si no, del body raíz.
+ * - Sin claves declaradas se auto-detectan las comunes: `nextCursor`,
+ *   `total`, `hasMore`.
+ * - `hasMore` explícito (boolean) tiene prioridad; sin él se deriva del
+ *   cursor: presente ⇒ `true`, ausente/vacío ⇒ `false`.
+ * - Cuerpo no-objeto ⇒ sin paginación. Nunca lanza: la paginación es
+ *   opt-in y su ausencia sólo significa `hasMore = false`.
+ */
+export function extractPagination(
+  raw: unknown,
+  unwrap: ResponseUnwrap | undefined,
+): PaginationMeta {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ...NO_PAGINATION };
+  }
+  const body = raw as Record<string, unknown>;
+
+  let source = body;
+  const metaKey = unwrap?.metaKey;
+  if (metaKey) {
+    const meta = body[metaKey];
+    if (meta !== null && typeof meta === 'object' && !Array.isArray(meta)) {
+      source = meta as Record<string, unknown>;
+    }
+  }
+
+  const cursorKey = unwrap?.pagination?.cursorKey ?? 'nextCursor';
+  const totalKey = unwrap?.pagination?.totalKey ?? 'total';
+  const hasMoreKey = unwrap?.pagination?.hasMoreKey ?? 'hasMore';
+
+  const cursorValue = source[cursorKey] ?? body[cursorKey];
+  const nextCursor = typeof cursorValue === 'string' && cursorValue !== '' ? cursorValue : null;
+
+  const totalValue = source[totalKey] ?? body[totalKey];
+  const total = typeof totalValue === 'number' ? totalValue : 0;
+
+  const hasMoreValue = source[hasMoreKey] ?? body[hasMoreKey];
+  const hasMore =
+    typeof hasMoreValue === 'boolean' ? hasMoreValue : nextCursor !== null;
+
+  return { nextCursor, total, hasMore };
+}

package/src/lib/core/utils/source-options.spec.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import type { DataSource, ResourceSchema } from '../models/schema.model';
+import { optionsFromRows } from './source-options';
+
+const TARGET: ResourceSchema = {
+  id: 'categories',
+  label: 'Categoría',
+  labelPlural: 'Categorías',
+  kind: 'collection',
+  endpoint: { list: '/admin/categories' },
+  keyField: 'slug',
+  titleField: 'name',
+  listColumns: [],
+  fields: [],
+};
+
+const FILAS = [
+  { slug: 'bebidas', name: 'Bebidas', description: 'Frías', active: true },
+  { slug: 'pan', name: '', description: '', active: false },
+];
+
+const source = (extra: Partial<DataSource> = {}): DataSource => ({
+  resource: 'categories',
+  ...extra,
+});
+
+describe('optionsFromRows', () => {
+  it('usa valueField/labelField declarados en la fuente', () => {
+    const opciones = optionsFromRows(FILAS, {
+      source: source({ valueField: 'slug', labelField: 'name' }),
+      target: TARGET,
+    });
+    expect(opciones).toEqual([
+      { value: 'bebidas', label: 'Bebidas' },
+      { value: 'pan', label: 'pan' }, // label vacío ⇒ cae al valor
+    ]);
+  });
+
+  it('sin los campos declarados cae a keyField/titleField del recurso destino', () => {
+    const opciones = optionsFromRows(FILAS, { source: source(), target: TARGET });
+    expect(opciones[0]).toEqual({ value: 'bebidas', label: 'Bebidas' });
+  });
+
+  it('sin nada declarado el valor es `id` (último recurso conocido)', () => {
+    const opciones = optionsFromRows([{ id: 'x' }], {
+      source: source(),
+      target: undefined,
+    });
+    expect(opciones).toEqual([{ value: 'x', label: 'x' }]);
+  });
+
+  it('una fila sin valor no es opción: no hay qué seleccionar', () => {
+    const opciones = optionsFromRows(
+      [{ slug: '', name: 'Vacía' }, { name: 'Sin clave' }, { slug: null, name: 'Nula' }],
+      { source: source({ valueField: 'slug', labelField: 'name' }), target: TARGET },
+    );
+    expect(opciones).toEqual([]);
+  });
+
+  it('`onlyActive` descarta las inactivas en el cliente', () => {
+    const opciones = optionsFromRows(FILAS, {
+      source: source({ valueField: 'slug', labelField: 'name' }),
+      target: TARGET,
+      onlyActive: true,
+    });
+    expect(opciones.map((o) => o.value)).toEqual(['bebidas']);
+  });
+
+  it('secondaryField añade el dato con « · », y se cae si no hay dato', () => {
+    const opciones = optionsFromRows(
+      [
+        { slug: 'a', name: 'A', description: 'Frías' },
+        { slug: 'b', name: 'B', description: '' },
+        { slug: 'c', name: 'C' },
+      ],
+      {
+        source: source({ valueField: 'slug', labelField: 'name' }),
+        target: TARGET,
+        secondaryField: 'description',
+      },
+    );
+    expect(opciones.map((o) => o.label)).toEqual(['A · Frías', 'B', 'C']);
+  });
+
+  it('no muta las filas de entrada', () => {
+    const filas = [{ slug: 'a', name: 'A', active: false }];
+    const copia = JSON.parse(JSON.stringify(filas));
+    optionsFromRows(filas, {
+      source: source({ valueField: 'slug', labelField: 'name' }),
+      target: TARGET,
+      onlyActive: true,
+    });
+    expect(filas).toEqual(copia);
+  });
+});

package/src/lib/core/utils/source-options.ts

@@ -0,0 +1,54 @@
+import type { DataSource, ResourceSchema, SelectOption } from '../models/schema.model';
+
+/** Contexto de mapeo: la fuente declarada más las particularidades del campo. */
+export interface RowsToOptions {
+  /** Fuente de la que salieron las filas (F8 · R6.5). */
+  source: DataSource;
+  /** Schema del recurso destino: aporta `keyField`/`titleField` por defecto. */
+  target: ResourceSchema | undefined;
+  /** Descarta filas con `active: false` (`relation.onlyActive`). */
+  onlyActive?: boolean;
+  /** Dato secundario junto a la etiqueta («Juan Pérez · DNI 123»). */
+  secondaryField?: string;
+}
+
+/**
+ * Filas de una fuente declarada → opciones de desplegable (F8 · R6.5).
+ *
+ * Es el ÚNICO punto que traduce filas a `SelectOption`: antes esa regla
+ * estaba escrita dos veces (en `relation` y cada consumidor montaba su
+ * propia petición). Con `source` compartido, relaciones y desplegables con
+ * datos remotos pasan por acá.
+ *
+ * Reglas, en orden:
+ * - valor: `source.valueField` → `target.keyField` → `id`;
+ * - etiqueta: `source.labelField` → `target.titleField` → el valor;
+ * - fila sin valor (vacío o inexistente) no es opción: no hay qué seleccionar;
+ * - `onlyActive` descarta las inactivas en el cliente — el back ya las excluye
+ *   de su FK, pero una lista cacheada puede traer una fila vieja.
+ */
+export function optionsFromRows(
+  rows: readonly Record<string, unknown>[],
+  { source, target, onlyActive, secondaryField }: RowsToOptions,
+): SelectOption[] {
+  const valueKey = source.valueField ?? target?.keyField ?? 'id';
+  const labelKey = source.labelField ?? target?.titleField ?? valueKey;
+  const options: SelectOption[] = [];
+  for (const row of rows) {
+    if (onlyActive === true && row['active'] === false) continue;
+    const value = row[valueKey];
+    if (value === undefined || value === null || value === '') continue;
+    const label = row[labelKey];
+    const primary = typeof label === 'string' && label !== '' ? label : String(value);
+    options.push({ value: String(value), label: withSecondary(primary, row, secondaryField) });
+  }
+  return options;
+}
+
+/** Etiqueta con su dato secundario, o la etiqueta tal cual si no hay. */
+function withSecondary(primary: string, row: Record<string, unknown>, key?: string): string {
+  if (key === undefined) return primary;
+  const secondary = row[key];
+  if (secondary === undefined || secondary === null || secondary === '') return primary;
+  return `${primary} · ${String(secondary)}`;
+}

package/src/lib/core/utils/template-interpolator.spec.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { interpolateTemplate } from './template-interpolator';
+
+describe('interpolateTemplate', () => {
+  it('1. interpola variables simples en la plantilla', () => {
+    const template = 'https://ejemplo.com/p/{ref}?cliente={customer_name}';
+    const data = { ref: 'ORD-123', customer_name: 'Juan Perez' };
+
+    const result = interpolateTemplate(template, data);
+
+    expect(result).toBe('https://ejemplo.com/p/ORD-123?cliente=Juan Perez');
+  });
+
+  it('2. reemplaza variables nulas o indefinidas por cadena vacía', () => {
+    const template = 'Pedido {ref} - Estado: {status}';
+    const data = { ref: 'ORD-999' };
+
+    const result = interpolateTemplate(template, data);
+
+    expect(result).toBe('Pedido ORD-999 - Estado: ');
+  });
+
+  it('3. resuelve claves anidadas usando notación de punto', () => {
+    const template = 'ID: {order.meta.id} - Nombre: {order.customer.name}';
+    const data = {
+      order: {
+        meta: { id: 'M-55' },
+        customer: { name: 'Maria' },
+      },
+    };
+
+    const result = interpolateTemplate(template, data);
+
+    expect(result).toBe('ID: M-55 - Nombre: Maria');
+  });
+
+  it('4. recurre al contexto adicional si la clave no está en data', () => {
+    const template = '{public_base_url}/p/{ref}';
+    const data = { ref: 'PED-404' };
+    const extraContext = { public_base_url: 'https://retiro.tienda.com' };
+
+    const result = interpolateTemplate(template, data, extraContext);
+
+    expect(result).toBe('https://retiro.tienda.com/p/PED-404');
+  });
+
+  it('5. devuelve la misma plantilla si no contiene marcadores', () => {
+    const template = 'Texto plano sin variables';
+    const result = interpolateTemplate(template, { a: 1 });
+
+    expect(result).toBe('Texto plano sin variables');
+  });
+
+  it('6. maneja plantillas vacías o nulas sin romper', () => {
+    expect(interpolateTemplate('', { ref: '123' })).toBe('');
+    // @ts-expect-error probando valor nulo
+    expect(interpolateTemplate(null, { ref: '123' })).toBe('');
+  });
+});