@envisiongroup/porygon 1.0.0-rc.8 → 1.0.0

package/README.md

@@ -1,4 +1,5 @@
 # Porygon
+
 Porygon es un paquete desarrollado por Envision, en el que se incluye varios componentes React diseñados inicialmente para gestionar la lógica y el manejo de formularios y tablas. Esto nos permite trabajar con un stack tecnológico moderno y sencillo.
 Estos componentes cumplen con los siguientes criterios:
 
@@ -10,10 +11,10 @@ Estos componentes cumplen con los siguientes criterios:
 
 ## Instalación
 
-Porygon es compatible con **React 17**, **18** y **19**. Instala el paquete con npm:
+Porygon es compatible con **React 17**, **18** y **19**. Instala el paquete con pnpm:
 
 ```bash
-npm install @grupoenvision/porygon
+pnpm add @grupoenvision/porygon
 ```
 
 ## Configuración inicial
@@ -31,9 +32,9 @@ import App from './App';
 const root = createRoot(document.getElementById('root'));
 
 root.render(
-  <FluentProvider theme={webLightTheme}>
-    <App />
-  </FluentProvider>
+	<FluentProvider theme={webLightTheme}>
+		<App />
+	</FluentProvider>,
 );
 ```
 
@@ -49,21 +50,56 @@ Porygon soporta los temas que Fluent tiene por defecto:
 - `teamsLightTheme` - Tema claro compatible con Microsoft Teams
 - `teamsDarkTheme` - Tema oscuro compatible with Microsoft Teams
 
-Sin embargo, es probable que prefieras usar un tema personalizado. Para esto, puedes crear uno mediante el [generador de temas de Fluent](/docs/diseñador-de-temas--docs). 
+Sin embargo, es probable que prefieras usar un tema personalizado. Para esto, puedes crear uno mediante el [generador de temas de Fluent](/docs/diseñador-de-temas--docs).
 Una vez que lo hayas creado, se guarda en un archivo JSON, que luego puedes importar y utilizar en tu aplicación.
 
 ```jsx
-import { 
-  FluentProvider, 
-  webLightTheme, 
-  webDarkTheme 
+import {
+	FluentProvider,
+	webLightTheme,
+	webDarkTheme,
 } from '@fluentui/react-components';
 import customTheme from '../themes/customTheme.json';
 
 // Ejemplo con tema customizado
 root.render(
-  <FluentProvider theme={customTheme}>
-    <App />
-  </FluentProvider>
+	<FluentProvider theme={customTheme}>
+		<App />
+	</FluentProvider>,
 );
-```
+```
+
+## Skill para agentes IA: `porygon-components`
+
+Porygon publica una **Agent Skill** llamada `porygon-components` para que los asistentes de código (Claude Code, Codex, Cursor, opencode, pi, etc.) sepan **consumir correctamente** la librería mientras escriben tu código: elegir el componente adecuado, conectar props, decidir estado controlado vs no-controlado, validación, callbacks y ejemplos copiables.
+
+La skill funciona como un **router**: aplica reglas globales de uso y luego carga solo el archivo de referencia de la familia que necesites.
+
+| Familia | Qué cubre                                                                                    |
+| ------- | -------------------------------------------------------------------------------------------- |
+| Buttons | Acciones con estado async (loading / success / error), drawers laterales y grupos de botones |
+| Fields  | Campos sueltos: texto, número, área de texto, switch, tags, fecha y adjuntos                 |
+| Forms   | Formularios declarativos: validación, layout grid, lógica entre campos y control imperativo  |
+| Tables  | Columnas derivadas de `fields`, CRUD, filtros, sorting, selección y overlays                 |
+| i18n    | Provider global, presets ES / EN / PT_BR y override de textos                                |
+
+Entre las **reglas de oro** que aplica automáticamente: no mezclar controlado y no-controlado, guardar siempre el `rawValue` de `onChange`, declarar `fields` tipados con `as const satisfies EFWFormFieldProps[]`, mantener identidad estable de fields/filas, traducir textos vía contexto i18n y preferir handlers/controller hooks por sobre `useEffect`.
+
+Sigue el [estándar Agent Skills](https://agentskills.io/specification), por lo que funciona en cualquier herramienta compatible. Se distribuye desde el repositorio público **`envisionlatam/skills`** (skill `porygon-components`).
+
+### Instalación
+
+```bash
+# Con skills.sh (CLI universal, recomendada)
+npx skills add envisionlatam/skills --skill porygon-components
+
+# Fijar una versión concreta (recomendado para equipos)
+npx skills add envisionlatam/skills#porygon-components-v1.0.1 --skill porygon-components
+
+# Con el agente pi
+pi install git:github.com/envisionlatam/skills
+```
+
+### Uso
+
+No hay que invocarla manualmente: el agente la **activa sola** cuando detecta que tu tarea importa o usa `EFWButton`, `EFW*Field`, `EFWForm`, `useFormController`, `EFWTable`, `useTableController`, `PorygonI18nProvider`, etc. En pi además queda disponible como comando `/skill:porygon-components`.

package/dist/index.d.ts

@@ -2,23 +2,17 @@ export * from './react-components/buttons/EFWButton';
 export * from './react-components/buttons/EFWDrawerButton';
 export * from './react-components/buttons/EFWGroupButton';
 export * from './react-components/commons/utils';
-export * from './react-components/fields/EFWAttachments';
-export * from './react-components/fields/EFWAttachmentsField';
-export * from './react-components/fields/EFWDatePicker';
-export * from './react-components/fields/EFWDatePickerField';
-export * from './react-components/fields/EFWField';
-export * from './react-components/fields/EFWInput';
-export * from './react-components/fields/EFWInputField';
-export * from './react-components/fields/EFWNumberInput';
-export * from './react-components/fields/EFWNumberInputField';
-export * from './react-components/fields/EFWSwitch';
-export * from './react-components/fields/EFWSwitchField';
-export * from './react-components/fields/EFWTagPicker';
-export * from './react-components/fields/EFWTagPickerField';
-export * from './react-components/fields/EFWTextArea';
-export * from './react-components/fields/EFWTextAreaField';
+export * from './react-components/fields/_shared/EFWField';
+export * from './react-components/fields/Attachments';
+export * from './react-components/fields/DatePicker';
+export * from './react-components/fields/Input';
+export * from './react-components/fields/NumberInput';
+export * from './react-components/fields/Switch';
+export * from './react-components/fields/TagPicker';
+export * from './react-components/fields/TextArea';
 export * from './react-components/forms/EFWForm';
 export * from './react-components/forms/EFWFormMessageBarGroup';
 export * from './react-components/forms/EFWMessageBarManager/EFWMessageBarManager';
 export * from './react-components/hooks/useDrawer';
+export * from './react-components/i18n';
 export * from './react-components/tables/EFWTable';

package/dist/index.js

@@ -1,63 +1,103 @@
 import { formatFileSize as o, getErrorMessage as t, getFileIconUrl as F } from "./react-components/commons/utils.js";
-import { EFWMessageBarManager as p } from "./react-components/forms/EFWMessageBarManager/EFWMessageBarManager.js";
-import { EFWButton as f } from "./react-components/buttons/EFWButton/EFWButton.js";
-import { useEFWButton as W } from "./react-components/buttons/EFWButton/EFWButton.hooks.js";
-import { EFWDrawerButton as l } from "./react-components/buttons/EFWDrawerButton/EFWDrawerButton.js";
-import { EFWGroupButton as u } from "./react-components/buttons/EFWGroupButton/EFWGroupButton.js";
-import { EFWAttachment as s } from "./react-components/fields/EFWAttachments/EFWAttachments.js";
-import { EFWAttachmentsField as d } from "./react-components/fields/EFWAttachmentsField/EFWAttachmentsField.js";
-import { EFWDatePicker as T } from "./react-components/fields/EFWDatePicker/EFWDatePicker.js";
-import { EFWDatePickerField as B } from "./react-components/fields/EFWDatePickerField/EFWDatePickerField.js";
-import { EFWField as I } from "./react-components/fields/EFWField/EFWField.js";
-import { EFWInput as k } from "./react-components/fields/EFWInput/EFWInput.js";
-import { EFWInputField as A } from "./react-components/fields/EFWInputField/EFWInputField.js";
-import { EFWNumberInput as P } from "./react-components/fields/EFWNumberInput/EFWNumberInput.js";
-import { EFWNumberInputField as S } from "./react-components/fields/EFWNumberInputField/EFWNumberInputField.js";
-import { EFWSwitch as G } from "./react-components/fields/EFWSwitch/EFWSwitch.js";
-import { EFWSwitchField as v } from "./react-components/fields/EFWSwitchField/EFWSwitchField.js";
-import { EFWTagPicker as O } from "./react-components/fields/EFWTagPicker/EFWTagPicker.js";
-import { EFWTagPickerField as j } from "./react-components/fields/EFWTagPickerField/EFWTagPickerField.js";
-import { EFWTextArea as H } from "./react-components/fields/EFWTextArea/EFWTextArea.js";
-import { EFWTextAreaField as K } from "./react-components/fields/EFWTextAreaField/EFWTextAreaField.js";
-import { getEFWFormFieldDisplayText as Q } from "./react-components/forms/EFWForm/EFWForm.converter.js";
-import { useFormController as V } from "./react-components/forms/EFWForm/EFWForm.hooks.js";
-import { EFWForm as Y } from "./react-components/forms/EFWForm/EFWForm.js";
-import { EFWFormMessageBarGroup as _ } from "./react-components/forms/EFWFormMessageBarGroup/EFWFormMessageBarGroup.js";
-import { useDrawer as rr } from "./react-components/hooks/useDrawer/useDrawer.js";
-import { EFWTable as or } from "./react-components/tables/EFWTable/EFWTable.js";
-import { useTableController as Fr } from "./react-components/tables/EFWTable/hooks/useTableController/useTableController.js";
-import { EFWTableEmpty as pr, EFWTableOverlay as xr } from "./react-components/tables/EFWTable/components/EFWTableOverlay/EFWTableOverlay.js";
+import { EFWMessageBarManager as a } from "./react-components/forms/EFWMessageBarManager/EFWMessageBarManager.js";
+import { EFWButton as p } from "./react-components/buttons/EFWButton/EFWButton.js";
+import { useEFWButton as l } from "./react-components/buttons/EFWButton/EFWButton.hooks.js";
+import { EFWDrawerButton as u } from "./react-components/buttons/EFWDrawerButton/EFWDrawerButton.js";
+import { EFWGroupButton as i } from "./react-components/buttons/EFWGroupButton/EFWGroupButton.js";
+import { EFWField as L } from "./react-components/fields/_shared/EFWField/EFWField.js";
+import { EFWAttachment as s } from "./react-components/fields/Attachments/EFWAttachments.js";
+import { getAttachmentsFormattedValue as g } from "./react-components/fields/Attachments/EFWAttachments.utils.js";
+import { EFWAttachmentsField as d } from "./react-components/fields/Attachments/EFWAttachmentsField.js";
+import { EFWDatePicker as O } from "./react-components/fields/DatePicker/EFWDatePicker.js";
+import { enLocalizedStrings as D, esLocalizedStrings as B, getDatePickerFormattedValue as C, ptLocalizedStrings as S } from "./react-components/fields/DatePicker/EFWDatePicker.utils.js";
+import { EFWDatePickerField as N } from "./react-components/fields/DatePicker/EFWDatePickerField.js";
+import { EFWInput as b } from "./react-components/fields/Input/EFWInput.js";
+import { getInputFormattedValue as k } from "./react-components/fields/Input/EFWInput.utils.js";
+import { EFWInputField as R } from "./react-components/fields/Input/EFWInputField.js";
+import { EFWNumberInput as w } from "./react-components/fields/NumberInput/EFWNumberInput.js";
+import { getNumberInputFormattedValue as M } from "./react-components/fields/NumberInput/EFWNumberInput.utils.js";
+import { EFWNumberInputField as X } from "./react-components/fields/NumberInput/EFWNumberInputField.js";
+import { EFWSwitch as v } from "./react-components/fields/Switch/EFWSwitch.js";
+import { getSwitchFormattedValue as q } from "./react-components/fields/Switch/EFWSwitch.utils.js";
+import { EFWSwitchField as J } from "./react-components/fields/Switch/EFWSwitchField.js";
+import { EFWTagPicker as Q } from "./react-components/fields/TagPicker/EFWTagPicker.js";
+import { getTagPickerFormattedValue as $ } from "./react-components/fields/TagPicker/EFWTagPicker.utils.js";
+import { EFWTagPickerField as re } from "./react-components/fields/TagPicker/EFWTagPickerField.js";
+import { EFWTextArea as te } from "./react-components/fields/TextArea/EFWTextArea.js";
+import { getTextAreaFormattedValue as me } from "./react-components/fields/TextArea/EFWTextArea.utils.js";
+import { EFWTextAreaField as Ee } from "./react-components/fields/TextArea/EFWTextAreaField.js";
+import { getFormFieldDisplayText as xe } from "./react-components/forms/EFWForm/EFWForm.converter.js";
+import { useFormController as fe } from "./react-components/forms/EFWForm/EFWForm.hooks.js";
+import { EFWForm as Te } from "./react-components/forms/EFWForm/EFWForm.js";
+import { EFWConversionError as We, EFWValuesToFlat as Le, flatToEFWValues as ne } from "./react-components/forms/EFWForm/EFWForm.flatConverter.js";
+import { EFWFormMessageBarGroup as _e } from "./react-components/forms/EFWFormMessageBarGroup/EFWFormMessageBarGroup.js";
+import { useDrawer as ce } from "./react-components/hooks/useDrawer/useDrawer.js";
+import { PorygonI18nProvider as Ae, useButtonsLocaleText as Oe, useFieldsLocaleText as Pe, useFormLocaleText as De, usePorygonLocaleText as Be, useTableLocaleText as Ce } from "./react-components/i18n/PorygonI18nProvider.js";
+import { DEFAULT_EFW_BUTTONS_LOCALE_TEXT as Ie, DEFAULT_EFW_FIELDS_LOCALE_TEXT as Ne, DEFAULT_EFW_FORM_LOCALE_TEXT as Ve, DEFAULT_EFW_TABLE_LOCALE_TEXT as be } from "./react-components/i18n/defaultLocaleText.js";
+import { PORYGON_LOCALES as ke, PORYGON_LOCALE_EN as Ge, PORYGON_LOCALE_ES as Re, PORYGON_LOCALE_PT_BR as Ue } from "./react-components/i18n/localePresets.js";
+import { EFWTable as ye } from "./react-components/tables/EFWTable/EFWTable.js";
+import { useTableController as ze } from "./react-components/tables/EFWTable/hooks/useTableController/useTableController.js";
+import { useDefaultFilterButton as Ye } from "./react-components/tables/EFWTable/hooks/useDefaultFilterButton/useDefaultFilterButton.js";
+import { EFWTableEmpty as je, EFWTableOverlay as qe } from "./react-components/tables/EFWTable/components/EFWTableOverlay/EFWTableOverlay.js";
 export {
+  Ie as DEFAULT_EFW_BUTTONS_LOCALE_TEXT,
+  Ne as DEFAULT_EFW_FIELDS_LOCALE_TEXT,
+  Ve as DEFAULT_EFW_FORM_LOCALE_TEXT,
+  be as DEFAULT_EFW_TABLE_LOCALE_TEXT,
   s as EFWAttachment,
   d as EFWAttachmentsField,
-  f as EFWButton,
-  T as EFWDatePicker,
-  B as EFWDatePickerField,
-  l as EFWDrawerButton,
-  I as EFWField,
-  Y as EFWForm,
-  _ as EFWFormMessageBarGroup,
-  u as EFWGroupButton,
-  k as EFWInput,
-  A as EFWInputField,
-  p as EFWMessageBarManager,
-  P as EFWNumberInput,
-  S as EFWNumberInputField,
-  G as EFWSwitch,
-  v as EFWSwitchField,
-  or as EFWTable,
-  pr as EFWTableEmpty,
-  xr as EFWTableOverlay,
-  O as EFWTagPicker,
-  j as EFWTagPickerField,
-  H as EFWTextArea,
-  K as EFWTextAreaField,
+  p as EFWButton,
+  We as EFWConversionError,
+  O as EFWDatePicker,
+  N as EFWDatePickerField,
+  u as EFWDrawerButton,
+  L as EFWField,
+  Te as EFWForm,
+  _e as EFWFormMessageBarGroup,
+  i as EFWGroupButton,
+  b as EFWInput,
+  R as EFWInputField,
+  a as EFWMessageBarManager,
+  w as EFWNumberInput,
+  X as EFWNumberInputField,
+  v as EFWSwitch,
+  J as EFWSwitchField,
+  ye as EFWTable,
+  je as EFWTableEmpty,
+  qe as EFWTableOverlay,
+  Q as EFWTagPicker,
+  re as EFWTagPickerField,
+  te as EFWTextArea,
+  Ee as EFWTextAreaField,
+  Le as EFWValuesToFlat,
+  ke as PORYGON_LOCALES,
+  Ge as PORYGON_LOCALE_EN,
+  Re as PORYGON_LOCALE_ES,
+  Ue as PORYGON_LOCALE_PT_BR,
+  Ae as PorygonI18nProvider,
+  D as enLocalizedStrings,
+  B as esLocalizedStrings,
+  ne as flatToEFWValues,
   o as formatFileSize,
-  Q as getEFWFormFieldDisplayText,
+  g as getAttachmentsFormattedValue,
+  C as getDatePickerFormattedValue,
   t as getErrorMessage,
   F as getFileIconUrl,
-  rr as useDrawer,
-  W as useEFWButton,
-  V as useFormController,
-  Fr as useTableController
+  xe as getFormFieldDisplayText,
+  k as getInputFormattedValue,
+  M as getNumberInputFormattedValue,
+  q as getSwitchFormattedValue,
+  $ as getTagPickerFormattedValue,
+  me as getTextAreaFormattedValue,
+  S as ptLocalizedStrings,
+  Oe as useButtonsLocaleText,
+  Ye as useDefaultFilterButton,
+  ce as useDrawer,
+  l as useEFWButton,
+  Pe as useFieldsLocaleText,
+  fe as useFormController,
+  De as useFormLocaleText,
+  Be as usePorygonLocaleText,
+  ze as useTableController,
+  Ce as useTableLocaleText
 };

package/dist/react-components/buttons/EFWButton/EFWButton.d.ts

@@ -32,7 +32,7 @@ import * as React from "react";
  *       return { success: false, error: error.message };
  *     }
  *   }}
- *   loadingText="Procesando datos..."
+ *   labels={{ loadingText: "Procesando datos..." }}
  *   autoLoading={true}
  *   successConfig={{
  *     text: "¡Completado!",

package/dist/react-components/buttons/EFWButton/EFWButton.hooks.js

@@ -1,61 +1,62 @@
 import * as t from "react";
-const w = (T = {}) => {
+const y = (p = {}) => {
   const {
-    onError: k,
-    onSuccess: m,
+    onError: C,
+    onSuccess: E,
     successTimeout: i = 2e3,
     errorTimeout: f = 2e3,
-    autoReset: a = !0
-  } = T, [E, s] = t.useState("idle"), [p, l] = t.useState(null), c = t.useRef(null), r = t.useCallback(() => {
+    autoReset: u = !0,
+    fallbackErrorMessage: g = "Operation failed"
+  } = p, [m, o] = t.useState("idle"), [R, l] = t.useState(null), c = t.useRef(null), r = t.useCallback(() => {
     c.current && (clearTimeout(c.current), c.current = null);
   }, []), n = t.useCallback(() => {
-    s("idle"), l(null), r();
+    o("idle"), l(null), r();
   }, [r]), b = t.useCallback(() => {
-    s("loading"), l(null), r();
+    o("loading"), l(null), r();
   }, [r]), d = t.useCallback(() => {
-    s((e) => e === "loading" ? "idle" : e), r();
-  }, [r]), C = t.useCallback(() => {
-    s("success"), l(null), m?.(), a && i > 0 && (r(), c.current = setTimeout(n, i));
-  }, [m, a, i, n, r]), u = t.useCallback(
+    o((e) => e === "loading" ? "idle" : e), r();
+  }, [r]), k = t.useCallback(() => {
+    o("success"), l(null), E?.(), u && i > 0 && (r(), c.current = setTimeout(n, i));
+  }, [E, u, i, n, r]), a = t.useCallback(
     (e) => {
-      l(e), s("error"), k?.(e), a && f > 0 && (r(), c.current = setTimeout(n, f));
+      l(e), o("error"), C?.(e), u && f > 0 && (r(), c.current = setTimeout(n, f));
     },
-    [k, a, f, n, r]
+    [C, u, f, n, r]
   ), S = t.useCallback(
     (e) => {
       if (!e)
         d();
       else if (typeof e == "object")
         if (e.success)
-          C();
+          k();
         else {
-          const o = e.error instanceof Error ? e.error : new Error(String(e.error || "Operation failed"));
-          u(o);
+          const s = e.error instanceof Error ? e.error : new Error(String(e.error || g));
+          a(s);
         }
     },
-    [C, u, d]
-  ), R = t.useCallback(
+    [k, a, d, g]
+  ), w = t.useCallback(
     async (e) => {
       try {
         b();
-        const o = await e();
-        S(o);
-      } catch (o) {
-        const g = o instanceof Error ? o : new Error(String(o));
-        throw u(g), g;
+        const s = await e();
+        S(s);
+      } catch (s) {
+        const T = s instanceof Error ? s : new Error(String(s));
+        throw a(T), T;
       }
     },
-    [b, S, u]
+    [b, S, a]
   );
   return t.useEffect(() => () => {
     r();
   }, [r]), {
     /** Estado actual del botón */
-    currentState: E,
+    currentState: m,
     /** Indica si el botón está en estado de carga */
-    isLoading: E === "loading",
+    isLoading: m === "loading",
     /** Error actual o null */
-    error: p,
+    error: R,
     /** Función para resetear el estado */
     reset: n,
     /** Función para iniciar estado de carga */
@@ -63,13 +64,13 @@ const w = (T = {}) => {
     /** Función para detener estado de carga */
     stopLoading: d,
     /** Función para establecer estado de éxito */
-    setSuccess: C,
+    setSuccess: k,
     /** Función para establecer estado de error */
-    setError: u,
+    setError: a,
     /** Función para ejecutar operaciones asíncronas */
-    executeAsync: R
+    executeAsync: w
   };
 };
 export {
-  w as useEFWButton
+  y as useEFWButton
 };