@sfperusacdev/sf-ui 0.2.5 → 0.2.6

package/dist/theme/dark.css

@@ -77,6 +77,7 @@
   --sf-modal-close-hover-text: #f1f5f9;
 
   --sf-card-bg: #1e293b;
+  --sf-section-panel-bg: #334155;
   --sf-card-border: #334155;
   --sf-card-title: #f1f5f9;
   --sf-card-subtitle: #94a3b8;

package/dist/theme/sf-tokens.css

@@ -111,6 +111,7 @@
 
   /* Cards / layout */
   --sf-card-bg: #ffffff;
+  --sf-section-panel-bg: #e5e7eb;
   --sf-card-border: #e5e7eb;
   --sf-card-shadow: 0 1px 2px rgb(0 0 0 / 0.05);
   --sf-card-shadow-hover: 0 4px 6px rgb(0 0 0 / 0.07);

package/dist/types/src/components/dashboard/CardNote.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+export type CardNoteTone = "info" | "warning";
+export type CardNoteProps = {
+    /** Cómo leer el dato de la tarjeta, en una frase. */
+    text: ReactNode;
+    tone?: CardNoteTone;
+    className?: string;
+};
+/**
+ * Nota al pie de una tarjeta o de un panel: explica cómo leer el dato con el mismo tintado que el pie de
+ * `MetricBarList`. Para procedencia de datos (período, fuentes, confianza) está `EvidenceFootnote`.
+ */
+export declare const CardNote: ({ text, tone, className }: CardNoteProps) => import("react").JSX.Element;

package/dist/types/src/components/dashboard/DashboardBoard.d.ts

@@ -0,0 +1,37 @@
+import { ReactNode } from 'react';
+/** Una fila del tablero: bloque ancho a la izquierda y, si viene, uno angosto a la derecha (2/3 · 1/3). */
+export type DashboardBoardBlock = {
+    left?: ReactNode;
+    right?: ReactNode;
+};
+/** Pieza que no aplica a esta empresa o a este contexto, con el motivo que se le explica al usuario. */
+export type DashboardBoardHiddenPiece = {
+    title: string;
+    reason: string;
+};
+export type DashboardBoardProps = {
+    /** Indicadores de la fila superior; los `null`/`false` se descartan y la grilla se ajusta a 3, 4 o 5 columnas. */
+    kpis?: ReactNode[];
+    /** Avisos informativos que van arriba de todo (uno por `Alert`). */
+    notes?: string[];
+    /** Piezas ocultas: se listan en un solo aviso de advertencia. */
+    hidden?: DashboardBoardHiddenPiece[];
+    hiddenTitle?: (count: number) => string;
+    /** Panel de detalle abierto (p. ej. `DetailPanel`); se pinta entre los indicadores y el bloque principal. */
+    detail?: ReactNode;
+    primary?: DashboardBoardBlock;
+    secondary?: DashboardBoardBlock;
+};
+/**
+ * Disposición de un tablero: avisos, fila de indicadores, panel de detalle y hasta dos filas de bloques
+ * (principal y secundario) con la proporción 2/3 · 1/3 cuando la fila tiene dos bloques. Va dentro de
+ * `DashboardLayout` o de `DashboardPageFrame`, que ponen el espacio vertical entre piezas.
+ */
+export declare const DashboardBoard: ({ kpis, notes, hidden, hiddenTitle, detail, primary, secondary, }: DashboardBoardProps) => import("react").JSX.Element;
+export type DashboardCardRowProps = {
+    /** Tarjetas de la fila; los `null`/`false` se descartan. Con tres o más van a 3 columnas, si no a 2. */
+    children: ReactNode[];
+    className?: string;
+};
+/** Tarjetas del mismo alto dentro de una sección (p. ej. Sexo · Edad · Antigüedad). */
+export declare const DashboardCardRow: ({ children, className }: DashboardCardRowProps) => import("react").JSX.Element;

package/dist/types/src/components/dashboard/DashboardBoard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/components/dashboard/DashboardCard.d.ts

@@ -15,6 +15,11 @@ export type DashboardCardProps = {
      * una sola fila, en vez de recortar con `truncate` (acabado actual, `false` por defecto). Útil con
      * títulos largos + `headerAction` ancho (ej. un selector de rango de fechas). */
     headerWrap?: boolean;
+    /** `false` quita la línea entre la cabecera y el cuerpo (tarjetas de tablero con título grande). */
+    headerDivider?: boolean;
+    /** "board" = la tarjeta de los tableros: cabecera `md` que pasa a dos líneas y sin divisor. Cada una de esas
+     * tres props se puede seguir fijando aparte; `look` solo cambia sus valores por defecto. */
+    look?: "default" | "board";
     /** Contenido opcional bajo el cuerpo, separado por un borde — ej. un resumen o un link "ver todo". */
     footer?: ReactNode;
     /** Estado del cuerpo. "idle" (por defecto) = `children` tal cual. Ver `DashboardCardState`. */
@@ -34,7 +39,7 @@ export type DashboardCardProps = {
     className?: string;
     children?: ReactNode;
 };
-export declare const DashboardCard: ({ title, subtitle, icon, headerAction, variant, span, padding, headerSize, headerWrap, footer, state, loadingMessage, errorMessage, emptyMessage, onRetry, retryLabel, minHeight, bodyOverflow, className, children, }: DashboardCardProps) => import("react").JSX.Element;
+export declare const DashboardCard: ({ title, subtitle, icon, headerAction, variant, span, padding, look, headerSize, headerWrap, headerDivider, footer, state, loadingMessage, errorMessage, emptyMessage, onRetry, retryLabel, minHeight, bodyOverflow, className, children, }: DashboardCardProps) => import("react").JSX.Element;
 type DashboardGridProps = {
     cols?: 2 | 3 | 4 | 5 | 6;
     gap?: "sm" | "md" | "lg";
@@ -58,10 +63,13 @@ type DashboardSectionProps = {
     icon?: ReactNode;
     /** Tamaño del tile de `icon`. "md" (por defecto) = 1.75rem, acabado actual. "lg" = 2.5rem. */
     iconSize?: "md" | "lg";
+    /** "plain" (por defecto) = sin fondo, acabado actual. "panel" la encierra en un recuadro gris redondeado
+     * (`--sf-section-panel-bg`) que agrupa visualmente sus tarjetas, como las secciones de los tableros. */
+    variant?: "plain" | "panel";
     className?: string;
     children?: ReactNode;
 };
-export declare const DashboardSection: ({ title, subtitle, action, icon, iconSize, className, children, }: DashboardSectionProps) => import("react").JSX.Element;
+export declare const DashboardSection: ({ title, subtitle, action, icon, iconSize, variant, className, children, }: DashboardSectionProps) => import("react").JSX.Element;
 type DashboardStatBarProps = {
     items: StatBarItem[];
     className?: string;

package/dist/types/src/components/dashboard/DashboardPageFrame.d.ts

@@ -0,0 +1,43 @@
+import { ReactNode } from 'react';
+export type DashboardDateRange = {
+    from: string;
+    to: string;
+};
+export type DashboardPageFrameProps = {
+    title: string;
+    /** La pregunta que responde el tablero, debajo del título. */
+    subtitle?: string;
+    /** Rango aplicado (YYYY-MM-DD). El marco guarda un borrador aparte hasta que el usuario pulsa «Aplicar». */
+    range: DashboardDateRange;
+    onApply: (range: DashboardDateRange) => void;
+    /** Devuelve el mensaje de error si el borrador no es válido; `null` si se puede aplicar. */
+    validate?: (range: DashboardDateRange) => string | null;
+    /** Error del rango ya aplicado (p. ej. venía inválido en la URL): se muestra y no se pintan los hijos. */
+    error?: string | null;
+    /** Hay consultas en curso: el botón «Aplicar» gira y el chip de estado cuenta los segundos. */
+    loading?: boolean;
+    /** Momento (epoch ms) del dato más antiguo en pantalla; alimenta el chip «datos de las HH:MM». */
+    updatedAt?: number | null;
+    /** El corte es el día de hoy: el chip dice «datos en vivo». */
+    live?: boolean;
+    /** Texto del corte a la derecha del chip, ya formateado (p. ej. «corte 30 set. 2026»). */
+    cutoffLabel?: string;
+    onRefresh?: () => void;
+    refreshLabel?: string;
+    /** Texto del tercer campo del filtro cuando el borrador coincide con lo aplicado. */
+    compareLabel?: string;
+    /** Texto del tercer campo cuando el borrador cambió y falta pulsar «Aplicar». */
+    pendingLabel?: string;
+    applyLabel?: string;
+    filterAriaLabel?: string;
+    /** Segundos de espera antes de mostrar el contador en el chip. */
+    slowAfterSeconds?: number;
+    className?: string;
+    children?: ReactNode;
+};
+/**
+ * Marco de una página de tablero: título y pregunta, chip de estado (en vivo / calculando / hora del dato),
+ * botón de actualizar y el filtro de rango de fechas con borrador y validación. Los hijos van dentro de
+ * `DashboardLayout`, así que `DashboardBoard` encaja directamente.
+ */
+export declare const DashboardPageFrame: ({ title, subtitle, range, onApply, validate, error, loading, updatedAt, live, cutoffLabel, onRefresh, refreshLabel, compareLabel, pendingLabel, applyLabel, filterAriaLabel, slowAfterSeconds, className, children, }: DashboardPageFrameProps) => import("react").JSX.Element;

package/dist/types/src/components/dashboard/DashboardPageFrame.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/components/dashboard/DashboardPlaceholder.d.ts

@@ -0,0 +1,18 @@
+export type DashboardPlaceholderShape = "kpi" | "bars" | "chart" | "list";
+export type DashboardPlaceholderState = "loading" | "error";
+export type DashboardPlaceholderProps = {
+    /** Título de la pieza que ocupará este lugar cuando llegue su dato. */
+    title: string;
+    /** Silueta que se dibuja mientras carga: la misma forma que tendrá la pieza, para que la página no salte. */
+    shape?: DashboardPlaceholderShape;
+    state?: DashboardPlaceholderState;
+    errorMessage?: string;
+    onRetry?: () => void;
+    className?: string;
+};
+/**
+ * Lugar de una pieza de tablero que todavía no tiene dato: en carga dibuja una silueta con la forma de la
+ * pieza (la de `shape="kpi"` mide lo mismo que `KPICard size="lg"`); en error muestra el mensaje y el botón de
+ * reintento de `DashboardCard`.
+ */
+export declare const DashboardPlaceholder: ({ title, shape, state, errorMessage, onRetry, className, }: DashboardPlaceholderProps) => import("react").JSX.Element;

package/dist/types/src/components/dashboard/DetailPanel.d.ts

@@ -0,0 +1,38 @@
+import { ReactNode } from 'react';
+import { DetailController, DetailSpec } from './detailTypes';
+export type { DetailColumn, DetailController, DetailGroup, DetailSpec } from './detailTypes';
+/** Estado del `DetailPanel` de un tablero: una sola cifra abierta a la vez; volver a pulsarla la cierra. */
+export declare const useDetailPanel: <Row>() => DetailController<Row>;
+type FlatRow = Record<string, unknown>;
+export type DetailPanelProps<Row> = {
+    detail: DetailController<Row>;
+    /** Convierte cada fila al objeto plano que leen las columnas (`column.key`). Por defecto la fila tal cual. */
+    rowMapper?: (row: Row) => FlatRow;
+    subtitle?: string;
+    /** Texto del contador de la cabecera, con el total ya formateado por quien llama. */
+    countLabel?: (total: number) => string;
+    /** Filas que se muestran en pantalla; el resto sale por Excel, para no convertir el tablero en una tabla. */
+    previewRows?: number;
+    /** Nota bajo la tabla cuando hay más filas que `previewRows`. */
+    previewNote?: (shown: number, total: number) => string;
+    /** Nota bajo la tabla cuando caben todas. */
+    totalNote?: (total: number) => string;
+    emptyMessage?: string;
+    closeLabel?: string;
+    exportLabel?: string;
+    /** Nombre del archivo exportado, sin extensión. */
+    exportFilename?: (spec: DetailSpec<Row>, groupId: string | null) => string;
+    /** Acciones extra junto a «Exportar Excel» (p. ej. abrir la lista en otro módulo); reciben las filas visibles. */
+    actions?: (context: {
+        spec: DetailSpec<Row>;
+        groupId: string | null;
+        groupTitle: string | null;
+        rows: Row[];
+    }) => ReactNode;
+};
+/**
+ * Panel de «qué hay detrás de la cifra»: título, contador, frase que explica la lista, una pestaña por caso
+ * con su acción, las primeras filas en una `CustomTable` y la exportación completa a Excel. Se abre desde
+ * `DrilldownKPICard`, `DrilldownAlertList` o cualquier pieza que llame a `detail.toggle(spec)`.
+ */
+export declare const DetailPanel: <Row>({ detail, rowMapper, subtitle, countLabel, previewRows, previewNote, totalNote, emptyMessage, closeLabel, exportLabel, exportFilename, actions, }: DetailPanelProps<Row>) => import("react").JSX.Element | null;

package/dist/types/src/components/dashboard/DetailPanel.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/components/dashboard/DrilldownCards.d.ts

@@ -0,0 +1,68 @@
+import { ReactNode } from 'react';
+import { KPICardAccentTone, KPICardTrendDirection } from '../cards/KPICard';
+import { DetailController, DetailSpec } from './detailTypes';
+import { EventStatus } from './types';
+/** Hay algo que mostrar: filas sueltas o filas dentro de algún caso. */
+export declare const detailHasRows: <Row>(spec: DetailSpec<Row> | null | undefined) => spec is DetailSpec<Row>;
+export type DrilldownKPICardProps<Row> = {
+    label: string;
+    /** Valor ya formateado (la librería no decide el separador de miles). */
+    value: string | number;
+    sublabel?: string;
+    icon?: ReactNode;
+    accentTone?: KPICardAccentTone;
+    /** El indicador destacado de la fila (`KPICard variant="filled"`). */
+    primary?: boolean;
+    /** Variación porcentual contra el período anterior; `null` cuando no hay base para comparar. */
+    trend?: number | null;
+    trendDirection?: KPICardTrendDirection;
+    trendLabel?: string;
+    detail: DetailController<Row>;
+    /** Lo que se abre al hacer clic; sin filas, la tarjeta no es clicable. */
+    spec?: DetailSpec<Row> | null;
+};
+/** `KPICard` de tablero que abre su detalle en el `DetailPanel` compartido y se marca cuando está abierto. */
+export declare const DrilldownKPICard: <Row>({ label, value, sublabel, icon, accentTone, primary, trend, trendDirection, trendLabel, detail, spec, }: DrilldownKPICardProps<Row>) => import("react").JSX.Element;
+export type DrilldownAlertItem<Row> = {
+    label: string;
+    /** Valor ya formateado; con `count` en 0 la fila toma `zeroTone`. */
+    value: ReactNode;
+    count: number;
+    tone: EventStatus;
+    description?: string;
+    spec?: DetailSpec<Row> | null;
+};
+export type DrilldownAlertListProps<Row> = {
+    items: DrilldownAlertItem<Row>[];
+    detail: DetailController<Row>;
+    /** Tono de una fila cuya cifra es 0 (nada pendiente). */
+    zeroTone?: EventStatus;
+    emptyMessage?: ReactNode;
+};
+/** Lista de pendientes en una tarjeta: cada fila abre su detalle en el `DetailPanel` compartido. */
+export declare const DrilldownAlertList: <Row>({ items, detail, zeroTone, emptyMessage, }: DrilldownAlertListProps<Row>) => import("react").JSX.Element;
+export type DetailPreviewItem = {
+    key: string;
+    /** Código o documento, en monoespaciada delante del texto principal. */
+    code?: string;
+    primary: string;
+    /** Texto corto a la derecha (p. ej. la situación o los días). */
+    meta?: string;
+};
+export type DetailPreviewListProps = {
+    items: DetailPreviewItem[];
+    /** Total real de la lista; se muestra grande arriba de la vista previa. */
+    total: number;
+    /** Total ya formateado; por defecto `String(total)`. */
+    totalLabel?: string;
+    /** Sustantivo junto al total (p. ej. «personas»). */
+    unit?: string;
+    /** Cuántos elementos se muestran antes del botón. */
+    previewCount?: number;
+    emptyText: string;
+    /** Abre el detalle completo; el botón dice «Ver las N» o `openLabel`. */
+    onOpen: () => void;
+    openLabel?: string;
+};
+/** Las primeras filas de una lista con su total y el acceso al detalle completo. */
+export declare const DetailPreviewList: ({ items, total, totalLabel, unit, previewCount, emptyText, onOpen, openLabel, }: DetailPreviewListProps) => import("react").JSX.Element;

package/dist/types/src/components/dashboard/detailTypes.d.ts

@@ -0,0 +1,31 @@
+/** Columna del panel de detalle: `key` indexa la fila ya aplanada (ver `DetailPanel.rowMapper`). */
+export type DetailColumn = {
+    key: string;
+    header: string;
+};
+/** Un caso distinto dentro de la misma cifra: su pestaña, la acción que se sugiere y sus filas. */
+export type DetailGroup<Row> = {
+    id: string;
+    title: string;
+    note?: string;
+    rows: Row[];
+};
+/** Lo que hay detrás de una cifra: las filas, cómo se leen (frase, columnas) y, si hay casos, una pestaña por caso. */
+export type DetailSpec<Row> = {
+    id: string;
+    title: string;
+    rows: Row[];
+    columns: DetailColumn[];
+    /** Qué es la lista y qué hacer con ella, en una frase. */
+    description?: string;
+    groups?: DetailGroup<Row>[];
+    /** Nota al pie, p. ej. quiénes quedaron fuera de la lista y por qué. */
+    footnote?: string;
+};
+/** Estado del panel de detalle compartido por las piezas de un tablero: qué cifra está abierta. */
+export type DetailController<Row> = {
+    open: DetailSpec<Row> | null;
+    /** Abre esa cifra, o la cierra si ya estaba abierta. */
+    toggle: (spec: DetailSpec<Row>) => void;
+    close: () => void;
+};

package/dist/types/src/components/dashboard/index.d.ts

@@ -22,6 +22,18 @@ export { DashboardCard, DashboardGrid, DashboardSection, DashboardStatBar, Dashb
 export type { DashboardCardProps } from './DashboardCard';
 export { DetailSidePanel } from './DetailSidePanel';
 export type { DetailSidePanelProps, DetailSidePanelRow, DetailSidePanelSecondaryItem } from './DetailSidePanel';
+export { CardNote } from './CardNote';
+export type { CardNoteProps, CardNoteTone } from './CardNote';
+export { DashboardBoard, DashboardCardRow } from './DashboardBoard';
+export type { DashboardBoardBlock, DashboardBoardHiddenPiece, DashboardBoardProps, DashboardCardRowProps } from './DashboardBoard';
+export { DashboardPageFrame } from './DashboardPageFrame';
+export type { DashboardDateRange, DashboardPageFrameProps } from './DashboardPageFrame';
+export { DashboardPlaceholder } from './DashboardPlaceholder';
+export type { DashboardPlaceholderProps, DashboardPlaceholderShape, DashboardPlaceholderState } from './DashboardPlaceholder';
+export { DetailPanel, useDetailPanel } from './DetailPanel';
+export type { DetailPanelProps, DetailColumn, DetailController, DetailGroup, DetailSpec } from './DetailPanel';
+export { DrilldownKPICard, DrilldownAlertList, DetailPreviewList, detailHasRows } from './DrilldownCards';
+export type { DrilldownKPICardProps, DrilldownAlertItem, DrilldownAlertListProps, DetailPreviewItem, DetailPreviewListProps, } from './DrilldownCards';
 export { DetailSection } from './DetailSection';
 export type { DetailSectionProps, DetailSectionRow, DetailSectionTone, DetailSectionDensity } from './DetailSection';
 export type { StepStatus, StepItem, CalendarBadgeVariant, CalendarDayBadge, DonutGaugeSize, DashboardCardVariant, DashboardCardState, EventStatus, EventItem, AlertRowItem, AlertRowSeverity, AlertRowListHeaderLabels, AlertActionItem, AlertDensity, StatBarItem, } from './types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sfperusacdev/sf-ui",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "SF UI — librería de componentes React (inputs, tablas, hooks) para aplicaciones SF Perú.",
   "type": "module",
   "main": "./dist/sf-ui.umd.cjs",