@opencosmos/ui 1.3.1

package/src/components/layout/PageTemplate.tsx

@@ -0,0 +1,158 @@
+'use client';
+
+import React from 'react';
+import { Header, type HeaderNavLink } from './Header/Header';
+import { Breadcrumbs, type BreadcrumbItemLegacy } from '../navigation/Breadcrumbs';
+import { SecondaryNav, type SecondaryNavItem } from '../navigation/SecondaryNav';
+import { PageLayout } from './PageLayout';
+import { CustomizerPanel } from './CustomizerPanel';
+import { Heading } from '../data-display/Heading';
+import { Text } from '../data-display/Text';
+
+export interface PageTemplateHeaderConfig {
+  /** Logo or brand element */
+  logo: React.ReactNode;
+  /** Navigation links with optional dropdowns */
+  navLinks?: HeaderNavLink[];
+  /** Actions (e.g., Sign In button, CTA) */
+  actions?: React.ReactNode;
+  /** Whether header should be sticky (default: true) */
+  sticky?: boolean;
+}
+
+export interface PageTemplateSecondaryNavConfig {
+  /** Secondary navigation items */
+  items: SecondaryNavItem[];
+  /** Currently active item ID */
+  activeId: string;
+  /** Callback when item changes */
+  onItemChange: (id: string) => void;
+}
+
+export interface PageTemplateProps {
+  /** Header configuration */
+  header: PageTemplateHeaderConfig;
+
+  /** Page title (required) */
+  title: string;
+
+  /** Optional page subtitle */
+  subtitle?: string;
+
+  /** Breadcrumb navigation items */
+  breadcrumbs: BreadcrumbItemLegacy[];
+
+  /** Optional secondary navigation */
+  secondaryNav?: PageTemplateSecondaryNavConfig;
+
+  /** Main page content */
+  children: React.ReactNode;
+
+  /** Optional footer */
+  footer?: React.ReactNode;
+
+  /** Show customizer panel (default: true) */
+  showCustomizer?: boolean;
+
+  /** Content width variant */
+  variant?: 'standard' | 'wide' | 'narrow';
+}
+
+/**
+ * PageTemplate Component
+ *
+ * An opinionated page layout template based on Swiss Grid Design principles.
+ * This template provides a structured, clean layout with sensible defaults for
+ * standard pages (blogs, docs, app pages).
+ *
+ * Swiss Grid Design Principles:
+ * - Structured spacing: 48-96px between major sections
+ * - Clear typography hierarchy: 36-48px title, 18px subtitle
+ * - Grid-based alignment with consistent content widths
+ * - Generous whitespace for breathing room
+ * - Minimal, functional aesthetic
+ *
+ * Features:
+ * - Sticky header with glass morphism effect
+ * - Breadcrumbs positioned below page title (static)
+ * - Always-sticky secondary navigation
+ * - Optional customizer panel
+ * - Three width variants: standard (1280px), wide (1440px), narrow (896px)
+ * - Automatic Swiss Grid spacing
+ *
+ * Example:
+ * ```tsx
+ * <PageTemplate
+ *   header={{
+ *     logo: <Link href="/">Brand</Link>,
+ *     navLinks: navigationItems,
+ *     sticky: true
+ *   }}
+ *   title="Welcome to Our Platform"
+ *   subtitle="Build amazing experiences with our tools"
+ *   breadcrumbs={[
+ *     { label: 'Home', href: '/' },
+ *     { label: 'Platform' }
+ *   ]}
+ * >
+ *   <article>Your content here</article>
+ * </PageTemplate>
+ * ```
+ */
+export function PageTemplate({
+  header,
+  title,
+  subtitle,
+  breadcrumbs,
+  secondaryNav,
+  children,
+  footer,
+  showCustomizer = true,
+  variant = 'standard',
+}: PageTemplateProps) {
+  // Determine content width based on variant
+  const maxWidthClass = {
+    standard: 'max-w-7xl',    // 1280px - default, matches most pages
+    wide: 'max-w-[1440px]',   // 1440px - for dashboard-like pages
+    narrow: 'max-w-4xl',      // 896px - for reading-focused pages
+  }[variant] as 'max-w-7xl' | 'max-w-[1440px]' | 'max-w-4xl';
+
+  return (
+    <>
+      <PageLayout
+        header={
+          <Header
+            logo={header.logo}
+            navLinks={header.navLinks}
+            actions={header.actions}
+            sticky={header.sticky ?? true}
+            maxWidth={maxWidthClass}
+          />
+        }
+        stickyHeader={header.sticky ?? true}
+        breadcrumbsPosition="below-title"
+        breadcrumbs={<Breadcrumbs items={breadcrumbs} variant="subtle" />}
+        title={<Heading level={1}>{title}</Heading>}
+        subtitle={subtitle ? <Text size="lg" variant="secondary">{subtitle}</Text> : undefined}
+        secondaryNav={
+          secondaryNav ? (
+            <SecondaryNav
+              items={secondaryNav.items}
+              activeId={secondaryNav.activeId}
+              onItemChange={secondaryNav.onItemChange}
+              maxWidth={maxWidthClass}
+            />
+          ) : undefined
+        }
+        footer={footer}
+        swissGridSpacing
+        contentMaxWidth={maxWidthClass}
+      >
+        {children}
+      </PageLayout>
+
+      {/* Customizer - Swiss Grid: sticky overlay, bottom right */}
+      {showCustomizer && <CustomizerPanel />}
+    </>
+  );
+}

package/src/components/layout/Resizable.tsx

@@ -0,0 +1,48 @@
+"use client"
+
+import * as React from "react"
+import { GripVertical } from "lucide-react"
+import { Group as PanelGroup, Panel, Separator as PanelResizeHandle } from "react-resizable-panels"
+
+import { cn } from "../../lib/utils"
+
+const ResizablePanelGroup = ({
+  className,
+  ...props
+}: React.ComponentProps<typeof PanelGroup>) => {
+  return (
+    <PanelGroup
+      className={cn(
+        "flex h-full w-full data-[panel-group-direction=vertical]:flex-col",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const ResizablePanel = Panel
+
+const ResizableHandle = ({
+  withHandle,
+  className,
+  ...props
+}: React.ComponentProps<typeof PanelResizeHandle> & { withHandle?: boolean }) => {
+  return (
+    <PanelResizeHandle
+      className={cn(
+        "relative flex w-px items-center justify-center bg-border after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-1 data-[panel-group-direction=vertical]:h-px data-[panel-group-direction=vertical]:w-full data-[panel-group-direction=vertical]:after:left-0 data-[panel-group-direction=vertical]:after:h-1 data-[panel-group-direction=vertical]:after:w-full data-[panel-group-direction=vertical]:after:-translate-y-1/2 data-[panel-group-direction=vertical]:after:translate-x-0 [&[data-panel-group-direction=vertical]>div]:rotate-90",
+        className
+      )}
+      {...props}
+    >
+      {withHandle && (
+        <div className="z-10 flex h-4 w-3 items-center justify-center rounded-xs border bg-border">
+          <GripVertical className="h-2.5 w-2.5" />
+        </div>
+      )}
+    </PanelResizeHandle>
+  )
+}
+
+export { ResizablePanelGroup, ResizablePanel, ResizableHandle }

package/src/components/layout/ScrollArea.tsx

@@ -0,0 +1,53 @@
+"use client";
+import * as React from "react"
+import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area"
+
+import { cn } from "../../lib/utils"
+
+const ScrollArea = (
+    {
+        ref,
+        className,
+        children,
+        ...props
+    }: React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root> & {
+        ref?: React.Ref<React.ElementRef<typeof ScrollAreaPrimitive.Root>>;
+    }
+) => (<ScrollAreaPrimitive.Root
+    ref={ref}
+    className={cn("relative overflow-hidden", className)}
+    {...props}
+>
+    <ScrollAreaPrimitive.Viewport className="h-full w-full rounded-[inherit]">
+        {children}
+    </ScrollAreaPrimitive.Viewport>
+    <ScrollBar />
+    <ScrollAreaPrimitive.Corner />
+</ScrollAreaPrimitive.Root>)
+
+const ScrollBar = (
+    {
+        ref,
+        className,
+        orientation = "vertical",
+        ...props
+    }: React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Scrollbar> & {
+        ref?: React.Ref<React.ElementRef<typeof ScrollAreaPrimitive.Scrollbar>>;
+    }
+) => (<ScrollAreaPrimitive.Scrollbar
+    ref={ref}
+    orientation={orientation}
+    className={cn(
+        "flex touch-none select-none transition-colors",
+        orientation === "vertical" &&
+        "h-full w-2.5 border-l border-l-transparent p-[1px]",
+        orientation === "horizontal" &&
+        "h-2.5 flex-col border-t border-t-transparent p-[1px]",
+        className
+    )}
+    {...props}
+>
+    <ScrollAreaPrimitive.Thumb className="relative flex-1 rounded-full bg-border" />
+</ScrollAreaPrimitive.Scrollbar>)
+
+export { ScrollArea, ScrollBar }

package/src/components/layout/Separator.test.tsx

@@ -0,0 +1,28 @@
+import { render } from '@testing-library/react'
+import { describe, it, expect } from 'vitest'
+import { Separator } from './Separator'
+
+describe('Separator', () => {
+  it('renders with horizontal orientation by default', () => {
+    const { container } = render(<Separator />)
+    const separator = container.firstChild as HTMLElement
+    expect(separator).toBeInTheDocument()
+    expect(separator).toHaveAttribute('data-orientation', 'horizontal')
+  })
+
+  it('renders with vertical orientation', () => {
+    const { container } = render(<Separator orientation="vertical" />)
+    const separator = container.firstChild as HTMLElement
+    expect(separator).toHaveAttribute('data-orientation', 'vertical')
+  })
+
+  it('applies custom className', () => {
+    const { container } = render(<Separator className="custom-sep" />)
+    expect(container.firstChild).toHaveClass('custom-sep')
+  })
+
+  it('has separator role when not decorative', () => {
+    const { container } = render(<Separator decorative={false} />)
+    expect(container.querySelector('[role="separator"]')).toBeInTheDocument()
+  })
+})

package/src/components/layout/Separator.tsx

@@ -0,0 +1,29 @@
+"use client";
+import * as React from "react"
+import * as SeparatorPrimitive from "@radix-ui/react-separator"
+
+import { cn } from "../../lib/utils"
+
+const Separator = (
+    {
+        ref,
+        className,
+        orientation = "horizontal",
+        decorative = true,
+        ...props
+    }: React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root> & {
+        ref?: React.Ref<React.ElementRef<typeof SeparatorPrimitive.Root>>;
+    }
+) => (<SeparatorPrimitive.Root
+    ref={ref}
+    decorative={decorative}
+    orientation={orientation}
+    className={cn(
+        "shrink-0 bg-border",
+        orientation === "horizontal" ? "h-[1px] w-full" : "h-full w-[1px]",
+        className
+    )}
+    {...props}
+/>)
+
+export { Separator }

package/src/components/layout/Sidebar.tsx

@@ -0,0 +1,171 @@
+"use client";
+import * as React from "react"
+import { cn } from "../../lib/utils"
+import { Slot } from "@radix-ui/react-slot"
+
+const Sidebar = (
+    {
+        ref,
+        className,
+        children,
+        isOpen = true,
+        ...props
+    }: React.HTMLAttributes<HTMLDivElement> & { isOpen?: boolean } & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => (<aside
+    ref={ref}
+    className={cn(
+        "fixed top-0 left-0 h-full w-[280px] bg-background border-r border-border z-40 transition-transform duration-300 transform",
+        isOpen ? "translate-x-0" : "-translate-x-full lg:translate-x-0",
+        className
+    )}
+    {...props}
+>
+    <div className="flex flex-col h-full">{children}</div>
+</aside>)
+
+const SidebarOverlay = (
+    {
+        ref,
+        className,
+        isOpen,
+        onDismiss,
+        ...props
+    }: React.HTMLAttributes<HTMLDivElement> & { isOpen?: boolean; onDismiss?: () => void } & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => {
+    if (!isOpen) return null
+
+    return (
+        <div
+            ref={ref}
+            className={cn(
+                "fixed inset-0 bg-black/50 z-40 lg:hidden",
+                className
+            )}
+            onClick={onDismiss}
+            {...props}
+        />
+    )
+}
+
+const SidebarHeader = (
+    {
+        ref,
+        className,
+        ...props
+    }: React.HTMLAttributes<HTMLDivElement> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => (<div
+    ref={ref}
+    className={cn("flex items-center justify-between px-4 py-4 border-b border-border", className)}
+    {...props}
+/>)
+
+const SidebarContent = (
+    {
+        ref,
+        className,
+        ...props
+    }: React.HTMLAttributes<HTMLDivElement> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => (<div
+    ref={ref}
+    className={cn("flex-1 min-h-0 overflow-y-auto py-4 px-3", className)}
+    {...props}
+/>)
+
+const SidebarFooter = (
+    {
+        ref,
+        className,
+        ...props
+    }: React.HTMLAttributes<HTMLDivElement> & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => (<div
+    ref={ref}
+    className={cn("px-4 py-4 space-y-3", className)}
+    {...props}
+/>)
+
+interface SidebarItemProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    isActive?: boolean
+    icon?: React.ReactNode
+    showIcon?: boolean
+    depth?: number
+    hasChildren?: boolean
+    isExpanded?: boolean
+    asChild?: boolean
+}
+
+const SidebarItem = (
+    {
+        ref,
+        className,
+        isActive,
+        icon,
+        showIcon = true,
+        depth = 0,
+        hasChildren,
+        isExpanded,
+        children,
+        asChild = false,
+        ...props
+    }: SidebarItemProps & {
+        ref?: React.Ref<HTMLButtonElement>;
+    }
+) => {
+    const Comp = asChild ? Slot : "button"
+
+    return (
+        <Comp
+            ref={ref}
+            className={cn(
+                "w-full flex items-center gap-2 px-3 py-2 text-sm transition-colors rounded-md sage-interactive",
+                isActive
+                    ? "bg-primary text-primary-foreground font-medium"
+                    : "text-muted-foreground hover:text-foreground",
+                depth === 0 && !isActive ? "font-medium text-foreground" : "",
+                className
+            )}
+            style={{ paddingLeft: `${12 + depth * 16}px` }}
+            {...props}
+        >
+            {hasChildren && (
+                <svg
+                    className={cn(
+                        "w-4 h-4 flex-shrink-0 transition-transform",
+                        isExpanded ? "rotate-90" : ""
+                    )}
+                    fill="none"
+                    stroke="currentColor"
+                    viewBox="0 0 24 24"
+                >
+                    <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth={2}
+                        d="M9 5l7 7-7 7"
+                    />
+                </svg>
+            )}
+            {!hasChildren && depth > 0 && <span className="w-4 flex-shrink-0" />}
+            {showIcon && icon && <span className="flex-shrink-0">{icon}</span>}
+            <span className="flex-1 text-left truncate">{children}</span>
+        </Comp>
+    )
+}
+
+export {
+    Sidebar,
+    SidebarOverlay,
+    SidebarHeader,
+    SidebarContent,
+    SidebarFooter,
+    SidebarItem,
+}

package/src/components/layout/Stack.test.tsx

@@ -0,0 +1,41 @@
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect } from 'vitest'
+import { Stack } from './Stack'
+
+describe('Stack', () => {
+  it('renders children in a flex container', () => {
+    render(
+      <Stack>
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Stack>
+    )
+    expect(screen.getByText('Item 1')).toBeInTheDocument()
+    expect(screen.getByText('Item 2')).toBeInTheDocument()
+  })
+
+  it('defaults to column direction', () => {
+    const { container } = render(<Stack><div>Child</div></Stack>)
+    expect(container.firstChild).toHaveClass('flex-col')
+  })
+
+  it('renders row direction', () => {
+    const { container } = render(<Stack direction="row"><div>Child</div></Stack>)
+    expect(container.firstChild).toHaveClass('flex-row')
+  })
+
+  it('applies alignment', () => {
+    const { container } = render(<Stack align="center"><div>Child</div></Stack>)
+    expect(container.firstChild).toHaveClass('items-center')
+  })
+
+  it('applies justify', () => {
+    const { container } = render(<Stack justify="between"><div>Child</div></Stack>)
+    expect(container.firstChild).toHaveClass('justify-between')
+  })
+
+  it('applies custom className', () => {
+    const { container } = render(<Stack className="custom-stack"><div>Child</div></Stack>)
+    expect(container.firstChild).toHaveClass('custom-stack')
+  })
+})

package/src/components/layout/Stack.tsx

@@ -0,0 +1,89 @@
+import React from 'react';
+
+export interface StackProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Content to arrange
+     */
+    children: React.ReactNode;
+    /**
+     * Direction of flow
+     * @default 'column'
+     */
+    direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+    /**
+     * Spacing between items (scale: 0-12, or px values)
+     * Maps to Tailwind gap utility (e.g. 4 -> gap-4)
+     * @default 4
+     */
+    gap?: number;
+    /**
+     * Alignment on the cross axis (align-items)
+     */
+    align?: 'start' | 'end' | 'center' | 'baseline' | 'stretch';
+    /**
+     * Distribution on the main axis (justify-content)
+     */
+    justify?: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly';
+    /**
+     * Whether to allow wrapping (for row layouts)
+     */
+    wrap?: boolean;
+    /**
+     * HTML element to render as
+     * @default 'div'
+     */
+    as?: any;
+}
+
+export const Stack = (
+    {
+        ref,
+        children,
+        direction = 'column',
+        gap = 4,
+        align = 'stretch',
+        justify = 'start',
+        wrap = false,
+        as: Component = 'div',
+        className = '',
+        ...props
+    }: StackProps & {
+        ref?: React.Ref<HTMLDivElement>;
+    }
+) => {
+
+    const styles = {
+        direction: {
+            row: 'flex-row',
+            column: 'flex-col',
+            'row-reverse': 'flex-row-reverse',
+            'column-reverse': 'flex-col-reverse',
+        },
+        align: {
+            start: 'items-start',
+            end: 'items-end',
+            center: 'items-center',
+            baseline: 'items-baseline',
+            stretch: 'items-stretch',
+        },
+        justify: {
+            start: 'justify-start',
+            end: 'justify-end',
+            center: 'justify-center',
+            between: 'justify-between',
+            around: 'justify-around',
+            evenly: 'justify-evenly',
+        }
+    };
+
+    return (
+        <Component
+            ref={ref}
+            className={`flex ${styles.direction[direction]} ${styles.align[align]} ${styles.justify[justify]} ${wrap ? 'flex-wrap' : 'flex-nowrap'
+                } gap-${gap} ${className}`}
+            {...props}
+        >
+            {children}
+        </Component>
+    );
+};

package/src/components/layout/glass-surface.css

@@ -0,0 +1,60 @@
+/* ── GlassSurface — Liquid Glass ──
+   Apple macOS 26 glass materials: same blur, same base color,
+   five thickness tiers that differ only in background opacity.
+   12 percentage-point steps: 28 → 38 → 48 → 58 → 68.
+
+   `backface-visibility: hidden` forces a GPU compositing layer so
+   the effect renders identically across environments.
+*/
+
+/* ── tokens ── */
+:root {
+  --glass-border: rgba(255, 255, 255, 0.35);
+  --glass-shadow: 0 8px 32px rgba(0, 0, 0, 0.10);
+}
+.dark {
+  --glass-border: rgba(255, 255, 255, 0.10);
+  --glass-shadow: 0 8px 32px rgba(0, 0, 0, 0.30);
+}
+
+/* Resolve light/dark tint — component sets both inline, CSS picks the right one */
+.glass-surface { --glass-tint-rgb: var(--glass-tint-light, 200, 200, 200); }
+.dark .glass-surface { --glass-tint-rgb: var(--glass-tint-dark, 57, 57, 57); }
+
+/* ── base ── */
+/* backdrop-filter is applied inline in GlassSurface.tsx to prevent
+   Lightning CSS from stripping the standard property and mangling
+   the -webkit- prefix value in production builds. */
+.glass-surface {
+  -webkit-backface-visibility: hidden;
+  backface-visibility: hidden;
+  background: transparent;
+  transition:
+    background 0.3s ease,
+    box-shadow 0.3s ease,
+    border-color 0.3s ease;
+}
+
+/* ── thickness classes — opacity driven by tint color from component ── */
+.glass-surface--active                           { background: rgba(var(--glass-tint-rgb), 0.38); }
+.glass-surface--active.glass-surface--ultrathin  { background: rgba(var(--glass-tint-rgb), 0.28); }
+.glass-surface--active.glass-surface--thin       { background: rgba(var(--glass-tint-rgb), 0.38); }
+.glass-surface--active.glass-surface--medium     { background: rgba(var(--glass-tint-rgb), 0.48); }
+.glass-surface--active.glass-surface--thick      { background: rgba(var(--glass-tint-rgb), 0.58); }
+.glass-surface--active.glass-surface--ultrathick { background: rgba(var(--glass-tint-rgb), 0.68); }
+
+/* ── shadow + inset highlight ── */
+.glass-surface--active {
+  box-shadow: var(--glass-shadow), inset 0 1px 0 rgba(255, 255, 255, 0.40);
+}
+.dark .glass-surface--active {
+  box-shadow: var(--glass-shadow), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+
+/* ── position borders ── */
+.glass-surface--top.glass-surface--active {
+  border-bottom: 1px solid var(--glass-border);
+}
+.glass-surface--bottom.glass-surface--active {
+  border-top: 1px solid var(--glass-border);
+}