@papernote/ui 1.2.0 → 1.3.1

package/src/components/Grid.stories.tsx

@@ -0,0 +1,348 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Grid } from './Grid';
+import Box from './Box';
+import Text from './Text';
+import Card from './Card';
+
+const meta = {
+  title: 'Layout/Grid',
+  component: Grid,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+Grid component for arranging children in a CSS grid layout with responsive breakpoints.
+
+## Features
+- **Column options**: 1, 2, 3, 4, 6, 12 columns
+- **Responsive breakpoints**: columns (base), sm (640px+), md (768px+), lg (1024px+), xl (1280px+)
+- **Gap spacing**: none, xs, sm, md, lg, xl
+- **Mobile-first**: Set base columns and override at larger breakpoints
+
+## Usage
+
+\`\`\`tsx
+import { Grid } from 'notebook-ui';
+
+// Simple 3-column grid
+<Grid columns={3} gap="md">
+  <Card>Item 1</Card>
+  <Card>Item 2</Card>
+  <Card>Item 3</Card>
+</Grid>
+
+// Responsive grid: 1 column mobile, 2 tablet, 4 desktop
+<Grid columns={1} md={2} lg={4} gap="md">
+  {items.map(item => <Card key={item.id}>{item.name}</Card>)}
+</Grid>
+\`\`\`
+        `,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    columns: {
+      control: 'select',
+      options: [1, 2, 3, 4, 6, 12],
+      description: 'Base number of columns',
+    },
+    sm: {
+      control: 'select',
+      options: [undefined, 1, 2, 3, 4, 6, 12],
+      description: 'Columns at sm breakpoint (640px+)',
+    },
+    md: {
+      control: 'select',
+      options: [undefined, 1, 2, 3, 4, 6, 12],
+      description: 'Columns at md breakpoint (768px+)',
+    },
+    lg: {
+      control: 'select',
+      options: [undefined, 1, 2, 3, 4, 6, 12],
+      description: 'Columns at lg breakpoint (1024px+)',
+    },
+    xl: {
+      control: 'select',
+      options: [undefined, 1, 2, 3, 4, 6, 12],
+      description: 'Columns at xl breakpoint (1280px+)',
+    },
+    gap: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+      description: 'Gap between grid items',
+    },
+  },
+} satisfies Meta<typeof Grid>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Helper component for demo items
+const DemoItem = ({ children }: { children: React.ReactNode }) => (
+  <Box padding="md" border="all" rounded="md" className="bg-paper-50">
+    <Text align="center">{children}</Text>
+  </Box>
+);
+
+export const Default: Story = {
+  args: {
+    columns: 3,
+    gap: 'md',
+    children: (
+      <>
+        <DemoItem>Item 1</DemoItem>
+        <DemoItem>Item 2</DemoItem>
+        <DemoItem>Item 3</DemoItem>
+        <DemoItem>Item 4</DemoItem>
+        <DemoItem>Item 5</DemoItem>
+        <DemoItem>Item 6</DemoItem>
+      </>
+    ),
+  },
+};
+
+export const TwoColumns: Story = {
+  args: {
+    columns: 2,
+    gap: 'md',
+    children: (
+      <>
+        <DemoItem>Left</DemoItem>
+        <DemoItem>Right</DemoItem>
+        <DemoItem>Left</DemoItem>
+        <DemoItem>Right</DemoItem>
+      </>
+    ),
+  },
+};
+
+export const FourColumns: Story = {
+  args: {
+    columns: 4,
+    gap: 'md',
+    children: (
+      <>
+        <DemoItem>1</DemoItem>
+        <DemoItem>2</DemoItem>
+        <DemoItem>3</DemoItem>
+        <DemoItem>4</DemoItem>
+        <DemoItem>5</DemoItem>
+        <DemoItem>6</DemoItem>
+        <DemoItem>7</DemoItem>
+        <DemoItem>8</DemoItem>
+      </>
+    ),
+  },
+};
+
+export const SixColumns: Story = {
+  args: {
+    columns: 6,
+    gap: 'sm',
+    children: (
+      <>
+        {[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].map((n) => (
+          <DemoItem key={n}>{n}</DemoItem>
+        ))}
+      </>
+    ),
+  },
+};
+
+export const TwelveColumns: Story = {
+  args: {
+    columns: 12,
+    gap: 'xs',
+    children: (
+      <>
+        {[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].map((n) => (
+          <DemoItem key={n}>{n}</DemoItem>
+        ))}
+      </>
+    ),
+  },
+};
+
+/**
+ * Responsive grid that changes columns based on screen size.
+ * Resize the browser to see it adapt.
+ */
+export const Responsive: Story = {
+  args: {
+    columns: 1,
+    sm: 2,
+    md: 3,
+    lg: 4,
+    gap: 'md',
+    children: (
+      <>
+        {[1, 2, 3, 4, 5, 6, 7, 8].map((n) => (
+          <DemoItem key={n}>Item {n}</DemoItem>
+        ))}
+      </>
+    ),
+  },
+};
+
+export const GapSizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '2rem' }}>
+      <div>
+        <Text weight="medium" size="sm" color="muted">gap="none"</Text>
+        <Grid columns={4} gap="none">
+          <DemoItem>1</DemoItem>
+          <DemoItem>2</DemoItem>
+          <DemoItem>3</DemoItem>
+          <DemoItem>4</DemoItem>
+        </Grid>
+      </div>
+      <div>
+        <Text weight="medium" size="sm" color="muted">gap="xs"</Text>
+        <Grid columns={4} gap="xs">
+          <DemoItem>1</DemoItem>
+          <DemoItem>2</DemoItem>
+          <DemoItem>3</DemoItem>
+          <DemoItem>4</DemoItem>
+        </Grid>
+      </div>
+      <div>
+        <Text weight="medium" size="sm" color="muted">gap="sm"</Text>
+        <Grid columns={4} gap="sm">
+          <DemoItem>1</DemoItem>
+          <DemoItem>2</DemoItem>
+          <DemoItem>3</DemoItem>
+          <DemoItem>4</DemoItem>
+        </Grid>
+      </div>
+      <div>
+        <Text weight="medium" size="sm" color="muted">gap="md" (default)</Text>
+        <Grid columns={4} gap="md">
+          <DemoItem>1</DemoItem>
+          <DemoItem>2</DemoItem>
+          <DemoItem>3</DemoItem>
+          <DemoItem>4</DemoItem>
+        </Grid>
+      </div>
+      <div>
+        <Text weight="medium" size="sm" color="muted">gap="lg"</Text>
+        <Grid columns={4} gap="lg">
+          <DemoItem>1</DemoItem>
+          <DemoItem>2</DemoItem>
+          <DemoItem>3</DemoItem>
+          <DemoItem>4</DemoItem>
+        </Grid>
+      </div>
+      <div>
+        <Text weight="medium" size="sm" color="muted">gap="xl"</Text>
+        <Grid columns={4} gap="xl">
+          <DemoItem>1</DemoItem>
+          <DemoItem>2</DemoItem>
+          <DemoItem>3</DemoItem>
+          <DemoItem>4</DemoItem>
+        </Grid>
+      </div>
+    </div>
+  ),
+};
+
+export const WithCards: Story = {
+  render: () => (
+    <Grid columns={1} md={2} lg={3} gap="md">
+      <Card>
+        <Card.Header>
+          <Card.Title>Card 1</Card.Title>
+        </Card.Header>
+        <Card.Content>
+          <Text color="secondary">Content for the first card.</Text>
+        </Card.Content>
+      </Card>
+      <Card>
+        <Card.Header>
+          <Card.Title>Card 2</Card.Title>
+        </Card.Header>
+        <Card.Content>
+          <Text color="secondary">Content for the second card.</Text>
+        </Card.Content>
+      </Card>
+      <Card>
+        <Card.Header>
+          <Card.Title>Card 3</Card.Title>
+        </Card.Header>
+        <Card.Content>
+          <Text color="secondary">Content for the third card.</Text>
+        </Card.Content>
+      </Card>
+    </Grid>
+  ),
+};
+
+export const DashboardLayout: Story = {
+  render: () => (
+    <Grid columns={1} md={2} lg={4} gap="md">
+      <Box padding="lg" border="all" rounded="lg" className="bg-success-50">
+        <Text size="sm" color="muted">Revenue</Text>
+        <Text size="2xl" weight="bold">$45,231</Text>
+        <Text size="sm" color="success">+20.1% from last month</Text>
+      </Box>
+      <Box padding="lg" border="all" rounded="lg" className="bg-primary-50">
+        <Text size="sm" color="muted">Users</Text>
+        <Text size="2xl" weight="bold">2,350</Text>
+        <Text size="sm" color="accent">+180 new this week</Text>
+      </Box>
+      <Box padding="lg" border="all" rounded="lg" className="bg-warning-50">
+        <Text size="sm" color="muted">Pending</Text>
+        <Text size="2xl" weight="bold">12</Text>
+        <Text size="sm" color="warning">Requires attention</Text>
+      </Box>
+      <Box padding="lg" border="all" rounded="lg" className="bg-error-50">
+        <Text size="sm" color="muted">Errors</Text>
+        <Text size="2xl" weight="bold">3</Text>
+        <Text size="sm" color="error">Critical issues</Text>
+      </Box>
+    </Grid>
+  ),
+};
+
+export const FormLayout: Story = {
+  render: () => (
+    <Box padding="lg" border="all" rounded="lg" style={{ maxWidth: '600px' }}>
+      <Text as="h3" size="lg" weight="semibold">User Details</Text>
+      <Box marginTop="md">
+        <Grid columns={1} md={2} gap="md">
+          <Box padding="sm" border="all" rounded="sm" className="bg-paper-50">
+            <Text size="sm" color="muted">First Name</Text>
+          </Box>
+          <Box padding="sm" border="all" rounded="sm" className="bg-paper-50">
+            <Text size="sm" color="muted">Last Name</Text>
+          </Box>
+          <Box padding="sm" border="all" rounded="sm" className="bg-paper-50">
+            <Text size="sm" color="muted">Email</Text>
+          </Box>
+          <Box padding="sm" border="all" rounded="sm" className="bg-paper-50">
+            <Text size="sm" color="muted">Phone</Text>
+          </Box>
+        </Grid>
+      </Box>
+    </Box>
+  ),
+};
+
+export const ImageGallery: Story = {
+  render: () => (
+    <Grid columns={2} md={3} lg={4} gap="sm">
+      {[1, 2, 3, 4, 5, 6, 7, 8].map((n) => (
+        <Box 
+          key={n} 
+          padding="none" 
+          rounded="md" 
+          className="bg-paper-200 aspect-square flex items-center justify-center"
+          style={{ aspectRatio: '1/1', display: 'flex', alignItems: 'center', justifyContent: 'center' }}
+        >
+          <Text color="muted">Image {n}</Text>
+        </Box>
+      ))}
+    </Grid>
+  ),
+};

package/src/components/Grid.tsx

@@ -1,11 +1,11 @@
 // Grid Component - CSS Grid layout system
 // Provides flexible grid layouts with consistent spacing
 
-import React from 'react';
+import React, { forwardRef } from 'react';
 
 type ColumnCount = 1 | 2 | 3 | 4 | 6 | 12;
 
-export interface GridProps {
+export interface GridProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Content to arrange in grid */
   children: React.ReactNode;
   /** Number of columns (default, or mobile-first base) */
@@ -26,6 +26,8 @@ export interface GridProps {
 
 /**
  * Grid component for arranging children in a CSS grid layout.
+ * 
+ * Supports ref forwarding for DOM access.
  *
  * Column options: 1, 2, 3, 4, 6, 12
  *
@@ -51,7 +53,7 @@ export interface GridProps {
  *   <Card>Item 2</Card>
  * </Grid>
  */
-export const Grid: React.FC<GridProps> = ({
+export const Grid = forwardRef<HTMLDivElement, GridProps>(({
   children,
   columns = 1,
   sm,
@@ -60,7 +62,8 @@ export const Grid: React.FC<GridProps> = ({
   xl,
   gap = 'md',
   className = '',
-}) => {
+  ...htmlProps
+}, ref) => {
   // Base column classes
   const baseColumnClasses: Record<ColumnCount, string> = {
     1: 'grid-cols-1',
@@ -128,6 +131,8 @@ export const Grid: React.FC<GridProps> = ({
 
   return (
     <div
+      ref={ref}
+      {...htmlProps}
       className={`
         grid
         ${columnClassList}
@@ -138,6 +143,8 @@ export const Grid: React.FC<GridProps> = ({
       {children}
     </div>
   );
-};
+});
+
+Grid.displayName = 'Grid';
 
 export default Grid;

package/src/components/Input.tsx

@@ -1,5 +1,5 @@
 import React, { forwardRef, useState } from 'react';
-import { AlertCircle, CheckCircle, AlertTriangle, Eye, EyeOff, X } from 'lucide-react';
+import { AlertCircle, CheckCircle, AlertTriangle, Eye, EyeOff, X, Loader2 } from 'lucide-react';
 
 /**
  * Validation state for input components
@@ -38,6 +38,8 @@ export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement>
   clearable?: boolean;
   /** Callback when clear button is clicked */
   onClear?: () => void;
+  /** Show loading spinner in input */
+  loading?: boolean;
 }
 
 /**
@@ -105,6 +107,7 @@ const Input = forwardRef<HTMLInputElement, InputProps>(
       showPasswordToggle = false,
       clearable = false,
       onClear,
+      loading = false,
       className = '',
       id,
       type = 'text',
@@ -245,8 +248,15 @@ const Input = forwardRef<HTMLInputElement, InputProps>(
 
           {/* Right Icon, Validation Icon, Clear Button, or Password Toggle */}
           <div className="absolute inset-y-0 right-0 pr-3 flex items-center gap-2">
+            {/* Loading Spinner */}
+            {loading && (
+              <div className="pointer-events-none text-ink-400">
+                <Loader2 className="h-5 w-5 animate-spin" />
+              </div>
+            )}
+
             {/* Suffix Icon */}
-            {suffixIcon && !suffix && !validationState && !showPasswordToggle && !showClearButton && (
+            {suffixIcon && !suffix && !validationState && !showPasswordToggle && !showClearButton && !loading && (
               <div className="pointer-events-none text-ink-400">
                 {suffixIcon}
               </div>

package/src/components/MultiSelect.tsx

@@ -1,5 +1,5 @@
-import React, { useState, useRef, useEffect } from 'react';
-import { Check, ChevronDown, Search, X } from 'lucide-react';
+import React, { useState, useRef, useEffect, forwardRef, useImperativeHandle } from 'react';
+import { Check, ChevronDown, Search, X, Loader2 } from 'lucide-react';
 
 export interface MultiSelectOption {
   value: string;
@@ -21,10 +21,22 @@ export interface MultiSelectProps {
   maxHeight?: number;
   /** Maximum number of selections allowed */
   maxSelections?: number;
+  /** Show loading spinner (for async options loading) */
+  loading?: boolean;
   'aria-label'?: string;
 }
 
-export default function MultiSelect({
+/** Handle for imperative methods */
+export interface MultiSelectHandle {
+  /** Focus the select trigger button */
+  focus: () => void;
+  /** Open the dropdown */
+  open: () => void;
+  /** Close the dropdown */
+  close: () => void;
+}
+
+const MultiSelect = forwardRef<MultiSelectHandle, MultiSelectProps>(({
   options,
   value = [],
   onChange,
@@ -36,12 +48,21 @@ export default function MultiSelect({
   error,
   maxHeight = 240,
   maxSelections,
+  loading = false,
   'aria-label': ariaLabel,
-}: MultiSelectProps) {
+}, ref) => {
   const [isOpen, setIsOpen] = useState(false);
   const [searchQuery, setSearchQuery] = useState('');
   const selectRef = useRef<HTMLDivElement>(null);
   const searchInputRef = useRef<HTMLInputElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  // Expose imperative methods
+  useImperativeHandle(ref, () => ({
+    focus: () => triggerRef.current?.focus(),
+    open: () => !disabled && setIsOpen(true),
+    close: () => setIsOpen(false),
+  }));
 
   const selectedOptions = options.filter(opt => value.includes(opt.value));
   const hasReachedMax = maxSelections ? value.length >= maxSelections : false;
@@ -112,13 +133,14 @@ export default function MultiSelect({
       <div ref={selectRef} className="relative">
         {/* Trigger Button */}
         <button
+          ref={triggerRef}
           type="button"
-          onClick={() => !disabled && setIsOpen(!isOpen)}
-          disabled={disabled}
+          onClick={() => !disabled && !loading && setIsOpen(!isOpen)}
+          disabled={disabled || loading}
           className={`
             input w-full flex items-center justify-between min-h-[42px]
             ${error ? 'border-error-400 focus:border-error-400 focus:ring-error-400' : ''}
-            ${disabled ? 'opacity-40 cursor-not-allowed' : 'cursor-pointer'}
+            ${disabled || loading ? 'opacity-40 cursor-not-allowed' : 'cursor-pointer'}
           `}
           aria-haspopup="listbox"
           aria-expanded={isOpen}
@@ -148,7 +170,10 @@ export default function MultiSelect({
             )}
           </div>
           <div className="flex items-center gap-2 ml-2">
-            {selectedOptions.length > 0 && !disabled && (
+            {loading && (
+              <Loader2 className="h-4 w-4 text-ink-400 animate-spin" />
+            )}
+            {!loading && selectedOptions.length > 0 && !disabled && (
               <button
                 type="button"
                 onClick={handleClearAll}
@@ -158,7 +183,9 @@ export default function MultiSelect({
                 <X className="h-4 w-4" />
               </button>
             )}
-            <ChevronDown className={`h-4 w-4 text-ink-500 transition-transform ${isOpen ? 'rotate-180' : ''}`} />
+            {!loading && (
+              <ChevronDown className={`h-4 w-4 text-ink-500 transition-transform ${isOpen ? 'rotate-180' : ''}`} />
+            )}
           </div>
         </button>
 
@@ -244,4 +271,8 @@ export default function MultiSelect({
       </div>
     </div>
   );
-}
+});
+
+MultiSelect.displayName = 'MultiSelect';
+
+export default MultiSelect;

package/src/components/Spreadsheet.tsx

@@ -1,10 +1,10 @@
 import React, { useState, useCallback } from 'react';
 import BaseSpreadsheet, { CellBase, Matrix } from 'react-spreadsheet';
-import { read, utils, writeFile, WorkBook } from 'xlsx';
+import { utils, writeFile } from 'xlsx';
 import Button from './Button';
 import Card, { CardHeader, CardTitle, CardContent } from './Card';
 import Stack from './Stack';
-import { Download, Upload, Save } from 'lucide-react';
+import { Download, Save } from 'lucide-react';
 import { addSuccessMessage, addErrorMessage } from './StatusBar';
 import './Spreadsheet.css';
 
@@ -39,7 +39,11 @@ export interface SpreadsheetProps {
   rowLabels?: string[];
   /** Show toolbar with actions */
   showToolbar?: boolean;
-  /** Enable Excel import */
+  /**
+   * Enable Excel import
+   * @deprecated Excel import has been disabled due to security vulnerabilities in the xlsx library.
+   * This prop is kept for API compatibility but has no effect.
+   */
   enableImport?: boolean;
   /** Enable Excel export */
   enableExport?: boolean;
@@ -123,7 +127,7 @@ export const Spreadsheet: React.FC<SpreadsheetProps> = ({
   columnLabels,
   rowLabels,
   showToolbar = false,
-  enableImport = false,
+  enableImport: _enableImport = false, // Deprecated - kept for API compatibility
   enableExport = false,
   enableSave = false,
   onSave,
@@ -153,44 +157,6 @@ export const Spreadsheet: React.FC<SpreadsheetProps> = ({
     [onChange]
   );
 
-  // Handle Excel import
-  const handleImport = useCallback(
-    (event: React.ChangeEvent<HTMLInputElement>) => {
-      const file = event.target.files?.[0];
-      if (!file) return;
-
-      const reader = new FileReader();
-      reader.onload = (e) => {
-        try {
-          const workbook: WorkBook = read(e.target?.result, { type: 'binary' });
-          const sheetName = workbook.SheetNames[0];
-          const worksheet = workbook.Sheets[sheetName];
-
-          // Convert to array of arrays
-          const jsonData: any[][] = utils.sheet_to_json(worksheet, { header: 1 });
-
-          // Convert to spreadsheet format
-          const spreadsheetData: Matrix<SpreadsheetCell> = jsonData.map(row =>
-            row.map(cell => ({
-              value: cell,
-            }))
-          );
-
-          handleChange(spreadsheetData);
-          addSuccessMessage('Excel file imported successfully');
-        } catch (error) {
-          console.error('Error importing Excel file:', error);
-          addErrorMessage('Failed to import Excel file');
-        }
-      };
-      reader.readAsBinaryString(file);
-
-      // Reset input
-      event.target.value = '';
-    },
-    [handleChange]
-  );
-
   // Handle Excel export
   const handleExport = useCallback(() => {
     try {
@@ -238,20 +204,6 @@ export const Spreadsheet: React.FC<SpreadsheetProps> = ({
     <Stack direction="horizontal" spacing="md" align="center" className="mb-4">
       {title && <div className="text-lg font-medium text-ink-900 flex-1">{title}</div>}
 
-      {enableImport && (
-        <label>
-          <input
-            type="file"
-            accept=".xlsx,.xls,.csv"
-            onChange={handleImport}
-            className="hidden"
-          />
-          <Button variant="ghost" size="sm" icon={<Upload className="h-4 w-4" />}>
-            Import
-          </Button>
-        </label>
-      )}
-
       {enableExport && (
         <Button
           variant="ghost"
@@ -342,7 +294,6 @@ export const SpreadsheetReport: React.FC<
     <Spreadsheet
       {...props}
       showToolbar
-      enableImport
       enableExport
       enableSave
       wrapInCard

package/src/components/Stack.stories.tsx

@@ -49,7 +49,16 @@ import { Stack, Button } from 'notebook-ui';
     spacing: {
       control: 'select',
       options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
-      description: 'Gap spacing between children (none: 0, xs: 0.25rem, sm: 0.5rem, md: 1rem, lg: 1.5rem, xl: 2rem)',
+      description: 'Gap spacing between children (alias: gap)',
+      table: {
+        type: { summary: 'none | xs | sm | md | lg | xl' },
+        defaultValue: { summary: 'md' },
+      },
+    },
+    gap: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+      description: 'Gap spacing between children (alias for spacing)',
       table: {
         type: { summary: 'none | xs | sm | md | lg | xl' },
         defaultValue: { summary: 'md' },
@@ -339,3 +348,17 @@ export const NestedStacks: Story = {
     </Stack>
   ),
 };
+
+/**
+ * The `gap` prop is an alias for `spacing` - they are interchangeable.
+ * This provides flexibility for developers who prefer the `gap` terminology.
+ */
+export const GapAlias: Story = {
+  render: () => (
+    <Stack direction="horizontal" gap="md">
+      <Box>Using</Box>
+      <Box color="#8b5cf6">gap</Box>
+      <Box color="#10b981">prop</Box>
+    </Stack>
+  ),
+};