@envisiongroup/porygon 1.0.0-rc.9 → 1.0.0

package/dist/react-components/fields/{EFWField → _shared/EFWField}/EFWField.types.d.ts

@@ -4,18 +4,21 @@ import { InfoLabelProps, FieldProps } from '@fluentui/react-components';
  * Estado de validación del campo, heredado de FieldProps.
  * Define el estado actual de la validación del componente.
  *
- * @typedef {'valid' | 'invalid' | 'warning' | undefined} ValidationState
+ * @typedef {'none' | 'error' | 'warning' | 'success' | 'loading' | undefined} ValidationState
  * @example
- * // Campo válido
- * const state: ValidationState = 'valid';
+ * // Campo exitoso
+ * const state: ValidationState = 'success';
  *
  * // Campo con error
- * const errorState: ValidationState = 'invalid';
+ * const errorState: ValidationState = 'error';
+ *
+ * // Campo en carga
+ * const loadingState: ValidationState = 'loading';
  *
  * // Campo sin validar
- * const neutralState: ValidationState = undefined;
+ * const neutralState: ValidationState = 'none';
  */
-export type ValidationState = FieldProps['validationState'] | string;
+export type ValidationState = FieldProps['validationState'] | 'loading' | string;
 /**
  * Mensaje de validación del campo, heredado de FieldProps.
  * Contiene el texto descriptivo del estado de validación.
@@ -51,7 +54,7 @@ export type ValidationMessage = FieldProps['validationMessage'];
  * const advancedProps: EFWFieldProps = {
  *   title: "Email corporativo",
  *   required: true,
- *   validationState: "invalid",
+ *   validationState: "error",
  *   validationMessage: "Formato de email inválido",
  *   onValidationChange: (validation) => {
  *     console.log('Estado:', validation.currentValidationState);
@@ -60,6 +63,10 @@ export type ValidationMessage = FieldProps['validationMessage'];
  * };
  */
 export interface EFWFieldProps {
+    /**
+     * Atributo de datos para identificar el internalName del campo en el DOM.
+     */
+    'data-field-internal-name'?: string;
     /**
      * Título del campo, mostrado como etiqueta principal.
      * Se renderiza generalmente como un label asociado al input.
@@ -160,15 +167,19 @@ export interface EFWFieldProps {
      * Determina el estilo visual y comportamiento del campo.
      *
      * @example
-     * validationState="invalid"
+     * validationState="error"
      *
      * @example
      * validationState="warning"
      *
      * @example
-     * validationState="valid"
+     * validationState="success"
+     *
+     * @example
+     * validationState="loading"
      */
     validationState?: ValidationState;
+    validationMessageIcon?: FieldProps['validationMessageIcon'];
     /**
      * Mensaje asociado al estado de validación.
      * Se muestra al usuario para explicar el estado de validación.
@@ -199,7 +210,7 @@ export interface EFWFieldProps {
      *
      * @example
      * onValidationChange={({ currentValidationState, currentValidationMessage }) => {
-     *   if (currentValidationState === 'valid') {
+     *   if (currentValidationState === 'success') {
      *     onFieldValid(fieldName);
      *   } else {
      *     onFieldInvalid(fieldName, currentValidationMessage);
@@ -223,9 +234,9 @@ export interface EFWFieldProps {
      *     onBlur={(value) => {
      *       // El hijo puede usar setParentComponentState para reportar validación
      *       if (!isValidEmail(value)) {
-     *         setParentComponentState('invalid', 'Email inválido');
+     *         setParentComponentState('error', 'Email inválido');
      *       } else {
-     *         setParentComponentState('valid');
+     *         setParentComponentState('success');
      *       }
      *     }}
      *   />
@@ -288,7 +299,7 @@ export interface EFWFieldChildrenProps {
      * Callback para comunicar cambios de estado al componente padre
      * @param status - Nuevo estado de validación a propagar
      * @param message - Mensaje opcional asociado al estado
-     * @example setParentComponentState('invalid', 'Este campo es requerido')
+     * @example setParentComponentState('error', 'Este campo es requerido')
      */
     setParentComponentState?: (status: ValidationState, message?: ValidationMessage) => void;
 }

package/dist/react-components/fields/_shared/EFWField/EFWField.utils.js

@@ -0,0 +1,20 @@
+import { jsx as r } from "react/jsx-runtime";
+import { Spinner as n } from "@fluentui/react-components";
+import { CheckmarkCircle12Regular as t, Warning12Regular as a, ErrorCircle12Regular as i } from "@fluentui/react-icons";
+const u = (e) => {
+  switch (e) {
+    case "error":
+      return /* @__PURE__ */ r(i, {});
+    case "warning":
+      return /* @__PURE__ */ r(a, {});
+    case "success":
+      return /* @__PURE__ */ r(t, {});
+    case "loading":
+      return /* @__PURE__ */ r(n, { size: "extra-tiny" });
+    default:
+      return null;
+  }
+};
+export {
+  u as getValidationIcon
+};

package/dist/react-components/fields/_shared/EFWField/useSyncedValidationState.d.ts

@@ -0,0 +1,50 @@
+import { ValidationMessage, ValidationState } from './EFWField.types';
+
+/**
+ * Argumentos del hook `useSyncedValidationState`.
+ */
+export interface UseSyncedValidationStateArgs {
+    /** Estado de validación impuesto por el componente padre (props externas). */
+    externalValidationState: ValidationState;
+    /** Mensaje de validación impuesto por el componente padre (props externas). */
+    externalValidationMessage: ValidationMessage;
+    /** Callback notificado cuando cambia el estado de validación efectivo. */
+    onValidationChange?: (validation: {
+        currentValidationState: ValidationState;
+        currentValidationMessage: ValidationMessage;
+    }) => void;
+}
+/**
+ * Resultado del hook `useSyncedValidationState`.
+ */
+export interface UseSyncedValidationStateResult {
+    /** Estado de validación efectivo que debe renderizar `EFWField`. */
+    validationState: ValidationState;
+    /** Mensaje de validación efectivo que debe renderizar `EFWField`. */
+    validationMessage: ValidationMessage;
+    /**
+     * Permite que el control hijo reporte su propio estado de validación.
+     * Si el hijo reporta valores no vacíos se usan; en otro caso se cae a las
+     * props externas (fallback). El último reporte crudo se recuerda para no
+     * suprimirlo cuando el padre limpia un error externo en la misma pulsación.
+     */
+    setFieldState: (status?: ValidationState, message?: string) => void;
+}
+/**
+ * Sincroniza el estado de validación de un campo entre dos fuentes:
+ *
+ * 1. **Props externas** (`externalValidationState`/`externalValidationMessage`):
+ *    el padre (`EFWForm`) impone errores como el de obligatoriedad.
+ * 2. **Reporte del control hijo** (`setFieldState`): el campo concreto reporta
+ *    sus propias reglas (minLength, formato, minValue, etc.).
+ *
+ * Regla clave de coexistencia: cuando el padre **limpia** un error externo
+ * (`error -> none`) en la misma pulsación en que el control hijo reportó un
+ * error propio, se **conserva** el error del hijo en vez de imponer `none`.
+ * Esto evita el "clobber" del error de regla propia al limpiar la
+ * obligatoriedad (p. ej. escribir una sola letra inválida con `minLength`).
+ *
+ * Se extrajo desde `EFWField` para aislar esta lógica de sincronización
+ * (antes embebida en dos `useEffect`) y reducir la complejidad del componente.
+ */
+export declare const useSyncedValidationState: ({ externalValidationState, externalValidationMessage, onValidationChange, }: UseSyncedValidationStateArgs) => UseSyncedValidationStateResult;

package/dist/react-components/fields/_shared/EFWField/useSyncedValidationState.js

@@ -0,0 +1,41 @@
+import { useState as h, useRef as v, useEffect as m, useCallback as S } from "react";
+const k = ({
+  externalValidationState: r,
+  externalValidationMessage: n,
+  onValidationChange: E
+}) => {
+  const [t, u] = h(
+    r
+  ), [o, e] = h(
+    n
+  ), R = v(!1), f = v(
+    null
+  ), p = v(
+    r
+  );
+  m(() => {
+    if (!R.current) {
+      R.current = !0, p.current = r;
+      return;
+    }
+    const s = p.current, c = f.current;
+    r === "none" && (n === "" || n === void 0) && s === "error" && c && c.state === "error" ? (u(c.state), e(c.msg)) : (u(r), e(n), r !== "none" && (f.current = null)), p.current = r;
+  }, [r, n]);
+  const w = S(
+    (s = "none", c = "") => {
+      f.current = { state: s ?? "none", msg: c };
+      const C = s !== "none" ? s : r, y = c !== "" ? c : n;
+      u(C), e(y);
+    },
+    [r, n]
+  );
+  return m(() => {
+    E?.({
+      currentValidationState: t,
+      currentValidationMessage: o
+    });
+  }, [t, o, E]), { validationState: t, validationMessage: o, setFieldState: w };
+};
+export {
+  k as useSyncedValidationState
+};

package/dist/react-components/fields/test-utils/testUtils.js

@@ -0,0 +1,10 @@
+import { jsx as o } from "react/jsx-runtime";
+import { FluentProvider as m, webLightTheme as i } from "@fluentui/react-components";
+import { render as p } from ".pnpm";
+const f = (r, e) => p(r, {
+  wrapper: ({ children: t }) => /* @__PURE__ */ o(m, { theme: i, children: t }),
+  ...e
+});
+export {
+  f as renderWithFluent
+};

package/dist/react-components/forms/EFWForm/EFWForm.converter.d.ts

@@ -1,3 +1,18 @@
 import { EFWFormFieldValue, EFWFormFieldProps, EFWFormFieldType } from './EFWForm.types';
 
-export declare const getEFWFormFieldDisplayText: <T extends EFWFormFieldType>(formField: EFWFormFieldProps<T>, cellValue: EFWFormFieldValue<T>) => string;
+export interface FormFieldDisplayTextOptions {
+    switchLabels?: {
+        checkedText?: string;
+        uncheckedText?: string;
+    };
+}
+/**
+ * Obtiene el texto de visualización para un campo de formulario.
+ * Es el punto de entrada público utilizado por componentes como `CellRenderer`
+ * para renderizar el contenido por defecto de una celda de tabla.
+ *
+ * @param formField - Props del campo de formulario que definen su tipo y configuración.
+ * @param cellValue - Valor actual del campo a representar como texto.
+ * @returns Texto formateado listo para mostrar en la UI, o cadena vacía si el valor es `null`/`undefined`.
+ */
+export declare const getFormFieldDisplayText: <T extends EFWFormFieldType>(formField: EFWFormFieldProps<T>, cellValue: EFWFormFieldValue<T>, options?: FormFieldDisplayTextOptions) => string;

package/dist/react-components/forms/EFWForm/EFWForm.converter.js

@@ -1,30 +1,61 @@
-const i = (r, t) => Array.isArray(r) ? r.map((n) => n.text).join(", ") : "", e = {
-  Text: (r, t) => r || "",
-  Number: (r, t) => r != null ? String(r) : "",
-  Note: (r, t) => r || "",
-  Boolean: (r, t) => r == null ? "" : r ? "Sí" : "No",
-  Choice: (r, t) => i(r),
-  MultiChoice: (r, t) => i(r),
-  Date: (r, t) => Array.isArray(r) ? r.map((n) => {
-    const o = new Date(n);
-    return isNaN(o.getTime()) ? "" : o.toLocaleDateString();
+import { getAttachmentsFormattedValue as m } from "../../fields/Attachments/EFWAttachments.utils.js";
+import { getTagPickerFormattedValue as n } from "../../fields/TagPicker/EFWTagPicker.utils.js";
+import { getSwitchFormattedValue as i } from "../../fields/Switch/EFWSwitch.utils.js";
+import { getTextAreaFormattedValue as c } from "../../fields/TextArea/EFWTextArea.utils.js";
+import { getNumberInputFormattedValue as u } from "../../fields/NumberInput/EFWNumberInput.utils.js";
+import { getInputFormattedValue as s } from "../../fields/Input/EFWInput.utils.js";
+import { getDatePickerFormattedValue as p } from "../../fields/DatePicker/EFWDatePicker.utils.js";
+const d = {
+  Text: (r, t) => s(r, t.formatType, {
+    formatPattern: t.formatPattern,
+    formatFunction: t.formatFunction,
+    formatConfig: t.formatConfig
+  }),
+  Number: (r, t) => u(r, {
+    enableFormatting: t.enableFormatting,
+    thousandSeparator: t.thousandSeparator,
+    decimalSeparator: t.decimalSeparator
+  }),
+  Note: (r, t) => c(r),
+  Boolean: (r, t, e) => i(r, {
+    checkedText: t.labels?.checkedText ?? e?.switchLabels?.checkedText,
+    uncheckedText: t.labels?.uncheckedText ?? e?.switchLabels?.uncheckedText
+  }),
+  Choice: (r, t) => n(r),
+  MultiChoice: (r, t) => n(r),
+  Date: (r, t) => Array.isArray(r) ? r.map((e) => {
+    const a = new Date(e);
+    if (isNaN(a.getTime())) return "";
+    const o = t.includeTime ? `${a.getHours().toString().padStart(2, "0")}${a.getMinutes().toString().padStart(2, "0")}` : void 0;
+    return p(e, {
+      includeTime: t.includeTime,
+      timeValue: o
+    });
   }).filter(Boolean).join(", ") : "",
-  Attachments: (r, t) => Array.isArray(r) ? `${r.length} archivo(s)` : "0 archivos"
+  Attachments: (r, t) => m(r)
 };
-function c(r, t, n) {
+function g(r, t, e, a) {
   if (t == null)
     return "";
   try {
-    const o = e[r];
-    return o(t, n);
+    const o = d[r];
+    return o(t, e, a);
   } catch (o) {
-    return console.error(`Error al convertir valor para tipo de campo ${r}: ${o}`, {
-      fieldValue: t,
-      error: o
-    }), String(t);
+    return console.error(
+      `Error al convertir valor para tipo de campo ${r}: ${o}`,
+      {
+        fieldValue: t,
+        error: o
+      }
+    ), String(t);
   }
 }
-const a = (r, t) => t == null ? "" : c(r.typeAsString, t, r);
+const b = (r, t, e) => t == null ? "" : g(
+  r.typeAsString,
+  t,
+  r,
+  e
+);
 export {
-  a as getEFWFormFieldDisplayText
+  b as getFormFieldDisplayText
 };

package/dist/react-components/forms/EFWForm/EFWForm.flatConverter.d.ts

@@ -0,0 +1,130 @@
+import { EFWAttachmentsValue } from '../../fields/Attachments';
+import { EFWFormFieldProps, EFWFormValues, EFWFormDatePickerFieldProps } from './EFWForm.types';
+
+/**
+ * Tipo derivado del array de fields que describe el shape "plano" natural
+ * para el consumer: primitivos, booleanos o arrays simples por field.
+ *
+ * Mapping por `typeAsString`:
+ * - `Text` / `Note` / `Choice` / `Date`     → `string`
+ * - `Number`                                 → `number`
+ * - `Boolean`                                → `boolean`
+ * - `MultiChoice`                            → `readonly string[]`
+ * - `Attachments`                            → `readonly EFWAttachmentsValue[]`
+ *
+ * Para `Choice` plano se usa la `key` del item seleccionado y para `MultiChoice`
+ * un array de `key`s, ya que `key` es el identificador estable.
+ */
+export type FlatValues<F extends readonly EFWFormFieldProps[] = EFWFormFieldProps[]> = {
+    [K in F[number] as K['internalName']]?: FlatValueOfField<K>;
+};
+export type FlatValueOfField<P extends EFWFormFieldProps> = P['typeAsString'] extends 'Text' ? string : P['typeAsString'] extends 'Number' ? number : P['typeAsString'] extends 'Note' ? string : P['typeAsString'] extends 'Boolean' ? boolean : P['typeAsString'] extends 'Choice' ? string : P['typeAsString'] extends 'MultiChoice' ? readonly string[] : P['typeAsString'] extends 'Date' ? string : P['typeAsString'] extends 'Attachments' ? readonly EFWAttachmentsValue[] : never;
+/**
+ * Función personalizada para serializar un valor de fecha al ir de EFW → flat.
+ */
+export type DateSerializeFunction = (value: Date | string, field: EFWFormDatePickerFieldProps) => string;
+export interface FlatToEFWOptions {
+    /**
+     * Estrategia para resolver opciones en Choice/MultiChoice cuando se recibe
+     * sólo la `key`.
+     *
+     * - `'lookup'` (default): busca la key en `field.options` y arma `{ key, text, ... }`.
+     *   Si la key no aparece, ver `unknownChoiceKey`.
+     * - `'passthrough'`: no busca; siempre genera `{ key, text: key }` directamente
+     *   (útil cuando `field.options` es un loader async o el caller ya validó las keys).
+     */
+    choiceLookup?: 'lookup' | 'passthrough';
+    /**
+     * Qué hacer cuando una `key` de Choice/MultiChoice no existe en `field.options`.
+     *
+     * - `'drop'` (default): omitir el item.
+     * - `'synthesize'`: generar `{ key, text: key }`.
+     * - `'error'`: lanzar `EFWConversionError`.
+     */
+    unknownChoiceKey?: 'drop' | 'synthesize' | 'error';
+    /**
+     * Para Date: cómo interpretar el string ISO al construir el `Date[]` que
+     * espera el field.
+     *
+     * - `'as-utc'` (default): `new Date(flat)`. Strings tipo `'YYYY-MM-DD'` o
+     *   ISO con `Z` se interpretan como UTC.
+     * - `'as-local'`: `new Date(flat)` interpretado por el runtime local.
+     * - `'string'`: no convierte; coloca el string crudo en el array (válido
+     *   porque `EFWDatePickerValue = Date | string`).
+     */
+    dateParse?: 'as-utc' | 'as-local' | 'string';
+}
+export interface EFWToFlatOptions {
+    /**
+     * Para Date: cómo serializar `Date | string` al string plano.
+     *
+     * - `'iso-date'` (default): `'YYYY-MM-DD'` UTC.
+     * - `'iso-datetime'`: ISO 8601 completo (`Date.prototype.toISOString`).
+     * - función custom `(value, field) => string`.
+     */
+    dateSerialize?: 'iso-date' | 'iso-datetime' | DateSerializeFunction;
+    /**
+     * Para campos vacíos / null, decide si la clave se omite del output o se
+     * incluye como `undefined`. Default: `'omit'`.
+     */
+    emptyKeys?: 'omit' | 'include';
+}
+/**
+ * Códigos de error producidos por las conversiones planas de EFWForm.
+ */
+export type EFWConversionErrorCode = 'unknown-choice-key' | 'invalid-date' | 'invalid-number' | 'unsupported-field-type';
+/**
+ * Error lanzado por `flatToEFWValues` / `EFWValuesToFlat` cuando una conversión
+ * falla de forma fatal o las opciones la fuerzan a fallar.
+ */
+export declare class EFWConversionError extends Error {
+    readonly code: EFWConversionErrorCode;
+    readonly fieldName: string;
+    readonly received: unknown;
+    constructor(params: {
+        code: EFWConversionErrorCode;
+        fieldName: string;
+        received: unknown;
+        message?: string;
+    });
+}
+/**
+ * Convierte un objeto plano (`{ field: primitive | array }`) al shape que
+ * espera `EFWForm` para sus `values` / `defaultValues` (ej. `Date` como
+ * `Date[]`, `Choice` como `EFWTagPickerOption[]`).
+ *
+ * - Las claves del input que no matcheen ningún `field.internalName` se
+ *   ignoran silenciosamente.
+ * - Las claves declaradas en `fields` que no estén presentes en el input se
+ *   omiten del output (no se completan con default).
+ * - Cuando una conversión no es posible (ej. Choice con key desconocida), el
+ *   field correspondiente se devuelve como vacío salvo que las opciones
+ *   indiquen lo contrario.
+ *
+ * @example
+ * const fields = [
+ *   { id: '1', typeAsString: 'Text', internalName: 'name' },
+ *   { id: '2', typeAsString: 'Choice', internalName: 'category', options: [{ key: 'a', text: 'A' }] },
+ * ] as const;
+ *
+ * flatToEFWValues(fields, { name: 'John', category: 'a' });
+ * // → { name: 'John', category: [{ key: 'a', text: 'A' }] }
+ */
+export declare function flatToEFWValues<F extends readonly EFWFormFieldProps[]>(fields: F, flat: FlatValues<F> | Partial<FlatValues<F>> | Record<string, unknown>, options?: FlatToEFWOptions): Partial<EFWFormValues<F>>;
+/**
+ * Operación inversa de {@link flatToEFWValues}: toma valores en el shape que
+ * usa `EFWForm` y los reduce a primitivos / arrays planos según el tipo de
+ * cada field.
+ *
+ * - Las claves del input que no matcheen ningún field se ignoran.
+ * - Si un field está ausente o tiene valor vacío equivalente, la clave se
+ *   omite del output (controlable con `emptyKeys: 'include'`).
+ *
+ * @example
+ * EFWValuesToFlat(fields, {
+ *   name: 'John',
+ *   category: [{ key: 'a', text: 'A' }],
+ * });
+ * // → { name: 'John', category: 'a' }
+ */
+export declare function EFWValuesToFlat<F extends readonly EFWFormFieldProps[]>(fields: F, efwValues: Partial<EFWFormValues<F>>, options?: EFWToFlatOptions): Partial<FlatValues<F>>;