siesa-ui-kit 1.0.0 → 1.0.2

package/src/components/Table/README.md

@@ -1,369 +1,369 @@
-# Table Component
-
-Componente de tabla flexible y accesible con soporte para sorting, variantes visuales y dark mode completo.
-
-## Características
-
-- ✅ **Definición de columnas flexible** con `accessor` y `render` custom
-- ✅ **Sorting** en columnas (controlado o no controlado)
-- ✅ **Variantes visuales**: basic, fullWidth, striped, grid
-- ✅ **Dark mode completo** en todos los estados
-- ✅ **Estados de loading y empty**
-- ✅ **Filas clickeables**
-- ✅ **TypeScript** con tipos estrictos y generics
-- ✅ **Accesibilidad** con roles y keyboard navigation
-
-## Uso Básico
-
-```tsx
-import { Table } from '@/components/Table';
-import type { TableColumn } from '@/components/Table';
-
-interface Usuario {
-  id: number;
-  nombre: string;
-  email: string;
-}
-
-const usuarios: Usuario[] = [
-  { id: 1, nombre: 'Juan Pérez', email: 'juan@example.com' },
-  { id: 2, nombre: 'María García', email: 'maria@example.com' },
-];
-
-const columns: TableColumn<Usuario>[] = [
-  { header: 'Nombre', accessor: 'nombre' },
-  { header: 'Email', accessor: 'email' },
-];
-
-function App() {
-  return (
-    <Table
-      title="Usuarios"
-      columns={columns}
-      data={usuarios}
-    />
-  );
-}
-```
-
-## Variantes
-
-### Basic
-Tabla estándar con padding y spacing consistente.
-
-```tsx
-<Table
-  title="Usuarios"
-  columns={columns}
-  data={data}
-  variant="basic"
-/>
-```
-
-### Full Width
-Tabla que ocupa todo el ancho disponible.
-
-```tsx
-<Table
-  title="Usuarios"
-  columns={columns}
-  data={data}
-  variant="fullWidth"
-/>
-```
-
-### Striped (Filas Alternas)
-Filas con fondo alternado para mejor legibilidad.
-
-```tsx
-<Table
-  title="Usuarios"
-  columns={columns}
-  data={data}
-  variant="striped"
-/>
-```
-
-### Grid (Con Bordes)
-Tabla con bordes alrededor de las celdas.
-
-```tsx
-<Table
-  title="Usuarios"
-  columns={columns}
-  data={data}
-  variant="grid"
-/>
-```
-
-## Sorting
-
-### Sorting No Controlado (Interno)
-
-```tsx
-const columns: TableColumn<Usuario>[] = [
-  {
-    header: 'Nombre',
-    accessor: 'nombre',
-    sortable: true, // Habilitar sorting
-  },
-  {
-    header: 'Email',
-    accessor: 'email',
-    sortable: true,
-  },
-];
-
-<Table columns={columns} data={data} />
-```
-
-### Sorting Controlado (Externo)
-
-```tsx
-const [sortColumn, setSortColumn] = useState<keyof Usuario | null>(null);
-const [sortDirection, setSortDirection] = useState<SortDirection>(null);
-
-const handleSort = (column: keyof Usuario | string, direction: SortDirection) => {
-  setSortColumn(column as keyof Usuario);
-  setSortDirection(direction);
-
-  // Ordenar los datos
-  const sorted = [...data].sort((a, b) => {
-    // Lógica de ordenamiento
-  });
-  setData(sorted);
-};
-
-<Table
-  columns={columns}
-  data={data}
-  sortColumn={sortColumn}
-  sortDirection={sortDirection}
-  onSort={handleSort}
-/>
-```
-
-## Render Custom
-
-Puedes personalizar cómo se renderiza el contenido de una celda:
-
-```tsx
-const columns: TableColumn<Usuario>[] = [
-  {
-    header: 'Estado',
-    accessor: 'estado',
-    render: (value, row, index) => (
-      <span
-        className={`
-          px-2 py-1 rounded-md text-xs font-bold
-          ${value === 'activo' ? 'bg-green-100 text-green-800' : 'bg-red-100 text-red-800'}
-        `}
-      >
-        {value}
-      </span>
-    ),
-  },
-];
-```
-
-## Accessor Function
-
-Puedes usar una función para acceder a valores anidados o calculados:
-
-```tsx
-const columns: TableColumn<Usuario>[] = [
-  {
-    header: 'Nombre Completo',
-    accessor: (row) => `${row.nombre} ${row.apellido}`,
-  },
-  {
-    header: 'Email',
-    accessor: (row) => row.contacto.email.toLowerCase(),
-  },
-];
-```
-
-## Alineación de Columnas
-
-```tsx
-const columns: TableColumn<Usuario>[] = [
-  {
-    header: 'ID',
-    accessor: 'id',
-    align: 'center', // 'left' | 'center' | 'right'
-    width: '80px',   // Ancho fijo
-  },
-  {
-    header: 'Nombre',
-    accessor: 'nombre',
-    align: 'left',
-  },
-];
-```
-
-## Estados
-
-### Loading
-
-```tsx
-<Table
-  title="Usuarios"
-  columns={columns}
-  data={[]}
-  loading={true}
-  loadingRows={5}
-/>
-```
-
-### Empty
-
-```tsx
-<Table
-  title="Usuarios"
-  columns={columns}
-  data={[]}
-  emptyMessage="No hay usuarios registrados"
-/>
-```
-
-## Filas Clickeables
-
-```tsx
-const handleRowClick = (row: Usuario, index: number) => {
-  console.log('Clicked:', row);
-  // Navegar a detalle, abrir modal, etc.
-};
-
-<Table
-  columns={columns}
-  data={data}
-  onRowClick={handleRowClick}
-/>
-```
-
-## Props
-
-### TableProps
-
-| Prop | Tipo | Default | Descripción |
-|------|------|---------|-------------|
-| `title` | `string` | `undefined` | Título opcional de la tabla |
-| `columns` | `TableColumn<T>[]` | **Required** | Definición de las columnas |
-| `data` | `T[]` | **Required** | Datos de las filas |
-| `variant` | `'basic' \| 'fullWidth' \| 'striped' \| 'grid'` | `'basic'` | Variante visual |
-| `showBorder` | `boolean` | `true` | Si se muestra el borde del container |
-| `showShadow` | `boolean` | `true` | Si se muestra la sombra del container |
-| `onRowClick` | `(row: T, index: number) => void` | `undefined` | Callback al hacer click en una fila |
-| `onSort` | `(column: string, direction: SortDirection) => void` | `undefined` | Callback al cambiar el sort |
-| `sortColumn` | `keyof T \| string` | `undefined` | Columna ordenada (controlado) |
-| `sortDirection` | `SortDirection` | `undefined` | Dirección de sort (controlado) |
-| `fullWidth` | `boolean` | `false` | Si ocupa todo el ancho |
-| `emptyMessage` | `string` | `'No hay datos disponibles'` | Mensaje cuando no hay datos |
-| `loading` | `boolean` | `false` | Si está cargando |
-| `loadingRows` | `number` | `5` | Número de rows skeleton |
-| `className` | `string` | `''` | Clases CSS adicionales |
-| `id` | `string` | `undefined` | ID único |
-
-### TableColumn
-
-| Prop | Tipo | Default | Descripción |
-|------|------|---------|-------------|
-| `header` | `string` | **Required** | Título del header |
-| `accessor` | `keyof T \| (row: T) => any` | **Required** | Key o función para obtener valor |
-| `sortable` | `boolean` | `false` | Si la columna es sortable |
-| `render` | `(value: any, row: T, index: number) => ReactNode` | `undefined` | Función custom de render |
-| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Alineación del contenido |
-| `width` | `string` | `undefined` | Ancho de la columna |
-
-## Dark Mode
-
-El componente Table se adapta automáticamente a dark mode usando los tokens de color del sistema:
-
-```tsx
-// Los colores se adaptan automáticamente
-<Table
-  columns={columns}
-  data={data}
-  // En light mode: bg-white, text-content-primary
-  // En dark mode: bg-dark-bg-primary, text-dark-content-primary
-/>
-```
-
-## Accesibilidad
-
-- ✅ Headers clickeables tienen `role="button"` y `tabIndex={0}`
-- ✅ Soporta navegación por teclado (Enter y Space)
-- ✅ Estados de sort anunciados visualmente con iconos
-- ✅ Filas clickeables con keyboard support
-
-## Ejemplos Avanzados
-
-### Tabla de Productos con Render Custom
-
-```tsx
-interface Producto {
-  id: number;
-  nombre: string;
-  precio: number;
-  stock: number;
-  disponible: boolean;
-}
-
-const columns: TableColumn<Producto>[] = [
-  {
-    header: 'Producto',
-    accessor: 'nombre',
-    sortable: true,
-  },
-  {
-    header: 'Precio',
-    accessor: 'precio',
-    align: 'right',
-    render: (value) => `$${value.toFixed(2)}`,
-  },
-  {
-    header: 'Stock',
-    accessor: 'stock',
-    align: 'center',
-    render: (value) => (
-      <span className={value < 10 ? 'text-red-600 font-bold' : ''}>
-        {value}
-      </span>
-    ),
-  },
-  {
-    header: 'Disponibilidad',
-    accessor: 'disponible',
-    align: 'center',
-    render: (value) => (
-      <span className={`
-        px-2 py-1 rounded text-xs font-bold
-        ${value ? 'bg-green-100 text-green-800' : 'bg-gray-100 text-gray-800'}
-      `}>
-        {value ? 'Disponible' : 'Agotado'}
-      </span>
-    ),
-  },
-];
-
-<Table
-  title="Inventario de Productos"
-  columns={columns}
-  data={productos}
-  variant="fullWidth"
-/>
-```
-
-## Archivos Relacionados
-
-- `Table.tsx` - Implementación del componente (561 líneas)
-- `Table.types.ts` - Tipos TypeScript (149 líneas)
-- `Table.stories.tsx` - Stories de Storybook (11 ejemplos)
-- `index.ts` - Exports del módulo
-
-## Referencias
-
-- [Figma Design](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4184-15615&m=dev)
-- `docs/colors.md` - Sistema de colores
-- `docs/typography.md` - Sistema tipográfico
-- `docs/spacing.md` - Sistema de espaciado
+# Table Component
+
+Componente de tabla flexible y accesible con soporte para sorting, variantes visuales y dark mode completo.
+
+## Características
+
+- ✅ **Definición de columnas flexible** con `accessor` y `render` custom
+- ✅ **Sorting** en columnas (controlado o no controlado)
+- ✅ **Variantes visuales**: basic, fullWidth, striped, grid
+- ✅ **Dark mode completo** en todos los estados
+- ✅ **Estados de loading y empty**
+- ✅ **Filas clickeables**
+- ✅ **TypeScript** con tipos estrictos y generics
+- ✅ **Accesibilidad** con roles y keyboard navigation
+
+## Uso Básico
+
+```tsx
+import { Table } from '@/components/Table';
+import type { TableColumn } from '@/components/Table';
+
+interface Usuario {
+  id: number;
+  nombre: string;
+  email: string;
+}
+
+const usuarios: Usuario[] = [
+  { id: 1, nombre: 'Juan Pérez', email: 'juan@example.com' },
+  { id: 2, nombre: 'María García', email: 'maria@example.com' },
+];
+
+const columns: TableColumn<Usuario>[] = [
+  { header: 'Nombre', accessor: 'nombre' },
+  { header: 'Email', accessor: 'email' },
+];
+
+function App() {
+  return (
+    <Table
+      title="Usuarios"
+      columns={columns}
+      data={usuarios}
+    />
+  );
+}
+```
+
+## Variantes
+
+### Basic
+Tabla estándar con padding y spacing consistente.
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={data}
+  variant="basic"
+/>
+```
+
+### Full Width
+Tabla que ocupa todo el ancho disponible.
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={data}
+  variant="fullWidth"
+/>
+```
+
+### Striped (Filas Alternas)
+Filas con fondo alternado para mejor legibilidad.
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={data}
+  variant="striped"
+/>
+```
+
+### Grid (Con Bordes)
+Tabla con bordes alrededor de las celdas.
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={data}
+  variant="grid"
+/>
+```
+
+## Sorting
+
+### Sorting No Controlado (Interno)
+
+```tsx
+const columns: TableColumn<Usuario>[] = [
+  {
+    header: 'Nombre',
+    accessor: 'nombre',
+    sortable: true, // Habilitar sorting
+  },
+  {
+    header: 'Email',
+    accessor: 'email',
+    sortable: true,
+  },
+];
+
+<Table columns={columns} data={data} />
+```
+
+### Sorting Controlado (Externo)
+
+```tsx
+const [sortColumn, setSortColumn] = useState<keyof Usuario | null>(null);
+const [sortDirection, setSortDirection] = useState<SortDirection>(null);
+
+const handleSort = (column: keyof Usuario | string, direction: SortDirection) => {
+  setSortColumn(column as keyof Usuario);
+  setSortDirection(direction);
+
+  // Ordenar los datos
+  const sorted = [...data].sort((a, b) => {
+    // Lógica de ordenamiento
+  });
+  setData(sorted);
+};
+
+<Table
+  columns={columns}
+  data={data}
+  sortColumn={sortColumn}
+  sortDirection={sortDirection}
+  onSort={handleSort}
+/>
+```
+
+## Render Custom
+
+Puedes personalizar cómo se renderiza el contenido de una celda:
+
+```tsx
+const columns: TableColumn<Usuario>[] = [
+  {
+    header: 'Estado',
+    accessor: 'estado',
+    render: (value, row, index) => (
+      <span
+        className={`
+          px-2 py-1 rounded-md text-xs font-bold
+          ${value === 'activo' ? 'bg-green-100 text-green-800' : 'bg-red-100 text-red-800'}
+        `}
+      >
+        {value}
+      </span>
+    ),
+  },
+];
+```
+
+## Accessor Function
+
+Puedes usar una función para acceder a valores anidados o calculados:
+
+```tsx
+const columns: TableColumn<Usuario>[] = [
+  {
+    header: 'Nombre Completo',
+    accessor: (row) => `${row.nombre} ${row.apellido}`,
+  },
+  {
+    header: 'Email',
+    accessor: (row) => row.contacto.email.toLowerCase(),
+  },
+];
+```
+
+## Alineación de Columnas
+
+```tsx
+const columns: TableColumn<Usuario>[] = [
+  {
+    header: 'ID',
+    accessor: 'id',
+    align: 'center', // 'left' | 'center' | 'right'
+    width: '80px',   // Ancho fijo
+  },
+  {
+    header: 'Nombre',
+    accessor: 'nombre',
+    align: 'left',
+  },
+];
+```
+
+## Estados
+
+### Loading
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={[]}
+  loading={true}
+  loadingRows={5}
+/>
+```
+
+### Empty
+
+```tsx
+<Table
+  title="Usuarios"
+  columns={columns}
+  data={[]}
+  emptyMessage="No hay usuarios registrados"
+/>
+```
+
+## Filas Clickeables
+
+```tsx
+const handleRowClick = (row: Usuario, index: number) => {
+  console.log('Clicked:', row);
+  // Navegar a detalle, abrir modal, etc.
+};
+
+<Table
+  columns={columns}
+  data={data}
+  onRowClick={handleRowClick}
+/>
+```
+
+## Props
+
+### TableProps
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `title` | `string` | `undefined` | Título opcional de la tabla |
+| `columns` | `TableColumn<T>[]` | **Required** | Definición de las columnas |
+| `data` | `T[]` | **Required** | Datos de las filas |
+| `variant` | `'basic' \| 'fullWidth' \| 'striped' \| 'grid'` | `'basic'` | Variante visual |
+| `showBorder` | `boolean` | `true` | Si se muestra el borde del container |
+| `showShadow` | `boolean` | `true` | Si se muestra la sombra del container |
+| `onRowClick` | `(row: T, index: number) => void` | `undefined` | Callback al hacer click en una fila |
+| `onSort` | `(column: string, direction: SortDirection) => void` | `undefined` | Callback al cambiar el sort |
+| `sortColumn` | `keyof T \| string` | `undefined` | Columna ordenada (controlado) |
+| `sortDirection` | `SortDirection` | `undefined` | Dirección de sort (controlado) |
+| `fullWidth` | `boolean` | `false` | Si ocupa todo el ancho |
+| `emptyMessage` | `string` | `'No hay datos disponibles'` | Mensaje cuando no hay datos |
+| `loading` | `boolean` | `false` | Si está cargando |
+| `loadingRows` | `number` | `5` | Número de rows skeleton |
+| `className` | `string` | `''` | Clases CSS adicionales |
+| `id` | `string` | `undefined` | ID único |
+
+### TableColumn
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `header` | `string` | **Required** | Título del header |
+| `accessor` | `keyof T \| (row: T) => any` | **Required** | Key o función para obtener valor |
+| `sortable` | `boolean` | `false` | Si la columna es sortable |
+| `render` | `(value: any, row: T, index: number) => ReactNode` | `undefined` | Función custom de render |
+| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Alineación del contenido |
+| `width` | `string` | `undefined` | Ancho de la columna |
+
+## Dark Mode
+
+El componente Table se adapta automáticamente a dark mode usando los tokens de color del sistema:
+
+```tsx
+// Los colores se adaptan automáticamente
+<Table
+  columns={columns}
+  data={data}
+  // En light mode: bg-white, text-content-primary
+  // En dark mode: bg-dark-bg-primary, text-dark-content-primary
+/>
+```
+
+## Accesibilidad
+
+- ✅ Headers clickeables tienen `role="button"` y `tabIndex={0}`
+- ✅ Soporta navegación por teclado (Enter y Space)
+- ✅ Estados de sort anunciados visualmente con iconos
+- ✅ Filas clickeables con keyboard support
+
+## Ejemplos Avanzados
+
+### Tabla de Productos con Render Custom
+
+```tsx
+interface Producto {
+  id: number;
+  nombre: string;
+  precio: number;
+  stock: number;
+  disponible: boolean;
+}
+
+const columns: TableColumn<Producto>[] = [
+  {
+    header: 'Producto',
+    accessor: 'nombre',
+    sortable: true,
+  },
+  {
+    header: 'Precio',
+    accessor: 'precio',
+    align: 'right',
+    render: (value) => `$${value.toFixed(2)}`,
+  },
+  {
+    header: 'Stock',
+    accessor: 'stock',
+    align: 'center',
+    render: (value) => (
+      <span className={value < 10 ? 'text-red-600 font-bold' : ''}>
+        {value}
+      </span>
+    ),
+  },
+  {
+    header: 'Disponibilidad',
+    accessor: 'disponible',
+    align: 'center',
+    render: (value) => (
+      <span className={`
+        px-2 py-1 rounded text-xs font-bold
+        ${value ? 'bg-green-100 text-green-800' : 'bg-gray-100 text-gray-800'}
+      `}>
+        {value ? 'Disponible' : 'Agotado'}
+      </span>
+    ),
+  },
+];
+
+<Table
+  title="Inventario de Productos"
+  columns={columns}
+  data={productos}
+  variant="fullWidth"
+/>
+```
+
+## Archivos Relacionados
+
+- `Table.tsx` - Implementación del componente (561 líneas)
+- `Table.types.ts` - Tipos TypeScript (149 líneas)
+- `Table.stories.tsx` - Stories de Storybook (11 ejemplos)
+- `index.ts` - Exports del módulo
+
+## Referencias
+
+- [Figma Design](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4184-15615&m=dev)
+- `docs/colors.md` - Sistema de colores
+- `docs/typography.md` - Sistema tipográfico
+- `docs/spacing.md` - Sistema de espaciado