@papernote/ui 1.3.1 → 1.6.0

package/src/components/PullToRefresh.stories.tsx

@@ -0,0 +1,321 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { RefreshCw } from 'lucide-react';
+import PullToRefresh from './PullToRefresh';
+
+const meta: Meta<typeof PullToRefresh> = {
+  title: 'Mobile/PullToRefresh',
+  component: PullToRefresh,
+  parameters: {
+    layout: 'fullscreen',
+    viewport: {
+      defaultViewport: 'mobile1',
+    },
+    docs: {
+      description: {
+        component: 'Native-feeling pull-to-refresh gesture handler for mobile content. Only activates when scrolled to top.',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof PullToRefresh>;
+
+// Helper component for interactive stories
+const RefreshableList = ({ 
+  itemCount = 10, 
+  pullThreshold = 80,
+  maxPull = 120,
+  disabled = false,
+}: { 
+  itemCount?: number;
+  pullThreshold?: number;
+  maxPull?: number;
+  disabled?: boolean;
+}) => {
+  const [items, setItems] = useState(() => 
+    Array.from({ length: itemCount }, (_, i) => ({
+      id: i + 1,
+      title: `Item ${i + 1}`,
+      timestamp: new Date().toLocaleTimeString(),
+    }))
+  );
+  const [refreshCount, setRefreshCount] = useState(0);
+
+  const handleRefresh = async () => {
+    // Simulate API call
+    await new Promise(resolve => setTimeout(resolve, 1500));
+    
+    setRefreshCount(prev => prev + 1);
+    setItems(prev => [
+      {
+        id: Date.now(),
+        title: `New Item (Refresh #${refreshCount + 1})`,
+        timestamp: new Date().toLocaleTimeString(),
+      },
+      ...prev,
+    ]);
+  };
+
+  return (
+    <PullToRefresh 
+      onRefresh={handleRefresh}
+      pullThreshold={pullThreshold}
+      maxPull={maxPull}
+      disabled={disabled}
+      className="h-screen"
+    >
+      <div style={{ padding: '16px', background: '#f5f5f4', minHeight: '100vh' }}>
+        <div style={{ 
+          padding: '12px 16px', 
+          background: '#fef3c7', 
+          borderRadius: '8px', 
+          marginBottom: '16px',
+          fontSize: '14px',
+        }}>
+          <strong>Pull down to refresh</strong>
+          <p style={{ color: '#666', marginTop: '4px' }}>
+            Refreshed {refreshCount} times. Items: {items.length}
+          </p>
+        </div>
+        
+        {items.map((item) => (
+          <div 
+            key={item.id} 
+            style={{ 
+              padding: '16px', 
+              margin: '8px 0', 
+              background: 'white', 
+              borderRadius: '8px',
+              boxShadow: '0 1px 3px rgba(0,0,0,0.1)',
+            }}
+          >
+            <div style={{ fontWeight: '500' }}>{item.title}</div>
+            <div style={{ fontSize: '12px', color: '#666', marginTop: '4px' }}>
+              Added at {item.timestamp}
+            </div>
+          </div>
+        ))}
+      </div>
+    </PullToRefresh>
+  );
+};
+
+export const Default: Story = {
+  render: () => <RefreshableList />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Pull down from the top to trigger a refresh. The spinner appears after pulling past the threshold.',
+      },
+    },
+  },
+};
+
+export const LowThreshold: Story = {
+  render: () => <RefreshableList pullThreshold={50} maxPull={80} />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Lower threshold (50px) makes it easier to trigger refresh.',
+      },
+    },
+  },
+};
+
+export const HighThreshold: Story = {
+  render: () => <RefreshableList pullThreshold={120} maxPull={180} />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Higher threshold (120px) requires more pull distance to trigger refresh.',
+      },
+    },
+  },
+};
+
+export const Disabled: Story = {
+  render: () => <RefreshableList disabled />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Pull-to-refresh can be disabled when not needed.',
+      },
+    },
+  },
+};
+
+export const CustomIndicator: Story = {
+  render: () => {
+    const [items, setItems] = useState(
+      Array.from({ length: 5 }, (_, i) => `Item ${i + 1}`)
+    );
+
+    const handleRefresh = async () => {
+      await new Promise(resolve => setTimeout(resolve, 1000));
+      setItems(prev => [`New Item ${Date.now()}`, ...prev]);
+    };
+
+    return (
+      <PullToRefresh
+        onRefresh={handleRefresh}
+        loadingIndicator={
+          <RefreshCw className="h-6 w-6 text-green-600 animate-spin" />
+        }
+        pullIndicator={
+          <RefreshCw className="h-6 w-6 text-gray-400" />
+        }
+        className="h-screen"
+      >
+        <div style={{ padding: '16px', background: '#f5f5f4', minHeight: '100vh' }}>
+          <div style={{ 
+            padding: '12px 16px', 
+            background: '#dcfce7', 
+            borderRadius: '8px', 
+            marginBottom: '16px',
+          }}>
+            Custom refresh indicator (green spinner)
+          </div>
+          {items.map((item, i) => (
+            <div 
+              key={i} 
+              style={{ 
+                padding: '16px', 
+                margin: '8px 0', 
+                background: 'white', 
+                borderRadius: '8px' 
+              }}
+            >
+              {item}
+            </div>
+          ))}
+        </div>
+      </PullToRefresh>
+    );
+  },
+};
+
+export const WithLongContent: Story = {
+  render: () => <RefreshableList itemCount={30} />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'With long scrollable content. Pull-to-refresh only activates when scrolled to the very top.',
+      },
+    },
+  },
+};
+
+export const EmptyState: Story = {
+  render: () => {
+    const [items, setItems] = useState<string[]>([]);
+    const [loading, setLoading] = useState(false);
+
+    const handleRefresh = async () => {
+      setLoading(true);
+      await new Promise(resolve => setTimeout(resolve, 1500));
+      setItems(['Fetched Item 1', 'Fetched Item 2', 'Fetched Item 3']);
+      setLoading(false);
+    };
+
+    return (
+      <PullToRefresh onRefresh={handleRefresh} className="h-screen">
+        <div style={{ 
+          padding: '16px', 
+          background: '#f5f5f4', 
+          minHeight: '100vh',
+          display: 'flex',
+          flexDirection: 'column',
+        }}>
+          {items.length === 0 ? (
+            <div style={{ 
+              flex: 1,
+              display: 'flex',
+              flexDirection: 'column',
+              alignItems: 'center',
+              justifyContent: 'center',
+              color: '#666',
+            }}>
+              <RefreshCw className="h-12 w-12 mb-4 text-gray-300" />
+              <p style={{ fontWeight: '500' }}>No items yet</p>
+              <p style={{ fontSize: '14px' }}>Pull down to load items</p>
+            </div>
+          ) : (
+            items.map((item, i) => (
+              <div 
+                key={i} 
+                style={{ 
+                  padding: '16px', 
+                  margin: '8px 0', 
+                  background: 'white', 
+                  borderRadius: '8px' 
+                }}
+              >
+                {item}
+              </div>
+            ))
+          )}
+        </div>
+      </PullToRefresh>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Pull-to-refresh works well with empty states to load initial data.',
+      },
+    },
+  },
+};
+
+export const MobileInstructions: Story = {
+  render: () => (
+    <div style={{ padding: '24px', background: '#f5f5f4', minHeight: '100vh' }}>
+      <h2 style={{ fontSize: '20px', fontWeight: 'bold', marginBottom: '16px' }}>
+        Pull to Refresh Component
+      </h2>
+      
+      <div style={{ background: 'white', padding: '16px', borderRadius: '8px', marginBottom: '16px' }}>
+        <h3 style={{ fontWeight: '600', marginBottom: '8px' }}>Usage</h3>
+        <pre style={{ 
+          background: '#f1f5f9', 
+          padding: '12px', 
+          borderRadius: '4px', 
+          fontSize: '12px',
+          overflow: 'auto',
+        }}>
+{`<PullToRefresh
+  onRefresh={async () => {
+    await fetchLatestData();
+  }}
+  pullThreshold={80}
+  maxPull={120}
+>
+  {content}
+</PullToRefresh>`}
+        </pre>
+      </div>
+
+      <div style={{ background: 'white', padding: '16px', borderRadius: '8px', marginBottom: '16px' }}>
+        <h3 style={{ fontWeight: '600', marginBottom: '8px' }}>Props</h3>
+        <ul style={{ fontSize: '14px', lineHeight: '1.6' }}>
+          <li><strong>onRefresh</strong>: Async function called on refresh</li>
+          <li><strong>pullThreshold</strong>: Distance to trigger (default: 80px)</li>
+          <li><strong>maxPull</strong>: Maximum pull distance (default: 120px)</li>
+          <li><strong>disabled</strong>: Disable pull-to-refresh</li>
+          <li><strong>loadingIndicator</strong>: Custom loading spinner</li>
+          <li><strong>pullIndicator</strong>: Custom pull indicator</li>
+        </ul>
+      </div>
+
+      <div style={{ background: '#fef3c7', padding: '16px', borderRadius: '8px' }}>
+        <h3 style={{ fontWeight: '600', marginBottom: '8px' }}>Testing</h3>
+        <p style={{ fontSize: '14px' }}>
+          To test on desktop, use Chrome DevTools mobile emulation with touch simulation enabled.
+          Click and drag down from the top of the content area.
+        </p>
+      </div>
+    </div>
+  ),
+};

package/src/components/PullToRefresh.tsx

@@ -0,0 +1,294 @@
+import React, { useState, useRef, useCallback, useEffect } from 'react';
+import { Loader2, ArrowDown } from 'lucide-react';
+
+/**
+ * PullToRefresh component props
+ */
+export interface PullToRefreshProps {
+  /** Content to wrap */
+  children: React.ReactNode;
+  /** Async refresh handler - should return a Promise */
+  onRefresh: () => Promise<void>;
+  /** Disable pull-to-refresh */
+  disabled?: boolean;
+  /** Pull distance required to trigger refresh (default: 80) */
+  pullThreshold?: number;
+  /** Maximum pull distance (default: 120) */
+  maxPull?: number;
+  /** Custom loading indicator */
+  loadingIndicator?: React.ReactNode;
+  /** Custom pull indicator */
+  pullIndicator?: React.ReactNode;
+  /** Additional class names for container */
+  className?: string;
+}
+
+type RefreshState = 'idle' | 'pulling' | 'ready' | 'refreshing';
+
+/**
+ * PullToRefresh - Mobile pull-to-refresh gesture handler
+ * 
+ * Wraps content and provides native-feeling pull-to-refresh functionality.
+ * Only activates when scrolled to top of content.
+ * 
+ * @example Basic usage
+ * ```tsx
+ * <PullToRefresh onRefresh={async () => {
+ *   await fetchLatestData();
+ * }}>
+ *   <div className="min-h-screen">
+ *     {content}
+ *   </div>
+ * </PullToRefresh>
+ * ```
+ * 
+ * @example With custom threshold
+ * ```tsx
+ * <PullToRefresh
+ *   onRefresh={handleRefresh}
+ *   pullThreshold={100}
+ *   maxPull={150}
+ * >
+ *   {content}
+ * </PullToRefresh>
+ * ```
+ */
+export default function PullToRefresh({
+  children,
+  onRefresh,
+  disabled = false,
+  pullThreshold = 80,
+  maxPull = 120,
+  loadingIndicator,
+  pullIndicator,
+  className = '',
+}: PullToRefreshProps) {
+  const [state, setState] = useState<RefreshState>('idle');
+  const [pullDistance, setPullDistance] = useState(0);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const startY = useRef(0);
+  const currentY = useRef(0);
+
+  // Check if at top of scroll container
+  const isAtTop = useCallback(() => {
+    const container = containerRef.current;
+    if (!container) return false;
+    return container.scrollTop <= 0;
+  }, []);
+
+  // Handle touch start
+  const handleTouchStart = useCallback((e: TouchEvent) => {
+    if (disabled || state === 'refreshing' || !isAtTop()) return;
+    
+    startY.current = e.touches[0].clientY;
+    currentY.current = startY.current;
+  }, [disabled, state, isAtTop]);
+
+  // Handle touch move
+  const handleTouchMove = useCallback((e: TouchEvent) => {
+    if (disabled || state === 'refreshing') return;
+    if (startY.current === 0) return;
+
+    currentY.current = e.touches[0].clientY;
+    const diff = currentY.current - startY.current;
+
+    // Only allow pulling down when at top
+    if (diff > 0 && isAtTop()) {
+      // Apply resistance - pull slows down as distance increases
+      const resistance = 0.5;
+      const adjustedPull = Math.min(diff * resistance, maxPull);
+      
+      setPullDistance(adjustedPull);
+      setState(adjustedPull >= pullThreshold ? 'ready' : 'pulling');
+
+      // Prevent default scroll when pulling
+      if (adjustedPull > 0) {
+        e.preventDefault();
+      }
+    }
+  }, [disabled, state, isAtTop, maxPull, pullThreshold]);
+
+  // Handle touch end
+  const handleTouchEnd = useCallback(async () => {
+    if (disabled || state === 'refreshing') return;
+
+    if (state === 'ready') {
+      setState('refreshing');
+      setPullDistance(pullThreshold); // Hold at threshold while refreshing
+
+      try {
+        await onRefresh();
+      } catch (error) {
+        console.error('Refresh failed:', error);
+      }
+
+      setState('idle');
+    }
+
+    setPullDistance(0);
+    startY.current = 0;
+    currentY.current = 0;
+  }, [disabled, state, pullThreshold, onRefresh]);
+
+  // Attach touch listeners
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    container.addEventListener('touchstart', handleTouchStart, { passive: true });
+    container.addEventListener('touchmove', handleTouchMove, { passive: false });
+    container.addEventListener('touchend', handleTouchEnd);
+
+    return () => {
+      container.removeEventListener('touchstart', handleTouchStart);
+      container.removeEventListener('touchmove', handleTouchMove);
+      container.removeEventListener('touchend', handleTouchEnd);
+    };
+  }, [handleTouchStart, handleTouchMove, handleTouchEnd]);
+
+  // Calculate indicator opacity and rotation
+  const progress = Math.min(pullDistance / pullThreshold, 1);
+  const rotation = progress * 180;
+
+  // Default loading indicator
+  const defaultLoadingIndicator = (
+    <Loader2 className="h-6 w-6 text-accent-600 animate-spin" />
+  );
+
+  // Default pull indicator
+  const defaultPullIndicator = (
+    <div
+      className={`
+        transition-transform duration-200
+        ${state === 'ready' ? 'text-accent-600' : 'text-ink-400'}
+      `}
+      style={{ transform: `rotate(${rotation}deg)` }}
+    >
+      <ArrowDown className="h-6 w-6" />
+    </div>
+  );
+
+  return (
+    <div
+      ref={containerRef}
+      className={`relative overflow-auto ${className}`}
+      style={{ touchAction: pullDistance > 0 ? 'none' : 'auto' }}
+    >
+      {/* Pull indicator */}
+      <div
+        className={`
+          absolute left-0 right-0 flex items-center justify-center
+          transition-all duration-200 overflow-hidden
+          ${state === 'idle' && pullDistance === 0 ? 'opacity-0' : 'opacity-100'}
+        `}
+        style={{
+          height: `${pullDistance}px`,
+          top: 0,
+          zIndex: 10,
+        }}
+      >
+        <div
+          className={`
+            w-10 h-10 rounded-full bg-white shadow-md
+            flex items-center justify-center
+            transition-transform duration-200
+            ${state === 'refreshing' ? 'scale-100' : progress < 0.3 ? 'scale-75' : 'scale-100'}
+          `}
+        >
+          {state === 'refreshing'
+            ? (loadingIndicator || defaultLoadingIndicator)
+            : (pullIndicator || defaultPullIndicator)
+          }
+        </div>
+      </div>
+
+      {/* Content wrapper */}
+      <div
+        className="transition-transform duration-200"
+        style={{
+          transform: `translateY(${pullDistance}px)`,
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * usePullToRefresh - Hook for custom pull-to-refresh implementations
+ * 
+ * @example
+ * ```tsx
+ * const { pullDistance, isRefreshing, bind } = usePullToRefresh({
+ *   onRefresh: async () => {
+ *     await fetchData();
+ *   }
+ * });
+ * 
+ * return (
+ *   <div {...bind}>
+ *     {isRefreshing && <Spinner />}
+ *     {content}
+ *   </div>
+ * );
+ * ```
+ */
+export function usePullToRefresh({
+  onRefresh,
+  pullThreshold = 80,
+  maxPull = 120,
+  disabled = false,
+}: {
+  onRefresh: () => Promise<void>;
+  pullThreshold?: number;
+  maxPull?: number;
+  disabled?: boolean;
+}) {
+  const [pullDistance, setPullDistance] = useState(0);
+  const [isRefreshing, setIsRefreshing] = useState(false);
+  const startY = useRef(0);
+
+  const handleTouchStart = useCallback((e: React.TouchEvent) => {
+    if (disabled || isRefreshing) return;
+    startY.current = e.touches[0].clientY;
+  }, [disabled, isRefreshing]);
+
+  const handleTouchMove = useCallback((e: React.TouchEvent) => {
+    if (disabled || isRefreshing || startY.current === 0) return;
+
+    const diff = e.touches[0].clientY - startY.current;
+    if (diff > 0) {
+      const adjustedPull = Math.min(diff * 0.5, maxPull);
+      setPullDistance(adjustedPull);
+    }
+  }, [disabled, isRefreshing, maxPull]);
+
+  const handleTouchEnd = useCallback(async () => {
+    if (disabled || isRefreshing) return;
+
+    if (pullDistance >= pullThreshold) {
+      setIsRefreshing(true);
+      try {
+        await onRefresh();
+      } finally {
+        setIsRefreshing(false);
+      }
+    }
+
+    setPullDistance(0);
+    startY.current = 0;
+  }, [disabled, isRefreshing, pullDistance, pullThreshold, onRefresh]);
+
+  return {
+    pullDistance,
+    isRefreshing,
+    isReady: pullDistance >= pullThreshold,
+    progress: Math.min(pullDistance / pullThreshold, 1),
+    bind: {
+      onTouchStart: handleTouchStart,
+      onTouchMove: handleTouchMove,
+      onTouchEnd: handleTouchEnd,
+    },
+  };
+}

package/src/components/QueryTransparency.tsx

@@ -37,7 +37,7 @@ export interface QueryTransparencyInfo {
   relatedData?: Array<{
     entity: string;
     description: string;
-    type: 'join' | 'include' | 'lookup';
+    type: 'primary' | 'join' | 'include' | 'lookup';
   }>;
   // Backend calculations
   calculations?: Array<{