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

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

@@ -0,0 +1,170 @@
+# BottomSheet
+
+> Slides up from bottom — reveals additional content/actions while maintaining parent screen context. Overlay container.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Variant Axes
+
+| Axis | Options | Default |
+|------|---------|---------|
+| **Type** | `standard` · `surface` | `standard` |
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `type` | string | `"standard"` \| `"surface"` | `"standard"` | Standard: with handle + backdrop. Surface: no handle, integrated feel [VERIFY] |
+| `visible` | boolean | `true` \| `false` | `false` | Controlled visibility |
+| `barrierDismissible` | boolean | `true` \| `false` | `true` | Tap backdrop to dismiss |
+| `showHandle` | boolean | `true` \| `false` | `true` | Show drag handle indicator [VERIFY] |
+| `children` | element | — | required | Sheet content — any components. Scrollable if exceeds height |
+| `onDismiss` | function | — | — | Callback khi dismissed. `"onDismiss": "action://closeSheet"` |
+
+---
+
+## Variants
+
+| Type | Handle | Backdrop | Use Case |
+|------|--------|---------|----------|
+| **standard** | Visible (36x4, `Colors.black_06`) | `Colors.black_20` at 40% opacity | Action lists, selections, additional info |
+| **surface** | Hidden | None or minimal | Integrated content that feels part of screen |
+
+---
+
+## States
+
+| State | Appearance |
+|-------|-----------|
+| **Hidden** | Not rendered |
+| **Opening** | Slide up from bottom (300ms ease-out), backdrop fade in |
+| **Visible** | Sheet visible, content scrollable if needed. Max 90% screen height |
+| **Closing** | Slide down (250ms ease-in), backdrop fade out |
+
+Dismiss triggers: swipe down on handle/content, tap backdrop (if barrierDismissible), system back button, programmatic.
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Action list** | Secondary actions cho list item | Primary actions → show visible | Share, Export, Report options |
+| **Selection** | Choose from <10 options | >10 options → full screen with search | Chọn ngân hàng, chọn lý do |
+| **Filter/Sort** | Filter or sort options | Complex multi-field filter → new screen | Lọc giao dịch, sắp xếp |
+| **Information** | Additional details without leaving context | Critical decisions → dùng PopupNotify | Chi tiết giao dịch, thông tin thêm |
+
+---
+
+## SSR Pattern
+
+### Action List BottomSheet
+```json
+{
+  "component": "BottomSheet",
+  "props": {
+    "visible": "{{state.showActions}}",
+    "barrierDismissible": true
+  },
+  "children": [
+    {
+      "component": "Text",
+      "props": {
+        "content": "Chia sẻ",
+        "typography": "body_default_regular"
+      },
+      "onPress": "action://share"
+    },
+    {
+      "component": "Divider",
+      "props": {}
+    },
+    {
+      "component": "Text",
+      "props": {
+        "content": "Báo cáo",
+        "typography": "body_default_regular"
+      },
+      "onPress": "action://report"
+    }
+  ],
+  "onDismiss": "setState://showActions=false"
+}
+```
+
+### Selection BottomSheet
+```json
+{
+  "component": "BottomSheet",
+  "props": {
+    "visible": "{{state.showBankPicker}}"
+  },
+  "children": [
+    {
+      "component": "Text",
+      "props": {
+        "content": "Chọn ngân hàng",
+        "typography": "headline_s_bold"
+      }
+    },
+    {
+      "id": "bank_options",
+      "type": "section",
+      "forEach": "{{data.banks}}",
+      "render": {
+        "component": "Radio",
+        "props": {
+          "value": "{{item.id}}",
+          "groupValue": "{{state.selectedBank}}",
+          "label": "{{item.name}}"
+        },
+        "onChange": "setState://selectedBank={{item.id}}"
+      }
+    },
+    {
+      "component": "Button",
+      "props": {
+        "variant": "primary",
+        "label": "Xác nhận"
+      },
+      "onPress": "action://confirmBank"
+    }
+  ],
+  "onDismiss": "setState://showBankPicker=false"
+}
+```
+
+---
+
+## Accessibility
+
+- Focus trap khi sheet open — cannot interact with content behind.
+- Handle: accessible label "Kéo xuống để đóng".
+- Content announces on open.
+- Back button / ESC dismisses.
+- All interactive elements meet 44dp touch target.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho secondary actions, filter/sort, selections (<10 items).
+- Show handle cho swipe-to-dismiss affordance.
+- Allow backdrop tap to dismiss cho non-critical sheets.
+- Keep content concise and scannable.
+
+### Don't
+- Không nest bottom sheets trong bottom sheets.
+- Không dùng cho lengthy forms → navigate to new screen.
+- Không disable swipe-to-dismiss unless data loss possible.
+- Không >90% screen height.
+- Không dùng cho critical confirmations → dùng **PopupNotify**.
+- Không dùng cho persistent content — sheet is dismissible.

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

@@ -0,0 +1,206 @@
+# Button
+
+> Interactive element trigger action — CTA chính và phụ cho mọi screen trong MoMo.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — Figma variant naming typo known ("sencondary")
+**Figma node:** [VERIFY]
+
+---
+
+## Variant Axes
+
+| Property | Type | Values | Description |
+|----------|------|--------|-------------|
+| type | variant | primary · secondary · tonal · outline · danger · textlink · disabled | Visual variant — determines colors and emphasis |
+| size | variant | large · medium · small | Button size |
+| full | boolean | true · false | Full-width mode |
+
+> **Note:** Figma treats `disabled` as variant trong `type`. Logically nó là state. ui-composer có thể dùng `type: "disabled"` hoặc `disabled: true` [VERIFY].
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `title` | string | — | required | Button label text. Sentence case. Max 20 chars. Start with verb |
+| `type` | string | `"primary"` \| `"secondary"` \| `"tonal"` \| `"outline"` \| `"danger"` \| `"textlink"` \| `"disabled"` | `"primary"` | Visual variant |
+| `size` | string | `"large"` \| `"medium"` \| `"small"` | `"large"` | Button size |
+| `full` | boolean | `true` \| `false` | `false` | Full-width mode — stretches to parent width |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive. Overrides variant colors |
+| `loading` | boolean | `true` \| `false` | `false` | Spinner replaces label. Non-interactive during loading |
+| `iconLeft` | string | icon name | — | Optional icon before label |
+| `iconRight` | string | icon name | — | Optional icon after label |
+| `onPress` | function | — | — | Tap handler. `"onPress": "action://submit"` |
+
+---
+
+## Variants
+
+| Variant | Background | Text Color | Border | Emphasis | Usage |
+|---------|-----------|-----------|--------|----------|-------|
+| **primary** | `Colors.pink_03` | `Colors.white` | none | Highest | Main CTA. Chỉ 1 per screen |
+| **secondary** | `Colors.white` | `Colors.pink_03` | `Colors.pink_03` | High | Supporting action. Pair với Primary |
+| **tonal** | `Colors.pink_09` | `Colors.pink_03` | none | Medium | Soft emphasis. Grouped actions |
+| **outline** | `Colors.white` | `Colors.black_17` | `Colors.black_04` | Low | Neutral, optional actions |
+| **danger** | `Colors.red_03` | `Colors.white` | none | Override | Destructive/irreversible only |
+| **textlink** | transparent | `Colors.pink_03` | none | Lowest | Inline text action. Skip, Show all |
+
+**Variant hierarchy:** primary > secondary > tonal/outline > textlink. Danger overrides all — dùng độc lập.
+
+---
+
+## States
+
+| State | Background | Text Color | Border | Opacity | Spinner | Interactive |
+|-------|-----------|-----------|--------|---------|---------|-------------|
+| **Default** | per variant | per variant | per variant | 1 | — | true |
+| **Pressed** | per variant | per variant | per variant | 0.8 | — | true |
+| **Disabled** | `Colors.black_04` | `Colors.black_08` | none | 1 | — | false |
+| **Loading** | per variant | — | per variant | 1 | matches text color | false |
+
+- Pressed: entire button opacity 0.8. Immediate transition.
+- Loading: spinner replaces label text. Button maintains exact size. Prevents double-tap.
+- Disabled: overrides ALL variant colors → grey.
+
+---
+
+## Variant-to-Context Map
+
+| Variant | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **primary** | Main action trên screen. Max 1 per view | Có 2+ primary actions — hạ bớt xuống secondary | "Chuyển tiền" button trên form transfer |
+| **secondary** | Supporting action alongside Primary | Standalone không có Primary kèm — dùng Primary | "Hủy" bên cạnh "Xác nhận" trên popup confirm |
+| **tonal** | Grouped actions cần soft emphasis | Action quan trọng cần nổi bật — dùng Primary | "Chọn phương thức" trên màn thanh toán |
+| **outline** | Neutral, optional, low-emphasis | Action chính — quá subtle | "Xem chi tiết" trên card giao dịch |
+| **danger** | Destructive, irreversible action | Non-destructive actions | "Xóa tài khoản" trên Settings, "Hủy giao dịch" |
+| **textlink** | Inline text action, lowest emphasis | Primary action — quá subtle | "Bỏ qua" trên onboarding, "Xem tất cả" trên section |
+
+---
+
+## SSR Pattern
+
+### Fixed Bottom CTA
+```json
+{
+  "id": "bottom_cta",
+  "type": "footer",
+  "children": [
+    {
+      "component": "Button",
+      "props": {
+        "title": "Chuyển tiền",
+        "type": "primary",
+        "size": "large",
+        "full": true,
+        "loading": "{{state.isSubmitting}}"
+      },
+      "onPress": "action://transfer"
+    }
+  ]
+}
+```
+
+### Horizontal Pair (Confirm/Cancel)
+```json
+{
+  "id": "action_pair",
+  "type": "row",
+  "spacing": "Spacing.S",
+  "children": [
+    {
+      "component": "Button",
+      "props": {
+        "title": "Hủy",
+        "type": "secondary",
+        "size": "medium"
+      },
+      "onPress": "action://cancel"
+    },
+    {
+      "component": "Button",
+      "props": {
+        "title": "Xác nhận",
+        "type": "primary",
+        "size": "medium"
+      },
+      "onPress": "action://confirm"
+    }
+  ]
+}
+```
+
+### Destructive Confirmation
+```json
+{
+  "id": "destructive_pair",
+  "type": "row",
+  "spacing": "Spacing.S",
+  "children": [
+    {
+      "component": "Button",
+      "props": {
+        "title": "Giữ lại",
+        "type": "outline",
+        "size": "medium"
+      },
+      "onPress": "action://keep"
+    },
+    {
+      "component": "Button",
+      "props": {
+        "title": "Xóa tài khoản",
+        "type": "danger",
+        "size": "medium"
+      },
+      "onPress": "action://deleteAccount"
+    }
+  ]
+}
+```
+
+### Loading Action
+```json
+{
+  "component": "Button",
+  "props": {
+    "title": "Đang xử lý...",
+    "type": "primary",
+    "size": "large",
+    "full": true,
+    "loading": true
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Screen reader announce: label + role (button) + state (disabled/loading).
+- Icon-only buttons: PHẢI có text accessible label.
+- Loading state: announce "Đang xử lý" hoặc equivalent.
+- Color contrast: tất cả variant text-on-background meet WCAG AA (4.5:1).
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng Primary cho 1 action quan trọng nhất trên screen.
+- Sentence case: "Chuyển tiền" không phải "CHUYỂN TIỀN".
+- Label 1-3 words, bắt đầu bằng verb.
+- Loading state cho async actions — prevent double-tap.
+- Pair Primary + Secondary khi có 2 choices.
+- Danger CHỈ cho destructive/irreversible.
+
+### Don't
+- Không đặt 2+ Primary buttons trên cùng 1 view area.
+- Không mix sizes trong cùng button group.
+- Không dùng Danger cho non-destructive actions.
+- Không dùng TextLink cho primary actions — quá subtle.
+- Không disable button mà không communicate lý do.
+- Không mix Primary + Danger trong cùng group.
+- Label không quá 20 ký tự, không dùng "!" hay ".".

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

@@ -0,0 +1,117 @@
+# Carousel
+
+> Horizontal scrollable content container — snap-to-item behavior for banners, galleries, onboarding. Pairs with Pagination.
+
+**Package:** `@momo-kits/carousel`
+**Platform:** RN ✅ | Compose ❌ (use HorizontalPager)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `items` | array | — | required | Data array for carousel items |
+| `renderItem` | function | — | required | Render function per item [VERIFY] |
+| `autoPlay` | boolean | `true` \| `false` | `false` | Auto-advance between items |
+| `autoPlayInterval` | number | milliseconds | `3000` | Interval between auto-advances [VERIFY] |
+| `loop` | boolean | `true` \| `false` | `false` | Seamless wrap from last → first item [VERIFY] |
+| `showPagination` | boolean | `true` \| `false` | `true` | Show PaginationDot below carousel [VERIFY] |
+| `paginationType` | string | `"dot"` \| `"scroll"` | `"dot"` | Pagination variant (see Pagination component) [VERIFY] |
+| `peek` | number | dp | `0` | Amount of adjacent item visible at edges (16-24dp recommended) [VERIFY] |
+| `onChange` | function | — | — | Callback khi current item changes. `"onChange": "setState://currentBanner"` |
+
+---
+
+## States
+
+| State | Appearance |
+|-------|-----------|
+| **Idle** | Current item fully visible, pagination updated |
+| **Scrolling** | Items move horizontally, pagination animates |
+| **Auto-playing** | Items advance automatically at interval |
+| **Paused** | Auto-play paused due to user touch interaction |
+
+Auto-play pauses on user interaction, resumes after release.
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Promotional banners** | Featured content at screen top | Critical content every user must see | Banner khuyến mãi trên Home |
+| **Image gallery** | Browse product/service images | Long lists → dùng FlatList | Ảnh merchant, ảnh sản phẩm |
+| **Onboarding** | Step-by-step intro slides | Navigation between sections → dùng TabView | Welcome slides, feature intro |
+
+---
+
+## SSR Pattern
+
+### Banner Carousel with Pagination
+```json
+{
+  "id": "banner_section",
+  "type": "section",
+  "children": [
+    {
+      "component": "Carousel",
+      "props": {
+        "items": "{{data.banners}}",
+        "autoPlay": true,
+        "autoPlayInterval": 5000,
+        "loop": true,
+        "showPagination": true,
+        "paginationType": "dot",
+        "peek": 0
+      },
+      "onChange": "setState://currentBanner"
+    }
+  ]
+}
+```
+
+### Image Gallery with Scroll Pagination
+```json
+{
+  "component": "Carousel",
+  "props": {
+    "items": "{{data.merchantImages}}",
+    "autoPlay": false,
+    "showPagination": true,
+    "paginationType": "scroll",
+    "peek": 16
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Items navigable via swipe gestures on assistive technology.
+- Auto-play MUST pause khi screen reader active.
+- Each item: descriptive accessible label.
+- Announce current position: "Mục 2 trong 5".
+- Provide way to pause auto-play without specific gesture.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho promotional banners, image galleries, onboarding slides.
+- Always include pagination indicators.
+- Peek adjacent items → signal scrollability.
+- Keep 3-8 items — manageable count.
+- Auto-play interval ≥3 seconds.
+
+### Don't
+- Không dùng cho long lists → dùng FlatList / LazyColumn.
+- Không dùng cho section navigation → dùng **TabView** / **BottomTab**.
+- Không set autoPlayInterval <3000ms — user cần time to read.
+- Không hide pagination khi >1 item.
+- Không nest carousels — scroll conflict.
+- Không rely on carousel cho critical content — items may be missed.

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

@@ -0,0 +1,98 @@
+# CheckBox
+
+> Multi-selection control — chọn nhiều options hoặc indicate agreement. Supports indeterminate state.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `checked` | boolean | `true` \| `false` | `false` | Checked state |
+| `indeterminate` | boolean | `true` \| `false` | `false` | Partial selection state (select-all parent) [VERIFY] |
+| `label` | string | — | — | Text label bên phải checkbox |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive state |
+| `onChange` | function | — | — | Callback khi toggle. `"onChange": "setState://option"` |
+
+---
+
+## States
+
+| State | Box Appearance | Icon | Label Color | Interactive |
+|-------|---------------|------|------------|-------------|
+| **Unchecked** | `Colors.black_04` border, no fill | none | `Colors.black_17` | true |
+| **Checked** | `Colors.pink_03` fill | white checkmark | `Colors.black_17` | true |
+| **Indeterminate** | `Colors.pink_03` fill | white minus | `Colors.black_17` | true |
+| **Disabled Unchecked** | `Colors.black_08` border, no fill | none | `Colors.black_08` | false |
+| **Disabled Checked** | `Colors.black_08` fill | white checkmark | `Colors.black_08` | false |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Multi-select** | Chọn nhiều options từ list | Chọn 1 exclusive → dùng Radio | Chọn nhiều dịch vụ, filter multi-category |
+| **Agreement** | Consent/terms checkbox | — | "Tôi đồng ý điều khoản" trên form |
+| **Select all** | Parent checkbox cho group (indeterminate khi partial) | — | "Chọn tất cả" trên danh sách |
+
+---
+
+## SSR Pattern
+
+### Agreement Checkbox
+```json
+{
+  "component": "CheckBox",
+  "props": {
+    "checked": "{{state.agreedToTerms}}",
+    "label": "Tôi đồng ý với Điều khoản sử dụng"
+  },
+  "onChange": "setState://agreedToTerms"
+}
+```
+
+### Multi-select List
+```json
+{
+  "id": "service_options",
+  "type": "section",
+  "forEach": "{{data.services}}",
+  "render": {
+    "component": "CheckBox",
+    "props": {
+      "checked": "{{item.selected}}",
+      "label": "{{item.name}}"
+    },
+    "onChange": "setState://toggleService={{item.id}}"
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Screen readers announce: label, state (checked/unchecked/indeterminate), role (checkbox).
+- Entire row (box + label) tappable.
+- State changes announce immediately.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho selecting multiple options từ list.
+- Dùng cho agreement/consent checkboxes.
+- Dùng indeterminate cho "select all" parent.
+- Luôn provide visible label.
+
+### Don't
+- Không dùng cho single on/off toggle → dùng **Switch**.
+- Không dùng cho mutually exclusive choices → dùng **Radio**.
+- Không dùng cho filter controls trong toolbar → dùng **Chip**.