@widergy/energy-ui 3.141.4 → 3.142.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [3.142.0](https://github.com/widergy/energy-ui/compare/v3.141.4...v3.142.0) (2026-04-14)
+
+
+### Features
+
+* [AXCH-1428] wrapper observation component ([#773](https://github.com/widergy/energy-ui/issues/773)) ([afb9df4](https://github.com/widergy/energy-ui/commit/afb9df458b74a543254473724644e79662f37d6b))
+
 ## [3.141.4](https://github.com/widergy/energy-ui/compare/v3.141.3...v3.141.4) (2026-04-14)
 
 

package/dist/components/UTWrapperObservation/README.md

@@ -0,0 +1,91 @@
+# UTWrapperObservation
+
+Wrapper que agrega acciones (ícono + tooltip) a un campo de formulario. Muestra todos los botones configurados en `observationWrapperConfiguration`, cambiando el layout según si hay observaciones activas en `field`. Soporta N acciones simultáneas.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `node` | Required | Contenido del campo a envolver. |
+| `dataTestId` | `string` | `undefined` | ID para testing. El container recibe `dataTestId` y cada action icon recibe `${dataTestId}.actionIcon.${config.key}`. |
+| `field` | `objectOf(bool)` | `undefined` | Objeto del campo. Las claves con valor `true` que coincidan con algún `key` en `observationWrapperConfiguration` renderizarán su acción correspondiente. |
+| `observationWrapperConfiguration` | `arrayOf(shape)` | `undefined` | Array de configuraciones para el wrapper. Ver estructura abajo. |
+
+### Estructura de `observationWrapperConfiguration`
+
+Cada objeto del array puede contener:
+
+| Campo | Type | Description |
+|-------|------|-------------|
+| `key` | `string` | Identificador de la acción. Si coincide con una clave `true` en `field`, determina que hay observaciones activas y cambia el layout a gap inline. |
+| `buttonProps` | `object` | Props pasados directamente al componente `UTButton` que se renderiza como ícono de acción. |
+| `action` | `func` | Callback ejecutado al hacer click sobre el botón de acción. |
+| `textTooltip` | `string` | Texto que se muestra en el tooltip al hacer hover sobre el botón. |
+
+## Lógica de renderizado
+
+```
+observationWrapperConfiguration vacío o undefined → retorna children sin wrapping
+sin coincidencias en field → renderiza wrapper con todos los botones en position:absolute (se revelan en hover)
+con al menos una coincidencia en field → renderiza wrapper con gap + todos los botones (se revelan en hover)
+```
+
+## Ejemplos
+
+### Uso básico (con observación activa)
+
+```jsx
+const observationConfig = [
+  {
+    key: 'observation',
+    buttonProps: {
+      children: '2',
+      colorTheme: 'negative',
+      Icon: 'IconMessagePlus',
+      size: 'small'
+    },
+    action: () => console.log('Observación ejecutada'),
+    textTooltip: 'Observar campo'
+  }
+];
+
+<UTWrapperObservation
+  field={{ observation: true }}
+  observationWrapperConfiguration={observationConfig}
+>
+  <UTLabel variant="body1">0112 4567890</UTLabel>
+</UTWrapperObservation>
+```
+
+### Sin observación activa (field.observation false)
+
+```jsx
+<UTWrapperObservation
+  field={{ observation: false }}
+  observationWrapperConfiguration={observationConfig}
+>
+  <UTLabel variant="body1">0112 4567890</UTLabel>
+</UTWrapperObservation>
+// → renderiza el wrapper con los botones en position:absolute encima del children
+// los botones se revelan al hacer hover
+```
+
+### Múltiples acciones
+
+```jsx
+<UTWrapperObservation
+  field={{ observation: true, review: true }}
+  observationWrapperConfiguration={[
+    { key: 'observation', ... },
+    { key: 'review', ... }
+  ]}
+>
+  <UTLabel variant="body1">0112 4567890</UTLabel>
+</UTWrapperObservation>
+// → renderiza children + 2 botones con tooltip
+```
+
+## Componentes relacionados
+
+- **UTButton**: Usado internamente para el botón de acción.
+- **UTTooltip**: Usado para mostrar el `textTooltip` al hacer hover sobre el botón.

package/dist/components/UTWrapperObservation/UTWrapperObservation.stories.js

@@ -0,0 +1,251 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.SinObservacionEnField = exports.SinConfiguracion = exports.Playground = exports.ConObservacion = exports.ConMultiplesAcciones = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _UTLabel = _interopRequireDefault(require("../UTLabel"));
+var _ = _interopRequireDefault(require("."));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); } /* eslint-disable no-alert */
+const observationConfig = [{
+  buttonProps: {
+    colorTheme: 'negative',
+    Icon: 'IconMessagePlus',
+    size: 'small'
+  },
+  action: () => alert('Acción de observación ejecutada'),
+  key: 'observation',
+  textTooltip: 'Observar campo'
+}];
+const multipleActionsConfig = [{
+  buttonProps: {
+    colorTheme: 'negative',
+    Icon: 'IconMessagePlus',
+    size: 'small'
+  },
+  action: () => alert('Acción de observación ejecutada'),
+  key: 'observation',
+  textTooltip: 'Observar campo'
+}, {
+  buttonProps: {
+    colorTheme: 'blue',
+    Icon: 'IconFlag',
+    size: 'small'
+  },
+  action: () => alert('Acción de revisión ejecutada'),
+  key: 'review',
+  textTooltip: 'Revisar campo'
+}];
+const FieldContent = () => /*#__PURE__*/_react.default.createElement("div", {
+  style: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4px'
+  }
+}, /*#__PURE__*/_react.default.createElement(_UTLabel.default, {
+  colorTheme: "gray",
+  variant: "caption"
+}, "Tel\xE9fono *"), /*#__PURE__*/_react.default.createElement(_UTLabel.default, {
+  variant: "body1"
+}, "0112 4567890"));
+var _default = exports.default = {
+  args: {
+    field: {
+      observation: true
+    },
+    observationWrapperConfiguration: observationConfig
+  },
+  argTypes: {
+    field: {
+      control: 'object',
+      description: 'Objeto del campo. Las claves con valor `true` que coincidan con algún `key` en `observationWrapperConfiguration` renderizarán su acción correspondiente.',
+      table: {
+        defaultValue: {
+          summary: 'undefined'
+        },
+        type: {
+          summary: 'objectOf(bool)'
+        }
+      }
+    },
+    observationWrapperConfiguration: {
+      control: false,
+      description: 'Array de acciones disponibles para el wrapper. Cada objeto debe tener `key`, `buttonProps`, `action` y `textTooltip`. Todos los botones se muestran siempre; el `key` se usa para detectar si hay observaciones activas en `field` y cambiar el layout.',
+      table: {
+        defaultValue: {
+          summary: 'undefined'
+        },
+        type: {
+          summary: 'arrayOf(shape({ key, buttonProps, action, textTooltip }))'
+        }
+      }
+    },
+    children: {
+      control: false,
+      description: 'Contenido del campo a envolver.',
+      table: {
+        defaultValue: {
+          summary: 'undefined'
+        },
+        type: {
+          summary: 'ReactNode'
+        }
+      }
+    },
+    dataTestId: {
+      control: 'text',
+      description: 'ID para testing. El container recibe `dataTestId` y cada action icon recibe `${dataTestId}.actionIcon.${config.key}`.',
+      table: {
+        defaultValue: {
+          summary: 'undefined'
+        },
+        type: {
+          summary: 'string'
+        }
+      }
+    }
+  },
+  component: _.default,
+  parameters: {
+    backgrounds: {
+      default: 'light03',
+      values: [{
+        name: 'light03',
+        value: '#F4F5F7'
+      }]
+    },
+    docs: {
+      description: {
+        component: 'Wrapper que agrega acciones (ícono + tooltip) a un campo de formulario. ' + 'Muestra todos los botones de `observationWrapperConfiguration` siempre que haya al menos uno configurado. ' + 'Si algún `key` de la configuración coincide con una clave `true` en `field`, aplica un gap entre el children y los botones; ' + 'si no hay coincidencias, los botones se posicionan encima del children y se revelan en hover.'
+      }
+    }
+  },
+  title: 'Energy-UI/UTWrapperObservation'
+};
+const ConObservacion = exports.ConObservacion = {
+  args: {
+    children: /*#__PURE__*/_react.default.createElement(FieldContent, null),
+    field: {
+      observation: true
+    },
+    observationWrapperConfiguration: observationConfig
+  },
+  name: 'Con observación activa',
+  parameters: {
+    docs: {
+      description: {
+        story: 'Campo con `field.observation: true` y configuración válida. Se muestra el ícono de observación ' + 'a la derecha del campo. Al hacer hover sobre el ícono aparece el tooltip; al hacer click se ejecuta la acción.'
+      }
+    }
+  }
+};
+const SinObservacionEnField = exports.SinObservacionEnField = {
+  args: {
+    children: /*#__PURE__*/_react.default.createElement(FieldContent, null),
+    field: {
+      observation: false
+    },
+    observationWrapperConfiguration: observationConfig
+  },
+  name: 'Sin observación activa',
+  parameters: {
+    docs: {
+      description: {
+        story: '`field.observation` es `false`. El componente renderiza el wrapper con los botones posicionados encima del children (`position: absolute`). Los botones se revelan al hacer hover.'
+      }
+    }
+  }
+};
+const SinConfiguracion = exports.SinConfiguracion = {
+  args: {
+    children: /*#__PURE__*/_react.default.createElement(FieldContent, null),
+    field: {
+      observation: true
+    },
+    observationWrapperConfiguration: []
+  },
+  name: 'Sin configuración (fallback)',
+  parameters: {
+    docs: {
+      description: {
+        story: '`field.observation: true` pero sin acciones en `observationWrapperConfiguration`. ' + 'El componente devuelve los `children` sin wrapping.'
+      }
+    }
+  }
+};
+const ConMultiplesAcciones = exports.ConMultiplesAcciones = {
+  args: {
+    children: /*#__PURE__*/_react.default.createElement(FieldContent, null),
+    field: {
+      observation: true,
+      review: true
+    },
+    observationWrapperConfiguration: multipleActionsConfig
+  },
+  name: 'Múltiples acciones',
+  parameters: {
+    docs: {
+      description: {
+        story: 'Campo con dos acciones activas (`field.observation: true` y `field.review: true`). ' + 'Se renderiza un botón por cada entrada de `observationWrapperConfiguration` cuya `key` coincida con un valor `true` en `field`.'
+      }
+    }
+  }
+};
+const Playground = exports.Playground = {
+  args: {
+    children: /*#__PURE__*/_react.default.createElement(FieldContent, null),
+    field: {
+      observation: true
+    },
+    configJSON: [{
+      key: 'observation',
+      textTooltip: '2 Campos observados',
+      buttonProps: {
+        colorTheme: 'gray',
+        Icon: 'IconMessagePlus',
+        size: 'small',
+        children: 2,
+        variant: 'semitransparent'
+      }
+    }]
+  },
+  argTypes: {
+    field: {
+      control: {
+        type: 'object'
+      }
+    },
+    configJSON: {
+      control: {
+        type: 'object'
+      },
+      description: 'Array de acciones para el wrapper. Editá el JSON para agregar o quitar botones. El `action` se inyecta automáticamente.',
+      name: 'observationWrapperConfiguration',
+      table: {
+        type: {
+          summary: 'arrayOf(shape({ key, buttonProps, textTooltip }))'
+        }
+      }
+    },
+    observationWrapperConfiguration: {
+      table: {
+        disable: true
+      }
+    }
+  },
+  name: 'Playground',
+  render: _ref => {
+    let {
+      configJSON,
+      ...args
+    } = _ref;
+    return /*#__PURE__*/_react.default.createElement(_.default, _extends({}, args, {
+      observationWrapperConfiguration: configJSON === null || configJSON === void 0 ? void 0 : configJSON.map(config => ({
+        ...config,
+        action: () => alert("Acci\xF3n ejecutada: ".concat(config.key)) // eslint-disable-line no-alert
+      }))
+    }), args.children);
+  }
+};

package/dist/components/UTWrapperObservation/index.js

@@ -0,0 +1,59 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _propTypes = require("prop-types");
+var _UTTooltip = _interopRequireDefault(require("../UTTooltip"));
+var _UTButton = _interopRequireDefault(require("../UTButton"));
+var _lodash = require("lodash");
+var _stylesModule = _interopRequireDefault(require("./styles.module.scss"));
+var _utils = require("./utils");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const UTWrapperObservation = _ref => {
+  let {
+    field,
+    observationWrapperConfiguration,
+    children,
+    dataTestId
+  } = _ref;
+  const matchingConfigs = (0, _utils.getMatchingConfigs)(observationWrapperConfiguration, field);
+  const hasObservation = !(0, _lodash.isEmpty)(matchingConfigs);
+  if (!(observationWrapperConfiguration !== null && observationWrapperConfiguration !== void 0 && observationWrapperConfiguration.length)) {
+    return children;
+  }
+  return /*#__PURE__*/_react.default.createElement("div", {
+    className: "".concat(_stylesModule.default.container, " ").concat(hasObservation ? _stylesModule.default.withObservation : ''),
+    "data-testid": dataTestId
+  }, children, /*#__PURE__*/_react.default.createElement("div", {
+    className: _stylesModule.default.actionButtons
+  }, observationWrapperConfiguration.map(config => /*#__PURE__*/_react.default.createElement(_UTTooltip.default, {
+    key: config.key,
+    arrow: false,
+    content: config.textTooltip,
+    tippyProps: {
+      appendTo: () => document.body,
+      interactive: false
+    }
+  }, /*#__PURE__*/_react.default.createElement("div", {
+    className: _stylesModule.default.iconButton,
+    onClick: config.action,
+    role: "button",
+    tabIndex: 0,
+    "data-testid": dataTestId ? "".concat(dataTestId, ".actionIcon.").concat(config.key) : undefined
+  }, /*#__PURE__*/_react.default.createElement(_UTButton.default, config.buttonProps))))));
+};
+UTWrapperObservation.propTypes = {
+  children: _propTypes.node.isRequired,
+  dataTestId: _propTypes.string,
+  field: (0, _propTypes.objectOf)(_propTypes.bool),
+  observationWrapperConfiguration: (0, _propTypes.arrayOf)((0, _propTypes.shape)({
+    action: _propTypes.func,
+    buttonProps: _propTypes.object,
+    key: _propTypes.string,
+    textTooltip: _propTypes.string
+  }))
+};
+var _default = exports.default = UTWrapperObservation;

package/dist/components/UTWrapperObservation/styles.module.scss

@@ -0,0 +1,37 @@
+.actionButtons {
+  align-items: center;
+  display: flex;
+  gap: var(--gap-sm);
+  position: absolute;
+  right: 0;
+}
+
+.container {
+  align-items: center;
+  display: flex;
+  flex-direction: row;
+  position: relative;
+  width: max-content;
+
+  &:hover .iconButton {
+    opacity: 1;
+  }
+}
+
+.iconButton {
+  align-items: center;
+  cursor: pointer;
+  display: flex;
+  flex-shrink: 0;
+  justify-content: center;
+  opacity: 0;
+  transition: opacity 0.2s ease;
+}
+
+.withObservation {
+  gap: var(--gap-sm);
+
+  .actionButtons {
+    position: static;
+  }
+}

package/dist/components/UTWrapperObservation/utils.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getMatchingConfigs = void 0;
+const getMatchingConfigs = (observationWrapperConfiguration, field) => {
+  var _observationWrapperCo;
+  return (_observationWrapperCo = observationWrapperConfiguration === null || observationWrapperConfiguration === void 0 ? void 0 : observationWrapperConfiguration.filter(config => (field === null || field === void 0 ? void 0 : field[config.key]) === true)) !== null && _observationWrapperCo !== void 0 ? _observationWrapperCo : [];
+};
+exports.getMatchingConfigs = getMatchingConfigs;

package/dist/constants/testIds.js

@@ -162,6 +162,9 @@ const TEST_IDS = exports.TEST_IDS = {
   tabs: {
     tab: 'tabs.tab.'
   },
+  wrapperObservation: {
+    actionIcon: 'wrapperObservation.actionIcon.'
+  },
   workflowContainer: {
     bottomNav: {
       backButton: "".concat(ID_CONSTANTS.WORKFLOW_CONTAINER, ".").concat(ID_CONSTANTS.BOTTOM_NAV, ".backButton"),

package/dist/index.js

@@ -489,6 +489,12 @@ Object.defineProperty(exports, "UTWorkflowContainer", {
     return _UTWorkflowContainer.default;
   }
 });
+Object.defineProperty(exports, "UTWrapperObservation", {
+  enumerable: true,
+  get: function () {
+    return _UTWrapperObservation.default;
+  }
+});
 Object.defineProperty(exports, "WithLoading", {
   enumerable: true,
   get: function () {
@@ -613,6 +619,7 @@ var _UTValidation = _interopRequireDefault(require("./components/UTValidation"))
 var _UTVirtualizedList = _interopRequireDefault(require("./components/UTVirtualizedList"));
 var _UTVirtualKeyboard = _interopRequireDefault(require("./components/UTVirtualKeyboard"));
 var _UTWorkflowContainer = _interopRequireDefault(require("./components/UTWorkflowContainer"));
+var _UTWrapperObservation = _interopRequireDefault(require("./components/UTWrapperObservation"));
 var _WithLoading = _interopRequireDefault(require("./components/WithLoading"));
 var _WithTouch = _interopRequireDefault(require("./components/WithTouch"));
 var _stylesDeduplicationUtils = _interopRequireDefault(require("./utils/stylesDeduplicationUtils"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@widergy/energy-ui",
-  "version": "3.141.4",
+  "version": "3.142.0",
   "description": "Widergy Web Components",
   "author": "widergy",
   "license": "MIT",