npm - @appforgeapps/uiforge - Versions diffs - 0.5.0 → 0.5.3 - Mend

@appforgeapps/uiforge 0.5.0 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -1,6 +1,7 @@
 import { default as default_2 } from 'react';
 import { FC } from 'react';
 import { JSX } from 'react/jsx-runtime';
+import { RefObject } from 'react';
 /**
  * Represents a single activity/event in the stream
@@ -62,6 +63,67 @@ export declare const ActivityIcons: {
     deploy: FC<IconProps>;
 };
+/**
+ * Context for passing density and showMeta settings from ActivityStream to ActivityItem
+ */
+export declare interface ActivityItemContextValue {
+    /**
+     * Density mode for the item
+     */
+    density: ActivityStreamDensity;
+    /**
+     * Whether to show metadata (timestamps, descriptions, etc.)
+     */
+    showMeta: boolean;
+}
+/**
+ * Represents a single activity/event item
+ */
+export declare interface ActivityItemEvent {
+    /**
+     * Unique identifier for the event
+     */
+    id: string | number;
+    /**
+     * Type/category of the event (e.g., 'commit', 'issue', 'pr', 'comment')
+     */
+    type: string;
+    /**
+     * Display title for the event
+     */
+    title: string;
+    /**
+     * Optional description or content
+     */
+    description?: string;
+    /**
+     * Timestamp of the event
+     */
+    timestamp: Date | string;
+    /**
+     * Icon to display (can be emoji, React node, or icon class)
+     */
+    icon?: default_2.ReactNode;
+    /**
+     * Optional metadata for the event (e.g., repository name, user, etc.)
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Provider component for ActivityItem context
+ */
+export declare const ActivityItemProvider: default_2.FC<{
+    children: default_2.ReactNode;
+    value: ActivityItemContextValue;
+}>;
+/**
+ * Density options for the activity stream
+ */
+export declare type ActivityStreamDensity = 'comfortable' | 'compact' | 'condensed';
 /**
  * Pagination configuration for loading more events
  */
@@ -109,10 +171,20 @@ export declare const BusinessIcons: {
 };
 /**
- * A customizable button component
+ * A customizable button component with accessibility-focused touch targets
+ *
+ * By default, buttons have a minimum 44×44px touch target for accessibility.
+ * Use density='condensed' to allow smaller targets in dense UIs.
  */
 export declare const Button: default_2.FC<ButtonProps>;
+/**
+ * Density options for button sizing
+ * - 'default': Standard 44px minimum touch target for accessibility
+ * - 'condensed': Smaller touch target for dense UIs (not recommended for touch devices)
+ */
+export declare type ButtonDensity = 'default' | 'condensed';
 export declare interface ButtonProps extends default_2.ButtonHTMLAttributes<HTMLButtonElement> {
     /**
      * Variant style of the button
@@ -122,6 +194,17 @@ export declare interface ButtonProps extends default_2.ButtonHTMLAttributes<HTML
      * Size of the button
      */
     size?: 'small' | 'medium' | 'large';
+    /**
+     * Theme variant ('light' or 'dark')
+     */
+    theme?: 'light' | 'dark';
+    /**
+     * Density of the button - affects minimum touch target size
+     * - 'default': Enforces 44px minimum touch target (recommended for accessibility)
+     * - 'condensed': Allows smaller touch targets for dense UIs
+     * @default 'default'
+     */
+    density?: ButtonDensity;
     /**
      * Button contents
      */
@@ -364,8 +447,111 @@ export declare interface GridPaginationConfig {
     serverSide?: boolean;
 }
+/**
+ * HamburgerButton - An accessible hamburger menu button for drawer/menu controls
+ *
+ * Features:
+ * - Proper ARIA attributes (aria-expanded, aria-controls)
+ * - Animated hamburger-to-X transformation
+ * - 44x44px minimum touch target by default
+ * - Keyboard accessible
+ */
+export declare const HamburgerButton: default_2.FC<HamburgerButtonProps>;
+/**
+ * Props for the HamburgerButton component
+ */
+export declare interface HamburgerButtonProps extends Omit<default_2.ButtonHTMLAttributes<HTMLButtonElement>, 'aria-expanded' | 'aria-controls'> {
+    /**
+     * Whether the controlled menu/drawer is open
+     */
+    isOpen: boolean;
+    /**
+     * ID of the element this button controls (for aria-controls)
+     */
+    controlsId: string;
+    /**
+     * Accessible label for the button
+     */
+    ariaLabel?: string;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+    /**
+     * Size variant of the button
+     * @default 'medium'
+     */
+    size?: 'small' | 'medium' | 'large';
+}
 export declare const HeartRateIcon: default_2.FC<IconProps>;
+/**
+ * IconButton - An accessible icon-only button with touch-friendly targets
+ *
+ * Features:
+ * - 44x44px minimum touch target for all sizes (WCAG 2.1 compliant)
+ * - Keyboard accessible (Enter/Space triggers click)
+ * - Visible focus styles
+ * - Optional badge support for notifications
+ * - Dark mode support
+ * - Reduced motion support
+ *
+ * @example
+ * ```tsx
+ * import { IconButton, CloseIcon } from '@appforgeapps/uiforge'
+ *
+ * <IconButton
+ *   icon={<CloseIcon />}
+ *   ariaLabel="Close dialog"
+ *   onClick={handleClose}
+ * />
+ * ```
+ *
+ * @example With badge
+ * ```tsx
+ * <IconButton
+ *   icon={<NotificationIcon />}
+ *   ariaLabel="Notifications"
+ *   badge={5}
+ *   onClick={handleNotifications}
+ * />
+ * ```
+ */
+export declare const IconButton: default_2.FC<IconButtonProps>;
+/**
+ * Props for the IconButton component
+ */
+export declare interface IconButtonProps extends Omit<default_2.ButtonHTMLAttributes<HTMLButtonElement>, 'aria-label'> {
+    /**
+     * The icon element to display. Should be an SVG icon or icon component.
+     */
+    icon: default_2.ReactNode;
+    /**
+     * Size variant of the button.
+     * All sizes maintain a minimum 44x44px touch target for accessibility.
+     * @default 'medium'
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Accessible label for the button.
+     * Required for icon-only buttons to ensure screen reader accessibility.
+     * @important Always provide a descriptive label for icon-only buttons.
+     */
+    ariaLabel: string;
+    /**
+     * Optional badge content to display (e.g., notification count).
+     * Can be a string or number. Will be visually displayed as a small badge on the button.
+     */
+    badge?: string | number;
+    /**
+     * Additional CSS class names for styling overrides.
+     */
+    className?: string;
+}
 /**
  * UIForge Icon Library
  * A collection of monochrome SVG icons for use across UIForge components
@@ -391,6 +577,206 @@ export declare const MeetingIcon: default_2.FC<IconProps>;
 export declare const MergeIcon: default_2.FC<IconProps>;
+/**
+ * MobileHeaderLayout - A 3-slot mobile header layout primitive
+ *
+ * This component provides a standardized mobile header with left, center, and right slots.
+ * It uses SafeAreaContainer internally to respect device safe areas (iOS notch, status bar).
+ *
+ * Features:
+ * - 3-slot layout: left / center (title) / right
+ * - Safe area handling via SafeAreaContainer
+ * - Left and right slots have fixed min-width (≥44px) for touch targets
+ * - Center slot is flexible with text-overflow: ellipsis for long titles
+ * - Optional hide-on-desktop behavior (configurable via CSS variable)
+ * - CSS variables for height (default 56px) and padding
+ * - Dark mode support
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { MobileHeaderLayout, IconButton, ArrowLeftIcon } from '@appforgeapps/uiforge'
+ *
+ * <MobileHeaderLayout
+ *   left={<IconButton icon={<ArrowLeftIcon />} ariaLabel="Go back" onClick={handleBack} />}
+ *   title="Page Title"
+ *   right={<IconButton icon={<MenuIcon />} ariaLabel="Menu" onClick={handleMenu} />}
+ * />
+ * ```
+ *
+ * @example With React node as title
+ * ```tsx
+ * <MobileHeaderLayout
+ *   left={<BackButton />}
+ *   title={<Logo />}
+ *   hideOnDesktop
+ * />
+ * ```
+ *
+ * @example Long title with ellipsis
+ * ```tsx
+ * <MobileHeaderLayout
+ *   title="This is a very long title that will be truncated with ellipsis"
+ *   right={<OverflowMenuButton />}
+ * />
+ * ```
+ */
+export declare const MobileHeaderLayout: default_2.FC<MobileHeaderLayoutProps>;
+/**
+ * Props for the MobileHeaderLayout component
+ */
+export declare interface MobileHeaderLayoutProps extends Omit<default_2.HTMLAttributes<HTMLDivElement>, 'title'> {
+    /**
+     * Content to render in the left slot (typically a back button or hamburger menu).
+     * Slot has a fixed min-width of 44px for touch target consistency.
+     */
+    left?: default_2.ReactNode;
+    /**
+     * Content to render in the center slot.
+     * Can be a string (which will be rendered with ellipsis on overflow) or a React node.
+     */
+    title?: default_2.ReactNode;
+    /**
+     * Content to render in the right slot (typically action buttons or overflow menu).
+     * Slot has a fixed min-width of 44px for touch target consistency.
+     */
+    right?: default_2.ReactNode;
+    /**
+     * When true, the header is hidden at desktop breakpoints (min-width: 600px by default).
+     * Override the breakpoint in your own CSS by targeting .uiforge-mobile-header-layout--hide-on-desktop.
+     * @default false
+     */
+    hideOnDesktop?: boolean;
+    /**
+     * Additional CSS class names for styling overrides.
+     */
+    className?: string;
+}
+/**
+ * OverflowMenu - An accessible popover menu for secondary actions
+ *
+ * Features:
+ * - Keyboard accessible (Arrow keys, Enter, Escape)
+ * - ARIA attributes for screen readers
+ * - Click outside to close
+ * - Focus management (returns focus to trigger on close)
+ * - Optional custom trigger element
+ * - Menu item icons and disabled states
+ * - Dark mode support
+ * - Reduced motion support
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { OverflowMenu } from '@appforgeapps/uiforge'
+ *
+ * <OverflowMenu
+ *   items={[
+ *     { id: 'edit', label: 'Edit' },
+ *     { id: 'delete', label: 'Delete' },
+ *   ]}
+ *   onSelect={(item) => console.log('Selected:', item.id)}
+ * />
+ * ```
+ *
+ * @example With icons and disabled items
+ * ```tsx
+ * <OverflowMenu
+ *   items={[
+ *     { id: 'edit', label: 'Edit', icon: <EditIcon /> },
+ *     { id: 'archive', label: 'Archive', icon: <ArchiveIcon />, disabled: true },
+ *     { id: 'delete', label: 'Delete', icon: <DeleteIcon /> },
+ *   ]}
+ *   ariaLabel="Post actions"
+ *   onSelect={handleAction}
+ * />
+ * ```
+ *
+ * @example With custom trigger
+ * ```tsx
+ * <OverflowMenu
+ *   trigger={<IconButton icon={<MoreIcon />} ariaLabel="More options" />}
+ *   items={menuItems}
+ *   onSelect={handleSelect}
+ * />
+ * ```
+ */
+export declare const OverflowMenu: default_2.FC<OverflowMenuProps>;
+/**
+ * Represents a single item in the overflow menu
+ */
+export declare interface OverflowMenuItem {
+    /**
+     * Unique identifier for this menu item
+     */
+    id: string;
+    /**
+     * Display label for this menu item
+     */
+    label: string;
+    /**
+     * Optional icon to display (can be a React node like an SVG icon)
+     */
+    icon?: default_2.ReactNode;
+    /**
+     * Whether this menu item is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Optional callback when this item is clicked.
+     * If not provided, the parent onSelect callback will be used.
+     */
+    onClick?: () => void;
+}
+/**
+ * Props for the OverflowMenu component
+ */
+export declare interface OverflowMenuProps {
+    /**
+     * Array of menu items to display
+     */
+    items: OverflowMenuItem[];
+    /**
+     * Callback when a menu item is selected
+     */
+    onSelect?: (item: OverflowMenuItem) => void;
+    /**
+     * Accessible label for the trigger button
+     * @default 'More actions'
+     */
+    ariaLabel?: string;
+    /**
+     * Custom trigger element. If not provided, a default "..." button is rendered.
+     */
+    trigger?: default_2.ReactNode;
+    /**
+     * Alignment of the menu relative to the trigger button
+     * @default 'right'
+     */
+    align?: 'left' | 'right';
+    /**
+     * Whether the menu is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Size variant of the trigger button (when using default trigger)
+     * @default 'medium'
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Additional CSS class names for styling overrides
+     */
+    className?: string;
+    /**
+     * Test ID for the component
+     */
+    'data-testid'?: string;
+}
 export declare const PlanetIcon: default_2.FC<IconProps>;
 /**
@@ -410,10 +796,89 @@ export declare const RocketIcon: default_2.FC<IconProps>;
 export declare const RunningIcon: default_2.FC<IconProps>;
+/**
+ * SafeAreaContainer - A container component that applies device safe area insets as padding.
+ *
+ * This component wraps content and automatically applies `env(safe-area-inset-*)` CSS values
+ * as padding to respect device safe areas such as iOS notches, status bars, and home indicators.
+ *
+ * Features:
+ * - Automatically applies safe area insets on all supported devices (iOS, Android)
+ * - Falls back gracefully to 0px on browsers that don't support `env()` function
+ * - Allows selective disabling of individual insets via props
+ * - Minimal CSS footprint with no JavaScript dependencies
+ * - Dark mode compatible
+ *
+ * @example Basic usage for a mobile header
+ * ```tsx
+ * import { SafeAreaContainer } from '@appforgeapps/uiforge'
+ *
+ * <SafeAreaContainer disableBottom>
+ *   <header>My App Header</header>
+ * </SafeAreaContainer>
+ * ```
+ *
+ * @example Full-screen container with all safe areas
+ * ```tsx
+ * <SafeAreaContainer className="my-app-layout">
+ *   <main>Content here is protected from notches and home indicators</main>
+ * </SafeAreaContainer>
+ * ```
+ *
+ * @example Header with only top inset
+ * ```tsx
+ * <SafeAreaContainer disableBottom disableLeft disableRight>
+ *   <nav>Navigation bar</nav>
+ * </SafeAreaContainer>
+ * ```
+ */
+export declare const SafeAreaContainer: default_2.FC<SafeAreaContainerProps>;
+/**
+ * Props for the SafeAreaContainer component
+ */
+export declare interface SafeAreaContainerProps extends default_2.HTMLAttributes<HTMLDivElement> {
+    /**
+     * The content to be wrapped with safe area insets.
+     */
+    children: default_2.ReactNode;
+    /**
+     * Disable the top safe area inset padding.
+     * Useful when a parent element already handles the top inset.
+     * @default false
+     */
+    disableTop?: boolean;
+    /**
+     * Disable the bottom safe area inset padding.
+     * Useful when you only need top inset for headers.
+     * @default false
+     */
+    disableBottom?: boolean;
+    /**
+     * Disable the left safe area inset padding.
+     * @default false
+     */
+    disableLeft?: boolean;
+    /**
+     * Disable the right safe area inset padding.
+     * @default false
+     */
+    disableRight?: boolean;
+    /**
+     * Additional CSS class names for styling overrides.
+     */
+    className?: string;
+}
 export declare const SatelliteIcon: default_2.FC<IconProps>;
 export declare const ServerIcon: default_2.FC<IconProps>;
+/**
+ * Sidebar variant types
+ */
+export declare type SidebarVariant = 'static' | 'drawer' | 'bottom';
 export declare const SpaceIcons: {
     rocket: FC<IconProps>;
     satellite: FC<IconProps>;
@@ -453,6 +918,59 @@ export declare interface TextFormat {
     code?: boolean;
 }
+/**
+ * A standalone activity item component that can be used independently or within ActivityStream.
+ * Supports compact/mobile layouts through density prop and showMeta flag.
+ */
+export declare const UIForgeActivityItem: default_2.FC<UIForgeActivityItemProps>;
+/**
+ * Props for the UIForgeActivityItem component
+ */
+export declare interface UIForgeActivityItemProps {
+    /**
+     * The activity event data to display
+     */
+    event: ActivityItemEvent;
+    /**
+     * Whether the item is expanded (shows description)
+     */
+    expanded?: boolean;
+    /**
+     * Callback when the item is toggled
+     */
+    onToggle?: (eventId: string | number, expanded: boolean) => void;
+    /**
+     * Whether the item is expandable (has description or is expandable)
+     */
+    expandable?: boolean;
+    /**
+     * Whether this is a child item (nested styling)
+     */
+    isChild?: boolean;
+    /**
+     * Whether to show the timeline marker
+     */
+    showTimeline?: boolean;
+    /**
+     * Density mode for the item. If not provided, uses context value or 'comfortable'
+     */
+    density?: ActivityStreamDensity;
+    /**
+     * Whether to show metadata (timestamps, descriptions). If not provided, uses context value.
+     * When false, hides timestamps and truncates long content.
+     */
+    showMeta?: boolean;
+    /**
+     * Custom icon renderer
+     */
+    renderIcon?: (event: ActivityItemEvent) => default_2.ReactNode;
+    /**
+     * Custom className for styling
+     */
+    className?: string;
+}
 /**
  * A GitHub-inspired activity stream component with smart grouping, timeline, and theming
  */
@@ -474,6 +992,10 @@ export declare interface UIForgeActivityStreamProps {
      * Custom className for styling
      */
     className?: string;
+    /**
+     * Custom inline styles
+     */
+    style?: default_2.CSSProperties;
     /**
      * Whether to show the "Show more" bar
      */
@@ -529,8 +1051,42 @@ export declare interface UIForgeActivityStreamProps {
     /**
      * Global scale factor (density) for spacing and icon sizes in the stream.
      * Set to values like 0.8 for compact, 1 for default, 1.2 for spacious.
+     * @deprecated Use `density` prop instead for semantic density control.
      */
     scale?: number;
+    /**
+     * Density mode for the activity stream.
+     * - 'comfortable': Default spacing and sizing (default)
+     * - 'compact': Reduced spacing and smaller icons
+     * - 'condensed': Minimal spacing for maximum information density
+     */
+    density?: ActivityStreamDensity;
+    /**
+     * Whether to enable responsive density switching based on container width.
+     * When true, the component will automatically switch to 'compact' density
+     * when the container width is below the breakpoint.
+     * @default true
+     */
+    responsive?: boolean;
+    /**
+     * Breakpoint width in pixels below which responsive mode switches to compact.
+     * Only applies when `responsive` is true.
+     * @default 640
+     */
+    compactBreakpointPx?: number;
+    /**
+     * Optional ref to the container element for responsive measurements.
+     * If not provided, an internal ref is used.
+     */
+    containerRef?: RefObject<HTMLElement | null>;
+    /**
+     * Whether to show metadata (timestamps, descriptions, etc.) on activity items.
+     * When false, hides timestamps and truncates long content for a denser display.
+     * When undefined, metadata is shown by default but may be auto-hidden on narrow containers
+     * if responsive is true.
+     * @default true
+     */
+    showMeta?: boolean;
     /**
      * Custom icon renderer
      */
@@ -539,6 +1095,19 @@ export declare interface UIForgeActivityStreamProps {
      * Custom event renderer
      */
     renderEvent?: (event: ActivityEvent) => default_2.ReactNode;
+    /**
+     * Whether to enable virtualization for improved performance with large lists.
+     * When enabled, uses react-window to render only visible items.
+     * Note: Virtualization may affect animations and dynamic height measurements.
+     * @default false
+     */
+    virtualization?: boolean;
+    /**
+     * Height of each item in pixels when virtualization is enabled.
+     * Required for react-window's fixed-size list.
+     * @default 48
+     */
+    virtualItemHeight?: number;
 }
 /**
@@ -587,6 +1156,10 @@ export declare interface UIForgeBlocksEditorProps {
      * Whether the editor is read-only
      */
     readOnly?: boolean;
+    /**
+     * Theme variant ('light' or 'dark')
+     */
+    theme?: 'light' | 'dark';
     /**
      * Custom CSS class name
      */
@@ -631,6 +1204,10 @@ export declare interface UIForgeComboBoxProps {
      * Async callback for dynamic suggestions (receives search text)
      */
     onSearch?: (searchText: string, signal?: AbortSignal) => Promise<ComboBoxOption[]>;
+    /**
+     * Theme variant ('light' or 'dark')
+     */
+    theme?: 'light' | 'dark';
     /**
      * Placeholder text
      */
@@ -704,7 +1281,7 @@ export declare interface UIForgeComboBoxProps {
 /**
  * UIForgeGrid - A feature-rich data grid component
  */
-export declare const UIForgeGrid: <T extends Record<string, unknown>>({ columns, data, selectable, selectedRows: controlledSelectedRows, getRowKey, onSelectionChange, onCellEdit, actionButtons, searchable, searchPlaceholder, onSearch, customFilter, pagination, onPageChange, onPageSizeChange, pageSizeOptions, className, loading, emptyMessage, }: UIForgeGridProps<T>) => JSX.Element;
+export declare const UIForgeGrid: <T extends Record<string, unknown>>({ columns, data, theme, selectable, selectedRows: controlledSelectedRows, getRowKey, onSelectionChange, onCellEdit, actionButtons, searchable, searchPlaceholder, onSearch, customFilter, pagination, onPageChange, onPageSizeChange, pageSizeOptions, className, loading, emptyMessage, }: UIForgeGridProps<T>) => JSX.Element;
 /**
  * Props for the UIForgeGrid component
@@ -718,6 +1295,10 @@ export declare interface UIForgeGridProps<T = Record<string, unknown>> {
      * Data to display in the grid
      */
     data: T[];
+    /**
+     * Theme variant ('light' or 'dark')
+     */
+    theme?: 'light' | 'dark';
     /**
      * Enable row selection
      */
@@ -788,6 +1369,85 @@ export declare interface UIForgeGridProps<T = Record<string, unknown>> {
     emptyMessage?: string;
 }
+/**
+ * UIForgeSidebar - A reusable sidebar component with multiple variants
+ *
+ * Features:
+ * - Static variant for desktop fixed sidebars
+ * - Drawer variant for slide-in panels with accessibility support
+ * - Bottom variant for mobile bottom navigation
+ * - Focus trapping for drawer/bottom variants
+ * - ESC and backdrop click to close
+ * - CSS safe-area insets support
+ */
+export declare const UIForgeSidebar: default_2.FC<UIForgeSidebarProps>;
+/**
+ * Props for the UIForgeSidebar component
+ */
+export declare interface UIForgeSidebarProps {
+    /**
+     * Unique identifier for the sidebar element
+     * Useful for linking with aria-controls on trigger buttons
+     */
+    id?: string;
+    /**
+     * Variant style of the sidebar
+     * - 'static': Desktop fixed sidebar (default)
+     * - 'drawer': Slide-in panel for mobile & small containers
+     * - 'bottom': Bottom navigation variant for mobile
+     */
+    variant?: SidebarVariant;
+    /**
+     * Whether the sidebar is open (only applies to 'drawer' and 'bottom' variants)
+     */
+    open?: boolean;
+    /**
+     * Callback when open state changes (only applies to 'drawer' and 'bottom' variants)
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Content to display inside the sidebar
+     */
+    children: default_2.ReactNode;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+    /**
+     * ARIA label for the sidebar
+     */
+    ariaLabel?: string;
+    /**
+     * Width of the sidebar (CSS value, applies to 'static' and 'drawer' variants)
+     */
+    width?: string;
+    /**
+     * Height of the sidebar (CSS value, applies to 'bottom' variant only)
+     */
+    height?: string;
+    /**
+     * Position of the sidebar for 'static' and 'drawer' variants
+     */
+    position?: 'left' | 'right';
+    /**
+     * Whether to show the backdrop overlay (only applies to 'drawer' and 'bottom' variants)
+     */
+    showBackdrop?: boolean;
+    /**
+     * Whether to close on backdrop click (only applies when showBackdrop is true)
+     */
+    closeOnBackdropClick?: boolean;
+    /**
+     * Whether to close on ESC key press (only applies to 'drawer' and 'bottom' variants)
+     */
+    closeOnEscape?: boolean;
+    /**
+     * Whether to trap focus within the sidebar (only applies to 'drawer' and 'bottom' variants)
+     */
+    trapFocus?: boolean;
+}
 /**
  * UIForgeVideo - A universal video component that supports 30+ video platforms
  *
@@ -952,6 +1612,21 @@ export declare interface UIForgeVideoProps {
      * Height of the video player
      */
     height?: string | number;
+    /**
+     * Maximum height of the video player
+     */
+    maxHeight?: string | number;
+    /**
+     * Enable responsive behavior (aspect-video, full width, no min-height constraints)
+     * When true, uses aspect-ratio layout that scales correctly on small screens
+     * @default false
+     */
+    responsive?: boolean;
+    /**
+     * Hide the header (title and description) for tight mobile UIs
+     * @default false
+     */
+    hideHeader?: boolean;
     /**
      * Custom overlay icon (defaults to play icon)
      */
@@ -976,6 +1651,94 @@ export declare const UIIcons: {
 export declare const UnfoldIcon: default_2.FC<IconProps>;
+/**
+ * Hook to access the ActivityItem context
+ */
+export declare function useActivityItemContext(): ActivityItemContextValue;
+/**
+ * A hook that dynamically calculates the optimal page size for paginated lists
+ * based on the container's available height and item measurements.
+ *
+ * Uses ResizeObserver to respond to container size changes and MutationObserver
+ * to detect when new items are added to the container.
+ *
+ * @param containerRef - A ref to the scrollable container element
+ * @param options - Configuration options for the hook
+ * @returns The calculated page size, clamped to [min, max]
+ *
+ * @example
+ * ```tsx
+ * function PaginatedList() {
+ *   const containerRef = useRef<HTMLDivElement>(null)
+ *   const pageSize = useDynamicPageCount(containerRef, {
+ *     sampleCount: 3,
+ *     min: 5,
+ *     max: 20,
+ *     approxItemHeight: 100,
+ *   })
+ *
+ *   return (
+ *     <div ref={containerRef} style={{ height: '600px', overflow: 'auto' }}>
+ *       {items.slice(0, pageSize).map(item => <ListItem key={item.id} {...item} />)}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useDynamicPageCount(containerRef: RefObject<HTMLElement | null> | null, options?: UseDynamicPageCountOptions): number;
+/**
+ * Options for the useDynamicPageCount hook
+ */
+export declare interface UseDynamicPageCountOptions {
+    /**
+     * Number of sample items to measure for calculating average item height.
+     * @default 3
+     */
+    sampleCount?: number;
+    /**
+     * Minimum page size to return.
+     * @default 3
+     */
+    min?: number;
+    /**
+     * Maximum page size to return.
+     * @default 15
+     */
+    max?: number;
+    /**
+     * Approximate item height in pixels used as fallback when items cannot be measured.
+     * @default 120
+     */
+    approxItemHeight?: number;
+}
+/**
+ * A hook that determines whether a container element is "compact" by measuring its width.
+ * Uses ResizeObserver to respond to container size changes.
+ *
+ * @param containerRef - A ref to the HTML element to observe, or null
+ * @param breakpointPx - The width threshold in pixels (default: 640). Returns true when width < breakpointPx
+ * @returns true when the container width is less than breakpointPx, false otherwise.
+ *          Returns false when the container width is 0 (not rendered/measured yet).
+ *
+ * @example
+ * ```tsx
+ * function ResponsiveComponent() {
+ *   const containerRef = useRef<HTMLDivElement>(null)
+ *   const isCompact = useResponsive(containerRef, 640)
+ *
+ *   return (
+ *     <div ref={containerRef}>
+ *       {isCompact ? <MobileLayout /> : <DesktopLayout />}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useResponsive(containerRef: RefObject<HTMLElement | null> | null, breakpointPx?: number): boolean;
 /**
  * Result of video ID extraction from a URL
  */