@xetwa/design-system 1.0.2

package/src/components/Headers/CountryHeader/CountryHeader.stories.tsx

@@ -0,0 +1,114 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { CountryHeader } from './CountryHeader';
+import { countryThemes } from '../../../styles/countryThemes';
+
+const meta = {
+  title: 'Components/Headers/CountryHeader',
+  component: CountryHeader,
+  argTypes: {
+    countryCode: {
+      control: 'select',
+      options: Object.keys(countryThemes),
+      description: 'Código do país para a paleta de cores e bandeira',
+    },
+  },
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `O **CountryHeader** é o cabeçalho principal dos ecrãs de Módulo ou Etapa de um País.
+Ele adapta inteligentemente a cor de fundo, o círculo decorativo e as cores da barra de progresso baseando-se unicamente no \`countryCode\` que recebe. Utiliza a paleta oficial da Xetwa para países francófonos.
+
+### Lidar com a SafeArea (Notch / Status Bar)
+Como este cabeçalho tem uma cor de fundo sólida e um círculo decorativo, ele deve ignorar as margens do ecrã e ir **até ao limite superior físico do telemóvel**.
+Para isso, NÃO coloque este componente dentro de uma \`SafeAreaView\` convencional com margem no topo.
+Em vez disso, passe a propriedade \`safeAreaTop\` com o valor gerado pelo hook \`useSafeAreaInsets()\` do \`react-native-safe-area-context\`.
+
+\`\`\`tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+export function Screen() {
+  const insets = useSafeAreaInsets();
+  
+  return (
+    <View style={{ flex: 1 }}>
+      <CountryHeader
+        countryCode="SN"
+        title="Senegal"
+        // ...
+        safeAreaTop={insets.top}
+      />
+    </View>
+  );
+}
+\`\`\`
+
+### Exemplo de Uso
+\`\`\`tsx
+<CountryHeader
+  countryCode="SN"
+  title="Senegal"
+  subtitle="Dakar · Saint-Louis · 2 de 4 módulos"
+  headerText="ETAPA 3 · A1"
+  progress={0.5}
+  progressSegments={4}
+  onBackPress={() => console.log('Voltar')}
+/>
+\`\`\`
+`
+      }
+    }
+  },
+  tags: ['autodocs'],
+} satisfies Meta<any>;
+
+export default meta;
+type Story = StoryObj<any>;
+
+export const Senegal: Story = {
+  name: 'Senegal (SN)',
+  args: {
+    countryCode: 'SN',
+    title: 'Senegal',
+    subtitle: 'Dakar · Saint-Louis · 2 de 4 módulos',
+    headerText: 'ETAPA 3 · A1',
+    progress: 0.5,
+    progressSegments: 4,
+  },
+};
+
+export const France: Story = {
+  name: 'França (FR)',
+  args: {
+    countryCode: 'FR',
+    title: 'França',
+    subtitle: 'Paris · Lyon · 1 de 4 módulos',
+    headerText: 'ETAPA 1 · A1',
+    progress: 0.25,
+    progressSegments: 4,
+  },
+};
+
+export const Congo: Story = {
+  name: 'RD Congo (CD)',
+  args: {
+    countryCode: 'CD',
+    title: 'Congo',
+    subtitle: 'Kinshasa · 4 de 4 módulos',
+    headerText: 'ETAPA 5 · B1',
+    progress: 1.0,
+    progressSegments: 4,
+  },
+};
+
+export const WithSafeArea: Story = {
+  name: 'Simulação de SafeArea (iPhone Notch)',
+  args: {
+    countryCode: 'SN',
+    title: 'Senegal (Com Notch)',
+    subtitle: 'Cabeçalho empurra o conteúdo para baixo',
+    headerText: 'SIMULAÇÃO DE INSETS.TOP',
+    progress: 0.5,
+    safeAreaTop: 47, // Valor comum para iPhone 12/13/14
+  },
+};

package/src/components/Headers/CountryHeader/CountryHeader.tsx

@@ -0,0 +1,147 @@
+import { View, StyleSheet } from 'react-native';
+import type { ViewStyle } from 'react-native';
+import { useResponsive } from '../../../hooks/useResponsive';
+import { getCountryTheme } from '../../../styles/countryThemes';
+import { Flag } from '../../DataDisplay/Flag/Flag';
+import { ProgressBar } from '../../DataDisplay/ProgressBar/ProgressBar';
+import { BackButton } from '../../Buttons/BackButton/BackButton';
+import { Typography } from '../../Typography/Typography';
+
+export interface CountryHeaderProps {
+  /** Código ISO do país (ex: 'SN') para a bandeira e o tema de cores */
+  countryCode: string;
+  /** Nome do país (ex: 'Senegal') */
+  title: string;
+  /** Subtítulo (ex: 'Dakar · Saint-Louis · 2 de 4 módulos') */
+  subtitle: string;
+  /** Texto do cabeçalho superior (ex: 'ETAPA 3 · A1') */
+  headerText: string;
+  /** Progresso atual de 0.0 a 1.0 */
+  progress: number;
+  /** Número de segmentos na barra de progresso */
+  progressSegments?: number;
+  /** Função ao clicar no botão de voltar */
+  onBackPress?: () => void;
+  /** 
+   * Espaçamento extra no topo para acomodar a Notch/Status Bar do dispositivo.
+   * O developer deve passar o \`insets.top\` gerado pelo \`react-native-safe-area-context\`.
+   */
+  safeAreaTop?: number;
+  /** Estilos customizados opcionais para o container principal */
+  style?: ViewStyle | ViewStyle[];
+}
+
+export const CountryHeader = ({
+  countryCode,
+  title,
+  subtitle,
+  headerText,
+  progress,
+  progressSegments = 4,
+  onBackPress,
+  safeAreaTop = 0,
+  style,
+}: CountryHeaderProps) => {
+  const { scale, scaleText } = useResponsive();
+  const countryTheme = getCountryTheme(countryCode);
+
+  return (
+    <View style={[styles.container, { backgroundColor: countryTheme.bg }, style]}>
+      {/* Círculo decorativo de fundo */}
+      <View
+        style={[
+          styles.decorativeCircle,
+          {
+            backgroundColor: countryTheme.circle,
+            width: scale(230),
+            height: scale(230),
+            borderRadius: scale(120),
+            top: scale(-80),
+            right: scale(-80),
+          },
+        ]}
+      />
+
+      <View style={[styles.content, { padding: scale(20), paddingTop: safeAreaTop + scale(24) }]}>
+        {/* Top Bar: Back Button e Header Text */}
+        <View style={[styles.topRow, { marginBottom: scale(16) }]}>
+          <BackButton onPress={onBackPress} variant="glass" />
+          <Typography style={[styles.headerText, { fontSize: scaleText(13), lineHeight: scaleText(16), marginLeft: scale(12) }]}>
+            {headerText}
+          </Typography>
+        </View>
+
+        {/* Flag e Título/Subtítulo */}
+        <View style={[styles.titleRow, { marginBottom: scale(16) }]}>
+          <View style={[styles.flagWrapper, { padding: scale(2) }]}>
+            <Flag countryCode={countryCode} size={scale(56)} />
+          </View>
+          <View style={[styles.textContainer, { marginLeft: scale(12) }]}>
+            <Typography style={[styles.title, { fontSize: scaleText(26), lineHeight: scaleText(30) }]}>
+              {title}
+            </Typography>
+            <Typography style={[styles.subtitle, { fontSize: scaleText(13), lineHeight: scaleText(16), marginTop: scale(2) }]}>
+              {subtitle}
+            </Typography>
+          </View>
+        </View>
+
+        {/* Progress Bar */}
+        <ProgressBar
+          progress={progress}
+          segments={progressSegments}
+          size="sm"
+          fillColor={countryTheme.progressFill}
+          trackColor={countryTheme.progressTrack}
+        />
+      </View>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    width: '100%',
+    overflow: 'hidden',
+    position: 'relative',
+  },
+  decorativeCircle: {
+    position: 'absolute',
+  },
+  content: {
+    width: '100%',
+  },
+  topRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    zIndex: 2, // Garante que fica acima do círculo decorativo
+  },
+  headerText: {
+    color: 'rgba(255, 255, 255, 0.8)',
+
+    letterSpacing: 0.5,
+  },
+  titleRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    zIndex: 2,
+  },
+  flagWrapper: {
+    backgroundColor: '#ffffff',
+    borderRadius: 999,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  textContainer: {
+    flex: 1,
+  },
+  title: {
+
+    color: '#ffffff',
+  },
+  subtitle: {
+
+    color: '#ffffff',
+    opacity: 0.9,
+  },
+});

package/src/components/Headers/ProfileHeader/ProfileHeader.stories.tsx

@@ -0,0 +1,141 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { View } from 'react-native';
+import { ProfileHeader } from './ProfileHeader';
+
+const meta = {
+  title: 'Components/Headers/ProfileHeader',
+  component: ProfileHeader,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `O **ProfileHeader** é o cabeçalho principal do ecrã de perfil do utilizador. Apresenta os dados do utilizador (nome e avatar circular), assim como um resumo do progresso no país atual.
+
+A responsividade e consistência visual são garantidas através do uso de escalas de fontes (\`scaleText\`), empacotamento em \`maxWidth: 500\`, e redimensionamento automático de texto para ecrãs mais pequenos ou nomes excessivamente longos.
+
+### Lidar com a SafeArea (Notch / Status Bar)
+Assim como o \`CountryHeader\`, este componente estende-se até ao limite superior físico do telemóvel. Deves passar a propriedade \`safeAreaTop\` com o valor gerado pelo hook \`useSafeAreaInsets()\` do \`react-native-safe-area-context\`.
+
+\`\`\`tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { View } from 'react-native';
+import { ProfileHeader } from '@xetlingo/design-system';
+
+export function ProfileScreen() {
+  const insets = useSafeAreaInsets();
+  
+  return (
+    <View style={{ flex: 1 }}>
+      <ProfileHeader
+        userName="Sofia"
+        userSubtitle="a caminho de C1 · entrou em jan 2026"
+        avatarInitials="SO"
+        countryCode="SN"
+        countryName="Senegal"
+        level="Nível B2"
+        moduleSubtitle="país atual · 2 de 4 módulos"
+        progressPercentage={50}
+        safeAreaTop={insets.top}
+        onSettingsPress={() => console.log('Definições')}
+      />
+    </View>
+  );
+}
+\`\`\`
+
+### Casos de Uso Comuns
+
+#### 1. Uso com Imagem no Avatar e Bandeira Nativa (Vetorizada)
+Caso o utilizador tenha uma foto de perfil, podes passá-la diretamente no \`avatarSrc\`.
+\`\`\`tsx
+<ProfileHeader
+  userName="Mamadou"
+  userSubtitle="a caminho de B1 · entrou em fev 2026"
+  avatarSrc="https://exemplo.com/avatar.jpg"
+  countryCode="BE"
+  countryName="Bélgica"
+  level="Nível A2"
+  moduleSubtitle="país atual · 1 de 4 módulos"
+  progressPercentage={25}
+  onSettingsPress={() => abrirDefinicoes()}
+/>
+\`\`\`
+
+#### 2. Uso com Iniciais do Utilizador e Fallback de Imagem Local
+Se o utilizador não tiver imagem, as iniciais serão apresentadas. Podes opcionalmente passar uma imagem local como bandeira utilizando \`countryFlagSrc\`.
+\`\`\`tsx
+<ProfileHeader
+  userName="Maria"
+  userSubtitle="a caminho do domínio completo do idioma"
+  avatarInitials="MA"
+  countryFlagSrc={require('./assets/bandeira_sn.png')}
+  countryName="Senegal"
+  level="Nível C1"
+  moduleSubtitle="país atual · 4 de 4 módulos"
+  progressPercentage={100}
+/>
+\`\`\`
+`
+      }
+    }
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <View style={{ flex: 1, backgroundColor: '#ffffff' }}>
+        <Story />
+      </View>
+    ),
+  ],
+} satisfies Meta<any>;
+
+export default meta;
+type Story = StoryObj<any>;
+
+
+export const Default: Story = {
+  args: {
+    userName: 'Sofia',
+    userSubtitle: 'a caminho de C1 · entrou em jan 2026',
+    avatarInitials: 'SO',
+    countryCode: 'SN',
+    countryName: 'Senegal',
+    level: 'Nível B2',
+    moduleSubtitle: 'país atual · 2 de 4 módulos',
+    progressPercentage: 50,
+    safeAreaTop: 44, // Simula a notch para que o design pareça real
+    onSettingsPress: () => console.log('Definições clicadas'),
+  },
+};
+
+export const AvatarImage: Story = {
+  name: 'Com Imagem no Avatar',
+  args: {
+    userName: 'Mamadou',
+    userSubtitle: 'a caminho de B1 · entrou em fev 2026',
+    avatarSrc: 'https://i.pravatar.cc/150?img=11',
+    countryCode: 'BE',
+    countryName: 'Bélgica',
+    level: 'Nível A2',
+    moduleSubtitle: 'país atual · 1 de 4 módulos',
+    progressPercentage: 25,
+    safeAreaTop: 44,
+    onSettingsPress: () => console.log('Definições clicadas'),
+  },
+};
+
+export const TextosLongos: Story = {
+  name: 'Com Textos Longos (Teste Responsivo)',
+  args: {
+    userName: 'Maria Francisca das Neves',
+    userSubtitle: 'a caminho do domínio completo do idioma local',
+    avatarInitials: 'MF',
+    countryCode: 'CD',
+    countryName: 'República Democrática do Congo',
+    level: 'Nível C1 - Avançado',
+    moduleSubtitle: 'país atual muito longo para testar a quebra ou encolhimento de texto em ecrãs',
+    progressPercentage: 100,
+    safeAreaTop: 44,
+    onSettingsPress: () => console.log('Definições clicadas'),
+  },
+};

package/src/components/Headers/ProfileHeader/ProfileHeader.tsx

@@ -0,0 +1,233 @@
+import { View, StyleSheet, Image, TouchableOpacity } from 'react-native';
+import type { ViewStyle, ImageSourcePropType } from 'react-native';
+import { Settings } from 'lucide-react-native';
+import { theme } from '../../../styles/theme';
+import { useResponsive } from '../../../hooks/useResponsive';
+import { Avatar } from '../../DataDisplay/Avatar/Avatar';
+import { Flag } from '../../DataDisplay/Flag/Flag';
+import { Typography } from '../../Typography/Typography';
+
+export interface ProfileHeaderProps {
+  /** Nome do utilizador */
+  userName: string;
+  /** Subtítulo do utilizador (ex: "a caminho de C1 · entrou em jan 2026") */
+  userSubtitle: string;
+  /** Fonte da imagem do avatar */
+  avatarSrc?: string | ImageSourcePropType;
+  /** Iniciais caso não haja avatar */
+  avatarInitials?: string;
+  
+  /** Código ISO do país (ex: 'SN') para renderizar a bandeira de forma nativa e nítida */
+  countryCode?: string;
+  /** Bandeira do país atual (fallback caso não forneça countryCode) */
+  countryFlagSrc?: ImageSourcePropType;
+  /** Nome do país atual */
+  countryName: string;
+  /** Nível de aprendizagem atual no país */
+  level: string;
+  /** Subtítulo do módulo atual */
+  moduleSubtitle: string;
+  /** Percentagem de progresso (0-100) */
+  progressPercentage: number;
+  
+  /** Espaçamento extra no topo para SafeArea/Notch */
+  safeAreaTop?: number;
+  /** Evento ao clicar nas definições */
+  onSettingsPress?: () => void;
+  /** Estilos opcionais */
+  style?: ViewStyle | ViewStyle[];
+}
+
+export const ProfileHeader = ({
+  userName,
+  userSubtitle,
+  avatarSrc,
+  avatarInitials,
+  countryCode,
+  countryFlagSrc,
+  countryName,
+  level,
+  moduleSubtitle,
+  progressPercentage,
+  safeAreaTop = 0,
+  onSettingsPress,
+  style,
+}: ProfileHeaderProps) => {
+  const { scale, scaleText } = useResponsive();
+
+  return (
+    <View style={[styles.container, style]}>
+      {/* Background Decorativo - Círculo menor na direita */}
+      <View 
+        style={[
+          styles.decorativeCircle, 
+          { 
+            width: scale(140), 
+            height: scale(140), 
+            borderRadius: scale(70),
+            top: -scale(30), 
+            right: -scale(30) 
+          }
+        ]} 
+      />
+
+      <View style={[styles.content, { paddingHorizontal: scale(20), paddingBottom: scale(20), paddingTop: safeAreaTop + scale(16) }]}>
+        {/* Top Section: Avatar & Info */}
+        <View style={styles.topSection}>
+          <View style={styles.userInfoRow}>
+            <View style={{ marginRight: scale(16) }}>
+              <Avatar 
+                size="xl" 
+                variant="circle" 
+                src={avatarSrc as any} 
+                initials={avatarInitials} 
+                color={theme.colors.primary} 
+              />
+            </View>
+            
+            <View style={styles.userTexts}>
+              <Typography 
+                style={[styles.userName, { fontSize: scaleText(26), lineHeight: scaleText(30) }]}
+                numberOfLines={1}
+                adjustsFontSizeToFit
+              >
+                {userName}
+              </Typography>
+              <Typography 
+                style={[styles.userSubtitle, { fontSize: scaleText(14.5), lineHeight: scaleText(18), marginTop: scale(4) }]}
+              >
+                {userSubtitle}
+              </Typography>
+            </View>
+          </View>
+          
+          {onSettingsPress && (
+            <TouchableOpacity 
+              style={[styles.settingsButton, { padding: scale(8) }]} 
+              onPress={onSettingsPress}
+              activeOpacity={0.7}
+            >
+              <Settings color={theme.colors.brown[100]} size={scale(24)} strokeWidth={2.2} />
+            </TouchableOpacity>
+          )}
+        </View>
+
+        {/* Bottom Section: Progress Card */}
+        <View style={[styles.progressCard, { padding: scale(16), borderRadius: scale(20), marginTop: scale(20) }]}>
+          <View style={styles.progressCardLeft}>
+            {countryCode ? (
+              <Flag 
+                countryCode={countryCode} 
+                size={scale(36)} 
+                style={{ 
+                  height: scale(26), 
+                  borderRadius: scale(4), 
+                  marginRight: scale(16) 
+                }} 
+              />
+            ) : countryFlagSrc ? (
+              <Image 
+                source={countryFlagSrc} 
+                style={[styles.flag, { width: scale(36), height: scale(26), borderRadius: scale(4), marginRight: scale(16) }]} 
+                resizeMode="cover"
+              />
+            ) : null}
+            <View style={styles.progressCardTexts}>
+              <Typography 
+                style={[styles.progressTitle, { fontSize: scaleText(16.5), lineHeight: scaleText(20) }]}
+                numberOfLines={1}
+                adjustsFontSizeToFit
+              >
+                {countryName} · {level}
+              </Typography>
+              <Typography style={[styles.progressSubtitle, { fontSize: scaleText(13.5), lineHeight: scaleText(17), marginTop: scale(2) }]}>
+                {moduleSubtitle}
+              </Typography>
+            </View>
+          </View>
+
+          <Typography style={[styles.progressPercent, { fontSize: scaleText(22), lineHeight: scaleText(26) }]}>
+            {progressPercentage}%
+          </Typography>
+        </View>
+      </View>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    backgroundColor: theme.colors.brown[700], // Fundo principal mais escuro (#3f2620)
+    width: '100%',
+    maxWidth: 500, // Limita o tamanho em Storybook / ecrãs largos
+    alignSelf: 'center',
+    overflow: 'hidden',
+  },
+  decorativeCircle: {
+    position: 'absolute',
+    backgroundColor: '#6b4332', // Cor customizada solicitada pelo utilizador
+  },
+  content: {
+    position: 'relative',
+    zIndex: 1,
+    width: '100%',
+  },
+  topSection: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+  },
+  userInfoRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    flex: 1,
+    paddingRight: 8,
+  },
+  userTexts: {
+    flex: 1,
+    justifyContent: 'center',
+  },
+  userName: {
+
+    color: theme.colors.white,
+  },
+  userSubtitle: {
+
+    color: theme.colors.brown[100], // Cor mais clara e legível
+  },
+  settingsButton: {
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  progressCard: {
+    backgroundColor: theme.colors.brown[800], // Mesma cor do círculo (#51332d)
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+  },
+  progressCardLeft: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    flex: 1,
+    paddingRight: 8,
+  },
+  flag: {
+    backgroundColor: theme.colors.brown[600], // fallback if loading
+  },
+  progressCardTexts: {
+    flex: 1,
+    justifyContent: 'center',
+  },
+  progressTitle: {
+
+    color: theme.colors.white,
+  },
+  progressSubtitle: {
+
+    color: theme.colors.brown[300],
+  },
+  progressPercent: {
+
+    color: theme.colors.primary,
+  },
+});