@fayz-ai/pos

The operator surface: one page, touch and keyboard at the same time.

Status: alpha — under active development, APIs will change.

@fayz-ai/admin is the shell for the back office. @fayz-ai/pos is the shell for the shift: the screen a waiter uses at the Saturday rush and a cashier uses with the muscle memory of ten years on a Bematech terminal. Same contract, opposite principles — no rail, no breadcrumb, no deep navigation, no table density. Everything the operator needs is on one page, because leaving that page mid-service is the failure this package exists to prevent.

It is not a restaurant package. A restaurant has tables and tabs that stay open for three hours; a bookstore has a counter and a sale that is born and dies at the register. Both are the same screen with a different PosAppConfig — the screen never reads "mesa", it reads what the config called the thing.

What's inside

• App config — PosAppConfig: the position surface (floor / list / none), the sale cycle (open_tab / immediate), vocabulary, action bar, payment methods
• The one page — PosScreen: position map, live ticket, catalogue, fixed action bar, open-tickets dock
• Ticket engine — ticketReducer, totalsOf: adding an item is an append, so two waiters ringing the same table sum instead of overwriting each other
• Money — formatCents, splitEvenly, serviceChargeCents: cents only, and a split that never loses nor invents a centavo
• Keyboard runtime — createKeymap: bindings declared once, dispatched by the runtime and drawn on the button by the UI
• Theme — @fayz-ai/pos/theme: touch size as a token (≥19mm floor), pastel as category identity, position status on its own accent+icon+word axis

Install

npm install @fayz-ai/pos

Peer deps: react (^18/^19), lucide-react, zustand. Pulls in @fayz-ai/core.

Usage

import { PosScreen } from '@fayz-ai/pos'

<PosScreen
  config={restaurantConfig}
  categories={categories}
  items={items}
  positions={positions}
  terminalName="Caixa 1"
  onAction={handleAction}
/>

The running dogfood app is FayaLabs/chef-pos — a restaurant profile, a real PWA and the E2E suite. It is where a vertical's configuration belongs; this package stays the engine.

Part of the Fayz SDK