@v-miniapp/ui-react 1.0.41 → 1.0.45

package/dist-storybook/assets/KEEP_ALIVE-CL2au0al.js

@@ -0,0 +1,126 @@
+import{j as e}from"./iframe-CQAwSt4E.js";import{useMDXComponents as a}from"./index-CgMRTj-o.js";import{b as l,M as t}from"./blocks-BuaOUtiH.js";import"./preload-helper-PPVm8Dsz.js";import"./index-DHiZ-gXR.js";function r(i){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...a(),...i.components};return e.jsxs(e.Fragment,{children:[`
+`,`
+`,e.jsx(l,{title:"App Framework/Keep Alive"}),`
+`,e.jsx(n.h1,{id:"keep-alive",children:"Keep Alive"}),`
+`,e.jsx(n.p,{children:"Keep Alive cho phép giữ các pages trong DOM (ẩn) thay vì unmount khi navigate, giúp giữ state và scroll position."}),`
+`,e.jsx(n.h2,{id:"cấu-trúc",children:"Cấu trúc"}),`
+`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-typescript",children:`type IAppKeepAliveState = {
+  enable?: boolean
+  maxStack?: number
+  freeze?: boolean
+  freezeDelay?: number
+}
+
+// Page-level có thể override bằng boolean hoặc config object
+type IPageState = {
+  keepAlive?: boolean | IAppKeepAliveState
+  freeze?: boolean
+  freezeDelay?: number
+}
+`})}),`
+`,e.jsx(n.h2,{id:"thuộc-tính",children:"Thuộc tính"}),`
+`,e.jsx(t,{children:"\n| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |\n| :--- | :--- | :--- | :--- |\n| `enable` | `boolean` | `true` | Bật/tắt keep-alive |\n| `maxStack` | `number` | `5` | Số lượng pages tối đa được giữ trong DOM |\n| `freeze` | `boolean` | `true` | Bật/tắt freeze (ngăn re-render cho pages không hiển thị) |\n| `freezeDelay` | `number` | `3000` | Delay (ms) trước khi freeze page sau khi navigate đi |\n"}),`
+`,e.jsx(n.h2,{id:"cách-hoạt-động",children:"Cách hoạt động"}),`
+`,e.jsxs(n.ol,{children:[`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Khi navigate đi"}),": Page được ẩn (",e.jsx(n.code,{children:"display: none"}),") nhưng vẫn trong DOM"]}),`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Khi navigate đến"}),": Page được hiển thị (",e.jsx(n.code,{children:"display: block"}),")"]}),`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Freeze"}),": Các pages không hiển thị được freeze bằng ",e.jsx(n.code,{children:"Freeze"})," component để tránh re-render. Freeze được áp dụng sau ",e.jsx(n.code,{children:"freezeDelay"})," (mặc định: 3000ms) để cho phép animation hoàn thành."]}),`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Giới hạn"}),": Chỉ giữ tối đa ",e.jsx(n.code,{children:"maxStack"})," pages trong DOM"]}),`
+`]}),`
+`,e.jsx(n.h2,{id:"cấu-hình",children:"Cấu hình"}),`
+`,e.jsx(n.h3,{id:"app-level-config",children:"App-level Config"}),`
+`,e.jsx(n.p,{children:"Cấu hình keep-alive mặc định cho tất cả pages:"}),`
+`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-tsx",children:`const appConfig: IAppConfig = {
+  keepAlive: {
+    enable: true,      // Bật keep-alive
+    maxStack: 5,       // Giữ tối đa 5 pages
+    freeze: true,      // Bật freeze để tránh re-render
+    freezeDelay: 3000, // Freeze sau 3 giây
+  },
+  pages: [
+    // Tất cả pages sẽ được keep-alive
+  ],
+}
+`})}),`
+`,e.jsx(n.h3,{id:"page-level-config",children:"Page-level Config"}),`
+`,e.jsx(n.p,{children:"Override keep-alive cho từng page cụ thể:"}),`
+`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-tsx",children:`const appConfig: IAppConfig = {
+  keepAlive: {
+    enable: true,
+    maxStack: 5,
+  },
+  pages: [
+    {
+      pathname: '/home',
+      Component: HomePage,
+      // Page này dùng app-level config (keep-alive enabled)
+    },
+    {
+      pathname: '/login',
+      Component: LoginPage,
+      // Tắt keep-alive cho page này
+      keepAlive: false,
+    },
+    {
+      pathname: '/detail',
+      Component: DetailPage,
+      // Override config cho page này
+      keepAlive: {
+        enable: true,
+        maxStack: 3, // Giữ ít hơn pages khác
+      },
+      // Tắt freeze cho page này (vẫn keep-alive nhưng không freeze)
+      freeze: false,
+    },
+    {
+      pathname: '/video',
+      Component: VideoPage,
+      keepAlive: true,
+      // Freeze ngay lập tức (không delay)
+      freeze: true,
+      freezeDelay: 0,
+    },
+  ],
+}
+`})}),`
+`,e.jsx(n.h2,{id:"lợi-ích",children:"Lợi ích"}),`
+`,e.jsxs(n.ul,{children:[`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Giữ state"}),": Component state không bị mất khi navigate"]}),`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Giữ scroll position"}),": Scroll position được giữ nguyên (kết hợp với ",e.jsx(n.code,{children:"scrollRestoration"}),")"]}),`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Form data"}),": Form data không bị mất khi navigate back"]}),`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Performance"}),": Không cần re-render khi navigate back/forward"]}),`
+`]}),`
+`,e.jsx(n.h2,{id:"lưu-ý",children:"Lưu ý"}),`
+`,e.jsxs(n.ul,{children:[`
+`,e.jsx(n.li,{children:"Pages được giữ trong DOM nên vẫn tốn memory"}),`
+`,e.jsxs(n.li,{children:[e.jsx(n.code,{children:"maxStack"})," giới hạn số pages để tránh tốn quá nhiều memory"]}),`
+`,e.jsx(n.li,{children:"Chỉ pages trong stack (theo thứ tự) mới được keep-alive"}),`
+`,e.jsxs(n.li,{children:["Pages ngoài ",e.jsx(n.code,{children:"maxStack"})," sẽ bị unmount"]}),`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Freeze"}),": Khi ",e.jsx(n.code,{children:"freeze: true"}),", pages không hiển thị sẽ bị freeze để tránh re-render, giúp tiết kiệm performance"]}),`
+`,e.jsxs(n.li,{children:[e.jsx(n.strong,{children:"Freeze Delay"}),": ",e.jsx(n.code,{children:"freezeDelay"})," cho phép animation hoàn thành trước khi freeze. Nếu set ",e.jsx(n.code,{children:"0"}),", page sẽ freeze ngay lập tức"]}),`
+`]}),`
+`,e.jsx(n.h2,{id:"ví-dụ",children:"Ví dụ"}),`
+`,e.jsx(n.pre,{children:e.jsx(n.code,{className:"language-tsx",children:`const appConfig: IAppConfig = {
+  keepAlive: {
+    enable: true,
+    maxStack: 5,
+  },
+  pages: [
+    {
+      pathname: '/home',
+      Component: HomePage,
+      // Keep-alive enabled
+    },
+    {
+      pathname: '/list',
+      Component: ListPage,
+      // Keep-alive enabled, giữ scroll position khi back
+    },
+    {
+      pathname: '/login',
+      Component: LoginPage,
+      keepAlive: false, // Tắt keep-alive, reset mỗi lần vào
+    },
+  ],
+}
+`})})]})}function g(i={}){const{wrapper:n}={...a(),...i.components};return n?e.jsx(n,{...i,children:e.jsx(r,{...i})}):r(i)}export{g as default};

package/dist-storybook/assets/LOCALE-XTCey55y.js

@@ -0,0 +1,465 @@
+import{j as n}from"./iframe-CQAwSt4E.js";import{useMDXComponents as i}from"./index-CgMRTj-o.js";import{b as l,M as t}from"./blocks-BuaOUtiH.js";import"./preload-helper-PPVm8Dsz.js";import"./index-DHiZ-gXR.js";function c(s){const e={code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...i(),...s.components};return n.jsxs(n.Fragment,{children:[`
+`,`
+`,n.jsx(l,{title:"App Framework/Locale"}),`
+`,n.jsx(e.h1,{id:"locales-module-multi-language",children:"Locales Module (Multi-language)"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Locales module"})," của ",n.jsx(e.code,{children:"@v-miniapp/ui-react"})," cung cấp giải pháp quản lý đa ngôn ngữ (i18n) mạnh mẽ với TypeScript type safety, hỗ trợ custom locales keys và custom language codes thông qua module augmentation."]}),`
+`,n.jsx(e.h2,{id:"giới-thiệu",children:"Giới thiệu"}),`
+`,n.jsx(e.p,{children:"Locales module cho phép bạn:"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsx(e.li,{children:"Quản lý translations cho nhiều ngôn ngữ"}),`
+`,n.jsx(e.li,{children:"Type-safe với TypeScript thông qua module augmentation"}),`
+`,n.jsx(e.li,{children:"Tự động cập nhật UI khi ngôn ngữ thay đổi (reactivity)"}),`
+`,n.jsx(e.li,{children:"Hỗ trợ template parameters trong translations"}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Sử dụng độc lập"})," hoặc ",n.jsx(e.strong,{children:"tích hợp sẵn với App component"})]}),`
+`]}),`
+`,n.jsx(e.h2,{id:"tính-năng",children:"Tính năng"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Type-safe"}),": TypeScript tự động infer types cho locales keys và language codes từ module augmentation"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Default languages"}),": Hỗ trợ sẵn tiếng Việt (",n.jsx(e.code,{children:"vi"}),") và tiếng Anh (",n.jsx(e.code,{children:"en"}),")"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Default translations"}),": Có sẵn các translation keys mặc định cho các component (pull-to-refresh, calendar, etc.)"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Custom languages"}),": Dễ dàng thêm ngôn ngữ mới (ví dụ: ",n.jsx(e.code,{children:"jp"}),", ",n.jsx(e.code,{children:"ko"}),", ",n.jsx(e.code,{children:"zh"}),") thông qua module augmentation"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Custom keys"}),": Mở rộng locales keys tùy chỉnh với type checking"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Template params"}),": Hỗ trợ template parameters trong translations"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"URL-based init"}),": Tự động lấy ngôn ngữ từ URL search params (",n.jsx(e.code,{children:"langCode"}),")"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Multiple APIs"}),": Hỗ trợ hooks (",n.jsx(e.code,{children:"useTranslate"}),", ",n.jsx(e.code,{children:"useLanguage"}),"), và standalone functions"]}),`
+`]}),`
+`,n.jsx(e.h2,{id:"text-mặc-định",children:"Text mặc định"}),`
+`,n.jsx(e.p,{children:"Locales module đã có sẵn các translation keys mặc định cho các component:"}),`
+`,n.jsx(e.h3,{id:"pull-to-refresh",children:"Pull to Refresh"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"pullToRefresh.canReleaseText"}),': "Thả để làm mới" (vi) / "Release to refresh" (en)']}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"pullToRefresh.completeText"}),': "Làm mới hoàn tất" (vi) / "Refresh complete" (en)']}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"pullToRefresh.pullingText"}),': "Kéo để làm mới" (vi) / "Pulling to refresh" (en)']}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"pullToRefresh.refreshingText"}),': "Đang làm mới..." (vi) / "Refreshing..." (en)']}),`
+`]}),`
+`,n.jsx(e.h3,{id:"calendar",children:"Calendar"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"calendar.monthLabel[0-11]"}),": Tên các tháng (Tháng 1-12 / January-December)"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"calendar.weekdayLabel[0-6]"}),": Tên các ngày trong tuần (CN-T7 / Sun-Sat)"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"calendar.headerLabel"}),": `{month} - {year}` - Template cho header"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"calendar.weekday"}),": `{day}` - Template cho weekday"]}),`
+`]}),`
+`,n.jsxs(e.p,{children:["Bạn có thể override các keys này hoặc thêm keys mới trong ",n.jsx(e.code,{children:"localesConfig"}),"."]}),`
+`,n.jsx(e.h2,{id:"khởi-tạo-initialization",children:"Khởi tạo (Initialization)"}),`
+`,n.jsx(e.p,{children:"Locales module có thể được sử dụng theo 2 cách:"}),`
+`,n.jsxs(e.ol,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Tích hợp sẵn với App component"})," (Khuyến nghị) - App component đã tích hợp sẵn ",n.jsx(e.code,{children:"LocalesProvider"})]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Sử dụng độc lập"})," - Sử dụng ",n.jsx(e.code,{children:"LocalesProvider"})," trực tiếp trong ứng dụng của bạn"]}),`
+`]}),`
+`,n.jsx(e.h3,{id:"sử-dụng-với-app-component-khuyến-nghị",children:"Sử dụng với App Component (Khuyến nghị)"}),`
+`,n.jsxs(e.p,{children:["App component đã tích hợp sẵn ",n.jsx(e.code,{children:"LocalesProvider"}),", bạn chỉ cần truyền ",n.jsx(e.code,{children:"localesConfig"}),":"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { App, type IAppConfig, type ILocalesConfig } from '@v-miniapp/ui-react'
+
+const appConfig: IAppConfig = {
+  pages: [
+    // ... your pages
+  ],
+}
+
+// Cấu hình locales
+const localesConfig: ILocalesConfig = {
+  defaultLanguage: 'vi', // hoặc 'en', hoặc 'system'
+  resources: {
+    vi: {
+      'app.title': 'Ứng dụng của tôi',
+      'app.description': 'Mô tả ứng dụng',
+    },
+    en: {
+      'app.title': 'My Application',
+      'app.description': 'Application description',
+    },
+  },
+}
+
+export function MiniApp() {
+  return <App config={appConfig} localesConfig={localesConfig} />
+}
+`})}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Thứ tự ưu tiên ngôn ngữ:"})," Locales module sẽ lấy ngôn ngữ theo thứ tự ưu tiên:"]}),`
+`,n.jsxs(e.ol,{children:[`
+`,n.jsxs(e.li,{children:["Từ config (",n.jsx(e.code,{children:"defaultLanguage"}),")"]}),`
+`,n.jsxs(e.li,{children:["Từ URL search params (",n.jsx(e.code,{children:"langCode"}),")"]}),`
+`,n.jsxs(e.li,{children:["Mặc định tiếng Việt (",n.jsx(e.code,{children:"'vi'"}),")"]}),`
+`]}),`
+`,n.jsxs(e.p,{children:["Ví dụ: Nếu không có ",n.jsx(e.code,{children:"defaultLanguage"})," trong config, URL ",n.jsx(e.code,{children:"https://yourapp.com?langCode=en"})," sẽ tự động set ngôn ngữ thành ",n.jsx(e.code,{children:"'en'"}),". Nếu không có trong URL, sẽ fallback về ",n.jsx(e.code,{children:"'vi'"}),"."]}),`
+`,n.jsx(e.h3,{id:"sử-dụng-localesprovider-độc-lập",children:"Sử dụng LocalesProvider độc lập"}),`
+`,n.jsxs(e.p,{children:["Nếu không sử dụng App component, bạn có thể sử dụng ",n.jsx(e.code,{children:"LocalesProvider"})," trực tiếp:"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { LocalesProvider, type ILocalesConfig } from '@v-miniapp/ui-react'
+
+const localesConfig: ILocalesConfig = {
+  defaultLanguage: 'vi',
+  resources: {
+    vi: {
+      'app.title': 'Ứng dụng của tôi',
+    },
+    en: {
+      'app.title': 'My Application',
+    },
+  },
+}
+
+function MyApp() {
+  return (
+    <>
+      <LocalesProvider config={localesConfig} />
+      {/* Your app content */}
+    </>
+  )
+}
+`})}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Lưu ý:"})," ",n.jsx(e.code,{children:"LocalesProvider"})," chỉ init một lần khi mount, nên cần đặt ở top-level của ứng dụng."]}),`
+`,n.jsx(e.h2,{id:"mở-rộng-với-custom-languages-và-locales-keys",children:"Mở rộng với Custom Languages và Locales Keys"}),`
+`,n.jsxs(e.p,{children:["Bạn có thể thêm các ngôn ngữ tùy chỉnh ngoài ",n.jsx(e.code,{children:"vi"})," và ",n.jsx(e.code,{children:"en"}),", đồng thời định nghĩa custom locales keys với type safety thông qua ",n.jsx(e.strong,{children:"module augmentation"})," trong ",n.jsx(e.code,{children:"global.d.ts"}),":"]}),`
+`,n.jsx(e.h3,{id:"bước-1-tạo-json-files-cho-translations",children:"Bước 1: Tạo JSON files cho translations"}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.code,{children:"locales/vi.json"}),":"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-json",children:`{
+  "app.title": "Ứng dụng của tôi",
+  "app.description": "Mô tả ứng dụng",
+  "user.greeting": "Xin chào {name}!",
+  "user.welcome": "Chào mừng bạn đến với {app}",
+  "button.submit": "Gửi",
+  "button.reset": "Đặt lại"
+}
+`})}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.code,{children:"locales/en.json"}),":"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-json",children:`{
+  "app.title": "My Application",
+  "app.description": "Application description",
+  "user.greeting": "Hello {name}!",
+  "user.welcome": "Welcome to {app}",
+  "button.submit": "Submit",
+  "button.reset": "Reset"
+}
+`})}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.code,{children:"locales/jp.json"}),":"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-json",children:`{
+  "app.title": "私のアプリケーション",
+  "app.description": "アプリケーションの説明",
+  "user.greeting": "こんにちは {name}！",
+  "user.welcome": "{app}へようこそ",
+  "button.submit": "送信",
+  "button.reset": "リセット"
+}
+`})}),`
+`,n.jsx(e.h3,{id:"bước-2-declare-module-augmentation-trong-globaldts",children:"Bước 2: Declare module augmentation trong global.d.ts"}),`
+`,n.jsxs(e.p,{children:["Tạo hoặc update file ",n.jsx(e.code,{children:"global.d.ts"})," (hoặc ",n.jsx(e.code,{children:"vite-env.d.ts"}),") trong project của bạn:"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import '@v-miniapp/ui-react'
+import vi from './locales/vi.json'
+
+declare module '@v-miniapp/ui-react' {
+  interface ICustomLocales {
+    resource: typeof vi
+    language: 'jp' | 'en' | 'vi'
+  }
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"Lưu ý:"})}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["Import từ JSON files và dùng ",n.jsx(e.code,{children:"typeof vi"})," để infer types tự động, đảm bảo type safety"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"resource"})," là type của locales keys (từ JSON file)"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"language"})," là union type của các language codes mà bạn muốn hỗ trợ"]}),`
+`]}),`
+`,n.jsx(e.h3,{id:"bước-3-sử-dụng-trong-localesconfig",children:"Bước 3: Sử dụng trong localesConfig"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import vi from './locales/vi.json'
+import en from './locales/en.json'
+import jp from './locales/jp.json'
+
+const localesConfig: ILocalesConfig = {
+  defaultLanguage: 'vi',
+  resources: {
+    vi,
+    en,
+    jp,
+  },
+}
+
+export function MiniApp() {
+  return <App config={appConfig} localesConfig={localesConfig} />
+}
+`})}),`
+`,n.jsxs(e.p,{children:["Sau khi declare ",n.jsx(e.code,{children:"ICustomLocales"}),", TypeScript sẽ tự động infer:"]}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:["Locales keys từ ",n.jsx(e.code,{children:"typeof vi"})]}),`
+`,n.jsxs(e.li,{children:["Language codes từ ",n.jsx(e.code,{children:"'jp' | 'en' | 'vi'"})]}),`
+`]}),`
+`,n.jsx(e.p,{children:"Tất cả các functions và hooks sẽ có type safety với các keys và languages đã declare."}),`
+`,n.jsx(e.h2,{id:"sử-dụng-translation-functions",children:"Sử dụng Translation Functions"}),`
+`,n.jsx(e.h3,{id:"standalone-functions",children:"Standalone Functions"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { t, getLanguage, setLanguage } from '@v-miniapp/ui-react'
+
+// Basic usage
+const title = t('app.title')
+
+// With template params
+const greeting = t('user.greeting', { name: 'John' })
+// Translation: "Xin chào {name}!" → "Xin chào John!"
+
+// Get translation in specific language
+const titleVi = t('app.title', undefined, 'vi')
+const titleEn = t('app.title', undefined, 'en')
+
+// Get current language
+const currentLang = getLanguage() // 'vi' | 'en' | 'jp' (inferred từ ICustomLocales)
+
+// Change language
+setLanguage('en') // Type-safe, chỉ chấp nhận languages đã declare
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"⚠️ Lưu ý về Reactivity:"})}),`
+`,n.jsxs(e.p,{children:["Các standalone functions ",n.jsx(e.code,{children:"t"})," ",n.jsx(e.strong,{children:"không có reactivity"}),". Khi ngôn ngữ thay đổi, component sử dụng các functions này sẽ ",n.jsx(e.strong,{children:"không tự động re-render"}),"."]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// ❌ Không reactive - Component không re-render khi language thay đổi
+function MyComponent() {
+  const title = t('app.title')
+  const greeting = t('user.greeting', undefined, 'en')
+  
+  return <div>{title} - {greeting}</div>
+  // Khi setLanguage() được gọi, component này sẽ KHÔNG re-render
+}
+`})}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Giải pháp:"})," Sử dụng ",n.jsx(e.strong,{children:"React Hook"})," ",n.jsx(e.code,{children:"useTranslate"})," trong components để có reactivity."]}),`
+`,n.jsx(e.h3,{id:"react-hooks",children:"React Hooks"}),`
+`,n.jsx(e.p,{children:"Sử dụng hooks trong React components để có reactivity:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`import { useTranslate, useLanguage } from '@v-miniapp/ui-react'
+
+function MyComponent() {
+  // useTranslate hook - tự động infer keys từ ICustomLocales
+  const t = useTranslate()
+
+  // useLanguage hook - tự động infer languages từ ICustomLocales
+  const { language, setLanguage } = useLanguage()
+
+  return (
+    <div>
+      <h1>{t('app.title')}</h1>
+      <p>{t('user.greeting', { name: 'John' })}</p>
+
+      <p>Current language: {language}</p>
+      <button onClick={() => setLanguage('vi')}>Tiếng Việt</button>
+      <button onClick={() => setLanguage('en')}>English</button>
+      <button onClick={() => setLanguage('jp')}>日本語</button>
+    </div>
+  )
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"✅ Reactivity:"})}),`
+`,n.jsxs(e.p,{children:["React hook ",n.jsx(e.code,{children:"useTranslate"})," ",n.jsx(e.strong,{children:"có reactivity"}),". Component sử dụng hook này sẽ ",n.jsx(e.strong,{children:"tự động re-render"})," khi ngôn ngữ thay đổi."]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// ✅ Có reactive - Component tự động re-render khi language thay đổi
+function MyComponent() {
+  const t = useTranslate()
+  
+  return <div>{t('app.title')}</div>
+  // Khi setLanguage() được gọi, component này sẽ TỰ ĐỘNG re-render
+}
+`})}),`
+`,n.jsx(e.h2,{id:"template-parameters",children:"Template Parameters"}),`
+`,n.jsx(e.p,{children:"Locales module hỗ trợ template parameters trong translation strings sử dụng cú pháp `{key}`:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// Locales definition (trong JSON files hoặc resources)
+const resources = {
+  vi: {
+    'user.greeting': 'Xin chào {name}!',
+    'user.welcome': 'Chào mừng bạn đến với {app}',
+    'calendar.headerLabel': '{month} - {year}',
+  },
+  en: {
+    'user.greeting': 'Hello {name}!',
+    'user.welcome': 'Welcome to {app}',
+    'calendar.headerLabel': '{month} - {year}',
+  },
+}
+
+// Usage
+t('user.greeting', { name: 'John' })
+// → "Xin chào John!" (vi) hoặc "Hello John!" (en)
+
+t('user.welcome', { app: 'MyApp' })
+// → "Chào mừng bạn đến với MyApp" (vi) hoặc "Welcome to MyApp" (en)
+
+t('calendar.headerLabel', { month: 'Tháng 1', year: '2024' })
+// → "Tháng 1 - 2024"
+`})}),`
+`,n.jsx(e.h2,{id:"type-inference-và-type-safety",children:"Type Inference và Type Safety"}),`
+`,n.jsxs(e.p,{children:["TypeScript tự động infer custom keys và custom languages từ module augmentation trong ",n.jsx(e.code,{children:"global.d.ts"}),". Sau khi declare ",n.jsx(e.code,{children:"ICustomLocales"}),":"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// global.d.ts
+declare module '@v-miniapp/ui-react' {
+  interface ICustomLocales {
+    resource: typeof vi // Infer keys từ vi.json
+    language: 'jp' | 'en' | 'vi' // Infer languages
+  }
+}
+`})}),`
+`,n.jsx(e.p,{children:"Tất cả các functions và hooks sẽ tự động có type safety:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// ✅ Type-safe: t() sẽ suggest keys từ ICustomLocales.resource
+const title = t('app.title')
+
+// ✅ Type-safe: setLanguage() chỉ chấp nhận 'jp' | 'en' | 'vi'
+setLanguage('jp')
+
+// ❌ Type error: 'ja' không có trong ICustomLocales.language
+setLanguage('ja') // Error!
+
+// ❌ Type error: Key không tồn tại trong ICustomLocales.resource
+const invalid = t('app.invalidKey') // Error!
+`})}),`
+`,n.jsx(e.h2,{id:"best-practices",children:"Best Practices"}),`
+`,n.jsx(e.h3,{id:"1-sử-dụng-hooks-trong-react-components",children:"1. Sử dụng hooks trong React components"}),`
+`,n.jsxs(e.p,{children:[n.jsxs(e.strong,{children:["Luôn sử dụng ",n.jsx(e.code,{children:"useTranslate"})," trong React components"]})," để có reactivity. Chỉ sử dụng standalone functions ",n.jsx(e.code,{children:"t"})," khi:"]}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsx(e.li,{children:"Bạn gọi từ bên ngoài React components (utility functions, services, etc.)"}),`
+`,n.jsx(e.li,{children:"Bạn không cần component re-render khi ngôn ngữ thay đổi"}),`
+`]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// ✅ Good - Trong React component, dùng hooks
+function MyComponent() {
+  const t = useTranslate()
+  return <div>{t('app.title')}</div>
+}
+
+// ✅ Good - Ngoài React component, dùng standalone function
+export function getPageTitle() {
+  return t('app.title')
+}
+
+// ❌ Bad - Trong React component, dùng standalone function (không reactive)
+function MyComponent() {
+  const title = t('app.title')
+  return <div>{title}</div> // Sẽ không re-render khi language thay đổi
+}
+`})}),`
+`,n.jsx(e.h3,{id:"2-đặt-tên-keys-có-cấu-trúc",children:"2. Đặt tên keys có cấu trúc"}),`
+`,n.jsx(e.p,{children:"Sử dụng dot notation để nhóm keys theo module/feature:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// ✅ Good
+'app.title'
+'user.greeting'
+'button.submit'
+'form.validation.required'
+
+// ❌ Bad
+'appTitle'
+'userGreeting'
+'submitButton'
+`})}),`
+`,n.jsx(e.h3,{id:"3-sử-dụng-module-augmentation-cho-type-safety",children:"3. Sử dụng module augmentation cho type safety"}),`
+`,n.jsxs(e.p,{children:["Declare ",n.jsx(e.code,{children:"ICustomLocales"})," trong ",n.jsx(e.code,{children:"global.d.ts"})," để có type safety cho cả keys và languages:"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// ✅ Type-safe với module augmentation
+declare module '@v-miniapp/ui-react' {
+  interface ICustomLocales {
+    resource: typeof vi
+    language: 'jp' | 'en' | 'vi'
+  }
+}
+
+// ❌ Không có type safety nếu không declare
+const title = t('app.title') // key là string, không có autocomplete
+`})}),`
+`,n.jsx(e.h3,{id:"4-override-default-translations",children:"4. Override default translations"}),`
+`,n.jsx(e.p,{children:"Bạn có thể override các translation keys mặc định:"}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`const localesConfig: ILocalesConfig = {
+  resources: {
+    vi: {
+      // Override default pull-to-refresh text
+      'pullToRefresh.canReleaseText': 'Thả tay để làm mới',
+      'pullToRefresh.completeText': 'Hoàn tất',
+
+      // Add custom keys
+      'app.title': 'Ứng dụng của tôi',
+    },
+  },
+}
+`})}),`
+`,n.jsx(e.h3,{id:"5-import-từ-json-files",children:"5. Import từ JSON files"}),`
+`,n.jsxs(e.p,{children:["Import translations từ JSON files và sử dụng ",n.jsx(e.code,{children:"typeof"})," để infer types:"]}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// ✅ Import từ JSON
+import vi from './locales/vi.json'
+
+declare module '@v-miniapp/ui-react' {
+  interface ICustomLocales {
+    resource: typeof vi // Auto-infer types
+    language: 'jp' | 'en' | 'vi'
+  }
+}
+`})}),`
+`,n.jsx(e.h2,{id:"reference",children:"Reference"}),`
+`,n.jsx(e.h3,{id:"types",children:"Types"}),`
+`,n.jsx(e.h4,{id:"ilocalesconfig",children:n.jsx(e.code,{children:"ILocalesConfig"})}),`
+`,n.jsx(e.p,{children:"Cấu hình locales cho App component hoặc LocalesProvider."}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-typescript",children:`type ILocalesConfig = {
+  defaultLanguage?: IAppLanguage
+  resources?: IOptinalResources
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"Properties:"})}),`
+`,n.jsx(t,{children:"\n| Name | Type | Required | Description |\n| :--- | :--- | :--- | :--- |\n| `defaultLanguage` | `IAppLanguage` | No | Ngôn ngữ mặc định. Có thể là `'vi'`, `'en'`, hoặc `'system'` (hoặc custom languages từ `ICustomLocales`) |\n| `resources` | `IOptinalResources` | No | Object chứa các locales translations. Keys là language codes, values là resource maps |\n"}),`
+`,n.jsx(e.h4,{id:"icustomlocales",children:n.jsx(e.code,{children:"ICustomLocales"})}),`
+`,n.jsx(e.p,{children:"Interface để declare custom locales thông qua module augmentation."}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-typescript",children:`interface ICustomLocales {
+  resource: Record<string, string> // Type của locales keys (thường là typeof vi từ JSON)
+  language: string // Union type của language codes (e.g., 'vi' | 'en' | 'jp')
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"Ví dụ:"})}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`// global.d.ts
+declare module '@v-miniapp/ui-react' {
+  interface ICustomLocales {
+    resource: typeof vi // Infer từ vi.json
+    language: 'jp' | 'en' | 'vi' // Custom languages
+  }
+}
+`})}),`
+`,n.jsx(e.h4,{id:"iapplanguage",children:n.jsx(e.code,{children:"IAppLanguage"})}),`
+`,n.jsx(e.p,{children:"Union type của language codes bao gồm default và custom languages."}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-typescript",children:`type IAppLanguage = ILang | 'system'
+`})}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.code,{children:"ILang"})," được infer từ ",n.jsx(e.code,{children:"IDefaultLocales['language']"})," (default: ",n.jsx(e.code,{children:"'vi' | 'en'"}),") và ",n.jsx(e.code,{children:"ICustomLocales['language']"})," (nếu có)."]}),`
+`,n.jsx(e.h3,{id:"components",children:"Components"}),`
+`,n.jsx(e.h4,{id:"localesprovider",children:n.jsx(e.code,{children:"LocalesProvider"})}),`
+`,n.jsx(e.p,{children:"Component để khởi tạo locales module."}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-typescript",children:`type LocalesProviderProps = {
+  config?: ILocalesConfig
+}
+`})}),`
+`,n.jsx(e.p,{children:n.jsx(e.strong,{children:"Usage:"})}),`
+`,n.jsx(e.pre,{children:n.jsx(e.code,{className:"language-tsx",children:`<LocalesProvider config={localesConfig} />
+`})}),`
+`,n.jsxs(e.p,{children:[n.jsx(e.strong,{children:"Lưu ý:"})," Component này chỉ init một lần khi mount, nên cần đặt ở top-level."]}),`
+`,n.jsx(e.h3,{id:"functions--hooks",children:"Functions & Hooks"}),`
+`,n.jsx(e.h4,{id:"tkey-params-lang",children:n.jsx(e.code,{children:"t(key, params?, lang?)"})}),`
+`,n.jsx(e.p,{children:"Standalone function để translate key."}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Parameters:"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"key"}),": ",n.jsx(e.code,{children:"IResourceKey"})," - Locales key (inferred từ ",n.jsx(e.code,{children:"ICustomLocales.resource"})," nếu có)"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"params?"}),": ",n.jsx(e.code,{children:"ITemplateParams"})," - Template parameters object"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"lang?"}),": ",n.jsx(e.code,{children:"ILang"})," - Ngôn ngữ chỉ định"]}),`
+`]}),`
+`]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Returns:"})," ",n.jsx(e.code,{children:"string"})," - Translated text"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Reactivity:"})," ❌ Không có reactivity"]}),`
+`]}),`
+`,n.jsx(e.h4,{id:"usetranslate",children:n.jsx(e.code,{children:"useTranslate()"})}),`
+`,n.jsx(e.p,{children:"React hook để translate trong components."}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Returns:"})," Function tương tự ",n.jsx(e.code,{children:"t(key, params?)"})]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Reactivity:"})," ✅ Có reactivity"]}),`
+`]}),`
+`,n.jsx(e.h4,{id:"getlanguage",children:n.jsx(e.code,{children:"getLanguage()"})}),`
+`,n.jsx(e.p,{children:"Standalone function để lấy current language."}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Returns:"})," ",n.jsx(e.code,{children:"ILang"})," - Current language"]}),`
+`]}),`
+`,n.jsx(e.h4,{id:"setlanguagelanguage",children:n.jsx(e.code,{children:"setLanguage(language)"})}),`
+`,n.jsx(e.p,{children:"Standalone function để thay đổi language."}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Parameters:"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"language"}),": ",n.jsx(e.code,{children:"ILang"})," - Language code (inferred từ ",n.jsx(e.code,{children:"ICustomLocales.language"})," nếu có)"]}),`
+`]}),`
+`]}),`
+`]}),`
+`,n.jsx(e.h4,{id:"uselanguage",children:n.jsx(e.code,{children:"useLanguage()"})}),`
+`,n.jsx(e.p,{children:"React hook để quản lý language."}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.strong,{children:"Returns:"})," ",n.jsx(e.code,{children:"{ language: ILang, setLanguage: (lang: ILang) => void }"}),`
+`,n.jsxs(e.ul,{children:[`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"language"}),": Current language (inferred từ ",n.jsx(e.code,{children:"ICustomLocales.language"})," nếu có)"]}),`
+`,n.jsxs(e.li,{children:[n.jsx(e.code,{children:"setLanguage"}),": Function để thay đổi language (type-safe với ",n.jsx(e.code,{children:"ICustomLocales.language"}),")"]}),`
+`]}),`
+`]}),`
+`]})]})}function g(s={}){const{wrapper:e}={...i(),...s.components};return e?n.jsx(e,{...s,children:n.jsx(c,{...s})}):c(s)}export{g as default};