@ffstack/turnos 0.3.3 → 0.4.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.
- package/README.md +40 -115
- package/bin/turnos.js +3 -1
- package/package.json +3 -4
package/README.md
CHANGED
|
@@ -1,146 +1,71 @@
|
|
|
1
|
-
# turnos
|
|
1
|
+
# @ffstack/turnos
|
|
2
2
|
|
|
3
3
|
Turnero instalable por npm: componentes de React para que un **usuario elija un turno** y un **administrador controle los turnos**, sobre **Firebase (Firestore)** o **Supabase**, con un adaptador **memoria** para demos y tests.
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/turnos)
|
|
5
|
+
[](https://www.npmjs.com/package/@ffstack/turnos)
|
|
6
6
|
[](https://github.com/Fran249/turnos-react)
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
## Instalación rápida (Recomendado)
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Configura todo tu proyecto (componentes, base de datos y dependencias) con un solo comando:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npx @ffstack/turnos init
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Este comando interactivo:
|
|
17
|
+
1. Te preguntará qué base de datos quieres usar (**Firebase**, **Supabase** o **Memoria/Demo**).
|
|
18
|
+
2. Generará los componentes `TurnoPicker` y `TurnoAdmin` en tu carpeta `src/turnos/`.
|
|
19
|
+
3. Instalará automáticamente las dependencias necesarias (`@supabase/supabase-js`, `firebase`, etc.).
|
|
20
|
+
4. Creará un archivo `.env.example` con las variables de entorno requeridas.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Qué genera `turnos` en tu proyecto:
|
|
11
25
|
|
|
12
26
|
| Archivo | Para qué |
|
|
13
27
|
|---|---|
|
|
14
28
|
| `src/turnos/TurnoPicker.jsx` | Componente del usuario: ve los turnos del día y elige uno |
|
|
15
29
|
| `src/turnos/TurnoAdmin.jsx` | Componente del administrador: crea, cambia estado y elimina turnos |
|
|
16
|
-
| `src/turnos/turnos.css` | Estilos autónomos
|
|
17
|
-
| `src/turnos/turnos.config.js` | Config de tu proveedor
|
|
30
|
+
| `src/turnos/turnos.css` | Estilos autónomos: talones con perforación y registro rayado. |
|
|
31
|
+
| `src/turnos/turnos.config.js` | Config de tu proveedor + cliente `turnos` |
|
|
18
32
|
| `firestore.rules` *(firebase)* | Reglas Firestore: lectura pública, escritura de admin |
|
|
19
33
|
| `supabase-migrations/0001_turnos.sql` *(supabase)* | Tabla `public.turnos`, RLS y RPC `book_turno` atómico |
|
|
20
34
|
|
|
21
|
-
## Instalación y configuración
|
|
22
|
-
|
|
23
|
-
npm **no** reenvía flags de CLI (`npm i turnos --firebase` no llega al postinstall). Las formas soportadas:
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
# 1) CLI explícita (recomendada, determinista):
|
|
27
|
-
npm i turnos
|
|
28
|
-
npx turnos init --firebase # o: npx turnos init --supabase
|
|
29
|
-
|
|
30
|
-
# 2) Variable de entorno (el postinstall genera solo con esto):
|
|
31
|
-
TURNOS_PROVIDER=firebase npm i turnos
|
|
32
|
-
TURNOS_PROVIDER=supabase npm i turnos
|
|
33
|
-
|
|
34
|
-
# 3) Instalación simple: no escribe nada; el postinstall muestra la guía
|
|
35
|
-
# (siempre termina en 0, nunca rompe el `npm i`).
|
|
36
|
-
npm i turnos
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
Opciones del CLI: `npx turnos init --firebase|--supabase [--force] [--dir <ruta>]`.
|
|
40
|
-
`--force` sobreescribe archivos ya generados; por defecto los respeta y te los lista.
|
|
41
|
-
|
|
42
|
-
La config generada contiene **solo placeholders** (`TU_API_KEY`, `TU_ORG.supabase.co`, `TU_ANON_KEY`): rellénala con tus credenciales.
|
|
43
|
-
|
|
44
35
|
## Uso
|
|
45
36
|
|
|
46
37
|
```jsx
|
|
47
|
-
// App del usuario
|
|
48
38
|
import { turnos } from './src/turnos/turnos.config'
|
|
49
39
|
import TurnoPicker from './src/turnos/TurnoPicker'
|
|
50
40
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
<TurnoAdmin adapter={turnos} />
|
|
62
|
-
// props: titulo? 'Administrar turnos'
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
El componente solo consume el **contrato del cliente** (mismo API con cualquier proveedor):
|
|
66
|
-
|
|
67
|
-
| Método | Devuelve |
|
|
68
|
-
|---|---|
|
|
69
|
-
| `listTurnos({ date })` | `Promise<Turno[]>` del día (filter por `dayKey`) |
|
|
70
|
-
| `upsertTurno(input)` | `{ ok, turn }` si válido; `{ ok:false, errors[] }` si la validación del merge falla |
|
|
71
|
-
| `removeTurno(id)` | `{ ok, removed }` |
|
|
72
|
-
| `bookTurno(id, user)` | `{ ok, turn }` o `{ ok:false, error: 'lleno' \| 'cancelado' \| 'duplicado' \| 'inexistente' }` |
|
|
73
|
-
| `unbookTurno(id, user)` | `{ ok, turn }` |
|
|
74
|
-
| `subscribe(cb)` | dispara al instante y en cada mutación; devuelve `unsubscribe()` |
|
|
75
|
-
|
|
76
|
-
Turno: `{ id, title, staff, hour: "HH:MM", durationMin (def 30), priority: low|medium|high (def medium), status: pending|confirmed|completed|cancelled, date: "YYYY-MM-DD", notes, capacity (def 1), booked: string[] }`.
|
|
77
|
-
|
|
78
|
-
## Proveedores
|
|
79
|
-
|
|
80
|
-
- **Firebase** — `src/adapters/firebase.js`: consulta por `date` con `where`, streaming con `onSnapshot`, reserva en `runTransaction` (la integridad de capacidad/duplicados la garantiza la transacción; las reglas no pueden expresar `booked.length < capacity`). Deploy: `firebase deploy --only firestore:rules`.
|
|
81
|
-
- **Supabase** — `src/adapters/supabase.js`: tabla `public.turnos` + RPC `book_turno(turno_id, user)` con `for update` (atómico para capacidad), realtime por `.channel()`. Push: `supabase db push` o aplica la migración.
|
|
82
|
-
- **Memoria** — `provider: 'memory'` + `turns` iniciales: para demos, previews y tests.
|
|
83
|
-
|
|
84
|
-
Ejemplo de cliente con memoria:
|
|
85
|
-
|
|
86
|
-
```js
|
|
87
|
-
import { createClient } from 'turnos'
|
|
88
|
-
const turnos = createClient({
|
|
89
|
-
provider: 'memory',
|
|
90
|
-
turns: [{ title: 'Mañana', staff: 'Equipo A', hour: '09:00', date: '2026-11-11', status: 'confirmed' }],
|
|
91
|
-
})
|
|
41
|
+
function App() {
|
|
42
|
+
return (
|
|
43
|
+
<TurnoPicker
|
|
44
|
+
adapter={turnos}
|
|
45
|
+
user="id-del-usuario"
|
|
46
|
+
onBooked={(turn) => console.log('Turno reservado:', turn)}
|
|
47
|
+
/>
|
|
48
|
+
)
|
|
49
|
+
}
|
|
92
50
|
```
|
|
93
51
|
|
|
94
|
-
|
|
52
|
+
## Adaptadores y Proveedores
|
|
95
53
|
|
|
96
|
-
|
|
54
|
+
- **Firebase**: Usa Firestore con transacciones para asegurar la capacidad de los turnos.
|
|
55
|
+
- **Supabase**: Usa Postgres con Row Level Security y funciones RPC atómicas.
|
|
56
|
+
- **Memoria (Demo)**: Ideal para prototipos. Permite visualizar el turnero sin base de datos, bloqueando las reservas hasta que se configure un proveedor real.
|
|
97
57
|
|
|
98
|
-
|
|
58
|
+
## Personalización (CSS)
|
|
99
59
|
|
|
100
|
-
|
|
60
|
+
El componente hereda la fuente y colores de tu app por defecto. Puedes personalizarlo sobreescribiendo estos tokens:
|
|
101
61
|
|
|
102
62
|
```css
|
|
103
63
|
.turnos {
|
|
104
|
-
--turnos-
|
|
105
|
-
--turnos-
|
|
106
|
-
--turnos-
|
|
107
|
-
--turnos-
|
|
108
|
-
--turnos-field: #faf7f1; /* inputs del admin */
|
|
109
|
-
--turnos-ink: #221a12; /* texto y bordes fuertes */
|
|
110
|
-
--turnos-soft: #6b6257; /* texto secundario */
|
|
111
|
-
--turnos-line: #e6ded2; /* líneas y bordes */
|
|
112
|
-
--turnos-accent: #3f5a2f; /* foco y avisos OK */
|
|
113
|
-
--turnos-danger: #9c3b2e; /* errores y "Eliminar" */
|
|
114
|
-
--turnos-primary-bg: #221a12; /* botón primario */
|
|
115
|
-
--turnos-primary-ink: #faf7f1;
|
|
116
|
-
--turnos-primary-bg-hover: #3a2c1f;
|
|
64
|
+
--turnos-bg: #faf7f1;
|
|
65
|
+
--turnos-primary-bg: #221a12;
|
|
66
|
+
--turnos-accent: #3f5a2f;
|
|
67
|
+
--turnos-radius: 12px;
|
|
117
68
|
}
|
|
118
69
|
```
|
|
119
70
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
Qué **no** es un token, a propósito: los tamaños de texto, el espaciado y la estructura (talón, registro, rejilla del formulario). Eso es el componente y no debería cambiar con el tema. No hay `prefers-color-scheme` forzado: si tu app tiene modo oscuro, remapeá los mismos tokens.
|
|
123
|
-
|
|
124
|
-
> La perforación del talón se dibuja con `--turnos-bg`. Si dejás la tarjeta transparente, poné ahí el fondo real de la página para que las muescas se vean.
|
|
125
|
-
|
|
126
|
-
## Rutas de la demo
|
|
127
|
-
|
|
128
|
-
El repo incluye una demo Vite (`npm run dev`) con **dos superficies, una por rol**. No se publica en el paquete.
|
|
129
|
-
|
|
130
|
-
| Ruta | Superficie |
|
|
131
|
-
|---|---|
|
|
132
|
-
| `/` y `/user` | **Usuario**: agenda del día + `TurnoPicker` para reservar. El calendario del mes es el índice; la tira semanal y el calendario mueven el día. Sin crear, sin estadísticas, sin eliminar |
|
|
133
|
-
| `/admin` | **Administrador**: `TurnoAdmin` para crear, cambiar estado y eliminar, más el resumen por estado y `StatsView` |
|
|
134
|
-
|
|
135
|
-
Las dos superficies comparten un solo cliente, `src/localClient.js`, que implementa el contrato del paquete sobre el store de `localStorage`. Una reserva hecha en `/user` actualiza el calendario y aparece en el registro de `/admin` sin recargar; un turno creado en `/admin` aparece en la agenda del usuario. Vite sirve `index.html` para rutas desconocidas (`appType: 'spa'`), así que las URLs funcionan también al abrirlas directamente.
|
|
136
|
-
|
|
137
|
-
`TurnoPicker` acepta `date` (fecha inicial), `onDateChange` y `showDateNav` (por defecto `true`). Cuando el anfitrión controla la fecha —como esta demo, que usa la tira semanal y el calendario— pasa `showDateNav={false}` y una `key={date}` para remontar el componente en el día nuevo.
|
|
138
|
-
|
|
139
|
-
## Desarrollo
|
|
140
|
-
|
|
141
|
-
```bash
|
|
142
|
-
npm test # vitest (unidades + componentes + generator + postinstall)
|
|
143
|
-
npm run test:coverage # cobertura v8 (src/**, objetivo ≥ 80 %)
|
|
144
|
-
npm run lint # oxlint
|
|
145
|
-
npm run build # vite build
|
|
146
|
-
```
|
|
71
|
+
Licencia MIT. Hecho por [@ffstack](https://github.com/Fran249).
|
package/bin/turnos.js
CHANGED
|
@@ -111,7 +111,9 @@ program
|
|
|
111
111
|
});
|
|
112
112
|
|
|
113
113
|
// Automatizar instalación de dependencias
|
|
114
|
-
const deps = provider === 'supabase' ? ['@supabase/supabase-js'] : ['firebase'];
|
|
114
|
+
const deps = provider === 'supabase' ? ['@supabase/supabase-js'] : provider === 'firebase' ? ['firebase'] : [];
|
|
115
|
+
// Siempre asegurar que el propio paquete esté instalado en el proyecto local
|
|
116
|
+
deps.push('@ffstack/turnos');
|
|
115
117
|
installDependencies(deps);
|
|
116
118
|
|
|
117
119
|
// Generar .env.example
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ffstack/turnos",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
7
|
-
"description": "Turnero npm: componentes usuario/admin de turnos sobre Firebase (Firestore) o Supabase, generados al instalar (npx turnos init
|
|
7
|
+
"description": "Turnero npm: componentes usuario/admin de turnos sobre Firebase (Firestore) o Supabase, generados al instalar (npx @ffstack/turnos init).",
|
|
8
8
|
"type": "module",
|
|
9
9
|
"license": "MIT",
|
|
10
10
|
"main": "src/core/index.js",
|
|
@@ -41,8 +41,7 @@
|
|
|
41
41
|
"preview": "vite preview",
|
|
42
42
|
"test": "vitest run",
|
|
43
43
|
"test:watch": "vitest",
|
|
44
|
-
"test:coverage": "vitest run --coverage"
|
|
45
|
-
"postinstall": "node bin/turnos.js postinstall"
|
|
44
|
+
"test:coverage": "vitest run --coverage"
|
|
46
45
|
},
|
|
47
46
|
"peerDependencies": {
|
|
48
47
|
"react": "^18.0.0 || ^19.0.0",
|