@xetwa/design-system 1.0.48 → 1.0.50

package/src/components/DataDisplay/StampCard/StampCard.stories.tsx

@@ -0,0 +1,275 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { View } from 'react-native';
+import { StampCard } from './StampCard';
+import { theme } from '../../../styles/theme';
+
+/**
+ * \`StampCard\` é um contentor elegante que exibe um \`Stamp\` no topo e 
+ * informações de contexto (Bandeira, Local, e Subtítulo) na base.
+ * É perfeito para ser usado como card de conquista ou progresso numa grelha.
+ * 
+ * ### Características
+ * - **Modular:** Recebe diretamente as propriedades do \`Stamp\` interno.
+ * - **Design Alinhado:** A cor do local mapeia automaticamente com a cor do carimbo.
+ * - **Container Clean:** Borda redonda e fundo sólido.
+ */
+const meta = {
+  title: 'Components/Cards/StampCard',
+  component: StampCard,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `O \`StampCard\` é um contentor elegante que exibe um \`Stamp\` no topo e informações de contexto (Bandeira, Local, e Subtítulo) na base.
+É perfeito para ser usado como card de conquista ou progresso numa grelha.
+
+### Características
+- **Modular:** Recebe diretamente as propriedades do \`Stamp\` interno.
+- **Design Alinhado:** A cor do local mapeia automaticamente com a cor do carimbo.
+- **Container Clean:** Borda redonda e fundo sólido.
+
+### Exemplo de Uso
+\`\`\`tsx
+import { StampCard } from '@/components/DataDisplay/StampCard/StampCard';
+import { theme } from '@/styles/theme';
+
+<StampCard 
+  stamp={{
+    color: theme.colors.error,
+    title: 'PARIS',
+    topLabel: 'FRANCE',
+    bottomLabels: ['NIVEAU A1', 'ABR 2026'],
+    size: 'md',
+    position: 'center',
+  }}
+  countryCode="FR"
+  locationName="Paris"
+  subtitle="A1 • concluído"
+  variant="warning"
+  warningText="Visto a expirar!"
+/>
+\`\`\`
+`
+      }
+    }
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    width: {
+      control: 'text',
+      description: 'Largura do cartão (ex: 320 ou "100%").',
+    },
+    height: {
+      control: 'text',
+      description: 'Altura do cartão.',
+    },
+    variant: {
+      control: 'radio',
+      options: ['default', 'highlight', 'warning'],
+      description: 'Variante visual do cartão.',
+    },
+    warningText: {
+      control: 'text',
+      description: 'Texto exibido no topo quando variant="warning".',
+      if: { arg: 'variant', eq: 'warning' },
+    },
+    countryCode: {
+      control: 'text',
+      description: 'Código ISO ou nome do país para gerar a bandeira.',
+    },
+    locationName: {
+      control: 'text',
+      description: 'Nome do local em destaque.',
+    },
+    subtitle: {
+      control: 'text',
+      description: 'Subtítulo cinzento/castanho inferior.',
+    },
+  },
+} satisfies Meta<typeof StampCard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Exemplo padrão conforme a especificação do design.
+ */
+export const Default: Story = {
+  args: {
+    stamp: {
+      color: theme.colors.error,
+      title: 'LYON',
+      topLabel: 'FRANCE',
+      bottomLabels: ['NIVEAU A1', 'ABR 2026'],
+      size: 'md',
+      position: 'center',
+    },
+    countryCode: 'FR',
+    locationName: 'Lyon',
+    subtitle: 'A1 • concluído',
+    variant: 'default',
+  },
+};
+
+/**
+ * Exemplo de um cartão em destaque (highlight) com a borda espessa 
+ * que herda a cor do carimbo interno.
+ */
+export const Highlight: Story = {
+  args: {
+    stamp: {
+      color: theme.colors.primary,
+      title: 'DAKAR',
+      topLabel: 'SÉNÉGAL',
+      bottomLabels: ['NIVEAU B1', 'EM CURSO'],
+      size: 'md',
+      position: 'center',
+    },
+    countryCode: 'SN',
+    locationName: 'Dakar',
+    subtitle: 'B1 • em curso',
+    variant: 'highlight',
+  },
+};
+
+/**
+ * Exemplo de um cartão com aviso crítico (warning),
+ * sobrepondo uma badge no topo.
+ */
+export const Warning: Story = {
+  args: {
+    stamp: {
+      color: theme.colors.primaryDark,
+      title: 'BRUXELLES',
+      topLabel: 'BELGIQUE',
+      bottomLabels: ['NIVEAU A2', 'JUL 2026'],
+      size: 'md',
+      position: 'left',
+    },
+    countryCode: 'BE',
+    locationName: 'Bruxelles',
+    subtitle: 'A2 • renovar visto',
+    variant: 'warning',
+    warningText: 'Visto a expirar!',
+  },
+};
+
+/**
+ * Exemplo demonstrando o card num estado de progresso contínuo
+ * (Ex: ainda em curso).
+ */
+export const InProgress: Story = {
+  args: {
+    stamp: {
+      color: theme.colors.primary,
+      title: 'DAKAR',
+      topLabel: 'SÉNÉGAL',
+      bottomLabels: ['NIVEAU B1', 'EM CURSO'],
+      size: 'md',
+      position: 'left',
+    },
+    countryCode: 'SN',
+    locationName: 'Dakar',
+    subtitle: 'B1 • a decorrer',
+  },
+};
+
+/**
+ * Grelha de vários cards para testar a escalabilidade visual
+ * e mostrar como se comportam lado a lado.
+ */
+export const Grid: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 24, justifyContent: 'center' }}>
+      <StampCard 
+        stamp={{
+          color: theme.colors.info,
+          title: 'PARIS',
+          topLabel: 'FRANCE',
+          bottomLabels: ['NIVEAU A2'],
+          size: 'md',
+          position: 'right',
+        }}
+        countryCode="FR"
+        locationName="Paris"
+        subtitle="A2 • concluído"
+      />
+      <StampCard 
+        stamp={{
+          color: theme.colors.success,
+          title: 'GENEVE',
+          topLabel: 'SUISSE',
+          bottomLabels: ['NIVEAU C1'],
+          size: 'md',
+          position: 'left',
+        }}
+        countryCode="CH"
+        locationName="Geneve"
+        subtitle="C1 • em curso"
+        variant="highlight"
+      />
+      <StampCard 
+        stamp={{
+          color: theme.colors.error,
+          title: 'ROMA',
+          topLabel: 'ITALIA',
+          bottomLabels: ['NIVEAU B2'],
+          size: 'md',
+          position: 'center',
+        }}
+        countryCode="IT"
+        locationName="Roma"
+        subtitle="B2 • atrasado"
+        variant="warning"
+        warningText="Atenção necessária"
+      />
+    </View>
+  ),
+};
+
+/**
+ * Exemplo demonstrando a passagem de uma \`width\` customizada.
+ * O cartão estica-se para preencher a largura fornecida, mantendo 
+ * os elementos internos perfeitamente centrados.
+ */
+export const CustomWidth: Story = {
+  args: {
+    width: 320,
+    stamp: {
+      color: theme.colors.primary,
+      title: 'LISBOA',
+      topLabel: 'PORTUGAL',
+      bottomLabels: ['NIVEAU C2'],
+      size: 'lg',
+      position: 'center',
+    },
+    countryCode: 'PT',
+    locationName: 'Lisboa',
+    subtitle: 'C2 • concluído',
+    variant: 'default',
+  },
+};
+
+/**
+ * Exemplo demonstrando a passagem de uma \`height\` customizada.
+ * O cartão estica-se verticalmente, e o carimbo afasta-se das informações
+ * graças ao \`justifyContent: 'space-between'\`.
+ */
+export const CustomHeight: Story = {
+  args: {
+    height: 450,
+    stamp: {
+      color: theme.colors.success,
+      title: 'ZURICH',
+      topLabel: 'SUISSE',
+      bottomLabels: ['NIVEAU B2'],
+      size: 'lg',
+      position: 'right',
+    },
+    countryCode: 'CH',
+    locationName: 'Zurich',
+    subtitle: 'B2 • concluído',
+    variant: 'default',
+  },
+};

package/src/components/DataDisplay/StampCard/StampCard.tsx

@@ -0,0 +1,196 @@
+import { View, StyleSheet } from 'react-native';
+import type { ViewStyle, DimensionValue } from 'react-native';
+import { Typography } from '../../Typography/Typography';
+import { Stamp } from '../Stamp/Stamp';
+import { Flag } from '../Flag/Flag';
+import { BaseCard } from '../../Cards/BaseCard/BaseCard';
+import { theme } from '../../../styles/theme';
+
+/**
+ * O \`StampCard\` é um cartão desenhado para exibir o progresso ou conquista num destino (carimbo).
+ * Usa o \`BaseCard\` como base, herda bordas e fundos do Design System, e disponibiliza 3 variantes visuais.
+ * 
+ * ### Exemplo de Uso
+ * \`\`\`tsx
+ * import { StampCard } from '@/components/DataDisplay/StampCard/StampCard';
+ * import { theme } from '@/styles/theme';
+ * 
+ * <StampCard 
+ *   stamp={{
+ *     color: theme.colors.error,
+ *     title: 'PARIS',
+ *     topLabel: 'FRANCE',
+ *     bottomLabels: ['NIVEAU A1', 'ABR 2026'],
+ *     size: 'md',
+ *     position: 'center',
+ *   }}
+ *   countryCode="FR"
+ *   locationName="Paris"
+ *   subtitle="A1 • concluído"
+ *   variant="warning"
+ *   warningText="Visto a expirar!"
+ * />
+ * \`\`\`
+ */
+export interface StampCardProps {
+  /** 
+   * Propriedades para configurar o carimbo que aparece dentro do card.
+   */
+  stamp: {
+    color: string;
+    title: string;
+    topLabel?: string;
+    bottomLabels?: string[];
+    size?: 'sm' | 'md' | 'lg';
+    position?: 'left' | 'center' | 'right';
+  };
+  /** 
+   * Código ISO do país ou nome para exibir a bandeira (ex: 'FR', 'France').
+   * Usa a componente Flag do sistema.
+   */
+  countryCode?: string;
+  /** 
+   * Nome do local que aparece ao lado da bandeira (ex: 'Lyon').
+   * Fica com a mesma cor principal do carimbo.
+   */
+  locationName: string;
+  /** 
+   * Subtítulo informativo (ex: 'A1 • concluído').
+   */
+  subtitle: string;
+  /**
+   * Largura customizada para o card.
+   */
+  width?: DimensionValue;
+  /**
+   * Altura customizada para o card.
+   */
+  height?: DimensionValue;
+  /**
+   * Variante visual do cartão:
+   * - `default`: Borda subtil neutra.
+   * - `highlight`: Borda espessa com a mesma cor do carimbo.
+   * - `warning`: Idêntico ao highlight, mas com badge a sobrepor no topo.
+   */
+  variant?: 'default' | 'highlight' | 'warning';
+  /**
+   * Texto para a badge de aviso (apenas renderizada se variant='warning').
+   * Opcional, por defeito será 'Visto a expirar!'.
+   */
+  warningText?: string;
+  /** 
+   * Estilo customizado para o card (opcional).
+   */
+  style?: ViewStyle;
+}
+
+export const StampCard = ({
+  stamp,
+  countryCode,
+  locationName,
+  subtitle,
+  width,
+  height,
+  variant = 'default',
+  warningText = 'Visto a expirar!',
+  style,
+}: StampCardProps) => {
+
+  const isHighlight = variant === 'highlight' || variant === 'warning';
+  const resolvedBorderColor = isHighlight ? stamp.color : theme.colors.brown[100];
+  const resolvedBorderWidth = isHighlight ? 4 : 2;
+
+  // Proteção contra inputs inválidos do painel do Storybook (ex: objetos vazios ou strings vazias)
+  const safeWidth = (typeof width === 'object' || width === '') ? undefined : width as DimensionValue;
+  const safeHeight = (typeof height === 'object' || height === '') ? undefined : height as DimensionValue;
+
+  return (
+    <BaseCard
+      width={safeWidth}
+      height={safeHeight}
+      borderColor={resolvedBorderColor}
+      borderWidth={resolvedBorderWidth}
+      borderRadius={theme.radius.xxl}
+      overflow="visible"
+      style={[
+        styles.card, 
+        variant === 'warning' && { paddingTop: 44 }, // Espaço extra para compensar a tag flutuante
+        style
+      ]}
+    >
+      
+      {variant === 'warning' ? (
+        <View style={[styles.warningBadge, { backgroundColor: stamp.color }]}>
+          <Typography variant="labelHeavy" color={theme.colors.white} style={{ textTransform: 'none' }}>
+            {warningText}
+          </Typography>
+        </View>
+      ) : null}
+
+      {/* Stamp Container */}
+      <View style={styles.stampContainer}>
+        <Stamp {...stamp} />
+      </View>
+
+      {/* Info Container */}
+      <View style={styles.infoContainer}>
+
+        <View style={styles.locationRow}>
+          {countryCode ? (
+            <Flag
+              countryCode={countryCode}
+              size={20}
+              style={{ marginRight: theme.spacing.xs }}
+            />
+          ) : null}
+          <Typography
+            variant="h5"
+            color={stamp.color}
+          >
+            {locationName}
+          </Typography>
+        </View>
+
+        <Typography
+          variant="subtitle1"
+          color={theme.colors.brown[500]}
+          style={{ marginTop: 2 }}
+        >
+          {subtitle}
+        </Typography>
+
+      </View>
+
+    </BaseCard>
+  );
+};
+
+const styles = StyleSheet.create({
+  card: {
+    padding: theme.spacing.space8,
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    alignSelf: 'flex-start', // Adapta-se ao conteúdo por defeito
+  },
+  warningBadge: {
+    position: 'absolute',
+    top: -18, // Sobe para quebrar a borda superior (ajustado para a nova borda branca)
+    alignSelf: 'center',
+    paddingHorizontal: 16,
+    paddingVertical: 6,
+    borderRadius: theme.radius.full,
+    zIndex: 10,
+    borderWidth: 4,
+    borderColor: theme.colors.white,
+  },
+  stampContainer: {
+    marginBottom: theme.spacing.space6,
+  },
+  infoContainer: {
+    alignItems: 'center',
+  },
+  locationRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+});

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

@@ -1,4 +1,5 @@
-import { View, StyleSheet } from 'react-native';
+import React, { useEffect, useRef } from 'react';
+import { View, StyleSheet, Animated, Easing } from 'react-native';
 import type { ViewStyle } from 'react-native';
 import { useResponsive } from '../../../hooks/useResponsive';
 import { getCountryTheme } from '../../../styles/countryThemes';
@@ -27,6 +28,8 @@ export interface CountryHeaderProps {
    * O developer deve passar o \`insets.top\` gerado pelo \`react-native-safe-area-context\`.
    */
   safeAreaTop?: number;
+  /** Se deve ocultar a barra de progresso com animação */
+  hideProgressBar?: boolean;
   /** Estilos customizados opcionais para o container principal */
   style?: ViewStyle | ViewStyle[];
 }
@@ -40,11 +43,23 @@ export const CountryHeader = ({
   progressSegments = 4,
   onBackPress,
   safeAreaTop = 0,
+  hideProgressBar = false,
   style,
 }: CountryHeaderProps) => {
   const { scale, scaleText } = useResponsive();
   const countryTheme = getCountryTheme(countryCode);
 
+  const progressAnim = useRef(new Animated.Value(hideProgressBar ? 0 : 1)).current;
+
+  useEffect(() => {
+    Animated.timing(progressAnim, {
+      toValue: hideProgressBar ? 0 : 1,
+      duration: 300,
+      easing: Easing.inOut(Easing.ease),
+      useNativeDriver: false,
+    }).start();
+  }, [hideProgressBar, progressAnim]);
+
   return (
     <View style={[styles.container, { backgroundColor: countryTheme.bg }, style]}>
       {/* Círculo decorativo de fundo */}
@@ -87,13 +102,24 @@ export const CountryHeader = ({
         </View>
 
         {/* Progress Bar */}
-        <ProgressBar
-          progress={progress}
-          segments={progressSegments}
-          size="sm"
-          fillColor={countryTheme.progressFill}
-          trackColor={countryTheme.progressTrack}
-        />
+        <Animated.View
+          style={{
+            opacity: progressAnim,
+            height: progressAnim.interpolate({
+              inputRange: [0, 1],
+              outputRange: [0, 12],
+            }),
+            overflow: 'hidden',
+          }}
+        >
+          <ProgressBar
+            progress={progress}
+            segments={progressSegments}
+            size="sm"
+            fillColor={countryTheme.progressFill}
+            trackColor={countryTheme.progressTrack}
+          />
+        </Animated.View>
       </View>
     </View>
   );

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

@@ -67,6 +67,13 @@ export const MapScreen = () => {
       control: 'radio',
       options: ['continuous', 'segmented'],
     },
+    variant: {
+      control: 'radio',
+      options: ['default', 'minimal'],
+    },
+    notificationCount: {
+      control: 'number',
+    },
   },
 } satisfies Meta<typeof RouteHeader>;
 
@@ -74,6 +81,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Continuous: Story = {
+  render: (args) => <RouteHeader {...args} />,
   args: {
     routeLabel: 'ROTA DA FRANCOFONIA',
     countryCode: 'SN',
@@ -88,6 +96,7 @@ export const Continuous: Story = {
 };
 
 export const Segmented: Story = {
+  render: (args) => <RouteHeader {...args} />,
   args: {
     routeLabel: 'ROTA DA FRANCOFONIA',
     stepLabel: 'paragem 5 de 8',
@@ -102,3 +111,22 @@ export const Segmented: Story = {
     safeAreaTop: 20,
   },
 };
+
+export const Minimal: Story = {
+  render: (args) => <RouteHeader {...args} />,
+  args: {
+    routeLabel: 'Francofonia',
+    stepLabel: '5/8',
+    countryCode: 'SN',
+    title: 'Dakar',
+    subtitle: 'B2',
+    progressText: '', 
+    progressSubText: '',
+    progress: 0.625,
+    progressType: 'segmented',
+    totalSegments: 8,
+    variant: 'minimal',
+    notificationCount: 3,
+    safeAreaTop: 20,
+  },
+};