@lucasvu/scope-ui 0.1.2 → 0.1.5

package/AI_SETUP.md

@@ -2,7 +2,7 @@
 
 Muc tieu cua file nay la de AI cua project dung `@lucasvu/scope-ui` dung cach, khong import lung tung, khong hardcode mau sai cho, va giu dung base `Vite + micro frontend` khi repo duoc setup o may khac.
 
-Tu phien ban nay, cac phan generic truoc day thuong nam o `packages/shared/theme` da duoc ship ngay trong package nay:
+Tu phien ban nay, cac phan theme/runtime truoc day tung nam o legacy shared theme source da duoc ship ngay trong package nay:
 
 - base stylesheet
 - color-mode runtime

package/README.md

@@ -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:

package/RULES.md

@@ -0,0 +1,52 @@
+# Rules Cho `@lucasvu/scope-ui`
+
+## Vai trò
+
+`@lucasvu/scope-ui` là package UI chính của workspace. Package này sở hữu:
+
+- component surface
+- stylesheet public
+- theme layers public
+- color-mode runtime
+- theme/runtime contract cho giao diện
+
+## Import đúng
+
+Import component từ:
+
+- `@lucasvu/scope-ui`
+
+Import runtime/theme contract từ:
+
+- `@lucasvu/scope-ui/core`
+
+Import stylesheet và theme từ:
+
+- `@lucasvu/scope-ui/styles.css`
+- `@lucasvu/scope-ui/themes/*`
+
+Không import:
+
+- từ `src/*`
+- từ `theme-source/*`
+- từ file nội bộ trong `dist/*`
+
+## Rule sử dụng
+
+- Import `styles.css` một lần ở app entry.
+- Nếu dùng theme layer, import từ `@lucasvu/scope-ui/themes/*`.
+- Nếu app không cần React surface mà chỉ cần theme/runtime, dùng `@lucasvu/scope-ui/core`.
+- Dùng component root trước. Chỉ dùng `MainFe` khi task thật sự yêu cầu legacy main-fe.
+- Không tự tạo thêm một hệ theme khác ngoài theme contract của package.
+
+## Rule cho AI và agent
+
+- Chọn component theo intent trước khi code.
+- Đọc `uiAiManifest` hoặc docs canonical props trước khi tự chọn component.
+- Không tự import file nội bộ chỉ vì tiện.
+- Không tự phát minh variant/theme path ngoài public API.
+
+## Ghi chú boundary
+
+- Theme source thuộc `ui`, không thuộc `shared`.
+- Utility generic như regex, formatter, runtime helper không nằm ở package này.

package/bin/copy-theme-assets.mjs

@@ -3,7 +3,7 @@
 import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
-const sourceDir = resolve(process.cwd(), '../shared/theme')
+const sourceDir = resolve(process.cwd(), 'theme-source')
 const targetDir = resolve(process.cwd(), 'dist/themes')
 
 if (!existsSync(sourceDir)) {

package/dist/{chunk-CL3F2TWE.js → chunk-QBAHQOOH.js}

@@ -1,9 +1,3 @@
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
 // src/ai-manifest.ts
 var uiAiManifest = {
   packageName: "@lucasvu/scope-ui",
@@ -1036,4 +1030,4 @@ function cn(...values) {
   return values.filter(Boolean).join(" ");
 }
 
-export { ROOT_CLIENT_THEME_ATTRIBUTE, ROOT_COLOR_MODE_ATTRIBUTE, __export, applyDocumentClientTheme, applyDocumentColorMode, cn, getSystemColorMode, initializeDocumentColorMode, isColorMode, subscribeToSystemColorMode, syncDocumentColorModeToSystem, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiScreenBlueprint, uiScreenBriefFields, uiThemeContract, uiThemeLayerAssets, uiThemePresets };
+export { ROOT_CLIENT_THEME_ATTRIBUTE, ROOT_COLOR_MODE_ATTRIBUTE, applyDocumentClientTheme, applyDocumentColorMode, cn, getSystemColorMode, initializeDocumentColorMode, isColorMode, subscribeToSystemColorMode, syncDocumentColorModeToSystem, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiScreenBlueprint, uiScreenBriefFields, uiThemeContract, uiThemeLayerAssets, uiThemePresets };

package/dist/core/index.js

@@ -1 +1 @@
-export { ROOT_CLIENT_THEME_ATTRIBUTE, ROOT_COLOR_MODE_ATTRIBUTE, applyDocumentClientTheme, applyDocumentColorMode, cn, getSystemColorMode, initializeDocumentColorMode, isColorMode, subscribeToSystemColorMode, syncDocumentColorModeToSystem, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiScreenBlueprint, uiScreenBriefFields, uiThemeContract, uiThemeLayerAssets, uiThemePresets } from '../chunk-CL3F2TWE.js';
+export { ROOT_CLIENT_THEME_ATTRIBUTE, ROOT_COLOR_MODE_ATTRIBUTE, applyDocumentClientTheme, applyDocumentColorMode, cn, getSystemColorMode, initializeDocumentColorMode, isColorMode, subscribeToSystemColorMode, syncDocumentColorModeToSystem, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiScreenBlueprint, uiScreenBriefFields, uiThemeContract, uiThemeLayerAssets, uiThemePresets } from '../chunk-QBAHQOOH.js';