@shanyucoder/flowgrid 0.1.0

package/templates/project-skeleton/surfaces/common/md/list-toolbar/common-list-toolbar.md

@@ -0,0 +1,81 @@
+# Common list toolbar
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn toolbar action của list page, gồm total readonly button, action chính/phụ, bulk action và per-page control.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## layout
+
+```yaml
+position: below search filter, above table
+style:
+  - Nằm cùng nền list block, không bọc card/nền trắng riêng.
+  - Dùng flex wrap, gap nhỏ, per-page đẩy sang phải khi đủ rộng.
+  - Thiết kế phẳng, không shadow hoặc gradient.
+```
+
+## items
+
+```yaml
+total:
+  text: 合計 {count}
+  variant: complete
+  color: "#48b0f7"
+  behavior: readonly button-style, không clickable
+  badgePolicy: Không bọc số bằng badge bo riêng; số nằm cùng text/nền button.
+  testId: "{module}-total-btn"
+primaryAction:
+  examples:
+    - 新規作成
+    - CSVアップロード
+    - インポート
+  variant: complete
+  icon: required khi action rõ nghĩa và có icon phù hợp
+bulkAction:
+  position: after primary actions
+  disabledWhen: no selection
+  destructive: true nếu là delete
+perPage:
+  position: right
+  labels:
+    before: 表示
+    after: 件 / ページ
+  pageSummary:
+    text: "{currentPage} / {totalPages}"
+    position: cạnh per-page select trong toolbar/header table góc phải
+    note: Đây là số trang hiện tại/tổng số trang, không đặt dưới pagination controls.
+  options:
+    - 20
+    - 40
+    - 80
+    - 100
+  testId: "{module}-per-page-select"
+```
+
+
+## Design intent
+
+**Inherits:** `admin-crud`
+
+**Shell:** #shell: DataPage
+
+**Patterns:**
+
+- #pattern: CRUD
+
+### Zones
+
+| ID | Nhãn | Vị trí | Container | Ghi chú |
+| --- | --- | --- | --- | --- |
+| main | Nội dung chính |  |  |  |
+
+## Legacy evidence

package/templates/project-skeleton/surfaces/common/md/navigation/common-navigation.md

@@ -0,0 +1,70 @@
+# Common navigation and page header
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn sidebar, page title, breadcrumb và route trong admin portal prototype.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## sidebar
+
+```yaml
+behavior:
+  - Parent menu click để open/close child.
+  - Active child route mở parent tương ứng.
+  - Prototype chỉ hiển thị feature đã migrate hoặc đang design.
+routePrefix:
+  legacyAdminPrefix: /admin
+  portalRoute: không dùng `/admin` prefix trong frontend route.
+testIds:
+  navItem: nav-{id}
+```
+
+## pageHeader
+
+```yaml
+title:
+  source: route meta hoặc component page header.
+  testId: "{module}-page-title"
+breadcrumb:
+  default: optional trong prototype; nếu dùng phải có testId theo
+    docs/operational/E2E-TESTIDS.md.
+actions:
+  - Header actions chỉ dùng cho page-level action thật sự.
+  - Nếu legacy/spec yêu cầu group_action trong card/form thì không đưa action
+    lên page header.
+```
+
+## dynamicRoutes
+
+```yaml
+detail: pages/{module}/[id]/index.vue
+edit: pages/{module}/[id]/edit.vue
+child: pages/{module}/[id]/{child}.vue
+```
+
+
+## Design intent
+
+**Inherits:** `admin-crud`
+
+**Shell:** #shell: DataPage
+
+**Patterns:**
+
+- #pattern: CRUD
+
+### Zones
+
+| ID | Nhãn | Vị trí | Container | Ghi chú |
+| --- | --- | --- | --- | --- |
+| main | Nội dung chính |  |  |  |
+
+## Legacy evidence

package/templates/project-skeleton/surfaces/common/md/pagination/common-pagination.md

@@ -0,0 +1,86 @@
+# Common pagination
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn pagination dưới table, dùng page numbers + ellipsis thay vì text generic `Page x of y`.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## layout
+
+```yaml
+position: below table
+alignment: center
+style:
+  - Flat outline buttons, border nhẹ, không shadow.
+  - Active page dùng text/border primary `#4EAAFF` hoặc background primary nhạt.
+  - Disabled previous/next vẫn giữ footprint để layout không nhảy.
+```
+
+## controls
+
+```yaml
+previous:
+  content: icon + text
+  icon: ChevronLeft
+  text: 前へ
+  ariaLabel: 前のページ
+next:
+  content: icon + text
+  icon: ChevronRight
+  text: 次へ
+  ariaLabel: 次のページ
+pageNumbers:
+  window: current page +/- 2
+  firstLast: show first/last when outside window
+  ellipsis: show `...` when gap exists
+```
+
+## behavior
+
+```yaml
+query:
+  - Pagination phải giữ search params hiện tại.
+  - Page change gọi list service/composable, không lọc local-only nếu API
+    contract có pagination.
+perPage:
+  - Per-page select và page summary không nằm trong pagination bar dưới table.
+  - Per-page select nằm ở toolbar/header table góc phải theo
+    `common-list-toolbar`, copy giữ `表示 ... 件 / ページ`.
+  - Đổi per-page reset page về 1.
+```
+
+## testIds
+
+```yaml
+pagination: "{module}-pagination"
+previous: "{module}-pagination-prev-btn"
+next: "{module}-pagination-next-btn"
+pageButton: "{module}-pagination-page-{page}"
+```
+
+
+## Design intent
+
+**Inherits:** `admin-crud`
+
+**Shell:** #shell: DataPage
+
+**Patterns:**
+
+- #pattern: CRUD
+
+### Zones
+
+| ID | Nhãn | Vị trí | Container | Ghi chú |
+| --- | --- | --- | --- | --- |
+| main | Nội dung chính |  |  |  |
+
+## Legacy evidence

package/templates/project-skeleton/surfaces/common/md/search-filter/common-search-filter.md

@@ -0,0 +1,96 @@
+# Common search filter
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn form search/filter cho list page, tách rõ input filter và nút search/clear.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## layout
+
+```yaml
+filterRow:
+  position: top of list block
+  behavior:
+    - Các field filter nằm cùng row khi đủ rộng, tự wrap theo nhóm field khi màn
+      nhỏ.
+    - Không đặt button search/clear cùng hàng với action toolbar như
+      create/delete/import.
+    - Date range dùng start + separator `to` + end trong cùng input group.
+buttonRow:
+  position: below filter row
+  alignment: center
+  buttons:
+    - key: search
+      text: 検索
+      icon: Search
+      variant: outline-primary
+      color: "#4EAAFF"
+      background: "#FFFFFF"
+      minWidth: 170px
+    - key: clear
+      text: クリア
+      icon: RotateCcw
+      variant: outline-secondary
+      color: "#C2C2C2"
+      background: "#FFFFFF"
+      minWidth: 170px
+```
+
+## behavior
+
+```yaml
+submit:
+  - Submit gọi composable/service-like action.
+  - Query filter phải có thể giữ trên URL ở phase wire để pagination/sort không
+    mất điều kiện.
+clear:
+  - Clear reset filter về default.
+  - Clear điều hướng hoặc sync về route base của list nếu URL đang có query.
+  - Clear không xoá dữ liệu list bằng local-only state; phải refresh qua service
+    boundary.
+```
+
+## fieldGuidelines
+
+```yaml
+text: input compact, max width theo domain.
+select: dùng select/combobox common, label rõ.
+dateRange: label `期間`, separator `to`, không tách thành hai field rời rạc nếu
+  legacy/domain đang hiểu là một khoảng.
+```
+
+## testIds
+
+```yaml
+searchForm: "{module}-search-form"
+submitButton: "{module}-search-btn"
+clearButton: "{module}-clear-btn"
+fields: "{module}-{field}-input|select"
+```
+
+
+## Design intent
+
+**Inherits:** `admin-crud`
+
+**Shell:** #shell: DataPage
+
+**Patterns:**
+
+- #pattern: CRUD
+
+### Zones
+
+| ID | Nhãn | Vị trí | Container | Ghi chú |
+| --- | --- | --- | --- | --- |
+| main | Nội dung chính |  |  |  |
+
+## Legacy evidence

package/templates/project-skeleton/surfaces/common/md/status-chip/common-status-chip.md

@@ -0,0 +1,93 @@
+# Common status chip
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn chip/tag trạng thái cho table, form detail và summary block.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## principles
+
+```yaml
+- Status không để text trần nếu cần người dùng nhận biết nhanh.
+- Màu phải có ý nghĩa trạng thái, không dùng để trang trí.
+- Chip luôn có text label, không chỉ dùng màu để đảm bảo accessibility.
+```
+
+## tones
+
+```yaml
+success:
+  useFor:
+    - active
+    - sent
+    - valid
+    - connected
+  color: green
+danger:
+  useFor:
+    - inactive
+    - failed
+    - error
+    - disconnected
+  color: red
+warning:
+  useFor:
+    - pending
+    - sending
+    - attention
+  color: amber
+info:
+  useFor:
+    - draft
+    - system
+    - informational
+  color: blue
+muted:
+  useFor:
+    - disabled
+    - unknown
+    - none
+  color: gray
+```
+
+## layout
+
+```yaml
+shape: rounded-full hoặc rounded-md nhỏ, phẳng, border nhẹ.
+size: compact table chip, không làm row cao.
+maxTextLength: 12-16 ký tự; text dài dùng truncate-tooltip.
+```
+
+## testIds
+
+```yaml
+chip: "{module}-{field}-chip"
+rowChip: "{module}-{field}-{id}-chip"
+```
+
+
+## Design intent
+
+**Inherits:** `admin-crud`
+
+**Shell:** #shell: DataPage
+
+**Patterns:**
+
+- #pattern: CRUD
+
+### Zones
+
+| ID | Nhãn | Vị trí | Container | Ghi chú |
+| --- | --- | --- | --- | --- |
+| main | Nội dung chính |  |  |  |
+
+## Legacy evidence

package/templates/project-skeleton/surfaces/common/md/table-action-column/common-table-action-column.md

@@ -0,0 +1,90 @@
+# Common table action column
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn cột action trong table list: icon-only, fixed width, accessible và không làm row phình.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## layout
+
+```yaml
+headerText: アクション hoặc blank nếu table quá hẹp nhưng phải có aria context.
+width: fixed theo số action, không auto co text.
+alignment: right hoặc center tùy table; mặc định right cho admin list.
+overflow: nowrap
+```
+
+## actions
+
+```yaml
+iconOnly: true
+requiredAttrs:
+  - data-testid
+  - aria-label
+  - title
+order:
+  - view/detail
+  - edit/settings
+  - duplicate/copy
+  - delete/destructive
+```
+
+## variants
+
+```yaml
+view:
+  variant: ghost hoặc outline
+  icon: Eye
+settings:
+  variant: outline
+  icon: Settings
+loginAs:
+  variant: info hoặc outline
+  icon: LogIn
+  note: Nếu có nhiều user login-as, dùng pattern riêng thay vì nhồi text dài vào
+    action column.
+delete:
+  variant: destructive-ghost
+  icon: Trash2
+```
+
+## permissions
+
+```yaml
+hiddenWhenNotAllowed: true
+disabledWhenPending: true
+disabledNeedsTooltip: true nếu người dùng cần biết lý do
+```
+
+## testIds
+
+```yaml
+actionButton: "{module}-{action}-{id}"
+```
+
+
+## Design intent
+
+**Inherits:** `admin-crud`
+
+**Shell:** #shell: DataPage
+
+**Patterns:**
+
+- #pattern: CRUD
+
+### Zones
+
+| ID | Nhãn | Vị trí | Container | Ghi chú |
+| --- | --- | --- | --- | --- |
+| main | Nội dung chính |  |  |  |
+
+## Legacy evidence

package/templates/project-skeleton/surfaces/common/patterns/breadcrumb-flow.md

@@ -0,0 +1,83 @@
+# Common Breadcrumb Flow
+
+Applies to all dashboard pages with sidebar navigation. Read in `/grill-bqa`, `/spec`, `/grill-docs`.
+
+## Rule
+
+Every page **must** show breadcrumb aligned with **left-menu parent → child** hierarchy and **in-page action navigation** (list → detail → edit → …).
+
+Breadcrumb is **not optional** on admin/list/detail/edit/create flows.
+
+## Hierarchy model
+
+```text
+Sidebar parent (menu group)
+  → Sidebar child (menu item) OR list page
+    → Action child page (detail, edit, create, settings, …)
+      → Further nested step if spec defines it
+```
+
+### Example — hotel admin
+
+```text
+ホテル管理 (sidebar parent)
+  → ホテル一覧 (list — menu child or list route)
+    → Hotel detail (row action / view)
+      → Hotel edit (action from detail)
+```
+
+Rendered breadcrumb (conceptual):
+
+```text
+ホテル管理 > ホテル一覧
+ホテル管理 > ホテル一覧 > {hotel name}
+ホテル管理 > ホテル一覧 > {hotel name} > 編集
+```
+
+Use **route labels from spec** (`ui.screens`, menu copy) — do not invent labels in code without spec.
+
+## Mapping spec → breadcrumb
+
+| Page type | Breadcrumb depth | Source in spec |
+|-----------|------------------|----------------|
+| List | Parent > List | Sidebar + `ui.routes` / page title |
+| Create | Parent > List > Create | Toolbar create action label |
+| Detail | Parent > List > Entity name | Row view action |
+| Edit | Parent > List > Entity name > Edit | Detail edit action |
+| Settings / sub-flow | Parent > List > … > Step | `ui.screens` action chain |
+
+**Create** is not a sidebar child — breadcrumb goes through **list** (from toolbar action), same as legacy portal pattern.
+
+## UI requirements
+
+- Breadcrumb sits in page header area (dashboard layout), above or beside page title per common list/detail shell.
+- Each segment except the last is a **link** back to that level (list → detail → edit: each prior segment navigates correctly).
+- Last segment is current page (plain text, not link).
+- Entity name segment uses display field from data (`name`, `title`) when on detail/edit.
+- i18n: labels match sidebar / spec copy (JP admin terms when legacy applies).
+
+## Grill BQA — questions
+
+1. Sidebar parent label và child label (menu copy)?
+2. Create page breadcrumb label (e.g. 新規作成)?
+3. Detail/edit segment: entity field hiển thị (`name`, `code`)?
+4. Sub-flows (crawl setting, import): chèn level nào?
+
+## Grill Dev — notes
+
+- `ui.routes` chain: list `/hotels`, detail `/hotels/[id]`, edit `/hotels/[id]/edit`.
+- Breadcrumb data often from route meta + loaded entity; `#wire-only` if menu API deferred.
+- Do not flatten menu hierarchy into flat titles.
+
+## Related common specs
+
+- ``docs/features/` stub · hubs`
+- ``docs/features/` stub · hubs` (if present)
+- `common-ui-spec.md` — flat design, header area
+
+## Anti-patterns
+
+- List page without breadcrumb when sidebar has parent group
+- Detail/edit only showing page title, no trail
+- Breadcrumb labels unrelated to sidebar menu
+- Create as fake sidebar root — must go through list

package/templates/project-skeleton/surfaces/common/patterns/delete-flow.md

@@ -0,0 +1,30 @@
+# Common delete flow
+
+Destructive actions **must** block the user until acknowledged. Applies to row delete and bulk delete.
+
+## Rule
+
+| Step | UI |
+|------|-----|
+| Before delete | Blocking confirm dialog (clear object + impact) |
+| After success | Blocking result dialog with success message — user must OK |
+| After failure | Blocking result dialog with error — user must OK |
+
+## Not allowed for delete
+
+- Toast-only feedback
+- Inline alert under title as sole confirmation
+- Non-blocking banner
+
+Bulk delete uses the same pattern; only copy and count differ.
+
+## Spec / grill
+
+- BQA: confirm copy, button labels, post-delete navigation (stay vs refresh list).
+- Dev: API action, `#wire-only` if endpoint deferred; tag `#tech-debt:{id}` if contract open.
+
+## Related
+
+- ``docs/features/` stub · hubs`
+- ``docs/features/` stub · hubs` (non-delete toasts)
+- `common-ui-spec.md`

package/templates/project-skeleton/surfaces/common/patterns/ui-spec.md

@@ -0,0 +1,15 @@
+# Common UI Spec (Portal)
+
+**CMN SSOT:** `surfaces/common/md/` + `common-*.bundle.yaml` below — promote via `gen-common`, do not paste into every `W-*` YAML.
+
+Follow `base-docs Code / `--id`` before copying legacy UI ad hoc.
+
+- **Design registry:** `registries/design.registry.json` when present in the FE checkout; list default `#shell: DataListPage`. Promotion: `platform/toolchain/DESIGN-REGISTRY-PROMOTION.md`.
+- If legacy violates project common UI, design to common global and note `#legacy-global-ui-violation` with legacy evidence.
+- Patterns: list page, search filter, toolbar, pagination, data table, table action column, buttons, status chip, form validation, feedback/alert, confirm dialog, CSV import, navigation, flat design.
+- Business buttons outside table actions: icon + text. Table row actions: icon-only per `common-table-action-column`. Paginator: page numbers/ellipsis; prev/next icon + Japanese text.
+- Flat design: no heavy gradient/shadow or nested card/dialog layers unless common requires it.
+- Prefer inline alert under page title/header on flat background. Alert dialog only when the page scrolls and inline alert would be hidden; non-action alert dialog top-right, not center/bottom legacy.
+- Action dialogs (confirm/delete/overwrite/cancel): centered modal per common confirm dialog.
+- Terminology: inline alert persists until user action; toast auto-dismiss ~5s with stack/animation; action modal blocks background.
+- Never stack modals; use page/step/inline section or close current modal before opening a new flow.

package/templates/project-skeleton/surfaces/common/yaml/breadcrumb-flow/common-breadcrumb-flow.bundle.yaml

@@ -0,0 +1,60 @@
+schema: portal-feature-bundle/v1
+id: common-breadcrumb-flow
+title: Common breadcrumb flow
+status: draft
+owner: portal-team
+summary: Mọi dashboard page có breadcrumb khớp menu cha-con và action chain; breadcrumb trên page title.
+specOrigin: legacy
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+spec:
+  principles:
+    - Breadcrumb bắt buộc trên list, detail, edit, create khi có sidebar parent.
+    - Thứ tự header — breadcrumb rồi page title rồi content.
+    - Create không phải menu con — trail đi qua list (toolbar create).
+  references:
+    - .cursor/extracts/common-breadcrumb-flow.md
+    - docs/features/common/common-list-page.spec.yaml
+  hierarchy:
+    - sidebarParent
+    - sidebarChildOrList
+    - actionPages
+  examples:
+    hotelList: ホテル管理 > ホテル一覧
+    hotelDetail: ホテル管理 > ホテル一覧 > {name}
+    hotelEdit: ホテル管理 > ホテル一覧 > {name} > 編集
+    hotelCreate: ホテル管理 > ホテル一覧 > 新規作成
+  grill:
+    bqa: labels, entity display field, create label
+    dev: ui.routes chain, route meta, wire-only menu API
+legacy:
+  legacyRef:
+    module: common/common
+    function: common-breadcrumb-flow
+    slice: slices.common-breadcrumb-flow
+  behaviors: []
+  fields: []
+  ui: []
+  evidence: []
+  refs: {}
+design:
+  inherits: admin-crud
+  shell:
+    tag: "#shell: DataPage"
+    overrideCommonPattern: false
+  patterns:
+    - "#pattern: CRUD"
+  zones:
+    - id: main
+      label: Nội dung chính
+  behavior: {}
+  actions: []
+review:
+  summary: Mọi dashboard page có breadcrumb khớp menu cha-con và action chain; breadcrumb trên page title.
+  layoutNotes: []
+_meta:
+  generatedBy: archived-legacy-converter
+  sourceRevision: null