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

package/.claude/skills/design-system/references/components/popup-notify.md

@@ -0,0 +1,128 @@
+# PopupNotify
+
+> Modal dialog — confirmation, alert, decision point. Requires user interaction before proceeding.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅ (via `navigator.showModal`)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `title` | string | — | required | Primary message or question |
+| `description` | string | — | — | Supporting detail text |
+| `image` | object | `{ uri: string }` | — | Optional illustration/image above title [VERIFY] |
+| `primaryButton` | object | `{ label, onPress }` | required | Main action button (filled style) |
+| `secondaryButton` | object | `{ label, onPress }` | — | Alternative/cancel button (outlined/text style) |
+| `showClose` | boolean | `true` \| `false` | `false` | Show close (X) icon at top-right [VERIFY] |
+| `barrierDismissible` | boolean | `true` \| `false` | `false` | Tap overlay to dismiss. Default false — prevents accidental dismissal [VERIFY] |
+| `onDismiss` | function | — | — | Callback khi dismissed. `"onDismiss": "action://closePopup"` |
+
+### Button Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `label` | string | yes | Button text — use strong verbs ("Xóa", "Xác nhận"), not generic "Yes"/"No" |
+| `onPress` | function | yes | Callback. `"onPress": "action://confirm"` |
+
+---
+
+## Variants
+
+| Layout | Khi nào | Description |
+|--------|---------|-------------|
+| **Row (side-by-side)** | Both labels short, fit in single row | Secondary left, Primary right |
+| **Column (stacked)** | Labels long, would truncate in row | Primary top, Secondary below |
+
+Layout auto-detected based on combined button text length. Column is safer default.
+
+---
+
+## States
+
+| State | Appearance |
+|-------|-----------|
+| **Appearing** | Fade in overlay + scale up container from center |
+| **Visible** | Static — user must interact to proceed |
+| **Dismissing** | Fade out overlay + container |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Destructive confirmation** | Confirm delete/cancel actions | Non-destructive feedback → dùng Toast | "Xóa giao dịch này?" |
+| **Important alert** | Alert requiring acknowledgment | Non-critical info → dùng Information | "Phiên đăng nhập hết hạn" |
+| **Binary decision** | Two-choice decision point | >2 choices → dùng BottomSheet | "Lưu thay đổi?" Lưu / Hủy |
+
+---
+
+## SSR Pattern
+
+### Destructive Confirmation
+```json
+{
+  "component": "PopupNotify",
+  "props": {
+    "title": "Xóa giao dịch?",
+    "description": "Hành động này không thể hoàn tác",
+    "primaryButton": {
+      "label": "Xóa",
+      "onPress": "action://deleteTransaction"
+    },
+    "secondaryButton": {
+      "label": "Hủy",
+      "onPress": "action://closePopup"
+    }
+  }
+}
+```
+
+### Alert with Image
+```json
+{
+  "component": "PopupNotify",
+  "props": {
+    "title": "Cập nhật thành công!",
+    "description": "Thông tin của bạn đã được cập nhật",
+    "image": { "uri": "{{assets.successIllustration}}" },
+    "primaryButton": {
+      "label": "Đóng",
+      "onPress": "action://closePopup"
+    }
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Focus trap: keyboard/screen reader focus trapped within dialog khi open.
+- Title announced by screen reader on open.
+- ESC / hardware back dismisses dialog.
+- Button labels must be clear, descriptive.
+- Role: `alertdialog`.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho destructive action confirmations ("Xóa mục này?").
+- Dùng cho important alerts requiring acknowledgment.
+- Dùng cho binary decision points ("Lưu / Hủy").
+- Strong verb labels on buttons — "Xóa", "Xác nhận", not "Yes"/"No".
+- Keep title clear, description concise.
+
+### Don't
+- Không dùng cho simple feedback → dùng **Toast** / **SnackBar**.
+- Không dùng cho form input → navigate to dedicated screen.
+- Không stack multiple PopupNotify dialogs.
+- Không >2 action buttons.
+- Không dùng cho informational messages without decision → dùng **Information**.

package/.claude/skills/design-system/references/components/progress-info.md

@@ -0,0 +1,114 @@
+# Progress Info
+
+> Linear progress bar with optional label, used to display completion status, upload progress, or goal tracking.
+
+**Package:** `@momo-kits/progress-info`
+**Platform support:** RN ✅ | Compose ❌ (use LinearProgressIndicator)
+
+---
+
+## Anatomy
+
+```
+    Title Label (optional)
+    ┌──────────────────────────────────────┐
+    │████████████░░░░░░░░░░░░░░░░░░░░░░░░░│  ← Track with fill
+    └──────────────────────────────────────┘
+```
+
+| Part        | Description                                        | Required |
+|-------------|-----------------------------------------------------|----------|
+| Track       | Full-width background bar                           | Yes      |
+| Fill        | Colored portion representing progress               | Yes      |
+| Title       | Text label above the bar describing what is tracked | No       |
+
+---
+
+## Visual Specs
+
+### Track
+
+| Property      | Token / Value                |
+|---------------|------------------------------|
+| Background    | `Colors.black_04`            |
+| Height        | 4-8 dp                       |
+| Corner radius | `Radius.XS`                 |
+| Width         | Full width of parent         |
+
+### Fill
+
+| Property      | Token / Value                              |
+|---------------|--------------------------------------------|
+| Color         | `Colors.pink_03` (default, themeable)      |
+| Height        | Same as track height                        |
+| Corner radius | `Radius.XS`                               |
+| Min width     | 0 dp (at 0% progress)                     |
+| Max width     | Full track width (at 100% progress)        |
+
+### Title
+
+| Property      | Token / Value                |
+|---------------|------------------------------|
+| Typography    | `body_default_regular`       |
+| Color         | Default text color           |
+| Position      | Above the progress bar       |
+| Spacing below | `Spacing.XS` (4) to track   |
+
+---
+
+## Progress Value
+
+| Property     | Value                                    |
+|--------------|------------------------------------------|
+| Range        | 0.0 (empty) to 1.0 (full)               |
+| Direction    | Left-to-right fill                        |
+
+---
+
+## Animation
+
+| Property       | Value                                         |
+|----------------|-----------------------------------------------|
+| Fill animation | Smooth animated transition when value changes |
+| Direction      | Left-to-right                                 |
+
+- When the progress value updates, the fill bar should animate smoothly to its new width.
+- The animation should feel responsive but not jarring.
+
+---
+
+## States
+
+| State            | Appearance                                       |
+|------------------|--------------------------------------------------|
+| **Empty (0.0)**  | Track only, no fill visible                      |
+| **In progress**  | Partial fill proportional to value               |
+| **Complete (1.0)**| Fill covers entire track                        |
+
+---
+
+## Accessibility
+
+- Announce the progress value as a percentage to screen readers (e.g., "Progress: 65%").
+- If a title label is present, associate it with the progress bar for context (e.g., "Upload progress: 65%").
+- Progress updates should be announced when they change significantly (not on every frame).
+
+---
+
+## Usage Guidelines
+
+### Do's
+
+- Use for upload or download progress indicators.
+- Use for goal completion tracking (e.g., savings goals, profile completeness).
+- Use for step completion within a process.
+- Provide a title label for context when the progress meaning is not obvious from surrounding content.
+- Use animated transitions when the progress value changes.
+
+### Don'ts
+
+- Don't use for indeterminate loading states — use a Loader or Skeleton component instead.
+- Don't use values outside the 0.0-1.0 range.
+- Don't use a progress bar for tiny increments that won't be visually perceptible — consider a numeric display instead.
+- Don't use multiple fill colors within a single progress bar — keep it simple.
+- Don't place progress bars where they might be confused with dividers — include a title or surrounding context.

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

@@ -0,0 +1,86 @@
+# Radio
+
+> Selection control — chọn exactly 1 option từ mutually exclusive set. Value + groupValue pattern.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `value` | string | — | required | Unique identifier cho radio option này |
+| `groupValue` | string | — | — | Currently selected value trong group. Radio selected khi `value == groupValue` |
+| `label` | string | — | — | Text label bên phải radio circle |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive state |
+| `onChange` | function | — | — | Callback khi selected. `"onChange": "setState://selectedOption"` |
+
+---
+
+## States
+
+| State | Circle Border | Inner Dot | Label Color | Interactive |
+|-------|-------------|----------|------------|-------------|
+| **Unselected** | `Colors.black_04` | none | `Colors.black_17` | true |
+| **Selected** | `Colors.pink_03` | `Colors.pink_03` fill | `Colors.black_17` | true |
+| **Disabled Unselected** | `Colors.black_08` | none | `Colors.black_08` | false |
+| **Disabled Selected** | `Colors.black_08` | `Colors.black_08` fill | `Colors.black_08` | false |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Single selection** | Chọn 1 từ 2-5 mutually exclusive options | >5 options → dùng InputDropDown | Chọn phương thức thanh toán, chọn lý do hủy |
+| **Default pre-selected** | Recommend 1 option | Không muốn bias user | Chọn gói cước với recommended option |
+
+---
+
+## SSR Pattern
+
+### Radio Group
+```json
+{
+  "id": "payment_method",
+  "type": "section",
+  "forEach": "{{data.paymentMethods}}",
+  "render": {
+    "component": "Radio",
+    "props": {
+      "value": "{{item.id}}",
+      "groupValue": "{{state.selectedMethod}}",
+      "label": "{{item.name}}"
+    },
+    "onChange": "setState://selectedMethod={{item.id}}"
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Screen readers announce: label, state (selected/unselected), role (radio button), position ("1 of 3").
+- Entire row (circle + label) tappable.
+- Radio groups PHẢI có group label.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho single selection từ 2-5 mutually exclusive options.
+- Luôn display trong group — single radio alone vô nghĩa.
+- Pre-select default option khi có recommendation.
+- Vertical list layout cho clarity.
+
+### Don't
+- Không dùng cho multiple selection → dùng **CheckBox**.
+- Không dùng cho >5 options → dùng **InputDropDown**.
+- Không dùng cho on/off toggle → dùng **Switch**.
+- Radio selections không toggle off — once selected, phải chọn option khác.

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

@@ -0,0 +1,126 @@
+# Rating
+
+> Star-based rating display và input — product reviews, service feedback, quality indicators.
+
+**Package:** `@momo-kits/rating`
+**Platform:** RN ✅ | Compose ❌ (build with Row of Icons)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `value` | number | `0` - `5` | `0` | Current rating value. Supports 0.5 increments for display mode |
+| `size` | string | `"small"` \| `"medium"` \| `"large"` | `"medium"` | Star size [VERIFY] |
+| `interactive` | boolean | `true` \| `false` | `true` | Interactive (input) vs display-only (read-only) [VERIFY] |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive, reduced opacity |
+| `onChange` | function | — | — | Callback khi tap star. `"onChange": "setState://rating"` |
+
+---
+
+## Variants
+
+| Mode | Granularity | Half-star | Tappable |
+|------|-----------|----------|---------|
+| **Interactive** | Whole stars only (1-5) | No | Yes |
+| **Display-only** | 0.5 increments (0.0-5.0) | Yes | No |
+
+### Star Colors
+
+| Part | Color |
+|------|-------|
+| Active (filled) | `Colors.gold_03` |
+| Inactive (outline) | `Colors.black_08` |
+| Half-star left | `Colors.gold_03` filled |
+| Half-star right | `Colors.black_08` outline |
+
+---
+
+## States
+
+| State | Appearance | Interactive |
+|-------|-----------|-------------|
+| **Empty (0)** | All 5 stars outlined | per mode |
+| **Partial (1-4)** | N filled + remaining outlined | per mode |
+| **Full (5)** | All 5 stars filled | per mode |
+| **Disabled** | All stars reduced opacity (0.4) | false |
+
+---
+
+## Variant-to-Context Map
+
+| Mode | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|------|-------------|-----------|-------------------|
+| **Interactive** | User submit feedback/review | Read-only display | Đánh giá merchant sau giao dịch, feedback dịch vụ |
+| **Display-only** | Show aggregate/existing rating | User cần input | Rating trung bình merchant, review score |
+
+---
+
+## SSR Pattern
+
+### Interactive Rating in Feedback Form
+```json
+{
+  "component": "Rating",
+  "props": {
+    "value": "{{state.rating}}",
+    "size": "large",
+    "interactive": true
+  },
+  "onChange": "setState://rating"
+}
+```
+
+### Display Rating with Number
+```json
+{
+  "id": "rating_display",
+  "type": "row",
+  "children": [
+    {
+      "component": "Rating",
+      "props": {
+        "value": "{{data.averageRating}}",
+        "size": "small",
+        "interactive": false
+      }
+    },
+    {
+      "component": "Text",
+      "props": {
+        "content": "{{data.averageRating}} / 5",
+        "typography": "body_s_regular",
+        "color": "Colors.black_12"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Announce current rating: "Rating: 4 out of 5 stars".
+- Interactive mode: each star individually selectable.
+- Display-only: announce as informational text.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho product/service reviews.
+- Display-only cho aggregate ratings. Pair với numeric label khi precision matters.
+- Half-star display cho averaged ratings (4.3 → 4.5 stars).
+- Consistent sizing within same context.
+
+### Don't
+- Không dùng cho binary like/dislike → dùng **Button** / **Switch**.
+- Không dùng cho non-quality metrics — stars imply quality.
+- Không allow half-star input — interactive chỉ whole stars.
+- Không dùng >5 hoặc <5 stars.
+- Không change star color from gold.

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

@@ -0,0 +1,120 @@
+# Skeleton
+
+> Loading placeholder mimics content shape — shimmer animation khi data đang fetch.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `width` | number/string | dp \| `"100%"` | `"100%"` | Skeleton width [VERIFY] |
+| `height` | number | dp | required | Skeleton height [VERIFY] |
+| `borderRadius` | number/string | dp \| `"circle"` | `0` | Corner radius. `"circle"` cho avatar shape [VERIFY] |
+| `animated` | boolean | `true` \| `false` | `true` | Enable shimmer animation [VERIFY] |
+
+> **Compose:** Skeletons dùng `BoxWithConstraints` — auto-adapt to parent size.
+
+---
+
+## Variants
+
+Skeleton không có visual variants — shape phụ thuộc content nó replace.
+
+| Content Type | Shape | borderRadius |
+|-------------|-------|-------------|
+| Text line | Rectangle narrow | small |
+| Avatar | Circle | `"circle"` |
+| Thumbnail/Image | Rectangle matching aspect ratio | medium |
+| Card | Rounded rectangle | card radius |
+| Button | Rounded rectangle matching button | pill |
+
+---
+
+## States
+
+| State | Base Color | Highlight Color | Animation |
+|-------|-----------|----------------|-----------|
+| **Loading** | `Colors.black_03` | `Colors.black_04` | Pulsing shimmer, continuous loop |
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **Content loading** | Data đang fetch, layout structure known | Content loads instantly → không cần | Transaction list loading, feed loading |
+| **Lazy section** | Section lazy-loaded within screen | Full-screen initial load → dùng Loader | Card section loading trên Home |
+| **Image placeholder** | Image đang download | — | Avatar loading, banner loading |
+
+---
+
+## SSR Pattern
+
+### User Card Skeleton
+```json
+{
+  "id": "user_skeleton",
+  "type": "row",
+  "children": [
+    {
+      "component": "Skeleton",
+      "props": {
+        "width": 48,
+        "height": 48,
+        "borderRadius": "circle"
+      }
+    },
+    {
+      "id": "text_skeleton",
+      "type": "section",
+      "children": [
+        {
+          "component": "Skeleton",
+          "props": {
+            "width": "60%",
+            "height": 16,
+            "borderRadius": 4
+          }
+        },
+        {
+          "component": "Skeleton",
+          "props": {
+            "width": "40%",
+            "height": 12,
+            "borderRadius": 4
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Skeleton areas announce "Đang tải" cho screen readers.
+- Khi content loaded → loaded content nhận focus và announce.
+- Skeleton không focusable hoặc interactive.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho content loading states khi layout structure known.
+- Match skeleton shapes to actual content layout.
+- Group multiple skeletons cho full content block (avatar circle + text rectangles).
+
+### Don't
+- Không dùng cho action loading (button submit) → dùng **Button** loading state.
+- Không dùng cho full-screen initial load → dùng **Loader**.
+- Không để skeleton visible indefinitely — show error/empty state nếu loading fails.
+- Không dùng cho content loads instantly — unnecessary visual noise.