@aragon/gov-ui-kit 1.20.0 → 1.22.0

package/dist/types/src/core/components/cards/cardCollapsible/cardCollapsible.d.ts

@@ -1,8 +1,14 @@
 import { type ICollapsibleProps } from '../../collapsible';
-export interface ICardCollapsibleProps extends Omit<ICollapsibleProps, 'buttonVariant' | 'className'> {
+export interface ICardCollapsibleProps extends Omit<ICollapsibleProps, 'buttonVariant' | 'className' | 'showOverlay' | 'collapsedLines'> {
     /**
      * Additional class names to apply to the card.
      */
     className?: string;
+    /**
+     * The collapsed height in pixels. CardCollapsible always uses overlay mode (showOverlay=true),
+     * which requires pixel-based height measurement instead of line-based counting.
+     * @default 180
+     */
+    collapsedPixels?: number;
 }
 export declare const CardCollapsible: React.FC<ICardCollapsibleProps>;

package/dist/types/src/core/components/collapsible/collapsible.api.d.ts

@@ -9,6 +9,13 @@ export interface ICollapsibleProps extends Omit<ComponentProps<'div'>, 'onToggle
      * Exact pixel height for the collapsible container that will override collapsedLines prop if defined.
      */
     collapsedPixels?: number;
+    /**
+     * Number of text lines used for the gradient overlay height when collapsed.
+     * Has effect only when `showOverlay` is true and the content is collapsed.
+     * Overlay height will be clamped to at most (collapsedLines - 1).
+     * @default 2
+     */
+    overlayLines?: number;
     /**
      * Controlled state of the collapsible container.
      * @default false

package/dist/types/src/core/components/collapsible/collapsible.d.ts

@@ -1,2 +1,18 @@
 import { type ICollapsibleProps } from './collapsible.api';
+/**
+ * Collapsible component that can wrap any content and visually collapse it for space-saving purposes.
+ *
+ * @param props - The component props
+ * @param props.collapsedLines - Number of text lines to show while collapsed (default: 3)
+ * @param props.collapsedPixels - Exact pixel height for the collapsible container that will override collapsedLines prop if defined
+ * @param props.overlayLines - Number of text lines used for the gradient overlay height when collapsed (default: 2)
+ * @param props.isOpen - Controlled state of the collapsible container (default: false)
+ * @param props.defaultOpen - Default state of the collapsible container (default: false)
+ * @param props.buttonLabelClosed - The label to display on the trigger button when the collapsible container is closed
+ * @param props.buttonLabelOpened - The label to display on the trigger button when the collapsible container is open
+ * @param props.showOverlay - Show overlay when the collapsible container is open (default: false)
+ * @param props.onToggle - Callback function that is called when the collapsible container is toggled
+ * @param props.children - The content to be collapsible
+ * @returns The rendered Collapsible component
+ */
 export declare const Collapsible: React.FC<ICollapsibleProps>;

package/dist/types/src/core/components/collapsible/collapsibleUtils.d.ts

@@ -0,0 +1,95 @@
+export declare const collapsibleDefaultLineHeight = 24;
+/**
+ * Computes the line height of an element with intelligent fallback strategy.
+ *
+ * The function uses a multi-level approach to find the most accurate line-height:
+ * 1. First, tries to get line-height from the first <p> child element
+ *    - This is important because content often consists of paragraphs with specific typography styles
+ *    - For example, `.prose p` classes in Tailwind Typography apply custom line-heights to paragraphs
+ *    - Taking line-height from the first paragraph ensures accurate height calculations when content
+ *      has different typography than the container
+ *
+ * 2. If no paragraph is found, falls back to the container element itself
+ *    - This handles cases where content doesn't use paragraph tags (images, custom components, etc.)
+ *
+ * 3. If line-height cannot be computed (SSR, null element, or invalid value), uses the fallback
+ *    - Ensures the component works gracefully in all environments
+ *
+ * @param element - The container element to compute the line height from
+ * @param fallback - The fallback line height to use if computation fails (default: 24px)
+ * @returns The computed line height in pixels
+ */
+export declare const computeElementLineHeight: (element: HTMLElement | null, fallback?: number) => number;
+/**
+ * Calculates the collapsed height of an element.
+ * @param collapsedLines - The number of lines to show while collapsed.
+ * @param lineHeight - The line height of the element.
+ * @param collapsedPixels - The collapsed pixels of the element.
+ * @returns The collapsed height of the element.
+ */
+export declare const calculateCollapsedHeight: (collapsedLines: number, lineHeight: number, collapsedPixels?: number) => number;
+/**
+ * Computes the whether an element is overflowing.
+ * @param fullHeight - The full height of the element.
+ * @param collapsedHeight - The collapsed height of the element.
+ * @param epsilon - The epsilon to use for the overflow.
+ * @returns The whether an element is overflowing.
+ */
+export declare const computeContentOverflow: (fullHeight: number, collapsedHeight: number, epsilon?: number) => boolean;
+export interface OverlayHeightParams {
+    showOverlay: boolean;
+    isOpen: boolean;
+    collapsedLines: number;
+    overlayLines: number;
+    lineHeight: number;
+    collapsedHeight: number;
+    fallbackLineHeight?: number;
+}
+export declare const computeOverlayHeightPx: (params: OverlayHeightParams) => number;
+/**
+ * Result of element height measurements for collapsible calculations.
+ */
+export interface MeasureHeightsResult {
+    /**
+     * The current rendered height of the element in the DOM (with clamp/max-height applied).
+     */
+    clampedClientHeight: number;
+    /**
+     * The full content height with no clamping and no max-height applied.
+     */
+    fullHeight: number;
+}
+/**
+ * Measures the current (clamped) clientHeight and the full content height by
+ * creating a hidden clone without clamping and without max-height.
+ *
+ * This allows overflow detection and overlay sizing for mixed-content
+ * rich text (e.g. combinations of h1, ul/li, p, code) where a single
+ * line-height is not representative.
+ */
+export declare const measureElementHeights: (element: HTMLElement | null) => MeasureHeightsResult;
+export interface OverlayRatioParams {
+    /** Number of lines visible when collapsed (requested). */
+    collapsedLines: number;
+    /** Number of lines used for overlay sizing (requested). */
+    overlayLines: number;
+    /** Actual rendered height of the collapsed block (in pixels). */
+    clampedClientHeight: number;
+    /** Minimum visible pixels of content above overlay to avoid full cover. */
+    minVisiblePx?: number;
+    /** Minimum overlay thickness in pixels (after clamping). */
+    minOverlayPx?: number;
+    /** Maximum overlay thickness in pixels (after clamping). */
+    maxOverlayPx?: number;
+}
+/**
+ * Computes overlay height as a ratio of the actual visible collapsed height
+ * instead of relying on a single line-height. This makes the overlay robust
+ * for mixed content where each line may have different heights.
+ *
+ * Constraints:
+ * - overlayLines is clamped to [0, collapsedLines - 1]
+ * - overlay cannot cover all visible content; we keep at least `minVisiblePx`
+ * - final result is clamped within [minOverlayPx, maxOverlayPx]
+ */
+export declare const computeOverlayHeightByRatio: (params: OverlayRatioParams) => number;

package/dist/types/src/core/components/dataList/dataListItem/dataListItem.d.ts

@@ -1,3 +1,7 @@
-import { type AnchorHTMLAttributes, type ButtonHTMLAttributes, type HTMLAttributes } from 'react';
-export type IDataListItemProps = ButtonHTMLAttributes<HTMLButtonElement> | AnchorHTMLAttributes<HTMLAnchorElement> | HTMLAttributes<HTMLDivElement>;
+import { type AnchorHTMLAttributes, type HTMLAttributes } from 'react';
+type DivPropsWithCustomClick = Omit<HTMLAttributes<HTMLDivElement>, 'onClick'> & {
+    onClick?: () => void;
+};
+export type IDataListItemProps = AnchorHTMLAttributes<HTMLAnchorElement> | DivPropsWithCustomClick;
 export declare const DataListItem: React.FC<IDataListItemProps>;
+export {};

package/dist/types/src/core/components/dialogs/dialog/dialogContent/dialogContent.d.ts

@@ -3,6 +3,7 @@ import { type ComponentPropsWithoutRef } from 'react';
 export interface IDialogContentProps extends ComponentPropsWithoutRef<'div'> {
     /**
      * Optional description of the dialog.
+     * Considering using the same prop on `DialogContentHeader` for sticky effect.
      */
     description?: string;
     /**

package/dist/types/src/core/components/dialogs/dialog/dialogHeader/dialogHeader.d.ts

@@ -4,6 +4,11 @@ export interface IDialogHeaderProps extends ComponentPropsWithoutRef<'div'> {
      * Title of the dialog displayed on the header and used as the dialog's accessible name.
      */
     title: string;
+    /**
+     * Optional description of the dialog. When set here, the description stays sticky with the header
+     * and remains visible while scrolling through long content.
+     */
+    description?: string;
     /**
      * Callback triggered on close button click. The close button is not displayed when the property is not set.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon/gov-ui-kit",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Implementation of the Aragon's Governance UI Kit",
   "main": "dist/index.es.js",
   "types": "dist/types/src/index.d.ts",