@lucasvu/scope-ui 0.0.5 → 0.0.7

package/AI_SETUP.md

@@ -5,13 +5,19 @@ Mục tiêu của file này là để AI của project dùng `@lucasvu/scope-ui`
 Nếu project consumer đã cài package, cách nhanh nhất là chạy:
 
 ```bash
-npx scope-ui-init --list-themes
+npm install @lucasvu/scope-ui
 npx scope-ui-init --theme forest
 ```
 
-Nếu chưa cài `@lucasvu/scope-ui`, lệnh trên sẽ báo `E404` vì npm sẽ cố tải package tên `scope-ui-init`.
+Nếu chưa biết chọn preset nào thì chạy thêm:
 
-CLI này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` theo đúng convention bên dưới. Nếu không truyền `--theme`, preset mặc định là `ocean`.
+```bash
+npx scope-ui-init --list-themes
+```
+
+Nếu chưa cài `@lucasvu/scope-ui`, các lệnh trên sẽ báo `E404` vì npm sẽ cố tải package tên `scope-ui-init`.
+
+CLI này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` theo đúng convention bên dưới. `AGENTS.md` sẽ chứa luôn workflow step-by-step để agent dựng UI đúng thứ tự. Nếu không truyền `--theme`, preset mặc định là `ocean`.
 
 ## 1. Import style đúng thứ tự
 
@@ -37,6 +43,8 @@ npx scope-ui-init --theme graphite
 
 File generate ra sẽ là source of truth cho palette, surface, radius và shadow của project. Agent phải bám vào file này thay vì tự nghĩ màu mới.
 
+`AGENTS.md` sẽ có thêm block brief dạng YAML để agent điền các giá trị như `routeUrl`, `sidebarItems`, `pageTitle`, `filters`, `fields`, `tableColumns` trước khi bắt đầu viết JSX.
+
 ```css
 :root {
   --tw-primary: 12 88% 56%;
@@ -67,8 +75,10 @@ Always:
 - import the project theme override file after the package stylesheet
 - use root exports from `@lucasvu/scope-ui`
 - stay inside the approved preset declared by `src/styles/ui-theme.css`
+- follow the step-by-step UI build workflow from `AGENTS.md` before writing JSX
+- fill the screen brief first: `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, and the page-specific schema
 - read `uiAiManifest` to choose the right component by intent
-- read `uiThemeContract` before changing colors, surfaces, borders, or shadows
+- read `uiScreenBlueprint` and `uiThemeContract` before changing layout, colors, surfaces, borders, or shadows
 
 Do not:
 - import from `MainFe` unless the task explicitly targets a legacy screen
@@ -93,10 +103,11 @@ Component choice:
 Trong code, AI có thể đọc trực tiếp:
 
 ```ts
-import { uiAiManifest, uiThemeContract, uiThemePresets, uiProjectAiRules } from '@lucasvu/scope-ui'
+import { uiAiManifest, uiScreenBlueprint, uiThemeContract, uiThemePresets, uiProjectAiRules } from '@lucasvu/scope-ui'
 ```
 
 - `uiAiManifest`: chọn component theo intent
+- `uiScreenBlueprint`: brief input và khung layout chuẩn cho `list | form | detail | dashboard`
 - `uiThemeContract`: biết override token nào và override ở đâu
 - `uiThemePresets`: danh sách preset được duyệt để nhiều project dùng chung một visual language
 - `uiProjectAiRules`: rule ngắn gọn để inject vào agent của project

package/README.md

@@ -19,13 +19,19 @@ import '@lucasvu/scope-ui/styles.css';
 3. Nếu muốn bootstrap rule/theme cho AI trong project consumer:
 
 ```bash
-npx scope-ui-init --list-themes
+npm install @lucasvu/scope-ui
 npx scope-ui-init --theme sunset
 ```
 
-Lưu ý: lệnh này chỉ chạy được sau khi project đã cài `@lucasvu/scope-ui`. Nếu chưa cài package, `npx` sẽ đi tìm một package riêng tên `scope-ui-init` trên npm và báo `E404`.
+Nếu chưa biết chọn preset nào thì mới cần xem danh sách trước:
 
-Lệnh này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` trong repo hiện tại theo preset đã chọn. Nếu không truyền `--theme`, preset mặc định là `ocean`. Dùng `--force` nếu muốn overwrite file đã tồn tại.
+```bash
+npx scope-ui-init --list-themes
+```
+
+Lưu ý: các lệnh này chỉ chạy được sau khi project đã cài `@lucasvu/scope-ui`. Nếu chưa cài package, `npx` sẽ đi tìm một package riêng tên `scope-ui-init` trên npm và báo `E404`.
+
+Lệnh này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` trong repo hiện tại theo preset đã chọn. `AGENTS.md` giờ có thêm playbook step-by-step để agent dựng màn hình đúng layout/component/theme chung. Nếu không truyền `--theme`, preset mặc định là `ocean`. Dùng `--force` nếu muốn overwrite file đã tồn tại.
 
 4. Dùng component:
 
@@ -104,17 +110,22 @@ Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng
 
 - Import CSS global một lần: `@lucasvu/scope-ui/styles.css`
 - Import file theme override của project ngay sau package CSS, ví dụ `./styles/ui-theme.css`
+- Cài package trước khi bootstrap: `npm install @lucasvu/scope-ui`
 - Chạy `npx scope-ui-init --list-themes` để xem preset được duyệt
 - Chạy `npx scope-ui-init --theme <preset>` ở project consumer sau khi đã cài `@lucasvu/scope-ui` để tạo `AGENTS.md` và `src/styles/ui-theme.css`
 - Khoá project vào một preset thay vì tự bịa palette mới cho từng page
+- Để agent đọc luôn playbook trong `AGENTS.md` để đi đúng thứ tự: điền brief, kiểm tra import, chọn component, dựng layout, rồi mới tinh chỉnh token
+- Buộc agent điền screen brief trước khi code: `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, `filters`, `fields`, `tableColumns`
+- `AGENTS.md` mới sẽ có sẵn block brief dạng YAML để agent hoặc dev điền trực tiếp trước khi code
 - Chỉ dùng các component canonical ở root package; tránh `MainFe` nếu không phải legacy screen
 - Cho agent đọc `uiAiManifest` để biết component nào dùng cho intent nào, props quan trọng là gì, và khi nào không nên dùng
-- Cho agent đọc `uiThemeContract` và `uiThemePresets` để biết danh sách preset và token nào được phép override
+- Cho agent đọc `uiScreenBlueprint`, `uiThemeContract` và `uiThemePresets` để biết screen recipe, preset và token nào được phép override
 
 ```ts
 import {
   uiAiManifest,
   uiProjectAiRules,
+  uiScreenBlueprint,
   uiThemeContract,
   uiThemePresets,
 } from '@lucasvu/scope-ui';
@@ -122,6 +133,8 @@ import {
 
 `uiAiManifest` mô tả luật chọn component theo intent như: text input, textarea, fixed select, searchable select, async combobox, multi select, data table, alert, card và field wrapper.
 
+`uiScreenBlueprint` mô tả input brief bắt buộc cho từng màn hình như `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, `filters`, `fields`, `tableColumns` và frame recipe cho `list | form | detail | dashboard`.
+
 `uiThemeContract` mô tả token màu, surface, border, shadow, radius, gradient và selector theme (`:root`, `.dark`, `[data-ui-theme='*']`) để AI không hardcode màu sai chỗ.
 
 `uiThemePresets` là danh sách preset được duyệt sẵn để nhiều project có thể chọn cùng một visual language mà không cần tự dựng theme từ đầu.
@@ -135,6 +148,7 @@ Nên để toàn bộ override theme của project vào một file riêng, ví d
 Cách nhanh nhất là generate file này từ preset:
 
 ```bash
+npm install @lucasvu/scope-ui
 npx scope-ui-init --list-themes
 npx scope-ui-init --theme ocean
 ```

package/bin/scope-ui-init.mjs

@@ -281,8 +281,12 @@ Usage:
   npx scope-ui-init
     Run this after @lucasvu/scope-ui has been installed in the consumer project.
 
-  npx scope-ui-init --list-themes
   npx scope-ui-init --theme sunset
+    Fast path when you already know the preset you want.
+
+  npx scope-ui-init --list-themes
+    Optional: inspect approved presets before choosing one.
+
   npx scope-ui-init --theme forest --force
   npx scope-ui-init --agents-file AGENTS.md --theme-file src/styles/ui-theme.css
 
@@ -338,13 +342,94 @@ This repo is locked to the \`${themePreset.label}\` theme preset (\`${themePrese
 Primary references:
 - \`node_modules/${PACKAGE_NAME}/README.md\`
 - \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`
+- \`uiScreenBlueprint\` and \`uiAiManifest\` from \`${PACKAGE_NAME}\`
 - \`${themeFile}\`
 
 Theme preset summary:
 - ${themePreset.description}
 - Recommended for: ${themePreset.recommendedFor.join(', ')}
 
-Always:
+## Required Flow
+
+When asked to build or edit a screen, follow these steps in order:
+
+1. Read \`${themeFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`, and the exported \`uiScreenBlueprint\` contract before generating UI.
+2. Fill the screen brief first. If route url, sidebar items, active sidebar item, title, actions, filters, fields, or columns are missing, ask for them or leave clear TODO placeholders instead of inventing them.
+3. Verify the app entry imports \`${PACKAGE_NAME}/styles.css\` first and the project theme file right after it.
+4. Identify the page kind (\`list | form | detail | dashboard\`), then map each block to canonical components from \`uiAiManifest\` before writing JSX.
+5. Build the shell in this exact order: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> top actions -> page body cards/grids.
+6. For list pages, build filters first and then the \`DataTable\`. For form pages, build section cards and fields. For detail pages, build summary cards and related tables. For dashboard pages, build stat cards and then supporting cards/tables.
+7. Keep all colors, radius, surface, and shadow decisions inside \`${themeFile}\`. If the preset is insufficient, update tokens there instead of styling one page ad hoc.
+8. Before finishing, run the output checklist in this file.
+
+## Screen Brief
+
+Complete this brief before writing JSX:
+
+\`\`\`yaml
+pageKind: list | form | detail | dashboard
+routeUrl:
+sidebarItems:
+  - id:
+    title:
+    href:
+activeSidebarItemId:
+breadcrumbs:
+  - label:
+    href:
+    current:
+pageTitle:
+pageSubtitle:
+primaryAction:
+  label:
+  href:
+secondaryActions:
+  - label:
+    href:
+summaryStats:
+  - label:
+    value:
+    delta:
+    trend:
+filters:
+  - type:
+    label:
+    key:
+tableColumns:
+  - key:
+    title:
+    type:
+rowActions:
+  - label:
+    key:
+formSections:
+  - title:
+    fields: []
+fields:
+  - name:
+    type:
+    label:
+    required:
+    helperText:
+detailSections:
+  - title:
+    type:
+emptyState:
+  title:
+  description:
+  actionLabel:
+permissions: []
+\`\`\`
+
+## Page Frame Recipes
+
+- \`list\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> header actions -> optional stats -> filter \`Card\` -> \`DataTable\` \`Card\`
+- \`form\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> primary/cancel actions -> sectioned form \`Card\` blocks -> bottom action row
+- \`detail\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> status/actions -> summary metadata \`Card\` -> detail \`Card\` blocks -> related \`DataTable\`
+- \`dashboard\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> header actions -> \`Stat\` row -> filters -> insight \`Card\` blocks and \`DataTable\`
+
+## Hard Rules
+
 - import \`${PACKAGE_NAME}/styles.css\` once at the app entry
 - import the project theme override file after the package stylesheet
 - use root exports from \`${PACKAGE_NAME}\`
@@ -360,7 +445,8 @@ Do not:
 - restyle individual pages if the preset tokens can solve it globally
 - create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
 
-Component choice:
+## Component Choice
+
 - \`Input\` for short text
 - \`Textarea\` for multiline text
 - \`Select\` for small fixed options
@@ -370,6 +456,18 @@ Component choice:
 - \`MultiSelect\` for multi-pick
 - \`Field\` only for custom controls or grouped content
 - \`DataTable\` for tabular records
+
+## Output Check
+
+Before finishing, confirm all of these are true:
+
+- The screen brief is complete or unresolved values are clearly marked as TODO.
+- The shell contains \`Sidebar\`, \`Breadcrumb\`, and \`PageTitle\` in the correct order.
+- The chosen components match the page kind and the brief.
+- No \`MainFe\` imports were used.
+- No hardcoded brand colors were added in page components.
+- Theme decisions live in \`${themeFile}\`, not in ad hoc JSX styling.
+- Spacing, card structure, and actions are consistent with the shared preset.
 `
 }
 

package/dist/index.cjs

@@ -6647,6 +6647,7 @@ var uiAiManifest = {
   rules: [
     "Import the stylesheet once at the app entry before rendering any component.",
     "If the project declares an approved theme preset in AGENTS.md or ui-theme.css, stay inside that preset and do not invent a second palette.",
+    "Collect the screen brief first: route url, sidebar items, active sidebar item, page title, actions, and the page-specific content schema.",
     "Prefer the canonical component for each intent instead of mixing legacy MainFe components.",
     "Use Input/Textarea/Select label props directly for simple fields; use Field only to wrap custom controls or grouped content.",
     "Use Select for small fixed option lists, SearchableSelect for larger local lists, Combobox for type-and-pick flows, and AsyncCombobox for remote search.",
@@ -6862,6 +6863,213 @@ var uiAiManifest = {
   ]
 };
 
+// src/screen-blueprint.ts
+var uiScreenBriefFields = [
+  {
+    id: "pageKind",
+    label: "Page kind",
+    description: "Choose the base recipe for the screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "list"
+  },
+  {
+    id: "routeUrl",
+    label: "Route URL",
+    description: "Final route for the screen or feature entry.",
+    required: true,
+    appliesTo: ["all"],
+    example: "/admin/users"
+  },
+  {
+    id: "sidebarItems",
+    label: "Sidebar items",
+    description: "Sidebar entries with at least id, title, and href so the shell stays consistent.",
+    required: true,
+    appliesTo: ["all"],
+    example: '[{ id: "users", title: "Users", href: "/admin/users" }]'
+  },
+  {
+    id: "activeSidebarItemId",
+    label: "Active sidebar item id",
+    description: "The sidebar item that should appear active on this screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "users"
+  },
+  {
+    id: "breadcrumbs",
+    label: "Breadcrumbs",
+    description: "Ordered breadcrumb items for the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Admin", href: "/admin" }, { label: "Users", current: true }]'
+  },
+  {
+    id: "pageTitle",
+    label: "Page title",
+    description: "Main page heading shown in the content header.",
+    required: true,
+    appliesTo: ["all"],
+    example: "Users"
+  },
+  {
+    id: "pageSubtitle",
+    label: "Page subtitle",
+    description: "Short supporting text under the title.",
+    required: false,
+    appliesTo: ["all"],
+    example: "Manage internal user accounts and permissions."
+  },
+  {
+    id: "primaryAction",
+    label: "Primary action",
+    description: "The highest-emphasis action shown in the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '{ label: "Create user", href: "/admin/users/create" }'
+  },
+  {
+    id: "secondaryActions",
+    label: "Secondary actions",
+    description: "Additional header actions such as export, refresh, or cancel.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Export" }, { label: "Refresh" }]'
+  },
+  {
+    id: "summaryStats",
+    label: "Summary stats",
+    description: "Top-line numbers for dashboard or overview screens.",
+    required: false,
+    appliesTo: ["dashboard", "detail"],
+    example: '[{ label: "Active users", value: "1,204", trend: "up", delta: "+12%" }]'
+  },
+  {
+    id: "filters",
+    label: "Filters",
+    description: "Filter bar controls shown above list or dashboard content.",
+    required: false,
+    appliesTo: ["list", "dashboard"],
+    example: '[{ type: "search", label: "Search user" }, { type: "select", label: "Role" }]'
+  },
+  {
+    id: "tableColumns",
+    label: "Table columns",
+    description: "Columns for a list table, including label and render intent.",
+    required: false,
+    appliesTo: ["list", "detail", "dashboard"],
+    example: '[{ key: "name", title: "Name" }, { key: "role", title: "Role" }]'
+  },
+  {
+    id: "rowActions",
+    label: "Row actions",
+    description: "Per-row actions for table screens.",
+    required: false,
+    appliesTo: ["list", "detail"],
+    example: '[{ label: "Edit" }, { label: "Reset password" }]'
+  },
+  {
+    id: "formSections",
+    label: "Form sections",
+    description: "Grouped form sections and the fields inside each section.",
+    required: false,
+    appliesTo: ["form"],
+    example: '[{ title: "Basic info", fields: ["name", "email", "role"] }]'
+  },
+  {
+    id: "fields",
+    label: "Fields",
+    description: "Detailed field list with type, label, required state, and helper text.",
+    required: false,
+    appliesTo: ["form", "detail"],
+    example: '[{ name: "email", type: "input", label: "Email", required: true }]'
+  },
+  {
+    id: "detailSections",
+    label: "Detail sections",
+    description: "Cards or sections for detail pages such as profile, activity, permissions, or related records.",
+    required: false,
+    appliesTo: ["detail"],
+    example: '[{ title: "Profile" }, { title: "Recent activity" }]'
+  },
+  {
+    id: "emptyState",
+    label: "Empty state",
+    description: "Fallback title, description, and action when there is no data.",
+    required: false,
+    appliesTo: ["list", "dashboard", "detail"],
+    example: '{ title: "No users yet", description: "Create the first user to get started." }'
+  },
+  {
+    id: "permissions",
+    label: "Permissions",
+    description: "Permission keys that affect sidebar visibility or action availability.",
+    required: false,
+    appliesTo: ["all"],
+    example: '["user.read", "user.write"]'
+  }
+];
+var uiScreenBlueprint = {
+  pageKinds: [
+    {
+      id: "list",
+      label: "List page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with actions",
+        "Optional stats",
+        "Filter card",
+        "DataTable card"
+      ]
+    },
+    {
+      id: "form",
+      label: "Form page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with primary and cancel actions",
+        "Sectioned form cards",
+        "Bottom action row"
+      ]
+    },
+    {
+      id: "detail",
+      label: "Detail page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with status/actions",
+        "Summary stats or metadata card",
+        "Detail cards and related tables"
+      ]
+    },
+    {
+      id: "dashboard",
+      label: "Dashboard page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with actions",
+        "Stat cards row",
+        "Filters",
+        "Main insight cards and tables"
+      ]
+    }
+  ],
+  workflow: [
+    "Collect the screen brief before coding. Do not invent sidebar items, route urls, filters, fields, or table columns if the brief is missing.",
+    "Use Sidebar plus Breadcrumb and PageTitle to lock the shell before building the page body.",
+    "Choose only canonical root exports from @lucasvu/scope-ui.",
+    "Use Card and ui-grid utilities to create the frame first, then place controls and data components inside.",
+    "Keep all palette, radius, surface, and shadow decisions in the shared ui-theme.css preset file.",
+    "End with a consistency check against the selected preset and the screen brief."
+  ],
+  briefFields: uiScreenBriefFields
+};
+
 // src/theme-contract.ts
 var uiThemePresets = [
   {
@@ -7296,5 +7504,7 @@ exports.hasActiveDescendant = hasActiveDescendant;
 exports.uiAiManifest = uiAiManifest;
 exports.uiDefaultThemePreset = uiDefaultThemePreset;
 exports.uiProjectAiRules = uiProjectAiRules;
+exports.uiScreenBlueprint = uiScreenBlueprint;
+exports.uiScreenBriefFields = uiScreenBriefFields;
 exports.uiThemeContract = uiThemeContract;
 exports.uiThemePresets = uiThemePresets;