@v-miniapp/ui-react 1.0.41 → 1.0.45

package/dist-storybook/assets/MIGRATION_GUIDE-2LONslE4.js

@@ -0,0 +1,449 @@
+import{j as n}from"./iframe-CQAwSt4E.js";import{useMDXComponents as o}from"./index-CgMRTj-o.js";import{b as s}from"./blocks-BuaOUtiH.js";import"./preload-helper-PPVm8Dsz.js";import"./index-DHiZ-gXR.js";function a(i){const e={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",hr:"hr",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...o(),...i.components};return n.jsxs(n.Fragment,{children:[`
+`,`
+`,n.jsx(s,{title:"Migration Guide"}),`
+`,n.jsx(e.h1,{id:"migration-guide-từ-vsf-miniappui-react-sang-v-miniappui-react",children:"Migration Guide: từ @vsf-miniapp/ui-react sang @v-miniapp/ui-react"}),`
+`,n.jsxs(e.p,{children:["Hướng dẫn này giúp bạn migrate từ phiên bản cũ ",n.jsx(e.code,{children:"@vsf-miniapp/ui-react"})," sang phiên bản mới ",n.jsx(e.code,{children:"@v-miniapp/ui-react"})," với nhiều tính năng và cải tiến hơn."]}),`
+`,n.jsx(e.h2,{id:"tổng-quan",children:"Tổng quan"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"@v-miniapp/ui-react"})," là phiên bản mới với nhiều cải tiến:"]}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"App Framework hoàn chỉnh"}),": Routing, navigation, page management được tích hợp sẵn"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Mobile Behaviours"}),": Swipe navigation, pull-to-refresh, keep-alive, scroll restoration"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Multi-language (i18n)"}),": Hệ thống locale với TypeScript type safety"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Nhiều component mới"}),": Bottom tab bar, calendar, date field, và nhiều component khác"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Tính năng nâng cao"}),": Animation, error boundary, toast provider, analytics"]}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"1-cài-đặt",children:"1. Cài đặt"}),`
+`,n.jsx(e.h3,{id:"cũ-vsf-miniappui-react",children:"Cũ (@vsf-miniapp/ui-react)"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-bash",children:`npm install @vsf-miniapp/ui-react
+`})}),`
+`,n.jsx(e.h3,{id:"mới-v-miniappui-react",children:"Mới (@v-miniapp/ui-react)"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-bash",children:`npm install @v-miniapp/ui-react
+`})}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"2-import-styles",children:"2. Import Styles"}),`
+`,n.jsx(e.h3,{id:"cũ",children:"Cũ"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import '@v-miniapp/ui-react/styles.css'
+`})}),`
+`,n.jsx(e.h3,{id:"mới",children:"Mới"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// Option 1: CSS chuẩn
+import '@v-miniapp/ui-react/styles.css'
+
+// Option 2: Tích hợp với Tailwind CSS
+// Trong file tailwind.css
+@import '@v-miniapp/ui-react/tailwind';
+`})}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"3-app-component--routing",children:"3. App Component & Routing"}),`
+`,n.jsx(e.h3,{id:"cũ-sử-dụng-approuter--react-router",children:"Cũ: Sử dụng AppRouter + React Router"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { AppRouter, Route } from '@vsf-miniapp/ui-react'
+
+function MyApp() {
+  return (
+    <AppRouter mode="browser">
+      <Route path="/" element={<HomePage />} />
+      <Route path="/about" element={<AboutPage />} />
+    </AppRouter>
+  )
+}
+`})}),`
+`,n.jsx(e.h3,{id:"mới-sử-dụng-app-framework",children:"Mới: Sử dụng App Framework"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { App, type IAppConfig } from '@v-miniapp/ui-react'
+
+const appConfig: IAppConfig = {
+  pages: [
+    {
+      pathname: '/',
+      Component: HomePage,
+      navigationBar: {
+        title: 'Home',
+      },
+    },
+    {
+      pathname: '/about',
+      Component: AboutPage,
+      navigationBar: {
+        title: 'About',
+        backIcon: true,
+      },
+    },
+  ],
+}
+
+function MyApp() {
+  return <App config={appConfig} />
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"Thay đổi chính:"})}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["❌ Không cần ",n.jsx(e.code,{children:"AppRouter"})," và React Router nữa"]}),`
+`,n.jsxs(e.li,{children:["Sử dụng ",n.jsx(e.code,{children:"App"})," component với ",n.jsx(e.code,{children:"IAppConfig"})]}),`
+`,n.jsx(e.li,{children:"Routing được quản lý tự động bởi framework"}),`
+`,n.jsx(e.li,{children:"Navigation bar được tích hợp sẵn"}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"4-navigation",children:"4. Navigation"}),`
+`,n.jsx(e.h3,{id:"cũ-usenavigate-từ-react-router",children:"Cũ: useNavigate từ React Router"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { useNavigate } from '@vsf-miniapp/ui-react/components/router/hooks'
+
+function MyPage() {
+  const navigate = useNavigate()
+
+  const handleClick = () => {
+    navigate('/about')
+  }
+
+  return <button onClick={handleClick}>Go to About</button>
+}
+`})}),`
+`,n.jsx(e.h3,{id:"mới-usenavigate-từ-v-miniappui-react",children:"Mới: useNavigate từ @v-miniapp/ui-react"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { useNavigate } from '@v-miniapp/ui-react'
+
+function MyPage() {
+  const navigate = useNavigate()
+
+  const handleClick = () => {
+    navigate('/about', {
+      params: { id: '123' },
+      state: { from: 'home' },
+      animation: { type: 'slide_left' },
+    })
+  }
+
+  return <button onClick={handleClick}>Go to About</button>
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"Tính năng mới:"})}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["Hỗ trợ ",n.jsx(e.code,{children:"params"})," (query parameters)"]}),`
+`,n.jsxs(e.li,{children:["Hỗ trợ ",n.jsx(e.code,{children:"state"})," (không hiển thị trong URL)"]}),`
+`,n.jsxs(e.li,{children:["Hỗ trợ ",n.jsx(e.code,{children:"animation"})," override"]}),`
+`,n.jsxs(e.li,{children:["Hỗ trợ ",n.jsx(e.code,{children:"replace"})," option"]}),`
+`,n.jsxs(e.li,{children:["Hỗ trợ navigate bằng delta: ",n.jsx(e.code,{children:"navigate(-1)"})," để back"]}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"5-layout-component",children:"5. Layout Component"}),`
+`,n.jsx(e.h3,{id:"cũ-app-component-chỉ-là-layout-wrapper",children:"Cũ: App component chỉ là layout wrapper"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { App } from '@vsf-miniapp/ui-react/components/layout'
+
+function MyApp() {
+  return (
+    <App mode="light" theme={{ primaryColor: '#3F7DFB' }}>
+      {/* Your content */}
+    </App>
+  )
+}
+`})}),`
+`,n.jsx(e.h3,{id:"mới-app-là-framework-hoàn-chỉnh",children:"Mới: App là framework hoàn chỉnh"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { App, type IAppConfig } from '@v-miniapp/ui-react'
+
+const appConfig: IAppConfig = {
+  // Config pages, navigation, animation, etc.
+  pages: [...],
+  animation: { type: 'slide_left' },
+  keepAlive: { enable: true },
+}
+
+function MyApp() {
+  return <App config={appConfig} />
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"Thay đổi:"})}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["❌ ",n.jsx(e.code,{children:"App"})," không còn là layout wrapper đơn giản"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"App"})," là framework với nhiều tính năng tích hợp"]}),`
+`,n.jsx(e.li,{children:"Theme được quản lý qua CSS variables và dark mode config"}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"6-components-mới",children:"6. Components mới"}),`
+`,n.jsx(e.h3,{id:"navigation-bar",children:"Navigation Bar"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Mới:"})," Component ",n.jsx(e.code,{children:"NavigationBar"})," để tạo navigation bar"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`const appConfig: IAppConfig = {
+  pages: [
+    {
+      pathname: '/',
+      Component: HomePage,
+      navigationBar: {
+        title: 'Home',
+      },
+    },
+    {
+      pathname: '/about',
+      Component: AboutPage,
+      navigationBar: {
+        title: 'About',
+        backIcon: true,
+      },
+    },
+  ],
+  navigationBar: {
+    transparentTitle: "always"
+  }
+}
+`})}),`
+`,n.jsx(e.h3,{id:"bottom-tab-bar",children:"Bottom Tab Bar"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Mới:"})," Component ",n.jsx(e.code,{children:"BottomTabBar"})," để tạo bottom navigation"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`const appConfig: IAppConfig = {
+  bottomTabBar: {
+    items: [
+      {
+        id: 'home',
+        path: '/',
+        title: 'Home',
+        icon: <HomeIcon />,
+      },
+      {
+        id: 'settings',
+        path: '/settings',
+        title: 'Settings',
+        icon: <SettingsIcon />,
+      },
+    ],
+  },
+  pages: [
+    {
+      pathname: '/',
+      Component: HomePage,
+      bottomTabBarId: 'home', // Link với bottom tab bar item
+    },
+    {
+      pathname: '/settings',
+      Component: SettingsPage,
+      bottomTabBarId: 'settings',
+    },
+  ],
+}
+`})}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"7-hooks-mới",children:"7. Hooks mới"}),`
+`,n.jsx(e.h3,{id:"usehistory",children:"useHistory"}),`
+`,n.jsx(e.p,{children:"Lấy history entry hiện tại:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { useHistory } from '@v-miniapp/ui-react'
+
+function MyPage() {
+  const history = useHistory()
+
+  console.log(history.location.pathname) // '/home'
+  console.log(history.location.params) // { id: '123' }
+  console.log(history.action) // 'PUSH' | 'REPLACE' | 'POP'
+}
+`})}),`
+`,n.jsx(e.h3,{id:"uselocation",children:"useLocation"}),`
+`,n.jsx(e.p,{children:"Lấy location object hiện tại:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { useLocation } from '@v-miniapp/ui-react'
+
+function MyPage() {
+  const location = useLocation()
+
+  console.log(location?.pathname) // '/home'
+  console.log(location?.params) // { id: '123' }
+}
+`})}),`
+`,n.jsx(e.h3,{id:"usepageconfig",children:"usePageConfig"}),`
+`,n.jsx(e.p,{children:"Lấy config của page hiện tại:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { usePageConfig } from '@v-miniapp/ui-react'
+
+function MyPage() {
+  const pageConfig = usePageConfig()
+
+  console.log(pageConfig?.pathname) // '/home'
+  console.log(pageConfig?.navigationBar) // Navigation bar config
+}
+`})}),`
+`,n.jsx(e.h3,{id:"usedidshow--usedidhide",children:"useDidShow / useDidHide"}),`
+`,n.jsx(e.p,{children:"Lifecycle hooks cho pages:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { useDidShow, useDidHide } from '@v-miniapp/ui-react'
+
+function MyPage() {
+  useDidShow(() => {
+    console.log('Page is shown')
+    // Fetch data, track analytics
+  })
+
+  useDidHide(() => {
+    console.log('Page is hidden')
+    // Cleanup, pause timers
+  })
+}
+`})}),`
+`,n.jsx(e.h3,{id:"usepulltorefresh--useloadmore",children:"usePullToRefresh / useLoadMore"}),`
+`,n.jsx(e.p,{children:"Hooks cho pull-to-refresh và infinite scroll:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { usePullToRefresh, useLoadMore } from '@v-miniapp/ui-react'
+
+function MyPage() {
+  const handleRefresh = async () => {
+    await fetchData()
+  }
+  usePullToRefresh(handleRefresh)
+
+  const loadMore = async () => {
+    await fetchMoreData()
+  }
+  useLoadMore(loadMore)
+}
+`})}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"8-mobile-behaviours",children:"8. Mobile Behaviours"}),`
+`,n.jsx(e.h3,{id:"swipe-navigation",children:"Swipe Navigation"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Mới:"})," Tự động hỗ trợ swipe từ cạnh màn hình để navigate back/forward"]}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsx(e.li,{children:"Không cần config, hoạt động tự động"}),`
+`,n.jsx(e.li,{children:"Tự động tắt animation khi swipe để tránh conflict"}),`
+`]}),`
+`,n.jsx(e.h3,{id:"pull-to-refresh",children:"Pull to Refresh"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Mới:"})," Hỗ trợ pull-to-refresh tích hợp sẵn"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// Sử dụng hook
+import { usePullToRefresh } from '@v-miniapp/ui-react'
+
+function MyPage() {
+  usePullToRefresh(async () => {
+    await fetchData()
+  })
+}
+
+// Hoặc sử dụng page layout config
+const appConfig: IAppConfig = {
+  pages: [
+    {
+      pathname: '/home',
+      Component: HomePage,
+      pageLayout: {
+        pullToRefresh: {
+          onRefresh: async () => {
+            await fetchData()
+          },
+        },
+      },
+    },
+  ],
+}
+`})}),`
+`,n.jsx(e.h3,{id:"keep-alive",children:"Keep Alive"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Mới:"})," Giữ state và scroll position của pages khi navigate"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`const appConfig: IAppConfig = {
+  keepAlive: {
+    enable: true,
+    maxStack: 5,
+    freeze: true,
+    freezeDelay: 3000,
+  },
+  pages: [
+    {
+      pathname: '/list',
+      Component: ListPage,
+      keepAlive: true, // Override cho page này
+    },
+  ],
+}
+`})}),`
+`,n.jsx(e.h3,{id:"animation",children:"Animation"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Mới:"})," Animation chuyển trang giữa các pages"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`const appConfig: IAppConfig = {
+  animation: {
+    type: 'slide_left', // 'none' | 'slide_up' | 'slide_left' | 'fade_in'
+  },
+  pages: [
+    {
+      pathname: '/detail',
+      Component: DetailPage,
+      animation: {
+        type: 'fade_in', // Override cho page này
+      },
+    },
+  ],
+}
+`})}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"9-multi-language-i18n",children:"9. Multi-language (i18n)"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Mới:"})," Hệ thống locale với TypeScript type safety"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { App, type IAppConfig, type ILocalesConfig } from '@v-miniapp/ui-react'
+
+// Declare custom locales trong global.d.ts
+// global.d.ts
+declare module '@v-miniapp/ui-react' {
+  interface ICustomLocales {
+    resource: typeof vi
+    language: 'jp' | 'en' | 'vi'
+  }
+}
+
+import vi from './locales/vi.json'
+import en from './locales/en.json'
+import jp from './locales/jp.json'
+
+const localesConfig: ILocalesConfig = {
+  resources: {
+    vi,
+    en,
+    jp,
+  },
+}
+
+const appConfig: IAppConfig = {
+  pages: [...],
+}
+
+function MyApp() {
+  return <App config={appConfig} localesConfig={localesConfig} />
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"Sử dụng trong components:"})}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { useTranslate, useLanguage } from '@v-miniapp/ui-react'
+
+function MyPage() {
+  const t = useTranslate()
+  const { language, setLanguage } = useLanguage()
+
+  return (
+    <div>
+      <div>{t('hello')}</div>
+      <button onClick={() => setLanguage('en')}>English</button>
+      <button onClick={() => setLanguage('jp')}>日本語</button>
+    </div>
+  )
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"Thay đổi:"})}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"localeConfig"})," → ",n.jsx(e.code,{children:"localesConfig"})]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"ILocaleConfig"})," → ",n.jsx(e.code,{children:"ILocalesConfig"})]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"locales"})," → ",n.jsx(e.code,{children:"resources"})]}),`
+`,n.jsxs(e.li,{children:["Sử dụng module augmentation (",n.jsx(e.code,{children:"ICustomLocales"}),") trong ",n.jsx(e.code,{children:"global.d.ts"})," thay vì generic parameters"]}),`
+`]}),`
+`,n.jsxs(e.p,{children:["Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-locale--docs",children:"Locale Function"})]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"10-breaking-changes",children:"10. Breaking Changes"}),`
+`,n.jsx(e.h3,{id:"1-app-component",children:"1. App Component"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["❌ ",n.jsx(e.code,{children:"App"})," không còn là layout wrapper đơn giản"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"App"})," là framework với config-based approach"]}),`
+`]}),`
+`,n.jsx(e.h3,{id:"2-routing",children:"2. Routing"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsx(e.li,{children:"❌ Không sử dụng React Router nữa"}),`
+`,n.jsx(e.li,{children:"Sử dụng built-in routing system của App framework"}),`
+`]}),`
+`,n.jsx(e.h3,{id:"3-navigation",children:"3. Navigation"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["❌ ",n.jsx(e.code,{children:"useNavigate"})," từ React Router"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"useNavigate"})," từ ",n.jsx(e.code,{children:"@v-miniapp/ui-react"})," với API khác"]}),`
+`]}),`
+`,n.jsx(e.h3,{id:"4-components",children:"4. Components"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsx(e.li,{children:"❌ Một số component đã đổi tên (Rate → Rating)"}),`
+`,n.jsx(e.li,{children:"Nhiều component mới được thêm vào"}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"11-migration-checklist",children:"11. Migration Checklist"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["[ ] Cài đặt ",n.jsx(e.code,{children:"@v-miniapp/ui-react"})]}),`
+`,n.jsx(e.li,{children:"[ ] Cập nhật import statements"}),`
+`,n.jsxs(e.li,{children:["[ ] Thay thế ",n.jsx(e.code,{children:"AppRouter"})," + React Router bằng ",n.jsx(e.code,{children:"App"})," framework"]}),`
+`,n.jsxs(e.li,{children:["[ ] Cập nhật ",n.jsx(e.code,{children:"useNavigate"})," usage"]}),`
+`,n.jsxs(e.li,{children:["[ ] Cập nhật ",n.jsx(e.code,{children:"App"})," component usage"]}),`
+`,n.jsxs(e.li,{children:["[ ] Thay thế ",n.jsx(e.code,{children:"Rate"})," bằng ",n.jsx(e.code,{children:"Rating"})," (nếu có)"]}),`
+`,n.jsx(e.li,{children:"[ ] Thêm config cho mobile behaviours (keep-alive, animation, etc.)"}),`
+`,n.jsx(e.li,{children:"[ ] Thêm locale config (nếu cần multi-language)"}),`
+`,n.jsx(e.li,{children:"[ ] Test navigation và routing"}),`
+`,n.jsx(e.li,{children:"[ ] Test mobile behaviours (swipe, pull-to-refresh, etc.)"}),`
+`]})]})}function p(i={}){const{wrapper:e}={...o(),...i.components};return e?n.jsx(e,{...i,children:n.jsx(a,{...i})}):a(i)}export{p as default};

package/dist-storybook/assets/MOBILE_BEHAVIOURS-DZ6alKTX.js

@@ -0,0 +1,177 @@
+import{j as n}from"./iframe-CQAwSt4E.js";import{useMDXComponents as h}from"./index-CgMRTj-o.js";import{b as r,M as s}from"./blocks-BuaOUtiH.js";import"./preload-helper-PPVm8Dsz.js";import"./index-DHiZ-gXR.js";function t(i){const e={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",hr:"hr",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...h(),...i.components};return n.jsxs(n.Fragment,{children:[`
+`,`
+`,n.jsx(r,{title:"App Framework/Mobile Behaviours"}),`
+`,n.jsx(e.h1,{id:"mobile-behaviours",children:"Mobile Behaviours"}),`
+`,n.jsxs(e.p,{children:["Component ",n.jsx(e.code,{children:"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 và mượt mà."]}),`
+`,n.jsx(e.h2,{id:"tổng-quan",children:"Tổng quan"}),`
+`,n.jsxs(e.p,{children:["Các behaviours sau đã được implement sẵn trong ",n.jsx(e.code,{children:"App"}),":"]}),`
+`,n.jsxs(e.ol,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Swipe Navigation"})," - Swipe từ cạnh màn hình để navigate back/forward"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Pull to Refresh"})," - Kéo xuống để refresh page"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Keep Alive"})," - Giữ state và scroll position của page khi navigate. Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-keep-alive--docs",children:"Keep Alive Config"})]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Scroll Restoration"})," - Tự động khôi phục scroll position khi navigate back"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Page Stacking"})," - Stack các pages giống native app với keep-alive"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Animation"})," - Animation chuyển trang giữa các pages. Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-animation--docs",children:"Animation Config"})]}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"1-swipe-navigation",children:"1. Swipe Navigation"}),`
+`,n.jsx(e.p,{children:"Swipe navigation cho phép user swipe từ cạnh màn hình để navigate back/forward, giống như native app iOS/Android."}),`
+`,n.jsx(e.h3,{id:"cách-hoạt-động",children:"Cách hoạt động"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Phát hiện gesture"}),": Hệ thống phát hiện swipe gesture từ cạnh trái hoặc phải màn hình"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Tự động tắt animation"}),": Khi phát hiện swipe gesture, animation chuyển trang sẽ tự động bị tắt để tránh conflict với gesture animation tự nhiên"]}),`
+`]}),`
+`,n.jsx(e.h3,{id:"lưu-ý",children:"Lưu ý"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsx(e.li,{children:"Swipe navigation hoạt động tự động, không cần config"}),`
+`,n.jsx(e.li,{children:"Chỉ hoạt động trên mobile/touch devices"}),`
+`,n.jsxs(e.li,{children:["Animation sẽ tự động tắt khi swipe để tránh conflict. Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-animation--docs",children:"Animation Config"})]}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"2-pull-to-refresh",children:"2. Pull to Refresh"}),`
+`,n.jsx(e.p,{children:"Pull to Refresh cho phép user kéo xuống để refresh page, giống như native app."}),`
+`,n.jsx(e.h3,{id:"cách-sử-dụng",children:"Cách sử dụng"}),`
+`,n.jsxs(e.h4,{id:"sử-dụng-hook-usepulltorefresh",children:["Sử dụng Hook ",n.jsx(e.code,{children:"usePullToRefresh"})]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { usePullToRefresh } from '@v-miniapp/ui-react'
+
+const MyPage: FC = () => {
+  const handleRefresh = async () => {
+    // Fetch data mới
+    await fetchData()
+  }
+
+  usePullToRefresh(handleRefresh)
+
+  return <div>Page content</div>
+}
+`})}),`
+`,n.jsx(e.h4,{id:"sử-dụng-page-layout-config",children:"Sử dụng Page Layout Config"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`const appConfig: IAppConfig = {
+  pages: [
+    {
+      pathname: '/home',
+      Component: HomePage,
+      pageLayout: {
+        pullToRefresh: {
+          onRefresh: async () => {
+            // Fetch data mới
+            await fetchData()
+          },
+          pullingText: 'Kéo xuống để làm mới',
+          canReleaseText: 'Thả để làm mới',
+          refreshingText: 'Đang tải...',
+          completeText: 'Làm mới thành công',
+        },
+      },
+    },
+  ],
+}
+`})}),`
+`,n.jsx(e.h3,{id:"options",children:"Options"}),`
+`,n.jsx(s,{children:"\n| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |\n| :--- | :--- | :--- | :--- |\n| `onRefresh` | `() => Promise<unknown> \\| unknown` | - | Function được gọi khi refresh. Phải return Promise |\n| `pullingText` | `ReactNode` | `'Kéo xuống để làm mới'` | Text hiển thị khi đang kéo |\n| `canReleaseText` | `ReactNode` | `'Thả để làm mới'` | Text hiển thị khi đã đủ threshold |\n| `refreshingText` | `ReactNode` | `'Đang tải...'` | Text hiển thị khi đang refresh |\n| `completeText` | `ReactNode` | `'Làm mới thành công'` | Text hiển thị sau khi refresh xong |\n| `completeDelay` | `number` | `500` | Delay (ms) trước khi reset sau khi complete |\n| `headHeight` | `number` | `40` | Chiều cao của refresh head (px) |\n| `threshold` | `number` | `60` | Khoảng cách kéo tối thiểu để trigger refresh (px) |\n| `disabled` | `boolean` | `false` | Tắt pull to refresh |\n| `renderText` | `(status: IPullToRefreshStatus) => ReactNode` | - | Custom render function cho text theo status |\n"}),`
+`,n.jsx(e.h3,{id:"các-trạng-thái",children:"Các trạng thái"}),`
+`,n.jsx(s,{children:"\n| Trạng thái | Mô tả |\n| :--- | :--- |\n| `pulling` | User đang kéo xuống nhưng chưa đủ threshold |\n| `canRelease` | User đã kéo đủ threshold, có thể thả để refresh |\n| `refreshing` | Đang thực hiện refresh (đang chạy `onRefresh`) |\n| `complete` | Refresh hoàn thành |\n"}),`
+`,n.jsx(e.h3,{id:"lưu-ý-1",children:"Lưu ý"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["Pull to refresh chỉ hoạt động khi scroll ở ",n.jsx(e.strong,{children:"top"})," (scrollTop = 0)"]}),`
+`,n.jsxs(e.li,{children:["Sử dụng ",n.jsx(e.strong,{children:"rubberband effect"})," để tạo cảm giác tự nhiên khi kéo quá threshold"]}),`
+`,n.jsx(e.li,{children:"Tự động prevent default scroll behavior khi đang pull"}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"3-keep-alive",children:"3. Keep Alive"}),`
+`,n.jsx(e.p,{children:"Keep Alive giữ các pages trong DOM (ẩn) thay vì unmount khi navigate, giúp giữ state và scroll position."}),`
+`,n.jsx(e.h3,{id:"cách-hoạt-động-1",children:"Cách hoạt động"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Giữ trong DOM"}),": Pages được ẩn (",n.jsx(e.code,{children:"display: none"}),") nhưng vẫn trong DOM"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Freeze"}),": Sử dụng ",n.jsx(e.code,{children:"react-freeze"})," để prevent re-render cho pages không hiển thị"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Giới hạn"}),": Chỉ giữ tối đa ",n.jsx(e.code,{children:"maxStack"})," pages trong DOM"]}),`
+`]}),`
+`,n.jsx(e.h3,{id:"cấu-hình",children:"Cấu hình"}),`
+`,n.jsxs(e.p,{children:["Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-keep-alive--docs",children:"Keep Alive Config"})]}),`
+`,n.jsx(e.h3,{id:"lợi-ích",children:"Lợi ích"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Giữ state"}),": Component state không bị mất khi navigate"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Giữ scroll position"}),": Scroll position được giữ nguyên (kết hợp với scroll restoration)"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Form data"}),": Form data không bị mất khi navigate back"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Performance"}),": Không cần re-render khi navigate back/forward"]}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"4-scroll-restoration",children:"4. Scroll Restoration"}),`
+`,n.jsx(e.p,{children:"Scroll Restoration tự động khôi phục scroll position khi navigate back đến page đã từng visit."}),`
+`,n.jsx(e.h3,{id:"cách-hoạt-động-2",children:"Cách hoạt động"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Lưu scroll position"}),": Khi navigate đi, scroll position được lưu vào cache với key là ",n.jsx(e.code,{children:"location.key"})]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Khôi phục scroll"}),": Khi navigate back, scroll position được khôi phục từ cache"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Manual management"}),": Sử dụng ",n.jsx(e.code,{children:"window.history.scrollRestoration = 'manual'"})," để tắt auto scroll restoration của browser"]}),`
+`]}),`
+`,n.jsx(e.h3,{id:"cấu-hình-1",children:"Cấu hình"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`const appConfig: IAppConfig = {
+  pages: [
+    {
+      pathname: '/list',
+      Component: ListPage,
+      pageLayout: {
+        scrollRestoration: true,  // Bật scroll restoration cho page này
+      },
+    },
+  ],
+}
+`})}),`
+`,n.jsx(e.h3,{id:"lưu-ý-2",children:"Lưu ý"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["Scroll restoration chỉ hoạt động khi ",n.jsx(e.code,{children:"scrollRestoration: true"})," trong page layout config"]}),`
+`,n.jsxs(e.li,{children:["Scroll position được lưu theo ",n.jsx(e.code,{children:"location.key"})," (unique cho mỗi lần visit)"]}),`
+`,n.jsxs(e.li,{children:["Kết hợp với Keep Alive để đạt hiệu quả tốt nhất. Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-keep-alive--docs",children:"Keep Alive Config"})]}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"5-page-stacking",children:"5. Page Stacking"}),`
+`,n.jsx(e.p,{children:"Page Stacking là cơ chế stack các pages giống native app, cho phép navigate back/forward qua history stack."}),`
+`,n.jsx(e.h3,{id:"cách-hoạt-động-3",children:"Cách hoạt động"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"History Stack"}),": Mỗi lần navigate tạo một entry mới trong history stack"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Stack Management"}),": Pages được stack và quản lý theo thứ tự LIFO (Last In First Out)"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Keep Alive Integration"}),": Pages trong stack được keep-alive để giữ state. Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-keep-alive--docs",children:"Keep Alive Config"})]}),`
+`]}),`
+`,n.jsx(e.h3,{id:"ví-dụ",children:"Ví dụ"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// User navigate: Home → List → Detail
+// History stack: [Home, List, Detail]
+// Current page: Detail
+
+// User navigate back
+navigate(-1)  // → List
+// History stack: [Home, List, Detail]
+// Current page: List (từ stack)
+
+// User navigate back lần nữa
+navigate(-1)  // → Home
+// History stack: [Home, List, Detail]
+// Current page: Home (từ stack)
+`})}),`
+`,n.jsx(e.h3,{id:"lưu-ý-3",children:"Lưu ý"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["Pages trong stack được keep-alive (nếu enabled). Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-keep-alive--docs",children:"Keep Alive Config"})]}),`
+`,n.jsx(e.li,{children:"Scroll position được restore khi navigate back (nếu scrollRestoration enabled)"}),`
+`,n.jsxs(e.li,{children:["Stack size bị giới hạn bởi ",n.jsx(e.code,{children:"keepAlive.maxStack"})]}),`
+`]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"6-animation",children:"6. Animation"}),`
+`,n.jsx(e.p,{children:"Animation chuyển trang giữa các pages, hỗ trợ các loại animation như slide, fade."}),`
+`,n.jsx(e.h3,{id:"cách-hoạt-động-4",children:"Cách hoạt động"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"View Transition API"}),": Sử dụng View Transition API của browser để tạo animation mượt mà"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Tự động tắt khi swipe"}),": Animation tự động tắt khi phát hiện swipe gesture để tránh conflict"]}),`
+`]}),`
+`,n.jsx(e.h3,{id:"cấu-hình-2",children:"Cấu hình"}),`
+`,n.jsxs(e.p,{children:["Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-animation--docs",children:"Animation Config"})]}),`
+`,n.jsx(e.hr,{}),`
+`,n.jsx(e.h2,{id:"tổng-kết",children:"Tổng kết"}),`
+`,n.jsx(e.p,{children:"Các mobile behaviours trên giúp Mini App có trải nghiệm giống native app:"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["✅ ",n.jsx(e.strong,{children:"Swipe Navigation"}),": Navigate tự nhiên bằng gesture"]}),`
+`,n.jsxs(e.li,{children:["✅ ",n.jsx(e.strong,{children:"Pull to Refresh"}),": Refresh page bằng gesture kéo xuống"]}),`
+`,n.jsxs(e.li,{children:["✅ ",n.jsx(e.strong,{children:"Keep Alive"}),": Giữ state và scroll position. Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-keep-alive--docs",children:"Keep Alive Config"})]}),`
+`,n.jsxs(e.li,{children:["✅ ",n.jsx(e.strong,{children:"Scroll Restoration"}),": Tự động khôi phục scroll position"]}),`
+`,n.jsxs(e.li,{children:["✅ ",n.jsx(e.strong,{children:"Page Stacking"}),": Stack pages giống native app"]}),`
+`,n.jsxs(e.li,{children:["✅ ",n.jsx(e.strong,{children:"Animation"}),": Animation chuyển trang mượt mà. Xem chi tiết tại ",n.jsx(e.a,{href:"?path=/docs/app-framework-animation--docs",children:"Animation Config"})]}),`
+`]}),`
+`,n.jsxs(e.p,{children:["Tất cả các behaviours này đã được tích hợp sẵn trong component ",n.jsx(e.code,{children:"App"}),", bạn chỉ cần config và sử dụng!"]})]})}function g(i={}){const{wrapper:e}={...h(),...i.components};return e?n.jsx(e,{...i,children:n.jsx(t,{...i})}):t(i)}export{g as default};