@momo-kits/native-kits 0.157.5-debug → 0.158.1-beta.1-debug

package/.claude/skills/design-system/references/components/tooltip.md

@@ -0,0 +1,138 @@
+# Tooltip
+
+> Contextual help popup attached to a trigger element, used for feature discovery, field help, and first-time guidance.
+
+**Package:** `@momo-kits/animated-tooltip`
+**Platform support:** RN ✅ (AnimatedTooltip) | Compose ✅
+
+---
+
+## Anatomy
+
+```
+              ┌──────────────────────────┐
+              │  Title (optional)        │
+              │  Description text here   │
+              │           [Action Button]│
+              └────────────┬─────────────┘
+                           ▼
+                    (arrow pointer)
+                   ┌──────────┐
+                   │ Trigger  │
+                   └──────────┘
+```
+
+| Part          | Description                                          | Required |
+|---------------|------------------------------------------------------|----------|
+| Container     | Rounded rectangle holding tooltip content            | Yes      |
+| Title         | Bold heading line within the tooltip                 | No       |
+| Description   | Explanatory text                                     | Yes      |
+| Action button | Optional text button for a follow-up action          | No       |
+| Arrow         | Triangular pointer connecting tooltip to trigger     | Yes      |
+
+---
+
+## Placement
+
+The tooltip can be positioned relative to the trigger element:
+
+| Placement  | Arrow direction         |
+|------------|-------------------------|
+| **TOP**    | Arrow points down       |
+| **BOTTOM** | Arrow points up         |
+| **LEFT**   | Arrow points right      |
+| **RIGHT**  | Arrow points left       |
+
+### Alignment
+
+Within each placement, the tooltip can be aligned along the trigger:
+
+| Alignment  | Description                                  |
+|------------|----------------------------------------------|
+| **START**  | Tooltip aligns to the start edge of trigger  |
+| **CENTER** | Tooltip is centered on the trigger           |
+| **END**    | Tooltip aligns to the end edge of trigger    |
+
+---
+
+## Visual Specs
+
+### Dark Theme (Default)
+
+| Property         | Token / Value              |
+|------------------|----------------------------|
+| Background       | `Colors.black_17`          |
+| Title color      | `Colors.white`             |
+| Description color| `Colors.white`             |
+| Title typography | `body_default_semibold`    |
+| Desc. typography | `body_s_regular`           |
+| Corner radius    | `Radius.S`                 |
+| Padding          | `Spacing.M` (12) all sides |
+| Max width        | 240 dp                     |
+
+### Light Theme
+
+| Property         | Token / Value                          |
+|------------------|----------------------------------------|
+| Background       | `Colors.surface` (theme surface color) |
+| Title color      | Default text color                     |
+| Description color| Default text color                     |
+| All other specs  | Same as dark theme                     |
+
+### Arrow
+
+| Property  | Value                                          |
+|-----------|------------------------------------------------|
+| Size      | 8 dp triangle                                  |
+| Color     | Matches container background                   |
+| Position  | Points toward the trigger element center       |
+
+---
+
+## Animation
+
+| Property   | Value                |
+|------------|----------------------|
+| Enter      | Fade in              |
+| Exit       | Fade out             |
+
+---
+
+## Interaction
+
+| Trigger action      | Behavior                          |
+|----------------------|-----------------------------------|
+| Tap trigger          | Show, hide, or toggle tooltip     |
+| Tap outside tooltip  | Dismiss tooltip                   |
+| Tap action button    | Execute action and dismiss        |
+
+The tooltip visibility is managed via state: **show**, **hide**, or **toggle**.
+
+---
+
+## Accessibility
+
+- Tooltip content must be announced to screen readers when displayed.
+- Tooltip must be dismissible by tapping outside — do not trap focus.
+- If the tooltip contains an action button, that button must be reachable by assistive technology.
+- On screen readers, the trigger element should indicate that additional information is available.
+
+---
+
+## Usage Guidelines
+
+### Do's
+
+- Use for feature discovery and onboarding highlights.
+- Use to provide brief explanations for form fields or icons.
+- Use for first-time user guidance to draw attention to new features.
+- Keep description text short and scannable (1-2 sentences).
+- Position the tooltip so it does not overflow the screen bounds.
+
+### Don'ts
+
+- Don't use for error messages — use the Input component's error state instead.
+- Don't use for lengthy or complex content — use a Modal or BottomSheet instead.
+- Don't display multiple tooltips simultaneously.
+- Don't rely on tooltip content for critical information that the user must see — tooltips are supplementary.
+- Don't use tooltips for menus or interactive lists — use a Popover or BottomSheet instead.

package/.claude/skills/design-system/references/components/top-nav-miniapp.md

@@ -0,0 +1,94 @@
+# TopNavMiniApp
+
+> Header cho mini-app — pill combo với "more" + "quit" buttons bắt buộc. Khác hoàn toàn TopNav native.
+
+**Package:** `@momo-kits/foundation` [VERIFY]
+**Platform:** RN ✅ | Compose ❌ [VERIFY]
+**Completeness:** need_update — thiếu Figma (không tìm thấy trong library), thiếu Dev Zip reference riêng
+**Figma node:** không tìm thấy trong `ZP6qAaBcmkB8j2XmR2uXCv` — có thể ở file khác [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `title` | string | — | required | Mini-app name |
+| `showMoreButton` | boolean | `true` \| `false` | `true` | "More" button trong pill. BẮT BUỘC [VERIFY] |
+| `showQuitButton` | boolean | `true` \| `false` | `true` | "Quit" (X) button trong pill. BẮT BUỘC [VERIFY] |
+| `rightPillActions` | array | — | `["more", "quit"]` | Pill combo actions [VERIFY] |
+| `onMorePress` | function | — | — | Callback khi tap More |
+| `onQuitPress` | function | — | — | Callback khi tap Quit (X). `"onQuitPress": "action://closeMiniApp"` |
+| `onBackPress` | function | — | — | Callback khi tap Back (nếu có) |
+
+> **CRITICAL:** Mini-app TopNav PHẢI có pill combo (more + quit). Đây là platform requirement — không thể remove.
+
+---
+
+## States
+
+| State | Title Color | Pill Style | Behavior |
+|-------|------------|-----------|----------|
+| **Default** | `Colors.black_17` | Outlined pill | Static |
+| **Scrolled** | `Colors.black_17` | Outlined pill | Shadow/border appear |
+
+> Mini-app TopNav đơn giản hơn native TopNav — ít background variations.
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Third-party mini-app** | App bên thứ 3 chạy trong MoMo container | Native MoMo feature → dùng **TopNav** | Game, dịch vụ partner (Grab, Tiki trong MoMo) |
+| **Internal mini-app** | Feature MoMo build dưới dạng mini-app | Full native screen → dùng **TopNav** | Campaign pages, event pages |
+
+> **Phân biệt:** Nếu là native MoMo feature → dùng **TopNav** (compact). Nếu là mini-app → dùng **TopNavMiniApp**. Chọn sai = toàn bộ navigation pattern sai.
+
+---
+
+## SSR Pattern
+
+### Mini-app Screen
+```json
+{
+  "navigation": {
+    "headerType": "miniapp",
+    "headerTitle": { "type": "text", "title": "{{data.miniAppName}}" },
+    "rightPill": ["more", "quit"]
+  },
+  "layout": [
+    {
+      "id": "miniapp_content",
+      "type": "section",
+      "children": []
+    }
+  ],
+  "actions": {
+    "quit": { "type": "action", "handler": "closeMiniApp" },
+    "more": { "type": "action", "handler": "openMiniAppMenu" }
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Quit button: accessible label "Đóng mini-app" hoặc "Thoát".
+- More button: accessible label "Tùy chọn" hoặc "Menu".
+- Title: announce mini-app name.
+
+---
+
+## Usage Guidelines
+
+### Do
+- LUÔN có pill combo (more + quit) — platform requirement.
+- Title hiển thị tên mini-app rõ ràng.
+- Quit button close mini-app hoàn toàn, return về MoMo.
+
+### Don't
+- KHÔNG remove quit button — user phải luôn có exit path.
+- KHÔNG dùng cho native MoMo features — dùng **TopNav**.
+- KHÔNG custom pill layout — giữ nguyên more + quit order.

package/.claude/skills/design-system/references/components/top-nav.md

@@ -0,0 +1,226 @@
+# Top Navigation
+
+> Screen header cho native features — cung cấp navigation context, title, và actions. Mọi screen PHẢI có TopNav.
+
+**Package:** `@momo-kits/foundation` [VERIFY]
+**Platform:** RN ✅ | Compose ✅ [VERIFY]
+**Completeness:** need_update — đã có Figma data, thiếu GitBook PDF riêng cho TopNav
+**Figma node:** `13028:10861` — Component Set, 29 variants
+
+---
+
+## Variant Axes
+
+| Property | Type | Values | Description |
+|----------|------|--------|-------------|
+| `Header type` | variant | `title` · `user name` · `location` · `journey` · `full page search` · `onboarding` · `forWL` | Loại nội dung hiển thị trong header |
+| `Background` | variant | `compact` · `expand` · `dark banner` · `light banner` · `none` | Kiểu nền của header |
+| `hasSearch` | variant (boolean) | `true` · `false` | Có hiển thị search bar trong header không |
+| `isScrolled` | variant (boolean) | `true` · `false` | Trạng thái đã scroll — tự động chuyển Background → none |
+| `hasExtension` | boolean | `true` · `false` | Hiển thị extended area bên dưới header |
+| `extendedNavigation` | instance swap | — | Component đặt vào extended area (TabView, SegmentControl, etc.) |
+
+> `isScrolled` do hệ thống tự quản lý, không cần set trong Design Spec. `none` background CHỈ cho scrolled state.
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `headerType` | string | `"title"` \| `"user name"` \| `"location"` \| `"journey"` \| `"full page search"` \| `"onboarding"` \| `"forWL"` | `"title"` | Loại header. Xem Variants section cho chi tiết |
+| `headerTitle` | object | `{ type, title }` \| `{ type, avatar, name, description }` \| `{ type, location, description }` | required | Title configuration — structure phụ thuộc headerType (xem bảng dưới) |
+| `backgroundType` | string | `"compact"` \| `"expand"` \| `"dark banner"` \| `"light banner"` \| `"none"` | `"compact"` | Kiểu nền header |
+| `hasSearch` | boolean | `true` \| `false` | `false` | Hiển thị search bar trong header |
+| `showBackButton` | boolean | `true` \| `false` | `true` | Hiển thị nút back (chevron left) |
+| `rightActions` | array | icon names | `[]` | Right-side action icons. Max 2-3. VD: `["search", "more"]` |
+| `hasNotice` | boolean | `true` \| `false` | `false` | Notice indicator dot trên action icon |
+| `bannerImage` | string | URL | — | Banner image URL. Dùng với `dark banner` / `light banner` |
+| `hasExtension` | boolean | `true` \| `false` | `false` | Extended area bên dưới header |
+| `extendedNavigation` | object | component config | — | Component trong extended area. VD: TabView, SegmentControl |
+| `enableKeyboardAvoidingView` | boolean | `true` \| `false` | `false` | Screen có input → auto-avoid keyboard [VERIFY] |
+
+### headerTitle Object — theo headerType
+
+| headerType | headerTitle structure | Ví dụ |
+|-----------|---------------------|-------|
+| `title` | `{ "type": "text", "title": "Screen Name" }` | `{ "type": "text", "title": "Chuyển tiền" }` |
+| `user name` | `{ "type": "user", "avatar": "url", "name": "Name", "description": "Status" }` | `{ "type": "user", "avatar": "{{data.avatar}}", "name": "{{data.name}}", "description": "Online" }` |
+| `location` | `{ "type": "location", "location": "Address", "description": "Detail" }` | `{ "type": "location", "location": "Q.7, HCM", "description": "Gần bạn" }` |
+| `journey` | `{ "type": "journey", "title": "Step Name" }` [VERIFY] | `{ "type": "journey", "title": "Xác thực danh tính" }` |
+| `full page search` | `{ "type": "search" }` [VERIFY] | `{ "type": "search" }` |
+| `onboarding` | `{ "type": "onboarding", "title": "Step" }` [VERIFY] | `{ "type": "onboarding", "title": "Chào mừng" }` |
+| `forWL` | `{ "type": "whitelabel", "title": "App Name" }` [VERIFY] | RESTRICTED — không dùng khi chưa có confirm |
+
+---
+
+## Variants
+
+### Header Types
+
+| Header Type | Mô tả | Props riêng |
+|------------|-------|-------------|
+| **title** | Standard screen title. DEFAULT choice | `title` (text) |
+| **user name** | User/contact header với avatar | `name`, `description`, `avatar`, `showDescription`, `showStatusUser` [VERIFY] |
+| **location** | Location context header | `location`, `description`, `showDescription` |
+| **journey** | Multi-step flow với progress context | [VERIFY — cần xác nhận props riêng] |
+| **full page search** | Dedicated search screen — search bar chiếm toàn bộ header | [VERIFY — cần xác nhận props riêng] |
+| **onboarding** | Onboarding flow — skip-able, minimal navigation | [VERIFY — cần xác nhận props riêng] |
+| **forWL** | White label. ⚠️ RESTRICTED — chưa có confirm từ system | [VERIFY] |
+
+### Background Types
+
+| Background | Visual | Khi nào dùng | Tránh khi |
+|-----------|--------|-------------|-----------|
+| **compact** | Pink nhạt. Text/icons đen | DEFAULT cho native features | Screen có hero image |
+| **expand** | Pink nhạt. Mở rộng area | Cần search + extended area trong header | Simple detail screen |
+| **dark banner** | Transparent trên dark image. Text/icons trắng | Hero image/banner tối phía sau header | Image quá sáng — không đủ contrast |
+| **light banner** | Transparent trên light image. Text/icons đen | Hero image/banner sáng phía sau header | Image quá tối — không đủ contrast |
+| **none** | White/transparent. Text/icons đen | CHỈ scrolled state — KHÔNG dùng làm default | Làm background mặc định |
+
+**Rules:** `compact` là default. `dark banner` vs `light banner` phụ thuộc tone ảnh bên dưới. `none` tự switch khi scroll — không bao giờ là trạng thái ban đầu.
+
+---
+
+## States
+
+| State | Background | Text/Icon Color | Search Bar | Extension | Behavior |
+|-------|-----------|----------------|-----------|-----------|----------|
+| **Default (compact)** | Pink nhạt | Đen | optional | optional | Static |
+| **Scrolled** | Chuyển sang `none` (white) | Đen | ẩn nếu có | giữ nguyên | Auto-transition khi user scroll |
+| **Dark banner** | Transparent trên dark image | Trắng | optional | optional | Floating trên image |
+| **Light banner** | Transparent trên light image | Đen | optional | optional | Floating trên image |
+
+---
+
+## Variant-to-Context Map
+
+| Header Type | Background | hasSearch | Khi nào dùng | Ví dụ trong MoMo |
+|-------------|-----------|----------|-------------|-------------------|
+| `title` | `compact` | `false` | Standard screen. DEFAULT choice | Chuyển tiền, Lịch sử GD, Cài đặt |
+| `title` | `compact` | `true` | Screen cần search trong header | Danh bạ, Tìm dịch vụ |
+| `title` | `expand` | `true` | Screen cần search + extended area | Home screen với search bar |
+| `title` | `expand` | `false` | Header mở rộng không có search | Screen cần subtitle/filter trong header |
+| `title` | `dark banner` | `false` | Screen có hero image tối | Campaign detail, Merchant page (ảnh tối) |
+| `title` | `light banner` | `false` | Screen có hero image sáng | Profile với banner sáng |
+| `user name` | `compact` | `false` | Chat/contact screen | Chat với người nhận chuyển tiền |
+| `user name` | `expand` | `false` | Profile view mở rộng | Xem profile user |
+| `user name` | `dark banner` | `false` | Profile với banner tối | Profile page với cover photo |
+| `location` | `compact` | `false` | Screen có location context | ATM/PGD gần đây |
+| `location` | `expand` | `false` | Location + extended info | Map view với filter |
+| `journey` | `compact` | `false` | Multi-step flow | KYC flow, Mở tài khoản |
+| `full page search` | `compact` | `false` | Dedicated search screen | Trang tìm kiếm chính |
+| `onboarding` | `compact` | `false` | Onboarding flow | First-time intro |
+
+> **Không phải tất cả 7×5 combinations đều tồn tại.** Chỉ 29 variants có trong Figma. ui-composer chỉ dùng những combinations listed ở trên.
+
+---
+
+## SSR Pattern
+
+### Standard Screen (title + compact)
+```json
+{
+  "navigation": {
+    "headerType": "title",
+    "headerTitle": { "type": "text", "title": "Chuyển tiền" },
+    "backgroundType": "compact",
+    "hasSearch": false,
+    "showBackButton": true,
+    "rightActions": ["search"],
+    "enableKeyboardAvoidingView": true
+  }
+}
+```
+
+### User Header (chat screen)
+```json
+{
+  "navigation": {
+    "headerType": "user name",
+    "headerTitle": {
+      "type": "user",
+      "avatar": "{{data.userAvatar}}",
+      "name": "{{data.userName}}",
+      "description": "{{data.userStatus}}"
+    },
+    "backgroundType": "compact",
+    "showBackButton": true,
+    "rightActions": ["more"]
+  }
+}
+```
+
+### Banner Screen (merchant/campaign)
+```json
+{
+  "navigation": {
+    "headerType": "title",
+    "headerTitle": { "type": "text", "title": "{{data.merchantName}}" },
+    "backgroundType": "dark banner",
+    "bannerImage": "{{data.bannerUrl}}",
+    "showBackButton": true
+  }
+}
+```
+
+### Search Screen
+```json
+{
+  "navigation": {
+    "headerType": "title",
+    "headerTitle": { "type": "text", "title": "Tìm kiếm" },
+    "backgroundType": "compact",
+    "hasSearch": true,
+    "showBackButton": true
+  }
+}
+```
+
+### Screen with Extended Navigation (tabs)
+```json
+{
+  "navigation": {
+    "headerType": "title",
+    "headerTitle": { "type": "text", "title": "Khám phá" },
+    "backgroundType": "expand",
+    "hasSearch": true,
+    "hasExtension": true,
+    "extendedNavigation": {
+      "component": "TabView",
+      "props": {
+        "tabs": ["Tất cả", "Ưu đãi", "Dịch vụ"]
+      }
+    },
+    "showBackButton": false
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Back button: accessible label "Quay lại".
+- Title: announce screen name cho screen readers.
+- Toolkit icons: PHẢI có accessible labels ("Tìm kiếm", "Menu").
+- Banner mode: đảm bảo đủ contrast text trên image (dark banner → text trắng, light banner → text đen).
+- Search: announce "Tìm kiếm, text field" khi focus.
+
+---
+
+## Usage Guidelines
+
+### Do
+- MỌI screen phải có TopNav — không exception trừ full-screen media.
+- Default: `title` + `compact`. Khi không chắc → dùng cái này.
+- Phân biệt rõ `dark banner` vs `light banner` dựa trên tone ảnh.
+- Max 2-3 right action icons trong `rightActions`.
+- Dùng `hasExtension` khi cần tab/segment ngay dưới header.
+
+### Don't
+- KHÔNG dùng `none` làm background mặc định — chỉ cho scrolled state.
+- KHÔNG dùng `forWL` khi chưa có confirm từ system.
+- KHÔNG dùng cho mini-app — dùng **TopNavMiniApp** (file riêng).
+- KHÔNG custom header type ngoài 7 types đã định nghĩa.
+- KHÔNG đặt quá 3 icons trong `rightActions`.

package/.claude/skills/design-system/references/components/uploader.md

@@ -0,0 +1,115 @@
+# Uploader
+
+> File/image upload interface — trigger area + thumbnails + progress. Single or multi-file upload.
+
+**Package:** `@momo-kits/uploader`
+**Platform:** RN ✅ | Compose ❌ (use platform file picker)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `files` | array | `[{ uri, name, status }]` | `[]` | Current uploaded files list |
+| `maxFiles` | number | — | `5` | Maximum files allowed. Trigger hidden khi reached |
+| `acceptTypes` | string | MIME pattern | `"image/*"` | Allowed file types (e.g., `"image/*"`, `"application/pdf"`) [VERIFY] |
+| `maxFileSize` | number | bytes | — | Maximum size per file [VERIFY] |
+| `thumbnailSize` | number | dp | `80` | Preview thumbnail dimensions (square) [VERIFY] |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive state |
+| `onAdd` | function | — | — | Callback khi file selected. `"onAdd": "action://uploadFile"` |
+| `onRemove` | function | — | — | Callback khi remove file. `"onRemove": "action://removeFile={{item.id}}"` |
+
+### File Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `uri` | string | File URI for thumbnail preview |
+| `name` | string | File name |
+| `status` | string | `"uploading"` \| `"complete"` \| `"error"` |
+| `progress` | number | Upload progress 0-100 (when status=uploading) [VERIFY] |
+
+---
+
+## States
+
+| State | Appearance | Interactive |
+|-------|-----------|-------------|
+| **Empty** | Only trigger area visible (dashed border + add icon) | true |
+| **Uploading** | Thumbnail with semi-transparent overlay + progress indicator | partial |
+| **Complete** | Thumbnail with image preview + remove (X) button | true |
+| **Error** | Thumbnail border `Colors.red_03`, error icon overlay | true (retry) |
+| **Max reached** | Trigger area hidden, only thumbnails visible | remove only |
+| **Disabled** | Trigger border + icon `Colors.black_08`, non-interactive | false |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Photo upload** | Attach photos to forms/reviews | Camera capture → dùng Camera | Upload CMND/CCCD, ảnh review merchant |
+| **Document upload** | Attach PDF/docs | Structured data entry → dùng Input | Upload hợp đồng, biên lai |
+| **Profile photo** | Single image selection | Multi-photo → set maxFiles=1 | Thay đổi ảnh đại diện |
+
+---
+
+## SSR Pattern
+
+### ID Photo Upload
+```json
+{
+  "id": "id_upload",
+  "type": "section",
+  "children": [
+    {
+      "component": "Text",
+      "props": {
+        "content": "Tải ảnh CMND/CCCD",
+        "typography": "body_default_bold"
+      }
+    },
+    {
+      "component": "Uploader",
+      "props": {
+        "files": "{{state.idPhotos}}",
+        "maxFiles": 2,
+        "acceptTypes": "image/*"
+      },
+      "onAdd": "action://uploadIdPhoto",
+      "onRemove": "action://removeIdPhoto"
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Trigger: accessible label "Thêm ảnh" hoặc "Tải tệp lên".
+- Each thumbnail: announce file name + status + remove action.
+- Remove button: "Xóa ảnh 1".
+- Upload progress announced as live region: "Đang tải, 50%".
+- Error state communicated: "Tải lên thất bại cho ảnh 2".
+- All interactive elements meet 44dp touch target.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho document/photo uploads trong forms.
+- Show clear progress during upload.
+- Allow easy removal with X button.
+- Set appropriate file type + size restrictions — communicate limits to user.
+- Thumbnail preview cho uploaded images.
+
+### Don't
+- Không dùng cho camera capture → dùng dedicated Camera component.
+- Không allow unlimited uploads — always set reasonable maxFiles.
+- Không silently reject oversized/wrong-type files → show error message.
+- Không hide trigger until maxFiles reached.
+- Không dùng tiny thumbnails — user cần verify uploaded content.