@papernote/ui 1.2.0 → 1.3.1

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/Text.stories.tsx

@@ -0,0 +1,273 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Text } from './Text';
+import Stack from './Stack';
+
+const meta = {
+  title: 'Typography/Text',
+  component: Text,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+Text component for consistent typography across the application.
+
+## Features
+- **Semantic elements**: Render as p, span, div, h1-h6, or label
+- **Size scale**: xs, sm, base, lg, xl, 2xl
+- **Weight options**: normal, medium, semibold, bold
+- **Color variants**: primary, secondary, muted, accent, error, success, warning
+- **Text alignment**: left, center, right
+- **Truncation**: Single line truncate or multi-line clamp (1-6 lines)
+- **Transform**: uppercase, lowercase, capitalize
+
+## Usage
+
+\`\`\`tsx
+import { Text } from 'notebook-ui';
+
+<Text size="lg" weight="semibold" color="primary">
+  Hello World
+</Text>
+
+<Text color="warning">Warning message</Text>
+
+<Text truncate>This text will be truncated...</Text>
+
+<Text lineClamp={2}>
+  This text will be clamped to 2 lines with ellipsis...
+</Text>
+\`\`\`
+        `,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    as: {
+      control: 'select',
+      options: ['p', 'span', 'div', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'label'],
+      description: 'HTML element to render',
+    },
+    size: {
+      control: 'select',
+      options: ['xs', 'sm', 'base', 'lg', 'xl', '2xl'],
+      description: 'Font size',
+    },
+    weight: {
+      control: 'select',
+      options: ['normal', 'medium', 'semibold', 'bold'],
+      description: 'Font weight',
+    },
+    color: {
+      control: 'select',
+      options: ['primary', 'secondary', 'muted', 'accent', 'error', 'success', 'warning'],
+      description: 'Text color',
+    },
+    align: {
+      control: 'select',
+      options: ['left', 'center', 'right'],
+      description: 'Text alignment',
+    },
+    truncate: {
+      control: 'boolean',
+      description: 'Truncate text with ellipsis (single line)',
+    },
+    lineClamp: {
+      control: 'select',
+      options: [undefined, 1, 2, 3, 4, 5, 6],
+      description: 'Clamp text to specific number of lines',
+    },
+    transform: {
+      control: 'select',
+      options: [undefined, 'uppercase', 'lowercase', 'capitalize', 'normal'],
+      description: 'Text transform',
+    },
+  },
+} satisfies Meta<typeof Text>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: 'The quick brown fox jumps over the lazy dog.',
+  },
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <Stack spacing="sm">
+      <Text size="xs">Extra Small (xs) - 12px</Text>
+      <Text size="sm">Small (sm) - 14px</Text>
+      <Text size="base">Base (base) - 16px</Text>
+      <Text size="lg">Large (lg) - 18px</Text>
+      <Text size="xl">Extra Large (xl) - 20px</Text>
+      <Text size="2xl">2X Large (2xl) - 24px</Text>
+    </Stack>
+  ),
+};
+
+export const Weights: Story = {
+  render: () => (
+    <Stack spacing="sm">
+      <Text weight="normal">Normal weight - 400</Text>
+      <Text weight="medium">Medium weight - 500</Text>
+      <Text weight="semibold">Semibold weight - 600</Text>
+      <Text weight="bold">Bold weight - 700</Text>
+    </Stack>
+  ),
+};
+
+/**
+ * All available color variants including the new `warning` color.
+ */
+export const Colors: Story = {
+  render: () => (
+    <Stack spacing="sm">
+      <Text color="primary">Primary - Default text color</Text>
+      <Text color="secondary">Secondary - Slightly muted</Text>
+      <Text color="muted">Muted - Subdued text</Text>
+      <Text color="accent">Accent - Branded color</Text>
+      <Text color="success">Success - Positive feedback</Text>
+      <Text color="warning">Warning - Caution messages</Text>
+      <Text color="error">Error - Error messages</Text>
+    </Stack>
+  ),
+};
+
+/**
+ * The warning color is useful for displaying caution messages,
+ * threshold alerts, or status indicators that need attention.
+ */
+export const WarningColor: Story = {
+  render: () => (
+    <Stack spacing="md">
+      <Text color="warning" size="lg" weight="semibold">
+        Warning: Your subscription expires in 3 days
+      </Text>
+      <Text color="warning">
+        Storage usage is at 85% capacity
+      </Text>
+      <Text color="warning" size="sm">
+        This action cannot be undone
+      </Text>
+    </Stack>
+  ),
+};
+
+export const Alignment: Story = {
+  render: () => (
+    <Stack spacing="sm" style={{ width: '300px' }}>
+      <Text align="left">Left aligned text</Text>
+      <Text align="center">Center aligned text</Text>
+      <Text align="right">Right aligned text</Text>
+    </Stack>
+  ),
+};
+
+export const Truncate: Story = {
+  render: () => (
+    <div style={{ width: '200px' }}>
+      <Text truncate>
+        This is a very long text that will be truncated with an ellipsis when it overflows the container.
+      </Text>
+    </div>
+  ),
+};
+
+export const LineClamp: Story = {
+  render: () => (
+    <Stack spacing="lg">
+      <div style={{ width: '300px' }}>
+        <Text size="sm" color="muted" weight="medium">1 Line Clamp:</Text>
+        <Text lineClamp={1}>
+          This is a very long text that will be clamped to one line with an ellipsis at the end.
+        </Text>
+      </div>
+      <div style={{ width: '300px' }}>
+        <Text size="sm" color="muted" weight="medium">2 Line Clamp:</Text>
+        <Text lineClamp={2}>
+          This is a very long text that will be clamped to two lines with an ellipsis at the end. 
+          It demonstrates how multi-line truncation works with the lineClamp prop.
+        </Text>
+      </div>
+      <div style={{ width: '300px' }}>
+        <Text size="sm" color="muted" weight="medium">3 Line Clamp:</Text>
+        <Text lineClamp={3}>
+          This is a very long text that will be clamped to three lines with an ellipsis at the end.
+          It demonstrates how multi-line truncation works with the lineClamp prop. This is useful
+          for card descriptions or preview text that needs to fit a specific space.
+        </Text>
+      </div>
+    </Stack>
+  ),
+};
+
+export const Transform: Story = {
+  render: () => (
+    <Stack spacing="sm">
+      <Text transform="uppercase">uppercase text</Text>
+      <Text transform="lowercase">LOWERCASE TEXT</Text>
+      <Text transform="capitalize">capitalize each word</Text>
+      <Text transform="normal">Normal Text (no transform)</Text>
+    </Stack>
+  ),
+};
+
+export const SemanticElements: Story = {
+  render: () => (
+    <Stack spacing="sm">
+      <Text as="h1" size="2xl" weight="bold">Heading 1</Text>
+      <Text as="h2" size="xl" weight="semibold">Heading 2</Text>
+      <Text as="h3" size="lg" weight="semibold">Heading 3</Text>
+      <Text as="p">Paragraph text</Text>
+      <Text as="span" color="muted">Inline span text</Text>
+      <Text as="label" weight="medium">Label text</Text>
+    </Stack>
+  ),
+};
+
+export const CombinedStyles: Story = {
+  render: () => (
+    <Stack spacing="md">
+      <Text as="h1" size="2xl" weight="bold" color="primary">
+        Dashboard Overview
+      </Text>
+      <Text color="secondary">
+        Welcome back! Here's what's happening with your projects today.
+      </Text>
+      <Text size="sm" color="muted">
+        Last updated: 5 minutes ago
+      </Text>
+      <Text color="success" weight="medium">
+        All systems operational
+      </Text>
+      <Text color="warning" weight="medium">
+        2 items need attention
+      </Text>
+      <Text color="error" weight="medium">
+        1 critical error detected
+      </Text>
+    </Stack>
+  ),
+};
+
+export const StatusMessages: Story = {
+  render: () => (
+    <Stack spacing="sm">
+      <Text color="success" size="sm">
+        ✓ Changes saved successfully
+      </Text>
+      <Text color="warning" size="sm">
+        ⚠ Your session will expire in 5 minutes
+      </Text>
+      <Text color="error" size="sm">
+        ✗ Failed to connect to server
+      </Text>
+      <Text color="muted" size="sm">
+        Last sync: 2 hours ago
+      </Text>
+    </Stack>
+  ),
+};

package/src/components/Text.tsx

@@ -1,19 +1,21 @@
 // Text Component - Typography with consistent styling
 // Provides semantic text elements with design system styling
 
-import React from 'react';
+import React, { forwardRef } from 'react';
 
-export interface TextProps {
+type TextElement = 'p' | 'span' | 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'label';
+
+export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'> {
   /** Text content */
   children: React.ReactNode;
   /** HTML element to render */
-  as?: 'p' | 'span' | 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'label';
+  as?: TextElement;
   /** Size variant */
   size?: 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl';
   /** Weight variant */
   weight?: 'normal' | 'medium' | 'semibold' | 'bold';
   /** Color variant */
-  color?: 'primary' | 'secondary' | 'muted' | 'accent' | 'error' | 'success';
+  color?: 'primary' | 'secondary' | 'muted' | 'accent' | 'error' | 'success' | 'warning';
   /** Text alignment */
   align?: 'left' | 'center' | 'right';
   /** Truncate text with ellipsis (single line) */
@@ -29,6 +31,8 @@ export interface TextProps {
 /**
  * Text component for consistent typography across the application.
  * 
+ * Supports ref forwarding for DOM access.
+ * 
  * Size scale:
  * - xs: 0.75rem (12px)
  * - sm: 0.875rem (14px)
@@ -36,8 +40,21 @@ export interface TextProps {
  * - lg: 1.125rem (18px)
  * - xl: 1.25rem (20px)
  * - 2xl: 1.5rem (24px)
+ * 
+ * @example
+ * ```tsx
+ * <Text size="lg" weight="semibold" color="primary">
+ *   Hello World
+ * </Text>
+ * 
+ * <Text color="warning">Warning message</Text>
+ * 
+ * // With ref
+ * const textRef = useRef<HTMLParagraphElement>(null);
+ * <Text ref={textRef}>Measurable text</Text>
+ * ```
  */
-export const Text: React.FC<TextProps> = ({
+export const Text = forwardRef<HTMLElement, TextProps>(({
   children,
   as: Component = 'p',
   size = 'base',
@@ -48,7 +65,8 @@ export const Text: React.FC<TextProps> = ({
   lineClamp,
   transform,
   className = '',
-}) => {
+  ...htmlProps
+}, ref) => {
   const sizeClasses = {
     xs: 'text-xs',
     sm: 'text-sm',
@@ -72,6 +90,7 @@ export const Text: React.FC<TextProps> = ({
     accent: 'text-primary-600',
     error: 'text-error-600',
     success: 'text-success-600',
+    warning: 'text-warning-600',
   };
 
   const alignClasses = {
@@ -109,10 +128,16 @@ export const Text: React.FC<TextProps> = ({
   ].filter(Boolean).join(' ');
 
   return (
-    <Component className={classes}>
+    <Component 
+      ref={ref as any} 
+      className={classes}
+      {...htmlProps}
+    >
       {children}
     </Component>
   );
-};
+});
+
+Text.displayName = 'Text';
 
 export default Text;

package/src/components/Textarea.tsx

@@ -1,5 +1,5 @@
 import { forwardRef, useEffect, useRef } from 'react';
-import { AlertCircle, CheckCircle, AlertTriangle } from 'lucide-react';
+import { AlertCircle, CheckCircle, AlertTriangle, Loader2 } from 'lucide-react';
 
 export type ValidationState = 'error' | 'success' | 'warning' | null;
 
@@ -18,6 +18,8 @@ export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextArea
   maxRows?: number;
   /** Resize behavior (default: 'vertical') - overridden to 'none' when autoExpand is true */
   resize?: 'none' | 'vertical' | 'horizontal' | 'both';
+  /** Show loading spinner (for async operations like auto-save) */
+  loading?: boolean;
 }
 
 const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
@@ -33,6 +35,7 @@ const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
       minRows = 2,
       maxRows = 10,
       resize = 'vertical',
+      loading = false,
       className = '',
       id,
       value,
@@ -136,26 +139,34 @@ const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
           </label>
         )}
 
-        {/* Textarea */}
-        <textarea
-          ref={textareaRef}
-          id={textareaId}
-          value={value}
-          maxLength={maxLength}
-          rows={autoExpand ? minRows : rows}
-          className={`
-            block w-full px-4 py-3 border rounded-lg text-sm text-ink-800 placeholder-ink-400
-            bg-white bg-subtle-grain transition-all duration-200
-            focus:outline-none focus:ring-2 ${getResizeClass()}
-            disabled:bg-paper-100 disabled:text-ink-400 disabled:cursor-not-allowed disabled:opacity-60
-            ${getValidationClasses()}
-            ${className}
-          `}
-          aria-invalid={validationState === 'error'}
-          aria-describedby={validationMessage || helperText ? `${textareaId}-help` : undefined}
-          aria-required={props.required}
-          {...props}
-        />
+        {/* Textarea with loading indicator */}
+        <div className="relative">
+          <textarea
+            ref={textareaRef}
+            id={textareaId}
+            value={value}
+            maxLength={maxLength}
+            rows={autoExpand ? minRows : rows}
+            className={`
+              block w-full px-4 py-3 border rounded-lg text-sm text-ink-800 placeholder-ink-400
+              bg-white bg-subtle-grain transition-all duration-200
+              focus:outline-none focus:ring-2 ${getResizeClass()}
+              disabled:bg-paper-100 disabled:text-ink-400 disabled:cursor-not-allowed disabled:opacity-60
+              ${getValidationClasses()}
+              ${loading ? 'pr-10' : ''}
+              ${className}
+            `}
+            aria-invalid={validationState === 'error'}
+            aria-describedby={validationMessage || helperText ? `${textareaId}-help` : undefined}
+            aria-required={props.required}
+            {...props}
+          />
+          {loading && (
+            <div className="absolute top-3 right-3 pointer-events-none">
+              <Loader2 className="h-5 w-5 text-ink-400 animate-spin" />
+            </div>
+          )}
+        </div>
 
         {/* Helper Text / Validation Message / Character Count */}
         {((helperText || validationMessage) || (showCharCount && maxLength)) && (

package/src/components/index.ts

@@ -13,7 +13,7 @@ export { default as Select } from './Select';
 export type { SelectProps, SelectOption, SelectHandle } from './Select';
 
 export { default as MultiSelect } from './MultiSelect';
-export type { MultiSelectProps, MultiSelectOption } from './MultiSelect';
+export type { MultiSelectProps, MultiSelectOption, MultiSelectHandle } from './MultiSelect';
 
 export { default as Switch } from './Switch';
 export type { SwitchProps } from './Switch';
@@ -205,9 +205,6 @@ export { default as StepIndicator } from './StepIndicator';
 export type { StepIndicatorProps, Step } from './StepIndicator';
 
 // Data Display Components
-export { default as Table } from './Table';
-export type { TableProps, Column, SortDirection } from './Table';
-
 export { default as Badge } from './Badge';
 export type { BadgeProps } from './Badge';
 

package/dist/components/Table.d.ts

@@ -1,26 +0,0 @@
-import React from 'react';
-export type SortDirection = 'asc' | 'desc' | null;
-export interface Column<T> {
-    key: string;
-    header: string;
-    accessor?: (row: T) => React.ReactNode;
-    sortable?: boolean;
-    filterable?: boolean;
-    width?: string;
-}
-export interface TableProps<T> {
-    data: T[];
-    columns: Column<T>[];
-    keyExtractor: (row: T) => string;
-    selectable?: boolean;
-    expandable?: boolean;
-    onRowSelect?: (selectedRows: string[]) => void;
-    renderExpandedRow?: (row: T) => React.ReactNode;
-    emptyState?: React.ReactNode;
-    className?: string;
-    onSort?: (columnKey: string, direction: SortDirection) => void;
-    sortColumn?: string | null;
-    sortDirection?: SortDirection;
-}
-export default function Table<T>({ data, columns, keyExtractor, selectable, expandable, onRowSelect, renderExpandedRow, emptyState, className, onSort, sortColumn: externalSortColumn, sortDirection: externalSortDirection, }: TableProps<T>): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=Table.d.ts.map

package/dist/components/Table.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Table.d.ts","sourceRoot":"","sources":["../../src/components/Table.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmB,MAAM,OAAO,CAAC;AAGxC,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;AAElD,MAAM,WAAW,MAAM,CAAC,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IACrB,YAAY,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC/C,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC;IAChD,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,CAAC,EAAE,EAC/B,IAAI,EACJ,OAAO,EACP,YAAY,EACZ,UAAkB,EAClB,UAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,SAAc,EACd,MAAM,EACN,UAAU,EAAE,kBAAkB,EAC9B,aAAa,EAAE,qBAAqB,GACrC,EAAE,UAAU,CAAC,CAAC,CAAC,2CAoMf"}