Code Usage

<ActivityCard
  activity={{
    pageId: "abc123",
    pageName: "Example Page",
    userId: "user123",
    username: "jamie",
    timestamp: "2024-01-15T10:30:00Z",
    currentContent: "...",
    previousContent: "...",
    diff: { added: 42, removed: 8, hasChanges: true }
  }}
  isCarousel={false}
  compactLayout={false}
/>

Step 1: Import and Initialize

import { useConfirmation } from '@/hooks/useConfirmation';
import { ConfirmationModal } from '@/components/utils/UnifiedModal';

// In your component:
const { confirmationState, confirm, closeConfirmation } = useConfirmation();

Step 2: Use confirm() (returns Promise<boolean>)

// Generic confirmation
const handleDelete = async () => {
  const confirmed = await confirm({
    title: "Delete Page?",
    message: "Are you sure you want to delete this page?",
    confirmText: "Delete",
    cancelText: "Cancel",
    variant: "destructive"  // or "warning" | "default"
  });

  if (confirmed) {
    // User clicked confirm
    await deletePage();
  }
};

// Convenience methods available:
const confirmed = await confirmDelete("this item");
const confirmed = await confirmLogout();
const confirmed = await confirmCancelSubscription();

Step 3: Render the Modal

// In your JSX (typically near the end of the component):
<ConfirmationModal
  isOpen={confirmationState.isOpen}
  onClose={closeConfirmation}
  onConfirm={confirmationState.onConfirm}
  title={confirmationState.title}
  message={confirmationState.message}
  confirmText={confirmationState.confirmText}
  cancelText={confirmationState.cancelText}
  type={confirmationState.variant}
/>

Component Usage

// UnifiedModal uses Dialog component internally (always centered)
// For alerts/confirmations, use UnifiedModal or its wrappers:

import { ConfirmationModal } from '@/components/utils/UnifiedModal';

<ConfirmationModal
  isOpen={true}
  onClose={handleClose}
  onConfirm={handleConfirm}
  title="Delete Page?"
  message="Are you sure?"
  type="destructive"
/>

// For complex forms/content, use Modal or AdaptiveModal instead

AnimatedStack (multiple items)

import { AnimatedStack, AnimatedStackItem } from '@/components/ui/AnimatedStack';

<AnimatedStack gap={12} preset="default">
  {items.map(item => (
    <AnimatedStackItem key={item.id}>
      <Card>{item.content}</Card>
    </AnimatedStackItem>
  ))}
</AnimatedStack>

AnimatedPresenceItem (single toggle)

import { AnimatedPresenceItem } from '@/components/ui/AnimatedStack';

<AnimatedPresenceItem
  show={showError}
  gap={12}
  preset="gentleSpring"
  gapPosition="top"
>
  <ErrorBanner message="Something went wrong" />
</AnimatedPresenceItem>

Direct Framer Motion usage

import { AnimatePresence, motion } from 'framer-motion';

<AnimatePresence>
  {show && (
    <motion.div
      initial={{ opacity: 0, height: 0, marginTop: 0 }}
      animate={{ opacity: 1, height: 'auto', marginTop: 12 }}
      exit={{ opacity: 0, height: 0, marginTop: 0 }}
      transition={{ duration: 0.2, ease: 'easeOut' }}
      className="overflow-hidden"
    >
      <Button>Animated Button</Button>
    </motion.div>
  )}
</AnimatePresence>

Import

import EmptyState from '@/components/ui/EmptyState';

Basic Usage

<EmptyState
  icon="Inbox"
  title="No messages"
  description="When you receive messages, they'll appear here."
/>

With Action Button

<EmptyState
  icon="FileText"
  title="No pages yet"
  description="Create your first page to get started."
  action={{
    label: "Create Page",
    onClick: () => handleCreate(),
    variant: 'outline' // optional
  }}
/>

Size Variants

// Small - for compact spaces
<EmptyState size="sm" icon="Tags" title="No tags" description="..." />

// Medium (default) - standard usage
<EmptyState size="md" icon="Inbox" title="No messages" description="..." />

// Large - for primary empty states
<EmptyState size="lg" icon="Folder" title="No projects" description="..." />

Error boundary usage

// In error.tsx or error boundary
import FullPageError from '@/components/ui/FullPageError';

export default function ErrorPage({
  error,
  reset
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <FullPageError
      error={error}
      reset={reset}
      title="Page Error"
      message="This page encountered an unexpected error."
      showGoBack={true}
      showGoHome={true}
      showTryAgain={true}
    />
  );
}

Import

import { InlineError } from '@/components/ui/InlineError';

Basic Usage

<InlineError
  message="Something went wrong. Please try again."
  variant="error"
  size="md"
/>

With Retry Action

<InlineError
  message="Failed to load page content."
  variant="error"
  size="md"
  onRetry={() => refetch()}
  retryLabel="Retry"
/>

With Error Details

<InlineError
  message="An unexpected error occurred."
  variant="error"
  size="lg"
  title="Request Failed"
  errorDetails="Error: 500 Internal Server Error\nRequest ID: abc-123-def"
  showCopy={true}
  showCollapsible={true}
  onRetry={() => retry()}
/>

Loading state usage

// Default loader (PulseLoader) - always use default style
<Icon name="Loader" size={24} />

// Size variants
<Icon name="Loader" size={16} />  // small
<Icon name="Loader" size={32} />  // large

// WRONG - never add animate-spin to Loader (it already animates)
// <Icon name="Loader" className="animate-spin" />

// WRONG - don't use Loader2, use Loader instead
// <Icon name="Loader2" className="animate-spin" />

// Bordered loading state (matches EmptyState style)
<LoadingState
  message="Loading content..."
  showBorder
  size="md"
  minHeight="h-32"
/>

// Skeleton placeholders
<SkeletonLine width="w-3/4" />
<SkeletonCard />

Basic Usage

<NotificationItem
  notification={{
    id: "notif-123",
    type: "link",
    sourceUserId: "user-456",
    targetPageTitle: "My Page",
    sourcePageTitle: "Their Page",
    createdAt: "2024-01-15T10:30:00Z",
    read: false,
  }}
/>

Import

import { PageHeader } from '@/components/ui/PageHeader';

Page Structure (always wrap in NavPageLayout)

import NavPageLayout from '@/components/layout/NavPageLayout';
import { PageHeader } from '@/components/ui/PageHeader';

export default function MyPage() {
  return (
    <NavPageLayout>
      <PageHeader title="My Page" />
      {/* page content */}
    </NavPageLayout>
  );
}

With Description

<PageHeader
  title="Recently Viewed"
  description="Pages you've viewed recently"
/>

With Back Button

// Uses router.back()
<PageHeader title="Settings" backHref={true} />

// Navigates to specific URL
<PageHeader title="Settings" backHref="/groups" />

With Actions and Children

<PageHeader
  title="Random Pages"
  actions={<Button>Shuffle</Button>}
>
  <div className="mt-4">
    {/* Additional content below the header */}
  </div>
</PageHeader>

import { UnifiedPageList, PageListViewToggle, ListMetadataSelector } from '@/components/pages/UnifiedPageList';
import type { PageItem, PageListView, ListMetadata } from '@/components/pages/UnifiedPageList';

// Basic usage — wrapped PillLinks (default)
<UnifiedPageList pages={pages} />

// With view toggle (controlled)
const [view, setView] = useState<PageListView>('wrapped');
const [metadata, setMetadata] = useState<ListMetadata>('none');
<PageListViewToggle view={view} onViewChange={setView} />
{view === 'list' && <ListMetadataSelector metadata={metadata} onMetadataChange={setMetadata} />}
<UnifiedPageList pages={pages} view={view} onViewChange={setView} listMetadata={metadata} onListMetadataChange={setMetadata} />

// With built-in view toggle
<UnifiedPageList pages={pages} showViewToggle />

// Show owned pages (private titles visible)
<UnifiedPageList pages={pages} isOwned={true} />

// Custom empty state props
<UnifiedPageList pages={[]} emptyIcon="PenLine" emptyTitle="No writing yet" emptyDescription="Create your first page!" />

// List view with specific metadata
<UnifiedPageList pages={pages} view="list" listMetadata="author" />

// List view with item actions
<UnifiedPageList
  pages={pages}
  view="list"
  renderItemAction={(page) => <Button size="sm">Edit</Button>}
/>