@khipu/design-system 0.2.0-alpha.76 → 0.2.0-alpha.78

package/dist/beercss/metadata.json

@@ -1,8 +1,8 @@
 {
   "name": "@khipu/design-system/beercss",
-  "version": "0.2.0-alpha.76",
+  "version": "0.2.0-alpha.78",
   "description": "Khipu BeerCSS bundle with Material Design 3 and Khipu customizations",
-  "buildDate": "2026-06-25T20:08:52.748Z",
+  "buildDate": "2026-06-26T12:31:17.989Z",
   "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.76/dist/beercss/khipu-beercss.min.css",
-    "cssScoped": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.76/dist/beercss/khipu-beercss.scoped.min.css",
-    "js": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.76/dist/beercss/khipu-beercss.min.js"
+    "css": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.78/dist/beercss/khipu-beercss.min.css",
+    "cssScoped": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.78/dist/beercss/khipu-beercss.scoped.min.css",
+    "js": "https://cdn.jsdelivr.net/npm/@khipu/design-system@0.2.0-alpha.78/dist/beercss/khipu-beercss.min.js"
   }
 }

package/dist/index.d.mts

@@ -3667,6 +3667,47 @@ declare function useTabsKeyboard(tabCount: number, activeIndex: number, onChange
     onKeyDown: (e: React.KeyboardEvent) => void;
 };
 
+/**
+ * Options for {@link useStickyInvoiceCollapse}.
+ */
+interface UseStickyInvoiceCollapseOptions {
+    /**
+     * Called once each time the sticky header *starts* collapsing (scroll crosses the
+     * threshold, progress 0 → >0). Use it to close any open expand panel from React
+     * state — mirrors the vanilla DS behavior that closes `[data-expand-toggle]` panels
+     * as soon as the header begins to collapse. Not fired again until the header
+     * fully expands (progress returns to 0).
+     */
+    onCollapseStart?: () => void;
+    /**
+     * Scroll/collapse range end in px (header is fully collapsed at this scroll). Default 20.
+     */
+    collapseEnd?: number;
+    /**
+     * Max viewport width (px) for the collapse to apply. Desktop is always expanded. Default 768.
+     */
+    mobileBreakpoint?: number;
+}
+/**
+ * React port of the DS vanilla `initStickyInvoice` (`khipu-init.js`).
+ *
+ * On **mobile only** (< `mobileBreakpoint`), maps scroll (0 → `collapseEnd`px) to
+ * `--collapse-progress` (0 → 1) on `.kds-screen.active`; the scoped DS CSS interpolates
+ * the sticky-header collapse + box-shadow. Also caches `--collapse-collapsible-h`,
+ * toggles `.is-collapsed` on `.kds-invoice-sticky`, and closes any open expand panel as
+ * soon as the header starts collapsing (DOM `[data-expand-toggle]` / `.kds-expand-toggle`
+ * for uncontrolled consumers, plus the {@link UseStickyInvoiceCollapseOptions.onCollapseStart}
+ * callback for React-controlled toggles).
+ *
+ * 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 })`.
+ *
+ * This hook only reads/writes the DOM and `window` listeners; it renders nothing and
+ * returns nothing. Call it once near the root of the payment screen.
+ */
+declare function useStickyInvoiceCollapse(options?: UseStickyInvoiceCollapseOptions): void;
+
 /**
  * Khipu Design System - Core Utilities
  *
@@ -3685,4 +3726,4 @@ declare function getContrastColor(hex: string): string;
  */
 declare function lighten(hex: string, amount: number): string;
 
-export { type Colors, 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, 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, borderRadius, breakpoints, colors, colorsByMode, fontFamilies, fontSizes, fontWeights, getContrastColor, letterSpacings, lighten, lineHeights, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useTabsKeyboard, zIndex };
+export { type Colors, 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, 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 UseStickyInvoiceCollapseOptions, borderRadius, breakpoints, colors, colorsByMode, fontFamilies, fontSizes, fontWeights, getContrastColor, letterSpacings, lighten, lineHeights, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useStickyInvoiceCollapse, useTabsKeyboard, zIndex };

package/dist/index.d.ts

@@ -3667,6 +3667,47 @@ declare function useTabsKeyboard(tabCount: number, activeIndex: number, onChange
     onKeyDown: (e: React.KeyboardEvent) => void;
 };
 
+/**
+ * Options for {@link useStickyInvoiceCollapse}.
+ */
+interface UseStickyInvoiceCollapseOptions {
+    /**
+     * Called once each time the sticky header *starts* collapsing (scroll crosses the
+     * threshold, progress 0 → >0). Use it to close any open expand panel from React
+     * state — mirrors the vanilla DS behavior that closes `[data-expand-toggle]` panels
+     * as soon as the header begins to collapse. Not fired again until the header
+     * fully expands (progress returns to 0).
+     */
+    onCollapseStart?: () => void;
+    /**
+     * Scroll/collapse range end in px (header is fully collapsed at this scroll). Default 20.
+     */
+    collapseEnd?: number;
+    /**
+     * Max viewport width (px) for the collapse to apply. Desktop is always expanded. Default 768.
+     */
+    mobileBreakpoint?: number;
+}
+/**
+ * React port of the DS vanilla `initStickyInvoice` (`khipu-init.js`).
+ *
+ * On **mobile only** (< `mobileBreakpoint`), maps scroll (0 → `collapseEnd`px) to
+ * `--collapse-progress` (0 → 1) on `.kds-screen.active`; the scoped DS CSS interpolates
+ * the sticky-header collapse + box-shadow. Also caches `--collapse-collapsible-h`,
+ * toggles `.is-collapsed` on `.kds-invoice-sticky`, and closes any open expand panel as
+ * soon as the header starts collapsing (DOM `[data-expand-toggle]` / `.kds-expand-toggle`
+ * for uncontrolled consumers, plus the {@link UseStickyInvoiceCollapseOptions.onCollapseStart}
+ * callback for React-controlled toggles).
+ *
+ * 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 })`.
+ *
+ * This hook only reads/writes the DOM and `window` listeners; it renders nothing and
+ * returns nothing. Call it once near the root of the payment screen.
+ */
+declare function useStickyInvoiceCollapse(options?: UseStickyInvoiceCollapseOptions): void;
+
 /**
  * Khipu Design System - Core Utilities
  *
@@ -3685,4 +3726,4 @@ declare function getContrastColor(hex: string): string;
  */
 declare function lighten(hex: string, amount: number): string;
 
-export { type Colors, 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, 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, borderRadius, breakpoints, colors, colorsByMode, fontFamilies, fontSizes, fontWeights, getContrastColor, letterSpacings, lighten, lineHeights, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useTabsKeyboard, zIndex };
+export { type Colors, 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, 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 UseStickyInvoiceCollapseOptions, borderRadius, breakpoints, colors, colorsByMode, fontFamilies, fontSizes, fontWeights, getContrastColor, letterSpacings, lighten, lineHeights, semanticSpacing, shadows, spacing, tokens, tokensByMode, transitions, typography, useAutoHide, useCopyToClipboard, useCountdown, useStickyInvoiceCollapse, useTabsKeyboard, zIndex };

package/dist/index.js

@@ -102,6 +102,7 @@ __export(index_exports, {
   useAutoHide: () => useAutoHide,
   useCopyToClipboard: () => useCopyToClipboard,
   useCountdown: () => useCountdown,
+  useStickyInvoiceCollapse: () => useStickyInvoiceCollapse,
   useTabsKeyboard: () => useTabsKeyboard,
   zIndex: () => zIndex
 });
@@ -2627,6 +2628,83 @@ var KdsBillAttachments = (0, import_react45.forwardRef)(
   ({ children, className, ...props }, ref) => /* @__PURE__ */ (0, import_jsx_runtime43.jsx)("div", { ref, className: (0, import_clsx.clsx)("kds-bill-attachments", className), ...props, children })
 );
 KdsBillAttachments.displayName = "KdsBillAttachments";
+
+// src/components/core/hooks/useStickyInvoiceCollapse.ts
+var import_react46 = require("react");
+function useStickyInvoiceCollapse(options = {}) {
+  const { onCollapseStart, collapseEnd = 20, mobileBreakpoint = 768 } = options;
+  const onCollapseStartRef = (0, import_react46.useRef)(onCollapseStart);
+  onCollapseStartRef.current = onCollapseStart;
+  (0, import_react46.useEffect)(() => {
+    let viewportOffset = 0;
+    let ticking = false;
+    let wasCollapsing = false;
+    const isMobile = () => window.innerWidth < mobileBreakpoint;
+    const closeOpenPanels = (sticky) => {
+      const toggles = sticky.querySelectorAll(
+        '[data-expand-toggle][aria-expanded="true"], .kds-expand-toggle[aria-expanded="true"]'
+      );
+      toggles.forEach((toggle) => {
+        toggle.setAttribute("aria-expanded", "false");
+        const panelId = toggle.getAttribute("aria-controls");
+        const panel = panelId ? document.getElementById(panelId) : toggle.parentElement?.querySelector("[data-expand-panel], .kds-expand-panel");
+        panel?.classList.remove("open");
+      });
+    };
+    const apply = () => {
+      ticking = false;
+      const screen = document.querySelector(".kds-screen.active");
+      if (!screen) return;
+      const sticky = screen.querySelector(".kds-invoice-sticky");
+      if (!sticky || !isMobile()) {
+        screen.style.removeProperty("--collapse-progress");
+        screen.style.removeProperty("--collapse-collapsible-h");
+        sticky?.classList.remove("is-collapsed");
+        wasCollapsing = false;
+        return;
+      }
+      const scrollY = Math.max(window.scrollY || window.pageYOffset || 0, viewportOffset);
+      const progress = Math.min(Math.max(scrollY / collapseEnd, 0), 1);
+      if (!screen.style.getPropertyValue("--collapse-collapsible-h")) {
+        const collapsible = sticky.querySelector(".kds-invoice-collapsible");
+        if (collapsible) {
+          screen.style.setProperty("--collapse-collapsible-h", `${collapsible.offsetHeight}px`);
+        }
+      }
+      screen.style.setProperty("--collapse-progress", String(progress));
+      sticky.classList.toggle("is-collapsed", progress >= 1);
+      if (progress > 0) {
+        if (!wasCollapsing) {
+          wasCollapsing = true;
+          closeOpenPanels(sticky);
+          onCollapseStartRef.current?.();
+        }
+      } else {
+        wasCollapsing = false;
+      }
+    };
+    const onScroll = () => {
+      if (ticking) return;
+      ticking = true;
+      window.requestAnimationFrame(apply);
+    };
+    const onMessage = (event) => {
+      if (event.data && event.data.type === "VIEWPORT_OFFSET") {
+        viewportOffset = Math.max(0, event.data.offsetTop || 0);
+        onScroll();
+      }
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    window.addEventListener("message", onMessage);
+    apply();
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+      window.removeEventListener("message", onMessage);
+    };
+  }, [collapseEnd, mobileBreakpoint]);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   KdsAccordion,
@@ -2701,6 +2779,7 @@ KdsBillAttachments.displayName = "KdsBillAttachments";
   useAutoHide,
   useCopyToClipboard,
   useCountdown,
+  useStickyInvoiceCollapse,
   useTabsKeyboard,
   zIndex
 });

package/dist/index.mjs

@@ -2518,6 +2518,83 @@ var KdsBillAttachments = forwardRef41(
   ({ children, className, ...props }, ref) => /* @__PURE__ */ jsx43("div", { ref, className: clsx("kds-bill-attachments", className), ...props, children })
 );
 KdsBillAttachments.displayName = "KdsBillAttachments";
+
+// src/components/core/hooks/useStickyInvoiceCollapse.ts
+import { useEffect as useEffect4, useRef as useRef4 } from "react";
+function useStickyInvoiceCollapse(options = {}) {
+  const { onCollapseStart, collapseEnd = 20, mobileBreakpoint = 768 } = options;
+  const onCollapseStartRef = useRef4(onCollapseStart);
+  onCollapseStartRef.current = onCollapseStart;
+  useEffect4(() => {
+    let viewportOffset = 0;
+    let ticking = false;
+    let wasCollapsing = false;
+    const isMobile = () => window.innerWidth < mobileBreakpoint;
+    const closeOpenPanels = (sticky) => {
+      const toggles = sticky.querySelectorAll(
+        '[data-expand-toggle][aria-expanded="true"], .kds-expand-toggle[aria-expanded="true"]'
+      );
+      toggles.forEach((toggle) => {
+        toggle.setAttribute("aria-expanded", "false");
+        const panelId = toggle.getAttribute("aria-controls");
+        const panel = panelId ? document.getElementById(panelId) : toggle.parentElement?.querySelector("[data-expand-panel], .kds-expand-panel");
+        panel?.classList.remove("open");
+      });
+    };
+    const apply = () => {
+      ticking = false;
+      const screen = document.querySelector(".kds-screen.active");
+      if (!screen) return;
+      const sticky = screen.querySelector(".kds-invoice-sticky");
+      if (!sticky || !isMobile()) {
+        screen.style.removeProperty("--collapse-progress");
+        screen.style.removeProperty("--collapse-collapsible-h");
+        sticky?.classList.remove("is-collapsed");
+        wasCollapsing = false;
+        return;
+      }
+      const scrollY = Math.max(window.scrollY || window.pageYOffset || 0, viewportOffset);
+      const progress = Math.min(Math.max(scrollY / collapseEnd, 0), 1);
+      if (!screen.style.getPropertyValue("--collapse-collapsible-h")) {
+        const collapsible = sticky.querySelector(".kds-invoice-collapsible");
+        if (collapsible) {
+          screen.style.setProperty("--collapse-collapsible-h", `${collapsible.offsetHeight}px`);
+        }
+      }
+      screen.style.setProperty("--collapse-progress", String(progress));
+      sticky.classList.toggle("is-collapsed", progress >= 1);
+      if (progress > 0) {
+        if (!wasCollapsing) {
+          wasCollapsing = true;
+          closeOpenPanels(sticky);
+          onCollapseStartRef.current?.();
+        }
+      } else {
+        wasCollapsing = false;
+      }
+    };
+    const onScroll = () => {
+      if (ticking) return;
+      ticking = true;
+      window.requestAnimationFrame(apply);
+    };
+    const onMessage = (event) => {
+      if (event.data && event.data.type === "VIEWPORT_OFFSET") {
+        viewportOffset = Math.max(0, event.data.offsetTop || 0);
+        onScroll();
+      }
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    window.addEventListener("message", onMessage);
+    apply();
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+      window.removeEventListener("message", onMessage);
+    };
+  }, [collapseEnd, mobileBreakpoint]);
+}
 export {
   KdsAccordion,
   KdsAccordionDetails,
@@ -2591,6 +2668,7 @@ export {
   useAutoHide,
   useCopyToClipboard,
   useCountdown,
+  useStickyInvoiceCollapse,
   useTabsKeyboard,
   zIndex
 };

package/package.json

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