@papernote/ui 1.1.0 → 1.3.0

package/src/components/Button.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { forwardRef } from 'react';
 import { Loader2 } from 'lucide-react';
 
 /**
@@ -31,6 +31,8 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
  * A versatile button component that supports multiple visual styles, sizes, icons,
  * loading states, and notification badges.
  *
+ * Supports ref forwarding for DOM access.
+ *
  * @example Basic usage
  * ```tsx
  * <Button variant="primary">Click me</Button>
@@ -38,9 +40,9 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
  *
  * @example With icon and loading
  * ```tsx
- * <Button 
- *   variant="secondary" 
- *   icon={<Save />} 
+ * <Button
+ *   variant="secondary"
+ *   icon={<Save />}
  *   loading={isSaving}
  * >
  *   Save Changes
@@ -49,16 +51,22 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
  *
  * @example Icon-only with badge
  * ```tsx
- * <Button 
- *   iconOnly 
- *   badge={5} 
+ * <Button
+ *   iconOnly
+ *   badge={5}
  *   badgeVariant="error"
  * >
  *   <Bell />
  * </Button>
  * ```
+ *
+ * @example With ref
+ * ```tsx
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * <Button ref={buttonRef}>Focusable</Button>
+ * ```
  */
-export default function Button({
+const Button = forwardRef<HTMLButtonElement, ButtonProps>(({
   variant = 'primary',
   size = 'md',
   loading = false,
@@ -72,7 +80,7 @@ export default function Button({
   disabled,
   className = '',
   ...props
-}: ButtonProps) {
+}, ref) => {
   const baseStyles = 'inline-flex items-center justify-center font-medium rounded-lg border transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-accent-400 disabled:opacity-40 disabled:cursor-not-allowed';
 
   const variantStyles = {
@@ -111,6 +119,7 @@ export default function Button({
 
   const buttonElement = (
     <button
+      ref={ref}
       className={`
         ${baseStyles}
         ${variantStyles[variant]}
@@ -163,4 +172,8 @@ export default function Button({
       </span>
     </div>
   );
-}
+});
+
+Button.displayName = 'Button';
+
+export default Button;

package/src/components/Card.tsx

@@ -1,10 +1,10 @@
-import React from 'react';
+import React, { forwardRef } from 'react';
 import { Skeleton } from './Loading';
 
 /**
  * Card component props
  */
-export interface CardProps {
+export interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onClick'> {
   /** Card content */
   children: React.ReactNode;
   /** Visual style variant affecting padding and shadow */
@@ -24,6 +24,8 @@ export interface CardProps {
 /**
  * Card - Container component with paper aesthetic and subtle shadow
  *
+ * Supports ref forwarding for DOM access.
+ *
  * A content container with paper texture, border, and shadow effects. Supports
  * different sizes, variants (padding/shadow levels), and loading states.
  *
@@ -53,8 +55,14 @@ export interface CardProps {
  *   <p>Content</p>
  * </Card>
  * ```
+ * 
+ * @example With ref
+ * ```tsx
+ * const cardRef = useRef<HTMLDivElement>(null);
+ * <Card ref={cardRef}>Content</Card>
+ * ```
  */
-export default function Card({
+const Card = forwardRef<HTMLDivElement, CardProps>(({
   children,
   variant = 'default',
   width = 'auto',
@@ -62,7 +70,8 @@ export default function Card({
   onClick,
   hoverable = false,
   loading = false,
-}: CardProps) {
+  ...htmlProps
+}, ref) => {
   const baseStyles = 'bg-white bg-subtle-grain border-2 border-paper-300 transition-shadow duration-200';
 
   const variantStyles = {
@@ -84,6 +93,8 @@ export default function Card({
 
   return (
     <div
+      ref={ref}
+      {...htmlProps}
       className={`${baseStyles} ${variantStyles[variant]} ${widthStyles[width]} ${interactiveStyles} ${className}`}
       onClick={!loading ? onClick : undefined}
       role={onClick ? 'button' : undefined}
@@ -101,7 +112,11 @@ export default function Card({
       )}
     </div>
   );
-}
+});
+
+Card.displayName = 'Card';
+
+export default Card;
 
 /**
  * CardHeader component props

package/src/components/CurrencyInput.stories.tsx

@@ -0,0 +1,290 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import CurrencyInput from './CurrencyInput';
+
+const meta = {
+  title: 'Forms/CurrencyInput',
+  component: CurrencyInput,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+Specialized input component for monetary values with automatic currency formatting.
+
+## Features
+- **Auto-formatting**: Formats currency with proper symbols and thousands separators
+- **Smart parsing**: Handles user input gracefully, removing invalid characters
+- **Multiple currencies**: Supports any currency code (USD, EUR, GBP, etc.)
+- **Localization**: Respects locale for number formatting
+- **Validation**: Built-in min/max value constraints
+- **Negative values**: Optional support for negative amounts
+- **Precision control**: Configurable decimal places
+
+## Usage
+
+\`\`\`tsx
+import { CurrencyInput } from 'notebook-ui';
+
+const [price, setPrice] = useState<number | null>(1234.56);
+
+<CurrencyInput
+  label="Price"
+  value={price}
+  onChange={setPrice}
+  currency="USD"
+  precision={2}
+/>
+\`\`\`
+        `,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    value: {
+      control: 'number',
+      description: 'Numeric value (unformatted)',
+      table: {
+        type: { summary: 'number | string' },
+      },
+    },
+    onChange: {
+      description: 'Callback when value changes (receives numeric value)',
+      table: {
+        type: { summary: '(value: number | null) => void' },
+      },
+    },
+    currency: {
+      control: 'text',
+      description: 'Currency code (ISO 4217)',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'USD' },
+      },
+    },
+    locale: {
+      control: 'text',
+      description: 'Locale for formatting',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'en-US' },
+      },
+    },
+    precision: {
+      control: 'number',
+      description: 'Number of decimal places',
+      table: {
+        type: { summary: 'number' },
+        defaultValue: { summary: '2' },
+      },
+    },
+    allowNegative: {
+      control: 'boolean',
+      description: 'Allow negative values',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    min: {
+      control: 'number',
+      description: 'Minimum allowed value',
+      table: {
+        type: { summary: 'number' },
+      },
+    },
+    max: {
+      control: 'number',
+      description: 'Maximum allowed value',
+      table: {
+        type: { summary: 'number' },
+      },
+    },
+  },
+} satisfies Meta<typeof CurrencyInput>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(1234.56);
+    return (
+      <div style={{ width: '300px' }}>
+        <CurrencyInput
+          label="Price"
+          value={value}
+          onChange={setValue}
+          helperText="Enter the product price"
+        />
+        <div style={{ marginTop: '1rem', fontSize: '0.875rem', color: '#64748b' }}>
+          Current value: {value !== null ? `$${value.toFixed(2)}` : 'null'}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const WithValidation: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(150);
+    const max = 100;
+    const hasError = value !== null && value > max;
+
+    return (
+      <div style={{ width: '300px' }}>
+        <CurrencyInput
+          label="Budget"
+          value={value}
+          onChange={setValue}
+          max={max}
+          validationState={hasError ? 'error' : value !== null && value > 0 ? 'success' : null}
+          validationMessage={hasError ? `Exceeds maximum budget of $${max}` : value !== null && value > 0 ? 'Within budget' : ''}
+        />
+      </div>
+    );
+  },
+};
+
+export const DifferentCurrencies: Story = {
+  render: () => {
+    const [usd, setUsd] = useState<number | null>(1234.56);
+    const [eur, setEur] = useState<number | null>(1234.56);
+    const [gbp, setGbp] = useState<number | null>(1234.56);
+    const [jpy, setJpy] = useState<number | null>(123456);
+
+    return (
+      <div style={{ width: '300px', display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+        <CurrencyInput
+          label="US Dollars"
+          value={usd}
+          onChange={setUsd}
+          currency="USD"
+          locale="en-US"
+        />
+        <CurrencyInput
+          label="Euros"
+          value={eur}
+          onChange={setEur}
+          currency="EUR"
+          locale="de-DE"
+        />
+        <CurrencyInput
+          label="British Pounds"
+          value={gbp}
+          onChange={setGbp}
+          currency="GBP"
+          locale="en-GB"
+        />
+        <CurrencyInput
+          label="Japanese Yen"
+          value={jpy}
+          onChange={setJpy}
+          currency="JPY"
+          locale="ja-JP"
+          precision={0}
+        />
+      </div>
+    );
+  },
+};
+
+export const WithNegativeValues: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(-500.75);
+    return (
+      <div style={{ width: '300px' }}>
+        <CurrencyInput
+          label="Profit/Loss"
+          value={value}
+          onChange={setValue}
+          allowNegative
+          helperText="Negative values allowed for losses"
+        />
+        <div style={{ marginTop: '1rem', fontSize: '0.875rem', color: '#64748b' }}>
+          Current value: {value !== null ? `$${value.toFixed(2)}` : 'null'}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const WithMinMax: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(50);
+    const min = 10;
+    const max = 100;
+
+    return (
+      <div style={{ width: '300px' }}>
+        <CurrencyInput
+          label="Amount"
+          value={value}
+          onChange={setValue}
+          min={min}
+          max={max}
+          helperText={`Min: $${min}, Max: $${max}`}
+        />
+        <div style={{ marginTop: '1rem', fontSize: '0.875rem', color: '#64748b' }}>
+          Current value: {value !== null ? `$${value.toFixed(2)}` : 'null'}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Required: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(null);
+    const hasError = value === null;
+
+    return (
+      <div style={{ width: '300px' }}>
+        <CurrencyInput
+          label="Donation Amount"
+          value={value}
+          onChange={setValue}
+          required
+          validationState={hasError ? 'error' : 'success'}
+          validationMessage={hasError ? 'Amount is required' : 'Thank you!'}
+        />
+      </div>
+    );
+  },
+};
+
+export const Clearable: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(1234.56);
+    return (
+      <div style={{ width: '300px' }}>
+        <CurrencyInput
+          label="Price"
+          value={value}
+          onChange={setValue}
+          clearable
+          onClear={() => setValue(null)}
+          helperText="Click X to clear the value"
+        />
+        <div style={{ marginTop: '1rem', fontSize: '0.875rem', color: '#64748b' }}>
+          Current value: {value !== null ? `$${value.toFixed(2)}` : 'null'}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <div style={{ width: '300px' }}>
+      <CurrencyInput
+        label="Price"
+        value={1234.56}
+        onChange={() => {}}
+        disabled
+        helperText="This field is disabled"
+      />
+    </div>
+  ),
+};

package/src/components/CurrencyInput.tsx

@@ -0,0 +1,193 @@
+import React, { forwardRef, useState, useEffect } from 'react';
+import Input, { InputProps } from './Input';
+
+export interface CurrencyInputProps extends Omit<InputProps, 'type' | 'value' | 'onChange' | 'prefix'> {
+  /** Numeric value (not formatted) */
+  value?: number | string;
+  /** Callback when value changes (receives numeric value) */
+  onChange?: (value: number | null) => void;
+  /** Currency code (default: 'USD') */
+  currency?: string;
+  /** Locale for formatting (default: 'en-US') */
+  locale?: string;
+  /** Number of decimal places (default: 2) */
+  precision?: number;
+  /** Allow negative values (default: false) */
+  allowNegative?: boolean;
+  /** Minimum allowed value */
+  min?: number;
+  /** Maximum allowed value */
+  max?: number;
+}
+
+/**
+ * CurrencyInput - Specialized input for monetary values
+ *
+ * Automatically formats currency values with proper symbols and thousands separators.
+ * Handles parsing and validation of numeric currency input.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <CurrencyInput
+ *   label="Price"
+ *   value={price}
+ *   onChange={setPrice}
+ *   currency="USD"
+ * />
+ * ```
+ *
+ * @example With validation
+ * ```tsx
+ * <CurrencyInput
+ *   label="Budget"
+ *   value={budget}
+ *   onChange={setBudget}
+ *   min={0}
+ *   max={10000}
+ *   validationState={budget > 10000 ? 'error' : null}
+ *   validationMessage={budget > 10000 ? 'Exceeds maximum budget' : ''}
+ * />
+ * ```
+ */
+const CurrencyInput = forwardRef<HTMLInputElement, CurrencyInputProps>(
+  (
+    {
+      value,
+      onChange,
+      currency = 'USD',
+      locale = 'en-US',
+      precision = 2,
+      allowNegative = false,
+      min,
+      max,
+      onBlur,
+      onFocus,
+      ...props
+    },
+    ref
+  ) => {
+    const [displayValue, setDisplayValue] = useState('');
+    const [isFocused, setIsFocused] = useState(false);
+
+    // Get currency symbol
+    const getCurrencySymbol = () => {
+      const formatter = new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+      });
+      const parts = formatter.formatToParts(0);
+      const symbolPart = parts.find(part => part.type === 'currency');
+      return symbolPart?.value || '$';
+    };
+
+    const currencySymbol = getCurrencySymbol();
+
+    // Format number as currency
+    const formatCurrency = (num: number): string => {
+      const formatter = new Intl.NumberFormat(locale, {
+        minimumFractionDigits: isFocused ? 0 : precision,
+        maximumFractionDigits: precision,
+      });
+      return formatter.format(num);
+    };
+
+    // Parse display value to number
+    const parseValue = (str: string): number | null => {
+      if (!str || str === '') return null;
+
+      // Remove all non-numeric characters except decimal point and minus sign
+      let cleaned = str.replace(/[^\d.-]/g, '');
+
+      // Handle multiple decimal points
+      const parts = cleaned.split('.');
+      if (parts.length > 2) {
+        cleaned = parts[0] + '.' + parts.slice(1).join('');
+      }
+
+      // Handle multiple minus signs (keep only first)
+      const minusCount = (cleaned.match(/-/g) || []).length;
+      if (minusCount > 1) {
+        const hasLeadingMinus = cleaned.startsWith('-');
+        cleaned = cleaned.replace(/-/g, '');
+        if (hasLeadingMinus) cleaned = '-' + cleaned;
+      }
+
+      // Parse to float
+      const num = parseFloat(cleaned);
+
+      if (isNaN(num)) return null;
+
+      // Apply precision
+      return Math.round(num * Math.pow(10, precision)) / Math.pow(10, precision);
+    };
+
+    // Update display value when external value changes
+    useEffect(() => {
+      if (value === undefined || value === null || value === '') {
+        setDisplayValue('');
+      } else {
+        const numValue = typeof value === 'string' ? parseFloat(value) : value;
+        if (!isNaN(numValue)) {
+          setDisplayValue(formatCurrency(numValue));
+        }
+      }
+    }, [value, isFocused]);
+
+    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+      const inputValue = e.target.value;
+      setDisplayValue(inputValue);
+
+      const numValue = parseValue(inputValue);
+
+      // Validate constraints
+      if (numValue !== null) {
+        if (!allowNegative && numValue < 0) return;
+        if (min !== undefined && numValue < min) return;
+        if (max !== undefined && numValue > max) return;
+      }
+
+      onChange?.(numValue);
+    };
+
+    const handleFocus = (e: React.FocusEvent<HTMLInputElement>) => {
+      setIsFocused(true);
+      // Remove formatting when focused for easier editing
+      if (value !== undefined && value !== null && value !== '') {
+        const numValue = typeof value === 'string' ? parseFloat(value) : value;
+        if (!isNaN(numValue)) {
+          setDisplayValue(numValue.toString());
+        }
+      }
+      onFocus?.(e);
+    };
+
+    const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+      setIsFocused(false);
+      // Reformat on blur
+      const numValue = parseValue(displayValue);
+      if (numValue !== null) {
+        setDisplayValue(formatCurrency(numValue));
+      } else if (displayValue === '') {
+        setDisplayValue('');
+      }
+      onBlur?.(e);
+    };
+
+    return (
+      <Input
+        ref={ref}
+        type="text"
+        value={displayValue}
+        onChange={handleChange}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        prefix={currencySymbol}
+        {...props}
+      />
+    );
+  }
+);
+
+CurrencyInput.displayName = 'CurrencyInput';
+
+export default CurrencyInput;