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

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

@@ -0,0 +1,146 @@
+# Chip
+
+> Interactive filter/selection pill — toggle giữa selected/unselected khi tap.
+
+**Package:** `@momo-kits/chip`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `label` | string | — | required | Display text. 1-3 words |
+| `size` | string | `"small"` \| `"large"` | `"small"` | Chip size |
+| `selected` | boolean | `true` \| `false` | `false` | Selection state |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive state |
+| `leftIcon` | string | icon name | — | Optional icon trước label |
+| `rightIcon` | string | icon name \| `"close"` | — | Optional icon sau label. `"close"` cho removable chip |
+| `onPress` | function | — | — | Tap handler — toggle selected state |
+| `onPressRightIcon` | function | — | — | Right icon tap — remove/deselect [VERIFY] |
+
+> **Lưu ý cho ui-composer:** Chip dùng package riêng `@momo-kits/chip`, không nằm trong `@momo-kits/foundation`.
+
+---
+
+## Variants
+
+| Variant | Background | Text Color | Icon Color | Usage |
+|---------|-----------|-----------|-----------|-------|
+| **Unselected** | `Colors.black_04` | `Colors.black_17` | `Colors.black_12` | Default resting state |
+| **Selected** | `Colors.pink_09` | `Colors.pink_03` | `Colors.pink_03` | Active / chosen state |
+
+---
+
+## States
+
+| State | Background | Text Color | Icon Color | Opacity | Interactive |
+|-------|-----------|-----------|-----------|---------|-------------|
+| **Unselected** | `Colors.black_04` | `Colors.black_17` | `Colors.black_12` | 1 | true |
+| **Selected** | `Colors.pink_09` | `Colors.pink_03` | `Colors.pink_03` | 1 | true |
+| **Pressed** | same as current | same as current | same as current | 0.8 | true |
+| **Disabled** | `Colors.black_04` | `Colors.black_08` | `Colors.black_08` | 0.5 | false |
+
+Transition giữa unselected ↔ selected là immediate (no animation).
+
+---
+
+## Variant-to-Context Map
+
+| Variant | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| Unselected (default) | Chip chưa được chọn trong filter group | Chỉ có 1 chip đơn lẻ — không có group | Filter dịch vụ trên màn hình tìm kiếm (Tất cả / Chuyển tiền / Thanh toán) |
+| Selected | User đã chọn — active filter đang apply | Không có toggle behavior — dùng Tag | Filter "Chuyển tiền" đang active trong lịch sử GD |
+| Removable (rightIcon=close) | User remove selection bằng tap X | Label dài >3 từ — chip bị stretch | Địa chỉ đã chọn trong form giao hàng, tags đã pick |
+
+---
+
+## SSR Pattern
+
+### Horizontal Filter Bar
+```json
+{
+  "id": "filter_chips",
+  "type": "row",
+  "scrollable": true,
+  "spacing": "Spacing.XS",
+  "forEach": "{{data.filterOptions}}",
+  "render": {
+    "component": "Chip",
+    "props": {
+      "label": "{{item.label}}",
+      "size": "small",
+      "selected": "{{state.selectedFilter == $index}}"
+    },
+    "onPress": "setState://selectedFilter=$index"
+  }
+}
+```
+
+### Multi-select Wrap Group
+```json
+{
+  "id": "category_chips",
+  "type": "wrap",
+  "forEach": "{{data.categories}}",
+  "render": {
+    "component": "Chip",
+    "props": {
+      "label": "{{item.name}}",
+      "size": "large",
+      "selected": "{{item.selected}}",
+      "leftIcon": "{{item.icon}}"
+    },
+    "onPress": "setState://toggleCategory={{item.id}}"
+  }
+}
+```
+
+### Removable Tags
+```json
+{
+  "id": "selected_tags",
+  "type": "wrap",
+  "forEach": "{{state.selectedItems}}",
+  "render": {
+    "component": "Chip",
+    "props": {
+      "label": "{{item.name}}",
+      "size": "small",
+      "selected": true,
+      "rightIcon": "close"
+    },
+    "onPressRightIcon": "setState://removeItem={{item.id}}"
+  }
+}
+```
+
+---
+
+## Accessibility
+
+- Mỗi chip cần accessible label gồm: text + current state (selected/not).
+- Role: `"button"` hoặc `"toggle"` — screen readers phải announce interactive nature.
+- Khi selected state thay đổi: announce "Selected" hoặc "Deselected".
+- Trong chip group: navigable as a group với clear boundaries.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng Chip để filter content theo category, type, attribute.
+- Dùng cho multi-select — user pick từ set of options.
+- Dùng cho removable selections (dismiss bằng X icon).
+- Giữ label ngắn — 1-3 words.
+- Group related chips trong horizontal scrollable row hoặc wrapping layout.
+
+### Don't
+- Không dùng cho static status display — dùng **Tag**.
+- Không dùng cho navigation actions — dùng **Button**.
+- Không dùng cho notification counts — dùng **Badge**.
+- Không nest interactive elements bên trong Chip.
+- Không dùng text label dài gây stretch chip.

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

@@ -0,0 +1,120 @@
+# Collapse
+
+> Expandable/collapsible content section — header + chevron toggle to show/hide content. Progressive disclosure.
+
+**Package:** `@momo-kits/collapse`
+**Platform:** RN ✅ | Compose ❌ (build with AnimatedVisibility)
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `title` | string | — | required | Header text label |
+| `expanded` | boolean | `true` \| `false` | `false` | Controlled expand/collapse state |
+| `defaultExpanded` | boolean | `true` \| `false` | `false` | Initial state khi uncontrolled [VERIFY] |
+| `disabled` | boolean | `true` \| `false` | `false` | Non-interactive — header not tappable |
+| `showDivider` | boolean | `true` \| `false` | `false` | Show Divider between header and content [VERIFY] |
+| `children` | element | — | required | Content to show/hide — any components |
+| `onChange` | function | — | — | Callback khi toggle. `"onChange": "setState://expanded"` |
+
+---
+
+## States
+
+| State | Header | Chevron | Content | Interactive |
+|-------|--------|---------|---------|-------------|
+| **Collapsed** | `Colors.black_17` text | Down (0°) | Hidden | true |
+| **Expanded** | `Colors.black_17` text | Up (180°) | Visible | true |
+| **Pressed** | Opacity 0.8 | — | — | true |
+| **Disabled** | `Colors.black_08` text | `Colors.black_08` | Per current state | false |
+
+Chevron rotates smoothly (180°) on toggle. Content animates with height transition.
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **FAQ / Help** | Q&A sections, supplementary info | Primary content → show directly | FAQ trong Help center |
+| **Advanced settings** | Secondary options user rarely needs | Critical settings → show always | Cài đặt nâng cao, tùy chọn bổ sung |
+| **Accordion** | Multiple collapse sections, one open at a time | Independent sections | Chi tiết giao dịch, điều khoản |
+
+---
+
+## SSR Pattern
+
+### FAQ Section
+```json
+{
+  "id": "faq_section",
+  "type": "section",
+  "forEach": "{{data.faqs}}",
+  "render": {
+    "component": "Collapse",
+    "props": {
+      "title": "{{item.question}}",
+      "expanded": false
+    },
+    "children": [
+      {
+        "component": "Text",
+        "props": {
+          "content": "{{item.answer}}",
+          "typography": "body_default_regular"
+        }
+      }
+    ]
+  }
+}
+```
+
+### Transaction Details Accordion
+```json
+{
+  "component": "Collapse",
+  "props": {
+    "title": "Chi tiết giao dịch",
+    "showDivider": true
+  },
+  "children": [
+    {
+      "component": "Text",
+      "props": {
+        "content": "{{data.transactionDetails}}",
+        "typography": "body_s_regular"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Header role: button. Announce title + state ("Chi tiết giao dịch, collapsed").
+- Content hidden from accessibility tree khi collapsed.
+- Full header row is tap target, not just chevron.
+- State change announced on toggle.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho secondary/supplementary content — FAQ, advanced settings, details.
+- Clear descriptive title — user knows what content is hidden.
+- Start collapsed by default unless content is expected to be read immediately.
+- Divider khi content is visually dense.
+
+### Don't
+- Không hide primary/critical content trong collapse.
+- Không dùng cho navigation → dùng proper nav patterns.
+- Không nest collapse deeply (collapse trong collapse) — confusing UX.
+- Không dùng khi content chỉ 1-2 lines — show directly instead.
+- Không remove chevron icon — user cần visual indicator.

package/.claude/skills/design-system/references/components/date-picker.md

@@ -0,0 +1,119 @@
+# DatePicker
+
+> Calendar-based date selection — single date, date range, or multiple dates. Month grid (RN) or format-driven (Compose).
+
+**Package:** `@momo-kits/date-picker` (RN) / built-in (Compose)
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Variant Axes
+
+| Axis | Options | Default |
+|------|---------|---------|
+| **Mode** | `single` · `range` · `multiple` | `single` |
+| **Platform** | RN (calendar grid) · Compose (format-driven DD-MM-YYYY) | per platform |
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `mode` | string | `"single"` \| `"range"` \| `"multiple"` | `"single"` | Selection mode |
+| `value` | varies | Date (single), `{ start, end }` (range), `[Date]` (multiple) | — | Current selected value |
+| `minDate` | date | — | — | Earliest selectable date. Dates before → disabled |
+| `maxDate` | date | — | — | Latest selectable date. Dates after → disabled |
+| `format` | string | date format pattern | `"DD-MM-YYYY"` | Display format (Compose) [VERIFY] |
+| `showTimePicker` | boolean | `true` \| `false` | `false` | Include time selection (Compose: HH:mm) [VERIFY] |
+| `onChange` | function | — | — | Callback khi date selected. `"onChange": "setState://selectedDate"` |
+
+---
+
+## Day Cell States
+
+| State | Background | Text Color | Description |
+|-------|-----------|-----------|-------------|
+| **Default** | Transparent | `Colors.black_17` | Normal selectable date |
+| **Today** | Transparent | `Colors.pink_03` | Current date highlight |
+| **Selected** | `Colors.pink_03` circle | `Colors.white` | User-chosen date |
+| **Disabled** | Transparent | `Colors.black_08` | Outside min/max range |
+| **Range start** | `Colors.pink_03` (left-rounded) | `Colors.white` | First date in range |
+| **Range end** | `Colors.pink_03` (right-rounded) | `Colors.white` | Last date in range |
+| **In range** | `Colors.pink_09` (light pink) | `Colors.pink_03` | Dates between start/end |
+| **Other month** | Transparent | `Colors.black_08` | Adjacent month dates |
+
+---
+
+## Variant-to-Context Map
+
+| Mode | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|------|-------------|-----------|-------------------|
+| **single** | Pick one specific date | Date range needed | Chọn ngày sinh, ngày hẹn |
+| **range** | Select start + end date | Single date needed | Lọc lịch sử giao dịch, đặt phòng |
+| **multiple** | Select multiple individual dates | Continuous range → dùng range mode | Chọn nhiều ngày nghỉ |
+
+---
+
+## SSR Pattern
+
+### Single Date Selection
+```json
+{
+  "component": "DatePicker",
+  "props": {
+    "mode": "single",
+    "value": "{{state.selectedDate}}",
+    "minDate": "{{data.today}}",
+    "maxDate": "{{data.maxBookingDate}}"
+  },
+  "onChange": "setState://selectedDate"
+}
+```
+
+### Date Range Filter
+```json
+{
+  "component": "DatePicker",
+  "props": {
+    "mode": "range",
+    "value": {
+      "start": "{{state.startDate}}",
+      "end": "{{state.endDate}}"
+    },
+    "minDate": "{{data.earliestTransaction}}"
+  },
+  "onChange": "setState://dateRange"
+}
+```
+
+---
+
+## Accessibility
+
+- Each day cell announces full date: "26 tháng 3 năm 2026".
+- Selected dates announce selected state.
+- Disabled dates: announced as disabled, not focusable/tappable.
+- Navigation arrows: "Tháng trước", "Tháng sau".
+- Range mode: announce context "Ngày bắt đầu: 20 tháng 3. Ngày kết thúc: 26 tháng 3."
+- Today distinguishable: "Hôm nay, 20 tháng 3 năm 2026".
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng cho date selection trong forms, booking, scheduling.
+- Highlight today cho reference point.
+- Disable dates outside valid range.
+- Show selected date in text field bên ngoài calendar cho confirmation.
+- Range mode cho check-in/check-out, date filters.
+
+### Don't
+- Không dùng cho time-only selection → dùng dedicated time picker.
+- Không allow selection of disabled dates.
+- Không show quá nhiều months — month-by-month navigation.
+- Không hide current month/year — user cần context.
+- Không dùng cho relative dates ("7 ngày gần nhất") → dùng **Chip** preset options.

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

@@ -0,0 +1,84 @@
+# Divider
+
+> Horizontal line separator — phân chia content sections hoặc list items.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** done
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `color` | string | `Colors.*` token | `"Colors.black_04"` | Line color [VERIFY] |
+
+> Divider là component đơn giản nhất — chỉ 1 prop optional. Full width of parent container by default.
+
+---
+
+## States
+
+| State | Color | Description |
+|-------|-------|-------------|
+| **Default** | `Colors.black_04` | Static, non-interactive |
+
+Divider chỉ có 1 state. Không interactive.
+
+---
+
+## Variant-to-Context Map
+
+| Context | Khi nào dùng | Tránh khi | Ví dụ trong MoMo |
+|---------|-------------|-----------|-------------------|
+| **List separator** | Phân cách items trong vertical list | Spacing đủ clear → không cần divider | Danh sách giao dịch, contacts list |
+| **Section boundary** | Phân chia content sections | Chỉ có 1 section → không cần | Phân chia "Thông tin" và "Số tiền" trong confirm screen |
+
+---
+
+## SSR Pattern
+
+### List with Dividers
+```json
+{
+  "id": "transaction_list",
+  "type": "section",
+  "forEach": "{{data.transactions}}",
+  "render": [
+    {
+      "component": "ListItem",
+      "props": {
+        "title": "{{item.title}}",
+        "rightText": "{{item.amount}}"
+      }
+    },
+    {
+      "component": "Divider",
+      "props": {}
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Divider là decorative — ẩn khỏi screen readers.
+- Không dùng divider để convey meaning — chỉ visual separator.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng để separate list items trong vertical list.
+- Dùng sparingly — rely on spacing trước.
+- Parent layout control spacing above/below divider.
+
+### Don't
+- Không dùng cho purely decorative khi spacing đủ.
+- Không stack multiple dividers.
+- Không đặt divider ở top/bottom container khi không cần separation.

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

@@ -0,0 +1,130 @@
+# Icon
+
+> Vector icon component — render icons từ design system icon set cho actions, navigation, và visual cues.
+
+**Package:** `@momo-kits/foundation`
+**Platform:** RN ✅ | Compose ✅
+**Completeness:** need_update — thiếu Figma
+**Figma node:** [VERIFY]
+
+---
+
+## Props
+
+| Prop | Type | Values | Default | Description |
+|------|------|--------|---------|-------------|
+| `name` | string | icon name | required | Icon identifier từ icon set [VERIFY] |
+| `size` | string | `"inline"` \| `"default"` \| `"standard"` \| `"featured"` \| `"hero"` | `"default"` | Icon size [VERIFY] |
+| `color` | string | `Colors.*` token | `"Colors.black_17"` | Icon color. Có thể inherit từ parent [VERIFY] |
+
+---
+
+## Variants
+
+| Size | Dimension | Usage |
+|------|-----------|-------|
+| **inline** | 16×16pt | Inline with text, small indicators |
+| **default** | 20×20pt | Default cho most UI contexts |
+| **standard** | 24×24pt | Navigation bars, action buttons, list items |
+| **featured** | 32×32pt | Emphasized icons, feature highlights |
+| **hero** | 48×48pt | Empty states, onboarding, large call-outs |
+
+### Color Context
+
+| Context | Color Token |
+|---------|-----------|
+| Primary content | `Colors.black_17` |
+| Secondary | `Colors.black_15` |
+| Hint/placeholder | `Colors.black_12` |
+| Disabled | `Colors.black_08` |
+| Accent/interactive | `Colors.pink_03` |
+| Error | `Colors.red_03` |
+| On dark background | `Colors.white` |
+
+---
+
+## States
+
+| State | Color | Description |
+|-------|-------|-------------|
+| **Default** | per `color` prop | Normal display |
+| **Disabled** | `Colors.black_08` | Non-interactive context |
+
+Icon là static display. States chỉ ảnh hưởng color.
+
+---
+
+## Variant-to-Context Map
+
+| Size | Color | Khi nào dùng | Ví dụ trong MoMo |
+|------|-------|-------------|-------------------|
+| `standard` | `Colors.black_17` | Navigation bar, toolbar icons | Back arrow, search icon trong TopNav |
+| `inline` | `Colors.black_12` | Inline with text | Icon trước hint text |
+| `featured` | `Colors.pink_03` | Feature highlights | Service icons trên Home |
+| `hero` | `Colors.black_12` | Empty state illustrations | Empty transaction list icon |
+
+---
+
+## SSR Pattern
+
+### Icon in Navigation Action
+```json
+{
+  "component": "Icon",
+  "props": {
+    "name": "navigation_search",
+    "size": "standard",
+    "color": "Colors.black_17"
+  }
+}
+```
+
+### Icon Inline with Text
+```json
+{
+  "id": "info_row",
+  "type": "row",
+  "children": [
+    {
+      "component": "Icon",
+      "props": {
+        "name": "info_circle",
+        "size": "inline",
+        "color": "Colors.blue_03"
+      }
+    },
+    {
+      "component": "Text",
+      "props": {
+        "content": "Phí giao dịch miễn phí",
+        "typography": "caption_default_regular",
+        "color": "Colors.blue_03"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Accessibility
+
+- Interactive icons: PHẢI có text accessible label. Icon-only button → provide label.
+- Decorative icons (next to text label): ẩn khỏi screen readers.
+- Không rely solely on icon color để convey state — pair với indicators.
+
+---
+
+## Usage Guidelines
+
+### Do
+- Dùng predefined sizes consistently.
+- Dùng `Colors.*` tokens cho tất cả icon colors.
+- Provide accessible labels cho tất cả interactive icons.
+- `standard` (24pt) cho navigation/toolbar. `inline` (16pt) cho text.
+
+### Don't
+- Không dùng icon là sole means of communication without accessible label.
+- Không scale icons to arbitrary sizes giữa predefined steps.
+- Không dùng raw hex colors — luôn reference design tokens.
+- Không dùng overly detailed graphics làm icons.

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

@@ -0,0 +1,81 @@
+# Image
+
+## Description
+
+An image display component for rendering photos, illustrations, and banners with built-in loading state support. Image handles URL-based loading, displays a skeleton or placeholder while content is being fetched, and supports aspect ratio control to maintain proper proportions.
+
+**Package:** `@momo-kits/foundation`
+**Platform support:** RN ✅ | Compose ✅
+
+---
+
+## Features
+
+| Feature            | Description                                                  |
+|--------------------|--------------------------------------------------------------|
+| **URL loading**    | Loads images from remote URLs with automatic caching         |
+| **Aspect ratio**   | Maintains image proportions via configurable aspect ratio    |
+| **Loading state**  | Displays a skeleton or placeholder while the image loads     |
+| **Error fallback** | Shows a fallback placeholder if the image fails to load      |
+
+---
+
+## Loading States
+
+| State       | Visual                                                       |
+|-------------|--------------------------------------------------------------|
+| **Loading** | Skeleton placeholder (animated shimmer) matching the image dimensions |
+| **Loaded**  | Full image displayed, skeleton fades out                     |
+| **Error**   | Static fallback placeholder (generic image icon or custom)   |
+
+- The skeleton placeholder should match the expected dimensions of the final image to prevent layout shifts
+- Transition from skeleton to loaded image should use a subtle fade-in
+
+---
+
+## Sizing
+
+- Image dimensions are constrained by the parent container
+- Aspect ratio can be explicitly set to maintain proportions regardless of container size
+- Common aspect ratios: 1:1 (square), 16:9 (banner), 4:3 (photo), 3:2 (landscape)
+- When only width or height is provided, the other dimension is calculated from the aspect ratio
+- If no aspect ratio is specified, the image uses its natural dimensions constrained by the parent
+
+---
+
+## Layout
+
+- Images fill their container by default (resize mode: cover)
+- Other resize modes: contain (fit within bounds), stretch (fill exactly), center (no scaling)
+- Corner radius can be applied for rounded images (use `Radius.*` tokens)
+- For circular images (e.g., avatars), apply a radius equal to half the width/height
+- Images should not overflow their container — clip content at the container bounds
+
+---
+
+## Accessibility
+
+- **Alt text required:** Always provide descriptive alt text that conveys the content or purpose of the image
+- **Decorative images:** If an image is purely decorative and adds no informational value, mark it as decorative so screen readers skip it
+- **Loading announcement:** Screen readers should not announce the loading state repeatedly — announce once when the image finishes loading if it is meaningful content
+- **Error state:** If the image fails to load, the fallback should convey that the content is unavailable
+
+---
+
+## Do's and Don'ts
+
+### Do's
+- Always provide alt text that describes the image content or purpose
+- Set an explicit aspect ratio to prevent layout shifts during loading
+- Use the skeleton loading state for all remotely loaded images
+- Optimize image URLs for the target display size (avoid loading oversized assets)
+- Use appropriate resize mode based on context (cover for banners, contain for logos)
+- Apply `Radius.*` tokens for rounded corners
+
+### Don'ts
+- Don't use Image for vector icons — use the Icon component instead
+- Don't leave alt text empty for meaningful images
+- Don't load full-resolution images when a thumbnail would suffice
+- Don't allow images to cause layout shifts by omitting dimensions or aspect ratio
+- Don't use stretch resize mode for photos — it distorts the content
+- Don't hard-code pixel dimensions when the layout should be responsive to the container