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

package/src/lib/actions/action-service.ts

@@ -0,0 +1,87 @@
+import { Service, inject } from '@angular/core';
+
+import {
+  actionType,
+  getAction,
+  type ActionContext,
+  type ActionRequest,
+  type ActionResult,
+} from './action-registry';
+import type { ResourceAction } from '../core/models/schema.model';
+import { ConfigService } from '../core/services/config.service';
+import { ErrorMapperService } from '../core/services/error-mapper.service';
+
+/**
+ * Ejecuta una acción declarada en el schema (R3.9 · `refactormotor.md`).
+ *
+ * Sustituye el dispatch por tipo que hoy vive en `list-view` y en las
+ * copias de `detail-view` y `post-create-modal` (R3.11). El camino siempre
+ * es el mismo:
+ *
+ *   1. resolver el descriptor (si no existe, **rompe** — nada de «disponible
+ *      próximamente», que hoy oculta esquemas mal declarados);
+ *   2. pedir confirmación si el descriptor la exige;
+ *   3. montar el `ActionContext` (petición + `vars` de interpolación);
+ *   4. ejecutar y, si el descriptor lanza, notificar el error y devolver
+ *      `{ ok: false }` para que la vista no trate el fallo como éxito.
+ */
+@Service()
+export class ActionService {
+  private readonly config = inject(ConfigService);
+  private readonly errores = inject(ErrorMapperService);
+
+  async run(action: ResourceAction, request: ActionRequest): Promise<ActionResult> {
+    const type = actionType(action);
+    const descriptor = getAction(type);
+    if (!descriptor) {
+      throw new Error(
+        `[actions] «${action.label}» no tiene descriptor registrado (type "${type}").`,
+      );
+    }
+
+    if (descriptor.confirm) {
+      const aceptado = await request.toast.confirm({
+        title: action.label,
+        message: confirmMessage(action),
+        confirmLabel: 'Confirmar',
+        cancelLabel: 'Cancelar',
+      });
+      if (!aceptado) {
+        return { ok: false };
+      }
+    }
+
+    // `copy-share` (R8.7) resuelve su mensaje contra la config global
+    // (`share_message_template`). Si el load del bootstrap no llegó (arranque
+    // sin sesión o red lenta), lo pedimos ahora —con la sesión ya iniciada—
+    // ANTES de congelar `vars`: si no, el mensaje copiado degradaría a
+    // «sólo la URL» hasta el próximo F5.
+    if (descriptor.type === 'copy-share') {
+      await this.config.ensureLoaded();
+    }
+
+    const ctx: ActionContext = { ...request, vars: this.vars(request.record) };
+    try {
+      return await descriptor.run(ctx, action);
+    } catch (err) {
+      request.toast.error(this.errores.messageOf(err));
+      return { ok: false };
+    }
+  }
+
+  /**
+   * Config global + registro. Sin registro (`header`, `bulk`) el contexto de
+   * interpolación queda vacío: el descriptor no tiene nada que interpolar.
+   *
+   * Público porque `detail-view` sólo **presenta** una acción (pinta
+   * `<app-copy-share>`) en vez de ejecutarla, y aun así necesita el mismo
+   * contexto: R3.11 acabó con la tercera copia de esta lógica.
+   */
+  vars(record: Record<string, unknown> | null): Record<string, unknown> {
+    return record ? this.config.buildInterpolationContext(record) : {};
+  }
+}
+
+function confirmMessage(action: ResourceAction): string {
+  return 'confirmMessage' in action && action.confirmMessage ? action.confirmMessage : action.label;
+}

package/src/lib/actions/descriptors.spec.ts

@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from 'vitest';
+import { of } from 'rxjs';
+
+import { getAction, type ActionContext } from './action-registry';
+import { resolveShare } from './descriptors';
+import type { CopyShareAction, NavigateAction, TriggerAction } from '../core/models/schema.model';
+import type { ApiService } from '../core/services/api.service';
+import type { NotificationService } from '../core/services/notification.service';
+import type { Router } from '@angular/router';
+
+const VARS = { public_base_url: 'https://demo', ref: 'p1', customer_name: 'Ana' };
+
+const COMPARTIR: CopyShareAction = {
+  id: 'share',
+  label: 'Compartir',
+  type: 'copy-share',
+  urlTemplate: '{public_base_url}/p/{ref}',
+  shareTextTemplate: 'Hola {customer_name}, tu pedido {ref}',
+};
+
+function contexto(): ActionContext {
+  return {
+    record: { ref: 'p1' },
+    resource: 'orders',
+    api: { request: vi.fn().mockReturnValue(of({ ok: true })) } as unknown as ApiService,
+    router: { navigateByUrl: vi.fn().mockResolvedValue(true) } as unknown as Router,
+    toast: {
+      success: vi.fn(),
+      error: vi.fn(),
+      info: vi.fn(),
+      confirm: vi.fn(),
+      dismiss: vi.fn(),
+    } as unknown as NotificationService,
+    user: null,
+    keyField: 'ref',
+    vars: VARS,
+  };
+}
+
+/** El `run` de un tipo registrado; lanza si no existe (estado incoherente). */
+function ejecutar(type: string, action: CopyShareAction | NavigateAction | TriggerAction) {
+  const descriptor = getAction(type);
+  if (!descriptor) throw new Error(`sin descriptor «${type}»`);
+  return descriptor.run;
+}
+
+describe('resolveShare', () => {
+  it('interpola enlace y mensaje con el contexto del registro', () => {
+    expect(resolveShare(COMPARTIR, VARS)).toEqual({
+      url: 'https://demo/p/p1',
+      shareText: 'Hola Ana, tu pedido p1',
+    });
+  });
+
+  it('sin shareTextTemplate cae a share_message_template (config global)', () => {
+    const action: CopyShareAction = { ...COMPARTIR, shareTextTemplate: undefined };
+    expect(resolveShare(action, { ...VARS, share_message_template: 'Hola {ref}' })).toEqual({
+      url: 'https://demo/p/p1',
+      shareText: 'Hola p1',
+    });
+  });
+
+  it('sin plantilla ninguna el mensaje queda vacío', () => {
+    const action: CopyShareAction = { ...COMPARTIR, shareTextTemplate: undefined };
+    expect(resolveShare(action, VARS).shareText).toBe('');
+  });
+});
+
+describe('descriptores de acción', () => {
+  const escritor = vi.fn().mockResolvedValue(undefined);
+  let abrir: MockInstance;
+
+  beforeEach(() => {
+    escritor.mockClear();
+    Object.defineProperty(window.navigator, 'clipboard', {
+      value: { writeText: escritor },
+      configurable: true,
+    });
+    abrir = vi.spyOn(window, 'open').mockReturnValue(null);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('copy-share copia el mensaje completo y lo anuncia', async () => {
+    const ctx = contexto();
+    const resultado = await ejecutar('copy-share', COMPARTIR)(ctx, COMPARTIR);
+
+    expect(escritor).toHaveBeenCalledWith('Hola Ana, tu pedido p1 https://demo/p/p1');
+    expect(ctx.toast.success).toHaveBeenCalledWith('Mensaje copiado al portapapeles.');
+    expect(resultado).toEqual({ ok: true });
+  });
+
+  it('navigate abre una URL absoluta en otra pestaña', async () => {
+    const action: NavigateAction = {
+      id: 'ver',
+      label: 'Ver público',
+      urlTemplate: '{public_base_url}/p/{ref}',
+    };
+    const ctx = contexto();
+
+    await ejecutar('navigate', action)(ctx, action);
+
+    expect(abrir).toHaveBeenCalledWith('https://demo/p/p1', '_blank', 'noopener');
+    expect(ctx.router.navigateByUrl).not.toHaveBeenCalled();
+  });
+
+  it('navigate entrega una ruta interna al router', async () => {
+    const action: NavigateAction = { id: 'editar', label: 'Editar', urlTemplate: '/orders/p1' };
+    const ctx = contexto();
+
+    await ejecutar('navigate', action)(ctx, action);
+
+    expect(ctx.router.navigateByUrl).toHaveBeenCalledWith('/orders/p1');
+    expect(abrir).not.toHaveBeenCalled();
+  });
+
+  it('trigger arma la ruta lógica de la acción declarada y pide recarga', async () => {
+    const action: TriggerAction = {
+      id: 'markDelivered',
+      label: 'Marcar entregado',
+      type: 'trigger',
+    };
+    const ctx = contexto();
+
+    const resultado = await ejecutar('trigger', action)(ctx, action);
+
+    expect(ctx.api.request).toHaveBeenCalledWith('POST', '/admin/orders/p1/actions/markDelivered');
+    expect(resultado).toEqual({ ok: true, reload: true });
+  });
+
+  it('trigger usa `name` cuando en el back se llama distinto que el `id`', async () => {
+    const action: TriggerAction = {
+      id: 'reenviar',
+      label: 'Reenviar pin',
+      type: 'trigger',
+      name: 'resendPin',
+    };
+    const ctx = contexto();
+
+    await ejecutar('trigger', action)(ctx, action);
+
+    expect(ctx.api.request).toHaveBeenCalledWith('POST', '/admin/orders/p1/actions/resendPin');
+  });
+
+  it('sin clave de registro no dispara nada y lo dice (fail-loud)', async () => {
+    const action: TriggerAction = { id: 'markDelivered', label: 'Marcar', type: 'trigger' };
+    const ctx = contexto();
+    ctx.record = null;
+
+    await expect(ejecutar('trigger', action)(ctx, action)).rejects.toThrow('necesita la clave ref');
+    expect(ctx.api.request).not.toHaveBeenCalled();
+  });
+});

package/src/lib/actions/descriptors.ts

@@ -0,0 +1,154 @@
+import { firstValueFrom } from 'rxjs';
+import { LucideShare2 } from '@lucide/angular';
+
+import type { ActionDescriptor } from './action-registry';
+import type {
+  CopyShareAction,
+  NavigateAction,
+  ResourceAction,
+  TriggerAction,
+} from '../core/models/schema.model';
+import { buildShareMessage, writeClipboard } from '../core/utils/clipboard';
+import { interpolateTemplate } from '../core/utils/template-interpolator';
+
+/**
+ * Descriptores de las tres acciones que hoy declara el modelo
+ * (R3.10 · `doc/plan-refactor-motor.md` §3.2).
+ *
+ * Éste es el fichero que **cierra la triplicación de `copy-share`**: la
+ * resolución de enlace y de mensaje vivía en `list-view.runAction`,
+ * `detail-view.resolveUrl/resolveShareText` y
+ * `post-create-modal.resolvedShareUrl/resolvedShareText`. Aquí se resuelve
+ * una sola vez (`resolveShare`) y las vistas consumen ese resultado en R3.11.
+ *
+ * Se registra al importar, desde `action-registry.ts`, con el mismo criterio
+ * que el registro de render: sin esperar a DI, porque el registro es la única
+ * fuente de verdad en runtime.
+ */
+
+/** Enlace y mensaje ya interpolados, listos para copiar o compartir. */
+export interface ResolvedShare {
+  url: string;
+  shareText: string;
+}
+
+/**
+ * `true` cuando la acción es de las que las vistas presentan como botón de
+ * compartir (`detail-view`, `post-create-modal`).
+ *
+ * Vive acá y no en la vista porque es **el único sitio donde se puede nombrar
+ * `'copy-share'`**: fuera de `descriptors.ts` ninguna vista decide por tipo
+ * (criterio de R3.11).
+ */
+export function isShareAction(action: ResourceAction): action is CopyShareAction {
+  return action.type === 'copy-share';
+}
+
+/**
+ * `true` cuando la acción es un `trigger` (acción de dominio del back).
+ *
+ * Mismo criterio que `isShareAction`: el único sitio que nombra el tipo,
+ * para que las vistas no decidan por string literal (R3.11). `detail-view`
+ * lo usa en R8.8 para renderizar «Regenerar PIN» junto a los botones de
+ * compartir.
+ */
+export function isTriggerAction(action: ResourceAction): action is TriggerAction {
+  return action.type === 'trigger';
+}
+
+/**
+ * Resuelve `urlTemplate` y el mensaje de compartir contra `vars`
+ * (config global + registro).
+ *
+ * **Única implementación** de esta lógica en el admin. El fallback a
+ * `share_message_template` (la plantilla que declara el singleton de
+ * configuración) lo aplican los tres puntos por igual: hasta ahora la fila
+ * del listado no lo honraba y se quedaba sin saludo.
+ */
+export function resolveShare(
+  action: CopyShareAction,
+  vars: Record<string, unknown>,
+): ResolvedShare {
+  const template =
+    action.shareTextTemplate || (vars['share_message_template'] as string | undefined);
+  return {
+    url: interpolateTemplate(action.urlTemplate, vars),
+    shareText: template ? interpolateTemplate(template, vars) : '',
+  };
+}
+
+/** `copy-share` — copia (o comparte) el mensaje completo del enlace público. */
+const copyShare: ActionDescriptor = {
+  type: 'copy-share',
+  surfaces: ['row', 'detail', 'post-create'],
+  // Icono de la fila del listado: la vista sólo decide entre «icono» y
+  // «rótulo», nunca por tipo. Se pasa la CLASE, no el nombre: sin
+  // `provideLucideIcons` no hay riesgo de `Unable to resolve icon`.
+  icon: LucideShare2,
+  run: async (ctx, action) => {
+    const { url, shareText } = resolveShare(action as CopyShareAction, ctx.vars);
+    const message = buildShareMessage(url, shareText);
+    const copied = await writeClipboard(message);
+    if (copied) {
+      ctx.toast.success('Mensaje copiado al portapapeles.');
+    } else {
+      ctx.toast.info(`Copiar manualmente: ${message}`);
+    }
+    return { ok: true };
+  },
+};
+
+/**
+ * `navigate` — abre la plantilla resuelta: URL absoluta en otra pestaña,
+ * ruta interna en el router. `NavigateAction.type` es opcional, así que el
+ * servicio llega acá también con una acción que no declara `type`.
+ */
+const navigate: ActionDescriptor = {
+  type: 'navigate',
+  surfaces: ['row', 'detail'],
+  run: async (ctx, action) => {
+    const url = interpolateTemplate((action as NavigateAction).urlTemplate, ctx.vars);
+    if (/^https?:\/\//.test(url)) {
+      window.open(url, '_blank', 'noopener');
+    } else {
+      await ctx.router.navigateByUrl(url);
+    }
+    return { ok: true };
+  },
+};
+
+/**
+ * `trigger` — dispara una **acción de dominio declarada en el back** (B3).
+ *
+ * **R3.12:** el destino ya no lo declara el schema (`endpoint` y `method`
+ * murieron en este cambio). Se deriva de `resource` + clave del registro +
+ * `name` (o `id`), que es exactamente la ruta que el back publica solo en
+ * R5.4: `POST /admin/<recurso>/:id/actions/<name>`.
+ *
+ * ⚠️ **O2:** la ruta lógica viaja en el `path` del envelope, no en la URL —
+ * el HTTP sigue siendo el `POST API_URL` de siempre.
+ *
+ * Siempre pide confirmación: es la única acción de las tres que puede dejar
+ * una cola de trabajo hecha.
+ */
+const trigger: ActionDescriptor = {
+  type: 'trigger',
+  surfaces: ['row', 'detail'],
+  confirm: true,
+  run: async (ctx, action) => {
+    const declared = action as TriggerAction;
+    const rawKey = ctx.record?.[ctx.keyField];
+    if (rawKey === null || rawKey === undefined || rawKey === '') {
+      throw new Error(
+        `La acción «${declared.label}» necesita la clave ${ctx.keyField} del registro.`,
+      );
+    }
+    const name = declared.name ?? declared.id;
+    const route = `/admin/${ctx.resource}/${String(rawKey)}/actions/${name}`;
+    await firstValueFrom(ctx.api.request('POST', route));
+    return { ok: true, reload: true };
+  },
+};
+
+/** Catálogo — una línea por acción, en el orden en que se registran. */
+export const actionDescriptors: readonly ActionDescriptor[] = [copyShare, navigate, trigger];

package/src/lib/columns/column-cell.ts

@@ -0,0 +1,33 @@
+import type { FieldSchema, ListColumn } from '../core/models/schema.model';
+
+type Row = Record<string, unknown>;
+
+/**
+ * Contexto de una celda de listado (R4.3 · `kind: 'column-format'`).
+ *
+ * Es lo que antes cada `@case` de `list-view` pedía a la vista como
+ * `row`/`column` y lo que el descriptor cuelga de `extras.data`: el
+ * componente de formato no conoce a la vista, sólo a su celda.
+ *
+ * `fields`, `canUpdate`, `saving`, `currency` y `toggle` viajan acá porque
+ * son decisiones de la vista (permisos, moneda del schema, escritura de la
+ * fila); un formato nuevo no necesita tocar `list-view` para leerlas.
+ */
+export interface ColumnCell {
+  /** Fila completa. */
+  row: Row;
+  /** Columna que se pinta (`key`, `label`, `format`). */
+  column: ListColumn;
+  /** Campos del recurso: de acá salen `trueLabel`/`falseLabel`. */
+  fields: FieldSchema[];
+  /** `titleField` de la fila, para el `aria-label` del interruptor. */
+  title: string;
+  /** ¿La fila admite escritura? (`ListView.canUpdate`) */
+  canUpdate: boolean;
+  /** ¿La fila está guardando? (`ListView.savingKey === keyOf(row)`) */
+  saving: boolean;
+  /** Moneda del schema, para el formato `currency`. */
+  currency: string;
+  /** Escribe el valor en la fila. Sólo lo usa el interruptor `active`. */
+  toggle?: (checked: boolean) => void;
+}

package/src/lib/columns/column-defaults.spec.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+
+import { SUPPORTED_FIELD_TYPE_LIST } from '../fields/descriptors';
+import type { FieldSchema, ListColumn } from '../core/models/schema.model';
+import { FORMATO_POR_DEFECTO, formatoDeColumna, formatoPorTipo } from './column-defaults';
+
+/**
+ * R4.4 — «declarada, no implícita»: la tabla de formato por defecto.
+ *
+ * Dos promesas: que la tabla cubra **todos** los tipos del catálogo, y que
+ * una columna sin `format` pinta lo que la tabla dice — no un `?? 'text'`
+ * implícito que dependía de la memoria de quien escribía el schema.
+ */
+describe('R4.4 — formato por defecto según field.type', () => {
+  const columna = (parcial: Partial<ListColumn> & Pick<ListColumn, 'key'>): ListColumn => ({
+    label: parcial.key,
+    ...parcial,
+  });
+  const campo = (key: string, type: FieldSchema['type']): FieldSchema =>
+    ({ key, label: key, type }) as FieldSchema;
+
+  it('cubre exactamente el catálogo de tipos de campo', () => {
+    // El `Record<FieldType, …>` ya lo exige en compilación; el test además
+    // fija que ningún tipo se quede sin fila ni aparezca una fantasma.
+    expect(Object.keys(FORMATO_POR_DEFECTO).sort()).toEqual([...SUPPORTED_FIELD_TYPE_LIST].sort());
+    expect(SUPPORTED_FIELD_TYPE_LIST.length).toBe(24);
+  });
+
+  it('repasa la paridad tipo a tipo con el display del detalle', () => {
+    const esperado: Record<string, string> = {
+      text: 'text',
+      textarea: 'text',
+      slug: 'text',
+      url: 'text',
+      email: 'text',
+      phone: 'text',
+      'readonly-text': 'text',
+      relation: 'text',
+      group: 'text',
+      'key-value': 'text',
+      'string-list': 'text',
+      multiselect: 'text',
+      time: 'text',
+      list: 'text',
+      date: 'date',
+      number: 'number',
+      currency: 'currency',
+      boolean: 'boolean',
+      select: 'badge',
+      image: 'thumbnail',
+      file: 'text',
+      color: 'text',
+      'rich-select': 'badge',
+      dropdown: 'badge',
+    };
+    expect(Object.keys(FORMATO_POR_DEFECTO).sort()).toEqual(Object.keys(esperado).sort());
+    for (const [tipo, formato] of Object.entries(esperado)) {
+      expect(formatoPorTipo(tipo), `tipo ${tipo}`).toBe(formato);
+    }
+  });
+
+  it('la declaración del schema manda sobre la tabla', () => {
+    expect(
+      formatoDeColumna(columna({ key: 'status', format: 'text' }), [campo('status', 'select')]),
+    ).toBe('text');
+    expect(
+      formatoDeColumna(columna({ key: 'price', format: 'badge' }), [campo('price', 'currency')]),
+    ).toBe('badge');
+  });
+
+  it('sin formato declarado usa el tipo del campo', () => {
+    const campos = [
+      campo('status', 'select'),
+      campo('pickup_date', 'date'),
+      campo('active', 'boolean'),
+      campo('photo', 'image'),
+      campo('price', 'currency'),
+      campo('name', 'slug'),
+    ];
+    expect(formatoDeColumna(columna({ key: 'status' }), campos)).toBe('badge');
+    expect(formatoDeColumna(columna({ key: 'pickup_date' }), campos)).toBe('date');
+    expect(formatoDeColumna(columna({ key: 'active' }), campos)).toBe('boolean');
+    expect(formatoDeColumna(columna({ key: 'photo' }), campos)).toBe('thumbnail');
+    expect(formatoDeColumna(columna({ key: 'price' }), campos)).toBe('currency');
+    expect(formatoDeColumna(columna({ key: 'name' }), campos)).toBe('text');
+  });
+
+  it('una columna sin campo asociado o con tipo mal escrito degrada a text', () => {
+    // El `@default` del `@switch` que R4.3 reemplazó: la degradación es la
+    // misma y nunca lanza.
+    expect(formatoDeColumna(columna({ key: 'inventada' }), [campo('otra', 'text')])).toBe('text');
+    expect(formatoPorTipo('holograma')).toBeUndefined();
+    expect(
+      formatoDeColumna(columna({ key: 'raro' }), [
+        campo('raro', 'holograma' as FieldSchema['type']),
+      ]),
+    ).toBe('text');
+  });
+});

package/src/lib/columns/column-defaults.ts

@@ -0,0 +1,84 @@
+import type {
+  FieldSchema,
+  FieldType,
+  ListColumn,
+  ListColumnFormat,
+} from '../core/models/schema.model';
+
+/**
+ * **Tabla de formato de columna por defecto según `field.type`** (R4.4 del
+ * plan): «declarada, no implícita» — `column.format` sólo sirve para
+ * sobreescribirla.
+ *
+ * Es la hermana de `fields/display/display-defaults.ts` (R4.1): un solo
+ * sitio decide qué pinta una columna cuando el schema no dice nada, en vez
+ * de un `?? 'text'` repartido por la vista. El vocabulario se alinea con el
+ * display del detalle — `select` es chip, `date` es fecha, `image` es
+ * miniatura — con las dos concesiones que sólo el listado puede hacer:
+ * `boolean` baja al interruptor (R4.3) en vez de al chip, y `list`, que en
+ * la ficha es timeline, acá sigue siendo texto porque el registro de
+ * formatos no tiene timeline (D41).
+ *
+ * `Record<FieldType, …>` es el **tripwire de exhaustividad en compilación**:
+ * un tipo nuevo obliga a elegir su formato de lista antes de que el build
+ * pase, y un tipo retirado obliga a limpiar la entrada.
+ */
+export const FORMATO_POR_DEFECTO: Record<FieldType, ListColumnFormat> = {
+  text: 'text',
+  textarea: 'text',
+  slug: 'text',
+  url: 'text',
+  email: 'text',
+  phone: 'text',
+  'readonly-text': 'text',
+  relation: 'text',
+  group: 'text',
+  'key-value': 'text',
+  'string-list': 'text',
+  multiselect: 'text',
+  time: 'text',
+  list: 'text',
+  date: 'date',
+  number: 'number',
+  currency: 'currency',
+  boolean: 'boolean',
+  select: 'badge',
+  image: 'thumbnail',
+  // Un archivo no tiene miniatura: en la lista va como URL en crudo (R9.5.3).
+  file: 'text',
+  // Un color se pinta como texto (el hex #RRGGBB) en el listado.
+  color: 'text',
+  // Un rich-select se pinta como badge con el label de la opción.
+  'rich-select': 'badge',
+  // Un dropdown se pinta como badge con el label de la opción.
+  dropdown: 'badge',
+};
+
+/**
+ * Formato por defecto para un `type`, o `undefined` si el schema lo escribió
+ * mal (tipo fuera de la unión). La degradación — igual que `displayLoader()` —
+ * es `text`, que era el `@default` del `@switch` que R4.3 reemplazó.
+ */
+export function formatoPorTipo(type: string): ListColumnFormat | undefined {
+  return Object.prototype.hasOwnProperty.call(FORMATO_POR_DEFECTO, type)
+    ? FORMATO_POR_DEFECTO[type as FieldType]
+    : undefined;
+}
+
+/**
+ * Formato final de una columna: la declaración del schema si existe, si no,
+ * la tabla de arriba según el `type` del campo con esa `key`, y si la columna
+ * ni siquiera aparece en `fields` (columna derivada o key inventada), `text`.
+ *
+ * Es la única puerta por la que `list-view` decide qué pinta una celda.
+ */
+export function formatoDeColumna(
+  column: ListColumn,
+  fields: readonly FieldSchema[],
+): ListColumnFormat {
+  if (column.format) {
+    return column.format;
+  }
+  const field = fields.find((candidate) => candidate.key === column.key);
+  return (field ? formatoPorTipo(field.type) : undefined) ?? 'text';
+}