@papernote/ui 1.1.0 → 1.3.0

package/src/components/DataTable.stories.tsx

@@ -1,3 +1,4 @@
+import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import DataTable from './DataTable';
 import Badge from './Badge';
@@ -126,14 +127,6 @@ const actions = [
         defaultValue: { summary: 'false' },
       },
     },
-    multiSelect: {
-      control: 'boolean',
-      description: 'Allow multiple row selection (requires selectable=true)',
-      table: {
-        type: { summary: 'boolean' },
-        defaultValue: { summary: 'true' },
-      },
-    },
     actions: {
       description: 'Row actions displayed in sticky actions column',
       table: {
@@ -179,23 +172,21 @@ type Story = StoryObj<typeof meta>;
 const columns = [
   {
     key: 'name',
-    label: 'Name',
+    header: 'Name',
     sortable: true,
-    filterable: true,
   },
   {
     key: 'email',
-    label: 'Email',
+    header: 'Email',
     sortable: true,
   },
   {
     key: 'role',
-    label: 'Role',
-    filterable: true,
+    header: 'Role',
   },
   {
     key: 'status',
-    label: 'Status',
+    header: 'Status',
     render: (user: User) => {
       const variant = user.status === 'active' ? 'success' : user.status === 'inactive' ? 'error' : 'warning';
       return <Badge variant={variant}>{user.status}</Badge>;
@@ -203,7 +194,7 @@ const columns = [
   },
   {
     key: 'joinedAt',
-    label: 'Joined',
+    header: 'Joined',
     sortable: true,
   },
 ];
@@ -234,7 +225,7 @@ export const WithActions: Story = {
         label: 'Delete',
         icon: <Trash className="h-4 w-4" />,
         onClick: (user: User) => alert(`Delete ${user.name}`),
-        danger: true,
+        variant: 'danger',
       },
     ],
   },
@@ -245,16 +236,36 @@ export const Selectable: Story = {
     data: sampleUsers,
     columns,
     selectable: true,
-    onSelectionChange: (selected: User[]) => console.log('Selected:', selected),
+    onRowSelect: (selected: string[]) => console.log('Selected:', selected),
   },
 };
 
 export const Paginated: Story = {
-  args: {
-    data: sampleUsers,
-    columns,
-    paginated: true,
-    pageSize: 3,
+  render: () => {
+    const [currentPage, setCurrentPage] = React.useState(1);
+    const [pageSize, setPageSize] = React.useState(2);
+
+    // Simulate client-side pagination
+    const paginatedData = sampleUsers.slice(
+      (currentPage - 1) * pageSize,
+      currentPage * pageSize
+    );
+
+    return (
+      <DataTable
+        data={paginatedData}
+        columns={columns}
+        paginated
+        currentPage={currentPage}
+        pageSize={pageSize}
+        totalItems={sampleUsers.length}
+        onPageChange={setCurrentPage}
+        onPageSizeChange={(size) => {
+          setPageSize(size);
+          setCurrentPage(1);
+        }}
+      />
+    );
   },
 };
 
@@ -263,6 +274,7 @@ export const WithExpandedRows: Story = {
     data: sampleUsers,
     columns,
     expandable: true,
+    showExpandChevron: true,
     renderExpandedRow: (user: User) => (
       <div style={{ padding: '1rem', backgroundColor: '#f5f5f4' }}>
         <h4 style={{ marginBottom: '0.5rem', fontWeight: 600 }}>User Details</h4>
@@ -311,8 +323,6 @@ export const FullFeatured: Story = {
     data: sampleUsers,
     columns,
     selectable: true,
-    paginated: true,
-    pageSize: 3,
     actions: [
       {
         label: 'Edit',
@@ -323,10 +333,11 @@ export const FullFeatured: Story = {
         label: 'Delete',
         icon: <Trash className="h-4 w-4" />,
         onClick: (user: User) => alert(`Delete ${user.name}`),
-        danger: true,
+        variant: 'danger',
       },
     ],
     expandable: true,
+    showExpandChevron: true,
     renderExpandedRow: (user: User) => (
       <div style={{ padding: '1rem' }}>
         <p>Additional details for {user.name}</p>

package/src/components/DataTable.tsx

@@ -2,6 +2,9 @@
 import React, { useState, useRef, useEffect } from 'react';
 import { createPortal } from 'react-dom';
 import { ChevronDown, ChevronRight, MoreVertical, Edit, Trash } from 'lucide-react';
+import Menu, { MenuItem } from './Menu';
+import Pagination from './Pagination';
+import Select from './Select';
 
 /**
  * Base data item interface - all data items must have an id
@@ -12,8 +15,6 @@ import { ChevronDown, ChevronRight, MoreVertical, Edit, Trash } from 'lucide-rea
 export interface BaseDataItem {
   /** Unique identifier for the data item */
   id: string | number;
-  /** Additional properties specific to your data type */
-  [key: string]: unknown;
 }
 
 /**
@@ -164,6 +165,8 @@ interface DataTableProps<T extends BaseDataItem = BaseDataItem> {
   onDelete?: (item: T) => void | Promise<void>;
   /** Optional custom row actions (in addition to edit/delete) */
   actions?: DataTableAction<T>[];
+  /** Enable context menu (right-click) for row actions (default: true when actions exist) */
+  enableContextMenu?: boolean;
   /** Optional click handler for rows */
   onRowClick?: (item: T) => void;
   /** Optional double-click handler for rows */
@@ -226,6 +229,24 @@ interface DataTableProps<T extends BaseDataItem = BaseDataItem> {
   virtualHeight?: string;
   /** Row height for virtual scrolling (default: 60) */
   virtualRowHeight?: number;
+
+  // Pagination props
+  /** Enable built-in pagination (renders Pagination component above table) */
+  paginated?: boolean;
+  /** Current page number (1-indexed) */
+  currentPage?: number;
+  /** Number of items per page */
+  pageSize?: number;
+  /** Total number of items (for server-side pagination) */
+  totalItems?: number;
+  /** Callback when page changes */
+  onPageChange?: (page: number) => void;
+  /** Available page size options (default: [10, 25, 50, 100]) */
+  pageSizeOptions?: number[];
+  /** Callback when page size changes */
+  onPageSizeChange?: (pageSize: number) => void;
+  /** Show page size selector (default: true when paginated) */
+  showPageSizeSelector?: boolean;
 }
 
 /**
@@ -455,6 +476,7 @@ export default function DataTable<T extends BaseDataItem = BaseDataItem>({
   onEdit,
   onDelete,
   actions = [],
+  enableContextMenu = true,
   onRowClick,
   onRowDoubleClick,
   selectable = false,
@@ -486,6 +508,15 @@ export default function DataTable<T extends BaseDataItem = BaseDataItem>({
   virtualized = false,
   virtualHeight = '600px',
   virtualRowHeight = 60,
+  // Pagination props
+  paginated = false,
+  currentPage = 1,
+  pageSize = 10,
+  totalItems,
+  onPageChange,
+  pageSizeOptions = [10, 25, 50, 100],
+  onPageSizeChange,
+  showPageSizeSelector = true,
 }: DataTableProps<T>) {
   // Column resizing state
   const [columnWidths, setColumnWidths] = useState<Record<string, number>>({});
@@ -505,6 +536,17 @@ export default function DataTable<T extends BaseDataItem = BaseDataItem>({
   // Row hover state (for coordinating primary + secondary row highlighting)
   const [hoveredRowKey, setHoveredRowKey] = useState<string | null>(null);
 
+  // Context menu state
+  const [contextMenuState, setContextMenuState] = useState<{
+    isOpen: boolean;
+    position: { x: number; y: number };
+    item: T | null;
+  }>({
+    isOpen: false,
+    position: { x: 0, y: 0 },
+    item: null,
+  });
+
   // Filter columns based on hiddenColumns
   const baseVisibleColumns = columns.filter(
     col => !hiddenColumns.includes(String(col.key))
@@ -746,18 +788,56 @@ export default function DataTable<T extends BaseDataItem = BaseDataItem>({
     });
   }
   
+  // Combine all actions: built-in first, then custom actions, then delete last
+  // Delete is stored separately to ensure it's always last
+  let deleteAction: DataTableAction<T> | null = null;
   if (onDelete) {
-    builtInActions.push({
+    deleteAction = {
       label: 'Delete',
       icon: Trash,
       onClick: onDelete,
       variant: 'danger',
       tooltip: 'Delete item'
-    });
+    };
   }
   
-  const allActions = [...builtInActions, ...actions];
-  
+  // Build final actions array with consistent ordering:
+  // 1. Edit (first - most common action)
+  // 2. View Details
+  // 3. Add Related actions
+  // 4. Manage Related actions
+  // 5. Custom actions (from actions prop)
+  // 6. Delete (always last - destructive action)
+  const allActions: DataTableAction<T>[] = [
+    ...builtInActions,
+    ...actions,
+    ...(deleteAction ? [deleteAction] : [])
+  ];
+
+  // Convert actions to menu items for context menu
+  const convertActionsToMenuItems = (item: T): MenuItem[] => {
+    const visibleActions = allActions.filter(action => !action.show || action.show(item));
+
+    return visibleActions.map((action, idx) => {
+      let iconElement: React.ReactNode = null;
+      if (action.icon) {
+        if (React.isValidElement(action.icon)) {
+          iconElement = action.icon;
+        } else {
+          iconElement = React.createElement(action.icon as any, { className: 'h-4 w-4' });
+        }
+      }
+
+      return {
+        id: `action-${idx}`,
+        label: action.label,
+        icon: iconElement,
+        onClick: () => action.onClick(item),
+        danger: action.variant === 'danger',
+      };
+    });
+  };
+
   // Selection state management
   const [internalSelectedRows, setInternalSelectedRows] = useState<Set<string>>(new Set());
   
@@ -997,6 +1077,21 @@ export default function DataTable<T extends BaseDataItem = BaseDataItem>({
           onMouseEnter={() => !disableHover && setHoveredRowKey(rowKey)}
           onMouseLeave={() => !disableHover && setHoveredRowKey(null)}
           onClick={() => onRowClick?.(item)}
+          onContextMenu={(e) => {
+            if (enableContextMenu && allActions.length > 0) {
+              e.preventDefault();
+              e.stopPropagation();
+
+              const x = e.clientX;
+              const y = e.clientY;
+
+              setContextMenuState({
+                isOpen: true,
+                position: { x, y },
+                item,
+              });
+            }
+          }}
           onDoubleClick={() => {
             // Priority 1: If there's an onEdit handler (legacy), trigger it
             if (onEdit) {
@@ -1382,18 +1477,77 @@ export default function DataTable<T extends BaseDataItem = BaseDataItem>({
   );
 
   // Wrap in scrollable container if virtualized
-  if (virtualized) {
+  const finalContent = virtualized ? (
+    <div
+      ref={tableContainerRef}
+      onScroll={handleScroll}
+      style={{ height: virtualHeight, overflow: 'auto' }}
+      className="rounded-lg"
+    >
+      {tableContent}
+    </div>
+  ) : tableContent;
+
+  // Calculate pagination values
+  const effectiveTotalItems = totalItems ?? data.length;
+  const totalPages = Math.ceil(effectiveTotalItems / pageSize);
+
+  // Page size selector options
+  const pageSizeSelectOptions = pageSizeOptions.map(size => ({
+    value: String(size),
+    label: `${size} per page`,
+  }));
+
+  // Render pagination controls
+  const renderPaginationControls = () => {
+    if (!paginated) return null;
+
     return (
-      <div
-        ref={tableContainerRef}
-        onScroll={handleScroll}
-        style={{ height: virtualHeight, overflow: 'auto' }}
-        className="rounded-lg"
-      >
-        {tableContent}
+      <div className="flex items-center justify-between mb-4 px-1">
+        <div className="flex items-center gap-4">
+          {showPageSizeSelector && onPageSizeChange && (
+            <div className="flex items-center gap-2">
+              <span className="text-sm text-ink-600">Show:</span>
+              <Select
+                options={pageSizeSelectOptions}
+                value={String(pageSize)}
+                onChange={(value) => onPageSizeChange?.(Number(value))}
+              />
+            </div>
+          )}
+          <span className="text-sm text-ink-600">
+            {effectiveTotalItems > 0 ? (
+              <>
+                Showing {((currentPage - 1) * pageSize) + 1} - {Math.min(currentPage * pageSize, effectiveTotalItems)} of {effectiveTotalItems}
+              </>
+            ) : (
+              'No items'
+            )}
+          </span>
+        </div>
+        {totalPages > 1 && onPageChange && (
+          <Pagination
+            currentPage={currentPage}
+            totalPages={totalPages}
+            onPageChange={onPageChange}
+          />
+        )}
       </div>
     );
-  }
+  };
 
-  return tableContent;
+  // Render with context menu
+  return (
+    <>
+      {renderPaginationControls()}
+      {finalContent}
+      {contextMenuState.isOpen && contextMenuState.item && (
+        <Menu
+          items={convertActionsToMenuItems(contextMenuState.item)}
+          position={contextMenuState.position}
+          onClose={() => setContextMenuState({ isOpen: false, position: { x: 0, y: 0 }, item: null })}
+        />
+      )}
+    </>
+  );
 }

package/src/components/EmptyState.stories.tsx

@@ -1,7 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import EmptyState from './EmptyState';
 import Button from './Button';
-import { Inbox, Users, FileText, Search, Database, ShoppingCart } from 'lucide-react';
+import Input from './Input';
+import Stack from './Stack';
+import Text from './Text';
+import { Inbox, Users, FileText, Search, Database, ShoppingCart, Plus } from 'lucide-react';
 
 const meta = {
   title: 'Feedback/EmptyState',
@@ -18,6 +21,7 @@ Empty state component for displaying helpful messages when no content is availab
 - **Title and description**: Clear messaging about empty state
 - **Primary action**: Main CTA button
 - **Secondary action**: Optional additional action
+- **Children support**: Custom content below description
 - **Centered layout**: Vertically and horizontally centered
 - **Responsive**: Adapts to container width
 
@@ -79,6 +83,12 @@ import { Inbox } from 'lucide-react';
         type: { summary: '{ label: string; onClick: () => void }' },
       },
     },
+    children: {
+      description: 'Optional custom content rendered below the description',
+      table: {
+        type: { summary: 'React.ReactNode' },
+      },
+    },
   },
   decorators: [
     (Story) => (
@@ -95,7 +105,7 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {
     title: 'No items found',
-    message: 'There are no items to display at this time.',
+    description: 'There are no items to display at this time.',
   },
 };
 
@@ -103,7 +113,7 @@ export const WithIcon: Story = {
   args: {
     icon: <Inbox className="h-12 w-12" />,
     title: 'Your inbox is empty',
-    message: 'No new messages at this time.',
+    description: 'No new messages at this time.',
   },
 };
 
@@ -111,32 +121,35 @@ export const WithAction: Story = {
   args: {
     icon: <Users className="h-12 w-12" />,
     title: 'No users yet',
-    message: 'Get started by adding your first user.',
-    action: <Button variant="primary">Add User</Button>,
+    description: 'Get started by adding your first user.',
+    action: {
+      label: 'Add User',
+      onClick: () => alert('Add user clicked'),
+    },
   },
 };
 
-export const WithMultipleActions: Story = {
-  render: () => (
-    <EmptyState
-      icon={<FileText className="h-12 w-12" />}
-      title="No documents"
-      message="You haven't created any documents yet. Create a new one or upload existing files."
-      action={
-        <div style={{ display: 'flex', gap: '0.75rem' }}>
-          <Button variant="primary">Create New</Button>
-          <Button variant="outline">Upload Files</Button>
-        </div>
-      }
-    />
-  ),
+export const WithBothActions: Story = {
+  args: {
+    icon: <FileText className="h-12 w-12" />,
+    title: 'No documents',
+    description: "You haven't created any documents yet. Create a new one or upload existing files.",
+    action: {
+      label: 'Create New',
+      onClick: () => alert('Create clicked'),
+    },
+    secondaryAction: {
+      label: 'Upload Files',
+      onClick: () => alert('Upload clicked'),
+    },
+  },
 };
 
 export const SearchResults: Story = {
   args: {
     icon: <Search className="h-12 w-12" />,
     title: 'No results found',
-    message: 'Try adjusting your search or filter to find what you\'re looking for.',
+    description: "Try adjusting your search or filter to find what you're looking for.",
   },
 };
 
@@ -144,66 +157,103 @@ export const NoData: Story = {
   args: {
     icon: <Database className="h-12 w-12" />,
     title: 'No data available',
-    message: 'There is no data to display for the selected time period.',
+    description: 'There is no data to display for the selected time period.',
   },
 };
 
 export const EmptyCart: Story = {
-  render: () => (
-    <EmptyState
-      icon={<ShoppingCart className="h-12 w-12" />}
-      title="Your cart is empty"
-      message="Looks like you haven't added anything to your cart yet."
-      action={<Button variant="primary">Continue Shopping</Button>}
-    />
+  args: {
+    icon: <ShoppingCart className="h-12 w-12" />,
+    title: 'Your cart is empty',
+    description: "Looks like you haven't added anything to your cart yet.",
+    action: {
+      label: 'Continue Shopping',
+      onClick: () => alert('Continue shopping clicked'),
+    },
+  },
+};
+
+/**
+ * Use the `children` prop to add custom content below the description.
+ * This is useful for adding forms, additional context, or complex UI elements.
+ */
+export const WithChildren: Story = {
+  args: {
+    icon: <Plus className="h-12 w-12" />,
+    title: 'Create your first project',
+    description: 'Projects help you organize your work and collaborate with team members.',
+  },
+  render: (args) => (
+    <EmptyState {...args}>
+      <Stack spacing="sm" align="stretch">
+        <Input 
+          placeholder="Enter project name..." 
+          label="Project Name"
+        />
+        <Button variant="primary" icon={<Plus className="h-4 w-4" />}>
+          Create Project
+        </Button>
+      </Stack>
+    </EmptyState>
   ),
 };
 
-export const WithDescription: Story = {
-  render: () => (
-    <EmptyState
-      icon={<FileText className="h-12 w-12" />}
-      title="No projects yet"
-      message="Projects help you organize your work and collaborate with team members."
-      action={
-        <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', alignItems: 'center' }}>
-          <Button variant="primary">Create Your First Project</Button>
-          <a href="#" style={{ fontSize: '0.875rem', color: '#3b82f6', textDecoration: 'none' }}>
-            Learn more about projects →
-          </a>
-        </div>
-      }
-    />
+/**
+ * Children can contain any custom content like search inputs for filtering.
+ */
+export const WithSearchInChildren: Story = {
+  args: {
+    icon: <Search className="h-12 w-12" />,
+    title: 'No results found',
+    description: 'Try a different search term or browse categories.',
+  },
+  render: (args) => (
+    <EmptyState {...args}>
+      <Stack spacing="md" align="center">
+        <Input 
+          placeholder="Search again..." 
+          prefixIcon={<Search className="h-4 w-4" />}
+          clearable
+        />
+        <Text size="sm" color="muted">
+          Popular searches: React, TypeScript, Components
+        </Text>
+      </Stack>
+    </EmptyState>
   ),
 };
 
-export const ErrorState: Story = {
-  render: () => (
-    <EmptyState
-      icon={
-        <div style={{
-          width: '64px',
-          height: '64px',
-          borderRadius: '50%',
-          backgroundColor: '#fef2f2',
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-        }}>
-          <span style={{ fontSize: '2rem' }}>⚠️</span>
-        </div>
-      }
-      title="Something went wrong"
-      message="We encountered an error while loading your data. Please try again."
-      action={<Button variant="primary">Retry</Button>}
-    />
+/**
+ * Combine children with action buttons for maximum flexibility.
+ */
+export const WithChildrenAndActions: Story = {
+  args: {
+    icon: <Users className="h-12 w-12" />,
+    title: 'Invite team members',
+    description: 'Add team members to collaborate on this project.',
+    action: {
+      label: 'Send Invites',
+      onClick: () => alert('Send invites clicked'),
+    },
+    secondaryAction: {
+      label: 'Skip for now',
+      onClick: () => alert('Skip clicked'),
+    },
+  },
+  render: (args) => (
+    <EmptyState {...args}>
+      <Input 
+        placeholder="Enter email addresses..." 
+        helperText="Separate multiple emails with commas"
+      />
+    </EmptyState>
   ),
 };
 
 export const MinimalStyle: Story = {
   args: {
     title: 'No notifications',
-    message: 'You\'re all caught up!',
+    description: "You're all caught up!",
   },
 };
 
@@ -221,7 +271,7 @@ export const InCard: Story = {
       <EmptyState
         icon={<Inbox className="h-10 w-10" />}
         title="No recent activity"
-        message="Your recent activity will appear here."
+        description="Your recent activity will appear here."
       />
     </div>
   ),
@@ -240,13 +290,15 @@ export const FullPage: Story = {
       <EmptyState
         icon={<Users className="h-16 w-16" />}
         title="Welcome to Your Dashboard"
-        message="Get started by inviting team members or creating your first project."
-        action={
-          <div style={{ display: 'flex', gap: '0.75rem' }}>
-            <Button variant="primary">Invite Team</Button>
-            <Button variant="outline">Create Project</Button>
-          </div>
-        }
+        description="Get started by inviting team members or creating your first project."
+        action={{
+          label: 'Invite Team',
+          onClick: () => alert('Invite clicked'),
+        }}
+        secondaryAction={{
+          label: 'Create Project',
+          onClick: () => alert('Create clicked'),
+        }}
       />
     </div>
   ),