@xetwa/design-system 1.0.48 → 1.0.50

package/package.json

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

package/src/components/Buttons/Chip/Chip.tsx

@@ -1,5 +1,5 @@
 import React, { useRef } from 'react';
-import { Pressable, StyleSheet, Animated } from 'react-native';
+import { Pressable, StyleSheet, Animated, View } from 'react-native';
 import type { ViewStyle } from 'react-native';
 import { Typography } from '../../Typography/Typography';
 import { useResponsive } from '../../../hooks/useResponsive';
@@ -8,6 +8,8 @@ import { theme } from '../../../styles/theme';
 export interface ChipProps {
   /** Texto a ser exibido no chip */
   label: string;
+  /** Elemento extra à esquerda (ex: ícone, flag) */
+  leftElement?: React.ReactNode;
   /** Função a executar ao pressionar */
   onPress?: () => void;
   /** Tamanho do chip (afeta paddings e fonte) */
@@ -30,6 +32,7 @@ export interface ChipProps {
  */
 export const Chip = ({
   label,
+  leftElement,
   onPress,
   size = 'md',
   backgroundColor = theme.colors.white,
@@ -104,6 +107,7 @@ export const Chip = ({
           style,
         ]}
       >
+        {leftElement && <View style={{ marginRight: 6 }}>{leftElement}</View>}
         <Typography variant={typographyVariant} color={textColor} style={{ textAlign: 'center' }}>
           {label}
         </Typography>

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

@@ -0,0 +1,67 @@
+// eslint-disable-next-line storybook/no-renderer-packages
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+import { View } from 'react-native';
+import { CircularProgress } from './CircularProgress';
+import { Typography } from '../../Typography/Typography';
+
+const meta = {
+  title: 'Components/DataDisplay/CircularProgress',
+  component: CircularProgress,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'O **CircularProgress** exibe o progresso de uma determinada métrica num formato circular (usando SVG). Permite configurar cores, espessura da linha e incluir texto ou filhos personalizados no centro.\n\n### Exemplo de Uso\n```tsx\n<CircularProgress progress={50} size={120} strokeWidth={12} text="50%" />\n```',
+      }
+    }
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    progress: { control: { type: 'range', min: 0, max: 100 } },
+    size: { control: 'number' },
+    strokeWidth: { control: 'number' },
+    color: { control: 'color' },
+    trackColor: { control: 'color' },
+    text: { control: 'text' },
+  },
+} satisfies Meta<typeof CircularProgress>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    progress: 45,
+    size: 100,
+    strokeWidth: 10,
+    text: '45%',
+  },
+};
+
+export const CustomTypography: Story = {
+  args: {
+    progress: 75,
+    size: 140,
+    strokeWidth: 12,
+  },
+  render: (args) => (
+    <CircularProgress {...args}>
+      <View style={{ alignItems: 'center' }}>
+        <Typography variant="h2">75%</Typography>
+        <Typography variant="small" color="#9a8478">Concluído</Typography>
+      </View>
+    </CircularProgress>
+  ),
+};
+
+export const Sizes: Story = {
+  args: { progress: 30 },
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 20, alignItems: 'center' }}>
+      <CircularProgress progress={15} size={50} strokeWidth={6} text="15%" />
+      <CircularProgress progress={30} size={80} strokeWidth={8} text="30%" />
+      <CircularProgress progress={85} size={120} strokeWidth={12} text="85%" />
+    </View>
+  ),
+};

package/src/components/DataDisplay/CircularProgress/CircularProgress.tsx

@@ -0,0 +1,92 @@
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import Svg, { Circle } from 'react-native-svg';
+import { theme } from '../../../styles/theme';
+import { Typography } from '../../Typography/Typography';
+
+export interface CircularProgressProps {
+  /** O valor do progresso (0 a 100) */
+  progress: number;
+  /** Tamanho total (largura/altura) do círculo */
+  size?: number;
+  /** Grossura da linha */
+  strokeWidth?: number;
+  /** Cor da linha de progresso */
+  color?: string;
+  /** Cor da linha de fundo (track) */
+  trackColor?: string;
+  /** Texto opcional para aparecer no centro */
+  text?: string;
+  /** Permite customizar o conteúdo central, sobrepõe a prop text */
+  children?: React.ReactNode;
+}
+
+export const CircularProgress = ({
+  progress,
+  size = 100,
+  strokeWidth = 10,
+  color = theme.colors.primary,
+  trackColor = theme.colors.primaryLight,
+  text,
+  children,
+}: CircularProgressProps) => {
+  const radius = (size - strokeWidth) / 2;
+  const circumference = radius * 2 * Math.PI;
+  // Limita o progresso entre 0 e 100
+  const safeProgress = Math.min(Math.max(progress, 0), 100);
+  const strokeDashoffset = circumference - (safeProgress / 100) * circumference;
+
+  return (
+    <View style={[styles.container, { width: size, height: size }]}>
+      <Svg width={size} height={size} style={styles.svg}>
+        {/* Fundo do Progresso (Track) */}
+        <Circle
+          stroke={trackColor}
+          fill="none"
+          cx={size / 2}
+          cy={size / 2}
+          r={radius}
+          strokeWidth={strokeWidth}
+        />
+        {/* Linha de Progresso */}
+        <Circle
+          stroke={color}
+          fill="none"
+          cx={size / 2}
+          cy={size / 2}
+          r={radius}
+          strokeWidth={strokeWidth}
+          strokeDasharray={circumference}
+          strokeDashoffset={strokeDashoffset}
+          strokeLinecap="round"
+        />
+      </Svg>
+
+      {/* Conteúdo Central */}
+      <View style={styles.contentContainer}>
+        {children ? (
+          children
+        ) : text ? (
+          <Typography variant="h3" color={theme.colors.brown[800]}>
+            {text}
+          </Typography>
+        ) : null}
+      </View>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  svg: {
+    transform: [{ rotate: '-90deg' }],
+  },
+  contentContainer: {
+    position: 'absolute',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});

package/src/components/DataDisplay/ProgressBar/ProgressBar.tsx

@@ -53,7 +53,7 @@ export const ProgressBar = ({
   }, [progress, animatedProgress]);
 
   const sizeStyles = {
-    xs: { height: 8, borderRadius: 5 },
+    xs: { height: 8, borderRadius: 4 },
     sm: { height: 12, borderRadius: 7 },
     md: { height: 16, borderRadius: 9 },
   }[size === 'lg' ? 'md' : size] || { height: 16, borderRadius: 9 };

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

@@ -0,0 +1,153 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+import { View } from 'react-native';
+import { Stamp } from './Stamp';
+import { theme } from '../../../styles/theme';
+
+const meta = {
+  title: 'Components/DataDisplay/Stamp',
+  component: Stamp,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `O componente **Stamp** reproduz visualmente um "carimbo de passaporte". É usado no ecrã da rota para representar módulos que estão em curso, concluídos, ou localidades visitadas.
+
+### Características
+- **Cores Livres:** Pode passar a propriedade \`color\` com qualquer cor (HEX, RGB) e o fundo é gerado automaticamente.
+- **Textos Flexíveis:** O carimbo aceita \`topLabel\`, \`title\` e \`bottomLabels\` para escrever o que quiser.
+## Notas de Uso
+- O componente possui três tamanhos pré-definidos: **sm** (100px), **md** (140px, padrão), e **lg** (180px).
+- Cada tamanho tem a sua própria escala de tipografia matematicamente calculada para garantir que as letras nunca ficam desproporcionais ao círculo.
+- Se a palavra do título for demasiado comprida, o tamanho de letra ajusta-se automaticamente (\`adjustsFontSizeToFit\`) sem quebrar o carimbo.
+
+### Exemplo de Uso
+\`\`\`tsx
+import { Stamp } from '@xetwa/design-system';
+
+// Carimbo estilo Paris (Azul)
+<Stamp 
+  topLabel="REPUBLIQUE"
+  title="PARIS"
+  bottomLabels={['NIVEAU A1', 'MAR 2026']} 
+  color="#2a6fc2"
+/>
+
+// Carimbo estilo Dakar com inclinação à direita
+<Stamp 
+  topLabel="SÉNÉGAL"
+  title="DAKAR" 
+  bottomLabels={['NIVEAU B1', 'EM CURSO']} 
+  color="#f2974b"
+  position="right"
+/>
+\`\`\`
+`,
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <View style={{ padding: 40, backgroundColor: theme.colors.brown[50], alignItems: 'center', justifyContent: 'center' }}>
+        <Story />
+      </View>
+    ),
+  ],
+  tags: ['autodocs'],
+  argTypes: {
+    color: {
+      control: 'color',
+      description: 'Cor principal do carimbo (texto e borda).',
+    },
+    size: {
+      control: 'radio',
+      options: ['sm', 'md', 'lg'],
+      description: 'Tamanho pré-definido do carimbo.',
+    },
+    bgColor: {
+      control: 'color',
+      description: 'Cor de fundo do círculo interno (opcional).',
+    },
+    position: {
+      control: 'radio',
+      options: ['left', 'center', 'right'],
+      description: 'Inclinação do carimbo.',
+    },
+  },
+} satisfies Meta<typeof Stamp>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Carimbo Laranja, estilo Dakar (Em curso)
+ */
+export const Dakar: Story = {
+  render: (args) => <Stamp {...args} />,
+  args: {
+    topLabel: 'SÉNÉGAL',
+    title: 'DAKAR',
+    bottomLabels: ['NIVEAU B1', 'EM CURSO'],
+    color: theme.colors.primary,
+    position: 'left',
+  },
+};
+
+/**
+ * Carimbo Azul, estilo Paris (Concluído antigo)
+ */
+export const Paris: Story = {
+  render: (args) => <Stamp {...args} />,
+  args: {
+    topLabel: 'REPUBLIQUE',
+    title: 'PARIS',
+    bottomLabels: ['NIVEAU A1', 'MAR 2026'],
+    color: theme.colors.info,
+    position: 'right',
+  },
+};
+
+/**
+ * Carimbo Vermelho, estilo Lyon (Concluído recente)
+ */
+export const Lyon: Story = {
+  render: (args) => <Stamp {...args} />,
+  args: {
+    topLabel: 'FRANCE',
+    title: 'LYON',
+    bottomLabels: ['NIVEAU A1', 'ABR 2026'],
+    color: theme.colors.error,
+    position: 'center',
+  },
+};
+
+/**
+ * Demonstra a capacidade do componente se ajustar perfeitamente a diferentes escalas.
+ */
+export const Scalability: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 24, justifyContent: 'center', alignItems: 'center' }}>
+      <Stamp 
+        color="#8e44ad" 
+        title="GENEVE" 
+        topLabel="SUISSE"
+        size="sm"
+        bottomLabels={['NIVEAU A2']} 
+      />
+      <Stamp 
+        color="#d35400" 
+        title="MONTREAL" 
+        topLabel="CANADA"
+        size="md"
+        bottomLabels={['NIVEAU B1']} 
+      />
+      <Stamp 
+        color="#16a085" 
+        title="KINSHASA" 
+        topLabel="RD CONGO"
+        size="lg"
+        bottomLabels={['NIVEAU C2']} 
+      />
+    </View>
+  ),
+};

package/src/components/DataDisplay/Stamp/Stamp.tsx

@@ -0,0 +1,173 @@
+import React from 'react';
+import { View, StyleSheet, Platform } from 'react-native';
+import type { ViewStyle } from 'react-native';
+import { Typography } from '../../Typography/Typography';
+
+export interface StampProps {
+  /** 
+   * Texto superior (ex: 'REPUBLIQUE', 'FRANCE', 'SÉNÉGAL').
+   */
+  topLabel?: string;
+  /** 
+   * Título central em destaque (ex: 'PARIS', 'LYON', 'DAKAR').
+   */
+  title: string;
+  /** 
+   * Textos inferiores, normalmente nível e data (ex: ['NIVEAU A1', 'MAR 2026']).
+   */
+  bottomLabels?: string[];
+  /** 
+   * Cor principal do carimbo (aplicada ao texto e borda).
+   */
+  color: string;
+  /** 
+   * Cor de fundo do círculo interno. Se não for fornecida, 
+   * calculará automaticamente 10% de opacidade se a cor principal for HEX.
+   */
+  bgColor?: string;
+  /**
+   * Tamanho do carimbo.
+   * - `sm`: 100px (ideal para ícones/badges)
+   * - `md`: 140px (tamanho padrão)
+   * - `lg`: 180px (grande destaque)
+   * @default 'md'
+   */
+  size?: 'sm' | 'md' | 'lg';
+  /** 
+   * Posição (inclinação) do carimbo.
+   * - `left`: Inclinado para a esquerda (-8 graus)
+   * - `center`: Direito (0 graus)
+   * - `right`: Inclinado para a direita (8 graus)
+   * @default 'left'
+   */
+  position?: 'left' | 'center' | 'right';
+  /** 
+   * Estilos adicionais para o contentor exterior.
+   */
+  style?: ViewStyle | ViewStyle[];
+}
+
+/**
+ * **Stamp (Carimbo)**
+ * 
+ * Componente visual para representar módulos ou cidades concluídas/em curso na rota de aprendizagem.
+ * Possui um aspeto autêntico de carimbo de passaporte, com borda tracejada e textos proporcionais.
+ */
+export const Stamp = ({
+  topLabel,
+  title,
+  bottomLabels = [],
+  color,
+  bgColor,
+  size = 'md',
+  position = 'left',
+  style,
+}: StampProps) => {
+
+  const SIZE_MAP = {
+    sm: { base: 100, top: 9, title: 18, bottom1: 7, bottom2: 6 },
+    md: { base: 140, top: 11, title: 22, bottom1: 9, bottom2: 7 },
+    lg: { base: 180, top: 14, title: 26, bottom1: 11, bottom2: 8 },
+  };
+
+  const currentSize = SIZE_MAP[size];
+  const BASE_SIZE = currentSize.base;
+
+  // Determinar inclinação: aplicamos a rotação ao carimbo inteiro!
+  const rotation = position === 'right' ? 12 : position === 'center' ? 0 : -12;
+
+  // Determinar cor de fundo (injetar 10% de opacidade se for HEX)
+  const isHex = color.startsWith('#') && (color.length === 7 || color.length === 4);
+  const calculatedBgColor = bgColor || (isHex ? `${color}1A` : 'transparent');
+
+  // Cálculos dinâmicos de proporção baseados no tamanho
+  const innerSize = BASE_SIZE * 0.82;
+  const borderWidth = Math.max(2.5, BASE_SIZE * 0.035);
+
+  return (
+    <View style={[{ alignSelf: 'flex-start', transform: [{ rotate: `${rotation}deg` }] }, style]}>
+      <View
+        style={[
+          styles.outerCircle,
+          {
+            width: BASE_SIZE,
+            height: BASE_SIZE,
+            borderRadius: BASE_SIZE / 2,
+            borderColor: color,
+            borderWidth: borderWidth,
+          },
+        ]}
+      >
+        <View style={[
+          styles.innerCircle,
+          {
+            width: innerSize,
+            height: innerSize,
+            borderRadius: innerSize / 2,
+            backgroundColor: calculatedBgColor,
+          }
+        ]}>
+
+          {topLabel ? (
+            <View style={{ position: 'absolute', top: '22%', width: '100%', alignItems: 'center' }}>
+              <Typography
+                color={color}
+                variant="stampTop"
+                style={{ textAlign: 'center', fontSize: currentSize.top, lineHeight: currentSize.top + 2 }}
+              >
+                {topLabel}
+              </Typography>
+            </View>
+          ) : null}
+
+          <View style={[styles.contentWrapper, { paddingHorizontal: BASE_SIZE * 0.2 }]}>
+            <Typography
+              color={color}
+              variant="stampTitle"
+              style={{ textAlign: 'center', fontSize: currentSize.title, lineHeight: currentSize.title + 4 }}
+            >
+              {title}
+            </Typography>
+          </View>
+
+          {bottomLabels.length > 0 ? (
+            <View style={{ position: 'absolute', bottom: '15%', width: '100%', alignItems: 'center' }}>
+              {bottomLabels.map((label, index) => (
+                <Typography
+                  key={index}
+                  color={color}
+                  variant={index === 0 ? "stampBottom1" : "stampBottom2"}
+                  style={{
+                    marginTop: index > 0 ? 2 : 0,
+                    textAlign: 'center',
+                    fontSize: index === 0 ? currentSize.bottom1 : currentSize.bottom2,
+                    lineHeight: index === 0 ? currentSize.bottom1 + 2 : currentSize.bottom2 + 2,
+                  }}
+                >
+                  {label}
+                </Typography>
+              ))}
+            </View>
+          ) : null}
+
+        </View>
+      </View>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  outerCircle: {
+    borderStyle: 'dashed',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  innerCircle: {
+    overflow: 'hidden',
+  },
+  contentWrapper: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+  }
+});