@papernote/ui 1.2.0 → 1.3.0

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/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>
+  ),
+};

package/src/components/Stack.tsx

@@ -1,15 +1,19 @@
 // Stack Component - Vertical or horizontal stacking layout
 // Provides consistent spacing between child elements
 
-import React from 'react';
+import React, { forwardRef } from 'react';
 
-export interface StackProps {
+type SpacingValue = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export interface StackProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Content to stack */
   children: React.ReactNode;
   /** Direction of stack */
   direction?: 'vertical' | 'horizontal';
-  /** Spacing between items */
-  spacing?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** Spacing between items (alias: gap) */
+  spacing?: SpacingValue;
+  /** Spacing between items (alias for spacing - for developer convenience) */
+  gap?: SpacingValue;
   /** Alignment of items */
   align?: 'start' | 'center' | 'end' | 'stretch';
   /** Justify content */
@@ -23,23 +27,45 @@ export interface StackProps {
 /**
  * Stack component for arranging children vertically or horizontally with consistent spacing.
  * 
- * Spacing scale:
+ * Supports ref forwarding for DOM access.
+ * 
+ * Spacing scale (use either `spacing` or `gap` prop - they're aliases):
  * - none: 0
  * - xs: 0.5rem (2)
  * - sm: 0.75rem (3)
  * - md: 1.5rem (6)
  * - lg: 2rem (8)
  * - xl: 3rem (12)
+ * 
+ * @example
+ * ```tsx
+ * // Using spacing prop
+ * <Stack spacing="md">
+ *   <Card>Item 1</Card>
+ *   <Card>Item 2</Card>
+ * </Stack>
+ * 
+ * // Using gap prop (alias)
+ * <Stack gap="md">
+ *   <Card>Item 1</Card>
+ *   <Card>Item 2</Card>
+ * </Stack>
+ * ```
  */
-export const Stack: React.FC<StackProps> = ({
+export const Stack = forwardRef<HTMLDivElement, StackProps>(({
   children,
   direction = 'vertical',
-  spacing = 'md',
+  spacing,
+  gap,
   align = 'stretch',
   justify = 'start',
   wrap = false,
   className = '',
-}) => {
+  ...htmlProps
+}, ref) => {
+  // Use gap as alias for spacing (spacing takes precedence if both provided)
+  const effectiveSpacing = spacing ?? gap ?? 'md';
+
   const spacingClasses = {
     vertical: {
       none: '',
@@ -76,11 +102,13 @@ export const Stack: React.FC<StackProps> = ({
 
   return (
     <div
+      ref={ref}
+      {...htmlProps}
       className={`
         flex
         ${direction === 'vertical' ? 'flex-col' : 'flex-row'}
         ${wrap ? 'flex-wrap' : ''}
-        ${spacingClasses[direction][spacing]}
+        ${spacingClasses[direction][effectiveSpacing]}
         ${alignClasses[align]}
         ${justifyClasses[justify]}
         ${className}
@@ -89,6 +117,8 @@ export const Stack: React.FC<StackProps> = ({
       {children}
     </div>
   );
-};
+});
+
+Stack.displayName = 'Stack';
 
 export default Stack;