Components API Reference

Complete reference for all React components in the Sofondo Framework.

Installation

npm install @sofondo/react @sofondo/styles

Usage

Import components from @sofondo/react:

import { PageHeader, DataGrid, StatCard } from '@sofondo/react';

Layout Components

<PageHeader />

Page header with breadcrumbs, title, subtitle, and actions.

Props:

interface PageHeaderProps {
  breadcrumbs?: BreadcrumbItem[];
  title: string;
  subtitle?: ReactNode;
  actions?: ReactNode;
}

Example:

<PageHeader
  title="Dashboard"
  subtitle="Welcome back!"
  actions={<button>New Item</button>}
/>

<BaseSidebar />

Framework-agnostic sidebar component.

Props:

interface BaseSidebarProps {
  isCollapsed: boolean;
  toggleSidebar: () => void;
  menuItems: MenuItem[];
  navigationAdapter: NavigationAdapter;
  tooltipOffsetX?: number;
  tooltipOffsetY?: number;
}

<BaseHeader />

Framework-agnostic header component.

Props:

interface BaseHeaderProps {
  user?: {
    name: string;
    email?: string;
    avatar?: string;
  };
  navigationAdapter: NavigationAdapter;
}

<BaseAdminLayout />

Complete admin layout with sidebar and header.

Props:

interface BaseAdminLayoutProps {
  children: ReactNode;
  menuItems: MenuItem[];
  user?: UserInfo;
  navigationAdapter: NavigationAdapter;
}

UI Components

<ProgressBar />

Horizontal progress indicator.

Props:

interface ProgressBarProps {
  value: number;          // Current value
  max: number;            // Maximum value
  height?: number;        // Height in pixels (default: 6)
  color?: string;         // Fill color
}

Example:

<ProgressBar value={45} max={100} height={8} color="#0066cc" />

<Skeleton />

Loading skeleton placeholder.

Props:

interface SkeletonProps {
  width?: number | string;
  height?: number | string;
  variant?: 'text' | 'circular' | 'rounded' | 'rectangular';
  style?: React.CSSProperties;
}

Example:

<Skeleton width={200} height={20} />
<Skeleton variant="circular" width={40} height={40} />

<DataGrid />

Flexible data table component.

Props:

interface DataGridProps<T> {
  data: T[];
  columns: Column<T>[];
  keyField: keyof T;
}

interface Column<T> {
  key: keyof T;
  header: string;
  width?: string;
  align?: 'left' | 'center' | 'right';
  render?: (item: T) => ReactNode;
}

Example:

<DataGrid
  data={users}
  keyField="id"
  columns={[
    { key: 'name', header: 'Name', width: '2fr' },
    { key: 'email', header: 'Email', width: '2fr' },
    { key: 'role', header: 'Role', width: '1fr' },
  ]}
/>

<Toast />

Toast notification component.

Props:

interface ToastProps {
  id: string;
  message: string;
  type?: 'info' | 'success' | 'warning' | 'error';
  duration?: number;
  onClose: (id: string) => void;
}

<StatCard />

Statistics card for dashboard metrics.

Props:

interface StatCardProps {
  icon: LucideIcon;
  label: string;
  value: string | number;
  change?: string;
  changeClassName?: 'positive' | 'warning' | 'negative';
  children?: ReactNode;
  animate?: boolean;
}

Example:

<StatCard
  icon={Users}
  label="Total Users"
  value="1,234"
  change="+12% this month"
  changeClassName="positive"
/>

<StatGrid />

Grid container for stat cards.

Props:

interface StatGridProps {
  children: ReactNode;
  animate?: boolean;
}

<Card />

Generic card container.

Props:

interface CardProps {
  children: ReactNode;
  className?: string;
  style?: React.CSSProperties;
}

<Breadcrumb />

Breadcrumb navigation.

Props:

interface BreadcrumbProps {
  items: BreadcrumbItem[];
}

interface BreadcrumbItem {
  icon?: LucideIcon;
  label: string;
  href?: string;
}

<CustomScrollbar />

Custom styled scrollbar.

Props:

interface CustomScrollbarProps {
  container: HTMLElement | null;
  className?: string;
}

<ContextPanel />

Contextual information panel.

Props:

interface ContextPanelProps {
  title: string;
  children: ReactNode;
  isOpen: boolean;
  onClose: () => void;
}

<TableOfContents />

Automatically tracks and displays page headings with smooth scrolling navigation. Features include:

• Highlights the currently visible section as user scrolls
• Auto-scrolls the TOC to keep active items visible
• Smooth scrolling to sections when clicked
• Accounts for sticky headers during scroll
• Supports nested heading levels (h2, h3, etc.)

Props:

interface TableOfContentsProps {
  headings: TocHeading[];
  title?: string;  // Default: "On This Page"
  className?: string;
}

interface TocHeading {
  id: string;    // The heading's DOM id
  text: string;  // Display text
  level: number; // Heading level (2 for h2, 3 for h3, etc.)
}

Example:

import TableOfContents from '@sofondo/react';

const headings = [
  { id: 'introduction', text: 'Introduction', level: 2 },
  { id: 'getting-started', text: 'Getting Started', level: 2 },
  { id: 'installation', text: 'Installation', level: 3 },
  { id: 'configuration', text: 'Configuration', level: 3 },
  { id: 'usage', text: 'Usage', level: 2 }
];

<TableOfContents
  headings={headings}
  title="On This Page"
/>

Framework Integration:

For Astro:

// Extract headings from Astro content collections
const { Content, headings } = await doc.render();

const tocHeadings = headings
  .filter(h => h.depth === 2 || h.depth === 3)
  .map(h => ({
    id: h.slug,
    text: h.text,
    level: h.depth
  }));

<TableOfContents headings={tocHeadings} />