@kapiuara/ui 0.0.0-stage → 0.1.1

package/dist/components/data/KapiPagination.d.ts

@@ -0,0 +1,36 @@
+import { type HTMLAttributes } from "react";
+import "./KapiTable.css";
+import type { KapiLabelsOverride } from "../labelsLogic";
+export type KapiPaginationLabels = {
+    /** Texto antes del selector de tamaño de página. */
+    rowsPerPage: string;
+    prevPage: string;
+    nextPage: string;
+    /** Conector del rango: "1–10 de 42". */
+    of: string;
+    /** Nombre de la navegación. */
+    nav: string;
+};
+/** Atributos nativos (`id`, `style`, `data-*`…) van al `<nav>`; `aria-label` gana sobre `labels.nav`. */
+export type KapiPaginationProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+    /** Página actual, desde 1 (se acota al rango válido). */
+    page: number;
+    /** Filas por página. */
+    pageSize: number;
+    /** Total de filas (de todas las páginas); define la cantidad de páginas. */
+    total: number;
+    /** Se llama con la página nueva (desde 1) al navegar. */
+    onPageChange: (page: number) => void;
+    /** El selector de tamaño aparece sólo si vienen `pageSizeOptions` y `onPageSizeChange`. */
+    pageSizeOptions?: number[];
+    /** Se llama con el tamaño elegido en el selector; junto con `pageSizeOptions` lo muestra. */
+    onPageSizeChange?: (pageSize: number) => void;
+    /** Textos fijos (clave `pagination`). */
+    labels?: KapiLabelsOverride<KapiPaginationLabels> | undefined;
+};
+/**
+ * Paginador standalone (rango, anterior/siguiente y tamaño de página). Reusa el footer de la tabla.
+ * En los extremos, anterior/siguiente quedan `aria-disabled` (siguen enfocables e ignoran la activación)
+ * para que el foco no se pierda al llegar a la primera o la última página.
+ */
+export declare function KapiPagination({ page, pageSize, total, onPageChange, pageSizeOptions, onPageSizeChange, labels, className, "aria-label": ariaLabel, ...rest }: KapiPaginationProps): import("react").JSX.Element;

package/dist/components/data/KapiPagination.js

@@ -0,0 +1,102 @@
+"use client";
+import { useLabels as e } from "../locale/KapiLocaleProvider.js";
+import { KapiSelect as t } from "../inputs/KapiSelect.js";
+import { joinClasses as n } from "../rootProps.js";
+import { computePagination as r } from "./tableLogic.js";
+/* empty css              */
+import { jsx as i, jsxs as a } from "react/jsx-runtime";
+import { useEffect as o } from "react";
+import { ChevronLeft as s, ChevronRight as c } from "lucide-react";
+//#region src/components/data/KapiPagination.tsx
+var l = {
+	rowsPerPage: "Filas por página",
+	prevPage: "Página anterior",
+	nextPage: "Página siguiente",
+	of: "de",
+	nav: "Paginación"
+};
+function u({ page: u, pageSize: d, total: f, onPageChange: p, pageSizeOptions: m, onPageSizeChange: h, labels: g, className: _, "aria-label": v, ...y }) {
+	let b = e("pagination", l, g), x = r({
+		page: u,
+		pageSize: d,
+		total: f
+	});
+	return o(() => {
+		x.page !== u && p(x.page);
+	}, [
+		x.page,
+		u,
+		p
+	]), /* @__PURE__ */ a("nav", {
+		...y,
+		className: n("kapi-tablefoot", _),
+		"aria-label": v ?? b.nav,
+		children: [/* @__PURE__ */ a("div", {
+			className: "kapi-tablefoot__l",
+			children: [/* @__PURE__ */ a("span", { children: [
+				x.from,
+				"–",
+				x.to,
+				" ",
+				b.of,
+				" ",
+				f
+			] }), m && h && /* @__PURE__ */ a("div", {
+				className: "kapi-tablefoot__size",
+				children: [/* @__PURE__ */ i("span", { children: b.rowsPerPage }), /* @__PURE__ */ i(t, {
+					size: "sm",
+					searchable: !1,
+					"aria-label": b.rowsPerPage,
+					options: m.map((e) => ({
+						value: String(e),
+						label: String(e)
+					})),
+					value: String(d),
+					onChange: (e) => {
+						e !== null && h(Number(e));
+					}
+				})]
+			})]
+		}), /* @__PURE__ */ a("div", {
+			className: "kapi-tablefoot__r",
+			children: [
+				/* @__PURE__ */ i("button", {
+					type: "button",
+					className: "kapi-tablefoot__btn",
+					"aria-label": b.prevPage,
+					"aria-disabled": !x.canPrev || void 0,
+					onClick: () => {
+						x.canPrev && p(x.page - 1);
+					},
+					children: /* @__PURE__ */ i(s, {
+						size: 16,
+						strokeWidth: 2
+					})
+				}),
+				/* @__PURE__ */ a("span", {
+					"aria-live": "polite",
+					children: [
+						x.page,
+						" / ",
+						x.totalPages
+					]
+				}),
+				/* @__PURE__ */ i("button", {
+					type: "button",
+					className: "kapi-tablefoot__btn",
+					"aria-label": b.nextPage,
+					"aria-disabled": !x.canNext || void 0,
+					onClick: () => {
+						x.canNext && p(x.page + 1);
+					},
+					children: /* @__PURE__ */ i(c, {
+						size: 16,
+						strokeWidth: 2
+					})
+				})
+			]
+		})]
+	});
+}
+//#endregion
+export { u as KapiPagination };

package/dist/components/data/KapiTable.d.ts

@@ -0,0 +1,245 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type KapiMenuItem } from "../overlays/KapiContextMenu";
+import { type KapiTableColumnVisibility, type KapiTableColumnWidths, type KapiTableSortState, type KapiTableSortValue, type KapiTableFilterState } from "./tableLogic";
+import { type KapiRootProps } from "../rootProps";
+import "../overlays/overlays.css";
+import "./KapiTable.css";
+import type { KapiLabelsOverride } from "../labelsLogic";
+export type { KapiTableSortDirection, KapiTableSortState, KapiTableSortValue, KapiTableFilterState } from "./tableLogic";
+/** Valor primitivo de una celda para copiar, filtrar o exportar (`null`/`undefined` = vacío). */
+export type KapiTableCellValue = string | number | boolean | Date | null | undefined;
+/** Lo común a toda columna de `KapiTable<T>` (todo salvo `key` y `render`). */
+type KapiTableColumnBase<T> = {
+    /** Encabezado de la columna. */
+    label: ReactNode;
+    /** Ancho en px. En columnas `sticky` fija el ancho y el offset de las siguientes. */
+    width?: number;
+    /** Se clava a la izquierda (después de la columna de checkboxes, si hay). */
+    sticky?: boolean;
+    /** Absorbe el ancho sobrante (permite wrap). Pensada para UNA columna. */
+    flex?: boolean;
+    /** Alineación del contenido de la celda y del encabezado. */
+    align?: "left" | "center" | "right";
+    /** Muestra el botón copiar al hacer hover sobre la celda. */
+    copyable?: boolean;
+    /** Valor a copiar (default: `row[key]`). */
+    copyValue?: (row: T) => KapiTableCellValue;
+    /** Click en el header ordena asc/desc/ninguno. */
+    sortable?: boolean;
+    /** Valor por el que se ordena (default: `row[key]`). */
+    sortValue?: (row: T) => KapiTableSortValue;
+    /** Se puede ocultar desde el menú "Columnas". Default `true`; con `false` nunca se oculta. */
+    hideable?: boolean;
+    /** Se puede redimensionar arrastrando el borde. Default: el valor de `resizableColumns`. */
+    resizable?: boolean;
+    /** Ancho mínimo (px) al redimensionar. Default 60. */
+    minWidth?: number;
+    /** Entra en el filtro de la tabla (en "Todas" y en el selector de columna). Default `true`. */
+    filterable?: boolean;
+    /** Texto con el que compara el filtro, p. ej. para celdas que muestran un badge (default: `row[key]`). */
+    filterValue?: (row: T) => KapiTableCellValue;
+    /** Valor exportado al CSV (default: `copyValue` o `row[key]`). */
+    csvValue?: (row: T) => KapiTableCellValue;
+};
+/**
+ * Columna de `KapiTable<T>`. Sin `render`, `key` tiene que ser una propiedad de la fila (es lo que se
+ * muestra, y un error de tipeo no compila); con `render`, `key` es un identificador libre.
+ */
+export type KapiTableColumn<T> = KapiTableColumnBase<T> & ({
+    /** Propiedad de la fila que se muestra; también identifica la columna. */
+    key: keyof T & string;
+    /** Sin `render`, la celda muestra `row[key]`. */
+    render?: undefined;
+} | {
+    /** Identifica la columna (anchos, visibilidad, orden, filtro). */
+    key: string;
+    /** Contenido de la celda. */
+    render: (row: T) => ReactNode;
+});
+/** Opciones de "Exportar CSV". */
+export type KapiTableCsvOptions<T = never> = {
+    /** Nombre del archivo (se agrega `.csv` si falta). Default `"tabla.csv"`. */
+    fileName?: string;
+    /** Separador de campos. Default `","`. */
+    separator?: string;
+    /**
+     * Filas a exportar en vez de las que muestra la tabla (p. ej. el conjunto completo cuando la tabla
+     * recibe solo una página). Se exportan tal cual, en ese orden; una función se llama al exportar.
+     * Sin esta opción, las filas filtradas y ordenadas que recibe la tabla.
+     */
+    rows?: ReadonlyArray<T> | (() => ReadonlyArray<T>) | undefined;
+};
+/** Textos de la tabla (accesibilidad y header de acciones). */
+export type KapiTableLabels = {
+    /** Contenido sin filas (lo pisa `emptyMessage`). */
+    empty: string;
+    /** Contenido durante la carga con `loadingRows={0}` (lo pisa `loadingMessage`). */
+    loading: string;
+    selectAll: string;
+    /** Checkbox de una fila sin etiqueta propia: "Seleccionar fila 3". */
+    selectRow: string;
+    /** Checkbox de una fila con etiqueta (`rowLabel` o la primera columna): "Seleccionar Ana". */
+    selectRowNamed: string;
+    copy: string;
+    actions: string;
+    moreActions: string;
+    sortBy: string;
+    rowsPerPage: string;
+    prevPage: string;
+    nextPage: string;
+    expandRow: string;
+    columns: string;
+    resizeColumn: string;
+    filter: string;
+    filterPlaceholder: string;
+    filterColumn: string;
+    filterAll: string;
+    /** Conector "N de M": contador del filtro y rango del footer ("1–10 de 42"). */
+    of: string;
+    exportCsv: string;
+};
+export declare const DEFAULT_TABLE_LABELS: KapiTableLabels;
+/** Paginación presentacional: la tabla NO recorta `rows`, el padre pasa la página actual. */
+export type KapiTablePagination = {
+    /** Página actual (desde 1). */
+    page: number;
+    pageSize: number;
+    /** Total de filas (de todas las páginas). */
+    total: number;
+    onPageChange: (page: number) => void;
+    /** Con `onPageSizeChange`, muestra el selector de filas por página. */
+    pageSizeOptions?: number[];
+    onPageSizeChange?: (size: number) => void;
+};
+/** `className`/`style`/`id` (`KapiRootProps`) van a la carcasa `.kapi-table-shell` (herramientas + tabla + pie). */
+export type KapiTableProps<T, K extends keyof T = keyof T> = KapiRootProps & {
+    /** Definición de columnas (clave, encabezado, render, orden, filtro, ancho…). */
+    columns: ReadonlyArray<KapiTableColumn<T>>;
+    /** Filas a mostrar. */
+    rows: ReadonlyArray<T>;
+    /** Propiedad con el id único de la fila. Default `"id"`. */
+    keyField?: K;
+    /** Alto máximo del área con scroll. Se ignora con `fill`. */
+    maxHeight?: CSSProperties["maxHeight"];
+    /**
+     * Ocupa el 100% del alto del padre (que debe tener alto definido): el área de filas se estira y
+     * scrollea internamente, y el footer queda fijo abajo. Con `fill`, `maxHeight` se ignora.
+     */
+    fill?: boolean;
+    /** Dónde se muestra la barra de acciones masivas: arriba (estilo Gmail) o abajo. Default `"bottom"`. */
+    bulkActionsPlacement?: "top" | "bottom";
+    /** Textos fijos de la tabla (selección, paginación, columnas, filtro…). */
+    labels?: KapiLabelsOverride<KapiTableLabels> | undefined;
+    /** Columna de acciones: contenido custom por fila (botones). */
+    actions?: (row: T) => ReactNode;
+    /** Agrega el botón ⋯ en la columna de acciones, con estos ítems. */
+    rowMenu?: (row: T) => KapiMenuItem[];
+    /** Menú contextual de la tabla (doble click derecho). */
+    contextMenu?: KapiMenuItem[];
+    /** Se llama tras copiar una celda. */
+    onCopy?: (value: unknown) => void;
+    /** Columna de checkboxes. */
+    selectable?: boolean;
+    /** Con `selectable`: click en cualquier parte de la fila alterna la selección. */
+    rowSelect?: boolean;
+    /**
+     * Con `selectable`: etiqueta de la fila para el nombre accesible de su checkbox ("Seleccionar {etiqueta}").
+     * Default: el texto de la primera columna visible si es texto/número; si no, "Seleccionar fila N".
+     */
+    rowLabel?: (row: T) => string;
+    /** Selección controlada. Sin esta prop la tabla maneja su propio estado. */
+    selectedIds?: ReadonlyArray<T[K]>;
+    /** Recibe los ids seleccionados cada vez que cambia la selección (controlada o no). */
+    onSelectedIdsChange?: (ids: Array<T[K]>) => void;
+    /** Con `selectable` y selección no vacía: barra sticky de acciones masivas con las acciones que devuelve esta función. */
+    bulkActions?: (ctx: {
+        ids: Array<T[K]>;
+        clear: () => void;
+    }) => ReactNode;
+    /** Con `selectable`: Shift+clic selecciona (o deselecciona) el rango desde la última fila tildada. Default `true`. */
+    rangeSelect?: boolean;
+    /** Renderiza sólo las filas visibles (altura fija `rowHeight`). */
+    virtual?: boolean;
+    /** Alto fijo de fila en px para `virtual`. */
+    rowHeight?: number;
+    /** Orden controlado (`null` = sin orden). Sin esta prop la tabla maneja su propio estado. */
+    sort?: KapiTableSortState | null;
+    /** Orden inicial sin control. */
+    defaultSort?: KapiTableSortState | null;
+    /** Se llama al cambiar el orden desde el header. */
+    onSortChange?: (sort: KapiTableSortState | null) => void;
+    /** No reordena localmente (el servidor ya ordenó); el header igual emite `onSortChange`. */
+    manualSort?: boolean;
+    /** Footer de paginación (modo servidor/presentacional). */
+    pagination?: KapiTablePagination;
+    /** Reemplaza las filas por un estado de carga. */
+    loading?: boolean;
+    /** Cantidad de filas skeleton durante la carga (default 5). Con `0` se muestra el spinner con `loadingMessage`. */
+    loadingRows?: number;
+    /** Envuelve la tabla (y su paginación) en una card. Default `false`. */
+    card?: boolean;
+    /** Contenido cuando no hay filas. Default `labels.empty` ("Sin resultados"); `null` no muestra nada. */
+    emptyMessage?: ReactNode;
+    /** Contenido durante la carga. Default `labels.loading` ("Cargando…"); `null` no muestra nada. */
+    loadingMessage?: ReactNode;
+    /** Con `selectable`: define qué filas se pueden seleccionar (default: todas). */
+    isRowSelectable?: (row: T) => boolean;
+    /** Fila expandible: contenido que se muestra bajo la fila. No aplica con `virtual`. */
+    renderSubComponent?: (row: T) => ReactNode;
+    /** Expansión controlada. Sin esta prop la tabla maneja su propio estado. */
+    expandedIds?: ReadonlyArray<T[K]>;
+    /** Recibe los ids expandidos cada vez que cambia la expansión (controlada o no). */
+    onExpandedIdsChange?: (ids: Array<T[K]>) => void;
+    /** `card`: filas blandas y espaciadas, look de listado. Sólo visual; no cambia el comportamiento. */
+    density?: "default" | "card";
+    /** Resalta la fila al pasar el mouse (fondo tenue). Opt-in: apagado por defecto. */
+    rowHover?: boolean;
+    /** Muestra el botón "Columnas" (menú para mostrar/ocultar columnas `hideable`). */
+    columnToggle?: boolean;
+    /** Visibilidad controlada (`key → mostrada`; ausente = visible). Sin esta prop la tabla maneja su estado. */
+    columnVisibility?: KapiTableColumnVisibility;
+    /** Visibilidad inicial sin control. */
+    defaultColumnVisibility?: KapiTableColumnVisibility;
+    /** Se llama al mostrar u ocultar columnas. */
+    onColumnVisibilityChange?: (visibility: KapiTableColumnVisibility) => void;
+    /** Habilita el redimensionado por arrastre en todas las columnas (salvo `resizable: false`). */
+    resizableColumns?: boolean;
+    /** Anchos controlados (`key → px`). Sin esta prop la tabla maneja su estado. */
+    columnWidths?: KapiTableColumnWidths;
+    /** Anchos iniciales sin control. */
+    defaultColumnWidths?: KapiTableColumnWidths;
+    /** Se llama al soltar un redimensionado, con los anchos confirmados. */
+    onColumnWidthsChange?: (widths: KapiTableColumnWidths) => void;
+    /**
+     * Filtro de la tabla: un campo de texto y, al lado, la columna donde buscar ("Todas" por defecto =
+     * columnas visibles con `filterable` distinto de `false`). Cada palabra tiene que aparecer en alguna
+     * de esas columnas, sin distinguir mayúsculas ni acentos. Con filtro activo muestra "N de M".
+     */
+    filterable?: boolean;
+    /** Filtro controlado (`column: null` = todas). Sin esta prop la tabla maneja su estado. */
+    filter?: KapiTableFilterState;
+    /** Filtro inicial sin control. */
+    defaultFilter?: KapiTableFilterState;
+    /** Se llama al cambiar el filtro (con `manualFilter`, con debounce mientras se tipea). */
+    onFilterChange?: (filter: KapiTableFilterState) => void;
+    /** Modo servidor: no filtra localmente; sólo emite `onFilterChange` (para backends paginados). */
+    manualFilter?: boolean;
+    /** Debounce (ms) del texto con `manualFilter`. Default 300. */
+    filterDebounce?: number;
+    /**
+     * Botón "Exportar CSV": baja las filas filtradas y ordenadas con las columnas visibles (o las `rows`
+     * de las opciones, para exportar todo cuando la tabla recibe solo una página).
+     */
+    exportCsv?: boolean | KapiTableCsvOptions<T>;
+    /**
+     * Modo tarjeta automático: cuando la tabla mide menos de 600px de ancho (mobile o un panel
+     * angosto), cada fila se muestra como una tarjeta con "columna: valor". No aplica con `virtual`.
+     */
+    mobileCards?: boolean;
+};
+/**
+ * Tabla: header y columnas sticky, selección (controlada o interna), ordenamiento
+ * por header, columna de acciones fija, copiar por celda, virtualización de altura fija,
+ * drag-scroll con click derecho y menú contextual con doble click derecho.
+ */
+export declare function KapiTable<T, K extends keyof T = keyof T>({ columns, rows, keyField, maxHeight, fill, bulkActionsPlacement, className, style, id, labels, actions, rowMenu, contextMenu, onCopy, selectable, rowSelect, rowLabel, selectedIds, onSelectedIdsChange, bulkActions, rangeSelect, virtual, rowHeight, sort, defaultSort, onSortChange, manualSort, pagination, loading, loadingRows, card, emptyMessage, loadingMessage, isRowSelectable, renderSubComponent, expandedIds, onExpandedIdsChange, density, rowHover, columnToggle, columnVisibility, defaultColumnVisibility, onColumnVisibilityChange, resizableColumns, columnWidths, defaultColumnWidths, onColumnWidthsChange, filterable, filter, defaultFilter, onFilterChange, manualFilter, filterDebounce, exportCsv, mobileCards }: KapiTableProps<T, K>): import("react").JSX.Element;