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

package/.claude/skills/design-system-kits/references/navigation/bottom-tab.md

@@ -0,0 +1,155 @@
+# Bottom Tab Navigation
+
+## React Native — BottomTab
+
+The `BottomTab` component from `@momo-kits/foundation` wraps `@react-navigation/bottom-tabs` with KitX styling.
+
+```tsx
+import { BottomTab } from '@momo-kits/foundation';
+
+<BottomTab
+  navigation={navigation}
+  initialRouteName="Home"
+  tabs={[
+    {
+      name: 'Home',
+      label: 'Home',
+      icon: 'ic_home',
+      screen: HomeScreen,
+      options: { headerTitle: 'Home' },
+    },
+    {
+      name: 'Search',
+      label: 'Search',
+      icon: 'ic_search',
+      screen: SearchScreen,
+      options: { headerTitle: 'Search' },
+    },
+    {
+      name: 'Profile',
+      label: 'Profile',
+      icon: 'ic_profile',
+      badgeLabel: '3',
+      screen: ProfileScreen,
+      options: { headerTitle: 'Profile' },
+    },
+  ]}
+  floatingButton={{
+    icon: 'ic_plus',
+    label: 'New',
+    onPress: () => handleNewAction(),
+  }}
+/>
+```
+
+### BottomTab Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tabs` | `BottomTabItemProps[]` | required | Array of tab configurations |
+| `navigation` | `NavigationProps` | required | Navigation object from parent |
+| `initialRouteName` | `string` | — | Initially focused tab name |
+| `nested` | `boolean` | — | Whether tabs use shared parent stack or independent NavigationContainer |
+| `listeners` | `{ tabPress?, focus?, blur? }` | — | Event listeners for tab events |
+| `floatingButton` | `FloatingButtonProps` | — | Center floating action button |
+
+### BottomTabItemProps
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | required | Tab route identifier |
+| `label` | `string` | required | Tab bar display label |
+| `icon` | `string` | required | Icon source string |
+| `screen` | `React.ComponentType` | required | Tab content component |
+| `options` | `NavigationOptions` | required | Navigation options for this tab |
+| `badgeLabel` | `string \| number` | — | Badge: `""` = dot, `"3"` = count, `0` = hidden |
+| `showDot` | `boolean` | — | Legacy prop (dot behavior is controlled by `badgeLabel=""`) |
+| `initialParams` | `any` | — | Initial params passed to the tab screen |
+
+### FloatingButtonProps
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | `string \| ReactNode` | FAB icon (required) |
+| `label` | `string` | FAB label (required) |
+| `onPress` | `() => void` | Click handler (required) |
+| `container` | `ReactNode` | Custom container component |
+
+### Tab Bar Details
+
+- Icon size: 28px
+- Animated indicator pill: 44px wide, centered in selected tab
+- Tab transitions: fade + scale (200ms)
+- Supports badges (dot via `badgeLabel=""` and count via `badgeLabel="3"`)
+
+---
+
+## Compose
+
+```kotlin
+import vn.momo.kits.navigation.bottomtab.BottomTab
+import vn.momo.kits.navigation.bottomtab.BottomTabItem
+import vn.momo.kits.navigation.bottomtab.BottomTabFloatingButton
+
+BottomTab(
+    items = listOf(
+        BottomTabItem(
+            name = "home",
+            label = "Home",
+            icon = "ic_home",
+            screen = { HomeScreen() },
+            options = NavigationOptions(
+                headerTitle = HeaderTitle.Default("Home"),
+            ),
+        ),
+        BottomTabItem(
+            name = "search",
+            label = "Search",
+            icon = "ic_search",
+            screen = { SearchScreen() },
+        ),
+        BottomTabItem(
+            name = "profile",
+            label = "Profile",
+            icon = "ic_profile",
+            showDot = true,
+            badgeLabel = "3",
+            screen = { ProfileScreen() },
+        ),
+    ),
+    floatingButton = BottomTabFloatingButton(
+        icon = "ic_plus",
+        label = "New",
+        onPress = { handleNewAction() },
+    ),
+)
+```
+
+### BottomTabItem
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `name` | String | Tab identifier |
+| `label` | String | Tab bar label |
+| `icon` | String | Icon source string |
+| `showDot` | Boolean | Show notification dot (default: false) |
+| `badgeLabel` | String? | Badge text (null = no badge, "0" = hidden) |
+| `screen` | @Composable () -> Unit | Tab content |
+| `options` | NavigationOptions? | Navigation config for this tab |
+
+### BottomTabFloatingButton
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | String | FAB icon |
+| `label` | String | FAB label |
+| `onPress` | () -> Unit | Click handler |
+
+The floating button appears centered between tabs with a curved container.
+
+### Tab Bar Details
+
+- Height: 64dp
+- Animated indicator bar follows selected tab
+- Supports badges (dot and count)
+- Tab transitions: fade + scale (200ms)

package/.claude/skills/design-system-kits/references/navigation/bottomsheet.md

@@ -0,0 +1,94 @@
+# Bottom Sheet
+
+## React Native — showBottomSheet
+
+Bottom sheets are displayed via `navigator.showBottomSheet()` from `ApplicationContext`.
+
+```tsx
+const { navigator } = useContext(ApplicationContext);
+
+navigator.showBottomSheet({
+  screen: SheetContent,
+  options: { title: 'Sheet Title' },
+  surface: true,
+  draggable: true,
+  barrierDismissible: false,
+  onDismiss: (type) => console.log('dismissed by', type),
+});
+```
+
+Dismiss from inside:
+
+```tsx
+navigator.pop();
+// or from content component via injected prop:
+props.onRequestClose?.(() => {
+  // callback after dismiss animation
+});
+```
+
+### BottomSheetParams
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `screen` | `React.ComponentType` | required | Content component rendered inside the sheet |
+| `options.title` | `string` | — | Title shown in the header |
+| `options.header` | `ReactNode` | — | Custom header node (replaces title) |
+| `surface` | `boolean` | — | Use `background.surface` color instead of `background.default` |
+| `onDismiss` | `(type?: string) => void` | — | Callback on dismiss; `type` is `'touch'`, `'gesture'`, or `'icon_close'` |
+| `barrierDismissible` | `boolean` | `false` | Allow backdrop tap to dismiss |
+| `draggable` | `boolean` | `true` | Enable drag-to-dismiss gesture |
+| `useBottomInset` | `boolean` | `true` | Add safe area bottom inset padding |
+| `useKeyboardAvoidingView` | `boolean` | `true` | Wrap content in KeyboardAvoidingView |
+| `keyboardVerticalOffset` | `number` | auto | Override keyboard avoiding offset |
+| `useDivider` | `boolean` | `true` | Show bottom border under the header |
+| `footerComponent` | `ReactNode` | — | Sticky footer below content |
+| `useNativeModal` | `boolean` | `false` | Use native RN Modal (auto-enabled in widget mode) |
+| `leftOptions.iconLeft` | `string` | `'ic_back'` | Left header button icon |
+| `leftOptions.onPressIconLeft` | `() => void` | — | Left header button handler (adds a back button) |
+
+Additional params are spread as props to the content `screen` component.
+
+### Left Options (Back Navigation in Sheet)
+
+For stacked bottom sheets with back navigation:
+
+```tsx
+navigator.showBottomSheet({
+  screen: SecondSheet,
+  options: { title: 'Step 2' },
+  leftOptions: {
+    iconLeft: 'ic_back_ios',
+    onPressIconLeft: () => navigator.pop(),
+  },
+});
+```
+
+### Footer Component
+
+```tsx
+navigator.showBottomSheet({
+  screen: SheetContent,
+  options: { title: 'Selection' },
+  footerComponent: <Button title="Confirm" onPress={handleConfirm} />,
+});
+```
+
+---
+
+## Compose
+
+```kotlin
+navigator.showBottomSheet(
+    content = { SheetContent() },
+    isSurface = false,
+    barrierDismissible = true,
+    onDismiss = { },
+)
+```
+
+Dismiss from inside:
+
+```kotlin
+navigator.pop()
+```

package/.claude/skills/design-system-kits/references/navigation/modal.md

@@ -0,0 +1,125 @@
+# Modal
+
+## React Native — showModal
+
+Modal overlays are displayed via `navigator.showModal()` from `ApplicationContext`.
+
+```tsx
+const { navigator } = useContext(ApplicationContext);
+
+navigator.showModal(
+  {
+    screen: MyModalContent,
+    barrierDismissible: true,
+    onDismiss: () => console.log('dismissed'),
+  },
+  (error) => console.log(error), // optional onError callback
+);
+```
+
+Dismiss from inside:
+
+```tsx
+navigator.pop();
+// or from content component via injected prop:
+props.onRequestClose?.(() => {
+  // callback after dismiss animation
+});
+```
+
+### ModalParams
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `screen` | `React.ComponentType` | required | Content component to render inside the modal |
+| `barrierDismissible` | `boolean` | — | Allow backdrop tap to dismiss |
+| `onDismiss` | `() => void` | — | Callback when modal is dismissed |
+| `modalStyle` | `ViewStyle` | — | Custom style for the modal container |
+| `useNativeModal` | `boolean` | `false` | Use native RN Modal (auto-enabled in widget mode) |
+
+Additional params are spread as props to the content `screen` component.
+
+### PopupNotify in Modal
+
+Show a confirmation dialog by passing `PopupNotify` as the modal content:
+
+```tsx
+navigator.showModal({
+  screen: ({ onRequestClose }) => (
+    <PopupNotify
+      title="Confirm?"
+      description="Are you sure you want to proceed?"
+      primary={{ title: 'OK', onPress: () => onRequestClose?.() }}
+      secondary={{ title: 'Cancel', onPress: () => onRequestClose?.() }}
+      onRequestClose={onRequestClose}
+    />
+  ),
+  barrierDismissible: true,
+});
+```
+
+### PopupNotify Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Title text (required) |
+| `primary` | `{ title, onPress }` | Primary action button (required) |
+| `description` | `string \| ReactNode` | Description text |
+| `image` | `string` | Image URL/path |
+| `error` | `string` | Error message text |
+| `secondary` | `{ title, onPress }` | Secondary action button |
+| `buttonDirection` | `'row' \| 'column' \| 'auto'` | Button layout (`'auto'` switches based on title length > 12 chars) |
+| `onIconClose` | `() => void` | Close icon press handler |
+| `onRequestClose` | `(callback?) => void` | Dismiss modal — accepts optional callback that runs after dismiss animation |
+| `id` | `string` | Tracking component ID |
+
+### PopupPromotion
+
+Full-screen promotional modal with an image.
+
+```tsx
+navigator.showModal({
+  screen: ({ onRequestClose }) => (
+    <PopupPromotion
+      image="https://promo-image.png"
+      onActionClick={() => handlePromo()}
+      onIconClose={() => onRequestClose?.()}
+      onRequestClose={onRequestClose}
+    />
+  ),
+});
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `image` | `string` | Promotion image (required) |
+| `onActionClick` | `() => void` | Action click handler |
+| `onIconClose` | `() => void` | Close icon handler |
+| `onRequestClose` | `(callback?) => void` | Dismiss modal |
+| `id` | `string` | Tracking component ID |
+
+---
+
+## Compose — Modal Overlay
+
+```kotlin
+navigator.showModal(
+    content = { ModalContent() },
+    barrierDismissible = true,
+    onDismiss = { },
+)
+```
+
+Dismiss from inside:
+
+```kotlin
+navigator.pop()
+```
+
+## Compose — Present (Full-screen Modal)
+
+```kotlin
+navigator.present(content = { FullScreenModal() })
+```
+
+Use `present` for full-screen modals, `showModal` for overlay dialogs.