@appforgeapps/uiforge 0.1.0 → 0.5.2

package/dist/index.d.ts

@@ -1,5 +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
@@ -43,18 +45,85 @@ export declare interface ActivityEvent {
     children?: ActivityEvent[];
 }
 
+/**
+ * Icon Maps - Icon lookup tables for easy access to icon components
+ *
+ * These maps are in a separate file to avoid React Fast Refresh issues
+ * when exporting both components and constants from the same file.
+ */
 export declare const ActivityIcons: {
-    commit: default_2.FC<IconProps>;
-    pr: default_2.FC<IconProps>;
-    issue: default_2.FC<IconProps>;
-    comment: default_2.FC<IconProps>;
-    star: default_2.FC<IconProps>;
-    fork: default_2.FC<IconProps>;
-    merge: default_2.FC<IconProps>;
-    release: default_2.FC<IconProps>;
-    deploy: default_2.FC<IconProps>;
+    commit: FC<IconProps>;
+    pr: FC<IconProps>;
+    issue: FC<IconProps>;
+    comment: FC<IconProps>;
+    star: FC<IconProps>;
+    fork: FC<IconProps>;
+    merge: FC<IconProps>;
+    release: FC<IconProps>;
+    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
  */
@@ -94,18 +163,28 @@ export declare const BugIcon: default_2.FC<IconProps>;
 export declare const BuildIcon: default_2.FC<IconProps>;
 
 export declare const BusinessIcons: {
-    chart: default_2.FC<IconProps>;
-    meeting: default_2.FC<IconProps>;
-    document: default_2.FC<IconProps>;
-    calendar: default_2.FC<IconProps>;
-    briefcase: default_2.FC<IconProps>;
+    chart: FC<IconProps>;
+    meeting: FC<IconProps>;
+    document: FC<IconProps>;
+    calendar: FC<IconProps>;
+    briefcase: FC<IconProps>;
 };
 
 /**
- * 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
@@ -115,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
      */
@@ -196,35 +286,83 @@ export declare const DeployIcon: default_2.FC<IconProps>;
 
 export declare const DeploymentIcon: default_2.FC<IconProps>;
 
+/**
+ * Detect which video provider handles a given URL
+ * @param url - The video URL to analyze
+ * @returns The matching VideoProvider or null if not found
+ */
+export declare function detectProvider(url: string): VideoProvider | null;
+
 export declare const DevProcessIcons: {
-    gitbranch: default_2.FC<IconProps>;
-    prdraft: default_2.FC<IconProps>;
-    testing: default_2.FC<IconProps>;
-    deployment: default_2.FC<IconProps>;
-    review: default_2.FC<IconProps>;
-    build: default_2.FC<IconProps>;
+    gitbranch: FC<IconProps>;
+    prdraft: FC<IconProps>;
+    testing: FC<IconProps>;
+    deployment: FC<IconProps>;
+    review: FC<IconProps>;
+    build: FC<IconProps>;
 };
 
 export declare const DocumentIcon: default_2.FC<IconProps>;
 
 export declare const DumbbellIcon: default_2.FC<IconProps>;
 
+/**
+ * Options for video embedding
+ */
+export declare interface EmbedOptions {
+    /**
+     * Enable autoplay (note: most browsers require muted=true for autoplay to work)
+     */
+    autoplay?: boolean;
+    /**
+     * Mute the video by default
+     */
+    muted?: boolean;
+    /**
+     * Loop the video
+     */
+    loop?: boolean;
+    /**
+     * Start time in seconds
+     */
+    startTime?: number;
+    /**
+     * Show video controls
+     */
+    controls?: boolean;
+}
+
 /**
  * Export format options
  */
 export declare type ExportFormat = 'json' | 'html' | 'markdown';
 
+/**
+ * Extract video ID from a URL using the appropriate provider
+ * @param url - The video URL to parse
+ * @returns Object containing the provider and video ID, or null if not found
+ */
+export declare function extractVideoId(url: string): VideoIdExtractionResult | null;
+
 export declare const FitnessIcons: {
-    dumbbell: default_2.FC<IconProps>;
-    running: default_2.FC<IconProps>;
-    heartrate: default_2.FC<IconProps>;
-    strength: default_2.FC<IconProps>;
+    dumbbell: FC<IconProps>;
+    running: FC<IconProps>;
+    heartrate: FC<IconProps>;
+    strength: FC<IconProps>;
 };
 
 export declare const FoldIcon: default_2.FC<IconProps>;
 
 export declare const ForkIcon: default_2.FC<IconProps>;
 
+/**
+ * Get embed URL from a video URL
+ * @param url - The video URL
+ * @param options - Embed options
+ * @returns The embed URL or null if not found
+ */
+export declare function getEmbedUrlFromVideoUrl(url: string, options?: Parameters<VideoProvider['getEmbedUrl']>[1]): string | null;
+
 export declare const GitBranchIcon: default_2.FC<IconProps>;
 
 /**
@@ -309,6 +447,44 @@ 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>;
 
 /**
@@ -321,6 +497,13 @@ export declare interface IconProps {
     color?: string;
 }
 
+/**
+ * Check if a URL is from an adult content provider
+ * @param url - The video URL to check
+ * @returns true if the URL is from an adult content provider
+ */
+export declare function isAdultContent(url: string): boolean;
+
 export declare const IssueIcon: default_2.FC<IconProps>;
 
 export declare const MeditationIcon: default_2.FC<IconProps>;
@@ -331,6 +514,11 @@ export declare const MergeIcon: default_2.FC<IconProps>;
 
 export declare const PlanetIcon: default_2.FC<IconProps>;
 
+/**
+ * Map of provider names to provider objects for quick lookup
+ */
+export declare const providersByName: Record<string, VideoProvider>;
+
 export declare const PullRequestDraftIcon: default_2.FC<IconProps>;
 
 export declare const PullRequestIcon: default_2.FC<IconProps>;
@@ -347,12 +535,17 @@ 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: default_2.FC<IconProps>;
-    satellite: default_2.FC<IconProps>;
-    alien: default_2.FC<IconProps>;
-    planet: default_2.FC<IconProps>;
-    telescope: default_2.FC<IconProps>;
+    rocket: FC<IconProps>;
+    satellite: FC<IconProps>;
+    alien: FC<IconProps>;
+    planet: FC<IconProps>;
+    telescope: FC<IconProps>;
 };
 
 export declare const StarIcon: default_2.FC<IconProps>;
@@ -362,12 +555,12 @@ export declare const StrengthIcon: default_2.FC<IconProps>;
 export declare const TaiChiIcon: default_2.FC<IconProps>;
 
 export declare const TechIcons: {
-    server: default_2.FC<IconProps>;
-    database: default_2.FC<IconProps>;
-    cloud: default_2.FC<IconProps>;
-    terminal: default_2.FC<IconProps>;
-    bug: default_2.FC<IconProps>;
-    code: default_2.FC<IconProps>;
+    server: FC<IconProps>;
+    database: FC<IconProps>;
+    cloud: FC<IconProps>;
+    terminal: FC<IconProps>;
+    bug: FC<IconProps>;
+    code: FC<IconProps>;
 };
 
 export declare const TelescopeIcon: default_2.FC<IconProps>;
@@ -386,6 +579,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
  */
@@ -407,6 +653,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
      */
@@ -462,8 +712,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
      */
@@ -472,6 +756,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;
 }
 
 /**
@@ -520,6 +817,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
      */
@@ -564,6 +865,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
      */
@@ -637,7 +942,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
@@ -651,6 +956,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
      */
@@ -722,24 +1031,108 @@ export declare interface UIForgeGridProps<T = Record<string, unknown>> {
 }
 
 /**
- * UIForgeVideo - A video component with overlay that supports YouTube and Vimeo embeds
+ * 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
  *
  * Features:
- * - Displays video title and optional description
- * - Supports YouTube and Vimeo video embeds
+ * - Auto-detects video provider from URL
+ * - Supports 30+ video platforms including YouTube, Vimeo, Twitch, and more
  * - Shows thumbnail with overlay icon before playing
- * - Emits event when video is clicked to play
+ * - Emits events for video interactions
  * - Lazy loads the video player on interaction
+ * - Adult content filtering (disabled by default)
+ * - Responsive design with configurable aspect ratios
  *
  * @example
  * ```tsx
+ * // Auto-detect from URL
+ * <UIForgeVideo url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />
+ *
+ * // With options
  * <UIForgeVideo
- *   title="Introduction to React"
- *   description="Learn React basics in this tutorial"
- *   youtubeId="dQw4w9WgXcQ"
- *   onPlay={(videoId, provider) => {
- *     console.log(`Playing ${provider} video: ${videoId}`)
- *   }}
+ *   url="https://vimeo.com/123456789"
+ *   autoplay={false}
+ *   muted={true}
+ *   aspectRatio="16:9"
+ *   onPlay={(id, provider) => console.log(`Playing ${provider} video ${id}`)}
  * />
  * ```
  */
@@ -790,21 +1183,56 @@ export declare interface UIForgeVideoPreviewProps {
  */
 export declare interface UIForgeVideoProps {
     /**
-     * Video title
+     * Video title (optional when using url prop)
      */
-    title: string;
+    title?: string;
     /**
      * Video description
      */
     description?: string;
+    /**
+     * Video URL from any supported platform
+     * The provider and video ID will be automatically detected
+     */
+    url?: string;
     /**
      * YouTube video ID (e.g., "dQw4w9WgXcQ" from https://www.youtube.com/watch?v=dQw4w9WgXcQ)
+     * @deprecated Use url prop instead
      */
     youtubeId?: string;
     /**
      * Vimeo video ID (e.g., "123456789" from https://vimeo.com/123456789)
+     * @deprecated Use url prop instead
      */
     vimeoId?: string;
+    /**
+     * Directly specify the provider name (e.g., "youtube", "vimeo")
+     */
+    provider?: string;
+    /**
+     * Video ID when using direct provider specification
+     */
+    videoId?: string;
+    /**
+     * Enable autoplay (note: most browsers require muted=true for autoplay to work)
+     */
+    autoplay?: boolean;
+    /**
+     * Mute the video by default
+     */
+    muted?: boolean;
+    /**
+     * Loop the video
+     */
+    loop?: boolean;
+    /**
+     * Start time in seconds
+     */
+    startTime?: number;
+    /**
+     * Show video controls (default: true)
+     */
+    controls?: boolean;
     /**
      * Custom thumbnail URL (optional, will use provider's default if not specified)
      */
@@ -812,34 +1240,227 @@ export declare interface UIForgeVideoProps {
     /**
      * Callback fired when the video overlay is clicked and playback begins
      */
-    onPlay?: (videoId: string, provider: 'youtube' | 'vimeo') => void;
+    onPlay?: (videoId: string, provider: string) => void;
+    /**
+     * Callback fired when video playback is paused
+     */
+    onPause?: (videoId: string, provider: string) => void;
+    /**
+     * Callback fired when video playback ends
+     */
+    onEnded?: (videoId: string, provider: string) => void;
+    /**
+     * Callback fired when an error occurs
+     */
+    onError?: (error: Error, provider: string) => void;
+    /**
+     * Callback fired when the video player is ready
+     */
+    onReady?: (videoId: string, provider: string) => void;
     /**
      * Custom className for styling
      */
     className?: string;
+    /**
+     * Aspect ratio of the video player (default: "16:9")
+     */
+    aspectRatio?: '16:9' | '4:3' | '1:1' | 'auto' | string;
+    /**
+     * Width of the video player
+     */
+    width?: string | number;
+    /**
+     * 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)
      */
     overlayIcon?: default_2.ReactNode;
     /**
-     * Aspect ratio of the video player (default: "16/9")
+     * Allow adult content to be embedded
+     * Default: false (must be explicitly enabled)
      */
-    aspectRatio?: string;
+    allowAdultContent?: boolean;
+    /**
+     * Fallback content when video cannot be loaded
+     */
+    fallback?: default_2.ReactNode;
 }
 
 export declare const UIIcons: {
-    unfold: default_2.FC<IconProps>;
-    fold: default_2.FC<IconProps>;
-    close: default_2.FC<IconProps>;
-    check: default_2.FC<IconProps>;
+    unfold: FC<IconProps>;
+    fold: FC<IconProps>;
+    close: FC<IconProps>;
+    check: FC<IconProps>;
 };
 
 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
+ */
+declare interface VideoIdExtractionResult {
+    provider: VideoProvider;
+    videoId: string;
+}
+
+/**
+ * Video provider interface
+ */
+export declare interface VideoProvider {
+    /**
+     * Internal provider name (lowercase, no spaces)
+     */
+    name: string;
+    /**
+     * Display name for the provider
+     */
+    displayName: string;
+    /**
+     * Domains this provider handles
+     */
+    domains: string[];
+    /**
+     * Extract video ID from a URL
+     */
+    extractVideoId: (url: string) => string | null;
+    /**
+     * Generate embed URL for a video ID
+     */
+    getEmbedUrl: (videoId: string, options?: EmbedOptions) => string;
+    /**
+     * Whether the provider supports autoplay
+     */
+    supportsAutoplay?: boolean;
+    /**
+     * Whether the provider has a JavaScript API
+     */
+    supportsApi?: boolean;
+    /**
+     * Provider tier classification
+     */
+    tier: VideoProviderTier;
+}
+
+/**
+ * Array of all registered video providers
+ * Ordered by tier and priority for matching
+ */
+export declare const videoProviders: VideoProvider[];
+
+/**
+ * Video provider tier classification
+ */
+export declare type VideoProviderTier = 'major' | 'professional' | 'cloud' | 'social' | 'adult';
+
 export declare const WellnessIcons: {
-    taichi: default_2.FC<IconProps>;
-    meditation: default_2.FC<IconProps>;
-    yoga: default_2.FC<IconProps>;
+    taichi: FC<IconProps>;
+    meditation: FC<IconProps>;
+    yoga: FC<IconProps>;
 };
 
 export declare const YogaIcon: default_2.FC<IconProps>;