@retalia/pos-components 0.0.12 → 0.0.14
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 +410 -442
- package/fesm2022/retalia-pos-components.mjs +58 -23
- package/fesm2022/retalia-pos-components.mjs.map +1 -1
- package/package.json +1 -5
- package/types/retalia-pos-components.d.ts +7 -0
- package/fesm2022/retalia-pos-components-services.mjs +0 -203
- package/fesm2022/retalia-pos-components-services.mjs.map +0 -1
- package/types/retalia-pos-components-services.d.ts +0 -179
package/README.md
CHANGED
|
@@ -1,442 +1,410 @@
|
|
|
1
|
-
# @retalia/pos-components
|
|
2
|
-
|
|
3
|
-
Presentational Adaptive POS Angular components. State in, typed intents out — no service calls.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
Requires **Angular 21** (`@angular/core` and `@angular/common` `^21.2.0`).
|
|
8
|
-
|
|
9
|
-
## Install
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
npm i @retalia/pos-components
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
{
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
```ts
|
|
63
|
-
import { Component } from '@angular/core';
|
|
64
|
-
import {
|
|
65
|
-
|
|
66
|
-
@Component({
|
|
67
|
-
selector: 'app-
|
|
68
|
-
imports: [
|
|
69
|
-
template:
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
|
178
|
-
|
|
|
179
|
-
|
|
|
180
|
-
| Input `
|
|
181
|
-
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
|
200
|
-
|
|
|
201
|
-
|
|
|
202
|
-
|
|
|
203
|
-
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
`editing`
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
gross: 0,
|
|
412
|
-
net: 0,
|
|
413
|
-
vat: 0,
|
|
414
|
-
discount: 0,
|
|
415
|
-
due: 0,
|
|
416
|
-
currency: 'EUR',
|
|
417
|
-
});
|
|
418
|
-
readonly payments = signal<readonly PosReceiptPayment[]>([]);
|
|
419
|
-
readonly document = signal<PosReceiptDocument>({
|
|
420
|
-
number: '',
|
|
421
|
-
receiptReady: false,
|
|
422
|
-
});
|
|
423
|
-
|
|
424
|
-
onReceiptAction(intent: PosReceiptIntent): void {
|
|
425
|
-
if (intent.type !== 'receipt.newSale') {
|
|
426
|
-
return;
|
|
427
|
-
}
|
|
428
|
-
// Host envelope binding maps receipt.newSale → newSale.
|
|
429
|
-
}
|
|
430
|
-
}
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
| | |
|
|
434
|
-
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
435
|
-
| Selector | `pos-receipt` |
|
|
436
|
-
| Input `lines` | Envelope `basket.lines[]` as given (`lineId`, `sku`, `name`, `qty`, `unitPrice`, `lineTotal`, `vat`, `struckThrough`) |
|
|
437
|
-
| Input `totals` | Envelope `totals` as given (`gross`, `net`, `vat`, `discount`, `due`, `currency`) |
|
|
438
|
-
| Input `payments` | Envelope `payments[]` as given (`tender`, `amount`, `tendered`, `change`, `state`) |
|
|
439
|
-
| Input `document` | Envelope `document` as given (`number`, `receiptReady`) |
|
|
440
|
-
| Input `disabled` | Optional lock while the host is busy |
|
|
441
|
-
| Input `bordered` | Panel frame. Default `false` |
|
|
442
|
-
| Output `action` | Typed intent: `receipt.newSale` |
|
|
1
|
+
# @retalia/pos-components
|
|
2
|
+
|
|
3
|
+
Presentational Adaptive POS Angular components. State in, typed intents out — no service calls.
|
|
4
|
+
|
|
5
|
+
API clients live in **`@retalia/pos-sdk`**. Components never import that package. The host calls the SDK, then passes display state into the UI.
|
|
6
|
+
|
|
7
|
+
Requires **Angular 21** (`@angular/core` and `@angular/common` `^21.2.0`).
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm i @retalia/pos-components
|
|
13
|
+
npm i @retalia/pos-sdk
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Styles
|
|
17
|
+
|
|
18
|
+
Add the package stylesheet once in the host app (e.g. `angular.json` `styles`):
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
node_modules/@retalia/pos-components/styles/styles.css
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Theme via CSS custom properties (`--pos-*`) defined in that file. Override tokens in the host to rebrand; values not exposed as tokens are not overridable without a library change. Brand wordmarks use `--pos-letter-spacing-brand`, tight titles use `--pos-letter-spacing-tight`, keypad keys use `--pos-shadow-key`, and menus use `--pos-shadow-overlay`. The masked PIN keeps `--pos-letter-spacing-display`.
|
|
25
|
+
|
|
26
|
+
Use `<pos-tokens>` (Storybook: **Theme / Tokens**, or an internal theme lab page) to see every token in action. Click a sample or token to edit values as **live overrides** — this does not change the package defaults in `styles.css`. Export a complete `:root` CSS file for the consuming POS, and import that file back into the lab later.
|
|
27
|
+
|
|
28
|
+
## Tokens gallery
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
import { Component } from '@angular/core';
|
|
32
|
+
import { PosTokens } from '@retalia/pos-components';
|
|
33
|
+
|
|
34
|
+
@Component({
|
|
35
|
+
selector: 'app-theme-lab',
|
|
36
|
+
imports: [PosTokens],
|
|
37
|
+
template: `<pos-tokens />`,
|
|
38
|
+
})
|
|
39
|
+
export class ThemeLab {}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Host the exported file **after** the package stylesheet so `--pos-*` overrides win:
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
node_modules/@retalia/pos-components/styles/styles.css
|
|
46
|
+
src/styles/pos-theme.css
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
| | |
|
|
50
|
+
| -------- | ------------------------------------------------------------ |
|
|
51
|
+
| Selector | `pos-tokens` |
|
|
52
|
+
| Purpose | Documentation / theme lab — not for production POS screens |
|
|
53
|
+
| Export | Complete `:root { --pos-*: … }` CSS for the host POS |
|
|
54
|
+
| Import | Previously exported theme CSS, applied as lab overrides only |
|
|
55
|
+
|
|
56
|
+
## Login
|
|
57
|
+
|
|
58
|
+
Keypad login UI — presentational only. It does not call auth services.
|
|
59
|
+
|
|
60
|
+
The host envelope holds login/session state and passes it in. If the host uses a package `AuthService`, it calls that on `login.submit`, then updates `[session]` / `[errorMessage]`. The component never injects the service.
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
import { Component, signal } from '@angular/core';
|
|
64
|
+
import { PosLogin, PosLoginIntent, PosLoginSessionState } from '@retalia/pos-components';
|
|
65
|
+
|
|
66
|
+
@Component({
|
|
67
|
+
selector: 'app-root',
|
|
68
|
+
imports: [PosLogin],
|
|
69
|
+
template: `
|
|
70
|
+
<pos-login
|
|
71
|
+
[session]="session()"
|
|
72
|
+
[errorMessage]="errorMessage()"
|
|
73
|
+
(action)="onLoginAction($event)"
|
|
74
|
+
/>
|
|
75
|
+
`,
|
|
76
|
+
})
|
|
77
|
+
export class App {
|
|
78
|
+
readonly session = signal<PosLoginSessionState>({ status: 'signedOut' });
|
|
79
|
+
readonly errorMessage = signal('');
|
|
80
|
+
|
|
81
|
+
onLoginAction(intent: PosLoginIntent): void {
|
|
82
|
+
if (intent.type !== 'login.submit') {
|
|
83
|
+
return;
|
|
84
|
+
}
|
|
85
|
+
// Host (or @retalia/pos-sdk ClerkAuthService) calls the API, then:
|
|
86
|
+
// this.session.set({ status: 'busy' });
|
|
87
|
+
// this.session.set({ status: 'signedIn', displayName: clerk.name });
|
|
88
|
+
// this.errorMessage.set('Invalid clerk or password');
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
| | |
|
|
94
|
+
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
95
|
+
| Selector | `pos-login` |
|
|
96
|
+
| Input `session` | Display-only login/session state: `signedOut` \| `busy` \| `signedIn`, optional `displayName` |
|
|
97
|
+
| Input `errorMessage` | Optional error text |
|
|
98
|
+
| Input `showAside` | Shop context beside the keypad. Default `true`. Set `false` for the keypad alone |
|
|
99
|
+
| Input `bordered` | Frame around the login shell. Default `false` |
|
|
100
|
+
| Input `showBrandImage`, `brandImage`, `brandLabel` | Same brand rules as the header. `brandLabel` defaults to `RETALIA`. Empty hides the word. Empty `brandImage` uses the built-in mark |
|
|
101
|
+
| Input `locationName`, `terminalLine`, `shopName`, `posNumber` | Defaults `Address1`, `Address2`, `shop 1`, and `001`. Empty hides that line or tile |
|
|
102
|
+
| Date | Always the PC's local date. `dateLabel` is the caption only |
|
|
103
|
+
| Output `action` | Typed intents: `login.key`, `login.next`, `login.submit`, `login.back`, … |
|
|
104
|
+
|
|
105
|
+
## Basket
|
|
106
|
+
|
|
107
|
+
Presentational sale basket — renders `basket.lines[]` and `totals` exactly as the host envelope provides them. It does not price, tax, or discount. Quantity and void only emit intents; the host (or server) updates the envelope. Clearing the sale is a transaction action bar control, not a basket button. The host still dispatches `basket.clear`.
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
import { Component, signal } from '@angular/core';
|
|
111
|
+
import {
|
|
112
|
+
PosBasket,
|
|
113
|
+
PosBasketIntent,
|
|
114
|
+
PosBasketLine,
|
|
115
|
+
PosBasketTotals,
|
|
116
|
+
} from '@retalia/pos-components';
|
|
117
|
+
|
|
118
|
+
@Component({
|
|
119
|
+
selector: 'app-sale',
|
|
120
|
+
imports: [PosBasket],
|
|
121
|
+
template: `
|
|
122
|
+
<pos-basket [lines]="lines()" [totals]="totals()" (action)="onBasketAction($event)" />
|
|
123
|
+
`,
|
|
124
|
+
})
|
|
125
|
+
export class Sale {
|
|
126
|
+
readonly lines = signal<readonly PosBasketLine[]>([]);
|
|
127
|
+
readonly totals = signal<PosBasketTotals>({
|
|
128
|
+
gross: 0,
|
|
129
|
+
net: 0,
|
|
130
|
+
vat: 0,
|
|
131
|
+
discount: 0,
|
|
132
|
+
due: 0,
|
|
133
|
+
currency: 'EUR',
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
onBasketAction(intent: PosBasketIntent): void {
|
|
137
|
+
// Host envelope binding maps:
|
|
138
|
+
// basket.changeQuantity → change-quantity
|
|
139
|
+
// basket.voidLine → void-line
|
|
140
|
+
// Clear sale (`basket.clear`) is dispatched from the transaction action bar.
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
| | |
|
|
146
|
+
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
147
|
+
| Selector | `pos-basket` |
|
|
148
|
+
| Input `lines` | Envelope `basket.lines[]` as given (`lineId`, `sku`, `name`, `qty`, `unitPrice`, `lineTotal`, `vat`, `struckThrough`) |
|
|
149
|
+
| Input `totals` | Envelope `totals` as given (`gross`, `net`, `vat`, `discount`, `due`, `currency`) |
|
|
150
|
+
| Input `disabled` | Optional lock while the host is busy |
|
|
151
|
+
| Input `bordered` | Panel frame. Default `false` |
|
|
152
|
+
| Output `action` | Typed intents: `basket.changeQuantity`, `basket.voidLine`. `basket.clear` remains a host intent for the action bar |
|
|
153
|
+
|
|
154
|
+
## Header
|
|
155
|
+
|
|
156
|
+
Placeable sale chrome. The host passes the title, shop or other context, and clerk name. The menu beside the clerk initial currently offers sign out only. That click emits an intent; the host clears the session and navigates. The component does not know where it sits in the layout.
|
|
157
|
+
|
|
158
|
+
```html
|
|
159
|
+
<pos-header
|
|
160
|
+
[clerkName]="clerkName()"
|
|
161
|
+
[clerkRole]="clerkRole()"
|
|
162
|
+
[disabled]="busy()"
|
|
163
|
+
(action)="onHeader($event)"
|
|
164
|
+
/>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
| | |
|
|
168
|
+
| ---------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
169
|
+
| Selector | `pos-header` |
|
|
170
|
+
| Input `showBrandImage` | Shows an image before the wordmark. Defaults to true. False hides the image, including the built-in mark |
|
|
171
|
+
| Input `brandImage` | Image URL. Empty, while the image is shown, uses the built-in Retalia mark |
|
|
172
|
+
| Input `brandLabel` | Text after the image. Empty shows no text |
|
|
173
|
+
| Input `title` | Screen title. Omitted from the bar when empty |
|
|
174
|
+
| Input `context` | Secondary label, such as the shop name |
|
|
175
|
+
| Input `clerkName` | Signed-in clerk. The bar shows an initial and the name, and hides the block when empty |
|
|
176
|
+
| Input `clerkRole` | Role label under the name, such as Clerk or Manager. Shown in lowercase |
|
|
177
|
+
| Input `signOutLabel` | Menu item label. Defaults to `Portal Logout` |
|
|
178
|
+
| Input `menuLabel` | Accessible name for the menu button. Defaults to `Menu` |
|
|
179
|
+
| Input `canSignOut` | Hides the menu button when false |
|
|
180
|
+
| Input `disabled` | Disables sign out while the host is busy |
|
|
181
|
+
| Output `action` | `header.signOut` |
|
|
182
|
+
|
|
183
|
+
## Transaction action bar
|
|
184
|
+
|
|
185
|
+
Sale commands for the open basket. Cancel and Cash are drawn by the bar, in the danger and success colors, when the envelope lists `clearBasket` or `tender`. The host can still project extra controls into the same row. Cancel emits `actionBar.clearBasket`. The host maps that to `basket.clear`. Cash emits `actionBar.tender`.
|
|
186
|
+
|
|
187
|
+
```html
|
|
188
|
+
<pos-transaction-action-bar
|
|
189
|
+
[availableActions]="availableActions()"
|
|
190
|
+
[disabled]="busy()"
|
|
191
|
+
(action)="onActionBar($event)"
|
|
192
|
+
>
|
|
193
|
+
<button type="button" (click)="onPark()">Park</button>
|
|
194
|
+
</pos-transaction-action-bar>
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
| | |
|
|
198
|
+
| ----------------------- | -------------------------------------------------------------------------- |
|
|
199
|
+
| Selector | `pos-transaction-action-bar` |
|
|
200
|
+
| Input `availableActions` | `clearBasket` shows Cancel. `tender` shows Cash |
|
|
201
|
+
| Input `disabled` | Disables Cancel and Cash while the host is busy |
|
|
202
|
+
| Output `action` | `actionBar.clearBasket` or `actionBar.tender` |
|
|
203
|
+
| Content | Optional extra controls, laid out in the same wrapping row |
|
|
204
|
+
|
|
205
|
+
## Item entry
|
|
206
|
+
|
|
207
|
+
Presentational scan-or-type field for the sale screen. It captures an item reference (barcode scan or typed SKU) and emits an item-entry intent. It does not look up, validate, or price the item — the host envelope maps the intent to `item-entry`, and the server handles catalog lookup.
|
|
208
|
+
|
|
209
|
+
```ts
|
|
210
|
+
import { Component, signal } from '@angular/core';
|
|
211
|
+
import { PosItemEntry, PosItemEntryIntent } from '@retalia/pos-components';
|
|
212
|
+
|
|
213
|
+
@Component({
|
|
214
|
+
selector: 'app-sale',
|
|
215
|
+
imports: [PosItemEntry],
|
|
216
|
+
template: `
|
|
217
|
+
<pos-item-entry
|
|
218
|
+
[disabled]="busy()"
|
|
219
|
+
[errorMessage]="errorMessage()"
|
|
220
|
+
(action)="onItemEntryAction($event)"
|
|
221
|
+
/>
|
|
222
|
+
`,
|
|
223
|
+
})
|
|
224
|
+
export class Sale {
|
|
225
|
+
readonly busy = signal(false);
|
|
226
|
+
readonly errorMessage = signal('');
|
|
227
|
+
|
|
228
|
+
onItemEntryAction(intent: PosItemEntryIntent): void {
|
|
229
|
+
// Host envelope binding maps:
|
|
230
|
+
// itemEntry.submit → item-entry (payload: reference)
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
| | |
|
|
236
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
237
|
+
| Selector | `pos-item-entry` |
|
|
238
|
+
| Input `disabled` | Optional lock while the host is busy (e.g. AddItem in flight) |
|
|
239
|
+
| Input `bordered` | Panel frame. Default `false` |
|
|
240
|
+
| Input `errorMessage` | Optional host-provided error text (lookup failures belong to the host) |
|
|
241
|
+
| Input `label` | Accessible name for the field. Default `Item`. Not shown on the bar |
|
|
242
|
+
| Input `autofocus` | Focus the field on render so a scanner can type immediately (default `true`) |
|
|
243
|
+
| Input `placeholder` | Field hint. Default `Scan barcode, search products` |
|
|
244
|
+
| Input `scannerStatus` | Status in the chip at the right of the field. Default `scanner ready` |
|
|
245
|
+
| Input `focusHotkey` | Key that focuses the field, shown beside the chip. Default `F2`. Empty hides the hint and the shortcut |
|
|
246
|
+
| Output `action` | Typed intent: `itemEntry.submit` with `reference` |
|
|
247
|
+
|
|
248
|
+
Enter in the field submits the reference. `F2` moves focus back to the field from anywhere else on the page, matching the POS proof of concept. The label is the accessible name and is not shown on the bar.
|
|
249
|
+
|
|
250
|
+
## Workspace
|
|
251
|
+
|
|
252
|
+
Logged-in sale shell. It places the header, item lookup, basket, and action bar. The default stack matches the sale screen: header, item lookup, a flexible basket, then the action bar. The host still owns each region's state and intents; the workspace only arranges them.
|
|
253
|
+
|
|
254
|
+
`editing` draws a Components menu above the screen, plus a dashed outline, a drag handle, a settings control, and a height bar on each region that is placed. Open the menu and drag a component onto the screen, or press it, and it stacks in the left column. The menu scrolls, so a long list stays usable. Drag those panes after that to move them. While one is moving, the right side is highlighted. Drop on the right side and that region docks there at full height. Drop a pane above that docked column to span both columns. Full width is also a setting. A pane fills leftover height only when Flexible height is on, which sets its weight above 0. Weight 0 stays the content height. Visible hides that pane on the till and keeps it in the editor so it can be shown again. The X removes that pane: a library component goes back to the Components menu, and an empty slot is deleted. `fullWidth: true` and `span: 'top'` are the top placement. `span: 'bottom'` is the bottom placement. Drag the bar under a region to share leftover height, or the divider between columns to change the split. Arrow keys do the same from the keyboard. Undo restores the previous arrangement. Default layout puts the sale stack back: header, item lookup, basket, then the action bar. New clears every region off the screen and returns the library components to the Components menu. The arrangement used when the host does not pass a layout is still that sale stack.
|
|
255
|
+
|
|
256
|
+
Custom container adds the next slot, `empty-1`, then `empty-2`, and so on. On screen they are Custom container 1, Custom container 2, and so on. That slot is only a space. The consuming POS fills it by projecting a pane with the same id. Until that content is projected, the slot keeps the custom-container name. A region that is not listed in `layout.panes` stays off the screen, including while editing.
|
|
257
|
+
|
|
258
|
+
`layoutChange` reports the arrangement when a component is added, moved, resized, removed, or the layout is reset. This package does not save it. Export layout downloads that arrangement as `pos-workspace-layout.json` and emits `layoutExport`. Import layout reads that same file and applies it. Pass the object back as `layout` from the consuming POS, or call `parseWorkspaceLayout` on the file text. On a narrow screen the regions stack in one column, with the header kept at the top and the action bar at the bottom.
|
|
259
|
+
|
|
260
|
+
```html
|
|
261
|
+
<pos-workspace [editing]="editing()" (layoutChange)="onLayout($event)">
|
|
262
|
+
<pos-workspace-pane paneId="header">
|
|
263
|
+
<pos-header [clerkName]="clerkName()" (action)="onHeader($event)" />
|
|
264
|
+
</pos-workspace-pane>
|
|
265
|
+
<pos-workspace-pane paneId="itemEntry">
|
|
266
|
+
<pos-item-entry (action)="onItemEntry($event)" />
|
|
267
|
+
</pos-workspace-pane>
|
|
268
|
+
<pos-workspace-pane paneId="basket">
|
|
269
|
+
<pos-basket [lines]="lines()" [totals]="totals()" (action)="onBasket($event)" />
|
|
270
|
+
</pos-workspace-pane>
|
|
271
|
+
<pos-workspace-pane paneId="actionBar">
|
|
272
|
+
<pos-transaction-action-bar
|
|
273
|
+
[availableActions]="availableActions()"
|
|
274
|
+
(action)="onActionBar($event)"
|
|
275
|
+
/>
|
|
276
|
+
</pos-workspace-pane>
|
|
277
|
+
<pos-workspace-pane paneId="empty-1">
|
|
278
|
+
<app-custom-panel />
|
|
279
|
+
</pos-workspace-pane>
|
|
280
|
+
</pos-workspace>
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
| | |
|
|
284
|
+
| --------------------- | ------------------------------------------------------------------------ |
|
|
285
|
+
| Selector | `pos-workspace` |
|
|
286
|
+
| Input `editing` | Shows outlines, drag handles, and resize controls. Default `false` |
|
|
287
|
+
| Input `layout` | Optional starting arrangement. Default is the sale stack |
|
|
288
|
+
| Output `layoutChange` | The arrangement after an add, move, resize, remove, or reset. Not stored |
|
|
289
|
+
| Output `layoutExport` | The arrangement from Export layout, ready to pass back as `layout` |
|
|
290
|
+
| `parseWorkspaceLayout` | Reads an exported layout file back into a `layout` value |
|
|
291
|
+
| Pane `paneId` | `header`, `itemEntry`, `basket`, `actionBar`, or `empty-1`, `empty-2`, … |
|
|
292
|
+
| Pane `fullWidth` | On a placement in `layout`. Spans both columns above the split |
|
|
293
|
+
| Pane `span` | `top` or `bottom`. Spans both columns on that edge of the split |
|
|
294
|
+
| Pane `weight` | `0` sizes to content. Above `0`, the pane shares leftover height |
|
|
295
|
+
| Pane `visible` | Omitted or `true` shows the pane. `false` hides it on the till |
|
|
296
|
+
|
|
297
|
+
## Tender
|
|
298
|
+
|
|
299
|
+
Presentational cash tender — coins, notes, and quick amounts build the amount given. Pay Now emits `tender.cash`. Cancel emits `tender.cancel`. The host envelope sends the cash intent and passes back `changeDue`. The component never calculates change or takes payment. Card / electronic tender is out of scope.
|
|
300
|
+
|
|
301
|
+
```ts
|
|
302
|
+
import { Component, signal } from '@angular/core';
|
|
303
|
+
import { PosTender, PosTenderIntent } from '@retalia/pos-components';
|
|
304
|
+
|
|
305
|
+
@Component({
|
|
306
|
+
selector: 'app-tender',
|
|
307
|
+
imports: [PosTender],
|
|
308
|
+
template: `
|
|
309
|
+
<pos-tender
|
|
310
|
+
[amountDue]="amountDue()"
|
|
311
|
+
[changeDue]="changeDue()"
|
|
312
|
+
[currency]="currency()"
|
|
313
|
+
[disabled]="busy()"
|
|
314
|
+
[errorMessage]="errorMessage()"
|
|
315
|
+
(action)="onTenderAction($event)"
|
|
316
|
+
/>
|
|
317
|
+
`,
|
|
318
|
+
})
|
|
319
|
+
export class Tender {
|
|
320
|
+
readonly amountDue = signal(12);
|
|
321
|
+
readonly changeDue = signal<number | null>(null);
|
|
322
|
+
readonly currency = signal('EUR');
|
|
323
|
+
readonly busy = signal(false);
|
|
324
|
+
readonly errorMessage = signal('');
|
|
325
|
+
|
|
326
|
+
onTenderAction(intent: PosTenderIntent): void {
|
|
327
|
+
if (intent.type !== 'tender.cash') {
|
|
328
|
+
return;
|
|
329
|
+
}
|
|
330
|
+
// Host envelope binding maps tender.cash → tender intent,
|
|
331
|
+
// then sets changeDue from the envelope response.
|
|
332
|
+
// this.busy.set(true);
|
|
333
|
+
// this.changeDue.set(envelope.changeDue);
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
| | |
|
|
339
|
+
| -------------------- | -------------------------------------------------------------------------------------------------- |
|
|
340
|
+
| Selector | `pos-tender` |
|
|
341
|
+
| Input `amountDue` | Envelope amount due as given — display only |
|
|
342
|
+
| Input `changeDue` | Envelope change due as given (`null` until the host responds). Shown as received, never calculated |
|
|
343
|
+
| Input `currency` | ISO currency code used only for display formatting |
|
|
344
|
+
| Input `disabled` | Optional lock while the host is busy |
|
|
345
|
+
| Input `errorMessage` | Optional error text |
|
|
346
|
+
| Output `action` | `tender.cash` with the amount given, or `tender.cancel` |
|
|
347
|
+
|
|
348
|
+
## Receipt
|
|
349
|
+
|
|
350
|
+
Presentational completed-sale receipt — renders `basket.lines[]`, `totals`, `payments[]`, and `document` exactly as the host envelope provides them. It does not format, tax, or calculate change. Printing is out of scope.
|
|
351
|
+
|
|
352
|
+
```ts
|
|
353
|
+
import { Component, signal } from '@angular/core';
|
|
354
|
+
import {
|
|
355
|
+
PosReceipt,
|
|
356
|
+
PosReceiptIntent,
|
|
357
|
+
PosReceiptLine,
|
|
358
|
+
PosReceiptPayment,
|
|
359
|
+
PosReceiptTotals,
|
|
360
|
+
PosReceiptDocument,
|
|
361
|
+
} from '@retalia/pos-components';
|
|
362
|
+
|
|
363
|
+
@Component({
|
|
364
|
+
selector: 'app-receipt',
|
|
365
|
+
imports: [PosReceipt],
|
|
366
|
+
template: `
|
|
367
|
+
<pos-receipt
|
|
368
|
+
[lines]="lines()"
|
|
369
|
+
[totals]="totals()"
|
|
370
|
+
[payments]="payments()"
|
|
371
|
+
[document]="document()"
|
|
372
|
+
(action)="onReceiptAction($event)"
|
|
373
|
+
/>
|
|
374
|
+
`,
|
|
375
|
+
})
|
|
376
|
+
export class Receipt {
|
|
377
|
+
readonly lines = signal<readonly PosReceiptLine[]>([]);
|
|
378
|
+
readonly totals = signal<PosReceiptTotals>({
|
|
379
|
+
gross: 0,
|
|
380
|
+
net: 0,
|
|
381
|
+
vat: 0,
|
|
382
|
+
discount: 0,
|
|
383
|
+
due: 0,
|
|
384
|
+
currency: 'EUR',
|
|
385
|
+
});
|
|
386
|
+
readonly payments = signal<readonly PosReceiptPayment[]>([]);
|
|
387
|
+
readonly document = signal<PosReceiptDocument>({
|
|
388
|
+
number: '',
|
|
389
|
+
receiptReady: false,
|
|
390
|
+
});
|
|
391
|
+
|
|
392
|
+
onReceiptAction(intent: PosReceiptIntent): void {
|
|
393
|
+
if (intent.type !== 'receipt.newSale') {
|
|
394
|
+
return;
|
|
395
|
+
}
|
|
396
|
+
// Host envelope binding maps receipt.newSale → newSale.
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
| | |
|
|
402
|
+
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
403
|
+
| Selector | `pos-receipt` |
|
|
404
|
+
| Input `lines` | Envelope `basket.lines[]` as given (`lineId`, `sku`, `name`, `qty`, `unitPrice`, `lineTotal`, `vat`, `struckThrough`) |
|
|
405
|
+
| Input `totals` | Envelope `totals` as given (`gross`, `net`, `vat`, `discount`, `due`, `currency`) |
|
|
406
|
+
| Input `payments` | Envelope `payments[]` as given (`tender`, `amount`, `tendered`, `change`, `state`) |
|
|
407
|
+
| Input `document` | Envelope `document` as given (`number`, `receiptReady`) |
|
|
408
|
+
| Input `disabled` | Optional lock while the host is busy |
|
|
409
|
+
| Input `bordered` | Panel frame. Default `false` |
|
|
410
|
+
| Output `action` | Typed intent: `receipt.newSale` |
|