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);

#Màn hình chuẩn

POS đặt element theo layout chung của các trang POS; app chỉ chọn đúng element và thứ tự, không chỉnh màu hay khoảng cách.

• Trang app.page: pos-page là khung trang của POS. heading và description nằm ở dòng tiêu đề trên cùng, slot actions ở bên phải cạnh nút chính (pos.page.setPrimaryAction); nội dung xếp dọc trên nền xám.
• Khối: pos-section đặt thẳng trong pos-page là thẻ trắng; pos-section lồng trong pos-section là nhóm phẳng; trong block và modal, pos-section là thẻ trắng viền mảnh. pos-table, pos-chart đặt thẳng trong pos-page tự nằm trong thẻ trắng.
• Số liệu: pos-stat trong pos-grid 3–5 cột; không ghép pos-section với pos-heading để làm ô số liệu.
• Lọc: gom ô lọc vào một pos-filter-bar ở đầu trang hoặc đầu khối; khoảng ngày dùng pos-date-range. Lọc theo trạng thái dùng pos-tabs có badge: chip có số đếm như thanh trạng thái của các trang danh sách POS.
• Nút: nút công cụ (tải lại, lọc, cài đặt) là nút chỉ có icon kèm tooltip; nhiều thao tác phụ thì gom vào pos-menu-button. Trạng thái trong bảng dùng cột format: 'badge'; chi tiết một dòng mở trong pos-drawer hoặc pos-modal với pos-description-list, pos-timeline.
• Không lặp tiêu đề trang trong nội dung, không dùng emoji hay ký tự trang trí trong nhãn (dùng tone của pos-stat, pos-badge), không lồng pos-section quá hai cấp, không bọc từng element trong một pos-section riêng.
• Bỏ khỏi biểu đồ và bảng các dòng toàn số 0 hoặc không có dữ liệu; hiện tên thay vì mã (tra tên qua Open API).

#Trang báo cáo

<pos-page description="Đối chiếu thời gian giao thực tế với SLA cam kết của ĐVVC" width="full">
  <pos-button slot="actions" icon="download" onClick={exportCsv}>Xuất</pos-button>
  <pos-filter-bar>
    <pos-date-range label="Ngày tạo đơn" value={range} onChange={(e) => e.detail && setRange(e.detail)} />
    <pos-button icon="refresh" tooltip="Tải lại" onClick={load} />
  </pos-filter-bar>
  <pos-grid columns={4}>
    <pos-stat label="Tỷ lệ đúng hạn" value={58.3} format="percent" help="12 đơn đã giao" />
    <pos-stat label="Đúng hạn" value={7} tone="success" selected={state === 'on_time'} onClick={() => setState('on_time')} />
    <pos-stat label="Giao trễ" value={5} tone="critical" selected={state === 'late'} onClick={() => setState('late')} />
    <pos-stat label="Phí ship" value={2450000} format="money" />
  </pos-grid>
  <pos-section heading="Theo ĐVVC">
    <pos-chart type="bar" xKey="carrier" data={byCarrier} series={[{ key: 'rate', label: 'Tỷ lệ đúng hạn (%)' }]} onSelect={(e) => setCarrier(e.detail.x)} />
  </pos-section>
</pos-page>

#Trang danh sách

<pos-page width="full">
  <pos-button slot="actions" icon="upload" onClick={importFile}>Nhập</pos-button>
  <pos-menu-button slot="actions" items={[{ id: 'csv', label: 'Xuất CSV' }]} onSelect={exportAs} />
  <pos-section>
    <pos-filter-bar>
      <pos-text-field label="Tìm mã đơn" value={search} onChange={(e) => setSearch(e.detail)} />
      <pos-select label="Kho" options={warehouses} value={warehouse} onChange={(e) => setWarehouse(e.detail)} />
    </pos-filter-bar>
    <pos-tabs tabs={[{ id: 'all', label: 'Tất cả', badge: 169 }, { id: 'late', label: 'Giao trễ', badge: 12 }]} selected={status} onChange={(e) => setStatus(e.detail)}>
      <pos-table
        columns={[
          { key: 'code', title: 'Mã đơn', format: 'link' },
          { key: 'customer', title: 'Khách hàng', subtitle: 'phone' },
          { key: 'state', title: 'SLA', format: 'badge', tones: { 'Trễ': 'critical', 'Đúng hạn': 'success' } },
          { key: 'fee', title: 'Phí ship', format: 'money', align: 'right', sortable: true },
        ]}
        rows={rows}
        sort={sort}
        pagination={{ page, pageSize: 30, total }}
        onSortChange={(e) => setSort(e.detail)}
        onPageChange={(e) => setPage(e.detail.page)}
        onCellClick={(e) => setDetail(e.detail.row)}
      />
    </pos-tabs>
  </pos-section>
</pos-page>

<pos-drawer open={!!detail} heading={detail?.code} onClose={() => setDetail(null)}>
  <pos-description-list items={[{ label: 'ĐVVC', value: detail?.carrier }, { label: 'Phí ship', value: detail?.fee, format: 'money' }]} />
  <pos-timeline items={detail?.events ?? []} />
</pos-drawer>

Nút chính của trang (ví dụ "Đồng bộ") đặt bằng pos.page.setPrimaryAction, luôn nằm cuối dòng tiêu đề. Xuất file (CSV, Excel) bằng pos.download.

#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; ô hẹp hơn 180 px thì tự xuống hàng (màn hình hẹp còn một cột).

#pos-section

Khối có tiêu đề. Đặt thẳng trong pos-page là thẻ trắng; lồng trong pos-section khác là nhóm phẳng; trong block và modal là thẻ trắng viền mảnh (xem Màn hình chuẩn).

Slot actions: pos-button, pos-link, pos-menu-button 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

Cỡ chữ: 1 20 px (bằng tiêu đề trang), 2 18 px, 3 16 px (bằng tiêu đề khối), 4 14 px.

#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).

#pos-description-list

Cặp nhãn – giá trị như khối thông tin đơn của POS (nhãn xám bên trái, giá trị bên phải); dùng trong modal, panel, khối chi tiết.

type Item = {
  label: string;
  value: string | number | null;     // null hoặc rỗng hiện "—"
  format?: 'text' | 'number' | 'money' | 'percent' | 'date' | 'datetime' | 'badge';
  tone?: 'default' | 'info' | 'success' | 'warning' | 'critical';  // màu khi format là badge
};

<pos-description-list columns={2} items={[
  { label: 'ĐVVC', value: 'GHN' },
  { label: 'Phí ship', value: 25000, format: 'money' },
  { label: 'SLA', value: 'Trễ 2 ngày', format: 'badge', tone: 'critical' },
]} />

#pos-timeline

Dòng thời gian: hành trình đơn, lịch sử thay đổi.

#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

#pos-date-range

Khoảng ngày như bộ chọn thời gian của trang Thống kê, có sẵn lựa chọn nhanh: Hôm nay, Hôm qua, 7 ngày qua, 30 ngày qua, Đầu tuần đến nay, Đầu tháng đến nay, Tháng trước.

Cùng các thuộc tính chung của ô nhập (label, disabled, required, error, help). Sự kiện onChange: event.detail là { from, to } hoặc null khi xoá.

<pos-date-range label="Ngày tạo đơn" value={range} onChange={(e) => e.detail && setRange(e.detail)} />

#Phản hồi

#pos-banner

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

Sự kiện onDismiss.

#pos-spinner

#pos-progress

Thanh tiến độ cho tỷ lệ (đúng hạn, hoàn thành chỉ tiêu).

#pos-empty

Trạng thái trống như các trang POS: hình minh hoạ nhỏ, tiêu đề, mô tả và nút hành động.

Slot actions cho pos-button, pos-link.

<pos-empty heading="Chưa có đơn trễ" description="Đổi khoảng ngày để xem thêm">
  <pos-button slot="actions" onClick={reset}>Đặt lại bộ lọc</pos-button>
</pos-empty>

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

#pos-button

Sự kiện onClick.

Icon (bộ icon của POS): plus, edit, delete, download, upload, refresh, filter, search, settings, print, copy, link, external, view, send, check, close, more, calendar, info, warning.

<pos-button icon="download" onClick={exportCsv}>Xuất</pos-button>
<pos-button icon="refresh" tooltip="Tải lại" onClick={reload} />

#pos-menu-button

Nút mở danh sách thao tác. Không có label thì là nút "⋯".

Sự kiện onSelect: event.detail là id của mục được bấm.

<pos-menu-button slot="actions" items={[{ id: 'csv', label: 'Xuất CSV' }, { id: 'delete', label: 'Xoá', danger: true }]} onSelect={(e) => run(e.detail)} />

#pos-table

Bảng dữ liệu như bảng danh sách của POS. Ô chỉ chứa giá trị (chuỗi, số); cách hiển thị (định dạng, badge, link, dòng phụ) khai ở 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' | 'percent' | 'date' | 'datetime' | 'badge' | 'link';
  tones?: Record<string, 'default' | 'info' | 'success' | 'warning' | 'critical'>;  // màu badge theo giá trị ô
  subtitle?: string;                 // trường hiện thành dòng phụ màu xám (ví dụ mã SKU dưới tên)
  sortable?: boolean;
  fixed?: 'left' | 'right';          // cố định cột khi cuộn ngang
  ellipsis?: boolean;                // cắt chữ dài trên một dòng
};

• percent: số là phần trăm (12.5 → 12,5%). badge: giá trị ô thành nhãn màu theo tones. link: chữ dạng link, bấm phát onCellClick.

Sự kiện:

• onPageChange: event.detail là { page, pageSize }.
• onRowClick: event.detail là row được bấm.
• onSortChange: event.detail là { key, order }, hoặc null khi bỏ sắp xếp.
• onSelectionChange: event.detail là mảng khoá các dòng đang chọn (giữ cả dòng ở trang khác).
• onCellClick: event.detail là { key, row } khi bấm ô format: 'link'.

<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-table
  columns={[
    { key: 'name', title: 'Sản phẩm', subtitle: 'sku', sortable: true, fixed: 'left' },
    { key: 'state', title: 'SLA', format: 'badge', tones: { 'Trễ': 'critical', 'Đúng hạn': 'success' } },
    { key: 'code', title: 'Mã đơn', format: 'link' },
    { key: 'rate', title: 'Tỷ lệ', format: 'percent', align: 'right' },
  ]}
  rows={rows}
  sort={sort}
  summary={{ name: 'Tổng', rate: 62.5 }}
  selectable
  selected={selected}
  onSortChange={(e) => setSort(e.detail)}
  onSelectionChange={(e) => setSelected(e.detail)}
  onCellClick={(e) => openOrder(e.detail.row)}
/>

#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.

#pos-drawer

Panel trượt từ cạnh phải, như "Cài đặt" của trang Thống kê: xem chi tiết một dòng mà không rời danh sách.

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

#Trang Worker UI

Các element dưới đây dùng để dựng trang render: "worker" và màn báo cáo (xem Extension point › app.page); dùng được cả trong block và modal.

#pos-page

Khung trang. Trên trang app.page, heading và description hiện ở dòng tiêu đề của POS (không có heading thì dùng tiêu đề đặt bằng pos.page.setTitle hoặc title của extension), slot actions nằm bên phải cạnh nút chính, nội dung xếp dọc trên nền xám. Trong block và modal, pos-page là khối có tiêu đề.

Slot actions cho pos-button, pos-link, pos-menu-button; trên trang app.page nằm trước nút chính.

#pos-tabs

Thanh chọn dạng chip có số đếm (badge), như thanh trạng thái của các trang danh sách POS. App giữ tab đang chọn và vẽ nội dung của tab đó làm element con.

Sự kiện onChange: event.detail là id của tab được chọn. POS đổi tab ngay khi bấm, không chờ app.

#pos-filter-bar

Hàng bộ lọc phía trên bảng hoặc biểu đồ. Element con: pos-text-field, pos-number-field, pos-select, pos-checkbox, pos-date-picker, pos-date-range, pos-button, pos-menu-button. Ô nhập vẽ gọn một hàng, label thành chữ gợi ý khi không có placeholder; hết chỗ thì xuống dòng.

<pos-filter-bar>
  <pos-text-field label="Tìm mã đơn" value={search} onChange={(e) => setSearch(e.detail)} />
  <pos-select label="Nguồn đơn" options={sources} value={source} onChange={(e) => setSource(e.detail)} />
  <pos-date-picker label="Từ ngày" value={from} onChange={(e) => setFrom(e.detail)} />
  <pos-button onClick={reset}>Đặt lại</pos-button>
</pos-filter-bar>

#pos-chart

Biểu đồ do POS vẽ; app chỉ truyền dữ liệu. Màu theo bảng màu của POS.

• Sự kiện onSelect: có nghe thì bấm được vào cột, lát hoặc điểm; event.detail là { x, series }: x là giá trị xKey được bấm, series là key của cột được bấm (null với line, area, pie).
• format: 'percent': giá trị là phần trăm; mọi chuỗi đều là phần trăm thì trục số ghi thêm "%". Các chuỗi dùng chung một trục số, nên chỉ kết hợp những chuỗi cùng cỡ giá trị (số đơn với số đơn trễ, không phải số đơn với doanh thu).
• Nhãn trục ngang dài được cắt cho vừa chỗ, rê chuột để xem đủ; nhiều nhóm đến mức mỗi nhóm quá hẹp thì nhãn xoay nghiêng. Nên bỏ các nhóm toàn số 0 và gom nhóm nhỏ vào "Khác" trước khi truyền data.

<pos-chart
  type="bar"
  xKey="day"
  data={[{ day: '01/10', revenue: 12500000, cost: 8000000 }, { day: '02/10', revenue: 9800000, cost: 7100000 }]}
  series={[{ key: 'revenue', label: 'Doanh thu', format: 'money' }, { key: 'cost', label: 'Giá vốn', format: 'money' }]}
/>

#pos-stat

Ô số liệu cho màn báo cáo: nhãn, giá trị lớn, dòng phụ và mức thay đổi so với kỳ trước. Đặt nhiều ô trong pos-grid. Trên nền trang là thẻ trắng; trong khối trắng (pos-section, modal, block) là ô nền xám nhạt.

Sự kiện onClick: có nghe thì thẻ bấm được (cả bằng phím Enter), ví dụ bấm "Giao trễ" để lọc bảng bên dưới.

<pos-grid columns={4}>
  <pos-stat label="Tỷ lệ đúng hạn" value={58.3} format="percent" help="12 đơn đã giao" change={4.2} changeLabel="so với tuần trước" />
  <pos-stat label="Giao trễ" value={5} tone="critical" change={12.5} inverse selected={filter === 'late'} onClick={() => setFilter('late')} />
  <pos-stat label="Phí hoàn" value={2450000} format="money" />
</pos-grid>