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

@appforgeapps/uiforge 0.5.0 → 0.5.2

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,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>;
 /**
@@ -414,6 +535,11 @@ 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 +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
  */
@@ -474,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
      */
@@ -529,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
      */
@@ -539,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;
 }
 /**
@@ -587,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
      */
@@ -631,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
      */
@@ -704,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
@@ -718,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
      */
@@ -788,6 +1030,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 +1273,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 +1312,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
  */