@papernote/ui 1.6.0 → 1.7.0

package/src/components/FormulaAutocomplete.tsx

@@ -0,0 +1,417 @@
+import React, { useState, useEffect, useRef, useCallback, useMemo } from 'react';
+import { createPortal } from 'react-dom';
+import {
+  FORMULA_DEFINITIONS,
+  searchFormulas,
+  getFormula,
+  FORMULA_CATEGORIES,
+  FormulaDefinition,
+  FormulaCategory,
+} from '../utils/formulaDefinitions';
+
+export interface FormulaAutocompleteProps {
+  /** Current input value */
+  value: string;
+  /** Callback when value changes */
+  onChange: (value: string) => void;
+  /** Callback when editing is complete */
+  onComplete: () => void;
+  /** Callback to cancel editing */
+  onCancel: () => void;
+  /** Position for the dropdown */
+  anchorRect: DOMRect | null;
+  /** Auto focus the input */
+  autoFocus?: boolean;
+  /** Custom class name */
+  className?: string;
+}
+
+interface FormulaHint {
+  formula: FormulaDefinition;
+  currentParamIndex: number;
+}
+
+/**
+ * FormulaAutocomplete - Input with formula intellisense
+ *
+ * Features:
+ * - Autocomplete dropdown when typing after '='
+ * - Function signature hints while typing parameters
+ * - Category-based browsing
+ * - Keyboard navigation
+ */
+const FormulaAutocomplete: React.FC<FormulaAutocompleteProps> = ({
+  value,
+  onChange,
+  onComplete,
+  onCancel,
+  anchorRect,
+  autoFocus = true,
+  className = '',
+}) => {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [showDropdown, setShowDropdown] = useState(false);
+  const [showHint, setShowHint] = useState(false);
+  const [hint, setHint] = useState<FormulaHint | null>(null);
+  const [activeCategory, setActiveCategory] = useState<FormulaCategory | null>(null);
+
+  // Parse the current formula context
+  const formulaContext = useMemo(() => {
+    if (!value.startsWith('=')) {
+      return { isFormula: false, query: '', inFunction: false, functionName: '', paramIndex: 0 };
+    }
+
+    const formulaText = value.substring(1);
+
+    // Check if we're typing a function name (before opening paren)
+    const functionMatch = formulaText.match(/^([A-Z]+)$/i);
+    if (functionMatch) {
+      return {
+        isFormula: true,
+        query: functionMatch[1].toUpperCase(),
+        inFunction: false,
+        functionName: '',
+        paramIndex: 0,
+      };
+    }
+
+    // Check if we're inside a function (after opening paren)
+    const insideFunctionMatch = formulaText.match(/^([A-Z]+)\((.*)$/i);
+    if (insideFunctionMatch) {
+      const functionName = insideFunctionMatch[1].toUpperCase();
+      const params = insideFunctionMatch[2];
+
+      // Count commas to determine parameter index (accounting for nested parens)
+      let paramIndex = 0;
+      let parenDepth = 0;
+      for (const char of params) {
+        if (char === '(') parenDepth++;
+        else if (char === ')') parenDepth--;
+        else if (char === ',' && parenDepth === 0) paramIndex++;
+      }
+
+      return {
+        isFormula: true,
+        query: '',
+        inFunction: true,
+        functionName,
+        paramIndex,
+      };
+    }
+
+    // Just '=' or other expression
+    return {
+      isFormula: true,
+      query: formulaText.toUpperCase(),
+      inFunction: false,
+      functionName: '',
+      paramIndex: 0,
+    };
+  }, [value]);
+
+  // Get matching formulas for dropdown
+  const matchingFormulas = useMemo(() => {
+    if (!formulaContext.isFormula || formulaContext.inFunction) return [];
+
+    if (activeCategory) {
+      const categoryFormulas = FORMULA_DEFINITIONS.filter(f => f.category === activeCategory);
+      if (formulaContext.query) {
+        return categoryFormulas.filter(f => f.name.startsWith(formulaContext.query));
+      }
+      return categoryFormulas;
+    }
+
+    if (formulaContext.query) {
+      return searchFormulas(formulaContext.query);
+    }
+
+    // Show all formulas grouped by first letter when just '='
+    return FORMULA_DEFINITIONS.slice(0, 20); // Show first 20 as default
+  }, [formulaContext, activeCategory]);
+
+  // Update hint when inside a function
+  useEffect(() => {
+    if (formulaContext.inFunction && formulaContext.functionName) {
+      const formula = getFormula(formulaContext.functionName);
+      if (formula) {
+        setHint({
+          formula,
+          currentParamIndex: formulaContext.paramIndex,
+        });
+        setShowHint(true);
+        setShowDropdown(false);
+      } else {
+        setShowHint(false);
+        setHint(null);
+      }
+    } else if (formulaContext.isFormula && !formulaContext.inFunction) {
+      setShowDropdown(true);
+      setShowHint(false);
+      setHint(null);
+    } else {
+      setShowDropdown(false);
+      setShowHint(false);
+      setHint(null);
+    }
+  }, [formulaContext]);
+
+  // Reset selected index when matches change
+  useEffect(() => {
+    setSelectedIndex(0);
+  }, [matchingFormulas.length]);
+
+  // Auto-focus
+  useEffect(() => {
+    if (autoFocus && inputRef.current) {
+      inputRef.current.focus();
+      inputRef.current.select();
+    }
+  }, [autoFocus]);
+
+  // Scroll selected item into view
+  useEffect(() => {
+    if (dropdownRef.current && showDropdown) {
+      const selectedItem = dropdownRef.current.querySelector(`[data-index="${selectedIndex}"]`);
+      if (selectedItem) {
+        selectedItem.scrollIntoView({ block: 'nearest' });
+      }
+    }
+  }, [selectedIndex, showDropdown]);
+
+  // Handle keyboard navigation
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (showDropdown && matchingFormulas.length > 0) {
+        switch (e.key) {
+          case 'ArrowDown':
+            e.preventDefault();
+            setSelectedIndex((prev) => Math.min(prev + 1, matchingFormulas.length - 1));
+            break;
+          case 'ArrowUp':
+            e.preventDefault();
+            setSelectedIndex((prev) => Math.max(prev - 1, 0));
+            break;
+          case 'Tab':
+          case 'Enter':
+            e.preventDefault();
+            insertFormula(matchingFormulas[selectedIndex]);
+            break;
+          case 'Escape':
+            e.preventDefault();
+            if (showDropdown) {
+              setShowDropdown(false);
+            } else {
+              onCancel();
+            }
+            break;
+        }
+      } else {
+        if (e.key === 'Enter') {
+          e.preventDefault();
+          onComplete();
+        } else if (e.key === 'Escape') {
+          e.preventDefault();
+          onCancel();
+        }
+      }
+    },
+    [showDropdown, matchingFormulas, selectedIndex, onComplete, onCancel]
+  );
+
+  // Insert selected formula
+  const insertFormula = useCallback(
+    (formula: FormulaDefinition) => {
+      // Replace the current query with the formula name and open paren
+      const newValue = `=${formula.name}(`;
+      onChange(newValue);
+      setShowDropdown(false);
+      inputRef.current?.focus();
+    },
+    [onChange]
+  );
+
+  // Calculate dropdown position
+  const dropdownPosition = useMemo(() => {
+    if (!anchorRect) return { top: 0, left: 0 };
+    return {
+      top: anchorRect.bottom + 2,
+      left: anchorRect.left,
+    };
+  }, [anchorRect]);
+
+  // Prevent blur when clicking inside dropdown
+  const handleDropdownMouseDown = useCallback((e: React.MouseEvent) => {
+    e.preventDefault(); // Prevents input from losing focus
+  }, []);
+
+  // Render parameter hint
+  const renderHint = () => {
+    if (!showHint || !hint) return null;
+
+    return createPortal(
+      <div
+        className="fixed z-[9999] bg-white border border-stone-200 rounded-lg shadow-lg p-3 max-w-md"
+        style={{
+          top: dropdownPosition.top,
+          left: dropdownPosition.left,
+        }}
+        onMouseDown={handleDropdownMouseDown}
+      >
+        {/* Function name and syntax */}
+        <div className="font-mono text-sm mb-2">
+          <span className="text-primary-600 font-semibold">{hint.formula.name}</span>
+          <span className="text-ink-500">(</span>
+          {hint.formula.parameters.map((param, idx) => (
+            <span key={param.name}>
+              {idx > 0 && <span className="text-ink-500">, </span>}
+              <span
+                className={`${
+                  idx === hint.currentParamIndex
+                    ? 'bg-primary-100 text-primary-700 px-1 rounded font-semibold'
+                    : param.optional
+                    ? 'text-ink-400'
+                    : 'text-ink-600'
+                }`}
+              >
+                {param.optional ? `[${param.name}]` : param.name}
+              </span>
+            </span>
+          ))}
+          <span className="text-ink-500">)</span>
+        </div>
+
+        {/* Description */}
+        <div className="text-xs text-ink-600 mb-2">{hint.formula.description}</div>
+
+        {/* Current parameter description */}
+        {hint.formula.parameters[hint.currentParamIndex] && (
+          <div className="text-xs bg-paper-50 p-2 rounded border border-stone-100">
+            <span className="font-semibold text-primary-600">
+              {hint.formula.parameters[hint.currentParamIndex].name}:
+            </span>{' '}
+            <span className="text-ink-600">
+              {hint.formula.parameters[hint.currentParamIndex].description}
+            </span>
+          </div>
+        )}
+      </div>,
+      document.body
+    );
+  };
+
+  // Render autocomplete dropdown
+  const renderDropdown = () => {
+    if (!showDropdown || matchingFormulas.length === 0) return null;
+
+    return createPortal(
+      <div
+        ref={dropdownRef}
+        className="fixed z-[9999] bg-white border border-stone-200 rounded-lg shadow-lg overflow-hidden"
+        style={{
+          top: dropdownPosition.top,
+          left: dropdownPosition.left,
+          minWidth: 320,
+          maxWidth: 450,
+          maxHeight: 300,
+        }}
+        onMouseDown={handleDropdownMouseDown}
+      >
+        {/* Category tabs */}
+        <div className="flex flex-wrap gap-1 p-2 border-b border-stone-100 bg-paper-50">
+          <button
+            className={`px-2 py-1 text-xs rounded ${
+              activeCategory === null
+                ? 'bg-primary-500 text-white'
+                : 'bg-white text-ink-600 hover:bg-stone-100'
+            }`}
+            onClick={() => {
+              setActiveCategory(null);
+              inputRef.current?.focus();
+            }}
+          >
+            All
+          </button>
+          {FORMULA_CATEGORIES.map((cat) => (
+            <button
+              key={cat}
+              className={`px-2 py-1 text-xs rounded ${
+                activeCategory === cat
+                  ? 'bg-primary-500 text-white'
+                  : 'bg-white text-ink-600 hover:bg-stone-100'
+              }`}
+              onClick={() => {
+                setActiveCategory(cat);
+                inputRef.current?.focus();
+              }}
+            >
+              {cat}
+            </button>
+          ))}
+        </div>
+
+        {/* Formula list */}
+        <div className="overflow-y-auto" style={{ maxHeight: 220 }}>
+          {matchingFormulas.map((formula, index) => (
+            <div
+              key={formula.name}
+              data-index={index}
+              className={`px-3 py-2 cursor-pointer border-b border-stone-50 ${
+                index === selectedIndex ? 'bg-primary-50' : 'hover:bg-paper-50'
+              }`}
+              onClick={() => insertFormula(formula)}
+              onMouseEnter={() => setSelectedIndex(index)}
+            >
+              <div className="flex items-center gap-2">
+                <span className="font-mono font-semibold text-primary-600 text-sm">
+                  {formula.name}
+                </span>
+                <span className="text-xs text-ink-400 bg-stone-100 px-1.5 py-0.5 rounded">
+                  {formula.category}
+                </span>
+              </div>
+              <div className="text-xs text-ink-500 mt-0.5 truncate">{formula.description}</div>
+              <div className="font-mono text-xs text-ink-400 mt-0.5">{formula.syntax}</div>
+            </div>
+          ))}
+        </div>
+
+        {/* Footer hint */}
+        <div className="px-3 py-1.5 bg-paper-50 border-t border-stone-100 text-xs text-ink-400">
+          <span className="font-medium">↑↓</span> navigate
+          <span className="mx-2">·</span>
+          <span className="font-medium">Tab/Enter</span> insert
+          <span className="mx-2">·</span>
+          <span className="font-medium">Esc</span> close
+        </div>
+      </div>,
+      document.body
+    );
+  };
+
+  return (
+    <>
+      <input
+        ref={inputRef}
+        type="text"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        onKeyDown={handleKeyDown}
+        onBlur={() => {
+          // Delay to allow click on dropdown
+          setTimeout(() => {
+            setShowDropdown(false);
+            setShowHint(false);
+          }, 150);
+        }}
+        className={`w-full h-full border-none outline-none bg-transparent font-mono text-sm ${className}`}
+        style={{ margin: '-4px', padding: '4px' }}
+      />
+      {renderDropdown()}
+      {renderHint()}
+    </>
+  );
+};
+
+export default FormulaAutocomplete;

package/src/components/Select.tsx

@@ -83,6 +83,8 @@ export interface SelectProps {
   size?: 'sm' | 'md' | 'lg';
   /** Mobile display mode - 'auto' uses BottomSheet on mobile, 'dropdown' always uses dropdown, 'native' uses native select on mobile */
   mobileMode?: 'auto' | 'dropdown' | 'native';
+  /** Render dropdown via portal (default: true). Set to false when overflow clipping is not an issue */
+  usePortal?: boolean;
 }
 
 // Size classes for trigger button
@@ -191,13 +193,16 @@ const Select = forwardRef<SelectHandle, SelectProps>(
     virtualItemHeight = 42,
     size = 'md',
     mobileMode = 'auto',
+    usePortal = true,
   } = props;
   const [isOpen, setIsOpen] = useState(false);
   const [searchQuery, setSearchQuery] = useState('');
   const [scrollTop, setScrollTop] = useState(0);
   const [activeDescendant] = useState<string | undefined>(undefined);
+  const [dropdownPosition, setDropdownPosition] = useState<{ top: number; left: number; width: number; placement: 'bottom' | 'top' } | null>(null);
   const selectRef = useRef<HTMLDivElement>(null);
   const buttonRef = useRef<HTMLButtonElement>(null);
+  const dropdownRef = useRef<HTMLDivElement>(null);
   const searchInputRef = useRef<HTMLInputElement>(null);
   const mobileSearchInputRef = useRef<HTMLInputElement>(null);
   const listRef = useRef<HTMLDivElement>(null);
@@ -313,9 +318,14 @@ const Select = forwardRef<SelectHandle, SelectProps>(
   // Handle click outside (desktop dropdown only)
   useEffect(() => {
     if (useMobileSheet) return; // Mobile sheet handles its own closing
-    
+
     const handleClickOutside = (event: MouseEvent) => {
-      if (selectRef.current && !selectRef.current.contains(event.target as Node)) {
+      const target = event.target as Node;
+      // Check if click is outside both the select trigger and the dropdown portal
+      const isOutsideSelect = selectRef.current && !selectRef.current.contains(target);
+      const isOutsideDropdown = dropdownRef.current && !dropdownRef.current.contains(target);
+
+      if (isOutsideSelect && isOutsideDropdown) {
         setIsOpen(false);
         setSearchQuery('');
       }
@@ -342,6 +352,55 @@ const Select = forwardRef<SelectHandle, SelectProps>(
     }
   }, [isOpen, searchable, useMobileSheet]);
 
+  // Calculate dropdown position with collision detection and scroll/resize handling
+  useEffect(() => {
+    if (!isOpen || useMobileSheet || !usePortal) {
+      setDropdownPosition(null);
+      return;
+    }
+
+    const updatePosition = () => {
+      if (!buttonRef.current) return;
+
+      const rect = buttonRef.current.getBoundingClientRect();
+      const dropdownHeight = 240; // max-h-60 = 15rem = 240px
+      const gap = 2; // Small gap to visually connect to trigger
+      const viewportHeight = window.innerHeight;
+
+      // Check if there's enough space below
+      const spaceBelow = viewportHeight - rect.bottom;
+      const spaceAbove = rect.top;
+      const hasSpaceBelow = spaceBelow >= dropdownHeight + gap;
+      const hasSpaceAbove = spaceAbove >= dropdownHeight + gap;
+
+      // Prefer bottom placement, flip to top if not enough space below but enough above
+      const placement: 'bottom' | 'top' = hasSpaceBelow || !hasSpaceAbove ? 'bottom' : 'top';
+
+      const top = placement === 'bottom'
+        ? rect.bottom + gap
+        : rect.top - dropdownHeight - gap;
+
+      setDropdownPosition({
+        top,
+        left: rect.left,
+        width: rect.width,
+        placement,
+      });
+    };
+
+    // Initial position calculation
+    updatePosition();
+
+    // Listen for scroll events on all scrollable ancestors
+    window.addEventListener('scroll', updatePosition, true);
+    window.addEventListener('resize', updatePosition);
+
+    return () => {
+      window.removeEventListener('scroll', updatePosition, true);
+      window.removeEventListener('resize', updatePosition);
+    };
+  }, [isOpen, useMobileSheet, usePortal]);
+
   // Lock body scroll when mobile sheet is open
   useEffect(() => {
     if (useMobileSheet && isOpen) {
@@ -617,9 +676,64 @@ const Select = forwardRef<SelectHandle, SelectProps>(
           </div>
         </button>
 
-        {/* Desktop Dropdown */}
-        {isOpen && !useMobileSheet && (
-          <div className="absolute z-50 w-full mt-2 bg-white bg-subtle-grain rounded-lg shadow-lg border border-paper-200 max-h-60 overflow-hidden animate-fade-in">
+      </div>
+
+      {/* Desktop Dropdown - rendered via portal to avoid overflow clipping */}
+      {isOpen && !useMobileSheet && (usePortal ? dropdownPosition : true) && (
+        usePortal ? createPortal(
+          <div
+            ref={dropdownRef}
+            className={`fixed z-[9999] bg-white bg-subtle-grain rounded-lg shadow-lg border border-paper-200 max-h-60 overflow-hidden animate-fade-in ${
+              dropdownPosition?.placement === 'top' ? 'origin-bottom' : 'origin-top'
+            }`}
+            style={{
+              top: dropdownPosition!.top,
+              left: dropdownPosition!.left,
+              width: dropdownPosition!.width,
+            }}
+          >
+            {/* Search Input */}
+            {searchable && (
+              <div className="p-2 border-b border-paper-200">
+                <div className="relative">
+                  <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-ink-400" />
+                  <input
+                    ref={searchInputRef}
+                    type="text"
+                    value={searchQuery}
+                    onChange={(e) => setSearchQuery(e.target.value)}
+                    placeholder="Search..."
+                    className="w-full pl-9 pr-3 py-2 text-sm border border-paper-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-accent-400 focus:border-accent-400"
+                    role="searchbox"
+                    aria-label="Search options"
+                    aria-autocomplete="list"
+                    aria-controls={listboxId}
+                  />
+                </div>
+              </div>
+            )}
+
+            {/* Options List */}
+            <div
+              ref={listRef}
+              id={listboxId}
+              className="overflow-y-auto"
+              style={{ maxHeight: useVirtualScrolling ? virtualHeight : '12rem' }}
+              onScroll={(e) => useVirtualScrolling && setScrollTop(e.currentTarget.scrollTop)}
+              role="listbox"
+              aria-label="Available options"
+              aria-multiselectable="false"
+            >
+              {renderOptionsContent(false)}
+            </div>
+          </div>,
+          document.body
+        ) : (
+          // Non-portal dropdown (inline, relative positioning)
+          <div
+            ref={dropdownRef}
+            className="absolute z-50 mt-1 w-full bg-white bg-subtle-grain rounded-lg shadow-lg border border-paper-200 max-h-60 overflow-hidden animate-fade-in"
+          >
             {/* Search Input */}
             {searchable && (
               <div className="p-2 border-b border-paper-200">
@@ -655,8 +769,8 @@ const Select = forwardRef<SelectHandle, SelectProps>(
               {renderOptionsContent(false)}
             </div>
           </div>
-        )}
-      </div>
+        )
+      )}
 
       {/* Mobile Bottom Sheet */}
       {isOpen && useMobileSheet && createPortal(

package/src/components/index.ts

@@ -315,6 +315,17 @@ export type {
 export { default as DataTableCardView } from './DataTableCardView';
 export type { CardViewConfig, DataTableCardViewProps } from './DataTableCardView';
 
+// DataGrid (Excel-like grid with formulas)
+export { default as DataGrid } from './DataGrid';
+export type {
+  DataGridProps,
+  DataGridHandle,
+  DataGridColumn,
+  DataGridCell,
+  CellValue,
+  FrozenRowMode,
+} from './DataGrid';
+
 export { default as SwipeActions } from './SwipeActions';
 export type { SwipeActionsProps, SwipeAction } from './SwipeActions';
 
@@ -322,6 +333,10 @@ export type { SwipeActionsProps, SwipeAction } from './SwipeActions';
 export { Spreadsheet, SpreadsheetReport } from './Spreadsheet';
 export type { SpreadsheetProps, SpreadsheetCell, Matrix, CellBase } from './Spreadsheet';
 
+// ExcelTable has been moved to a separate package: @papernote/excel-table
+// This is due to Handsontable's commercial licensing requirements
+// See: https://github.com/kwhittenberger/papernote-ui/tree/main/packages/excel-table
+
 export { default as ExpandedRowEditForm } from './ExpandedRowEditForm';
 export type {
   ExpandedRowEditFormProps,
@@ -448,6 +463,21 @@ export type { ColumnResize, ColumnOrder } from '../utils/tableEnhancements';
 export { exportToExcel, exportDataTableToExcel, createMultiSheetExcel } from '../utils/excelExport';
 export type { ExcelColumn, ExportToExcelOptions, DataTableExportOptions, MultiSheetExcelOptions } from '../utils/excelExport';
 
+// Formula Definitions (for DataGrid intellisense)
+export {
+  FORMULA_DEFINITIONS,
+  FORMULA_NAMES,
+  FORMULA_CATEGORIES,
+  getFormulasByCategory,
+  searchFormulas,
+  getFormula,
+} from '../utils/formulaDefinitions';
+export type {
+  FormulaDefinition,
+  FormulaParameter,
+  FormulaCategory,
+} from '../utils/formulaDefinitions';
+
 // Hooks
 export { useColumnResize, useColumnReorder } from '../hooks/useTableEnhancements';
 export type { UseColumnResizeOptions, UseColumnReorderOptions } from '../hooks/useTableEnhancements';