@papernote/ui 1.10.12 → 1.10.13

package/src/components/SuccessCheck.stories.tsx

@@ -0,0 +1,233 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { SuccessCheck } from './SuccessCheck';
+import { Button } from './Button';
+import { Stack } from './Stack';
+import { Text } from './Text';
+
+const meta: Meta<typeof SuccessCheck> = {
+  title: 'Feedback/SuccessCheck',
+  component: SuccessCheck,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'An animated checkmark for completed actions. Features SVG stroke animation with configurable size, color, and delay. Respects prefers-reduced-motion for accessibility.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Size of the checkmark',
+    },
+    color: {
+      control: 'color',
+      description: 'Color of the checkmark',
+    },
+    delay: {
+      control: { type: 'number', min: 0, max: 2000, step: 100 },
+      description: 'Delay in ms before animation starts',
+    },
+    enabled: {
+      control: 'boolean',
+      description: 'Whether animations are enabled',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof SuccessCheck>;
+
+// Basic example
+export const Default: Story = {
+  args: {
+    size: 'md',
+  },
+};
+
+// All sizes
+export const Sizes: Story = {
+  render: () => (
+    <Stack direction="horizontal" gap="lg" align="center">
+      <Stack align="center" gap="sm">
+        <SuccessCheck size="sm" />
+        <Text size="sm" className="text-ink-500">Small</Text>
+      </Stack>
+      <Stack align="center" gap="sm">
+        <SuccessCheck size="md" />
+        <Text size="sm" className="text-ink-500">Medium</Text>
+      </Stack>
+      <Stack align="center" gap="sm">
+        <SuccessCheck size="lg" />
+        <Text size="sm" className="text-ink-500">Large</Text>
+      </Stack>
+    </Stack>
+  ),
+};
+
+// Custom colors
+export const CustomColors: Story = {
+  render: () => (
+    <Stack direction="horizontal" gap="lg" align="center">
+      <Stack align="center" gap="sm">
+        <SuccessCheck color="#10b981" />
+        <Text size="sm" className="text-ink-500">Success</Text>
+      </Stack>
+      <Stack align="center" gap="sm">
+        <SuccessCheck color="#3b82f6" />
+        <Text size="sm" className="text-ink-500">Blue</Text>
+      </Stack>
+      <Stack align="center" gap="sm">
+        <SuccessCheck color="#8b5cf6" />
+        <Text size="sm" className="text-ink-500">Purple</Text>
+      </Stack>
+      <Stack align="center" gap="sm">
+        <SuccessCheck color="#f59e0b" />
+        <Text size="sm" className="text-ink-500">Amber</Text>
+      </Stack>
+    </Stack>
+  ),
+};
+
+// With delay
+export const WithDelay: Story = {
+  render: () => (
+    <Stack direction="horizontal" gap="lg" align="center">
+      <Stack align="center" gap="sm">
+        <SuccessCheck delay={0} />
+        <Text size="sm" className="text-ink-500">No delay</Text>
+      </Stack>
+      <Stack align="center" gap="sm">
+        <SuccessCheck delay={500} />
+        <Text size="sm" className="text-ink-500">500ms</Text>
+      </Stack>
+      <Stack align="center" gap="sm">
+        <SuccessCheck delay={1000} />
+        <Text size="sm" className="text-ink-500">1000ms</Text>
+      </Stack>
+    </Stack>
+  ),
+};
+
+// Interactive demo with trigger
+export const Interactive: Story = {
+  render: function InteractiveDemo() {
+    const [key, setKey] = useState(0);
+    const [completed, setCompleted] = useState(false);
+
+    const triggerAnimation = () => {
+      setCompleted(false);
+      setKey(prev => prev + 1);
+    };
+
+    return (
+      <Stack align="center" gap="lg">
+        <div className="w-24 h-24 flex items-center justify-center bg-paper-100 rounded-xl">
+          <SuccessCheck 
+            key={key} 
+            size="lg" 
+            onComplete={() => setCompleted(true)} 
+          />
+        </div>
+        <Stack align="center" gap="sm">
+          <Button onClick={triggerAnimation} variant="primary">
+            Replay Animation
+          </Button>
+          <Text size="sm" className="text-ink-500">
+            {completed ? 'Animation complete!' : 'Animating...'}
+          </Text>
+        </Stack>
+      </Stack>
+    );
+  },
+};
+
+// Static (no animation)
+export const Static: Story = {
+  args: {
+    enabled: false,
+    size: 'lg',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'When `enabled` is false, the checkmark appears immediately without animation. This also happens automatically when the user prefers reduced motion.',
+      },
+    },
+  },
+};
+
+// In context - Task completion
+export const TaskCompletion: Story = {
+  render: function TaskCompletionDemo() {
+    const [isComplete, setIsComplete] = useState(false);
+
+    return (
+      <div className="p-6 bg-white rounded-xl shadow-card border border-paper-200 w-80">
+        <Stack gap="md">
+          <Stack direction="horizontal" justify="between" align="center">
+            <Text weight="semibold">Complete your profile</Text>
+            {isComplete && <SuccessCheck size="sm" />}
+          </Stack>
+          
+          <Stack gap="xs">
+            <Stack direction="horizontal" gap="sm" align="center">
+              <SuccessCheck size="sm" />
+              <Text size="sm" className="text-ink-600">Add profile photo</Text>
+            </Stack>
+            <Stack direction="horizontal" gap="sm" align="center">
+              <SuccessCheck size="sm" />
+              <Text size="sm" className="text-ink-600">Verify email address</Text>
+            </Stack>
+            <Stack direction="horizontal" gap="sm" align="center">
+              {isComplete ? (
+                <SuccessCheck size="sm" />
+              ) : (
+                <div className="w-6 h-6 rounded-full border-2 border-paper-300" />
+              )}
+              <Text size="sm" className={isComplete ? 'text-ink-600' : 'text-ink-400'}>
+                Set up payment method
+              </Text>
+            </Stack>
+          </Stack>
+
+          {!isComplete && (
+            <Button 
+              onClick={() => setIsComplete(true)} 
+              variant="primary" 
+              size="sm"
+              className="w-full"
+            >
+              Mark Complete
+            </Button>
+          )}
+        </Stack>
+      </div>
+    );
+  },
+};
+
+// Staggered animation
+export const Staggered: Story = {
+  render: function StaggeredDemo() {
+    const [key, setKey] = useState(0);
+
+    return (
+      <Stack align="center" gap="lg">
+        <Stack direction="horizontal" gap="md" align="center">
+          <SuccessCheck key={`${key}-1`} delay={0} />
+          <SuccessCheck key={`${key}-2`} delay={200} />
+          <SuccessCheck key={`${key}-3`} delay={400} />
+          <SuccessCheck key={`${key}-4`} delay={600} />
+          <SuccessCheck key={`${key}-5`} delay={800} />
+        </Stack>
+        <Button onClick={() => setKey(k => k + 1)} variant="secondary">
+          Replay Staggered
+        </Button>
+      </Stack>
+    );
+  },
+};

package/src/components/SuccessCheck.tsx

@@ -0,0 +1,214 @@
+import { useEffect, useState, useRef } from 'react';
+
+export interface SuccessCheckProps {
+  /** Size of the checkmark */
+  size?: 'sm' | 'md' | 'lg';
+  /** Color of the checkmark (defaults to success green) */
+  color?: string;
+  /** Delay in ms before animation starts */
+  delay?: number;
+  /** Callback when animation completes */
+  onComplete?: () => void;
+  /** Additional CSS classes */
+  className?: string;
+  /** Whether the animation is enabled (respects prefers-reduced-motion) */
+  enabled?: boolean;
+}
+
+const sizeStyles = {
+  sm: { size: 24, strokeWidth: 3 },
+  md: { size: 32, strokeWidth: 3 },
+  lg: { size: 48, strokeWidth: 4 },
+};
+
+/**
+ * SuccessCheck - An animated checkmark for completed actions.
+ * 
+ * Features:
+ * - SVG checkmark with stroke animation
+ * - Configurable size and color
+ * - Optional delay before animation
+ * - Respects prefers-reduced-motion
+ * - Callback on animation complete
+ */
+export function SuccessCheck({
+  size = 'md',
+  color,
+  delay = 0,
+  onComplete,
+  className = '',
+  enabled = true,
+}: SuccessCheckProps) {
+  const [isAnimating, setIsAnimating] = useState(false);
+  const [showCheck, setShowCheck] = useState(false);
+  const timeoutRef = useRef<number | null>(null);
+  const animationTimeoutRef = useRef<number | null>(null);
+
+  const { size: dimensions, strokeWidth } = sizeStyles[size];
+  const checkColor = color || '#10b981'; // success-500
+
+  // Check for reduced motion preference
+  const prefersReducedMotion = 
+    typeof window !== 'undefined' && 
+    window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+  useEffect(() => {
+    if (!enabled) {
+      setShowCheck(true);
+      return;
+    }
+
+    // Start animation after delay
+    timeoutRef.current = window.setTimeout(() => {
+      setShowCheck(true);
+      setIsAnimating(true);
+
+      // Animation duration is 0.6s for the draw + 0.3s for the scale
+      const animationDuration = prefersReducedMotion ? 0 : 900;
+      
+      animationTimeoutRef.current = window.setTimeout(() => {
+        setIsAnimating(false);
+        onComplete?.();
+      }, animationDuration);
+    }, delay);
+
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+      if (animationTimeoutRef.current) {
+        clearTimeout(animationTimeoutRef.current);
+      }
+    };
+  }, [delay, enabled, onComplete, prefersReducedMotion]);
+
+  if (!showCheck) {
+    return (
+      <div
+        className={`inline-flex items-center justify-center ${className}`}
+        style={{ width: dimensions, height: dimensions }}
+        role="status"
+        aria-label="Loading"
+      />
+    );
+  }
+
+  // For reduced motion, show static checkmark
+  if (prefersReducedMotion || !enabled) {
+    return (
+      <div
+        className={`inline-flex items-center justify-center ${className}`}
+        style={{ width: dimensions, height: dimensions }}
+        role="status"
+        aria-label="Success"
+      >
+        <svg
+          width={dimensions}
+          height={dimensions}
+          viewBox="0 0 24 24"
+          fill="none"
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <circle
+            cx="12"
+            cy="12"
+            r="10"
+            stroke={checkColor}
+            strokeWidth={strokeWidth * 0.8}
+            fill="none"
+            opacity={0.2}
+          />
+          <path
+            d="M7 12.5L10.5 16L17 9"
+            stroke={checkColor}
+            strokeWidth={strokeWidth}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
+      </div>
+    );
+  }
+
+  // Animated version
+  // The checkmark path length for the animation
+  const pathLength = 20; // Approximate length of the check path
+
+  return (
+    <div
+      className={`inline-flex items-center justify-center ${className}`}
+      style={{ width: dimensions, height: dimensions }}
+      role="status"
+      aria-label="Success"
+    >
+      <svg
+        width={dimensions}
+        height={dimensions}
+        viewBox="0 0 24 24"
+        fill="none"
+        xmlns="http://www.w3.org/2000/svg"
+        className={isAnimating ? 'animate-success-check' : ''}
+      >
+        {/* Background circle */}
+        <circle
+          cx="12"
+          cy="12"
+          r="10"
+          stroke={checkColor}
+          strokeWidth={strokeWidth * 0.8}
+          fill="none"
+          opacity={0.2}
+          className="origin-center"
+          style={{
+            animation: isAnimating ? 'successCircle 0.4s ease-out forwards' : 'none',
+          }}
+        />
+        
+        {/* Checkmark path with stroke animation */}
+        <path
+          d="M7 12.5L10.5 16L17 9"
+          stroke={checkColor}
+          strokeWidth={strokeWidth}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          style={{
+            strokeDasharray: pathLength,
+            strokeDashoffset: isAnimating ? 0 : pathLength,
+            animation: isAnimating 
+              ? `successDraw 0.4s 0.2s ease-out forwards` 
+              : 'none',
+          }}
+        />
+      </svg>
+      
+      {/* Inject keyframes for the animations */}
+      <style>{`
+        @keyframes successDraw {
+          0% {
+            stroke-dashoffset: ${pathLength};
+          }
+          100% {
+            stroke-dashoffset: 0;
+          }
+        }
+        
+        @keyframes successCircle {
+          0% {
+            transform: scale(0);
+            opacity: 0;
+          }
+          50% {
+            transform: scale(1.1);
+            opacity: 0.3;
+          }
+          100% {
+            transform: scale(1);
+            opacity: 0.2;
+          }
+        }
+      `}</style>
+    </div>
+  );
+}
+
+export default SuccessCheck;

package/src/components/index.ts

@@ -69,6 +69,44 @@ export { Celebration, useCelebration } from './Celebration';
 export type { CelebrationProps } from './Celebration';
 export type { CardProps } from './Card';
 
+// Delighter Components (PAP-12)
+export { SuccessCheck } from './SuccessCheck';
+export type { SuccessCheckProps } from './SuccessCheck';
+
+export { MotivationalMessage } from './MotivationalMessage';
+export type { MotivationalMessageProps } from './MotivationalMessage';
+
+export { StreakBadge } from './StreakBadge';
+export type { StreakBadgeProps } from './StreakBadge';
+
+export { AchievementBadge } from './AchievementBadge';
+export type { AchievementBadgeProps, AchievementBadgeData } from './AchievementBadge';
+
+export { ProgressCelebration } from './ProgressCelebration';
+export type { ProgressCelebrationProps } from './ProgressCelebration';
+
+export { AchievementUnlock } from './AchievementUnlock';
+export type { AchievementUnlockProps } from './AchievementUnlock';
+
+export { useDelighters } from '../hooks/useDelighters';
+export type { UseDelightersReturn, CelebrationType, CelebrationOptions } from '../hooks/useDelighters';
+
+// Collaboration Components (PAP-11)
+export { CollaboratorAvatars } from './CollaboratorAvatars';
+export type { CollaboratorAvatarsProps, Collaborator } from './CollaboratorAvatars';
+
+export { PermissionBadge } from './PermissionBadge';
+export type { PermissionBadgeProps, PermissionLevel } from './PermissionBadge';
+
+export { SharedBadge } from './SharedBadge';
+export type { SharedBadgeProps } from './SharedBadge';
+
+export { ActivityFeed } from './ActivityFeed';
+export type { ActivityFeedProps, ActivityItem } from './ActivityFeed';
+
+export { InviteCard } from './InviteCard';
+export type { InviteCardProps, PendingInvite } from './InviteCard';
+
 export { default as Stack } from './Stack';
 export type { StackProps } from './Stack';
 

package/src/hooks/useDelighters.ts

@@ -0,0 +1,133 @@
+import { useState, useCallback, useEffect } from 'react';
+import { useCelebration } from '../components/Celebration';
+import type { AchievementBadgeData } from '../components/AchievementBadge';
+
+export type CelebrationType = 'confetti' | 'fireworks' | 'stars';
+
+export interface CelebrationOptions {
+  /** Duration of the celebration in ms */
+  duration?: number;
+  /** Number of particles */
+  particleCount?: number;
+  /** Custom colors for the celebration */
+  colors?: string[];
+  /** Origin point (x, y in 0-1 range) */
+  origin?: { x: number; y: number };
+}
+
+export interface UseDelightersReturn {
+  /** Trigger a celebration animation */
+  celebrate: (type: CelebrationType, options?: CelebrationOptions) => void;
+  /** Show an achievement unlock (returns a function to trigger the achievement modal) */
+  showAchievement: (badge: AchievementBadgeData) => void;
+  /** Whether delighters are globally enabled */
+  enabled: boolean;
+  /** Set the global enabled state */
+  setEnabled: (enabled: boolean) => void;
+  /** The currently pending achievement (for rendering AchievementUnlock) */
+  pendingAchievement: AchievementBadgeData | null;
+  /** Clear the pending achievement */
+  clearAchievement: () => void;
+}
+
+const STORAGE_KEY = 'notebook-ui-delighters-enabled';
+
+/**
+ * useDelighters - Global control hook for celebration effects.
+ * 
+ * Features:
+ * - Wraps useCelebration for consistent celebration API
+ * - Global enabled/disabled state with localStorage persistence
+ * - Respects prefers-reduced-motion automatically
+ * - Provides showAchievement for achievement unlock modals
+ * 
+ * Usage:
+ * ```tsx
+ * const { celebrate, showAchievement, enabled, setEnabled } = useDelighters();
+ * 
+ * // Trigger a celebration
+ * celebrate('confetti', { particleCount: 100 });
+ * 
+ * // Show an achievement
+ * showAchievement({ icon: <Trophy />, name: 'Budget Master', description: '...' });
+ * 
+ * // Toggle celebrations globally
+ * setEnabled(false);
+ * ```
+ */
+export function useDelighters(): UseDelightersReturn {
+  const { celebrate: baseCelebrate } = useCelebration();
+  const [pendingAchievement, setPendingAchievement] = useState<AchievementBadgeData | null>(null);
+  
+  // Initialize enabled state from localStorage
+  const [enabled, setEnabledState] = useState<boolean>(() => {
+    if (typeof window === 'undefined') return true;
+    const stored = localStorage.getItem(STORAGE_KEY);
+    return stored === null ? true : stored === 'true';
+  });
+
+  // Check for reduced motion preference
+  const prefersReducedMotion = 
+    typeof window !== 'undefined' && 
+    window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+  // Persist enabled state to localStorage
+  const setEnabled = useCallback((newEnabled: boolean) => {
+    setEnabledState(newEnabled);
+    if (typeof window !== 'undefined') {
+      localStorage.setItem(STORAGE_KEY, String(newEnabled));
+    }
+  }, []);
+
+  // Sync with system preference changes
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const handleChange = (e: MediaQueryListEvent) => {
+      if (e.matches) {
+        // System now prefers reduced motion, but don't change user's preference
+        // Just let the celebrate function respect it
+      }
+    };
+
+    mediaQuery.addEventListener('change', handleChange);
+    return () => mediaQuery.removeEventListener('change', handleChange);
+  }, []);
+
+  const celebrate = useCallback((type: CelebrationType, options?: CelebrationOptions) => {
+    // Skip if disabled or prefers reduced motion
+    if (!enabled || prefersReducedMotion) return;
+
+    baseCelebrate({
+      type,
+      duration: options?.duration,
+      particleCount: options?.particleCount,
+      colors: options?.colors,
+      origin: options?.origin,
+    });
+  }, [enabled, prefersReducedMotion, baseCelebrate]);
+
+  const showAchievement = useCallback((badge: AchievementBadgeData) => {
+    // Always show achievement (unless disabled), even with reduced motion
+    // The modal itself will handle reduced motion for its animations
+    if (!enabled) return;
+    
+    setPendingAchievement(badge);
+  }, [enabled]);
+
+  const clearAchievement = useCallback(() => {
+    setPendingAchievement(null);
+  }, []);
+
+  return {
+    celebrate,
+    showAchievement,
+    enabled,
+    setEnabled,
+    pendingAchievement,
+    clearAchievement,
+  };
+}
+
+export default useDelighters;