@retalia/pos-components 0.0.8 → 0.0.9

package/README.md

@@ -53,7 +53,7 @@ Add the package stylesheet once in the host app (e.g. `angular.json` `styles`):
 node_modules/@retalia/pos-components/styles/styles.css
 ```
 
-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.
+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`.
 
 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.
 
@@ -87,7 +87,7 @@ src/styles/pos-theme.css
 
 ## Login
 
-Keypad login UI — presentational only. It does not call auth services. Layout around it (e.g. split with an image) belongs in the host app.
+Keypad login UI — presentational only. It does not call auth services.
 
 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.
 
@@ -131,11 +131,16 @@ export class App {
 | Selector | `pos-login` |
 | Input `session` | Display-only login/session state: `signedOut` \| `busy` \| `signedIn`, optional `displayName` |
 | Input `errorMessage` | Optional error text |
+| Input `showAside` | Shop context beside the keypad. Default `true`. Set `false` for the keypad alone |
+| Input `bordered` | Frame around the login shell. Default `false` |
+| 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 |
+| Input `locationName`, `terminalLine`, `shopName`, `posNumber` | Defaults `Address1`, `Address2`, `shop 1`, and `001`. Empty hides that line or tile |
+| Date | Always the PC's local date. `dateLabel` is the caption only |
 | Output `action` | Typed intents: `login.key`, `login.next`, `login.submit`, `login.back`, … |
 
 ## Basket
 
-Presentational sale basket — renders `basket.lines[]` and `totals` exactly as the host envelope provides them. It does not price, tax, or discount. Quantity, void, and clear only emit intents; the host (or server) updates the envelope.
+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`.
 
 ```ts
 import { Component, signal } from '@angular/core';
@@ -172,7 +177,7 @@ export class Sale {
     // Host envelope binding maps:
     //   basket.changeQuantity → change-quantity
     //   basket.voidLine       → void-line
-    //   basket.clear          → clear-basket
+    // Clear sale (`basket.clear`) is dispatched from the transaction action bar.
   }
 }
 ```
@@ -183,7 +188,54 @@ export class Sale {
 | Input `lines` | Envelope `basket.lines[]` as given (`lineId`, `sku`, `name`, `qty`, `unitPrice`, `lineTotal`, `vat`, `struckThrough`) |
 | Input `totals` | Envelope `totals` as given (`gross`, `net`, `vat`, `discount`, `due`, `currency`) |
 | Input `disabled` | Optional lock while the host is busy |
-| Output `action` | Typed intents: `basket.changeQuantity`, `basket.voidLine`, `basket.clear` |
+| Input `bordered` | Panel frame. Default `false` |
+| Output `action` | Typed intents: `basket.changeQuantity`, `basket.voidLine`. `basket.clear` remains a host intent for the action bar |
+
+## Header
+
+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.
+
+```html
+<pos-header
+  [clerkName]="clerkName()"
+  [clerkRole]="clerkRole()"
+  [disabled]="busy()"
+  (action)="onHeader($event)"
+/>
+```
+
+| | |
+|---|---|
+| Selector | `pos-header` |
+| Input `showBrandImage` | Shows an image before the wordmark. Defaults to true. False hides the image, including the built-in mark |
+| Input `brandImage` | Image URL. Empty, while the image is shown, uses the built-in Retalia mark |
+| Input `brandLabel` | Text after the image. Empty shows no text |
+| Input `title` | Screen title. Omitted from the bar when empty |
+| Input `context` | Secondary label, such as the shop name |
+| Input `clerkName` | Signed-in clerk. The bar shows an initial and the name, and hides the block when empty |
+| Input `clerkRole` | Role label under the name, such as Clerk or Manager. Shown in lowercase |
+| Input `signOutLabel` | Menu item label. Defaults to `Portal Logout` |
+| Input `menuLabel` | Accessible name for the menu button. Defaults to `Menu` |
+| Input `canSignOut` | Hides the menu button when false |
+| Input `disabled` | Disables sign out while the host is busy |
+| Output `action` | `header.signOut` |
+
+## Transaction action bar
+
+Layout container for sale commands. It does not render buttons or emit intents. The host projects the controls and decides what each one does, including mapping Cancel to `basket.clear`.
+
+```html
+<pos-transaction-action-bar>
+  <button type="button" (click)="onCancel()">Cancel</button>
+  <button type="button" (click)="onCash()">Cash</button>
+</pos-transaction-action-bar>
+```
+
+| | |
+|---|---|
+| Selector | `pos-transaction-action-bar` |
+| Content | Projected controls. The bar lays them out in a wrapping row |
+| Output | None. Clicks stay on the projected controls |
 
 ## Item entry
 
@@ -219,13 +271,20 @@ export class Sale {
 |---|---|
 | Selector | `pos-item-entry` |
 | Input `disabled` | Optional lock while the host is busy (e.g. AddItem in flight) |
+| Input `bordered` | Panel frame. Default `false` |
 | Input `errorMessage` | Optional host-provided error text (lookup failures belong to the host) |
+| Input `label` | Accessible name for the field. Default `Item`. Not shown on the bar |
 | Input `autofocus` | Focus the field on render so a scanner can type immediately (default `true`) |
+| Input `placeholder` | Field hint. Default `Scan barcode, search products` |
+| Input `scannerStatus` | Status in the chip at the right of the field. Default `scanner ready` |
+| Input `focusHotkey` | Key that focuses the field, shown beside the chip. Default `F2`. Empty hides the hint and the shortcut |
 | Output `action` | Typed intent: `itemEntry.submit` with `reference` |
 
+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.
+
 ## Tender
 
-Presentational cash tender — the cashier enters the amount tendered; the host envelope sends that intent and passes back `changeDue`. The component never calculates change or takes payment. Card / electronic tender is out of scope.
+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.
 
 ```ts
 import { Component, signal } from '@angular/core';
@@ -272,7 +331,7 @@ export class Tender {
 | Input `currency` | ISO currency code used only for display formatting |
 | Input `disabled` | Optional lock while the host is busy |
 | Input `errorMessage` | Optional error text |
-| Output `action` | Typed intent: `tender.cash` with the cashier-entered `amount` |
+| Output `action` | `tender.cash` with the amount given, or `tender.cancel` |
 
 ## Receipt
 
@@ -335,4 +394,5 @@ export class Receipt {
 | Input `payments` | Envelope `payments[]` as given (`tender`, `amount`, `tendered`, `change`, `state`) |
 | Input `document` | Envelope `document` as given (`number`, `receiptReady`) |
 | Input `disabled` | Optional lock while the host is busy |
+| Input `bordered` | Panel frame. Default `false` |
 | Output `action` | Typed intent: `receipt.newSale` |