@xetwa/design-system 1.0.2

package/src/components/Inputs/FillInTheBlank/FillInTheBlank.stories.tsx

@@ -0,0 +1,333 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { View } from 'react-native';
+import { FillInTheBlank } from './FillInTheBlank';
+import { WordChip } from '../../Buttons/WordChip/WordChip';
+import { MainButton } from '../../Buttons/MainButton/MainButton';
+import { useResponsive } from '../../../hooks/useResponsive';
+
+const meta = {
+  title: 'Components/Inputs/FillInTheBlank',
+  component: FillInTheBlank,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `O **FillInTheBlank** é um componente interativo avançado para exercícios de preenchimento de lacunas (Cloze Tests), amplamente usados em apps de ensino de línguas.
+
+Ele é focado apenas na renderização da frase e das lacunas. O banco de opções (Word Bank) é renderizado separadamente pelo ecrã usando o componente \`WordChip\`, o que permite organizar os botões da forma que desejar.
+
+### Exemplo de Uso (Seleção / Word Bank com chips externos)
+\`\`\`tsx
+import { useState } from 'react';
+import { FillInTheBlank, WordChip } from '@xetlingo/design-system';
+
+const parts = [
+  { type: 'text', text: 'Je suis' },
+  { type: 'blank', id: 'b1', placeholder: '...' },
+  { type: 'text', text: "et j'habite à Paris." }
+];
+
+const MyScreen = () => {
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [activeId, setActiveId] = useState('b1');
+
+  return (
+    <>
+      <FillInTheBlank
+        instruction="Completa a frase:"
+        parts={parts}
+        values={values}
+        activeBlankId={activeId}
+        onBlankPress={(id) => setActiveId(id)}
+      />
+      
+      {/* WordChips gerenciados pelo ecrã */}
+      <WordChip
+        word="étudiant"
+        state={values.b1 === 'étudiant' ? 'used' : 'default'}
+        onPress={() => setValues({ b1: 'étudiant' })}
+      />
+    </>
+  );
+};
+\`\`\`
+
+### Exemplo de Uso (Modo Digitação)
+\`\`\`tsx
+import { useState } from 'react';
+import { FillInTheBlank } from '@xetlingo/design-system';
+
+const inputParts = [
+  { type: 'text', text: 'He' },
+  { type: 'blank', id: 'b1', placeholder: 'write', expectedLength: 6 },
+  { type: 'text', text: 'letters.' }
+];
+
+const MyInputScreen = () => {
+  const [values, setValues] = useState<Record<string, string>>({});
+
+  return (
+    <FillInTheBlank
+      instruction="Digita a resposta correta:"
+      parts={inputParts}
+      values={values}
+      mode="input"
+      onChangeText={(id, text) => setValues(prev => ({ ...prev, [id]: text }))}
+    />
+  );
+};
+\`\`\`
+`
+      }
+    }
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <View style={{ width: '100%', maxWidth: 500, alignSelf: 'center' }}>
+        <Story />
+      </View>
+    ),
+  ],
+} satisfies Meta<any>;
+
+export default meta;
+type Story = StoryObj<any>;
+
+// 1. Interactive Selection (Word Bank) wrapper
+const InteractiveSelectionWrapper = (args: any) => {
+  const { width } = useResponsive();
+  const isSmallScreen = width < 480;
+
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [usedOptions, setUsedOptions] = useState<string[]>([]);
+  const [activeBlankId, setActiveBlankId] = useState<string>('blank1');
+  const [validationStates, setValidationStates] = useState<Record<string, 'correct' | 'wrong'>>({});
+
+  const parts = [
+    { type: 'text' as const, text: 'Je suis' },
+    { type: 'blank' as const, id: 'blank1', placeholder: '...' },
+    { type: 'text' as const, text: "et j'habite à" },
+    { type: 'blank' as const, id: 'blank2', placeholder: '...' },
+    { type: 'text' as const, text: 'depuis dois anos.' },
+  ];
+
+  const options = ['étudiant', 'Paris', 'professeur', 'Saint-Louis', 'médecin'];
+
+  const handleOptionPress = (word: string) => {
+    if (!activeBlankId) return;
+
+    setValidationStates({});
+
+    const oldWord = values[activeBlankId];
+    let newUsed = [...usedOptions];
+    if (oldWord) {
+      newUsed = newUsed.filter(w => w !== oldWord);
+    }
+
+    setValues(prev => ({ ...prev, [activeBlankId]: word }));
+    setUsedOptions([...newUsed, word]);
+
+    if (activeBlankId === 'blank1' && !values['blank2']) {
+      setActiveBlankId('blank2');
+    } else {
+      setActiveBlankId('');
+    }
+  };
+
+  const handleBlankPress = (id: string) => {
+    setActiveBlankId(id);
+    setValidationStates({});
+
+    const currentWord = values[id];
+    if (currentWord) {
+      setValues(prev => ({ ...prev, [id]: '' }));
+      setUsedOptions(prev => prev.filter(w => w !== currentWord));
+    }
+  };
+
+  const handleReset = () => {
+    setValues({});
+    setUsedOptions([]);
+    setActiveBlankId('blank1');
+    setValidationStates({});
+  };
+
+  const handleVerify = () => {
+    const results: Record<string, 'correct' | 'wrong'> = {};
+    results.blank1 = (values.blank1 === 'étudiant' || values.blank1 === 'professeur' || values.blank1 === 'médecin') ? 'correct' : 'wrong';
+    results.blank2 = values.blank2 === 'Paris' ? 'correct' : 'wrong';
+    setValidationStates(results);
+  };
+
+  return (
+    <View style={{ width: '100%' }}>
+      <FillInTheBlank
+        instruction={args.instruction}
+        parts={args.parts || parts}
+        values={values}
+        activeBlankId={activeBlankId}
+        onBlankPress={handleBlankPress}
+        validationStates={validationStates}
+        mode="selection"
+      />
+
+      <View style={[styles.optionsContainer, { marginTop: isSmallScreen ? 12 : 20, marginBottom: isSmallScreen ? 12 : 20 }]}>
+        {options.map((option, idx) => {
+          const isUsed = usedOptions.includes(option);
+          const state = isUsed ? 'used' : 'default';
+
+          return (
+            <WordChip
+              key={`opt-${idx}`}
+              word={option}
+              state={state}
+              onPress={() => !isUsed && handleOptionPress(option)}
+              style={{ margin: 4 }}
+            />
+          );
+        })}
+      </View>
+
+      <View style={[styles.buttonRow, { flexDirection: isSmallScreen ? 'column' : 'row' }]}>
+        <MainButton
+          variant="secondary"
+          onPress={handleReset}
+          style={isSmallScreen ? { width: '100%', marginBottom: 8 } : { flex: 1, marginRight: 8 }}
+        >
+          Limpar
+        </MainButton>
+        <MainButton
+          variant="primary"
+          onPress={handleVerify}
+          style={isSmallScreen ? { width: '100%' } : { flex: 2 }}
+          disabled={!values.blank1 || !values.blank2}
+        >
+          Verificar Resposta
+        </MainButton>
+      </View>
+    </View>
+  );
+};
+
+export const SelectionMode: Story = {
+  name: 'Modo Seleção (Word Bank Interativo)',
+  args: {
+    parts: [], instruction: 'Completa a frase:',
+  },
+  render: (args) => <InteractiveSelectionWrapper {...args} />,
+};
+
+// 2. Interactive Input (Typing) wrapper
+const InteractiveInputWrapper = (args: any) => {
+  const { width } = useResponsive();
+  const isSmallScreen = width < 480;
+
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [validationStates, setValidationStates] = useState<Record<string, 'correct' | 'wrong'>>({});
+
+  const parts = [
+    { type: 'text' as const, text: 'He' },
+    { type: 'blank' as const, id: 'b1', placeholder: 'write', expectedLength: 6 },
+    { type: 'text' as const, text: 'letters to his family, and they' },
+    { type: 'blank' as const, id: 'b2', placeholder: 'send', expectedLength: 4 },
+    { type: 'text' as const, text: 'them back.' },
+  ];
+
+  const handleTextChange = (id: string, text: string) => {
+    setValues(prev => ({ ...prev, [id]: text }));
+    if (validationStates[id]) {
+      setValidationStates(prev => ({ ...prev, [id]: undefined as any }));
+    }
+  };
+
+  const handleVerify = () => {
+    const results: Record<string, 'correct' | 'wrong'> = {};
+    results.b1 = (values.b1 || '').trim().toLowerCase() === 'writes' ? 'correct' : 'wrong';
+    results.b2 = (values.b2 || '').trim().toLowerCase() === 'send' ? 'correct' : 'wrong';
+    setValidationStates(results);
+  };
+
+  const handleReset = () => {
+    setValues({});
+    setValidationStates({});
+  };
+
+  return (
+    <View style={{ width: '100%' }}>
+      <FillInTheBlank
+        instruction={args.instruction}
+        parts={args.parts || parts}
+        values={values}
+        onChangeText={handleTextChange}
+        validationStates={validationStates}
+        mode="input"
+      />
+
+      <View style={[styles.buttonRow, { flexDirection: isSmallScreen ? 'column' : 'row', marginTop: 16 }]}>
+        <MainButton
+          variant="secondary"
+          onPress={handleReset}
+          style={isSmallScreen ? { width: '100%', marginBottom: 8 } : { flex: 1, marginRight: 8 }}
+        >
+          Limpar
+        </MainButton>
+        <MainButton
+          variant="primary"
+          onPress={handleVerify}
+          style={isSmallScreen ? { width: '100%' } : { flex: 2 }}
+          disabled={!values.b1 || !values.b2}
+        >
+          Verificar Resposta
+        </MainButton>
+      </View>
+    </View>
+  );
+};
+
+export const InputMode: Story = {
+  name: 'Modo Digitação (Teclado)',
+  args: {
+    parts: [], instruction: 'Digita a resposta correta:',
+  },
+  render: (args) => <InteractiveInputWrapper {...args} />,
+};
+
+// 3. Validation States (Correct / Wrong) static preview
+export const ValidationStates: Story = {
+  name: 'Estados de Validação (Resultado)',
+  args: {
+    parts: [
+      { type: 'text', text: 'Nous' },
+      { type: 'blank', id: 'b1', expectedLength: 6 },
+      { type: 'text', text: 'le français et vous' },
+      { type: 'blank', id: 'b2', expectedLength: 7 },
+      { type: 'text', text: 'le wolof.' },
+    ],
+    values: {
+      b1: 'parlons',
+      b2: 'parlezs', // incorreto
+    },
+    validationStates: {
+      b1: 'correct',
+      b2: 'wrong',
+    },
+    mode: 'selection',
+  },
+};
+
+const styles = {
+  optionsContainer: {
+    flexDirection: 'row' as const,
+    flexWrap: 'wrap' as const,
+    alignItems: 'center' as const,
+    justifyContent: 'flex-start' as const,
+    width: '100%' as const,
+  },
+  buttonRow: {
+    alignItems: 'center' as const,
+    justifyContent: 'space-between' as const,
+    width: '100%' as const,
+  },
+};

package/src/components/Inputs/FillInTheBlank/FillInTheBlank.tsx

@@ -0,0 +1,287 @@
+
+import { View, StyleSheet, TextInput, TouchableOpacity } from 'react-native';
+import type { ViewStyle } from 'react-native';
+import { theme } from '../../../styles/theme';
+import { useResponsive } from '../../../hooks/useResponsive';
+import { Typography } from '../../Typography/Typography';
+
+export type FillInTheBlankPart =
+  | { type: 'text'; text: string; id?: string }
+  | { type: 'blank'; id: string; blankWidth?: number; expectedLength?: number; placeholder?: string };
+
+export interface FillInTheBlankProps {
+  /** Segmentos da frase (texto ou lacunas) */
+  parts: FillInTheBlankPart[];
+  /** Valores atualmente preenchidos nas lacunas: { [blankId: string]: string } */
+  values?: Record<string, string>;
+  /** Callback ao clicar numa lacuna (modo seleção/word bank) */
+  onBlankPress?: (blankId: string) => void;
+  /** Callback ao digitar texto numa lacuna (modo input) */
+  onChangeText?: (blankId: string, text: string) => void;
+  /** ID da lacuna ativa/focada (ex: para destacar em modo seleção) */
+  activeBlankId?: string;
+  /** Modo de interação da lacuna: 'selection' (word bank) ou 'input' (digitação) */
+  mode?: 'selection' | 'input';
+  /** Estados de validação para cada lacuna: { [blankId: string]: 'correct' | 'wrong' } */
+  validationStates?: Record<string, 'correct' | 'wrong'>;
+  /** Instrução opcional exibida acima do componente (ex: "Complete a frase:") */
+  instruction?: string;
+  /** Estilos customizados para o container wrapper principal */
+  style?: ViewStyle | ViewStyle[];
+}
+
+export const FillInTheBlank = ({
+  parts,
+  values = {},
+  onBlankPress,
+  onChangeText,
+  activeBlankId,
+  mode = 'selection',
+  validationStates = {},
+  instruction,
+  style,
+}: FillInTheBlankProps) => {
+  const { scale, scaleText } = useResponsive();
+
+  const renderBlank = (part: FillInTheBlankPart) => {
+    const blankId = part.id || "";
+    const value = values[blankId] || '';
+    const validation = validationStates[blankId];
+    const isActive = activeBlankId === blankId;
+    const isFilled = value !== '';
+
+    // Calcula largura com base nas propriedades fornecidas
+    const blankWidth = (part as any).blankWidth
+      ? scale((part as any).blankWidth)
+      : (part as any).expectedLength
+        ? scale((part as any).expectedLength * 12 + 28)
+        : scale(88);
+
+    // Definição de estilos base do slot consoante o estado
+    let borderColor = theme.colors.brown[100];
+    let backgroundColor = theme.colors.brown[50];
+    let textColor = theme.colors.brown[800];
+    let borderStyle: 'solid' | 'dashed' = 'dashed';
+    let shadowColor = 'transparent';
+    let show3DShadow = false;
+
+    if (validation === 'correct') {
+      borderColor = theme.colors.success;
+      backgroundColor = '#eafaf2'; // verde claro
+      textColor = theme.colors.success;
+      borderStyle = 'solid';
+      shadowColor = 'rgba(22, 145, 90, 0.2)';
+    } else if (validation === 'wrong') {
+      borderColor = theme.colors.error;
+      backgroundColor = '#fdf0ee'; // vermelho claro
+      textColor = theme.colors.error;
+      borderStyle = 'solid';
+      shadowColor = 'rgba(207, 91, 72, 0.2)';
+    } else if (isFilled) {
+      borderColor = isActive ? theme.colors.primary : theme.colors.brown[500];
+      backgroundColor = theme.colors.white;
+      textColor = theme.colors.brown[800];
+      borderStyle = 'solid';
+      shadowColor = isActive ? 'rgba(242, 151, 75, 0.2)' : theme.colors.brown[100];
+      show3DShadow = true;
+    } else if (isActive) {
+      borderColor = theme.colors.primary;
+      backgroundColor = theme.colors.primaryLight;
+      borderStyle = 'solid';
+    }
+
+    if (mode === 'input') {
+      return (
+        <View
+          key={`blank-${blankId}`}
+          style={[
+            styles.blankContainer,
+            {
+              width: isFilled ? undefined : blankWidth,
+              minWidth: blankWidth,
+              marginHorizontal: scale(4),
+              marginVertical: scale(4),
+            }
+          ]}
+        >
+          <TextInput
+            value={value}
+            onChangeText={(text) => onChangeText?.(part.id || "", text)}
+            placeholder={(part as any).placeholder || '...'}
+            placeholderTextColor={theme.colors.brown[400]}
+            editable={validation === undefined}
+            style={[
+              styles.input,
+              {
+                height: scale(40),
+                borderColor,
+                backgroundColor,
+                color: textColor,
+                borderRadius: scale(10),
+                fontSize: scaleText(16),
+                paddingHorizontal: scale(12),
+                borderWidth: 2,
+              }
+            ]}
+          />
+        </View>
+      );
+    } else {
+      const displayContent = (
+        <View style={[
+          styles.blankInner,
+          {
+            borderColor,
+            backgroundColor,
+            borderRadius: scale(10),
+            borderWidth: 2,
+            borderStyle,
+            minWidth: blankWidth,
+            height: scale(40),
+            paddingHorizontal: scale(12),
+          }
+        ]}>
+          <Typography style={[
+            styles.blankText,
+            {
+              color: isFilled ? textColor : theme.colors.brown[400],
+              fontSize: scaleText(16),
+            }
+          ]}>
+            {value || (part as any).placeholder || ''}
+          </Typography>
+        </View>
+      );
+
+      const handlePress = () => {
+        if (validation === undefined && onBlankPress) {
+          onBlankPress(blankId);
+        }
+      };
+
+      if (isFilled && show3DShadow && validation === undefined) {
+        return (
+          <TouchableOpacity
+            key={`blank-${blankId}`}
+            onPress={handlePress}
+            activeOpacity={0.85}
+            style={[
+              styles.blankContainer,
+              {
+                marginHorizontal: scale(4),
+                marginVertical: scale(4),
+              }
+            ]}
+          >
+            <View style={[
+              styles.shadowContainer,
+              {
+                backgroundColor: shadowColor,
+                borderRadius: scale(10),
+                paddingBottom: scale(3),
+              }
+            ]}>
+              {displayContent}
+            </View>
+          </TouchableOpacity>
+        );
+      }
+
+      return (
+        <TouchableOpacity
+          key={`blank-${blankId}`}
+          onPress={handlePress}
+          disabled={validation !== undefined || !onBlankPress}
+          activeOpacity={0.85}
+          style={[
+            styles.blankContainer,
+            {
+              marginHorizontal: scale(4),
+              marginVertical: scale(4),
+            }
+          ]}
+        >
+          {displayContent}
+        </TouchableOpacity>
+      );
+    }
+  };
+
+  const renderPart = (part: FillInTheBlankPart, index: number) => {
+    if (part.type === 'text') {
+      const words = (part.text || '').split(' ');
+      return words.map((word, wIdx) => {
+        if (word === '' && wIdx > 0 && wIdx < words.length - 1) return null;
+
+        return (
+          <Typography
+            key={`text-${index}-${wIdx}`}
+            style={[styles.staticText, { fontSize: scaleText(17.5), marginRight: scale(6), marginVertical: scale(4) }]}
+          >
+            {word}
+          </Typography>
+        );
+      });
+    } else {
+      return renderBlank(part);
+    }
+  };
+
+  return (
+    <View style={[styles.container, style]}>
+      {/* Opcional: Texto de instrução no topo */}
+      {!!instruction && (
+        <Typography style={[styles.instructionText, { fontSize: scaleText(16), marginBottom: scale(16) }]}>
+          {instruction}
+        </Typography>
+      )}
+
+      {/* Zona da Frase / Bloco das Lacunas */}
+      <View style={styles.sentenceWrapper}>
+        {parts.map((part, index) => renderPart(part, index))}
+      </View>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    width: '100%',
+    alignSelf: 'center',
+  },
+  instructionText: {
+
+    color: theme.colors.brown[500],
+
+  },
+  sentenceWrapper: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    justifyContent: 'flex-start',
+    width: '100%',
+  },
+  staticText: {
+
+    color: theme.colors.brown[800], // cor do texto principal
+  },
+  blankContainer: {
+    alignSelf: 'center',
+  },
+  blankInner: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  blankText: {
+
+    textAlign: 'center',
+  },
+  input: {
+
+    textAlign: 'center',
+    padding: 0,
+  },
+  shadowContainer: {
+    alignSelf: 'flex-start',
+  },
+});

package/src/components/Inputs/FillInTheBlank/index.ts

@@ -0,0 +1 @@
+export * from './FillInTheBlank';