@khipu/design-system 0.2.0-alpha.83 → 0.2.0-alpha.84

package/dist/beercss/metadata.json

@@ -1,8 +1,8 @@
 {
   "name": "@khipu/design-system/beercss",
-  "version": "0.2.0-alpha.83",
+  "version": "0.2.0-alpha.84",
   "description": "Khipu BeerCSS bundle with Material Design 3 and Khipu customizations",
-  "buildDate": "2026-07-01T02:24:52.411Z",
+  "buildDate": "2026-07-01T17:49:02.523Z",
   "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.83/dist/beercss/khipu-beercss.min.css",
-    "cssScoped": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.83/dist/beercss/khipu-beercss.scoped.min.css",
-    "js": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.83/dist/beercss/khipu-beercss.min.js"
+    "css": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.84/dist/beercss/khipu-beercss.min.css",
+    "cssScoped": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.84/dist/beercss/khipu-beercss.scoped.min.css",
+    "js": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.84/dist/beercss/khipu-beercss.min.js"
   }
 }

package/dist/index.d.mts

@@ -3298,6 +3298,40 @@ declare const KdsCountdown: React__default.ForwardRefExoticComponent<KdsCountdow
 type KdsSegmentedTabsProps = KdsTabsProps;
 declare const KdsSegmentedTabs: React$1.ForwardRefExoticComponent<KdsTabsProps & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Khipu Design System - Floating Action Button (FAB)
+ *
+ * A circular, icon-only floating button built with native HTML and kds-* CSS classes.
+ * Presentational only: pair it with `useHideOnScroll` and drive the `hidden` prop for
+ * hide-on-scroll behavior.
+ */
+
+type KdsFabPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'none';
+interface KdsFabProps extends React__default.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Material Symbols icon name, e.g. "close". */
+    icon: string;
+    /** Accessible label — required, since the button is icon-only. */
+    'aria-label': string;
+    /** Corner to pin to (fixed). Use `none` to leave positioning to the consumer. Default `top-right`. */
+    position?: KdsFabPosition;
+    /** When true, animates the button out (fade + slight move) and disables interaction. */
+    hidden?: boolean;
+}
+/**
+ * Floating action button — circular, icon-only, with an animated hide state.
+ *
+ * @example
+ * ```tsx
+ * // Static, pinned top-right
+ * <KdsFab icon="close" aria-label="Cancelar pago" onClick={openCancel} />
+ *
+ * // Hide on scroll down, show on scroll up
+ * const { hidden } = useHideOnScroll();
+ * <KdsFab icon="close" aria-label="Cancelar pago" hidden={hidden} onClick={openCancel} />
+ * ```
+ */
+declare const KdsFab: React__default.ForwardRefExoticComponent<KdsFabProps & React__default.RefAttributes<HTMLButtonElement>>;
+
 interface KdsBankRowProps extends Omit<React__default.ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'name'> {
     /**
      * Contenido principal de la fila. Acepta texto o nodo — permite contenido en
@@ -3798,6 +3832,40 @@ interface UseExpandToggleResult {
  */
 declare function useExpandToggle(options?: UseExpandToggleOptions): UseExpandToggleResult;
 
+/**
+ * Options for {@link useHideOnScroll}.
+ */
+interface UseHideOnScrollOptions {
+    /** Minimum scroll delta (px) before toggling, to avoid jitter. Default 8. */
+    threshold?: number;
+    /** Scroll offset (px) at/under which the element is always visible. Default 0. */
+    topOffset?: number;
+}
+/**
+ * Result of {@link useHideOnScroll}.
+ */
+interface UseHideOnScrollResult {
+    /** True when the element should be hidden (user scrolled down past the threshold). */
+    hidden: boolean;
+}
+/**
+ * Hide-on-scroll-down / show-on-scroll-up for floating UI (e.g. `KdsFab`).
+ *
+ * Returns `{ hidden }`: starts visible, hides once the user scrolls **down** past
+ * `threshold`, shows again as soon as they scroll **up**, and is always visible while
+ * within `topOffset` of the top. Coalesced through `requestAnimationFrame` so it stays cheap.
+ *
+ * Works standalone (`window.scrollY`) and **embedded in an iframe**, where the widget does
+ * not scroll internally and the parent posts the scroll offset via
+ * `postMessage({ type: 'VIEWPORT_OFFSET', offsetTop })` — the same mechanism as
+ * {@link useStickyInvoiceCollapse}.
+ *
+ * @example
+ * const { hidden } = useHideOnScroll();
+ * <KdsFab icon="close" aria-label="Cancelar" hidden={hidden} onClick={open} />
+ */
+declare function useHideOnScroll(options?: UseHideOnScrollOptions): UseHideOnScrollResult;
+
 /**
  * Khipu Design System - Core Utilities
  *
@@ -3816,4 +3884,4 @@ declare function getContrastColor(hex: string): string;
  */
 declare function lighten(hex: string, amount: number): 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, 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, type ThemeMode, type Tokens, type TokensByMode, type Typography as TypographyTokens, type UseExpandToggleOptions, type UseExpandToggleResult, type UseStickyInvoiceCollapseOptions, borderRadius, breakpoints, colors, colorsByMode, fontFamilies, fontSizes, fontWeights, getContrastColor, letterSpacings, lighten, lineHeights, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useExpandToggle, 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, 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, getContrastColor, letterSpacings, lighten, lineHeights, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useExpandToggle, useHideOnScroll, useStickyInvoiceCollapse, useTabsKeyboard, zIndex };

package/dist/index.d.ts

@@ -3298,6 +3298,40 @@ declare const KdsCountdown: React__default.ForwardRefExoticComponent<KdsCountdow
 type KdsSegmentedTabsProps = KdsTabsProps;
 declare const KdsSegmentedTabs: React$1.ForwardRefExoticComponent<KdsTabsProps & React$1.RefAttributes<HTMLDivElement>>;
 
+/**
+ * Khipu Design System - Floating Action Button (FAB)
+ *
+ * A circular, icon-only floating button built with native HTML and kds-* CSS classes.
+ * Presentational only: pair it with `useHideOnScroll` and drive the `hidden` prop for
+ * hide-on-scroll behavior.
+ */
+
+type KdsFabPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'none';
+interface KdsFabProps extends React__default.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Material Symbols icon name, e.g. "close". */
+    icon: string;
+    /** Accessible label — required, since the button is icon-only. */
+    'aria-label': string;
+    /** Corner to pin to (fixed). Use `none` to leave positioning to the consumer. Default `top-right`. */
+    position?: KdsFabPosition;
+    /** When true, animates the button out (fade + slight move) and disables interaction. */
+    hidden?: boolean;
+}
+/**
+ * Floating action button — circular, icon-only, with an animated hide state.
+ *
+ * @example
+ * ```tsx
+ * // Static, pinned top-right
+ * <KdsFab icon="close" aria-label="Cancelar pago" onClick={openCancel} />
+ *
+ * // Hide on scroll down, show on scroll up
+ * const { hidden } = useHideOnScroll();
+ * <KdsFab icon="close" aria-label="Cancelar pago" hidden={hidden} onClick={openCancel} />
+ * ```
+ */
+declare const KdsFab: React__default.ForwardRefExoticComponent<KdsFabProps & React__default.RefAttributes<HTMLButtonElement>>;
+
 interface KdsBankRowProps extends Omit<React__default.ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'name'> {
     /**
      * Contenido principal de la fila. Acepta texto o nodo — permite contenido en
@@ -3798,6 +3832,40 @@ interface UseExpandToggleResult {
  */
 declare function useExpandToggle(options?: UseExpandToggleOptions): UseExpandToggleResult;
 
+/**
+ * Options for {@link useHideOnScroll}.
+ */
+interface UseHideOnScrollOptions {
+    /** Minimum scroll delta (px) before toggling, to avoid jitter. Default 8. */
+    threshold?: number;
+    /** Scroll offset (px) at/under which the element is always visible. Default 0. */
+    topOffset?: number;
+}
+/**
+ * Result of {@link useHideOnScroll}.
+ */
+interface UseHideOnScrollResult {
+    /** True when the element should be hidden (user scrolled down past the threshold). */
+    hidden: boolean;
+}
+/**
+ * Hide-on-scroll-down / show-on-scroll-up for floating UI (e.g. `KdsFab`).
+ *
+ * Returns `{ hidden }`: starts visible, hides once the user scrolls **down** past
+ * `threshold`, shows again as soon as they scroll **up**, and is always visible while
+ * within `topOffset` of the top. Coalesced through `requestAnimationFrame` so it stays cheap.
+ *
+ * Works standalone (`window.scrollY`) and **embedded in an iframe**, where the widget does
+ * not scroll internally and the parent posts the scroll offset via
+ * `postMessage({ type: 'VIEWPORT_OFFSET', offsetTop })` — the same mechanism as
+ * {@link useStickyInvoiceCollapse}.
+ *
+ * @example
+ * const { hidden } = useHideOnScroll();
+ * <KdsFab icon="close" aria-label="Cancelar" hidden={hidden} onClick={open} />
+ */
+declare function useHideOnScroll(options?: UseHideOnScrollOptions): UseHideOnScrollResult;
+
 /**
  * Khipu Design System - Core Utilities
  *
@@ -3816,4 +3884,4 @@ declare function getContrastColor(hex: string): string;
  */
 declare function lighten(hex: string, amount: number): 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, 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, type ThemeMode, type Tokens, type TokensByMode, type Typography as TypographyTokens, type UseExpandToggleOptions, type UseExpandToggleResult, type UseStickyInvoiceCollapseOptions, borderRadius, breakpoints, colors, colorsByMode, fontFamilies, fontSizes, fontWeights, getContrastColor, letterSpacings, lighten, lineHeights, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useExpandToggle, 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, 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, getContrastColor, letterSpacings, lighten, lineHeights, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useExpandToggle, useHideOnScroll, useStickyInvoiceCollapse, useTabsKeyboard, zIndex };