@lucasvu/scope-ui 0.1.1 → 0.1.4

package/AI_SETUP.md

@@ -298,7 +298,7 @@ File generate ra se la source of truth cho palette, surface, radius va shadow cu
 
 Neu can them mot bundled package theme layer de co shell tone dung san, import no o app entry. Neu theme layer do la attribute-scoped, set them `data-client-theme` bang `applyDocumentClientTheme`.
 
-`AGENTS.md` se co them shell brief + screen brief dang YAML de agent dien cac gia tri nhu `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `pageTitle`, `filters`, `fields`, `tableColumns` truoc khi bat dau viet JSX.
+`AGENTS.md` se duoc generate theo format agent-definition YAML, co `activation-instructions`, `agent`, `persona`, `commands`, `dependencies`, va `brief_templates`. Agent se dien cac gia tri nhu `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `pageTitle`, `filters`, `fields`, `tableColumns` truoc khi bat dau viet JSX. Neu tool cua ban discover agent theo file rieng, co the truyen `--agents-file agents/dev.md` hoac mot path tuong tu.
 
 `src/layout-presets/workspace-admin-v1.ts` khong can import vao runtime. Day la layout contract cho agent/codegen doc de giu dark sidebar, gradient topbar, intro card, tab row, va toolbar card nhat quan giua cac man.
 

package/README.md

@@ -61,7 +61,7 @@ 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`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts` trong repo hiện tại theo preset đã chọn. `AGENTS.md` giờ có thêm playbook step-by-step để agent hỏi đủ input, đọc layout preset, rồi 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.
+Lệnh này sẽ tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts` trong repo hiện tại theo preset đã chọn. `AGENTS.md` giờ được generate theo format agent-definition YAML có `activation-instructions`, `agent`, `persona`, `commands`, `dependencies`, `brief_templates`, và rule lock theme/layout. Nếu muốn output thẳng vào path agent-discovery của tooling, dùng `--agents-file`, ví dụ `npx scope-ui-init --theme sunset --agents-file agents/dev.md`. 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.
 
 5. Dùng component:
 
@@ -134,6 +134,188 @@ export function Example() {
 - `Field` phù hợp khi bạn cần bọc một control custom hoặc gom nhiều control dưới cùng một nhãn.
 - Nếu bạn đổi tên package trước khi publish, thay `@lucasvu/scope-ui` trong các ví dụ bằng package name mới.
 
+## MainFe (legacy) - Docs rõ nghĩa
+
+Nếu bạn đang dùng nhóm component legacy, nên import component qua namespace `MainFe` và import type qua alias rõ nghĩa ở root package:
+
+```ts
+import {
+  MainFe,
+  type MainFePageTitleProps,
+  type MainFeSectionTitleProps,
+  type MainFeButtonProps,
+  type MainFeInputProps,
+  type MainFeComboboxProps,
+  type MainFeDataTableProps,
+  type MainFeSwitchProps,
+  type MultiTabsProps,
+  type StatCardProps,
+  type DateRangePickerProps,
+  type DateTimePickerProps,
+  type ArgonSidebarProps,
+} from '@lucasvu/scope-ui';
+```
+
+Quy ước:
+
+- Component render: `MainFe.PageTitle`, `MainFe.SectionTitle`, `MainFe.Button`, `MainFe.Input`, `MainFe.Combobox`, `MainFe.DataTable`, ...
+- Type unique sẵn: `MainFePageTitleProps`, `MainFeSectionTitleProps`, `MultiTabsProps`, `StatCardProps`, `DateRangePickerProps`, `DateTimePickerProps`, `ArgonSidebarProps`
+- Type trùng tên với root component đã được alias rõ nghĩa: `MainFeButtonProps`, `MainFeInputProps`, `MainFeComboboxProps`, `MainFeDataTableProps`, `MainFeSwitchProps`
+
+### MainFe.PageTitle
+
+Phù hợp cho header đầu trang của màn list/detail/dashboard trong legacy main FE.
+
+```tsx
+<MainFe.PageTitle
+  title="Campaign Detail"
+  subtitle="Overview and linked metrics"
+  topSlot={<Breadcrumb items={[...]} />}
+  rightSlot={<MainFe.Button>Export</MainFe.Button>}
+/>
+```
+
+Type: `MainFePageTitleProps`
+
+| Prop | Type | Mô tả |
+|---|---|---|
+| `title` | `string` | VI: Tiêu đề chính của trang. EN: Main title of the page. ZH: 页面主标题。 |
+| `subtitle` | `string` | VI: Mô tả ngắn nằm dưới title. EN: Short description below the title. ZH: 显示在标题下方的简短描述。 |
+| `size` | `'default' \| 'compact'` | VI: Mật độ hiển thị của header. EN: Visual density of the header. ZH: 页头显示密度。 |
+| `topSlot` | `ReactNode` | VI: Slot phía trên title, thường dùng cho breadcrumb/status. EN: Slot above the title, usually for breadcrumbs or status. ZH: 标题上方插槽，常用于面包屑或状态标签。 |
+| `rightSlot` | `ReactNode` | VI: Slot phía phải header, thường dùng cho action/filter. EN: Right-side slot for actions or filters. ZH: 头部右侧插槽，常用于操作或筛选。 |
+
+### MainFe.SectionTitle
+
+Phù hợp cho phần header của card/section trong các màn legacy.
+
+Type: `MainFeSectionTitleProps`
+
+| Prop | Type | Mô tả |
+|---|---|---|
+| `title` | `string` | VI: Tiêu đề chính của section. EN: Main title of the section. ZH: 区块主标题。 |
+| `subtitle` | `string` | VI: Mô tả ngắn giải thích section. EN: Short explanation for the section. ZH: 用于说明区块的简短描述。 |
+| `icon` | `ReactNode` | VI: Icon hiển thị bên trái title. EN: Icon shown to the left of the title. ZH: 显示在标题左侧的图标。 |
+| `iconClassName` | `string` | VI: Class tùy chỉnh cho wrapper của icon. EN: Custom class for the icon wrapper. ZH: 图标容器的自定义 class。 |
+| `rightSlot` | `ReactNode` | VI: Slot phía phải section title. EN: Right-side slot of the section title. ZH: 区块标题右侧插槽。 |
+
+### MainFe.MultiTabs
+
+Type: `MultiTabsProps`
+
+| Prop | Type | Mô tả |
+|---|---|---|
+| `items` | `MultiTabItem[]` | VI: Danh sách tab cần render. EN: Tabs to render. ZH: 需要渲染的 tab 列表。 |
+| `value` | `string` | VI: Giá trị tab đang active. EN: Currently active tab value. ZH: 当前激活的 tab 值。 |
+| `onChange` | `(value: string) => void` | VI: Callback khi đổi tab. EN: Callback fired when tab changes. ZH: tab 切换时触发的回调。 |
+| `className` | `string` | VI: Class bổ sung cho wrapper. EN: Extra class for the wrapper. ZH: 容器额外 class。 |
+| `style` | `CSSProperties` | VI: Inline style cho wrapper. EN: Inline style for the wrapper. ZH: 容器内联样式。 |
+
+### MainFe.StatCard
+
+Type: `StatCardProps`
+
+| Prop | Type | Mô tả |
+|---|---|---|
+| `label` | `ReactNode` | VI: Nhãn mô tả ý nghĩa của chỉ số. EN: Label describing the metric. ZH: 指标说明标签。 |
+| `value` | `ReactNode` | VI: Giá trị chính cần nhấn mạnh. EN: Primary metric value. ZH: 主要指标值。 |
+| `tone` | `'emerald' \| 'sky' \| 'violet' \| 'rose'` | VI: Tông màu chủ đạo của card. EN: Main visual tone of the card. ZH: 卡片主视觉色调。 |
+| `icon` | `ReactNode` | VI: Icon hiển thị góc phải. EN: Icon shown in the right corner. ZH: 显示在右侧角落的图标。 |
+| `className` | `string` | VI: Class bổ sung cho card. EN: Extra class for the card. ZH: 卡片额外 class。 |
+
+### MainFe.Combobox
+
+Type import rõ nghĩa: `MainFeComboboxProps`
+
+Ngoài các prop quen thuộc như `value`, `options`, `onChange`, `label`, `helperText`, `errorMessage`, bản `main-fe` có thêm các prop thiên về remote-search và dropdown behavior:
+
+| Prop | Type | Mô tả |
+|---|---|---|
+| `asyncConfig` | `MainFeComboboxAsyncConfig` | VI: Gom config cho search/load-more từ xa. EN: Bundles remote search/load-more behavior. ZH: 用于远程搜索/加载更多的配置集合。 |
+| `onLoadMore` | `() => void` | VI: Callback tải thêm khi dropdown chạm cuối. EN: Callback for loading more items at the end. ZH: 下拉到底部时加载更多的回调。 |
+| `hasMore` | `boolean` | VI: Cho biết còn dữ liệu để tải hay không. EN: Indicates whether more data exists. ZH: 是否还有更多数据。 |
+| `allowClear` | `boolean` | VI: Hiện nút xóa giá trị hiện tại. EN: Shows a clear-current-value action. ZH: 是否显示清空当前值的操作。 |
+| `portal` | `boolean` | VI: Render dropdown qua portal để tránh bị cắt bởi layout cha. EN: Renders dropdown in a portal to avoid clipping. ZH: 通过 portal 渲染下拉层，避免被父层裁切。 |
+| `dropdownClassName` | `string` | VI: Class bổ sung cho dropdown. EN: Extra class for the dropdown. ZH: 下拉层额外 class。 |
+| `dropdownMaxHeight` | `number` | VI: Ghi đè chiều cao tối đa của dropdown. EN: Overrides dropdown max height. ZH: 覆盖下拉层最大高度。 |
+| `hideErrorMessage` | `boolean` | VI: Giữ style lỗi nhưng không hiện dòng lỗi dưới field. EN: Keeps error styling without rendering the error text line. ZH: 保留错误样式但不显示下方错误文本。 |
+
+### MainFe.DataTable
+
+Type import rõ nghĩa: `MainFeDataTableProps<T>`
+
+`MainFe.DataTable` giữ mô hình gần giống `DataTable<T>` ở root nhưng thêm một vài prop phục vụ layout legacy:
+
+| Prop | Type | Mô tả |
+|---|---|---|
+| `columns` | `MainFeDataTableColumn<T>[]` | VI: Cấu hình cột của bảng. EN: Table column configuration. ZH: 表格列配置。 |
+| `data` | `T[]` | VI: Dữ liệu nguồn của bảng. EN: Table data source. ZH: 表格数据源。 |
+| `rowKey` | `keyof T \| ((record: T) => string \| number)` | VI: Cách lấy key duy nhất cho mỗi dòng. EN: How to resolve a unique row key. ZH: 每行唯一 key 的获取方式。 |
+| `sort` | `MainFeDataTableSortState \| null` | VI: Trạng thái sort nếu control từ ngoài. EN: Controlled sort state. ZH: 受控排序状态。 |
+| `rowSelection` | `MainFeDataTableRowSelection` | VI: Cấu hình checkbox chọn dòng. EN: Row-selection config. ZH: 行选择配置。 |
+| `renderActions` | `(record: T) => ReactNode` | VI: Render cột action của từng dòng. EN: Renders the per-row action column. ZH: 每行操作列渲染函数。 |
+| `actionColumnWidth` | `number \| string` | VI: Chiều rộng của cột action. EN: Width of the action column. ZH: 操作列宽度。 |
+| `stickyOffset` | `number` | VI: Offset sticky khi layout có top bar. EN: Sticky offset for layouts with top bars. ZH: 布局存在顶部栏时的 sticky 偏移。 |
+
+### MainFe.DateRangePicker
+
+Type: `DateRangePickerProps`  
+Value type: `DateRangePickerValue`
+
+| Prop | Type | Mô tả |
+|---|---|---|
+| `value` | `DateRangePickerValue` | VI: Khoảng ngày hiện tại `{ startDate, endDate }`. EN: Current date range `{ startDate, endDate }`. ZH: 当前日期区间 `{ startDate, endDate }`。 |
+| `onChange` | `(next) => void` | VI: Callback khi user xác nhận khoảng ngày mới. EN: Callback when a new range is confirmed. ZH: 用户确认新区间时触发的回调。 |
+| `label` | `string` | VI: Nhãn phía trên picker. EN: Label above the picker. ZH: 选择器上方标签。 |
+| `placeholder` | `string` | VI: Placeholder khi chưa chọn ngày. EN: Placeholder before a range is selected. ZH: 未选择日期时的占位文本。 |
+| `className` | `string` | VI: Class bổ sung cho wrapper. EN: Extra class for the wrapper. ZH: 容器额外 class。 |
+
+### MainFe.DateTimePicker
+
+Type: `DateTimePickerProps`
+
+| Prop | Type | Mô tả |
+|---|---|---|
+| `value` | `string` | VI: Giá trị ngày giờ hiện tại. EN: Current date-time value. ZH: 当前日期时间值。 |
+| `onChange` | `(value: string) => void` | VI: Callback khi giá trị thay đổi. EN: Callback when the value changes. ZH: 值变化时触发的回调。 |
+| `parseFormat` | `string` | VI: Format dùng để parse giá trị đầu vào. EN: Format used to parse incoming values. ZH: 用于解析输入值的格式。 |
+| `outputFormat` | `string` | VI: Format xuất ra qua `onChange`. EN: Format used for outgoing `onChange` values. ZH: 通过 `onChange` 输出时使用的格式。 |
+| `displayFormat` | `string` | VI: Format hiển thị trong trigger/input. EN: Format displayed in the trigger/input. ZH: 在触发器/输入区显示的格式。 |
+| `minDateTime` | `Date` | VI: Mốc nhỏ nhất được phép chọn. EN: Minimum selectable date-time. ZH: 可选的最小日期时间。 |
+| `quickOptions` | `MainFeQuickOption[]` | VI: Danh sách lựa chọn nhanh. EN: Quick-select options. ZH: 快捷选项列表。 |
+| `onQuickSelect` | `(value: string) => void` | VI: Callback khi chọn quick option. EN: Callback when a quick option is chosen. ZH: 选择快捷项时触发的回调。 |
+| `onClear` | `() => void` | VI: Callback khi xóa giá trị hiện tại. EN: Callback when clearing the current value. ZH: 清空当前值时触发的回调。 |
+| `portal` | `boolean` | VI: Render panel qua portal. EN: Renders the panel through a portal. ZH: 通过 portal 渲染面板。 |
+
+### MainFe.ArgonSidebar
+
+Type: `ArgonSidebarProps`
+
+Ngoài các prop kế thừa từ `SidebarProps`, đây là các prop được dùng nhiều nhất trong thực tế:
+
+| Prop | Type | Mô tả |
+|---|---|---|
+| `items` | `SidebarItem[]` | VI: Danh sách item sẽ render trong sidebar. EN: Sidebar items to render. ZH: 需要渲染的侧边栏项。 |
+| `activeItemId` | `string` | VI: `id` của item đang active. EN: `id` of the active item. ZH: 当前激活项的 `id`。 |
+| `onItemClick` | `(item) => void` | VI: Callback khi click item. EN: Callback fired when an item is clicked. ZH: 点击菜单项时触发的回调。 |
+| `collapsed` | `boolean` | VI: Trạng thái collapsed ở chế độ controlled. EN: Controlled collapsed state. ZH: 受控折叠状态。 |
+| `defaultCollapsed` | `boolean` | VI: Trạng thái collapsed mặc định ở uncontrolled mode. EN: Default collapsed state in uncontrolled mode. ZH: 非受控模式的默认折叠状态。 |
+| `onCollapseChange` | `(collapsed: boolean) => void` | VI: Callback khi trạng thái thu gọn thay đổi. EN: Callback when collapsed state changes. ZH: 折叠状态变化时的回调。 |
+| `collapsedWidth` | `number \| string` | VI: Chiều rộng khi sidebar thu gọn. EN: Width when the sidebar is collapsed. ZH: 侧边栏折叠时宽度。 |
+| `expandedWidth` | `number \| string` | VI: Chiều rộng khi sidebar mở rộng. EN: Width when the sidebar is expanded. ZH: 侧边栏展开时宽度。 |
+| `header` | `ReactNode \| ArgonSidebarHeaderRender` | VI: Header tĩnh hoặc hàm render động theo state collapse/hover. EN: Static header or render function based on collapse/hover state. ZH: 静态头部或基于折叠/悬停状态的渲染函数。 |
+| `onHoverChange` | `(hovered: boolean) => void` | VI: Callback khi sidebar tạm mở do hover. EN: Callback when the sidebar hover-expands. ZH: 侧边栏因悬停展开时的回调。 |
+
+### MainFe.Button / Input / Switch
+
+Các component này chủ yếu khác về visual style so với root component. Khi cần import type rõ ràng, dùng:
+
+- `MainFeButtonProps`
+- `MainFeInputProps`
+- `MainFeSwitchProps`
+
+Với `MainFe.Input`, các prop đáng chú ý là `prefix`, `suffix`, `inputClassName`, `onValueChange`, `showPasswordToggle`. Với `MainFe.Button`, các prop đáng chú ý là `variant`, `size`, `startIcon`, `endIcon`. Với `MainFe.Switch`, prop đặc thù là `trackClassName`, `thumbClassName`, `onCheckedChange`.
+
 ## Bundled Theme Layers
 
 Package ship sẵn các theme asset để máy khác cài vào là dùng được ngay:
@@ -180,10 +362,11 @@ Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng
 - 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`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts`
+- Nếu tooling của bạn đọc agent theo file riêng, dùng `--agents-file agents/dev.md` hoặc path tương đương để generate luôn agent markdown đúng chỗ
 - 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` và `src/layout-presets/workspace-admin-v1.ts` để đi đúng thứ tự: hỏi input, khóa shell, chọn component, dựng layout, rồi mới tinh chỉnh token
+- Để agent đọc luôn agent-definition trong `AGENTS.md` hoặc file bạn truyền qua `--agents-file`, cùng với `src/layout-presets/workspace-admin-v1.ts`, để đi đúng thứ tự: hỏi input, khóa shell, chọn component, dựng layout, rồi mới tinh chỉnh token
 - Buộc agent điền shell + screen brief trước khi code: `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `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
+- `AGENTS.md` mới sẽ có sẵn block `commands`, `dependencies`, và `brief_templates` 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 `uiScreenBlueprint`, `uiThemeContract` và `uiThemePresets` để biết screen recipe, preset và token nào được phép override