@kapiuara/ui 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,40 @@
+import { type HTMLAttributes, type ReactNode, type Ref } from "react";
+import "./KapiScrollArea.css";
+import type { KapiScrollAxis } from "../../hooks/scrollEdgesLogic";
+import type { KapiLabelsOverride } from "../labelsLogic";
+/** Textos de los controles de paginado (nombre accesible de las zonas de borde). */
+export type KapiScrollAreaLabels = {
+    /** Zona del borde inicial: scrollea un page hacia atrás. */
+    previous: string;
+    /** Zona del borde final: scrollea un page hacia adelante. */
+    next: string;
+};
+export declare const DEFAULT_SCROLL_AREA_LABELS: KapiScrollAreaLabels;
+/**
+ * Atributos nativos (`id`, `style`, `aria-label`, `data-*`…) van al contenedor; el contenido
+ * scrollea en una zona interior enfocable (`viewportRef`).
+ */
+export type KapiScrollAreaProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Contenido que puede desbordar. */
+    children?: ReactNode;
+    /** Eje que scrollea; el otro eje no scrollea. */
+    axis?: KapiScrollAxis | undefined;
+    /** Desvanece (con `mask-image`) sólo el borde que tiene más contenido. */
+    fade?: boolean | undefined;
+    /** Click sobre la zona de un borde con más contenido para scrollear un page hacia ese lado. */
+    paging?: boolean | undefined;
+    /** Clase del contenedor. */
+    className?: string | undefined;
+    /** Ref de la zona interior que scrollea (para `scrollTo`, `scrollIntoView`…). */
+    viewportRef?: Ref<HTMLDivElement> | undefined;
+    /** Ref del contenedor. */
+    ref?: Ref<HTMLDivElement> | undefined;
+    /** Textos de los controles de paginado. */
+    labels?: KapiLabelsOverride<KapiScrollAreaLabels> | undefined;
+};
+/**
+ * Contenedor que scrollea en un eje y desvanece sólo el borde con más contenido (`mask-image`, sin
+ * chevrons). Con `paging`, un click en la zona del borde avanza un page (instantáneo con movimiento
+ * reducido). La zona que scrollea es enfocable para scrollear con el teclado. Sólo LTR.
+ */
+export declare function KapiScrollArea({ children, axis, fade, paging, className, viewportRef, ref, labels, ...rest }: KapiScrollAreaProps): import("react").JSX.Element;

package/dist/components/layout/KapiScrollArea.js

@@ -0,0 +1,49 @@
+"use client";
+import { useLabels as e } from "../locale/KapiLocaleProvider.js";
+import { joinClasses as t } from "../rootProps.js";
+import { useScrollEdges as n } from "../../hooks/useScrollEdges.js";
+/* empty css                   */
+import { jsx as r, jsxs as i } from "react/jsx-runtime";
+import { useCallback as a } from "react";
+//#region src/components/layout/KapiScrollArea.tsx
+var o = {
+	previous: "Ver contenido anterior",
+	next: "Ver contenido siguiente"
+};
+function s({ children: s, axis: c = "x", fade: l = !0, paging: u = !0, className: d, viewportRef: f, ref: p, labels: m, ...h }) {
+	let g = e("scrollArea", o, m), { ref: _, edges: v, scrollByPage: y } = n({ axis: c }), b = a((e) => {
+		_.current = e, typeof f == "function" ? f(e) : f && (f.current = e);
+	}, [_, f]);
+	return /* @__PURE__ */ i("div", {
+		...h,
+		ref: p,
+		className: t("kapi-scroll-area", d),
+		"data-axis": c,
+		children: [
+			/* @__PURE__ */ r("div", {
+				ref: b,
+				className: t("kapi-scroll-area__viewport", l && `kapi-fade-${c}`),
+				"data-edge-start": v.start ? "" : void 0,
+				"data-edge-end": v.end ? "" : void 0,
+				tabIndex: 0,
+				children: s
+			}),
+			u && v.start && /* @__PURE__ */ r("button", {
+				type: "button",
+				tabIndex: -1,
+				"aria-label": g.previous,
+				className: "kapi-scroll-area__edge kapi-scroll-area__edge--start",
+				onClick: () => y(-1)
+			}),
+			u && v.end && /* @__PURE__ */ r("button", {
+				type: "button",
+				tabIndex: -1,
+				"aria-label": g.next,
+				className: "kapi-scroll-area__edge kapi-scroll-area__edge--end",
+				onClick: () => y(1)
+			})
+		]
+	});
+}
+//#endregion
+export { o as DEFAULT_SCROLL_AREA_LABELS, s as KapiScrollArea };

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

@@ -0,0 +1,40 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import { type KapiMenuItem } from "../overlays/KapiContextMenu";
+/**
+ * Atributos nativos (`id`, `style`, `data-*`…) van a la raíz `.kapi`. `data-theme`/`data-motion`
+ * son propios y las variables del tema (`--kapi-font`, `--kapi-primary`) ganan sobre `style`.
+ */
+export type KapiShellProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Navegación principal (típicamente `<KapiRail />`). OPCIONAL. */
+    rail?: ReactNode;
+    /** Panel contextual (típicamente `<KapiContextSlot />`). OPCIONAL. */
+    panel?: ReactNode;
+    /** Contenido de la página; va dentro de `<main class="kapi-content">` (el que scrollea). */
+    children?: ReactNode;
+    /** Ítems del menú del sistema (doble click derecho). Sin ítems no se abre menú. */
+    contextMenuItems?: KapiMenuItem[];
+    /** Mecánica global de click derecho (drag-scroll + supresión del menú nativo). */
+    rightClick?: boolean;
+    /** Monta acá toasts, tours, modales globales: viven DENTRO de `.kapi` (heredan tokens). */
+    overlays?: ReactNode;
+    /** Clase extra del `<main>` que envuelve el contenido. */
+    contentClassName?: string;
+    /**
+     * Namespace de las preferencias guardadas (tema, acento, fuente, movimiento). Default `kapi`
+     * (`kapi:theme`…). Dos apps del design system en el mismo origen pasan uno distinto para no pisarse.
+     */
+    storageNamespace?: string;
+};
+/**
+ * Marco de la app. Es la raíz `.kapi` (tokens, tema, fuente) y compone:
+ *
+ *   [rail?] [panel?] <main.kapi-content>
+ *
+ * Rail y panel son opcionales e independientes: el contenido no depende de ninguno.
+ *
+ *   // con rail + panel
+ *   <KapiShell rail={<KapiRail items={…} />} panel={<KapiContextSlot title="Módulo">…</KapiContextSlot>}>…</KapiShell>
+ *   // sin rail (otra navegación, p. ej. tabs arriba o router propio)
+ *   <KapiShell><MiTopNav /><Pagina /></KapiShell>
+ */
+export declare const KapiShell: ({ rail, panel, children, contextMenuItems, rightClick, overlays, className, contentClassName, storageNamespace, style, ...rest }: KapiShellProps) => import("react").JSX.Element;

package/dist/components/layout/KapiShell.js

@@ -0,0 +1,48 @@
+"use client";
+import { joinClasses as e } from "../rootProps.js";
+import { KapiContextMenu as t } from "../overlays/KapiContextMenu.js";
+import { useGlobalRightClick as n } from "../../hooks/useGlobalRightClick.js";
+import { KapiThemeContext as r, themeRootStyle as i, useKapiThemeState as a } from "../../hooks/useKapiTheme.js";
+import { jsx as o, jsxs as s } from "react/jsx-runtime";
+import { useState as c } from "react";
+//#region src/components/layout/KapiShell.tsx
+var l = ({ rail: l, panel: u, children: d, contextMenuItems: f, rightClick: p = !0, overlays: m, className: h, contentClassName: g = "", storageNamespace: _, style: v, ...y }) => {
+	let b = a({ namespace: _ }), [x, S] = c(null);
+	return n({
+		enabled: p,
+		onMenu: f?.length ? (e, t) => S({
+			x: e,
+			y: t
+		}) : void 0
+	}), /* @__PURE__ */ o(r.Provider, {
+		value: b,
+		children: /* @__PURE__ */ s("div", {
+			...y,
+			className: e("kapi", h),
+			"data-theme": b.theme,
+			"data-motion": b.motion === "reduced" ? "reduced" : void 0,
+			style: {
+				...v,
+				...i(b)
+			},
+			children: [
+				l,
+				u,
+				/* @__PURE__ */ o("main", {
+					className: `kapi-content${g ? ` ${g}` : ""}`,
+					children: d
+				}),
+				m,
+				x && f && /* @__PURE__ */ o(t, {
+					open: !0,
+					x: x.x,
+					y: x.y,
+					items: f,
+					onClose: () => S(null)
+				})
+			]
+		})
+	});
+};
+//#endregion
+export { l as KapiShell };

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

@@ -0,0 +1,11 @@
+import type { HTMLAttributes } from "react";
+import { type KapiAlign, type KapiGap } from "./layoutPrimitives";
+import "./layout-primitives.css";
+export type KapiStackProps = HTMLAttributes<HTMLDivElement> & {
+    /** Espacio entre hijos: número = px, string = largo CSS. Default 12px. */
+    gap?: KapiGap;
+    /** Alineación en el eje horizontal (`align-items`). */
+    align?: KapiAlign;
+};
+/** Pila vertical (flex column). */
+export declare function KapiStack({ gap, align, className, style, children, ...rest }: KapiStackProps): import("react").JSX.Element;

package/dist/components/layout/KapiStack.js

@@ -0,0 +1,19 @@
+"use client";
+import { stackProps as e } from "./layoutPrimitives.js";
+/* empty css                      */
+import { jsx as t } from "react/jsx-runtime";
+//#region src/components/layout/KapiStack.tsx
+function n({ gap: n, align: r, className: i, style: a, children: o, ...s }) {
+	return /* @__PURE__ */ t("div", {
+		...s,
+		...e({
+			gap: n,
+			align: r,
+			className: i,
+			style: a
+		}),
+		children: o
+	});
+}
+//#endregion
+export { n as KapiStack };

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

@@ -0,0 +1,18 @@
+export type KapiAccessCardTone = "primary" | "success" | "warning" | "danger" | "info";
+export type KapiAccessCardAffordance = "external" | "chevron";
+/** Which trailing icon to show: a cross-system/new-tab link gets the arrow, in-app navigation the chevron. */
+export declare const accessCardAffordance: (external: boolean | undefined) => KapiAccessCardAffordance;
+/** Props for the anchor of an `href` card. `newTab` opens `_blank`; external links always get `rel`. */
+export declare const linkAttrs: (opts: {
+    external?: boolean | undefined;
+    newTab?: boolean | undefined;
+}) => {
+    target?: "_blank";
+    rel?: string;
+};
+export declare const accessCardClasses: (opts?: {
+    tone?: KapiAccessCardTone | undefined;
+    className?: string | undefined;
+}) => string;
+/** Keys that activate a `role="button"` element. */
+export declare const isActivationKey: (key: string) => boolean;

package/dist/components/layout/accessCardLogic.js

@@ -0,0 +1,11 @@
+//#region src/components/layout/accessCardLogic.ts
+var e = (e) => e ? "external" : "chevron", t = (e) => {
+	let t = {};
+	return e.newTab && (t.target = "_blank"), (e.newTab || e.external) && (t.rel = "noopener noreferrer"), t;
+}, n = (e = {}) => [
+	"kapi-accesscard",
+	`kapi-accesscard--${e.tone ?? "primary"}`,
+	e.className
+].filter(Boolean).join(" "), r = (e) => e === "Enter" || e === " ";
+//#endregion
+export { e as accessCardAffordance, n as accessCardClasses, r as isActivationKey, t as linkAttrs };

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

@@ -0,0 +1,9 @@
+/** Clases de KapiCard: base `.kapi-card` + padding del `.kapi-panelcard` salvo `flush`. */
+export declare const cardClasses: ({ flush, responsive, interactive, className }?: {
+    flush?: boolean | undefined;
+    responsive?: boolean | undefined;
+    interactive?: boolean | undefined;
+    className?: string | undefined;
+}) => string;
+/** Un header se dibuja sólo si hay título o acciones. */
+export declare const hasCardHeader: (title: unknown, actions: unknown) => boolean;

package/dist/components/layout/cardLogic.js

@@ -0,0 +1,11 @@
+//#region src/components/layout/cardLogic.ts
+var e = ({ flush: e = !1, responsive: t = !1, interactive: n = !1, className: r = "" } = {}) => [
+	"kapi-card",
+	"kapi-panelcard",
+	e && "kapi-panelcard--flush",
+	t && "kapi-card--cq",
+	n && "kapi-card--interactive",
+	r
+].filter(Boolean).join(" "), t = (e) => e != null && e !== !1 && e !== "", n = (e, n) => t(e) || t(n);
+//#endregion
+export { e as cardClasses, n as hasCardHeader };

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

@@ -0,0 +1,33 @@
+export { KapiShell } from "./KapiShell";
+export type { KapiShellProps } from "./KapiShell";
+export { KapiRail, DEFAULT_RAIL_LABELS } from "./KapiRail";
+export type { KapiRailItem, KapiRailLabels, KapiRailProps, KapiRailEntry, KapiRailPinned, KapiRailSeparator, KapiRailVariant, KapiRailZone } from "./KapiRail";
+export { KapiContextSlot, DEFAULT_CONTEXT_SLOT_LABELS } from "./KapiContextSlot";
+export type { KapiContextSlotProps, KapiContextSlotLabels } from "./KapiContextSlot";
+export { KapiPanelDivider, KapiPanelHint, KapiPanelItem, KapiPanelLabel, KapiPanelList } from "./KapiPanelParts";
+export type { KapiPanelItemProps } from "./KapiPanelParts";
+export { KapiCard, KapiCardBody, KapiCardFooter, KapiCardHeader } from "./KapiCard";
+export type { KapiCardHeaderProps, KapiCardProps } from "./KapiCard";
+export { cardClasses, hasCardHeader } from "./cardLogic";
+export { KapiDivider, dividerClasses } from "./KapiDivider";
+export type { KapiDividerOrientation, KapiDividerProps } from "./KapiDivider";
+export { KapiAccountMenu, DEFAULT_ACCOUNT_MENU_LABELS } from "./KapiAccountMenu";
+export type { KapiAccountMenuProps, KapiAccountMenuUser, KapiAccountMenuLabels } from "./KapiAccountMenu";
+export { KapiNotificationBell, DEFAULT_NOTIFICATION_BELL_LABELS } from "./KapiNotificationBell";
+export type { KapiNotification, KapiNotificationBellLabels, KapiNotificationBellProps } from "./KapiNotificationBell";
+export { NOTIFICATION_BELL_PLACEMENT, bellTriggerLabel } from "./notificationBellLogic";
+export { KapiAccessCard } from "./KapiAccessCard";
+export type { KapiAccessCardProps } from "./KapiAccessCard";
+export { accessCardAffordance, accessCardClasses, isActivationKey } from "./accessCardLogic";
+export type { KapiAccessCardTone, KapiAccessCardAffordance } from "./accessCardLogic";
+export { KapiStack } from "./KapiStack";
+export type { KapiStackProps } from "./KapiStack";
+export { KapiCluster } from "./KapiCluster";
+export type { KapiClusterProps } from "./KapiCluster";
+export { KapiGrid } from "./KapiGrid";
+export type { KapiGridProps } from "./KapiGrid";
+export type { KapiGap, KapiAlign, KapiClusterAlign, KapiClusterJustify } from "./layoutPrimitives";
+export { KapiPageHeader } from "./KapiPageHeader";
+export type { KapiPageHeaderProps } from "./KapiPageHeader";
+export { KapiScrollArea, DEFAULT_SCROLL_AREA_LABELS } from "./KapiScrollArea";
+export type { KapiScrollAreaLabels, KapiScrollAreaProps } from "./KapiScrollArea";

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

@@ -0,0 +1,51 @@
+import type { CSSProperties } from "react";
+/** Gap: número = px; string = largo CSS crudo (`"1rem"`, `"var(--x)"`). */
+export type KapiGap = number | string;
+export type KapiAlign = "start" | "center" | "end" | "stretch";
+export type KapiClusterAlign = KapiAlign | "baseline";
+export type KapiClusterJustify = "start" | "center" | "end" | "between";
+/** Número -> `Npx`; string -> tal cual; `undefined` -> `undefined` (gana el default del CSS). */
+export declare const gapValue: (gap: KapiGap | undefined) => string | undefined;
+/**
+ * Retorno de los helpers de primitivas: clase + estilo resuelto.
+ * Tipado explícito para que el emit de `.d.ts` no tenga que nombrar tipos internos de `csstype` (TS2883).
+ */
+type PrimitiveProps = {
+    className: string;
+    style: CSSProperties;
+};
+/** Clases + estilo de KapiStack. `style` del usuario pisa al resuelto. */
+export declare const stackProps: ({ gap, align, className, style }?: {
+    gap?: KapiGap | undefined;
+    align?: KapiAlign | undefined;
+    className?: string | undefined;
+    style?: CSSProperties | undefined;
+}) => PrimitiveProps;
+/** Clases + estilo de KapiCluster. `wrap` default true. */
+export declare const clusterProps: ({ gap, justify, align, wrap, className, style }?: {
+    gap?: KapiGap | undefined;
+    justify?: KapiClusterJustify | undefined;
+    align?: KapiClusterAlign | undefined;
+    wrap?: boolean | undefined;
+    className?: string | undefined;
+    style?: CSSProperties | undefined;
+}) => PrimitiveProps;
+/**
+ * `gridTemplateColumns` de KapiGrid. `cols` (entero >= 1) gana sobre `min`.
+ * `min` usa `auto-fit` con `minmax(min(100%, Npx), 1fr)` para no desbordar en contenedores angostos.
+ * Sin ninguno: `undefined` (el CSS aplica un `min` por defecto).
+ */
+export declare const gridColumns: (cols?: number, min?: number | string) => string | undefined;
+export declare const gridProps: ({ gap, cols, min, responsive, className, style }?: {
+    gap?: KapiGap | undefined;
+    cols?: number | undefined;
+    min?: number | string | undefined;
+    /**
+     * Con `cols`: las columnas bajan con el ancho del contenedor (container queries): 2 bajo 768px,
+     * 1 bajo 480px. Pasa por `--kapi-grid-cols` / `--kapi-grid-cols-md` en vez de `gridTemplateColumns`.
+     */
+    responsive?: boolean | undefined;
+    className?: string | undefined;
+    style?: CSSProperties | undefined;
+}) => PrimitiveProps;
+export {};

package/dist/components/layout/layoutPrimitives.js

@@ -0,0 +1,58 @@
+//#region src/components/layout/layoutPrimitives.ts
+var e = {
+	start: "flex-start",
+	center: "center",
+	end: "flex-end",
+	stretch: "stretch",
+	baseline: "baseline"
+}, t = {
+	start: "flex-start",
+	center: "center",
+	end: "flex-end",
+	between: "space-between"
+}, n = (e) => e === void 0 ? void 0 : typeof e == "number" ? `${e}px` : e, r = (e) => Object.fromEntries(Object.entries(e).filter(([, e]) => e !== void 0)), i = (...e) => e.filter(Boolean).join(" "), a = ({ gap: t, align: a, className: o, style: s } = {}) => ({
+	className: i("kapi-stackx", o),
+	style: {
+		...r({
+			gap: n(t),
+			alignItems: a && e[a]
+		}),
+		...s
+	}
+}), o = ({ gap: a, justify: o, align: s, wrap: c = !0, className: l, style: u } = {}) => ({
+	className: i("kapi-clusterx", l),
+	style: {
+		...r({
+			gap: n(a),
+			justifyContent: o && t[o],
+			alignItems: s && e[s],
+			flexWrap: c ? void 0 : "nowrap"
+		}),
+		...u
+	}
+}), s = (e, t) => {
+	if (e !== void 0 && Number.isFinite(e) && e >= 1) return `repeat(${Math.floor(e)}, minmax(0, 1fr))`;
+	if (t !== void 0) return `repeat(auto-fit, minmax(min(100%, ${typeof t == "number" ? `${t}px` : t}), 1fr))`;
+}, c = ({ gap: e, cols: t, min: a, responsive: o = !1, className: c, style: l } = {}) => {
+	let u = t !== void 0 && Number.isFinite(t) && t >= 1 ? Math.floor(t) : void 0;
+	return o && u !== void 0 ? {
+		className: i("kapi-gridx", "kapi-gridx--cols", c),
+		style: {
+			...r({ gap: n(e) }),
+			"--kapi-grid-cols": u,
+			"--kapi-grid-cols-md": Math.min(u, 2),
+			...l
+		}
+	} : {
+		className: i("kapi-gridx", c),
+		style: {
+			...r({
+				gap: n(e),
+				gridTemplateColumns: s(t, a)
+			}),
+			...l
+		}
+	};
+};
+//#endregion
+export { o as clusterProps, n as gapValue, s as gridColumns, c as gridProps, a as stackProps };

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

@@ -0,0 +1,20 @@
+/** Posición del panel: debajo de la campana, alineado a su borde final (la campana suele ir a la derecha). */
+export declare const NOTIFICATION_BELL_PLACEMENT: {
+    readonly side: "bottom";
+    readonly align: "end";
+    readonly offset: 6;
+    readonly margin: 8;
+};
+/** Cantidad de notificaciones sin leer: todo ítem sin `read: true` cuenta como no leído. */
+export declare const unreadCount: (items: ReadonlyArray<{
+    read?: boolean;
+}>) => number;
+/** Texto del badge: vacío con 0 (se oculta), el número hasta `max` y `max+` por encima. */
+export declare const badgeText: (count: number, max?: number) => string;
+/** Nombre accesible del disparador: "Notificaciones" o "Notificaciones, 3 sin leer" (conteo real). */
+export declare const bellTriggerLabel: (title: string, count: number, unreadSuffix: string) => string;
+/**
+ * Valor del atributo `dateTime` de `<time>` de una notificación (ver `isoDateTime`): ISO para un
+ * `Date`, el string tal cual y `null` si la fecha es inválida.
+ */
+export declare const notificationDateTime: (date: Date | string) => string | null;

package/dist/components/layout/notificationBellLogic.js

@@ -0,0 +1,14 @@
+import { isoDateTime as e } from "../../hooks/dateFormat.js";
+//#region src/components/layout/notificationBellLogic.ts
+var t = {
+	side: "bottom",
+	align: "end",
+	offset: 6,
+	margin: 8
+}, n = (e) => e.reduce((e, t) => t.read ? e : e + 1, 0), r = (e, t = 9) => {
+	if (!Number.isFinite(e)) return "";
+	let n = Math.floor(e);
+	return n <= 0 ? "" : n > t ? `${t}+` : String(n);
+}, i = (e, t, n) => t > 0 ? `${e}, ${t} ${n}` : e, a = e;
+//#endregion
+export { t as NOTIFICATION_BELL_PLACEMENT, r as badgeText, i as bellTriggerLabel, a as notificationDateTime, n as unreadCount };

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

@@ -0,0 +1,52 @@
+import type { ReactNode } from "react";
+import type { KapiBadgeVariant } from "../display/KapiBadge";
+import type { KapiNavBadgeValue } from "../navigation/navBadgeLogic";
+export type KapiRailVariant = "labeled" | "compact";
+/** Zona fija de un ítem: `start` arriba (bajo la marca), `end` abajo (sobre el footer). */
+export type KapiRailPinned = "start" | "end";
+/** Zonas del rail: las dos fijas más la del medio, que scrollea. */
+export type KapiRailZone = KapiRailPinned | "scroll";
+/** Ítem del rail. `Id` acota los ids (p. ej. una unión de literales). */
+export type KapiRailItem<Id extends string = string> = {
+    id: Id;
+    label: string;
+    /** Ícono (lucide-react), p. ej. `<Home size={21} strokeWidth={1.8} />`. */
+    icon: ReactNode;
+    /** Si se pasa, el ítem es un enlace real (`<a>`) en vez de un botón; `onSelect` no se dispara. */
+    href?: string;
+    /** Marca el destino como otro sistema: agrega el ícono ↗ (sólo con `href`). */
+    external?: boolean;
+    /** Abrir el enlace en una pestaña nueva (sólo con `href`). */
+    newTab?: boolean;
+    /** Fija el ítem arriba (`start`) o abajo (`end`): no se mueve con el scroll. Sin valor, va a la zona del medio. */
+    pinned?: KapiRailPinned | undefined;
+    /** Aviso sobre el ícono: contador (0 no dibuja nada; tope "99+") 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;
+};
+/** Divisor entre grupos de ítems: `{ separator: true }` dentro de `items`. */
+export type KapiRailSeparator = {
+    separator: true;
+    /** Opcional, sólo para estabilizar la `key` si el orden cambia. */
+    id?: string;
+    /** Zona del divisor, igual que en los ítems. */
+    pinned?: KapiRailPinned | undefined;
+};
+export type KapiRailEntry<Id extends string = string> = KapiRailItem<Id> | KapiRailSeparator;
+export declare const isRailSeparator: <Id extends string>(entry: KapiRailEntry<Id>) => entry is KapiRailSeparator;
+/** Reparte las entradas en zona fija de arriba, zona que scrollea y zona fija de abajo (cada una en su orden). */
+export declare const splitRailEntries: <Id extends string>(entries: KapiRailEntry<Id>[]) => Record<KapiRailZone, KapiRailEntry<Id>[]>;
+/** Clases del `<nav>`: `compact` agrega el modificador que angosta el rail. */
+export declare const railClasses: ({ variant }?: {
+    variant?: KapiRailVariant;
+}) => string;
+/** Clases de un ítem (botón o enlace). */
+export declare const railItemClasses: ({ active, link }?: {
+    active?: boolean;
+    link?: boolean;
+}) => string;
+/** a11y: sólo `compact` muestra tooltip; en `labeled` la etiqueta ya es visible (sería redundante). */
+export declare const railShowsTooltip: (variant?: KapiRailVariant) => boolean;

package/dist/components/layout/railLogic.js

@@ -0,0 +1,16 @@
+//#region src/components/layout/railLogic.ts
+var e = (e) => "separator" in e && e.separator === !0, t = (e) => {
+	let t = {
+		start: [],
+		scroll: [],
+		end: []
+	};
+	for (let n of e) t[n.pinned ?? "scroll"].push(n);
+	return t;
+}, n = ({ variant: e = "labeled" } = {}) => ["kapi-rail", e === "compact" && "kapi-rail--compact"].filter(Boolean).join(" "), r = ({ active: e = !1, link: t = !1 } = {}) => [
+	"kapi-rail__item",
+	e && "kapi-rail__item--on",
+	t && "kapi-rail__item--link"
+].filter(Boolean).join(" "), i = (e = "labeled") => e === "compact";
+//#endregion
+export { e as isRailSeparator, n as railClasses, r as railItemClasses, i as railShowsTooltip, t as splitRailEntries };

package/dist/components/locale/KapiLocaleProvider.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+import { type KapiLabelsOverride } from "../labelsLogic";
+import type { KapiLabelOverrides, KapiLabelRegistry } from "./labelRegistry";
+export type KapiLocaleProviderProps = {
+    /** Locale BCP 47 (`"es-AR"`, `"en"`…) para comparaciones/formatos. Sin valor = el del runtime. */
+    locale?: string | undefined;
+    /**
+     * Textos por clave del registro, cada uno parcial: `{ table: { empty: "No data" } }`.
+     * Defínelo fuera del render (o memoízalo): un objeto nuevo por render re-renderiza a todos.
+     */
+    labels?: KapiLabelOverrides | undefined;
+    /** Subárbol que usa estos textos. */
+    children: ReactNode;
+};
+/**
+ * Un solo lugar para localizar o pisar el copy del DS. Precedencia por clave:
+ * defaults del componente < provider < prop `labels` del componente.
+ * Se puede anidar: el provider interno reemplaza al externo (no se mezclan).
+ */
+export declare function KapiLocaleProvider({ locale, labels, children }: KapiLocaleProviderProps): import("react").JSX.Element;
+/** Locale del `KapiLocaleProvider` más cercano, o `undefined` (= el del runtime) sin provider. */
+export declare const useKapiLocale: () => string | undefined;
+/**
+ * Textos resueltos de un componente: `defaults` < provider (por `key`) < `prop`.
+ * Una clave en `undefined` (en el provider o en la prop) no borra el valor anterior.
+ * Llamalo en el tope del componente (es un hook). El resultado es estable mientras no cambien
+ * `defaults`, el override del provider ni `prop`.
+ */
+export declare function useLabels<K extends keyof KapiLabelRegistry, L extends Partial<KapiLabelRegistry[K]>>(key: K, defaults: L, prop?: KapiLabelsOverride<L>): L;

package/dist/components/locale/KapiLocaleProvider.js

@@ -0,0 +1,27 @@
+"use client";
+import { withLabels as e } from "../labelsLogic.js";
+import { jsx as t } from "react/jsx-runtime";
+import { createContext as n, useContext as r, useMemo as i } from "react";
+//#region src/components/locale/KapiLocaleProvider.tsx
+var a = n(null), o = {};
+function s({ locale: e, labels: n = o, children: r }) {
+	let s = i(() => ({
+		locale: e,
+		labels: n
+	}), [e, n]);
+	return /* @__PURE__ */ t(a.Provider, {
+		value: s,
+		children: r
+	});
+}
+var c = () => r(a)?.locale;
+function l(t, n, o) {
+	let s = r(a)?.labels[t];
+	return i(() => e(s ? e(n, s) : n, o), [
+		n,
+		s,
+		o
+	]);
+}
+//#endregion
+export { s as KapiLocaleProvider, c as useKapiLocale, l as useLabels };

package/dist/components/locale/index.d.ts

@@ -0,0 +1,5 @@
+export { KapiLocaleProvider, useKapiLocale, useLabels } from "./KapiLocaleProvider";
+export type { KapiLocaleProviderProps } from "./KapiLocaleProvider";
+export type { KapiLabelOverrides, KapiLabelRegistry } from "./labelRegistry";
+export { DEFAULT_LINK_LABELS } from "./linkLabels";
+export type { KapiLinkLabels } from "./linkLabels";