@papernote/ui 1.7.1 → 1.7.3

package/dist/styles.css

@@ -1575,10 +1575,6 @@ input:checked + .slider:before{
   margin-left: -0.5rem;
 }
 
-.-ml-3{
-  margin-left: -0.75rem;
-}
-
 .-ml-px{
   margin-left: -1px;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papernote/ui",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "type": "module",
   "description": "A modern React component library with a paper notebook aesthetic - minimal, professional, and expressive",
   "main": "dist/index.js",

package/src/components/Breadcrumbs.tsx

@@ -1,31 +1,192 @@
-import React from 'react';
-import { Link } from 'react-router-dom';
+import React, { useEffect, useRef } from 'react';
+import { Link, useNavigate, useLocation, useInRouterContext } from 'react-router-dom';
 import { ChevronRight, Home } from 'lucide-react';
 
+/** State passed during breadcrumb navigation */
+export interface BreadcrumbNavigationState {
+  /** Unique timestamp to detect navigation, even to the same route */
+  breadcrumbReset: number;
+  /** Identifies the source of navigation */
+  from: 'breadcrumb';
+}
+
+/**
+ * Hook to detect breadcrumb navigation and trigger callbacks.
+ * Use this in host components to reset state when a breadcrumb is clicked.
+ * 
+ * Note: This hook requires React Router context. If used outside a Router,
+ * it will be a no-op (the callback will never be called).
+ * 
+ * @param onReset - Callback fired when breadcrumb navigation is detected
+ * 
+ * @example
+ * function ProductsPage() {
+ *   const [viewMode, setViewMode] = useState<'list' | 'detail'>('list');
+ *   
+ *   // Automatically reset to list view when breadcrumb is clicked
+ *   useBreadcrumbReset(() => setViewMode('list'));
+ *   
+ *   // ... rest of component
+ * }
+ */
+export function useBreadcrumbReset(onReset: () => void): void {
+  const inRouter = useInRouterContext();
+  const lastResetRef = useRef<number | null>(null);
+  
+  // Only use useLocation when inside Router context
+  const location = inRouter ? useLocation() : null;
+
+  useEffect(() => {
+    if (!location) return;
+    
+    const state = location.state as BreadcrumbNavigationState | null;
+    
+    if (state?.breadcrumbReset && state.breadcrumbReset !== lastResetRef.current) {
+      lastResetRef.current = state.breadcrumbReset;
+      onReset();
+    }
+  }, [location?.state, onReset, location]);
+}
+
 export interface BreadcrumbItem {
+  /** Display text for the breadcrumb */
   label: string;
+  /** URL to navigate to. When provided, renders as a Link */
   href?: string;
+  /** 
+   * Optional callback fired when breadcrumb is clicked.
+   * Called in addition to navigation when href is provided.
+   * Use for custom actions like analytics, state resets, etc.
+   */
   onClick?: () => void;
+  /** Optional icon to display before the label */
   icon?: React.ReactNode;
 }
 
 export interface BreadcrumbsProps {
   items: BreadcrumbItem[];
+  /** Whether to show the home icon link at the start. Default: true */
   showHome?: boolean;
 }
 
+/**
+ * Breadcrumbs navigation component.
+ * 
+ * When a breadcrumb with href is clicked:
+ * - If navigating to a different route: standard navigation occurs
+ * - If navigating to the same route: navigation state is updated with a unique key,
+ *   which can be used by host apps to detect "reset" navigation via useLocation().state
+ * 
+ * @example
+ * // Basic usage
+ * <Breadcrumbs items={[
+ *   { label: 'Home', href: '/' },
+ *   { label: 'Products', href: '/products' },
+ *   { label: 'Widget' }  // Current page (no href)
+ * ]} />
+ * 
+ * @example
+ * // Host app detecting breadcrumb navigation for state reset
+ * function ProductsPage() {
+ *   const location = useLocation();
+ *   const [viewMode, setViewMode] = useState<'list' | 'detail'>('list');
+ * 
+ *   // Reset to list view when breadcrumb navigation occurs
+ *   useEffect(() => {
+ *     if (location.state?.breadcrumbReset) {
+ *       setViewMode('list');
+ *     }
+ *   }, [location.state?.breadcrumbReset]);
+ * 
+ *   // ... rest of component
+ * }
+ */
 export default function Breadcrumbs({ items, showHome = true }: BreadcrumbsProps) {
+  const inRouter = useInRouterContext();
+  
+  // Only use router hooks when inside Router context
+  const navigate = inRouter ? useNavigate() : null;
+  const location = inRouter ? useLocation() : null;
+
+  /**
+   * Handle breadcrumb click with same-route detection.
+   * When clicking a breadcrumb that points to the current route,
+   * we navigate with state to trigger a reset in the host component.
+   */
+  const handleBreadcrumbClick = (
+    e: React.MouseEvent,
+    href: string,
+    onClick?: () => void
+  ) => {
+    // Always call onClick if provided (for custom actions)
+    onClick?.();
+
+    // If not in router context, let the browser handle navigation naturally
+    if (!navigate || !location) return;
+
+    // Check if we're navigating to the same base path
+    const targetPath = href.split('?')[0].split('#')[0];
+    const currentPath = location.pathname;
+
+    if (targetPath === currentPath) {
+      // Same route - prevent default Link behavior and use navigate with state
+      e.preventDefault();
+      navigate(href, { 
+        state: { 
+          breadcrumbReset: Date.now(),
+          from: 'breadcrumb'
+        },
+        replace: true 
+      });
+    }
+    // Different route - let the Link handle it normally
+  };
+
+  // Helper to render a link - uses Link when in router, <a> when not
+  const renderLink = (
+    href: string,
+    children: React.ReactNode,
+    className: string,
+    onClick?: (e: React.MouseEvent) => void,
+    ariaLabel?: string
+  ) => {
+    if (inRouter) {
+      return (
+        <Link
+          to={href}
+          className={className}
+          onClick={onClick}
+          aria-label={ariaLabel}
+        >
+          {children}
+        </Link>
+      );
+    }
+    return (
+      <a
+        href={href}
+        className={className}
+        onClick={(e) => {
+          onClick?.(e);
+        }}
+        aria-label={ariaLabel}
+      >
+        {children}
+      </a>
+    );
+  };
+
   return (
     <nav aria-label="Breadcrumb" className="flex items-center space-x-2 text-sm">
       {showHome && (
         <>
-          <Link
-            to="/"
-            className="text-ink-500 hover:text-ink-900 transition-colors"
-            aria-label="Home"
-          >
-            <Home className="h-4 w-4" />
-          </Link>
+          {renderLink(
+            '/',
+            <Home className="h-4 w-4" />,
+            'text-ink-500 hover:text-ink-900 transition-colors',
+            (e) => handleBreadcrumbClick(e, '/'),
+            'Home'
+          )}
           {items.length > 0 && <ChevronRight className="h-4 w-4 text-ink-400" />}
         </>
       )}
@@ -53,16 +214,13 @@ export default function Breadcrumbs({ items, showHome = true }: BreadcrumbsProps
             );
           }
 
-          // Has href - render as Link, also call onClick if provided
+          // Has href - render as Link (or <a> if no router) with same-route detection
           if (item.href) {
-            return (
-              <Link
-                to={item.href}
-                onClick={item.onClick}
-                className="flex items-center gap-2 text-ink-500 hover:text-ink-900 hover:underline transition-colors"
-              >
-                {content}
-              </Link>
+            return renderLink(
+              item.href,
+              content,
+              'flex items-center gap-2 text-ink-500 hover:text-ink-900 hover:underline transition-colors',
+              (e) => handleBreadcrumbClick(e, item.href!, item.onClick)
             );
           }
 

package/src/components/Calendar.tsx

@@ -1,6 +1,6 @@
 
 import React, { useState, useMemo } from 'react';
-import { ChevronLeft, ChevronRight } from 'lucide-react';
+import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from 'lucide-react';
 
 export interface CalendarEvent {
   date: Date;
@@ -14,6 +14,8 @@ export interface CalendarProps {
   value?: Date;
   /** Callback when date is selected */
   onChange?: (date: Date) => void;
+  /** Callback when displayed month changes (via navigation buttons or goToToday) */
+  onMonthChange?: (date: Date) => void;
   /** Events to display on calendar */
   events?: CalendarEvent[];
   /** Callback when event marker is clicked */
@@ -41,6 +43,7 @@ export interface CalendarProps {
 export default function Calendar({
   value,
   onChange,
+  onMonthChange,
   events = [],
   onEventClick,
   rangeMode = false,
@@ -200,25 +203,35 @@ export default function Calendar({
 
   // Navigate months
   const previousMonth = () => {
-    setCurrentMonth(new Date(currentMonth.getFullYear(), currentMonth.getMonth() - 1, 1));
+    const newMonth = new Date(currentMonth.getFullYear(), currentMonth.getMonth() - 1, 1);
+    setCurrentMonth(newMonth);
+    onMonthChange?.(newMonth);
   };
 
   const nextMonth = () => {
-    setCurrentMonth(new Date(currentMonth.getFullYear(), currentMonth.getMonth() + 1, 1));
+    const newMonth = new Date(currentMonth.getFullYear(), currentMonth.getMonth() + 1, 1);
+    setCurrentMonth(newMonth);
+    onMonthChange?.(newMonth);
   };
 
   // Navigate years
   const previousYear = () => {
-    setCurrentMonth(new Date(currentMonth.getFullYear() - 1, currentMonth.getMonth(), 1));
+    const newMonth = new Date(currentMonth.getFullYear() - 1, currentMonth.getMonth(), 1);
+    setCurrentMonth(newMonth);
+    onMonthChange?.(newMonth);
   };
 
   const nextYear = () => {
-    setCurrentMonth(new Date(currentMonth.getFullYear() + 1, currentMonth.getMonth(), 1));
+    const newMonth = new Date(currentMonth.getFullYear() + 1, currentMonth.getMonth(), 1);
+    setCurrentMonth(newMonth);
+    onMonthChange?.(newMonth);
   };
 
   // Go to today
   const goToToday = () => {
-    setCurrentMonth(new Date());
+    const today = new Date();
+    setCurrentMonth(today);
+    onMonthChange?.(today);
   };
 
   // Day names
@@ -244,8 +257,7 @@ export default function Calendar({
             className="p-1.5 hover:bg-paper-100 rounded transition-colors"
             aria-label="Previous year"
           >
-            <ChevronLeft className="h-4 w-4 text-ink-600" />
-            <ChevronLeft className="h-4 w-4 text-ink-600 -ml-3" />
+            <ChevronsLeft className="h-4 w-4 text-ink-600" />
           </button>
           <button
             onClick={previousMonth}
@@ -281,8 +293,7 @@ export default function Calendar({
             className="p-1.5 hover:bg-paper-100 rounded transition-colors"
             aria-label="Next year"
           >
-            <ChevronRight className="h-4 w-4 text-ink-600" />
-            <ChevronRight className="h-4 w-4 text-ink-600 -ml-3" />
+            <ChevronsRight className="h-4 w-4 text-ink-600" />
           </button>
         </div>
       </div>

package/src/components/index.ts

@@ -201,8 +201,8 @@ export type { ExpandablePanelProps } from './ExpandablePanel';
 export { Show, Hide } from './ResponsiveUtilities';
 
 // Navigation Components
-export { default as Breadcrumbs } from './Breadcrumbs';
-export type { BreadcrumbsProps, BreadcrumbItem } from './Breadcrumbs';
+export { default as Breadcrumbs, useBreadcrumbReset } from './Breadcrumbs';
+export type { BreadcrumbsProps, BreadcrumbItem, BreadcrumbNavigationState } from './Breadcrumbs';
 
 export { default as Tabs } from './Tabs';
 export type { TabsProps, Tab } from './Tabs';