@opencosmos/ui 1.3.1

package/src/components/layout/Header/Header.tsx

@@ -0,0 +1,450 @@
+'use client';;
+import React, { useState, useEffect } from 'react';
+import { useMotionPreference } from '../../../hooks/useMotionPreference';
+import { NavLink } from '../../navigation/NavLink';
+import { Menu, X, ChevronDown } from 'lucide-react';
+
+export interface HeaderNavLink {
+    label: string;
+    href?: string;
+    /**
+     * Whether this link represents the current/active page
+     * @default false
+     */
+    active?: boolean;
+    /**
+     * Nested links for dropdown menus
+     */
+    children?: Array<{
+        label: string;
+        href: string;
+        active?: boolean;
+    }>;
+}
+
+export interface HeaderProps {
+    /**
+     * Brand/logo element or text
+     */
+    logo?: React.ReactNode;
+    /**
+     * Array of navigation links
+     */
+    navLinks?: HeaderNavLink[];
+    /**
+     * Content for the right side (e.g., Sign In, CTA buttons)
+     */
+    actions?: React.ReactNode;
+    /**
+     * Whether to apply glass morphism effect on scroll
+     * @default true
+     */
+    glassOnScroll?: boolean;
+    /**
+     * Scroll threshold in pixels before applying glass effect
+     * @default 10
+     */
+    scrollThreshold?: number;
+    /**
+     * Whether the header is sticky (fixed position)
+     * @default true
+     */
+    sticky?: boolean;
+    /**
+     * Font size for desktop navigation links
+     * @default 'text-sm' (14px)
+     */
+    navLinkSize?: 'text-xs' | 'text-sm' | 'text-base' | 'text-lg';
+    /**
+     * Font family for navigation links
+     * Uses CSS variable --font-header-nav by default
+     * Logo font is controlled by the logo ReactNode itself or --font-header-logo
+     * @default 'var(--font-header-nav)'
+     */
+    fontFamily?: string;
+    /**
+     * Maximum width for header content
+     * @default 'max-w-7xl' (1280px)
+     */
+    maxWidth?: 'max-w-7xl' | 'max-w-[1440px]' | 'max-w-4xl';
+    /**
+     * Alignment of the navigation links
+     * @default 'center'
+     */
+    navAlignment?: 'center' | 'left' | 'right';
+    /**
+     * Additional className for customization
+     */
+    className?: string;
+}
+
+export const Header = (
+    {
+        ref,
+        logo,
+        navLinks = [],
+        actions,
+        glassOnScroll = true,
+        scrollThreshold = 10,
+        sticky = true,
+        navLinkSize = 'text-sm',
+        navAlignment = 'center',
+        fontFamily = 'var(--font-header-nav)',
+        maxWidth = 'max-w-7xl',
+        className = ''
+    }: HeaderProps & {
+        ref?: React.Ref<HTMLElement>;
+    }
+) => {
+    const [isMenuOpen, setIsMenuOpen] = useState(false);
+    const [hasScrolled, setHasScrolled] = useState(false);
+    const [openDropdown, setOpenDropdown] = useState<string | null>(null);
+    const [expandedMobileSection, setExpandedMobileSection] = useState<string | null>(null);
+    const { shouldAnimate, scale } = useMotionPreference();
+
+    // Calculate motion factors
+    const motionFactor = shouldAnimate && scale > 0 ? (5 / scale) : 0;
+    const transitionDuration = `${300 * motionFactor}ms`;
+
+    // Handle scroll detection
+    useEffect(() => {
+        if (!glassOnScroll) return;
+
+        const handleScroll = () => {
+            setHasScrolled(window.scrollY > scrollThreshold);
+        };
+
+        window.addEventListener('scroll', handleScroll, { passive: true });
+        return () => window.removeEventListener('scroll', handleScroll);
+    }, [glassOnScroll, scrollThreshold]);
+
+    // Lock body scroll when mobile menu is open
+    useEffect(() => {
+        if (isMenuOpen) {
+            document.body.style.overflow = 'hidden';
+        } else {
+            document.body.style.overflow = '';
+        }
+        return () => {
+            document.body.style.overflow = '';
+        };
+    }, [isMenuOpen]);
+
+    const baseStyles = 'top-0 left-0 right-0 z-50';
+    const positionStyles = sticky ? 'fixed' : 'relative';
+    const transitionStyles = shouldAnimate ? 'transition-all' : '';
+
+    // Liquid Glass Effect
+    // Unscrolled: Transparent & Borderless (looks printed on background), but with blur for "liquid" feel over Orb
+    // Scrolled: Wetter glass, more opaque, shadow for depth, no harsh borders
+    const backgroundStyles = hasScrolled && glassOnScroll
+        ? 'backdrop-blur-3xl bg-[var(--color-surface)]/60 border-b border-transparent shadow-xs supports-[backdrop-filter]:bg-[var(--color-surface)]/50'
+        : 'bg-transparent border-b border-transparent backdrop-blur-xl';
+
+    // Nav Alignment Classes
+    const getNavClasses = () => {
+        switch (navAlignment) {
+            case 'left':
+                return 'ml-8 mr-auto';
+            case 'right':
+                return 'ml-auto mr-8';
+            case 'center':
+            default:
+                return 'absolute left-1/2 -translate-x-1/2';
+        }
+    };
+
+    return (
+        <>
+            <header
+                ref={ref}
+                className={`${baseStyles} ${positionStyles} ${transitionStyles} ${backgroundStyles} ${className}`}
+                style={{ transitionDuration }}
+            >
+                <div className={`${maxWidth} mx-auto px-4 sm:px-6 lg:px-8`}>
+                    <div className="flex items-center justify-between h-16 lg:h-20 relative">
+                        {/* Logo */}
+                        {logo && (
+                            <div className="flex-shrink-0 z-10">
+                                {logo}
+                            </div>
+                        )}
+
+                        {/* Desktop Navigation */}
+                        {navLinks.length > 0 && (
+                            <nav
+                                className={`hidden lg:flex items-center gap-8 ${getNavClasses()}`}
+                                aria-label="Main navigation"
+                            >
+                                {navLinks.map((link) => {
+                                    const hasDropdown = link.children && link.children.length > 0;
+                                    const isOpen = openDropdown === link.label;
+
+                                    if (hasDropdown) {
+                                        return (
+                                            <div
+                                                key={link.label}
+                                                className="relative group"
+                                                onMouseEnter={() => setOpenDropdown(link.label)}
+                                                onMouseLeave={() => setOpenDropdown(null)}
+                                            >
+                                                <button
+                                                    className={`
+                                                        ${navLinkSize}
+                                                        relative
+                                                        pb-1
+                                                        flex items-center gap-1
+                                                        focus-visible:outline
+                                                        focus-visible:outline-2
+                                                        focus-visible:outline-offset-4
+                                                        focus-visible:outline-[var(--color-focus)]
+                                                        rounded-xs
+                                                        ${shouldAnimate ? 'transition-colors' : ''}
+                                                        ${link.active
+                                                            ? 'text-[var(--color-text-primary)] font-medium after:absolute after:bottom-0 after:left-0 after:right-0 after:h-0.5 after:bg-[var(--color-primary)] after:rounded-full'
+                                                            : 'text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)]'
+                                                        }
+                                                    `}
+                                                    style={{ fontFamily, transitionDuration }}
+                                                    aria-expanded={isOpen}
+                                                    aria-haspopup="true"
+                                                >
+                                                    {link.label}
+                                                    <ChevronDown className={`w-3 h-3 ${shouldAnimate ? 'transition-transform' : ''} ${isOpen ? 'rotate-180' : ''}`} style={{ transitionDuration }} />
+                                                </button>
+                                                {/* Invisible bridge to prevent dropdown from closing */}
+                                                {isOpen && <div className="absolute top-full left-1/2 -translate-x-1/2 w-[200px] h-2" />}
+                                                {isOpen && (
+                                                    <div className={`
+                                                        absolute top-full left-1/2 -translate-x-1/2 mt-2 min-w-[200px] z-50
+                                                        bg-[var(--color-surface)] border border-[var(--color-border)]
+                                                        rounded-lg shadow-xl py-1 p-1
+                                                        backdrop-blur-3xl bg-[var(--color-surface)]/95
+                                                        ${shouldAnimate ? 'animate-fade-in' : ''}
+                                                    `} style={{ animationDuration: `${0.2 * motionFactor}s` }}>
+                                                        {link.children?.map((child) => (
+                                                            <NavLink
+                                                                key={child.label}
+                                                                href={child.href}
+                                                                active={child.active}
+                                                                variant="pill"
+                                                                className="w-full"
+                                                            >
+                                                                {child.label}
+                                                            </NavLink>
+                                                        ))}
+                                                    </div>
+                                                )}
+                                            </div>
+                                        );
+                                    }
+
+                                    return (
+                                        <NavLink
+                                            key={link.label}
+                                            href={link.href}
+                                            active={link.active}
+                                            variant="minimal"
+                                            className={navLinkSize}
+                                            style={{ fontFamily }}
+                                        >
+                                            {link.label}
+                                        </NavLink>
+                                    );
+                                })}
+                            </nav>
+                        )}
+
+                        {/* Desktop Actions */}
+                        {actions && (
+                            <div className="hidden lg:flex items-center gap-4 z-10">
+                                {actions}
+                            </div>
+                        )}
+
+                        {/* Mobile Menu Button */}
+                        <button
+                            onClick={() => setIsMenuOpen(!isMenuOpen)}
+                            className={`
+                                lg:hidden
+                                p-2
+                                text-[var(--color-text-primary)]
+                                hover:bg-[var(--color-surface)]
+                                rounded-lg
+                                focus-visible:outline
+                                focus-visible:outline-2
+                                focus-visible:outline-offset-2
+                                focus-visible:outline-[var(--color-focus)]
+                                ${shouldAnimate ? 'transition-colors' : ''}
+                            `}
+                            style={{ transitionDuration }}
+                            aria-label={isMenuOpen ? 'Close menu' : 'Open menu'}
+                            aria-expanded={isMenuOpen}
+                        >
+                            {isMenuOpen ? (
+                                <X className="w-6 h-6" />
+                            ) : (
+                                <Menu className="w-6 h-6" />
+                            )}
+                        </button>
+                    </div>
+                </div>
+            </header>
+
+            {/* Mobile Full-Screen Menu */}
+            <div
+                className={`
+                    fixed inset-0 z-[100] lg:hidden
+                    ${shouldAnimate ? 'transition-all' : ''}
+                    ${isMenuOpen
+                        ? 'opacity-100 pointer-events-auto'
+                        : 'opacity-0 pointer-events-none'
+                    }
+                `}
+                style={{ transitionDuration }}
+                aria-hidden={!isMenuOpen}
+            >
+                <div className="absolute inset-0 bg-[var(--color-background)]">
+                    <div className="flex flex-col items-center justify-center h-full gap-8 px-4">
+                        {/* Mobile Navigation Links */}
+                        {navLinks.map((link, index) => {
+                            const hasDropdown = link.children && link.children.length > 0;
+                            const isExpanded = expandedMobileSection === link.label;
+
+                            if (hasDropdown) {
+                                return (
+                                    <div key={link.label} className="w-full max-w-xs">
+                                        <button
+                                            onClick={() => setExpandedMobileSection(isExpanded ? null : link.label)}
+                                            className={`
+                                                text-3xl w-full text-center
+                                                focus-visible:outline
+                                                focus-visible:outline-2
+                                                focus-visible:outline-offset-4
+                                                focus-visible:outline-[var(--color-focus)]
+                                                rounded-xs
+                                                ${shouldAnimate ? 'transition-all' : ''}
+                                                ${link.active
+                                                    ? 'text-[var(--color-primary)] font-semibold'
+                                                    : 'text-[var(--color-text-primary)] hover:text-[var(--color-text-secondary)]'
+                                                }
+                                            `}
+                                            style={
+                                                shouldAnimate && isMenuOpen
+                                                    ? {
+                                                        animation: `fadeInUp ${0.5 * motionFactor}s ease-out ${index * 0.1 * motionFactor}s forwards`,
+                                                        opacity: 0,
+                                                        fontFamily,
+                                                        transitionDuration
+                                                    }
+                                                    : { opacity: 1, fontFamily }
+                                            }
+                                            aria-expanded={isExpanded}
+                                        >
+                                            {link.label}
+                                        </button>
+                                        {isExpanded && (
+                                            <div className="flex flex-col gap-3 mt-4">
+                                                {link.children?.map((child) => (
+                                                    <a
+                                                        key={child.label}
+                                                        href={child.href}
+                                                        onClick={() => setIsMenuOpen(false)}
+                                                        className={`
+                                                            text-xl text-center block
+                                                            focus-visible:outline
+                                                            focus-visible:outline-2
+                                                            focus-visible:outline-offset-4
+                                                            focus-visible:outline-[var(--color-focus)]
+                                                            rounded-xs
+                                                            ${shouldAnimate ? 'transition-colors' : ''}
+                                                            ${child.active
+                                                                ? 'text-[var(--color-primary)] font-medium'
+                                                                : 'text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)]'
+                                                            }
+                                                        `}
+                                                        style={{ transitionDuration }}
+                                                        aria-current={child.active ? 'page' : undefined}
+                                                    >
+                                                        {child.label}
+                                                    </a>
+                                                ))}
+                                            </div>
+                                        )}
+                                    </div>
+                                );
+                            }
+
+                            return (
+                                <a
+                                    key={link.label}
+                                    href={link.href}
+                                    onClick={() => setIsMenuOpen(false)}
+                                    aria-current={link.active ? 'page' : undefined}
+                                    className={`
+                                        text-3xl
+                                        focus-visible:outline
+                                        focus-visible:outline-2
+                                        focus-visible:outline-offset-4
+                                        focus-visible:outline-[var(--color-focus)]
+                                        rounded-xs
+                                        ${shouldAnimate ? 'transition-all' : ''}
+                                        ${link.active
+                                            ? 'text-[var(--color-primary)] font-semibold'
+                                            : 'text-[var(--color-text-primary)] hover:text-[var(--color-text-secondary)]'
+                                        }
+                                    `}
+                                    style={
+                                        shouldAnimate && isMenuOpen
+                                            ? {
+                                                animation: `fadeInUp ${0.5 * motionFactor}s ease-out ${index * 0.1 * motionFactor}s forwards`,
+                                                opacity: 0,
+                                                fontFamily,
+                                                transitionDuration
+                                            }
+                                            : { opacity: 1, fontFamily }
+                                    }
+                                >
+                                    {link.label}
+                                </a>
+                            );
+                        })}
+
+                        {/* Mobile Actions */}
+                        {actions && (
+                            <div
+                                className="flex flex-col gap-4 mt-8 w-full max-w-xs"
+                                style={
+                                    shouldAnimate && isMenuOpen
+                                        ? {
+                                            animation: `fadeInUp ${0.5 * motionFactor}s ease-out ${navLinks.length * 0.1 * motionFactor}s forwards`,
+                                            opacity: 0,
+                                        }
+                                        : { opacity: 1 }
+                                }
+                            >
+                                {actions}
+                            </div>
+                        )}
+                    </div>
+                </div>
+            </div>
+
+            {/* Animation keyframes - only added if motion is enabled */}
+            {shouldAnimate && (
+                <style>{`
+                    @keyframes fadeInUp {
+                        from {
+                            opacity: 0;
+                            transform: translateY(20px);
+                        }
+                        to {
+                            opacity: 1;
+                            transform: translateY(0);
+                        }
+                    }
+                `}</style>
+            )}
+        </>
+    );
+};

package/src/components/layout/Header/index.ts

@@ -0,0 +1,2 @@
+export { Header } from './Header';
+export type { HeaderProps, HeaderNavLink } from './Header';

package/src/components/layout/PageLayout.tsx

@@ -0,0 +1,180 @@
+import React from 'react';
+
+export interface PageLayoutProps {
+  /** Optional header configuration */
+  header?: React.ReactNode;
+
+  /** Whether the header is sticky (adds top padding to first content element) */
+  stickyHeader?: boolean;
+
+  /** Optional breadcrumbs */
+  breadcrumbs?: React.ReactNode;
+
+  /** Breadcrumbs position: 'top' (sticky below header) or 'below-title' (static below title+subtitle) */
+  breadcrumbsPosition?: 'top' | 'below-title';
+
+  /** Optional page title - rendered in content-width container */
+  title?: React.ReactNode;
+
+  /** Optional page subtitle - rendered below title */
+  subtitle?: React.ReactNode;
+
+  /** Apply Swiss Grid Design spacing to title/subtitle area */
+  swissGridSpacing?: boolean;
+
+  /** Maximum width for title/subtitle area - should match content width for alignment */
+  contentMaxWidth?: 'max-w-7xl' | 'max-w-[1440px]' | 'max-w-4xl';
+
+  /** Optional secondary navigation (first stack) */
+  secondaryNav?: React.ReactNode;
+
+  /** Optional tertiary navigation (second stack) */
+  tertiaryNav?: React.ReactNode;
+
+  /** Optional footer */
+  footer?: React.ReactNode;
+
+  /** Main content */
+  children: React.ReactNode;
+
+  /** Optional className for main content */
+  className?: string;
+}
+
+/**
+ * PageLayout Component
+ *
+ * A flexible layout organism that composes Header, Breadcrumbs, SecondaryNav,
+ * TertiaryNav, and Footer with automatic z-index and sticky positioning management.
+ *
+ * Features:
+ * - Automatic z-index stacking (50 → 45 → 40 → 30)
+ * - Dynamic sticky positioning calculations
+ * - Optional title/subtitle slots with Swiss Grid spacing
+ * - Flexible breadcrumb positioning (sticky top or static below title)
+ * - Optional composition (all props optional)
+ * - Handles full-height layouts
+ * - Theme-aware styling
+ *
+ * Z-Index Stack:
+ * - Header: z-50, h-16 lg:h-20
+ * - Breadcrumbs (if position='top'): z-45, sticky below header
+ * - SecondaryNav: z-40, first navigation stack
+ * - TertiaryNav: z-30, second navigation stack
+ *
+ * Swiss Grid Design:
+ * - Title/subtitle area uses structured spacing (48-96px sections)
+ * - Typography hierarchy: text-4xl/5xl title, text-lg subtitle
+ * - Content-width container (max-w-7xl) for proper alignment
+ *
+ * Example:
+ * ```tsx
+ * <PageLayout
+ *   header={<Header logo={logo} navLinks={links} />}
+ *   title={<h1>Page Title</h1>}
+ *   subtitle={<p>Page subtitle</p>}
+ *   breadcrumbs={<Breadcrumbs items={breadcrumbItems} />}
+ *   breadcrumbsPosition="below-title"
+ *   swissGridSpacing
+ *   secondaryNav={<SecondaryNav items={sections} />}
+ * >
+ *   <article>Your content here</article>
+ * </PageLayout>
+ * ```
+ */
+export function PageLayout({
+  header,
+  stickyHeader = false,
+  breadcrumbs,
+  breadcrumbsPosition = 'top',
+  title,
+  subtitle,
+  swissGridSpacing = false,
+  contentMaxWidth = 'max-w-7xl',
+  secondaryNav,
+  tertiaryNav,
+  footer,
+  children,
+  className = '',
+}: PageLayoutProps) {
+  // Determine if breadcrumbs should be at the top (sticky) or below title (static)
+  const showBreadcrumbsAtTop = breadcrumbsPosition === 'top';
+  const showBreadcrumbsBelowTitle = breadcrumbsPosition === 'below-title';
+
+  // Sticky header spacing - add top padding to first content element
+  const stickyHeaderSpacing = stickyHeader ? 'pt-16 lg:pt-20' : '';
+
+  // Swiss Grid spacing classes
+  // When breadcrumbs are below title, reduce bottom padding on title area to avoid excessive space
+  const titleAreaTopSpacing = swissGridSpacing ? 'pt-12 lg:pt-16' : 'pt-8';
+  const titleAreaBottomSpacing = swissGridSpacing && showBreadcrumbsBelowTitle ? 'pb-3' : swissGridSpacing ? 'pb-12 lg:pb-16' : 'pb-8';
+  const titleBottomMargin = swissGridSpacing ? 'mb-4' : 'mb-3';
+  const breadcrumbsAreaSpacing = swissGridSpacing ? 'pt-4 pb-8' : 'pt-3 pb-6';
+
+  return (
+    <div className="min-h-screen flex flex-col w-full min-w-0">
+      {/* Header - z-50, h-16 lg:h-20 */}
+      {header}
+
+      {/* Breadcrumbs - z-45, sticky below header (only if position='top') */}
+      {breadcrumbs && showBreadcrumbsAtTop && (
+        <div
+          className={`
+            sticky bg-[var(--color-background)]/95 backdrop-blur-xs
+            border-b border-[var(--color-border)]
+            transition-all duration-300
+            top-16 lg:top-20
+            ${stickyHeaderSpacing}
+          `}
+          style={{ zIndex: 45 }}
+        >
+          <div className={`${contentMaxWidth} mx-auto px-4 sm:px-6 lg:px-8 py-3`}>
+            {breadcrumbs}
+          </div>
+        </div>
+      )}
+
+      {/* Title/Subtitle Area - Swiss Grid Design */}
+      {(title || subtitle) && (
+        <div className={`${titleAreaTopSpacing} ${titleAreaBottomSpacing} ${!showBreadcrumbsAtTop ? stickyHeaderSpacing : ''} bg-[var(--color-background)]`}>
+          <div className={`${contentMaxWidth} mx-auto px-4 sm:px-6 lg:px-8`}>
+            {/* Title */}
+            {title && (
+              <div className={titleBottomMargin}>
+                {title}
+              </div>
+            )}
+
+            {/* Subtitle */}
+            {subtitle && <div>{subtitle}</div>}
+          </div>
+        </div>
+      )}
+
+      {/* Breadcrumbs below title+subtitle (only if position='below-title') */}
+      {breadcrumbs && showBreadcrumbsBelowTitle && (
+        <div className={`${breadcrumbsAreaSpacing} bg-[var(--color-background)]`}>
+          <div className={`${contentMaxWidth} mx-auto px-4 sm:px-6 lg:px-8`}>
+            {breadcrumbs}
+          </div>
+        </div>
+      )}
+
+      {/* Secondary Nav - z-40, first navigation stack */}
+      {secondaryNav}
+
+      {/* Tertiary Nav - z-30, second navigation stack */}
+      {tertiaryNav}
+
+      {/* Main Content - flexible, fills remaining space */}
+      <main className={`flex-1 ${className}`}>
+        <div className={`${contentMaxWidth} mx-auto px-4 sm:px-6 lg:px-8 py-12`}>
+          {children}
+        </div>
+      </main>
+
+      {/* Footer */}
+      {footer}
+    </div>
+  );
+}