feat: tambah sistem guide onboarding per fitur dengan GuideOverlay

- Buat komponen GuideOverlay dengan animasi fade+slide, arrow tooltip, dan dot indicator - Buat hook useGuide untuk menyimpan state guide per fitur via AsyncStorage - Sentralisasi semua step guide di lib/guideSteps.ts - Pasang guide pada 12 halaman: village-calendar, project detail, banner, group, position, member, announcement, discussion, division calendar/document/discussion, dan division task detail - Posisi card menggunakan cardTopRatio (rasio layar) untuk kompatibilitas berbagai ukuran device - Tambah styles guide dan village calendar di constants/Styles.ts
2026-05-11 16:34:46 +08:00
parent 84935e8188
commit 7341f378dd
16 changed files with 539 additions and 1 deletions
--- a/app/(application)/announcement/index.tsx
+++ b/app/(application)/announcement/index.tsx
@@ -1,9 +1,12 @@
+import GuideOverlay from "@/components/GuideOverlay";
 import BorderBottomItem from "@/components/borderBottomItem";
 import InputSearch from "@/components/inputSearch";
 import SkeletonContent from "@/components/skeletonContent";
 import Text from '@/components/Text';
 import Styles from "@/constants/Styles";
 import { apiGetAnnouncement } from "@/lib/api";
+import { GUIDE_ANNOUNCEMENT } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { MaterialIcons } from "@expo/vector-icons";
@@ -25,6 +28,7 @@ export default function Announcement() {
   const { colors } = useTheme();
   const [search, setSearch] = useState('')
   const update = useSelector((state: any) => state.announcementUpdate)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('announcement')
   const arrSkeleton = Array.from({ length: 5 }, (_, index) => index)

   // TanStack Query Infinite Query
@@ -78,6 +82,7 @@ export default function Announcement() {

   return (
      <View style={[Styles.p15, Styles.flex1, { backgroundColor: colors.background }]}>
+         <GuideOverlay visible={guideVisible} steps={GUIDE_ANNOUNCEMENT} onDismiss={dismissGuide} />
         <View>
            <InputSearch onChange={setSearch} />
         </View>
--- a/app/(application)/banner/index.tsx
+++ b/app/(application)/banner/index.tsx
@@ -1,5 +1,5 @@
-import styles from "@/components/AppHeader"
 import AppHeader from "@/components/AppHeader"
+import GuideOverlay from "@/components/GuideOverlay"
 import HeaderRightBannerList from "@/components/banner/headerBannerList"
 import BorderBottomItem from "@/components/borderBottomItem"
 import DrawerBottom from "@/components/drawerBottom"
@@ -12,6 +12,8 @@ import { ConstEnv } from "@/constants/ConstEnv"
 import Styles from "@/constants/Styles"
 import { apiDeleteBanner, apiGetBanner } from "@/lib/api"
 import { setEntities } from "@/lib/bannerSlice"
+import { GUIDE_BANNER } from "@/lib/guideSteps"
+import { useGuide } from "@/lib/useGuide"
 import { useAuthSession } from "@/providers/AuthProvider"
 import { useTheme } from "@/providers/ThemeProvider"
 import { Ionicons, MaterialCommunityIcons } from "@expo/vector-icons"
@@ -44,6 +46,7 @@ export default function BannerList() {
   const dispatch = useDispatch()
   const [refreshing, setRefreshing] = useState(false)
   const [loadingOpen, setLoadingOpen] = useState(false)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('banner')
   const [viewImg, setViewImg] = useState(false)
   const [showDeleteModal, setShowDeleteModal] = useState(false)
   const queryClient = useQueryClient()
@@ -147,6 +150,7 @@ export default function BannerList() {
               )
            }}
         />
+         <GuideOverlay visible={guideVisible} steps={GUIDE_BANNER} onDismiss={dismissGuide} />
         <ModalLoading isVisible={loadingOpen} setVisible={setLoadingOpen} />
         <ScrollView
            refreshControl={
--- a/app/(application)/discussion/index.tsx
+++ b/app/(application)/discussion/index.tsx
@@ -1,3 +1,4 @@
+import GuideOverlay from "@/components/GuideOverlay";
 import ButtonTab from "@/components/buttonTab";
 import InputSearch from "@/components/inputSearch";
 import LabelStatus from "@/components/labelStatus";
@@ -6,6 +7,8 @@ import Text from "@/components/Text";
 import WrapTab from "@/components/wrapTab";
 import Styles from "@/constants/Styles";
 import { apiGetDiscussionGeneral } from "@/lib/api";
+import { GUIDE_DISCUSSION } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { AntDesign, Feather } from "@expo/vector-icons";
@@ -34,6 +37,7 @@ export default function Discussion() {
   const queryClient = useQueryClient()
   const [status, setStatus] = useState<'true' | 'false'>(active == 'false' ? 'false' : 'true')
   const [refreshing, setRefreshing] = useState(false)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('discussion')

   const {
      data,
@@ -85,6 +89,7 @@ export default function Discussion() {

   return (
      <View style={[Styles.flex1, { backgroundColor: colors.background }]}>
+         <GuideOverlay visible={guideVisible} steps={GUIDE_DISCUSSION} onDismiss={dismissGuide} />
         {/* Header controls */}
         <View style={[Styles.ph15, { paddingTop: 12 }]}>
            {entityUser.role != "user" && entityUser.role != "coadmin" && (
--- a/app/(application)/division/[id]/(fitur-division)/calendar/index.tsx
+++ b/app/(application)/division/[id]/(fitur-division)/calendar/index.tsx
@@ -1,4 +1,5 @@
 import AppHeader from "@/components/AppHeader";
+import GuideOverlay from "@/components/GuideOverlay";
 import HeaderRightCalendarList from "@/components/calendar/headerCalendarList";
 import ItemDateCalendar from "@/components/calendar/itemDateCalendar";
 import EventItem from "@/components/eventItem";
@@ -6,6 +7,8 @@ import Skeleton from "@/components/skeleton";
 import Text from "@/components/Text";
 import Styles from "@/constants/Styles";
 import { apiGetCalendarByDateDivision, apiGetIndicatorCalendar } from "@/lib/api";
+import { GUIDE_DIVISION_CALENDAR } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { Feather } from "@expo/vector-icons";
@@ -46,6 +49,7 @@ export default function CalendarDivision() {
   const [loading, setLoading] = useState(true)
   const [loadingBtn, setLoadingBtn] = useState(false)
   const [refreshing, setRefreshing] = useState(false)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('division-calendar')


   async function handleLoad(loading: boolean) {
@@ -150,6 +154,7 @@ export default function CalendarDivision() {
               )
            }}
         />
+         <GuideOverlay visible={guideVisible} steps={GUIDE_DIVISION_CALENDAR} onDismiss={dismissGuide} />
         <ScrollView
            refreshControl={
               <RefreshControl
--- a/app/(application)/division/[id]/(fitur-division)/discussion/index.tsx
+++ b/app/(application)/division/[id]/(fitur-division)/discussion/index.tsx
@@ -1,3 +1,4 @@
+import GuideOverlay from "@/components/GuideOverlay";
 import ButtonTab from "@/components/buttonTab";
 import ImageUser from "@/components/imageNew";
 import InputSearch from "@/components/inputSearch";
@@ -7,6 +8,8 @@ import WrapTab from "@/components/wrapTab";
 import { ConstEnv } from "@/constants/ConstEnv";
 import Styles from "@/constants/Styles";
 import { apiGetDiscussion, apiGetDivisionOneFeature } from "@/lib/api";
+import { GUIDE_DIVISION_DISCUSSION } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { AntDesign, Feather } from "@expo/vector-icons";
@@ -43,6 +46,7 @@ export default function DiscussionDivision() {
   const [isMemberDivision, setIsMemberDivision] = useState(false)
   const [isAdminDivision, setIsAdminDivision] = useState(false)
   const entityUser = useSelector((state: any) => state.user)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('division-discussion')

   async function handleCheckMember() {
      try {
@@ -96,6 +100,7 @@ export default function DiscussionDivision() {

   return (
      <View style={[Styles.flex1, { backgroundColor: colors.background }]}>
+         <GuideOverlay visible={guideVisible} steps={GUIDE_DIVISION_DISCUSSION} onDismiss={dismissGuide} />
         {((entityUser.role != "user" && entityUser.role != "coadmin") || isAdminDivision) && (
            <View style={[Styles.ph15, { paddingTop: 12 }]}>
               <WrapTab>
--- a/app/(application)/division/[id]/(fitur-division)/document/index.tsx
+++ b/app/(application)/division/[id]/(fitur-division)/document/index.tsx
@@ -1,3 +1,4 @@
+import GuideOverlay from "@/components/GuideOverlay";
 import ModalConfirmation from "@/components/ModalConfirmation";
 import AppHeader from "@/components/AppHeader";
 import { ButtonHeader } from "@/components/buttonHeader";
@@ -22,6 +23,8 @@ import {
   apiShareDocument,
 } from "@/lib/api";
 import { setUpdateDokumen } from "@/lib/dokumenUpdate";
+import { GUIDE_DIVISION_DOCUMENT } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import {
@@ -90,6 +93,7 @@ export default function DocumentDivision() {
   const [isMemberDivision, setIsMemberDivision] = useState(false)
   const entityUser = useSelector((state: any) => state.user)
   const [showDeleteModal, setShowDeleteModal] = useState(false)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('division-document')
   const [bodyRename, setBodyRename] = useState({
      id: "",
      name: "",
@@ -415,6 +419,7 @@ export default function DocumentDivision() {
               )
            }}
         />
+         <GuideOverlay visible={guideVisible} steps={GUIDE_DIVISION_DOCUMENT} onDismiss={dismissGuide} />
         <ModalLoading isVisible={loadingOpen} setVisible={setLoadingOpen} />
         <ScrollView
            refreshControl={
--- a/app/(application)/division/[id]/(fitur-division)/task/[detail]/index.tsx
+++ b/app/(application)/division/[id]/(fitur-division)/task/[detail]/index.tsx
@@ -1,4 +1,5 @@
 import AppHeader from "@/components/AppHeader";
+import GuideOverlay from "@/components/GuideOverlay";
 import SectionCancel from "@/components/sectionCancel";
 import SectionProgress from "@/components/sectionProgress";
 import HeaderRightTaskDetail from "@/components/task/headerTaskDetail";
@@ -9,6 +10,8 @@ import SectionReportTask from "@/components/task/sectionReportTask";
 import SectionTanggalTugasTask from "@/components/task/sectionTanggalTugasTask";
 import Styles from "@/constants/Styles";
 import { apiGetDivisionOneFeature, apiGetTaskOne } from "@/lib/api";
+import { GUIDE_PROJECT_DETAIL } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { router, Stack, useLocalSearchParams } from "expo-router";
@@ -36,6 +39,7 @@ export default function DetailTaskDivision() {
   const update = useSelector((state: any) => state.taskUpdate)
   const [refreshing, setRefreshing] = useState(false)
   const [isMemberDivision, setIsMemberDivision] = useState(false);
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('division-task-detail')
   const [isAdminDivision, setIsAdminDivision] = useState(false);
   const entityUser = useSelector((state: any) => state.user);

@@ -139,6 +143,7 @@ export default function DetailTaskDivision() {
               )
            }}
         />
+         <GuideOverlay visible={guideVisible} steps={GUIDE_PROJECT_DETAIL} onDismiss={dismissGuide} />
         <ScrollView
            refreshControl={
               <RefreshControl
--- a/app/(application)/group/index.tsx
+++ b/app/(application)/group/index.tsx
@@ -1,3 +1,4 @@
+import GuideOverlay from "@/components/GuideOverlay";
 import ModalConfirmation from "@/components/ModalConfirmation";
 import BorderBottomItem from "@/components/borderBottomItem";
 import { ButtonForm } from "@/components/buttonForm";
@@ -12,6 +13,8 @@ import WrapTab from "@/components/wrapTab";
 import Styles from "@/constants/Styles";
 import { apiDeleteGroup, apiEditGroup, apiGetGroup } from "@/lib/api";
 import { setUpdateGroup } from "@/lib/groupSlice";
+import { GUIDE_GROUP } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { AntDesign, Feather, Ionicons, MaterialCommunityIcons } from "@expo/vector-icons";
@@ -41,6 +44,7 @@ export default function Index() {
   const [titleChoose, setTitleChoose] = useState('')
   const queryClient = useQueryClient()
   const [refreshing, setRefreshing] = useState(false)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('group')

   const dispatch = useDispatch()
   const update = useSelector((state: any) => state.groupUpdate)
@@ -136,6 +140,7 @@ export default function Index() {

   return (
      <View style={[Styles.p15, { flex: 1, backgroundColor: colors.background }]}>
+         <GuideOverlay visible={guideVisible} steps={GUIDE_GROUP} onDismiss={dismissGuide} />
         <View style={[Styles.mb10]}>
            <WrapTab>
               <ButtonTab
--- a/app/(application)/member/index.tsx
+++ b/app/(application)/member/index.tsx
@@ -1,3 +1,4 @@
+import GuideOverlay from "@/components/GuideOverlay";
 import BorderBottomItem from "@/components/borderBottomItem";
 import ButtonTab from "@/components/buttonTab";
 import ImageUser from "@/components/imageNew";
@@ -9,6 +10,8 @@ import WrapTab from "@/components/wrapTab";
 import { ConstEnv } from "@/constants/ConstEnv";
 import Styles from "@/constants/Styles";
 import { apiGetUser } from "@/lib/api";
+import { GUIDE_MEMBER } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { AntDesign, Feather } from "@expo/vector-icons";
@@ -42,6 +45,7 @@ export default function Index() {
   const queryClient = useQueryClient()
   const [status, setStatus] = useState<'true' | 'false'>(active == 'false' ? 'false' : 'true')
   const [refreshing, setRefreshing] = useState(false)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('member')

   // TanStack Query for Members with Infinite Scroll
   const {
@@ -117,6 +121,7 @@ export default function Index() {

   return (
      <View style={[Styles.p15, { flex: 1, backgroundColor: colors.background }]}>
+         <GuideOverlay visible={guideVisible} steps={GUIDE_MEMBER} onDismiss={dismissGuide} />
         <View>
            <WrapTab>
               <ButtonTab
--- a/app/(application)/position/index.tsx
+++ b/app/(application)/position/index.tsx
@@ -1,3 +1,4 @@
+import GuideOverlay from "@/components/GuideOverlay";
 import BorderBottomItem from "@/components/borderBottomItem";
 import { ButtonForm } from "@/components/buttonForm";
 import ButtonTab from "@/components/buttonTab";
@@ -13,6 +14,8 @@ import WrapTab from "@/components/wrapTab";
 import Styles from "@/constants/Styles";
 import { apiDeletePosition, apiEditPosition, apiGetPosition } from "@/lib/api";
 import { setUpdatePosition } from "@/lib/positionSlice";
+import { GUIDE_POSITION } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { AntDesign, Feather, MaterialCommunityIcons } from "@expo/vector-icons";
@@ -48,6 +51,7 @@ export default function Index() {
   const queryClient = useQueryClient()
   const [refreshing, setRefreshing] = useState(false)
   const [showDeleteModal, setShowDeleteModal] = useState(false)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('position')

   const dispatch = useDispatch()
   const update = useSelector((state: any) => state.positionUpdate)
@@ -160,6 +164,7 @@ export default function Index() {

   return (
      <View style={[Styles.p15, Styles.flex1, { backgroundColor: colors.background }]}>
+         <GuideOverlay visible={guideVisible} steps={GUIDE_POSITION} onDismiss={dismissGuide} />
         <View>
            <WrapTab>
               <ButtonTab
--- a/app/(application)/project/[id]/index.tsx
+++ b/app/(application)/project/[id]/index.tsx
@@ -1,4 +1,5 @@
 import AppHeader from "@/components/AppHeader";
+import GuideOverlay from "@/components/GuideOverlay";
 import HeaderRightProjectDetail from "@/components/project/headerProjectDetail";
 import SectionFile from "@/components/project/sectionFile";
 import SectionLink from "@/components/project/sectionLink";
@@ -9,6 +10,8 @@ import SectionCancel from "@/components/sectionCancel";
 import SectionProgress from "@/components/sectionProgress";
 import Styles from "@/constants/Styles";
 import { apiGetProjectOne } from "@/lib/api";
+import { GUIDE_PROJECT_DETAIL } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { router, Stack, useLocalSearchParams } from "expo-router";
@@ -43,6 +46,7 @@ export default function DetailProject() {
   const [isMember, setIsMember] = useState(false)
   const entityUser = useSelector((state: any) => state.user)
   const [refreshing, setRefreshing] = useState(false)
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('project-detail')

   async function handleLoad(cat: 'data' | 'progress') {
      try {
@@ -129,6 +133,7 @@ export default function DetailProject() {
               )
            }}
         />
+         <GuideOverlay visible={guideVisible} steps={GUIDE_PROJECT_DETAIL} onDismiss={dismissGuide} />
         <ScrollView
            style={[Styles.h100, { backgroundColor: colors.background }]}
            refreshControl={
--- a/app/(application)/village-calendar/index.tsx
+++ b/app/(application)/village-calendar/index.tsx
@@ -1,9 +1,12 @@
 import AppHeader from "@/components/AppHeader";
 import ItemDateCalendar from "@/components/calendar/itemDateCalendar";
+import GuideOverlay from "@/components/GuideOverlay";
 import Skeleton from "@/components/skeleton";
 import Text from "@/components/Text";
 import Styles from "@/constants/Styles";
 import { apiGetVillageCalendarByDate, apiGetVillageCalendarIndicator } from "@/lib/api";
+import { GUIDE_VILLAGE_CALENDAR } from "@/lib/guideSteps";
+import { useGuide } from "@/lib/useGuide";
 import { useAuthSession } from "@/providers/AuthProvider";
 import { useTheme } from "@/providers/ThemeProvider";
 import { Feather } from "@expo/vector-icons";
@@ -84,9 +87,11 @@ function VillageEventItem({ item, onPress }: { item: EventItem; onPress: () => v
   );
 }

+
 export default function VillageCalendar() {
   const { colors, activeTheme } = useTheme();
   const { token, decryptToken } = useAuthSession();
+   const { visible: guideVisible, dismiss: dismissGuide } = useGuide('village-calendar');
   const [selected, setSelected] = useState<any>(new Date());
   const [data, setData] = useState<EventItem[]>([]);
   const [dataIndicator, setDataIndicator] = useState<{ calendar: string[], task: string[] }>({ calendar: [], task: [] });
@@ -194,6 +199,11 @@ export default function VillageCalendar() {
               ),
            }}
         />
+         <GuideOverlay
+            visible={guideVisible}
+            steps={GUIDE_VILLAGE_CALENDAR}
+            onDismiss={dismissGuide}
+         />
         <ScrollView
            refreshControl={
               <RefreshControl
--- a/components/GuideOverlay.tsx
+++ b/components/GuideOverlay.tsx
@@ -0,0 +1,159 @@
+import Text from '@/components/Text';
+import Styles from '@/constants/Styles';
+import { useTheme } from '@/providers/ThemeProvider';
+import { Feather } from '@expo/vector-icons';
+import React, { useEffect, useRef, useState } from 'react';
+import {
+   Animated,
+   Dimensions,
+   Modal,
+   TouchableOpacity,
+   View,
+} from 'react-native';
+
+export type GuideStep = {
+   title: string;
+   description: string;
+   // posisi card: pixel absolut atau rasio layar (0.0-1.0), rasio lebih aman untuk layout dinamis
+   cardTop?: number;
+   cardTopRatio?: number;
+   // arrow menunjuk ke atas (elemen ada di atas card) atau ke bawah (elemen ada di bawah card)
+   arrowDirection?: 'up' | 'down' | 'none';
+   // offset horizontal arrow dari kiri card (0.0-1.0), default 0.5 = tengah
+   arrowOffset?: number;
+};
+
+type Props = {
+   visible: boolean;
+   steps: GuideStep[];
+   onDismiss: () => void;
+};
+
+const { height: SCREEN_H } = Dimensions.get('window');
+const CARD_MARGIN = 24;
+
+export default function GuideOverlay({ visible, steps, onDismiss }: Props) {
+   const { colors } = useTheme();
+   const [currentStep, setCurrentStep] = useState(0);
+   const fadeAnim = useRef(new Animated.Value(0)).current;
+   const slideAnim = useRef(new Animated.Value(20)).current;
+
+   const step = steps[currentStep];
+   const isLast = currentStep === steps.length - 1;
+
+   const arrowDirection = step?.arrowDirection ?? 'none';
+   const arrowOffset = step?.arrowOffset ?? 0.5;
+   const cardTop = step?.cardTopRatio != null
+      ? SCREEN_H * step.cardTopRatio
+      : (step?.cardTop ?? SCREEN_H * 0.35);
+
+   const cardPositionStyle = { top: cardTop };
+
+   useEffect(() => {
+      if (visible) {
+         setCurrentStep(0);
+         Animated.parallel([
+            Animated.timing(fadeAnim, { toValue: 1, duration: 300, useNativeDriver: true }),
+            Animated.timing(slideAnim, { toValue: 0, duration: 300, useNativeDriver: true }),
+         ]).start();
+      } else {
+         fadeAnim.setValue(0);
+         slideAnim.setValue(20);
+      }
+   }, [visible]);
+
+   function animateStep(next: number) {
+      Animated.sequence([
+         Animated.timing(slideAnim, { toValue: 12, duration: 120, useNativeDriver: true }),
+         Animated.timing(slideAnim, { toValue: 0, duration: 180, useNativeDriver: true }),
+      ]).start();
+      setCurrentStep(next);
+   }
+
+   if (!visible) return null;
+
+   return (
+      <Modal transparent visible={visible} animationType="none" onRequestClose={onDismiss}>
+         <Animated.View style={[Styles.guideOverlay, { opacity: fadeAnim }]}>
+            <Animated.View
+               style={[
+                  Styles.guideCard,
+                  { backgroundColor: colors.modalBackground, transform: [{ translateY: slideAnim }] },
+                  cardPositionStyle,
+               ]}
+            >
+               {/* Arrow atas — menunjuk ke elemen di atas card */}
+               {arrowDirection === 'up' && (
+                  <View style={[Styles.guideArrowUp, {
+                     left: `${arrowOffset * 100}%` as any,
+                     borderBottomColor: colors.modalBackground,
+                  }]} />
+               )}
+
+               {/* Header */}
+               <View style={[Styles.rowItemsCenter, Styles.rowSpaceBetween, Styles.mb10]}>
+                  <View style={[Styles.guideBadge, { backgroundColor: colors.icon + '20' }]}>
+                     <Text style={[Styles.textSmallSemiBold, { color: colors.icon }]}>
+                        {currentStep + 1} / {steps.length}
+                     </Text>
+                  </View>
+                  <TouchableOpacity onPress={onDismiss} hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}>
+                     <Feather name="x" size={18} color={colors.dimmed} />
+                  </TouchableOpacity>
+               </View>
+
+               {/* Content */}
+               <Text style={[Styles.textDefaultSemiBold, Styles.mb05, { color: colors.text }]}>
+                  {step.title}
+               </Text>
+               <Text style={[Styles.textMediumNormal, { color: colors.text, lineHeight: 20 }]}>
+                  {step.description}
+               </Text>
+
+               {/* Dot indicator */}
+               <View style={[Styles.rowItemsCenter, Styles.guideDotRow]}>
+                  {steps.map((_, i) => (
+                     <View
+                        key={i}
+                        style={[Styles.guideDot, {
+                           backgroundColor: i === currentStep ? colors.icon : colors.icon + '30',
+                        }]}
+                     />
+                  ))}
+               </View>
+
+               {/* Footer */}
+               <View style={[Styles.rowItemsCenter, Styles.rowSpaceBetween, Styles.mt10]}>
+                  {currentStep > 0 ? (
+                     <TouchableOpacity onPress={() => animateStep(currentStep - 1)} style={Styles.guideButtonSecondary}>
+                        <Text style={[Styles.textMediumNormal, { color: colors.dimmed }]}>Kembali</Text>
+                     </TouchableOpacity>
+                  ) : (
+                     <TouchableOpacity onPress={onDismiss}>
+                        <Text style={[Styles.textMediumNormal, { color: colors.dimmed }]}>Lewati</Text>
+                     </TouchableOpacity>
+                  )}
+
+                  <TouchableOpacity
+                     onPress={() => isLast ? onDismiss() : animateStep(currentStep + 1)}
+                     style={[Styles.guideButtonPrimary, { backgroundColor: colors.icon }]}
+                  >
+                     <Text style={[Styles.textMediumSemiBold, { color: '#ffffff' }]}>
+                        {isLast ? 'Selesai' : 'Lanjut'}
+                     </Text>
+                     {!isLast && <Feather name="arrow-right" size={14} color="#ffffff" style={{ marginLeft: 4 }} />}
+                  </TouchableOpacity>
+               </View>
+
+               {/* Arrow bawah — menunjuk ke elemen di bawah card */}
+               {arrowDirection === 'down' && (
+                  <View style={[Styles.guideArrowDown, {
+                     left: `${arrowOffset * 100}%` as any,
+                     borderTopColor: colors.modalBackground,
+                  }]} />
+               )}
+            </Animated.View>
+         </Animated.View>
+      </Modal>
+   );
+}
--- a/constants/Styles.ts
+++ b/constants/Styles.ts
@@ -1170,6 +1170,76 @@ const Styles = StyleSheet.create({
      fontStyle: 'italic',
   },

+   // guide overlay
+   guideOverlay: {
+      flex: 1,
+      backgroundColor: 'rgba(0,0,0,0.6)',
+      justifyContent: 'center',
+      alignItems: 'center',
+   },
+   guideCard: {
+      position: 'absolute',
+      left: 24,
+      right: 24,
+      borderRadius: 16,
+      padding: 20,
+      shadowColor: '#000',
+      shadowOffset: { width: 0, height: 4 },
+      shadowOpacity: 0.2,
+      shadowRadius: 12,
+      elevation: 8,
+   },
+   guideBadge: {
+      paddingHorizontal: 8,
+      paddingVertical: 3,
+      borderRadius: 20,
+   },
+   guideDotRow: {
+      marginTop: 16,
+      gap: 6,
+      justifyContent: 'center',
+   },
+   guideDot: {
+      width: 6,
+      height: 6,
+      borderRadius: 3,
+   },
+   guideButtonPrimary: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      paddingHorizontal: 16,
+      paddingVertical: 8,
+      borderRadius: 20,
+   },
+   guideButtonSecondary: {
+      paddingHorizontal: 4,
+      paddingVertical: 8,
+   },
+   guideArrowUp: {
+      position: 'absolute',
+      top: -10,
+      marginLeft: -8,
+      width: 0,
+      height: 0,
+      borderLeftWidth: 8,
+      borderRightWidth: 8,
+      borderBottomWidth: 10,
+      borderLeftColor: 'transparent',
+      borderRightColor: 'transparent',
+   },
+   guideArrowDown: {
+      position: 'absolute',
+      bottom: -10,
+      marginLeft: -8,
+      width: 0,
+      height: 0,
+      borderLeftWidth: 8,
+      borderRightWidth: 8,
+      borderTopWidth: 10,
+      borderLeftColor: 'transparent',
+      borderRightColor: 'transparent',
+   },
+
   // village calendar & itemDateCalendar
   calendarDotRow: {
      flexDirection: 'row',
--- a/lib/guideSteps.ts
+++ b/lib/guideSteps.ts
@@ -0,0 +1,217 @@
+import { GuideStep } from "@/components/GuideOverlay";
+
+export const GUIDE_VILLAGE_CALENDAR: GuideStep[] = [
+   {
+      title: 'Kalender Umum',
+      description: 'Halaman ini menampilkan semua acara divisi dan kegiatan yang ada di desa kamu dalam satu kalender.',
+      cardTopRatio: 0.58,
+      arrowDirection: 'up',
+      arrowOffset: 0.5,
+   },
+   {
+      title: 'Pilih Tanggal',
+      description: 'Ketuk tanggal pada kalender untuk melihat acara dan kegiatan yang berlangsung pada hari tersebut.',
+      cardTopRatio: 0.58,
+      arrowDirection: 'up',
+      arrowOffset: 0.5,
+   },
+   {
+      title: 'Indikator Dot',
+      description: 'Titik ungu menandakan ada acara divisi, titik biru-abu menandakan ada kegiatan pada tanggal tersebut.',
+      cardTopRatio: 0.63,
+      arrowDirection: 'up',
+      arrowOffset: 0.12,
+   },
+   {
+      title: 'Detail Event',
+      description: 'Ketuk salah satu acara atau kegiatan di bawah untuk melihat detail lengkapnya.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'down',
+      arrowOffset: 0.5,
+   },
+];
+
+export const GUIDE_DIVISION_DISCUSSION: GuideStep[] = [
+   {
+      title: 'Diskusi Divisi',
+      description: 'Halaman ini menampilkan semua topik diskusi dalam divisi. Setiap card menunjukkan pembuat, deskripsi singkat, jumlah komentar, dan status diskusi.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Buka Diskusi',
+      description: 'Ketuk salah satu diskusi untuk membaca detail dan ikut berkomentar.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+];
+
+export const GUIDE_DIVISION_DOCUMENT: GuideStep[] = [
+   {
+      title: 'Dokumen Divisi',
+      description: 'Halaman ini menampilkan semua file dan folder dokumen milik divisi kamu.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Buka File atau Folder',
+      description: 'Ketuk folder untuk masuk ke dalamnya, atau ketuk file untuk langsung membukanya.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Pilih & Kelola',
+      description: 'Centang file atau folder untuk memilihnya, lalu gunakan menu di bawah untuk menghapus, mengganti nama, atau membagikan ke divisi lain.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+];
+
+export const GUIDE_DIVISION_CALENDAR: GuideStep[] = [
+   {
+      title: 'Kalender Divisi',
+      description: 'Halaman ini menampilkan semua acara yang ada di divisi kamu dalam satu kalender.',
+      cardTopRatio: 0.50,
+      arrowDirection: 'none',
+      arrowOffset: 0.5,
+   },
+   {
+      title: 'Indikator Acara',
+      description: 'Garis di bawah tanggal menandakan ada acara pada hari tersebut. Ketuk tanggal untuk melihat daftarnya.',
+      cardTopRatio: 0.50,
+      arrowDirection: 'none',
+      arrowOffset: 0.55,
+   },
+   {
+      title: 'Detail Acara',
+      description: 'Ketuk salah satu acara di bawah kalender untuk melihat detail lengkapnya.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'down',
+      arrowOffset: 0.55,
+   },
+];
+
+export const GUIDE_DISCUSSION: GuideStep[] = [
+   {
+      title: 'Daftar Diskusi',
+      description: 'Halaman ini menampilkan semua topik diskusi. Setiap card menunjukkan judul, deskripsi singkat, jumlah komentar, dan status diskusi.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Buka Diskusi',
+      description: 'Ketuk salah satu diskusi untuk membaca detail dan ikut berkomentar.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+];
+
+export const GUIDE_ANNOUNCEMENT: GuideStep[] = [
+   {
+      title: 'Daftar Pengumuman',
+      description: 'Halaman ini menampilkan semua pengumuman yang ada di desamu.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Detail Pengumuman',
+      description: 'Ketuk salah satu pengumuman untuk membaca isi lengkapnya.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+];
+
+export const GUIDE_MEMBER: GuideStep[] = [
+   {
+      title: 'Daftar Anggota',
+      description: 'Halaman ini menampilkan semua anggota desa. Gunakan tab untuk memfilter anggota aktif atau tidak aktif.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Detail Anggota',
+      description: 'Ketuk salah satu anggota untuk melihat informasi lengkapnya seperti NIK, jabatan, lembaga, dan kontak.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+];
+
+export const GUIDE_POSITION: GuideStep[] = [
+   {
+      title: 'Daftar Jabatan',
+      description: 'Halaman ini menampilkan semua jabatan yang terdaftar. Gunakan tab untuk memfilter jabatan aktif atau tidak aktif.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Menu Aksi',
+      description: 'Ketuk salah satu jabatan untuk membuka menu aksi — kamu bisa mengaktifkan/menonaktifkan atau mengedit nama jabatan.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+];
+
+export const GUIDE_GROUP: GuideStep[] = [
+   {
+      title: 'Daftar Lembaga Desa',
+      description: 'Halaman ini menampilkan semua lembaga desa yang terdaftar. Gunakan tab untuk memfilter yang aktif atau tidak aktif.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Menu Aksi',
+      description: 'Ketuk salah satu lembaga untuk membuka menu aksi — kamu bisa mengaktifkan/menonaktifkan atau mengedit nama lembaga.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+];
+
+export const GUIDE_BANNER: GuideStep[] = [
+   {
+      title: 'Daftar Banner',
+      description: 'Halaman ini menampilkan semua banner yang ada di desa kamu.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Buka Menu Aksi',
+      description: 'Ketuk salah satu banner untuk membuka menu aksi — kamu bisa melihat, mengedit, atau menghapus banner.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Tambah Banner',
+      description: 'Ketuk tombol tambah di pojok kanan atas untuk menambahkan banner baru.',
+      cardTopRatio: 0.15,
+      arrowDirection: 'up',
+      arrowOffset: 1.05,
+   },
+];
+
+export const GUIDE_PROJECT_DETAIL: GuideStep[] = [
+   {
+      title: 'Detail Kegiatan',
+      description: 'Halaman ini menampilkan informasi lengkap sebuah kegiatan, mulai dari progress, tugas, file, hingga anggota.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'Progress Kegiatan',
+      description: 'Bar ini menunjukkan seberapa banyak tugas yang sudah diselesaikan dari total tugas yang ada.',
+      cardTopRatio: 0.28,
+      arrowDirection: 'up',
+      arrowOffset: 0.5,
+   },
+   {
+      title: 'Daftar Tugas',
+      description: 'Semua tugas dalam kegiatan ini ditampilkan di sini. Ketuk tugas untuk melihat detail atau mengubah statusnya.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+   {
+      title: 'File & Tautan',
+      description: 'File dan tautan pendukung kegiatan tersedia di bagian bawah. Scroll ke bawah untuk mengaksesnya.',
+      cardTopRatio: 0.35,
+      arrowDirection: 'none',
+   },
+];
--- a/lib/useGuide.ts
+++ b/lib/useGuide.ts
@@ -0,0 +1,28 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { useEffect, useState } from 'react';
+
+const KEY_PREFIX = '@guide:';
+
+export function useGuide(featureKey: string) {
+   const [visible, setVisible] = useState(false);
+   const [checked, setChecked] = useState(false);
+
+   useEffect(() => {
+      AsyncStorage.getItem(KEY_PREFIX + featureKey).then((val) => {
+         if (!val) setVisible(true);
+         setChecked(true);
+      });
+   }, [featureKey]);
+
+   async function dismiss() {
+      setVisible(false);
+      await AsyncStorage.setItem(KEY_PREFIX + featureKey, 'done');
+   }
+
+   async function reset() {
+      await AsyncStorage.removeItem(KEY_PREFIX + featureKey);
+      setVisible(true);
+   }
+
+   return { visible: checked && visible, dismiss, reset };
+}