@imj_media/ui

v1.1.1

Published

5 days ago

Componentes UI

0High
0Medium
0Low

🎨 @imj_media/ui

Biblioteca de componentes UI moderna y accesible para React, construida con TypeScript y Tailwind CSS.

📦 Instalación

npm install @imj_media/ui
# o
yarn add @imj_media/ui
# o
pnpm add @imj_media/ui

🚀 Uso Básico

import { Button, Input, Modal } from '@imj_media/ui'
import '@imj_media/ui/index.css'

function App() {
  return (
    <div>
      <Button variant="button" color="blue">
        Hola Mundo
      </Button>
      <Input label="Email" placeholder="[email protected]" />
    </div>
  )
}

🎯 Características Principales

TypeScript First: Tipos completamente tipados para una mejor experiencia de desarrollo
Tailwind CSS: Sistema de diseño consistente y personalizable
Accesibilidad: Componentes construidos siguiendo las mejores prácticas de a11y
Responsive: Diseño adaptable a todos los tamaños de pantalla
Tema Personalizable: Sistema de colores y estilos fácilmente configurable
Storybook: Documentación interactiva de todos los componentes

🏗️ Estructura del Paquete

src/
├── modules/          # Componentes principales
├── shared/           # Utilidades y tipos compartidos
│   ├── types/        # Definiciones de tipos TypeScript
│   ├── utils/        # Funciones utilitarias
│   ├── styles/       # Estilos CSS y variables
│   ├── hooks/        # Hooks personalizados
│   └── assets/       # Recursos estáticos
└── index.ts          # Punto de entrada principal

🧩 Componentes Disponibles

🎨 Componentes de Navegación

Accordion

import { Accordion } from '@imj_media/ui'

<Accordion>
  <Accordion.Item title="Sección 1">
    Contenido de la sección 1
  </Accordion.Item>
</Accordion>

Breadcrumbs

import { Breadcrumbs } from '@imj_media/ui'

<Breadcrumbs
  items={[
    { label: 'Inicio', href: '/' },
    { label: 'Productos', href: '/productos' }
  ]}
/>

Drawer

import { Drawer } from '@imj_media/ui'

<Drawer isOpen={isOpen} onClose={() => setIsOpen(false)}>
  Contenido del drawer
</Drawer>

Modal

import { Modal } from '@imj_media/ui'

<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} size="md">
  <Modal.Header title="Título del Modal" />
  <Modal.Body>
    Contenido del modal
  </Modal.Body>
  <Modal.Footer>
    <Button onClick={onCancel}>Cancelar</Button>
    <Button onClick={onSuccess}>Confirmar</Button>
  </Modal.Footer>
</Modal>

Popup

import { Popup } from '@imj_media/ui'

<Popup
  trigger={<Button>Abrir Popup</Button>}
  content="Contenido del popup"
  position="top"
/>

🎯 Componentes de Formulario

Button

import { Button } from '@imj_media/ui'

<Button
  variant="button"
  color="blue"
  size="md"
  icon="check"
  onClick={handleClick}
>
  Botón Principal
</Button>

Variantes disponibles:

button: Botón estándar con fondo
text: Botón de texto sin fondo
outlined: Botón con borde
soft: Botón con fondo suave
icon: Botón solo con icono

Colores disponibles:

blue, green, orange, red
white, black, neutral
yellow, blue-dark, blue-light
transparent

Tamaños disponibles:

xs, sm, md, lg, xl, 2xl

ButtonGroup

import { ButtonGroup } from '@imj_media/ui'

<ButtonGroup>
  <Button variant="outlined">Izquierda</Button>
  <Button variant="outlined">Centro</Button>
  <Button variant="outlined">Derecha</Button>
</ButtonGroup>

Input

import { Input } from '@imj_media/ui'

<Input
  label="Email"
  placeholder="[email protected]"
  size="md"
  color="blue"
  leftSlot="mail"
  error="Email inválido"
  helperText="Ingresa tu email corporativo"
/>

Características:

Soporte para slots izquierdo y derecho
Validación de errores
Texto de ayuda
Auto-redimensionamiento
Diferentes tamaños y colores

Textarea

import { Textarea } from '@imj_media/ui'

<Textarea
  label="Descripción"
  placeholder="Describe tu proyecto..."
  rows={4}
  maxLength={500}
/>

Switch

import { Switch } from '@imj_media/ui'

<Switch
  checked={isEnabled}
  onChange={setIsEnabled}
  label="Habilitar notificaciones"
/>

RadioButton

import { RadioButton } from '@imj_media/ui'

<RadioButton
  name="tipo"
  value="personal"
  checked={tipo === 'personal'}
  onChange={(value) => setTipo(value)}
  label="Proyecto Personal"
/>

DatePicker

import { DatePicker } from '@imj_media/ui'

<DatePicker
  value={selectedDate}
  onChange={setSelectedDate}
  placeholder="Selecciona una fecha"
  format="DD/MM/YYYY"
/>

🎨 Componentes de Visualización

Badge

import { Badge } from '@imj_media/ui'

<Badge color="green" size="md" label="Activo" />

Tag

import { Tag } from '@imj_media/ui'

<Tag
  color="blue"
  size="md"
  onDelete={() => handleDelete()}
  label="Etiqueta"
/>

Avatar

import { Avatar } from '@imj_media/ui'

<Avatar
  src="/avatar.jpg"
  alt="Usuario"
  size="md"
  fallback="U"
/>

Logo

import { Logo } from '@imj_media/ui'

<Logo
  src="/logo.svg"
  alt="IMJ Media"
  size="lg"
/>

Picture

import { Picture } from '@imj_media/ui'

<Picture
  src="/image.jpg"
  alt="Descripción"
  size="lg"
  fallback="/placeholder.jpg"
/>

Visual

import { Visual } from '@imj_media/ui'

<Visual
  type="icon"
  name="star"
  size="lg"
  color="yellow"
/>

📊 Componentes de Datos

Lists

import { Lists } from '@imj_media/ui'

<Lists>
  <Lists.Item>Elemento 1</Lists.Item>
  <Lists.Item>Elemento 2</Lists.Item>
  <Lists.Item>Elemento 3</Lists.Item>
</Lists>

Pagination

import { Pagination } from '@imj_media/ui'

<Pagination
  currentPage={currentPage}
  totalPages={totalPages}
  onPageChange={setCurrentPage}
  showFirstLast={true}
/>

ProgressBar

import { ProgressBar } from '@imj_media/ui'

<ProgressBar
  value={75}
  max={100}
  color="blue"
  size="md"
  showLabel={true}
/>

Stepper

import { Stepper } from '@imj_media/ui'

<Stepper
  steps={[
    { label: 'Paso 1', status: 'completed' },
    { label: 'Paso 2', status: 'active' },
    { label: 'Paso 3', status: 'pending' }
  ]}
  currentStep={1}
/>

Estados disponibles:

completed: Paso completado
active: Paso actual
pending: Paso pendiente

🔔 Componentes de Notificación

Alert

import { Alert } from '@imj_media/ui'

<Alert
  type="info"
  title="Información"
  description="Este es un mensaje informativo"
  closable={true}
  onClose={() => handleClose()}
/>

Toast

import { Toast } from '@imj_media/ui'

<Toast
  type="success"
  title="Éxito"
  description="Operación completada"
  duration={5000}
  position="top-right"
/>

Tooltip

import { Tooltip } from '@imj_media/ui'

<Tooltip
  content="Información adicional"
  position="top"
  alignment="center"
  color="blue"
>
  <Button>Hover me</Button>
</Tooltip>

🎭 Componentes de Layout

Cards

import { Cards } from '@imj_media/ui'

<Cards>
  <Cards.Header>
    <Cards.Title>Título de la Tarjeta</Cards.Title>
    <Cards.Subtitle>Subtítulo opcional</Cards.Subtitle>
  </Cards.Header>
  <Cards.Body>
    Contenido de la tarjeta
  </Cards.Body>
  <Cards.Footer>
    <Button>Acción</Button>
  </Cards.Footer>
</Cards>

Separator

import { Separator } from '@imj_media/ui'

<Separator orientation="horizontal" />
<Separator orientation="vertical" />

Tag

import { Tag } from '@imj_media/ui'

<Tag
  color="blue"
  size="md"
  closable={true}
  onClose={() => handleClose()}
>
  Etiqueta
</Tag>

🎨 Componentes de Iconos y Emojis

Icon

import { Icon } from '@imj_media/ui'

<Icon
  name="star"
  variant="fill"
  size="lg"
  color="yellow"
/>

Variantes disponibles:

outline: Iconos con contorno
fill: Iconos rellenos

Emoji

import { Emoji } from '@imj_media/ui'

<Emoji name="smile" size="lg" />

🎬 Componentes Especiales

StoryBox

import { StoryBox } from '@imj_media/ui'

<StoryBox
  title="Historia del Usuario"
  description="Como usuario, quiero..."
  priority="high"
  status="in-progress"
/>

Filters

import { Filters } from '@imj_media/ui'

<Filters
  filters={[
    { key: 'status', label: 'Estado', type: 'select' },
    { key: 'priority', label: 'Prioridad', type: 'radio' }
  ]}
  onFilterChange={handleFilterChange}
/>

🎨 Sistema de Colores

El paquete incluye un sistema de colores completo con variables CSS personalizables:

:root {
  --ds-color-blue-50: #ebeef9;
  --ds-color-blue-500: #3658c1;
  --ds-color-blue-900: #172551;
  
  --ds-color-green-50: #f0f9f0;
  --ds-color-green-500: #039b59;
  --ds-color-green-900: #014125;
  
  --ds-color-red-50: #f9eae9;
  --ds-color-red-500: #c62e1f;
  --ds-color-red-900: #53130d;
  
  --ds-color-orange-50: #fcf3e9;
  --ds-color-orange-500: #dc8921;
  --ds-color-orange-900: #5c3a0e;
  
  --ds-color-yellow-50: #fcfbec;
  --ds-color-yellow-500: #e1d63d;
  --ds-color-yellow-900: #5f5a1a;
  
  --ds-color-neutral-50: #f0f0f0;
  --ds-color-neutral-500: #6b6b6b;
  --ds-color-neutral-900: #2d2d2d;
}

🛠️ Utilidades

Función `cn()`

Utilidad para combinar clases CSS de manera inteligente:

import { cn } from '@imj_media/ui'

const className = cn(
  'base-class',
  condition && 'conditional-class',
  'another-class'
)

📱 Responsive Design

Todos los componentes están diseñados para ser completamente responsivos:

Breakpoints: xs, sm, md, lg, xl, 2xl
Mobile First: Diseño optimizado para dispositivos móviles
Adaptive Layouts: Componentes que se adaptan automáticamente

♿ Accesibilidad

Los componentes siguen las mejores prácticas de accesibilidad:

ARIA Labels: Etiquetas descriptivas para lectores de pantalla
Keyboard Navigation: Navegación completa por teclado
Focus Management: Manejo inteligente del foco
Screen Reader Support: Compatibilidad con lectores de pantalla

🎨 Personalización

Variables CSS

Puedes personalizar el tema modificando las variables CSS:

:root {
  --ds-color-blue-500: #your-custom-blue;
  --ds-color-green-500: #your-custom-green;
}

Tailwind CSS

Todos los componentes utilizan Tailwind CSS y pueden ser personalizados a través de tu configuración:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        'custom-blue': '#1234567',
      }
    }
  }
}

📚 Storybook

Para ver todos los componentes en acción y explorar sus variantes:

npm run storybook

Storybook incluye:

Documentación interactiva de todos los componentes
Controles en tiempo real para probar diferentes props
Ejemplos de uso y mejores prácticas
Testing visual de componentes

🔧 Scripts Disponibles

{
  "scripts": {
    "build": "vite build",
    "dev": "vite build --watch",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,css,scss,md}\"",
    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,css,scss,md}\""
  }
}

📦 Dependencias

Peer Dependencies

react: ^18.0.0
react-dom: ^18.0.0

Dependencies Principales

class-variance-authority: Sistema de variantes de componentes
clsx: Utilidad para combinar clases CSS
tailwind-merge: Fusión inteligente de clases Tailwind
tailwind-variants: Sistema de variantes tipadas

🚀 Roadmap

[ ] Componente de Tabla avanzada
[ ] Componente de Gráficos
[ ] Componente de Calendario
[ ] Componente de Drag & Drop
[ ] Componente de Rich Text Editor
[ ] Temas oscuros/claros
[ ] Internacionalización (i18n)

🤝 Contribuir

Fork el proyecto
Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add some AmazingFeature')
Push a la rama (git push origin feature/AmazingFeature)
Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia ISC. Ver el archivo LICENSE para más detalles.

👥 Autores

Oscar Rubio - IMJ - Desarrollo inicial - [email protected]

🙏 Agradecimientos

Tailwind CSS por el sistema de diseño
React por el framework
TypeScript por el tipado estático
Storybook por la documentación interactiva

¿Necesitas ayuda? Abre un issue en el repositorio o contacta al equipo de desarrollo.