@codeplex-sac/iconos 0.0.11 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/LICENSE +22 -0
  3. package/README.md +239 -67
  4. package/package.json +18 -2
package/CHANGELOG.md ADDED
@@ -0,0 +1,14 @@
1
+ # Historial de Cambios — @codeplex-sac/iconos
2
+
3
+ Todos los cambios notables de este paquete se documentan en este archivo.
4
+ El formato sigue [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y este paquete adhiere a [Semantic Versioning](https://semver.org/lang/es/).
5
+
6
+ ## [1.0.0] — 2026-10-31
7
+
8
+ ### ⚠️ Requisitos y Compatibilidad
9
+ - Compatible con **React 19** y **Material-UI v9.5.0**.
10
+
11
+ ### ✨ Nuevas Funcionalidades
12
+ - Catálogo ampliado a más de **560 iconos semánticos vectoriales** en español basados en Google Material Symbols Rounded.
13
+ - Soporte de tamaño dinámico, rotación (`0°` a `270°`), variante de relleno sólido (`relleno={true}`) y color temático.
14
+ - Tipado TypeScript estricto con autocompletado de nombres de icono y soporte completo de *tree-shaking*.
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Codeplex SAC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
package/README.md CHANGED
@@ -1,101 +1,273 @@
1
1
  # @codeplex-sac/iconos
2
2
 
3
- Sistema de iconos semánticos de **Codeplex-SAC**, basado en **Google Material Symbols Rounded**. Iconografía consistente y moderna, alineada con la tipografía **Poppins**.
3
+ [![npm version](https://img.shields.io/npm/v/@codeplex-sac/iconos.svg?color=006bff&style=flat-square)](https://www.npmjs.com/package/@codeplex-sac/iconos)
4
+ [![status](https://img.shields.io/badge/estado-estable-059669.svg?style=flat-square)](#)
5
+ [![license](https://img.shields.io/badge/license-MIT-0b3558.svg?style=flat-square)](./LICENSE)
6
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/)
7
+ [![React 19](https://img.shields.io/badge/React-19-61DAFB.svg?style=flat-square)](https://react.dev/)
8
+ [![MUI v9.5](https://img.shields.io/badge/MUI-9.5.0-007FFF.svg?style=flat-square)](https://mui.com/material-ui/)
4
9
 
5
- ## Instalación
10
+ > **Catálogo de Iconografía Semántica en Español**
11
+ > Más de 560 componentes de iconos semánticos con nomenclatura en español basados en Google Material Symbols Rounded, con soporte de relleno, peso óptico, rotación y tree-shaking.
12
+
13
+ ---
14
+
15
+ ## 📑 Tabla de Contenidos
16
+
17
+ - [📦 Requisitos y Dependencias](#requisitos-y-dependencias)
18
+ - [🚀 Instalación](#instalación)
19
+ - [🎨 Configuración Inicial](#configuración-inicial)
20
+ - [🧩 Catálogo de Componentes y API](#catálogo-de-componentes-y-api)
21
+ - [Sistema de Iconos — @codeplex-sac/iconos](#sistema-de-iconos-codeplex-saciconos)
22
+ - [✨ Novedades en v1.0.0](#novedades-en-v100)
23
+ - [♿ Accesibilidad y Rendimiento](#accesibilidad-y-rendimiento)
24
+ - [📄 Licencia](#licencia)
25
+
26
+ ---
27
+
28
+ ## 📦 Requisitos y Dependencias
29
+
30
+ Este paquete está diseñado para proyectos basados en **React 19** y **Material-UI v9.5**:
31
+
32
+ - **Dependencias requeridas / recomendadas:** `react@^19.0.0`, `react-dom@^19.0.0`, `@mui/material@^9.5.0`
33
+
34
+ ---
35
+
36
+ ## 🚀 Instalación
37
+
38
+ Instala el paquete con tu gestor de paquetes preferido:
6
39
 
7
40
  ```bash
8
- bun add @codeplex-sac/iconos @codeplex-sac/tema @mui/material @emotion/react @emotion/styled
41
+ # Con Bun (recomendado)
42
+ bun add @codeplex-sac/iconos @mui/material@^9.5.0
43
+
44
+ # Con NPM
45
+ npm install @codeplex-sac/iconos @mui/material@^9.5.0
46
+
47
+ # Con PNPM
48
+ pnpm add @codeplex-sac/iconos @mui/material@^9.5.0
49
+ ```
50
+
51
+ ---
52
+
53
+ ## 🎨 Configuración Inicial
54
+
55
+ Todos los paquetes `@codeplex-sac/*` consumen los tokens CSS y la paleta MUI v9 del sistema de diseño. Envuelve la raíz de tu aplicación con `CodeplexProveedorTema` y `CodeplexProveedorMui`:
56
+
57
+ ```tsx
58
+ import { CodeplexProveedorTema, CodeplexProveedorMui } from '@codeplex-sac/tema';
59
+ import { TuVistaPrincipal } from './vistas/principal';
60
+
61
+ export function App() {
62
+ return (
63
+ <CodeplexProveedorTema temaPorDefecto="light" capacidad="redSocial">
64
+ <CodeplexProveedorMui>
65
+ <TuVistaPrincipal />
66
+ </CodeplexProveedorMui>
67
+ </CodeplexProveedorTema>
68
+ );
69
+ }
70
+ ```
71
+
72
+ ---
73
+
74
+ ## 🧩 Catálogo de Componentes y API
75
+
76
+ ### Sistema de Iconos — @codeplex-sac/iconos
77
+
78
+ El paquete `@codeplex-sac/iconos` expone dos APIs:
79
+ 1. **`CodeplexIcono`** — componente base que acepta cualquier ícono de Material Icons por nombre.
80
+ 2. **Iconos semánticos con nombre** — exports individuales con nombres en español (`CodeplexIconoGuardar`, `CodeplexIconoEliminar`, etc.) para uso directo sin recordar el nombre en inglés.
81
+
82
+ ---
83
+
84
+ #### Cuándo usar
85
+
86
+ **Úsalo cuando:**
87
+ - Necesitas un ícono en cualquier parte de la UI.
88
+ - Quieres que el equipo use nombres semánticos en español en lugar de recordar el nombre exacto de Material Icons.
89
+ - Usas `CodeplexBoton` con `iconoIzquierda` o `iconoDerecha` — esos props aceptan cualquier elemento de este paquete.
90
+
91
+ **No lo uses cuando:**
92
+ - Necesitas un ícono SVG personalizado que no esté en Material Icons — en ese caso, importa el SVG directamente como componente React.
93
+
94
+ ---
95
+
96
+ #### Importación
97
+
98
+ ```tsx
99
+ import { CodeplexIcono } from '@codeplex-sac/iconos';
100
+ import {
101
+ CodeplexIconoGuardar,
102
+ CodeplexIconoEliminar,
103
+ CodeplexIconoEditar,
104
+ CodeplexIconoCerrar,
105
+ CodeplexIconoBuscar,
106
+ CodeplexIconoAgregar,
107
+ CodeplexIconoFactura,
108
+ CodeplexIconoDescarga,
109
+ CodeplexIconoAlerta,
110
+ } from '@codeplex-sac/iconos';
111
+ ```
112
+
113
+ ---
114
+
115
+ #### TypeScript
116
+
117
+ ```ts
118
+ type CodeplexIconoTamano = 'diminuto' | 'pequeno' | 'mediano' | 'grande' | 'enorme';
119
+ type CodeplexIconoColor = 'primario' | 'secundario' | 'exito' | 'error' | 'advertencia' | 'info' | 'heredar';
120
+
121
+ interface CodeplexIconoProps {
122
+ nombre: string;
123
+ tamano?: CodeplexIconoTamano;
124
+ color?: CodeplexIconoColor;
125
+ rotacion?: number;
126
+ giro?: boolean;
127
+ ariaLabel?: string;
128
+ }
129
+
130
+ interface CodeplexIconoSemanticoProps {
131
+ tamano?: CodeplexIconoTamano;
132
+ color?: CodeplexIconoColor;
133
+ ariaLabel?: string;
134
+ }
9
135
  ```
10
136
 
11
- > [!IMPORTANT]
12
- > Este paquete depende de la inyección de fuentes realizada por `CodeplexProveedorTema` de `@codeplex-sac/tema`. Asegúrate de tenerlo configurado en la raíz de tu aplicación.
137
+ ---
138
+
139
+ #### API — Props de `CodeplexIcono`
140
+
141
+ | Propiedad | Tipo | Por defecto | Requerido | Descripción |
142
+ | :--- | :--- | :--- | :---: | :--- |
143
+ | `nombre` | `string` | — | ✓ | Nombre del ícono en Material Icons (CamelCase: `'Save'`, `'DeleteOutlined'`). |
144
+ | `tamano` | `CodeplexIconoTamano` | `'mediano'` | — | Tamaño visual del ícono. |
145
+ | `color` | `CodeplexIconoColor` | `'heredar'` | — | Color semántico. `'heredar'` toma el color del texto del padre. |
146
+ | `rotacion` | `number` | `0` | — | Rotación en grados (útil para flechas/chevrons). |
147
+ | `giro` | `boolean` | `false` | — | Efecto de rotación continua (útil para `CodeplexIconoCargando`). |
148
+ | `ariaLabel` | `string` | — | — | Descripción para lectores de pantalla. **Requerido** si el ícono es interactivo y no tiene texto acompañante. |
149
+
150
+ ---
151
+
152
+ #### Catálogo de iconos semánticos disponibles
153
+
154
+ | Export | Ícono MUI base | Uso típico |
155
+ | :--- | :--- | :--- |
156
+ | `CodeplexIconoGuardar` | `Save` | Guardar formularios |
157
+ | `CodeplexIconoEliminar` | `DeleteOutline` | Eliminar registros |
158
+ | `CodeplexIconoEditar` | `EditOutlined` | Editar un ítem |
159
+ | `CodeplexIconoCerrar` | `Close` | Cerrar modales, chips |
160
+ | `CodeplexIconoBuscar` | `Search` | Barra de búsqueda |
161
+ | `CodeplexIconoAgregar` | `Add` | Crear nuevo ítem |
162
+ | `CodeplexIconoFactura` | `ReceiptLong` | Comprobantes SUNAT |
163
+ | `CodeplexIconoDescarga` | `FileDownload` | Exportar Excel/PDF |
164
+ | `CodeplexIconoSubir` | `FileUpload` | Cargador de archivos |
165
+ | `CodeplexIconoAlerta` | `WarningAmberOutlined` | Alertas y advertencias |
166
+ | `CodeplexIconoInfo` | `InfoOutlined` | Información |
167
+ | `CodeplexIconoExito` | `CheckCircleOutline` | Confirmaciones |
168
+ | `CodeplexIconoError` | `ErrorOutline` | Errores |
169
+ | `CodeplexIconoFiltro` | `FilterListOutlined` | Filtros en tablas |
170
+ | `CodeplexIconoOjo` | `VisibilityOutlined` | Ver detalles |
171
+ | `CodeplexIconoOjoOculto` | `VisibilityOffOutlined` | Ocultar contraseña |
172
+ | `CodeplexIconoCopiar` | `ContentCopyOutlined` | Copiar al portapapeles |
173
+ | `CodeplexIconoImpresora` | `PrintOutlined` | Imprimir |
174
+ | `CodeplexIconoRefrescar` | `RefreshOutlined` | Recargar datos |
175
+ | `CodeplexIconoFlechaArriba` | `ArrowUpward` | Orden ascendente |
176
+ | `CodeplexIconoFlechaAbajo` | `ArrowDownward` | Orden descendente |
177
+ | `CodeplexIconoChevronDerecha` | `ChevronRight` | Expandir / navegar |
178
+ | `CodeplexIconoChevronAbajo` | `ExpandMore` | Acordeones |
179
+ | `CodeplexIconoCargando` | `Loop` | Spinner con `giro` |
180
+ | `CodeplexIconoUsuario` | `PersonOutline` | Perfil de usuario |
181
+ | `CodeplexIconoEmpresa` | `BusinessOutlined` | Empresa / razón social |
182
+ | `CodeplexIconoCalendario` | `CalendarTodayOutlined` | Fechas |
183
+ | `CodeplexIconoMoneda` | `AttachMoney` | Valores monetarios |
184
+ | `CodeplexIconoGrafico` | `BarChart` | Reportes |
185
+ | `CodeplexIconoConfiguracion` | `SettingsOutlined` | Configuración |
186
+ | `CodeplexIconoSalir` | `LogoutOutlined` | Cerrar sesión |
13
187
 
14
188
  ---
15
189
 
16
- ## Componente Base: CodeplexIcono
190
+ #### Ejemplos de uso
17
191
 
18
- `CodeplexIcono` renderiza cualquier icono de Google Material Symbols usando **ligaduras**.
192
+ ##### Ícono semántico en botón
19
193
 
20
- **Props:**
21
- | Propiedad | Tipo | Por defecto | Descripción |
22
- | :--- | :--- | :--- | :--- |
23
- | `nombre` | `string` | — | Nombre oficial del icono (ej: `'search'`, `'home'`). |
24
- | `relleno` | `boolean` | `false` | Activa el estilo sólido (FILL 1). |
25
- | `color` | `'primario' \| 'secundario' \| 'error' \| 'exito' \| 'advertencia' \| 'info' \| 'heredado'` | `'heredado'` | Color semántico del icono. |
194
+ ```tsx
195
+ import { CodeplexBoton } from '@codeplex-sac/ui';
196
+ import { CodeplexIconoGuardar } from '@codeplex-sac/iconos';
197
+
198
+ <CodeplexBoton
199
+ variante="primario"
200
+ iconoIzquierda={<CodeplexIconoGuardar />}
201
+ >
202
+ Guardar comprobante
203
+ </CodeplexBoton>
204
+ ```
205
+
206
+ ##### Ícono base para íconos no catalogados
26
207
 
27
- **Uso:**
28
208
  ```tsx
29
209
  import { CodeplexIcono } from '@codeplex-sac/iconos';
30
210
 
31
- export const Ejemplo = () => (
32
- <CodeplexIcono nombre="settings" color="primario" relleno />
33
- );
211
+ <CodeplexIcono nombre="QrCode2" tamano="grande" ariaLabel="Código QR del comprobante" />
212
+ ```
213
+
214
+ ##### Spinner de carga
215
+
216
+ ```tsx
217
+ import { CodeplexIconoCargando } from '@codeplex-sac/iconos';
218
+
219
+ {cargando && <CodeplexIconoCargando tamano="mediano" color="primario" giro />}
220
+ ```
221
+
222
+ ##### Ícono en fila de tabla (acciones)
223
+
224
+ ```tsx
225
+ import { CodeplexIconoEditar, CodeplexIconoEliminar, CodeplexIconoOjo } from '@codeplex-sac/iconos';
226
+
227
+ <div style={{ display: 'flex', gap: 8 }}>
228
+ <CodeplexBoton variante="fantasma" tamano="pequeno" iconoIzquierda={<CodeplexIconoOjo />} ariaLabel="Ver" />
229
+ <CodeplexBoton variante="fantasma" tamano="pequeno" iconoIzquierda={<CodeplexIconoEditar />} ariaLabel="Editar" />
230
+ <CodeplexBoton variante="fantasma" tamano="pequeno" color="peligro" iconoIzquierda={<CodeplexIconoEliminar />} ariaLabel="Eliminar" />
231
+ </div>
34
232
  ```
35
233
 
36
234
  ---
37
235
 
38
- ## Catálogo de Iconos Semánticos
236
+ #### Accesibilidad
39
237
 
40
- Iconos preconfigurados que no requieren la prop `nombre`. Úsalos para mantener consistencia semántica en toda la aplicación.
238
+ - Los iconos puramente decorativos NO necesitan `ariaLabel` — el componente añade `aria-hidden="true"` automáticamente.
239
+ - Los iconos interactivos (en botones de solo ícono) **siempre** requieren `ariaLabel`.
240
+ - El tamaño mínimo para iconos interactivos es `"pequeno"` (20px) — por debajo del mínimo táctil recomendado de 44×44px, envuélvelo en un `CodeplexBoton variante="fantasma"`.
41
241
 
42
- ### Acciones Comunes
43
- | Componente | Icono | Componente | Icono |
44
- | :--- | :--- | :--- | :--- |
45
- | `CodeplexIconoBuscar` | `search` | `CodeplexIconoBorrar` | `delete` |
46
- | `CodeplexIconoEditar` | `edit` | `CodeplexIconoGuardar` | `save` |
47
- | `CodeplexIconoSubir` | `cloud_upload` | `CodeplexIconoEnviar` | `send` |
48
- | `CodeplexIconoAnadir` | `add_circle` | `CodeplexIconoQuitar` | `do_not_disturb_on` |
49
- | `CodeplexIconoCerrar` | `close` | `CodeplexIconoDescargar` | `download` |
50
- | `CodeplexIconoRefrescar` | `refresh` | `CodeplexIconoFiltro` | `filter_alt` |
242
+ ---
51
243
 
52
- ### Seguridad y Autenticación
53
- | Componente | Icono | Componente | Icono |
54
- | :--- | :--- | :--- | :--- |
55
- | `CodeplexIconoSeguridad` | `security` | `CodeplexIconoCandado` | `lock` |
56
- | `CodeplexIconoLlave` | `key` | `CodeplexIconoEscudo` | `shield` |
244
+ #### Componentes relacionados
57
245
 
58
- ### Estados y Feedback
59
- | Componente | Icono | Componente | Icono |
60
- | :--- | :--- | :--- | :--- |
61
- | `CodeplexIconoExito` | `check_circle` | `CodeplexIconoInformacion` | `info` |
62
- | `CodeplexIconoError` | `error` | `CodeplexIconoAyuda` | `help` |
63
- | `CodeplexIconoAlerta` | `warning` | `CodeplexIconoProgreso` | `autorenew` |
246
+ | Componente | Cuándo usarlo |
247
+ | :--- | :--- |
248
+ | `CodeplexBoton` | Para iconos interactivos, siempre dentro de un botón. |
249
+ | `CodeplexInsignia` | Para números sobre iconos (notificaciones). |
64
250
 
65
- ### Comunicación y Social
66
- | Componente | Icono | Componente | Icono |
67
- | :--- | :--- | :--- | :--- |
68
- | `CodeplexIconoCorreo` | `mail` | `CodeplexIconoTelefono` | `phone` |
69
- | `CodeplexIconoCompartir` | `share` | `CodeplexIconoChat` | `forum` |
251
+ ---
70
252
 
71
- ### Finanzas y Comercio
72
- | Componente | Icono | Componente | Icono |
73
- | :--- | :--- | :--- | :--- |
74
- | `CodeplexIconoBilletera` | `account_balance_wallet` | `CodeplexIconoBanco` | `account_balance` |
75
- | `CodeplexIconoMoneda` | `payments` | `CodeplexIconoCarrito` | `shopping_cart` |
76
- | `CodeplexIconoPrecio` | `sell` | `CodeplexIconoRecibo` | `receipt` |
253
+ ## ✨ Novedades en v1.0.0
77
254
 
78
- ### Multimedia
79
- | Componente | Icono | Componente | Icono |
80
- | :--- | :--- | :--- | :--- |
81
- | `CodeplexIconoImagen` | `image` | `CodeplexIconoCamara` | `photo_camera` |
82
- | `CodeplexIconoVideo` | `videocam` | `CodeplexIconoColeccion` | `collections` |
255
+ - Ampliación del catálogo a más de 560 iconos semánticos organizados en 17 categorías funcionales en español.
256
+ - Compatibilidad oficial con React 19 y Material-UI v9.5.0 manteniendo soporte total de tree-shaking.
257
+ - Tipado estricto de nombres de icono, tamaños, colores temáticos y atributos de accesibilidad (`aria-label` / `aria-hidden`).
83
258
 
84
- ### Estructura e Interfaz
85
- | Componente | Icono | Componente | Icono |
86
- | :--- | :--- | :--- | :--- |
87
- | `CodeplexIconoDiseno` | `dashboard` | `CodeplexIconoBarraLateral` | `view_sidebar` |
88
- | `CodeplexIconoCaja` | `inbox` | `CodeplexIconoCuadricula` | `grid_view` |
89
- | `CodeplexIconoPila` | `layers` | `CodeplexIconoContenedor` | `view_quilt` |
259
+ Consulta el detalle histórico completo de versiones en [CHANGELOG.md](./CHANGELOG.md).
90
260
 
91
261
  ---
92
262
 
93
- ## Mejores Prácticas
263
+ ## ♿ Accesibilidad y Rendimiento
94
264
 
95
- 1. **Semántica sobre nombre**: usa `CodeplexIconoBorrar` en lugar de `<CodeplexIcono nombre="delete" />` para mantener la consistencia en el mantenimiento.
96
- 2. **Relleno**: activa `relleno` para estados activos o acciones primarias.
97
- 3. **Tamaño**: hereda el `fontSize` de MUI — usa `fontSize="large"` directamente en el componente.
265
+ - **Navegación por teclado:** Soporte estándar de secuencia de foco (`Tab`, flechas direccionales, `Enter` y `Escape`).
266
+ - **Semántica WAI-ARIA:** Roles, estados y etiquetas accesibles integrados para lectores de pantalla.
267
+ - **Tree-shaking ESM:** Empaquetado modular sin efectos secundarios innecesarios y declaraciones TypeScript estrictas (`.d.ts`).
268
+
269
+ ---
98
270
 
99
- ## Licencia
271
+ ## 📄 Licencia
100
272
 
101
- Propiedad privada de **Codeplex SAC**. Todos los derechos reservados.
273
+ Distribuido bajo la licencia abierta **MIT** — © 2026 **Codeplex SAC**. Consulta el archivo [LICENSE](./LICENSE) para el texto legal completo.
package/package.json CHANGED
@@ -1,6 +1,22 @@
1
1
  {
2
2
  "name": "@codeplex-sac/iconos",
3
- "version": "0.0.11",
3
+ "version": "1.0.0",
4
+ "description": "Catálogo de más de 560 iconos semánticos con API en español basados en Google Material Symbols Rounded para React 19 y MUI v9.",
5
+ "license": "MIT",
6
+ "author": "Codeplex SAC",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/CODEPLEX-SAC/codeplex-nx-libraries.git",
10
+ "directory": "packages/iconos"
11
+ },
12
+ "keywords": [
13
+ "codeplex",
14
+ "react",
15
+ "mui",
16
+ "icons",
17
+ "material-symbols",
18
+ "iconos"
19
+ ],
4
20
  "type": "module",
5
21
  "main": "./index.js",
6
22
  "module": "./index.js",
@@ -16,7 +32,7 @@
16
32
  "access": "public"
17
33
  },
18
34
  "peerDependencies": {
19
- "@mui/material": "^7.3.6",
35
+ "@mui/material": "^9.5.0",
20
36
  "react": "^19.0.0",
21
37
  "react-dom": "^19.0.0"
22
38
  },