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

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

@@ -0,0 +1,152 @@
+# Stack Screen Configuration
+
+## React Native — Screen Component
+
+The `Screen` component from `@momo-kits/foundation` is the outermost container for every screen. It manages the header, scroll, keyboard avoidance, safe areas, and grid layout.
+
+### Screen Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `navigation` | `Navigation` | — | Navigation object (injected by NavigationContainer) |
+| `scrollable` | `boolean` | — | Enable scrollable content |
+| `headerType` | `HeaderType` | `'default'` | `'default'` \| `'extended'` \| `'none'` |
+| `animatedHeader` | `AnimatedHeader` | — | Object: `{ headerTintColor?, component?, headerTitle? }` — collapses on scroll |
+| `headerComponent` | `ReactNode` | — | Custom header component |
+| `footerComponent` | `ReactNode` | — | Sticky footer component |
+| `backgroundColor` | `string` | — | Screen background color |
+| `enableKeyboardAvoidingView` | `boolean` | — | Wrap content in KeyboardAvoidingView |
+| `keyboardVerticalOffset` | `number` | auto | Override keyboard avoiding offset |
+| `floatingButtonProps` | `FloatingButtonProps` | — | `{ icon, label, onPress, container? }` |
+| `scrollViewProps` | `ScrollViewProps` | — | Pass-through props for underlying ScrollView |
+| `layoutOffset` | `-8 \| -24 \| -56` | `-56` | Card offset overlap with header banner |
+| `headerRightWidth` | `0 \| 73 \| 110 \| number` | `73` | Width of the right header area |
+| `useGridLayout` | `boolean` | `true` | Apply auto grid spacing to children |
+| `inputSearchProps` | `SearchHeaderProps` | — | Animated search header config |
+| `inputSearchRef` | `Ref<InputRef>` | — | Ref for the search input |
+| `animatedValue` | `Animated.Value` | auto | Inject a custom animated value |
+| `useShadowHeader` | `boolean` | `true` | Header shadow |
+| `headerBackground` | `string` | — | Custom header background image |
+| `trackingParams` | `ScreenTrackingParams` | — | `{ value1?, value2? }` for auto tracking |
+
+### ScreenRef (imperative methods)
+
+```tsx
+import { Screen, ScreenRef } from '@momo-kits/foundation';
+
+const screenRef = useRef<ScreenRef>(null);
+
+<Screen ref={screenRef} navigation={navigation} scrollable headerType="default">
+  {/* content */}
+</Screen>
+
+// Dynamically update header options
+screenRef.current?.setOptions({
+  headerTitle: 'New Title',
+  hiddenBack: false,
+  headerRight: { useShortcut: true },
+});
+
+// Show/update search header
+screenRef.current?.setSearchHeader({
+  placeholder: 'Search...',
+  onChangeText: setQuery,
+});
+```
+
+### HeaderType
+
+| Value | Description |
+|-------|-------------|
+| `'default'` | Standard header with title + back button |
+| `'extended'` | Taller header, supports search and collapse animation |
+| `'none'` | No header rendered |
+
+### AnimatedHeader
+
+```tsx
+animatedHeader={{
+  headerTintColor: '#FFFFFF',
+  headerTitle: 'Animated Title',          // string | HeaderTitleProps
+  component: (props) => <CustomBanner {...props} />,
+}}
+```
+
+### FloatingButtonProps
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | `string \| ReactNode` | FAB icon (required) |
+| `label` | `string` | FAB label (required) |
+| `onPress` | `() => void` | Click handler (required) |
+| `container` | `ReactNode` | Optional custom container |
+
+---
+
+## Compose — Screen-level Configuration
+
+Use `LazyColumn` + `rememberLazyListState()` as the preferred scrollable — triggers header collapse via `ScrollData(scrollState = lazyListState)`.
+
+```kotlin
+import vn.momo.kits.navigation.LocalNavigation
+import vn.momo.kits.navigation.LocalNavigator
+import vn.momo.kits.navigation.ScrollData
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.rememberLazyListState
+
+@Composable
+fun MyScreen() {
+    val navigation = LocalNavigation.current
+    val navigator = LocalNavigator.current
+    val lazyListState = rememberLazyListState()
+
+    LaunchedEffect(Unit) {
+        navigation.setOptions(
+            headerTitle = HeaderTitle.Default("Screen Title"),
+            headerType = HeaderType.Default(),
+            headerRight = HeaderRight.Toolkit(),
+            hiddenBack = false,
+            scrollData = ScrollData(scrollState = lazyListState),
+            footerComponent = { FooterContent() },
+            floatingButtonProps = FloatingButtonProps(icon = "ic_plus", label = "Add", onClick = { }),
+        )
+    }
+
+    LazyColumn(state = lazyListState) {
+        // content
+    }
+}
+```
+
+### setOptions params
+
+```kotlin
+navigation.setOptions(
+    headerTitle: HeaderTitle,
+    headerType: HeaderType,
+    headerRight: HeaderRight,
+    hiddenBack: Boolean,
+    scrollData: ScrollData,
+    backgroundColor: Color?,
+    tintColor: Color?,
+    footerComponent: @Composable () -> Unit,
+    floatingButtonProps: FloatingButtonProps?,
+    onBackHandler: (() -> Unit)?,
+)
+```
+
+### HeaderType Options
+
+- `HeaderType.Default()` — standard header with title + back button
+- `HeaderType.Extended()` — larger header (supports `inputSearchProps` for animated search)
+- `HeaderType.Animated()` — collapses on scroll
+- `HeaderType.None` — no header
+
+### ScrollData
+
+```kotlin
+ScrollData(scrollable = true)
+ScrollData(scrollState = lazyListState)   // triggers header collapse
+```
+
+Use `LazyColumn` + `rememberLazyListState()` as preferred scrollable.

package/.claude/skills/design-system-kits/references/screen-layout-rule.md

@@ -0,0 +1,125 @@
+# Screen Layout Rules
+
+How `Screen` manages spacing, grid, and content layout in React Native and Compose.
+
+---
+
+## useGridLayout (React Native)
+
+`Screen` has a `useGridLayout` prop (default: `true`) that controls whether the screen automatically applies grid-based spacing to its body and children.
+
+| `useGridLayout` | Behavior |
+|-----------------|----------|
+| `true` (default) | Screen **automatically constrains** spacing — body padding, Section/Card margins, Item gutters are all managed by the grid system. You do **not** add manual padding/margin to Section, Card, or Item. |
+| `false` | Screen does **not** apply automatic spacing. Each element (Section, Card, Item, View) must define its own padding, margin, and gap explicitly. Use this when you need full manual control over layout. |
+
+### When to use `useGridLayout={true}` (default)
+
+- Standard screens with Section/Card/Item layout
+- Design spec screens — the grid system matches design tokens automatically
+- Most screens in the app — this is the recommended default
+
+### When to use `useGridLayout={false}`
+
+- Custom layouts that don't follow the Section/Card/Item pattern
+- Full-bleed content (edge-to-edge images, maps, video players)
+- Screens where you need pixel-perfect manual control over every spacing value
+- Embedding third-party components that manage their own layout
+
+```tsx
+// Default: grid layout ON — spacing is automatic
+<Screen navigation={navigation} scrollable>
+  <Section>
+    <Item>{/* auto-spaced by grid */}</Item>
+  </Section>
+  <Card>
+    <Item>{/* auto-spaced by grid */}</Item>
+  </Card>
+</Screen>
+
+// Grid layout OFF — you control all spacing
+<Screen navigation={navigation} scrollable useGridLayout={false}>
+  <View style={{ padding: Spacing.L }}>
+    {/* manual spacing everywhere */}
+  </View>
+</Screen>
+```
+
+---
+
+## Screen Layout Hierarchy (React Native)
+
+`Section` and `Card` are **siblings** (same level) under `Screen` — never nest one inside the other.
+
+```
+Screen
+├── Section > Item    (margin container — no background/elevation)
+├── Card > Item       (elevated container with background + optional shadow)
+```
+
+```tsx
+import { Screen, Section, Card, Item } from '@momo-kits/foundation';
+
+<Screen navigation={navigation} scrollable headerType="default">
+  <Section>
+    <Item widthSpan={12}>{/* full width */}</Item>
+    <Item widthSpan={6}>{/* half width */}</Item>
+  </Section>
+  <Card>
+    <Item widthSpan={12}>{/* elevated content */}</Item>
+  </Card>
+</Screen>
+```
+
+- **Screen**: Outermost container (header, scroll, keyboard, safe areas). See `navigation/stack.md` for full props.
+- **Section**: Margin container (12px margin, gutter 12px) — contains `Item` directly
+- **Card**: Elevated container (background + optional shadow, gutter 8px) — contains `Item` directly
+- **Item**: Grid item, `widthSpan` 1-12 (12 = full width)
+- **Section and Card are siblings** — both are direct children of Screen, never nested
+
+---
+
+## Section Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `expanded` | `boolean` | `false` | Display in expanded state |
+| `useMargin` | `boolean` | `true` | Apply 12px horizontal margin |
+| `backgroundImage` | `string` | — | Background image source |
+
+Grid context: `numberOfColumns` (12), `gutterSize` (12px), `sizePerSpan`, `getSizeSpan(span)`.
+
+---
+
+## Card Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `useShadow` | `boolean` | `false` | Show card shadow |
+| `backgroundImage` | `string` | — | Background image source |
+
+Grid context: `numberOfColumns` (12), `gutterSize` (8px), `sizePerSpan`, `getSizeSpan(span)`.
+
+---
+
+## Item Props
+
+```tsx
+<Item widthSpan={6} heightSpan={2} style={viewStyle} />
+```
+
+`widthSpan` and `heightSpan` accept values 1-12.
+
+---
+
+## Automatic Spacing Summary
+
+When `useGridLayout={true}` (default), the Screen applies:
+
+| Container | Horizontal margin | Gutter (gap between Items) | Background |
+|-----------|-------------------|---------------------------|------------|
+| **Section** | 12px (when `useMargin={true}`) | 12px | None (transparent) |
+| **Card** | 12px | 8px | Surface color + optional shadow |
+| **Item** | Auto (from grid) | Auto (from grid) | None |
+
+The body itself gets automatic vertical spacing between Section/Card blocks. You do **not** need to add `marginTop`/`marginBottom` between siblings — the grid handles it.

package/.claude/skills/design-system-kits/references/tokens/colors.md

@@ -0,0 +1,183 @@
+# Colors Reference
+
+Both platforms share identical color token names and values.
+
+## Import
+
+| Platform | Import |
+|----------|--------|
+| React Native | `import { Colors } from '@momo-kits/foundation'` |
+| Compose | `import vn.momo.kits.const.Colors` |
+
+Usage is identical: `Colors.pink_03`, `Colors.black_17`, etc.
+
+---
+
+## Grayscale (black_01 – black_20)
+
+| Token | Hex | Notes |
+|-------|-----|-------|
+| `black_01` | #FFFFFF | White |
+| `black_02` | #F9F9F9 | |
+| `black_03` | #F0F0F0 | Border disable |
+| `black_04` | #E8E8E8 | Border default |
+| `black_05` | #E5E5E5 | |
+| `black_06` | #D8D8D8 | |
+| `black_07` | #CCCCCC | |
+| `black_08` | #C6C6C6 | Text disable |
+| `black_09` | #B9B9B9 | |
+| `black_10` | #A0A0A0 | |
+| `black_11` | #878787 | |
+| `black_12` | #727272 | Text hint |
+| `black_13` | #646464 | |
+| `black_14` | #565656 | |
+| `black_15` | #484848 | Text secondary |
+| `black_16` | #404040 | |
+| `black_17` | #303233 | Text default |
+| `black_18` | #242424 | |
+| `black_19` | #18191A | |
+| `black_20` | #000000 | Black |
+
+---
+
+## Brand Color Families
+
+Each family has 11 tint levels: **01** (darkest) → **11** (lightest). Levels 07–11 are suitable for backgrounds and containers.
+
+### pink — Brand / primary
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `pink_01` | #BC2678 | `pink_07` | #F7ACD5 |
+| `pink_02` | #D42A87 | `pink_08` | #FBD5EA |
+| `pink_03` | #EB2F96 | `pink_09` | #FDEAF4 |
+| `pink_04` | #ED43A0 | `pink_10` | #FEF4FA |
+| `pink_05` | #EF59AB | `pink_11` | #FEF8FC |
+| `pink_06` | #F382C0 | | |
+
+Special: `pink_MoMo_Branding` = #A50064
+
+### violet — Accents, special features
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `violet_01` | #7822C0 | `violet_07` | #D5AAF9 |
+| `violet_02` | #8726D8 | `violet_08` | #EAD4FC |
+| `violet_03` | #962AF0 | `violet_09` | #F4E9FD |
+| `violet_04` | #A03FF1 | `violet_10` | #FAF4FE |
+| `violet_05` | #AB55F3 | `violet_11` | #FCF8FE |
+| `violet_06` | #C07FF6 | `violet_11_stroke` | #DFE1E5 |
+
+### indigo — Accents
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `indigo_01` | #3E3CCC | `indigo_07` | #B8B7FF |
+| `indigo_02` | #4644E6 | `indigo_08` | #DCDBFF |
+| `indigo_03` | #4E4BFF | `indigo_09` | #EDEDFF |
+| `indigo_04` | #5F5DFF | `indigo_10` | #F6F6FF |
+| `indigo_05` | #716FFF | `indigo_11` | #F9F9FF |
+| `indigo_06` | #9593FF | | |
+
+### blue — Interactive
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `blue_01` | #0062CC | `blue_07` | #99CAFF |
+| `blue_02` | #006EE6 | `blue_08` | #CCE4FF |
+| `blue_03` | #007AFF | `blue_09` | #E5F1FF |
+| `blue_04` | #1987FF | `blue_10` | #F2F8FF |
+| `blue_05` | #3395FF | `blue_11` | #F7FBFF |
+| `blue_06` | #66AFFF | | |
+
+### mint — Highlight
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `mint_01` | #0F9B9B | `mint_07` | #A1E7E7 |
+| `mint_02` | #11AFAF | `mint_08` | #D0F3F3 |
+| `mint_03` | #13C2C2 | `mint_09` | #E7F8F8 |
+| `mint_04` | #2AC8C8 | `mint_10` | #F3FCFC |
+| `mint_05` | #42CECE | `mint_11` | #F8FDFD |
+| `mint_06` | #71DADA | | |
+
+### green — Success
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `green_01` | #2A9F47 | `green_07` | #AEE9BD |
+| `green_02` | #2FB350 | `green_08` | #D6F4DE |
+| `green_03` | #34C759 | `green_09` | #EAF9EE |
+| `green_04` | #48CC69 | `green_10` | #F5FCF6 |
+| `green_05` | #5DD27A | `green_11` | #F9FDFA |
+| `green_06` | #85DD9B | | |
+
+### lime — Accents
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `lime_01` | #80AE0E | `lime_07` | #D9F0A0 |
+| `lime_02` | #90C30F | `lime_08` | #ECF7CF |
+| `lime_03` | #A0D911 | `lime_09` | #F5FBE7 |
+| `lime_04` | #A9DC28 | `lime_10` | #FAFDF3 |
+| `lime_05` | #B3E141 | `lime_11` | #FCFEF8 |
+| `lime_06` | #C6E870 | | |
+
+### yellow — Accents
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `yellow_01` | #CCA300 | `yellow_07` | #FFEB99 |
+| `yellow_02` | #E6B800 | `yellow_08` | #FFF5CC |
+| `yellow_03` | #FFCC00 | `yellow_09` | #FFF9E5 |
+| `yellow_04` | #FFD119 | `yellow_10` | #FFFCF2 |
+| `yellow_05` | #FFD633 | `yellow_11` | #FFFDF7 |
+| `yellow_06` | #FFE066 | | |
+
+### gold — Gold accents
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `gold_01` | #C87012 | `gold_07` | #FDD1A2 |
+| `gold_02` | #E17E14 | `gold_08` | #FEE8D0 |
+| `gold_03` | #FA8C16 | `gold_09` | #FEF3E7 |
+| `gold_04` | #FA972D | `gold_10` | #FFF9F3 |
+| `gold_05` | #FBA345 | `gold_11` | #FEFBF8 |
+| `gold_06` | #FCBA73 | | |
+
+### orange — Warning
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `orange_01` | #C84316 | `orange_07` | #FDBBA4 |
+| `orange_02` | #E14C19 | `orange_08` | #FEDDD2 |
+| `orange_03` | #FA541C | `orange_09` | #FEEDE8 |
+| `orange_04` | #FA6532 | `orange_10` | #FFF6F3 |
+| `orange_05` | #FB7649 | `orange_11` | #FEFAF8 |
+| `orange_06` | #FC9877 | | |
+
+### red — Error / danger
+
+| Token | Hex | Token | Hex |
+|-------|-----|-------|-----|
+| `red_01` | #C41B24 | `red_07` | #FBA7AB |
+| `red_02` | #DD1F29 | `red_08` | #FDD3D5 |
+| `red_03` | #F5222D | `red_09` | #FEE8EA |
+| `red_04` | #F63842 | `red_10` | #FEF4F4 |
+| `red_05` | #F74E57 | `red_11` | #FEF8F8 |
+| `red_06` | #F97A81 | | |
+
+### Quick Usage
+
+- Brand: `Colors.pink_03`
+- Interactive links/buttons: `Colors.blue_03`
+- Error/danger: `Colors.red_03`
+- Success: `Colors.green_03`
+- Warning: `Colors.orange_03`
+- Highlight: `Colors.mint_03`
+
+---
+
+## Rule
+
+**Never hardcode hex values.** Always use `Colors.*` tokens for consistency across themes and platforms.

package/.claude/skills/design-system-kits/references/tokens/spacing-radius.md

@@ -0,0 +1,45 @@
+# Spacing & Radius Reference
+
+## Spacing
+
+| Token | Value | RN Type | Compose Type |
+|-------|-------|---------|-------------|
+| `Spacing.XXS` | 2 | number | Dp |
+| `Spacing.XS` | 4 | number | Dp |
+| `Spacing.S` | 8 | number | Dp |
+| `Spacing.M` | 12 | number | Dp |
+| `Spacing.L` | 16 | number | Dp |
+| `Spacing.XL` | 24 | number | Dp |
+| `Spacing.XXL` | 32 | number | Dp |
+| `Spacing.Size3XL` | 48 | number | Dp |
+| `Spacing.Size4XL` | 56 | number | Dp |
+| `Spacing.Size5XL` | 64 | number | Dp |
+
+### Import
+
+| Platform | Import |
+|----------|--------|
+| React Native | `import { Spacing } from '@momo-kits/foundation'` |
+| Compose | `import vn.momo.kits.const.Spacing` |
+
+> **Note:** Compose `Spacing.L`, `Spacing.M`, `Spacing.S` are already `Dp` values — do NOT call `.dp` on them.
+
+---
+
+## Radius
+
+| Token | Value | Use for |
+|-------|-------|---------|
+| `Radius.XXS` | 2 | Subtle rounding |
+| `Radius.XS` | 4 | Small elements |
+| `Radius.S` | 8 | Cards, inputs |
+| `Radius.M` | 12 | Medium containers |
+| `Radius.L` | 16 | Modals, sheets |
+| `Radius.XL` | 24 | Pills, chips |
+
+### Import
+
+| Platform | Import |
+|----------|--------|
+| React Native | `import { Radius } from '@momo-kits/foundation'` |
+| Compose | `import vn.momo.kits.const.Radius` |

package/.claude/skills/design-system-kits/references/tokens/theme.md

@@ -0,0 +1,97 @@
+# Theme Reference
+
+The theme system provides semantic color mappings for light/dark mode support.
+
+## Accessing Theme
+
+| Platform | Access |
+|----------|--------|
+| React Native | `const { theme } = useContext(ApplicationContext)` |
+| Compose | `val theme = AppTheme.current` |
+
+Both expose an identical structure:
+
+```
+theme.colors.primary           → Color (pink_03 light / pink_04 dark)
+theme.colors.secondary         → Color
+theme.colors.gradient          → Color
+theme.colors.background.default / .surface / .tonal / .pressed / .selected / .disable
+theme.colors.text.default / .secondary / .hint / .disable
+theme.colors.border.default / .disable
+theme.colors.success.primary / .secondary / .container
+theme.colors.warning.primary / .secondary / .container
+theme.colors.error.primary / .secondary / .container
+theme.colors.highlight.primary / .secondary / .container
+theme.colors.interactive.primary / .secondary / .container
+```
+
+---
+
+## Light Theme (defaultTheme)
+
+| Path | Value |
+|------|-------|
+| `primary` | `pink_03` (#EB2F96) |
+| `secondary` | `pink_07` |
+| `gradient` | #FDCADE |
+| `background.default` | #F2F2F6 |
+| `background.surface` | `black_01` (white) |
+| `background.tonal` | `pink_09` |
+| `background.pressed` | #DFDFE6 |
+| `background.selected` | `pink_10` |
+| `background.disable` | #EBEBF2 |
+| `text.default` | `black_17` (#303233) |
+| `text.secondary` | `black_15` (#484848) |
+| `text.hint` | `black_12` (#727272) |
+| `text.disable` | `black_08` (#C6C6C6) |
+| `border.default` | `black_04` (#E8E8E8) |
+| `border.disable` | `black_02` (#F9F9F9) |
+| `success` | `green_03` / `green_07` / `green_08` |
+| `warning` | `orange_03` / `orange_07` / `orange_08` |
+| `error` | `red_03` / `red_07` / `red_08` |
+| `highlight` | `mint_03` / `mint_07` / `mint_08` |
+| `interactive` | `blue_03` / `blue_07` / `blue_08` |
+
+---
+
+## Dark Theme (darkTheme)
+
+| Path | Value |
+|------|-------|
+| `primary` | `pink_04` |
+| `secondary` | `pink_08` |
+| `gradient` | #FDCADE |
+| `background.default` | #121212 |
+| `background.surface` | #1E1E1E |
+| `background.tonal` | `pink_10` |
+| `background.pressed` | #1A1A1A |
+| `background.selected` | `pink_11` |
+| `background.disable` | #303030 |
+| `text.default` | White |
+| `text.secondary` | #B0B0B0 |
+| `text.hint` | #727272 |
+| `text.disable` | #505050 |
+| `border.default` | #2A2A2A |
+| `border.disable` | #242424 |
+
+Success, warning, error, highlight, and interactive colors are the same in both themes.
+
+---
+
+## Compose Theme Data Structures
+
+```kotlin
+data class Theme(dark: Boolean, colors: ColorScheme, font: String, assets: ThemeAssets)
+data class ColorScheme(primary, secondary, gradient: Color, background: Background, text: TextColors, border: BorderColors, success/warning/error/highlight/interactive: ColorSet)
+data class Background(default, surface, tonal, pressed, selected, disable: Color)
+data class TextColors(default, secondary, hint, disable: Color)
+data class BorderColors(default, disable: Color)
+data class ColorSet(primary, secondary, container: Color)
+data class ThemeAssets(headerBackground: String?)
+```
+
+---
+
+## Best Practice
+
+Always prefer `theme.colors.*` over direct `Colors.*` tokens so the UI automatically adapts to light/dark mode.