@kapiuara/ui 0.0.0-stage → 0.1.1

package/dist/components/layout/KapiGrid.d.ts

@@ -0,0 +1,19 @@
+import type { HTMLAttributes } from "react";
+import { type KapiGap } from "./layoutPrimitives";
+import "./layout-primitives.css";
+export type KapiGridProps = HTMLAttributes<HTMLDivElement> & {
+    /** Espacio entre celdas: número = px, string = largo CSS. Default 12px. */
+    gap?: KapiGap;
+    /** Ancho mínimo de columna (número = px, string = largo CSS): `auto-fit` + `minmax`. Default 220px. */
+    min?: number | string;
+    /** Cantidad fija de columnas. Si se pasan `cols` y `min`, gana `cols`. */
+    cols?: number;
+    /**
+     * Responde al ancho de su contenedor (container queries) en vez del viewport: con `cols`, baja a
+     * 2 columnas bajo 768px y a 1 bajo 480px. Envuelve la grilla en un `div.kapi-gridx-cq`
+     * (`container: kapi-grid`), que también pueden consultar los hijos. Default `false`.
+     */
+    responsive?: boolean;
+};
+/** Grilla responsive: columnas fijas (`cols`) o fluidas por ancho mínimo (`min`). */
+export declare function KapiGrid({ gap, min, cols, responsive, className, style, children, ...rest }: KapiGridProps): import("react").JSX.Element;

package/dist/components/layout/KapiGrid.js

@@ -0,0 +1,25 @@
+"use client";
+import { gridProps as e } from "./layoutPrimitives.js";
+/* empty css                      */
+import { jsx as t } from "react/jsx-runtime";
+//#region src/components/layout/KapiGrid.tsx
+function n({ gap: n, min: r, cols: i, responsive: a = !1, className: o, style: s, children: c, ...l }) {
+	let u = /* @__PURE__ */ t("div", {
+		...l,
+		...e({
+			gap: n,
+			min: r,
+			cols: i,
+			responsive: a,
+			className: o,
+			style: s
+		}),
+		children: c
+	});
+	return a ? /* @__PURE__ */ t("div", {
+		className: "kapi-gridx-cq",
+		children: u
+	}) : u;
+}
+//#endregion
+export { n as KapiGrid };

package/dist/components/layout/KapiNotificationBell.d.ts

@@ -0,0 +1,75 @@
+import { type ButtonHTMLAttributes, type MouseEvent as ReactMouseEvent, type ReactNode, type Ref } from "react";
+import "./KapiNotificationBell.css";
+import type { KapiLabelsOverride } from "../labelsLogic";
+/** Una notificación de la campana. */
+export type KapiNotification<Id extends string = string> = {
+    /** Identificador estable (clave de la lista y lo que recibe `onItemSelect`). */
+    id: Id;
+    /** Título (en negrita). */
+    title: ReactNode;
+    /** Texto secundario debajo del título. */
+    description?: ReactNode;
+    /** Fecha de la notificación; se muestra relativa ("hace 5 minutos"). */
+    date?: Date | string;
+    /** Ya leída; sin valor cuenta como no leída (resaltada y en el badge). */
+    read?: boolean;
+    /** Ícono a la izquierda. */
+    icon?: ReactNode;
+    /** Con `href` el ítem es un enlace; sin él, un botón. */
+    href?: string;
+};
+export type KapiNotificationBellLabels = {
+    /** Título del panel y base del nombre accesible de la campana. */
+    title: string;
+    /** Sufijo del conteo en el nombre accesible: "Notificaciones, 3 sin leer". */
+    unread: string;
+    /** Marca (solo lectores de pantalla) de cada ítem no leído. */
+    unreadItem: string;
+    markAllRead: string;
+    viewAll: string;
+    /** Lista vacía (lo pisa `emptyMessage`). */
+    empty: string;
+    loading: string;
+};
+export declare const DEFAULT_NOTIFICATION_BELL_LABELS: KapiNotificationBellLabels;
+type OwnKeys = "children" | "type" | "onChange" | "onSelect" | "defaultValue" | "value";
+/** Los atributos nativos (`className`, `style`, `id`, `onClick`, `aria-label`…) van al botón de la campana. */
+export type KapiNotificationBellProps<Id extends string = string> = Omit<ButtonHTMLAttributes<HTMLButtonElement>, OwnKeys> & {
+    /** Notificaciones a listar, en el orden en que se muestran. */
+    items: KapiNotification<Id>[];
+    /** Click (o Enter) en un ítem; después el panel se cierra. El evento permite `preventDefault` en enlaces (router). */
+    onItemSelect?: (item: KapiNotification<Id>, event: ReactMouseEvent<HTMLElement>) => void;
+    /** Muestra "Marcar todas como leídas" (solo si hay no leídas). */
+    onMarkAllRead?: () => void;
+    /** Muestra el pie "Ver todas"; después el panel se cierra. */
+    onViewAll?: () => void;
+    /** Muestra el estado de carga en lugar de la lista. */
+    loading?: boolean;
+    /** Contenido de la lista vacía; pisa `labels.empty`. */
+    emptyMessage?: ReactNode;
+    /**
+     * Tope del badge: por encima muestra `max+`.
+     * @default 9
+     */
+    max?: number;
+    /** Panel abierto (controlado). */
+    open?: boolean;
+    /** Panel abierto al montar (no controlado). */
+    defaultOpen?: boolean;
+    /** Cambio de apertura (campana, Escape, click afuera, elegir un ítem o "Ver todas"). */
+    onOpenChange?: (open: boolean) => void;
+    /** Textos de la campana y el panel. */
+    labels?: KapiLabelsOverride<KapiNotificationBellLabels> | undefined;
+    /** Hora de referencia de las fechas relativas (tests y capturas deterministas). Sin valor, el reloj real. */
+    now?: Date | undefined;
+    /** Ref al botón de la campana. */
+    ref?: Ref<HTMLButtonElement>;
+};
+/**
+ * Campana de notificaciones: botón con badge de no leídas que abre un panel no modal (`role="dialog"`)
+ * portaleado a `.kapi` y posicionado con `usePlacement`. Al abrir enfoca la primera notificación;
+ * las flechas, Home y End recorren la lista (con vuelta); Escape cierra y devuelve el foco a la campana;
+ * click afuera o sacar el foco del panel lo cierran.
+ */
+export declare function KapiNotificationBell<Id extends string = string>({ items, onItemSelect, onMarkAllRead, onViewAll, loading, emptyMessage, max, open: openProp, defaultOpen, onOpenChange, labels, now: nowProp, ref, className, onClick, "aria-label": ariaLabel, ...rest }: KapiNotificationBellProps<Id>): import("react").JSX.Element;
+export {};

package/dist/components/layout/KapiNotificationBell.js

@@ -0,0 +1,196 @@
+"use client";
+import { assignRef as e, focusLeaves as t } from "../inputs/fieldLogic.js";
+import { useKapiLocale as n, useLabels as r } from "../locale/KapiLocaleProvider.js";
+import { resolveKapiRoot as i } from "../../hooks/kapiRoot.js";
+import { isOutsidePopover as a } from "../overlays/popoverLogic.js";
+import { usePlacement as ee } from "../../hooks/usePlacement.js";
+import { joinClasses as o } from "../rootProps.js";
+import { KapiOverlayPortal as te } from "../overlays/overlayPortal.js";
+import { focusedMenuIndex as ne, menuKeyIntent as s, nextEnabledIndex as c } from "../overlays/menuKeyboardLogic.js";
+import { formatRelativeTime as l } from "../../hooks/dateFormat.js";
+import { NOTIFICATION_BELL_PLACEMENT as u, badgeText as re, bellTriggerLabel as ie, notificationDateTime as ae, unreadCount as oe } from "./notificationBellLogic.js";
+/* empty css                         */
+import { Fragment as d, jsx as f, jsxs as p } from "react/jsx-runtime";
+import { useCallback as m, useEffect as h, useId as g, useLayoutEffect as se, useRef as _, useState as v } from "react";
+import { Bell as ce } from "lucide-react";
+//#region src/components/layout/KapiNotificationBell.tsx
+var y = {
+	title: "Notificaciones",
+	unread: "sin leer",
+	unreadItem: "Sin leer",
+	markAllRead: "Marcar todas como leídas",
+	viewAll: "Ver todas",
+	empty: "No tienes notificaciones",
+	loading: "Cargando notificaciones…"
+}, b = "[data-menu-index]", x = (e) => (e?.querySelector(b) ?? e)?.focus();
+function S({ items: S, onItemSelect: le, onMarkAllRead: C, onViewAll: w, loading: T = !1, emptyMessage: E, max: D = 9, open: O, defaultOpen: k = !1, onOpenChange: A, labels: j, now: M, ref: N, className: P, onClick: F, "aria-label": I, ...L }) {
+	let R = r("notificationBell", y, j), z = n() ?? "es", [B, V] = v(k), H = O ?? B, U = g(), W = g(), G = _(null), K = _(null), [q, ue] = v(null), J = m((e) => {
+		O === void 0 && V(e), A?.(e);
+	}, [O, A]), Y = _(J);
+	h(() => {
+		Y.current = J;
+	}), se(() => {
+		ue(H ? i(G.current) : null);
+	}, [H]);
+	let { style: de } = ee({
+		open: H,
+		enabled: !!q,
+		anchor: G,
+		floatingRef: K,
+		hideUntilPlaced: !1,
+		...u
+	}), fe = () => Array.from(K.current?.querySelectorAll(b) ?? []), pe = () => x(K.current);
+	h(() => {
+		H && q && x(K.current);
+	}, [H, q]), h(() => {
+		if (!H) return;
+		let e = (e) => {
+			e.key !== "Escape" || e.defaultPrevented || (e.preventDefault(), Y.current(!1), G.current?.focus());
+		}, t = (e) => {
+			a(e.target, [K.current, G.current]) && Y.current(!1);
+		};
+		return document.addEventListener("keydown", e), document.addEventListener("pointerdown", t, !0), () => {
+			document.removeEventListener("keydown", e), document.removeEventListener("pointerdown", t, !0);
+		};
+	}, [H]);
+	let X = () => {
+		J(!1), G.current?.focus();
+	}, Z = oe(S), Q = re(Z, D), $ = (e) => {
+		F?.(e), !e.defaultPrevented && J(!H);
+	}, me = (e) => {
+		let t = s(e.key);
+		if (t.kind !== "move") return;
+		let n = fe();
+		n.length !== 0 && (e.preventDefault(), n[c(ne(document.activeElement), t.dir, n.map((e, t) => t))]?.focus());
+	}, he = (e) => {
+		t(e.relatedTarget, K.current, G.current) && e.relatedTarget && J(!1);
+	}, ge = () => {
+		C?.(), pe();
+	}, _e = M ?? /* @__PURE__ */ new Date();
+	return /* @__PURE__ */ p(d, { children: [/* @__PURE__ */ p("button", {
+		...L,
+		ref: (t) => {
+			G.current = t, e(N, t);
+		},
+		type: "button",
+		className: o("kapi-bell", P),
+		"aria-label": I ?? ie(R.title, Z, R.unread),
+		"aria-haspopup": "dialog",
+		"aria-expanded": H,
+		"aria-controls": H ? U : void 0,
+		onClick: $,
+		children: [/* @__PURE__ */ f(ce, {
+			size: 20,
+			strokeWidth: 1.8,
+			"aria-hidden": "true"
+		}), Q && /* @__PURE__ */ f("span", {
+			className: "kapi-bell__badge",
+			"aria-hidden": "true",
+			children: Q
+		})]
+	}), H && /* @__PURE__ */ f(te, {
+		root: q,
+		children: /* @__PURE__ */ p("div", {
+			ref: K,
+			id: U,
+			role: "dialog",
+			"aria-labelledby": W,
+			tabIndex: -1,
+			className: "kapi-bell__panel",
+			style: de,
+			onKeyDown: me,
+			onBlur: he,
+			children: [
+				/* @__PURE__ */ p("div", {
+					className: "kapi-bell__head",
+					children: [/* @__PURE__ */ f("h2", {
+						id: W,
+						className: "kapi-bell__title",
+						children: R.title
+					}), C && Z > 0 && !T && /* @__PURE__ */ f("button", {
+						type: "button",
+						className: "kapi-bell__link",
+						onClick: ge,
+						children: R.markAllRead
+					})]
+				}),
+				T ? /* @__PURE__ */ p("div", {
+					className: "kapi-bell__state",
+					role: "status",
+					children: [/* @__PURE__ */ f("span", {
+						className: "kapi-spinner kapi-spinner--sm",
+						"aria-hidden": "true"
+					}), R.loading]
+				}) : S.length === 0 ? /* @__PURE__ */ f("div", {
+					className: "kapi-bell__state",
+					children: E ?? R.empty
+				}) : /* @__PURE__ */ f("ul", {
+					className: "kapi-bell__list",
+					"aria-labelledby": W,
+					children: S.map((e, t) => {
+						let n = e.date === void 0 ? null : ae(e.date), r = (t) => {
+							le?.(e, t), X();
+						}, i = /* @__PURE__ */ p(d, { children: [
+							e.icon && /* @__PURE__ */ f("span", {
+								className: "kapi-bell__icon",
+								"aria-hidden": "true",
+								children: e.icon
+							}),
+							/* @__PURE__ */ p("span", {
+								className: "kapi-bell__body",
+								children: [
+									/* @__PURE__ */ f("span", {
+										className: "kapi-bell__itemtitle",
+										children: e.title
+									}),
+									e.description && /* @__PURE__ */ f("span", {
+										className: "kapi-bell__desc",
+										children: e.description
+									}),
+									n !== null && /* @__PURE__ */ f("time", {
+										className: "kapi-bell__date",
+										dateTime: n,
+										children: l(e.date, _e, z)
+									})
+								]
+							}),
+							!e.read && /* @__PURE__ */ f("span", {
+								className: "kapi-bell__dot",
+								children: /* @__PURE__ */ f("span", {
+									className: "kapi-bell__sr",
+									children: R.unreadItem
+								})
+							})
+						] }), a = {
+							className: o("kapi-bell__item", !e.read && "is-unread"),
+							"data-menu-index": t,
+							onClick: r
+						};
+						return /* @__PURE__ */ f("li", { children: e.href ? /* @__PURE__ */ f("a", {
+							...a,
+							href: e.href,
+							children: i
+						}) : /* @__PURE__ */ f("button", {
+							...a,
+							type: "button",
+							children: i
+						}) }, e.id);
+					})
+				}),
+				w && /* @__PURE__ */ f("div", {
+					className: "kapi-bell__foot",
+					children: /* @__PURE__ */ f("button", {
+						type: "button",
+						className: "kapi-bell__link",
+						onClick: () => {
+							w(), X();
+						},
+						children: R.viewAll
+					})
+				})
+			]
+		})
+	})] });
+}
+//#endregion
+export { y as DEFAULT_NOTIFICATION_BELL_LABELS, S as KapiNotificationBell };

package/dist/components/layout/KapiPageHeader.d.ts

@@ -0,0 +1,28 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import "./KapiPageHeader.css";
+/** Atributos nativos (`id`, `style`, `data-*`…) van al `<header>` (no al centinela de scroll). */
+export type KapiPageHeaderProps = Omit<HTMLAttributes<HTMLElement>, "title" | "children"> & {
+    /** Título de la página (`<h1>`). */
+    title: ReactNode;
+    /** Texto secundario bajo el título. */
+    subtitle?: ReactNode;
+    /** Datos breves bajo el subtítulo (fecha, responsable, contadores…). */
+    meta?: ReactNode;
+    /** Acciones a la derecha (botones principales de la página). */
+    actions?: ReactNode;
+    /** Etiqueta/estado inline junto al título. */
+    chip?: ReactNode;
+    /** Se reduce a una barra compacta al scrollear. */
+    collapseOnScroll?: boolean;
+    /** `position: sticky; top: 0`. */
+    sticky?: boolean;
+    /** Contenedor con scroll (default: viewport). */
+    scrollRoot?: Element | null;
+    /**
+     * Se adapta al ancho de su contenedor (container queries, `container: kapi-pageheader`): bajo
+     * 560px las acciones pasan debajo del título y el título se achica. Default `true`.
+     */
+    responsive?: boolean;
+};
+/** Cabecera de página que colapsa a barra sticky compacta al hacer scroll. */
+export declare function KapiPageHeader({ title, subtitle, meta, actions, chip, collapseOnScroll, sticky, scrollRoot, responsive, className, ...rest }: KapiPageHeaderProps): import("react").JSX.Element;

package/dist/components/layout/KapiPageHeader.js

@@ -0,0 +1,47 @@
+"use client";
+import { useScrollCollapse as e } from "../../hooks/useScrollCollapse.js";
+/* empty css                   */
+import { Fragment as t, jsx as n, jsxs as r } from "react/jsx-runtime";
+//#region src/components/layout/KapiPageHeader.tsx
+function i({ title: i, subtitle: a, meta: o, actions: s, chip: c, collapseOnScroll: l = !0, sticky: u = !0, scrollRoot: d = null, responsive: f = !0, className: p, ...m }) {
+	let { collapsed: h, sentinelRef: g } = e({ root: d }), _ = [
+		"kapi-pageheader",
+		u && "kapi-pageheader--sticky",
+		f && "kapi-pageheader--cq",
+		l && h && "kapi-pageheader--collapsed",
+		p
+	].filter(Boolean).join(" ");
+	return /* @__PURE__ */ r(t, { children: [/* @__PURE__ */ n("div", {
+		ref: g,
+		className: "kapi-pageheader__sentinel",
+		"aria-hidden": !0
+	}), /* @__PURE__ */ r("header", {
+		...m,
+		className: _,
+		children: [/* @__PURE__ */ r("div", {
+			className: "kapi-pageheader__main",
+			children: [
+				/* @__PURE__ */ r("div", {
+					className: "kapi-pageheader__titlerow",
+					children: [/* @__PURE__ */ n("h1", {
+						className: "kapi-pageheader__title",
+						children: i
+					}), c]
+				}),
+				a && /* @__PURE__ */ n("div", {
+					className: "kapi-pageheader__subtitle",
+					children: a
+				}),
+				o && /* @__PURE__ */ n("div", {
+					className: "kapi-pageheader__meta",
+					children: o
+				})
+			]
+		}), s && /* @__PURE__ */ n("div", {
+			className: "kapi-pageheader__actions",
+			children: s
+		})]
+	})] });
+}
+//#endregion
+export { i as KapiPageHeader };

package/dist/components/layout/KapiPanelParts.d.ts

@@ -0,0 +1,35 @@
+import { type KapiNavBadgeValue } from "../navigation/navBadgeLogic";
+import type { KapiBadgeVariant } from "../display/KapiBadge";
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from "react";
+import "./KapiPanelParts.css";
+type DivProps = HTMLAttributes<HTMLDivElement>;
+/** Etiqueta de sección dentro del panel (mayúsculas chicas). Atributos nativos al `<div>`. */
+export declare const KapiPanelLabel: ({ className, ...rest }: DivProps) => import("react").JSX.Element;
+/** Separador del panel. Atributos nativos al `<div>`. */
+export declare const KapiPanelDivider: ({ className, ...rest }: Omit<DivProps, "children">) => import("react").JSX.Element;
+/** Texto de ayuda al pie del panel. Atributos nativos al `<div>`. */
+export declare const KapiPanelHint: ({ className, ...rest }: DivProps) => import("react").JSX.Element;
+/** Lista vertical de ítems del panel. Atributos nativos al contenedor `.kapi-ctxlist`. */
+export declare const KapiPanelList: ({ children, ...rest }: Omit<DivProps, "children"> & {
+    /** Ítems de la lista (`KapiPanelItem`). */
+    children: ReactNode;
+}) => import("react").JSX.Element;
+export type KapiPanelItemProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+    /** Marca el ítem actual (resaltado y `aria-current="page"`). */
+    active?: boolean;
+    /** Contenido a la derecha (badge, contador…). */
+    trailing?: ReactNode;
+    /** Aviso de atención al final: contador (0 no dibuja nada; tope "999+") o `"dot"` sin número. */
+    badge?: KapiNavBadgeValue | undefined;
+    /** Color del aviso, como `KapiBadge` (`danger` para vencidos…). @default "primary" */
+    badgeTone?: KapiBadgeVariant | undefined;
+    /** Texto accesible del aviso (p. ej. "3 trámites vencidos"); sin él se lee el número. */
+    badgeLabel?: string | undefined;
+    /** Ícono decorativo antes del texto (va en un contenedor `aria-hidden`). */
+    icon?: ReactNode;
+    /** Texto del ítem. */
+    children: ReactNode;
+};
+/** Ítem de navegación del panel contextual. `aria-current` sale de `active`; `icon` va antes del texto. */
+export declare const KapiPanelItem: ({ active, trailing, badge, badgeTone, badgeLabel, icon, className, type, children, ...rest }: KapiPanelItemProps) => import("react").JSX.Element;
+export {};

package/dist/components/layout/KapiPanelParts.js

@@ -0,0 +1,63 @@
+"use client";
+import { joinClasses as e } from "../rootProps.js";
+import { CtxSlidingList as t } from "../navigation/CtxSlidingList.js";
+import "../navigation/navBadgeLogic.js";
+import { KapiNavBadge as n } from "../navigation/KapiNavBadge.js";
+import { useKapiPanelMini as r } from "../navigation/panelMini.js";
+import { MiniNavItem as i } from "../navigation/MiniNavItem.js";
+/* empty css                   */
+import { jsx as a, jsxs as o } from "react/jsx-runtime";
+//#region src/components/layout/KapiPanelParts.tsx
+var s = ({ className: t, ...n }) => /* @__PURE__ */ a("div", {
+	...n,
+	className: e("kapi-ct", t)
+}), c = ({ className: t, ...n }) => /* @__PURE__ */ a("div", {
+	...n,
+	className: e("kapi-ctxdivider", t)
+}), l = ({ className: t, ...n }) => /* @__PURE__ */ a("div", {
+	...n,
+	className: e("kapi-hint", t)
+}), u = ({ children: e, ...n }) => /* @__PURE__ */ a(t, {
+	...n,
+	children: e
+}), d = ({ active: t = !1, trailing: s, badge: c, badgeTone: l, badgeLabel: u, icon: d, className: f, type: p = "button", children: m, ...h }) => {
+	let { mini: g } = r();
+	return g ? /* @__PURE__ */ a(i, {
+		...h,
+		type: p,
+		className: f,
+		label: m,
+		icon: d,
+		active: t,
+		badge: c,
+		badgeTone: l,
+		badgeLabel: u
+	}) : /* @__PURE__ */ o("button", {
+		...h,
+		type: p,
+		className: e("kapi-ctxitem", t && "kapi-ctxitem--on", f),
+		"aria-current": t ? "page" : void 0,
+		children: [
+			d == null || d === !1 ? m : /* @__PURE__ */ o("span", {
+				className: "kapi-ctxitem__lead",
+				children: [/* @__PURE__ */ a("span", {
+					className: "kapi-ctxitem__icon",
+					"aria-hidden": "true",
+					children: d
+				}), /* @__PURE__ */ a("span", {
+					className: "kapi-ctxitem__label",
+					children: m
+				})]
+			}),
+			/* @__PURE__ */ a(n, {
+				value: c,
+				tone: l,
+				label: u,
+				max: 999
+			}),
+			s
+		]
+	});
+};
+//#endregion
+export { c as KapiPanelDivider, l as KapiPanelHint, d as KapiPanelItem, s as KapiPanelLabel, u as KapiPanelList };

package/dist/components/layout/KapiRail.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import { type KapiRailEntry, type KapiRailItem, type KapiRailPinned, type KapiRailSeparator, type KapiRailZone, type KapiRailVariant } from "./railLogic";
+import "./KapiRail.css";
+import { type KapiLinkLabels } from "../locale/linkLabels";
+import type { KapiLabelsOverride } from "../labelsLogic";
+export type { KapiRailEntry, KapiRailItem, KapiRailPinned, KapiRailSeparator, KapiRailVariant, KapiRailZone };
+export type KapiRailLabels = {
+    /** Nombre accesible del `<nav>` (sin `aria-label`). */
+    navigation: string;
+};
+export declare const DEFAULT_RAIL_LABELS: KapiRailLabels;
+/** Atributos nativos (`id`, `style`, `data-*`…) van al `<nav>`. `Id` se infiere de `items`. */
+export type KapiRailProps<Id extends string = string> = Omit<HTMLAttributes<HTMLElement>, "children" | "onSelect"> & {
+    /**
+     * Ítems del rail. Intercala `{ separator: true }` para dibujar un divisor entre grupos. Con `pinned: "start"`
+     * o `"end"` el ítem queda fijo arriba o abajo; el resto va en la zona del medio, la única que scrollea.
+     */
+    items: KapiRailEntry<Id>[];
+    /** id del ítem activo (controlado por la app: derívalo de tu router). */
+    activeId?: Id;
+    /** Se llama con el `id` del ítem clickeado (la app navega y actualiza `activeId`). */
+    onSelect?: (id: Id) => void;
+    /** Marca arriba del rail (logo / inicial). Siempre fija. */
+    brand?: ReactNode;
+    /** Zona inferior (cuenta, tema…). Se pega al fondo del rail y siempre queda fija. */
+    footer?: ReactNode;
+    /**
+     * `labeled` (default): ícono + nombre debajo, sin tooltip (la etiqueta ya se ve).
+     * `compact`: sólo ícono, más angosto; el nombre aparece en un tooltip al hover/foco.
+     */
+    variant?: KapiRailVariant;
+    /** Textos fijos; `newTab` sale de la clave compartida `link`. `aria-label` gana sobre `navigation`. */
+    labels?: KapiLabelsOverride<KapiRailLabels & KapiLinkLabels> | undefined;
+};
+/**
+ * Rail de navegación (Nav A): ícono + nombre debajo. OPCIONAL en el shell.
+ * Es presentacional: no conoce el router; la app pasa `activeId` y `onSelect`.
+ * En móvil se convierte en barra inferior (shell.css).
+ */
+export declare const KapiRail: <Id extends string = string>({ items, activeId, onSelect, brand, footer, variant, "aria-label": ariaLabel, labels, className, ...rest }: KapiRailProps<Id>) => import("react").JSX.Element;

package/dist/components/layout/KapiRail.js

@@ -0,0 +1,102 @@
+"use client";
+import { useLabels as e } from "../locale/KapiLocaleProvider.js";
+import { joinClasses as t } from "../rootProps.js";
+import { useSlidingIndicator as n } from "../../hooks/useSlidingIndicator.js";
+import { KapiTooltip as r } from "../overlays/KapiTooltip.js";
+import { DEFAULT_LINK_LABELS as i } from "../locale/linkLabels.js";
+import { navBadgeA11yText as a } from "../navigation/navBadgeLogic.js";
+import { KapiNavBadge as o } from "../navigation/KapiNavBadge.js";
+import { isRailSeparator as s, railClasses as c, railItemClasses as l, railShowsTooltip as u, splitRailEntries as d } from "./railLogic.js";
+/* empty css             */
+import { jsx as f, jsxs as p } from "react/jsx-runtime";
+import { ExternalLink as m } from "lucide-react";
+//#region src/components/layout/KapiRail.tsx
+var h = { navigation: "Navegación principal" }, g = ({ items: g, activeId: _, onSelect: v, brand: y, footer: b, variant: x = "labeled", "aria-label": S, labels: C, className: w, ...T }) => {
+	let E = e("rail", h, C), D = e("link", i, C), O = x === "compact", k = u(x), A = d(g), { containerRef: j, indicatorRef: M } = n({
+		active: _ ?? null,
+		deps: [g, x],
+		findActive: (e) => e.querySelector(".kapi-rail__item[aria-current=\"page\"]")
+	}), N = ({ id: e, label: t, icon: n, href: i, external: s, newTab: c, badge: u, badgeTone: d, badgeLabel: h }) => {
+		let g = _ === e, y = g ? "page" : void 0, b = a(u, h), x = b === null ? t : `${t} ${b}`, S = O ? x : void 0, C = /* @__PURE__ */ f(o, {
+			value: u,
+			tone: d,
+			label: h,
+			placement: "corner",
+			announce: !O
+		}), w = i === void 0 ? /* @__PURE__ */ p("button", {
+			type: "button",
+			className: l({ active: g }),
+			onClick: () => v?.(e),
+			"aria-current": y,
+			"aria-label": S,
+			children: [
+				n,
+				!O && t,
+				C
+			]
+		}, k ? void 0 : e) : /* @__PURE__ */ p("a", {
+			className: l({
+				active: g,
+				link: !0
+			}),
+			href: i,
+			rel: "noopener noreferrer",
+			target: c ? "_blank" : void 0,
+			"aria-current": y,
+			"aria-label": S,
+			children: [
+				n,
+				!O && t,
+				C,
+				s && /* @__PURE__ */ f(m, {
+					className: "kapi-rail__ext",
+					size: 12,
+					"aria-hidden": "true"
+				}),
+				c && /* @__PURE__ */ f("span", {
+					className: "kapi-rail__sr",
+					children: D.newTab
+				})
+			]
+		}, k ? void 0 : e);
+		return k ? /* @__PURE__ */ f(r, {
+			label: x,
+			children: w
+		}, e) : w;
+	}, P = (e) => e.map((e, t) => s(e) ? /* @__PURE__ */ f("div", {
+		className: "kapi-rail__sep",
+		role: "separator",
+		"aria-orientation": "horizontal"
+	}, e.id ?? `sep-${t}`) : N(e));
+	return /* @__PURE__ */ p("nav", {
+		...T,
+		className: t(c({ variant: x }), w),
+		"aria-label": S ?? E.navigation,
+		children: [
+			y !== void 0 && /* @__PURE__ */ f("div", {
+				className: "kapi-rail__brand",
+				children: y
+			}),
+			A.start.length > 0 && /* @__PURE__ */ f("div", {
+				className: "kapi-rail__start",
+				children: P(A.start)
+			}),
+			/* @__PURE__ */ p("div", {
+				ref: j,
+				className: "kapi-rail__scroll",
+				children: [/* @__PURE__ */ f("span", {
+					ref: M,
+					className: "kapi-rail__indicator",
+					"aria-hidden": "true"
+				}), P(A.scroll)]
+			}),
+			A.end.length > 0 && /* @__PURE__ */ f("div", {
+				className: "kapi-rail__end",
+				children: P(A.end)
+			}),
+			b
+		]
+	});
+};
+//#endregion
+export { h as DEFAULT_RAIL_LABELS, g as KapiRail };