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

package/.claude/skills/design-system/references/components/input-search.md

@@ -0,0 +1,124 @@
+# InputSearch
+
+> Search bar với search icon prefix và cancel action — dùng cho mọi search flow trong MoMo.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `value` | string | — | `""` | Current search query |
+| `placeholder` | string | — | `"Tìm kiếm"` | Hint text. Không dùng floating label [VERIFY] |
+| `hintText` | string | — | — | Helper text bên dưới (hiếm dùng cho search) |
+| `errorMessage` | string | — | — | Error text (hiếm dùng cho search) |
+| `size` | string | `"large"` \| `"medium"` | `"medium"` | Search bar size |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive |
+| `showClearButton` | boolean | `true` \| `false` | `true` | Clear button khi có value [VERIFY] |
+| `onChange` | function | — | — | Callback mỗi keystroke. `"onChange": "setState://searchQuery"` |
+| `onFocus` | function | — | — | Callback khi focus — thường trigger search UI |
+| `onBlur` | function | — | — | Callback khi blur |
+| `onClear` | function | — | — | Callback khi clear [VERIFY] |
+| `onCancel` | function | — | — | Callback khi tap Cancel button. Clear value + dismiss focus [VERIFY] |
+
+> **Khác biệt:** InputSearch có search icon prefix built-in và Cancel button appears on focus. Có thể KHÔNG dùng `floatingValue` mà dùng `placeholder` trực tiếp [VERIFY].
+
+---
+
+## States
+
+| State | Border | Text Color | Icon Color | Cancel Btn | Clear Btn | Interactive |
+|-------|--------|-----------|-----------|------------|-----------|-------------|
+| **Default** | `Colors.black_04` | `Colors.black_17` | `Colors.black_12` | hidden | hidden | true |
+| **Focused** | `Colors.blue_03` | `Colors.black_17` | `Colors.black_12` | visible | hidden | true |
+| **Typing** | `Colors.blue_03` | `Colors.black_17` | `Colors.black_12` | visible | visible | true |
+| **Filled** | `Colors.black_04` | `Colors.black_17` | `Colors.black_12` | hidden | visible | true |
+| **Disabled** | `Colors.black_03` | `Colors.black_08` | `Colors.black_08` | hidden | hidden | false |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **List search** | Tìm kiếm trong danh sách dài | Chỉ filter đơn giản 3-5 options — dùng Chip group | Search giao dịch lịch sử, search contacts |
+| **Service search** | Tìm dịch vụ/merchant | Danh mục cố định — dùng tabs/chips | Search dịch vụ trên Home, search merchant |
+| **Global search** | Search bar chính của app | — | Search bar trên Home screen MoMo |
+
+---
+
+## SSR Pattern
+
+### Search with Results List
+```json
+{
+  "id": "search_section",
+  "type": "section",
+  "children": [
+    {
+      "component": "InputSearch",
+      "props": {
+        "placeholder": "Tìm kiếm giao dịch",
+        "size": "medium"
+      },
+      "onChange": "setState://searchQuery"
+    },
+    {
+      "id": "search_results",
+      "type": "section",
+      "forEach": "{{data.searchResults}}",
+      "render": {
+        "component": "ListItem",
+        "props": {
+          "title": "{{item.title}}",
+          "subtitle": "{{item.date}}",
+          "rightText": "{{item.amount}}"
+        },
+        "onPress": "navigate://TransactionDetail?id={{item.id}}"
+      }
+    }
+  ]
+}
+```
+
+### Global Search Bar
+```json
+{
+  "component": "InputSearch",
+  "props": {
+    "placeholder": "Tìm dịch vụ, bạn bè...",
+    "size": "large"
+  },
+  "onFocus": "navigate://SearchScreen",
+  "onChange": "setState://globalSearch"
+}
+```
+
+---
+
+## Accessibility
+
+- Search icon phải accessible — role "search".
+- Placeholder announce: "Tìm kiếm giao dịch, search field".
+- Cancel button: announce "Cancel search".
+- Results count announce khi results change: "5 results found".
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng full width cho search bar.
+- Show Cancel button khi focused — cho phép user dismiss nhanh.
+- Implement live search (debounced) hoặc search on submit.
+- Clear results khi query cleared.
+
+### Don't
+- Không dùng cho simple filter — dùng **Chip** group.
+- Không hide search icon — user cần visual cue đây là search.
+- Không disable Cancel khi focused — luôn cho phép dismiss.

package/.claude/skills/design-system/references/components/input-text-area.md

@@ -0,0 +1,133 @@
+# InputTextArea
+
+> Multiline text input — container grows vertically theo content cho đến max height.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `value` | string | — | `""` | Current input value (multiline) |
+| `floatingValue` | string | — | required | Floating label text |
+| `placeholder` | string | — | — | Hint text khi chưa có value |
+| `hintText` | string | — | — | Helper text bên dưới container |
+| `errorMessage` | string | — | — | Error text. Replaces hintText |
+| `size` | string | `"large"` \| `"medium"` | `"medium"` | Initial input size |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive state |
+| `editable` | boolean | `true` \| `false` | `true` | `false` = read-only [VERIFY] |
+| `required` | boolean | `true` \| `false` | `false` | Required indicator |
+| `maxLines` | number | — | — | Max dòng trước khi scroll [VERIFY] |
+| `maxHeight` | number | — | — | Max chiều cao container [VERIFY] |
+| `showClearButton` | boolean | `true` \| `false` | `true` | Clear button [VERIFY] |
+| `onChange` | function | — | — | Callback khi value thay đổi |
+| `onFocus` | function | — | — | Callback khi focus |
+| `onBlur` | function | — | — | Callback khi blur |
+| `onClear` | function | — | — | Callback khi clear [VERIFY] |
+
+> **Khác biệt so với Input:** Container height KHÔNG cố định — grows vertically theo content. Keyboard default (multiline enter).
+
+---
+
+## States
+
+| State | Border | Text Color | Label Color | Error Color | Cursor | Clear Btn | Interactive |
+|-------|--------|-----------|------------|-------------|--------|-----------|-------------|
+| **Default** | `Colors.black_04` | `Colors.black_17` | `Colors.black_17` | — | hidden | hidden | true |
+| **Focused** | `Colors.blue_03` | `Colors.black_17` | `Colors.black_17` | — | visible | hidden | true |
+| **Typing** | `Colors.blue_03` | `Colors.black_17` | `Colors.black_17` | — | visible | visible | true |
+| **Filled** | `Colors.black_04` | `Colors.black_17` | `Colors.black_17` | — | hidden | visible | true |
+| **Error** | `Colors.red_03` | `Colors.black_17` | `Colors.black_17` | `Colors.red_03` | hidden | visible | true |
+| **Disabled** | `Colors.black_03` | `Colors.black_08` | `Colors.black_08` | — | hidden | hidden | false |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Long note** | Nhập text dài nhiều dòng | Text ngắn 1 dòng — dùng Input standard | Ghi chú chuyển tiền dài, lý do hoàn tiền |
+| **Description** | Mô tả chi tiết | Chỉ cần 1 field ngắn | Mô tả yêu cầu hỗ trợ, feedback |
+| **Message** | Tin nhắn dạng freeform | Structured input — dùng form fields riêng | Nhắn tin cho merchant, comment |
+
+---
+
+## SSR Pattern
+
+### Feedback Form
+```json
+{
+  "id": "feedback_section",
+  "type": "section",
+  "children": [
+    {
+      "component": "Rating",
+      "props": {
+        "value": "{{state.rating}}"
+      },
+      "onChange": "setState://rating"
+    },
+    {
+      "component": "InputTextArea",
+      "props": {
+        "floatingValue": "Nhận xét của bạn",
+        "placeholder": "Chia sẻ trải nghiệm...",
+        "size": "medium",
+        "maxLines": 5
+      },
+      "onChange": "setState://feedback"
+    },
+    {
+      "component": "Button",
+      "props": {
+        "title": "Gửi đánh giá",
+        "type": "primary",
+        "size": "large",
+        "full": true
+      },
+      "onPress": "action://submitFeedback"
+    }
+  ]
+}
+```
+
+### Transfer Note
+```json
+{
+  "component": "InputTextArea",
+  "props": {
+    "floatingValue": "Lời nhắn",
+    "placeholder": "Nhập ghi chú cho người nhận",
+    "size": "medium",
+    "maxLines": 3
+  },
+  "onChange": "setState://transferNote"
+}
+```
+
+---
+
+## Accessibility
+
+- Floating label required cho screen readers.
+- Announce multiline capability — "text area, 3 of 5 lines".
+- Error message linked.
+- Touch target: full container tappable.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Set `maxLines` hoặc `maxHeight` để tránh content chiếm toàn bộ screen.
+- Dùng `placeholder` để guide content ("Chia sẻ trải nghiệm...").
+- Show character count nếu có limit [VERIFY — cần check prop].
+
+### Don't
+- Không dùng cho text ngắn 1 dòng — dùng **Input** standard.
+- Không set maxLines quá nhỏ (1-2) — vô nghĩa, dùng Input standard.

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

@@ -0,0 +1,152 @@
+# Input
+
+> Single-line text input với floating label — form control cơ bản cho mọi dạng nhập text trong MoMo.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `value` | string | — | `""` | Current input value |
+| `floatingValue` | string | — | required | Floating label text. Animates từ placeholder position lên trên khi focus/filled |
+| `placeholder` | string | — | — | Hint text khi chưa có value |
+| `hintText` | string | — | — | Helper text hiển thị bên dưới container |
+| `errorMessage` | string | — | — | Error text bên dưới container. Khi có, replaces hintText |
+| `size` | string | `"large"` \| `"medium"` | `"medium"` | Input size. Maps to `InputSize.Large` / `InputSize.Medium` |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive state |
+| `editable` | boolean | `true` \| `false` | `true` | `false` = read-only state [VERIFY] |
+| `required` | boolean | `true` \| `false` | `false` | Hiển thị required indicator bên cạnh label |
+| `prefix` | node | icon \| text | — | Element ở đầu input |
+| `trailingIcon` | node | icon | — | Icon ở cuối input |
+| `showClearButton` | boolean | `true` \| `false` | `true` | Clear button xuất hiện ở typing/filled/error states [VERIFY] |
+| `showInformationIcon` | boolean | `true` \| `false` | `false` | Optional info icon [VERIFY] |
+| `image` | node | — | — | Optional image inside input [VERIFY] |
+| `onChange` | function | — | — | Callback khi value thay đổi. `"onChange": "setState://fieldName"` |
+| `onFocus` | function | — | — | Callback khi input nhận focus |
+| `onBlur` | function | — | — | Callback khi input mất focus |
+| `onClear` | function | — | — | Callback khi tap clear button [VERIFY] |
+
+---
+
+## States
+
+| State | Border | Text Color | Label Color | Error Color | Cursor | Clear Btn | Interactive |
+|-------|--------|-----------|------------|-------------|--------|-----------|-------------|
+| **Default** | `Colors.black_04` | `Colors.black_17` | `Colors.black_17` | — | hidden | hidden | true |
+| **Focused** | `Colors.blue_03` | `Colors.black_17` | `Colors.black_17` | — | visible | hidden | true |
+| **Typing** | `Colors.blue_03` | `Colors.black_17` | `Colors.black_17` | — | visible | visible | true |
+| **Filled** | `Colors.black_04` | `Colors.black_17` | `Colors.black_17` | — | hidden | visible | true |
+| **Error** | `Colors.red_03` | `Colors.black_17` | `Colors.black_17` | `Colors.red_03` | hidden | visible | true |
+| **Disabled** | `Colors.black_03` | `Colors.black_08` | `Colors.black_08` | — | hidden | hidden | false |
+| **Read-only** | `Colors.black_04` | `Colors.black_17` | `Colors.black_17` | — | hidden | hidden | false |
+
+**Floating label behavior:**
+- Default (no value): label inside at placeholder position
+- Focus hoặc có value: label animates upward, reduces in size
+
+**Support text priority:** Error > Read-only ("Không thể chỉnh sửa") > Hint
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Text entry** | Nhập text ngắn 1 dòng trong form | Cần nhập số tiền → `InputMoney`, SĐT → `InputPhoneNumber` | Họ tên form KYC, địa chỉ giao hàng |
+| **With prefix** | Field có icon/label prefix | Icon không mang ý nghĩa → bỏ prefix | Email field với @ icon |
+| **Read-only display** | Show value không cho edit | Cần interactive display → dùng Text component | Thông tin tài khoản đã xác thực |
+
+---
+
+## SSR Pattern
+
+### Standard Form
+```json
+{
+  "id": "form_section",
+  "type": "section",
+  "children": [
+    {
+      "component": "Input",
+      "props": {
+        "floatingValue": "Họ và tên",
+        "placeholder": "Nhập họ và tên",
+        "size": "medium",
+        "required": true
+      },
+      "onChange": "setState://fullName"
+    },
+    {
+      "component": "Input",
+      "props": {
+        "floatingValue": "Email",
+        "placeholder": "example@email.com",
+        "size": "medium"
+      },
+      "onChange": "setState://email"
+    },
+    {
+      "component": "Button",
+      "props": {
+        "title": "Tiếp tục",
+        "type": "primary",
+        "size": "large",
+        "full": true,
+        "disabled": "{{state.fullName == ''}}"
+      },
+      "onPress": "action://submitForm"
+    }
+  ]
+}
+```
+
+### Input with Validation Error
+```json
+{
+  "component": "Input",
+  "props": {
+    "floatingValue": "Email",
+    "placeholder": "example@email.com",
+    "size": "medium",
+    "required": true,
+    "errorMessage": "{{state.emailError}}",
+    "value": "{{state.email}}"
+  },
+  "onChange": "setState://email"
+}
+```
+
+---
+
+## Accessibility
+
+- Every input phải có floating label cho screen readers. Không dùng placeholder thay label.
+- Error message phải programmatically associated với input.
+- Tap label hoặc container area = focus input.
+- Read-only: screen reader phải announce non-editable status.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Luôn cung cấp floating label — không dùng placeholder thay label.
+- Error message inline bên dưới input, không dùng alert/toast.
+- Dùng hint text để clarify format ("DD/MM/YYYY").
+- Clear error state ngay khi user sửa input.
+- Read-only PHẢI có support text.
+
+### Don't
+- Không dùng disabled input để hiển thị read-only info — dùng **Text**.
+- Không stack nhiều error messages cho 1 input.
+- Không ẩn floating label khi input có value.
+- Hint text không quá 2 dòng.
+- Cần nhập tiền → dùng **InputMoney**, không dùng Input standard.
+- Cần nhập SĐT → dùng **InputPhoneNumber**.
+- Cần nhập OTP → dùng **InputOTP**.

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

@@ -0,0 +1,87 @@
+# Loader
+
+> Loading spinner/dot animation — full-screen loading states và initial data fetches.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ❌ (dùng `CircularProgressIndicator` hoặc Skeleton)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `type` | string | `"spinner"` \| `"dot"` | `"spinner"` | Loader variant [VERIFY] |
+| `color` | string | `Colors.*` token | `"Colors.pink_03"` | Loader color [VERIFY] |
+
+---
+
+## Variants
+
+| Variant | Animation | Usage |
+|---------|----------|-------|
+| **spinner** | Continuous circular rotation | General-purpose loading |
+| **dot** | Sequential pulsing/scaling dots | Lighter, playful contexts |
+
+---
+
+## States
+
+| State | Color | Animation | Description |
+|-------|-------|----------|-------------|
+| **Loading** | `Colors.pink_03` | Active | Continuous animation |
+
+---
+
+## Variant-to-Context Map
+
+| Variant | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **spinner** | Full-screen loading, screen transitions | Inline content loading → dùng Skeleton | App initialization, screen data fetch |
+| **dot** | Lighter loading contexts | Formal/serious screens | Chat typing indicator, playful loading |
+
+---
+
+## SSR Pattern
+
+### Full-screen Loading
+```json
+{
+  "id": "loading_screen",
+  "type": "center",
+  "children": [
+    {
+      "component": "Loader",
+      "props": {
+        "type": "spinner"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Loader announce "Đang tải" cho screen readers.
+- Khi loading complete → loaded content nhận focus.
+- Loader không focusable hoặc interactive.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho full-screen loading states.
+- Dùng cho initial data fetches khi no layout structure known.
+- Center loader trong available space.
+- Spinner cho general-purpose, dot cho lighter contexts.
+
+### Don't
+- Không dùng cho inline content loading → dùng **Skeleton**.
+- Không dùng trong button → dùng **Button** loading prop.
+- Không show Loader cho near-instant operations.
+- Không dùng trên Compose → dùng native `CircularProgressIndicator`.

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

@@ -0,0 +1,105 @@
+# Pagination
+
+> Page/position indicators — dots, numbers, hoặc scroll bar cho carousels và paged content.
+
+**Package:** `@momo-kits/carousel` (PaginationDot, PaginationScroll) / `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `type` | string | `"dot"` \| `"whiteDot"` \| `"number"` \| `"scroll"` | `"dot"` | Pagination variant [VERIFY] |
+| `total` | number | — | required | Total number of pages |
+| `current` | number | 0-based index | `0` | Current active page |
+| `onChange` | function | — | — | Callback khi page change (for number variant) [VERIFY] |
+
+---
+
+## Variants
+
+| Variant | Active Color | Inactive Color | Content | Usage |
+|---------|-------------|---------------|---------|-------|
+| **dot** | `Colors.pink_03` | `Colors.black_08` | Circles | Standard carousels, image galleries |
+| **whiteDot** | `Colors.white` | `Colors.white` (50% opacity) | Circles | Dark/image backgrounds |
+| **number** | `Colors.pink_03` | `Colors.black_12` | Page numbers | When exact page count matters |
+| **scroll** | `Colors.pink_03` (indicator) | `Colors.black_08` (track) | Scroll bar | Large page counts |
+
+---
+
+## States
+
+| State | Appearance |
+|-------|-----------|
+| **Active page** | Highlighted indicator (pink/white, larger dot) |
+| **Inactive pages** | Subdued indicator (grey/translucent, smaller) |
+| **Transitioning** | Animated interpolation between two page states |
+
+---
+
+## Variant-to-Context Map
+
+| Variant | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **dot** | Standard carousel, ≤7 pages | >7 pages → dùng scroll | Banner carousel trên Home |
+| **whiteDot** | Pagination trên dark/image background | Light background → dùng dot | Image gallery, hero banners |
+| **number** | Exact page count matters to user | Decorative paging | Onboarding steps |
+| **scroll** | Many pages, continuous scroll | ≤5 discrete pages → dùng dot | Feed với lazy loading |
+
+---
+
+## SSR Pattern
+
+### Carousel with Dot Pagination
+```json
+{
+  "id": "banner_carousel",
+  "type": "section",
+  "children": [
+    {
+      "component": "Carousel",
+      "props": {
+        "items": "{{data.banners}}",
+        "autoPlay": true
+      }
+    },
+    {
+      "component": "Pagination",
+      "props": {
+        "type": "dot",
+        "total": "{{data.banners.length}}",
+        "current": "{{state.currentBanner}}"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Announce current page position: "Trang 2 trong 5".
+- Dot indicators là decorative khi paired with swipe navigation.
+- Number pagination nếu tappable → meet 44dp touch target.
+
+---
+
+## Usage Guidelines
+
+### Do
+- PaginationDot cho carousels / image galleries.
+- PaginationWhiteDot cho dark backgrounds.
+- PaginationNumber khi exact page count matters.
+- PaginationScroll cho many pages.
+- Center-align below associated content.
+
+### Don't
+- Không dùng cho step-by-step progress → dùng **Steps**.
+- Không dùng dot cho >7-8 pages → switch to scroll/number.
+- Không đặt pagination xa content.
+- Không mix variants trong cùng carousel.