@retalia/pos-components 0.0.2 → 0.0.4

package/README.md

@@ -1,44 +1,303 @@
-# @retalia/pos-components
-
-Presentational Adaptive POS Angular components. State in, typed intents out — no service calls.
-
-Requires **Angular 21** (`@angular/core` and `@angular/common` `^21.2.0`).
-
-## Install
-
-```bash
-npm i @retalia/pos-components
-```
-
-## Hello world
-
-Import the standalone component and put it in the template.
-
-```ts
-import { Component } from '@angular/core';
-import { PosHelloWorld, HelloWorldIntent } from '@retalia/pos-components';
-
-@Component({
-  selector: 'app-root',
-  imports: [PosHelloWorld],
-  template: `
-    <pos-hello-world
-      [label]="'Library connected'"
-      (acknowledge)="onAcknowledge($event)"
-    />
-  `,
-})
-export class App {
-  onAcknowledge(intent: HelloWorldIntent): void {
-    console.log(intent.type); // 'helloWorld.acknowledge'
-  }
-}
-```
-
-| | |
-|---|---|
-| Selector | `pos-hello-world` |
-| Input `label` | Heading text (optional) |
-| Output `acknowledge` | `{ type: 'helloWorld.acknowledge' }` when the user clicks Acknowledge |
-
-If the card renders, the package installed and the host can consume components from this library.
+# @retalia/pos-components
+
+Presentational Adaptive POS Angular components. State in, typed intents out — no service calls.
+
+Requires **Angular 21** (`@angular/core` and `@angular/common` `^21.2.0`).
+
+## Install
+
+```bash
+npm i @retalia/pos-components
+```
+
+## Styles
+
+Add the package stylesheet once in the host app (e.g. `angular.json` `styles`):
+
+```text
+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.
+
+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.
+
+## Tokens gallery
+
+```ts
+import { Component } from '@angular/core';
+import { PosTokens } from '@retalia/pos-components';
+
+@Component({
+  selector: 'app-theme-lab',
+  imports: [PosTokens],
+  template: `<pos-tokens />`,
+})
+export class ThemeLab {}
+```
+
+Host the exported file **after** the package stylesheet so `--pos-*` overrides win:
+
+```text
+node_modules/@retalia/pos-components/styles/styles.css
+src/styles/pos-theme.css
+```
+
+| | |
+|---|---|
+| Selector | `pos-tokens` |
+| Purpose | Documentation / theme lab — not for production POS screens |
+| Export | Complete `:root { --pos-*: … }` CSS for the host POS |
+| Import | Previously exported theme CSS, applied as lab overrides only |
+
+## 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.
+
+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.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  PosLogin,
+  PosLoginIntent,
+  PosLoginSessionState,
+} from '@retalia/pos-components';
+
+@Component({
+  selector: 'app-root',
+  imports: [PosLogin],
+  template: `
+    <pos-login
+      [session]="session()"
+      [errorMessage]="errorMessage()"
+      (action)="onLoginAction($event)"
+    />
+  `,
+})
+export class App {
+  readonly session = signal<PosLoginSessionState>({ status: 'signedOut' });
+  readonly errorMessage = signal('');
+
+  onLoginAction(intent: PosLoginIntent): void {
+    if (intent.type !== 'login.submit') {
+      return;
+    }
+    // Host (or optional package AuthService) calls the API, then:
+    // this.session.set({ status: 'busy' });
+    // this.session.set({ status: 'signedIn', displayName: clerk.name });
+    // this.errorMessage.set('Invalid clerk or password');
+  }
+}
+```
+
+| | |
+|---|---|
+| Selector | `pos-login` |
+| Input `session` | Display-only login/session state: `signedOut` \| `busy` \| `signedIn`, optional `displayName` |
+| Input `errorMessage` | Optional error text |
+| 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.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  PosBasket,
+  PosBasketIntent,
+  PosBasketLine,
+  PosBasketTotals,
+} from '@retalia/pos-components';
+
+@Component({
+  selector: 'app-sale',
+  imports: [PosBasket],
+  template: `
+    <pos-basket
+      [lines]="lines()"
+      [totals]="totals()"
+      (action)="onBasketAction($event)"
+    />
+  `,
+})
+export class Sale {
+  readonly lines = signal<readonly PosBasketLine[]>([]);
+  readonly totals = signal<PosBasketTotals>({
+    gross: 0,
+    net: 0,
+    vat: 0,
+    discount: 0,
+    due: 0,
+    currency: 'EUR',
+  });
+
+  onBasketAction(intent: PosBasketIntent): void {
+    // Host envelope binding maps:
+    //   basket.changeQuantity → change-quantity
+    //   basket.voidLine       → void-line
+    //   basket.clear          → clear-basket
+  }
+}
+```
+
+| | |
+|---|---|
+| Selector | `pos-basket` |
+| 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` |
+
+## Item entry
+
+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.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { PosItemEntry, PosItemEntryIntent } from '@retalia/pos-components';
+
+@Component({
+  selector: 'app-sale',
+  imports: [PosItemEntry],
+  template: `
+    <pos-item-entry
+      [disabled]="busy()"
+      [errorMessage]="errorMessage()"
+      (action)="onItemEntryAction($event)"
+    />
+  `,
+})
+export class Sale {
+  readonly busy = signal(false);
+  readonly errorMessage = signal('');
+
+  onItemEntryAction(intent: PosItemEntryIntent): void {
+    // Host envelope binding maps:
+    //   itemEntry.submit → item-entry  (payload: reference)
+  }
+}
+```
+
+| | |
+|---|---|
+| Selector | `pos-item-entry` |
+| Input `disabled` | Optional lock while the host is busy (e.g. AddItem in flight) |
+| Input `errorMessage` | Optional host-provided error text (lookup failures belong to the host) |
+| Input `autofocus` | Focus the field on render so a scanner can type immediately (default `true`) |
+| Output `action` | Typed intent: `itemEntry.submit` with `reference` |
+
+## 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.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { PosTender, PosTenderIntent } from '@retalia/pos-components';
+
+@Component({
+  selector: 'app-tender',
+  imports: [PosTender],
+  template: `
+    <pos-tender
+      [amountDue]="amountDue()"
+      [changeDue]="changeDue()"
+      [currency]="currency()"
+      [disabled]="busy()"
+      [errorMessage]="errorMessage()"
+      (action)="onTenderAction($event)"
+    />
+  `,
+})
+export class Tender {
+  readonly amountDue = signal(12);
+  readonly changeDue = signal<number | null>(null);
+  readonly currency = signal('EUR');
+  readonly busy = signal(false);
+  readonly errorMessage = signal('');
+
+  onTenderAction(intent: PosTenderIntent): void {
+    if (intent.type !== 'tender.cash') {
+      return;
+    }
+    // Host envelope binding maps tender.cash → tender intent,
+    // then sets changeDue from the envelope response.
+    // this.busy.set(true);
+    // this.changeDue.set(envelope.changeDue);
+  }
+}
+```
+
+| | |
+|---|---|
+| Selector | `pos-tender` |
+| Input `amountDue` | Envelope amount due as given — display only |
+| Input `changeDue` | Envelope change due as given (`null` until the host responds). Shown as received, never calculated |
+| 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` |
+
+## Receipt
+
+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.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  PosReceipt,
+  PosReceiptIntent,
+  PosReceiptLine,
+  PosReceiptPayment,
+  PosReceiptTotals,
+  PosReceiptDocument,
+} from '@retalia/pos-components';
+
+@Component({
+  selector: 'app-receipt',
+  imports: [PosReceipt],
+  template: `
+    <pos-receipt
+      [lines]="lines()"
+      [totals]="totals()"
+      [payments]="payments()"
+      [document]="document()"
+      (action)="onReceiptAction($event)"
+    />
+  `,
+})
+export class Receipt {
+  readonly lines = signal<readonly PosReceiptLine[]>([]);
+  readonly totals = signal<PosReceiptTotals>({
+    gross: 0,
+    net: 0,
+    vat: 0,
+    discount: 0,
+    due: 0,
+    currency: 'EUR',
+  });
+  readonly payments = signal<readonly PosReceiptPayment[]>([]);
+  readonly document = signal<PosReceiptDocument>({
+    number: '',
+    receiptReady: false,
+  });
+
+  onReceiptAction(intent: PosReceiptIntent): void {
+    if (intent.type !== 'receipt.newSale') {
+      return;
+    }
+    // Host envelope binding maps receipt.newSale → newSale.
+  }
+}
+```
+
+| | |
+|---|---|
+| Selector | `pos-receipt` |
+| 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 `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 |
+| Output `action` | Typed intent: `receipt.newSale` |

package/eslint.config.js

@@ -0,0 +1,32 @@
+// @ts-check
+const { defineConfig } = require('eslint/config');
+const rootConfig = require('../../eslint.config.js');
+
+module.exports = defineConfig([
+  ...rootConfig,
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'pos',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'pos',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    rules: {},
+  },
+]);

package/ng-package.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/pos-components",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  },
+  "assets": [
+    {
+      "glob": "**/*",
+      "input": "src/styles",
+      "output": "styles"
+    }
+  ]
+}

package/package.json

@@ -1,28 +1,17 @@
-{
-  "name": "@retalia/pos-components",
-  "version": "0.0.2",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "peerDependencies": {
-    "@angular/common": "^21.2.0",
-    "@angular/core": "^21.2.0"
-  },
-  "dependencies": {
-    "tslib": "^2.3.0"
-  },
-  "sideEffects": false,
-  "module": "fesm2022/retalia-pos-components.mjs",
-  "typings": "types/retalia-pos-components.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./types/retalia-pos-components.d.ts",
-      "default": "./fesm2022/retalia-pos-components.mjs"
-    }
-  },
-  "type": "module"
-}
+{
+  "name": "@retalia/pos-components",
+  "version": "0.0.4",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "@angular/common": "^21.2.0",
+    "@angular/core": "^21.2.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": ["**/*.css"],
+  "style": "./styles/styles.css"
+}

package/src/lib/basket/pos-basket.html

@@ -0,0 +1,124 @@
+<section
+  class="pos-basket__panel"
+  [attr.aria-busy]="disabled() ? true : null"
+>
+  <header class="pos-basket__header">
+    <h2 class="pos-basket__title">{{ title() }}</h2>
+    <p class="pos-basket__count">
+      {{ lines().length }}
+      {{ lines().length === 1 ? 'line' : 'lines' }}
+    </p>
+  </header>
+
+  <ul class="pos-basket__lines" aria-label="Basket lines">
+    @if (!hasLines()) {
+      <li class="pos-basket__empty">{{ emptyMessage() }}</li>
+    } @else {
+      @for (line of lines(); track line.lineId) {
+        <li>
+          <article
+            class="pos-basket__line"
+            [class.pos-basket__line--voided]="line.struckThrough"
+          >
+            <div class="pos-basket__line-info">
+              <h3 class="pos-basket__line-name">{{ line.name }}</h3>
+              <p class="pos-basket__line-sku">{{ line.sku }}</p>
+              @if (line.struckThrough) {
+                <p class="pos-basket__line-voided">Voided</p>
+              }
+            </div>
+
+            <div
+              class="pos-basket__stepper"
+              role="group"
+              [attr.aria-label]="'Quantity for ' + line.name"
+            >
+              <button
+                type="button"
+                class="pos-basket__qty-btn"
+                aria-label="Decrease quantity"
+                [disabled]="!canDecrement(line)"
+                (click)="onDecrement(line)"
+              >
+                −
+              </button>
+              <span class="pos-basket__qty" aria-live="polite">{{ line.qty }}</span>
+              <button
+                type="button"
+                class="pos-basket__qty-btn"
+                aria-label="Increase quantity"
+                [disabled]="!canChangeQuantity(line)"
+                (click)="onIncrement(line)"
+              >
+                +
+              </button>
+            </div>
+
+            <div class="pos-basket__line-prices">
+              <p class="pos-basket__unit-price">{{ formatMoney(line.unitPrice) }}</p>
+              <p class="pos-basket__line-total">{{ formatMoney(line.lineTotal) }}</p>
+            </div>
+
+            <button
+              type="button"
+              class="pos-basket__void"
+              [attr.aria-label]="'Void ' + line.name"
+              [disabled]="!canVoid(line)"
+              (click)="onVoid(line)"
+            >
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="18"
+                height="18"
+                viewBox="0 0 24 24"
+                fill="none"
+                aria-hidden="true"
+              >
+                <path
+                  d="M6 6l12 12M18 6 6 18"
+                  stroke="currentColor"
+                  stroke-width="2"
+                  stroke-linecap="round"
+                />
+              </svg>
+            </button>
+          </article>
+        </li>
+      }
+    }
+  </ul>
+
+  <footer class="pos-basket__footer">
+    <dl class="pos-basket__totals" aria-live="polite">
+      <div class="pos-basket__total-row">
+        <dt>Gross</dt>
+        <dd>{{ formatMoney(totals().gross) }}</dd>
+      </div>
+      <div class="pos-basket__total-row">
+        <dt>Net</dt>
+        <dd>{{ formatMoney(totals().net) }}</dd>
+      </div>
+      <div class="pos-basket__total-row">
+        <dt>VAT</dt>
+        <dd>{{ formatMoney(totals().vat) }}</dd>
+      </div>
+      <div class="pos-basket__total-row">
+        <dt>Discount</dt>
+        <dd>{{ formatMoney(totals().discount) }}</dd>
+      </div>
+      <div class="pos-basket__total-row pos-basket__total-row--due">
+        <dt>Due</dt>
+        <dd>{{ formatMoney(totals().due) }}</dd>
+      </div>
+    </dl>
+
+    <button
+      type="button"
+      class="pos-basket__clear"
+      [disabled]="!canClear()"
+      (click)="onClear()"
+    >
+      {{ clearLabel() }}
+    </button>
+  </footer>
+</section>