Component giao diện

Extension Worker UI (block, action modal/fullscreen, trang render: "worker") chỉ dựng giao diện bằng các element pos-* dưới đây. POS vẽ mỗi element bằng component thật của POS, nên giao diện luôn đồng bộ với POS.

Trang iframe không dùng danh sách này; dùng HTML/React tự do, có thể kèm @pancake-pos/ui để giao diện giống POS.

#Quy tắc chung

• Chỉ dùng element trong danh sách. Thẻ HTML thường (div, span, img, table, script…) và element lạ không được vẽ; extension báo lỗi trong nhật ký của app.
• Text chỉ hiển thị khi nằm trong pos-text, pos-heading, pos-badge, pos-link, pos-button, pos-banner.
• Không có style, className, HTML thô. Màu sắc, khoảng cách, font theo POS.
• URL (href, src) chỉ chấp nhận https://.
• Sự kiện truyền giá trị qua event.detail. Trong JSX dùng thuộc tính onClick, onChange… như component thông thường. Với JS thuần, tên sự kiện là phần sau on viết thường: onPageChange → addEventListener('pagechange', …).
• Giới hạn 2.000 element mỗi extension; pos-table tối đa 500 dòng mỗi lần render (dùng phân trang).
• Thuộc tính dạng mảng/đối tượng (options, columns, rows, pagination) truyền trực tiếp bằng JSX, không cần JSON.stringify.

<pos-stack gap="small">
  <pos-text-field label="Mã phiếu" value={code} onChange={(e) => setCode(e.detail)} />
  <pos-button variant="primary" loading={saving} onClick={save}>Lưu</pos-button>
</pos-stack>

Không dùng framework thì dựng bằng DOM API của runtime (xem Môi trường worker):

let code = '';

const field = document.createElement('pos-text-field');
field.label = 'Mã phiếu';
field.addEventListener('change', (e) => { code = e.detail; });

const button = document.createElement('pos-button');
button.variant = 'primary';
button.textContent = 'Lưu';
button.addEventListener('click', () => save(code));

const stack = document.createElement('pos-stack');
stack.gap = 'small';
stack.append(field, button);
document.body.append(stack);

#Bố cục

#pos-stack

Xếp các phần tử con theo hàng dọc hoặc ngang.

#pos-grid

Lưới cột đều nhau; trên màn hình hẹp tự chuyển về một cột.

#pos-section

Khung có tiêu đề, dùng làm vỏ ngoài của block.

Slot actions: nút hiển thị ở góc phải tiêu đề.

<pos-section heading="Công nợ">
  <pos-button slot="actions" variant="tertiary" onClick={reload}>Tải lại</pos-button>
  <pos-text>...</pos-text>
</pos-section>

#pos-divider

Đường kẻ ngang. Không có thuộc tính.

#Hiển thị

#pos-text

#pos-heading

#pos-badge

Nhãn trạng thái ngắn.

#pos-money

Hiển thị số tiền theo định dạng và đơn vị tiền tệ của shop.

#pos-link

Sự kiện onClick: dùng khi link thực hiện thao tác trong app thay vì mở URL (không đặt href).

#pos-image

POS tải ảnh qua máy chủ trung gian của sandbox: chỉ nhận định dạng ảnh, tối đa 5 MB. Ảnh từ domain chưa khai không hiển thị (chế độ phát triển có cảnh báo).

#Nhập liệu

Thuộc tính chung của mọi ô nhập:

Sự kiện chung: onChange (event.detail là giá trị mới), onBlur.

POS hiện ngay chữ người dùng gõ rồi mới gửi onChange cho app, nên ô không giật dù app đang bận. Nếu app đặt value khác giá trị người dùng vừa nhập (ví dụ chuẩn hoá chữ hoa hoặc xóa ô), POS hiển thị giá trị của app. Nên đặt value ngay trong onChange; đổi value sau một lệnh await có thể ghi đè chữ người dùng đang gõ.

#pos-text-field

#pos-number-field

#pos-select

#pos-checkbox

onChange: event.detail là boolean.

#pos-date-picker

#Phản hồi

#pos-banner

Thông báo nổi bật trong extension.

Sự kiện onDismiss.

#pos-spinner

#Dữ liệu và thao tác

#pos-button

Sự kiện onClick.

#pos-table

Bảng dữ liệu. Ô chỉ chứa giá trị (chuỗi, số); POS định dạng theo format của cột.

type Column = {
  key: string;                       // tên trường trong row
  title: string;
  align?: 'left' | 'center' | 'right';
  width?: number;                    // px
  format?: 'text' | 'number' | 'money' | 'date' | 'datetime';
};

Sự kiện:

• onPageChange: event.detail là { page, pageSize }.
• onRowClick: event.detail là row được bấm.

<pos-table
  columns={[
    { key: 'system_id', title: 'Mã đơn' },
    { key: 'total_price', title: 'Tổng tiền', format: 'money', align: 'right' },
  ]}
  rows={orders}
  rowKey="system_id"
  pagination={{ page, pageSize: 20, total }}
  onPageChange={(e) => setPage(e.detail.page)}
/>

#pos-modal

Hộp thoại mở từ bên trong extension (ví dụ từ một nút trong block).

Slot footer cho các nút cuối hộp thoại. Sự kiện onClose khi người dùng bấm đóng hoặc ra ngoài.

<pos-modal open={open} heading="Xác nhận" onClose={() => setOpen(false)}>
  <pos-text>Đẩy đơn sang ERP?</pos-text>
  <pos-button slot="footer" onClick={() => setOpen(false)}>Huỷ</pos-button>
  <pos-button slot="footer" variant="primary" onClick={push}>Đẩy</pos-button>
</pos-modal>

Action presentation: "modal" đã có sẵn modal của POS; không cần bọc thêm pos-modal.

#Dự kiến bổ sung

pos-page, pos-tabs, pos-filter-bar, pos-chart (POS vẽ biểu đồ, app chỉ truyền dữ liệu), phục vụ trang Worker UI full màn hình.