@roax/ui 0.2.0 → 0.3.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 (8) hide show
  1. package/README.md +186 -170
  2. package/dist/index.js +461 -250
  3. package/dist/index.js.map +1 -1
  4. package/dist/index.mjs +492 -254
  5. package/dist/index.mjs.map +1 -1
  6. package/package.json +7 -5
  7. package/src/styles/_roax-colors.scss +107 -8
  8. package/src/styles/index.scss +3 -8
package/README.md CHANGED
@@ -1,7 +1,6 @@
1
1
  # @roax/ui
2
2
 
3
- Librería de componentes UI del sistema de diseño Roax.
4
- Construida sobre **React 18**, **CoreUI Pro** y **SCSS** con tokens de color propios.
3
+ Librería de componentes UI de Roax — construida sobre React 18, CoreUI Pro y Recharts. Lista para consumir desde cualquier plataforma React/Next.js.
5
4
 
6
5
  ---
7
6
 
@@ -14,260 +13,277 @@ npm install @roax/ui
14
13
  ### Peer dependencies requeridas
15
14
 
16
15
  ```bash
17
- npm install @coreui/react-pro @coreui/icons-react react react-dom
18
- # Opcional (requerida para IconButton con tooltip):
19
- npm install @tippyjs/react
16
+ npm install @coreui/react-pro @coreui/icons-react @coreui/icons @tippyjs/react lucide-react recharts react react-dom
20
17
  ```
21
18
 
22
19
  ---
23
20
 
24
21
  ## Uso
25
22
 
26
- ### 1. Importar estilos (una sola vez, en tu layout raíz)
23
+ ```jsx
24
+ import { SolidButton, GeneralCard, FunnelChart } from '@roax/ui'
25
+ ```
26
+
27
+ ### Estilos (colores y tokens CSS)
27
28
 
28
- El paquete asume que CoreUI Pro ya está configurado en tu proyecto.
29
- Luego importa los tokens de color ROAX:
29
+ Importa los design tokens en tu archivo SCSS global **después** de CoreUI:
30
30
 
31
31
  ```scss
32
- // En tu archivo SCSS principal (después de CoreUI)
33
32
  @import '@coreui/coreui-pro/scss/coreui';
34
33
  @import '@roax/ui/styles';
35
34
  ```
36
35
 
37
- O si usas el archivo de estilos global del proyecto:
36
+ O directamente el archivo de colores:
38
37
 
39
38
  ```scss
40
- // style.scss
41
- @import "variables";
42
- @import "@coreui/coreui-pro/scss/coreui";
43
- @import "@roax/ui/styles";
39
+ @import '@roax/ui/styles/roax-colors';
44
40
  ```
45
41
 
46
- ### 2. Importar componentes
42
+ Esto expone todas las variables CSS `--roax-*` en tu proyecto.
43
+
44
+ ---
45
+
46
+ ## Componentes
47
+
48
+ ### Buttons
49
+
50
+ | Componente | Descripción |
51
+ |---|---|
52
+ | `SolidButton` | Botón primario con soporte de loading, icono y colores CoreUI |
53
+ | `OutlineButton` | Botón con borde, mismas opciones que SolidButton |
54
+ | `TextButton` | Botón ghost sin fondo |
55
+ | `IconButton` | Botón de ícono circular con tooltip integrado |
47
56
 
48
57
  ```jsx
49
58
  import { SolidButton, OutlineButton, TextButton, IconButton } from '@roax/ui'
59
+ import { cilTrash } from '@coreui/icons'
60
+
61
+ <SolidButton title="Guardar" onClick={handleSave} />
62
+ <OutlineButton title="Cancelar" color="secondary" />
63
+ <TextButton>Ver detalle</TextButton>
64
+ <IconButton icon={cilTrash} tooltip="Eliminar" color="danger" />
50
65
  ```
51
66
 
52
67
  ---
53
68
 
54
- ## Componentes
55
-
56
- ### SolidButton
69
+ ### Cards
57
70
 
58
- Botón principal con fondo sólido y gradiente ROAX.
71
+ | Componente | Descripción |
72
+ |---|---|
73
+ | `GeneralCard` | Tarjeta de métrica con valor actual, anterior, variación % y tooltip |
74
+ | `MetricCard` | Tarjeta glassmorphism para KPIs de alto nivel |
59
75
 
60
76
  ```jsx
61
- <SolidButton
62
- title="Guardar"
63
- color="custom-primary" // default
64
- textColor="custom-white" // default
65
- loading={false}
66
- disabled={false}
67
- icon={cilCheck} // @coreui/icons
68
- onClick={() => {}}
77
+ import { GeneralCard } from '@roax/ui'
78
+
79
+ <GeneralCard
80
+ title="Ventas totales"
81
+ current={15420000}
82
+ previous={12300000}
83
+ change={25.4}
84
+ isPositive={true}
85
+ unit="COP"
86
+ previousDateRange="2024-03-01 - 2024-03-31"
87
+ tooltipText="Total de ventas brutas del período."
69
88
  />
70
89
  ```
71
90
 
72
- | Prop | Tipo | Default | Descripción |
73
- |-----------------|------------|-------------------|------------------------------------|
74
- | `title` | `string` | `'Button'` | Texto del botón |
75
- | `color` | `string` | `'custom-primary'`| Clase de color CoreUI |
76
- | `textColor` | `string` | `'custom-white'` | Clase de color del texto |
77
- | `loading` | `boolean` | `false` | Muestra spinner, deshabilita clic |
78
- | `disabled` | `boolean` | — | Deshabilita el botón |
79
- | `icon` | `array` | — | Ícono CIcon de `@coreui/icons` |
80
- | `svgComponent` | `component`| — | Componente SVG personalizado |
81
- | `badge` | `node` | — | Badge/chip junto al texto |
82
- | `type` | `string` | `'submit'` | Tipo HTML del botón |
83
- | `onClick` | `function` | — | Handler de clic |
84
- | `className` | `string` | `''` | Clases CSS adicionales |
91
+ **Unidades soportadas:** `'COP'` · `'%'` · `'x'` · `''` (número genérico)
85
92
 
86
93
  ---
87
94
 
88
- ### OutlineButton
95
+ ### Charts
89
96
 
90
- Botón con borde. Al hacer hover se rellena con el gradiente ROAX (cuando `color="custom-primary"`).
97
+ | Componente | Descripción |
98
+ |---|---|
99
+ | `FunnelChart` | Embudo horizontal con tarjetas de métricas |
100
+ | `TimeSeriesComparisonChart` | Gráfico de líneas para comparar series de tiempo |
101
+ | `TopProductsChart` | Ranking horizontal de productos más vendidos |
102
+ | `SalesByChannelChart` | Barras apiladas por canal (Meta, TikTok, Google) |
103
+ | `InvestmentByPlatformChart` | Gráfico de dona para inversión por plataforma |
91
104
 
92
105
  ```jsx
93
- <OutlineButton
94
- title="Cancelar"
95
- color="custom-primary"
96
- loading={false}
97
- disabled={false}
98
- icon={cilArrowLeft}
99
- onClick={() => {}}
106
+ import { FunnelChart, TimeSeriesComparisonChart } from '@roax/ui'
107
+
108
+ <FunnelChart data={[
109
+ { title: 'Impresiones', value: 120000, previous: 98000,
110
+ percentageChange: 22.4, isPositive: true, unit: '',
111
+ previousDateRange: '2024-03-01 - 2024-03-31' },
112
+ { title: 'Clics', value: 8400, previous: 7200,
113
+ percentageChange: 16.7, isPositive: true, unit: '' },
114
+ ]} />
115
+
116
+ <TimeSeriesComparisonChart
117
+ data={data} // [{ date: '2024-05-01', ventas: 800000, inversión: 200000 }]
118
+ lines={['ventas', 'inversión']}
119
+ colors={{ ventas: '#FF2F86', inversión: '#5B01D2' }}
120
+ currency="COP"
121
+ yAxisLabel="Pesos (COP)"
122
+ displayNames={{ ventas: 'Ventas', inversión: 'Inversión en Ads' }}
123
+ />
124
+
125
+ <InvestmentByPlatformChart
126
+ data={[{ name: 'Meta', value: 4500000 }, { name: 'Google', value: 2500000 }]}
127
+ title="Inversión por plataforma"
128
+ currencySymbol="COP"
129
+ locale="es-CO"
100
130
  />
101
131
  ```
102
132
 
103
133
  ---
104
134
 
105
- ### TextButton
135
+ ### Overlay
106
136
 
107
- Botón fantasma sin borde ni fondo. Ideal para acciones secundarias o navegación.
137
+ | Componente | Descripción |
138
+ |---|---|
139
+ | `Modal` | Modal con título, footer y botón de cierre |
140
+ | `CustomTooltip` | Wrapper de Tippy.js, funciona sobre cualquier elemento |
108
141
 
109
142
  ```jsx
110
- <TextButton
111
- title="Ver más"
112
- color="dark"
113
- loading={false}
114
- disabled={false}
115
- icon={cilExternalLink}
116
- onClick={() => {}}
143
+ import { Modal, CustomTooltip, SolidButton } from '@roax/ui'
144
+
145
+ <Modal
146
+ visible={open}
147
+ onClose={() => setOpen(false)}
148
+ title="Confirmar acción"
149
+ footer={<SolidButton title="Confirmar" onClick={() => setOpen(false)} />}
117
150
  >
118
- {/* O pasar children en lugar de title */}
119
- Texto personalizado
120
- </TextButton>
151
+ <p>¿Estás seguro de continuar?</p>
152
+ </Modal>
153
+
154
+ <CustomTooltip content="Más información" placement="top">
155
+ <span>Hover aquí</span>
156
+ </CustomTooltip>
121
157
  ```
122
158
 
123
159
  ---
124
160
 
125
- ### IconButton
161
+ ### Pagination
126
162
 
127
- Botón de ícono con tooltip opcional (usa Tippy.js).
163
+ | Componente | Descripción |
164
+ |---|---|
165
+ | `PaginatedTable` | Tabla con paginación y estado de loading |
166
+ | `PaginatedGrid` | Grid de cards con paginación |
128
167
 
129
168
  ```jsx
130
- <IconButton
131
- icon={cilTrash}
132
- tooltip="Eliminar registro"
133
- color="danger"
134
- loading={false}
135
- disabled={false}
136
- onClick={() => {}}
169
+ import { PaginatedTable } from '@roax/ui'
170
+ import { CTableRow, CTableDataCell } from '@coreui/react-pro'
171
+
172
+ <PaginatedTable
173
+ data={rows}
174
+ columns={['#', 'Nombre', 'Estado']}
175
+ itemsPerPage={10}
176
+ currentPage={page}
177
+ setCurrentPage={setPage}
178
+ renderRow={(row) => (
179
+ <CTableRow key={row.id}>
180
+ <CTableDataCell>{row.id}</CTableDataCell>
181
+ <CTableDataCell>{row.name}</CTableDataCell>
182
+ </CTableRow>
183
+ )}
184
+ emptyMessage="No se encontraron registros."
137
185
  />
138
186
  ```
139
187
 
140
188
  ---
141
189
 
142
- ## Colores disponibles
190
+ ### Skeletons
191
+
192
+ | Componente | Descripción |
193
+ |---|---|
194
+ | `CardSkeleton` | Placeholder de tarjeta |
195
+ | `TextSkeleton` | Placeholder de línea de texto |
196
+ | `MetricsSkeleton` | Placeholder de métrica |
197
+ | `ReportTableSkeleton` | Placeholder de tabla de reporte |
198
+ | `SummaryReportSkeleton` | Grid de placeholders para reportes de resumen |
143
199
 
144
- Los colores base del proyecto que puedes usar en `color` y `textColor`:
200
+ ```jsx
201
+ import { MetricsSkeleton, SummaryReportSkeleton } from '@roax/ui'
145
202
 
146
- | Token | Hex | Uso |
147
- |-------------------|-----------|------------------------------|
148
- | `custom-primary` | Gradiente | Acciones principales ROAX |
149
- | `secondary` | `#9da5b1` | Acciones secundarias |
150
- | `success` | `#2eb85c` | Confirmaciones |
151
- | `danger` | `#e55353` | Eliminaciones / errores |
152
- | `warning` | `#f9b115` | Advertencias |
153
- | `info` | `#39f` | Información |
154
- | `dark` | `#4f5d73` | Acciones neutras |
203
+ {loading ? <MetricsSkeleton /> : <GeneralCard {...props} />}
204
+
205
+ <SummaryReportSkeleton
206
+ layout={[
207
+ { sm: 6, md: 4 },
208
+ { sm: 6, md: 4 },
209
+ { sm: 6, md: 4 },
210
+ ]}
211
+ />
212
+ ```
155
213
 
156
214
  ---
157
215
 
158
- ## Desarrollo local
216
+ ### Feedback
159
217
 
160
- ### Desde el monorepo
218
+ | Componente | Descripción |
219
+ |---|---|
220
+ | `NoDataMessage` | Alerta de advertencia cuando no hay datos disponibles |
161
221
 
162
- ```bash
163
- # Instalar todas las dependencias
164
- npm install
222
+ ```jsx
223
+ import { NoDataMessage } from '@roax/ui'
165
224
 
166
- # Correr Storybook (documentación visual)
167
- npm run storybook
225
+ <NoDataMessage message="No hay ventas para el período seleccionado." />
226
+ ```
168
227
 
169
- # Correr tests
170
- npm run test
228
+ ---
171
229
 
172
- # Build del paquete
173
- npm run ui:build
230
+ ### Navigation
174
231
 
175
- # Watch mode del paquete
176
- npm run ui:dev
177
- ```
232
+ | Componente | Descripción |
233
+ |---|---|
234
+ | `BackButton` | Botón de regreso que usa `next/navigation` |
178
235
 
179
- ### Solo el paquete
236
+ ```jsx
237
+ import { BackButton } from '@roax/ui'
180
238
 
181
- ```bash
182
- cd packages/ui
183
- npm run build # Genera dist/
184
- npm run dev # Watch mode
185
- npm run pack:preview # Ver qué archivos se publicarían
239
+ <BackButton title="Volver al listado" path="/dashboard" />
186
240
  ```
187
241
 
188
242
  ---
189
243
 
190
- ## Publicación en npm
244
+ ## Design Tokens — Colores
191
245
 
192
- ### Configuración del token
246
+ Todas las variables están disponibles como CSS custom properties después de importar `@roax/ui/styles`.
193
247
 
194
- ```bash
195
- # Opción 1: variable de entorno
196
- NPM_TOKEN=npm_xxxx npm publish
248
+ | Escala | Variable principal | Hex |
249
+ |---|---|---|
250
+ | Rosa | `--roax-rosa-400` | `#ED1E78` |
251
+ | Naranja | `--roax-orange-400` | `#F05A24` |
252
+ | Morado | `--roax-purple-400` | `#5B01D2` |
253
+ | Neutral | `--roax-neutral-500` | `#071324` |
254
+ | Success | `--roax-success-400` | `#34C38F` |
255
+ | Warning | `--roax-warning-400` | `#FFCE33` |
256
+ | Error | `--roax-error-400` | `#FF0505` |
257
+ | Info | `--roax-info-400` | `#33A7FF` |
197
258
 
198
- # Opción 2: .npmrc en CI/CD
199
- echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> ~/.npmrc
200
- ```
259
+ Cada escala va de `50` (más claro) a `900` (más oscuro).
201
260
 
202
- ### Publicar manualmente
261
+ ---
203
262
 
204
- ```bash
205
- cd packages/ui
263
+ ## Utilidades
206
264
 
207
- # 1. Build
208
- npm run build
265
+ ```jsx
266
+ import { formatValue, getBadgeStyles, formatDateRange } from '@roax/ui'
209
267
 
210
- # 2. Verificar contenido
211
- npm run pack:preview
268
+ formatValue(15420000, 'COP') // → 'COP 15.420.000'
269
+ formatValue(3.75, '%') // → '3.75%'
270
+ formatValue(4.2, 'x') // → 'x 4.20'
212
271
 
213
- # 3. Publicar
214
- npm publish --access public
215
- ```
272
+ getBadgeStyles(true) // → { backgroundColor: '#55ed7b', color: '#0b3e26', ... }
273
+ getBadgeStyles(false) // → { backgroundColor: '#f74a4a', color: '#842029', ... }
216
274
 
217
- ### GitHub Actions (recomendado)
218
-
219
- Crea `.github/workflows/publish.yml`:
220
-
221
- ```yaml
222
- name: Publish @roax/ui
223
-
224
- on:
225
- push:
226
- tags:
227
- - 'ui-v*'
228
-
229
- jobs:
230
- publish:
231
- runs-on: ubuntu-latest
232
- steps:
233
- - uses: actions/checkout@v4
234
- - uses: actions/setup-node@v4
235
- with:
236
- node-version: '20'
237
- registry-url: 'https://registry.npmjs.org'
238
- - run: npm ci
239
- - run: npm run ui:build
240
- - run: npm publish --workspace=packages/ui --access public
241
- env:
242
- NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
275
+ formatDateRange('2024-03-01 - 2024-03-31')
276
+ // → { formattedRange: 'mar 01,24 - mar 31,24' }
243
277
  ```
244
278
 
245
- Agrega `NPM_TOKEN` como secret en tu repositorio GitHub.
279
+ ---
280
+
281
+ ## Storybook
282
+
283
+ Todos los componentes están documentados en Storybook con variantes interactivas y design tokens de color.
246
284
 
247
285
  ---
248
286
 
249
- ## Estructura del paquete
287
+ ## Licencia
250
288
 
251
- ```
252
- packages/ui/
253
- ├── src/
254
- │ ├── components/
255
- │ │ ├── buttons/
256
- │ │ │ ├── SolidButton.jsx
257
- │ │ │ ├── SolidButton.scss
258
- │ │ │ ├── OutlineButton.jsx
259
- │ │ │ ├── OutlineButton.scss
260
- │ │ │ ├── TextButton.jsx
261
- │ │ │ ├── IconButton.jsx
262
- │ │ │ └── __tests__/
263
- │ │ └── custom-tooltip/
264
- │ │ └── CustomTooltip.jsx
265
- │ ├── styles/
266
- │ │ ├── index.scss
267
- │ │ └── _roax-colors.scss
268
- │ └── index.js
269
- ├── dist/ ← generado por tsup
270
- ├── tsup.config.js
271
- ├── package.json
272
- └── README.md
273
- ```
289
+ MIT © Roax SAS