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

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

@@ -0,0 +1,141 @@
+# Slider
+
+> Range selection control — drag thumb along track to select value or range within min-max bounds.
+
+**Package:** `@momo-kits/slider`
+**Platform:** RN ✅ | Compose ❌ (use native Slider)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Variant Axes
+
+| Axis | Options | Default |
+|------|---------|---------|
+| **Mode** | `single` · `range` | `single` |
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `mode` | string | `"single"` \| `"range"` | `"single"` | Single thumb or dual-thumb range selection |
+| `value` | number \| array | number (single) or `[min, max]` (range) | `0` | Current value. Single: number. Range: `[lowValue, highValue]` |
+| `min` | number | — | `0` | Minimum bound |
+| `max` | number | — | `100` | Maximum bound |
+| `step` | number | — | `1` | Value increment. `0` for continuous [VERIFY] |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive state |
+| `showLabel` | boolean | `true` \| `false` | `false` | Show value label above thumb [VERIFY] |
+| `onChange` | function | — | — | Callback khi value changes. `"onChange": "setState://sliderValue"` |
+
+---
+
+## Variants
+
+| Mode | Thumbs | Track Fill | Usage |
+|------|--------|-----------|-------|
+| **single** | 1 thumb | Fill from min to thumb | Select single value (volume, brightness) |
+| **range** | 2 thumbs | Fill between two thumbs | Select value range (price filter, age range) |
+
+### Track Colors
+
+| Part | Color |
+|------|-------|
+| Active fill | `Colors.pink_03` |
+| Inactive track | `Colors.black_04` |
+| Thumb | `Colors.white` with shadow [VERIFY] |
+
+---
+
+## States
+
+| State | Appearance | Interactive |
+|-------|-----------|-------------|
+| **Default** | Pink fill + grey track, white thumb | true |
+| **Dragging** | Thumb enlarged, optional value label shown | true |
+| **Disabled** | All elements reduced opacity (0.4) | false |
+
+---
+
+## Variant-to-Context Map
+
+| Mode | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|------|-------------|-----------|-------------------|
+| **single** | Adjust single value in continuous range | Discrete options (3-5 choices) → dùng Radio | Volume, brightness, loan amount |
+| **range** | Filter by range (min-max) | Single value selection | Lọc giá sản phẩm, khoảng tuổi |
+
+---
+
+## SSR Pattern
+
+### Price Range Filter
+```json
+{
+  "id": "price_filter",
+  "type": "section",
+  "children": [
+    {
+      "component": "Text",
+      "props": {
+        "content": "Khoảng giá",
+        "typography": "body_default_bold"
+      }
+    },
+    {
+      "component": "Slider",
+      "props": {
+        "mode": "range",
+        "value": [0, 1000000],
+        "min": 0,
+        "max": 5000000,
+        "step": 100000,
+        "showLabel": true
+      },
+      "onChange": "setState://priceRange"
+    }
+  ]
+}
+```
+
+### Single Value Slider
+```json
+{
+  "component": "Slider",
+  "props": {
+    "mode": "single",
+    "value": "{{state.amount}}",
+    "min": 100000,
+    "max": 50000000,
+    "step": 100000
+  },
+  "onChange": "setState://amount"
+}
+```
+
+---
+
+## Accessibility
+
+- Announce current value: "Slider: 500,000".
+- Range mode: announce both values: "Range: 100,000 to 1,000,000".
+- Thumb adjustable via accessibility actions (increment/decrement by step).
+- Disabled state announced.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho continuous value selection in a range.
+- Range mode cho price/quantity filters.
+- Show min/max labels at track ends.
+- `showLabel` khi exact value matters to user.
+- Reasonable step size — không quá fine-grained.
+
+### Don't
+- Không dùng cho small discrete options (1-5) → dùng **Stepper** hoặc **Radio**.
+- Không dùng cho exact numeric input → dùng **Input** with numeric keyboard.
+- Không set step=0 unless truly continuous control needed.
+- Không hide value display khi precision matters — show label or pair with Text.

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

@@ -0,0 +1,97 @@
+# SnackBar
+
+> Transient notification with optional action — bottom-of-screen feedback. Compose equivalent of Toast.
+
+**Package:** built-in Compose (`SnackbarHost`)
+**Platform:** RN ❌ (use Toast) | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `message` | string | — | required | Snackbar text content |
+| `duration` | number | milliseconds | `3000` | Auto-dismiss duration [VERIFY] |
+| `actionLabel` | string | — | — | Optional action button text (e.g., "Hoàn tác"). Omit for no action [VERIFY] |
+| `onAction` | function | — | — | Callback khi tap action button. `"onAction": "action://undoDelete"` |
+| `type` | string | `"default"` \| `"error"` | `"default"` | Snackbar style variant [VERIFY] |
+
+---
+
+## Variants
+
+| Type | Background | Text Color | Action Color |
+|------|-----------|-----------|-------------|
+| **default** | `Colors.black_17` (dark) | `Colors.white` | `Colors.pink_03` [VERIFY] |
+| **error** | `Colors.red_03` | `Colors.white` | `Colors.white` [VERIFY] |
+
+---
+
+## States
+
+| State | Appearance |
+|-------|-----------|
+| **Entering** | Slide up from bottom with animation |
+| **Visible** | Full opacity at bottom, countdown active |
+| **Exiting** | Slide down with fade animation |
+| **Dismissed** | Removed from view |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Action feedback** | Confirm action + offer undo | No undo possible | "Đã xóa. Hoàn tác?" |
+| **Brief notification** | Non-critical info (no action needed) | Critical errors → dùng Information | "Đã lưu thay đổi" |
+| **Error feedback** | Brief error on Compose | Error needs detail → dùng Information | "Lỗi kết nối" |
+
+---
+
+## SSR Pattern
+
+### SnackBar with Undo Action
+```json
+{
+  "id": "delete_feedback",
+  "type": "action",
+  "trigger": "onSuccess",
+  "snackbar": {
+    "component": "SnackBar",
+    "props": {
+      "message": "Đã xóa mục đã chọn",
+      "actionLabel": "Hoàn tác",
+      "duration": 5000
+    },
+    "onAction": "action://undoDelete"
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Announce snackbar content as live region.
+- Action button must meet 44dp touch target.
+- Duration sufficient for screen reader announcement + action interaction (~5s when action present).
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho Compose platform transient notifications.
+- Include action button khi undo/retry is possible.
+- Position at bottom of screen (standard Material placement).
+- Extend duration khi có action button (5000ms vs 3000ms).
+
+### Don't
+- Không dùng trên RN → dùng **Toast**.
+- Không dùng cho persistent messages → dùng **Information**.
+- Không dùng cho blocking alerts → dùng **PopupNotify**.
+- Không include more than 1 action.
+- Không stack multiple snackbars.

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

@@ -0,0 +1,100 @@
+# Stepper
+
+> Numeric increment/decrement control — minus/plus buttons để adjust value theo discrete steps.
+
+**Package:** `@momo-kits/stepper`
+**Platform:** RN ✅ | Compose ❌ (build with Row + Button)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `value` | number | — | `1` | Current numeric value |
+| `min` | number | — | `0` | Minimum value. Minus button disabled khi reached |
+| `max` | number | — | — | Maximum value. Plus button disabled khi reached |
+| `step` | number | — | `1` | Increment/decrement amount per tap [VERIFY] |
+| `disabled` | boolean | `true` \| `false` | `false` | Both buttons disabled |
+| `onChange` | function | — | — | Callback khi value change. `"onChange": "setState://quantity"` |
+
+---
+
+## States
+
+| State | Minus Button | Plus Button | Value Color | Interactive |
+|-------|-------------|-----------|------------|-------------|
+| **Default** | `Colors.black_17` icon | `Colors.black_17` icon | `Colors.black_17` | true |
+| **At minimum** | `Colors.black_08` (disabled) | `Colors.black_17` | `Colors.black_17` | partial |
+| **At maximum** | `Colors.black_17` | `Colors.black_08` (disabled) | `Colors.black_17` | partial |
+| **Pressed** | opacity 0.8 | opacity 0.8 | `Colors.black_17` | true |
+| **Disabled** | `Colors.black_08` | `Colors.black_08` | `Colors.black_08` | false |
+
+Value updates immediately on tap.
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Quantity picker** | Adjust số lượng items (1-10) | Range lớn (0-1000) → dùng Slider | Số lượng vé, số suất ăn |
+| **Count adjustment** | Small numeric adjustments | Freeform numeric input → dùng Input | Số người trong nhóm, số tháng |
+
+---
+
+## SSR Pattern
+
+### Quantity Picker
+```json
+{
+  "id": "quantity_row",
+  "type": "row",
+  "children": [
+    {
+      "component": "Text",
+      "props": {
+        "content": "Số lượng",
+        "typography": "body_default_regular"
+      }
+    },
+    {
+      "component": "Stepper",
+      "props": {
+        "value": "{{state.quantity}}",
+        "min": 1,
+        "max": 10,
+        "step": 1
+      },
+      "onChange": "setState://quantity"
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Minus button: accessible label "Giảm".
+- Plus button: accessible label "Tăng".
+- Current value announce as live region — changes spoken aloud.
+- Disabled buttons at boundaries announce disabled.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho small numeric adjustments (1-10 range).
+- Show current value rõ ràng between buttons.
+- Disable button khi value reach min/max.
+- Reasonable default value — user không cần tap nhiều.
+
+### Don't
+- Không dùng cho large ranges → dùng **Slider**.
+- Không dùng cho freeform numeric → dùng **Input** numeric keyboard.
+- Không hide value display.
+- Không dùng cho non-numeric → dùng **Chip** / **Radio**.

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

@@ -0,0 +1,91 @@
+# Steps
+
+> Step progress indicator — numbered circles + connecting lines for multi-step flows. Shows current position.
+
+**Package:** `@momo-kits/step`
+**Platform:** RN ✅ | Compose ❌ (build with Row)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `steps` | array | `[{ label }]` | required | List of step definitions |
+| `current` | number | 0-based index | `0` | Current active step index |
+| `showLabels` | boolean | `true` \| `false` | `true` | Show text labels below circles [VERIFY] |
+
+### Step Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `label` | string | yes | Step description text (e.g., "Chi tiết", "Thanh toán", "Xác nhận") |
+
+---
+
+## States (per step)
+
+| State | Circle Background | Circle Content | Label Color | Connecting Line |
+|-------|------------------|---------------|------------|----------------|
+| **Completed** | `Colors.pink_03` | White check icon (✓) | `Colors.black_17` | `Colors.pink_03` (to next completed/current) |
+| **Current** | `Colors.pink_03` | White step number | `Colors.black_17` | `Colors.black_04` (to next upcoming) |
+| **Upcoming** | `Colors.black_04` | `Colors.black_17` step number | `Colors.black_08` | `Colors.black_04` |
+
+Steps evenly distributed across full width. Labels centered below circles.
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Checkout flow** | Multi-step purchase/payment | Single page form | Thanh toán: Chi tiết → Xác nhận → Hoàn thành |
+| **Registration** | Step-by-step onboarding | Simple 1-page signup | eKYC: Thông tin → CMND → Selfie → Hoàn thành |
+| **Wizard** | Complex form broken into sections | ≤2 steps → just use buttons | Đăng ký dịch vụ mới |
+
+---
+
+## SSR Pattern
+
+### Checkout Steps
+```json
+{
+  "component": "Steps",
+  "props": {
+    "steps": [
+      { "label": "Chi tiết" },
+      { "label": "Thanh toán" },
+      { "label": "Xác nhận" }
+    ],
+    "current": "{{state.currentStep}}"
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Each step announces: label + number + state ("Bước 1, Chi tiết, hoàn thành").
+- Current step clearly identified: "Bước 2, Thanh toán, bước hiện tại".
+- Overall progress context: "Bước 2 trong 4".
+- Not rely solely on color — check icon (completed) + number (current/upcoming) provide distinction.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho linear multi-step flows (checkout, registration, onboarding).
+- Keep labels short — 1-2 words.
+- Limit 3-5 steps for readability.
+- Show completed check icon → user confidence.
+
+### Don't
+- Không dùng cho tab navigation → dùng **TabView**.
+- Không dùng cho percentage progress → dùng **ProgressInfo**.
+- Không allow tap upcoming steps to skip ahead (unless flow supports non-linear).
+- Không >5 steps — break flow into sections or simplify.
+- Không dùng cho page indicators → dùng **Pagination**.

package/.claude/skills/design-system/references/components/suggest-action.md

@@ -0,0 +1,95 @@
+# SuggestAction
+
+> Tappable suggestion row — title + optional description + chevron. Quick-action entry point.
+
+**Package:** `@momo-kits/suggest-action`
+**Platform:** RN ✅ | Compose ❌
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `title` | string | — | required | Primary text — action label |
+| `description` | string | — | — | Secondary text below title. Optional [VERIFY] |
+| `icon` | string | icon name | — | Leading icon [VERIFY] |
+| `showChevron` | boolean | `true` \| `false` | `true` | Show trailing chevron (→) indicator [VERIFY] |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive state |
+| `onPress` | function | — | — | Callback khi tap. `"onPress": "navigate://Screen"` hoặc `"onPress": "action://doSomething"` |
+
+---
+
+## States
+
+| State | Appearance | Interactive |
+|-------|-----------|-------------|
+| **Default** | Full opacity, chevron visible | true |
+| **Pressed** | Opacity 0.8 (entire row) | true |
+| **Disabled** | Reduced opacity (0.4), no press feedback | false |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Quick action** | Suggest next action after completing flow | Primary CTA needed → dùng Button | "Xem lịch sử giao dịch" sau khi chuyển tiền |
+| **Navigation shortcut** | Link to related screen/feature | Standalone navigation → dùng list item | "Mời bạn bè" suggestion |
+| **Contextual suggestion** | AI/system-suggested action based on context | Static menu items | "Thanh toán điện nước" khi đến hạn |
+
+---
+
+## SSR Pattern
+
+### Post-Transaction Suggestions
+```json
+{
+  "id": "suggest_actions",
+  "type": "section",
+  "children": [
+    {
+      "component": "SuggestAction",
+      "props": {
+        "title": "Xem lịch sử giao dịch",
+        "icon": "history"
+      },
+      "onPress": "navigate://TransactionHistory"
+    },
+    {
+      "component": "SuggestAction",
+      "props": {
+        "title": "Chuyển tiền cho người khác",
+        "description": "Gửi tiền nhanh đến số điện thoại"
+      },
+      "onPress": "navigate://Transfer"
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Announce as button: "[title], [description]".
+- Chevron is decorative — not announced separately.
+- Full row is single tap target.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho contextual next-step suggestions.
+- Keep title actionable — verb-first ("Xem...", "Mời...", "Thanh toán...").
+- Description chỉ khi cần clarify action.
+- Group 2-3 suggestions together maximum.
+
+### Don't
+- Không dùng cho primary actions → dùng **Button**.
+- Không dùng cho navigation menus → dùng list với proper list items.
+- Không show >3 suggestions — overwhelming.
+- Không omit onPress — mỗi SuggestAction phải navigate/action.

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

@@ -0,0 +1,121 @@
+# Swipe
+
+> Swipeable list item — horizontal swipe reveals hidden action buttons (delete, edit, archive).
+
+**Package:** `@momo-kits/swipe`
+**Platform:** RN ✅ | Compose ❌ (use SwipeToDismissBox)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `actions` | array | `[{ label, icon, color, onPress }]` | required | Right-side action buttons revealed on swipe |
+| `leftActions` | array | `[{ label, icon, color, onPress }]` | — | Optional left-side actions (swipe right to reveal) [VERIFY] |
+| `disabled` | boolean | `true` \| `false` | `false` | Disable swipe gesture |
+| `children` | element | — | required | Content layer — the visible list item |
+
+### Action Object
+
+| Field | Type | Values | Required | Description |
+|-------|------|--------|----------|-------------|
+| `label` | string | — | yes | Action button text |
+| `icon` | string | icon name | no | Action button icon [VERIFY] |
+| `color` | string | color token | yes | Action button background color |
+| `onPress` | function | — | yes | Callback. `"onPress": "action://deleteItem={{item.id}}"` |
+
+### Common Action Colors
+
+| Action | Background |
+|--------|-----------|
+| Delete | `Colors.red_03` |
+| Archive | `Colors.blue_03` |
+| Edit | `Colors.orange_03` |
+| Pin | `Colors.pink_03` |
+
+---
+
+## States
+
+| State | Appearance | Interactive |
+|-------|-----------|-------------|
+| **Resting** | Content fully visible, actions hidden | true (swipeable) |
+| **Swiping** | Content moves left, actions partially revealed | true |
+| **Actions open** | Content offset, action buttons fully visible | true |
+| **Action pressed** | Pressed action button opacity 0.8 | true |
+| **Disabled** | No swipe gesture response | false |
+
+Auto-close: opening another Swipe item closes previously open items.
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **List item actions** | Secondary actions on list items (delete, archive) | Primary actions → show visibly | Xóa tin nhắn, archive notification |
+| **Quick edit** | Fast inline editing actions | Complex editing → navigate to edit screen | Sửa tên nhóm, pin conversation |
+
+---
+
+## SSR Pattern
+
+### Swipeable Notification List
+```json
+{
+  "id": "notification_list",
+  "type": "section",
+  "forEach": "{{data.notifications}}",
+  "render": {
+    "component": "Swipe",
+    "props": {
+      "actions": [
+        {
+          "label": "Xóa",
+          "color": "Colors.red_03",
+          "onPress": "action://deleteNotification={{item.id}}"
+        }
+      ]
+    },
+    "children": [
+      {
+        "component": "Text",
+        "props": {
+          "content": "{{item.message}}",
+          "typography": "body_default_regular"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Swipe actions PHẢI có alternative access (long-press menu hoặc accessible actions list).
+- Each action button: clear accessible label ("Xóa mục", "Lưu trữ").
+- Screen reader users cannot swipe — provide fallback interaction.
+- Khi actions revealed → focusable by assistive technology.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho secondary actions on list items — delete, archive, edit.
+- Limit 2-3 action buttons per item.
+- Distinct colors per action for quick identification.
+- Destructive action (Delete) rightmost.
+- Confirmation dialog cho destructive actions.
+
+### Don't
+- Không dùng cho primary actions → make them visible by default.
+- Không dùng cho navigation → dùng tap.
+- Không >3 action buttons — cramped and hard to target.
+- Không rely solely on swipe — always provide accessible fallback.
+- Không dùng on items with horizontal scrolling — gesture conflict.