@seatsyoo/angular 0.0.0-stage → 1.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tikyoo, S.L.
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.
package/README.md CHANGED
@@ -1,3 +1,352 @@
1
- # Temporary Holding Version
1
+ # @seatsyoo/angular
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ El visor de mapas de asientos de **Seatsyoo** como componente de Angular: el comprador ve el plano del recinto,
4
+ elige sus butacas (quedan retenidas a su nombre mientras paga) y ve en tiempo real lo que otros compran. Es el
5
+ visor de [`@seatsyoo/visor`](https://www.npmjs.com/package/@seatsyoo/visor) envuelto en un componente standalone,
6
+ `<seatsyoo-chart>`, con entradas, salidas y tipos de TypeScript.
7
+
8
+ *(English summary below.)*
9
+
10
+ ## Instalación
11
+
12
+ ```sh
13
+ npm install @seatsyoo/angular
14
+ # o: pnpm add @seatsyoo/angular · yarn add @seatsyoo/angular
15
+ ```
16
+
17
+ Funciona con Angular 17 o posterior, con zone.js o sin él (zoneless), y con renderizado en el servidor (SSR).
18
+ Con él se instala `@seatsyoo/visor`, su única dependencia.
19
+
20
+ ## Uso
21
+
22
+ ```ts
23
+ import { Component, signal } from "@angular/core";
24
+ import { SeatsyooChartComponent, type SelectedObject } from "@seatsyoo/angular";
25
+
26
+ @Component({
27
+ selector: "app-entradas",
28
+ standalone: true, // hace falta hasta Angular 18; desde la 19 es lo normal
29
+ imports: [SeatsyooChartComponent],
30
+ template: `
31
+ <!-- El visor ocupa todo el elemento: dale altura. -->
32
+ <seatsyoo-chart
33
+ style="height: 640px"
34
+ server="https://seatsyoo.example"
35
+ publicKey="pk_tu_clave_publica"
36
+ [event]="evento()"
37
+ (selectionChange)="seleccion.set($event)"
38
+ (holdExpired)="avisar('Se ha acabado el tiempo: vuelve a elegir.')"
39
+ (chartError)="avisar($event.message)"
40
+ />
41
+ <p>{{ seleccion().length }} butacas elegidas</p>
42
+ `,
43
+ })
44
+ export class EntradasComponent {
45
+ evento = signal("hamlet-2026-11-20");
46
+ seleccion = signal<SelectedObject[]>([]);
47
+ avisar(texto: string) {
48
+ alert(texto);
49
+ }
50
+ }
51
+ ```
52
+
53
+ En una aplicación con módulos (`NgModule`), añade `SeatsyooChartComponent` a los `imports` del módulo.
54
+
55
+ Al pagar, manda a tu servidor solo el evento y el token de retención, nunca la lista de lo elegido: tu servidor
56
+ pregunta a Seatsyoo qué retiene ese token, cobra eso y, con el pago confirmado, lo reserva (ver «Vender»). El token y
57
+ los métodos del visor están en la propiedad `chart` del componente:
58
+
59
+ ```ts
60
+ import { viewChild } from "@angular/core";
61
+
62
+ grafico = viewChild.required(SeatsyooChartComponent); // desde Angular 17.2; antes, @ViewChild
63
+
64
+ pagar() {
65
+ const visor = this.grafico().chart; // SeatingChart, o null si aún no está montado
66
+ if (!visor) return;
67
+ const caja = { evento: this.evento(), holdToken: visor.holdToken }; // nada más
68
+ // fetch("/caja", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(caja) })
69
+ }
70
+ ```
71
+
72
+ ### Entradas
73
+
74
+ Las mismas opciones que `render()` de `@seatsyoo/visor`, salvo `container` (es el propio elemento) y los avisos
75
+ (son salidas). Hacen falta `server` y qué enseñar: `event`, `season` (abonos), `link` (el enlace público de un plano,
76
+ solo para ver) o `document` (un plano ya cargado, solo para ver). Con `event` o `season`, también `publicKey`.
77
+
78
+ | Entrada | Qué hace |
79
+ | --- | --- |
80
+ | `server` | La dirección de Seatsyoo de tu cuenta (obligatoria). |
81
+ | `publicKey` | La clave pública de tu espacio. |
82
+ | `event` · `season` · `seasonEvents` · `link` · `document` | Qué se enseña. |
83
+ | `language` | `"es"` (por defecto) o `"en"`. |
84
+ | `maxSelected` | Plazas que se pueden elegir como mucho (10 por defecto; una mesa o un palco enteros cuentan 1). El servidor tiene sus propios topes, y ahí una mesa o un palco enteros cuentan todas sus plazas: ver «Topes de retención». |
85
+ | `pricing` · `currency` · `locale` | Los precios que pone tu web, por clave de categoría (`{ platea: 30 }`), su moneda y su formato. El visor los enseña en la ficha de cada butaca, en la leyenda y en el total, y salen en `price` de lo elegido: lo que cuesta cada unidad de `quantity` (por plaza; una mesa entera, con todas sus sillas), así que `price × quantity` es lo que suma el total del visor. Sin `pricing`, no hay precios (`price` es `null`). Seatsyoo no guarda precios: lo que se cobra lo calcula tu servidor. |
86
+ | `channels` | Canales de venta desde los que se compra. |
87
+ | `holdToken` | Un token de retención creado por tu servidor, en lugar de que el visor cree uno. |
88
+ | `session` | `"continue"` (por defecto) recupera la selección al recargar; `"start"` empieza de cero. |
89
+ | `mode` · `showLegend` · `showSelectionBar` · `floor` · `sectors` · `view3d` · `entrance` · `texts` | Cómo se ve y se usa el plano. |
90
+ | `theme` | `"light"` (por defecto), `"dark"` o `"auto"`. |
91
+ | `colorBy` | `"category"` (por defecto) o `"channel"`. |
92
+ | `statusStyles` · `marks` | Solo con `mode="manager"` (un panel de gestión): nombre, color e icono de cada estado (`StatusStyle`, que no es el formato de la API: ver «Estados propios y marcas»), y marcas sobre plazas que siguen libres, objeto → estado. |
93
+ | `load3d` | Cómo cargar la vista 3D (por defecto se pide al servidor). |
94
+
95
+ **Cuándo se vuelve a montar el visor.** Si cambia cualquier entrada salvo `theme`, `colorBy`, `statusStyles`, `marks`
96
+ y `load3d`, el visor se desmonta y se monta de nuevo con los valores nuevos (lo ya retenido sigue retenido: con
97
+ `session: "continue"`, el visor nuevo lo recupera). Las listas y los objetos (`pricing`, `channels`, `seasonEvents`,
98
+ `texts`, `document`) se comparan por valor: pasar otro objeto con lo mismo no vuelve a montar nada. `theme` y
99
+ `colorBy` se aplican al momento sin volver a montar, y `statusStyles` y `marks` también (`setStatusStyles`,
100
+ `setMarks`), solo si cambia su valor: se comparan como datos (da igual el prototipo, y una clave que vale `undefined`
101
+ es como si no estuviera), así que otro objeto con lo mismo no hace nada. Como con cualquier entrada de Angular, pasa
102
+ un objeto nuevo (cambiar el que ya pasaste, en el sitio, no llega al componente). De `load3d` se usa siempre la última
103
+ función (solo vuelve a montar si se pone o se quita).
104
+ Al volver a montarlo, el visor nuevo avisa otra vez al cargar: `selectionChange` con lo que tenga (nada, si es otro
105
+ evento) y `holdTokenChange` con su token o, si no tiene y el anterior sí, con `null`. Así lo que guardes de esas
106
+ salidas no se queda con lo del evento anterior.
107
+
108
+ Si vuelves a pasar al componente el token que te da `holdTokenChange` como `[holdToken]`, el visor se volverá a
109
+ montar cada vez que cambie: `holdToken` es para un token que crea tu servidor.
110
+
111
+ ### Salidas
112
+
113
+ Con nombres que no chocan con los eventos del DOM:
114
+
115
+ | Salida | Cuándo | Valor |
116
+ | --- | --- | --- |
117
+ | `ready` | El plano está pintado y los estados cargados. | `SeatingChart` |
118
+ | `selectionChange` | Cambia la selección. | `SelectedObject[]` |
119
+ | `objectSelect` · `objectDeselect` | Se elige o se quita un objeto. | `SelectedObject` |
120
+ | `holdExpired` | Se ha acabado el tiempo de la retención. | — |
121
+ | `holdTokenChange` | Cambia el token de retención (o deja de haberlo; también al volver a montar el visor, ver arriba). | `{ token, expiresAt } \| null` |
122
+ | `floorChange` | Se cambia de planta. | `{ id, name }` |
123
+ | `chartError` | Algo ha fallado (`invalid-options` si faltan opciones) o se ha llegado a un tope de retención (`hold-limit`, `hold-limit-ip`, `hold-rate-limited`: no es que el plano no cargue). Si nadie la escucha, sale en la consola. | `{ code, message }` |
124
+
125
+ ### `chart`
126
+
127
+ La instancia del visor (`SeatingChart`) o `null` (en el servidor, antes de montarlo o si las opciones no valen).
128
+ Métodos: `getSelection()`, `holdToken`, `holdExpiresAt`, `refreshHoldToken()`, `clearSelection()`,
129
+ `selectBestAvailable(n, categorías?)`, `statusOf(clave)`, `floors`, `setFloor(id)`, `show3d(clave?)`,
130
+ `zoomToFit()` y `refresh()`. No llames a `destroy()`: lo hace el componente al destruirse. Para cambiar el tema, el
131
+ color, los estilos o las marcas, usa sus entradas (no `setTheme`, `setStatusStyles`… directamente): el componente
132
+ compara con lo que aplicó él.
133
+
134
+ ### Vender
135
+
136
+ A tu servidor la página le manda el evento y el `holdToken`, nada más: nunca la lista de lo elegido. En la caja, tu
137
+ servidor pregunta a Seatsyoo qué retiene ese token (`GET /api/v1/events/{evento}/statuses?holdToken=…`: lo suyo lleva
138
+ `mine: true` y, en una zona de pie, `mq` con las plazas del token; `mq` solo viene si en la zona hay más de una plaza
139
+ ocupada, contando las de otros compradores, y si no viene es 1), calcula el importe con sus precios (precio × plazas:
140
+ una mesa entera cuenta todas sus sillas, como el total del visor) y guarda esa lista con el pedido, cada objeto con su
141
+ cantidad (`{ key, quantity: mq ?? 1 }`). Con el pago confirmado, reserva exactamente lo guardado
142
+ (`POST /api/v1/events/{evento}/actions/book` con `holdToken` y tu número de pedido, `orderId`), sin volver a preguntar.
143
+
144
+ No reserves una lista que mande la página: `book` reserva también objetos libres, así que cualquiera podría añadirle
145
+ butacas que no ha retenido, y saltarse los topes de retención. Es lo que hace la tienda de ejemplo de `@seatsyoo/node`
146
+ (`ejemplo/tienda.ts`: `POST /caja` con `{ evento, holdToken }` y `POST /pagar` con `{ holdToken }`) y lo que cuenta la
147
+ guía de integración de la documentación (**/docs/integracion**).
148
+
149
+ ### Topes de retención
150
+
151
+ Lo que el comprador retiene desde el visor tiene topes en el servidor. Al pasar uno, la butaca no se retiene y llega
152
+ el error a `chartError`:
153
+
154
+ | Código | Qué tope |
155
+ | --- | --- |
156
+ | `hold-limit` (409) | Las «Plazas por comprador» de tu espacio (`maxHoldPerToken`, 10 si no se cambia; lo da `GET /workspace`), por token y evento. Una mesa o un palco que se venden enteros cuentan todas sus plazas. |
157
+ | `hold-limit-ip` (409) | Lo retenido a la vez desde una misma conexión (IP) en un evento, sumando todas sus compras en curso: el 10 % del aforo, hasta 200, y nunca menos que `maxHoldPerToken`. |
158
+ | `hold-rate-limited` (429) | Lo que retiene una misma IP en poco tiempo: como mucho 600 plazas cada 10 minutos (soltar no cuenta). |
159
+
160
+ - `maxSelected` cuenta una mesa o un palco enteros como 1, y el servidor, con todas sus plazas: con
161
+ `maxSelected` y `maxHoldPerToken` en 10, dos mesas de 8 dan `hold-limit`. No pongas `maxSelected` por encima de
162
+ `maxHoldPerToken` y, si vendes mesas o palcos enteros, cuenta con ese error o sube el ajuste.
163
+ - `selectBestAvailable(n)` pide de 1 a 100 plazas, y nunca más que `maxHoldPerToken` (si no, `hold-limit` antes de
164
+ buscar).
165
+ - Un `holdToken` que crea tu servidor con la clave secreta (`POST /api/v1/hold-tokens`) no lleva IP: no cuenta para
166
+ `hold-limit-ip`. Lo que el comprador retiene con él desde el visor sí cuenta para `hold-limit` y `hold-rate-limited`.
167
+ - Lo que hace tu servidor con la clave secreta (retener, reservar) no tiene ninguno de estos topes.
168
+
169
+ Distingue el código en `chartError`: con un tope, el comprador no tiene que leer que el plano no ha cargado.
170
+
171
+ ### Estados propios y marcas (modo «manager»)
172
+
173
+ En un panel de gestión (modo `"manager"`), `statusStyles` dice cómo se ve cada estado y `marks`, qué plazas libres
174
+ llevan una marca. Se sacan de la API con la clave secreta, así que los pide tu servidor y se los da a la página:
175
+
176
+ - `marks` es tal cual el `marks` de `GET /api/v1/events/{evento}/marks` (`{ "marks": { "Platea-A-1":
177
+ "visibilidad-reducida" } }`): objeto → clave del estado.
178
+ - `statusStyles` sale del catálogo de `GET /api/v1/statuses` (`{ statuses, system }`; con `?event={evento}`, solo los
179
+ que valen para ese evento), pero no es el mismo formato: por la clave de cada estado, `{ name, color, icon }`, y el
180
+ icono cambia de forma. `{ type: "text", text }` pasa a `{ text }` y `{ type: "image", src }`, a `{ image: src }`;
181
+ `{ type: "preset", name }` es de la colección del panel, que no se publica: sin icono, o con un trazado tuyo de 24×24
182
+ (`{ path }`). De `system` (los estados de base que tu espacio ha cambiado), solo los que traen `color`, y nunca
183
+ `free`. Un estado de base con `color: null` no pasa, así que el visor lo pinta como siempre y también pierde el
184
+ nombre y el icono propios que le hayas puesto, aunque el panel sí los enseñe (en el modo «manager», «Reservado» en
185
+ vez de tu «Vendida»). Si los quieres, ponle color propio en el panel. Pasar el catálogo tal cual no compila en
186
+ TypeScript y, en JavaScript, rompe el pintado.
187
+
188
+ ```ts
189
+ import type { StatusStyle } from "@seatsyoo/angular";
190
+
191
+ /** Un icono del catálogo de estados (GET /api/v1/statuses). */
192
+ type IconoDeEstado = { type: "preset"; name: string } | { type: "text"; text: string } | { type: "image"; src: string };
193
+ /** Lo que responde GET /api/v1/statuses (lo que hace falta aquí). */
194
+ interface Catalogo {
195
+ statuses: { key: string; name: string; color: string; icon: IconoDeEstado | null }[];
196
+ system: { key: string; name: string | null; color: string | null; icon: IconoDeEstado | null }[];
197
+ }
198
+
199
+ function estilo(name: string | null, color: string, icon: IconoDeEstado | null): StatusStyle {
200
+ // «preset»: sin icono (o tu trazado de 24×24, { path: "M4 12h16" }).
201
+ const forma = icon?.type === "text" ? { text: icon.text } : icon?.type === "image" ? { image: icon.src } : null;
202
+ return { ...(name ? { name } : {}), color, ...(forma ? { icon: forma } : {}) };
203
+ }
204
+
205
+ /** De GET /api/v1/statuses a la opción statusStyles. */
206
+ export function estilosDeEstados({ statuses, system }: Catalogo): Record<string, StatusStyle> {
207
+ const estilos: Record<string, StatusStyle> = {};
208
+ for (const s of statuses) estilos[s.key] = estilo(s.name, s.color, s.icon);
209
+ // De los de base, solo los que tienen color propio: sin él se quedan como los pinta el visor, también con su nombre
210
+ // y su icono de siempre (los tuyos se pierden). «free» no se pinta con estilo.
211
+ for (const s of system) if (s.key !== "free" && s.color) estilos[s.key] = estilo(s.name, s.color, s.icon);
212
+ return estilos;
213
+ }
214
+ ```
215
+
216
+ Después, `<seatsyoo-chart mode="manager" … [statusStyles]="estilos" [marks]="marcas" />`, con `estilos =
217
+ estilosDeEstados(catalogo)` y las marcas tal cual; para cambiarlos, pasa objetos nuevos.
218
+
219
+ ### Zonas, zoneless y SSR
220
+
221
+ - El visor corre **fuera de la zona de Angular**: su cuenta atrás, sus peticiones y su tiempo real no lanzan la
222
+ detección de cambios. Las salidas se emiten **dentro**, así que tu plantilla se actualiza sola.
223
+ - Sin zone.js (zoneless, lo normal desde Angular 21) funciona igual: las salidas marcan la vista del padre.
224
+ - En el servidor (SSR) el elemento sale vacío y el visor no se crea ni pide nada; se monta en el navegador. El
225
+ elemento lleva `ngSkipHydration`: la hidratación no compara el DOM que añade el visor.
226
+
227
+ ## El diseñador de planos
228
+
229
+ `<seatsyoo-designer>` (`SeatsyooDesignerComponent`, standalone) abre en tu web el diseñador de planos de Seatsyoo,
230
+ para que tus clientes dibujen sus recintos. Tu servidor abre una sesión para un plano con su clave secreta
231
+ (`POST /api/v1/charts/{plano}/designer-sessions`, o `charts.designerSession` de `@seatsyoo/node`) y le da el token a tu
232
+ web:
233
+
234
+ ```ts
235
+ import { Component, input, output } from "@angular/core";
236
+ import { SeatsyooDesignerComponent } from "@seatsyoo/angular";
237
+
238
+ @Component({
239
+ selector: "app-disenador",
240
+ standalone: true,
241
+ imports: [SeatsyooDesignerComponent],
242
+ template: `
243
+ <seatsyoo-designer
244
+ style="display: block; height: 80vh"
245
+ server="https://seatsyoo.example"
246
+ [token]="token()"
247
+ [refreshToken]="pedirToken"
248
+ (publish)="publicado($event.version)"
249
+ (designerClose)="cerrar.emit()"
250
+ />
251
+ `,
252
+ })
253
+ export class DisenadorComponent {
254
+ readonly token = input.required<string>();
255
+ readonly cerrar = output<void>();
256
+ // Tu servidor abre otra sesión del mismo plano y te da el token (aquí, una ruta tuya).
257
+ readonly pedirToken = (): Promise<string> =>
258
+ fetch("/mi-api/disenador/teatro", { method: "POST" }).then((r) => r.json()).then((s: { token: string }) => s.token);
259
+ publicado(version: number): void {
260
+ console.log("Publicada la versión", version);
261
+ }
262
+ }
263
+ ```
264
+
265
+ Entradas: `server`, `token`, `language` y `refreshToken` (pide a tu servidor otro token del mismo plano antes de que
266
+ caduque: sin ella, al caducar deja de guardar). Salidas: `ready`, `save`, `publish`, `designerClose` («←» sale si hay
267
+ quien la escuche al montarse) y `designerError`. El elemento necesita alto. Un `token` nuevo se le manda sin volver a
268
+ montarlo; cambiar `server` o `language`, o pasar o quitar `refreshToken`, lo vuelve a montar. `designer` es el diseñador
269
+ abierto (`setToken()`, `iframe`). Solo se monta en el navegador (en SSR el elemento queda vacío) y corre fuera de la zona
270
+ de Angular; las salidas se emiten dentro.
271
+
272
+ ## Desarrollo
273
+
274
+ En el repositorio de los SDK de Seatsyoo, con pnpm, desde la raíz:
275
+
276
+ ```sh
277
+ pnpm --filter @seatsyoo/angular build # dist/ con ng-packagr (formato de paquete de Angular)
278
+ pnpm --filter @seatsyoo/angular test # compila y prueba el componente compilado con el visor real
279
+ pnpm --filter @seatsyoo/angular typecheck # tipos de todo y el ejemplo (ejemplo/) con el compilador de Angular
280
+ ```
281
+
282
+ Lo que se publica es `dist/`, no esta carpeta. Con pnpm basta `pnpm pack` aquí: `publishConfig.directory` hace que se
283
+ empaquete `dist/` y `prepack` la compila antes. Con npm, que no entiende `publishConfig.directory`, `pnpm run build` y
284
+ después `npm pack ./dist` (empaquetar esta carpeta con npm se para con un aviso). `dist/package.json` lleva
285
+ `publishConfig.access: "public"`, así que el paquete sale público.
286
+
287
+ ---
288
+
289
+ ## Licencia
290
+
291
+ MIT (archivo `LICENSE`). El visor del que depende, `@seatsyoo/visor`, tiene su propia licencia: se usa gratis para
292
+ integrar Seatsyoo.
293
+
294
+ ## English
295
+
296
+ `@seatsyoo/angular` is the **Seatsyoo** seating chart as an Angular standalone component, `<seatsyoo-chart>`
297
+ (Angular 17+, with or without zone.js, SSR-safe). Install it with `npm install @seatsyoo/angular`, import
298
+ `SeatsyooChartComponent` and give the element a height:
299
+
300
+ ```html
301
+ <seatsyoo-chart style="height: 640px" server="https://seatsyoo.example" publicKey="pk_your_public_key"
302
+ event="hamlet-2026-11-20" (selectionChange)="selection = $event" />
303
+ ```
304
+
305
+ - **Embedded designer:** `<seatsyoo-designer server [token] [refreshToken] (publish) (designerClose) />`
306
+ (`SeatsyooDesignerComponent`) opens the Seatsyoo chart designer in your website, with a session token your server
307
+ opens with its secret key (`POST /api/v1/charts/{chart}/designer-sessions`).
308
+ - **Inputs:** every `render()` option of `@seatsyoo/visor` except `container` and the callbacks (`server`,
309
+ `publicKey`, `event`, `season`, `seasonEvents`, `link`, `document`, `channels`, `pricing`, `currency`, `locale`,
310
+ `language`, `maxSelected`, `session`, `holdToken`, `mode`, `showLegend`, `showSelectionBar`, `floor`, `sectors`,
311
+ `view3d`, `entrance`, `texts`, `theme`, `colorBy`, `statusStyles`, `marks`, `load3d`). Changing any of them remounts the chart
312
+ (arrays and objects are compared by value), except `theme`, `colorBy`, `statusStyles` and `marks` (`"manager"`
313
+ mode), which are applied in place when their value changes (compared as data: the prototype doesn't matter and a
314
+ key set to `undefined` counts as missing; pass a new object, as with any Angular input), and `load3d`.
315
+ - **Prices:** Seatsyoo does not store prices. Pass yours with `pricing` (per category key, with `currency` and
316
+ `locale`): the chart shows them and they come in `price` of each selected object (`null` without `pricing`).
317
+ `price` is what each unit of `quantity` costs (per place; a whole table, all its chairs), so `price × quantity` adds
318
+ up to the chart's total.
319
+ - **Selling:** the page sends your server the event and the `holdToken`, nothing else. At checkout your server asks
320
+ Seatsyoo what that token holds (`GET /api/v1/events/{event}/statuses?holdToken=…`: `mine: true`, plus `mq` in a
321
+ standing area with the token's places, which only comes when more than one place is taken there, counting other
322
+ buyers'; when it is missing, it is 1), prices it (price × places: a whole table counts all its chairs, as in the
323
+ viewer's total) and stores that list with the order, each object with an explicit quantity
324
+ (`{ key, quantity: mq ?? 1 }`). Once paid, it books exactly that list (`POST …/actions/book` with
325
+ `holdToken` and your `orderId`). Never book a list sent by the page: `book` also books free objects, so anyone could
326
+ add seats they never held. The `@seatsyoo/node` example store (`ejemplo/tienda.ts`) does this; see
327
+ **/en/docs/integration**.
328
+ - **Hold limits** (errors in `chartError`): `hold-limit` (409, the workspace's "places per buyer", `maxHoldPerToken`, 10
329
+ by default, per token and event; a whole table or box counts all its places), `hold-limit-ip` (409, per connection
330
+ and event: 10% of the capacity, up to 200, never below `maxHoldPerToken`) and `hold-rate-limited` (429, 600 places
331
+ held per IP every 10 minutes). `maxSelected` counts a whole table or box as 1, so keep it at or below
332
+ `maxHoldPerToken` and expect `hold-limit` with whole tables. `selectBestAvailable(n)` takes 1 to 100 and never more
333
+ than `maxHoldPerToken`. A `holdToken` your server creates with the secret key has no IP, so it does not count for
334
+ `hold-limit-ip`, but what the buyer holds with it from the viewer still counts for `hold-limit` and
335
+ `hold-rate-limited`. Your server's own calls with the secret key have none of these limits. Tell the codes apart in
336
+ `chartError`: with a hold limit, the buyer should not read that the chart failed to load.
337
+ - **Custom statuses and marks** (`"manager"` mode): `marks` is the `marks` of `GET /api/v1/events/{event}/marks` as
338
+ is. `statusStyles` is not the shape of `GET /api/v1/statuses`: per status key, `{ name, color, icon }` with the icon
339
+ converted (`text` → `{ text }`, `image` → `{ image: src }`, `preset` → no icon or your own 24×24 `{ path }`); from
340
+ `system`, only entries with a `color`, never `free` (one with `color: null` stays exactly as the viewer draws it:
341
+ its own name and icon are lost too, even if the panel shows them; give it its own colour if you want them). Both
342
+ need the secret key: your server fetches them. The `estilosDeEstados` function above does the conversion.
343
+ - **Outputs:** `ready`, `selectionChange`, `objectSelect`, `objectDeselect`, `holdExpired`, `holdTokenChange`,
344
+ `floorChange` and `chartError` (`{ code, message }`; logged to the console when nobody listens). After a remount
345
+ the new chart reports its selection again and, if the previous chart had a hold token and the new one has none,
346
+ `holdTokenChange` emits `null` once it has loaded.
347
+ - **`chart`:** the `SeatingChart` instance (or `null`), with `getSelection()`, `holdToken`, `clearSelection()`,
348
+ `selectBestAvailable()`… The component calls `destroy()` when it is destroyed.
349
+ - The chart runs outside Angular's zone and outputs are emitted inside it. On the server nothing is created or
350
+ fetched; the chart mounts in the browser.
351
+
352
+ License: MIT. The viewer it depends on, `@seatsyoo/visor`, has its own license (free to use to integrate Seatsyoo).