Cayaqui.Metadata 0.3.8

Cayaqui.Metadata

Zero-dependency attributes + resolver para decorar DTOs con metadata consumida por web grids, Cayaqui.Reports y Cayaqui.ExcelImport. Un solo decorado → tres usos consistentes.

Distribución propietaria — requiere contrato comercial con Cayaqui. Ver LICENSE.txt.

v0.2.1 — Namespace Cayaqui.Metadata.Resolver (BREAKING)

El resolver y sus tipos asociados se movieron de Cayaqui.Metadata a Cayaqui.Metadata.Resolver (consistencia carpeta↔namespace). Afecta IExtendedPropertyResolver, ExtendedPropertyResolver, PropertyMetadata.

// antes
using Cayaqui.Metadata;
// ahora (para los tipos del resolver)
using Cayaqui.Metadata.Resolver;

Los atributos ([Display], [GridWidth], [GridFormat], [Money], [Wbs], …) permanecen en Cayaqui.Metadata. Sin cambios de comportamiento — corrige la divergencia entre el source y el binario 0.19.0 publicado (que aún tenía estos tipos en el namespace raíz).

v0.19.0 — Grid column attributes

Two new optional attributes for CayaquiAutoGrid column control:

public class BudgetDto
{
 [Label("Código WBS"), GridWidth("120")] public string WbsCode { get; set; }
 [Label("CPI"), GridWidth("80"), GridFormat("N2")] public decimal Cpi { get; set; }
 [Label("Descripción"), GridWidth("25%")] public string? Name { get; set; }
}

• [GridWidth(string)] — column width as px string ("120") or CSS value ("25%"). Read via PropertyMetadata.GridWidthString. Takes precedence over [ColumnWidth(int)].
• [GridFormat(string)] — custom number format applied by IExtendedPropertyResolver.Format() when no other format attribute is present. Accepts any .NET format string ("N2", "P1", "#,##0.00").

Both attributes are additive — no breaking changes.

v0.4.0 — Enum [Display(Name)] resolution + idempotencia

IExtendedPropertyResolver.Format() ahora resuelve [Display(Name="…")] para valores enum (antes devolvía el identifier C# directo). Esto hace que los componentes de Cayaqui.Components (CayaquiAutoGrid, CayaquiAutoBadge, CayaquiAutoForm read-only) y los renderers de Cayaqui.Reports muestren labels localizados.

public enum Status
{
 [Display(Name = "Aprobado")] Approved,
 [Display(Name = "Rechazado")] Rejected,
}

resolver.Format(Status.Approved, typeof(Row), nameof(Row.Status));
// → "Aprobado" (era "Approved" en 0.3.x)

Cambio aditivo: enums sin [Display] siguen devolviendo value.ToString(). Limitación: enums [Flags] con combinación bit-OR caen al ToString() de .NET ("A, B, C" con identifiers C#) — resolución bit-a-bit es follow-up.

Bug fix idempotencia DI: AddCayaquiMetadata() y los demás AddCayaquiX() usan ahora TryAddSingleton/TryAddScoped. Múltiples llamadas (que ocurren cuando otros helpers como AddCayaquiComponents() lo invocan internamente) no duplican los registros.

Nuevo helper público: EnumExtensions.GetDisplayName() para uso fuera del resolver (charts, chips, código manual).

Instalación

dotnet add package Cayaqui.Metadata

builder.Services.AddCayaquiMetadata(); // registra IExtendedPropertyResolver singleton

Ejemplo

public sealed class ControlAccountDto
{
 [Label("Código CA")] [Wbs] [UpperCase]
 [NotEmpty] [MaxLength(20)] [RegularExpression(@"^[A-Z]{2,3}-\d{3,}$")]
 [ImportAlias("Code", "Control Account")]
 public string Code { get; set; } = "";

 [Currency("USD", 2)] [Money] [Align(TextAlign.Right)] [ColumnWidth(140)]
 public decimal Bac { get; set; }

 [Percentage(1)] [EvmIndicator(EvmKind.Cpi)] [EvmBand(green: 0.97, yellow: 0.90)]
 public decimal Cpi { get; set; }

 [Date("dd-MMM-yy")] [Schedule]
 public DateTime ControlDate { get; set; }

 [Badge] // reads colors from BadgeEnum values
 public ProjectStatus Status { get; set; }

 [Mask(MaskKind.Email, visibleChars: 1)] [Tooltip("Owner email (masked)")]
 public string Owner { get; set; } = "";

 [Hidden]
 public Guid InternalId { get; set; }

 [ImportAlias("SPI", "Schedule Performance Index")]
 [ImportCulture("es-CL")]
 public decimal Spi { get; set; }
}

public enum ProjectStatus
{
 [BadgeColor(BadgeKind.Neutral)] Draft,
 [BadgeColor(BadgeKind.Info)] InReview,
 [BadgeColor(BadgeKind.Success)] Approved,
 [BadgeColor(BadgeKind.Warning)] OnHold,
 [BadgeColor(BadgeKind.Error)] Cancelled
}

Los 37 atributos

Display

• [Label("text")] — override (reuse [Display(Name)] si existe)
• [Tooltip("text")] — tooltip específico
• [Placeholder("text")] — placeholder input Blazor
• Reusar [Display(Name, Description, Order, GroupName)] de DataAnnotations

Format

• [Currency("USD", 2)] — "USD 1,234.56"
• [Percentage(1)] — 0.756 → "75.6%"
• [Date("dd-MMM-yy")] — formato custom
• [Integer(thousands: true)] — "1,234,567"
• [DecimalFormat(decimals: 4)]
• [Duration(DurationUnit.Days)] — "5d", "3h", "15m"

Transform (no mutan el valor, sólo el display)

• [UpperCase] · [LowerCase] · [TitleCase]
• [Mask(MaskKind.Email, visibleChars: 1)] → "a********@cayaqui.com"
• [Mask(MaskKind.Email, visibleChars: 3)] → "ale******@cayaqui.com"
• [Mask(MaskKind.LastChars, visibleChars: 4)] → "******7890"
• [Truncate(30)]

Layout / Visibility

• [Align(TextAlign.Right)]
• [ColumnWidth(150)]
• [VisibleIn(RenderTargets.Web | RenderTargets.Report)]
• [Hidden] — shortcut de [VisibleIn(None)]
• [ReadOnlyDisplay]

Badge

• [Badge(BadgeKind.Success)] — fijo
• [Badge] + [BadgeColor(...)] en cada valor del enum — mapeado por valor

Usuario / persona

• [UserColumn] — marca una prop string como nombre de usuario para que CayaquiAutoGrid la renderice como <UserChip>. Opcionales:
  • AvatarSource = "SiblingProp" — prop hermana con la URL del avatar.
  • RoleSource = "SiblingProp" — prop hermana con el rol/cargo.

public sealed record AuditRow(
 string Action,
 [property: UserColumn(AvatarSource = "PerformedByAvatar", RoleSource = "PerformedByRole")]
 string PerformedByName,
 string? PerformedByAvatar,
 string? PerformedByRole);

Cayaqui.Components 0.24+ consume este atributo automáticamente.

Validation (custom shortcuts — reuse DataAnnotations para el resto)

• [NotEmpty] — [Required(AllowEmptyStrings = false)]
• [Min(0)] / [Max(100)] — sugar sobre [Range]
• Reusar [Required], [MaxLength], [MinLength], [Range], [RegularExpression], [EmailAddress], [Phone], [Url]

EPC dominio

• [EvmIndicator(EvmKind.Cpi)] — renderer aplica íconos/colores contextuales
• [EvmBand(green: 0.95, yellow: 0.85)] — thresholds semaforo configurables
• [Wbs] · [Cbs] · [Schedule] · [Money] — markers semánticos

Import

• [ImportAlias("CPI", "Cost Performance Index")] — multi-header match
• [ImportIgnore]
• [ImportDefault(0)]
• [ImportCulture("es-CL")] — parsing locale
• [ImportColumn(3)] — opt-in por posición
• [ImportTrim(false)] — default true
• [ImportRegex(@"^[A-Z]+-\d+$")]

API del resolver

public interface IExtendedPropertyResolver
{
 PropertyMetadata? Get(Type dtoType, string propertyName);
 IReadOnlyList<PropertyMetadata> GetAll(Type dtoType);

 /// <summary>
 /// Filtra GetAll() por <see cref="RenderTargets"/> visible (Web | Report |
 /// Excel). Usado por CayaquiAutoGrid/CayaquiAutoForm para descartar props
 /// con [VisibleIn] que excluya el target actual.
 /// </summary>
 IReadOnlyList<PropertyMetadata> GetVisibleProperties(Type dtoType, RenderTargets target);

 string? Format(object? value, Type dtoType, string propertyName, CultureInfo? culture = null);
 bool TryParse(string? text, Type dtoType, string propertyName, CultureInfo? culture, out object? value);
}

RenderTargets es un enum bandera (en Cayaqui.Metadata/Models/Enums.cs):

[Flags]
public enum RenderTargets
{
 None = 0,
 Web = 1 << 0, // grids, forms, modals en Blazor
 Report = 1 << 1, // PDF/Word/PPT vía Cayaqui.Reports
 Excel = 1 << 2, // export a XLSX vía Cayaqui.ExcelExport
 All = Web | Report | Excel,
}

Helper público adicional (v0.4.0+):

namespace Cayaqui.Metadata;
public static class EnumExtensions
{
 /// Devuelve [Display(Name)] del miembro del enum, fallback a ToString().
 public static string GetDisplayName(this Enum value);
}

Cache por Type en primer acceso, thread-safe.

Requisitos

• .NET 10.0 o superior
• Zero dependencies externas (sólo Microsoft.Extensions.DependencyInjection.Abstractions para el extension method, que es BCL+)