@appforgeapps/uiforge 0.5.2 → 0.5.3

package/README.md

@@ -1652,6 +1652,19 @@ function App() {
 }
 ```
 
+## Mobile Header Best Practices
+
+For building mobile headers with `MobileHeaderLayout`, `IconButton`, `SafeAreaContainer`, and `OverflowMenu`, see [MOBILE_HEADER_BEST_PRACTICES.md](./MOBILE_HEADER_BEST_PRACTICES.md) for:
+
+- Touch target guidelines (44×44px minimum)
+- ARIA label requirements for accessibility
+- Recommended header height (56px)
+- Safe area usage for notched devices
+- When to use overflow menus vs primary actions
+- Layout vs behavior separation rationale
+
+See `examples/CourseForgeMobileHeaderExample.tsx` for a complete composition example demonstrating these patterns.
+
 ## Development
 
 ### Prerequisites

package/dist/index.d.ts

@@ -487,6 +487,71 @@ export declare interface HamburgerButtonProps extends Omit<default_2.ButtonHTMLA
 
 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
@@ -512,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>;
 
 /**
@@ -531,6 +796,80 @@ 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>;