@xetwa/design-system 1.0.42 → 1.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xetwa/design-system",
-  "version": "1.0.42",
+  "version": "1.0.43",
   "type": "module",
   "publishConfig": {
     "access": "public"

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

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { View } from 'react-native';
+import { RouteHeader } from './RouteHeader';
+import { theme } from '../../../styles/theme';
+
+const meta = {
+  title: 'Components/Headers/RouteHeader',
+  component: RouteHeader,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `O **RouteHeader** é o cabeçalho principal (HUD) para ecrãs de percurso/navegação num mapa, substituindo a navegação clássica com setas de voltar.
+        
+### Caso de Uso Principal
+Utilizado no topo do mapa para informar o utilizador:
+1. Em que **país/módulo** se encontra (bandeira grande + nome da cidade).
+2. Qual o seu **nível e evolução** atual (ex: A1 → C1, 63%).
+3. Como está o seu **progresso**, que pode ser exibido de forma fluida (\`continuous\`) ou em paragens discretas (\`segmented\`).
+
+### Lidar com a SafeArea (Notch / Status Bar)
+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\`.
+
+### Exemplo de Código
+\`\`\`tsx
+import { RouteHeader } from '@xetwa/design-system';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { View } from 'react-native';
+
+export const MapScreen = () => {
+  const insets = useSafeAreaInsets();
+
+  return (
+    <View style={{ flex: 1 }}>
+      <RouteHeader
+        routeLabel="ROTA DA FRANCOFONIA"
+        stepLabel="paragem 5 de 8"
+        countryCode="SN"
+        title="Dakar"
+        subtitle="Nível B2 · estás aqui"
+        progressText="63%"
+        progressSubText="A1 → C1"
+        progress={0.63}
+        progressType="segmented"
+        totalSegments={8}
+        safeAreaTop={insets.top}
+      />
+      {/* ... Mapa Embaixo ... */}
+    </View>
+  );
+};
+\`\`\`
+`,
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <View style={{ flex: 1, backgroundColor: theme.colors.brown[100] }}>
+        <Story />
+      </View>
+    ),
+  ],
+  tags: ['autodocs'],
+  argTypes: {
+    progressType: {
+      control: 'radio',
+      options: ['continuous', 'segmented'],
+    },
+  },
+} satisfies Meta<typeof RouteHeader>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Continuous: Story = {
+  args: {
+    routeLabel: 'ROTA DA FRANCOFONIA',
+    countryCode: 'SN',
+    title: 'Dakar',
+    subtitle: 'Nível B2 · estás aqui',
+    progressText: '63%',
+    progressSubText: 'A1 → C1',
+    progress: 0.63,
+    progressType: 'continuous',
+    safeAreaTop: 20,
+  },
+};
+
+export const Segmented: Story = {
+  args: {
+    routeLabel: 'ROTA DA FRANCOFONIA',
+    stepLabel: 'paragem 5 de 8',
+    countryCode: 'SN',
+    title: 'Dakar',
+    subtitle: 'Nível B2 · estás aqui',
+    progressText: '63%',
+    progressSubText: 'A1 → C1',
+    progress: 0.63,
+    totalSegments: 8,
+    progressType: 'segmented',
+    safeAreaTop: 20,
+  },
+};

package/src/components/Headers/RouteHeader/RouteHeader.tsx

@@ -0,0 +1,218 @@
+import React from 'react';
+import { View, StyleSheet, Platform } from 'react-native';
+import type { ViewStyle } from 'react-native';
+import { Typography } from '../../Typography/Typography';
+import { Flag } from '../../DataDisplay/Flag/Flag';
+import { ProgressBar } from '../../DataDisplay/ProgressBar/ProgressBar';
+import { theme } from '../../../styles/theme';
+import { useResponsive } from '../../../hooks/useResponsive';
+
+/**
+ * Propriedades para o componente RouteHeader.
+ */
+export interface RouteHeaderProps {
+  /** 
+   * Label principal no topo esquerdo. Usado para indicar a rota global.
+   * @example "ROTA DA FRANCOFONIA"
+   */
+  routeLabel: string;
+  /** 
+   * Label secundária no topo direito. Usada para indicar a etapa ou paragem atual no caminho.
+   * @example "paragem 5 de 8"
+   */
+  stepLabel?: string;
+  /** 
+   * Código ISO Alpha-2 do país para a bandeira. 
+   * A bandeira serve como o avatar principal ("estás aqui").
+   * @example "SN" (Senegal)
+   */
+  countryCode: string;
+  /** 
+   * Título principal, geralmente o nome do destino ou cidade atual.
+   * @example "Dakar"
+   */
+  title: string;
+  /** 
+   * Subtítulo por baixo do título. Mostra o nível ou estado do utilizador.
+   * @example "Nível B2 · estás aqui"
+   */
+  subtitle: string;
+  /** 
+   * Percentagem ou valor métrico em formato de texto grande.
+   * @example "63%"
+   */
+  progressText: string;
+  /** 
+   * Texto auxiliar debaixo da percentagem que descreve a evolução.
+   * @example "A1 → C1"
+   */
+  progressSubText: string;
+  /** 
+   * Valor numérico absoluto do progresso total (entre 0.0 e 1.0).
+   * Controla a percentagem preenchida da barra (independente de ser segmentada).
+   */
+  progress: number;
+  /** 
+   * Total de segmentos visíveis se a barra for do tipo "segmented".
+   * Representa o número total de paragens ou módulos de uma rota.
+   * @default 1
+   */
+  totalSegments?: number;
+  /** 
+   * Determina a aparência da barra de progresso.
+   * - `continuous`: Barra lisa, ideal para indicar a percentagem de uma única etapa longa.
+   * - `segmented`: Barra dividida em secções, excelente para rotas com várias "paragens".
+   * @default 'continuous'
+   */
+  progressType?: 'continuous' | 'segmented';
+  /** 
+   * Espaçamento extra no topo para evitar que o conteúdo fique por baixo da Notch/Status Bar.
+   * Deve receber o `insets.top` devolvido pelo hook `useSafeAreaInsets()`.
+   */
+  safeAreaTop?: number;
+  /** 
+   * Estilos adicionais para o contentor exterior (ex: zIndex, position absolute). 
+   */
+  style?: ViewStyle | ViewStyle[];
+}
+
+/**
+ * **RouteHeader**
+ * 
+ * Cabeçalho principal para os ecrãs de percurso e navegação. Apresenta o progresso 
+ * de aprendizagem do utilizador ao longo de uma "rota" cultural/geográfica.
+ * 
+ * ### Casos de Uso
+ * - **Home do Percurso (Mapa Principal):** Usado sem setas de voltar, servindo de HUD de navegação global. 
+ * Combina informações de localização (onde estou? -> Dakar) e informações de progresso (63%).
+ * - **Tipos de Progresso:** Pode apresentar o progresso fluido (`continuous`) para uma visão global, ou
+ * faseado por módulos/paragens (`segmented`) quando o foco é passar de um ponto para o outro num mapa.
+ */
+export const RouteHeader = ({
+  routeLabel,
+  stepLabel,
+  countryCode,
+  title,
+  subtitle,
+  progressText,
+  progressSubText,
+  progress,
+  totalSegments = 1,
+  progressType = 'continuous',
+  safeAreaTop = 0,
+  style,
+}: RouteHeaderProps) => {
+  const { scale } = useResponsive();
+
+  const segments = progressType === 'segmented' ? Math.max(1, totalSegments) : 1;
+
+  return (
+    <View style={[styles.container, { paddingTop: safeAreaTop + scale(20), paddingHorizontal: scale(24), paddingBottom: scale(24) }, style]}>
+      {/* Top Row: Labels */}
+      <View style={[styles.topRow, { marginBottom: scale(16) }]}>
+        <Typography variant="bodySm" color={theme.colors.brown[500]} style={{ textTransform: 'uppercase', letterSpacing: 0.5 }}>
+          {routeLabel}
+        </Typography>
+        {stepLabel ? (
+          <Typography variant="bodySmHeavy" color={theme.colors.brown[500]}>
+            {stepLabel}
+          </Typography>
+        ) : null}
+      </View>
+
+      {/* Middle Row: Flag, Title, Progress Text */}
+      <View style={[styles.middleRow, { marginBottom: scale(20) }]}>
+        {/* Bandeira com anel "estás aqui" e shadow 3D */}
+        <View style={[styles.flagWrapper, { width: scale(64), height: scale(64) }, styles.flagShadow]}>
+          <Flag countryCode={countryCode} size={scale(48)} />
+        </View>
+
+        <View style={[styles.titleContainer, { marginLeft: scale(16) }]}>
+          <Typography variant="h1" color={theme.colors.brown[800]}>
+            {title}
+          </Typography>
+          <Typography variant="bodyMdHeavy" color={theme.colors.primary}>
+            {subtitle}
+          </Typography>
+        </View>
+
+        <View style={styles.progressTextContainer}>
+          <Typography variant="h2" color={theme.colors.primary}>
+            {progressText}
+          </Typography>
+          <Typography variant="smallHeavy" color={theme.colors.brown[500]}>
+            {progressSubText}
+          </Typography>
+        </View>
+      </View>
+
+      {/* Bottom Row: Progress Bar */}
+      <ProgressBar
+        progress={progress}
+        segments={segments}
+        size="md"
+        variant="default" // Usa a cor primária (laranja)
+      />
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    backgroundColor: theme.colors.brown[50], // cream color matching the image
+    width: '100%',
+    zIndex: 10,
+    // Soft shadow to separate from content below
+    ...Platform.select({
+      web: {
+        boxShadow: '0px 4px 12px rgba(0, 0, 0, 0.05)',
+      },
+      default: {
+        shadowColor: '#000',
+        shadowOffset: { width: 0, height: 4 },
+        shadowOpacity: 0.05,
+        shadowRadius: 8,
+        elevation: 4,
+      }
+    }),
+  },
+  topRow: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+  },
+  middleRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+  flagWrapper: {
+    borderRadius: 999,
+    borderWidth: 2.5,
+    borderColor: theme.colors.primary, // Anel laranja que significa "estás aqui"
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: theme.colors.white,
+  },
+  flagShadow: {
+    ...Platform.select({
+      web: {
+        boxShadow: `0px 4px 0px ${theme.colors.brown[100]}`,
+      },
+      default: {
+        shadowColor: theme.colors.brown[100],
+        shadowOffset: { width: 0, height: 4 },
+        shadowOpacity: 1,
+        shadowRadius: 0,
+        elevation: 4,
+      }
+    })
+  },
+  titleContainer: {
+    flex: 1,
+    justifyContent: 'center',
+  },
+  progressTextContainer: {
+    alignItems: 'flex-end',
+    justifyContent: 'center',
+  },
+});

package/src/index.ts

@@ -40,6 +40,7 @@ export * from './components/Forms/Switch/Switch';
 export * from './components/Forms/TimeSlot/TimeSlot';
 export * from './components/Headers/CountryHeader/CountryHeader';
 export * from './components/Headers/ProfileHeader/ProfileHeader';
+export * from './components/Headers/RouteHeader/RouteHeader';
 export * from './components/Inputs/FillInTheBlank/FillInTheBlank';
 export * from './components/Inputs/TextInput/TextInput';
 export * from './components/Mascots/Vava/Vava';