@xetwa/design-system 1.0.2

package/src/components/Mascots/Yaya/Yaya.stories.tsx

@@ -0,0 +1,98 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Yaya } from './Yaya';
+
+const meta = {
+  title: 'Mascots/Yaya',
+  component: Yaya,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: [
+        'neutra',
+        'feliz',
+        'errou',
+        'acertou',
+        'celebrar',
+        'dormir',
+        'falar',
+        'pensar',
+        'surpresa',
+      ],
+      description: 'A expressão ou estado da mascote Yaya.',
+    },
+    size: {
+      control: { type: 'range', min: 50, max: 500, step: 10 },
+      description: 'O tamanho do componente (largura e altura em pixels).',
+    },
+  },
+} satisfies Meta<any>;
+
+export default meta;
+type Story = StoryObj<any>;
+
+export const Default: Story = {
+  args: {
+    variant: 'feliz',
+    size: 200,
+  },
+};
+
+export const Neutra: Story = {
+  args: {
+    variant: 'neutra',
+    size: 200,
+  },
+};
+
+export const Errou: Story = {
+  args: {
+    variant: 'errou',
+    size: 200,
+  },
+};
+
+export const Acertou: Story = {
+  args: {
+    variant: 'acertou',
+    size: 200,
+  },
+};
+
+export const Celebrar: Story = {
+  args: {
+    variant: 'celebrar',
+    size: 200,
+  },
+};
+
+export const Dormir: Story = {
+  args: {
+    variant: 'dormir',
+    size: 200,
+  },
+};
+
+export const Falar: Story = {
+  args: {
+    variant: 'falar',
+    size: 200,
+  },
+};
+
+export const Pensar: Story = {
+  args: {
+    variant: 'pensar',
+    size: 200,
+  },
+};
+
+export const Surpresa: Story = {
+  args: {
+    variant: 'surpresa',
+    size: 200,
+  },
+};

package/src/components/Mascots/Yaya/Yaya.tsx

@@ -0,0 +1,233 @@
+import React from 'react';
+import Svg, { Path, Rect, Circle, Ellipse, G, Text as SvgText } from 'react-native-svg';
+
+export type YayaVariant =
+  | 'neutra'
+  | 'feliz'
+  | 'errou'
+  | 'acertou'
+  | 'celebrar'
+  | 'dormir'
+  | 'falar'
+  | 'pensar'
+  | 'surpresa';
+
+export interface YayaProps {
+  /**
+   * A expressão ou estado da mascote Yaya.
+   * @default 'feliz'
+   */
+  variant?: YayaVariant;
+  /**
+   * O tamanho do componente (largura e altura em pixels).
+   * @default 200
+   */
+  size?: number;
+  /**
+   * Se verdadeiro, renderiza apenas o rosto/cabeça da mascote em formato Avatar.
+   * Útil para exibir em caixas de feedback.
+   * @default false
+   */
+  avatarOnly?: boolean;
+}
+
+/**
+ * Componente Yaya - A mascote assistente do Xetlingo.
+ * 
+ * Este componente renderiza de forma estática, vetorial e performática as diferentes expressões da Yaya.
+ * É compatível tanto com React Native (iOS/Android) quanto com React Native Web.
+ * 
+ * @example
+ * ```tsx
+ * // Yaya feliz com tamanho padrão (200px)
+ * <Yaya variant="feliz" />
+ * 
+ * // Yaya celebrando com 150px de tamanho
+ * <Yaya variant="celebrar" size={150} />
+ * 
+ * // Apenas o avatar para usar num bottom sheet
+ * <Yaya variant="acertou" avatarOnly size={64} />
+ * ```
+ */
+export const Yaya: React.FC<YayaProps> = ({ variant = 'feliz', size = 200, avatarOnly = false }) => {
+  const renderFace = () => {
+    switch (variant) {
+      case 'neutra':
+        return (
+          <>
+            <Path d="M78 81 l-5 -3 M122 81 l5 -3" stroke="#15100d" strokeWidth={2} strokeLinecap="round" />
+            <Ellipse cx={86} cy={88} rx={8} ry={10} fill="#fff" />
+            <Ellipse cx={114} cy={88} rx={8} ry={10} fill="#fff" />
+            <Circle cx={87} cy={90} r={4.3} fill="#15100d" />
+            <Circle cx={115} cy={90} r={4.3} fill="#15100d" />
+            <Circle cx={85} cy={86} r={1.6} fill="#fff" />
+            <Circle cx={113} cy={86} r={1.6} fill="#fff" />
+            <Path d="M93 104 Q100 109 107 104" fill="none" stroke="#cf7a30" strokeWidth={3} strokeLinecap="round" />
+          </>
+        );
+
+      case 'feliz':
+        return (
+          <>
+            <Path d="M78 81 l-5 -3 M122 81 l5 -3" stroke="#15100d" strokeWidth={2} strokeLinecap="round" />
+            <Ellipse cx={86} cy={88} rx={8} ry={10} fill="#fff" />
+            <Ellipse cx={114} cy={88} rx={8} ry={10} fill="#fff" />
+            <Circle cx={87} cy={90} r={4.3} fill="#15100d" />
+            <Circle cx={115} cy={90} r={4.3} fill="#15100d" />
+            <Circle cx={85} cy={86} r={1.6} fill="#fff" />
+            <Circle cx={113} cy={86} r={1.6} fill="#fff" />
+            <Path d="M91 103 Q100 113 109 103 Z" fill="#f2974b" />
+          </>
+        );
+
+      case 'errou':
+        return (
+          <>
+            <Path d="M76 82 l11 4 M124 82 l-11 4" stroke="#15100d" strokeWidth={2.2} strokeLinecap="round" />
+            <Ellipse cx={86} cy={91} rx={7.5} ry={9} fill="#fff" />
+            <Ellipse cx={114} cy={91} rx={7.5} ry={9} fill="#fff" />
+            <Circle cx={87} cy={93} r={4} fill="#15100d" />
+            <Circle cx={115} cy={93} r={4} fill="#15100d" />
+            <Path d="M94 107 Q100 102 106 107" stroke="#cf7a30" strokeWidth={3} fill="none" strokeLinecap="round" />
+            <Path d="M133 86 q3.6 5 0 9 q-3.6 -4 0 -9 Z" fill="#7ab8e0" />
+            {!avatarOnly && (
+              <G transform="translate(150, 58)">
+                <Circle r={16} fill="#cf5b48" />
+                <Path d="M-6 -6 l12 12 M6 -6 l-12 12" stroke="#fff" strokeWidth={3.5} strokeLinecap="round" />
+              </G>
+            )}
+          </>
+        );
+
+      case 'acertou':
+        return (
+          <>
+            <Path d="M79 90 Q86 82 93 90" stroke="#15100d" strokeWidth={3.2} fill="none" strokeLinecap="round" />
+            <Path d="M107 90 Q114 82 121 90" stroke="#15100d" strokeWidth={3.2} fill="none" strokeLinecap="round" />
+            <Path d="M91 103 Q100 113 109 103 Z" fill="#f2974b" />
+            {avatarOnly ? (
+              <G>
+                <Path d="M55 75 Q60 75 60 70 Q60 75 65 75 Q60 75 60 80 Q60 75 55 75 Z" fill="#f2974b" />
+                <Path d="M68 60 Q70 60 70 58 Q70 60 72 60 Q70 60 70 62 Q70 60 68 60 Z" fill="#f2974b" />
+              </G>
+            ) : (
+              <G transform="translate(150, 58)">
+                <Circle r={16} fill="#16915a" />
+                <Path d="M-7 0 l4 5 9 -10" stroke="#fff" strokeWidth={3.5} fill="none" strokeLinecap="round" strokeLinejoin="round" />
+              </G>
+            )}
+          </>
+        );
+
+      case 'celebrar':
+        return (
+          <>
+            <Path d="M79 90 Q86 82 93 90" stroke="#15100d" strokeWidth={3.2} fill="none" strokeLinecap="round" />
+            <Path d="M107 90 Q114 82 121 90" stroke="#15100d" strokeWidth={3.2} fill="none" strokeLinecap="round" />
+            <Path d="M90 102 Q100 117 110 102 Q100 108 90 102 Z" fill="#fff" />
+            <Path d="M92 103 Q100 114 108 103" fill="#f2974b" />
+          </>
+        );
+
+      case 'dormir':
+        return (
+          <>
+            <Path d="M78 89 Q86 95 94 89" stroke="#15100d" strokeWidth={3} fill="none" strokeLinecap="round" />
+            <Path d="M106 89 Q114 95 122 89" stroke="#15100d" strokeWidth={3} fill="none" strokeLinecap="round" />
+            <Circle cx={100} cy={105} r={3} fill="none" stroke="#cf7a30" strokeWidth={2.5} />
+            <SvgText x="50" y="50" fontFamily="sans-serif" fontWeight="700" fontSize={15} fill="#9a8478">z</SvgText>
+            <SvgText x="50" y="50" fontFamily="sans-serif" fontWeight="700" fontSize={20} fill="#9a8478">Z</SvgText>
+          </>
+        );
+
+      case 'falar':
+        return (
+          <>
+            <Ellipse cx={86} cy={88} rx={8} ry={10} fill="#fff" />
+            <Ellipse cx={114} cy={88} rx={8} ry={10} fill="#fff" />
+            <Circle cx={87} cy={90} r={4.3} fill="#15100d" />
+            <Circle cx={115} cy={90} r={4.3} fill="#15100d" />
+            <Circle cx={85} cy={86} r={1.6} fill="#fff" />
+            <Circle cx={113} cy={86} r={1.6} fill="#fff" />
+            <Ellipse cx={100} cy={106} rx={6.5} ry={6} fill="#f2974b" />
+            <Ellipse cx={100} cy={104} rx={3.5} ry={1.6} fill="#fff" opacity={0.5} />
+          </>
+        );
+
+      case 'pensar':
+        return (
+          <>
+            <Ellipse cx={86} cy={88} rx={8} ry={10} fill="#fff" />
+            <Ellipse cx={114} cy={88} rx={8} ry={10} fill="#fff" />
+            <Circle cx={88} cy={84} r={4} fill="#15100d" />
+            <Circle cx={116} cy={84} r={4} fill="#15100d" />
+            <Path d="M93 105 L105 103" stroke="#cf7a30" strokeWidth={3} fill="none" strokeLinecap="round" />
+            <SvgText x="50" y="50" fontFamily="sans-serif" fontWeight="700" fontSize={28} fill="#f2974b">?</SvgText>
+          </>
+        );
+
+      case 'surpresa':
+        return (
+          <>
+            <Circle cx={86} cy={88} r={10} fill="#fff" />
+            <Circle cx={114} cy={88} r={10} fill="#fff" />
+            <Circle cx={86} cy={89} r={5} fill="#15100d" />
+            <Circle cx={114} cy={89} r={5} fill="#15100d" />
+            <Circle cx={84} cy={86} r={2} fill="#fff" />
+            <Circle cx={112} cy={86} r={2} fill="#fff" />
+            <Ellipse cx={100} cy={105} rx={6} ry={7} fill="#f2974b" />
+          </>
+        );
+
+      default:
+        return null;
+    }
+  };
+
+  return (
+    <Svg
+      width={size}
+      height={size}
+      viewBox={avatarOnly ? "50 32 100 100" : "0 0 200 200"}
+      role="img"
+      aria-label={`Mascote Yaya: ${variant}`}
+    >
+      {!avatarOnly && (
+        <>
+          {/* Corpo base */}
+          <Path d="M72 170 Q70 124 100 124 Q130 124 128 170 Z" fill="#f2974b" />
+          <Path d="M82 128 L120 150" stroke="#3f2620" strokeWidth={3} fill="none" />
+
+          {/* Dispositivo / Tablet lateral */}
+          <Rect x={112} y={148} width={22} height={18} rx={5} fill="#cf7a30" />
+          <Rect x={118} y={144} width={10} height={6} rx={3} fill="none" stroke="#3f2620" strokeWidth={2} />
+
+          {/* Colar / Cachecol */}
+          <Path d="M76 122 Q100 138 124 122 L124 130 Q100 146 76 130 Z" fill="#e0662e" />
+          <Circle cx={88} cy={129} r={1.5} fill="#fbe6cf" />
+          <Circle cx={100} cy={133} r={1.5} fill="#fbe6cf" />
+          <Circle cx={112} cy={129} r={1.5} fill="#fbe6cf" />
+
+          {/* Orelhas / Cabelo lateral */}
+          <Path d="M62 96 q-6 18 4 30 q8 -10 6 -26 Z" fill="#3f2620" />
+          <Path d="M138 96 q6 18 -4 30 q-8 -10 -6 -26 Z" fill="#3f2620" />
+        </>
+      )}
+
+      {/* Cabeça (Fundo) */}
+      <Circle cx={100} cy={88} r={40} fill="#51332d" />
+
+      {/* Bochechas */}
+      <Circle cx={74} cy={101} r={6} fill="#f2974b" opacity={0.4} />
+      <Circle cx={126} cy={101} r={6} fill="#f2974b" opacity={0.4} />
+
+      {/* Expressão Facial */}
+      {renderFace()}
+
+      {/* Antena / Chapéu superior */}
+      <Ellipse cx={100} cy={54} rx={33} ry={13} fill="#f2974b" />
+      <Ellipse cx={100} cy={50} rx={30} ry={10} fill="#ff9f57" />
+      <Circle cx={100} cy={42} r={3.6} fill="#f2974b" />
+    </Svg>
+  );
+};

package/src/components/Navigation/BottomTabBar/BottomTabBar.stories.tsx

@@ -0,0 +1,68 @@
+// eslint-disable-next-line storybook/no-renderer-packages
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { View } from 'react-native';
+import { BottomTabBar } from './BottomTabBar';
+import { theme } from '../../../styles/theme';
+import { Home, BookOpen, Trophy, User, PlusCircle } from 'lucide-react-native';
+
+const meta = {
+  title: 'Components/Navigation/BottomTabBar',
+  component: BottomTabBar,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: 'A **BottomTabBar** é a barra de navegação principal da aplicação, fixa no fundo do ecrã.\n\nContém as secções vitais (Aprender, Revisão, Social, Perfil) e integra animações de escala quando um botão é pressionado.\n\n### Exemplo de Uso\n```tsx\nconst [activeTab, setActiveTab] = useState("home");\n\nreturn (\n  <BottomTabBar \n    currentTab={activeTab}\n    onTabPress={setActiveTab}\n    safeAreaBottom={20}\n  />\n)\n```',
+      }
+    }
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <View style={{ flex: 1, backgroundColor: theme.colors.cream, justifyContent: 'flex-end', minHeight: 200 }}>
+        <Story />
+      </View>
+    ),
+  ],
+} satisfies Meta<any>;
+
+export default meta;
+type Story = StoryObj<any>;
+
+const defaultTabs = [
+  { id: 'inicio', label: 'Início', icon: Home },
+  { id: 'passaporte', label: 'Passaporte', icon: BookOpen },
+  { id: 'aulas', label: 'Aulas', icon: Trophy },
+  { id: 'perfil', label: 'Perfil', icon: User },
+];
+
+const fiveTabs = [
+  ...defaultTabs,
+  { id: 'extra', label: 'Extra Tab', icon: PlusCircle },
+];
+
+const InteractiveTabBar = ({ tabs, safeAreaBottom }: { tabs: any[], safeAreaBottom?: number }) => {
+  const [activeTab, setActiveTab] = useState(tabs[0].id);
+
+  return (
+    <BottomTabBar
+      tabs={tabs}
+      activeTabId={activeTab}
+      onTabChange={setActiveTab}
+      safeAreaBottom={safeAreaBottom}
+    />
+  );
+};
+
+export const DefaultMobile: Story = {
+  render: () => <InteractiveTabBar tabs={defaultTabs} />,
+};
+
+export const WithSafeAreaInset: Story = {
+  render: () => <InteractiveTabBar tabs={defaultTabs} safeAreaBottom={34} />,
+};
+
+export const ScalabilityFiveTabs: Story = {
+  render: () => <InteractiveTabBar tabs={fiveTabs} />,
+};

package/src/components/Navigation/BottomTabBar/BottomTabBar.tsx

@@ -0,0 +1,85 @@
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import { BottomTabBarItem } from './BottomTabBarItem';
+import { theme } from '../../../styles/theme';
+import { useResponsive } from '../../../hooks/useResponsive';
+
+export interface TabConfig {
+  /** Identificador único do separador */
+  id: string;
+  /** Texto a mostrar abaixo do ícone */
+  label: string;
+  /** Componente do ícone (ex: da biblioteca lucide-react-native) */
+  icon: React.ElementType;
+}
+
+/**
+ * Barra de Navegação Inferior (Bottom Tab Bar)
+ * Renderiza ícones com labels para navegação primária da app.
+ */
+export interface BottomTabBarProps {
+  /** Array de configurações dos separadores a renderizar */
+  tabs: TabConfig[];
+  /** O id do separador atualmente selecionado */
+  activeTabId: string;
+  /** Callback executado quando o utilizador clica num separador */
+  onTabChange: (id: string) => void;
+  /** Valor numérico correspondente ao safe-area-inset-bottom (útil para iOS home indicator) */
+  safeAreaBottom?: number;
+}
+
+/**
+ * O componente principal para a barra de navegação inferior (mobile).
+ *
+ * É totalmente flexível e ajusta-se automaticamente ao número de separadores inseridos.
+ * Para funcionar corretamente em dispositivos com ecrãs curvos ou barra inicial (ex: iPhone),
+ * deve receber o tamanho da `safeAreaBottom`.
+ */
+export const BottomTabBar = ({
+  tabs,
+  activeTabId,
+  onTabChange,
+  safeAreaBottom = 0,
+}: BottomTabBarProps) => {
+  const { scale } = useResponsive();
+
+  const baseHeight = scale(56);
+  const totalHeight = baseHeight + safeAreaBottom;
+
+  return (
+    <View 
+      style={[
+        styles.container, 
+        { 
+          height: totalHeight,
+          paddingBottom: safeAreaBottom,
+          paddingHorizontal: scale(6),
+        }
+      ]}
+      accessibilityRole="tablist"
+    >
+      {tabs.map((tab) => (
+        <BottomTabBarItem
+          key={tab.id}
+          id={tab.id}
+          label={tab.label}
+          icon={tab.icon}
+          isActive={activeTabId === tab.id}
+          onPress={onTabChange}
+        />
+      ))}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    justifyContent: 'space-around',
+    alignItems: 'center',
+    backgroundColor: theme.colors.white,
+    borderTopWidth: 1.5,
+    borderTopColor: theme.colors.brown[100],
+    width: '100%',
+  },
+});

package/src/components/Navigation/BottomTabBar/BottomTabBarItem.tsx

@@ -0,0 +1,68 @@
+import React from 'react';
+import { Pressable, View, StyleSheet } from 'react-native';
+import { theme } from '../../../styles/theme';
+import { useResponsive } from '../../../hooks/useResponsive';
+import { Typography } from '../../Typography/Typography';
+
+export interface BottomTabBarItemProps {
+  id: string;
+  label: string;
+  icon: React.ElementType;
+  isActive: boolean;
+  onPress: (id: string) => void;
+}
+
+export const BottomTabBarItem = ({
+  id,
+  label,
+  icon: IconComponent,
+  isActive,
+  onPress,
+}: BottomTabBarItemProps) => {
+  const { scale, scaleText } = useResponsive();
+
+  const color = isActive ? theme.colors.primary : theme.colors.brown[300];
+
+  return (
+    <Pressable
+      onPress={() => onPress(id)}
+      style={styles.container}
+      accessibilityRole="tab"
+      accessibilityState={{ selected: isActive }}
+    >
+      <View style={styles.iconContainer}>
+        <IconComponent stroke={color} size={scale(24)} strokeWidth={2} />
+      </View>
+      <Typography
+        style={[
+          styles.label,
+          {
+            color,
+            fontSize: scaleText(10),
+            marginTop: scale(4),
+          }
+        ]}
+        numberOfLines={1}
+      >
+        {label}
+      </Typography>
+    </Pressable>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    flex: 1, // To distribute space evenly (space-around effectively works well if all flex:1)
+    height: '100%',
+  },
+  iconContainer: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  label: {
+
+    textAlign: 'center',
+  },
+});

package/src/components/Navigation/BottomTabBar/index.ts

@@ -0,0 +1,2 @@
+export * from './BottomTabBar';
+export * from './BottomTabBarItem';

package/src/components/Navigation/PaginationDots/PaginationDots.stories.tsx

@@ -0,0 +1,62 @@
+// eslint-disable-next-line storybook/no-renderer-packages
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { View, Button } from 'react-native';
+import { PaginationDots } from './PaginationDots';
+import { theme } from '../../../styles/theme';
+
+const meta = {
+  title: 'Components/Navigation/PaginationDots',
+  component: PaginationDots,
+  parameters: { 
+    layout: 'padded',
+    docs: {
+      description: {
+        component: 'O **PaginationDots** é o indicador de posição para listas horizontais (como tutoriais de Onboarding ou carrosséis de imagens).\n\nEle suporta uma animação fluida (usando `react-native-reanimated`) onde o ponto ativo se expande e contrai em forma de "pílula" ao transitar entre páginas.\n\n### Exemplo de Uso\n```tsx\n<PaginationDots \n  totalPages={4}\n  currentPage={1}\n/>\n```',
+      }
+    }
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <View style={{ padding: 40, backgroundColor: theme.colors.cream }}>
+        <Story />
+      </View>
+    ),
+  ],
+} satisfies Meta<any>;
+
+export default meta;
+type Story = StoryObj<any>;
+
+export const Default: Story = {
+  args: { totalPages: 4, currentPage: 1 } as any,
+  render: (args: any) => <PaginationDots {...args} />,
+};
+
+const InteractiveDots = ({ totalPages }: { totalPages: number }) => {
+  const [currentPage, setCurrentStep] = useState(0);
+
+  return (
+    <View style={{ alignItems: 'center' }}>
+      <PaginationDots totalPages={totalPages} currentPage={currentPage} />
+      
+      <View style={{ flexDirection: 'row', gap: 20, marginTop: 20 }}>
+        <Button 
+          title="Prev" 
+          onPress={() => setCurrentStep(prev => Math.max(0, prev - 1))} 
+          disabled={currentPage === 0} 
+        />
+        <Button 
+          title="Next" 
+          onPress={() => setCurrentStep(prev => Math.min(totalPages - 1, prev + 1))} 
+          disabled={currentPage === totalPages - 1} 
+        />
+      </View>
+    </View>
+  );
+};
+
+export const Interactive: Story = {
+  render: () => <InteractiveDots totalPages={4} />,
+};