@roax/ui 0.2.0 → 0.3.1

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 +192 -170
  2. package/dist/index.js +435 -250
  3. package/dist/index.js.map +1 -1
  4. package/dist/index.mjs +466 -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,283 @@ 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
69
+ ### Cards
55
70
 
56
- ### SolidButton
57
-
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 — solo el gráfico, sin cards
109
+ <FunnelChart
110
+ data={[
111
+ { label: 'Impressions', value: 120000 },
112
+ { label: 'Clicks', value: 8400 },
113
+ { label: 'Purchases', value: 630, unit: 'COP', color: '#5B01D2' },
114
+ ]}
115
+ gradientStart="#FF8AAE"
116
+ gradientEnd="#FF1F3D"
117
+ />
118
+
119
+ // TimeSeriesComparisonChart — genérico, cualquier clave de datos
120
+ <TimeSeriesComparisonChart
121
+ data={[{ date: '2024-05-01', sales: 800000, adSpend: 200000 }]}
122
+ lines={['sales', 'adSpend']}
123
+ colors={{ sales: '#FF2F86', adSpend: '#5B01D2' }}
124
+ currency="COP"
125
+ yAxisLabel="COP"
126
+ displayNames={{ sales: 'Sales', adSpend: 'Ad Spend' }}
127
+ xDataKey="date"
128
+ height={340}
129
+ />
130
+
131
+ <InvestmentByPlatformChart
132
+ data={[{ name: 'Meta', value: 4500000 }, { name: 'Google', value: 2500000 }]}
133
+ title="Investment by Platform"
134
+ currencySymbol="USD"
135
+ locale="en-US"
100
136
  />
101
137
  ```
102
138
 
103
139
  ---
104
140
 
105
- ### TextButton
141
+ ### Overlay
106
142
 
107
- Botón fantasma sin borde ni fondo. Ideal para acciones secundarias o navegación.
143
+ | Componente | Descripción |
144
+ |---|---|
145
+ | `Modal` | Modal con título, footer y botón de cierre |
146
+ | `CustomTooltip` | Wrapper de Tippy.js, funciona sobre cualquier elemento |
108
147
 
109
148
  ```jsx
110
- <TextButton
111
- title="Ver más"
112
- color="dark"
113
- loading={false}
114
- disabled={false}
115
- icon={cilExternalLink}
116
- onClick={() => {}}
149
+ import { Modal, CustomTooltip, SolidButton } from '@roax/ui'
150
+
151
+ <Modal
152
+ visible={open}
153
+ onClose={() => setOpen(false)}
154
+ title="Confirmar acción"
155
+ footer={<SolidButton title="Confirmar" onClick={() => setOpen(false)} />}
117
156
  >
118
- {/* O pasar children en lugar de title */}
119
- Texto personalizado
120
- </TextButton>
157
+ <p>¿Estás seguro de continuar?</p>
158
+ </Modal>
159
+
160
+ <CustomTooltip content="Más información" placement="top">
161
+ <span>Hover aquí</span>
162
+ </CustomTooltip>
121
163
  ```
122
164
 
123
165
  ---
124
166
 
125
- ### IconButton
167
+ ### Pagination
126
168
 
127
- Botón de ícono con tooltip opcional (usa Tippy.js).
169
+ | Componente | Descripción |
170
+ |---|---|
171
+ | `PaginatedTable` | Tabla con paginación y estado de loading |
172
+ | `PaginatedGrid` | Grid de cards con paginación |
128
173
 
129
174
  ```jsx
130
- <IconButton
131
- icon={cilTrash}
132
- tooltip="Eliminar registro"
133
- color="danger"
134
- loading={false}
135
- disabled={false}
136
- onClick={() => {}}
175
+ import { PaginatedTable } from '@roax/ui'
176
+ import { CTableRow, CTableDataCell } from '@coreui/react-pro'
177
+
178
+ <PaginatedTable
179
+ data={rows}
180
+ columns={['#', 'Nombre', 'Estado']}
181
+ itemsPerPage={10}
182
+ currentPage={page}
183
+ setCurrentPage={setPage}
184
+ renderRow={(row) => (
185
+ <CTableRow key={row.id}>
186
+ <CTableDataCell>{row.id}</CTableDataCell>
187
+ <CTableDataCell>{row.name}</CTableDataCell>
188
+ </CTableRow>
189
+ )}
190
+ emptyMessage="No se encontraron registros."
137
191
  />
138
192
  ```
139
193
 
140
194
  ---
141
195
 
142
- ## Colores disponibles
196
+ ### Skeletons
143
197
 
144
- Los colores base del proyecto que puedes usar en `color` y `textColor`:
198
+ | Componente | Descripción |
199
+ |---|---|
200
+ | `CardSkeleton` | Placeholder de tarjeta |
201
+ | `TextSkeleton` | Placeholder de línea de texto |
202
+ | `MetricsSkeleton` | Placeholder de métrica |
203
+ | `ReportTableSkeleton` | Placeholder de tabla de reporte |
204
+ | `SummaryReportSkeleton` | Grid de placeholders para reportes de resumen |
145
205
 
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 |
206
+ ```jsx
207
+ import { MetricsSkeleton, SummaryReportSkeleton } from '@roax/ui'
208
+
209
+ {loading ? <MetricsSkeleton /> : <GeneralCard {...props} />}
210
+
211
+ <SummaryReportSkeleton
212
+ layout={[
213
+ { sm: 6, md: 4 },
214
+ { sm: 6, md: 4 },
215
+ { sm: 6, md: 4 },
216
+ ]}
217
+ />
218
+ ```
155
219
 
156
220
  ---
157
221
 
158
- ## Desarrollo local
222
+ ### Feedback
159
223
 
160
- ### Desde el monorepo
224
+ | Componente | Descripción |
225
+ |---|---|
226
+ | `NoDataMessage` | Alerta de advertencia cuando no hay datos disponibles |
161
227
 
162
- ```bash
163
- # Instalar todas las dependencias
164
- npm install
228
+ ```jsx
229
+ import { NoDataMessage } from '@roax/ui'
165
230
 
166
- # Correr Storybook (documentación visual)
167
- npm run storybook
231
+ <NoDataMessage message="No hay ventas para el período seleccionado." />
232
+ ```
168
233
 
169
- # Correr tests
170
- npm run test
234
+ ---
171
235
 
172
- # Build del paquete
173
- npm run ui:build
236
+ ### Navigation
174
237
 
175
- # Watch mode del paquete
176
- npm run ui:dev
177
- ```
238
+ | Componente | Descripción |
239
+ |---|---|
240
+ | `BackButton` | Botón de regreso que usa `next/navigation` |
178
241
 
179
- ### Solo el paquete
242
+ ```jsx
243
+ import { BackButton } from '@roax/ui'
180
244
 
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
245
+ <BackButton title="Volver al listado" path="/dashboard" />
186
246
  ```
187
247
 
188
248
  ---
189
249
 
190
- ## Publicación en npm
250
+ ## Design Tokens — Colores
191
251
 
192
- ### Configuración del token
252
+ Todas las variables están disponibles como CSS custom properties después de importar `@roax/ui/styles`.
193
253
 
194
- ```bash
195
- # Opción 1: variable de entorno
196
- NPM_TOKEN=npm_xxxx npm publish
254
+ | Escala | Variable principal | Hex |
255
+ |---|---|---|
256
+ | Rosa | `--roax-rosa-400` | `#ED1E78` |
257
+ | Naranja | `--roax-orange-400` | `#F05A24` |
258
+ | Morado | `--roax-purple-400` | `#5B01D2` |
259
+ | Neutral | `--roax-neutral-500` | `#071324` |
260
+ | Success | `--roax-success-400` | `#34C38F` |
261
+ | Warning | `--roax-warning-400` | `#FFCE33` |
262
+ | Error | `--roax-error-400` | `#FF0505` |
263
+ | Info | `--roax-info-400` | `#33A7FF` |
197
264
 
198
- # Opción 2: .npmrc en CI/CD
199
- echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> ~/.npmrc
200
- ```
265
+ Cada escala va de `50` (más claro) a `900` (más oscuro).
201
266
 
202
- ### Publicar manualmente
267
+ ---
203
268
 
204
- ```bash
205
- cd packages/ui
269
+ ## Utilidades
206
270
 
207
- # 1. Build
208
- npm run build
271
+ ```jsx
272
+ import { formatValue, getBadgeStyles, formatDateRange } from '@roax/ui'
209
273
 
210
- # 2. Verificar contenido
211
- npm run pack:preview
274
+ formatValue(15420000, 'COP') // → 'COP 15.420.000'
275
+ formatValue(3.75, '%') // → '3.75%'
276
+ formatValue(4.2, 'x') // → 'x 4.20'
212
277
 
213
- # 3. Publicar
214
- npm publish --access public
215
- ```
278
+ getBadgeStyles(true) // → { backgroundColor: '#55ed7b', color: '#0b3e26', ... }
279
+ getBadgeStyles(false) // → { backgroundColor: '#f74a4a', color: '#842029', ... }
216
280
 
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 }}
281
+ formatDateRange('2024-03-01 - 2024-03-31')
282
+ // → { formattedRange: 'mar 01,24 - mar 31,24' }
243
283
  ```
244
284
 
245
- Agrega `NPM_TOKEN` como secret en tu repositorio GitHub.
285
+ ---
286
+
287
+ ## Storybook
288
+
289
+ Todos los componentes están documentados en Storybook con variantes interactivas y design tokens de color.
246
290
 
247
291
  ---
248
292
 
249
- ## Estructura del paquete
293
+ ## Licencia
250
294
 
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
- ```
295
+ MIT © Roax SAS