@v-miniapp/ui-react 1.0.47 → 1.0.60

package/dist-storybook/stories-data.json

@@ -1,58 +1,4 @@
 [
-  {
-    "id": "app-framework-animation--docs",
-    "title": "App Framework/Animation",
-    "subtitle": "Cấu hình animation chuyển trang giữa các pages trong App Framework.",
-    "content": "Animation Config cho phép cấu hình animation chuyển trang. Các loại animation bao gồm none, slide_up, slide_left và fade_in. Cấu trúc IAppAnimationState với type INavigationAnimationType."
-  },
-  {
-    "id": "app-framework-bottom-tab-bar--docs",
-    "title": "App Framework/Bottom Tab Bar",
-    "subtitle": "Cấu hình bottom tab bar cho ứng dụng Mini App.",
-    "content": "Bottom Tab Bar Config cho phép cấu hình bottom tab bar với các items, styling và behavior. IAppBottomTabBarState extends IBottomTabBarProps và thêm items với path và hidden property."
-  },
-  {
-    "id": "app-framework-general--docs",
-    "title": "App Framework/General",
-    "subtitle": "App Framework là bộ khung để xây dựng Mini App hoàn chỉnh với routing, mobile behaviours và các tính năng native app.",
-    "content": "App Framework cung cấp component App với nhiều tính năng global như Error Boundary, Toast Provider, Navigation Analytics và Multi-language. Có thể cấu hình với IAppConfig bao gồm animation, keepAlive, pages và các tính năng khác. Hỗ trợ pull-to-refresh, swipe navigation, page stacking với keep-alive."
-  },
-  {
-    "id": "app-framework-keep-alive--docs",
-    "title": "App Framework/Keep Alive",
-    "subtitle": "Keep Alive cho phép giữ các pages trong DOM thay vì unmount khi navigate, giúp giữ state và scroll position.",
-    "content": "Keep Alive cho phép giữ các pages trong DOM (ẩn) thay vì unmount khi navigate. IAppKeepAliveState có enable, maxStack, freeze và freezeDelay. Page-level có thể override bằng boolean hoặc config object với keepAlive, freeze và freezeDelay."
-  },
-  {
-    "id": "app-framework-locale--docs",
-    "title": "App Framework/Locale",
-    "subtitle": "Locales module cung cấp giải pháp quản lý đa ngôn ngữ với TypeScript type safety và hỗ trợ custom locales keys.",
-    "content": "Locales Module cung cấp quản lý đa ngôn ngữ với TypeScript type safety. Hỗ trợ custom locales keys và custom language codes thông qua module augmentation. Có sẵn tiếng Việt và tiếng Anh. Hỗ trợ hooks useTranslate, useLanguage và standalone functions. Tự động lấy ngôn ngữ từ URL search params."
-  },
-  {
-    "id": "app-framework-mobile-behaviours--docs",
-    "title": "App Framework/Mobile Behaviours",
-    "subtitle": "Component App đã tích hợp sẵn nhiều behaviours giống native app để mang lại trải nghiệm mobile tự nhiên.",
-    "content": "Mobile Behaviours bao gồm Swipe Navigation, Pull to Refresh, Keep Alive, Scroll Restoration, Page Stacking và Animation. Swipe navigation cho phép swipe từ cạnh màn hình để navigate. Pull to Refresh kéo xuống để refresh page. Keep Alive giữ state và scroll position. Scroll Restoration tự động khôi phục scroll position khi navigate back."
-  },
-  {
-    "id": "app-framework-page-layout--docs",
-    "title": "App Framework/Page Layout",
-    "subtitle": "Cấu hình page layout cho các pages trong ứng dụng Mini App.",
-    "content": "Page Layout Config cho phép cấu hình layout cho pages với các thuộc tính như spacing, safe area offsets, pull-to-refresh, và scroll restoration. IAppPageLayoutState extends IPageBaseProps và thêm hidden và scrollRestoration."
-  },
-  {
-    "id": "app-framework-routing-navigation--docs",
-    "title": "App Framework/Routing & Navigation",
-    "subtitle": "Hệ thống routing và navigation cung cấp các hooks và utilities để quản lý navigation và lifecycle events.",
-    "content": "Routing & Navigation sử dụng exact path matching. Navigation được thực hiện qua function navigate từ hook useNavigate. Có thể navigate bằng pathname hoặc delta. Các hooks bao gồm useNavigate, useLocation, useHistory, useHistories, usePageState, usePageConfig, usePageScroll, useNavigationType, useDidShow, useDidHide, useAppPause, useAppResume, useCustomIconEvent và useSettingsChanged."
-  },
-  {
-    "id": "app-framework-theme-mode--docs",
-    "title": "App Framework/Theme Mode",
-    "subtitle": "Cấu hình theme cho ứng dụng Mini App.",
-    "content": "Theme Config cho phép cấu hình theme mặc định cho ứng dụng. IThemeConfig có defaultMode để thiết lập theme mặc định (light, dark, hoặc system)."
-  },
   {
     "id": "components-alert--docs",
     "title": "Components/Alert",
@@ -258,106 +204,184 @@
     "content": "Component Uploader là component upload file. Có thể được tùy chỉnh với các props value, onChange, limit, disabled, showPreview, includeBase64 và className. Thuộc tính Tên thuộc tính Kiểu dữ liệu Bắt buộc Mô tả \\ API Properties: value: IFileUpload[] - Danh sách các file đã upload. onChange: (files: IFileUpload[]) => void - Callback khi danh sách file thay đổi. limit: number - Số lượng file tối đa. disabled: boolean - Trạng thái disabled. showPreview: boolean - Hiển thị preview. includeBase64: boolean - Bao gồm base64. className: string - Class name tùy chỉnh."
   },
   {
-    "id": "getting-started--docs",
-    "title": "Getting Started",
-    "subtitle": "Hướng dẫn bắt đầu sử dụng @v-miniapp/ui-react để phát triển V-MiniApp.",
-    "content": "Getting Started với @v-miniapp/ui-react. Hướng dẫn cài đặt, import styles, và ví dụ bắt đầu sử dụng. Thư viện cung cấp đầy đủ các component UI, routing, theme management và các tính năng native app như pull-to-refresh, swipe navigation, page stacking với keep-alive. Có thể tích hợp với Tailwind CSS hoặc sử dụng CSS chuẩn."
+    "id": "locale-components-localesprovider--docs",
+    "title": "Locale/LocalesProvider",
+    "subtitle": "Component provider khởi tạo Locale module, cung cấp resources và context cho toàn bộ cây component.",
+    "content": "LocalesProvider nhận config (ILocalesConfig) và children. Chỉ init một lần khi mount. Đặt ở top-level. Khi dùng App thì không cần dùng trực tiếp."
   },
   {
-    "id": "hooks-useapppause--docs",
-    "title": "Hooks/useAppPause",
-    "subtitle": "Hook để xử lý khi app bị pause (background).",
-    "content": "useAppPause hook xử lý khi app bị pause. Nhận callback function được gọi khi app pause. Có thể sử dụng để pause timers, animations hoặc các tác vụ đang chạy khi app vào background."
+    "id": "locale-getting-started--docs",
+    "title": "Locale/Getting Started",
+    "subtitle": "Hướng dẫn bắt đầu sử dụng Locale module cho đa ngôn ngữ với TypeScript type safety.",
+    "content": "Cài đặt và khởi tạo Locale với LocalesProvider. Thứ tự ưu tiên ngôn ngữ, text mặc định cho component, và mở rộng custom languages/keys qua module augmentation."
   },
   {
-    "id": "hooks-useappresume--docs",
-    "title": "Hooks/useAppResume",
-    "subtitle": "Hook để xử lý khi app được resume (foreground).",
-    "content": "useAppResume hook xử lý khi app được resume. Nhận callback function được gọi khi app resume. Có thể sử dụng để resume timers, animations hoặc các tác vụ khi app quay lại foreground."
+    "id": "locale-hooks-uselanguage--docs",
+    "title": "Locale/useLanguage",
+    "subtitle": "Hook trả về ngôn ngữ hiện tại, ngôn ngữ system và function setLanguage.",
+    "content": "useLanguage() trả về { language, systemLanguage, setLanguage }. Có reactivity. Dùng để hiển thị/đổi ngôn ngữ trong component."
   },
   {
-    "id": "hooks-usecustomiconevent--docs",
-    "title": "Hooks/useCustomIconEvent",
-    "subtitle": "Hook để xử lý custom icon event từ navigation bar.",
-    "content": "useCustomIconEvent hook xử lý custom icon event từ navigation bar. Nhận callback function được gọi khi custom icon được click. Có thể sử dụng để xử lý các action tùy chỉnh từ navigation bar."
+    "id": "locale-hooks-usetranslate--docs",
+    "title": "Locale/useTranslate",
+    "subtitle": "Hook trả về function translate với reactivity khi đổi ngôn ngữ.",
+    "content": "useTranslate() trả về function (key, params?, lang?) => string. Có reactivity: component re-render khi ngôn ngữ thay đổi. Nên dùng trong React component thay cho t() để UI cập nhật đúng."
   },
   {
-    "id": "hooks-usedidhide--docs",
-    "title": "Hooks/useDidHide",
-    "subtitle": "Hook để xử lý khi page bị ẩn (hide).",
-    "content": "useDidHide hook xử lý khi page bị ẩn. Nhận callback function được gọi khi page hide. Có thể sử dụng để pause animations, timers hoặc các tác vụ khi page không còn hiển thị."
+    "id": "migration-guide--docs",
+    "title": "UI React/Migration Guide",
+    "subtitle": "Hướng dẫn migrate từ @vsf-miniapp/ui-react sang @v-miniapp/ui-react với nhiều tính năng và cải tiến hơn.",
+    "content": "Migration Guide từ @vsf-miniapp/ui-react sang @v-miniapp/ui-react. Phiên bản mới có App Framework hoàn chỉnh, Mobile Behaviours, Multi-language với TypeScript type safety, nhiều component mới và tính năng nâng cao như Animation, Error Boundary, Toast Provider, Analytics."
   },
   {
-    "id": "hooks-usedidshow--docs",
-    "title": "Hooks/useDidShow",
-    "subtitle": "Hook để xử lý khi page được hiển thị (show).",
-    "content": "useDidShow hook xử lý khi page được hiển thị. Nhận callback function được gọi khi page show. Có thể sử dụng để resume animations, timers hoặc các tác vụ khi page được hiển thị."
+    "id": "overview--docs",
+    "title": "Overview",
+    "subtitle": "Tổng quan bộ thư viện @v-miniapp/* và ba thư viện chính: ui-react, router, locale.",
+    "content": "Giới thiệu ecosystem @v-miniapp/* dùng để phát triển V-MiniApp với React. Ba thư viện chính: @v-miniapp/ui-react (UI + App Framework), @v-miniapp/router (routing), @v-miniapp/locale (đa ngôn ngữ)."
   },
   {
-    "id": "hooks-usehistories--docs",
-    "title": "Hooks/useHistories",
-    "subtitle": "Hook để lấy toàn bộ history stack.",
-    "content": "useHistories hook trả về mảng các history entries trong navigation stack. Mỗi history entry có action, location với key, pathname, params, state và timestamp. Có thể sử dụng để hiển thị breadcrumb hoặc navigation history."
+    "id": "router-deeplink--docs",
+    "title": "Router/Deeplink",
+    "subtitle": "Định dạng Deeplink và Universal link để mở V-MiniApp tới pathname và params cụ thể.",
+    "content": "Deeplink: vapp://mini/{appid}/{pathname}?{params}. Universal link: https://v-app.vn/mini/{appid}/{pathname}?{params}."
   },
   {
-    "id": "hooks-usehistory--docs",
-    "title": "Hooks/useHistory",
-    "subtitle": "Hook để lấy history entry hiện tại của page.",
-    "content": "useHistory hook trả về history entry hiện tại với action PUSH, REPLACE hoặc POP, location object chứa key, pathname, params và state, cùng với timestamp. Có thể sử dụng để truy cập thông tin navigation hiện tại."
+    "id": "router-events--docs",
+    "title": "Router/Events",
+    "subtitle": "routerEvents: EventEmitter để lắng nghe before/after history change, before/after navigate và afterInit.",
+    "content": "routerEvents.on(event, handler) trả về hàm unsubscribe. Các event: beforeHistoryChange, beforeHistoryChangeP2, afterHistoryChange, afterHistoryChangeP2, beforeNavigate, afterNavigate, afterInit. Payload chứa history, histories, nextHistory/prevHistory, nextHistories/prevHistories. Hỗ trợ CustomEvent trên window."
   },
   {
-    "id": "hooks-uselocation--docs",
-    "title": "Hooks/useLocation",
-    "subtitle": "Hook để lấy location object hiện tại (pathname, params, state, key).",
-    "content": "useLocation hook trả về location object hiện tại với key, pathname, params và state. Có thể sử dụng để truy cập pathname, query parameters và state được truyền qua navigation. Location object được cập nhật khi navigate."
+    "id": "router-getting-started--docs",
+    "title": "Router/Getting Started",
+    "subtitle": "Hướng dẫn bắt đầu sử dụng @v-miniapp/router cho routing và navigation trong V-MiniApp.",
+    "content": "Cài đặt, import styles, cấu hình IRouterConfig với pages, animation, keepAlive. Ví dụ Router component và điều hướng cơ bản."
   },
   {
-    "id": "hooks-usenavigate--docs",
-    "title": "Hooks/useNavigate",
-    "subtitle": "Hook để lấy function navigate để điều hướng giữa các pages.",
-    "content": "useNavigate hook trả về function navigate với type INavigate. Có thể navigate bằng pathname với options INavigatePathnameOptions hoặc bằng delta với options INavigateDeltaOptions. INavigatePathnameOptions có replace và state. INavigateDeltaOptions có replace."
+    "id": "router-hooks-useapppause--docs",
+    "title": "Router/useAppPause",
+    "subtitle": "Hook lắng nghe sự kiện onAppPause (app vào nền).",
+    "content": "useAppPause(onPause) đăng ký listener cho window event 'onAppPause'. Gọi onPause khi app bị pause (ví dụ chuyển tab, thu nhỏ). Dùng cho mini app / native bridge."
   },
   {
-    "id": "hooks-usenavigationtype--docs",
-    "title": "Hooks/useNavigationType",
-    "subtitle": "Hook để lấy navigation action type (PUSH, REPLACE, POP).",
-    "content": "useNavigationType hook trả về navigation action type là PUSH, REPLACE hoặc POP. Có thể sử dụng để xác định cách page được navigate đến, ví dụ để xử lý khác nhau giữa push và replace navigation."
+    "id": "router-hooks-useappresume--docs",
+    "title": "Router/useAppResume",
+    "subtitle": "Hook lắng nghe sự kiện onAppResume (app quay lại foreground).",
+    "content": "useAppResume(onResume) đăng ký listener cho window event 'onAppResume'. Gọi onResume khi app resume. Dùng cho mini app / native bridge."
   },
   {
-    "id": "hooks-usepageconfig--docs",
-    "title": "Hooks/usePageConfig",
-    "subtitle": "Hook để lấy config của page hiện tại.",
-    "content": "usePageConfig hook trả về IPageConfig của page hiện tại. IPageConfig chứa các cấu hình như pathname, Component, navigationBar, layouts và các config khác. Có thể sử dụng để truy cập cấu hình page hiện tại."
+    "id": "router-hooks-usedidhide--docs",
+    "title": "Router/useDidHide",
+    "subtitle": "Hook gọi callback khi page bị ẩn (hide) và trả về trạng thái didHide.",
+    "content": "useDidHide(func?) gọi func khi page hide (beforeHistoryChange khi nextHistory khác location key). Trả về boolean didHide. Dùng để dọn dẹp, pause khi rời page."
   },
   {
-    "id": "hooks-usepagescroll--docs",
-    "title": "Hooks/usePageScroll",
-    "subtitle": "Hook để lắng nghe sự kiện scroll của page.",
-    "content": "usePageScroll hook lắng nghe sự kiện scroll của page. Nhận callback function và options cho throttle. Callback nhận target HTMLDivElement và event. Có thể sử dụng để xử lý scroll events với throttle để tối ưu performance."
+    "id": "router-hooks-usedidshow--docs",
+    "title": "Router/useDidShow",
+    "subtitle": "Hook gọi callback khi page được hiển thị (show) và trả về trạng thái didShow.",
+    "content": "useDidShow(func?) gọi func khi page show (sau beforeHistoryChangeP2 khi nextHistory trùng location key). Trả về boolean didShow. Dùng để fetch data, analytics khi vào page."
   },
   {
-    "id": "hooks-usepagestate--docs",
-    "title": "Hooks/usePageState",
-    "subtitle": "Hook để quản lý state của page hiện tại.",
-    "content": "usePageState hook trả về pageState IPageState và setPageState function. IPageState chứa các state như keepAlive, freeze, freezeDelay. Có thể sử dụng để quản lý và cập nhật state của page hiện tại."
+    "id": "router-hooks-usehistories--docs",
+    "title": "Router/useHistories",
+    "subtitle": "Hook trả về toàn bộ history stack (mảng IHistory).",
+    "content": "useHistories() trả về IHistory[]. Dùng để biết số lượng page trong stack, có thể back hay không, hoặc render breadcrumb."
   },
   {
-    "id": "hooks-usesettingschanged--docs",
-    "title": "Hooks/useSettingsChanged",
-    "subtitle": "Hook để xử lý khi settings của app thay đổi.",
-    "content": "useSettingsChanged hook xử lý khi settings của app thay đổi. Nhận callback function được gọi khi settings thay đổi. Có thể sử dụng để phản ứng với các thay đổi settings như theme, language hoặc các cài đặt khác."
+    "id": "router-hooks-usehistory--docs",
+    "title": "Router/useHistory",
+    "subtitle": "Hook trả về history entry hiện tại (action + location).",
+    "content": "useHistory() trả về IHistory: action (PUSH | REPLACE | POP) và location. Phụ thuộc LocationKeyContext nên trả về entry tương ứng với page/component đang render."
   },
   {
-    "id": "migration-guide--docs",
-    "title": "Migration Guide",
-    "subtitle": "Hướng dẫn migrate từ @vsf-miniapp/ui-react sang @v-miniapp/ui-react với nhiều tính năng và cải tiến hơn.",
-    "content": "Migration Guide từ @vsf-miniapp/ui-react sang @v-miniapp/ui-react. Phiên bản mới có App Framework hoàn chỉnh, Mobile Behaviours, Multi-language với TypeScript type safety, nhiều component mới và tính năng nâng cao như Animation, Error Boundary, Toast Provider, Analytics."
+    "id": "router-hooks-uselocation--docs",
+    "title": "Router/useLocation",
+    "subtitle": "Hook trả về location hiện tại (pathname, params, state, key).",
+    "content": "useLocation() trả về ILocation | undefined. Dựa trên useHistory(); location tương ứng với history entry của page/context hiện tại."
+  },
+  {
+    "id": "router-hooks-usenavigate--docs",
+    "title": "Router/useNavigate",
+    "subtitle": "Hook trả về function navigate để điều hướng bằng pathname hoặc delta.",
+    "content": "useNavigate() trả về INavigate: navigate(pathname, options?) hoặc navigate(delta, options?). Options gồm replace, params, state và IRouterPageState."
   },
   {
-    "id": "use-cases-custom-error-boundary--docs",
-    "title": "Use Cases/Custom Error Boundary",
-    "subtitle": "Hướng dẫn thêm ErrorBoundary riêng cho từng page để bắt lỗi trước và xử lý chi tiết hơn.",
-    "content": "Custom Error Boundary cho phép thêm ErrorBoundary riêng cho từng page thông qua Layouts trong IPageConfig. ErrorBoundary ở page-level sẽ bắt lỗi trước ErrorBoundary global, cho phép xử lý chi tiết và isolate errors. App component đã có ErrorBoundary global sẵn để catch tất cả lỗi không được handle."
+    "id": "router-hooks-usenavigationtype--docs",
+    "title": "Router/useNavigationType",
+    "subtitle": "Hook trả về action type của history hiện tại (PUSH, REPLACE, POP).",
+    "content": "useNavigationType() trả về IHistoryAction. Bằng useHistory().action. Dùng để biết user vào page bằng push, replace hay back/forward."
+  },
+  {
+    "id": "router-router--docs",
+    "title": "Router/Router",
+    "subtitle": "Component Router: props, IRouterConfig, IRouterPageConfig, animation, keepAlive, ErrorPage, NotFoundPage.",
+    "content": "Router nhận config (IRouterConfig hoặc function trả về config). Hỗ trợ animation (type, mode), keepAlive, Layouts, ErrorPage, NotFoundPage. Config chỉ được đọc lần đầu khi mount."
+  },
+  {
+    "id": "ui-react-app--docs",
+    "title": "UI React/App",
+    "subtitle": "Component App: props, IAppConfig, IPageConfig. Tích hợp Router, Locale, ErrorBoundary, Toast, NavigationBar, BottomTabBar.",
+    "content": "App nhận config, localesConfig, className. IAppConfig gồm pages, animation, navigationBar, bottomTabBar, keepAlive, pageLayout, theme. IPageConfig mở rộng từ router với navigationBar, bottomTabBar, pageLayout. App-level áp dụng mặc định, page-level override."
+  },
+  {
+    "id": "ui-react-getting-started--docs",
+    "title": "UI React/Getting Started",
+    "subtitle": "Hướng dẫn bắt đầu sử dụng @v-miniapp/ui-react để phát triển V-MiniApp.",
+    "content": "Cài đặt, import styles (CSS hoặc Tailwind), ví dụ App với IAppConfig. Thư viện tích hợp Router, Locale, UI components, theme, pull-to-refresh, swipe navigation, keep-alive."
+  },
+  {
+    "id": "ui-react-theme--docs",
+    "title": "UI React/Theme",
+    "subtitle": "Hướng dẫn sử dụng theme (light/dark/system) trong @v-miniapp/ui-react.",
+    "content": "Theme hỗ trợ 3 chế độ: light, dark, system. Cấu hình qua IAppConfig.theme.mode. Các hàm: getDataTheme, setDataTheme, toggleDataTheme. Theme được áp dụng qua data-theme attribute trên documentElement."
+  },
+  {
+    "id": "ui-react-usebottomtabbar--docs",
+    "title": "UI React/useBottomTabBar",
+    "subtitle": "Hook đọc và cập nhật state bottom tab bar (app-level và page-level).",
+    "content": "useBottomTabBar() trả về state (merged), pageState, appState, hidden và các setter: setPageBottomTabBar, setAppBottomTabBar, remove*, reset*. hidden true khi bar ẩn hoặc page không có bottomTabBarId/items."
+  },
+  {
+    "id": "ui-react-usecustomiconevent--docs",
+    "title": "UI React/useCustomIconEvent",
+    "subtitle": "Hook xử lý khi user bấm custom icon trên navigation bar.",
+    "content": "useCustomIconEvent(onCustomIconEvent). Callback nhận index của icon được bấm. Dùng khi navigationBar có custom icons."
+  },
+  {
+    "id": "ui-react-useloadmore--docs",
+    "title": "UI React/useLoadMore",
+    "subtitle": "Hook đăng ký handler load more (onEndReached) cho page hiện tại.",
+    "content": "useLoadMore(onEndReached) gọi setPagePageLayout với onEndReached. Khi scroll tới cuối (hoặc trigger tương đương), onEndReached được gọi. Chỉ áp dụng cho page hiện tại."
+  },
+  {
+    "id": "ui-react-usenavigationbar--docs",
+    "title": "UI React/useNavigationBar",
+    "subtitle": "Hook đọc và cập nhật state navigation bar (app-level và page-level).",
+    "content": "useNavigationBar() trả về state (merged), pageState, appState và các setter: setPageNavigationBar, setAppNavigationBar, removePageNavigationBar, removeAppNavigationBar, resetPageNavigationBar, resetAppNavigationBar."
+  },
+  {
+    "id": "ui-react-usepagelayout--docs",
+    "title": "UI React/usePageLayout",
+    "subtitle": "Hook đọc và cập nhật state page layout (app-level và page-level).",
+    "content": "usePageLayout() trả về state (merged), pageState, appState và các setter: setPagePageLayout, setAppPageLayout, remove/removeApp, resetPagePageLayout, resetAppPageLayout. State gồm scrollRestoration, pullToRefresh, onEndReached, contentClassName, hidden."
+  },
+  {
+    "id": "ui-react-usepagescroll--docs",
+    "title": "UI React/usePageScroll",
+    "subtitle": "Hook lắng nghe sự kiện scroll của page.",
+    "content": "usePageScroll(callback, options?) với throttle. Callback nhận target (HTMLDivElement) và event. Chỉ hoạt động khi page đang hiển thị."
+  },
+  {
+    "id": "ui-react-usepulltorefresh--docs",
+    "title": "UI React/usePullToRefresh",
+    "subtitle": "Hook đăng ký handler pull-to-refresh cho page hiện tại.",
+    "content": "usePullToRefresh(onRefresh) gọi setPagePageLayout với pullToRefresh.onRefresh. onRefresh có thể sync hoặc async. Chỉ áp dụng cho page hiện tại."
+  },
+  {
+    "id": "ui-react-usesettingschanged--docs",
+    "title": "UI React/useSettingsChanged",
+    "subtitle": "Hook lắng nghe khi settings của app thay đổi.",
+    "content": "useSettingsChanged(onSettingsChanged). Callback nhận object settings. Dùng để phản ứng với thay đổi theme, language hoặc cài đặt khác từ native/môi trường."
   },
   {
     "id": "use-cases-infinite-scroll--docs",
@@ -365,6 +389,12 @@
     "subtitle": "Hướng dẫn implement infinite scroll để tự động load thêm data khi user scroll đến cuối danh sách.",
     "content": "Infinite Scroll cho phép tự động load thêm data khi user scroll đến cuối danh sách. Có thể sử dụng hook useLoadMore để quản lý loading state, hasMore state và loadMore function. Hook này tự động phát hiện khi scroll đến cuối và gọi loadMore function."
   },
+  {
+    "id": "use-cases-migrate-darkmode-to-theme--docs",
+    "title": "Use Cases/Migrate darkMode to theme",
+    "subtitle": "Hướng dẫn migrate từ deprecated darkMode sang theme.mode mới trong @v-miniapp/ui-react.",
+    "content": "darkMode đã được deprecated và sẽ bị xóa trong tương lai. Cần migrate sang theme.mode với các giá trị: 'light', 'dark', hoặc 'system'. Mapping: darkMode.defaultEnabled: true → theme.mode: 'dark', darkMode.defaultEnabled: false → theme.mode: 'light'."
+  },
   {
     "id": "use-cases-tailwind-integration--docs",
     "title": "Use Cases/Tailwind Integration",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-miniapp/ui-react",
-  "version": "1.0.47",
+  "version": "1.0.60",
   "type": "module",
   "files": [
     "dist",
@@ -19,6 +19,8 @@
   "dependencies": {
     "@types/lodash": "^4.17.23",
     "@use-gesture/react": "^10.3.1",
+    "@v-miniapp/locale": "1.0.2",
+    "@v-miniapp/router": "1.0.5",
     "ahooks": "^3.9.6",
     "classnames": "^2.5.1",
     "dayjs": "^1.11.19",

package/dist/components/app/components/app.d.ts

@@ -1,13 +0,0 @@
-import { ComponentPropsWithRef, ReactNode } from 'react';
-import { IAppConfig } from '../types/app';
-import { ILocalesConfig, IResourceKey, ITemplateParams } from '../../../locales/types';
-export type IAppConfigContext = {
-    t: (key: IResourceKey, params?: ITemplateParams) => ReactNode;
-};
-export type IAppConfigFunction = (context: IAppConfigContext) => IAppConfig;
-export type IAppProps = ComponentPropsWithRef<'div'> & {
-    config: IAppConfig | IAppConfigFunction;
-    localesConfig?: ILocalesConfig;
-};
-export declare const AppInner: ({ config: configProp }: IAppProps) => import("react/jsx-runtime").JSX.Element;
-export declare const App: ({ className, config, localesConfig, ...props }: IAppProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/app/components/link.d.ts

@@ -1,8 +0,0 @@
-import { ComponentProps, FC } from 'react';
-import { INavigatePathnameOptions, INavigateDeltaOptions } from '../types/navigation';
-export type ILinkProps = Omit<ComponentProps<'a'>, 'href' | 'onClick'> & (({
-    to: number;
-} & INavigateDeltaOptions) | ({
-    to: string;
-} & INavigatePathnameOptions));
-export declare const Link: FC<ILinkProps>;

package/dist/components/app/components/navigation-analytic.d.ts

@@ -1,2 +0,0 @@
-import { FC, PropsWithChildren } from 'react';
-export declare const NavigationAnalytic: FC<PropsWithChildren>;

package/dist/components/app/components/pages-render.d.ts

@@ -1,2 +0,0 @@
-import { FC } from 'react';
-export declare const PagesRender: FC;

package/dist/components/app/context/location-key.d.ts

@@ -1,4 +0,0 @@
-export type ILocationKeyState = {
-    locationKey: string | null;
-};
-export declare const LocationKeyContext: import('react').Context<ILocationKeyState>;

package/dist/components/app/hooks/use-app-pause.d.ts

@@ -1 +0,0 @@
-export declare const useAppPause: (onPause: () => void) => void;

package/dist/components/app/hooks/use-app-resume.d.ts

@@ -1 +0,0 @@
-export declare const useAppResume: (onResume: () => void) => void;

package/dist/components/app/hooks/use-app-state.d.ts

@@ -1,7 +0,0 @@
-import { Dispatch, SetStateAction } from 'react';
-import { IAppState } from '../types/app';
-export declare const useAppState: () => {
-    config: import('..').IAppConfig;
-    appState: IAppState;
-    setAppState: Dispatch<SetStateAction<IAppState>>;
-};

package/dist/components/app/hooks/use-bottom-tab-bar.d.ts

@@ -1,13 +0,0 @@
-import { IAppBottomTabBarState } from '../types/app';
-export declare const useBottomTabBar: () => {
-    state: IAppBottomTabBarState;
-    pageState: IAppBottomTabBarState | undefined;
-    appState: IAppBottomTabBarState | undefined;
-    hidden: boolean;
-    setPageBottomTabBar: (bottomTabBar: Partial<IAppBottomTabBarState>) => void;
-    setAppBottomTabBar: (bottomTabBar: Partial<IAppBottomTabBarState>) => void;
-    removePageBottomTabBar: () => void;
-    removeAppBottomTabBar: () => void;
-    resetPageBottomTabBar: () => void;
-    resetAppBottomTabBar: () => void;
-};

package/dist/components/app/hooks/use-did-hide.d.ts

@@ -1 +0,0 @@
-export declare const useDidHide: (func?: () => void) => boolean;

package/dist/components/app/hooks/use-did-show.d.ts

@@ -1 +0,0 @@
-export declare const useDidShow: (func?: () => void) => boolean;

package/dist/components/app/hooks/use-history.d.ts

@@ -1,2 +0,0 @@
-export declare const useHistory: () => import('..').IHistory;
-export declare const useHistories: () => import('..').IHistory[];

package/dist/components/app/hooks/use-location.d.ts

@@ -1 +0,0 @@
-export declare const useLocation: () => import('..').ILocation;

package/dist/components/app/hooks/use-navigate.d.ts

@@ -1 +0,0 @@
-export declare const useNavigate: () => import('..').INavigate;

package/dist/components/app/hooks/use-navigation-bar.d.ts

@@ -1,12 +0,0 @@
-import { IAppNavigationBarState } from '../types/app';
-export declare const useNavigationBar: () => {
-    state: IAppNavigationBarState;
-    pageState: IAppNavigationBarState | undefined;
-    appState: IAppNavigationBarState | undefined;
-    setPageNavigationBar: (navigationBar: Partial<IAppNavigationBarState>) => void;
-    setAppNavigationBar: (navigationBar: Partial<IAppNavigationBarState>) => void;
-    removePageNavigationBar: () => void;
-    removeAppNavigationBar: () => void;
-    resetPageNavigationBar: () => void;
-    resetAppNavigationBar: () => void;
-};

package/dist/components/app/hooks/use-navigation-type.d.ts

@@ -1 +0,0 @@
-export declare const useNavigationType: () => import('..').IHistoryAction;

package/dist/components/app/hooks/use-page-config.d.ts

@@ -1 +0,0 @@
-export declare const usePageConfig: () => import('..').IPageConfig | undefined;

package/dist/components/app/hooks/use-page-layout.d.ts

@@ -1,14 +0,0 @@
-import { IAppPageLayoutState } from '../types/app';
-export declare const usePageLayout: () => {
-    state: IAppPageLayoutState;
-    pageState: IAppPageLayoutState | undefined;
-    appState: IAppPageLayoutState | undefined;
-    setPagePagelayout: (pageLayoutState: Partial<IAppPageLayoutState>) => void;
-    setAppPageLayout: (pageLayoutState: Partial<IAppPageLayoutState>) => void;
-    removePagePagelayout: () => void;
-    removeAppPageLayout: () => void;
-    resetPagePagelayout: () => void;
-    resetAppPageLayout: () => void;
-};
-export declare const usePullToRefresh: (onRefresh: () => Promise<unknown> | unknown) => void;
-export declare const useLoadMore: (onEndReached: () => void) => void;

package/dist/components/app/hooks/use-page-scroll.d.ts

@@ -1,5 +0,0 @@
-import { ThrottleOptions } from 'ahooks/lib/useThrottle/throttleOptions';
-export type IUsePageScrollOptions = {
-    throttle?: ThrottleOptions;
-};
-export declare const usePageScroll: (callback: (target: HTMLDivElement, event: Event) => void, options?: IUsePageScrollOptions) => void;

package/dist/components/app/hooks/use-page-state.d.ts

@@ -1,6 +0,0 @@
-import { Dispatch, SetStateAction } from 'react';
-import { IPageState } from '../types/app';
-export declare const usePageState: () => {
-    pageState: IPageState | undefined;
-    setPageState: Dispatch<SetStateAction<IPageState | undefined>>;
-};

package/dist/components/app/stores/app.d.ts

@@ -1,24 +0,0 @@
-import { IAppConfig, IAppState, IPageState } from '../types/app';
-import { IHistory, INavigate } from '../types/navigation';
-import { EventEmitter } from '../../../utils/event-emitter';
-export type IAppStoreState = {
-    config: IAppConfig;
-    initialized: boolean;
-    appState: IAppState;
-    pageStates: Partial<Record<string, IPageState>>;
-    histories: IHistory[];
-    init: (config: IAppConfig) => void;
-    navigate: INavigate;
-};
-type IBeforeLocationChangeData = {
-    history: IHistory;
-    histories: IHistory[];
-    nextHistory: IHistory;
-    nextHistories: IHistory[];
-};
-export declare const navigationEventEmitter: EventEmitter<{
-    beforeLocationChangeP1: IBeforeLocationChangeData;
-    beforeLocationChangeP2: IBeforeLocationChangeData;
-}>;
-export declare const useAppStore: import('zustand').UseBoundStore<import('zustand').StoreApi<IAppStoreState>>;
-export {};

package/dist/components/app/stores/app.selector.d.ts

@@ -1,11 +0,0 @@
-import { IAppStoreState } from './app';
-export declare const historiesSelector: (state: IAppStoreState) => import('..').IHistory[];
-export declare const lastHistorySelector: (state: IAppStoreState) => import('..').IHistory;
-export declare const historySelector: (locationKey: string | null) => (state: IAppStoreState) => import('..').IHistory | undefined;
-export declare const lastLocationSelector: (state: IAppStoreState) => import('..').ILocation;
-export declare const pageStatesSelector: (state: IAppStoreState) => Partial<Record<string, import('..').IPageState>>;
-export declare const pageStateSelector: (locationKey: string | null) => (state: IAppStoreState) => import('..').IPageState | undefined;
-export declare const lastPageStateSelector: (state: IAppStoreState) => import('..').IPageState | undefined;
-export declare const pageConfigsSelector: (state: IAppStoreState) => import('..').IPageConfig[];
-export declare const pageConfigSelector: (locationKey: string | null) => (state: IAppStoreState) => import('..').IPageConfig | undefined;
-export declare const lastPageConfigSelector: (state: IAppStoreState) => import('..').IPageConfig | undefined;

package/dist/components/app/types/app.d.ts

@@ -1,65 +0,0 @@
-import { ComponentType, PropsWithChildren } from 'react';
-import { INavigationAnimationType } from './navigation';
-import { INavigationBarProps } from '../../navigation-bar';
-import { IBottomTabBarItem, IBottomTabBarProps } from '../../bottom-tab-bar';
-import { IPageBaseProps } from '../../layout';
-export type IAppAnimationState = {
-    type?: INavigationAnimationType;
-};
-export type IAppKeepAliveState = {
-    enable?: boolean;
-    maxStack?: number;
-    freeze?: boolean;
-    freezeDelay?: number;
-};
-export type IAppPageLayoutState = IPageBaseProps & {
-    hidden?: boolean;
-    scrollRestoration?: boolean;
-};
-export type IAppNavigationBarState = INavigationBarProps & {
-    hidden?: boolean;
-};
-export type IAppBottomTabBarState = Partial<Omit<IBottomTabBarProps, 'activeId' | 'items'>> & {
-    items: Array<IBottomTabBarItem & {
-        path: string;
-        params?: Record<string, string>;
-    }>;
-    hidden?: boolean;
-};
-export type ILayout = ComponentType<PropsWithChildren>;
-export type IAppState = {
-    animation?: IAppAnimationState;
-    navigationBar?: IAppNavigationBarState;
-    bottomTabBar?: IAppBottomTabBarState;
-    keepAlive?: IAppKeepAliveState;
-    pageLayout?: IAppPageLayoutState;
-    Layouts?: ILayout[];
-};
-export type IPageState = Omit<IAppState, 'keepAlive'> & {
-    keepAlive?: boolean;
-    freeze?: boolean;
-    freezeDelay?: number;
-};
-export type IPageConfig = {
-    pathname: string;
-    Component: ComponentType;
-    Layouts?: ILayout[];
-    bottomTabBarId?: string;
-} & IPageState;
-export type IDarkModeConfig = {
-    defaultEnabled?: boolean;
-};
-export type IThemeConfig = {
-    defaultMode?: 'dark' | 'light' | 'system';
-};
-export type IAppConfig = {
-    pages: IPageConfig[];
-    theme?: IThemeConfig;
-    /**
-     * @deprecated This will be removed soon. Use `theme.darkMode` instead.
-     */
-    darkMode?: IDarkModeConfig;
-    navigation?: {
-        alwaysRootPage?: boolean;
-    };
-} & IAppState;