@papernote/ui 1.1.0 → 1.3.0

package/src/components/SpreadsheetSimple.stories.tsx

@@ -1,27 +1,27 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import { Spreadsheet } from './Spreadsheet';
-
-const meta: Meta<typeof Spreadsheet> = {
-  title: 'Components/Spreadsheet/Simple Test',
-  component: Spreadsheet,
-  parameters: {
-    docs: {
-      description: {
-        component: 'Simple test story for Spreadsheet component debugging.',
-      },
-    },
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof Spreadsheet>;
-
-/**
- * Minimal test - just render with defaults
- */
-export const MinimalTest: Story = {
-  args: {
-    rows: 5,
-    columns: 3,
-  },
-};
+import type { Meta, StoryObj } from '@storybook/react';
+import { Spreadsheet } from './Spreadsheet';
+
+const meta: Meta<typeof Spreadsheet> = {
+  title: 'Components/Spreadsheet/Simple Test',
+  component: Spreadsheet,
+  parameters: {
+    docs: {
+      description: {
+        component: 'Simple test story for Spreadsheet component debugging.',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Spreadsheet>;
+
+/**
+ * Minimal test - just render with defaults
+ */
+export const MinimalTest: Story = {
+  args: {
+    rows: 5,
+    columns: 3,
+  },
+};

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;

package/src/components/Tabs.tsx

@@ -1,152 +1,152 @@
-import React, { useState, useEffect } from 'react';
-
-export interface Tab {
-  id: string;
-  label: string;
-  icon?: React.ReactNode;
-  content: React.ReactNode;
-  disabled?: boolean;
-}
-
-export interface TabsProps {
-  tabs: Tab[];
-  /** Controlled mode: Currently active tab ID */
-  activeTab?: string;
-  /** Uncontrolled mode: Initial tab ID (ignored if activeTab is provided) */
-  defaultTab?: string;
-  variant?: 'underline' | 'pill';
-  /** Orientation of tabs (default: 'horizontal') */
-  orientation?: 'horizontal' | 'vertical';
-  /** Size of tabs (default: 'md') */
-  size?: 'sm' | 'md' | 'lg';
-  /** Called when tab changes (required for controlled mode) */
-  onChange?: (tabId: string) => void;
-}
-
-export default function Tabs({ tabs, activeTab: controlledActiveTab, defaultTab, variant = 'underline', orientation = 'horizontal', size = 'md', onChange }: TabsProps) {
-  const [internalActiveTab, setInternalActiveTab] = useState(defaultTab || tabs[0]?.id);
-
-  // Controlled mode: use activeTab prop, Uncontrolled mode: use internal state
-  const isControlled = controlledActiveTab !== undefined;
-  const activeTab = isControlled ? controlledActiveTab : internalActiveTab;
-
-  // Ensure the activeTab exists in the current tabs array
-  // This handles the case where tabs array reference changes at the same time as activeTab
-  useEffect(() => {
-    const tabExists = tabs.some(tab => tab.id === activeTab);
-    if (!tabExists && tabs.length > 0) {
-      // If the activeTab doesn't exist in the new tabs array, use the first tab
-      if (isControlled) {
-        onChange?.(tabs[0].id);
-      } else {
-        setInternalActiveTab(tabs[0].id);
-      }
-    }
-  }, [tabs, activeTab, isControlled, onChange]);
-
-  const handleTabChange = (tabId: string) => {
-    if (!isControlled) {
-      setInternalActiveTab(tabId);
-    }
-    onChange?.(tabId);
-  };
-
-  // Size-specific classes
-  const sizeClasses = {
-    sm: {
-      padding: 'px-3 py-1.5',
-      text: 'text-xs',
-      icon: 'h-3.5 w-3.5',
-      gap: orientation === 'vertical' ? 'gap-1.5' : 'gap-4',
-      minWidth: orientation === 'vertical' ? 'min-w-[150px]' : '',
-      spacing: orientation === 'vertical' ? 'mt-4' : 'mt-4',
-    },
-    md: {
-      padding: 'px-4 py-2.5',
-      text: 'text-sm',
-      icon: 'h-4 w-4',
-      gap: orientation === 'vertical' ? 'gap-2' : 'gap-6',
-      minWidth: orientation === 'vertical' ? 'min-w-[200px]' : '',
-      spacing: orientation === 'vertical' ? 'mt-6' : 'mt-6',
-    },
-    lg: {
-      padding: 'px-5 py-3',
-      text: 'text-base',
-      icon: 'h-5 w-5',
-      gap: orientation === 'vertical' ? 'gap-3' : 'gap-8',
-      minWidth: orientation === 'vertical' ? 'min-w-[250px]' : '',
-      spacing: orientation === 'vertical' ? 'mt-8' : 'mt-8',
-    },
-  };
-
-  return (
-    <div className={`w-full ${orientation === 'vertical' ? `flex ${sizeClasses[size].gap}` : ''}`}>
-      {/* Tab Headers */}
-      <div
-        className={`
-          flex ${orientation === 'vertical' ? 'flex-col' : ''}
-          ${variant === 'underline'
-            ? orientation === 'vertical'
-              ? `border-r border-paper-200 ${sizeClasses[size].gap} pr-6`
-              : `border-b border-paper-200 ${sizeClasses[size].gap}`
-            : `${sizeClasses[size].gap} p-1 bg-paper-50 rounded-lg`
-          }
-          ${sizeClasses[size].minWidth}
-        `}
-        role="tablist"
-      >
-        {tabs.map((tab) => {
-          const isActive = activeTab === tab.id;
-
-          return (
-            <button
-              key={tab.id}
-              role="tab"
-              aria-selected={isActive}
-              aria-controls={`panel-${tab.id}`}
-              disabled={tab.disabled}
-              onClick={() => !tab.disabled && handleTabChange(tab.id)}
-              className={`
-                flex items-center gap-2 ${sizeClasses[size].padding} ${sizeClasses[size].text} font-medium transition-all duration-200
-                ${orientation === 'vertical' ? 'w-full justify-start' : ''}
-                ${
-                  variant === 'underline'
-                    ? isActive
-                      ? orientation === 'vertical'
-                        ? 'text-accent-900 border-r-2 border-accent-500 -mr-[1px]'
-                        : 'text-accent-900 border-b-2 border-accent-500 -mb-[1px]'
-                      : orientation === 'vertical'
-                      ? 'text-ink-600 hover:text-ink-900 border-r-2 border-transparent'
-                      : 'text-ink-600 hover:text-ink-900 border-b-2 border-transparent'
-                    : isActive
-                    ? 'bg-white text-accent-900 rounded-md shadow-xs'
-                    : 'text-ink-600 hover:text-ink-900 hover:bg-white/50 rounded-md'
-                }
-                ${tab.disabled ? 'opacity-40 cursor-not-allowed' : 'cursor-pointer'}
-              `}
-            >
-              {tab.icon && <span className={`flex-shrink-0 ${sizeClasses[size].icon}`}>{tab.icon}</span>}
-              <span>{tab.label}</span>
-            </button>
-          );
-        })}
-      </div>
-
-      {/* Tab Content */}
-      <div className={`${orientation === 'vertical' ? 'flex-1' : sizeClasses[size].spacing}`}>
-        {tabs.map((tab) => (
-          <div
-            key={tab.id}
-            id={`panel-${tab.id}`}
-            role="tabpanel"
-            aria-labelledby={tab.id}
-            hidden={activeTab !== tab.id}
-            className={activeTab === tab.id ? 'animate-fade-in' : ''}
-          >
-            {activeTab === tab.id && tab.content}
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}
+import React, { useState, useEffect } from 'react';
+
+export interface Tab {
+  id: string;
+  label: string;
+  icon?: React.ReactNode;
+  content: React.ReactNode;
+  disabled?: boolean;
+}
+
+export interface TabsProps {
+  tabs: Tab[];
+  /** Controlled mode: Currently active tab ID */
+  activeTab?: string;
+  /** Uncontrolled mode: Initial tab ID (ignored if activeTab is provided) */
+  defaultTab?: string;
+  variant?: 'underline' | 'pill';
+  /** Orientation of tabs (default: 'horizontal') */
+  orientation?: 'horizontal' | 'vertical';
+  /** Size of tabs (default: 'md') */
+  size?: 'sm' | 'md' | 'lg';
+  /** Called when tab changes (required for controlled mode) */
+  onChange?: (tabId: string) => void;
+}
+
+export default function Tabs({ tabs, activeTab: controlledActiveTab, defaultTab, variant = 'underline', orientation = 'horizontal', size = 'md', onChange }: TabsProps) {
+  const [internalActiveTab, setInternalActiveTab] = useState(defaultTab || tabs[0]?.id);
+
+  // Controlled mode: use activeTab prop, Uncontrolled mode: use internal state
+  const isControlled = controlledActiveTab !== undefined;
+  const activeTab = isControlled ? controlledActiveTab : internalActiveTab;
+
+  // Ensure the activeTab exists in the current tabs array
+  // This handles the case where tabs array reference changes at the same time as activeTab
+  useEffect(() => {
+    const tabExists = tabs.some(tab => tab.id === activeTab);
+    if (!tabExists && tabs.length > 0) {
+      // If the activeTab doesn't exist in the new tabs array, use the first tab
+      if (isControlled) {
+        onChange?.(tabs[0].id);
+      } else {
+        setInternalActiveTab(tabs[0].id);
+      }
+    }
+  }, [tabs, activeTab, isControlled, onChange]);
+
+  const handleTabChange = (tabId: string) => {
+    if (!isControlled) {
+      setInternalActiveTab(tabId);
+    }
+    onChange?.(tabId);
+  };
+
+  // Size-specific classes
+  const sizeClasses = {
+    sm: {
+      padding: 'px-3 py-1.5',
+      text: 'text-xs',
+      icon: 'h-3.5 w-3.5',
+      gap: orientation === 'vertical' ? 'gap-1.5' : 'gap-4',
+      minWidth: orientation === 'vertical' ? 'min-w-[150px]' : '',
+      spacing: orientation === 'vertical' ? 'mt-4' : 'mt-4',
+    },
+    md: {
+      padding: 'px-4 py-2.5',
+      text: 'text-sm',
+      icon: 'h-4 w-4',
+      gap: orientation === 'vertical' ? 'gap-2' : 'gap-6',
+      minWidth: orientation === 'vertical' ? 'min-w-[200px]' : '',
+      spacing: orientation === 'vertical' ? 'mt-6' : 'mt-6',
+    },
+    lg: {
+      padding: 'px-5 py-3',
+      text: 'text-base',
+      icon: 'h-5 w-5',
+      gap: orientation === 'vertical' ? 'gap-3' : 'gap-8',
+      minWidth: orientation === 'vertical' ? 'min-w-[250px]' : '',
+      spacing: orientation === 'vertical' ? 'mt-8' : 'mt-8',
+    },
+  };
+
+  return (
+    <div className={`w-full ${orientation === 'vertical' ? `flex ${sizeClasses[size].gap}` : ''}`}>
+      {/* Tab Headers */}
+      <div
+        className={`
+          flex ${orientation === 'vertical' ? 'flex-col' : ''}
+          ${variant === 'underline'
+            ? orientation === 'vertical'
+              ? `border-r border-paper-200 ${sizeClasses[size].gap} pr-6`
+              : `border-b border-paper-200 ${sizeClasses[size].gap}`
+            : `${sizeClasses[size].gap} p-1 bg-paper-50 rounded-lg`
+          }
+          ${sizeClasses[size].minWidth}
+        `}
+        role="tablist"
+      >
+        {tabs.map((tab) => {
+          const isActive = activeTab === tab.id;
+
+          return (
+            <button
+              key={tab.id}
+              role="tab"
+              aria-selected={isActive}
+              aria-controls={`panel-${tab.id}`}
+              disabled={tab.disabled}
+              onClick={() => !tab.disabled && handleTabChange(tab.id)}
+              className={`
+                flex items-center gap-2 ${sizeClasses[size].padding} ${sizeClasses[size].text} font-medium transition-all duration-200
+                ${orientation === 'vertical' ? 'w-full justify-start' : ''}
+                ${
+                  variant === 'underline'
+                    ? isActive
+                      ? orientation === 'vertical'
+                        ? 'text-accent-900 border-r-2 border-accent-500 -mr-[1px]'
+                        : 'text-accent-900 border-b-2 border-accent-500 -mb-[1px]'
+                      : orientation === 'vertical'
+                      ? 'text-ink-600 hover:text-ink-900 border-r-2 border-transparent'
+                      : 'text-ink-600 hover:text-ink-900 border-b-2 border-transparent'
+                    : isActive
+                    ? 'bg-white text-accent-900 rounded-md shadow-xs'
+                    : 'text-ink-600 hover:text-ink-900 hover:bg-white/50 rounded-md'
+                }
+                ${tab.disabled ? 'opacity-40 cursor-not-allowed' : 'cursor-pointer'}
+              `}
+            >
+              {tab.icon && <span className={`flex-shrink-0 ${sizeClasses[size].icon}`}>{tab.icon}</span>}
+              <span>{tab.label}</span>
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Tab Content */}
+      <div className={`${orientation === 'vertical' ? 'flex-1' : sizeClasses[size].spacing}`}>
+        {tabs.map((tab) => (
+          <div
+            key={tab.id}
+            id={`panel-${tab.id}`}
+            role="tabpanel"
+            aria-labelledby={tab.id}
+            hidden={activeTab !== tab.id}
+            className={activeTab === tab.id ? 'animate-fade-in' : ''}
+          >
+            {activeTab === tab.id && tab.content}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}