@khipu/design-system 0.2.0-alpha.134 → 0.2.0-alpha.136

package/dist/beercss/metadata.json

@@ -1,8 +1,8 @@
 {
   "name": "@khipu/design-system/beercss",
-  "version": "0.2.0-alpha.134",
+  "version": "0.2.0-alpha.136",
   "description": "Khipu BeerCSS bundle with Material Design 3 and Khipu customizations",
-  "buildDate": "2026-07-21T18:07:11.562Z",
+  "buildDate": "2026-07-22T17:27:17.155Z",
   "includes": {
     "beercss": "4.0.1",
     "khipu-tokens": "latest",
@@ -19,8 +19,8 @@
   },
   "scopeClass": ".kds-theme-root",
   "cdn": {
-    "css": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.134/dist/beercss/khipu-beercss.min.css",
-    "cssScoped": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.134/dist/beercss/khipu-beercss.scoped.min.css",
-    "js": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.134/dist/beercss/khipu-beercss.min.js"
+    "css": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.136/dist/beercss/khipu-beercss.min.css",
+    "cssScoped": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.136/dist/beercss/khipu-beercss.scoped.min.css",
+    "js": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.136/dist/beercss/khipu-beercss.min.js"
   }
 }

package/dist/index.d.mts

@@ -3750,6 +3750,47 @@ interface KdsBillAttachmentsProps extends React__default.HTMLAttributes<HTMLDivE
  */
 declare const KdsBillAttachments: React__default.ForwardRefExoticComponent<KdsBillAttachmentsProps & React__default.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Corre el callback cuando termina el gesto de puntero en curso (fin del click),
+ * o tras un fallback corto si el gesto no era de puntero (Tab del teclado).
+ *
+ * Por qué: el blur de un campo llega en el mousedown, pero el click sobre el
+ * elemento destino (p.ej. el checkbox de términos) recién se completa en el
+ * mouseup EN LAS MISMAS COORDENADAS. Cualquier cambio de layout o robo de foco
+ * entre medio (mostrar un error bajo el campo, enfocar otro elemento) desplaza
+ * el destino y el click se pierde. Anclar el efecto al fin del click garantiza
+ * el orden: gesto completo → onChange/re-render → efecto.
+ */
+declare const runAfterPointerGesture: (callback: () => void) => void;
+
+/**
+ * Scroll + focus al primer campo inválido de un formulario.
+ *
+ * El scroll se aplica sobre el ancestro scrolleable real del campo (en la app el
+ * scroller es el body con height:100vh, no el window). El centrado usa la porción
+ * visible: con el teclado virtual abierto visualViewport se achica (el layout
+ * viewport no), así que centrar contra él deja el campo visible sobre el teclado.
+ * Además se re-centra una vez cuando el viewport cambia (apertura del teclado
+ * gatillada por el propio focus).
+ */
+declare const centerFieldInViewport: (field: HTMLElement) => void;
+declare const focusFirstInvalidField: (form: HTMLFormElement) => void;
+/**
+ * Trigger en el blur de los campos: el submit vive deshabilitado hasta que el form
+ * valida, así que la guía al primer campo con error debe correr al perder el foco
+ * (p.ej. al marcar el checkbox de términos con un campo vacío).
+ *
+ * La guía NO puede correr con un timer fijo: el blur llega en el mousedown y el
+ * toggle del checkbox recién en el click (mouseup) — si el gesto dura más que el
+ * timer, robar el foco a mitad de gesto deja el checkbox sin marcar. Por eso se
+ * ancla al fin del click que causó el blur (más un tick para que corran onChange
+ * y el re-render), con fallback por timer para blur de teclado (Tab).
+ *
+ * Guard anti-trampa: si el foco pasó a OTRO campo de texto del form (el usuario va
+ * a escribir ahí), no se le roba el foco.
+ */
+declare const guideToFirstInvalidFieldOnBlur: (form: HTMLFormElement) => void;
+
 declare function useCopyToClipboard(resetMs?: number): {
     copied: boolean;
     copy: (text: string) => Promise<void>;
@@ -3969,4 +4010,4 @@ declare function formatDate(iso?: string): string;
  */
 declare function formatTime(iso?: string): string;
 
-export { type Colors, type ExpandPanelProps, type ExpandToggleProps, KdsAccordion, KdsAccordionDetails, type KdsAccordionDetailsProps, type KdsAccordionProps, KdsAccordionSummary, type KdsAccordionSummaryProps, KdsAlert, type KdsAlertProps, type KdsAlertSeverity, KdsBankList, type KdsBankListProps, KdsBankModal, type KdsBankModalProps, KdsBankRow, type KdsBankRowProps, KdsBillAttachment, type KdsBillAttachmentProps, KdsBillAttachments, type KdsBillAttachmentsProps, KdsBottomSheet, type KdsBottomSheetProps, KdsButton, type KdsButtonProps, type KdsButtonSize, type KdsButtonVariant, KdsCard, KdsCardBody, KdsCardFooter, KdsCardHeader, KdsCardPlan, type KdsCardPlanProps, type KdsCardProps, type KdsCardSectionProps, KdsCardSelector, type KdsCardSelectorProps, type KdsCardVariant, KdsCheckbox, type KdsCheckboxProps, KdsChip, type KdsChipColor, type KdsChipProps, KdsCopyButton, type KdsCopyButtonProps, KdsCopyRow, type KdsCopyRowProps, KdsCopyableTable, type KdsCopyableTableProps, type KdsCopyableTableRow, KdsCountdown, type KdsCountdownProps, KdsDivider, type KdsDividerProps, KdsExpandPanel, type KdsExpandPanelProps, KdsFab, type KdsFabPosition, type KdsFabProps, KdsInvoiceMerchant, type KdsInvoiceMerchantProps, KdsInvoiceSticky, type KdsInvoiceStickyProps, KdsLinearProgress, type KdsLinearProgressProps, KdsMerchantTile, type KdsMerchantTileProps, KdsMontoRow, type KdsMontoRowProps, KdsPaymentTotal, type KdsPaymentTotalProps, type KdsPaymentTotalVariant, KdsQrRow, type KdsQrRowProps, KdsRadioGroup, type KdsRadioGroupProps, type KdsRadioOption, type KdsRecapItem, KdsRecapList, type KdsRecapListProps, KdsSearchField, type KdsSearchFieldProps, KdsSectionNote, type KdsSectionNoteProps, KdsSecureFooter, type KdsSecureFooterProps, KdsSecureLoader, type KdsSecureLoaderProps, KdsSegmentedTabs, type KdsSegmentedTabsProps, KdsSelect, type KdsSelectOption, type KdsSelectProps, KdsSnackbar, type KdsSnackbarProps, type KdsSnackbarType, KdsSpinner, type KdsSpinnerProps, type KdsSpinnerSize, KdsStatusBlock, type KdsStatusBlockProps, type KdsStatusType, KdsStepper, type KdsStepperProps, KdsTab, KdsTabPanel, type KdsTabPanelProps, type KdsTabProps, KdsTabs, type KdsTabsProps, KdsTextField, type KdsTextFieldProps, KdsThemeProvider, type KdsThemeProviderProps, KdsTooltip, type KdsTooltipPlacement, type KdsTooltipProps, KdsTypography, type KdsTypographyProps, type KdsTypographyVariant, LIGHT_LOGO_LUMINANCE_THRESHOLD, type LogoBackdrop, type ThemeMode, type Tokens, type TokensByMode, type Typography as TypographyTokens, type UseExpandToggleOptions, type UseExpandToggleResult, type UseHideOnScrollOptions, type UseHideOnScrollResult, type UseStickyInvoiceCollapseOptions, borderRadius, breakpoints, colors, colorsByMode, fontFamilies, fontSizes, fontWeights, formatDate, formatDateTime, formatTime, getContrastColor, letterSpacings, lighten, lineHeights, measureLogoLuminance, pickLogoBackdrop, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useExpandToggle, useHideOnScroll, useLogoBackdrop, useMediaQuery, useStickyInvoiceCollapse, useTabsKeyboard, zIndex };
+export { type Colors, type ExpandPanelProps, type ExpandToggleProps, KdsAccordion, KdsAccordionDetails, type KdsAccordionDetailsProps, type KdsAccordionProps, KdsAccordionSummary, type KdsAccordionSummaryProps, KdsAlert, type KdsAlertProps, type KdsAlertSeverity, KdsBankList, type KdsBankListProps, KdsBankModal, type KdsBankModalProps, KdsBankRow, type KdsBankRowProps, KdsBillAttachment, type KdsBillAttachmentProps, KdsBillAttachments, type KdsBillAttachmentsProps, KdsBottomSheet, type KdsBottomSheetProps, KdsButton, type KdsButtonProps, type KdsButtonSize, type KdsButtonVariant, KdsCard, KdsCardBody, KdsCardFooter, KdsCardHeader, KdsCardPlan, type KdsCardPlanProps, type KdsCardProps, type KdsCardSectionProps, KdsCardSelector, type KdsCardSelectorProps, type KdsCardVariant, KdsCheckbox, type KdsCheckboxProps, KdsChip, type KdsChipColor, type KdsChipProps, KdsCopyButton, type KdsCopyButtonProps, KdsCopyRow, type KdsCopyRowProps, KdsCopyableTable, type KdsCopyableTableProps, type KdsCopyableTableRow, KdsCountdown, type KdsCountdownProps, KdsDivider, type KdsDividerProps, KdsExpandPanel, type KdsExpandPanelProps, KdsFab, type KdsFabPosition, type KdsFabProps, KdsInvoiceMerchant, type KdsInvoiceMerchantProps, KdsInvoiceSticky, type KdsInvoiceStickyProps, KdsLinearProgress, type KdsLinearProgressProps, KdsMerchantTile, type KdsMerchantTileProps, KdsMontoRow, type KdsMontoRowProps, KdsPaymentTotal, type KdsPaymentTotalProps, type KdsPaymentTotalVariant, KdsQrRow, type KdsQrRowProps, KdsRadioGroup, type KdsRadioGroupProps, type KdsRadioOption, type KdsRecapItem, KdsRecapList, type KdsRecapListProps, KdsSearchField, type KdsSearchFieldProps, KdsSectionNote, type KdsSectionNoteProps, KdsSecureFooter, type KdsSecureFooterProps, KdsSecureLoader, type KdsSecureLoaderProps, KdsSegmentedTabs, type KdsSegmentedTabsProps, KdsSelect, type KdsSelectOption, type KdsSelectProps, KdsSnackbar, type KdsSnackbarProps, type KdsSnackbarType, KdsSpinner, type KdsSpinnerProps, type KdsSpinnerSize, KdsStatusBlock, type KdsStatusBlockProps, type KdsStatusType, KdsStepper, type KdsStepperProps, KdsTab, KdsTabPanel, type KdsTabPanelProps, type KdsTabProps, KdsTabs, type KdsTabsProps, KdsTextField, type KdsTextFieldProps, KdsThemeProvider, type KdsThemeProviderProps, KdsTooltip, type KdsTooltipPlacement, type KdsTooltipProps, KdsTypography, type KdsTypographyProps, type KdsTypographyVariant, LIGHT_LOGO_LUMINANCE_THRESHOLD, type LogoBackdrop, type ThemeMode, type Tokens, type TokensByMode, type Typography as TypographyTokens, type UseExpandToggleOptions, type UseExpandToggleResult, type UseHideOnScrollOptions, type UseHideOnScrollResult, type UseStickyInvoiceCollapseOptions, borderRadius, breakpoints, centerFieldInViewport, colors, colorsByMode, focusFirstInvalidField, fontFamilies, fontSizes, fontWeights, formatDate, formatDateTime, formatTime, getContrastColor, guideToFirstInvalidFieldOnBlur, letterSpacings, lighten, lineHeights, measureLogoLuminance, pickLogoBackdrop, runAfterPointerGesture, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useExpandToggle, useHideOnScroll, useLogoBackdrop, useMediaQuery, useStickyInvoiceCollapse, useTabsKeyboard, zIndex };

package/dist/index.d.ts

@@ -3750,6 +3750,47 @@ interface KdsBillAttachmentsProps extends React__default.HTMLAttributes<HTMLDivE
  */
 declare const KdsBillAttachments: React__default.ForwardRefExoticComponent<KdsBillAttachmentsProps & React__default.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Corre el callback cuando termina el gesto de puntero en curso (fin del click),
+ * o tras un fallback corto si el gesto no era de puntero (Tab del teclado).
+ *
+ * Por qué: el blur de un campo llega en el mousedown, pero el click sobre el
+ * elemento destino (p.ej. el checkbox de términos) recién se completa en el
+ * mouseup EN LAS MISMAS COORDENADAS. Cualquier cambio de layout o robo de foco
+ * entre medio (mostrar un error bajo el campo, enfocar otro elemento) desplaza
+ * el destino y el click se pierde. Anclar el efecto al fin del click garantiza
+ * el orden: gesto completo → onChange/re-render → efecto.
+ */
+declare const runAfterPointerGesture: (callback: () => void) => void;
+
+/**
+ * Scroll + focus al primer campo inválido de un formulario.
+ *
+ * El scroll se aplica sobre el ancestro scrolleable real del campo (en la app el
+ * scroller es el body con height:100vh, no el window). El centrado usa la porción
+ * visible: con el teclado virtual abierto visualViewport se achica (el layout
+ * viewport no), así que centrar contra él deja el campo visible sobre el teclado.
+ * Además se re-centra una vez cuando el viewport cambia (apertura del teclado
+ * gatillada por el propio focus).
+ */
+declare const centerFieldInViewport: (field: HTMLElement) => void;
+declare const focusFirstInvalidField: (form: HTMLFormElement) => void;
+/**
+ * Trigger en el blur de los campos: el submit vive deshabilitado hasta que el form
+ * valida, así que la guía al primer campo con error debe correr al perder el foco
+ * (p.ej. al marcar el checkbox de términos con un campo vacío).
+ *
+ * La guía NO puede correr con un timer fijo: el blur llega en el mousedown y el
+ * toggle del checkbox recién en el click (mouseup) — si el gesto dura más que el
+ * timer, robar el foco a mitad de gesto deja el checkbox sin marcar. Por eso se
+ * ancla al fin del click que causó el blur (más un tick para que corran onChange
+ * y el re-render), con fallback por timer para blur de teclado (Tab).
+ *
+ * Guard anti-trampa: si el foco pasó a OTRO campo de texto del form (el usuario va
+ * a escribir ahí), no se le roba el foco.
+ */
+declare const guideToFirstInvalidFieldOnBlur: (form: HTMLFormElement) => void;
+
 declare function useCopyToClipboard(resetMs?: number): {
     copied: boolean;
     copy: (text: string) => Promise<void>;
@@ -3969,4 +4010,4 @@ declare function formatDate(iso?: string): string;
  */
 declare function formatTime(iso?: string): string;
 
-export { type Colors, type ExpandPanelProps, type ExpandToggleProps, KdsAccordion, KdsAccordionDetails, type KdsAccordionDetailsProps, type KdsAccordionProps, KdsAccordionSummary, type KdsAccordionSummaryProps, KdsAlert, type KdsAlertProps, type KdsAlertSeverity, KdsBankList, type KdsBankListProps, KdsBankModal, type KdsBankModalProps, KdsBankRow, type KdsBankRowProps, KdsBillAttachment, type KdsBillAttachmentProps, KdsBillAttachments, type KdsBillAttachmentsProps, KdsBottomSheet, type KdsBottomSheetProps, KdsButton, type KdsButtonProps, type KdsButtonSize, type KdsButtonVariant, KdsCard, KdsCardBody, KdsCardFooter, KdsCardHeader, KdsCardPlan, type KdsCardPlanProps, type KdsCardProps, type KdsCardSectionProps, KdsCardSelector, type KdsCardSelectorProps, type KdsCardVariant, KdsCheckbox, type KdsCheckboxProps, KdsChip, type KdsChipColor, type KdsChipProps, KdsCopyButton, type KdsCopyButtonProps, KdsCopyRow, type KdsCopyRowProps, KdsCopyableTable, type KdsCopyableTableProps, type KdsCopyableTableRow, KdsCountdown, type KdsCountdownProps, KdsDivider, type KdsDividerProps, KdsExpandPanel, type KdsExpandPanelProps, KdsFab, type KdsFabPosition, type KdsFabProps, KdsInvoiceMerchant, type KdsInvoiceMerchantProps, KdsInvoiceSticky, type KdsInvoiceStickyProps, KdsLinearProgress, type KdsLinearProgressProps, KdsMerchantTile, type KdsMerchantTileProps, KdsMontoRow, type KdsMontoRowProps, KdsPaymentTotal, type KdsPaymentTotalProps, type KdsPaymentTotalVariant, KdsQrRow, type KdsQrRowProps, KdsRadioGroup, type KdsRadioGroupProps, type KdsRadioOption, type KdsRecapItem, KdsRecapList, type KdsRecapListProps, KdsSearchField, type KdsSearchFieldProps, KdsSectionNote, type KdsSectionNoteProps, KdsSecureFooter, type KdsSecureFooterProps, KdsSecureLoader, type KdsSecureLoaderProps, KdsSegmentedTabs, type KdsSegmentedTabsProps, KdsSelect, type KdsSelectOption, type KdsSelectProps, KdsSnackbar, type KdsSnackbarProps, type KdsSnackbarType, KdsSpinner, type KdsSpinnerProps, type KdsSpinnerSize, KdsStatusBlock, type KdsStatusBlockProps, type KdsStatusType, KdsStepper, type KdsStepperProps, KdsTab, KdsTabPanel, type KdsTabPanelProps, type KdsTabProps, KdsTabs, type KdsTabsProps, KdsTextField, type KdsTextFieldProps, KdsThemeProvider, type KdsThemeProviderProps, KdsTooltip, type KdsTooltipPlacement, type KdsTooltipProps, KdsTypography, type KdsTypographyProps, type KdsTypographyVariant, LIGHT_LOGO_LUMINANCE_THRESHOLD, type LogoBackdrop, type ThemeMode, type Tokens, type TokensByMode, type Typography as TypographyTokens, type UseExpandToggleOptions, type UseExpandToggleResult, type UseHideOnScrollOptions, type UseHideOnScrollResult, type UseStickyInvoiceCollapseOptions, borderRadius, breakpoints, colors, colorsByMode, fontFamilies, fontSizes, fontWeights, formatDate, formatDateTime, formatTime, getContrastColor, letterSpacings, lighten, lineHeights, measureLogoLuminance, pickLogoBackdrop, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useExpandToggle, useHideOnScroll, useLogoBackdrop, useMediaQuery, useStickyInvoiceCollapse, useTabsKeyboard, zIndex };
+export { type Colors, type ExpandPanelProps, type ExpandToggleProps, KdsAccordion, KdsAccordionDetails, type KdsAccordionDetailsProps, type KdsAccordionProps, KdsAccordionSummary, type KdsAccordionSummaryProps, KdsAlert, type KdsAlertProps, type KdsAlertSeverity, KdsBankList, type KdsBankListProps, KdsBankModal, type KdsBankModalProps, KdsBankRow, type KdsBankRowProps, KdsBillAttachment, type KdsBillAttachmentProps, KdsBillAttachments, type KdsBillAttachmentsProps, KdsBottomSheet, type KdsBottomSheetProps, KdsButton, type KdsButtonProps, type KdsButtonSize, type KdsButtonVariant, KdsCard, KdsCardBody, KdsCardFooter, KdsCardHeader, KdsCardPlan, type KdsCardPlanProps, type KdsCardProps, type KdsCardSectionProps, KdsCardSelector, type KdsCardSelectorProps, type KdsCardVariant, KdsCheckbox, type KdsCheckboxProps, KdsChip, type KdsChipColor, type KdsChipProps, KdsCopyButton, type KdsCopyButtonProps, KdsCopyRow, type KdsCopyRowProps, KdsCopyableTable, type KdsCopyableTableProps, type KdsCopyableTableRow, KdsCountdown, type KdsCountdownProps, KdsDivider, type KdsDividerProps, KdsExpandPanel, type KdsExpandPanelProps, KdsFab, type KdsFabPosition, type KdsFabProps, KdsInvoiceMerchant, type KdsInvoiceMerchantProps, KdsInvoiceSticky, type KdsInvoiceStickyProps, KdsLinearProgress, type KdsLinearProgressProps, KdsMerchantTile, type KdsMerchantTileProps, KdsMontoRow, type KdsMontoRowProps, KdsPaymentTotal, type KdsPaymentTotalProps, type KdsPaymentTotalVariant, KdsQrRow, type KdsQrRowProps, KdsRadioGroup, type KdsRadioGroupProps, type KdsRadioOption, type KdsRecapItem, KdsRecapList, type KdsRecapListProps, KdsSearchField, type KdsSearchFieldProps, KdsSectionNote, type KdsSectionNoteProps, KdsSecureFooter, type KdsSecureFooterProps, KdsSecureLoader, type KdsSecureLoaderProps, KdsSegmentedTabs, type KdsSegmentedTabsProps, KdsSelect, type KdsSelectOption, type KdsSelectProps, KdsSnackbar, type KdsSnackbarProps, type KdsSnackbarType, KdsSpinner, type KdsSpinnerProps, type KdsSpinnerSize, KdsStatusBlock, type KdsStatusBlockProps, type KdsStatusType, KdsStepper, type KdsStepperProps, KdsTab, KdsTabPanel, type KdsTabPanelProps, type KdsTabProps, KdsTabs, type KdsTabsProps, KdsTextField, type KdsTextFieldProps, KdsThemeProvider, type KdsThemeProviderProps, KdsTooltip, type KdsTooltipPlacement, type KdsTooltipProps, KdsTypography, type KdsTypographyProps, type KdsTypographyVariant, LIGHT_LOGO_LUMINANCE_THRESHOLD, type LogoBackdrop, type ThemeMode, type Tokens, type TokensByMode, type Typography as TypographyTokens, type UseExpandToggleOptions, type UseExpandToggleResult, type UseHideOnScrollOptions, type UseHideOnScrollResult, type UseStickyInvoiceCollapseOptions, borderRadius, breakpoints, centerFieldInViewport, colors, colorsByMode, focusFirstInvalidField, fontFamilies, fontSizes, fontWeights, formatDate, formatDateTime, formatTime, getContrastColor, guideToFirstInvalidFieldOnBlur, letterSpacings, lighten, lineHeights, measureLogoLuminance, pickLogoBackdrop, runAfterPointerGesture, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useExpandToggle, useHideOnScroll, useLogoBackdrop, useMediaQuery, useStickyInvoiceCollapse, useTabsKeyboard, zIndex };

package/dist/index.js

@@ -85,9 +85,11 @@ __export(index_exports, {
   LIGHT_LOGO_LUMINANCE_THRESHOLD: () => LIGHT_LOGO_LUMINANCE_THRESHOLD,
   borderRadius: () => borderRadius,
   breakpoints: () => breakpoints,
+  centerFieldInViewport: () => centerFieldInViewport,
   clsx: () => import_clsx.clsx,
   colors: () => colors,
   colorsByMode: () => colorsByMode,
+  focusFirstInvalidField: () => focusFirstInvalidField,
   fontFamilies: () => fontFamilies,
   fontSizes: () => fontSizes,
   fontWeights: () => fontWeights,
@@ -95,11 +97,13 @@ __export(index_exports, {
   formatDateTime: () => formatDateTime,
   formatTime: () => formatTime,
   getContrastColor: () => getContrastColor,
+  guideToFirstInvalidFieldOnBlur: () => guideToFirstInvalidFieldOnBlur,
   letterSpacings: () => letterSpacings,
   lighten: () => lighten,
   lineHeights: () => lineHeights,
   measureLogoLuminance: () => measureLogoLuminance,
   pickLogoBackdrop: () => pickLogoBackdrop,
+  runAfterPointerGesture: () => runAfterPointerGesture,
   semanticSpacing: () => semanticSpacing,
   shadows: () => shadows,
   spacing: () => spacing,
@@ -2820,6 +2824,100 @@ var KdsBillAttachments = (0, import_react48.forwardRef)(
 );
 KdsBillAttachments.displayName = "KdsBillAttachments";
 
+// src/utils/runAfterPointerGesture.ts
+var KEYBOARD_FALLBACK_MS = 400;
+var runAfterPointerGesture = (callback) => {
+  let done = false;
+  const run = () => {
+    if (done) {
+      return;
+    }
+    done = true;
+    document.removeEventListener("click", run, true);
+    window.setTimeout(callback, 0);
+  };
+  document.addEventListener("click", run, true);
+  window.setTimeout(run, KEYBOARD_FALLBACK_MS);
+};
+
+// src/utils/focusFirstInvalidField.ts
+var RECENTER_WINDOW_MS = 1500;
+var getScrollParent = (field) => {
+  let node = field.parentElement;
+  while (node) {
+    const style = getComputedStyle(node);
+    if (node.scrollHeight > node.clientHeight && /auto|scroll|overlay/.test(style.overflowY)) {
+      const htmlOverflow = getComputedStyle(document.documentElement).overflowY;
+      if (node === document.body && (htmlOverflow === "visible" || htmlOverflow === "")) {
+        return null;
+      }
+      return node;
+    }
+    node = node.parentElement;
+  }
+  return null;
+};
+var centerFieldInViewport = (field) => {
+  const viewport = window.visualViewport;
+  const viewportTop = viewport?.offsetTop ?? 0;
+  const viewportHeight = viewport?.height ?? window.innerHeight;
+  const rect = field.getBoundingClientRect();
+  const scroller = getScrollParent(field);
+  if (!scroller || scroller === document.documentElement || scroller === document.scrollingElement) {
+    const top = window.scrollY + rect.top - viewportTop - (viewportHeight - rect.height) / 2;
+    window.scrollTo({ top: Math.max(top, 0), behavior: "smooth" });
+    return;
+  }
+  const scrollerRect = scroller.getBoundingClientRect();
+  const visibleTop = Math.max(scrollerRect.top, viewportTop);
+  const visibleBottom = Math.min(scrollerRect.bottom, viewportTop + viewportHeight);
+  const visibleHeight = Math.max(visibleBottom - visibleTop, 0);
+  const target = scroller.scrollTop + (rect.top - visibleTop) - (visibleHeight - rect.height) / 2;
+  scroller.scrollTo({ top: Math.max(target, 0), behavior: "smooth" });
+};
+var isInvalidField = (element) => {
+  const field = element;
+  return typeof field.willValidate === "boolean" && field.willValidate && !field.validity.valid;
+};
+var focusFirstInvalidField = (form) => {
+  const firstInvalid = Array.from(form.elements).find(isInvalidField);
+  if (!firstInvalid) {
+    return;
+  }
+  firstInvalid.focus({ preventScroll: true });
+  centerFieldInViewport(firstInvalid);
+  const viewport = window.visualViewport;
+  if (viewport) {
+    const recenter = () => centerFieldInViewport(firstInvalid);
+    viewport.addEventListener("resize", recenter, { once: true });
+    window.setTimeout(() => viewport.removeEventListener("resize", recenter), RECENTER_WINDOW_MS);
+  }
+};
+var isTextEntryElement = (element) => {
+  if (!element) {
+    return false;
+  }
+  if (element.tagName === "TEXTAREA") {
+    return true;
+  }
+  const input = element;
+  return element.tagName === "INPUT" && !["checkbox", "radio", "button", "submit", "reset"].includes(input.type);
+};
+var guideToFirstInvalidFieldOnBlur = (form) => {
+  runAfterPointerGesture(() => {
+    if (!form.isConnected) {
+      return;
+    }
+    const active = document.activeElement;
+    if (active && form.contains(active) && isTextEntryElement(active)) {
+      return;
+    }
+    if (!form.checkValidity()) {
+      focusFirstInvalidField(form);
+    }
+  });
+};
+
 // src/components/core/hooks/useStickyInvoiceCollapse.ts
 var import_react49 = require("react");
 function useStickyInvoiceCollapse(options = {}) {
@@ -3067,9 +3165,11 @@ function useMediaQuery(query) {
   LIGHT_LOGO_LUMINANCE_THRESHOLD,
   borderRadius,
   breakpoints,
+  centerFieldInViewport,
   clsx,
   colors,
   colorsByMode,
+  focusFirstInvalidField,
   fontFamilies,
   fontSizes,
   fontWeights,
@@ -3077,11 +3177,13 @@ function useMediaQuery(query) {
   formatDateTime,
   formatTime,
   getContrastColor,
+  guideToFirstInvalidFieldOnBlur,
   letterSpacings,
   lighten,
   lineHeights,
   measureLogoLuminance,
   pickLogoBackdrop,
+  runAfterPointerGesture,
   semanticSpacing,
   shadows,
   spacing,

package/dist/index.mjs

@@ -2698,6 +2698,100 @@ var KdsBillAttachments = forwardRef43(
 );
 KdsBillAttachments.displayName = "KdsBillAttachments";
 
+// src/utils/runAfterPointerGesture.ts
+var KEYBOARD_FALLBACK_MS = 400;
+var runAfterPointerGesture = (callback) => {
+  let done = false;
+  const run = () => {
+    if (done) {
+      return;
+    }
+    done = true;
+    document.removeEventListener("click", run, true);
+    window.setTimeout(callback, 0);
+  };
+  document.addEventListener("click", run, true);
+  window.setTimeout(run, KEYBOARD_FALLBACK_MS);
+};
+
+// src/utils/focusFirstInvalidField.ts
+var RECENTER_WINDOW_MS = 1500;
+var getScrollParent = (field) => {
+  let node = field.parentElement;
+  while (node) {
+    const style = getComputedStyle(node);
+    if (node.scrollHeight > node.clientHeight && /auto|scroll|overlay/.test(style.overflowY)) {
+      const htmlOverflow = getComputedStyle(document.documentElement).overflowY;
+      if (node === document.body && (htmlOverflow === "visible" || htmlOverflow === "")) {
+        return null;
+      }
+      return node;
+    }
+    node = node.parentElement;
+  }
+  return null;
+};
+var centerFieldInViewport = (field) => {
+  const viewport = window.visualViewport;
+  const viewportTop = viewport?.offsetTop ?? 0;
+  const viewportHeight = viewport?.height ?? window.innerHeight;
+  const rect = field.getBoundingClientRect();
+  const scroller = getScrollParent(field);
+  if (!scroller || scroller === document.documentElement || scroller === document.scrollingElement) {
+    const top = window.scrollY + rect.top - viewportTop - (viewportHeight - rect.height) / 2;
+    window.scrollTo({ top: Math.max(top, 0), behavior: "smooth" });
+    return;
+  }
+  const scrollerRect = scroller.getBoundingClientRect();
+  const visibleTop = Math.max(scrollerRect.top, viewportTop);
+  const visibleBottom = Math.min(scrollerRect.bottom, viewportTop + viewportHeight);
+  const visibleHeight = Math.max(visibleBottom - visibleTop, 0);
+  const target = scroller.scrollTop + (rect.top - visibleTop) - (visibleHeight - rect.height) / 2;
+  scroller.scrollTo({ top: Math.max(target, 0), behavior: "smooth" });
+};
+var isInvalidField = (element) => {
+  const field = element;
+  return typeof field.willValidate === "boolean" && field.willValidate && !field.validity.valid;
+};
+var focusFirstInvalidField = (form) => {
+  const firstInvalid = Array.from(form.elements).find(isInvalidField);
+  if (!firstInvalid) {
+    return;
+  }
+  firstInvalid.focus({ preventScroll: true });
+  centerFieldInViewport(firstInvalid);
+  const viewport = window.visualViewport;
+  if (viewport) {
+    const recenter = () => centerFieldInViewport(firstInvalid);
+    viewport.addEventListener("resize", recenter, { once: true });
+    window.setTimeout(() => viewport.removeEventListener("resize", recenter), RECENTER_WINDOW_MS);
+  }
+};
+var isTextEntryElement = (element) => {
+  if (!element) {
+    return false;
+  }
+  if (element.tagName === "TEXTAREA") {
+    return true;
+  }
+  const input = element;
+  return element.tagName === "INPUT" && !["checkbox", "radio", "button", "submit", "reset"].includes(input.type);
+};
+var guideToFirstInvalidFieldOnBlur = (form) => {
+  runAfterPointerGesture(() => {
+    if (!form.isConnected) {
+      return;
+    }
+    const active = document.activeElement;
+    if (active && form.contains(active) && isTextEntryElement(active)) {
+      return;
+    }
+    if (!form.checkValidity()) {
+      focusFirstInvalidField(form);
+    }
+  });
+};
+
 // src/components/core/hooks/useStickyInvoiceCollapse.ts
 import { useEffect as useEffect5, useRef as useRef4 } from "react";
 function useStickyInvoiceCollapse(options = {}) {
@@ -2944,9 +3038,11 @@ export {
   LIGHT_LOGO_LUMINANCE_THRESHOLD,
   borderRadius,
   breakpoints,
+  centerFieldInViewport,
   clsx,
   colors,
   colorsByMode,
+  focusFirstInvalidField,
   fontFamilies,
   fontSizes,
   fontWeights,
@@ -2954,11 +3050,13 @@ export {
   formatDateTime,
   formatTime,
   getContrastColor,
+  guideToFirstInvalidFieldOnBlur,
   letterSpacings,
   lighten,
   lineHeights,
   measureLogoLuminance,
   pickLogoBackdrop,
+  runAfterPointerGesture,
   semanticSpacing,
   shadows,
   spacing,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khipu/design-system",
-  "version": "0.2.0-alpha.134",
+  "version": "0.2.0-alpha.136",
   "description": "Khipu Design System - UI components and design tokens for the Khipu payment platform",
   "main": "dist/index.js",
   "module": "dist/index.mjs",