@astra-peru/expo-ui-components

Biblioteca de componentes UI reutilizables para aplicaciones Expo/React Native con NativeWind/Tailwind CSS.

📦 Instalación

Instalar desde npm

npm install @astra-peru/expo-ui-components

O con yarn:

yarn add @astra-peru/expo-ui-components

O con pnpm:

pnpm add @astra-peru/expo-ui-components

Dependencias Peer

Este paquete requiere las siguientes dependencias peer que debes instalar en tu proyecto:

npm install react react-native nativewind tailwindcss
npm install expo-image-picker react-native-safe-area-context react-native-autocomplete-dropdown

Nota: Si el paquete es privado y usas el scope @astra, asegúrate de estar autenticado en npm y tener acceso al paquete privado.

Versiones y Actualizaciones

Para actualizar a la última versión:

npm update @astra/expo-ui-components

Para instalar una versión específica:

npm install @astra-peru/[email protected]

Ver todas las versiones disponibles:

npm view @astra/expo-ui-components versions

⚡ Configuración Rápida

Ejecuta el script de configuración automática:

npm run setup

Este script:

• Detecta configuraciones existentes
• Hace merge inteligente (no sobrescribe)
• Configura Tailwind, Babel, Metro y TypeScript
• Verifica que global.css esté configurado

🔧 Configuración Manual

Si prefieres configurar manualmente o el script no funciona:

1. Configurar Tailwind CSS

Crea o actualiza tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./app/**/*.{js,jsx,ts,tsx}",
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@astra-peru/expo-ui-components/**/*.{js,jsx,ts,tsx}",
  ],
  presets: [require("nativewind/preset")],
  theme: {
    extend: {
      colors: {
        primary: {
          50: "#f3f6fc",
          100: "#e6edf8",
          // ... ver templates/tailwind.config.js para colores completos
        },
        // ... otros colores
      },
    },
  },
  plugins: [],
};

2. Configurar Babel

Actualiza babel.config.js:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      ["babel-preset-expo", { jsxImportSource: "nativewind" }],
      "nativewind/babel",
    ],
  };
};

3. Configurar Metro

Actualiza metro.config.js:

const { getDefaultConfig } = require("expo/metro-config");
const { withNativeWind } = require('nativewind/metro');
 
const config = getDefaultConfig(__dirname)
 
module.exports = withNativeWind(config, { input: './app/global.css' })

4. Configurar TypeScript

Crea o actualiza nativewind-env.d.ts:

/// <reference types="nativewind/types" />

5. Asegurar global.css

Asegúrate de tener app/global.css con:

@tailwind base;
@tailwind components;
@tailwind utilities;

E importarlo en tu app/_layout.tsx:

import '../global.css';

📚 Componentes Disponibles

Componentes de Formulario

• Button - Botón con múltiples variantes y colores
• Input - Campo de texto con iconos y validación
• TextAreaInput - Área de texto multilínea
• Checkbox - Casilla de verificación individual y grupo
• RadioButton - Botón de radio individual y grupo
• Toggle - Interruptor on/off
• Dropdown - Selector desplegable (single/multi)
• AutocompleteDropdown - Autocompletado con búsqueda
• FormLabel - Etiqueta para formularios
• FormDatePicker - Selector de fecha
• FormTimePicker - Selector de hora
• FormDateRange - Selector de rango de fechas

Componentes de Media

• SingleImageUploader - Cargador de imagen única
• MultipleImageUploader - Cargador de múltiples imágenes

Componentes de UI

• Chip - Etiqueta/chip con estados
• Modal - Modal base con variantes:
  • AlertModal
  • ConfirmModal
  • ErrorModal
  • LoadingModal
  • LocationPermissionModal

Componentes de Layout

• LoadingScreen - Pantalla de carga
• SplashScreen - Pantalla de inicio
• DeviceSafeArea - Wrapper para safe area

Iconos

34 iconos disponibles: IconArrowLeft, IconCalendar, IconCamera, IconCheckmark, IconChevronDown, IconChevronLeft, IconChevronRight, IconClock, IconCloudUpload, IconCollection, IconDashboard, IconDownload, IconEdit, IconEye, IconEyeOff, IconFilter, IconFlag, IconHome, IconInfo, IconLock, IconLogout, IconMapPin, IconPhone, IconPhoto, IconQuestion, IconRefresh, IconSearch, IconSearchOff, IconSettings, IconTrash, IconUser, IconWhatsapp, IconX

🎯 Ejemplos de Uso

Button

import { Button } from '@astra-peru/expo-ui-components';

<Button
  variant="filled"
  color="primary"
  size="md"
  onPress={() => console.log('Pressed')}
>
  Click me
</Button>

Input

import { Input } from '@astra-peru/expo-ui-components';

<Input
  label="Email"
  placeholder="Enter your email"
  value={email}
  onChangeText={setEmail}
  format="email"
  leftIcon={{ name: "user" }}
  required
/>

FormDatePicker

import { FormDatePicker } from '@astra-peru/expo-ui-components';

<FormDatePicker
  label="Fecha de nacimiento"
  value={date}
  onValueChange={setDate}
  minimumDate={new Date(1900, 0, 1)}
  maximumDate={new Date()}
/>

Modal

import { AlertModal, ConfirmModal } from '@astra-peru/expo-ui-components';

<AlertModal
  visible={showAlert}
  title="Éxito"
  message="Operación completada"
  onClose={() => setShowAlert(false)}
/>

<ConfirmModal
  visible={showConfirm}
  title="Confirmar"
  message="¿Estás seguro?"
  onConfirm={handleConfirm}
  onClose={() => setShowConfirm(false)}
/>

useAlert Hook

import { useAlert } from '@astra-peru/expo-ui-components';
import { AlertModal } from '@astra-peru/expo-ui-components';

function MyComponent() {
  const { alertState, showAlert, showConfirm, hideAlert } = useAlert();

  return (
    <>
      <Button onPress={() => showAlert('Título', 'Mensaje')}>
        Mostrar Alerta
      </Button>
      
      <AlertModal
        visible={alertState.visible}
        title={alertState.title}
        message={alertState.message}
        buttons={alertState.buttons}
        onClose={hideAlert}
      />
    </>
  );
}

Utilidades de Fecha

import { formatDateForDisplay, formatDateToString, parseDateSafely } from '@astra-peru/expo-ui-components';

const date = new Date();
const display = formatDateForDisplay(date); // "15/01/2024"
const apiFormat = formatDateToString(date); // "2024-01-15"
const parsed = parseDateSafely("2024-01-15"); // Date object

DeviceSafeArea

import { DeviceSafeArea } from '@astra-peru/expo-ui-components';

export default function App() {
  return (
    <DeviceSafeArea>
      <YourContent />
    </DeviceSafeArea>
  );
}

🛠️ Hooks Disponibles

useAlert

Hook para mostrar alertas y confirmaciones:

const {
  alertState,
  showAlert,
  showConfirm,
  showDestructive,
  showCustom,
  hideAlert,
} = useAlert();

📝 Tipos Disponibles

ApiError

interface ApiError {
  message: string;
  status?: number;
  code?: string;
  errors?: Record<string, string[]>;
  title?: string;
  traceId?: string;
}

🐛 Troubleshooting

Los estilos de Tailwind no se aplican

1. Verifica que global.css esté importado en app/_layout.tsx
2. Asegúrate de que tailwind.config.js incluya la ruta del paquete en content
3. Reinicia el servidor de desarrollo

Error: "Cannot find module 'nativewind'"

Instala NativeWind:

npm install nativewind

Los componentes no se renderizan correctamente

1. Verifica que todas las dependencias peer estén instaladas
2. Asegúrate de que Babel y Metro estén configurados correctamente
3. Revisa que nativewind-env.d.ts exista

Error de tipos TypeScript

Asegúrate de tener nativewind-env.d.ts con:

/// <reference types="nativewind/types" />

Y que esté incluido en tu tsconfig.json.

📄 Licencia

MIT

🤝 Contribuir

Este es un paquete privado. Para contribuir, contacta al equipo de desarrollo.

📁 Proyecto de Ejemplo

Este repositorio incluye un proyecto de ejemplo completo en la carpeta example/ que demuestra el uso de todos los componentes.

Ejecutar el Ejemplo

cd example
npm install
npm start

El proyecto de ejemplo:

• Usa la versión publicada de @astra/expo-ui-components desde npm
• Incluye un formulario completo con validación
• Demuestra todos los componentes disponibles
• Está configurado con Expo Router y NativeWind

Para más información, consulta example/README.md.

Nota para Desarrolladores: Si estás desarrollando el paquete y quieres probar cambios localmente, consulta example/DEVELOPMENT.md para configurar desarrollo local.

📞 Soporte

Para problemas o preguntas, abre un issue en el repositorio del proyecto.

📦 Publicación

Para información sobre cómo publicar este paquete, consulta PUBLISHING.md.